[AZ-899] [AZ-900] [AZ-901] Baseline doc + retro gate + EVIDENCE_OUT fix

AZ-899: create _docs/02_document/architecture_compliance_baseline.md
seeded with 0 violations and the 2026-05-20 structural snapshot facts
(15 inventory entries, 0 import cycles, 5 contract files). Documents
the append-on-violation / mark-resolved-on-fix / snapshot-refresh
protocol so cumulative reviews can emit Baseline Delta sections.
Closes cycle-1 retro Top-3 #3 (third attempt).

AZ-900: codify LESSONS 2026-05-26 [process] in
.cursor/skills/autodev/flows/existing-code.md - Re-Entry After
Completion now hosts a Previous-Cycle Retro Existence Gate that
BLOCKS the cycle increment if no _docs/06_metrics/retro_*.md file
dated within [cycle_start, cycle_end] exists. Skipped on
state.cycle == 1. Presents Choose A (author retro) / B (stub +
leftover) / C (abort). state.md - Session Boundaries gains a
cross-reference bullet.

AZ-901: fix e2e/runner/conftest.py:56 EVIDENCE_OUT default - host
pytest now resolves <repo_root>/e2e-results/evidence/ instead of
/e2e-results/evidence (container-only path; crashed on macOS / non-
root Linux). Docker + Jetson harnesses unaffected (they pass
--evidence-out explicitly). Verified locally: 24 SKIPPED, exit 0,
evidence written. Closes leftover 2026-05-26_evidence_out_default_path.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-26 17:18:54 +03:00
parent 940066bee2
commit aa8b9f2ee9
8 changed files with 190 additions and 54 deletions
@@ -0,0 +1,78 @@
# 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"