roadmapsmith 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# roadmap-skill
+
+Production-grade roadmap generator and sync tool for agent-driven projects.
+
+## Install Status
+
+This package and skill are in private/internal development. Public install flows are not available yet.
+
+### Primary install path: agent skill (available for private repository users)
+
+```bash
+npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
+```
+
+This install command adds the `roadmap-sync` agent skill. It does not install the CLI package.
+
+### Optional CLI package install (future, unavailable until npm publication)
+
+```bash
+npm install -g roadmapsmith
+```
+
+### Local development usage
+
+```bash
+cd roadmap-skill
+node bin/cli.js --help
+node bin/cli.js init --dry-run
+node bin/cli.js generate --project-root . --dry-run --audit
+```
+
+### Legacy/internal alias
+
+The `roadmap-skill` CLI alias remains for backward compatibility and internal use, but public examples use `roadmapsmith`.
+
+## Commands
+
+```bash
+roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]
+roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]
+roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]
+roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]
+```
+
+## Behavior
+
+- Generates deterministic `ROADMAP.md` with fixed section order.
+- Uses stable task IDs: `<!-- rs:task=<slug> -->`.
+- Sync marks `[x]` only when validation passes.
+- Validation evidence gate:
+  - code OR test OR artifact evidence required.
+  - test evidence required for code tasks when test frameworks are detected.
+- Validation failures in sync write warning lines:
+  - `- ⚠️ attempted but validation failed: <reason>`
+- Preserves unmanaged markdown content by updating only the managed roadmap block.
+
+## Defaults
+
+- Roadmap file: `./ROADMAP.md` (falls back to `./roadmap.md` when only the legacy file exists)
+- Agent rules file: `./AGENTS.md` (falls back to `./CLAUDE.md` when present)
+- Config file: `./roadmap-skill.config.json`
+
+Roadmap resolution precedence:
+
+1. `--roadmap-file` CLI flag
+2. `config.roadmapFile` in `roadmap-skill.config.json`
+3. Existing `./ROADMAP.md`
+4. Existing `./roadmap.md` (legacy fallback)
+5. `./ROADMAP.md` when neither file exists
+
+## Config
+
+Create `roadmap-skill.config.json`:
+
+```json
+{
+  "roadmapFile": "./ROADMAP.md",
+  "agentsFile": "./AGENTS.md",
+  "taskMatchers": [
+    {
+      "pattern": "src/payments/",
+      "task": "Complete payment flow hardening",
+      "phase": "P0",
+      "priority": "P0"
+    }
+  ],
+  "validators": [
+    {
+      "type": "file-exists",
+      "when": "migration",
+      "path": "db/migrations"
+    }
+  ],
+  "customSections": [
+    {
+      "title": "Compliance",
+      "items": [
+        "- [ ] Complete SOC2 evidence packet <!-- rs:task=compliance-soc2-evidence -->"
+      ]
+    }
+  ],
+  "plugins": [
+    "./plugins/roadmap.plugin.js"
+  ],
+  "milestones": [
+    { "version": "v0.1", "goal": "Foundation" },
+    { "version": "v0.2", "goal": "Reliability" },
+    { "version": "v0.3", "goal": "Release candidate" },
+    { "version": "v1.0", "goal": "General availability" }
+  ],
+  "phaseTemplates": {
+    "P0": ["Stabilize critical path"],
+    "P1": ["Expand reliability"],
+    "P2": ["Finalize release hardening"]
+  }
+}
+```
+
+## Plugin API
+
+Plugin module path(s) are loaded from `config.plugins` in deterministic order.
+
+```js
+module.exports = {
+  registerTaskDetectors(ctx) {
+    return [
+      { text: 'Implement billing retries', phase: 'P1', priority: 'P1' }
+    ];
+  },
+  registerSectionGenerators(ctx) {
+    return [
+      {
+        title: 'Platform Notes',
+        items: ['- [ ] Verify deployment rollback path <!-- rs:task=verify-deployment-rollback-path -->']
+      }
+    ];
+  },
+  registerValidators(ctx) {
+    return [
+      {
+        type: 'symbol',
+        when: 'billing',
+        pattern: 'retry',
+        message: 'billing retry symbol not found'
+      }
+    ];
+  }
+};
+```
+
+## Example Usage
+
+```bash
+roadmapsmith init
+roadmapsmith generate --project-root .
+roadmapsmith validate --json
+roadmapsmith sync --audit
+roadmapsmith sync --dry-run
+```
+
+## Dry Run and Audit
+
+- `--dry-run`: shows file diff preview without writing.
+- `--audit`: reports roadmap/code mismatches:
+  - checked without evidence
+  - ready but unchecked
+
+## Development
+
+```bash
+npm test
+```
+
+## Publishing (Future, Not Yet)
+
+### npm (public package, future)
+
+1. Run tests.
+
+```bash
+npm test
+```
+
+2. Bump version using semver.
+
+```bash
+npm version patch
+# or: npm version minor
+# or: npm version major
+```
+
+3. Publish package.
+
+```bash
+npm publish --access public
+```
+
+4. Push tags.
+
+```bash
+git push origin main --follow-tags
+```
+
+### skills.sh / `npx skills add` discoverability (future)
+
+1. After internal release-readiness is complete, make the repository public with `skills/roadmap-sync/SKILL.md` and `skills.json`.
+2. Verify install flow from a clean project:
+
+```bash
+npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
+```
+
+3. Confirm the installed skill appears in your agent skill list. This install command adds the agent skill, not the CLI package.
+
+## Versioning Strategy
+
+- `patch`: bug fixes and non-breaking validation/generation improvements.
+- `minor`: backward-compatible features (new flags, new plugin hooks, additive config fields).
+- `major`: breaking CLI/config behavior or marker/format changes.

package/bin/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgv } = require('../src/utils');
+const { loadConfig, resolveRoadmapFile, resolveAgentsFile, loadPlugins } = require('../src/config');
+const { readTextIfExists, writeText, printDryRunDiff } = require('../src/io');
+const { renderRoadmapTemplate, renderAgentsTemplate } = require('../src/templates');
+const { generateRoadmapDocument } = require('../src/generator');
+const { parseRoadmap } = require('../src/parser');
+const { buildValidationContext, validateTasks, auditValidation } = require('../src/validator');
+const { applySync } = require('../src/sync');
+
+function printHelp() {
+  console.log([
+    'Usage:',
+    '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
+    '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]',
+    '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]',
+    '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]'
+  ].join('\n'));
+}
+
+function isEnabled(value) {
+  if (value === true) return true;
+  if (typeof value !== 'string') return false;
+  const normalized = value.toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+
+function formatResultLine(task, result) {
+  const status = result.passed ? 'PASS' : 'FAIL';
+  const reason = result.reasons.length > 0 ? ` :: ${result.reasons.join('; ')}` : '';
+  return `${status} [${task.id}] ${task.text}${reason}`;
+}
+
+function maybeFilterTasks(tasks, filterValue) {
+  if (!filterValue) return tasks;
+  const normalized = String(filterValue).toLowerCase();
+  return tasks.filter((task) => {
+    return task.id.toLowerCase() === normalized || task.text.toLowerCase().includes(normalized);
+  });
+}
+
+function printAudit(audit) {
+  console.log(`Audit summary: ${audit.checkedWithoutEvidence.length} checked-without-evidence, ${audit.readyButUnchecked.length} ready-but-unchecked.`);
+  if (audit.checkedWithoutEvidence.length > 0) {
+    console.log('Checked without evidence:');
+    audit.checkedWithoutEvidence.forEach((item) => {
+      console.log(`- [${item.task.id}] ${item.task.text}`);
+    });
+  }
+  if (audit.readyButUnchecked.length > 0) {
+    console.log('Ready but unchecked:');
+    audit.readyButUnchecked.forEach((item) => {
+      console.log(`- [${item.task.id}] ${item.task.text}`);
+    });
+  }
+}
+
+async function run() {
+  const parsed = parseArgv(process.argv.slice(2));
+  const command = parsed.command;
+  const flags = parsed.flags;
+
+  if (!command || isEnabled(flags.help) || isEnabled(flags.h)) {
+    printHelp();
+    return;
+  }
+
+  if (command === 'init') {
+    const projectRoot = process.cwd();
+    const config = loadConfig({ projectRoot });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
+    const dryRun = isEnabled(flags['dry-run']);
+
+    const roadmapExists = fs.existsSync(roadmapFile);
+    const agentsExists = fs.existsSync(agentsFile);
+
+    if (!roadmapExists) {
+      const roadmap = renderRoadmapTemplate();
+      const result = writeText(roadmapFile, roadmap, { dryRun });
+      if (dryRun && result.changed) {
+        printDryRunDiff(roadmapFile, result.before, result.after);
+      }
+      console.log(`${dryRun ? 'Would create' : 'Created'} ${roadmapFile}`);
+    } else {
+      console.log(`Skipped existing ${roadmapFile}`);
+    }
+
+    if (!agentsExists) {
+      const agents = renderAgentsTemplate({ roadmapPath: path.basename(roadmapFile) });
+      const result = writeText(agentsFile, agents, { dryRun });
+      if (dryRun && result.changed) {
+        printDryRunDiff(agentsFile, result.before, result.after);
+      }
+      console.log(`${dryRun ? 'Would create' : 'Created'} ${agentsFile}`);
+    } else {
+      console.log(`Skipped existing ${agentsFile}`);
+    }
+    return;
+  }
+
+  if (command === 'generate') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const plugins = loadPlugins(projectRoot, config.plugins);
+    const existingContent = readTextIfExists(roadmapFile) || '';
+    const dryRun = isEnabled(flags['dry-run']);
+
+    const document = generateRoadmapDocument({
+      projectRoot,
+      roadmapPath: roadmapFile,
+      existingContent,
+      config,
+      plugins
+    });
+
+    const writeResult = writeText(roadmapFile, document, { dryRun });
+    if (dryRun) {
+      if (writeResult.changed) {
+        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
+      } else {
+        console.log(`No changes for ${roadmapFile}`);
+      }
+    } else {
+      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
+    }
+
+    if (isEnabled(flags.audit)) {
+      const parsedRoadmap = parseRoadmap(document);
+      const validationContext = buildValidationContext(projectRoot, config, plugins);
+      const results = validateTasks(parsedRoadmap.tasks, validationContext, config, plugins);
+      const audit = auditValidation(parsedRoadmap.tasks, results);
+      printAudit(audit);
+    }
+    return;
+  }
+
+  if (command === 'sync') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const content = readTextIfExists(roadmapFile);
+    if (content == null) {
+      throw new Error(`Roadmap not found: ${roadmapFile}`);
+    }
+
+    const parsedRoadmap = parseRoadmap(content);
+    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+    const results = validateTasks(parsedRoadmap.tasks, validationContext, config, validationContext.plugins);
+    const next = applySync(content, parsedRoadmap.tasks, results);
+    const dryRun = isEnabled(flags['dry-run']);
+    const writeResult = writeText(roadmapFile, next, { dryRun });
+
+    if (dryRun) {
+      if (writeResult.changed) {
+        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
+      } else {
+        console.log(`No changes for ${roadmapFile}`);
+      }
+    } else {
+      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
+    }
+
+    if (isEnabled(flags.audit)) {
+      const audit = auditValidation(parsedRoadmap.tasks, results);
+      printAudit(audit);
+    }
+    return;
+  }
+
+  if (command === 'validate') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const content = readTextIfExists(roadmapFile);
+    if (content == null) {
+      throw new Error(`Roadmap not found: ${roadmapFile}`);
+    }
+
+    const parsedRoadmap = parseRoadmap(content);
+    const tasks = maybeFilterTasks(parsedRoadmap.tasks, flags.task);
+    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+    const results = validateTasks(tasks, validationContext, config, validationContext.plugins);
+
+    if (isEnabled(flags.json)) {
+      const payload = tasks.map((task) => ({ task, result: results[task.id] }));
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      tasks.forEach((task) => {
+        console.log(formatResultLine(task, results[task.id]));
+      });
+    }
+
+    const failed = tasks.some((task) => !results[task.id].passed);
+    if (failed) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+run().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "roadmapsmith",
+  "version": "0.1.0",
+  "description": "Generate, sync, and validate deterministic project roadmaps for agent-driven execution.",
+  "main": "src/index.js",
+  "bin": {
+    "roadmap-skill": "bin/cli.js",
+    "roadmapsmith": "bin/cli.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "roadmap",
+    "skills",
+    "agent",
+    "cli",
+    "planning"
+  ],
+  "author": "PapiScholz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PapiScholz/roadmapsmith.git",
+    "directory": "roadmap-skill"
+  },
+  "bugs": {
+    "url": "https://github.com/PapiScholz/roadmapsmith/issues"
+  },
+  "homepage": "https://github.com/PapiScholz/roadmapsmith#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ]
+}

package/src/config.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { readTextIfExists } = require('./io');
+
+const DEFAULT_CONFIG = {
+  roadmapFile: './ROADMAP.md',
+  agentsFile: './AGENTS.md',
+  taskMatchers: [],
+  validators: [],
+  customSections: [],
+  plugins: [],
+  milestones: [
+    { version: 'v0.1', goal: 'Foundation baseline complete' },
+    { version: 'v0.2', goal: 'Core feature coverage stabilized' },
+    { version: 'v0.3', goal: 'Release candidate hardening complete' },
+    { version: 'v1.0', goal: 'Production readiness exit criteria met' }
+  ],
+  phaseTemplates: {
+    P0: [
+      'Stabilize project baseline and unblock high-risk delivery paths',
+      'Implement critical tasks required for milestone v0.1'
+    ],
+    P1: [
+      'Expand feature completeness and improve reliability',
+      'Reduce operational risk before v0.3'
+    ],
+    P2: [
+      'Complete final hardening and release readiness for v1.0',
+      'Close non-critical backlog aligned to anti-goals'
+    ]
+  }
+};
+
+function safeParseJson(content, filePath) {
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
+  }
+}
+
+function mergeConfig(userConfig) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...userConfig,
+    taskMatchers: Array.isArray(userConfig.taskMatchers) ? userConfig.taskMatchers : DEFAULT_CONFIG.taskMatchers,
+    validators: Array.isArray(userConfig.validators) ? userConfig.validators : DEFAULT_CONFIG.validators,
+    customSections: Array.isArray(userConfig.customSections) ? userConfig.customSections : DEFAULT_CONFIG.customSections,
+    plugins: Array.isArray(userConfig.plugins) ? userConfig.plugins : DEFAULT_CONFIG.plugins,
+    milestones: Array.isArray(userConfig.milestones) ? userConfig.milestones : DEFAULT_CONFIG.milestones,
+    phaseTemplates: {
+      ...DEFAULT_CONFIG.phaseTemplates,
+      ...((userConfig && userConfig.phaseTemplates) || {})
+    }
+  };
+}
+
+function loadConfig(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const resolvedConfigPath = options.configPath
+    ? path.resolve(projectRoot, String(options.configPath))
+    : path.resolve(projectRoot, 'roadmap-skill.config.json');
+
+  const content = readTextIfExists(resolvedConfigPath);
+  let userConfig = {};
+  if (!content) {
+    const merged = mergeConfig(userConfig);
+    Object.defineProperty(merged, '__roadmapFileExplicit', {
+      value: false,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return merged;
+  }
+
+  userConfig = safeParseJson(content, resolvedConfigPath);
+  const merged = mergeConfig(userConfig);
+  Object.defineProperty(merged, '__roadmapFileExplicit', {
+    value: Object.prototype.hasOwnProperty.call(userConfig, 'roadmapFile'),
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return merged;
+}
+
+function resolveRoadmapFile(projectRoot, config, overridePath) {
+  if (overridePath) {
+    return path.resolve(projectRoot, overridePath);
+  }
+
+  const configuredRoadmapFile =
+    config && typeof config.roadmapFile === 'string' ? config.roadmapFile.trim() : '';
+  const hasExplicitRoadmapFile = Boolean(config && config.__roadmapFileExplicit);
+  const hasCustomConfigRoadmapFile =
+    configuredRoadmapFile.length > 0 &&
+    (hasExplicitRoadmapFile || configuredRoadmapFile !== DEFAULT_CONFIG.roadmapFile);
+
+  if (hasCustomConfigRoadmapFile) {
+    return path.resolve(projectRoot, configuredRoadmapFile);
+  }
+
+  let rootEntries = null;
+  try {
+    rootEntries = fs.readdirSync(projectRoot);
+  } catch {
+    rootEntries = null;
+  }
+
+  const canonicalRoadmapPath = path.resolve(projectRoot, DEFAULT_CONFIG.roadmapFile);
+  const legacyRoadmapPath = path.resolve(projectRoot, './roadmap.md');
+
+  const hasCanonicalRoadmap = Array.isArray(rootEntries)
+    ? rootEntries.includes('ROADMAP.md')
+    : readTextIfExists(canonicalRoadmapPath) != null;
+  const hasLegacyRoadmap = Array.isArray(rootEntries)
+    ? rootEntries.includes('roadmap.md')
+    : readTextIfExists(legacyRoadmapPath) != null;
+
+  if (hasCanonicalRoadmap) {
+    return canonicalRoadmapPath;
+  }
+  if (hasLegacyRoadmap) {
+    return legacyRoadmapPath;
+  }
+  return canonicalRoadmapPath;
+}
+
+function resolveAgentsFile(projectRoot, config, overridePath) {
+  if (overridePath) {
+    return path.resolve(projectRoot, overridePath);
+  }
+
+  const agentsPath = path.resolve(projectRoot, config.agentsFile || './AGENTS.md');
+  const claudePath = path.resolve(projectRoot, './CLAUDE.md');
+
+  if (readTextIfExists(agentsPath) != null) {
+    return agentsPath;
+  }
+  if (readTextIfExists(claudePath) != null) {
+    return claudePath;
+  }
+  return agentsPath;
+}
+
+function loadPlugins(projectRoot, pluginEntries) {
+  const plugins = [];
+  for (const entry of pluginEntries || []) {
+    const pluginPath = path.resolve(projectRoot, entry);
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    const pluginModule = require(pluginPath);
+    plugins.push({
+      name: path.basename(pluginPath),
+      path: pluginPath,
+      module: pluginModule
+    });
+  }
+  return plugins;
+}
+
+function collectPluginContributions(plugins, hookName, context) {
+  const contributions = [];
+  for (const plugin of plugins || []) {
+    const hook = plugin.module && plugin.module[hookName];
+    if (typeof hook !== 'function') {
+      continue;
+    }
+    const result = hook(context);
+    if (Array.isArray(result)) {
+      for (const item of result) {
+        contributions.push(item);
+      }
+    }
+  }
+  return contributions;
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  collectPluginContributions,
+  loadConfig,
+  loadPlugins,
+  resolveAgentsFile,
+  resolveRoadmapFile
+};