@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/audit/agents.js

@@ -1,20 +1,13 @@
 import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { readConfig } from "#cli/commands/init/config";
-import { DEFAULT_PACKAGED_SKILL_SLUG_SET } from "#content/skill-policy";
+import { AGENT_KIT_INTERNAL_SKILL_SLUGS, DEFAULT_PACKAGED_SKILL_SLUG_SET, DEFAULT_PACKAGED_SKILL_SLUGS, MERGED_DELETED_SKILL_SLUGS, UNPACKAGED_SKILL_SLUGS, } from "#content/skill-policy";
 import { readTrustedJsonFile } from "#shared-utils/read-json-file.js";
 import matter from "gray-matter";
 import { WP_HOOK_SPECS } from "#cli/commands/init/scaffolders/agent-hooks/ir.js";
 const REQUIRED_HOOKS = WP_HOOK_SPECS.map(({ event, bin }) => ({ event, bin }));
 const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
 const CODEX_HOOKS_PATH = ".codex/hooks.json";
-const REQUIRED_SUBAGENTS = [
-    "code-reviewer.md",
-    "security-auditor.md",
-    "doc-writer.md",
-    "explorer.md",
-    "implementer.md",
-];
 const EXPLORER_CONTRACT_MARKERS = [
     "3–5 tool calls",
     "Defs:",
@@ -54,6 +47,10 @@ export function auditAgents(rootDirectory = process.cwd()) {
         checkCatalogAgents(root, violations);
         checked += 1;
         checkCatalogReportOnlySkills(root, violations);
+        checked += 1;
+        checkSelfHostClaudeAgents(root, violations);
+        checked += 1;
+        checkCatalogSkillClassification(root, violations);
     }
     else {
         checked += 1;
@@ -117,6 +114,19 @@ function checkCatalogSkillHooks(root, violations) {
         }
     }
 }
+/**
+ * List the `.md` filenames (e.g. "code-reviewer.md") directly under a
+ * catalog/agent/agents-shaped directory, excluding README.md. Returns an
+ * empty array when the directory does not exist. This is the single source
+ * of truth for "which subagents are required" — no hardcoded list.
+ */
+function listCatalogAgentFiles(agentsSourceDir) {
+    if (!existsSync(agentsSourceDir))
+        return [];
+    return readdirSync(agentsSourceDir)
+        .filter((file) => file.endsWith(".md") && file !== "README.md")
+        .sort();
+}
 function checkCatalogAgents(root, violations) {
     const agentsSource = join(root, "catalog", "agent", "agents");
     if (!existsSync(agentsSource)) {
@@ -126,28 +136,44 @@ function checkCatalogAgents(root, violations) {
         });
         return;
     }
-    for (const file of REQUIRED_SUBAGENTS) {
+    const requiredFiles = listCatalogAgentFiles(agentsSource);
+    if (requiredFiles.length === 0) {
+        violations.push({
+            file: "catalog/agent/agents",
+            message: "catalog/agent/agents must contain canonical subagent markdown files.",
+        });
+        return;
+    }
+    for (const file of requiredFiles) {
+        if (file !== "explorer.md")
+            continue;
         const sourcePath = join(agentsSource, file);
-        if (!existsSync(sourcePath)) {
+        const content = readFileSync(sourcePath, "utf8");
+        for (const marker of EXPLORER_CONTRACT_MARKERS) {
+            if (content.includes(marker))
+                continue;
             violations.push({
                 file: relative(root, sourcePath),
-                message: `Missing canonical subagent ${file} in catalog/agent/agents.`,
+                message: `Explorer subagent output contract is missing marker: ${marker}`,
             });
-            continue;
-        }
-        if (file === "explorer.md") {
-            const content = readFileSync(sourcePath, "utf8");
-            for (const marker of EXPLORER_CONTRACT_MARKERS) {
-                if (content.includes(marker))
-                    continue;
-                violations.push({
-                    file: relative(root, sourcePath),
-                    message: `Explorer subagent output contract is missing marker: ${marker}`,
-                });
-            }
         }
     }
 }
+/**
+ * Self-host-only: validate `.claude/agents/` (this repo's own generated
+ * projection) the same way a consumer's `.claude/agents/` is validated.
+ * Absent is acceptable — the surface is generated + gitignored in a clean
+ * checkout — but when present, every catalog-required subagent must resolve
+ * to a live symlink.
+ */
+function checkSelfHostClaudeAgents(root, violations) {
+    const agentsTarget = join(root, ".claude", "agents");
+    if (!existsSync(agentsTarget))
+        return;
+    const agentsSource = join(root, "catalog", "agent", "agents");
+    const requiredFiles = listCatalogAgentFiles(agentsSource);
+    validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations);
+}
 function checkCatalogReportOnlySkills(root, violations) {
     const skillsSource = join(root, "catalog", "agent", "skills");
     if (!existsSync(skillsSource)) {
@@ -193,6 +219,63 @@ function checkCatalogReportOnlySkills(root, violations) {
         }
     }
 }
+/**
+ * Resolve the required subagent file list for a consumer repo. Preferred
+ * source: the installed catalog under node_modules (the real consumer-mode
+ * source of truth that `.claude/agents/*.md` symlinks point at). When
+ * node_modules is not installed (e.g. a partial checkout), fall back to
+ * whatever `.claude/agents/*.md` already exists so symlink-health checks
+ * still run without false-positiving "missing" for agents we have no
+ * catalog reference for.
+ */
+function resolveConsumerRequiredAgentFiles(root) {
+    const installedAgentsSource = join(root, "node_modules", "@webpresso", "agent-kit", "catalog", "agent", "agents");
+    const fromInstalled = listCatalogAgentFiles(installedAgentsSource);
+    if (fromInstalled.length > 0)
+        return fromInstalled;
+    const agentsTarget = join(root, ".claude", "agents");
+    if (!existsSync(agentsTarget))
+        return [];
+    // Restrict to symlinks only — a hand-authored real file (Claude Code's
+    // native subagent authoring surface) is never agent-kit-managed and must
+    // not be false-flagged as "must remain a symlink" just because node_modules
+    // isn't installed to prove otherwise.
+    return readdirSync(agentsTarget)
+        .filter((file) => file.endsWith(".md") && lstatSync(join(agentsTarget, file)).isSymbolicLink())
+        .sort();
+}
+/**
+ * Every catalog skill slug must be accounted for as either default-packaged,
+ * explicitly unpackaged (with a reason), merged/deleted, or an
+ * agent-kit-internal maintainer-only skill. An unclassified slug is a
+ * violation — it means a new catalog skill was added without a deliberate
+ * packaging decision.
+ */
+function checkCatalogSkillClassification(root, violations) {
+    const skillsSource = join(root, "catalog", "agent", "skills");
+    if (!existsSync(skillsSource))
+        return; // reported by checkCatalogReportOnlySkills
+    const knownSlugs = new Set([
+        ...DEFAULT_PACKAGED_SKILL_SLUGS,
+        ...Object.keys(UNPACKAGED_SKILL_SLUGS),
+        ...MERGED_DELETED_SKILL_SLUGS,
+        ...AGENT_KIT_INTERNAL_SKILL_SLUGS,
+    ]);
+    for (const entry of readdirSync(skillsSource, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!existsSync(join(skillsSource, entry.name, "SKILL.md")))
+            continue;
+        if (knownSlugs.has(entry.name))
+            continue;
+        violations.push({
+            file: `catalog/agent/skills/${entry.name}/SKILL.md`,
+            message: `Skill "${entry.name}" is not classified as packaged or unpackaged. Add it to ` +
+                "DEFAULT_PACKAGED_SKILL_SLUGS or UNPACKAGED_SKILL_SLUGS in src/content/skill-policy.ts " +
+                "with a one-line reason.",
+        });
+    }
+}
 function checkClaudeAgents(root, violations) {
     const agentsTarget = join(root, ".claude", "agents");
     if (!existsSync(agentsTarget)) {
@@ -202,16 +285,33 @@ function checkClaudeAgents(root, violations) {
         });
         return;
     }
-    for (const file of REQUIRED_SUBAGENTS) {
+    const requiredFiles = resolveConsumerRequiredAgentFiles(root);
+    validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations);
+}
+/**
+ * Shared per-file symlink validator for `.claude/agents/<file>`, used by both
+ * the self-host and consumer audit paths. Checks: missing entry, not a
+ * symlink, wrong/unrecognized target, and dangling target.
+ */
+function validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations) {
+    for (const file of requiredFiles) {
         const targetPath = join(agentsTarget, file);
-        if (!existsSync(targetPath)) {
+        // lstatSync (not existsSync) so a dangling symlink — an entry that
+        // exists but resolves to nothing — is distinguished from a genuinely
+        // missing entry. existsSync follows symlinks, so it would misreport
+        // every dangling symlink as "missing" and the dangling check below
+        // would never be reachable.
+        let stat;
+        try {
+            stat = lstatSync(targetPath);
+        }
+        catch {
             violations.push({
                 file: relative(root, targetPath),
                 message: `Missing Claude subagent ${file}. Run \`wp setup\` to re-sync canonical subagents.`,
             });
             continue;
         }
-        const stat = lstatSync(targetPath);
         if (!stat.isSymbolicLink()) {
             violations.push({
                 file: relative(root, targetPath),

package/dist/esm/audit/hook-surface.js

@@ -33,7 +33,11 @@ export function detectDrift(entries) {
         .map(([key, entries]) => ({ key, count: entries.length, entries }));
 }
 function isRewriter(command) {
-    return (command.includes("rtk hook claude") ||
+    // Managed pretool-guard emits updatedInput rewrites (exact git status → rtk).
+    // Classify it as a rewriter so freestanding RTK + pretool-guard collide in audit.
+    return (command.includes("wp-pretool-guard") ||
+        command.includes("wp hook pretool-guard") ||
+        command.includes("rtk hook claude") ||
         command.endsWith("pretooluse.mjs") ||
         command.includes("/pretooluse.mjs"));
 }

package/dist/esm/audit/repo-guardrails.d.ts

@@ -49,6 +49,14 @@ export declare function auditCatalogDrift(rootDirectory?: string, options?: Cata
 export declare function validateCommitMessage(message: string, options?: CommitMessageOptions): RepoAuditResult;
 export declare function auditCommitMessageFile(messageFile: string, options?: CommitMessageOptions): RepoAuditResult;
 export declare function auditDocsFrontmatter(rootDirectory?: string, options?: DocsFrontmatterOptions): RepoAuditResult;
+/**
+ * Flags a blueprint whose raw frontmatter clearly lists one or more
+ * `approvals:` entries but whose YAML-parsed `approvals` field yields zero —
+ * the corruption signature `wp blueprint move --force-recovery` produces
+ * when it silently destroys approval authority without making the document
+ * fail to parse outright.
+ */
+export declare function detectSuspiciousZeroApprovals(raw: string, frontmatter: Record<string, unknown>): string | undefined;
 export declare function auditBlueprintLifecycle(rootDirectory?: string, options?: BlueprintLifecycleOptions): RepoAuditResult;
 export declare function formatRepoAuditReport(auditResult: RepoAuditResult): string;
 export declare function parseFrontmatter(markdown: string): Record<string, string>;

package/dist/esm/audit/repo-guardrails.js

@@ -210,6 +210,53 @@ export function auditDocsFrontmatter(rootDirectory = process.cwd(), options = {}
     }
     return result("Docs frontmatter", markdownFiles.length, violations);
 }
+const APPROVALS_KEY_LINE = /^approvals:\s*$/m;
+/**
+ * Count `- ` list-item lines that follow a top-level `approvals:` key inside
+ * the RAW frontmatter text, stopping at the next top-level key. Returns -1
+ * when there is no `approvals:` key at all (nothing to check).
+ *
+ * This is deliberately independent of the YAML parser: it is the ground
+ * truth for "did the author intend approval entries here", used to catch a
+ * corrupted write where the YAML still happens to parse but the approvals
+ * mapping was silently truncated or displaced (e.g. a scalar-restore bug
+ * that inserts or drops lines near the approvals block).
+ */
+function countRawApprovalEntries(raw) {
+    const frontmatterBlock = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)?.[1] ?? "";
+    const keyIndex = frontmatterBlock.search(APPROVALS_KEY_LINE);
+    if (keyIndex === -1)
+        return -1;
+    const afterKey = frontmatterBlock.slice(keyIndex).split("\n").slice(1);
+    let count = 0;
+    for (const line of afterKey) {
+        if (/^[A-Za-z0-9_]+:/.test(line))
+            break;
+        if (/^\s*-\s/.test(line))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Flags a blueprint whose raw frontmatter clearly lists one or more
+ * `approvals:` entries but whose YAML-parsed `approvals` field yields zero —
+ * the corruption signature `wp blueprint move --force-recovery` produces
+ * when it silently destroys approval authority without making the document
+ * fail to parse outright.
+ */
+export function detectSuspiciousZeroApprovals(raw, frontmatter) {
+    const rawEntryCount = countRawApprovalEntries(raw);
+    if (rawEntryCount <= 0)
+        return undefined;
+    const parsedApprovals = frontmatter["approvals"];
+    const parsedCount = Array.isArray(parsedApprovals) ? parsedApprovals.length : 0;
+    if (parsedCount > 0)
+        return undefined;
+    return (`Frontmatter parses to 0 approvals but the raw YAML lists ${rawEntryCount} ` +
+        "approval entr" +
+        (rawEntryCount === 1 ? "y" : "ies") +
+        " — likely corrupted frontmatter near the approvals block.");
+}
 export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options = {}) {
     const root = resolve(rootDirectory);
     const blueprintsRoot = resolve(root, options.blueprintsRoot ?? "blueprints");
@@ -259,7 +306,30 @@ export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options =
                 continue;
             }
             const raw = readFileSync(canonicalPath, "utf8");
-            const frontmatter = matter(raw).data;
+            let frontmatter;
+            try {
+                frontmatter = matter(raw).data;
+            }
+            catch (error) {
+                // A blueprint write (e.g. `wp blueprint move --force-recovery`) can
+                // emit invalid YAML — most commonly a folded-scalar continuation
+                // line stranded after an already-quoted scalar. Every downstream
+                // reader (including the approval gate) then fails the same way this
+                // parse does, so surface it as a first-class violation instead of
+                // letting the whole audit crash on the first corrupted file.
+                violations.push({
+                    file: relativePath(root, canonicalPath),
+                    message: `Frontmatter failed to parse as YAML: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            const suspiciousApprovals = detectSuspiciousZeroApprovals(raw, frontmatter);
+            if (suspiciousApprovals) {
+                violations.push({
+                    file: relativePath(root, canonicalPath),
+                    message: suspiciousApprovals,
+                });
+            }
             if (frontmatter.type !== "blueprint" && frontmatter.type !== "parent-roadmap") {
                 violations.push({
                     file: relativePath(root, canonicalPath),

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) {