docs(symphony): add handover and V-model reports for three orchestration runs

Handover documents for tlaplus-ts (8 issues), rust-genai (10 issues),
and terraphim-private (9 issues) Symphony runs. Includes verification
and validation reports for the tlaplus-ts TypeScript bindings project.

Co-Authored-By: Terraphim AI <noreply@terraphim.io>

Author: Terraphim CI

.docs/handover-2026-03-15-symphony-tlaplus.md

@@ -0,0 +1,131 @@
+# Handover: Symphony tlaplus-ts Orchestration
+
+**Date**: 2026-03-15 11:53 GMT
+**Branch**: `main` (terraphim-ai), `main` (tlaplus-ts on Gitea)
+**Status**: Complete -- all work delivered and verified
+
+---
+
+## Progress Summary
+
+### Completed This Session
+
+1. **Symphony WORKFLOW rewrite** (`WORKFLOW-tlaplus-ts.md`)
+   - Fixed three root causes preventing code accumulation across agents:
+     - Branch isolation: added merge-to-main in `after_run` so downstream agents inherit work
+     - Unconditional auto-close: replaced with quality gate (build + test must pass)
+     - Insufficient turns: increased from 15 to 50
+   - Added retry support via `{% if attempt %}` Liquid template block
+
+2. **Gitea dependency graph setup**
+   - Deleted and recreated `terraphim/tlaplus-ts` repo with 8 issues
+   - Added 12 dependency edges using corrected `gitea-robot add-dep` semantics
+   - Fixed documentation: `--issue X --blocks Y` means "X is blocked by Y" (not "X blocks Y")
+   - Documentation fixes applied to: `gitea-robot/skill/SKILL.md`, `skill/references/claude-md-snippet.md`, `~/.claude/CLAUDE.md`
+
+3. **Symphony execution on bigbox**
+   - All 8 issues completed in ~53 minutes with 2 concurrent agents
+   - Dependency ordering verified: roots first (#1, #2), then cascading (#3 -> #4+#5 -> #6 -> #7 -> #8)
+   - Merge race on #2 handled automatically by retry mechanism
+   - Result: 26 TypeScript source files, 8 test files, 414 tests passing
+
+4. **Verification and validation** (disciplined V-model Phases 4 + 5)
+   - Build: PASS (CJS + ESM + DTS)
+   - Tests: 414/414 passing
+   - Coverage: 77% statement, 92% function
+   - 5 defects found, all in CLI commands (Issue #7 agent)
+   - Reports: `.docs/verification-report-tlaplus-ts.md`, `.docs/validation-report-tlaplus-ts.md`
+
+5. **Defect fixes applied** (commit `f4632e4` on tlaplus-ts)
+   - D1: `check.ts` -- fixed `bridge.check()` call signature (2 args -> 3 args)
+   - D2a: `check.ts` -- `duration` -> `durationSeconds`
+   - D2b: `check.ts` -- `state.number` -> `state.num`
+   - D3: `format.ts` -- added null guard for `result.module`
+   - D4: `validate.ts` -- added null guard for `result.module`
+   - D5: `.gitignore` -- removed 5 duplicate `CLAUDE.md` entries
+   - Post-fix: zero TypeScript errors, 414/414 tests passing, build succeeds
+
+### Nothing Blocked
+
+All work is complete and pushed.
+
+---
+
+## Technical Context
+
+### Repositories
+
+| Repo | Location | State |
+|------|----------|-------|
+| terraphim-ai | `/Users/alex/projects/terraphim/terraphim-ai` (local) | Clean on `main`, 2 untracked report files |
+| tlaplus-ts | `https://git.terraphim.cloud/terraphim/tlaplus-ts` | All 8 issues closed, `main` has all merged work + defect fixes |
+| tlaplus-ts (bigbox clone) | `/tmp/tlaplus-ts-verify/` on bigbox | Used for verification and fix commits |
+
+### Key Commits
+
+**terraphim-ai** (`main`):
+```
+73e6b4c3 feat(symphony): rewrite WORKFLOW with quality gate and merge-to-main
+```
+
+**tlaplus-ts** (`main` on Gitea):
+```
+f4632e4 fix(cli): resolve TypeScript strict-mode errors in CLI commands
+e444f35 Merge #8: docs and npm publishing
+1132049 Merge #7: CLI commands
+9366879 Merge #5: formatter
+...8 merge commits total from Symphony agents
+```
+
+### tlaplus-ts Architecture (as built)
+
+```
+src/
+  parser/       -- tree-sitter wrapper, CST-to-AST transform (Issue #3)
+  ast/          -- TypeScript type definitions for TLA+ AST (Issue #2)
+  eval/         -- Expression evaluator: sets, logic, functions (Issue #4)
+  format/       -- Pretty-printer (Issue #5)
+  bridge/       -- TLC model checking bridge via Java CLI (Issue #6)
+  cli/          -- CLI: parse|format|validate|check (Issue #7)
+  index.ts      -- Public API exports (Issue #1 scaffold)
+test/
+  8 test files, 414 tests
+```
+
+### Symphony Configuration
+
+- **WORKFLOW file**: `crates/terraphim_symphony/examples/WORKFLOW-tlaplus-ts.md`
+- **max_turns**: 50 per agent
+- **max_concurrent_agents**: 2
+- **Quality gate**: checks for .ts files, build pass, test pass before merging to main
+- **Retry**: Symphony re-dispatches if issue stays open (quality gate failed)
+
+### Untracked Files (terraphim-ai)
+
+```
+.docs/validation-report-tlaplus-ts.md   -- Phase 5 validation report
+.docs/verification-report-tlaplus-ts.md -- Phase 4 verification report
+.cachebro/                              -- cache directory (ignorable)
+```
+
+These reports are informational and can be committed if desired.
+
+---
+
+## Lessons Learned
+
+1. **gitea-robot `add-dep` semantics**: `--issue X --blocks Y` means "X is blocked by Y" (Y blocks X). Documentation was wrong and has been corrected.
+2. **Symphony merge-to-main pattern works**: downstream agents successfully inherited accumulated code via `git fetch origin main` + rebase in `before_run`.
+3. **Quality gate prevents false closes**: issues only close when build + tests pass, preventing the zero-code-output problem from previous runs.
+4. **CLI agents produce most defects**: all 5 defects came from Issue #7 (CLI). Core library (parser, AST, eval, format, bridge) was defect-free.
+5. **Agent CLAUDE.md should be minimal**: stripping task-tracking commands from agent instructions leaves more turns for actual coding.
+
+---
+
+## Potential Follow-up Work
+
+- **Commit the verification/validation reports** to terraphim-ai if desired
+- **Publish tlaplus-ts to npm** -- the package.json is configured, just needs `npm publish`
+- **Add CI/CD** to tlaplus-ts repo (GitHub Actions or Gitea runner)
+- **Clean up symphony/* branches** on tlaplus-ts remote (8 branches from completed issues)
+- **Run Symphony on other projects** using the proven WORKFLOW pattern

.docs/handover-2026-03-16-symphony-rust-genai.md

@@ -0,0 +1,101 @@
+# Handover: Symphony Orchestration for rust-genai Fork Sync
+
+**Date**: 2026-03-16
+**Session duration**: ~2 hours
+**Status**: COMPLETE -- all 10 issues closed, verified
+
+## Progress Summary
+
+### Completed
+
+1. **Created Gitea repo** `terraphim/rust-genai` at `git.terraphim.cloud` and pushed fork main
+2. **Created 10 issues** on Gitea with full descriptions covering upstream merge, adapter updates, new features, tests, and validation
+3. **Added 16 dependency edges** via `gitea-robot add-dep` forming a proper DAG
+4. **Created WORKFLOW-rust-genai.md** adapted from the proven tlaplus-ts WORKFLOW for Rust (cargo build/test/clippy/fmt quality gate, 600s timeout, `-X theirs` merge strategy)
+5. **Deployed and ran Symphony** on bigbox -- all 10 issues dispatched, agents completed, merged to main, issues closed
+6. **Verified final result** -- fresh clone passes all quality gates (107 tests pass, 0 failures, clean clippy, clean fmt)
+
+### Dispatch Waves Observed
+
+| Wave | Issues | Time |
+|------|--------|------|
+| 1 | #1 (merge), #3 (Cerebras), #5 (AuthData), #10 (Zai URL) -- concurrent | ~5 min |
+| 2 | #4 (OpenRouter) | ~3 min |
+| 3 | #2 (Bedrock) -- required 1 retry | ~8 min |
+| 4 | #6 (Kimi), #8 (tests) -- concurrent | ~5 min |
+| 5 | #7 (SSE) | ~3 min |
+| 6 | #8 (manual close due to hook bug), #9 (final validation) | ~5 min |
+
+Total orchestration: ~45 minutes including retries.
+
+## Technical Context
+
+### Repositories
+
+| Repo | Location | State |
+|------|----------|-------|
+| terraphim-ai (primary) | `/Users/alex/projects/terraphim/terraphim-ai` | main, WORKFLOW file uncommitted |
+| rust-genai (local) | `/Users/alex/projects/terraphim/rust-genai` | main, local behind gitea/main |
+| rust-genai (Gitea) | `git.terraphim.cloud/terraphim/rust-genai` | main at `b76e5a0`, fully synced |
+| rust-genai (GitHub) | `github.com/terraphim/rust-genai` | main at `1c62bfb`, NOT synced |
+
+### Uncommitted Files in terraphim-ai
+
+- `crates/terraphim_symphony/examples/WORKFLOW-rust-genai.md` -- the Symphony WORKFLOW for rust-genai
+
+### Key Artefact
+
+**WORKFLOW-rust-genai.md** (`crates/terraphim_symphony/examples/WORKFLOW-rust-genai.md`):
+- Tracker: Gitea `terraphim/rust-genai`
+- Agent: claude-code, max 2 concurrent, 50 turns
+- Quality gate: `cargo build && cargo test && cargo clippy -- -D warnings && cargo fmt -- --check`
+- Hook timeout: 600000ms (10 min for Rust compilation)
+- Merge strategy: `-X theirs` to auto-resolve CLAUDE.md conflicts
+- CLAUDE.md tracked in git per user preference
+
+## Issues Encountered and Fixed
+
+### 1. Symphony positional argument
+**Problem**: Used `symphony run --workflow <path>` but correct syntax is `symphony <path>` (positional)
+**Fix**: Removed `run --workflow` flag
+
+### 2. before_run branch already exists
+**Problem**: On retry, `git checkout -b "$BRANCH"` fails because local branch exists from previous run
+**Fix**: Added `git checkout main && git branch -D "$BRANCH"` before branch creation
+
+### 3. CLAUDE.md merge conflicts blocking merge-to-main
+**Problem**: Each agent writes a different CLAUDE.md; when merging branch to main, git conflicts on CLAUDE.md
+**Fix**: Used `git merge -X theirs` in both before_run fallback and after_run merge step
+
+### 4. Untracked CLAUDE.md blocking branch checkout
+**Problem**: after_create wrote CLAUDE.md but didn't commit it; before_run's `git checkout` refused because local changes would be overwritten
+**Fix**: Added `git add CLAUDE.md && git commit` at end of after_create
+
+### 5. Issue #8 merge-to-main loop
+**Problem**: Quality gate passed but curl to close issue timed out, triggering fallback "merge failed" message; issue stayed open; Symphony re-dispatched forever
+**Fix**: Manual merge-and-close via Gitea API. Root cause: the `||` error handling in after_run treats any failure in the `git merge && git push && curl close && curl comment` chain as merge failure
+
+## Pending / Follow-up
+
+1. **Push Gitea main to GitHub origin**: `cd ~/projects/terraphim/rust-genai && git pull gitea main && git push origin main` -- the GitHub fork is still at the pre-sync state
+2. **Commit WORKFLOW-rust-genai.md**: The WORKFLOW file in terraphim-ai is uncommitted
+3. **Fix after_run hook robustness**: The curl timeout issue (#5 above) should be addressed -- separate the merge+push from the issue-close curl, and handle curl failures independently
+4. **Clean up symphony branches**: Remote branches `symphony/issue-{2,6,7,8,9}` remain on Gitea after merge; could be cleaned up
+5. **CLAUDE.md on main**: Contains agent-specific instructions rather than project-level learnings. Could be replaced with proper project CLAUDE.md
+
+## Key Learnings for MEMORY.md
+
+Already recorded in MEMORY.md:
+- Symphony positional argument syntax
+- Branch cleanup in before_run for retries
+- `-X theirs` merge strategy for CLAUDE.md conflicts
+- after_create must commit tracked files
+- Rust quality gate with 600s timeout
+- after_run curl timeout can cause infinite retry loops
+
+## Environment State
+
+- **bigbox**: Symphony stopped, tmux session `symphony-genai` killed
+- **Gitea**: All 10 issues closed, main at `b76e5a0`
+- **Local rust-genai**: main at `1c62bfb`, gitea/main at `b76e5a0` (needs pull)
+- **GITEA_TOKEN**: `5d663368d955953ddf900ff33420fcabebfbfb4b` (also in MEMORY.md context)

.docs/handover-2026-03-17-symphony-terraphim-private.md

@@ -0,0 +1,112 @@
+# Handover: Symphony V-Model Orchestration for terraphim-private Upgrade
+
+**Date**: 2026-03-17
+**Session duration**: ~3 hours
+**Status**: COMPLETE -- all 9 issues closed, verified, quality gate passes
+
+## Progress Summary
+
+### Completed
+
+1. **Created WORKFLOW-terraphim-private.md** with V-model disciplined engineering (5-phase: research, design, implementation, verification, validation)
+2. **Created Gitea repo** `zestic-ai/terraphim-private` and pushed private/main
+3. **Created 9 issues** on Gitea covering full upstream merge of 181 commits from `terraphim/terraphim-ai`
+4. **Added 12 dependency edges** via `gitea-robot add-dep` forming proper DAG
+5. **Deployed and ran Symphony** on bigbox -- all 9 issues dispatched, merged to main, closed
+6. **Fixed WORKFLOW mid-run**: V-model instructions failed in heredoc injection; moved to Liquid template body (commit `4c457e03`)
+7. **Handled disk space crisis**: 8 workspace clones consumed 177GB, cleaned completed workspaces, freed 163GB, relaunched
+8. **Verified final result**: fresh clone passes all quality gates (build, 28 tests pass, clean clippy, clean fmt)
+
+### Issue Decomposition
+
+| # | Title | Depends On | Result |
+|---|-------|------------|--------|
+| 1 | Merge upstream terraphim-ai main | -- | Merged (3 attempts) |
+| 2 | Fix compilation after upstream merge | #1 | Merged |
+| 3 | Reconcile email-worker with upstream | #2 | Merged |
+| 4 | Reconcile onboarding wizard with upstream | #2 | Merged |
+| 5 | Reconcile Groq provider with upstream | #2 | Merged (full V-model completed) |
+| 6 | Update CI/CD for upstream changes | #2 | Merged |
+| 7 | Add Symphony crate to private workspace | #2 | Merged |
+| 8 | Full test suite pass | #3,#4,#5,#6 | Merged (disk space cleanup needed) |
+| 9 | Final validation and documentation | #7,#8 | Merged |
+
+### V-Model Artefacts Produced
+
+- **8 research documents** (`.docs/research-issue-*.md`)
+- **7 design documents** (`.docs/design-issue-*.md`)
+- **1 verification document** (issue #5, Groq provider)
+- **1 validation document** (issue #5, Groq provider)
+
+Most agents spent their turns on implementation and test-fixing, reaching phases 1-3 but not always phases 4-5. This is expected for merge/reconciliation work vs greenfield features.
+
+### Key Incidents
+
+1. **Issue #1 quality gate failed** (attempt 1): tests + format check failed. Fixed on attempt 3.
+2. **Disk space exhaustion**: 8 workspaces at 13-79GB each filled 3.5TB disk. Killed Symphony, cleaned workspaces 1-7, freed 163GB, relaunched.
+3. **Stall timeouts on issues #8 and #9**: `cargo test --workspace` exceeds 600s stall timeout on bigbox, but after_run hook still completed and merged successfully.
+
+## Technical Context
+
+### Branch
+```
+main @ 4c457e03 fix(symphony): move V-model instructions from heredoc to Liquid template
+```
+
+### Recent Commits (local)
+```
+4c457e03 fix(symphony): move V-model instructions from heredoc to Liquid template
+b6b66bd2 feat(symphony): add V-model disciplined engineering WORKFLOW for terraphim-private
+f9e0a6f9 fix(symphony): separate merge+push from curl in after_run hook
+18ba792a feat(symphony): add WORKFLOW-rust-genai.md for fork sync orchestration
+```
+
+### Modified Files (uncommitted)
+```
+M  Cargo.lock
+M  crates/terraphim_orchestrator/src/config.rs
+?? crates/terraphim_tracker/
+?? crates/terraphim_workspace/
+```
+
+### Key File
+- `crates/terraphim_symphony/examples/WORKFLOW-terraphim-private.md` -- the V-model WORKFLOW (committed)
+
+### Remote State
+- **Gitea**: `zestic-ai/terraphim-private` -- 9/9 issues closed, 1957 commits, 50 crate dirs
+- **bigbox**: Symphony stopped, workspaces cleaned, 415GB free
+
+## Lessons Learnt
+
+### WORKFLOW Design
+- **Liquid template body > heredoc injection**: Heredocs in `after_create` are fragile with nested quotes, variable expansion, and line continuation. Placing V-model instructions in the Liquid template body after `---` frontmatter is cleaner and allows `{{ issue.identifier }}` interpolation.
+- **`Skill` in allowedTools**: Required for agents to invoke `/disciplined-research`, `/disciplined-design`, etc. Also added `Task` for subagent orchestration.
+- **MERGE_OK pattern**: Separate `git merge && git push` success from `curl` API calls using a boolean flag. Prevents curl timeouts from triggering false "merge failed" messages.
+
+### Operational
+- **Disk space**: Each Rust workspace clone with `target/` can be 13-79GB. With `max_concurrent_agents: 2` and 9 issues, disk can fill quickly. Consider adding workspace cleanup to `after_run` hook.
+- **Stall timeout**: 600s is insufficient for `cargo test --workspace` on large projects. The after_run hook still runs even when the agent session times out.
+- **GITEA_TOKEN**: The 1Password token (`op://TerraphimPlatform/gitea-test-token/credential`) does NOT work for `zestic-ai` org repos. Must use the direct token.
+- **V-model completion rate**: Agents typically reach phases 1-3 within 50 turns for merge/reconciliation work. Full 5-phase V-model more achievable for smaller, greenfield features.
+
+## Verification Evidence
+
+```bash
+# All issues closed
+curl -sf "https://git.terraphim.cloud/api/v1/repos/zestic-ai/terraphim-private/issues?state=open" | jq length
+# 0
+
+# Quality gate on fresh clone
+cargo build        # exit 0
+cargo test         # 28 passed, 0 failed
+cargo clippy -- -D warnings  # 0 warnings
+cargo fmt -- --check         # 0 diffs
+```
+
+## Potential Follow-ups
+
+1. **Push local commits to GitHub**: `4c457e03` and `b6b66bd2` are local only
+2. **Sync terraphim-private to GitHub**: Push Gitea main to `git@github.com:zestic-ai/terraphim-private.git`
+3. **Increase stall_timeout_ms**: Consider 900s or 1200s for large Rust workspaces
+4. **Workspace cleanup in after_run**: Add `cargo clean` or workspace removal after successful merge
+5. **V-model phase budgeting**: Consider splitting into separate issues (implementation + verification/validation) for complex merge work