@planu/cli 3.9.14 → 4.0.0

package/dist/tools/create-spec.js

@@ -2,14 +2,14 @@ import { checkGate } from '../engine/clarification-gate/gate.js';
 import { upsertToken, hashQuestions } from '../engine/clarification-gate/token-store.js';
 import { ti } from '../i18n/index.js';
 import { knowledgeStore, specStore } from '../storage/index.js';
-import { formatSuccess, addNextSteps, toolResult } from './response-helpers.js';
+import { formatSuccess, addNextSteps, toolResult, interactiveResult } from './response-helpers.js';
 import { writeFile, mkdir, rm, readFile, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { estimateSpec } from '../engine/estimator.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { buildSpecContext, buildSplitResult } from './create-spec/spec-builder.js';
 import { validateConstitution } from './create-spec/constitution-validator.js';
-import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostCreationSuggestions, runAutopilotAsync, } from './create-spec/post-creation.js';
+import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostCreationSuggestions, runAutopilotAsync, getAsyncAnalysisPath, } from './create-spec/post-creation.js';
 import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js';
 import { compactObj } from '../engine/compact-obj.js';
 import { buildCreateSpecSummary } from '../engine/human-summary.js';
@@ -36,6 +36,7 @@ import { runPriorDecisionsHint } from './create-spec/adapters/prior-decisions-hi
 import { suggestOutOfScope } from '../engine/scope-boundaries/index.js';
 import { adviseSimilarSpecs } from '../engine/complexity-budget/index.js';
 import { issuePlannerToken } from '../engine/reviewer-tokens/issuer.js';
+import { generateInteractiveQuestions } from './create-spec/question-generator.js';
 /** SPEC-584: Persist a clarification token when interactive questions are emitted. Best-effort. */
 async function persistClarificationToken(earlyReturn, projectId, toolName) {
     try {
@@ -65,7 +66,7 @@ async function runClarificationGate(projectPath, toolName, answers) {
     });
     return gateResult.allow ? null : gateResult.error;
 }
-function handleClarification(_server, _description, _knowledge, autopilot, params) {
+function handleClarification(_server, description, knowledge, autopilot, params) {
     if (!autopilot.needsClarification) {
         return null;
     }
@@ -75,12 +76,32 @@ function handleClarification(_server, _description, _knowledge, autopilot, param
     if (hasAnswers) {
         return null;
     }
-    // The description is too vague — ask the LLM to gather more context from the user.
-    // No hardcoded question templates: the host LLM asks its own contextual questions.
+    const generatedQuestions = generateInteractiveQuestions(description, knowledge);
+    const questions = generatedQuestions.length > 0
+        ? generatedQuestions
+        : [
+            {
+                question: 'What specific behavior should this spec deliver?',
+                header: 'Scope',
+                options: [
+                    {
+                        label: 'User workflow (Recommended)',
+                        description: 'Focus the spec on the end-to-end user behavior and completion state.',
+                    },
+                    {
+                        label: 'Backend behavior',
+                        description: 'Focus the spec on API, persistence, jobs, or integration behavior.',
+                    },
+                    {
+                        label: 'Cleanup/fix',
+                        description: 'Focus the spec on removing stale behavior or fixing a known bug.',
+                    },
+                ],
+                multiSelect: false,
+            },
+        ];
     return {
-        earlyReturn: toolResult('The description needs more detail before a spec can be created.\n\n' +
-            'Ask the user to clarify: what specific behavior they want, who will use it, ' +
-            'and what "done" looks like. Then call create_spec again with the enriched description.', { needsClarification: true }),
+        earlyReturn: interactiveResult(questions, 'The description needs more detail before a spec can be created. Answer the questions, then retry create_spec with clarificationAnswers or an enriched description.', 'universal'),
     };
 }
 const HIGH_RISK_WARNING = 'High-risk spec — consider: ' +
@@ -236,15 +257,12 @@ function computeIdempotencyKey(title, projectPath) {
 }
 /**
  * SPEC-781: Check if async analysis has completed for a given spec.
- * Returns { pending: true } when .analysis.json is absent (analysis still running or never started).
+ * Returns { pending: true } when external analysis state is absent.
  */
 async function checkAnalysisStatus(projectPath, specId) {
     try {
-        const { glob } = await import('glob');
-        const { join: pathJoin } = await import('node:path');
-        const pattern = pathJoin(projectPath, 'planu/specs', `${specId}-*`, '.analysis.json');
-        const matches = await glob(pattern);
-        return { pending: matches.length === 0 };
+        await readFile(getAsyncAnalysisPath(projectPath, specId), 'utf-8');
+        return { pending: false };
     }
     catch {
         return { pending: true };
@@ -358,6 +376,12 @@ export async function handleCreateSpec(inputParams, server) {
         return {
             content: [{ type: 'text', text: DESCRIPTION_EXCEED_MSG }],
             isError: true,
+            structuredContent: {
+                error: 'DESCRIPTION_TOO_LONG',
+                maxChars: DESCRIPTION_MAX_CHARS,
+                actualChars: inputParams.description.length,
+                fixHint: 'Create with a summary description under 3000 chars, then append detailed context through reconcile_spec.',
+            },
         };
     }
     // SPEC-509: resolve projectPath from git root when omitted
@@ -406,7 +430,7 @@ export async function handleCreateSpec(inputParams, server) {
     const idempotencyKey = computeIdempotencyKey(inputParams.title, resolvedPath);
     const existingByKey = await findByIdempotencyKey(resolvedPath, idempotencyKey, hashProjectPath(resolvedPath));
     if (existingByKey) {
-        // SPEC-781: Check if async analysis has completed (.analysis.json exists)
+        // SPEC-781: Check if async analysis has completed in external project data.
         const analysisStatus = await checkAnalysisStatus(resolvedPath, existingByKey.id);
         return {
             content: [
@@ -630,7 +654,7 @@ export async function handleCreateSpec(inputParams, server) {
             });
             // Build result (SPEC-461: lean — no progress, HTML, diagrams, scope filters)
             const result = {
-                // SPEC-781: async analysis running in background (writes .analysis.json when done)
+                // SPEC-781: async analysis running in background (external project data)
                 pendingAnalysis: true,
                 specId: spec.id,
                 title: spec.title,
@@ -684,7 +708,7 @@ export async function handleCreateSpec(inputParams, server) {
             }
             // Dispatch hook event (fire-and-forget)
             fireSpecCreatedHook(projectId, spec, params.projectPath ?? '');
-            // SPEC-781: Fire-and-forget async analysis (writes .analysis.json when complete)
+            // SPEC-781: Fire-and-forget async analysis (external project data)
             runAutopilotAsync(spec.id, params.projectPath ?? '', description);
             // SPEC-713: Track warnings from budgeted post-creation steps
             const budgetWarnings = [];
@@ -770,7 +794,7 @@ export async function handleCreateSpec(inputParams, server) {
             if (budgetWarnings.length > 0) {
                 result.budgetWarnings = budgetWarnings;
             }
-            // SPEC-464: Removed auto-regeneration of planu/index.html — use generate_dashboard on demand
+            // SPEC-1017: No auto-regeneration of project-tree dashboard HTML.
             if (params.projectPath) {
                 notifyStoreChange(params.projectPath, 'specs');
             }

package/dist/tools/flag-spec-gap.d.ts

@@ -13,7 +13,7 @@ export interface FlagSpecGapInput {
  * Handle the flag_spec_gap tool invocation.
  *
  * Validates inputs (severity enum, affectedSpecs pattern + existence),
- * applies defaults, and appends a hash-chained entry to planu/research/gaps.jsonl.
+ * applies defaults, and appends a hash-chained entry to external Planu project data.
  */
 export declare function handleFlagSpecGap(input: FlagSpecGapInput): Promise<ToolResult>;
 //# sourceMappingURL=flag-spec-gap.d.ts.map

package/dist/tools/flag-spec-gap.js

@@ -8,7 +8,7 @@ const VALID_SEVERITIES = ['low', 'medium', 'high'];
  * Handle the flag_spec_gap tool invocation.
  *
  * Validates inputs (severity enum, affectedSpecs pattern + existence),
- * applies defaults, and appends a hash-chained entry to planu/research/gaps.jsonl.
+ * applies defaults, and appends a hash-chained entry to external Planu project data.
  */
 export async function handleFlagSpecGap(input) {
     const { projectId, specId, description } = input;

package/dist/tools/generate-dashboard.js

@@ -4,11 +4,11 @@ import { specStore } from '../storage/index.js';
 import { hashProjectPath } from '../storage/base-store.js';
 export function registerGenerateDashboardTools(server) {
     server.registerTool('generate_spec_dashboard', {
-        description: 'Regenerate planu/index.html dashboard with all specs, metrics, and pagination. Call after bulk changes or to fix a stale dashboard.',
+        description: 'Deprecated compatibility tool. Planu no longer writes generated dashboard HTML into planu/.',
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root directory'),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async (args) => {
         const projectId = hashProjectPath(args.projectPath);
         const specs = await specStore.listSpecs(projectId);
@@ -18,7 +18,7 @@ export function registerGenerateDashboardTools(server) {
             content: [
                 {
                     type: 'text',
-                    text: `Dashboard regenerated: ${String(specs.length)} specs (${String(doneCount)} done). File: planu/index.html`,
+                    text: `Dashboard generation is deprecated; no project files were written. Current specs: ${String(specs.length)} (${String(doneCount)} done).`,
                 },
             ],
         };

package/dist/tools/housekeeping-sweep.js

@@ -143,6 +143,21 @@ export async function handleHousekeepingSweep(args, resolvedProjectPath) {
     catch {
         /* best-effort — never block housekeeping_sweep */
     }
+    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 };
+        }
+    }
+    catch {
+        /* best-effort — never block housekeeping_sweep */
+    }
     // SPEC-1012: Detect and auto-fix specs released on main but still in non-terminal status
     let releaseStatusDrift = null;
     try {
@@ -186,6 +201,7 @@ export async function handleHousekeepingSweep(args, resolvedProjectPath) {
             details: report,
             ...(orphanSummary ? { orphanBrainstorming: orphanSummary } : {}),
             ...(ephemeralResult ? { ephemeralArtifacts: ephemeralResult } : {}),
+            ...(strictPlanuCleanup ? { strictPlanuCleanup } : {}),
             ...(releaseStatusDrift ? { releaseStatusDrift } : {}),
         },
     };

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

@@ -121,9 +121,18 @@ async function configureGitignore(projectPath) {
         // SPEC-724: Gitignore heal_spec_docs backup files (.bak.<ts>)
         const planuIgnores = [
             'planu/*.html',
-            'planu/*.pdf',
             'planu/status.json',
-            'planu/session-state.json',
+            'planu/CHANGELOG.md',
+            'planu/.housekeeping-history.jsonl',
+            'planu/audits/',
+            'planu/handoffs/',
+            'planu/data/',
+            'planu/state/',
+            'planu/.locks/',
+            'planu/specs/data/',
+            'planu/specs/**/.analysis.json',
+            'planu/specs/**/technical-report.html',
+            'planu/specs/**/reference/',
             'planu/specs/**/*.bak.*',
         ];
         for (const entry of planuIgnores) {

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

@@ -24,7 +24,7 @@ import { readAutoInstallFlag, orchestrateSkillInstalls, runHealthCheckWithBaseli
 import { injectProactiveRules } from '../../engine/claude-md-injector/index.js';
 import { discoverSkillsForInit } from '../../engine/skill-bootstrap/registry-fetcher.js';
 import { join } from 'node:path';
-import { stat, readFile } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
 import { generateAgentTeamsRulesIfMissing, generateWorkflowRulesIfMissing, } from './rules-generator.js';
 import { installUniversalRules } from '../../engine/universal-rules/installer.js';
 import { detectHost } from '../../engine/host-detection/detect-host.js';
@@ -126,32 +126,6 @@ export async function handleInitProject(params, server) {
             // Read-only — we surface the finding but never touch existing data.
             const ancestorReport = await detectAncestorDataDirs(projectPath, projectId);
             const ancestorWarning = buildAncestorDataWarning(ancestorReport);
-            // SPEC-540: Idempotency check — if planu/status.json exists, return early with existing projectId
-            const statusJsonPath = join(projectPath, 'planu', 'status.json');
-            try {
-                const statusRaw = await readFile(statusJsonPath, 'utf-8');
-                const statusData = JSON.parse(statusRaw);
-                const existingProjectId = typeof statusData.projectId === 'string' ? statusData.projectId : null;
-                if (existingProjectId) {
-                    const baseText = `Project already initialized at ${projectPath}. Using existing projectId: ${existingProjectId}. Use list_specs to see existing specs or create_spec to add new ones.`;
-                    const text = ancestorWarning !== null ? `${baseText}\n\n⚠️  ${ancestorWarning}` : baseText;
-                    return {
-                        content: [{ type: 'text', text }],
-                        structuredContent: {
-                            projectId: existingProjectId,
-                            projectPath,
-                            alreadyInitialized: true,
-                            message: `Project already initialized at ${projectPath}. Using existing projectId: ${existingProjectId}.`,
-                            ...(ancestorWarning !== null
-                                ? { ancestorDataWarning: ancestorWarning, ancestorDataDirs: ancestorReport }
-                                : {}),
-                        },
-                    };
-                }
-            }
-            catch {
-                // status.json does not exist or is not parseable — proceed with normal init
-            }
             if (ancestorWarning !== null) {
                 console.warn(`[Planu] init_project: ${ancestorWarning}`);
             }

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

@@ -63,6 +63,14 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
     catch {
         /* best-effort — never block init_project */
     }
+    // SPEC-1017: strict managed planu/ cleanup after all legacy migrations.
+    try {
+        const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+        await runStrictPlanuCleanup(projectPath);
+    }
+    catch {
+        /* best-effort — never block init_project */
+    }
     return { discoveryResult, migrationResult, folderMigrationResult };
 }
 /** Return all specs for the project (needed by caller for health check refs). */

package/dist/tools/license-gate.d.ts

@@ -7,6 +7,7 @@ export declare function invalidateTierCache(): void;
  * Returns 'enterprise' for owner token, 'pro' if a license key env var is set, 'free' otherwise.
  */
 export declare function getTierSync(): PricingTier;
+export declare function shouldBypassDailyRateLimit(toolName: string): boolean;
 export declare function withLicenseGate<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
 /**
  * Wraps a handler with rate limiting (free tier only) and usage event recording.

package/dist/tools/license-gate.js

@@ -88,6 +88,10 @@ export function getTierSync() {
 // ---------------------------------------------------------------------------
 const sessionTierCache = new Map();
 const SESSION_TIER_TTL_MS = 10 * 60 * 1000; // 10 min — longer since online validation is expensive
+const RATE_LIMIT_EXEMPT_TOOLS = new Set(['planu_status', 'update_status_batch']);
+export function shouldBypassDailyRateLimit(toolName) {
+    return RATE_LIMIT_EXEMPT_TOOLS.has(toolName);
+}
 async function resolveSessionTier(licenseKey) {
     const now = Date.now();
     const cached = sessionTierCache.get(licenseKey);
@@ -151,7 +155,7 @@ export function withUsageTracking(toolName, handler) {
     return async (args, extra) => {
         const tier = await getCurrentTier();
         // During open-access window, skip rate limiting for free tier
-        if (tier === 'free' && !isOpenAccessActive()) {
+        if (tier === 'free' && !isOpenAccessActive() && !shouldBypassDailyRateLimit(toolName)) {
             const today = new Date().toISOString().slice(0, 10);
             const [trialState, callCount, lastCallAt] = await Promise.all([
                 usageStore.ensureTrialState(),

package/dist/tools/list-specs.js

@@ -63,6 +63,19 @@ async function autoDiscoverProject(projectId, projectPath, collector) {
     catch {
         /* best-effort */
     }
+    // SPEC-1017: list_specs enforces the strict planu/ policy in check mode.
+    // Mutating cleanup is handled by init/update/validate/housekeeping; list_specs
+    // stays read-mostly and surfaces exact offenders if any remain.
+    try {
+        const { validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
+        const layout = await validateStrictPlanuLayout(projectPath);
+        if (!layout.ok) {
+            collector.pushOk('strict-planu-layout', `Non-canonical planu/ paths detected:\n${layout.offenders.map((p) => `- ${p}`).join('\n')}`);
+        }
+    }
+    catch {
+        /* best-effort — never block list_specs */
+    }
     // SPEC-715: list_specs is read-only. Migrations are NEVER run here.
     // Drift is detected (read-only) and reported so the LLM can decide to run heal_spec_docs.
     try {

package/dist/tools/register-sdd-tools.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ["planu_status", "facilitate", "init_project", "clarify_requirements", "create_spec", "challenge_spec", "check_readiness", "update_status", "package_handoff", "validate", "reconcile_spec", "create_rule", "create_skill", "skill_search"];
+export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ["planu_status", "facilitate", "init_project", "clarify_requirements", "create_spec", "challenge_spec", "check_readiness", "update_status", "update_status_batch", "package_handoff", "validate", "reconcile_spec", "create_rule", "create_skill", "skill_search"];
 export declare function registerSddTools(server: McpServer): void;
 //# sourceMappingURL=register-sdd-tools.d.ts.map

package/dist/tools/register-sdd-tools.js

@@ -21,6 +21,7 @@ export const OFFICIAL_SDD_TOOL_NAMES = [
     'challenge_spec',
     'check_readiness',
     'update_status',
+    'update_status_batch',
     'package_handoff',
     'validate',
     'reconcile_spec',

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -10,6 +10,7 @@ import { handleClarifyRequirements } from '../clarify-requirements.js';
 import { handleCreateSpec } from '../create-spec.js';
 import { handleListSpecs } from '../list-specs.js';
 import { handleUpdateStatus } from '../update-status.js';
+import { handleUpdateStatusBatch } from '../update-status/batch.js';
 import { handleEstimate } from '../estimate.js';
 import { handleReverseEngineer } from '../reverse-engineer.js';
 import { handleValidate } from '../validate.js';
@@ -304,6 +305,21 @@ export function registerCoreSpecTools(server) {
                 .describe('SPEC-769: Force-approve a spec that scored below 70 on the readiness gate. Warnings are stored in spec.md frontmatter. Use when the LLM has explicitly confirmed the spec is ready despite a low readiness score.'),
         },
     }, safeTracked('update_status', async (args) => handleUpdateStatus(args)));
+    server.registerTool('update_status_batch', {
+        description: 'Batch update many specs to the same status in one MCP execution. Uses the same transition rules as update_status and reports updated/skipped/failed per spec.',
+        inputSchema: {
+            specIds: z.array(z.string().min(1).max(500)).min(1).describe('Spec IDs to update'),
+            projectId: z.string().max(500).optional().describe('Project ID, if known'),
+            projectPath: z
+                .string()
+                .max(4096)
+                .optional()
+                .describe('Absolute project root. Preferred when projectId is unknown.'),
+            status: SpecStatusEnum.describe('New status for all specs'),
+            dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
+            reviewNotes: z.string().max(10_000).optional().describe('Optional notes for each transition.'),
+        },
+    }, safeTracked('update_status_batch', async (args) => handleUpdateStatusBatch(args)));
     // 8. estimate
     server.registerTool('estimate', {
         description: t('tools.estimate.description'),

package/dist/tools/spec-lock-handler.js

@@ -107,7 +107,7 @@ export async function handleListLocks(input) {
     try {
         // SPEC-301: legacy manual locks (data/projects/.../locks/*.json)
         const legacyLocks = await listActiveLocks(projectPath);
-        // SPEC-719: cross-process disk locks (planu/.locks/*.lock)
+        // SPEC-719: cross-process disk locks (data/.locks/planu/*.lock)
         const crossProcessLocks = await listActiveCrossProcessLocks(projectPath).catch(() => []);
         const totalCount = legacyLocks.length + crossProcessLocks.length;
         if (totalCount === 0) {

package/dist/tools/tool-registry/group-misc.js

@@ -1182,11 +1182,11 @@ export function registerMiscGroupTools(s) {
     registerRepairFrontmatterDriftTool(s);
     // ── Generate dashboard ─────────────────────────────────────────────────────
     s.registerTool('generate_spec_dashboard', {
-        description: 'Regenerate planu/index.html dashboard with all specs, metrics, and pagination. Call after bulk changes or to fix a stale dashboard.',
+        description: 'Deprecated compatibility tool. Planu no longer writes generated dashboard HTML into planu/.',
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root directory'),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async (args) => {
         const projectId = hashProjectPath(args.projectPath);
         const specs = await specStore.listSpecs(projectId);
@@ -1196,7 +1196,7 @@ export function registerMiscGroupTools(s) {
             content: [
                 {
                     type: 'text',
-                    text: `Dashboard regenerated: ${String(specs.length)} specs (${String(doneCount)} done). File: planu/index.html`,
+                    text: `Dashboard generation is deprecated; no project files were written. Current specs: ${String(specs.length)} (${String(doneCount)} done).`,
                 },
             ],
         };
@@ -1331,7 +1331,7 @@ export function registerMiscGroupTools(s) {
     // ── SPEC-739: flag_spec_gap ─────────────────────────────────────────────────
     s.registerTool('flag_spec_gap', {
         description: 'Record a spec implementation gap discovered mid-implementation. ' +
-            'Persists a hash-chained entry to planu/research/gaps.jsonl with severity ' +
+            'Persists a hash-chained entry to external Planu project data with severity ' +
             "classification ('low' | 'medium' | 'high') and affected spec links. " +
             'Existing callers without severity or affectedSpecs continue to work (defaults applied).',
         inputSchema: {

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

@@ -0,0 +1,3 @@
+import type { ToolResult, UpdateStatusBatchInput } from '../../types/index.js';
+export declare function handleUpdateStatusBatch(input: UpdateStatusBatchInput): Promise<ToolResult>;
+//# sourceMappingURL=batch.d.ts.map

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

@@ -0,0 +1,96 @@
+// tools/update-status/batch.ts — SPEC-1017 batch status transitions
+import { handleUpdateStatus } from './index.js';
+import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
+function firstText(result) {
+    const first = result.content[0];
+    return first?.type === 'text' ? first.text : JSON.stringify(result.structuredContent ?? {});
+}
+export async function handleUpdateStatusBatch(input) {
+    const uniqueSpecIds = [...new Set(input.specIds)].sort();
+    if (uniqueSpecIds.length === 0) {
+        return { content: [{ type: 'text', text: 'update_status_batch requires at least one specId.' }], isError: true };
+    }
+    const resolved = await resolveProjectIdOrAutoDetect({
+        projectId: input.projectId,
+        projectPath: input.projectPath,
+    });
+    if (!resolved.ok) {
+        return resolved.errorResult;
+    }
+    if (input.dryRun) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Batch status dry run: ${uniqueSpecIds.length} spec(s) would transition to ${input.status}.\n` +
+                        uniqueSpecIds.map((id) => `- ${id}`).join('\n'),
+                },
+            ],
+            structuredContent: {
+                dryRun: true,
+                status: input.status,
+                specIds: uniqueSpecIds,
+            },
+        };
+    }
+    const updated = [];
+    const skipped = [];
+    const failed = [];
+    const previousSuppress = process.env.PLANU_SUPPRESS_AUTOCOMMIT;
+    process.env.PLANU_SUPPRESS_AUTOCOMMIT = 'true';
+    try {
+        for (const specId of uniqueSpecIds) {
+            const result = await handleUpdateStatus({
+                specId,
+                status: input.status,
+                projectId: resolved.projectId,
+                projectPath: resolved.projectPath,
+                reviewNotes: input.reviewNotes,
+            });
+            const message = firstText(result);
+            if (result.isError === true) {
+                if (/already|idempotent|same status/i.test(message)) {
+                    skipped.push({ specId, message });
+                }
+                else {
+                    failed.push({ specId, message });
+                }
+            }
+            else {
+                updated.push({ specId, message });
+            }
+        }
+    }
+    finally {
+        if (previousSuppress === undefined) {
+            delete process.env.PLANU_SUPPRESS_AUTOCOMMIT;
+        }
+        else {
+            process.env.PLANU_SUPPRESS_AUTOCOMMIT = previousSuppress;
+        }
+    }
+    try {
+        const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+        await runStrictPlanuCleanup(resolved.projectPath);
+    }
+    catch {
+        /* best-effort final pass */
+    }
+    const text = [
+        `Batch status transition complete: ${input.status}`,
+        `Updated: ${updated.length}`,
+        `Skipped: ${skipped.length}`,
+        `Failed: ${failed.length}`,
+    ].join('\n');
+    return {
+        content: [{ type: 'text', text }],
+        isError: failed.length > 0,
+        structuredContent: {
+            updated,
+            skipped,
+            failed,
+            sideEffectsFlushed: ['strict-planu-cleanup'],
+        },
+    };
+}
+//# sourceMappingURL=batch.js.map

package/dist/tools/update-status/dod-gates.js

@@ -264,7 +264,7 @@ export async function checkValidationReportGate(specId, projectId, force) {
             return null;
         }
         if (!result.payload.passed) {
-            const artifactPath = `planu/data/projects/${projectId}/handoffs/${specId}/validation-report.json`;
+            const artifactPath = `external Planu project data: handoffs/${specId}/validation-report.json`;
             return {
                 content: [
                     {

package/dist/tools/update-status/file-sync.js

@@ -86,7 +86,9 @@ export async function syncSpecFiles(updatedSpec, currentStatus, newStatus, proje
             // Commit message must reflect the actual transition — 'mark-done' is only
             // correct when newStatus === 'done'; any other transition uses 'status-update'
             // to avoid misleading "mark as done" messages on approved/implementing/etc.
-            if (projectPath) {
+            if (projectPath &&
+                process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
+                process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                 try {
                     const { git: gitCmd } = await import('../git/git-helpers.js');
                     await gitCmd(projectPath, ['add', '--', updatedSpec.specPath]);

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

@@ -240,6 +240,16 @@ export async function handleUpdateStatus(params, server) {
             return resolved.errorResult;
         }
         const projectId = resolved.projectId;
+        const effectiveProjectPath = resolved.projectPath;
+        if (effectiveProjectPath) {
+            try {
+                const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+                await runStrictPlanuCleanup(effectiveProjectPath);
+            }
+            catch {
+                /* strict cleanup is best-effort here; validate fails closed if artifacts remain */
+            }
+        }
         try {
             // Get the current spec
             const spec = await specStore.getSpec(projectId, specId);
@@ -271,7 +281,7 @@ export async function handleUpdateStatus(params, server) {
                         content: [
                             {
                                 type: 'text',
-                                text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect planu/.locks/${specId}.lock`,
+                                text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect data/.locks/planu/${specId}.lock`,
                             },
                         ],
                         isError: true,
@@ -864,7 +874,10 @@ export async function handleUpdateStatus(params, server) {
                 }
                 // SPEC-544: Final git add after all writes complete (covers auto-advance multi-step transitions)
                 // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
-                if (effectiveGatePath && updatedSpec.specPath) {
+                if (effectiveGatePath &&
+                    updatedSpec.specPath &&
+                    process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
+                    process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                     try {
                         const { git: gitCmd } = await import('../git/git-helpers.js');
                         await gitCmd(effectiveGatePath, ['add', 'planu/']);

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

@@ -162,22 +162,18 @@ export async function runDoneActions(projectId, specId, gitBranch) {
             }
             return null;
         })(),
-        // SPEC-544: Auto-stage planu/ files, then warn only if non-planu changes remain
-        // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
+        // Warn if non-planu changes remain. Planu autocommit/staging is opt-in only.
         (async () => {
             try {
                 const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
                 const projectPath = await resolveProjectPath(projectId);
-                try {
+                if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
                     await gitCmd(projectPath, ['add', 'planu/']);
                     const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
                     void planuAutoCommit({ projectPath, specId, reason: 'mark-done' }).catch((err) => {
                         console.error('[update-status] planuAutoCommit failed:', err instanceof Error ? err.message : String(err));
                     });
                 }
-                catch {
-                    // git add failed (nothing to stage, or not a git repo) — continue to status check
-                }
                 const { stdout } = await gitCmd(projectPath, ['status', '--porcelain']);
                 const nonPlanuLines = stdout
                     .trim()