docs(sisyphus): docs

.gitignore

@@ -68,4 +68,6 @@ Testing/
 .cache/
 
 # local evidence artifacts generated by standalone scripts
-.sisyphus/
+.sisyphus/evidence/
+.sisyphus/evidence/*
+.sisyphus/boulder.json

.sisyphus/notepads/major-refactor-cli11-cvmmap/learnings.md

@@ -0,0 +1,8 @@
+- 2026-03-06: Updated `src/main_streamer.cpp` to remove explicit `has_help_flag`/`print_help` preflight checks and treat empty/`help` parse result as graceful exit.
+- `parse_runtime_config` in `src/config/runtime_config.cpp` now returns `std::unexpected("")` for help path (via `app.exit(e) == 0`) and `std::unexpected("parse_error")` for parse failures.
+- Kept `--help` behavior delegated to CLI11: `./build/cvmmap_streamer --help` prints CLI11-generated help and exits non-zero through parse path logging in current wrapper.
+- Verified with `cmake --build build` and CLI smoke commands: `--help`, `--definitely-invalid`, and no-arg execution (shows runtime config then fails runtime stage as expected).
+
+- 2026-03-06: applied concrete edits: streamer now relies on parse_runtime_config returning "help"/"parse_error" and main handles those exits directly (help=>0, parse_error=>2).
+
+- 2026-03-06: completed remaining task checks: grep-verified no manual streamer help preflight in main, plus help parse/parse_error control flow validated with --help exit 0 and invalid flag exit 2; note appended.

.sisyphus/plans/major-refactor-cli11-cvmmap.md

@@ -0,0 +1,659 @@
+# 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.

AGENTS.md

@@ -0,0 +1,25 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Core code lives in `src/` and public headers in `include/cvmmap_streamer/`. The main runtime is `src/main_streamer.cpp`; shared logic is split by concern under `src/config`, `src/core`, `src/ipc`, `src/pipeline`, `src/protocol`, and `src/metrics`. Test utilities are standalone binaries in `src/testers/`. Automation and release gates live in `scripts/`, while operator notes and smoke-test profiles live in `docs/`. Third-party dependencies are vendored in `lib/` and should only be changed deliberately.
+
+## Build, Test, and Development Commands
+Configure and build with:
+
+```bash
+cmake -B build -S .
+cmake --build build
+```
+
+This produces `build/cvmmap_streamer`, `build/rtp_receiver_tester`, `build/rtmp_stub_tester`, and `build/ipc_snapshot_tester`.
+
+Use `cmake --fresh -B build -S .` if CMake caches stale dependency paths. Run the mandatory acceptance matrix with `./scripts/acceptance_standalone.sh` and the baseline fault suite with `./scripts/fault_suite.sh`. For targeted manual checks, run the built testers directly against `build/cvmmap_streamer`.
+
+## Coding Style & Naming Conventions
+This project targets C++23. Follow the existing style: tabs for indentation, braces on the same line, `snake_case` for functions and variables, `PascalCase` for types and enums, and lowercase directory names by subsystem. Keep headers under `include/cvmmap_streamer/...` aligned with their implementation paths where practical. No formatter or linter config is checked in, so match the surrounding file exactly before submitting changes.
+
+## Testing Guidelines
+There is no top-level unit-test framework in this repo; verification is primarily binary- and script-driven. Add behavior checks through `src/testers/` and extend the shell suites in `scripts/` when introducing new protocol or fault scenarios. Prefer deterministic inputs such as the dummy backend (`--input-mode dummy`) and keep labels short. Review generated evidence under `.sisyphus/evidence/` when validating failures.
+
+## Commit & Pull Request Guidelines
+Recent history uses Conventional Commit prefixes such as `feat(...)`, `fix(...)`, `refactor(...)`, `test(...)`, `build(...)`, and `chore(...)`. Continue that pattern and keep scopes specific, for example `refactor(protocol): simplify wire codec setup`. PRs should explain the runtime impact, list the commands you ran, and attach relevant logs or screenshots when output behavior changes. Link any issue or task ID when one exists.