feat: TRD-2026-005 mid-pipeline rebase + TRD-2026-006 Sprint 1-2 foundation

.claude/settings.local.json

@@ -13,5 +13,6 @@
       "Bash(wc:*)",
       "Skill(commit-commands:commit-push-pr)"
     ]
-  }
+  },
+  "outputStyle": "default"
 }

CLAUDE.md

@@ -90,6 +90,47 @@ CLI (commander) -> Dispatcher -> Agent Workers (detached processes)
 
 After finalize: autoMerge triggers immediately → refinery merges to dev → bead closed.
 
+## VCS Backend Abstraction (PRD-2026-004)
+
+Foreman abstracts all VCS operations behind a `VcsBackend` interface so that orchestration code is decoupled from the concrete VCS tool. Two built-in implementations ship with Foreman:
+
+- **`GitBackend`** (`src/lib/vcs/git-backend.ts`) — wraps standard git CLI commands
+- **`JujutsuBackend`** (`src/lib/vcs/jujutsu-backend.ts`) — wraps jj CLI; requires **colocated mode** (`.jj/` + `.git/` both present)
+
+**All orchestration code uses VcsBackend — no direct git/jj calls outside the backend implementations.**
+
+### Key modules
+
+- `src/lib/vcs/interface.ts` — `VcsBackend` interface (25+ methods)
+- `src/lib/vcs/types.ts` — Shared types (`Workspace`, `MergeResult`, `FinalizeCommands`, etc.)
+- `src/lib/vcs/index.ts` — Re-exports + `VcsBackendFactory` (auto-detection + creation)
+- `src/lib/project-config.ts` — `ProjectConfig` loader for `.foreman/config.yaml`
+
+### Configuration precedence
+
+```
+Workflow YAML vcs.backend   (highest priority)
+    ↓
+.foreman/config.yaml vcs.backend
+    ↓
+Auto-detection (.jj/ → jujutsu, .git/ → git)   (lowest priority)
+```
+
+Example `.foreman/config.yaml`:
+
+```yaml
+vcs:
+  backend: jujutsu        # 'git' | 'jujutsu' | 'auto' (default: 'auto')
+  jujutsu:
+    minVersion: "0.21.0"  # validated by 'foreman doctor'
+```
+
+### Documentation
+
+- [VcsBackend Interface Reference](docs/guides/vcs-backend-interface.md) — Method reference, custom backend guide
+- [VCS Configuration Guide](docs/guides/vcs-configuration.md) — Config examples, precedence, troubleshooting
+- [Jujutsu Considerations](docs/guides/jujutsu-considerations.md) — Colocated mode, bookmarks, finalize diffs, migration
+
 ## Development Rules
 
 - **TypeScript strict mode** — no `any` escape hatches

FINALIZE_VALIDATION.md

@@ -0,0 +1,20 @@
+# Finalize Validation: [trd:trd-2026-004-vcs-backend-abstraction:phase:E] Phase E: Configuration and Detection (v0.3-alpha)
+
+## Seed: bd-nuu2
+## Run: ff9d2aae-d56e-4828-b474-10526f417acd
+## Timestamp: 2026-03-28T17:08:50Z
+
+## Rebase
+- Status: SUCCESS
+- Target: origin/dev
+- Note: Feature branch feature/trd-2026-004-vcs-backend-abstraction no longer exists; rebased onto origin/dev instead
+
+## Test Validation
+- Status: PASS
+- Output:
+  - Test Files: 172 passed
+  - Tests: 3125 passed | 2 skipped | 12 todo
+  - Duration: 36.20s
+  - Exit Code: 0
+
+## Verdict: PASS

SESSION_LOG_QA.md

@@ -0,0 +1,31 @@
+## Metadata
+- Date: 2026-03-29
+- Phase: qa
+- Seed: bd-yo2r
+- Run ID: 2d789da8-8313-43f1-b409-6037d11681cd
+
+## Key Activities
+
+1. Verified send-mail skill availability (found at ~/.pi/agent/skills/send-mail/)
+2. Checked for conflict markers in source files — none found (only string literals in test data)
+3. Read TASK.md and EXPLORER_REPORT.md for task context
+4. Read DEVELOPER_REPORT.md and SESSION_LOG.md — developer claims 46 new tests and full implementation
+5. Checked git log and git status — branch `foreman/bd-yo2r` at commit `14db0f2`, nothing to commit
+6. Searched for all claimed implementation files — none exist in source tree
+7. Verified key source files (types.ts, roles.ts, config.ts, pi-sdk-tools.ts) — no troubleshooter code
+8. Checked default.yaml — no onFailure block
+9. Ran full test suite — 3290 tests pass (all pre-existing)
+10. Determined root cause: developer made changes but did not commit to git
+11. Wrote QA_REPORT.md with FAIL verdict
+
+## Artifacts Created
+
+- `QA_REPORT.md` — QA findings with FAIL verdict
+- `SESSION_LOG_QA.md` — This file
+
+## Notes
+
+- The developer's SESSION_LOG.md says "all 46 new tests pass; TypeScript compiles clean" but this is false — the code was never committed
+- The working tree is clean with no uncommitted changes, so the files were either never saved or were somehow lost
+- The developer phase must be re-run entirely
+- The existing test suite is healthy (3290 pass, 0 fail)

SESSION_LOG_REVIEWER.md

@@ -0,0 +1,28 @@
+## Metadata
+- Date: 2026-03-28T15:10:00Z
+- Phase: reviewer
+- Seed: bd-gmzn
+- Run ID: 1a4a8fcf-6748-4e23-bce2-d125077f6f14
+
+## Key Activities
+- Verified `send_mail` tool availability (confirmed present as native Pi SDK tool)
+- Sent phase-started notification to foreman
+- Read TASK.md for task context
+- Read EXPLORER_REPORT.md for architecture/type design context
+- Read QA_REPORT.md (30 tests passed, all ACs covered, no issues)
+- Read DEVELOPER_REPORT.md (no code changes needed, verification-only task)
+- Reviewed `src/lib/vcs/__tests__/types.test.ts` (265 lines, 30 tests, 11 describe blocks)
+- Reviewed `src/lib/vcs/types.ts` for completeness and quality
+- Reviewed `src/lib/vcs/interface.ts` briefly for import consistency
+- Checked for conflict markers in VCS source tree (none found)
+- Read SESSION_LOG.md to understand developer's findings (conflict already resolved)
+- Wrote REVIEW.md with verdict: PASS
+
+## Artifacts Created
+- `REVIEW.md` — Code review with PASS verdict
+
+## Notes
+- This was a verification-only task; no code was authored — only pre-existing code reviewed
+- The test suite is exemplary: thorough, well-named, edge-case-aware
+- Pre-existing failures in merge-queue tests are correctly flagged as out-of-scope
+- No issues found — clean PASS