@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/blueprint/lifecycle/review-provenance.js

@@ -108,10 +108,22 @@ export function readBlueprintOverviewAtRef(repoRoot, ref, file) {
         }
     }
 }
-function workingContentMatchesRef(repoRoot, file, purpose, ref) {
+/**
+ * Whether the working-tree document still represents what `ref` holds, so the
+ * ref-side review ledger may be consulted.
+ *
+ * Every `false` branch records a specific reason in `issues`. Without that, the
+ * caller reports "0 approvals" with no `Evidence issues:` suffix and no way to
+ * tell a substantive plan edit apart from a missing overview, a path outside the
+ * repo, or a failed git probe — an opacity that has cost whole debugging
+ * sessions on exactly this class of digest divergence.
+ */
+function workingContentMatchesRef(repoRoot, file, purpose, ref, issues) {
     const relative = path.relative(repoRoot, file);
-    if (relative.startsWith("..") || path.isAbsolute(relative))
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        issues?.push(`Review authority at ${ref} not consulted for ${file}: the blueprint path resolves outside the repository root ${repoRoot}.`);
         return false;
+    }
     try {
         if (purpose === "plan") {
             // Compare normalized plan content, not raw bytes: promotion rewrites
@@ -122,10 +134,16 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
             // Also resolve by stable slug when the lifecycle path changed (draft→planned)
             // so pre-commit on a rename does not falsely drop plan authority.
             const atRef = readBlueprintOverviewAtRef(repoRoot, ref, file);
-            if (!atRef)
+            if (!atRef) {
+                issues?.push(`Review authority at ${ref} not consulted for ${relative}: no blueprint overview for this slug exists at ${ref}.`);
                 return false;
+            }
             const working = readFileSync(file);
-            return normalizePlanSubjectContent(working).equals(normalizePlanSubjectContent(atRef));
+            if (normalizePlanSubjectContent(working).equals(normalizePlanSubjectContent(atRef))) {
+                return true;
+            }
+            issues?.push(`Review authority at ${ref} not consulted for ${relative}: the working document's normalized plan content differs from ${ref}, so its plan-subject digest differs and no approval recorded against ${ref} can match. Re-run the plan review gate against the current content, or restore the reviewed content.`);
+            return false;
         }
         const output = execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], {
             cwd: repoRoot,
@@ -133,9 +151,13 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 5_000,
         });
-        return output.trim().length === 0;
+        if (output.trim().length === 0)
+            return true;
+        issues?.push(`Review authority at ${ref} not consulted for ${relative}: the working tree is dirty, so a delivery subject at ${ref} does not cover the current content.`);
+        return false;
     }
-    catch {
+    catch (error) {
+        issues?.push(`Review authority at ${ref} not consulted for ${relative}: divergence probe failed: ${error instanceof Error ? error.message : String(error)}`);
         return false;
     }
 }
@@ -224,13 +246,17 @@ function collectWorkingDeliverySubjects(input) {
 function collectWorkingV2ReviewProvenance(file, purpose, issues) {
     try {
         const repoRoot = findGitRoot(file);
-        if (!repoRoot)
+        if (!repoRoot) {
+            issues?.push(`Working review authority unavailable for ${file}: no enclosing git repository was found.`);
             return [];
+        }
         const slug = stableSlugForBlueprintFile(file);
         const working = readWorkingReviewEvents(file, slug);
+        issues?.push(...working.issues);
+        // No v2 ledger at all is the normal shape for a blueprint whose authority is
+        // a legacy frontmatter approval, so it is not a reason worth reporting.
         if (working.events.length === 0)
             return [];
-        issues?.push(...working.issues);
         // Events whose recorded `reviewedCommit` no longer resolves (typically
         // orphaned by a rebase). Collected here rather than mutating
         // `working.compromisedIds`, which is a ReadonlySet by contract, then merged
@@ -252,7 +278,7 @@ function collectWorkingV2ReviewProvenance(file, purpose, issues) {
                 unresolvableEventIds,
                 issues,
             });
-        return subjects
+        const approvals = subjects
             .flatMap((subject) => evaluateReviewEvents(working.events, {
             purpose,
             blueprintSlug: slug,
@@ -267,6 +293,19 @@ function collectWorkingV2ReviewProvenance(file, purpose, issues) {
             artifact: event.artifactPath,
             targetHash: event.subjectDigest,
         }));
+        if (approvals.length === 0) {
+            // The ledger has events but none of them approves the CURRENT content.
+            // Name both sides of the comparison: this is the digest-divergence
+            // failure mode, and reporting it as a bare "0 approvals" is what makes it
+            // expensive to diagnose.
+            const computed = subjects.length === 0
+                ? "no subject could be computed for the current content"
+                : `computed subject digest(s) ${subjects.map((subject) => subject.digest).join(", ")}`;
+            issues?.push(`No working-tree approval matched the current ${purpose} subject of ${slug}: ${computed}; the ledger's ${working.events.length} event(s) bind ${[
+                ...new Set(working.events.map((event) => event.subjectDigest)),
+            ].join(", ")}.`);
+        }
+        return approvals;
     }
     catch (error) {
         issues?.push(`Working review authority unavailable for ${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -277,9 +316,23 @@ export function collectV2ReviewProvenance(file, purpose, ref = "HEAD", issues) {
     const repoRoot = findGitRoot(file);
     if (!repoRoot)
         return [];
+    // Only explain a skipped/unmatched v2 lookup when the blueprint actually has a
+    // v2 ledger. A blueprint whose authority is a legacy frontmatter approval has
+    // no ledger by design, and narrating the absence for every one of those would
+    // bury the one case that matters (a ledger that no longer matches its subject)
+    // under warnings that report nothing wrong.
+    const explain = existsSync(path.join(path.dirname(file), "review-events.jsonl"))
+        ? issues
+        : undefined;
     const workingApprovals = collectWorkingV2ReviewProvenance(file, purpose, issues);
-    if (!workingContentMatchesRef(repoRoot, file, purpose, ref))
+    if (!workingContentMatchesRef(repoRoot, file, purpose, ref, explain)) {
+        // The ref-side ledger is deliberately skipped here (its approvals bind a
+        // subject the working content no longer matches), so the working set is all
+        // the authority there is. Say so: an empty result on this path used to be
+        // indistinguishable from "there was never any review".
+        explain?.push(`Returning ${workingApprovals.length} working-tree approval(s) for ${file} without ref authority from ${ref}.`);
         return workingApprovals;
+    }
     try {
         const authority = readReviewAuthorityAtRef(repoRoot, ref, stableSlugForBlueprintFile(file), purpose);
         issues?.push(...authority.issues);

package/dist/esm/blueprint/lifecycle/rollout-anchor.d.ts

@@ -25,6 +25,28 @@
 export declare const ROLLOUT_ANCHOR_COMMIT = "c6ccb5f31cbecde3be4dbd6d3b7e67918006d22e";
 /** The date that anchor landed, used only by the legacy fallback below. */
 export declare const ROLLOUT_DATE = "2026-07-12";
+/**
+ * The commit that closed the legacy frontmatter approval bypass ("fix(review):
+ * bind the legacy frontmatter approval leg to the rollout anchor", 2026-07-25).
+ *
+ * Until that change, a frontmatter `approvals:` entry naming a strong reviewer
+ * satisfied the promotion gate with **no content binding whatsoever**: the gate
+ * called `evaluateApprovalGate` without a `targetHash`, so `matchesApproval`
+ * skipped its binding clause, and `collectTrackedReviewProvenance` never read or
+ * hashed the blueprint body at all. Any such blueprint passed the gate no matter
+ * what its plan currently said.
+ *
+ * 172 already-landed blueprints resolve their approval through that leg, so it
+ * is grandfathered rather than deleted: slugs tracked at this anchor keep the
+ * legacy leg, and every blueprint created afterwards must produce authority
+ * through the content-addressed v2 `review-events.jsonl` ledger. Anchor-tree
+ * membership is used for the same reason as {@link ROLLOUT_ANCHOR_COMMIT}: no
+ * file content can add a slug to a tree that was written earlier, so the
+ * grandfather cannot be forged by editing `created:`.
+ */
+export declare const LEGACY_APPROVAL_LEG_ANCHOR_COMMIT = "079be82e39de7099a5bda1261e37598baed8644e";
+/** The date that anchor landed, used only by the non-agent-kit fallback. */
+export declare const LEGACY_APPROVAL_LEG_ROLLOUT_DATE = "2026-07-25";
 /**
  * Outcome of consulting the anchor, cached per (repoRoot, anchorCommit).
  *

package/dist/esm/blueprint/lifecycle/rollout-anchor.js

@@ -26,12 +26,42 @@ import { execFileSync } from "node:child_process";
 export const ROLLOUT_ANCHOR_COMMIT = "c6ccb5f31cbecde3be4dbd6d3b7e67918006d22e";
 /** The date that anchor landed, used only by the legacy fallback below. */
 export const ROLLOUT_DATE = "2026-07-12";
+/**
+ * The commit that closed the legacy frontmatter approval bypass ("fix(review):
+ * bind the legacy frontmatter approval leg to the rollout anchor", 2026-07-25).
+ *
+ * Until that change, a frontmatter `approvals:` entry naming a strong reviewer
+ * satisfied the promotion gate with **no content binding whatsoever**: the gate
+ * called `evaluateApprovalGate` without a `targetHash`, so `matchesApproval`
+ * skipped its binding clause, and `collectTrackedReviewProvenance` never read or
+ * hashed the blueprint body at all. Any such blueprint passed the gate no matter
+ * what its plan currently said.
+ *
+ * 172 already-landed blueprints resolve their approval through that leg, so it
+ * is grandfathered rather than deleted: slugs tracked at this anchor keep the
+ * legacy leg, and every blueprint created afterwards must produce authority
+ * through the content-addressed v2 `review-events.jsonl` ledger. Anchor-tree
+ * membership is used for the same reason as {@link ROLLOUT_ANCHOR_COMMIT}: no
+ * file content can add a slug to a tree that was written earlier, so the
+ * grandfather cannot be forged by editing `created:`.
+ */
+export const LEGACY_APPROVAL_LEG_ANCHOR_COMMIT = "079be82e39de7099a5bda1261e37598baed8644e";
+/** The date that anchor landed, used only by the non-agent-kit fallback. */
+export const LEGACY_APPROVAL_LEG_ROLLOUT_DATE = "2026-07-25";
 const anchorSlugCache = new Map();
+/**
+ * Every git call here is on the audit/promote hot path, so each carries an
+ * explicit deadline (parity with `review-provenance.ts`). A wedged git process
+ * must not hang the gate; a timeout surfaces as the same failure the `catch`
+ * already handles, which for the two membership probes means fail-closed.
+ */
+const ANCHOR_GIT_TIMEOUT_MS = 5_000;
 function anchorCommitExists(repoRoot, anchorCommit) {
     try {
         execFileSync("git", ["cat-file", "-e", `${anchorCommit}^{commit}`], {
             cwd: repoRoot,
             stdio: ["ignore", "ignore", "ignore"],
+            timeout: ANCHOR_GIT_TIMEOUT_MS,
         });
         return true;
     }
@@ -51,6 +81,7 @@ function isShallowRepository(repoRoot) {
             cwd: repoRoot,
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
+            timeout: ANCHOR_GIT_TIMEOUT_MS,
         });
         // A path that is not a git repository at all answers with a non-zero exit,
         // handled below. Anything else that is not a clean "false" is treated as
@@ -86,7 +117,12 @@ export function blueprintSlugsAtRolloutAnchor(repoRoot, anchorCommit = ROLLOUT_A
             return isShallowRepository(repoRoot) ? { kind: "unreadable" } : { kind: "not-applicable" };
         }
         try {
-            const stdout = execFileSync("git", ["ls-tree", "-r", "--name-only", anchorCommit, "blueprints/"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            const stdout = execFileSync("git", ["ls-tree", "-r", "--name-only", anchorCommit, "blueprints/"], {
+                cwd: repoRoot,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: ANCHOR_GIT_TIMEOUT_MS,
+            });
             const found = new Set();
             for (const line of stdout.split("\n")) {
                 const match = /^blueprints\/[^/]+\/(.+)$/u.exec(line.trim());

package/dist/esm/blueprint/markdown/blocked-line.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Single owner of the task-body `**Blocked:** <reason>` line grammar.
+ *
+ * Both sides of the plan-approval contract read this file: `updateBlockedReason`
+ * (`#markdown/helpers.js`) writes the line, and `neutralizeTaskBlockedReason`
+ * (`#review/subject.js`) removes it before the plan-subject digest is taken. That
+ * pairing is exactly the arrangement the Promotion Gates row grammar already uses
+ * (`#trust/gate-row.js`), and for the same reason: when a writer and the
+ * normalizer spell the same grammar twice, they drift, the lifecycle stamp
+ * survives into the digest, and the plan approval the promotion gates on is
+ * silently dismissed.
+ *
+ * Deliberately dependency-free so any module on either side can import it
+ * without risking a cycle.
+ */
+/**
+ * Regex source for a whole `**Blocked:** …` line, anchored to line bounds.
+ *
+ * Anchoring is load-bearing in both directions. Blueprint prose legitimately
+ * mentions the marker mid-sentence ("add a non-empty **Blocked:** line with the
+ * reason") — those mentions are plan substance, and an unanchored pattern would
+ * have the writer overwrite them and the normalizer strip them.
+ */
+export declare const BLOCKED_LINE_SOURCE: string;
+/**
+ * Build a matcher for the blocked line. Mirrors the `buildTaskHeadingRegex`
+ * convention in `./task-heading.js`: callers pick the flags they need, but the
+ * pattern itself has exactly one definition.
+ */
+export declare function buildBlockedLineRegex(flags?: string): RegExp;
+/** True when `line` IS a blocked-reason line, not merely a line that mentions one. */
+export declare function isBlockedLine(line: string): boolean;
+/**
+ * Serialize the blocked line. The writer-side counterpart to
+ * {@link isBlockedLine}: every emitter goes through here so the written form and
+ * the parsed form cannot diverge.
+ */
+export declare function formatBlockedLine(reason: string): string;
+/**
+ * Read the reason off the first blocked line in a task section, or `undefined`
+ * when the section has none.
+ *
+ * The reader counterpart to {@link formatBlockedLine}. Three parsers used to
+ * carry their own unanchored copy of this pattern (`src/blueprint/core/parser.ts`,
+ * `src/blueprint/tracked-document/parser.ts`, `src/docs-linter/blueprint-plan.ts`),
+ * so a task whose prose merely mentioned the marker was read as genuinely
+ * blocked and the lifecycle audit failed the document.
+ */
+export declare function extractBlockedReason(section: string): string | undefined;

package/dist/esm/blueprint/markdown/blocked-line.js

@@ -0,0 +1,63 @@
+/**
+ * Single owner of the task-body `**Blocked:** <reason>` line grammar.
+ *
+ * Both sides of the plan-approval contract read this file: `updateBlockedReason`
+ * (`#markdown/helpers.js`) writes the line, and `neutralizeTaskBlockedReason`
+ * (`#review/subject.js`) removes it before the plan-subject digest is taken. That
+ * pairing is exactly the arrangement the Promotion Gates row grammar already uses
+ * (`#trust/gate-row.js`), and for the same reason: when a writer and the
+ * normalizer spell the same grammar twice, they drift, the lifecycle stamp
+ * survives into the digest, and the plan approval the promotion gates on is
+ * silently dismissed.
+ *
+ * Deliberately dependency-free so any module on either side can import it
+ * without risking a cycle.
+ */
+/**
+ * Regex source for a whole `**Blocked:** …` line, anchored to line bounds.
+ *
+ * Anchoring is load-bearing in both directions. Blueprint prose legitimately
+ * mentions the marker mid-sentence ("add a non-empty **Blocked:** line with the
+ * reason") — those mentions are plan substance, and an unanchored pattern would
+ * have the writer overwrite them and the normalizer strip them.
+ */
+export const BLOCKED_LINE_SOURCE = String.raw `^\*\*Blocked:\*\*.*$`;
+/**
+ * Build a matcher for the blocked line. Mirrors the `buildTaskHeadingRegex`
+ * convention in `./task-heading.js`: callers pick the flags they need, but the
+ * pattern itself has exactly one definition.
+ */
+export function buildBlockedLineRegex(flags = "imu") {
+    return new RegExp(BLOCKED_LINE_SOURCE, flags);
+}
+const SINGLE_LINE_MATCHER = buildBlockedLineRegex("iu");
+/** True when `line` IS a blocked-reason line, not merely a line that mentions one. */
+export function isBlockedLine(line) {
+    return SINGLE_LINE_MATCHER.test(line);
+}
+const MARKER_LENGTH = "**Blocked:**".length;
+/**
+ * Serialize the blocked line. The writer-side counterpart to
+ * {@link isBlockedLine}: every emitter goes through here so the written form and
+ * the parsed form cannot diverge.
+ */
+export function formatBlockedLine(reason) {
+    return `**Blocked:** ${reason}`;
+}
+/**
+ * Read the reason off the first blocked line in a task section, or `undefined`
+ * when the section has none.
+ *
+ * The reader counterpart to {@link formatBlockedLine}. Three parsers used to
+ * carry their own unanchored copy of this pattern (`src/blueprint/core/parser.ts`,
+ * `src/blueprint/tracked-document/parser.ts`, `src/docs-linter/blueprint-plan.ts`),
+ * so a task whose prose merely mentioned the marker was read as genuinely
+ * blocked and the lifecycle audit failed the document.
+ */
+export function extractBlockedReason(section) {
+    const match = buildBlockedLineRegex().exec(section);
+    if (!match)
+        return undefined;
+    const reason = match[0].slice(MARKER_LENGTH).trim();
+    return reason === "" ? undefined : reason;
+}

package/dist/esm/blueprint/markdown/helpers.js

@@ -8,6 +8,7 @@
  * produces identical output (for the same inputs).
  */
 import { escapeRegex } from "#utils/string";
+import { BLOCKED_LINE_SOURCE, buildBlockedLineRegex, formatBlockedLine } from "./blocked-line.js";
 import { buildTaskHeaderRegexForId, buildTaskSectionBoundaryRegex, TASK_HEADING_PREFIX_PATTERN, } from "./task-heading.js";
 function buildTaskPattern(taskId) {
     return new RegExp(`(####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+${escapeRegex(taskId)}[:\\s].*?)(?=\\n####|\\n###|$)`, "s");
@@ -65,7 +66,11 @@ export function updateBlockedReason(content, taskId, reason) {
     const taskPattern = buildTaskPattern(taskId);
     return content.replace(taskPattern, (section) => {
         const trimmedReason = reason.trim();
-        const blockedPattern = /\n?\*\*Blocked:\*\*\s*.*(?:\n+)?/i;
+        // Grammar comes from ./blocked-line.js, which the plan-subject normalizer
+        // consumes too. Line-anchored on purpose: a task whose prose mentions
+        // `**Blocked:**` mid-sentence is plan substance, and the previous
+        // unanchored pattern would have overwritten it.
+        const blockedPattern = new RegExp(String.raw `\n?${BLOCKED_LINE_SOURCE}\n*`, "imu");
         if (!trimmedReason) {
             // Preserve the section's trailing whitespace: trimEnd on the whole
             // section would also delete the blank line separating this task from the
@@ -76,9 +81,10 @@ export function updateBlockedReason(content, taskId, reason) {
                 .replace(/\n{3,}/g, "\n\n")
                 .trimEnd() + trailingWhitespace);
         }
-        const blockedLine = `**Blocked:** ${trimmedReason}`;
-        if (/\*\*Blocked:\*\*/i.test(section)) {
-            return section.replace(/\*\*Blocked:\*\*\s*.+/i, blockedLine);
+        const blockedLine = formatBlockedLine(trimmedReason);
+        const existingLine = buildBlockedLineRegex();
+        if (existingLine.test(section)) {
+            return section.replace(existingLine, blockedLine);
         }
         return insertAfterStatusLine(section, blockedLine);
     });

package/dist/esm/blueprint/tracked-document/parser.js

@@ -6,6 +6,7 @@
  *
  * Git-Native SSoT: Checkbox state derives status, no external state.
  */
+import { extractBlockedReason } from "#markdown/blocked-line";
 import { isTaskHeaderLine } from "#markdown/task-heading";
 /**
  * Extract checkbox status from a markdown section and derive task state.
@@ -100,10 +101,9 @@ export function extractDepends(section) {
  * ```
  */
 export function extractBlocked(section) {
-    const blockedMatch = section.match(/\*\*Blocked:\*\*\s*(.+)/i);
-    if (!blockedMatch?.[1])
+    const blockedText = extractBlockedReason(section);
+    if (blockedText === undefined)
         return undefined;
-    const blockedText = blockedMatch[1].trim();
     // Handle missing/empty reason gracefully
     if (blockedText === "" || blockedText.toLowerCase() === "none") {
         return undefined;

package/dist/esm/blueprint/trust/dossier.js

@@ -39,8 +39,15 @@ export function parseTrustDossier(markdown) {
     const gates = parsePromotionGatesTable(requiredBlock(blocks, "Promotion Gates"), violations);
     const residualUnknowns = requiredBlock(blocks, "Residual Unknowns").trim();
     for (const [section, block] of blocks) {
-        if (containsPlaceholder(block))
+        const fields = findPlaceholderFields(block);
+        if (fields.length > 0) {
+            for (const field of fields) {
+                violations.push({ section, message: `placeholder value not filled in: ${field}` });
+            }
+        }
+        else if (containsPlaceholder(block)) {
             violations.push({ section, message: "placeholder values are not allowed" });
+        }
     }
     if (violations.length > 0 || readiness === null)
         return { violations };
@@ -181,6 +188,39 @@ function splitRow(row) {
 function containsPlaceholder(value) {
     return /<[^>]+>|\bTBD\b|\bTODO\b/u.test(value);
 }
+// Names the specific field(s) inside a Trust Dossier subsection block that
+// still carry a scaffold placeholder, instead of only flagging the section as
+// a whole. Covers both shapes the dossier uses: `- key: value` list lines
+// (Readiness Verdict) and markdown table rows (Material Claims/Decisions,
+// Promotion Gates). Free-text sections (Residual Unknowns) have no named
+// field to point at, so the caller falls back to the whole-section message
+// when this returns an empty array.
+function findPlaceholderFields(block) {
+    const fields = [];
+    for (const line of block.split("\n")) {
+        const match = /^-\s*([^:]+):\s*(.+?)\s*$/u.exec(line.trim());
+        if (match && containsPlaceholder(match[2] ?? ""))
+            fields.push(match[1].trim());
+    }
+    const rows = block
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("|") && line.endsWith("|"));
+    if (rows.length >= 2) {
+        const header = splitRow(rows[0] ?? "");
+        for (const row of rows.slice(2)) {
+            const cells = splitRow(row);
+            for (const [index, cell] of cells.entries()) {
+                if (!containsPlaceholder(cell))
+                    continue;
+                const columnName = header[index] ?? `column ${index + 1}`;
+                const rowId = cells[0] ? ` (row ${cells[0]})` : "";
+                fields.push(`${columnName}${rowId}`);
+            }
+        }
+    }
+    return fields;
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/dist/esm/blueprint/trust/gate-row.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Single owner of the Trust Dossier "Promotion Gates" table row grammar.
+ *
+ * Two callers must agree on this grammar byte-for-byte:
+ *
+ * - the lifecycle WRITER `updateGateLastResult` (`./promotion.ts`), which stamps
+ *   the `Last result` cell during `wp blueprint promote`; and
+ * - the plan-subject digest NORMALIZER `neutralizePromotionGateResults`
+ *   (`#review/subject.js`), which replaces that same cell with a placeholder so
+ *   the stamp is never hashed into a plan approval's subject.
+ *
+ * They each used to implement the grammar independently, and diverged on four
+ * axes at once — cell count (writer 4 or 5, normalizer 4 only), section scope
+ * (writer any table row in the document, normalizer inside `### Promotion Gates`
+ * only), trailing pipe (writer `trim().startsWith("|")` alone, normalizer both
+ * pipes), and trailing whitespace after the closing pipe (writer sliced the
+ * UNTRIMMED line, so it mis-counted a 4-cell row as 5 and appended a spurious
+ * empty cell). Every divergence made `digest(doc) !== digest(writer(doc))`,
+ * which destroys the plan approval the promotion is gating on. One owner,
+ * consumed from both sides, is the only structural fix; anything else lets them
+ * drift again.
+ *
+ * The grammar deliberately matches what `parsePromotionGatesTable` in
+ * `./dossier.ts` already enforces on committed documents: a row is the trimmed
+ * line starting AND ending with a pipe, cells are split on `|` and trimmed, and
+ * the accepted widths are 4 (legacy) and 5 (opt-in `Defer` column). A row this
+ * module rejects is a row the dossier parser reports as `malformed table row`,
+ * so it can never be a live gate — skipping it is the fail-safe direction.
+ */
+/** Zero-based index of the lifecycle-owned `Last result` cell. */
+export declare const LAST_RESULT_CELL_INDEX = 3;
+/**
+ * Cells of one Promotion Gates table row, trimmed, or null when the line is not
+ * a row this grammar owns (no pipes, a single pipe, or an unsupported width).
+ */
+export declare function parsePromotionGateCells(line: string): readonly string[] | null;
+/**
+ * Canonical row bytes. Whitespace around a row (leading indent, padding inside
+ * cells, whitespace after the closing pipe) is not plan substance, so both
+ * callers re-emit this single canonical form. That is what keeps a stamped row
+ * and its normalized counterpart byte-identical, and it is exactly the form the
+ * normalizer has always emitted for a 4-cell row, so committed plan digests are
+ * unaffected.
+ */
+export declare function formatPromotionGateRow(cells: readonly string[]): string;
+/** Copy `cells` with the lifecycle-owned `Last result` cell set to `value`. */
+export declare function setLastResultCell(cells: readonly string[], value: string): readonly string[];
+/**
+ * Rewrite every Promotion Gates table row (header, separator, and data rows
+ * alike) inside the `### Promotion Gates` subsection through `transform`.
+ * Returning the received `cells` reference unchanged leaves the line
+ * byte-identical; returning a new array re-emits the canonical row. Every line
+ * outside the section is always byte-identical.
+ */
+export declare function mapPromotionGateRows(text: string, transform: (cells: readonly string[]) => readonly string[]): string;

package/dist/esm/blueprint/trust/gate-row.js

@@ -0,0 +1,113 @@
+/**
+ * Single owner of the Trust Dossier "Promotion Gates" table row grammar.
+ *
+ * Two callers must agree on this grammar byte-for-byte:
+ *
+ * - the lifecycle WRITER `updateGateLastResult` (`./promotion.ts`), which stamps
+ *   the `Last result` cell during `wp blueprint promote`; and
+ * - the plan-subject digest NORMALIZER `neutralizePromotionGateResults`
+ *   (`#review/subject.js`), which replaces that same cell with a placeholder so
+ *   the stamp is never hashed into a plan approval's subject.
+ *
+ * They each used to implement the grammar independently, and diverged on four
+ * axes at once — cell count (writer 4 or 5, normalizer 4 only), section scope
+ * (writer any table row in the document, normalizer inside `### Promotion Gates`
+ * only), trailing pipe (writer `trim().startsWith("|")` alone, normalizer both
+ * pipes), and trailing whitespace after the closing pipe (writer sliced the
+ * UNTRIMMED line, so it mis-counted a 4-cell row as 5 and appended a spurious
+ * empty cell). Every divergence made `digest(doc) !== digest(writer(doc))`,
+ * which destroys the plan approval the promotion is gating on. One owner,
+ * consumed from both sides, is the only structural fix; anything else lets them
+ * drift again.
+ *
+ * The grammar deliberately matches what `parsePromotionGatesTable` in
+ * `./dossier.ts` already enforces on committed documents: a row is the trimmed
+ * line starting AND ending with a pipe, cells are split on `|` and trimmed, and
+ * the accepted widths are 4 (legacy) and 5 (opt-in `Defer` column). A row this
+ * module rejects is a row the dossier parser reports as `malformed table row`,
+ * so it can never be a live gate — skipping it is the fail-safe direction.
+ */
+/** Zero-based index of the lifecycle-owned `Last result` cell. */
+export const LAST_RESULT_CELL_INDEX = 3;
+/**
+ * Exact end-anchored heading match, mirroring `sectionBlock(markdown, 3, ...)`
+ * in `./dossier.ts` — `### Promotion Gates Notes` is NOT the owned section and
+ * its contents stay plan substance.
+ */
+const PROMOTION_GATES_HEADING = /^###\s+Promotion Gates\s*$/iu;
+/**
+ * The section ends at the next heading of ANY level. `sectionBlock` itself ends
+ * at the next heading of level <= 3, so a table placed after an intervening
+ * `####` heading would be a gate to the parser but not to this walk. The
+ * narrower scope is deliberate: it is the scope every committed plan digest was
+ * computed against (measured: zero tracked blueprint documents put gate rows in
+ * that gap), and the consequence of the mismatch is fail-closed — the writer
+ * leaves such a row unstamped, so `validateBlueprintTrust` rejects the promotion
+ * with a non-passing gate instead of silently leaking the stamp into the digest.
+ */
+const ANY_HEADING = /^#{1,6}\s/u;
+const ACCEPTED_ROW_WIDTHS = [4, 5];
+/**
+ * Cells of one Promotion Gates table row, trimmed, or null when the line is not
+ * a row this grammar owns (no pipes, a single pipe, or an unsupported width).
+ */
+export function parsePromotionGateCells(line) {
+    const body = line.trim();
+    if (body.length < 2 || !body.startsWith("|") || !body.endsWith("|"))
+        return null;
+    const cells = body
+        .slice(1, -1)
+        .split("|")
+        .map((cell) => cell.trim());
+    if (!ACCEPTED_ROW_WIDTHS.includes(cells.length))
+        return null;
+    return cells;
+}
+/**
+ * Canonical row bytes. Whitespace around a row (leading indent, padding inside
+ * cells, whitespace after the closing pipe) is not plan substance, so both
+ * callers re-emit this single canonical form. That is what keeps a stamped row
+ * and its normalized counterpart byte-identical, and it is exactly the form the
+ * normalizer has always emitted for a 4-cell row, so committed plan digests are
+ * unaffected.
+ */
+export function formatPromotionGateRow(cells) {
+    return `| ${cells.join(" | ")} |`;
+}
+/** Copy `cells` with the lifecycle-owned `Last result` cell set to `value`. */
+export function setLastResultCell(cells, value) {
+    const next = [...cells];
+    next[LAST_RESULT_CELL_INDEX] = value;
+    return next;
+}
+/**
+ * Rewrite every Promotion Gates table row (header, separator, and data rows
+ * alike) inside the `### Promotion Gates` subsection through `transform`.
+ * Returning the received `cells` reference unchanged leaves the line
+ * byte-identical; returning a new array re-emits the canonical row. Every line
+ * outside the section is always byte-identical.
+ */
+export function mapPromotionGateRows(text, transform) {
+    const lines = text.split("\n");
+    let inGatesSection = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (PROMOTION_GATES_HEADING.test(line)) {
+            inGatesSection = true;
+            continue;
+        }
+        if (inGatesSection && ANY_HEADING.test(line)) {
+            inGatesSection = false;
+            continue;
+        }
+        if (!inGatesSection)
+            continue;
+        const cells = parsePromotionGateCells(line);
+        if (!cells)
+            continue;
+        const next = transform(cells);
+        if (next !== cells)
+            lines[index] = formatPromotionGateRow(next);
+    }
+    return lines.join("\n");
+}

package/dist/esm/blueprint/trust/promotion.d.ts

@@ -19,3 +19,20 @@ export declare function assertPromotionTrustProofCurrent(input: Pick<PromotionTr
 export declare function runPromotionCommand(repoRoot: string, command: string, deps?: {
     spawn?: typeof spawnSync;
 }): void;
+/**
+ * Exported for the plan-subject digest invariance suite
+ * (`src/review/lifecycle-writers.ts`, `src/review/subject-normalize.test.ts`).
+ * Those tests MUST call the production writer, never a hand-written mirror: a
+ * mirror can drift with the very bug under test and stay self-consistent, which
+ * is exactly how the 5-cell Promotion Gates leak survived the suite.
+ */
+export declare function upsertReadinessValue(markdown: string, key: string, value: string): string;
+/**
+ * Stamp the `Last result` cell of the gate named `gate`.
+ *
+ * Exported for the same reason as `upsertReadinessValue` above. The row grammar
+ * and the section scope both come from `./gate-row.js`, which the plan-subject
+ * digest normalizer consumes too — hand-rolling either here is what let the two
+ * sides diverge on four axes and destroy plan approvals on promotion.
+ */
+export declare function updateGateLastResult(markdown: string, gate: string, result: string): string;