@expo/code-review-cli 0.8.0 → 0.9.1

package/README.md

@@ -116,6 +116,7 @@ is a ready example to adapt.
 | `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
 | `ecr doctor [--list-scopes]` | Check environment, config, credentials, and (with a manifest) scopes. |
 | `ecr feedback [--repo <owner/repo>]` | Report which findings PR authors pushed back on, across history. See below. |
+| `ecr ref-check [--json]` | Fail when the review setup cites code that moved or vanished. See below. |
 
 Extra flags for monorepos: `review`/`ci` `--config-dir <dir>` (load config from an
 alternate dir; also `ECR_CONFIG_DIR`), `ci --scopes a,b` (limit the fan-out to
@@ -127,6 +128,48 @@ untrusted external context; see below).
 
 ---
 
+## Keeping prompts true (`ecr ref-check`)
+
+Good reviewer prompts cite real code: "the only session entry point is
+`server/src/session.ts`", "every webhook router must call `sanitizeSecrets`". Then the
+code moves and the prompt keeps citing a path that no longer exists — the reviewer
+reasons from a fiction, on every PR, with nothing to warn you.
+
+`ecr ref-check` makes those citations checkable. Pin each one with a ref, in a comment
+of its own (`<!-- … -->` in Markdown, `//` in JSONC):
+
+```md
+<!-- @ref server/src/session.ts#createSession — the only place a session is minted -->
+<!-- @ref server/src/entities/oauth/ — every provider lives here -->
+<!-- @ref glob:**/*WebhookRouter.ts — the routers this rule is about -->
+```
+
+A target is a file, a `dir/`, `glob:<pattern>`, `file#symbol`, or `doc.md#heading` —
+never a line number, since a line number rots without any signal. Symbol anchors are
+checked by whole-word match, so code moving inside its file is fine and a rename is not.
+
+The check is strict on purpose: a backticked token in `.expo-code-review/` that looks
+like a repo path **must** be a ref, because the stale citations are exactly the ones
+nobody thought to annotate. A token with no extension (`eas-build-worker/terraform`,
+`general-central/{module,production}`, `finops`) counts when it names something that
+exists — so those get pinned too, while `anthropic/claude-opus-5`, shaped the same way,
+stays prose. For a token that only looks like a path, say so once:
+`<!-- @ref-ignore knex.raw() -->`. It also checks what your config already declares —
+`enforceAgents` ids, scope `config` directories, scope path globs.
+
+Refs are repo-root-relative, including in a scope's own setup dir. A scope prompt that
+cites `general-central/module` for `infrastructure/general-central/module` gets told the
+root-relative form to use.
+
+Two run points:
+
+- `ecr ref-check` exits 1 on any problem. Run it in CI or a pre-commit hook.
+- `ecr review` / `ecr ci` run it too, and never fail a PR's checks with it. The comment
+  carries a **Review setup** note instead: refs that no longer resolve, plus cited code
+  *this PR* changes, where the ref still resolves but the guidance may not.
+
+---
+
 ## Monorepos (routing manifest)
 
 A monorepo can route different subtrees to different reviewer rosters from a single

package/build/cli.js

@@ -5,6 +5,7 @@ import { dismissCommand } from "./commands/dismiss.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { feedbackCommand } from "./commands/feedback.js";
 import { initCommand } from "./commands/init.js";
+import { refCheckCommand } from "./commands/ref-check.js";
 import { reviewCommand } from "./commands/review.js";
 import { setupAuthCommand } from "./commands/setup-auth.js";
 import { verifyConfigCommand } from "./commands/verify-config.js";
@@ -20,6 +21,7 @@ Usage:
   ecr setup-auth [--yes]   Walk through getting model credentials for local runs.
   ecr doctor [--list-scopes]   Check environment, config, credentials, and scopes.
   ecr verify-config [--expected <env>] [--json]   Refuse to run if a config could redirect the credential (CI guard).
+  ecr ref-check [--root <dir>] [--json]   Fail if the review setup cites code that moved or vanished.
 
 Agents live in each repo under .expo-code-review/. This CLI is the engine.
 
@@ -65,6 +67,9 @@ async function main() {
         case "verify-config":
             await verifyConfigCommand(rest);
             break;
+        case "ref-check":
+            await refCheckCommand(rest);
+            break;
         default:
             process.stderr.write(`Unknown command: ${sub}\n\n${USAGE}`);
             process.exitCode = 2;

package/build/commands/ref-check.js

@@ -0,0 +1,84 @@
+// @ref LLP 0012#run-points-command-and-review — the gating run point: exit 1 on any broken ref
+import path from "node:path";
+import { checkConfigRefs } from "../core/config-refs.js";
+import { repoRoot } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+const USAGE = `ecr ref-check — fail when the review setup cites code that moved or vanished
+
+Usage:
+  ecr ref-check [--root <dir>] [--json]
+
+Sweeps every .expo-code-review/ directory in the repo (root and scopes) and checks
+that each code citation still resolves against this checkout:
+  • \`@ref <target>\` annotations in prompts and configs. A target is a file, a
+    directory (trailing slash), \`glob:<pattern>\`, a \`file#symbol\`, or a
+    \`doc.md#heading\`. Never a line number — lines rot silently.
+  • Unannotated citations: a backticked token that looks like a repo path must be a
+    ref, so nothing cites code without being checked. Use \`@ref-ignore <token>\`
+    for a token that is not a path.
+  • Structural refs the config already declares: enforceAgents ids, scope config
+    directories, and scope path globs.
+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}]} on stdout.
+`;
+const KIND_LABEL = {
+    "broken-ref": "broken ref",
+    "line-number-ref": "line-number ref",
+    "unannotated-citation": "unannotated citation",
+    structural: "structural ref",
+};
+export async function refCheckCommand(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    let root;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--root") {
+            root = argv[++i];
+            // A flag-shaped value means the directory was forgotten: taking it would check
+            // some nonexistent path and report "all resolve" while swallowing the real flag.
+            if (!root || root.startsWith("-")) {
+                process.stderr.write("ecr ref-check: --root needs a directory\n");
+                process.exitCode = 2;
+                return;
+            }
+        }
+        else {
+            process.stderr.write(`ecr ref-check: unknown argument ${arg}\n${USAGE}`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    try {
+        const resolvedRoot = root ? path.resolve(root) : ((await repoRoot()) ?? process.cwd());
+        const report = await checkConfigRefs({ root: resolvedRoot });
+        if (json) {
+            process.stdout.write(`${JSON.stringify({ ok: report.ok, problems: report.problems })}\n`);
+        }
+        else if (report.ok) {
+            process.stdout.write(`ref-check: ${report.refs.length} ref(s) across ${report.scannedFiles.length} setup file(s) — all resolve\n`);
+        }
+        else {
+            for (const problem of report.problems) {
+                process.stderr.write(`${problem.file}:${problem.line}: ${KIND_LABEL[problem.kind]}: ${problem.problem}\n`);
+            }
+            process.stderr.write(`\nref-check: ${report.problems.length} problem(s). Update the ref or the prompt that cites it.\n`);
+        }
+        if (!report.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`ecr ref-check: ${errorMessage(error)}\n`);
+        process.exitCode = 2;
+    }
+}

package/build/core/config-refs.js

@@ -0,0 +1,776 @@
+// @ref LLP 0012#the-ref-grammar — one grammar for every code citation in a review setup
+// @ref LLP 0012#no-line-numbers-symbol-anchors-instead — targets are files, dirs, globs, symbols; never line numbers
+// @ref LLP 0012#unannotated-citations-are-broken-refs — a path-like backtick token that is not a ref fails the check
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../config/load.js";
+import { ROUTING_FILENAME } from "../config/routing.js";
+import { git, pathInside } from "./exec.js";
+import { matchesIgnore } from "./noise.js";
+/**
+ * Built by concatenation so this module's own regexes and doc comments are not
+ * themselves collected as refs by a scanner (the repo's `ref-check` does the same).
+ */
+const REF_MARK = "@" + "ref";
+const IGNORE_MARK = REF_MARK + "-ignore";
+/** `@ref <target> [relation] — gloss` inside a `//`-style comment. */
+const LINE_REF_RE = new RegExp(String.raw `${REF_MARK}\s+(.+)`);
+/** `<!-- @ref <target> — gloss -->`, possibly spanning lines. */
+const MD_REF_RE = new RegExp(String.raw `<!--\s*${REF_MARK}\s+([\s\S]+?)-->`, "g");
+const IGNORE_RE = new RegExp(String.raw `${IGNORE_MARK}\s+(.+)`);
+/** LLP-corpus targets (`LLP 0004#anchor`) belong to the engine repo, not an adopting one. */
+const LLP_TARGET_RE = /^LLP\s+\d{1,4}(?:#\S+)?$/;
+const URL_RE = /^https?:\/\/\S+$/;
+/** `<path>`, `<agent-id>`: documenting the grammar, not citing a file. */
+const PLACEHOLDER_RE = /^[<`]/;
+const GLOB_PREFIX = "glob:";
+/** A citation that pins a line (`src/a.ts:42`, `src/a.ts:42-51`) — always refused. */
+const LINE_CITATION_RE = /^(.+?):(\d+)(?:-\d+)?$/;
+/**
+ * Extensions that make a backticked token a *code citation* rather than prose.
+ * Deliberately an allowlist: `openai/gpt-5.5` and `label:<agent>` must not read as
+ * paths, while `session.ts` and `.github/workflows/**` must.
+ */
+const CITATION_EXTENSIONS = new Set([
+    ".c",
+    ".cc",
+    ".cjs",
+    ".cpp",
+    ".cs",
+    ".css",
+    ".go",
+    ".graphql",
+    ".h",
+    ".hpp",
+    ".html",
+    ".java",
+    ".js",
+    ".json",
+    ".jsonc",
+    ".jsx",
+    ".kt",
+    ".lock",
+    ".md",
+    ".mjs",
+    ".mts",
+    ".php",
+    ".prisma",
+    ".proto",
+    ".py",
+    ".rb",
+    ".rs",
+    ".scss",
+    ".sh",
+    ".sql",
+    ".swift",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".vue",
+    ".yaml",
+    ".yml",
+    ".zsh",
+]);
+/** Files inside a review-setup dir that are prompts or config (everything else is skipped). */
+const SCANNED_EXTENSIONS = new Set([".md", ".markdown", ".json", ".jsonc", ".txt"]);
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** GitHub-style heading slug: lowercase, spaces to hyphens, drop other punctuation. */
+export function slugifyHeading(text) {
+    return [...text.replace(/`/g, "").trim().toLowerCase()]
+        .map((ch) => (/[a-z0-9\-_]/.test(ch) ? ch : /\s/.test(ch) ? "-" : ""))
+        .join("");
+}
+/** Heading texts outside fenced code blocks. */
+function markdownHeadings(text) {
+    const headings = [];
+    let fenced = false;
+    for (const line of text.split(/\r?\n/)) {
+        if (line.trimStart().startsWith("```")) {
+            fenced = !fenced;
+            continue;
+        }
+        const match = fenced ? null : /^#{1,6}\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            headings.push(match[1]);
+        }
+    }
+    return headings;
+}
+/** Strip the trailing `— gloss` and `[relation]` so only the target remains. */
+function refTarget(body) {
+    const withoutGloss = body.split(/\s+(?:[—–]|--)(?:\s+|$)/)[0].trim();
+    const withoutRelation = withoutGloss.replace(/\s*\[[a-z-]+\]\s*$/, "").trim();
+    // `LLP 0009#anchor` is ONE target that contains a space; taking the first
+    // whitespace-separated token would leave a bare `LLP` and read as a broken path.
+    const llp = /^LLP\s+\d{1,4}(?:#\S+)?/.exec(withoutRelation);
+    return llp ? llp[0] : (withoutRelation.split(/\s+/)[0] ?? "");
+}
+/** Line numbers (1-based) that sit inside a fenced code block. */
+function fencedLines(text) {
+    const fenced = new Set();
+    let open = false;
+    text.split(/\r?\n/).forEach((line, index) => {
+        if (line.trimStart().startsWith("```")) {
+            fenced.add(index + 1); // the fence line itself is never a ref site
+            open = !open;
+            return;
+        }
+        if (open) {
+            fenced.add(index + 1);
+        }
+    });
+    return fenced;
+}
+/**
+ * Every `@ref` annotation in a setup file, markdown comments included. Fenced code
+ * blocks are skipped: an annotation shown inside one is documenting the grammar, and
+ * resolving it would make every doc that explains refs fail the check.
+ */
+export function parseRefAnnotations(text, file) {
+    const refs = [];
+    if (file.endsWith(".md") || file.endsWith(".markdown")) {
+        const fenced = fencedLines(text);
+        for (const match of text.matchAll(MD_REF_RE)) {
+            const line = text.slice(0, match.index).split("\n").length;
+            if (fenced.has(line)) {
+                continue;
+            }
+            refs.push({ file, line, target: refTarget(match[1]) });
+        }
+        return refs;
+    }
+    text.split(/\r?\n/).forEach((lineText, index) => {
+        const match = LINE_REF_RE.exec(lineText);
+        if (match) {
+            refs.push({ file, line: index + 1, target: refTarget(match[1]) });
+        }
+    });
+    return refs;
+}
+/** Tokens an author declared as prose, not citations (`@ref-ignore knex.raw()`). */
+export function parseRefIgnores(text) {
+    const ignored = new Set();
+    for (const lineText of text.split(/\r?\n/)) {
+        const match = IGNORE_RE.exec(lineText);
+        if (!match) {
+            continue;
+        }
+        for (const token of match[1].replace(/-->\s*$/, "").split(/[\s,]+/)) {
+            const cleaned = token.replace(/^`|`$/g, "").trim();
+            if (cleaned) {
+                ignored.add(cleaned);
+            }
+        }
+    }
+    return ignored;
+}
+/**
+ * Does this backticked token cite code? True for `a/b/c.ts`, `session.ts`,
+ * `src/entities/oauth/` and `.github/workflows/**`; false for `ecr ci`,
+ * `label:<agent>`, `knex.raw()`, `openai/gpt-5.5` and bare `**`.
+ */
+export function isCodeCitation(token) {
+    if (!token || /[\s<>(){}"'|=,;]/.test(token) || token.length > 200) {
+        return false;
+    }
+    const withoutLine = LINE_CITATION_RE.exec(token)?.[1] ?? token;
+    if (withoutLine.includes(":")) {
+        return false;
+    }
+    if (withoutLine.endsWith("/")) {
+        return withoutLine.replace(/[/*]/g, "").length > 0;
+    }
+    const base = withoutLine.split("/").pop() ?? "";
+    // A wildcard tail inside a path (`.github/workflows/**`) is a citation with no extension.
+    if (base.includes("*") && withoutLine.includes("/")) {
+        return withoutLine.replace(/[/*]/g, "").length > 0;
+    }
+    // A bare extension (`.ts`, `.js`) is prose about a suffix, not a file.
+    if (CITATION_EXTENSIONS.has(base.toLowerCase())) {
+        return false;
+    }
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 && !base.startsWith(".")) {
+        return false;
+    }
+    const extension = base.slice(base.lastIndexOf("."));
+    return CITATION_EXTENSIONS.has(extension.toLowerCase()) && base.replace(/[*.]/g, "").length > 0;
+}
+/**
+ * The ref an unannotated citation should have become. Abbreviated paths (`.../a/B.kt`),
+ * wildcards (`*Policy.ts`) and bare filenames (`session.ts`) become suffix globs, so a
+ * prompt keeps its short readable form and still gets checked.
+ */
+export function suggestedRef(token) {
+    const trimmed = token.replace(/^\.\.\.\/?/, "").replace(/^\/+/, "");
+    if (token.startsWith("...") || !trimmed.includes("/")) {
+        return `${GLOB_PREFIX}**/${trimmed}`;
+    }
+    return trimmed.includes("*") ? `${GLOB_PREFIX}${trimmed}` : trimmed;
+}
+/**
+ * Every form under which an annotated target can cover a prose citation, so one ref
+ * silences the token it is about: `glob:src/commands/*.ts` covers `src/commands/*.ts`,
+ * and `src/core/util.ts#errorMessage` covers `src/core/util.ts`.
+ */
+function coveringForms(target) {
+    const bare = target.startsWith(GLOB_PREFIX) ? target.slice(GLOB_PREFIX.length) : target;
+    const withoutAnchor = splitAnchor(bare)[0];
+    return [target, bare, withoutAnchor].flatMap((form) => [
+        form,
+        form.replace(/\/$/, ""),
+        `${form}/`,
+    ]);
+}
+/** The forms a prose citation could have been annotated as. */
+function citationForms(token) {
+    const suggested = suggestedRef(token);
+    return [
+        token,
+        token.replace(/\/$/, ""),
+        suggested,
+        suggested.startsWith(GLOB_PREFIX) ? suggested.slice(GLOB_PREFIX.length) : suggested,
+    ];
+}
+/**
+ * Paths to test when a token has no extension to give it away — `eas-build-worker/terraform`,
+ * `general-central/{module,production}`, a bare `finops`. These are only citations if they
+ * actually resolve, since `anthropic/claude-opus-5` is shaped exactly the same and is not
+ * a path. Returns the candidate paths to probe, or [] when the token cannot be one.
+ */
+export function pathishCandidates(token) {
+    if (!token || token.length > 200) {
+        return [];
+    }
+    // Cut a brace list or wildcard tail off FIRST: the part before it is the path to
+    // probe, and only that part has to look like one (`a/{b,c}` carries a comma).
+    const cut = Math.min(...[token.indexOf("{"), token.indexOf("*")].filter((index) => index >= 0), token.length);
+    const prefix = token.slice(0, cut).replace(/\/$/, "");
+    if (!prefix ||
+        !/[a-zA-Z]/.test(prefix) ||
+        /[\s<>()"'|=,;:]/.test(prefix) ||
+        prefix.startsWith("-")) {
+        return [];
+    }
+    return prefix === token ? [token] : [prefix];
+}
+/** Backticked code citations, outside fenced code blocks, with their line numbers. */
+export function findProseCitations(text) {
+    const found = [];
+    let fenced = false;
+    text.split(/\r?\n/).forEach((lineText, index) => {
+        if (lineText.trimStart().startsWith("```")) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced) {
+            return;
+        }
+        for (const match of lineText.matchAll(/`([^`]+)`/g)) {
+            found.push({ line: index + 1, token: match[1] });
+        }
+    });
+    return found;
+}
+async function pathKind(absolute) {
+    try {
+        const stats = await stat(absolute);
+        return stats.isDirectory() ? "dir" : "file";
+    }
+    catch {
+        return "missing";
+    }
+}
+/**
+ * Resolve one ref target against the repo. Returns the problem text, or null when
+ * the ref holds. Refs are ALWAYS repo-root-relative — a scope's prompts cite the
+ * same paths the reviewer sees in the diff, so there is no per-directory base.
+ */
+async function resolveTarget(target, index, 
+/** A scope's own subtree, used only to say "did you mean" on a scope-relative path. */
+scopeRoot) {
+    if (!target) {
+        return `empty ${REF_MARK} target`;
+    }
+    if (URL_RE.test(target) || LLP_TARGET_RE.test(target) || PLACEHOLDER_RE.test(target)) {
+        // URLs are shape-only (never fetched); LLP numbers belong to the engine's own
+        // corpus (`./ref-check`); `<placeholder>` targets are documentation of the syntax.
+        return null;
+    }
+    if (target.startsWith(GLOB_PREFIX)) {
+        const pattern = target.slice(GLOB_PREFIX.length);
+        if (!pattern) {
+            return `empty glob in ${REF_MARK} target`;
+        }
+        if (index.files.length === 0) {
+            return null; // no file list to match against (not a git checkout) — uncheckable
+        }
+        return index.files.some((file) => matchesIgnore(file, pattern))
+            ? null
+            : `glob matches no file in the repo: ${pattern}`;
+    }
+    const lineCitation = LINE_CITATION_RE.exec(target);
+    if (lineCitation) {
+        return `cites a line number (${target}); refs pin a file, dir, glob, or \`#symbol\` — line numbers rot silently`;
+    }
+    const [rawPath, anchor] = splitAnchor(target);
+    if (path.isAbsolute(rawPath) || rawPath.startsWith("~")) {
+        return `absolute path (${rawPath}); refs are repo-root-relative`;
+    }
+    const absolute = path.resolve(index.root, rawPath);
+    if (!pathInside(absolute, index.root)) {
+        return `escapes the repository (${rawPath})`;
+    }
+    const kind = await pathKind(absolute);
+    if (kind === "missing") {
+        // A scope's prompts naturally say `general-central/module` for what is really
+        // `infrastructure/general-central/module`. That is still a broken ref (one base, no
+        // ambiguity), but the fix is named instead of left as a puzzle.
+        const scoped = scopeRoot ? path.resolve(scopeRoot, rawPath) : null;
+        if (scoped && pathInside(scoped, index.root) && (await pathKind(scoped)) !== "missing") {
+            const suggestion = path.relative(index.root, scoped).split(path.sep).join("/");
+            return `no such path in the repo: ${rawPath} — refs are repo-root-relative; did you mean ${suggestion}?`;
+        }
+        return `no such path in the repo: ${rawPath}`;
+    }
+    if (rawPath.endsWith("/") && kind !== "dir") {
+        return `${rawPath} is a file, not a directory (drop the trailing slash)`;
+    }
+    if (!anchor) {
+        return null;
+    }
+    if (kind === "dir") {
+        return `${rawPath} is a directory, so \`#${anchor}\` cannot resolve`;
+    }
+    let content;
+    try {
+        content = await readFile(absolute, "utf8");
+    }
+    catch {
+        return null; // unreadable (binary, permissions) — uncheckable, never a failure
+    }
+    if (rawPath.endsWith(".md") || rawPath.endsWith(".markdown")) {
+        const slugs = new Set(markdownHeadings(content).map(slugifyHeading));
+        return slugs.has(slugifyHeading(anchor)) ? null : `${rawPath} has no heading #${anchor}`;
+    }
+    return new RegExp(String.raw `\b${escapeRegExp(anchor)}\b`).test(content)
+        ? null
+        : `${rawPath} no longer contains \`${anchor}\``;
+}
+/**
+ * How a setup file is named in a problem. Normally repo-relative, but in CI the setup
+ * is materialized from the trusted base ref OUTSIDE the code tree, where a relative
+ * path would read as `../../tmp/…`; there, name it by its position in the setup dir.
+ */
+function fileLabel(root, setupDir, file) {
+    const relative = path.relative(root, file);
+    if (!relative.startsWith("..")) {
+        return relative;
+    }
+    return path.join(CONFIG_DIRNAME, path.relative(setupDir, file));
+}
+function splitAnchor(target) {
+    const hash = target.indexOf("#");
+    return hash === -1 ? [target, undefined] : [target.slice(0, hash), target.slice(hash + 1)];
+}
+/**
+ * The repo's files, repo-relative with `/` separators — what `glob:` targets and scope
+ * globs match against. `git ls-files` when possible (fast, and "tracked" is the right
+ * notion for reviewable code), else a filesystem walk so the check still works in a
+ * plain directory. Empty only for an unreadable root.
+ */
+async function listRepoFiles(root) {
+    try {
+        // Tracked AND untracked-but-not-ignored: a plain path ref resolves with `stat` and
+        // therefore sees a file the moment it exists, so a glob must too — otherwise a
+        // freshly scaffolded (uncommitted) tree reports globs as matching nothing.
+        const tracked = (await git(["ls-files", "--cached", "--others", "--exclude-standard"], root))
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (tracked.length > 0) {
+            return tracked;
+        }
+    }
+    catch {
+        // not a git checkout — fall through to the walk
+    }
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === "node_modules" || (entry.name.startsWith(".") && entry.isDirectory())) {
+                continue;
+            }
+            const child = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(child);
+            }
+            else if (entry.isFile()) {
+                found.push(path.relative(root, child).split(path.sep).join("/"));
+            }
+        }
+    }
+    await walk(root);
+    return found.sort();
+}
+// @ref LLP 0012#what-gets-scanned [implements] — on-disk sweep of every setup dir, .runs/ excluded
+/**
+ * Every review-setup directory in the repo, found by walking the tree (not the
+ * routing manifest): a scope dir the manifest forgot still ships prompts to nobody,
+ * and its stale refs are exactly what this check exists to surface.
+ */
+export async function discoverSetupDirs(root) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const child = path.join(dir, entry.name);
+            if (entry.name === CONFIG_DIRNAME) {
+                found.push(child);
+                continue; // a setup dir never nests another
+            }
+            // Other dot dirs are skipped wholesale: `.claude/worktrees/` holds checkouts of
+            // this same repo, whose setup dirs would otherwise be swept as if they were scopes.
+            if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+                continue;
+            }
+            await walk(child);
+        }
+    }
+    await walk(root);
+    return found.sort();
+}
+/** Prompt and config files inside a setup dir. Skips `.runs/` and other dot entries. */
+async function setupFiles(dir) {
+    const found = [];
+    async function walk(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".")) {
+                continue;
+            }
+            const child = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(child);
+            }
+            else if (SCANNED_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+                found.push(child);
+            }
+        }
+    }
+    await walk(dir);
+    return found.sort();
+}
+function parseJsonc(text) {
+    try {
+        const value = JSON.parse(stripTrailingCommas(stripJsonComments(text)));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+// @ref LLP 0012#structural-refs-need-no-annotation [implements] — ids and scope dirs are refs the config already declares
+/**
+ * Refs the config declares structurally, so they are checked without an annotation:
+ * every `enforceAgents` id must have a root `agents/<id>.md`, every scope must point
+ * at a real setup dir, and every scope glob must match at least one tracked file (a
+ * glob matching nothing means those prompts review nothing).
+ */
+async function checkRoutingManifest(file, index, rootAgentIds) {
+    const problems = [];
+    const relative = fileLabel(index.root, path.dirname(file), file);
+    let parsed;
+    try {
+        parsed = parseJsonc(await readFile(file, "utf8"));
+    }
+    catch {
+        return problems;
+    }
+    if (!parsed) {
+        return [
+            { file: relative, line: 1, kind: "structural", problem: "could not be parsed as JSONC" },
+        ];
+    }
+    const defaults = (parsed.defaults ?? {});
+    const enforced = new Set(stringArray(defaults.enforceAgents));
+    const scopes = Array.isArray(parsed.scopes) ? parsed.scopes : [];
+    for (const scope of scopes) {
+        if (!scope || typeof scope !== "object") {
+            continue;
+        }
+        const entry = scope;
+        const name = typeof entry.name === "string" ? entry.name : "(unnamed)";
+        for (const id of stringArray(entry.enforceAgents)) {
+            enforced.add(id);
+        }
+        const configDir = typeof entry.config === "string" ? entry.config : null;
+        if (configDir) {
+            const setupDir = path.resolve(index.root, configDir, CONFIG_DIRNAME);
+            if (!pathInside(setupDir, index.root)) {
+                problems.push({
+                    file: relative,
+                    line: 1,
+                    kind: "structural",
+                    problem: `scope "${name}" points outside the repository (config: ${configDir})`,
+                });
+            }
+            else if ((await pathKind(setupDir)) !== "dir") {
+                problems.push({
+                    file: relative,
+                    line: 1,
+                    kind: "structural",
+                    problem: `scope "${name}" has no ${configDir}/${CONFIG_DIRNAME}/ directory`,
+                });
+            }
+        }
+        if (index.files.length > 0) {
+            for (const pattern of stringArray(entry.paths)) {
+                const variants = [pattern, pattern.replace(/\*\*\//g, "")];
+                if (!index.files.some((repoFile) => variants.some((v) => v && matchesIgnore(repoFile, v)))) {
+                    problems.push({
+                        file: relative,
+                        line: 1,
+                        kind: "structural",
+                        problem: `scope "${name}" glob matches no file in the repo: ${pattern}`,
+                    });
+                }
+            }
+        }
+    }
+    for (const id of enforced) {
+        if (!rootAgentIds.has(id)) {
+            problems.push({
+                file: relative,
+                line: 1,
+                kind: "structural",
+                problem: `enforceAgents names "${id}", but the root setup has no agents/${id}.md`,
+            });
+        }
+    }
+    return problems;
+}
+/** Agent ids in a setup dir (id = filename without `.md`, per the loader). */
+async function agentIds(setupDir) {
+    try {
+        const entries = await readdir(path.join(setupDir, "agents"));
+        return new Set(entries.filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -3)));
+    }
+    catch {
+        return new Set();
+    }
+}
+// @ref LLP 0012#run-points-command-and-review [implements] — one pure-ish entry point both the command and the review call
+/**
+ * Check every code citation in the repo's review setup. Deterministic, no model, no
+ * network: refs either resolve against the tree or they do not.
+ */
+export async function checkConfigRefs(options) {
+    const root = path.resolve(options.root);
+    const index = { root, files: await listRepoFiles(root) };
+    const dirs = options.setupDirs ?? (await discoverSetupDirs(root));
+    const problems = [];
+    const refs = [];
+    const scannedFiles = [];
+    const citedPaths = new Set();
+    // 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();
+    /** The root-relative path an extensionless token names, or null if it names nothing. */
+    const namedPath = async (token, scopeRoot) => {
+        for (const candidate of pathishCandidates(token)) {
+            for (const base of [root, scopeRoot]) {
+                const absolute = path.resolve(base, candidate);
+                let resolved = resolvable.get(absolute);
+                if (resolved === undefined) {
+                    const kind = pathInside(absolute, root) ? await pathKind(absolute) : "missing";
+                    resolved =
+                        kind === "missing"
+                            ? null
+                            : path.relative(root, absolute).split(path.sep).join("/") +
+                                (kind === "dir" ? "/" : "");
+                    resolvable.set(absolute, resolved);
+                }
+                if (resolved) {
+                    return resolved;
+                }
+            }
+        }
+        return null;
+    };
+    for (const dir of dirs) {
+        const scopeRoot = path.dirname(dir);
+        for (const file of await setupFiles(dir)) {
+            const relative = fileLabel(root, dir, file);
+            let text;
+            try {
+                text = await readFile(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            scannedFiles.push(relative);
+            const annotated = parseRefAnnotations(text, relative);
+            const ignored = parseRefIgnores(text);
+            const covered = new Set(annotated.flatMap((ref) => coveringForms(ref.target)));
+            // A glob ref also covers any citation the glob itself matches, so a prompt can
+            // cite `.../nested/Handler.kt` and pin it once with `glob:**/Handler.kt`.
+            const coveringGlobs = annotated
+                .filter((ref) => ref.target.startsWith(GLOB_PREFIX))
+                .map((ref) => ref.target.slice(GLOB_PREFIX.length));
+            for (const ref of annotated) {
+                const problem = await resolveTarget(ref.target, index, scopeRoot);
+                if (problem) {
+                    problems.push({
+                        file: relative,
+                        line: ref.line,
+                        kind: problem.startsWith("cites a line number") ? "line-number-ref" : "broken-ref",
+                        problem,
+                    });
+                    continue;
+                }
+                // An `LLP NNNN` target belongs to a different mechanism (a design corpus, owned
+                // by that repo's own checker). ecr neither resolves nor counts it: the refs it
+                // owns are the ones citing the reviewed code.
+                if (LLP_TARGET_RE.test(ref.target)) {
+                    continue;
+                }
+                refs.push(ref);
+                const cited = splitAnchor(ref.target)[0];
+                if (cited && !cited.startsWith(GLOB_PREFIX) && !URL_RE.test(cited)) {
+                    citedPaths.add(cited.replace(/\/$/, ""));
+                }
+            }
+            for (const { line, token } of findProseCitations(text)) {
+                // 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;
+                }
+                // Coverage must accept the path the token RESOLVED to, not just the token as
+                // written: a prompt says `cert-manager` and the ref that pins it is
+                // `infrastructure/cert-manager/`. Without this, the fix the message suggests
+                // does not silence the citation it was suggested for.
+                const forms = [...citationForms(token), ...(named ? coveringForms(named) : [])];
+                if (ignored.has(token) ||
+                    forms.some((form) => covered.has(form)) ||
+                    coveringGlobs.some((pattern) => forms.some((form) => matchesIgnore(form.replace(/^\.\.\.\//, ""), pattern)))) {
+                    continue;
+                }
+                const lineCitation = LINE_CITATION_RE.exec(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,
+                    kind: lineCitation ? "line-number-ref" : "unannotated-citation",
+                    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)`,
+                });
+            }
+        }
+        const routing = path.join(dir, ROUTING_FILENAME);
+        if ((await pathKind(routing)) === "file") {
+            // The roster comes from the dir that OWNS the manifest, never from `root`:
+            // under `ecr ci` the setup is a trusted base-ref checkout while `root` is the PR
+            // head tree, so reading `root/.expo-code-review/agents` would judge enforceAgents
+            // against a different (or absent) roster than the one actually loaded.
+            problems.push(...(await checkRoutingManifest(routing, index, await agentIds(dir))));
+        }
+    }
+    problems.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.problem.localeCompare(b.problem));
+    return {
+        ok: problems.length === 0,
+        problems,
+        refs,
+        scannedFiles,
+        citedPaths: [...citedPaths].sort(),
+    };
+}
+/** How many examples a review-side note names before saying "and N more". */
+const NOTE_EXAMPLES = 5;
+function andMore(items) {
+    const shown = items.slice(0, NOTE_EXAMPLES).join(", ");
+    const rest = items.length - NOTE_EXAMPLES;
+    return rest > 0 ? `${shown}, and ${rest} more` : shown;
+}
+// @ref LLP 0012#run-points-command-and-review [constrained-by] — advises, never fails the review
+/**
+ * The advice a review gives about its own setup: refs that no longer resolve, and cited
+ * code this PR changes (where the ref still resolves but the guidance may not). Returns
+ * an empty array when the setup is clean, so a healthy run stays silent.
+ */
+export async function reviewSetupRefNotes(options) {
+    let report;
+    try {
+        report = await checkConfigRefs({ root: options.root, setupDirs: options.setupDirs });
+    }
+    catch {
+        return []; // a check that cannot run must never degrade the review
+    }
+    const notes = [];
+    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)): ` +
+            `${andMore(broken.map((problem) => `${problem.file}:${problem.line}`))}. ` +
+            "Run `ecr ref-check` — the prompts may be reviewing against code that moved.");
+    }
+    const touched = citedPathsTouchedBy(report, options.changedFiles);
+    if (touched.length > 0) {
+        notes.push(`This PR changes code the reviewer prompts cite (${andMore(touched)}). ` +
+            "Check that the guidance quoting it is still correct.");
+    }
+    return notes;
+}
+/**
+ * Which of this PR's changed files are cited by a ref. The review uses this to say
+ * "you moved code the reviewer prompts point at" even when the ref still resolves.
+ */
+export function citedPathsTouchedBy(report, changedFiles) {
+    const touched = new Set();
+    for (const changed of changedFiles) {
+        for (const cited of report.citedPaths) {
+            if (changed === cited || changed.startsWith(`${cited}/`)) {
+                touched.add(cited);
+            }
+        }
+    }
+    return [...touched].sort();
+}

package/build/core/render.js

@@ -156,6 +156,7 @@ export function renderMarkdown(review, tag, dismissed = [], link, feedback = [],
     if (review.incomplete.length > 0) {
         lines.push("> ⏱️ **Coverage note:** coverage is partial — some review passes did not", "> finish (timed out or failed), so issues may exist in areas not fully reviewed:", ...review.incomplete.map((note) => `> - ${stripStateMarkers(note)}`), "");
     }
+    lines.push(...setupNote(review.setupNotes));
     lines.push(...requalificationAuditNote(requalified.map((entry) => entry.finding)));
     lines.push(...feedbackAuditNote([...feedbackByFp.values()]));
     if (kept.length === 0) {
@@ -235,6 +236,14 @@ function renderFindingLines(finding, link, id = fingerprintFinding(finding), rep
     out.push("");
     return out;
 }
+// @ref LLP 0012#run-points-command-and-review [implements] — setup advice renders outside the findings list, so it never blocks
+/** Advice about the reviewer's own setup (stale refs, cited code this PR moves). */
+function setupNote(notes = []) {
+    if (notes.length === 0) {
+        return [];
+    }
+    return ["> 🔗 **Review setup:**", ...notes.map((note) => `> - ${stripStateMarkers(note)}`), ""];
+}
 // @ref LLP 0010#rendering-in-all-three-paths [implements] — the visible audit count is mandatory: requalification's only effect on a real finding is moving it out of the blocking set, so it must never be silent
 /**
  * The visible one-line audit note in the OPEN body, naming the addressing PRs. This
@@ -423,6 +432,10 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts, fee
             }
             lines.push("");
         }
+        const setupLines = results.flatMap((result) => (result.review.setupNotes ?? []).map((note) => `> - [${stripStateMarkers(result.scope)}] ${stripStateMarkers(note)}`));
+        if (setupLines.length > 0) {
+            lines.push("> 🔗 **Review setup:**", ...setupLines, "");
+        }
         // Shown = the most-severe N kept findings per scope (N = limitPerScope). The
         // embedded state trims KEPT findings to the same set so a truncated comment
         // still fits GitHub's body limit (the hidden findings are noted, not silently

package/build/core/review.js

@@ -15,6 +15,7 @@ import { confirmStackRequalifications, patchConfirmer } from "./stack-confirm.js
 import { sortFindings } from "./render.js";
 import { appendStepSummary } from "./step-summary.js";
 import { errorMessage, sleep } from "./util.js";
+import { reviewSetupRefNotes } from "./config-refs.js";
 import { verifyFindings } from "./verify.js";
 import { applyInlineIgnores } from "./suppress.js";
 /**
@@ -168,6 +169,19 @@ export async function runReview(source, options) {
         progress("Reviewing the PR-head tree (so reads match the PR, not the checkout).");
         process.chdir(readRoot.dir);
     }
+    // Ref integrity of the setup that is about to review this PR. Resolved against the
+    // tree the reviewers read (PR head when materialized), while the setup itself may
+    // come from the trusted base ref — so a PR that moves cited code is reported against
+    // the prompts that will actually judge it.
+    // @ref LLP 0012#run-points-command-and-review [implements] — every review checks its own refs; advice only, never a gate
+    const setupNotes = await reviewSetupRefNotes({
+        root: readRoot?.dir ?? originalCwd,
+        setupDirs: [config.configDir],
+        changedFiles: kept.map((entry) => entry.path),
+    });
+    for (const note of setupNotes) {
+        progress(`  setup: ${note}`);
+    }
     const starting = [
         usesClaude ? "Claude Code engine" : null,
         usesOpencode ? "OpenCode server" : null,
@@ -862,7 +876,10 @@ export async function runReview(source, options) {
             findingCount: output.findings.length,
             summary: output.summary,
         });
-        return feedbackRecords ? { ...output, feedback: feedbackRecords } : output;
+        // Engine-owned: overwrite whatever the coordinator may have emitted under this key,
+        // so setup advice is always the checker's, never model text.
+        const reviewed = { ...output, setupNotes };
+        return feedbackRecords ? { ...reviewed, feedback: feedbackRecords } : reviewed;
     }
     catch (error) {
         await safeLog(logPath, {

package/build/core/schema.js

@@ -115,6 +115,16 @@ export const CoordinatorOutputSchema = z.object({
      * overrides the presentation instead).
      */
     couldNotComplete: z.boolean().optional(),
+    /**
+     * Advice about the review's OWN setup: refs in `.expo-code-review/` that no longer
+     * resolve, and cited code this PR changes. Engine-set (never the model, never a
+     * finding) and never blocking — a stale prompt is a maintenance signal, not a defect
+     * in the PR.
+     */
+    // @ref LLP 0012#run-points-command-and-review [implements] — the review advises about stale refs instead of failing on them
+    // Optional (like couldNotComplete) so every internal CoordinatorOutput literal stays
+    // valid without restating an engine-owned field.
+    setupNotes: z.array(z.string()).optional(),
 });
 /** How an author's reply to a finding held up against the source. */
 export const FEEDBACK_VERDICTS = ["accepted", "refuted", "unclear"];

package/build/reporters/terminal.js

@@ -51,6 +51,14 @@ export class TerminalReporter {
             }
             out.push("");
         }
+        const setupNotes = review.setupNotes ?? [];
+        if (setupNotes.length > 0) {
+            out.push(this.paint(BOLD, "🔗 Review setup:"));
+            for (const note of setupNotes) {
+                out.push(this.paint(DIM, `  - ${note}`));
+            }
+            out.push("");
+        }
         if (review.findings.length === 0) {
             out.push(this.paint(DIM, "No findings."), "");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/agents/consistency.md

@@ -39,7 +39,10 @@ must support `--non-interactive` the way sibling commands do (a non-interactive
 path with no prompts, erroring clearly when a required value is missing), and it
 must expose flags to supply every prompted value so the command stays scriptable.
 
-<!-- TODO: replace the example above with this repo's most important conventions. -->
+<!-- TODO: replace the example above with this repo's most important conventions.
+     Pin each file, directory, or symbol you cite with a ref on its own line —
+         @ref <path/to/file.ts>#<symbol> — why this matters
+     so `ecr ref-check` fails when the cited code moves. Never a line number. -->
 
 ## What NOT to flag
 

package/templates/agents/correctness.md

@@ -19,7 +19,13 @@ issues in the changed code.
   concrete trigger.
 
 <!-- TODO: customize for this repo — add project-specific correctness rules,
-     e.g. framework conventions, required flag handling, API compatibility. -->
+     e.g. framework conventions, required flag handling, API compatibility.
+
+     Cite real code, and pin every citation with a ref so `ecr ref-check` fails when
+     it moves. In a comment of its own, on one line:
+         @ref <path/to/file.ts>#<symbol> — why this matters
+     Targets: a file, a `<dir>/`, `glob:<pattern>`, `<file>#<symbol>`, `<doc>.md#<heading>`.
+     Never a line number. Not a path? `@ref-ignore <token>`. -->
 
 ## What NOT to flag
 

package/templates/agents/security.md

@@ -26,7 +26,14 @@ average severity.
 - Insecure file permissions, or writing secrets to world-readable paths.
 
 <!-- TODO: customize for this repo — name the sensitive surfaces specific to this
-     codebase (credential stores, tokens, arbitrary-command features, etc.). -->
+     codebase (credential stores, tokens, arbitrary-command features, etc.).
+
+     Pin every path or symbol you cite with a ref, on a line of its own:
+         @ref <path/to/file.ts>#<symbol> — why this matters
+     `ecr ref-check` then fails when that code moves, so this prompt never sends a
+     reviewer after a file that no longer exists. Never cite a line number. -->
+
+<!-- @ref glob:.github/workflows/** — the workflows this section judges -->
 
 ## CI / workflow supply-chain (changes under `.github/workflows/**`)
 

package/templates/shared.md

@@ -12,6 +12,9 @@ These rules apply to every reviewer and are concatenated onto your role prompt.
 - **Do not judge the diff in isolation.** Before reporting, read the surrounding
   source with your file/read/grep tools and trace the relevant execution path.
   If you cannot substantiate a concrete failure or exploit path, do not report it.
+<!-- Generic guidance, not a claim that either file exists. Once this repo has one,
+     replace this with a real ref: @ref AGENTS.md — the conventions to judge against -->
+<!-- @ref-ignore AGENTS.md CLAUDE.md -->
 - Ground your judgment in the repo's own conventions (`AGENTS.md` / `CLAUDE.md`
   at the repo root, and any per-directory guidance) rather than generic
   best-practices.