manual_slop/conductor/tracks/chronology_20260619/spec.md

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):

# 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_<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 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>.

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:

#### 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:

**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.

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 <init>..<end> -- <folder> 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' -- <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.

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/<thing>.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.