@planu/cli 5.3.1 → 5.3.3

package/dist/tools/create-spec-helpers.d.ts

@@ -1,9 +1,9 @@
-import type { GitSetupResult } from '../types/index.js';
+import type { GitSetupResult, GitAutoSetupOptions } from '../types/index.js';
 export declare function slugify(text: string): string;
 export declare function generateSpecId(existingSpecs: {
     id: string;
 }[]): string;
 export declare function generateBranchName(specId: string, slug: string, type: string): string;
 /** Try auto-setup git branch. Returns result or undefined on failure. */
-export declare function tryAutoSetupGit(projectId: string, specId: string): Promise<GitSetupResult | undefined>;
+export declare function tryAutoSetupGit(projectId: string, specId: string, options?: GitAutoSetupOptions): Promise<GitSetupResult | undefined>;
 //# sourceMappingURL=create-spec-helpers.d.ts.map

package/dist/tools/create-spec-helpers.js

@@ -29,10 +29,10 @@ export function generateBranchName(specId, slug, type) {
     return `${BRANCH_PREFIXES[type] ?? 'feat'}/${specId.toLowerCase()}-${slug}`;
 }
 /** Try auto-setup git branch. Returns result or undefined on failure. */
-export async function tryAutoSetupGit(projectId, specId) {
+export async function tryAutoSetupGit(projectId, specId, options) {
     /* v8 ignore start -- requires real git repo with branches */
     try {
-        const r = await handleAutoSetup(projectId, specId);
+        const r = await handleAutoSetup(projectId, specId, undefined, options);
         if (!r.isError && r.content[0]?.type === 'text') {
             const data = JSON.parse(r.content[0].text);
             if (typeof data.newBranch !== 'string') {

package/dist/tools/git/branch-ops.d.ts

@@ -1,12 +1,16 @@
-import type { ToolResult, GitConfig } from '../../types/index.js';
-export declare function handleCreateBranch(projectId: string, specId: string | undefined, config?: GitConfig, resolvedProjectPath?: string): Promise<ToolResult>;
+import type { ToolResult, GitConfig, GitAutoSetupOptions } from '../../types/index.js';
+export declare function handleCreateBranch(projectId: string, specId: string | undefined, config?: GitConfig, resolvedProjectPath?: string, options?: GitAutoSetupOptions): Promise<ToolResult>;
 export declare function handleCheckBranch(projectId: string, _specId: string | undefined, config?: GitConfig): Promise<ToolResult>;
 /**
  * Auto-setup: detect git workflow, sync base branch, create feature branch.
  * Combines detectGitFlowType + resolveBaseBranch + fetch/pull + create-branch
  * into a single atomic operation for spec creation.
+ *
+ * SPEC-1396: `mutateCheckout: false` creates the branch ref without touching HEAD
+ * or the working tree. Automatic callers (outbox recovery, cascades) MUST use it —
+ * a background checkout silently moves the shared checkout onto a foreign branch.
  */
-export declare function handleAutoSetup(projectId: string, specId: string | undefined, config?: GitConfig): Promise<ToolResult>;
+export declare function handleAutoSetup(projectId: string, specId: string | undefined, config?: GitConfig, options?: GitAutoSetupOptions): Promise<ToolResult>;
 /**
  * Returns a structured worktree-start payload with commands/paths so the caller
  * knows exactly how to spin up an isolated Claude Code session.

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

@@ -19,10 +19,11 @@ function randomSuffix() {
         .toString(16)
         .padStart(8, '0');
 }
-export async function handleCreateBranch(projectId, specId, config, resolvedProjectPath) {
+export async function handleCreateBranch(projectId, specId, config, resolvedProjectPath, options) {
     if (!specId) {
         return compactError('❌ Error: specId is required for create-branch action');
     }
+    const mutateCheckout = options?.mutateCheckout ?? true;
     const suppliedPath = resolvedProjectPath?.trim();
     const projectPath = suppliedPath && suppliedPath.length > 0 ? suppliedPath : await resolveProjectPath(projectId);
     const spec = await specStore.getSpec(projectId, specId);
@@ -40,11 +41,18 @@ export async function handleCreateBranch(projectId, specId, config, resolvedProj
     try {
         const { stdout } = await git(projectPath, ['branch', '--list', branchName]);
         if (stdout.trim().length > 0) {
-            await git(projectPath, ['checkout', branchName]);
+            if (mutateCheckout) {
+                await git(projectPath, ['checkout', branchName]);
+            }
+            // Record the branch even when it already exists — otherwise callers keep re-entering
+            // this path and a background checkout is retried forever.
+            await specStore.updateSpec(projectId, specId, { gitBranch: branchName });
             const result = {
                 action: 'create-branch',
                 branchName,
-                message: `Switched to existing branch '${branchName}'`,
+                message: mutateCheckout
+                    ? `Switched to existing branch '${branchName}'`
+                    : `Branch '${branchName}' already exists (checkout left untouched)`,
             };
             return compactResult(formatKeyValue(result));
         }
@@ -52,7 +60,14 @@ export async function handleCreateBranch(projectId, specId, config, resolvedProj
     catch {
         // branch list failed — proceed with creation
     }
-    await git(projectPath, ['checkout', '-b', branchName]);
+    if (mutateCheckout) {
+        await git(projectPath, ['checkout', '-b', branchName]);
+    }
+    else {
+        // SPEC-1396: automatic caller — cut the branch from the resolved base without moving HEAD.
+        const base = await resolveBaseBranch(projectPath, mergeConfig(config).baseBranch);
+        await git(projectPath, base ? ['branch', branchName, base] : ['branch', branchName]);
+    }
     await specStore.updateSpec(projectId, specId, { gitBranch: branchName });
     const result = {
         action: 'create-branch',
@@ -117,14 +132,19 @@ async function hasDirtyState(projectPath) {
  * Auto-setup: detect git workflow, sync base branch, create feature branch.
  * Combines detectGitFlowType + resolveBaseBranch + fetch/pull + create-branch
  * into a single atomic operation for spec creation.
+ *
+ * SPEC-1396: `mutateCheckout: false` creates the branch ref without touching HEAD
+ * or the working tree. Automatic callers (outbox recovery, cascades) MUST use it —
+ * a background checkout silently moves the shared checkout onto a foreign branch.
  */
-export async function handleAutoSetup(projectId, specId, config) {
+export async function handleAutoSetup(projectId, specId, config, options) {
     if (!specId) {
         return compactError('❌ Error: specId is required for auto-setup action');
     }
+    const mutateCheckout = options?.mutateCheckout ?? true;
     const projectPath = await resolveProjectPath(projectId);
     // Check for dirty state — abort if uncommitted changes exist
-    if (await hasDirtyState(projectPath)) {
+    if (mutateCheckout && (await hasDirtyState(projectPath))) {
         return compactError('❌ Error: Working tree has uncommitted changes. Commit or stash them before auto-setup.\nSuggestion: git stash or git commit your changes first');
     }
     const spec = await specStore.getSpec(projectId, specId);
@@ -139,16 +159,39 @@ export async function handleAutoSetup(projectId, specId, config) {
     if (!baseBranch) {
         return compactError('❌ Error: No base branch found (develop/main/master). Is this a git repository?');
     }
-    // 3. Switch to base branch and sync with remote
-    await git(projectPath, ['checkout', baseBranch]);
+    // 3. Sync base branch with remote (switching only when the caller owns the checkout)
     let syncedBase = false;
-    try {
-        await git(projectPath, ['fetch', 'origin', baseBranch]);
-        await git(projectPath, ['pull', '--ff-only', 'origin', baseBranch]);
-        syncedBase = true;
+    let baseRef = baseBranch;
+    if (mutateCheckout) {
+        await git(projectPath, ['checkout', baseBranch]);
+        try {
+            await git(projectPath, ['fetch', 'origin', baseBranch]);
+            await git(projectPath, ['pull', '--ff-only', 'origin', baseBranch]);
+            syncedBase = true;
+        }
+        catch {
+            // No remote or fetch failed — continue with local base (offline-friendly)
+        }
     }
-    catch {
-        // No remote or fetch failed — continue with local base (offline-friendly)
+    else {
+        try {
+            // Fast-forwards the local base ref without touching HEAD or the working tree.
+            await git(projectPath, ['fetch', 'origin', `${baseBranch}:${baseBranch}`]);
+            syncedBase = true;
+        }
+        catch {
+            // git refuses the refspec when the base is the branch currently checked out. Fetch the
+            // remote-tracking ref instead and cut the feature branch from it.
+            try {
+                await git(projectPath, ['fetch', 'origin', baseBranch]);
+                await git(projectPath, ['rev-parse', '--verify', `origin/${baseBranch}`]);
+                baseRef = `origin/${baseBranch}`;
+                syncedBase = true;
+            }
+            catch {
+                // No remote or offline — use the local base as-is.
+            }
+        }
     }
     // 4. Create feature branch from the updated base
     const prefixes = mergedConfig.branchPrefix ?? DEFAULT_BRANCH_PREFIXES;
@@ -160,14 +203,19 @@ export async function handleAutoSetup(projectId, specId, config) {
     try {
         const { stdout } = await git(projectPath, ['branch', '--list', branchName]);
         if (stdout.trim().length > 0) {
-            await git(projectPath, ['checkout', branchName]);
+            if (mutateCheckout) {
+                await git(projectPath, ['checkout', branchName]);
+            }
+            await specStore.updateSpec(projectId, specId, { gitBranch: branchName });
             const result = {
                 action: 'auto-setup',
                 gitFlowType,
                 baseBranch,
                 newBranch: branchName,
                 syncedBase,
-                message: `Switched to existing branch '${branchName}' (${gitFlowType} workflow detected)`,
+                message: mutateCheckout
+                    ? `Switched to existing branch '${branchName}' (${gitFlowType} workflow detected)`
+                    : `Branch '${branchName}' already exists (checkout left untouched)`,
             };
             return compactResult(formatKeyValue(result));
         }
@@ -175,7 +223,7 @@ export async function handleAutoSetup(projectId, specId, config) {
     catch {
         // branch list failed — proceed with creation
     }
-    await git(projectPath, ['checkout', '-b', branchName]);
+    await git(projectPath, mutateCheckout ? ['checkout', '-b', branchName] : ['branch', branchName, baseRef]);
     await specStore.updateSpec(projectId, specId, { gitBranch: branchName });
     const result = {
         action: 'auto-setup',
@@ -183,7 +231,9 @@ export async function handleAutoSetup(projectId, specId, config) {
         baseBranch,
         newBranch: branchName,
         syncedBase,
-        message: `Created branch '${branchName}' from '${baseBranch}' (${gitFlowType} workflow detected)`,
+        message: mutateCheckout
+            ? `Created branch '${branchName}' from '${baseBranch}' (${gitFlowType} workflow detected)`
+            : `Created branch '${branchName}' from '${baseBranch}' without switching the checkout`,
     };
     return compactResult(formatKeyValue(result));
 }

package/dist/tools/package-handoff.d.ts

@@ -1,3 +1,4 @@
-import type { ToolResult, PackageHandoffInput } from '../types/index.js';
+import type { ToolResult, PackageHandoffInput, HandoffPackage } from '../types/index.js';
+export declare function formatHandoff(pkg: HandoffPackage): string;
 export declare function handlePackageHandoff(args: PackageHandoffInput): Promise<ToolResult>;
 //# sourceMappingURL=package-handoff.d.ts.map

package/dist/tools/package-handoff.js

@@ -8,7 +8,7 @@ import { appendTransitionEvent } from '../storage/transition-log.js';
 import { formatProjectGraphContext, queryProjectGraphSlice, } from '../engine/project-graph/index.js';
 import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '../engine/minimality/index.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
-function formatHandoff(pkg) {
+export function formatHandoff(pkg) {
     const lines = [];
     lines.push(`# Implementation Handoff Package — ${pkg.specId}`);
     lines.push('');
@@ -59,6 +59,19 @@ function formatHandoff(pkg) {
         lines.push('_(None identified)_');
     }
     lines.push('');
+    lines.push('## Test Files');
+    lines.push('');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+    const filesToTest = pkg.filesToTest ?? [];
+    if (filesToTest.length > 0) {
+        for (const f of filesToTest) {
+            lines.push(`- ${f}`);
+        }
+    }
+    else {
+        lines.push('_(None identified)_');
+    }
+    lines.push('');
     lines.push('## Ownership');
     lines.push('');
     if (pkg.ownership.length > 0) {
@@ -152,7 +165,9 @@ function buildHandoffSummaryText(args) {
     if (args.pkg.contextHash) {
         lines.push(`Context Hash: ${args.pkg.contextHash}`);
     }
-    lines.push(`Counts: ${String(args.pkg.criteria.length)} criteria, ${String(args.pkg.filesToModify.length)} files to modify, ${String(args.pkg.filesToCreate.length)} files to create, ${String(args.pkg.testPlan.length)} tests, ${String(args.pkg.risks.length)} risks.`);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+    const filesToTestCount = (args.pkg.filesToTest ?? []).length;
+    lines.push(`Counts: ${String(args.pkg.criteria.length)} criteria, ${String(args.pkg.filesToModify.length)} files to modify, ${String(args.pkg.filesToCreate.length)} files to create, ${String(filesToTestCount)} files to test, ${String(args.pkg.testPlan.length)} tests, ${String(args.pkg.risks.length)} risks.`);
     if (args.topBlockers.length > 0) {
         lines.push(`Top blockers: ${args.topBlockers.join('; ')}`);
     }
@@ -238,7 +253,8 @@ async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
         const context = analyzeContextPreflight({
             action: 'package_handoff',
             policy,
-            candidates: [...pkg.filesToModify, ...pkg.filesToCreate].map((path) => ({
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+            candidates: [...pkg.filesToModify, ...pkg.filesToCreate, ...(pkg.filesToTest ?? [])].map((path) => ({
                 path,
                 reason: 'Referenced by handoff package.',
             })),
@@ -297,7 +313,8 @@ async function buildMinimalImplementationReport(pkg, knowledge, spec, handoffTex
             specId: spec.id,
             specRisk: spec.risk,
             handoffText,
-            files: [...pkg.filesToModify, ...pkg.filesToCreate].map((path) => ({ path, content: path })),
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+            files: [...pkg.filesToModify, ...pkg.filesToCreate, ...(pkg.filesToTest ?? [])].map((path) => ({ path, content: path })),
             evidence,
         });
     }
@@ -421,6 +438,8 @@ export async function handlePackageHandoff(args) {
                 criteria: pkgWithScore.criteria.length,
                 filesToModify: pkgWithScore.filesToModify.length,
                 filesToCreate: pkgWithScore.filesToCreate.length,
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+                filesToTest: (pkgWithScore.filesToTest ?? []).length,
                 ownership: pkgWithScore.ownership.length,
                 testPlan: pkgWithScore.testPlan.length,
                 risks: pkgWithScore.risks.length,

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

@@ -11,6 +11,7 @@ import { safe } from './safe-handler.js';
 import { handleCreateRule } from './create-rule.js';
 import { handleCreateSkill } from './create-skill.js';
 import { handleReconcileUniversalRules } from './reconcile-universal-rules.js';
+import { registerBumpSpecVersionTool } from './bump-spec-version.js';
 import { registerPrompts } from '../prompts/index.js';
 import { OFFICIAL_SDD_TOOL_NAMES } from './tool-registry/inventory.js';
 export { OFFICIAL_SDD_TOOL_NAMES } from './tool-registry/inventory.js';
@@ -110,6 +111,7 @@ export function registerSddTools(server) {
     registerOnly(server, OFFICIAL_SDD_TOOL_SET, registerQualityComplianceGroupTools);
     registerOnly(server, OFFICIAL_SDD_TOOL_SET, registerInfraGroupTools);
     registerOnly(server, OFFICIAL_SDD_TOOL_SET, registerUniversalRulesTools);
+    registerOnly(server, OFFICIAL_SDD_TOOL_SET, registerBumpSpecVersionTool);
     registerPrompts(server);
 }
 //# sourceMappingURL=register-sdd-tools.js.map

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

@@ -54,11 +54,13 @@ export async function runImplementingSideEffects(projectId, specId, transitionPr
         let branchResult;
         try {
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            branchResult = await withAudit(projectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId, undefined, projectPath), (r) => ({ isError: r.isError }));
+            branchResult = await withAudit(projectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId, undefined, projectPath, { mutateCheckout: false }), (r) => ({ isError: r.isError }));
         }
         catch {
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            branchResult = await handleCreateBranch(projectId, specId, undefined, projectPath);
+            branchResult = await handleCreateBranch(projectId, specId, undefined, projectPath, {
+                mutateCheckout: false,
+            });
         }
         if (!branchResult.isError) {
             try {

package/dist/types/git.d.ts

@@ -144,6 +144,10 @@ export interface GitSetupResult {
     data: Record<string, unknown>;
     branch: string;
 }
+/** SPEC-1396: automatic callers set `mutateCheckout: false` so the shared checkout never moves. */
+export interface GitAutoSetupOptions {
+    mutateCheckout?: boolean;
+}
 export interface AutoSetupResult {
     action: 'auto-setup';
     gitFlowType: GitFlowType;

package/dist/types/outbox-worker.d.ts

@@ -12,6 +12,8 @@ export interface OutboxFenceRecord {
     readonly state: 'leased' | 'failed' | 'dead-letter' | 'delivered';
     readonly attempts?: number;
     readonly lastError?: string;
+    /** Durable retry deadline (ISO timestamp). Only set for `failed` fences; optional for schemaVersion 1 compatibility. */
+    readonly nextAttemptAt?: string;
 }
 export declare const SPEC_CREATED_POST_COMMIT_TASKS: readonly ['git-setup', 'analysis', 'quality-score', 'duplicate-detection', 'complexity-advice', 'prior-decisions', 'suggestions', 'challenge-readiness'];
 export type SpecCreatedPostCommitTask = (typeof SPEC_CREATED_POST_COMMIT_TASKS)[number];

package/dist/types/readiness.d.ts

@@ -32,6 +32,7 @@ export interface HandoffPackage {
     criteria: string[];
     filesToModify: string[];
     filesToCreate: string[];
+    filesToTest: string[];
     ownership: string[];
     testPlan: string[];
     risks: string[];

package/dist/types/runtime-policy.d.ts

@@ -47,5 +47,14 @@ export interface RuntimePolicy {
         maximumRememberedTransitions: number;
         minimumHeartbeatMs: number;
     };
+    outbox: {
+        sliceRecordBudget: number;
+        sliceTimeBudgetMs: number;
+        backoffBaseMs: number;
+        backoffCapMs: number;
+        maxAttempts: number;
+        diagnosticMaxLength: number;
+        continuationDelayMs: number;
+    };
 }
 //# sourceMappingURL=runtime-policy.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -35,14 +35,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "5.3.1",
-    "@planu/core-darwin-x64": "5.3.1",
-    "@planu/core-linux-arm64-gnu": "5.3.1",
-    "@planu/core-linux-arm64-musl": "5.3.1",
-    "@planu/core-linux-x64-gnu": "5.3.1",
-    "@planu/core-linux-x64-musl": "5.3.1",
-    "@planu/core-win32-arm64-msvc": "5.3.1",
-    "@planu/core-win32-x64-msvc": "5.3.1"
+    "@planu/core-darwin-arm64": "5.3.3",
+    "@planu/core-darwin-x64": "5.3.3",
+    "@planu/core-linux-arm64-gnu": "5.3.3",
+    "@planu/core-linux-arm64-musl": "5.3.3",
+    "@planu/core-linux-x64-gnu": "5.3.3",
+    "@planu/core-linux-x64-musl": "5.3.3",
+    "@planu/core-win32-arm64-msvc": "5.3.3",
+    "@planu/core-win32-x64-msvc": "5.3.3"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

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

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",
@@ -35,7 +35,8 @@
       "triage_feedback",
       "resolve_feedback",
       "sync_feedback",
-      "feedback_status"
+      "feedback_status",
+      "bump_spec_version"
     ],
     "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
     "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],