@expo/code-review-cli 0.7.0 → 0.8.0

package/build/sources/github-pr.js

@@ -1,13 +1,120 @@
+// @ref LLP 0008#pr-head-materialization — PR HEAD is materialized as a detached worktree pinned to the immutable head OID, never a branch/ref name
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { resolveTrustedTool, run } from "../core/exec.js";
 import { parseUnifiedDiff } from "../core/diff.js";
+import { normalizeManifestPath } from "../core/stack.js";
 import { removeEscapingSymlinks, scrubAmbientRuntimeConfig } from "../core/scrub.js";
 /** A full 40-hex-char commit OID — the only ref form passed to security-sensitive git calls. */
+// @ref LLP 0008#pr-head-materialization [constrained-by] — the single gate: only a full 40-hex OID reaches git worktree add/fetch, closing the TOCTOU race and blocking ref/argument injection at once
 export function isCommitOid(value) {
     return typeof value === "string" && /^[0-9a-f]{40}$/i.test(value);
 }
+// @ref LLP 0010#bounded-guarded-upward-walk [implements] — every guard (same-repo, same-author, depth/width caps, cycle guard, fail-open) lives here as pure logic; the IO is injected so it is unit-testable without gh
+/**
+ * The bounded, guarded upward walk, factored pure over injected fetchers so it can be
+ * tested without gh. Level-by-level (BFS over head branches), it keeps only same-repo
+ * (and, when required, same-author) children, caps children per level at `maxPrs`,
+ * stops at `maxDepth`, and guards against branch cycles. ANY fetch error → `null`
+ * (fail-open); an empty result → `null` (nothing to inject).
+ */
+export async function walkUpstack(rootHeadRef, rootAuthor, options, fetchChildren, fetchFiles) {
+    const upstackPRs = [];
+    let truncated = false;
+    const visited = new Set([rootHeadRef]);
+    let frontier = [rootHeadRef];
+    try {
+        for (let depth = 0; depth < options.maxDepth && frontier.length > 0; depth++) {
+            const next = [];
+            // maxPrs is a PER-LEVEL budget shared by every parent in the frontier, not a
+            // per-parent one — otherwise a branching (diamond) stack would widen each level
+            // to frontier.length × maxPrs and compound across depths, blowing the documented
+            // hard bound on walked PRs and gh calls.
+            let levelBudget = options.maxPrs;
+            for (const baseBranch of frontier) {
+                if (levelBudget <= 0) {
+                    break;
+                }
+                const children = await fetchChildren(baseBranch);
+                const eligible = children
+                    .filter((child) => child.sameRepo)
+                    .filter((child) => !options.requireSameAuthor || child.authorLogin === rootAuthor)
+                    .filter((child) => !visited.has(child.headRef))
+                    .slice(0, levelBudget);
+                levelBudget -= eligible.length;
+                for (const child of eligible) {
+                    visited.add(child.headRef);
+                    const { files, truncated: capped } = await fetchFiles(child.number);
+                    truncated = truncated || capped;
+                    upstackPRs.push({
+                        number: child.number,
+                        title: child.title,
+                        authorLogin: child.authorLogin,
+                        files,
+                    });
+                    next.push(child.headRef);
+                }
+            }
+            frontier = next;
+        }
+    }
+    catch {
+        return null;
+    }
+    return upstackPRs.length > 0 ? { upstackPRs, truncated } : null;
+}
+/**
+ * Parse the NDJSON `{filename}` lines from the child-PR files endpoint into a clean
+ * path list. Any name carrying a control character (a git path may legally contain
+ * a newline) is dropped outright: split on raw lines it would have forged an extra
+ * manifest entry, and no legitimate reviewable path needs control characters. A
+ * malformed line throws — the walk's fail-open catch turns that into "no manifest".
+ * Exported for tests.
+ */
+export function parseChildFileNdjson(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line).filename ?? "")
+        .filter((name) => name.length > 0 && ![...name].some((char) => char.charCodeAt(0) < 0x20));
+}
+/** Page size for the child-PR files endpoint (fetchAllComments convention). */
+export const CHILD_FILES_PER_PAGE = 100;
+/**
+ * Safety cap on pagination, same convention as the reporter's MAX_COMMENT_PAGES:
+ * 30 pages = 3000 files bounds a pathological child PR; virtually every real
+ * child PR exits far earlier via the maxFiles early stop below.
+ */
+export const MAX_CHILD_FILE_PAGES = 30;
+/**
+ * Collect a child PR's file pages, factored pure over an injected per-page fetcher
+ * (same pattern as walkUpstack) so the stop conditions are testable without gh.
+ * Stops at end-of-list, one entry past `maxFiles` (enough to know the list is
+ * truncated — never paginates a huge child PR to the end just to throw the tail
+ * away), or the hard page ceiling. Exported for tests.
+ */
+export async function collectChildFiles(fetchPage, maxFiles) {
+    const files = [];
+    let sawEnd = false;
+    for (let page = 1; page <= MAX_CHILD_FILE_PAGES && !sawEnd; page++) {
+        const stdout = await fetchPage(page);
+        // "Last page?" is decided on the RAW line count (jq emits exactly one NDJSON
+        // line per array element): parseChildFileNdjson drops control-char names, so
+        // deciding on its output would mistake a page with a dropped entry for the
+        // final page and silently skip the rest of the list.
+        const rawCount = stdout.split("\n").filter((line) => line.trim()).length;
+        files.push(...parseChildFileNdjson(stdout));
+        sawEnd = rawCount < CHILD_FILES_PER_PAGE;
+        if (files.length > maxFiles) {
+            break;
+        }
+    }
+    // Hitting the page ceiling without seeing the end of the list still marks the
+    // manifest as a subset — never claim completeness that wasn't observed.
+    return { files: files.slice(0, maxFiles), truncated: files.length > maxFiles || !sawEnd };
+}
 /**
  * Append gh as a git credential helper for a single command. The token comes from
  * GH_TOKEN via the credential-helper protocol — never argv, never `.git/config` —
@@ -130,6 +237,7 @@ export class GitHubPRSource {
      * Materialization FAILURES throw — the caller decides per mode whether that is
      * fatal (CI: fail closed) or a soft fallback (local: the user's own checkout).
      */
+    // @ref LLP 0008#pr-head-materialization [implements] — a half-scrubbed tree must never be returned; a scrub failure tears down the worktree and rethrows instead of handing back a partial scrub
     async prepareReadRootAsync() {
         if (!this.options.repo) {
             // Without an explicit owner/repo we can't build the fetch URL safely.
@@ -151,12 +259,176 @@ export class GitHubPRSource {
         }
         return root;
     }
+    // @ref LLP 0010#bounded-guarded-upward-walk [constrained-by] — the whole method is wrapped fail-open: no gh/parse error ever escapes as a throw, so a broken walk can never fail a check or block a finding
+    /**
+     * Walk the OPEN PRs stacked on top of this one and return a paths-only manifest.
+     * Fails open to `null` on ANY error (no repo, gh failure, rate limit, parse error,
+     * empty stack), so the review is exactly as if the feature were off.
+     */
+    async getStackContextAsync(options) {
+        const repo = this.options.repo;
+        if (!repo) {
+            // Without an explicit owner/repo we can't query the pulls list safely.
+            return null;
+        }
+        try {
+            const gh = await resolveTrustedTool("gh");
+            const [metadata, anchors] = await Promise.all([
+                this.getMetadata(),
+                this.fetchPrTrustAnchors(gh, repo),
+            ]);
+            if (!metadata.headRef || !anchors.author) {
+                return null;
+            }
+            // A fork PR's headRefName is a branch of the FORK, not of the base repo. Using
+            // it as the pulls-list `base=` filter would match a same-named BASE-repo branch
+            // (a fork head called "main" would pull in every open PR targeting main), so
+            // unrelated PRs would enter the manifest. A cross-repo head has no base-repo
+            // branch to walk — there is no stack.
+            if (anchors.crossRepo) {
+                return null;
+            }
+            return await walkUpstack(metadata.headRef, anchors.author, options, (baseBranch) => this.fetchOpenChildren(gh, repo, baseBranch), (prNumber) => this.fetchChildFiles(gh, repo, prNumber, options.maxFilesPerPr));
+        }
+        catch {
+            return null;
+        }
+    }
+    // @ref LLP 0010#patch-level-confirmation-v2 [implements] — fetch ONLY the cited file's patch, match by the same normalization grounding uses; the untrusted filename is filtered in JS, never spliced into a jq program
+    /**
+     * The unified-diff patch a stacked child PR (`prNumber`) applied to `file`, or `null`
+     * when the file isn't in that PR (or on any error — fail-open toward blocking). The
+     * files endpoint's `.patch` fragment is inlined by the caller and never written to
+     * disk. The untrusted `file` is matched against each entry's filename in JS (same
+     * normalization as grounding), NOT passed into the jq program, so it can't inject.
+     */
+    async getStackFilePatchAsync(prNumber, file) {
+        const repo = this.options.repo;
+        if (!repo) {
+            return null;
+        }
+        try {
+            const gh = await resolveTrustedTool("gh");
+            const { stdout } = await run(gh, [
+                "api",
+                // --method GET is mandatory once a -f field is present (else gh POSTs);
+                // 100/page is the fetchAllComments pagination convention.
+                "--method",
+                "GET",
+                `repos/${repo}/pulls/${prNumber}/files`,
+                "-f",
+                "per_page=100",
+                "--paginate",
+                "--jq",
+                ".[] | {filename, patch}",
+            ], { cwd: this.options.cwd });
+            const want = normalizeManifestPath(file);
+            for (const line of stdout.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    continue;
+                }
+                const raw = JSON.parse(trimmed);
+                if (raw.filename && normalizeManifestPath(raw.filename) === want) {
+                    // A file with no textual patch (binary/rename-only) can't confirm a fix.
+                    return typeof raw.patch === "string" ? raw.patch : null;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * The current PR's author login (the same-author gate's trust anchor) and whether
+     * its head lives in another repository (a fork — see the cross-repo guard above).
+     */
+    async fetchPrTrustAnchors(gh, repo) {
+        const { stdout } = await run(gh, [
+            "pr",
+            "view",
+            String(this.options.prNumber),
+            "--repo",
+            repo,
+            "--json",
+            "author,isCrossRepository",
+        ], { cwd: this.options.cwd });
+        const raw = JSON.parse(stdout);
+        const author = raw.author?.login?.trim();
+        return { author: author || null, crossRepo: raw.isCrossRepository === true };
+    }
+    /** Open PRs whose base branch is `baseBranch` (this PR's head, or a child's head). */
+    async fetchOpenChildren(gh, repo, baseBranch) {
+        // --method GET is mandatory (else gh POSTs); --paginate + a per-element --jq
+        // yields NDJSON that stays valid when gh concatenates pages.
+        const { stdout } = await run(gh, [
+            "api",
+            "--method",
+            "GET",
+            `repos/${repo}/pulls`,
+            "-f",
+            "state=open",
+            "-f",
+            `base=${baseBranch}`,
+            // Safety cap on pagination (100/page), same convention as fetchAllComments:
+            // fewer round-trips per level of the walk.
+            "-f",
+            "per_page=100",
+            "--paginate",
+            "--jq",
+            ".[] | {number, title, authorLogin: .user.login, headRef: .head.ref, headRepoFullName: .head.repo.full_name}",
+        ], { cwd: this.options.cwd });
+        return stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const raw = JSON.parse(line);
+            return {
+                number: raw.number,
+                title: raw.title ?? "",
+                authorLogin: raw.authorLogin ?? "",
+                headRef: raw.headRef ?? "",
+                sameRepo: raw.headRepoFullName === repo,
+            };
+        });
+    }
+    /**
+     * A child PR's changed paths, capped at `maxFiles` with a truncated marker.
+     * Pages are fetched one by one (not `--paginate`, which would walk a large
+     * child PR's whole file list before the client-side cap applies) so pagination
+     * stops as soon as the cap is exceeded, and never past MAX_CHILD_FILE_PAGES.
+     */
+    async fetchChildFiles(gh, repo, prNumber, maxFiles) {
+        return collectChildFiles(async (page) => {
+            const { stdout } = await run(gh, [
+                "api",
+                // --method GET is mandatory once a -f field is present (else gh POSTs).
+                "--method",
+                "GET",
+                `repos/${repo}/pulls/${prNumber}/files`,
+                "-f",
+                `per_page=${CHILD_FILES_PER_PAGE}`,
+                "-f",
+                `page=${page}`,
+                "--jq",
+                // Objects, NOT raw strings (.[].filename): gh prints a raw string result
+                // one value per line, so a git path containing a newline would split into
+                // TWO manifest entries — one of them a forged membership the grounding
+                // check would then accept. NDJSON keeps the newline escaped.
+                ".[] | {filename}",
+            ], { cwd: this.options.cwd });
+            return stdout;
+        }, maxFiles);
+    }
     /**
      * Materialize the PR's BASE commit as the trusted configuration root: review
      * policy, prompts, routing, and auth mapping load from here, so a PR cannot
      * change the reviewer that evaluates it (config changes activate on merge).
      * Failures throw — `ecr ci` must fail closed, never fall back to the checkout.
      */
+    // @ref LLP 0008#the-trusted-base-root [implements] — materializes the PR BASE (not HEAD) as a separate, unscrubbed worktree; a PR cannot change the reviewer that evaluates it
     async prepareTrustedConfigRootAsync() {
         const metadata = await this.getMetadata();
         if (!isCommitOid(metadata.baseOid)) {

package/build/sources/local-git.js

@@ -1,3 +1,4 @@
+// @ref LLP 0008#local-git-source — no network; diff base is merge-base(defaultBranch, HEAD), not the branch tip
 import { git, resolveTrustedTool, run } from "../core/exec.js";
 import { parseUnifiedDiff } from "../core/diff.js";
 /**
@@ -36,6 +37,7 @@ export class LocalGitSource {
         }
         return "main";
     }
+    // @ref LLP 0008#local-git-source [implements] — merge-base(default, HEAD), not the branch tip: reviews only the current branch's own changes, excluding commits merged into default after divergence
     async resolveBase() {
         if (this.resolvedBase) {
             return this.resolvedBase;
@@ -87,6 +89,7 @@ export class LocalGitSource {
      * Synthesize add-diffs for untracked files without mutating the index. Uses
      * `git diff --no-index` (which exits 1 when files differ, hence check: false).
      */
+    // @ref LLP 0008#local-git-source [implements] — no-index diff against /dev/null avoids mutating the index; -z listing and the -- separator guard against newline- and dash-prefixed filenames
     async untrackedDiffs() {
         // -z: null-terminated output so filenames containing newlines parse correctly.
         const listing = await git(["ls-files", "-z", "--others", "--exclude-standard"], this.cwd);

package/build/sources/source.js

@@ -1,3 +1,18 @@
+/** Pick the walk bounds out of a resolved stack config (drops enable/v2 fields). */
+export function stackWalkFromConfig(stack) {
+    return {
+        maxDepth: stack.maxDepth,
+        maxPrs: stack.maxPrs,
+        maxFilesPerPr: stack.maxFilesPerPr,
+        requireSameAuthor: stack.requireSameAuthor,
+    };
+}
+/** The v2 confirmation cap, or undefined when confirmWithPatch is off. Callers apply
+ * the on/off gate (ci: trusted-base `enabled`; review: `--stack-aware`) around this. */
+// @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — confirmWithPatch is the v2 gate; off (default) → grounding is the floor and no patch is ever fetched
+export function stackConfirmFromConfig(stack) {
+    return stack.confirmWithPatch ? { maxConfirmations: stack.maxConfirmations } : undefined;
+}
 /**
  * Wrap a source so getMetadata/getChangedFiles/prepareReadRootAsync each run once
  * and are shared across N sequential runReview calls (one `gh pr diff`, one
@@ -5,14 +20,34 @@
  * prepareReadRootAsync hands each run a handle whose cleanup() is a no-op; the real
  * cleanup is deferred to dispose(), which must be called once after the last scope.
  */
+// @ref LLP 0008#the-reviewsource-contract [implements] — one fetch/worktree shared across N scope runs; dispose() must run once, after the last scope, not per call
 export function memoizeSource(source) {
     let metadataPromise;
     let changedPromise;
     let readRootPromise;
+    let stackPromise;
     let realHandle = null;
+    const stackFn = source.getStackContextAsync;
+    const patchFn = source.getStackFilePatchAsync;
     return {
         getMetadata: () => (metadataPromise ??= source.getMetadata()),
         getChangedFiles: () => (changedPromise ??= source.getChangedFiles()),
+        // One PR has one stack: fetch it once and share it across every scope's run
+        // (like getMetadata). Only exposed when the wrapped source can walk a stack, so
+        // an optional-chained call on a stack-less source stays a structural no-op.
+        ...(stackFn
+            ? {
+                getStackContextAsync: (options) => (stackPromise ??= stackFn.call(source, options)),
+            }
+            : {}),
+        // Passed straight through: v2 confirmation dedupes by (prNumber, file) within a run
+        // and the fetch is cheap, so it needs no cross-scope memo — only the conditional
+        // exposure that keeps a stack-less source a structural no-op.
+        ...(patchFn
+            ? {
+                getStackFilePatchAsync: (prNumber, file) => patchFn.call(source, prNumber, file),
+            }
+            : {}),
         prepareReadRootAsync: async () => {
             readRootPromise ??= source.prepareReadRootAsync
                 ? source.prepareReadRootAsync()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,7 @@
     "lint": "oxlint src",
     "fmt": "oxfmt --threads=1 src",
     "fmt:check": "oxfmt --threads=1 --check src",
+    "llp:check": "./ref-check",
     "dev": "bun run src/cli.ts",
     "test:unit": "bun test",
     "release": "bash scripts/release.sh",

package/templates/agents/consistency.md

@@ -1,3 +1,4 @@
+<!-- @ref LLP 0009#prompt-rules-for-adopters — restraint is a cross-cutting constraint, echoed from shared.md -->
 ---
 description: Consistency with the repo's existing patterns and conventions for the same kind of change (flags, error messages and types, structure).
 ---
@@ -49,5 +50,6 @@ must expose flags to supply every prompted value so the command stays scriptable
 - A "pattern" you saw only once — you need multiple existing examples to call
   something an established convention.
 
+<!-- @ref LLP 0009#prompt-rules-for-adopters [implements] — precedent requirement is this agent's form of restraint -->
 Only flag when you can name the existing sibling(s) that establish the pattern and
 say why matching it matters. If you can't point to the precedent, don't report it.

package/templates/agents/correctness.md

@@ -1,3 +1,4 @@
+<!-- @ref LLP 0009#prompt-rules-for-adopters — restraint is a cross-cutting constraint, echoed from shared.md -->
 ---
 description: Logic, correctness, and code-quality bugs in the changed code (off-by-one, bad error handling, type-safety gaps, unsafe assumptions).
 ---
@@ -29,4 +30,5 @@ issues in the changed code.
 - Nitpicks about naming or idiom when the existing convention is being followed.
 - Anything a type-checker or linter would already catch.
 
+<!-- @ref LLP 0009#prompt-rules-for-adopters [implements] -->
 Prefer zero findings over a low-value one.

package/templates/agents/security.md

@@ -1,3 +1,4 @@
+<!-- @ref LLP 0009#workflow-security-posture — highest-stakes agent; author-association gates control who, not what -->
 ---
 description: Security and secrets. Injection, credential or secret leakage, unsafe shell/child-process use, missing validation at trust boundaries.
 alwaysRun: true
@@ -5,6 +6,7 @@ alwaysRun: true
 # reasoning, so it runs on the pro tier even though the other specialists use the
 # default model. Scoped to this one agent to limit the extra latency/rate-limit cost;
 # subdivide-on-timeout + the per-fetch deadline keep a slow pro pass from hanging.
+# @ref LLP 0009#config-and-prompt-templates [implements]
 model: openai/gpt-5.5-pro
 ---
 
@@ -36,6 +38,7 @@ the code. Flag:
   ref) and also exposes secrets or a write-scoped `GITHUB_TOKEN` in that job's
   environment is a secret-exfiltration RCE — the attacker controls build scripts,
   source, and install-time lifecycle hooks.
+<!-- @ref LLP 0009#workflow-security-posture [explains] — quoted verbatim in the guide's workflow security posture -->
 - **Trigger fork semantics.** `pull_request` from a fork runs with secrets
   withheld and a read-only token; `issue_comment`, `workflow_run`, and
   `pull_request_target` are **NOT** fork-restricted. An `author_association` /

package/templates/atlantis.yml

@@ -0,0 +1,123 @@
+# @ref LLP 0009#atlantis-comment-triggered-template — issue_comment plan trigger; base-only checkout, comment body via env → --context-file
+name: AI code review (atlantis plan)
+
+# Runs the reviewer when Atlantis posts a `terraform plan` result on a PR, feeding
+# the plan output into the review as UNTRUSTED external context (`--context-file`).
+# This is an OPT-IN extra template — `ecr init` does NOT scaffold it. Copy it into
+# .github/workflows/ and set two repo variables:
+#   ATLANTIS_BOT_LOGIN   the Atlantis bot's comment author login (e.g. atlantis-app[bot])
+#   ATLANTIS_PLAN_MARKER optional; the plan-comment marker text (default 'Ran Plan for')
+
+on:
+  issue_comment:
+    types: [created]
+
+# Comment-only: read the repo, write PR comments (issue comments API).
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+env:
+  # Published reviewer run via npx (override with repo variable ECR_VERSION; pin to a
+  # specific version to freeze it). Used for the guard AND the review so the engine
+  # that clears a config is the same engine that then reads it.
+  ECR_VERSION: ${{ vars.ECR_VERSION || 'latest' }}
+
+concurrency:
+  group: ai-code-review-atlantis-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  atlantis-plan:
+    # Gate on WHO commented, not on what the run does: only a comment from the
+    # Atlantis bot login, on a PR, whose body carries the plan marker. The login
+    # gate is the security boundary (bot comments are write-gated); the marker is a
+    # cheap filter and is operator-overridable via ATLANTIS_PLAN_MARKER, so it must
+    # not be the only gate. Templates are also overridable via
+    # --markdown-template-overrides-dir, which is exactly why the identity gate is on
+    # the bot login and not on the marker text.
+    # @ref LLP 0009#atlantis-comment-triggered-template [implements] — identity gate on the bot login; marker filter is operator-overridable
+    if: >-
+      github.event.issue.pull_request != null &&
+      github.event.comment.user.login == vars.ATLANTIS_BOT_LOGIN &&
+      contains(github.event.comment.body, vars.ATLANTIS_PLAN_MARKER || 'Ran Plan for')
+    runs-on: ubuntu-latest
+    # Keep margin over the worst-case internal chain (passes budget 55m + coordinator
+    # 10m + verification + setup), like the auto-review workflow's cap.
+    timeout-minutes: 90
+    # A reviewer failure must never fail the PR's checks.
+    continue-on-error: true
+    steps:
+      # The plan body is UNTRUSTED. Pass it in via env: (never inline ${{ }}) and
+      # write it to a file with printf so it can never inject shell; export the path
+      # for the review step. The reviewer reads it as --context-file (untrusted data).
+      # @ref LLP 0009#workflow-security-posture [implements] — comment body only via env:, never inline ${{ }}
+      - name: Write plan to a file
+        env:
+          COMMENT: ${{ github.event.comment.body }}
+        run: |
+          printf '%s' "$COMMENT" > "$RUNNER_TEMP/atlantis-plan.txt"
+          echo "PLAN_FILE=$RUNNER_TEMP/atlantis-plan.txt" >> "$GITHUB_ENV"
+
+      # SECURITY: `issue_comment` is NOT fork-restricted — it runs in the base-repo
+      # context with full secrets regardless of whether the PR is a fork. Check out
+      # ONLY the trusted base ref (the default branch) for the `.expo-code-review/`
+      # config, and never `gh pr checkout` the PR head. The engine is the PUBLISHED
+      # package via npx, not built from any checkout, so PR code never runs here.
+      - name: Checkout (base ref only — never the PR head)
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          # The CLI's own git fetches authenticate through `gh` from GH_TOKEN, so the
+          # token never lands in .git/config.
+          persist-credentials: false
+
+      - name: Set up Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          # The reviewer runs via npx and never installs with a package manager, so
+          # disable setup-node's auto package-manager cache.
+          package-manager-cache: false
+
+      # SECURITY: the base-ref checkout includes every .expo-code-review/ config,
+      # whose auth.tokenEnv names the forwarded model credential. `ecr verify-config`
+      # sweeps every config and refuses unless tokenEnv appears exactly once, in a
+      # ROOT-owned file, equal to ECR_EXPECTED_TOKEN_ENV. This is layer 2; layer 1 is
+      # the runtime lock in `ecr ci`. Runs the SAME $ECR_VERSION `ecr ci` will.
+      # @ref LLP 0009#guard-step-ordering-and-job-budgets [implements] — same $ECR_VERSION feeds guard and review
+      - name: Guard config tokenEnv (root + routing + all scopes)
+        env:
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
+        run: npx --yes -p "@expo/code-review-cli@$ECR_VERSION" ecr verify-config
+
+      # Running via `issue_comment` makes this a manual /review, which the CLI detects
+      # (GITHUB_EVENT_NAME=issue_comment) and treats as a trigger-gate bypass, and it
+      # resolves the PR from issue.number. The bypass affects ONLY the trigger gate;
+      # the config guard above, break-glass, and the auth lock still apply.
+      - name: Run AI review
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Layer-1 auth lock: keep in sync with the guard's EXPECTED.
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
+          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          # Optional: override the model for every agent (uses your OpenCode login).
+          REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}
+        run: |
+          # Build the flags as a bash array so the path never word-splits.
+          ARGS=(--context-file "$PLAN_FILE")
+          npx --yes -p "@expo/code-review-cli@$ECR_VERSION" ecr ci "${ARGS[@]}"
+
+      # Same ephemeral per-run log as the other workflows; issue.number IS the PR
+      # number in issue_comment context.
+      - name: Upload review run log
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: review-run-log-pr${{ github.event.issue.number }}
+          path: .expo-code-review/.runs/reviews.jsonl
+          if-no-files-found: ignore
+          retention-days: 14

package/templates/command.yml

@@ -1,3 +1,4 @@
+# @ref LLP 0009#workflow-security-posture — issue_comment is not fork-restricted; runs with full secrets regardless of PR origin
 name: AI code review (command)
 
 # On-demand, ONE-SHOT reviewer triggered by a PR comment (maintainers only):
@@ -31,6 +32,7 @@ concurrency:
 jobs:
   command:
     # Only PR comments starting with /review, from a maintainer.
+    # @ref LLP 0009#workflow-security-posture [implements] — gate controls who triggers, not what code runs
     if: >-
       github.event.issue.pull_request != null &&
       startsWith(github.event.comment.body, '/review') &&
@@ -43,6 +45,7 @@ jobs:
     # A reviewer failure must never fail the PR's checks.
     continue-on-error: true
     steps:
+      # @ref LLP 0009#workflow-security-posture [implements] — comment body only via env:; agent ids sanitized before reaching argv
       - name: Parse command
         id: cmd
         env:
@@ -118,6 +121,7 @@ jobs:
       # JSON-escaped key, or stage an unreferenced scope config with its own auth.
       # This is layer 2; layer 1 is the runtime ECR_EXPECTED_TOKEN_ENV lock in `ecr ci`.
       # Runs after Set up Node so the guard runs the SAME $ECR_VERSION `ecr ci` will.
+      # @ref LLP 0009#guard-step-ordering-and-job-budgets [implements] — same $ECR_VERSION feeds guard and review
       - name: Guard config tokenEnv (root + routing + all scopes)
         if: steps.cmd.outputs.run == 'true'
         env:

package/templates/config.jsonc

@@ -1,3 +1,4 @@
+// @ref LLP 0009#config-and-prompt-templates — root config: agent roster by filename, phase-1 defaults, auth
 {
   // Default model for every agent. Override per-agent via frontmatter in the
   // agent's markdown, or at runtime with the REVIEWER_MODEL env var
@@ -10,6 +11,7 @@
   // reserved filenames. Per-agent overrides go in each file's YAML frontmatter,
   // e.g. `---\nmodel: openai/gpt-5.5-pro\n---`.
 
+  // @ref LLP 0009#config-and-prompt-templates [implements] — suggestions off by default, not a schema limit
   "policy": {
     // Phase 1: keep signal high by surfacing only critical/warning.
     "includeSuggestions": false
@@ -87,5 +89,52 @@
     "mode": "api-key",
     "provider": "openai",
     "tokenEnv": "OPENAI_API_KEY"
-  }
+  },
+
+  // Stack-aware requalification (ROOT-ONLY; off by default). When on, `ecr ci` walks
+  // the OPEN PRs stacked on top of this one and lets the coordinator mark an
+  // absence-style finding (a missing test/migration/doc) as addressed when a later
+  // stacked PR already adds it. Such findings are never dropped — they render in a
+  // collapsed "Addressed in stacked PRs" section, are counted in a visible audit line,
+  // and are only excluded from the blocking decision. Critical/secrets/security
+  // findings are never requalifiable. Loaded only from the trusted base commit, so a
+  // PR cannot enable, widen, or disable its own requalification.
+  // "stack": {
+  //   "enabled": false,          // turn the feature on
+  //   "maxDepth": 4,             // how many levels up the stack to walk
+  //   "maxPrs": 8,               // children per level to follow
+  //   "maxFilesPerPr": 100,      // per-child file-list cap
+  //   "requireSameAuthor": true, // only children by this PR's author (anti-poisoning)
+  //   "confirmWithPatch": false, // v2: confirm each requalification against the addressing PR's patch
+  //   "maxConfirmations": 10     // v2: max patch confirmations per run (overflow is stripped)
+  // }
+
+  // Author feedback (ROOT-ONLY: the comment lifecycle is global). A PR author's
+  // reply is matched to the finding it answers (a quoted title and/or an
+  // `id:<fp>` token) and recorded in the comment's embedded state. This is ON
+  // by default even if you never touch this block, and deliberately ASYMMETRIC:
+  // `mode: "annotate"` marks a matched finding "author replied" with a link back
+  // to the comment — purely informational, no effect on the pass/fail decision.
+  // `dismiss: "never"` keeps it that way: no reply, and no model judgment, can
+  // remove a finding from the blocking set until you opt in below. This is
+  // deliberate — a repo that never edits this file still gets the useful,
+  // read-only behavior, never a surprise auto-dismissal.
+  //   "mode": "off" | "annotate" | "adjudicate" — "adjudicate" additionally runs
+  //     a model that re-checks the reply against the SOURCE (distrust by
+  //     default, like the verifier) and records a verdict.
+  //   "dismiss": "never" | "maintainers" | "adjudicated" — who/what may actually
+  //     clear a finding: nothing, a maintainer's reply, or (with `adjudicate`) a
+  //     maintainer reply OR an author reply the adjudicator confirmed.
+  // Clearing always needs the reply to cite the finding's `id:<fp>` token in the
+  // replier's OWN words: an id (or a title) inside a `>` quote only annotates,
+  // because "Quote reply" copies text the PR author wrote.
+  // Critical findings and `protectedCategories` can never be dismissed by a
+  // reply, whatever you set here — that floor is enforced in code, not here.
+  // "feedback": {
+  //   "mode": "annotate",
+  //   "match": "both",                              // "quote" | "id" | "both"
+  //   "dismiss": "never",
+  //   "protectedCategories": ["secrets", "security"],
+  //   "maxAdjudications": 10                        // cap on model calls per run
+  // }
 }