chore: WIP pre-implement

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-26 17:09:13 +03:00
parent be743a72d6
commit 940066bee2
31 changed files with 1709 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"