conductor(track): add initial spec for chronology_20260619
Conductor Chronology is a manually-maintained, complete index of all tracks (active + shipped + superseded + abandoned) plus notable non-track commits. The per-track spec/plan/metadata in tracks/ and archive/ remain the source of truth for each track's details; this file is the index. Scope (per the no-day-estimates rule added 2026-06-16): - 6 FRs, 5 NFRs, 12 VCs, 9 Risks, 10 Phases - 3 new files: conductor/chronology.md, scripts/audit/generate_chronology.py, docs/reports/CHRONOLOGY_MIGRATION_20260619.md - 2 modified files: conductor/tracks.md (prune [x] entries), conductor/workflow.md (3-step archiving convention) - 165+ per-row cross-check tasks (Phase 8 hard gate per user directive 2026-06-19) User directive baked in as FR6 + VC10/VC11/VC12: 'EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.' The helper script is DRAFT-ONLY; the cross-check is the authority. Tier 1 does the mechanical check; the user is the quality gate. Plan + initial migration to follow in subsequent commits.
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
{
|
||||
"track_id": "chronology_20260619",
|
||||
"name": "Conductor Chronology",
|
||||
"created": "2026-06-19",
|
||||
"status": "spec_written",
|
||||
"blocked_by": [],
|
||||
"blocks": [],
|
||||
"priority": "C",
|
||||
"rationale": "conductor/tracks.md currently has duplicated completed-track listings across 3 sections (Phase 9 Chore Tracks, Active Research Tracks [x], Follow-up [shipped]). This track creates conductor/chronology.md as the single canonical index of all tracks (active + shipped + superseded + abandoned) plus notable non-track commits, removes the duplicates from tracks.md, and documents the new convention in workflow.md. The per-track spec/plan/metadata in tracks/ and archive/ remain the source of truth for each track's details.",
|
||||
"type": "documentation + tooling (no production code change)",
|
||||
"scope": {
|
||||
"new_files": [
|
||||
"conductor/chronology.md",
|
||||
"scripts/audit/generate_chronology.py",
|
||||
"docs/reports/CHRONOLOGY_MIGRATION_20260619.md"
|
||||
],
|
||||
"modified_files": [
|
||||
"conductor/tracks.md",
|
||||
"conductor/workflow.md"
|
||||
],
|
||||
"deleted_files": []
|
||||
},
|
||||
"estimated_effort": {
|
||||
"method": "scope (per conductor/workflow.md Tier 1 Track Initialization Rules). NO day estimates.",
|
||||
"phase_1": "1 task: data extraction audit + draft helper script (FR5)",
|
||||
"phase_2": "1 task: run script, generate conductor/chronology.md.draft",
|
||||
"phase_3": "1 task: prune [x]/[shipped] entries from conductor/tracks.md (FR2)",
|
||||
"phase_4": "1 task: add 3-step archiving convention to conductor/workflow.md (FR3)",
|
||||
"phase_5": "1 task: write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4)",
|
||||
"phase_6": "1 task: user review of draft",
|
||||
"phase_7": "1 task: final commit (rename draft to canonical)",
|
||||
"phase_8": "165+ tasks: per-row cross-check (FR6 hard gate; one task per track)",
|
||||
"phase_9": "1 task: completeness check (FR6 hard gate; folder set vs row set)",
|
||||
"phase_10": "1 task: user sign-off (FR6 hard gate; user is the quality gate)",
|
||||
"summary": "10 phases, 165+ cross-check tasks, 3 new files, 2 modified files. Per the user directive (2026-06-19), the cross-check (Phases 8-10) is the hard gate; nothing is committed until every row is verified and the user signs off."
|
||||
},
|
||||
"verification_criteria": [
|
||||
"conductor/chronology.md exists and is populated with one row per track (active + shipped + superseded + abandoned) per FR1",
|
||||
"Each row has: date, backticked track ID, status badge, one-sentence summary (≤25 words), folder link, range line (<init-sha>..<end-sha> with commit count)",
|
||||
"Notable Non-Track Commits section is sorted newest first with date + SHA + description per row",
|
||||
"conductor/tracks.md no longer contains any [x] or [shipped] entries; the 3 sections (Phase 9, Active Research, Follow-up) either are removed or are one-line stubs pointing to chronology.md (FR2)",
|
||||
"conductor/workflow.md 'Notes > Editing this file' section includes the new 3-step archiving convention (FR3)",
|
||||
"docs/reports/CHRONOLOGY_MIGRATION_20260619.md exists with count summaries + diff preview + per-row cross-check log (FR4)",
|
||||
"conductor/chronology.md is sorted newest first",
|
||||
"Every track folder in conductor/tracks/ and conductor/archive/ has a corresponding row in chronology.md OR a documented exception in the migration report (FR6 completeness check)",
|
||||
"Per-row cross-check completed: every row's 5 fields (date, ID, status, summary, range) were verified by Tier 1 before the file was committed (FR6, VC10)",
|
||||
"User sign-off recorded in the migration report (FR6, VC12)",
|
||||
"No new src/*.py files created (per AGENTS.md File Size and Naming Convention rule)",
|
||||
"End-of-track report at docs/reports/TRACK_COMPLETION_chronology_20260619.md (if executed by Tier 2)"
|
||||
],
|
||||
"risk_register": [
|
||||
{
|
||||
"id": "R1",
|
||||
"title": "Migration is incomplete (some tracks missed)",
|
||||
"likelihood": "medium",
|
||||
"scope_impact": "implementation may be larger than the spec suggests if many tracks lack spec.md or have ambiguous status",
|
||||
"mitigation": "The migration report (FR4) explicitly lists skipped tracks; VC11 checks for 'every folder has a row OR a documented exception.'"
|
||||
},
|
||||
{
|
||||
"id": "R2",
|
||||
"title": "Brief summaries are too long or too vague",
|
||||
"likelihood": "medium",
|
||||
"scope_impact": "implementation may require manual editing of ~165 summaries",
|
||||
"mitigation": "The helper script (FR5) extracts the first sentence of spec.md; the cross-check (FR6) reviews and trims every row."
|
||||
},
|
||||
{
|
||||
"id": "R3",
|
||||
"title": "Commit ranges are wrong (init SHA or end SHA)",
|
||||
"likelihood": "low",
|
||||
"scope_impact": "minimal - git log is authoritative",
|
||||
"mitigation": "The cross-check (FR6 field 5) verifies init SHA and end SHA exist; the range is recomputed by the script per track folder."
|
||||
},
|
||||
{
|
||||
"id": "R4",
|
||||
"title": "Date source is ambiguous (slug vs first-commit date)",
|
||||
"likelihood": "low",
|
||||
"scope_impact": "minimal",
|
||||
"mitigation": "Rule (per FR1): use the slug date. If the slug date disagrees with the first commit (older tracks), the slug wins because the slug is the project's convention. Documented in FR1."
|
||||
},
|
||||
{
|
||||
"id": "R5",
|
||||
"title": "User changes mind on the format after seeing the migration",
|
||||
"likelihood": "medium",
|
||||
"scope_impact": "implementation may be larger than the spec suggests",
|
||||
"mitigation": "The migration is reviewed (Phase 6 + Phase 10 user sign-off) BEFORE the chronology.md is finalized. The draft phase (FR5) is the early review point; the final review is Phase 10."
|
||||
},
|
||||
{
|
||||
"id": "R6",
|
||||
"title": "tracks.md pruning breaks a link the user uses",
|
||||
"likelihood": "low",
|
||||
"scope_impact": "minimal",
|
||||
"mitigation": "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."
|
||||
},
|
||||
{
|
||||
"id": "R7",
|
||||
"title": "Cross-check (FR6) is shallow or skipped (USER DIRECTIVE 2026-06-19)",
|
||||
"likelihood": "high",
|
||||
"scope_impact": "the whole track is not 'done' until every row is verified - this is a hard gate",
|
||||
"mitigation": "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' clause in FR6."
|
||||
},
|
||||
{
|
||||
"id": "R8",
|
||||
"title": "Folder has no spec.md (older tracks)",
|
||||
"likelihood": "medium",
|
||||
"scope_impact": "minimal - the summary is unknown",
|
||||
"mitigation": "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."
|
||||
},
|
||||
{
|
||||
"id": "R9",
|
||||
"title": "Track folder exists but is not a real track (e.g., a research note, a scratch dir)",
|
||||
"likelihood": "medium",
|
||||
"scope_impact": "minimal",
|
||||
"mitigation": "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."
|
||||
}
|
||||
],
|
||||
"architecture_reference": {
|
||||
"primary_documents": [
|
||||
"conductor/tracks.md (line 459: existing 'lightweight chronology' reference)",
|
||||
"conductor/workflow.md 'Notes > Editing this file' (existing archive convention)"
|
||||
],
|
||||
"related_tracks": [
|
||||
"conductor/archive/tier2_autonomous_sandbox_20260616/ (precedent for one-page reports at docs/reports/)",
|
||||
"conductor/tracks/test_sandbox_hardening_20260619/ (precedent for spec/plan/metadata schema)"
|
||||
],
|
||||
"styleguides": [
|
||||
"conductor/code_styleguides/feature_flags.md (helper script is 'delete to turn off')"
|
||||
]
|
||||
},
|
||||
"deferred_to_followup_tracks": [
|
||||
{
|
||||
"title": "Auto-generation of chronology.md on every commit",
|
||||
"description": "Per the user's 'manual maintenance' choice (2026-06-19), there is no auto-generation. A future track could add a git hook that updates chronology.md on every archive-move commit, but this is explicitly out of scope for this track.",
|
||||
"track_status": "not requested"
|
||||
},
|
||||
{
|
||||
"title": "GUI integration of the chronology",
|
||||
"description": "The chronology is a markdown file for in-repo reading. A future track could add a GUI panel that visualizes it (e.g., a timeline view), but no GUI integration is in scope.",
|
||||
"track_status": "not requested"
|
||||
}
|
||||
],
|
||||
"regressions_and_pre_existing_failures": [],
|
||||
"pre_existing_failures_remaining": [],
|
||||
"user_directives": [
|
||||
"Helper script may be used (approved 2026-06-19) but EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.",
|
||||
"Manual maintenance is the ongoing workflow (approved 2026-06-19). The helper script is a one-shot extraction tool, not part of the ongoing workflow.",
|
||||
"Date source is the track slug (not the first-commit date) per FR1. If the slug date disagrees with the first commit (older tracks), the slug wins.",
|
||||
"Notable non-track commits section: 'if they look notable maybe we should note them' (user 2026-06-19). The bar is non-obvious work that wasn't part of a track.",
|
||||
"chronology.md is manually maintained like tracks.md; the helper script (FR5) is draft-only.",
|
||||
"No day estimates per conductor/workflow.md Tier 1 Track Initialization Rules (added 2026-06-16). Scope measured in files/sites."
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,250 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Track state for chronology_20260619
|
||||
# Updated by Tier 2 Tech Lead (or Tier 1 in this case) as tasks complete
|
||||
|
||||
[meta]
|
||||
track_id = "chronology_20260619"
|
||||
name = "Conductor Chronology"
|
||||
status = "active"
|
||||
current_phase = 0 # 0 = pre-Phase 1; spec is written but no implementation yet
|
||||
last_updated = "2026-06-19"
|
||||
|
||||
[blocked_by]
|
||||
# Independent track. No blockers.
|
||||
|
||||
[blocks]
|
||||
# No followup tracks blocked on this one (deferred items listed in metadata.json).
|
||||
|
||||
[phases]
|
||||
phase_1 = { status = "pending", checkpointsha = "", name = "Data extraction audit + draft helper script (FR5)" }
|
||||
phase_2 = { status = "pending", checkpointsha = "", name = "Run script, generate conductor/chronology.md.draft" }
|
||||
phase_3 = { status = "pending", checkpointsha = "", name = "Prune [x]/[shipped] entries from conductor/tracks.md (FR2)" }
|
||||
phase_4 = { status = "pending", checkpointsha = "", name = "Add 3-step archiving convention to conductor/workflow.md (FR3)" }
|
||||
phase_5 = { status = "pending", checkpointsha = "", name = "Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4)" }
|
||||
phase_6 = { status = "pending", checkpointsha = "", name = "User review of draft" }
|
||||
phase_7 = { status = "pending", checkpointsha = "", name = "Final commit (rename draft to canonical)" }
|
||||
phase_8 = { status = "pending", checkpointsha = "", name = "Per-row cross-check (FR6 hard gate; 165+ tasks)" }
|
||||
phase_9 = { status = "pending", checkpointsha = "", name = "Completeness check (FR6 hard gate; folder set vs row set)" }
|
||||
phase_10 = { status = "pending", checkpointsha = "", name = "User sign-off (FR6 hard gate; user is the quality gate)" }
|
||||
|
||||
[tasks]
|
||||
# Phase 1 tasks
|
||||
t1_1 = { status = "pending", commit_sha = "", description = "Audit: walk conductor/tracks/ and conductor/archive/; capture per-folder (id, date, status, init SHA, end SHA, summary source). Build the migration dataset." }
|
||||
t1_2 = { status = "pending", commit_sha = "", description = "Write scripts/audit/generate_chronology.py per FR5: extract date from slug, init SHA via 'git log --reverse --format=%h -- <folder>', end SHA via 'git log -1 --format=%h -- <folder>', summary from spec.md first sentence (or metadata.json.description). Output markdown to stdout when --draft flag is set." }
|
||||
t1_3 = { status = "pending", commit_sha = "", description = "Write 3-5 unit tests for the script: slug parsing, SHA extraction, summary extraction, multi-folder walk, draft output format. Commit Phase 1." }
|
||||
|
||||
# Phase 2 tasks
|
||||
t2_1 = { status = "pending", commit_sha = "", description = "Run 'uv run python scripts/audit/generate_chronology.py --draft > conductor/chronology.md.draft'. Verify the draft has one row per folder, 5 fields per row, sorted newest first." }
|
||||
t2_2 = { status = "pending", commit_sha = "", description = "Sanity-check the draft: count rows; spot-check 5-10 rows against source spec.md; verify Notable Non-Track Commits section is empty (filled in later or by Tier 1 manually)." }
|
||||
|
||||
# Phase 3 tasks
|
||||
t3_1 = { status = "pending", commit_sha = "", description = "Prune 'Phase 9: Chore Tracks' section in conductor/tracks.md: either remove entirely or replace with a one-line stub pointing to chronology.md." }
|
||||
t3_2 = { status = "pending", commit_sha = "", description = "Prune [x] entries from 'Active Research Tracks' section; keep [ ] in-flight entries. Verify with grep that no [x] remains." }
|
||||
t3_3 = { status = "pending", commit_sha = "", description = "Prune [shipped: ...] entries from 'Follow-up (Planned, Not Yet Specced)' section; keep 'planned' and 'not yet specced' entries. Commit Phase 3." }
|
||||
|
||||
# Phase 4 tasks
|
||||
t4_1 = { status = "pending", commit_sha = "", description = "Append 3-step archiving convention to conductor/workflow.md 'Notes > Editing this file' section per FR3. Commit Phase 4." }
|
||||
|
||||
# Phase 5 tasks
|
||||
t5_1 = { status = "pending", commit_sha = "", description = "Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md per FR4: count by status, count by section removed, list of notable non-track commits, list of documented exceptions, 10-20 row diff preview for user spot-check. Commit Phase 5." }
|
||||
|
||||
# Phase 6 tasks
|
||||
t6_1 = { status = "pending", commit_sha = "", description = "User reviews conductor/chronology.md.draft + the migration report. Approves format, OR requests changes (loop back to Phase 2)." }
|
||||
|
||||
# Phase 7 tasks
|
||||
t7_1 = { status = "pending", commit_sha = "", description = "Rename conductor/chronology.md.draft to conductor/chronology.md. Commit Phase 7." }
|
||||
|
||||
# Phase 8 tasks (per-row cross-check, 165+ rows)
|
||||
# Each row's 5 fields are verified per FR6.
|
||||
# This is a Tier 1 effort; rows are processed in batches of ~20 for commit granularity.
|
||||
# Per the user directive: EVERY row, not a sample.
|
||||
t8_1 = { status = "pending", commit_sha = "", description = "Batch 1 (~20 rows): cross-check the 20 newest tracks. Open each row, verify date/ID/status/summary/range. Fix any errors. Commit." }
|
||||
t8_2 = { status = "pending", commit_sha = "", description = "Batch 2 (~20 rows): continue. Commit per batch." }
|
||||
# ... (8-9 more batches to cover 165+ rows)
|
||||
|
||||
# Phase 9 tasks
|
||||
t9_1 = { status = "pending", commit_sha = "", description = "Enumerate every folder in conductor/tracks/ and conductor/archive/. Compare to row set in chronology.md. Diff must be empty OR only contain documented exceptions (per migration report)." }
|
||||
t9_2 = { status = "pending", commit_sha = "", description = "For each missing folder: add the row (and verify per FR6), OR document the exception in the migration report. Commit Phase 9." }
|
||||
|
||||
# Phase 10 tasks
|
||||
t10_1 = { status = "pending", commit_sha = "", description = "User reviews the final chronology.md + migration report + completeness check result. Confirms: (a) format correct, (b) summaries accurate, (c) commit ranges right, (d) nothing missed. Records sign-off in the migration report." }
|
||||
|
||||
[verification]
|
||||
phase_8_cross_check_complete = false
|
||||
phase_9_completeness_check_complete = false
|
||||
phase_10_user_signoff_recorded = false
|
||||
chronology_md_committed = false
|
||||
tracks_md_pruned = false
|
||||
workflow_md_updated = false
|
||||
migration_report_committed = false
|
||||
|
||||
[user_directives_logged]
|
||||
cross_check_mandatory = "Per user 2026-06-19: 'EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL CORRECT, AND NOTHING WAS MISSED.' Hard gate (FR6, VC10/11/12). No shortcut is acceptable."
|
||||
helper_script_approved = "Per user 2026-06-19: helper script may be used, but is DRAFT-ONLY. The cross-check is the authority."
|
||||
manual_maintenance = "Per user 2026-06-19: ongoing workflow is hand-edited (like tracks.md). The helper script is one-shot only."
|
||||
no_day_estimates = "Per conductor/workflow.md Tier 1 Track Initialization Rules (added 2026-06-16). Scope measured in files/sites only."
|
||||
date_source = "Per FR1: track slug date wins. First-commit date is the fallback when slug is missing."
|
||||
Reference in New Issue
Block a user