@webpresso/agent-kit 0.21.4 → 0.23.0

package/dist/esm/audit/package-surface.js

@@ -47,6 +47,7 @@ const SKIP_DIRECTORIES = new Set([
     '.omx',
     '.omc',
     '.stryker-tmp',
+    '.webpresso-packed-surface',
     'node_modules',
     'dist',
     'build',
@@ -393,6 +394,7 @@ function stagePackedFiles(root, destinationRoot, candidate, packedFiles) {
 function runSecretlint(stageRoot, packageRoot) {
     const rcPath = findSecretlintRc(packageRoot);
     const outputFile = join(stageRoot, '.secretlint-output.json');
+    const toolRoot = findSecretlintToolRoot(packageRoot) ?? findSecretlintToolRoot(process.cwd());
     const args = ['exec', 'secretlint', '--format', 'json', '--output', outputFile, '--no-gitignore'];
     if (rcPath) {
         args.push('--secretlintrc', rcPath);
@@ -403,7 +405,7 @@ function runSecretlint(stageRoot, packageRoot) {
     args.push(join(stageRoot, '**/*'));
     try {
         execFileSync('pnpm', args, {
-            cwd: packageRoot,
+            cwd: toolRoot ?? packageRoot,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
             maxBuffer: 20 * 1024 * 1024,
@@ -421,6 +423,17 @@ function runSecretlint(stageRoot, packageRoot) {
         rmSync(outputFile, { force: true });
     }
 }
+function findSecretlintToolRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, 'node_modules', '.bin', 'secretlint')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
 function findSecretlintRc(root) {
     const candidates = [
         '.secretlintrc.json',

package/dist/esm/audit/repo-guardrails.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import matter from 'gray-matter';
 import { blueprintDerivedHandoffSchema } from '#execution/types';
+import { BLUEPRINT_OVERVIEW_FILENAME, isBlueprintSupportingMarkdownRelativePath, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
 import { validateLoreTrailers } from './commit-message-lore.js';
 const DEFAULT_COMMIT_TYPES = [
     'feat',
@@ -209,33 +210,59 @@ export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options =
         if (!existsSync(statusRoot))
             continue;
         for (const entry of readdirSync(statusRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+            if (!entry.isDirectory() && !entry.isFile())
                 continue;
-            const overviewPath = join(statusRoot, entry.name, '_overview.md');
-            checked += 1;
-            if (!existsSync(overviewPath)) {
-                violations.push({
-                    file: relativePath(root, overviewPath),
-                    message: 'Missing _overview.md',
-                });
+            const canonicalPath = entry.isDirectory()
+                ? join(statusRoot, entry.name, BLUEPRINT_OVERVIEW_FILENAME)
+                : join(statusRoot, entry.name);
+            const relativeBlueprintPath = relative(blueprintsRoot, canonicalPath);
+            const parsedPath = parseBlueprintDocumentRelativePath(relativeBlueprintPath);
+            if (entry.isDirectory()) {
+                checked += 1;
+                if (!existsSync(canonicalPath)) {
+                    const hasNestedMarkdown = readdirSync(join(statusRoot, entry.name), {
+                        withFileTypes: true,
+                    }).some((nested) => nested.isFile() && nested.name.endsWith('.md') && nested.name !== 'README.md');
+                    if (hasNestedMarkdown) {
+                        violations.push({
+                            file: relativePath(root, canonicalPath),
+                            message: 'Blueprint folders with supporting markdown must include _overview.md',
+                        });
+                    }
+                    else {
+                        violations.push({
+                            file: relativePath(root, canonicalPath),
+                            message: 'Missing _overview.md',
+                        });
+                    }
+                    continue;
+                }
+            }
+            else {
+                if (!parsedPath || isBlueprintSupportingMarkdownRelativePath(relativeBlueprintPath)) {
+                    continue;
+                }
+                checked += 1;
+            }
+            if (!parsedPath) {
                 continue;
             }
-            const raw = readFileSync(overviewPath, 'utf8');
+            const raw = readFileSync(canonicalPath, 'utf8');
             const frontmatter = matter(raw).data;
             if (frontmatter.type !== 'blueprint' && frontmatter.type !== 'parent-roadmap') {
                 violations.push({
-                    file: relativePath(root, overviewPath),
-                    message: 'Blueprint overview must use type: blueprint or parent-roadmap',
+                    file: relativePath(root, canonicalPath),
+                    message: 'Blueprint markdown must use type: blueprint or parent-roadmap',
                 });
             }
             if (frontmatter.status !== status) {
                 violations.push({
-                    file: relativePath(root, overviewPath),
+                    file: relativePath(root, canonicalPath),
                     message: `Blueprint status must match folder (${status})`,
                 });
             }
             violations.push(...validateBlueprintLinkingFrontmatter({
-                file: relativePath(root, overviewPath),
+                file: relativePath(root, canonicalPath),
                 frontmatter,
                 status,
             }));

package/dist/esm/audit/resolve-audit-script.d.ts

@@ -0,0 +1,24 @@
+export interface ResolveAuditScriptDeps {
+    /** `import.meta.url` of the calling module (`cli/commands/audit` or `mcp/tools/audit`). */
+    moduleUrl: string;
+    /** Existence probe; defaults to `fs.existsSync`. Injected in tests to model each layout. */
+    exists?: (url: URL) => boolean;
+}
+/**
+ * Resolve the absolute path of a Bun audit script (`audit-tph.ts`,
+ * `audit-tph-e2e.ts`) living in the sibling `audit/` directory two levels up
+ * from the caller.
+ *
+ * `../../audit/` is correct relative to the caller in BOTH layouts:
+ *   - dev:       `src/{cli,mcp}/.../audit.ts` → `src/audit/`
+ *   - published: `dist/esm/{cli,mcp}/.../audit.js` → `dist/esm/audit/`
+ *
+ * The npm tarball ships only `dist/` (never `src/`), so the dev `.ts` source is
+ * absent there — fall back to the compiled `.js` sibling the build emits. The
+ * previous CLI resolver instead hand-rolled a `<bundle>/src/audit/<name>.ts`
+ * path that does not exist in dist, which made `bun` fail with
+ * "Module not found"; the MCP twin reached for the unshipped `src/audit/` via
+ * `resolvePackageAsset` and failed the same way.
+ */
+export declare function resolveAuditScriptPath(name: string, { moduleUrl, exists }: ResolveAuditScriptDeps): string;
+//# sourceMappingURL=resolve-audit-script.d.ts.map

package/dist/esm/audit/resolve-audit-script.js

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the absolute path of a Bun audit script (`audit-tph.ts`,
+ * `audit-tph-e2e.ts`) living in the sibling `audit/` directory two levels up
+ * from the caller.
+ *
+ * `../../audit/` is correct relative to the caller in BOTH layouts:
+ *   - dev:       `src/{cli,mcp}/.../audit.ts` → `src/audit/`
+ *   - published: `dist/esm/{cli,mcp}/.../audit.js` → `dist/esm/audit/`
+ *
+ * The npm tarball ships only `dist/` (never `src/`), so the dev `.ts` source is
+ * absent there — fall back to the compiled `.js` sibling the build emits. The
+ * previous CLI resolver instead hand-rolled a `<bundle>/src/audit/<name>.ts`
+ * path that does not exist in dist, which made `bun` fail with
+ * "Module not found"; the MCP twin reached for the unshipped `src/audit/` via
+ * `resolvePackageAsset` and failed the same way.
+ */
+export function resolveAuditScriptPath(name, { moduleUrl, exists = existsSync }) {
+    const sourceUrl = new URL(`../../audit/${name}`, moduleUrl);
+    if (exists(sourceUrl)) {
+        return fileURLToPath(sourceUrl);
+    }
+    const compiledUrl = new URL(`../../audit/${name.replace(/\.ts$/, '.js')}`, moduleUrl);
+    return fileURLToPath(compiledUrl);
+}
+//# sourceMappingURL=resolve-audit-script.js.map

package/dist/esm/audit/roadmap-links.js

@@ -1,6 +1,7 @@
 import matter from 'gray-matter';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
+import { BLUEPRINT_OVERVIEW_FILENAME, isBlueprintSupportingMarkdownRelativePath, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
 const BLUEPRINT_STATUSES = [
     'draft',
     'planned',
@@ -11,7 +12,7 @@ const BLUEPRINT_STATUSES = [
 ];
 const BLUEPRINT_STATUS_PATTERN = BLUEPRINT_STATUSES.join('|');
 const ACTIVE_BLUEPRINT_STATUSES = new Set(['draft', 'planned', 'in-progress', 'parked']);
-const LOCAL_BLUEPRINT_REFERENCE_PATTERN = new RegExp(String.raw `^(?:blueprints/)?(?:${BLUEPRINT_STATUS_PATTERN})/[A-Za-z0-9._-]+(?:/_overview\.md)?$`);
+const LOCAL_BLUEPRINT_REFERENCE_PATTERN = new RegExp(String.raw `^(?:blueprints/)?(?:${BLUEPRINT_STATUS_PATTERN})/[A-Za-z0-9._-]+(?:\.md|/_overview\.md)?$`);
 const GITHUB_URL_PATTERN = /https?:\/\/github\.com\//i;
 const ABSOLUTE_FILE_REFERENCE_PATTERN = /(?:^|[\s(])(?:\/|[A-Za-z]:[\\/]|file:\/\/)/i;
 const LEGACY_CROSS_REPO_LABEL_PATTERN = /cross-repo:/i;
@@ -112,22 +113,32 @@ function readBlueprintRecords(root, blueprintsRoot) {
         if (!existsSync(statusRoot))
             continue;
         for (const entry of readdirSync(statusRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+            const canonicalPath = entry.isDirectory()
+                ? join(statusRoot, entry.name, BLUEPRINT_OVERVIEW_FILENAME)
+                : entry.isFile() && entry.name.endsWith('.md')
+                    ? join(statusRoot, entry.name)
+                    : null;
+            if (!canonicalPath || !existsSync(canonicalPath))
                 continue;
-            const overviewPath = join(statusRoot, entry.name, '_overview.md');
-            if (!existsSync(overviewPath))
+            const relativeBlueprintPath = relative(blueprintsRoot, canonicalPath);
+            if (!parseBlueprintDocumentRelativePath(relativeBlueprintPath) ||
+                isBlueprintSupportingMarkdownRelativePath(relativeBlueprintPath)) {
                 continue;
-            const raw = readFileSync(overviewPath, 'utf8');
+            }
+            const raw = readFileSync(canonicalPath, 'utf8');
             const data = matter(raw).data;
             const type = data.type === 'parent-roadmap' ? 'parent-roadmap' : 'blueprint';
             const parentRoadmap = typeof data.parent_roadmap === 'string' && data.parent_roadmap.trim()
                 ? data.parent_roadmap.trim()
                 : undefined;
-            const key = `${status}/${entry.name}`;
+            const parsedPath = parseBlueprintDocumentRelativePath(relativeBlueprintPath);
+            if (!parsedPath)
+                continue;
+            const key = `${status}/${parsedPath.slug}`;
             records.push({
-                file: relativePath(root, overviewPath),
+                file: relativePath(root, canonicalPath),
                 key,
-                name: entry.name,
+                name: parsedPath.slug,
                 ...(parentRoadmap ? { parentRoadmap } : {}),
                 raw,
                 slug: key,
@@ -146,16 +157,18 @@ function indexBlueprints(records) {
         byKey.set(record.name, record);
         byKey.set(`blueprints/${record.key}`, record);
         byKey.set(`blueprints/${record.key}/_overview.md`, record);
+        byKey.set(`blueprints/${record.key}.md`, record);
         byKey.set(`${record.key}/_overview.md`, record);
+        byKey.set(`${record.key}.md`, record);
     }
     return byKey;
 }
 function extractWaveMapChildren(markdown) {
     const refs = new Set();
-    const pathPattern = new RegExp(String.raw `(?:blueprints/)?(${BLUEPRINT_STATUS_PATTERN})/([A-Za-z0-9._-]+)(?:/_overview\.md)?`, 'g');
+    const pathPattern = new RegExp(String.raw `(?:blueprints/)?(${BLUEPRINT_STATUS_PATTERN})/([A-Za-z0-9._-]+)(?:\.md|/_overview\.md)?`, 'g');
     for (const match of markdown.matchAll(pathPattern)) {
         const status = match[1];
-        const slug = match[2];
+        const slug = match[2]?.replace(/\.md$/, '');
         if (!status || !slug)
             continue;
         refs.add(`${status}/${slug}`);

package/dist/esm/blueprint/core/schema.d.ts

@@ -19,8 +19,8 @@ export declare const planStatusSchema: z.ZodEnum<{
     completed: "completed";
     draft: "draft";
     planned: "planned";
-    "in-progress": "in-progress";
     parked: "parked";
+    "in-progress": "in-progress";
     archived: "archived";
 }>;
 /**
@@ -30,8 +30,8 @@ export declare const lifecycleBlueprintStatusSchema: z.ZodEnum<{
     completed: "completed";
     draft: "draft";
     planned: "planned";
-    "in-progress": "in-progress";
     parked: "parked";
+    "in-progress": "in-progress";
     archived: "archived";
 }>;
 /**
@@ -71,8 +71,8 @@ export declare const crossRepoDependencySchema: z.ZodObject<{
         completed: "completed";
         draft: "draft";
         planned: "planned";
-        "in-progress": "in-progress";
         parked: "parked";
+        "in-progress": "in-progress";
         archived: "archived";
     }>>;
 }, z.core.$strip>;
@@ -82,7 +82,7 @@ export declare const crossRepoDependencySchema: z.ZodObject<{
  * Required fields:
  * - type: `blueprint` or `parent-roadmap`
  * - status: Current plan status
- * - complexity: Estimated effort using t-shirt sizing
+ * - complexity: Estimated effort using t-shirt sizing (defaults to `M` when omitted for legacy blueprints)
  *
  * Optional fields:
  * - last_updated: Date plan was last modified (YYYY-MM-DD)
@@ -101,17 +101,17 @@ export declare const planFrontmatterSchema: z.ZodObject<{
         completed: "completed";
         draft: "draft";
         planned: "planned";
-        "in-progress": "in-progress";
         parked: "parked";
+        "in-progress": "in-progress";
         archived: "archived";
     }>;
-    complexity: z.ZodEnum<{
+    complexity: z.ZodDefault<z.ZodEnum<{
         XS: "XS";
         S: "S";
         M: "M";
         L: "L";
         XL: "XL";
-    }>;
+    }>>;
     last_updated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>>;
     created: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>>;
     progress: z.ZodOptional<z.ZodString>;
@@ -146,8 +146,8 @@ export declare const planFrontmatterSchema: z.ZodObject<{
             completed: "completed";
             draft: "draft";
             planned: "planned";
-            "in-progress": "in-progress";
             parked: "parked";
+            "in-progress": "in-progress";
             archived: "archived";
         }>>;
     }, z.core.$strip>>>;

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

@@ -64,7 +64,7 @@ export const crossRepoDependencySchema = z.object({
  * Required fields:
  * - type: `blueprint` or `parent-roadmap`
  * - status: Current plan status
- * - complexity: Estimated effort using t-shirt sizing
+ * - complexity: Estimated effort using t-shirt sizing (defaults to `M` when omitted for legacy blueprints)
  *
  * Optional fields:
  * - last_updated: Date plan was last modified (YYYY-MM-DD)
@@ -77,7 +77,7 @@ export const planFrontmatterSchema = z.object({
     title: z.string().optional(),
     description: z.string().optional(),
     status: planStatusSchema,
-    complexity: complexitySchema,
+    complexity: complexitySchema.default('M'),
     last_updated: z.union([z.string(), z.date()]).optional(),
     created: z.union([z.string(), z.date()]).optional(),
     progress: z.string().optional(),

package/dist/esm/blueprint/db/enums.d.ts

@@ -13,8 +13,8 @@ export declare const blueprintStatusSchema: z.ZodEnum<{
     completed: "completed";
     draft: "draft";
     planned: "planned";
-    "in-progress": "in-progress";
     parked: "parked";
+    "in-progress": "in-progress";
     archived: "archived";
 }>;
 export declare const blueprintComplexitySchema: z.ZodEnum<{

package/dist/esm/blueprint/db/ingester.js

@@ -2,18 +2,24 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { Database } from '#db/sqlite.js';
-import { glob } from 'glob';
 import { parseBlueprintForDb } from './parser/blueprint-db-parser.js';
 import { parseTechDebtForDb } from './parser/tech-debt-db-parser.js';
 import { resolvesCrossRepo } from '#cross-repo/resolver.js';
+import { scanBlueprintDirectory } from '#service/scanner.js';
 import { resolveBlueprintRoot } from '#utils/blueprint-root.js';
+import { parseBlueprintDocumentRelativePath } from '#utils/document-paths.js';
 import { resolveTechDebtRoot } from '#utils/tech-debt-root.js';
+import { glob } from 'glob';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function deriveSlugFromBlueprintPath(filePath) {
-    // blueprints/<status>/<slug>/_overview.md  →  slug is the grandparent dir name
-    return path.basename(path.dirname(filePath));
+function deriveSlugFromBlueprintPath(filePath, blueprintRoot) {
+    const relativePath = path.relative(blueprintRoot, filePath);
+    const parsed = parseBlueprintDocumentRelativePath(relativePath);
+    if (!parsed) {
+        throw new Error(`Not a canonical blueprint document: ${filePath}`);
+    }
+    return parsed.slug;
 }
 function deriveSlugFromTechDebtPath(filePath) {
     // tech-debt/<status>/h-NNN-slug.md  →  slug is the basename without extension
@@ -47,9 +53,9 @@ function isAllowedCrossOrg(db, sourceOrg, targetOrg) {
 // ---------------------------------------------------------------------------
 // Blueprint ingester
 // ---------------------------------------------------------------------------
-function upsertBlueprint(db, filePath, _cwd) {
+function upsertBlueprint(db, filePath, blueprintRoot) {
     const content = readFileSync(filePath, 'utf8');
-    const slug = deriveSlugFromBlueprintPath(filePath);
+    const slug = deriveSlugFromBlueprintPath(filePath, blueprintRoot);
     const parsed = parseBlueprintForDb(content, filePath, slug);
     const now = Date.now();
     const upsertBp = db.prepare(`INSERT INTO blueprints
@@ -197,18 +203,20 @@ export async function ingestBlueprints(opts) {
     const errors = [];
     let ingested = 0;
     const blueprintRoot = resolveBlueprintRoot(cwd);
-    const pattern = path.join(blueprintRoot, '**', '_overview.md').replace(/\\/g, '/');
-    const files = await glob(pattern, { absolute: true, nodir: true });
+    const files = scanBlueprintDirectory({
+        baseDir: blueprintRoot,
+        includeSpecialFolders: true,
+    }).map((entry) => entry.path);
     for (const filePath of files) {
         try {
             const content = readFileSync(filePath, 'utf8');
-            const slug = deriveSlugFromBlueprintPath(filePath);
+            const slug = deriveSlugFromBlueprintPath(filePath, blueprintRoot);
             const newHash = createHash('sha256').update(content).digest('hex');
             if (!dryRun) {
                 const existing = existingBlueprintHash(db, slug);
                 if (existing === newHash)
                     continue;
-                upsertBlueprint(db, filePath, cwd);
+                upsertBlueprint(db, filePath, blueprintRoot);
             }
             ingested++;
         }

package/dist/esm/blueprint/index.d.ts

@@ -16,7 +16,6 @@ export { validatePlanTemplate } from './core/validation/template.js';
 export { type BlueprintDiff, type DiffChange, type DiffFieldChange, formatDiffForDisplay, generateBlueprintDiff, } from './history/diff.js';
 export { checkAllCheckboxes, checkFirstCheckbox, extractCodeBlocks, extractTaskSection, updateBlockedReason, updateTaskStatus, } from './markdown/helpers.js';
 export { applyBlueprintLifecycle, type BlueprintLifecycleIntent, type BlueprintLifecycleResult, type LifecycleTaskStatus, } from './lifecycle/engine.js';
-export { type GraphEdge, type GraphEdgeType, type GraphLayout, type GraphNode, type GraphNodeType, type NormalizedGraph, parseMermaidToGraph, serializeGraphToMermaid, taskGraphToNormalizedGraph, } from './graph/index.js';
 export type { BlueprintQueryFilters, BlueprintQueryResult, BlueprintQuerySummary, BlueprintRecord, BlueprintSortField, BlueprintSortOptions, Complexity, SortDirection, TaskStatus, } from './query/types.js';
 export { isBlueprintStatus, isComplexity, isTaskStatus } from './query/types.js';
 export { BlueprintNotFoundError } from './utils/errors.js';

package/dist/esm/blueprint/index.js

@@ -17,8 +17,6 @@ export { formatDiffForDisplay, generateBlueprintDiff, } from './history/diff.js'
 // Markdown helpers (pure functions)
 export { checkAllCheckboxes, checkFirstCheckbox, extractCodeBlocks, extractTaskSection, updateBlockedReason, updateTaskStatus, } from './markdown/helpers.js';
 export { applyBlueprintLifecycle, } from './lifecycle/engine.js';
-// Graph model + Mermaid integration
-export { parseMermaidToGraph, serializeGraphToMermaid, taskGraphToNormalizedGraph, } from './graph/index.js';
 export { isBlueprintStatus, isComplexity, isTaskStatus } from './query/types.js';
 export { BlueprintNotFoundError } from './utils/errors.js';
 // Evidence Contract (F10) — pin per-kind evidence rules at zod parse time.

package/dist/esm/blueprint/lifecycle/audit.js

@@ -8,11 +8,18 @@ import { readBlueprintExecutionMetadata } from '#execution/metadata';
 import { BlueprintService } from '#service/BlueprintService';
 import { scanBlueprintDirectory } from '#service/scanner';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { parseBlueprintDocumentRelativePath } from '#utils/document-paths.js';
 import { relativeBlueprintSlug } from './local.js';
 function isBlueprintOverview(file) {
     const normalized = file.replace(/\\/g, '/');
-    return (normalized.endsWith('/_overview.md') &&
-        (normalized.includes('webpresso/blueprints/') || normalized.includes('blueprints/')));
+    const roots = ['webpresso/blueprints/', 'blueprints/'];
+    for (const root of roots) {
+        const index = normalized.indexOf(root);
+        if (index === -1)
+            continue;
+        return parseBlueprintDocumentRelativePath(normalized.slice(index + root.length)) !== null;
+    }
+    return false;
 }
 function normalizePath(file) {
     return file.replace(/\\/g, '/');

package/dist/esm/blueprint/lifecycle/local.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { applyBlueprintLifecycle } from '#lifecycle/engine';
 import { scanBlueprintDirectory } from '#service/scanner';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { getBlueprintDocumentPaths } from '#utils/document-paths.js';
 const BLUEPRINT_SLUG_SEGMENT_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function isStatusSegment(segment) {
     return (segment === 'draft' ||
@@ -73,10 +74,20 @@ export async function applyBlueprintLifecycleToFile(projectRoot, slug, intent) {
     const location = await resolveBlueprintFile(projectRoot, slug);
     const raw = await readFile(location.path, 'utf-8');
     const mutation = applyBlueprintLifecycle(raw, location.slug, intent);
+    const relativeSlug = relativeBlueprintSlug(location.slug);
+    const isFlatFile = path.basename(location.path) !== '_overview.md';
     const sourceDir = path.dirname(location.path);
-    const targetDir = path.join(baseDir, mutation.targetStatus, relativeBlueprintSlug(location.slug));
-    const targetPath = path.join(targetDir, '_overview.md');
-    if (sourceDir !== targetDir) {
+    const targetDocumentPaths = getBlueprintDocumentPaths(baseDir, mutation.targetStatus, relativeSlug);
+    const targetDir = targetDocumentPaths.directory;
+    const targetPath = isFlatFile ? targetDocumentPaths.flat : targetDocumentPaths.folder;
+    if (isFlatFile) {
+        if (location.path !== targetPath) {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await rename(location.path, targetPath);
+            await tryRemoveEmptyParent(sourceDir);
+        }
+    }
+    else if (sourceDir !== targetDir) {
         await mkdir(path.dirname(targetDir), { recursive: true });
         await rename(sourceDir, targetDir);
         await tryRemoveEmptyParent(path.dirname(sourceDir));
@@ -84,7 +95,7 @@ export async function applyBlueprintLifecycleToFile(projectRoot, slug, intent) {
     await writeFile(targetPath, mutation.markdown, 'utf-8');
     return {
         ...mutation,
-        moved: sourceDir !== targetDir,
+        moved: isFlatFile ? location.path !== targetPath : sourceDir !== targetDir,
         path: targetPath,
         slug: location.slug,
     };

package/dist/esm/blueprint/local.d.ts

@@ -4,9 +4,6 @@
  * These exports use Node.js APIs (fs, simple-git) and are NOT compatible with Cloudflare Workers.
  * For Workers-safe functions, use the main 'webpresso/blueprint' entry point.
  */
-export type { FalseDependency, ParallelizeResult, TaskFiles, TaskPairAnalysis, } from './dag/local/independence.js';
-export { createMockPackageGraph, IndependenceDetector } from './dag/local/independence.js';
-export { createMockFileSystem, PackageGraph, realFileSystem } from './dag/local/package-graph.js';
 export { type AcceptanceCriteria, type Blueprint, buildRoadmapModel, buildBlueprintProgressBridgeState, type BlueprintStatus, type BlueprintTaskStatus, checkAcceptanceCriteria, checkAllCheckboxes, checkChangelog, checkFirstCheckbox, complexitySchema, type CriteriaResult, extractTaskSection, formatDiffForDisplay, generateBlueprintDiff, isBlueprintStatus, isComplexity, isTaskStatus, lifecycleBlueprintStatusSchema, normalizeOmxTeamTaskSnapshot, type OmxTeamTaskSnapshot, type Phase, parseBlueprint, type PlanComplexity, type PlanFrontmatter, planStatusSchema, projectBlueprintLifecycleFromRuntime, resolveBlueprintProgressBridgePath, type RoadmapModel, type RoadmapNode, type RoadmapRollup, type RoadmapLike, serializeBlueprint, type Task, taskStatusSchema, type TaskStatusValue, updateBlockedReason, updateTaskStatus, type ValidationResult, validateEmbeddedPhases, validatePlanLinks, validatePlanState, validatePlanTemplate, } from './index.js';
 export { BlueprintCreationService, type BlueprintCreationServiceOptions, type BlueprintDraft, type CreateBlueprintInput, type CreatedBlueprint, } from './service/BlueprintCreationService.js';
 export { type BlueprintQueryOptions, BlueprintService, type BlueprintSummary, } from './service/BlueprintService.js';

package/dist/esm/blueprint/local.js

@@ -4,8 +4,6 @@
  * These exports use Node.js APIs (fs, simple-git) and are NOT compatible with Cloudflare Workers.
  * For Workers-safe functions, use the main 'webpresso/blueprint' entry point.
  */
-export { createMockPackageGraph, IndependenceDetector } from './dag/local/independence.js';
-export { createMockFileSystem, PackageGraph, realFileSystem } from './dag/local/package-graph.js';
 // Workers-safe exports for convenience (explicit re-export to avoid wildcard)
 export { buildRoadmapModel, buildBlueprintProgressBridgeState, checkAcceptanceCriteria, checkAllCheckboxes, checkChangelog, checkFirstCheckbox, complexitySchema, extractTaskSection, formatDiffForDisplay, generateBlueprintDiff, isBlueprintStatus, isComplexity, isTaskStatus, lifecycleBlueprintStatusSchema, normalizeOmxTeamTaskSnapshot, parseBlueprint, planStatusSchema, projectBlueprintLifecycleFromRuntime, resolveBlueprintProgressBridgePath, serializeBlueprint, taskStatusSchema, updateBlockedReason, updateTaskStatus, validateEmbeddedPhases, validatePlanLinks, validatePlanState, validatePlanTemplate, } from './index.js';
 // Services (require filesystem/git)

package/dist/esm/blueprint/service/BlueprintCreationService.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { parseBlueprint } from '#core/parser';
 import { scanBlueprintDirectory } from '#service/scanner';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
-import { resolvePackageAsset } from '#utils/package-assets';
+import { getBlueprintDocumentPaths } from '#utils/document-paths.js';
+import { resolvePackageAssetPreferred } from '#utils/package-assets';
 const RESERVED_BLUEPRINT_SLUGS = new Set([
     'draft',
     'planned',
@@ -13,7 +14,10 @@ const RESERVED_BLUEPRINT_SLUGS = new Set([
     'completed',
     'archived',
 ]);
-const DEFAULT_TEMPLATE_PATH = resolvePackageAsset('docs/templates/blueprint.md');
+const DEFAULT_TEMPLATE_PATH = resolvePackageAssetPreferred([
+    'docs/templates/blueprint.md',
+    'catalog/docs/templates/blueprint.md',
+]);
 function formatDate(date) {
     return date.toISOString().split('T')[0] ?? date.toISOString();
 }
@@ -164,7 +168,7 @@ export class BlueprintCreationService {
         assertGoalProducesUsableSlug(goal, baseSlug);
         const slug = this.resolveCollisionSafeSlug(baseSlug);
         const title = sentenceCase(goal);
-        const outputPath = path.join(this.blueprintsRoot, 'draft', slug, '_overview.md');
+        const outputPath = getBlueprintDocumentPaths(this.blueprintsRoot, 'draft', slug).flat;
         const relativeFilePath = toPortableRelativePath(this.projectRoot, outputPath);
         const date = formatDate(this.now());
         const template = type === 'blueprint' ? prepareTemplate(await readFile(this.templatePath, 'utf-8')) : undefined;
@@ -202,11 +206,11 @@ export class BlueprintCreationService {
     async create(input) {
         const draft = await this.compileDraft(input);
         const draftRoot = path.join(this.blueprintsRoot, 'draft');
-        const finalDir = path.dirname(draft.outputPath);
+        const finalPath = draft.outputPath;
         await mkdir(draftRoot, { recursive: true });
-        await mkdir(path.dirname(finalDir), { recursive: true });
+        await mkdir(path.dirname(finalPath), { recursive: true });
         const tempDir = await mkdtemp(path.join(draftRoot, `${draft.slug}.tmp-`));
-        const tempPath = path.join(tempDir, '_overview.md');
+        const tempPath = path.join(tempDir, `${draft.slug}.md`);
         try {
             await writeFile(tempPath, draft.markdown, 'utf-8');
             const writtenMarkdown = await readFile(tempPath, 'utf-8');
@@ -214,7 +218,8 @@ export class BlueprintCreationService {
             if (!validation.valid || !validation.blueprint) {
                 throw new Error(validation.error ?? 'Generated blueprint failed validation.');
             }
-            await rename(tempDir, finalDir);
+            await rename(tempPath, finalPath);
+            await rm(tempDir, { force: true, recursive: true });
             return {
                 ...draft,
                 blueprint: validation.blueprint,
@@ -244,7 +249,10 @@ export class BlueprintCreationService {
     }
 }
 function blueprintDirectoryExists(blueprintsRoot, slug) {
-    return [...RESERVED_BLUEPRINT_SLUGS].some((status) => existsSync(path.join(blueprintsRoot, status, slug)));
+    return [...RESERVED_BLUEPRINT_SLUGS].some((status) => {
+        const paths = getBlueprintDocumentPaths(blueprintsRoot, status, slug);
+        return existsSync(paths.directory) || existsSync(paths.flat);
+    });
 }
 async function removeIfEmpty(directory) {
     try {