rafcode 1.2.0 → 2.0.0

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.

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