Architecture Change Management (TOGAF Phase H)
Auto-generated from USM decisions, risks, and future items.
Architecture Decisions (80)
| ID | Decision | Status | Source |
|---|---|---|---|
| outputs-from-config | All generators read output paths from usmconfig.json outputs section | accepted | usm/cli-config-outputs |
| generate-only-flag | Replace generate:xxx commands with generate --only <target> flag | accepted | usm/cli-config-outputs |
| scaffold-project-to-subcommand | Rename scaffold-project to 'scaffold project' (subcommand) | accepted | usm/cli-config-outputs |
| no-dependency | Implement port probing with Node.js built-in net module — no third-party dependency like detect-port or chokidar. | accepted | usm/docs-serve-port-check |
| auto-port-opt-in | Auto-port selection is opt-in via --auto-port flag, not the default. | accepted | usm/docs-serve-port-check |
| lsof-best-effort | Process detection via lsof is best-effort only — graceful degradation if lsof is unavailable. | accepted | usm/docs-serve-port-check |
| pid-file-approach | Use a PID file (.usm-workspace/.vitepress.pid) for already-serving detection, not port-sniffing alone. | accepted | usm/docs-serve-port-check |
| watch-in-process | Watch-mode regeneration runs usm generate --only docs in-process (calling the generator functions directly), not as a subprocess. | accepted | usm/docs-serve-port-check |
| debounce-500ms | Watch-mode debounce is 500ms — a pragmatic balance between responsiveness and avoiding thrash on bulk writes. | accepted | usm/docs-serve-port-check |
| vitepress-over-custom | Use VitePress as the rendering layer instead of building a custom server | accepted | usm/cli-docs |
| unified-docs-directory | All generated docs write to a single docs/ directory instead of scattered .agents-workspace/ paths | accepted | usm/cli-docs |
| sidebar-from-system-index | Auto-generate VitePress sidebar config from system.usm index + feature directory structure | accepted | usm/cli-docs |
| vitepress-optional-dependency | VitePress is an optional peer dependency, not bundled with USM | accepted | usm/cli-docs |
| dont-commit-generated-docs | Generated docs are not committed to the repo — served locally and deployed via CI | accepted | usm/cli-docs |
| internal-over-external | Internal (host-language) DSL, not a custom grammar | — | usm/internal-dsl-builder |
| runtime-schema-validation | Enforce constraints by validating at build() rather than type-level branding | — | usm/internal-dsl-builder |
| manifest-based-detection | Detect services by language manifest files | accepted | usm/cli-multi-lang-scan |
| framework-specific-route-detection | Detect routes per-framework, not per-language | accepted | usm/cli-multi-lang-scan |
| configurable-in-usmconfig | Language/framework detection rules are configurable in usmconfig.json | accepted | usm/cli-multi-lang-scan |
| all-languages-from-start | Support all major languages from the initial implementation | accepted | usm/cli-multi-lang-scan |
| tiny-grammar-not-sql | A ~200-line recursive-descent grammar, not SQL/jq subset | — | usm/query-layer |
| missing-field-is-false | Unknown/absent fields make predicates false instead of erroring | — | usm/query-layer |
| capability-registry-pattern | Capabilities self-describe (detect + setup + introducedIn); upgrade orchestrates without hardcoding. | accepted | usm/upgrade |
| usm-version-field-for-alignment | Use system.usm.usm_version for USM-tool alignment, NOT the project's own version field. | accepted | usm/upgrade |
| schema-version-independence | Schema $version moves independently of the package version: additive schema changes do NOT bump $version (still v1); breaking changes bump $version + CURRENT_SCHEMA_VERSION together and ship a migration in usm upgrade. | accepted | usm/upgrade |
| setup-owned-by-capability | Each registry entry owns its own setup function (interactive + default); upgrade just calls it. | accepted | usm/upgrade |
| interactive-with-flag-fallback | TTY prompts per capability; --apply uses defaults for CI/scripts; --check is report-only. | accepted | usm/upgrade |
| non-destructive | Upgrade only adds missing blocks and bumps usm_version; existing config is never overwritten. | accepted | usm/upgrade |
| homepage-simplify-not-remove | Simplify the homepage by removing marketing content, not by removing the homepage entirely. Keep the spec-first diagram, quick stats, and quick start as the core reference content. | accepted | usm/vitepress-home-feedback-schema |
| feedback-as-generated-page | The feedback page is a generated markdown page (docs/feedback.md), not a custom Vue component. The nav bar link is added via VitePress themeConfig.nav. | accepted | usm/vitepress-home-feedback-schema |
| agent-feedback-via-existing-mcp | The agent feedback path reuses the existing usm_report_feedback MCP tool (from usm/agent-feedback feature). The feedback page documents how agents should use it with page context. | accepted | usm/vitepress-home-feedback-schema |
| cross-links-in-generator | Cross-links and next-steps sections are added in the markdown generator, not hand-edited into output. | accepted | usm/vitepress-home-feedback-schema |
| schema-as-single-source | The schema reference is generated entirely from schema/v1.json; terse field descriptions are enriched in-place in the schema so the reference is self-generating and never drifts. | accepted | usm/vitepress-schema-polish |
| homepage-from-system-usm | Homepage hero, tagline, principle cards, and CTAs are derived from system.usm (identity, summary, principles, repository) so every USM project gets a reflective homepage. | accepted | usm/vitepress-schema-polish |
| mermaid-dark-mode-aware | Inject a small theme-bridge script so Mermaid follows VitePress isDark instead of the hardcoded 'default' theme. | accepted | usm/vitepress-schema-polish |
| declarative-sidebar-groups | Sidebar group order/names are driven by a declarative group-to-paths mapping while still only emitting links to pages that exist. | accepted | usm/vitepress-schema-polish |
| native-vitepress-containers | Use VitePress native containers and Mermaid code fences for visuals — no custom Vue components or heavy deps. | accepted | usm/vitepress-schema-polish |
| priority-ordering | Deliver schema-reference and homepage/getting-started first; visuals/polish last. | accepted | usm/vitepress-schema-polish |
| emit-only-when-populated | Emit a templated page only when its source section is populated; never write a placeholder | — | usm/docs-experience |
| togaf-as-architecture-section | Surface togaf output as the Architecture section of the docs site, not a separate target | — | usm/docs-experience |
| css-not-config-for-width | Widen via generated theme CSS custom properties, not VitePress config knobs | — | usm/docs-experience |
| feature-cards-as-nav | Use the VitePress features grid as homepage navigation rather than forcing a sidebar onto layout home | — | usm/docs-experience |
| voice-is-render-mode | Audience is a render mode (voice), not just a filter | — | usm/docs-experience |
| post-process-filtering | Generate full docs first, then filter for help audience | accepted | usm/gen-docs-split |
| visibility-field-optional | Add optional visibility field (public/internal) to features and services | accepted | usm/gen-docs-split |
| help-docs-simplified-features | Help docs show summary + intent + flows only, not contracts/tests/implementation | accepted | usm/gen-docs-split |
| review-mode-separate-from-reference | Add a review-oriented template alongside the existing overview template | accepted | usm/gen-feature-review |
| flows-as-numbered-steps | Render flows as numbered human-readable steps, not tables | accepted | usm/gen-feature-review |
| contracts-as-checklist | Render contracts as a markdown checklist the human can mentally tick | accepted | usm/gen-feature-review |
| tests-as-given-when-then | Render tests in given/when/then format | accepted | usm/gen-feature-review |
| default-upstream-hardcoded | Default upstream tracker is the canonical USM repo, overridable via feedback.upstream_tracker | — | usm/feedback-upstream-routing |
| classification-instructions-not-detection | Teach scope classification via instructions rather than automatic detection in the MCP tool | — | usm/feedback-upstream-routing |
| usage-in-feature-spec | Add usage/options/prerequisites to FeatureUsm schema (optional fields) | accepted | usm/gen-help-reference |
| config-reference-from-schema | Generate usmconfig reference from usmconfig-v1.json schema descriptions | accepted | usm/gen-help-reference |
| schema-reference-from-v1-json | Generate schema reference from v1.json schema descriptions | accepted | usm/gen-help-reference |
| logo-carousel | Use a clickable logo carousel, not tabs | accepted | usm/mkt-language-tabs |
| simple-icons | Use Simple Icons (simpleicons.org) for language and framework logos | accepted | usm/mkt-language-tabs |
| full-grid-in-docs | Full language/framework reference grid goes in help docs, not marketing site | accepted | usm/mkt-language-tabs |
| instructions-plus-skill-not-plugin | Use opencode instructions array + skill, not a plugin with experimental.chat.system.transform | — | usm/opencode-integration |
| short-dedicated-file-not-agents-md | Generate a dedicated short instructions file rather than reusing AGENTS.md | — | usm/opencode-integration |
| skill-file-usm-owned | The skill and instructions files are fully USM-owned (wholesale regeneration); opencode.json is merge-touched only in instructions | — | usm/opencode-integration |
| roadmap-links-to-features | Roadmap items can optionally reference a feature $id via a feature field | accepted | usm/gen-roadmap |
| shipped-in-optional | Add optional shipped_in field to roadmap items for version tracking | accepted | usm/gen-roadmap |
| sidebar-checks-file-existence | Sidebar generation should only include links to files that exist | accepted | usm/gen-roadmap |
| mermaid-via-vitepress-plugin | Use VitePress mermaid plugin instead of relying on native mermaid rendering | accepted | usm/gen-roadmap |
| one-generator-multiple-outputs | Single generator produces all tool-specific files in one pass | accepted | usm/gen-rules-files |
| workflow-instructions-not-just-context | Rules files contain behavioural instructions, not just system description | accepted | usm/gen-rules-files |
| smart-merge-for-rules-files | Reuse the smart-merge strategy from AGENTS.md generator | accepted | usm/gen-rules-files |
| cursor-uses-mdc-format | Generate .cursor/rules/usm.mdc in Cursor's rule format | accepted | usm/gen-rules-files |
| json-import-first | Import the Structurizr workspace JSON format, not the DSL grammar | — | usm/structurizr-bridge |
| features-as-components | Export features as components inside their service container | — | usm/structurizr-bridge |
| default-human-gate | human-gate is the default policy | — | usm/agent-feedback |
| feedback-as-first-class-usm-type | Feedback entries are $type: feedback .usm files in .usm/feedback, not a free-form markdown log | — | usm/agent-feedback |
| one-shared-protocol-block | A single Feedback Protocol block is rendered into all four rules files from one code path | — | usm/agent-feedback |
| setup-asks-two-questions | usm init asks exactly two questions: gh auth presence and policy choice | — | usm/agent-feedback |
| mcp-tool-respects-policy | usm_report_feedback consults system.feedback.policy before writing | — | usm/agent-feedback |
| write-tools-as-mcp-not-cli | Implement authoring as MCP tools rather than CLI commands only | accepted | usm/mcp-write |
| draft-returns-preview | draft_feature returns both YAML and generated markdown | accepted | usm/mcp-write |
| validate-before-write | All write operations validate against the v1 schema before persisting | accepted | usm/mcp-write |
| json-over-yaml | Use JSON for usmconfig (not YAML) because it is machine-generated and machine-read | — | usm/usm-config |
Change Governance Principles
- Structured Source of Truth: Every system artifact is captured in YAML validated by a JSON Schema — no scattered, stale docs.
- Agent First: USM files are designed for AI agent consumption via MCP tools before human readability.
- Idempotent Generation: Scan and generate are safe to run repeatedly; smart-merge preserves human edits.
- One Source, Many Outputs: A single .usm/ directory generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.