@planu/cli 3.9.14 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.1.0] - 2026-05-21
+
+### Features
+- Enforce English-only persisted Planu artifacts across specs, skills, agent instructions, and rules.
+- Gate host-aware init scaffolding for `AGENTS.md`, `CLAUDE.md`, Cursor, Windsurf, Cline, Gemini, Codex, and OpenCode generated AI docs.
+- Keep user-authored host file content intact while validating only Planu-owned generated blocks.
+
+### Tests
+- Add coverage for skill, rule, and agent instruction language gates across core writers and host generators.
+
+
+## [4.0.0] - 2026-05-20
+
+**Tarball SHA-256:** `8c00d74f48ed5614197000a967b103cc17653150aadf876fcfd18d0174263017`
+
+
 ## [3.9.12] - 2026-05-19
 
 **Tarball SHA-256:** `cd07a22fdfc0c982726a918c1e47f147ca300ecad710e8377f1751ef993fea60`
@@ -3787,4 +3803,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/cli/commands/spec.js

@@ -10,6 +10,7 @@ import { resolve } from 'node:path';
 import { handleCreateSpec } from '../../tools/create-spec.js';
 import { handleListSpecs } from '../../tools/list-specs.js';
 import { handleUpdateStatus } from '../../tools/update-status.js';
+import { handleUpdateStatusBatch } from '../../tools/update-status/batch.js';
 import { formatToolResult } from '../formatter.js';
 import { detectProjectId } from '../project-detector.js';
 import { bold, cyan, green, red, dim } from '../colors.js';
@@ -178,12 +179,15 @@ async function runStatus(args, flags) {
         options: {
             'project-id': { type: 'string' },
             notes: { type: 'string', short: 'n' },
+            batch: { type: 'boolean' },
+            set: { type: 'string', short: 's' },
         },
         strict: false,
         allowPositionals: true,
     });
+    const batch = values.batch === true;
     const specId = positionals[0];
-    const status = positionals[1];
+    const status = batch ? values.set : positionals[1];
     if (!specId) {
         process.stderr.write(`${red('Error:')} Spec ID is required.\nUsage: planu spec status SPEC-NNN <status>\n`);
         process.exitCode = 1;
@@ -195,6 +199,21 @@ async function runStatus(args, flags) {
         return;
     }
     const projectId = values['project-id'] ?? detectProjectId();
+    if (batch) {
+        const result = await handleUpdateStatusBatch({
+            specIds: positionals,
+            projectId,
+            status: status,
+            reviewNotes: values.notes ?? undefined,
+        });
+        if (result.isError) {
+            process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write(formatToolResult(result, flags) + '\n');
+        return;
+    }
     const result = await handleUpdateStatus({
         specId,
         projectId,

package/dist/cli/commands/status.js

@@ -1,13 +1,14 @@
 // cli/commands/status.ts — planu status <specId> [--set implementing] (SPEC-124)
 import { parseArgs } from 'node:util';
 import { handleUpdateStatus } from '../../tools/update-status.js';
+import { handleUpdateStatusBatch } from '../../tools/update-status/batch.js';
 import { formatToolResult } from '../formatter.js';
 import { detectProjectId } from '../project-detector.js';
 import { red, green } from '../colors.js';
 export const statusCommand = {
     name: 'status',
     description: 'Update the status of a spec',
-    usage: 'planu status <specId> --set <status> [--project-id ID]',
+    usage: 'planu status <specId> --set <status> [--project-id ID] | planu status batch --set <status> SPEC-001 SPEC-002',
     async run(args, flags) {
         const { values, positionals } = parseArgs({
             args,
@@ -19,6 +20,7 @@ export const statusCommand = {
             strict: false,
             allowPositionals: true,
         });
+        const isBatch = positionals[0] === 'batch';
         const specId = positionals[0];
         if (!specId) {
             process.stderr.write(`${red('Error:')} Spec ID is required.\nUsage: ${statusCommand.usage}\n`);
@@ -32,6 +34,21 @@ export const statusCommand = {
             return;
         }
         const projectId = values['project-id'] ?? detectProjectId();
+        if (isBatch) {
+            const result = await handleUpdateStatusBatch({
+                specIds: positionals.slice(1),
+                projectId,
+                status: status,
+                reviewNotes: values.notes ?? undefined,
+            });
+            if (result.isError) {
+                process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            process.stdout.write(formatToolResult(result, flags) + '\n');
+            return;
+        }
         const result = await handleUpdateStatus({
             specId,
             projectId,

package/dist/config/license-plans.json

@@ -94,6 +94,7 @@
     "unlock_spec",
     "unregister_project_path",
     "update_status",
+    "update_status_batch",
     "validate",
     "worker_status",
     "security_scan",

package/dist/engine/ai-integration/agents-md/generator.js

@@ -1,6 +1,7 @@
 // engine/ai-integration/agents-md/generator.ts — Universal AGENTS.md generator (SPEC-269)
 import { writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../spec-language/english-only.js';
 const PLANU_SECTION_START = '<!-- planu-sdd:start -->';
 const PLANU_SECTION_END = '<!-- planu-sdd:end -->';
 function buildActiveSpecBlock(activeSpecId, activeSpecTitle) {
@@ -105,7 +106,9 @@ function buildSddSection(options) {
         parts.push('', approvedQueueBlock);
     }
     parts.push('', toolsBlock, '', branchBlock, '', architectureBlock, '', PLANU_SECTION_END);
-    return parts.join('\n');
+    const content = parts.join('\n');
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 /** Generates the full universal AGENTS.md content for a project using Planu SDD. */
 export function generateUniversalAgentsMd(options) {

package/dist/engine/ai-integration/cline/clinerules-generator.js

@@ -1,6 +1,7 @@
 // engine/ai-integration/cline/clinerules-generator.ts — .clinerules generator (SPEC-271)
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../spec-language/english-only.js';
 const SECTION_START = '<!-- planu-sdd:start -->';
 const SECTION_END = '<!-- planu-sdd:end -->';
 function buildPlanuSection(options) {
@@ -52,12 +53,16 @@ function buildPlanuSection(options) {
     lines.push('Place in `.clinerules` at project root or in `.clinerules/` directory.');
     lines.push('');
     lines.push(SECTION_END);
-    return lines.join('\n');
+    const content = lines.join('\n');
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function generateClineRules(options) {
     const stackStr = options.stack.length > 0 ? options.stack.join(', ') : 'Not specified';
     const header = [`# Cline Rules — ${options.projectName}`, '', `Stack: ${stackStr}`, ''].join('\n');
-    return header + buildPlanuSection(options);
+    const content = header + buildPlanuSection(options);
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function writeClineRules(projectPath, options) {
     const filePath = join(projectPath, '.clinerules');

package/dist/engine/ai-integration/codex/agents-md-generator.js

@@ -1,5 +1,6 @@
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../spec-language/english-only.js';
 const PLANU_SECTION_START = '<!-- planu:start -->';
 const PLANU_SECTION_END = '<!-- planu:end -->';
 function buildWorkflowSection() {
@@ -91,6 +92,7 @@ export function generateAgentsMd(options) {
         architectureSection,
         PLANU_SECTION_END,
     ].join('\n');
+    assertEnglishOnlyArtifactText(planuBlock, 'agent');
     return planuBlock;
 }
 /**

package/dist/engine/ai-integration/codex/hooks-generator.js

@@ -8,6 +8,7 @@ const SESSION_START_COMMAND = [
 ].join(' ');
 const STOP_COMMAND = [
     'if [ -d "planu/" ]; then',
+    '  if [ "$PLANU_ENABLE_AUTOCOMMIT" != "true" ]; then exit 0; fi;',
     '  git add planu/specs/ planu/conventions.json 2>/dev/null;',
     '  git diff --staged --quiet || git commit -m "chore: auto-save planu state" 2>/dev/null;',
     'fi',

package/dist/engine/ai-integration/cursor/cursorrules-generator.js

@@ -1,6 +1,7 @@
 // engine/ai-integration/cursor/cursorrules-generator.ts — .cursorrules generator (SPEC-268)
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../spec-language/english-only.js';
 const SECTION_START = '<!-- planu-sdd:start -->';
 const SECTION_END = '<!-- planu-sdd:end -->';
 function buildPlanuSection(options) {
@@ -46,12 +47,16 @@ function buildPlanuSection(options) {
         lines.push('');
     }
     lines.push(SECTION_END);
-    return lines.join('\n');
+    const content = lines.join('\n');
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function generateCursorRules(options) {
     const stackStr = options.stack.length > 0 ? options.stack.join(', ') : 'Not specified';
     const header = [`# Cursor Rules — ${options.projectName}`, '', `Stack: ${stackStr}`, ''].join('\n');
-    return header + buildPlanuSection(options);
+    const content = header + buildPlanuSection(options);
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function writeCursorRules(projectPath, options) {
     const filePath = join(projectPath, '.cursorrules');

package/dist/engine/ai-integration/gemini/settings-generator.js

@@ -17,7 +17,10 @@ const HOOK_SCRIPT_SESSION_START = [
 ].join('\n');
 const HOOK_SCRIPT_SESSION_END = [
     '#!/usr/bin/env bash',
-    '# session-end.sh — auto-commit planu/ changes',
+    '# session-end.sh — optionally auto-commit planu/ changes',
+    'if [ "$PLANU_ENABLE_AUTOCOMMIT" != "true" ]; then',
+    '  exit 0',
+    'fi',
     'if git diff --quiet HEAD -- planu/ 2>/dev/null; then',
     '  exit 0',
     'fi',

package/dist/engine/ai-integration/kiro/hooks-generator.js

@@ -18,6 +18,7 @@ const POST_TOOL_SCRIPT = [
 const STOP_SCRIPT = [
     'planu session_checkpoint --auto 2>/dev/null;',
     'if [ -d "planu/" ]; then',
+    '  if [ "$PLANU_ENABLE_AUTOCOMMIT" != "true" ]; then exit 0; fi;',
     '  git add planu/specs/ planu/conventions.json 2>/dev/null;',
     '  git diff --staged --quiet || git commit -m "chore: auto-save planu state [kiro]" 2>/dev/null;',
     'fi',
@@ -40,7 +41,7 @@ export function generateKiroHooks() {
         {
             id: 'planu-stop',
             event: 'stop',
-            description: 'Save session checkpoint and auto-commit planu state on session end',
+            description: 'Save session checkpoint and optionally auto-commit planu state on session end',
             script: STOP_SCRIPT,
         },
     ];

package/dist/engine/ai-integration/windsurf/windsurfrules-generator.js

@@ -1,6 +1,7 @@
 // engine/ai-integration/windsurf/windsurfrules-generator.ts — .windsurfrules generator (SPEC-268)
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertEnglishOnlyArtifactText } from '../../spec-language/english-only.js';
 const SECTION_START = '<!-- planu-sdd:start -->';
 const SECTION_END = '<!-- planu-sdd:end -->';
 function buildPlanuSection(options) {
@@ -46,12 +47,16 @@ function buildPlanuSection(options) {
         lines.push('');
     }
     lines.push(SECTION_END);
-    return lines.join('\n');
+    const content = lines.join('\n');
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function generateWindsurfRules(options) {
     const stackStr = options.stack.length > 0 ? options.stack.join(', ') : 'Not specified';
     const header = [`# Windsurf Rules — ${options.projectName}`, '', `Stack: ${stackStr}`, ''].join('\n');
-    return header + buildPlanuSection(options);
+    const content = header + buildPlanuSection(options);
+    assertEnglishOnlyArtifactText(content, 'agent');
+    return content;
 }
 export function writeWindsurfRules(projectPath, options) {
     const filePath = join(projectPath, '.windsurfrules');

package/dist/engine/autopilot/action-registry.js

@@ -202,25 +202,16 @@ const ACTION_HANDLERS = {
         const specs = await specStore.listSpecs(ctx.projectId);
         const { generateChangelog } = await import('../doc-generator/support-generators.js');
         const doc = generateChangelog(specs, 'en');
-        // Write changelog to disk inside planu/ directory
+        // Generated changelog is returned to callers; strict Planu mode forbids planu/CHANGELOG.md.
         const { writeFile, mkdir } = await import('node:fs/promises');
         const { join } = await import('node:path');
-        const changelogPath = join(ctx.projectPath, 'planu', 'CHANGELOG.md');
-        await mkdir(join(ctx.projectPath, 'planu'), { recursive: true });
+        const { projectDataDir } = await import('../../storage/base-store.js');
+        const changelogPath = join(projectDataDir(ctx.projectId), 'generated', 'CHANGELOG.md');
+        await mkdir(join(projectDataDir(ctx.projectId), 'generated'), { recursive: true });
         await writeFile(changelogPath, doc.content, 'utf-8');
-        // Auto-commit planu/ changes so CHANGELOG.md is never left unstaged
-        void (async () => {
-            try {
-                const { planuAutoCommit } = await import('../git/planu-autocommit.js');
-                await planuAutoCommit({ projectPath: ctx.projectPath, reason: 'sync-release' });
-            }
-            catch {
-                /* best-effort */
-            }
-        })();
         return {
             success: true,
-            summary: `Changelog written to planu/CHANGELOG.md (${doc.content.length} chars)`,
+            summary: `Changelog written to external Planu project data (${doc.content.length} chars)`,
             durationMs: 0,
         };
     }),

package/dist/engine/autopilot/state-updater.js

@@ -1,26 +1,29 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
-// engine/autopilot/state-updater.ts — SPEC-459: Auto-update planu/status.json on every status change
+// engine/autopilot/state-updater.ts — SPEC-459: Auto-update external project status on every status change
 // Fire-and-forget: never blocks the event pipeline, never throws to callers.
 // SPEC-753: File-lock applied to all writes; self-healing on corrupt reads.
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { withStatusLock } from '../../storage/status-store/file-lock.js';
-import { validateStatusJson, quarantineCorruptStatus, rebuildStatusFromFrontmatters, writeRebuiltStatus, } from '../../storage/status-store/self-healing.js';
+import { validateStatusJson, rebuildStatusFromFrontmatters, writeRebuiltStatus, } from '../../storage/status-store/self-healing.js';
 import { syncVersionField } from '../../storage/status-store/version-sync.js';
-const STATUS_FILENAME = 'planu/status.json';
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
+const STATUS_FILENAME = 'status.json';
 const MAX_RECENT_CHANGES = 20;
+function getStatusPath(projectPath) {
+    return join(projectDataDir(hashProjectPath(projectPath)), STATUS_FILENAME);
+}
 /**
  * SPEC-753: Load status.json with self-healing.
  * If corrupt: quarantine → rebuild from frontmatters → return fresh state.
  */
 async function loadStatus(projectPath) {
-    const filePath = join(projectPath, STATUS_FILENAME);
+    const filePath = getStatusPath(projectPath);
     // SPEC-753: Validate before parsing
     const validation = await validateStatusJson(filePath);
     if (!validation.ok && validation.error !== 'ENOENT') {
-        // Corrupt — quarantine and rebuild
+        // Corrupt external state is rebuilt in place; no project-tree quarantine.
         try {
-            await quarantineCorruptStatus(filePath, projectPath);
             const rebuilt = await rebuildStatusFromFrontmatters({ projectPath });
             await writeRebuiltStatus(filePath, rebuilt);
             return rebuilt;
@@ -48,7 +51,7 @@ async function loadStatus(projectPath) {
     }
 }
 async function saveStatus(projectPath, status) {
-    const filePath = join(projectPath, STATUS_FILENAME);
+    const filePath = getStatusPath(projectPath);
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, JSON.stringify(status, null, 2), 'utf-8');
 }
@@ -58,7 +61,7 @@ async function saveStatus(projectPath, status) {
  * SPEC-753: Wrapped in file-lock to prevent concurrent write corruption.
  */
 export async function recordStatusChange(projectPath, _projectId, specId, fromStatus, toStatus) {
-    const filePath = join(projectPath, STATUS_FILENAME);
+    const filePath = getStatusPath(projectPath);
     try {
         await withStatusLock(filePath, async () => {
             const status = await loadStatus(projectPath);
@@ -91,7 +94,7 @@ export async function recordStatusChange(projectPath, _projectId, specId, fromSt
  * SPEC-753: Wrapped in file-lock.
  */
 export async function refreshProjectStatus(projectPath, projectId) {
-    const filePath = join(projectPath, STATUS_FILENAME);
+    const filePath = getStatusPath(projectPath);
     try {
         await withStatusLock(filePath, async () => {
             const { specStore } = await import('../../storage/index.js');
@@ -124,7 +127,7 @@ export async function refreshProjectStatus(projectPath, projectId) {
  * SPEC-753: Wrapped in file-lock.
  */
 export async function incrementSpecCount(projectPath) {
-    const filePath = join(projectPath, STATUS_FILENAME);
+    const filePath = getStatusPath(projectPath);
     try {
         await withStatusLock(filePath, async () => {
             const status = await loadStatus(projectPath);

package/dist/engine/cascade-hooks/hooks/git-auto-stage.hook.js

@@ -5,6 +5,9 @@ async function handler(ctx) {
     if (!projectPath) {
         return;
     }
+    if (process.env.PLANU_ENABLE_AUTOCOMMIT !== 'true') {
+        return;
+    }
     // Guard: only auto-stage when validateScore is non-null (matches original inline guard)
     if (validateScore === null) {
         return;

package/dist/engine/cascade-hooks/hooks/html-regen.hook.js

@@ -13,7 +13,7 @@ export const htmlRegenHook = {
     id: 'html-regen',
     triggers: ['done'], // only on done
     requiresProjectPath: true,
-    label: 'Regenerate planu/index.html on done (SPEC-464)',
+    label: 'Run legacy dashboard compatibility hook without writing project HTML',
     handler,
 };
 //# sourceMappingURL=html-regen.hook.js.map

package/dist/engine/cascade-hooks/hooks/status-json.hook.js

@@ -28,7 +28,7 @@ export const statusJsonHook = {
     id: 'status-json',
     triggers: [], // any status change + release_completed
     requiresProjectPath: true,
-    label: 'Auto-update planu/status.json with spec counts (SPEC-459/776)',
+    label: 'Auto-update external project status with spec counts (SPEC-459/776)',
     handler,
 };
 //# sourceMappingURL=status-json.hook.js.map

package/dist/engine/cascade-hooks/state-drift-detector.d.ts

@@ -1,6 +1,6 @@
 import type { DriftReport } from '../../types/cascade-hooks.js';
 /**
- * SPEC-776: Compare in-memory spec counts vs planu/status.json and
+ * SPEC-776: Compare in-memory spec counts vs external status.json and
  * recently-done spec vs planu/session-context.md.
  * Returns a DriftReport with any detected mismatches.
  */

package/dist/engine/cascade-hooks/state-drift-detector.js

@@ -1,32 +1,35 @@
 // engine/cascade-hooks/state-drift-detector.ts — SPEC-776
-// Detects drift between in-memory spec store and planu/ state files.
+// Detects drift between in-memory spec store and canonical Planu state files.
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore } from '../../storage/index.js';
-import { hashProjectPath } from '../../storage/base-store.js';
-/** Read and parse planu/status.json counts field; returns null if missing or invalid. */
+import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
+function externalStatusPath(projectPath) {
+    return join(projectDataDir(hashProjectPath(projectPath)), 'status.json');
+}
+/** Read and parse external status counts; returns null if missing or invalid. */
 async function readStatusJsonDoneCounts(projectPath) {
     try {
-        const raw = await readFile(join(projectPath, 'planu', 'status.json'), 'utf-8');
+        const raw = await readFile(externalStatusPath(projectPath), 'utf-8');
         const parsed = JSON.parse(raw);
         if (parsed === null || typeof parsed !== 'object') {
             return null;
         }
-        const counts = parsed.counts;
-        if (counts === null || typeof counts !== 'object') {
+        const byStatus = parsed.byStatus;
+        if (byStatus === null || typeof byStatus !== 'object') {
             return null;
         }
-        const doneVal = counts.done;
+        const doneVal = byStatus.done;
         return typeof doneVal === 'number' ? doneVal : null;
     }
     catch {
         return null;
     }
 }
-/** Returns true if planu/status.json exists (even if counts are missing). */
+/** Returns true if external status.json exists (even if counts are missing). */
 async function statusJsonExists(projectPath) {
     try {
-        await readFile(join(projectPath, 'planu', 'status.json'), 'utf-8');
+        await readFile(externalStatusPath(projectPath), 'utf-8');
         return true;
     }
     catch {
@@ -57,7 +60,7 @@ function extractLastDoneSpecFromContext(content) {
     return idMatch ? idMatch[0] : null;
 }
 /**
- * SPEC-776: Compare in-memory spec counts vs planu/status.json and
+ * SPEC-776: Compare in-memory spec counts vs external status.json and
  * recently-done spec vs planu/session-context.md.
  * Returns a DriftReport with any detected mismatches.
  */
@@ -72,12 +75,12 @@ export async function verifyStateFiles(projectPath) {
         return { drifted: false, alerts: [] };
     }
     const expectedDoneCount = specs.filter((s) => s.status === 'done').length;
-    // --- Check planu/status.json ---
+    // --- Check external status.json ---
     const exists = await statusJsonExists(projectPath);
     if (!exists) {
         alerts.push({
             kind: 'state_drift',
-            message: 'state_drift: planu/status.json missing or unreadable',
+            message: 'state_drift: external status.json missing or unreadable',
             severity: 'warning',
             fix: 'reconcile_status_json(projectPath)',
         });

package/dist/engine/git/planu-autocommit.d.ts

@@ -1,4 +1,5 @@
 import type { PlanuAutocommitOptions, PlanuAutocommitResult } from '../../types/index.js';
+export declare function isPlanuAutocommitEnabled(): boolean;
 /**
  * Idempotent autocommit for staged planu/ docs.
  *

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

@@ -4,6 +4,9 @@ import { promisify } from 'node:util';
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 const execFile = promisify(execFileCb);
+export function isPlanuAutocommitEnabled() {
+    return process.env.PLANU_ENABLE_AUTOCOMMIT === 'true';
+}
 /** Run git with execFile (no shell injection risk). */
 async function runGit(cwd, args) {
     const result = await execFile('git', args, {
@@ -101,6 +104,9 @@ async function unstageFiles(projectPath) {
  */
 export async function planuAutoCommit(opts) {
     const { projectPath, specId, reason } = opts;
+    if (!isPlanuAutocommitEnabled()) {
+        return { committed: false, skipped: 'disabled' };
+    }
     // 1. Safety check: refuse if mid-merge
     const midMerge = await isMidMerge(projectPath);
     if (midMerge) {

package/dist/engine/git-hook-injector.js

@@ -3,7 +3,7 @@
 // SPEC-347: auto-stage planu HTML files so they are never left out of commits
 import { readFile, writeFile, access, constants } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-const PLANU_SNIPPET = `\n# Planu: auto-stage specs (SPEC-466 — only source-of-truth files)\ngit add planu/specs/ planu/conventions.json 2>/dev/null || true\n`;
+const PLANU_SNIPPET = `\n# Planu: optional auto-stage specs (SPEC-466 — only source-of-truth files)\nif [ "$PLANU_ENABLE_AUTOCOMMIT" = "true" ]; then\n  git add planu/specs/ planu/conventions.json 2>/dev/null || true\nfi\n`;
 const PLANU_MARKER = 'git add planu/';
 async function fileExists(filePath) {
     try {
@@ -74,8 +74,8 @@ export async function injectPlanuAutoStage(projectPath) {
     }
     // lefthook / simple-git-hooks: cannot auto-inject, return manual instructions
     const manualInstructions = hookSystem === 'lefthook'
-        ? `Add to lefthook.yml under pre-commit commands:\n  - run: git add planu/specs/ planu/conventions.json 2>/dev/null || true`
-        : `Add to package.json "simple-git-hooks"."pre-commit":\n  "git add planu/specs/ planu/conventions.json 2>/dev/null || true"`;
+        ? `Add to lefthook.yml under pre-commit commands:\n  - run: '[ "$PLANU_ENABLE_AUTOCOMMIT" = "true" ] && git add planu/specs/ planu/conventions.json 2>/dev/null || true'`
+        : `Add to package.json "simple-git-hooks"."pre-commit":\n  "[ \\"$PLANU_ENABLE_AUTOCOMMIT\\" = \\"true\\" ] && git add planu/specs/ planu/conventions.json 2>/dev/null || true"`;
     return {
         injected: false,
         hookSystem,

package/dist/engine/handoff-artifacts/io.js

@@ -7,6 +7,7 @@ import { acquireLock, releaseLock } from '../safety/cross-process-lock.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 import { validateArtifact } from './schemas.js';
 import { resolveCompat } from './version-policy.js';
+import { projectDataDir } from '../../storage/base-store.js';
 // Current schema version for version-policy checks
 const CURRENT_SCHEMA_VERSION = '1.0.0';
 // ---------------------------------------------------------------------------
@@ -14,14 +15,14 @@ const CURRENT_SCHEMA_VERSION = '1.0.0';
 // ---------------------------------------------------------------------------
 /**
  * Returns the file path for a handoff artifact.
- * Layout: planu/data/projects/<projectId>/handoffs/<specId>/<kind>
+ * Layout: ~/.planu/data/projects/<projectId>/handoffs/<specId>/<kind>
  *
  * Note: kind values like 'spec.lock', 'review_feedback', etc. are used directly as filenames.
  */
 function artifactPath(projectId, specId, kind) {
     // review_feedback is a .md file, rest are .json
     const filename = kind === 'review_feedback' ? 'review_feedback.md' : `${kind}.json`;
-    return join('planu', 'data', 'projects', projectId, 'handoffs', specId, filename);
+    return join(projectDataDir(projectId), 'handoffs', specId, filename);
 }
 /** Map artifact kind to the transition-log eventType */
 function eventTypeForKind(kind) {

package/dist/engine/handoff-packager.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { stripFrontmatter } from './frontmatter-parser.js';
+import { hashProjectPath, projectDataDir } from '../storage/base-store.js';
 // ── Parsing helpers ──────────────────────────────────────────────────────────
 async function safeReadFile(path) {
     if (!path) {
@@ -293,7 +294,7 @@ async function persistHandoffIfPossible(pkg, knowledge) {
     if (!knowledge.projectPath) {
         return pkg;
     }
-    const handoffDir = join(knowledge.projectPath, 'planu', 'handoffs');
+    const handoffDir = join(projectDataDir(hashProjectPath(knowledge.projectPath)), 'handoffs');
     const handoffPath = join(handoffDir, `${pkg.specId}.md`);
     const sessionContextPath = join(knowledge.projectPath, 'planu', 'session-context.md');
     const markdown = renderPersistedHandoff(pkg);

package/dist/engine/hooks/full-spectrum-generator.d.ts

@@ -1,6 +1,7 @@
 import type { FullSpectrumHookConfig, HookScript } from '../../types/hooks-advanced.js';
 /**
- * Generates the Stop hook script — auto-commits planu/ on session end.
+ * Generates the Stop hook script. Planu housekeeping is opt-in so generated
+ * hooks cannot silently stage or commit user branches.
  */
 export declare function generateStopHookScript(projectPath: string): string;
 /**

package/dist/engine/hooks/full-spectrum-generator.js

@@ -3,12 +3,14 @@
 // Individual script builders
 // ---------------------------------------------------------------------------
 /**
- * Generates the Stop hook script — auto-commits planu/ on session end.
+ * Generates the Stop hook script. Planu housekeeping is opt-in so generated
+ * hooks cannot silently stage or commit user branches.
  */
 export function generateStopHookScript(projectPath) {
     return `#!/bin/bash
-# Auto-commit planu/ if there are changes (Planu Stop hook)
+# Optionally auto-commit planu/ if explicitly enabled (Planu Stop hook)
 cd "${projectPath}"
+if [ "$PLANU_ENABLE_AUTOCOMMIT" != "true" ]; then exit 0; fi
 if git diff --quiet planu/ 2>/dev/null; then exit 0; fi
 git add planu/specs/ planu/conventions.json && git commit -m "chore(planu): auto-commit session state [skip ci]" --no-verify
 `;
@@ -73,7 +75,7 @@ export function generateFullSpectrumHooks(config, projectPath = '$CLAUDE_PROJECT
         scripts.push({
             eventType: 'Stop',
             scriptContent: generateStopHookScript(projectPath),
-            description: 'Auto-commits planu/ changes at session end.',
+            description: 'Optionally auto-commits planu/ changes at session end when enabled.',
         });
     }
     if (config.preCompactHook) {