@shepai/cli 1.37.3 → 1.39.0

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/feature-agent-worker.js

@@ -53,6 +53,10 @@ export function parseWorkerArgs(args) {
     const openPr = args.includes('--open-pr');
     const threadIdx = args.indexOf('--thread-id');
     const threadId = threadIdx !== -1 && threadIdx + 1 < args.length ? args[threadIdx + 1] : undefined;
+    const resumePayloadIdx = args.indexOf('--resume-payload');
+    const resumePayload = resumePayloadIdx !== -1 && resumePayloadIdx + 1 < args.length
+        ? args[resumePayloadIdx + 1]
+        : undefined;
     return {
         featureId: getArg('feature-id'),
         runId: getArg('run-id'),
@@ -65,6 +69,7 @@ export function parseWorkerArgs(args) {
         resumeFromInterrupt,
         push,
         openPr,
+        resumePayload,
     };
 }
 /** Simple worker logger — writes to stdout which is redirected to log file by the parent. */
@@ -163,8 +168,33 @@ export async function runWorker(args) {
         let result;
         if (args.resume && args.resumeFromInterrupt) {
             // Resume from an interrupt (human-in-the-loop approval)
+            let resumeValue = { approved: true }; // default backward-compatible
+            if (args.resumePayload) {
+                try {
+                    resumeValue = JSON.parse(args.resumePayload);
+                    log(`Resuming with typed payload: ${args.resumePayload.slice(0, 200)}`);
+                }
+                catch (e) {
+                    log(`Warning: Failed to parse --resume-payload, using default approval: ${e}`);
+                }
+            }
+            // Derive state updates from the resume payload so executeNode() can
+            // read _approvalAction from state instead of from interrupt() return
+            // value (fixes the dual-interrupt stale replay bug).
+            const stateUpdate = {};
+            if (typeof resumeValue === 'object' &&
+                resumeValue !== null &&
+                'rejected' in resumeValue &&
+                resumeValue.rejected === true) {
+                stateUpdate._approvalAction = 'rejected';
+                stateUpdate._rejectionFeedback = resumeValue.feedback ?? null;
+            }
+            else {
+                stateUpdate._approvalAction = 'approved';
+                stateUpdate._rejectionFeedback = null;
+            }
             log('Resuming graph from interrupt checkpoint...');
-            result = await graph.invoke(new Command({ resume: { approved: true } }), graphConfig);
+            result = await graph.invoke(new Command({ resume: resumeValue, update: stateUpdate }), graphConfig);
         }
         else if (args.resume) {
             // Resume from error — re-invoke with initial state; LangGraph continues

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.d.ts

@@ -39,9 +39,8 @@ export declare function safeYamlLoad(content: string): unknown;
  * - allowPlan: when true, skip interrupt after plan phase
  * - allowMerge: when true, skip interrupt after merge phase
  *
- * Nodes not covered by a gate (analyze, research) never interrupt.
- * The implement node always interrupts when gates are present
- * (unless all three gates are true, meaning fully autonomous).
+ * Nodes not covered by a gate (analyze, research, implement) never interrupt.
+ * Implementation always proceeds to merge; the merge node handles its own gate.
  *
  */
 export declare function shouldInterrupt(nodeName: string, gates: ApprovalGates | undefined): boolean;
@@ -75,10 +74,27 @@ export declare function retryExecute(executor: IAgentExecutor, prompt: string, o
  * Read completed phases from feature.yaml.
  */
 export declare function getCompletedPhases(specDir: string): string[];
+/**
+ * Remove a phase from completedPhases in feature.yaml.
+ * Used when a phase is rejected and needs to re-execute.
+ */
+export declare function clearCompletedPhase(specDir: string, phaseId: string, log?: NodeLogger): void;
+/**
+ * Type guard to detect rejection payloads from interrupt() return value.
+ */
+export declare function isRejectionPayload(value: unknown): value is {
+    rejected: true;
+    feedback: string;
+};
 /**
  * Mark a phase as complete in feature.yaml by adding its ID to completedPhases.
  */
 export declare function markPhaseComplete(specDir: string, phaseId: string, log?: NodeLogger): void;
+/**
+ * Write a spec file atomically using temp-file-then-rename pattern.
+ * Prevents corruption on crash mid-write.
+ */
+export declare function writeSpecFileAtomic(specDir: string, filename: string, content: string): void;
 /**
  * Execute a node with consistent logging and error handling.
  *

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-helpers.d.ts","sourceRoot":"","sources":["../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,+DAA+D,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AASrD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM;kBAE/B,MAAM,GAAG,IAAI;mBAIZ,MAAM,GAAG,IAAI;EAK/B;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,qBAAqB,CAMpF;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAS3F;AAMD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,GAAG,SAAS,CAAC;AAMhG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAKjE;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,EAC9B,SAAS,CAAC,EAAE,YAAY,GACvB,OAAO,CAAC,oBAAoB,CAAC,CA6B/B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAW5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAwB1F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,UAAU,KAAK,MAAM,GACjE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAiFnE"}
+{"version":3,"file":"node-helpers.d.ts","sourceRoot":"","sources":["../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,+DAA+D,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AASrD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM;kBAE/B,MAAM,GAAG,IAAI;mBAIZ,MAAM,GAAG,IAAI;EAK/B;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,qBAAqB,CAMpF;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAQ3F;AAMD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,GAAG,SAAS,CAAC;AAMhG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAKjE;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,EAC9B,SAAS,CAAC,EAAE,YAAY,GACvB,OAAO,CAAC,oBAAoB,CAAC,CA6B/B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAW5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAqB5F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAOhG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAwB1F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAa5F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,UAAU,KAAK,MAAM,GACjE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAmHnE"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.js

@@ -5,7 +5,7 @@
  * and error handling so every node follows the same patterns.
  */
 import yaml from 'js-yaml';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { interrupt, isGraphBubbleUp } from '@langchain/langgraph';
 import { reportNodeStart } from '../heartbeat.js';
@@ -81,9 +81,8 @@ export function safeYamlLoad(content) {
  * - allowPlan: when true, skip interrupt after plan phase
  * - allowMerge: when true, skip interrupt after merge phase
  *
- * Nodes not covered by a gate (analyze, research) never interrupt.
- * The implement node always interrupts when gates are present
- * (unless all three gates are true, meaning fully autonomous).
+ * Nodes not covered by a gate (analyze, research, implement) never interrupt.
+ * Implementation always proceeds to merge; the merge node handles its own gate.
  *
  */
 export function shouldInterrupt(nodeName, gates) {
@@ -97,8 +96,6 @@ export function shouldInterrupt(nodeName, gates) {
         return !gates.allowPlan;
     if (nodeName === 'merge')
         return !gates.allowMerge;
-    if (nodeName === 'implement')
-        return true;
     return false;
 }
 const API_ERROR_RE = /API Error: (400|429|5\d{2})/;
@@ -169,6 +166,38 @@ export function getCompletedPhases(specDir) {
         return [];
     }
 }
+/**
+ * Remove a phase from completedPhases in feature.yaml.
+ * Used when a phase is rejected and needs to re-execute.
+ */
+export function clearCompletedPhase(specDir, phaseId, log) {
+    try {
+        const content = readSpecFile(specDir, 'feature.yaml');
+        if (!content)
+            return;
+        const data = yaml.load(content);
+        if (!data || typeof data !== 'object')
+            return;
+        const status = (data.status ?? {});
+        const completedPhases = Array.isArray(status.completedPhases)
+            ? status.completedPhases.filter((p) => p !== phaseId)
+            : [];
+        data.status = { ...status, completedPhases };
+        writeFileSync(join(specDir, 'feature.yaml'), yaml.dump(data, { indent: 2, lineWidth: -1 }), 'utf-8');
+    }
+    catch (err) {
+        log?.error(`Failed to clear completed phase: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Type guard to detect rejection payloads from interrupt() return value.
+ */
+export function isRejectionPayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'rejected' in value &&
+        value.rejected === true);
+}
 /**
  * Mark a phase as complete in feature.yaml by adding its ID to completedPhases.
  */
@@ -194,6 +223,26 @@ export function markPhaseComplete(specDir, phaseId, log) {
         log?.error(`Failed to mark phase complete: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Write a spec file atomically using temp-file-then-rename pattern.
+ * Prevents corruption on crash mid-write.
+ */
+export function writeSpecFileAtomic(specDir, filename, content) {
+    const targetPath = join(specDir, filename);
+    const tempPath = join(specDir, `.${filename}.tmp`);
+    try {
+        writeFileSync(tempPath, content, 'utf-8');
+        renameSync(tempPath, targetPath);
+    }
+    finally {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // Temp file already renamed or doesn't exist
+        }
+    }
+}
 /**
  * Execute a node with consistent logging and error handling.
  *
@@ -210,16 +259,46 @@ export function executeNode(nodeName, executor, buildPrompt) {
         // Update feature lifecycle to reflect the current phase
         await updateNodeLifecycle(nodeName);
         // On resume from interrupt, LangGraph re-executes the node function from
-        // the top. Skip the expensive executor call if this phase already completed
-        // (markPhaseComplete is called before interrupt, so completed = done but
-        // awaiting approval; the approval has now been granted).
+        // the top. Instead of re-executing within this invocation (which would
+        // require a second interrupt() call and trigger the stale-replay bug),
+        // we return early. Rejection sets _needsReexecution=true so a conditional
+        // edge in the graph routes back to this node for a fresh invocation.
         const completedPhases = getCompletedPhases(state.specDir);
         if (completedPhases.includes(nodeName)) {
-            log.info('Phase already completed (resuming from approval), skipping execution');
-            return {
-                currentNode: nodeName,
-                messages: [`[${nodeName}] Approved — continuing`],
-            };
+            if (shouldInterrupt(nodeName, state.approvalGates)) {
+                if (state._approvalAction === 'rejected') {
+                    const feedback = state._rejectionFeedback ?? '(no feedback)';
+                    log.info(`Phase rejected with feedback: "${feedback}" — scheduling re-execution`);
+                    clearCompletedPhase(state.specDir, nodeName, log);
+                    // Return early — the conditional edge will route back to this node
+                    // for a fresh invocation with a clean interrupt index.
+                    return {
+                        currentNode: nodeName,
+                        messages: [`[${nodeName}] Rejected — will re-execute`],
+                        _approvalAction: null,
+                        _rejectionFeedback: null,
+                        _needsReexecution: true,
+                    };
+                }
+                else {
+                    log.info('Phase approved, skipping re-execution');
+                    return {
+                        currentNode: nodeName,
+                        messages: [`[${nodeName}] Approved — continuing`],
+                        _approvalAction: null,
+                        _rejectionFeedback: null,
+                        _needsReexecution: false,
+                    };
+                }
+            }
+            else {
+                log.info('Phase already completed (no gate), skipping execution');
+                return {
+                    currentNode: nodeName,
+                    messages: [`[${nodeName}] Approved — continuing`],
+                    _needsReexecution: false,
+                };
+            }
         }
         const startTime = Date.now();
         // Record phase start (no-op if timing context not set)
@@ -236,13 +315,19 @@ export function executeNode(nodeName, executor, buildPrompt) {
             // Record phase completion
             await recordPhaseEnd(timingId, durationMs);
             // Mark phase complete BEFORE interrupting so that on resume the
-            // node detects the work is already done and skips re-execution.
+            // node detects the work is already done and returns early.
             markPhaseComplete(state.specDir, nodeName, log);
             const nodeResult = {
                 currentNode: nodeName,
                 messages: [`[${nodeName}] Complete (${result.result.length} chars, ${elapsed}s)`],
+                _approvalAction: null,
+                _rejectionFeedback: null,
+                _needsReexecution: false,
             };
-            // Human-in-the-loop: interrupt after node execution for review
+            // Human-in-the-loop: interrupt after node execution for review.
+            // This is the ONLY interrupt() call in the entire execution path.
+            // On resume, the node returns early (above) without calling interrupt(),
+            // so there is no stale interrupt replay.
             if (shouldInterrupt(nodeName, state.approvalGates)) {
                 log.info('Interrupting for human approval');
                 await recordApprovalWaitStart(timingId);

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/requirements.prompt.d.ts

@@ -2,7 +2,8 @@
  * Requirements Phase Prompt
  *
  * Instructs the agent to build comprehensive requirements from the analysis,
- * including product questions with AI-recommended default answers.
+ * including product questions with structured QuestionOption[] arrays
+ * and AI-recommended default answers.
  * Writes back to spec.yaml with full requirements.
  */
 import type { FeatureAgentState } from '../../state.js';

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/requirements.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requirements.prompt.d.ts","sourceRoot":"","sources":["../../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/requirements.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CA4GxE"}
+{"version":3,"file":"requirements.prompt.d.ts","sourceRoot":"","sources":["../../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/requirements.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAkKxE"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/requirements.prompt.js

@@ -2,14 +2,40 @@
  * Requirements Phase Prompt
  *
  * Instructs the agent to build comprehensive requirements from the analysis,
- * including product questions with AI-recommended default answers.
+ * including product questions with structured QuestionOption[] arrays
+ * and AI-recommended default answers.
  * Writes back to spec.yaml with full requirements.
  */
+import yaml from 'js-yaml';
 import { readSpecFile } from '../node-helpers.js';
 export function buildRequirementsPrompt(state) {
     const specContent = readSpecFile(state.specDir, 'spec.yaml');
+    // Extract rejection feedback if present
+    let rejectionFeedbackSection = '';
+    try {
+        const specData = yaml.load(specContent);
+        const rejectionFeedback = specData?.rejectionFeedback;
+        if (rejectionFeedback && rejectionFeedback.length > 0) {
+            const entries = rejectionFeedback
+                .map((entry) => `- **Iteration ${entry.iteration}** (${entry.timestamp}): ${entry.message}`)
+                .join('\n');
+            rejectionFeedbackSection = `
+## Previous Rejection Feedback
+
+The user has previously rejected this PRD with the following feedback. You MUST address these concerns in your revised output:
+
+${entries}
+
+Focus on the most recent feedback (highest iteration number) while ensuring earlier feedback is still addressed.
+
+`;
+        }
+    }
+    catch {
+        // If YAML parsing fails, continue without rejection feedback
+    }
     return `You are a product analyst performing the REQUIREMENTS phase of feature development.
-
+${rejectionFeedbackSection}
 ## Your Task
 
 1. Read the current spec with codebase analysis below
@@ -29,13 +55,20 @@ ${specContent}
 - **Non-functional requirements (NFR-N)**: performance, security, UX, maintainability constraints
 - **Success criteria**: measurable checkboxes that define "done"
 
-### Product Questions with AI Defaults
+### Product Questions with Structured Options
 For every ambiguous product decision, create an openQuestion entry with:
 - A clear question
 - resolved: true (your recommendation is the default)
-- Your recommended answer with reasoning
+- Structured options array with EXACTLY ONE option marked selected: true
+- A selectionRationale explaining the recommendation
+- An answer field containing the text of the selected option (for backward compatibility)
+
+Each option MUST have:
+- \`option\`: Short label for the approach (2-5 words)
+- \`description\`: Explanation of this option's trade-offs and benefits
+- \`selected\`: boolean — exactly ONE option per question must be true
 
-The user can later review and override these defaults. This is the AI-recommended path — not the only option.
+The user can later review and override these defaults via interactive TUI.
 
 ## Output Instructions
 
@@ -60,12 +93,28 @@ Write the COMPLETE file. Preserve name/number/branch/technologies from analysis
   relatedLinks: (keep)
 
   openQuestions:
-    - question: 'Should X use approach A or B?'
+    - question: 'Should X use approach A, B, or C?'
       resolved: true
-      answer: 'Recommend A because [rationale]. Alternative: B if [condition].'
+      options:
+        - option: 'Approach A'
+          description: 'Benefits of A, when to use it, trade-offs'
+          selected: true
+        - option: 'Approach B'
+          description: 'Benefits of B, when to use it, trade-offs'
+          selected: false
+      selectionRationale: 'Approach A is recommended because [detailed reasoning]'
+      answer: 'Approach A'
     - question: 'What level of Y is needed?'
       resolved: true
-      answer: 'Recommend Z level because [rationale].'
+      options:
+        - option: 'Basic'
+          description: 'Minimal implementation, fast to build'
+          selected: false
+        - option: 'Advanced'
+          description: 'Full-featured, handles edge cases'
+          selected: true
+      selectionRationale: 'Advanced is recommended because [reasoning]'
+      answer: 'Advanced'
 
   content: |
     ## Problem Statement
@@ -109,7 +158,8 @@ Write the COMPLETE file. Preserve name/number/branch/technologies from analysis
 ## Constraints
 
 - Write ONLY to ${state.specDir}/spec.yaml
-- Every open question MUST have an AI-recommended default answer (resolved: true)
+- Every open question MUST have structured options with exactly ONE option marked selected: true
+- Every open question MUST also have an \`answer\` field matching the selected option text
 - Requirements must be specific and testable, not vague
 - Do NOT create any other files
 - Do NOT modify any source code`;

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/research.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research.prompt.d.ts","sourceRoot":"","sources":["../../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/research.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAiHpE"}
+{"version":3,"file":"research.prompt.d.ts","sourceRoot":"","sources":["../../../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/research.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CA8HpE"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/nodes/prompts/research.prompt.js

@@ -74,7 +74,19 @@ Use this YAML structure:
   openQuestions:
     - question: '(Any technical question that arose)'
       resolved: true
-      answer: '(Resolution with technical reasoning)'
+      options:
+        - option: (Option A)
+          description: (What option A means and its trade-offs)
+          selected: true
+        - option: (Option B)
+          description: (What option B means and its trade-offs)
+          selected: false
+        - option: (Option C)
+          description: (What option C means and its trade-offs)
+          selected: false
+      selectionRationale: >
+        (Detailed reasoning for why this option was selected.
+        Reference codebase patterns and technical constraints.)
 
   content: |
     ## Technology Decisions
@@ -115,6 +127,7 @@ Use this YAML structure:
 - Write ONLY to ${state.specDir}/research.yaml
 - Every decision MUST have at least one rejected alternative with reasoning
 - Every decision MUST have clear rationale referencing the codebase where applicable
+- Every open question MUST have exactly 3 options to choose from
 - Prefer solutions that follow existing codebase patterns and conventions
 - Do NOT create any other files
 - Do NOT modify any source code`;

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/phase-timing-context.d.ts

@@ -24,6 +24,9 @@ export declare function clearPhaseTimingContext(): void;
 /**
  * Record the start of a phase. Returns the timing record ID (for later update)
  * or null if context is not set or save fails.
+ *
+ * Automatically appends an iteration suffix (`:2`, `:3`, …) when the same
+ * phase has already been recorded for this run (e.g. after a rejection loop).
  */
 export declare function recordPhaseStart(phase: string): Promise<string | null>;
 /**

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/phase-timing-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase-timing-context.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/phase-timing-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wEAAwE,CAAC;AAMrH;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAG7F;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqB5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE,sBAAsB,GACpC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpF"}
+{"version":3,"file":"phase-timing-context.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/phase-timing-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wEAAwE,CAAC;AAMrH;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAG7F;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AA+BD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAsB5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE,sBAAsB,GACpC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpF"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/phase-timing-context.js

@@ -33,9 +33,35 @@ export function clearPhaseTimingContext() {
     contextRepository = undefined;
     lastTimingId = null;
 }
+/**
+ * Compute the iteration-aware phase name.
+ *
+ * Queries existing PhaseTiming rows for the current run, counts how many
+ * share the same base phase name, and appends `:N` for iterations > 1.
+ *
+ * Examples:
+ *   - First "requirements" execution  → "requirements"
+ *   - Second "requirements" execution → "requirements:2"
+ *   - Third "requirements" execution  → "requirements:3"
+ */
+async function resolveIterationPhase(phase, runId, repository) {
+    try {
+        const existing = await repository.findByRunId(runId);
+        // Count rows whose phase is the base name or matches the base:N pattern
+        const count = existing.filter((t) => t.phase === phase || t.phase.startsWith(`${phase}:`)).length;
+        return count === 0 ? phase : `${phase}:${count + 1}`;
+    }
+    catch {
+        // On error, fall back to bare phase name
+        return phase;
+    }
+}
 /**
  * Record the start of a phase. Returns the timing record ID (for later update)
  * or null if context is not set or save fails.
+ *
+ * Automatically appends an iteration suffix (`:2`, `:3`, …) when the same
+ * phase has already been recorded for this run (e.g. after a rejection loop).
  */
 export async function recordPhaseStart(phase) {
     if (!contextRunId || !contextRepository)
@@ -43,10 +69,11 @@ export async function recordPhaseStart(phase) {
     const id = randomUUID();
     const now = new Date();
     try {
+        const iterationPhase = await resolveIterationPhase(phase, contextRunId, contextRepository);
         await contextRepository.save({
             id,
             agentRunId: contextRunId,
-            phase,
+            phase: iterationPhase,
             startedAt: now,
             createdAt: now,
             updatedAt: now,

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/state.d.ts

@@ -38,6 +38,9 @@ export declare const FeatureAgentAnnotation: import("@langchain/langgraph").Anno
     validationRetries: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
     lastValidationTarget: import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
     lastValidationErrors: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    _approvalAction: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    _rejectionFeedback: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    _needsReexecution: import("@langchain/langgraph").BinaryOperatorAggregate<boolean, boolean>;
     prUrl: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
     prNumber: import("@langchain/langgraph").BinaryOperatorAggregate<number | null, number | null>;
     commitHash: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwDjC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,OAAO,sBAAsB,CAAC,KAAK,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/infrastructure/services/agents/feature-agent/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqEjC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,OAAO,sBAAsB,CAAC,KAAK,CAAC"}

package/dist/packages/core/src/infrastructure/services/agents/feature-agent/state.js

@@ -37,6 +37,19 @@ export const FeatureAgentAnnotation = Annotation.Root({
         reducer: (_prev, next) => next,
         default: () => [],
     }),
+    // --- Approval action channels (set by Command({update}) on resume) ---
+    _approvalAction: Annotation({
+        reducer: (_prev, next) => (next !== undefined ? next : _prev),
+        default: () => null,
+    }),
+    _rejectionFeedback: Annotation({
+        reducer: (_prev, next) => (next !== undefined ? next : _prev),
+        default: () => null,
+    }),
+    _needsReexecution: Annotation({
+        reducer: (_prev, next) => next,
+        default: () => false,
+    }),
     // --- Merge and workflow state channels ---
     prUrl: Annotation({
         reducer: (_prev, next) => (next !== undefined ? next : _prev),

package/dist/packages/core/src/infrastructure/services/notifications/notification-bus.d.ts

@@ -2,7 +2,7 @@
  * Notification Event Bus
  *
  * Typed EventEmitter singleton for in-process pub/sub of notification events.
- * Follows the getSettings() singleton pattern from settings.service.ts.
+ * Lazily initialized on first access — works in any context (CLI, web dev server, tests).
  *
  * Multiple listeners can subscribe to the 'notification' event for fan-out
  * delivery (SSE clients, desktop notifier, etc.).
@@ -22,26 +22,11 @@ export interface NotificationEventMap {
     notification: [event: NotificationEvent];
 }
 export type NotificationBus = EventEmitter<NotificationEventMap>;
-/**
- * Initialize the notification event bus singleton.
- * Must be called once during CLI bootstrap.
- *
- * @throws Error if the bus is already initialized
- */
-export declare function initializeNotificationBus(): void;
 /**
  * Get the notification event bus singleton.
- *
- * @returns The notification event bus
- * @throws Error if the bus hasn't been initialized yet
+ * Lazily creates the bus on first access.
  */
 export declare function getNotificationBus(): NotificationBus;
-/**
- * Check if the notification bus has been initialized.
- *
- * @returns True if the bus is initialized, false otherwise
- */
-export declare function hasNotificationBus(): boolean;
 /**
  * Reset the notification bus singleton (for testing purposes only).
  * DO NOT use in production code.

package/dist/packages/core/src/infrastructure/services/notifications/notification-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification-bus.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/notifications/notification-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;AAIjE;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C"}
+{"version":3,"file":"notification-bus.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/notifications/notification-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;AAIjE;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C"}

package/dist/packages/core/src/infrastructure/services/notifications/notification-bus.js

@@ -2,7 +2,7 @@
  * Notification Event Bus
  *
  * Typed EventEmitter singleton for in-process pub/sub of notification events.
- * Follows the getSettings() singleton pattern from settings.service.ts.
+ * Lazily initialized on first access — works in any context (CLI, web dev server, tests).
  *
  * Multiple listeners can subscribe to the 'notification' event for fan-out
  * delivery (SSE clients, desktop notifier, etc.).
@@ -18,38 +18,14 @@
  */
 import { EventEmitter } from 'node:events';
 let busInstance = null;
-/**
- * Initialize the notification event bus singleton.
- * Must be called once during CLI bootstrap.
- *
- * @throws Error if the bus is already initialized
- */
-export function initializeNotificationBus() {
-    if (busInstance !== null) {
-        throw new Error('Notification bus already initialized. Cannot re-initialize.');
-    }
-    busInstance = new EventEmitter();
-}
 /**
  * Get the notification event bus singleton.
- *
- * @returns The notification event bus
- * @throws Error if the bus hasn't been initialized yet
+ * Lazily creates the bus on first access.
  */
 export function getNotificationBus() {
-    if (busInstance === null) {
-        throw new Error('Notification bus not initialized. Call initializeNotificationBus() during CLI bootstrap.');
-    }
+    busInstance ??= new EventEmitter();
     return busInstance;
 }
-/**
- * Check if the notification bus has been initialized.
- *
- * @returns True if the bus is initialized, false otherwise
- */
-export function hasNotificationBus() {
-    return busInstance !== null;
-}
 /**
  * Reset the notification bus singleton (for testing purposes only).
  * DO NOT use in production code.

package/dist/src/presentation/cli/commands/agent/reject.command.js

@@ -25,7 +25,7 @@ export function createRejectCommand() {
                 return;
             }
             const useCase = container.resolve(RejectAgentRunUseCase);
-            const result = await useCase.execute(resolved.run.id, opts.reason);
+            const result = await useCase.execute(resolved.run.id, opts.reason ?? 'Rejected by user');
             if (result.rejected) {
                 messages.success(`Rejected ${colors.accent(resolved.run.id.substring(0, 8))}: ${result.reason}`);
             }