rafcode 2.3.0 → 2.4.1-0

package/RAF/ahwidh-quick-fix-gremlin/plans/02-fix-amend-commit-scope.md

@@ -0,0 +1,48 @@
+effort: low
+---
+# Task: Fix amend mode commit to exclude plan files
+
+## Objective
+Change the amend commit to only include `input.md` and `decisions.md`, not the new plan files.
+
+## Context
+In `raf plan --amend`, the commit includes new plan files alongside `input.md` and `decisions.md`. Plan files should be committed by Claude during task execution instead, matching how initial planning only commits `input.md` and `decisions.md`.
+
+## Requirements
+- Remove `additionalFiles: newPlanPaths` from the amend commit call
+- Keep the `isAmend: true` flag (commit message should still use "Amend:" prefix)
+- Initial planning commit behavior must remain unchanged
+
+## Implementation Steps
+
+1. **Edit `src/commands/plan.ts`** at lines 650-656. Change:
+   ```typescript
+   // Commit planning artifacts (input.md, decisions.md, and new plan files)
+   const newPlanPaths = newPlanFiles.map(f => path.join(plansDir, f));
+   await commitPlanningArtifacts(projectPath, {
+     cwd: worktreePath ?? undefined,
+     additionalFiles: newPlanPaths,
+     isAmend: true,
+   });
+   ```
+   To:
+   ```typescript
+   // Commit planning artifacts (input.md, decisions.md only — plan files committed during execution)
+   await commitPlanningArtifacts(projectPath, {
+     cwd: worktreePath ?? undefined,
+     isAmend: true,
+   });
+   ```
+   Remove the `newPlanPaths` variable as well since it's no longer used.
+
+2. **Update tests** — Check `tests/unit/commit-planning-artifacts.test.ts` and `tests/unit/commit-planning-artifacts-worktree.test.ts` for any amend-specific tests that assert plan files are committed. Update them to verify plan files are NOT included.
+
+## Acceptance Criteria
+- [ ] Amend commit only stages `input.md` and `decisions.md`
+- [ ] `additionalFiles` is not passed in the amend code path
+- [ ] Initial planning commit behavior unchanged
+- [ ] Existing tests updated and passing
+
+## Notes
+- The `commitPlanningArtifacts` function itself doesn't need changes — just stop passing `additionalFiles` from the amend caller
+- The `additionalFiles` parameter on `commitPlanningArtifacts` can remain in the interface for future use

package/RAF/ahwidh-quick-fix-gremlin/plans/03-fix-diverged-main-branch-sync.md

@@ -0,0 +1,49 @@
+effort: low
+---
+# Task: Fix diverged main branch sync to report failure
+
+## Objective
+Change `pullMainBranch()` to return `success: false` when the local main branch has diverged from remote, so callers surface the issue as a warning.
+
+## Context
+PR #5 review comment: When `git fetch origin main:main` fails because local main has diverged, the code falls back to `git fetch origin main` and returns `success: true` with an `error` message. Callers only check `success === false` to warn, so the divergence is silently ignored. Worktree/PR flows then proceed on stale base refs.
+
+The fix: return `success: false` so callers show the warning. Per user decision, this should be a visible warning that lets execution continue (not a hard error).
+
+## Requirements
+- Change `success: true` to `success: false` in the diverged branch path
+- Callers already handle `success: false` with `logger.warn()` — no caller changes needed
+- The plain `git fetch origin main` should still run (we still want the remote ref updated)
+
+## Implementation Steps
+
+1. **Edit `src/core/worktree.ts`** at lines 533-538. Change:
+   ```typescript
+   return {
+     success: true,
+     mainBranch,
+     hadChanges: false,
+     error: `Local ${mainBranch} has diverged from origin, not updated`,
+   };
+   ```
+   To:
+   ```typescript
+   return {
+     success: false,
+     mainBranch,
+     hadChanges: false,
+     error: `Local ${mainBranch} has diverged from origin, not updated`,
+   };
+   ```
+
+2. **Update tests** — Find tests for `pullMainBranch` (likely in `tests/unit/worktree.test.ts`) and update the diverged branch test case to assert `success: false`.
+
+## Acceptance Criteria
+- [ ] Diverged branch path returns `success: false`
+- [ ] Callers show a warning via `logger.warn()` (already happens for `success: false`)
+- [ ] Execution continues after the warning (callers don't abort on sync failure)
+- [ ] Tests updated and passing
+
+## Notes
+- The second `git fetch origin main` (plain fetch) still runs successfully — it updates `origin/main` remote ref even though local `main` isn't updated. This is fine.
+- Callers in `do.ts` (line 243-250) and `plan.ts` already have the pattern: `if (!syncResult.success) { logger.warn(...) }` — no changes needed there.

package/RAF/ahwidh-quick-fix-gremlin/plans/04-wire-rate-limit-to-do-command.md

@@ -0,0 +1,78 @@
+effort: low
+---
+# Task: Wire rate-limit estimate display config to do command
+
+## Objective
+Pass the `display` config settings (`showRateLimitEstimate`, `showCacheTokens`) through to `formatTaskTokenSummary()` and `formatTokenTotalSummary()` calls in the do command.
+
+## Context
+PR #5 review comment: The formatter defaults `showRateLimitEstimate` to `false` in its destructuring, but `raf do` calls both formatters without passing `TokenSummaryOptions`. Despite `display.showRateLimitEstimate` defaulting to `true` in config, the feature is effectively dead code.
+
+## Requirements
+- Read display config settings and pass them as `TokenSummaryOptions` to both formatters
+- Calculate and pass `rateLimitPercentage` from `TokenTracker`
+- Per-task summaries should show cumulative rate limit percentage
+- Grand total summary should show the final cumulative percentage
+
+## Implementation Steps
+
+1. **Edit `src/commands/do.ts`** — Build `TokenSummaryOptions` from config and pass to formatters.
+
+   Near the top of `runDoCommand()` (after tokenTracker is created), import and read display config:
+   ```typescript
+   import { getShowRateLimitEstimate, getShowCacheTokens } from '../utils/config.js';
+   ```
+
+2. **Update per-task token display** (lines 1218-1220 and 1246-1248). Change both locations from:
+   ```typescript
+   logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u)));
+   ```
+   To:
+   ```typescript
+   const taskRateLimitPct = tokenTracker.getCumulativeRateLimitPercentage();
+   logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u), {
+     showCacheTokens: getShowCacheTokens(),
+     showRateLimitEstimate: getShowRateLimitEstimate(),
+     rateLimitPercentage: taskRateLimitPct,
+   }));
+   ```
+
+3. **Update grand total display** (lines 1360-1361). Change from:
+   ```typescript
+   logger.dim(formatTokenTotalSummary(totals.usage, totals.cost));
+   ```
+   To:
+   ```typescript
+   const totalRateLimitPct = tokenTracker.getCumulativeRateLimitPercentage();
+   logger.dim(formatTokenTotalSummary(totals.usage, totals.cost, {
+     showCacheTokens: getShowCacheTokens(),
+     showRateLimitEstimate: getShowRateLimitEstimate(),
+     rateLimitPercentage: totalRateLimitPct,
+   }));
+   ```
+
+4. **Update the default value** in `formatTokenTotalSummary` (line 258 of `terminal-symbols.ts`). Change:
+   ```typescript
+   const { showCacheTokens = true, showRateLimitEstimate = false, rateLimitPercentage } = options;
+   ```
+   To:
+   ```typescript
+   const { showCacheTokens = true, showRateLimitEstimate = true, rateLimitPercentage } = options;
+   ```
+   This makes the default behavior match the config default (`display.showRateLimitEstimate: true`), so any callers that don't pass options still get the feature.
+
+   Also update `formatTokenLine` if it has a similar default for `showRateLimitEstimate`.
+
+5. **Update tests** — Adjust any test expectations that rely on `showRateLimitEstimate` defaulting to `false`.
+
+## Acceptance Criteria
+- [ ] Per-task token summaries show rate limit percentage when `display.showRateLimitEstimate` is `true`
+- [ ] Grand total summary shows rate limit percentage
+- [ ] Setting `display.showRateLimitEstimate: false` in config suppresses the display
+- [ ] `display.showCacheTokens` config is also wired through
+- [ ] Tests pass
+
+## Notes
+- The `TokenTracker.getCumulativeRateLimitPercentage()` method already exists and works correctly
+- The `getShowRateLimitEstimate()` and `getShowCacheTokens()` config helpers already exist in `src/utils/config.ts`
+- All the pieces are in place — this task just wires them together

package/RAF/ahwidh-quick-fix-gremlin/plans/05-add-config-get-set-flags.md

@@ -0,0 +1,101 @@
+effort: medium
+---
+# Task: Add --get and --set flags to raf config
+
+## Objective
+Add `raf config --get [key]` and `raf config --set <key> <value>` for quick config viewing/editing without launching the interactive Claude wizard.
+
+## Context
+Currently `raf config` always launches an interactive Claude session (Sonnet). For quick operations like checking a single value or changing a model, this is slow and expensive. The `--get` and `--set` flags provide instant, non-interactive alternatives.
+
+## Requirements
+- `raf config --get` (no key): Print full merged config as JSON (defaults + overrides)
+- `raf config --get models.plan`: Print plain value (e.g., `opus`) — no key prefix, no quotes for strings
+- `raf config --set models.plan sonnet`: Set a leaf-level config value
+- Only support leaf-level keys (dot-notation like `models.plan`, `timeout`, `display.showRateLimitEstimate`)
+- Do NOT support setting entire nested objects (e.g., `--set models '{...}'`)
+- If `--get` or `--set` is present, do NOT launch the interactive wizard
+- If value matches default after `--set`, remove the key from config file (keep config minimal)
+- If removing the last key from a section empties it, remove the section too
+- Validate the value before saving (use existing validation)
+- `--set` and `--get` are mutually exclusive; show error if both provided
+- `--reset` takes precedence / is mutually exclusive with `--get`/`--set`
+
+## Implementation Steps
+
+1. **Edit `src/commands/config.ts`** — Add new options to the command:
+   ```typescript
+   .option('--get [key]', 'Show config value (all config if no key, or specific dot-notation key)')
+   .option('--set <key> <value>', 'Set a config value using dot-notation key')
+   ```
+   Note: Commander.js handles `--set key value` with two arguments. You may need to use `.option('--set <key_value...>')` or handle it as a positional pair. Consider using a variadic option that takes exactly 2 values.
+
+2. **Update the `ConfigCommandOptions` interface**:
+   ```typescript
+   interface ConfigCommandOptions {
+     reset?: boolean;
+     get?: true | string;  // true when --get with no key, string when --get <key>
+     set?: string[];       // [key, value]
+   }
+   ```
+
+3. **Update the action handler** to check for `--get`/`--set` before launching the wizard:
+   ```typescript
+   if (options.reset) { await handleReset(); return; }
+   if (options.get !== undefined) { handleGet(options.get); return; }
+   if (options.set) { handleSet(options.set); return; }
+   // ... existing wizard launch
+   ```
+
+4. **Implement `handleGet(key?: string | true)`**:
+   - If `key` is `true` (no argument): Print `JSON.stringify(resolveConfig(), null, 2)`
+   - If `key` is a string: Use dot-notation to traverse the resolved config object
+   - Print the value: strings plain, numbers/booleans as-is, objects as JSON
+   - If key not found, print error and exit with code 1
+
+5. **Implement `handleSet(args: string[])`**:
+   - Parse `args` as `[key, value]`
+   - Read the current user config file (or start with `{}`)
+   - Parse the value: try `JSON.parse(value)` first (for numbers, booleans), fall back to string
+   - Use dot-notation to set the leaf value in the user config object
+   - Check if the value matches the default at that path — if so, remove the key instead
+   - If removing leaves an empty parent object, remove the parent too
+   - Validate the resulting config with `validateConfig()`
+   - Save with `saveConfig()`
+   - If config becomes empty `{}`, delete the file entirely
+   - Print confirmation message
+
+6. **Add helper functions**:
+   - `getNestedValue(obj, dotPath)` — traverse an object by dot-notation path
+   - `setNestedValue(obj, dotPath, value)` — set a leaf value by dot-notation path
+   - `deleteNestedValue(obj, dotPath)` — remove a leaf and clean up empty parents
+   - `getDefaultValue(dotPath)` — get the default value at a dot-notation path from `DEFAULT_CONFIG`
+
+7. **Add tests** in `tests/unit/config-command.test.ts` (or update existing):
+   - `--get` with no key returns full config JSON
+   - `--get models.plan` returns just the value
+   - `--get nonexistent.key` exits with error
+   - `--set models.plan sonnet` updates the config file
+   - `--set timeout 120` parses as number
+   - `--set autoCommit false` parses as boolean
+   - `--set models.plan opus` (default value) removes the key from file
+   - Setting last key in section removes the section
+   - Validation errors are reported
+
+## Acceptance Criteria
+- [ ] `raf config --get` prints full merged config as formatted JSON
+- [ ] `raf config --get models.plan` prints plain value (e.g., `opus`)
+- [ ] `raf config --set models.plan sonnet` updates config file
+- [ ] Setting value to default removes it from config file
+- [ ] Empty sections cleaned up after removal
+- [ ] Value parsing handles strings, numbers, and booleans
+- [ ] Invalid keys/values show clear error messages
+- [ ] Interactive wizard NOT launched when --get or --set is present
+- [ ] Tests pass
+
+## Notes
+- The `resolveConfig()` function already merges defaults + overrides, perfect for `--get`
+- The `saveConfig()` function already handles file creation and formatting
+- The `validateConfig()` function validates the entire user config, so validate after modification
+- For `--get`, use the resolved (merged) config; for `--set`, read/write only the user config file
+- Commander.js variadic options: `--set <key> <value>` can be done with `.option('--set <items...>')` which collects remaining args

package/RAF/ahwidh-quick-fix-gremlin/plans/06-sync-worktree-branch-before-execution.md

@@ -0,0 +1,92 @@
+effort: medium
+---
+# Task: Sync worktree branch with main before execution
+
+## Objective
+Before executing tasks in a worktree, rebase the worktree branch onto the latest main branch to ensure it's up-to-date.
+
+## Dependencies
+03
+
+## Context
+When using `raf do` in worktree mode, the worktree branch may be behind main (e.g., if other worktree projects were merged into main since this branch was created). Rebasing before execution ensures the branch starts from the latest main, reducing merge conflicts later.
+
+## Requirements
+- After `pullMainBranch()` syncs main, rebase the worktree branch onto main
+- Only do this in worktree mode in `raf do`
+- If rebase has conflicts: abort the rebase, show a warning, and continue execution without sync
+- The rebase should happen after worktree project selection but before task execution begins
+- Respect the `syncMainBranch` config setting — skip if disabled
+
+## Implementation Steps
+
+1. **Add a `rebaseOntoMain` function to `src/core/worktree.ts`**:
+   ```typescript
+   export interface RebaseResult {
+     success: boolean;
+     error?: string;
+   }
+
+   export function rebaseOntoMain(mainBranch: string, cwd: string): RebaseResult {
+     try {
+       execSync(`git rebase ${mainBranch}`, {
+         encoding: 'utf-8',
+         stdio: 'pipe',
+         cwd,
+       });
+       return { success: true };
+     } catch (error) {
+       // Abort the failed rebase to restore clean state
+       try {
+         execSync('git rebase --abort', {
+           encoding: 'utf-8',
+           stdio: 'pipe',
+           cwd,
+         });
+       } catch {
+         // Ignore abort errors
+       }
+       const msg = error instanceof Error ? error.message : String(error);
+       return { success: false, error: msg };
+     }
+   }
+   ```
+
+2. **Edit `src/commands/do.ts`** — Add the rebase step after `pullMainBranch()` in the worktree mode section (after line 251, before task execution). The rebase should run inside the worktree directory:
+   ```typescript
+   // After pullMainBranch sync and worktree project selection...
+   // Rebase worktree branch onto main before execution
+   if (getSyncMainBranch() && worktreeCwd) {
+     const mainBranch = syncResult?.mainBranch ?? detectMainBranch();
+     if (mainBranch) {
+       const rebaseResult = rebaseOntoMain(mainBranch, worktreeCwd);
+       if (rebaseResult.success) {
+         logger.info(`Rebased onto ${mainBranch}`);
+       } else {
+         logger.warn(`Could not rebase onto ${mainBranch}: ${rebaseResult.error}`);
+         logger.warn('Continuing with current branch state.');
+       }
+     }
+   }
+   ```
+   Note: The exact placement depends on where `worktreeCwd` is set. Find the right location — it should be after the worktree is validated/created and `worktreeCwd` is determined, but before the task execution loop begins.
+
+3. **Determine the main branch name** — The `pullMainBranch()` result includes `mainBranch`. Store it so it can be used for the rebase. If `pullMainBranch()` wasn't called (syncMainBranch disabled), you can detect main branch with the existing `detectMainBranch()` utility from `worktree.ts`.
+
+4. **Add tests** for the new `rebaseOntoMain` function:
+   - Successful rebase
+   - Rebase with conflicts → aborts and returns failure
+   - Verify `git rebase --abort` is called on failure
+
+## Acceptance Criteria
+- [ ] Worktree branch is rebased onto main before task execution
+- [ ] Conflicts cause rebase abort + warning, execution continues
+- [ ] Rebase only happens in worktree mode
+- [ ] Respects `syncMainBranch` config setting
+- [ ] Main branch name correctly determined from sync result or detection
+- [ ] Tests pass
+
+## Notes
+- The rebase should use the local main branch ref (which was just synced by `pullMainBranch`)
+- If `pullMainBranch` failed (e.g., diverged — now returns `success: false` after task 03), the rebase should still attempt using whatever local main is available
+- This runs in the worktree directory (`cwd`), not the main repo

package/RAF/ahwidh-quick-fix-gremlin/plans/07-update-frontmatter-format.md

@@ -0,0 +1,105 @@
+---
+effort: medium
+---
+# Task: Update plan frontmatter to standard Obsidian format
+
+## Objective
+Change the plan file frontmatter format from closing-delimiter-only to standard Obsidian/YAML frontmatter with both opening and closing `---` delimiters.
+
+## Context
+Currently plan files use a non-standard format with only a closing `---`:
+```
+effort: medium
+---
+# Task: ...
+```
+
+Standard Obsidian (and Jekyll/Hugo/etc.) frontmatter uses `---` on both top and bottom:
+```
+---
+effort: medium
+---
+# Task: ...
+```
+
+This change aligns RAF with the widely-used standard format, improving compatibility with Obsidian and other markdown tools.
+
+## Requirements
+- Update the frontmatter parser to support the standard `---`/`---` format
+- Also keep backward compatibility with the old closing-only format (existing plan files should still parse)
+- Update all prompts that instruct Claude to generate frontmatter
+- Update CLAUDE.md documentation
+- Update existing plan files in this project to use the new format (if any are being generated)
+
+## Implementation Steps
+
+1. **Edit `src/utils/frontmatter.ts`** — Update `parsePlanFrontmatter()` to handle both formats:
+   - Check if content starts with `---` (after optional leading whitespace/newline)
+   - If it does: standard format — find the closing `---` after it, extract content between the two delimiters
+   - If it doesn't: legacy format — find the first `---` and treat everything before it as frontmatter (current behavior)
+
+   Updated parsing logic:
+   ```typescript
+   export function parsePlanFrontmatter(content: string): FrontmatterParseResult {
+     const result: FrontmatterParseResult = { frontmatter: {}, hasFrontmatter: false, warnings: [] };
+     const trimmedContent = content.trimStart();
+
+     let frontmatterSection: string;
+
+     if (trimmedContent.startsWith('---')) {
+       // Standard format: ---\nkey: value\n---
+       const afterOpener = trimmedContent.substring(3);
+       // Skip the rest of the opener line (handles "---\n" or "--- \n")
+       const openerEnd = afterOpener.indexOf('\n');
+       if (openerEnd === -1) return result;
+       const rest = afterOpener.substring(openerEnd + 1);
+       const closerIndex = rest.indexOf('---');
+       if (closerIndex === -1) return result;
+       frontmatterSection = rest.substring(0, closerIndex);
+     } else {
+       // Legacy format: key: value\n---
+       const delimiterIndex = content.indexOf('---');
+       if (delimiterIndex === -1) return result;
+       frontmatterSection = content.substring(0, delimiterIndex);
+     }
+
+     // ... rest of key: value parsing remains the same
+   }
+   ```
+
+2. **Update prompts** — Edit these files to show the new format with opening `---`:
+   - `src/prompts/planning.ts` — Update the frontmatter example/instructions
+   - `src/prompts/amend.ts` — Same update
+   - Search for any other prompts that reference frontmatter format
+
+3. **Update CLAUDE.md** — Change the plan file format documentation from:
+   ```
+   effort: medium
+   ---
+   ```
+   To:
+   ```
+   ---
+   effort: medium
+   ---
+   ```
+
+4. **Update tests** in `tests/unit/frontmatter.test.ts`:
+   - Add tests for the new standard format (opening + closing `---`)
+   - Keep tests for legacy format (closing only) to verify backward compatibility
+   - Test edge cases: extra whitespace before opening `---`, empty frontmatter block (`---\n---`)
+
+5. **Update this project's planning prompt** — The system prompt at the top of this conversation also references the frontmatter format. This is injected by RAF, so updating the prompts in step 2 covers future projects.
+
+## Acceptance Criteria
+- [ ] Parser handles standard `---`/`---` format correctly
+- [ ] Parser still handles legacy closing-only format (backward compatibility)
+- [ ] Planning prompts generate the new standard format
+- [ ] CLAUDE.md documentation updated
+- [ ] Tests cover both old and new formats
+- [ ] All existing tests pass
+
+## Notes
+- Backward compatibility is important since existing projects have plan files in the old format
+- The parser should be robust: handle `---` with trailing spaces, `---` with trailing content on the same line, etc.
+- Obsidian treats `---` at the very start of a file as YAML frontmatter — this is the standard we're adopting

package/RAF/ahwidh-quick-fix-gremlin/plans/08-remove-plan-token-report.md

@@ -0,0 +1,50 @@
+effort: low
+---
+# Task: Remove Token Report from Plan Command
+
+## Objective
+Remove all token usage reporting from `raf plan` and `raf plan --amend`, including the session-parser module that only exists to support this feature.
+
+## Context
+The token report shown after planning sessions is not useful — planning is an interactive session where token cost is less relevant than during automated task execution. Removing it simplifies the plan command and eliminates dead code.
+
+## Requirements
+- Remove token reporting from both `runPlanCommand()` and `runAmendCommand()` in `src/commands/plan.ts`
+- Delete the `displayPlanSessionTokenSummary()` function entirely
+- Delete `src/utils/session-parser.ts` (only consumer is the plan command)
+- Delete `tests/unit/session-parser.test.ts`
+- Remove the `sessionId` parameter from `claudeRunner.runInteractive()` in `src/core/claude-runner.ts` (no other callers use it)
+- Clean up all unused imports in affected files
+
+## Implementation Steps
+
+1. **Edit `src/commands/plan.ts`:**
+   - Remove imports: `TokenTracker`, `formatTokenTotalSummary`, `TokenSummaryOptions`, `parseSessionById`, `crypto`
+   - Remove `getDisplayConfig` and `getPricingConfig` from the config import (if not used elsewhere in the file)
+   - In `runPlanCommand()`: remove `sessionId` generation, `sessionCwd` variable, remove `sessionId` from `claudeRunner.runInteractive()` options, remove `displayPlanSessionTokenSummary()` call
+   - In `runAmendCommand()`: same removals as above
+   - Delete the entire `displayPlanSessionTokenSummary()` function (around lines 702-741)
+
+2. **Edit `src/core/claude-runner.ts`:**
+   - Remove `sessionId` from the `runInteractive()` method's options interface/parameter
+   - Remove any internal usage of `sessionId` (e.g., passing `--session-id` flag to Claude CLI)
+
+3. **Delete files:**
+   - `src/utils/session-parser.ts`
+   - `tests/unit/session-parser.test.ts`
+
+4. **Verify:** Run `npm run build` and `npm test` to ensure no broken imports or failing tests
+
+## Acceptance Criteria
+- [ ] `raf plan` no longer displays a token usage summary after the planning session
+- [ ] `raf plan --amend` no longer displays a token usage summary after the amendment session
+- [ ] `src/utils/session-parser.ts` is deleted
+- [ ] `tests/unit/session-parser.test.ts` is deleted
+- [ ] `sessionId` parameter removed from `runInteractive()` API
+- [ ] No unused imports remain in modified files
+- [ ] Build passes (`npm run build`)
+- [ ] Tests pass (`npm test`)
+
+## Notes
+- The `TokenTracker`, `formatTokenTotalSummary`, and `formatTaskTokenSummary` utilities in `token-tracker.ts` and `terminal-symbols.ts` are still used by `raf do` — do NOT delete those modules
+- The `display` and `pricing` config sections remain valid for `raf do` usage — do NOT remove them from config types/defaults

package/README.md

@@ -76,7 +76,7 @@ raf do                # Interactive picker
 raf do abcdef         # Execute by project ID
 raf do my-project     # Execute by name
 raf do --worktree     # Pick and execute a worktree project
-raf do my-feature -w --merge  # Execute in worktree, merge on success
+raf do my-feature -w  # Execute in worktree (picker will ask what to do after)
 ```
 
 Note: In non-verbose mode, the completion summary reflects the tasks executed in that run (the remaining tasks at start), so the elapsed time maps to those tasks.
@@ -163,18 +163,39 @@ Worktree mode runs planning and execution in an isolated git worktree, keeping y
 # Plan in a worktree (creates branch and worktree directory)
 raf plan my-feature --worktree
 
-# Execute tasks in the worktree, merge back on success
-raf do my-feature --worktree --merge
+# Execute tasks in the worktree
+raf do my-feature --worktree
 ```
 
+### Post-execution picker
+
+When running `raf do` in worktree mode, an interactive picker appears **before** task execution asking what to do after tasks complete:
+
+- **Merge into current branch** — Merge the worktree branch back (fast-forward preferred, merge commit fallback)
+- **Create a GitHub PR** — Push the branch and create a pull request (requires `gh` CLI)
+- **Leave branch as-is** — Do nothing, keep the branch for later
+
+The chosen action only runs if all tasks succeed. On task failure, the action is skipped and the worktree is kept for inspection.
+
+### PR creation
+
+The "Create a GitHub PR" option:
+
+- Requires `gh` CLI installed and authenticated (`gh auth login`)
+- Auto-detects the base branch from `origin/HEAD`
+- Generates a PR title from the project name
+- Uses Claude to summarize your input, decisions, and outcomes into a PR body
+- Auto-pushes the branch to origin if needed
+
+If `gh` is missing or unauthenticated, the option falls back to "Leave branch" with a warning.
+
 ### How it works
 
 - `--worktree` creates a git worktree at `~/.raf/worktrees/<repo>/<project>/` with a new branch named after the project folder (e.g., `abcdef-my-feature`)
 - All planning artifacts, code changes, and commits happen in the worktree branch
-- `--merge` on `raf do` merges the branch back after all tasks succeed (fast-forward preferred, merge commit as fallback)
+- After successful post-actions (merge, PR, or leave), the worktree directory is cleaned up automatically — the git branch is preserved
 - On merge conflicts, the merge is aborted and you get instructions for manual resolution
-- If tasks fail, the worktree branch is preserved for inspection
-- Worktrees persist after completion — clean them up manually with `git worktree remove` when done
+- If tasks fail, the worktree is kept for inspection
 
 ## Command Reference
 
@@ -196,7 +217,6 @@ raf do my-feature --worktree --merge
 | `-m, --model <name>` | Claude model (sonnet, haiku, opus) |
 | `--sonnet` | Shorthand for `--model sonnet` |
 | `-w, --worktree` | Execute tasks in a git worktree |
-| `--merge` | Merge worktree branch after successful completion (requires `--worktree`) |
 
 Alias: `raf act`
 

package/dist/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiHpC,wBAAgB,mBAAmB,IAAI,OAAO,CAgB7C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4UpC,wBAAgB,mBAAmB,IAAI,OAAO,CAsC7C"}