conductor(track): init chronology_v2_20260701 (spec + metadata + state + plan)
This commit is contained in:
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"track_id": "chronology_v2_20260701",
|
||||
"name": "Chronology v2 Redo (git-history classifier + tracks.md de-gunk + maintenance rule)",
|
||||
"priority": "A",
|
||||
"category": "meta-tooling",
|
||||
"status": "spec_written",
|
||||
"blocked_by": [],
|
||||
"verification_criteria": [
|
||||
"conductor/chronology.md exists with one row per track folder (tracks/ + archive/), sorted newest-first, 6 columns, generated from the current filesystem",
|
||||
"every row's status is backed by git-history evidence (not metadata.json.status); the evidence reason is non-empty for every row",
|
||||
"no summary contains metadata-field text (**Priority:**, **Date:**, **Initialized:**, **Track:**, **Parent umbrella:**, **Status:**, **Confidence:**)",
|
||||
"scripts/audit/chronology_quality_gate.py --strict exits 0",
|
||||
"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",
|
||||
"conductor/workflow.md contains the 'Chronology Maintenance' section",
|
||||
"docs/reports/CHRONOLOGY_QUALITY_20260701.md exists with status distribution + Needs Review queue + v1 comparison + desync gap list",
|
||||
"docs/reports/TRACK_COMPLETION_chronology_v2_20260701.md exists",
|
||||
"chronology_20260619 is archived with status = superseded in its state.toml",
|
||||
"superpowers_review_20260619/state.toml [blocked_by] no longer contains chronology_20260619",
|
||||
"tests/test_generate_chronology.py + tests/test_chronology_quality_gate.py pass",
|
||||
"user sign-off recorded in the TRACK_COMPLETION report"
|
||||
]
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Track state for chronology_v2_20260701
|
||||
|
||||
[meta]
|
||||
track_id = "chronology_v2_20260701"
|
||||
name = "Chronology v2 Redo"
|
||||
status = "active"
|
||||
current_phase = 0
|
||||
last_updated = "2026-07-01"
|
||||
|
||||
[blocked_by]
|
||||
# Independent track. No blockers.
|
||||
|
||||
[blocks]
|
||||
# superpowers_review_20260619 was blocked by the old chronology_20260619;
|
||||
# that blocker was removed in Task 1.4. This track does not block anything.
|
||||
|
||||
[phases]
|
||||
phase_1 = { status = "pending", checkpointsha = "", name = "Close out old track + scaffold new one" }
|
||||
phase_2 = { status = "pending", checkpointsha = "", name = "TDD the classifier + quality gate (Red)" }
|
||||
phase_3 = { status = "pending", checkpointsha = "", name = "Implement the classifier + quality gate (Green)" }
|
||||
phase_4 = { status = "pending", checkpointsha = "", name = "Regenerate chronology.md + write quality report" }
|
||||
phase_5 = { status = "pending", checkpointsha = "", name = "De-gunk tracks.md + add workflow.md maintenance rule" }
|
||||
phase_6 = { status = "pending", checkpointsha = "", name = "Verification + end-of-track report" }
|
||||
|
||||
[tasks]
|
||||
t1_1 = { status = "pending", commit_sha = "", description = "Mark chronology_20260619 as superseded in state.toml" }
|
||||
t1_2 = { status = "pending", commit_sha = "", description = "Update chronology_20260619 row in tracks.md" }
|
||||
t1_3 = { status = "pending", commit_sha = "", description = "Archive chronology_20260619 folder" }
|
||||
t1_4 = { status = "pending", commit_sha = "", description = "Unblock superpowers_review_20260619" }
|
||||
t1_5 = { status = "pending", commit_sha = "", description = "Scaffold chronology_v2_20260701 track folder" }
|
||||
Reference in New Issue
Block a user