@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/review/lifecycle-writers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Registry of every blueprint-document writer, classified by whether it leaves a
+ * recorded plan approval intact.
+ *
+ * The recurring bug class is "a lifecycle writer touches a region the plan-subject
+ * normalizer does not neutralize". Each recurrence looked different (a frontmatter
+ * key, a readiness stamp, a task status, a 5-cell gate row) but the shape was
+ * always the same, and every hand-maintained list of writers used to catch it
+ * drifted out of date — including a hand-written test mirror of one writer that
+ * implemented only half of it.
+ *
+ * So the writer list here is not a literal list of names. `discoverLifecycleWriterCandidates`
+ * derives it from source: every non-test top-level function under the blueprint
+ * mutation surface whose signature is a document transformer (takes
+ * `markdown`/`content`/`text: string`, returns `string`). The suite then requires
+ * every discovered candidate to be classified in `LIFECYCLE_WRITER_REGISTRY`, so a
+ * new writer added without a classification fails CI by construction.
+ *
+ * Classifications:
+ *
+ * - `digest-neutral` — asserted `digest(doc) === digest(apply(doc))` across a
+ *   corpus spanning every supported Promotion Gates row shape.
+ * - `known-leak` — asserted to REALLY change the digest, so the classification
+ *   cannot rot into an unchecked excuse, and required to carry a written reason.
+ * - `excluded` — not a document writer (parser helper, generic combinator, or a
+ *   private function exercised through a registered composite). Requires a reason.
+ */
+/**
+ * Source roots that make up the blueprint mutation surface. A document writer
+ * added anywhere under these paths is discovered automatically.
+ */
+export declare const LIFECYCLE_WRITER_SCAN_ROOTS: readonly string[];
+export interface LifecycleWriterCandidate {
+    /** Repo-relative module path, POSIX separators. */
+    readonly module: string;
+    /** Declared function name. */
+    readonly fn: string;
+    readonly exported: boolean;
+}
+export type LifecycleWriterEntry = {
+    readonly module: string;
+    readonly fn: string;
+    readonly classification: "digest-neutral";
+    readonly apply: (markdown: string) => string;
+    readonly note?: string;
+} | {
+    readonly module: string;
+    readonly fn: string;
+    readonly classification: "known-leak";
+    readonly apply: (markdown: string) => string;
+    readonly reason: string;
+} | {
+    readonly module: string;
+    readonly fn: string;
+    readonly classification: "excluded";
+    readonly reason: string;
+};
+/** Stable identity of a writer, used to match candidates against the registry. */
+export declare function lifecycleWriterId(entry: {
+    module: string;
+    fn: string;
+}): string;
+/**
+ * Every document-transformer function declared under the blueprint mutation
+ * surface, derived from source rather than hand-listed.
+ */
+export declare function discoverLifecycleWriterCandidates(repoRoot: string): readonly LifecycleWriterCandidate[];
+export declare const LIFECYCLE_WRITER_REGISTRY: readonly LifecycleWriterEntry[];
+/**
+ * Writers currently known to break a recorded plan approval. Empty: every
+ * document writer under the blueprint mutation surface is now asserted
+ * digest-neutral. Frozen at empty so that a new leak cannot be waved through as
+ * "another one of those" — growing this set is an explicit, reviewable registry
+ * edit, and the suite refuses a `known-leak` entry that does not actually leak.
+ */
+export declare const KNOWN_LEAK_WRITER_IDS: readonly string[];

package/dist/esm/review/lifecycle-writers.js

@@ -0,0 +1,330 @@
+/**
+ * Registry of every blueprint-document writer, classified by whether it leaves a
+ * recorded plan approval intact.
+ *
+ * The recurring bug class is "a lifecycle writer touches a region the plan-subject
+ * normalizer does not neutralize". Each recurrence looked different (a frontmatter
+ * key, a readiness stamp, a task status, a 5-cell gate row) but the shape was
+ * always the same, and every hand-maintained list of writers used to catch it
+ * drifted out of date — including a hand-written test mirror of one writer that
+ * implemented only half of it.
+ *
+ * So the writer list here is not a literal list of names. `discoverLifecycleWriterCandidates`
+ * derives it from source: every non-test top-level function under the blueprint
+ * mutation surface whose signature is a document transformer (takes
+ * `markdown`/`content`/`text: string`, returns `string`). The suite then requires
+ * every discovered candidate to be classified in `LIFECYCLE_WRITER_REGISTRY`, so a
+ * new writer added without a classification fails CI by construction.
+ *
+ * Classifications:
+ *
+ * - `digest-neutral` — asserted `digest(doc) === digest(apply(doc))` across a
+ *   corpus spanning every supported Promotion Gates row shape.
+ * - `known-leak` — asserted to REALLY change the digest, so the classification
+ *   cannot rot into an unchecked excuse, and required to carry a written reason.
+ * - `excluded` — not a document writer (parser helper, generic combinator, or a
+ *   private function exercised through a registered composite). Requires a reason.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { clearBlueprintExecutionArtifacts, writeBlueprintExecutionArtifacts, } from "#execution/artifacts.js";
+import { clearBlueprintExecutionMetadata, writeBlueprintExecutionMetadata, } from "#execution/metadata.js";
+import { setBlueprintFrontmatterFields } from "#lifecycle/engine.js";
+import { checkAllCheckboxes, checkFirstCheckbox, completeTask, updateBlockedReason, updateTaskStatus, } from "#markdown/helpers.js";
+import { updateGateLastResult, upsertReadinessValue } from "#trust/promotion.js";
+import { applyVerification } from "#verification.js";
+import { updateFrontmatterStatus, upsertCompletedAt } from "#cli/commands/blueprint/mutations.js";
+/**
+ * Source roots that make up the blueprint mutation surface. A document writer
+ * added anywhere under these paths is discovered automatically.
+ */
+export const LIFECYCLE_WRITER_SCAN_ROOTS = [
+    "src/blueprint",
+    "src/cli/commands/blueprint",
+    "src/mcp/blueprint",
+];
+/**
+ * Parameter names this repo uses for "the whole blueprint document". Kept
+ * deliberately broad so a writer cannot dodge discovery by renaming its
+ * parameter.
+ */
+const DOCUMENT_PARAMETER_NAMES = ["markdown", "content", "text"];
+const DOCUMENT_PARAMETER_PATTERN = new RegExp(`\\b(?:${DOCUMENT_PARAMETER_NAMES.join("|")})\\s*:\\s*string`, "u");
+const FUNCTION_DECLARATION_PATTERN = /(^|\n)(export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)\s*\(/gu;
+/** Stable identity of a writer, used to match candidates against the registry. */
+export function lifecycleWriterId(entry) {
+    return `${entry.module}::${entry.fn}`;
+}
+function isScannableSource(name) {
+    return (name.endsWith(".ts") &&
+        !name.endsWith(".test.ts") &&
+        !name.endsWith(".d.ts") &&
+        !name.endsWith("test-harness.ts"));
+}
+function collectSourceFiles(directory, out) {
+    for (const name of readdirSync(directory)) {
+        const full = path.join(directory, name);
+        if (statSync(full).isDirectory())
+            collectSourceFiles(full, out);
+        else if (isScannableSource(name))
+            out.push(full);
+    }
+}
+/** Signature text between the declaration's parentheses, plus its return type. */
+function readSignature(source, declarationEnd) {
+    const openParen = source.indexOf("(", declarationEnd);
+    let depth = 0;
+    let cursor = openParen;
+    for (; cursor < source.length; cursor += 1) {
+        const character = source[cursor];
+        if (character === "(")
+            depth += 1;
+        else if (character === ")") {
+            depth -= 1;
+            if (depth === 0)
+                break;
+        }
+    }
+    const brace = source.indexOf("{", cursor);
+    return {
+        params: source.slice(openParen + 1, cursor),
+        ret: source
+            .slice(cursor + 1, brace)
+            .replace(/^:\s*/u, "")
+            .trim(),
+    };
+}
+/**
+ * Every document-transformer function declared under the blueprint mutation
+ * surface, derived from source rather than hand-listed.
+ */
+export function discoverLifecycleWriterCandidates(repoRoot) {
+    const candidates = [];
+    for (const root of LIFECYCLE_WRITER_SCAN_ROOTS) {
+        const files = [];
+        collectSourceFiles(path.join(repoRoot, root), files);
+        for (const file of files) {
+            const source = readFileSync(file, "utf8");
+            const pattern = new RegExp(FUNCTION_DECLARATION_PATTERN.source, "gu");
+            let match = pattern.exec(source);
+            while (match) {
+                const { params, ret } = readSignature(source, match.index + (match[1] ?? "").length);
+                if (ret === "string" && DOCUMENT_PARAMETER_PATTERN.test(params)) {
+                    candidates.push({
+                        module: path.relative(repoRoot, file).split(path.sep).join("/"),
+                        fn: match[3] ?? "",
+                        exported: Boolean(match[2]),
+                    });
+                }
+                match = pattern.exec(source);
+            }
+        }
+    }
+    return candidates.toSorted((left, right) => lifecycleWriterId(left).localeCompare(lifecycleWriterId(right)));
+}
+const TASK_ID = "1.1";
+const PASSING_TEST_EVIDENCE = [
+    {
+        kind: "test",
+        result: "pass",
+        ts: "2026-07-25T00:00:00.000Z",
+        command: "wp test",
+        exit_code: 0,
+    },
+];
+const EXECUTION_METADATA = {
+    backend: "local-worktree",
+    executionId: "exec-1",
+    status: "running",
+    updatedAt: "2026-07-25T00:00:00.000Z",
+};
+const EXECUTION_ARTIFACTS = {
+    artifacts: ["dist/report.json"],
+    logPath: ".webpresso/logs/exec-1.log",
+    verifications: ["1.1"],
+};
+export const LIFECYCLE_WRITER_REGISTRY = [
+    // ---- Promotion / lifecycle frontmatter and trust stamps -----------------
+    {
+        module: "src/cli/commands/blueprint/mutations.ts",
+        fn: "updateFrontmatterStatus",
+        classification: "digest-neutral",
+        apply: (markdown) => updateFrontmatterStatus(markdown, "planned"),
+    },
+    {
+        module: "src/cli/commands/blueprint/mutations.ts",
+        fn: "upsertCompletedAt",
+        classification: "digest-neutral",
+        apply: (markdown) => upsertCompletedAt(markdown, "2026-07-25"),
+    },
+    {
+        module: "src/blueprint/trust/promotion.ts",
+        fn: "upsertReadinessValue",
+        classification: "digest-neutral",
+        apply: (markdown) => upsertReadinessValue(markdown, "verified-at", "2026-07-25T00:00:00.000Z"),
+    },
+    {
+        module: "src/blueprint/trust/promotion.ts",
+        fn: "updateGateLastResult",
+        classification: "digest-neutral",
+        apply: (markdown) => updateGateLastResult(markdown, "Lint", "pass at 2026-07-25T00:00:00.000Z"),
+    },
+    {
+        module: "src/blueprint/lifecycle/engine.ts",
+        fn: "setBlueprintFrontmatterFields",
+        classification: "digest-neutral",
+        apply: (markdown) => setBlueprintFrontmatterFields(markdown, {
+            progress: "50% (1/2 tasks done, 0 blocked, updated 2026-07-25)",
+            last_updated: "2026-07-25",
+            worktree_owner_id: "owner-abc123",
+            worktree_owner_branch: "bp/some-slug",
+        }),
+        note: "Exercised with the lifecycle intents its callers use; the keys are in the normalizer's strip set.",
+    },
+    // ---- Task execution state ----------------------------------------------
+    {
+        module: "src/blueprint/markdown/helpers.ts",
+        fn: "updateTaskStatus",
+        classification: "digest-neutral",
+        apply: (markdown) => updateTaskStatus(markdown, TASK_ID, "done"),
+    },
+    {
+        module: "src/blueprint/markdown/helpers.ts",
+        fn: "checkFirstCheckbox",
+        classification: "digest-neutral",
+        apply: (markdown) => checkFirstCheckbox(markdown, TASK_ID),
+    },
+    {
+        module: "src/blueprint/markdown/helpers.ts",
+        fn: "checkAllCheckboxes",
+        classification: "digest-neutral",
+        apply: (markdown) => checkAllCheckboxes(markdown, TASK_ID),
+    },
+    {
+        module: "src/blueprint/markdown/helpers.ts",
+        fn: "completeTask",
+        classification: "digest-neutral",
+        apply: (markdown) => completeTask(markdown, TASK_ID),
+    },
+    {
+        // Registered although it is not a discovered candidate (it returns a
+        // VerificationResult, not a string): it is the composite that actually runs
+        // on `wp_blueprint_task_verify`, and registering it is what lets the private
+        // `insertVerificationAfterStatus` / `removeVerificationFromTask` helpers be
+        // excluded honestly.
+        module: "src/blueprint/verification.ts",
+        fn: "applyVerification",
+        classification: "digest-neutral",
+        apply: (markdown) => {
+            const result = applyVerification(markdown, TASK_ID, PASSING_TEST_EVIDENCE);
+            if (!result.ok)
+                throw new Error(`applyVerification failed: ${result.failures.join("; ")}`);
+            return result.markdown;
+        },
+    },
+    {
+        module: "src/blueprint/markdown/helpers.ts",
+        fn: "updateBlockedReason",
+        classification: "digest-neutral",
+        apply: (markdown) => updateBlockedReason(markdown, TASK_ID, "waiting on an upstream release"),
+        note: "The `**Blocked:** <reason>` line it writes is stripped inside task sections by `neutralizeTaskBlockedReason`. Writer and normalizer share the grammar in src/blueprint/markdown/blocked-line.ts, so they cannot drift apart again.",
+    },
+    // ---- Execution metadata / artifacts (real _overview.md writers) ---------
+    {
+        module: "src/blueprint/execution/metadata.ts",
+        fn: "writeBlueprintExecutionMetadata",
+        classification: "digest-neutral",
+        apply: (markdown) => writeBlueprintExecutionMetadata(markdown, EXECUTION_METADATA),
+        note: "Its `execution_*` frontmatter keys are declared once in src/blueprint/execution/frontmatter-keys.ts, typed into this writer's field object and spread into the normalizer's strip set, so a new key cannot reach a document without also being stripped.",
+    },
+    {
+        module: "src/blueprint/execution/artifacts.ts",
+        fn: "writeBlueprintExecutionArtifacts",
+        classification: "digest-neutral",
+        apply: (markdown) => writeBlueprintExecutionArtifacts(markdown, EXECUTION_ARTIFACTS),
+        note: "Same shared key owner as writeBlueprintExecutionMetadata, for `execution_artifacts` / `execution_log_path` / `execution_verifications`.",
+    },
+    {
+        module: "src/blueprint/execution/metadata.ts",
+        fn: "clearBlueprintExecutionMetadata",
+        classification: "digest-neutral",
+        apply: (markdown) => clearBlueprintExecutionMetadata(writeBlueprintExecutionMetadata(markdown, EXECUTION_METADATA)),
+        note: "Asserted as the exact inverse of its writer: write-then-clear restores the original digest.",
+    },
+    {
+        module: "src/blueprint/execution/artifacts.ts",
+        fn: "clearBlueprintExecutionArtifacts",
+        classification: "digest-neutral",
+        apply: (markdown) => clearBlueprintExecutionArtifacts(writeBlueprintExecutionArtifacts(markdown, EXECUTION_ARTIFACTS)),
+        note: "Asserted as the exact inverse of its writer: write-then-clear restores the original digest.",
+    },
+    // ---- Not document writers ----------------------------------------------
+    {
+        module: "src/blueprint/lifecycle/engine.ts",
+        fn: "applyTaskIntent",
+        classification: "excluded",
+        reason: "Private composite: delegates entirely to updateTaskStatus, updateBlockedReason, and applyVerification, all registered above.",
+    },
+    {
+        module: "src/blueprint/execution/progress-bridge.ts",
+        fn: "applyIntent",
+        classification: "excluded",
+        reason: "Private composite: delegates to applyBlueprintLifecycle, whose document writes are the registered primitives above.",
+    },
+    {
+        module: "src/blueprint/verification.ts",
+        fn: "insertVerificationAfterStatus",
+        classification: "excluded",
+        reason: "Private helper, exercised through the registered applyVerification entry.",
+    },
+    {
+        module: "src/blueprint/verification.ts",
+        fn: "removeVerificationFromTask",
+        classification: "excluded",
+        reason: "Private helper, exercised through the registered applyVerification entry.",
+    },
+    {
+        module: "src/blueprint/verification.ts",
+        fn: "mapTaskSection",
+        classification: "excluded",
+        reason: "Generic combinator that applies a caller-supplied transform to one task section; it owns no lifecycle field of its own.",
+    },
+    {
+        module: "src/blueprint/trust/gate-row.ts",
+        fn: "mapPromotionGateRows",
+        classification: "excluded",
+        reason: "Generic combinator that applies a caller-supplied transform to Promotion Gates rows; its two callers (updateGateLastResult and neutralizePromotionGateResults) are what must agree, and the writer side is registered above.",
+    },
+    {
+        module: "src/blueprint/trust/dossier.ts",
+        fn: "stripFencedCodeBlocks",
+        classification: "excluded",
+        reason: "Parser helper: produces a derived string for Trust Dossier parsing that is never written back to disk.",
+    },
+    {
+        module: "src/blueprint/tech-debt/parser.ts",
+        fn: "extractTitle",
+        classification: "excluded",
+        reason: "Reads a tech-debt document (`h-NNN-slug.md`), not a blueprint overview, and returns a title rather than a document.",
+    },
+    {
+        module: "src/blueprint/trust/command-runner.ts",
+        fn: "tailBounded",
+        classification: "excluded",
+        reason: "Bounds captured subprocess output for an error message; never touches a blueprint document.",
+    },
+    {
+        module: "src/blueprint/context.ts",
+        fn: "clampText",
+        classification: "excluded",
+        reason: "Generic string truncation for context payloads; never writes a blueprint document.",
+    },
+];
+/**
+ * Writers currently known to break a recorded plan approval. Empty: every
+ * document writer under the blueprint mutation surface is now asserted
+ * digest-neutral. Frozen at empty so that a new leak cannot be waved through as
+ * "another one of those" — growing this set is an explicit, reviewable registry
+ * edit, and the suite refuses a `known-leak` entry that does not actually leak.
+ */
+export const KNOWN_LEAK_WRITER_IDS = LIFECYCLE_WRITER_REGISTRY.filter((entry) => entry.classification === "known-leak").map(lifecycleWriterId);

package/dist/esm/review/subject.js

@@ -1,5 +1,9 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { EXECUTION_ARTIFACTS_FRONTMATTER_KEYS, EXECUTION_METADATA_FRONTMATTER_KEYS, } from "#execution/frontmatter-keys.js";
+import { isBlockedLine } from "#markdown/blocked-line.js";
+import { isTaskHeaderLine } from "#markdown/task-heading.js";
+import { mapPromotionGateRows, setLastResultCell } from "#trust/gate-row.js";
 const GIT_PROBE_TIMEOUT_MS = 5_000;
 const GIT_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
 const DELIVERY_DOMAIN = Buffer.from("webpresso-review-subject\0v1\0", "ascii");
@@ -274,39 +278,16 @@ const PLAN_STATUS_PLACEHOLDER = "__wp-lifecycle-status__";
 const PLAN_GATE_RESULT_PLACEHOLDER = "__wp-gate-result__";
 // Neutralize the Promotion Gates "Last result" stamps that
 // applyPromotionTrustGate rewrites (updateGateLastResult in
-// src/blueprint/trust/promotion.ts). Scoped to the `### Promotion Gates`
-// subsection; every 4-cell table row is rewritten with trimmed cells and a
-// placeholder result cell, mirroring the writer's own whitespace
-// canonicalization so pre- and post-promotion rows normalize identically.
+// src/blueprint/trust/promotion.ts). The row grammar and the section scope are
+// NOT restated here: both come from #trust/gate-row.js, which the writer
+// consumes too. That shared owner exists because the two sides previously
+// implemented the grammar twice and diverged on cell count, section scope,
+// trailing pipe, and trailing whitespace — each divergence letting a lifecycle
+// stamp survive into the digest and dismiss the approval the promotion gates on.
 // Deliberate NO_CODE_CHANGE semantics: whitespace-only table edits and "Last
 // result" values are not plan substance.
 function neutralizePromotionGateResults(text) {
-    const lines = text.split("\n");
-    let inGatesSection = false;
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index];
-        const trimmed = line.trim();
-        // Exact end-anchored heading match, mirroring the dossier parser's
-        // sectionBlock regex — "### Promotion Gates Notes" is NOT the owned section.
-        if (/^###\s+Promotion Gates\s*$/iu.test(line)) {
-            inGatesSection = true;
-            continue;
-        }
-        if (inGatesSection && /^#{1,6}\s/u.test(line)) {
-            inGatesSection = false;
-            continue;
-        }
-        if (!inGatesSection || !trimmed.startsWith("|") || !trimmed.endsWith("|"))
-            continue;
-        const cells = trimmed
-            .slice(1, -1)
-            .split("|")
-            .map((cell) => cell.trim());
-        if (cells.length !== 4)
-            continue;
-        lines[index] = `| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${PLAN_GATE_RESULT_PLACEHOLDER} |`;
-    }
-    return lines.join("\n");
+    return mapPromotionGateRows(text, (cells) => setLastResultCell(cells, PLAN_GATE_RESULT_PLACEHOLDER));
 }
 // Frontmatter keys removed wholesale by the normalizer (value + folded
 // continuation lines). Each mirrors exactly one lifecycle writer:
@@ -320,11 +301,27 @@ const PLAN_LIFECYCLE_STRIPPED_KEYS_CORE = [
     "worktree_owner_id",
     "worktree_owner_branch",
 ];
-// Current plan-subject strip set: core lifecycle keys plus advisory `tags`.
+// Current plan-subject strip set: core lifecycle keys, advisory `tags`, and the
+// `execution_*` keys the execution backend stamps.
+//
 // Tags are not plan substance; MCP put and CLI serialize disagree on array-item
 // quoting (`- "x"` vs `- x`). Approvals recorded before the tags strip must
 // still verify via `preTagsStripNormalizePlanSubjectContent`.
-const PLAN_LIFECYCLE_STRIPPED_KEYS = [...PLAN_LIFECYCLE_STRIPPED_KEYS_CORE, "tags"];
+//
+// The `execution_*` names come from `#execution/frontmatter-keys.js`, which the
+// writers in `#execution/metadata.js` / `#execution/artifacts.js` type their
+// field objects against — one owner, so a new execution key cannot enter the
+// document without also entering this strip set. They are added to the CURRENT
+// set only, never to `_CORE`: `_CORE` defines the frozen pre-tags compatibility
+// tier, and editing it would retroactively change digests that tier already
+// produced. Stripping a key no document carries is a no-op, and no tracked
+// blueprint carries an `execution_*` key today, so nothing is restated.
+const PLAN_LIFECYCLE_STRIPPED_KEYS = [
+    ...PLAN_LIFECYCLE_STRIPPED_KEYS_CORE,
+    "tags",
+    ...EXECUTION_METADATA_FRONTMATTER_KEYS,
+    ...EXECUTION_ARTIFACTS_FRONTMATTER_KEYS,
+];
 // Neutralize the lifecycle-owned frontmatter fields (`status:` value plus the
 // stripped keys above, including advisory `tags`) INSIDE the leading frontmatter block only. A body line
 // that merely looks like one of these (e.g. task text reading
@@ -393,8 +390,11 @@ function neutralizeReadinessStamps(text) {
 // lifecycle writer, scoped to the location that writer owns:
 // - frontmatter status/progress/owner fields (blueprint lifecycle mutations)
 // - frontmatter `completed_at:` line       (upsertCompletedAt)
+// - frontmatter `execution_*:` keys        (writeBlueprintExecutionMetadata /
+//   writeBlueprintExecutionArtifacts)
 // - Readiness Verdict `- verified-at:`/`- verified-head:` items (upsertReadinessValue)
 // - Promotion Gates "Last result" cells (updateGateLastResult)
+// - task-section `**Blocked:** <reason>` lines (updateBlockedReason)
 // Any other byte change — task text, acceptance criteria, scope, lookalike
 // lines outside the owned locations — still changes the digest and dismisses
 // prior plan approvals.
@@ -437,12 +437,46 @@ function neutralizeTaskExecutionState(text) {
     }
     return out.join("\n");
 }
+// Remove the `**Blocked:** <reason>` line that `wp blueprint task block` writes
+// into a task section (updateBlockedReason). The line grammar comes from
+// `#markdown/blocked-line.js`, which the writer consumes too — same shared-owner
+// arrangement as the Promotion Gates row grammar, and for the same reason.
+//
+// Scoped to task sections, mirroring the only place the writer can insert it.
+// Unlike `**Status:**`, whose value is a closed enum, a blocked reason is free
+// text, so a document-wide rule would have no grammar left to keep it honest: a
+// Notes paragraph opening with the marker is plan substance and stays hashed.
+//
+// The writer emits the line followed by one blank line (insertAfterStatusLine
+// appends `line + "\n\n"`), so exactly one following blank line is removed with
+// it — that is the byte shape the writer owns, no more.
+function neutralizeTaskBlockedReason(text) {
+    const lines = text.split("\n");
+    const out = [];
+    let inTaskSection = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/^#{1,6}\s/u.test(line)) {
+            inTaskSection = isTaskHeaderLine(line);
+            out.push(line);
+            continue;
+        }
+        if (inTaskSection && isBlockedLine(line)) {
+            if ((lines[index + 1] ?? "").trim() === "")
+                index += 1;
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
 export function normalizePlanSubjectContent(content) {
     let text = typeof content === "string" ? content : content.toString("utf8");
     text = neutralizeLifecycleFrontmatter(text);
     text = neutralizeReadinessStamps(text);
     text = neutralizePromotionGateResults(text);
     text = neutralizeTaskExecutionState(text);
+    text = neutralizeTaskBlockedReason(text);
     return Buffer.from(text, "utf8");
 }
 /**

package/dist/esm/status/snapshot.d.ts

@@ -51,6 +51,10 @@ export declare const wpStatusSnapshotSchema: z.ZodObject<{
             path: z.ZodString;
             lifecycle: z.ZodString;
             approvalsSatisfied: z.ZodBoolean;
+            approvalsSatisfiedBy: z.ZodOptional<z.ZodEnum<{
+                delivery: "delivery";
+                plan: "plan";
+            }>>;
         }, z.core.$strip>>;
         ultragoal: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         reviews: z.ZodOptional<z.ZodObject<{
@@ -127,6 +131,7 @@ export interface PrReadinessEvidence {
         readonly path: string;
         readonly lifecycle: string;
         readonly approvalsSatisfied: boolean;
+        readonly approvalsSatisfiedBy?: "plan" | "delivery";
     };
 }
 interface ReadinessEvaluation {

package/dist/esm/status/snapshot.js

@@ -42,6 +42,9 @@ const statusContextSchema = z.object({
         path: z.string(),
         lifecycle: z.string(),
         approvalsSatisfied: z.boolean(),
+        // Which review purpose carried the satisfying approval ("plan" or
+        // "delivery"), so a satisfied/unsatisfied result is attributable.
+        approvalsSatisfiedBy: z.enum(["plan", "delivery"]).optional(),
     })
         .optional(),
     ultragoal: z.record(z.string(), z.unknown()).optional(),
@@ -319,6 +322,20 @@ function selectBlueprintFile(projectRoot, pr) {
     const priority = (file) => file.changeType === "ADDED" ? 0 : file.changeType === "RENAMED" ? 1 : 2;
     return candidates.toSorted((left, right) => priority(left) - priority(right))[0];
 }
+// The authoritative CI gate (`validateApprovalGate` -> `provenanceBackedApprovalReviewers`)
+// accepts an approval recorded for EITHER purpose: it defaults to
+// `["plan", "delivery"]` when no purpose is pinned. This advisory snapshot used to
+// query `"delivery"` only, so a blueprint approved at the plan boundary reported
+// `review-provenance` unsatisfied while CI passed on the same commit — an advisory
+// blocker stricter than the gate it advises about, which reads as a real problem.
+// Union both purposes here so the two agree.
+//
+// Deliberately NOT reusing `provenanceBackedApprovalReviewers` directly: that helper
+// resolves v2 provenance at `HEAD`, whereas this snapshot must answer for the PR's
+// exact target commit. Matching its purpose set while keeping `targetHash` is the
+// smallest change that makes the two evaluators agree without loosening exact-SHA
+// semantics.
+const APPROVAL_PURPOSES = ["plan", "delivery"];
 function resolveBlueprintEvidence(projectRoot, pr, targetHash) {
     const blueprintFile = selectBlueprintFile(projectRoot, pr);
     if (!blueprintFile || !targetHash)
@@ -327,12 +344,20 @@ function resolveBlueprintEvidence(projectRoot, pr, targetHash) {
         const authority = readReviewAuthorityAtRef(projectRoot, targetHash, blueprintFile.stableSlug, "delivery");
         if (authority.blueprintPath !== blueprintFile.path)
             return undefined;
-        const approvals = collectV2ReviewProvenance(path.resolve(projectRoot, blueprintFile.path), "delivery", targetHash);
+        const blueprintPath = path.resolve(projectRoot, blueprintFile.path);
+        const perPurpose = APPROVAL_PURPOSES.map((purpose) => ({
+            purpose,
+            reviewers: collectV2ReviewProvenance(blueprintPath, purpose, targetHash).map((approval) => approval.reviewer),
+        }));
+        const satisfiedPurpose = perPurpose.find((entry) => evaluateApprovalReviewers(entry.reviewers).satisfied);
         return {
             path: blueprintFile.path,
             lifecycle: authority.lifecycle,
-            approvalsSatisfied: evaluateApprovalReviewers(approvals.map((approval) => approval.reviewer))
+            approvalsSatisfied: evaluateApprovalReviewers(perPurpose.flatMap((entry) => entry.reviewers))
                 .satisfied,
+            // Which purpose carried the approval, so a red/green flip is attributable
+            // instead of opaque.
+            approvalsSatisfiedBy: satisfiedPurpose?.purpose,
         };
     }
     catch {

package/dist/esm/symlinker/consumers.d.ts

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -116,6 +116,8 @@ export declare function unifiedRuleFilename(consumer: UnifiedConsumerConfig, slu
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.