@webpresso/agent-kit 0.21.5 → 0.24.0

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/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/service/BlueprintCreationService.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { parseBlueprint } from '#core/parser';
 import { scanBlueprintDirectory } from '#service/scanner';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { getBlueprintDocumentPaths } from '#utils/document-paths.js';
 import { resolvePackageAssetPreferred } from '#utils/package-assets';
 const RESERVED_BLUEPRINT_SLUGS = new Set([
     'draft',
@@ -167,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;
@@ -205,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');
@@ -217,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,
@@ -247,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 {

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

@@ -11,6 +11,7 @@ import { parseBlueprint } from '#core/parser';
 import { applyBlueprintLifecycleToFile } from '#lifecycle/local';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
 import { emitTraceArtifact, generateBlueprintLifecycleTrace } from '#utils/decision-trace-artifacts';
+import { getBlueprintDocumentCandidates } from '#utils/document-paths.js';
 import { BlueprintNotFoundError } from '#utils/errors';
 import { computeBlueprintQuerySummary, matchesBlueprintFilters, sortBlueprintRecords, toBlueprintRecord, } from './blueprint-records.js';
 import { linkBlueprintToTechDebt, unlinkBlueprintFromTechDebt, } from './blueprint-tech-debt-links.js';
@@ -74,25 +75,28 @@ export class BlueprintService extends TrackedDocumentService {
     }
     async get(slug) {
         // Try direct path first (supports both 'in-progress/foo' and 'foo')
-        const planPath = path.join(this.baseDir, slug, '_overview.md');
-        try {
-            await fs.access(planPath);
-            const content = await fs.readFile(planPath, 'utf-8');
-            return parseBlueprint(content, slug);
-        }
-        catch {
-            // Scan all plans to find a match by slug
-            const scannedPlans = scanBlueprintDirectory({
-                baseDir: this.baseDir,
-                includeSpecialFolders: true,
-            });
-            const found = scannedPlans.find((p) => p.slug === slug || p.slug.endsWith(`/${slug}`));
-            if (!found) {
-                throw new BlueprintNotFoundError(slug, planPath, scannedPlans.map((p) => p.slug));
+        const directCandidates = getBlueprintDocumentCandidates(this.baseDir, slug);
+        for (const candidate of directCandidates) {
+            try {
+                await fs.access(candidate);
+                const content = await fs.readFile(candidate, 'utf-8');
+                return parseBlueprint(content, slug);
+            }
+            catch {
+                // Keep trying the remaining canonical shapes before falling back to a scan.
             }
-            const content = await fs.readFile(found.path, 'utf-8');
-            return parseBlueprint(content, found.slug);
         }
+        const searchedPath = directCandidates[0] ?? path.join(this.baseDir, slug, '_overview.md');
+        const scannedPlans = scanBlueprintDirectory({
+            baseDir: this.baseDir,
+            includeSpecialFolders: true,
+        });
+        const found = scannedPlans.find((p) => p.slug === slug || p.slug.endsWith(`/${slug}`));
+        if (!found) {
+            throw new BlueprintNotFoundError(slug, searchedPath, scannedPlans.map((p) => p.slug));
+        }
+        const content = await fs.readFile(found.path, 'utf-8');
+        return parseBlueprint(content, found.slug);
     }
     async query(options) {
         const scannedPlans = scanBlueprintDirectory({ baseDir: this.baseDir });
@@ -153,8 +157,22 @@ export class BlueprintService extends TrackedDocumentService {
      * @returns Array of TechDebtRecord objects
      */
     async getLinkedTechDebt(bpSlug) {
-        const blueprintPath = path.join(this.baseDir, bpSlug, '_overview.md');
-        const content = await fs.readFile(blueprintPath, 'utf-8');
+        const directCandidates = getBlueprintDocumentCandidates(this.baseDir, bpSlug);
+        let resolvedBlueprintPath = null;
+        for (const candidate of directCandidates) {
+            try {
+                await fs.access(candidate);
+                resolvedBlueprintPath = candidate;
+                break;
+            }
+            catch {
+                // Keep trying the other canonical shape.
+            }
+        }
+        const filePath = resolvedBlueprintPath ??
+            directCandidates[0] ??
+            path.join(this.baseDir, bpSlug, '_overview.md');
+        const content = await fs.readFile(filePath, 'utf-8');
         const parsed = matter(content);
         const data = JSON.parse(JSON.stringify(parsed.data));
         const linkedTechDebtSlugs = data.linked_tech_debt_slugs ?? [];

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

@@ -7,10 +7,18 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { BLUEPRINT_OVERVIEW_FILENAME, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
+const BLUEPRINT_STATUS_FOLDERS = new Set([
+    'draft',
+    'planned',
+    'parked',
+    'in-progress',
+    'completed',
+    'archived',
+]);
 /** Special folder prefixes that indicate archived/deferred plans */
 const SPECIAL_FOLDERS = ['_completed', '_future', '_deprioritized'];
 /** Standard plan overview filename */
-const OVERVIEW_FILENAME = '_overview.md';
 /**
  * Check if a path component is a special folder.
  */
@@ -28,6 +36,9 @@ function findSpecialFolderType(pathSegments) {
     }
     return undefined;
 }
+function isStatusFolder(name) {
+    return BLUEPRINT_STATUS_FOLDERS.has(name);
+}
 /**
  * Extract the slug and group from a plan path.
  *
@@ -39,15 +50,42 @@ function findSpecialFolderType(pathSegments) {
  * - 'webpresso/blueprints/_completed/old-plan/_overview.md'
  *   -> slug: '_completed/old-plan', group: null (special folder)
  */
-function extractSlugAndGroup(fullPath, baseDir, filePattern = OVERVIEW_FILENAME) {
-    // Get relative path from base directory
+function extractSlugAndGroup(fullPath, baseDir, filePattern = BLUEPRINT_OVERVIEW_FILENAME) {
     const relPath = relative(baseDir, fullPath);
-    // Split into segments and remove the document filename
-    const segments = relPath.split('/').filter((s) => s !== filePattern && s !== '');
+    const canonicalDocument = parseBlueprintDocumentRelativePath(relPath);
+    if (canonicalDocument) {
+        const slug = `${canonicalDocument.state}/${canonicalDocument.slug}`;
+        return {
+            slug,
+            group: canonicalDocument.state,
+        };
+    }
+    const relSegments = relPath.split('/').filter((s) => s !== '');
+    const segments = [...relSegments];
+    if (!segments.length) {
+        return { slug: '', group: null };
+    }
+    if (filePattern === BLUEPRINT_OVERVIEW_FILENAME) {
+        if (segments[segments.length - 1] === filePattern) {
+            segments.pop();
+        }
+    }
+    else if (filePattern.toLowerCase() === 'readme.md') {
+        if (segments[segments.length - 1] === filePattern) {
+            segments.pop();
+        }
+    }
+    else {
+        const last = segments[segments.length - 1] ?? '';
+        if (last === filePattern) {
+            segments[segments.length - 1] = last.replace(/\.md$/i, '');
+        }
+    }
     if (!segments.length) {
         return { slug: '', group: null };
     }
-    // Filter out special folders from the slug calculation for group determination
+    // Filter out archival special folders from group determination. Lifecycle
+    // status folders are part of the public slug and remain valid groups.
     const nonSpecialSegments = segments.filter((s) => !isSpecialFolder(s));
     // The slug is the full path (including special folders)
     const slug = segments.join('/');
@@ -68,7 +106,7 @@ function extractSlugAndGroup(fullPath, baseDir, filePattern = OVERVIEW_FILENAME)
  * Check if an entry should be skipped during directory traversal.
  */
 function shouldSkipEntry(entry) {
-    return entry.startsWith('.') || entry === 'node_modules';
+    return entry.startsWith('.') || entry.startsWith('__') || entry === 'node_modules';
 }
 /**
  * Safely get file stats, returning null on error.
@@ -126,11 +164,22 @@ function processEntry(entry, dir, baseDir, filePattern, includeSpecialFolders, r
         }
         return;
     }
+    if (filePattern === BLUEPRINT_OVERVIEW_FILENAME &&
+        entry.endsWith('.md') &&
+        entry !== 'README.md') {
+        const relativeParentSegments = relative(baseDir, dir).split('/').filter((s) => s !== '');
+        if (relativeParentSegments.length === 1 && isStatusFolder(relativeParentSegments[0] ?? '')) {
+            const plan = processPlanFile(fullPath, baseDir, includeSpecialFolders, entry);
+            if (plan) {
+                results.push(plan);
+            }
+        }
+    }
 }
 /**
  * Process a plan file (_overview.md or _overview.md) and create a ScannedBlueprint if applicable.
  */
-function processPlanFile(fullPath, baseDir, includeSpecialFolders, filePattern = OVERVIEW_FILENAME) {
+function processPlanFile(fullPath, baseDir, includeSpecialFolders, filePattern = BLUEPRINT_OVERVIEW_FILENAME) {
     const relativePath = relative(baseDir, fullPath);
     // Skip files in hidden directories (defense-in-depth check)
     if (containsHiddenDirectory(relativePath)) {
@@ -192,6 +241,21 @@ export function scanDocumentDirectory(options) {
     }
     const results = [];
     scanDirectory(absoluteBaseDir, absoluteBaseDir, filePattern, includeSpecialFolders, results);
+    const duplicates = new Map();
+    for (const result of results) {
+        const existing = duplicates.get(result.slug);
+        if (existing) {
+            existing.push(result.path);
+        }
+        else {
+            duplicates.set(result.slug, [result.path]);
+        }
+    }
+    const duplicate = Array.from(duplicates.entries()).find(([, paths]) => paths.length > 1);
+    if (duplicate) {
+        const [slug, paths] = duplicate;
+        throw new Error(`Duplicate blueprint slug "${slug}" found in multiple canonical shapes: ${paths.join(', ')}`);
+    }
     return results;
 }
 /**
@@ -205,7 +269,7 @@ export function scanBlueprintDirectory(options) {
     const includeSpecialFolders = options?.includeSpecialFolders ?? false;
     return scanDocumentDirectory({
         baseDir,
-        filePattern: OVERVIEW_FILENAME,
+        filePattern: BLUEPRINT_OVERVIEW_FILENAME,
         includeSpecialFolders,
     });
 }

package/dist/esm/blueprint/tracked-document/schema.d.ts

@@ -18,8 +18,8 @@ export declare const trackedDocumentStatusSchema: z.ZodEnum<{
     completed: "completed";
     draft: "draft";
     planned: "planned";
-    "in-progress": "in-progress";
     parked: "parked";
+    "in-progress": "in-progress";
     archived: "archived";
 }>;
 export type TrackedDocumentStatus = z.infer<typeof trackedDocumentStatusSchema>;
@@ -54,8 +54,8 @@ export declare const trackedDocumentFrontmatterSchema: z.ZodObject<{
         completed: "completed";
         draft: "draft";
         planned: "planned";
-        "in-progress": "in-progress";
         parked: "parked";
+        "in-progress": "in-progress";
         archived: "archived";
     }>;
     last_updated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>>;

package/dist/esm/blueprint/utils/document-paths.d.ts

@@ -0,0 +1,23 @@
+export declare const BLUEPRINT_OVERVIEW_FILENAME = "_overview.md";
+export declare const BLUEPRINT_STATUSES: readonly ["draft", "planned", "parked", "in-progress", "completed", "archived"];
+export type BlueprintStatus = (typeof BLUEPRINT_STATUSES)[number];
+export type BlueprintShape = 'flat' | 'folder';
+export interface BlueprintDocumentPath {
+    relativePath: string;
+    shape: BlueprintShape;
+    slug: string;
+    state: BlueprintStatus;
+}
+export declare function normalizeBlueprintPath(filePath: string): string;
+export declare function isBlueprintStatus(value: string | undefined): value is BlueprintStatus;
+export declare function isBlueprintSlugSegment(value: string | undefined): value is string;
+export declare function parseBlueprintDocumentRelativePath(filePath: string): BlueprintDocumentPath | null;
+export declare function isBlueprintSupportingMarkdownRelativePath(filePath: string): boolean;
+export declare function getBlueprintDocumentPaths(root: string, state: BlueprintStatus, slug: string): {
+    directory: string;
+    flat: string;
+    folder: string;
+};
+export declare function getBlueprintDocumentCandidates(root: string, slug: string): string[];
+export declare function getBlueprintAlternateDocumentPath(root: string, filePath: string): string | null;
+//# sourceMappingURL=document-paths.d.ts.map