Repository navigation
pm dashboard /roadmap: integrate the repos' own roadmap files (ROADMAP.md, planning/roadmaps/*.md) alongside the Grist table #1738
Description
Gap
The /roadmap page is fed only by a hand-maintained Grist table (doc "Program roadmap", read by sources/live.ts gristRoadmap). The repos' own roadmap records are invisible to the dashboard:
- dezren39/nix has ROADMAP.md (with its Done table, maintained by fleet jobs).
- developing-today/code keeps program roadmaps under planning/roadmaps/ (e.g. planning/roadmaps/id.md is the id program's record) plus .opencode/plans/ phase files.
- The Oct 26 dashboard review found the Grist roadmap held 16 rows with ZERO id rows, while ~68 id issues were open — the hand-kept table drifts from the repo records.
Related but different in scope: code#1216 (add PM stack rows to the code repo's ROADMAP.md / planning files) and code#1352 (program tending). This issue is the dashboard READ side: surface what the repos already record.
What to build
- A roadmap source in the aggregator that reads the repos' roadmap files from the laptop's primary checkouts (the aggregator already deploys from ~/git/code): ROADMAP.md files and planning/roadmaps/*.md, parsed into RoadmapRow-shaped records (title, area/project, status, horizon when stated, source file + heading anchor as the link).
- Merge with the Grist rows on /roadmap and /api/roadmap.json: each row shows its source (grist vs repo file); repo-derived rows link back to the file/heading.
- Dedup rule: when a Grist row and a repo section describe the same roadmap item (title/area match), prefer the repo row and note the Grist duplicate in provenance rather than showing both.
- Per code#1500's rule, the page must say why a section is empty (file missing vs parse-empty vs source unreadable).
Acceptance
- /roadmap shows rows derived from at least the code repo's planning/roadmaps/*.md and the nix repo's ROADMAP.md, with source labels and working links.
- The id program appears on the dashboard roadmap from its repo record without any hand entry.
- Grist rows still render; duplicates are collapsed per the rule above; the /api twin matches the page.
Raised by Drew 2026-10-28 ("does roadmap integrate roadmap.md files?" — currently no); companion to the PM event-log issue filed the same day.
Acceptance criteria
- /roadmap and /api/roadmap.json show rows derived from at least the code repo's planning/roadmaps/*.md and the nix repo's ROADMAP.md, with source labels and working links back to the file/heading.
- The id program appears on the dashboard roadmap from its repo record without any hand entry.
- Grist rows still render; duplicates are collapsed preferring the repo row with the Grist duplicate noted in provenance; any empty section says why (file missing vs parse-empty vs source unreadable).
Metadata
Metadata
Assignees
Labels
pm-stack (Pad/Grist) in developing-today/codeMedium: expected under 1 day of workNew feature or requestIntake review done: acceptance criteria, links, and normalized labels addedOrg Project gate: queued next — orchestrator adds to the boardOrdinary priority (the default)Filed directly by a humanTriaged and routed (see agent note)Queue packet kind: verify, reproduce, and route this itemNeeds a user-look: Muse reviews first and handles what it can
Activity
developing-today commentedon Oct 28, 2026
CODE-701
dezren39 commentedon Oct 28, 2026
Direction correction (Drew, 2026-10-28): the requirement is NOT primarily that /roadmap reads the Markdown files. The requirement is that all roadmap planning files are automatically synced — Grist table, ROADMAP.md files, planning/roadmaps/*.md, and any other roadmap home — so no source drifts from the others. Whether the dashboard should then READ the synced Markdown (vs keep reading Grist) is an implementation choice that needs a design pass before building: options include (a) sync engine keeps every store current and each consumer reads its native store, (b) one canonical store with the others as generated views, (c) read-through in the aggregator. The interim 4-hourly sync task (cron roadmap-sync-grist-md, first run 2026-10-28 ~16:13 CDT) covers the sync requirement operationally until this design lands. Acceptance updated: a design record comparing the options lands FIRST and is linked here; the build follows the design, not this issue's original framing.
dezren39 commentedon Oct 28, 2026
Intake review
Related: #1216 (PM-stack rows in the code repo's own ROADMAP/planning files — write side; this issue is the dashboard read side), #1352 (program tending), #1744 (shared schema), #1739 (event log, companion filed the same day).
Notes: Verified still live at intake (2026-10-28T17:45Z): /roadmap is still Grist-only per the body (sources/live.ts gristRoadmap); no PR adds a repo-files roadmap source. The drift evidence is concrete (16 Grist rows, zero id rows vs ~68 open id issues). Acceptance criteria section appended formalizing the body's
## Acceptancelist; original body preserved above it.Risks: Title/area matching for dedup is fuzzy — a bad match could hide a legitimately distinct Grist row; provenance note (per the body's rule) is the mitigation, keep it visible. Parsing two different roadmap formats (nix ROADMAP.md tables vs code planning/roadmaps/*.md) may need per-format parsers.
Suggested approach: Start with the code repo's planning/roadmaps/*.md (the aggregator already deploys from ~/git/code), prove the id program appears, then add nix ROADMAP.md, then the dedup pass.
🤖 Fleet monitor intake enrichment · 2026-10-28
20 remaining items
dezren39 commentedon Nov 3, 2026
agent-note:v1
event: pr_opened
task: 5037 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727)
state: design record submitted for review.
artifact: Roadmap homes synchronization design
PR: #4833 — OPEN against main. No dashboard or sync implementation is included.
validation: document-only; git diff --cached --check passed. Fresh PR checks currently show CodeRabbit NEUTRAL and no other check yet; CI will be rechecked.
resume: review PR checks; keep the proposed Grist authority and generated-view policy subject to Drew’s explicit decisions in the design.
dezren39 commentedon Nov 3, 2026
agent-note:v1
event: done
task: 5037 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727)
result: Design-only PR #4833 opened against main and the note linked on #1738. The record compares all three options, recommends a canonical-store/generated-view approach with Grist as a candidate pending Drew confirmation, and specifies identity, conflicts, freshness, rollout, and open decisions. No implementation or dashboard change.
validation:
git diff --cached --checkpassed. This prose-only change is class 0 under.github/ci-policy.md; no PR-tier test was required. Fresh PR state: OPEN; only CodeRabbit reportedskipping, with no pending CI checks.interim sync: #1738 documents the 4-hour schedule, but its current deployment/health could not be verified in the source repos or laptop user systemd; the note records this as unknown.
labels:
user/reviewadded; queue/status/work claim labels removed. Bookkeeping deferred to fleet reconciliation.dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · handed off
handed_off— the laptop claimant launches the bound opencode session, which drives task 7728 to its terminal state.dezren39 commentedon Nov 3, 2026
🤖 Agent note · triaged
bf419306-c4ef-470f-a553-beabf93239de(OpenChamber scheduled lane)/roadmapshould surface the repos' own roadmap files.pm-stack/aggregator/src/roadmap-reconcile.ts·planning/roadmaps/Verdict: still live, not implemented (checked at
mainbb592a618)What exists today.
/roadmapis fed by two sources, both non-file: Grist's "Program roadmap" rows plus the org Project pool's Kind=Epic items, joined bypm-stack/aggregator/src/roadmap-reconcile.ts(header: "Grist roadmap ↔ Project epic reconciliation (#1144)").roadmap-annotations.tsadds commentary on top. Neither reads a markdown roadmap file.What the issue asks for and is missing. A source that parses the repos' own records into
RoadmapRows and merges them into/roadmapand/api/roadmap.json, with a Grist/repo dedup rule.git grepforplanning/roadmaps/ROADMAP.mdinsidepm-stack/aggregator/srcfinds onlyproject-config.ts, where they appear ashomeDoclinks on project pages (e.g.planning/roadmaps/basement-cluster.md,id.md,repo-and-ci.md,mcpx.md) — i.e. the dashboard already knows those files exist, but no parser turns them into rows.The records to read do exist (verified in the checkout): repo root
ROADMAP.md;planning/roadmaps/{id,mcpx,nixos-and-infra,repo-and-ci,basement-cluster,basement-cluster-electrician-brief}.md;planning/templates/roadmap-item.md.Scoped fix path (three pieces, in this order)
roadmap-files.tsthat readsROADMAP.md+planning/roadmaps/*.mdand emitsRoadmapRow-shaped records (title, area/project from the file or heading, status, horizon when stated, link = file path + heading anchor). Unit-test against the real files plus a fixture, matchingroadmap-reconcile.test.tsstyle.source: grist | repo, prefer the repo row when title/area match, and keep the Grist duplicate as a noted annotation rather than dropping it silently — the same "surface both readings" postureproject-config.tsalready argues for./roadmapbadges the source and links a repo row to its file/anchor;/api/roadmap.jsonpublishes the same field, soroadmap-reconcile's drift counts keep working.Blockers / ordering to record before work starts
~/code/dezren39-nix(the nixROADMAP.mdthe issue cites was not readable), while~/git/codeis present. Decide the checkout root(s) and behaviour when a repo is absent (skip with a stated reason vs fail the read) before writing the parser./roadmapshows for existing rows, so it belongs with the roadmap's owner.next,effort/manduser/review, and a design-sized read-path change is not asmall_fix, so no fix packet was enqueued from this triage.