docs(chain): add Bash v1 mounted-chain architecture and operator guide

[teseo]

Intent

Update Combo Chen docs, architecture, specifications, and guides to match the real Bash v1 chain while excluding README and all non-docs payloads.

What Changed

• Added docs/bash-v1-chain.md, the normative architecture and operator guide for the Bash v1 mounted-chain product, covering cb-run.sh topology, endpoint dispatch, Reviewer cardinality and routing, Launcher custody, Gate admission and replay, terminal outcomes, Cleaner release behavior, and operator commands.
• Updated docs/spec.md to cross-reference the new chain document as the authoritative specification for the plan-driven mounted chain, with a note that earlier v0 sections must not be used to infer v1 behavior.

Testing

Ran the full test suite (13 suites, 0 failures) and performed a structured cross-reference of 16 architectural claims in the new docs/bash-v1-chain.md against the actual Bash v1 chain implementation in bin/cb-*.sh — every claim matched the code exactly, including plan/chain order, five tmux endpoints, three exit classes, role-specific 0/1 events, Launcher custody seven keys, reviewer != coder enforcement, max review rounds default (20), process status precedence, Gate terminal outcomes, Cleaner release behavior, and endpoint job/receipt contracts. The change scope is strictly docs with no README or non-docs payloads.

Evidence: Docs-to-code cross-reference verification

# Docs-to-Code Cross-Reference Verification

## Change Summary
- `docs/bash-v1-chain.md`: New 873-line normative architecture and operator guide
- `docs/spec.md`: +9 lines linking to the new guide, declaring it normative for the plan-driven mounted chain
- No README changes, no non-docs payloads

## Claims Verified Against Code

| Doc Claim | Code Location | Match |
|---|---|---|
| Plan order: launcher → coder → reviewers → gate → cleaner | `bin/cb-plan.sh:229-240` | ✅ |
| Chain order: Launcher → Coder → all Reviewers → Gate → Cleaner | `bin/cb-chain.sh:81-83` | ✅ |
| Five endpoints: combo-\<run-id\> with cb-\<run-id\>-{launcher,coder,reviewer,gate,cleaner} | `bin/cb-tmux.sh:19` (`cb_tmux_window_name`) | ✅ |
| Three exit classes: completed, technical_error, cancelled | `bin/cb-step.sh:391-400` | ✅ |
| Role events: launch_ready/not_ready, coder_ready/not_ready, lgtm/needs_change, gate_ok/failed, cleaned/clean_failed | `bin/cb-step.sh:356-387` | ✅ |
| Launcher custody 7 keys: base_sha, branch, lease_id, repo_dir, run, runway_kind, worktree | `bin/cb-launcher-adapter.sh:304` | ✅ |
| reviewer != coder enforcement | `bin/cb-plan.sh:179` | ✅ |
| Max review rounds default: 20 | `bin/cb-chain.sh:121` | ✅ |
| Process status precedence (cleanup cancelled→130, etc.) | `bin/cb-run.sh:480-504` | ✅ |
| Gate terminal outcomes: validated, merged, failed | `bin/cb-run.sh:562-607` | ✅ |
| Cleaner only releases after terminal Gate evidence | `bin/cb-cleaner-adapter.sh:406-531` | ✅ |
| Cleaner treehouse return path-only, non-forcing | `bin/cb-cleaner.sh` (mechanical end) | ✅ |
| Endpoint jobs use `combo.endpoint-job/v1` schema | `bin/cb-run.sh:205-207` | ✅ |
| Job/receipt collision-safe, no stale adoption | `bin/cb-run.sh:172-267` | ✅ |
| Completed chain replay: no re-entry when `chain-result.json` exists | `bin/cb-run.sh` (mount/verify logic) | ✅ |
| Gate admission order: custody→candidate→paths→seal replay→base→no-mistakes | `bin/cb-gate.sh` | ✅ |

## Test Results
- `tests/run.sh`: **13 suites, 0 failures**
- All Bash v1 chain contract tests pass (plan-contract, step-adapter-contract, chain-state-machine, chain-mount-integration, chain-mount-e2e skipped by design)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⏭️ **Review** - skipped

Step was skipped.

✅ **Test** - passed

✅ No issues found.

• tests/run.sh
• Cross-referenced 16 doc claims against bin/cb-plan.sh, bin/cb-chain.sh, bin/cb-run.sh, bin/cb-step.sh, bin/cb-launcher-adapter.sh, bin/cb-cleaner-adapter.sh, bin/cb-tmux.sh, bin/cb-gate.sh — all matched
• Verified git diff contains only docs/bash-v1-chain.md and docs/spec.md — no README or bin/ changes
• tests/run.sh — 13 suites, 0 failures

⏭️ **Document** - skipped

Step was skipped.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1a93d36b-4bdf-448b-bbe3-3f75c4de7199

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch combo/e2e-339-aa0efdf-r7-20260728

---

_{Comment @coderabbitai help to get the list of available commands.}