gps-denied-onboard/_docs/03_implementation/batch_04_cycle4_report.md

Batch Report — cycle 4, batch 04

Batch: 04 Cycle: 4 Tasks: AZ-842 Total complexity: 3 SP Date: 2026-05-29 Commit: pending (this batch)

Task Selection

AZ-842 (docs — replay_protocol.md Invariant 12 extension + Invariant 14 cycle-4 + architecture.md AZ-777 supersession + cycle-4 redesign sub-section + tests/e2e/replay/README.md AZ-835 orchestrator-test section + license attribution) ships solo. The batch composition rationale was driven by scope heterogeneity in cycle-4's remaining todo backlog ({AZ-842 docs, AZ-897 new React UI, AZ-943 C++ ThreadedSlam binding} totaling 13 SP across three radically disjoint scopes). Single-task batch keeps code review tractable; AZ-897 and AZ-943 each remain non-trivial (5 SP) and trigger their own Complexity Budget Check when their batches start.

Task Results

Task	Status	Files Modified	Tests	AC Coverage	Issues
AZ-842_replay_protocol_and_orchestrator_docs	Done	3 modified	n/a (docs only)	8/8 (AC-1, AC-1b, AC-2, AC-2b, AC-3, AC-4, AC-5, AC-6)	1 documented spec deviation + 1 out-of-scope hygiene gap

Files touched

Documentation (_docs/02_document/):

• MODIFIED _docs/02_document/contracts/replay/replay_protocol.md:
  • Sub-invariant 12.c added — route-driven seeding supersedes the legacy AZ-777 bbox-driven approach (~100× tile efficiency, "did fly vs. might fly" honesty rationale).
  • Sub-invariant 12.d added — fixture failure-handling contract (validation/terminal re-raise; transient → C11 backoff retry × 3 with full-history-on-exhaust message).
  • Invariant 14 added with sub-invariants 14.a-14.d covering cycle-4's single-canonical-clock model, the CSV-driven primary path (AZ-894), the tlog adapter's audit-only role (AZ-895), the auto-sync deprecation (AZ-895), and the operator-UI follow-up pointer (AZ-897).
• MODIFIED _docs/02_document/architecture.md:
  • Added "AZ-777 Phase 3+ superseded by Epic AZ-835" supersession block inside the satellite-provider integration section.
  • Added new sub-section "Replay input redesign (cycle 4 — single canonical clock + CSV-driven path)" with a 4-row ticket table (AZ-894 / AZ-895 / AZ-896 / AZ-897) and the architectural rationale tying back to Invariant 14 of the replay protocol.

Tests-adjacent documentation (tests/e2e/replay/):

• MODIFIED tests/e2e/replay/README.md:
  • Top header restructured for two distinct entry points (AZ-265/AZ-404 derkachi_1min vs. AZ-835/AZ-840 orchestrator).
  • New section "AZ-835 orchestrator test — full (tlog, video, calibration) loop (Tier-2 only)" covering required inputs, Tier-2 invocation (Jetson SSH + env vars), skip gates in evaluation order, expected runtime (≤ 8 min cold, ≤ 60 s warm), and verdict report location semantics.
  • New section "Imagery source license attribution (dev/research use only)" carrying the "Imagery © Google" attribution and the production-deployment caveat (Google Maps Platform licensing review or CC-BY migration TBD).
  • New section "Epic AZ-835 ticket map" with explicit Jira links to AZ-836 / AZ-838 / AZ-839 / AZ-840 / AZ-842 + cycle-4 redesign tickets AZ-894 / AZ-895 / AZ-896 / AZ-897.

AC verification

Each AC verified by Grep on the modified file's content (no code-path tests exist for prose):

AC	Verification
AC-1	Sub-invariant 12.c + Sub-invariant 12.d present in replay_protocol.md — bbox-supersedure rationale + transient-retry-3-attempts contract
AC-1b	Invariant 14 block with sub-invariants 14.a (CSV path, AZ-894), 14.b (tlog audit-only, AZ-895), 14.c (auto-sync deprecation, AZ-895), 14.d (UI follow-up, AZ-897), plus cross-link to csv_replay_format.md (AZ-896)
AC-2	AZ-777 Phase 3+ superseded by Epic AZ-835 block in architecture.md satellite-provider integration section, pointing at AZ-839 (Phase 3) + AZ-842 (Phase 5) child tickets
AC-2b	### Replay input redesign (cycle 4 — single canonical clock + CSV-driven path) sub-section in architecture.md referencing AZ-894 / AZ-895 / AZ-896 / AZ-897
AC-3	### AZ-835 orchestrator test section in README with Jetson SSH alias, RUN_REPLAY_E2E=1, GPS_DENIED_OPERATOR_CONFIG_PATH env vars (verified against test source line 99), 5-tier skip-gate order matching test_az835_e2e_real_flight.py lines 29-36, expected runtime, and verdict report path
AC-4	Epic AZ-835 + children AZ-836 / AZ-838 / AZ-839 / AZ-840 + cycle-4 redesign AZ-894 / AZ-895 / AZ-896 / AZ-897 referenced in all three modified docs (AZ-841 omitted as an active-epic link per the AC; mentioned once in architecture.md AZ-777 supersession block as a backlog-deferred historical note only)
AC-5	Imagery © Google + dev/research use only strings present in tests/e2e/replay/README.md
AC-6	_docs/02_tasks/_dependencies_table.md preamble already covers AZ-835 + children + cycle-4 redesign (verified in cycle-3/cycle-4 prior preamble updates); _docs/02_tasks/done/AZ-777_derkachi_c6_reference_fixture.md already carries the SUPERSEDED banner pointing at AZ-839 / AZ-841 / AZ-842 — both cross-reference obligations were satisfied by prior work and verified during this batch

AC Test Coverage: 8 of 8 covered (docs-only — coverage = content presence verified by Grep)

Code Review Verdict: PASS_WITH_WARNINGS

Findings

Finding 1 — Spec deviation (documented, accepted by agent; flagged for user awareness)

• Severity: Medium
• Category: Spec-Gap
• Location: _docs/02_tasks/todo/AZ-842_replay_protocol_and_orchestrator_docs.md lines 27, 37, 39, 65 (AC-1b)
• Description: AC-1b directs "new Invariant 13 (cycle-4)" but Invariant 13 already exists in replay_protocol.md (C4↔C5 composition-profile pairing matrix, added by AZ-776 / ADR-012 cycle 3). It is referenced by number in architecture.md:781 (ADR-012 consequences), _docs/02_document/components/06_c4_pose/description.md:11 (component doc), and the AZ-776 unit test docstring.
• Resolution: Added the cycle-4 content as Invariant 14 instead. Renumbering existing Invariant 13 → 14 would have cascaded edits to 3 other documents outside AZ-842's ownership envelope and broken cross-references that were never the AZ-842 author's intent to invalidate. The AZ-842 spec was authored before the Invariant 13 collision was visible.
• Suggested follow-up: refresh the local AZ-842 spec mirror to say "Invariant 14" in the AC text (post-close hygiene). Not a tracker-write blocker.

Finding 2 — Out-of-scope hygiene gap (do NOT auto-fix)

• Severity: Low
• Category: Maintainability
• Location: _docs/02_document/module-layout.md Build-Time Exclusion Map
• Description: BUILD_CSV_REPLAY_ADAPTER flag is now mentioned in _docs/02_document/architecture.md and _docs/02_document/contracts/replay/replay_protocol.md (this batch's edits) and exists in src/, docker-compose.test.yml, docker-compose.test.jetson.yml, and unit tests, but is NOT enumerated in module-layout.md's Build-Time Exclusion Map. Inherited gap from cycle-4 AZ-894.
• Resolution: NOT fixed in this batch — module-layout.md is outside AZ-842's OWNED envelope (the file is owned by the decompose Step 1.5 / refactor cycle-3 AZ-846 cadence). Suggested as a cycle-5+ hygiene PBI (no blocker filed this session per scope-discipline rule).

Auto-fix Attempts

0 — neither finding is auto-fix-eligible (Finding 1 is a documented design choice; Finding 2 is out of OWNED scope).

Stuck Agents: None

Jira description sync

The Jira description on AZ-842 is the pre-cycle-4-rescope version (2 SP, AC-1..AC-6 without AC-1b / AC-2b / AC-7, no cycle-4 narrative). The local spec mirror is the more current source. Description sync will happen at the Step 12 transition (In Progress → In Testing) so the ticket-side AC list matches what shipped.

Next Batch

Remaining cycle-4 todo backlog: AZ-897 (5 SP — first operator-facing React + Tailwind UI), AZ-943 (5 SP — OKVIS2 ThreadedSlam binding, replaces AZ-332 skeleton). AZ-835 epic file moves to done/ with this batch (its last todo-leaf child AZ-842 closes here).

Recommended next batch composition (subject to Complexity Budget Check at planning time): batch 05 = AZ-897 alone or batch 05 = AZ-943 alone. Either ordering is valid — they have no inter-dependency. The implement skill's batch loop will re-evaluate.