rafcode 1.1.2 → 1.3.2

package/RAF/018-workflow-forge/decisions.md

@@ -0,0 +1,13 @@
+# Project Decisions
+
+## For the task number in progress reporting, what format would you like?
+[NNN] prefix - Shows as '[001] task-name' - task ID prefix style
+
+## Where should the [NNN] prefix appear?
+Both places - Show [NNN] prefix in both the spinner during execution and in the completion summary
+
+## For the 'plan' prompt update, what level of detail is acceptable?
+Paths are OK if referencing previous plan/output and the project. Avoid code snippets and implementation specifics otherwise.
+
+## For the 'do' prompt, should Task tool and subagents be mandatory or recommended?
+Mandatory - Every task execution must use Task tool and subagents, no exceptions.

package/RAF/018-workflow-forge/input.md

@@ -0,0 +1,2 @@
+- [ ] add task number to "raf do" progress reporting
+- [ ] update "plan" and "do" prompts. "plan" prompt should mention that the plan should output should be high level but detailed, excluding technical details and code snippets. i "do" specify the following "use task tool to split work and delegate to subagents task execution" 

package/RAF/018-workflow-forge/outcomes/001-add-task-number-progress.md

@@ -0,0 +1,61 @@
+# Outcome: Add Task Number to Progress Reporting
+
+## Summary
+
+Added [NNN] task number prefix to the "raf do" progress reporting in both spinner and completion summary.
+
+## Changes Made
+
+### Files Modified
+
+1. **src/utils/terminal-symbols.ts**
+   - Added optional `taskId` parameter to `formatTaskProgress` function
+   - Modified output format to include `[NNN]` prefix when task ID is provided
+   - Updated JSDoc to reflect new parameter and output format
+
+2. **src/commands/do.ts**
+   - Added `taskId` variable capture for closure in timer callback
+   - Updated all 4 calls to `formatTaskProgress` to pass task ID:
+     - Blocked task display (line 462)
+     - Running spinner update (line 519)
+     - Completed task display (line 670)
+     - Failed task display (line 690)
+
+3. **tests/unit/terminal-symbols.test.ts**
+   - Added 4 new tests for task ID prefix functionality:
+     - Running task with task ID prefix
+     - Completed task with task ID prefix and elapsed time
+     - Blocked task with task ID prefix
+     - Failed task with task ID prefix and elapsed time
+
+## Output Examples
+
+Before:
+```
+● auth-login 1m 23s
+✓ setup-db 2m 34s
+✗ deploy 45s
+⊘ depends-on-failed 2/5
+```
+
+After:
+```
+● [001] auth-login 1m 23s
+✓ [002] setup-db 2m 34s
+✗ [003] deploy 45s
+⊘ [004] depends-on-failed 2/5
+```
+
+## Acceptance Criteria
+
+- [x] Spinner shows [NNN] prefix during task execution
+- [x] Completion summary shows [NNN] prefix
+- [x] Task number correctly extracted from plan filename
+- [x] Formatting consistent across all progress messages
+
+## Test Results
+
+- All 747 tests pass
+- Build succeeds with no TypeScript errors
+
+<promise>COMPLETE</promise>

package/RAF/018-workflow-forge/outcomes/002-update-plan-do-prompts.md

@@ -0,0 +1,62 @@
+# Outcome: Update Plan and Do Prompts
+
+## Summary
+
+Updated the planning prompt to produce high-level, conceptual output and the execution prompt to mandate Task tool usage for subagent delegation.
+
+## Changes Made
+
+### Files Modified
+
+1. **src/prompts/planning.ts**
+   - Added "Plan Output Style" section with instructions for high-level output
+   - Explicitly prohibits code snippets and implementation details
+   - Allows file paths for project references (existing files, previous plans/outcomes, directories)
+   - Emphasizes describing WHAT needs to be done, not HOW to code it
+
+2. **src/prompts/execution.ts**
+   - Added mandatory Task tool instruction as first bullet point in Step 2
+   - Specifies agent types: Explore for codebase investigation, Plan for design decisions, general-purpose for implementation
+   - Instruction: "Use the Task tool to delegate work to subagents"
+
+3. **src/prompts/amend.ts**
+   - Added same "Plan Output Style" section as planning.ts for consistency
+   - Amendment mode now produces the same high-level output style as regular planning
+
+## New Prompt Content
+
+### Planning/Amend Prompt Addition
+```
+## Plan Output Style
+
+**CRITICAL**: Plans should be HIGH-LEVEL and CONCEPTUAL:
+- Describe WHAT needs to be done, not HOW to code it
+- Focus on architecture, data flow, and component interactions
+- NO code snippets or implementation details in plans
+- File paths ARE acceptable when referencing:
+  - Existing project files to modify
+  - Previous plan/outcome files for context
+  - Project structure and directories
+- Let the executing agent decide implementation specifics
+- Plans guide the work; they don't prescribe exact code
+```
+
+### Execution Prompt Addition
+```
+- **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)
+```
+
+## Acceptance Criteria
+
+- [x] Planning prompt instructs high-level output without code snippets
+- [x] Planning prompt allows file paths for project references
+- [x] Execution prompt mandates Task tool usage for subagent delegation
+- [x] Prompts remain clear and well-structured
+- [x] Amend prompt updated for consistency
+
+## Test Results
+
+- Build succeeds with no TypeScript errors
+- All 747 tests pass
+
+<promise>COMPLETE</promise>

package/RAF/018-workflow-forge/plans/001-add-task-number-progress.md

@@ -0,0 +1,30 @@
+# Task: Add Task Number to Progress Reporting
+
+## Objective
+Add [NNN] task number prefix to the "raf do" progress reporting in both spinner and completion summary.
+
+## Context
+Currently "raf do" shows task names during execution but doesn't show the task number (e.g., 001, 002). Adding the task number prefix helps users understand which specific task is running and correlate output with plan files.
+
+## Requirements
+- Display task number as [NNN] prefix (e.g., [001], [002])
+- Show prefix in spinner/progress message during task execution
+- Show prefix in task completion/failure summary
+- Format: `[001] task-name` style
+
+## Implementation Steps
+1. Locate the progress reporting code in the "do" command
+2. Extract task number from the task filename (e.g., "001" from "001-task-name.md")
+3. Update spinner message format to include [NNN] prefix
+4. Update completion summary format to include [NNN] prefix
+5. Test with multi-task projects to verify correct numbering
+
+## Acceptance Criteria
+- [ ] Spinner shows [NNN] prefix during task execution
+- [ ] Completion summary shows [NNN] prefix
+- [ ] Task number correctly extracted from plan filename
+- [ ] Formatting consistent across all progress messages
+
+## Notes
+- Task number comes from plan filename format: `NNN-task-name.md`
+- Existing progress reporting logic is in `src/commands/do.ts` or related execution files

package/RAF/018-workflow-forge/plans/002-update-plan-do-prompts.md

@@ -0,0 +1,34 @@
+# Task: Update Plan and Do Prompts
+
+## Objective
+Update the planning prompt to produce high-level output and the execution prompt to mandate Task tool usage for subagent delegation.
+
+## Context
+The planning prompt needs to guide Claude to produce high-level, conceptual plans without code snippets or excessive implementation details. The execution prompt needs to instruct Claude to use the Task tool to split work and delegate to subagents for better task management.
+
+## Requirements
+- **Plan prompt updates:**
+  - Instruct to produce high-level but detailed plans
+  - Avoid code snippets and implementation specifics
+  - File paths are acceptable when referencing previous plans/outputs or project structure
+
+- **Do prompt updates:**
+  - Add mandatory instruction: "Use Task tool to split work and delegate to subagents for task execution"
+  - This applies to all task executions, not optional
+
+## Implementation Steps
+1. Read the current planning prompt in `src/prompts/planning.ts`
+2. Add instructions for high-level output, avoiding code snippets
+3. Read the current execution prompt in `src/prompts/execution.ts`
+4. Add mandatory Task tool / subagent delegation instruction
+5. Ensure prompt changes don't conflict with existing instructions
+
+## Acceptance Criteria
+- [ ] Planning prompt instructs high-level output without code snippets
+- [ ] Planning prompt allows file paths for project references
+- [ ] Execution prompt mandates Task tool usage for subagent delegation
+- [ ] Prompts remain clear and well-structured
+
+## Notes
+- Prompt files are located in `src/prompts/` directory
+- The amend prompt (`amend.ts`) may also need similar updates for consistency

package/RAF/019-verbose-chronicle/decisions.md

@@ -0,0 +1,25 @@
+# Project Decisions
+
+## For the amendment iteration reference feature — when a new task looks like a follow-up/fix to a previous completed task, how should the reference appear in the new plan?
+Context section, make sure to put file path to prev task outcome.
+
+## Should the iteration reference be determined automatically by the planning Claude (via prompt instructions), or should RAF code analyze task content programmatically?
+Prompt-based (Recommended) — update the amend system prompt to instruct Claude to identify follow-ups and include references to previous tasks in new plans.
+
+## For verbose task name display — should the task name appear everywhere task ID is shown, or just in the main header?
+Everywhere — show task name alongside ID in all verbose log messages, status updates, and summaries.
+
+## For streaming Claude output in verbose mode — is it currently broken or is there a different streaming behavior wanted?
+In verbose mode only a summary of completed work is shown, not constant stream of how Claude executes. Need to investigate and fix — streaming should show real-time Claude output.
+
+## For verifying git commits before halting Claude — how should RAF check that the commit landed?
+All three checks combined: (1) HEAD changed from before task, (2) new commit message starts with RAF[project:task], and (3) outcome file is committed in git.
+
+## If the commit hasn't landed when the grace period expires, what should happen?
+Extend grace period — keep waiting (with a maximum cap) until the commit appears or a hard timeout is reached.
+
+## What should the maximum cap be for the extended grace period when waiting for commit?
+180 seconds (3 minutes total max wait for commit). Current grace period is 60 seconds.
+
+## For the verbose streaming fix — any suspicion about what's wrong?
+Investigate fully — debug the entire verbose code path end-to-end to find why streaming isn't working.

package/RAF/019-verbose-chronicle/input.md

@@ -0,0 +1,3 @@
+- [ ] in amendment, if new task looks like follow up or fix to previous completed task in the project - you should reference it in new plan (iteration plan)
+- [ ] in 'raf do --verbose' add task name  (not just "Executing task 011..."). also steam output from claude into terminal in verbose mode
+- [ ] raf halted before commit was done. make sure commit is there before halting claude by checking commits. see previous halt work in commit 4d3868c3ef4c607c59829e94462ffd0490d82a98

package/RAF/019-verbose-chronicle/outcomes/001-amend-iteration-references.md

@@ -0,0 +1,25 @@
+# Outcome: Amend Iteration References
+
+## Summary
+Enhanced the amend planning prompt to include outcome file paths for completed tasks and instruct Claude to reference previous task outcomes when creating follow-up/fix plans.
+
+## Changes Made
+
+### `src/prompts/amend.ts`
+- **Enhanced `existingTasksSummary`**: Completed tasks now include an `Outcome:` line with the full path to their outcome file (e.g., `Outcome: /project/outcomes/001-setup.md`). Non-completed tasks are unaffected.
+- **Added follow-up task instructions**: New "Identifying Follow-up Tasks" paragraph in Step 2 instructs Claude to reference previous task outcomes in the Context section when creating follow-up, fix, or iteration tasks. Includes the exact format to use.
+- **Updated plan template**: Added a placeholder line in the Context section showing the follow-up reference format.
+
+### `tests/unit/plan-command.test.ts`
+- Added 3 new tests:
+  - Verifies outcome file paths appear for completed tasks in the task summary
+  - Verifies outcome file paths do NOT appear for pending/failed tasks
+  - Verifies follow-up task instructions are present in the system prompt
+
+## Acceptance Criteria
+- [x] Amend prompt includes outcome file paths for completed tasks in the task summary
+- [x] Prompt instructs Claude to identify follow-up/fix tasks and reference outcomes in Context section
+- [x] Existing amend functionality is not broken (all 40 plan-command tests pass)
+- [x] All tests pass (1 pre-existing failure in planning-prompt.test.ts is unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/019-verbose-chronicle/outcomes/002-verbose-task-name-display.md

@@ -0,0 +1,31 @@
+# Outcome: Verbose Task Name Display
+
+## Summary
+Updated all verbose mode log messages in `do.ts` to include the task name alongside the task ID, using the format `task 011 (fix-login-bug)` instead of just `task 011`.
+
+## Changes Made
+
+### `src/commands/do.ts`
+- **Added `taskLabel` variable** (line 449): Computes `${task.id} (${displayName})` when the name differs from the ID, or just `${task.id}` when they're the same (to avoid redundant `001 (001)` display).
+- **Updated 7 verbose log messages** to use `taskLabel`:
+  - Blocked task warning: `Task ${taskLabel} blocked by failed dependency: ...`
+  - Retry message: `Retrying task ${taskLabel} (previously failed)...`
+  - Force re-run message: `Re-running task ${taskLabel} (force mode)...`
+  - Execute message: `Executing task ${taskLabel}...`
+  - Retry loop message: `Retry N/M for task ${taskLabel}...`
+  - Completion message: `Task ${taskLabel} completed (elapsed)`
+  - Stash message: `Changes for task ${taskLabel} stashed as: ...`
+  - Failure message: `Task ${taskLabel} failed: reason (elapsed)`
+
+### No test changes needed
+- The `formatRetryHistoryForConsole` function already supported task name display
+- No existing tests assert on verbose log message format directly
+- All 757 tests pass (1 pre-existing failure in planning-prompt.test.ts is unrelated)
+
+## Acceptance Criteria
+- [x] All verbose log messages that mention a task ID also show the task name
+- [x] Format is consistent across all messages (`taskLabel` pattern)
+- [x] Non-verbose mode is unaffected (uses `formatTaskProgress` separately)
+- [x] All tests pass
+
+<promise>COMPLETE</promise>

package/RAF/019-verbose-chronicle/outcomes/003-verbose-streaming-fix.md

@@ -0,0 +1,48 @@
+# Outcome: Verbose Streaming Fix
+
+## Summary
+Fixed `runVerbose()` to stream Claude's real-time execution output (tool calls, file operations, text) by using `--output-format stream-json --verbose` instead of plain `-p` mode which only showed the final summary.
+
+## Root Cause
+The `runVerbose()` method used the same `-p` (print) flag as `run()`, which runs Claude in non-interactive mode and only outputs the final assistant response text. This meant users saw a summary of completed work rather than real-time streaming of Claude's activity.
+
+## Changes Made
+
+### `src/parsers/stream-renderer.ts` (NEW)
+- **Stream event parser**: Parses NDJSON lines from Claude CLI `stream-json` output
+- **Human-readable rendering**: Converts events to user-friendly display:
+  - Text blocks: displayed directly
+  - Tool calls: descriptive one-line summaries (e.g., `→ Reading /src/main.ts`, `→ Running: npm test`)
+  - System/result events: suppressed (not useful for display)
+- **Tool descriptions**: Custom formatting for Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, TodoWrite, Task, and NotebookEdit tools
+- **Text content extraction**: Returns text content separately for completion marker detection and output parsing
+
+### `src/core/claude-runner.ts`
+- **Modified `runVerbose()` spawn args**: Added `--output-format stream-json --verbose` flags to get real-time NDJSON streaming events
+- **NDJSON line buffering**: Added line buffer to handle data chunks that split across NDJSON line boundaries
+- **Event rendering pipeline**: Each complete NDJSON line is parsed by `renderStreamEvent()`, display text goes to stdout, text content accumulates in `output` for completion detection and parsing
+- **Preserved all existing behavior**: Timeout, context overflow detection, completion marker detection, outcome file polling, and kill mechanisms all work unchanged
+- **`run()` method unchanged**: Non-verbose mode remains exactly as before
+
+### `tests/unit/stream-renderer.test.ts` (NEW)
+- 25 tests covering all event types: system, assistant (text), assistant (tool_use), user (tool results), result
+- Edge cases: empty lines, invalid JSON, empty content, unknown events
+- Tool-specific rendering: all 11 supported tools tested
+
+### `tests/unit/claude-runner.test.ts`
+- Added 4 new tests in `verbose stream-json output` describe block:
+  - Verifies `runVerbose()` includes `--output-format stream-json --verbose` flags
+  - Verifies `run()` does NOT include these flags
+  - Verifies NDJSON assistant events are parsed and text extracted correctly
+  - Verifies tool_use events don't add text to output
+
+## Acceptance Criteria
+- [x] `raf do --verbose` shows Claude's real-time execution (tool calls, file operations, thinking)
+- [x] Completion marker detection still works correctly
+- [x] Timeout mechanism still functions
+- [x] Context overflow detection still works
+- [x] Non-verbose mode (`raf do`) is completely unaffected
+- [x] Success/failure parsing still works from the captured output
+- [x] All existing tests pass (786 pass, 1 pre-existing failure in planning-prompt.test.ts is unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/019-verbose-chronicle/outcomes/004-commit-verification-before-halt.md

@@ -0,0 +1,56 @@
+# Outcome: Commit Verification Before Halt
+
+## Summary
+Added commit verification to the grace period logic so that when a COMPLETE marker is detected, the system verifies the expected git commit has actually landed before terminating. If the commit hasn't landed within the initial 60-second grace period, it extends polling up to a hard maximum of 180 seconds.
+
+## Changes Made
+
+### `src/core/git.ts`
+- **`getHeadCommitHash()`**: Returns the current HEAD commit hash (or null if not in a git repo)
+- **`getHeadCommitMessage()`**: Returns the HEAD commit message first line (or null)
+- **`isFileCommittedInHead(filePath)`**: Checks if a file exists in HEAD's tree using `git ls-tree`
+
+### `src/core/claude-runner.ts`
+- **New exports**: `COMPLETION_HARD_MAX_MS` (180s), `COMMIT_POLL_INTERVAL_MS` (10s), `CommitContext` interface
+- **New `commitContext` field in `ClaudeRunnerOptions`**: Allows passing pre-execution HEAD hash, expected commit prefix, and outcome file path
+- **`verifyCommit()` helper**: Checks all three conditions (HEAD changed, message prefix matches, outcome file committed)
+- **Updated `createCompletionDetector()`**: Accepts optional `commitContext` parameter. On grace period expiry:
+  - If COMPLETE marker and `commitContext` provided: verifies commit before killing
+  - If commit not verified: starts polling every 10s up to 180s total
+  - If FAILED marker or no `commitContext`: kills immediately (existing behavior)
+- **Both `run()` and `runVerbose()`**: Pass `commitContext` through to completion detector
+
+### `src/commands/do.ts`
+- **Captures HEAD hash** before each task execution attempt using `getHeadCommitHash()`
+- **Builds `commitContext`** with `preExecutionHead`, `expectedPrefix` (e.g., `RAF[005:001]`), and `outcomeFilePath`
+- **Passes `commitContext`** to both `run()` and `runVerbose()` calls
+- Gracefully handles non-git-repo case (skips commit verification)
+
+### `tests/unit/git-commit-helpers.test.ts` (NEW)
+- 11 tests covering all three new git functions:
+  - `getHeadCommitHash`: normal, not-in-repo, empty output, whitespace trimming
+  - `getHeadCommitMessage`: normal, not-in-repo, empty output
+  - `isFileCommittedInHead`: file exists, file missing, not-in-repo, command failure
+
+### `tests/unit/claude-runner.test.ts`
+- Added mock for `git.js` module (`getHeadCommitHash`, `getHeadCommitMessage`, `isFileCommittedInHead`)
+- Added 7 new tests in `commit verification during grace period` describe block:
+  - Commit verified within initial grace period (kills normally)
+  - Commit found during extended polling (extends, then kills)
+  - Commit never lands (hard max at 180s)
+  - FAILED markers don't trigger commit verification
+  - Backward compatible without commitContext
+  - Verifies commit message prefix must match
+  - Verifies outcome file must be committed
+
+## Acceptance Criteria
+- [x] HEAD hash is recorded before each task execution
+- [x] Grace period checks for commit matching `RAF[project:task]` pattern
+- [x] Grace period checks that outcome file is committed
+- [x] Grace period extends up to 180 seconds if commit not found
+- [x] Process is killed with a warning after 180 seconds if commit never lands
+- [x] Normal flow (commit lands within 60s) is not affected
+- [x] All existing tests pass (805 pass, 1 pre-existing failure in planning-prompt.test.ts is unrelated)
+- [x] New tests cover: commit found within grace, commit found in extended grace, commit never found (hard timeout)
+
+<promise>COMPLETE</promise>

package/RAF/019-verbose-chronicle/plans/001-amend-iteration-references.md

@@ -0,0 +1,35 @@
+# Task: Amend Iteration References
+
+## Objective
+When amending a project, instruct the planning Claude to reference previous completed tasks (with outcome file paths) in the Context section of new plans that are follow-ups or fixes.
+
+## Context
+Currently, amendment mode shows existing tasks with their status (COMPLETED/PENDING/FAILED) but doesn't guide Claude to treat new tasks as iterations on previous work. When a user amends a project to fix or follow up on a completed task, the new plan should reference the previous task's outcome file so the executing agent has full context about what was done before.
+
+## Requirements
+- Update the amend system prompt in `src/prompts/amend.ts` to instruct Claude to:
+  - Identify when new tasks are follow-ups, fixes, or iterations of previously completed tasks
+  - Include a reference to the previous task's outcome file path in the Context section of the new plan
+  - Use the format: "This is a follow-up to task NNN. See outcome: {projectPath}/outcomes/NNN-task-name.md"
+- The existing tasks summary already includes task IDs and names — enhance it to also show the outcome file path for completed tasks so Claude has the information readily available
+- This is purely a prompt engineering change — no programmatic detection logic needed
+- Do NOT modify the plan template structure (no new dedicated fields) — use the existing Context section
+
+## Implementation Steps
+1. Read the current amend prompt in `src/prompts/amend.ts`
+2. Enhance the `existingTasksSummary` generation to include outcome file paths for completed tasks
+3. Add instructions in the system prompt (Step 2: Analyze New Requirements section) telling Claude to identify follow-up/fix tasks and reference previous outcomes in the Context section
+4. Add an example in the prompt showing how to reference a previous task's outcome
+5. Update tests for the amend prompt if any exist
+
+## Acceptance Criteria
+- [ ] Amend prompt includes outcome file paths for completed tasks in the task summary
+- [ ] Prompt instructs Claude to identify follow-up/fix tasks and reference outcomes in Context section
+- [ ] Existing amend functionality is not broken
+- [ ] All tests pass
+
+## Notes
+- The outcome file path follows the pattern: `{projectPath}/outcomes/{taskId}-{taskName}.md`
+- Only completed tasks have meaningful outcome files to reference
+- The `AmendPromptParams` interface already includes `projectPath` which can be used to construct outcome paths
+- The `existingTasks` array includes `planFile` from which the task name can be extracted for outcome path construction

package/RAF/019-verbose-chronicle/plans/002-verbose-task-name-display.md

@@ -0,0 +1,38 @@
+# Task: Verbose Task Name Display
+
+## Objective
+Show the task name alongside the task ID in all verbose mode log messages (e.g., "Executing task 011 (fix-login-bug)..." instead of "Executing task 011...").
+
+## Context
+Currently in verbose mode, log messages reference tasks by ID only (e.g., "Executing task 011..."). The task name is available via `extractTaskNameFromPlanFile()` and is already stored in `displayName`, but not consistently used in all log messages. Users need the task name to quickly understand what's running without cross-referencing plan files.
+
+## Requirements
+- Add task name to ALL verbose log messages that reference a task ID, including:
+  - "Executing task 011..." → "Executing task 011 (fix-login-bug)..."
+  - "Retrying task 011 (previously failed)..." → include name
+  - "Re-running task 011 (force mode)..." → include name
+  - "Task 011 completed (2m 30s)" → include name
+  - "Task 011 failed: reason (2m 30s)" → include name
+  - "Task 011 blocked by failed dependency: 003" → include name
+  - Retry messages
+  - Changes stashed messages
+- The task name is already computed as `displayName` in `do.ts` — use it consistently
+- Also update the `logger.setContext()` call if it's being used (currently no-op but may be restored)
+- Update the verbose summary section to include task names where applicable
+
+## Implementation Steps
+1. Read `src/commands/do.ts` and identify all verbose log messages that reference task IDs
+2. Update each message to include `displayName` in parentheses after the task ID
+3. Ensure the format is consistent: `task ${task.id} (${displayName})` everywhere
+4. Update tests if any test verbose output format
+
+## Acceptance Criteria
+- [ ] All verbose log messages that mention a task ID also show the task name
+- [ ] Format is consistent across all messages
+- [ ] Non-verbose mode is unaffected
+- [ ] All tests pass
+
+## Notes
+- `displayName` is already computed at line 447 of `do.ts` as `taskName ?? task.id`
+- When `displayName` equals `task.id` (name extraction failed), showing it in parens would be redundant — consider only showing parens when name differs from ID
+- The `setContext` and `clearContext` methods on logger are currently no-ops (deprecated) but the calls remain in do.ts

package/RAF/019-verbose-chronicle/plans/003-verbose-streaming-fix.md

@@ -0,0 +1,45 @@
+# Task: Verbose Streaming Fix
+
+## Objective
+Investigate and fix why verbose mode only shows a summary of completed work instead of streaming Claude's real-time execution output.
+
+## Context
+The `runVerbose()` method in `claude-runner.ts` does call `process.stdout.write(text)` on stdout data, but users report only seeing a summary rather than a real-time stream. The likely root cause is that Claude CLI is invoked with the `-p` (print/pipe) flag, which runs in non-interactive mode and only outputs the final assistant response text — not the intermediate tool calls, file reads, code edits, and thinking steps that constitute the real-time execution flow.
+
+The non-verbose `run()` method correctly uses `-p` since it only needs the final output for parsing. But `runVerbose()` needs a different approach to show Claude's work as it happens.
+
+## Requirements
+- Investigate the exact cause of why streaming doesn't show real-time Claude activity
+- Fix `runVerbose()` to stream Claude's real-time execution output (tool calls, file operations, code writing, etc.)
+- The fix likely involves either:
+  - Removing `-p` flag and using a different mode that streams intermediate output
+  - Using `--output-format stream-json` to get streaming JSON events and rendering them
+  - Using PTY-based execution (like `runInteractive`) but without stdin interaction
+- The completion marker detection must still work with the new approach
+- Output parsing for success/failure must still function correctly
+- The timeout mechanism must still work
+- Non-verbose mode must remain unchanged
+
+## Implementation Steps
+1. Investigate what Claude CLI output modes are available (check `claude --help` or documentation)
+2. Determine the best approach for streaming real-time output while maintaining completion detection
+3. Modify `runVerbose()` to use the chosen streaming approach
+4. Ensure completion markers can still be detected in the new output format
+5. Test that timeout, context overflow detection, and kill mechanisms still work
+6. Verify output can still be parsed for success/failure determination
+
+## Acceptance Criteria
+- [ ] `raf do --verbose` shows Claude's real-time execution (tool calls, file operations, thinking)
+- [ ] Completion marker detection still works correctly
+- [ ] Timeout mechanism still functions
+- [ ] Context overflow detection still works
+- [ ] Non-verbose mode (`raf do`) is completely unaffected
+- [ ] Success/failure parsing still works from the captured output
+- [ ] All existing tests pass (update as needed for new implementation)
+
+## Notes
+- The `run()` method must NOT be changed — only `runVerbose()` needs modification
+- Claude CLI streaming options may include `--output-format stream-json` which outputs JSON events
+- If using stream-json, a renderer/formatter will be needed to display events in a human-readable way
+- PTY-based approach (similar to `runInteractive`) could work but would need `--dangerously-skip-permissions` to avoid interactive prompts
+- The `activeProcess` tracking needs to work with whichever approach is chosen for the shutdown handler

package/RAF/019-verbose-chronicle/plans/004-commit-verification-before-halt.md

@@ -0,0 +1,62 @@
+# Task: Commit Verification Before Halt
+
+## Objective
+Before halting Claude after detecting a completion marker, verify that the expected git commit has actually been made, extending the grace period if the commit hasn't landed yet.
+
+## Context
+The current halt mechanism in `claude-runner.ts` detects completion markers (`<promise>COMPLETE/FAILED</promise>`) and starts a fixed 60-second grace period before killing Claude. However, if Claude hasn't finished its git commit within that window, the process gets killed mid-commit, potentially leaving the repository in a broken state. The previous halt work was introduced in commit `4d3868c`. This task adds commit verification to ensure the grace period only expires after the commit is confirmed.
+
+See previous halt work: commit `4d3868c3ef4c607c59829e94462ffd0490d82a98`
+
+## Dependencies
+003
+
+## Requirements
+- Record the HEAD commit hash before task execution begins
+- After the grace period triggers, verify the commit landed by checking ALL three conditions:
+  1. HEAD has changed from the pre-execution hash
+  2. The new HEAD commit message starts with the expected `RAF[project:task]` pattern
+  3. The outcome file is tracked in git (committed, not just on disk)
+- If the commit hasn't landed when the initial grace period (60s) expires:
+  - Extend the grace period by polling for the commit
+  - Continue extending until either the commit is confirmed or a hard maximum of 180 seconds is reached
+  - Poll at a reasonable interval (e.g., every 10 seconds)
+- If the hard maximum is reached without commit confirmation, kill the process and log a warning
+- Add git helper functions to `src/core/git.ts` for:
+  - Getting the current HEAD hash
+  - Checking if a commit message matches a pattern
+  - Checking if a file is committed in HEAD
+- The completion detector factory (`createCompletionDetector`) needs additional parameters:
+  - Pre-execution HEAD hash
+  - Expected commit message prefix (e.g., `RAF[005:001]`)
+  - Outcome file path (already available)
+- Pass the necessary context from `do.ts` when creating the completion detector
+
+## Implementation Steps
+1. Add new git utility functions to `src/core/git.ts`:
+   - `getHeadCommitHash()`: returns current HEAD hash
+   - `getHeadCommitMessage()`: returns HEAD commit message
+   - `isFileCommittedInHead(filePath)`: checks if file is in HEAD commit
+2. Update `createCompletionDetector` in `claude-runner.ts` to accept commit verification parameters
+3. Modify the grace period logic: instead of a single `setTimeout`, use an interval that checks for the commit
+4. If initial 60s grace period expires without commit, continue polling up to 180s total
+5. Update `do.ts` to capture HEAD hash before task execution and pass commit context to the runner
+6. Add unit tests for the new git functions
+7. Add unit tests for the extended grace period behavior
+
+## Acceptance Criteria
+- [ ] HEAD hash is recorded before each task execution
+- [ ] Grace period checks for commit matching `RAF[project:task]` pattern
+- [ ] Grace period checks that outcome file is committed
+- [ ] Grace period extends up to 180 seconds if commit not found
+- [ ] Process is killed with a warning after 180 seconds if commit never lands
+- [ ] Normal flow (commit lands within 60s) is not affected
+- [ ] All existing tests pass
+- [ ] New tests cover: commit found within grace, commit found in extended grace, commit never found (hard timeout)
+
+## Notes
+- The `ClaudeRunnerOptions` interface may need new fields for the commit context
+- On task failure, Claude does NOT commit (changes are stashed) — the commit check should only apply when a COMPLETE marker is detected, not FAILED
+- The project number and task ID are already available in `do.ts` where the runner is called
+- Use `execSync` for git commands (consistent with existing `git.ts` functions)
+- Handle "not in git repo" gracefully — skip commit verification if not in a git repo