USM

Appearance

usm/gen-roadmap [in-progress] ​

Roadmap improvements — add feature links and shipped_in version to roadmap items, fill in USM's own roadmap with real delivery items, and render the roadmap page with status badges and feature cross-links. Also fixes sidebar dead links and mermaid rendering.

Status: in-progress

Intent ​

The roadmap page was empty because we treated it as "future plans only." A roadmap should show the full delivery arc — what shipped, what's in progress, what's next. Roadmap items should link to their corresponding feature specs so a visitor can click through from "shipped: VitePress docs" to the feature detail. Additionally, the sidebar has dead links (risks, roadmap, usmconfig, case-mismatched agentsMd/testSpecs) and mermaid diagrams don't render in VitePress. These are all fixed together.

Decisions ​

Decision: Roadmap items can optionally reference a feature $id via a feature field

Rationale: Not every roadmap item is a feature (some are refactors, infra, etc.), but when a roadmap item corresponds to a feature, linking them lets the generated roadmap page cross-link to the feature spec. The feature field is optional — roadmap items without a feature link still work.

shipped-in-optional [accepted] ​

Decision: Add optional shipped_in field to roadmap items for version tracking

Rationale: When a roadmap item ships, recording which package version it shipped in gives a release history without complex versioning machinery. The CHANGELOG already tracks release contents — shipped_in just annotates the roadmap item with the version number.

Decision: Sidebar generation should only include links to files that exist

Rationale: The sidebar currently includes links to /risks and /roadmap even when those pages aren't generated (empty content suppressed). The sidebar generator should check if the target file exists before adding the link. Same for feature links — only include features whose docs files exist.

mermaid-via-vitepress-plugin [accepted] ​

Decision: Use VitePress mermaid plugin instead of relying on native mermaid rendering

Rationale: VitePress doesn't render mermaid code blocks by default — they show as raw text. The vitepress-plugin-mermaid plugin (or MermaidMarkdown plugin) enables mermaid rendering. This is configured in the VitePress config.

Flows ​

Generate roadmap page with feature links and status badges (generate-roadmap-with-links) ​

When usm generate runs, if the system has roadmap items, generate a roadmap.md page with a table showing status badge, title (linked to feature spec if feature field is set), shipped_in version, and target date.

  1. parse → system.usm roadmap array
  2. generate → table with Status, Title, Shipped In, Target Date columns
  3. link → feature $id to features/<area>/<slug> path if feature field set
  4. write → .usm-workspace/docs/roadmap.md (only if roadmap items exist)

The sidebar generator in docs.ts should check if the target .md file exists before adding a sidebar entry. This prevents dead links for suppressed pages (risks, roadmap) and missing feature docs.

  1. check → does risks.md exist in docs root?
  2. check → does roadmap.md exist in docs root?
  3. check → does each feature doc file exist before adding to sidebar?
  4. skip → omit sidebar entries for non-existent files

Fix sidebar slug case to match actual file names (fix-sidebar-case-sensitivity) ​

The sidebar slug derivation uses feat.id.replace(/^[^-]+-/, "") which produces lowercase slugs. But actual file names preserve case from the source .usm file path (e.g., agentsMd.md not agentsmd.md). The sidebar should derive the slug from the ref path, not the $id.

  1. parse → feature ref path (e.g., .usm/features/generators/agentsMd.usm)
  2. derive → slug from ref path preserving case (agentsMd, not agentsmd)
  3. generate → sidebar link with correct case

Enable mermaid rendering in VitePress config (enable-mermaid-in-vitepress) ​

VitePress doesn't render mermaid code blocks by default. Add the vitepress-plugin-mermaid to the VitePress config so architecture diagrams and other mermaid blocks render properly.

  1. install → vitepress-plugin-mermaid as dev dependency
  2. configure → add MermaidMarkdown plugin to VitePress config.mts
  3. verify → architecture diagram renders on the architecture page

Contracts ​

roadmap-only-generated-when-non-empty ​

Roadmap page is only generated when system.usm has roadmap items

Acceptance criteria:

  • [ ] Empty roadmap array → no roadmap.md generated
  • [ ] Non-empty roadmap → roadmap.md with table

Sidebar must not contain links to non-existent files

Acceptance criteria:

  • [ ] Links to /risks only if risks.md exists
  • [ ] Links to /roadmap only if roadmap.md exists
  • [ ] Feature links only if the feature doc file exists

Sidebar links must match actual file name case

Acceptance criteria:

  • [ ] agentsMd link matches agentsMd.md file
  • [ ] testSpecs link matches testSpecs.md file

mermaid-renders-in-vitepress ​

Mermaid code blocks render as diagrams, not raw text

Acceptance criteria:

  • [ ] Architecture page shows rendered diagram
  • [ ] Other mermaid blocks render properly

Tests ​

roadmap-with-items ​

Given:

  • system_with_roadmap_items: true

Then:

  • assertion: roadmap.md generated with table
  • assertion: shipped items show status badge
  • assertion: items with feature field link to feature spec

roadmap-empty ​

Given:

  • system_with_empty_roadmap: true

Then:

  • assertion: roadmap.md not generated
  • assertion: no roadmap link in sidebar

Given:

  • risks_md_does_not_exist: true

Then:

  • assertion: no Risks link in sidebar

Given:

  • feature_with_camelcase_filename: true

Then:

  • assertion: sidebar link matches file name case exactly

Implementation ​

  • Primary: src/generators/markdown.ts
  • Test code status: none

See Also ​

  • usm/gen-markdown
  • usm/cli-docs