v1.10.0

plan2code-loop/src/cli.ts

@@ -224,7 +224,8 @@ export async function setupSession(
     model: 'default',
     maxIterations,
     specPath,
-    timeout: 30,
+    timeout: 3,
+    maxRetries: 5,
     verbose: false,
     startedAt: new Date().toISOString(),
     currentIteration: 0,

plan2code-loop/src/controller.ts

@@ -64,9 +64,82 @@ export class Controller {
     });
   }
 
-  private async executeIteration(prompt: string): Promise<AgentExecutionResult> {
-    const timeoutMs = this.config.timeout * 60 * 1000;
+  private computeTimeoutMs(attempt: number): number {
+    const baseMs = this.config.timeout * 60 * 1000;
+    return baseMs + (attempt * 30 * 1000);
+  }
 
+  private formatDuration(ms: number): string {
+    const totalSec = Math.round(ms / 1000);
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    if (min === 0) return `${sec}s`;
+    if (sec === 0) return `${min}m`;
+    return `${min}m ${sec}s`;
+  }
+
+  private async executeWithRetry(prompt: string, iterNum: number): Promise<AgentExecutionResult | 'fatal_timeout'> {
+    const maxAttempts = (this.config.maxRetries ?? 5) + 1;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const timeoutMs = this.computeTimeoutMs(attempt);
+
+      if (attempt > 0) {
+        const prevTimeoutMs = this.computeTimeoutMs(attempt - 1);
+        logger.warning(
+          `Timed out after ${this.formatDuration(prevTimeoutMs)}, retrying (${attempt}/${maxAttempts - 1})...`
+        );
+      }
+
+      const spinnerBase = attempt > 0
+        ? `Waiting for AI Agent response (retry ${attempt}/${maxAttempts - 1})`
+        : 'Waiting for AI Agent response (please be patient)';
+      const spinner = logger.spinner(spinnerBase);
+      const startTime = Date.now();
+
+      const elapsedInterval = setInterval(() => {
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        spinner.text = `${spinnerBase} ... (${elapsed}s)`;
+      }, 1000);
+
+      const result = await this.executeIteration(prompt, timeoutMs);
+      clearInterval(elapsedInterval);
+      spinner.stop();
+
+      // Cancelled or interrupted — return immediately, don't retry
+      if (result.cancelled || this.interrupted) {
+        return result;
+      }
+
+      // Completed (success or error exit code) — return to caller
+      if (!result.timedOut) {
+        return result;
+      }
+
+      // Timed out — retry if attempts remain, otherwise fatal
+      if (attempt < maxAttempts - 1) {
+        continue;
+      }
+
+      // All attempts exhausted
+      logger.error(
+        `Iteration ${iterNum} timed out on all ${maxAttempts} attempt${maxAttempts === 1 ? '' : 's'}. Stopping loop.`
+      );
+      const entry: IterationLogEntry = {
+        iteration: iterNum,
+        timestamp: new Date().toISOString(),
+        duration: result.duration,
+        exitCode: -1,
+        status: 'timeout',
+      };
+      await this.stateManager.appendIterationLog(entry);
+      return 'fatal_timeout';
+    }
+
+    return 'fatal_timeout'; // unreachable, satisfies TS
+  }
+
+  private async executeIteration(prompt: string, timeoutMs: number): Promise<AgentExecutionResult> {
     // Create new AbortController for this iteration
     this.abortController = new AbortController();
 
@@ -179,19 +252,21 @@ export class Controller {
       // Build prompt - simple, just spec path and iteration info
       const prompt = await this.buildPrompt();
 
-      const spinner = logger.spinner('Waiting for AI Agent response (please be patient)');
-      const startTime = Date.now();
-
-      // Update spinner with elapsed time every second
-      const elapsedInterval = setInterval(() => {
-        const elapsed = Math.round((Date.now() - startTime) / 1000);
-        spinner.text = `Waiting for AI Agent response (please be patient) ... (${elapsed}s)`;
-      }, 1000);
-
       try {
-        const result = await this.executeIteration(prompt);
-        clearInterval(elapsedInterval);
-        spinner.stop();
+        const retryResult = await this.executeWithRetry(prompt, iterNum);
+
+        if (retryResult === 'fatal_timeout') {
+          return {
+            completed: false,
+            iterations: this.config.currentIteration,
+            exitReason: 'error',
+            tasksCompleted: this.tasksCompleted,
+            prereqsCompleted: this.prereqsCompleted,
+            error: new Error(`Iteration ${iterNum} failed after all retry attempts`),
+          };
+        }
+
+        const result = retryResult;
 
         // Check if cancelled
         if (result.cancelled || this.interrupted) {
@@ -390,13 +465,8 @@ export class Controller {
         await this.stateManager.updateSpecHash(this.config.specPath);
         this.config.currentIteration++;
 
-        // Handle timeout
-        if (result.timedOut) {
-          logger.warning(`Iteration ${iterNum} timed out, continuing...`);
-        }
-
         // Handle error (but continue - LLM might recover)
-        if (result.exitCode !== 0 && !result.timedOut) {
+        if (result.exitCode !== 0) {
           // In phase mode, check if any tasks completed despite error exit code
           const hasCompletions = isPhaseMode
             ? checkForAllCompletions(result.stdout + result.stderr).tasks.length > 0

plan2code-loop/src/index.ts

@@ -80,7 +80,6 @@ export async function run(): Promise<LoopResult | null> {
     logger.dim('  - config.json (session configuration)');
     logger.dim('  - scratchpad.md (LLM-managed notes)');
     logger.dim('  - iteration.log (history)');
-    logger.dim('Tip: run `plan2code-metrics` to capture run data for prompt improvement.');
 
     return loopResult;
   } finally {

plan2code-loop/src/prompt/templates.ts

@@ -23,18 +23,19 @@ Find the FIRST unchecked task, implement ONLY that task, then STOP and report.
 2. Find the FIRST phase with an unchecked checkbox (\`- [ ]\` or \`- [/]\`)
 3. Read that phase's file (e.g., \`phase-1.md\`)
 4. Check the \`## Prerequisites\` section FIRST
-5. Find the FIRST unchecked prerequisite (\`- [ ]\`)
-   - If found, that is your task for this iteration
-   - Verify/complete it, then mark \`[x]\` or \`[?]\`
-6. Only if ALL prerequisites are complete (\`[x]\` or \`[?]\`), find the FIRST unchecked task
+5. Find the FIRST unverified prerequisite (no "VERIFIED" or "ASSUMED" annotation)
+   - If found, verify/complete it, then annotate "VERIFIED" or "ASSUMED: [reason]" inline
+6. Only if ALL prerequisites are verified or assumed, find the FIRST unchecked task (\`- [ ]\`)
 7. That is your ONE task - implement ONLY that task
 
-## Checkbox States
+## Checkbox States (Task items only)
 - \`[ ]\` = incomplete/pending (do the FIRST one you find)
 - \`[x]\` = complete (skip)
 - \`[?]\` = assumed complete, couldn't verify (skip)
 - \`[!]\` = blocked (skip)
 
+Prerequisites use plain bullets with inline annotations, not checkboxes.
+
 ## Implementation Steps
 1. Read and understand the single task
 2. Implement it completely
@@ -66,7 +67,10 @@ Use only when ALL phases in overview.md are marked complete.
 
 ## Scratchpad Management
 
-After completing each task, append to \`{{specPath}}/.plan2code-loop/scratchpad.md\`:
+After completing each task, add a new entry at the **bottom** of \`{{specPath}}/.plan2code-loop/scratchpad.md\`.
+Never edit, reorganize, or insert into existing content � only append new entries to the end of the file.
+
+Each entry should include:
 - Task completed and Phase item reference
 - Key decisions made and reasoning
 - Files changed
@@ -108,17 +112,19 @@ Complete each task fully before moving to the next task within the phase.
 2. Find the FIRST phase with an unchecked checkbox (\`- [ ]\` or \`- [/]\`)
 3. Read that phase's file (e.g., \`phase-1.md\`)
 4. Check the \`## Prerequisites\` section FIRST
-5. Complete ALL unchecked prerequisites (\`- [ ]\`) first, in order
-   - Verify/complete each, then mark \`[x]\` or \`[?]\`
-6. Once ALL prerequisites are complete, implement ALL unchecked tasks in order
+5. Verify ALL unverified prerequisites first, in order
+   - Annotate each "VERIFIED" or "ASSUMED: [reason]" inline
+6. Once ALL prerequisites are verified, implement ALL unchecked tasks in order
 7. Continue until every task in the phase is marked \`[x]\`
 
-## Checkbox States
+## Checkbox States (Task items only)
 - \`[ ]\` = incomplete/pending
 - \`[x]\` = complete (skip)
 - \`[?]\` = assumed complete, couldn't verify (skip)
 - \`[!]\` = blocked (skip, note in scratchpad)
 
+Prerequisites use plain bullets with inline annotations, not checkboxes.
+
 ## Implementation Steps (repeat for EACH task in the phase)
 1. Read and understand the task
 2. Implement it completely
@@ -139,9 +145,13 @@ git commit -m "<commit message>"
 \`\`\`
 
 **Commit message format:**
-- With JIRA ticket: Use \`-m "Task X.Y: description" -m "{{jiraTicketId}}" -m "AI Assisted"\` (three \`-m\` flags)
-- Without JIRA ticket: \`-m "Task X.Y: description" -m "AI Assisted"\` (two \`-m\` flags)
-- ALWAYS include the "AI Assisted" footer as the final \`-m\` flag
+\`\`\`
+git add -A
+git commit -m "Task X.Y: description" -m "{{jiraTicketId}}" -m "AI Assisted"
+\`\`\`
+- With JIRA ticket: three \`-m\` flags (description, ticket ID, AI Assisted)
+- Without JIRA ticket: two \`-m\` flags (description, AI Assisted)
+- ALWAYS include "AI Assisted" as the final \`-m\` flag
 
 Replace X.Y with the actual task ID and description with a concise summary of what was implemented.
 
@@ -167,7 +177,10 @@ After ALL tasks in the phase are complete (or blocked), output:
 
 ## Scratchpad Management
 
-After completing each task, append to \`{{specPath}}/.plan2code-loop/scratchpad.md\`:
+After completing each task, add a new entry at the **bottom** of \`{{specPath}}/.plan2code-loop/scratchpad.md\`.
+Never edit, reorganize, or insert into existing content � only append new entries to the end of the file.
+
+Each entry should include:
 - Task completed and Phase item reference
 - Key decisions made and reasoning
 - Files changed

plan2code-loop/src/state/config.ts

@@ -4,7 +4,8 @@ export interface SessionConfig {
   agent: string;              // "claude-code" | "copilot-cli"
   model: string;              // Selected model
   maxIterations: number;      // 5-50
-  timeout: number;            // Minutes per iteration
+  timeout: number;            // Base timeout in minutes per iteration attempt
+  maxRetries: number;         // Max retry attempts per iteration (timeout increments by 30s each retry)
   verbose: boolean;
   specPath: string;           // Path to the spec directory
   startedAt: string;          // ISO timestamp
@@ -26,7 +27,8 @@ export type SessionState = 'new' | 'continue' | 'changed';
 
 export const DEFAULT_CONFIG: Partial<SessionConfig> = {
   maxIterations: 100,
-  timeout: 30,
+  timeout: 3,
+  maxRetries: 5,
   verbose: false,
   currentIteration: 0,
   loopMode: 'task',

plan2code-loop/src/utils/git.ts

@@ -109,7 +109,7 @@ export async function createTaskCommit(options: GitCommitOptions): Promise<boole
     // Build commit message
     let commitMessage = taskName;
     if (jiraTicketId) {
-      commitMessage = `${taskName}\n\n${jiraTicketId}\n\nAI Assisted`;
+      commitMessage = `${taskName}\n\n${jiraTicketId}\nAI Assisted`;
     } else {
       commitMessage = `${taskName}\n\nAI Assisted`;
     }