@planu/cli 5.5.0 → 5.5.3

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [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

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"2c3e47edf445a0c8422cbeec33a6a929edd764b5"}
+{"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/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

@@ -233,6 +233,7 @@ export async function handleInitProject(params, server) {
                         importedSpecIds: reconciliation.importedSpecIds,
                         failures: reconciliation.failures,
                         skippedLegacy: reconciliation.skippedLegacy,
+                        strayRepoRemovals: reconciliation.strayRepoRemovals,
                     },
                     ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
                 };

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

@@ -2,7 +2,7 @@ import type { FilesystemImportDeps, FilesystemImportFailure, PortableIndexReconc
 /** 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[]): string;
+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. */

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.5.0",
+  "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",

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