@planu/cli 5.4.1 → 5.5.3

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+## [5.5.3] - 2026-08-30
+
+### Bug Fixes
+- fix: reuse canonical pathExistsStrictByStat and give worktree-list test a real project path
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
+## [5.5.2] - 2026-08-30
+
+### Bug Fixes
+- fix: reuse canonical pathExistsStrictByStat and give worktree-list test a real project path
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
+## [5.5.1] - 2026-08-30
+
+### Bug Fixes
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
+## [5.5.0] - 2026-08-29
+
+### Features
+- feat(SPEC-1681): cache the prettier format gate with content strategy
+
+### Bug Fixes
+- fix(SPEC-1684): cap vitest workers at 6 in preflight related and full-suite runs
+- fix(storage): handle ENOENT explicitly in best-effort path normalization
+- fix(SPEC-1677,SPEC-1678): dedupe AGENTS.md changes and bound legacy skips to contract codes
+- fix(SPEC-1678): classify legacy contract failures as non-fatal skipped entries
+- fix(SPEC-1677): install and refresh planu core host assets on safe update
+- fix(SPEC-1679): normalize both roots in canonical re-check to match heal semantics
+- fix(SPEC-1679): self-heal missing registry logicalProjectId in canonical-root gate
+
+
 ## [5.4.1] - 2026-08-29
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"c920f236390f64d91a02ca3e0566e59210f00a49"}
+{"schemaVersion":1,"commit":"5060255598e14cab792b6b5b0d75a077f23fe018"}

package/dist/engine/git/git-command-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function assertSafeGitInvocation(cwd: string, args: readonly string[]): void;
+//# sourceMappingURL=git-command-guard.d.ts.map

package/dist/engine/git/git-command-guard.js

@@ -0,0 +1,43 @@
+import { normalize, sep } from 'node:path';
+const VALUE_TAKING_GLOBAL_OPTIONS = new Set([
+    '-C',
+    '-c',
+    '--config-env',
+    '--exec-path',
+    '--git-dir',
+    '--work-tree',
+    '--namespace',
+    '--super-prefix',
+    '--attr-source',
+    '--list-cmds',
+]);
+const REPO_CREATING_SUBCOMMANDS = new Set(['init', 'clone']);
+function resolveSubcommand(args) {
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index];
+        if (!arg?.startsWith('-')) {
+            return arg;
+        }
+        if (!arg.includes('=') && VALUE_TAKING_GLOBAL_OPTIONS.has(arg)) {
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return undefined;
+}
+function cwdTargetsSpecFolder(cwd) {
+    const segments = normalize(cwd).split(sep);
+    return segments.some((segment, i) => segment === 'planu' && segments[i + 1] === 'specs');
+}
+export function assertSafeGitInvocation(cwd, args) {
+    const subcommand = resolveSubcommand(args);
+    if (subcommand !== undefined && REPO_CREATING_SUBCOMMANDS.has(subcommand)) {
+        throw new Error(`Refusing to run repo-creating git subcommand "${subcommand}" (cwd: ${cwd}). Planu's git wrappers never create git repositories.`);
+    }
+    if (cwdTargetsSpecFolder(cwd)) {
+        throw new Error(`Refusing to run git with cwd inside a planu/specs folder (cwd: ${cwd}). Git commands must target the project root, never a spec folder.`);
+    }
+}
+//# sourceMappingURL=git-command-guard.js.map

package/dist/engine/git/planu-autocommit.js

@@ -2,11 +2,13 @@
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runAbortableProcess } from '../abortable-process-runner.js';
+import { assertSafeGitInvocation } from './git-command-guard.js';
 export function isPlanuAutocommitEnabled() {
     return process.env.PLANU_ENABLE_AUTOCOMMIT === 'true';
 }
 /** Run git through the request-aware process-group supervisor. */
 async function runGit(cwd, args) {
+    assertSafeGitInvocation(cwd, args);
     const result = await runAbortableProcess('git', args, {
         cwd,
         maxBufferBytes: 1024 * 1024,

package/dist/engine/handoff-packager.js

@@ -484,10 +484,46 @@ function extractLinesByKeywords(content, keywords) {
         .filter((line) => line.length > 0 && !/^#{1,6}\s/.test(line) && keywords.test(line));
     return [...new Set(lines)].slice(0, 12);
 }
+const LIST_ITEM_PATTERN = /^(?:[-*]|\d+\.)\s+(?:\[[ x]\]\s+)?(.+)$/;
+function sectionBullets(content, headingRegex) {
+    const lines = content.split('\n');
+    const bullets = [];
+    let inSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (headingRegex.test(trimmed)) {
+            inSection = true;
+            continue;
+        }
+        if (/^#{1,6}\s/.test(trimmed)) {
+            inSection = false;
+            continue;
+        }
+        if (!inSection) {
+            continue;
+        }
+        const match = LIST_ITEM_PATTERN.exec(trimmed);
+        if (match?.[1]) {
+            bullets.push(match[1].trim());
+        }
+    }
+    return bullets;
+}
+function dedupeMerge(primary, fallback) {
+    const seen = new Set();
+    const merged = [];
+    for (const item of [...primary, ...fallback]) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            merged.push(item);
+        }
+    }
+    return merged.slice(0, 12);
+}
 function extractOperationalSections(content, spec) {
     return {
-        testPlan: extractLinesByKeywords(content, /\b(test|typecheck|lint|vitest|playwright|verification|validate|pnpm|npm)\b/i),
-        risks: extractLinesByKeywords(content, /\b(risk|edge|failure|security|drift|migration|breaking|compatibility|rollback)\b/i),
+        testPlan: dedupeMerge(sectionBullets(content, /^#{2,6}\s*test plan\b/i), extractLinesByKeywords(content, /\b(test|typecheck|lint|vitest|playwright|verification|validate|pnpm|npm)\b/i)),
+        risks: dedupeMerge(sectionBullets(content, /^#{2,6}\s*risks?\b/i), extractLinesByKeywords(content, /\b(risk|edge|failure|security|drift|migration|breaking|compatibility|rollback)\b/i)),
         ownership: extractLinesByKeywords(content, /\b(owner|ownership|wave|agent|reviewer|arbiter|files?|responsible)\b/i),
         currentState: `Spec ${spec.id} is ${spec.status}; implementation must follow the approved spec artifact, not chat history.`,
         nextAction: lifecycleNextAction(spec.status),

package/dist/storage/project-identity.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { lstat, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { resolveStorageLayout } from './storage-layout.js';
-import { getCanonicalRoot, readLogicalProjectId } from './global-projects-store.js';
+import { addProject, getCanonicalRoot, getProjects, readLogicalProjectId, } from './global-projects-store.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 const IDENTITY_VERSION = 1;
@@ -205,37 +205,64 @@ function rejectsRootEscape(root, candidate) {
     const rel = relative(root, candidate);
     return rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel);
 }
-async function realpathClassified(path, notFoundCode) {
+async function realpathOr(path, onEnoent) {
     try {
         return await realpath(path);
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-            throw new PortablePathError(notFoundCode, `[Planu] path not found: ${notFoundCode}`);
+            return onEnoent();
         }
         throw error;
     }
 }
+async function realpathClassified(path, code) {
+    return realpathOr(path, () => {
+        throw new PortablePathError(code, `[Planu] path not found: ${code}`);
+    });
+}
+async function normalizePathBestEffort(path) {
+    return realpathOr(path, () => resolve(path));
+}
+/** Bounded self-heal: backfill logicalProjectId via {@link addProject} using the registry entry's own stored path when exactly one path matches. */
+async function healMissingLogicalProjectId(root) {
+    const normalizedRoot = await normalizePathBestEffort(root);
+    const projects = await getProjects();
+    const normalized = await Promise.all(projects.map((p) => normalizePathBestEffort(p.path)));
+    const matches = projects.filter((_, i) => normalized[i] === normalizedRoot);
+    const [match] = matches;
+    if (matches.length !== 1 || !match) {
+        return false;
+    }
+    await addProject(match.path);
+    return true;
+}
 /**
- * Reject a candidate root that carries a tracked logical project identity but
- * is not the single registry-confirmed canonical root for it — a checkout
- * left over from a rename/fork, or an ambiguous/unregistered project never
- * resolves specs against an arbitrary directory. A candidate with no tracked
- * identity (`planu/project.json` absent) is untracked, not unverified, and
- * passes through unchanged — as does an ephemeral checkout (test fixture,
- * scratch clone), since the global registry deliberately excludes those
- * (SPEC-581) and can never confirm a root for them.
+ * Verify a candidate root with a tracked identity against the single
+ * registry-confirmed canonical root for it, fails closed on a fork/rename
+ * checkout. An untracked or ephemeral candidate passes through unchanged
+ * (SPEC-581) and skips the heal below. On a zero-match registry entry that
+ * predates `logicalProjectId`, self-heals once via {@link healMissingLogicalProjectId}
+ * before failing closed.
  */
-async function rejectsUnverifiedRoot(root) {
+async function verifyCanonicalRoot(root) {
     if (isEphemeralProject(root)) {
-        return false;
+        return undefined;
     }
     const logicalProjectId = await readLogicalProjectId(root);
     if (logicalProjectId === undefined) {
-        return false;
+        return undefined;
+    }
+    let canonical = await getCanonicalRoot(logicalProjectId);
+    if (!canonical.ok && canonical.reason === 'zero' && (await healMissingLogicalProjectId(root))) {
+        canonical = await getCanonicalRoot(logicalProjectId);
     }
-    const canonical = await getCanonicalRoot(logicalProjectId);
-    return !canonical.ok || resolve(canonical.root) !== root;
+    if (canonical.ok) {
+        return (await normalizePathBestEffort(canonical.root)) === (await normalizePathBestEffort(root))
+            ? undefined
+            : { reason: 'mismatch', roots: [canonical.root] };
+    }
+    return { reason: canonical.reason, roots: canonical.roots };
 }
 /**
  * Resolve a stored `specPath`/`technicalPath` value against the verified canonical
@@ -281,8 +308,12 @@ export async function resolvePortableSpecPath(specId, storedPath, canonicalRoot)
  * Delegates to {@link resolvePortableSpecPath} once verified.
  */
 export async function resolveVerifiedSpecPath(specId, storedPath, canonicalRoot) {
-    if (await rejectsUnverifiedRoot(resolve(canonicalRoot))) {
-        throw new PortablePathError('ROOT_UNVERIFIED', '[Planu] canonical root is not the single registry-confirmed root for this project');
+    const root = resolve(canonicalRoot);
+    const failure = await verifyCanonicalRoot(root);
+    if (failure) {
+        const registered = failure.roots.length > 0 ? `, registered=[${failure.roots.join(', ')}]` : '';
+        throw new PortablePathError('ROOT_UNVERIFIED', `[Planu] canonical root is not the single registry-confirmed root for this project ` +
+            `(reason=${failure.reason}, candidate=${root}${registered}) — run init_project on the canonical checkout`);
     }
     return resolvePortableSpecPath(specId, storedPath, canonicalRoot);
 }

package/dist/tools/git/git-helpers.js

@@ -1,5 +1,6 @@
 import { knowledgeStore } from '../../storage/index.js';
 import { runAbortableProcess } from '../../engine/abortable-process-runner.js';
+import { assertSafeGitInvocation } from '../../engine/git/git-command-guard.js';
 /** Default branch prefixes by spec type. */
 export const DEFAULT_BRANCH_PREFIXES = {
     feature: 'feat',
@@ -15,6 +16,7 @@ export const DEFAULT_PROTECTED_BRANCHES = ['main', 'master', 'develop', 'product
 export const DEFAULT_STALENESS_THRESHOLD = 50;
 /** Execute a git command in the project directory. */
 export async function git(projectPath, args, options = {}) {
+    assertSafeGitInvocation(projectPath, args);
     try {
         const result = await runAbortableProcess('git', args, {
             cwd: projectPath,

package/dist/tools/init-project/handler.js

@@ -21,7 +21,8 @@ import { regeneratePages } from '../../engine/doc-generator/portal/index.js';
 import { detectStackPatterns } from './stack-detector.js';
 import { buildProjectConfig } from './config-builder.js';
 import { runSpecMigrations, listProjectSpecs } from './migration-runner.js';
-import { reconcilePortableSpecIndex } from './portable-index-reconciler.js';
+import { reconcilePortableSpecIndex, describeReconciliationOutcome, } from './portable-index-reconciler.js';
+import { refreshCoreHostAssets } from './host-assets-writer.js';
 import { runScaffoldWriter } from './scaffold-writer.js';
 import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseline, runConventionScanSafe, fireTelemetry, } from './lifecycle-helpers.js';
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
@@ -215,23 +216,24 @@ export async function handleInitProject(params, server) {
             const authorizedMigrations = params.authorizedMigrations ?? [];
             if (isUpdate && authorizedMigrations.length === 0) {
                 const reconciliation = await reconcilePortableSpecIndex(projectPath, projectId);
+                const repositoryFilesChanged = reconciliation.failures.length === 0 ? await refreshCoreHostAssets(projectPath) : [];
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: reconciliation.failures.length === 0
-                                ? 'Project already initialized. Safe update reconciled the portable spec index without changing repository files.'
-                                : `Portable spec index reconciliation failed for ${String(reconciliation.failures.length)} contract(s).`,
+                            text: describeReconciliationOutcome(reconciliation, repositoryFilesChanged),
                         },
                     ],
                     structuredContent: {
                         projectId,
                         ...(reconciliation.failures.length === 0 ? { projectPath } : {}),
                         isUpdate: true,
-                        repositoryFilesChanged: [],
+                        repositoryFilesChanged,
                         authorizedMigrations: [],
                         importedSpecIds: reconciliation.importedSpecIds,
                         failures: reconciliation.failures,
+                        skippedLegacy: reconciliation.skippedLegacy,
+                        strayRepoRemovals: reconciliation.strayRepoRemovals,
                     },
                     ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
                 };

package/dist/tools/init-project/host-assets-writer.d.ts

@@ -17,5 +17,18 @@ export interface InitHostAssetsResult {
  * host configs that should stay in sync too.
  */
 export declare function detectInitAssetHosts(projectPath: string): Promise<InitAssetHost[]>;
+/** Whether `host` already has an on-disk asset surface in `projectPath` (SPEC-1677). */
+export declare function hasCoreSkillSurface(projectPath: string, host: HostId): Promise<boolean>;
+export declare function installCoreSkillsForHost(projectPath: string, host: HostId): Promise<{
+    host: HostId;
+    name: string;
+    path: string;
+}[]>;
 export declare function installInitHostAssets(projectPath: string, _knowledge: ProjectKnowledge, installSkills?: boolean): Promise<InitHostAssetsResult>;
+/**
+ * SPEC-1677: refresh Planu-owned core skills on the init_project safe-update path,
+ * restricted to detected hosts whose asset surface already exists on disk. Returns
+ * project-relative paths of every file whose content actually changed.
+ */
+export declare function refreshCoreHostAssets(projectPath: string): Promise<string[]>;
 //# sourceMappingURL=host-assets-writer.d.ts.map

package/dist/tools/init-project/host-assets-writer.js

@@ -1,6 +1,6 @@
 // tools/init-project/host-assets-writer.ts — Host-aware rules/skills installed by init_project
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { handleCreateSkill } from '../create-skill.js';
 import { fileExists } from '../../core/shared/fs.js';
@@ -119,7 +119,25 @@ async function canRefreshCoreSkill(projectPath, host, name) {
         return true;
     }
 }
-async function installCoreSkillsForHost(projectPath, host) {
+/** Whether `host` already has an on-disk asset surface in `projectPath` (SPEC-1677). */
+export async function hasCoreSkillSurface(projectPath, host) {
+    if (host === 'codex') {
+        return fileExists(join(projectPath, 'AGENTS.md'));
+    }
+    if (host === 'gemini') {
+        return fileExists(join(projectPath, '.gemini'));
+    }
+    return fileExists(join(projectPath, '.claude'));
+}
+async function readTargetContent(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function installCoreSkillsForHost(projectPath, host) {
     const installed = [];
     for (const fileName of CORE_SKILL_TEMPLATES) {
         const template = await readCoreSkillTemplate(fileName);
@@ -129,6 +147,8 @@ async function installCoreSkillsForHost(projectPath, host) {
         if (!(await canRefreshCoreSkill(projectPath, host, template.name))) {
             continue;
         }
+        const targetPath = coreSkillPath(projectPath, host, template.name);
+        const before = await readTargetContent(targetPath);
         const result = await handleCreateSkill({
             projectPath,
             host,
@@ -145,11 +165,11 @@ async function installCoreSkillsForHost(projectPath, host) {
             'skillFilePath' in result.structuredContent &&
             typeof result.structuredContent.skillFilePath === 'string'
             ? result.structuredContent.skillFilePath
-            : host === 'codex'
-                ? join(projectPath, 'AGENTS.md')
-                : host === 'gemini'
-                    ? join(projectPath, '.gemini', 'skills', `${template.name}.md`)
-                    : join(projectPath, '.claude', 'skills', template.name, 'SKILL.md');
+            : targetPath;
+        const after = await readTargetContent(path);
+        if (after === before) {
+            continue;
+        }
         installed.push({ host, name: template.name, path });
     }
     return installed;
@@ -195,4 +215,28 @@ export async function installInitHostAssets(projectPath, _knowledge, installSkil
     }
     return { detectedHosts, rulesInstalled, skillsInstalled, opencodeConfigured };
 }
+const CORE_SKILL_HOST_IDS = ['claude-code', 'codex', 'gemini'];
+function isCoreSkillHost(host) {
+    return CORE_SKILL_HOST_IDS.includes(host);
+}
+/**
+ * SPEC-1677: refresh Planu-owned core skills on the init_project safe-update path,
+ * restricted to detected hosts whose asset surface already exists on disk. Returns
+ * project-relative paths of every file whose content actually changed.
+ */
+export async function refreshCoreHostAssets(projectPath) {
+    const detectedHosts = await detectInitAssetHosts(projectPath);
+    const coreSkillHosts = detectedHosts.filter(isCoreSkillHost);
+    const changed = [];
+    for (const host of coreSkillHosts) {
+        if (!(await hasCoreSkillSurface(projectPath, host))) {
+            continue;
+        }
+        const installed = await installCoreSkillsForHost(projectPath, host);
+        for (const skill of installed) {
+            changed.push(relative(projectPath, skill.path));
+        }
+    }
+    return [...new Set(changed)];
+}
 //# sourceMappingURL=host-assets-writer.js.map

package/dist/tools/init-project/portable-index-reconciler.d.ts

@@ -1,4 +1,10 @@
-import type { FilesystemImportDeps, PortableIndexReconciliationResult } from '../../types/index.js';
+import type { FilesystemImportDeps, FilesystemImportFailure, PortableIndexReconciliationResult, SkippedLegacyContract } from '../../types/index.js';
+/** Autopilot-first summary of fatal reconciliation failures: what failed, why, and the next action. */
+export declare function describeReconciliationFailures(failures: FilesystemImportFailure[]): string;
+/** Autopilot-first summary of a successful reconciliation, including any legacy skips. */
+export declare function describeReconciliationSuccess(repositoryFilesChanged: string[], skippedLegacy: SkippedLegacyContract[], strayRepoRemovals?: string[]): string;
+/** Autopilot-first message for a reconciliation outcome, success or fatal-failure. */
+export declare function describeReconciliationOutcome(reconciliation: PortableIndexReconciliationResult, repositoryFilesChanged: string[]): string;
 /** Rebuild the mutable external index from the repository-owned portable contracts. */
 export declare function reconcilePortableSpecIndex(projectPath: string, projectId: string, deps?: FilesystemImportDeps): Promise<PortableIndexReconciliationResult>;
 //# sourceMappingURL=portable-index-reconciler.d.ts.map

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

@@ -1,5 +1,161 @@
+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 = [];
+    const LEGACY_SKIPPABLE_CODES = new Set([
+        'INVALID_CONTRACT',
+        'INCOMPATIBLE_IDENTITY',
+    ]);
+    for (const failure of failures) {
+        if (indexedSpecIds.has(failure.specId) && LEGACY_SKIPPABLE_CODES.has(failure.code)) {
+            skippedLegacy.push({
+                ...failure,
+                reason: `${failure.specId} is already indexed; the on-disk contract is a historic mismatch left as-is.`,
+            });
+            continue;
+        }
+        remainingFailures.push(failure);
+    }
+    return { failures: remainingFailures, skippedLegacy };
+}
+const NEXT_ACTION_BY_CODE = {
+    READ_FAILED: 'fix file permissions or contents so spec.md can be read',
+    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) {
+    const counts = new Map();
+    for (const failure of failures) {
+        counts.set(failure.code, (counts.get(failure.code) ?? 0) + 1);
+    }
+    const codeSummary = [...counts.entries()]
+        .map(([code, count]) => `${String(count)} ${code}`)
+        .join(', ');
+    const topPaths = failures
+        .slice(0, 3)
+        .map((failure) => failure.path)
+        .join(', ');
+    const remainder = failures.length > 3 ? ', …' : '';
+    const nextActions = [...counts.keys()].map((code) => NEXT_ACTION_BY_CODE[code]).join('; ');
+    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, 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).`;
+    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, reconciliation.strayRepoRemovals)
+        : describeReconciliationFailures(reconciliation.failures);
+}
 /** Rebuild the mutable external index from the repository-owned portable contracts. */
 export async function reconcilePortableSpecIndex(projectPath, projectId, deps = {
     listSpecs: specStore.listSpecs,
@@ -10,6 +166,15 @@ export async function reconcilePortableSpecIndex(projectPath, projectId, deps =
     const result = await importFilesystemSpecs(projectPath, deps, projectId, {
         strictPortableContract: true,
     });
-    return { ...result, repositoryFilesChanged: [] };
+    const indexedSpecIds = new Set((await deps.listSpecs(projectId)).map((spec) => spec.id));
+    const { failures, skippedLegacy } = classifyFailures(result.failures, indexedSpecIds);
+    const { removals: strayRepoRemovals, failures: strayRepoFailures } = await healStraySpecRepos(projectPath);
+    return {
+        ...result,
+        failures: [...failures, ...strayRepoFailures],
+        skippedLegacy,
+        repositoryFilesChanged: [],
+        strayRepoRemovals,
+    };
 }
 //# sourceMappingURL=portable-index-reconciler.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;
@@ -233,8 +233,16 @@ export interface FilesystemImportDeps {
     getSpecFresh?: (projectId: string, specId: string) => Promise<Spec | null>;
     getGlobalConfig?: () => Promise<Partial<GlobalConfig>>;
 }
+export interface SkippedLegacyContract {
+    specId: string;
+    path: string;
+    code: FilesystemImportFailureCode;
+    reason: string;
+}
 export interface PortableIndexReconciliationResult extends FilesystemImportResult {
     repositoryFilesChanged: string[];
+    skippedLegacy: SkippedLegacyContract[];
+    strayRepoRemovals: string[];
 }
 export interface ImportEntryContext {
     projectPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.4.1",
+  "version": "5.5.3",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",
@@ -40,11 +40,11 @@
     "lint:gate": "eslint src/ tests/ --max-warnings 0",
     "lint:fix": "eslint src/ tests/ --fix --max-warnings 0",
     "format": "prettier --write 'src/**/*.ts' 'tests/**/*.test.ts'",
-    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.test.ts'",
+    "format:check": "prettier --check --cache --cache-strategy content 'src/**/*.ts' 'tests/**/*.test.ts'",
     "typecheck": "tsc --noEmit",
     "typecheck:compat": "tsc6 --noEmit",
     "verify:typescript-migration": "node scripts/verify-typescript-migration.mjs",
-    "test": "vitest run",
+    "test": "vitest run --maxWorkers=6",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage --testTimeout=60000 --maxWorkers=4",
     "test:release-gate": "vitest run --exclude 'tests/integration/**'",

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.4.1",
+  "version": "5.5.3",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",