@mrciphersmith/keryx 0.3.113 → 0.3.114

package/README.md

@@ -1148,6 +1148,10 @@ package. See
 
 Every managed review start, attach or ingest (and any `dispatch-check` or `blast-radius` given `--package`) refreshes the graph, the wiki and the memory index for the PR head and writes `layers.json`, with **no model call**; `wiki enrich` is the only model step and is never automatic (`keryx review layers refresh --package <dir> [--write-wiki]`). Blast-radius files beyond the 40-file cap are reviewed in chunks (`keryx review chunks estimate|next|record|merge`; the ceiling is 25 passes of 40 files, `reviewChunks.maxPasses` in `routing.config.json`), `keryx review coverage` counts what is covered, omitted by name, and uncovered, and `keryx review complete` refuses while a file is uncovered unless you pass `--waive-coverage "<your words>"`. `/reviews` and `/review layers` in the shell show it.
 
+### Gates that keep a review report honest
+
+`keryx review complete` on a pull-request package refuses a merged PR or a moved head until the first line of `report.md` names the reviewed SHA and says so, and refuses a report with no `Evidence level:` line (`static only — did not run: <what>` or `ran — <what>`; a package ingested before the field existed only warns). `keryx review ingest` reads each finding's quote at its `path` at the reviewed SHA and refuses one that does not resolve there, adds a `citation not found` line to a rebuttal that cites a rule or document missing from the tree (the finding is never deleted), and a finding can close as `narrowed` only with a "what remains" text. See [review with a record](docs/docs/guides/review-with-a-record.md).
+
 ### Review bot on pull requests
 
 A GitHub Action reviews each same-repository pull request, has a second model

package/dist/cli.js

@@ -23150,7 +23150,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.113",
+    version: "0.3.114",
     description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
     private: false,
     publishConfig: {
@@ -68818,10 +68818,12 @@ function researchErrors(value, findings) {
     ids.add(id);
     if (!nonempty(o.source) || !nonempty(o.question))
       errors.push(`${id}: source and question are required`);
-    if (!["finding", "refuted", "out-of-scope"].includes(String(o.status)))
+    if (!["finding", "refuted", "out-of-scope", "narrowed"].includes(String(o.status)))
       errors.push(`${id}: unresolved research (${String(o.status)})`);
     if (!nonempty(o.evidence) || !nonempty(o.reason))
       errors.push(`${id}: closure needs evidence and reason`);
+    if (o.status === "narrowed" && !nonempty(o.remains))
+      errors.push(`${id}: narrowed needs a "what remains" text`);
     if (o.status === "finding") {
       const matches = findings.filter((f) => f && typeof f === "object" && (f.id === o.finding || f.global_id === o.finding));
       if (!nonempty(o.finding) || matches.length !== 1)
@@ -78919,6 +78921,127 @@ function arbiterSession() {
 }
 var session;
 
+// src/review/rebuttal-citation.ts
+function citedPaths(text) {
+  const found = new Set;
+  for (const match of text.replace(URL2, " ").matchAll(CITED)) {
+    const cited = match[1];
+    if (cited.includes("/") || ROOT_DOCUMENT.test(cited))
+      found.add(cited);
+  }
+  return [...found];
+}
+async function flagMissingCitations(findings, exists) {
+  let added = 0;
+  for (const finding of findings) {
+    const disposition = finding.disposition;
+    if (disposition === undefined || typeof disposition.evidence !== "string")
+      continue;
+    const missing = [];
+    for (const cited of citedPaths(disposition.evidence)) {
+      if (disposition.evidence.includes(marker(cited)))
+        continue;
+      if (!await exists(cited))
+        missing.push(cited);
+    }
+    if (missing.length === 0)
+      continue;
+    disposition.evidence = `${disposition.evidence}
+${missing.map(marker).join(`
+`)}`;
+    added += missing.length;
+  }
+  return added;
+}
+var URL2, CITED, ROOT_DOCUMENT, marker = (cited) => `citation not found: ${cited}`;
+var init_rebuttal_citation = __esm(() => {
+  URL2 = /\bhttps?:\/\/\S+/gi;
+  CITED = /(?<![\w./-])((?:\.\.?\/)*(?:[\w.-]+\/)*[\w.-]+\.(?:mdc|mdx|md|txt|json|ya?ml|toml))(?![\w-])/g;
+  ROOT_DOCUMENT = /^[A-Z][A-Z0-9_-]*\.(?:md|mdx|txt)$/;
+});
+
+// src/review/complete-head-gate.ts
+async function completeHeadGate(input) {
+  const { target } = input.manifest;
+  if (target.kind !== "pr")
+    return { warnings: [] };
+  let pr;
+  try {
+    pr = await input.lookup(target.ref);
+  } catch (error) {
+    return { warnings: [`could not read the PR state for ${target.ref} (${error instanceof Error ? error.message : String(error)}); the head and merge check was skipped`] };
+  }
+  if (pr === null || !pr.exists)
+    return { warnings: [`could not read the PR state for ${target.ref}; the head and merge check was skipped`] };
+  const recorded = target.head ?? null;
+  const reviewed = recorded !== null && USABLE_SHA.test(recorded) ? recorded : null;
+  const unusable = recorded !== null && reviewed === null ? [`the reviewed head recorded for ${target.ref} ("${recorded}") is not a commit SHA; the moved-head check was skipped`] : [];
+  const merged = typeof pr.state === "string" && pr.state.toUpperCase() === "MERGED";
+  const prHead = typeof pr.headSha === "string" && pr.headSha !== "" ? pr.headSha : null;
+  const moved = reviewed !== null && prHead !== null && !sameCommit(reviewed, prHead);
+  if (!merged && !moved)
+    return { warnings: unusable };
+  const what = [merged ? "the PR is merged" : undefined, moved ? `the PR head moved (reviewed ${reviewed.slice(0, 7)}, now ${prHead.slice(0, 7)})` : undefined].filter(Boolean).join(" and ");
+  const first = input.report.split(/\r?\n/).find((line) => line.trim() !== "" && !/^\s*<!--.*-->\s*$/.test(line)) ?? "";
+  const names = reviewed === null ? /\b[0-9a-f]{7,40}\b/i.test(first) : first.toLowerCase().includes(reviewed.slice(0, 7).toLowerCase());
+  if (names && SAYS_SO.test(first))
+    return { warnings: unusable };
+  throw new Error(`Cannot complete managed review; ${what}. The report's first line must name the reviewed SHA${reviewed === null ? "" : ` (${reviewed.slice(0, 7)})`} and say the PR moved, for example: "Reviewed ${(reviewed ?? "<sha>").slice(0, 7)} \u2014 the PR has since ${merged ? "merged" : "moved on"}."`);
+}
+var MOVE_WORD = "(?:merged|moved|advanced|superseded|closed|force-pushed)", PR_WORD = "(?:pr|pull request|head)", SAYS_SO, USABLE_SHA, sameCommit = (a, b) => {
+  const [x, y] = [a.toLowerCase(), b.toLowerCase()];
+  return x.startsWith(y) || y.startsWith(x);
+};
+var init_complete_head_gate = __esm(() => {
+  SAYS_SO = new RegExp(`\\b${PR_WORD}\\b.{0,40}\\b${MOVE_WORD}\\b|\\b${MOVE_WORD}\\b.{0,40}\\b${PR_WORD}\\b`, "i");
+  USABLE_SHA = /^[0-9a-f]{7,40}$/i;
+});
+
+// src/review/evidence-level.ts
+function itemsOf(text) {
+  return text.split(/[,;]/).map((item) => item.trim()).filter((item) => item.length > 0 && !PLACEHOLDER.test(item));
+}
+function withoutFences(report) {
+  let fence = null;
+  const kept = [];
+  for (const line of report.split(/\r?\n/)) {
+    const marker = /^\s*(```+|~~~+)/.exec(line)?.[1];
+    if (marker !== undefined) {
+      if (fence === null)
+        fence = marker[0];
+      else if (marker[0] === fence)
+        fence = null;
+      continue;
+    }
+    if (fence === null)
+      kept.push(line);
+  }
+  return kept;
+}
+function parseEvidenceLevel(report) {
+  const line = withoutFences(report).map((l) => LINE.exec(l)).find((m) => m !== null);
+  if (!line)
+    return { ok: false, reason: "the report has no `Evidence level:` line" };
+  const value = line[1].replace(/(?:\*\*|__)\s*$/, "").trim();
+  const staticOnly = /^static[ -]only\b/i.exec(value);
+  if (staticOnly) {
+    const items = itemsOf(value.slice(staticOnly[0].length).replace(SEPARATORS, "").replace(/^(?:did not run|not run|did not)\s*:?\s*/i, ""));
+    return items.length > 0 ? { ok: true, level: "static-only", items } : { ok: false, reason: "`static only` must list what did not run" };
+  }
+  const ran = /^ran\b/i.exec(value);
+  if (ran) {
+    const items = itemsOf(value.slice(ran[0].length).replace(SEPARATORS, ""));
+    return items.length > 0 ? { ok: true, level: "ran", items } : { ok: false, reason: "`ran` must list what ran" };
+  }
+  return { ok: false, reason: "the evidence level must start with `static only` or `ran`" };
+}
+var REPORT_FIELD_EVIDENCE_LEVEL = "evidence-level", LINE, SEPARATORS, PLACEHOLDER;
+var init_evidence_level = __esm(() => {
+  LINE = /^\s*(?:[-*+]\s+)?(?:\*\*|__)?evidence level\s*:?\s*(?:\*\*|__)?\s*:?\s*(.*)$/i;
+  SEPARATORS = /^[\s:\u2014\u2013-]+/;
+  PLACEHOLDER = /^(?:none|nothing|n\/a|na|nil|-|\u2014|\u2013)\.?$/i;
+});
+
 // src/review/verification.ts
 function verificationClaims(source) {
   if (source === undefined) {
@@ -79868,7 +79991,7 @@ var init_repair = __esm(() => {
 });
 
 // src/review/managed.ts
-import { mkdir as mkdir52, readFile as readFile98, readdir as readdir33, realpath as realpath18, rm as rm13, stat as stat27 } from "fs/promises";
+import { lstat as lstat12, mkdir as mkdir52, readFile as readFile98, readdir as readdir33, realpath as realpath18, rm as rm13, stat as stat27 } from "fs/promises";
 import path188 from "path";
 function reviewsRoot(cwd) {
   return path188.join(cwd, ".metaproject", "reviews");
@@ -79937,6 +80060,7 @@ async function createManagedReviewPackage(input) {
   const repairs = repairMechanicalOmissions(reported);
   const head = await resolveTargetHead(input);
   await anchorFindings(reported, input, head);
+  refuseUnresolvedLocators(reported, input, head);
   assignGlobalIds(reported, reviewId);
   const merged = mergeVerifications(reported, input.verifications ?? [], {
     mode: input.verificationMode ?? DEFAULT_VERIFICATION_MODE
@@ -79955,6 +80079,7 @@ async function createManagedReviewPackage(input) {
     ...roundDismissed
   ];
   assignGlobalIds(findings, reviewId);
+  await flagMissingCitations(findings, (cited) => citationExists(input.cwd, head, cited));
   const carried = input.scope === undefined ? await readPreFilterScopeBlock(packageDir) : undefined;
   const concurrency = concurrencyPlan(input, coverage);
   const caps = {
@@ -80150,6 +80275,18 @@ async function completeManagedReview(cwd, ref, options = {}) {
   if (missing.length > 0) {
     throw new Error(`Cannot complete managed review; missing artifacts: ${missing.join(", ")}`);
   }
+  const warnings = [];
+  const reportText = await readFile98(path188.join(packageDir, "report.md"), "utf8");
+  if (options.prLookup !== undefined)
+    warnings.push(...(await completeHeadGate({ manifest, report: reportText, lookup: options.prLookup })).warnings);
+  const evidence = parseEvidenceLevel(reportText);
+  if (!evidence.ok) {
+    const problem = `the report's evidence level is missing or invalid: ${evidence.reason}`;
+    if (manifest.report_fields?.includes(REPORT_FIELD_EVIDENCE_LEVEL)) {
+      throw new Error(`Cannot complete managed review; ${problem}. Add a line \`Evidence level: static only \u2014 did not run: <what>\` or \`Evidence level: ran \u2014 <what>\` to report.md`);
+    }
+    warnings.push(`${problem} (this package predates the field, so it is a warning)`);
+  }
   const researchFindings = JSON.parse(await readFile98(path188.join(packageDir, "findings.json"), "utf8"));
   const researchPath = path188.join(packageDir, "research.json");
   const researchBefore = options.waiveCoverage === undefined ? undefined : await readFile98(researchPath, "utf8").catch(() => {
@@ -80193,7 +80330,7 @@ async function completeManagedReview(cwd, ref, options = {}) {
     packagePath: path188.relative(cwd, packageDir),
     ...options.now === undefined ? {} : { now: options.now }
   });
-  return { manifest: updated, reviewNotes, dispositions: tallyDispositions(recorded), ...coverageWaiver === undefined ? {} : { coverageWaiver } };
+  return { manifest: updated, reviewNotes, dispositions: tallyDispositions(recorded), warnings, ...coverageWaiver === undefined ? {} : { coverageWaiver } };
 }
 async function validateManagedReviewManifest(cwd, manifest) {
   const errors = [];
@@ -80283,6 +80420,7 @@ function buildManifest(args) {
     coverage: args.coverage,
     filter_stats: args.filterStats,
     ...args.repairs.length === 0 ? {} : { repairs: args.repairs },
+    report_fields: [REPORT_FIELD_EVIDENCE_LEVEL],
     ...args.input.cost === undefined ? {} : { cost: args.input.cost },
     ...crossFamily === undefined ? {} : { cross_family_review: crossFamily },
     ...args.input.automatic === true ? { automatic: true } : {},
@@ -80358,7 +80496,7 @@ function triage(findings, args) {
 }
 async function anchorFindings(findings, input, head) {
   const read = input.readTreeFile ?? (head === null ? readFromWorkingTree(input) : async (relative) => {
-    const contained = await containedRelativePath(input.cwd, relative);
+    const contained = lexicalRelativePath(relative);
     return contained === null ? null : readFileAtCommit(input.cwd, head, contained);
   });
   for (const finding of findings) {
@@ -80384,17 +80522,42 @@ async function anchorFindings(findings, input, head) {
     };
   }
 }
-async function containedRelativePath(cwd, relative) {
-  const root = await realpath18(cwd).catch(() => path188.resolve(cwd));
-  const resolved = path188.resolve(root, relative);
-  const real = await realpath18(resolved).catch(() => null);
-  if (real === null || real !== root && !real.startsWith(`${root}${path188.sep}`)) {
+function refuseUnresolvedLocators(findings, input, head) {
+  if (head === null || input.readTreeFile !== undefined) {
+    return;
+  }
+  const unresolved = findings.filter((finding) => finding.source !== "external" && finding.disposition === undefined && finding.locator?.state === "unlocatable");
+  if (unresolved.length === 0) {
+    return;
+  }
+  const lines = unresolved.map((finding) => {
+    const locator = finding.locator?.state === "unlocatable" ? finding.locator : undefined;
+    const line = locator?.reported_line ?? null;
+    return `  - ${finding.id ?? finding.summary} (${finding.file}${line === null ? "" : `:${line}`}): ${locator?.reason ?? ""}`;
+  });
+  throw new Error(`Cannot ingest review; ${unresolved.length} finding(s) cite a quote that does not resolve at the reviewed SHA ${head.slice(0, 12)}:
+${lines.join(`
+`)}
+Causes: the quote is not in the file at that commit, appears in it more than once, or the file or the commit is not in this checkout (check \`git cat-file -e ${head.slice(0, 12)}\`). Re-quote one distinct line from \`git show ${head.slice(0, 7)}:<path>\` or dismiss the finding with evidence.`);
+}
+async function citationExists(cwd, head, cited) {
+  const relative = lexicalRelativePath(cited);
+  if (relative === null) {
+    return false;
+  }
+  if (head !== null && await readFileAtCommit(cwd, head, relative) !== null) {
+    return true;
+  }
+  return lstat12(path188.resolve(cwd, relative)).then(() => true, () => false);
+}
+function lexicalRelativePath(relative) {
+  const normalised = path188.posix.normalize(relative.replace(/\\/g, "/"));
+  if (normalised === "." || normalised === ".." || normalised.startsWith("../") || path188.posix.isAbsolute(normalised)) {
     return null;
   }
-  return real;
+  return normalised;
 }
-async function readFileAtCommit(cwd, commit, absolute) {
-  const relative = path188.relative(await realpath18(cwd).catch(() => path188.resolve(cwd)), absolute);
+async function readFileAtCommit(cwd, commit, relative) {
   try {
     const proc = Bun.spawn(["git", "show", `${commit}:${relative}`], {
       cwd,
@@ -81091,6 +81254,9 @@ async function loadDocpackSchema(cwd) {
 var REQUIRED_ARTIFACTS, BLAST_RADIUS_ARTIFACT = "blast-radius.json", EMBEDDED_FINDINGS_FENCE, SEVERITY_PREFIX, NOT_RECORDED = (field) => `not recorded: derived from a markdown review report, which carried no ${field} field`, LABEL_LINE, HEADING_MARKER, FINDING_IDENTIFIER, TITLE_SEPARATOR, REFERENCE_PUNCTUATION, PRE_FILTER_SCOPE_BLOCK, BLAST_RADIUS_RECORD_SOURCE, MAX_SAME_DAY_ROUNDS = 99;
 var init_managed = __esm(() => {
   init_coverage_complete();
+  init_rebuttal_citation();
+  init_complete_head_gate();
+  init_evidence_level();
   init_research();
   init_validator();
   init_contracts();
@@ -88980,7 +89146,7 @@ function sha256Hex5(bytes) {
 var init_checksum = () => {};
 
 // src/bundle/external.ts
-import { mkdir as mkdir54, lstat as lstat12, readFile as readFile108, readdir as readdir40, rename as rename11, stat as stat29, unlink, writeFile as writeFile33 } from "fs/promises";
+import { mkdir as mkdir54, lstat as lstat13, readFile as readFile108, readdir as readdir40, rename as rename11, stat as stat29, unlink, writeFile as writeFile33 } from "fs/promises";
 import { createHmac as createHmac4, randomBytes as randomBytes10, timingSafeEqual as timingSafeEqual2 } from "crypto";
 import path215 from "path";
 function emptyRegistry() {
@@ -89024,7 +89190,7 @@ async function loadIntegrityKey(env, homeDir) {
   const keyPath = integrityKeyPathFor(env, homeDir);
   let st;
   try {
-    st = await lstat12(keyPath);
+    st = await lstat13(keyPath);
   } catch (err) {
     if (err?.code === "ENOENT")
       return { ok: false, reason: "missing" };
@@ -89464,7 +89630,7 @@ var init_external = __esm(() => {
 
 // src/gdskills/governance/scout.ts
 import { existsSync as existsSync32, readFileSync as readFileSync19, statSync as statSync8 } from "fs";
-import { lstat as lstat13, mkdtemp as mkdtemp2, readdir as readdir41, readFile as readFile109 } from "fs/promises";
+import { lstat as lstat14, mkdtemp as mkdtemp2, readdir as readdir41, readFile as readFile109 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
 import path216 from "path";
 function stemLite(token) {
@@ -89690,7 +89856,7 @@ async function scoutImports(query, opts = {}) {
 async function collectSkillDirectorySnapshot(dir, limits = DEFAULT_SNAPSHOT_VETTING_LIMITS) {
   let rootStat;
   try {
-    rootStat = await lstat13(dir);
+    rootStat = await lstat14(dir);
   } catch (error) {
     return { ok: false, reason: "unreadable-dir", message: `cannot read ${dir}: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -89722,7 +89888,7 @@ async function collectSkillDirectorySnapshot(dir, limits = DEFAULT_SNAPSHOT_VETT
       const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
       let entryStat;
       try {
-        entryStat = await lstat13(abs);
+        entryStat = await lstat14(abs);
       } catch (error) {
         return { ok: false, reason: "unreadable-file", message: `cannot stat ${rel}: ${error instanceof Error ? error.message : String(error)}` };
       }
@@ -94092,7 +94258,7 @@ var init_slate_lifecycle = __esm(() => {
 
 // src/harness/tool/builtin/slate-memory-tools.ts
 import { createReadStream } from "fs";
-import { lstat as lstat14, realpath as realpath19 } from "fs/promises";
+import { lstat as lstat15, realpath as realpath19 } from "fs/promises";
 import path223 from "path";
 import { createInterface } from "readline";
 function failure3(message) {
@@ -94110,7 +94276,7 @@ async function confinedFile(sessionDir, candidate, within) {
   try {
     const root = await realpath19(within === undefined ? sessionDir : path223.join(sessionDir, within));
     const sessionReal = await realpath19(sessionDir);
-    const info = await lstat14(path223.resolve(candidate));
+    const info = await lstat15(path223.resolve(candidate));
     if (info.isSymbolicLink() || !info.isFile())
       return null;
     const real = await realpath19(path223.resolve(candidate));
@@ -99580,7 +99746,7 @@ async function resolveGitHooksRoot(projectRoot) {
 var init_git_hooks = () => {};
 
 // src/lib/managed-git-hook.ts
-import { chmod as chmod9, lstat as lstat15, mkdir as mkdir57, readFile as readFile112, realpath as realpath20, writeFile as writeFile35 } from "fs/promises";
+import { chmod as chmod9, lstat as lstat16, mkdir as mkdir57, readFile as readFile112, realpath as realpath20, writeFile as writeFile35 } from "fs/promises";
 import path230 from "path";
 function escapeRegExp6(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -99611,13 +99777,13 @@ async function resolveContainedHookPath(projectRoot, hookName) {
   const commonDirReal = await realpath20(path230.dirname(hooksRoot)).catch(() => path230.dirname(hooksRoot));
   const projectRootReal = await realpath20(projectRoot).catch(() => projectRoot);
   const acceptedContainers = [commonDirReal, projectRootReal];
-  const hooksRootStat = await lstat15(hooksRoot).catch(() => null);
+  const hooksRootStat = await lstat16(hooksRoot).catch(() => null);
   const hooksRootReal = await realpath20(hooksRoot).catch(() => hooksRoot);
   if (hooksRootStat?.isSymbolicLink()) {
     await assertResolvesInside(hooksRoot, acceptedContainers, "the git hooks directory");
   }
   const hookPath = path230.join(hooksRoot, hookName);
-  const hookStat = await lstat15(hookPath).catch(() => null);
+  const hookStat = await lstat16(hookPath).catch(() => null);
   if (hookStat?.isSymbolicLink()) {
     await assertResolvesInside(hookPath, [hooksRootReal, projectRootReal], "the git hook file");
   }
@@ -107924,7 +108090,7 @@ var init_registry3 = __esm(() => {
 // src/harness/tool/builtin/spawn-subagent-tool.ts
 import { createHash as createHash74, randomUUID as randomUUID28 } from "crypto";
 import { execFile as execFile7 } from "child_process";
-import { lstat as lstat16, mkdir as mkdir60, mkdtemp as mkdtemp3, readFile as readFile114, realpath as realpath21, rm as rm16, stat as stat31, writeFile as writeFile38 } from "fs/promises";
+import { lstat as lstat17, mkdir as mkdir60, mkdtemp as mkdtemp3, readFile as readFile114, realpath as realpath21, rm as rm16, stat as stat31, writeFile as writeFile38 } from "fs/promises";
 import { tmpdir as tmpdir7 } from "os";
 import path243 from "path";
 import { promisify as promisify5 } from "util";
@@ -108232,7 +108398,7 @@ async function verifyWorktreeCandidate(candidate, commonDir, worktreesDir) {
   try {
     const realCandidate = await realpath21(candidate);
     const dotGit = path243.join(realCandidate, ".git");
-    const dotGitStat = await lstat16(dotGit);
+    const dotGitStat = await lstat17(dotGit);
     if (dotGitStat.isDirectory()) {
       return await realpath21(dotGit) === commonDir ? realCandidate : undefined;
     }
@@ -126701,6 +126867,12 @@ function layersLockPath(packageDir) {
 function packageMemoryDir(packageDir) {
   return path275.join(packageDir, LAYERS_DIR, MEMORY_DIR);
 }
+function failedRecently(existing, now) {
+  if (existing.graph.status !== "failed")
+    return false;
+  const age = now.getTime() - Date.parse(existing.graph.failedAt ?? existing.refreshedAt);
+  return age >= 0 && age < FAILED_RETRY_WINDOW_MS;
+}
 function layersRefreshInFlight(packageDir) {
   return isLockHeld(layersLockPath(packageDir), LOCK_STALE_MS2);
 }
@@ -126842,20 +127014,35 @@ async function sweepStaleWorktrees(deps, projectRoot) {
     await rm19(worktree, { recursive: true, force: true }).catch(() => {});
   }
 }
-async function withDetachedWorktree(deps, input, rev, cleanupExtra, use) {
-  const worktree = await mkdtemp6(path275.join(tmpdir12(), WORKTREE_PREFIX));
-  const cleanup = async () => {
-    await cleanupExtra().catch(() => {});
-    await deps.git(input.projectRoot, ["worktree", "remove", "--force", "--end-of-options", worktree]);
-    await rm19(worktree, { recursive: true, force: true }).catch(() => {});
-  };
+async function withSignalCleanup(packageDir, body) {
+  const cleanups = new Set;
   const onSignal = (signal) => {
     for (const name of SIGNALS)
       process.off(name, onSignal);
-    cleanup().then(() => rm19(layersLockPath(input.packageDir), { recursive: true, force: true })).catch(() => {}).finally(() => process.kill(process.pid, signal));
+    const settled = Promise.all([...cleanups].map((cleanup) => cleanup().catch(() => {})));
+    const bound = new Promise((resolve) => setTimeout(resolve, SIGNAL_CLEANUP_MAX_MS).unref());
+    Promise.race([settled, bound]).then(() => rm19(layersLockPath(packageDir), { recursive: true, force: true })).catch(() => {}).finally(() => process.kill(process.pid, signal));
   };
   for (const name of SIGNALS)
     process.on(name, onSignal);
+  try {
+    return await body((cleanup) => {
+      cleanups.add(cleanup);
+      return () => void cleanups.delete(cleanup);
+    });
+  } finally {
+    for (const name of SIGNALS)
+      process.off(name, onSignal);
+  }
+}
+async function withDetachedWorktree(deps, input, rev, cleanupExtra, register, use) {
+  const worktree = await mkdtemp6(path275.join(tmpdir12(), WORKTREE_PREFIX));
+  const cleanup = async () => {
+    await cleanupExtra().catch(() => {});
+    await deps.git(input.projectRoot, ["worktree", "remove", "--force", "--end-of-options", worktree]);
+    await rm19(worktree, { recursive: true, force: true }).catch(() => {});
+  };
+  const unregister = register(cleanup);
   try {
     const add = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "worktree", "add", "--detach", "--force", "--end-of-options", worktree, rev];
     let added = await deps.git(input.projectRoot, add);
@@ -126867,19 +127054,22 @@ async function withDetachedWorktree(deps, input, rev, cleanupExtra, use) {
       throw new Error(`could not check out ${rev} to build its graph`);
     return await use(worktree, await deps.git(worktree, ["rev-parse", "HEAD"]));
   } finally {
-    for (const name of SIGNALS)
-      process.off(name, onSignal);
-    await cleanup();
+    try {
+      await cleanup();
+    } finally {
+      unregister();
+    }
   }
 }
-async function buildPackageGraph(deps, input, prHead) {
+async function buildPackageGraph(deps, input, prHead, register) {
   const failed = (error) => ({
     status: "failed",
     commit: null,
     builtAt: null,
     nodes: 0,
     edges: 0,
-    error
+    error,
+    failedAt: deps.now().toISOString()
   });
   if (prHead === null)
     return failed("no commit to build the graph at");
@@ -126887,7 +127077,7 @@ async function buildPackageGraph(deps, input, prHead) {
   const staging = `${dataDir}.${randomUUID35()}`;
   const dropStaging = () => rm19(staging, { recursive: true, force: true }).catch(() => {});
   try {
-    return await withDetachedWorktree(deps, input, prHead, dropStaging, async (worktree, builtFrom) => {
+    return await withDetachedWorktree(deps, input, prHead, dropStaging, register, async (worktree, builtFrom) => {
       if (builtFrom !== prHead) {
         return failed(`graph would be built at ${builtFrom ?? "an unknown commit"}, not the PR head ${prHead}`);
       }
@@ -127005,7 +127195,7 @@ async function refreshLayers(input) {
     base = fromTarget ?? `${prHead}~1`;
   }
   await writeSelfIgnoringDir(path275.join(input.packageDir, LAYERS_DIR));
-  return withFileLock(layersLockPath(input.packageDir), async () => {
+  return withFileLock(layersLockPath(input.packageDir), () => withSignalCleanup(input.packageDir, async (register) => {
     await recoverGraphDirectory(input.packageDir);
     await sweepStaleWorktrees(deps, input.projectRoot);
     const existing = await readLayers(input.packageDir);
@@ -127013,8 +127203,10 @@ async function refreshLayers(input) {
     let graph;
     if (input.force !== true && sameHead && await layersCurrent(input.packageDir, existing, prHead)) {
       graph = existing.graph;
+    } else if (input.force !== true && sameHead && failedRecently(existing, deps.now())) {
+      graph = existing.graph;
     } else {
-      graph = await buildPackageGraph(deps, input, prHead);
+      graph = await buildPackageGraph(deps, input, prHead, register);
       if (graph.status === "failed" && sameHead && await layersCurrent(input.packageDir, existing, prHead)) {
         graph = existing.graph;
       }
@@ -127032,10 +127224,10 @@ async function refreshLayers(input) {
       wiki,
       memory
     };
-    await writeFileAtomic(layersFilePath(input.packageDir), `${JSON.stringify(layers, null, 2)}
+    await deps.writeLayers(layersFilePath(input.packageDir), `${JSON.stringify(layers, null, 2)}
 `);
     return layers;
-  }, { timeoutMs: LOCK_WAIT_MS, staleMs: LOCK_STALE_MS2 });
+  }), { timeoutMs: LOCK_WAIT_MS, staleMs: LOCK_STALE_MS2 });
 }
 async function loadPackageGraph(packageDir, prHead) {
   if (await layersRefreshInFlight(packageDir)) {
@@ -127045,7 +127237,8 @@ async function loadPackageGraph(packageDir, prHead) {
   if (layers === null)
     throw new PackageGraphError(`no ${LAYERS_FILE} in ${packageDir}; run \`keryx review layers refresh --package ${shellWord(packageDir)}\``);
   if (layers.graph.status !== "ok") {
-    throw new PackageGraphError(`the package graph is ${layers.graph.status}${layers.graph.error ? `: ${layers.graph.error}` : ""}`);
+    const retry = layers.graph.status === "failed" ? `; a failed build is not retried for ${FAILED_RETRY_WINDOW_MS / 60000} minutes at the same head, run \`keryx review layers refresh --package ${shellWord(packageDir)} --force\` to retry now` : "";
+    throw new PackageGraphError(`the package graph is ${layers.graph.status}${layers.graph.error ? `: ${layers.graph.error}` : ""}${retry}`);
   }
   if (!await graphIntact(packageDir, layers)) {
     throw new PackageGraphError(`the package graph directory is missing or does not match ${LAYERS_FILE}; run \`keryx review layers refresh --package ${shellWord(packageDir)}\``);
@@ -127057,7 +127250,7 @@ async function loadPackageGraph(packageDir, prHead) {
   const dataDir = packageGraphDir(packageDir);
   return { graph: await loadGraph(packageDir, dataDir), dataDir, layers };
 }
-var execFileAsync9, LAYERS_FILE = "layers.json", LAYERS_VERSION = 1, LAYERS_DIR = "layers", GRAPH_DIR = "graph", GRAPH_BUILD_FILE = "build.json", MEMORY_DIR = "memory", LOCK_NAME = "refresh.lock", MANIFEST_FILE2 = "manifest.json", LOCK_STALE_MS2 = 60000, LOCK_WAIT_MS, WORKTREE_PREFIX = "keryx-layers-", WORKTREE_SWEEP_AGE_MS, SIGNALS, WIKI_PATH_PREFIX = ".metaproject/wiki", MEMORY_PATH_PREFIX = ".metaproject/memory", defaultLayerDeps, COMMIT_ID, PackageGraphError;
+var execFileAsync9, LAYERS_FILE = "layers.json", LAYERS_VERSION = 1, LAYERS_DIR = "layers", GRAPH_DIR = "graph", GRAPH_BUILD_FILE = "build.json", MEMORY_DIR = "memory", LOCK_NAME = "refresh.lock", MANIFEST_FILE2 = "manifest.json", LOCK_STALE_MS2 = 60000, LOCK_WAIT_MS, WORKTREE_PREFIX = "keryx-layers-", WORKTREE_SWEEP_AGE_MS, FAILED_RETRY_WINDOW_MS, SIGNALS, SIGNAL_CLEANUP_MAX_MS = 5000, WIKI_PATH_PREFIX = ".metaproject/wiki", MEMORY_PATH_PREFIX = ".metaproject/memory", defaultLayerDeps, COMMIT_ID, PackageGraphError;
 var init_layers = __esm(() => {
   init_build();
   init_fs();
@@ -127071,6 +127264,7 @@ var init_layers = __esm(() => {
   execFileAsync9 = promisify9(execFile11);
   LOCK_WAIT_MS = 16 * 60000;
   WORKTREE_SWEEP_AGE_MS = 30 * 60000;
+  FAILED_RETRY_WINDOW_MS = 5 * 60000;
   SIGNALS = ["SIGINT", "SIGTERM"];
   defaultLayerDeps = {
     async git(cwd, args) {
@@ -127090,6 +127284,7 @@ var init_layers = __esm(() => {
     async indexMemory(cwd, indexDir) {
       return createMemoryService().index({ cwd, embeddings: false, indexDir });
     },
+    writeLayers: writeFileAtomic,
     now: () => new Date
   };
   COMMIT_ID = /^[0-9a-f]{7,64}$/i;
@@ -127119,7 +127314,7 @@ function layersSummaryLine(layers) {
 function layersDetailLines(layers) {
   const lines = [];
   const graph = layers.graph;
-  lines.push(graph.status === "ok" ? `graph: ok @${shortSha(graph.commit)} = ${graphHeadState(layers)} (PR head ${shortSha(layers.prHead)}), ${graph.nodes} nodes, ${graph.edges} edges, built ${graph.builtAt ?? "?"}` : `graph: ${graph.status}${graph.error ? ` \u2014 ${graph.error}` : ""}`);
+  lines.push(graph.status === "ok" ? `graph: ok @${shortSha(graph.commit)} = ${graphHeadState(layers)} (PR head ${shortSha(layers.prHead)}), ${graph.nodes} nodes, ${graph.edges} edges, built ${graph.builtAt ?? "?"}` : `graph: ${graph.status}${graph.error ? ` \u2014 ${graph.error}` : ""}${graph.status === "failed" ? " (not retried automatically for a few minutes at the same head; refresh --force retries now)" : ""}`);
   const wiki = layers.wiki;
   lines.push(`wiki: ${wiki.status} @${shortSha(wiki.commit)}, divergence ${divergenceText(wiki.divergence)}, ${wiki.pagesRefreshed} page(s) ${wiki.written ? "refreshed" : "would refresh (dry run)"}, ` + `${wiki.pagesStaleProse === null ? "stale prose unknown" : `${wiki.pagesStaleProse} page(s) with stale prose`}${wiki.error ? ` \u2014 ${wiki.error}` : ""}`);
   const memory = layers.memory;
@@ -127458,7 +127653,7 @@ var init_review_panel = __esm(() => {
 // src/tui/review-layers-actions.ts
 import { execFile as execFile12 } from "child_process";
 function layersRefreshArgv(entry, packageDir) {
-  return [...SAFE_BUN_SPAWN_ARGS, entry, "review", "layers", "refresh", "--package", packageDir, "--json"];
+  return [...SAFE_BUN_SPAWN_ARGS, entry, "review", "layers", "refresh", "--package", packageDir, "--force", "--json"];
 }
 function killLiveChildren() {
   for (const child of liveChildren)
@@ -127474,8 +127669,14 @@ function makeLayersRefreshRunner(entry, timeoutMs = REFRESH_TIMEOUT_MS) {
       exitHookInstalled = true;
       process.once("exit", killLiveChildren);
     }
+    const startedAt = Date.now();
     const child = execFile12(process.execPath, layersRefreshArgv(entry, packageDir), { cwd: projectRoot, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
       liveChildren.delete(child);
+      if (error?.killed === true || /maxBuffer/i.test(error?.message ?? "")) {
+        const timedOut = error?.killed === true && Date.now() - startedAt >= timeoutMs - 100;
+        reject(new Error(timedOut ? `the layers refresh did not finish within ${Math.round(timeoutMs / 1000)}s and was stopped` : "the layers refresh printed more output than the limit allows and was stopped"));
+        return;
+      }
       try {
         resolve(JSON.parse(stdout));
       } catch {
@@ -137684,7 +137885,7 @@ function protectJsonIds(text) {
   const head = text.trim();
   if (head.length === 0 || head[0] !== "[" && head[0] !== "{")
     return;
-  if (text.includes(PLACEHOLDER))
+  if (text.includes(PLACEHOLDER2))
     return;
   try {
     JSON.parse(head);
@@ -137694,7 +137895,7 @@ function protectJsonIds(text) {
   const hidden = [];
   const hide = (value) => {
     hidden.push(value);
-    return `${PLACEHOLDER}${letters(hidden.length - 1)}x`;
+    return `${PLACEHOLDER2}${letters(hidden.length - 1)}x`;
   };
   let out = "";
   let i = 0;
@@ -137724,13 +137925,13 @@ function protectJsonIds(text) {
   }
   return {
     text: out,
-    restore: (scrubbed) => scrubbed.replace(new RegExp(`${PLACEHOLDER}([a-j]+)x`, "g"), (whole, index) => {
+    restore: (scrubbed) => scrubbed.replace(new RegExp(`${PLACEHOLDER2}([a-j]+)x`, "g"), (whole, index) => {
       const at = Number(index.replace(/[a-j]/g, (c) => String(c.charCodeAt(0) - 97)));
       return hidden[at] ?? whole;
     })
   };
 }
-var PLACEHOLDER = "kxjsonid", GITHUB_URL_PREFIX, GITHUB_URL_REST, SENSITIVE_KEY, NUMBER2;
+var PLACEHOLDER2 = "kxjsonid", GITHUB_URL_PREFIX, GITHUB_URL_REST, SENSITIVE_KEY, NUMBER2;
 var init_granted_json_ids = __esm(() => {
   GITHUB_URL_PREFIX = /^https:\/\/(?:api\.)?github\.com\/(?:repos\/)?[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\//;
   GITHUB_URL_REST = /^(?:actions\/runs|pull|issues)\/\d+(?:\/[A-Za-z0-9_-]+)*(?:#[A-Za-z_-]+-?\d+)?$/;
@@ -181120,7 +181321,7 @@ var init_retired_rules = __esm(() => {
 });
 
 // src/gdskills/guarded-fs-ops.ts
-import { cp as cp2, lstat as lstat17, readFile as readFile171, readdir as readdir59, realpath as realpath25, unlink as unlink3 } from "fs/promises";
+import { cp as cp2, lstat as lstat18, readFile as readFile171, readdir as readdir59, realpath as realpath25, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync63 } from "fs";
 import { createHash as createHash84 } from "crypto";
 import path340 from "path";
@@ -181211,7 +181412,7 @@ async function removeStaleRuntimeBuilds(skillsRoot, fsOps = { unlink: unlink3 })
         continue;
       const installedPath = path340.join(installedDir, entryName);
       try {
-        const stats = await lstat17(installedPath);
+        const stats = await lstat18(installedPath);
         if (!stats.isFile()) {
           outcomes.push({ path: installedPath, action: "kept-not-regular-file" });
           continue;
@@ -181230,7 +181431,7 @@ async function removeStaleRuntimeBuilds(skillsRoot, fsOps = { unlink: unlink3 })
 }
 async function resolveSweepableDir(dir) {
   try {
-    const stats = await lstat17(dir);
+    const stats = await lstat18(dir);
     if (stats.isSymbolicLink() || !stats.isDirectory()) {
       return {
         kind: "blocked",
@@ -181305,7 +181506,7 @@ async function removeUnmodifiedRetiredRules(rulesTarget, fsOps = { unlink: unlin
     const installedPath = path340.join(rulesTarget, retired.fileName);
     let stage = "lstat";
     try {
-      const stats = await lstat17(installedPath);
+      const stats = await lstat18(installedPath);
       if (!stats.isFile()) {
         outcomes.push({ fileName: retired.fileName, action: "kept-not-regular-file" });
         continue;
@@ -181376,7 +181577,7 @@ var init_guarded_fs_ops = __esm(() => {
 });
 
 // src/gdskills/install.ts
-import { lstat as lstat18, readFile as readFile172, readlink as readlink2 } from "fs/promises";
+import { lstat as lstat19, readFile as readFile172, readlink as readlink2 } from "fs/promises";
 import { existsSync as existsSync64 } from "fs";
 import path341 from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
@@ -181489,7 +181690,7 @@ async function installBundledSharedSkills(skillsRoot, metaprojectRoot) {
 async function checkInstallDestination(destination, displayPath) {
   let stats;
   try {
-    stats = await lstat18(destination);
+    stats = await lstat19(destination);
   } catch (error) {
     if (isErrnoException(error) && error.code === "ENOENT") {
       return { usable: true };
@@ -181572,7 +181773,7 @@ async function installContracts(contractsRoot, metaprojectRoot) {
 async function checkInstallFile(destination, displayPath) {
   let stats;
   try {
-    stats = await lstat18(destination);
+    stats = await lstat19(destination);
   } catch (error) {
     if (isMissingPathError(error)) {
       return { usable: true };
@@ -189768,7 +189969,7 @@ var init_plan = __esm(() => {
 });
 
 // src/gdskills/manifest/state.ts
-import { lstat as lstat19, readFile as readFile182 } from "fs/promises";
+import { lstat as lstat20, readFile as readFile182 } from "fs/promises";
 import path363 from "path";
 function isValidInstallState(value) {
   return validateAgainstSchemaObject(INSTALL_STATE_SCHEMA, value).valid;
@@ -189811,7 +190012,7 @@ async function hasSymlinkSegment(repoRoot, posixRel) {
     current = path363.join(current, segment);
     let stat;
     try {
-      stat = await lstat19(current);
+      stat = await lstat20(current);
     } catch {
       return false;
     }
@@ -190390,7 +190591,7 @@ var init_sync2 = __esm(() => {
 });
 
 // src/gdskills/import-skills.ts
-import { lstat as lstat20, readdir as readdir64, readFile as readFile185, stat as stat41 } from "fs/promises";
+import { lstat as lstat21, readdir as readdir64, readFile as readFile185, stat as stat41 } from "fs/promises";
 import { homedir as homedir15 } from "os";
 import path368 from "path";
 function emptyOnlyError(label) {
@@ -191401,7 +191602,7 @@ async function decideReferencedRules(options, sources, refusedPackages) {
 async function listTemplateFiles(sourcePath) {
   const root = path368.join(path368.dirname(sourcePath), TEMPLATES_DIR);
   try {
-    if (!(await lstat20(root)).isDirectory())
+    if (!(await lstat21(root)).isDirectory())
       return [];
   } catch {
     return [];
@@ -191823,7 +192024,7 @@ var init_import_skills = __esm(() => {
 });
 
 // src/gdskills/remove-skill.ts
-import { lstat as lstat21, readdir as readdir65, readFile as readFile186, realpath as realpath26 } from "fs/promises";
+import { lstat as lstat22, readdir as readdir65, readFile as readFile186, realpath as realpath26 } from "fs/promises";
 import path369 from "path";
 async function removeProjectSkill(projectRoot, options) {
   if (!await pathExists(path369.join(projectRoot, ".metaproject"))) {
@@ -192018,7 +192219,7 @@ function normalizeSkillKey(input) {
 }
 async function lstatOrMissing(target) {
   try {
-    return await lstat21(target);
+    return await lstat22(target);
   } catch (error) {
     if (isMissingPathError(error))
       return;
@@ -192083,7 +192284,7 @@ async function locateRewritable(root, relativePath) {
   if (absolute === root || !isPathInside(root, absolute)) {
     throw new Error(`${LABEL}: ${relativePath} resolves to ${absolute}, outside the project. Refusing to rewrite a file the project does not own. ${UNCHANGED}`);
   }
-  if (!(await lstat21(absolute)).isFile()) {
+  if (!(await lstat22(absolute)).isFile()) {
     throw new Error(`${LABEL}: ${relativePath} is not a regular file. ${UNCHANGED}`);
   }
   const resolvedPath = toPosix(path369.relative(root, absolute));
@@ -197025,7 +197226,7 @@ function buildLedger(input) {
         continue;
       }
       obligations.push({ ...base, status: "unresolved" });
-      gaps.push({ detail: `${id}: raw finding is not in the canonical findings and has no closure`, next: `add a disposition {"id":"${id}","status":"finding|refuted|out-of-scope","evidence":\u2026,"reason":\u2026} to --dispositions` });
+      gaps.push({ detail: `${id}: raw finding is not in the canonical findings and has no closure`, next: `add a disposition {"id":"${id}","status":"finding|refuted|out-of-scope|narrowed","evidence":\u2026,"reason":\u2026,"remains":\u2026 (narrowed only)} to --dispositions` });
     }
   }
   for (const given of input.dispositions) {
@@ -197053,7 +197254,9 @@ function closeWith(given, canonical) {
     return;
   if (given.status === "finding" && !(text4(given.finding) && canonical.filter((f) => f.id === given.finding || f.global_id === given.finding).length === 1))
     return;
-  return { status: given.status, evidence: given.evidence, reason: given.reason, ...given.status === "finding" ? { finding: given.finding } : {} };
+  if (given.status === "narrowed" && !text4(given.remains))
+    return;
+  return { status: given.status, evidence: given.evidence, reason: given.reason, ...given.status === "finding" ? { finding: given.finding } : {}, ...given.status === "narrowed" ? { remains: given.remains } : {} };
 }
 async function ledgerBlockers(ledger, canonical, options) {
   const dispatch = dispatchErrors(ledger.dispatch);
@@ -197069,7 +197272,7 @@ var init_ledger2 = __esm(() => {
   init_slice();
   init_waves();
   FINISHED = new Set(["DONE", "DONE_WITH_CONCERNS"]);
-  CLOSED = new Set(["finding", "refuted", "out-of-scope"]);
+  CLOSED = new Set(["finding", "refuted", "out-of-scope", "narrowed"]);
   OBJECT_START = /\{\s*["}]/y;
   RESULT_KEYS = new Set(["status", "reviewer", "findings"]);
   KEY_COLON = /\s*:/y;
@@ -197101,8 +197304,8 @@ needs_context and every slice its path gate requires covered by its dispatched p
 complete run (source-only, executionRequired false); anything else \u2014 NEEDS_CONTEXT, BLOCKED,
 INCOMPLETE, missing slices, no result \u2014 stays incomplete or not-run, never declared complete.
 Each raw finding becomes an obligation, closed only by a matching canonical finding or a
-valid --dispositions entry ({id, status finding|refuted|out-of-scope, evidence, reason,
-finding?}; default: the obligations already in research.json). scopeReviewed and rawReconciled
+valid --dispositions entry ({id, status finding|refuted|out-of-scope|narrowed, evidence, reason,
+finding?, remains? \u2014 required for narrowed: what of the finding still stands}; default: the obligations already in research.json). scopeReviewed and rawReconciled
 are true only when established.
 
 Slices are dispatched in waves bounded by the manifest's wave budget; a reviewer that covered
@@ -197348,24 +197551,36 @@ import path380 from "path";
 function sizeOf(block) {
   return Buffer.byteLength(JSON.stringify(block), "utf8");
 }
+function reasonOf(error) {
+  const first = (error instanceof Error ? error.message : String(error)).split(`
+`)[0] ?? "unknown error";
+  return first.length > MAX_REASON_CHARS ? `${first.slice(0, MAX_REASON_CHARS)}\u2026` : first;
+}
 function unique2(values) {
   return [...new Set(values)].sort();
 }
 function affectedFor(graph, files, depth) {
   const own = new Set(files);
   const found = new Set;
+  const failures = [];
   for (const file of files) {
     let result;
     try {
       result = computeAffected(graph, file, { depth });
-    } catch {
+    } catch (error) {
+      failures.push(`${file}: ${reasonOf(error)}`);
       continue;
     }
     for (const dependent of result.dependents)
       if (!own.has(dependent))
         found.add(dependent);
   }
-  return [...found].sort();
+  const named = failures.slice(0, MAX_NAMED_FAILURES).join("; ");
+  const more = failures.length > MAX_NAMED_FAILURES ? ` (and ${failures.length - MAX_NAMED_FAILURES} more)` : "";
+  return {
+    files: [...found].sort(),
+    unavailable: failures.length === 0 ? null : `not computed for ${failures.length} of ${files.length} file(s) \u2014 ${named}${more}`
+  };
 }
 function symbolsFor(graph, files) {
   const symbols = graph.symbols ?? [];
@@ -197415,29 +197630,34 @@ function relatedTestsFor(graph, files, affected) {
       found.add(dependent);
   return [...found].sort();
 }
-async function wikiFor(projectRoot, graph, files) {
+async function wikiFor(projectRoot, graph, files, readPage = (absolutePath) => readFile196(absolutePath, "utf8")) {
   let pages;
   try {
     pages = await collectPages(projectRoot);
-  } catch {
-    return [];
+  } catch (error) {
+    return { items: [], unavailable: `the wiki could not be read \u2014 ${reasonOf(error)}` };
   }
   const knownPaths = new Set(graph.nodes.map((node) => node.path));
   const keyFilesIndex = computeModuleKeyFiles(graph);
   const wanted = new Set(files);
   const out = [];
+  const unreadable = [];
   for (const page of pages) {
     let content;
     try {
-      content = await readFile196(page.absolutePath, "utf8");
+      content = await readPage(page.absolutePath);
     } catch {
+      unreadable.push(page.relativePath);
       continue;
     }
     const set = resolveDescribeSet({ page, content, knownPaths, keyFilesIndex });
     if (set.paths.some((candidate) => wanted.has(candidate)))
       out.push({ page: page.relativePath, title: page.title });
   }
-  return out.sort((a, b) => a.page.localeCompare(b.page));
+  return {
+    items: out.sort((a, b) => a.page.localeCompare(b.page)),
+    unavailable: unreadable.length === 0 ? null : `${unreadable.length} of ${pages.length} wiki page(s) could not be read \u2014 ${unreadable.slice(0, MAX_NAMED_FAILURES).join(", ")}`
+  };
 }
 function modulesOf(file) {
   const parts = file.split("/").filter(Boolean);
@@ -197451,8 +197671,8 @@ async function memoryFor(projectRoot, files) {
   let entries;
   try {
     entries = await collectEntries(projectRoot);
-  } catch {
-    return [];
+  } catch (error) {
+    return { items: [], unavailable: `the memory could not be read \u2014 ${reasonOf(error)}` };
   }
   const modules = new Set(files.flatMap(modulesOf));
   const wanted = new Set(files);
@@ -197466,7 +197686,7 @@ async function memoryFor(projectRoot, files) {
     if (byModule || byFile)
       out.push({ path: entry.relativePath, title: entry.title, status: entry.status, module: module ?? "" });
   }
-  return out.sort((a, b) => a.path.localeCompare(b.path));
+  return { items: out.sort((a, b) => a.path.localeCompare(b.path)), unavailable: null };
 }
 function fetchCommand(section, files, packageDir, projectRoot) {
   const first = files[0] ?? "<file>";
@@ -197496,18 +197716,28 @@ async function buildLayersBlock(input) {
   const { graph, layers } = await loadPackageGraph(input.packageDir);
   const base = async (depth) => {
     const affected = affectedFor(graph, files, depth);
+    const wiki = await wikiFor(input.projectRoot, graph, files, input.readPage);
+    const memory = await memoryFor(input.projectRoot, files);
+    const unavailable = [];
+    if (affected.unavailable !== null)
+      unavailable.push({ section: "affected", reason: affected.unavailable });
+    if (wiki.unavailable !== null)
+      unavailable.push({ section: "wiki", reason: wiki.unavailable });
+    if (memory.unavailable !== null)
+      unavailable.push({ section: "memory", reason: memory.unavailable });
     return {
       version: LAYERS_BLOCK_VERSION,
       files,
       prHead: layers.prHead,
       graphCommit: layers.graphCommit,
       maxBytes,
-      affected: { depth, files: affected },
+      affected: { depth, files: affected.files },
       symbols: symbolsFor(graph, files),
-      relatedTests: relatedTestsFor(graph, files, affected),
-      wiki: await wikiFor(input.projectRoot, graph, files),
-      memory: await memoryFor(input.projectRoot, files),
-      truncated: []
+      relatedTests: relatedTestsFor(graph, files, affected.files),
+      wiki: wiki.items,
+      memory: memory.items,
+      truncated: [],
+      unavailable
     };
   };
   let block = await base(1);
@@ -197577,11 +197807,13 @@ function layersBlockLines(block) {
     `  wiki pages: ${block.wiki.length}`,
     `  memory entries: ${block.memory.length}`
   ];
+  for (const gap of block.unavailable)
+    lines.push(`  ${gap.section}: unavailable (${gap.reason})`);
   for (const cut of block.truncated)
     lines.push(`  truncated ${cut.section}: ${cut.shown}/${cut.total} \u2014 ${cut.command}`);
   return lines;
 }
-var LAYERS_BLOCK_VERSION = 1, DEFAULT_LAYERS_BLOCK_MAX_BYTES = 8192, MAX_SYMBOLS_PER_FILE = 6, MAX_NEIGHBOURS_PER_SYMBOL = 4, MAX_BLOCK_FILES = 100, LAYERS_BLOCK_SECTIONS, CONTROL_CHARACTER;
+var LAYERS_BLOCK_VERSION = 1, DEFAULT_LAYERS_BLOCK_MAX_BYTES = 8192, MAX_SYMBOLS_PER_FILE = 6, MAX_NEIGHBOURS_PER_SYMBOL = 4, MAX_REASON_CHARS = 160, MAX_BLOCK_FILES = 100, LAYERS_BLOCK_SECTIONS, MAX_NAMED_FAILURES = 3, CONTROL_CHARACTER;
 var init_layers_payload = __esm(() => {
   init_affected();
   init_shell_quote();
@@ -197602,7 +197834,7 @@ function printLayersHelp() {
 
   keryx review layers refresh --package <dir> [--head <sha>] [--base <ref>] [--write-wiki] [--force] [--json]
   keryx review layers status  --package <dir> [--json]
-  keryx review layers block   --package <dir> --files <a,b,...> [--max-bytes <n>] [--json]
+  keryx review layers block   --package <dir> --files <a,b,...> [--max-bytes <n>] [--force] [--json]
 
 \`block\` prints the bounded \`layers\` block a reviewer payload carries for those files: files
 the graph says are affected (depth 1, then 2 while under the cap), symbol neighbours, related
@@ -197618,7 +197850,8 @@ The graph is built at the PR head into <dir>/layers/graph; the tracked graph art
 the working tree are not touched. The wiki and the memory are read from the project's
 working copy, and layers.json marks how far that is from the PR head. The wiki refresh is a
 dry run unless --write-wiki is given. A graph that is already built at this head and intact is
-kept (the wiki and the memory are still refreshed); --force rebuilds it.`);
+kept (the wiki and the memory are still refreshed); --force rebuilds it. A graph that failed at
+this head is not rebuilt for 5 minutes after the failure; --force or a new head rebuilds it.`);
 }
 function wantsHelp2(args) {
   return args.includes("--help") || args.includes("-h");
@@ -197649,7 +197882,8 @@ async function ensurePackageLayers(packageDir, options = {}) {
     projectRoot,
     packageDir,
     ...head === undefined ? {} : { prHead: head },
-    ...options.base === undefined ? {} : { base: options.base }
+    ...options.base === undefined ? {} : { base: options.base },
+    ...options.force === true ? { force: true } : {}
   });
 }
 function print(layers, json) {
@@ -197708,7 +197942,7 @@ async function runLayers(args, deps) {
     if (maxBytes !== undefined && (!Number.isInteger(maxBytes) || maxBytes < 256))
       throw new Error("--max-bytes must be an integer of at least 256; a block with every list empty needs more than that, and the refusal names how much.");
     const projectRoot = resolveProjectRoot2(process.cwd());
-    await ensurePackageLayers(packageDir, { projectRoot });
+    await ensurePackageLayers(packageDir, { projectRoot, force: rest.includes("--force") });
     const block = await buildLayersBlock({ projectRoot, packageDir, files, ...maxBytes === undefined ? {} : { maxBytes } });
     console.log(rest.includes("--json") ? JSON.stringify(block, null, 2) : layersBlockLines(block).join(`
 `));
@@ -197727,7 +197961,7 @@ var init_review_layers = __esm(() => {
   init_layers_payload();
   LAYERS_REFRESH_FLAGS = ["--package", "--head", "--base", "--write-wiki", "--force", "--json", "--help", "-h"];
   LAYERS_STATUS_FLAGS = ["--package", "--json", "--help", "-h"];
-  LAYERS_BLOCK_FLAGS = ["--package", "--files", "--max-bytes", "--json", "--help", "-h"];
+  LAYERS_BLOCK_FLAGS = ["--package", "--files", "--max-bytes", "--force", "--json", "--help", "-h"];
 });
 
 // src/commands/review-chunks.ts
@@ -199687,6 +199921,11 @@ function rejectUnknownFlags(args, allowed, usage) {
     throw new Error(`Unknown option${unknown.length > 1 ? "s" : ""} for \`keryx review ${usage}\`: ${[...new Set(unknown)].join(", ")}. Accepted: ${allowed.join(", ")}. Refused rather than ignored \u2014 a flag that is silently dropped writes nothing and reports success.`);
   }
 }
+async function trackerPrLookup(ref) {
+  if (!await githubAdapter.detect())
+    return null;
+  return githubAdapter.prStatus(ref);
+}
 async function reviewCommand(args, seams) {
   const command = args[0];
   if (!command || command === "--help" || command === "-h") {
@@ -201667,8 +201906,11 @@ async function runComplete3(args, seams) {
     manifest,
     reviewNotes,
     dispositions: tally,
-    coverageWaiver
-  } = await completeManagedReview(process.cwd(), ref, { dispositions, ...waiver?.value === undefined ? {} : { waiveCoverage: waiver.value } });
+    coverageWaiver,
+    warnings
+  } = await completeManagedReview(process.cwd(), ref, { dispositions, prLookup: seams?.prLookup ?? trackerPrLookup, ...waiver?.value === undefined ? {} : { waiveCoverage: waiver.value } });
+  for (const warning of warnings)
+    console.error(`warning: ${warning}`);
   if (coverageWaiver !== undefined) {
     const shown = coverageWaiver.files.slice(0, FIRST_FILES).join(", ");
     console.log(`coverage waived by the operator (${coverageWaiver.time}): "${coverageWaiver.operatorQuote}"; ${coverageWaiver.files.length} file(s) not reviewed: ${shown}${coverageWaiver.files.length > FIRST_FILES ? ", \u2026" : ""}`);
@@ -201927,7 +202169,7 @@ Usage:
                             [--package <review-dir>] [--json | --brief] [--out <file>]
   keryx review layers refresh --package <review-dir> [--head <sha>] [--base <ref>] [--write-wiki] [--force] [--json]
   keryx review layers status  --package <review-dir> [--json]
-  keryx review layers block   --package <review-dir> --files a,b [--max-bytes <n>] [--json]
+  keryx review layers block   --package <review-dir> --files a,b [--max-bytes <n>] [--force] [--json]
                       Graph, wiki and memory for one review; no model is called. An intact graph at
                       the same head is reused (--force rebuilds); a second refresh waits up to 16 min.
   keryx review chunks plan|estimate|next|record|merge --package <review-dir>
@@ -208130,7 +208372,7 @@ var init_tools3 = __esm(() => {
 
 // src/mcp/resources.ts
 import path396 from "path";
-import { lstat as lstat22, readdir as readdir76, realpath as realpath28, stat as stat44 } from "fs/promises";
+import { lstat as lstat23, readdir as readdir76, realpath as realpath28, stat as stat44 } from "fs/promises";
 function mimeForPath(filePath) {
   if (filePath.endsWith(".json") || filePath.endsWith(".jsonl")) {
     return "application/json";
@@ -208153,7 +208395,7 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   if (!await pathExists(root)) {
     return [];
   }
-  const ownerInfo = await lstat22(ownerRoot).catch(() => null);
+  const ownerInfo = await lstat23(ownerRoot).catch(() => null);
   if (!ownerInfo || !ownerInfo.isDirectory() || ownerInfo.isSymbolicLink())
     return [];
   const ownerReal = await realpath28(ownerRoot).catch(() => null);
@@ -224400,7 +224642,7 @@ function describeAvailability(entry, availability) {
   const range = verdict.state === "in-range" ? "within the recorded range" : verdict.state === "below-min" ? `below the recorded minimum ${verdict.min} \u2014 parsing may drift` : verdict.state === "above-max" ? `above the recorded maximum ${verdict.max} \u2014 parsing may drift` : "version banner not recognised";
   return `installed, ${version} (${range}); login not verified \u2014 keryx cannot know`;
 }
-function marker(availability) {
+function marker2(availability) {
   if (availability.state === "available")
     return style.cyan("\u25CF");
   if (availability.state === "binary-missing")
@@ -224440,7 +224682,7 @@ function renderExternalAgents(rows, capability) {
   lines.push(capability.available ? "capability: enabled" : `capability: unavailable \u2014 ${capability.reason ?? "no reason given"}`);
   lines.push("");
   for (const row of rows) {
-    lines.push(`  ${marker(row.availability)} ${row.entry.id}  ${row.entry.label}`);
+    lines.push(`  ${marker2(row.availability)} ${row.entry.id}  ${row.entry.label}`);
     lines.push(`      ${describeAvailability(row.entry, row.availability)}`);
     lines.push(`      transport: ${transportOf(row.entry)}  sandbox: ${row.entry.sandboxModes.join(", ")}  streaming: ${row.entry.streamingInput}  ` + `resumable: ${row.entry.resumable}  reports cost: ${row.entry.reportsCost}`);
   }
@@ -230794,7 +231036,7 @@ var init_types13 = __esm(() => {
 });
 
 // src/bundle/paths.ts
-import { lstat as lstat23, readFile as readFile214 } from "fs/promises";
+import { lstat as lstat24, readFile as readFile214 } from "fs/promises";
 import path423 from "path";
 function scopeRoot(scope, ctx) {
   if (scope === "user") {
@@ -230988,7 +231230,7 @@ async function resolveContainedPathForWrite(root, relPath) {
 async function refuseSymlinkChain(root, relPath) {
   const rootResolved = path423.resolve(root);
   try {
-    const rootStat = await lstat23(rootResolved);
+    const rootStat = await lstat24(rootResolved);
     if (rootStat.isSymbolicLink()) {
       return {
         ok: false,
@@ -231001,7 +231243,7 @@ async function refuseSymlinkChain(root, relPath) {
   for (const segment of segments) {
     current = path423.join(current, segment);
     try {
-      const stat = await lstat23(current);
+      const stat = await lstat24(current);
       if (stat.isSymbolicLink()) {
         return {
           ok: false,
@@ -231051,7 +231293,7 @@ var init_paths5 = __esm(() => {
 });
 
 // src/bundle/archive.ts
-import { readdir as readdir79, readFile as readFile215, lstat as lstat24 } from "fs/promises";
+import { readdir as readdir79, readFile as readFile215, lstat as lstat25 } from "fs/promises";
 import path424 from "path";
 import { gzipSync, gunzipSync } from "zlib";
 function resolveLimits(limits) {
@@ -231259,7 +231501,7 @@ async function openBundle(bundlePath, limits) {
   const resolved = resolveLimits(limits);
   let stat;
   try {
-    stat = await lstat24(bundlePath);
+    stat = await lstat25(bundlePath);
   } catch {
     return { ok: false, refusal: { reason: BUNDLE_REFUSAL.notABundle, message: `no such path: ${bundlePath}` } };
   }
@@ -231273,7 +231515,7 @@ async function openBundle(bundlePath, limits) {
       for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
         const abs = path424.join(dir, entry.name);
         const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
-        const entryStat = await lstat24(abs);
+        const entryStat = await lstat25(abs);
         if (entryStat.isSymbolicLink()) {
           return { reason: BUNDLE_REFUSAL.symlinkRefused, path: rel, message: `${rel} is a symlink; bundles may not contain symlinks` };
         }
@@ -232148,7 +232390,7 @@ var init_learned_pattern_schema = __esm(() => {
 
 // src/bundle/export.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { mkdir as mkdir89, readdir as readdir80, readFile as readFile216, writeFile as writeFile63, lstat as lstat25 } from "fs/promises";
+import { mkdir as mkdir89, readdir as readdir80, readFile as readFile216, writeFile as writeFile63, lstat as lstat26 } from "fs/promises";
 import { existsSync as existsSync78 } from "fs";
 import path425 from "path";
 function globToRegExp6(glob) {
@@ -232235,7 +232477,7 @@ async function walkFiles2(dir, relPrefix, out, skipped) {
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     const abs = path425.join(dir, entry.name);
     const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
-    const st = await lstat25(abs);
+    const st = await lstat26(abs);
     if (st.isSymbolicLink()) {
       skipped.push({ path: rel, reason: "symlink" });
       continue;
@@ -232283,7 +232525,7 @@ async function collectAgents(root, skipped) {
   const candidates = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     const abs = path425.join(base, entry.name);
-    const st = await lstat25(abs);
+    const st = await lstat26(abs);
     if (st.isSymbolicLink()) {
       skipped.push({ path: `agents/${entry.name}`, reason: "symlink" });
       continue;
@@ -232308,7 +232550,7 @@ async function collectMemory(root, skipped) {
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       const abs = path425.join(base, entry.name);
-      const st = await lstat25(abs);
+      const st = await lstat26(abs);
       if (st.isSymbolicLink()) {
         skipped.push({ path: `memory/${folder}/${entry.name}`, reason: "symlink" });
         continue;
@@ -232324,7 +232566,7 @@ async function collectHookConfig(root) {
   const abs = path425.join(root, "hooks.json");
   if (!existsSync78(abs))
     return [];
-  const st = await lstat25(abs);
+  const st = await lstat26(abs);
   if (st.isSymbolicLink() || !st.isFile())
     return [];
   return [{ bundlePath: "hooks.json", kind: "hook-config", absolutePath: abs }];
@@ -232705,7 +232947,7 @@ var init_applied_state = __esm(() => {
 });
 
 // src/lib/private-dir.ts
-import { lstat as lstat26, mkdir as mkdir90, open as open12, readFile as readFile218 } from "fs/promises";
+import { lstat as lstat27, mkdir as mkdir90, open as open12, readFile as readFile218 } from "fs/promises";
 import path427 from "path";
 async function checkPrivateDirGitignore(dir, root) {
   if (root !== undefined) {
@@ -232724,7 +232966,7 @@ async function checkPrivateDirGitignore(dir, root) {
   }
   let dirStats;
   try {
-    dirStats = await lstat26(dir);
+    dirStats = await lstat27(dir);
   } catch (error) {
     if (isNotFound(error)) {
       return { ok: true, action: "create" };
@@ -232745,7 +232987,7 @@ async function checkPrivateDirGitignore(dir, root) {
   const gitignorePath = path427.join(dir, ".gitignore");
   let stats;
   try {
-    stats = await lstat26(gitignorePath);
+    stats = await lstat27(gitignorePath);
   } catch (error) {
     if (isNotFound(error)) {
       return { ok: true, action: "create" };

package/dist/core.js

@@ -28739,10 +28739,12 @@ function researchErrors(value, findings) {
     ids.add(id);
     if (!nonempty(o.source) || !nonempty(o.question))
       errors.push(`${id}: source and question are required`);
-    if (!["finding", "refuted", "out-of-scope"].includes(String(o.status)))
+    if (!["finding", "refuted", "out-of-scope", "narrowed"].includes(String(o.status)))
       errors.push(`${id}: unresolved research (${String(o.status)})`);
     if (!nonempty(o.evidence) || !nonempty(o.reason))
       errors.push(`${id}: closure needs evidence and reason`);
+    if (o.status === "narrowed" && !nonempty(o.remains))
+      errors.push(`${id}: narrowed needs a "what remains" text`);
     if (o.status === "finding") {
       const matches = findings.filter((f) => f && typeof f === "object" && (f.id === o.finding || f.global_id === o.finding));
       if (!nonempty(o.finding) || matches.length !== 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.113",
+  "version": "0.3.114",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -207,8 +207,7 @@ keryx review complete <review-id-or-path>
                       [--finding <id> --disposition <state> --evidence <ref>]...
 ```
 
-**An unrecognised option is refused, not ignored** — a misspelled flag exits
-non-zero rather than printing `status: closed` and writing nothing at all.
+**An unrecognised option is refused, not ignored** — a misspelled flag exits non-zero rather than printing `status: closed` and writing nothing at all.
 
 `--verifications` takes what `review-verifier` returned. `--scope` takes the
 whole `--json` output of `keryx review scope`, so the package records what the
@@ -234,9 +233,7 @@ Two channels, and both work:
   it: it is copied into the package it screened and removed from the slot, so a
   later round cannot be screened against a set nobody recomputed.
 
-Do **not** write the record inside the package directory before the ingest. A
-round that names no `--review-id` has not allocated that directory yet, and
-creating it makes the ingest take the next free name instead.
+Do **not** write the record inside the package directory before the ingest. A round that names no `--review-id` has not allocated that directory yet, and creating it makes the ingest take the next free name instead.
 
 `--refuted` takes the findings this round **raised and then dismissed**, in the
 same finding shape, each carrying `disposition: {state, evidence}` with one of
@@ -252,9 +249,12 @@ Everything except `unknown` must cite where the outcome is written down — the
 commit, the test, the decision. A recorded state and its citation cannot be
 overwritten by a later close; record a correction as a new round.
 
-**Closing a fix round without dispositions leaves every finding reading
-`unknown`.** That is not "the reviewers were right"; it is "nobody wrote down
-what happened", and it is the single reason the precision figure cannot be read.
+`review complete` on a PR-bound package refuses a merged PR or a moved head unless `report.md`'s first line names the reviewed SHA and says so; a package with no PR binding is unaffected.
+`review complete` refuses a report with no `Evidence level:` line (`static only — did not run: <what>` or `ran — <what>`); a package ingested before the field existed only warns.
+`review ingest` refuses an internal finding whose `quote` is not at its `path` at the reviewed SHA, and adds a `citation not found` line, never a deletion, to a rebuttal citing a rule or document that is not in the tree.
+A finding may close as `narrowed` (research obligation `"status":"narrowed","remains":"<what remains>"`); it counts as closed only with that text, and the report keeps it under "Refuted and narrowed".
+
+**Closing a fix round without dispositions leaves every finding reading `unknown`.** That is not "the reviewers were right"; it is "nobody wrote down what happened", and it is the single reason the precision figure cannot be read.
 
 Managed modes:
 

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-input.schema.json

@@ -259,6 +259,19 @@
             },
             "additionalProperties": false
           }
+        },
+        "unavailable": {
+          "type": "array",
+          "description": "Sections that could not be read, with the reason. An empty section that is not listed here was read and held nothing.",
+          "items": {
+            "type": "object",
+            "required": ["section", "reason"],
+            "properties": {
+              "section": { "enum": ["affected", "wiki", "memory"] },
+              "reason": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
         }
       },
       "additionalProperties": false

package/src/gdskills/bundled/skills/review/review-orchestrator/templates/review-report.md

@@ -34,8 +34,10 @@ what a reader must act on; everything else is folded.
 
 ```markdown
 <!-- slot:pre-verdict -->
+<only when the PR merged or its head moved: "Reviewed `<sha>` — the PR has since merged / moved on to `<new sha>`." as the very first line>
 **Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** <what holds, and where the risk is — one sentence.>
 Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del> · CI <green | red: check names>.
+Evidence level: <static only — did not run: tests, build | ran — the commands that ran>
 <!-- slot:after-verdict -->
 
 ### Prior findings            (fix rounds only)
@@ -43,6 +45,7 @@ Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del>
 ### Major
 ### Minor
 ### Questions
+### Refuted and narrowed      (only when a finding was dismissed or narrowed)
 
 <details><summary><b>Pre-existing (not blocking)</b></summary> … </details>
 <details><summary><b>Scope</b></summary> … </details>          (only when a pr-process note exists)
@@ -68,6 +71,25 @@ author answer, rendered under Questions, not as a finding.
 The second line is the context line: head, base, round, size, CI. If head moved
 during the round, add `· unchecked: <commits>`.
 
+The third line is the **evidence level** and is required: `Evidence level: static
+only — did not run: <what>` when nothing was executed, or `Evidence level: ran —
+<what ran>`. `keryx review complete` refuses a report without it.
+
+When the PR was merged or its head moved after the review, the report's first line
+says so and names the reviewed SHA, or `keryx review complete` refuses.
+
+### Refuted and narrowed
+
+One line per finding that did not stand as reported, kept with its evidence so a
+reader sees what was claimed and why it was set aside:
+
+```markdown
+- **F-007. Dismissed** — <the author's rebuttal, quoted>. <citation not found: …> where the cited rule is not in the tree.
+- **F-009. Narrowed** — <what the finding claimed>. **Remains:** <what is still open>. Evidence: <what was run>.
+```
+
+A narrowed finding counts as closed only with its "Remains" text.
+
 ## One finding
 
 Blocker and Major as a paragraph, visible: