# Tracker UX Upgrade — Overview Landing, Milestone Dashboard, Phase Timeline, Item Pages, Kanban

- Poster: claude
- Date: 2026-06-18
- Status: closed (human-directed work, completed and verified)
- Topic: Upgrade the `docs/tracking` generated site so partners open to an
  overview, can read milestone/phase health at a glance, drill into per-item
  detail pages, and watch a live kanban — modeled on the GCMD lab tracker.

## Human Direction (the brief)

Human direction 2026-06-18: "focus on sprint tracker updates and update the
handoff at end using deliberations as a way to explain your work." Six explicit
requirements:

1. `docs/tracking` should open to the overview.
2. Milestones shown in a horizontal dashboard with a clear done state.
3. Phase summaries showing milestone lists + HITL/open tasks, synced with the
   sprint tracker.
4. A phase timeline visualization + an overview breakdown of what is actively
   being worked on, with per-milestone progress.
5. A better route + an item navigation/detail page per the GCMD lab pattern
   (each item captures goals / todos / findings / concerns / risks / HITL /
   artifacts).
6. An active kanban visual in the sprint tracker.

This is human-directed work, not an open question, so it is recorded as a
closed deliberation explaining what changed and where the evidence lives.

## Response From Claude

I rewrote `apps/web/scripts/build-sprint-tracker.mjs` so a single generator
emits a small linked site from the existing JSON sources
(`status.json`, `roadmap.json`, `hitl-tasks.json`). Nothing about the data
contract changed; only the rendering and routing did. Mapping to the brief:

1. **Opens to overview.** `index.html` is now the overview landing.
   `overview.html` is a meta-refresh redirect to `index.html` so the old route
   still works. A shared `page()` wrapper gives every page a tab nav
   (Overview / Sprint Board / Requirements / Decisions / roadmap.json) with the
   active tab highlighted and depth-correct relative links.
2. **Horizontal milestone dashboard.** A "Milestone dashboard" section renders
   every gate as a chip grouped by phase (`.mstrip` / `.mchip`), done gates show
   a green check, in-progress are highlighted, todo are muted — "every gate at a
   glance."
3. **Phase summaries synced to the board.** Phase summary cards list each
   phase's milestones with status, plus the work items mapped to that phase
   (`itemsForPhase`) and the HITL tasks for that phase (`hitlForPhase`), so the
   overview and the sprint board read from the same status source and cannot
   drift.
4. **Phase timeline + active breakdown.** A "Phase timeline" strip
   (`.timeline` / `.tlphase`) shows A->G with per-phase progress bars and lane
   styling (the parallel positioning phase is dashed). An "Active now" block
   surfaces the current sprint with per-milestone progress. The KPI row adds
   milestone-gates-passed, current-sprint milestones, work-items-done %, active
   phases, and HITL-waiting counts.
5. **Item detail pages + better route.** Every status item generates
   `items/<id>.html` (GCMD lab pattern): Goals, a Checklist/Milestone-gate list
   (derived from roadmap milestone gates or `item.todos`), Human-in-the-loop,
   Findings, Concerns, Risks, Artifacts, and a Work log. Section tables and
   board cards link to these pages.
6. **Kanban.** `sprint.html` leads with a four-column board
   (`.kanban` / `.kcol`: To Do / In Progress / Blocked / Done) with per-column
   counts; each card carries owner, priority, and milestone-gate chips and links
   to its item page. The per-section item tables remain below.

To make pages 4 and 5 real rather than empty scaffolds, I enriched the two
in-progress items in `status.json` with `goals`, `todos`, `concerns`, `risks`,
`artifacts`, and a dated `log` entry:

- `sprint-1-spine-poc` — todos for B1 identity/status contract, B2 QR resolver,
  B3 CSV roundtrip, and demo fixtures; artifacts linking the closed build-order
  deliberation and the capture-to-sale tracking contract.
- `hitl-foundation` — todos for the Mark S-corp plan, trademark research, Paul
  review, and Justin contribution log; artifacts linking `hitl-tasks.json`.

### Verification

- `npm run docs:tracker` built clean: `index.html` (overview), `sprint.html`
  (kanban + 6/21 items done), 21 `items/*.html`, `overview.html` (redirect);
  milestone gates 3/23 done.
- Served on the local doc server and confirmed HTTP 200 for `index.html`,
  `sprint.html`, `overview.html`, and two sample item pages.
- Rendered small previews of the overview and sprint board and visually
  confirmed the milestone dashboard, phase timeline, and kanban render as
  intended.

### Scope notes

- No plan, roadmap, milestone, or requirement scope changed — this is a
  presentation/routing upgrade over the accepted D6/D7 structure, so no new
  decision-log row is warranted.
- `apps/web/CLAUDE.md` and `pricing-and-tokens.md` were left untouched.
- Open for Codex review: the item-page schema fields (goals/todos/findings/
  concerns/risks/hitl/artifacts/log) are now the convention for enriching any
  item; extend the remaining items as they enter `in_progress`.

## Human decision

Work performed under the standing 2026-06-18 direction above. No further
decision required; recorded for Codex visibility.