diff --git a/conductor/tracks/chronology_20260619/metadata.json b/conductor/tracks/chronology_20260619/metadata.json new file mode 100644 index 00000000..79ae4c9e --- /dev/null +++ b/conductor/tracks/chronology_20260619/metadata.json @@ -0,0 +1,151 @@ +{ + "track_id": "chronology_20260619", + "name": "Conductor Chronology", + "created": "2026-06-19", + "status": "spec_written", + "blocked_by": [], + "blocks": [], + "priority": "C", + "rationale": "conductor/tracks.md currently has duplicated completed-track listings across 3 sections (Phase 9 Chore Tracks, Active Research Tracks [x], Follow-up [shipped]). This track creates conductor/chronology.md as the single canonical index of all tracks (active + shipped + superseded + abandoned) plus notable non-track commits, removes the duplicates from tracks.md, and documents the new convention in workflow.md. The per-track spec/plan/metadata in tracks/ and archive/ remain the source of truth for each track's details.", + "type": "documentation + tooling (no production code change)", + "scope": { + "new_files": [ + "conductor/chronology.md", + "scripts/audit/generate_chronology.py", + "docs/reports/CHRONOLOGY_MIGRATION_20260619.md" + ], + "modified_files": [ + "conductor/tracks.md", + "conductor/workflow.md" + ], + "deleted_files": [] + }, + "estimated_effort": { + "method": "scope (per conductor/workflow.md Tier 1 Track Initialization Rules). NO day estimates.", + "phase_1": "1 task: data extraction audit + draft helper script (FR5)", + "phase_2": "1 task: run script, generate conductor/chronology.md.draft", + "phase_3": "1 task: prune [x]/[shipped] entries from conductor/tracks.md (FR2)", + "phase_4": "1 task: add 3-step archiving convention to conductor/workflow.md (FR3)", + "phase_5": "1 task: write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4)", + "phase_6": "1 task: user review of draft", + "phase_7": "1 task: final commit (rename draft to canonical)", + "phase_8": "165+ tasks: per-row cross-check (FR6 hard gate; one task per track)", + "phase_9": "1 task: completeness check (FR6 hard gate; folder set vs row set)", + "phase_10": "1 task: user sign-off (FR6 hard gate; user is the quality gate)", + "summary": "10 phases, 165+ cross-check tasks, 3 new files, 2 modified files. Per the user directive (2026-06-19), the cross-check (Phases 8-10) is the hard gate; nothing is committed until every row is verified and the user signs off." + }, + "verification_criteria": [ + "conductor/chronology.md exists and is populated with one row per track (active + shipped + superseded + abandoned) per FR1", + "Each row has: date, backticked track ID, status badge, one-sentence summary (≤25 words), folder link, range line (.. with commit count)", + "Notable Non-Track Commits section is sorted newest first with date + SHA + description per row", + "conductor/tracks.md no longer contains any [x] or [shipped] entries; the 3 sections (Phase 9, Active Research, Follow-up) either are removed or are one-line stubs pointing to chronology.md (FR2)", + "conductor/workflow.md 'Notes > Editing this file' section includes the new 3-step archiving convention (FR3)", + "docs/reports/CHRONOLOGY_MIGRATION_20260619.md exists with count summaries + diff preview + per-row cross-check log (FR4)", + "conductor/chronology.md is sorted newest first", + "Every track folder in conductor/tracks/ and conductor/archive/ has a corresponding row in chronology.md OR a documented exception in the migration report (FR6 completeness check)", + "Per-row cross-check completed: every row's 5 fields (date, ID, status, summary, range) were verified by Tier 1 before the file was committed (FR6, VC10)", + "User sign-off recorded in the migration report (FR6, VC12)", + "No new src/*.py files created (per AGENTS.md File Size and Naming Convention rule)", + "End-of-track report at docs/reports/TRACK_COMPLETION_chronology_20260619.md (if executed by Tier 2)" + ], + "risk_register": [ + { + "id": "R1", + "title": "Migration is incomplete (some tracks missed)", + "likelihood": "medium", + "scope_impact": "implementation may be larger than the spec suggests if many tracks lack spec.md or have ambiguous status", + "mitigation": "The migration report (FR4) explicitly lists skipped tracks; VC11 checks for 'every folder has a row OR a documented exception.'" + }, + { + "id": "R2", + "title": "Brief summaries are too long or too vague", + "likelihood": "medium", + "scope_impact": "implementation may require manual editing of ~165 summaries", + "mitigation": "The helper script (FR5) extracts the first sentence of spec.md; the cross-check (FR6) reviews and trims every row." + }, + { + "id": "R3", + "title": "Commit ranges are wrong (init SHA or end SHA)", + "likelihood": "low", + "scope_impact": "minimal - git log is authoritative", + "mitigation": "The cross-check (FR6 field 5) verifies init SHA and end SHA exist; the range is recomputed by the script per track folder." + }, + { + "id": "R4", + "title": "Date source is ambiguous (slug vs first-commit date)", + "likelihood": "low", + "scope_impact": "minimal", + "mitigation": "Rule (per FR1): use the slug date. If the slug date disagrees with the first commit (older tracks), the slug wins because the slug is the project's convention. Documented in FR1." + }, + { + "id": "R5", + "title": "User changes mind on the format after seeing the migration", + "likelihood": "medium", + "scope_impact": "implementation may be larger than the spec suggests", + "mitigation": "The migration is reviewed (Phase 6 + Phase 10 user sign-off) BEFORE the chronology.md is finalized. The draft phase (FR5) is the early review point; the final review is Phase 10." + }, + { + "id": "R6", + "title": "tracks.md pruning breaks a link the user uses", + "likelihood": "low", + "scope_impact": "minimal", + "mitigation": "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." + }, + { + "id": "R7", + "title": "Cross-check (FR6) is shallow or skipped (USER DIRECTIVE 2026-06-19)", + "likelihood": "high", + "scope_impact": "the whole track is not 'done' until every row is verified - this is a hard gate", + "mitigation": "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' clause in FR6." + }, + { + "id": "R8", + "title": "Folder has no spec.md (older tracks)", + "likelihood": "medium", + "scope_impact": "minimal - the summary is unknown", + "mitigation": "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." + }, + { + "id": "R9", + "title": "Track folder exists but is not a real track (e.g., a research note, a scratch dir)", + "likelihood": "medium", + "scope_impact": "minimal", + "mitigation": "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." + } + ], + "architecture_reference": { + "primary_documents": [ + "conductor/tracks.md (line 459: existing 'lightweight chronology' reference)", + "conductor/workflow.md 'Notes > Editing this file' (existing archive convention)" + ], + "related_tracks": [ + "conductor/archive/tier2_autonomous_sandbox_20260616/ (precedent for one-page reports at docs/reports/)", + "conductor/tracks/test_sandbox_hardening_20260619/ (precedent for spec/plan/metadata schema)" + ], + "styleguides": [ + "conductor/code_styleguides/feature_flags.md (helper script is 'delete to turn off')" + ] + }, + "deferred_to_followup_tracks": [ + { + "title": "Auto-generation of chronology.md on every commit", + "description": "Per the user's 'manual maintenance' choice (2026-06-19), there is no auto-generation. A future track could add a git hook that updates chronology.md on every archive-move commit, but this is explicitly out of scope for this track.", + "track_status": "not requested" + }, + { + "title": "GUI integration of the chronology", + "description": "The chronology is a markdown file for in-repo reading. A future track could add a GUI panel that visualizes it (e.g., a timeline view), but no GUI integration is in scope.", + "track_status": "not requested" + } + ], + "regressions_and_pre_existing_failures": [], + "pre_existing_failures_remaining": [], + "user_directives": [ + "Helper script may be used (approved 2026-06-19) but EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.", + "Manual maintenance is the ongoing workflow (approved 2026-06-19). The helper script is a one-shot extraction tool, not part of the ongoing workflow.", + "Date source is the track slug (not the first-commit date) per FR1. If the slug date disagrees with the first commit (older tracks), the slug wins.", + "Notable non-track commits section: 'if they look notable maybe we should note them' (user 2026-06-19). The bar is non-obvious work that wasn't part of a track.", + "chronology.md is manually maintained like tracks.md; the helper script (FR5) is draft-only.", + "No day estimates per conductor/workflow.md Tier 1 Track Initialization Rules (added 2026-06-16). Scope measured in files/sites." + ] +} diff --git a/conductor/tracks/chronology_20260619/spec.md b/conductor/tracks/chronology_20260619/spec.md new file mode 100644 index 00000000..4f31bbaa --- /dev/null +++ b/conductor/tracks/chronology_20260619/spec.md @@ -0,0 +1,250 @@ +# Track Specification: Conductor Chronology (2026-06-19) + +## 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. + +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. + +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). + +## Current State Audit (as of 2026-06-19) + +### Already Implemented (DO NOT re-implement) + +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. + +### 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 | + +## 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. + +## Functional Requirements + +### FR1. `conductor/chronology.md` file structure + +**WHERE:** New file `conductor/chronology.md` at the conductor root. + +**WHAT:** A markdown file with the following structure (top to bottom): + +```markdown +# Conductor Chronology + +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. + +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`). + +## Tracks (newest first) + +- **YYYY-MM-DD** — `track_id_` *(Status)* — One-sentence summary. + - Folder: [tracks/track_id_/](./tracks/track_id_/) (active) OR [archive/track_id_/](./archive/track_id_/) (shipped) + - Range: `..` (N commits) + +*(one row per track, ~165 total)* + +## Notable Non-Track Commits + +- **YYYY-MM-DD** — `` — One-line description of why this commit is notable. +- ... +``` + +**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_` 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//` (active) or `archive//` (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' -- ` and `git log --format='%h' -1 -- `. + +**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. + +### 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).* +``` + +### FR3. `conductor/workflow.md` update + +**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//` to `conductor/archive//`. +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. +``` + +### FR4. Migration report + +**WHERE:** New file `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`. + +**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. + +### FR5. Helper script (DRAFT-ONLY; never source of truth) + +**WHERE:** New file `scripts/audit/generate_chronology.py` (used for the initial population only). + +**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. + +**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. + +**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. + +**This script is REQUIRED for the initial migration** (165+ rows of hand-typing is impractical) but does NOT replace the cross-check. + +### FR6. Mandatory per-row cross-check (USER DIRECTIVE 2026-06-19) + +**WHERE:** `conductor/chronology.md.draft` (after the script runs per FR5), then `conductor/chronology.md` (after cross-check). + +**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. + +**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 .. -- ` and verify the count is plausible (not 0, not absurd). + +**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. + +**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. + +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. + +**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. + +**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 + +- **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.) + +## 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. + +## 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. +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`. +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. + +## 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. + +## 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' -- ` and `git log -1 --format='%h' -- `; 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. | + +## 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. + +## 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. +- `conductor/code_styleguides/feature_flags.md` — "delete to turn off" convention; the helper script (FR5) follows it. +- `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/.py` files; this track doesn't touch `src/`. +- `conductor/workflow.md` "Tier 1 Track Initialization Rules" — the no-day-estimates rule followed in this spec. diff --git a/conductor/tracks/chronology_20260619/state.toml b/conductor/tracks/chronology_20260619/state.toml new file mode 100644 index 00000000..c8c181a9 --- /dev/null +++ b/conductor/tracks/chronology_20260619/state.toml @@ -0,0 +1,85 @@ +# Track state for chronology_20260619 +# Updated by Tier 2 Tech Lead (or Tier 1 in this case) as tasks complete + +[meta] +track_id = "chronology_20260619" +name = "Conductor Chronology" +status = "active" +current_phase = 0 # 0 = pre-Phase 1; spec is written but no implementation yet +last_updated = "2026-06-19" + +[blocked_by] +# Independent track. No blockers. + +[blocks] +# No followup tracks blocked on this one (deferred items listed in metadata.json). + +[phases] +phase_1 = { status = "pending", checkpointsha = "", name = "Data extraction audit + draft helper script (FR5)" } +phase_2 = { status = "pending", checkpointsha = "", name = "Run script, generate conductor/chronology.md.draft" } +phase_3 = { status = "pending", checkpointsha = "", name = "Prune [x]/[shipped] entries from conductor/tracks.md (FR2)" } +phase_4 = { status = "pending", checkpointsha = "", name = "Add 3-step archiving convention to conductor/workflow.md (FR3)" } +phase_5 = { status = "pending", checkpointsha = "", name = "Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4)" } +phase_6 = { status = "pending", checkpointsha = "", name = "User review of draft" } +phase_7 = { status = "pending", checkpointsha = "", name = "Final commit (rename draft to canonical)" } +phase_8 = { status = "pending", checkpointsha = "", name = "Per-row cross-check (FR6 hard gate; 165+ tasks)" } +phase_9 = { status = "pending", checkpointsha = "", name = "Completeness check (FR6 hard gate; folder set vs row set)" } +phase_10 = { status = "pending", checkpointsha = "", name = "User sign-off (FR6 hard gate; user is the quality gate)" } + +[tasks] +# Phase 1 tasks +t1_1 = { status = "pending", commit_sha = "", description = "Audit: walk conductor/tracks/ and conductor/archive/; capture per-folder (id, date, status, init SHA, end SHA, summary source). Build the migration dataset." } +t1_2 = { status = "pending", commit_sha = "", description = "Write scripts/audit/generate_chronology.py per FR5: extract date from slug, init SHA via 'git log --reverse --format=%h -- ', end SHA via 'git log -1 --format=%h -- ', summary from spec.md first sentence (or metadata.json.description). Output markdown to stdout when --draft flag is set." } +t1_3 = { status = "pending", commit_sha = "", description = "Write 3-5 unit tests for the script: slug parsing, SHA extraction, summary extraction, multi-folder walk, draft output format. Commit Phase 1." } + +# Phase 2 tasks +t2_1 = { status = "pending", commit_sha = "", description = "Run 'uv run python scripts/audit/generate_chronology.py --draft > conductor/chronology.md.draft'. Verify the draft has one row per folder, 5 fields per row, sorted newest first." } +t2_2 = { status = "pending", commit_sha = "", description = "Sanity-check the draft: count rows; spot-check 5-10 rows against source spec.md; verify Notable Non-Track Commits section is empty (filled in later or by Tier 1 manually)." } + +# Phase 3 tasks +t3_1 = { status = "pending", commit_sha = "", description = "Prune 'Phase 9: Chore Tracks' section in conductor/tracks.md: either remove entirely or replace with a one-line stub pointing to chronology.md." } +t3_2 = { status = "pending", commit_sha = "", description = "Prune [x] entries from 'Active Research Tracks' section; keep [ ] in-flight entries. Verify with grep that no [x] remains." } +t3_3 = { status = "pending", commit_sha = "", description = "Prune [shipped: ...] entries from 'Follow-up (Planned, Not Yet Specced)' section; keep 'planned' and 'not yet specced' entries. Commit Phase 3." } + +# Phase 4 tasks +t4_1 = { status = "pending", commit_sha = "", description = "Append 3-step archiving convention to conductor/workflow.md 'Notes > Editing this file' section per FR3. Commit Phase 4." } + +# Phase 5 tasks +t5_1 = { status = "pending", commit_sha = "", description = "Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md per FR4: count by status, count by section removed, list of notable non-track commits, list of documented exceptions, 10-20 row diff preview for user spot-check. Commit Phase 5." } + +# Phase 6 tasks +t6_1 = { status = "pending", commit_sha = "", description = "User reviews conductor/chronology.md.draft + the migration report. Approves format, OR requests changes (loop back to Phase 2)." } + +# Phase 7 tasks +t7_1 = { status = "pending", commit_sha = "", description = "Rename conductor/chronology.md.draft to conductor/chronology.md. Commit Phase 7." } + +# Phase 8 tasks (per-row cross-check, 165+ rows) +# Each row's 5 fields are verified per FR6. +# This is a Tier 1 effort; rows are processed in batches of ~20 for commit granularity. +# Per the user directive: EVERY row, not a sample. +t8_1 = { status = "pending", commit_sha = "", description = "Batch 1 (~20 rows): cross-check the 20 newest tracks. Open each row, verify date/ID/status/summary/range. Fix any errors. Commit." } +t8_2 = { status = "pending", commit_sha = "", description = "Batch 2 (~20 rows): continue. Commit per batch." } +# ... (8-9 more batches to cover 165+ rows) + +# Phase 9 tasks +t9_1 = { status = "pending", commit_sha = "", description = "Enumerate every folder in conductor/tracks/ and conductor/archive/. Compare to row set in chronology.md. Diff must be empty OR only contain documented exceptions (per migration report)." } +t9_2 = { status = "pending", commit_sha = "", description = "For each missing folder: add the row (and verify per FR6), OR document the exception in the migration report. Commit Phase 9." } + +# Phase 10 tasks +t10_1 = { status = "pending", commit_sha = "", description = "User reviews the final chronology.md + migration report + completeness check result. Confirms: (a) format correct, (b) summaries accurate, (c) commit ranges right, (d) nothing missed. Records sign-off in the migration report." } + +[verification] +phase_8_cross_check_complete = false +phase_9_completeness_check_complete = false +phase_10_user_signoff_recorded = false +chronology_md_committed = false +tracks_md_pruned = false +workflow_md_updated = false +migration_report_committed = false + +[user_directives_logged] +cross_check_mandatory = "Per user 2026-06-19: 'EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.' Hard gate (FR6, VC10/11/12). No shortcut is acceptable." +helper_script_approved = "Per user 2026-06-19: helper script may be used, but is DRAFT-ONLY. The cross-check is the authority." +manual_maintenance = "Per user 2026-06-19: ongoing workflow is hand-edited (like tracks.md). The helper script is one-shot only." +no_day_estimates = "Per conductor/workflow.md Tier 1 Track Initialization Rules (added 2026-06-16). Scope measured in files/sites only." +date_source = "Per FR1: track slug date wins. First-commit date is the fallback when slug is missing."