ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
db7d94de886eb8246fac5e2b66d33af2f6e032a1
manual_slop/conductor/tracks/chronology_20260619/plan.md
T
ed f0f4046322 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

28 KiB
Raw Blame History

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: 
      ### 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: 
      
**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.
View Git Blame Copy Permalink