@planu/cli 5.3.13 → 5.3.15

package/dist/tools/git/cleanup-ops.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { git, resolveProjectPath } from './git-helpers.js';
+import { runAbortableProcess } from '../../engine/abortable-process-runner.js';
 import { compactResult, compactError } from '../output-formatter.js';
 const WORKTREES_DIR = '.claude/worktrees';
 const STALE_DAYS_THRESHOLD = 7;
@@ -48,9 +49,9 @@ async function getMergedBranches(projectPath) {
     return new Set();
 }
 /** Remove a worktree — idempotent (ignores "not a worktree" errors). */
-async function removeWorktree(projectPath, worktreePath) {
+async function removeWorktree(projectPath, worktreePath, force) {
     try {
-        await git(projectPath, ['worktree', 'remove', '--force', worktreePath]);
+        await git(projectPath, ['worktree', 'remove', ...(force ? ['--force'] : []), worktreePath]);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -97,7 +98,7 @@ async function cleanupOrphanWorktrees(projectPath, mergedBranches) {
                 continue;
             }
             try {
-                await removeWorktree(projectPath, wt.path);
+                await removeWorktree(projectPath, wt.path, true);
                 removed.push(wt.path);
             }
             catch (err) {
@@ -337,85 +338,149 @@ async function findSpecWorktree(projectPath, specId) {
  * AC-01: When a spec is marked done, clean its worktree, local branch, and remote branch.
  * Best-effort — never throws. Caller should fire-and-forget or log result.
  */
-export async function cleanupSpecOnDone(projectPath, specId, gitBranch) {
+export async function cleanupSpecOnDone(projectPath, specId, gitBranch, authority = { mode: 'report' }) {
     const result = {
+        mode: authority.mode,
+        proposals: [],
         worktreeRemoved: null,
         localBranchRemoved: null,
         remoteBranchRemoved: null,
         errors: [],
     };
-    // 1. Remove worktree if it exists
     const worktreePath = await findSpecWorktree(projectPath, specId);
+    const mergedState = gitBranch ? await getBranchMergedState(projectPath, gitBranch) : 'unknown';
+    if (worktreePath) {
+        const worktreeClean = await isWorktreeClean(worktreePath);
+        result.proposals.push({
+            kind: 'worktree',
+            ref: worktreePath,
+            worktreeClean,
+            mergedState,
+            reason: `spec ${specId} is done`,
+            suggestedAction: worktreeClean ? 'delete' : 'inspect',
+        });
+    }
+    if (gitBranch) {
+        const currentBranch = await getCurrentBranch(projectPath);
+        const suggestedAction = mergedState === 'merged' && currentBranch !== gitBranch ? 'delete' : 'keep';
+        result.proposals.push({
+            kind: 'local-branch',
+            ref: gitBranch,
+            worktreeClean: null,
+            mergedState,
+            reason: `spec ${specId} is done`,
+            suggestedAction,
+        });
+        if (await remoteBranchExists(projectPath, gitBranch)) {
+            result.proposals.push({
+                kind: 'remote-branch',
+                ref: `origin/${gitBranch}`,
+                worktreeClean: null,
+                mergedState,
+                reason: `spec ${specId} is done`,
+                suggestedAction: mergedState === 'merged' ? 'delete' : 'keep',
+            });
+        }
+    }
+    if (authority.mode === 'report') {
+        return result;
+    }
     if (worktreePath) {
         try {
-            await removeWorktree(projectPath, worktreePath);
+            await removeWorktree(projectPath, worktreePath, false);
             result.worktreeRemoved = worktreePath;
         }
         catch (err) {
             result.errors.push(`worktree: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    if (!gitBranch) {
+    if (!gitBranch || mergedState !== 'merged') {
         return result;
     }
-    // 2. Remove local branch if merged
-    try {
-        const { stdout } = await git(projectPath, ['branch', '--merged', 'develop']);
-        const merged = new Set(stdout
-            .split('\n')
-            .map((b) => b.replace(/^\*?\s+/, '').trim())
-            .filter(Boolean));
-        const isMerged = merged.has(gitBranch);
-        // Also check main as fallback
-        let isMergedMain = false;
-        if (!isMerged) {
-            try {
-                const { stdout: mainOut } = await git(projectPath, ['branch', '--merged', 'main']);
-                const mergedMain = new Set(mainOut
-                    .split('\n')
-                    .map((b) => b.replace(/^\*?\s+/, '').trim())
-                    .filter(Boolean));
-                isMergedMain = mergedMain.has(gitBranch);
-            }
-            catch {
-                // ignore
-            }
+    if ((await getCurrentBranch(projectPath)) !== gitBranch) {
+        try {
+            await git(projectPath, ['branch', '-d', gitBranch]);
+            result.localBranchRemoved = gitBranch;
         }
-        if (isMerged || isMergedMain) {
-            // Never delete current branch
-            const { stdout: headOut } = await git(projectPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
-            if (headOut.trim() !== gitBranch) {
-                try {
-                    await git(projectPath, ['branch', '-d', gitBranch]);
-                    result.localBranchRemoved = gitBranch;
-                }
-                catch {
-                    // Force-delete if needed
-                    try {
-                        await git(projectPath, ['branch', '-D', gitBranch]);
-                        result.localBranchRemoved = gitBranch;
-                    }
-                    catch (err) {
-                        result.errors.push(`local branch: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-            }
+        catch (err) {
+            result.errors.push(`local branch: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    catch (err) {
-        result.errors.push(`merged check: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // 3. Remove remote branch if it exists
-    try {
-        const { stdout } = await git(projectPath, ['ls-remote', '--heads', 'origin', gitBranch]);
-        if (stdout.trim()) {
+    if (authority.deleteRemoteRefs && (await remoteBranchExists(projectPath, gitBranch))) {
+        try {
             await git(projectPath, ['push', 'origin', '--delete', gitBranch]);
             result.remoteBranchRemoved = `origin/${gitBranch}`;
         }
-    }
-    catch (err) {
-        result.errors.push(`remote branch: ${err instanceof Error ? err.message : String(err)}`);
+        catch (err) {
+            result.errors.push(`remote branch: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     return result;
 }
+async function isAncestorOf(projectPath, branch, base) {
+    try {
+        const result = await runAbortableProcess('git', ['merge-base', '--is-ancestor', branch, base], {
+            cwd: projectPath,
+            timeoutMs: 30_000,
+            maxBufferBytes: 1024 * 1024,
+        });
+        if (result.status === 0) {
+            return 'yes';
+        }
+        return result.status === 1 && !result.error ? 'no' : 'indeterminate';
+    }
+    catch {
+        return 'indeterminate';
+    }
+}
+async function getBranchMergedState(projectPath, branch) {
+    let sawNotMerged = false;
+    let indeterminate = false;
+    for (const base of ['main', 'develop', 'master']) {
+        try {
+            await git(projectPath, ['rev-parse', '--verify', base]);
+        }
+        catch {
+            continue;
+        }
+        const ancestry = await isAncestorOf(projectPath, branch, base);
+        if (ancestry === 'yes') {
+            return 'merged';
+        }
+        if (ancestry === 'no') {
+            sawNotMerged = true;
+        }
+        else {
+            indeterminate = true;
+        }
+    }
+    return sawNotMerged && !indeterminate ? 'not_merged' : 'unknown';
+}
+async function isWorktreeClean(worktreePath) {
+    try {
+        const { stdout } = await git(worktreePath, ['status', '--porcelain']);
+        return stdout.trim() === '';
+    }
+    catch {
+        return null;
+    }
+}
+async function getCurrentBranch(projectPath) {
+    try {
+        const { stdout } = await git(projectPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function remoteBranchExists(projectPath, branch) {
+    try {
+        const { stdout } = await git(projectPath, ['ls-remote', '--heads', 'origin', branch]);
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=cleanup-ops.js.map

package/dist/tools/github-release-handler.js

@@ -209,13 +209,12 @@ export async function handleCreateRelease(args, exec = defaultExec) {
         const { runHousekeepingSweep } = await import('../engine/housekeeping/index.js');
         const sweepReport = await runHousekeepingSweep({
             projectPath: releasePath,
-            dryRun: false,
             aggressive: false,
             includeStashes: false,
         });
-        if (sweepReport.deleted.branches > 0 || sweepReport.deleted.worktrees > 0) {
-            outputLines.push(`  Housekeeping: deleted ${String(sweepReport.deleted.branches)} branch(es), ` +
-                `${String(sweepReport.deleted.worktrees)} worktree(s)`);
+        if (sweepReport.wouldDelete.branches.length > 0 ||
+            sweepReport.wouldDelete.worktrees.length > 0) {
+            outputLines.push(`  Housekeeping: ${String(sweepReport.wouldDelete.branches.length)} branch(es), ${String(sweepReport.wouldDelete.worktrees.length)} worktree(s) proposed — run housekeeping_sweep`);
         }
     }
     catch {
@@ -247,14 +246,6 @@ export async function handleCreateRelease(args, exec = defaultExec) {
                 validateScore: null,
                 allSpecs,
             }, { disabledByConfig: new Set(), disabledByEnv: new Set() });
-            // SPEC-790: Auto-trigger housekeeping_sweep after release to clean branches/worktrees
-            try {
-                const { runHousekeepingSweep } = await import('../engine/housekeeping/index.js');
-                void runHousekeepingSweep({ projectPath: releasePath, dryRun: false });
-            }
-            catch {
-                /* best-effort — housekeeping never blocks the release */
-            }
         }
         catch {
             /* best-effort — release_completed cascade never blocks the release response */

package/dist/tools/housekeeping-sweep.d.ts

@@ -3,6 +3,7 @@ import type { ToolResult } from '../types/index.js';
 export declare const HousekeepingSweepInputSchema: z.ZodObject<{
     projectPath: z.ZodOptional<z.ZodString>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    deleteRemoteRefs: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     aggressive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeStashes: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;

package/dist/tools/housekeeping-sweep.js

@@ -19,6 +19,11 @@ export const HousekeepingSweepInputSchema = z.object({
         .optional()
         .default(true)
         .describe('When true (default), only report — no deletions performed'),
+    deleteRemoteRefs: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('When true with dryRun false, allow deletion of merged origin branches'),
     aggressive: z
         .boolean()
         .optional()
@@ -107,9 +112,13 @@ function formatReportWithEphemeral(report, orphan, ephemeral) {
 export async function handleHousekeepingSweep(args, resolvedProjectPath) {
     const projectPath = args.projectPath ?? resolvedProjectPath;
     const dryRun = args.dryRun ?? true;
+    const deleteRemoteRefs = args.deleteRemoteRefs ?? false;
+    const authority = dryRun
+        ? { mode: 'report' }
+        : { mode: 'execute', deleteRemoteRefs };
     const report = await runHousekeepingSweep({
         projectPath,
-        dryRun,
+        authority,
         aggressive: args.aggressive ?? false,
         includeStashes: args.includeStashes ?? false,
     });
@@ -145,15 +154,13 @@ export async function handleHousekeepingSweep(args, resolvedProjectPath) {
     }
     let strictPlanuCleanup = null;
     try {
-        const { runStrictPlanuCleanup, validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
-        if (!dryRun) {
-            const cleanup = await runStrictPlanuCleanup(projectPath);
-            strictPlanuCleanup = { deleted: cleanup.deleted, merged: cleanup.merged, offenders: [] };
-        }
-        else {
-            const validation = await validateStrictPlanuLayout(projectPath);
-            strictPlanuCleanup = { deleted: [], merged: [], offenders: validation.offenders };
-        }
+        const { runStrictPlanuCleanup } = await import('../engine/spec-migrator/index.js');
+        const cleanup = await runStrictPlanuCleanup(projectPath, authority);
+        strictPlanuCleanup = {
+            deleted: cleanup.deleted,
+            merged: cleanup.merged,
+            offenders: cleanup.proposed,
+        };
     }
     catch {
         /* best-effort — never block housekeeping_sweep */

package/dist/tools/init-project/git-setup.d.ts

@@ -3,6 +3,7 @@ export interface GitSetupResult {
     gitFlowType: string;
     gitignoreUpdated: boolean;
     gitRepoDetected: boolean;
+    layoutOffenders: string[];
 }
 /** SPEC-001 + SPEC-539: Setup git hooks, detect branching model, and configure .gitignore.
  * SPEC-539: Only installs hooks if a git repository is detected — never creates .git. */

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 {