# Major Refactor: CLI11 Unification + Real cv-mmap Primary + Dummy Backend

## TL;DR
> **Summary**: Remove manual/custom CLI/help paths, make CLI11 the single CLI surface, remove `cvmmap_sim`, and refactor ingestion to support `real` (default, cvmmap-client-cpp) and protocol-faithful `dummy` backends.
> **Deliverables**:
> - Unified CLI11 behavior across streamer + testers (no handcrafted help)
> - `cvmmap_sim` removed from build/scripts/docs
> - `FrameSource` input boundary with `real` and `dummy` backends
> - Required real cv-mmap integration profile using `/home/crosstyan/Code/cv-mmap`
> - Updated acceptance/fault/release gates + evidence paths
> **Effort**: XL
> **Parallel**: YES - 3 waves
> **Critical Path**: T1 → T2/T3/T4 → T5 → T6/T7 → T8 → T9/T10/T11 → T12

## Context
### Original Request
- Remove custom CLI flags/help and use CLI11.
- Major cleanup/refactor with `cvmmap-client-cpp` integration.
- Stop using `cvmmap_sim`; use real cv-mmap and add dummy/stub mode.
- Improve testing/integration with SRS/ZLMediaKit and real cv-mmap.

### Interview Summary
- Legacy CLI policy: **immediate removal**.
- Integration gating: **required real cv-mmap profile**; SRS/ZLMediaKit remain optional/nightly-manual.
- Default input mode: **real**.
- Dummy backend shape: **protocol-faithful SHM+ZMQ**.
- `cvmmap_sim` binary: **remove**.
- Input target must support **CVMMAP URI** compatible with `/home/crosstyan/Code/cvmmap-python-client` conventions.
- Execution model: implementation must run from a dedicated **git worktree** (branch-isolated workspace), not the primary checkout.

### Metis Review (gaps addressed)
- Guardrail added for preserving exit code semantics and evidence formats.
- Guardrail added for script updates in same refactor wave as `cvmmap_sim` removal.
- Guardrail added for protocol/fault knob parity in dummy backend.

## Work Objectives
### Core Objective
Produce a decision-complete refactor plan that eliminates CLI ambiguity, replaces simulator-binary dependency with backend architecture, and hardens verification with required real cv-mmap integration.

### Deliverables
- CLI11-only entrypoints for streamer and tester binaries.
- `FrameSource` boundary with `RealCvmmapSource` + `DummyShmZmqSource`.
- Streamer runtime option `--input-mode real|dummy` (default `real`).
- Removal of `cvmmap_sim` build target and sim-binary assumptions.
- Updated acceptance/fault/release scripts and docs.
- Required integration script/profile against `/home/crosstyan/Code/cv-mmap`.

### Definition of Done (verifiable conditions with commands)
- Work executes from a dedicated worktree path created via `git worktree add` and branch-isolated from main workspace.
- `cmake -S . -B build && cmake --build build` succeeds.
- `test ! -x build/cvmmap_sim` returns success.
- `./build/cvmmap_streamer --help` shows CLI11-generated usage/options and no handcrafted help path.
- `./build/cvmmap_streamer --input-uri "cvmmap://default" ...` (or equivalent URI input flag) resolves and starts in real mode.
- `./scripts/acceptance_standalone.sh` returns 0 with `total=5 pass=5 fail=0 skip=0`.
- `./scripts/fault_suite.sh` returns 0 baseline.
- Required real profile script returns 0 when `/home/crosstyan/Code/cv-mmap` is available.

### Must Have
- Dedicated worktree bootstrap and validation step before any refactor change.
- No `src/ipc/help.cpp` runtime dependency for CLI help.
- No manual argv scanning/parsing in tester binaries.
- Dummy backend reproduces SHM/ZMQ protocol semantics needed by acceptance/fault suites.
- Real mode uses `cvmmap-client-cpp` path by default.
- Streamer accepts CVMMAP plain names and URI form compatible with python client semantics (`cvmmap://<instance>[@<prefix>][?namespace=<namespace>]`).

### Must NOT Have (guardrails, AI slop patterns, scope boundaries)
- No compatibility aliases for removed legacy CLI flags.
- No behavioral drift in accepted exit-code contracts used by scripts.
- No mandatory SRS/ZLMediaKit gate in PR critical path.
- No new feature scope (RTSP/WebRTC/audio/etc.).

## Verification Strategy
> ZERO HUMAN INTERVENTION — all verification is agent-executed.
- Test decision: **tests-after** using existing shell suites + tester binaries.
- QA policy: Every task includes happy + edge/failure scenario.
- Evidence: `.sisyphus/evidence/task-{N}-{slug}.{ext}`

## Execution Strategy
### Parallel Execution Waves
Wave 1: worktree bootstrap + CLI contract + parser unification + foundational input abstraction
Wave 2: real/dummy backend implementation + simulator removal plumbing
Wave 3: script/gate/docs/integration profile hardening

### Dependency Matrix (full, all tasks)
- T0 blocks all implementation tasks.
- T1 blocks T2, T3, T4.
- T2/T3/T4 block T12 validation updates.
- T5 blocks T6 and T7.
- T6/T7 block T8/T9/T10.
- T8 blocks T9/T10/T11.
- T9/T10/T11 block T12.

### Agent Dispatch Summary (wave → task count → categories)
- Wave 1 → 6 tasks → quick, unspecified-high
- Wave 2 → 5 tasks → deep, unspecified-high
- Wave 3 → 3 tasks → writing, unspecified-high

## TODOs
> Implementation + Test = ONE task. Never separate.
> EVERY task MUST have: Agent Profile + Parallelization + QA Scenarios.

- [ ] 0. Bootstrap dedicated git worktree and enforce branch isolation

  **What to do**: Create a dedicated git worktree for this refactor branch, validate branch isolation, and pin all subsequent build/test commands to that worktree path.
  **Must NOT do**: Do not execute refactor work in primary checkout; do not reuse a dirty worktree.

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: procedural setup with strict safeguards.
  - Skills: [`git-master`] — safe git/worktree operations and verification.
  - Omitted: [`feature-research`] — no architecture decision here.

  **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [1,2,3,4,5,6,6A,7,8,9,10,11,12] | Blocked By: []

  **References**:
  - Pattern: `docs/caveats.md:49-61` — downstream path and cache-collision constraints.
  - Pattern: `README.md:237-244` — sibling-path configure caveat.
  - External: `https://git-scm.com/docs/git-worktree` — official worktree commands/constraints.

  **Acceptance Criteria**:
  - [ ] `git worktree list --porcelain` shows exactly one new path for refactor branch.
  - [ ] `git -C <worktree-path> status --short` is clean before edits.
  - [ ] Build/test commands in plan execution are run from `<worktree-path>`.

  **QA Scenarios**:
  ```
  Scenario: Happy path worktree bootstrap
    Tool: Bash
    Steps: Create worktree with new branch, verify list output and clean status.
    Expected: New worktree present, branch checked out, clean tree.
    Evidence: .sisyphus/evidence/task-0-worktree.txt

  Scenario: Failure path dirty/non-isolated workspace
    Tool: Bash
    Steps: Attempt run with dirty worktree or branch already checked out elsewhere.
    Expected: Preflight stops execution with clear isolation error.
    Evidence: .sisyphus/evidence/task-0-worktree-error.txt
  ```

  **Commit**: NO | Message: `n/a` | Files: `none (setup/preflight only)`

- [ ] 1. CLI contract lock + help-path inventory

  **What to do**: Create an explicit CLI contract table (flags, defaults, required/optional, error codes) for `cvmmap_streamer`, `rtp_receiver_tester`, `rtmp_stub_tester`, and identify all handcrafted help/manual parser call sites to remove.
  **Must NOT do**: Do not alter behavior yet; this task is contract freeze and inventory only.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: cross-file contract extraction with regression risk.
  - Skills: [`explore`] — discover all parser/help call sites and script expectations.
  - Omitted: [`playwright`] — no browser surface.

  **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [2,3,4] | Blocked By: []

  **References**:
  - Pattern: `src/main_streamer.cpp:14-29` — manual help path entry.
  - Pattern: `src/ipc/help.cpp:26-44` — handcrafted help + `has_help_flag`.
  - Pattern: `src/testers/rtp_receiver_tester.cpp:189-232,291-299` — manual parse/help.
  - Pattern: `src/testers/rtmp_stub_tester.cpp:267-303,1906-1912` — manual parse/help.
  - Pattern: `src/config/runtime_config.cpp:262-447` — current CLI11 + normalization behavior.

  **Acceptance Criteria**:
  - [ ] A machine-readable contract file/checklist exists in plan notes with every currently supported flag and expected exit behavior.
  - [ ] All help/manual parse call sites are enumerated with exact paths and replacement targets.

  **QA Scenarios** (MANDATORY — task incomplete without these):
  ```
  Scenario: Happy path inventory completeness
    Tool: Bash
    Steps: Run static searches for help/parser symbols and map all binaries to parser entrypoints.
    Expected: No binary entrypoint remains unaccounted for in contract table.
    Evidence: .sisyphus/evidence/task-1-cli-contract.txt

  Scenario: Edge path missing-coverage check
    Tool: Bash
    Steps: Search for "--help" and manual argv scanning patterns; compare to contract table.
    Expected: Zero unmatched parser/help call sites.
    Evidence: .sisyphus/evidence/task-1-cli-contract-error.txt
  ```

  **Commit**: YES | Message: `chore(cli): freeze cli contract and removal inventory` | Files: `docs/* (if used), internal planning evidence`

- [ ] 2. Remove handcrafted help path and rely on CLI11-generated help

  **What to do**: Eliminate `has_help_flag` + handcrafted `print_help` call chain from runtime flow; entrypoints should delegate help/error output to CLI11 parse behavior.
  **Must NOT do**: Do not reintroduce custom help text wrappers.

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: focused code-path cleanup with clear target.
  - Skills: [`code-edit`] — precise edits across small set of files.
  - Omitted: [`feature-research`] — design already fixed.

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1]

  **References**:
  - Pattern: `src/main_streamer.cpp:14-29` — remove pre-parse manual help checks.
  - Pattern: `src/ipc/help.cpp` — remove usage in runtime path (delete or dead-code prune if fully unused).
  - API/Type: `src/config/runtime_config.cpp:262-292` — canonical CLI11 parse error flow.

  **Acceptance Criteria**:
  - [ ] `./build/cvmmap_streamer --help` exits 0 and prints CLI11 help.
  - [ ] Manual help helper symbols are not referenced by production entrypoints.

  **QA Scenarios**:
  ```
  Scenario: Happy path CLI11 help output
    Tool: Bash
    Steps: Build then run ./build/cvmmap_streamer --help
    Expected: Exit code 0 and CLI11-style usage/options output.
    Evidence: .sisyphus/evidence/task-2-cli11-help.txt

  Scenario: Failure path unknown option handling
    Tool: Bash
    Steps: Run ./build/cvmmap_streamer --definitely-invalid
    Expected: Non-zero exit and parse error from CLI11 path (no handcrafted help banner).
    Evidence: .sisyphus/evidence/task-2-cli11-help-error.txt
  ```

  **Commit**: YES | Message: `refactor(cli): remove handcrafted help path` | Files: `src/main_streamer.cpp, src/ipc/help.cpp, related headers`

- [ ] 3. Migrate `rtp_receiver_tester` to CLI11-only parsing

  **What to do**: Replace manual `parseArgs` and bespoke help output with CLI11 parser, preserving current option names and exit code semantics.
  **Must NOT do**: Do not change tester protocol validation behavior.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: parser migration + behavior compatibility.
  - Skills: [`code-edit`] — reliable targeted rewrite.
  - Omitted: [`frontend-ui-ux`] — not applicable.

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1]

  **References**:
  - Pattern: `src/testers/rtp_receiver_tester.cpp:189-232` — manual parse path.
  - Pattern: `src/testers/rtp_receiver_tester.cpp:291-299` — manual help pre-check.
  - Pattern: `src/config/runtime_config.cpp` — preferred CLI11 style.

  **Acceptance Criteria**:
  - [ ] Existing flags (`--port`, `--expect-pt`, `--sdp`, `--decode-hook`, `--packet-threshold`, `--timeout-ms`) still function.
  - [ ] `--help` and invalid flag behavior are CLI11-native; scripts relying on return-code expectations still pass.

  **QA Scenarios**:
  ```
  Scenario: Happy path tester invocation
    Tool: Bash
    Steps: Run ./build/rtp_receiver_tester --port 5004 --expect-pt 96 --packet-threshold 1 --timeout-ms 100
    Expected: CLI parsing succeeds and tester enters runtime path.
    Evidence: .sisyphus/evidence/task-3-rtp-cli11.txt

  Scenario: Failure path invalid option
    Tool: Bash
    Steps: Run ./build/rtp_receiver_tester --not-a-real-flag
    Expected: Exit code matches contract and parse fails cleanly.
    Evidence: .sisyphus/evidence/task-3-rtp-cli11-error.txt
  ```

  **Commit**: YES | Message: `refactor(testers): migrate rtp_receiver_tester to cli11` | Files: `src/testers/rtp_receiver_tester.cpp`

- [ ] 4. Migrate `rtmp_stub_tester` to CLI11-only parsing

  **What to do**: Replace manual `parse_args` and custom help with CLI11, preserving modes/threshold/timeouts and existing semantics.
  **Must NOT do**: Do not alter protocol parser/state machine logic.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: large file, parser section surgery.
  - Skills: [`code-edit`] — scoped rewrite.
  - Omitted: [`deep`] — not needed if confined to parser/help layer.

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1]

  **References**:
  - Pattern: `src/testers/rtmp_stub_tester.cpp:267-303` — custom usage + arg parsing helpers.
  - Pattern: `src/testers/rtmp_stub_tester.cpp:1906-1912` — parser call in main.
  - Test: `scripts/acceptance_standalone.sh:205-212` — expected invocation shape.

  **Acceptance Criteria**:
  - [ ] Modes (`h264`, `h265-enhanced`, `h265-domestic`) parse exactly as before.
  - [ ] Invalid arg handling/exit behavior matches contract table.

  **QA Scenarios**:
  ```
  Scenario: Happy path mode parsing
    Tool: Bash
    Steps: Run ./build/rtmp_stub_tester --mode h264 --listen-host 127.0.0.1 --listen-port 1935 --video-threshold 1 --timeout-ms 100
    Expected: Parser accepts args and tester starts.
    Evidence: .sisyphus/evidence/task-4-rtmp-cli11.txt

  Scenario: Failure path unsupported mode
    Tool: Bash
    Steps: Run ./build/rtmp_stub_tester --mode invalid-mode
    Expected: Parse/config failure with non-zero exit per contract.
    Evidence: .sisyphus/evidence/task-4-rtmp-cli11-error.txt
  ```

  **Commit**: YES | Message: `refactor(testers): migrate rtmp_stub_tester to cli11` | Files: `src/testers/rtmp_stub_tester.cpp`

- [ ] 5. Introduce `FrameSource` boundary and input-mode contract

  **What to do**: Define common source interface for frame/event ingestion and wire streamer runtime to select backend via `--input-mode real|dummy` (default `real`).
  **Must NOT do**: Do not couple backend-specific SHM/ZMQ details into pipeline/controller layers.

  **Recommended Agent Profile**:
  - Category: `deep` — Reason: architectural seam with broad downstream impact.
  - Skills: [`feature-research`] — ensure interface matches existing runtime contracts.
  - Omitted: [`quick`] — insufficient for this scope.

  **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [6,7] | Blocked By: [1]

  **References**:
  - Pattern: `src/core/ingest_runtime.cpp:155-386` — current direct SHM/ZMQ ingest flow.
  - Pattern: `src/pipeline/pipeline_stub.cpp:692-1138` — duplicated ingestion/open logic.
  - API/Type: `include/cvmmap_streamer/config/runtime_config.hpp` — extend with input mode enum.

  **Acceptance Criteria**:
  - [ ] Streamer supports explicit `--input-mode` with default `real`.
  - [ ] Runtime constructs backend through interface, not direct branch sprawl.

  **QA Scenarios**:
  ```
  Scenario: Happy path default backend selection
    Tool: Bash
    Steps: Run streamer without --input-mode and inspect startup logs/config dump.
    Expected: Backend resolves to real mode by default.
    Evidence: .sisyphus/evidence/task-5-framesource.txt

  Scenario: Failure path invalid mode value
    Tool: Bash
    Steps: Run ./build/cvmmap_streamer --input-mode nonsense ...
    Expected: Immediate config error with non-zero exit.
    Evidence: .sisyphus/evidence/task-5-framesource-error.txt
  ```

  **Commit**: YES | Message: `refactor(input): add framesource interface and input-mode contract` | Files: `include/src config/core/pipeline inputs`

- [ ] 6. Implement `RealCvmmapSource` using `cvmmap-client-cpp`

  **What to do**: Integrate `lib/cvmmap-client-cpp` as the real backend implementation behind `FrameSource`; map callbacks/events to existing ingest semantics.
  **Must NOT do**: Do not bypass `FrameSource` or duplicate direct SHM+ZMQ open logic in pipeline/ingest loops.

  **Recommended Agent Profile**:
  - Category: `deep` — Reason: third-party integration + callback/contract adaptation.
  - Skills: [`feature-research`] — align API/metadata contract and lifecycle.
  - Omitted: [`playwright`] — irrelevant.

  **Parallelization**: Can Parallel: YES | Wave 2 | Blocks: [8,12] | Blocked By: [5]

  **References**:
  - API/Type: `lib/cvmmap-client-cpp/include/app/cvmmap/cvmmap_client.hpp:274-309` — client API/callbacks.
  - Pattern: `lib/cvmmap-client-cpp/app_cvmmap_client.cpp` — polling lifecycle and event flow.
  - Pattern: `src/core/ingest_runtime.cpp` — target behavior to preserve.

  **Acceptance Criteria**:
  - [ ] Real backend successfully receives frames/events and feeds existing pipeline path.
  - [ ] Existing coherent-frame semantics and reset handling remain valid under real backend.
  - [ ] Real backend path accepts CVMMAP URI inputs and resolves endpoints consistently with python client behavior.

  **QA Scenarios**:
  ```
  Scenario: Happy path real backend ingest
    Tool: Bash
    Steps: Start real cv-mmap server profile, then run streamer in default mode.
    Expected: Frames processed and published without backend init failures.
    Evidence: .sisyphus/evidence/task-6-real-backend.txt

  Scenario: Failure path server unavailable
    Tool: Bash
    Steps: Run streamer in real mode with unavailable cv-mmap endpoint/root.
    Expected: Deterministic startup failure with actionable error and non-zero exit.
    Evidence: .sisyphus/evidence/task-6-real-backend-error.txt
  ```

  **Commit**: YES | Message: `feat(input): add real cvmmap source via client-cpp` | Files: `src/input/*, CMakeLists.txt, core/pipeline integration`

- [ ] 6A. Enforce CVMMAP URI compatibility contract; refactor `cvmmap-client-cpp` if needed

  **What to do**: Validate C++ client URI parsing/resolution against `/home/crosstyan/Code/cvmmap-python-client` contract; if any divergence exists, refactor `lib/cvmmap-client-cpp` to match and expose the aligned URI path to streamer config.
  **Must NOT do**: Do not invent a streamer-only URI grammar that diverges from python client contract.

  **Recommended Agent Profile**:
  - Category: `deep` — Reason: cross-repo contract parity and potential library-level refactor.
  - Skills: [`feature-research`] — compare URI grammar, validation, derived endpoint rules.
  - Omitted: [`quick`] — cross-library behavior risk.

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: [8,11,12] | Blocked By: [6]

  **References**:
  - External: `/home/crosstyan/Code/cvmmap-python-client/src/cvmmap/__init__.py` — authoritative URI resolver behavior.
  - External: `/home/crosstyan/Code/cvmmap-python-client/README.md` — documented URI scheme and examples.
  - Pattern: `lib/cvmmap-client-cpp/app_cvmmap_client.cpp:93-190,593-597` — current C++ URI resolution and constructor path.
  - API/Type: `lib/cvmmap-client-cpp/include/app/cvmmap/cvmmap_client.hpp:285` — constructor contract surface.

  **Acceptance Criteria**:
  - [ ] Plain instance and URI forms produce the same derived base/endpoint semantics as python client for shared test vectors.
  - [ ] Unsupported query keys, invalid prefixes, invalid namespace/instance tokens fail with deterministic validation errors.
  - [ ] Streamer runtime can consume URI input and pass it cleanly into C++ client path.

  **QA Scenarios**:
  ```
  Scenario: Happy path URI parity vectors
    Tool: Bash
    Steps: Run parity checks for vectors like "cvmmap://default" and "cvmmap://camera0@/run/cvmmap?namespace=zed" through C++ client path.
    Expected: Derived names/endpoints match python client contract exactly.
    Evidence: .sisyphus/evidence/task-6a-uri-parity.txt

  Scenario: Failure path invalid URI validation
    Tool: Bash
    Steps: Pass invalid forms (bad query key, traversal prefix, invalid token chars).
    Expected: Deterministic validation failure and non-zero exit/error propagation.
    Evidence: .sisyphus/evidence/task-6a-uri-parity-error.txt
  ```

  **Commit**: YES | Message: `refactor(client): align cvmmap-client-cpp uri contract with python client` | Files: `lib/cvmmap-client-cpp/*, streamer runtime config/plumbing`

- [ ] 7. Implement protocol-faithful `DummyShmZmqSource` backend (in-process)

  **What to do**: Add in-process dummy backend that reproduces SHM metadata + ZMQ sync/status semantics and fault knobs used by matrix/fault suites.
  **Must NOT do**: Do not create a replacement standalone simulator binary.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: protocol emulation with timing/fault controls.
  - Skills: [`feature-research`] — preserve wire-level behavior.
  - Omitted: [`quick`] — too risky for protocol fidelity.

  **Parallelization**: Can Parallel: YES | Wave 2 | Blocks: [8,12] | Blocked By: [5]

  **References**:
  - Pattern: `src/main_sim.cpp` — behavior source to port into backend, not binary.
  - Pattern: `src/sim/wire.cpp` and `include/cvmmap_streamer/sim/wire.hpp` — protocol writers/serialization.
  - Test: `scripts/fault_suite.sh:171-239` — required scenario knobs and dynamics.

  **Acceptance Criteria**:
  - [ ] Dummy backend supports equivalent frame generation, reset emission, and timing knobs required by existing suites.
  - [ ] Standalone suite can run using streamer+testers without `build/cvmmap_sim`.

  **QA Scenarios**:
  ```
  Scenario: Happy path dummy backend matrix row
    Tool: Bash
    Steps: Run one acceptance row configured for dummy backend.
    Expected: Streamer/tester pass with expected packet/video threshold.
    Evidence: .sisyphus/evidence/task-7-dummy-backend.txt

  Scenario: Failure path dummy reset storm edge
    Tool: Bash
    Steps: Configure high reset frequency and run fault reset scenario.
    Expected: Fault suite captures expected behavior and exits per baseline criteria.
    Evidence: .sisyphus/evidence/task-7-dummy-backend-error.txt
  ```

  **Commit**: YES | Message: `feat(input): add protocol-faithful dummy shm+zmq backend` | Files: `src/input/*, migrated sim logic files`

- [ ] 8. Remove `cvmmap_sim` target and all sim-binary dependencies

  **What to do**: Delete CMake target and obsolete simulator entrypoint files, and replace all build/script references with backend-mode runtime execution.
  **Must NOT do**: Do not leave stale references in scripts/docs/README quickstart.

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: deterministic deletion/plumbing updates.
  - Skills: [`code-edit`] — direct target/reference cleanup.
  - Omitted: [`deep`] — architecture decisions already made.

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: [9,10,11,12] | Blocked By: [6,6A,7]

  **References**:
  - Pattern: `CMakeLists.txt:101-105` — remove sim target block.
  - Pattern: `scripts/acceptance_standalone.sh:273` and `scripts/fault_suite.sh:303` — binary preflight assumptions.
  - Pattern: `README.md` quickstart sections mentioning `cvmmap_sim`.

  **Acceptance Criteria**:
  - [ ] `build/cvmmap_sim` is no longer generated.
  - [ ] No script/doc references require `cvmmap_sim` as executable.

  **QA Scenarios**:
  ```
  Scenario: Happy path build artifact validation
    Tool: Bash
    Steps: Configure+build then assert build/cvmmap_sim absent.
    Expected: Assertion passes and build completes.
    Evidence: .sisyphus/evidence/task-8-remove-sim.txt

  Scenario: Failure path stale-reference scan
    Tool: Bash
    Steps: Search repo scripts/docs for remaining executable references to cvmmap_sim.
    Expected: Zero hard dependency references remain.
    Evidence: .sisyphus/evidence/task-8-remove-sim-error.txt
  ```

  **Commit**: YES | Message: `refactor(build): remove cvmmap_sim target and references` | Files: `CMakeLists.txt, src/main_sim.cpp, src/sim/*, scripts/docs refs`

- [ ] 9. Rewrite acceptance suite to backend-mode runner (no simulator process)

  **What to do**: Update `scripts/acceptance_standalone.sh` so each row drives streamer in `--input-mode dummy` and removes sim process lifecycle/return-code handling.
  **Must NOT do**: Do not change matrix semantics (5 rows/protocol+codec coverage) or summary format contract.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: gate-critical script surgery with evidence contract.
  - Skills: [`code-edit`] — safe structured shell changes.
  - Omitted: [`feature-research`] — behavior already specified.

  **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8]

  **References**:
  - Pattern: `scripts/acceptance_standalone.sh:129-139,224-238` — current sim process usage.
  - Pattern: `scripts/acceptance_summary_helper.py` — output schema to preserve.
  - Test: `README.md` mandatory acceptance expected summary.

  **Acceptance Criteria**:
  - [ ] Script returns 0 with `total=5 pass=5 fail=0 skip=0` on passing runs.
  - [ ] Manifest/summary fields remain compatible with helper parser expectations.

  **QA Scenarios**:
  ```
  Scenario: Happy path full acceptance run
    Tool: Bash
    Steps: Run ./scripts/acceptance_standalone.sh after build.
    Expected: Exit 0 and expected pass/fail/skip totals.
    Evidence: .sisyphus/evidence/task-9-acceptance.txt

  Scenario: Failure path induced row failure
    Tool: Bash
    Steps: Trigger one row with invalid endpoint/arg via controlled injection and run suite.
    Expected: Row marked FAIL, summary reflects non-zero fail count, script exits non-zero.
    Evidence: .sisyphus/evidence/task-9-acceptance-error.txt
  ```

  **Commit**: YES | Message: `test(acceptance): migrate standalone matrix to dummy backend mode` | Files: `scripts/acceptance_standalone.sh`

- [ ] 10. Rewrite fault suite to backend-mode scenarios (no simulator process)

  **What to do**: Update `scripts/fault_suite.sh` to drive fault knobs through dummy backend config in streamer path and remove sim process management.
  **Must NOT do**: Do not relax baseline success criteria (`3/3 pass`) or degraded-mode semantics.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: fault semantics are fragile and gate-critical.
  - Skills: [`code-edit`] — structured shell and threshold contract preservation.
  - Omitted: [`quick`] — risk too high.

  **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8]

  **References**:
  - Pattern: `scripts/fault_suite.sh:208-220,258-271,301-330` — current sim-driven lifecycle.
  - Pattern: `scripts/fault_summary_helper.py` — threshold expectations and summary schema.

  **Acceptance Criteria**:
  - [ ] Baseline mode still returns 0 only when all three scenarios pass.
  - [ ] Degraded mode behavior preserved per existing semantics.

  **QA Scenarios**:
  ```
  Scenario: Happy path baseline fault suite
    Tool: Bash
    Steps: Run ./scripts/fault_suite.sh
    Expected: Exit 0 with total=3 pass=3 fail=0.
    Evidence: .sisyphus/evidence/task-10-fault-suite.txt

  Scenario: Edge path degraded thresholds
    Tool: Bash
    Steps: Run ./scripts/fault_suite.sh --degraded
    Expected: Behavior matches existing degraded contract and evidence records threshold outcomes.
    Evidence: .sisyphus/evidence/task-10-fault-suite-error.txt
  ```

  **Commit**: YES | Message: `test(fault): migrate fault suite to dummy backend scenarios` | Files: `scripts/fault_suite.sh`

- [ ] 11. Add required real cv-mmap integration profile and gate wiring

  **What to do**: Add required integration script/profile using `/home/crosstyan/Code/cv-mmap`, with explicit preflight checks and deterministic fail messages when dependency is unavailable/misconfigured.
  **Must NOT do**: Do not fold SRS/ZLMediaKit into required PR gate.

  **Recommended Agent Profile**:
  - Category: `unspecified-high` — Reason: external dependency contract and deterministic gating.
  - Skills: [`feature-research`] — align with real server startup/runtime assumptions.
  - Omitted: [`playwright`] — not needed.

  **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8]

  **References**:
  - External: `/home/crosstyan/Code/cv-mmap` — required integration root.
  - Pattern: `scripts/release_gate.sh:101-117` — existing gate sequencing.
  - Docs: `docs/smoke/srs.md`, `docs/smoke/zlm.md` — keep optional-only placement.

  **Acceptance Criteria**:
  - [ ] New integration profile script exits 0 when real cv-mmap profile is healthy.
  - [ ] Fails with clear actionable message if profile cannot be started or connected.

  **QA Scenarios**:
  ```
  Scenario: Happy path real integration profile
    Tool: Bash
    Steps: Run integration script with --cvmmap-root /home/crosstyan/Code/cv-mmap and valid runtime options.
    Expected: End-to-end profile passes and emits evidence bundle.
    Evidence: .sisyphus/evidence/task-11-real-profile.txt

  Scenario: Failure path missing cv-mmap root
    Tool: Bash
    Steps: Run integration script with non-existent --cvmmap-root.
    Expected: Deterministic preflight failure with non-zero exit and explicit missing-path reason.
    Evidence: .sisyphus/evidence/task-11-real-profile-error.txt
  ```

  **Commit**: YES | Message: `test(integration): add required real cv-mmap profile` | Files: `scripts/*real-profile*.sh, docs/smoke/*.md, release gate wiring`

- [ ] 12. Final gate/docs alignment and regression sweep

  **What to do**: Update `release_gate.sh`, README, compat/caveats docs, and any evidence expectations to reflect no simulator binary, real default mode, dummy backend usage, and required real profile.
  **Must NOT do**: Do not alter scope constraints (no rtsp/webrtc/audio) or evidence key names unless helper tooling is updated in same task.

  **Recommended Agent Profile**:
  - Category: `writing` — Reason: high-accuracy docs+gate alignment.
  - Skills: [`code-edit`] — script/doc synchronized edits.
  - Omitted: [`frontend-ui-ux`] — irrelevant.

  **Parallelization**: Can Parallel: NO | Wave 3 | Blocks: [] | Blocked By: [2,3,4,6,7,8,9,10,11]

  **References**:
  - Pattern: `scripts/release_gate.sh:119-141` — required evidence bundle checks.
  - Pattern: `README.md` quickstart/manual test sections currently showing `cvmmap_sim`.
  - Docs: `docs/compat_matrix.md`, `docs/caveats.md` — keep optional checks separation and scope text.

  **Acceptance Criteria**:
  - [ ] Release gate passes with updated mandatory checks and evidence expectations.
  - [ ] Documentation examples no longer require `cvmmap_sim` and accurately describe `--input-mode` behavior.
  - [ ] No stale references to removed simulator binary remain.

  **QA Scenarios**:
  ```
  Scenario: Happy path full release gate
    Tool: Bash
    Steps: Run ./scripts/release_gate.sh
    Expected: PASS with updated gate summary and evidence bundle.
    Evidence: .sisyphus/evidence/task-12-release-gate.txt

  Scenario: Failure path evidence gate injection
    Tool: Bash
    Steps: Run ./scripts/release_gate.sh --inject-failure evidence
    Expected: Deterministic FAIL at evidence gate with clear failing_gates output.
    Evidence: .sisyphus/evidence/task-12-release-gate-error.txt
  ```

  **Commit**: YES | Message: `docs(gate): align release gate and docs with real/dummy backend model` | Files: `scripts/release_gate.sh, README.md, docs/*.md, helper references`

## Final Verification Wave (4 parallel agents, ALL must APPROVE)
- [ ] F1. Plan Compliance Audit — oracle
- [ ] F2. Code Quality Review — unspecified-high
- [ ] F3. Real Manual QA — unspecified-high (+ playwright if UI)
- [ ] F4. Scope Fidelity Check — deep

## Commit Strategy
- Commit in atomic slices by wave; no cross-wave mixed commits.
- Suggested pattern:
  - `refactor(cli): remove manual help paths and unify CLI11`
  - `refactor(input): add real/dummy FrameSource and remove cvmmap_sim target`
  - `test(integration): update acceptance/fault/release gates and real cv-mmap profile`
  - `docs(runtime): align README/compat/caveats with new backend model`

## Success Criteria
- All mandatory gates pass with no simulator binary.
- Real cv-mmap integration profile is required and passing when local dependency exists.
- Dummy backend fully replaces simulator role for standalone matrix/fault coverage.
- CLI experience is deterministic, CLI11-native, and free from handcrafted help output.
- CVMMAP URI behavior in streamer/C++ client is contract-compatible with python client semantics.