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

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.