@planu/cli 5.5.0 → 5.6.0

package/dist/tools/init-project/portable-index-reconciler.js

@@ -1,5 +1,99 @@
+import { readdir, rename, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExistsStrictByStat } from '../../core/shared/fs.js';
 import { globalStore, specStore } from '../../storage/index.js';
 import { importFilesystemSpecs } from '../../engine/spec-migrator/filesystem-import.js';
+function isErrnoCode(error, code) {
+    return (error instanceof Error && 'code' in error && error.code === code);
+}
+async function countFilesRecursive(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT')) {
+            return 0;
+        }
+        throw error;
+    }
+    let count = 0;
+    for (const entry of entries) {
+        count += entry.isDirectory()
+            ? await countFilesRecursive(join(dir, entry.name))
+            : Number(entry.isFile());
+    }
+    return count;
+}
+async function isPristineInitRepo(gitDir) {
+    try {
+        const [objectsCount, refsCount, hasPackedRefs, hasIndex, logsCount, hasAlternates] = await Promise.all([
+            countFilesRecursive(join(gitDir, 'objects')),
+            countFilesRecursive(join(gitDir, 'refs')),
+            pathExistsStrictByStat(join(gitDir, 'packed-refs')),
+            pathExistsStrictByStat(join(gitDir, 'index')),
+            countFilesRecursive(join(gitDir, 'logs')),
+            pathExistsStrictByStat(join(gitDir, 'objects', 'info', 'alternates')),
+        ]);
+        return (objectsCount === 0 &&
+            refsCount === 0 &&
+            !hasPackedRefs &&
+            !hasIndex &&
+            logsCount === 0 &&
+            !hasAlternates);
+    }
+    catch {
+        return false;
+    }
+}
+async function quarantineVerifyAndDelete(gitDir, specDirectory) {
+    const quarantinePath = join(specDirectory, `.git.stray-${String(process.pid)}`);
+    try {
+        await rename(gitDir, quarantinePath);
+    }
+    catch {
+        return false;
+    }
+    if (await isPristineInitRepo(quarantinePath)) {
+        await rm(quarantinePath, { recursive: true, force: true });
+        return true;
+    }
+    await rename(quarantinePath, gitDir).catch(() => undefined);
+    return false;
+}
+async function healStraySpecRepos(projectPath) {
+    const specsRoot = join(projectPath, 'planu', 'specs');
+    let entries;
+    try {
+        entries = await readdir(specsRoot, { withFileTypes: true });
+    }
+    catch {
+        return { removals: [], failures: [] };
+    }
+    const removals = [];
+    const failures = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const specDirectory = join(specsRoot, entry.name);
+        const gitDir = join(specDirectory, '.git');
+        const gitDirStat = await stat(gitDir).catch(() => undefined);
+        if (!gitDirStat?.isDirectory()) {
+            continue;
+        }
+        const relativePath = join('planu', 'specs', entry.name, '.git');
+        const isCandidate = await isPristineInitRepo(gitDir);
+        const removed = isCandidate && (await quarantineVerifyAndDelete(gitDir, specDirectory));
+        if (removed) {
+            removals.push(relativePath);
+        }
+        else {
+            failures.push({ specId: entry.name, path: relativePath, code: 'STRAY_REPO_NOT_PRISTINE' });
+        }
+    }
+    return { removals, failures };
+}
 function classifyFailures(failures, indexedSpecIds) {
     const remainingFailures = [];
     const skippedLegacy = [];
@@ -24,6 +118,7 @@ const NEXT_ACTION_BY_CODE = {
     INVALID_CONTRACT: 'add the required portable frontmatter fields (id, title, type, scope, status, risk, target, difficulty)',
     CREATE_FAILED: 'retry init_project once the underlying store write succeeds',
     INCOMPATIBLE_IDENTITY: 'reconcile the spec identity (id, title, slug, uuid) with the indexed record',
+    STRAY_REPO_NOT_PRISTINE: 'inspect the embedded .git manually — it holds refs, staged state, or history and was left untouched',
 };
 /** Autopilot-first summary of fatal reconciliation failures: what failed, why, and the next action. */
 export function describeReconciliationFailures(failures) {
@@ -43,19 +138,22 @@ export function describeReconciliationFailures(failures) {
     return `Portable spec index reconciliation failed for ${String(failures.length)} contract(s) (${codeSummary}). Affected: ${topPaths}${remainder}. Next: ${nextActions}.`;
 }
 /** Autopilot-first summary of a successful reconciliation, including any legacy skips. */
-export function describeReconciliationSuccess(repositoryFilesChanged, skippedLegacy) {
+export function describeReconciliationSuccess(repositoryFilesChanged, skippedLegacy, strayRepoRemovals = []) {
     const base = repositoryFilesChanged.length === 0
         ? 'Project already initialized. Safe update reconciled the portable spec index without changing repository files.'
         : `Project already initialized. Safe update reconciled the portable spec index and refreshed ${String(repositoryFilesChanged.length)} core host asset file(s).`;
     const skippedSuffix = skippedLegacy.length === 0
         ? ''
         : ` Skipped ${String(skippedLegacy.length)} already-indexed legacy contract(s).`;
-    return base + skippedSuffix;
+    const strayRepoSuffix = strayRepoRemovals.length === 0
+        ? ''
+        : ` Removed ${String(strayRepoRemovals.length)} stray embedded git repositor${strayRepoRemovals.length === 1 ? 'y' : 'ies'} from spec folders.`;
+    return base + skippedSuffix + strayRepoSuffix;
 }
 /** Autopilot-first message for a reconciliation outcome, success or fatal-failure. */
 export function describeReconciliationOutcome(reconciliation, repositoryFilesChanged) {
     return reconciliation.failures.length === 0
-        ? describeReconciliationSuccess(repositoryFilesChanged, reconciliation.skippedLegacy)
+        ? describeReconciliationSuccess(repositoryFilesChanged, reconciliation.skippedLegacy, reconciliation.strayRepoRemovals)
         : describeReconciliationFailures(reconciliation.failures);
 }
 /** Rebuild the mutable external index from the repository-owned portable contracts. */
@@ -70,6 +168,13 @@ export async function reconcilePortableSpecIndex(projectPath, projectId, deps =
     });
     const indexedSpecIds = new Set((await deps.listSpecs(projectId)).map((spec) => spec.id));
     const { failures, skippedLegacy } = classifyFailures(result.failures, indexedSpecIds);
-    return { ...result, failures, skippedLegacy, repositoryFilesChanged: [] };
+    const { removals: strayRepoRemovals, failures: strayRepoFailures } = await healStraySpecRepos(projectPath);
+    return {
+        ...result,
+        failures: [...failures, ...strayRepoFailures],
+        skippedLegacy,
+        repositoryFilesChanged: [],
+        strayRepoRemovals,
+    };
 }
 //# sourceMappingURL=portable-index-reconciler.js.map

package/dist/tools/init-project/runtime-residue.d.ts

@@ -0,0 +1,2 @@
+export declare function scheduleRuntimeResidueSweep(projectPath: string): void;
+//# sourceMappingURL=runtime-residue.d.ts.map

package/dist/tools/init-project/runtime-residue.js

@@ -0,0 +1,11 @@
+// tools/init-project/runtime-residue.ts — SPEC-1695
+// Fire-and-forget trigger for the runtime-residue sweep, called from init_project
+// so existing client checkouts self-heal without a manual cleanup step.
+import { withAudit } from '../../engine/autopilot/audit-logger.js';
+import { sweepRuntimeResidue } from '../../engine/housekeeping/runtime-residue-sweep.js';
+export function scheduleRuntimeResidueSweep(projectPath) {
+    void withAudit(projectPath, 'init_project', 'sweepRuntimeResidue', () => sweepRuntimeResidue(projectPath), (result) => ({ removed: result.removed.length })).catch(() => {
+        /* best-effort */
+    });
+}
+//# sourceMappingURL=runtime-residue.js.map

package/dist/tools/session-checkpoint.js

@@ -9,7 +9,7 @@ import { compactResult } from './output-formatter.js';
 export async function handleSessionCheckpoint(args) {
     const snapshot = sessionTracker.getSnapshot();
     await writeCheckpoint(args.projectPath, snapshot);
-    return compactResult(`Session checkpoint written to ${args.projectPath}/planu/session-context.md\n` +
+    return compactResult(`Session checkpoint written to ${args.projectPath}/planu/.runtime/session-context.md\n` +
         `Calls recorded: ${String(snapshot.callCount)}, ` +
         `files tracked: ${String(snapshot.modifiedFiles.length)}.`);
 }

package/dist/tools/update-status/index.js

@@ -7,7 +7,7 @@ import { rollbackTransitionSpec, transitionSpec, } from '../../engine/spec-state
 import { calculateAccuracy } from '../../engine/estimator.js';
 import { cascadeCheck } from '../../engine/spec-versioner.js';
 import { runComplianceGates } from '../update-status-convention-gate.js';
-import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, } from '../update-status-actions.js';
+import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, pruneRuntimeArtifactsOnTerminal, } from '../update-status-actions.js';
 import { compactObj } from '../../engine/compact-obj.js';
 import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, checkImplementationDependencyGate, checkSpecArtifactCommittedGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
 import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
@@ -1426,6 +1426,12 @@ export async function handleUpdateStatus(params, server) {
                             /* reliability-optional: TERMINAL_VALIDATION_REPORT — canonical receipt is authoritative */
                             reportClassifiedDegradation('TERMINAL_VALIDATION_REPORT', error);
                         });
+                        try {
+                            await pruneRuntimeArtifactsOnTerminal(projectId, specId);
+                        }
+                        catch (error) {
+                            reportClassifiedDegradation('RETENTION_TERMINAL_PRUNE', error);
+                        }
                     }
                     const allSpecs = await specStore.listSpecs(projectId);
                     const cascadeResult = cascadeCheck(specId, allSpecs, newStatus);

package/dist/tools/update-status-actions.d.ts

@@ -1,4 +1,10 @@
-import type { ConstitutionViolation, DoneSideEffectsReport } from '../types/index.js';
+import type { ConstitutionViolation, DoneSideEffectsReport, RetentionResult } from '../types/index.js';
+/**
+ * Remove handoff packages, evidence bundles, and archived context for a spec
+ * that just reached a terminal status (done or discarded). Never touches
+ * planu/specs/ — the canonical spec.md lives outside runtime storage.
+ */
+export declare function pruneRuntimeArtifactsOnTerminal(projectId: string, specId: string): Promise<RetentionResult>;
 export declare function runImplementingActions(projectId: string, specId: string, options?: {
     deferSideEffects?: boolean;
     projectPath?: string;

package/dist/tools/update-status-actions.js

@@ -1,7 +1,15 @@
-import { specStore, knowledgeStore } from '../storage/index.js';
+import { specStore, knowledgeStore, projectDataDir, enforceRetention } from '../storage/index.js';
 import { checkConstitutionCompliance } from './create-spec-tech.js';
 import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { hasPending, markPending, clearPending } from '../engine/autopilot/cascade-deduplicator.js';
+/**
+ * Remove handoff packages, evidence bundles, and archived context for a spec
+ * that just reached a terminal status (done or discarded). Never touches
+ * planu/specs/ — the canonical spec.md lives outside runtime storage.
+ */
+export async function pruneRuntimeArtifactsOnTerminal(projectId, specId) {
+    return enforceRetention({ kind: 'spec-artifacts', path: projectDataDir(projectId), specId });
+}
 function normalizeRejectedReasons(results) {
     return results.map((result) => {
         const reason = result.reason;
@@ -210,7 +218,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
     // SPEC-649: slim cascade — 2 actions only
     const autopilotSummary = [
         'session.json: refresh queued',
-        'releases/pending.json: refresh queued',
+        'project.json releases: refresh queued',
     ];
     return {
         mergeWarning,

package/dist/types/housekeeping.d.ts

@@ -146,4 +146,8 @@ export interface HousekeepingHistoryEntry {
     prevSha: string;
     sha256: string;
 }
+export interface RuntimeResidueSweepResult {
+    /** Absolute paths of every legacy runtime artifact removed from planu/. */
+    removed: string[];
+}
 //# sourceMappingURL=housekeeping.d.ts.map

package/dist/types/index.d.ts

@@ -293,5 +293,6 @@ export * from './host-tool-filter.js';
 export * from './reconcile.js';
 export * from './release-pipeline.js';
 export * from './network-policy.js';
+export * from './retention.js';
 export type { VerifiedImplementationReviewResult, VerifiedImplementationReviewOk, VerifiedImplementationReviewErr, ImplementationReviewRejectionReason, } from './handoff-artifacts.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -304,4 +304,5 @@ export * from './reconcile.js';
 // SPEC-1012: Release spec closer types
 export * from './release-pipeline.js';
 export * from './network-policy.js';
+export * from './retention.js';
 //# sourceMappingURL=index.js.map

package/dist/types/retention.d.ts

@@ -0,0 +1,12 @@
+export interface RetentionResult {
+    readonly freedBytes: number;
+    readonly removedPaths: readonly string[];
+}
+export type RetentionKind = 'transition-log' | 'graph-cache' | 'spec-store-backup' | 'idempotency' | 'snapshot' | 'spec-artifacts';
+export interface EnforceRetentionInput {
+    readonly kind: RetentionKind;
+    readonly path: string;
+    readonly protectedPaths?: readonly string[];
+    readonly specId?: string;
+}
+//# sourceMappingURL=retention.d.ts.map

package/dist/types/retention.js

@@ -0,0 +1,3 @@
+// types/retention.ts — SPEC-1697: retention budgets for runtime storage artifacts
+export {};
+//# sourceMappingURL=retention.js.map

package/dist/types/spec/core.d.ts

@@ -139,6 +139,13 @@ export interface Spec {
      * Contains failure scenarios, addressed count, and overall risk.
      */
     challengeReport?: ChallengeReport;
+    /**
+     * SPEC-1699: sha256 digest of the spec.md content this record's title was
+     * last synced from. Absent or mismatched against the current spec.md means
+     * the record is stale and is refreshed on the next read that supplies a
+     * canonicalRoot (see spec-store.ts refreshSpecFromDisk).
+     */
+    contentDigest?: string;
 }
 /** SPEC-964: Result of running challenge_spec on a spec. */
 export interface ChallengeReport {

package/dist/types/spec/index-cache.d.ts

@@ -0,0 +1,25 @@
+/** One spec's fields as parsed from its canonical spec.md, plus a content digest. */
+export interface SpecIndexRecord {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly type: string;
+    readonly target: string;
+    readonly scope: string;
+    readonly difficulty: number | null;
+    readonly risk: string;
+    readonly createdAt: string | null;
+    readonly updatedAt: string;
+    readonly specPath: string;
+    readonly digest: string;
+    /** GIVEN/WHEN/THEN acceptance-criteria lines parsed from the spec.md body. */
+    readonly scenarios: readonly string[];
+    /** `TEST:` marker contents parsed from the spec.md body. */
+    readonly tests: readonly string[];
+}
+/** Regenerable cache persisted at planu/.runtime/index.json. spec.md is authoritative. */
+export interface SpecIndex {
+    readonly generatedAt: string;
+    readonly specs: Readonly<Record<string, SpecIndexRecord>>;
+}
+//# sourceMappingURL=index-cache.d.ts.map

package/dist/types/spec/index-cache.js

@@ -0,0 +1,3 @@
+// Planu — Regenerable spec.md read-index types (SPEC-1699)
+export {};
+//# sourceMappingURL=index-cache.js.map

package/dist/types/spec/index.d.ts

@@ -6,4 +6,5 @@ export * from './agent.js';
 export * from './repair.js';
 export * from './health-score.js';
 export * from './versioning.js';
+export * from './index-cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/spec/index.js

@@ -8,4 +8,5 @@ export * from './agent.js';
 export * from './repair.js';
 export * from './health-score.js';
 export * from './versioning.js';
+export * from './index-cache.js';
 //# sourceMappingURL=index.js.map

package/dist/types/spec/inputs.d.ts

@@ -215,7 +215,7 @@ export interface SpecMigrationDeps {
     listSpecs: (projectId: string) => Promise<Spec[]>;
     updateSpec: (projectId: string, specId: string, updates: Partial<Spec>) => Promise<Spec>;
 }
-export type FilesystemImportFailureCode = 'READ_FAILED' | 'INVALID_CONTRACT' | 'CREATE_FAILED' | 'INCOMPATIBLE_IDENTITY';
+export type FilesystemImportFailureCode = 'READ_FAILED' | 'INVALID_CONTRACT' | 'CREATE_FAILED' | 'INCOMPATIBLE_IDENTITY' | 'STRAY_REPO_NOT_PRISTINE';
 export interface FilesystemImportFailure {
     specId: string;
     path: string;
@@ -242,6 +242,7 @@ export interface SkippedLegacyContract {
 export interface PortableIndexReconciliationResult extends FilesystemImportResult {
     repositoryFilesChanged: string[];
     skippedLegacy: SkippedLegacyContract[];
+    strayRepoRemovals: string[];
 }
 export interface ImportEntryContext {
     projectPath: string;

package/dist/types/spec-format.d.ts

@@ -72,6 +72,7 @@ export interface PlanuCanonicalPathPolicy {
     readonly canonicalSpecFiles: readonly string[];
     readonly canonicalSpecDirs: readonly string[];
     readonly forbiddenHostAssetRootDirs: readonly string[];
+    readonly runtimeHomeDir: string;
     readonly generatedRuntimePatterns: readonly string[];
     readonly legacyMergeBeforeDeleteFiles: readonly string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",

package/scripts/lib/pending-release-file.mjs

@@ -116,15 +116,31 @@ export function isCommitReachable(repoRoot, commit, ontoCommit) {
   throw new Error(`git merge-base --is-ancestor exited with status ${String(result.status)}`);
 }
 
-export async function writePendingReleaseLedger(pendingPath, entries) {
-  const temporaryPath = `${pendingPath}.${process.pid}.${Date.now()}.tmp`;
+async function readJsonObject(path) {
   try {
-    await writeFile(temporaryPath, `${JSON.stringify(entries, null, 2)}\n`, {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+/**
+ * SPEC-1699: writes `entries` into the `releases` field of the committed
+ * planu/project.json, preserving every other field already on disk.
+ */
+export async function writePendingReleaseLedger(projectJsonPath, entries) {
+  const project = await readJsonObject(projectJsonPath);
+  const nextProject = { ...project, releases: entries };
+  const temporaryPath = `${projectJsonPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(nextProject, null, 2)}\n`, {
       encoding: 'utf8',
       flag: 'wx',
       mode: 0o644,
     });
-    await rename(temporaryPath, pendingPath);
+    await rename(temporaryPath, projectJsonPath);
   } catch (error) {
     await rm(temporaryPath, { force: true });
     throw error;