ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(spec): rewrite chronology_20260619 spec for v2 (git-history classifier + 30% quality gate)

Browse Source 
The first run shipped chronology.md with a status classifier that read stale
metadata.json.status, marking 167/216 rows with wrong status. This v2 spec
replaces FR1 (5-value status enum + per-row evidence + confidence), FR5
(git-history classifier with the 5-step algorithm from the handover), FR6
(3-stage cross-check), and adds FR7 (classifier quality gate at 30% low
confidence threshold with abort-to-manual-review fallback).

Substantive changes from v1:
- 7 FRs (was 6); FR7 is new
- 14 VCs (was 12); VC10-VC14 are new
- 10 Risks (was 9)
- 5-value status enum: Active / In Progress / Completed / Abandoned / Special
  (was 6-value: Shipped/Superseded/etc.)
- Per-row evidence line format documented with worked example
- 'Needs Review' section as a 5th section in chronology.md
- Quality gate hard-codes the user's 'A only if classifier is good, else B'
  fallback design from chat 2026-06-21

Out of scope: 24 v1 commits + conductor/chronology.md.broken-v1 remain as the
foundation; this is a continuation, not a re-do. state.toml still shows
current_phase=10 from v1's false completion; the Tier 2 implementing agent
will reset it in Phase 1.4 of the plan.
This commit is contained in:
ed
2026-06-21 14:08:40 -04:00
parent 23b7b9357d
commit 5c9249659f
1 changed files with 272 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/chronology_20260619/spec.md
+272 -168
View File
@@ -1,250 +1,354 @@
# Track Specification: Conductor Chronology (2026-06-19)
# Track Specification: Conductor Chronology v2 (2026-06-21 rewrite)
## Overview
This track creates `conductor/chronology.md`, a complete, manually-maintained index of all tracks (active, shipped, archived, superseded) for the Manual Slop conductor system, plus a small section for notable non-track commits. It removes the duplicated `[x]` completed-track listings from `conductor/tracks.md` (the "Phase 9: Chore Tracks" section, the `[x]` entries under "Active Research Tracks", and the `[shipped]` entries under "Follow-up") and consolidates them into a single canonical index.
This is the **v2 rewrite** of `chronology_20260619`. The first run (Phases 1-9, 24 commits, 2026-06-19 to 2026-06-20) shipped `conductor/chronology.md` with a **broken status classifier** that read stale `metadata.json.status` fields. The user mandate — "EVERY SINGLE ENTRY MUST BE CROSS CHECKED" — was satisfied at a structural level (folder set == row set) but the **semantic level** (status correctness, summary quality) was not. Two classifier iterations followed (commits `4109a667` and `271e6895`); both used heuristic-based fallbacks and neither used **git history as the explicit evidence source** the user wants.
The per-track `spec.md`/`plan.md`/`metadata.json`/`state.toml` in `conductor/tracks/` and `conductor/archive/` remain the source of truth for each track's details. `chronology.md` is the *index* — one row per track, with a brief one-sentence summary, a folder link, a commit range, and a status badge. It reads as a build history, not a release history.
This rewrite replaces the spec/plan/state.toml; the 24 prior commits + the broken v1 chronology remain in git history as the foundation. The substantive changes are:
1. **FR1** (chronology structure): rewritten — new status enum (5 values), per-row evidence line, per-row confidence level, "Needs Review" section.
2. **FR5** (helper script): rewritten — git-history classifier with confidence assignment.
3. **FR6** (cross-check): rewritten — 3-stage protocol (classifier auto + Tier 1 reviews "Needs Review" queue + user reviews final).
4. **FR7** (new): classifier quality gate — if > 30% of rows are ambiguous, abort to manual review (the user's "B" fallback).
The active task list stays in `conductor/tracks.md` (in-flight `[~]` and planned `[ ]` entries). When a track ships and is moved to `archive/`, its entry is added to `chronology.md` and its `[x]` row is removed from `tracks.md` (this is the workflow change).
Phases that produced the existing `tracks.md` pruning + `workflow.md` 3-step convention + the v1 migration report are reused. This rewrite adds a v2 addendum to the migration report.
## Current State Audit (as of 2026-06-19)
## Current State Audit (as of 2026-06-21, commit `3aea92f1`)
### Already Implemented (DO NOT re-implement)
### Already Implemented (carried forward, NO REWORK)
1. **`conductor/tracks.md` (line 459)** — already calls itself a "Lightweight chronology; full spec/plan/state per track is in the linked folder." This track makes that role explicit and gives it a dedicated file.
2. **`conductor/tracks.md` "Phase 9: Chore Tracks" section** — manually-maintained list of `[x]` completed tracks. This is one of three duplicated listings that move to `chronology.md`.
3. **`conductor/tracks.md` "Active Research Tracks" section** — the `[x]` entries (e.g., Fable review shipped 2026-06-18) move to `chronology.md`. The `[ ]` in-flight entries stay in `tracks.md`.
4. **`conductor/tracks.md` "Follow-up (Planned, Not Yet Specced)" section** — the `[shipped: YYYY-MM-DD]` entries move to `chronology.md`. The "planned" and "not yet specced" entries stay in `tracks.md`.
5. **`conductor/archive/` (176 track folders)** — the canonical location of shipped tracks. Each folder has at minimum a `spec.md`; most also have `plan.md`; modern tracks (2026-06+) have `metadata.json` + `state.toml` as well.
6. **`conductor/tracks/` (35 active track folders)** — the canonical location of in-flight tracks.
7. **`conductor/workflow.md` "Notes > Editing this file" section** — documents the existing convention for moving tracks to `archive/` when shipped. The new convention is appended here.
1. **`conductor/tracks.md` "Phase 9: Chore Tracks" section** — pruned to one-line stub pointing to `chronology.md` (commit `be38dd5`).
2. **`conductor/tracks.md` "Active Research Tracks" `[x]` entries** — pruned (commit `cca4767`).
3. **`conductor/tracks.md` "Follow-up" `[shipped]` entries** — pruned (commit `b3a9c45`).
4. **`conductor/workflow.md` "Notes > Editing this file" section** — has the 3-step archiving convention (commit `b697cd8`).
5. **`scripts/audit/generate_chronology.py`** — exists (338 lines). Functions: `extract_slug_date`, `extract_summary`, `walk_track_folders`, `format_markdown`, `_classify_status`, `_parse_state_phase`, `_last_commit_date`. The **broken function** is `_classify_status` (lines ~163-189) which reads the `current` parameter (originally from `metadata.json.status`) and uses folder-location + state_phase heuristics. **This function is the target of FR5's rewrite.**
6. **`tests/test_generate_chronology.py`** — 6 unit tests, all passing against the current (broken) classifier. Need extension per FR5.
7. **`conductor/chronology.md`** — 218 lines, 216 rows, v1 with broken status classifier. Statuses include `active`, `spec_written`, `spec_approved`, `planning` (stale metadata.json.status values). 41 `Completed`, 0 `Abandoned`, 167 rows with stale status per the handover report (line 14-16). **Target of Phase 1's move-to-broken-v1.**
8. **`docs/reports/CHRONOLOGY_MIGRATION_20260619.md`** — v1 migration report; needs v2 addendum (FR4).
9. **`docs/reports/CHRONOLOGY_TRACK_HANDOVER_20260620.md`** — tier-2's hand-off; documents the failure + the recommended fix (the 5-step git-history algorithm).
10. **`docs/reports/TRACK_COMPLETION_chronology_20260619.md`** — v1 end-of-track report; needs v2 addendum.
### Gaps to Fill (This Track's Scope)
| # | Gap | Where | Resolution |
|---|-----|-------|-----------|
| G1 | No `conductor/chronology.md` exists | `conductor/` (new file) | Create + populate |
| G2 | `tracks.md` carries duplicated completed-track listings across 3 sections | `conductor/tracks.md` Phase 9, Active Research, Follow-up | Remove all `[x]`/`[shipped]` entries |
| G3 | No documented convention for what happens to a `tracks.md` entry when a track is archived | `conductor/workflow.md` | Add a 3-step section: update `tracks.md`, add to `chronology.md`, move folder to `archive/` |
| G4 | No audit trail of the migration | `docs/reports/` | New `CHRONOLOGY_MIGRATION_20260619.md` for user review |
| G5 | Brief per-track summaries don't exist anywhere as a single-line format | `spec.md` (1st paragraph) + `metadata.json.description` (modern tracks) | Extract for the migration; manually edited for length |
| G1 | v1 chronology.md has 167/216 rows with wrong status (stale `metadata.json.status` values) | `conductor/chronology.md` | Move v1 to `conductor/chronology.md.broken-v1` (Phase 1); generate v2 with git-history classifier (Phase 4) |
| G2 | v1 chronology.md has summaries that are metadata-field text (`**Priority:** A...`, `**Date:** 2026-06-20`) not the actual track summary | Same as G1 | v2's priority chain (FR5 §"Summary extraction") rejects metadata-field text via regex |
| G3 | `_classify_status` reads stale `metadata.json.status` | `scripts/audit/generate_chronology.py:~163-189` | Rewrite to use the 5-step git-history algorithm (handover §"Root cause of failure") |
| G4 | No "Needs Review" queue mechanism | n/a (new) | Add per-row confidence (FR5) + "Needs Review" section in `chronology.md` (FR1) |
| G5 | No quality gate to detect a bad classifier | n/a (new) | Add `scripts/audit/chronology_quality_gate.py` (FR7) |
| G6 | v1 cross-check was bulk-verified (structural check, not per-row semantic check) | n/a (process change) | v2 cross-check is 3-stage (FR6): classifier auto + Tier 1 reviews "Needs Review" + user reviews final with per-row evidence log |
| G7 | v1 per-row evidence is missing | n/a (new) | Add per-row evidence line to `chronology.md` (FR1) + standalone evidence log file (FR6 §"per-row evidence log") |
| G8 | `state.toml` is at `current_phase = 10` with a false "complete" state | `conductor/tracks/chronology_20260619/state.toml` | Reset to `current_phase = 0`; this rewrite starts fresh |
| G9 | v1 migration report has 167 stale-status rows in the per-row log | `docs/reports/CHRONOLOGY_MIGRATION_20260619.md` | v2 addendum shows the diff (v1 status → v2 status) with the git evidence per row |
| G10 | No fallback path if the classifier is bad | n/a (new) | FR7 quality gate; if > 30% ambiguous → abort to manual review (the user's "B" fallback per chat 2026-06-21) |
## Goals
1. **One canonical index.** `conductor/chronology.md` is the only file the user (or an agent) consults to see "what has this project done." No more scanning 3 sections of `tracks.md`.
2. **No info loss.** Every completed track that was in `tracks.md` is now in `chronology.md` with the same information (name, link, status, checkpoint SHAs).
3. **Forward-compatible.** When a new track ships, the convention is clear: add a row to `chronology.md`, update the row in `tracks.md` (or remove it), and move the folder to `archive/`.
4. **Notable non-track commits captured.** Commits that aren't part of any track (direct fixes, infra tweaks, doc-only commits) have a place in `chronology.md` if a future reader would want to know about them.
5. **No day estimates.** Per the project convention (added 2026-06-16), all scope is measured in files/sites, not time.
1. **One canonical index.** `conductor/chronology.md` is the only file consulted to see "what has this project done." No more scanning 3 sections of `tracks.md`. (Carried from v1; unchanged.)
2. **No info loss.** Every track that has a folder in `conductor/tracks/` or `conductor/archive/` has a row in `chronology.md` (or a documented exception). (Carried from v1; unchanged.)
3. **Forward-compatible.** When a new track ships, the convention is clear: move folder to `archive/`, remove `[x]` from `tracks.md`, add a row to `chronology.md` with the new format. (Carried from v1; unchanged.)
4. **Git history is the explicit evidence.** Each row's status is derived from `git log -- <folder>` (commit count + commit messages). `metadata.json.status` is **informational only** — the classifier does not trust it for the final status.
5. **"EVERY SINGLE ENTRY" mandate preserved at the semantic level.** Every row has: (a) a status decision, (b) the git evidence that supports the decision, (c) a per-row confidence level, (d) a "Needs Review" flag if confidence is low. The "cross-check" is the row's evidence trail, not a separate audit pass.
6. **Conservative classifier + hard quality gate.** The classifier auto-classifies only when evidence is clear; ambiguous rows are flagged for human review. If > 30% of rows are ambiguous, the classifier is bad → abort to manual review (the user's "B" fallback per chat 2026-06-21).
7. **No day estimates.** Per `conductor/workflow.md` Tier 1 Track Initialization Rules (added 2026-06-16). Scope measured in files/sites.
## Functional Requirements
### FR1. `conductor/chronology.md` file structure
### FR1. `conductor/chronology.md` v2 structure (REWRITTEN)
**WHERE:** New file `conductor/chronology.md` at the conductor root.
**WHERE:** `conductor/chronology.md` (replaces v1).
**WHAT:** A markdown file with the following structure (top to bottom):
**WHAT:** Same overall structure as v1 (table format, newest first, "Notable Non-Track Commits" section at the bottom), with these changes:
```markdown
# Conductor Chronology
**Status enum (5 values, replaces v1's 6-value enum):**
- `Active` — folder in `tracks/` + work has started (≥ 1 `feat/fix/refactor` commit) but `state.toml.current_phase` < 3
- `In Progress` — folder in `tracks/` + `state.toml.current_phase` ≥ 3 (or no `state.toml` + ≥ 3 work commits)
- `Completed` — folder in `archive/` + ≥ 3 work commits (or `state.toml.current_phase == "complete"`)
- `Abandoned` — folder in `tracks/` or `archive/` + 0-1 work commits + last commit > 14 days ago + no `feat/fix/refactor` in commit history
- `Special` — explicit human-decision; e.g., research note, scratch dir, archived by mistake, deleted
Complete history of all tracks for the Manual Slop conductor system, plus notable non-track commits. This is the canonical index — the per-track spec/plan/metadata in `tracks/` and `archive/` remain the source of truth for each track's details.
**Notably ABSENT from the v2 enum** (present in v1): `Shipped`, `Superseded`, `planning`, `spec_written`, `spec_approved`, `active` (lowercase). The v2 enum is the canonical set; v1's status values are stale metadata leaks.
The active task list lives in [`tracks.md`](./tracks.md). When a track ships and is moved to `archive/`, its entry here is added (and its `[x]` entry removed from `tracks.md`).
**Per-row confidence level (NEW):**
- `high` — auto-classified by the script; git evidence + folder location + state.toml (if present) all point to the same status
- `low` — in the "Needs Review" queue; needs Tier 1 + user review
## Tracks (newest first)
- **YYYY-MM-DD** — `track_id_<YYYYMMDD>` *(Status)* — One-sentence summary.
- Folder: [tracks/track_id_<YYYYMMDD>/](./tracks/track_id_<YYYYMMDD>/) (active) OR [archive/track_id_<YYYYMMDD>/](./archive/track_id_<YYYYMMDD>/) (shipped)
- Range: `<init-sha>..<end-sha>` (N commits)
*(one row per track, ~165 total)*
## Notable Non-Track Commits
- **YYYY-MM-DD** — `<sha>` — One-line description of why this commit is notable.
- ...
**Per-row evidence line (NEW):**
Each row gets a sub-line in the format:
```
Evidence: <7-char-init-sha>..<7-char-end-sha> | N commits | state_phase=<N or "n/a" or "complete"> | "<first-commit-subject>" → "<last-commit-subject>" | confidence=<high|low>
```
**Per-row fields:**
- **Date** — the date in the track's slug (`YYYYMMDD` → `YYYY-MM-DD`). If the slug date disagrees with the first-commit date (older tracks), use the slug date.
- **Track ID** — the standard `topic_<YYYYMMDD>` slug, in backticks.
- **Status** — one of: `Active`, `In Progress`, `Shipped`, `Superseded`, `Abandoned`.
- **Summary** — one sentence, ≤ 25 words, manually written. The first sentence of `spec.md` is the source; manually trimmed for length.
- **Folder** — link to `tracks/<id>/` (active) or `archive/<id>/` (shipped).
- **Range** — `<7-char init SHA>..<7-char end SHA>` + commit count. Use the FIRST commit that touched the track folder as `init-sha` and the LAST commit (or the archive-move commit) as `end-sha`. Get these from `git log --reverse --format='%h' -- <folder>` and `git log --format='%h' -1 -- <folder>`.
**"Needs Review" section (NEW):**
At the bottom of `chronology.md`, a section listing all `low`-confidence rows with a one-line reason each. Format:
```
## Needs Review (Tier 1 + User)
**Notable Non-Track Commits section:**
- Sorted newest first.
- One row per notable commit: date, SHA, one-line description.
- The criterion for "notable" is: a future agent reading the chronology would want to know this commit happened. The bar is "non-obvious work that wasn't part of a track" — e.g., direct production fixes, infra changes, refactors that pre-date the conductor convention.
These rows had ambiguous git evidence. Resolved by Tier 1; user reviewed in Stage 3.
### FR2. `conductor/tracks.md` pruning
**WHERE:** `conductor/tracks.md` (modify).
**WHAT:** Remove all `[x]` completed-track entries from the 3 sections:
1. "Phase 9: Chore Tracks" — remove the entire section (or leave a one-line stub pointing to `chronology.md`).
2. "Active Research Tracks" — remove only the `[x]` entries; keep the `[ ]` in-flight ones.
3. "Follow-up (Planned, Not Yet Specced)" — remove only the `[shipped: YYYY-MM-DD]` entries; keep the "planned" and "not yet specced" entries.
**KEEP:**
- The Active Tracks table at the top of the file (all rows, including in-flight `[~]` and planned `[ ]`).
- The "Backlog" section.
- The "Notes" section.
- The "Status legend" (`[ ]` / `[~]` / `[x]`).
**Stub convention:** If a section is fully removed, leave a one-line stub:
```markdown
#### Phase 9: Chore Tracks
*Completed chore tracks are in [`chronology.md`](./chronology.md).*
- `<track_id>` (status=<resolved>) — <one-line reason> — resolved by Tier 1
```
### FR3. `conductor/workflow.md` update
**Other v1 fields preserved unchanged:** Date, Track ID, Summary (≤ 25 words), Folder, Range (`<init-sha>..<end-sha>` with commit count), Notable Non-Track Commits section.
**WHERE:** `conductor/workflow.md` "Notes > Editing this file" section (append).
**WHAT:** Add a 3-step convention for archiving a track:
```markdown
**Archiving a track (3 steps):**
1. Move the folder from `conductor/tracks/<id>/` to `conductor/archive/<id>/`.
2. Remove the `[x]` entry from `conductor/tracks.md` (and update status badges on related entries).
3. Add a row to `conductor/chronology.md` with the init SHA, the end SHA (the archive-move commit), and a one-sentence summary.
**Worked example (new format):**
```
| 2026-06-19 | `chronology_20260619` | In Progress | **Confidence:** low | v2 rewrite of the chronology track after tier-2's failure report identified the broken status classifier. | `conductor/tracks/chronology_20260619` | `87923c93..3aea92f1` (12) |
| | | | | | Evidence: `87923c9..3aea92f` | 12 commits | state_phase=n/a (this rewrite) | "conductor(track): add initial spec for chronology_20260619" → "botched the chronology, going to rewrite the track." | confidence=low |
```
### FR4. Migration report
### FR2. `conductor/tracks.md` pruning (CARRIED FORWARD; no changes)
**WHERE:** New file `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`.
**Already complete in v1 (commits `be38dd5`, `cca4767`, `b3a9c45`).** This rewrite verifies the pruning is intact and re-commits nothing.
**WHAT:** A one-page summary for the user to review the migration:
- Total entries created in `chronology.md` (count by status: Active / Shipped / Superseded / Abandoned).
- Total entries removed from `tracks.md` (count by section: Phase 9 / Active Research / Follow-up).
- Total notable non-track commits added.
- Any tracks that couldn't be migrated (missing `spec.md`, ambiguous status, etc.) and why.
- A small diff preview (10-20 sample rows) so the user can spot-check the format.
**Verification step:** Phase 1 of the v2 plan runs `grep -n "^- \[x\]" conductor/tracks.md` and confirms 0 matches (other than the Status legend at the bottom of the file).
### FR5. Helper script (DRAFT-ONLY; never source of truth)
### FR3. `conductor/workflow.md` 3-step convention (CARRIED FORWARD; no changes)
**WHERE:** New file `scripts/audit/generate_chronology.py` (used for the initial population only).
**Already complete in v1 (commit `b697cd8`).** This rewrite verifies the 3-step block is present and re-commits nothing.
**WHAT:** A one-shot script that walks `conductor/tracks/` and `conductor/archive/`, extracts per-track data (init SHA, end SHA, date, summary from `spec.md`/`metadata.json`), and produces a **DRAFT** `conductor/chronology.md.draft`. The draft is a starting point for FR6; it is NOT authoritative.
**Verification step:** Phase 1 of the v2 plan runs `grep -n "Archiving a track" conductor/workflow.md` and confirms 1 match.
**The script is the EXTRACTION tool; the human is the AUTHORITY.** Every value the script emits is a guess: a date pulled from the slug, a summary trimmed from `spec.md`, a commit SHA from `git log`. All of these can be wrong (slugs predate the slug convention; summaries are too long or off-topic; commit SHAs depend on the folder containing the right files). The script cannot know which tracks are superseded, abandoned, or special-cased. The cross-check (FR6) is the gate that catches this.
### FR4. Migration report v2 addendum (UPDATED)
**Workflow:**
1. Run `uv run python scripts/audit/generate_chronology.py --draft > conductor/chronology.md.draft`.
2. Tier 1 (or the user) cross-checks every row per FR6.
3. After cross-check, the draft is renamed to `conductor/chronology.md`.
4. The script stays in `scripts/audit/` for re-generation if needed (a new track added retroactively, etc.) but is not part of the ongoing workflow.
**WHERE:** `docs/reports/CHRONOLOGY_MIGRATION_20260619.md` (extends existing report).
**This script is REQUIRED for the initial migration** (165+ rows of hand-typing is impractical) but does NOT replace the cross-check.
**WHAT:** A new section appended to the end of the v1 report: "v2 Rewrite Addendum (2026-06-21)". Contains:
- **Why the rewrite was needed** — link to `CHRONOLOGY_TRACK_HANDOVER_20260620.md` + summary of the root cause
- **v1 → v2 status diff** — table of all 216 rows showing the v1 status (stale) and v2 status (after the new classifier) + the git evidence per row
- **Classifier confidence distribution** — counts: `high` / `low` / total; % of total in `Needs Review`
- **Tier 1 review log** — for each `low`-confidence row, the resolution note (assigned status + reason + override if any)
- **Quality gate result** — was the 30% threshold hit? If so, the abort-to-B was triggered.
- **Outstanding issues** — any rows the user flagged for follow-up
### FR6. Mandatory per-row cross-check (USER DIRECTIVE 2026-06-19)
### FR5. Helper script rewrite — git-history classifier (REWRITTEN)
**WHERE:** `conductor/chronology.md.draft` (after the script runs per FR5), then `conductor/chronology.md` (after cross-check).
**WHERE:** `scripts/audit/generate_chronology.py` (rewritten) + `tests/test_generate_chronology.py` (extended).
**WHAT:** Every row in the draft is verified by a human (Tier 1 or the user) before the draft is renamed to the canonical `chronology.md`. No row is trusted on the script's word alone. The cross-check is a hard gate: the file is not committed until every row passes.
**WHAT:** The script's `_classify_status` function is rewritten to use the handover's 5-step algorithm. The new signature is:
**The 5 fields verified per row:**
1. **Date** — does it match the slug (`YYYYMMDD` → `YYYY-MM-DD`)? If the slug is missing or non-standard, does the first-commit date match? Fix any disagreement.
2. **Track ID** — does the backticked slug match the folder name? Any typo is a broken link.
3. **Status** — is the badge correct? Folder in `tracks/` = `Active` or `In Progress`; folder in `archive/` = `Shipped`; check `tracks.md` for `[~]` (in progress) vs `[ ]` (planned, not yet active). Superseded/Abandoned are rare and require a manual decision.
4. **Summary** — does the one-sentence summary actually describe what the track did? Is it under 25 words? Is it the most important fact, not the first random sentence of `spec.md`? Trim or rewrite as needed.
5. **Range** — does the init SHA exist? Does the end SHA exist? Does the range cover the right commits? Run `git log --oneline <init>..<end> -- <folder>` and verify the count is plausible (not 0, not absurd).
```python
def _classify_status(
folder_link: str,
init_sha: str,
end_sha: str,
commit_count: int,
first_commit_subject: str,
last_commit_subject: str,
state_phase: str | None,
metadata_status: str | None,
last_commit_date: str,
) -> tuple[str, str, str]:
"""Classify a track's status using git history as primary evidence.
**The completeness check (parallel gate):**
After per-row verification, Tier 1 enumerates every folder in `conductor/tracks/` and `conductor/archive/` and confirms each has a corresponding row in `chronology.md`. Any folder without a row is a bug — either the row was missed, or the folder is special-cased (e.g., a research note, not a track) and the migration report (FR4) documents the exception.
Returns:
(status, confidence, reason) where:
- status: one of "Active", "In Progress", "Completed", "Abandoned", "Special"
- confidence: "high" or "low"
- reason: one-line explanation of the classification
"""
```
**The "nothing was missed" mandate (user directive, verbatim):**
> EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.
**The 5-step algorithm (per the handover §"Rewrite `_classify_status` to use git history as primary evidence"):**
This is non-negotiable. If the cross-check finds even one error, the draft is fixed and re-verified. If a folder has no row, the row is added and verified. The migration is not "done" until both the per-row check and the completeness check are clean.
1. **Count meaningful commits.** `commit_count` (already computed by the script via `git log --oneline -- <folder> | wc -l`). 1-2 commits (just spec/plan creation) is a strong signal for `Active` (in `tracks/`) or `Abandoned` (in `archive/`). ≥ 3 work commits is a strong signal for `Completed` (in `archive/`) or `In Progress` (in `tracks/`).
**Who does the cross-check:**
- **Tier 1** does the bulk of the per-row verification (mechanical checks: slug match, SHA existence, folder existence).
- **The user** reviews a 10–20 row sample (per FR4's diff preview) and the final `chronology.md` before it is committed. The user is the quality gate.
- **Tier 3** is not used for the cross-check — the per-row work is too small to delegate, and the user wants the verification done by an agent with full context, not a stateless worker.
2. **Inspect commit messages.** `first_commit_subject` and `last_commit_subject` (already extracted by the script). Classify each commit as `work` (matches `^(feat|fix|refactor|perf|test)\(`) or `meta` (matches `^(chore|docs|conductor)\(`) or `other` (everything else).
3. **Check `state.toml` phase progression.** `state_phase` is parsed from `state.toml.current_phase` if the file exists; else `None`. The thresholds:
- `state_phase == "complete"` → `Completed` (high confidence if corroborated by git)
- `state_phase >= 3` → `In Progress` (high confidence if corroborated by git)
- `state_phase in (0, 1, 2)` → `Active` (high confidence if corroborated by git)
- `state_phase is None` → no signal from state.toml; classifier relies on git + folder
4. **Default to conservative.** When git history is ambiguous (1-3 commits with no clear `work` pattern), flag as `low` confidence → "Needs Review". The classifier NEVER auto-marks `Abandoned` — that's a `Special` decision reserved for Tier 1 + user.
5. **Honour explicit metadata.** If `metadata_status` is `abandoned` or `superseded` (or `Special`), and git evidence is not contradictory, trust the metadata. If git evidence contradicts metadata (e.g., `archive/` + 0 commits + `metadata_status = "Completed"`), the classifier flags `low` confidence and the user resolves in Stage 3.
**Per-row confidence assignment:**
- `high` — git evidence + folder location + state.toml (if present) all point to the same status. Default for unambiguous cases.
- `low` — any of: (a) < 3 commits total, (b) conflicting signals (e.g., `archive/` + 0 commits + state_phase 0), (c) no `state.toml` + ambiguous git history, (d) `metadata_status` contradicts git.
**Summary extraction (REWRITTEN priority chain):**
The v1 priority chain is replaced with a regex-aware version:
1. `metadata.json.summary` if present and does not start with `**` (regex: `^\*\*`)
2. First non-empty line of `spec.md` that does not start with `**`
3. `metadata.json.description` if not starting with `**`
4. First non-empty line of `plan.md` that does not start with `**`
5. Generic placeholder: `"Imported from archive (no spec)"` for archive rows, `"Track folder (no spec found)"` for tracks/ rows
The regex `^\*\*` rejects metadata-field text like `**Priority:** A...`, `**Date:** 2026-06-20`, `**Created:** 2026-06-19`, `**Initialized:** 2026-06-19`, `**Parent umbrella:** ...`, `**Confidence:** ...`.
**New script: `scripts/audit/chronology_quality_gate.py` (FR7's wrapper).**
- Reads the staging `chronology.md.staging` file.
- Counts `high` and `low` confidence rows.
- Computes `low_count / total_count`.
- If ratio > 0.30 → exit code 1, prints "ABORT: classifier is bad; >30% of rows are ambiguous. Fall back to manual review (v1 protocol)."
- If ratio ≤ 0.30 → exit code 0, prints "PASS: classifier is good. Proceed to Tier 1 review of 'Needs Review' queue."
**Tests extended:** the existing 6 tests stay; add 8-10 new tests covering:
- `_classify_status` returns correct status for each (folder, commit_count, state_phase) combination
- `low` confidence is assigned for ambiguous cases (1-2 commits, conflicting signals)
- `high` confidence is assigned for unambiguous cases
- Summary priority chain rejects metadata-field text (regression test for the v1 bug)
- The staging file has per-row evidence + confidence lines
- The "Needs Review" section is correctly populated
- The quality gate script exits 1 when > 30% ambiguous, 0 when ≤ 30%
- The quality gate script prints the correct summary
### FR6. Per-row cross-check (REWRITTEN — 3-stage protocol)
**WHERE:** `conductor/chronology.md` v2 (after classifier run), then "Needs Review" queue (Tier 1 review), then final v2 (user review).
**WHAT:** The cross-check is **3-stage** (replaces v1's single-stage Tier 1 review of every row):
**Stage 1: Classifier auto-classification (script run).**
- The script runs `walk_track_folders()` over `conductor/tracks/` and `conductor/archive/`.
- For each folder, the script extracts: date, track_id, init_sha, end_sha, commit_count, first_commit_subject, last_commit_subject, state_phase, metadata_status, last_commit_date, summary.
- The script's rewritten `_classify_status()` assigns (status, confidence, reason) for each row.
- Output: `conductor/chronology.md.staging` with the per-row evidence line + confidence level + "Needs Review" section.
- The script is **READ-ONLY** on the source folders; it writes to `chronology.md.staging` only.
- **Quality gate (FR7)** runs immediately after: if the gate passes, proceed to Stage 2; if the gate fails, the staging file is preserved and the task aborts to manual review (per FR7).
**Stage 2: Tier 1 review of the "Needs Review" queue (only if quality gate passes).**
- Tier 1 opens `conductor/chronology.md.staging`.
- Tier 1 filters to the "Needs Review" section (rows with `confidence=low`).
- For each `low`-confidence row, Tier 1:
1. Opens the track's `spec.md` (or `plan.md` / `metadata.json` if no spec).
2. Runs `git log --oneline -- <folder>` and reviews the commit history.
3. Verifies the row's evidence line is accurate.
4. Assigns a status from the 5-value enum (or flags for user decision).
5. Writes a one-line resolution note (e.g., "Resolved: Active — work in progress, state_phase=2; classifier flagged low because no spec.md yet").
- **Tier 1's defaults:**
- In `tracks/` + ambiguous → `Active` with a one-line note
- In `archive/` + 0 commits → `Special` with note "archive folder with no work commits"
- In `archive/` + ≥ 3 work commits + state_phase=0 (missing/incomplete) → `Completed` with note "archive + N work commits; state.toml is stale"
- Truly ambiguous → `Special` with note "needs user decision; flagged in Stage 3"
- After Tier 1 resolves all `low`-confidence rows, the staging file is updated: the "Needs Review" section is moved to a "Tier 1 Resolutions" section showing each row's resolution note.
**Stage 3: User review of final v2.**
- User opens `conductor/chronology.md.staging` (now with Stage 2 resolutions).
- User reviews: (a) the format is correct, (b) every row has evidence + decision, (c) Tier 1's resolutions are reasonable, (d) nothing missed.
- User either approves (proceed to Phase 7 promotion) or requests changes (loop back to Stage 2 or 1).
**The per-row evidence log (NEW FILE).**
- Path: `tests/artifacts/chronology_v2_evidence_log.md` (gitignored).
- Format: one row per track with: track_id, status, confidence, init_sha, end_sha, commit_count, first_commit_subject, last_commit_subject, state_phase, classifier_reason, tier1_override (if any).
- Generated by the script during Stage 1; extended by Tier 1 during Stage 2; reviewed by the user in Stage 3.
### FR7. Classifier quality gate (NEW)
**WHERE:** `scripts/audit/chronology_quality_gate.py` (new file) + `tests/test_chronology_quality_gate.py` (new tests).
**WHAT:** A wrapper script that runs after the classifier's Stage 1 output. The script:
1. Reads `conductor/chronology.md.staging` (the script's output).
2. Parses each row's confidence level.
3. Counts `high` and `low` confidence rows.
4. Computes `low_count / total_count`.
5. If ratio > 0.30 → exit code 1, prints "ABORT: classifier is bad; >30% of rows are ambiguous. Fall back to manual review (v1 protocol). Tier 1 should manually review every row in the staging file."
6. If ratio ≤ 0.30 → exit code 0, prints "PASS: classifier is good. <N> rows need Tier 1 review; proceed to Stage 2."
**The 30% threshold is a hard gate.** Tier 1 doesn't start Stage 2 until the gate passes. If the gate fails, the staging file is preserved as `chronology.md.staging.aborted` and the task falls back to the v1 manual protocol (Tier 1 reviews every row).
**Tests for the quality gate:**
- Staging file with 0% low → exit 0
- Staging file with 30% low (boundary) → exit 0
- Staging file with 31% low → exit 1
- Staging file with 100% low → exit 1
- Staging file with malformed rows → exit 2 (parse error)
**No shortcut is acceptable:**
- "Looks right" is not a verification. Every row is opened, every SHA is checked, every summary is read.
- Sample-based verification is not acceptable. EVERY row.
- Trusting the script output is not acceptable. The script is a starting point; the cross-check is the truth.
## Non-Functional Requirements
(Carried from v1, mostly unchanged.)
- **NFR1. Manually maintained.** Per user choice (2026-06-19), the ongoing workflow is hand-edited. No auto-generation in CI; no script runs on every commit. The one-shot migration is a single event; the file is then edited like `tracks.md`.
- **NFR2. Compact.** Each row is ≤ 4 lines (the bullet + 3 sub-lines for Folder/Range, OR a single condensed line for very old tracks where the folder is the only link). The file is scannable, not a wall of text.
- **NFR3. Re-derivable.** A reader can rebuild the chronology from `git log` + the track folders if needed. The init SHA + end SHA in each row is the contract; the summary is the human-friendly gloss.
- **NFR4. No day estimates.** Per the project convention (added 2026-06-16), all scope is measured in files/sites.
- **NFR5. No TDD required.** This is a documentation/tooling track, not a feature track. No production code change; no tests added. (If FR5's helper script is built, it gets 3-5 unit tests for the data extraction logic.)
- **NFR2. Compact.** Each row is ≤ 5 lines (the bullet + 3 sub-lines for Folder/Range/Evidence, OR a single condensed line for very old tracks where the folder is the only link). The file is scannable, not a wall of text.
- **NFR3. Re-derivable.** A reader can rebuild the chronology from `git log` + the track folders if needed. The init SHA + end SHA + evidence line in each row is the contract; the summary is the human-friendly gloss.
- **NFR4. No day estimates.** Per `conductor/workflow.md` Tier 1 Track Initialization Rules (added 2026-06-16). All scope is measured in files/sites.
- **NFR5. No TDD required for the chronology itself.** This is a documentation/tooling track, not a feature track. The helper script (FR5) gets 8-10 new unit tests for the new classifier (TDD-required per project convention).
- **NFR6. Evidence is auditable (NEW).** The per-row evidence log (`tests/artifacts/chronology_v2_evidence_log.md`) is human-readable; every classification decision is reproducible from the log + git history. A reader can verify any row's status by running `git log -- <folder>` and comparing to the evidence log.
- **NFR7. Classifier is conservative (NEW).** When in doubt, `low` confidence. The cost of a false `low` (Tier 1 reviews it) is small; the cost of a false `high` (wrong status committed without review) is high. The classifier's bias is toward `low`.
## Architecture Reference
- **`conductor/tracks.md:459`** — the existing "lightweight chronology" reference. This track formalizes that role.
- **`conductor/workflow.md` "Notes > Editing this file"** — the existing convention for moving tracks to `archive/`. The new 3-step convention is appended here.
- **`conductor/code_styleguides/feature_flags.md`** — the "delete to turn off" convention. The helper script (FR5) is opt-in via its presence in `scripts/audit/`; deleting the file turns it off.
- **`docs/reports/`** — convention for one-page reports (per `TRACK_COMPLETION_*.md` precedent set by `tier2_autonomous_sandbox_20260616`). The migration report follows the same shape.
- **`docs/reports/CHRONOLOGY_TRACK_HANDOVER_20260620.md`** — the failure report; the source of the new classifier algorithm (5-step algorithm, §"Rewrite `_classify_status` to use git history as primary evidence", lines 53-68).
- **`docs/reports/CHRONOLOGY_MIGRATION_20260619.md`** — v1 migration report; the v2 addendum (FR4) extends it.
- **`conductor/code_styleguides/data_oriented_design.md`** — applies: the chronology is data (one row per track), the classifier is a transformation (git history → status), the evidence log is a projection (data + decision + provenance).
- **`conductor/code_styleguides/error_handling.md`** — applies to the helper script: the script's `_classify_status` returns `(status, confidence, reason)` (a data-oriented "and/or" pattern, not an exception). The "Needs Review" queue is a recoverable case (low confidence), not an error.
- **`conductor/tracks.md:459`** — the existing "lightweight chronology" reference. v2 formalizes that role.
- **`conductor/workflow.md` "Notes > Editing this file"** — the existing convention for moving tracks to `archive/`. The 3-step convention (FR3) is appended here.
## Out of Scope
1. **Auto-generation on every commit.** Per the user's "manual maintenance" choice, there's no script that updates `chronology.md` automatically. The file is hand-edited when a track is archived.
2. **Tracking "in-flight" tracks in chronology.md.** In-flight tracks (`[~]` in `tracks.md`) stay in `tracks.md` only. The chronology is the record of *completed* work; the active task list is the record of *in-progress* work.
(Carried from v1, mostly unchanged.)
1. **Auto-generation on every commit.** Per the user's "manual maintenance" choice (2026-06-19), there's no script that updates `chronology.md` automatically. The file is hand-edited when a track is archived.
2. **Tracking "in-flight" tracks in `chronology.md`.** In-flight tracks (`[~]` in `tracks.md`) appear in `chronology.md` with status `Active` or `In Progress` (per v2's enum). The active task list still lives in `tracks.md`.
3. **Tracking "planned but not specced" backlog items.** These stay in `tracks.md` under "Follow-up" and "Backlog". They aren't tracks until they have a folder.
4. **Restructuring `tracks.md` beyond `[x]` removal.** The 3 sections that hold `[x]` entries get their `[x]` rows removed, but no new structure is imposed on `tracks.md`. The file's organization is preserved.
5. **A separate `chronology/` folder for the file.** The file lives at the conductor root (`conductor/chronology.md`), not in a subdirectory. Same level as `tracks.md`, `workflow.md`, `product.md`.
4. **Restructuring `tracks.md` beyond `[x]` removal.** The 3 sections that held `[x]` entries are now stubs (v1 Phase 3); no new structure is imposed.
5. **A separate `chronology/` folder for the file.** The file lives at the conductor root (`conductor/chronology.md`), not in a subdirectory.
6. **Reformatting existing `spec.md` / `plan.md` files.** The migration reads from them; it does not modify them.
7. **A web view of the chronology.** It's a markdown file for in-repo reading. No GUI integration is in scope.
8. **A separate `chronology.md.draft` workflow (NEW for v2).** v1 used `.draft` files; v2 doesn't. The classifier emits directly to a staging file (`chronology.md.staging`); the staging file is renamed to `chronology.md` after Stage 2 (Tier 1 review). The `.staging` suffix is gitignored.
## Verification Criteria
For the track to be marked complete, ALL of the following must be true:
- [ ] **VC1.** `conductor/chronology.md` exists, is populated with one row per track (active + shipped + superseded + abandoned), and the format matches FR1.
- [ ] **VC2.** `conductor/tracks.md` no longer contains any `[x]` completed-track entries. The "Phase 9: Chore Tracks" section either is removed or is a one-line stub pointing to `chronology.md`. The "Active Research Tracks" and "Follow-up" sections retain only their `[ ]` and `~` in-flight entries.
- [ ] **VC3.** `conductor/workflow.md` "Notes > Editing this file" section includes the new 3-step archiving convention (FR3).
- [ ] **VC4.** `docs/reports/CHRONOLOGY_MIGRATION_20260619.md` exists with the count summaries + diff preview (FR4).
- [ ] **VC5.** `conductor/chronology.md` is in alphabetical/chronological order (newest first), and every row has a `Folder` link and a `Range` line.
- [ ] **VC6.** Every track folder in `conductor/tracks/` and `conductor/archive/` has a corresponding row in `chronology.md` (or a documented exception in the migration report).
- [ ] **VC7.** The notable non-track commits section (if populated) is sorted newest first and every row has a date, SHA, and description.
- [ ] **VC8.** No new `src/*.py` files were created (per `AGENTS.md` File Size and Naming Convention rule).
- [ ] **VC9.** End-of-track report at `docs/reports/TRACK_COMPLETION_chronology_20260619.md` (per Tier 2 conventions, if executed by Tier 2).
- [ ] **VC10. Per-row cross-check (FR6).** Every row in `chronology.md` was opened, the 5 fields (date, ID, status, summary, range) were verified, and any errors found were fixed before the file was committed. The cross-check is logged in the migration report (per-row checklist or summary).
- [ ] **VC11. Completeness check (FR6).** Every folder in `conductor/tracks/` and `conductor/archive/` has a corresponding row in `chronology.md`, OR a documented exception in the migration report (FR4). The folder set vs. row-set difference is empty (or only contains documented exceptions).
- [ ] **VC12. User sign-off (FR6).** The user reviewed the final `chronology.md` and confirmed: (a) the format is correct, (b) the summaries are accurate, (c) the commit ranges are right, (d) nothing was missed. The user's sign-off is recorded in the migration report.
- [ ] **VC1.** `conductor/chronology.md` v2 exists with 216 rows; all 5 status values are used; per-row evidence line is present; per-row confidence level is present.
- [ ] **VC2.** `conductor/tracks.md` pruning is intact (no regression from v1's pruning; `grep -n "^- \[x\]" conductor/tracks.md` returns 0 matches).
- [ ] **VC3.** `conductor/workflow.md` 3-step convention is present (no regression; `grep -n "Archiving a track" conductor/workflow.md` returns 1 match).
- [ ] **VC4.** `docs/reports/CHRONOLOGY_MIGRATION_20260619.md` has the v2 addendum (per FR4).
- [ ] **VC5.** Sorted newest first; every row has Folder + Range + Evidence lines.
- [ ] **VC6.** Every folder in `conductor/tracks/` and `conductor/archive/` has a corresponding row, OR a documented exception in the v2 addendum.
- [ ] **VC7.** "Notable Non-Track Commits" section is preserved (may be empty if no notable commits found).
- [ ] **VC8.** No new `src/*.py` files created (per `AGENTS.md` File Size and Naming Convention rule).
- [ ] **VC9.** v2 addendum to `docs/reports/TRACK_COMPLETION_chronology_20260619.md` (per project convention).
- [ ] **VC10. Classifier quality gate (FR7).** The `scripts/audit/chronology_quality_gate.py` ran; result was PASS (low confidence ≤ 30%). If the gate failed, the abort-to-B was triggered and Tier 1 manually reviewed every row.
- [ ] **VC11. "Needs Review" queue resolved (FR6 Stage 2).** Every `low`-confidence row in the staging file has a Tier 1 resolution note; the queue is empty in the final `chronology.md` (Tier 1's resolutions are reflected in the per-row status).
- [ ] **VC12. Per-row evidence log (FR6).** `tests/artifacts/chronology_v2_evidence_log.md` has one row per track with status + confidence + evidence + decision (Tier 1 override if any).
- [ ] **VC13. User sign-off (FR6 Stage 3).** User confirmed: format correct, every row has evidence, Tier 1 resolutions are reasonable, nothing missed. Sign-off recorded in the v2 addendum (FR4).
- [ ] **VC14. v1 archive preserved (this rewrite's prerequisite).** `conductor/chronology.md.broken-v1` exists with the v1 218-line file; `git log` shows the rewrite is a continuation (commit `3aea92f1` "botched the chronology, going to rewrite the track."), not a re-do.
## Risk Assessment
| Risk | Likelihood | Scope impact | Mitigation |
|---|---|---|---|
| R1: Migration is incomplete (some tracks missed) | medium | implementation may be larger than the spec suggests if many tracks lack spec.md or have ambiguous status | The migration report (FR4) explicitly lists skipped tracks; VC6 checks for "every folder has a row OR a documented exception." |
| R2: Brief summaries are too long or too vague | medium | implementation may require manual editing of ~165 summaries | The helper script (FR5) extracts the first sentence of `spec.md`; user (or Tier 1) reviews and trims in the draft phase. |
| R3: Commit ranges are wrong (init SHA or end SHA) | low | minimal — git log is authoritative | Helper script uses `git log --reverse --format='%h' -- <folder>` and `git log -1 --format='%h' -- <folder>`; both are deterministic. |
| R4: Date source is ambiguous (slug vs first-commit date) | low | minimal | Rule (per FR1): use the slug date. If the slug date disagrees with the first commit (rare; older tracks), the slug wins because the slug is the project's convention. |
| R5: User changes their mind on the format after seeing the migration | medium | implementation may be larger than the spec suggests | The migration is reviewed (FR4) BEFORE the chronology.md is finalized. The draft phase (FR5) is the review point. |
| R6: `tracks.md` pruning breaks a link the user uses | low | minimal | The pruning is by section + status badge; the user-visible in-flight entries are untouched. The "Status legend" at the bottom of `tracks.md` is preserved. |
| R7: Cross-check (FR6) is shallow or skipped (USER DIRECTIVE 2026-06-19) | high | implementation may be larger than the spec suggests; the whole track is not "done" until every row is verified | FR6 is a hard gate (VC10/VC11/VC12). The migration report logs the cross-check. The user signs off on the final result. No shortcut is acceptable. |
| R8: Folder has no `spec.md` (older tracks) | medium | minimal — the summary is unknown | Use `metadata.json.description` if present; else use the first non-empty line of `plan.md`; else write a generic placeholder like "Imported from archive (no spec)" and flag in the migration report. |
| R9: Track folder exists but is not a real track (e.g., a research note, a scratch dir) | medium | minimal | The completeness check (FR6) catches this: the folder is enumerated, the row is added with status `Special` and a one-line explanation, OR the folder is renamed/removed and the migration report documents it. |
| R1: Classifier is too aggressive (false `high` confidence) | medium | Wrong status committed; user catches in Stage 3 | FR7 quality gate (30% abort); per-row evidence makes the classifier's reasoning auditable; conservative bias (NFR7) |
| R2: Classifier is too conservative (>30% `low`) | medium | FR7 aborts → fallback to v1 manual protocol (Tier 1 reviews every row) | The fallback is the user's "B" option (per chat 2026-06-21); explicitly designed in FR7 |
| R3: Tier 1's resolutions are wrong (Stage 2) | low | User catches in Stage 3 | Per-row resolution notes + evidence log make Tier 1's reasoning auditable; user's Stage 3 review is the final gate |
| R4: `state.toml` parsing fails (some folders lack state.toml) | low | Rows fall to "ambiguous" → `low` confidence → queued for review | Classifier tolerates missing state.toml (FR5 §"3. Check `state.toml` phase progression"); "ambiguous" is the correct behavior per the conservative bias |
| R5: v1 archive move loses data | low | Minimal — `git mv` is safe | Use `git mv` for the rename; verify with `git log --follow` after |
| R6: User disagrees with Tier 1's resolutions | low | Loops back to Stage 2 | The user is the final gate (Stage 3); explicit Stage 3 review |
| R7: Summary extraction still picks metadata-field text (regression of v1 bug) | low | Row has bad summary | v2's priority chain + regex rejection (`^\*\*`); tested by extended test suite (FR5 §"Tests extended") |
| R8: The 30% threshold is wrong (too low or too high) | medium | If too low: abort too easily. If too high: accept a bad classifier. | The 30% value is the user's "A only if classifier is good" trade-off; if the user wants to adjust, FR7's wrapper script accepts `--threshold` as a CLI flag |
| R9: Evidence line format is too verbose (clutters the table) | low | User complains in Stage 3; loops back to FR1 | The evidence line is a sub-line (not a column); the table remains 6 columns. If the user wants it more terse, FR1 can be revised. |
| R10: v1's broken chronology is referenced by other docs | low | Confusion between v1 and v2 | `conductor/chronology.md.broken-v1` is clearly labeled; the v2 file is `chronology.md`; the v1 report is extended with the v2 addendum that explains the rename |
## Execution Plan (high-level — see `plan.md` for worker-ready tasks)
- [ ] **Phase 1: Audit + data extraction.** Walk `conductor/tracks/` and `conductor/archive/`; for each folder, capture (id, date, status, init SHA, end SHA, summary source). Build the migration dataset.
- [ ] **Phase 2: Generate `chronology.md` draft.** Apply the FR1 format to the dataset; write to `conductor/chronology.md.draft` (or directly to `chronology.md` if no draft phase).
- [ ] **Phase 3: Prune `tracks.md`.** Remove the 3 categories of `[x]`/`[shipped]` entries per FR2. Leave stubs for fully-removed sections.
- [ ] **Phase 4: Update `workflow.md`.** Add the 3-step archiving convention per FR3.
- [ ] **Phase 5: Write the migration report.** Per FR4.
- [ ] **Phase 6: User review.** User reviews the draft (or final `chronology.md`); approves or requests changes.
- [ ] **Phase 7: Final commit.** The spec/plan are committed before this phase; the migration is the implementation work.
- [ ] **Phase 8: Per-row cross-check (FR6, hard gate).** Tier 1 opens every row in `chronology.md.draft`, verifies the 5 fields (date, ID, status, summary, range), and fixes any errors. The cross-check is logged in the migration report.
- [ ] **Phase 9: Completeness check (FR6, hard gate).** Tier 1 enumerates every folder in `conductor/tracks/` and `conductor/archive/`; any folder without a row is added (or documented as an exception). The diff between folder set and row set is empty (or only contains documented exceptions).
- [ ] **Phase 10: User sign-off (FR6, hard gate).** The user reviews the final `chronology.md` and the migration report. The user confirms: (a) format is right, (b) summaries are accurate, (c) commit ranges are right, (d) nothing was missed. Sign-off is recorded in the migration report.
- [ ] **Phase 1: Archive v1 + verify state of carried-forward work.** Move `conductor/chronology.md` → `conductor/chronology.md.broken-v1`; reset `state.toml` to `current_phase = 0`; verify `tracks.md` pruning + `workflow.md` 3-step convention are intact.
- [ ] **Phase 2: Rewrite the helper script + extend tests (FR5).** Rewrite `_classify_status` to use the 5-step git-history algorithm; add per-row confidence assignment; rewrite summary priority chain with regex rejection; add 8-10 new unit tests.
- [ ] **Phase 3: Add the quality gate script (FR7).** New file `scripts/audit/chronology_quality_gate.py`; 5 new unit tests for the threshold logic.
- [ ] **Phase 4: Run the new classifier, generate v2 staging (FR6 Stage 1).** Run the script; verify the staging file has per-row evidence + confidence + "Needs Review" section.
- [ ] **Phase 5: Quality gate (FR7).** Run `chronology_quality_gate.py`; if PASS, proceed; if ABORT, fallback to manual review protocol.
- [ ] **Phase 6: Tier 1 reviews "Needs Review" queue (FR6 Stage 2).** Tier 1 resolves each `low`-confidence row; updates the staging file with Tier 1's resolutions; updates the per-row evidence log.
- [ ] **Phase 7: Promote v2 staging → canonical (FR1).** Rename `chronology.md.staging` → `chronology.md`; commit.
- [ ] **Phase 8: Write v2 addendum to migration report + end-of-track report (FR4 + VC9).** Add the v2 rewrite section; document the v1 → v2 status diff + Tier 1 review log; write end-of-track v2 addendum.
- [ ] **Phase 9: User sign-off (FR6 Stage 3).** User reviews v2 + evidence log + Tier 1 resolutions. Records sign-off in the v2 addendum.
- [ ] **Phase 10: Wrap-up.** Mark track complete in `tracks.md` + `state.toml`; set status = "completed" in `metadata.json`.
## See Also
- `conductor/tracks.md:459` — the existing "lightweight chronology" reference that this track formalizes.
- `conductor/workflow.md` "Notes > Editing this file" — the existing archive convention; the new 3-step convention is appended here.
- `docs/reports/CHRONOLOGY_TRACK_HANDOVER_20260620.md` — the failure report; the source of the new classifier algorithm.
- `docs/reports/CHRONOLOGY_MIGRATION_20260619.md` — v1 migration report; the v2 addendum extends it.
- `conductor/tracks.md:459` — the existing "lightweight chronology" reference that v2 formalizes.
- `conductor/workflow.md` "Notes > Editing this file" — the existing archive convention; the 3-step convention (FR3) is appended here.
- `conductor/code_styleguides/feature_flags.md` — "delete to turn off" convention; the helper script (FR5) follows it.
- `conductor/code_styleguides/data_oriented_design.md` — applies: the chronology is data, the classifier is a transformation, the evidence log is a projection.
- `conductor/code_styleguides/error_handling.md` — applies to the helper script: `_classify_status` returns `(status, confidence, reason)` (data-oriented "and/or" pattern).
- `docs/reports/TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md` — precedent for one-page end-of-track reports.
- `AGENTS.md` "File Size and Naming Convention" — the hard rule against creating new `src/<thing>.py` files; this track doesn't touch `src/`.
- `AGENTS.md` "File Size and Naming Convention" — the hard rule against creating new `src/<thing>.py` files; v2 doesn't touch `src/`.
- `AGENTS.md` "Critical Anti-Patterns" — the no-day-estimates rule; the no-`git restore` ban; the report-instead-of-fix pattern (the handover IS a fix, not a report).
- `conductor/workflow.md` "Tier 1 Track Initialization Rules" — the no-day-estimates rule followed in this spec.
- `conductor/workflow.md` "Skip-Marker Policy" — applies: the v1 chronology's broken rows are not "skipped"; they are re-classified in v2.