@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/db/parser/blueprint-db-parser.js

@@ -0,0 +1,408 @@
+/**
+ * Blueprint DB Parser
+ *
+ * Extracts structured data from blueprint `_overview.md` files for DB projection.
+ * This is SEPARATE from `src/blueprint/core/parser.ts` which serves the CLI/runtime layer.
+ *
+ * Design: fault-tolerant — malformed YAML or missing sections log to stderr and return
+ * partial data rather than throwing. Callers should check required fields before ingesting.
+ */
+import crypto from 'node:crypto';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import matter from 'gray-matter';
+// ---------------------------------------------------------------------------
+// Gstack-recognized skill names — treated as plain text, no validation needed.
+// These appear in acceptance criteria lines and must parse cleanly.
+// ---------------------------------------------------------------------------
+const _GSTACK_SKILL_PATTERN = /\/(?:qa|design-review|investigate|review|ship|browse|autoplan|plan-eng-review|plan-ceo-review|plan-design-review|design-consultation|canary|land-and-deploy|retro|codex|cso|devex-review|plan-devex-review|careful|freeze|guard|unfreeze|gstack-upgrade|learn|document-release|design-shotgun|design-html|context-save|context-restore)/g;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function safeString(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString().split('T')[0] ?? null;
+    const str = String(value).trim();
+    return str.length > 0 ? str : null;
+}
+function safeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string' && v.trim().length > 0);
+}
+/** Detect org from git remote URL in the directory containing filePath. */
+function detectOrganization(filePath) {
+    try {
+        const dir = path.dirname(filePath);
+        const remote = execSync('git remote get-url origin', {
+            cwd: dir,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        // Handles both SSH (git@github.com:org/repo.git) and HTTPS (https://github.com/org/repo.git)
+        const match = remote.match(/[:/]([^/]+)\/[^/]+(?:\.git)?$/);
+        if (match?.[1])
+            return match[1];
+    }
+    catch {
+        // Silently fall through — not all environments have git remotes
+    }
+    return 'unknown';
+}
+/** Determine visibility from frontmatter or filepath convention. Defaults to private. */
+function detectVisibility(frontmatter, filePath) {
+    const fm = frontmatter;
+    if (typeof fm['visibility'] === 'string') {
+        return fm['visibility'] === 'public' ? 'public' : 'private';
+    }
+    // If the file lives under a path segment named 'public', treat as public
+    if (filePath.includes('/public/'))
+        return 'public';
+    return 'private';
+}
+/** Parse cross_repo_depends_on array from frontmatter. */
+function parseCrossRepoDeps(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        if (typeof item === 'string') {
+            result.push({ repo: item, slug: null, requireStatus: null });
+        }
+        else if (item !== null && typeof item === 'object') {
+            const obj = item;
+            result.push({
+                repo: typeof obj['repo'] === 'string' ? obj['repo'] : String(obj['repo'] ?? ''),
+                slug: typeof obj['slug'] === 'string' ? obj['slug'] : null,
+                requireStatus: typeof obj['require_status'] === 'string' ? obj['require_status'] : null,
+            });
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Task parsing
+// ---------------------------------------------------------------------------
+/** Map raw status text to the canonical DB enum. */
+function normalizeTaskStatus(raw) {
+    const lower = raw.toLowerCase().trim();
+    if (lower === 'done')
+        return 'done';
+    if (lower === 'in-progress' || lower === 'in_progress')
+        return 'in-progress';
+    if (lower === 'blocked')
+        return 'blocked';
+    if (lower === 'dropped')
+        return 'dropped';
+    return 'todo';
+}
+/** Derive task status from checkbox coverage when no explicit **Status:** line exists. */
+function deriveStatusFromCheckboxes(body) {
+    const checkboxes = Array.from(body.matchAll(/^- \[([ x])\]/gm));
+    if (checkboxes.length === 0)
+        return 'todo';
+    const checked = checkboxes.filter((m) => m[1] === 'x').length;
+    if (checked === checkboxes.length)
+        return 'done';
+    if (checked > 0)
+        return 'in-progress';
+    return 'todo';
+}
+/** Extract acceptance criteria lines (- [ ] and - [x]) from a task body.
+ *  Gstack skill names in these lines are treated as plain text — no warning emitted. */
+function extractAcceptanceCriteria(body) {
+    const lines = [];
+    for (const line of body.split('\n')) {
+        if (/^- \[[ x]\]/.test(line)) {
+            // Strip the gstack skill tokens so they pass through without any external validation.
+            // We intentionally keep the full original line — the regex match just confirms it's a
+            // valid checklist item; the gstack skill names are plain text and need no processing.
+            lines.push(line.trim());
+        }
+    }
+    return lines;
+}
+/** Extract "**Depends:** Task X.Y, Task A.B" → ['X.Y', 'A.B'] */
+function extractDependsOnTaskIds(body) {
+    const match = body.match(/\*\*Depends:\*\*\s*(.+)/i);
+    if (!match?.[1])
+        return [];
+    const text = match[1].trim();
+    if (text.toLowerCase() === 'none')
+        return [];
+    return Array.from(text.matchAll(/(?:Tasks?\s+)?(\d+(?:\.\d+)+)/gi), (m) => m[1] ?? '').filter((id) => id !== '');
+}
+/** Parse file entries from a task body. Supports:
+ *  - `create src/foo.ts` / `modify src/foo.ts` / `delete src/foo.ts`
+ *  - bare file paths inferred as 'modify'
+ */
+function extractTaskFiles(body) {
+    const results = [];
+    const opPattern = /^[-*]\s+(create|modify|delete)\s+([^\s]+\.[a-z]{1,5})/gim;
+    for (const m of body.matchAll(opPattern)) {
+        results.push({
+            op: (m[1]?.toLowerCase() ?? 'modify'),
+            filePath: m[2] ?? '',
+        });
+    }
+    return results;
+}
+/** Extract description text: lines after the task header that are not metadata/checkboxes. */
+function extractTaskDescription(body) {
+    const lines = body.split('\n');
+    const descLines = [];
+    let pastHeader = false;
+    for (const line of lines) {
+        // Skip the task header line itself
+        if (/^####\s+.*Task\s+\d/.test(line)) {
+            pastHeader = true;
+            continue;
+        }
+        if (!pastHeader)
+            continue;
+        // Skip metadata lines
+        if (/^\*\*(Status|Depends|Blocked|Wave):\*\*/i.test(line))
+            continue;
+        // Skip checkbox lines
+        if (/^- \[[ x]\]/.test(line))
+            continue;
+        // Skip sub-section headers
+        if (/^#{2,5}\s/.test(line))
+            continue;
+        // Collect up to first blank line after non-blank content
+        if (line.trim() === '') {
+            if (descLines.length > 0)
+                break;
+            continue;
+        }
+        descLines.push(line.trim());
+    }
+    const desc = descLines.join(' ').trim();
+    return desc.length > 0 ? desc : null;
+}
+/** Parse the wave tag from the task header, e.g. `[Wave 1]` → '1'. */
+function extractWaveFromHeader(header) {
+    const m = header.match(/\[Wave\s+(\S+)\]/i);
+    return m?.[1] ?? null;
+}
+function parseTasks(content) {
+    const taskHeaderRegex = /^(####\s+(?:\[[^\]]+\]\s+)?Task\s+(\d+(?:\.\d+)+):\s*(.+))$/gm;
+    const headerMatches = Array.from(content.matchAll(taskHeaderRegex));
+    return headerMatches.map((match, idx) => {
+        const taskId = match[2] ?? '';
+        const title = (match[3] ?? '').trim();
+        const headerLine = match[1] ?? '';
+        const wave = extractWaveFromHeader(headerLine);
+        const bodyStart = (match.index ?? 0) + headerLine.length;
+        const bodyEnd = headerMatches[idx + 1]?.index ?? content.length;
+        const body = content.slice(bodyStart, bodyEnd);
+        const explicitStatusMatch = body.match(/\*\*Status:\*\*\s*(.+)/i);
+        const status = explicitStatusMatch?.[1]
+            ? normalizeTaskStatus(explicitStatusMatch[1])
+            : deriveStatusFromCheckboxes(body);
+        return {
+            taskId,
+            wave,
+            title,
+            status,
+            description: extractTaskDescription(match[0] + body),
+            acceptanceCriteria: extractAcceptanceCriteria(body),
+            dependsOnTaskIds: extractDependsOnTaskIds(body),
+            files: extractTaskFiles(body),
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Risks parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the Risks table. Expected format:
+ * | R1 | HIGH | description | mitigation |
+ */
+function parseRisks(content) {
+    const section = extractSection(content, 'Risks');
+    if (!section)
+        return [];
+    const rows = extractTableRows(section);
+    const risks = [];
+    for (const cells of rows) {
+        if (cells.length < 4)
+            continue;
+        const riskId = (cells[0] ?? '').trim();
+        const severityRaw = (cells[1] ?? '').trim().toUpperCase();
+        // Guard: skip header rows
+        if (riskId.toLowerCase() === '#' || riskId.toLowerCase() === 'risk')
+            continue;
+        const severity = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].includes(severityRaw)
+            ? severityRaw
+            : 'LOW';
+        risks.push({
+            riskId,
+            severity,
+            description: (cells[2] ?? '').trim(),
+            mitigation: (cells[3] ?? '').trim(),
+        });
+    }
+    return risks;
+}
+// ---------------------------------------------------------------------------
+// Edge cases parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the Edge cases/Edge Cases table. Expected format:
+ * | E1 | scenario | handling | task |
+ * The severity column is optional (some blueprints omit it).
+ */
+function parseEdgeCases(content) {
+    const section = extractSection(content, 'Edge [Cc]ases?');
+    if (!section)
+        return [];
+    const rows = extractTableRows(section);
+    const edges = [];
+    for (const cells of rows) {
+        if (cells.length < 3)
+            continue;
+        const edgeId = (cells[0] ?? '').trim();
+        // Skip header rows
+        if (edgeId.toLowerCase() === '#' || edgeId.toLowerCase() === 'edge')
+            continue;
+        // Some tables: | E1 | severity | desc | mitigation |
+        // Others:      | E1 | desc | handling | task |
+        // Heuristic: if cell[1] looks like a severity keyword, use 4-col layout
+        const col1 = (cells[1] ?? '').trim().toLowerCase();
+        const isSeverityCol = col1 === 'critical' || col1 === 'high' || col1 === 'medium' || col1 === 'low';
+        if (isSeverityCol && cells.length >= 4) {
+            edges.push({
+                edgeId,
+                severity: (cells[1] ?? '').trim().toUpperCase(),
+                description: (cells[2] ?? '').trim(),
+                mitigation: (cells[3] ?? '').trim(),
+            });
+        }
+        else {
+            edges.push({
+                edgeId,
+                severity: 'UNKNOWN',
+                description: (cells[1] ?? '').trim(),
+                mitigation: (cells[2] ?? '').trim(),
+            });
+        }
+    }
+    return edges;
+}
+// ---------------------------------------------------------------------------
+// Shared table / section utilities
+// ---------------------------------------------------------------------------
+/** Extract the text under a named ## section up to the next ## heading. */
+function extractSection(content, headingPattern) {
+    const regex = new RegExp(`^## ${headingPattern}\\s*$`, 'im');
+    const match = content.match(regex);
+    if (!match || match.index === undefined)
+        return null;
+    const start = match.index + match[0].length;
+    const rest = content.slice(start);
+    const nextHeading = rest.search(/^## /m);
+    return nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+}
+/** Parse all data rows from a markdown table block (skip separator rows). */
+function extractTableRows(block) {
+    const rows = [];
+    for (const line of block.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        // Skip separator rows like | --- | --- |
+        if (/^\|[-| :]+\|$/.test(trimmed))
+            continue;
+        const cells = trimmed
+            .split('|')
+            .slice(1, -1)
+            .map((c) => c.trim());
+        if (cells.length > 0)
+            rows.push(cells);
+    }
+    return rows;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse a blueprint `_overview.md` for DB projection.
+ *
+ * Fault-tolerant: malformed YAML or missing sections log to stderr and return
+ * partial data; this function never throws.
+ */
+export function parseBlueprintForDb(content, filePath, slug) {
+    const byteSize = Buffer.byteLength(content, 'utf8');
+    const contentHash = crypto.createHash('sha256').update(content).digest('hex');
+    let frontmatter = {};
+    let bodyContent = content;
+    try {
+        const parsed = matter(content);
+        frontmatter = parsed.data;
+        bodyContent = parsed.content;
+    }
+    catch (err) {
+        process.stderr.write(`[blueprint-db-parser] Failed to parse frontmatter in ${filePath}: ${String(err)}\n`);
+    }
+    // Extract title from first # heading in body, fall back to frontmatter, then slug
+    const titleMatch = bodyContent.match(/^# (.+)$/m);
+    const title = safeString(frontmatter['title']) ?? titleMatch?.[1]?.trim() ?? slug;
+    const status = safeString(frontmatter['status']) ?? 'draft';
+    const complexity = safeString(frontmatter['complexity']);
+    const owner = safeString(frontmatter['owner']);
+    const created = safeString(frontmatter['created']);
+    const lastUpdated = safeString(frontmatter['last_updated']);
+    const completedAt = safeString(frontmatter['completed_at']);
+    const tags = safeStringArray(frontmatter['tags']);
+    const dependsOn = safeStringArray(frontmatter['depends_on']);
+    const crossRepoDependsOn = parseCrossRepoDeps(frontmatter['cross_repo_depends_on']);
+    const organization = detectOrganization(filePath);
+    const visibility = detectVisibility(frontmatter, filePath);
+    let tasks = [];
+    let risks = [];
+    let edgeCases = [];
+    try {
+        tasks = parseTasks(bodyContent);
+    }
+    catch (err) {
+        process.stderr.write(`[blueprint-db-parser] Failed to parse tasks in ${filePath}: ${String(err)}\n`);
+    }
+    try {
+        risks = parseRisks(bodyContent);
+    }
+    catch (err) {
+        process.stderr.write(`[blueprint-db-parser] Failed to parse risks in ${filePath}: ${String(err)}\n`);
+    }
+    try {
+        edgeCases = parseEdgeCases(bodyContent);
+    }
+    catch (err) {
+        process.stderr.write(`[blueprint-db-parser] Failed to parse edge cases in ${filePath}: ${String(err)}\n`);
+    }
+    return {
+        slug,
+        filePath,
+        title,
+        status,
+        complexity,
+        owner,
+        created,
+        lastUpdated,
+        completedAt,
+        tags,
+        dependsOn,
+        crossRepoDependsOn,
+        organization,
+        visibility,
+        tasks,
+        risks,
+        edgeCases,
+        byteSize,
+        contentHash,
+    };
+}
+//# sourceMappingURL=blueprint-db-parser.js.map

package/dist/esm/blueprint/db/parser/tech-debt-db-parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tech-Debt DB Parser
+ *
+ * Extracts structured data from tech-debt `h-NNN-<slug>.md` files for DB projection.
+ * Reuses the existing `techDebtFrontmatterSchema` for validation.
+ *
+ * Fault-tolerant: malformed YAML logs to stderr and returns partial data; never throws.
+ */
+export interface ParsedTechDebtForDb {
+    slug: string;
+    filePath: string;
+    status: string;
+    severity: string;
+    category: string;
+    reviewCadence: string;
+    lastReviewed: string | null;
+    created: string | null;
+    nextReview: string | null;
+    basePriority: number | null;
+    linkedBlueprints: string[];
+    autoFiledHash: string | null;
+    organization: string;
+    visibility: 'public' | 'private';
+    byteSize: number;
+    contentHash: string;
+}
+/**
+ * Parse a tech-debt `h-NNN-<slug>.md` file for DB projection.
+ *
+ * Fault-tolerant: invalid frontmatter logs to stderr and returns partial data.
+ */
+export declare function parseTechDebtForDb(content: string, filePath: string, slug: string): ParsedTechDebtForDb;
+//# sourceMappingURL=tech-debt-db-parser.d.ts.map

package/dist/esm/blueprint/db/parser/tech-debt-db-parser.js

@@ -0,0 +1,134 @@
+/**
+ * Tech-Debt DB Parser
+ *
+ * Extracts structured data from tech-debt `h-NNN-<slug>.md` files for DB projection.
+ * Reuses the existing `techDebtFrontmatterSchema` for validation.
+ *
+ * Fault-tolerant: malformed YAML logs to stderr and returns partial data; never throws.
+ */
+import crypto from 'node:crypto';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { techDebtFrontmatterSchema } from '#tech-debt/schema';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function safeString(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString().split('T')[0] ?? null;
+    const str = String(value).trim();
+    return str.length > 0 ? str : null;
+}
+/** Detect org from git remote URL in the directory containing filePath. */
+function detectOrganization(filePath) {
+    try {
+        const dir = path.dirname(filePath);
+        const remote = execSync('git remote get-url origin', {
+            cwd: dir,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        const match = remote.match(/[:/]([^/]+)\/[^/]+(?:\.git)?$/);
+        if (match?.[1])
+            return match[1];
+    }
+    catch {
+        // No remote or git not available — silently return unknown
+    }
+    return 'unknown';
+}
+/** Detect visibility from frontmatter or path convention. Defaults to private. */
+function detectVisibility(frontmatter, filePath) {
+    if (typeof frontmatter['visibility'] === 'string') {
+        return frontmatter['visibility'] === 'public' ? 'public' : 'private';
+    }
+    if (filePath.includes('/public/'))
+        return 'public';
+    return 'private';
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse a tech-debt `h-NNN-<slug>.md` file for DB projection.
+ *
+ * Fault-tolerant: invalid frontmatter logs to stderr and returns partial data.
+ */
+export function parseTechDebtForDb(content, filePath, slug) {
+    const byteSize = Buffer.byteLength(content, 'utf8');
+    const contentHash = crypto.createHash('sha256').update(content).digest('hex');
+    const organization = detectOrganization(filePath);
+    const visibility = detectVisibility({}, filePath);
+    // Baseline: defaults for all fields in case frontmatter is absent/broken
+    let status = 'accepted';
+    let severity = 'low';
+    let category = 'complexity';
+    let reviewCadence = 'monthly';
+    let lastReviewed = null;
+    let created = null;
+    let nextReview = null;
+    let basePriority = null;
+    let linkedBlueprints = [];
+    let autoFiledHash = null;
+    let rawFrontmatter = {};
+    try {
+        const parsed = matter(content);
+        rawFrontmatter = parsed.data;
+    }
+    catch (err) {
+        process.stderr.write(`[tech-debt-db-parser] Failed to parse frontmatter in ${filePath}: ${String(err)}\n`);
+    }
+    // Run the canonical schema through safeParse so we get computed fields (nextReview, basePriority)
+    const schemaResult = techDebtFrontmatterSchema.safeParse(rawFrontmatter);
+    if (schemaResult.success) {
+        const d = schemaResult.data;
+        status = d.status;
+        severity = d.severity;
+        category = d.category;
+        reviewCadence = d.review_cadence;
+        lastReviewed = safeString(d.last_reviewed);
+        created = safeString(d.created ?? null);
+        nextReview = d.nextReview;
+        basePriority = d.basePriority;
+        linkedBlueprints = d.linked_blueprints;
+        autoFiledHash = d.auto_filed_hash ?? null;
+    }
+    else {
+        // Schema validation failed — fall back to raw field extraction so the DB
+        // still gets as much data as possible without throwing.
+        process.stderr.write(`[tech-debt-db-parser] Schema validation failed for ${filePath}: ${JSON.stringify(schemaResult.error.issues.map((i) => i.message))}\n`);
+        status = safeString(rawFrontmatter['status']) ?? status;
+        severity = safeString(rawFrontmatter['severity']) ?? severity;
+        category = safeString(rawFrontmatter['category']) ?? category;
+        reviewCadence = safeString(rawFrontmatter['review_cadence']) ?? reviewCadence;
+        lastReviewed = safeString(rawFrontmatter['last_reviewed']);
+        created = safeString(rawFrontmatter['created']);
+        linkedBlueprints = Array.isArray(rawFrontmatter['linked_blueprints'])
+            ? rawFrontmatter['linked_blueprints'].filter((v) => typeof v === 'string')
+            : [];
+        autoFiledHash = safeString(rawFrontmatter['auto_filed_hash']);
+    }
+    return {
+        slug,
+        filePath,
+        status,
+        severity,
+        category,
+        reviewCadence,
+        lastReviewed,
+        created,
+        nextReview,
+        basePriority,
+        linkedBlueprints,
+        autoFiledHash,
+        organization,
+        visibility,
+        byteSize,
+        contentHash,
+    };
+}
+//# sourceMappingURL=tech-debt-db-parser.js.map

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

@@ -0,0 +1,104 @@
+/**
+ * Centralized blueprint projection-DB path policy.
+ *
+ * Single source of truth for where the SQLite projection of blueprint markdown
+ * lives, plus the two lock files that gate writes to that projection and to
+ * the underlying markdown directory.
+ *
+ * ## Lock-scope decision (F9 / R7, Task 1.1)
+ *
+ * We adopt the **two-lock** policy:
+ *
+ * 1. **Projection DB lock — `'worktree'` scope.**
+ *    The SQLite file at `getSurfacePath('blueprints/blueprints.db', 'worktree', cwd)`
+ *    is a per-worktree derived artifact. Concurrent writers in the **same**
+ *    worktree (cold-start + mutation re-ingest, two ingest paths, etc.) must
+ *    serialize against the projection. Cross-worktree writers target distinct
+ *    DB files, so they do not need this lock.
+ *
+ * 2. **Markdown-mutation lock — `'repo'` scope.**
+ *    The `blueprints/` markdown directory is git-tracked and shared across
+ *    all worktrees of the same repository. Cross-worktree concurrent writers
+ *    that mutate markdown (`advanceTask`, `promoteBlueprint`, `finalizeBlueprint`)
+ *    must serialize against each other. This lock guards the directory, not
+ *    the DB.
+ *
+ * ## Silent advisory escape removed
+ *
+ * The legacy `acquireLock` helper in `cold-start.ts` waited up to 5 s and then
+ * "proceeded anyway" if it could not acquire. That escape is removed on write
+ * paths — write callers must use the typed lock helpers in this module, which
+ * raise `LockTimeoutError` on failure. Read-only paths may proceed without a
+ * lock (they take a consistent SQLite snapshot regardless).
+ *
+ * ## Legacy fallback
+ *
+ * Non-git temp repos (most tests, ad-hoc directories) cannot resolve a repo
+ * key. For those we keep the historical `<cwd>/.agent/.blueprints.db` layout
+ * so existing fixtures and bootstrap flows continue to work.
+ *
+ * For git repos that still carry a stray `.agent/.blueprints.db` from a
+ * previous webpresso version, see `legacy-migration.ts`.
+ */
+export declare const LEGACY_AGENT_DIR = ".agent";
+export declare const LEGACY_DB_FILENAME = ".blueprints.db";
+export declare const LEGACY_LOCK_FILENAME = ".blueprints.lock";
+export declare class LockTimeoutError extends Error {
+    readonly lockPath: string;
+    readonly nextAction: 'reingest_project';
+    constructor(lockPath: string, cause?: unknown);
+}
+/**
+ * Resolve the worktree-scoped projection DB path.
+ *
+ * In a git repo: `<state-root>/<repoKey>/worktree/<wtKey>/blueprints/blueprints.db`.
+ * Outside a git repo: legacy `<cwd>/.agent/.blueprints.db` (no isolation).
+ */
+export declare function resolveBlueprintProjectionDbPath(cwd: string): string;
+/**
+ * Resolve the worktree-scoped lock file for the projection DB.
+ *
+ * Lives next to the DB so a single `mkdir -p` covers both. Cross-worktree
+ * writers do not contend on this lock; see `resolveBlueprintMarkdownLockPath`
+ * for the cross-worktree case.
+ */
+export declare function resolveBlueprintProjectionDbLockPath(cwd: string): string;
+/**
+ * Resolve the repo-scoped lock file for markdown mutations.
+ *
+ * Two worktrees of one repo share the same markdown directory under git, so
+ * mutations against `_overview.md` must serialize across worktrees.
+ */
+export declare function resolveBlueprintMarkdownLockPath(cwd: string): string;
+export interface AcquireLockOptions {
+    /** Lock-acquisition timeout. Default 5000ms. */
+    readonly timeoutMs?: number;
+    /** Stale-lock window (proper-lockfile recovers if holder died). Default 30000ms. */
+    readonly staleMs?: number;
+}
+/**
+ * Acquire the worktree-scoped projection-DB write lock.
+ *
+ * Throws `LockTimeoutError` on failure — there is no silent "proceeds anyway"
+ * escape. Read-only callers should not use this helper.
+ */
+export declare function acquireProjectionDbWriteLock(cwd: string, opts?: AcquireLockOptions): Promise<() => Promise<void>>;
+/**
+ * Acquire the repo-scoped markdown-mutation write lock.
+ *
+ * Two worktrees of one repo share `blueprints/` under git, so cross-worktree
+ * mutations must serialize here. Throws `LockTimeoutError` on failure.
+ */
+export declare function acquireMarkdownWriteLock(cwd: string, opts?: AcquireLockOptions): Promise<() => Promise<void>>;
+/**
+ * Run `fn` while holding the projection-DB write lock. Lock is released even
+ * if `fn` throws. See `acquireProjectionDbWriteLock` for the no-silent-escape
+ * guarantee.
+ */
+export declare function withProjectionDbWriteLock<T>(cwd: string, fn: () => Promise<T> | T, opts?: AcquireLockOptions): Promise<T>;
+/**
+ * Run `fn` while holding the markdown-mutation write lock. Lock is released
+ * even if `fn` throws.
+ */
+export declare function withMarkdownWriteLock<T>(cwd: string, fn: () => Promise<T> | T, opts?: AcquireLockOptions): Promise<T>;
+//# sourceMappingURL=paths.d.ts.map