@attalabs/vinaya 0.22.0 → 0.23.0

package/dist/checks/bin/check-dispatch-readiness.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-dispatch-readiness.ts
 import { execFile as execFile4, execFileSync as execFileSync4 } 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;
@@ -3922,27 +4335,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 +4540,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 +4592,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 +4706,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 +4727,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 +4758,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 +4822,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"
   },
   {
@@ -5129,6 +5588,9 @@ async function main() {
   process.exit(ready ? 0 : 1);
 }
 function recoveryPromptFor(blocker) {
+  if (blocker.startsWith("dispatch-gate INTERNAL:")) {
+    return "This is an INTERNAL parser-bug report, not a real dispatch gate — a task cannot depend on itself, so there is nothing here to wait for or resolve. Do NOT work around it and do NOT skip the hook. Report it upstream, and re-run once the rationale text is corrected or the parser fix ships.";
+  }
   if (blocker.startsWith("dispatch-gate issue-existence:")) {
     return "This task has no resolvable Issue yet. Wait for the Planner to cut the Issue (or fix the phantom reference in the topology), then re-run `vinaya check dispatch-readiness`.";
   }
@@ -5149,4 +5611,9 @@ function recoveryPromptFor(blocker) {
   }
   return "Resolve the named dispatch blocker before continuing work on this task, then re-run `vinaya check dispatch-readiness`.";
 }
-main();
+if (__require.main == __require.module) {
+  main();
+}
+export {
+  recoveryPromptFor
+};