rafcode 1.3.2 → 2.0.0

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

@@ -0,0 +1,60 @@
+# Task: Update All Pattern Matching and Resolution for 6-Char IDs
+
+## Objective
+Update every regex pattern, folder matching function, and identifier resolution function across the codebase to recognize the new 6-character base36 project ID format.
+
+## Context
+After task 001 changes the ID generation, the rest of the codebase still has regex patterns like `/^(\d{2,3})-/` and `/^([a-z][0-9a-z]{2})-/` that match the old format. These must all be updated to match the new 6-char alphanumeric format (e.g., `00j3k1-project-name`). This is a clean break, so old patterns should be removed entirely.
+
+## Dependencies
+001
+
+## Requirements
+- New project folder pattern: `/^([0-9a-z]{6})-(.+)$/` (6 lowercase alphanumeric chars, hyphen, name)
+- Update all functions in `src/utils/paths.ts` that parse folder names:
+  - `extractProjectNumber()` — match 6-char prefix
+  - `extractProjectName()` — match 6-char prefix, return name after hyphen
+  - `extractTaskNameFromPlanFile()` — this uses task IDs (3-digit like `001`), leave as-is since task numbering within a project hasn't changed
+  - `parseProjectPrefix()` — parse 6-char base36 string
+  - `getProjectDir()` — match 6-char prefix pattern
+  - `listProjects()` — match 6-char prefix pattern
+  - `parseProjectFolder()` — match 6-char prefix pattern
+  - `resolveProjectIdentifierWithDetails()` — update the full folder pattern regex, update identifier detection (no more separate numeric vs base36 paths — all IDs are 6-char base36)
+- Update `src/core/state-derivation.ts`:
+  - `discoverProjects()` — currently only matches `/^(\d{2,3})-/`, must match new 6-char format
+  - `parseDependencies()` — this is about task IDs (like `001`), not project IDs, so leave as-is
+  - Outcome file matching in `deriveProjectState()` — these use task IDs (`/^(\d{2,3})-/` for tasks), leave as-is
+  - Plan file matching in `deriveProjectState()` — same, task IDs, leave as-is
+- Update `src/core/project-manager.ts`:
+  - `readOutcomes()` — uses `/^(\d{2,3})-/` to match task outcomes, this is task ID format, leave as-is
+- Update `src/utils/validation.ts`:
+  - `validateProjectExists()` — update folder matching patterns
+- Update `src/commands/plan.ts`:
+  - Any regex matching existing plan files (line ~582: `/^(\d{2,3})-/`) — this is for task files, leave as-is
+- Update `src/commands/status.ts` and `src/commands/do.ts` — these use `extractProjectNumber()` and `extractProjectName()` which will be updated via paths.ts, but check for any inline regex patterns
+- Update identifier resolution to support:
+  - Full 6-char ID: `00j3k1` → look up by decoded number
+  - Full folder name: `00j3k1-epoch-shift` → exact match
+  - Project name: `epoch-shift` → name match (case-insensitive)
+  - Remove old numeric-only (`3`, `003`) and old 3-char base36 (`a00`) resolution paths
+
+## Implementation Steps
+1. Update all regex patterns in `src/utils/paths.ts` from old numeric/base36 dual patterns to single 6-char pattern
+2. Simplify `resolveProjectIdentifierWithDetails()` — all IDs are now 6-char base36, so the numeric vs base36 branching can be unified
+3. Update `discoverProjects()` in `src/core/state-derivation.ts` to match 6-char prefix
+4. Update `validateProjectExists()` in `src/utils/validation.ts`
+5. Verify that task-level patterns (3-digit IDs like `001`) are untouched
+6. Verify commands (`do.ts`, `status.ts`, `plan.ts`) work with updated utility functions
+
+## Acceptance Criteria
+- [ ] All project folder patterns match `[0-9a-z]{6}-name` format
+- [ ] Task-level patterns (`001`, `002`) remain unchanged
+- [ ] `resolveProjectIdentifierWithDetails()` resolves 6-char IDs and project names
+- [ ] `discoverProjects()` finds projects with new ID format
+- [ ] `validateProjectExists()` works with new format
+- [ ] No old numeric-only or 3-char base36 patterns remain for project IDs
+- [ ] TypeScript compiles with no errors
+
+## Notes
+- Be careful to distinguish between PROJECT IDs (changing to 6-char) and TASK IDs within a project (staying as 3-digit `001`, `002`, etc.). Only project-level patterns change.
+- The `number` field in project interfaces remains a `number` type — it just holds a larger value now (the shifted timestamp).

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

@@ -0,0 +1,48 @@
+# Task: Update Tests for New Epoch-Based ID System
+
+## Objective
+Rewrite all unit tests affected by the project ID format change to test the new 6-character base36 epoch-based ID system.
+
+## Context
+The test suite in `tests/unit/paths.test.ts` (~741 lines) extensively tests the old sequential numbering and base36 encoding. After tasks 001 and 002 change the production code, these tests will all fail. Other test files (`status-command.test.ts`, `plan-command.test.ts`, `do-command.test.ts`) may also have hardcoded project folder names in old format.
+
+## Dependencies
+001, 002
+
+## Requirements
+- Rewrite `tests/unit/paths.test.ts` to cover:
+  - `encodeBase36()` — now encodes any non-negative integer to 6-char zero-padded base36
+  - `decodeBase36()` — inverse of encode
+  - `getNextProjectNumber()` — generates from current timestamp, handles collisions
+  - `formatProjectNumber()` — produces 6-char strings
+  - `extractProjectNumber()` — extracts 6-char prefix from folder names
+  - `extractProjectName()` — extracts name portion after 6-char prefix
+  - `parseProjectPrefix()` — parses 6-char base36 strings
+  - `resolveProjectIdentifierWithDetails()` — test all resolution paths (6-char ID, folder name, project name)
+  - `listProjects()` — lists projects with new format
+  - `discoverProjects()` — discovers projects with new format
+- Update any test fixtures that use old folder names (e.g., `001-test-project` → `00abcd-test-project`)
+- Test collision handling in `getNextProjectNumber()` — mock `Date.now()` and pre-create folders
+- Test edge cases: zero timestamp (epoch start), very large timestamps, invalid format strings
+- Update tests in other test files (`status-command.test.ts`, `plan-command.test.ts`, `do-command.test.ts`) that reference project folder names with old format
+
+## Implementation Steps
+1. Read existing test files to understand current test structure and patterns
+2. Rewrite `tests/unit/paths.test.ts` for the new ID system
+3. Update project folder references in `tests/unit/status-command.test.ts`
+4. Update project folder references in `tests/unit/plan-command.test.ts`
+5. Update project folder references in `tests/unit/do-command.test.ts`
+6. Run all tests and fix any remaining failures
+
+## Acceptance Criteria
+- [ ] All tests in `paths.test.ts` rewritten and passing
+- [ ] Tests cover encode/decode round-trip
+- [ ] Tests cover collision handling
+- [ ] Tests cover identifier resolution (6-char ID, full folder, name)
+- [ ] Tests in other files updated with new folder format
+- [ ] `npm test` passes with all tests green
+- [ ] No references to old folder format (e.g., `001-`, `a00-`) remain in test files for project IDs (task IDs like `001-task.md` within plans/outcomes are fine)
+
+## Notes
+- For time-dependent tests, mock `Date.now()` to return predictable values. E.g., `Date.now = jest.fn(() => (1767225600 + 12345) * 1000)` → ID should be `encodeBase36(12345)` = `"0009ix"`.
+- Remember task IDs within projects still use the `001`, `002` format — only project-level IDs changed.

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

@@ -0,0 +1,44 @@
+# Task: Update Documentation for New ID System
+
+## Objective
+Update CLAUDE.md and README.md to reflect the new epoch-based project ID format.
+
+## Context
+After the code changes, the documentation still references the old sequential numbering system (001-999 numeric, a00-zzz base36). All references need to be updated to describe the new 6-character base36 epoch-based IDs.
+
+## Dependencies
+001, 002
+
+## Requirements
+- Update `CLAUDE.md`:
+  - Project Naming Convention section: describe new epoch-based scheme
+  - Remove references to NNN (001-999) sequential format
+  - Remove references to old base36 (a00-zzz) format
+  - Update "Supports 46,000+ projects" — new system supports 69 years of unique IDs
+  - Update Project Identifier Resolution section: 6-char ID, project name, full folder name
+  - Update example folder names (e.g., `001-fix-bug` → `00abcd-fix-bug`)
+  - Update git commit format examples: `RAF[00abcd:001]`
+  - Update worktree branch name examples
+  - Update RAF Project Structure section with new folder format
+- Update `README.md`:
+  - Update any user-facing references to project ID format
+  - Update example commands and output
+
+## Implementation Steps
+1. Read current CLAUDE.md and identify all sections referencing the old ID format
+2. Update each section with the new 6-char base36 epoch-based format
+3. Read current README.md and update relevant sections
+4. Ensure consistency between CLAUDE.md and README.md
+
+## Acceptance Criteria
+- [ ] No references to old sequential numbering (001-999) for project IDs in docs
+- [ ] No references to old base36 format (a00-zzz) for project IDs in docs
+- [ ] New epoch-based scheme clearly documented
+- [ ] Examples use realistic 6-char IDs
+- [ ] Git commit format examples updated
+- [ ] Project resolution formats documented
+- [ ] Task IDs within projects still shown as 001, 002 format (unchanged)
+
+## Notes
+- Be careful to distinguish between project IDs (changing) and task IDs (staying as 001, 002). Don't accidentally change task ID documentation.
+- The prompts in `src/prompts/` also reference project structure — the amend prompt mentions `NNN` for task references which is about task IDs, not project IDs. The planning prompt shows `001-task-name.md` which is also task format. These should NOT be changed.

package/RAF/ahmpro-merge-guardian/decisions.md

@@ -0,0 +1,25 @@
+# Project Decisions
+
+## Amend commit bug: does it fail only with --worktree or also without?
+Worktree only. The bug only happens when using --amend --worktree.
+
+## Amend commit bug: suspected root cause?
+Needs investigation. Not sure of root cause — the task should investigate the full amend+worktree flow to find the bug.
+
+## Task ID format change: breaking change or backward compatible?
+Breaking change. Update everything to new format, no backward compat needed.
+
+## PR creation: what content should the PR body contain?
+Input.md, key decisions, and outcomes summary combined.
+
+## PR creation: how should the PR body be generated?
+Use Claude (Haiku) to generate a clean PR description from input + decisions + outcomes.
+
+## PR target branch: auto-detect or let user pick?
+Auto-detect base. Automatically use the branch the worktree was forked from (usually main).
+
+## Post-execution picker: when should it appear?
+Remove --merge flag entirely. Always show picker BEFORE worktree tasks execute.
+
+## Post-execution picker: flow after task completion?
+Pre-pick + auto. Pick before execution, auto-perform after success, skip on failure.

package/RAF/ahmpro-merge-guardian/input.md

@@ -0,0 +1,4 @@
+- [ ] if i do amend - input.md and decision.md updates don't get commited. investigate and fix (prev attempt to fix in commit c94558940d232fabcf8023c92867891de3a0dbcc)
+- [ ] make task id two decimal places (01, 02, 03..., a0, a1) same encoding
+- [ ] use gh to create a PR from worktree if possible
+- [ ] add picker for raf do --worktree to chose between --merge or --pr or leave branch options

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>