rafcode 2.3.0 → 2.4.1-0

package/RAF/ahvrih-rate-forge/outcomes/08-plan-execution-metadata.md

@@ -0,0 +1,130 @@
+# Outcome: Add Per-Task Execution Metadata + Remove Effort Config
+
+## Summary
+Implemented Obsidian-style frontmatter for plan files with required `effort` metadata, introduced `effortMapping` config section, redefined `models.execute` as a ceiling and fallback, removed the legacy `effort.*` config section entirely, and relaxed planning prompt restrictions.
+
+## Key Changes
+
+### Types (`src/types/config.ts`)
+- Removed `EffortConfig`, `EffortScenario`, `EffortLevel` types
+- Removed `VALID_EFFORTS` constant
+- Removed `effort` from `RafConfig` interface
+- Added `TaskEffortLevel` type (`'low' | 'medium' | 'high'`)
+- Added `EffortMappingConfig` type (`{ low: ClaudeModelName; medium: ClaudeModelName; high: ClaudeModelName }`)
+- Added `VALID_TASK_EFFORTS` constant (`['low', 'medium', 'high']`)
+- Updated `DEFAULT_CONFIG` with `effortMapping: { low: 'haiku', medium: 'sonnet', high: 'opus' }`
+
+### Config Utilities (`src/utils/config.ts`)
+- Removed `getEffort()` accessor
+- Removed effort validation logic
+- Added `effortMapping` to `VALID_TOP_LEVEL_KEYS`
+- Added `effortMapping` validation (values must be valid model names)
+- Added `getEffortMapping()` accessor
+- Added `resolveEffortToModel(effort)` function
+- Added `MODEL_TIER_ORDER` constant for tier comparison
+- Added `getModelTier(modelName)` function:
+  - Returns numeric tier: haiku=1, sonnet=2, opus=3
+  - Extracts family from full model IDs (e.g., `claude-opus-4-6` → opus)
+  - Unknown models default to tier 3 (no cap)
+- Added `applyModelCeiling(resolvedModel, ceiling?)` function:
+  - Caps resolved model to the ceiling tier
+  - Uses `models.execute` as default ceiling
+
+### Frontmatter Parser (`src/utils/frontmatter.ts`) - NEW FILE
+- Parses Obsidian-style frontmatter from plan file content
+- Format: `key: value` lines at top, terminated by `---` (no opening delimiter)
+- Extracts `effort` (required) and `model` (optional) fields
+- Case-insensitive effort values
+- Returns warnings for invalid/unknown keys (doesn't throw)
+- Handles missing delimiter gracefully (returns empty frontmatter)
+- Detects markdown headings before delimiter (invalid frontmatter)
+
+### State Derivation (`src/core/state-derivation.ts`)
+- Added frontmatter parsing alongside dependency parsing
+- Extended `DerivedTask` interface with:
+  - `frontmatter?: PlanFrontmatter` - parsed metadata
+  - `frontmatterWarnings?: string[]` - parsing warnings
+
+### Do Command (`src/commands/do.ts`)
+- Removed `getEffort()` usage
+- Added `resolveTaskModel()` helper function:
+  - Uses explicit `model` frontmatter if present
+  - Falls back to `effort` → `effortMapping` resolution
+  - Applies ceiling using `applyModelCeiling()`
+  - Returns `{ model, source }` for logging
+- Creates new `ClaudeRunner` per task with resolved model
+- Logs missing frontmatter warnings
+- Implements retry escalation: failed tasks retry with ceiling model
+
+### Config Command (`src/commands/config.ts`)
+- Removed `getEffort()` usage and fallback
+
+### Claude Runner (`src/core/claude-runner.ts`)
+- Removed `effortLevel` option from `ClaudeRunnerOptions`
+- Removed `CLAUDE_CODE_EFFORT_LEVEL` env var injection
+
+### Planning Prompts (`src/prompts/planning.ts`, `src/prompts/amend.ts`)
+- Removed restrictive "Plan Output Style" section
+- Removed "NO code snippets or implementation details" restrictions
+- Added frontmatter format requirements with effort assessment guidelines:
+  - `low` — trivial/mechanical changes, simple one-file edits
+  - `medium` — well-scoped features, bug fixes, multi-file changes
+  - `high` — architectural changes, complex logic, deep codebase understanding
+
+### Documentation
+- **`src/prompts/config-docs.md`**:
+  - Removed entire `effort` section
+  - Added `effortMapping` section with defaults and validation rules
+  - Updated `models.execute` description to document ceiling/fallback behavior
+- **`CLAUDE.md`**:
+  - Updated "Plan File Structure" to include frontmatter format
+  - Documented effort metadata and model resolution
+  - Removed effort config references
+  - Added ceiling behavior documentation
+
+### Tests
+- **`tests/unit/config.test.ts`**:
+  - Removed effort config tests
+  - Added `effortMapping` validation tests
+  - Added `getModelTier()` tests
+  - Added `applyModelCeiling()` tests
+  - Added `resolveEffortToModel()` tests
+- **`tests/unit/config-command.test.ts`**:
+  - Updated tests to use `effortMapping` instead of `effort`
+- **`tests/unit/frontmatter.test.ts`** - NEW FILE:
+  - Comprehensive tests for frontmatter parsing
+  - Valid frontmatter tests (effort, model, both)
+  - No frontmatter tests (missing delimiter, empty content, markdown heading)
+  - Warning tests (unknown keys, invalid values)
+  - Edge cases (whitespace, tabs, multiple delimiters)
+- **`tests/unit/claude-runner.test.ts`**:
+  - Removed `effortLevel` tests
+  - Updated to test environment passing without effort override
+- **`tests/unit/claude-runner-interactive.test.ts`**:
+  - Updated default model test to accept both short aliases and full model IDs
+  - Updated environment test to not depend on user's env vars
+- **`tests/unit/validation.test.ts`**:
+  - Updated default model test to accept config-dependent values
+
+## Acceptance Criteria Verification
+- [x] The entire `effort.*` config section is removed (types, defaults, validation, accessors, env var)
+- [x] `ClaudeRunner` no longer sets `CLAUDE_CODE_EFFORT_LEVEL`
+- [x] Existing config files with `effort` are handled gracefully (rejected as unknown key with warning)
+- [x] `effortMapping` config exists with sensible defaults (low→haiku, medium→sonnet, high→opus)
+- [x] `models.execute` acts as a ceiling — resolved model is capped to this tier
+- [x] Ceiling works correctly: opus plan + sonnet ceiling = sonnet execution
+- [x] Under-ceiling works correctly: haiku plan + sonnet ceiling = haiku execution
+- [x] Retry escalation: failed task retries use the ceiling model
+- [x] Plan files with frontmatter are parsed correctly (effort and optional model extracted)
+- [x] Plan files without frontmatter produce a warning and fall back to config model
+- [x] Effort label in frontmatter correctly maps to a model via `effortMapping`
+- [x] Explicit `model` in frontmatter takes precedence over `effort` mapping but is still subject to ceiling
+- [x] Planning prompts no longer restrict implementation details
+- [x] Planning prompts mandate effort frontmatter with assessment guidelines
+- [x] Invalid frontmatter values produce a warning but don't block execution
+- [x] Frontmatter parsing doesn't break existing plan files (backwards compatible)
+- [x] Tests cover effort removal, effortMapping, ceiling logic, frontmatter parsing, and override logic
+- [x] All 1273 tests pass
+- [x] TypeScript builds successfully
+
+<promise>COMPLETE</promise>

package/RAF/ahvrih-rate-forge/plans/01-remove-claude-command-config.md

@@ -0,0 +1,36 @@
+# Task: Remove `claudeCommand` from Config
+
+## Objective
+Remove the `claudeCommand` configuration key entirely, hardcoding `"claude"` as the CLI binary name.
+
+## Context
+The `claudeCommand` config key allows overriding the Claude CLI binary path. In practice this is unnecessary — Claude CLI is always installed as `claude`. Removing it simplifies the config schema and also resolves the PR #4 review comment: with a broken config file, `getClaudeCommand()` could throw before `raf config` launched its repair session. Hardcoding eliminates that failure path.
+
+## Requirements
+- Remove `claudeCommand` from `RafConfig` interface and `DEFAULT_CONFIG` in `src/types/config.ts`
+- Remove `getClaudeCommand()` accessor from `src/utils/config.ts`
+- Update `getClaudePath()` in `src/core/claude-runner.ts` to hardcode `"claude"` instead of calling `getClaudeCommand()`
+- Remove `claudeCommand` from config validation logic in `src/utils/config.ts`
+- Update `src/prompts/config-docs.md` to remove the `claudeCommand` section
+- Update any tests that reference `claudeCommand`
+- Verify `raf config` works correctly even when `~/.raf/raf.config.json` is malformed (this is the PR #4 fix — with hardcoded command, `getClaudePath` no longer depends on config)
+
+## Implementation Steps
+1. Remove `claudeCommand` from the TypeScript interface and default config
+2. Remove the `getClaudeCommand()` helper and update all call sites to use `"claude"` directly
+3. Update `getClaudePath()` to use hardcoded `"claude"` in the `which` lookup
+4. Remove `claudeCommand` from config validation (the strict validator should reject it as unknown key if a user still has it — consider adding a migration warning or silently ignoring it)
+5. Update config-docs.md documentation
+6. Update/remove affected tests
+7. Verify the `raf config` fallback path no longer depends on config file state
+
+## Acceptance Criteria
+- [ ] `claudeCommand` key no longer exists in types, defaults, validation, or documentation
+- [ ] `getClaudePath()` works without reading any config
+- [ ] `raf config` launches successfully even with a completely broken config file
+- [ ] All existing tests pass (updated as needed)
+- [ ] Config files containing `claudeCommand` are handled gracefully (warning or silent ignore)
+
+## Notes
+- This also addresses the PR #4 review comment about `raf config` being unusable as a repair path when config is malformed. With the hardcoded command, the entire Claude runner initialization is config-independent.
+- Consider whether to warn users who still have `claudeCommand` in their config or just silently ignore it via validation.

package/RAF/ahvrih-rate-forge/plans/02-fix-mixed-attempt-cost.md

@@ -0,0 +1,33 @@
+# Task: Fix Mixed-Attempt Cost Underreporting
+
+## Objective
+Fix cost calculation to compute cost per-attempt rather than on accumulated usage, preventing underreporting when attempts have mixed aggregate-only and per-model usage data.
+
+## Context
+`TokenTracker.addTask()` currently calls `accumulateUsage(attempts)` to merge all attempts into one `UsageData`, then calls `calculateCost()` on the merged result. The problem: if some attempts have `modelUsage` populated and others only have aggregate fields (which `extractUsageData` allows), the merged result has a non-empty `modelUsage` map. `calculateCost()` then takes the per-model branch and only prices tokens in `modelUsage`, silently dropping aggregate-only tokens from attempts that lacked `modelUsage`. This means mixed-attempt retries underreport cost.
+
+## Requirements
+- Calculate cost independently for each attempt's `UsageData`
+- Each attempt uses per-model pricing if it has `modelUsage`, or aggregate-fallback (Sonnet rates) if it doesn't
+- Sum the per-attempt costs to get the task total
+- The per-attempt cost calculation should also be available for the display formatter (it already receives a `calculateAttemptCost` callback)
+- Preserve the accumulated usage totals for token count display (input/output/cache totals should still be summed across attempts)
+
+## Implementation Steps
+1. Modify `addTask()` in `TokenTracker` to calculate cost per-attempt, then sum into the task's `CostBreakdown`
+2. Ensure `calculateCost()` is called on individual attempt `UsageData` objects, not on the accumulated merge
+3. Update the `CostBreakdown` aggregation to sum per-attempt breakdowns
+4. Verify that `formatTaskTokenSummary()` still works correctly — it receives per-attempt cost via callback, so the callback should use single-attempt `calculateCost()`
+5. Add test cases covering the mixed-attempt scenario: one attempt with `modelUsage`, another with only aggregate fields
+
+## Acceptance Criteria
+- [ ] Cost is calculated per-attempt, not on merged usage
+- [ ] Mixed attempts (some with modelUsage, some without) report accurate total cost
+- [ ] Per-attempt display in multi-attempt summaries shows correct individual costs
+- [ ] Grand total cost across all tasks remains accurate
+- [ ] New test cases cover the mixed-attempt edge case
+- [ ] Existing token tracking tests still pass
+
+## Notes
+- The key insight: `accumulateUsage()` is fine for summing token counts for display, but cost calculation must happen before merging to respect the per-model vs. aggregate distinction per attempt.
+- The `formatTaskTokenSummary` already accepts a `calculateAttemptCost` callback — this callback should call `calculateCost` on individual attempt data, which is already the correct granularity.

package/RAF/ahvrih-rate-forge/plans/03-rate-limit-estimation.md

@@ -0,0 +1,82 @@
+# Task: Add 5h Window Rate Limit Estimation + Plan Session Token Tracking
+
+## Objective
+Add an estimated percentage of the 5-hour rate limit window consumed, displayed after each task and in the grand total summary. Also add token usage tracking and display for `raf plan` interactive sessions.
+
+## Dependencies
+02
+
+## Context
+Anthropic's subscription plans use a shared credit pool per 5-hour window. The pool is measured in cost-weighted credits, not raw token count. Heavier models (Opus) consume the pool faster than lighter ones (Haiku) in proportion to their API pricing ratios. Users need visibility into how much of their 5-hour window they've consumed during a RAF session.
+
+The baseline is 88,000 Sonnet-equivalent tokens per 5h window. All token usage is normalized to Sonnet-equivalent tokens using the API pricing ratios:
+- Haiku input/output costs ~1/3 of Sonnet → 1 Haiku token ≈ 0.33 Sonnet tokens
+- Opus input/output costs ~1.67× of Sonnet → 1 Opus token ≈ 1.67 Sonnet tokens
+- Cache read/create tokens follow the same model-specific pricing ratios
+
+## Requirements
+
+### Rate Limit Estimation (raf do)
+- Convert all token usage to "Sonnet-equivalent tokens" using the configured pricing ratios
+- The conversion formula: `sonnetEquivalentTokens = actualCost / sonnetCostPerToken` (where sonnet cost per token is derived from the configured Sonnet pricing)
+- **Per-attempt model awareness**: task 08 introduces per-task model selection and retry escalation (a task may start with haiku and retry with sonnet/opus). Cost and rate limit calculations must use the actual model that ran each attempt, not a single model for the whole task. This is already handled if cost is calculated per-attempt (task 02), but the rate limit conversion must also use the correct per-attempt pricing
+- Display estimated 5h window percentage after each task (alongside existing token summary)
+- Display cumulative 5h window percentage in the grand total summary
+- New config keys under `display` section:
+  - `display.showRateLimitEstimate` (boolean, default: `true`) — toggle showing the % estimate
+  - `display.showCacheTokens` (boolean, default: `true`) — toggle showing cache token counts in summaries
+- New config key for the baseline cap:
+  - `rateLimitWindow.sonnetTokenCap` (number, default: `88000`) — the Sonnet-equivalent token cap for the 5h window
+- The percentage is a rough estimate — make this clear in the display (e.g., "~42% of 5h window")
+
+### Token Tracking for Plan Sessions (raf plan)
+- After the `raf plan` interactive session ends, display a token usage summary (input/output tokens, cache, estimated cost, 5h window %)
+- Approach: Claude CLI saves session data to `~/.claude/projects/<escaped-path>/<session-id>.jsonl` — each assistant message entry contains usage data (input_tokens, output_tokens, cache tokens, model name)
+- Pass `--session-id <uuid>` to `runInteractive()` so we know exactly which session file to read after the session ends
+- After `runInteractive()` returns, locate and parse the session JSONL file to extract and accumulate all usage data from assistant message entries
+- The session file path is `~/.claude/projects/<escaped-project-path>/<session-id>.jsonl` where the project path is escaped by replacing `/` with `-`
+- Reuse the existing `TokenTracker` and display formatters to show the summary
+- This also applies to `raf plan --amend` sessions
+
+## Implementation Steps
+
+### Rate Limit Estimation
+1. Add new config types: `display` section with `showRateLimitEstimate` and `showCacheTokens` booleans; `rateLimitWindow` section with `sonnetTokenCap` number
+2. Add defaults to `DEFAULT_CONFIG`, validation rules, and config accessor helpers
+3. Update config-docs.md with the new keys
+4. Implement the Sonnet-equivalent conversion in `TokenTracker` — the simplest approach: use the total estimated cost (already calculated) divided by the Sonnet cost-per-token to get Sonnet-equivalent tokens
+5. Add a method to `TokenTracker` to compute cumulative 5h window percentage
+6. Update `formatTaskTokenSummary()` to optionally append the window percentage
+7. Update `formatTokenTotalSummary()` to optionally show the cumulative window percentage
+8. Respect the `display.showRateLimitEstimate` and `display.showCacheTokens` config flags in the formatters
+
+### Plan Session Token Tracking
+9. Modify `runInteractive()` in `claude-runner.ts` to accept an optional `sessionId` parameter and pass it as `--session-id <uuid>` to the Claude CLI spawn
+10. In `plan.ts` (both plan and amend flows), generate a UUID before calling `runInteractive()` and pass it
+11. Create a utility to locate and parse the Claude session JSONL file: read `~/.claude/projects/<escaped-path>/<session-id>.jsonl`, extract usage data from all assistant message entries, and accumulate into a `UsageData` structure
+12. After `runInteractive()` returns in `plan.ts`, call the session parser, feed results to `TokenTracker`, and display the summary using existing formatters
+13. Handle edge cases: session file not found (Claude CLI may change storage), malformed entries, zero usage
+
+### Tests
+14. Add tests for the conversion logic, display formatting, and session file parsing
+
+## Acceptance Criteria
+- [ ] After each task, the token summary includes `~X% of 5h window` when enabled
+- [ ] Grand total summary includes cumulative `~X% of 5h window` when enabled
+- [ ] Percentage correctly reflects cost-weighted usage (Opus tasks consume more % than Haiku tasks for same raw token count)
+- [ ] Multi-model tasks (retry escalation) correctly account for different models across attempts in both cost and rate limit calculations
+- [ ] `display.showRateLimitEstimate: false` hides the percentage
+- [ ] `display.showCacheTokens: false` hides cache read/create token counts from summaries
+- [ ] `rateLimitWindow.sonnetTokenCap` correctly adjusts the denominator
+- [ ] Config validation accepts the new keys
+- [ ] Config docs updated with new keys and explanation
+- [ ] After `raf plan` interactive session, a token usage summary is displayed
+- [ ] After `raf plan --amend` interactive session, a token usage summary is displayed
+- [ ] Session file parsing handles missing/malformed files gracefully (warn, don't crash)
+- [ ] Tests cover the conversion math, display toggling, and session file parsing
+
+## Notes
+- The percentage is inherently an estimate — the actual Anthropic rate limit algorithm may differ. The display should communicate this (tilde prefix).
+- The conversion can be simplified by reusing the already-computed dollar cost: `sonnetEquivalentTokens = totalCost / ((sonnetInputPrice + sonnetOutputPrice) / 2M)`. But a more accurate approach would normalize input and output tokens separately since they have different price ratios. Consider which approach is more appropriate.
+- This task depends on task 02 (fix mixed-attempt cost) because accurate cost calculation is the foundation for accurate percentage estimation.
+- Task 08 introduces per-task model selection and retry escalation (cheaper model on first attempt, ceiling model on retry). The per-attempt cost calculation from task 02 already handles different models per attempt via `modelUsage`, but the Sonnet-equivalent conversion for rate limit % must also respect per-attempt model differences. Since conversion is derived from cost (which is already per-attempt), this should work naturally — but verify with a test case covering a multi-model retry scenario.

package/RAF/ahvrih-rate-forge/plans/04-show-version-in-do-logs.md

@@ -0,0 +1,32 @@
+# Task: Show RAF Version and Model in `raf do` Logs
+
+## Objective
+Display the RAF version and execution model in a single combined line at the start of `raf do` execution.
+
+## Context
+Currently `raf do` logs don't prominently show what version of RAF is running or which model is being used for execution. This information is useful for debugging and for users to confirm their setup. The model name should be shown in its full format (e.g., `claude-opus-4-6` rather than just `opus`).
+
+## Requirements
+- Display a single combined line at the start of task execution, before any tasks run
+- Format: `RAF v{version} | Model: {fullModelId}`
+- Version comes from `package.json` via the existing `getVersion()` utility
+- Model should be the full model ID (e.g., `claude-opus-4-6`), not the short alias
+- Use the existing logger formatting (e.g., `logger.info` or appropriate level)
+- Do NOT show effort level — the `effort.*` config is being removed in task 08
+
+## Implementation Steps
+1. In `src/commands/do.ts`, add a log line at the start of the execution flow (before the first task begins)
+2. Resolve the full model ID — if the config uses a short alias like `opus`, resolve it to the full model ID
+3. Format and display the combined line
+4. Ensure this appears in both worktree and non-worktree execution modes
+
+## Acceptance Criteria
+- [ ] A version/model line appears at the start of every `raf do` execution
+- [ ] Model name is shown in full format (e.g., `claude-opus-4-6`)
+- [ ] Line appears before any task execution output
+- [ ] Works in both worktree and non-worktree modes
+
+## Notes
+- The existing `getVersion()` utility is in `src/utils/version.ts`.
+- Model resolution from short alias to full ID may already exist in the codebase — check how `ClaudeRunner` resolves model names.
+- Keep the display subtle (dim or info level) so it doesn't clutter the output.

package/RAF/ahvrih-rate-forge/plans/05-sync-main-before-worktree.md

@@ -0,0 +1,40 @@
+# Task: Sync Main Branch Before Worktree/PR Operations
+
+## Objective
+Automatically push main to remote before creating a PR and pull main from remote before creating a git worktree, with a configurable toggle.
+
+## Context
+When working with worktrees, the worktree is branched from the current state of the main branch. If main is behind the remote, the worktree starts from stale code. Similarly, before creating a PR, the main branch should be pushed to ensure the remote has the latest state for the PR base. Auto-detecting the main branch (from `origin/HEAD`) avoids hardcoding assumptions about branch naming.
+
+## Requirements
+- Before creating a worktree (`raf plan --worktree` or `raf do --worktree`): pull the main branch from remote to ensure the worktree starts from the latest code
+- Before creating a PR (post-execution "Create PR" action): push the main branch to remote so the PR base is up to date
+- Auto-detect the main branch name from `refs/remotes/origin/HEAD` (the same detection logic used in `pull-request.ts` via `detectBaseBranch()`)
+- New config key: `syncMainBranch` (boolean, default: `true`)
+- When `syncMainBranch` is `false`, skip both push and pull operations
+- Handle failures gracefully: if push/pull fails (e.g., no remote, auth issues), warn but don't block the operation
+
+## Implementation Steps
+1. Add `syncMainBranch` config key to `RafConfig` interface, `DEFAULT_CONFIG`, validation, and config-docs.md
+2. Add `getSyncMainBranch()` accessor in `src/utils/config.ts`
+3. Reuse or extract `detectBaseBranch()` from `src/core/pull-request.ts` into a shared utility (it's already used for PR base detection)
+4. Add a `syncMainBranch()` utility function that pulls main before worktree creation
+5. Integrate pull into the worktree creation flow in `src/core/worktree.ts` or the calling code in `do.ts`/`plan` command
+6. Integrate push into the PR creation flow — before `createPullRequest()` is called, push main
+7. Add appropriate logging (info level) when syncing occurs
+8. Handle errors: catch failures, log warning, continue with the operation
+9. Update config-docs.md
+
+## Acceptance Criteria
+- [ ] Main branch is pulled from remote before worktree creation (when `syncMainBranch: true`)
+- [ ] Main branch is pushed to remote before PR creation (when `syncMainBranch: true`)
+- [ ] Main branch name is auto-detected from `origin/HEAD`
+- [ ] `syncMainBranch: false` skips both operations
+- [ ] Failures in push/pull produce warnings but don't block the workflow
+- [ ] Config validation accepts the new key
+- [ ] Config docs updated
+
+## Notes
+- `detectBaseBranch()` in `src/core/pull-request.ts` already handles the `origin/HEAD` detection with fallback to `main`/`master`. Reuse this logic rather than duplicating it.
+- The pull should only pull the main branch, not the current branch or all branches.
+- Be careful about the pull: if the user has uncommitted changes on main, a pull could fail. Consider using `git fetch origin main && git merge --ff-only origin/main` which fails cleanly if main has diverged.

package/RAF/ahvrih-rate-forge/plans/06-sync-readme-with-codebase.md

@@ -0,0 +1,61 @@
+# Task: Sync README with Codebase (Critical Items)
+
+## Objective
+Fix critical discrepancies between README.md and the actual codebase implementation.
+
+## Context
+The README documents features that no longer exist (like `--merge` flag) and is missing documentation for major features (post-execution picker, PR creation). This causes user confusion and makes the tool harder to adopt.
+
+## Dependencies
+01, 05
+
+## Requirements
+Fix these three critical discrepancies:
+
+### 1. Remove `--merge` flag references
+The `--merge` CLI flag for `raf do` is documented in the README but does not exist in the code. It was replaced by an interactive post-execution action picker. All references to `--merge` must be removed and replaced with the actual behavior.
+
+Affected locations in README:
+- Usage examples showing `raf do my-feature -w --merge`
+- Command Reference table listing `--merge` as a flag
+- Any other mentions of `--merge`
+
+### 2. Document the post-execution action picker
+When running `raf do` in worktree mode, an interactive picker appears BEFORE task execution asking what to do after tasks complete. The three options are:
+- **Merge** — merge branch into the original branch (fast-forward preferred, merge-commit fallback)
+- **Create PR** — push branch and create a GitHub PR
+- **Leave branch** — keep the branch as-is, do nothing
+
+This is implemented in `src/commands/do.ts` via `pickPostExecutionAction()`. On task failure, the chosen post-action is skipped. After successful post-actions (merge, PR, leave), the worktree directory is cleaned up automatically (the git branch is preserved).
+
+### 3. Document PR creation from worktree
+The "Create PR" post-execution action is a significant feature not mentioned in the README at all. It:
+- Requires `gh` CLI installed and authenticated
+- Auto-detects the base branch from `origin/HEAD`
+- Generates a PR title from the project name
+- Generates a PR body using Claude summarizing input.md, decisions.md, and outcomes
+- Auto-pushes the branch to origin if needed
+- Runs preflight checks; falls back to "leave branch" if `gh` is missing or unauthenticated
+
+Also fix the worktree cleanup description — the README currently says worktrees persist and need manual cleanup, but they're actually auto-cleaned after post-actions (only the git branch is preserved). On failure, the worktree IS kept for inspection.
+
+## Implementation Steps
+1. Read the current README.md thoroughly
+2. Remove all `--merge` flag references from examples and command reference
+3. Update the Worktree Mode section to describe the post-execution picker flow
+4. Add documentation about PR creation capability and its requirements (`gh` CLI)
+5. Fix the worktree cleanup description to reflect auto-cleanup behavior
+6. Ensure examples in the README use valid, existing flags only
+7. Review the updated text for consistency and accuracy
+
+## Acceptance Criteria
+- [ ] No references to `--merge` flag remain in README
+- [ ] Post-execution action picker is documented with all three options
+- [ ] PR creation from worktree is documented including prerequisites
+- [ ] Worktree cleanup behavior is accurately described
+- [ ] All CLI examples use valid, existing flags
+- [ ] README reads naturally and doesn't feel patched
+
+## Notes
+- This task depends on 01 (remove `claudeCommand`) and 05 (sync main branch) because those tasks add/change config keys that should be reflected if mentioned in README.
+- Only fix the critical items listed above. Medium and low priority discrepancies (missing verbose flag in table, blocked symbol, token tracking docs, effort/pricing docs) are out of scope for this task.

package/RAF/ahvrih-rate-forge/plans/07-no-session-persistence.md

@@ -0,0 +1,28 @@
+# Task: Add --no-session-persistence to Throwaway Claude Calls
+
+## Objective
+Prevent PR body generation and failure analysis Claude calls from polluting the user's session history.
+
+## Context
+Claude CLI saves every session to disk by default, making them appear in `claude --resume`. Throwaway utility calls (PR body generation, failure analysis) clutter this history with sessions the user will never want to resume. The name generation utility already solved this by adding `--no-session-persistence` to its `spawn()` call (implemented in the token-reaper project). The same pattern should be applied to the remaining throwaway Claude invocations.
+
+## Requirements
+- Add `--no-session-persistence` flag to the `spawn()` call in `callClaudeForPrBody()` in `src/core/pull-request.ts`
+- Add `--no-session-persistence` flag to the `spawn()` call in the failure analyzer in `src/core/failure-analyzer.ts`
+- Both already use `-p` (print mode), which is required for `--no-session-persistence` to work
+- Follow the exact same pattern used in `src/utils/name-generator.ts`
+
+## Implementation Steps
+1. In `src/core/pull-request.ts`, add `'--no-session-persistence'` to the args array in `callClaudeForPrBody()`
+2. In `src/core/failure-analyzer.ts`, add `'--no-session-persistence'` to the args array in the Claude spawn call
+3. Verify both functions still work correctly — the flag should be transparent to the output
+
+## Acceptance Criteria
+- [ ] PR body generation sessions don't appear in `claude --resume`
+- [ ] Failure analysis sessions don't appear in `claude --resume`
+- [ ] Both features still function correctly (output unchanged)
+- [ ] Pattern matches the existing implementation in `name-generator.ts`
+
+## Notes
+- This is a minimal two-line change (one per file). The flag is well-tested in name-generator.ts already.
+- The `--no-session-persistence` flag only works with `-p` (print mode), which both call sites already use.

package/RAF/ahvrih-rate-forge/plans/08-plan-execution-metadata.md

@@ -0,0 +1,123 @@
+# Task: Add Per-Task Execution Metadata + Remove Effort Config
+
+## Objective
+Add Obsidian-style frontmatter to plan files with required effort metadata, introduce an effort-to-model mapping config, redefine `models.execute` as a ceiling, remove the legacy `effort.*` config section entirely, and relax planning prompt restrictions.
+
+## Context
+The philosophy is "plan with a smart model, execute with a less smart model when possible." Currently, all tasks execute with the same globally-configured model. By adding frontmatter metadata to plan files during the planning stage, the planner (typically Opus) can assess each task's complexity and recommend the appropriate execution model.
+
+The config's role shifts from "pick one model for all tasks" to "set the budget ceiling." The planner recommends effort per task, which maps to a model via `effortMapping`. The final model is capped by `models.execute` (the ceiling). This gives users budget control while letting the planner differentiate tasks.
+
+The existing `effort.*` config section (which maps to Claude CLI's `--effort` flag via `CLAUDE_CODE_EFFORT_LEVEL` env var) should be removed entirely — it's a separate concept from the task complexity "effort" label in plan frontmatter.
+
+Additionally, the planning prompts currently contain restrictive wording that discourages implementation details in plans. This wording should be removed to allow the planning model to include whatever level of detail it deems appropriate.
+
+## Dependencies
+04
+
+## Requirements
+
+### Frontmatter Metadata in Plan Files
+- Plan files MUST have Obsidian-style properties at the top, before the `# Task:` heading
+- Format uses only a closing `---` delimiter (no opening delimiter):
+  ```
+  effort: medium
+  ---
+  # Task: ...
+  ```
+- `effort` is REQUIRED — a human-readable task complexity label (low/medium/high) that maps to a model. NOT Claude's `--effort` flag
+- `model` is OPTIONAL — an explicit model override (short alias or full model ID) that bypasses the effort mapping entirely
+- If both `model` and `effort` are present, `model` takes precedence over the effort mapping
+- If frontmatter is missing (e.g., manually created plans), warn and fall back to the config default model
+
+### Effort-to-Model Mapping
+- New config section: `effortMapping` that maps complexity labels to model names
+- Default mapping: `{ low: "haiku", medium: "sonnet", high: "opus" }`
+- When a plan has `effort: medium`, RAF resolves it to the model from the mapping (e.g., sonnet)
+- The mapping values follow the same validation as model names (short aliases or full model IDs)
+- Add to `DEFAULT_CONFIG`, validation, config-docs.md
+
+### Config as Ceiling + Fallback
+- `models.execute` serves dual purpose:
+  1. **Ceiling**: the maximum model tier allowed for task execution
+  2. **Fallback**: the model used when a plan has no effort frontmatter (e.g., manually created plans, legacy plans)
+- Model tier ordering: haiku < sonnet < opus (based on pricing — cheaper = lower tier)
+- When frontmatter IS present: final model = `min(resolved_model, models.execute)` where "min" means the cheaper/lower-tier model
+- When frontmatter is MISSING: final model = `models.execute` directly (with a warning about missing frontmatter)
+- Example: if `models.execute: "sonnet"` (ceiling) and plan says `effort: high` (maps to opus), the task runs with sonnet (capped)
+- Example: if `models.execute: "sonnet"` and plan says `effort: low` (maps to haiku), the task runs with haiku (under ceiling, no cap)
+- Example: if plan has no frontmatter, the task runs with sonnet (fallback)
+- The explicit `model` field in frontmatter is ALSO subject to the ceiling — no way to exceed the config ceiling from a plan file
+- **Retry escalation**: when a task fails and is retried, bump the model to `models.execute` (the ceiling) for the retry attempt. If the first attempt already used the ceiling model, retry with the same model. This gives failing tasks the best available model on subsequent attempts
+- Implement a `getModelTier()` utility that returns a numeric tier for comparison (using pricing ratios or a simple ordered list)
+
+### Remove Legacy Effort Config
+- Remove the entire `effort.*` config section from `RafConfig` interface in `src/types/config.ts`
+- Remove `EffortConfig`, `EffortScenario`, `EffortLevel` types, `VALID_EFFORTS` constant
+- Remove `getEffort()` accessor from `src/utils/config.ts`
+- Remove effort validation logic from config validation
+- Remove `effortLevel` option from `ClaudeRunner` run options in `src/core/claude-runner.ts`
+- Remove `CLAUDE_CODE_EFFORT_LEVEL` env var injection from `ClaudeRunner`
+- Remove all `getEffort()` call sites:
+  - `src/commands/do.ts` — `getEffort('execute')` passed to runner options
+  - `src/commands/config.ts` — `getEffort('config')` and its fallback
+  - Any other call sites
+- Remove effort from `src/prompts/config-docs.md`
+- Update tests that reference effort config
+
+### Planning Prompt Changes
+- Remove the "Plan Output Style" section that says "CRITICAL: Plans should be HIGH-LEVEL and CONCEPTUAL" from both `src/prompts/planning.ts` and `src/prompts/amend.ts`
+- Remove the restrictive bullet points: "Describe WHAT needs to be done, not HOW to code it", "NO code snippets or implementation details in plans"
+- Replace with neutral guidance: plans can include whatever level of detail the planner deems helpful
+- Add instructions that the planner MUST include effort frontmatter on every task, with guidance on how to assess complexity:
+  - `low` — trivial/mechanical changes, simple one-file edits, config changes
+  - `medium` — well-scoped feature work, bug fixes with clear plans, multi-file changes following existing patterns
+  - `high` — architectural changes, complex logic, tasks requiring deep codebase understanding
+- Document the frontmatter format (Obsidian-style, closing `---` only) in the prompt
+
+## Implementation Steps
+1. Remove the legacy effort config: delete `EffortConfig`, `EffortScenario`, `EffortLevel` types, `VALID_EFFORTS`, `getEffort()`, the `effort` key from `RafConfig` and `DEFAULT_CONFIG`, effort validation, `effortLevel` from `ClaudeRunner` run options, `CLAUDE_CODE_EFFORT_LEVEL` env var logic
+2. Remove all `getEffort()` call sites in `do.ts`, `config.ts`, and anywhere else
+3. Add new `effortMapping` config section: type definition, defaults (`{ low: "haiku", medium: "sonnet", high: "opus" }`), validation (values must be valid model names), accessor helper
+4. Implement model tier comparison: a `getModelTier()` utility that returns a numeric rank based on the model family (haiku=1, sonnet=2, opus=3). For full model IDs, extract the family name. For unknown models, default to highest tier (no cap)
+5. Redefine `models.execute` semantics: it now acts as ceiling + fallback. Update its documentation to reflect this
+6. Create a frontmatter parser utility that extracts `model` and `effort` from plan file content (parse `key: value` lines before the closing `---` delimiter)
+7. Integrate frontmatter parsing into `state-derivation.ts` alongside the existing `parseDependencies()` — store parsed metadata on the task state object
+8. In `do.ts`, before each task execution, resolve the per-task model:
+   - Read frontmatter `model` or resolve `effort` via `effortMapping`
+   - Apply ceiling: `min(resolved_model, models.execute)` using tier comparison
+   - Fall back to `models.execute` if no frontmatter (fallback role)
+9. Implement retry escalation: when retrying a failed task, use `models.execute` (ceiling) instead of the original resolved model. The retry logic in `do.ts` should detect attempt > 1 and escalate
+10. Modify `ClaudeRunner` or the task execution loop to support per-task model (consider creating a new runner instance per task if the model differs)
+10. Update `src/prompts/planning.ts` — remove the restrictive "Plan Output Style" section, replace with neutral guidance, add required frontmatter format instructions with effort assessment criteria
+11. Update `src/prompts/amend.ts` — same prompt changes
+12. Update config-docs.md: remove effort section, add effortMapping section, update models.execute description to "ceiling"
+13. Update CLAUDE.md: update "Plan File Structure" to include frontmatter, remove effort references, document ceiling behavior
+14. Update/remove affected tests
+
+## Acceptance Criteria
+- [ ] The entire `effort.*` config section is removed (types, defaults, validation, accessors, env var)
+- [ ] `ClaudeRunner` no longer sets `CLAUDE_CODE_EFFORT_LEVEL`
+- [ ] Existing config files with `effort` are handled gracefully (warning or silent ignore)
+- [ ] `effortMapping` config exists with sensible defaults (low→haiku, medium→sonnet, high→opus)
+- [ ] `models.execute` acts as a ceiling — resolved model is capped to this tier
+- [ ] Ceiling works correctly: opus plan + sonnet ceiling = sonnet execution
+- [ ] Under-ceiling works correctly: haiku plan + sonnet ceiling = haiku execution
+- [ ] Retry escalation: failed task retries use the ceiling model
+- [ ] Plan files with frontmatter are parsed correctly (effort and optional model extracted)
+- [ ] Plan files without frontmatter produce a warning and fall back to config model
+- [ ] Effort label in frontmatter correctly maps to a model via `effortMapping`
+- [ ] Explicit `model` in frontmatter takes precedence over `effort` mapping but is still subject to ceiling
+- [ ] Planning prompts no longer restrict implementation details
+- [ ] Planning prompts mandate effort frontmatter with assessment guidelines
+- [ ] Invalid frontmatter values produce a warning but don't block execution
+- [ ] Frontmatter parsing doesn't break existing plan files (backwards compatible)
+- [ ] Tests cover effort removal, effortMapping, ceiling logic, frontmatter parsing, and override logic
+
+## Notes
+- The frontmatter parser should be lenient: ignore unknown keys, handle missing `---` delimiter gracefully, treat malformed properties as "no frontmatter" rather than erroring. The format is Obsidian-style: `key: value` lines at the top of the file, terminated by a `---` line (no opening delimiter).
+- This task depends on task 04 (version/model display) since the per-task model override should be visible in the execution log line.
+- The `parseDependencies()` function in `state-derivation.ts` already reads plan file content — the frontmatter parser can be called at the same point, avoiding a second file read.
+- Removing effort config is a breaking change for users who have `effort.*` in their config file. The config validator should handle this gracefully (warn about unknown key, don't crash).
+- Model tier comparison for full model IDs: extract the family name (e.g., `claude-opus-4-6` → `opus`) and use the same tier ordering. Unknown families should default to the highest tier so they're never accidentally capped.
+- The ceiling concept also applies to the explicit `model` frontmatter field — a plan cannot exceed the user's configured budget. This is intentional: the user always has final say on cost.

package/RAF/ahwidh-quick-fix-gremlin/decisions.md

@@ -0,0 +1,37 @@
+# Project Decisions
+
+## For `raf config --get/--set`: Should `--get` with no key show the full merged config (defaults + overrides), or only user overrides from the config file?
+Full merged config — Shows the complete resolved config with all defaults filled in, so users see every active setting.
+
+## For `raf config --set`: Should setting a value to its default automatically remove it from the config file (keeping config minimal), or always write explicitly?
+Remove if default — If the value matches the default, remove the key from the config file to keep it clean.
+
+## For the diverged main branch fix: Should callers treat this as a hard error or a warning?
+Warning only — Show a visible warning (yellow) but continue execution. Stale base is better than blocking work.
+
+## For the name generation fix: Should the fix tighten the prompt, add response parsing, or both?
+Prompt only — Just improve the prompt instructions to be more explicit about output format.
+
+## For `raf config --get models.plan`: Should the output be plain value only or formatted?
+Plain value — Just print 'opus'. Easy to pipe into other commands.
+
+## For the token investigation task: Research only or plan fix now?
+Research now and create task if needed — investigated and found it's a display issue: `input_tokens` from Claude API only reports non-cached tokens. Fix plan created as task 07 to show total input in display.
+
+## Token investigation findings
+Root cause: Claude API separates `input_tokens` (non-cached, e.g. 3-22) from `cache_read_input_tokens` (e.g. 18,000+) and `cache_creation_input_tokens` (e.g. 6,000+). RAF displays only non-cached as "X in". Fix: sum all three for the display. Cost calculation is already correct.
+
+## For amend commit fix: Should plan files be removed from the commit or committed separately?
+Remove from commit — Only commit input.md and decisions.md during planning. Plan files get committed by Claude during execution.
+
+## For syncing worktree branch with main before execution: Rebase or merge?
+Rebase onto main — Cleaner history, replays worktree commits on top of latest main.
+
+## If the rebase has conflicts, should `raf do` abort or skip sync?
+Skip sync and warn — Skip the sync step, show a warning, and continue execution on the current branch state.
+
+## For removing token report from plan: Should `session-parser.ts` and its tests be deleted or kept?
+Delete session-parser entirely — Remove session-parser.ts and its test file since they have no other consumers.
+
+## Should the `sessionId` parameter be removed from `runInteractive()` in claude-runner.ts?
+Remove sessionId from runInteractive() too — Clean up the runner API as well since no other callers pass sessionId.