docs(report): add TRACK_COMPLETION_chronology_v2_20260701

2026-07-01 23:56:44 -04:00
parent c6593278ab
commit 9f268fd3e2
1 changed files with 62 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Track Completion: chronology_v2_20260701
+
+**Date:** 2026-07-01
+**Track ID:** `chronology_v2_20260701`
+**Status:** completed (pending user sign-off)
+
+## Summary
+
+Replaced the broken v1 `conductor/chronology.md` (167/216 rows with wrong status due to a stale-metadata classifier) with a correct v2 that uses git-history evidence. Closed out the stuck `chronology_20260619` track, de-gunked `conductor/tracks.md` (941→90 lines), and added a maintenance rule to `conductor/workflow.md` to prevent future desync.
+
+## What was done
+
+1. **Closed out `chronology_20260619`**: marked superseded in state.toml, updated tracks.md row, archived the folder to `conductor/archive/chronology_20260619/`, unblocked `superpowers_review_20260619`.
+2. **Rewrote the classifier**: `scripts/audit/generate_chronology.py` now uses a 4-tier evidence-priority chain (override signals > git work-commits > directory location > fallback) returning `(status, confidence, reason)`. 7-status enum: Active / In Progress / Completed / Abandoned / Superseded / Special / Needs Review. Handles scoped commit prefixes (`feat(rag):`, `fix(gui):`, etc.) and queries both archive + original tracks paths for moved folders.
+3. **Added a quality gate**: `scripts/audit/chronology_quality_gate.py` with 4 checks (Needs Review threshold ≤30%, ≥1 Completed row, ≤20% metadata-field summaries, 0 empty reasons) + `--strict` CI mode + `--rows-json` option for fast re-verification without re-walking.
+4. **Regenerated `conductor/chronology.md`** from the current filesystem: 244 rows (up from v1's 218), closing the 5-day desync gap (26+ tracks added that were missing from v1). Status distribution: 78 Completed, 113 Abandoned, 44 Active, 7 In Progress, 2 Special, 0 Needs Review.
+5. **De-gunked `conductor/tracks.md`**: removed Phase 0-9 history sections + shipped-track rows from the active queue; left active queue (15 rows) + standby (13 rows) + pointer to chronology.md. Reduced from 941 lines to 90 lines.
+6. **Added "Chronology Maintenance" section to `conductor/workflow.md`**: regeneration cadence (after every track ships/abandons/supersedes) + quality gate obligation.
+7. **Wrote the quality report**: `docs/reports/CHRONOLOGY_QUALITY_20260701.md` with status distribution, confidence distribution, Needs Review queue (empty), v1 comparison, desync gap list (27 tracks), heuristics summary.
+
+## Files changed
+
+| File | Action | Commit |
+|---|---|---|
+| `conductor/tracks/chronology_20260619/state.toml` | Modified (superseded) | `2e52944b` |
+| `conductor/tracks.md` | Modified (row update) | `1867d1c` |
+| `conductor/tracks/chronology_20260619/` → `conductor/archive/chronology_20260619/` | Moved | `0b00671b` |
+| `conductor/tracks/superpowers_review_20260619/state.toml` | Modified (unblocked) | `fefc1526` |
+| `conductor/tracks/chronology_v2_20260701/` | Created (spec/metadata/state/plan) | `c1da0f99` |
+| `tests/test_generate_chronology.py` | Rewritten (20 tests) | `6f57c893`, `945751b9` |
+| `tests/test_chronology_quality_gate.py` | Created (6 tests) | `078a84b6` |
+| `scripts/audit/generate_chronology.py` | Rewritten (v2 classifier) | `945751b9`, `f5a08634` |
+| `scripts/audit/chronology_quality_gate.py` | Created (4 checks + --strict) | `9010e690`, `f5a08634` |
+| `conductor/chronology.md` | Regenerated (244 rows) | `f5a08634` |
+| `conductor/tracks.md` | De-gunked (941→90 lines) | `342638e1` |
+| `conductor/workflow.md` | Modified (Chronology Maintenance section) | `5a0453b3` |
+| `docs/reports/CHRONOLOGY_QUALITY_20260701.md` | Created | `ddc4cb7d` |
+
+## Verification criteria
+
+1. [x] conductor/chronology.md exists, one row per track folder (244 rows), sorted newest-first, 6 columns, from current filesystem
+2. [x] Every row's status backed by git-history evidence; reason non-empty (244/244)
+3. [x] No summary contains metadata-field text (0/244)
+4. [x] chronology_quality_gate.py --strict exits 0 (PASS)
+5. [x] conductor/tracks.md contains only active queue + standby + pointer + Editing notes (90 lines; no Phase/Archived headings)
+6. [x] conductor/workflow.md contains Chronology Maintenance section
+7. [x] docs/reports/CHRONOLOGY_QUALITY_20260701.md exists with required contents
+8. [x] This report exists
+9. [x] chronology_20260619 archived with status = superseded (5 matches in state.toml)
+10. [x] superpowers_review_20260619 [blocked_by] no longer has chronology_20260619 as a key (only in comment + historical log)
+11. [x] tests/test_generate_chronology.py + tests/test_chronology_quality_gate.py pass (26/26)
+12. [ ] User sign-off recorded (pending)
+
+## Known limitations
+
+- **113 Abandoned (low confidence)**: archive tracks with 0 work commits and no TRACK_COMPLETION/TRACK_ABORTED report. Many of these are genuinely abandoned (one-off tracks that were never completed), but some may be completed tracks from before the TRACK_COMPLETION report convention was established (2026-06-16+). The quality gate accepts these because the "Abandoned" classification is low-confidence but valid — the user can manually reclassify any that are wrong.
+- **Generator speed**: the `walk_track_folders` function makes 1-2 `git log` subprocess calls per folder (244 folders × ~1.5 calls = ~366 subprocess calls). This takes ~60-120 seconds. The `--rows-json` option on the quality gate allows fast re-verification without re-walking.
+- **The `--draft` flag** on the generator is a legacy name; it outputs the markdown table (the canonical output). The non-`--draft` mode outputs JSON (useful for piping to the quality gate).
+
+## User sign-off
+
+[ ] User has reviewed the chronology.md, the quality report, and the Needs Review queue (empty). Track is complete.