@webpresso/agent-kit 3.3.2 → 3.3.4

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,12 +151,93 @@ 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;
     }
 }
+/**
+ * Candidate delivery subjects for the working path.
+ *
+ * Two sources, in this order:
+ *
+ * 1. **The live tree at HEAD.** This mirrors what {@link readReviewAuthorityAtRef}
+ *    already does for delivery on the ref path: it builds the subject from the
+ *    ref under audit and matches events by digest, never resolving the commit an
+ *    event recorded. Doing the same here removes the working path's outlier
+ *    behaviour.
+ * 2. **Reconstruction at each event's `reviewedCommit`**, for events the live
+ *    subject does not already cover.
+ *
+ * Why the live tree has to come first: `reviewedCommit` is a *locator*, not the
+ * binding. The binding is `subjectDigest`, which content-addresses the reviewed
+ * tree. A squash merge destroys the branch commit while preserving its tree, so
+ * an approval recorded at the branch tip kept a digest that still describes the
+ * post-merge tree exactly — yet resolving its now-orphaned SHA threw, the event
+ * was marked compromised, and a genuinely valid approval was discarded. The
+ * standing workaround was to hand-append a rebind event after every squash.
+ *
+ * Matching on the digest first is not a loosening: an event is accepted only
+ * when the tree it recorded is byte-for-byte the tree we have. Content that
+ * differs still fails, and an event whose commit is gone *and* whose digest
+ * matches nothing reachable is still marked unresolvable — fail-closed.
+ */
+function collectWorkingDeliverySubjects(input) {
+    const { repoRoot, slug, blueprintPath, events, unresolvableEventIds, issues } = input;
+    const candidates = new Map();
+    // Nothing to resolve against: skip before paying for a whole-tree read. This
+    // path also runs for plan-only ledgers, where the old code cost nothing.
+    if (!events.some((event) => event.purpose === "delivery"))
+        return [];
+    let liveDigest = null;
+    try {
+        const live = createDeliverySubjectAtRef(repoRoot, "HEAD", slug, blueprintPath);
+        liveDigest = live.digest;
+        candidates.set(live.digest, { scheme: live.scheme, digest: live.digest });
+    }
+    catch (error) {
+        // No HEAD (fresh repo) or no blueprint document at HEAD (first commit of a
+        // new blueprint). Not fatal: fall through to per-event reconstruction.
+        issues?.push(`Working delivery subject unavailable at HEAD for ${slug}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const event of events) {
+        if (event.purpose !== "delivery")
+            continue;
+        // Already covered by the live tree — the reviewed content is exactly what
+        // we have, so the recorded commit does not need to exist any more.
+        if (liveDigest !== null && event.subjectDigest === liveDigest)
+            continue;
+        // Scope subject-construction failure to THIS event. A rebase rewrites
+        // commit SHAs, so a previously-recorded `reviewedCommit` can become
+        // unresolvable; letting that throw would escape to the outer catch and
+        // discard every approval, including valid ones for commits that still
+        // resolve. Mirror the ref-path's markCompromisedArtifactEvents: record the
+        // issue, mark the event compromised, and drop only it.
+        let subject;
+        try {
+            subject = createDeliverySubjectAtRef(repoRoot, event.reviewedCommit, slug, blueprintPath);
+        }
+        catch (error) {
+            issues?.push(`Working delivery review subject unavailable for ${event.id} at ${event.reviewedCommit}: ${error instanceof Error ? error.message : String(error)}`);
+            // Compromised (not merely skipped) so the event can never grant approval
+            // while still participating in reviewer supersession — see
+            // evaluateReviewEvents.
+            unresolvableEventIds.add(event.id);
+            continue;
+        }
+        if (subject.digest !== event.subjectDigest) {
+            issues?.push(`Working delivery review subject mismatch for ${event.id}: expected ${subject.digest}, found ${event.subjectDigest}.`);
+            continue;
+        }
+        candidates.set(subject.digest, { scheme: subject.scheme, digest: subject.digest });
+    }
+    return [...candidates.values()];
+}
 // Working-ledger acceptance: pre-commit validates a blueprint whose new review
 // events are staged alongside it and therefore not yet at any git ref. An
 // event still counts only when its subjectDigest matches the digest of the
@@ -147,13 +246,17 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
 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
@@ -167,37 +270,15 @@ function collectWorkingV2ReviewProvenance(file, purpose, issues) {
                     createLegacyPlanSubjectDigestForContent(slug, readFileSync(file)),
                 ].map((digest) => [digest, { scheme: "wp-blueprint-v1", digest }])).values(),
             ]
-            : [
-                ...new Map(working.events
-                    .filter((event) => event.purpose === "delivery")
-                    .flatMap((event) => {
-                    // Scope subject-construction failure to THIS event. A rebase
-                    // rewrites commit SHAs, so a previously-recorded
-                    // `reviewedCommit` can become unresolvable; letting that throw
-                    // would escape to the outer catch and discard every approval,
-                    // including valid ones for commits that still resolve. Mirror
-                    // the ref-path's markCompromisedArtifactEvents: record the
-                    // issue, mark the event compromised, and drop only it.
-                    let subject;
-                    try {
-                        subject = createDeliverySubjectAtRef(repoRoot, event.reviewedCommit, slug, normalizePath(path.relative(repoRoot, file)));
-                    }
-                    catch (error) {
-                        issues?.push(`Working delivery review subject unavailable for ${event.id} at ${event.reviewedCommit}: ${error instanceof Error ? error.message : String(error)}`);
-                        // Compromised (not merely skipped) so the event can never
-                        // grant approval while still participating in reviewer
-                        // supersession — see evaluateReviewEvents.
-                        unresolvableEventIds.add(event.id);
-                        return [];
-                    }
-                    if (subject.digest !== event.subjectDigest) {
-                        issues?.push(`Working delivery review subject mismatch for ${event.id}: expected ${subject.digest}, found ${event.subjectDigest}.`);
-                        return [];
-                    }
-                    return [[subject.digest, subject]];
-                })).values(),
-            ];
-        return subjects
+            : collectWorkingDeliverySubjects({
+                repoRoot,
+                slug,
+                blueprintPath: normalizePath(path.relative(repoRoot, file)),
+                events: working.events,
+                unresolvableEventIds,
+                issues,
+            });
+        const approvals = subjects
             .flatMap((subject) => evaluateReviewEvents(working.events, {
             purpose,
             blueprintSlug: slug,
@@ -212,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)}`);
@@ -222,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/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;