roadmapsmith 0.9.13 → 0.9.15

package/src/index.js

@@ -6,6 +6,9 @@ module.exports = {
   sync: require('./sync'),
   validator: require('./validator'),
   config: require('./config'),
+  host: require('./host'),
+  slash: require('./slash'),
+  zero: require('./zero'),
   model: require('./model'),
   renderer: require('./renderer')
 };

package/src/renderer/professional.js

@@ -238,10 +238,25 @@ const MODULE_METADATA = {
       { text: 'Tune similarity threshold to reduce false-positive merges', priority: 'P0', id: 'prof-mat-match-tune-similarity-threshold' }
     ]
   },
+  sync: {
+    state: 'Applies validation outcomes to ROADMAP.md and can append warning lines for failed attempts.',
+    tasks: [
+      { text: 'Define explicit contract for sync, sync --audit, and future promote-only flows', priority: 'P0', id: 'prof-mat-sync-define-command-contract' },
+      { text: 'Separate mutating sync behavior from future read-only audit mode', priority: 'P0', id: 'prof-mat-sync-separate-mutation-from-read-only-audit' },
+      { text: 'Expose weak-evidence, documentation-only, and structural-mismatch findings in audit output', priority: 'P1', id: 'prof-mat-sync-expose-rich-audit-findings' },
+      { text: 'Claude PostToolUse hook must invoke the CLI without relying on bare "node" in PATH', priority: 'P0', id: 'prof-mat-sync-claude-hook-avoid-bare-node-path' },
+      { text: 'Claude PostToolUse hook must fail visibly when sync execution fails', priority: 'P0', id: 'prof-mat-sync-claude-hook-fail-visibly-on-sync-error' },
+      { text: 'Claude PostToolUse hook must keep lock-file cleanup on both success and failure', priority: 'P1', id: 'prof-mat-sync-claude-hook-cleanup-lockfile-on-both-paths' },
+      { text: 'Differentiate write-time hook sync from commit-time pre-commit sync in the command contract', priority: 'P1', id: 'prof-mat-sync-differentiate-write-time-and-pre-commit-sync' }
+    ]
+  },
   config: {
     state: 'Supports roadmapProfile, product block, milestones, phaseTemplates, plugins.',
     tasks: [
-      { text: 'Add JSON schema validation for roadmap-skill.config.json', priority: 'P1', id: 'prof-mat-config-json-schema-validation' }
+      { text: 'Add JSON schema validation for roadmap-skill.config.json', priority: 'P1', id: 'prof-mat-config-json-schema-validation' },
+      { text: 'Add init --professional or init --with-config bootstrap flow', priority: 'P0', id: 'prof-mat-config-add-init-with-config-bootstrap-flow' },
+      { text: 'Honor versioned roadmap config instead of regenerating from defaults', priority: 'P1', id: 'prof-mat-config-honor-versioned-config-before-defaults' },
+      { text: 'Define manual-to-managed migration flow and drift warnings between skill and CLI guidance', priority: 'P1', id: 'prof-mat-config-define-manual-to-managed-migration-and-drift-warnings' }
     ]
   },
   io: {
@@ -298,7 +313,12 @@ function renderSection7OutputContract(model, lines) {
   lines.push('');
   const formatItems = [
     { text: 'Define stable public output format (stdout, files, exit codes)', priority: 'P0' },
-    { text: 'Version output format alongside package version', priority: 'P1' }
+    { text: 'Version output format alongside package version', priority: 'P1' },
+    { text: 'Define explicit contract for sync, sync --audit, and future promote-only flows', priority: 'P0' },
+    { text: 'Document current gap: sync --audit is not yet a dedicated read-only audit command', priority: 'P1' },
+    { text: 'Add machine-readable audit output (JSON)', priority: 'P1' },
+    { text: 'Add audit summary-only output mode', priority: 'P1' },
+    { text: 'Define explicit exit-code semantics for sync and audit commands', priority: 'P0' }
   ];
   for (const item of formatItems) {
     const id = `prof-out-${slugify(item.text)}`;
@@ -310,7 +330,9 @@ function renderSection7OutputContract(model, lines) {
   lines.push('');
   const breakingItems = [
     { text: 'Document breaking vs. non-breaking output changes', priority: 'P1' },
-    { text: 'Add output schema validation to CI', priority: 'P1' }
+    { text: 'Add output schema validation to CI', priority: 'P1' },
+    { text: 'Separate mutating sync behavior from future read-only audit mode', priority: 'P0' },
+    { text: 'Expose weak-evidence, documentation-only, and structural-mismatch findings in audit output', priority: 'P1' }
   ];
   for (const item of breakingItems) {
     const id = `prof-out-${slugify(item.text)}`;
@@ -329,7 +351,13 @@ function renderSection8Testing(model, lines) {
     { text: 'Unit test coverage for all core modules', priority: 'P0' },
     { text: 'Integration tests covering the full generate → sync → validate pipeline', priority: 'P0' },
     { text: 'Regression fixtures for compact and professional profile output', priority: 'P1' },
-    { text: 'Edge case coverage: empty repo, no config, large monorepo scan', priority: 'P1' }
+    { text: 'Edge case coverage: empty repo, no config, large monorepo scan', priority: 'P1' },
+    { text: 'Add direct tests for .claude/hooks/roadmap-sync.js payload parsing', priority: 'P1' },
+    { text: 'Add direct tests for ROADMAP.md self-edit skip behavior', priority: 'P1' },
+    { text: 'Add direct tests for lock-file reentry guard', priority: 'P1' },
+    { text: 'Add direct tests for sync failure surfacing when the child process cannot be spawned', priority: 'P0' },
+    { text: 'Add regression coverage for environments where node is not available on PATH', priority: 'P0' },
+    { text: 'Add integration coverage for pre-commit sync using the absolute Node path', priority: 'P1' }
   ];
   for (const item of coverageItems) {
     const id = `prof-test-${slugify(item.text)}`;
@@ -389,7 +417,18 @@ function renderSection10Documentation(model, lines) {
   const coreItems = [
     { text: 'README.md covers install, commands, and profile selection', priority: 'P0' },
     { text: 'SKILL.md reflects current feature set and guardrails', priority: 'P0' },
-    { text: 'CHANGELOG.md maintained for each release', priority: 'P1' }
+    { text: 'CHANGELOG.md maintained for each release', priority: 'P1' },
+    { text: 'README.md documents current sync --audit semantics without claiming read-only behavior', priority: 'P0' },
+    { text: 'README.md includes host matrix for Claude Code, Codex/Codex CLI, CI, and manual workflows', priority: 'P1' },
+    { text: 'Document distinction between supported Claude hooks and manual workflows on other hosts', priority: 'P1' },
+    { text: 'Document Codex/Codex CLI manual fallback workflow', priority: 'P1' },
+    { text: 'Document Windows shell caveats: roadmapsmith.cmd, npm.cmd, and PowerShell policy differences', priority: 'P1' },
+    { text: 'Skill instructions require extending existing phases before adding new ones', priority: 'P1' },
+    { text: 'Document that Claude write-time autoupdate currently depends on Node resolution in the hook environment', priority: 'P1' },
+    { text: 'Document the difference between the Claude PostToolUse hook and the git pre-commit hook', priority: 'P1' },
+    { text: 'Document current autoupdate reliability boundaries: write-time hook is best-effort, pre-commit is stricter', priority: 'P1' },
+    { text: 'Document troubleshooting for hook failure when node is missing from PATH', priority: 'P1' },
+    { text: 'Document that Codex/Codex CLI remains manual and does not share the Claude repo-local hook path', priority: 'P1' }
   ];
   for (const item of coreItems) {
     const id = `prof-doc-${slugify(item.text)}`;

package/src/slash.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const SLASH_ACTIONS = [
+  {
+    id: 'zero',
+    description: 'Interview the developer in terminal and generate the first roadmap for an empty or low-context repo.',
+    classicCliExample: 'roadmapsmith zero',
+    slashExamples: ['/zero', '/road zero', '/roadmap-sync zero'],
+    taskLabel: 'RoadmapSmith: Zero Mode'
+  },
+  {
+    id: 'maintain',
+    description: 'Regenerate, sync, and audit the roadmap for an existing repository.',
+    classicCliExample: 'roadmapsmith maintain',
+    slashExamples: ['/maintain', '/road maintain', '/roadmap-sync maintain'],
+    taskLabel: 'RoadmapSmith: Maintain'
+  },
+  {
+    id: 'status',
+    description: 'Inspect CLI, roadmap, VS Code task, and Claude hook readiness.',
+    classicCliExample: 'roadmapsmith doctor --json',
+    slashExamples: ['/status', '/road status', '/roadmap-sync status'],
+    taskLabel: 'RoadmapSmith: Status'
+  },
+  {
+    id: 'init',
+    description: 'Create ROADMAP.md and AGENTS.md when they are missing.',
+    classicCliExample: 'roadmapsmith init',
+    slashExamples: ['/init', '/road init', '/roadmap-sync init'],
+    taskLabel: 'RoadmapSmith: Init'
+  },
+  {
+    id: 'generate',
+    description: 'Rebuild the managed roadmap block from repository context.',
+    classicCliExample: 'roadmapsmith generate --project-root .',
+    slashExamples: ['/generate', '/road generate', '/roadmap-sync generate'],
+    taskLabel: 'RoadmapSmith: Generate'
+  },
+  {
+    id: 'validate',
+    description: 'Inspect per-task evidence status as JSON.',
+    classicCliExample: 'roadmapsmith validate --json --project-root .',
+    slashExamples: ['/validate', '/road validate', '/roadmap-sync validate'],
+    taskLabel: 'RoadmapSmith: Validate'
+  },
+  {
+    id: 'sync',
+    description: 'Apply evidence-backed checklist sync to ROADMAP.md.',
+    classicCliExample: 'roadmapsmith sync --project-root .',
+    slashExamples: ['/sync', '/road sync', '/roadmap-sync sync'],
+    taskLabel: 'RoadmapSmith: Sync'
+  },
+  {
+    id: 'audit',
+    description: 'Run sync and print the post-sync mismatch summary.',
+    classicCliExample: 'roadmapsmith sync --audit --project-root .',
+    slashExamples: ['/audit', '/road audit', '/roadmap-sync audit'],
+    taskLabel: 'RoadmapSmith: Sync Audit'
+  },
+  {
+    id: 'setup',
+    description: 'Generate visible VS Code tasks and optional Claude hook wiring.',
+    classicCliExample: 'roadmapsmith setup',
+    slashExamples: ['/setup', '/road setup', '/roadmap-sync setup'],
+    taskLabel: 'RoadmapSmith: Refresh Setup'
+  }
+];
+
+const SLASH_ROOT_ALIASES = new Set(['/road', '/roadmap-sync']);
+
+const DIRECT_SLASH_ALIAS_TO_ACTION = Object.freeze({
+  '/zero': 'zero',
+  '/maintain': 'maintain',
+  '/status': 'status',
+  '/init': 'init',
+  '/generate': 'generate',
+  '/validate': 'validate',
+  '/sync': 'sync',
+  '/audit': 'audit',
+  '/setup': 'setup'
+});
+
+function normalizeActionId(value) {
+  return String(value || '').trim().toLowerCase().replace(/^\/+/, '');
+}
+
+function isSlashToken(value) {
+  return typeof value === 'string' && value.trim().startsWith('/');
+}
+
+function getSlashAction(actionId) {
+  const normalized = normalizeActionId(actionId);
+  return SLASH_ACTIONS.find((action) => action.id === normalized) || null;
+}
+
+function getSlashActionSpecs() {
+  return SLASH_ACTIONS.map((action) => ({ ...action }));
+}
+
+function getSlashSuggestions(query) {
+  const normalized = normalizeActionId(query);
+  if (!normalized) {
+    return getSlashActionSpecs();
+  }
+
+  const startsWithMatches = SLASH_ACTIONS.filter((action) => action.id.startsWith(normalized));
+  const containsMatches = SLASH_ACTIONS.filter((action) => {
+    return !action.id.startsWith(normalized) && action.id.includes(normalized);
+  });
+
+  return [...startsWithMatches, ...containsMatches].map((action) => ({ ...action }));
+}
+
+function resolveSlashInvocation(command, args = []) {
+  if (!isSlashToken(command)) {
+    return null;
+  }
+
+  const normalizedCommand = String(command).trim().toLowerCase();
+
+  if (Object.prototype.hasOwnProperty.call(DIRECT_SLASH_ALIAS_TO_ACTION, normalizedCommand)) {
+    return {
+      kind: 'execute',
+      actionId: DIRECT_SLASH_ALIAS_TO_ACTION[normalizedCommand],
+      query: normalizeActionId(normalizedCommand),
+      source: normalizedCommand,
+      suggestions: getSlashSuggestions(normalizedCommand)
+    };
+  }
+
+  if (SLASH_ROOT_ALIASES.has(normalizedCommand)) {
+    const queryToken = args.length > 0 ? normalizeActionId(args[0]) : '';
+    if (!queryToken) {
+      return {
+        kind: 'palette',
+        query: '',
+        source: normalizedCommand,
+        suggestions: getSlashSuggestions('')
+      };
+    }
+
+    const exactAction = getSlashAction(queryToken);
+    if (exactAction) {
+      return {
+        kind: 'execute',
+        actionId: exactAction.id,
+        query: queryToken,
+        source: normalizedCommand,
+        suggestions: getSlashSuggestions(queryToken)
+      };
+    }
+
+    return {
+      kind: 'palette',
+      query: queryToken,
+      source: normalizedCommand,
+      suggestions: getSlashSuggestions(queryToken)
+    };
+  }
+
+  return {
+    kind: 'palette',
+    query: normalizeActionId(normalizedCommand),
+    source: normalizedCommand,
+    suggestions: getSlashSuggestions(normalizedCommand)
+  };
+}
+
+function renderSlashPalette(options = {}) {
+  const source = options.source || '/road';
+  const query = normalizeActionId(options.query);
+  const suggestions = Array.isArray(options.suggestions) ? options.suggestions : getSlashSuggestions(query);
+  const lines = [];
+
+  lines.push('RoadmapSmith slash palette');
+  lines.push('');
+
+  if (query) {
+    lines.push(`Input: ${source} ${query}`);
+    if (suggestions.length > 0) {
+      lines.push('No exact slash match was executed. Related actions:');
+    } else {
+      lines.push('No exact slash match was executed.');
+    }
+  } else {
+    lines.push(`Entry point: ${source}`);
+    lines.push('Use an exact slash action to execute work. Incomplete or ambiguous input only shows suggestions.');
+  }
+
+  lines.push('');
+
+  if (suggestions.length === 0) {
+    lines.push('No related slash actions found.');
+  } else {
+    suggestions.forEach((action) => {
+      lines.push(`- /${action.id}: ${action.description}`);
+      lines.push(`  Classic CLI: ${action.classicCliExample}`);
+      lines.push(`  Skill form: /roadmap-sync ${action.id}`);
+      lines.push(`  VS Code task: ${action.taskLabel}`);
+    });
+  }
+
+  lines.push('');
+  lines.push('Examples:');
+  lines.push('- roadmapsmith zero');
+  lines.push('- roadmapsmith maintain');
+  lines.push('- roadmapsmith /road');
+  lines.push('- roadmapsmith /maintain');
+  lines.push('- roadmapsmith /roadmap-sync maintain');
+  lines.push('');
+  lines.push('Installing the skill alone does not expose CLI behavior in VS Code. Use roadmapsmith setup for the visible task/launcher layer.');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  DIRECT_SLASH_ALIAS_TO_ACTION,
+  SLASH_ROOT_ALIASES,
+  getSlashAction,
+  getSlashActionSpecs,
+  getSlashSuggestions,
+  isSlashToken,
+  normalizeActionId,
+  renderSlashPalette,
+  resolveSlashInvocation
+};

package/src/zero.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const path = require('path');
+
+const ZERO_MODE_QUESTIONS = [
+  { id: 'productName', prompt: '1. What product are we building?' },
+  { id: 'primaryUser', prompt: '2. Who is the target user?' },
+  { id: 'problemStatement', prompt: '3. What problem does it solve?' },
+  { id: 'targetOutcome', prompt: '4. What is the desired v1.0 outcome?' },
+  { id: 'antiGoals', prompt: '5. What is explicitly out of scope? Separate multiple items with ;' },
+  { id: 'preferredStack', prompt: '6. What stack do you prefer, if any?' },
+  { id: 'constraints', prompt: '7. What constraints exist? Separate multiple items with ;' },
+  { id: 'doneCriteria', prompt: '8. What does "done" mean for the first usable version? Separate multiple items with ;' }
+];
+
+function splitListAnswer(value) {
+  return String(value || '')
+    .split(/(?:\r?\n|;)+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function joinListDefault(values) {
+  return Array.isArray(values) && values.length > 0 ? values.join('; ') : '';
+}
+
+function deriveDefaultProblemStatement(config) {
+  const explicit = config.zeroMode && config.zeroMode.problemStatement;
+  if (explicit) {
+    return explicit;
+  }
+  const positioning = String((config.product && config.product.positioning) || '').trim();
+  const prefix = 'Core problem: ';
+  if (positioning.startsWith(prefix)) {
+    return positioning.slice(prefix.length).trim();
+  }
+  return '';
+}
+
+function buildZeroModeDefaults(projectRoot, config) {
+  return {
+    productName: (config.product && config.product.name) || path.basename(projectRoot),
+    primaryUser: (config.product && config.product.primaryUser) || '',
+    problemStatement: deriveDefaultProblemStatement(config),
+    targetOutcome: (config.product && config.product.targetOutcome) || '',
+    antiGoals: joinListDefault(config.product && config.product.antiGoals),
+    preferredStack: (config.zeroMode && config.zeroMode.preferredStack) || '',
+    constraints: joinListDefault(config.zeroMode && config.zeroMode.constraints),
+    doneCriteria: joinListDefault(
+      (config.zeroMode && config.zeroMode.doneCriteria && config.zeroMode.doneCriteria.length > 0)
+        ? config.zeroMode.doneCriteria
+        : (config.product && config.product.successCriteria)
+    )
+  };
+}
+
+async function collectZeroModeAnswers(ask, defaults = {}) {
+  const answers = {};
+  for (const question of ZERO_MODE_QUESTIONS) {
+    const fallback = String(defaults[question.id] || '').trim();
+    const suffix = fallback ? ` [${fallback}]` : '';
+    const response = await ask(`${question.prompt}${suffix}: `);
+    const normalized = String(response || '').trim();
+    answers[question.id] = normalized || fallback;
+  }
+  return answers;
+}
+
+function deriveNorthStar(answers) {
+  const productName = String(answers.productName || '').trim();
+  const primaryUser = String(answers.primaryUser || '').trim();
+  const targetOutcome = String(answers.targetOutcome || '').trim();
+  if (productName && primaryUser && targetOutcome) {
+    return `${productName} helps ${primaryUser} achieve ${targetOutcome}.`;
+  }
+  if (productName && targetOutcome) {
+    return `${productName} exists to deliver ${targetOutcome}.`;
+  }
+  if (productName) {
+    return `Ship the first usable version of ${productName}.`;
+  }
+  return '';
+}
+
+function buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers) {
+  const productName = String(answers.productName || '').trim() || path.basename(projectRoot);
+  const primaryUser = String(answers.primaryUser || '').trim();
+  const problemStatement = String(answers.problemStatement || '').trim();
+  const targetOutcome = String(answers.targetOutcome || '').trim();
+  const antiGoals = splitListAnswer(answers.antiGoals);
+  const constraints = splitListAnswer(answers.constraints);
+  const doneCriteria = splitListAnswer(answers.doneCriteria);
+  const preferredStack = String(answers.preferredStack || '').trim();
+
+  return {
+    ...existingUserConfig,
+    product: {
+      ...((existingUserConfig && existingUserConfig.product) || {}),
+      name: productName,
+      northStar: deriveNorthStar({ productName, primaryUser, targetOutcome }) || (((existingUserConfig || {}).product || {}).northStar || ''),
+      positioning: problemStatement ? `Core problem: ${problemStatement}` : ((((existingUserConfig || {}).product || {}).positioning) || ''),
+      primaryUser,
+      targetOutcome,
+      antiGoals,
+      risks: constraints.map((constraint) => `Constraint: ${constraint}`),
+      successCriteria: doneCriteria
+    },
+    zeroMode: {
+      ...((existingUserConfig && existingUserConfig.zeroMode) || {}),
+      problemStatement,
+      preferredStack,
+      constraints,
+      doneCriteria
+    }
+  };
+}
+
+function isInteractiveTerminal(input = process.stdin, output = process.stdout) {
+  return Boolean(input && input.isTTY && output && output.isTTY);
+}
+
+module.exports = {
+  ZERO_MODE_QUESTIONS,
+  buildZeroModeConfigPatch,
+  buildZeroModeDefaults,
+  collectZeroModeAnswers,
+  isInteractiveTerminal,
+  splitListAnswer
+};