mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-23 00:01:14 +00:00
[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:
@@ -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"
|
||||
Reference in New Issue
Block a user