@attalabs/vinaya 0.22.0 → 0.24.0

package/dist/checks/bin/check-coherence.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/checks/bin/check-coherence.ts
 import { execFile as execFile4, execFileSync as execFileSync3 } from "node:child_process";
@@ -213,17 +215,18 @@ function splitIds(raw) {
     return [];
   return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0 && !isEmptyMarker(s) && ID_TOKEN.test(s));
 }
-function resolveIds(raw, lastSlug) {
+function resolveIds(raw) {
   const ids = splitIds(raw);
   const resolved = [];
+  let lastSlug = null;
   for (const id of ids) {
     const qualified = id.match(SLUG_QUALIFIED_ID);
     if (qualified) {
-      lastSlug.current = qualified[1] ?? null;
+      lastSlug = qualified[1] ?? null;
       resolved.push(id);
-    } else if (lastSlug.current) {
-      resolved.push(`${lastSlug.current} ${id}`);
-      lastSlug.current = null;
+    } else if (lastSlug) {
+      resolved.push(`${lastSlug} ${id}`);
+      lastSlug = null;
     } else {
       resolved.push(id);
     }
@@ -243,12 +246,7 @@ function parseRationaleDeps(body) {
   const section = extractSection(body);
   const dependsOn = [];
   const conflictsWith = [];
-  let current = null;
   const assignedFields = new Set;
-  const lastSlugByField = {
-    dependsOn: { current: null },
-    conflictsWith: { current: null }
-  };
   const spanPattern = /`([^`]*)`/g;
   let match = spanPattern.exec(section);
   while (match !== null) {
@@ -258,13 +256,9 @@ function parseRationaleDeps(body) {
       const field = labelMatch[1]?.toLowerCase() === "conflicts-with" ? "conflictsWith" : "dependsOn";
       if (!assignedFields.has(field)) {
         assignedFields.add(field);
-        current = field;
-        const ids = resolveIds(labelMatch[2] ?? "", lastSlugByField[field]);
+        const ids = resolveIds(labelMatch[2] ?? "");
         pushUnique(field === "dependsOn" ? dependsOn : conflictsWith, ids);
       }
-    } else if (current) {
-      const ids = resolveIds(content, lastSlugByField[current]);
-      pushUnique(current === "dependsOn" ? dependsOn : conflictsWith, ids);
     }
     match = spanPattern.exec(section);
   }
@@ -1729,6 +1723,48 @@ function splitTableRow(row) {
     parts.pop();
   return parts.map((p) => p.split(PLACEHOLDER).join("|"));
 }
+// ../../packages/aeg-core/src/blast-radius-domains.ts
+function resolveWorkspaceEntry(entry2, listDirs) {
+  if (entry2.endsWith("/*")) {
+    const baseDir = entry2.slice(0, -2);
+    return listDirs(baseDir).map((name) => `${baseDir}/${name}`);
+  }
+  if (entry2.includes("*"))
+    return [];
+  return [entry2];
+}
+// ../../packages/aeg-core/src/consumer-enumeration.ts
+function deriveWorkspaceMemberDirs(workspaces, listDirs) {
+  const positive = workspaces.filter((entry2) => !entry2.startsWith("!"));
+  const negative = workspaces.filter((entry2) => entry2.startsWith("!")).map((entry2) => entry2.slice(1));
+  const excluded = new Set;
+  for (const entry2 of negative) {
+    for (const member of resolveWorkspaceEntry(entry2, listDirs))
+      excluded.add(member);
+  }
+  const members = new Set;
+  for (const entry2 of positive) {
+    for (const member of resolveWorkspaceEntry(entry2, listDirs)) {
+      if (!excluded.has(member))
+        members.add(member);
+    }
+  }
+  return [...members].sort();
+}
+function buildConsumersOf(workspaces, listDirs, readManifest) {
+  const members = deriveWorkspaceMemberDirs(workspaces, listDirs);
+  return (pkg) => {
+    const target = `@attalabs/${pkg}`;
+    return members.filter((dir) => {
+      if (dir === `packages/${pkg}`)
+        return false;
+      const manifest = readManifest(dir);
+      if (!manifest)
+        return false;
+      return target in (manifest.dependencies ?? {}) || target in (manifest.devDependencies ?? {});
+    });
+  };
+}
 // ../../packages/aeg-core/src/state-machine-model.ts
 var FORGE_FACT_INPUTS = [
   {
@@ -1833,6 +1869,22 @@ function isEmDashOrDash(s) {
   const t = s.trim();
   return t === "—" || t === "-" || t === "–";
 }
+// ../../packages/aeg-core/src/waiver-label.ts
+var WAIVER_LABEL = label("waiver-docs");
+var WAIVER_LABEL_REVIEW = label("waiver-review");
+var PRINCIPAL_ALLOWLIST = ["daniboomerang"];
+function isPrincipal(login, principalAllowlist) {
+  if (login === null)
+    return false;
+  const normalized = login.toLowerCase();
+  return principalAllowlist.some((p) => p.toLowerCase() === normalized);
+}
+function isWaiverLabelActorVerified(opts) {
+  if (!opts.labels.includes(opts.label))
+    return false;
+  return isPrincipal(opts.labelActor, opts.principalAllowlist);
+}
+
 // ../../packages/aeg-core/src/parse-token-report.ts
 var TOKEN_REPORT_HEADING = /^\s*(?:#{1,6}\s*Token report\s*|\*\*Token report\*\*)\s*$/i;
 var INLINE_FIELD_LIST = /Phase:\s*([^|]+?)\s*\|\s*Role:\s*([^|]+?)\s*\|\s*Agent\/Model:\s*([^|]+?)\s*\|\s*Tokens in:\s*([^|]+?)\s*\|\s*Tokens out:\s*([^|]+?)\s*\|\s*Cost:\s*([^|]+?)\s*\|\s*Date:\s*(.+?)\s*$/im;
@@ -1887,6 +1939,47 @@ function parseInlineFieldList(section) {
     return null;
   return rowFromCells([m[1], m[2], m[3], m[4], m[5], m[6], m[7]]);
 }
+// ../../packages/aeg-core/src/verdict-extraction.ts
+var HEAD_SHA_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Judged head:\s*([0-9a-f]{7,40})(?![A-Za-z0-9])/im;
+function firstThreeLines(comment) {
+  return comment.split(`
+`).slice(0, 3).join(`
+`);
+}
+function extractHeadSha(comment) {
+  const m = firstThreeLines(comment).match(HEAD_SHA_PATTERN);
+  return m ? m[1].toLowerCase() : null;
+}
+function extractVerdict(comments, valuePattern, missingLabel) {
+  const candidates = comments.filter((c) => valuePattern.test(c));
+  if (candidates.length === 0) {
+    return {
+      value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
+      headSha: null,
+      danglingNote: `no ${missingLabel} verdict comment found on this PR`
+    };
+  }
+  const latest = candidates[candidates.length - 1];
+  const m = firstThreeLines(latest).match(valuePattern);
+  if (!m) {
+    return {
+      value: `the most recent ${missingLabel} comment's VERDICT line is not within its first three lines — DANGLING, see below`,
+      headSha: null,
+      danglingNote: `the most recent ${missingLabel} verdict comment carries a VERDICT-shaped line outside the first-three-line read window`
+    };
+  }
+  return {
+    value: m[1].toUpperCase().replace(/[_-]/g, " "),
+    headSha: extractHeadSha(latest),
+    danglingNote: null
+  };
+}
+function extractCodeReviewVerdict(comments) {
+  return extractVerdict(comments, /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(APPROVE|REQUEST[ _-]?CHANGES|LGTM)(?![A-Za-z0-9])/im, "code-reviewer");
+}
+function extractSecurityReviewVerdict(comments) {
+  return extractVerdict(comments, /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(PASS|FAIL)(?![A-Za-z0-9])/im, "security-review");
+}
 // ../../packages/aeg-core/src/report-tokens.ts
 var DASH_LOOKALIKES = {
   "-": "‑",
@@ -2051,22 +2144,6 @@ function isCodeFile(p) {
     return false;
   return /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|sql|css)$/.test(p);
 }
-// ../../packages/aeg-core/src/waiver-label.ts
-var WAIVER_LABEL = label("waiver-docs");
-var WAIVER_LABEL_REVIEW = label("waiver-review");
-var PRINCIPAL_ALLOWLIST = ["daniboomerang"];
-function isPrincipal(login, principalAllowlist) {
-  if (login === null)
-    return false;
-  const normalized = login.toLowerCase();
-  return principalAllowlist.some((p) => p.toLowerCase() === normalized);
-}
-function isWaiverLabelActorVerified(opts) {
-  if (!opts.labels.includes(opts.label))
-    return false;
-  return isPrincipal(opts.labelActor, opts.principalAllowlist);
-}
-
 // ../../packages/aeg-core/src/doc-owners.ts
 var DOC_OWNERS_PATH = ".vinaya/doc-owners";
 function parseDocOwners(content) {
@@ -2283,6 +2360,32 @@ function parsePremiseBlock(prBody) {
   }
   return assertions;
 }
+function premiseBlockText(prBody) {
+  const searchIn = anchoredRegion(prBody, "PREMISE") ?? prBody;
+  const lines = searchIn.split(/\r?\n/);
+  let startIdx = -1;
+  let endIdxExclusive = lines.length;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (startIdx === -1) {
+      if (isPremiseHeader(line))
+        startIdx = i;
+      continue;
+    }
+    if (line === "") {
+      endIdxExclusive = i;
+      break;
+    }
+    if (!PREMISE_LINE.test(line)) {
+      endIdxExclusive = i;
+      break;
+    }
+  }
+  if (startIdx === -1)
+    return null;
+  return lines.slice(startIdx, endIdxExclusive).join(`
+`);
+}
 function checkPremises(assertions, fileReader) {
   const failures = [];
   for (const a of assertions) {
@@ -2369,15 +2472,18 @@ function testPlanRegion(prBody) {
   return located.found ? located.section : prBody;
 }
 function checkTestPlan(prBody) {
-  const region = testPlanRegion(prBody);
+  const located = locateTestPlanSection(prBody);
+  const region = located.found ? located.section : prBody;
   if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
   if (/\*\*\[(?:agent|principal)\]\*\*/.test(region))
     return { status: "pass", errors: [] };
+  if (located.found && extractFencedBlocks(region).length > 0)
+    return { status: "pass", errors: [] };
   return {
     status: "fail",
     errors: [
-      "brief-validation Test Plan: no Test Plan section found — expected `Test Plan: unit-tests-only`, or at least one `**[agent]**`/`**[principal]**`-tagged checklist item."
+      "brief-validation Test Plan: no Test Plan section found — expected `Test Plan: unit-tests-only`, a fenced `[agent]` command list, or at least one `**[agent]**`/`**[principal]**`-tagged checklist item."
     ]
   };
 }
@@ -2500,8 +2606,162 @@ function isBriefShaped(prBody) {
   const stripped = stripCode(prBody);
   return BRIEF_SHAPE_MARKERS.filter((check) => check(stripped).status === "pass").length >= 2;
 }
+var COMMAND_WORDS = ["export", "bun", "gh", "git", "grep", "sed", "cat", "diff", "vinaya"];
+var BRIEF_RULES_SINCE_PR = 394;
+var AGENT_BOXES_REFUSED_SINCE_PR = 396;
+var AGENT_BOX_LINE_RE = /^-\s*\[[ xX]\]\s*\*{2}\[agent\]\*{2}/im;
+function checkNoAgentBoxes(prBody) {
+  const region = testPlanRegion(prBody);
+  if (!AGENT_BOX_LINE_RE.test(region))
+    return { status: "pass", errors: [] };
+  return {
+    status: "fail",
+    errors: [
+      "brief-validation no agent boxes: the Test Plan carries a checkbox `[agent]` item — an agent never ticks a box or edits a PR body (Principal ruling, 2026-09-03, after PR #395). Render the `[agent]` half as a fenced command list instead; `vinaya pr report` runs each command from the PR head and writes its actual output into the AEG:EVIDENCE block. `[principal]` checkboxes are unaffected."
+    ]
+  };
+}
+function rolloutThresholdFor(message) {
+  if (message.startsWith("brief-validation unpinned code claim:") || message.startsWith("brief-validation commands carry output:") || message.startsWith("brief-validation consumer tests:") || message.startsWith("brief-validation defeat cases:")) {
+    return BRIEF_RULES_SINCE_PR;
+  }
+  if (message.startsWith("brief-validation no agent boxes:"))
+    return AGENT_BOXES_REFUSED_SINCE_PR;
+  return null;
+}
+function partitionBriefErrorsByRollout(errors, prNumber) {
+  const blocking = [];
+  const info = [];
+  for (const e of errors) {
+    const threshold = rolloutThresholdFor(e);
+    const grandfathered = threshold !== null && prNumber !== null && prNumber < threshold;
+    (grandfathered ? info : blocking).push(e);
+  }
+  return { blocking, info };
+}
+function extractFencedBlocks(text) {
+  const re = /^[ \t]*(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)^[ \t]*\1[ \t]*$/gm;
+  const blocks = [];
+  let m = re.exec(text);
+  while (m !== null) {
+    const lang = m[2].trim().toLowerCase().split(/\s+/)[0] ?? "";
+    blocks.push({ start: m.index, end: m.index + m[0].length, lang, content: m[3] });
+    m = re.exec(text);
+  }
+  return blocks;
+}
+function firstNonBlankLine(text) {
+  const line = text.split(`
+`).find((l) => l.trim().length > 0);
+  return line?.trim() ?? "";
+}
+var FILE_LINE_RE = /\b[\w./-]+\.(?:tsx?|jsx?|mjs|cjs|md|mdx|json|ya?ml|sh|py|toml):\d+\b/g;
+function checkNoUnpinnedCodeClaims(prBody) {
+  const premiseText = premiseBlockText(prBody);
+  const withoutPremise = premiseText ? prBody.replace(premiseText, "") : prBody;
+  const scanned = stripCode(withoutPremise, { inlineSpans: "keep" });
+  const matches = scanned.match(FILE_LINE_RE) ?? [];
+  if (matches.length === 0)
+    return { status: "pass", errors: [] };
+  return {
+    status: "fail",
+    errors: matches.map((m) => `brief-validation unpinned code claim: "${m}" states a code fact by file-and-line reference outside a \`Premise:\` pin and outside a fenced code block — pin it in \`Premise:\`, or show the executed command and its output instead.`)
+  };
+}
+function extractNumberedSection(prBody, num) {
+  const startRe = new RegExp(`^#{1,4}\\s*(?:\\*\\*)?${num}[a-z]?\\.\\s`, "im");
+  const start = startRe.exec(prBody);
+  if (!start)
+    return null;
+  const afterStart = start.index + start[0].length;
+  const rest = prBody.slice(afterStart);
+  const next = /^#{1,4}\s/m.exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+}
+function commandWordOf(line) {
+  return line.trim().split(/\s+/)[0] ?? "";
+}
+function isCommandBlock(content) {
+  return COMMAND_WORDS.includes(commandWordOf(firstNonBlankLine(content)));
+}
+function isStep0Block(content) {
+  return firstNonBlankLine(content).startsWith("git worktree add");
+}
+function checkCommandsCarryOutput(prBody) {
+  const errors = [];
+  for (const [label2, num] of [
+    ["5", 5],
+    ["6", 6]
+  ]) {
+    const section = extractNumberedSection(prBody, num);
+    if (!section)
+      continue;
+    const blocks = extractFencedBlocks(section);
+    for (let i = 0;i < blocks.length; i++) {
+      const block = blocks[i];
+      if (isStep0Block(block.content) || !isCommandBlock(block.content))
+        continue;
+      const next = blocks[i + 1];
+      if (!next || isCommandBlock(next.content)) {
+        errors.push(`brief-validation commands carry output: §${label2} has a command block ("${firstNonBlankLine(block.content)}") not immediately followed by a non-command output block — the very next fenced block must hold that command's actual output, not another command.`);
+      }
+    }
+  }
+  return errors.length === 0 ? { status: "pass", errors: [] } : { status: "fail", errors };
+}
+var CONSUMER_TESTS_SENTINEL_RE = /consumer-tests\s*:\s*none\s*[-—–]\s*\S/i;
+function packagesNamedIn(text) {
+  const re = /\bpackages\/([A-Za-z0-9_-]+)\//g;
+  const pkgs = new Set;
+  let m = re.exec(text);
+  while (m !== null) {
+    pkgs.add(m[1]);
+    m = re.exec(text);
+  }
+  return [...pkgs];
+}
+function hasTestPathForConsumer(text, consumerDir) {
+  const escaped = consumerDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`${escaped}\\/[\\w./-]*\\.test\\.[A-Za-z0-9]+`);
+  return re.test(text);
+}
+function checkConsumerTests(prBody, consumersOf) {
+  const section4 = extractNumberedSection(prBody, 4);
+  if (!section4)
+    return { status: "pass", errors: [] };
+  if (CONSUMER_TESTS_SENTINEL_RE.test(section4))
+    return { status: "pass", errors: [] };
+  const errors = [];
+  for (const pkg of packagesNamedIn(section4)) {
+    for (const consumerDir of consumersOf(pkg)) {
+      if (hasTestPathForConsumer(section4, consumerDir))
+        continue;
+      errors.push(`brief-validation consumer tests: §4 names a path under packages/${pkg}/, and ${consumerDir} depends on @attalabs/${pkg}, but no test path under ${consumerDir} is named in §4 — name one, or add \`consumer-tests: none — <reason>\`.`);
+    }
+  }
+  return errors.length === 0 ? { status: "pass", errors: [] } : { status: "fail", errors };
+}
+var CHECK_NAME_RE = /\bcheck-[a-z0-9-]+(?:\.ts)?\b/;
+var FORGE_WRITE_COMMAND_RE = /\bgh\s+(?:pr|issue)\s+(?:create|merge|close|comment|edit|review)\b|\bgit\s+push\b|\bvinaya\s+pr\s+(?:create|report\s+--write)\b/i;
+var DEFEAT_CASES_RE = /defeat cases\s*:/i;
+function checkDefeatCases(prBody) {
+  const section4 = extractNumberedSection(prBody, 4);
+  if (!section4)
+    return { status: "pass", errors: [] };
+  if (!CHECK_NAME_RE.test(section4) && !FORGE_WRITE_COMMAND_RE.test(section4))
+    return { status: "pass", errors: [] };
+  const section6 = extractNumberedSection(prBody, 6) ?? "";
+  if (DEFEAT_CASES_RE.test(section6))
+    return { status: "pass", errors: [] };
+  return {
+    status: "fail",
+    errors: [
+      "brief-validation defeat cases: §4 names a check or a forge-writing command, but §6 carries no `Defeat cases:` line — name the inputs that would defeat this check, or that this command must not accidentally trigger on."
+    ]
+  };
+}
 function checkBriefSections(prBody, readTier, options = {}) {
-  const { requireClosesN = true } = options;
+  const { requireClosesN = true, consumersOf = () => [] } = options;
   const results = [
     checkTierField(prBody, readTier),
     checkTestPlan(prBody),
@@ -2514,10 +2774,219 @@ function checkBriefSections(prBody, readTier, options = {}) {
     checkAutonomyClause(prBody),
     checkProjectField(prBody),
     checkForField(prBody),
+    checkNoUnpinnedCodeClaims(prBody),
+    checkNoAgentBoxes(prBody),
+    checkCommandsCarryOutput(prBody),
+    checkConsumerTests(prBody, consumersOf),
+    checkDefeatCases(prBody),
     ...requireClosesN ? [checkClosesN(prBody)] : []
   ];
   return { errors: results.flatMap((r) => r.errors) };
 }
+// ../../packages/aeg-core/src/doctrine-portability.ts
+var DEFAULT_SHIPS_PREFIX = "aeg-root/";
+var STATIC_PORTABLE_PREFIXES = [
+  "roles/",
+  "contracts/",
+  "skills/",
+  ".github/",
+  ".vinaya/",
+  ".claude/",
+  ".git/",
+  ".husky/"
+];
+var EXEMPT_LITERALS = new Set([
+  "path/inside/the/shipped/diff.ts",
+  "path/inside/the/surface.ts",
+  "apps/x/specs/..."
+]);
+var CITED_PATH_PATTERN = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]*)+$/;
+var NON_PATH_TOP_SEGMENTS = new Set(["origin", "refs", "HEAD", "vinaya", "fix"]);
+var VENDOR_NAME_SOURCE = "\\bclaude code\\b|\\bclaude\\b|\\banthropic\\b|\\bchatgpt\\b|\\bopenai\\b|\\bgpt\\b|\\bgemini\\b|\\bcodex\\b|\\bgrok\\b|\\bdeepseek\\b|\\bopus\\b|\\bsonnet\\b|\\bhaiku\\b";
+var VENDOR_EXAMPLE_START = /<!--\s*AEG:VENDOR-EXAMPLE:START\s*-->/;
+var VENDOR_EXAMPLE_END = /<!--\s*AEG:VENDOR-EXAMPLE:END\s*-->/;
+function maskVendorExampleRegion(masked) {
+  const start = VENDOR_EXAMPLE_START.exec(masked);
+  if (!start)
+    return masked;
+  const afterStart = start.index + start[0].length;
+  const end = VENDOR_EXAMPLE_END.exec(masked.slice(afterStart));
+  if (!end)
+    return masked;
+  const regionEnd = afterStart + end.index + end[0].length;
+  const region = masked.slice(start.index, regionEnd);
+  const blanked = region.replace(/[^\n]/g, " ");
+  return masked.slice(0, start.index) + blanked + masked.slice(regionEnd);
+}
+function extractVendorMentions(content) {
+  const scoped = maskVendorExampleRegion(maskCode(content));
+  const found = [];
+  const pattern = new RegExp(VENDOR_NAME_SOURCE, "gi");
+  let match = pattern.exec(scoped);
+  while (match !== null) {
+    found.push({ name: match[0], index: match.index });
+    match = pattern.exec(scoped);
+  }
+  return found;
+}
+function extractCitedPaths(content) {
+  const found = [];
+  const spanPattern = /`([^`\n]+)`/g;
+  let match = spanPattern.exec(content);
+  while (match !== null) {
+    const cited = match[1] ?? "";
+    const topSegment = cited.slice(0, cited.indexOf("/"));
+    if (CITED_PATH_PATTERN.test(cited) && !NON_PATH_TOP_SEGMENTS.has(topSegment)) {
+      found.push({ cited, index: match.index });
+    }
+    match = spanPattern.exec(content);
+  }
+  return found;
+}
+function lineAtIndex(content, index) {
+  let line = 1;
+  for (let i = 0;i < index; i++) {
+    if (content.charCodeAt(i) === 10)
+      line++;
+  }
+  return line;
+}
+function isPortable(cited, shipsPrefix) {
+  if (cited.startsWith(shipsPrefix))
+    return true;
+  return STATIC_PORTABLE_PREFIXES.some((prefix) => cited.startsWith(prefix));
+}
+function checkDoctrinePortability(files, shipsPrefix = DEFAULT_SHIPS_PREFIX) {
+  const findings = [];
+  for (const file of files) {
+    if (!file.path.startsWith(shipsPrefix))
+      continue;
+    for (const { cited, index } of extractCitedPaths(file.content)) {
+      if (EXEMPT_LITERALS.has(cited))
+        continue;
+      if (isPortable(cited, shipsPrefix))
+        continue;
+      findings.push({
+        file: file.path,
+        line: lineAtIndex(file.content, index),
+        cited,
+        message: `cites "${cited}", a path that only exists in the authoring repository — not portable doctrine`,
+        kind: "path"
+      });
+    }
+    for (const { name, index } of extractVendorMentions(file.content)) {
+      findings.push({
+        file: file.path,
+        line: lineAtIndex(file.content, index),
+        cited: name,
+        message: `names "${name}" outside the one fenced vendor-example home (an <!-- AEG:VENDOR-EXAMPLE:START --> … <!-- AEG:VENDOR-EXAMPLE:END --> pair) — portable doctrine refers to a host generically everywhere else`,
+        kind: "vendor-name"
+      });
+    }
+  }
+  return findings;
+}
+
+// ../../packages/aeg-core/src/doctrine-no-procedures.ts
+function vendorExampleSpan(content) {
+  const start = VENDOR_EXAMPLE_START.exec(content);
+  if (!start)
+    return null;
+  const afterStart = start.index + start[0].length;
+  const end = VENDOR_EXAMPLE_END.exec(content.slice(afterStart));
+  if (!end)
+    return null;
+  return { start: start.index, end: afterStart + end.index + end[0].length };
+}
+function isCommandLine(line) {
+  const word = line.trim().split(/\s+/)[0] ?? "";
+  return COMMAND_WORDS.includes(word);
+}
+var SHELL_LANGS = new Set(["", "sh", "bash", "shell", "console"]);
+function procedureLineNumberAt(content, index) {
+  return content.slice(0, index).split(`
+`).length;
+}
+function isTemplatePath(path) {
+  return /(^|\/)templates\//.test(path);
+}
+function checkDoctrineNoProcedures(files) {
+  const findings = [];
+  for (const file of files) {
+    if (isTemplatePath(file.path))
+      continue;
+    const span = vendorExampleSpan(file.content);
+    for (const block of extractFencedBlocks(file.content)) {
+      if (span && block.start >= span.start && block.end <= span.end)
+        continue;
+      if (!SHELL_LANGS.has(block.lang))
+        continue;
+      const commandLineCount = block.content.split(`
+`).filter(isCommandLine).length;
+      if (commandLineCount >= 2) {
+        findings.push({
+          file: file.path,
+          line: procedureLineNumberAt(file.content, block.start),
+          message: `this fenced block has ${commandLineCount} shell-command lines — this sequence is a \`vinaya\` command, name it (or move it inside the \`AEG:VENDOR-EXAMPLE\` anchor / a \`templates/\` file).`
+        });
+      }
+    }
+  }
+  return findings;
+}
+// ../../packages/aeg-core/src/pr-report-density.ts
+function headingSectionBody(prBody, heading) {
+  const headingRe = new RegExp(`^##\\s+${heading}\\s*$`, "im");
+  const m = headingRe.exec(prBody);
+  if (!m)
+    return null;
+  const start = m.index + m[0].length;
+  const rest = prBody.slice(start);
+  const nextHeading = /^#{1,2}\s/m.exec(rest);
+  return nextHeading ? rest.slice(0, nextHeading.index) : rest;
+}
+function stripAnchorBlocks(sectionText) {
+  let result = sectionText;
+  for (const field of ["CLOSES", "PROJECT", "TIER", "PREMISE", "TEST-PLAN", "EVIDENCE"]) {
+    for (;; ) {
+      const bounds = anchoredRegionBounds(result, field);
+      if (!bounds)
+        break;
+      result = result.slice(0, bounds.outerStart) + result.slice(bounds.outerEnd);
+    }
+  }
+  return result;
+}
+function paragraphCount(sectionText) {
+  const stripped = stripCode(stripAnchorBlocks(sectionText)).trim();
+  if (stripped.length === 0)
+    return 0;
+  return stripped.split(/\n[ \t]*\n/).map((block) => block.trim()).filter((block) => block.length > 0).length;
+}
+function checkSectionDensity(prBody, heading) {
+  const body = headingSectionBody(prBody, heading);
+  if (body === null)
+    return { status: "pass", errors: [] };
+  const count = paragraphCount(body);
+  if (count <= 1)
+    return { status: "pass", errors: [] };
+  return {
+    status: "fail",
+    errors: [
+      `pr-report-density ${heading}: "## ${heading}" holds ${count} paragraphs — the canonical PR-report form (aeg-root/roles/developer.md § PR body) requires exactly one. Collapse it to one paragraph; move the rest into a section of your own below the canonical four ("Add anything you want beneath the four sections", developer.md), a commit message, or the changeset — never into the AEG:EVIDENCE block, which is emitted only, never hand-typed.`
+    ]
+  };
+}
+function checkSummaryDensity(prBody) {
+  return checkSectionDensity(prBody, "Summary");
+}
+function checkScopeDensity(prBody) {
+  return checkSectionDensity(prBody, "Scope");
+}
+function checkPrReportDensity(prBody) {
+  const results = [checkSummaryDensity(prBody), checkScopeDensity(prBody)];
+  return { errors: results.flatMap((r) => r.errors) };
+}
 // ../../packages/aeg-core/src/issue-validation.ts
 function hasRationaleField(body, labelPattern) {
   const re = new RegExp(`(?:\\*\\*|^#{1,4}\\s+)\\s*(?:${labelPattern})`, "im");
@@ -2769,6 +3238,17 @@ function checkD1(entries, issueToEntry, taskToEntry) {
       const depEntry = resolveDepEntry(dep, e.trancheSlug, issueToEntry, taskToEntry);
       if (!depEntry)
         continue;
+      const sameTask = depEntry.trancheSlug === e.trancheSlug && depEntry.task.id === e.task.id;
+      const sameIssue = depEntry.task.issue !== null && e.task.issue !== null && depEntry.task.issue === e.task.issue;
+      if (sameTask || sameIssue) {
+        failures.push({
+          issue: e.task.issue,
+          tranche: e.trancheSlug,
+          task: e.task.id,
+          reason: `INTERNAL: parsed a self-dependency (depends-on ${dep}) — this is a parser bug in parseRationaleDeps, not a real dependency. Please report it upstream.`
+        });
+        continue;
+      }
       const depFacts = depEntry.facts;
       const depClosed = depFacts?.issueState === "closed";
       if (!depClosed) {
@@ -2912,41 +3392,24 @@ function checkClosesN2(branch, prBody, trancheFiles, taskIssueRefs) {
   }
   return { ok: true, expectedIssue };
 }
-// ../../packages/aeg-core/src/verdict-extraction.ts
-var HEAD_SHA_PATTERN = /^[ \t]*(?:\*{1,3}|_{1,3})?Judged head:\s*([0-9a-f]{7,40})(?![A-Za-z0-9])/im;
-function extractHeadSha(comment) {
-  const m = comment.match(HEAD_SHA_PATTERN);
-  return m ? m[1].toLowerCase() : null;
-}
-function extractVerdict(comments, valuePattern, missingLabel) {
-  const clearHits = comments.filter((c) => valuePattern.test(c));
-  if (clearHits.length > 0) {
-    const latest = clearHits[clearHits.length - 1];
-    const m = latest.match(valuePattern);
-    return {
-      value: m[1].toUpperCase().replace(/[_-]/g, " "),
-      headSha: extractHeadSha(latest),
-      danglingNote: null
-    };
-  }
-  return {
-    value: `no ${missingLabel} pass was run before merge — DANGLING, see below`,
-    headSha: null,
-    danglingNote: `no ${missingLabel} verdict comment found on this PR`
-  };
-}
-function extractCodeReviewVerdict(comments) {
-  return extractVerdict(comments, /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(APPROVE|REQUEST[ _-]?CHANGES|LGTM)(?![A-Za-z0-9])/im, "code-reviewer");
-}
-function extractSecurityReviewVerdict(comments) {
-  return extractVerdict(comments, /^[ \t]*(?:\*{1,3}|_{1,3})?VERDICT:\s*(PASS|FAIL)(?![A-Za-z0-9])/im, "security-review");
-}
 // ../../packages/aeg-core/src/review-gate.ts
 function isBoundToHead(extraction, headSha) {
   if (!extraction.headSha)
     return false;
   return headSha.toLowerCase().startsWith(extraction.headSha.toLowerCase());
 }
+function isBoundByPatchIdentity(extraction, headSha, patchIdOf) {
+  if (patchIdOf === undefined || !extraction.headSha)
+    return false;
+  const judged = patchIdOf(extraction.headSha);
+  const current = patchIdOf(headSha);
+  if (judged === null || current === null)
+    return false;
+  return judged === current;
+}
+function isBoundToPatch(extraction, headSha, patchIdOf) {
+  return isBoundToHead(extraction, headSha) || isBoundByPatchIdentity(extraction, headSha, patchIdOf);
+}
 function checkReviewGate(input) {
   const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST;
   const waived = isWaiverLabelActorVerified({
@@ -2962,6 +3425,8 @@ function checkReviewGate(input) {
       waived: true
     };
   }
+  const reportedMechanicalChecks = input.mechanicalChecks.filter((c) => c.bucket !== "skipping" && c.bucket !== "neutral");
+  const mechanicalChecksClean = reportedMechanicalChecks.length > 0 && reportedMechanicalChecks.every((c) => c.bucket === "pass");
   const verified = input.comments.filter((c) => isPrincipal(c.author, principalAllowlist));
   const ignoredCount = input.comments.filter((c) => !isPrincipal(c.author, principalAllowlist) && c.body.includes("VERDICT")).length;
   const verifiedBodies = verified.map((c) => c.body);
@@ -2969,12 +3434,12 @@ function checkReviewGate(input) {
   const security = extractSecurityReviewVerdict(verifiedBodies);
   const codeReviewClean = codeReview.value === "APPROVE";
   const securityClean = security.value === "PASS";
-  const codeReviewBound = isBoundToHead(codeReview, input.headSha);
-  const securityBound = isBoundToHead(security, input.headSha);
-  if (codeReviewClean && codeReviewBound && securityClean && securityBound) {
+  const codeReviewBound = isBoundToPatch(codeReview, input.headSha, input.patchIdOf);
+  const securityBound = isBoundToPatch(security, input.headSha, input.patchIdOf);
+  if (codeReviewClean && codeReviewBound && securityClean && securityBound && mechanicalChecksClean) {
     return {
       verdict: "pass",
-      reason: `code-reviewer verdict is a clean APPROVE and security-review verdict is a clean PASS, both covering head ${input.headSha}.`,
+      reason: `code-reviewer verdict is a clean APPROVE and security-review verdict is a clean PASS, both covering head ${input.headSha}, and every reported mechanical check is green.`,
       waived: false
     };
   }
@@ -2989,6 +3454,9 @@ function checkReviewGate(input) {
   } else if (!securityBound) {
     problems.push(`the newest security-review verdict covers ${security.headSha ?? "no recorded commit"}, head is ${input.headSha}`);
   }
+  if (!mechanicalChecksClean) {
+    problems.push(reportedMechanicalChecks.length === 0 ? "no mechanical checks have reported for this head yet" : `mechanical check(s) not green: ${reportedMechanicalChecks.filter((c) => c.bucket !== "pass").map((c) => `${c.name} (${c.bucket})`).join(", ")}`);
+  }
   const ignoredNote = ignoredCount > 0 ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.` : "";
   return {
     verdict: "fail",
@@ -3268,72 +3736,6 @@ function compareToBaseline(current, baseline) {
     perTool
   };
 }
-// ../../packages/aeg-core/src/doctrine-portability.ts
-var DEFAULT_SHIPS_PREFIX = "aeg-root/";
-var STATIC_PORTABLE_PREFIXES = [
-  "roles/",
-  "contracts/",
-  "skills/",
-  ".github/",
-  ".vinaya/",
-  ".claude/",
-  ".git/",
-  ".husky/"
-];
-var EXEMPT_LITERALS = new Set([
-  "path/inside/the/shipped/diff.ts",
-  "path/inside/the/surface.ts",
-  "apps/x/specs/..."
-]);
-var CITED_PATH_PATTERN = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]*)+$/;
-var NON_PATH_TOP_SEGMENTS = new Set(["origin", "refs", "HEAD", "vinaya", "fix"]);
-function extractCitedPaths(content) {
-  const found = [];
-  const spanPattern = /`([^`\n]+)`/g;
-  let match = spanPattern.exec(content);
-  while (match !== null) {
-    const cited = match[1] ?? "";
-    const topSegment = cited.slice(0, cited.indexOf("/"));
-    if (CITED_PATH_PATTERN.test(cited) && !NON_PATH_TOP_SEGMENTS.has(topSegment)) {
-      found.push({ cited, index: match.index });
-    }
-    match = spanPattern.exec(content);
-  }
-  return found;
-}
-function lineAtIndex(content, index) {
-  let line = 1;
-  for (let i = 0;i < index; i++) {
-    if (content.charCodeAt(i) === 10)
-      line++;
-  }
-  return line;
-}
-function isPortable(cited, shipsPrefix) {
-  if (cited.startsWith(shipsPrefix))
-    return true;
-  return STATIC_PORTABLE_PREFIXES.some((prefix) => cited.startsWith(prefix));
-}
-function checkDoctrinePortability(files, shipsPrefix = DEFAULT_SHIPS_PREFIX) {
-  const findings = [];
-  for (const file of files) {
-    if (!file.path.startsWith(shipsPrefix))
-      continue;
-    for (const { cited, index } of extractCitedPaths(file.content)) {
-      if (EXEMPT_LITERALS.has(cited))
-        continue;
-      if (isPortable(cited, shipsPrefix))
-        continue;
-      findings.push({
-        file: file.path,
-        line: lineAtIndex(file.content, index),
-        cited,
-        message: `cites "${cited}", a path that only exists in the authoring repository — not portable doctrine`
-      });
-    }
-  }
-  return findings;
-}
 // ../../packages/aeg-core/src/reader-resolvable-prose.ts
 var SHIPS_PREFIX = "aeg-root/";
 function shipsArchivePrefix(shipsPrefix) {
@@ -3669,6 +4071,12 @@ function scanRetiredVocabulary(files) {
 function isHandClosedByRecognizedPrincipal(dep, principalAllowlist) {
   return dep.issueState === "closed" && dep.stateReason === "completed" && isPrincipal(dep.closedByActor ?? null, principalAllowlist);
 }
+function isSelfDependency(dep, task, issue) {
+  if (dep.issue !== null && issue !== null && dep.issue === issue.number)
+    return true;
+  const bare = dep.id.trim().replace(/^#/, "");
+  return bare.toLowerCase() === task.id.trim().toLowerCase();
+}
 function checkDispatchReadiness(input) {
   const { trancheSlug, task } = input;
   const taskLabel = `task ${task.id} (tranche ${trancheSlug})`;
@@ -3683,6 +4091,11 @@ function checkDispatchReadiness(input) {
     blockers.push(`dispatch-gate rationale: Issue #${input.issue.number} for ${taskLabel} fails the rationale gate (checkIssueRationale) — the Planner must complete the eight-field rationale before this task is dispatchable.`);
   }
   for (const dep of input.dependsOn) {
+    if (isSelfDependency(dep, task, input.issue)) {
+      const issueStr = input.issue !== null ? `#${input.issue.number}` : "?";
+      blockers.push(`dispatch-gate INTERNAL: parsed a self-dependency for task ${task.id} (${issueStr}) — this is a parser bug in parseRationaleDeps, not a real dependency. Please report it upstream. Re-run once the rationale is corrected or the fix ships.`);
+      continue;
+    }
     if (dep.resolved === false) {
       blockers.push(`dispatch-gate depends-on: ${taskLabel} depends on "${dep.id}", which is UNRESOLVABLE — the resolver could not find a matching tranche/task/Issue for this edge (not a claim about merge status). Not dispatchable until the edge is corrected.`);
       continue;
@@ -3747,8 +4160,12 @@ function isNewDiskStateFile(path, status) {
   return ANY_DEPTH_TRANCHES_MD.test(path) || TOKENS_FILE.test(path);
 }
 // ../../packages/aeg-core/src/main-branch-refusal.ts
+function pushesAnyBranchRef(pushRefs) {
+  return pushRefs.split(`
+`).map((line) => line.trim()).filter((line) => line.length > 0).some((line) => line.split(/\s+/)[2]?.startsWith("refs/heads/") === true);
+}
 function checkMainBranchRefusal(facts) {
-  const { currentSymbolicBranch, defaultBranch } = facts;
+  const { currentSymbolicBranch, defaultBranch, pushRefs = null } = facts;
   if (currentSymbolicBranch === null)
     return null;
   if (defaultBranch === null) {
@@ -3760,6 +4177,8 @@ function checkMainBranchRefusal(facts) {
     };
   }
   if (currentSymbolicBranch === defaultBranch) {
+    if (pushRefs !== null && !pushesAnyBranchRef(pushRefs))
+      return null;
     return {
       reason: "on-default-branch",
       severity: "error",
@@ -3922,27 +4341,27 @@ function evaluateTestPlanGate(body, branch) {
     };
   }
   const checkboxLines = section.split(`
-`).map((line) => line.trimStart()).filter((line) => /^[-*]\s+\[[ xX]\]/.test(line));
+`).map((line) => line.trimStart()).filter((line) => /^[-*]\s+\[[ xX]\]\s*\*{0,2}\[principal\]\*{0,2}/i.test(line));
   if (checkboxLines.length === 0) {
     return {
       verdict: "pass",
       messages: [
-        "Test Plan section found but has no checkbox items.",
+        "Test Plan section found but has no `[principal]` checkbox items.",
         "PASS (advisory) — the section may be empty or expressed in prose; verification is the Principal's call."
       ]
     };
   }
   const unchecked = checkboxLines.filter((line) => /^[-*]\s+\[\s\]/.test(line));
   const checked = checkboxLines.filter((line) => /^[-*]\s+\[[xX]\]/.test(line));
-  const messages = [`Test Plan items: ${checked.length} ticked, ${unchecked.length} unticked.`];
+  const messages = [`Test Plan [principal] items: ${checked.length} ticked, ${unchecked.length} unticked.`];
   if (unchecked.length > 0) {
-    messages.push("", "FAIL — the following Test Plan items are unticked:");
+    messages.push("", "FAIL — the following [principal] Test Plan items are unticked:");
     for (const line of unchecked)
       messages.push(`  ${line}`);
-    messages.push("", "Per aeg-root/roles/developer.md (Verification), a PR is not mergeable while any Test Plan box is unticked.", "- [agent] items: the Developer-agent posts the actual command output as evidence and ticks the box.", "- [principal] items: the Principal runs the item in a real signed-in browser and ticks the box.", "Note: editing the PR body does not retrigger most workflows. If your PR body changes do not surface here, push an empty commit to re-run.");
+    messages.push("", "Per aeg-root/roles/developer.md (Verification), a PR is not mergeable while any [principal] Test Plan box is unticked.", "The Principal runs the item in a real signed-in browser and ticks the box.", "Note: editing the PR body does not retrigger most workflows. If your PR body changes do not surface here, push an empty commit to re-run.");
     return { verdict: "fail", messages };
   }
-  messages.push("All Test Plan items ticked — runtime verification complete.", "PASS.");
+  messages.push("All [principal] Test Plan items ticked — runtime verification complete.", "PASS.");
   return { verdict: "pass", messages };
 }
 // ../../packages/aeg-core/src/workspace-escape.ts
@@ -4127,6 +4546,19 @@ var COMMANDS = [
     ],
     status: "shipped"
   },
+  {
+    name: "brief render",
+    description: "Emit the twelve-section brief skeleton from the forge and the tree, every derivable section filled",
+    flags: [
+      { flag: "--surfaces <glob1,glob2,...>", description: "Intended surface globs, expanded against tracked files" },
+      { flag: "--out <path>", description: "Write the rendered brief to a file instead of stdout" }
+    ],
+    details: [
+      "Reads the task Issue (`vinaya/tranche:<tranche>`-labeled, id `<n>`) and the tree, and fills every section a program can derive: the header `Project:`/`Tier:`/`Closes #N`, the Step 0 worktree line, the dispatch-gate status as the pre-flight line, §4's file list (with consumer packages and a `sha256` premise pin per file), §7 from the `.vinaya/doc-owners` derivation, and every remaining section from the Issue's eight-field Planner rationale. Refuses — naming the missing fact — when a derived section cannot be derived: no Issue, the dispatch gate not clear, or a `--surfaces` glob matching no tracked file.",
+      "Never writes under `aeg-root/` or to the Issue — a brief is pasted to the Developer, never committed. Reads `aeg-root/templates/brief-template.md` at run time for its one fixed sentence and the standing autonomy clause; every other byte is generated from the forge/tree facts."
+    ],
+    status: "shipped"
+  },
   {
     name: "pr create",
     description: "Open a pull request after full brief-schema validation",
@@ -4166,11 +4598,16 @@ var COMMANDS = [
       {
         flag: "--write",
         description: "Path to the PR body file; replaces the content between the AEG:EVIDENCE anchors in place"
+      },
+      {
+        flag: "--push",
+        description: "PR number; splices the same content into that PR's LIVE body (fetched from the forge) and pushes it via `gh pr edit`, self-verifying nothing outside the AEG:EVIDENCE/AEG:TOKENS regions changed. Mutually exclusive with --write."
       }
     ],
     details: [
       "Two groups: Group A (recomputable) is the head sha and a width-invariant `git diff --numstat` against the merge-base with `BASE_SHA` (else `origin/main`, then `main`) — `check-evidence-fresh` recomputes and byte-compares this exactly. Group B (attested) is the result of `vinaya check --all --diff-only`, this CLI's own portable gate suite — `check-evidence-fresh` can only check it for staleness (the block's recorded head still matches the PR's real head), never re-run it.",
-      "With no `--write`, prints the block to stdout instead of writing a file. Exits non-zero whenever the gate run failed, whether or not `--write` was given — the block records a failing result rather than hiding one, and a non-zero exit stops a scripted `--write && open-pr` from carrying a failing suite onto the forge."
+      "With no `--write`/`--push`, prints the block to stdout instead of writing a file. Exits non-zero whenever the gate run failed, whether or not `--write`/`--push` was given — the block records a failing result rather than hiding one, and a non-zero exit stops a scripted `--write && open-pr` (or `--push`) from carrying a failing suite onto the forge.",
+      "`--push` refuses before writing anything when the live body carries no real `AEG:EVIDENCE` pair (it never appends one, unlike `--write`), when the anchor resolves differently before and after normalisation, or when `<pr>` isn't a bare number. When the live body has no real `AEG:TOKENS` pair, the token splice is skipped (same reasoning, softer outcome) rather than creating one. After pushing, it re-reads the live body and restores the pre-edit body — exiting non-zero — if anything outside the two anchored regions changed."
     ],
     status: "shipped"
   },
@@ -4275,6 +4712,16 @@ var COMMANDS = [
     ],
     status: "shipped"
   },
+  {
+    name: "review status",
+    description: "Print the review loop's own state for a PR, and its branch's distance from the base",
+    details: [
+      "Two lines at most. The first is `CONTINUE`, `PAUSE: <reason>[ <id>]` for `reappearance`, `zero-deaths` or `max-rounds` — or, for `stale`, the actionable fact itself: `push after verdict — re-review required`. The second reads `behind main by <n> — merge first` when the branch is behind its base, or `behind main: unknown — fetch origin/<base> first` when git cannot measure the distance; it is absent only when the branch is measurably not behind.",
+      "Rounds are derived from the PR's own verdict comments — one round per `Judged head:` value, read through the same extractors the merge gate blocks on, and only from comments an allowlisted principal authored. A Developer round comment is recognised by its `<!-- aeg:developer:round-<n> -->` marker, at that fixed position, never by scanning its prose.",
+      "Exit `0` only when the state is `CONTINUE` and the branch is not behind; `1` otherwise, so a script can gate on the exit code without parsing the text."
+    ],
+    status: "shipped"
+  },
   {
     name: "review post",
     description: "Render, post, and self-verify a code-reviewer or security-review verdict comment on a PR",
@@ -4286,15 +4733,24 @@ var COMMANDS = [
       },
       {
         flag: "--verdict",
-        description: "code-reviewer: `APPROVE` | `REQUEST_CHANGES`. security: `PASS` | `FAIL`"
+        description: "Optional — derived from the findings file (code-reviewer: `APPROVE`/`REQUEST_CHANGES`; security: `PASS`/`FAIL`). Refused before posting if it disagrees with the derivation."
+      },
+      {
+        flag: "--escalate",
+        description: "`authority` | `strategy` | `product` — posts an `ESCALATE:` comment instead of a verdict. Refused together with `--verdict` or a blocking finding."
       },
+      { flag: "--summary", description: "Required with `--escalate` — the escalation body text" },
       {
         flag: "--findings-file",
-        description: "One finding per line: `SEVERITY|file:line|description` (`|`-delimited). Omit for zero findings."
+        description: "One finding per line: `SEVERITY|file:line|description` (`|`-delimited). A re-review names a prior id in the description as `F<n> <class> <state>:`. Omit for zero findings."
       },
       { flag: "--brief-conformance", description: "code-reviewer only: the BRIEF CONFORMANCE line" },
       { flag: "--spec-conformance", description: "code-reviewer only: the SPEC CONFORMANCE line" },
       { flag: "--scope", description: "code-reviewer only: the SCOPE line" },
+      {
+        flag: "--scope-evidence-file",
+        description: "code-reviewer only: pasted diff-stat output, rendered as a fence directly below the verdict block"
+      },
       { flag: "--tests", description: "code-reviewer only: the TESTS line" },
       { flag: "--docs", description: "code-reviewer only: the DOCS line" },
       { flag: "--config-scan", description: "security only: the CONFIG SCAN line" },
@@ -4308,12 +4764,18 @@ var COMMANDS = [
       { flag: "--tokens-in", description: "a non-negative integer, or `-` if unknown" },
       { flag: "--tokens-out", description: "a non-negative integer, or `-` if unknown" },
       { flag: "--cost", description: "free text, or `-` if unknown" },
+      {
+        flag: "--print-only",
+        description: "Render and self-check the comment, print it, and exit — never calls `gh pr comment`"
+      },
       { flag: "--json", description: "Enveloped JSON output (schema: 1)" }
     ],
     details: [
+      "`--print-only` runs the exact same render-then-self-check path as a real post, then returns before `gh pr comment` — closes atta-labs/vinaya#184, where the old command silently posted a verdict anyway after a reviewer guessed this flag existed.",
       "Every structural line (`VERDICT:`, `Judged head:`) is rendered from this command's own validated enum/sha inputs — never from a caller-supplied string — so a Reviewer's free-typed prose can no longer produce a shape the merge gate's line-anchored regex fails to see.",
-      "Refuses a contradictory verdict before posting anything: a BLOCKER finding with `--verdict APPROVE`, or a CRITICAL/HIGH finding with `--verdict PASS`, is rejected outright, mirroring each role doc's own consistency rule.",
-      "After posting, re-fetches the PR's comments and runs them through the exact `extractCodeReviewVerdict`/`extractSecurityReviewVerdict` functions `checkReviewGate` calls — the same functions, not a second implementation — and exits non-zero naming precisely what failed to re-parse if the post does not come back clean and bound to the resolved head. There is no `--skip-verify` escape."
+      "The verdict is derived, not typed: a BLOCKER (or CRITICAL/HIGH) finding forces REQUEST_CHANGES/FAIL and its absence forces APPROVE/PASS, before posting anything — an explicit `--verdict` that disagrees is refused naming the derived value. When a same-role verdict comment already exists on the PR, a new findings file must carry every prior id with a state and no non-blocking finding outside the diff since that comment's judged head, or the post is refused.",
+      "Before the post ever reaches the forge, runs the exact `extractCodeReviewVerdict`/`extractSecurityReviewVerdict` functions `checkReviewGate` calls over its own rendered text and refuses (exit 2) unless exactly the intended verdict extracts and the other role extracts none — an escalation requires both to extract none. Both extractors read only a comment's first three lines, which are always this command's own structural lines, so no caller-supplied field can smuggle a line the gate would misread.",
+      "After posting, re-fetches the PR's comments and runs them through the same extractors `checkReviewGate` calls — the same functions, not a second implementation — and exits non-zero naming precisely what failed to re-parse if the post does not come back clean, bound to the resolved head, and free of the other role's verdict. There is no `--skip-verify` escape."
     ],
     status: "shipped"
   },
@@ -4366,6 +4828,9 @@ var COMMANDS = [
       { flag: "--dry-run", description: "Print the full diff without regenerating anything" },
       { flag: "--yes", description: "Skip the confirmation prompt" }
     ],
+    details: [
+      "When `claude` is a selected agent vendor, also retrofits the Claude Code `Stop` hook (`.claude/hooks/track-transcript.sh`, `.claude/settings.json`) the same way `init` installs it on a fresh repo — for a repo that ran `init` before this hook existed, closing the gap that left token rows reading `—/—/—` with no operator ever told to re-run `init`. Never overwrites a foreign `.claude/settings.json` (refuse-if-foreign, same as `init`); appends to a foreign Stop-hook script rather than replacing it (managed-block, same discipline as the git hooks)."
+    ],
     status: "shipped"
   },
   {
@@ -4459,6 +4924,26 @@ var COMMANDS = [
       "Never reimplements or edits `init`/`init product`/`demo break`/`doctor` — it only calls their existing, unmodified entry points in sequence."
     ],
     status: "shipped"
+  },
+  {
+    name: "release",
+    description: "Run this repo's own publish sequence in one command, refusing to start unless every precondition holds",
+    flags: [
+      {
+        flag: "--dry-run",
+        description: "Run the preconditions only and print the plan; publishes nothing"
+      },
+      {
+        flag: "--allow-any-commit",
+        description: "Skip the check that HEAD's commit is a Version Packages commit"
+      }
+    ],
+    details: [
+      "Refuses unless HEAD is the default branch, the working tree is clean, HEAD equals `origin/<default>` (after `git fetch origin`), HEAD's commit subject starts with `Chore(release): Version packages` (unless `--allow-any-commit`), and `npm whoami` exits `0` — each its own refusal naming the fix.",
+      "Then streams `bun install --frozen-lockfile`, `bun run build`, `bun run changeset:publish`, and `git push origin --tags` — a real push, so the repo's own generated pre-push hook sees it exactly as any other push would. After it, prints `npm view <pkg> version` for every tag now on HEAD, noting registry lag on `@attalabs/vinaya` (observed ~20 minutes) when it still shows the previous version.",
+      'This is the one procedure named in `apps/cli/specs/self-hosting.md`, "How the published version is produced" — publishing itself stays manual and human-triggered; this command only removes the hand-typed four-step recipe.'
+    ],
+    status: "shipped"
   }
 ];
 // ../../packages/sources/src/forge-adapter.ts
@@ -4851,7 +5336,10 @@ function taskToEntry(entries, slug) {
     m.set(`${slug}/${e.task.id}`, e);
   return m;
 }
-function recoveryPromptFor(checkCode) {
+function recoveryPromptFor(checkCode, detail = "") {
+  if (detail.includes("INTERNAL:")) {
+    return "This is an INTERNAL parser-bug report, not a real coherence failure — a task cannot depend on itself, so there is nothing here to close or resolve. Do NOT work around it. Report it upstream, and re-run once the rationale text is corrected or the parser fix ships.";
+  }
   switch (checkCode) {
     case "A1":
       return "The task's Issue is closed but its closing PR is not merged. Verify the PR actually merged (or reopen the Issue if it was closed in error), then re-run `vinaya check coherence`.";
@@ -4878,7 +5366,7 @@ function emitFailure(result) {
     check: CHECK_NAME,
     severity: "error",
     message: `${result.check}: ${detail}`,
-    agent_recovery_prompt: recoveryPromptFor(result.check)
+    agent_recovery_prompt: recoveryPromptFor(result.check, detail)
   });
 }
 async function main() {
@@ -4955,4 +5443,9 @@ async function main() {
   }
   process.exit(0);
 }
-main();
+if (__require.main == __require.module) {
+  main();
+}
+export {
+  recoveryPromptFor
+};