rafcode 1.2.0 → 1.3.2

package/src/core/claude-runner.ts

@@ -1,7 +1,10 @@
+import * as fs from 'node:fs';
 import * as pty from 'node-pty';
 import type { IDisposable } from 'node-pty';
 import { execSync, spawn } from 'node:child_process';
 import { logger } from '../utils/logger.js';
+import { renderStreamEvent } from '../parsers/stream-renderer.js';
+import { getHeadCommitHash, getHeadCommitMessage, isFileCommittedInHead } from './git.js';
 
 function getClaudePath(): string {
   try {
@@ -26,6 +29,27 @@ export interface ClaudeRunnerOptions {
    * Claude will still ask planning interview questions.
    */
   dangerouslySkipPermissions?: boolean;
+  /**
+   * Path to the outcome file. When provided, enables completion detection:
+   * - Monitors stdout for completion markers (<promise>COMPLETE/FAILED</promise>)
+   * - Polls the outcome file for completion markers
+   * When detected, starts a grace period before terminating the process,
+   * allowing time for git commit operations to complete.
+   */
+  outcomeFilePath?: string;
+  /**
+   * Commit verification context. When provided, the grace period will verify
+   * that the expected git commit has been made before terminating.
+   * Only applies when a COMPLETE marker is detected (not FAILED).
+   */
+  commitContext?: {
+    /** HEAD commit hash recorded before task execution began. */
+    preExecutionHead: string;
+    /** Expected commit message prefix (e.g., "RAF[005:001]"). */
+    expectedPrefix: string;
+    /** Path to the outcome file that should be committed. */
+    outcomeFilePath: string;
+  };
 }
 
 export interface ClaudeRunnerConfig {
@@ -50,6 +74,180 @@ const CONTEXT_OVERFLOW_PATTERNS = [
   /context window/i,
 ];
 
+const COMPLETION_MARKER_PATTERN = /<promise>(COMPLETE|FAILED)<\/promise>/i;
+
+/**
+ * Grace period in ms after completion marker is detected before terminating.
+ * Allows time for git commit operations to complete.
+ */
+export const COMPLETION_GRACE_PERIOD_MS = 60_000;
+
+/**
+ * Hard maximum grace period in ms. If the commit hasn't landed by this point,
+ * the process is killed regardless.
+ */
+export const COMPLETION_HARD_MAX_MS = 180_000;
+
+/**
+ * Interval in ms for polling commit verification after the initial grace period expires.
+ */
+export const COMMIT_POLL_INTERVAL_MS = 10_000;
+
+/**
+ * Interval in ms for polling the outcome file for completion markers.
+ */
+export const OUTCOME_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Context for commit verification during grace period.
+ */
+export interface CommitContext {
+  /** HEAD commit hash recorded before task execution began. */
+  preExecutionHead: string;
+  /** Expected commit message prefix (e.g., "RAF[005:001]"). */
+  expectedPrefix: string;
+  /** Path to the outcome file that should be committed. */
+  outcomeFilePath: string;
+}
+
+/**
+ * Monitors for task completion markers in stdout and outcome files.
+ * When a marker is detected, starts a grace period before killing the process.
+ */
+interface CompletionDetector {
+  /** Check accumulated stdout output for completion markers. */
+  checkOutput(output: string): void;
+  /** Clean up all timers. Must be called when the process exits. */
+  cleanup(): void;
+}
+
+const COMPLETE_MARKER_PATTERN = /<promise>COMPLETE<\/promise>/i;
+
+/**
+ * Verify that the expected commit has been made.
+ * Checks: HEAD changed, commit message matches prefix, outcome file is committed.
+ */
+function verifyCommit(commitContext: CommitContext): boolean {
+  const currentHead = getHeadCommitHash();
+  if (!currentHead || currentHead === commitContext.preExecutionHead) {
+    return false;
+  }
+
+  const message = getHeadCommitMessage();
+  if (!message || !message.startsWith(commitContext.expectedPrefix)) {
+    return false;
+  }
+
+  if (!isFileCommittedInHead(commitContext.outcomeFilePath)) {
+    return false;
+  }
+
+  return true;
+}
+
+function createCompletionDetector(
+  killFn: () => void,
+  outcomeFilePath?: string,
+  commitContext?: CommitContext,
+): CompletionDetector {
+  let graceHandle: ReturnType<typeof setTimeout> | null = null;
+  let commitPollHandle: ReturnType<typeof setInterval> | null = null;
+  let hardMaxHandle: ReturnType<typeof setTimeout> | null = null;
+  let pollHandle: ReturnType<typeof setInterval> | null = null;
+  let initialMtime = 0;
+  let detectedMarkerIsComplete = false;
+
+  // Record initial mtime of outcome file to avoid false positives from previous runs
+  if (outcomeFilePath) {
+    try {
+      if (fs.existsSync(outcomeFilePath)) {
+        initialMtime = fs.statSync(outcomeFilePath).mtimeMs;
+      }
+    } catch {
+      // Ignore stat errors
+    }
+  }
+
+  /**
+   * Called when the initial grace period expires.
+   * If commit verification is needed and the commit hasn't landed yet,
+   * start polling for the commit up to the hard maximum.
+   */
+  function onGracePeriodExpired(): void {
+    if (commitContext && detectedMarkerIsComplete) {
+      // Check if commit already landed
+      if (verifyCommit(commitContext)) {
+        logger.debug('Grace period expired - commit verified, terminating Claude process');
+        killFn();
+        return;
+      }
+
+      // Commit not found yet - extend with polling
+      logger.debug('Grace period expired but commit not verified - extending with polling');
+      const remainingMs = COMPLETION_HARD_MAX_MS - COMPLETION_GRACE_PERIOD_MS;
+
+      hardMaxHandle = setTimeout(() => {
+        logger.warn('Hard maximum grace period reached without commit verification - terminating Claude process');
+        if (commitPollHandle) clearInterval(commitPollHandle);
+        killFn();
+      }, remainingMs);
+
+      commitPollHandle = setInterval(() => {
+        if (commitContext && verifyCommit(commitContext)) {
+          logger.debug('Commit verified during extended grace period - terminating Claude process');
+          if (commitPollHandle) clearInterval(commitPollHandle);
+          if (hardMaxHandle) clearTimeout(hardMaxHandle);
+          killFn();
+        }
+      }, COMMIT_POLL_INTERVAL_MS);
+    } else {
+      // No commit verification needed (FAILED marker or no context) - kill immediately
+      logger.debug('Grace period expired - terminating Claude process');
+      killFn();
+    }
+  }
+
+  function startGracePeriod(markerOutput: string): void {
+    if (graceHandle) return; // Already started
+    detectedMarkerIsComplete = COMPLETE_MARKER_PATTERN.test(markerOutput);
+    logger.debug('Completion marker detected - starting grace period before termination');
+    graceHandle = setTimeout(onGracePeriodExpired, COMPLETION_GRACE_PERIOD_MS);
+  }
+
+  function checkOutput(output: string): void {
+    if (!graceHandle && COMPLETION_MARKER_PATTERN.test(output)) {
+      startGracePeriod(output);
+    }
+  }
+
+  // Start outcome file polling if path provided
+  if (outcomeFilePath) {
+    const filePath = outcomeFilePath;
+    pollHandle = setInterval(() => {
+      try {
+        if (!fs.existsSync(filePath)) return;
+        const stat = fs.statSync(filePath);
+        if (stat.mtimeMs <= initialMtime) return; // File unchanged from before execution
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (COMPLETION_MARKER_PATTERN.test(content)) {
+          startGracePeriod(content);
+        }
+      } catch {
+        // Ignore read errors - file may be mid-write
+      }
+    }, OUTCOME_POLL_INTERVAL_MS);
+  }
+
+  function cleanup(): void {
+    if (graceHandle) clearTimeout(graceHandle);
+    if (pollHandle) clearInterval(pollHandle);
+    if (commitPollHandle) clearInterval(commitPollHandle);
+    if (hardMaxHandle) clearTimeout(hardMaxHandle);
+  }
+
+  return { checkOutput, cleanup };
+}
+
 export class ClaudeRunner {
   private activeProcess: pty.IPty | null = null;
   private killed = false;
@@ -169,7 +367,7 @@ export class ClaudeRunner {
    * - Default timeout is 60 minutes if not specified
    */
   async run(prompt: string, options: ClaudeRunnerOptions = {}): Promise<RunResult> {
-    const { timeout = 60, cwd = process.cwd() } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -213,11 +411,21 @@ export class ClaudeRunner {
         proc.kill('SIGTERM');
       }, timeoutMs);
 
+      // Set up completion detection (stdout marker + outcome file polling)
+      const completionDetector = createCompletionDetector(
+        () => proc.kill('SIGTERM'),
+        outcomeFilePath,
+        commitContext,
+      );
+
       // Collect stdout
       proc.stdout.on('data', (data) => {
         const text = data.toString();
         output += text;
 
+        // Check for completion marker to start grace period
+        completionDetector.checkOutput(output);
+
         // Check for context overflow
         for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
           if (pattern.test(text)) {
@@ -236,6 +444,7 @@ export class ClaudeRunner {
 
       proc.on('close', (exitCode) => {
         clearTimeout(timeoutHandle);
+        completionDetector.cleanup();
         this.activeProcess = null;
 
         if (stderr) {
@@ -254,7 +463,8 @@ export class ClaudeRunner {
 
   /**
    * Run Claude non-interactively with verbose output to stdout.
-   * Uses child_process.spawn with -p flag for prompt (like ralphy).
+   * Uses --output-format stream-json --verbose to get real-time streaming
+   * of tool calls, file operations, and thinking steps.
    *
    * TIMEOUT BEHAVIOR:
    * - The timeout is applied per individual call to this method
@@ -264,7 +474,7 @@ export class ClaudeRunner {
    * - Default timeout is 60 minutes if not specified
    */
   async runVerbose(prompt: string, options: ClaudeRunnerOptions = {}): Promise<RunResult> {
-    const { timeout = 60, cwd = process.cwd() } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -277,13 +487,13 @@ export class ClaudeRunner {
 
       const claudePath = getClaudePath();
 
-      logger.debug(`Starting Claude execution session (verbose) with model: ${this.model}`);
+      logger.debug(`Starting Claude execution session (verbose/stream-json) with model: ${this.model}`);
       logger.debug(`Prompt length: ${prompt.length}, timeout: ${timeoutMs}ms, cwd: ${cwd}`);
       logger.debug(`Claude path: ${claudePath}`);
 
       logger.debug('Spawning process...');
-      // Use --append-system-prompt to add RAF instructions to system prompt
-      // This gives RAF instructions stronger precedence than passing as user message
+      // Use --output-format stream-json --verbose to get real-time streaming events
+      // including tool calls, file operations, and intermediate output.
       // --dangerously-skip-permissions bypasses interactive prompts
       // -p enables print mode (non-interactive)
       const proc = spawn(claudePath, [
@@ -292,6 +502,9 @@ export class ClaudeRunner {
         this.model,
         '--append-system-prompt',
         prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
         '-p',
         'Execute the task as described in the system prompt.',
       ], {
@@ -311,24 +524,52 @@ export class ClaudeRunner {
         proc.kill('SIGTERM');
       }, timeoutMs);
 
-      // Collect and display stdout
+      // Set up completion detection (stdout marker + outcome file polling)
+      const completionDetector = createCompletionDetector(
+        () => proc.kill('SIGTERM'),
+        outcomeFilePath,
+        commitContext,
+      );
+
+      // Buffer for incomplete NDJSON lines (data chunks may split across line boundaries)
+      let lineBuffer = '';
       let dataReceived = false;
+
       proc.stdout.on('data', (data) => {
         if (!dataReceived) {
           logger.debug('First data chunk received');
           dataReceived = true;
         }
-        const text = data.toString();
-        output += text;
-        process.stdout.write(text);
 
-        // Check for context overflow
-        for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
-          if (pattern.test(text)) {
-            contextOverflow = true;
-            logger.warn('Context overflow detected');
-            proc.kill('SIGTERM');
-            break;
+        lineBuffer += data.toString();
+
+        // Process complete lines from the NDJSON stream
+        let newlineIndex: number;
+        while ((newlineIndex = lineBuffer.indexOf('\n')) !== -1) {
+          const line = lineBuffer.substring(0, newlineIndex);
+          lineBuffer = lineBuffer.substring(newlineIndex + 1);
+
+          const { display, textContent } = renderStreamEvent(line);
+
+          if (textContent) {
+            output += textContent;
+
+            // Check for completion marker to start grace period
+            completionDetector.checkOutput(output);
+
+            // Check for context overflow
+            for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
+              if (pattern.test(textContent)) {
+                contextOverflow = true;
+                logger.warn('Context overflow detected');
+                proc.kill('SIGTERM');
+                break;
+              }
+            }
+          }
+
+          if (display) {
+            process.stdout.write(display);
           }
         }
       });
@@ -339,7 +580,19 @@ export class ClaudeRunner {
       });
 
       proc.on('close', (exitCode) => {
+        // Process any remaining data in the line buffer
+        if (lineBuffer.trim()) {
+          const { display, textContent } = renderStreamEvent(lineBuffer);
+          if (textContent) {
+            output += textContent;
+          }
+          if (display) {
+            process.stdout.write(display);
+          }
+        }
+
         clearTimeout(timeoutHandle);
+        completionDetector.cleanup();
         this.activeProcess = null;
         logger.debug(`Claude exited with code ${exitCode}, output length: ${output.length}, timedOut: ${timedOut}, contextOverflow: ${contextOverflow}`);
 

package/src/core/git.ts

@@ -167,6 +167,50 @@ export function stashChanges(name: string): boolean {
   }
 }
 
+/**
+ * Get the current HEAD commit hash.
+ * Returns null if not in a git repo or HEAD doesn't exist.
+ */
+export function getHeadCommitHash(): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: 'pipe' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the current HEAD commit message (first line only).
+ * Returns null if not in a git repo or HEAD doesn't exist.
+ */
+export function getHeadCommitMessage(): string | null {
+  try {
+    return execSync('git log -1 --format=%s', { encoding: 'utf-8', stdio: 'pipe' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a file is tracked in the HEAD commit.
+ * Returns true if the file appears in the latest commit's tree.
+ */
+export function isFileCommittedInHead(filePath: string): boolean {
+  try {
+    // Use git ls-tree to check if the file exists in HEAD
+    // We need the path relative to the repo root
+    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    const relativePath = path.relative(repoRoot, path.resolve(filePath));
+    const result = execSync(`git ls-tree HEAD -- "${relativePath.replace(/"/g, '\\"')}"`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    }).trim();
+    return result.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Commit planning artifacts (input.md and decisions.md) for a project.
  * Uses commit message format: RAF[NNN] Plan: project-name

package/src/parsers/stream-renderer.ts

@@ -0,0 +1,139 @@
+/**
+ * Renders stream-json events from Claude CLI into human-readable verbose output.
+ *
+ * Event types from `claude -p --output-format stream-json --verbose`:
+ * - system (init): Session initialization info
+ * - assistant: Claude's response with text or tool_use content blocks
+ * - user: Tool results (tool_result content blocks)
+ * - result: Final result with success/failure status
+ */
+
+export interface StreamEvent {
+  type: string;
+  subtype?: string;
+  message?: {
+    content?: ContentBlock[];
+  };
+  result?: string;
+  tool_use_result?: {
+    type?: string;
+    file?: {
+      filePath?: string;
+    };
+  };
+}
+
+interface ContentBlock {
+  type: string;
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+/**
+ * Describes what a tool is doing in human-readable form.
+ */
+function describeToolUse(name: string, input: Record<string, unknown>): string {
+  switch (name) {
+    case 'Read':
+      return `Reading ${input.file_path ?? 'file'}`;
+    case 'Write':
+      return `Writing ${input.file_path ?? 'file'}`;
+    case 'Edit':
+      return `Editing ${input.file_path ?? 'file'}`;
+    case 'Bash':
+      return `Running: ${truncate(String(input.command ?? ''), 120)}`;
+    case 'Glob':
+      return `Searching files: ${input.pattern ?? ''}`;
+    case 'Grep':
+      return `Searching for: ${truncate(String(input.pattern ?? ''), 80)}`;
+    case 'WebFetch':
+      return `Fetching: ${input.url ?? ''}`;
+    case 'WebSearch':
+      return `Searching web: ${input.query ?? ''}`;
+    case 'TodoWrite':
+      return 'Updating task list';
+    case 'Task':
+      return `Launching agent: ${truncate(String(input.description ?? input.prompt ?? ''), 80)}`;
+    case 'NotebookEdit':
+      return `Editing notebook: ${input.notebook_path ?? ''}`;
+    default:
+      return `Using tool: ${name}`;
+  }
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.substring(0, maxLen - 3) + '...';
+}
+
+export interface RenderResult {
+  /** Text to display to stdout (may be empty if no display needed) */
+  display: string;
+  /** Text content to accumulate for output parsing (completion markers, etc.) */
+  textContent: string;
+}
+
+/**
+ * Parse and render a single NDJSON line from stream-json output.
+ * Returns display text for stdout and text content for output accumulation.
+ */
+export function renderStreamEvent(line: string): RenderResult {
+  if (!line.trim()) {
+    return { display: '', textContent: '' };
+  }
+
+  let event: StreamEvent;
+  try {
+    event = JSON.parse(line) as StreamEvent;
+  } catch {
+    // Not valid JSON - pass through raw
+    return { display: line + '\n', textContent: line };
+  }
+
+  switch (event.type) {
+    case 'system':
+      return { display: '', textContent: '' };
+
+    case 'assistant':
+      return renderAssistant(event);
+
+    case 'user':
+      // Tool results — skip verbose display (the tool_use already described what's happening)
+      return { display: '', textContent: '' };
+
+    case 'result':
+      return renderResult(event);
+
+    default:
+      return { display: '', textContent: '' };
+  }
+}
+
+function renderAssistant(event: StreamEvent): RenderResult {
+  const content = event.message?.content;
+  if (!content || !Array.isArray(content)) {
+    return { display: '', textContent: '' };
+  }
+
+  let display = '';
+  let textContent = '';
+
+  for (const block of content) {
+    if (block.type === 'text' && block.text) {
+      textContent += block.text;
+      display += block.text + '\n';
+    } else if (block.type === 'tool_use' && block.name) {
+      const description = describeToolUse(block.name, block.input ?? {});
+      display += `  → ${description}\n`;
+    }
+  }
+
+  return { display, textContent };
+}
+
+function renderResult(_event: StreamEvent): RenderResult {
+  // The result event's text duplicates the last assistant message,
+  // which is already captured. Skip to avoid double-counting.
+  return { display: '', textContent: '' };
+}

package/src/prompts/amend.ts

@@ -35,7 +35,11 @@ export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
             : '[PENDING]';
       const modifiability =
         task.status === 'completed' ? '[PROTECTED]' : '[MODIFIABLE]';
-      return `- Task ${task.id}: ${task.taskName} ${status} ${modifiability}`;
+      const outcomeRef =
+        task.status === 'completed'
+          ? `\n  Outcome: ${projectPath}/outcomes/${task.planFile.replace('plans/', '').replace(/\.md$/, '')}.md`
+          : '';
+      return `- Task ${task.id}: ${task.taskName} ${status} ${modifiability}${outcomeRef}`;
     })
     .join('\n');
 
@@ -94,6 +98,13 @@ Read the user's description of new tasks and identify what needs to be added. Co
 - Dependencies on completed tasks (check the ## Dependencies section in existing plan files)
 - Whether new tasks should reference existing task outcomes
 
+**Identifying Follow-up Tasks**: When a new task is a follow-up, fix, or iteration of a previously completed task, you MUST reference the previous task's outcome in the new plan's Context section. This gives the executing agent full context about what was done before.
+
+Use this format in the Context section:
+\`This is a follow-up to task NNN. See outcome: {projectPath}/outcomes/NNN-task-name.md\`
+
+The outcome file paths for completed tasks are listed above in the Existing Tasks section.
+
 ### Step 3: Interview the User
 
 For EACH new task you identify, use the AskUserQuestion tool to gather:
@@ -109,7 +120,7 @@ After EACH interview question is answered, append the Q&A pair to the existing d
 
 Use this format:
 \`\`\`markdown
-## [Amendment] [Question asked]
+## [Question asked]
 [User's answer]
 \`\`\`
 
@@ -131,6 +142,7 @@ Each plan file should follow this structure:
 ## Context
 [Why this task is needed, how it fits into the larger project]
 [Reference relevant existing tasks if applicable]
+[For follow-up/fix tasks: "This is a follow-up to task NNN. See outcome: {projectPath}/outcomes/NNN-task-name.md"]
 
 ## Dependencies
 [Optional section - omit if task has no dependencies]

package/src/prompts/execution.ts

@@ -164,12 +164,10 @@ First, read the plan file to understand exactly what needs to be done.
 ### Step 2: Execute the Task
 
 Follow the implementation steps in the plan. Key guidelines:
-- **Use the Task tool to delegate work to subagents** - Split complex work into subtasks and use specialized agents (Explore for codebase investigation, Plan for design decisions, general-purpose for implementation)
 - Write clean, maintainable code
 - Follow existing code patterns in the project
 - Add appropriate error handling
-- Write tests if specified in the plan
-- Follow any CLAUDE.md instructions if present
+- Follow any CLAUDE.md instructions
 ${dependencyContextSection}${outcomesSection}
 ### Step 3: Verify Completion
 

package/src/prompts/planning.ts

@@ -20,7 +20,7 @@ export function getPlanningPrompt(params: PlanningPromptParams): PlanningPromptR
 
 ## Your Goals
 
-1. **Analyze the input** and identify 3-8 distinct, actionable tasks
+1. **Analyze the input** and identify distinct, actionable tasks
 2. **Interview the user** about EACH task to gather specific requirements
 3. **Create plan files** for each task with clear instructions
 
@@ -32,7 +32,7 @@ Project folder: ${projectPath}
 
 ### Step 1: Identify and Order Tasks
 
-Based on the project description, identify 3-8 distinct tasks. Each task should:
+Based on the project description, identify distinct tasks. Each task should:
 - Be independently completable
 - Have a clear outcome
 - Take roughly 10-30 minutes of work for Claude