@planu/cli 5.5.3 → 5.7.0

package/dist/hosts/claude-code/ux/mcp-resources.js

@@ -4,6 +4,8 @@
 import { readFile } from 'node:fs/promises';
 import { glob } from 'glob';
 import { resolveStorageLayout } from '../../../storage/storage-layout.js';
+import { loadSpecIndex, listSpecIndexRecords } from '../../../storage/spec-index.js';
+import { resolveCurrentProjectPath } from '../../../storage/current-project.js';
 import { join } from 'node:path';
 /** Planu-namespaced resource URIs exposed by SPEC-588. */
 export const PLANU_UX_RESOURCE_URIS = {
@@ -56,30 +58,12 @@ function safeStr(value) {
     return typeof value === 'string' ? value : '';
 }
 async function loadAllSpecEntries() {
-    const specs = [];
-    try {
-        const files = await glob(join(resolveStorageLayout().projects, '*', 'specs.json'));
-        for (const file of files) {
-            try {
-                const raw = await readFile(file, 'utf-8');
-                const parsed = JSON.parse(raw);
-                if (Array.isArray(parsed)) {
-                    for (const entry of parsed) {
-                        if (entry !== null && typeof entry === 'object' && 'id' in entry) {
-                            specs.push(toSpecDataEntry(entry));
-                        }
-                    }
-                }
-            }
-            catch {
-                // skip malformed files
-            }
-        }
-    }
-    catch {
-        // data/ not present yet
+    const projectPath = await resolveCurrentProjectPath();
+    if (!projectPath) {
+        return [];
     }
-    return specs;
+    const index = await loadSpecIndex(projectPath);
+    return listSpecIndexRecords(index).map((record) => toSpecDataEntry(record));
 }
 async function buildSpecListContent() {
     const all = await loadAllSpecEntries();

package/dist/index.js

@@ -84,6 +84,27 @@ function scheduleStartupStateRecovery(startupSync, recoverPendingPostCommitTasks
         recoverValidateJobsAtStartup();
     });
 }
+const MCP_HOST_MARKERS = [
+    ['claude-code', 'claude-code'],
+    ['claude-code', 'claude code'],
+    ['claude-desktop', 'claude-desktop'],
+    ['claude-desktop', 'claude desktop'],
+    ['cursor', 'cursor'],
+    ['codex', 'codex'],
+];
+/** Maps the MCP client's reported implementation name to the envelope's allowlisted mcpHost. */
+function resolveMcpHost(clientName) {
+    if (!clientName) {
+        return 'unknown';
+    }
+    const normalized = clientName.toLowerCase();
+    for (const [host, marker] of MCP_HOST_MARKERS) {
+        if (normalized.includes(marker)) {
+            return host;
+        }
+    }
+    return 'other';
+}
 // Loads post-handshake modules after the MCP handshake has completed.
 // Separated from main() to keep main() within the 80-line function budget.
 async function setupPostHandshake(handshakeGate, officialToolNames) {
@@ -109,6 +130,11 @@ async function setupPostHandshake(handshakeGate, officialToolNames) {
     if (clientVersion) {
         setConnectedClient(clientVersion);
     }
+    // SPEC-1704: emit the mcp_server_started envelope now that the client is known.
+    const { sendTelemetryEnvelopeEvent } = await import('./engine/telemetry/telemetry-client.js');
+    sendTelemetryEnvelopeEvent('mcp_server_started', {
+        mcpHost: resolveMcpHost(clientVersion?.name),
+    });
     // SPEC-251: Check npm registry for newer version (fire-and-forget, 24h cache)
     checkForUpdates().catch(() => {
         /* best-effort */

package/dist/resources/specs.js

@@ -1,46 +1,25 @@
 // resources/specs.ts — Current project specs list resource
-// Returns the list of specs for the current project from the data store.
-// Storage format: data/projects/{projectId}/specs.json (single array per project)
-import { readFile } from 'node:fs/promises';
-import { glob } from 'glob';
+// Returns the list of specs for the current project, read from spec.md via
+// the regenerable spec index (SPEC-1699). spec.md is the authoritative record.
 import { t } from '../i18n/index.js';
-import { resolveStorageLayout } from '../storage/storage-layout.js';
-import { join } from 'node:path';
+import { loadSpecIndex, listSpecIndexRecords } from '../storage/spec-index.js';
+import { resolveCurrentProjectPath } from '../storage/current-project.js';
 /**
- * Scan the data/projects/ directory for all specs.json files and return them.
- * Each project stores ALL specs in a single data/projects/{projectId}/specs.json as an array.
+ * Load every spec for the current project (cwd) from its spec.md files under
+ * planu/specs/. Returns an empty list when cwd is not an initialized Planu project.
  */
-async function loadAllSpecs() {
-    const specs = [];
-    try {
-        const specFiles = await glob(join(resolveStorageLayout().projects, '*', 'specs.json'));
-        for (const file of specFiles) {
-            try {
-                const raw = await readFile(file, 'utf-8');
-                const parsed = JSON.parse(raw);
-                if (Array.isArray(parsed)) {
-                    for (const entry of parsed) {
-                        if (entry !== null && typeof entry === 'object' && 'id' in entry) {
-                            specs.push(entry);
-                        }
-                    }
-                }
-            }
-            catch {
-                // Skip malformed files
-            }
-        }
+async function loadCurrentProjectSpecs() {
+    const projectPath = await resolveCurrentProjectPath();
+    if (!projectPath) {
+        return [];
     }
-    catch {
-        // No data directory yet — that is fine
-    }
-    return specs;
+    return listSpecIndexRecords(await loadSpecIndex(projectPath));
 }
 /**
  * MCP resource handler for planu://specs
  */
 export async function handleSpecsResource() {
-    const specs = await loadAllSpecs();
+    const specs = await loadCurrentProjectSpecs();
     if (specs.length === 0) {
         return JSON.stringify({
             count: 0,

package/dist/storage/current-project.d.ts

@@ -0,0 +1,3 @@
+/** Return process.cwd() when it is an initialized Planu project, else null. */
+export declare function resolveCurrentProjectPath(cwd?: string): Promise<string | null>;
+//# sourceMappingURL=current-project.d.ts.map

package/dist/storage/current-project.js

@@ -0,0 +1,21 @@
+// storage/current-project.ts — SPEC-1699
+// Resolves the current project from cwd's planu/project.json. Used by MCP
+// resources that used to scan every registered project's specs.json store;
+// they now read only the project the server is actually running in.
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+/** Return process.cwd() when it is an initialized Planu project, else null. */
+export async function resolveCurrentProjectPath(cwd = process.cwd()) {
+    try {
+        await access(join(cwd, 'planu', 'project.json'));
+        return cwd;
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.code === 'ENOENT')) {
+            reportClassifiedDegradation('CURRENT_PROJECT_PROBE_FAILED', error);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=current-project.js.map

package/dist/storage/index.d.ts

@@ -24,4 +24,5 @@ export * as actualsStore from './actuals-store.js';
 export * as approvalStore from './approval-store.js';
 export * as technologySelectionStore from './technology-selection-store.js';
 export * from './skill-registry-storage.js';
+export * from './retention.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.js

@@ -25,4 +25,5 @@ export * as actualsStore from './actuals-store.js';
 export * as approvalStore from './approval-store.js';
 export * as technologySelectionStore from './technology-selection-store.js';
 export * from './skill-registry-storage.js';
+export * from './retention.js';
 //# sourceMappingURL=index.js.map

package/dist/storage/migrations/canonical-storage.js

@@ -7,6 +7,7 @@ import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } fr
 import { acquireLock as acquireFileMutex, releaseLock as releaseFileMutex, } from '../../engine/safety/file-mutex.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { assertNoObsoleteFileLock } from '../../engine/safety/obsolete-lock-guard.js';
+import { enforceRetention } from '../retention.js';
 function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
 }
@@ -715,6 +716,10 @@ export async function migrateCanonicalStorage(input) {
         await rm(journal.backupRoot, { recursive: true, force: true });
         journal.phase = 'completed';
         await writeJournal(paths.journalPath, journal);
+        await enforceRetention({
+            kind: 'snapshot',
+            path: join(journal.destinationRoot, 'migration-conflicts'),
+        });
         return result(resumed ? 'resumed' : 'migrated', journal, paths.journalPath, resumed, verified);
     }
     catch (error) {

package/dist/storage/retention.d.ts

@@ -0,0 +1,14 @@
+import type { EnforceRetentionInput, RetentionResult } from '../types/index.js';
+export declare const TRANSITION_LOG_MAX_BYTES: number;
+export declare const GRAPH_CACHE_MAX_BYTES: number;
+export declare const SPEC_STORE_BACKUPS_KEPT = 1;
+export declare const IDEMPOTENCY_TTL_DAYS = 30;
+export declare const SNAPSHOTS_KEPT = 10;
+export declare const ARCHIVED_CONTEXT_SUBDIR = "archived-context";
+/**
+ * Enforce the retention budget for one artifact kind. Never throws — a failure
+ * to prune is swallowed and reported as an empty result so the primary write
+ * that triggered enforcement is never affected.
+ */
+export declare function enforceRetention(input: EnforceRetentionInput): Promise<RetentionResult>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/storage/retention.js

@@ -0,0 +1,279 @@
+// storage/retention.ts — SPEC-1697: enforce per-artifact retention budgets on runtime storage.
+import { readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+function isMissingPath(error) {
+    return error instanceof Error && error.code === 'ENOENT';
+}
+export const TRANSITION_LOG_MAX_BYTES = 10 * 1024 * 1024;
+export const GRAPH_CACHE_MAX_BYTES = 100 * 1024 * 1024;
+export const SPEC_STORE_BACKUPS_KEPT = 1;
+export const IDEMPOTENCY_TTL_DAYS = 30;
+export const SNAPSHOTS_KEPT = 10;
+export const ARCHIVED_CONTEXT_SUBDIR = 'archived-context';
+const EMPTY_RESULT = { freedBytes: 0, removedPaths: [] };
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function statOrNull(path) {
+    try {
+        const info = await stat(path);
+        return { size: info.size, mtimeMs: info.mtimeMs, isDirectory: info.isDirectory() };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_STAT_FAILED', error);
+        }
+        return null;
+    }
+}
+async function listFilesRecursive(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_READDIR_FAILED', error);
+        }
+        return [];
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            return listFilesRecursive(path);
+        }
+        return entry.isFile() ? [path] : [];
+    }));
+    return nested.flat();
+}
+async function pathSize(path) {
+    const info = await statOrNull(path);
+    if (info === null) {
+        return 0;
+    }
+    if (!info.isDirectory) {
+        return info.size;
+    }
+    const files = await listFilesRecursive(path);
+    const sizes = await Promise.all(files.map((file) => statOrNull(file).then((s) => s?.size ?? 0)));
+    return sizes.reduce((sum, size) => sum + size, 0);
+}
+/**
+ * Rotate a transition log file when it has grown beyond TRANSITION_LOG_MAX_BYTES.
+ * The active file is moved aside to `${filePath}.1`; any pre-existing rotated
+ * predecessor is discarded first, so at most one predecessor is ever kept.
+ * Must be called before the caller appends its next entry to `filePath`.
+ */
+async function rotateTransitionLog(filePath) {
+    try {
+        const active = await statOrNull(filePath);
+        if (active === null || active.isDirectory || active.size <= TRANSITION_LOG_MAX_BYTES) {
+            return EMPTY_RESULT;
+        }
+        const rotatedPath = `${filePath}.1`;
+        const removedPaths = [];
+        let freedBytes = 0;
+        const rotated = await statOrNull(rotatedPath);
+        if (rotated !== null) {
+            await unlink(rotatedPath);
+            freedBytes += rotated.size;
+            removedPaths.push(rotatedPath);
+        }
+        await rename(filePath, rotatedPath);
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_LOG_ROTATION_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/**
+ * Evict least-recently-used entries under `dir` until it fits GRAPH_CACHE_MAX_BYTES.
+ * Paths in `protectedPaths` (e.g. the artifact just written) are never evicted.
+ */
+async function enforceGraphCacheBudget(dir, protectedPaths) {
+    try {
+        const files = await listFilesRecursive(dir);
+        const stats = await Promise.all(files.map(async (path) => ({ path, info: await statOrNull(path) })));
+        const entries = stats
+            .filter((entry) => entry.info !== null)
+            .map((entry) => ({ path: entry.path, size: entry.info.size, mtimeMs: entry.info.mtimeMs }));
+        let totalBytes = entries.reduce((sum, entry) => sum + entry.size, 0);
+        if (totalBytes <= GRAPH_CACHE_MAX_BYTES) {
+            return EMPTY_RESULT;
+        }
+        const protectedSet = new Set(protectedPaths);
+        const candidates = entries
+            .filter((entry) => !protectedSet.has(entry.path))
+            .sort((a, b) => a.mtimeMs - b.mtimeMs);
+        const removedPaths = [];
+        let freedBytes = 0;
+        for (const candidate of candidates) {
+            if (totalBytes <= GRAPH_CACHE_MAX_BYTES) {
+                break;
+            }
+            await unlink(candidate.path);
+            totalBytes -= candidate.size;
+            freedBytes += candidate.size;
+            removedPaths.push(candidate.path);
+        }
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_GRAPH_CACHE_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/** Keep exactly SPEC_STORE_BACKUPS_KEPT `.bak.N` siblings of `filePath`, newest first. */
+async function enforceSpecStoreBackupBudget(filePath) {
+    try {
+        const dir = dirname(filePath);
+        const base = basename(filePath);
+        const bakPattern = new RegExp(`^${escapeRegExp(base)}\\.bak\\.(\\d+)$`);
+        const entries = await readdir(dir);
+        const backups = entries
+            .map((name) => {
+            const match = bakPattern.exec(name);
+            return match ? { name, generation: Number(match[1]) } : null;
+        })
+            .filter((entry) => entry !== null)
+            .sort((a, b) => a.generation - b.generation);
+        const toRemove = backups.filter((entry) => entry.generation > SPEC_STORE_BACKUPS_KEPT);
+        const removedPaths = [];
+        let freedBytes = 0;
+        for (const entry of toRemove) {
+            const path = join(dir, entry.name);
+            const size = await pathSize(path);
+            await unlink(path);
+            freedBytes += size;
+            removedPaths.push(path);
+        }
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_SPEC_BACKUP_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/** Drop idempotency evidence records older than IDEMPOTENCY_TTL_DAYS from `dir`. */
+async function enforceIdempotencyTtl(dir) {
+    try {
+        const entries = await readdir(dir);
+        const cutoffMs = Date.now() - IDEMPOTENCY_TTL_DAYS * 24 * 60 * 60 * 1000;
+        const removedPaths = [];
+        let freedBytes = 0;
+        for (const name of entries) {
+            if (!name.endsWith('.json') || name.endsWith('.claim.json')) {
+                continue;
+            }
+            const path = join(dir, name);
+            const info = await statOrNull(path);
+            if (info === null || info.isDirectory || info.mtimeMs >= cutoffMs) {
+                continue;
+            }
+            await unlink(path);
+            freedBytes += info.size;
+            removedPaths.push(path);
+        }
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_IDEMPOTENCY_TTL_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/** Keep the SNAPSHOTS_KEPT most recent top-level entries under `dir`. */
+async function enforceSnapshotBudget(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const stats = await Promise.all(entries.map(async (entry) => {
+            const path = join(dir, entry.name);
+            const info = await statOrNull(path);
+            return info === null ? null : { path, mtimeMs: info.mtimeMs };
+        }));
+        const items = stats.filter((entry) => entry !== null);
+        if (items.length <= SNAPSHOTS_KEPT) {
+            return EMPTY_RESULT;
+        }
+        const toRemove = items.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(SNAPSHOTS_KEPT);
+        const removedPaths = [];
+        let freedBytes = 0;
+        for (const item of toRemove) {
+            freedBytes += await pathSize(item.path);
+            await rm(item.path, { recursive: true, force: true });
+            removedPaths.push(item.path);
+        }
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_SNAPSHOT_BUDGET_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/**
+ * Remove handoff packages, evidence bundles, and archived context for `specId`
+ * under `dataDir`. Never touches planu/specs/ — those live outside `dataDir`.
+ */
+async function pruneSpecArtifacts(dataDir, specId) {
+    try {
+        const targets = [
+            join(dataDir, 'handoffs', specId),
+            join(dataDir, 'handoffs', `${specId}.md`),
+            join(dataDir, ARCHIVED_CONTEXT_SUBDIR, `${specId}.json`),
+        ];
+        const removedPaths = [];
+        let freedBytes = 0;
+        for (const target of targets) {
+            const info = await statOrNull(target);
+            if (info === null) {
+                continue;
+            }
+            freedBytes += await pathSize(target);
+            await rm(target, { recursive: true, force: true });
+            removedPaths.push(target);
+        }
+        return { freedBytes, removedPaths };
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            reportClassifiedDegradation('RETENTION_SPEC_ARTIFACTS_FAILED', error);
+        }
+        return EMPTY_RESULT;
+    }
+}
+/**
+ * Enforce the retention budget for one artifact kind. Never throws — a failure
+ * to prune is swallowed and reported as an empty result so the primary write
+ * that triggered enforcement is never affected.
+ */
+export async function enforceRetention(input) {
+    const kind = input.kind;
+    switch (kind) {
+        case 'transition-log':
+            return rotateTransitionLog(input.path);
+        case 'graph-cache':
+            return enforceGraphCacheBudget(input.path, input.protectedPaths ?? []);
+        case 'spec-store-backup':
+            return enforceSpecStoreBackupBudget(input.path);
+        case 'idempotency':
+            return enforceIdempotencyTtl(input.path);
+        case 'snapshot':
+            return enforceSnapshotBudget(input.path);
+        case 'spec-artifacts':
+            return input.specId === undefined
+                ? EMPTY_RESULT
+                : pruneSpecArtifacts(input.path, input.specId);
+    }
+}
+//# sourceMappingURL=retention.js.map

package/dist/storage/spec-index.d.ts

@@ -0,0 +1,23 @@
+import type { SpecIndex, SpecIndexRecord } from '../types/index.js';
+/** Exported so other storage/ modules (e.g. spec-store.ts) can verify a spec.md digest without re-implementing the hash. */
+export declare function digestOf(content: string): string;
+/**
+ * Storage-layer-only scalar frontmatter reader — deliberately not the shared
+ * engine/frontmatter-parser.ts, since storage/ may only import from types/
+ * (SPEC-1660 layering). Only reads the flat top-level fields this index needs.
+ */
+export declare function readFrontmatterScalars(content: string): Record<string, string>;
+/**
+ * Rebuild the spec index from every spec.md file under planu/specs/ of
+ * `projectPath` and persist it to planu/.runtime/index.json.
+ *
+ * spec.md is always the source of truth: this function re-reads and re-parses
+ * every spec.md on every call, so a record can never be stale relative to disk.
+ * A project with no spec.md files, or a deleted index.json, rebuilds cleanly.
+ */
+export declare function loadSpecIndex(projectPath: string): Promise<SpecIndex>;
+/** Read the last persisted index without rebuilding it. Used only for diagnostics. */
+export declare function readPersistedSpecIndex(projectPath: string): Promise<SpecIndex>;
+/** List spec index records sorted by id — convenience for callers needing an array. */
+export declare function listSpecIndexRecords(index: SpecIndex): SpecIndexRecord[];
+//# sourceMappingURL=spec-index.d.ts.map

package/dist/storage/spec-index.js

@@ -0,0 +1,123 @@
+// storage/spec-index.ts — SPEC-1699
+// Regenerable read cache over planu/specs/*/spec.md. spec.md is the authoritative
+// record for every field it carries; this index only avoids re-deriving it from
+// scratch elsewhere. Every read re-parses spec.md from disk, so a stale cached
+// record can never be served — the persisted index.json exists so writers can
+// verify their own write landed (digest match) without a caller re-reading spec.md.
+import { readFile, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join, relative } from 'node:path';
+import { glob } from 'glob';
+import { readJson, writeJson } from './base-store.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+function specIndexPath(projectPath) {
+    return join(projectPath, 'planu', '.runtime', 'index.json');
+}
+/** Exported so other storage/ modules (e.g. spec-store.ts) can verify a spec.md digest without re-implementing the hash. */
+export function digestOf(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+const SCALAR_LINE_RE = /^(\w+):\s*(.+)$/;
+const SCENARIO_LINE_RE = /^-?\s*GIVEN\b.*$/;
+const TEST_MARKER_RE = /^TEST:\s*(.+)$/;
+/**
+ * Storage-layer-only scalar frontmatter reader — deliberately not the shared
+ * engine/frontmatter-parser.ts, since storage/ may only import from types/
+ * (SPEC-1660 layering). Only reads the flat top-level fields this index needs.
+ */
+export function readFrontmatterScalars(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match?.[1]) {
+        return {};
+    }
+    const fields = {};
+    for (const line of match[1].split('\n')) {
+        if (/^\s/.test(line)) {
+            continue;
+        }
+        const kv = SCALAR_LINE_RE.exec(line);
+        if (!kv?.[1] || kv[2] === undefined) {
+            continue;
+        }
+        fields[kv[1]] = kv[2].trim().replace(/^"(.*)"$/, '$1');
+    }
+    return fields;
+}
+function extractScenarios(content) {
+    return content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => SCENARIO_LINE_RE.test(line))
+        .map((line) => line.replace(/^-\s*/, ''));
+}
+function extractTestMarkers(content) {
+    const tests = [];
+    for (const line of content.split('\n')) {
+        const match = TEST_MARKER_RE.exec(line.trim());
+        if (match?.[1]) {
+            tests.push(match[1].trim());
+        }
+    }
+    return tests;
+}
+async function parseSpecRecord(projectPath, specMdPath) {
+    const content = await readFile(specMdPath, 'utf-8');
+    const fields = readFrontmatterScalars(content);
+    const id = fields.id ?? '';
+    if (!id) {
+        return null;
+    }
+    const fileStat = await stat(specMdPath);
+    const difficulty = fields.difficulty !== undefined ? Number(fields.difficulty) : NaN;
+    return {
+        id,
+        title: fields.title ?? '',
+        status: fields.status ?? 'draft',
+        type: fields.type ?? '',
+        target: fields.target ?? '',
+        scope: fields.scope ?? '',
+        difficulty: Number.isFinite(difficulty) ? difficulty : null,
+        risk: fields.risk ?? '',
+        createdAt: fields.created ?? null,
+        updatedAt: fileStat.mtime.toISOString(),
+        specPath: relative(projectPath, specMdPath),
+        digest: digestOf(content),
+        scenarios: extractScenarios(content),
+        tests: extractTestMarkers(content),
+    };
+}
+/**
+ * Rebuild the spec index from every spec.md file under planu/specs/ of
+ * `projectPath` and persist it to planu/.runtime/index.json.
+ *
+ * spec.md is always the source of truth: this function re-reads and re-parses
+ * every spec.md on every call, so a record can never be stale relative to disk.
+ * A project with no spec.md files, or a deleted index.json, rebuilds cleanly.
+ */
+export async function loadSpecIndex(projectPath) {
+    const specFiles = await glob(join(projectPath, 'planu', 'specs', '*', 'spec.md'));
+    const parsed = await Promise.all(specFiles.map((specMdPath) => parseSpecRecord(projectPath, specMdPath)));
+    const specs = {};
+    for (const record of parsed) {
+        if (record) {
+            specs[record.id] = record;
+        }
+    }
+    const index = { generatedAt: new Date().toISOString(), specs };
+    // A read-only checkout (or a concurrent writer) must not turn a successful
+    // parse into a failed read — the caller gets the parsed result either way.
+    await writeJson(specIndexPath(projectPath), index).catch((error) => {
+        reportClassifiedDegradation('SPEC_INDEX_CACHE_PERSIST', error);
+    });
+    return index;
+}
+/** Read the last persisted index without rebuilding it. Used only for diagnostics. */
+export async function readPersistedSpecIndex(projectPath) {
+    return readJson(specIndexPath(projectPath), { generatedAt: '', specs: {} });
+}
+/** List spec index records sorted by id — convenience for callers needing an array. */
+export function listSpecIndexRecords(index) {
+    return Object.values(index.specs).sort((left, right) => left.id.localeCompare(right.id));
+}
+//# sourceMappingURL=spec-index.js.map