rafcode 1.2.0 → 2.0.0

package/RAF/ahmpro-merge-guardian/outcomes/001-fix-amend-worktree-commit.md

@@ -0,0 +1,45 @@
+# Outcome: Fix Amend Worktree Commit Bug
+
+## Summary
+
+Fixed the bug where `input.md` and `decisions.md` changes were not committed when running `raf plan --amend --worktree`. The fix addresses two root causes in `commitPlanningArtifacts()`:
+
+1. **Absolute path resolution in worktrees**: Converted file paths from absolute to relative when `cwd` is provided (worktree mode). This avoids potential path resolution mismatches between Node.js and git, particularly on macOS where symlinks (e.g., `/tmp` → `/private/tmp`) can cause absolute paths to not match git's internal worktree path tracking.
+
+2. **All-or-nothing staging failure**: Changed from a single `git add` call with all files to individual `git add` calls per file. Previously, if any single file failed to stage (e.g., missing `decisions.md`), the entire `git add` command failed with exit code 128, meaning NO files were staged — including `input.md` which was always modified.
+
+## Root Cause Analysis
+
+The `commitPlanningArtifacts()` function used absolute paths for `git add` even when operating in a worktree. While this works in simple cases, it can fail when:
+- macOS path symlink resolution causes the absolute path to differ from git's internal representation
+- One file in the batch doesn't exist (e.g., `decisions.md` not yet written by Claude), causing `git add` to fail for ALL files
+
+Evidence: commit `60d6565` ("missed desicions") shows that project 022's amend produced updated `input.md` and `decisions.md` that were never committed by `commitPlanningArtifacts`, requiring a manual commit.
+
+## Changes Made
+
+### `src/core/git.ts`
+- Convert absolute file paths to relative (via `path.relative(cwd, file)`) when `cwd` is provided
+- Stage files individually with separate `git add` calls per file
+- Add per-file error handling so one failed staging doesn't block others
+- Add early return when no files are successfully staged
+
+### `tests/unit/commit-planning-artifacts.test.ts`
+- Updated existing tests for individual `git add` call behavior
+- Added tests for: relative path conversion in worktree mode, absolute paths in standard mode, partial staging failure recovery, total staging failure handling, additional file path conversion in worktree mode
+
+### `tests/unit/commit-planning-artifacts-worktree.test.ts` (new)
+- Real git repo integration tests covering:
+  - Basic worktree commit (input.md + decisions.md)
+  - Amend with additional plan files in worktree
+  - Commit after worktree recreation from branch (the exact bug scenario)
+  - Partial file changes (only some files modified)
+  - Non-worktree standard mode (regression check)
+
+## Test Results
+
+- All 852 tests pass (842 existing + 10 new)
+- Build succeeds with no type errors
+- No regressions in existing functionality
+
+<promise>COMPLETE</promise>

package/RAF/ahmpro-merge-guardian/outcomes/002-base36-task-ids.md

@@ -0,0 +1,55 @@
+# Outcome: Change Task IDs to 2-Character Base36 Format
+
+## Summary
+
+Changed task IDs from 3-digit decimal (001, 002, ..., 999) to 2-character base36 (01, 02, ..., 0a, ..., zz) across the entire codebase, supporting up to 1296 tasks per project.
+
+## Changes Made
+
+### Core Utilities (`src/utils/paths.ts`)
+- Added `TASK_ID_WIDTH = 2` constant
+- Added `TASK_ID_PATTERN = '[0-9a-z]{2}'` exported regex pattern
+- Added `encodeTaskId(num)` function: converts number to 2-char zero-padded base36 string
+- Added `decodeTaskId(str)` function: converts 2-char base36 string back to number (returns null if invalid)
+- Updated `extractTaskNameFromPlanFile` regex from `\d{2,3}` to `[0-9a-z]{2}`
+
+### State Derivation (`src/core/state-derivation.ts`)
+- Updated `parseDependencies` filter to use `TASK_ID_PATTERN` regex
+- Updated outcome file and plan file parsing regexes from `\d{2,3}` to `TASK_ID_PATTERN`
+
+### Project Manager (`src/core/project-manager.ts`)
+- Updated `readOutcomes` regex to use `TASK_ID_PATTERN`
+
+### Plan Command (`src/commands/plan.ts`)
+- Updated `maxTaskNumber` calculation to use `decodeTaskId()` instead of `parseInt()`
+- Updated new plan file detection regex to use `TASK_ID_PATTERN` and `decodeTaskId()`
+- Updated amend template task numbering to use `encodeTaskId()`
+
+### Prompt Templates
+- **execution.ts**: Changed commit message format from 3-digit padStart to 2-char base36 encoding
+- **planning.ts**: Updated all plan file examples (001 -> 01), dependency format examples (001, 002 -> 01, 02), numbering rule (001, 002, 003 -> 01, 02, 03)
+- **amend.ts**: Updated all task numbering to use `encodeTaskId()`, updated dependency format examples
+
+### Comments Updated
+- **claude-runner.ts**: Updated commit message examples (RAF[005:001] -> RAF[005:01])
+- **git.ts**: Updated stash name example
+
+### Documentation (`CLAUDE.md`)
+- Updated project structure examples to show 2-char task IDs
+- Added "Task ID Format" section to architectural decisions
+- Updated dependencies format and git commit examples
+
+### Test Files (25+ files updated)
+All test fixtures updated to use 2-char base36 task IDs in plan/outcome filenames, task ID assertions, dependency strings, commit messages, and prompt expectations. Key patterns changed:
+- Plan filenames: `001-task.md` -> `01-task.md`
+- Task IDs: `'001'` -> `'01'`
+- Commit messages: `RAF[005:001]` -> `RAF[005:01]`
+- Dependencies: `001, 002` -> `01, 02`
+
+## Test Results
+
+- All 853 tests pass (42 test suites)
+- Build succeeds with no type errors
+- No regressions
+
+<promise>COMPLETE</promise>

package/RAF/ahmpro-merge-guardian/outcomes/003-worktree-pr-creation.md

@@ -0,0 +1,41 @@
+# Outcome: Add PR Creation from Worktree
+
+## Summary
+
+Added a reusable `src/core/pull-request.ts` module that creates GitHub Pull Requests from worktree branches using the `gh` CLI tool, with Claude Haiku-generated PR bodies.
+
+## Changes Made
+
+### New Module: `src/core/pull-request.ts`
+- **`createPullRequest(branch, projectPath, options?)`**: Main entry point - runs preflight checks, detects base branch, auto-pushes branch, generates PR body via Claude Haiku, and calls `gh pr create`
+- **`prPreflight(branch, cwd?)`**: Validates prerequisites - gh CLI installed, authenticated, GitHub remote present, branch push status
+- **`generatePrBody(projectPath, timeoutMs?)`**: Reads input.md, decisions.md, and outcome files, then calls Claude Haiku to generate a summary. Falls back to simple body if Claude is unavailable
+- **`generatePrTitle(projectPath)`**: Converts project name from kebab-case to human-readable (e.g., "merge-guardian" -> "Merge guardian")
+- **`detectBaseBranch(cwd?)`**: Auto-detects base branch from `refs/remotes/origin/HEAD`, falling back to checking `main` then `master`
+- **`readProjectContext(projectPath)`**: Reads input.md, decisions.md, and outcome files for context
+- Helper functions: `isGhInstalled()`, `isGhAuthenticated()`, `isGitHubRemote()`, `isBranchPushed()`, `pushBranch()`
+- All git-related functions accept optional `cwd` parameter for worktree support
+
+### New Tests: `tests/unit/pull-request.test.ts`
+- 43 tests covering all exported functions
+- Tests for: gh CLI detection, authentication check, GitHub remote detection, branch push status, base branch detection (with fallback chain), preflight checks, PR title generation, project context reading, PR body generation (with Claude fallback), full PR creation flow (success, failures, cwd passthrough)
+- Follows existing mock patterns: `jest.unstable_mockModule()` for ESM, mocks `child_process`, `fs`, `logger`
+
+### Documentation: `CLAUDE.md`
+- Added "PR Creation from Worktree" section under Architectural Decisions
+
+## Test Results
+
+- All 896 tests pass (43 test suites)
+  - 853 existing tests: passing
+  - 43 new tests: passing
+- Build succeeds with no type errors
+
+## Notes
+
+- This module is a standalone utility - it will be consumed by the post-execution picker (task 004)
+- PR body generation uses Claude Haiku for cost efficiency, with a configurable timeout (default 60s)
+- If Claude CLI is unavailable, falls back to a simple body with project input and task count
+- Branch is automatically pushed to origin if not already pushed before PR creation
+
+<promise>COMPLETE</promise>

package/RAF/ahmpro-merge-guardian/outcomes/004-post-execution-picker.md

@@ -0,0 +1,53 @@
+# Outcome: Add Post-Execution Picker for Worktree Mode
+
+## Summary
+
+Replaced the `--merge` CLI flag with an interactive post-execution picker shown before task execution in worktree mode. Users now choose upfront what happens after tasks complete: merge, create PR, or leave the branch.
+
+## Changes Made
+
+### `src/commands/do.ts`
+- Removed `--merge` Commander.js option
+- Added `PostExecutionAction` type (`'merge' | 'pr' | 'leave'`)
+- Added `pickPostExecutionAction()` — interactive picker using `@inquirer/prompts` `select`, shown before task execution begins
+  - If "Create PR" is chosen, runs `prPreflight()` immediately; falls back to "leave" if preflight fails (e.g., `gh` not installed)
+- Added `executePostAction()` — dispatches the chosen action after all tasks succeed:
+  - **merge**: cleans up worktree, merges branch into original (same behavior as old `--merge`)
+  - **pr**: creates GitHub PR via `createPullRequest()` from task 003's module; preserves worktree for follow-up
+  - **leave**: cleans up worktree directory (branch preserved)
+- Refactored post-execution flow: old `mergeMode` boolean replaced with `postAction` variable
+- On failure, skips post-action with informational message (only for non-leave actions)
+- Added import for `createPullRequest` and `prPreflight` from `pull-request.ts`
+
+### `src/types/config.ts`
+- Removed `merge?: boolean` from `DoCommandOptions` interface
+
+### `tests/unit/post-execution-picker.test.ts` (new)
+- 16 tests covering:
+  - Picker presents three choices with correct labels and values
+  - Returns correct action for each choice
+  - PR preflight runs only for PR choice
+  - Falls back to "leave" when PR preflight fails
+  - Branch name extracted from worktree path for picker message
+  - Action dispatch logic: merge cleans up, PR preserves worktree, leave cleans up
+  - Action skip logic on failure (skip for merge/PR, silent for leave)
+
+### `tests/unit/worktree-integration.test.ts`
+- Replaced `--merge requires --worktree` test section with `post-execution picker is worktree-only` tests
+- Tests verify picker is shown only when worktreeMode && worktreeRoot are both set
+
+### `tests/unit/do-worktree-cleanup.test.ts`
+- Updated comment block to describe new cleanup flow (post-action based instead of `--merge` based)
+
+### `CLAUDE.md`
+- Updated Worktree Mode section: replaced `--merge` documentation with post-execution picker documentation
+- Documented three picker options, preflight behavior, cleanup rules, and exported symbols
+
+## Test Results
+
+- All 912 tests pass (44 test suites)
+  - 896 existing tests: passing
+  - 16 new tests: passing
+- Build succeeds with no type errors
+
+<promise>COMPLETE</promise>

package/RAF/ahmpro-merge-guardian/plans/001-fix-amend-worktree-commit.md

@@ -0,0 +1,39 @@
+# Task: Fix Amend Worktree Commit Bug
+
+## Objective
+Fix the bug where input.md and decisions.md changes are not committed when running `raf plan --amend --worktree`.
+
+## Context
+When amending a project in worktree mode, the updated input.md and decisions.md files are not being committed. The previous fix attempt (commit c94558940d) added `additionalFiles` and `isAmend` support to `commitPlanningArtifacts()`, but the bug persists specifically in the worktree scenario. The non-worktree amend flow works correctly.
+
+The root cause is unknown and requires investigation of the full amend+worktree flow — specifically how the worktree is recreated from an existing branch, how file paths are resolved, and how `cwd` is passed through to git commit operations.
+
+## Requirements
+- Investigate the amend+worktree flow end-to-end: worktree recreation, file writing, path resolution, and git commit
+- Identify why input.md and decisions.md changes aren't staged/committed in worktree mode
+- Fix the root cause (likely a path or cwd mismatch between where files are written and where git operates)
+- Verify the fix works for both: fresh worktree creation and worktree recreation from existing branch
+- Ensure the non-worktree amend flow remains unaffected
+
+## Implementation Steps
+1. Trace the amend+worktree flow in `src/commands/plan.ts` — follow the code path when both `--amend` and `--worktree` flags are set
+2. Check how the worktree is recreated (from branch vs fresh) and where the project folder ends up
+3. Examine how `commitPlanningArtifacts()` receives the `cwd` parameter in the amend+worktree case
+4. Verify that the project path passed to `commitPlanningArtifacts()` matches the actual worktree location where files were written
+5. Add or fix the `cwd` parameter passing so git operations run inside the worktree
+6. Write tests covering the amend+worktree commit scenario
+7. Manually verify with a real amend+worktree flow if possible
+
+## Acceptance Criteria
+- [ ] Root cause identified and documented in the outcome
+- [ ] input.md and decisions.md changes are committed during amend+worktree operations
+- [ ] New plan files are also committed correctly (regression check)
+- [ ] Non-worktree amend flow still works
+- [ ] Tests added covering the amend+worktree commit path
+- [ ] All existing tests pass
+
+## Notes
+- Previous fix attempt: commit c94558940d232fabcf8023c92867891de3a0dbcc
+- Key files: `src/commands/plan.ts`, `src/core/git.ts` (commitPlanningArtifacts), `src/core/worktree.ts`
+- The worktree root path is `~/.raf/worktrees/<repo-basename>/<project-folder>/`
+- Pay attention to the difference between the project path inside the worktree vs the worktree root — git operations need the worktree root as cwd, while file paths are relative to the project folder inside it

package/RAF/ahmpro-merge-guardian/plans/002-base36-task-ids.md

@@ -0,0 +1,43 @@
+# Task: Change Task IDs to 2-Character Base36 Format
+
+## Objective
+Replace the current 3-digit decimal task IDs (001, 002, ..., 999) with 2-character base36 IDs (01, 02, ..., 09, 0a, 0b, ..., 0z, 10, ..., zz) supporting up to 1296 tasks per project.
+
+## Context
+The project already uses base36 encoding for project IDs (6-char epoch-based). This change extends the same encoding philosophy to task IDs, making them shorter and consistent. This is a breaking change — no backward compatibility with old 3-digit decimal IDs is needed.
+
+## Requirements
+- Task IDs become 2-character base36, zero-padded (e.g., `01`, `0a`, `1z`, `zz`)
+- All file naming uses this format: `01-task-name.md`, `0a-task-name.md`, etc.
+- All regex patterns that match task IDs must be updated from `\d{2,3}` to a base36-aware pattern
+- Git commit format updates: `RAF[NNN:01]` instead of `RAF[NNN:001]`
+- Plan file dependencies section uses new format: `01, 02` instead of `001, 002`
+- State derivation, task parsing, and all consumers of task IDs must be updated
+- The encoding should reuse or mirror the existing base36 utilities in `src/utils/paths.ts`
+
+## Implementation Steps
+1. Add task ID encoding/decoding utilities — convert between numeric index and 2-char base36 string (reuse `encodeBase36`/`decodeBase36` pattern from paths.ts, but with width=2)
+2. Update plan file naming: change all references from 3-digit to 2-char base36 format
+3. Update task ID extraction regex throughout the codebase — search for patterns like `/^\d{2,3}-/`, `/^(\d{2,3})-/`, `\d{3}` and replace with base36-aware patterns
+4. Update `state-derivation.ts` — task ID parsing, dependency parsing, sorting logic
+5. Update `plan.ts` — next task number calculation, plan file creation, amend task numbering
+6. Update `do.ts` — task ID display, commit message formatting
+7. Update prompt templates — any system prompts that reference task ID format
+8. Update all test fixtures and test expectations to use new format
+9. Update CLAUDE.md documentation for the new task ID format
+
+## Acceptance Criteria
+- [ ] Task IDs use 2-character base36 format everywhere
+- [ ] Plan files created as `01-task-name.md`, `02-task-name.md`, etc.
+- [ ] State derivation correctly parses new task ID format
+- [ ] Dependencies section uses new format
+- [ ] Git commit messages use new format: `RAF[NNN:01]`
+- [ ] All existing tests updated and passing
+- [ ] CLAUDE.md updated with new task ID format documentation
+
+## Notes
+- Base36 charset: 0-9, a-z (lowercase)
+- 2-char base36 supports 00-zz = 1296 values (more than enough)
+- Sort order: 00, 01, ..., 09, 0a, 0b, ..., 0z, 10, 11, ..., zz
+- Task numbering still starts at 01 (not 00)
+- Key files to modify: `src/utils/paths.ts`, `src/core/state-derivation.ts`, `src/commands/plan.ts`, `src/commands/do.ts`, `src/prompts/` (system prompts), test files

package/RAF/ahmpro-merge-guardian/plans/003-worktree-pr-creation.md

@@ -0,0 +1,43 @@
+# Task: Add PR Creation from Worktree
+
+## Objective
+Add the ability to create a GitHub Pull Request from a worktree branch using the `gh` CLI tool.
+
+## Dependencies
+002
+
+## Context
+Currently, after completing tasks in a worktree, the only automated option is merging the branch back. This task adds PR creation as an alternative workflow. The PR body should be a Claude-generated summary combining the project's input.md, key decisions, and task outcomes.
+
+## Requirements
+- Use `gh pr create` CLI command to create PRs
+- Auto-detect the base branch (the branch the worktree was forked from, typically main)
+- PR title derived from the project name (human-readable, from the folder name)
+- PR body generated by Claude (Haiku model) summarizing: input.md content, key decisions from decisions.md, and outcomes from completed tasks
+- Handle errors gracefully: `gh` not installed, not authenticated, repo not on GitHub, etc.
+- The PR creation function should be a reusable utility in `src/core/` that the `do` command can call
+
+## Implementation Steps
+1. Create a new module `src/core/pull-request.ts` with the PR creation logic
+2. Implement base branch detection — determine which branch the worktree was forked from (likely stored or derivable from git)
+3. Implement PR body generation — read input.md, decisions.md, and outcome files, then call Claude Haiku to generate a clean summary
+4. Implement the `gh pr create` call — construct the command with title, body, base branch, and head branch
+5. Add error handling for common failure modes (gh not installed, auth issues, non-GitHub remote)
+6. Add prerequisite check: verify `gh` CLI is available and authenticated before attempting PR creation
+7. Write tests for the PR creation module (mock `gh` CLI calls)
+
+## Acceptance Criteria
+- [ ] PR creation works from a worktree branch
+- [ ] PR title is clean and derived from project name
+- [ ] PR body is a Claude-generated summary of input + decisions + outcomes
+- [ ] Base branch is auto-detected correctly
+- [ ] Graceful error handling when gh is not available or not authenticated
+- [ ] Tests cover the PR creation flow
+- [ ] All existing tests pass
+
+## Notes
+- The `gh` CLI must be installed and authenticated (`gh auth status`) for this to work
+- PR body generation uses Claude Haiku for cost efficiency
+- The head branch name is the project folder name (e.g., `021b5g-merge-guardian`)
+- This module will be consumed by the post-execution picker (task 004)
+- Consider adding a check that the branch has been pushed to the remote before creating the PR — `gh pr create` may handle this automatically

package/RAF/ahmpro-merge-guardian/plans/004-post-execution-picker.md

@@ -0,0 +1,51 @@
+# Task: Add Post-Execution Picker for Worktree Mode
+
+## Objective
+Replace the `--merge` flag with an interactive picker shown before task execution that lets users choose what to do with the worktree branch after tasks complete: merge, create PR, or leave the branch.
+
+## Dependencies
+001, 003
+
+## Context
+Currently `raf do --worktree --merge` is the only way to handle the branch after execution. This task replaces that with a better UX: an interactive picker shown before execution starts, so the user declares intent upfront. After all tasks succeed, the chosen action is performed automatically. On failure, the action is skipped.
+
+## Requirements
+- Remove the `--merge` CLI flag from the `do` command
+- When `--worktree` is used, show an interactive picker before task execution begins with three options:
+  1. **Merge** — merge the worktree branch into the original branch (existing behavior)
+  2. **Create PR** — push the branch and create a GitHub PR (uses task 003's PR creation module)
+  3. **Leave branch** — do nothing, keep the worktree branch as-is
+- Store the user's choice and execute it automatically after all tasks complete successfully
+- If any task fails, skip the post-execution action and inform the user
+- The picker should use the existing interactive selection pattern used elsewhere in RAF (or a simple numbered prompt if no pattern exists)
+
+## Implementation Steps
+1. Remove the `--merge` flag from the `do` command's Commander.js option definition
+2. Add the interactive picker UI — display the three options and capture user choice before task execution loop starts
+3. Refactor the merge logic: extract the existing merge code into a callable function if not already
+4. After the task execution loop completes, check if all tasks succeeded
+5. If successful, execute the chosen action: call merge function, PR creation function, or do nothing
+6. If failed, log that the post-execution action was skipped due to failures
+7. Update any documentation or help text referencing `--merge`
+8. Write tests for the picker flow and post-execution action dispatch
+9. Update CLAUDE.md to document the new workflow
+
+## Acceptance Criteria
+- [ ] `--merge` flag is removed from `raf do`
+- [ ] Interactive picker appears before task execution when `--worktree` is used
+- [ ] Picker offers three options: merge, create PR, leave branch
+- [ ] Chosen action executes automatically after all tasks succeed
+- [ ] Action is skipped with a message when tasks fail
+- [ ] PR creation option works end-to-end (push + create PR)
+- [ ] Merge option works as before
+- [ ] Leave branch option does nothing (clean exit)
+- [ ] Tests cover picker logic and action dispatch
+- [ ] All existing tests pass
+- [ ] CLAUDE.md updated
+
+## Notes
+- The picker must appear BEFORE execution starts (user's explicit requirement)
+- For the PR option, the branch needs to be pushed to remote first — handle this as part of the PR creation flow
+- Consider what happens if the user picks PR but `gh` is not installed — detect early and fall back or warn
+- The existing merge logic in `do.ts` (lines ~356-377) should be preserved but made callable independently
+- Worktree cleanup behavior should match the chosen action: cleanup after merge, preserve for PR and leave-branch

package/RAF/ahnbcu-letterjam/decisions.md

@@ -0,0 +1,13 @@
+# Project Decisions
+
+## Should task IDs also switch to pure letters (base26)?
+Only project IDs. Task IDs stay base36 (0-9a-z, 2-char).
+
+## What should the ID width be?
+6 characters, padded with 'a' (the base26 zero-equivalent). So a=0, b=1, ..., z=25. Value 0 = "aaaaaa", value 1 = "aaaaab", value 26 = "aaaaba". This gives 26^6 = ~308M values (~9.8 years from epoch).
+
+## How should existing projects with old ID formats be handled?
+A `raf migrate` CLI command that renames old project folders to new base26 encoding. Should support both old sequential 3-char base36 IDs (e.g., "007-project") and current 6-char base36 IDs (e.g., "021h44-project").
+
+## Should old IDs be auto-detected transparently in resolution?
+No — the migrate command is the transition path. After migration, only base26 IDs are recognized.

package/RAF/ahnbcu-letterjam/input.md

@@ -0,0 +1,3 @@
+switch project ids to  **pure letters** (base26, a-z only) — no digits to confuse natural sort.
+    we still encode seconds from jan 1 2026
+prev work on the topic base36 in commit f3a88aeead9549be7ff52ac50a197ddd42128bf0

package/RAF/ahnbcu-letterjam/outcomes/01-base26-encoding.md

@@ -0,0 +1,42 @@
+# Outcome: Base26 Encoding Migration
+
+## Summary
+
+Replaced base36 (0-9a-z) project ID encoding with base26 (a-z only) encoding across the entire codebase. Project IDs now contain only lowercase letters, making them visually distinct from task IDs (which remain base36) and sorting naturally as strings.
+
+## Key Changes
+
+### Source Files
+- **`src/utils/paths.ts`** — Core implementation:
+  - Added `BASE26_ALPHABET` constant (`'abcdefghijklmnopqrstuvwxyz'`)
+  - Replaced `encodeBase36()` → `encodeBase26()` with custom a-z encoding (a=0, b=1, ..., z=25)
+  - Replaced `decodeBase36()` → `decodeBase26()` with matching decoder
+  - Replaced `isBase36Prefix()` → `isBase26Prefix()` using `/^[a-z]{6}$/`
+  - Updated `formatProjectNumber()` to call `encodeBase26()`
+  - Updated all regex patterns from `[0-9a-z]{6}` to `[a-z]{6}`
+- **`src/core/state-derivation.ts`** — Updated import and regex for project discovery
+- **`src/utils/validation.ts`** — Updated regex for project validation
+
+### Test Files (12 files updated)
+- `tests/unit/paths.test.ts` — Rewrote encode/decode/prefix tests with base26 values
+- `tests/unit/project-manager.test.ts` — Updated regex and imports
+- `tests/unit/status-command.test.ts` — Updated all hardcoded folder names
+- `tests/unit/do-command.test.ts` — Updated folder name references
+- `tests/unit/plan-command.test.ts` — Updated folder name references
+- `tests/unit/state-derivation.test.ts` — Updated folder names
+- `tests/unit/project-picker.test.ts` — Updated folder names and display strings
+- `tests/unit/post-execution-picker.test.ts` — Updated folder names
+- `tests/unit/commit-planning-artifacts.test.ts` — Updated expected commit messages
+- `tests/unit/commit-planning-artifacts-worktree.test.ts` — Updated expected commit messages
+- `tests/unit/pull-request.test.ts` — Updated folder names with digit-free prefixes
+
+## Verification
+- Build: `npm run build` passes cleanly
+- Tests: All 913 tests pass across 44 test suites
+
+## Notes
+- Task IDs remain base36 (2-char, 0-9a-z) — unchanged
+- RAF_EPOCH constant unchanged (1767225600)
+- Encoding examples: 0→"aaaaaa", 1→"aaaaab", 25→"aaaaaz", 26→"aaaaba", 1000→"aaabmm"
+
+<promise>COMPLETE</promise>

package/RAF/ahnbcu-letterjam/outcomes/02-update-tests.md

@@ -0,0 +1,38 @@
+# Outcome: Update Tests for Base26 Project ID Encoding
+
+## Summary
+
+Updated all remaining test files to use base26 (a-z only) project ID prefixes and nomenclature, completing the migration started in task 01. Added edge case tests for max value encoding/decoding.
+
+## Key Changes
+
+### Test Files Updated (11 files)
+
+- **`tests/unit/execution-prompt.test.ts`** — Replaced digit-containing project numbers (`005`, `001`, `a0b`) with valid base26 prefixes (`aaabmm`, `aaaaab`, `abcdef`). Updated all project paths accordingly. Renamed test "base36 prefix" → "base26 prefix" and "base36 project" → "base26 project".
+- **`tests/unit/plan-command.test.ts`** — Renamed describe block "Base36 Project Resolution for Amend" → "Base26 Project Resolution for Amend".
+- **`tests/unit/worktree.test.ts`** — Replaced `020-worktree-weaver` → `abaaba-worktree-weaver`, `021-another-feature` → `ababab-another-feature`, `022-prune-cycle` → `abcabc-prune-cycle`, `001-feature` → `aaaaab-feature`. Renamed test "base36 project IDs" → "base26 project IDs".
+- **`tests/unit/plan-amend-worktree-recreate.test.ts`** — Replaced `022-my-project` → `abcabc-my-project` throughout.
+- **`tests/unit/do-worktree-cleanup.test.ts`** — Replaced `022-prune-cycle` → `abcabc-prune-cycle` throughout.
+- **`tests/unit/do-rerun.test.ts`** — Replaced `001-test-project` → `aaaaab-test-project`.
+- **`tests/unit/dependency-integration.test.ts`** — Replaced `001-test-project` → `aaaaab-test-project`.
+- **`tests/unit/do-blocked-tasks.test.ts`** — Replaced `001-test-project` → `aaaaab-test-project`.
+- **`tests/unit/state-derivation.test.ts`** — Replaced `001-test-project` → `aaaaab-test-project` (kept `001-too-short` as it tests invalid format rejection).
+- **`tests/unit/worktree-integration.test.ts`** — Replaced `020-test-project` → `abaaba-test-project`.
+- **`tests/unit/git-stash.test.ts`** — Replaced `raf-001-task-3-failed` → `raf-aaaaab-task-3-failed` and `raf-002-task-5-failed` → `raf-aaaaac-task-5-failed`.
+
+### New Edge Case Tests Added (in `paths.test.ts`)
+
+- `encodeBase26(26^6 - 1)` → `'zzzzzz'` (max 6-char value)
+- `encodeBase26(26^5)` → `'baaaaa'` (boundary value)
+- `decodeBase26('zzzzzz')` → `26^6 - 1` (max value decode)
+- Roundtrip test now includes max value `26^6 - 1`
+
+## Verification
+
+- Build: `npm run build` passes cleanly
+- Tests: All 916 tests pass across 44 test suites (3 new edge case tests added)
+- No skipped or commented-out tests
+- No remaining digit-containing project ID prefixes in test fixtures (except intentional rejection tests)
+- All remaining "base36" references in tests are about task IDs (which correctly remain base36)
+
+<promise>COMPLETE</promise>

package/RAF/ahnbcu-letterjam/outcomes/03-migrate-command.md

@@ -0,0 +1,51 @@
+# Outcome: Add `raf migrate-project-ids-base26` CLI Command
+
+## Summary
+
+Added a new CLI command `raf migrate-project-ids-base26` that renames existing project folders from legacy ID formats (3-char base36 or 6-char base36-with-digits) to the new 6-char base26 encoding.
+
+## Key Changes
+
+### Source Files
+
+- **`src/commands/migrate.ts`** (new) — Core migrate command implementation:
+  - `detectMigrations(dirPath)` — Scans a directory for legacy project folders and computes rename mappings
+  - Detects two legacy patterns: 3-char base36 (`[0-9a-z]{3}-<name>`) and 6-char base36 with digits (`[0-9a-z]{6}-<name>` where prefix contains a digit)
+  - Skips already-migrated base26 folders (`[a-z]{6}-`)
+  - Collision detection (multiple old IDs mapping to same base26 ID)
+  - Existing-target conflict detection
+  - `--dry-run` flag for preview without renaming
+  - `--worktree` flag to scan worktree RAF directories
+  - Summary output showing `oldName -> newName` for each migration
+  - Exported `MigrationEntry` interface and `detectMigrations()` for testability
+
+- **`src/index.ts`** — Registered the new command via `program.addCommand(createMigrateCommand())`
+
+- **`src/types/config.ts`** — Added `MigrateCommandOptions` interface with `dryRun` and `worktree` fields
+
+### Test Files
+
+- **`tests/unit/migrate-command.test.ts`** (new) — 15 tests covering:
+  - Detection of 3-char base36 legacy folders
+  - Detection of 6-char base36 legacy folders with digits
+  - Skipping already-migrated base26 folders
+  - Skipping non-directory entries and non-existent directories
+  - Mixed legacy and migrated folder handling
+  - Correct path generation
+  - Edge cases (000, zzz prefixes; folders without hyphens; mixed alpha-digit 6-char prefixes)
+  - Integration tests for rename execution with content preservation
+  - Encoding correctness verification
+
+## Verification
+
+- Build: `npm run build` passes cleanly
+- Tests: All 931 tests pass across 45 test suites (15 new tests added)
+
+## Notes
+
+- Branch renaming is out of scope — only folder renames are performed
+- Worktree scanning looks for RAF directories inside each worktree subdirectory
+- 3-char base36 IDs (e.g., 007=7) map to small base26 values (e.g., "aaaaah")
+- 6-char base36 epoch IDs map to larger but valid base26 values
+
+<promise>COMPLETE</promise>

package/RAF/ahnbcu-letterjam/outcomes/04-update-documentation.md

@@ -0,0 +1,29 @@
+# Outcome: Update Documentation for Base26 Project IDs
+
+## Summary
+
+Updated CLAUDE.md and README.md to reflect the base26 project ID encoding and document the new `raf migrate-project-ids-base26` command.
+
+## Key Changes
+
+### CLAUDE.md
+- **RAF Project Structure**: Changed example folder from `00j3k1-project-name` (base36) to `abcdef-project-name` (base26), updated comment
+- **Project Naming Convention**: Updated encoding description from base36 to base26, documented `a=0, b=1, ..., z=25` scheme, noted left-padding with 'a', added note about visual distinction from task IDs
+- **Project Identifier Resolution**: Updated examples from `00j3k1` to `abcdef`, changed "Base36 ID" to "Base26 ID"
+- **Git Commit Schema**: Updated example project IDs from `00j3k1`/`00k5m2` to `abcdef`/`abaaba`
+- **Worktree Mode**: Updated example paths and branch names from `00j3k1-my-feature` to `abcdef-my-feature`
+- **Migration Command** (new section): Documented `raf migrate-project-ids-base26` with its options, legacy pattern detection, and implementation location
+
+### README.md
+- **Project Structure**: Changed description from "base36 IDs" to "base26 IDs (a-z only)", updated example folders from `00j3k1-auth-system`/`00k5m2-dashboard` to `abcdef-auth-system`/`abaaba-dashboard`
+- **Commands section**: Added `raf migrate-project-ids-base26` with usage examples
+- **Command Reference**: Added option table for migrate command (`--dry-run`, `--worktree`)
+- **All examples**: Replaced all `00j3k1` occurrences with `abcdef` (plan, do, status commands)
+- **Worktree section**: Updated branch name example to `abcdef-my-feature`
+
+## Verification
+- All remaining "base36" references in docs correctly refer to task IDs (which remain base36) or legacy formats in the migration command docs
+- No digit-containing project ID examples remain (except in migration command docs showing legacy formats)
+- Task ID documentation unchanged (correctly remains base36)
+
+<promise>COMPLETE</promise>

package/RAF/ahnbcu-letterjam/plans/01-base26-encoding.md

@@ -0,0 +1,36 @@
+# Task: Replace base36 project ID encoding with base26 (a-z only)
+
+## Objective
+Replace the base36 (0-9a-z) project ID encoding with base26 (a-z only) so project IDs contain only letters and sort naturally.
+
+## Context
+Project IDs currently use base36 encoding (digits + letters), which confuses natural sort ordering. Switching to pure letters (a-z) eliminates this problem. Task IDs remain base36 unchanged. Prior work on the base36 system is in commit f3a88aeead9549be7ff52ac50a197ddd42128bf0.
+
+## Requirements
+- Base26 alphabet: a=0, b=1, c=2, ..., z=25
+- ID width: 6 characters, padded with 'a' (the zero-equivalent)
+- Examples: 0 → "aaaaaa", 1 → "aaaaab", 25 → "aaaaaz", 26 → "aaaaba"
+- Maximum value: 26^6 - 1 = 308,915,775 (~9.8 years from RAF epoch 2026-01-01)
+- Task IDs stay base36 (2-char, 0-9a-z) — do NOT modify task ID functions
+- RAF_EPOCH constant stays the same (1767225600)
+
+## Implementation Steps
+1. In `src/utils/paths.ts`, replace `encodeBase36()` with a base26 encoder (a-z alphabet, 6-char, 'a'-padded). Rename to reflect the new encoding.
+2. Replace `decodeBase36()` with the corresponding base26 decoder. Rename accordingly.
+3. Update `isBase36Prefix()` to validate `[a-z]{6}` instead of `[0-9a-z]{6}`. Rename.
+4. Update `formatProjectNumber()` to call the new encoder.
+5. Update all regex patterns across the codebase from `[0-9a-z]{6}` to `[a-z]{6}` — these appear in `paths.ts`, `state-derivation.ts`, `validation.ts`, and `git.ts`.
+6. Update all function names and references across importers — search for `encodeBase36`, `decodeBase36`, `isBase36Prefix` in all source files.
+7. Update JSDoc comments and inline documentation to say "base26" instead of "base36" for project IDs.
+
+## Acceptance Criteria
+- [ ] `encodeBase36` / `decodeBase36` / `isBase36Prefix` replaced with base26 equivalents
+- [ ] All project ID regex patterns updated to `[a-z]{6}`
+- [ ] `getNextProjectNumber()` generates base26 IDs
+- [ ] Task ID functions (`encodeTaskId`, `decodeTaskId`, `TASK_ID_PATTERN`) remain untouched
+- [ ] Project builds without errors (`npm run build`)
+
+## Notes
+- The encoding is NOT standard `toString(26)`. It uses a custom a-z alphabet (not 0-9a-p).
+- `parseInt(str, 26)` won't work for decoding because JS base26 uses 0-9a-p, not a-z. Implement custom encode/decode.
+- Only project IDs change. Task IDs, RAF_EPOCH, and the overall folder structure stay the same.

package/RAF/ahnbcu-letterjam/plans/02-update-tests.md

@@ -0,0 +1,37 @@
+# Task: Update tests for base26 project ID encoding
+
+## Objective
+Update all unit and integration tests to reflect the base36-to-base26 encoding change for project IDs.
+
+## Context
+After task 01 changes the core encoding functions, all existing tests that reference base36 project IDs will fail. Test fixtures, expected values, and regex patterns need updating. Task ID tests should remain unchanged.
+
+## Dependencies
+01
+
+## Requirements
+- All test cases for encode/decode functions updated with base26 expected values
+- Test fixtures using project folder names (e.g., "00abc0-project") updated to base26 format (e.g., "aabcda-project" or similar valid base26 IDs)
+- Regex pattern assertions updated from `[0-9a-z]{6}` to `[a-z]{6}`
+- Task ID test cases remain untouched
+- Edge cases covered: zero value ("aaaaaa"), max value, boundary values, invalid inputs (digits should be rejected)
+
+## Implementation Steps
+1. Update `tests/unit/paths.test.ts` — rewrite `encodeBase36`/`decodeBase36` test suites for the new base26 functions with correct expected values.
+2. Update `isBase36Prefix` tests → validate new prefix checker rejects digits, accepts pure a-z.
+3. Update `extractProjectNumber`, `extractProjectName`, `parseProjectPrefix` tests with base26 folder name fixtures.
+4. Update `resolveProjectIdentifier` tests — all project folder fixtures must use base26 prefixes.
+5. Update `getNextProjectNumber` tests — expected IDs should be base26 encoded.
+6. Update `listProjects` tests if they have base36 fixtures.
+7. Search all other test files for hardcoded project IDs (grep for patterns like `[0-9a-z]{6}-` or specific IDs like "00abc0") and update them.
+8. Run full test suite and ensure all tests pass.
+
+## Acceptance Criteria
+- [ ] All 40+ test suites pass (`npm test`)
+- [ ] No test references old base36 project ID format (except task ID tests which stay base36)
+- [ ] Edge cases covered: zero encoding, max value, invalid characters (digits), wrong length
+- [ ] No skipped or commented-out tests
+
+## Notes
+- The main test file is `tests/unit/paths.test.ts` (~525 lines) but other test files may contain project ID fixtures too.
+- New base26 encode/decode cannot use `parseInt`/`toString` — verify tests check the custom implementation correctly.