Implementation Governance (TOGAF Phase G)
Auto-generated from USM feature contracts and system risks.
Feature Contracts (200)
| Feature | Contract ID | Description | Applies After | Must Have |
|---|---|---|---|---|
| usm/cli-color-output | symbols-colored | Status symbols are colored in TTY output | — | ✓ green; ✗ red; ⚠ yellow; ⊘ dim/yellow; → cyan |
| usm/cli-color-output | no-color-respected | NO_COLOR env var disables all color | — | NO_COLOR set → output is plain text; NO_COLOR unset → colors active in TTY |
| usm/cli-color-output | non-tty-plain | Piped/redirected output is plain text | — | stdout not a TTY → no ANSI codes; stderr not a TTY → no ANSI codes; spinner suppressed in non-TTY; progress bar suppressed in non-TTY; output remains grep-friendly |
| usm/cli-color-output | palette-consistent | Color semantics are consistent across all commands | — | success states green across init/scan/validate/generate/enrich/etc; error states red across all commands; warning states yellow across all commands; file paths and counts dim across all commands |
| usm/cli-color-output | deps-cjs-compatible | All new dependencies are CJS-compatible | — | picocolors ^1 (CJS); ora ^5 (last CJS major; v6+ is ESM); cli-progress ^3 (CJS); treeify ^0.1 (CJS); update-notifier ^5 (last CJS major; v7+ is ESM); package.json remains CommonJS (no module type field) |
| usm/cli-color-output | spinner-long-ops | Animated spinner during async operations | — | scan, enrich, generate show spinner with elapsed context; spinner clears and is replaced by result line on completion; spinner suppressed in non-TTY (plain log fallback) |
| usm/cli-color-output | progress-batch | Progress bar for batch file operations | — | generate writing N files shows progress bar with current/total; scan detecting services shows count progress; bar hidden in non-TTY |
| usm/cli-color-output | tree-file-lists | File lists rendered as tree view | — | Files written/skipped lists use tree connectors; nested .usm/ structure shown hierarchically; flat fallback in non-TTY |
| usm/cli-color-output | ascii-banner | ASCII art USM banner on no-args/help | — | usm with no args shows ASCII USM banner then help; banner suppressed in non-TTY |
| usm/cli-color-output | did-you-mean | Suggestions for unknown commands | — | usm scaan suggests scan via did-you-mean; suggestion shown via Commander built-in |
| usm/cli-color-output | update-notifier | One-line hint when a newer @smithgray/usm is published | — | checks npm registry in background, non-blocking; cached with 24h interval; hint only shown if newer version exists and in TTY |
| usm/cli-color-output | verbosity-flags | --quiet and --verbose flags across commands | — | --quiet shows only errors and final summary; default shows current output level; --verbose shows timestamps, full paths, debug info |
| usm/cli-config-outputs | outputs-configurable | All output paths are configurable via usmconfig.json | — | Generators read paths from config, not hardcoded; Defaults work when config is missing or outputs section absent; All output types have config keys: workspace, docs, help_docs, archimate, togaf, openapi, tests, agents_md |
| usm/cli-config-outputs | only-flag-works | generate --only <target> runs only the specified output | — | Invalid target shows error with valid options; No --only runs all generators (backward compatible); Valid targets: docs, help-docs, togaf, archimate, openapi, tests, rules, agents-md |
| usm/cli-config-outputs | no-colon-commands | generate:xxx commands are removed | — | generate:help-docs removed — use 'generate --only help-docs'; generate:togaf removed — use 'generate --only togaf'; generate:archimate removed — use 'generate --only archimate' |
| usm/config-validation | config-validated-at-load | Every place the CLI reads usmconfig.json validates it against the published usmconfig-v1.json schema; unknown outputs.* keys (and other schema violations) are hard errors, never silent defaults (issue #43). | — | Unknown keys under outputs produce a hard error naming the key and the supported set (workspace, docs, help_docs, archimate, togaf, openapi, tests, usm_source, agents_md); Unknown keys at other config levels error with the same shape (key named, schema section named); All three readers (usm init, usm scan, usm generate) go through one validated loader — no reader bypasses validation; A config that previously relied on silently-ignored keys now fails loudly at first use instead of writing to the wrong output directory; Malformed JSON fails with the parse error, not silent defaults (the current silent catch is removed) |
| usm/config-validation | validate-config-flag | usm validate gains a --config flag so consumers can gate config correctness in CI without side effects. | — | usm validate --config usmconfig.json reports valid/invalid with structured error paths, exit 0/1; Same validation as the load-time check (single source of truth for the rule set); No --config argument and no default usmconfig.json present → validate behaves exactly as today (back-compat) |
| usm/config-validation | errors-are-actionable | The load-time failure must tell the user exactly how to fix it, not just what broke. | — | Unknown-key error lists the valid keys for the section; Error shows the offending config file path; A suggested replacement is included for known renamed keys where one exists (e.g. api_docs → openapi) |
| usm/config-validation | docs-break-namespace-confusion | Docs prevent the two documented failure modes behind issue #43: inventing config keys from spec-schema field names, and hunting for a YAML config format that does not exist. | — | config-reference states usmconfig.json is the only configuration format; no usm.yaml exists or is planned; config-reference states https://usm.dev/schema/v1.json is the schema for .usm spec files, a different artifact — do not derive config keys from it; A note where the two schemas share names (e.g. agent_context is a system.usm field, not a config key) |
| usm/config-validation | backward-compatible | Projects without a usmconfig.json, or with fully valid configs, behave byte-identically to 0.9.0. | — | No usmconfig.json → defaults used exactly as today (no new warnings); Valid config → identical output paths and identical generated artifacts; The usmconfig-v1.json schema file itself gains no breaking changes |
| usm/docs-ia-restructure | sidebar-single-level-nesting | The sidebar renders within VitePress's single-level nesting limit: top-level groups with item lists only. Nested group structures are flattened at generation time with boundaries preserved as prefixed labels, never lost. | — | No group ever nests a group inside its items array — generation flattens Features sub-areas into sibling top-level collapsible groups (CLI, Generators, MCP Tools, Schema & Docs); Every rendered group title is intentional (never falls back to first-item text); Rendered sidebar verified structurally in a browser fixture: group titles match the intended IA |
| usm/docs-ia-restructure | labels-unique-and-human | Every sidebar label is unique, human, and free of mechanical artifacts. | — | No duplicated area prefixes ('CLI CLI Color Output') — disk-discovered features reuse system.index display names when available, else title-case slug without area prefix; Area overview links are labelled '<Area> overview', not bare 'Overview' (no repeated labels across groups); Feature naming is consistent: the same feature renders the same label whether discovered from system.index or disk scan |
| usm/docs-ia-restructure | sections-ordered-and-named | Sidebar sections have a stable, audience-appropriate order and naming. | — | Dev order: Getting Started, Guides, Features, Project Management (Roadmap, Decision Register), Reference, Architecture, Source Map, Exports; Help order: Getting Started, Guides, Reference (user-facing pages only), Roadmap, Help (Language Support, Report Issue); Reference is its own top-level group (CLI Reference, MCP Tools, Configuration, Schema Reference) — not mixed into a group titled by its first item; Design section renders as 'Architecture' with its section labels intact |
| usm/docs-ia-restructure | help-audience-purity | Help docs contain user-journey content only: feature build specs (flows/contracts/test internals) and the Decision Register are developer-docs content. | — | Help tree excludes features/ area pages (all areas, including cli) and design/decision-register; Help keeps Roadmap, reference pages, guides, getting-started, agent-setup-guide, editor setup, language support, feedback; Roadmap links that point at excluded feature pages degrade to plain text in the help tree (same guard pattern as package docs); Help sidebar never shows a group containing contract/flow/test internals; Agent Setup Guide appears in the help sidebar Getting Started group — the page renders in both audiences (universal package content) and must never be nav-orphaned in either |
| usm/docs-ia-restructure | roadmap-current | The roadmap stays current: every shipped feature appears, and stale statuses are corrected at the spec level — the roadmap page renders from system.usm, so fixing the source fixes the docs. | — | Features marked built in system.index have roadmap entries with shipped_in set (rules-files, docs-split, help-reference, config-outputs, mcp-write, this session's 0.9.x work); No roadmap item claims 'planned' for something already shipped; statuses match feature status; The 2026-09-27/28 consumer-blocker fixes appear as shipped items once released |
| usm/docs-serve-port-check | port-check-clear-error | When an EXPLICITLY requested --port is in use, the user gets a clear, actionable error message — explicit requests are strict. | — | Error message includes the port number; Error message includes the process name/PID using the port (when detectable via lsof); Error message suggests --auto-port (omit --port) or --restart as remedies; Exit code is non-zero |
| usm/docs-serve-port-check | auto-port-selection | When no --port is given, the next available port is selected automatically — concurrent instances never clash. | — | Default port base is 5173; if taken, probe incrementing until free (max 100 probes); Logs the selected port clearly (e.g. 'Port 5173 in use, using port 5174 instead'); Works for both --audience developer and --audience help; The announced URL is always the bound URL (USM probes and passes --strictPort to VitePress; bind failure fails loudly, never silently drifts) |
| usm/docs-serve-port-check | already-serving-detection | Running serve when a server is already up is handled gracefully. | — | PID file written to .usm-workspace/.vitepress.pid on start; On serve, detects existing server and prints its URL + PID; Does not start a second server unless --restart is passed; --restart kills the old server before starting a new one; PID file cleaned up on shutdown (SIGINT, SIGTERM, normal exit) |
| usm/docs-serve-port-check | watch-mode-regeneration | --watch keeps docs in sync with .usm changes automatically. | — | Watches .usm/ directory recursively for .usm file changes; Debounces regeneration (500ms after last change); Runs usm generate --only docs in-process (not a subprocess); Logs regeneration summary (file count); VitePress HMR picks up changed markdown files |
| usm/docs-serve-port-check | qol-commands | usm docs status, usm docs stop, --open, and graceful shutdown all work. | — | usm docs status prints server URL + PID or 'Not running'; usm docs stop kills the server and removes PID file; --open flag opens browser at the served URL; SIGINT/SIGTERM kills VitePress child and removes PID file; usm docs build is unaffected by all changes |
| usm/docs-serve-port-check | no-breakage | Existing behavior is unchanged when the port is free and no server is running. | — | When port is free, behavior is identical to current (no extra output); usm docs serve --port 5173 works exactly as before when 5173 is free; usm docs build is unaffected; No new required dependencies (net, fs, child_process are all built-in) |
| usm/cli-docs | serve-starts-on-configurable-port | usm docs serve selects its port by audience need: auto-port by default (concurrent instances never clash), explicit --port strict. | — | Omitting --port auto-selects the next free port starting at 5173 and logs which port was chosen; Explicit --port N is strict: fails loudly with a clear, actionable error if N is taken; Bind-race in auto-port mode retries with a fresh probe (3 attempts) instead of failing; Announced URL always equals the bound URL (VitePress --strictPort); Server accessible at http://localhost:<port>; Clear console output with URL for review |
| usm/cli-docs | sidebar-matches-system-index | VitePress sidebar must enumerate every feature page in every area uniformly | — | Every index entry appears in the sidebar; Every feature page under docs/features/<area>/ appears, whether or not the area has an index.md (issue #36); Sidebar groups match .usm/features/ subdirectory names; Feature status (planned, active, deprecated) shown as badge; Services listed in sidebar from system.usm services[] |
| usm/cli-docs | hot-reload-on-usm-change | Editing a .usm file must trigger regeneration and browser update — of the FULL docs surface, not just developer markdown. Nav (config.mts) and the help-docs stream are part of the served contract. | — | File watcher monitors .usm/ directory recursively; Regeneration covers BOTH streams: developer docs AND help-docs tree; VitePress config.mts (sidebar/nav) refreshed on regeneration — write-on-change (idempotent), so the running server reloads nav exactly when it changed; Concurrent server startups self-organize: bind-race in auto-port mode retries with a fresh probe (3 attempts) instead of failing; generate --only help-docs preserves .vitepress/ across the tree rebuild (config.mts must not be deleted mid-serve); Sidebar renders zero dead links (every link resolves to a file on disk) and zero repeated links (dedup guard); VitePress HMR updates browser within 1 second; Console shows which file changed and was regenerated |
| usm/cli-docs | build-produces-static-output | usm docs build must produce a deployable static site | — | Static HTML output in docs/.vitepress/dist/; All assets (CSS, JS, images) bundled; No server runtime required to serve output; Output works on Cloudflare Pages, GitHub Pages, Netlify, or any static host |
| usm/cli-docs | unified-structure-is-flat-and-navigable | All docs in a single docs/ directory with predictable paths | — | One markdown file per .usm feature; Path pattern: docs/features/<area>/<feature>.md; Services at docs/services/<service>.md; No docs scattered across apps/ or .agents-workspace/ |
| usm/cli-docs | vitepress-missing-graceful-error | If VitePress is not installed, show helpful error not a crash | — | Error message explains VitePress is optional dependency; Install command shown (pnpm add -D vitepress); Exit code 1 with clear message, not a stack trace |
| usm/cli-docs | serve-identifies-project-and-url-shape | docs serve must make the served project and the docs URL shape unambiguous | — | Startup output prints the serving project name (system.usm identity, else package.json, else dir); Startup output prints the route shape /features/<area>/<slug> with the $system namespace dropped; MCP write tools return docs_url/docs_path so agents return correct links (issue #34) |
| usm/cli-docs | help-tree-layout-is-sibling-safe | The help-docs tree is a filtered derivative of the developer docs tree; the two output roots must be siblings (or at least the help root must not sit inside the docs root), because the filter walks the source tree and must never copy its own destination. | — | filterForHelpAudience rejects a helpRoot that is inside docsRoot (or equal to it) with a hard error naming both paths and the config keys to change (issue #47); The guard runs before any filesystem mutation — a bad layout fails fast without creating or deleting anything; No self-copy recursion is possible: copyFiltered never walks the help destination; Default sibling layout (.usm-workspace/docs + .usm-workspace/help-docs) unaffected; Configured nested layouts (e.g. docs: docs/ + help_docs: docs/help/) fail with an actionable error instead of ENAMETOOLONG |
| usm/cli-docs | help-output-path-honest | Every help-docs emission point reports the path files were actually written to — never a hardcoded default (issue #44). | — | generate --only help-docs success message names the resolved helpRoot (path.relative(root, helpRoot)), not the hardcoded .usm-workspace/help-docs/; Custom help_docs paths (e.g. docs/help/) are reflected in console output; docs serve/build --audience help likewise reports the configured path |
| usm/cli-docs | help-tree-derivation-gating-documented | The help-docs tree is derived from already-generated developer docs; plain usm generate does not emit it. This gating is documented where consumers configure it. | — | --only help-docs help text states it filters the developer docs tree and requires a prior usm generate; config-reference documents which commands emit the help tree (generate --only help-docs, docs serve/build --audience help) and that plain generate does not (issue #44) |
| usm/cli-docs | help-build-derives-if-missing | usm docs build --audience help auto-runs the filter pass when the help tree is absent, instead of erroring. | — | docs build --audience help with no existing help tree runs the filter pass first and then builds; docs build --audience help with an existing tree still rebuilds it (no stale-tree builds) |
| usm/cli-docs | vitepress-on-demand-fetch | Docs commands work on first run without any VitePress install: missing local + missing global → on-demand fetch via npx -y vitepress@1, transparently, mutating nothing; --no-fetch-vitepress restores the hard error for hermetic/CI environments. | — | Resolution order: project-local → global install → on-demand fetch (npx -y vitepress@1) → hard error only with --no-fetch-vitepress; Fetch mode prints one line stating what happened and how to make it permanent (npm i -D vitepress) — never silently; On-demand fetch pins vitepress@1 (no unpinned floating major); First-ever usm docs serve in a greenfield repo with no package.json works and mutates nothing (no package.json/node_modules side effects); Offline + no install + --no-fetch-vitepress → clear error naming the install command (today's behaviour preserved); spawn sites use the fetch-mode resolution (npx -y vitepress@1) consistently in both serve and build; Config-reference and getting-started document the fetch behaviour and the pinning option |
| usm/cli-enrich | enrich-preserves-human-edits | Enrich must never overwrite fields that already have non-TODO content | — | Fields with TODO: describe are filled; Fields with existing content are preserved; preserve_human_edits defaults to true |
| usm/cli-generate | generate-from-source-only | Generate must read .usm files directly — never derive docs from other docs | — | All outputs derived from parsed .usm data; Duplicate $ids detected and warned; --check mode compares without writing; Missing outputs outside git's tracked set are reported as (skipped: untracked) and do not fail --check — CI on a fresh clone can pass; missing tracked outputs still fail (issue #42); The skip summary states the count and remedy (run usm generate) so absence is never silent |
| usm/cli-init | init-creates-config | usm init must create a valid usmconfig.json at the specified output path | — | Config has version: '1'; Config has name, services, shared, data, sources, outputs fields; Config does not overwrite unless --force is passed |
| usm/internal-dsl-builder | builder-emits-valid-usm | Every build() result passes schema validation or reports errors explicitly | — | build() runs validateUsm and includes errors in the result; writeFeature refuses to write when valid is false; Generated YAML matches MCP write-tool serialization conventions |
| usm/internal-dsl-builder | required-fields-enforced | The builder surface mirrors the schema's required fields | — | summary and intent required before a valid build; $system and $service required at construction; flows get steps; contracts get must_have; tests get expect |
| usm/internal-dsl-builder | exported-public-api | The DSL ships as part of the package's public entry | — | import { defineFeature, defineService, writeFeature } from '@smithgray/usm' works; Types exported for IDE autocomplete |
| usm/internal-dsl-builder | roundtrip-fidelity | Builder output parses back to the same object | — | yaml → parseUsm → deep-equals object |
| usm/mcp-setup-guides | mcp-setup-index | Index page at /mcp-setup with a grid of all 35 editor cards | — | Grid layout of 35 editor cards grouped by category; Each card links to a per-editor setup page; Cards show editor name and one-line setup summary |
| usm/mcp-setup-guides | per-editor-pages | One dedicated setup page per editor (35 total) with exact config | — | H1 with editor name; Exact MCP config snippet (JSON/TOML/YAML/CLI command depending on editor); Restart-required flag where applicable; Rules/skills file installation for editors that support always-on hooks; Link back to the index page |
| usm/mcp-setup-guides | rules-files-coverage | Editors with always-on hook support document the rules file install | — | opencode: .opencode/skills/usm-workflow/SKILL.md + .opencode/usm-instructions.md; Claude Code: CLAUDE.md + .claude/skills/usm-workflow/SKILL.md; Cursor: .cursor/rules/usm.mdc + .cursor/rules/usm-always.mdc; Copilot: .github/copilot-instructions.md + .github/instructions/usm-iron-rules.md; Codex: AGENTS.md; Other editors: note if always-on hooks are not supported |
| usm/mcp-setup-guides | tool-logos-top-10 | Marketing site ToolLogos updated with top 10 editors | — | Top 10: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, opencode, Codex, Zed, Continue; SVG paths from Simple Icons where available, fallback Terminal icon otherwise |
| usm/mcp-setup-guides | help-audience | Setup pages are in the help docs (public audience), not developer docs | — | Pages sit under .usm-workspace/docs/mcp-setup/; Accessible at docs.usm.dev/mcp-setup; Sidebar entry under Getting Started |
| usm/cli-multi-lang-scan | manifest-detection-coverage | Scanner detects services from all supported language manifests | — | package.json → Node.js/TypeScript/JavaScript; pyproject.toml or requirements.txt → Python; Cargo.toml → Rust; go.mod → Go; pom.xml or build.gradle → Java/Kotlin; .csproj or .sln → C#/.NET; Gemfile → Ruby; composer.json → PHP; mix.exs → Elixir; Package.swift → Swift; build.sbt → Scala; CMakeLists.txt or Makefile → C/C++; Framework detected from dependencies in manifest |
| usm/cli-multi-lang-scan | route-detection-coverage | Scanner detects routes from 30+ frameworks across all languages | — | Next.js: app/page.tsx, app/route.ts (existing); Express: app.get/post/put/delete in .js/.ts files; FastAPI: @app.get/post decorators in .py files; Flask: @app.route decorators in .py files; Django: path() patterns in urls.py; Go chi/gin/echo: r.GET/POST and router.HandleFunc patterns; Go net/http: http.HandleFunc patterns; Rust Axum: .route() calls; Rust Actix: #[get/post] macros; Rust Rocket: #[get/post] attributes; Spring Boot: @GetMapping/@PostMapping/@RequestMapping annotations; Javalin: app.get/post calls; Quarkus: @GET/@POST + @Path annotations; ASP.NET Core: [HttpGet]/[HttpPost] attributes; ASP.NET Minimal: app.MapGet/MapPost; Rails: get/post/resources in config/routes.rb; Sinatra: get '/path' do in .rb files; Laravel: Route::get/post in routes/web.php; Symfony: #[Route] attributes; Slim: $app->get/post in .php files; Phoenix: get/post in router.ex; Vapor: routes.get/post in .swift files; Akka HTTP: path/endpoints in .scala files; Play: GET /path in conf/routes; Tapir: endpoint.get/post in .scala files; Crow: CROW_ROUTE macro in .cpp files; Drogon: registerHandler in .cpp files; Pistache: router.get/post in .cpp files |
| usm/cli-multi-lang-scan | data-model-detection-coverage | Scanner detects data models from ORMs across languages | — | Prisma: schema.prisma (existing, TypeScript); SQLAlchemy: class definitions in models.py (Python); Django ORM: class definitions in models.py (Python); GORM: struct definitions with gorm tags (Go); Diesel: table! macros in schema.rs (Rust); Hibernate: @Entity annotations in .java (Java); Entity Framework: DbSet properties in DbContext (C#); ActiveRecord: class definitions inheriting ApplicationRecord (Ruby); Eloquent: class definitions extending Model (PHP); Ecto: schema definitions in .ex files (Elixir) |
| usm/cli-multi-lang-scan | config-extensible | Detection rules are configurable in usmconfig.json | — | detection.manifests array with {pattern, language, frameworks?} objects; detection.routes array with {framework, pattern, method_group, path_group} objects; detection.data_models array with {orm, pattern, model_pattern?} objects; Defaults cover all supported frameworks; users can add custom patterns |
| usm/cli-multi-lang-scan | backward-compatible | Existing Node.js/TypeScript scanning unchanged | — | usm scan on a Node.js project produces same results as before; usmconfig.json without detection section uses defaults |
| usm/cli-multi-lang-scan | detector-file-format | Detector files in .usm/detectors/*.yaml are validated against a detector-v1.json schema before use | — | Each detector declares $id, kind (service|framework|routes|data-schema|infrastructure), manifest glob, language, runtime; Framework detectors declare frameworks[] with name + string-contains detect rule; Route detectors declare routes.extensions + routes.patterns[] (regex, methodGroup, pathGroup) OR routes.script (mutually exclusive); Invalid detector files are skipped with a warning, not an abort |
| usm/cli-multi-lang-scan | dual-extension-surfaces | Users can extend detection through either usmconfig.json or .usm/detectors/ files, with the same expressiveness | — | usmconfig.json detection.manifests / detection.routes / detection.data_models / detection.infrastructure arrays (existing accepted decision, unchanged); .usm/detectors/*.yaml files as a second, auto-discovered source; Both surfaces accept the same field shapes (manifest, frameworks, routes patterns, data model patterns); Detector files support routes.script for convention-based frameworks; usmconfig.json detection.routes supports script too |
| usm/cli-multi-lang-scan | orchestrator-generalized | Service detection is driven by detector manifests, removing the package.json hardcode in structural.ts | — | A service directory is detected if ANY detector manifest glob matches a file in it (not only package.json); A Go app with go.mod and no package.json produces a service.usm (no 'No package.json found' warning); A Zig app with build.zig.zon and no package.json produces a service.usm; The existing Python pyproject.toml and Docker docker-compose passes become built-in detectors, not special-case code |
| usm/cli-multi-lang-scan | infrastructure-extensible | Infrastructure detection is extensible beyond Terraform via detectors | — | Built-in Terraform detector preserves usm scan infrastructure output exactly; detection.infrastructure array in usmconfig.json (new, mirrors detection.manifests shape); Infrastructure detector files accepted in .usm/detectors/; CloudFormation, Pulumi, CDK detectable via user-supplied detectors without code change |
| usm/cli-multi-lang-scan | precedence-and-override | Detector sources merge with a deterministic precedence so users can override built-ins | — | Built-in detectors are the lowest precedence (seeded from current MANIFESTS/ROUTE_PATTERNS/Prisma/Terraform tables); .usm/detectors/ files override built-ins by detector $id; usmconfig.json detection section is highest precedence (overrides both built-ins and detector files); A usmconfig.json with no detection section and no .usm/detectors/ dir produces identical results to the current scanner (backward compatible) |
| usm/cli-multi-lang-scan | backward-compatible-existing-implementations | Existing USM projects with usmconfig.json and .usm files continue to scan identically | — | usm scan on a Node.js/Next.js project with no detection section and no detectors dir produces the same .usm output as before this feature; Existing PRESERVE_FIELDS / UPDATE_FIELDS smart-merge behaviour unchanged; Existing CLI flags (--force, --routes, --merge) unchanged in name and default; The existing manifest-detection-coverage and route-detection-coverage contracts from the original spec remain satisfied by the migrated built-in detectors |
| usm/pkg-universal-docs | package-ships-universal-docs | The npm package ships a universal docs-source/ directory with the onboarding pages every consumer repo needs; file list includes it so it lands in the tarball. | — | package files[] includes docs-source/; shipped set covers agent-setup-guide.md, getting-started.md, and editor-setup/ (index + per-editor guides); shipped pages contain no repo-specific content (no Smith & Gray ids, no internal links) |
| usm/pkg-universal-docs | consumer-override | Precedence is total: consumer repo docs-source/ wins wholesale; generated reference_pages beat package content on filename collision; package content is fallback only. | — | consumer repo with docs-source/ gets byte-identical output to today (no package content copied); consumer repo without docs-source/ gets the package set copied into the docs output tree; package file never overwrites a generated page with the same output name; merge is skipped in --check mode (no writes) |
| usm/pkg-universal-docs | nav-lights-up-automatically | Existing dead-link guards light up automatically once package content is present — no guard changes required for consumers to see onboarding nav. | — | homepage renders the Getting Started link when the package page was copied (hasPage guard); sidebar shows Editor Setup and Agent Setup Guide entries when the pages exist (docExists guard); consumer trees without the package content keep today's guarded behavior (no regression) |
| usm/pkg-universal-docs | link-discipline-in-consumer-tree | All shipped pages pass the full-link discipline in the CONSUMER output tree: every link resolves, sidebar and content, both docs audiences. | — | no relative or .md-suffixed hrefs in shipped page content; {"crawl of a consumer fixture tree":"0 dead links, 0 duplicate links, both audiences"}; cross-page links limited to pages guaranteed by the copy step (editor-setup/, agent-setup-guide, getting-started) or guarded at generation time |
| usm/pkg-universal-docs | idempotent-universal-docs | Package docs merge is deterministic and repeatable: same inputs produce byte-identical output trees. | — | second usm generate run produces byte-identical docs output; removed package files do not leave orphans in a clean tree; existing consumer-repo behavior unchanged for every other generator pass |
| usm/query-layer | selector-and-predicates | The grammar covers type selection, field comparison, existence, contains, and boolean composition | — | Selector maps to $type filtering (features→feature etc, all→any); = != on strings; > < >= <= on numeric fields (array lengths, version); ~ substring contains case-insensitive; has field for existence/non-empty; and or not with parentheses, standard precedence (not > and > or) |
| usm/query-layer | friendly-errors | Parse failures produce actionable messages, never raw stack traces | — | Message names the token and position and what was expected; Unknown fields resolve to missing (has is false, comparisons false) rather than erroring |
| usm/query-layer | read-only-and-capped | Query never writes; MCP results are capped for context safety | — | No file writes on any query path; MCP default limit 50 with total + truncated in the response |
| usm/query-layer | one-evaluator-two-surfaces | CLI and MCP share a single parser/evaluator module | — | src/query module is the only implementation; MCP response includes path so agents can usm_read hits directly |
| usm/cli-scaffold-project | scaffold-project-creates-structure | Scaffold-project must create all directories and files without overwriting existing ones | — | Creates .usm/ directory tree; Skips existing files (reports ⊘); Produces valid YAML for each file |
| usm/cli-scaffold | scaffold-valid-template | Scaffold must produce a file that validates against v1.json | — | All required fields present; File not overwritten if it already exists |
| usm/cli-scan | scan-preserves-edits | Smart-merge preserves human-edited fields (summary, intent, decisions, flows, contracts, tests) on re-scan | — | PRESERVE_FIELDS are kept if non-default; UPDATE_FIELDS ($last_updated, paths, port, depends_on) are overwritten; --force bypasses merge |
| usm/upgrade | version-compared | Upgrade reads the installed package.json version and system.usm.version and reports stale or up-to-date. | — | Installed version resolved from the USM package.json (not the project's); Absent system.usm.version treated as 0.0.0 (stale); Stale vs up-to-date clearly reported; --check message for a never-aligned project is actionable: names 'usm upgrade --apply' as the opt-in act (issue #46) |
| usm/upgrade | capabilities-detected | Every registry capability is checked; missing and recommended ones are reported with a setup hint. | — | All registry entries run through detect(); Missing recommended capabilities surfaced prominently; Each missing capability shows its setup hint |
| usm/upgrade | setup-non-destructive | Setup never overwrites an existing block. | — | detect() returns true → capability skipped entirely; No existing config field is overwritten |
| usm/upgrade | version-bumped-on-completion | After a successful apply, system.usm.usm_version is set to the installed version — including the already-aligned case (issue #46). | — | usm_version field written only after setup succeeds; Resulting system.usm validates against the schema; --apply with nothing left to set up (capabilities already configured) still stamps usm_version when stale — recording alignment, not silently doing nothing; Requested targets that fail to apply exit non-zero in every path (explicit-targets and recommended-missing alike); The already-aligned stamp is reported ('aligned at <version>') so the change is visible, not silent |
| usm/upgrade | non-interactive-safe | Non-interactive modes work without prompts and are CI-safe. | — | --apply runs all recommended missing capabilities with defaults, no prompts; --check reports only and exits non-zero if stale; Non-TTY defaults to report-only (no hanging on stdin) |
| usm/cli-validate | validate-against-v1-schema | Validate must use the v1.json schema with Ajv and report all errors | — | Uses Ajv with allErrors: true; Reports path and message for each error; Exit code 1 if any file fails |
| usm/vitepress-home-feedback-schema | homepage-reference-first | Homepage is a clean technical reference, not a marketing duplicate. | — | Short intro paragraph (2-3 sentences); Quick Stats table (feature count, service count, package count); Quick Start commands (copy-pasteable); Prominent link cards to Schema Reference, Getting Started, Roadmap; Spec-first workflow Mermaid diagram; No principle cards, benefit sections, or "Sound familiar?" content; Single link to usm.dev for marketing content; Sidebar fully visible (no collapsed groups by default) |
| usm/vitepress-home-feedback-schema | feedback-dual-mode | Feedback button works for both humans and agents. | — | Visible "Report Issue" link in nav bar and/or sidebar; Dedicated feedback page with two clear paths; Human path: pre-filled GitHub issue URL with template (title, body, page context); Agent path: MCP tool instructions (usm_report_feedback with page + .usm context); VitePress editLink points to .usm source on GitHub |
| usm/vitepress-home-feedback-schema | all-content-generated | All new content is generated from .usm files — no hand-authored output pages. | — | Homepage content derived from system.usm; Feedback page generated by markdown generator; Cross-links derived from system.usm index and feature refs; Smart-merge preserved; re-running generate is idempotent |
| usm/vitepress-home-feedback-schema | no-breakage | Existing pages, generators, and the docs build remain healthy. | — | usm validate passes with 0 errors; usm generate produces all existing pages plus new ones; usm docs serve / usm docs build succeed; Existing feature/service/reference pages unchanged in substance |
| usm/vitepress-schema-polish | fully-generated-from-usm | All new homepage/schema/getting-started content is generated from .usm files and schema/v1.json — no hand-authored output pages that can drift. | — | Homepage hero/cards/example derived from system.usm + schema, not hardcoded literals; Schema reference fully derived from schema/v1.json; Smart-merge preserved; re-running generate is idempotent |
| usm/vitepress-schema-polish | schema-reference-comprehensive | The schema reference answers 'what does this field do?' for every major type. | — | Covers system, service, feature, feedback file types plus shared sub-schemas (flow step, contract, test, decision, usage, options); Each field shows description/intent, type, required/optional, constraints, YAML example, generator/MCP/validation impact, best-practice; Scannable tables + collapsible detail blocks; cross-links to examples |
| usm/vitepress-schema-polish | no-breakage | Existing pages, generators, and the docs build remain healthy. | — | usm validate passes with 0 errors; usm generate produces all existing pages plus the new ones (no dead links, none removed); usm docs serve / usm docs build succeed; Existing feature/service/reference pages unchanged in substance |
| usm/vitepress-schema-polish | dark-mode-and-mobile | The site looks correct in both themes and on mobile. | — | Mermaid diagrams switch theme with VitePress light/dark; Layout, tables, code blocks responsive on narrow viewports; Typography/contrast consistent across themes |
| usm/vitepress-schema-polish | smart-merge-preserved | Generator changes never clobber hand-edits. | — | Pages still written between USM markers; content outside markers untouched; Re-generating over an existing tree does not discard human edits |
| usm/vitepress-schema-polish | lightweight | The site stays fast with no heavy runtime dependencies. | — | Mermaid loaded via CDN only; no new heavy client bundles; VitePress local search retained; build time does not regress materially |
| usm/gen-agentsmd | agents-md-preserve | AGENTS.md generator must never destroy hand-written content and must be idempotent | — | Content between USM:START and USM:END replaced with generated content; Content outside markers preserved exactly; If no markers exist, insert after first H1 heading; Repeated runs are byte-identical — no trailing-newline accumulation (issue #32) |
| usm/gen-agentsmd | agents-md-reference-pointer | AGENTS.md includes a compact USM reference block so agents in consumer repos know where authoritative USM documentation lives — without injecting dogfood content into the repo's own docs. | — | USM section lists: docs.usm.dev (tool reference), usm.dev (user docs), schema URL, and the upstream tracker; Instructs agents to prefer MCP tools (usm_list/usm_read/usm_search) for spec context, USM site for tool reference; Zero repo-specific dogfood content in the block — same links for every consumer; Idempotent and marker-preserved like the rest of the generated section |
| usm/gen-archimate | archimate-valid-xml | Generated XML must conform to the ArchiMate 3.1 Open Exchange format | — | Valid XML with proper namespace declarations; Elements organized by ArchiMate layer folders |
| usm/gen-content-blocks | content-block-schema | The schema defines a content block type with variants for every VitePress feature needed for rich docs. | — | Block types: heading, paragraph, code, mermaid, tabs, callout, table, steps, cards, badge, divider; code block supports language, title (VitePress code-group), and line highlighting; mermaid block outputs a fenced code block with language mermaid (rendered by VitePress mermaid plugin); tabs block contains tab entries with label + content blocks (nested); {"callout block supports types":"info, tip, warning, danger (VitePress containers)"}; table block has headers array and rows array of arrays; steps block has ordered items with optional inline code; cards block has items with title, description, optional icon/link (VitePress features grid); badge block supports type info/tip/warning/danger and text |
| usm/gen-content-blocks | reference-pages-on-system | system.usm can declare reference pages with inline content or runtime sources. | — | reference_pages array field on system.usm schema (optional); Each entry has id, title, audience (public or internal, default internal), optional content array (content blocks), optional source (detectors, schema, or config); source detectors renders from the detector registry at generation time; source schema renders from v1.json (delegates to existing generateSchemaReference logic); source config renders from usmconfig-v1.json (delegates to existing generateConfigReference logic); Pages with audience public appear in help docs; internal only in developer docs |
| usm/gen-content-blocks | reference-blocks-on-features | Feature specs can carry user-facing reference content that survives the help filter. | — | reference array field on feature schema (optional); Each reference entry has heading, audience (public or internal), content array (content blocks); Reference blocks rendered after standard feature doc sections (summary, intent, flows); Help filter keeps reference blocks with audience public; drops audience internal; Feature docs without reference array are unchanged (backward compatible) |
| usm/gen-content-blocks | generic-renderer | One rendering function converts content blocks to VitePress markdown — no per-page bespoke functions for content. | — | renderContentBlocks function is the single entry point; Every block type has a renderer; unknown block types produce a warning and are skipped; Nested blocks (tabs contain blocks, cards may contain blocks) render recursively; |
| usm/gen-content-blocks | delete-hardcoded-content | Hardcoded content functions and constants are removed and their content migrated to specs. | — | LANGUAGE_SUPPORT constant deleted from markdown.ts; generateLanguageSupportDoc replaced by reference_pages source detectors rendering; generateAgentSetupGuide replaced by reference_pages agent-setup inline content; Hardcoded prose in generateGettingStartedDoc migrated to reference_pages getting-started; Data Model Detection hardcoded table migrated to a reference block on usm/cli-multi-lang-scan; generateConfigReference and generateSchemaReference preserved (they read JSON schema files, which ARE the source of truth) |
| usm/gen-content-blocks | backward-compatible-existing-specs | Existing .usm files without content blocks or reference_pages generate identical docs. | — | Feature specs without reference array produce the same doc output as before; system.usm without reference_pages does not produce the deleted hardcoded pages (they are opt-in); All existing tests pass without modification; Spec-driven generators (generateCliReference, generateMcpReference, generateMarkdown, generateOpenApiSpec, generateTestSpecs, generateArchiMateModel, generateMermaid architecture/ER/deps) are unchanged |
| usm/gen-content-blocks | audience-filter-block-level | The help-doc filter operates at content-block granularity, not section granularity. | — | simplifyFeatureDoc updated to filter content blocks by audience field; Blocks with audience public or no audience field survive the help filter; Blocks with audience internal are dropped from help docs; Contracts, tests, implementation, decisions continue to be stripped (developer-only) |
| usm/gen-content-blocks | universal-not-usm-specific | The content-block system works for any USM project, not just USM's own docs. | — | Any project system.usm can declare reference_pages with inline content or detector/schema/config sources; Any project feature specs can carry reference blocks; The generic renderer has no USM-specific content baked in; A project with no reference_pages and no reference blocks generates the same docs as before this feature |
| usm/docs-experience | no-empty-stubs | No empty placeholder pages are emitted | — | A templated section page is emitted only when the source service carries data for it; Sidebar entries match emitted pages one-to-one (no dead links); A CLI never gets ui, production-deployment, or observability pages |
| usm/docs-experience | togaf-in-nav | The real TOGAF deliverables are reachable from the technical docs nav | — | dev-docs sidebar has an Architecture group linking the Phase A-H deliverables; help audience omits the Architecture section; No parallel orphaned togaf directory |
| usm/docs-experience | content-width | Reference content uses the viewport, not VitePress's 688px default | — | --vp-layout-max-width overridden to ~1280 or wider; Code blocks and tables render full-width; Applies to every consumer site on their next generate |
| usm/docs-experience | homepage-is-navigation | The homepage is a navigation surface, not a metrics dump | — | No At-a-glance, Identity, or Who-its-for body markdown on index.md; A features grid of cards links into the primary doc sections; Hero actions retained |
| usm/docs-experience | audience-voice-distinct | Help and technical audiences read differently for the same feature | — | Help feature page leads with when-to-run and example output; Technical feature page is spec-faithful (full flows, contracts, tests); Same source .usm, two render paths |
| usm/docs-experience | no-handwritten-drift | No hand-written drift in generated docs | — | getting-started install version derived from package.json; VitePress sitemap enabled on both audiences |
| usm/gen-docs-split | help-docs-only-built-features | Help docs only include features with status built (or visibility public) | — | Features with status planned or in-progress are excluded from help docs; Features with visibility: public are included regardless of status; Features with visibility: internal are excluded from help docs |
| usm/gen-docs-split | help-docs-simplified-content | Help docs feature pages show summary + intent + flows only | — | No contracts section in help docs; No tests section in help docs; No implementation section in help docs; No decisions section in help docs (or simplified to decision + rationale only) |
| usm/gen-docs-split | help-docs-no-sensitive-info | Help docs exclude deployment details and operations runbooks | — | No deployment.md in help docs; No operations section; No build commands or secrets in help docs |
| usm/gen-docs-split | developer-docs-unchanged | Developer docs remain exactly as before (full detail) | — | All features included (planned, in-progress, built); Full contracts, tests, decisions, implementation; Deployment and operations pages |
| usm/gen-docs-split | help-docs-user-journey-only | Help docs contain the user journey only — internal tooling pages (code-navigator, orphan-files, spec-coverage) and the design/ architecture section are contributor material and live exclusively in developer docs. | — | code-navigator.md, orphan-files.md, spec-coverage.md absent from help docs; design/ section absent from help docs (sidebar group too); getting-started, agent-setup-guide, CLI/MCP/schema/config references, roadmap, language-support, feedback present in help docs; composed user-docs guides present in help docs sidebar; developer docs keep all of the above (full detail, unchanged) |
| usm/gen-feature-review | review-doc-has-approval-framing | The review.md must frame the spec for human approval | — | Starts with a one-line intent summary in plain language; Flows section reads as a procedure, not a data table; Contracts section is a checklist, not a table; Tests section uses given/when/then format; Ends with an implementation plan section (primary file, status) |
| usm/gen-feature-review | review-doc-is-separate-from-overview | review.md is a new file, overview.md is unchanged | — | overview.md continues to be generated with current format; review.md is generated alongside overview.md; Both files share the same output directory |
| usm/gen-feature-review | decisions-included-when-present | When a feature has decisions[], they appear in the review doc | — | Each decision shows the decision text and rationale; Decisions frame as 'Why this approach' section |
| usm/feedback-upstream-routing | scope-branch-explicit | Every generated feedback protocol explicitly branches on bug scope before stating where it goes | — | A 'Where does the bug live?' distinction rendered in every rules file; Project scope: existing policy behaviour unchanged; USM-tool scope: upstream URL named literally with the gh -R command |
| usm/feedback-upstream-routing | upstream-default-and-override | The upstream tracker has a default and a system.feedback override | — | Default upstream: https://github.com/Smith-Gray-Pty-Ltd/usm/issues; Optional feedback.upstream_tracker field in system.usm overrides it; Schema update is optional-field-only (no breaking change) |
| usm/feedback-upstream-routing | no-misfiling | The protocol must forbid filing USM tool bugs against the consuming project | — | Explicit 'never file USM tool bugs in this repo's tracker' rule; usm_report_feedback human-gate draft mentions upstream routing for tool bugs |
| usm/feedback-upstream-routing | one-source-many-surfaces | Scope routing text is generated from a single code path into all surfaces | — | rulesFiles.ts generateFeedbackProtocol is the single source; Docs feedback page and MCP tool text stay consistent with it |
| usm/gen-help-reference | cli-reference-has-all-commands | CLI reference page includes all CLI commands with usage | — | Every feature in features/cli/ with usage field appears in the reference; Each command shows usage examples and options table |
| usm/gen-help-reference | config-reference-from-schema | Config reference is generated from usmconfig-v1.json | — | Every field in usmconfig-v1.json appears in the reference; Each field shows type, description, and default |
| usm/gen-help-reference | schema-reference-covers-all-types | Schema reference covers system, service, feature, and data types | — | Each .usm type has a field table; Required vs optional clearly marked |
| usm/gen-help-reference | mcp-reference-has-all-tools | MCP reference lists all 12 tools | — | All read tools (8) and write tools (4) appear in the table; Each tool shows summary and when to use |
| usm/gen-markdown | markdown-gfm | Markdown output must be valid GitHub-flavored markdown | — | H1 heading matches the .usm $id or name; Tables for flows, contracts, tests; No broken links |
| usm/gen-markdown | markdown-single-writer-per-path | Each output path must have exactly one generating pass, and output must be a pure function of the .usm inputs | — | No generator derives output by reading the file it is about to overwrite; generateDataModelDoc owns .usm-workspace/docs/data/models.md (ER section composed in); Area overviews write to the root .usm-workspace/docs/features/ — never apps/<svc>/.usm-workspace/; usm generate --check converges immediately after a clean usm generate |
| usm/gen-mermaid | mermaid-valid-syntax | Generated Mermaid files must parse without syntax errors | — | Special characters escaped (colons, pipes, brackets); Each diagram in its own .mmd file |
| usm/gen-mermaid | er-section-is-pure | The ER diagram section must be a pure function of the Prisma schema, never of prior on-disk output | — | buildERDiagramSection(root) reads only packages/db/prisma/schema.prisma; generateDataModelDoc is the sole writer of .usm-workspace/docs/data/models.md; No generator reads a file it is about to overwrite |
| usm/mkt-language-tabs | carousel-shows-all-languages | All 12 language logos visible at once in the carousel | — | 12 language logos in a horizontal row; Logos at 50% opacity, selected at 100%; Default: TypeScript selected; Clicking a logo updates frameworks + code example below |
| usm/mkt-language-tabs | framework-display | Frameworks shown as chips with logo where available | — | Frameworks with Simple Icons logo: logo + name; Frameworks without logo: name only as text chip; All frameworks for the selected language visible |
| usm/mkt-language-tabs | code-example-per-language | Route detection code example shown for each language | — | TypeScript: app.get('/users', handler); Python: @app.get('/users'); Go: r.GET('/users', handler); Rust: .route('/users', get(handler)); Java: @GetMapping('/users'); C#: [HttpGet('users')]; Ruby: get '/users' do; PHP: Route::get('/users', ...); Elixir: get('/users', UserController, :index); Swift: routes.get('users') { req in }; Scala: path('users') { get { handler } }; C++: CROW_ROUTE(app, '/users') |
| usm/mkt-language-tabs | docs-grid-comprehensive | Help docs page lists all languages and frameworks | — | Table with columns: Language, Manifest, Frameworks, Route Pattern; All 12 languages present; All 30+ frameworks listed |
| usm/mkt-language-tabs | responsive-carousel | Carousel works on mobile | — | Logo row scrolls horizontally on mobile; Selected logo clearly highlighted; Code example wraps on small screens |
| usm/mkt-mock-interfaces-v2 | browser-vitepress-look | Browser mock looks like the real VitePress docs site | — | Left sidebar with grouped nav sections (Getting Started, Features, etc.); Top bar with USM logo, search placeholder, Report Issue link; Content area renders real doc structure: H1, Usage code block, How it works numbered steps, Guarantees checkbox criteria |
| usm/mkt-mock-interfaces-v2 | ide-file-explorer | IDE mock has a file explorer sidebar showing .usm files being created | — | Left file explorer panel with tree of project files; .usm files appear with green + badge as the agent writes them; Explorer syncs with the agent's file-write actions |
| usm/mkt-mock-interfaces | two-mock-interfaces | Two side-by-side animated mock interfaces below the Works with your client section | — | Left mock = agentic IDE/chat with agent prompts and responses referencing USM; Right mock = browser window showing specs/docs loading for the corresponding command; Both mock interfaces animate (typing, streaming responses, page loads); Layout is responsive (stacks on mobile, side-by-side on desktop) |
| usm/mkt-mock-interfaces | usm-references-in-chat | Agent chat references USM tools and specs | — | Agent mentions usm_read, usm_write_feature, or similar MCP tools; Agent references a feature spec before coding; Spec-first workflow is visible in the dialogue |
| usm/mkt-mock-interfaces | browser-specs-loading | Right mock browser shows specs/docs loading in response to the agent action | — | Browser URL bar updates to a docs/spec URL; Page content loads progressively (skeleton then content); Loaded content matches the spec the agent just wrote or read |
| usm/mkt-mock-interfaces | synced-timing | The two mocks are loosely synced so the chat action appears to trigger the browser load | — | Chat completes an action then browser loads the corresponding spec; Cycle repeats with a different command/spec pair |
| usm/gen-openapi | openapi-valid-spec | Generated OpenAPI spec must validate against the OpenAPI 3.1 schema | — | All routes present as paths with correct HTTP methods; Security schemes for auth-required routes; TypeScript types generated for request/response schemas |
| usm/opencode-integration | skill-description-is-the-nudge | The skill's frontmatter description must carry the workflow trigger by itself, since it is the only part visible before invocation | — | Description front-loads trigger keywords and filenames (.usm, feature, spec); Description states when to invoke: before starting feature work, when unsure a change needs a spec, when the session has drifted; Body contains the full checklist including read-before-code, draft-before-build, show-human-review, update-status-after |
| usm/opencode-integration | instructions-injected-every-request | The iron-rules file must be registered in opencode.json instructions so opencode appends it to every system prompt | — | opencode.json instructions array contains .opencode/usm-instructions.md; The file is short (≤ ~30 lines) — iron rules only, no system description; Content is the same workflow taught by all other rules files |
| usm/opencode-integration | user-config-preserved | The generator must never damage user-authored opencode config | — | Existing instructions entries preserved in order; No other top-level field added, removed, or modified; $schema field preserved; valid JSON output; works when opencode.json does not yet exist (creates minimal file) and when it exists at root or .opencode/ |
| usm/opencode-integration | drift-countermeasure | The per-message reinforcement must explicitly address mid-session drift, not just initial onboarding | — | Iron rules phrased as per-message self-checks (e.g. 'Before ANY code change: does a .usm spec exist for this?'); Skill description mentions re-anchoring a drifted session |
| usm/gen-roadmap | roadmap-only-generated-when-non-empty | Roadmap page is only generated when system.usm has roadmap items | — | Empty roadmap array → no roadmap.md generated; Non-empty roadmap → roadmap.md with table |
| usm/gen-roadmap | sidebar-no-dead-links | Sidebar must not contain links to non-existent files | — | 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 |
| usm/gen-roadmap | sidebar-case-matches-files | Sidebar links must match actual file name case | — | agentsMd link matches agentsMd.md file; testSpecs link matches testSpecs.md file |
| usm/gen-roadmap | mermaid-renders-in-vitepress | Mermaid code blocks render as diagrams, not raw text | — | Architecture page shows rendered diagram; Other mermaid blocks render properly |
| usm/gen-rules-files | all-tools-covered | All tools covered with always-on iron rules where a per-message mechanism exists | — | Cursor usm.mdc plus usm-always.mdc; Claude CLAUDE.md plus skills SKILL.md; Codex AGENTS.md detail only; Copilot instructions plus usm-iron-rules.md; opencode SKILL.md plus wired instructions |
| usm/gen-rules-files | two-tier-enforcement-parity | Iron rules from one shared function; SKILL.md identical for opencode and Claude Code | — | Shared iron-rules body in all tiers; Identical SKILL.md across runtimes |
| usm/gen-source-mapping | bidirectional-mapping | The generator builds a bidirectional file-to-feature-to-service-to-module mapping from existing spec data. | — | Reads service.usm modules name, purpose, and paths for directory-level grouping; Reads feature.usm implementation.primary and implementation.test_code for file-level ownership; Reads feature.usm routes file_path for route source files; Walks the filesystem within each service paths directory to enumerate actual files; Matches each file to a module by directory, a feature by implementation.primary, and a route by file_path |
| usm/gen-source-mapping | multiple-views-one-mapping | Multiple views render from one SourceMap data structure, each as a reference_pages source. | — | file-tree source renders a directory tree with descriptions, grouped by service and module; coverage-matrix source renders a table of file, module, owning feature, spec status; orphan-report source renders only files with no governing feature spec; All views render through the generic content-block renderer as reference pages |
| usm/gen-source-mapping | universal-not-usm-specific | The source mapping generator works for any USM project, reading the project's own specs. | — | No USM-specific content baked into the generator; Reads the project's service and feature specs, not hardcoded file lists; A project with no reference_pages source-mapping entries produces no output (backward compatible); File descriptions come from module purpose and feature summary, not from the generator |
| usm/gen-source-mapping | backward-compatible | Existing projects without source-mapping reference_pages entries are unaffected. | — | No reference_pages entries with file-tree/coverage-matrix/orphan-report sources means no output; All existing tests pass without modification; No new schema fields required — uses existing modules, implementation.primary, routes file_path |
| usm/gen-source-mapping | orphan-detection | Files in the codebase not claimed by any feature spec are identified as orphans. | — | A file in a service paths directory with no matching implementation.primary is an orphan; Orphan files are excluded from exclude patterns (node_modules, dist, .git, etc.); The orphan-report view lists orphans grouped by service and module |
| usm/structurizr-bridge | import-never-destroys | Import guards existing work | — | Existing system.usm or service files are never overwritten without --force; --dry-run lists planned writes without writing; Invalid or non-workspace JSON fails with a clear message |
| usm/structurizr-bridge | export-valid-dsl | Exported workspace.dsl is well-formed Structurizr DSL | — | workspace, model and views structure with balanced braces; Quotes in names and descriptions escaped; System name from identity.name, containers from services, components from features with $service set |
| usm/structurizr-bridge | target-registered | Export participates in the standard generate target system | — | structurizr accepted by --only; Output written under .usm-workspace/structurizr/ |
| usm/structurizr-bridge | conservative-mapping | Mapping choices are documented and reversible | — | Container becomes service with type api by default, or database, cache, queue when technology suggests it; Unmappable detail preserved in summary text, never dropped silently |
| usm/gen-technical-design | adapt-to-project-type | The generator must adapt to any project type — a CLI tool with no database, a library with no deployment, a monorepo with multiple services. Sections with no data are suppressed entirely, not rendered as empty stubs. | — | Each of the 13 pages is only rendered if its data source exists; The sidebar only includes links to rendered pages; A CLI-only project produces no Database Design, API Design, or Deployment Architecture pages; No page contains an empty section with no content |
| usm/gen-technical-design | one-source-many-views | The technical design document is a view of the same .usm data as TOGAF, feature docs, and source mapping. It must not duplicate or hardcode content — it renders from specs. | — | All content is derived from .usm files, schema, or declared content blocks; No USM-specific content hardcoded in the generator; No content duplicated from TOGAF or feature docs — both read from the same specs independently |
| usm/gen-technical-design | content-block-enrichment | system.usm can declare inline content blocks for any Design section via a new design_pages[] field (parallel to reference_pages[]). These enrich the structured data with prose that doesn't fit schema fields. | — | design_pages[] entries have id, title, audience, and either content[] (content blocks) or source (structured data); Inline content blocks render AFTER structured data on the same page; Sections without design_pages entries still render from structured data alone |
| usm/gen-technical-design | prose-escaping | All prose from specs must be escaped via escapeProse before rendering to prevent VitePress Vue template compilation errors from unescaped angle brackets. | — | All spec-authored prose passed through escapeProse; All table cell content passed through escapeTableCell or escCell; Mermaid diagram blocks are exempt (they use their own escaping) |
| usm/gen-technical-design | sidebar-data-driven | The sidebar structure is generated from data availability, not hardcoded. Groups and pages appear only when their underlying data exists. | — | Design group only includes pages that were rendered; Project Management group only appears if roadmap, features, or decisions exist; Developers group only includes reference pages that have data; Exports group only appears if TOGAF or ArchiMate outputs exist |
| usm/gen-technical-design | decision-register | The Decision Register consolidates all decisions from features, services, and system principles into one page — the single source of truth for what was decided and why. | — | All feature decisions[] included with source feature $id; All service decisions[] included with source service $id; System principles[] rendered as architecture decisions; Each decision shows ID, decision, status, rationale, alternatives, consequences |
| usm/gen-technical-design | nav-template-structure | The generated sidebar follows a fixed five-group template structure that applies to any | ||
| project. The template defines which groups exist, which pages go in each group, and which | ||||
| content sections each Design page contains. Groups and pages are suppressed when their data | ||||
| source doesn't exist, but the structure itself is the standard template. | — | Getting Started group: Home, Getting Started; Design group: 13 section pages (Project Overview, Requirements, System Architecture, Module Design, Database Design, API Design, Security Design, Deployment Architecture, Testing Strategy, Maintenance & Monitoring, Backup & Recovery, Risks & Mitigation, Future Enhancements) — only rendered pages appear; Project Management group: Roadmap, Features (grouped by service/area), Decision Register; Developers group: Source Map, Test Coverage, Spec Coverage, API Reference, CLI Reference, Configuration (only pages with data appear); Exports group: TOGAF Phases, ArchiMate Model (collapsed); Each Design page has a defined set of content sections (3rd-level outline) that the generator renders — these are the page's TOC, not separate sidebar links | ||
| usm/gen-testspecs | test-specs-runnable | Generated test specs must be syntactically valid Vitest files | — | Each flow maps to a describe block; Each test maps to an it block with setup and expect; Aggregated specs import per-feature files |
| usm/gen-testspecs | vitest-specs-from-flows-tests | Test specs are a pure, collision-free function of the .usm inputs | — | One output spec file per feature $id; Source path resolution is exact $id parsing, not substring matching (issue #37 class); Two features must never target the same output path; Generated specs are valid Vitest files |
| usm/gen-togaf | togaf-phase-coverage | Generator must produce deliverables for phases A, B, C1, C2, D, E, G, H | — | Each phase in its own markdown file; Phase A includes principles and stakeholders; Phase C1 includes data model from data .usm files |
| usm/gen-user-docs | personas-first-class | system.usm gains personas[] — id, name, description. Flows and steps gain optional actor (persona id, or 'system'/'agent') and optional surface (e.g. ui, cli, api). | — | personas[] validates: unique ids, non-empty name; actor values either reference a declared persona id or are system/agent; validate fails on unknown persona references (typo protection); existing specs without personas/actor validate unchanged |
| usm/gen-user-docs | journeys-vs-pipelines | A flow is a journey when its actor (flow-level or step-level) references a persona; otherwise it is a pipeline and behaves exactly as today. | — | flows with default (no) actor default to system and stay in the developer stream; journeys render in user docs; pipelines never do; step-level actor overrides flow-level default |
| usm/gen-user-docs | user-docs-composed | New user-doc generator composes guides from personas and journeys — never by filtering developer content. | — | one guide page per journey: task-oriented title from flow name, ordered steps; steps with actor=system/agent rendered as 'the system …' prose, persona steps as instructions; per-persona navigation grouping (Guides for <persona>); generation is idempotent and deterministic |
| usm/gen-user-docs | e2e-from-journeys | tests[] gains optional flow reference; journey tests emit Playwright e2e skeletons alongside existing Vitest output. | — | tests with flow referencing a journey emit a valid Playwright .spec.ts under tests/auto-generated/e2e/; output path derives from exact feature $id — collision-free (issue #37 class); tests without flow ref continue to generate Vitest specs unchanged |
| usm/gen-user-docs | help-composition-replaces-subtraction | Feature pages in help docs are composed from summary, intent, and public journey guides; the subtraction filter is deprecated but stays functional for system-level pages. | — | help feature pages contain no contracts/tests/implementation sections; help feature pages embed the journey guides relevant to public personas; existing --audience help still runs and produces a valid site (non-feature pages unchanged); no user-visible regression for projects with no personas defined |
| usm/gen-user-docs | backward-compatible | Projects that never declare personas get byte-identical generated output to the previous version. | — | all existing generators unchanged when no personas/journey actors present; schema changes are additive and optional-only; existing .usm files validate with no edits required |
| usm/agent-feedback | policy-respected | All generated instructions and the MCP tool must honour the configured system.feedback.policy | — | human-gate mode instructs the agent to ask the human and forbids autonomous writes; direct-to-feedback mode instructs the agent to call usm_report_feedback; direct-to-github mode is only offered/emitted when feedback.github_auth is true |
| usm/agent-feedback | no-adhoc-tracking-files | The protocol must explicitly forbid agents from inventing their own bug/issue tracking files | — | Hard rule present in every rules file: NEVER create ad-hoc tracking files at repo root; Canonical feedback location named: .usm/feedback (overridable via feedback_dir) |
| usm/agent-feedback | feedback-schema-validated | Feedback entries are first-class .usm files validated against the schema | — | $type: feedback recognised by the v1 schema; Required fields: kind (bug|improvement|question), severity, summary, status, reported_by; usm_validate accepts a feedback file |
| usm/agent-feedback | init-persists-policy | usm init writes a valid feedback block and never leaves policy ambiguous | — | Both prompts answered or defaulted (human-gate) if skipped; Resulting system.usm passes schema validation |
| usm/agent-feedback | smart-merge-preserved | Generator additions respect existing smart-merge guarantees | — | Feedback block rendered between USM markers only; Hand-written content outside markers unchanged |
| usm/mcp-contracts | contracts-feature-only | Contracts tool only works on feature files | — | Returns error if file is not a feature; Returns contractCount and full contracts array; Each contract includes id, description, must_have |
| usm/mcp-flows | flows-feature-only | Flows tool only works on feature files | — | Returns error if file is not a feature; Each flow includes id, name, description, stepCount, steps |
| usm/mcp-list | list-returns-metadata | List must return path, id, type, version, and summary for each file | — | Count of files returned; Optional $type filter applied; Results sorted by path |
| usm/mcp-query | shared-evaluator | Query grammar shared with the CLI | — | Selector maps to $type filtering; Absent fields make predicates false, never errors; Friendly parse errors naming token and position |
| usm/mcp-query | read-only-capped | Read-only with context-safe capping | — | No file writes on any query path; Default limit 50 with total and truncated in the response |
| usm/mcp-read | read-returns-full-data | Read must return both the full parsed object and metadata | — | Metadata includes id, type, version, summary; System files include featureCount, serviceCount; Feature files include flowCount, contractCount, testCount |
| usm/mcp-references | references-deep-walk | References must walk the entire object tree, not just top-level fields | — | Finds references in $system, $service, depends_on, see_also, and nested objects; Returns context field showing where the reference was found; Results sorted by path |
| usm/mcp-search | search-top-10 | Search returns the top 10 most relevant results | — | Case-insensitive by default; Score based on occurrence count; Excerpt from summary around first match |
| usm/mcp-summary | summary-lightweight | Summary must return only metadata — not the full file content | — | Includes id, type, version, last_updated, summary; System files include featureCount, serviceCount; Feature files include flowCount, contractCount, testCount; Service files include runtime, port, depends_on |
| usm/mcp-validate | validate-inline-or-path | Validate must accept either a file path or inline YAML content | — | Returns { valid, errors } structure; Errors include path and message; File-not-found returns valid: false |
| usm/mcp-write | draft-validates-before-returning | draft_feature must validate the spec before returning it | — | Returns validation_status: valid or invalid; If invalid, returns structured errors with field paths; YAML is only generated if validation passes |
| usm/mcp-write | write-is-atomic | write_feature must not leave partial/corrupt files on disk | — | Validates full file before writing; Writes to temp then renames (atomic on POSIX); Returns error if write fails — original file untouched |
| usm/mcp-write | update-preserves-unspecified-fields | update_feature merges provided fields without losing existing ones | — | Fields not in the update payload are preserved; Array fields are replaced, not merged (explicit intent); $id, $type, $schema are immutable — cannot be changed via update |
| usm/mcp-write | status-transitions-are-sane | update_feature_status enforces valid status transitions | — | planned → in-progress → built is valid; built → deprecated is valid; built → planned is rejected (use a new feature instead) |
| usm/mcp-write | write-returns-docs-url | Write and update tools return the canonical docs link so agents don't guess ports or URL shapes (issue #34) | — | write_feature, update_feature and update_feature_status include docs_path on success; docs_url is a full localhost URL when a docs server port is recorded; docs_hint explains how to get a live URL when none is running |
| usm/schema-v1 | schema-three-types | The schema must support every file type advertised by the UsmFileType union, with the discriminator enum and oneOf in agreement | — | oneOf selects systemFile, serviceFile, featureFile, dataFile, or feedbackFile; Every $type in commonFields.enum has a matching oneOf/$defs branch; Common fields: $schema, $id, $type, $version, summary; $id pattern: ^[a-z0-9][a-z0-9-]/[a-z0-9][a-z0-9-]$; Flow steps require id and action; Contracts require id and description; Tests require id and expect |
| usm/schema-v1 | schema-additional-properties-false | Each file type must set additionalProperties: false to prevent undocumented fields | — | systemFile.additionalProperties is false; serviceFile.additionalProperties is false; featureFile.additionalProperties is false; dataFile.additionalProperties is false |