@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/hooks/stop/qa-changed-files.js

@@ -54,11 +54,85 @@ export function findTestFiles(sourceFile, projectDir) {
     const pattern = join(dir, `${base}.{test,integration.test}{.ts,.tsx}`);
     return globSync(pattern, { cwd: projectDir, withFileTypes: false });
 }
+/**
+ * Source files whose tests are NOT colocated.
+ *
+ * `findTestFiles` maps a changed file to `<same-dir>/<same-basename>.test.ts`.
+ * That is right for the common case and wrong for a few "contract" files whose
+ * dependent assertions deliberately live elsewhere — a registry that generates
+ * docs, a template rendered under a byte budget, and so on. Those tests then
+ * stay invisible to `--affected`, so `wp ci-preflight` (whose every stage runs
+ * `--affected --branch`) can report "all required checks passed" while they are
+ * genuinely failing.
+ *
+ * Observed 2026-07-24: adding MCP tools broke `scaffold-agents-md`,
+ * `package-manifest`, `reference-parity-tool-surface`, and `session-docs`.
+ * `wp ci-preflight` was green locally AND the pre-push hook passed; CI caught
+ * all of it. Three PRs landed red before the pattern was understood.
+ *
+ * Patterns are matched against repo-relative POSIX paths. Listed tests are
+ * existence-filtered by the caller, so an entry that does not apply to a
+ * consumer repo is simply inert.
+ */
+const CROSS_CUTTING_TEST_DEPENDENTS = [
+    {
+        // The compiled MCP tool registry feeds the generated AGENTS.md tool list
+        // (and its byte budget), the packed README session-memory contract, and
+        // reference-parity classification. None are colocated with the registry.
+        when: /^src\/mcp\/tools\/_(names|registry)\.ts$/u,
+        tests: [
+            "src/cli/commands/init/scaffold-agents-md.test.ts",
+            "src/build/package-manifest.test.ts",
+            "src/__integration__/reference-parity-tool-surface.integration.test.ts",
+            "src/mcp/tools/session-docs.test.ts",
+        ],
+    },
+    {
+        // The AGENTS.md template renders into the scaffold byte-budget assertion.
+        when: /^catalog\/AGENTS\.md\.tpl$/u,
+        tests: ["src/cli/commands/init/scaffold-agents-md.test.ts"],
+    },
+    {
+        // README and the session-memory guide are pinned to the registered
+        // session-memory tool set from both directions.
+        when: /^(README\.md|docs\/guides\/session-memory\.md)$/u,
+        tests: ["src/mcp/tools/session-docs.test.ts", "src/build/package-manifest.test.ts"],
+    },
+];
+/**
+ * Every test path the cross-cutting map can yield.
+ *
+ * Exported so a guard test can assert these still exist on disk. Without that
+ * guard a rename would keep the unit tests green — they only compare strings —
+ * while the caller's existence filter silently dropped the path, reinstating
+ * the very under-selection this map exists to prevent.
+ */
+export function crossCuttingTestDependentPaths() {
+    const paths = new Set();
+    for (const rule of CROSS_CUTTING_TEST_DEPENDENTS) {
+        for (const test of rule.tests)
+            paths.add(test);
+    }
+    return [...paths];
+}
+/** Non-colocated tests a changed file is known to affect. */
+export function findCrossCuttingTestFiles(sourceFile) {
+    const normalized = sourceFile.replaceAll("\\", "/");
+    const matched = new Set();
+    for (const rule of CROSS_CUTTING_TEST_DEPENDENTS) {
+        if (rule.when.test(normalized))
+            for (const test of rule.tests)
+                matched.add(test);
+    }
+    return [...matched];
+}
 export function discoverTestFiles(changedFiles, projectDir) {
     const testFiles = new Set();
     for (const file of changedFiles) {
         for (const testFile of findTestFiles(file, projectDir))
             testFiles.add(testFile);
+        for (const testFile of findCrossCuttingTestFiles(file))
+            testFiles.add(testFile);
     }
     return [...testFiles];
 }

package/dist/esm/mcp/blueprint/_shared/lifecycle.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import { parseBlueprint } from "#core/parser";
 import { setBlueprintFrontmatterFields } from "#lifecycle/engine";
-import { evaluateApprovalGate, formatApprovalGateRequirement } from "#lifecycle/audit";
+import { assertCompletedApprovalGate, evaluateApprovalGate, formatApprovalGateRequirement, } from "#lifecycle/audit";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
 import { assertAllTasksHaveCanonicalPassingEvidence } from "#verification.js";
@@ -70,6 +70,19 @@ export async function applyLocalBlueprintTransition(input) {
             throw new Error(`Cannot promote "${slug}" to ${to_state}: frontmatter \`approvals:\` does not satisfy the promotion reviewer mix (${formatApprovalGateRequirement(approvalEvaluation)}). Record approvals, commit the matching review ledger (e.g. reviews.md), and include tracked review transcript/artifact files referenced by each structured review entry — see catalog/agent/rules/pre-implementation.md.`);
         }
     }
+    // Completion parity for the MCP lifecycle funnel: finalize, promote, and
+    // transition all route here, so gate `completed` writes on the same
+    // plan-purpose approval CI's `wp audit blueprint-lifecycle` enforces
+    // afterward. Reads the raw on-disk markdown (not the trust-gated copy) to
+    // mirror the audit's frontmatter parsing exactly.
+    if (to_state === "completed") {
+        try {
+            assertCompletedApprovalGate(overviewPath, markdown);
+        }
+        catch (error) {
+            throw new Error(`Cannot complete "${slug}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     const updated = setBlueprintFrontmatterFields(trustedMarkdown, {
         status: to_state,
         last_updated: todayIsoDate(),

package/dist/esm/mcp/blueprint/handlers/document-mutations.js

@@ -2,14 +2,17 @@ import { existsSync, readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import matter from "gray-matter";
+import { parseBlueprint } from "#core/parser";
 import { evaluateApprovalGate, formatApprovalGateRequirement } from "#lifecycle/audit";
+import { canonicalizeBlueprint } from "#lifecycle/canonicalize.js";
 import { BlueprintCreationService } from "#service/BlueprintCreationService";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
-import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
+import { getBlueprintDocumentPaths, isBlueprintSlugSegment, } from "#utils/document-paths.js";
 import { makeNextAction } from "#next-action.js";
 import { ensureProjectionReady } from "#projection-ready.js";
 import { applyPromotionTrustGate } from "#trust/promotion.js";
 import { validateBlueprintTrust } from "#trust/validator.js";
+import { applyVerification, readTaskVerification } from "#verification.js";
 import { dbPath, persistBlueprintMarkdown, reIngest } from "#mcp/blueprint/_shared/db";
 import { err, finishPayload, jsonContent } from "#mcp/blueprint/_shared/errors";
 import { hashMutationPayload, readMutationReplay, recordMutationReplay, validateMutationFreshnessToken, } from "#mcp/blueprint/_shared/freshness";
@@ -353,6 +356,52 @@ function renderMarkdownTable(headers, rows) {
 function markdownTableCell(value) {
     return value.replace(/\s*\n\s*/gu, " ").trim();
 }
+/**
+ * wp_blueprint_put's task schema has no field for the `webpresso-evidence-v1`
+ * verification block that wp_blueprint_task_verify writes — evidence is an
+ * append-only trust artifact that callers must never freely reconstruct (see
+ * catalog/agent/rules/pre-implementation.md). A naive re-render of the whole
+ * document therefore silently discards any `**Verification:**` block already
+ * recorded for a `done` task.
+ *
+ * This reads the exact evidence already on disk for every task that has a
+ * block, and re-applies it verbatim onto the freshly rendered markdown when
+ * that task is still present in the payload with status "done" — the caller
+ * never supplies or fabricates evidence content. When the payload cannot
+ * represent a protected task (dropped, or moved off "done"), this fails
+ * closed with an actionable error instead of destroying the evidence.
+ */
+function preserveExistingTaskVerification(existingMarkdown, slug, document, renderedMarkdown) {
+    const existingBlueprint = parseBlueprint(existingMarkdown, slug);
+    const protectedTasks = existingBlueprint.tasks
+        .map((task) => ({ id: task.id, evidence: readTaskVerification(existingMarkdown, task.id) }))
+        .filter((entry) => entry.evidence !== null);
+    let markdown = renderedMarkdown;
+    for (const protectedTask of protectedTasks) {
+        const { id, evidence } = protectedTask;
+        const submittedTask = document.tasks.find((task) => task.id === id);
+        if (!submittedTask || submittedTask.status !== "done") {
+            return { error: describeEvidenceLossRefusal(id, submittedTask?.status) };
+        }
+        const applied = applyVerification(markdown, id, evidence);
+        if (!applied.ok) {
+            return {
+                error: `wp_blueprint_put failed to re-apply preserved verification evidence for task ${id}: ${applied.failures.join("; ")}`,
+            };
+        }
+        markdown = applied.markdown;
+    }
+    return { markdown };
+}
+function describeEvidenceLossRefusal(taskId, submittedStatus) {
+    const disposition = submittedStatus === undefined
+        ? `the submitted document does not include task ${taskId}`
+        : `the submitted document sets task ${taskId}'s status to "${submittedStatus}"`;
+    return (`wp_blueprint_put refused: task ${taskId} already has verification evidence recorded by ` +
+        `wp_blueprint_task_verify, but ${disposition} — wp_blueprint_put cannot represent or discard ` +
+        `that evidence. Keep task ${taskId} present with status "done" in the payload; put will carry ` +
+        `the recorded evidence forward automatically.`);
+}
 function validatePutTrustDossier(repoRoot, file, markdown) {
     const validated = validateBlueprintTrust({
         repoRoot,
@@ -374,6 +423,13 @@ export async function handleBlueprintPut(projectResolver, cwd, raw) {
     if (!p.success)
         return err("wp_blueprint_put validation error", p.error.message);
     const { project_id, slug, document, request_id, head_at_ingest } = p.data;
+    // Validate the slug against the canonical segment pattern before ANY
+    // routing or filesystem probe: an unvalidated slug such as "../../outside"
+    // would otherwise construct paths outside the blueprint root.
+    const slugSegments = slug.split("/");
+    if (slugSegments.length === 0 || !slugSegments.every((s) => isBlueprintSlugSegment(s))) {
+        return err("wp_blueprint_put validation error", `Invalid blueprint slug "${slug}": every segment must match lowercase [a-z0-9] with single hyphens.`);
+    }
     const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
     if ("content" in resolvedProject)
         return resolvedProject;
@@ -408,16 +464,34 @@ export async function handleBlueprintPut(projectResolver, cwd, raw) {
         if (found && found.state !== document.status) {
             return err("wp_blueprint_put refused", `Blueprint "${slug}" currently lives in "${found.state}" and cannot be rewritten as "${document.status}" without a lifecycle transition.`);
         }
+        // Failure atomicity: render and validate against the canonical folder
+        // path FIRST, and only canonicalize an existing flat document after every
+        // validation has passed. A validation failure must leave the flat file
+        // untouched; a persistence failure after conversion leaves the
+        // byte-identical document at the canonical folder path (retry-safe).
         const overviewPath = found
-            ? found.path
-            : getBlueprintDocumentPaths(root, document.status, slug).flat;
-        const markdown = renderBlueprintMarkdownFromDocument(slug, document);
+            ? found.shape === "flat"
+                ? getBlueprintDocumentPaths(root, found.state, slug).folder
+                : found.path
+            : getBlueprintDocumentPaths(root, document.status, slug).folder;
+        let markdown = renderBlueprintMarkdownFromDocument(slug, document);
+        if (found) {
+            const existingMarkdown = readFileSync(found.path, "utf8");
+            const preserved = preserveExistingTaskVerification(existingMarkdown, slug, document, markdown);
+            if ("error" in preserved) {
+                return err("wp_blueprint_put refused", preserved.error);
+            }
+            markdown = preserved.markdown;
+        }
         if (document.trust_dossier) {
             const trustDossierFailure = validatePutTrustDossier(writeCwd, overviewPath, markdown);
             if (trustDossierFailure) {
                 return err("wp_blueprint_put validation error", trustDossierFailure);
             }
         }
+        if (found && found.shape === "flat") {
+            await canonicalizeBlueprint(writeCwd, slug);
+        }
         const blueprint = await persistBlueprintMarkdown({
             projectCwd: writeCwd,
             slug,

package/dist/esm/mcp/blueprint/handlers/review-log.js

@@ -4,7 +4,7 @@ import matter from "gray-matter";
 import { z } from "zod";
 import { logReviewEntry, REVIEWER_IDS } from "#cli/commands/review.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
-import { isBlueprintSlugSegment } from "#utils/document-paths.js";
+import { folderBlueprintRequiredMessage, isBlueprintSlugSegment } from "#utils/document-paths.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
 import { err, finishPayload } from "#mcp/blueprint/_shared/errors";
@@ -98,6 +98,13 @@ export async function handleReviewLog(projectResolver, cwd, raw) {
     const found = findBlueprintDir(root, slug, ALL_BLUEPRINT_STATES);
     if (!found)
         return err("wp_blueprint_review_log failed", `Blueprint "${slug}" not found in any state directory`);
+    const shapeFailure = folderBlueprintRequiredMessage({
+        documentPath: found.path,
+        lifecycleSlug: `${found.state}/${slug}`,
+        shape: found.shape,
+    });
+    if (shapeFailure)
+        return err("wp_blueprint_review_log failed", shapeFailure);
     const blueprintDir = realpathSync(path.dirname(found.path));
     const artifactAbsolute = path.resolve(blueprintDir, normalizedArtifactPath);
     if (!artifactAbsolute.startsWith(`${blueprintDir}${path.sep}`)) {

package/dist/esm/mcp/blueprint/handlers/task-advance.js

@@ -8,12 +8,53 @@ import { dbPath, reIngest } from "#mcp/blueprint/_shared/db";
 import { err, finishPayload, jsonContent } from "#mcp/blueprint/_shared/errors";
 import { hashMutationPayload, readMutationReplay, recordMutationReplay, validateMutationFreshnessToken, } from "#mcp/blueprint/_shared/freshness";
 import { toStr } from "#mcp/blueprint/_shared/payload";
-import { resolveToolProject } from "#mcp/blueprint/_shared/project";
+import { findBlueprintDir, resolveToolProject } from "#mcp/blueprint/_shared/project";
 import { resolveSyncAdapter, runPlatformMutationSync } from "#mcp/blueprint/_shared/sync";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
 import { escapeRegex } from "#utils/string";
+import { withMarkdownWriteLock } from "#db/paths.js";
+import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
+const ALL_STATES = ["draft", "planned", "in-progress", "parked", "archived", "completed"];
+/**
+ * Matches the canonical task-heading grammar `parser.ts`'s `extractTasks`
+ * uses (`^####\s+(?:\[lane\]\s+)?Task\s+<id>:`), not a looser ad hoc pattern.
+ * The id is anchored on a trailing colon so "1.1" cannot match "1.10", and
+ * an optional `[lane]` prefix is accepted the same way the canonical parser
+ * does.
+ */
+function buildTaskHeadingPattern(taskId) {
+    return new RegExp(`^####\\s+(?:\\[[^\\]]+\\]\\s+)?Task\\s+${escapeRegex(taskId)}:`, "u");
+}
+function findTaskStatusLine(markdown, taskId) {
+    const lines = markdown.split("\n");
+    const headingPattern = buildTaskHeadingPattern(taskId);
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (headingPattern.test(line))
+            inBlock = true;
+        else if (inBlock && /^####\s+/u.test(line))
+            break;
+        else if (inBlock) {
+            // Preserve any inline metadata sharing the status line (the canonical
+            // format allows `**Status:** done | **Depends:** Task 1.1`) instead of
+            // overwriting the whole line and discarding it.
+            const match = line.match(/^(\*\*Status:\*\*\s*)(\S+)(.*)$/u);
+            if (match) {
+                return {
+                    lineIndex: i,
+                    prefix: match[1] ?? "",
+                    status: match[2] ?? "",
+                    suffix: match[3] ?? "",
+                };
+            }
+        }
+    }
+    return null;
+}
 const advanceSchema = z.object({
     project_id: z.string(),
+    slug: z.string(),
     task_id: z.string(),
     to: z.enum(["todo", "in-progress", "blocked", "done", "dropped"]),
     request_id: z.string().min(1).optional(),
@@ -23,7 +64,7 @@ export async function handleTaskAdvance(projectResolver, cwd, raw) {
     const p = advanceSchema.safeParse(raw);
     if (!p.success)
         return err("wp_blueprint_task_advance validation error", p.error.message);
-    const { project_id, task_id, to, request_id, head_at_ingest } = p.data;
+    const { project_id, slug, task_id, to, request_id, head_at_ingest } = p.data;
     const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
     if ("content" in resolvedProject)
         return resolvedProject;
@@ -32,7 +73,7 @@ export async function handleTaskAdvance(projectResolver, cwd, raw) {
     const freshnessFailure = validateMutationFreshnessToken(projectCwd, head_at_ingest, "wp_blueprint_task_advance", "wp_blueprint_list");
     if (freshnessFailure)
         return freshnessFailure;
-    const payloadHash = hashMutationPayload({ task_id, to });
+    const payloadHash = hashMutationPayload({ slug, task_id, to });
     const replay = request_id !== undefined
         ? readMutationReplay(projectCwd, "wp_blueprint_task_advance", request_id, payloadHash)
         : null;
@@ -54,70 +95,88 @@ export async function handleTaskAdvance(projectResolver, cwd, raw) {
         return err("wp_blueprint_task_advance failed", "Blueprint DB not found");
     try {
         const conn = openDb(target);
-        let oldStatus = null;
-        let filePath = null;
-        let blueprintSlug = null;
         try {
             const row = conn.db
-                .prepare("SELECT status, blueprint_slug FROM tasks WHERE task_id = ? LIMIT 1")
-                .get(task_id);
+                .prepare("SELECT status FROM tasks WHERE task_id = ? AND blueprint_slug = ? LIMIT 1")
+                .get(task_id, slug);
             if (!row)
-                return err("wp_blueprint_task_advance failed", `Task "${task_id}" not found in DB`);
-            oldStatus = row.status;
-            blueprintSlug = row.blueprint_slug;
-            const bp = conn.db
-                .prepare("SELECT file_path FROM blueprints WHERE slug = ?")
-                .get(row.blueprint_slug);
-            if (bp?.file_path)
-                filePath = bp.file_path;
+                return err("wp_blueprint_task_advance failed", `Task "${task_id}" not found in blueprint "${slug}"`);
         }
         finally {
             conn.close();
         }
+        // Derive the authoritative fromStatus from a live read of the blueprint's
+        // on-disk markdown, not the SQLite projection above (which is only
+        // re-ingested asynchronously and can be stale relative to the file --
+        // e.g. after a blueprint move/promotion changed its lifecycle directory).
+        // Fail closed here rather than proceeding with a guessed value, or later
+        // silently reporting success when the local write never happens.
+        const root = resolveBlueprintRoot(projectCwd);
+        const foundBeforePush = findBlueprintDir(root, slug, ALL_STATES);
+        if (!foundBeforePush || !existsSync(foundBeforePush.path)) {
+            return err("wp_blueprint_task_advance failed", `Blueprint "${slug}" overview file not found`);
+        }
+        const preStatus = findTaskStatusLine(readFileSync(foundBeforePush.path, "utf8"), task_id);
+        if (!preStatus) {
+            return err("wp_blueprint_task_advance failed", `Task "${task_id}" has no **Status:** line in blueprint "${slug}"`);
+        }
+        const oldStatus = preStatus.status;
         // Platform-first path: push event + pull fresh replica before local update.
         // Iron rule: resolveSyncAdapter() returns null when WP_BLUEPRINT_PLATFORM_DISABLED=1.
         const adapter = await resolveSyncAdapter(projectCwd);
-        if (blueprintSlug !== null && oldStatus !== null) {
-            try {
-                await runPlatformMutationSync(adapter, {
-                    label: "wp_blueprint_task_advance",
-                    event: {
-                        eventId: randomUUID(),
-                        repoId: process.env["WP_BLUEPRINT_PLATFORM_REPO_ID"] ?? "local",
-                        occurredAt: new Date().toISOString(),
+        try {
+            await runPlatformMutationSync(adapter, {
+                label: "wp_blueprint_task_advance",
+                event: {
+                    eventId: randomUUID(),
+                    repoId: process.env["WP_BLUEPRINT_PLATFORM_REPO_ID"] ?? "local",
+                    occurredAt: new Date().toISOString(),
+                    type: "task.status_changed",
+                    payload: {
                         type: "task.status_changed",
-                        payload: {
-                            type: "task.status_changed",
-                            blueprintSlug,
-                            taskId: task_id,
-                            fromStatus: oldStatus,
-                            toStatus: to,
-                        },
+                        blueprintSlug: slug,
+                        taskId: task_id,
+                        fromStatus: oldStatus,
+                        toStatus: to,
                     },
-                    ensureFreshSlug: blueprintSlug,
-                });
-            }
-            catch (e) {
-                return err("wp_blueprint_task_advance failed", toStr(e));
-            }
+                },
+                ensureFreshSlug: slug,
+            });
         }
-        // Always update local markdown + SQLite.
-        // Platform-first: these become derived artifacts; disabled: these are canonical.
-        if (filePath && existsSync(filePath)) {
-            const lines = readFileSync(filePath, "utf8").split("\n");
-            let inBlock = false;
-            for (let i = 0; i < lines.length; i++) {
-                const line = lines[i] ?? "";
-                if (line.match(new RegExp(`#### Task\\s+${escapeRegex(task_id)}`)))
-                    inBlock = true;
-                else if (inBlock && line.startsWith("#### "))
-                    break;
-                else if (inBlock && line.startsWith("**Status:**")) {
-                    lines[i] = `**Status:** ${to}`;
-                    break;
-                }
-            }
-            writeFileAtomic(filePath, lines.join("\n"), "utf8");
+        catch (e) {
+            return err("wp_blueprint_task_advance failed", toStr(e));
+        }
+        // Always update local markdown + SQLite. Re-resolve the path live INSIDE
+        // the repo-scoped write lock: a concurrent promotion can rename the
+        // blueprint's directory between the pre-push read above and this write.
+        // A missing blueprint or status line here is a genuine race, not
+        // something to paper over as success -- `wrote` makes that failure
+        // observable to the caller instead of silently no-op'ing.
+        let wrote = false;
+        await withMarkdownWriteLock(projectCwd, () => {
+            const liveFound = findBlueprintDir(root, slug, ALL_STATES);
+            const livePath = liveFound?.path;
+            if (!livePath || !existsSync(livePath))
+                return;
+            const markdown = readFileSync(livePath, "utf8");
+            const live = findTaskStatusLine(markdown, task_id);
+            if (!live)
+                return;
+            const lines = markdown.split("\n");
+            lines[live.lineIndex] = `${live.prefix}${to}${live.suffix}`;
+            writeFileAtomic(livePath, lines.join("\n"), "utf8");
+            wrote = true;
+        });
+        if (!wrote) {
+            // The platform mutation above already succeeded by this point (or was
+            // a no-op if platform sync is disabled) -- this failure therefore
+            // means platform and local state have genuinely diverged, not just
+            // that the local write was skipped harmlessly. There is no automatic
+            // reconciliation path today (that requires the platform-first
+            // mutation reconciliation work tracked separately, not built here);
+            // surface the divergence explicitly rather than a generic error so an
+            // operator knows this needs manual attention, not just a retry.
+            return err("wp_blueprint_task_advance failed", `Task "${task_id}" in blueprint "${slug}" could not be updated locally after the platform mutation already succeeded (blueprint or status line changed concurrently). Platform and local state have diverged and require manual reconciliation -- retrying this call alone will not fix it if the blueprint moved again.`);
         }
         try {
             await reIngest(projectCwd);

package/dist/esm/mcp/blueprint/handlers/task-verify.js

@@ -10,8 +10,9 @@ import { hashMutationPayload, readMutationReplay, recordMutationReplay, validate
 import { bytes } from "#mcp/blueprint/_shared/payload";
 import { findBlueprintDir, resolveToolProject } from "#mcp/blueprint/_shared/project";
 import { handleTaskNext } from "#mcp/blueprint/handlers/task-next";
-import { writeFileAtomic } from "#shared-utils/write-json-file.js";
-import { applyVerification, readTaskVerification } from "#verification.js";
+import { readTaskVerification } from "#verification.js";
+import { applyBlueprintLifecycle } from "#lifecycle/engine.js";
+import { applyBlueprintLifecycleToFile } from "#lifecycle/local.js";
 const ALL_STATES = ["draft", "planned", "in-progress", "parked", "archived", "completed"];
 // Task 3.2 — wp_blueprint_task_verify
 const taskVerifySchema = z.object({
@@ -52,13 +53,31 @@ export async function handleTaskVerify(projectResolver, cwd, raw) {
         return err("wp_blueprint_task_verify failed", `Blueprint overview not found at ${filePath}`);
     }
     const markdownBefore = readFileSync(filePath, "utf8");
-    // Idempotency check: if the task already has the same canonical evidence block, skip write.
-    // We check this BEFORE calling applyVerification to avoid whitespace normalization drift
-    // making `result.markdown !== markdownBefore` always true even for identical evidence.
     const incomingCanonical = canonicalizeEvidenceList(evidence);
     const existingEvidence = readTaskVerification(markdownBefore, task_id);
+    let result;
+    try {
+        result = applyBlueprintLifecycle(markdownBefore, slug, {
+            type: "task_verify",
+            taskId: task_id,
+            evidence,
+        });
+    }
+    catch (error) {
+        return jsonContent({
+            summary: "Verification failed",
+            failures: [error instanceof Error ? error.message : String(error)],
+            next_action: makeNextAction("verify_task", error instanceof Error ? error.message : String(error)),
+            bytes: 0,
+            tokensSaved: 0,
+        }, true);
+    }
+    // Idempotency includes all lifecycle-owned fields. Reapplying identical
+    // evidence repairs stale progress/last_updated metadata once, then becomes a
+    // byte-for-byte no-op.
     if (existingEvidence !== null &&
-        canonicalizeEvidenceList(existingEvidence) === incomingCanonical) {
+        canonicalizeEvidenceList(existingEvidence) === incomingCanonical &&
+        result.markdown === markdownBefore) {
         const nextPayload = parseStructuredJson(await handleTaskNext(projectResolver, projectCwd, {
             blueprint: slug,
             project_id: resolvedProject.project_id ?? projectCwd,
@@ -82,19 +101,20 @@ export async function handleTaskVerify(projectResolver, cwd, raw) {
         }
         return finishPayload(payload);
     }
-    // Apply verification (pure function — no FS side effects)
-    const result = applyVerification(markdownBefore, task_id, evidence);
-    if (!result.ok) {
-        return jsonContent({
-            summary: "Verification failed",
-            failures: result.failures,
-            next_action: makeNextAction("verify_task", result.failures[0] ?? "Verification failed"),
-            bytes: 0,
-            tokensSaved: 0,
-        }, true);
-    }
-    // Write updated markdown back to disk
-    writeFileAtomic(filePath, result.markdown, "utf8");
+    // Write the mutated markdown back to disk via the file-aware lifecycle
+    // wrapper, not a raw write to the pre-mutation path: the pure engine call
+    // above can change the blueprint's frontmatter `status` (e.g. draft ->
+    // in-progress on the first task mutation), and that status change must be
+    // paired with the matching physical folder move -- the same contract the
+    // CLI router and BlueprintService already honor via
+    // applyBlueprintLifecycleToFile. Writing to the original `filePath`
+    // unconditionally would leave folder and status disagreeing whenever the
+    // blueprint started outside in-progress/.
+    await applyBlueprintLifecycleToFile(projectCwd, slug, {
+        type: "task_verify",
+        taskId: task_id,
+        evidence,
+    });
     // Re-ingest so the DB projection reflects the completed status
     try {
         await reIngest(projectCwd);

package/dist/esm/mcp/blueprint/registration.js

@@ -107,16 +107,17 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
         type: "object",
         properties: { blueprint: { type: "string" }, project_id: { type: "string" } },
     }, undefined, (r) => handleTaskNext(projectResolver, cwd, r), { title: "Blueprint Task Next", readOnlyHint: true, openWorldHint: false });
-    registrar.registerTool("wp_blueprint_task_advance", "Advance task status. Edits the canonical blueprint markdown and re-syncs DB. Accepts optional request_id for idempotent retries and optional head_at_ingest from wp_blueprint_get/wp_blueprint_list to reject stale writes. Returns { summary, old_status, new_status, idempotent }.", {
+    registrar.registerTool("wp_blueprint_task_advance", "Advance task status within a specific blueprint. Requires slug to scope the mutation — task ids (e.g. 2.1) are not unique across blueprints in a project, so slug prevents advancing the wrong blueprint. Edits the canonical blueprint markdown and re-syncs DB. Accepts optional request_id for idempotent retries and optional head_at_ingest from wp_blueprint_get/wp_blueprint_list to reject stale writes. Returns { summary, old_status, new_status, idempotent }.", {
         type: "object",
         properties: {
             project_id: { type: "string" },
+            slug: { type: "string" },
             task_id: { type: "string" },
             to: { type: "string", enum: ["todo", "in-progress", "blocked", "done", "dropped"] },
             request_id: { type: "string" },
             head_at_ingest: { type: ["string", "null"] },
         },
-        required: ["project_id", "task_id", "to"],
+        required: ["project_id", "slug", "task_id", "to"],
     }, {
         ...summaryEnvelopeOutputSchema,
         properties: {

package/dist/esm/mcp/server.d.ts

@@ -7,6 +7,7 @@
  * — no edits required here.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function resolveMcpToolAllowlist(raw?: string | undefined): ReadonlySet<string> | null;
 export declare function isBunSingleFileModuleUrl(moduleUrl: string): boolean;
 export type ToolLoadMode = "filesystem" | "registry";
 export declare function resolveDefaultToolLoadMode(moduleUrl?: string): ToolLoadMode;

package/dist/esm/mcp/server.js

@@ -16,6 +16,24 @@ import { COMPILED_TOOL_REGISTRY } from "./tools/_registry.js";
 import { readOwnedPackageVersion } from "#runtime/package-version.js";
 const SERVER_NAME = "webpresso";
 const SERVER_VERSION = readOwnedPackageVersion(import.meta.url);
+const MCP_TOOL_ALLOWLIST_ENV = "WP_MCP_TOOL_ALLOWLIST";
+export function resolveMcpToolAllowlist(raw = process.env[MCP_TOOL_ALLOWLIST_ENV]) {
+    if (raw === undefined)
+        return null;
+    const names = raw
+        .split(",")
+        .map((name) => name.trim())
+        .filter(Boolean);
+    if (names.length === 0 || new Set(names).size !== names.length) {
+        throw new Error(`${MCP_TOOL_ALLOWLIST_ENV} must contain a non-empty, duplicate-free comma-separated tool list`);
+    }
+    for (const name of names) {
+        if (!/^wp_[a-z0-9_]+$/u.test(name)) {
+            throw new Error(`${MCP_TOOL_ALLOWLIST_ENV} contains invalid tool name: ${name}`);
+        }
+    }
+    return new Set(names);
+}
 function modulePathFromUrl(moduleUrl) {
     try {
         return fileURLToPath(moduleUrl);
@@ -53,8 +71,11 @@ export async function createServer(options = {}) {
         },
     });
     const tools = new Map();
+    const allowlist = resolveMcpToolAllowlist();
     const registrar = {
         registerTool(name, description, inputSchema, outputSchema, handler, annotations) {
+            if (allowlist !== null && !allowlist.has(name))
+                return;
             tools.set(name, { name, description, inputSchema, outputSchema, handler, annotations });
         },
     };
@@ -90,6 +111,12 @@ export async function createServer(options = {}) {
             }
         },
     });
+    if (allowlist !== null) {
+        const missing = [...allowlist].filter((name) => !tools.has(name));
+        if (missing.length > 0) {
+            throw new Error(`${MCP_TOOL_ALLOWLIST_ENV} names unavailable tools: ${missing.sort().join(", ")}`);
+        }
+    }
     // Empty prompts/resources/resource-templates handlers, registered exactly
     // the same way other MCP servers do. Several MCP clients —
     // including Claude Code 2.1.x and OpenCode — call listPrompts() or