@expo/code-review-cli 0.6.0 → 0.8.0

package/build/commands/setup-auth.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#doctor-and-setup-auth — derives a plan from auth config, then guides local credential acquisition
 import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import os from "node:os";
@@ -5,7 +6,8 @@ import path from "node:path";
 import readline from "node:readline/promises";
 import { hasConfig, loadReviewConfig } from "../config/load.js";
 import { jwtExpiryMs } from "../core/auth.js";
-import { opencodeBinSource } from "../core/opencode.js";
+import { claudeSubscriptionActive, resolveClaudeCli } from "../core/claude-code.js";
+import { resolveOpencodeCli } from "../core/opencode.js";
 import { errorMessage } from "../core/util.js";
 const USAGE = `ecr setup-auth — set up model credentials for local runs
 
@@ -15,6 +17,10 @@ getting each credential:
     \`opencode auth login\` (interactive; opens your browser), then prints the
     \`export <tokenEnv>=…\` line to add to your shell config. An existing
     OpenCode ChatGPT sign-in is reused instead of re-authenticating.
+  • a Claude Max/Team subscription (any anthropic/… model): reuses an active
+    \`claude\` login when present, or runs \`claude setup-token\` (interactive;
+    opens your browser) and prints the \`export <tokenEnv>=…\` line for
+    CI/headless runs.
   • an API key (api-key entries): prints where to create the key, the exact
     permissions it needs, and the export line to fill in.
 
@@ -24,10 +30,21 @@ with the default env name.
 Options:
   --yes   Skip confirmation prompts (still interactive during the login itself).
 `;
-export function planFromAuth(auth) {
+export function planFromAuth(auth, models = []) {
     const plan = { manualKeys: [], unsupported: [] };
+    // anthropic is always served by the Claude Code CLI — a `claude setup-token`
+    // subscription login covers it. Trigger on either an explicit anthropic auth
+    // entry OR any anthropic/… model in the roster (an entry is entirely optional).
+    const anthropicEntry = auth.find((entry) => entry.provider === "anthropic");
+    const usesAnthropicModel = models.some((model) => model === "anthropic" || model.startsWith("anthropic/"));
+    if (anthropicEntry || usesAnthropicModel) {
+        plan.claudeLogin = { tokenEnv: anthropicEntry?.tokenEnv ?? "CLAUDE_CODE_OAUTH_TOKEN" };
+    }
     for (const entry of auth) {
-        if (entry.mode === "oauth" && entry.provider === "openai" && entry.tokenEnv) {
+        if (entry.provider === "anthropic") {
+            continue; // handled above (claude engine); mode is irrelevant here.
+        }
+        else if (entry.mode === "oauth" && entry.provider === "openai" && entry.tokenEnv) {
             plan.chatgptLogin = { tokenEnv: entry.tokenEnv };
         }
         else if (entry.mode === "api-key" && entry.tokenEnv) {
@@ -49,6 +66,7 @@ export function opencodeAuthJsonPath(env = process.env) {
     const dataHome = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
     return path.join(dataHome, "opencode", "auth.json");
 }
+// @ref LLP 0007#doctor-and-setup-auth [constrained-by] — refresh tokens are single-use; they never leave OpenCode's store
 /**
  * The stored ChatGPT sign-in's ACCESS token, if OpenCode has a live one. The
  * refresh token deliberately never leaves OpenCode's store: refresh tokens are
@@ -86,6 +104,7 @@ async function confirm(question, skip) {
         rl.close();
     }
 }
+// @ref LLP 0007#doctor-and-setup-auth [constrained-by] — shell metacharacters in tokens never expand
 /** The line to paste into a shell config. Single-quoted: tokens never contain '. */
 export function exportLine(tokenEnv, value) {
     return `export ${tokenEnv}='${value}'`;
@@ -104,7 +123,10 @@ export async function setupAuthCommand(argv = []) {
         let plan;
         if (hasConfig(process.cwd())) {
             const config = await loadReviewConfig(process.cwd());
-            plan = planFromAuth(config.auth);
+            plan = planFromAuth(config.auth, [
+                ...config.agents.map((agent) => agent.model),
+                config.coordinator.model,
+            ]);
         }
         else {
             err("No .expo-code-review config here — setting up the default ChatGPT/Codex flow.");
@@ -112,11 +134,55 @@ export async function setupAuthCommand(argv = []) {
                 { provider: "openai", mode: "oauth", tokenEnv: "CODEX_OAUTH_ACCESS_TOKEN" },
             ]);
         }
-        if (!plan.chatgptLogin && plan.manualKeys.length === 0 && plan.unsupported.length === 0) {
+        if (!plan.chatgptLogin &&
+            !plan.claudeLogin &&
+            plan.manualKeys.length === 0 &&
+            plan.unsupported.length === 0) {
             out("This repo's auth config needs no local credential setup (OpenCode's own login covers it).");
             return;
         }
         const exports = [];
+        if (plan.claudeLogin) {
+            const { tokenEnv } = plan.claudeLogin;
+            if (process.env[tokenEnv]) {
+                err(`✓ ${tokenEnv} is already set in this shell — skipping the Claude subscription login.`);
+            }
+            else {
+                // Resolve to a trusted absolute path (refusing an in-tree binary), never a
+                // bare `claude`: setup-auth may run inside a cloned untrusted repo, so a
+                // PR-committed shim must not be the `claude` we probe or hand the terminal to.
+                const claudeCliPath = await resolveClaudeCli();
+                // A live local `claude` login already covers interactive runs — only CI or
+                // a headless box needs the token in an env var.
+                const loggedIn = await claudeSubscriptionActive({ cliPath: claudeCliPath ?? undefined });
+                if (loggedIn) {
+                    err("✓ A Claude Max/Team subscription login is active locally — `ecr review` works now. " +
+                        `You only need ${tokenEnv} for CI/headless runs.`);
+                }
+                err("`claude setup-token` mints a 1-year subscription token (opens your browser).");
+                if (!(await confirm("Run it now?", yes))) {
+                    err("Skipped `claude setup-token`.");
+                }
+                else if (!claudeCliPath) {
+                    throw new Error("The `claude` CLI is not installed on this host (npm i -g " +
+                        "@anthropic-ai/claude-code); nothing was changed.");
+                }
+                else {
+                    const result = spawnSync(claudeCliPath, ["setup-token"], {
+                        stdio: "inherit",
+                        cwd: os.tmpdir(),
+                    });
+                    if (result.status !== 0) {
+                        throw new Error(`\`claude setup-token\` exited with ${result.status ?? "a signal"}; nothing was changed.`);
+                    }
+                    // setup-token prints the token to the terminal and persists it nowhere we
+                    // can read back, so the user pastes it into the export line themselves.
+                    err(`Copy the token \`claude setup-token\` just printed and paste it in place of the ` +
+                        `placeholder below.`);
+                    exports.push(exportLine(tokenEnv, "<paste the token setup-token printed>"));
+                }
+            }
+        }
         if (plan.chatgptLogin) {
             const { tokenEnv } = plan.chatgptLogin;
             if (process.env[tokenEnv]) {
@@ -141,9 +207,20 @@ export async function setupAuthCommand(argv = []) {
                         err("Skipped the ChatGPT sign-in.");
                     }
                     else {
-                        const binDir = opencodeBinSource().dir;
-                        const opencode = binDir ? path.join(binDir, "opencode") : "opencode";
-                        const result = spawnSync(opencode, ["auth", "login"], { stdio: "inherit" });
+                        // Resolve to a trusted absolute path (our bundled shim, else PATH with an
+                        // in-tree refusal), never a bare `opencode`: setup-auth may run inside a
+                        // cloned untrusted repo, so a PR-committed shim must not be the CLI we hand
+                        // the terminal to. Run from tmpdir(), never the (possibly untrusted) cwd —
+                        // the login writes to OpenCode's global auth store, not the working dir.
+                        const opencodeCli = await resolveOpencodeCli();
+                        if (!opencodeCli) {
+                            throw new Error("The `opencode` CLI is not available (install `opencode-ai`, or add " +
+                                "node_modules/.bin to PATH); nothing was changed.");
+                        }
+                        const result = spawnSync(opencodeCli, ["auth", "login"], {
+                            stdio: "inherit",
+                            cwd: os.tmpdir(),
+                        });
                         if (result.status !== 0) {
                             throw new Error(`\`opencode auth login\` exited with ${result.status ?? "a signal"}; nothing was changed.`);
                         }
@@ -190,9 +267,7 @@ export async function setupAuthCommand(argv = []) {
         for (const entry of plan.unsupported) {
             err("");
             err(`auth for "${entry.provider}" is mode "oauth", which has no automated setup flow here` +
-                (entry.provider === "anthropic"
-                    ? " — and cannot work: Anthropic prohibits subscription tokens in third-party tools. Use an API key instead."
-                    : `. Set ${entry.tokenEnv ?? "its token env"} manually.`));
+                `. Set ${entry.tokenEnv ?? "its token env"} manually.`);
         }
         if (exports.length > 0) {
             const rc = process.env.SHELL?.includes("zsh") ? "~/.zshrc" : "your shell config";

package/build/commands/verify-config.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#verify-config-the-config-guard — the CI trust guard that runs before the loaders are trusted, so it deliberately does not use them
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../config/load.js";
@@ -28,6 +29,7 @@ Options:
   --json                  Emit {ok, findings:[{file, problem}]} on stdout.
 `;
 const CONFIG_FILENAMES = new Set(["config.jsonc", "config.json", ROUTING_FILENAME]);
+// @ref LLP 0007#verify-config-the-config-guard [implements] — on-disk sweep, not git index, not the manifest; CONFIG_FILENAMES must mirror load.ts
 /**
  * Discover every config the CLI could ever read via a plain recursive walk (not
  * `git ls-files`): a PR can't hide an unreferenced/untracked config dir from an
@@ -183,6 +185,7 @@ export async function verifyConfig(root, options = {}) {
         }
         seen.add(occurrence.value);
     }
+    // @ref LLP 0007#verify-config-the-config-guard [implements] — exact set equality; adding a credential is refused like repointing one
     // With an expectation set, the declared names must equal the expected SET
     // exactly (comma-separated; order-insensitive). A missing name is as much a
     // finding as an extra one — a PR must not add, drop, or repoint credentials.

package/build/config/load.js

@@ -1,9 +1,31 @@
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch — shared root/scope loader; ECR_CONFIG_DIR escape hatch
+// @ref LLP 0006#model-resolution — REVIEWER_MODEL env override resolution
+// @ref LLP 0006#auth-config-shapes — auth normalization (normalizeAuth, tokenEnvMismatch, loadAuthFromRoot)
+// @ref LLP 0006#root-vs-scope-config — scope config loading, commentTag derivation, enforceAgents injection
 import { readdir, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { ReviewConfigSchema, ScopeReviewConfigSchema } from "./schema.js";
 import { toolMap } from "../core/tools.js";
 export const CONFIG_DIRNAME = ".expo-code-review";
+/** Stack config for a scope load (where `stack` is schema-rejected and absent). */
+const STACK_CONFIG_DEFAULTS = {
+    enabled: false,
+    maxDepth: 4,
+    maxPrs: 8,
+    maxFilesPerPr: 100,
+    requireSameAuthor: true,
+    confirmWithPatch: false,
+    maxConfirmations: 10,
+};
+/** Feedback config for a scope load (where `feedback` is schema-rejected and absent). */
+const FEEDBACK_CONFIG_DEFAULTS = {
+    mode: "annotate",
+    match: "both",
+    dismiss: "never",
+    protectedCategories: ["secrets", "security"],
+    maxAdjudications: 10,
+};
 /** Default OpenCode tool toggles for a reviewer: read the repo, never mutate it. */
 const DEFAULT_AGENT_TOOLS = toolMap(["read", "grep", "glob", "list"]);
 export function configDirFor(repoRoot) {
@@ -61,6 +83,7 @@ async function loadConfigDir(dir, schema) {
     // agent and the coordinator then ran on whatever OpenCode picked by default, so a
     // config saying `anthropic/claude-sonnet-5` reviewed with something else entirely and
     // nothing anywhere said so. Trim too: a stray newline is the same class of accident.
+    // @ref LLP 0006#model-resolution [constrained-by] — never ??; GitHub Actions passes an unset var as empty string, not undefined
     const override = process.env.REVIEWER_MODEL?.trim() || undefined;
     const defaultModel = override ?? parsed.model;
     const resolveModel = (frontmatterModel) => override ?? frontmatterModel ?? defaultModel;
@@ -121,6 +144,14 @@ async function loadConfigDir(dir, schema) {
         commentTag: parsed.commentTag ?? "expo-ai-code-reviewer",
         auth: normalizeAuth(parsed.auth),
         review: parsed.review,
+        // Root-only: the scope schema rejects `stack`, so parsed.stack is absent for a
+        // scope config and the defaults stand in (unused — the command layer reads the
+        // ROOT config's stack values to drive the walk).
+        stack: parsed.stack ?? STACK_CONFIG_DEFAULTS,
+        // Root-only: the scope schema rejects `feedback`, so parsed.feedback is absent
+        // for a scope config and the defaults stand in (unused — the command layer
+        // reads the ROOT config's feedback values; the comment lifecycle is global).
+        feedback: parsed.feedback ?? FEEDBACK_CONFIG_DEFAULTS,
     };
     return { config, raw: rawObject };
 }
@@ -185,6 +216,7 @@ export function loadAuthFromRoot(rootConfig, manifest) {
  * with the root config; the scope config activates after merge) instead of
  * failing the run on exactly the PR that introduces the scope.
  */
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch [implements] — deliberately bypasses ECR_CONFIG_DIR; scope subtrees stay repo-root-relative
 export function hasScopeConfig(root, scope) {
     if (scope.config === ".") {
         return true;
@@ -224,6 +256,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         // loaded value here is only the manifest default, for display/doctor.
         commentTag = manifest.defaults.commentTag;
     }
+    // @ref LLP 0006#root-vs-scope-config [implements] — ROOT enforced agent always wins a same-id scope agent (risk 11)
     // Inject the enforced agents from the ROOT roster with alwaysRun, replacing any
     // same-id agent the scope defines (the enforced one wins — risk 11).
     const agents = base.agents.map((agent) => ({ ...agent }));
@@ -247,6 +280,12 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         auth: loadAuthFromRoot(rootConfig, manifest),
         breakGlassMarker: rootConfig.breakGlassMarker,
         commentTag,
+        // Root-only, like stack: a non-default scope's `base` carries only the
+        // hardcoded placeholder (the scope schema rejects `feedback`), so re-derive
+        // from the root here or consumers of a nested scope's config would silently
+        // run the default policy instead of the repo's real one.
+        stack: rootConfig.stack,
+        feedback: rootConfig.feedback,
         scopeName: scope.name,
     };
 }

package/build/config/routing.js

@@ -1,3 +1,6 @@
+// @ref LLP 0006#routing-manifest — routing.jsonc parsing, scope resolution (last-match-wins), overlaps/unmatched
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch — routing.jsonc travels with config.jsonc via resolveConfigDir
+// @ref LLP 0006#budgets-and-chunking-defaults — per-scope budget split (scopePassesBudgetMs)
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -15,6 +18,7 @@ export const ROUTING_FILENAME = "routing.jsonc";
  * Scope `config` paths stay repo-root-relative (see `loadScopeConfig`): an
  * override relocates only the ROOT artifacts, never the scopes' own subtrees.
  */
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch [implements] — travels with config.jsonc; a real bug once let them split
 export async function loadRoutingManifest(root, options = {}) {
     const manifestPath = path.join(resolveConfigDir(root, options.configDir), ROUTING_FILENAME);
     if (!existsSync(manifestPath)) {
@@ -30,6 +34,7 @@ export async function loadRoutingManifest(root, options = {}) {
 // silently miss root-level files (README.md, package.json). To give the double-star +
 // slash its conventional "zero or more directories" meaning, we also test the variant
 // with each such prefix removed, so the catch-all matches both `a.ts` and `src/b.ts`.
+// @ref LLP 0006#routing-manifest [constrained-by] — workaround for matchesIgnore's **-needs-a-slash limitation (LLP 0004 dialect)
 function patternVariants(pattern) {
     const collapsed = pattern.replace(/\*\*\//g, "");
     return collapsed !== pattern && collapsed.length > 0 ? [pattern, collapsed] : [pattern];
@@ -44,6 +49,7 @@ function scopeMatches(paths, file) {
  * matchesIgnore (supports ** across / and * within a segment — the manifest
  * documents this dialect). Deterministic, no filesystem access.
  */
+// @ref LLP 0006#routing-manifest [implements] — last-match-wins (CODEOWNERS discipline); each file lands in exactly one scope
 export function resolveScopes(manifest, changedFiles) {
     const buckets = new Map();
     const unmatched = [];
@@ -86,6 +92,7 @@ export function scopedCommentTag(rootTag, scopeName) {
  * starting — and `overshoot` flags that the run will exceed the total budget so
  * the caller can warn. Pure so the math is unit-testable.
  */
+// @ref LLP 0006#budgets-and-chunking-defaults [implements] — floor(total/active) clamped to a 5-min floor; overshoot flags the clamp
 export function scopePassesBudgetMs(totalMs, minMs, activeCount) {
     const count = Math.max(1, activeCount);
     const evenSplit = Math.floor(totalMs / count);

package/build/config/schema.js

@@ -1,5 +1,10 @@
+// @ref LLP 0006#root-vs-scope-config — schema for root vs. scope-overridable config keys
+// @ref LLP 0006#auth-config-shapes — auth union schema (legacy single credential + per-provider map)
+// @ref LLP 0006#routing-manifest — routing.jsonc manifest schema (scopes, budgets, traversal guard)
+// @ref LLP 0006#budgets-and-chunking-defaults — chunk/budget default values and re-tuning heuristics
 import path from "node:path";
 import { z } from "zod";
+import { CATEGORIES } from "../core/schema.js";
 export const ReviewConfigSchema = z.object({
     /** Default model for every agent + the coordinator. Override per-agent via
      * frontmatter in the agent's markdown, or globally via REVIEWER_MODEL. */
@@ -68,6 +73,7 @@ export const ReviewConfigSchema = z.object({
     // Union order matters: the map form must be tried FIRST — the legacy object's keys
     // all have defaults, so a non-strict legacy parse would accept (and gut) a
     // { providers } object by stripping the unknown key.
+    // @ref LLP 0006#auth-config-shapes [constrained-by] — map-first order is load-bearing; reordering silently guts multi-provider auth
     auth: z
         .union([
         z.object({
@@ -76,9 +82,13 @@ export const ReviewConfigSchema = z.object({
                 // "oauth": tokenEnv holds an OAuth token, injected into an isolated
                 // OpenCode auth.json. For "openai" this is the REFRESH token from a
                 // ChatGPT/Codex sign-in (OpenCode's codex plugin mints access tokens
-                // from it). NOTE: anthropic oauth cannot work — OpenCode has no
-                // anthropic OAuth plugin and Anthropic prohibits subscription tokens
-                // in third-party tools.
+                // from it).
+                // NOTE: provider "anthropic" is ALWAYS served by the Claude Code CLI
+                // (the engine is inferred from the `anthropic/…` model, not this mode) —
+                // for anthropic, mode is irrelevant; tokenEnv optionally names the
+                // credential env (an "sk-ant-oat…" subscription token or an Anthropic
+                // API key), and no entry at all falls back to the machine's `claude`
+                // login. See core/claude-code.ts.
                 mode: z.enum(["api-key", "oauth"]).default("api-key"),
                 tokenEnv: z.string().optional(),
                 // Set ⇒ this provider id is an ALIAS synthesized into the OpenCode
@@ -111,6 +121,77 @@ export const ReviewConfigSchema = z.object({
         skipLabel: z.string().default("ai-review:skip"),
     })
         .default({ trigger: "all", label: "ai-review", skipLabel: "ai-review:skip" }),
+    // Stack-aware requalification: walk the OPEN PRs stacked on top of this one and
+    // let the coordinator mark absence-style findings a later PR already addresses.
+    // ROOT-ONLY (one PR has one stack) and off by default — a suppression-adjacent
+    // feature earns trust with field data first. Under `ecr ci` it auto-enables from
+    // this trusted-base value; `ecr review --pr` needs an explicit --stack-aware.
+    // @ref LLP 0010#config-and-cli-surface [implements] — root-only + off-by-default; head config can never enable, widen, or disable it
+    stack: z
+        .object({
+        enabled: z.boolean().default(false),
+        maxDepth: z.number().int().positive().default(4),
+        // Children per level (per parent branch) the walk will follow.
+        maxPrs: z.number().int().positive().default(8),
+        maxFilesPerPr: z.number().int().positive().default(100),
+        // Only children whose author is the current PR's author enter the manifest —
+        // closes cross-author poisoning (a push-access colleague opening a child PR on
+        // the victim's branch). Set false from the trusted base for genuine team stacks.
+        requireSameAuthor: z.boolean().default(true),
+        // v2: confirm each requalification against the addressing PR's actual patch
+        // before believing it (a no-tools LLM reads the inlined patch). Default false so
+        // v2 ships dark until flipped; maxConfirmations bounds that cost.
+        confirmWithPatch: z.boolean().default(false),
+        maxConfirmations: z.number().int().positive().default(10),
+    })
+        .default({
+        enabled: false,
+        maxDepth: 4,
+        maxPrs: 8,
+        maxFilesPerPr: 100,
+        requireSameAuthor: true,
+        confirmWithPatch: false,
+        maxConfirmations: 10,
+    }),
+    // Author replies to findings: match them to the finding they answer, record
+    // them in the comment's embedded state, and (optionally) let a model judge the
+    // rebuttal against the source. ROOT-ONLY: the comment lifecycle is global.
+    // Defaults are deliberately ASYMMETRIC: `annotate` is on but `dismiss` is off.
+    // An adopting repo has its own config.jsonc and never re-copies this template,
+    // so a key it never set must still resolve to the safe, useful default via
+    // zod — annotating is safe and useful out of the box; suppressing a finding is
+    // not, so it stays opt-in.
+    // @ref LLP 0011#asymmetric-defaults [implements] — annotate on, dismiss off; adopting repos never re-copy the template
+    feedback: z
+        .object({
+        // "off"        — ignore replies entirely.
+        // "annotate"   — match + record + show "author replied" (no decision effect).
+        // "adjudicate" — also run a source-grounded judgment of the rebuttal and
+        //                record its verdict. Dismissal still obeys `dismiss`.
+        mode: z.enum(["off", "annotate", "adjudicate"]).default("annotate"),
+        // How a reply is MATCHED to a finding. Clearing one additionally requires the
+        // reply to cite its `id:` token in the replier's own words, whatever this says.
+        match: z.enum(["quote", "id", "both"]).default("both"),
+        // Who/what may actually remove a finding from the blocking set (always on a
+        // reply citing the finding's `id:` token — a quote only annotates):
+        //   "never"       — nothing does (default: adjudication ships dark).
+        //   "maintainers" — a maintainer reply dismisses, no model involved.
+        //   "adjudicated" — a maintainer reply, or an author reply the adjudicator
+        //                   confirmed against the source.
+        dismiss: z.enum(["never", "maintainers", "adjudicated"]).default("never"),
+        // Categories a reply can NEVER clear, whatever the verdict. Also hard-coded
+        // as a floor in code — this only widens the set, never narrows it.
+        protectedCategories: z.array(z.enum(CATEGORIES)).default(["secrets", "security"]),
+        // Cap on adjudication model calls per run.
+        maxAdjudications: z.number().int().positive().default(10),
+    })
+        .default({
+        mode: "annotate",
+        match: "both",
+        dismiss: "never",
+        protectedCategories: ["secrets", "security"],
+        maxAdjudications: 10,
+    }),
 });
 /** One routing scope: ordered globs → a directory containing .expo-code-review/. */
 export const RoutingScopeSchema = z.object({
@@ -122,6 +203,7 @@ export const RoutingScopeSchema = z.object({
      * routing.jsonc is read from the PR-head checkout, so this field is
      * PR-controllable input: absolute paths and `..` traversal are rejected so a
      * scope config can never resolve outside the repo. */
+    // @ref LLP 0006#routing-manifest [implements] — traversal guard; load.ts re-checks at runtime (defense in depth)
     config: z
         .string()
         .min(1)
@@ -155,6 +237,7 @@ export const RoutingManifestSchema = z
          * chain still fires the default when the key is absent, which would make
          * `defaults.auth` a phantom `{mode:'api-key',provider:'openai'}` for every
          * manifest that omits auth and silently override the root config's real auth. */
+        // @ref LLP 0006#routing-manifest [constrained-by] — zod v4 default().optional() trap; unwrap avoids a phantom auth stub
         auth: ReviewConfigSchema.shape.auth.unwrap().optional(),
         /** Agent ids injected into every scope with alwaysRun, from the ROOT roster. */
         enforceAgents: z.array(z.string()).default([]),
@@ -202,10 +285,13 @@ export const RoutingManifestSchema = z
  * standalone `ecr review --scope --post` always target the same marker — an
  * honored per-scope tag would let the two halves strand each other's comments.
  */
+// @ref LLP 0006#root-vs-scope-config [implements] — one of three enforcement layers; z.never fails at parse, not runtime
 export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
     auth: true,
     breakGlass: true,
     commentTag: true,
+    stack: true,
+    feedback: true,
 }).extend({
     auth: z
         .never({ error: "auth is locked to the root config; remove it from this scope config" })
@@ -216,4 +302,14 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
         error: "commentTag is locked: per-scope comment markers are derived as <rootTag>:<scope>; remove it from this scope config",
     })
         .optional(),
+    stack: z
+        .never({
+        error: "stack is locked to the root config (one PR has one stack); remove it from this scope config",
+    })
+        .optional(),
+    feedback: z
+        .never({
+        error: "feedback is locked to the root config (the comment lifecycle is global); remove it from this scope config",
+    })
+        .optional(),
 });