roadmapsmith 0.9.29 → 0.9.31

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 maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen] [--refresh-annotations]',
+    '  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 sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit] [--refresh-annotations]',
+    '  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'));
 }
 
@@ -81,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')
@@ -203,7 +226,8 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
   const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
   const results = validateTasks(syncTasks, validationContext, config, validationContext.plugins);
   applyMinimumConfidence(results, config.validation?.minimumConfidence);
-  const next = applySync(content, syncTasks, results);
+  const forceRefresh = isEnabled(flags['refresh-annotations']);
+  const next = applySync(content, syncTasks, results, { forceRefresh });
   const dryRun = isEnabled(flags['dry-run']);
   const writeResult = writeText(roadmapFile, next, { dryRun });
 
@@ -307,13 +331,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.');
   }
@@ -422,8 +451,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;
     }
@@ -458,6 +485,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;
   }
@@ -510,7 +538,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;
@@ -606,6 +636,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})` : ''}`);

package/package.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.",
   "main": "src/index.js",
   "bin": {
     "roadmapsmith": "bin/cli.js"

package/skills/roadmap-maintain/SKILL.md

@@ -17,3 +17,4 @@ Use this command when the repository already has code, tests, docs, or an existi
 4. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
 5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
 6. Mention that `roadmapsmith maintain --full-regen` or `roadmapsmith generate --full-regen` is the explicit destructive rebuild path when the user truly wants a full managed-block replacement.
+7. When the user wants stale or outdated warning annotations to be recomputed from scratch (including annotations that were written by a prior maintain run or an external agent), use `roadmapsmith maintain --refresh-annotations`. This forces all existing warning text to be replaced with the current deterministic result rather than preserved. It is distinct from `--full-regen` (which rebuilds the managed block structure) — `--refresh-annotations` only affects warning annotations on still-failing tasks.

package/skills/roadmap-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roadmap-status
-description: Inspect RoadmapSmith readiness through doctor JSON and summarize the result.
+description: Inspect RoadmapSmith readiness through status JSON and summarize the result.
 ---
 
 # RoadmapSmith Status
@@ -10,8 +10,9 @@ Use this command to inspect whether the shared bundle, native host surfaces, CLI
 ## Required behavior
 
 1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js doctor --json --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js doctor --json --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith doctor --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" doctor --json --project-root .`.
-3. Parse and summarize the JSON output in plain language.
-4. Explicitly call out missing commands or duplicate `/roadmap-sync` registration when doctor reports them.
+   - `node roadmap-skill/bin/cli.js status --json --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js status --json --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith status --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" status --json --project-root .`.
+3. Treat `roadmapsmith doctor --json` as compatibility-only output for existing automation, not as the primary recommendation.
+4. Parse and summarize the JSON output in plain language.
+5. Explicitly call out missing canonical commands, duplicate legacy `/roadmap-sync` registration, and any missing advanced VS Code labels as warnings rather than canonical-readiness failures.

package/skills/roadmap-update/SKILL.md

@@ -5,14 +5,14 @@ description: Apply evidence-backed checklist sync or complete one task with veri
 
 # RoadmapSmith Update
 
-Use this command when the user wants the direct sync surface without routing through the legacy `/roadmap-sync <action>` root.
+Use this command when the user wants the canonical public `update` surface without routing through the legacy `/roadmap-sync <action>` root.
 
 ## Required behavior
 
 1. Prefer the local engine inside this repository:
    - `node roadmap-skill/bin/cli.js update --project-root .`
    - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js update --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith update --project-root .`. If that global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
-3. Explain that `/roadmap-update` is the visible namespaced sync command, while `/roadmap-sync <action>` remains legacy compatibility.
-4. Keep the evidence-backed sync semantics unchanged: no-argument update syncs the roadmap from repository evidence; it is not a full regeneration path.
+2. Otherwise prefer `roadmapsmith update --project-root .`. If its global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
+3. Explain that `/roadmap-update` is the visible namespaced command for the public `update` family, while `/roadmap-sync <action>` remains deprecated compatibility only.
+4. Keep the evidence-backed refresh semantics unchanged: no-argument `update` syncs the roadmap from repository evidence, and `sync` remains the advanced CLI alias for that same mutating refresh path. It is not a full regeneration path and not an independent audit engine.
 5. To complete one task, run `roadmapsmith update --task <stable-id> --evidence "<single-line evidence>"`. It writes only after the supplied evidence validates at high confidence; use `--dry-run` to preview it.

package/skills.json

@@ -21,74 +21,74 @@
     "command": "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "source": "PapiScholz/roadmapsmith",
     "skill": "*",
-    "notes": "Recommended Claude Code install path for native GUI slash commands like /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, and /roadmap-setup. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the visible readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
+    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
   },
   "skills": [
     {
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
       "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
       "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
       "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
-      "description": "Native slash entrypoint for the current sync-plus-audit workflow.",
-      "version": "0.9.29"
+      "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.29"
+      "version": "0.9.31"
     }
   ]
 }

package/src/host.js

@@ -4,7 +4,14 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { readTextIfExists, writeText } = require('./io');
-const { getHostNativeSkillNames, getHostNativeSlashCommands, getSlashActionSpecs } = require('./slash');
+const {
+  getAdvancedHostNativeSlashCommands,
+  getCanonicalHostNativeSlashCommands,
+  getCompatibilityHostNativeSlashCommands,
+  getHostNativeSkillNames,
+  getHostNativeSlashCommands,
+  getSlashActionSpecs
+} = require('./slash');
 
 const SUPPORTED_EDITORS = new Set(['vscode']);
 const SUPPORTED_HOSTS = new Set(['codex', 'claude']);
@@ -13,18 +20,25 @@ const REPO_ROOT = path.resolve(PACKAGE_ROOT, '..');
 const VSCODE_LAUNCHER_RELATIVE_PATH = '.vscode/roadmapsmith-launcher.js';
 const WINDOWS_TASK_WRAPPER_RELATIVE_PATH = '.vscode/roadmapsmith-task.cmd';
 const POSIX_TASK_WRAPPER_RELATIVE_PATH = '.vscode/roadmapsmith-task.sh';
-const ROADMAPSMITH_TASK_LABELS = [
+const ROADMAPSMITH_CANONICAL_TASK_LABELS = [
   'RoadmapSmith: Zero Mode',
   'RoadmapSmith: Maintain',
   'RoadmapSmith: Status',
+  'RoadmapSmith: Validate',
+  'RoadmapSmith: Update',
+  'RoadmapSmith: Refresh Setup'
+];
+const ROADMAPSMITH_ADVANCED_TASK_LABELS = [
   'RoadmapSmith: Explain Workflow',
   'RoadmapSmith: Init',
   'RoadmapSmith: Generate',
-  'RoadmapSmith: Validate',
   'RoadmapSmith: Sync',
   'RoadmapSmith: Sync Dry Run',
-  'RoadmapSmith: Sync Audit',
-  'RoadmapSmith: Refresh Setup'
+  'RoadmapSmith: Sync Audit'
+];
+const ROADMAPSMITH_TASK_LABELS = [
+  ...ROADMAPSMITH_CANONICAL_TASK_LABELS,
+  ...ROADMAPSMITH_ADVANCED_TASK_LABELS
 ];
 const CLAUDE_HOOK_COMMAND = 'node .claude/hooks/roadmap-sync.js';
 const CLAUDE_HOOK_RELATIVE_PATH = '.claude/hooks/roadmap-sync.js';
@@ -32,6 +46,9 @@ const ROADMAPSMITH_PLUGIN_NAME = 'roadmapsmith';
 const LEGACY_ROADMAP_SYNC_SKILL_NAME = 'roadmap-sync';
 const EXPECTED_NATIVE_SKILL_NAMES = Object.freeze(getHostNativeSkillNames());
 const EXPECTED_NATIVE_SLASH_COMMANDS = Object.freeze(getHostNativeSlashCommands());
+const EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS = Object.freeze(getCanonicalHostNativeSlashCommands());
+const EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS = Object.freeze(getAdvancedHostNativeSlashCommands());
+const EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS = Object.freeze(getCompatibilityHostNativeSlashCommands());
 const BUNDLE_ROOT_CANDIDATES = Object.freeze([
   { kind: 'package', root: PACKAGE_ROOT },
   { kind: 'repo', root: REPO_ROOT }
@@ -294,14 +311,15 @@ function createManagedTasks() {
     createTask('zero', 'RoadmapSmith: Zero Mode', 'Run the Zero Mode interview and generate the first roadmap in one command.'),
     createTask('maintain', 'RoadmapSmith: Maintain', 'Run the preserve-first existing-repo flow: generate, sync, and audit in one command.'),
     createTask('status', 'RoadmapSmith: Status', 'Inspect readiness and learn the slash entrypoints like /roadmap, /roadmap-update, and legacy /roadmap-sync <action>.'),
+    createTask('validate', 'RoadmapSmith: Validate', 'Inspect per-task evidence status as JSON.'),
+    createTask('update', 'RoadmapSmith: Update', 'Apply evidence-backed checklist refresh or complete one task with verified evidence.'),
+    createTask('setup', 'RoadmapSmith: Refresh Setup', 'Reapply RoadmapSmith VS Code and host integration files.'),
     createTask('explain', 'RoadmapSmith: Explain Workflow', 'Explain how zero, maintain, the skill, setup, slash routing, and VS Code tasks work together.'),
     createTask('init', 'RoadmapSmith: Init', 'Create ROADMAP.md and AGENTS.md when they are missing.'),
     createTask('generate', 'RoadmapSmith: Generate', 'Update ROADMAP.md and refuse destructive replacement unless rerun with --full-regen.'),
-    createTask('validate', 'RoadmapSmith: Validate', 'Inspect per-task evidence status as JSON.'),
     createTask('sync', 'RoadmapSmith: Sync', 'Apply evidence-backed checklist sync to ROADMAP.md.'),
     createTask('sync-dry-run', 'RoadmapSmith: Sync Dry Run', 'Preview the next roadmap sync without writing files.'),
-    createTask('sync-audit', 'RoadmapSmith: Sync Audit', 'Run sync and print the post-sync mismatch summary.'),
-    createTask('setup', 'RoadmapSmith: Refresh Setup', 'Reapply RoadmapSmith VS Code and host integration files.')
+    createTask('sync-audit', 'RoadmapSmith: Sync Audit', 'Run sync and print the post-sync mismatch summary.')
   ];
 }
 
@@ -568,7 +586,7 @@ function inspectSharedBundleSurface() {
     ? skillsManifest.skills.map((skill) => skill && skill.name).filter(Boolean)
     : [];
   const availableCommands = declaredSkillNames.map((name) => `/${name}`);
-  const missingCommands = EXPECTED_NATIVE_SLASH_COMMANDS.filter((command) => !availableCommands.includes(command));
+  const missingCommands = EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.filter((command) => !availableCommands.includes(command));
 
   return {
     kind: bundleSurface.kind,
@@ -586,7 +604,9 @@ function inspectSharedBundleSurface() {
       hasCodexPluginManifest: bundleSurface.hasCodexPluginManifest
     },
     declaredSkillNames,
-    expectedCommands: EXPECTED_NATIVE_SLASH_COMMANDS.slice(),
+    expectedCommands: EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.slice(),
+    advancedCommands: EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.slice(),
+    compatibilityCommands: EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS.slice(),
     availableCommands,
     missingCommands
   };
@@ -635,7 +655,7 @@ function inspectCodexPluginState(projectRoot, options = {}) {
     ? options.codexCommandPath
     : findCommandPath('codex', env);
   const legacySkill = inspectLegacyRoadmapSyncSkill(options, env);
-  const expectedCommands = EXPECTED_NATIVE_SLASH_COMMANDS.slice();
+  const expectedCommands = EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.slice();
   const missingCommands = expectedCommands.slice();
   const baseState = {
     commandPath: codexCommandPath,
@@ -708,13 +728,15 @@ function inspectCodexPluginState(projectRoot, options = {}) {
     plugin,
     marketplace,
     expectedCommands,
+    advancedCommands: EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.slice(),
+    compatibilityCommands: EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS.slice(),
     availableCommands: expectedCommands,
     missingCommands: [],
     duplicates,
-    ready: duplicates.length === 0,
+    ready: true,
     source: `${plugin.pluginId || plugin.name}${plugin.marketplaceName ? ` (${plugin.marketplaceName})` : ''}`,
     message: duplicates.length > 0
-      ? 'RoadmapSmith is installed in Codex, but /roadmap-sync is duplicated by the legacy ~/.agents/skills install.'
+      ? 'RoadmapSmith is installed in Codex. The legacy ~/.agents/skills install still duplicates /roadmap-sync, but the canonical native surface is healthy.'
       : 'RoadmapSmith is installed and enabled in Codex. Interactive slash-menu visibility still needs manual host verification.',
     legacySkill
   };
@@ -783,14 +805,23 @@ function renderVsCodeLauncher() {
     '}',
     '',
     'function getNamespacedDirectSlash(actionId) {',
-    '  return actionId === \'sync\' ? \'/roadmap-update\' : `/roadmap-${actionId}`;',
+    '  return `/roadmap-${actionId}`;',
     '}',
     '',
     'const DIRECT_HOST_NATIVE_ALIAS_TO_ACTION = Object.fromEntries(',
     '  SLASH_ACTIONS.map((action) => [getNamespacedDirectSlash(action.id), action.id])',
     ');',
     'const DIRECT_DEPRECATED_CLI_ALIAS_TO_ACTION = Object.fromEntries(',
-    '  SLASH_ACTIONS.map((action) => [`/${action.id}`, action.id])',
+    '  SLASH_ACTIONS.flatMap((action) => {',
+    '    const aliases = Array.isArray(action.aliases) ? action.aliases : [];',
+    '    return [action.id, ...aliases].map((alias) => [`/${alias}`, action.id]);',
+    '  })',
+    ');',
+    'const ACTION_ALIAS_TO_ID = Object.fromEntries(',
+    '  SLASH_ACTIONS.flatMap((action) => {',
+    '    const aliases = Array.isArray(action.aliases) ? action.aliases : [];',
+    '    return [action.id, ...aliases].map((alias) => [alias, action.id]);',
+    '  })',
     ');',
     '',
     'function normalizeActionId(value) {',
@@ -798,19 +829,28 @@ function renderVsCodeLauncher() {
     '  if (normalized.startsWith(\'roadmap-\')) {',
     '    normalized = normalized.slice(\'roadmap-\'.length);',
     '  }',
-    '  if (normalized === \'update\') {',
-    '    normalized = \'sync\';',
-    '  }',
     '  return normalized;',
     '}',
     '',
+    'function canonicalizeActionId(value) {',
+    '  const normalized = normalizeActionId(value);',
+    '  return ACTION_ALIAS_TO_ID[normalized] || normalized;',
+    '}',
+    '',
+    'function actionSearchTerms(action) {',
+    '  return [action.id, ...(Array.isArray(action.aliases) ? action.aliases : [])];',
+    '}',
+    '',
     'function getSlashSuggestions(query) {',
     '  const normalized = normalizeActionId(query);',
     '  if (!normalized) {',
     '    return SLASH_ACTIONS.slice();',
     '  }',
-    '  const startsWithMatches = SLASH_ACTIONS.filter((action) => action.id.startsWith(normalized));',
-    '  const containsMatches = SLASH_ACTIONS.filter((action) => !action.id.startsWith(normalized) && action.id.includes(normalized));',
+    '  const startsWithMatches = SLASH_ACTIONS.filter((action) => actionSearchTerms(action).some((term) => term.startsWith(normalized)));',
+    '  const containsMatches = SLASH_ACTIONS.filter((action) => {',
+    '    return !actionSearchTerms(action).some((term) => term.startsWith(normalized))',
+    '      && actionSearchTerms(action).some((term) => term.includes(normalized));',
+    '  });',
     '  return [...startsWithMatches, ...containsMatches];',
     '}',
     '',
@@ -857,7 +897,7 @@ function renderVsCodeLauncher() {
     '}',
     '',
     'function getSlashAction(actionId) {',
-    '  const normalized = normalizeActionId(actionId);',
+    '  const normalized = canonicalizeActionId(actionId);',
     '  return SLASH_ACTIONS.find((action) => action.id === normalized) || null;',
     '}',
     '',
@@ -921,13 +961,13 @@ function renderVsCodeLauncher() {
     'function explain() {',
     '  console.log(\'RoadmapSmith layers:\\n\');',
     '  console.log(\'1. The roadmap-sync skill guides the agent. It does not add VS Code buttons or install the CLI.\');',
-    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus init/generate/validate/sync/setup/status, with doctor kept as a compatibility alias and --full-regen reserved for destructive replacement.\');',
+    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus the canonical update family, with sync kept as the advanced alias for manual refresh and doctor kept as a compatibility alias.\');',
     '  console.log(\'3. roadmapsmith setup makes the CLI visible in VS Code through tasks and optional Claude hook wiring.\\n\');',
     '  console.log(\'Typical VS Code workflow:\');',
     '  console.log(\'- Run "RoadmapSmith: Status" to inspect readiness.\');',
     '  console.log(\'- For empty repos, run "RoadmapSmith: Zero Mode" or use "/roadmap zero".\');',
     '  console.log(\'- For existing repos, run "RoadmapSmith: Maintain" or use "/roadmap maintain".\');',
-    '  console.log(\'- Use Init, Generate, Validate, and Sync when you want manual control.\\n\');',
+    '  console.log(\'- Use Update for the public checklist-refresh/task-completion family, and use Init, Generate, Validate, and Sync when you want manual control.\\n\');',
     '  console.log(\'If you installed only the skill, install the CLI as well and then run "RoadmapSmith: Refresh Setup".\');',
     '}',
     '',
@@ -954,6 +994,16 @@ function renderVsCodeLauncher() {
     '  }',
     '  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})`);',
+    '  if (payload.summary) {',
+    '    console.log(\'\\nStructured readiness summary:\');',
+    '    console.log(`- Workspace readiness: ${payload.summary.workspaceReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Codex readiness: ${payload.summary.codexReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Claude readiness: ${payload.summary.claudeReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Canonical native surfaces: ${payload.summary.canonicalSurfaceReady ? \'ready\' : \'needs attention\'}`);',
+    '    if (Array.isArray(payload.summary.advancedSurfaceWarnings)) {',
+    '      payload.summary.advancedSurfaceWarnings.forEach((warning) => console.log(`- Advanced warning: ${warning}`));',
+    '    }',
+    '  }',
     '  if (payload.surfaces && typeof payload.surfaces === \'object\') {',
     '    console.log(\'\\nNative slash surfaces:\');',
     '    Object.entries(payload.surfaces).forEach(([surfaceKey, surface]) => {',
@@ -976,7 +1026,8 @@ function renderVsCodeLauncher() {
     '  if (!payload.runtime.ready) {',
     '    console.log(\'\\nThe VS Code task runtime is missing. Install Node.js or set ROADMAPSMITH_NODE, then rerun "RoadmapSmith: Status".\');',
     '  }',
-    '  console.log(\'\\nRecommended entrypoints: roadmapsmith zero, roadmapsmith maintain\');',
+    '  console.log(\'\\nRecommended entrypoints: roadmapsmith zero, roadmapsmith maintain, roadmapsmith update\');',
+    '  console.log(\'Compatibility note: roadmapsmith doctor mirrors this payload for existing automation.\');',
     '  console.log(\'Slash entrypoints: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, /roadmap-setup, plus legacy /roadmap-sync <action>.\');',
     '}',
     '',
@@ -1041,6 +1092,7 @@ function renderVsCodeLauncher() {
     '  maintain: [\'maintain\', \'--project-root\', PROJECT_ROOT],',
     '  init: [\'init\'],',
     '  generate: [\'generate\', \'--project-root\', PROJECT_ROOT],',
+    '  update: [\'update\', \'--project-root\', PROJECT_ROOT],',
     '  validate: [\'validate\', \'--json\', \'--project-root\', PROJECT_ROOT],',
     '  sync: [\'sync\', \'--project-root\', PROJECT_ROOT],',
     '  audit: [\'sync\', \'--audit\', \'--project-root\', PROJECT_ROOT],',
@@ -1228,10 +1280,12 @@ function inspectVsCodeTasks(projectRoot) {
     tasks: {
       path: tasksPath,
       exists: tasksConfig != null,
-      ready: ROADMAPSMITH_TASK_LABELS.every((label) => presentLabels.includes(label)) && fs.existsSync(launcherPath) && wrapperEntries.every((entry) => entry.exists),
-      expectedLabels: ROADMAPSMITH_TASK_LABELS.slice(),
+      ready: ROADMAPSMITH_CANONICAL_TASK_LABELS.every((label) => presentLabels.includes(label)) && fs.existsSync(launcherPath) && wrapperEntries.every((entry) => entry.exists),
+      expectedLabels: ROADMAPSMITH_CANONICAL_TASK_LABELS.slice(),
+      advancedLabels: ROADMAPSMITH_ADVANCED_TASK_LABELS.slice(),
       presentLabels: presentManagedLabels,
-      missingLabels: ROADMAPSMITH_TASK_LABELS.filter((label) => !presentLabels.includes(label))
+      missingLabels: ROADMAPSMITH_CANONICAL_TASK_LABELS.filter((label) => !presentLabels.includes(label)),
+      missingAdvancedLabels: ROADMAPSMITH_ADVANCED_TASK_LABELS.filter((label) => !presentLabels.includes(label))
     }
   };
 }
@@ -1359,14 +1413,29 @@ function inspectHostSetup(projectRoot, options = {}) {
           ? 'Claude PostToolUse hook is configured'
           : 'Run roadmapsmith setup with the claude host and verify node is available to Claude'
       }
+    },
+    summary: {
+      workspaceReady: cli.ready && runtime.ready && vscode.tasks.ready && Boolean(roadmapFile && fs.existsSync(roadmapFile)) && Boolean(agentsFile && fs.existsSync(agentsFile)),
+      codexReady,
+      claudeReady: cli.ready && claude.ready,
+      canonicalSurfaceReady: bundle.ready && vscode.tasks.ready,
+      advancedSurfaceWarnings: [
+        ...vscode.tasks.missingAdvancedLabels.map((label) => `Missing advanced VS Code task: ${label}`),
+        ...EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.filter((command) => !bundle.advancedCommands.includes(command)).map((command) => `Missing advanced bundle slash command: ${command}`)
+      ]
     }
   };
 }
 
 module.exports = {
   CLAUDE_HOOK_COMMAND,
+  EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS,
+  EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS,
+  EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS,
   EXPECTED_NATIVE_SKILL_NAMES,
   EXPECTED_NATIVE_SLASH_COMMANDS,
+  ROADMAPSMITH_ADVANCED_TASK_LABELS,
+  ROADMAPSMITH_CANONICAL_TASK_LABELS,
   ROADMAPSMITH_TASK_LABELS,
   applySetupFiles,
   assertSupportedEditor,

package/src/reasons.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// Low-specificity reason strings produced by the deterministic validator for
+// policy-level failures. These messages carry no file- or symbol-specific
+// information and should not overwrite more informative existing annotations
+// that a prior run or a human/agent authored.
+const LOW_SPECIFICITY_REASONS = new Set([
+  'validation failed',
+  'implementation task requires deterministic Verify metadata or explicit Evidence to be marked complete',
+  'implementation task requires Evidence line or high-confidence evidence (code + test) to be marked complete',
+]);
+
+/**
+ * Returns true when `reason` is a low-specificity policy message — one that carries
+ * no file- or symbol-specific diagnostic value and should not be used to overwrite
+ * a more informative existing annotation.
+ *
+ * Input should be a normalized reason string (⚠️ prefix and warning prefixes already
+ * stripped, as produced by normalizeWarningReason in src/sync/index.js).
+ *
+ * @param {string} reason
+ * @returns {boolean}
+ */
+function isLowSpecificityReason(reason) {
+  return LOW_SPECIFICITY_REASONS.has(String(reason || '').trim());
+}
+
+module.exports = { LOW_SPECIFICITY_REASONS, isLowSpecificityReason };