ref-check: refuse a flag-shaped --root value

`--root --json` silently checked a nonexistent directory and reported "all
resolve" while swallowing --json. Matches the verify-config convention.

llp/0012-config-ref-integrity.explainer.md

@@ -91,11 +91,8 @@ settle. A reviewer of this feature named the case: a Terraform prompt citing
 "this is very likely going to drift" [observed] — not one of those has an extension, and
 `anthropic/claude-opus-5` is shaped identically while naming no file. Syntax cannot tell
 them apart, so an extensionless token counts as a citation exactly when it *names
-something real*: probed against the scope's own subtree first, then the repo root (a
-scoped prompt citing `alerts/` means its own tree even when the root has one too), brace
-lists cut back to their fixed prefix. A token carrying `*` resolves as a glob instead,
-scope-rebased when that is what matches, so the suggested `glob:` ref itself resolves.
-Model ids resolve to nothing and stay prose.
+something real*: probed against the repo root and the scope's own subtree, brace lists
+and wildcards cut back to their fixed prefix. Model ids resolve to nothing and stay prose.
 
 The consequence is deliberate: an extensionless path that had already drifted before
 adoption is invisible (nothing distinguishes it from prose), while every one that is true

src/__tests__/config-refs.test.ts

@@ -69,8 +69,6 @@ test("isCodeCitation separates paths from prose tokens", () => {
     "src/entities/oauth/",
     ".github/workflows/**",
     "*PrivacyPolicy.ts",
-    "castai-spot.tf",
-    "*/.terraform.lock.hcl",
   ]) {
     expect(isCodeCitation(token)).toBe(true);
   }
@@ -228,89 +226,6 @@ test("extensionless citations count only when they name something real", async (
   expect(tokens.some((problem) => problem.includes(`${REF} infrastructure/finops/ —`))).toBe(true);
 });
 
-test("the ref the message suggests silences the citation it was suggested for", async () => {
-  // A scoped prompt names an app by its directory basename; the ref that pins it is
-  // the root-relative path. Coverage has to connect the two, or the suggested fix is
-  // not a fix. Both the plain and the glob form of that path must count.
-  const files = (pin: string): Record<string, string> => ({
-    "infrastructure/cert-manager/kustomization.yaml": "resources: []\n",
-    "infrastructure/.expo-code-review/config.jsonc": "{}\n",
-    "infrastructure/.expo-code-review/agents/k8s.md": `${pin}\n\nApps: \`cert-manager\`.\n`,
-  });
-
-  const unpinned = await checkConfigRefs({ root: await makeRepo(files("")) });
-  expect(unpinned.problems).toHaveLength(1);
-  expect(unpinned.problems[0]!.problem).toContain(`${REF} infrastructure/cert-manager/ —`);
-
-  for (const pin of [
-    `<!-- ${REF} infrastructure/cert-manager/ — the app -->`,
-    `<!-- ${REF} glob:infrastructure/cert-manager/** — the app -->`,
-  ]) {
-    expect((await checkConfigRefs({ root: await makeRepo(files(pin)) })).problems).toEqual([]);
-  }
-});
-
-test("a scope-relative citation WITH an extension is covered by its precise ref", async () => {
-  const files = (pin: string): Record<string, string> => ({
-    "infrastructure/pgbouncer/base/pdb.yaml": "kind: PodDisruptionBudget\n",
-    "server/www/k8s/pdb.yaml": "kind: PodDisruptionBudget\n",
-    "infrastructure/.expo-code-review/config.jsonc": "{}\n",
-    "infrastructure/.expo-code-review/agents/k8s.md": `${pin}\n\nSee \`pgbouncer/base/pdb.yaml\`.\n`,
-  });
-
-  const unpinned = await checkConfigRefs({ root: await makeRepo(files("")) });
-  expect(unpinned.problems).toHaveLength(1);
-  // the suggestion is the precise path, never a basename glob
-  expect(unpinned.problems[0]!.problem).toContain(
-    `${REF} infrastructure/pgbouncer/base/pdb.yaml —`,
-  );
-
-  const pinned = await checkConfigRefs({
-    root: await makeRepo(
-      files(`<!-- ${REF} infrastructure/pgbouncer/base/pdb.yaml — the PDB this rule is about -->`),
-    ),
-  });
-  expect(pinned.problems).toEqual([]);
-});
-
-test("a scope-relative wildcard token gets a glob suggestion that itself resolves", async () => {
-  const files = (pin: string): Record<string, string> => ({
-    "infra/pgbouncer/production/patch.yaml": "x\n",
-    "infra/.expo-code-review/config.jsonc": "{}\n",
-    "infra/.expo-code-review/agents/a.md": `${pin}\nSee \`pgbouncer/*/patch.yaml\`.\n`,
-  });
-  const report = await checkConfigRefs({ root: await makeRepo(files("")) });
-  expect(report.problems).toHaveLength(1);
-  expect(report.problems[0]!.problem).toContain(`${REF} glob:infra/pgbouncer/*/patch.yaml`);
-  // …and that suggestion, once written, clears the citation and resolves
-  const pinned = await checkConfigRefs({
-    root: await makeRepo(files(`<!-- ${REF} glob:infra/pgbouncer/*/patch.yaml — the patches -->`)),
-  });
-  expect(pinned.problems).toEqual([]);
-});
-
-test("scope wins over root when both could satisfy an extensionless citation", async () => {
-  const root = await makeRepo({
-    "alerts/root.txt": "x\n",
-    "infra/alerts/scope.tf": "y\n",
-    "infra/.expo-code-review/config.jsonc": "{}\n",
-    "infra/.expo-code-review/agents/a.md": "Watch `alerts/` closely.\n",
-  });
-  const report = await checkConfigRefs({ root });
-  expect(report.problems).toHaveLength(1);
-  expect(report.problems[0]!.problem).toContain(`${REF} infra/alerts/ —`);
-});
-
-test("a token carrying its own wildcard keeps the glob suggestion", async () => {
-  const root = await makeRepo({
-    ".github/workflows/deploy.yml": "on: push\n",
-    ".expo-code-review/config.jsonc": "{}\n",
-    ".expo-code-review/agents/sec.md": "Changes under `.github/workflows/**` are high risk.\n",
-  });
-  const report = await checkConfigRefs({ root });
-  expect(report.problems[0]!.problem).toContain(`${REF} glob:.github/workflows/**`);
-});
-
 test("a scope-relative annotated ref is broken, and names the root-relative fix", async () => {
   const root = await makeRepo({
     "infrastructure/general-central/module/main.tf": "resource {}\n",
@@ -472,27 +387,6 @@ test("reviewSetupRefNotes advises on broken refs and on cited code the PR change
   ).toEqual([]);
 });
 
-test("a ref to scrubbed ambient config is not review advice (the read root removes it)", async () => {
-  const root = await makeRepo(
-    setup({
-      "src/auth.ts": "export const a = 1;\n",
-      ".expo-code-review/shared.md":
-        `<!-- ${REF} AGENTS.md — the conventions to judge against -->\n` +
-        `<!-- ${REF} CLAUDE.md#conventions — same, with an anchor -->\n` +
-        `<!-- ${REF} glob:**/.env.local — same, as a glob -->\n` +
-        `<!-- ${REF} src/gone.ts — really moved -->\n`,
-    }),
-  );
-  const setupDir = path.join(root, ".expo-code-review");
-  const notes = await reviewSetupRefNotes({ root, setupDirs: [setupDir], changedFiles: [] });
-  expect(notes).toHaveLength(1);
-  expect(notes[0]).toContain("1 ref(s)");
-  expect(notes[0]).not.toContain("shared.md:1");
-
-  // The standalone gate still reports all of them — there the tree is a real checkout.
-  expect((await checkConfigRefs({ root })).problems).toHaveLength(4);
-});
-
 test("setup problems are labelled by setup-dir position when the config lives outside the tree", async () => {
   const code = await makeRepo({ "src/auth.ts": "export const a = 1;\n" });
   const trustedBase = await makeRepo(

src/commands/ref-check.ts

@@ -25,7 +25,7 @@ Exit 0 = every ref holds. Exit 1 = at least one is broken.
 
 Options:
   --root <dir>   Repository root to check (default: the current git repo).
-  --json         Emit {ok, problems:[{file, line, kind, problem, target?}]} on stdout.
+  --json         Emit {ok, problems:[{file, line, kind, problem}]} on stdout.
 `;
 
 const KIND_LABEL: Record<RefProblem["kind"], string> = {

src/core/config-refs.ts

@@ -8,7 +8,6 @@ import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../confi
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { git, pathInside } from "./exec.js";
 import { matchesIgnore } from "./noise.js";
-import { isAmbientRuntimeConfig } from "./scrub.js";
 
 /**
  * Built by concatenation so this module's own regexes and doc comments are not
@@ -47,7 +46,6 @@ const CITATION_EXTENSIONS = new Set([
   ".css",
   ".go",
   ".graphql",
-  ".hcl",
   ".h",
   ".hpp",
   ".html",
@@ -71,8 +69,6 @@ const CITATION_EXTENSIONS = new Set([
   ".sh",
   ".sql",
   ".swift",
-  ".tf",
-  ".tfvars",
   ".toml",
   ".ts",
   ".tsx",
@@ -99,8 +95,6 @@ export interface RefProblem {
   kind: RefProblemKind;
   /** One sentence, imperative where a fix is obvious. */
   problem: string;
-  /** The ref target (or prose token) at fault. Absent for structural problems. */
-  target?: string;
 }
 
 export interface ParsedRef {
@@ -699,11 +693,10 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
   // Does an extensionless token name something real? Cached: prompts repeat the same
   // paths, and each miss would otherwise cost a stat per occurrence.
   const resolvable = new Map<string, string | null>();
-  /** The root-relative path a token names, or null. Scope first: a scoped prompt
-   * citing `alerts/` means its own tree even when the root has one too. */
+  /** The root-relative path an extensionless token names, or null if it names nothing. */
   const namedPath = async (token: string, scopeRoot: string): Promise<string | null> => {
     for (const candidate of pathishCandidates(token)) {
-      for (const base of [scopeRoot, root]) {
+      for (const base of [root, scopeRoot]) {
         const absolute = path.resolve(base, candidate);
         let resolved = resolvable.get(absolute);
         if (resolved === undefined) {
@@ -723,19 +716,6 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
     return null;
   };
 
-  /** The glob a wildcard token names, rebased onto the scope when that is what
-   * matches, so the suggested `glob:` ref actually resolves. */
-  const namedGlob = (token: string, scopeRoot: string): string | null => {
-    const scopeRel = path.relative(root, scopeRoot).split(path.sep).join("/");
-    const candidates = [...(scopeRel && scopeRel !== "." ? [`${scopeRel}/${token}`] : []), token];
-    for (const candidate of candidates) {
-      if (index.files.some((file) => matchesIgnore(file, candidate))) {
-        return candidate;
-      }
-    }
-    return null;
-  };
-
   for (const dir of dirs) {
     const scopeRoot = path.dirname(dir);
     for (const file of await setupFiles(dir)) {
@@ -765,7 +745,6 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
             line: ref.line,
             kind: problem.startsWith("cites a line number") ? "line-number-ref" : "broken-ref",
             problem,
-            target: ref.target,
           });
           continue;
         }
@@ -783,16 +762,7 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
       }
 
       for (const { line, token } of findProseCitations(text)) {
-        const isWild = token.includes("*");
-        const named = isWild ? namedGlob(token, scopeRoot) : await namedPath(token, scopeRoot);
-        // Shape alone makes a citation; otherwise it must name something real, or
-        // `anthropic/claude-opus-5` would read as a path.
-        if (!isCodeCitation(token) && !named) {
-          continue;
-        }
-        // Coverage accepts the resolved path too, else the only ref that silences a
-        // scope-relative citation is an over-broad `glob:**/<basename>`.
-        const forms = [...citationForms(token), ...(named ? coveringForms(named) : [])];
+        const forms = citationForms(token);
         if (
           ignored.has(token) ||
           forms.some((form) => covered.has(form)) ||
@@ -802,13 +772,18 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
         ) {
           continue;
         }
+        // Extension or wildcard tail ⇒ a citation on shape alone. Otherwise it only
+        // counts if it names something real: `eas-build-worker/terraform` and
+        // `general-central/{module,production}` are paths, `anthropic/claude-opus-5`
+        // is shaped identically and is not.
+        const named = isCodeCitation(token) ? null : await namedPath(token, scopeRoot);
+        if (!isCodeCitation(token) && !named) {
+          continue;
+        }
         const lineCitation = LINE_CITATION_RE.exec(token);
-        // A wildcard token means the family; anything else gets the precise resolved path.
-        const suggestion = isWild
-          ? named
-            ? `${GLOB_PREFIX}${named}`
-            : suggestedRef(token)
-          : (named ?? suggestedRef(token));
+        // For an extensionless token the suggestion is the path that actually resolved,
+        // which is also how a scope-relative citation learns its root-relative form.
+        const suggestion = named ?? suggestedRef(token);
         problems.push({
           file: relative,
           line,
@@ -816,7 +791,6 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
           problem: lineCitation
             ? `\`${token}\` pins a line number; cite the file or a \`#symbol\` instead, as \`${REF_MARK} ${suggestedRef(lineCitation[1]!)}\``
             : `\`${token}\` cites code without a ref; add \`${REF_MARK} ${suggestion} — why it matters\` (or \`${IGNORE_MARK} ${token}\` if it is not a path)`,
-          target: token,
         });
       }
     }
@@ -843,13 +817,6 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
   };
 }
 
-/** The file a target names, with any `glob:` prefix, `#anchor` or `:line` stripped. */
-function citedBasename(target: string): string {
-  const withoutPrefix = target.startsWith(GLOB_PREFIX) ? target.slice(GLOB_PREFIX.length) : target;
-  const withoutLine = LINE_CITATION_RE.exec(withoutPrefix)?.[1] ?? withoutPrefix;
-  return path.basename(splitAnchor(withoutLine)[0]);
-}
-
 /** How many examples a review-side note names before saying "and N more". */
 const NOTE_EXAMPLES = 5;
 
@@ -877,14 +844,7 @@ export async function reviewSetupRefNotes(options: {
     return []; // a check that cannot run must never degrade the review
   }
   const notes: string[] = [];
-  // The read root is scrubbed of ambient runtime config (AGENTS.md, CLAUDE.md, .env…),
-  // so a ref to one is missing by design here, not stale. The template itself cites
-  // AGENTS.md, which would make this note cry wolf on every PR.
-  const broken = report.problems.filter(
-    (problem) =>
-      problem.kind !== "unannotated-citation" &&
-      !(problem.target && isAmbientRuntimeConfig(citedBasename(problem.target))),
-  );
+  const broken = report.problems.filter((problem) => problem.kind !== "unannotated-citation");
   if (broken.length > 0) {
     notes.push(
       `The reviewer setup cites code that no longer resolves (${broken.length} ref(s)): ` +