roadmapsmith 0.9.33 → 0.9.36

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.36",
   "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,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.36",
   "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/README.md

@@ -8,7 +8,7 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 - `roadmapsmith setup`
 - `roadmapsmith zero`
-- `roadmapsmith maintain`
+- `roadmapsmith maintain [--dry-run]`
 - `roadmapsmith status [--json]`
 - `roadmapsmith validate [--json] [--strict]`
 - `roadmapsmith update [--task <stable-id> --evidence "<single-line evidence>"]`
@@ -40,11 +40,39 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 ### Zero Mode
 
-Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview, updates config, and generates the first roadmap.
+Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview when TTY is available, or consumes a complete brief from config plus flags in non-interactive environments.
+
+Non-interactive inputs:
+
+- `--product-name`
+- `--primary-user`
+- `--problem-statement`
+- `--target-outcome`
+- `--anti-goal` (repeatable)
+- `--preferred-stack`
+- `--constraint` (repeatable)
+- `--done-criterion` (repeatable)
+
+Without TTY, Zero Mode requires a complete brief from config/flags and fails clearly when required fields are missing.
 
 ### Sync/Audit Mode
 
-Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow.
+Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow for an existing managed roadmap block.
+
+If `ROADMAP.md` is authored and non-empty but has no `<!-- rs:managed:* -->` block:
+
+- `maintain` refuses to seed managed content implicitly
+- `update` is the conservative inline-annotation path
+- `generate` is the explicit managed-section creation path
+
+For write-capable surfaces (`maintain`, `generate`, `sync`, `update`), prefer `--dry-run` first.
+
+## Managed Block Ownership
+
+- `maintain` owns the managed roadmap block only.
+- `update` can annotate existing task lines even when no managed block exists.
+- `generate` is the explicit path that creates or replaces managed roadmap content.
+- Manually inserting empty `<!-- rs:managed:start -->` markers is no longer required as a workaround.
 
 ## Verification Model
 

package/bin/cli.js

@@ -14,14 +14,21 @@ const { generateRoadmapDocument } = require('../src/generator');
 const { parseRoadmap, tasksInManagedBlock } = require('../src/parser');
 const { buildValidationContext, validateTasks, auditValidation, CONFIDENCE_RANK, applyMinimumConfidence } = require('../src/validator');
 const { applySync } = require('../src/sync');
-const { buildZeroModeConfigPatch, buildZeroModeDefaults, collectZeroModeAnswers, isInteractiveTerminal } = require('../src/zero');
+const {
+  buildZeroModeConfigPatch,
+  collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
+  isInteractiveTerminal,
+  resolveZeroModeAnswers
+} = require('../src/zero');
 
 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] [--refresh-annotations]',
+    '  roadmapsmith zero [--project-root <path>] [--config <path>] [--product-name <text>] [--primary-user <text>] [--problem-statement <text>] [--target-outcome <text>] [--anti-goal <text> ...] [--preferred-stack <text>] [--constraint <text> ...] [--done-criterion <text> ...]',
+    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--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]',
@@ -85,6 +92,15 @@ function printAudit(audit) {
       console.log(`- [${item.task.id}] ${item.task.text}`);
     });
   }
+  if (Array.isArray(audit.newlyUnchecked) && audit.newlyUnchecked.length > 0) {
+    console.log(`Unchecked by this run (${audit.newlyUnchecked.length}): ${audit.newlyUnchecked.join(', ')}`);
+  }
+  if (Array.isArray(audit.humanVerifiedTasks) && audit.humanVerifiedTasks.length > 0) {
+    console.log(`Human-verified tasks (${audit.humanVerifiedTasks.length}):`);
+    audit.humanVerifiedTasks.forEach((item) => {
+      console.log(`- [${item.task.id}] ${item.task.text}`);
+    });
+  }
 }
 
 function printReadinessSummary(summary) {
@@ -140,6 +156,42 @@ function formatSetupVerb(result, dryRun) {
   return result.before == null ? 'Created' : 'Updated';
 }
 
+function emitPreWriteWarning(roadmapFile, options = {}) {
+  if (options.dryRun || options.suppressWarning) {
+    return;
+  }
+  if (options.warningState && options.warningState.emitted) {
+    return;
+  }
+
+  const commandName = options.commandName || 'roadmapsmith';
+  console.log(`Warning: ${commandName} will modify ${roadmapFile}. Review the preview first with --dry-run.`);
+  if (options.managedSectionNote) {
+    console.log(options.managedSectionNote);
+  }
+
+  if (options.warningState) {
+    options.warningState.emitted = true;
+  }
+}
+
+function assertMaintainCanWrite(roadmapFile, content) {
+  if (content == null || String(content).trim().length === 0) {
+    return;
+  }
+
+  const parsed = parseRoadmap(content);
+  if (parsed.hasManagedBlock) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to let roadmapsmith maintain seed a managed section into an authored roadmap without <!-- rs:managed:start --> markers: ${roadmapFile}\n` +
+    'For conservative inline annotations, run `roadmapsmith update --dry-run` then `roadmapsmith update`.\n' +
+    'To intentionally create a managed section, run `roadmapsmith generate --dry-run` then `roadmapsmith generate`.'
+  );
+}
+
 function runInitCommand(projectRoot, config, flags) {
   const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
   const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
@@ -187,6 +239,13 @@ function runGenerateCommand(projectRoot, config, flags, options = {}) {
     forceFullRegenerate: options.forceFullRegenerate === true || isEnabled(flags['full-regen'])
   });
 
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith generate',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState,
+    managedSectionNote: 'This command may create or replace a managed roadmap section depending on the current file state and flags.'
+  });
   const writeResult = writeText(roadmapFile, document, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -226,9 +285,25 @@ 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);
+  if (isEnabled(flags.audit)) {
+    const audit = auditValidation(syncTasks, results);
+    printAudit(audit);
+    const hasMismatch = audit.checkedWithoutEvidence.length > 0 || audit.readyButUnchecked.length > 0;
+    if (hasMismatch) {
+      process.exitCode = 2;
+    }
+    return;
+  }
+
   const forceRefresh = isEnabled(flags['refresh-annotations']);
-  const next = applySync(content, syncTasks, results, { forceRefresh });
+  const { content: next, changes } = applySync(content, syncTasks, results, { forceRefresh });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith sync',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
 
   if (dryRun) {
@@ -238,11 +313,17 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
       console.log(`No changes for ${roadmapFile}`);
     }
   } else {
+    if (changes.newlyUnchecked.length > 0) {
+      console.log(`Unchecked ${changes.newlyUnchecked.length} task(s): ${changes.newlyUnchecked.join(', ')}`);
+    }
+    if (changes.newlyChecked.length > 0) {
+      console.log(`Checked ${changes.newlyChecked.length} task(s): ${changes.newlyChecked.join(', ')}`);
+    }
     console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
   }
 
-  if (options.audit || isEnabled(flags.audit)) {
-    const audit = auditValidation(syncTasks, results);
+  if (options.audit) {
+    const audit = auditValidation(syncTasks, results, changes);
     printAudit(audit);
   }
 }
@@ -266,7 +347,7 @@ function runUpdateCommand(projectRoot, config, flags) {
   const hasTask = flags.task != null;
   const hasEvidence = flags.evidence != null;
   if (!hasTask && !hasEvidence) {
-    runSyncCommand(projectRoot, config, flags);
+    runSyncCommand(projectRoot, config, flags, { commandName: 'roadmapsmith update' });
     return;
   }
   if (!hasTask || !hasEvidence || Array.isArray(flags.task) || Array.isArray(flags.evidence)) {
@@ -298,14 +379,21 @@ function runUpdateCommand(projectRoot, config, flags) {
   const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
   const result = validateTasks([draftTask], validationContext, config, validationContext.plugins)[taskId];
   const errors = (result.diagnostics || []).filter((item) => item.severity === 'error');
+  const isEscapeHatch = draftTask.verifiedBy === 'human' || draftTask.kind === 'docs';
   const suppliedEvidenceResolved = result.evidence.authoritative && result.evidence.authoritativeFiles.length > 0;
-  if (!suppliedEvidenceResolved || !result.passed || result.confidence !== 'high' || errors.length > 0) {
+  const evidenceAccepted = isEscapeHatch ? result.passed : (suppliedEvidenceResolved && result.passed && result.confidence === 'high');
+  if (!evidenceAccepted || errors.length > 0) {
     const reasons = result.reasons.length > 0 ? `: ${result.reasons.join('; ')}` : '';
-    throw new Error(`Task ${taskId} was not updated; supplied evidence must resolve in the repository and validate at high confidence${reasons}`);
+    const hint = isEscapeHatch ? '; escape-hatch task requires an Evidence: child line' : '; supplied evidence must resolve in the repository and validate at high confidence';
+    throw new Error(`Task ${taskId} was not updated${hint}${reasons}`);
   }
 
-  const next = applySync(draft, [draftTask], { [taskId]: result });
+  const { content: next } = applySync(draft, [draftTask], { [taskId]: result });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: 'roadmapsmith update',
+    dryRun
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -371,40 +459,69 @@ function runStatusCommand(projectRoot, config, flags, options = {}) {
 async function runZeroCommand(projectRoot, flags) {
   const configPath = resolveConfigPath({ projectRoot, configPath: flags.config });
   const config = loadConfig({ projectRoot, configPath: flags.config });
-  if (!isInteractiveTerminal(process.stdin, process.stdout)) {
-    throw new Error('Zero Mode requires an interactive terminal. Run roadmapsmith zero from a terminal session, or add a config/brief workflow before retrying in non-interactive mode.');
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const roadmapExistedBeforeInit = fs.existsSync(roadmapFile);
+  const defaults = resolveZeroModeAnswers(projectRoot, config, flags);
+  const interactive = isInteractiveTerminal(process.stdin, process.stdout);
+  let answers = defaults;
+
+  if (!interactive) {
+    const missingFields = getMissingZeroModeFields(defaults);
+    if (missingFields.length > 0) {
+      throw new Error(
+        'Zero Mode requires a complete brief in non-interactive environments. Missing: ' +
+        `${formatMissingZeroModeFields(missingFields).join(', ')}. ` +
+        'Provide the missing values with CLI flags or in roadmap-skill.config.json before retrying.'
+      );
+    }
+    console.log('RoadmapSmith Zero Mode');
+    console.log('Using config/flag discovery inputs in non-interactive mode.\n');
+  } else {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    try {
+      console.log('RoadmapSmith Zero Mode');
+      console.log('Answer the discovery interview to generate the first roadmap.\n');
+      answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
+    } finally {
+      rl.close();
+    }
   }
 
-  const defaults = buildZeroModeDefaults(projectRoot, config);
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
+  const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
+  const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
+  writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
+  console.log(`Updated ${configPath}`);
+  const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
+  runInitCommand(projectRoot, nextConfig, flags);
+  runGenerateCommand(projectRoot, nextConfig, flags, {
+    commandName: 'roadmapsmith zero',
+    suppressPreWriteWarning: true,
+    forceFullRegenerate: !roadmapExistedBeforeInit
   });
-
-  try {
-    console.log('RoadmapSmith Zero Mode');
-    console.log('Answer the discovery interview to generate the first roadmap.\n');
-    const answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
-    const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
-    const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
-    writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
-    console.log(`Updated ${configPath}`);
-    const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
-    runInitCommand(projectRoot, nextConfig, flags);
-    runGenerateCommand(projectRoot, nextConfig, flags);
-  } finally {
-    rl.close();
-  }
 }
 
 function runMaintainCommand(projectRoot, flags) {
   const config = loadConfig({ projectRoot, configPath: flags.config });
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const existingContent = readTextIfExists(roadmapFile);
+  assertMaintainCanWrite(roadmapFile, existingContent);
   const fullRegen = isEnabled(flags['full-regen']);
+  const warningState = { emitted: false };
   runGenerateCommand(projectRoot, config, flags, {
+    commandName: 'roadmapsmith maintain',
     preserveManagedBlock: !fullRegen,
-    forceFullRegenerate: fullRegen
+    forceFullRegenerate: fullRegen,
+    warningState
+  });
+  runSyncCommand(projectRoot, config, { ...flags, audit: undefined }, {
+    audit: true,
+    commandName: 'roadmapsmith maintain',
+    warningState
   });
-  runSyncCommand(projectRoot, config, { ...flags, audit: true }, { audit: true });
 }
 
 async function run() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.33",
+  "version": "0.9.36",
   "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": {

package/skills/roadmap-maintain/SKILL.md

@@ -9,7 +9,8 @@ Use this command when the repository already has code, tests, docs, or an existi
 
 ## Required behavior
 
-1. Run `roadmapsmith maintain --project-root .`.
+1. Run `roadmapsmith maintain --project-root .`. Prefer `--dry-run` first when previewing impact.
 2. Treat this command as CLI-backed. Do not silently replace it with manual reasoning when the CLI is unavailable.
-3. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
-4. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
+3. Mention that maintain runs preserve-first generate, sync, and audit in one invocation, but only for an existing managed roadmap block.
+4. If the roadmap is non-empty and lacks `<!-- rs:managed:* -->`, direct the user to `roadmapsmith update` for conservative inline annotations or `roadmapsmith generate` for explicit managed-section creation.
+5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.

package/skills/roadmap-sync/agents/openai.yaml

@@ -2,6 +2,6 @@
   "interface": {
     "display_name": "Roadmap Sync (Deprecated)",
     "short_description": "DEPRECATED legacy root; use /roadmap-maintain or /roadmap-update.",
-    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update."
+    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update; use /roadmap-update when markers are missing."
   }
 }

package/skills/roadmap-zero/SKILL.md

@@ -10,4 +10,5 @@ Use this command when the repository is empty or low-context and the user needs
 ## Required behavior
 
 1. Run `roadmapsmith zero --project-root .`.
-2. If the CLI is missing, explain the install path instead of improvising the workflow manually.
+2. In non-interactive environments, provide or reuse a complete brief from config plus flags such as `--primary-user`, `--problem-statement`, `--target-outcome`, and repeatable `--done-criterion`.
+3. If the CLI is missing, explain the install path instead of improvising the workflow manually.

package/skills.json

@@ -12,7 +12,7 @@
     "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "roadmapsmith setup",
     "roadmapsmith zero",
-    "roadmapsmith maintain",
+    "roadmapsmith maintain --dry-run",
     "roadmapsmith /roadmap",
     "roadmapsmith update --task p2-customer-history --evidence \"src/app/api/customers/route.ts, test/customers.test.js\"",
     "roadmapsmith validate --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. 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."
+    "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. /roadmap-maintain now owns only existing managed roadmap blocks, while /roadmap-update is the conservative annotation path for authored roadmaps without markers. /roadmap-zero can consume a complete discovery brief from config plus CLI flags in non-interactive environments. 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.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
-      "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for Zero Mode, including non-interactive config-plus-flag discovery.",
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
-      "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for conservative managed-block maintenance plus sync and audit output.",
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     },
     {
       "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.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
-      "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.33"
+      "description": "Native slash entrypoint for evidence-backed inline annotation refresh and verified single-task completion.",
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.33"
+      "version": "0.9.36"
     }
   ]
 }

package/src/config.js

@@ -30,6 +30,9 @@ const DEFAULT_CONFIG = {
     constraints: [],
     doneCriteria: []
   },
+  scan: {
+    excludeDirs: []
+  },
   validation: {
     minimumConfidence: 'low',
     testReports: [],
@@ -95,6 +98,11 @@ function mergeConfig(userConfig) {
         ? userConfig.zeroMode.doneCriteria
         : DEFAULT_CONFIG.zeroMode.doneCriteria
     },
+    scan: {
+      excludeDirs: Array.isArray(userConfig && userConfig.scan && userConfig.scan.excludeDirs)
+        ? userConfig.scan.excludeDirs
+        : DEFAULT_CONFIG.scan.excludeDirs
+    },
     validation: {
       ...DEFAULT_CONFIG.validation,
       ...((userConfig && userConfig.validation) || {}),

package/src/io.js

@@ -12,6 +12,16 @@ const DEFAULT_IGNORED_DIRS = new Set([
   '.nuxt',
   '.turbo',
   '.cache',
+  '.open-next',
+  '.vercel',
+  '.svelte-kit',
+  '.parcel-cache',
+  '.angular',
+  '.expo',
+  '.serverless',
+  '.wrangler',
+  '.tmp',
+  'tmp',
   'dist',
   'dist-electron',
   'build',
@@ -68,7 +78,10 @@ function writeText(filePath, content, options = {}) {
 }
 
 function walkFiles(rootPath, options = {}) {
-  const ignoredDirs = options.ignoredDirs || DEFAULT_IGNORED_DIRS;
+  let ignoredDirs = options.ignoredDirs || DEFAULT_IGNORED_DIRS;
+  if (Array.isArray(options.extraIgnoredDirs) && options.extraIgnoredDirs.length > 0) {
+    ignoredDirs = new Set([...ignoredDirs, ...options.extraIgnoredDirs]);
+  }
   const result = [];
 
   function walk(current) {

package/src/parser/index.js

@@ -147,6 +147,10 @@ function parseRoadmap(content) {
 
     const { indent, checked, text, markerId, markerFlags } = taskLine;
     const noTest = /\brs:no-test\b/i.test(markerFlags);
+    const kindMatch = markerFlags.match(/\brs:kind=(\S+)/i);
+    const taskKind = kindMatch ? kindMatch[1].toLowerCase() : null;
+    const verifiedByMatch = markerFlags.match(/\brs:verified-by=(\S+)/i);
+    const taskVerifiedBy = verifiedByMatch ? verifiedByMatch[1].toLowerCase() : null;
     const taskIndentWidth = getIndentWidth(indent);
 
     let warningLineIndex = null;
@@ -243,6 +247,8 @@ function parseRoadmap(content) {
       blockedByIds,
       markerId,
       noTest,
+      kind: taskKind,
+      verifiedBy: taskVerifiedBy,
       indent,
       section
     });

package/src/sync/index.js

@@ -139,6 +139,13 @@ function applySync(content, parsedTasks, results, options) {
   const lines = [...parsed.lines];
   const tasks = parsedTasks || parsed.tasks;
 
+  const changes = {
+    newlyUnchecked: [],
+    newlyChecked: [],
+    warningsAdded: [],
+    warningsRemoved: []
+  };
+
   let offset = 0;
   for (const task of tasks) {
     const result = results[task.id];
@@ -151,7 +158,13 @@ function applySync(content, parsedTasks, results, options) {
       continue;
     }
 
+    const wasChecked = task.checked;
     lines[lineIndex] = setChecklistState(lines[lineIndex], result.passed);
+    if (wasChecked && !result.passed) {
+      changes.newlyUnchecked.push(task.id);
+    } else if (!wasChecked && result.passed) {
+      changes.newlyChecked.push(task.id);
+    }
 
     const reason = normalizeWarningReasons(result.reasons).join('; ');
     const warningText = formatWarning(task.indent || '', reason || 'validation failed', result.attempted);
@@ -198,6 +211,7 @@ function applySync(content, parsedTasks, results, options) {
     } else {
       lines.splice(lastChildLineIndex + 1, 0, warningText);
       offset += 1;
+      changes.warningsAdded.push(task.id);
     }
 
     const recipeIndex = findVerificationRecipeIndex(lines, lineIndex);
@@ -218,7 +232,7 @@ function applySync(content, parsedTasks, results, options) {
     }
   }
 
-  return ensureTrailingNewline(lines.join('\n'));
+  return { content: ensureTrailingNewline(lines.join('\n')), changes };
 }
 
 module.exports = {

package/src/validator/index.js

@@ -13,7 +13,11 @@ const CODE_EXTENSIONS = new Set([
 ]);
 const TRANSLATION_DIR_SEGMENTS = ['locale', 'locales', 'i18n', 'translations'];
 const DEFAULT_EXCLUDED_PATH_PREFIXES = ['.claude/', '.agent/', 'roadmap-skill/'];
-const GENERATED_OUTPUT_PREFIXES = ['dist-electron/', 'dist/', 'build/', 'out/', '.next/', 'coverage/'];
+const GENERATED_OUTPUT_PREFIXES = [
+  'dist-electron/', 'dist/', 'build/', 'out/', '.next/', 'coverage/',
+  '.open-next/', '.vercel/', '.svelte-kit/', '.parcel-cache/', '.angular/',
+  '.expo/', '.serverless/', '.wrangler/', '.tmp/', 'tmp/'
+];
 const AUXILIARY_HEURISTIC_PATH_SEGMENTS = new Set(['scripts', 'tools', 'tooling', 'demo', 'demos']);
 
 // "docs" omitted from DOC_HINTS — it is a path prefix in scan tasks, not a doc-authoring keyword.
@@ -246,6 +250,7 @@ function readFileIndex(projectRoot, files, config) {
     if (SELF_REFERENTIAL_FILES.has(relativePath)) continue;
     if (isFixturePath(relativePath)) continue;
     if (shouldExcludeByDefaultPath(relativePath, config)) continue;
+    if (isGeneratedOutputPath(relativePath)) continue;
 
     const absolutePath = path.resolve(projectRoot, relativePath);
     const ext = path.extname(relativePath).toLowerCase();
@@ -1774,7 +1779,10 @@ function evaluateDeterministicVerification(task, context) {
 }
 
 function buildValidationContext(projectRoot, config, plugins, options = {}) {
-  const files = walkFiles(projectRoot);
+  const userExcludeDirs = Array.isArray(config && config.scan && config.scan.excludeDirs)
+    ? config.scan.excludeDirs
+    : [];
+  const files = walkFiles(projectRoot, { extraIgnoredDirs: userExcludeDirs });
   const fileIndex = readFileIndex(projectRoot, files, config);
   const testFrameworks = detectTestFrameworks(projectRoot, files);
   const pathHintResolver = buildPathHintResolver(fileIndex);
@@ -1852,6 +1860,39 @@ function buildDiscoveredEvidenceLine(evidence) {
 }
 
 function validateTask(task, context, config, plugins) {
+  if (task.verifiedBy === 'human') {
+    const hasEvidenceLine = Array.isArray(task.evidenceLines) &&
+      task.evidenceLines.some((e) => e.text && e.text.trim().length > 0);
+    if (!hasEvidenceLine) {
+      return {
+        passed: false,
+        confidence: 'low',
+        attempted: false,
+        reasons: ['human-verified tasks require an Evidence: child line'],
+        evidence: { code: false, test: false, artifact: false, files: [], codeFiles: [], testFiles: [], weakPathFiles: [], weakPathContentTokens: [], artifactFiles: [], heuristicArtifacts: [], symbols: [], structuralEvidence: null, authoritative: false, authoritativeFiles: [], authoritativeSummaries: [] },
+        diagnostics: [],
+        verificationRecipe: null,
+        staleEvidenceDetected: false,
+        staleEvidenceResolved: false,
+        generatedTestEvidence: null
+      };
+    }
+    const evidenceText = task.evidenceLines[0].text;
+    return {
+      passed: true,
+      confidence: 'medium',
+      attempted: true,
+      reasons: [],
+      evidence: { code: false, test: false, artifact: false, files: [], codeFiles: [], testFiles: [], weakPathFiles: [], weakPathContentTokens: [], artifactFiles: [], heuristicArtifacts: [], symbols: [], structuralEvidence: null, authoritative: true, authoritativeFiles: [], authoritativeSummaries: [evidenceText] },
+      diagnostics: [],
+      verificationRecipe: null,
+      staleEvidenceDetected: false,
+      staleEvidenceResolved: false,
+      generatedTestEvidence: null,
+      humanVerified: true
+    };
+  }
+
   const {
     paths: pathHints,
     externalPaths,
@@ -1943,6 +1984,7 @@ function validateTask(task, context, config, plugins) {
 
   const requiresTest =
     !task.noTest &&
+    task.kind !== 'docs' &&
     context.testFrameworks.length > 0 &&
     isCodeTask(task.text) &&
     !isDocTask(task.text) &&
@@ -2010,6 +2052,7 @@ function validateTask(task, context, config, plugins) {
   // Only pure path hints (not line-reference hints like file.ts:169) count as direct evidence.
   const hasDirectReferencePass = filesFromPurePathHints.length > 0 || filesFromSymbols.length > 0;
   const hasArtifactTaskPass = evidence.artifact && (
+    task.kind === 'docs' ||
     isDocTask(task.text) ||
     evidence.heuristicArtifacts.length > 0 ||
     filesFromPaths.some((relativePath) => !CODE_EXTENSIONS.has(path.extname(relativePath).toLowerCase()))
@@ -2226,17 +2269,23 @@ function validateTasks(tasks, context, config, plugins) {
   return result;
 }
 
-function auditValidation(tasks, results) {
+function auditValidation(tasks, results, changes) {
   const checkedWithoutEvidence = [];
   const readyButUnchecked = [];
   const checkedWithWeakEvidence = [];
   const documentationOnlyEvidenceForImplementation = [];
   const checkedWithNoStructuralEvidence = [];
+  const humanVerifiedTasks = [];
+  const newlyUnchecked = Array.isArray(changes && changes.newlyUnchecked) ? changes.newlyUnchecked : [];
 
   for (const task of tasks) {
     const result = results[task.id];
     if (!result) continue;
 
+    if (result.humanVerified) {
+      humanVerifiedTasks.push({ task, result });
+    }
+
     if (task.checked && !result.passed) {
       checkedWithoutEvidence.push({ task, result });
     }
@@ -2265,6 +2314,8 @@ function auditValidation(tasks, results) {
     checkedWithWeakEvidence,
     documentationOnlyEvidenceForImplementation,
     checkedWithNoStructuralEvidence,
+    humanVerifiedTasks,
+    newlyUnchecked
   };
 }
 

package/src/zero.js

@@ -2,6 +2,17 @@
 
 const path = require('path');
 
+const ZERO_MODE_FLAG_SPECS = {
+  productName: { flag: '--product-name', configPath: 'product.name', type: 'scalar' },
+  primaryUser: { flag: '--primary-user', configPath: 'product.primaryUser', type: 'scalar', required: true },
+  problemStatement: { flag: '--problem-statement', configPath: 'zeroMode.problemStatement', type: 'scalar', required: true },
+  targetOutcome: { flag: '--target-outcome', configPath: 'product.targetOutcome', type: 'scalar', required: true },
+  antiGoals: { flag: '--anti-goal', configPath: 'product.antiGoals', type: 'list' },
+  preferredStack: { flag: '--preferred-stack', configPath: 'zeroMode.preferredStack', type: 'scalar' },
+  constraints: { flag: '--constraint', configPath: 'zeroMode.constraints', type: 'list' },
+  doneCriteria: { flag: '--done-criterion', configPath: 'zeroMode.doneCriteria', type: 'list', required: true }
+};
+
 const ZERO_MODE_QUESTIONS = [
   { id: 'productName', prompt: '1. What product are we building?' },
   { id: 'primaryUser', prompt: '2. Who is the target user?' },
@@ -54,6 +65,80 @@ function buildZeroModeDefaults(projectRoot, config) {
   };
 }
 
+function getSingleFlagValue(value) {
+  if (Array.isArray(value)) {
+    return value[value.length - 1];
+  }
+  return value;
+}
+
+function getListFlagValues(value) {
+  const rawValues = Array.isArray(value) ? value : [value];
+  return rawValues.flatMap((item) => splitListAnswer(item));
+}
+
+function resolveZeroModeAnswers(projectRoot, config, flags = {}) {
+  const defaults = buildZeroModeDefaults(projectRoot, config);
+  const answers = { ...defaults };
+
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    const flagKey = spec.flag.slice(2);
+    if (!Object.prototype.hasOwnProperty.call(flags, flagKey)) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      answers[field] = getListFlagValues(flags[flagKey]).join('; ');
+      continue;
+    }
+
+    const raw = getSingleFlagValue(flags[flagKey]);
+    answers[field] = String(raw == null ? '' : raw).trim();
+  }
+
+  if (!String(answers.productName || '').trim()) {
+    answers.productName = path.basename(projectRoot);
+  }
+
+  return answers;
+}
+
+function getMissingZeroModeFields(answers = {}) {
+  const missing = [];
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    if (!spec.required) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      if (splitListAnswer(answers[field]).length === 0) {
+        missing.push({
+          field,
+          flag: spec.flag,
+          configPath: spec.configPath
+        });
+      }
+      continue;
+    }
+
+    if (!String(answers[field] || '').trim()) {
+      missing.push({
+        field,
+        flag: spec.flag,
+        configPath: spec.configPath
+      });
+    }
+  }
+  return missing;
+}
+
+function formatMissingZeroModeFields(missingFields) {
+  return missingFields.map((item) => {
+    const label = item.field.replace(/([A-Z])/g, ' $1').toLowerCase();
+    return `${label} (${item.flag} or config ${item.configPath})`;
+  });
+}
+
 async function collectZeroModeAnswers(ask, defaults = {}) {
   const answers = {};
   for (const question of ZERO_MODE_QUESTIONS) {
@@ -124,6 +209,9 @@ module.exports = {
   buildZeroModeConfigPatch,
   buildZeroModeDefaults,
   collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
   isInteractiveTerminal,
+  resolveZeroModeAnswers,
   splitListAnswer
 };