rafcode 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -30,15 +30,15 @@ src/
 Each RAF project follows this structure:
 ```
 RAF/
-└── NNN-project-name/        # e.g., 001-fix-bug or a00-feature
+└── abcdef-project-name/    # 6-char epoch-based base26 ID (a-z only)
     ├── input.md             # User requirements
     ├── decisions.md         # Q&A from planning interviews
     ├── plans/               # Task breakdowns
-    │   ├── 001-task-name.md
-    │   └── 002-another-task.md
+    │   ├── 01-task-name.md  # 2-char base36 task ID
+    │   └── 02-another-task.md
     └── outcomes/            # Completed task results
-        ├── 001-task-name.md
-        └── 002-another-task.md
+        ├── 01-task-name.md
+        └── 02-another-task.md
 ```
 
 ### Plan File Structure
@@ -54,7 +54,7 @@ Each plan file follows this structure:
 [Why this task is needed]
 
 ## Dependencies
-[Optional - comma-separated task IDs, e.g., "001, 002"]
+[Optional - comma-separated task IDs, e.g., "01, 02"]
 [If a dependency fails, this task is blocked]
 
 ## Requirements
@@ -75,7 +75,7 @@ Each plan file follows this structure:
 
 **Dependencies Section**:
 - Optional - omit if task has no dependencies
-- Uses task IDs only (e.g., `001, 002`)
+- Uses task IDs only (e.g., `01, 02`)
 - If a dependency fails, dependent tasks are automatically blocked
 
 ## Development Commands
@@ -134,16 +134,28 @@ npm run lint       # Type check without emit
 - All failure outcomes end with `<promise>FAILED</promise>` marker
 
 ### Project Naming Convention
-- Format: `NNN-project-name` (001-999) then base36 `XXX-project-name` (a00-zzz)
+- Format: `XXXXXX-project-name` where `XXXXXX` is a 6-character base26 ID (a-z only)
+- ID is generated from `(current_unix_seconds - RAF_EPOCH)` encoded as base26, left-padded with 'a' to 6 characters
+- Base26 encoding: a=0, b=1, ..., z=25 (lowercase letters only, no digits)
+- RAF_EPOCH is 2026-01-01T00:00:00Z (Unix timestamp 1767225600)
 - Project name is kebab-case derived from core feature
-- Supports 46,000+ projects
+- IDs are unique by timestamp and sort chronologically
+- Project IDs are visually distinct from task IDs (which use base36 with digits)
+
+### Task ID Format
+- Task IDs are 2-character base36 strings, zero-padded (e.g., `01`, `0a`, `1z`, `zz`)
+- Base36 charset: 0-9, a-z (lowercase)
+- Supports up to 1296 tasks per project (00-zz)
+- Task numbering starts at `01` (not `00`)
+- Sort order: 00, 01, ..., 09, 0a, 0b, ..., 0z, 10, 11, ..., zz
+- Utilities in `src/utils/paths.ts`: `encodeTaskId()`, `decodeTaskId()`, `TASK_ID_PATTERN`
+- File naming: `01-task-name.md`, `0a-task-name.md`, etc.
 
 ### Project Identifier Resolution
 Support multiple identifier formats in commands:
-1. Numeric ID: `3` or `003`
-2. Base36 ID: `a00`, `a01`
-3. Project name: `fix-stuff` (case-insensitive, partial match)
-4. Full folder name: `001-fix-stuff` (exact match)
+1. Base26 ID: `abcdef` (6-character epoch-based ID, a-z only)
+2. Project name: `fix-stuff` (case-insensitive, partial match)
+3. Full folder name: `abcdef-fix-stuff` (exact match)
 
 Use `resolveProjectIdentifierWithDetails()` from `src/utils/paths.ts`
 
@@ -159,9 +171,9 @@ Claude writes a concise description of what was accomplished, focusing on the ac
 
 Examples:
 ```
-RAF[005:001] Add validation for user input fields
-RAF[005:002] Fix null pointer in auth handler
-RAF[a01:003] Refactor database connection pooling
+RAF[abcdef:01] Add validation for user input fields
+RAF[abcdef:02] Fix null pointer in auth handler
+RAF[abaaba:03] Refactor database connection pooling
 ```
 
 - Claude commits code changes and outcome file together in one commit per task
@@ -174,12 +186,96 @@ RAF[a01:003] Refactor database connection pooling
 - New tasks numbered sequentially after last task
 - No modification of existing plan files
 
-### Multi-Project Execution
-- `raf do <projects...>` supports multiple projects
-- Sequential execution (not parallel) for git safety
-- Continue on failure, report results at end
-- Deduplicates repeated projects
-- Non-verbose per-project summaries reflect tasks executed in the current run (remaining tasks at start) so elapsed time matches the work performed
+### Worktree Mode
+- `raf plan --worktree` and `raf do --worktree` run in an isolated git worktree
+- Worktree path: `~/.raf/worktrees/<repo-basename>/<project-id>` (e.g., `~/.raf/worktrees/myapp/abcdef-my-feature`)
+- Branch name matches the project folder name (e.g., `abcdef-my-feature`)
+- `--worktree` flag is required on `plan`; on `do` it is auto-detected when a worktree project is selected from the picker
+- `raf do` without arguments auto-discovers pending worktree projects and merges them into the project picker
+  - Worktree projects are labeled with `[worktree]` suffix in the picker
+  - Selecting a worktree project automatically enables worktree mode (post-action picker, worktree cwd)
+  - Projects are deduplicated: when a folder exists in both local and worktree, the worktree version is shown
+  - Mixed local and worktree projects are sorted chronologically
+- `raf status` automatically discovers and displays worktree projects (no flag needed)
+  - List mode: worktree projects that differ from main repo shown under `Worktrees:` header
+  - Single project mode: shows both main and worktree state when they differ
+  - Identical worktree projects are hidden; worktree-only projects always shown
+- Lifecycle: create worktree -> plan in worktree -> pick post-action -> execute in worktree -> auto-run chosen action
+- **Post-execution picker**: Before task execution, an interactive picker asks what to do after tasks complete:
+  1. **Merge** — merge branch into original branch (fast-forward preferred, merge-commit fallback)
+  2. **Create PR** — push branch and create a GitHub PR (uses `createPullRequest()` from `pull-request.ts`)
+  3. **Leave branch** — do nothing, keep the branch as-is
+- PR option runs preflight checks immediately; falls back to "leave" if `gh` CLI is missing or unauthenticated
+- On task failure, the chosen post-action is skipped with a message
+- Worktree cleanup: all post-actions (merge, PR, leave) clean up the worktree directory (branch preserved in git)
+- On failure, worktree is kept for inspection
+- `raf plan --amend --worktree` auto-recreates the worktree when it was cleaned up:
+  - If the branch exists (common after cleanup): recreates worktree from the existing branch
+  - If no branch exists: creates a fresh worktree and copies project files from the main repo
+- On plan failure with no plan files created, the worktree is cleaned up automatically
+- Core utilities in `src/core/worktree.ts`: `createWorktree()`, `createWorktreeFromBranch()`, `branchExists()`, `validateWorktree()`, `mergeWorktreeBranch()`, `removeWorktree()`, `listWorktreeProjects()`
+- Post-execution picker: `pickPostExecutionAction()` and `PostExecutionAction` type exported from `src/commands/do.ts`
+
+### PR Creation from Worktree
+- `src/core/pull-request.ts` provides `createPullRequest()` to create GitHub PRs from worktree branches
+- Requires `gh` CLI installed and authenticated (`gh auth login`)
+- Auto-detects base branch (from `refs/remotes/origin/HEAD`, falling back to `main`/`master`)
+- PR title derived from project name (kebab-case to human-readable)
+- PR body generated by Claude Haiku summarizing input.md, decisions.md, and outcomes
+- Falls back to simple body if Claude is unavailable
+- Auto-pushes branch to origin if not already pushed
+- Preflight checks: `prPreflight()` validates gh CLI, authentication, GitHub remote
+- Key functions: `createPullRequest()`, `prPreflight()`, `generatePrBody()`, `generatePrTitle()`, `detectBaseBranch()`
+
+
+## PR Review
+
+When reviewing a PR or addressing PR comments, use `gh` CLI to read PR details:
+
+```bash
+# View PR description and metadata
+gh pr view <number>
+
+# View PR diff
+gh pr diff <number>
+
+# View review comments (inline code comments)
+gh api repos/{owner}/{repo}/pulls/<number>/comments
+
+# View PR review summaries
+gh api repos/{owner}/{repo}/pulls/<number>/reviews
+
+# View general PR conversation comments (non-inline)
+gh api repos/{owner}/{repo}/issues/<number>/comments
+
+# List PR files changed
+gh pr diff <number> --name-only
+
+# View PR checks/CI status
+gh pr checks <number>
+```
+
+### Checking Out PR Branches
+
+PR branches are often checked out in git worktrees. Before creating a new checkout, check for existing worktrees:
+
+```bash
+# List existing worktrees
+git worktree list
+
+# Find the branch name from the PR
+gh pr view <number> --json headRefName -q .headRefName
+
+# If gh is rate-limited, list remote branches to find it
+git ls-remote --heads origin
+
+# Check if branch is already in a worktree (look for the path in worktree list output)
+# If it is, work directly in that worktree path (e.g., /Users/eremeev/.raf/worktrees/Paperi/<branch>)
+# If not, checkout normally:
+git fetch origin <branch> && git checkout <branch>
+```
+
+When working in a worktree, use absolute paths to the worktree directory for all file operations and builds.
 
 ## Important Reminders
 

package/RAF/aaaabt-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/aaaabt-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/aaaabt-verbose-chronicle/outcomes/01-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/aaaabt-verbose-chronicle/outcomes/02-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/aaaabt-verbose-chronicle/outcomes/03-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/aaaabt-verbose-chronicle/outcomes/04-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/aaaabt-verbose-chronicle/plans/01-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/aaaabt-verbose-chronicle/plans/02-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/aaaabt-verbose-chronicle/plans/03-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/aaaabt-verbose-chronicle/plans/04-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