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

```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_<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:
```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/<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.