@planu/cli 5.5.0 → 5.6.0

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

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

@@ -29,8 +29,11 @@ export declare function invalidateSpecsCache(projectId: string): void;
 export declare function discoverCanonicalSpecPath(specId: string, canonicalRoot: string): Promise<string | null>;
 /**
  * List every spec for a project.
+ *
+ * When `canonicalRoot` is supplied, every record's content-derived fields are
+ * verified against the current spec.md before being returned (SPEC-1699).
  */
-export declare function listSpecs(projectId: string): Promise<Spec[]>;
+export declare function listSpecs(projectId: string, canonicalRoot?: string): Promise<Spec[]>;
 /**
  * Run a read-modify side effect against a fresh spec snapshot while holding the
  * same cross-process lock used by status mutations.
@@ -39,9 +42,11 @@ export declare function withFreshSpecsLock<T>(projectId: string, fn: (specs: Spe
 /**
  * Get a single spec by ID. Returns `null` when not found.
  *
- * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * When `canonicalRoot` is supplied: a legacy absolute `specPath`/`technicalPath`
  * for this spec is migrated to its portable project-relative identity first
- * (best-effort — a failed migration attempt never blocks the read).
+ * (best-effort — a failed migration attempt never blocks the read), and the
+ * returned record's content-derived fields are verified against the current
+ * spec.md before being returned (SPEC-1699).
  */
 export declare function getSpec(projectId: string, specId: string, canonicalRoot?: string): Promise<Spec | null>;
 /** Result of a {@link migrateLegacySpecPaths} run. */

package/dist/storage/spec-store.js

@@ -1,5 +1,6 @@
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 import { CriticalJsonReadError, readCriticalJson, readJson, writeJson, projectDataDir, } from './base-store.js';
+import { enforceRetention } from './retention.js';
 import { decodeCriticalSchema, registerCriticalSchema } from './schema-registry.js';
 import { BoundaryFailure } from '../errors/error-taxonomy.js';
 import { withFileLock } from './file-mutex.js';
@@ -8,11 +9,13 @@ import { computeHealthScore } from '../engine/spec-health-scorer.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { loadSpecContent } from '../engine/validation-loop.js';
 import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { glob } from 'glob';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { acquireLock, releaseLock } from '../engine/safety/cross-process-lock.js';
-import { resolvePortableSpecPath, toPortableSpecPath, PortablePathError, } from './project-identity.js';
+import { resolvePortableSpecPath, resolveVerifiedSpecPath, toPortableSpecPath, PortablePathError, } from './project-identity.js';
+import { digestOf, readFrontmatterScalars } from './spec-index.js';
 import { appendEntry, getLastHash } from './audit-trail-store.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashEntry } from '../engine/audit-trail/hasher.js';
@@ -200,6 +203,7 @@ async function saveAll(projectId, specs) {
     const normalized = specs.map((spec) => normalizeSpec(spec));
     validateCanonicalSpecRows(projectId, normalized);
     await writeJson(specsFile(projectId), { schemaVersion: 1, data: normalized });
+    await enforceRetention({ kind: 'spec-store-backup', path: specsFile(projectId) });
     specsCache.set(projectId, normalized);
 }
 /** Evict the cache for a project (e.g. after external file changes). */
@@ -221,12 +225,72 @@ export async function discoverCanonicalSpecPath(specId, canonicalRoot) {
     });
     return candidates.length === 1 ? (candidates[0] ?? null) : null;
 }
+/**
+ * Persist a digest-refresh in isolation from whatever mutation the caller of
+ * getSpec/listSpecs is otherwise doing. Best-effort: failure to persist never
+ * blocks the caller — the freshly parsed value is already what gets returned.
+ */
+async function persistDigestRefresh(projectId, specId, title, contentDigest) {
+    await withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const idx = specs.findIndex((s) => s.id === specId);
+        if (idx === -1) {
+            return;
+        }
+        const nextSpecs = specs.map((current, currentIdx) => currentIdx === idx ? { ...current, title, contentDigest } : current);
+        await saveAll(projectId, nextSpecs);
+    });
+}
+/**
+ * SPEC-1699: single-source-of-truth choke point. spec.md is authoritative for
+ * the fields it carries — before returning a record, verify the persisted
+ * `contentDigest` still matches the current spec.md on disk. On a mismatch or
+ * missing digest, re-parse spec.md and return the fresh title/digest instead
+ * of the possibly-stale specs.json copy. Requires `canonicalRoot` to locate
+ * spec.md; callers that omit it get the specs.json record unchecked (matching
+ * the existing canonicalRoot-gated legacy-migration behavior on this same path).
+ */
+async function refreshSpecFromDisk(projectId, spec, canonicalRoot) {
+    let specMdPath;
+    try {
+        specMdPath = await resolveVerifiedSpecPath(spec.id, spec.specPath, canonicalRoot);
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_CHECK_SKIPPED', error);
+        return spec;
+    }
+    let content;
+    try {
+        content = await readFile(specMdPath, 'utf-8');
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_CHECK_SKIPPED', error);
+        return spec;
+    }
+    const digest = digestOf(content);
+    if (digest === spec.contentDigest) {
+        return spec;
+    }
+    const fields = readFrontmatterScalars(content);
+    const refreshed = { ...spec, title: fields.title ?? spec.title, contentDigest: digest };
+    await persistDigestRefresh(projectId, spec.id, refreshed.title, digest).catch((error) => {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_REFRESH_PERSIST', error);
+    });
+    return refreshed;
+}
 // --- public API ---
 /**
  * List every spec for a project.
+ *
+ * When `canonicalRoot` is supplied, every record's content-derived fields are
+ * verified against the current spec.md before being returned (SPEC-1699).
  */
-export async function listSpecs(projectId) {
-    return loadAll(projectId);
+export async function listSpecs(projectId, canonicalRoot) {
+    const specs = await loadAll(projectId);
+    if (canonicalRoot === undefined) {
+        return specs;
+    }
+    return Promise.all(specs.map((spec) => refreshSpecFromDisk(projectId, spec, canonicalRoot)));
 }
 /**
  * Run a read-modify side effect against a fresh spec snapshot while holding the
@@ -238,9 +302,11 @@ export async function withFreshSpecsLock(projectId, fn) {
 /**
  * Get a single spec by ID. Returns `null` when not found.
  *
- * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * When `canonicalRoot` is supplied: a legacy absolute `specPath`/`technicalPath`
  * for this spec is migrated to its portable project-relative identity first
- * (best-effort — a failed migration attempt never blocks the read).
+ * (best-effort — a failed migration attempt never blocks the read), and the
+ * returned record's content-derived fields are verified against the current
+ * spec.md before being returned (SPEC-1699).
  */
 export async function getSpec(projectId, specId, canonicalRoot) {
     if (canonicalRoot !== undefined) {
@@ -249,7 +315,11 @@ export async function getSpec(projectId, specId, canonicalRoot) {
         });
     }
     const specs = await loadAll(projectId);
-    return specs.find((s) => s.id === specId) ?? null;
+    const spec = specs.find((s) => s.id === specId) ?? null;
+    if (spec && canonicalRoot !== undefined) {
+        return refreshSpecFromDisk(projectId, spec, canonicalRoot);
+    }
+    return spec;
 }
 /**
  * Record one hash-chained audit event for a legacy specPath migration batch.

package/dist/storage/storage-catalog.js

@@ -69,9 +69,9 @@ export function createStorageCatalog(context = {}) {
         },
         {
             id: 'portable-release-evidence',
-            templatePath: '<project>/planu/releases/',
-            resolvedPath: portableRoot ? join(portableRoot, 'releases') : undefined,
-            purpose: 'Versioned release declarations and portable verification evidence.',
+            templatePath: '<project>/planu/project.json#releases',
+            resolvedPath: portableRoot ? join(portableRoot, 'project.json') : undefined,
+            purpose: 'Pending release declarations tracked in the releases field of project.json.',
             owner: 'project',
             sourceOfTruth: true,
             lifecycle: 'portable',

package/dist/storage/storage-layout.d.ts

@@ -19,6 +19,14 @@ export interface StorageLayoutOptions {
     readonly homeDirectory?: string;
     readonly platform?: NodeJS.Platform;
 }
+export type ProjectRuntimeSubdir = 'state' | 'cache' | 'logs' | 'reports';
+/**
+ * Resolve the per-project runtime directory for a subdir kind.
+ * Rooted at <projectPath>/planu/.runtime/ — the only per-project runtime root.
+ * Platform storage roots from resolveStorageLayout are machine-local and do not
+ * apply to per-project artifacts.
+ */
+export declare function projectRuntimeDir(projectPath: string, subdir: ProjectRuntimeSubdir): string;
 /** Resolve every machine-local Planu path independently from the current directory. */
 export declare function resolveStorageLayout(options?: StorageLayoutOptions): StorageLayout;
 //# sourceMappingURL=storage-layout.d.ts.map

package/dist/storage/storage-layout.js

@@ -73,6 +73,15 @@ function resolvePlatformRoots(platform, home, env) {
     }
     return xdgRoots(home, env);
 }
+/**
+ * Resolve the per-project runtime directory for a subdir kind.
+ * Rooted at <projectPath>/planu/.runtime/ — the only per-project runtime root.
+ * Platform storage roots from resolveStorageLayout are machine-local and do not
+ * apply to per-project artifacts.
+ */
+export function projectRuntimeDir(projectPath, subdir) {
+    return join(projectPath, 'planu', '.runtime', subdir);
+}
 /** Resolve every machine-local Planu path independently from the current directory. */
 export function resolveStorageLayout(options = {}) {
     const env = options.env ?? process.env;