roadmapsmith 0.9.28 → 0.9.30

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.28",
-  "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.30",
+  "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.28",
-  "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.30",
+  "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,378 +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
-
-```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
-
-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.
+### Advanced
 
-## Updating
+- `roadmapsmith init`
+- `roadmapsmith generate`
+- `roadmapsmith generate --full-regen`
+- `roadmapsmith sync`
+- `roadmapsmith sync --audit`
+- `roadmapsmith sync` as the advanced alias for `roadmapsmith update`
 
-Update the CLI based on how it was installed:
+### Compatibility only
 
-```bash
-# Global npm install
-npm install -g roadmapsmith@latest
-
-# Project dependency
-npm install roadmapsmith@latest
+- `roadmapsmith doctor`
+- `roadmapsmith regenerate`
+- `roadmapsmith /road <action>`
+- `roadmapsmith /roadmap-sync <action>`
+- deprecated direct aliases such as `/maintain` or `/status`
 
-# One-off execution without installing
-npx roadmapsmith@latest validate --json
-```
+`status` is the public readiness command. `doctor` remains a compatibility alias to the same payload.
 
-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:
+`update` is the public checklist-refresh and verified single-task completion family. `sync` remains executable as the advanced alias for the refresh path.
 
-```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
+`generate --full-regen` is the only public destructive rebuild path. `regenerate` remains executable but prints a deprecation warning.
 
-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.
+Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow.
 
-```bash
-roadmapsmith setup
-roadmapsmith maintain
-```
+## Verification Model
 
-## Recommended Daily Flow
+RoadmapSmith separates candidate discovery from completion.
 
-Use the public entrypoints first:
+Candidate discovery may use:
 
-```bash
-roadmapsmith setup
-roadmapsmith zero       # empty repo
-roadmapsmith maintain   # existing repo
-```
+- explicit path hints
+- symbol matches
+- code-token overlap
+- task-path overlap
+- test references
 
-Use the lower-level commands only when you want manual control over generation, validation, or sync.
+Unchecked implementation tasks complete only from:
 
-## Host Support Today
+- valid explicit `Evidence:`
+- `Verify: kind=contains`
+- `Verify: kind=property`
+- `Verify: kind=endpoints`
+- `Verify: kind=behavior` plus fresh configured test-report proof
 
-| 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. |
+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.
 
-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:
+Generated outputs such as `dist-electron/`, `dist/`, `build/`, `out/`, `.next/`, and `coverage/` are excluded from heuristic evidence discovery.
 
-```powershell
-& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" <command>
-```
+Auxiliary tooling paths such as `scripts/` and `tools/` are excluded from heuristic scoring unless the task explicitly references them.
 
----
+## Strict Validation
 
-## Commands
+`roadmapsmith validate --strict` is the independent audit path.
 
-```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
-```
+In strict mode:
 
-## Claude Code native slash commands
+- 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
 
-Install the full skill bundle for Claude Code:
+Recommended audit sequence:
 
 ```bash
-npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
-```
-
-Then reload the session:
-
-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`
-
-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.
-
-## Codex native plugin install
-
-RoadmapSmith now exposes a native Codex plugin manifest at `.codex-plugin/plugin.json` and a repo-local marketplace at `.agents/plugins/marketplace.json`.
-
-From the repository root:
-
-```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.
-
-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.
+`sync --audit` remains an advanced mutating summary, not an independent audit engine.
 
-`roadmapsmith status --json` now reports native slash surfaces separately from the VS Code task layer (`doctor --json` remains a compatibility alias):
+## Slash And Host Surfaces
 
-- `claudeGui`
-- `claudeCli`
-- `codexGui`
-- `codexCli`
+Canonical native slash surfaces:
 
-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.
+- `/roadmap`
+- `/roadmap-zero`
+- `/roadmap-maintain`
+- `/roadmap-status`
+- `/roadmap-validate`
+- `/roadmap-update`
+- `/roadmap-setup`
 
-If Codex shows `Roadmap Sync` twice, the usual cause is a collision between:
+Advanced native slash surfaces:
 
-- `~/.agents/skills/roadmap-sync`
-- the installed `roadmapsmith` Codex plugin
+- `/roadmap-init`
+- `/roadmap-generate`
+- `/roadmap-audit`
 
-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.
+Compatibility-only slash surfaces:
 
-## Behavior
+- `/roadmap-sync <action>`
+- `/road <action>`
+- deprecated direct aliases
 
-- 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.
-- Validation evidence gate:
-  - code OR test OR artifact evidence required.
-  - test evidence required for code tasks when test frameworks are detected.
-- 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 (`FAIL:NOT_IMPLEMENTED`, `FAIL:NO_TEST`, `FAIL:MISSING_REFERENCE`, and `WARN:STALE_EVIDENCE`).
-- `update --task <id> --evidence <text>` writes only when the evidence validates at high confidence; otherwise the roadmap is unchanged.
+Native-bundle readiness is computed from canonical surfaces only. Missing advanced labels or duplicate legacy `/roadmap-sync` installs are warnings, not canonical-health failures.
 
-## Defaults
+## Host Setup
 
-- 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`
+`roadmapsmith setup` generates:
 
-Roadmap resolution precedence:
+- `.vscode/tasks.json`
+- `.vscode/roadmapsmith-launcher.js`
+- `.vscode/roadmapsmith-task.cmd`
+- `.vscode/roadmapsmith-task.sh`
+- optional Claude hook wiring
 
-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)

package/bin/cli.js

@@ -19,21 +19,27 @@ const { buildZeroModeConfigPatch, buildZeroModeDefaults, collectZeroModeAnswers,
 function printHelp() {
   console.log([
     'Usage:',
+    '  Canonical commands:',
     '  roadmapsmith zero [--project-root <path>] [--config <path>]',
     '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen]',
-    '  roadmapsmith /roadmap',
-    '  roadmapsmith /roadmap <action>',
-    '  roadmapsmith /roadmap-zero | /roadmap-maintain | /roadmap-status | /roadmap-init | /roadmap-generate | /roadmap-validate | /roadmap-update | /roadmap-audit | /roadmap-setup',
-    '  roadmapsmith /road <action>              # deprecated compatibility alias',
-    '  roadmapsmith /roadmap-sync <action>      # deprecated legacy compatibility root',
-    '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
+    '  roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]',
+    '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json] [--strict]',
+    '  roadmapsmith update [--task <stable-id> --evidence <text>] [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]',
     '  roadmapsmith setup [--project-root <path>] [--config <path>] [--editor vscode] [--hosts <codex,claude>] [--dry-run]',
+    '',
+    '  Advanced commands:',
+    '  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'
+    '  roadmapsmith /roadmap',
+    '  roadmapsmith /roadmap <action>',
+    '  roadmapsmith /roadmap-zero | /roadmap-maintain | /roadmap-status | /roadmap-validate | /roadmap-update | /roadmap-setup | /roadmap-init | /roadmap-generate | /roadmap-audit',
+    '',
+    '  Compatibility notes:',
+    '  roadmapsmith doctor [--json]            # compatibility alias for status',
+    '  roadmapsmith regenerate                 # deprecated alias for generate --full-regen',
+    '  roadmapsmith /road <action>             # deprecated compatibility alias',
+    '  roadmapsmith /roadmap-sync <action>     # deprecated legacy compatibility root'
   ].join('\n'));
 }
 
@@ -48,7 +54,9 @@ function formatResultLine(task, result) {
   const diagnostics = Array.isArray(result.diagnostics) ? result.diagnostics : [];
   const primaryError = diagnostics.find((item) => item.severity === 'error');
   const warnings = diagnostics.filter((item) => item.severity === 'warning');
-  const status = primaryError ? `FAIL:${primaryError.code}` : (result.passed ? 'PASS' : 'FAIL');
+  const status = primaryError
+    ? `FAIL:${primaryError.code}`
+    : (result.passed ? 'PASS' : (warnings[0] ? `WARN:${warnings[0].code}` : 'FAIL'));
   const parts = [...result.reasons];
   warnings.forEach((item) => parts.push(`WARN:${item.code} ${item.message}`));
   const reason = parts.length > 0 ? ` :: ${parts.join('; ')}` : '';
@@ -79,6 +87,23 @@ function printAudit(audit) {
   }
 }
 
+function printReadinessSummary(summary) {
+  if (!summary || typeof summary !== 'object') {
+    return;
+  }
+
+  console.log('\nStructured readiness summary:');
+  console.log(`- Workspace readiness: ${summary.workspaceReady ? 'ready' : 'needs setup'}`);
+  console.log(`- Codex readiness: ${summary.codexReady ? 'ready' : 'needs setup'}`);
+  console.log(`- Claude readiness: ${summary.claudeReady ? 'ready' : 'needs setup'}`);
+  console.log(`- Canonical native surfaces: ${summary.canonicalSurfaceReady ? 'ready' : 'needs attention'}`);
+  if (Array.isArray(summary.advancedSurfaceWarnings) && summary.advancedSurfaceWarnings.length > 0) {
+    summary.advancedSurfaceWarnings.forEach((warning) => {
+      console.log(`- Advanced warning: ${warning}`);
+    });
+  }
+}
+
 function formatSurfaceLabel(surfaceKey) {
   return surfaceKey
     .replace(/([A-Z])/g, ' $1')
@@ -305,13 +330,18 @@ function printHumanStatus(payload) {
   if (!payload.vscode.tasks.ready && payload.vscode.tasks.missingLabels.length > 0) {
     console.log(`Missing VS Code tasks: ${payload.vscode.tasks.missingLabels.join(', ')}`);
   }
+  if (Array.isArray(payload.vscode.tasks.missingAdvancedLabels) && payload.vscode.tasks.missingAdvancedLabels.length > 0) {
+    console.log(`Missing advanced VS Code tasks: ${payload.vscode.tasks.missingAdvancedLabels.join(', ')}`);
+  }
   if (!payload.vscode.wrappers.ready) {
     console.log(`Missing task wrapper files: ${payload.vscode.wrappers.missingPaths.join(', ')}`);
   }
   console.log(`Codex readiness: ${payload.hosts.codex.ready ? 'ready' : 'needs setup'} (${payload.hosts.codex.message})`);
   console.log(`Claude readiness: ${payload.hosts.claude.ready ? 'ready' : 'needs setup'} (${payload.hosts.claude.message})`);
+  printReadinessSummary(payload.summary);
   printNativeSurfaceStatus(payload.surfaces);
-  console.log('\nRecommended entrypoints: roadmapsmith zero (empty repo), roadmapsmith maintain (existing repo).');
+  console.log('\nRecommended entrypoints: roadmapsmith zero (empty repo), roadmapsmith maintain (existing repo), roadmapsmith update (canonical checklist refresh/task completion).');
+  console.log('Compatibility note: roadmapsmith doctor mirrors this payload for existing automation.');
   if (!payload.cli.ready) {
     console.log('\nInstalling the skill alone does not expose the CLI in VS Code. Install the CLI and rerun roadmapsmith setup.');
   }
@@ -420,8 +450,6 @@ async function run() {
     if (slashAction.id === 'audit') {
       flags.audit = true;
       effectiveCommand = 'sync';
-    } else if (slashAction.id === 'sync' && String(command).trim().toLowerCase() === '/roadmap-update') {
-      effectiveCommand = 'update';
     } else {
       effectiveCommand = slashAction.id;
     }
@@ -456,6 +484,7 @@ async function run() {
   if (effectiveCommand === 'regenerate') {
     const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
     const config = loadConfig({ projectRoot, configPath: flags.config });
+    process.stderr.write('The regenerate command is deprecated. Use generate --full-regen for the public destructive rebuild path.\n');
     runRegenerateCommand(projectRoot, config, flags);
     return;
   }
@@ -508,7 +537,9 @@ async function run() {
 
     const parsedRoadmap = parseRoadmap(content);
     const tasks = maybeFilterTasks(parsedRoadmap.tasks, flags.task);
-    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins), {
+      strictValidation: isEnabled(flags.strict)
+    });
     const results = validateTasks(tasks, validationContext, config, validationContext.plugins);
 
     const minRank = CONFIDENCE_RANK[config.validation && config.validation.minimumConfidence] ?? 0;
@@ -604,6 +635,9 @@ async function run() {
         logError(`[fail] VS Code tasks incomplete: missing ${hostStatus.vscode.tasks.missingLabels.join(', ') || 'managed labels'}`);
         ok = false;
       }
+      if (Array.isArray(hostStatus.vscode.tasks.missingAdvancedLabels) && hostStatus.vscode.tasks.missingAdvancedLabels.length > 0) {
+        log(`[warn] Advanced VS Code tasks missing: ${hostStatus.vscode.tasks.missingAdvancedLabels.join(', ')}`);
+      }
 
       if (hostStatus.runtime.ready) {
         log(`[ok] Node runtime: ${hostStatus.runtime.kind}${hostStatus.runtime.path ? ` (${hostStatus.runtime.path})` : ''}`);