@@ -72,6 +72,21 @@ integration cases generated with an explicit `--out <dir>/docs` while `verify --
 the config default, and passed only because the two coincided. Sixteen cases failed the moment
 they stopped. They now take the config path, which is what the gate reads.
 
+### Fixed — the hash-manifest advisory prescribed editing a file that may not hold the rule
+
+It hardcoded `.metaobjects/.gitignore` and the literal pattern `.gen-state/`. That is only one
+of the places the exclusion can sit: it can be in ANY `.gitignore` up the tree, in
+`.git/info/exclude`, or in a per-user excludes file. Found by running an adopter estate against
+the RC — its rule was in the **ROOT** `.gitignore` as `.metaobjects/.gen-state/`, so following
+the advisory to the letter edited a file that did not hold the rule, changed nothing, and
+printed the same line again. The loop shape, in a second command.
+
+`git check-ignore -v` returns the exact `<file>:<line>:<pattern>` that matched, and the check
+already shells out to `check-ignore` for the verdict. The advisory now names the real rule and
+builds the `/*` + `!` negation from the pattern it found. When git cannot say, the wording
+degrades to "find it with `git check-ignore -v …`" rather than asserting a location — the same
+discipline the rest of this check follows, where "cannot say" is never reported as a fact.
+
 ### Changed — `--limit` is documented as per printed LIST, which is what it always was
 
 Its doc said "per SECTION, never shared across them". The anti-pattern tier prints TWO
 
@@ -113,3 +113,47 @@ export function isGitIgnored(
   if ("unavailable" in res) return undefined;
   return res.ignored.has(toPosix(rel));
 }
+
+/**
+ * WHICH rule ignores `rel` — the `.gitignore` file, its line, and the pattern.
+ *
+ * Advisories that tell an adopter to fix an ignore rule have to name the rule that is
+ * actually in force, not a conventional location. The exclusion can live in ANY
+ * `.gitignore` up the tree, in `.git/info/exclude`, or in a per-user excludes file, and an
+ * advisory that assumes one of them sends the reader to edit a file that does not hold the
+ * rule — after which the same advisory prints again, unchanged. `git check-ignore -v`
+ * answers it exactly, so nothing has to be assumed.
+ *
+ * `undefined` when git cannot say or nothing matches. The verdict itself still comes from
+ * `isGitIgnored`; this is only for the message, so a failure here degrades the wording
+ * rather than the check.
+ */
+export function gitIgnoreSource(
+  dir: string,
+  rel: string,
+  opts: GitIgnoreOptions,
+): { file: string; line: string; pattern: string } | undefined {
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  const args: string[] = [];
+  if (!opts.honourGlobalExcludes) {
+    args.push("-c", `core.excludesFile=${NO_SUCH_EXCLUDES_FILE}`);
+  }
+  args.push("-C", dir, "check-ignore", "-v", "--", toPosix(rel));
+
+  let res;
+  try {
+    res = spawnSync(gitBin, args, { encoding: "utf-8" });
+  } catch {
+    return undefined;
+  }
+  if (res.error !== undefined || res.status !== 0) return undefined;
+  // `<source>:<line>:<pattern>\t<path>` — the source may itself contain a colon on
+  // Windows, so split from the RIGHT of the first tab-delimited field.
+  const first = (res.stdout ?? "").split("\n")[0];
+  if (first === undefined || first === "") return undefined;
+  const lhs = first.split("\t")[0];
+  if (lhs === undefined) return undefined;
+  const m = /^(.*):(\d+):(.*)$/.exec(lhs);
+  if (m === null) return undefined;
+  return { file: m[1]!, line: m[2]!, pattern: m[3]! };
+}
@@ -18,7 +18,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
-import { isGitIgnored } from "./git-ignore.js";
+import { gitIgnoreSource, isGitIgnored } from "./git-ignore.js";
 
 /** Project-relative path of the manifest — the one artifact of `.gen-state/` that is
  *  meant to be committed. */
@@ -40,13 +40,28 @@ export function warnIfManifestIgnored(cwd: string): void {
   // per-user ignore file answers it just as truly as a committed .gitignore does.
   if (isGitIgnored(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true }) !== true) return;
 
+  // WHERE the rule actually lives, asked of git rather than assumed. This used to name
+  // `.metaobjects/.gitignore` and the literal pattern `.gen-state/`, which is only one of
+  // the places the exclusion can sit: an adopter estate had it in the ROOT `.gitignore` as
+  // `.metaobjects/.gen-state/`, so following this advisory to the letter edited a file that
+  // did not hold the rule, changed nothing, and printed this same line again — the loop
+  // shape. `git check-ignore -v` knows the answer, so nothing is guessed. When git cannot
+  // say, the wording degrades to the generic form rather than asserting a location.
+  const src = gitIgnoreSource(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true });
+  const where =
+    src !== undefined
+      ? `The rule is '${src.pattern}' at ${src.file}:${src.line} — replace it there with ` +
+        `a '/*' form plus a '!' negation for the manifest ` +
+        `(e.g. '${src.pattern.replace(/\/$/, "")}/*' and '!${src.pattern.replace(/\/$/, "")}/.hashes.json')`
+      : `Find the rule with 'git check-ignore -v ${HASH_MANIFEST_REL}' and replace it with ` +
+        `a '/*' form plus a '!' negation for the manifest`;
+
   log.warn(
     `${HASH_MANIFEST_REL} is git-ignored, so it never reaches another machine — ` +
       `on a fresh clone or CI runner 'meta gen' cannot tell your hand edits from its ` +
-      `own stale output, and will refuse to overwrite rather than guess. Fix it in ` +
-      `.metaobjects/.gitignore by replacing '.gen-state/' with '.gen-state/*' plus ` +
-      `'!.gen-state/.hashes.json' (the glob matters — git will not descend into an ` +
-      `excluded directory, so a negation under '.gen-state/' can never apply), then ` +
-      `commit the manifest. If you deliberately do not commit generated output, ignore this.`,
+      `own stale output, and will refuse to overwrite rather than guess. ${where} ` +
+      `(the glob matters — git will not descend into an excluded directory, so a negation ` +
+      `INSIDE an excluded directory can never apply), then commit the manifest. ` +
+      `If you deliberately do not commit generated output, ignore this.`,
   );
 }
@@ -98,3 +98,39 @@ describe("warnIfManifestIgnored", () => {
     expect(captureWarnings(() => warnIfManifestIgnored(root))).toEqual([]);
   });
 });
+
+describe("the advisory names the rule that is actually in force", () => {
+  // Found on an adopter estate: the exclusion was in the ROOT `.gitignore` as
+  // `.metaobjects/.gen-state/`, not in `.metaobjects/.gitignore` as the message assumed.
+  // Editing the named file changed nothing and the same advisory printed again — the loop
+  // shape. The remedy has to be derived from git, not from a convention.
+  test("a rule in the ROOT .gitignore is named, not the .metaobjects one", () => {
+    gitInit();
+    writeManifest();
+    writeFileSync(join(root, ".gitignore"), ".metaobjects/.gen-state/\n");
+    const warns = captureWarnings(() => warnIfManifestIgnored(root));
+    expect(warns).toHaveLength(1);
+    // It must point at the file that HOLDS the rule...
+    expect(warns[0]).toContain(".gitignore:1");
+    expect(warns[0]).toContain(".metaobjects/.gen-state/");
+    // ...and must NOT prescribe editing a file that does not hold it.
+    expect(warns[0]).not.toContain("Fix it in .metaobjects/.gitignore");
+  });
+
+  test("a rule in .metaobjects/.gitignore is named too, with its own pattern", () => {
+    gitInit();
+    writeManifest();
+    writeIgnore(".gen-state/\n");
+    const warns = captureWarnings(() => warnIfManifestIgnored(root));
+    expect(warns).toHaveLength(1);
+    expect(warns[0]).toContain(".metaobjects/.gitignore:1");
+    expect(warns[0]).toContain("!.gen-state/.hashes.json");
+  });
+
+  test("when git cannot say, it degrades to the generic form and asserts no location", () => {
+    // No repository at all: the verdict path returns undefined, so this warning never
+    // fires — proving the advisory cannot invent a location it does not have.
+    writeManifest();
+    expect(captureWarnings(() => warnIfManifestIgnored(root))).toEqual([]);
+  });
+});