rafcode 1.2.0 → 2.0.0

package/RAF/aaaacu-worktree-weaver/plans/04-auto-merge-and-cleanup.md

@@ -0,0 +1,51 @@
+# Task: Auto-merge on Project Completion
+
+## Objective
+When `--merge` flag is present on `raf do --worktree`, automatically merge the project branch into the original branch after all tasks complete successfully.
+
+## Context
+After worktree execution completes, the user may want to merge the project branch back into the branch from which `raf` was originally called. This is controlled by the `--merge` flag (only valid with `--worktree`). The worktree itself is NOT cleaned up or removed after merge — it stays in place.
+
+## Dependencies
+003
+
+## Requirements
+- Add `--merge` boolean flag to the do command in Commander.js
+- `--merge` is only valid when `--worktree` is also present — error if `--merge` is used without `--worktree`
+- After all tasks complete (project state is "completed") and `--merge` is set, attempt auto-merge:
+  1. Switch back to the original branch (the branch that was active when `raf do --worktree` was invoked)
+  2. Attempt merge using the merge utility from task 001 (tries ff first, falls back to merge-commit)
+  3. On success: log success message with merge details
+  4. On conflict: `git merge --abort` is called by the utility, log a warning with the branch name so the user can merge manually
+- Record the original branch name at the start of `raf do --worktree` execution (before switching to worktree)
+- The merge must happen from the ORIGINAL repo's working directory, not from inside the worktree
+- If the project is NOT fully completed (has failures), skip the merge entirely — just show a message about the worktree branch
+- The merge should also work for partially completed projects that were continued with `--force` and are now fully complete
+- Do NOT remove or clean up the worktree after merge — the worktree stays in place
+
+## Implementation Steps
+1. Add `--merge` option to the Commander command definition in `src/commands/do.ts`
+2. Validate that `--merge` is only used with `--worktree`, error otherwise
+3. In the `do` command's worktree flow, record the current branch name before execution starts
+4. After the task execution loop completes, check if `--merge` is set and the project is fully completed
+5. If completed with `--merge`: call the merge utility from task 001 (passing original branch, project branch, and paths)
+6. Handle merge result: success -> log success, conflict -> log warning with manual merge instructions
+7. If project has failures: just note that the worktree branch is available for inspection
+8. No worktree cleanup or removal after merge
+
+## Acceptance Criteria
+- [ ] `--merge` flag is added to the do command
+- [ ] `--merge` without `--worktree` shows an error
+- [ ] On full project completion with `--merge`, merge is attempted
+- [ ] Successful merge logs a clear success message
+- [ ] Merge conflicts trigger `git merge --abort` and show warning with branch name and manual merge instructions
+- [ ] Incomplete projects (failures) skip merge and mention the branch
+- [ ] Original branch is correctly recorded and restored
+- [ ] Worktree is NOT removed or cleaned up after merge
+- [ ] Without `--merge`, no merge is attempted even if project completes
+
+## Notes
+- The merge happens in the original repo directory, not the worktree — this is important because `git merge` needs to be on the target branch
+- The current branch at invocation time should be captured early (before any worktree operations change context)
+- Consider the case where the user's original branch has moved forward (other commits) while the worktree was being worked on — if ff fails, a merge-commit is created; only conflicts cause failure
+- Reference the worktree utility functions from task 001 for merge operations

package/RAF/aaaacu-worktree-weaver/plans/05-worktree-tests.md

@@ -0,0 +1,52 @@
+# Task: Add Tests for Worktree Functionality
+
+## Objective
+Add comprehensive tests covering the worktree utilities and the integration of `--worktree` and `--merge` flags into plan and do commands.
+
+## Context
+RAF uses Jest with ts-jest ESM preset. Existing tests are in `__tests__/` directories. The worktree functionality involves git operations that need careful testing with real temporary git repos.
+
+## Dependencies
+001, 002, 003, 004
+
+## Requirements
+- Unit tests for all worktree utility functions in `src/core/worktree.ts`:
+  - Path computation (given repo name and project folder, verify correct worktree path)
+  - Worktree creation (use a temporary git repo)
+  - Worktree validation (existing vs non-existing)
+  - Merge (fast-forward success, merge-commit fallback, and conflict/abort cases)
+  - Removal (for failed-plan cleanup scenario only)
+- Integration-level tests for command behavior:
+  - `raf do --worktree` with multiple projects should error
+  - `raf do --worktree` with no worktree should error with helpful message
+  - `raf do --merge` without `--worktree` should error
+- Test edge cases:
+  - Worktree path computation when repo has special characters in name
+  - Merge when original branch has diverged (merge-commit should be created)
+  - Merge with conflicts (should abort and return failure)
+- Use temporary directories and real git repos for git operation tests (create temp dir, `git init`, add commits, etc.)
+- Follow existing test patterns in the project
+
+## Implementation Steps
+1. Create `src/core/__tests__/worktree.test.ts` for unit tests of utility functions
+2. Write tests for path computation (pure function, no git needed)
+3. Write tests for worktree creation/validation/merge/removal using temporary git repos
+4. Create test helpers for setting up temporary git repos with commits
+5. Write tests for CLI validation (--worktree and --merge flag behavior)
+6. Ensure all tests clean up their temporary directories
+
+## Acceptance Criteria
+- [ ] All worktree utility functions have unit tests
+- [ ] Path computation tested with various repo and project names
+- [ ] Worktree creation tested with real temporary git repo
+- [ ] Merge tested for ff success, merge-commit fallback, and conflict/abort
+- [ ] Removal tested for failed-plan cleanup scenario
+- [ ] CLI validation tests for error cases (--merge without --worktree, etc.)
+- [ ] All tests pass with `npm test`
+- [ ] Tests clean up temporary files/directories
+
+## Notes
+- Creating temporary git repos for testing: use `fs.mkdtempSync` + `execSync('git init')` + add a commit
+- For worktree tests, the base repo needs at least one commit before `git worktree add` will work
+- Be careful with `process.cwd()` in tests - some utilities may depend on it. Consider mocking or using `chdir` carefully
+- Reference existing test files in the project for patterns and conventions

package/RAF/aaaacu-worktree-weaver/plans/06-update-documentation.md

@@ -0,0 +1,55 @@
+# Task: Update Documentation for Worktree Support
+
+## Objective
+Document the `--worktree` and `--merge` flags and worktree workflow in both CLAUDE.md (internal developer docs) and README.md (user-facing docs).
+
+## Context
+The worktree feature adds a new workflow to RAF. Users need to know how to use it, and developers maintaining RAF need to understand the architecture. Both docs files need updates.
+
+## Dependencies
+002, 003, 004
+
+## Requirements
+
+### README.md updates:
+- Add `--worktree` to the Features section (brief mention of isolated branch execution)
+- Add worktree usage examples to the Commands section for both `raf plan` and `raf do`
+- Add `--worktree` and `--merge` rows to the Command Reference tables for both plan and do
+- Add a new "Worktree Mode" section (after the existing "Project Structure" section) explaining:
+  - What worktree mode does and why you'd use it (isolated branch for parallel work)
+  - The basic workflow: `raf plan my-feature --worktree` -> `raf do my-feature --worktree --merge`
+  - Where worktree directories are created (`~/.raf/worktrees/<repo>/<project>`)
+  - Merge behavior with `--merge` flag (ff preferred, merge-commit fallback, conflict abort)
+  - What happens on failure (branch preserved, user can merge manually)
+  - Worktrees persist after completion — no automatic cleanup
+
+### CLAUDE.md updates:
+- Add a new "Worktree Mode" subsection under "Architectural Decisions" explaining:
+  - Worktree path convention: `~/.raf/worktrees/<repo-basename>/<project-id>`
+  - Branch naming: full project folder name (e.g., `020-my-feature`)
+  - How worktree mode detection works (--worktree flag required on both plan and do)
+  - The lifecycle: create worktree -> plan in worktree -> execute in worktree -> optionally merge with `--merge`
+  - Merge strategy: ff preferred, merge-commit fallback, abort on conflicts
+  - Worktrees are NOT cleaned up after completion or merge
+  - Single project limitation (no multi-project with --worktree)
+  - `--merge` only valid with `--worktree`
+- Add `--worktree` and `--merge` to the plan and do command descriptions if they exist in CLAUDE.md
+
+## Implementation Steps
+1. Read both README.md and CLAUDE.md to understand current structure
+2. Add worktree content to README.md in the appropriate sections
+3. Add worktree architectural decision to CLAUDE.md
+4. Ensure the documentation is consistent with the actual implementation
+
+## Acceptance Criteria
+- [ ] README.md has `--worktree` and `--merge` in Features, Commands, and Command Reference
+- [ ] README.md has a "Worktree Mode" section with workflow explanation
+- [ ] CLAUDE.md has a "Worktree Mode" architectural decision section
+- [ ] Documentation mentions that worktrees persist (no auto-cleanup)
+- [ ] Documentation matches the implemented behavior
+- [ ] No existing documentation is broken or contradicted
+
+## Notes
+- Keep documentation concise - match the existing style of both files
+- Focus on the user workflow in README.md and the technical architecture in CLAUDE.md
+- The worktree path example should use concrete values so it's easy to understand

package/RAF/aaaacv-trim-the-fat/decisions.md

@@ -0,0 +1,34 @@
+# Project Decisions
+
+## Should we remove raf status or modify it?
+Don't remove status. Add automatic worktree discovery — no flag needed.
+
+## Should raf status need a --worktree flag?
+No. Always look for worktree projects automatically (if in a git repo).
+
+## Should raf status show only worktree projects or both main and worktree?
+Both combined. If a project exists in both main repo and worktree, don't duplicate in list mode — only show additional worktree projects and mark them.
+
+## How should worktree-only projects be marked in the status list?
+Indented under a "Worktrees:" header at the bottom of the list.
+
+## How should single-project view work when project exists in both main and worktree?
+Show both states separately ONLY if they differ. For example, after an amend, the main repo might show 5/5 tasks done while the worktree shows 5/7 (not fully completed). List both with clear labels (Main: / Worktree:). If states are identical, show just the normal view with no worktree label.
+
+## Should worktree projects always appear in status output?
+Only if they differ from their main repo counterpart (more tasks, different statuses). If identical, skip them. Worktree-only projects (no main counterpart) are always shown.
+
+## For raf plan --amend syntax change — keep -a alias?
+Keep -a alias. However, this task was SKIPPED — Commander.js treats both orderings identically so no code change needed.
+
+## For removing multi-project support from raf do — what should the arg look like?
+Single project argument only: `raf do <project>` with exactly one identifier.
+
+## For amend commit — should plan files be included?
+Yes. Commit input.md, decisions.md, AND any new/modified plan files.
+
+## Should amend commit message be distinct from new plan commit?
+Yes. Use `RAF[NNN] Amend: project-name` for amendments (vs `RAF[NNN] Plan: project-name` for new plans).
+
+## Should planning/amend exit messages be worktree-aware?
+Yes. When running in worktree mode, the exit message should show `raf do <project> --worktree` instead of `raf do <project>`. Both planning and amend prompts need this.

package/RAF/aaaacv-trim-the-fat/input.md

@@ -0,0 +1,5 @@
+- [ ] remove "raf status"
+- [ ] support only "raf plan project --amend" syntax (remove support for "raf plan --amend project syntax). update docs (readme and claude.md)
+- [ ] remove multi project support for raf do
+- [ ] even if plan was not created in amend (but updated) RAF should still commit input and decisions and updated plan files
+

package/RAF/aaaacv-trim-the-fat/outcomes/01-add-worktree-support-to-status.md

@@ -0,0 +1,43 @@
+# Outcome: Add Automatic Worktree Discovery to raf status
+
+## Summary
+
+Added automatic worktree project discovery to `raf status`. When inside a git repo, the status command now discovers and displays worktree projects from `~/.raf/worktrees/<repo>/` alongside main repo projects, with no flag required.
+
+## Key Changes
+
+### `src/commands/status.ts`
+- Added `getWorktreeContext()` to resolve repo basename and RAF relative path
+- Added `discoverWorktreeProjectStates()` to scan worktree directories and derive project state
+- Added `projectStatesDiffer()` to compare main vs worktree project states (by task count and statuses)
+- **List mode** (`raf status`): Shows main repo projects normally, then appends a `Worktrees:` section listing worktree projects that differ from their main repo counterpart. Identical projects are hidden. Worktree-only projects always shown.
+- **Single project mode** (`raf status <project>`): Shows both "Main:" and "Worktree:" progress bars when states differ. Shows only one view when identical or when project exists in only one location.
+- **JSON output**: List mode wraps in `{ projects: [...], worktrees: [...] }`. Single project mode adds `worktree` field when worktree data exists.
+- Gracefully handles non-git-repo case (skips worktree discovery silently)
+
+### `tests/unit/status-command.test.ts`
+- Added 10 new tests covering:
+  - Project state comparison (identical states, differing task counts, differing statuses)
+  - Worktree project discovery patterns
+  - Filtering worktree-only vs counterpart projects
+  - Stats computation for worktree projects
+
+### `README.md`
+- Updated `raf status` section to mention automatic worktree discovery
+
+### `CLAUDE.md`
+- Added worktree discovery details to the Worktree Mode section
+
+## Acceptance Criteria Verification
+
+- [x] `raf status` lists main repo projects normally, then worktree projects that differ under a `Worktrees:` header
+- [x] Worktree projects identical to their main repo counterpart are not shown
+- [x] `raf status <project>` shows both main repo and worktree state only when they differ
+- [x] `raf status <project>` shows just worktree state when project only exists in worktree
+- [x] `--json` includes worktree project data
+- [x] Non-git-repo environments work fine (worktree section just doesn't appear)
+- [x] README.md and CLAUDE.md updated
+- [x] Tests cover the new functionality (10 new tests, all passing)
+- [x] All existing tests pass (1 pre-existing failure in planning-prompt.test.ts unrelated to changes)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/02-remove-multi-project-from-do.md

@@ -0,0 +1,50 @@
+# Outcome: Remove Multi-Project Support from raf do
+
+## Summary
+
+Simplified `raf do` to accept only a single project identifier, removing the multi-project execution feature. The command argument changed from `[projects...]` (variadic) to `[project]` (single optional). All multi-project logic was removed.
+
+## Key Changes
+
+### `src/commands/do.ts`
+- Changed `.argument('[projects...]', ...)` to `.argument('[project]', ...)`
+- Changed action handler signature from `(projects: string[], ...)` to `(project: string | undefined, ...)`
+- Rewrote `runDoCommand()` to work with a single optional identifier:
+  - No array iteration, deduplication (`seenPaths`), or error accumulation
+  - Direct project resolution instead of loop
+  - Simplified merge check: `result.success` instead of `results.every(r => r.success)`
+- Removed `printMultiProjectSummary()` function entirely
+- Removed `isMultiProject` flag and multi-project verbose logging
+- Removed verbose model logging for multi-project (`if (verbose && model && resolvedProjects.length > 1)`)
+- Removed worktree guard for multiple projects (no longer needed)
+- Removed unused `SYMBOLS` import
+
+### `tests/unit/do-multiproject.test.ts`
+- Deleted entirely
+
+### `tests/unit/do-command.test.ts`
+- Removed "Multiple Projects with Full Folder Names" describe block
+- Removed "Mixed Formats" describe block (tested multi-identifier resolution)
+- Kept all single-project, backward compatibility, and error handling tests
+
+### `README.md`
+- Removed `raf do 3 4 5` example from usage
+- Changed command reference from `raf do [projects...]` to `raf do [project]`
+- Removed `--worktree supports a single project at a time (no multi-project)` line
+
+### `CLAUDE.md`
+- Removed `### Multi-Project Execution` section from architectural decisions
+- Removed `--worktree supports single project only (no multi-project)` line from worktree section
+
+## Acceptance Criteria Verification
+
+- [x] `raf do 3` works for a single project
+- [x] `raf do` (no args) still shows interactive picker
+- [x] `raf do --worktree` still shows worktree picker
+- [x] `raf do 3 4` — Commander.js with `[project]` ignores extra args
+- [x] `printMultiProjectSummary` and multi-project loop removed
+- [x] `do-multiproject.test.ts` removed
+- [x] README.md and CLAUDE.md updated (no multi-project references)
+- [x] All remaining tests pass (843 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/03-commit-artifacts-on-amend.md

@@ -0,0 +1,35 @@
+# Outcome: Commit Planning Artifacts (Including Plan Files) on Amend
+
+## Summary
+
+Extended `commitPlanningArtifacts()` to support amending by accepting additional file paths and an `isAmend` flag. The amend flow in `plan.ts` now passes new plan file paths to the commit function, and uses a distinct `Amend:` commit message prefix. Also fixed a bug where `isGitRepo()` was not receiving the `cwd` option for worktree support.
+
+## Key Changes
+
+### `src/core/git.ts`
+- Extended `commitPlanningArtifacts()` options to include `additionalFiles?: string[]` and `isAmend?: boolean`
+- When `isAmend` is true, commit message uses `RAF[NNN] Amend: project-name` instead of `RAF[NNN] Plan: project-name`
+- Additional files are staged alongside `input.md` and `decisions.md`
+- Fixed bug: `isGitRepo()` now receives `execCwd` parameter for correct worktree support (was called without `cwd` previously)
+
+### `src/commands/plan.ts`
+- Updated `runAmendCommand()` to build full paths for new plan files (`newPlanPaths = newPlanFiles.map(f => path.join(plansDir, f))`)
+- Passes `additionalFiles` and `isAmend: true` to `commitPlanningArtifacts()`
+- Normal `raf plan` flow unchanged — still only commits input + decisions with "Plan:" prefix
+
+### `tests/unit/commit-planning-artifacts.test.ts`
+- Added test: "should use 'Amend:' prefix when isAmend is true"
+- Added test: "should stage additional files when provided"
+- Added test: "should pass cwd to isGitRepo for worktree support"
+- All 11 tests pass (8 existing + 3 new)
+
+## Acceptance Criteria Verification
+
+- [x] `raf plan --amend` commits input.md, decisions.md, and new plan files together
+- [x] Amend commits use message format `RAF[NNN] Amend: project-name`
+- [x] Normal `raf plan` still uses `RAF[NNN] Plan: project-name` and only commits input + decisions
+- [x] Worktree mode works correctly (cwd passed through)
+- [x] Tests cover the amend commit scenario (3 new tests)
+- [x] All existing tests pass (846 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/04-worktree-aware-exit-messages.md

@@ -0,0 +1,36 @@
+# Outcome: Make Planning and Amend Exit Messages Worktree-Aware
+
+## Summary
+
+Made the exit messages in both planning and amend prompts worktree-aware. When planning or amending in worktree mode, the exit message now shows `raf do <project> --worktree` instead of `raf do <project>`. Also improved the amend prompt's exit message to include the `raf do` command (previously it only said "Press Ctrl-C twice to exit").
+
+## Key Changes
+
+### `src/prompts/planning.ts`
+- Added `worktreeMode?: boolean` to `PlanningPromptParams` interface
+- Updated `getPlanningPrompt()` to conditionally append ` --worktree` to the `raf do <project>` exit message
+
+### `src/prompts/amend.ts`
+- Added `worktreeMode?: boolean` to `AmendPromptParams` interface
+- Updated `getAmendPrompt()` exit message from "Press Ctrl-C twice to exit" to include `raf do <project>` command with conditional `--worktree` flag
+
+### `src/commands/plan.ts`
+- Passed `worktreeMode` to `getPlanningPrompt()` in `runPlanCommand()`
+- Passed `worktreeMode` to `getAmendPrompt()` in `runAmendCommand()`
+
+### `tests/unit/planning-prompt.test.ts`
+- Added 3 new tests: worktreeMode false, undefined, and true variations
+
+### `tests/unit/amend-prompt.test.ts` (new file)
+- Added 7 tests covering basic prompt functionality and worktree mode variations
+
+## Acceptance Criteria Verification
+
+- [x] Planning in worktree mode shows `raf do <project> --worktree` in exit message
+- [x] Planning in normal mode still shows `raf do <project>` in exit message
+- [x] Amend in worktree mode shows `raf do <project> --worktree` in exit message
+- [x] Amend in normal mode shows exit message without `--worktree`
+- [x] Tests cover both worktree and non-worktree variations (6 new tests)
+- [x] All existing tests pass (856 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/plans/01-add-worktree-support-to-status.md

@@ -0,0 +1,43 @@
+# Task: Add Automatic Worktree Discovery to raf status
+
+## Objective
+Make `raf status` always discover and display worktree projects alongside main repo projects — no flag required.
+
+## Context
+Currently `raf status` only discovers and displays projects from the main RAF directory. Projects that exist only in worktrees (`~/.raf/worktrees/<repo>/<project>/`) are invisible to the status command. This makes it hard to track worktree project progress without running `raf do --worktree`. Worktree discovery should be automatic — if a git repo is detected and worktree projects exist, they should appear.
+
+## Requirements
+- **No new flag** — worktree discovery happens automatically when the current directory is inside a git repo
+- **List mode** (`raf status`): Show main repo projects as normal, then append a `Worktrees:` section at the bottom listing worktree projects that DIFFER from their main repo counterpart (indented). A worktree project "differs" if it has more tasks (amend added new ones) or different task statuses. If the worktree state is identical to main repo, skip it. Worktree-only projects (no main repo counterpart) are always shown.
+- **Single project mode** (`raf status <project>`): Show the project from BOTH main repo and worktree only when they differ. This is common after `--amend` — e.g., main repo shows 5/5 tasks completed (original plan), while worktree shows 5/7 (amended with 2 new tasks not yet executed). Display both states, clearly labeled (e.g., "Main:" and "Worktree:"). If the states are identical, show just the main view without any worktree label. If the project only exists in worktree, show just that one.
+- Both modes should support the existing `--json` flag (include worktree data in JSON output)
+- Gracefully handle non-git-repo case: if `getRepoBasename()` returns null, skip worktree discovery silently
+- Use existing worktree utilities: `getRepoBasename()`, `listWorktreeProjects()`, `computeWorktreePath()`, `computeWorktreeBaseDir()` from `src/core/worktree.ts`
+- Use existing state derivation: `deriveProjectState()`, `getDerivedStats()` from `src/core/state-derivation.ts`
+- Follow existing patterns in `src/commands/do.ts` for worktree project resolution (searching worktree directories, resolving identifiers within them)
+
+## Implementation Steps
+1. In `runStatusCommand()` in `src/commands/status.ts`, after the main repo logic, attempt worktree discovery using `getRepoBasename()` and `listWorktreeProjects()`. If not in a git repo, skip silently.
+2. For list mode: discover worktree projects, filter out any that already appear in main repo projects (match by folder name), then display remaining under a `Worktrees:` header with indentation. Derive state for each worktree project to show progress bars.
+3. For single-project mode: resolve the project identifier in both main repo and worktrees. If found in both, show two progress displays labeled "Main:" and "Worktree:". If found in only one, show just that.
+4. Update the `--json` output to include worktree project data when worktree projects are discovered
+5. Update tests in `tests/unit/status-command.test.ts` to cover worktree discovery for both list and single-project modes
+6. Update README.md `raf status` section to mention that worktree projects are shown automatically
+7. Update CLAUDE.md to mention automatic worktree discovery in the status command
+
+## Acceptance Criteria
+- [ ] `raf status` lists main repo projects normally, then worktree projects that differ under a `Worktrees:` header
+- [ ] Worktree projects identical to their main repo counterpart are not shown
+- [ ] `raf status <project>` shows both main repo and worktree state only when they differ
+- [ ] `raf status <project>` shows just worktree state when project only exists in worktree
+- [ ] `--json` includes worktree project data
+- [ ] Non-git-repo environments work fine (worktree section just doesn't appear)
+- [ ] README.md and CLAUDE.md updated
+- [ ] Tests cover the new functionality
+- [ ] All existing tests pass
+
+## Notes
+- The worktree project resolution pattern already exists in `do.ts` — reuse that logic (or extract shared utility if the duplication is significant)
+- `listWorktreeProjects()` returns folder names like `['020-my-feature', '021-another']` — use `extractProjectNumber()` and `extractProjectName()` to display them consistently with main repo projects
+- Worktree projects need their RAF relative path computed (from repo root to RAF dir) to find the project folder inside the worktree, same as `do.ts` does
+- No changes needed to `StatusCommandOptions` type or command definition — this is automatic behavior, not a flag

package/RAF/aaaacv-trim-the-fat/plans/02-remove-multi-project-from-do.md

@@ -0,0 +1,44 @@
+# Task: Remove Multi-Project Support from raf do
+
+## Objective
+Simplify `raf do` to accept only a single project identifier, removing the multi-project execution feature.
+
+## Context
+Multi-project support (`raf do 3 4 5`) adds complexity with deduplication, sequential execution, multi-project summaries, and per-project error handling. This simplification reduces code surface area. The single-project interactive picker (`raf do` with no args) and worktree mode remain unchanged.
+
+## Requirements
+- Change the command argument from `[projects...]` (variadic) to `[project]` (single optional)
+- Remove all multi-project execution logic: the `isMultiProject` flag, the results accumulation loop, and the `printMultiProjectSummary()` function
+- Remove the verbose log for multi-project model name (`if (verbose && model && resolvedProjects.length > 1)`)
+- Remove the worktree guard for multiple projects (`if (worktreeMode && projectIdentifiers.length > 1)`) since it's no longer possible
+- Simplify the standard-mode resolution loop (no need for `seenPaths` deduplication or building a `resolvedProjects` array — just resolve one project)
+- Keep all existing single-project behavior: interactive picker, worktree auto-discovery, `--merge`, `--force`, etc.
+- Remove the `do-multiproject.test.ts` test file entirely
+- Update `do-command.test.ts` if it references multi-project behavior
+- Update README.md: remove `raf do 3 4 5` example and `[projects...]` in command reference
+- Update CLAUDE.md: remove `### Multi-Project Execution` section from architectural decisions
+
+## Implementation Steps
+1. Change the `.argument()` in `createDoCommand()` from `'[projects...]'` to `'[project]'`
+2. Update the action handler signature to receive `project: string | undefined` instead of `projects: string[]`
+3. Refactor `runDoCommand()` to work with a single optional identifier: no array iteration, no deduplication, no multi-project summary
+4. Remove `printMultiProjectSummary()` function
+5. Remove or simplify the `ProjectExecutionResult` interface and results accumulation if they become unnecessary
+6. Remove `tests/unit/do-multiproject.test.ts`
+7. Update any other test files that reference multi-project behavior
+8. Update README.md and CLAUDE.md docs
+
+## Acceptance Criteria
+- [ ] `raf do 3` works for a single project
+- [ ] `raf do` (no args) still shows interactive picker
+- [ ] `raf do --worktree` still shows worktree picker
+- [ ] `raf do 3 4` produces an error (too many arguments) or ignores extra args
+- [ ] `printMultiProjectSummary` and multi-project loop removed
+- [ ] `do-multiproject.test.ts` removed
+- [ ] README.md and CLAUDE.md updated (no multi-project references)
+- [ ] All remaining tests pass
+
+## Notes
+- Commander.js with `[project]` (non-variadic) will only capture the first argument — extra arguments are typically ignored. Consider adding explicit validation or letting Commander handle it.
+- The `ProjectExecutionResult` type and `executeSingleProject()` function can stay — they're used for the single-project case too. Just remove the array accumulation pattern around them.
+- The `--merge` logic depends on `results.every(r => r.success)` — simplify this to just check the single result.

package/RAF/aaaacv-trim-the-fat/plans/03-commit-artifacts-on-amend.md

@@ -0,0 +1,38 @@
+# Task: Commit Planning Artifacts (Including Plan Files) on Amend
+
+## Objective
+Ensure that `raf plan --amend` commits input.md, decisions.md, AND plan files — not just input and decisions — using a distinct "Amend" commit message.
+
+## Dependencies
+002
+
+## Context
+Currently `commitPlanningArtifacts()` in `src/core/git.ts` only stages and commits `input.md` and `decisions.md`. For new plans (`raf plan`), this is fine because Claude commits plan files during execution. But for amendments, the new/updated plan files created during the amend session are never committed by RAF. Additionally, the commit message should distinguish amendments from new plans.
+
+## Requirements
+- Modify `commitPlanningArtifacts()` (or create a new function) to optionally accept plan file paths to include in the commit
+- The amend flow in `src/commands/plan.ts` (`runAmendCommand()`) should pass the new/modified plan files to the commit function
+- Use commit message format `RAF[NNN] Amend: project-name` for amendments (vs existing `RAF[NNN] Plan: project-name` for new plans)
+- The normal `raf plan` flow should continue to use the existing behavior (commit only input + decisions with "Plan:" message)
+- Support worktree mode (pass `cwd` option through)
+- Plan files are in the `plans/` subdirectory of the project path; the amend flow already detects new plan files by checking if their task number >= `nextTaskNumber`
+
+## Implementation Steps
+1. Extend `commitPlanningArtifacts()` in `src/core/git.ts` to accept optional additional file paths and an optional commit message override (or an `isAmend` flag that changes the message format)
+2. In `runAmendCommand()` in `src/commands/plan.ts`, after detecting new plan files, build their full paths and pass them to `commitPlanningArtifacts()` along with the amend flag
+3. The git add command should stage `input.md`, `decisions.md`, and all plan files (new and existing, since existing ones won't have changes and won't affect the commit)
+4. Update the existing tests in `tests/unit/commit-planning-artifacts.test.ts` to cover the new parameters
+5. Add tests for the amend commit message format
+
+## Acceptance Criteria
+- [ ] `raf plan --amend` commits input.md, decisions.md, and new plan files together
+- [ ] Amend commits use message format `RAF[NNN] Amend: project-name`
+- [ ] Normal `raf plan` still uses `RAF[NNN] Plan: project-name` and only commits input + decisions
+- [ ] Worktree mode works correctly (cwd passed through)
+- [ ] Tests cover the amend commit scenario
+- [ ] All existing tests pass
+
+## Notes
+- The amend flow in `plan.ts` already computes `newPlanFiles` (lines 547-553) — these are just filenames like `004-new-task.md`. Build full paths as `path.join(plansDir, filename)`.
+- Consider staging the entire `plans/` directory with a glob rather than individual files — simpler and captures any modifications to existing plans too. But be careful not to stage unrelated files.
+- `commitPlanningArtifacts()` currently checks `isGitRepo()` without cwd — this should also be fixed to use the cwd option for worktree support (existing bug).

package/RAF/aaaacv-trim-the-fat/plans/04-worktree-aware-exit-messages.md

@@ -0,0 +1,38 @@
+# Task: Make Planning and Amend Exit Messages Worktree-Aware
+
+## Objective
+When planning or amending in worktree mode, the exit message shown to the user should include `--worktree` in the `raf do` command.
+
+## Context
+Currently the planning prompt (`src/prompts/planning.ts`) shows `raf do <project>` as the exit message, and the amend prompt (`src/prompts/amend.ts`) shows a generic "Press Ctrl-C twice to exit" with no `raf do` hint. Neither is aware of worktree mode. When the user planned with `--worktree`, the follow-up `raf do` command also needs `--worktree`, so the exit message should reflect that.
+
+## Dependencies
+002
+
+## Requirements
+- Add a `worktreeMode` (boolean) parameter to both `PlanningPromptParams` and `AmendPromptParams` interfaces
+- When `worktreeMode` is true, the exit message in the planning prompt should show `raf do <project> --worktree` instead of `raf do <project>`
+- When `worktreeMode` is true, the exit message in the amend prompt should also include `raf do <project> --worktree`
+- Pass the `worktreeMode` value through from `runPlanCommand()` and `runAmendCommand()` in `src/commands/plan.ts` when calling `getPlanningPrompt()` and `getAmendPrompt()`
+- Update any existing tests for planning and amend prompts to cover the worktree variation
+
+## Implementation Steps
+1. Add `worktreeMode?: boolean` to `PlanningPromptParams` in `src/prompts/planning.ts`
+2. Update the exit message template in `getPlanningPrompt()` to conditionally include `--worktree`
+3. Add `worktreeMode?: boolean` to `AmendPromptParams` in `src/prompts/amend.ts`
+4. Update the exit message in `getAmendPrompt()` to include `raf do <project> --worktree` when in worktree mode
+5. Pass `worktreeMode` from `runPlanCommand()` and `runAmendCommand()` in `src/commands/plan.ts` to the prompt functions
+6. Update tests for both prompts to verify the worktree-aware exit messages
+
+## Acceptance Criteria
+- [ ] Planning in worktree mode shows `raf do <project> --worktree` in exit message
+- [ ] Planning in normal mode still shows `raf do <project>` in exit message
+- [ ] Amend in worktree mode shows `raf do <project> --worktree` in exit message
+- [ ] Amend in normal mode shows exit message without `--worktree`
+- [ ] Tests cover both worktree and non-worktree variations
+- [ ] All existing tests pass
+
+## Notes
+- The planning prompt's exit message is at approximately line 154 of `src/prompts/planning.ts`
+- The amend prompt's exit message is at approximately line 184 of `src/prompts/amend.ts` — it currently says "Press Ctrl-C twice to exit" without mentioning `raf do` at all; add the `raf do` command there too
+- The `plan.ts` command already has `worktreeMode` as a local variable in both `runPlanCommand()` and `runAmendCommand()`, so it's trivial to pass through

package/RAF/aaaacw-prune-cycle/decisions.md

@@ -0,0 +1,25 @@
+# Project Decisions
+
+## When should worktrees be cleaned up after execution?
+Success only - Clean worktree only when all tasks complete successfully. Keep on failure for inspection.
+
+## When cleaning up the worktree, should the git branch also be deleted, or kept for potential future amend?
+Keep branch - Only remove the worktree directory. Keep the git branch so amend can find it later.
+
+## For `raf plan --amend --worktree`: when the worktree doesn't exist but a branch matching the project name is found, should RAF automatically recreate the worktree or prompt the user first?
+Auto-recreate silently - Automatically create a new worktree from the existing branch and continue. Just log an info message.
+
+## For `raf do --worktree`: same scenario - worktree was cleaned up but branch exists. Should `raf do` also auto-recreate?
+Keep current behaviour of raf do - no auto-recreate. Only amend should recreate worktrees.
+
+## Should `createWorktreeFromBranch()` be a new function or extend existing `createWorktree()`?
+New function - Add a separate `createWorktreeFromBranch()` function. Keeps create-new and create-from-existing as distinct operations.
+
+## Should the worktree cleanup happen immediately after all tasks finish or after the merge step?
+After tasks only - Always cleanup right after tasks finish, before merge. Merge operates on the branch, not the worktree directory.
+
+## Should the 'branch not found' fallback be a new task or part of task 003?
+Modify task 003 - Add the 'branch not found → create fresh worktree' fallback directly into the existing task 003 plan.
+
+## When neither worktree nor branch exists during amend, what should happen?
+Create fresh worktree + copy project folder from main repo into it, then continue the amend flow.

package/RAF/aaaacw-prune-cycle/input.md

@@ -0,0 +1,5 @@
+- [ ] clean worktrees on execution completion. in case of plan --amend - look for a git branch what matches project name (raf creates it during plan) and create new git worktree from it and then continue amend flow from there
+
+---
+
+if branch not exist - copy use the same flow as "raf do"

package/RAF/aaaacw-prune-cycle/outcomes/01-create-worktree-from-branch.md

@@ -0,0 +1,32 @@
+# Outcome: Add createWorktreeFromBranch utility
+
+## Summary
+
+Added two new functions to `src/core/worktree.ts`:
+
+1. **`branchExists(branchName)`** - Checks if a local git branch exists using `git branch --list`
+2. **`createWorktreeFromBranch(repoBasename, projectId)`** - Creates a git worktree from an existing branch (using `git worktree add <path> <branch>` without the `-b` flag)
+
+## Key Changes
+
+### Files Modified
+- `src/core/worktree.ts` - Added `branchExists()` and `createWorktreeFromBranch()` functions
+- `tests/unit/worktree.test.ts` - Added 7 new test cases covering both functions
+
+### Implementation Details
+- `createWorktreeFromBranch()` reuses existing `computeWorktreePath()` and `computeWorktreeBaseDir()` helpers
+- Returns `WorktreeCreateResult` (same interface as `createWorktree()`)
+- Validates branch existence before attempting worktree creation
+- Handles error cases: branch not found, parent directory creation failure, git command failure
+- Existing `createWorktree()` is unchanged
+
+### Test Coverage
+- `branchExists`: existing branch, non-existing branch, git failure
+- `createWorktreeFromBranch`: success path, branch-not-found, parent dir failure, worktree-already-exists
+
+## Verification
+- TypeScript compiles without errors
+- All 43 worktree tests pass (36 existing + 7 new)
+- 1 pre-existing failure in `planning-prompt.test.ts` (unrelated)
+
+<promise>COMPLETE</promise>