gps-denied-onboard/_docs/02_tasks/todo/AZ-899_architecture_compliance_baseline.md

Land architecture_compliance_baseline.md (cycle-3 retro #3, third try)

Task: AZ-899_architecture_compliance_baseline Name: Create _docs/02_document/architecture_compliance_baseline.md so cumulative reviews can emit ## Baseline Delta rows Description: Cycle-1 retro Top-3 Improvement Action #3, repeated in cycle-3 retro Top-3 #3. The file has been unmade across cycles 2 and 3, leaving cumulative reviews unable to quantify carried-over / resolved / newly-introduced architecture violations per cycle. Seed the baseline from _docs/06_metrics/structure_2026-05-20.md with 0 violations, freeze the snapshot semantics, and wire the existing-code flow's Step 2 to reference it. Complexity: 1 SP Dependencies: None (operates on existing artifact _docs/06_metrics/structure_2026-05-20.md) Component: documentation only — no source code change Tracker: AZ-899 (https://denyspopov.atlassian.net/browse/AZ-899) Epic: (none — cycle-4 process housekeeping)

Problem

Cycle-3 retro § Structural Metrics:

_docs/02_document/architecture_compliance_baseline.md still does not exist — cycle-1 retro Top-3 Improvement Action #3 was NOT delivered in cycles 2 or 3.

Without a baseline, cumulative reviews log "_docs/02_document/architecture_compliance_baseline.md does NOT exist → no Baseline Delta section emitted". Structural regressions (new cycles in the import graph, newly-introduced violations) therefore cannot be quantified across cycles — only verified pairwise per batch.

Outcome

• Cumulative-review reports starting from cycle-4 batch 1 emit a ## Baseline Delta section that quantifies new vs. resolved vs. carried-over architecture violations.
• Cycle-end retros can compare structural deltas across cycles using a single canonical baseline document instead of re-deriving from the previous cycle's snapshot.

Scope

Included

• Create _docs/02_document/architecture_compliance_baseline.md seeded with 0 violations.
• Reference _docs/06_metrics/structure_2026-05-20.md as the source-of-truth snapshot from which the baseline was derived.
• Document the file's update protocol: a new violation found in a cumulative review is appended (with batch ID, severity, finding ID); a resolution is recorded by marking the row RESOLVED in batch <ID>.
• Document the snapshot-refresh trigger: any cycle that materially changes structure (component count, cross-component edges, new contracts) re-snapshots via python -m gps_denied_onboard.tools.structure_snapshot (or equivalent existing script — verify before reference).

Excluded

• Refactoring source code to fix violations — none currently exist.
• Adding new component scaffolding — out of scope.
• Modifying code-review or retrospective skills — they already reference the file; the only change needed is making the referenced file exist.

Acceptance Criteria

AC-1: Baseline file exists with 0 violations Given a fresh repo checkout When ls _docs/02_document/architecture_compliance_baseline.md runs Then the file exists and its ## Violations section is explicitly empty (or marked "None at baseline")

AC-2: Baseline references the structural snapshot Given the baseline file When read Then it includes a ## Source section pointing at _docs/06_metrics/structure_2026-05-20.md and lists the structural facts (15 components, 0 import cycles, 5 contract files) that establish the "0 violations" claim

AC-3: Update protocol documented Given the baseline file When read Then it includes an ## Update Protocol section describing append-on-violation, mark-resolved-on-fix, and the snapshot-refresh trigger

AC-4: Cumulative-review hook verified Given the baseline file in place When the cycle-4 first cumulative-review report is generated Then the report emits a ## Baseline Delta section (even if empty: "0 new, 0 resolved, 0 carried-over")

Constraints

• File format: markdown, matches the structure of _docs/06_metrics/structure_2026-05-20.md style.
• No source code change permitted under this ticket — strictly documentation.

Risks & Mitigation

Risk 1: Future violations slip past the baseline

• Risk: A cumulative review finds a violation but the reviewer forgets to append it to the baseline.
• Mitigation: The code-review skill (referenced in cycle-3 retro Suggested Updates) should be updated separately to auto-append; this ticket only delivers the baseline file. The follow-up belongs in cycle 5 if needed.

References

• Cycle-3 retro: _docs/06_metrics/retro_2026-05-26.md § Top 3 Improvement Actions #3
• Cycle-1 retro: _docs/06_metrics/retro_2026-05-20.md § Top 3 Improvement Actions #3 (original)
• Source snapshot: _docs/06_metrics/structure_2026-05-20.md
• Existing-code flow Step 2: .cursor/skills/autodev/flows/existing-code.md § "Step 2 — Architecture Baseline Scan"