@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/audit/registry.d.ts

@@ -14,11 +14,11 @@ export interface AuditKindDescriptor {
 }
 export declare const SCRIPT_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e"];
 export declare const SPECIAL_AUDIT_KIND_IDS: readonly ["bundle-budget", "commit-message", "blueprint-pr-coverage", "mutation", "guardrails", "quality"];
-export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "legacy-workflow-identity", "rules", "skills"];
+export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "ci-guardrails-wiring", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "host-substitution-risk", "legacy-workflow-identity", "rules", "skills", "typescript-version"];
 export declare const AUDIT_KIND_DESCRIPTORS: readonly AuditKindDescriptor[];
-export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "test-scan-perf" | "toolchain-isolation" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
-export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "session-memory-hardcut", "worktree-main-ownership", "sast"];
-export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random", "test-scan-perf"];
+export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-guardrails-wiring" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "host-substitution-risk" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "test-scan-perf" | "toolchain-isolation" | "typescript-version" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
+export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "host-substitution-risk", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "session-memory-hardcut", "worktree-main-ownership", "typescript-version", "ci-guardrails-wiring", "sast"];
+export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random", "test-scan-perf", "ci-guardrails-wiring"];
 export type AuditKindId = (typeof AUDIT_KIND_IDS)[number];
 export type RepoAuditKindId = (typeof REPO_AUDIT_KIND_IDS)[number];
 export type MCPAuditKindId = (typeof MCP_AUDIT_KIND_IDS)[number];

package/dist/esm/audit/registry.js

@@ -17,6 +17,7 @@ const affectedSafeKinds = [
     "no-first-party-mjs",
     "no-math-random",
     "test-scan-perf",
+    "ci-guardrails-wiring",
 ];
 const mcpKindIds = [
     "test-smells",
@@ -44,6 +45,7 @@ const mcpKindIds = [
     "harness-surfaces",
     "weakness-mining",
     "harness-overlay-evidence",
+    "host-substitution-risk",
     "ai-contracts",
     "atomic-state-writes",
     "no-relative-package-scripts",
@@ -60,6 +62,8 @@ const mcpKindIds = [
     "test-scan-perf",
     "session-memory-hardcut",
     "worktree-main-ownership",
+    "typescript-version",
+    "ci-guardrails-wiring",
     "sast",
 ];
 const affectedSafe = new Set(affectedSafeKinds);
@@ -132,15 +136,18 @@ const repoKinds = [
     "secrets-config",
     "consumer-agent-kit-dependency",
     "ci-test-perf",
+    "ci-guardrails-wiring",
     "test-scan-perf",
     "worktree-main-ownership",
     "sast",
     "harness-surfaces",
     "weakness-mining",
     "harness-overlay-evidence",
+    "host-substitution-risk",
     "legacy-workflow-identity",
     "rules",
     "skills",
+    "typescript-version",
 ];
 function descriptor(id, kindClass) {
     return {
@@ -151,7 +158,7 @@ function descriptor(id, kindClass) {
         gateClass: signalKinds.has(id) ? "signal" : "blocking",
         scopeSafety: affectedSafe.has(id) ? "affected-safe" : "full-scan-only",
         summaryLabel: id === "sast" ? "SAST" : id,
-        ...(id === "sast" ? { includedInGuardrails: false } : {}),
+        ...(["sast", "host-substitution-risk"].includes(id) ? { includedInGuardrails: false } : {}),
         ...(["blueprint-readme-drift", "docs-frontmatter"].includes(id) ? { fixable: true } : {}),
     };
 }

package/dist/esm/audit/toolchain-isolation.js

@@ -133,10 +133,9 @@ function shouldSkipDirectory(name) {
         ".stryker-tmp",
         ".agent",
         ".agents",
-        ".gemini",
-        ".windsurf",
         ".runtime",
         ".codex",
+        ".grok",
         "_worktrees",
         // Gitignored Claude Code agent surface — agent worktree scratch under
         // .claude/worktrees/* carries vendored package manifests that are not the

package/dist/esm/audit/typescript-version.d.ts

@@ -0,0 +1,2 @@
+import type { RepoAuditResult } from "./repo-guardrails.js";
+export declare function auditTypescriptVersion(rootDirectory: string): RepoAuditResult;

package/dist/esm/audit/typescript-version.js

@@ -0,0 +1,123 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * `wp audit typescript-version` — enforce the native TypeScript compiler major
+ * at consumers.
+ *
+ * agent-kit migrated itself to TypeScript 7 (the native Go compiler) and pins
+ * `typescript: ^7.0.2` in every shipped template, but nothing checked that a
+ * downstream consumer stayed on 7 — so a consumer could silently regress to a
+ * legacy TypeScript major (observed: edge-matte pinned `typescript: ^6.0.3`).
+ * This audit ships through `wp audit guardrails`, so consumers inherit it
+ * automatically on their next `wp` bump with no CI edits.
+ *
+ * It gates only the `typescript` compiler dependency. `@typescript/typescript6`
+ * — the Microsoft-published TS6 compiler-API compatibility package that
+ * agent-kit itself depends on until TS 7.1 stabilizes the programmatic API — is
+ * a distinct dependency and is never flagged.
+ */
+const REQUIRED_MAJOR = 7;
+const COMPILER_DEP = "typescript";
+// Inline escape hatch for a documented, temporary exception (e.g. a consumer
+// mid-migration). Placed as a comment in pnpm-workspace.yaml or in the manifest.
+const OPT_OUT_MARKER = "typescript-version-allow";
+/** Lowest major a version range can resolve to (the enforceable floor). */
+function majorFloor(range) {
+    const match = /(\d+)/u.exec(range);
+    return match ? Number(match[1]) : undefined;
+}
+/** `catalog:` / `workspace:` pins resolve elsewhere; `*`/`latest` carry no floor. */
+function isDelegatedPin(value) {
+    return (value.startsWith("catalog:") ||
+        value.startsWith("workspace:") ||
+        value === "*" ||
+        value === "latest");
+}
+function checkTypescriptPin(source, value, violations) {
+    if (isDelegatedPin(value))
+        return;
+    const major = majorFloor(value);
+    if (major === undefined || major >= REQUIRED_MAJOR)
+        return;
+    violations.push({
+        file: source,
+        severity: "error",
+        ruleId: "typescript-version",
+        message: `typescript is pinned to "${value}" (major ${major}); the native compiler ` +
+            `requires TypeScript ${REQUIRED_MAJOR}. Bump to ^${REQUIRED_MAJOR} (or a catalog: ref). ` +
+            `The @typescript/typescript6 compiler-API bridge is separate and allowed.`,
+    });
+}
+function collectManifestPaths(rootDirectory) {
+    const paths = [];
+    if (existsSync(join(rootDirectory, "package.json")))
+        paths.push("package.json");
+    for (const group of ["packages", "apps"]) {
+        const dir = join(rootDirectory, group);
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const manifest = join(group, entry.name, "package.json");
+            if (existsSync(join(rootDirectory, manifest)))
+                paths.push(manifest);
+        }
+    }
+    return paths;
+}
+export function auditTypescriptVersion(rootDirectory) {
+    const violations = [];
+    const sources = [];
+    let checked = 0;
+    // 1. Workspace catalog pin — the primary contract; catches catalog-level drift.
+    const workspacePath = join(rootDirectory, "pnpm-workspace.yaml");
+    if (existsSync(workspacePath)) {
+        const raw = readFileSync(workspacePath, "utf8");
+        sources.push({ path: "pnpm-workspace.yaml", kind: "pnpm-workspace" });
+        if (!raw.includes(OPT_OUT_MARKER)) {
+            const workspace = (parseYaml(raw) ?? {});
+            const catalogPin = workspace.catalog?.[COMPILER_DEP];
+            if (typeof catalogPin === "string") {
+                checked += 1;
+                checkTypescriptPin("pnpm-workspace.yaml (catalog.typescript)", catalogPin, violations);
+            }
+            // pnpm also supports NAMED catalogs (`catalogs.<name>.typescript`), a
+            // separate map from the default `catalog` above. A pin placed there
+            // resolves the same way for consumers using `catalog:<name>` refs, so it
+            // must be enforced identically or a consumer can dodge the check by
+            // moving the pin into a named catalog.
+            for (const [catalogName, entries] of Object.entries(workspace.catalogs ?? {})) {
+                const namedPin = entries[COMPILER_DEP];
+                if (typeof namedPin !== "string")
+                    continue;
+                checked += 1;
+                checkTypescriptPin(`pnpm-workspace.yaml (catalogs.${catalogName}.typescript)`, namedPin, violations);
+            }
+        }
+    }
+    // 2. Direct typescript pins in package manifests (catalog:/workspace: skipped —
+    //    they resolve through the catalog checked above).
+    for (const manifest of collectManifestPaths(rootDirectory)) {
+        const raw = readFileSync(join(rootDirectory, manifest), "utf8");
+        sources.push({ path: manifest, kind: "package-manifest" });
+        if (raw.includes(OPT_OUT_MARKER))
+            continue;
+        const parsed = JSON.parse(raw);
+        for (const field of ["dependencies", "devDependencies"]) {
+            const pin = parsed[field]?.[COMPILER_DEP];
+            if (typeof pin === "string") {
+                checked += 1;
+                checkTypescriptPin(`${manifest} (${field}.typescript)`, pin, violations);
+            }
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: `TypeScript ${REQUIRED_MAJOR} consumer pin`,
+        checked,
+        sources,
+        violations,
+    };
+}

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

@@ -74,14 +74,56 @@ 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 preserveOriginalFrontmatterScalars(serialized, 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 and array fields (no inline value) are left to js-yaml, which
+// dumps them deterministically. 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)}`;
+}
 function extractCheckboxStatus(section) {
     const checkboxRegex = /^- \[([ x])\]/gm;
     const matches = Array.from(section.matchAll(checkboxRegex));

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

@@ -13,6 +13,7 @@ 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 { MAINTAINER_OVERRIDE_REVIEWER } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 function isBlueprintOverview(file) {
     const normalized = file.replace(/\\/g, "/");
@@ -94,11 +95,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 +119,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")
@@ -162,6 +174,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 +263,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 +282,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 +669,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)));
     }