@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/audit/test-scan-perf.js

@@ -0,0 +1,275 @@
+/**
+ * Guardrail: keep tests from silently growing multi-second / multi-ten-second
+ * full-repo filesystem scans, and from "fixing" that cost with elevated
+ * per-test timeouts.
+ *
+ * The private-UI cutover anti-regression suite originally walked the monorepo
+ * with readdirSync/statSync/readFileSync and needed a 30s timeout. Prefer
+ * `git grep` (tracked files) or a bounded fixture tree instead.
+ *
+ * Opt-out: `// test-scan-perf-allow` on the same line or previous line as the
+ * walk/timeout site, or `// test-scan-perf-allow-file` anywhere in the file.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+const TITLE = "test-scan-perf";
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
+const E2E_FILE_PATTERN = /\.e2e\./u;
+const SKIP_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "coverage",
+    ".turbo",
+    ".webpresso",
+    ".agent",
+    ".agents",
+    ".claude",
+    ".codex",
+    ".cursor",
+    ".opencode",
+    ".omx",
+    "playwright-report",
+    "test-results",
+    "logs",
+    "_worktrees",
+]);
+const ALLOW_LINE_PATTERN = /test-scan-perf-allow(?:-timeout|-walk)?\b/iu;
+const ALLOW_FILE_PATTERN = /test-scan-perf-allow-file\b/iu;
+/** Recursive walk helper that also reads file contents (content scan). */
+const RECURSIVE_WALK_HINT = /(?:function\s+walk\b|const\s+walk\s*=|let\s+walk\s*=|var\s+walk\s*=)/u;
+const RECURSIVE_CALL_HINT = /\bwalk\s*\(\s*(?:full|dir|current|directory|entryPath|sub|next)\b/u;
+const READDIR_HINT = /\breaddirSync\b/u;
+const READ_FILE_HINT = /\breadFileSync\b/u;
+/**
+ * True when the file acquires the *workspace* root (not a mkdtemp fixture)
+ * and feeds that root into a recursive walk / file-finder helper.
+ */
+function hasWorkspaceRootScanStart(code) {
+    const assignsWorkspaceRoot = /\bfindRepoRoot\s*\(/u.test(code) ||
+        /(?:const|let|var)\s+(?:repoRoot|REPO_ROOT)\s*=\s*process\.cwd\s*\(/u.test(code) ||
+        /(?:const|let|var)\s+root\s*=\s*(?:findRepoRoot\s*\(|process\.cwd\s*\()/u.test(code);
+    if (!assignsWorkspaceRoot)
+        return false;
+    // Direct walk(repoRoot|REPO_ROOT) or helper(repoRoot|REPO_ROOT) that owns the walk.
+    if (/\b(?:walk|findFiles|list\w*|scan\w*|collect\w*)\s*\(\s*(?:repoRoot|REPO_ROOT)\b/u.test(code)) {
+        return true;
+    }
+    // walk(root) only when `root` itself is the workspace root assignment.
+    if (/(?:const|let|var)\s+root\s*=\s*(?:findRepoRoot\s*\(|process\.cwd\s*\()/u.test(code) &&
+        /\b(?:walk|findFiles|list\w*|scan\w*|collect\w*)\s*\(\s*root\b/u.test(code)) {
+        return true;
+    }
+    return false;
+}
+const MIN_ELEVATED_TIMEOUT_MS = 30_000;
+export function isTestScanPerfTargetPath(relativePath) {
+    const normalized = relativePath.replaceAll("\\", "/");
+    if (!TEST_FILE_PATTERN.test(normalized))
+        return false;
+    if (E2E_FILE_PATTERN.test(normalized))
+        return false;
+    // Audit self-tests and fixtures intentionally include positive examples.
+    if (normalized.includes("/__fixtures__/"))
+        return false;
+    if (normalized.endsWith("/test-scan-perf.test.ts"))
+        return false;
+    return true;
+}
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/(^|[^:])\/\/[^\n]*/gu, "$1");
+}
+function stripAllowedLines(source) {
+    const lines = source.split(/\r?\n/u);
+    return lines.map((line, index) => (lineAllowed(lines, index) ? "" : line)).join("\n");
+}
+function lineAllowed(lines, index) {
+    const current = lines[index] ?? "";
+    if (ALLOW_LINE_PATTERN.test(current))
+        return true;
+    if (index > 0 && ALLOW_LINE_PATTERN.test(lines[index - 1] ?? ""))
+        return true;
+    return false;
+}
+function hasRepoRootContentWalk(code) {
+    if (!READDIR_HINT.test(code) || !READ_FILE_HINT.test(code))
+        return false;
+    if (!RECURSIVE_WALK_HINT.test(code))
+        return false;
+    const recursiveCall = RECURSIVE_CALL_HINT.test(code) || /\bwalk\s*\(\s*join\s*\(/u.test(code);
+    if (!recursiveCall)
+        return false;
+    return hasWorkspaceRootScanStart(code);
+}
+function parseTimeoutMs(raw) {
+    const digits = raw.replaceAll("_", "");
+    if (!/^\d+$/u.test(digits))
+        return null;
+    const value = Number(digits);
+    return Number.isFinite(value) ? value : null;
+}
+function findElevatedTimeoutLines(text) {
+    const hits = [];
+    const lines = text.split(/\r?\n/u);
+    // Line-oriented: `{ timeout: 30000 }`, trailing `, 30000)`, or a multi-line
+    // `it(\n  "…",\n  () => {…},\n  30_000,\n)` form.
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (lineAllowed(lines, index))
+            continue;
+        const optionMatch = line.match(/timeout\s*:\s*([0-9_]+)/u);
+        if (optionMatch?.[1]) {
+            const ms = parseTimeoutMs(optionMatch[1]);
+            if (ms !== null && ms >= MIN_ELEVATED_TIMEOUT_MS) {
+                hits.push({ line: index + 1, ms });
+                continue;
+            }
+        }
+        // Same-line trailing timeout: `}, 30_000)` / `, 30000)`
+        const trailingMatch = line.match(/,\s*([0-9_]+)\s*\)\s*;?\s*$/u);
+        // Own-line timeout before closing paren: `    30_000,` / `    30000`
+        const ownLineMatch = line.match(/^\s*([0-9_]+)\s*,?\s*$/u);
+        const raw = trailingMatch?.[1] ?? ownLineMatch?.[1];
+        if (!raw)
+            continue;
+        const ms = parseTimeoutMs(raw);
+        const windowStart = Math.max(0, index - 16);
+        const windowEnd = Math.min(lines.length, index + 3);
+        const window = lines.slice(windowStart, windowEnd).join("\n");
+        if (ms !== null &&
+            ms >= MIN_ELEVATED_TIMEOUT_MS &&
+            /\b(?:it|test)(?:\.only|\.each)?\s*\(/u.test(window)) {
+            hits.push({ line: index + 1, ms });
+        }
+    }
+    // Deduplicate by line.
+    const seen = new Set();
+    return hits.filter((hit) => {
+        if (seen.has(hit.line))
+            return false;
+        seen.add(hit.line);
+        return true;
+    });
+}
+export function findTestScanPerfViolationsInText(relativePath, text) {
+    if (!isTestScanPerfTargetPath(relativePath))
+        return [];
+    if (ALLOW_FILE_PATTERN.test(text))
+        return [];
+    const violations = [];
+    const code = stripComments(stripAllowedLines(text));
+    const hasSlowWalk = hasRepoRootContentWalk(code);
+    if (hasSlowWalk) {
+        violations.push({
+            file: relativePath,
+            ruleId: "repo-root-recursive-content-scan",
+            severity: "error",
+            message: `${relativePath}: recursive readdir/readFile content scan from the repo root. ` +
+                `Use \`git grep -l\` (tracked files) or a bounded fixture tree instead of walking ` +
+                `the whole workspace. Opt out with \`// test-scan-perf-allow\` on the walk site ` +
+                `or \`// test-scan-perf-allow-file\` once with justification.`,
+        });
+    }
+    // Elevated timeouts are only flagged when co-located with a repo-root FS walk —
+    // that is the "band-aid for a slow scan" pattern. Legitimate long e2e/subprocess
+    // timeouts without a root walk are out of scope.
+    if (hasSlowWalk) {
+        for (const hit of findElevatedTimeoutLines(text)) {
+            violations.push({
+                file: relativePath,
+                line: hit.line,
+                ruleId: "timeout-band-aid-for-scan",
+                severity: "error",
+                message: `${relativePath}:${hit.line}: per-test timeout ${hit.ms}ms co-located with a ` +
+                    `repo-root recursive FS scan. Fix the scan (git-grep / bounded tree) instead of ` +
+                    `raising the timeout. Opt out with \`// test-scan-perf-allow\` on that line.`,
+            });
+        }
+    }
+    return violations;
+}
+function listTestFilesViaGit(root) {
+    try {
+        const stdout = execFileSync("git", ["-C", root, "ls-files", "-z"], {
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout
+            .split("\0")
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .filter((entry) => isTestScanPerfTargetPath(entry));
+    }
+    catch {
+        return null;
+    }
+}
+function walkTestFiles(dir, root, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walkTestFiles(full, root, out);
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        const rel = relative(root, full).replaceAll("\\", "/");
+        if (isTestScanPerfTargetPath(rel))
+            out.push(rel);
+    }
+}
+function listTestFiles(root, affectedFiles) {
+    if (affectedFiles !== undefined) {
+        return affectedFiles
+            .map((file) => file.replaceAll("\\", "/"))
+            .filter((file) => isTestScanPerfTargetPath(file));
+    }
+    const fromGit = listTestFilesViaGit(root);
+    if (fromGit)
+        return fromGit;
+    const out = [];
+    walkTestFiles(root, root, out);
+    return out;
+}
+export function auditTestScanPerf(rootDirectory = process.cwd(), options = {}) {
+    const root = rootDirectory;
+    if (!existsSync(root)) {
+        return { ok: true, title: TITLE, checked: 0, violations: [] };
+    }
+    const files = listTestFiles(root, options.affectedFiles);
+    const violations = [];
+    for (const rel of files) {
+        const full = join(root, rel);
+        let text;
+        try {
+            text = readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        violations.push(...findTestScanPerfViolationsInText(rel, text));
+    }
+    return {
+        ok: violations.length === 0,
+        title: TITLE,
+        checked: files.length,
+        violations,
+    };
+}

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}. ` +