@webpresso/agent-kit 0.21.4 → 0.23.0

package/dist/esm/mcp/blueprint-server.js

@@ -18,10 +18,12 @@ import path from 'node:path';
 import matter from 'gray-matter';
 import { z } from 'zod';
 import { parseBlueprint } from '#core/parser';
+import { setBlueprintFrontmatterFields } from '#lifecycle/engine';
 import { openDb } from '#db/connection.js';
 import { resolveBlueprintProjectionDbPath } from '#db/paths.js';
 import { findTemplate } from '#db/templates.js';
 import { resolveBlueprintRoot } from '#utils/blueprint-root.js';
+import { getBlueprintDocumentPaths } from '#utils/document-paths.js';
 import { evidenceListSchema, canonicalizeEvidenceList } from '#evidence.js';
 import { checkFreshness, readCurrentHead, readProjectionMetadata } from '#freshness.js';
 import { applyVerification, assertAllTasksHaveCanonicalPassingEvidence, readTaskVerification, } from '#verification.js';
@@ -93,6 +95,13 @@ async function resolveSyncAdapter(cwd) {
     };
 }
 const DEFAULT_PLATFORM_MUTATION_TIMEOUT_MS = 5_000;
+function todayIsoDate() {
+    return new Date().toISOString().split('T')[0] ?? new Date().toISOString();
+}
+function formatBlueprintProgress(totalTasks, doneTasks, blockedTasks) {
+    const percent = totalTasks === 0 ? 0 : Math.round((doneTasks / totalTasks) * 100);
+    return `${percent}% (${doneTasks}/${totalTasks} tasks done, ${blockedTasks} blocked, updated ${todayIsoDate()})`;
+}
 function readPlatformMutationTimeoutMs() {
     const parsed = Number.parseInt(process.env['WP_BLUEPRINT_PLATFORM_MUTATION_TIMEOUT_MS'] ??
         String(DEFAULT_PLATFORM_MUTATION_TIMEOUT_MS), 10);
@@ -242,11 +251,25 @@ function openDbRW(cwd) {
 async function reIngest(cwd) {
     await reIngestProjection(cwd);
 }
+async function persistBlueprintMarkdown(input) {
+    const { projectCwd, slug, blueprintPath, markdown } = input;
+    mkdirSync(path.dirname(blueprintPath), { recursive: true });
+    parseBlueprint(markdown, slug);
+    writeFileSync(blueprintPath, markdown, 'utf8');
+    await reIngest(projectCwd);
+    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!refreshed.blueprint) {
+        throw new Error(`Blueprint "${slug}" did not appear in the projection after write`);
+    }
+    return refreshed.blueprint;
+}
 function findBlueprintDir(blueprintRoot, slug, states) {
     for (const state of states) {
-        const d = path.join(blueprintRoot, state, slug);
-        if (existsSync(d))
-            return { dir: d, state };
+        const paths = getBlueprintDocumentPaths(blueprintRoot, state, slug);
+        if (existsSync(paths.flat))
+            return { dir: path.dirname(paths.flat), path: paths.flat, shape: 'flat', state };
+        if (existsSync(paths.directory))
+            return { dir: paths.directory, path: paths.folder, shape: 'folder', state };
     }
     return null;
 }
@@ -537,7 +560,7 @@ async function handleNew(cwd, raw) {
     }
     const b = bytes(template);
     const slug = titleToSlug(title);
-    const targetPath = path.join(resolveBlueprintRoot(cwd), 'draft', slug, '_overview.md');
+    const targetPath = getBlueprintDocumentPaths(resolveBlueprintRoot(cwd), 'draft', slug).flat;
     // Platform-first path: push event to register the blueprint before returning the scaffold.
     // Iron rule: resolveSyncAdapter() returns null when WP_BLUEPRINT_PLATFORM_DISABLED=1.
     const adapter = await resolveSyncAdapter(cwd);
@@ -866,7 +889,7 @@ async function handleTaskVerify(projectResolver, cwd, raw) {
     if (!found) {
         return err('wp_blueprint_task_verify failed', `Blueprint "${slug}" not found in any state directory`);
     }
-    const filePath = path.join(found.dir, '_overview.md');
+    const filePath = found.path;
     if (!existsSync(filePath)) {
         return err('wp_blueprint_task_verify failed', `Blueprint overview not found at ${filePath}`);
     }
@@ -961,12 +984,8 @@ async function handlePromote(projectResolver, cwd, raw) {
     const found = findBlueprintDir(root, slug, ALL_STATES);
     if (!found)
         return err('wp_blueprint_promote failed', `Blueprint "${slug}" not found in any state directory`);
-    const { dir: currentDir, state: currentState } = found;
-    const overviewPath = path.join(currentDir, '_overview.md');
-    const ts = readVt(projectCwd);
-    const mtime = existsSync(overviewPath) ? statSync(overviewPath).mtimeMs : 0;
-    if ((ts[slug] ?? 0) < mtime)
-        return err('wp_blueprint_promote refused', `Blueprint "${slug}" not validated since last write. Run wp_blueprint_validate first.`);
+    const { state: currentState } = found;
+    const overviewPath = found.path;
     if (to_state === 'completed') {
         try {
             assertBlueprintCanComplete(overviewPath, slug);
@@ -999,40 +1018,34 @@ async function handlePromote(projectResolver, cwd, raw) {
     catch (e) {
         return err('wp_blueprint_promote failed', toStr(e));
     }
-    const { renameSync } = await import('node:fs');
-    const destDir = path.join(root, to_state, slug);
-    mkdirSync(path.dirname(destDir), { recursive: true });
     try {
-        renameSync(currentDir, destDir);
+        const transitioned = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state,
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" promoted from "${currentState}" to "${to_state}"`,
+            slug,
+            from_state: currentState,
+            to_state,
+            new_path: transitioned.overviewPath,
+            status: transitioned.blueprint.status,
+            content_hash: transitioned.blueprint.content_hash,
+            revision: transitioned.blueprint.content_hash,
+            ingested_at: transitioned.blueprint.ingested_at,
+            failures: [],
+            bytes: 0,
+            tokensSaved: 0,
+        };
+        if (currentState === 'draft' && to_state === 'planned')
+            appendHint(payload, projectCwd, 'PLAN_REFINE');
+        return finishPayload(payload);
     }
     catch (e) {
-        return err('wp_blueprint_promote failed', `Directory move error: ${toStr(e)}`);
-    }
-    const destOverview = path.join(destDir, '_overview.md');
-    if (existsSync(destOverview)) {
-        const fm = matter(readFileSync(destOverview, 'utf8'));
-        fm.data['status'] = to_state;
-        writeFileSync(destOverview, matter.stringify(fm.content, fm.data), 'utf8');
-    }
-    try {
-        await reIngest(projectCwd);
-    }
-    catch {
-        /* non-fatal */
+        return err('wp_blueprint_promote failed', toStr(e));
     }
-    const payload = {
-        summary: `Blueprint "${slug}" promoted from "${currentState}" to "${to_state}"`,
-        slug,
-        from_state: currentState,
-        to_state,
-        new_path: destOverview,
-        failures: [],
-        bytes: 0,
-        tokensSaved: 0,
-    };
-    if (currentState === 'draft' && to_state === 'planned')
-        appendHint(payload, projectCwd, 'PLAN_REFINE');
-    return finishPayload(payload);
 }
 const finalizeSchema = z.object({ project_id: z.string().optional(), slug: z.string() });
 async function handleFinalize(projectResolver, cwd, raw) {
@@ -1075,7 +1088,7 @@ async function handleFinalize(projectResolver, cwd, raw) {
         return err('wp_blueprint_finalize failed', `Blueprint "${slug}" not found`);
     }
     try {
-        assertBlueprintCanComplete(path.join(found.dir, '_overview.md'), slug);
+        assertBlueprintCanComplete(found.path, slug);
     }
     catch (error) {
         return err('wp_blueprint_finalize refused', toStr(error));
@@ -1102,39 +1115,32 @@ async function handleFinalize(projectResolver, cwd, raw) {
     catch (e) {
         return err('wp_blueprint_finalize failed', toStr(e));
     }
-    const { renameSync } = await import('node:fs');
-    const destDir = path.join(root, 'completed', slug);
-    mkdirSync(path.dirname(destDir), { recursive: true });
     try {
-        renameSync(found.dir, destDir);
+        const transitioned = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state: 'completed',
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" finalized and moved to completed`,
+            slug,
+            new_path: transitioned.overviewPath,
+            status: transitioned.blueprint.status,
+            content_hash: transitioned.blueprint.content_hash,
+            revision: transitioned.blueprint.content_hash,
+            ingested_at: transitioned.blueprint.ingested_at,
+            failures: [],
+            bytes: 0,
+            tokensSaved: 0,
+        };
+        if (hasRecentAuditFinding(projectCwd))
+            appendHint(payload, projectCwd, 'AUDIT_FIX');
+        return finishPayload(payload);
     }
     catch (e) {
-        return err('wp_blueprint_finalize failed', `Directory move error: ${toStr(e)}`);
-    }
-    const destOverview = path.join(destDir, '_overview.md');
-    if (existsSync(destOverview)) {
-        const fm = matter(readFileSync(destOverview, 'utf8'));
-        fm.data['status'] = 'completed';
-        fm.data['completed_at'] = new Date().toISOString().split('T')[0] ?? '';
-        writeFileSync(destOverview, matter.stringify(fm.content, fm.data), 'utf8');
-    }
-    try {
-        await reIngest(projectCwd);
-    }
-    catch {
-        /* non-fatal */
+        return err('wp_blueprint_finalize failed', toStr(e));
     }
-    const payload = {
-        summary: `Blueprint "${slug}" finalized and moved to completed`,
-        slug,
-        new_path: destOverview,
-        failures: [],
-        bytes: 0,
-        tokensSaved: 0,
-    };
-    if (hasRecentAuditFinding(projectCwd))
-        appendHint(payload, projectCwd, 'AUDIT_FIX');
-    return finishPayload(payload);
 }
 function assertBlueprintCanComplete(overviewPath, slug) {
     const markdown = readFileSync(overviewPath, 'utf8');
@@ -1698,6 +1704,245 @@ const createSchema = MutationTarget.extend({
     request_id: z.string().min(1).optional(),
     head_at_ingest: z.string().nullable().optional(),
 });
+const putTaskSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'dropped']).default('todo'),
+    wave: z.string().optional(),
+    lane: z.string().optional(),
+    description: z.string().optional(),
+    acceptance: z.array(z.string().min(1)).min(1),
+});
+const putDocumentSchema = z.object({
+    type: z.literal('blueprint').default('blueprint'),
+    title: z.string().min(1),
+    status: z.enum(['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived']),
+    complexity: z.enum(['XS', 'S', 'M', 'L', 'XL']),
+    owner: z.string().min(1),
+    created: z.string().min(1),
+    last_updated: z.string().min(1),
+    progress: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    product_wedge_anchor: z.object({
+        stage_outcome: z.string().min(1),
+        consuming_surface: z.string().min(1),
+        new_user_visible_capability: z.string().min(1),
+    }),
+    summary: z.string().min(1),
+    tasks: z.array(putTaskSchema).min(1),
+});
+const putSchema = MutationTarget.extend({
+    slug: z.string().min(1),
+    document: putDocumentSchema,
+    request_id: z.string().min(1).optional(),
+    head_at_ingest: z.string().nullable().optional(),
+});
+function renderBlueprintMarkdownFromDocument(slug, document) {
+    const frontmatter = [
+        '---',
+        `type: ${document.type}`,
+        `title: ${document.title}`,
+        `status: ${document.status}`,
+        `complexity: ${document.complexity}`,
+        `owner: ${document.owner}`,
+        `created: '${document.created}'`,
+        `last_updated: '${document.last_updated}'`,
+        ...(document.progress ? [`progress: ${JSON.stringify(document.progress)}`] : []),
+        ...(document.tags && document.tags.length > 0
+            ? ['tags:', ...document.tags.map((tag) => `  - ${tag}`)]
+            : []),
+        '---',
+        '',
+    ];
+    const sections = [
+        `# ${document.title}`,
+        '',
+        '## Product wedge anchor',
+        '',
+        `- **Stage outcome:** ${document.product_wedge_anchor.stage_outcome}`,
+        `- **Consuming surface:** ${document.product_wedge_anchor.consuming_surface}`,
+        `- **New user-visible capability:** ${document.product_wedge_anchor.new_user_visible_capability}`,
+        '',
+        '## Summary',
+        '',
+        document.summary,
+        '',
+    ];
+    const taskBlocks = document.tasks.flatMap((task) => [
+        `#### Task ${task.id}: ${task.title}`,
+        '',
+        `**Status:** ${task.status}`,
+        ...(task.wave ? [`**Wave:** ${task.wave}`] : []),
+        ...(task.lane ? [`**Lane:** ${task.lane}`] : []),
+        ...(task.description ? ['', task.description] : []),
+        '',
+        '**Acceptance:**',
+        ...task.acceptance.map((item) => `- [ ] ${item}`),
+        '',
+    ]);
+    return [...frontmatter, ...sections, ...taskBlocks].join('\n').trimEnd() + '\n';
+}
+async function handleBlueprintPut(projectResolver, cwd, raw) {
+    const p = putSchema.safeParse(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;
+    const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
+    if ('content' in resolvedProject)
+        return resolvedProject;
+    const projectCwd = resolvedProject.cwd;
+    await ensureProjectionReady(projectCwd);
+    const freshnessFailure = validateMutationFreshnessToken(projectCwd, head_at_ingest, 'wp_blueprint_put', 'wp_blueprint_get');
+    if (freshnessFailure)
+        return freshnessFailure;
+    const payloadHash = hashMutationPayload({ slug, document });
+    const replay = request_id !== undefined
+        ? readMutationReplay(projectCwd, 'wp_blueprint_put', request_id, payloadHash)
+        : null;
+    if (replay)
+        return replay;
+    const root = resolveBlueprintRoot(projectCwd);
+    const found = findBlueprintDir(root, slug, ALL_STATES);
+    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.`);
+    }
+    if (!found && document.status !== 'draft') {
+        return err('wp_blueprint_put refused', `New blueprint "${slug}" must start in "draft"; use wp_blueprint_transition for later lifecycle moves.`);
+    }
+    const overviewPath = found
+        ? found.path
+        : getBlueprintDocumentPaths(root, document.status, slug).flat;
+    try {
+        const markdown = renderBlueprintMarkdownFromDocument(slug, document);
+        const blueprint = await persistBlueprintMarkdown({
+            projectCwd,
+            slug,
+            blueprintPath: overviewPath,
+            markdown,
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" written to ${overviewPath}`,
+            slug,
+            path: overviewPath,
+            status: blueprint.status,
+            content_hash: blueprint.content_hash,
+            ingested_at: blueprint.ingested_at,
+            revision: blueprint.content_hash,
+            idempotent: false,
+            failures: [],
+            next_action: makeNextAction('verify_task', 'Blueprint written. Next: validate or transition the latest revision token through the structured surface.'),
+            project_id: resolvedProject.project_id ?? projectCwd,
+        };
+        if (request_id !== undefined) {
+            recordMutationReplay(projectCwd, 'wp_blueprint_put', request_id, payloadHash, payload);
+        }
+        return finishPayload(payload);
+    }
+    catch (e) {
+        return err('wp_blueprint_put failed', toStr(e));
+    }
+}
+const transitionSchema = MutationTarget.extend({
+    slug: z.string().min(1),
+    to_state: z.enum(['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived']),
+    expected_version: z.string().min(1),
+});
+async function handleBlueprintTransition(projectResolver, cwd, raw) {
+    const p = transitionSchema.safeParse(raw);
+    if (!p.success)
+        return err('wp_blueprint_transition validation error', p.error.message);
+    const { project_id, slug, to_state, expected_version } = p.data;
+    const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
+    if ('content' in resolvedProject)
+        return resolvedProject;
+    const projectCwd = resolvedProject.cwd;
+    await ensureProjectionReady(projectCwd);
+    const target = dbPath(projectCwd);
+    if (!existsSync(target))
+        return err('wp_blueprint_transition failed', 'Blueprint DB not found');
+    const current = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!current.blueprint) {
+        return err('wp_blueprint_transition failed', `Blueprint "${slug}" not found`);
+    }
+    if (current.blueprint.content_hash !== expected_version) {
+        return jsonContent({
+            summary: `wp_blueprint_transition rejected a stale blueprint revision`,
+            failures: [
+                `expected_version "${expected_version}" does not match current content hash "${current.blueprint.content_hash}"`,
+            ],
+            error: 'stale_blueprint_revision',
+            next_action: makeNextAction('reingest_project', 'Call wp_blueprint_get again to fetch the latest content_hash before retrying the transition.'),
+            bytes: 0,
+            tokensSaved: 0,
+        }, true);
+    }
+    const root = resolveBlueprintRoot(projectCwd);
+    const found = findBlueprintDir(root, slug, ALL_STATES);
+    if (!found)
+        return err('wp_blueprint_transition failed', `Blueprint "${slug}" not found on disk`);
+    try {
+        const refreshed = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state,
+        });
+        return finishPayload({
+            summary: `Blueprint "${slug}" transitioned to ${to_state}`,
+            slug,
+            old_status: current.blueprint.status,
+            new_status: to_state,
+            status: refreshed.blueprint.status,
+            content_hash: refreshed.blueprint.content_hash,
+            revision: refreshed.blueprint.content_hash,
+            ingested_at: refreshed.blueprint.ingested_at,
+            failures: [],
+            project_id: resolvedProject.project_id ?? projectCwd,
+        });
+    }
+    catch (e) {
+        return err('wp_blueprint_transition failed', toStr(e));
+    }
+}
+async function applyLocalBlueprintTransition(input) {
+    const { projectCwd, slug, to_state, found } = input;
+    const root = resolveBlueprintRoot(projectCwd);
+    const overviewPath = found.path;
+    const parsed = runValidate(overviewPath);
+    if (!parsed.valid) {
+        throw new Error(parsed.gaps.join('; '));
+    }
+    const markdown = readFileSync(overviewPath, 'utf8');
+    const currentBlueprint = parseBlueprint(markdown, slug);
+    const updated = setBlueprintFrontmatterFields(markdown, {
+        status: to_state,
+        last_updated: todayIsoDate(),
+        completed_at: to_state === 'completed' ? todayIsoDate() : undefined,
+        progress: formatBlueprintProgress(currentBlueprint.tasks.length, currentBlueprint.tasks.filter((task) => task.status === 'done').length, currentBlueprint.tasks.filter((task) => task.status === 'blocked').length),
+    });
+    parseBlueprint(updated, slug);
+    const destination = getBlueprintDocumentPaths(root, to_state, slug);
+    mkdirSync(path.dirname(found.shape === 'flat' ? destination.flat : destination.directory), {
+        recursive: true,
+    });
+    let finalOverviewPath = overviewPath;
+    if (found.state !== to_state) {
+        const { renameSync } = await import('node:fs');
+        renameSync(found.shape === 'flat' ? overviewPath : found.dir, found.shape === 'flat' ? destination.flat : destination.directory);
+        finalOverviewPath = found.shape === 'flat' ? destination.flat : destination.folder;
+    }
+    writeFileSync(finalOverviewPath, updated, 'utf8');
+    await reIngest(projectCwd);
+    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!refreshed.blueprint) {
+        throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+    }
+    return {
+        blueprint: refreshed.blueprint,
+        overviewPath: finalOverviewPath,
+        fromState: found.state,
+    };
+}
 async function handleBlueprintCreate(projectResolver, cwd, raw) {
     const p = createSchema.safeParse(raw);
     if (!p.success)
@@ -1720,17 +1965,19 @@ async function handleBlueprintCreate(projectResolver, cwd, raw) {
     const today = new Date().toISOString().split('T')[0] ?? '';
     const slug = titleToSlug(title);
     const root = resolveBlueprintRoot(projectCwd);
-    const targetDir = path.join(root, 'draft', slug);
-    const overviewPath = path.join(targetDir, '_overview.md');
+    const overviewPath = getBlueprintDocumentPaths(root, 'draft', slug).flat;
     try {
-        mkdirSync(targetDir, { recursive: true });
+        mkdirSync(path.dirname(overviewPath), { recursive: true });
         const content = BLUEPRINT_TEMPLATE.replace(/{TITLE}/g, title)
             .replace(/{COMPLEXITY}/g, complexity)
             .replace(/{DATE}/g, today)
             .replace('{GOAL}', goal);
-        writeFileSync(overviewPath, content, 'utf8');
-        // Re-ingest so the DB reflects the new blueprint
-        await reIngest(projectCwd);
+        await persistBlueprintMarkdown({
+            projectCwd,
+            slug,
+            blueprintPath: overviewPath,
+            markdown: content,
+        });
         const b = bytes(content);
         const payload = {
             summary: `Blueprint "${slug}" created at ${overviewPath}`,
@@ -1788,12 +2035,64 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
         },
         required: ['title', 'goal_prompt'],
     }, undefined, (r) => handleNew(cwd, r), { title: 'Blueprint New', readOnlyHint: true, openWorldHint: false });
-    registrar.registerTool('wp_blueprint_validate', 'Validate _overview.md structure. Returns { valid, gaps }. Must pass before wp_blueprint_promote.', { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] }, undefined, (r) => handleValidate(cwd, r), { title: 'Blueprint Validate', readOnlyHint: false, openWorldHint: false });
+    registrar.registerTool('wp_blueprint_put', 'Create or replace a blueprint from a structured whole-document payload. Renders markdown, validates it, re-ingests the projection, and returns revision metadata.', {
+        type: 'object',
+        properties: {
+            project_id: { type: 'string' },
+            slug: { type: 'string' },
+            document: { type: 'object' },
+            request_id: { type: 'string' },
+            head_at_ingest: { type: ['string', 'null'] },
+        },
+        required: ['project_id', 'slug', 'document'],
+    }, {
+        ...summaryEnvelopeOutputSchema,
+        properties: {
+            ...summaryEnvelopeOutputSchema.properties,
+            slug: { type: 'string' },
+            path: { type: 'string' },
+            status: { type: 'string' },
+            content_hash: { type: 'string' },
+            ingested_at: { type: 'number' },
+            revision: { type: 'string' },
+            idempotent: { type: 'boolean' },
+            project_id: { type: 'string' },
+            next_action: nextActionOutputSchema,
+        },
+    }, (r) => handleBlueprintPut(projectResolver, cwd, r), { title: 'Blueprint Put', destructiveHint: false, openWorldHint: false });
+    registrar.registerTool('wp_blueprint_transition', 'Transition a blueprint lifecycle state using an expected revision token. Revalidates the latest markdown, rewrites frontmatter atomically, re-ingests the projection, and returns updated revision metadata.', {
+        type: 'object',
+        properties: {
+            project_id: { type: 'string' },
+            slug: { type: 'string' },
+            to_state: {
+                type: 'string',
+                enum: ['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived'],
+            },
+            expected_version: { type: 'string' },
+        },
+        required: ['project_id', 'slug', 'to_state', 'expected_version'],
+    }, {
+        ...summaryEnvelopeOutputSchema,
+        properties: {
+            ...summaryEnvelopeOutputSchema.properties,
+            slug: { type: 'string' },
+            old_status: { type: 'string' },
+            new_status: { type: 'string' },
+            status: { type: 'string' },
+            content_hash: { type: 'string' },
+            revision: { type: 'string' },
+            ingested_at: { type: 'number' },
+            project_id: { type: 'string' },
+            next_action: nextActionOutputSchema,
+        },
+    }, (r) => handleBlueprintTransition(projectResolver, cwd, r), { title: 'Blueprint Transition', destructiveHint: false, openWorldHint: false });
+    registrar.registerTool('wp_blueprint_validate', 'Validate canonical blueprint markdown structure (`<slug>.md` or `<slug>/_overview.md`). Returns { valid, gaps }. Must pass before wp_blueprint_promote.', { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] }, undefined, (r) => handleValidate(cwd, r), { title: 'Blueprint Validate', readOnlyHint: false, openWorldHint: false });
     registrar.registerTool('wp_blueprint_task_next', 'Return the next ready task (all deps done). Accepts optional project_id for nested-workspace disambiguation. Returns { summary, task }.', {
         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 _overview.md 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. 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' },
@@ -1911,7 +2210,7 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
         },
         required: [...summaryEnvelopeOutputSchema.required, 'chunks', 'total_bytes', 'project_id'],
     }, (r) => handleBlueprintContext(projectResolver, cwd, r), { title: 'Blueprint Context', readOnlyHint: true, openWorldHint: false });
-    registrar.registerTool('wp_blueprint_create', 'Create a new blueprint markdown under blueprints/draft/<slug>/_overview.md and re-ingest. Accepts optional request_id for idempotent retries and optional head_at_ingest from wp_blueprint_projects/wp_blueprint_list to reject stale writes. Returns { slug, path, next_action, idempotent }.', {
+    registrar.registerTool('wp_blueprint_create', 'Create a new blueprint markdown under blueprints/draft/<slug>.md by default (folder-shaped `<slug>/_overview.md` remains supported elsewhere) and re-ingest. Accepts optional request_id for idempotent retries and optional head_at_ingest from wp_blueprint_projects/wp_blueprint_list to reject stale writes. Returns { slug, path, next_action, idempotent }.', {
         type: 'object',
         properties: {
             project_id: { type: 'string' },

package/dist/esm/mcp/cli.js

@@ -12,18 +12,26 @@ import { createServer } from './server.js';
 export async function runStdioServer() {
     const server = await createServer();
     const transport = new StdioServerTransport();
+    const settle = Promise.withResolvers();
     let shuttingDown = false;
     const shutdown = async () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
         deleteSentinel();
+        try {
+            await transport.close();
+        }
+        catch {
+            /* ignore transport close errors during shutdown */
+        }
         try {
             await server.close();
         }
         catch {
             /* ignore close errors during shutdown */
         }
+        settle.resolve();
     };
     process.on('SIGINT', () => {
         void shutdown().then(() => process.exit(0));
@@ -31,8 +39,21 @@ export async function runStdioServer() {
     process.on('SIGTERM', () => {
         void shutdown().then(() => process.exit(0));
     });
+    process.stdin.on('end', () => {
+        void shutdown();
+    });
+    process.stdin.on('close', () => {
+        void shutdown();
+    });
+    transport.onclose = () => {
+        void shutdown();
+    };
+    transport.onerror = () => {
+        void shutdown();
+    };
     await server.connect(transport);
     writeSentinel();
+    await settle.promise;
 }
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';

package/dist/esm/mcp/runners/test.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { globSync } from 'glob';
+import { getPackageScript, isRecursiveWpScript, packageUsesVitest } from '#cli/package-scripts.js';
 import { isRunFailure, runCommand as runSharedCommand } from '#mcp/tools/_shared/run-command';
 // Keep the runner's own deadline comfortably below common MCP client call
 // ceilings so slow suites fail fast with a structured `timedOut` payload
@@ -55,6 +56,14 @@ export async function runTests(input) {
     if (workspaceShardRuns && workspaceShardRuns.length > 0) {
         return runScopedSequence(cwd, workspaceShardRuns, input, workspaceSharding);
     }
+    if (shouldBypassWorkspaceTestScript(cwd)) {
+        const result = await runCommand('vp', ['exec', '--', 'vitest', 'run', '--reporter=json', '--no-color'], {
+            ...input,
+            cwd,
+            timeoutMs: commandTimeoutMs,
+        });
+        return withFailureScope(result, 'workspace vitest command');
+    }
     const result = await runCommand('vp', ['run', 'test'], {
         ...input,
         cwd,
@@ -222,6 +231,12 @@ function hasRootVitestTestScript(cwd) {
     const testScript = scripts.test;
     return typeof testScript === 'string' && /\bvitest\b/.test(testScript);
 }
+function shouldBypassWorkspaceTestScript(cwd) {
+    const testScript = getPackageScript(cwd, 'test');
+    if (!testScript || !isRecursiveWpScript(testScript, 'test'))
+        return false;
+    return packageUsesVitest(cwd);
+}
 function discoverVitestFiles(cwd) {
     return globSync(VITEST_DEFAULT_INCLUDE, {
         cwd,

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

@@ -7,6 +7,7 @@
  * — no edits required here.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export type ToolLoadMode = 'filesystem' | 'registry';
 export interface CreateServerOptions {
     /**
      * Directory to scan for tool descriptors. Defaults to `./tools` relative to
@@ -14,6 +15,12 @@ export interface CreateServerOptions {
      * `vp run build`.
      */
     toolsDir?: string;
+    /**
+     * Tool loading strategy. Use `registry` for compiled runtime execution where
+     * runtime directory scans are unsafe, and `filesystem` for dev/test disk
+     * discovery.
+     */
+    toolLoadMode?: ToolLoadMode;
     /**
      * Repo working directory passed through to the blueprint structured-store
      * registrar (Task 2.1). Defaults to `process.cwd()`. Tests inject a tmpdir.