fix: prevent infinite self-discuss loop in auto/headless mode (#1426)

When running in --auto or headless mode, the discuss step could loop
indefinitely — each pass reads its own CONTEXT.md, finds "gaps" in
referenced types/interfaces, creates new decisions to fill them, and
repeats. Observed: 34 passes, 167 decisions, 7 hours, zero code written.

Fixes:
- Add max_discuss_passes config (default: 3) to WorkflowConfig
- Add single-pass guard instruction to SDK self-discuss prompt
- Add pass cap documentation to CLI discuss-phase workflow
- Add pass guard step to SDK headless discuss-phase prompt
- Add stall detection note to autonomous workflow

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sdk/src/config.ts

@@ -31,6 +31,8 @@ export interface WorkflowConfig {
   research_before_questions: boolean;
   discuss_mode: string;
   skip_discuss: boolean;
+  /** Maximum self-discuss passes in auto/headless mode before forcing proceed. Default: 3. */
+  max_discuss_passes: number;
 }
 
 export interface HooksConfig {
@@ -82,6 +84,7 @@ export const CONFIG_DEFAULTS: GSDConfig = {
     research_before_questions: false,
     discuss_mode: 'discuss',
     skip_discuss: false,
+    max_discuss_passes: 3,
   },
   hooks: {
     context_warnings: true,

sdk/src/phase-runner.ts

@@ -410,8 +410,9 @@ export class PhaseRunner {
       const contextFiles = await this.contextEngine.resolveContextFiles(PhaseType.Discuss);
       let prompt = await this.promptFactory.buildPrompt(PhaseType.Discuss, null, contextFiles);
 
-      // Supplement with self-discuss instructions
-      prompt += '\n\n## Self-Discuss Mode\n\nYou are the AI discussing decisions with yourself. No human is present. Identify 3-5 gray areas in the project scope, reason through each one, make opinionated choices, and write CONTEXT.md with your decisions.';
+      // Supplement with self-discuss instructions with pass cap
+      const maxPasses = this.config.workflow.max_discuss_passes ?? 3;
+      prompt += `\n\n## Self-Discuss Mode\n\nYou are the AI discussing decisions with yourself. No human is present. Identify 3-5 gray areas in the project scope, reason through each one, make opinionated choices, and write CONTEXT.md with your decisions.\n\n**CRITICAL: Single-pass only.** You MUST complete all decisions in ONE pass and write CONTEXT.md once. Do NOT re-read your own CONTEXT.md to find "gaps" and do additional passes. The maximum allowed passes is ${maxPasses} — if you have already written CONTEXT.md, you are DONE. Proceed to the next workflow step. Self-referential gap-finding loops waste resources without adding value.`;
 
       planResult = await runPhaseStepSession(
         prompt,