@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -54,11 +54,103 @@ 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"],
+    },
+    {
+        // blueprint-server.ts owns the MCP architecture contract (tool naming,
+        // handler wiring, transport shape). Its architecture test is not colocated
+        // under the same basename, so --affected would otherwise skip it.
+        when: /^src\/mcp\/blueprint-server\./u,
+        tests: ["src/mcp/blueprint-server.test-architecture.test.ts"],
+    },
+    {
+        // Package surface / publishability contracts live in the audit package,
+        // not next to package.json or the manifest builder.
+        when: /^(package\.json|src\/build\/package-manifest\.ts)$/u,
+        tests: ["src/audit/package-surface.test.ts"],
+    },
+    {
+        // Marketplace and plugin.json validation is a build-side contract test.
+        when: /^\.claude-plugin\/(marketplace|plugin)\.json$/u,
+        tests: ["src/build/validate-marketplace.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.d.ts

@@ -194,6 +194,11 @@ export declare const putInputJsonSchema: {
                                     last_result: {
                                         type: string;
                                     };
+                                    defer: {
+                                        type: string;
+                                        const: string;
+                                        description: string;
+                                    };
                                 };
                                 required: string[];
                                 additionalProperties: boolean;

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

@@ -2,14 +2,18 @@ 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 { taskIdSchema } from "#core/schema";
 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";
@@ -37,7 +41,7 @@ const createSchema = MutationTarget.extend({
     head_at_ingest: z.string().nullable().optional(),
 });
 const putTaskSchema = z.object({
-    id: z.string().min(1),
+    id: taskIdSchema,
     title: z.string().min(1),
     status: z.enum(["todo", "in-progress", "blocked", "done", "dropped"]).default("todo"),
     wave: z.string().optional(),
@@ -69,6 +73,12 @@ const putPromotionGateSchema = z.object({
     command: z.string().min(1),
     expected_outcome: z.string().min(1),
     last_result: z.string().min(1),
+    // Explicit per-gate pre-implementation deferral. When set, `wp blueprint
+    // promote` skips executing/existence-checking this gate's command entirely
+    // and records a `deferred: ...` Last result instead. See
+    // src/blueprint/trust/promotion.ts and catalog/agent/rules
+    // /pre-implementation.md's Promotion gate section.
+    defer: z.literal("pre-implementation").optional(),
 });
 const putTrustDossierSchema = z.object({
     readiness: putTrustReadinessSchema,
@@ -177,6 +187,11 @@ const putTrustDossierJsonSchema = {
                     command: { type: "string", description: "wp or ./bin/wp facade command" },
                     expected_outcome: { type: "string" },
                     last_result: { type: "string" },
+                    defer: {
+                        type: "string",
+                        const: "pre-implementation",
+                        description: "Explicit opt-in: skip executing/existence-checking this gate at promote time",
+                    },
                 },
                 required: ["gate", "command", "expected_outcome", "last_result"],
                 additionalProperties: false,
@@ -320,12 +335,7 @@ function renderTrustDossierMarkdown(dossier) {
         "",
         "### Promotion Gates",
         "",
-        ...renderMarkdownTable(["Gate", "Command", "Expected outcome", "Last result"], dossier.promotion_gates.map((gate) => [
-            gate.gate,
-            gate.command,
-            gate.expected_outcome,
-            gate.last_result,
-        ])),
+        ...renderPromotionGatesTable(dossier.promotion_gates),
         "",
         "### Residual Unknowns",
         "",
@@ -333,6 +343,23 @@ function renderTrustDossierMarkdown(dossier) {
         "",
     ];
 }
+// Only emits the (opt-in) Defer column when at least one gate uses it, so
+// the common no-defer case keeps rendering the legacy 4-column table exactly
+// as before -- matching src/blueprint/trust/dossier.ts's parser, which
+// accepts either width.
+function renderPromotionGatesTable(gates) {
+    const hasDefer = gates.some((gate) => gate.defer !== undefined);
+    if (!hasDefer) {
+        return renderMarkdownTable(["Gate", "Command", "Expected outcome", "Last result"], gates.map((gate) => [gate.gate, gate.command, gate.expected_outcome, gate.last_result]));
+    }
+    return renderMarkdownTable(["Gate", "Command", "Expected outcome", "Last result", "Defer"], gates.map((gate) => [
+        gate.gate,
+        gate.command,
+        gate.expected_outcome,
+        gate.last_result,
+        gate.defer ?? "",
+    ]));
+}
 function normalizeResidualUnknowns(value) {
     if (value === undefined)
         return "None.";
@@ -353,6 +380,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 +447,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 +488,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);