rafcode 1.3.2 → 2.0.0

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>

package/RAF/aaaacw-prune-cycle/outcomes/02-cleanup-worktree-on-success.md

@@ -0,0 +1,33 @@
+# Outcome: Clean up worktree after successful execution
+
+## Summary
+
+Added automatic worktree cleanup to `raf do --worktree` when all tasks complete successfully. The worktree directory is removed but the git branch is preserved for future `raf plan --amend --worktree` operations.
+
+## Key Changes
+
+### Files Modified
+- `src/commands/do.ts` - Added worktree cleanup logic after `executeSingleProject()` returns, before the `--merge` step. Imported `removeWorktree` from worktree module.
+- `src/core/worktree.ts` - Updated `removeWorktree()` JSDoc to reflect its use for both failed-plan cleanup and post-completion cleanup.
+- `CLAUDE.md` - Updated worktree lifecycle documentation to reflect automatic cleanup on success.
+- `tests/unit/do-worktree-cleanup.test.ts` - New test file with 8 tests covering cleanup behavior.
+
+### Implementation Details
+- Cleanup condition: `worktreeMode && worktreeRoot && result.success`
+- On success: calls `removeWorktree(worktreeRoot)` and logs "Cleaned up worktree: <path>"
+- On cleanup failure: logs a warning via `logger.warn()` but does NOT exit with error
+- On task failure: worktree is kept for inspection (cleanup not triggered)
+- Cleanup happens BEFORE the `--merge` step — merge operates on the branch name, not the worktree directory
+
+### Test Coverage
+- `removeWorktree preserves branch`: verifies only `git worktree remove` is called, no branch deletion
+- `cleanup decision logic` (4 tests): verifies cleanup conditions (worktreeMode, worktreeRoot, result.success)
+- `cleanup failure handling` (2 tests): verifies error/success result from removeWorktree
+- `merge after cleanup`: verifies merge uses branch name, not worktree directory path
+
+## Verification
+- TypeScript compiles without errors
+- All 879 tests pass (871 existing + 8 new), 1 pre-existing failure in `planning-prompt.test.ts` (unrelated)
+- No regressions introduced
+
+<promise>COMPLETE</promise>

package/RAF/aaaacw-prune-cycle/outcomes/03-amend-recreate-worktree.md

@@ -0,0 +1,40 @@
+# Outcome: Auto-recreate worktree from existing branch in amend flow
+
+## Summary
+
+Modified `runAmendCommand()` in `src/commands/plan.ts` to auto-recreate worktrees when `raf plan --amend --worktree` is run and the worktree directory doesn't exist (e.g., after automatic cleanup on successful execution). Two fallback paths are supported:
+
+1. **Branch exists** (common after cleanup): Recreates worktree from the existing branch using `createWorktreeFromBranch()`
+2. **No branch exists**: Creates a fresh worktree with `createWorktree()` and copies project files from the main repo using `fs.cpSync()`
+
+## Key Changes
+
+### Files Modified
+- `src/commands/plan.ts` — Replaced the hard error when no worktree is found with a two-tier fallback: resolve project from main repo, check for existing branch, recreate or create fresh worktree. Also removed the early exit when the worktree base directory doesn't exist (now gracefully skips the search and falls through to the fallback).
+- `CLAUDE.md` — Updated worktree lifecycle documentation to mention recreate-on-amend scenarios and new utility functions.
+- `tests/unit/plan-amend-worktree-recreate.test.ts` — New test file with 11 tests covering: decision logic, branch recreation, fresh creation, file copy, error handling, and existing-flow preservation.
+
+### Implementation Details
+- When worktree search finds no match, resolves the project from the main repo using `resolveProjectIdentifierWithDetails(rafDir, identifier)`
+- Extracts folder name via `path.basename()` (folder name = branch name)
+- Uses `branchExists()` (from task 001) to decide which path
+- `createWorktreeFromBranch()` (from task 001) recreates from existing branch — project files are already on the branch
+- `createWorktree()` creates a fresh worktree, then `fs.cpSync()` copies the project folder from main repo
+- Both paths set `matchedWorktreeDir` and `matchedProjectPath` so the rest of the amend flow continues seamlessly
+- Info messages logged: "Recreated worktree from branch: <name>" or "Created fresh worktree and copied project files: <name>"
+- Error if project not found in main repo or worktrees: "Project not found in any worktree or main repo: <identifier>"
+
+### Test Coverage
+- Decision logic: branch exists → createWorktreeFromBranch, branch doesn't exist → createWorktree
+- Branch recreation: success path, branch-not-found error
+- Fresh worktree: success with -b flag
+- File copy: all project files (input.md, decisions.md, plans/, outcomes/) copied correctly with preserved structure
+- Error handling: project not found, createWorktreeFromBranch failure, createWorktree failure
+- Existing flow: worktree search match skips recreation
+
+## Verification
+- TypeScript compiles without errors
+- All 882 tests pass (871 existing + 11 new), 1 pre-existing failure in `planning-prompt.test.ts` (unrelated)
+- No regressions introduced
+
+<promise>COMPLETE</promise>

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

@@ -0,0 +1,31 @@
+# Task: Add createWorktreeFromBranch utility
+
+## Objective
+Add a new `createWorktreeFromBranch()` function to `src/core/worktree.ts` that creates a git worktree from an existing branch, and a `branchExists()` helper to check if a branch exists locally.
+
+## Context
+Currently `createWorktree()` always creates a new branch (`git worktree add -b`). The new amend flow needs to recreate a worktree from an existing branch after the worktree was cleaned up post-execution. This is a prerequisite for both the cleanup feature (branch must survive worktree removal) and the amend recreation feature.
+
+## Requirements
+- Add `branchExists(branchName: string): boolean` function that checks if a local branch exists
+- Add `createWorktreeFromBranch(repoBasename: string, projectId: string): WorktreeCreateResult` that uses `git worktree add <path> <existing-branch>` (no `-b` flag) to attach a worktree to an existing branch
+- Reuse the same `WorktreeCreateResult` interface and `computeWorktreePath` logic
+- Handle error cases: branch doesn't exist, worktree path already exists, git command failure
+- Add unit tests covering success path, branch-not-found, and worktree-already-exists scenarios
+
+## Implementation Steps
+1. Add `branchExists()` helper using `git branch --list <name>`
+2. Add `createWorktreeFromBranch()` function - same structure as `createWorktree()` but uses `git worktree add <path> <branch>` without the `-b` flag
+3. Export both new functions
+4. Add tests in the worktree test file
+
+## Acceptance Criteria
+- [ ] `branchExists()` correctly detects existing and non-existing branches
+- [ ] `createWorktreeFromBranch()` creates a worktree attached to an existing branch
+- [ ] Returns appropriate error when branch doesn't exist
+- [ ] All new and existing tests pass
+- [ ] TypeScript compiles without errors
+
+## Notes
+- The existing `createWorktree()` function should remain unchanged - it's used by `raf plan --worktree` for new projects
+- The branch name matches the project folder name (e.g., `022-prune-cycle`)

package/RAF/aaaacw-prune-cycle/plans/02-cleanup-worktree-on-success.md

@@ -0,0 +1,38 @@
+# Task: Clean up worktree after successful execution
+
+## Objective
+Add automatic worktree cleanup to `raf do --worktree` when all tasks complete successfully, preserving the git branch for future amend operations.
+
+## Context
+Currently worktrees persist indefinitely after execution. Since the git branch contains all committed work, the worktree directory is redundant after successful completion. Cleaning it up reduces clutter in `~/.raf/worktrees/`. The branch is intentionally kept so `raf plan --amend --worktree` can recreate the worktree later.
+
+## Dependencies
+001
+
+## Requirements
+- After `executeSingleProject()` returns successfully in worktree mode, remove the worktree using `removeWorktree()`
+- Cleanup happens immediately after tasks finish, BEFORE the `--merge` step (merge operates on the branch, not the worktree directory)
+- Only clean up on success (all tasks completed). Keep worktree on failure for inspection
+- Do NOT delete the git branch - only remove the worktree directory
+- Log a message when cleanup happens (e.g., "Cleaned up worktree: <path>")
+- If cleanup fails, log a warning but don't fail the overall command
+
+## Implementation Steps
+1. In `src/commands/do.ts`, after `executeSingleProject()` returns, check if worktree mode is active and result is successful
+2. Call `removeWorktree(worktreeRoot)` to clean up the directory
+3. Log appropriate success/warning messages
+4. Continue to the merge step (which uses the branch, not the worktree directory)
+5. Add/update tests for the do command's cleanup behavior
+
+## Acceptance Criteria
+- [ ] Worktree directory is removed after successful execution with `--worktree`
+- [ ] Git branch is preserved after worktree cleanup
+- [ ] Worktree is NOT cleaned up on failure
+- [ ] `--merge` still works after worktree cleanup (operates on branch)
+- [ ] Cleanup failure produces a warning, not an error exit
+- [ ] All tests pass
+
+## Notes
+- The `removeWorktree()` function already exists in `src/core/worktree.ts`
+- The merge step in `do.ts` already uses the branch name (`path.basename(worktreeRoot)`), not the worktree directory itself, so merge should work after cleanup
+- Consider that `raf status` auto-discovers worktree directories - after cleanup, the project will no longer appear in the worktrees section of status output (this is expected)

package/RAF/aaaacw-prune-cycle/plans/03-amend-recreate-worktree.md

@@ -0,0 +1,50 @@
+# Task: Auto-recreate worktree from existing branch in amend flow
+
+## Objective
+When `raf plan --amend --worktree` is run and the worktree directory doesn't exist, automatically recreate it — either from an existing branch or by creating a fresh worktree and copying project files from the main repo.
+
+## Context
+After task 002, worktrees are cleaned up on successful execution but branches are preserved. When a user wants to amend a completed worktree project, the amend command needs to detect this situation and recreate the worktree. Currently, amend in worktree mode searches existing worktree directories and fails if none is found. There are two fallback scenarios to handle:
+1. Branch exists → recreate worktree from that branch (most common after cleanup)
+2. Neither branch nor worktree exists → create a fresh worktree with a new branch and copy the project files from the main repo
+
+## Dependencies
+001, 002
+
+## Requirements
+- In `runAmendCommand()` when `worktreeMode` is true, after the existing worktree search fails to find the project:
+  1. Resolve the project identifier from the main repo to get the project folder name
+  2. Check if a branch matching that folder name exists using `branchExists()`
+  3. **If branch exists**: call `createWorktreeFromBranch()` to recreate the worktree. Log an info message like "Recreated worktree from branch: <branch>"
+  4. **If branch does NOT exist**: call the regular `createWorktree()` to create a fresh worktree with a new branch, then copy the project folder (`RAF/<project>/`) from the main repo into the new worktree. Log an info message about creating a fresh worktree.
+  5. Continue the amend flow with the recreated/new worktree path
+- The recreated worktree (from branch) should already contain the project files since they're on the branch
+- The fresh worktree (no branch) needs the project files copied over from the main repo
+- Both paths should seamlessly continue into the normal amend planning flow
+
+## Implementation Steps
+1. In `src/commands/plan.ts`, modify the `runAmendCommand()` worktree resolution logic
+2. After the existing worktree search loop finds no match, add a two-tier fallback:
+   - First, check for existing branch with `branchExists(folderName)`
+   - If branch found: call `createWorktreeFromBranch(repoBasename, folderName)`
+   - If no branch: call `createWorktree(repoBasename, folderName)`, then copy the `RAF/<project>/` directory from the main repo into the new worktree
+3. Set `worktreePath` and resolve `projectPath` inside the new worktree
+4. Import the new functions from `worktree.ts`
+5. Add tests covering: branch found and worktree recreated, no branch found and fresh worktree created with project files copied, neither scenario errors
+
+## Acceptance Criteria
+- [ ] `raf plan --amend --worktree <project>` works when worktree was cleaned up but branch exists
+- [ ] `raf plan --amend --worktree <project>` works when neither worktree nor branch exists — creates fresh worktree and copies project files
+- [ ] Recreated worktree (from branch) contains the project files from the branch
+- [ ] Fresh worktree (no branch) contains project files copied from the main repo
+- [ ] Info messages are logged about which path was taken (recreate from branch vs. fresh worktree)
+- [ ] Existing amend flow (worktree still exists) continues to work unchanged
+- [ ] All tests pass
+
+## Notes
+- The project folder name IS the branch name (e.g., `022-prune-cycle`)
+- The main repo may or may not have the project folder — worktree-only projects exist only on the branch
+- For the "no branch" fallback, the project MUST exist in the main repo (otherwise there's nothing to copy) — if it doesn't, show an error
+- After `createWorktreeFromBranch()`, the worktree should have all the files from the branch including `RAF/<project>/plans/`, `outcomes/`, etc.
+- After `createWorktree()` + copy, the new worktree will have the project files but on a fresh branch based on the current HEAD
+- Update CLAUDE.md documentation about the worktree lifecycle to mention both recreate-on-amend scenarios

package/RAF/aaaacx-epoch-shift/decisions.md

@@ -0,0 +1,25 @@
+# Project Decisions
+
+## Should the base36 timestamp ID be fixed-width or variable-length?
+Fixed-width, 6 characters. This covers ~69 years from the shifted epoch (36^6 = 2,176,782,336 seconds).
+
+## How should collisions be handled if two projects are created within the same second?
+Increment by 1 — if timestamp ID already exists, increment until a free slot is found.
+
+## Should existing projects using the old sequential numbering still be recognized?
+Clean break. Only support the new timestamp-based format going forward.
+
+## Unix time precision?
+Seconds.
+
+## What is the shifted epoch?
+Exactly Jan 1, 2026 00:00:00 UTC (unix timestamp 1,767,225,600). All project IDs are base36(floor(current_unix_seconds) - 1,767,225,600), zero-padded to 6 chars.
+
+## What about git commit and branch naming format?
+Same pattern with new ID. Commits: `RAF[00j3k1:001] description`. Branches: `00j3k1-epoch-shift`.
+
+## How should identifier resolution work?
+Support both the 6-char base36 ID and project name substring matching (similar to current system, minus old sequential format).
+
+## Sort order?
+Sort by ID, which naturally equals chronological (creation time) order.

package/RAF/aaaacx-epoch-shift/input.md

@@ -0,0 +1 @@
+- [ ] switch project id number generation to base36 encoding (starting with 0) of unix time (but make "unix" start from 01-01-2026 or unix time - 56 years)

package/RAF/aaaacx-epoch-shift/outcomes/01-epoch-id-generation.md

@@ -0,0 +1,34 @@
+# Outcome: Replace Core ID Generation with Epoch-Based Base36
+
+## Summary
+
+Replaced the sequential project numbering system (001-999 numeric, then a00-zzz base36) with epoch-based timestamp IDs. Each project ID is now the base36 encoding of `(current_unix_seconds - 1767225600)`, zero-padded to 6 characters.
+
+## Key Changes
+
+### `src/utils/paths.ts`
+- Added `RAF_EPOCH` constant (1767225600 = 2026-01-01T00:00:00Z)
+- Rewrote `encodeBase36()`: now accepts any non-negative integer, produces 6-char zero-padded base36 string using native `Number.toString(36)`
+- Rewrote `decodeBase36()`: validates 6-char format, uses `parseInt(str, 36)`
+- Rewrote `isBase36Prefix()`: validates 6-char `[0-9a-z]` format
+- Rewrote `getNextProjectNumber()`: generates timestamp-based ID with collision avoidance (increment until free slot found)
+- Simplified `formatProjectNumber()`: delegates to `encodeBase36()`
+- Updated all regex patterns from `\d{2,3}` / `[a-z][0-9a-z]{2}` to `[0-9a-z]{6}` in: `getProjectDir`, `extractProjectNumber`, `extractProjectName`, `listProjects`, `parseProjectFolder`, `resolveProjectIdentifierWithDetails`
+- Simplified `parseProjectPrefix()`: only accepts 6-char base36
+- Fixed `resolveProjectIdentifierWithDetails()` to fall through from number matching to name matching when a 6-char identifier doesn't match any project by number (prevents e.g. "second" being mistaken for a base36 prefix)
+- Removed old constants: `BASE36_START`, `MAX_NUMERIC`
+
+### `src/core/state-derivation.ts`
+- Updated `discoverProjects()` to use new 6-char base36 prefix pattern
+- Added `decodeBase36` import
+
+### `tests/unit/paths.test.ts`
+- Completely rewritten to test the new epoch-based ID system
+- 66 tests, all passing
+
+## Notes
+- This is a clean break from old IDs - no backward compatibility
+- Other test files in the project still use old-format directories (e.g., `001-first`) for their own test scenarios. These will need updating in a subsequent task that updates the remaining callers/patterns.
+- The `number` field in `ProjectInfo`, `DiscoveredProject`, etc. now holds the shifted timestamp value (a large integer) rather than a small sequential number. This still sorts correctly by creation time.
+
+<promise>COMPLETE</promise>

package/RAF/aaaacx-epoch-shift/outcomes/02-update-pattern-matching.md

@@ -0,0 +1,32 @@
+# Outcome: Update All Pattern Matching and Resolution for 6-Char IDs
+
+## Summary
+
+Updated all remaining project ID patterns across the codebase to use the new 6-character base36 format. Task 001 had already updated `paths.ts` and `state-derivation.ts`; this task updated the remaining callers.
+
+## Key Changes
+
+### `src/utils/validation.ts`
+- Rewrote `validateProjectExists()`: replaced dual regex patterns (`/^\d{2,3}-/` and `/^[a-z][0-9a-z]{2}-/`) with single 6-char base36 pattern `/^[0-9a-z]{6}-(.+)$/i`
+
+### `src/commands/status.ts`
+- Updated project number display in `listAllProjects()`: replaced `String(project.number).padStart(3, '0')` with `formatProjectNumber(project.number)` to show base36 IDs
+- Added `formatProjectNumber` import from paths.ts
+- Updated CLI argument help text to show new format examples (`00j3k1` instead of `001`)
+
+### `src/commands/do.ts`
+- Updated CLI argument help text to show new format examples (`00j3k1` instead of `001`)
+
+## Verification
+
+- TypeScript compiles with no errors (`npm run lint` passes)
+- All remaining `\d{2,3}` patterns in source code are for task-level IDs (3-digit like `001`), not project IDs — confirmed correct
+- No old numeric-only or 3-char base36 project patterns remain in source code
+- Test failures exist but are expected — test files still use old-format fixtures (e.g., `001-first`) and will be updated in Task 003
+
+## Notes
+- The `paths.ts`, `state-derivation.ts`, and `project-picker.ts` files were already updated by Task 001
+- Task-level patterns (`\d{2,3}`) in `state-derivation.ts`, `project-manager.ts`, `plan.ts`, and `execution.ts` are intentionally unchanged — task numbering within a project remains 3-digit
+- The `project-manager.ts:readOutcomes()` uses `\d{2,3}` for task file matching, which is correct
+
+<promise>COMPLETE</promise>

package/RAF/aaaacx-epoch-shift/outcomes/03-update-tests.md

@@ -0,0 +1,59 @@
+# Outcome: Update All Tests for 6-Char Base36 Project IDs
+
+## Summary
+
+Updated all test files affected by the project ID format change from sequential 3-char prefixes (e.g., `001-project`, `a01-project`) to epoch-based 6-char base36 prefixes (e.g., `000001-project`, `00a001-project`). All 842 tests across 41 suites pass.
+
+## Key Changes
+
+### `tests/unit/status-command.test.ts`
+- Updated all project folder names from 3-char to 6-char prefixes (e.g., `003-numeric-project` → `000003-numeric-project`)
+- Changed `createProject` helper to use `encodeBase36(number)` instead of `padStart(3, '0')`
+- Updated test identifiers from `'3'`, `'003'`, `'a00'` to `'000003'`, `'00a001'`, etc.
+- Added `encodeBase36` import from paths.ts
+- Added negative test for old-format folder rejection
+
+### `tests/unit/plan-command.test.ts`
+- Updated all project folder names from 3-char to 6-char prefixes
+- Changed resolution test identifiers from `'3'`, `'a01'`, `'1'` to `'000003'`, `'00a001'`, `'000001'`
+
+### `tests/unit/do-command.test.ts`
+- Updated all project folder names from 3-char to 6-char prefixes
+- Removed obsolete "Backward Compatibility" section that tested old 3-char and numeric identifiers
+- Tests now verify 6-char base36 prefix resolution, full folder name resolution, and name resolution
+
+### `tests/unit/project-picker.test.ts`
+- Updated all mock data paths from `001-*`, `002-*` to `000001-*`, `000002-*`
+- Updated format expectations from `'001 fix-auth-bug (2/5 tasks)'` to `'000001 fix-auth-bug (2/5 tasks)'`
+- Updated `mockSelect` return values accordingly
+
+### `tests/unit/project-manager.test.ts`
+- Changed tests to use regex matching for epoch-based IDs (e.g., `/^[0-9a-z]{6}-first$/`) instead of exact matches
+- Uses `toBeGreaterThanOrEqual` comparisons for epoch-based ID values
+- Added imports for `encodeBase36` and `RAF_EPOCH`
+
+### `tests/unit/state-derivation.test.ts`
+- Updated `discoverProjects` tests from `001-first-project` to `000001-first-project`
+- Added `001-too-short` as an intentionally ignored directory (validates 3-char prefixes are rejected)
+
+### `tests/unit/planning-prompt.test.ts`
+- Fixed pre-existing bug: changed assertion from `'3-8 distinct'` to `'identify distinct'` to match actual prompt text
+
+### `tests/unit/commit-planning-artifacts.test.ts`
+- Updated `017-decision-vault` → `000017-decision-vault`
+- Updated `a01-my-feature` → `00a001-my-feature`
+- Updated regex patterns `RAF\[017\]` → `RAF\[000017\]` and `RAF\[a01\]` → `RAF\[00a001\]`
+
+## Files Not Changed (Verified Correct)
+
+The following test files use 3-char prefixes but were verified to be correct:
+- `do-blocked-tasks.test.ts`, `do-rerun.test.ts`, `dependency-integration.test.ts` — use `001-test-project` as arbitrary temp directory names not parsed by project resolution; inner references are task-level IDs (3-digit, intentionally unchanged)
+- `worktree.test.ts`, `worktree-integration.test.ts`, `plan-amend-worktree-recreate.test.ts`, `do-worktree-cleanup.test.ts` — use names as branch names/worktree paths, not parsed by project ID resolution
+
+## Verification
+
+- All 842 tests pass across 41 test suites
+- TypeScript compiles with no errors
+- No old-format project ID references remain in test files (only task-level 3-digit IDs, temp directory names, and intentional negative test cases)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacx-epoch-shift/outcomes/04-update-documentation.md

@@ -0,0 +1,30 @@
+# Outcome: Update Documentation for New ID System
+
+## Summary
+
+Updated CLAUDE.md and README.md to reflect the new epoch-based 6-character base36 project ID format, replacing all references to the old sequential numbering system.
+
+## Key Changes
+
+### `CLAUDE.md`
+- **RAF Project Structure**: Updated folder example from `NNN-project-name/` (e.g., `001-fix-bug or a00-feature`) to `00j3k1-project-name/` with 6-char epoch-based base36 ID
+- **Project Naming Convention**: Replaced old format description (`NNN` 001-999, then `XXX` a00-zzz, "46,000+ projects") with epoch-based scheme (`XXXXXX` 6-char base36, generated from Unix timestamp minus RAF_EPOCH, unique by timestamp, sorts chronologically)
+- **Project Identifier Resolution**: Simplified from 4 formats (numeric, base36, name, folder) to 3 formats (base36 ID, name, full folder name) with updated examples
+- **Git Commit Schema**: Updated examples from `RAF[005:001]`, `RAF[a01:003]` to `RAF[00j3k1:001]`, `RAF[00k5m2:003]`
+- **Worktree Mode**: Updated worktree path and branch name examples from `020-my-feature` to `00j3k1-my-feature`
+
+### `README.md`
+- Updated `raf plan --amend` example from `3` to `00j3k1`
+- Updated `raf do` example from `3` (project #3) to `00j3k1` (by project ID)
+- Updated `raf status` example from `3` (project #3) to `00j3k1`
+- Updated Project Structure section: folder examples from `001-auth-system/`, `002-dashboard/` to `00j3k1-auth-system/`, `00k5m2-dashboard/`; description changed from "numbered project directories" to "project directories identified by epoch-based base36 IDs"
+- Updated worktree branch name example from `020-my-feature` to `00j3k1-my-feature`
+
+## Verification
+
+- No references to old sequential numbering (001-999) for project IDs remain in docs
+- No references to old base36 format (a00-zzz) for project IDs remain in docs
+- Task-level IDs (001, 002, etc.) correctly preserved throughout both files
+- All examples use consistent 6-char base36 IDs
+
+<promise>COMPLETE</promise>

package/RAF/aaaacx-epoch-shift/plans/01-epoch-id-generation.md

@@ -0,0 +1,40 @@
+# Task: Replace Core ID Generation with Epoch-Based Base36
+
+## Objective
+Replace the sequential project numbering system with timestamp-based IDs using base36 encoding of shifted unix time.
+
+## Context
+Currently RAF uses sequential numbering (001-999 numeric, then a00-zzz base36). This task replaces that with a new scheme: each project ID is the base36 encoding of `(current_unix_seconds - RAF_EPOCH)`, zero-padded to 6 characters. The RAF epoch is 2026-01-01T00:00:00Z (unix timestamp 1767225600). This is a clean break — no backward compatibility with old IDs.
+
+## Requirements
+- Define the RAF epoch constant: 1767225600 (2026-01-01T00:00:00Z)
+- ID width: 6 characters, zero-padded (covers ~69 years)
+- Encoding: standard base36 (digits 0-9, letters a-z) of the shifted timestamp in seconds
+- `getNextProjectNumber()` → replace with a function that generates an ID from `Math.floor(Date.now()/1000) - RAF_EPOCH`
+- Collision handling: if a folder with that ID already exists in the RAF dir, increment by 1 until a free slot is found
+- Replace `encodeBase36()` / `decodeBase36()` with simple base36 encode/decode operating on any non-negative integer, outputting 6-char zero-padded strings
+- Replace `formatProjectNumber()` to use the new encoding
+- Remove the old constants `BASE36_START`, `MAX_NUMERIC`, and the old `isBase36Prefix()` check
+- The function should still accept a `rafDir` parameter to scan for collisions
+- Keep the function signatures compatible where possible or update all callers
+
+## Implementation Steps
+1. Replace the old base36 constants and encoding functions in `src/utils/paths.ts` with the new epoch-based system
+2. Rewrite `getNextProjectNumber()` to generate timestamp-based IDs with collision avoidance
+3. Rewrite `formatProjectNumber()` to produce 6-char zero-padded base36 strings
+4. Update `isBase36Prefix()` to validate 6-char base36 strings (the new format)
+5. Update callers in `src/core/project-manager.ts` and `src/commands/plan.ts` (both call `getNextProjectNumber()` and `formatProjectNumber()`)
+
+## Acceptance Criteria
+- [ ] New epoch constant defined
+- [ ] `encodeBase36(n)` converts any non-negative integer to a 6-char zero-padded base36 string
+- [ ] `decodeBase36(str)` converts a 6-char base36 string back to an integer
+- [ ] ID generation uses `floor(Date.now()/1000) - 1767225600`
+- [ ] Collision detection increments ID when folder already exists
+- [ ] Old sequential numbering code fully removed
+- [ ] All callers updated
+- [ ] TypeScript compiles with no errors
+
+## Notes
+- The `number` field in `ProjectInfo`, `DiscoveredProject`, etc. will now hold the shifted timestamp value (a large integer like 3456000) rather than a small sequential number. This is fine — it still sorts correctly by creation time.
+- Consider whether `getNextProjectNumber` should return a number or a string. Currently returns number, which works since the timestamp fits in JS number range easily.