@planu/cli 5.3.14 → 5.3.15

package/dist/tools/init-project/git-setup.js

@@ -59,35 +59,19 @@ export async function runGitSetup(projectPath, projectId) {
     // Auto-configure .gitignore (best-effort)
     const gitignoreUpdated = await configureGitignore(projectPath);
     // SPEC-646: Remove planu/*.html from git tracking — they are regenerable, not source files
-    if (gitRepoDetected) {
-        await untrackHtmlFiles(projectPath);
-    }
-    return { hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected };
+    const layoutOffenders = gitRepoDetected ? await untrackHtmlFiles(projectPath) : [];
+    return { hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, layoutOffenders };
 }
 /** SPEC-646: Delete legacy planu/*.html files from disk and remove from git index.
  *  These files are regenerable — committing them wastes ≥1MB per repo clone. */
 async function untrackHtmlFiles(projectPath) {
     const htmlFiles = ['planu/index.html', 'planu/roadmap.html'];
-    // Remove from git index if tracked (best-effort)
     try {
         const { stdout } = await git(projectPath, ['ls-files', ...htmlFiles]);
-        const tracked = stdout.trim().split('\n').filter(Boolean);
-        if (tracked.length > 0) {
-            await git(projectPath, ['rm', '--force', ...tracked]);
-        }
+        return stdout.trim().split('\n').filter(Boolean);
     }
     catch {
-        /* not a git repo or files not tracked */
-    }
-    // Also delete any remaining files from disk (e.g. not tracked but still present)
-    for (const rel of htmlFiles) {
-        try {
-            const { unlink } = await import('node:fs/promises');
-            await unlink(join(projectPath, rel));
-        }
-        catch {
-            /* file doesn't exist or can't be deleted — skip */
-        }
+        return [];
     }
 }
 /** SPEC-466: Also exported for list_specs auto-cleanup. */
@@ -95,11 +79,11 @@ export async function configureGitignoreForPlanu(projectPath) {
     return configureGitignore(projectPath);
 }
 async function configureGitignore(projectPath) {
-    const gitignorePath = join(projectPath, '.gitignore');
+    const targetPath = join(projectPath, '.gitignore');
     try {
         let gitignoreContent = '';
         try {
-            gitignoreContent = await readFile(gitignorePath, 'utf-8');
+            gitignoreContent = await readFile(targetPath, 'utf-8');
         }
         catch {
             /* file doesn't exist */
@@ -145,7 +129,7 @@ async function configureGitignore(projectPath) {
             const addition = linesToAdd.length > 0
                 ? `${separator}# Planu (auto-configured)\n${linesToAdd.join('\n')}\n`
                 : '';
-            await writeFile(gitignorePath, gitignoreContent + addition, 'utf-8');
+            await writeFile(targetPath, gitignoreContent + addition, 'utf-8');
             updated = true;
         }
         return updated;

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

@@ -428,7 +428,7 @@ export async function handleInitProject(params, server) {
             const { skillsAutoInstalled, skillsPendingInstall, skillsSkipped } = await orchestrateSkillInstalls(recommendedSkills, projectPath, autoInstallFromConfig);
             // Write scaffold files: rules, git setup, constitution, CLAUDE.md, lint, architecture rules
             const scaffoldResult = await runScaffoldWriter(projectPath, projectId, knowledge, recommendedSkills, params.permissionsMode, params.pluginsMode, autoInstallFromConfig);
-            const { platform, generatedRules, rulesWritten, additionalFilesWritten, hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, constitutionInitialized, claudeMdUpdated, eslintCreated, prettierCreated, lintSuggestions, architectureRulesWritten, architectureRulesSkipped, planuWorkflowInjected, planuHooksConfigured, planuRulesWritten, gitAutoStageInjected, } = scaffoldResult;
+            const { platform, generatedRules, rulesWritten, additionalFilesWritten, hooksInstalled, gitFlowType, gitignoreUpdated, gitRepoDetected, layoutOffenders, constitutionInitialized, claudeMdUpdated, eslintCreated, prettierCreated, lintSuggestions, architectureRulesWritten, architectureRulesSkipped, planuWorkflowInjected, planuHooksConfigured, planuRulesWritten, gitAutoStageInjected, } = scaffoldResult;
             // SPEC-444: Inject proactive behavior rules into project CLAUDE.md
             const proactiveRulesInjected = await injectProactiveRules(join(projectPath, 'CLAUDE.md'), '1.22.0')
                 .then(() => true)
@@ -545,6 +545,9 @@ export async function handleInitProject(params, server) {
             if (gitignoreUpdated) {
                 collector.pushOk('gitignore', 'Updated .gitignore with planu/ and project rules');
             }
+            if (layoutOffenders.length > 0) {
+                collector.pushOk('planu-layout-offenders', layoutOffenders.join(', '));
+            }
             if (skillsAutoInstalled.length > 0) {
                 collector.pushOk('skills-installed', `Auto-installed skills: ${skillsAutoInstalled.join(', ')}`);
             }

package/dist/tools/init-project/migration-runner.js

@@ -166,7 +166,14 @@ export async function runSpecMigrations(projectPath, projectId, knowledge, optio
     // SPEC-1017: strict managed planu/ cleanup after all legacy migrations.
     try {
         const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
-        await runStrictPlanuCleanup(projectPath);
+        const cleanup = await runStrictPlanuCleanup(projectPath);
+        for (const path of cleanup.proposed) {
+            criticalMigrationFailures.push({
+                phase: 'strict-planu-validate',
+                severity: 'critical',
+                message: `Non-canonical planu path requires manual review: ${path}`,
+            });
+        }
     }
     catch (err) {
         criticalMigrationFailures.push(issueFromError('strict-planu-cleanup', 'critical', err));

package/dist/tools/init-project/scaffold-writer.d.ts

@@ -11,6 +11,7 @@ export interface ScaffoldWriteResult {
     gitFlowType: string;
     gitignoreUpdated: boolean;
     gitRepoDetected: boolean;
+    layoutOffenders: string[];
     constitutionInitialized: boolean;
     claudeMdUpdated: boolean;
     eslintCreated: boolean;

package/dist/tools/init-project/scaffold-writer.js

@@ -383,6 +383,7 @@ export async function runScaffoldWriter(projectPath, projectId, knowledge, recom
         gitFlowType: gitResult.gitFlowType,
         gitignoreUpdated: gitResult.gitignoreUpdated,
         gitRepoDetected: gitResult.gitRepoDetected,
+        layoutOffenders: gitResult.layoutOffenders,
         constitutionInitialized,
         claudeMdUpdated,
         eslintCreated,

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

@@ -150,7 +150,7 @@ export async function handleUpdateStatusBatch(input) {
             updated,
             skipped,
             failed,
-            sideEffectsFlushed: ['strict-planu-cleanup'],
+            sideEffectsFlushed: ['strict-planu-validate'],
             ...(aggregatedNextAction ? { nextAction: aggregatedNextAction } : {}),
         },
     };

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

@@ -1446,6 +1446,7 @@ export async function handleUpdateStatus(params, server) {
                         if (doneActions?.prSuggestion) {
                             collector.pushOk('pr-created', doneActions.prSuggestion.title);
                         }
+                        collector.pushOk('housekeeping', 'Housekeeping: pending cleanup proposals — run housekeeping_sweep to review');
                     }
                     if (newStatus === 'approved' && versionSnapshotTag) {
                         collector.pushOk('version-snapshot', `Snapshot queued: ${versionSnapshotTag}`);

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

@@ -1,4 +1,4 @@
-import type { ConstitutionViolation } from '../types/index.js';
+import type { ConstitutionViolation, DoneSideEffectsReport } from '../types/index.js';
 export declare function runImplementingActions(projectId: string, specId: string, options?: {
     deferSideEffects?: boolean;
     projectPath?: string;
@@ -24,7 +24,7 @@ export declare function runDoneActions(projectId: string, specId: string, gitBra
     autopilotSummary: string[];
 }>;
 /** Run cleanup and state refreshes only after the done transition is durable. */
-export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined, transitionProjectPath?: string): Promise<void>;
+export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined, transitionProjectPath?: string): Promise<DoneSideEffectsReport>;
 /**
  * Best-effort constitution compliance check for status transitions.
  * Returns warnings (never blocks the transition).

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

@@ -241,7 +241,7 @@ export async function runDoneSideEffects(projectId, specId, gitBranch, transitio
     const results = await Promise.allSettled([
         (async () => {
             const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');
-            await withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch));
+            return withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch));
         })(),
         (async () => {
             const { removeSpecFromSession } = await import('../engine/session-state/writer.js');
@@ -259,11 +259,11 @@ export async function runDoneSideEffects(projectId, specId, gitBranch, transitio
         (async () => {
             const { join } = await import('node:path');
             const { cleanPlanuRoot } = await import('../engine/spec-migrator/planu-root-cleaner.js');
-            await cleanPlanuRoot(join(projectPath, 'planu'));
+            return cleanPlanuRoot(join(projectPath, 'planu'));
         })(),
         (async () => {
             const { runHousekeepingSweep } = await import('../engine/housekeeping/index.js');
-            await runHousekeepingSweep({ projectPath, dryRun: false });
+            return runHousekeepingSweep({ projectPath });
         })(),
         (async () => {
             if (hasPending(specId, 'generateSessionContext')) {
@@ -278,18 +278,28 @@ export async function runDoneSideEffects(projectId, specId, gitBranch, transitio
                 clearPending(specId, 'generateSessionContext');
             }
         })(),
-        (async () => {
-            const { glob } = await import('glob');
-            const { unlink } = await import('node:fs/promises');
-            const specFiles = await glob(`planu/specs/${specId}-*/prompt.md`, { cwd: projectPath, absolute: true });
-            const exactFiles = await glob(`planu/specs/${specId}/prompt.md`, { cwd: projectPath, absolute: true });
-            await Promise.allSettled([...specFiles, ...exactFiles].map((file) => unlink(file)));
-        })(),
     ]);
     const failures = results.filter((result) => result.status === 'rejected');
     if (failures.length > 0) {
         throw new AggregateError(normalizeRejectedReasons(failures), `${String(failures.length)} done side effect(s) failed`);
     }
+    const cleanup = results[0].status === 'fulfilled' ? results[0].value : null;
+    const planuCleanup = results[4].status === 'fulfilled' ? results[4].value : null;
+    const housekeeping = results[5].status === 'fulfilled' ? results[5].value : null;
+    return {
+        cleanupProposals: cleanup?.proposals ?? [],
+        housekeepingProposal: housekeeping ?? {
+            mode: 'report',
+            sweepAt: new Date().toISOString(),
+            projectPath,
+            wouldDelete: { branches: [], worktrees: [], stashes: [] },
+            kept: { branches: [] },
+            executed: false,
+            deleted: { branches: 0, worktrees: 0, stashes: 0, backups: 0 },
+            errors: [],
+        },
+        planuLayoutOffenders: planuCleanup?.proposed ?? [],
+    };
 }
 /**
  * Best-effort constitution compliance check for status transitions.

package/dist/types/git.d.ts

@@ -1,5 +1,6 @@
 import type { GitAction } from './common/index.js';
 import type { GeneratedDocument } from './docs.js';
+import type { HousekeepingReport } from './housekeeping.js';
 export interface GitConfig {
     branchPrefix?: Record<string, string>;
     commitFormat?: 'conventional' | 'spec-id' | 'custom';
@@ -173,12 +174,30 @@ export interface CleanupReport {
     message: string;
     autoCompleted?: string[];
 }
+export type CleanupProposalKind = 'worktree' | 'local-branch' | 'remote-branch';
+export type CleanupMergedState = 'merged' | 'not_merged' | 'unknown';
+export type CleanupSuggestedAction = 'delete' | 'keep' | 'inspect';
+export interface SpecDoneCleanupProposal {
+    kind: CleanupProposalKind;
+    ref: string;
+    worktreeClean: boolean | null;
+    mergedState: CleanupMergedState;
+    reason: string;
+    suggestedAction: CleanupSuggestedAction;
+}
 export interface SpecDoneCleanupResult {
+    mode: 'report' | 'execute';
+    proposals: SpecDoneCleanupProposal[];
     worktreeRemoved: string | null;
     localBranchRemoved: string | null;
     remoteBranchRemoved: string | null;
     errors: string[];
 }
+export interface DoneSideEffectsReport {
+    cleanupProposals: SpecDoneCleanupProposal[];
+    housekeepingProposal: HousekeepingReport;
+    planuLayoutOffenders: string[];
+}
 export interface GitHubIssueImportResult {
     action: 'import-issue';
     specId: string;

package/dist/types/housekeeping.d.ts

@@ -36,7 +36,14 @@ export interface StaleStashInfo {
      */
     reason: 'age' | 'orphan-branch' | 'orphan-merged';
 }
+export type HousekeepingAuthority = {
+    mode: 'report';
+} | {
+    mode: 'execute';
+    deleteRemoteRefs: boolean;
+};
 export interface HousekeepingReport {
+    mode: 'report' | 'execute';
     /** ISO timestamp of when the sweep ran. */
     sweepAt: string;
     /** Project path that was analysed. */
@@ -61,6 +68,7 @@ export interface HousekeepingReport {
         /** SPEC-771: stale .bak.* files removed from planu/specs/. */
         backups: number;
     };
+    errors: string[];
 }
 export type OrphanMarkdownAction = 'deleted_matched' | 'imported_then_deleted' | 'skipped';
 export interface OrphanMarkdownEntry {
@@ -124,7 +132,7 @@ export interface FindStaleStashesInput {
 }
 export interface RunHousekeepingSweepInput {
     projectPath: string;
-    dryRun?: boolean;
+    authority?: HousekeepingAuthority;
     aggressive?: boolean;
     includeStashes?: boolean;
 }

package/dist/types/index.d.ts

@@ -141,6 +141,7 @@ export * from './red-team.js';
 export * from './update-notifier.js';
 export * from './batch-script.js';
 export * from './hooks-advanced.js';
+export * from './housekeeping.js';
 export * from './codex-integration.js';
 export * from './gemini-integration.js';
 export * from './ai-integration.js';

package/dist/types/index.js

@@ -138,6 +138,7 @@ export * from './red-team.js';
 export * from './update-notifier.js';
 export * from './batch-script.js';
 export * from './hooks-advanced.js';
+export * from './housekeeping.js';
 export * from './codex-integration.js';
 export * from './gemini-integration.js';
 export * from './ai-integration.js';

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

@@ -64,6 +64,7 @@ export interface CleanupResult {
     deletedRootFiles: string[];
     deletedSpecFiles: string[];
     totalDeleted: number;
+    proposed: string[];
 }
 export interface PlanuCanonicalPathPolicy {
     readonly canonicalRootFiles: readonly string[];
@@ -75,8 +76,10 @@ export interface PlanuCanonicalPathPolicy {
     readonly legacyMergeBeforeDeleteFiles: readonly string[];
 }
 export interface StrictPlanuCleanupResult {
+    mode: 'report' | 'execute';
     deleted: string[];
     merged: string[];
+    proposed: string[];
     gitignoreUpdated: boolean;
 }
 export interface StrictPlanuValidationResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.14",
+  "version": "5.3.15",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -35,14 +35,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "5.3.14",
-    "@planu/core-darwin-x64": "5.3.14",
-    "@planu/core-linux-arm64-gnu": "5.3.14",
-    "@planu/core-linux-arm64-musl": "5.3.14",
-    "@planu/core-linux-x64-gnu": "5.3.14",
-    "@planu/core-linux-x64-musl": "5.3.14",
-    "@planu/core-win32-arm64-msvc": "5.3.14",
-    "@planu/core-win32-x64-msvc": "5.3.14"
+    "@planu/core-darwin-arm64": "5.3.15",
+    "@planu/core-darwin-x64": "5.3.15",
+    "@planu/core-linux-arm64-gnu": "5.3.15",
+    "@planu/core-linux-arm64-musl": "5.3.15",
+    "@planu/core-linux-x64-gnu": "5.3.15",
+    "@planu/core-linux-x64-musl": "5.3.15",
+    "@planu/core-win32-arm64-msvc": "5.3.15",
+    "@planu/core-win32-x64-msvc": "5.3.15"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -86,7 +86,8 @@
     "native:project-graph:e2e": "PLANU_NATIVE_E2E=1 vitest run tests/integration/native-project-graph-e2e.test.ts",
     "native:project-graph:benchmark": "node scripts/benchmark-native-performance.mjs --operation project_graph_query --samples 30 --warmups 5 --project-path . --spec-id SPEC-1119 --json",
     "benchmark:execution-kernel": "pnpm build && node scripts/benchmark-execution-kernel.mjs",
-    "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm check:release-authorities && pnpm check:commercial-surfaces && pnpm check:tool-registration && pnpm check:public-privacy && pnpm check:website-proof && pnpm check:donation-assets && pnpm check:website-public-assets",
+    "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm check:destructive-ops && pnpm check:release-authorities && pnpm check:commercial-surfaces && pnpm check:tool-registration && pnpm check:public-privacy && pnpm check:website-proof && pnpm check:donation-assets && pnpm check:website-public-assets",
+    "check:destructive-ops": "bash scripts/check-no-automatic-destructive-ops.sh",
     "check:strict": "pnpm check && pnpm generate:host-tool-registry -- --check && pnpm check:native-version-parity && pnpm check:environment-schema && pnpm audit:hardcodes && pnpm audit:deadcode && pnpm audit:circular && pnpm audit:types && pnpm audit:security && pnpm audit:i18n",
     "check:reliability": "node scripts/check-reliability-policies.mjs",
     "check:environment-schema": "node scripts/check-environment-schema.mjs",

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "5.3.14",
+  "version": "5.3.15",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

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