rafcode 3.2.1 → 3.8.0

package/src/core/codex-runner.ts

@@ -4,6 +4,7 @@ import { execSync, spawn } from 'node:child_process';
 import { logger } from '../utils/logger.js';
 import { renderCodexStreamEvent } from '../parsers/codex-stream-renderer.js';
 import { getModel } from '../utils/config.js';
+import { mergeUsageData } from '../utils/token-tracker.js';
 import type { ICliRunner } from './runner-interface.js';
 import type { RunnerOptions, RunnerConfig, RunResult } from './runner-types.js';
 import { createCompletionDetector } from './completion-detector.js';
@@ -36,9 +37,11 @@ export class CodexRunner implements ICliRunner {
   private activeProcess: pty.IPty | null = null;
   private killed = false;
   private model: string;
+  private reasoningEffort?: string;
 
   constructor(config: RunnerConfig = {}) {
-    this.model = config.model ?? getModel('execute', 'codex');
+    this.model = config.model ?? getModel('execute').model;
+    this.reasoningEffort = config.reasoningEffort;
   }
 
   /**
@@ -54,7 +57,14 @@ export class CodexRunner implements ICliRunner {
 
     return new Promise((resolve) => {
       const combinedPrompt = buildCombinedPrompt(systemPrompt, userMessage);
-      const args = ['-m', this.model, combinedPrompt];
+      const args = ['-m', this.model];
+
+      // Add reasoning effort via config override when configured
+      if (this.reasoningEffort) {
+        args.push('-c', `model_reasoning_effort="${this.reasoningEffort}"`);
+      }
+
+      args.push(combinedPrompt);
 
       logger.debug(`Starting interactive Codex session with model: ${this.model}`);
 
@@ -167,6 +177,7 @@ export class CodexRunner implements ICliRunner {
       let stderr = '';
       let timedOut = false;
       let contextOverflow = false;
+      let usageData: import('../types/config.js').UsageData | undefined;
 
       const codexPath = getCodexPath();
 
@@ -175,15 +186,23 @@ export class CodexRunner implements ICliRunner {
       logger.debug(`Codex path: ${codexPath}`);
 
       logger.debug('Spawning process...');
-      const proc = spawn(codexPath, [
+      const execArgs = [
         'exec',
         '--full-auto',
         '--json',
         '--ephemeral',
         '-m',
         this.model,
-        prompt,
-      ], {
+      ];
+
+      // Add reasoning effort via config override when configured
+      if (this.reasoningEffort) {
+        execArgs.push('-c', `model_reasoning_effort="${this.reasoningEffort}"`);
+      }
+
+      execArgs.push(prompt);
+
+      const proc = spawn(codexPath, execArgs, {
         cwd,
         env: process.env,
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -244,6 +263,10 @@ export class CodexRunner implements ICliRunner {
             }
           }
 
+          if (rendered.usageData) {
+            usageData = mergeUsageData(usageData, rendered.usageData);
+          }
+
           if (shouldDisplay() && rendered.display) {
             process.stdout.write(rendered.display);
           }
@@ -262,6 +285,9 @@ export class CodexRunner implements ICliRunner {
           if (rendered.textContent) {
             output += rendered.textContent;
           }
+          if (rendered.usageData) {
+            usageData = mergeUsageData(usageData, rendered.usageData);
+          }
           if (shouldDisplay() && rendered.display) {
             process.stdout.write(rendered.display);
           }
@@ -281,8 +307,7 @@ export class CodexRunner implements ICliRunner {
           exitCode: exitCode ?? (this.killed ? 130 : 1),
           timedOut,
           contextOverflow,
-          // Codex does not provide usage data in the same format — omit gracefully
-          usageData: undefined,
+          usageData,
         });
       });
     });

package/src/core/failure-analyzer.ts

@@ -308,7 +308,8 @@ Respond with ONLY a markdown report in this exact format:
     const claudePath = getClaudePath();
 
     // Use configured model for failure analysis
-    const failureModel = getModel('failureAnalysis');
+    const failureEntry = getModel('failureAnalysis');
+    const failureModel = failureEntry.model;
     const proc = spawn(claudePath, [
       '--model', failureModel,
       '--no-session-persistence',

package/src/core/git.ts

@@ -1,4 +1,5 @@
 import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { logger } from '../utils/logger.js';
 import { extractProjectNumber, extractProjectName } from '../utils/paths.js';
@@ -213,10 +214,56 @@ export function isFileCommittedInHead(filePath: string): boolean {
   }
 }
 
+/**
+ * Extract a concise description from input.md for use in plan commit messages.
+ * Reads the first non-empty line and truncates to ~70 chars.
+ * Falls back to the project name if input.md can't be read.
+ */
+function extractPlanDescription(projectPath: string, fallback: string): string {
+  const inputPath = path.join(projectPath, 'input.md');
+  try {
+    const content = fs.readFileSync(inputPath, 'utf-8');
+    const firstLine = content.split('\n').find(line => line.trim().length > 0);
+    if (firstLine) {
+      // Strip leading markdown markers (-, *, [ ], [x], #, etc.)
+      let cleaned = firstLine.trim().replace(/^[-*#>\s]*(\[.\]\s*)?/, '').trim();
+      if (cleaned.length > 70) {
+        cleaned = cleaned.substring(0, 67) + '...';
+      }
+      if (cleaned.length > 0) {
+        return cleaned;
+      }
+    }
+  } catch {
+    // Can't read input.md, use fallback
+  }
+  return fallback;
+}
+
+/**
+ * Generate a description for amend commit messages.
+ * Uses the count and names of additional plan files if provided.
+ */
+function extractAmendDescription(additionalFiles?: string[]): string {
+  if (!additionalFiles || additionalFiles.length === 0) {
+    return 'updated plans';
+  }
+  // Extract task names from plan file paths (e.g., "plans/3-fix-bug.md" → "fix-bug")
+  const taskNames = additionalFiles
+    .map(f => path.basename(f, '.md'))
+    .map(name => name.replace(/^\d+-/, ''))
+    .filter(name => name.length > 0);
+
+  if (taskNames.length <= 3) {
+    return taskNames.join(', ');
+  }
+  return `${taskNames.length} tasks`;
+}
+
 /**
  * Commit planning artifacts (input.md and decisions.md) for a project.
- * Uses commit message format: RAF[NNN] Plan: project-name
- * For amendments: RAF[NNN] Amend: project-name
+ * Uses commit message format: RAF[project-name] Plan: description
+ * For amendments: RAF[project-name] Amend: description
  *
  * @param projectPath - Full path to the project folder (e.g., /path/to/RAF/017-decision-vault)
  * @param options - Optional settings
@@ -254,10 +301,17 @@ export async function commitPlanningArtifacts(projectPath: string, options?: { c
   const formatType = options?.isAmend ? 'amend' as const : 'plan' as const;
   const template = getCommitFormat(formatType);
   const commitPrefix = getCommitPrefix();
+
+  // Auto-generate description based on commit type
+  const description = options?.isAmend
+    ? extractAmendDescription(options?.additionalFiles)
+    : extractPlanDescription(projectPath, projectName);
+
   const commitMessage = renderCommitMessage(template, {
     prefix: commitPrefix,
-    projectId: projectNumber,
+    projectId: projectName,  // backwards compat: {projectId} resolves to projectName
     projectName,
+    description,
   });
 
   // Build list of files to stage (absolute paths)

package/src/core/pull-request.ts

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { logger } from '../utils/logger.js';
-import { getModel, getModelShortName } from '../utils/config.js';
+import { formatModelDisplay, getModel } from '../utils/config.js';
 import { extractProjectName, getInputPath, getDecisionsPath, getOutcomesDir, TASK_ID_PATTERN, numericFileSort } from '../utils/paths.js';
 
 export interface PrCreateResult {
@@ -279,7 +279,7 @@ Respond with ONLY the PR body in this exact format (no extra text, no code fence
 [1-3 bullet points describing how to verify these changes work correctly]`;
 
   try {
-    const prModel = getModelShortName(getModel('prGeneration'));
+    const prModel = formatModelDisplay(getModel('prGeneration').model);
     logger.info(`Generating PR with ${prModel}...`);
     const body = await callClaudeForPrBody(prompt, timeoutMs);
     return body;
@@ -365,7 +365,7 @@ async function callClaudeForPrBody(prompt: string, timeoutMs: number): Promise<s
     let output = '';
     let stderr = '';
 
-    const prModel = getModel('prGeneration');
+    const prModel = getModel('prGeneration').model;
     const proc = spawn(claudePath, [
       '--model', prModel,
       '--no-session-persistence',

package/src/core/runner-factory.ts

@@ -1,35 +1,35 @@
-import type { HarnessProvider } from '../types/config.js';
+import type { HarnessName } from '../types/config.js';
 import type { ICliRunner } from './runner-interface.js';
 import type { RunnerConfig } from './runner-types.js';
 import { ClaudeRunner } from './claude-runner.js';
 import { CodexRunner } from './codex-runner.js';
 
 /**
- * Create a CLI runner for the given provider configuration.
+ * Create a CLI runner for the given harness configuration.
  */
 export function createRunner(config: RunnerConfig = {}): ICliRunner {
-  const provider = config.provider ?? 'claude';
+  const harness = config.harness ?? 'claude';
 
-  switch (provider) {
+  switch (harness) {
     case 'claude':
       return new ClaudeRunner(config);
     case 'codex':
       return new CodexRunner(config);
     default:
-      throw new Error(`Unknown provider: ${provider}`);
+      throw new Error(`Unknown harness: ${harness}`);
   }
 }
 
 /**
- * Get the binary name for a given provider.
+ * Get the binary name for a given harness.
  */
-export function getProviderBinaryName(provider: HarnessProvider): string {
-  switch (provider) {
+export function getHarnessBinaryName(harness: HarnessName): string {
+  switch (harness) {
     case 'claude':
       return 'claude';
     case 'codex':
       return 'codex';
     default:
-      throw new Error(`Unknown provider: ${provider}`);
+      throw new Error(`Unknown harness: ${harness}`);
   }
 }

package/src/core/runner-interface.ts

@@ -1,7 +1,7 @@
 import type { RunnerOptions, RunResult } from './runner-types.js';
 
 /**
- * Provider-agnostic CLI runner interface.
+ * Harness-agnostic CLI runner interface.
  * Both ClaudeRunner and CodexRunner implement this interface.
  */
 export interface ICliRunner {

package/src/core/runner-types.ts

@@ -1,4 +1,4 @@
-import type { UsageData, HarnessProvider } from '../types/config.js';
+import type { UsageData, HarnessName } from '../types/config.js';
 
 /**
  * Options for a single runner execution (run, runVerbose, runInteractive, etc.).
@@ -52,14 +52,27 @@ export interface RunnerOptions {
 export interface RunnerConfig {
   /**
    * Model to use (e.g., opus, sonnet, haiku, gpt-5.4).
-   * Default: provider-specific default.
+   * Default: harness-specific default.
    */
   model?: string;
   /**
-   * CLI provider to use.
+   * CLI harness to use.
    * Default: 'claude'.
    */
-  provider?: HarnessProvider;
+  harness?: HarnessName;
+  /**
+   * Reasoning effort level to pass to the CLI.
+   * Claude CLI: --effort <level>
+   * Codex CLI: -c model_reasoning_effort="<level>"
+   * Only included when explicitly set.
+   */
+  reasoningEffort?: string;
+  /**
+   * Enable fast mode for faster output.
+   * Claude CLI: --settings '{"fastMode": true}'
+   * Only included when explicitly set to true.
+   */
+  fast?: boolean;
 }
 
 /**

package/src/parsers/codex-stream-renderer.ts

@@ -9,10 +9,13 @@
  * - TodoList: Task tracking (skipped)
  */
 
+import type { UsageData } from '../types/config.js';
 import type { RenderResult } from './stream-renderer.js';
 
 export interface CodexEvent {
   type: string;
+  id?: string;
+  model?: string;
   /** Claude flat-format fields (AgentMessage) */
   content?: string;
   /** Claude flat-format fields (CommandExecution) */
@@ -32,9 +35,12 @@ export interface CodexEvent {
     exit_code?: number;
     path?: string;
     change_kind?: string;
+    message?: string;
   };
   /** Error message (for error / turn.failed events) */
   message?: string;
+  /** Nested error object (for turn.failed events) */
+  error?: { message?: string };
   /** Usage data (for turn.completed events) */
   usage?: {
     input_tokens?: number;
@@ -172,25 +178,62 @@ function renderItemCompleted(event: CodexEvent): RenderResult {
         textContent: '',
       };
     }
+    case 'error': {
+      const msg = item.message ?? 'Unknown error';
+      return {
+        display: `  ✗ Error: ${msg}\n`,
+        textContent: msg,
+      };
+    }
     default:
       return { display: '', textContent: '' };
   }
 }
 
 function renderTurnCompleted(event: CodexEvent): RenderResult {
+  const usageData = extractUsageData(event);
+
   if (event.usage) {
     const { input_tokens, output_tokens } = event.usage;
     const parts: string[] = [];
-    if (input_tokens) parts.push(`in: ${input_tokens}`);
-    if (output_tokens) parts.push(`out: ${output_tokens}`);
+    if (input_tokens !== undefined) parts.push(`in: ${input_tokens}`);
+    if (output_tokens !== undefined) parts.push(`out: ${output_tokens}`);
     if (parts.length > 0) {
       return {
         display: `  → Usage: ${parts.join(', ')}\n`,
         textContent: '',
+        usageData,
       };
     }
   }
-  return { display: '', textContent: '' };
+  return { display: '', textContent: '', usageData };
+}
+
+function extractUsageData(event: CodexEvent): UsageData | undefined {
+  if (!event.usage) {
+    return undefined;
+  }
+
+  const modelId = event.model ?? 'codex';
+  const inputTokens = event.usage.input_tokens ?? 0;
+  const outputTokens = event.usage.output_tokens ?? 0;
+
+  return {
+    inputTokens,
+    outputTokens,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+    modelUsage: {
+      [modelId]: {
+        inputTokens,
+        outputTokens,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUsd: null,
+      },
+    },
+    totalCostUsd: null,
+  };
 }
 
 function renderError(event: CodexEvent): RenderResult {
@@ -202,7 +245,7 @@ function renderError(event: CodexEvent): RenderResult {
 }
 
 function renderTurnFailed(event: CodexEvent): RenderResult {
-  const msg = event.message ?? 'Turn failed';
+  const msg = event.error?.message ?? event.message ?? 'Turn failed';
   return {
     display: `  ✗ Failed: ${msg}\n`,
     textContent: msg,

package/src/prompts/amend.ts

@@ -56,15 +56,14 @@ export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
       ? modifiableTasks.map((t) => `- Task ${t.id}: ${t.taskName}`).join('\n')
       : '(none)';
 
-  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Your task is to ADD NEW TASKS or MODIFY PENDING tasks in an existing project.
+  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Add new tasks or modify pending tasks in an existing project.
 
-## IMPORTANT: Amendment Mode
+## Amendment Mode
 
-You are in AMENDMENT MODE. This means:
-- You MAY modify [MODIFIABLE] tasks (pending/failed) if the user requests changes
-- NEVER modify [PROTECTED] tasks (completed) - their outcomes depend on the original plan
-- DO NOT renumber existing tasks
-- You can create NEW tasks starting from number ${encodeTaskId(nextTaskNumber)}
+- [PROTECTED] tasks (completed): NEVER modify — their outcomes depend on the original plan
+- [MODIFIABLE] tasks (pending/failed): MAY modify if the user requests changes
+- Do NOT renumber existing tasks
+- New tasks start from number ${encodeTaskId(nextTaskNumber)}
 
 ## Project Location
 
@@ -72,54 +71,30 @@ Project folder: ${projectPath}
 
 ## Existing Tasks
 
-The following tasks already exist in this project:
-
 ${existingTasksSummary}
 
-### Protected Tasks (COMPLETED - cannot be modified)
+### Protected (COMPLETED)
 ${protectedTasksList}
 
-### Modifiable Tasks (PENDING/FAILED - can be modified if requested)
+### Modifiable (PENDING/FAILED)
 ${modifiableTasksList}
 
 ## Instructions
 
 ### Step 1: Read Context
 
-First, read the original project description from:
-- ${projectPath}/input.md
-
-And review existing decisions from:
-- ${projectPath}/decisions.md (if it exists)
+Read the original project description (\`${projectPath}/input.md\`) and existing decisions (\`${projectPath}/decisions.md\`, if it exists).
 
 ### Step 2: Analyze New Requirements
 
-Read the user's description of new tasks and identify what needs to be added. Consider:
-- How the new tasks relate to existing ones
-- 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:
+Consider how new tasks relate to existing ones and their dependencies. For follow-up/fix tasks, reference the previous task's outcome in the Context section:
 \`This is a follow-up to task NN. See outcome: {projectPath}/outcomes/NN-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:
-- Specific requirements and constraints
-- Technology preferences
-- Any existing code or patterns to follow
-- Edge cases to handle
-
-### Step 3.5: Record Decisions
+For EACH new task, use AskUserQuestion to gather specific requirements, technology preferences, existing patterns, and edge cases.
 
-After EACH interview question is answered, append the Q&A pair to the existing decisions file:
-- ${projectPath}/decisions.md
-
-Use this format:
+After EACH answer, append the Q&A to \`${projectPath}/decisions.md\`:
 \`\`\`markdown
 ## [Question asked]
 [User's answer]
@@ -127,12 +102,9 @@ Use this format:
 
 ### Step 4: Create New Plan Files
 
-After interviewing the user about all NEW tasks, create plan files starting from the next available number:
-- ${projectPath}/plans/${encodeTaskId(nextTaskNumber)}-task-name.md
-- ${projectPath}/plans/${encodeTaskId(nextTaskNumber + 1)}-task-name.md
-- etc.
+Create plan files starting from \`${projectPath}/plans/${encodeTaskId(nextTaskNumber)}-task-name.md\`. Use kebab-case names.
 
-Each plan file MUST have Obsidian-style frontmatter at the top, before the \`# Task:\` heading. The frontmatter uses standard YAML format with opening and closing \`---\` delimiters:
+Each plan file MUST have this structure:
 
 \`\`\`markdown
 ---
@@ -141,68 +113,38 @@ effort: medium
 # Task: [Task Name]
 
 ## Objective
-[Clear, one-sentence description of what this task accomplishes]
+[Clear, one-sentence description]
 
 ## 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 NN. See outcome: {projectPath}/outcomes/NN-task-name.md"]
+[Why this task is needed, relation to existing tasks]
+[For follow-ups: "This is a follow-up to task NN. See outcome: {projectPath}/outcomes/NN-task-name.md"]
 
 ## Dependencies
-[Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "1, 2"]
-[If a dependency fails, this task will be automatically blocked]
+[Optional — omit if none. Comma-separated task IDs, e.g., "1, 2"]
 
 ## Requirements
-[Specific requirements gathered from the user interview]
 - Requirement 1
 - Requirement 2
-- ...
 
 ## Implementation Steps
 1. [Step 1]
 2. [Step 2]
-3. [Step 3]
-...
 
 ## Acceptance Criteria
 - [ ] Criterion 1
 - [ ] Criterion 2
-- [ ] All tests pass
 
 ## Notes
-[Any additional context, warnings, or considerations]
-[Reference to existing task outcomes if relevant]
-\`\`\`
-
-### Frontmatter Requirements
-
-The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which model will execute the task:
-- \`effort: low\` — Trivial/mechanical changes, simple one-file edits, config changes
-- \`effort: medium\` — Well-scoped feature work, bug fixes with clear plans, multi-file changes following existing patterns
-- \`effort: high\` — Architectural changes, complex logic, tasks requiring deep codebase understanding
-
-Optionally, you can add an explicit \`model\` field to override the effort-based model selection:
-\`\`\`markdown
----
-effort: medium
-model: opus
----
-# Task: ...
+[Additional context, warnings, references to existing task outcomes]
 \`\`\`
 
-This is rarely needed — prefer using the \`effort\` label so the user's config controls the actual model used.
+**Frontmatter fields:**
+- \`effort\` (REQUIRED): \`low\` (trivial/mechanical), \`medium\` (well-scoped feature work), \`high\` (architectural/complex)
+- \`model\` (optional): Override effort-based model selection. Rarely needed.
 
 ### Step 5: Confirm Completion
 
-After creating all new plan files:
-1. Provide a summary of:
-   - The new tasks you've created, including the effort level for each task. Example format:
-     - Task 2: add-caching (effort: medium)
-     - Task 3: update-docs (effort: low)
-   - How they relate to existing tasks
-   - Total task count in the project
-2. Display this exit message to the user:
+Summarize new tasks with effort levels, their relation to existing tasks, and total task count. Then display:
 
 \`\`\`
 Planning complete! To exit this session and run your tasks:
@@ -210,26 +152,12 @@ Planning complete! To exit this session and run your tasks:
   2. Then run: raf do <project>
 \`\`\`
 
-## Important Rules
-
-1. NEVER modify COMPLETED task plans - they are [PROTECTED] because their outcomes depend on the original plan
-2. You MAY modify non-completed task plans (pending/failed) if the user requests changes - they are [MODIFIABLE]
-3. ALWAYS interview the user before creating or modifying plans
-4. New tasks start from number ${encodeTaskId(nextTaskNumber)}
-5. Use descriptive, kebab-case names for plan files
-6. Each plan should be self-contained with all context needed
-7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "1, 2")
-8. Tasks without dependencies should omit the Dependencies section entirely
-9. Be specific - vague plans lead to poor execution
-10. ALWAYS include the \`effort\` frontmatter field in every plan file — assess each task's complexity
-
-## Plan Output Style
-
-Plans can include whatever level of detail you deem helpful for the executing agent. Use your judgment:
-- Include implementation details when they clarify the approach
-- Code snippets are acceptable when they help illustrate a specific pattern
-- File paths are helpful when referencing existing project files, patterns, or directories
-- Focus on clarity — the goal is for the executing agent to understand what needs to be done`;
+## Rules
+
+- Always interview the user before creating or modifying plans
+- Each plan must be self-contained with all context needed
+- Be specific — vague plans lead to poor execution
+- Include implementation details, code snippets, and file paths when they clarify the approach`;
 
   const userMessage = `I want to add the following new tasks to this project: