@planu/cli 5.3.2 → 5.3.4

package/dist/storage/runtime-db.d.ts

@@ -167,8 +167,30 @@ export declare class RuntimeDatabase implements Disposable {
         readonly pendingOnly?: boolean;
         readonly limit?: number;
         readonly topics?: readonly string[];
+        /**
+         * When set, applies fence-based eligibility filtering (excludes dead-lettered
+         * records and records whose durable `nextAttemptAt` is still in the future)
+         * BEFORE the LIMIT clause, so ineligible records cannot head-of-line block
+         * an eligible record behind them in the same scope.
+         */
+        readonly eligibleAt?: string;
+        /** Only rows with `id > afterId`, for paginating past ineligible head records. */
+        readonly afterId?: number;
     }): readonly RuntimeOutboxRecord[];
-    listPendingOutboxScopes(): readonly RuntimeOutboxScope[];
+    /**
+     * Counts pending records that would be eligible for delivery right now, without
+     * materializing them. Used to report an exact `skipped` count when a bounded
+     * slice stops early (budget or time), rather than inferring it from the LIMIT.
+     */
+    countEligibleOutbox(projectId: string, workspaceId: string, options: {
+        readonly topics?: readonly string[];
+        readonly eligibleAt: string;
+        readonly afterId?: number;
+    }): number;
+    listPendingOutboxScopes(options?: {
+        readonly topics?: readonly string[];
+        readonly eligibleAt?: string;
+    }): readonly RuntimeOutboxScope[];
     markOutboxDelivered(projectId: string, workspaceId: string, id: number, deliveredAt?: string): boolean;
     appendAudit(input: {
         readonly projectId: string;

package/dist/storage/runtime-db.js

@@ -6,6 +6,36 @@ import { parseValidationReceiptPendingCheckpoint, } from '../types/durable-valid
 const CURRENT_SCHEMA_VERSION = 4;
 const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_CONNECTIONS = 4;
+/**
+ * Joins each outbox row to its fence record (stored as a `mutation` runtime record
+ * keyed `outbox-fence:<id>`) so eligibility can be evaluated in SQL before LIMIT.
+ */
+const OUTBOX_FENCE_JOIN = `
+         LEFT JOIN runtime_records fence
+           ON fence.project_id = o.project_id AND fence.workspace_id = o.workspace_id
+              AND fence.kind = 'mutation' AND fence.record_key = 'outbox-fence:' || o.id`;
+/**
+ * Excludes dead-lettered records and records whose durable `nextAttemptAt` retry
+ * deadline is still in the future. Records with no fence, or a fence without
+ * `nextAttemptAt` (schemaVersion 1 legacy), remain eligible.
+ *
+ * A fence with invalid JSON, or a `nextAttemptAt` that is not ISO-8601-shaped,
+ * is deliberately left ELIGIBLE rather than filtered: a non-ISO string compares
+ * lexicographically against the `?` bound and can hide the record from every
+ * future slice, so malformed fences must surface to claim()/parseFence as a
+ * `Corrupt` failure instead of vanishing silently.
+ */
+const OUTBOX_ELIGIBILITY_CLAUSE = `
+           AND (fence.value_json IS NULL
+                OR NOT json_valid(fence.value_json)
+                OR json_extract(fence.value_json, '$.state') IS NULL
+                OR json_extract(fence.value_json, '$.state') != 'dead-letter')
+           AND (fence.value_json IS NULL
+                OR NOT json_valid(fence.value_json)
+                OR json_extract(fence.value_json, '$.nextAttemptAt') IS NULL
+                OR json_extract(fence.value_json, '$.nextAttemptAt')
+                     NOT GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*'
+                OR json_extract(fence.value_json, '$.nextAttemptAt') <= ?)`;
 const openConnections = new Map();
 let integrityCheckedOpens = 0;
 let integrityBypassedOpens = 0;
@@ -746,20 +776,60 @@ export class RuntimeDatabase {
             requireIdentifier(topic, 'outbox topic');
         }
         const topicsClause = topics.length > 0 ? ` AND topic IN (${topics.map(() => '?').join(', ')})` : '';
+        const afterClause = options.afterId !== undefined ? ' AND o.id > ?' : '';
+        const afterParams = options.afterId !== undefined ? [options.afterId] : [];
+        const eligibilityJoin = options.eligibleAt !== undefined ? OUTBOX_FENCE_JOIN : '';
+        const eligibilityClause = options.eligibleAt !== undefined ? OUTBOX_ELIGIBILITY_CLAUSE : '';
+        const eligibilityParams = options.eligibleAt !== undefined ? [options.eligibleAt] : [];
         const rows = this.database
-            .prepare(`SELECT id, project_id, workspace_id, topic, payload_json, created_at, delivered_at
-         FROM outbox
-         WHERE project_id = ? AND workspace_id = ?${pendingClause}${topicsClause}
-         ORDER BY id LIMIT ?`)
-            .all(projectId, workspaceId, ...topics, limit);
+            .prepare(`SELECT o.id AS id, o.project_id AS project_id, o.workspace_id AS workspace_id,
+                o.topic AS topic, o.payload_json AS payload_json,
+                o.created_at AS created_at, o.delivered_at AS delivered_at
+         FROM outbox o${eligibilityJoin}
+         WHERE o.project_id = ? AND o.workspace_id = ?${pendingClause}${topicsClause}${afterClause}${eligibilityClause}
+         ORDER BY o.id LIMIT ?`)
+            .all(projectId, workspaceId, ...topics, ...afterParams, ...eligibilityParams, limit);
         return rows.map(mapOutboxRow);
     }
-    listPendingOutboxScopes() {
+    /**
+     * Counts pending records that would be eligible for delivery right now, without
+     * materializing them. Used to report an exact `skipped` count when a bounded
+     * slice stops early (budget or time), rather than inferring it from the LIMIT.
+     */
+    countEligibleOutbox(projectId, workspaceId, options) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        const topics = options.topics ?? [];
+        for (const topic of topics) {
+            requireIdentifier(topic, 'outbox topic');
+        }
+        const topicsClause = topics.length > 0 ? ` AND o.topic IN (${topics.map(() => '?').join(', ')})` : '';
+        const afterClause = options.afterId !== undefined ? ' AND o.id > ?' : '';
+        const afterParams = options.afterId !== undefined ? [options.afterId] : [];
+        const row = this.database
+            .prepare(`SELECT COUNT(*) AS count
+         FROM outbox o${OUTBOX_FENCE_JOIN}
+         WHERE o.project_id = ? AND o.workspace_id = ? AND o.delivered_at IS NULL${topicsClause}${afterClause}${OUTBOX_ELIGIBILITY_CLAUSE}`)
+            .get(projectId, workspaceId, ...topics, ...afterParams, options.eligibleAt);
+        return row.count;
+    }
+    listPendingOutboxScopes(options = {}) {
         this.assertOpen();
+        const topics = options.topics ?? [];
+        for (const topic of topics) {
+            requireIdentifier(topic, 'outbox topic');
+        }
+        const topicsClause = topics.length > 0 ? ` AND o.topic IN (${topics.map(() => '?').join(', ')})` : '';
+        const eligibilityJoin = options.eligibleAt !== undefined ? OUTBOX_FENCE_JOIN : '';
+        const eligibilityClause = options.eligibleAt !== undefined ? OUTBOX_ELIGIBILITY_CLAUSE : '';
+        const eligibilityParams = options.eligibleAt !== undefined ? [options.eligibleAt] : [];
         return this.database
-            .prepare(`SELECT DISTINCT project_id AS projectId, workspace_id AS workspaceId
-         FROM outbox WHERE delivered_at IS NULL ORDER BY project_id, workspace_id`)
-            .all();
+            .prepare(`SELECT DISTINCT o.project_id AS projectId, o.workspace_id AS workspaceId
+         FROM outbox o${eligibilityJoin}
+         WHERE o.delivered_at IS NULL${topicsClause}${eligibilityClause}
+         ORDER BY o.project_id, o.workspace_id`)
+            .all(...topics, ...eligibilityParams);
     }
     markOutboxDelivered(projectId, workspaceId, id, deliveredAt = new Date().toISOString()) {
         this.assertOpen();

package/dist/tools/create-spec/post-creation.js

@@ -8,6 +8,8 @@ import { incrementSpecCount } from '../../engine/autopilot/state-updater.js';
 import { join } from 'node:path';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
+import { getRuntimePolicy } from '../../engine/runtime-policy.js';
+import { redactText } from '../../security/redactor.js';
 import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../../engine/token-optimizer/index.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
@@ -52,7 +54,9 @@ export async function buildInitialTokenWasteMetadata(specId, projectPath, descri
 }
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export async function setupGitBranch(projectId, specId) {
-    const result = await tryAutoSetupGit(projectId, specId);
+    // SPEC-1396: runs from durable outbox delivery (including startup recovery) — never
+    // move the shared checkout, or replaying a backlog walks HEAD through every spec branch.
+    const result = await tryAutoSetupGit(projectId, specId, { mutateCheckout: false });
     /* v8 ignore start -- requires real git repo */
     if (result) {
         return { branch: result.branch, data: result.data };
@@ -254,7 +258,8 @@ export async function runAutopilotAnalysis(specId, projectPath, description) {
         });
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
+        const raw = err instanceof Error ? err.message : String(err);
+        const error = redactText(raw).slice(0, getRuntimePolicy().outbox.diagnosticMaxLength);
         await appendAutopilotLogEntry(projectId, {
             specId,
             hookName: ASYNC_ANALYSIS_HOOK,

package/dist/tools/create-spec/spec-created-outbox-consumer.d.ts

@@ -11,4 +11,6 @@ export declare class SpecCreatedOutboxConsumer {
 }
 export declare function drainSpecCreatedOutbox(databasePath?: string): Promise<void>;
 export declare function startSpecCreatedOutboxConsumer(): Promise<void>;
+/** Test-only: clear scheduler state so fixtures do not leak timers across tests. */
+export declare function resetSpecCreatedOutboxSchedulerForTests(): void;
 //# sourceMappingURL=spec-created-outbox-consumer.d.ts.map

package/dist/tools/create-spec/spec-created-outbox-consumer.js

@@ -6,6 +6,13 @@ import { specStore } from '../../storage/index.js';
 import { runAutopilotAnalysis, setupGitBranch } from './post-creation.js';
 import { SPEC_CREATED_POST_COMMIT_TASKS, } from '../../types/outbox-worker.js';
 import { TransactionalOutboxWorker } from '../../engine/execution/outbox-worker.js';
+import { getRuntimePolicy } from '../../engine/runtime-policy.js';
+import { redactText } from '../../security/redactor.js';
+const SPEC_CREATED_TOPICS = ['spec.created'];
+/** Redact and bound a raw thrown diagnostic before it reaches durable storage. */
+function sanitizeDiagnostic(message) {
+    return redactText(message).slice(0, getRuntimePolicy().outbox.diagnosticMaxLength);
+}
 export { SPEC_CREATED_POST_COMMIT_TASKS } from '../../types/outbox-worker.js';
 const RESPONSE_ONLY_REASON = 'Advisory task is intentionally terminal because it has no durable post-commit side effect.';
 function isObject(value) {
@@ -123,6 +130,7 @@ export class SpecCreatedOutboxConsumer {
                 });
             }
             catch (error) {
+                const raw = error instanceof Error ? error.message : String(error);
                 this.database.appendAudit({
                     projectId: payload.projectId,
                     workspaceId: 'default',
@@ -130,7 +138,7 @@ export class SpecCreatedOutboxConsumer {
                     payload: {
                         deliveryKey: context.deliveryKey,
                         task,
-                        error: error instanceof Error ? error.message : String(error),
+                        error: sanitizeDiagnostic(raw),
                     },
                 });
                 throw error;
@@ -140,6 +148,8 @@ export class SpecCreatedOutboxConsumer {
 }
 let interval;
 let activeDrain;
+let continuationTimer;
+let rotationCursor = 0;
 export function drainSpecCreatedOutbox(databasePath = resolveStorageLayout().runtimeDatabase) {
     if (activeDrain) {
         return activeDrain;
@@ -147,11 +157,7 @@ export function drainSpecCreatedOutbox(databasePath = resolveStorageLayout().run
     activeDrain = (async () => {
         const database = new RuntimeDatabase({ path: databasePath });
         try {
-            const consumer = new SpecCreatedOutboxConsumer(database);
-            for (const scope of database.listPendingOutboxScopes()) {
-                const worker = new TransactionalOutboxWorker(database, scope.projectId, scope.workspaceId, `spec-created-${process.pid}-${randomUUID()}`);
-                await worker.drain((context) => consumer.deliver(context), { topics: ['spec.created'] });
-            }
+            await drainBoundedSlice(database, databasePath);
         }
         finally {
             database.close();
@@ -161,6 +167,75 @@ export function drainSpecCreatedOutbox(databasePath = resolveStorageLayout().run
     });
     return activeDrain;
 }
+/**
+ * Processes one bounded, fair slice of the spec.created backlog: round-robins
+ * pending scopes one eligible record at a time (SQL already excludes dead-lettered
+ * and not-yet-due records, so a poison record cannot head-of-line block a healthy
+ * scope) until the record or elapsed-time budget is exhausted. If work remains,
+ * schedules a single unref()'d continuation instead of blocking the caller.
+ */
+async function drainBoundedSlice(database, databasePath) {
+    const policy = getRuntimePolicy().outbox;
+    const consumer = new SpecCreatedOutboxConsumer(database);
+    const discovered = database.listPendingOutboxScopes({
+        topics: [...SPEC_CREATED_TOPICS],
+        eligibleAt: new Date().toISOString(),
+    });
+    if (discovered.length === 0) {
+        return;
+    }
+    const offset = rotationCursor % discovered.length;
+    const activeScopes = [...discovered.slice(offset), ...discovered.slice(0, offset)];
+    const startedAtMs = Date.now();
+    let recordBudget = policy.sliceRecordBudget;
+    let turnsTaken = 0;
+    let index = 0;
+    while (activeScopes.length > 0 && recordBudget > 0) {
+        if (Date.now() - startedAtMs > policy.sliceTimeBudgetMs) {
+            break;
+        }
+        const position = index % activeScopes.length;
+        const scope = activeScopes[position];
+        if (!scope) {
+            break;
+        }
+        const worker = new TransactionalOutboxWorker(database, scope.projectId, scope.workspaceId, `spec-created-${process.pid}-${randomUUID()}`);
+        const result = await worker.drain((context) => consumer.deliver(context), {
+            topics: [...SPEC_CREATED_TOPICS],
+            limit: 1,
+        });
+        turnsTaken += 1;
+        // Only actually-processed records consume the pass budget; ineligible-only
+        // turns (foreign lease, self-healed delivered fence) are free.
+        recordBudget -= result.delivered + result.failed;
+        if (result.exhausted) {
+            // No eligible record remains in this scope right now — drop it from this
+            // pass's rotation instead of spinning on it. A failed-but-not-exhausted
+            // scope stays in rotation so a poison record cannot block healthy work
+            // behind it.
+            activeScopes.splice(position, 1);
+            continue;
+        }
+        index += 1;
+    }
+    rotationCursor += turnsTaken;
+    if (activeScopes.length > 0) {
+        scheduleContinuation(databasePath);
+    }
+}
+function scheduleContinuation(databasePath) {
+    if (continuationTimer) {
+        return;
+    }
+    const policy = getRuntimePolicy().outbox;
+    continuationTimer = setTimeout(() => {
+        continuationTimer = undefined;
+        void drainSpecCreatedOutbox(databasePath).catch((error) => {
+            console.error('[Planu] spec.created outbox continuation failed:', error);
+        });
+    }, policy.continuationDelayMs);
+    continuationTimer.unref();
+}
 export async function startSpecCreatedOutboxConsumer() {
     await drainSpecCreatedOutbox();
     if (interval) {
@@ -173,4 +248,17 @@ export async function startSpecCreatedOutboxConsumer() {
     }, 30_000);
     interval.unref();
 }
+/** Test-only: clear scheduler state so fixtures do not leak timers across tests. */
+export function resetSpecCreatedOutboxSchedulerForTests() {
+    if (interval) {
+        clearInterval(interval);
+        interval = undefined;
+    }
+    if (continuationTimer) {
+        clearTimeout(continuationTimer);
+        continuationTimer = undefined;
+    }
+    activeDrain = undefined;
+    rotationCursor = 0;
+}
 //# sourceMappingURL=spec-created-outbox-consumer.js.map

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/create-spec.js

@@ -1030,6 +1030,11 @@ async function prepareCreateSpecCandidate(initialParams, server) {
         },
     }));
     spec.generation = generatedSpec.generation;
+    // SPEC-1406 (DEFECT 4, round 2): FallbackGenerator no longer emits an unconditional
+    // warning, so qualityWarnings only needs the non-empty guard now — the redundant
+    // constant-string filter was removed from create-spec.ts, fallback-generator.ts and
+    // opus-generator.ts (dead code, reverted) so the literal doesn't have to stay
+    // byte-identical across three files.
     spec.qualityWarnings =
         generatedSpec.qualityWarnings.length > 0 ? generatedSpec.qualityWarnings : undefined;
     const baseCriteria = extractCriteria(generatedSpec.specBody).map((criterion) => criterion.text);

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/update-status/evidence-gate.js

@@ -68,7 +68,7 @@ import { captureValidationFreshnessLease } from '../../engine/validation/validat
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
 import { checkReconciliationFreshness } from '../../engine/evidence-gates/reconciliation-freshness.js';
 import { extractCanonicalFileOwnership } from '../../engine/handoff-packager.js';
-import { generateDiscoverySkeleton, generateTaskPlanSkeleton, writeEvidenceSkeleton, } from '../../engine/evidence-gates/evidence-skeletons.js';
+import { generateTaskPlanSkeleton, writeEvidenceSkeleton, } from '../../engine/evidence-gates/evidence-skeletons.js';
 import { extractSection } from '../../engine/spec-format/markdown-sections.js';
 const CANONICAL_SCOPE_PATH = /(?:src|tests|scripts|website)\/[\w/.@-]+\.\w+/g;
 /** SPEC-1356: repo-relative paths mentioned in the spec's Problem/Technical prose also count
@@ -187,28 +187,21 @@ function isArtifactAbsent(artifacts, label) {
     return !artifacts.invalidArtifacts.some((entry) => entry.startsWith(label));
 }
 /**
- * SPEC-1356: self-heal missing (not malformed) discovery/task-plan handoff evidence by
- * generating a schema-valid skeleton and persisting it, instead of blocking the transition
- * on a manual authoring step. Malformed existing artifacts still fail the gate as before.
+ * SPEC-1356: self-heal missing (not malformed) task-plan handoff evidence by generating a
+ * schema-valid skeleton and persisting it, instead of blocking the transition on a manual
+ * authoring step. Malformed existing artifacts still fail the gate as before.
+ *
+ * SPEC-1406 (DEFECT 3): discovery evidence for `approved` is intentionally NOT self-healed —
+ * writing a skeleton here made the blocking discovery gate self-certify by fabricating the
+ * evidence it was supposed to require. `checkLifecycleEvidenceGate` (lifecycle-gate.ts) reports
+ * `discovery_missing` with the specific missing fields named when discovery is absent, and that
+ * is the intended, honest outcome.
  */
 async function autofillMissingEvidenceSkeletons(args) {
     if (args.spec.scope === 'trivial') {
         return args.artifacts;
     }
     let artifacts = args.artifacts;
-    if (args.transition === 'approved' &&
-        !artifacts.discovery &&
-        isArtifactAbsent(artifacts, 'Discovery evidence')) {
-        const skeleton = generateDiscoverySkeleton({ spec: args.spec, body: args.body });
-        await writeEvidenceSkeleton({
-            projectId: args.projectId,
-            specId: args.specId,
-            filename: 'discovery.json',
-            artifact: skeleton,
-        });
-        console.warn('[planu:evidence-skeleton]', { specId: args.specId, filename: 'discovery.json' });
-        artifacts = { ...artifacts, discovery: skeleton };
-    }
     if (args.transition === 'implementing' &&
         !artifacts.taskPlan &&
         isArtifactAbsent(artifacts, 'Task plan evidence')) {