From f0f404632255236388f9ed5af3a18152cdbdf715 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Fri, 19 Jun 2026 20:03:39 -0400 Subject: [PATCH] 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. --- conductor/tracks/chronology_20260619/plan.md | 402 +++++++++++++++++++ 1 file changed, 402 insertions(+) create mode 100644 conductor/tracks/chronology_20260619/plan.md diff --git a/conductor/tracks/chronology_20260619/plan.md b/conductor/tracks/chronology_20260619/plan.md new file mode 100644 index 00000000..1f6f35af --- /dev/null +++ b/conductor/tracks/chronology_20260619/plan.md @@ -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 `/tracks/` and `/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' -- ` (first commit) + - Extracts end SHA via `git log -1 --format='%h' -- ` (last commit) + - Computes commit count via `git log --oneline .. -- | wc -l` (approximate; actual count is the `git log ..` line count) + - Extracts status from folder location: `tracks/` = `Active`; `archive/` = `Shipped`. Override via `/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 `. 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//spec.md" | Select-Object -First 1` (verify summary source) + - `git log --oneline --reverse -- "conductor/archive//"` (verify init SHA) + - `git log -1 --format='%h' -- "conductor/archive//"` (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//` 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. + ``` + - 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 .. -- ` 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/, conductor/archive/` (verify folder exists; pick the right location based on status) + - `Get-Content "conductor///spec.md" | Select-Object -First 1` (verify summary source) + - `git log --oneline --reverse -- "conductor///"` (verify init SHA) + - `git log -1 --format='%h' -- "conductor///"` (verify end SHA) + - `git log --oneline .. -- "conductor///" | 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 -- ` / `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.