conductor(plan): add implementation plan for chronology_20260619

10 phases, 29 tasks, all worker-ready (WHERE / WHAT / HOW / SAFETY / COMMIT / GIT NOTE per task): Phase 1: Data extraction audit + draft helper script (FR5; TDD) Phase 2: Generate conductor/chronology.md.draft Phase 3: Prune [x]/[shipped] entries from conductor/tracks.md (FR2) Phase 4: Add 3-step archiving convention to conductor/workflow.md (FR3) Phase 5: Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4) Phase 6: User review of draft (GATE) Phase 7: Promote draft to canonical chronology.md Phase 8: Per-row cross-check (FR6 HARD GATE; 9 batches of ~20 rows) Phase 9: Completeness check (FR6 HARD GATE; folder set vs row set) Phase 10: User sign-off + end-of-track report (FR6 HARD GATE) The cross-check (Phase 8) is the dominant cost. Per the user directive 2026-06-19, EVERY SINGLE ENTRY must be cross-checked. The plan batches the work into 9 commits for review ergonomics; no batch is 'sample-based' or 'looks right' -- each row's 5 fields (date, ID, status, summary, range) are verified independently per FR6. All 12 VCs from the spec are addressed in the plan's 'Verification Criteria Recap' section.
2026-06-19 20:03:39 -04:00
parent 87923c93af
commit f0f4046322
1 changed files with 402 additions and 0 deletions
@@ -0,0 +1,402 @@
+# Conductor Chronology Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Create `conductor/chronology.md` as the canonical manually-maintained index of all tracks (active + shipped + superseded + abandoned) plus notable non-track commits, prune the duplicated `[x]` entries from `conductor/tracks.md`, document the new 3-step archiving convention in `conductor/workflow.md`, and write a migration report. Every row is cross-checked per the user directive (2026-06-19): "EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED."
+
+**Architecture:** One-shot helper script (`scripts/audit/generate_chronology.py`, FR5) extracts per-track data from `conductor/tracks/` and `conductor/archive/` and produces a draft `chronology.md.draft`. Tier 1 (or the user) then cross-checks every row in the draft per FR6 (5 fields: date, ID, status, summary, range), and verifies completeness (every folder has a row). The user is the final quality gate (VC12). No CI integration; the file is hand-maintained like `tracks.md`.
+
+**Tech Stack:** Python 3.11+ (helper script), `tomllib`, `git log` (for commit SHAs), `pathlib`. No new production code in `src/`. No new dependencies.
+
+**Spec reference:** `conductor/tracks/chronology_20260619/spec.md` (250 lines; 6 FRs, 5 NFRs, 12 VCs, 9 Risks, 10 Phases).
+
+---
+
+## Phase 1: Data extraction audit + draft helper script (FR5)
+
+Focus: Build the extraction tool. The tool emits a DRAFT (per FR5); the cross-check (FR6, Phase 8) is the authority.
+
+- [ ] **Task 1.1: Audit the source folders** (estimate: 5 min)
+  - WHERE: `conductor/tracks/`, `conductor/archive/`
+  - WHAT: Enumerate every subfolder. For each, capture: folder name, presence of `spec.md` / `plan.md` / `metadata.json`, and the date string in the slug (if any).
+  - HOW: `Get-ChildItem -Directory conductor/tracks`, `Get-ChildItem -Directory conductor/archive` (PowerShell). Save counts to `tests/artifacts/chronology_audit_step1.json`: `{"tracks_count": N, "archive_count": M, "with_slug": X, "without_slug": Y}`.
+  - SAFETY: Read-only. Don't modify any folder.
+  - NO COMMIT (investigation only).
+
+- [ ] **Task 1.2: Write failing tests for the helper script** (estimate: 5 min)
+  - WHERE: New file `tests/test_generate_chronology.py`
+  - WHAT: 5 unit tests covering the script's per-folder extraction logic:
+    1. `test_slug_date_extraction` — given folder name `gencpp_python_bindings_20260308`, returns `2026-03-08`
+    2. `test_slug_date_extraction_handles_missing_date` — given `my_folder` (no date), returns `None`
+    3. `test_summary_extraction_from_spec_md` — given a `spec.md` with "## Overview\n\nFirst sentence here. Second sentence.", returns `"First sentence here."`
+    4. `test_summary_extraction_falls_back_to_metadata` — given a folder with `metadata.json.description` and no `spec.md`, returns the description
+    5. `test_summary_extraction_truncates_to_25_words` — given a 50-word sentence, returns first 25 words + "…"
+  - HOW: Use `pytest.tmp_path` to create fixture folders with synthetic `spec.md` / `metadata.json`. Pure unit tests; no `live_gui`, no `tmp_path_factory.mktemp` outside `./tests/`.
+  - SAFETY: Tests must FAIL initially (the script doesn't exist yet). Use `pytest.raises` for the failure case.
+  - VERIFY: `uv run pytest tests/test_generate_chronology.py -v` should FAIL on each test with `ModuleNotFoundError` or `NameError`.
+  - COMMIT: `test(chronology): failing tests for generate_chronology.py extraction logic`
+  - GIT NOTE: "Phase 1.2. TDD red. 5 tests cover slug date parsing, summary extraction, fallback chain, word truncation. Tests must fail before Task 1.3 writes the script."
+
+- [ ] **Task 1.3: Write the helper script (TDD green)** (estimate: 10 min)
+  - WHERE: New file `scripts/audit/generate_chronology.py`
+  - WHAT: A Python 3.11+ script that:
+    - Accepts `--draft` flag (output to stdout) and `--root PATH` (default: `conductor/`)
+    - Walks `<root>/tracks/` and `<root>/archive/`
+    - For each folder:
+      - Extracts date from slug (regex `\d{8}$`); falls back to first-commit date if slug has no date
+      - Extracts init SHA via `git log --reverse --format='%h' -- <folder>` (first commit)
+      - Extracts end SHA via `git log -1 --format='%h' -- <folder>` (last commit)
+      - Computes commit count via `git log --oneline <init>..<end> -- <folder> | wc -l` (approximate; actual count is the `git log <init>..<end>` line count)
+      - Extracts status from folder location: `tracks/` = `Active`; `archive/` = `Shipped`. Override via `<folder>/metadata.json.status` if present.
+      - Extracts summary: prefer `metadata.json.description` (modern tracks); else first non-empty line of `spec.md` (trimmed to 25 words, "…" if truncated); else first non-empty line of `plan.md`; else `"Imported from archive (no spec)"`.
+    - Emits markdown to stdout: one row per folder, sorted by date descending. Format per FR1.
+  - HOW: Use `subprocess.run(["git", "log", ...], capture_output=True, text=True)` for git queries. Use `pathlib`. Match the 1-space indentation convention.
+  - SAFETY: The script is READ-ONLY on the source folders. It writes to stdout only.
+  - VERIFY: `uv run pytest tests/test_generate_chronology.py -v` should now PASS (all 5 tests green).
+  - COMMIT: `feat(chronology): add draft-only helper script (FR5)`
+  - GIT NOTE: "Phase 1.3. TDD green. generate_chronology.py extracts date/SHA/status/summary per track folder. Draft-only: emits to stdout; the cross-check (Phase 8) is the authority."
+
+- [ ] **Task 1.4: Commit Phase 1** (estimate: 1 min)
+  - WHERE: Working tree
+  - WHAT: Confirm both files (`tests/test_generate_chronology.py` + `scripts/audit/generate_chronology.py`) are staged from Tasks 1.2 + 1.3. Verify `git status` is clean except for pre-existing modifications.
+  - HOW: `git log -1 --stat` to confirm the Phase 1 commit is in place.
+  - SAFETY: Don't commit unrelated working-tree changes.
+  - NO COMMIT (Phase 1 already committed in Task 1.3).
+  - CHECKPOINT: `conductor(checkpoint): Phase 1 complete — script + tests green`
+
+---
+
+## Phase 2: Generate `chronology.md.draft` (FR5 + pre-Phase 8 prep)
+
+Focus: Run the script, produce the draft. Do NOT commit `chronology.md` yet — it's still a draft.
+
+- [ ] **Task 2.1: Run the script, capture the draft** (estimate: 2 min)
+  - WHERE: `scripts/audit/generate_chronology.py`
+  - WHAT: `uv run python scripts/audit/generate_chronology.py --draft > conductor/chronology.md.draft`. This produces one row per track (165+ rows), sorted newest first.
+  - HOW: Run the command. Verify the output file exists and has > 100 rows.
+  - SAFETY: The draft file is git-ignored OR clearly marked as draft (e.g., filename `chronology.md.draft`).
+  - VERIFY: `Get-Content conductor/chronology.md.draft | Measure-Object -Line`. Expect ≥ 200 lines (header + 165+ rows × ~4 lines each).
+  - NO COMMIT (draft is not canonical yet).
+
+- [ ] **Task 2.2: Sanity-check 5-10 random rows** (estimate: 5 min)
+  - WHERE: `conductor/chronology.md.draft`
+  - WHAT: Pick 5 random rows; for each, manually verify the 5 fields (date, ID, status, summary, range) against the source folder's `spec.md` and `git log <folder>`. If any field is wrong, the script has a bug — fix the script in a follow-up commit BEFORE Phase 3.
+  - HOW: For each picked row, run:
+    - `Get-Content "conductor/archive/<id>/spec.md" | Select-Object -First 1` (verify summary source)
+    - `git log --oneline --reverse -- "conductor/archive/<id>/"` (verify init SHA)
+    - `git log -1 --format='%h' -- "conductor/archive/<id>/"` (verify end SHA)
+  - SAFETY: Don't proceed to Phase 3 if the script is buggy. Fix the script first.
+  - NO COMMIT (sanity check, not implementation).
+
+---
+
+## Phase 3: Prune `conductor/tracks.md` (FR2)
+
+Focus: Remove the 3 categories of `[x]`/`[shipped]` entries. Preserve in-flight and backlog entries.
+
+- [ ] **Task 3.1: Prune "Phase 9: Chore Tracks" section** (estimate: 5 min)
+  - WHERE: `conductor/tracks.md` (around the "Phase 9" heading, roughly lines 480-560 based on the file's current size)
+  - WHAT: Either delete the entire "Phase 9: Chore Tracks" section OR replace it with a one-line stub:
+    ```markdown
+    ### Phase 9: Chore Tracks
+    *Completed chore tracks are in [`chronology.md`](./chronology.md).*
+    ```
+  - HOW: Use the `manual-slop_edit_file` MCP tool with the exact anchor for the section header + the first child line. Verify with `git diff conductor/tracks.md`.
+  - SAFETY: Don't touch the "Active Tracks" table at the top of the file, the "Backlog" section, the "Follow-up" section, or the "Notes" section.
+  - VERIFY: `grep -n "^- \[x\]" conductor/tracks.md | wc -l` should be reduced (this counts the remaining `[x]` markers; non-zero is fine if "Active Research" still has them, but should be smaller than before).
+  - COMMIT: `conductor(track): prune Phase 9 Chore Tracks section from tracks.md (FR2)`
+  - GIT NOTE: "Phase 3.1. Phase 9 section either deleted or stubbed; canonical record now in chronology.md."
+
+- [ ] **Task 3.2: Prune `[x]` entries from "Active Research Tracks"** (estimate: 5 min)
+  - WHERE: `conductor/tracks.md` "Active Research Tracks" section
+  - WHAT: Remove only the `[x]` entries (e.g., the Fable review row that shipped 2026-06-18). Keep the `[ ]` in-flight entries.
+  - HOW: For each `[x]` line in the section, delete the entire bullet (including the linked line, if any). The section heading and the `[ ]` rows stay.
+  - SAFETY: Don't remove the section heading. Don't remove the `[ ]` rows. Don't touch other sections.
+  - VERIFY: `grep -n "Active Research Tracks" -A 20 conductor/tracks.md` shows no `[x]` rows in that section.
+  - COMMIT: `conductor(track): prune [x] entries from Active Research Tracks (FR2)`
+  - GIT NOTE: "Phase 3.2. [x] entries from Active Research Tracks moved to chronology.md. [ ] in-flight rows preserved."
+
+- [ ] **Task 3.3: Prune `[shipped: ...]` entries from "Follow-up"** (estimate: 5 min)
+  - WHERE: `conductor/tracks.md` "Follow-up (Planned, Not Yet Specced)" section
+  - WHAT: Remove only the `[shipped: YYYY-MM-DD]` entries. Keep the "planned" and "not yet specced" entries.
+  - HOW: For each `[shipped: ...]` bullet, delete the entire bullet. The section heading and the active followups stay.
+  - SAFETY: Don't remove the section heading. Don't remove the "planned" entries. Don't touch other sections.
+  - VERIFY: `grep -n "shipped:" conductor/tracks.md | wc -l` should be 0.
+  - COMMIT: `conductor(track): prune [shipped] entries from Follow-up section (FR2)`
+  - GIT NOTE: "Phase 3.3. [shipped] entries from Follow-up moved to chronology.md. 'planned' and 'not yet specced' rows preserved."
+
+- [ ] **Task 3.4: Verify no `[x]` remains** (estimate: 2 min)
+  - WHERE: `conductor/tracks.md`
+  - WHAT: Final scan. Any `[x]` in the file should be in a "Status legend" or in-context comment, not a track entry.
+  - HOW: `grep -n "^- \[x\]" conductor/tracks.md`. Expected: 0 matches.
+  - SAFETY: If there are matches, identify which section and Task 3.1/3.2/3.3 missed them. Fix and re-commit.
+  - NO COMMIT (verification only).
+  - CHECKPOINT: `conductor(checkpoint): Phase 3 complete — tracks.md pruned`
+
+---
+
+## Phase 4: Update `conductor/workflow.md` (FR3)
+
+Focus: Document the 3-step archiving convention.
+
+- [ ] **Task 4.1: Append the 3-step convention** (estimate: 3 min)
+  - WHERE: `conductor/workflow.md` "Notes > Editing this file" section (the last subsection of the "Notes" section near the end of the file)
+  - WHAT: Append the following 3-step block:
+    ```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.
+    ```
+  - HOW: Find the "Editing this file" subheading; append after its last paragraph.
+  - SAFETY: Don't change the existing convention text; just add the new block at the end.
+  - VERIFY: `grep -n "Archiving a track" conductor/workflow.md` should match.
+  - COMMIT: `conductor(track): document 3-step archiving convention in workflow.md (FR3)`
+  - GIT NOTE: "Phase 4. Workflow.md gets the 3-step convention: move folder, remove from tracks.md, add to chronology.md."
+  - CHECKPOINT: `conductor(checkpoint): Phase 4 complete — workflow.md updated`
+
+---
+
+## Phase 5: Write the migration report (FR4)
+
+Focus: One-page report for the user to review. This is the user's first check-point to verify the migration is on track.
+
+- [ ] **Task 5.1: Write the report** (estimate: 10 min)
+  - WHERE: New file `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`
+  - WHAT: Markdown report with the following sections:
+    1. **Summary** — total rows in `chronology.md` (active + shipped + superseded + abandoned); total rows removed from `tracks.md`; total notable non-track commits.
+    2. **Counts by status** — table: status, count.
+    3. **Counts by `tracks.md` section removed** — table: section, count.
+    4. **Documented exceptions** — list of folders that have no row in `chronology.md` (per FR6 completeness check) with one-line reason each.
+    5. **Notable non-track commits added** — list of SHAs + dates + one-line descriptions.
+    6. **Diff preview (10-20 rows)** — first 10 + last 10 rows of `chronology.md` for the user to spot-check the format and content.
+    7. **Per-row cross-check log** — table of (row index, track ID, date verified, ID verified, status verified, summary verified, range verified, fixes if any). For Phase 5 (pre-cross-check), this is empty; it gets filled in during Phase 8.
+    8. **User sign-off** — final section with a checklist for the user to fill in during Phase 10.
+  - HOW: Generate the counts by running the script with `--counts` flag (add this flag in a script update, or compute manually from `chronology.md.draft` for now). Manually write the diff preview by copy-pasting 10 rows from the draft.
+  - SAFETY: The report is the user's window into the migration. Make the tables readable; don't dump raw data.
+  - VERIFY: The file should be 100-200 lines, well-formatted markdown.
+  - COMMIT: `docs(chronology): write CHRONOLOGY_MIGRATION_20260619.md (FR4)`
+  - GIT NOTE: "Phase 5. Migration report written. Pre-cross-check; the per-row log is empty until Phase 8."
+  - CHECKPOINT: `conductor(checkpoint): Phase 5 complete — migration report drafted`
+
+---
+
+## Phase 6: User review of the draft (gate)
+
+Focus: The user reviews the draft + report. Approves, OR requests changes (loop back to Phase 2).
+
+- [ ] **Task 6.1: User reviews `conductor/chronology.md.draft` + the migration report** (estimate: user-paced)
+  - WHERE: `conductor/chronology.md.draft`, `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`
+  - WHAT: User opens both files and confirms:
+    - (a) The format matches FR1.
+    - (b) The diff preview in the report is accurate.
+    - (c) The documented exceptions are acceptable.
+    - (d) The overall structure is correct.
+  - HOW: User posts "approve" or specific change requests.
+  - OUTCOMES:
+    - **Approve** → proceed to Phase 7.
+    - **Request changes** → loop back to Phase 2 (re-run script with fixed parameters, regenerate draft, update report).
+  - SAFETY: Don't proceed past Phase 6 without explicit user approval.
+  - NO COMMIT (gate).
+
+---
+
+## Phase 7: Promote draft to canonical + commit (FR1, FR2, FR3, FR4 finalized)
+
+Focus: Rename `chronology.md.draft` to `chronology.md`; this is the first time `chronology.md` is committed.
+
+- [ ] **Task 7.1: Rename + commit** (estimate: 2 min)
+  - WHERE: `conductor/chronology.md.draft` → `conductor/chronology.md`
+  - WHAT: `git mv conductor/chronology.md.draft conductor/chronology.md`. Then `git commit` with the message below.
+  - HOW: `git mv` preserves git history; the file appears as a rename in the diff. (If `chronology.md` already exists for some reason, the `git mv` will fail; in that case, delete the old file first, but this shouldn't happen since chronology.md didn't exist before.)
+  - SAFETY: Verify the rename with `git status` before commit. Verify the file content is identical to the draft.
+  - VERIFY: `git log -1 --stat` shows the rename.
+  - COMMIT: `conductor(track): add conductor/chronology.md (FR1)`
+  - GIT NOTE: "Phase 7. chronology.md promoted from draft to canonical. Pre-cross-check; rows are verified in Phase 8."
+  - CHECKPOINT: `conductor(checkpoint): Phase 7 complete — chronology.md committed (pre-cross-check)`
+
+---
+
+## Phase 8: Per-row cross-check (FR6, HARD GATE)
+
+Focus: **EVERY** row is opened and verified per FR6's 5 fields. The migration report's per-row log is filled in. **This is the hard gate per the user directive (2026-06-19). NO shortcut is acceptable.**
+
+The 5 fields per row (per FR6):
+1. **Date** — match the slug (`YYYYMMDD` → `YYYY-MM-DD`)? Fix any disagreement.
+2. **Track ID** — backticked slug matches the folder name?
+3. **Status** — `Active` / `In Progress` / `Shipped` / `Superseded` / `Abandoned`? Per FR1's status mapping.
+4. **Summary** — accurate, ≤ 25 words, describes the most important fact? Trim or rewrite if needed.
+5. **Range** — init SHA exists, end SHA exists, count is plausible? Run `git log --oneline <init>..<end> -- <folder>` to spot-check.
+
+The cross-check is done in batches of ~20 rows for commit granularity. Each batch is one commit. Per the user directive: "EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED." Every row, no samples.
+
+- [ ] **Task 8.1: Batch 1 — newest 20 rows** (estimate: 30 min)
+  - WHERE: First 20 rows of `conductor/chronology.md`
+  - WHAT: For each row, verify the 5 fields. Fix any errors in `chronology.md`. Log the result in the migration report's per-row table.
+  - HOW: For each row, run:
+    - `Get-ChildItem -Directory conductor/tracks/<id>, conductor/archive/<id>` (verify folder exists; pick the right location based on status)
+    - `Get-Content "conductor/<tracks|archive>/<id>/spec.md" | Select-Object -First 1` (verify summary source)
+    - `git log --oneline --reverse -- "conductor/<tracks|archive>/<id>/"` (verify init SHA)
+    - `git log -1 --format='%h' -- "conductor/<tracks|archive>/<id>/"` (verify end SHA)
+    - `git log --oneline <init>..<end> -- "conductor/<tracks|archive>/<id>/" | Measure-Object -Line` (verify count)
+  - SAFETY: Don't trust the script output. Verify each row independently. If a field is wrong, fix the row in `chronology.md` BEFORE moving to the next row.
+  - VERIFY: After this batch, the first 20 rows are confirmed correct in the migration report.
+  - COMMIT: `conductor(chronology): cross-check batch 1 — 20 newest rows verified (FR6)`
+  - GIT NOTE: "Phase 8.1. Per-row cross-check batch 1. 20 rows verified; [N] fixes applied; per-row log updated in migration report."
+
+- [ ] **Task 8.2: Batch 2 — rows 21-40** (estimate: 30 min)
+  - WHERE: Rows 21-40 of `conductor/chronology.md`
+  - WHAT: Same procedure as 8.1.
+  - HOW: Same as 8.1.
+  - SAFETY: Same as 8.1.
+  - VERIFY: Rows 21-40 are correct.
+  - COMMIT: `conductor(chronology): cross-check batch 2 — rows 21-40 verified (FR6)`
+  - GIT NOTE: "Phase 8.2. Per-row cross-check batch 2."
+
+- [ ] **Task 8.3: Batch 3 — rows 41-60** (estimate: 30 min)
+  - WHERE / WHAT / HOW / SAFETY / VERIFY / COMMIT / GIT NOTE: Same pattern as 8.1.
+
+- [ ] **Task 8.4: Batch 4 — rows 61-80** (estimate: 30 min)
+  - Same pattern.
+
+- [ ] **Task 8.5: Batch 5 — rows 81-100** (estimate: 30 min)
+  - Same pattern.
+
+- [ ] **Task 8.6: Batch 6 — rows 101-120** (estimate: 30 min)
+  - Same pattern.
+
+- [ ] **Task 8.7: Batch 7 — rows 121-140** (estimate: 30 min)
+  - Same pattern.
+
+- [ ] **Task 8.8: Batch 8 — rows 141-160** (estimate: 30 min)
+  - Same pattern.
+
+- [ ] **Task 8.9: Batch 9 — rows 161+ (final batch)** (estimate: 30 min)
+  - WHERE: Remaining rows (whatever the count is after batch 8).
+  - WHAT: Final batch. After this, every row in `chronology.md` has been verified.
+  - SAFETY: If the count is > 160 + 20, split into another batch. Don't exceed 30 rows per batch for review ergonomics.
+  - VERIFY: Every row in `chronology.md` is now in the per-row log as "verified".
+  - COMMIT: `conductor(chronology): cross-check batch 9 (final) — all rows verified (FR6)`
+  - GIT NOTE: "Phase 8.9. FINAL cross-check batch. All 165+ rows verified; FR6 per-row gate satisfied."
+  - CHECKPOINT: `conductor(checkpoint): Phase 8 complete — all rows cross-checked`
+
+---
+
+## Phase 9: Completeness check (FR6, HARD GATE)
+
+Focus: Every folder in `conductor/tracks/` and `conductor/archive/` has a row in `chronology.md`. No exceptions except documented ones.
+
+- [ ] **Task 9.1: Enumerate folders, compare to rows** (estimate: 10 min)
+  - WHERE: `conductor/tracks/`, `conductor/archive/`, `conductor/chronology.md`
+  - WHAT: Get the list of folder names from both directories. Get the list of track IDs from `chronology.md`. Compute the set difference: folders without rows, rows without folders.
+  - HOW:
+    - Folders: `Get-ChildItem -Directory conductor/tracks | Select-Object -ExpandProperty Name` + `Get-ChildItem -Directory conductor/archive | Select-Object -ExpandProperty Name`
+    - Rows: extract backticked track IDs from `chronology.md` via `Select-String -Pattern '`([a-z_0-9]+_\d{8})`' -AllMatches`
+    - Diff: `Compare-Object -ReferenceObject $folders -DifferenceObject $rows`
+  - SAFETY: An empty diff is the goal. If non-empty, every diff item needs disposition (added or exception).
+  - VERIFY: `$diff` is empty OR only contains documented exceptions.
+  - NO COMMIT (verification only).
+
+- [ ] **Task 9.2: Resolve diff** (estimate: 10 min)
+  - WHERE: `conductor/chronology.md` + `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`
+  - WHAT: For each item in the diff from 9.1:
+    - If it's a folder without a row: add the row (using the same FR1 format; extract data per the script; verify per FR6's 5 fields).
+    - If it's a row without a folder: investigate. Either the folder was renamed/removed (update the row's folder link) or the row is stale (remove it). Document the resolution in the migration report.
+  - HOW: Add rows using the same procedure as Phase 8 (verify 5 fields, log in the per-row table). Update the migration report's "Documented exceptions" section if any folders are intentional non-tracks.
+  - VERIFY: Re-run the diff from 9.1; the result is now empty (or only contains documented exceptions).
+  - COMMIT: `conductor(chronology): completeness check passed — folder set matches row set (FR6)`
+  - GIT NOTE: "Phase 9. FR6 completeness check. [N] missing rows added; [M] exceptions documented. Diff is now empty."
+  - CHECKPOINT: `conductor(checkpoint): Phase 9 complete — completeness check passed`
+
+---
+
+## Phase 10: User sign-off (FR6, HARD GATE)
+
+Focus: The user is the quality gate. The track is not "done" until the user signs off.
+
+- [ ] **Task 10.1: User reviews final state** (estimate: user-paced)
+  - WHERE: `conductor/chronology.md`, `conductor/tracks.md`, `conductor/workflow.md`, `docs/reports/CHRONOLOGY_MIGRATION_20260619.md`
+  - WHAT: User confirms:
+    - (a) The format is correct.
+    - (b) The summaries are accurate.
+    - (c) The commit ranges are right.
+    - (d) Nothing was missed.
+  - HOW: User fills in the "User sign-off" section in the migration report with a confirmation + date.
+  - OUTCOMES:
+    - **Sign-off** → track is complete. Proceed to end-of-track wrap-up.
+    - **More changes** → loop back to the relevant phase (Phase 8 for per-row fixes, Phase 9 for completeness, etc.).
+  - SAFETY: No commit after Phase 10 without user sign-off.
+  - NO COMMIT (gate).
+
+- [ ] **Task 10.2: End-of-track report** (estimate: 15 min)
+  - WHERE: New file `docs/reports/TRACK_COMPLETION_chronology_20260619.md`
+  - WHAT: Per Tier 2 conventions (precedent: `TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md`), write a one-page end-of-track report with:
+    - Summary (1-2 sentences)
+    - Final state (5 fields: chronology.md, tracks.md, workflow.md, migration report, end-of-track report)
+    - Statistics (rows in chronology, batches in Phase 8, fixes applied, exceptions documented)
+    - Cross-check summary (per VC10/11/12 confirmation)
+    - User sign-off (reference to the migration report)
+    - Lessons learned (optional; "what would I do differently next time")
+  - HOW: Write the file. Commit.
+  - SAFETY: No new content beyond the summary; link to existing files.
+  - COMMIT: `docs(chronology): add end-of-track report`
+  - GIT NOTE: "Phase 10.2. Track complete. User sign-off recorded. All VCs satisfied."
+
+- [ ] **Task 10.3: Update `conductor/tracks.md`** (estimate: 2 min)
+  - WHERE: `conductor/tracks.md` top-level entry for `chronology_20260619`
+  - WHAT: Add a line at the top of the file (or in the active section) noting the new track's completion. Mark it `[x]` completed.
+  - HOW: Edit the file; flip the status marker.
+  - SAFETY: Don't touch other entries.
+  - VERIFY: `grep -n "chronology_20260619" conductor/tracks.md` shows the entry with `[x]`.
+  - COMMIT: `conductor(track): mark chronology_20260619 as complete in tracks.md`
+  - GIT NOTE: "Phase 10.3. Track marked complete in tracks.md."
+
+- [ ] **Task 10.4: Update `state.toml` to completed** (estimate: 1 min)
+  - WHERE: `conductor/tracks/chronology_20260619/state.toml`
+  - WHAT: Set `[meta].status = "completed"`, `[meta].current_phase = "complete"`, all phase statuses to `"completed"`, all task statuses to `"completed"`, all `[verification]` flags to `true`.
+  - HOW: Edit the file.
+  - SAFETY: Don't change the task descriptions; just flip the status fields.
+  - VERIFY: `uv run python -c "import tomllib; tomllib.load(open('conductor/tracks/chronology_20260619/state.toml','rb'))"` parses cleanly.
+  - COMMIT: `conductor(track): mark chronology_20260619 as completed`
+  - GIT NOTE: "Phase 10.4. Track complete. All VCs satisfied; user sign-off recorded."
+
+---
+
+## Summary
+
+| Phase | Scope | Time estimate | Gate? |
+|---|---|---|---|
+| 1 | Data extraction + script + tests | ~25 min | No |
+| 2 | Generate draft | ~7 min | No |
+| 3 | Prune tracks.md (3 sections) | ~17 min | No |
+| 4 | Update workflow.md | ~3 min | No |
+| 5 | Write migration report | ~10 min | No |
+| 6 | User review of draft | user-paced | Yes |
+| 7 | Promote draft to canonical | ~2 min | No |
+| 8 | Per-row cross-check (165+ rows, 9 batches) | ~4.5 hours | Yes (HARD per user directive) |
+| 9 | Completeness check | ~20 min | Yes (HARD) |
+| 10 | User sign-off + end-of-track | ~20 min | Yes (HARD) |
+
+**Total: ~5.5 hours of focused work** (estimated scope, not time-bound; per the no-day-estimates rule). The cross-check (Phase 8) is the dominant cost; the user's "EVERY SINGLE ENTRY" mandate makes this non-negotiable.
+
+## Verification Criteria Recap
+
+All 12 VCs from the spec must be satisfied for the track to be marked complete:
+- VC1-VC5: File contents (FR1, FR2, FR3, FR4) — verified in Phases 3, 4, 5, 7.
+- VC6: Sort order (FR1) — verified in Phase 7.
+- VC7: Folder coverage (FR6 completeness) — verified in Phase 9.
+- VC8: No `src/*.py` files created — verified by `git diff --stat` against the spec'd scope.
+- VC9: End-of-track report — written in Phase 10.2.
+- VC10: Per-row cross-check completed (FR6) — verified at end of Phase 8.
+- VC11: Completeness check (FR6) — verified at end of Phase 9.
+- VC12: User sign-off (FR6) — recorded in Phase 10.1.
+
+## Cross-cutting safety
+
+- **No day estimates in the report.** Per the project rule added 2026-06-16.
+- **Per-task atomic commits.** Per `conductor/workflow.md` "Commit Guidelines" — one commit per task, no batching.
+- **Git notes on every commit.** Per the project convention.
+- **No `git restore` / `git checkout -- <file>` / `git reset`.** Per the HARD BAN in `AGENTS.md`.
+- **No new `src/*.py` files.** Per `AGENTS.md` File Size and Naming Convention. The helper script lives in `scripts/audit/`; no `src/` changes.
+- **No new `conductor/code_styleguides/*` files.** The 3-step convention is added to existing `workflow.md`, not a new styleguide.