@webpresso/agent-kit 3.3.3 → 3.3.4

package/dist/esm/blueprint/core/parser.js

@@ -6,6 +6,7 @@
  */
 import matter from "gray-matter";
 import { planFrontmatterSchema, taskStatusSchema } from "#core/schema";
+import { extractBlockedReason } from "#markdown/blocked-line";
 import { buildTaskHeadingRegex, isTaskHeaderLine } from "#markdown/task-heading";
 function parseWithSchema(markdown, schema) {
     const { data: rawData, content } = matter(markdown);
@@ -87,7 +88,13 @@ const SERIALIZE_OWNED_FRONTMATTER_KEYS = new Set([
     "progress",
     "completed_at",
 ]);
-const FRONTMATTER_SCALAR_LINE = /^([A-Za-z0-9_]+):[ \t]+\S.*$/;
+// `\r?$` is load-bearing on a CRLF checkout: `blueprint.raw` is stored verbatim
+// and split on "\n", so every original line still carries a trailing `\r`. `.`
+// does not match a line terminator, so without `\r?` the anchor cannot match,
+// NO originals are collected, preservation bails, and matter.stringify's
+// re-quoted scalars survive — silently invalidating every recorded approval on
+// that checkout. `FRONTMATTER_MULTILINE_KEY` below already carries `\r?$`.
+const FRONTMATTER_SCALAR_LINE = /^([A-Za-z0-9_]+):[ \t]+\S.*\r?$/;
 function quoteGeneratedProgressScalar(serialized, progress) {
     if (!progress)
         return serialized;
@@ -108,7 +115,10 @@ function preserveOriginalFrontmatterScalars(serialized, originalRaw) {
     for (const line of originalFrontmatter.split("\n")) {
         const match = FRONTMATTER_SCALAR_LINE.exec(line);
         if (match && !SERIALIZE_OWNED_FRONTMATTER_KEYS.has(match[1])) {
-            originalScalars.set(match[1], line);
+            // Store without the source's line ending; the substitution below re-applies
+            // whichever ending the SERIALIZED document uses, so a CRLF original is
+            // never spliced into an LF document (or vice versa) as a mixed ending.
+            originalScalars.set(match[1], line.replace(/\r$/, ""));
         }
     }
     if (originalScalars.size === 0)
@@ -116,13 +126,30 @@ function preserveOriginalFrontmatterScalars(serialized, originalRaw) {
     const block = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(serialized);
     if (!block)
         return serialized;
-    const rebuilt = block[2]
-        .split("\n")
-        .map((line) => {
+    const lines = block[2].split("\n");
+    const rebuiltLines = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
         const match = FRONTMATTER_SCALAR_LINE.exec(line);
-        return (match && originalScalars.get(match[1])) || line;
-    })
-        .join("\n");
+        const originalScalar = match && originalScalars.get(match[1]);
+        if (!originalScalar) {
+            rebuiltLines.push(line);
+            continue;
+        }
+        rebuiltLines.push(line.endsWith("\r") ? `${originalScalar}\r` : originalScalar);
+        // A freshly re-dumped value for this key may not fit on one line: long
+        // plain/quoted scalars get YAML-folded by js-yaml into indented
+        // continuation lines directly beneath the `key:` line (no `key:` prefix
+        // of their own). We are replacing the whole value wholesale with the
+        // original single-line scalar, so those continuation lines must be
+        // dropped too — otherwise they survive as an orphaned mapping fragment
+        // right after an already-complete (and possibly already-quote-closed)
+        // scalar, which is invalid YAML.
+        while (index + 1 < lines.length && /^[ \t]/.test(lines[index + 1])) {
+            index += 1;
+        }
+    }
+    const rebuilt = rebuiltLines.join("\n");
     return `${serialized.slice(0, block.index)}${block[1]}${rebuilt}${block[3]}${serialized.slice(block.index + block[0].length)}`;
 }
 // Same residual as scalars, for multi-line blocks (YAML arrays/maps under a
@@ -328,11 +355,10 @@ function extractDepends(section) {
     return ids.filter((id) => id !== "");
 }
 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();
-    if (blockedText === "" || blockedText.toLowerCase() === "none") {
+    if (blockedText.toLowerCase() === "none") {
         return undefined;
     }
     return blockedText;

package/dist/esm/blueprint/execution/artifacts.js

@@ -29,16 +29,20 @@ export function readBlueprintExecutionArtifacts(markdown) {
     };
 }
 export function writeBlueprintExecutionArtifacts(markdown, artifacts) {
-    return setBlueprintFrontmatterFields(markdown, {
+    // Typed against the shared key union so a key can never be written here
+    // without also entering the plan-subject normalizer's strip set.
+    const fields = {
         execution_artifacts: artifacts.artifacts,
         execution_log_path: artifacts.logPath,
         execution_verifications: artifacts.verifications,
-    });
+    };
+    return setBlueprintFrontmatterFields(markdown, fields);
 }
 export function clearBlueprintExecutionArtifacts(markdown) {
-    return setBlueprintFrontmatterFields(markdown, {
+    const fields = {
         execution_artifacts: undefined,
         execution_log_path: undefined,
         execution_verifications: undefined,
-    });
+    };
+    return setBlueprintFrontmatterFields(markdown, fields);
 }

package/dist/esm/blueprint/execution/frontmatter-keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Single owner of the `execution_*` blueprint frontmatter key names.
+ *
+ * The execution backend writes these keys into `_overview.md`
+ * (`./metadata.js`, `./artifacts.js`), and the plan-subject normalizer
+ * (`#review/subject.js`) strips them so starting or advancing an execution does
+ * not dismiss a recorded plan approval. Both sides import this list, so a key
+ * added to one side without the other is a typecheck error rather than a silent
+ * digest leak.
+ *
+ * Deliberately dependency-free so the normalizer can import it without pulling
+ * in the lifecycle engine.
+ */
+export declare const EXECUTION_METADATA_FRONTMATTER_KEYS: readonly ["execution_backend", "execution_id", "execution_status", "execution_updated_at"];
+export type ExecutionMetadataFrontmatterKey = (typeof EXECUTION_METADATA_FRONTMATTER_KEYS)[number];
+export declare const EXECUTION_ARTIFACTS_FRONTMATTER_KEYS: readonly ["execution_artifacts", "execution_log_path", "execution_verifications"];
+export type ExecutionArtifactsFrontmatterKey = (typeof EXECUTION_ARTIFACTS_FRONTMATTER_KEYS)[number];

package/dist/esm/blueprint/execution/frontmatter-keys.js

@@ -0,0 +1,24 @@
+/**
+ * Single owner of the `execution_*` blueprint frontmatter key names.
+ *
+ * The execution backend writes these keys into `_overview.md`
+ * (`./metadata.js`, `./artifacts.js`), and the plan-subject normalizer
+ * (`#review/subject.js`) strips them so starting or advancing an execution does
+ * not dismiss a recorded plan approval. Both sides import this list, so a key
+ * added to one side without the other is a typecheck error rather than a silent
+ * digest leak.
+ *
+ * Deliberately dependency-free so the normalizer can import it without pulling
+ * in the lifecycle engine.
+ */
+export const EXECUTION_METADATA_FRONTMATTER_KEYS = [
+    "execution_backend",
+    "execution_id",
+    "execution_status",
+    "execution_updated_at",
+];
+export const EXECUTION_ARTIFACTS_FRONTMATTER_KEYS = [
+    "execution_artifacts",
+    "execution_log_path",
+    "execution_verifications",
+];

package/dist/esm/blueprint/execution/metadata.js

@@ -28,18 +28,22 @@ export function readBlueprintExecutionMetadata(markdown) {
     };
 }
 export function writeBlueprintExecutionMetadata(markdown, metadata) {
-    return setBlueprintFrontmatterFields(markdown, {
+    // Typed against the shared key union so a key can never be written here
+    // without also entering the plan-subject normalizer's strip set.
+    const fields = {
         execution_backend: metadata.backend,
         execution_id: metadata.executionId,
         execution_status: metadata.status,
         execution_updated_at: metadata.updatedAt,
-    });
+    };
+    return setBlueprintFrontmatterFields(markdown, fields);
 }
 export function clearBlueprintExecutionMetadata(markdown) {
-    return setBlueprintFrontmatterFields(markdown, {
+    const fields = {
         execution_backend: undefined,
         execution_id: undefined,
         execution_status: undefined,
         execution_updated_at: undefined,
-    });
+    };
+    return setBlueprintFrontmatterFields(markdown, fields);
 }

package/dist/esm/blueprint/lifecycle/audit.d.ts

@@ -47,6 +47,27 @@ export interface ApprovalGateEvaluation {
     satisfied: boolean;
     strongReviewers: string[];
 }
+/**
+ * Whether to explain a skipped legacy approval leg to the caller.
+ *
+ * Exported so the decision is unit-testable without standing up a v2 ledger
+ * fixture. Two properties matter and neither is obvious from the call site:
+ *
+ * 1. Never fail silently. Before this message existed a skipped leg reported as a
+ *    bare "0 approvals" with no reason, which is the most expensive failure mode
+ *    in this area.
+ * 2. Never cry wolf. A post-rollout blueprint that already holds content-bound v2
+ *    authority and merely still carries a leftover frontmatter entry needs no
+ *    message: the leg was not required. `validateApprovalGate` turns sink entries
+ *    into `Review evidence integrity:` WARNINGS on an otherwise-passing audit, so
+ *    an unconditional note would flag clean strict runs as suspect.
+ */
+export declare function shouldExplainSkippedLegacyLeg(input: {
+    readonly legacyLegApplies: boolean;
+    readonly includesPlanPurpose: boolean;
+    readonly approvals: unknown;
+    readonly currentReviewers: readonly string[];
+}): boolean;
 export declare function countDistinctProvenanceBackedApprovals(file: string, approvals: unknown): number;
 export declare function evaluateApprovalGate(file: string, approvals: unknown, options?: {
     readonly purpose?: "plan" | "delivery";

package/dist/esm/blueprint/lifecycle/audit.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import matter from "gray-matter";
@@ -13,7 +14,7 @@ import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { parseBlueprintDocumentRelativePath } from "#utils/document-paths.js";
 import { relativeBlueprintSlug } from "#lifecycle/local.js";
 import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, stableSlugForBlueprintFile, } from "#lifecycle/review-provenance.js";
-import { isBlueprintExemptFromRollout, ROLLOUT_DATE } from "#lifecycle/rollout-anchor.js";
+import { isBlueprintExemptFromRollout, LEGACY_APPROVAL_LEG_ANCHOR_COMMIT, LEGACY_APPROVAL_LEG_ROLLOUT_DATE, ROLLOUT_DATE, } from "#lifecycle/rollout-anchor.js";
 import { MAINTAINER_OVERRIDE_REVIEWER } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 function isBlueprintOverview(file) {
@@ -106,14 +107,99 @@ function approvalReviewerKey(reviewer) {
     const parts = normalized.split(/[/:@#]/).filter(Boolean);
     return parts.at(-1) ?? normalized;
 }
+/**
+ * `created:` as written in the blueprint's own frontmatter.
+ *
+ * Only consulted on the non-agent-kit fallback path inside
+ * {@link isBlueprintExemptFromRollout} (where the anchor commit is absent and
+ * cannot answer the question), so the fact that the gated author writes this
+ * value does not weaken the gate where it is enforced. Read from disk rather than
+ * threaded through {@link evaluateApprovalGate}'s ten call sites: a call site
+ * that forgot the parameter would silently fail the leg closed and block
+ * promotion on a grandfathered blueprint.
+ */
+function readBlueprintCreated(file) {
+    try {
+        return matter(readFileSync(file, "utf8")).data.created;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when this blueprint may still satisfy the approval gate through the
+ * LEGACY frontmatter `approvals:` leg.
+ *
+ * That leg carries no content binding: `collectTrackedReviewProvenance` resolves
+ * a ledger from `approval.evidence`, matches a `reviews.md` record and requires a
+ * tracked artifact, but never reads or hashes the blueprint body — and the gate
+ * supplies no `targetHash`, so `matchesApproval`'s binding clause is skipped too.
+ * An approval recorded against one plan therefore kept satisfying the gate after
+ * the plan was rewritten into something else entirely.
+ *
+ * The leg is grandfathered rather than deleted because 172 already-landed
+ * blueprints resolve their approval through it; failing those would block
+ * ordinary work (a completed blueprint touched again in a PR is re-gated). New
+ * blueprints get the fail-closed behaviour: their authority must come from the
+ * content-addressed v2 `review-events.jsonl` ledger, which `wp review gate` and
+ * `wp review override` already write.
+ *
+ * `approval.targetHash`/`commit`/`rev` do NOT make an approval content-bound —
+ * those fields only cross-check the approval against its `reviews.md` record
+ * (`matchesApproval`), and neither is ever compared against document content. So
+ * presence of a binding-looking field is deliberately not an escape from this
+ * check.
+ */
+function legacyApprovalLegIsGrandfathered(file) {
+    return isBlueprintExemptFromRollout({
+        repoRoot: findGitRoot(file),
+        slug: stableSlugForBlueprintFile(file),
+        created: readBlueprintCreated(file),
+        rolloutDate: LEGACY_APPROVAL_LEG_ROLLOUT_DATE,
+        anchorCommit: LEGACY_APPROVAL_LEG_ANCHOR_COMMIT,
+    });
+}
+function hasPolicyApprovalEntry(approvals) {
+    return normalizeTrackedReviewApprovals(approvals).some((entry) => isPolicyApprovalVerdict(entry.verdict));
+}
+/**
+ * Whether to explain a skipped legacy approval leg to the caller.
+ *
+ * Exported so the decision is unit-testable without standing up a v2 ledger
+ * fixture. Two properties matter and neither is obvious from the call site:
+ *
+ * 1. Never fail silently. Before this message existed a skipped leg reported as a
+ *    bare "0 approvals" with no reason, which is the most expensive failure mode
+ *    in this area.
+ * 2. Never cry wolf. A post-rollout blueprint that already holds content-bound v2
+ *    authority and merely still carries a leftover frontmatter entry needs no
+ *    message: the leg was not required. `validateApprovalGate` turns sink entries
+ *    into `Review evidence integrity:` WARNINGS on an otherwise-passing audit, so
+ *    an unconditional note would flag clean strict runs as suspect.
+ */
+export function shouldExplainSkippedLegacyLeg(input) {
+    return (!input.legacyLegApplies &&
+        input.includesPlanPurpose &&
+        hasPolicyApprovalEntry(input.approvals) &&
+        !evaluateApprovalReviewers(input.currentReviewers).satisfied);
+}
 function provenanceBackedApprovalReviewers(file, approvals, options = {}) {
     const purposes = options.purpose
         ? [options.purpose]
         : ["plan", "delivery"];
-    const legacy = purposes.includes("plan")
+    const current = purposes.flatMap((purpose) => collectV2ReviewProvenance(file, purpose, "HEAD", options.issuesSink).map((record) => record.reviewer));
+    const legacyLegApplies = purposes.includes("plan") && legacyApprovalLegIsGrandfathered(file);
+    if (shouldExplainSkippedLegacyLeg({
+        legacyLegApplies,
+        includesPlanPurpose: purposes.includes("plan"),
+        approvals,
+        currentReviewers: current,
+    })) {
+        options.issuesSink?.push("legacy frontmatter approval entries are not accepted for this blueprint: the unbound `approvals:` leg is grandfathered only for slugs tracked at the legacy-approval rollout anchor. Record the approval through `wp review gate` so it binds to the reviewed content.");
+    }
+    const legacy = legacyLegApplies
         ? collectTrackedReviewProvenance(file, approvals, options).map((record) => record.reviewer)
         : [];
-    const current = purposes.flatMap((purpose) => collectV2ReviewProvenance(file, purpose, "HEAD", options.issuesSink).map((record) => record.reviewer));
     return new Set([...legacy, ...current]);
 }
 export function countDistinctProvenanceBackedApprovals(file, approvals) {

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;