@planu/cli 5.5.3 → 5.6.0

package/dist/engine/sdd-flow/checkpoints.js

@@ -2,12 +2,28 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../storage/storage-layout.js';
+const RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function assertValidRunId(runId) {
+    if (!RUN_ID_PATTERN.test(runId)) {
+        throw new Error(`Invalid runId: "${runId}". Run IDs must match ${RUN_ID_PATTERN.source} (no path separators).`);
+    }
+}
 function getStateDir(projectPath) {
+    return projectRuntimeDir(projectPath, 'state');
+}
+function getLegacyStateDir(projectPath) {
     return join(projectPath, 'planu', 'state');
 }
 function getStatePath(projectPath, runId) {
+    assertValidRunId(runId);
     return join(getStateDir(projectPath), `sdd-flow-${runId}.json`);
 }
+function getLegacyStatePath(projectPath, runId) {
+    assertValidRunId(runId);
+    return join(getLegacyStateDir(projectPath), `sdd-flow-${runId}.json`);
+}
 export async function saveCheckpoint(projectPath, state) {
     const dir = getStateDir(projectPath);
     if (!existsSync(dir)) {
@@ -18,11 +34,22 @@ export async function saveCheckpoint(projectPath, state) {
 }
 export async function loadCheckpoint(projectPath, runId) {
     const path = getStatePath(projectPath, runId);
-    if (!existsSync(path)) {
+    if (existsSync(path)) {
+        try {
+            const raw = await readFile(path, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    // SPEC-1695: one-time legacy fallback for runs persisted before the relocation.
+    const legacyPath = getLegacyStatePath(projectPath, runId);
+    if (!existsSync(legacyPath)) {
         return null;
     }
     try {
-        const raw = await readFile(path, 'utf-8');
+        const raw = await readFile(legacyPath, 'utf-8');
         return JSON.parse(raw);
     }
     catch {

package/dist/engine/session/checkpoint-writer.d.ts

@@ -4,7 +4,7 @@ export declare function buildCheckpointBlock(snapshot: AutoSessionSnapshot): str
 /** Remove old checkpoint sections and prepend the new one to keep the file small. */
 export declare function replaceLatestCheckpoint(existing: string, newBlock: string): string;
 /**
- * Write a compact checkpoint to `<projectPath>/planu/session-context.md`.
+ * Write a compact checkpoint to `<projectPath>/planu/.runtime/session-context.md`.
  * Replaces any previous checkpoint section — idempotent.
  * May throw — callers should catch or use maybeWriteCheckpoint.
  */

package/dist/engine/session/checkpoint-writer.js

@@ -1,5 +1,6 @@
 // engine/session/checkpoint-writer.ts — Writes a compact session checkpoint to
-// planu/session-context.md (SPEC-563). Fire-and-forget safe — never throws to caller.
+// planu/.runtime/session-context.md (SPEC-563, relocated under SPEC-1699).
+// Fire-and-forget safe — never throws to caller.
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { sessionTracker } from './session-tracker.js';
@@ -56,13 +57,13 @@ export function replaceLatestCheckpoint(existing, newBlock) {
     return `${newBlock}\n${trimmed}`.trimEnd() + '\n';
 }
 /**
- * Write a compact checkpoint to `<projectPath>/planu/session-context.md`.
+ * Write a compact checkpoint to `<projectPath>/planu/.runtime/session-context.md`.
  * Replaces any previous checkpoint section — idempotent.
  * May throw — callers should catch or use maybeWriteCheckpoint.
  */
 export async function writeCheckpoint(projectPath, snapshot) {
-    const planuDir = join(projectPath, 'planu');
-    const filePath = join(planuDir, 'session-context.md');
+    const runtimeDir = join(projectPath, 'planu', '.runtime');
+    const filePath = join(runtimeDir, 'session-context.md');
     let existing = '';
     try {
         existing = await readFile(filePath, 'utf8');
@@ -72,7 +73,7 @@ export async function writeCheckpoint(projectPath, snapshot) {
     }
     const newBlock = buildCheckpointBlock(snapshot);
     const updated = replaceLatestCheckpoint(existing, newBlock);
-    await mkdir(planuDir, { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
     await writeFile(filePath, updated, 'utf8');
 }
 /**

package/dist/engine/session-state/writer.js

@@ -4,16 +4,17 @@ import { readFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { stableJsonStringify, stableWriteGeneratedFile, stripRootUpdatedAt, } from '../generated-artifact-writer.js';
-const STATE_DIR = 'state';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../storage/storage-layout.js';
 const ROOT_SESSION = 'session.json';
 function stateDir(projectPath) {
-    return join(projectPath, 'planu', STATE_DIR);
+    return projectRuntimeDir(projectPath, 'state');
 }
 function specFile(projectPath, specId) {
     return join(stateDir(projectPath), `session-${specId}.json`);
 }
 export function rootFile(projectPath) {
-    return join(projectPath, 'planu', ROOT_SESSION);
+    return join(projectPath, 'planu', '.runtime', ROOT_SESSION);
 }
 function getModifiedFiles(projectPath) {
     try {

package/dist/engine/spec-format/lean-spec-generator.js

@@ -166,7 +166,7 @@ function extractCheckboxCriteria(description) {
 function extractGivenWhenThenCriteria(description) {
     const criteria = [];
     // Single-line: GIVEN ... WHEN ... THEN ...
-    const singleLineRegex = /^[ \t]*(?:[-*>]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
+    const singleLineRegex = /^[ \t]*(?:[-*>]\s*|\d+[.)]\s*)?GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+(.+)$/gim;
     let match = singleLineRegex.exec(description);
     while (match) {
         const thenText = match[1]?.trim() ?? '';

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -5,6 +5,13 @@ export declare function isCanonicalPlanuRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
 export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;
-export declare function isCanonicalReleaseFile(relativeToPlanu: string): boolean;
+/**
+ * Legacy-transition carve-out ONLY: strict-planu-cleanup.ts still walks a
+ * not-yet-migrated planu/releases/ directory and must not delete
+ * pending.json before the migration folds it into project.json's
+ * `releases` field. This is not part of the canonical contract — see
+ * canonicalContractText().
+ */
+export declare function isLegacyReleasePendingFile(relativeToPlanu: string): boolean;
 export declare function canonicalContractText(): string;
 //# sourceMappingURL=planu-canonical-policy.d.ts.map

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -14,18 +14,12 @@ const LEGACY_CONTENT_BEARING_PATTERNS = legacyArtifactRulesLoader
     .filter((rule) => rule.classification === 'content-bearing')
     .map((rule) => rule.pattern);
 export const PLANU_CANONICAL_POLICY = {
-    canonicalRootFiles: [
-        'conventions.json',
-        'context.md',
-        'project.json',
-        'session-context.md',
-        'session.json',
-        'technology-selection.json',
-    ],
-    canonicalRootDirs: ['releases', 'specs'],
+    canonicalRootFiles: ['project.json'],
+    canonicalRootDirs: ['specs'],
     canonicalSpecFiles: ['spec.md'],
     canonicalSpecDirs: [],
     forbiddenHostAssetRootDirs: ['agents', 'skills', 'rules', 'hooks'],
+    runtimeHomeDir: 'planu/.runtime/',
     generatedRuntimePatterns: [
         'planu/index.html',
         'planu/roadmap.html',
@@ -36,6 +30,7 @@ export const PLANU_CANONICAL_POLICY = {
         'planu/handoffs/',
         'planu/data/',
         'planu/state/',
+        'planu/reports/',
         'planu/.locks/',
         'planu/specs/data/',
         'planu/specs/*/technical-report.html',
@@ -68,7 +63,14 @@ export function isCanonicalSpecDir(name) {
 export function mustMergeBeforeDeleteSpecFile(name) {
     return LEGACY_MERGE_SET.has(name);
 }
-export function isCanonicalReleaseFile(relativeToPlanu) {
+/**
+ * Legacy-transition carve-out ONLY: strict-planu-cleanup.ts still walks a
+ * not-yet-migrated planu/releases/ directory and must not delete
+ * pending.json before the migration folds it into project.json's
+ * `releases` field. This is not part of the canonical contract — see
+ * canonicalContractText().
+ */
+export function isLegacyReleasePendingFile(relativeToPlanu) {
     return relativeToPlanu === 'releases/pending.json';
 }
 export function canonicalContractText() {
@@ -76,15 +78,14 @@ export function canonicalContractText() {
         'planu/',
         '  conventions.json',
         '  context.md',
-        '  project.json',
+        '  project.json (pending release records live in its `releases` field)',
         '  session-context.md',
         '  session.json',
         '  technology-selection.json',
-        '  releases/',
-        '    pending.json',
         '  specs/',
         '    SPEC-XXX-slug/',
         '      spec.md',
+        '  .runtime/ (generated runtime home — session/index data, not committed)',
         '',
         'Evidence artifacts are Planu runtime data and are stored outside planu/specs/.',
         '',

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -8,8 +8,21 @@ import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
 import { scanLegacyArtifacts } from './legacy-classifier.js';
-import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalReleaseFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
+// SPEC-1699: legacy planu/ root files folded into project.json by init_project's
+// migration. Destructive cleanup must never delete them outright — only the
+// migration step, which reads their content first, may retire them.
+const PENDING_ROOT_MIGRATION_FILES = new Set([
+    'conventions.json',
+    'context.md',
+    'session-context.md',
+    'session.json',
+    'technology-selection.json',
+]);
+function isPendingRootMigrationFile(entry) {
+    return PENDING_ROOT_MIGRATION_FILES.has(entry);
+}
 async function pathIsDirectory(path) {
     try {
         return (await stat(path)).isDirectory();
@@ -176,11 +189,23 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     for (const entry of entries) {
         const full = join(planuDir, entry);
         const isDir = await pathIsDirectory(full);
+        if (isDir && entry === 'releases') {
+            // SPEC-1699: 'releases' is no longer a canonical root dir, but its
+            // pending.json still needs the dedicated fold-into-project.json
+            // migration below before its directory can be removed.
+            continue;
+        }
         if (isDir && !isCanonicalPlanuRootDir(entry)) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
             continue;
         }
+        if (!isDir && isPendingRootMigrationFile(entry)) {
+            // SPEC-1699: content-bearing legacy root file — init_project's migration
+            // folds it into project.json before this cleanup may delete it.
+            result.proposed.push(relative(projectPath, full));
+            continue;
+        }
         if (!isDir && !isCanonicalPlanuRootFile(entry)) {
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
@@ -189,7 +214,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     const releasesDir = join(planuDir, 'releases');
     for (const entry of await readDirectory(releasesDir)) {
         const rel = `releases/${entry}`;
-        if (!isCanonicalReleaseFile(rel)) {
+        if (!isLegacyReleasePendingFile(rel)) {
             const full = join(releasesDir, entry);
             await removePath(projectPath, full);
             result.deleted.push(relative(projectPath, full));
@@ -235,7 +260,7 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
         }
         for (const entry of await readDirectory(join(planuDir, 'releases'))) {
             const rel = `releases/${entry}`;
-            if (!isCanonicalReleaseFile(rel)) {
+            if (!isLegacyReleasePendingFile(rel)) {
                 offenders.push(`planu/${rel}`);
             }
         }

package/dist/engine/universal-rules/rules/planu-release-policy.js

@@ -19,7 +19,7 @@ When implementation changes are complete and validated, always address release e
 - local validation commands passed
 - changelog or release notes updated when applicable
 - package version and git tag stay aligned
-- release metadata under \`planu/releases/pending.json\` contains only genuinely pending entries
+- release metadata under the \`releases\` field of \`planu/project.json\` contains only genuinely pending entries
 - published package smoke check is run after release when applicable
 
 ## Hard Blocks

package/dist/engine/validator/spec-compliance-runner.js

@@ -24,6 +24,41 @@ const FILE_EXTENSION = /\.[A-Za-z0-9]+$/;
 function isPathShapedSegment(segment) {
     return segment.length > 0 && (PATH_SHAPED.test(segment) || FILE_EXTENSION.test(segment));
 }
+function splitInlineArrayItems(content) {
+    const items = [];
+    let current = '';
+    let quote = null;
+    for (const char of content) {
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === ',') {
+            items.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    items.push(current);
+    return items;
+}
+function parseInlineTestLinks(bracketContent) {
+    return splitInlineArrayItems(bracketContent)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0)
+        .map((item) => parseTestLinkString(item))
+        .filter((link) => link !== null);
+}
 function parseTestLinkString(raw) {
     if (WINDOWS_DRIVE_PATH.test(raw)) {
         return { path: raw };
@@ -104,6 +139,16 @@ export function parseFrontmatterScenarios(raw) {
             inSteps = false;
             continue;
         }
+        const inlineTestsMatch = /^\s+tests:\s*\[(.*)\]\s*$/.exec(trimmed);
+        if (inlineTestsMatch) {
+            currentScenario.tests = [
+                ...(currentScenario.tests ?? []),
+                ...parseInlineTestLinks(inlineTestsMatch[1] ?? ''),
+            ];
+            inTests = false;
+            inSteps = false;
+            continue;
+        }
         if (/^\s+steps:\s*$/.test(trimmed)) {
             currentScenario.steps ??= [];
             inSteps = true;

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/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