docs: add Bash v1 mounted-chain architecture guide and spec pointer

[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, a comprehensive normative architecture, runtime specification, and operator guide for the Bash v1 cb-plan.sh → cb-chain.sh pipeline covering component ownership, the five execution endpoints, normalized exit classes, step routing, replay semantics, and operator commands.
• Updated docs/spec.md with a forward pointer declaring the mounted-chain contract as the governing document for the Bash v1 product line where it differs from legacy v0 mechanics.
• Removed stale cb-run.sh references so all documented entry points match the real cb-chain.sh state machine.

Testing

Verified the docs-only change by running the three most relevant test suites (chain state machine, plan contract, step adapter contract — 16/16 tests passed), then manually cross-referenced every documented script name, the architecture flow, exit codes, and step exit classes against the actual code. All 10 documented scripts exist, cb-run.sh (the prior finding) is correctly absent, and zero non-docs files were changed — meeting the user intent constraint exactly.

Evidence: Doc-to-code alignment evidence

=== Evidence: docs/bash-v1-chain.md matches real Bash v1 codebase ===

Commit range: 471156c20..563516b9
Branch: combo/e2e-339-aa0efdf-r5-20260728

FILES CHANGED (docs only, no non-docs payload):
  docs/bash-v1-chain.md  (+635 lines, new file)
  docs/spec.md           (+7 lines, cross-reference only)

PRIOR FINDING FIXED:
  Round 1 reported cb-run.sh referenced in docs but absent from codebase.
  Commit 563516b9 ("Remove cb-run.sh references from docs, match real
  cb-chain.sh entry point") resolved this. grep -r 'cb-run' docs/bash-v1-chain.md
  returns zero hits. The architecture diagram, operator guide (§11), and all
  references now correctly name cb-chain.sh as the product state machine.

DOCUMENTED SCRIPTS → ACTUAL CODE MAPPING:
  Script              Doc reference         In bin/       Role
  cb-plan.sh          config compiler        EXISTS       Plan compilation
  cb-chain.sh         state machine          EXISTS       Product state machine / entry point
  cb-step.sh          adapter boundary       EXISTS       Universal step ABI
  cb-tmux.sh          tmux lifecycle         EXISTS       Session/window management
  cb-send.sh          pane dispatch          EXISTS       Tmux command dispatch
  cb-launcher.sh      mechanical launcher    EXISTS       Runway acquisition
  cb-cleaner.sh       mechanical cleaner     EXISTS       Custody release
  cb-agent-run.sh     coder consumption      EXISTS       Coder tool execution
  cb-status.sh        observe                EXISTS       Status display
  cb-peek.sh          observe                EXISTS       Pane capture
  cb-run.sh           —                      ABSENT       Correctly absent

ARCHITECTURE SIGNATURE MATCH:
  Doc: plan -> Launcher -> Coder <-> Reviewer* -> Gate -> Cleaner
  Code (bin/cb-chain.sh header):
    plan -> Launcher -> Coder <-> Reviewer* -> Gate -> Cleaner -> chain result
  ✓ Identical flow

EXIT CODES MATCH:
  Doc: 0 = success, 1 = code 1 product/cleanup, 70 = technical error, 130 = cancel
  Code (bin/cb-chain.sh grep): exit 1, exit 70, exit 130
  ✓ Consistent with documented terminal status table

STEP EXIT CLASSES MATCH:
  Doc: completed, technical_error, cancelled
  Code (bin/cb-step.sh): technical_error, cancelled, completed
  ✓ All three exit classes present

ALL DOC-REFERENCED FILES EXIST: ✓ (10/10 scripts verified)

TESTS PASSING:
  tests/chain-state-machine.test.sh   — 6/6 passed
  tests/plan-contract.test.sh         — 5/5 passed
  tests/step-adapter-contract.test.sh — 5/5 passed
  tests/run.sh                        — baseline (pre-existing pass)

SPEC CROSS-REFERENCE:
  docs/spec.md adds a callout linking to bash-v1-chain.md as the normative
  contract for the cb-*.sh pipeline, with clear governance precedence.

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (18m21s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⏭️ **Review** - skipped

Step was skipped.

🔧 **Test** - 1 issue found → auto-fixed ✅

• ⚠️ docs/bash-v1-chain.md:18 - docs/bash-v1-chain.md prominently documents cb-run.sh as the central dispatcher/mounter (architecture diagram, component ownership table, endpoint job/receipt protocol §4, operator guide §11) but cb-run.sh does not exist in the codebase. The actual state machine (cb-chain.sh) is invoked directly by tests without this intermediate layer. If the intent is forward-looking specification, this is acceptable; if the intent is to match current reality, the docs describe an unimplemented component.
• tests/run.sh
• tests/chain-state-machine.test.sh
• tests/plan-contract.test.sh
• tests/step-adapter-contract.test.sh
• tests/mechanical-ends.test.sh
• tests/journal-spine.test.sh
• Manual plan compilation and step-order verification via cb-plan.sh
• Cross-reference verification between docs/spec.md and docs/bash-v1-chain.md
• Git diff verification that only docs/ files changed

🔧 Fix: Remove cb-run.sh references from docs, match real cb-chain.sh entry point
✅ Re-checked - no issues remain.

• tests/run.sh
• tests/chain-state-machine.test.sh (all 6 passed)
• tests/plan-contract.test.sh (all 5 passed)
• tests/step-adapter-contract.test.sh (all 5 passed)
• Manually verified all 10 documented scripts exist in bin/ and cb-run.sh is correctly absent
• Manually verified architecture flow, exit codes, and step exit classes match between docs/bash-v1-chain.md and actual code
• Manually verified only docs/ files changed — no non-docs payloads touched
• Baseline: tests/run.sh (pre-existing pass)

⏭️ **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: 97ef9999-7ded-4743-b03c-39ab91c7a41b

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-r5-20260728

---

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

[teseo]

Closing: experiment debris. main-combo-v1 restored via #346 (tree == post-P7 471156c).