roadmapsmith 0.1.1 → 0.4.0

package/README.md

@@ -18,6 +18,31 @@ npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
 
 This adds the `roadmap-sync` agent skill. It does not install the CLI package.
 
+## Operating Modes
+
+### Zero Mode
+
+Agent-guided discovery for empty or low-context repositories. The developer has a product idea but no implementation files, no stack decision, and no ROADMAP.md yet.
+
+The CLI creates governance files. The AI agent (using the `roadmap-sync` skill) performs the discovery interview before generating the roadmap.
+
+```bash
+roadmapsmith init
+roadmapsmith generate --project-root .
+```
+
+### Sync/Audit Mode
+
+Repository-backed roadmap generation, validation, and synchronization. Use when the repository already has code, tests, docs, TODOs, or an existing ROADMAP.md.
+
+```bash
+roadmapsmith generate --project-root .
+roadmapsmith validate --json
+roadmapsmith sync --audit
+```
+
+---
+
 ## Commands
 
 ```bash
@@ -61,6 +86,27 @@ Create `roadmap-skill.config.json`:
 {
   "roadmapFile": "./ROADMAP.md",
   "agentsFile": "./AGENTS.md",
+
+  // Forward-compatible fields — recognized by the skill/agent for Zero Mode discovery context,
+  // but not yet read by the generator or validator. Safe to add now; they will be wired in a future release.
+  "northStar": "Ship a self-hosted CLI tool for website capture and AI-readable design analysis.",
+  "targetUser": "Frontend developers, full-stack developers, and AI coding agents.",
+  "problemStatement": "Developers lack a unified tool to capture screenshots, crawl pages, extract assets, and export structured context.",
+  "v1Outcome": "A stable CLI that captures full-page screenshots, crawls internal links, exports metadata, and produces an AI-readable report.",
+  "antiGoals": [
+    "Do not bypass authentication",
+    "Do not target private systems without authorization"
+  ],
+  "risks": [
+    "Browser automation instability",
+    "Scope creep into generic scraping"
+  ],
+  "exitCriteria": [
+    "CLI works against a public test site",
+    "Screenshots and metadata are exported deterministically",
+    "README documents safe and authorized usage"
+  ],
+
   "taskMatchers": [
     {
       "pattern": "src/payments/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "Generate, sync, and validate deterministic project roadmaps for agent-driven execution.",
   "main": "src/index.js",
   "bin": {

package/src/config.js

@@ -7,10 +7,23 @@ const { readTextIfExists } = require('./io');
 const DEFAULT_CONFIG = {
   roadmapFile: './ROADMAP.md',
   agentsFile: './AGENTS.md',
+  roadmapProfile: 'compact',
   taskMatchers: [],
   validators: [],
   customSections: [],
   plugins: [],
+  product: {
+    name: '',
+    northStar: '',
+    positioning: '',
+    primaryUser: '',
+    targetOutcome: '',
+    antiGoals: [],
+    risks: [],
+    successCriteria: [],
+    steps: [],
+    phases: []
+  },
   milestones: [
     { version: 'v0.1', goal: 'Foundation baseline complete' },
     { version: 'v0.2', goal: 'Core feature coverage stabilized' },
@@ -53,6 +66,13 @@ function mergeConfig(userConfig) {
     phaseTemplates: {
       ...DEFAULT_CONFIG.phaseTemplates,
       ...((userConfig && userConfig.phaseTemplates) || {})
+    },
+    product: {
+      ...DEFAULT_CONFIG.product,
+      ...((userConfig && userConfig.product) || {}),
+      phases: (userConfig && userConfig.product && Array.isArray(userConfig.product.phases))
+        ? userConfig.product.phases
+        : DEFAULT_CONFIG.product.phases
     }
   };
 }
@@ -185,4 +205,4 @@ module.exports = {
   loadPlugins,
   resolveAgentsFile,
   resolveRoadmapFile
-};
+};

package/src/generator/index.js

@@ -8,6 +8,7 @@ const { slugify, ensureTrailingNewline } = require('../utils');
 const { parseRoadmap, upsertManagedBlock } = require('../parser');
 const { findBestTaskMatch, dedupeTasks } = require('../match');
 const { collectPluginContributions } = require('../config');
+const { renderBody } = require('../renderer');
 
 function detectModules(files) {
   const modules = new Set();
@@ -73,6 +74,37 @@ function collectTodoHints(projectRoot, files) {
   return hints;
 }
 
+function collectCodeTodoHints(projectRoot, files) {
+  const hints = [];
+  const codeFiles = files.filter((file) => /\.(js|ts|tsx|py|go|rs)$/.test(file)).slice(0, 120);
+
+  for (const file of codeFiles) {
+    const absolutePath = path.resolve(projectRoot, file);
+    let content = '';
+    try {
+      content = fs.readFileSync(absolutePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+      if (/TODO|FIXME/i.test(lines[i])) {
+        hints.push({
+          file,
+          line: i + 1,
+          text: lines[i].trim()
+        });
+      }
+      if (hints.length >= 6) {
+        return hints;
+      }
+    }
+  }
+
+  return hints;
+}
+
 function scanProject(projectRoot) {
   const files = walkFiles(projectRoot);
   const languages = detectLanguages(files);
@@ -80,17 +112,20 @@ function scanProject(projectRoot) {
   const modules = detectModules(files);
   const commands = detectCommands(files);
   const todos = collectTodoHints(projectRoot, files);
+  const codeTodos = collectCodeTodoHints(projectRoot, files);
 
   const implementedFiles = files.filter((file) => /\.(js|ts|tsx|py|go|rs|java|kt|cs)$/.test(file));
   const testFiles = files.filter((file) => /(^|\/)(__tests__|tests)\//.test(file) || /\.test\.|\.spec\.|_test\.go$/.test(file));
 
   return {
+    projectRoot,
     files,
     languages,
     testFrameworks,
     modules,
     commands,
     todos,
+    codeTodos,
     implementedCount: implementedFiles.length,
     testCount: testFiles.length
   };
@@ -328,10 +363,131 @@ function renderManagedBody(model) {
   return ensureTrailingNewline(lines.join('\n')).trimEnd();
 }
 
+function inferProjectName(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg.name) return pkg.name;
+  } catch {
+    // ignore — try other manifests
+  }
+  return path.basename(projectRoot);
+}
+
+function buildPhasesDetailed(phases, config) {
+  const configPhases = config.product && Array.isArray(config.product.phases)
+    ? config.product.phases : [];
+  if (configPhases.length > 0) return configPhases;
+
+  return [
+    {
+      phaseNumber: 1,
+      title: 'Foundation Baseline',
+      priority: 'P0',
+      objective: 'Establish a stable, testable baseline that unblocks all downstream delivery.',
+      steps: [{
+        stepNumber: 1,
+        title: 'Core Implementation',
+        priority: 'P0',
+        dependsOn: [],
+        objective: 'Close critical path items.',
+        tasks: phases.P0,
+        exitCriteria: [
+          { text: 'All P0 tasks validated by evidence', priority: 'P0' },
+          { text: 'CI is green on main', priority: 'P0' }
+        ],
+        risks: []
+      }]
+    },
+    {
+      phaseNumber: 2,
+      title: 'Feature Completeness',
+      priority: 'P1',
+      objective: 'Expand functionality and reduce operational risk.',
+      steps: [{
+        stepNumber: 1,
+        title: 'Feature Delivery',
+        priority: 'P1',
+        dependsOn: [1],
+        objective: 'Deliver planned P1 features.',
+        tasks: phases.P1,
+        exitCriteria: [
+          { text: 'All P1 tasks validated by evidence', priority: 'P1' },
+          { text: 'No regressions on Phase 1 functionality', priority: 'P0' }
+        ],
+        risks: []
+      }]
+    },
+    {
+      phaseNumber: 3,
+      title: 'Release Hardening',
+      priority: 'P2',
+      objective: 'Complete hardening and production readiness for v1.0.',
+      steps: [{
+        stepNumber: 1,
+        title: 'Hardening',
+        priority: 'P2',
+        dependsOn: [2],
+        objective: 'Close P2 items and harden release.',
+        tasks: phases.P2,
+        exitCriteria: [
+          { text: 'All P2 tasks validated by evidence', priority: 'P2' },
+          { text: 'Release candidate checklist complete', priority: 'P0' }
+        ],
+        risks: []
+      }]
+    }
+  ];
+}
+
+function buildSteps(phases, config) {
+  const configSteps = config.product && Array.isArray(config.product.steps) ? config.product.steps : [];
+  if (configSteps.length > 0) return configSteps;
+
+  const stepDefs = [
+    { stepNumber: 1, title: 'Foundation Baseline', priority: 'P0', dependsOn: [], phaseKey: 'P0',
+      objective: 'Establish a stable, testable baseline that unblocks all downstream delivery.' },
+    { stepNumber: 2, title: 'Feature Completeness', priority: 'P1', dependsOn: [1], phaseKey: 'P1',
+      objective: 'Expand functionality, improve reliability, and reduce operational risk.' },
+    { stepNumber: 3, title: 'Release Hardening', priority: 'P2', dependsOn: [2], phaseKey: 'P2',
+      objective: 'Complete hardening, final validation, and production readiness for v1.0.' }
+  ];
+
+  const defaultExitCriteria = {
+    1: ['All P0 tasks validated by evidence', 'CI is green on main'],
+    2: ['All P1 tasks validated by evidence', 'No regressions on P0 functionality'],
+    3: ['All P2 tasks validated by evidence', 'Release candidate checklist complete']
+  };
+
+  return stepDefs.map((def) => ({
+    stepNumber: def.stepNumber,
+    title: def.title,
+    priority: def.priority,
+    dependsOn: def.dependsOn,
+    objective: def.objective,
+    deliverables: phases[def.phaseKey] || [],
+    exitCriteria: defaultExitCriteria[def.stepNumber] || [],
+    risks: []
+  }));
+}
+
 function createModel(scan, tasks, config, customSections, checkedById) {
   const phases = groupByPhase(tasks);
 
+  const implemented = [
+    `${scan.implementedCount} implementation files across ${scan.languages.join(', ') || 'detected stack'}`
+  ];
+
+  const scaffold = scan.modules.length > 0
+    ? scan.modules.slice(0, 6).map((m) => `Module "${m}" partially implemented — coverage unknown`)
+    : [];
+
+  const knownLimitations = (scan.codeTodos || []).slice(0, 6).map((t) => `${t.file}:${t.line} — ${t.text.slice(0, 80)}`);
+
   const currentState = {
+    implemented,
+    scaffold,
+    knownLimitations,
     implementedSummary: `${scan.implementedCount} implementation files detected`,
     todoSummary: `${scan.todos.length} TODO/FIXME markers detected`,
     stackSummary: scan.languages.length > 0 ? scan.languages.join(', ') : 'No language-specific stack detected'
@@ -351,23 +507,50 @@ function createModel(scan, tasks, config, customSections, checkedById) {
     commandBreakdown.push(`Command: ${command}`);
   }
 
+  const productConfig = config.product || {};
+  const inferredName = inferProjectName(scan.projectRoot || process.cwd());
+  const product = {
+    name: productConfig.name || inferredName,
+    northStar: productConfig.northStar || '',
+    positioning: productConfig.positioning || '',
+    primaryUser: productConfig.primaryUser || '',
+    targetOutcome: productConfig.targetOutcome || ''
+  };
+
+  const defaultRisks = [
+    'Roadmap drift if checklist state diverges from repository evidence',
+    'Silent regressions when tasks are marked complete without tests',
+    'Scope creep that delays the v1.0 milestone path'
+  ];
+  const defaultAntiGoals = [
+    'Do not mark tasks complete without repository evidence',
+    'Do not introduce non-deterministic roadmap formatting',
+    'Do not hide validation failures from roadmap consumers'
+  ];
+
+  const risks = (productConfig.risks && productConfig.risks.length > 0) ? productConfig.risks : defaultRisks;
+  const antiGoals = (productConfig.antiGoals && productConfig.antiGoals.length > 0) ? productConfig.antiGoals : defaultAntiGoals;
+  const successCriteria = productConfig.successCriteria || [];
+
+  const northStar = productConfig.northStar
+    || 'Ship validated, high-impact increments with deterministic delivery and transparent completion evidence.';
+
+  const steps = buildSteps(phases, config);
+  const phasesDetailed = buildPhasesDetailed(phases, config);
+
   return createRoadmapModel({
-    northStar: 'Ship validated, high-impact increments with deterministic delivery and transparent completion evidence.',
+    northStar,
+    product,
     currentState,
     phases,
+    steps,
+    phasesDetailed,
     milestones: config.milestones,
     commandBreakdown,
     exitCriteria,
-    risks: [
-      'Roadmap drift if checklist state diverges from repository evidence',
-      'Silent regressions when tasks are marked complete without tests',
-      'Scope creep that delays the v1.0 milestone path'
-    ],
-    antiGoals: [
-      'Do not mark tasks complete without repository evidence',
-      'Do not introduce non-deterministic roadmap formatting',
-      'Do not hide validation failures from roadmap consumers'
-    ],
+    risks,
+    antiGoals,
+    successCriteria,
     customSections,
     checkedById
   });
@@ -424,7 +607,8 @@ function generateRoadmapDocument(options) {
   const matcherCandidates = applyTaskMatchers(scan, config);
   const merged = mergeWithExisting([...baseCandidates, ...matcherCandidates, ...pluginTaskCandidates], existingPhaseTasks);
   const model = createModel(scan, merged, config, [...configSections, ...pluginSections], existingCheckedById);
-  const managedBody = renderManagedBody(model);
+  const profile = config.roadmapProfile || 'compact';
+  const managedBody = renderBody(model, profile);
 
   return upsertManagedBlock(existingContent, managedBody);
 }
@@ -433,4 +617,4 @@ module.exports = {
   generateRoadmapDocument,
   renderManagedBody,
   scanProject
-};
+};

package/src/model.js

@@ -10,14 +10,19 @@ function phaseWeight(phase) {
 function createRoadmapModel(input) {
   return {
     northStar: input.northStar,
+    product: input.product || {},
     currentState: input.currentState,
     phases: input.phases,
+    steps: input.steps || [],
+    phasesDetailed: input.phasesDetailed || [],
     milestones: input.milestones,
     commandBreakdown: input.commandBreakdown,
     exitCriteria: input.exitCriteria,
     risks: input.risks,
     antiGoals: input.antiGoals,
-    customSections: input.customSections || []
+    successCriteria: input.successCriteria || [],
+    customSections: input.customSections || [],
+    checkedById: input.checkedById || {}
   };
 }
 
@@ -25,4 +30,4 @@ module.exports = {
   PHASE_ORDER,
   createRoadmapModel,
   phaseWeight
-};
+};

package/src/renderer/compact.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { slugify, ensureTrailingNewline } = require('../utils');
+const { taskLine, checkedState } = require('./helpers');
+
+function renderCompact(model) {
+  const lines = [];
+
+  lines.push('# Project Roadmap');
+  lines.push('');
+  lines.push('## Product North Star');
+  lines.push(model.northStar);
+  lines.push('');
+
+  lines.push('## Current State');
+  lines.push(`- Implemented surface: ${model.currentState.implementedSummary}`);
+  lines.push(`- TODO surface: ${model.currentState.todoSummary}`);
+  lines.push(`- Detected stacks: ${model.currentState.stackSummary}`);
+  lines.push('');
+
+  lines.push('## Phased Roadmap');
+  lines.push('');
+  lines.push('### Phase P0 (Critical)');
+  for (const task of model.phases.P0) {
+    lines.push(taskLine(task));
+  }
+  lines.push('');
+  lines.push('### Phase P1 (Important)');
+  for (const task of model.phases.P1) {
+    lines.push(taskLine(task));
+  }
+  lines.push('');
+  lines.push('### Phase P2 (Optimization)');
+  for (const task of model.phases.P2) {
+    lines.push(taskLine(task));
+  }
+  lines.push('');
+
+  lines.push('## Release Milestones');
+  for (const milestone of model.milestones) {
+    const id = `milestone-${slugify(milestone.version)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${milestone.version}: ${milestone.goal} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('## Command/Module Breakdown');
+  if (model.commandBreakdown.length === 0) {
+    const id = 'identify-command-module-boundaries';
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] Identify command/module boundaries for the next increment <!-- rs:task=${id} -->`);
+  } else {
+    for (const item of model.commandBreakdown) {
+      const id = `module-${slugify(item)}`;
+      lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${item} <!-- rs:task=${id} -->`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Exit Criteria Per Phase');
+  for (const item of model.exitCriteria) {
+    const id = `exit-${slugify(item)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${item} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  for (const section of model.customSections) {
+    lines.push(`## ${section.title}`);
+    for (const line of section.items) {
+      lines.push(line);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Risks and Anti-goals');
+  lines.push('### Risks');
+  for (const risk of model.risks) {
+    const id = `risk-${slugify(risk)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${risk} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+  lines.push('### Anti-goals');
+  for (const antiGoal of model.antiGoals) {
+    const id = `anti-goal-${slugify(antiGoal)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${antiGoal} <!-- rs:task=${id} -->`);
+  }
+
+  return ensureTrailingNewline(lines.join('\n')).trimEnd();
+}
+
+module.exports = { renderCompact };

package/src/renderer/helpers.js

@@ -0,0 +1,19 @@
+'use strict';
+
+function taskLine(task) {
+  return `- [${task.checked ? 'x' : ' '}] ${task.text} <!-- rs:task=${task.id} -->`;
+}
+
+function sectionHeader(n, title) {
+  return `## ${n}. ${title}`;
+}
+
+function checkedState(model, id) {
+  return Boolean(model.checkedById && model.checkedById[id]);
+}
+
+function priorityLabel(priority) {
+  return priority ? `\`[${priority}]\`` : '';
+}
+
+module.exports = { taskLine, sectionHeader, checkedState, priorityLabel };

package/src/renderer/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const { renderCompact } = require('./compact');
+const { renderProfessional } = require('./professional');
+
+function renderBody(model, profile) {
+  if (profile === 'professional') return renderProfessional(model);
+  if (profile === 'enterprise') {
+    throw new Error(
+      'roadmapProfile "enterprise" is not yet implemented. ' +
+      'Use "professional" instead, or contribute via the plugin registry. ' +
+      'See docs/use-cases/ for the extension guide.'
+    );
+  }
+  return renderCompact(model);
+}
+
+module.exports = { renderBody };

package/src/renderer/professional.js

@@ -0,0 +1,467 @@
+'use strict';
+
+const { slugify, ensureTrailingNewline } = require('../utils');
+const { sectionHeader, checkedState, priorityLabel } = require('./helpers');
+
+function taskLineWithPriority(task, model) {
+  const pri = task.priority ? `${priorityLabel(task.priority)} ` : '';
+  const id = task.id || `prof-task-${slugify(task.text || String(task))}`;
+  const text = task.text || String(task);
+  const checked = task.checked || checkedState(model, id);
+  return `- [${checked ? 'x' : ' '}] ${pri}${text} <!-- rs:task=${id} -->`;
+}
+
+function exitLine(item, phN, stN, model) {
+  const text = typeof item === 'string' ? item : item.text;
+  const pri = (typeof item === 'object' && item.priority) ? `${priorityLabel(item.priority)} ` : '';
+  const id = `prof-ph${phN}-st${stN}-exit-${slugify(text)}`;
+  const checked = checkedState(model, id);
+  return `- [${checked ? 'x' : ' '}] ${pri}${text} <!-- rs:task=${id} -->`;
+}
+
+function renderSection1NorthStar(model, lines) {
+  lines.push(sectionHeader(1, 'Product North Star'));
+  lines.push('');
+  lines.push(model.product.northStar || model.northStar);
+  lines.push('');
+  if (model.product.primaryUser) {
+    lines.push(`**Primary user:** ${model.product.primaryUser}`);
+    lines.push('');
+  }
+  if (model.product.targetOutcome) {
+    lines.push(`**Target outcome:** ${model.product.targetOutcome}`);
+    lines.push('');
+  }
+}
+
+function renderSection2Positioning(model, lines) {
+  lines.push(sectionHeader(2, 'Positioning and Competitive Advantage'));
+  lines.push('');
+  if (model.product.positioning) {
+    lines.push(model.product.positioning);
+  } else {
+    lines.push('_No positioning statement configured. Add `product.positioning` to roadmap-skill.config.json._');
+  }
+  lines.push('');
+}
+
+function renderSection3CurrentState(model, lines) {
+  lines.push(sectionHeader(3, 'Explicit Current State'));
+  lines.push('');
+
+  lines.push('### Implemented');
+  lines.push('');
+  if (model.currentState.implemented && model.currentState.implemented.length > 0) {
+    for (const item of model.currentState.implemented) {
+      lines.push(`- [x] ${item} <!-- rs:task=prof-state-impl-${slugify(item)} -->`);
+    }
+  } else {
+    lines.push(`- Detected implementation surface: ${model.currentState.implementedSummary}`);
+    lines.push(`- Detected stacks: ${model.currentState.stackSummary}`);
+  }
+  lines.push('');
+
+  lines.push('### Scaffold / Partial');
+  lines.push('');
+  if (model.currentState.scaffold && model.currentState.scaffold.length > 0) {
+    for (const item of model.currentState.scaffold) {
+      const id = `prof-state-scaffold-${slugify(item)}`;
+      lines.push(`- [ ] ${item} <!-- rs:task=${id} -->`);
+    }
+  } else {
+    lines.push('_No scaffold modules detected. Improve detection by adding `product.steps` to config._');
+  }
+  lines.push('');
+
+  lines.push('### Known Limitations');
+  lines.push('');
+  if (model.currentState.knownLimitations && model.currentState.knownLimitations.length > 0) {
+    for (const item of model.currentState.knownLimitations) {
+      const id = `prof-state-limit-${slugify(item)}`;
+      lines.push(`- [ ] ${item} <!-- rs:task=${id} -->`);
+    }
+  } else {
+    lines.push(`- Code-level TODO/FIXME surface: ${model.currentState.todoSummary}`);
+  }
+  lines.push('');
+}
+
+function renderSection4PhasedExecution(model, lines) {
+  lines.push(sectionHeader(4, 'Phased Execution Roadmap'));
+  lines.push('');
+
+  const detailedPhases = [...(model.phasesDetailed || [])].sort((a, b) => a.phaseNumber - b.phaseNumber);
+
+  for (const phase of detailedPhases) {
+    lines.push(`### Phase ${phase.phaseNumber}: ${phase.title}`);
+    lines.push('');
+    lines.push(`**Phase Priority:** ${priorityLabel(phase.priority)}`);
+    lines.push('');
+    if (phase.objective) {
+      lines.push(`**Objective:** ${phase.objective}`);
+      lines.push('');
+    }
+
+    const steps = [...(phase.steps || [])].sort((a, b) => a.stepNumber - b.stepNumber);
+    for (const step of steps) {
+      const stepLabel = `${phase.phaseNumber}.${step.stepNumber}`;
+      lines.push(`#### Step ${stepLabel}: ${step.title}`);
+      lines.push('');
+      lines.push(`**Step Priority:** ${priorityLabel(step.priority)}`);
+      const deps = step.dependsOn && step.dependsOn.length > 0
+        ? step.dependsOn.map((n) => `Phase ${n}`).join(', ')
+        : 'None';
+      lines.push(`**Depends on:** ${deps}`);
+      lines.push('');
+      if (step.objective) {
+        lines.push(`**Objective:** ${step.objective}`);
+        lines.push('');
+      }
+
+      if (step.tasks && step.tasks.length > 0) {
+        lines.push('**Tasks:**');
+        lines.push('');
+        for (const task of step.tasks) {
+          lines.push(taskLineWithPriority(task, model));
+        }
+        lines.push('');
+      }
+
+      if (step.exitCriteria && step.exitCriteria.length > 0) {
+        lines.push('**Exit Criteria:**');
+        lines.push('');
+        for (const item of step.exitCriteria) {
+          lines.push(exitLine(item, phase.phaseNumber, step.stepNumber, model));
+        }
+        lines.push('');
+      }
+
+      if (step.risks && step.risks.length > 0) {
+        lines.push(`**Notable Risks:** ${step.risks.join('; ')}`);
+        lines.push('');
+      }
+    }
+  }
+}
+
+function renderSection5Milestones(model, lines) {
+  lines.push(sectionHeader(5, 'Versioned Milestones'));
+  lines.push('');
+
+  for (const milestone of model.milestones) {
+    const msSlug = slugify(milestone.version);
+    lines.push(`### ${milestone.version}`);
+    lines.push('');
+    lines.push(`**Goal:** ${milestone.goal}`);
+    lines.push('');
+
+    if (milestone.mustExist && milestone.mustExist.length > 0) {
+      lines.push('**What Must Exist:**');
+      lines.push('');
+      for (const item of milestone.mustExist) {
+        const id = `prof-ms-${msSlug}-exist-${slugify(item)}`;
+        lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P0]\` ${item} <!-- rs:task=${id} -->`);
+      }
+      lines.push('');
+    }
+
+    if (milestone.mustBeStable && milestone.mustBeStable.length > 0) {
+      lines.push('**What Must Be Stable:**');
+      lines.push('');
+      for (const item of milestone.mustBeStable) {
+        const id = `prof-ms-${msSlug}-stable-${slugify(item)}`;
+        lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P1]\` ${item} <!-- rs:task=${id} -->`);
+      }
+      lines.push('');
+    }
+
+    if (milestone.outOfScope && milestone.outOfScope.length > 0) {
+      lines.push('**Intentionally Out of Scope:**');
+      lines.push('');
+      for (const item of milestone.outOfScope) {
+        lines.push(`- ${item}`);
+      }
+      lines.push('');
+    }
+
+    if (!milestone.mustExist && !milestone.mustBeStable && !milestone.outOfScope) {
+      const id = `prof-ms-${msSlug}`;
+      lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P0]\` ${milestone.version}: ${milestone.goal} <!-- rs:task=${id} -->`);
+      lines.push('');
+    }
+  }
+}
+
+const MODULE_METADATA = {
+  generator: {
+    state: 'Compact and professional profiles supported; Phase→Step→Task model implemented.',
+    tasks: [
+      { text: 'Improve Phase→Step→Task model inference quality', priority: 'P0', id: 'prof-mat-generator-improve-phase-step-task-inference' },
+      { text: 'Add scan-driven task suggestions per detected module', priority: 'P1', id: 'prof-mat-generator-scan-driven-task-suggestions' }
+    ]
+  },
+  parser: {
+    state: 'Parses managed blocks, rs:task IDs, and checked state.',
+    tasks: [
+      { text: 'Add parser validation for Phase→Step hierarchy markers', priority: 'P1', id: 'prof-mat-parser-phase-hierarchy-validation' },
+      { text: 'Improve section boundary detection for professional format', priority: 'P1', id: 'prof-mat-parser-professional-section-detection' }
+    ]
+  },
+  renderer: {
+    state: 'Dispatcher supports compact, professional, and enterprise (error) profiles.',
+    tasks: [
+      { text: 'Add snapshot regression fixtures for compact and professional', priority: 'P0', id: 'prof-mat-renderer-snapshot-regression-fixtures' },
+      { text: 'Harden priority label rendering for edge cases', priority: 'P1', id: 'prof-mat-renderer-priority-label-edge-cases' }
+    ]
+  },
+  validator: {
+    state: 'Evidence-based validation against file, symbol, and test presence.',
+    tasks: [
+      { text: 'Extend validator to verify Phase→Step→Task IDs survive sync', priority: 'P1', id: 'prof-mat-validator-phase-step-task-id-sync' },
+      { text: 'Add validation coverage for professional profile task IDs', priority: 'P1', id: 'prof-mat-validator-professional-task-id-coverage' }
+    ]
+  },
+  match: {
+    state: 'Task similarity matching with edit-distance threshold.',
+    tasks: [
+      { text: 'Tune similarity threshold to reduce false-positive merges', priority: 'P0', id: 'prof-mat-match-tune-similarity-threshold' }
+    ]
+  },
+  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' }
+    ]
+  },
+  io: {
+    state: 'Scans files, detects languages, test frameworks, commands, modules.',
+    tasks: [
+      { text: 'Improve module detection for monorepo workspace layouts', priority: 'P2', id: 'prof-mat-io-monorepo-workspace-detection' }
+    ]
+  }
+};
+
+function renderSection6MaturityPath(model, lines) {
+  lines.push(sectionHeader(6, 'Command-by-Command / Module-by-Module Maturity Path'));
+  lines.push('');
+
+  const allAreas = [...model.commandBreakdown];
+
+  if (allAreas.length === 0) {
+    const id = 'prof-mat-identify-boundaries';
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P1]\` Identify command/module boundaries for the next increment <!-- rs:task=${id} -->`);
+    lines.push('');
+    return;
+  }
+
+  for (const area of allAreas) {
+    const rawName = area.replace(/^(Module:|Command:)\s*/i, '').trim();
+    const meta = MODULE_METADATA[rawName.toLowerCase()];
+    const displayName = rawName;
+
+    lines.push(`### ${displayName}`);
+    lines.push('');
+    if (meta) {
+      lines.push(`**Current state:** ${meta.state}`);
+      lines.push('');
+      for (const task of meta.tasks) {
+        lines.push(`- [${checkedState(model, task.id) ? 'x' : ' '}] ${priorityLabel(task.priority)} ${task.text} <!-- rs:task=${task.id} -->`);
+      }
+    } else {
+      const isCommand = /^Command:/i.test(area);
+      const kind = isCommand ? 'command' : 'module';
+      const nextId = `prof-mat-${slugify(rawName)}-define-maturity-criteria`;
+      lines.push(`**Current state:** ${kind} detected in scan.`);
+      lines.push('');
+      lines.push(`- [${checkedState(model, nextId) ? 'x' : ' '}] \`[P1]\` Define maturity criteria and testability gates for ${displayName} <!-- rs:task=${nextId} -->`);
+    }
+    lines.push('');
+  }
+}
+
+function renderSection7OutputContract(model, lines) {
+  lines.push(sectionHeader(7, 'Output Contract Roadmap'));
+  lines.push('');
+
+  lines.push('### Output Format');
+  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' }
+  ];
+  for (const item of formatItems) {
+    const id = `prof-out-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('### Breaking Changes');
+  lines.push('');
+  const breakingItems = [
+    { text: 'Document breaking vs. non-breaking output changes', priority: 'P1' },
+    { text: 'Add output schema validation to CI', priority: 'P1' }
+  ];
+  for (const item of breakingItems) {
+    const id = `prof-out-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+}
+
+function renderSection8Testing(model, lines) {
+  lines.push(sectionHeader(8, 'Testing and Quality-Gate Roadmap'));
+  lines.push('');
+
+  lines.push('### Test Coverage');
+  lines.push('');
+  const coverageItems = [
+    { 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' }
+  ];
+  for (const item of coverageItems) {
+    const id = `prof-test-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('### Quality Gates');
+  lines.push('');
+  const gateItems = [
+    { text: 'CI quality gate: tests must pass before merge', priority: 'P0' },
+    { text: 'Block merge when generated roadmap loses checked state', priority: 'P0' },
+    { text: 'Add professional renderer snapshot tests', priority: 'P1' }
+  ];
+  for (const item of gateItems) {
+    const id = `prof-test-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+}
+
+function renderSection9Distribution(model, lines) {
+  lines.push(sectionHeader(9, 'Distribution Roadmap'));
+  lines.push('');
+
+  lines.push('### npm Registry');
+  lines.push('');
+  const npmItems = [
+    { text: 'Publish to npm registry with stable semver', priority: 'P0' },
+    { text: 'Ensure CLI binary is correctly linked in package.json `bin`', priority: 'P0' }
+  ];
+  for (const item of npmItems) {
+    const id = `prof-dist-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('### Release Process');
+  lines.push('');
+  const releaseItems = [
+    { text: 'Tag git releases aligned with npm publish', priority: 'P1' },
+    { text: 'Document install instructions for npm global and npx usage', priority: 'P1' }
+  ];
+  for (const item of releaseItems) {
+    const id = `prof-dist-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+}
+
+function renderSection10Documentation(model, lines) {
+  lines.push(sectionHeader(10, 'Documentation Roadmap'));
+  lines.push('');
+
+  lines.push('### Core Docs');
+  lines.push('');
+  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' }
+  ];
+  for (const item of coreItems) {
+    const id = `prof-doc-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('### Showcase');
+  lines.push('');
+  const showcaseItems = [
+    { text: 'docs/ use-cases cover compact and professional profiles', priority: 'P1' },
+    { text: 'Generated ROADMAP.md showcases professional Phase→Step→Task output', priority: 'P1' }
+  ];
+  for (const item of showcaseItems) {
+    const id = `prof-doc-${slugify(item.text)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(item.priority)} ${item.text} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+}
+
+function renderSection11Risks(model, lines) {
+  lines.push(sectionHeader(11, 'Risks, Constraints, and Anti-Goals'));
+  lines.push('');
+
+  lines.push('### Risks');
+  lines.push('');
+  for (let i = 0; i < model.risks.length; i += 1) {
+    const risk = model.risks[i];
+    const pri = i === 0 ? 'P0' : 'P1';
+    const id = `prof-risk-${slugify(risk)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] ${priorityLabel(pri)} ${risk} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+
+  lines.push('### Anti-Goals');
+  lines.push('');
+  for (const antiGoal of model.antiGoals) {
+    lines.push(`- ${antiGoal}`);
+  }
+  lines.push('');
+}
+
+function renderSection12SuccessCriteria(model, lines) {
+  lines.push(sectionHeader(12, '1.0 Measurable Success Criteria'));
+  lines.push('');
+
+  const criteria = model.successCriteria && model.successCriteria.length > 0
+    ? model.successCriteria
+    : [
+        'All roadmap sections render without errors for compact and professional profiles',
+        'Checked task state is preserved across regeneration',
+        'npm test passes with no failures',
+        'ROADMAP.md is generated by RoadmapSmith itself'
+      ];
+
+  for (const criterion of criteria) {
+    const id = `prof-sc-${slugify(criterion)}`;
+    lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P0]\` ${criterion} <!-- rs:task=${id} -->`);
+  }
+  lines.push('');
+}
+
+function renderProfessional(model) {
+  const projectName = (model.product && model.product.name) || 'Project';
+  const lines = [];
+
+  lines.push(`# ${projectName} Roadmap`);
+  lines.push('');
+
+  renderSection1NorthStar(model, lines);
+  renderSection2Positioning(model, lines);
+  renderSection3CurrentState(model, lines);
+  renderSection4PhasedExecution(model, lines);
+  renderSection5Milestones(model, lines);
+  renderSection6MaturityPath(model, lines);
+  renderSection7OutputContract(model, lines);
+  renderSection8Testing(model, lines);
+  renderSection9Distribution(model, lines);
+  renderSection10Documentation(model, lines);
+  renderSection11Risks(model, lines);
+  renderSection12SuccessCriteria(model, lines);
+
+  return ensureTrailingNewline(lines.join('\n')).trimEnd();
+}
+
+module.exports = { renderProfessional };