@webpresso/agent-kit 0.21.0

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

@@ -0,0 +1,92 @@
+import { mkdir, readFile, readdir, rename, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { applyBlueprintLifecycle } from '#lifecycle/engine';
+import { scanBlueprintDirectory } from '#service/scanner';
+import { resolveBlueprintRoot } from '#utils/blueprint-root';
+const BLUEPRINT_SLUG_SEGMENT_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isStatusSegment(segment) {
+    return (segment === 'draft' ||
+        segment === 'planned' ||
+        segment === 'parked' ||
+        segment === 'in-progress' ||
+        segment === 'completed' ||
+        segment === 'archived');
+}
+export function relativeBlueprintSlug(slug) {
+    const segments = slug.split('/');
+    if (segments.length > 1 && isStatusSegment(segments[0])) {
+        return segments.slice(1).join('/');
+    }
+    return slug;
+}
+export function isValidBlueprintSlug(slug) {
+    const normalized = slug.trim();
+    if (normalized.length === 0 || normalized !== slug) {
+        return false;
+    }
+    const segments = normalized.split('/');
+    return segments.every((segment) => BLUEPRINT_SLUG_SEGMENT_PATTERN.test(segment));
+}
+function assertValidBlueprintSlug(slug) {
+    if (isValidBlueprintSlug(slug)) {
+        return;
+    }
+    throw new Error(`Invalid blueprint slug: ${slug}. Use lowercase letters, numbers, and hyphen-separated path segments.`);
+}
+export async function resolveBlueprintFile(projectRoot, slug) {
+    assertValidBlueprintSlug(slug);
+    const baseDir = resolveBlueprintRoot(projectRoot);
+    const scanned = scanBlueprintDirectory({
+        baseDir,
+        includeSpecialFolders: true,
+    });
+    const exactMatch = scanned.find((entry) => entry.slug === slug);
+    const suffixMatches = scanned.filter((entry) => entry.slug.endsWith(`/${slug}`) || entry.slug === slug);
+    const match = exactMatch ?? suffixMatches[0];
+    if (!match) {
+        const available = scanned.map((entry) => entry.slug).toSorted();
+        throw new Error([
+            `Blueprint ${slug} not found.`,
+            `Available blueprints: ${available.join(', ') || 'none'}`,
+        ].join('\n'));
+    }
+    if (suffixMatches.length > 1 && !exactMatch) {
+        throw new Error(`Blueprint slug "${slug}" is ambiguous across lifecycle folders. Matches: ${suffixMatches
+            .map((entry) => entry.slug)
+            .join(', ')}`);
+    }
+    return { path: match.path, slug: match.slug };
+}
+async function tryRemoveEmptyParent(dir) {
+    try {
+        const entries = await readdir(dir);
+        if (entries.length === 0) {
+            await rmdir(dir);
+        }
+    }
+    catch {
+        // Directory may not exist or may not be removable — ignore silently
+    }
+}
+export async function applyBlueprintLifecycleToFile(projectRoot, slug, intent) {
+    const baseDir = resolveBlueprintRoot(projectRoot);
+    const location = await resolveBlueprintFile(projectRoot, slug);
+    const raw = await readFile(location.path, 'utf-8');
+    const mutation = applyBlueprintLifecycle(raw, location.slug, intent);
+    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) {
+        await mkdir(path.dirname(targetDir), { recursive: true });
+        await rename(sourceDir, targetDir);
+        await tryRemoveEmptyParent(path.dirname(sourceDir));
+    }
+    await writeFile(targetPath, mutation.markdown, 'utf-8');
+    return {
+        ...mutation,
+        moved: sourceDir !== targetDir,
+        path: targetPath,
+        slug: location.slug,
+    };
+}
+//# sourceMappingURL=local.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * webpresso/blueprint/local - CLI-only exports
+ *
+ * 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';
+export { type ScannedBlueprint, type ScanOptions, scanBlueprintDirectory, } from './service/scanner.js';
+export { runBlueprintAudit, type BlueprintAuditIssue, type BlueprintAuditResult, type RunBlueprintAuditOptions, } from './lifecycle/audit.js';
+export { applyBlueprintLifecycle, type BlueprintLifecycleIntent, type BlueprintLifecycleResult, type LifecycleTaskStatus, } from './lifecycle/engine.js';
+export { applyBlueprintLifecycleToFile, relativeBlueprintSlug, resolveBlueprintFile, type BlueprintLifecycleWriteResult, type ResolvedBlueprintFile, } from './lifecycle/local.js';
+export { type TechDebtQueryOptions, TechDebtService, type TechDebtSummary, } from './service/TechDebtService.js';
+export { archiveBlueprint, type ArchiveResult, type IncompleteTask, type ValidationResult as ArchiveValidationResult, validateAllTasksDone, } from './utils/archive.js';
+export { type ConflictInfo, type ConflictResolution, ConflictResolver, createConflictResolver, type ResolvedConflict, } from './utils/conflict.js';
+export { BlueprintNotFoundError } from './utils/errors.js';
+//# sourceMappingURL=local.d.ts.map

package/dist/esm/blueprint/local.js

@@ -0,0 +1,25 @@
+/**
+ * webpresso/blueprint/local - CLI-only exports
+ *
+ * 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)
+export { BlueprintCreationService, } from './service/BlueprintCreationService.js';
+export { BlueprintService, } from './service/BlueprintService.js';
+export { scanBlueprintDirectory, } from './service/scanner.js';
+export { runBlueprintAudit, } from './lifecycle/audit.js';
+export { applyBlueprintLifecycle, } from './lifecycle/engine.js';
+export { applyBlueprintLifecycleToFile, relativeBlueprintSlug, resolveBlueprintFile, } from './lifecycle/local.js';
+export { TechDebtService, } from './service/TechDebtService.js';
+// Archive (requires git)
+export { archiveBlueprint, validateAllTasksDone, } from './utils/archive.js';
+// Conflict Resolution
+export { ConflictResolver, createConflictResolver, } from './utils/conflict.js';
+// Error Types
+export { BlueprintNotFoundError } from './utils/errors.js';
+//# sourceMappingURL=local.js.map

package/dist/esm/blueprint/markdown/helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plan Markdown Helpers
+ *
+ * Pure functions for patching markdown plan files.
+ * Used by AgentBlueprintContext for task status updates.
+ *
+ * All functions are idempotent - running them multiple times
+ * produces identical output (for the same inputs).
+ */
+export declare function extractCodeBlocks(content: string, language: string): string[];
+export declare function extractTaskSection(raw: string, taskId: string): string | null;
+export declare function checkFirstCheckbox(content: string, taskId: string): string;
+export declare function checkAllCheckboxes(content: string, taskId: string): string;
+export declare function completeTask(content: string, taskId: string): string;
+export declare function updateBlockedReason(content: string, taskId: string, reason: string): string;
+export declare function updateTaskStatus(content: string, taskId: string, status: 'todo' | 'in_progress' | 'blocked' | 'done'): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/esm/blueprint/markdown/helpers.js

@@ -0,0 +1,92 @@
+/**
+ * Plan Markdown Helpers
+ *
+ * Pure functions for patching markdown plan files.
+ * Used by AgentBlueprintContext for task status updates.
+ *
+ * All functions are idempotent - running them multiple times
+ * produces identical output (for the same inputs).
+ */
+import { escapeRegex } from '#utils/string';
+import { buildTaskHeaderRegexForId, buildTaskSectionBoundaryRegex, TASK_HEADING_PREFIX_PATTERN, } from './task-heading.js';
+function buildTaskPattern(taskId) {
+    return new RegExp(`(####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+${escapeRegex(taskId)}[:\\s].*?)(?=\\n####|\\n###|$)`, 's');
+}
+function insertAfterTaskTitle(section, line) {
+    const titleMatch = section.match(new RegExp(`(####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+[^\\n]+\\n+)`));
+    if (!titleMatch) {
+        return `${section}\n${line}\n`;
+    }
+    return section.replace(titleMatch[0], `${titleMatch[0]}${line}\n\n`);
+}
+function insertAfterStatusLine(section, line) {
+    const statusMatch = section.match(/(\*\*Status:\*\*\s*.+\n+)/i);
+    if (!statusMatch) {
+        return insertAfterTaskTitle(section, line);
+    }
+    return section.replace(statusMatch[0], `${statusMatch[0]}${line}\n\n`);
+}
+export function extractCodeBlocks(content, language) {
+    const escapedLanguage = escapeRegex(language);
+    const blockPattern = new RegExp('^```\\s*' + escapedLanguage + '\\s*\\n([\\s\\S]*?)\\n```\\s*$', 'gm');
+    return Array.from(content.matchAll(blockPattern), (match) => (match[1] ?? '').trim());
+}
+export function extractTaskSection(raw, taskId) {
+    const headerPattern = buildTaskHeaderRegexForId(taskId);
+    const headerMatch = raw.match(headerPattern);
+    if (!headerMatch || headerMatch.index === undefined)
+        return null;
+    const startIndex = headerMatch.index;
+    const restOfContent = raw.slice(startIndex + headerMatch[0].length);
+    const nextSectionMatch = restOfContent.match(buildTaskSectionBoundaryRegex());
+    const endIndex = nextSectionMatch?.index
+        ? startIndex + headerMatch[0].length + nextSectionMatch.index
+        : raw.length;
+    return raw.slice(startIndex, endIndex).trim();
+}
+export function checkFirstCheckbox(content, taskId) {
+    const taskPattern = buildTaskPattern(taskId);
+    return content.replace(taskPattern, (section) => {
+        return section.replace(/- \[ \]/, '- [x]');
+    });
+}
+export function checkAllCheckboxes(content, taskId) {
+    const taskPattern = buildTaskPattern(taskId);
+    return content.replace(taskPattern, (section) => {
+        return section.replace(/- \[ \]/g, '- [x]');
+    });
+}
+export function completeTask(content, taskId) {
+    const markedDone = updateTaskStatus(content, taskId, 'done');
+    const unblocked = updateBlockedReason(markedDone, taskId, '');
+    return checkAllCheckboxes(unblocked, taskId);
+}
+export function updateBlockedReason(content, taskId, reason) {
+    const taskPattern = buildTaskPattern(taskId);
+    return content.replace(taskPattern, (section) => {
+        const trimmedReason = reason.trim();
+        const blockedPattern = /\n?\*\*Blocked:\*\*\s*.*(?:\n+)?/i;
+        if (!trimmedReason) {
+            return section
+                .replace(blockedPattern, '\n')
+                .replace(/\n{3,}/g, '\n\n')
+                .trimEnd();
+        }
+        const blockedLine = `**Blocked:** ${trimmedReason}`;
+        if (/\*\*Blocked:\*\*/i.test(section)) {
+            return section.replace(/\*\*Blocked:\*\*\s*.+/i, blockedLine);
+        }
+        return insertAfterStatusLine(section, blockedLine);
+    });
+}
+export function updateTaskStatus(content, taskId, status) {
+    const taskPattern = buildTaskPattern(taskId);
+    return content.replace(taskPattern, (section) => {
+        const statusLine = `**Status:** ${status}`;
+        if (/\*\*Status:\*\*/i.test(section)) {
+            return section.replace(/\*\*Status:\*\*\s*.+/i, statusLine);
+        }
+        return insertAfterTaskTitle(section, statusLine);
+    });
+}
+//# sourceMappingURL=helpers.js.map

package/dist/esm/blueprint/markdown/task-heading.d.ts

@@ -0,0 +1,8 @@
+export declare const TASK_HEADING_PREFIX_PATTERN = "(?:\\[[^\\]]+\\]\\s+)?";
+export declare const TASK_ID_PATTERN = "\\d+(?:\\.\\d+)+";
+export declare function taskHeadingPatternSource(taskIdPattern?: string): string;
+export declare function buildTaskHeadingRegex(flags?: string): RegExp;
+export declare function buildTaskHeaderRegexForId(taskId: string, flags?: string): RegExp;
+export declare function buildTaskSectionBoundaryRegex(flags?: string): RegExp;
+export declare function isTaskHeaderLine(line: string): boolean;
+//# sourceMappingURL=task-heading.d.ts.map

package/dist/esm/blueprint/markdown/task-heading.js

@@ -0,0 +1,19 @@
+import { escapeRegex } from '#utils/string';
+export const TASK_HEADING_PREFIX_PATTERN = '(?:\\[[^\\]]+\\]\\s+)?';
+export const TASK_ID_PATTERN = '\\d+(?:\\.\\d+)+';
+export function taskHeadingPatternSource(taskIdPattern = TASK_ID_PATTERN) {
+    return `####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+(${taskIdPattern}):\\s*(.+)`;
+}
+export function buildTaskHeadingRegex(flags = 'gm') {
+    return new RegExp(`^${taskHeadingPatternSource()}$`, flags);
+}
+export function buildTaskHeaderRegexForId(taskId, flags = 'm') {
+    return new RegExp(`^####\\s+${TASK_HEADING_PREFIX_PATTERN}Task\\s+${escapeRegex(taskId)}:`, flags);
+}
+export function buildTaskSectionBoundaryRegex(flags = 'm') {
+    return new RegExp(`^(?:####\\s+${TASK_HEADING_PREFIX_PATTERN}Task|###\\s+Phase)`, flags);
+}
+export function isTaskHeaderLine(line) {
+    return buildTaskHeadingRegex('m').test(line);
+}
+//# sourceMappingURL=task-heading.js.map

package/dist/esm/blueprint/next-action.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NextAction — discriminated union for MCP tool routing hints (F18).
+ *
+ * Six MCP blueprint tools return `next_action` to nudge agents toward the
+ * follow-up call that resolves a failed read or mutation. Without a single
+ * source of truth, hint strings drift between handler code and the agent
+ * routing logic that consumes them.
+ *
+ * This module is the only source of truth for those values. New kinds must
+ * extend `NEXT_ACTION_KINDS` and the matching `NextAction` union together so
+ * exhaustive `switch` statements force a compile error when a case is
+ * forgotten.
+ *
+ * Wire-shape: `{ kind, hint }`. `hint` is human-readable guidance; it must
+ * be non-empty so audit trails remain grep-able.
+ */
+export declare const NEXT_ACTION_KINDS: readonly ["rebuild_db", "reingest_project", "disambiguate_slug", "verify_task", "create_blueprint", "configure_workspace", "unsupported_roots"];
+export type NextActionKind = (typeof NEXT_ACTION_KINDS)[number];
+export type NextAction = {
+    readonly kind: NextActionKind;
+    readonly hint: string;
+};
+/** Build a `NextAction` with a required non-empty hint. */
+export declare function makeNextAction(kind: NextActionKind, hint: string): NextAction;
+/** Type-guard for tagged-union narrowing at boundary IO (MCP, JSON, tests). */
+export declare function isNextAction(value: unknown): value is NextAction;
+//# sourceMappingURL=next-action.d.ts.map

package/dist/esm/blueprint/next-action.js

@@ -0,0 +1,45 @@
+/**
+ * NextAction — discriminated union for MCP tool routing hints (F18).
+ *
+ * Six MCP blueprint tools return `next_action` to nudge agents toward the
+ * follow-up call that resolves a failed read or mutation. Without a single
+ * source of truth, hint strings drift between handler code and the agent
+ * routing logic that consumes them.
+ *
+ * This module is the only source of truth for those values. New kinds must
+ * extend `NEXT_ACTION_KINDS` and the matching `NextAction` union together so
+ * exhaustive `switch` statements force a compile error when a case is
+ * forgotten.
+ *
+ * Wire-shape: `{ kind, hint }`. `hint` is human-readable guidance; it must
+ * be non-empty so audit trails remain grep-able.
+ */
+export const NEXT_ACTION_KINDS = [
+    'rebuild_db',
+    'reingest_project',
+    'disambiguate_slug',
+    'verify_task',
+    'create_blueprint',
+    'configure_workspace',
+    'unsupported_roots',
+];
+Object.freeze(NEXT_ACTION_KINDS);
+/** Build a `NextAction` with a required non-empty hint. */
+export function makeNextAction(kind, hint) {
+    if (hint.trim().length === 0) {
+        throw new Error('NextAction hint must be a non-empty string');
+    }
+    return { kind, hint };
+}
+/** Type-guard for tagged-union narrowing at boundary IO (MCP, JSON, tests). */
+export function isNextAction(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    if (typeof obj.kind !== 'string')
+        return false;
+    if (typeof obj.hint !== 'string')
+        return false;
+    return NEXT_ACTION_KINDS.includes(obj.kind);
+}
+//# sourceMappingURL=next-action.js.map

package/dist/esm/blueprint/project-resolver.d.ts

@@ -0,0 +1,31 @@
+import { type BlueprintProjectRef, type ResolveBlueprintProjectsOptions } from '#projects.js';
+export interface ResolveProjectTarget {
+    readonly cwd: string;
+    readonly projectId?: string;
+    readonly discovery?: Omit<ResolveBlueprintProjectsOptions, 'cwd'>;
+}
+export type ResolveProjectResult = {
+    readonly ok: true;
+    readonly cwd: string;
+    readonly project_id: string | null;
+} | {
+    readonly ok: false;
+    readonly reason: 'not_found' | 'ambiguous';
+    readonly summary: string;
+    readonly hint: string;
+    readonly candidates: readonly BlueprintProjectRef[];
+};
+export interface ProjectResolver {
+    listVisibleProjects(options: ResolveBlueprintProjectsOptions): Promise<readonly BlueprintProjectRef[]>;
+    resolve(target: ResolveProjectTarget): Promise<ResolveProjectResult>;
+    warm(projects: readonly BlueprintProjectRef[]): void;
+    invalidate(): void;
+}
+interface CreateProjectResolverOptions {
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+    readonly resolveProjects?: (options: ResolveBlueprintProjectsOptions) => Promise<readonly BlueprintProjectRef[]>;
+}
+export declare function createProjectResolver(options?: CreateProjectResolverOptions): ProjectResolver;
+export {};
+//# sourceMappingURL=project-resolver.d.ts.map

package/dist/esm/blueprint/project-resolver.js

@@ -0,0 +1,142 @@
+import { realpathSync } from 'node:fs';
+import { PROJECT_SOURCES, resolveBlueprintProjects, } from '#projects.js';
+const DEFAULT_PROJECT_RESOLUTION_CACHE_TTL_MS = 15_000;
+export function createProjectResolver(options = {}) {
+    const now = options.now ?? Date.now;
+    const ttlMs = options.ttlMs ?? DEFAULT_PROJECT_RESOLUTION_CACHE_TTL_MS;
+    const resolveProjects = options.resolveProjects ?? resolveBlueprintProjects;
+    const recentProjectIndex = new Map();
+    function evictExpired(key, at) {
+        if (now() - at > ttlMs) {
+            recentProjectIndex.delete(key);
+        }
+    }
+    function readRecentProjectMatch(projectId, resolvedPath) {
+        const keys = [projectId];
+        if (resolvedPath !== null)
+            keys.push(resolvedPath);
+        for (const key of keys) {
+            const cached = recentProjectIndex.get(key);
+            if (!cached)
+                continue;
+            if (now() - cached.at > ttlMs) {
+                recentProjectIndex.delete(key);
+                continue;
+            }
+            return cached.project;
+        }
+        return null;
+    }
+    function warm(projects) {
+        const at = now();
+        for (const project of projects) {
+            recentProjectIndex.set(project.project_id, { at, project });
+            recentProjectIndex.set(project.worktree_path, { at, project });
+            recentProjectIndex.set(project.repo_path, { at, project });
+        }
+    }
+    async function listVisibleProjects(discovery) {
+        const projects = await resolveProjects(discovery);
+        warm(projects);
+        return projects;
+    }
+    async function resolve(target) {
+        const { cwd, projectId } = target;
+        if (projectId !== undefined) {
+            const resolvedPath = (() => {
+                try {
+                    return realpathSync(projectId);
+                }
+                catch {
+                    return null;
+                }
+            })();
+            const cachedMatch = readRecentProjectMatch(projectId, resolvedPath);
+            if (cachedMatch) {
+                return { ok: true, cwd: cachedMatch.worktree_path, project_id: cachedMatch.project_id };
+            }
+            if (resolvedPath !== null) {
+                return { ok: true, cwd: resolvedPath, project_id: null };
+            }
+            const projects = await listVisibleProjects({ cwd, ...target.discovery });
+            const match = projects.find((project) => project.project_id === projectId ||
+                project.worktree_path === projectId ||
+                project.repo_path === projectId) ?? null;
+            if (match) {
+                return { ok: true, cwd: match.worktree_path, project_id: match.project_id };
+            }
+            return {
+                ok: false,
+                reason: 'not_found',
+                summary: `Project "${projectId}" not found`,
+                hint: 'Call wp_blueprint_projects to pick an explicit project_id or pass a valid project path.',
+                candidates: projects,
+            };
+        }
+        const projects = await listVisibleProjects({ cwd, ...target.discovery });
+        const current = projects.find((project) => project.source === PROJECT_SOURCES.current) ?? null;
+        if (current) {
+            return { ok: true, cwd: current.worktree_path, project_id: current.project_id };
+        }
+        const currentScopeProjects = projects.filter((project) => project.source === PROJECT_SOURCES.recursive_scan);
+        if (currentScopeProjects.length === 1) {
+            const onlyProject = currentScopeProjects[0];
+            if (!onlyProject) {
+                return {
+                    ok: false,
+                    reason: 'not_found',
+                    summary: 'Recursive current project selection was empty',
+                    hint: 'No blueprint project could be resolved from the current working directory.',
+                    candidates: [],
+                };
+            }
+            return { ok: true, cwd: onlyProject.worktree_path, project_id: onlyProject.project_id };
+        }
+        if (currentScopeProjects.length > 1) {
+            return {
+                ok: false,
+                reason: 'ambiguous',
+                summary: 'Multiple blueprint projects found under the current working directory',
+                hint: 'Call wp_blueprint_projects and pass an explicit project_id to the blueprint tool you want to run.',
+                candidates: currentScopeProjects,
+            };
+        }
+        if (projects.length === 1) {
+            const onlyProject = projects[0];
+            if (!onlyProject) {
+                return {
+                    ok: false,
+                    reason: 'not_found',
+                    summary: 'Single project selection was empty',
+                    hint: 'No blueprint project could be resolved from the current working directory.',
+                    candidates: [],
+                };
+            }
+            return { ok: true, cwd: onlyProject.worktree_path, project_id: onlyProject.project_id };
+        }
+        if (projects.length > 1) {
+            return {
+                ok: false,
+                reason: 'ambiguous',
+                summary: 'Multiple blueprint projects are visible from the current workspace',
+                hint: 'Call wp_blueprint_projects and pass an explicit project_id to disambiguate.',
+                candidates: projects,
+            };
+        }
+        return { ok: true, cwd, project_id: null };
+    }
+    function invalidate() {
+        for (const [key, value] of recentProjectIndex.entries()) {
+            evictExpired(key, value.at);
+        }
+        if (recentProjectIndex.size > 0)
+            recentProjectIndex.clear();
+    }
+    return {
+        listVisibleProjects,
+        resolve,
+        warm,
+        invalidate,
+    };
+}
+//# sourceMappingURL=project-resolver.js.map

package/dist/esm/blueprint/projection-ready.d.ts

@@ -0,0 +1,3 @@
+export declare function reIngestProjection(cwd: string): Promise<void>;
+export declare function ensureProjectionReady(cwd: string): Promise<void>;
+//# sourceMappingURL=projection-ready.d.ts.map

package/dist/esm/blueprint/projection-ready.js

@@ -0,0 +1,29 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { coldStartIfNeeded } from '#db/cold-start.js';
+import { openDb } from '#db/connection.js';
+import { ingestAll } from '#db/ingester.js';
+import { resolveBlueprintProjectionDbPath, withProjectionDbWriteLock } from '#db/paths.js';
+import { recordProjectionMetadata } from './freshness.js';
+export async function reIngestProjection(cwd) {
+    const target = resolveBlueprintProjectionDbPath(cwd);
+    await withProjectionDbWriteLock(cwd, async () => {
+        mkdirSync(path.dirname(target), { recursive: true });
+        const conn = openDb(target);
+        try {
+            await ingestAll({ db: conn.db, cwd });
+            recordProjectionMetadata({
+                dbPath: target,
+                cwd,
+                ingestedAt: Date.now(),
+            });
+        }
+        finally {
+            conn.close();
+        }
+    });
+}
+export async function ensureProjectionReady(cwd) {
+    await coldStartIfNeeded(cwd);
+}
+//# sourceMappingURL=projection-ready.js.map

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

@@ -0,0 +1,96 @@
+/**
+ * Project / worktree discovery for the structured-blueprint MCP surface.
+ *
+ * Owns one reusable, lazy, injectable resolver that returns
+ * `BlueprintProjectRef[]` aggregated across five sources, in priority order:
+ *
+ *   1. Current project (`cwd`, `CLAUDE_PROJECT_DIR`, upward marker walk via
+ *      the shared `resolveProjectRoot`).
+ *   2. MCP client roots via `Server.listRoots()` — gracefully handles the
+ *      `assertClientCapability` throw when the client did not advertise the
+ *      roots capability.
+ *   3. Static workspace config from `~/.agent/workspace.yaml` (read via the
+ *      existing `getWorkspaceRepos` helper).
+ *   4. Git worktrees parsed by the already-exported `parseWorktreePorcelain`
+ *      from `#cli/commands/worktree/router-dispatch.ts` (do NOT duplicate).
+ *   5. Bounded recursive scan (only when explicit roots are supplied) capped
+ *      at `depth ≤ 3`, `count ≤ 200`, `timeoutMs 2000`, ignoring well-known
+ *      build/cache directories and dotfiles other than `.agent`.
+ *
+ * No persistent registry, daemon, or background indexer. All filesystem and
+ * git access is funnelled through an injectable `GitProbe` so tests run with
+ * deterministic stubs and never spawn real git.
+ *
+ * **`project_id_v1` spec (F14):**
+ *   `project_id = sha256(realpath(worktree) + '\0' + (repo_common_dir ?? '') + '\0' + os.platform()).hex().slice(0, 16)`
+ *
+ * - `realpath` may case-fold on macOS APFS — accepted and documented.
+ * - Moving a worktree changes the id (by design).
+ * - Recreating a worktree at the same path reuses the id — clients must use
+ *   `branch` + HEAD commit as the freshness signal.
+ */
+export { parseWorktreePorcelain } from '#cli/commands/worktree/router-dispatch';
+export declare const PROJECT_SOURCES: {
+    readonly current: "current";
+    readonly mcp_roots: "mcp_roots";
+    readonly workspace_config: "workspace_config";
+    readonly git_worktree: "git_worktree";
+    readonly recursive_scan: "recursive_scan";
+};
+export type ProjectSource = (typeof PROJECT_SOURCES)[keyof typeof PROJECT_SOURCES];
+export interface BlueprintProjectRef {
+    readonly project_id: string;
+    readonly label: string;
+    readonly repo_path: string;
+    readonly worktree_path: string;
+    readonly repo_key?: string;
+    readonly worktree_key?: string;
+    readonly source: ProjectSource;
+    readonly branch?: string;
+    readonly has_blueprints: boolean;
+    readonly db_path: string;
+    readonly stale?: boolean;
+}
+export interface RootsResponse {
+    readonly roots: ReadonlyArray<{
+        readonly uri: string;
+        readonly name?: string;
+    }>;
+}
+export type RootsProvider = () => Promise<RootsResponse>;
+export interface GitProbe {
+    isGitRepo: (cwd: string) => boolean;
+    repoToplevel: (cwd: string) => string | null;
+    repoCommonDir: (cwd: string) => string | null;
+    listWorktreesPorcelain: (cwd: string) => string;
+    headBranch: (cwd: string) => string | null;
+    platform: () => NodeJS.Platform;
+}
+export interface RecursiveScanLimits {
+    readonly depth: number;
+    readonly count: number;
+    readonly timeoutMs: number;
+}
+export declare const RECURSIVE_SCAN_LIMITS: RecursiveScanLimits;
+export declare const GIT_DISCOVERY_TIMEOUT_MS = 100;
+export declare const RECURSIVE_SCAN_IGNORED_DIRS: ReadonlySet<string>;
+export interface ResolveBlueprintProjectsOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly rootsProvider?: RootsProvider;
+    readonly workspaceRepos?: ReadonlyArray<string>;
+    readonly recursiveScanRoots?: ReadonlyArray<string>;
+    readonly caps?: RecursiveScanLimits;
+    readonly git?: GitProbe;
+    readonly now?: () => number;
+}
+/**
+ * Pinned `project_id_v1` formula.
+ *
+ * Inputs are taken at the `realpath` boundary by the caller, not inside the
+ * hasher; that keeps the hash a pure function of its arguments and lets tests
+ * exercise platform-folding behavior without touching the filesystem.
+ */
+export declare function projectIdV1(worktreePath: string, repoCommonDir: string | undefined, platformValue: NodeJS.Platform): string;
+export declare function resolveBlueprintProjects(options?: ResolveBlueprintProjectsOptions): Promise<BlueprintProjectRef[]>;
+//# sourceMappingURL=projects.d.ts.map