roadmapsmith 0.9.29 → 0.9.31

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.29",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
+  "version": "0.9.31",
+  "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"
   },

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.29",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
+  "version": "0.9.31",
+  "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"
   },
@@ -35,7 +35,7 @@
   "interface": {
     "displayName": "RoadmapSmith",
     "shortDescription": "Evidence-backed roadmap workflows for AI coding agents",
-    "longDescription": "Install RoadmapSmith in Codex to expose the shared skills bundle for zero-mode onboarding, existing-repo maintenance, roadmap discovery, and evidence-backed validation while keeping the CLI and Claude bundle surfaces aligned.",
+    "longDescription": "Install RoadmapSmith in Codex to expose the shared skills bundle for zero-mode onboarding, existing-repo maintenance, roadmap discovery, evidence-backed validation, and compatibility-aware host readiness while keeping the CLI and Claude bundle surfaces aligned.",
     "developerName": "PapiScholz",
     "category": "Developer Tools",
     "capabilities": [

package/README.md

@@ -1,390 +1,164 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/PapiScholz/roadmapsmith/main/assets/roadmapsmith-logo.png" alt="RoadmapSmith logo" width="180">
-</p>
+# RoadmapSmith CLI Contract
 
-<h1 align="center">RoadmapSmith</h1>
+This package owns the RoadmapSmith CLI, validator, sync engine, host setup files, and the shared command-surface contract consumed by the root bundle docs, `skills.json`, and both plugin manifests.
 
-Production-grade roadmap generator and sync tool for agent-driven projects.
+## Public Contract
 
-## Install
+### Canonical
 
-### CLI
+- `roadmapsmith setup`
+- `roadmapsmith zero`
+- `roadmapsmith maintain`
+- `roadmapsmith status [--json]`
+- `roadmapsmith validate [--json] [--strict]`
+- `roadmapsmith update [--task <stable-id> --evidence "<single-line evidence>"]`
 
-```bash
-npm install -g roadmapsmith
-roadmapsmith setup
-roadmapsmith zero
-roadmapsmith maintain
-```
-
-Slash entrypoints are also supported from the CLI and launcher, for example: `roadmapsmith /roadmap`, `roadmapsmith /roadmap-zero`, `roadmapsmith /roadmap-maintain`, `roadmapsmith /roadmap-update`, and the deprecated legacy router form `roadmapsmith /roadmap-sync validate`.
-The generated VS Code task layer now resolves Node automatically where possible; if it cannot, RoadmapSmith prints a readable runtime diagnostic instead of a dead task.
-`RoadmapSmith: Status` now treats "ready" as runnable task UX, not merely generated files.
-
-### Agent Skill
+### Advanced
 
-```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
+- `roadmapsmith init`
+- `roadmapsmith generate`
+- `roadmapsmith generate --full-regen`
+- `roadmapsmith sync`
+- `roadmapsmith sync --audit`
+- `roadmapsmith sync` as the advanced alias for `roadmapsmith update`
 
-This is the recommended Claude Code install path for native GUI slash commands such as `/roadmap`, `/roadmap-zero`, `/roadmap-maintain`, `/roadmap-status`, `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`.
-`roadmap-sync` is deprecated compatibility only; install the full bundle for new workflows and use `/roadmap-maintain` or `/roadmap-update`.
-The skill bundle does not install the CLI and it does not create visible VS Code actions by itself.
-The published `roadmapsmith` package/plugin surface now also ships the shared bundle files for both hosts (`skills.json`, `skills/*`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`) for downstream host installers, but consuming the CLI alone still does not auto-register native Codex or Claude GUI commands.
+### Compatibility only
 
-## Updating
+- `roadmapsmith doctor`
+- `roadmapsmith regenerate`
+- `roadmapsmith /road <action>`
+- `roadmapsmith /roadmap-sync <action>`
+- deprecated direct aliases such as `/maintain` or `/status`
 
-Update the CLI based on how it was installed:
+`status` is the public readiness command. `doctor` remains a compatibility alias to the same payload.
 
-```bash
-# Global npm install
-npm install -g roadmapsmith@latest
+`update` is the public checklist-refresh and verified single-task completion family. `sync` remains executable as the advanced alias for the refresh path.
 
-# Project dependency
-npm install roadmapsmith@latest
-
-# One-off execution without installing
-npx roadmapsmith@latest validate --json
-```
+`generate --full-regen` is the only public destructive rebuild path. `regenerate` remains executable but prints a deprecation warning.
 
-The Claude skill bundle is separate from the CLI. Re-running the skills install updates the Claude-facing instructions, but it does not update the `roadmapsmith` npm binary or the generated VS Code host files:
-
-```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
-
-After updating the Claude skill bundle, run `/reload-skills` and, if applicable, `/reload-plugins`.
-After updating the CLI, rerun `roadmapsmith setup` in repositories where you want the latest VS Code tasks, task wrappers, launcher behavior, or Claude hook template. Published npm/plugin artifacts now include the Codex and Claude bundle files for downstream host loaders, but native UX still depends on the host loading the correct surface.
-
-Fixes are available through `@latest` after the automated release path completes on `main`. In this repo, a successful push to `main` now opens or refreshes an automated `release/vX.Y.Z` PR, that PR squashes back into `main` as the bot release commit `chore(release): vX.Y.Z`, and the follow-up `main` run publishes the new patch version. Before that completes, install from a local checkout or a packed tarball for testing.
-
-## Operating Modes
+## Modes
 
 ### Zero Mode
 
-Agent-guided discovery for empty or low-context repositories. The developer has a product idea but no implementation files, no stack decision, and no ROADMAP.md yet.
-
-Run `roadmapsmith setup` first if you want visible VS Code tasks. `roadmapsmith zero` is the one-command entrypoint: it runs the terminal interview, creates governance files when needed, and generates the first roadmap.
-
-```bash
-roadmapsmith setup
-roadmapsmith zero
-```
+Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview, updates config, and generates the first roadmap.
 
 ### Sync/Audit Mode
 
-Repository-backed roadmap generation, validation, and synchronization. Use when the repository already has code, tests, docs, TODOs, or an existing ROADMAP.md.
-
-```bash
-roadmapsmith setup
-roadmapsmith maintain
-```
-
-## Recommended Daily Flow
-
-Use the public entrypoints first:
-
-```bash
-roadmapsmith setup
-roadmapsmith zero       # empty repo
-roadmapsmith maintain   # existing repo
-```
+Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow.
 
-Use the lower-level commands only when you want manual control over generation, validation, or sync.
+## Verification Model
 
-## Deterministic completion
-
-For unchecked implementation tasks, related files and matching test names are candidate signals only. `maintain` completes a task only from explicit `Evidence:` or typed child verification metadata:
-
-```markdown
-- [ ] Enable ESLint builds
-  - Verify: kind=property; file=next.config.js; key=ignoreDuringBuilds; equals=false
-- [ ] Prevent double submit
-  - Verify: kind=behavior; source=src/login.tsx; test=src/__tests__/login.test.tsx; case=disables submit; trigger=fireEvent.click; assertion=toBeDisabled
-```
-
-`contains`, `property`, and `endpoints` are static checks. A behavioral check also requires a fresh `validation.testReports` entry using `format: "vitest-json"`; RoadmapSmith reads reports but never executes tests. Missing proof produces a `Verification recipe:` and a warning rather than a checked box. A fresh passing report is persisted as `Test evidence: file=<test>; case=<case>; status=PASS; verifiedAt=<ISO timestamp>` and becomes stale when it predates the referenced source or test file.
-
-## Host Support Today
-
-| Host | Current support |
-|---|---|
-| Claude Code | Supported through the full RoadmapSmith skill bundle for native GUI slash commands, plus `roadmapsmith setup` for visible VS Code tasks and the optional repo-local Claude hook. |
-| Codex / Codex CLI | Supported through the native Codex plugin surface (`.codex-plugin/plugin.json` + repo marketplace) and the visible VS Code task workflow after `roadmapsmith setup`. |
-| CI | Use disposable checkouts if you run `sync --audit`, because it still mutates the roadmap today. |
-| Other hosts | Use the skill plus manual CLI commands. |
-
-If Node is installed outside PATH, set `ROADMAPSMITH_NODE` to a working `node` executable before using the generated VS Code tasks. If the globally installed `roadmapsmith` shim itself cannot resolve Node, bypass it in PowerShell with:
-
-```powershell
-& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" <command>
-```
+RoadmapSmith separates candidate discovery from completion.
 
----
+Candidate discovery may use:
 
-## Commands
+- explicit path hints
+- symbol matches
+- code-token overlap
+- task-path overlap
+- test references
 
-```bash
-roadmapsmith /roadmap
-roadmapsmith /roadmap-zero
-roadmapsmith /roadmap-maintain
-roadmapsmith /roadmap-update
-roadmapsmith /roadmap-sync validate
-roadmapsmith setup [--project-root <path>] [--config <path>] [--editor vscode] [--hosts <codex,claude>] [--dry-run]
-roadmapsmith zero [--project-root <path>] [--config <path>]
-roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen]
-roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]
-roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]
-roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]
-roadmapsmith update --task <stable-id> --evidence <text> [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]
-roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]
-roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]
-roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]   # compatibility alias
-```
+Unchecked implementation tasks complete only from:
 
-## Claude Code native slash commands
+- valid explicit `Evidence:`
+- `Verify: kind=contains`
+- `Verify: kind=property`
+- `Verify: kind=endpoints`
+- `Verify: kind=behavior` plus fresh configured test-report proof
 
-Install the full skill bundle for Claude Code:
+Behavioral tasks without explicit proof remain warnings. When the engine can generate exactly one task-specific verification recipe, sync can render it as `Verification recipe:`. If the recipe is global, duplicated, off-domain, or otherwise non-specific, it is suppressed.
 
-```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
+Generated outputs such as `dist-electron/`, `dist/`, `build/`, `out/`, `.next/`, and `coverage/` are excluded from heuristic evidence discovery.
 
-Then reload the session:
+Auxiliary tooling paths such as `scripts/` and `tools/` are excluded from heuristic scoring unless the task explicitly references them.
 
-1. Run `/reload-skills`
-2. If RoadmapSmith was installed through a Claude plugin, also run `/reload-plugins`
-3. Confirm the slash menu shows `/roadmap`, `/roadmap-zero`, `/roadmap-maintain`, `/roadmap-status`, `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`
+## Strict Validation
 
-Native Claude GUI slash commands come from the installed skill bundle. CLI slash routing such as `roadmapsmith /roadmap` is a separate surface and does not populate the Claude GUI menu by itself. The packed npm artifact now mirrors that bundle on disk so published plugin/distribution flows can expose the same slash set without depending on a source checkout.
+`roadmapsmith validate --strict` is the independent audit path.
 
-## Codex native plugin install
+In strict mode:
 
-RoadmapSmith now exposes a native Codex plugin manifest at `.codex-plugin/plugin.json` and a repo-local marketplace at `.agents/plugins/marketplace.json`.
+- candidate discovery still narrows where to look
+- PASS may come only from explicit `Evidence:` or passing typed `Verify:`
+- file existence, domain overlap, token proximity, and test-file presence alone never produce PASS
+- preserved checked-state behavior is disabled
 
-From the repository root:
+Recommended audit sequence:
 
 ```bash
-codex plugin marketplace add .
+roadmapsmith maintain
+roadmapsmith validate --strict --json
 ```
 
-Then restart Codex, open the plugin directory, install `roadmapsmith` from the `RoadmapSmith Local Plugins` marketplace, and confirm the plugin resolves the shared `./skills/` bundle.
+`sync --audit` remains an advanced mutating summary, not an independent audit engine.
 
-Codex native plugin support means install/enable discovery inside Codex. It is separate from Claude-specific `/reload-skills` behavior, and the VS Code task layer remains the fallback/manual workflow when you are not using the plugin directory.
+## Slash And Host Surfaces
 
-`roadmapsmith status --json` now reports native slash surfaces separately from the VS Code task layer (`doctor --json` remains a compatibility alias):
+Canonical native slash surfaces:
 
-- `claudeGui`
-- `claudeCli`
-- `codexGui`
-- `codexCli`
+- `/roadmap`
+- `/roadmap-zero`
+- `/roadmap-maintain`
+- `/roadmap-status`
+- `/roadmap-validate`
+- `/roadmap-update`
+- `/roadmap-setup`
 
-Each surface includes the detected source, expected slash commands, missing commands, and duplicate registrations such as a second `/roadmap-sync` coming from a legacy user skill install.
+Advanced native slash surfaces:
 
-If Codex shows `Roadmap Sync` twice, the usual cause is a collision between:
+- `/roadmap-init`
+- `/roadmap-generate`
+- `/roadmap-audit`
 
-- `~/.agents/skills/roadmap-sync`
-- the installed `roadmapsmith` Codex plugin
+Compatibility-only slash surfaces:
 
-The repo does not remove user-global skills automatically. Use the `doctor` output to confirm the duplicate and then disable or remove the legacy skill if you want a single `/roadmap-sync` entry.
+- `/roadmap-sync <action>`
+- `/road <action>`
+- deprecated direct aliases
 
-## Behavior
+Native-bundle readiness is computed from canonical surfaces only. Missing advanced labels or duplicate legacy `/roadmap-sync` installs are warnings, not canonical-health failures.
 
-- Generates deterministic `ROADMAP.md` with fixed section order.
-- Uses stable task IDs: `<!-- rs:task=<slug> -->`.
-- Sync marks `[x]` only when validation passes.
-- `sync --audit` currently runs sync and then prints a mismatch summary; it is not yet a dedicated read-only audit mode.
-- For unchecked implementation tasks, heuristic code/test/path matches are candidates only. Completion requires explicit `Evidence:`, a trusted validator rule, or typed deterministic `Verify:` metadata.
-- `Verify:` supports `contains`, `property`, `endpoints`, and `behavior`; behavior additionally requires a fresh configured Vitest JSON report or a fresh `Test evidence:` annotation.
-- Validation failures in sync write warning lines:
-  - `- ⚠️ attempted but validation failed: <reason>` when there is concrete attempt evidence
-  - `- ⚠️ no implementation evidence found yet: <reason>` when there is not
-- Preserves unmanaged markdown content by updating only the managed roadmap block.
-- `validate` emits structured diagnostics in human and JSON output, including `FAIL:NOT_IMPLEMENTED`, `FAIL:NO_TEST`, `FAIL:MISSING_REFERENCE`, `FAIL:WRONG_VALUE`, `FAIL:PARTIAL`, `WARN:STALE_EVIDENCE`, `WARN:REQUIRES_HUMAN_EVIDENCE`, `WARN:NO_STATIC_SIGNAL`, `WARN:HAS_EXPLICIT_PENDING`, and `WARN:STALE_TEST_REPORT`.
-- `update --task <id> --evidence <text>` writes only when the evidence validates at high confidence; otherwise the roadmap is unchanged.
+## Host Setup
 
-## Defaults
+`roadmapsmith setup` generates:
 
-- Roadmap file: `./ROADMAP.md` (falls back to `./roadmap.md` when only the legacy file exists)
-- Agent rules file: `./AGENTS.md` (falls back to `./CLAUDE.md` when present)
-- Config file: `./roadmap-skill.config.json`
+- `.vscode/tasks.json`
+- `.vscode/roadmapsmith-launcher.js`
+- `.vscode/roadmapsmith-task.cmd`
+- `.vscode/roadmapsmith-task.sh`
+- optional Claude hook wiring
 
-Roadmap resolution precedence:
-
-1. `--roadmap-file` CLI flag
-2. `config.roadmapFile` in `roadmap-skill.config.json`
-3. Existing `./ROADMAP.md`
-4. Existing `./roadmap.md` (legacy fallback)
-5. `./ROADMAP.md` when neither file exists
+The internal hook filename remains `.claude/hooks/roadmap-sync.js`. It is a legacy internal filename, not a public command surface.
 
 ## Config
 
-Create `roadmap-skill.config.json`:
+Typical config file:
 
 ```json
 {
   "roadmapFile": "./ROADMAP.md",
   "agentsFile": "./AGENTS.md",
-  "roadmapProfile": "professional",
-  "product": {
-    "name": "My Project",
-    "northStar": "Ship a self-hosted CLI tool for website capture and AI-readable design analysis.",
-    "positioning": "What makes this different from alternatives.",
-    "primaryUser": "Frontend developers, full-stack developers, and AI coding agents.",
-    "targetOutcome": "A stable CLI that captures full-page screenshots, crawls internal links, exports metadata, and produces an AI-readable report.",
-    "antiGoals": [
-      "Do not bypass authentication",
-      "Do not target private systems without authorization"
-    ],
-    "risks": [
-      "Browser automation instability",
-      "Scope creep into generic scraping"
-    ],
-    "successCriteria": [
-      "CLI works against a public test site",
-      "Screenshots and metadata are exported deterministically",
-      "README documents safe and authorized usage"
-    ]
-  },
-
-  "taskMatchers": [
-    {
-      "pattern": "src/payments/",
-      "task": "Complete payment flow hardening",
-      "phase": "P0",
-      "priority": "P0"
-    }
-  ],
-  "validators": [
-    {
-      "type": "file-exists",
-      "when": "migration",
-      "path": "db/migrations"
-    },
-    {
-      "type": "grant-evidence",
-      "whenId": "^p0-electron-builder-windows$",
-      "evidence": ["test"],
-      "testFiles": ["test/electron-builder.test.js"]
-    }
-  ],
-  "customSections": [
-    {
-      "title": "Compliance",
-      "items": [
-        "- [ ] Complete SOC2 evidence packet <!-- rs:task=compliance-soc2-evidence -->"
-      ]
-    }
-  ],
-  "plugins": [
-    "./plugins/roadmap.plugin.js"
-  ],
-  "milestones": [
-    { "version": "v0.1", "goal": "Foundation" },
-    { "version": "v0.2", "goal": "Reliability" },
-    { "version": "v0.3", "goal": "Release candidate" },
-    { "version": "v1.0", "goal": "General availability" }
-  ],
-  "phaseTemplates": {
-    "P0": ["Stabilize critical path"],
-    "P1": ["Expand reliability"],
-    "P2": ["Finalize release hardening"]
-  }
-}
-```
-
-Task markers can include `rs:no-test` to disable the test-evidence requirement for one task:
-
-```markdown
-- [ ] Add Windows autostart script <!-- rs:task=p0-windows-autostart rs:no-test -->
-```
-
-Validator rules are backward compatible:
-
-- `when` matches task text.
-- `whenId` matches the stable `rs:task` ID.
-- `grant-evidence` can grant `code`, `test`, or `artifact` evidence without `overrideResult`.
-- `overrideResult: true` is only needed when a rule should replace automatic failures.
-- Tests that read a referenced file with `fs.readFileSync`, `fs.readFile`, `readFileSync`, or `readFile` can count as test evidence for tasks that explicitly mention that file.
-
-## Plugin API
-
-Plugin module path(s) are loaded from `config.plugins` in deterministic order.
-
-```js
-module.exports = {
-  registerTaskDetectors(ctx) {
-    return [
-      { text: 'Implement billing retries', phase: 'P1', priority: 'P1' }
-    ];
-  },
-  registerSectionGenerators(ctx) {
-    return [
-      {
-        title: 'Platform Notes',
-        items: ['- [ ] Verify deployment rollback path <!-- rs:task=verify-deployment-rollback-path -->']
-      }
-    ];
-  },
-  registerValidators(ctx) {
-    return [
+  "validation": {
+    "minimumConfidence": "low",
+    "recipeCommand": "npm test -- {testFile}",
+    "testReports": [
       {
-        type: 'symbol',
-        when: 'billing',
-        pattern: 'retry',
-        message: 'billing retry symbol not found'
+        "path": "test-results.json",
+        "format": "vitest-json"
       }
-    ];
+    ]
   }
-};
-```
-
-## Example Usage
-
-```bash
-roadmapsmith zero
-roadmapsmith maintain
-roadmapsmith validate --json
-roadmapsmith sync --dry-run
-```
-
-## Dry Run and Audit
-
-- `--dry-run`: shows file diff preview without writing.
-- `--audit`: currently runs sync and then reports roadmap/code mismatches:
-  - checked without evidence
-  - ready but unchecked
-
-## Development
-
-```bash
-npm test
-npm run validate:qa-regression
-npm run validate:functional-smoke
-```
-
-If `npm test` fails in your shell with "`node` is not recognized", treat that as a local PATH/runtime issue first and rerun the suite with an explicit Node executable.
-
-## Publishing
-
-```bash
-npm run validate:qa-regression
-npm run validate:functional-smoke
-npm test
+}
 ```
 
-Repository-specific release note:
+Key validation fields:
 
-- The canonical release automation lives in `.github/workflows/ci.yml`.
-- Every successful push to `main` now bumps `PATCH` through an automated `release/vX.Y.Z` PR, writes the version back with the squashed bot commit `chore(release): vX.Y.Z`, and then the follow-up `main` run publishes npm plus the GitHub Release.
-- Repair reruns on the bot release commit do not bump again; they only publish/create any missing artifacts left behind by a partial failure.
-- On repos where GitHub blocks `GITHUB_TOKEN` from creating or merging PRs, provide a dedicated secret such as `RELEASE_BOT_TOKEN` so the protected-branch release PR flow can complete.
-- Before any push, run the dual validation gate with separate owners: `QA/Regression` uses `npm run validate:qa-regression` and `Functional/Smoke` uses `npm run validate:functional-smoke`.
-- The release gate now includes packed-artifact verification for `skills.json`, `skills/*`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and the referenced Codex assets so the published surface matches the GitHub-source bundle for both hosts.
-- Before merging to `main`, verify the UX/release gate in `docs/release-ux-gate.md` and keep `CHANGELOG.md` ready for CI-managed version section generation.
+- `minimumConfidence`: output filter for validate/sync
+- `recipeCommand`: optional command suffix for generated verification recipes
+- `testReports`: configured behavioral proof sources
 
-## Versioning Strategy
+## Related Docs
 
-- `patch`: bug fixes and non-breaking validation/generation improvements.
-- `minor`: backward-compatible features (new flags, new plugin hooks, additive config fields).
-- `major`: breaking CLI/config behavior or marker/format changes.
+- [../docs/command-surfaces.md](../docs/command-surfaces.md)
+- [../docs/troubleshooting-host-setup.md](../docs/troubleshooting-host-setup.md)
+- [../docs/use-cases/sync-audit-mode.md](../docs/use-cases/sync-audit-mode.md)