@expo/code-review-cli 0.7.0 → 0.8.0

package/build/commands/init.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#init-and-dismiss — scaffolds .expo-code-review/; --scope validates before any file lands on disk
 import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -5,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { CONFIG_DIRNAME } from "../config/load.js";
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { RoutingScopeSchema } from "../config/schema.js";
+import { FORBIDDEN_TOKEN_ENVS } from "../core/auth.js";
 import { repoRoot } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
 const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
@@ -21,9 +23,18 @@ Options:
   --scope <dir>   Scaffold <dir>/.expo-code-review/ (no auth) + add a scope entry
   --no-workflow   Skip writing the CI workflows (review, command, and dismiss
                   under .github/workflows/)
+  --token-env <name[,name…]>
+                  Env var(s) holding the model credential (default OPENAI_API_KEY,
+                  e.g. CLAUDE_CODE_OAUTH_TOKEN). The scaffolded workflows forward
+                  the matching repo secret(s) and expect this tokenEnv
   --force         Overwrite existing files
+  --force-workflows
+                  Overwrite only the CI workflow files, keeping your customized
+                  config.jsonc, prompts, and agents/. Use this to re-run
+                  --token-env on an already-scaffolded repo.
   -h, --help      Show this help
 `;
+const DEFAULT_TOKEN_ENV = "OPENAI_API_KEY";
 export async function initCommand(argv) {
     if (argv.includes("-h") || argv.includes("--help")) {
         process.stdout.write(USAGE);
@@ -32,6 +43,9 @@ export async function initCommand(argv) {
     try {
         const scopeDir = parseValue(argv, "--scope");
         if (scopeDir != null) {
+            if (parseValue(argv, "--token-env") != null) {
+                throw new Error("--token-env applies to the root scaffold's workflows; drop it from `--scope`");
+            }
             await scaffoldScope(argv, scopeDir);
         }
         else {
@@ -46,13 +60,58 @@ export async function initCommand(argv) {
 /** Scaffold .expo-code-review/ (and optionally the CI workflow + routing manifest). */
 async function scaffold(argv) {
     const force = argv.includes("--force");
+    // Re-running --token-env on an adopted repo needs to rewrite the workflow YAML
+    // without clobbering the adopter's tuned prompts and auth config, so the
+    // workflow writes honor a narrower force that leaves everything else skipped.
+    const forceWorkflows = force || argv.includes("--force-workflows");
     // The CI workflow is scaffolded by default (most repos adopting this want it);
     // `--no-workflow` opts out. `--with-workflow` is still accepted as a no-op for
     // back-compat.
     const withWorkflow = !argv.includes("--no-workflow");
     const monorepo = argv.includes("--monorepo");
+    // Validate before any file is written so a bad flag can't leave a half scaffold.
+    const tokenEnvs = parseTokenEnvs(parseValue(argv, "--token-env"));
+    if (!withWorkflow && parseValue(argv, "--token-env") != null) {
+        throw new Error("--token-env customizes the CI workflows; drop it or remove --no-workflow");
+    }
     const root = (await repoRoot()) ?? process.cwd();
     const configDir = path.join(root, CONFIG_DIRNAME);
+    // A non-default --token-env only takes effect through the review workflows,
+    // but existing workflow files are skipped (not rewritten) without --force —
+    // the flag would silently never reach CI while the next steps claim the
+    // workflow references the new secret. Refuse before any file is written.
+    // @ref LLP 0007#init-and-dismiss [implements] — validated before any file is written; no half scaffold
+    if (withWorkflow && tokenEnvs.join(",") !== DEFAULT_TOKEN_ENV && !forceWorkflows) {
+        const existing = ["expo-code-review.yml", "expo-code-review-command.yml"]
+            .map((name) => path.join(".github", "workflows", name))
+            .filter((rel) => existsSync(path.join(root, rel)));
+        if (existing.length > 0) {
+            throw new Error(`--token-env cannot take effect: ${existing.join(" and ")} already ` +
+                `exist${existing.length > 1 ? "" : "s"} and would be skipped, so CI would keep ` +
+                `forwarding the default secret. Re-run with --force-workflows to rewrite just the ` +
+                `workflows (keeps your config.jsonc, prompts, and agents/), with --force to rewrite ` +
+                `everything, or edit their ECR_EXPECTED_TOKEN_ENV fallback and forwarded secret ` +
+                `lines by hand.`);
+        }
+    }
+    // The reverse of the guard above: --force-workflows (or --force) always rewrites
+    // the review workflows from the pristine template, which forwards the default
+    // OPENAI_API_KEY unless --token-env names the credential again. An adopter who
+    // scaffolded with a non-default tokenEnv and later refreshes the workflow YAML
+    // without re-passing --token-env would silently lose the forwarded secret, and
+    // CI would keep passing the auth lock but run with an empty credential. Refuse
+    // before any file is written; naming --token-env again (or the default, to reset
+    // on purpose) is the explicit opt-in.
+    if (withWorkflow && forceWorkflows && parseValue(argv, "--token-env") == null) {
+        const baked = await detectWorkflowTokenEnv(root);
+        if (baked != null && baked !== DEFAULT_TOKEN_ENV) {
+            throw new Error(`refusing to revert the CI credential wiring: the existing review workflows forward ` +
+                `${baked}, but this run has no --token-env, so rewriting them would restore the ` +
+                `default ${DEFAULT_TOKEN_ENV} and CI would run with an empty credential. Re-run with ` +
+                `--token-env ${baked} to keep the current credential, or --token-env ${DEFAULT_TOKEN_ENV} ` +
+                `to reset to OpenAI on purpose.`);
+        }
+    }
     // Create only the config dir; let copyInto create prompts/ so it reports
     // accurately as created vs skipped.
     await mkdir(configDir, { recursive: true });
@@ -78,25 +137,35 @@ async function scaffold(argv) {
         await mkdir(workflowDir, { recursive: true });
         // The auto (pull_request) workflow, plus the two issue_comment command
         // workflows: `/review` (on-demand one-shot) and `/dismiss` (hide a finding).
-        await copyInto(path.join(TEMPLATES_DIR, "workflow.yml"), path.join(workflowDir, "expo-code-review.yml"), force, created, skipped, root);
-        await copyInto(path.join(TEMPLATES_DIR, "command.yml"), path.join(workflowDir, "expo-code-review-command.yml"), force, created, skipped, root);
-        await copyInto(path.join(TEMPLATES_DIR, "dismiss.yml"), path.join(workflowDir, "expo-code-review-dismiss.yml"), force, created, skipped, root);
+        // The two review-running workflows get the tokenEnv substituted so the
+        // credential mapping stays STATIC in the committed YAML (the auth lock relies
+        // on that); dismiss.yml runs no model and needs no credential.
+        await copyTemplate(path.join(TEMPLATES_DIR, "workflow.yml"), path.join(workflowDir, "expo-code-review.yml"), forceWorkflows, created, skipped, root, (raw) => substituteTokenEnv(raw, tokenEnvs));
+        await copyTemplate(path.join(TEMPLATES_DIR, "command.yml"), path.join(workflowDir, "expo-code-review-command.yml"), forceWorkflows, created, skipped, root, (raw) => substituteTokenEnv(raw, tokenEnvs));
+        await copyInto(path.join(TEMPLATES_DIR, "dismiss.yml"), path.join(workflowDir, "expo-code-review-dismiss.yml"), forceWorkflows, created, skipped, root);
     }
     reportFiles(created, skipped);
-    process.stdout.write([
-        "",
-        "Next steps:",
-        `  1. Customize ${CONFIG_DIRNAME}/agents/*.md (and shared.md, coordinator.md) for this repo.`,
-        "  2. Configure a model provider in OpenCode (or set REVIEWER_MODEL).",
-        "  3. Run `ecr doctor`, then `ecr review`.",
+    const names = tokenEnvs.map((name) => `\`${name}\``).join(" + ");
+    const steps = [
+        `Customize ${CONFIG_DIRNAME}/agents/*.md (and shared.md, coordinator.md) for this repo.`,
+        // --token-env only rewires the workflows; the scaffolded config.jsonc still
+        // declares OPENAI_API_KEY, and CI's `ecr verify-config` refuses to review
+        // until the config's tokenEnv set matches the workflow's expected set.
+        ...(tokenEnvs.join(",") !== DEFAULT_TOKEN_ENV
+            ? [
+                `Point ${CONFIG_DIRNAME}/config.jsonc at ${tokenEnvs.length > 1 ? "these credentials" : "this credential"}: set \`auth\` (and \`model\`) per the file's comments — CI's \`ecr verify-config\` refuses to review until the config names ${names}.`,
+            ]
+            : []),
+        "Configure a model provider in OpenCode (or set REVIEWER_MODEL).",
+        "Run `ecr doctor`, then `ecr review`.",
         withWorkflow
-            ? "  4. Add the model-key secret referenced by the workflow, then add an `ai-review` label to a PR."
-            : "  4. (No CI workflow written — re-run without `--no-workflow` to add it.)",
+            ? `Add the ${names} repo secret${tokenEnvs.length > 1 ? "s" : ""} referenced by the workflow, then add an \`ai-review\` label to a PR.`
+            : "(No CI workflow written — re-run without `--no-workflow` to add it.)",
         monorepo
-            ? `  5. Add per-team scopes with \`ecr init --scope <dir>\` (see ${CONFIG_DIRNAME}/${ROUTING_FILENAME}).`
-            : `  5. Monorepo? Run \`ecr init --monorepo\` to add a routing manifest.`,
-        "",
-    ].join("\n"));
+            ? `Add per-team scopes with \`ecr init --scope <dir>\` (see ${CONFIG_DIRNAME}/${ROUTING_FILENAME}).`
+            : "Monorepo? Run `ecr init --monorepo` to add a routing manifest.",
+    ];
+    process.stdout.write(["", "Next steps:", ...steps.map((step, index) => `  ${index + 1}. ${step}`), ""].join("\n"));
 }
 /**
  * Scaffold a per-team scope under <dir>: <dir>/.expo-code-review/ with a no-auth
@@ -110,6 +179,7 @@ async function scaffoldScope(argv, scopeDirRaw) {
     if (!existsSync(routingPath)) {
         throw new Error(`no ${CONFIG_DIRNAME}/${ROUTING_FILENAME} — run \`ecr init --monorepo\` first`);
     }
+    // @ref LLP 0007#init-and-dismiss [implements] — traversal and unparsable-routing.jsonc prevented before any file lands
     // Derive the scope entry and validate it BEFORE creating any files: the name must
     // satisfy RoutingScopeSchema's kebab-case rule (derived by sanitizing the dir,
     // apps/Foo_Bar -> apps-foo-bar), and the config path is rejected when absolute or
@@ -172,6 +242,7 @@ async function scaffoldScope(argv, scopeDirRaw) {
         "",
     ].join("\n"));
 }
+// @ref LLP 0007#init-and-dismiss [implements] — comment-preserving text surgery; idempotent; comma placement rules
 /**
  * Insert a scope entry before the closing ] of the "scopes" array in raw JSONC,
  * preserving comments/formatting. Returns the new text, the original text unchanged
@@ -293,3 +364,148 @@ async function copyInto(src, dest, force, created, skipped, root) {
     await cp(src, dest, { recursive: true, force, errorOnExist: false });
     (existed && !force ? skipped : created).push(path.relative(root, dest));
 }
+/** Like copyInto for a single file, but pipes the content through `transform`. */
+async function copyTemplate(src, dest, force, created, skipped, root, transform) {
+    if (existsSync(dest) && !force) {
+        skipped.push(path.relative(root, dest));
+        return;
+    }
+    await writeFile(dest, transform(await readFile(src, "utf8")), "utf8");
+    created.push(path.relative(root, dest));
+}
+/**
+ * Parse + validate `--token-env`: a comma-separated list of env var names holding
+ * the model credential(s). Refuses names the runtime would refuse anyway
+ * (FORBIDDEN_TOKEN_ENVS) so a bad choice fails here, not at review time.
+ */
+// @ref LLP 0007#init-and-dismiss [implements] — validated before any file is written; no half scaffold
+export function parseTokenEnvs(value) {
+    if (value == null) {
+        return [DEFAULT_TOKEN_ENV];
+    }
+    const names = value.split(",").map((name) => name.trim());
+    if (names.some((name) => !/^[A-Z][A-Z0-9_]*$/.test(name))) {
+        throw new Error(`--token-env must be UPPER_SNAKE_CASE env var name(s), got "${value}"`);
+    }
+    for (const name of names) {
+        if (FORBIDDEN_TOKEN_ENVS.has(name)) {
+            throw new Error(`--token-env ${name} is a well-known unrelated secret; the reviewer refuses it`);
+        }
+    }
+    if (new Set(names).size !== names.length) {
+        throw new Error(`--token-env has duplicate names: "${value}"`);
+    }
+    return names;
+}
+// Secrets that a review workflow forwards for reasons other than the model
+// credential, so a non-default name here is not a baked credential to preserve.
+const NON_MODEL_FORWARDED_SECRETS = new Set(["GH_TOKEN", "GITHUB_TOKEN"]);
+/**
+ * Detect the non-default model credential an existing review workflow bakes in,
+ * so a --force-workflows run can refuse to silently revert it to the default
+ * instead of rewriting from the pristine (OpenAI) template. Reads two
+ * independent signals and returns whichever is non-default:
+ *   - the `ECR_EXPECTED_TOKEN_ENV` fallback (`vars.ECR_EXPECTED_TOKEN_ENV || '<name>'`),
+ *     the joined list init bakes for the auth lock; and
+ *   - the forwarded credential lines (`<NAME>: ${{ secrets.<NAME> }}`), which are
+ *     what actually exposes the secret to the job. A hand edit — or a repo-variable
+ *     lock (`vars.ECR_EXPECTED_TOKEN_ENV`) that leaves the YAML fallback at the
+ *     default — can change the forwarded line alone, so reading only the fallback
+ *     would miss the baked credential and revert it.
+ * Returns the credential value to re-pass via --token-env, or null when the
+ * workflows forward only the default (or none exist).
+ */
+async function detectWorkflowTokenEnv(root) {
+    for (const name of ["expo-code-review.yml", "expo-code-review-command.yml"]) {
+        const file = path.join(root, ".github", "workflows", name);
+        if (!existsSync(file)) {
+            continue;
+        }
+        const raw = await readFile(file, "utf8");
+        const fallback = raw.match(/vars\.ECR_EXPECTED_TOKEN_ENV \|\| '([^']*)'/);
+        if (fallback && fallback[1] !== DEFAULT_TOKEN_ENV) {
+            return fallback[1];
+        }
+        const forwarded = forwardedModelCredentials(raw);
+        if (forwarded.length > 0) {
+            return forwarded.join(",");
+        }
+    }
+    return null;
+}
+/**
+ * Slice the `Run AI review` step (its `env:` maps the model credential) out of a
+ * workflow file, so credential detection reads only the block the scaffold owns
+ * and not secrets a hand edit forwards to unrelated steps (a deploy step's AWS
+ * keys, an acknowledge step's GH_TOKEN, …). Steps sit at 6-space `- ` indent, so
+ * the step runs until the next such line or EOF. Returns "" when the step is
+ * absent (drifted or removed template).
+ */
+function runAiReviewStep(raw) {
+    const start = raw.indexOf("- name: Run AI review");
+    if (start === -1) {
+        return "";
+    }
+    const rest = raw.slice(start);
+    const nextStep = rest.search(/\n {6}- /);
+    return nextStep === -1 ? rest : rest.slice(0, nextStep);
+}
+/**
+ * Names of the non-default model credential a workflow's `Run AI review` step
+ * forwards, read from its `<NAME>: ${{ secrets.<...> }}` env lines. Skips the
+ * default, the known non-model secrets (GH_TOKEN), and any FORBIDDEN_TOKEN_ENVS
+ * name — the runtime refuses those as a model credential, so surfacing one as a
+ * baked credential would produce a remediation (`--token-env <name>`) that either
+ * cannot pass parseTokenEnvs or would wire an unrelated secret to the provider.
+ * Scanning is scoped to the credential block the scaffold owns so a secret a hand
+ * edit forwards to another step is never mistaken for the model credential.
+ */
+function forwardedModelCredentials(raw) {
+    const names = [];
+    const re = /^\s*([A-Z][A-Z0-9_]*):\s*\$\{\{\s*secrets\.[A-Z][A-Z0-9_]*\s*\}\}/gm;
+    for (const match of runAiReviewStep(raw).matchAll(re)) {
+        const name = match[1];
+        if (name === DEFAULT_TOKEN_ENV ||
+            NON_MODEL_FORWARDED_SECRETS.has(name) ||
+            FORBIDDEN_TOKEN_ENVS.has(name)) {
+            continue;
+        }
+        if (!names.includes(name)) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Rewrite a scaffolded review workflow for a non-default tokenEnv: the
+ * ECR_EXPECTED_TOKEN_ENV fallback and the forwarded credential secret(s). GitHub
+ * Actions never exposes a secret the YAML doesn't map explicitly, so without this
+ * a Claude/Codex setup would pass the auth lock but run with an empty credential.
+ * Throws when a template marker is missing (template drift must fail loudly, not
+ * scaffold a workflow that silently keeps the OpenAI-only wiring).
+ */
+// @ref LLP 0009#what-ecr-init-scaffolds [implements] — static credential mapping baked at init from a trusted flag, never resolved at run time
+export function substituteTokenEnv(raw, tokenEnvs) {
+    const joined = tokenEnvs.join(",");
+    if (joined === DEFAULT_TOKEN_ENV) {
+        return raw;
+    }
+    const expectedFallback = `vars.ECR_EXPECTED_TOKEN_ENV || '${DEFAULT_TOKEN_ENV}'`;
+    const credentialBlock = [
+        "          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.",
+        "          # Store it as a repo secret; a project-scoped key restricted to model",
+        "          # inference (with a spend limit) is all the reviewer needs.",
+        "          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}",
+    ].join("\n");
+    if (!raw.includes(expectedFallback) || !raw.includes(credentialBlock)) {
+        throw new Error("workflow template drifted: tokenEnv markers not found (report this bug)");
+    }
+    const replacement = [
+        `          # Model credential${tokenEnvs.length > 1 ? "s" : ""} — the env var${tokenEnvs.length > 1 ? "s" : ""} named by auth.tokenEnv in config.jsonc.`,
+        "          # Store each as a repo secret under the same name.",
+        ...tokenEnvs.map((name) => `          ${name}: \${{ secrets.${name} }}`),
+    ].join("\n");
+    return raw
+        .replaceAll(expectedFallback, `vars.ECR_EXPECTED_TOKEN_ENV || '${joined}'`)
+        .replace(credentialBlock, replacement);
+}

package/build/commands/review.js

@@ -1,11 +1,14 @@
+// @ref LLP 0007#ecr-review-local-trust-and-flag-rules — local runs: the person at the terminal is the trust principal, even with --pr
 import { loadReviewConfig, loadScopeConfig } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopedCommentTag } from "../config/routing.js";
 import { repoRoot, resolveRepo } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
+import { readContextFile } from "../core/context-file.js";
+import { feedbackNeedsRunSeam } from "../core/adjudicate.js";
 import { runReview } from "../core/review.js";
 import { LocalGitSource } from "../sources/local-git.js";
 import { GitHubPRSource } from "../sources/github-pr.js";
-import { memoizeSource } from "../sources/source.js";
+import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import { TerminalReporter } from "../reporters/terminal.js";
 import { GitHubReporter } from "../reporters/github.js";
 const USAGE = `ecr review — AI code review, printed to your terminal
@@ -34,6 +37,11 @@ Options:
                        runs its config over just that scope's changed files
   --config-dir <dir>   load config from <dir> instead of .expo-code-review/
                        (also ECR_CONFIG_DIR); can't combine with --scope
+  --context-file <p>   inject <p>'s UTF-8 text into reviewer prompts as an
+                       explicitly UNTRUSTED external-context block
+  --stack-aware        with --pr: walk the open PRs stacked on top and let the
+                       coordinator requalify absence-style findings a later PR
+                       already addresses (off by default; rejected without --pr)
   --json               emit machine-readable JSON on stdout
   --no-fail            always exit 0, even on request-changes
   -h, --help           show this help
@@ -57,6 +65,7 @@ function parseArgs(argv) {
         staged: false,
         post: false,
         route: false,
+        stackAware: false,
         json: false,
         noFail: false,
         help: false,
@@ -103,6 +112,12 @@ function parseArgs(argv) {
             case "--config-dir":
                 args.configDir = requireValue(arg, argv[++i]);
                 break;
+            case "--context-file":
+                args.contextFile = requireValue(arg, argv[++i]);
+                break;
+            case "--stack-aware":
+                args.stackAware = true;
+                break;
             case "--json":
                 args.json = true;
                 break;
@@ -147,6 +162,29 @@ export async function reviewCommand(argv) {
     if (root && root !== process.cwd()) {
         process.chdir(root);
     }
+    // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — --context-file is orthogonal enrichment; local read errors fail loud (exit 2)
+    // Read the context file ONCE, in the command layer (routed review calls runReview
+    // per scope; reading inside would re-read the file N times). Local runs FAIL LOUD
+    // on a read error: the user typed the path, so a typo or oversized file is a
+    // mistake to surface, not to silently skip (unlike `ecr ci`, which warns and
+    // continues to keep the never-fail-checks invariant).
+    let contextText;
+    if (args.contextFile) {
+        try {
+            contextText = await readContextFile(args.contextFile);
+        }
+        catch (error) {
+            process.stderr.write(`--context-file: ${errorMessage(error)}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        // Empty/whitespace-only file: warn (a typo'd or unwritten path) but do not fail
+        // — there is simply no context to add.
+        if (!contextText.trim()) {
+            process.stderr.write(`--context-file: ${args.contextFile} is empty; no context added.\n`);
+            contextText = undefined;
+        }
+    }
     try {
         const cwd = process.cwd();
         const makeSource = () => args.pr != null
@@ -176,46 +214,74 @@ export async function reviewCommand(argv) {
                     process.stdout.write(`No changed files in scope ${args.scope}.\n`);
                     return;
                 }
+                // Build the PR reporter up front when posting, so adjudicate mode can judge the
+                // replies against the source before the result is rendered (see the non-scope
+                // path). A scope always posts under the DERIVED marker `<rootTag>:<scope>` —
+                // from the ROOT config's tag exactly like `ecr ci` does (runRoutedCi prefers
+                // rootConfig.commentTag over manifest defaults when they diverge) — so a
+                // standalone scope post and CI's per-scope post/clear/reconcile paths always
+                // target the same marker, and the bare aggregate marker is never used here.
+                // (Per-scope commentTag overrides are rejected by the scope schema for exactly
+                // this reason.)
+                // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [constrained-by] — must match ci.ts's derivation; the scope schema ban on commentTag is what keeps them aligned
+                const { repo: postRepo, error: postRepoError } = await resolvePostRepo(args, cwd);
+                const reporter = postRepo != null && args.pr != null
+                    ? new GitHubReporter({
+                        prNumber: args.pr,
+                        repo: postRepo,
+                        commentTag: scopedCommentTag(rootConfig.commentTag, args.scope),
+                        breakGlassMarker: config.breakGlassMarker,
+                        cwd,
+                        // Root-only feedback config (loadScopeConfig inherits it from the root).
+                        feedback: config.feedback,
+                        headSha: await reviewedHeadSha(source),
+                    })
+                    : null;
                 const review = await runReview(source, {
                     config,
                     mode: "local",
                     agents: args.agents,
                     route: args.route,
                     includePaths: files,
+                    contextText,
+                    // Explicit --stack-aware only: local config is not a trusted base, so the
+                    // user typing the flag is the trust principal. Bounds come from the root
+                    // config; validateArgs already rejected --stack-aware without --pr, and the
+                    // pr guard here keeps that invariant local.
+                    stack: args.stackAware && args.pr != null ? stackWalkFromConfig(rootConfig.stack) : undefined,
+                    stackConfirm: args.stackAware && args.pr != null
+                        ? stackConfirmFromConfig(rootConfig.stack)
+                        : undefined,
+                    feedback: reporter && feedbackNeedsRunSeam(config.feedback)
+                        ? { config: config.feedback, match: (r) => reporter.matchAdjudicationItems(r) }
+                        : undefined,
                     onProgress: (message) => process.stderr.write(`${message}\n`),
                 });
                 await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
-                if (args.post && args.pr != null) {
-                    const repo = args.repo ?? (await resolveRepo(cwd));
-                    // A scope always posts under the DERIVED marker `<rootTag>:<scope>` —
-                    // from the ROOT config's tag exactly like `ecr ci` does (runRoutedCi
-                    // prefers rootConfig.commentTag over manifest defaults when they
-                    // diverge) — so a standalone scope post and CI's per-scope post/clear/
-                    // reconcile paths always target the same marker, and the bare aggregate
-                    // marker is never used here. (Per-scope commentTag overrides are
-                    // rejected by the scope schema for exactly this reason.)
-                    const tag = scopedCommentTag(rootConfig.commentTag, args.scope);
-                    const reporter = new GitHubReporter({
-                        prNumber: args.pr,
-                        repo,
-                        commentTag: tag,
-                        breakGlassMarker: config.breakGlassMarker,
-                        cwd,
-                    });
-                    // Respect the author's break-glass opt-out, same as the non-scope path.
-                    let breakGlass = false;
-                    try {
-                        breakGlass = await reporter.checkBreakGlass();
-                    }
-                    catch {
-                        breakGlass = false;
-                    }
-                    if (breakGlass) {
-                        process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${repo}#${args.pr} (break-glass).\n`);
+                if (args.pr != null && args.post) {
+                    if (reporter) {
+                        // Respect the author's break-glass opt-out, same as the non-scope path.
+                        let breakGlass = false;
+                        try {
+                            breakGlass = await reporter.checkBreakGlass();
+                        }
+                        catch {
+                            breakGlass = false;
+                        }
+                        if (breakGlass) {
+                            process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${postRepo}#${args.pr} (break-glass).\n`);
+                        }
+                        else {
+                            await reporter.report(review, review.feedback);
+                            process.stderr.write(`\nPosted scope "${args.scope}" review to ${postRepo}#${args.pr}.\n`);
+                        }
                     }
                     else {
-                        await reporter.report(review);
-                        process.stderr.write(`\nPosted scope "${args.scope}" review to ${repo}#${args.pr}.\n`);
+                        // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — a
+                        // `gh` failure resolving the repo must not hide the review already
+                        // printed above; only the post step fails here, with a clear message.
+                        process.stderr.write(`\nNot posted: could not resolve the repo for --post (${errorMessage(postRepoError)}). Pass --repo owner/repo.\n`);
+                        process.exitCode = 2;
                     }
                 }
             }
@@ -226,39 +292,65 @@ export async function reviewCommand(argv) {
         }
         const config = await loadReviewConfig(cwd, { configDir: args.configDir });
         const source = makeSource();
+        // Build the PR reporter up front when posting, so adjudicate mode can judge the
+        // PR's replies against the source before the result is rendered. Feedback only
+        // has replies to match when reviewing a PR and posting (the terminal preview never
+        // renders annotations), so it is wired only on the --post --pr path.
+        const { repo: postRepo, error: postRepoError } = await resolvePostRepo(args, cwd);
+        const reporter = postRepo != null && args.pr != null
+            ? new GitHubReporter({
+                prNumber: args.pr,
+                repo: postRepo,
+                commentTag: config.commentTag,
+                breakGlassMarker: config.breakGlassMarker,
+                cwd,
+                feedback: config.feedback,
+                headSha: await reviewedHeadSha(source),
+            })
+            : null;
         const review = await runReview(source, {
             config,
             mode: "local",
             agents: args.agents,
             route: args.route,
+            contextText,
+            // Explicit --stack-aware only (see the scope branch); validateArgs already
+            // rejected --stack-aware without --pr.
+            stack: args.stackAware && args.pr != null ? stackWalkFromConfig(config.stack) : undefined,
+            stackConfirm: args.stackAware && args.pr != null ? stackConfirmFromConfig(config.stack) : undefined,
+            feedback: reporter && feedbackNeedsRunSeam(config.feedback)
+                ? { config: config.feedback, match: (r) => reporter.matchAdjudicationItems(r) }
+                : undefined,
             onProgress: (message) => process.stderr.write(`${message}\n`),
         });
         // Always print the result here first.
         await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
         // Then, only if asked, publish the same result to the PR.
-        if (args.post && args.pr != null) {
-            const repo = args.repo ?? (await resolveRepo(cwd));
-            const reporter = new GitHubReporter({
-                prNumber: args.pr,
-                repo,
-                commentTag: config.commentTag,
-                breakGlassMarker: config.breakGlassMarker,
-                cwd,
-            });
-            // Respect the author's break-glass opt-out, same as the CI path.
-            let breakGlass = false;
-            try {
-                breakGlass = await reporter.checkBreakGlass();
-            }
-            catch {
-                breakGlass = false;
-            }
-            if (breakGlass) {
-                process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${repo}#${args.pr} (break-glass).\n`);
+        if (args.pr != null && args.post) {
+            if (reporter) {
+                // Respect the author's break-glass opt-out, same as the CI path.
+                let breakGlass = false;
+                try {
+                    breakGlass = await reporter.checkBreakGlass();
+                }
+                catch {
+                    breakGlass = false;
+                }
+                if (breakGlass) {
+                    process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${postRepo}#${args.pr} (break-glass).\n`);
+                }
+                else {
+                    await reporter.report(review, review.feedback);
+                    process.stderr.write(`\nPosted review to ${postRepo}#${args.pr}.\n`);
+                }
             }
             else {
-                await reporter.report(review);
-                process.stderr.write(`\nPosted review to ${repo}#${args.pr}.\n`);
+                // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — a `gh`
+                // failure resolving the repo (no auth, no network, no GitHub remote, rate
+                // limit) must not hide the review already printed above; only the post
+                // step fails here, with a clear message.
+                process.stderr.write(`\nNot posted: could not resolve the repo for --post (${errorMessage(postRepoError)}). Pass --repo owner/repo.\n`);
+                process.exitCode = 2;
             }
         }
     }
@@ -267,6 +359,49 @@ export async function reviewCommand(argv) {
         process.exitCode = 2;
     }
 }
+/**
+ * The head commit the review reads, when the source can pin one (a GitHub PR). The
+ * reporter binds every adjudication verdict to it, so a stored verdict carries to a
+ * later run only while the reviewed source is unchanged (see mergeFeedback). Never
+ * throws: an unresolvable head reads as unknown source, which re-judges the reply
+ * instead of trusting a verdict about code we cannot pin.
+ */
+async function reviewedHeadSha(source) {
+    try {
+        return (await source.getMetadata()).headOid;
+    }
+    catch {
+        return undefined;
+    }
+}
+// @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — local runs
+// still print the review even when --post's repo can't be resolved
+/**
+ * Resolve the repo needed for --post --pr, without ever throwing: a `gh` failure
+ * (no auth, no network, no GitHub remote, rate limit) must degrade to "skip the
+ * post step", not abort the review itself — the local run already trusts the
+ * caller and should still show them the review. Callers treat a returned `error`
+ * as "no repo, and here's why" once they reach the post step; the review and its
+ * optional feedback seam simply run without a reporter until then.
+ *
+ * `resolve` is injectable (defaults to the real `resolveRepo`) purely so tests can
+ * exercise the failure path deterministically, without a `gh` binary or network.
+ */
+export async function resolvePostRepo(args, cwd, resolve = resolveRepo) {
+    if (!(args.post && args.pr != null)) {
+        return {};
+    }
+    if (args.repo) {
+        return { repo: args.repo };
+    }
+    try {
+        return { repo: await resolve(cwd) };
+    }
+    catch (error) {
+        return { error };
+    }
+}
+// @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — mutually exclusive flags rejected outright, never silently ignored
 /** Reject flag combinations that don't make sense together. */
 function validateArgs(args) {
     if (args.pr != null && (args.base || args.head || args.staged)) {
@@ -275,6 +410,11 @@ function validateArgs(args) {
     if (args.pr == null && (args.repo || args.post)) {
         throw new Error("--repo/--post only apply together with --pr.");
     }
+    // Same rule as --repo/--post: the stack walk needs a PR to walk from, so a bare
+    // --stack-aware would be silently ignored — reject it instead.
+    if (args.pr == null && args.stackAware) {
+        throw new Error("--stack-aware only applies together with --pr.");
+    }
     // --staged diffs the index against HEAD, so --base/--head have no effect. Reject
     // the combination rather than silently ignoring the range the user asked for.
     if (args.staged && (args.base || args.head)) {