@webpresso/agent-kit 3.3.2 → 3.3.4

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,7 +6,8 @@
  */
 import matter from "gray-matter";
 import { planFrontmatterSchema, taskStatusSchema } from "#core/schema";
-import { buildTaskHeadingRegex } from "#markdown/task-heading";
+import { extractBlockedReason } from "#markdown/blocked-line";
+import { buildTaskHeadingRegex, isTaskHeaderLine } from "#markdown/task-heading";
 function parseWithSchema(markdown, schema) {
     const { data: rawData, content } = matter(markdown);
     const data = schema.parse(rawData);
@@ -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,18 +355,15 @@ 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;
 }
-function isTaskHeader(line) {
-    return /^####\s+(?:\[[^\]]+\]\s+)?Task\s+\d+(?:\.\d+)+:/.test(line);
-}
+const isTaskHeader = isTaskHeaderLine;
 function isMetadataLine(line) {
     return /^\*\*(Depends|Blocked|Status):\*\*/i.test(line);
 }

package/dist/esm/blueprint/core/validation/criteria.js

@@ -1,8 +1,9 @@
 /**
  * Check acceptance criteria completion in plan markdown.
  */
+import { buildTaskHeadingRegex } from "#markdown/task-heading";
 const CHECKBOX_REGEX = /^- \[([ x])\]/gm;
-const TASK_HEADER_REGEX = /^####\s+(?:\[[^\]]+\]\s+)?Task\s+\d+(?:\.\d+)+:.*$/gm;
+const TASK_HEADER_REGEX = buildTaskHeadingRegex("gm");
 const TASK_DONE_OR_DROPPED_REGEX = /^\*\*Status:\*\*\s*(done|dropped)\s*$/im;
 const SECTION_BOUNDARY_REGEX = /\n##\s|\n---\n/;
 export function checkAcceptanceCriteria(markdown) {

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