@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -6,6 +6,7 @@
  */
 import matter from "gray-matter";
 import { planFrontmatterSchema, taskStatusSchema } from "#core/schema";
+import { buildTaskHeadingRegex } from "#markdown/task-heading";
 function parseWithSchema(markdown, schema) {
     const { data: rawData, content } = matter(markdown);
     const data = schema.parse(rawData);
@@ -74,14 +75,109 @@ export function serializeBlueprint(blueprint) {
         delete data.completed_at;
     }
     const { tasks: _tasks, task_statuses: _task_statuses, ...cleanedData } = data;
-    return quoteGeneratedProgressScalar(matter.stringify(content, cleanedData), blueprint.progress);
+    const serialized = quoteGeneratedProgressScalar(matter.stringify(content, cleanedData), blueprint.progress);
+    return preserveOriginalFrontmatterMultiline(preserveOriginalFrontmatterScalars(serialized, blueprint.raw), blueprint.raw);
 }
+// Frontmatter keys serializeBlueprint intentionally rewrites; every other
+// scalar must survive a write byte-for-byte.
+const SERIALIZE_OWNED_FRONTMATTER_KEYS = new Set([
+    "status",
+    "complexity",
+    "last_updated",
+    "progress",
+    "completed_at",
+]);
+const FRONTMATTER_SCALAR_LINE = /^([A-Za-z0-9_]+):[ \t]+\S.*$/;
 function quoteGeneratedProgressScalar(serialized, progress) {
     if (!progress)
         return serialized;
     const escaped = progress.replace(/'/g, "''");
     return serialized.replace(/^progress: .+$/m, `progress: '${escaped}'`);
 }
+// `matter.stringify` re-dumps the whole frontmatter YAML, which canonicalizes
+// scalar quoting (e.g. `title: "X"` -> `title: X`, `owner: "claude"` ->
+// `owner: claude`). Those bytes feed the plan-subject digest, so a cosmetic
+// re-quote on a write silently invalidates a recorded review approval. Restore
+// the ORIGINAL single-line scalar verbatim for every field this serializer does
+// not own, so a status/progress write never disturbs `title`/`owner`/`created`
+// etc. Multi-line/array fields are restored separately by
+// preserveOriginalFrontmatterMultiline. Generalizes the earlier progress-only patch.
+function preserveOriginalFrontmatterScalars(serialized, originalRaw) {
+    const originalFrontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(originalRaw)?.[1] ?? "";
+    const originalScalars = new Map();
+    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);
+        }
+    }
+    if (originalScalars.size === 0)
+        return serialized;
+    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 match = FRONTMATTER_SCALAR_LINE.exec(line);
+        return (match && originalScalars.get(match[1])) || line;
+    })
+        .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
+// key with no inline value). `matter.stringify` re-dumps arrays and drops
+// item quotes (`- "review"` -> `- review`). MCP put and the CLI disagree on
+// that quoting; restore the ORIGINAL multi-line block for every non-owned key.
+// Allow optional CR on the key line so CRLF checkouts still match.
+const FRONTMATTER_MULTILINE_KEY = /^([A-Za-z0-9_]+):[ \t]*\r?$/;
+function preserveOriginalFrontmatterMultiline(serialized, originalRaw) {
+    const originalFrontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(originalRaw)?.[1] ?? "";
+    const originalBlocks = new Map();
+    const lines = originalFrontmatter.split("\n");
+    for (let index = 0; index < lines.length;) {
+        const match = FRONTMATTER_MULTILINE_KEY.exec(lines[index]);
+        if (!match) {
+            index += 1;
+            continue;
+        }
+        const key = match[1];
+        if (SERIALIZE_OWNED_FRONTMATTER_KEYS.has(key)) {
+            index += 1;
+            continue;
+        }
+        // Strip a trailing CR so joined blocks stay LF-normalized like the rest of the pipeline.
+        const blockLines = [lines[index].replace(/\r$/, "")];
+        index += 1;
+        while (index < lines.length && /^[ \t]/.test(lines[index])) {
+            blockLines.push(lines[index].replace(/\r$/, ""));
+            index += 1;
+        }
+        if (blockLines.length > 1) {
+            originalBlocks.set(key, blockLines.join("\n"));
+        }
+    }
+    if (originalBlocks.size === 0)
+        return serialized;
+    const wrapper = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(serialized);
+    if (!wrapper)
+        return serialized;
+    let body = wrapper[2];
+    for (const [key, originalBlock] of originalBlocks) {
+        // Match the serialized multi-line block. A trailing newline is optional when
+        // the block is the last key in the frontmatter body (wrapper[2] does not
+        // include the newline before `---`).
+        const pattern = new RegExp(String.raw `^${key}:[ \t]*\n(?:[ \t][^\n]*\n?)*`, "mu");
+        if (!pattern.test(body))
+            continue;
+        // Replacer function: avoid `$` re-interpretation of originalBlock contents,
+        // and only re-append a trailing newline when the match consumed one — otherwise
+        // a last-key `tags:` block gains a blank line before `---` and the plan digest
+        // flips on the first lifecycle write after MCP put (B1).
+        body = body.replace(pattern, (matched) => matched.endsWith("\n") ? `${originalBlock}\n` : originalBlock);
+    }
+    return `${serialized.slice(0, wrapper.index)}${wrapper[1]}${body}${wrapper[3]}${serialized.slice(wrapper.index + wrapper[0].length)}`;
+}
 function extractCheckboxStatus(section) {
     const checkboxRegex = /^- \[([ x])\]/gm;
     const matches = Array.from(section.matchAll(checkboxRegex));
@@ -136,7 +232,10 @@ function validateTaskFormat(content) {
     }
 }
 function extractTasks(content) {
-    const taskRegex = /^####\s+(?:\[[^\]]+\]\s+)?Task\s+(\d+(?:\.\d+)+):\s*(.+)$/gm;
+    // Built from #markdown/task-heading's shared pattern (also consumed by
+    // #core/schema's taskIdSchema) so the reader and the MCP put-task writer
+    // cannot drift apart on what counts as a valid task ID.
+    const taskRegex = buildTaskHeadingRegex();
     const matches = Array.from(content.matchAll(taskRegex));
     validateTaskFormat(content);
     return matches.map((match, index) => {

package/dist/esm/blueprint/core/schema.d.ts

@@ -77,6 +77,7 @@ export declare const crossRepoDependencySchema: z.ZodObject<{
         planned: "planned";
     }>>;
 }, z.core.$strip>;
+export declare const taskIdSchema: z.ZodString;
 /**
  * Plan frontmatter schema.
  *

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

@@ -11,6 +11,7 @@ import { z } from "zod";
  */
 import { executionBackendSchema } from "#types/execution-backend.js";
 export { executionBackendSchema } from "#types/execution-backend.js";
+import { TASK_ID_PATTERN as TASK_HEADING_TASK_ID_PATTERN } from "#markdown/task-heading";
 /**
  * Valid plan status values.
  * Maps to plan lifecycle: draft/planned/parked → in-progress → completed/archived.
@@ -58,6 +59,31 @@ export const crossRepoDependencySchema = z.object({
     slug: z.string().min(1),
     require_status: planStatusSchema.optional(),
 });
+/**
+ * Task-ID validator for MCP writer boundaries (e.g. `wp_blueprint_put`).
+ *
+ * Built from `#markdown/task-heading`'s `TASK_ID_PATTERN` — the existing
+ * single source of truth for the numeric-dotted task-ID shape (e.g. "1.1",
+ * "2.3.1") already consumed by `#core/parser`'s `extractTasks()` (via
+ * `buildTaskHeadingRegex()`) and by `verification.ts` / `markdown/helpers.ts`.
+ * Validating writer-supplied IDs against the same pattern the reader uses
+ * means the writer (MCP `put`) and the reader (parser) cannot drift apart —
+ * a non-numeric-dotted ID like "task-1" is rejected before it ever reaches
+ * markdown, instead of being silently unparseable afterward.
+ */
+const TASK_ID_ANCHORED_PATTERN = new RegExp(`^${TASK_HEADING_TASK_ID_PATTERN}$`);
+export const taskIdSchema = z
+    .string()
+    .min(1)
+    .superRefine((value, ctx) => {
+    if (!TASK_ID_ANCHORED_PATTERN.test(value)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Task IDs must be numeric dotted (e.g. "1.1", "2.3.1") — the blueprint parser only ` +
+                `recognizes "#### Task <numeric-dotted-id>:" headers. Use "1.1", got "${value}".`,
+        });
+    }
+});
 /**
  * Plan frontmatter schema.
  *

package/dist/esm/blueprint/core/validation/criteria.d.ts

@@ -3,3 +3,17 @@
  */
 import type { CriteriaResult } from "#core/types";
 export declare function checkAcceptanceCriteria(markdown: string): CriteriaResult;
+/**
+ * Count checked acceptance-criteria checkboxes that are NOT explained by an
+ * explicit `**Status:** done`/`dropped` line on their containing task.
+ *
+ * `completeTask()` (see `markdown/helpers.ts`) checks every checkbox inside
+ * a task's own section when that task is marked done — which is expected,
+ * honest progress tracking during `draft` (pretool-guard's `blueprint-first`
+ * validator explicitly allows implementing source while a blueprint is
+ * still draft). A checked box that is NOT inside a done/dropped task section
+ * — e.g. the top-level `## Approvals` checklist, or a task still `todo` with
+ * pre-checked boxes — still signals an unreviewed completion claim and must
+ * keep failing the draft anti-masquerade guard.
+ */
+export declare function countUnexplainedCheckedCriteria(markdown: string): number;

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

@@ -1,9 +1,12 @@
 /**
  * Check acceptance criteria completion in plan markdown.
  */
+const CHECKBOX_REGEX = /^- \[([ x])\]/gm;
+const TASK_HEADER_REGEX = /^####\s+(?:\[[^\]]+\]\s+)?Task\s+\d+(?:\.\d+)+:.*$/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) {
-    const criteriaRegex = /^- \[([ x])\]/gm;
-    const matches = Array.from(markdown.matchAll(criteriaRegex));
+    const matches = Array.from(markdown.matchAll(CHECKBOX_REGEX));
     const total = matches.length;
     const checked = matches.filter((m) => m[1] === "x").length;
     return {
@@ -12,3 +15,39 @@ export function checkAcceptanceCriteria(markdown) {
         allChecked: total === 0 || checked === total,
     };
 }
+function countChecked(text) {
+    return Array.from(text.matchAll(CHECKBOX_REGEX)).filter((m) => m[1] === "x").length;
+}
+function taskSectionEnd(markdown, start, nextTaskStart) {
+    const rest = markdown.slice(start);
+    const boundaryMatch = rest.match(SECTION_BOUNDARY_REGEX);
+    const boundaryIndex = boundaryMatch?.index === undefined ? markdown.length : start + boundaryMatch.index + 1;
+    return Math.min(nextTaskStart, boundaryIndex);
+}
+function sumCheckedInDoneOrDroppedTasks(markdown) {
+    const headers = Array.from(markdown.matchAll(TASK_HEADER_REGEX));
+    return headers.reduce((sum, header, index) => {
+        const start = header.index ?? 0;
+        const nextStart = headers[index + 1]?.index ?? markdown.length;
+        const section = markdown.slice(start, taskSectionEnd(markdown, start, nextStart));
+        return TASK_DONE_OR_DROPPED_REGEX.test(section) ? sum + countChecked(section) : sum;
+    }, 0);
+}
+/**
+ * Count checked acceptance-criteria checkboxes that are NOT explained by an
+ * explicit `**Status:** done`/`dropped` line on their containing task.
+ *
+ * `completeTask()` (see `markdown/helpers.ts`) checks every checkbox inside
+ * a task's own section when that task is marked done — which is expected,
+ * honest progress tracking during `draft` (pretool-guard's `blueprint-first`
+ * validator explicitly allows implementing source while a blueprint is
+ * still draft). A checked box that is NOT inside a done/dropped task section
+ * — e.g. the top-level `## Approvals` checklist, or a task still `todo` with
+ * pre-checked boxes — still signals an unreviewed completion claim and must
+ * keep failing the draft anti-masquerade guard.
+ */
+export function countUnexplainedCheckedCriteria(markdown) {
+    const { checked } = checkAcceptanceCriteria(markdown);
+    const explained = sumCheckedInDoneOrDroppedTasks(markdown);
+    return Math.max(0, checked - explained);
+}

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

@@ -2,7 +2,7 @@
  * Validate plan state consistency with folder structure and checkbox status.
  */
 import { planStatusSchema } from "#core/schema";
-import { checkAcceptanceCriteria } from "./criteria.js";
+import { checkAcceptanceCriteria, countUnexplainedCheckedCriteria } from "./criteria.js";
 /**
  * Validate plan is in completed/ folder if status is completed.
  */
@@ -22,7 +22,9 @@ function validateCompletedFolder(status, isInCompleted, criteria) {
     if (status === "completed" && !criteria.allChecked) {
         return {
             valid: false,
-            error: `Plan has status: completed but only ${criteria.checked}/${criteria.total} acceptance criteria are checked`,
+            error: `Plan has status: completed but only ${criteria.checked}/${criteria.total} acceptance ` +
+                `criteria are checked. Check the remaining boxes once that work is genuinely done, or ` +
+                `set status back to in-progress until it is.`,
         };
     }
     return { valid: true };
@@ -30,7 +32,7 @@ function validateCompletedFolder(status, isInCompleted, criteria) {
 /**
  * Validate plan is in draft/ folder if status is draft.
  */
-function validateDraftFolder(status, isInDraft, criteria) {
+function validateDraftFolder(status, isInDraft, markdown) {
     if (status === "draft" && !isInDraft) {
         return {
             valid: false,
@@ -43,11 +45,20 @@ function validateDraftFolder(status, isInDraft, criteria) {
             error: `Plan is in draft/ folder but has status: ${status} (expected status: draft)`,
         };
     }
-    if (status === "draft" && criteria.checked > 0) {
-        return {
-            valid: false,
-            error: `Plan has status: draft but ${criteria.checked} acceptance criteria are checked (expected 0)`,
-        };
+    if (status === "draft") {
+        const unexplained = countUnexplainedCheckedCriteria(markdown);
+        if (unexplained > 0) {
+            return {
+                valid: false,
+                error: `Plan has status: draft but ${unexplained} acceptance criteria are checked outside ` +
+                    `a task marked **Status:** done/dropped (expected 0). Marking a task's own status ` +
+                    `done/dropped legitimately checks its boxes during draft implementation; a checked ` +
+                    `box elsewhere (e.g. the Approvals checklist, or a still-todo task) claims unreviewed ` +
+                    `completion. Fix by either setting the owning task's **Status:** to done/dropped if ` +
+                    `the work is genuinely finished, unchecking the box if it isn't, or promoting the ` +
+                    `blueprint with \`wp blueprint promote <slug>\` once it has been reviewed.`,
+            };
+        }
     }
     return { valid: true };
 }
@@ -72,11 +83,11 @@ function validateParkedFolder(status, isInParked) {
 /**
  * Validate state without path information.
  */
-function validateStateOnly(status, criteria) {
+function validateStateOnly(status, markdown, criteria) {
     if (status === "completed" && !criteria.allChecked) {
         return { valid: false, error: "Plan completed but criteria not met" };
     }
-    if (status === "draft" && criteria.checked > 0) {
+    if (status === "draft" && countUnexplainedCheckedCriteria(markdown) > 0) {
         return { valid: false, error: "Plan draft but criteria checked" };
     }
     return { valid: true };
@@ -84,14 +95,14 @@ function validateStateOnly(status, criteria) {
 /**
  * Validate state with path information.
  */
-function validateStateWithPath(status, filePath, criteria) {
+function validateStateWithPath(status, filePath, markdown, criteria) {
     const isInCompleted = filePath.includes("/completed/") || filePath.includes("completed/");
     const isInDraft = filePath.includes("/draft/") || filePath.includes("draft/");
     const isInParked = filePath.includes("/parked/") || filePath.includes("parked/");
     const completedResult = validateCompletedFolder(status, isInCompleted, criteria);
     if (!completedResult.valid)
         return completedResult;
-    const draftResult = validateDraftFolder(status, isInDraft, criteria);
+    const draftResult = validateDraftFolder(status, isInDraft, markdown);
     if (!draftResult.valid)
         return draftResult;
     const parkedResult = validateParkedFolder(status, isInParked);
@@ -116,7 +127,7 @@ export function validatePlanState(markdown, filePath) {
     }
     const criteria = checkAcceptanceCriteria(markdown);
     if (!filePath) {
-        return validateStateOnly(status, criteria);
+        return validateStateOnly(status, markdown, criteria);
     }
-    return validateStateWithPath(status, filePath, criteria);
+    return validateStateWithPath(status, filePath, markdown, criteria);
 }

package/dist/esm/blueprint/db/migrations/run.js

@@ -4,8 +4,10 @@ import { findPackageAsset } from "#utils/package-assets.js";
 const PACKAGED_MIGRATIONS_RELATIVE_DIR = "dist/esm/blueprint/db/migrations";
 const SOURCE_MIGRATIONS_RELATIVE_DIR = "src/blueprint/db/migrations";
 function resolveMigrationsDir() {
-    const found = findPackageAsset(PACKAGED_MIGRATIONS_RELATIVE_DIR) ??
-        findPackageAsset(SOURCE_MIGRATIONS_RELATIVE_DIR);
+    // Source checkouts may rebuild dist concurrently in another test project.
+    // Prefer immutable authoring SQL there; published packages fall back to dist.
+    const found = findPackageAsset(SOURCE_MIGRATIONS_RELATIVE_DIR) ??
+        findPackageAsset(PACKAGED_MIGRATIONS_RELATIVE_DIR);
     if (found)
         return found;
     throw new Error(`Missing blueprint migrations at ${PACKAGED_MIGRATIONS_RELATIVE_DIR} or ${SOURCE_MIGRATIONS_RELATIVE_DIR}. ` +

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

@@ -43,6 +43,7 @@ export declare function countDistinctLogBackedApprovals(file: string, approvals:
 export interface ApprovalGateEvaluation {
     distinct: number;
     openCodeGoModelReviewers: string[];
+    overrideReviewers: string[];
     satisfied: boolean;
     strongReviewers: string[];
 }
@@ -59,5 +60,24 @@ export declare function validateApprovalGate(file: string, frontmatter: Lifecycl
     completedApprovalGate?: boolean;
     inProgressApprovalGate?: boolean;
 }): BlueprintAuditIssue[];
+/**
+ * Write-path mirror of {@link validateApprovalGate}'s `completed` branch.
+ *
+ * There is no single completion chokepoint: this helper is called from all
+ * three write-path owners that can set `status: completed` — the MCP transition
+ * funnel `applyLocalBlueprintTransition` (finalize/promote/transition), the CLI
+ * `promoteBlueprintLocked` (which does not traverse that funnel), and the
+ * execution engine's `finalize` intent via `applyBlueprintLifecycleToFile`
+ * (exec/resume/stop/move). Calling it before each write guarantees a blueprint
+ * can only reach `completed` when it carries the same plan-purpose approval CI's
+ * `wp audit blueprint-lifecycle` requires afterward. It delegates to
+ * {@link validateApprovalGate} verbatim — including the pre-rollout grandfather
+ * ({@link predatesCompletedApprovalGate}) and the v2 `review-events.jsonl`
+ * ledger — so the write-path and the audit-path can never diverge and a
+ * finalized blueprint can never fail its own lifecycle audit.
+ *
+ * @throws Error when no plan-purpose approval satisfies the promotion reviewer mix.
+ */
+export declare function assertCompletedApprovalGate(file: string, markdown: string): void;
 export declare function runBlueprintAudit(options: RunBlueprintAuditOptions): Promise<BlueprintAuditResult>;
 export {};

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

@@ -12,7 +12,9 @@ import { scanBlueprintDirectory } from "#service/scanner";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { parseBlueprintDocumentRelativePath } from "#utils/document-paths.js";
 import { relativeBlueprintSlug } from "#lifecycle/local.js";
-import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, } from "#lifecycle/review-provenance.js";
+import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, stableSlugForBlueprintFile, } from "#lifecycle/review-provenance.js";
+import { isBlueprintExemptFromRollout, ROLLOUT_DATE } from "#lifecycle/rollout-anchor.js";
+import { MAINTAINER_OVERRIDE_REVIEWER } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 function isBlueprintOverview(file) {
     const normalized = file.replace(/\\/g, "/");
@@ -50,14 +52,25 @@ function readLifecycleAuditFrontmatter(raw) {
  * blueprints that predate those changed-state gates.
  */
 const APPROVAL_GATED_STATUSES = new Set(["planned"]);
-const COMPLETED_APPROVAL_GATE_ROLLOUT_DATE = "2026-07-12";
-function predatesCompletedApprovalGate(created) {
-    const date = created instanceof Date
-        ? created.toISOString().slice(0, 10)
-        : typeof created === "string" && /^\d{4}-\d{2}-\d{2}$/u.test(created)
-            ? created
-            : null;
-    return date !== null && date < COMPLETED_APPROVAL_GATE_ROLLOUT_DATE;
+/**
+ * True when this blueprint predates the completed-approval gate and is exempt.
+ *
+ * Inside this repository the rollout anchor commit decides and the
+ * author-supplied `created` is ignored, which closes a real bypass: `created`
+ * is written by the same author the gate constrains, so an old date used to
+ * disable the gate outright -- on the CI audit path and on the unconditional
+ * `assertCompletedApprovalGate` write path, letting a blueprint reach
+ * `completed` with no approval at all. Outside this repository the anchor
+ * cannot answer the question and the legacy date compare still applies. See
+ * `#lifecycle/rollout-anchor.js` for the full resolution order.
+ */
+function predatesCompletedApprovalGate(file, created) {
+    return isBlueprintExemptFromRollout({
+        repoRoot: findGitRoot(file),
+        slug: stableSlugForBlueprintFile(file),
+        created,
+        rolloutDate: ROLLOUT_DATE,
+    });
 }
 /**
  * Promotion gate: a blueprint past `draft` must carry either one provenance-backed
@@ -94,11 +107,13 @@ function approvalReviewerKey(reviewer) {
     return parts.at(-1) ?? normalized;
 }
 function provenanceBackedApprovalReviewers(file, approvals, options = {}) {
-    const purpose = options.purpose ?? "plan";
-    const legacy = purpose === "plan"
+    const purposes = options.purpose
+        ? [options.purpose]
+        : ["plan", "delivery"];
+    const legacy = purposes.includes("plan")
         ? collectTrackedReviewProvenance(file, approvals, options).map((record) => record.reviewer)
         : [];
-    const current = collectV2ReviewProvenance(file, purpose, "HEAD", options.issuesSink).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) {
@@ -116,15 +131,24 @@ export function evaluateApprovalReviewers(reviewerIds) {
     const openCodeGoModelReviewers = reviewers
         .map(approvalReviewerKey)
         .filter((reviewer) => OPENCODE_GO_MODEL_APPROVAL_REVIEWERS.has(reviewer));
+    const overrideReviewers = reviewers
+        .map(approvalReviewerKey)
+        .filter((reviewer) => reviewer === MAINTAINER_OVERRIDE_REVIEWER);
     return {
         distinct: reviewers.length,
         openCodeGoModelReviewers: [...new Set(openCodeGoModelReviewers)].sort(),
-        satisfied: strongReviewers.length >= 1 || new Set(openCodeGoModelReviewers).size >= 1,
+        overrideReviewers: [...new Set(overrideReviewers)].sort(),
+        satisfied: strongReviewers.length >= 1 ||
+            new Set(openCodeGoModelReviewers).size >= 1 ||
+            new Set(overrideReviewers).size >= 1,
         strongReviewers: [...new Set(strongReviewers)].sort(),
     };
 }
 export function formatApprovalGateRequirement(evaluation) {
-    return `need 1 provenance-backed Claude/Codex/Grok or OpenCode-Go model approval; currently have ${evaluation.strongReviewers.length} Claude/Codex/Grok approval(s), ${evaluation.openCodeGoModelReviewers.length} OpenCode-Go model approval(s), ${evaluation.distinct} distinct provenance-backed approval(s) total`;
+    const override = evaluation.overrideReviewers.length >= 1
+        ? ` + ${evaluation.overrideReviewers.length} maintainer-override(s)`
+        : "";
+    return `need 1 provenance-backed Claude/Codex/Grok or OpenCode-Go model approval (or a recorded maintainer-override); currently have ${evaluation.strongReviewers.length} Claude/Codex/Grok approval(s), ${evaluation.openCodeGoModelReviewers.length} OpenCode-Go model approval(s)${override}, ${evaluation.distinct} distinct provenance-backed approval(s) total`;
 }
 export function validateApprovalGate(file, frontmatter, options = {}) {
     if (frontmatter.type !== "blueprint")
@@ -132,7 +156,7 @@ export function validateApprovalGate(file, frontmatter, options = {}) {
     const status = typeof frontmatter.status === "string" ? frontmatter.status : "";
     if (status === "completed" &&
         options.completedApprovalGate === true &&
-        predatesCompletedApprovalGate(frontmatter.created)) {
+        predatesCompletedApprovalGate(file, frontmatter.created)) {
         return [];
     }
     const gateApplies = APPROVAL_GATED_STATUSES.has(status) ||
@@ -162,6 +186,31 @@ export function validateApprovalGate(file, frontmatter, options = {}) {
         message: `Review evidence integrity: ${issue}`,
     }));
 }
+/**
+ * Write-path mirror of {@link validateApprovalGate}'s `completed` branch.
+ *
+ * There is no single completion chokepoint: this helper is called from all
+ * three write-path owners that can set `status: completed` — the MCP transition
+ * funnel `applyLocalBlueprintTransition` (finalize/promote/transition), the CLI
+ * `promoteBlueprintLocked` (which does not traverse that funnel), and the
+ * execution engine's `finalize` intent via `applyBlueprintLifecycleToFile`
+ * (exec/resume/stop/move). Calling it before each write guarantees a blueprint
+ * can only reach `completed` when it carries the same plan-purpose approval CI's
+ * `wp audit blueprint-lifecycle` requires afterward. It delegates to
+ * {@link validateApprovalGate} verbatim — including the pre-rollout grandfather
+ * ({@link predatesCompletedApprovalGate}) and the v2 `review-events.jsonl`
+ * ledger — so the write-path and the audit-path can never diverge and a
+ * finalized blueprint can never fail its own lifecycle audit.
+ *
+ * @throws Error when no plan-purpose approval satisfies the promotion reviewer mix.
+ */
+export function assertCompletedApprovalGate(file, markdown) {
+    const frontmatter = readLifecycleAuditFrontmatter(markdown);
+    const errors = validateApprovalGate(file, { ...frontmatter, status: "completed" }, { completedApprovalGate: true }).filter((issue) => issue.level === "error");
+    if (errors.length > 0) {
+        throw new Error(errors.map((issue) => issue.message).join("; "));
+    }
+}
 function countTaskHeadings(raw) {
     return raw.match(/^####\s+(?:\[[^\]]+\]\s+)?Task\s+/gm)?.length ?? 0;
 }
@@ -226,7 +275,13 @@ function validateTaskState(blueprint) {
     }
     return issues;
 }
-function validateBlueprintSlugUniqueness(blueprints) {
+function validateBlueprintSlugUniqueness(blueprints, 
+// When auditing a changed-only subset, `stagedSet` restricts reporting to
+// duplicates a CHANGED blueprint participates in, and attributes the error to
+// that changed file so a scope-filtering caller still surfaces it. A
+// pre-existing duplicate among only-untouched blueprints is left for the
+// full-corpus (CI) pass, not the changed-only hook.
+scope) {
     const grouped = new Map();
     for (const blueprint of blueprints) {
         const normalizedSlug = relativeBlueprintSlug(blueprint.slug);
@@ -239,12 +294,18 @@ function validateBlueprintSlugUniqueness(blueprints) {
         }
     }
     const issues = [];
+    const stagedSet = scope?.stagedSet ?? null;
     for (const [normalizedSlug, entries] of grouped) {
         const uniqueLifecycleSlugs = new Set(entries.map((entry) => entry.slug));
         if (uniqueLifecycleSlugs.size <= 1)
             continue;
+        const changedEntry = stagedSet
+            ? entries.find((entry) => stagedSet.has(normalizePath(path.relative(scope.projectRoot, entry.file))))
+            : undefined;
+        if (stagedSet && !changedEntry)
+            continue;
         issues.push({
-            file: entries[0]?.file,
+            file: (changedEntry ?? entries[0])?.file,
             level: "error",
             message: `Blueprint slug "${normalizedSlug}" appears in multiple lifecycle locations: ${Array.from(uniqueLifecycleSlugs)
                 .toSorted()
@@ -620,10 +681,16 @@ export async function runBlueprintAudit(options) {
         baseDir: resolveBlueprintRoot(options.projectRoot),
         includeSpecialFolders: true,
     });
-    const blueprintFiles = options.all || !options.stagedFiles
+    const stagedSet = options.all || !options.stagedFiles ? null : new Set(options.stagedFiles.map(normalizePath));
+    const blueprintFiles = stagedSet === null
         ? scanned
-        : scanned.filter((entry) => new Set(options.stagedFiles?.map(normalizePath) ?? []).has(normalizePath(path.relative(options.projectRoot, entry.path))));
-    issues.push(...validateBlueprintSlugUniqueness(blueprintFiles));
+        : scanned.filter((entry) => stagedSet.has(normalizePath(path.relative(options.projectRoot, entry.path))));
+    // Slug uniqueness is a corpus-wide invariant, so validate it over ALL scanned
+    // blueprints even in changed-only mode — otherwise a changed blueprint that
+    // duplicates an *untouched* lifecycle slug would only be compared with itself
+    // and the error would vanish. Only the expensive per-file audit below is
+    // scoped to the changed subset.
+    issues.push(...validateBlueprintSlugUniqueness(scanned, { projectRoot: options.projectRoot, stagedSet }));
     for (const entry of blueprintFiles) {
         issues.push(...(await auditBlueprintFile(entry.path, entry.slug, options)));
     }

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

@@ -0,0 +1,6 @@
+export interface CanonicalizeBlueprintResult {
+    readonly from: string;
+    readonly to: string;
+    readonly moved: boolean;
+}
+export declare function canonicalizeBlueprint(projectRoot: string, slug: string): Promise<CanonicalizeBlueprintResult>;