roadmapsmith 0.9.16 → 0.9.23

package/skills/roadmap-validate/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: roadmap-validate
+description: Inspect evidence-backed roadmap validation through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Validate
+
+Use this command when the user wants per-task evidence status without mutating the roadmap.
+
+## Required behavior
+
+1. Prefer the local engine inside this repository:
+   - `node roadmap-skill/bin/cli.js validate --json --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js validate --json --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith validate --json --project-root .`.
+3. Treat this command as CLI-backed and non-mutating.

package/skills/roadmap-zero/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: roadmap-zero
+description: Run the one-command Zero Mode workflow through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Zero
+
+Use this command when the repository is empty or low-context and the user needs the discovery interview plus first roadmap generation.
+
+## Required behavior
+
+1. Prefer the local engine inside this repository:
+   - `node roadmap-skill/bin/cli.js zero --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js zero --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith zero --project-root .`.
+3. Treat this command as CLI-backed and interactive.
+4. If the CLI is missing, explain the install path instead of improvising the workflow manually.

package/skills.json

@@ -0,0 +1,95 @@
+{
+  "name": "roadmapsmith",
+  "description": "One-command roadmap generation and maintenance for coding agents, with a shared native slash bundle for Claude and Codex plus the RoadmapSmith CLI.",
+  "triggers": [
+    "roadmap",
+    "sync roadmap",
+    "validate task completion",
+    "project milestones",
+    "agent roadmap"
+  ],
+  "usageExamples": [
+    "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
+    "npx skills add PapiScholz/roadmapsmith --skill roadmap-sync",
+    "roadmapsmith setup",
+    "roadmapsmith zero",
+    "roadmapsmith maintain",
+    "roadmapsmith /roadmap",
+    "roadmapsmith /roadmap-update",
+    "roadmapsmith validate --json"
+  ],
+  "install": {
+    "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. The legacy /roadmap-sync root remains available for compatibility, especially as /roadmap-sync <action>. Install the roadmapsmith CLI separately for actual command execution, 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.23"
+    },
+    {
+      "name": "roadmap-zero",
+      "path": "skills/roadmap-zero",
+      "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-maintain",
+      "path": "skills/roadmap-maintain",
+      "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-status",
+      "path": "skills/roadmap-status",
+      "description": "Native slash readiness check grounded in roadmapsmith doctor JSON.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-init",
+      "path": "skills/roadmap-init",
+      "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
+      "version": "0.9.23"
+    },
+    {
+      "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.23"
+    },
+    {
+      "name": "roadmap-validate",
+      "path": "skills/roadmap-validate",
+      "description": "Native slash entrypoint for evidence-backed roadmap validation.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-update",
+      "path": "skills/roadmap-update",
+      "description": "Native slash entrypoint for applying evidence-backed checklist sync.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-sync",
+      "path": "skills/roadmap-sync",
+      "description": "Legacy namespaced root plus policy guidance for RoadmapSmith slash workflows.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-audit",
+      "path": "skills/roadmap-audit",
+      "description": "Native slash entrypoint for the current sync-plus-audit workflow.",
+      "version": "0.9.23"
+    },
+    {
+      "name": "roadmap-setup",
+      "path": "skills/roadmap-setup",
+      "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
+      "version": "0.9.23"
+    }
+  ]
+}

package/src/classifier/index.js

@@ -12,7 +12,16 @@ const WEB_CONFIGS = [
 ];
 const STYLE_CONFIGS = ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.cjs'];
 const WEB_DEPS = new Set(['next', 'react', 'vue', 'svelte', 'astro', 'vite', 'nuxt', 'gatsby', 'remix', '@remix-run/react']);
+const ELECTRON_DEPS = new Set(['electron', 'electron-builder', 'electron-forge', '@electron-forge/cli', 'electron-updater']);
+const ELECTRON_CONFIGS = [
+  'electron-builder.json',
+  'electron-builder.yml',
+  'electron-builder.yaml',
+  'forge.config.js',
+  'forge.config.ts'
+];
 const LANDING_ROUTE_RE = /(?:^|\/)(?:contact|services|about|pricing|hero|cta|landing)(?:\/|\.)/i;
+const FIXTURE_PATH_RE = /(^|\/)(?:test|tests)\/fixtures\//i;
 
 function readPackageDeps(projectRoot) {
   if (!projectRoot) return [];
@@ -44,6 +53,9 @@ function hasWorkspaces(projectRoot) {
 }
 
 function classifyProject({ projectRoot, files }) {
+  const candidateFiles = Array.isArray(files)
+    ? files.filter((file) => !FIXTURE_PATH_RE.test(String(file || '')))
+    : [];
   const signals = [];
 
   if (hasWorkspaces(projectRoot)) {
@@ -51,17 +63,22 @@ function classifyProject({ projectRoot, files }) {
     return { type: 'monorepo', confidence: 'high', signals };
   }
 
-  const hasPy = hasFilename(files, 'pyproject.toml') || hasFilename(files, 'setup.py');
-  if (hasPy && !files.some((f) => /\.[jt]sx?$/.test(f))) {
+  const hasPy = hasFilename(candidateFiles, 'pyproject.toml') || hasFilename(candidateFiles, 'setup.py');
+  if (hasPy && !candidateFiles.some((f) => /\.[jt]sx?$/.test(f))) {
     signals.push('pyproject.toml / setup.py, no JS files');
     return { type: 'python-package', confidence: 'high', signals };
   }
 
   let webScore = 0;
   let landingScore = 0;
+  let electronScore = 0;
   const deps = readPackageDeps(projectRoot);
 
   for (const dep of deps) {
+    if (ELECTRON_DEPS.has(dep)) {
+      electronScore += 3;
+      signals.push(`dependency: ${dep}`);
+    }
     if (WEB_DEPS.has(dep)) {
       webScore += 2;
       signals.push(`dependency: ${dep}`);
@@ -69,59 +86,81 @@ function classifyProject({ projectRoot, files }) {
   }
 
   for (const dir of WEB_DIRS) {
-    if (hasDir(files, dir)) {
+    if (hasDir(candidateFiles, dir)) {
       webScore += 2;
       signals.push(`directory: ${dir.replace(/\/$/, '')}`);
     }
   }
 
   for (const dir of ASSET_DIRS) {
-    if (hasDir(files, dir)) {
+    if (hasDir(candidateFiles, dir)) {
       webScore += 1;
       signals.push(`directory: ${dir.replace(/\/$/, '')}`);
     }
   }
 
+  if (hasDir(candidateFiles, 'electron/')) {
+    electronScore += 3;
+    signals.push('directory: electron');
+  }
+
+  if (candidateFiles.some((file) => /^electron\/.+\.(js|ts|cjs|mjs)$/.test(file))) {
+    electronScore += 2;
+    signals.push('electron main/preload sources');
+  }
+
+  for (const cfg of ELECTRON_CONFIGS) {
+    if (hasFilename(candidateFiles, cfg)) {
+      electronScore += 2;
+      signals.push(`config: ${cfg}`);
+    }
+  }
+
   for (const cfg of WEB_CONFIGS) {
-    if (hasFilename(files, cfg)) {
+    if (hasFilename(candidateFiles, cfg)) {
       webScore += 3;
       signals.push(`config: ${cfg}`);
     }
   }
 
   for (const cfg of STYLE_CONFIGS) {
-    if (hasFilename(files, cfg)) {
+    if (hasFilename(candidateFiles, cfg)) {
       webScore += 1;
       signals.push(`config: ${cfg}`);
     }
   }
 
-  if (files.some((f) => /\.css$/.test(f))) {
+  if (candidateFiles.some((f) => /\.css$/.test(f))) {
     webScore += 1;
     signals.push('CSS files present');
   }
 
-  const landingRoutes = files.filter((f) => LANDING_ROUTE_RE.test(f));
+  const landingRoutes = candidateFiles.filter((f) => LANDING_ROUTE_RE.test(f));
   if (landingRoutes.length > 0) {
     landingScore += landingRoutes.length * 2;
     signals.push(`landing/service routes: ${landingRoutes.length}`);
   }
 
-  if (hasFilename(files, 'favicon.ico') || hasFilename(files, 'logo.png') || hasFilename(files, 'logo.svg')) {
+  if (hasFilename(candidateFiles, 'favicon.ico') || hasFilename(candidateFiles, 'logo.png') || hasFilename(candidateFiles, 'logo.svg')) {
     landingScore += 1;
     signals.push('branding asset in public/');
   }
 
-  if (webScore === 0 && (files.some((f) => f.startsWith('bin/')) || hasFilename(files, 'cli.js'))) {
+  if (webScore === 0 && (candidateFiles.some((f) => f.startsWith('bin/')) || hasFilename(candidateFiles, 'cli.js'))) {
     signals.push('bin/ directory or cli.js');
     return { type: 'cli-tool', confidence: 'medium', signals };
   }
 
-  if (webScore === 0 && hasFilename(files, 'package.json')) {
+  if (webScore === 0 && hasFilename(candidateFiles, 'package.json')) {
     signals.push('package.json, no web signals');
     return { type: 'npm-package', confidence: 'low', signals };
   }
 
+  if (electronScore >= 3) {
+    const confidence = electronScore >= 6 ? 'high' : 'medium';
+    return { type: 'electron-app', confidence, signals };
+  }
+
   if (webScore >= 3) {
     const type = landingScore >= 3 ? 'landing-site' : 'frontend-web';
     const confidence = webScore >= 7 ? 'high' : 'medium';

package/src/generator/index.js

@@ -4,8 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const { walkFiles, detectLanguages, detectTestFrameworks, detectWorkspaces } = require('../io');
 const { createRoadmapModel, PHASE_ORDER } = require('../model');
-const { slugify, ensureTrailingNewline } = require('../utils');
-const { parseRoadmap, upsertManagedBlock } = require('../parser');
+const { slugify } = require('../utils');
+const { parseRoadmap, tasksInManagedBlock, upsertManagedBlock } = require('../parser');
 const { findBestTaskMatch, dedupeTasks } = require('../match');
 const { collectPluginContributions } = require('../config');
 const { renderBody } = require('../renderer');
@@ -13,6 +13,8 @@ const { classifyProject } = require('../classifier');
 
 const IMPL_PATTERN_RE = /[/|]TODO|TODO[|/]|[/|]FIXME|FIXME[|/]/;
 const COMMENT_TODO_RE = /(?:\/\/|#|\*\s*).*\b(?:TODO|FIXME)\b/;
+const ADDITIONS_SECTION_TITLE = 'RoadmapSmith Additions';
+const PHASE_LABEL_RE = /`?\[(P[0-2])\]`?/i;
 
 function isTodoMarker(line) {
   return COMMENT_TODO_RE.test(line) && !IMPL_PATTERN_RE.test(line);
@@ -181,6 +183,58 @@ function toCandidate(text, phase, priority, source = 'default') {
   };
 }
 
+function hasSubstantiveManagedBlock(parsedRoadmap) {
+  if (!parsedRoadmap || !parsedRoadmap.managedRange) {
+    return false;
+  }
+
+  const managedLines = parsedRoadmap.lines.slice(
+    parsedRoadmap.managedRange.start + 1,
+    parsedRoadmap.managedRange.end
+  );
+  return managedLines.some((line) => line.trim().length > 0);
+}
+
+function stripTrailingBlankLines(lines) {
+  const next = Array.isArray(lines) ? lines.slice() : [];
+  while (next.length > 0 && !next[next.length - 1].trim()) {
+    next.pop();
+  }
+  return next;
+}
+
+function renderAdditionTask(task) {
+  return `- [ ] ${task.text} <!-- rs:task=${task.id} -->`;
+}
+
+function isGenericPreserveModeCandidate(candidate) {
+  return candidate && ['default', 'classifier', 'todo-hint'].includes(candidate.source);
+}
+
+function buildManagedAdditionsLines(tasks, options = {}) {
+  const groups = groupByPhase(tasks);
+  const lines = [];
+  const includeSectionHeading = options.includeSectionHeading !== false;
+
+  if (includeSectionHeading) {
+    lines.push(`## ${ADDITIONS_SECTION_TITLE}`);
+    lines.push('');
+  }
+
+  for (const phase of PHASE_ORDER) {
+    if (!groups[phase] || groups[phase].length === 0) {
+      continue;
+    }
+    lines.push(`### Phase ${phase}`);
+    for (const task of groups[phase]) {
+      lines.push(renderAdditionTask(task));
+    }
+    lines.push('');
+  }
+
+  return stripTrailingBlankLines(lines);
+}
+
 const WEB_CANDIDATES_COMMON = [
   { text: 'Add SEO metadata: title, description, and canonical URL for all pages', phase: 'P0' },
   { text: 'Implement responsive and mobile-first layout across all breakpoints', phase: 'P0' },
@@ -285,6 +339,9 @@ function applyTaskMatchers(scan, config) {
 }
 
 function inferPhase(existingTask) {
+  const textPhaseMatch = String(existingTask.text || '').match(PHASE_LABEL_RE);
+  if (textPhaseMatch) return textPhaseMatch[1].toUpperCase();
+
   const section = String(existingTask.section || '').toUpperCase();
   if (section.includes('P0')) return 'P0';
   if (section.includes('P1')) return 'P1';
@@ -292,12 +349,138 @@ function inferPhase(existingTask) {
   return 'P1';
 }
 
-function mergeWithExisting(candidates, existingTasks) {
+function sortTasksByPhaseAndText(tasks) {
+  return tasks.slice().sort((left, right) => {
+    const leftPhaseIndex = PHASE_ORDER.indexOf(left.phase);
+    const rightPhaseIndex = PHASE_ORDER.indexOf(right.phase);
+    if (leftPhaseIndex !== rightPhaseIndex) {
+      return leftPhaseIndex - rightPhaseIndex;
+    }
+    return left.text.localeCompare(right.text);
+  });
+}
+
+function findPhaseSectionRange(lines, managedRange, phase) {
+  const headingPattern = /^(#{2,4})\s+(.*)$/;
+  const phasePattern = new RegExp(`\\b${phase}\\b`, 'i');
+  let sectionStart = -1;
+  let sectionLevel = 0;
+
+  for (let index = managedRange.start + 1; index < managedRange.end; index += 1) {
+    const match = lines[index].trim().match(headingPattern);
+    if (!match) {
+      continue;
+    }
+    if (!phasePattern.test(match[2])) {
+      continue;
+    }
+    sectionStart = index;
+    sectionLevel = match[1].length;
+  }
+
+  if (sectionStart < 0) {
+    return null;
+  }
+
+  let sectionEnd = managedRange.end;
+  for (let index = sectionStart + 1; index < managedRange.end; index += 1) {
+    const match = lines[index].trim().match(headingPattern);
+    if (!match) {
+      continue;
+    }
+    if (match[1].length <= sectionLevel) {
+      sectionEnd = index;
+      break;
+    }
+  }
+
+  return {
+    start: sectionStart,
+    end: sectionEnd
+  };
+}
+
+function buildPreserveModeInsertions(parsedRoadmap, tasks) {
+  const managedTasks = sortTasksByPhaseAndText(tasksInManagedBlock(parsedRoadmap));
+  const groups = groupByPhase(tasks);
+  const lines = parsedRoadmap.lines;
+  const insertions = [];
+  const fallbackTasks = [];
+
+  for (const phase of PHASE_ORDER) {
+    const phaseTasks = sortTasksByPhaseAndText(groups[phase] || []);
+    if (phaseTasks.length === 0) {
+      continue;
+    }
+
+    const samePhaseTasks = managedTasks.filter((task) => inferPhase(task) === phase);
+    if (samePhaseTasks.length > 0) {
+      const anchor = samePhaseTasks.reduce((latest, task) => {
+        if (!latest || task.lastChildLineIndex > latest.lastChildLineIndex) {
+          return task;
+        }
+        return latest;
+      }, null);
+      insertions.push({
+        index: anchor.lastChildLineIndex + 1,
+        lines: phaseTasks.map(renderAdditionTask)
+      });
+      continue;
+    }
+
+    const phaseSection = findPhaseSectionRange(lines, parsedRoadmap.managedRange, phase);
+    if (phaseSection) {
+      let insertionIndex = phaseSection.end;
+      while (insertionIndex > phaseSection.start + 1 && !lines[insertionIndex - 1].trim()) {
+        insertionIndex -= 1;
+      }
+      insertions.push({
+        index: insertionIndex,
+        lines: phaseTasks.map(renderAdditionTask)
+      });
+      continue;
+    }
+
+    fallbackTasks.push(...phaseTasks);
+  }
+
+  if (fallbackTasks.length > 0) {
+    const fallbackLines = buildManagedAdditionsLines(fallbackTasks, { includeSectionHeading: true });
+    insertions.push({
+      index: parsedRoadmap.managedRange.end,
+      lines: ['', ...fallbackLines]
+    });
+  }
+
+  return insertions.sort((left, right) => right.index - left.index);
+}
+
+function insertPreserveModeTasks(existingContent, parsedRoadmap, tasks) {
+  if (!parsedRoadmap || !parsedRoadmap.managedRange || tasks.length === 0) {
+    return existingContent;
+  }
+
+  const nextLines = parsedRoadmap.lines.slice();
+  const insertions = buildPreserveModeInsertions(parsedRoadmap, tasks);
+  for (const insertion of insertions) {
+    nextLines.splice(insertion.index, 0, ...insertion.lines);
+  }
+
+  return nextLines.join('\n');
+}
+
+function filterPreserveModeCandidates(candidates) {
+  return candidates.filter((candidate) => !isGenericPreserveModeCandidate(candidate));
+}
+
+function mergeWithExisting(candidates, existingTasks, options = {}) {
   const matchedExistingIds = new Set();
   const merged = [];
 
   for (const candidate of candidates) {
-    const match = findBestTaskMatch(candidate, existingTasks);
+    const match = findBestTaskMatch(candidate, existingTasks, {
+      allowFuzzy: options.allowFuzzy !== false
+    });
     if (match) {
       matchedExistingIds.add(match.task.id);
       merged.push({
@@ -311,20 +494,22 @@ function mergeWithExisting(candidates, existingTasks) {
     merged.push(candidate);
   }
 
-  for (const existing of existingTasks) {
-    if (matchedExistingIds.has(existing.id)) {
-      continue;
-    }
+  if (options.includeUnmatchedExisting) {
+    for (const existing of existingTasks) {
+      if (matchedExistingIds.has(existing.id)) {
+        continue;
+      }
 
-    const phase = inferPhase(existing);
-    merged.push({
-      id: existing.id,
-      text: existing.text,
-      phase,
-      priority: phase,
-      checked: existing.checked,
-      source: 'existing'
-    });
+      const phase = inferPhase(existing);
+      merged.push({
+        id: existing.id,
+        text: existing.text,
+        phase,
+        priority: phase,
+        checked: existing.checked,
+        source: 'existing'
+      });
+    }
   }
 
   return dedupeTasks(merged);
@@ -566,6 +751,8 @@ function generateRoadmapDocument(options) {
   const zeroModeConfig = config.zeroMode || {};
   const plugins = options.plugins || [];
   const existingContent = options.existingContent || '';
+  const preserveManagedBlock = options.preserveManagedBlock === true;
+  const forceFullRegenerate = options.forceFullRegenerate === true;
 
   const scan = scanProject(projectRoot);
   const existing = parseRoadmap(existingContent);
@@ -573,7 +760,7 @@ function generateRoadmapDocument(options) {
   for (const task of existing.tasks) {
     existingCheckedById[task.id] = task.checked;
   }
-  const existingPhaseTasks = existing.tasks.filter((task) => /^Phase P[0-2]/i.test(String(task.section || '')));
+  const existingManagedTasks = tasksInManagedBlock(existing);
 
   const pluginTaskCandidates = collectPluginContributions(plugins, 'registerTaskDetectors', {
     projectRoot,
@@ -627,7 +814,32 @@ function generateRoadmapDocument(options) {
 
   const baseCandidates = buildDefaultCandidates(scan, config);
   const matcherCandidates = applyTaskMatchers(scan, config);
-  const merged = mergeWithExisting([...baseCandidates, ...matcherCandidates, ...pluginTaskCandidates], existingPhaseTasks);
+  const allCandidates = dedupeTasks([...baseCandidates, ...matcherCandidates, ...pluginTaskCandidates]);
+
+  if (hasSubstantiveManagedBlock(existing) && preserveManagedBlock && !forceFullRegenerate) {
+    const unmatchedCandidates = allCandidates.filter((candidate) => {
+      return !findBestTaskMatch(candidate, existingManagedTasks, {
+        allowFuzzy: true,
+        minScore: 0.72
+      });
+    });
+    const preserveModeCandidates = filterPreserveModeCandidates(unmatchedCandidates);
+
+    if (preserveModeCandidates.length === 0) {
+      return existingContent;
+    }
+
+    return insertPreserveModeTasks(existingContent, existing, preserveModeCandidates);
+  }
+
+  if (hasSubstantiveManagedBlock(existing) && !forceFullRegenerate) {
+    throw new Error('Refusing to regenerate a substantive managed roadmap block. Rerun with --full-regen to replace it explicitly.');
+  }
+
+  const merged = mergeWithExisting(allCandidates, existingManagedTasks, {
+    allowFuzzy: true,
+    includeUnmatchedExisting: false
+  });
   const model = createModel(scan, merged, config, [profileSection, ...generatedZeroModeSection, ...configSections, ...pluginSections], existingCheckedById);
   const profile = config.roadmapProfile || 'compact';
   const managedBody = renderBody(model, profile);