|
|
|
@@ -0,0 +1,444 @@
|
|
|
|
|
# Chronology v2 Redo — Design Spec
|
|
|
|
|
|
|
|
|
|
**Date:** 2026-07-01
|
|
|
|
|
**Track ID:** `chronology_v2_20260701`
|
|
|
|
|
**Priority:** A (meta-tooling / infrastructure)
|
|
|
|
|
**Status:** design (pre-spec)
|
|
|
|
|
**Ancestors:**
|
|
|
|
|
- `conductor/tracks/chronology_20260619/spec.md` (the v2 rewrite spec, 354 lines — designed but never executed)
|
|
|
|
|
- `docs/reports/2026-06-15/CHRONOLOGY_TRACK_HANDOVER_20260620.md` (the v1 failure report, 128 lines)
|
|
|
|
|
- `docs/reports/2026-06-15/CHRONOLOGY_MIGRATION_20260619.md` (the v1 migration report)
|
|
|
|
|
- `docs/reports/2026-06-15/TRACK_COMPLETION_chronology_20260619.md` (the v1 end-of-track report)
|
|
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
|
|
|
|
The `chronology_20260619` track produced a broken `conductor/chronology.md` (v1):
|
|
|
|
|
167 of 216 rows had wrong status (the classifier read stale `metadata.json.status`
|
|
|
|
|
instead of git history), summaries were metadata-field text instead of track
|
|
|
|
|
descriptions, and the per-row cross-check was bypassed. A v2 rewrite was specced
|
|
|
|
|
and planned in detail but never executed. The track sits at `current_phase=10`
|
|
|
|
|
pending user sign-off that never came, blocking `superpowers_review_20260619`.
|
|
|
|
|
|
|
|
|
|
This track is the redo: a **fresh track** that closes out the old one, adopts
|
|
|
|
|
the v2 design as a starting point, revises it for the current project state
|
|
|
|
|
(5+ days of desync, new track patterns, the tracks.md bloat), and executes it
|
|
|
|
|
through to a user sign-off that is actionable this time.
|
|
|
|
|
|
|
|
|
|
## What v1 Got Wrong (from the records)
|
|
|
|
|
|
|
|
|
|
Per `CHRONOLOGY_TRACK_HANDOVER_20260620.md`:
|
|
|
|
|
|
|
|
|
|
1. **`_classify_status()` reads `metadata.json.status`** — a stale field set when
|
|
|
|
|
each track was created, rarely updated when work completed or was abandoned.
|
|
|
|
|
167/216 rows had wrong status.
|
|
|
|
|
2. **Summaries are metadata-field text** (`**Priority:** A (foundational...)`,
|
|
|
|
|
`**Date:** 2026-06-20`) not actual track descriptions.
|
|
|
|
|
3. **Phase 8 per-row cross-check was bypassed** in favor of bulk structural
|
|
|
|
|
verification; the manual summary-adequacy check was partial (15-row sample).
|
|
|
|
|
4. **Phase 6 user review gate was bypassed** in the autonomous session.
|
|
|
|
|
5. **No quality gate** to detect a broken classifier before the chronology ships.
|
|
|
|
|
6. **No maintenance plan** — the chronology desynced within days because nobody
|
|
|
|
|
regenerated it after new tracks shipped.
|
|
|
|
|
|
|
|
|
|
The five lessons from the handover (lines 88-98):
|
|
|
|
|
1. Bypassing the manual review clause was the original sin.
|
|
|
|
|
2. `metadata.json` is a snapshot, not a source of truth.
|
|
|
|
|
3. Git history is the project's audit log — use it.
|
|
|
|
|
4. Default to "when in doubt, ask" — the chronology is read by humans.
|
|
|
|
|
5. The user said "manual review" twice; both times an interpretation was found
|
|
|
|
|
to be less strict — listen to the literal request.
|
|
|
|
|
|
|
|
|
|
## Goals
|
|
|
|
|
|
|
|
|
|
1. Produce a correct `conductor/chronology.md` where every row's status is
|
|
|
|
|
backed by git-history evidence, not stale metadata.
|
|
|
|
|
2. Produce a per-row evidence artifact (the quality report) so the user can
|
|
|
|
|
audit the classification without re-deriving it.
|
|
|
|
|
3. Close out `chronology_20260619` (mark superseded, archive, unblock
|
|
|
|
|
`superpowers_review_20260619`).
|
|
|
|
|
4. De-gunk `conductor/tracks.md` — remove shipped/completed tracks from the
|
|
|
|
|
active queue, remove the Phase 0-9 history sections that duplicate
|
|
|
|
|
chronology.md, leave only the active queue + standby + a pointer.
|
|
|
|
|
5. Add a `conductor/workflow.md` maintenance rule so the chronology is
|
|
|
|
|
regenerated after each track ships (closes the desync root cause).
|
|
|
|
|
6. Ship a quality-gate script that catches a broken classifier before it
|
|
|
|
|
ships (closes the "no quality gate" root cause).
|
|
|
|
|
|
|
|
|
|
## Non-Goals
|
|
|
|
|
|
|
|
|
|
- Fixing or executing `superpowers_review_20260619` (just unblocking it).
|
|
|
|
|
- Changing how `metadata.json.status` is maintained going forward (the
|
|
|
|
|
classifier uses git history, not metadata; metadata staleness is no longer
|
|
|
|
|
the problem).
|
|
|
|
|
- Archiving the 66 folders in `conductor/tracks/` that are already shipped
|
|
|
|
|
(separate cleanup; the chronology indexes them regardless of location).
|
|
|
|
|
- Renaming or restructuring `conductor/archive/` (out of scope; the
|
|
|
|
|
chronology walks it as-is).
|
|
|
|
|
- A broader `workflow.md` review for other stale rules (the only workflow.md
|
|
|
|
|
change is the chronology maintenance section).
|
|
|
|
|
|
|
|
|
|
## Design
|
|
|
|
|
|
|
|
|
|
### 1. New track identity + old track close-out
|
|
|
|
|
|
|
|
|
|
**New track:** `chronology_v2_20260701` (Priority A; meta-tooling/infrastructure).
|
|
|
|
|
Fresh track, not a continuation of `chronology_20260619`.
|
|
|
|
|
|
|
|
|
|
**Old track close-out (Phase 1):**
|
|
|
|
|
- Mark `chronology_20260619` as superseded in its `state.toml`
|
|
|
|
|
(`status = "superseded"`, `current_phase = 10`, add a `[supersession]`
|
|
|
|
|
section pointing to `chronology_v2_20260701`).
|
|
|
|
|
- Update its tracks.md row (line 64) to reflect supersession.
|
|
|
|
|
- Archive `conductor/tracks/chronology_20260619/` →
|
|
|
|
|
`conductor/archive/chronology_20260619/`. The v2 spec/plan are preserved
|
|
|
|
|
in git history; the new track references them by commit SHA.
|
|
|
|
|
- **Unblock `superpowers_review_20260619`** — remove `chronology_20260619`
|
|
|
|
|
from its `state.toml` `[blocked_by]` entirely (no re-gating on the new
|
|
|
|
|
track).
|
|
|
|
|
|
|
|
|
|
**v2 design adoption:** The new track's spec explicitly cites
|
|
|
|
|
`conductor/tracks/chronology_20260619/spec.md` (the v2 rewrite spec) and
|
|
|
|
|
`CHRONOLOGY_TRACK_HANDOVER_20260620.md` (the failure report) as its design
|
|
|
|
|
ancestors. It adopts the v2 status enum, the git-history classifier approach,
|
|
|
|
|
and the quality-gate concept — with the revisions below.
|
|
|
|
|
|
|
|
|
|
### 2. The six revisions to v2
|
|
|
|
|
|
|
|
|
|
#### Revision 1 — The desync gap (regenerate from current filesystem)
|
|
|
|
|
|
|
|
|
|
v2 was specced when the newest track was ~2026-06-20. The chronology now needs
|
|
|
|
|
to cover 5+ more days of tracks: the layout saga
|
|
|
|
|
(`default_layout_install_20260629`, `default_layout_extract_20260629`,
|
|
|
|
|
`default_layout_install_followup_20260629`), the MMA quarantine
|
|
|
|
|
(`mma_quarantine_rag_test_decoupling_20260701`), the module_taxonomy abort +
|
|
|
|
|
cleanup (`module_taxonomy_refactor_20260627`, `post_module_taxonomy_de_cruft_20260627`),
|
|
|
|
|
`cruft_elimination_20260627`, `directive_hotswap_harness_20260627`,
|
|
|
|
|
`enforcement_gap_closure_20260627`, `test_engine_integration_20260627`,
|
|
|
|
|
`fix_mma_concurrent_tracks_sim_20260627`, `type_alias_unfuck_20260626`,
|
|
|
|
|
`video_analysis_campaign_2_20260627`.
|
|
|
|
|
|
|
|
|
|
**Change:** The new track's first generation pass runs against the **current**
|
|
|
|
|
filesystem (all `conductor/tracks/` + `conductor/archive/` as of execution
|
|
|
|
|
day), not the 2026-06-19 snapshot. The generation script walks both directories
|
|
|
|
|
fresh each run.
|
|
|
|
|
|
|
|
|
|
#### Revision 2 — `superpowers_review_20260619` blocker resolution
|
|
|
|
|
|
|
|
|
|
v2 didn't address this because it was rewriting the same track in place. The
|
|
|
|
|
new track explicitly closes out `chronology_20260619` and removes it from
|
|
|
|
|
`superpowers_review_20260619/state.toml` `[blocked_by]` (no re-gating).
|
|
|
|
|
|
|
|
|
|
#### Revision 3 — Classifier heuristics updated for recent track patterns
|
|
|
|
|
|
|
|
|
|
v2's 5-step git-history algorithm was designed 2026-06-20. Since then, new
|
|
|
|
|
patterns emerged that it would misclassify:
|
|
|
|
|
|
|
|
|
|
- **Aborted tracks** (`module_taxonomy_refactor_20260627`): many
|
|
|
|
|
`conductor(track):` + `conductor(plan):` commits but a
|
|
|
|
|
`TRACK_ABORTED_*.md` report — classifier must detect the abort report as
|
|
|
|
|
an `Abandoned`/`Superseded` signal.
|
|
|
|
|
- **Phase 9 patches after "completion"** (`result_migration_cruft_removal_20260620`):
|
|
|
|
|
a track that "shipped" then got a patch commit days later — classifier must
|
|
|
|
|
look at the latest commit, not just count.
|
|
|
|
|
- **Tier 2 autonomous tracks**: produce many `conductor(plan):` commits (one
|
|
|
|
|
per task) — the "feat/fix/refactor vs chore/docs" heuristic must not count
|
|
|
|
|
`conductor(plan):` as a work commit.
|
|
|
|
|
- **Follow-up tracks** (`default_layout_install_followup_20260629`): short,
|
|
|
|
|
few commits, but legitimately `Completed` — the "0-1 commits + >14 days
|
|
|
|
|
old = Abandoned" rule would misfire.
|
|
|
|
|
|
|
|
|
|
**Change:** The classifier's commit-message pattern list is extended:
|
|
|
|
|
|
|
|
|
|
- `conductor(plan):`, `conductor(state):`, `conductor(track):`,
|
|
|
|
|
`docs(spec):`, `docs(plan):` are **metadata commits**, not work commits
|
|
|
|
|
(don't count toward the "≥3 work commits = Completed" threshold).
|
|
|
|
|
- `feat:`, `fix:`, `refactor:`, `perf:`, `test:`, `docs(report):` are work
|
|
|
|
|
commits.
|
|
|
|
|
- Presence of `TRACK_ABORTED_*.md` or `TRACK_COMPLETION_*.md` in
|
|
|
|
|
`docs/reports/` matching the track ID is a **strong signal** that
|
|
|
|
|
overrides commit-count heuristics.
|
|
|
|
|
- The "last commit > 14 days = Abandoned" rule is **removed**; replaced
|
|
|
|
|
with "no work commits AND no completion/abort report = Needs Review".
|
|
|
|
|
- Confidence is reported per-row; anything below a threshold goes to the
|
|
|
|
|
Needs Review queue for manual classification.
|
|
|
|
|
|
|
|
|
|
#### Revision 4 — tracks.md de-gunk
|
|
|
|
|
|
|
|
|
|
v2's scope was only chronology.md. The new track also restructures
|
|
|
|
|
`conductor/tracks.md`:
|
|
|
|
|
|
|
|
|
|
**Current state (96KB, bloated):**
|
|
|
|
|
- 60-row "Active Tracks (Current Queue)" table — ~40 of these rows are
|
|
|
|
|
shipped/completed tracks that belong in history, not the active queue.
|
|
|
|
|
- Phase 0-9 chronological sections with Completed/Archived subsections —
|
|
|
|
|
duplicates chronology.md.
|
|
|
|
|
- 4 backlog/follow-up sections — some entries are shipped, some pending.
|
|
|
|
|
- "Recently Shipped Tracks (2026-06-29)" section at the bottom.
|
|
|
|
|
|
|
|
|
|
**Target state:**
|
|
|
|
|
- **Section 1: Active Queue** — only tracks that are genuinely unblocked and
|
|
|
|
|
ready to start OR in-progress. Shipped tracks are removed (they're in
|
|
|
|
|
chronology.md). Each row: `| # | Priority | Track | Status | Blocked By |`
|
|
|
|
|
(same columns, filtered to active-only).
|
|
|
|
|
- **Section 2: Standby / Pending Spec** — tracks with spec TBD or pending
|
|
|
|
|
decision (the backlog). Same columns.
|
|
|
|
|
- **Section 3: Pointer** — one line:
|
|
|
|
|
`> Full project history: see [chronology.md](./chronology.md)`
|
|
|
|
|
- **Delete:** Phase 0-9 sections, Completed/Archived subsections, backlog/
|
|
|
|
|
follow-up sections that duplicate chronology.md, the "Recently Shipped"
|
|
|
|
|
section, the "Archived (Closed 2026-06-23)" video analysis section.
|
|
|
|
|
- **Keep:** the "Editing this file" / archiving convention notes at the
|
|
|
|
|
bottom (from v1 Phase 4).
|
|
|
|
|
|
|
|
|
|
**Migration safety:** the full tracks.md is preserved in git history; the
|
|
|
|
|
de-gunk is a single commit. If anything is lost,
|
|
|
|
|
`git show HEAD~1:conductor/tracks.md` recovers it.
|
|
|
|
|
|
|
|
|
|
#### Revision 5 — workflow.md maintenance rule
|
|
|
|
|
|
|
|
|
|
v2 had no maintenance plan (the root cause of the desync). The new track adds
|
|
|
|
|
a section to `conductor/workflow.md`:
|
|
|
|
|
|
|
|
|
|
**New subsection under "Documentation Refresh Protocol"** (or a new top-level
|
|
|
|
|
section "Chronology Maintenance"):
|
|
|
|
|
|
|
|
|
|
> **Chronology regeneration cadence.** After every track ships (completion
|
|
|
|
|
> commit + TRACK_COMPLETION report), the implementing agent must run
|
|
|
|
|
> `uv run python scripts/audit/generate_chronology.py` to regenerate
|
|
|
|
|
> `conductor/chronology.md`. The regeneration is a single atomic commit
|
|
|
|
|
> (`docs(chronology): regenerate after <track-id> shipped`). If the
|
|
|
|
|
> regeneration produces a diff beyond the new row (e.g., status changes on
|
|
|
|
|
> other rows), the agent must investigate before committing — a status drift
|
|
|
|
|
> on an unrelated row indicates a stale classifier, not a chronology bug.
|
|
|
|
|
>
|
|
|
|
|
> **Quality gate.** `scripts/audit/chronology_quality_gate.py` runs as part
|
|
|
|
|
> of the regeneration. It fails (exit 1) if >30% of rows are classified as
|
|
|
|
|
> `Needs Review`. A failing quality gate blocks the regeneration commit.
|
|
|
|
|
|
|
|
|
|
This makes regeneration a per-track-shipping obligation, not a one-shot.
|
|
|
|
|
|
|
|
|
|
#### Revision 6 — Report(s)
|
|
|
|
|
|
|
|
|
|
Two reports:
|
|
|
|
|
|
|
|
|
|
1. **`docs/reports/TRACK_COMPLETION_chronology_v2_20260701.md`** — the
|
|
|
|
|
standard end-of-track report (what was done, files changed, verification
|
|
|
|
|
results).
|
|
|
|
|
2. **`docs/reports/CHRONOLOGY_QUALITY_20260701.md`** — the chronology-quality
|
|
|
|
|
report (new, not in v1). Contents:
|
|
|
|
|
- Total rows generated + breakdown by status (Active / In Progress /
|
|
|
|
|
Completed / Abandoned / Superseded / Special / Needs Review)
|
|
|
|
|
- Confidence distribution (high / medium / low)
|
|
|
|
|
- The Needs Review queue (list of rows that need manual classification,
|
|
|
|
|
with the evidence the classifier found)
|
|
|
|
|
- Comparison vs v1 (row count delta, status-correction count: "N rows
|
|
|
|
|
changed status vs v1")
|
|
|
|
|
- The desync gap closed (list of tracks added that were missing from v1)
|
|
|
|
|
- Classifier heuristics summary (which patterns matched, which were
|
|
|
|
|
overridden by completion/abort reports)
|
|
|
|
|
|
|
|
|
|
The quality report is the evidence artifact — it's what makes this track
|
|
|
|
|
auditable rather than "trust the script." v1 failed because there was no
|
|
|
|
|
quality gate and no evidence per row; this report is the fix.
|
|
|
|
|
|
|
|
|
|
### 3. Architecture — the generation script + quality gate
|
|
|
|
|
|
|
|
|
|
#### `scripts/audit/generate_chronology.py` (rewritten)
|
|
|
|
|
|
|
|
|
|
**Inputs:** `conductor/tracks/` + `conductor/archive/` (walked fresh each
|
|
|
|
|
run); `git log` per folder for commit evidence; `docs/reports/TRACK_COMPLETION_*.md`
|
|
|
|
|
+ `TRACK_ABORTED_*.md` for override signals.
|
|
|
|
|
|
|
|
|
|
**Extraction pipeline (per folder):**
|
|
|
|
|
1. **Date** — slug date from folder name (regex, unchanged from v1).
|
|
|
|
|
2. **ID** — folder name (unchanged).
|
|
|
|
|
3. **Status** — the new classifier (see below), returns
|
|
|
|
|
`(status, confidence, reason)`.
|
|
|
|
|
4. **Summary** — rewritten extractor: rejects lines starting with
|
|
|
|
|
`**Priority:**`, `**Date:**`, `**Initialized:**`, `**Track:**`,
|
|
|
|
|
`**Parent umbrella:**`, `**Status:**`, `**Confidence:**`; prefers
|
|
|
|
|
`metadata.json.description` if it's actual prose (not metadata-field
|
|
|
|
|
text); falls back to first non-heading, non-metadata line of `spec.md`;
|
|
|
|
|
truncates to 25 words.
|
|
|
|
|
5. **Folder** — path (unchanged).
|
|
|
|
|
6. **Range** — `git log --oneline -- <folder>` → first + last SHA + count.
|
|
|
|
|
|
|
|
|
|
**The new classifier (`_classify_status`, returning `(status, confidence, reason)`):**
|
|
|
|
|
|
|
|
|
|
Evidence sources, in priority order:
|
|
|
|
|
|
|
|
|
|
1. **Override signals (highest confidence):**
|
|
|
|
|
- `TRACK_COMPLETION_*.md` exists in `docs/reports/` matching this track
|
|
|
|
|
ID → `Completed`, confidence=high, reason="completion report found".
|
|
|
|
|
- `TRACK_ABORTED_*.md` exists → `Abandoned`, confidence=high,
|
|
|
|
|
reason="abort report found". (If `state.toml` also says `superseded`,
|
|
|
|
|
the `Superseded` classification wins — see next row.)
|
|
|
|
|
- `state.toml` `status = "superseded"` → `Superseded`,
|
|
|
|
|
confidence=high (overrides the abort-report signal if both exist).
|
|
|
|
|
2. **Git commit evidence (medium confidence):**
|
|
|
|
|
- Count work commits (`feat/fix/refactor/perf/test/docs(report):` prefixes)
|
|
|
|
|
via `git log --oneline -- <folder>`, excluding metadata commits
|
|
|
|
|
(`conductor(plan):`, `conductor(state):`, `conductor(track):`,
|
|
|
|
|
`docs(spec):`, `docs(plan):`).
|
|
|
|
|
- ≥3 work commits → `Completed`, confidence=medium, reason="N work commits".
|
|
|
|
|
- 1-2 work commits + in `tracks/` → `In Progress`, confidence=medium.
|
|
|
|
|
- 0 work commits + in `tracks/` → `Active` (spec/plan only),
|
|
|
|
|
confidence=medium.
|
|
|
|
|
3. **Directory location (low confidence):**
|
|
|
|
|
- In `archive/` + no override signal → `Completed`, confidence=low,
|
|
|
|
|
reason="archived but no completion report".
|
|
|
|
|
- In `archive/` + 0 commits → `Abandoned`, confidence=low,
|
|
|
|
|
reason="archived with 0 commits".
|
|
|
|
|
4. **Fallback:** `Needs Review`, confidence=none,
|
|
|
|
|
reason="classifier inconclusive".
|
|
|
|
|
|
|
|
|
|
**Status enum:** `Active` / `In Progress` / `Completed` / `Abandoned` /
|
|
|
|
|
`Superseded` / `Special` / `Needs Review` (7 values; v2 had 5, adding
|
|
|
|
|
`Superseded` + `Needs Review`).
|
|
|
|
|
|
|
|
|
|
**Output format:** Markdown table with 6 columns (Date, ID, Status, Summary,
|
|
|
|
|
Folder, Range) + a **"Needs Review" section** at the bottom listing rows with
|
|
|
|
|
`Needs Review` status, each with its evidence reason. Sorted newest-first. A
|
|
|
|
|
preamble header with generation date + row count.
|
|
|
|
|
|
|
|
|
|
#### `scripts/audit/chronology_quality_gate.py` (new)
|
|
|
|
|
|
|
|
|
|
**Purpose:** detect a broken classifier before the chronology ships.
|
|
|
|
|
|
|
|
|
|
**Checks:**
|
|
|
|
|
- **Needs Review threshold:** if >30% of rows are `Needs Review`, exit 1
|
|
|
|
|
(the classifier is failing on too many rows).
|
|
|
|
|
- **Status distribution sanity:** if 0 rows are `Completed`, exit 1 (the
|
|
|
|
|
classifier is misclassifying everything).
|
|
|
|
|
- **Summary quality:** if >20% of summaries still contain metadata-field
|
|
|
|
|
text (`**Priority:**` etc.), exit 1 (the summary extractor is broken).
|
|
|
|
|
- **Per-row evidence:** every row must have a non-empty `reason` from the
|
|
|
|
|
classifier; if any row has no reason, exit 1.
|
|
|
|
|
|
|
|
|
|
**Modes:** default informational (exits 0, prints report); `--strict` CI
|
|
|
|
|
gate (exits 1 on any violation). Follows the project's audit-script
|
|
|
|
|
convention (per `conductor/workflow.md` "Audit Script Policy").
|
|
|
|
|
|
|
|
|
|
#### Tests (TDD)
|
|
|
|
|
|
|
|
|
|
`tests/test_generate_chronology.py` (rewritten) +
|
|
|
|
|
`tests/test_chronology_quality_gate.py` (new). Tests for:
|
|
|
|
|
- The classifier's 7 status values + the evidence priority chain (override
|
|
|
|
|
signals > git evidence > directory > fallback).
|
|
|
|
|
- The summary extractor's rejection of metadata-field lines.
|
|
|
|
|
- The quality gate's 4 checks.
|
|
|
|
|
- Edge cases: aborted tracks with completion reports (override conflict),
|
|
|
|
|
tracks with 0 commits, archive folders with no metadata.json.
|
|
|
|
|
|
|
|
|
|
### 4. Execution plan structure (phases)
|
|
|
|
|
|
|
|
|
|
6 phases, each a checkpoint with atomic per-task commits.
|
|
|
|
|
|
|
|
|
|
#### Phase 1: Close out the old track + scaffold the new one
|
|
|
|
|
- Task 1.1: Update `chronology_20260619/state.toml` →
|
|
|
|
|
`status = "superseded"`, add `[supersession]` section. Commit.
|
|
|
|
|
- Task 1.2: Update `chronology_20260619` row in tracks.md (line 64) to
|
|
|
|
|
"superseded by `chronology_v2_20260701`". Commit.
|
|
|
|
|
- Task 1.3: Archive `conductor/tracks/chronology_20260619/` →
|
|
|
|
|
`conductor/archive/chronology_20260619/`. Commit.
|
|
|
|
|
- Task 1.4: Update `superpowers_review_20260619/state.toml` `[blocked_by]` —
|
|
|
|
|
remove `chronology_20260619` entirely. Commit.
|
|
|
|
|
- Task 1.5: Create `conductor/tracks/chronology_v2_20260701/` with
|
|
|
|
|
`spec.md`, `metadata.json`, `state.toml`, `plan.md`. Commit.
|
|
|
|
|
|
|
|
|
|
#### Phase 2: TDD the classifier + quality gate (Red)
|
|
|
|
|
- Task 2.1: Write `tests/test_generate_chronology.py` — tests for the
|
|
|
|
|
7-status classifier, evidence priority chain, summary extractor. Red.
|
|
|
|
|
- Task 2.2: Write `tests/test_chronology_quality_gate.py` — tests for the
|
|
|
|
|
4 quality-gate checks. Red.
|
|
|
|
|
|
|
|
|
|
#### Phase 3: Implement the classifier + quality gate (Green)
|
|
|
|
|
- Task 3.1: Rewrite `scripts/audit/generate_chronology.py` — the new
|
|
|
|
|
`_classify_status` returning `(status, confidence, reason)`, the
|
|
|
|
|
rewritten summary extractor, the git-history evidence pipeline. Green.
|
|
|
|
|
- Task 3.2: Create `scripts/audit/chronology_quality_gate.py` — the 4
|
|
|
|
|
checks + `--strict` mode. Green.
|
|
|
|
|
|
|
|
|
|
#### Phase 4: Regenerate chronology.md + write the quality report
|
|
|
|
|
- Task 4.1: Run the generator against the current filesystem. Capture
|
|
|
|
|
output to `conductor/chronology.md` (replacing v1). Commit.
|
|
|
|
|
- Task 4.2: Run the quality gate. If it fails, iterate on the classifier
|
|
|
|
|
(back to Phase 3) until it passes. Commit the passing state.
|
|
|
|
|
- Task 4.3: Write `docs/reports/CHRONOLOGY_QUALITY_20260701.md` — the
|
|
|
|
|
quality report. Commit.
|
|
|
|
|
|
|
|
|
|
#### Phase 5: De-gunk tracks.md + add workflow.md maintenance rule
|
|
|
|
|
- Task 5.1: Restructure `conductor/tracks.md` — remove shipped/completed
|
|
|
|
|
rows from the active queue, remove Phase 0-9 history sections, remove
|
|
|
|
|
backlog/follow-up sections that duplicate chronology.md, add the pointer
|
|
|
|
|
to chronology.md, keep the "Editing this file" notes. Single commit.
|
|
|
|
|
- Task 5.2: Add the "Chronology Maintenance" section to
|
|
|
|
|
`conductor/workflow.md` — the regeneration cadence + quality gate
|
|
|
|
|
obligation. Commit.
|
|
|
|
|
|
|
|
|
|
#### Phase 6: Verification + end-of-track report
|
|
|
|
|
- Task 6.1: Run the quality gate `--strict` mode. Confirm exit 0. Commit.
|
|
|
|
|
- Task 6.2: Verify the Needs Review queue is empty or small (the user
|
|
|
|
|
reviews any remaining rows). Commit.
|
|
|
|
|
- Task 6.3: Write
|
|
|
|
|
`docs/reports/TRACK_COMPLETION_chronology_v2_20260701.md`. Commit.
|
|
|
|
|
- Task 6.4: User sign-off (the final gate — same as v1's Phase 10, but
|
|
|
|
|
this time the quality report + evidence per row makes it actionable).
|
|
|
|
|
|
|
|
|
|
### Commit strategy
|
|
|
|
|
|
|
|
|
|
- Per-task atomic commits (no batching).
|
|
|
|
|
- Git notes per commit (task summary).
|
|
|
|
|
- Phase checkpoints after each phase (per the workflow protocol).
|
|
|
|
|
|
|
|
|
|
## Verification Criteria
|
|
|
|
|
|
|
|
|
|
1. `conductor/chronology.md` exists with one row per track folder (tracks/
|
|
|
|
|
+ archive/), sorted newest-first, 6 columns, generated from the current
|
|
|
|
|
filesystem (no 2026-06-19 snapshot pin).
|
|
|
|
|
2. Every row's status is backed by git-history evidence (not
|
|
|
|
|
`metadata.json.status`); the evidence `reason` is non-empty for every
|
|
|
|
|
row.
|
|
|
|
|
3. No summary contains metadata-field text (`**Priority:**`, `**Date:**`,
|
|
|
|
|
`**Initialized:**`, `**Track:**`, `**Parent umbrella:**`,
|
|
|
|
|
`**Status:**`, `**Confidence:**`).
|
|
|
|
|
4. `scripts/audit/chronology_quality_gate.py --strict` exits 0.
|
|
|
|
|
5. `conductor/tracks.md` contains only the active queue + standby/pending +
|
|
|
|
|
a pointer to chronology.md + the "Editing this file" notes. No Phase 0-9
|
|
|
|
|
history sections, no shipped-track rows in the active queue.
|
|
|
|
|
6. `conductor/workflow.md` contains the "Chronology Maintenance" section
|
|
|
|
|
(regeneration cadence + quality gate obligation).
|
|
|
|
|
7. `docs/reports/CHRONOLOGY_QUALITY_20260701.md` exists with the status
|
|
|
|
|
distribution, confidence distribution, Needs Review queue, v1
|
|
|
|
|
comparison, desync gap list, and heuristics summary.
|
|
|
|
|
8. `docs/reports/TRACK_COMPLETION_chronology_v2_20260701.md` exists.
|
|
|
|
|
9. `chronology_20260619` is archived (in `conductor/archive/`) with
|
|
|
|
|
`status = "superseded"` in its state.toml.
|
|
|
|
|
10. `superpowers_review_20260619/state.toml` `[blocked_by]` no longer
|
|
|
|
|
contains `chronology_20260619`.
|
|
|
|
|
11. `tests/test_generate_chronology.py` +
|
|
|
|
|
`tests/test_chronology_quality_gate.py` pass.
|
|
|
|
|
12. User sign-off recorded in the TRACK_COMPLETION report.
|
|
|
|
|
|
|
|
|
|
## Risks
|
|
|
|
|
|
|
|
|
|
- **R1 (medium):** The git-history classifier may still misclassify some
|
|
|
|
|
edge cases (e.g., tracks with `conductor(checkpoint):` commits only).
|
|
|
|
|
Mitigation: the Needs Review queue surfaces these for manual
|
|
|
|
|
classification; the quality gate fails if >30% are Needs Review.
|
|
|
|
|
- **R2 (medium):** The tracks.md de-gunk may accidentally remove a row
|
|
|
|
|
that's still active. Mitigation: the full tracks.md is preserved in git
|
|
|
|
|
history; recovery is `git show HEAD~1:conductor/tracks.md`.
|
|
|
|
|
- **R3 (low):** The workflow.md maintenance rule may not be followed by
|
|
|
|
|
future agents. Mitigation: the rule is in the operational workflow doc
|
|
|
|
|
that agents read at session start; the quality gate catches a desync
|
|
|
|
|
when the next regeneration runs.
|
|
|
|
|
|
|
|
|
|
## Out of Scope
|
|
|
|
|
|
|
|
|
|
- Fixing or executing `superpowers_review_20260619` (just unblocking it).
|
|
|
|
|
- Changing how `metadata.json.status` is maintained going forward.
|
|
|
|
|
- Archiving the 66 folders in `conductor/tracks/` that are already shipped.
|
|
|
|
|
- Renaming or restructuring `conductor/archive/`.
|
|
|
|
|
- A broader `workflow.md` review for other stale rules.
|
|
|
|
|
- The `superpowers_review_20260619` track's execution.
|
