@smartmemory/compose 0.2.25-beta → 0.2.26-beta

package/bin/compose.js

@@ -1154,6 +1154,47 @@ if (cmd === 'roadmap') {
     process.exit(0)
   }
 
+  // compose roadmap graph — generate a self-contained dependency-graph HTML
+  // from feature.json + deps.yaml + frontmatter (COMP-ROADMAP-GRAPH-1).
+  if (subcmd === 'graph') {
+    const { generateRoadmapGraph, checkRoadmapGraph } = await import('../lib/roadmap-graph/index.js')
+    let cwd
+    const projIdx = args.indexOf('--project')
+    if (projIdx !== -1 && args[projIdx + 1]) {
+      cwd = resolve(args[projIdx + 1])
+    } else {
+      cwd = resolveCwdWithWorkspace(args).root
+    }
+    let out
+    const outIdx = args.indexOf('--out')
+    if (outIdx !== -1 && args[outIdx + 1]) out = args[outIdx + 1]
+    const checkMode = args.includes('--check')
+    try {
+      if (checkMode) {
+        const r = checkRoadmapGraph(cwd, { out })
+        for (const w of r.warnings) console.warn(`  warning: ${w}`)
+        if (r.matches) {
+          console.log(`roadmap-graph up to date (${r.nodeCount} nodes, ${r.edgeCount} edges): ${r.path}`)
+          process.exit(0)
+        }
+        console.error(r.diffSummary)
+        process.exit(1)
+      }
+      const r = generateRoadmapGraph(cwd, { out })
+      for (const w of r.warnings) console.warn(`  warning: ${w}`)
+      console.log(`Generated ${r.path} — ${r.nodeCount} nodes, ${r.edgeCount} edges` +
+        (r.droppedCount ? ` (${r.droppedCount} completed/superseded/killed dropped)` : ''))
+      process.exit(0)
+    } catch (err) {
+      if (err && err.code === 'DANGLING_EDGE') {
+        console.error(err.message)
+        console.error('\nFix the deps.yaml edge(s) above, or complete/register the missing feature(s).')
+        process.exit(1)
+      }
+      throw err
+    }
+  }
+
   // Default: compose roadmap (show status)
   const { parseRoadmap, filterBuildable } = await import('../lib/roadmap-parser.js')
   const { buildDag, topoSort } = await import('../lib/build-dag.js')

package/contracts/roadmap-deps.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://regression.io/compose/roadmap-deps.schema.json",
+  "title": "Roadmap graph dependency manifest (deps.yaml)",
+  "description": "Per-feature-folder edge declarations for the roadmap dependency graph. All keys optional; absent means no edges of that kind. COMP-ROADMAP-GRAPH-1.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "depends_on": {
+      "type": "array",
+      "description": "Feature codes that are prerequisites of this feature.",
+      "items": { "$ref": "#/definitions/featureCode" }
+    },
+    "concurrent_with": {
+      "type": "array",
+      "description": "Sibling feature codes with no blocking relationship.",
+      "items": { "$ref": "#/definitions/featureCode" }
+    },
+    "blocks": {
+      "type": "array",
+      "description": "Feature codes that this feature is a prerequisite of (inverse convenience).",
+      "items": { "$ref": "#/definitions/featureCode" }
+    }
+  },
+  "definitions": {
+    "featureCode": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"
+    }
+  }
+}

package/contracts/roadmap-graph-frontmatter.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://regression.io/compose/roadmap-graph-frontmatter.schema.json",
+  "title": "Roadmap graph node display metadata",
+  "description": "Per-feature display fields for the roadmap dependency graph, sourced from design.md YAML frontmatter or feature.json extension keys. All optional; extra keys ignored. COMP-ROADMAP-GRAPH-1.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable feature title."
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Drives node border weight."
+    },
+    "track": {
+      "type": "string",
+      "description": "Project-defined grouping; drives node color via the track->color map."
+    },
+    "desc": {
+      "type": "string",
+      "description": "One-paragraph blurb shown in the node tooltip."
+    }
+  }
+}

package/lib/roadmap-graph/collect.js

@@ -0,0 +1,178 @@
+/**
+ * collect.js — gather the roadmap-graph node universe + raw edges from a
+ * project's feature folders and ROADMAP.md (COMP-ROADMAP-GRAPH-1).
+ *
+ * Node universe = (feature folders with feature.json) ∪ (real-coded ROADMAP.md
+ * rows). feature.json wins on status when both exist; ROADMAP-only features get
+ * a warning + minimal display metadata. The union's code set is the dangling
+ * oracle for model.buildGraph.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { listFeatures } from '../feature-json.js';
+import { loadFeaturesDir, loadExternalPrefixes } from '../project-paths.js';
+import { parseRoadmap } from '../roadmap-parser.js';
+import { SchemaValidator } from '../../server/schema-validator.js';
+import { depsToEdges } from './model.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEPS_SCHEMA = resolve(__dirname, '../../contracts/roadmap-deps.schema.json');
+const FRONTMATTER_SCHEMA = resolve(__dirname, '../../contracts/roadmap-graph-frontmatter.schema.json');
+
+const FM_KEYS = ['name', 'priority', 'track', 'desc'];
+
+/**
+ * @param {string} cwd project root
+ * @param {string} [featuresDir] relative features dir (default from compose.json)
+ * @returns {{ nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings: string[] }}
+ */
+export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
+  const warnings = [];
+  const depsValidator = new SchemaValidator(DEPS_SCHEMA);
+  const fmValidator = new SchemaValidator(FRONTMATTER_SCHEMA);
+  const externalPrefixes = loadExternalPrefixes(cwd);
+  const isExternal = (code) => externalPrefixes.some((p) => code.startsWith(p));
+
+  /** @type {Map<string, object>} id -> collected node (rendered features only) */
+  const universe = new Map();
+  // Codes that exist as cross-project references — known (so deps to them don't
+  // dangle) but not rendered as nodes and not warned about.
+  const externalCodes = new Set();
+
+  // (a) Feature folders — authoritative source.
+  const features = listFeatures(cwd, featuresDir);
+  for (const f of features) {
+    if (!f || typeof f.code !== 'string') continue;
+    // An external-prefixed folder is a cross-project reference living here —
+    // known (so edges resolve) but never rendered as one of THIS project's nodes.
+    if (isExternal(f.code)) { externalCodes.add(f.code); continue; }
+    const folder = join(cwd, featuresDir, f.code);
+    const fm = readDisplayMetadata(folder, f, fmValidator, warnings);
+    universe.set(f.code, {
+      id: f.code,
+      status: String(f.status || 'PLANNED').toUpperCase(),
+      name: fm.name,
+      priority: fm.priority,
+      track: fm.track,
+      desc: fm.desc,
+      _hasFolder: true,
+    });
+  }
+
+  // (b) ROADMAP.md rows — fallback for features not registered as folders.
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  if (existsSync(roadmapPath)) {
+    let entries = [];
+    try { entries = parseRoadmap(readFileSync(roadmapPath, 'utf-8')); } catch { /* ignore */ }
+    for (const e of entries) {
+      if (!e.code || e.code.startsWith('_anon_')) continue;
+      if (universe.has(e.code)) continue; // folder wins
+      if (isExternal(e.code)) { externalCodes.add(e.code); continue; } // cross-project ref
+      universe.set(e.code, {
+        id: e.code,
+        status: String(e.status || 'PLANNED').toUpperCase(),
+        name: e.code,
+        priority: 'medium',
+        track: 'standalone',
+        desc: stripMd(e.description || ''),
+        _hasFolder: false,
+      });
+      warnings.push(`${e.code}: unregistered (ROADMAP.md fallback — no feature.json)`);
+    }
+  }
+
+  // Edges — only feature folders may declare deps.yaml.
+  const rawEdges = [];
+  for (const f of features) {
+    if (!f || typeof f.code !== 'string') continue;
+    if (isExternal(f.code)) continue;
+    const depsPath = join(cwd, featuresDir, f.code, 'deps.yaml');
+    if (!existsSync(depsPath)) continue;
+    let deps;
+    try {
+      deps = parseYaml(readFileSync(depsPath, 'utf-8')) || {};
+    } catch (err) {
+      warnings.push(`${f.code}: unparseable deps.yaml (${err.message}) — skipped`);
+      continue;
+    }
+    const res = depsValidator.validateRoot(deps);
+    if (!res.valid) {
+      const msg = res.errors.map((e) => `${e.instancePath || '/'} ${e.message}`).join('; ');
+      warnings.push(`${f.code}: invalid deps.yaml (${msg}) — skipped`);
+      continue;
+    }
+    rawEdges.push(...depsToEdges(f.code, deps));
+  }
+
+  // An edge endpoint matching an external prefix is a cross-project reference we
+  // cannot validate locally — treat it as known (never dangling). The node is
+  // not rendered, so model.buildGraph silently drops the edge.
+  for (const e of rawEdges) {
+    for (const code of [e.from, e.to]) {
+      if (!knownLocally(code, universe, externalCodes) && isExternal(code)) externalCodes.add(code);
+    }
+  }
+
+  const knownCodes = new Set([...universe.keys(), ...externalCodes]);
+  return { nodes: [...universe.values()], rawEdges, knownCodes, warnings };
+}
+
+function knownLocally(code, universe, externalCodes) {
+  return universe.has(code) || externalCodes.has(code);
+}
+
+/**
+ * Display metadata precedence: design.md YAML frontmatter > feature.json keys >
+ * defaults. Returns { name, priority, track, desc }.
+ */
+function readDisplayMetadata(folder, feature, fmValidator, warnings) {
+  const fromFeature = pick(feature, FM_KEYS);
+  const fromDesign = readDesignFrontmatter(folder, fmValidator, feature.code, warnings);
+  const merged = { ...fromFeature, ...fromDesign };
+  return {
+    name: merged.name || firstLine(feature.description) || feature.code,
+    priority: merged.priority,
+    track: merged.track,
+    desc: merged.desc || stripMd(feature.description || ''),
+  };
+}
+
+function readDesignFrontmatter(folder, fmValidator, code, warnings) {
+  const designPath = join(folder, 'design.md');
+  if (!existsSync(designPath)) return {};
+  const text = readFileSync(designPath, 'utf-8');
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  let data;
+  try { data = parseYaml(m[1]) || {}; } catch { return {}; }
+  if (typeof data !== 'object' || Array.isArray(data)) return {};
+  const res = fmValidator.validateRoot(data);
+  if (!res.valid) {
+    warnings.push(`${code}: invalid design.md frontmatter — ignored`);
+    return {};
+  }
+  return pick(data, FM_KEYS);
+}
+
+function pick(obj, keys) {
+  const out = {};
+  for (const k of keys) {
+    if (obj && obj[k] != null && obj[k] !== '') out[k] = obj[k];
+  }
+  return out;
+}
+
+function firstLine(s) {
+  return stripMd(String(s || '').split('\n')[0] || '').trim();
+}
+
+// Strip the heaviest markdown so node names/descs render cleanly as plain text.
+function stripMd(s) {
+  return String(s || '')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/^\s*#+\s*/, '')
+    .trim();
+}

package/lib/roadmap-graph/config.js

@@ -0,0 +1,57 @@
+/**
+ * config.js — read `.compose/compose.json#roadmap_graph` display config for the
+ * roadmap dependency graph generator (COMP-ROADMAP-GRAPH-1).
+ *
+ * All fields optional. Defaults keep the generator usable with zero config.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+// Default track -> accent color map. Projects override via
+// compose.json#roadmap_graph.tracks. 'standalone' is the fallback track.
+export const DEFAULT_TRACKS = {
+  knowledge: '#0ea5e9',
+  distribution: '#10b981',
+  governance: '#a855f7',
+  agent: '#f59e0b',
+  worker: '#ef4444',
+  platform: '#ec4899',
+  developer: '#f97316',
+  async: '#6b7280',
+  standalone: '#64748b',
+};
+
+export const DEFAULT_OUT = 'roadmap-graph.html';
+
+/**
+ * Resolve graph display config for a project root.
+ * @param {string} cwd
+ * @returns {{ title: string, subtitle: string, tracks: Record<string,string>, out: string }}
+ */
+export function loadGraphConfig(cwd) {
+  let raw = {};
+  const cfgPath = join(cwd, '.compose', 'compose.json');
+  if (existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+      raw = (cfg && typeof cfg.roadmap_graph === 'object' && cfg.roadmap_graph) || {};
+    } catch { /* fall through to defaults */ }
+  }
+  const projectName = deriveProjectName(cwd, cfgPath);
+  return {
+    title: typeof raw.title === 'string' && raw.title ? raw.title : `${projectName} — Roadmap Dependency Graph`,
+    subtitle: typeof raw.subtitle === 'string' ? raw.subtitle : '',
+    tracks: { ...DEFAULT_TRACKS, ...(raw.tracks && typeof raw.tracks === 'object' ? raw.tracks : {}) },
+    out: typeof raw.out === 'string' && raw.out ? raw.out : DEFAULT_OUT,
+  };
+}
+
+function deriveProjectName(cwd, cfgPath) {
+  if (existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+      if (typeof cfg.workspaceId === 'string' && cfg.workspaceId) return cfg.workspaceId;
+    } catch { /* ignore */ }
+  }
+  return basename(cwd) || 'Project';
+}

package/lib/roadmap-graph/index.js

@@ -0,0 +1,93 @@
+/**
+ * index.js — public API for the roadmap dependency graph generator
+ * (COMP-ROADMAP-GRAPH-1).
+ *
+ *   generateRoadmapGraph(cwd, opts) — render + atomic-write the HTML
+ *   checkRoadmapGraph(cwd, opts)    — render in-memory, diff vs on-disk
+ *
+ * Both throw DanglingEdgeError (code DANGLING_EDGE) when an edge points at an
+ * unknown feature — the Cytoscape-crash bug class this feature kills.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join, isAbsolute, dirname } from 'node:path';
+import { loadFeaturesDir } from '../project-paths.js';
+import { collectGraphInputs } from './collect.js';
+import { buildGraph } from './model.js';
+import { renderGraphHtml } from './render.js';
+import { loadGraphConfig } from './config.js';
+
+/**
+ * Build the HTML + graph stats for a project without writing to disk.
+ * @param {string} cwd
+ * @returns {{ html: string, nodes: object[], edges: object[], dropped: string[], warnings: string[], config: object }}
+ */
+export function buildRoadmapGraph(cwd) {
+  const featuresDir = loadFeaturesDir(cwd);
+  const inputs = collectGraphInputs(cwd, featuresDir);
+  const graph = buildGraph(inputs); // throws DanglingEdgeError
+  const config = loadGraphConfig(cwd);
+  const html = renderGraphHtml({ nodes: graph.nodes, edges: graph.edges, config });
+  return { html, nodes: graph.nodes, edges: graph.edges, dropped: graph.dropped, warnings: inputs.warnings, config };
+}
+
+/**
+ * Generate and atomically write roadmap-graph.html.
+ * @param {string} cwd project root
+ * @param {{ out?: string }} [opts] out path (relative to cwd unless absolute); defaults to config.out
+ * @returns {{ path: string, nodeCount: number, edgeCount: number, droppedCount: number, warnings: string[] }}
+ */
+export function generateRoadmapGraph(cwd, opts = {}) {
+  const built = buildRoadmapGraph(cwd);
+  const outRel = opts.out || built.config.out;
+  const outPath = isAbsolute(outRel) ? outRel : join(cwd, outRel);
+  atomicWrite(outPath, built.html);
+  return {
+    path: outPath,
+    nodeCount: built.nodes.length,
+    edgeCount: built.edges.length,
+    droppedCount: built.dropped.length,
+    warnings: built.warnings,
+  };
+}
+
+/**
+ * Render in-memory and compare to the on-disk file.
+ * @param {string} cwd
+ * @param {{ out?: string }} [opts]
+ * @returns {{ matches: boolean, path: string, exists: boolean, diffSummary: string, nodeCount: number, edgeCount: number, warnings: string[] }}
+ */
+export function checkRoadmapGraph(cwd, opts = {}) {
+  const built = buildRoadmapGraph(cwd);
+  const outRel = opts.out || built.config.out;
+  const outPath = isAbsolute(outRel) ? outRel : join(cwd, outRel);
+  const exists = existsSync(outPath);
+  const onDisk = exists ? readFileSync(outPath, 'utf-8') : null;
+  const matches = exists && onDisk === built.html;
+  let diffSummary = '';
+  if (!exists) diffSummary = `missing: ${outPath} not generated yet`;
+  else if (!matches) diffSummary = `stale: ${outPath} differs from regenerated output (run \`compose roadmap graph\`)`;
+  return {
+    matches,
+    path: outPath,
+    exists,
+    diffSummary,
+    nodeCount: built.nodes.length,
+    edgeCount: built.edges.length,
+    warnings: built.warnings,
+  };
+}
+
+function atomicWrite(outPath, content) {
+  const dir = dirname(outPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${outPath}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, content);
+    renameSync(tmp, outPath);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* tmp may not exist */ }
+    throw err;
+  }
+}
+
+export { DanglingEdgeError } from './model.js';

package/lib/roadmap-graph/model.js

@@ -0,0 +1,128 @@
+/**
+ * model.js — pure graph rules for the roadmap dependency graph
+ * (COMP-ROADMAP-GRAPH-1).
+ *
+ * Takes the collected node universe + raw edge declarations and produces the
+ * final `{ nodes, edges }` arrays the template renders — applying the drop
+ * rules and refusing to emit when an edge would dangle (the Cytoscape-crash
+ * bug class this feature kills).
+ */
+
+/** Statuses whose nodes are dropped from the graph entirely. */
+export const DROP_STATUSES = new Set(['COMPLETE', 'SUPERSEDED', 'KILLED']);
+
+/** UPPERCASE feature status -> lowercase template status vocabulary. */
+const STATUS_MAP = {
+  PLANNED: 'planned',
+  IN_PROGRESS: 'in_progress',
+  PARTIAL: 'partial',
+  PARKED: 'parked',
+  BLOCKED: 'blocked',
+};
+
+export class DanglingEdgeError extends Error {
+  /** @param {{from:string,to:string,kind:string}[]} dangling */
+  constructor(dangling) {
+    const lines = dangling.map((d) => `  ${d.from} --${d.kind}--> ${d.to}  (${d.to} is not a known feature)`);
+    super(`roadmap-graph: refusing to emit — ${dangling.length} dangling edge(s):\n${lines.join('\n')}`);
+    this.code = 'DANGLING_EDGE';
+    this.dangling = dangling;
+  }
+}
+
+/**
+ * @typedef {object} CollectedNode
+ * @property {string} id
+ * @property {string} status      UPPERCASE source status
+ * @property {string} [name]
+ * @property {string} [priority]
+ * @property {string} [track]
+ * @property {string} [desc]
+ *
+ * @typedef {object} RawEdge
+ * @property {string} from   prerequisite (source)
+ * @property {string} to     dependent (target)
+ * @property {'dep'|'concurrent'} type
+ */
+
+/**
+ * Build the final graph from collected inputs.
+ * @param {{ nodes: CollectedNode[], rawEdges: RawEdge[], knownCodes: Set<string> }} inputs
+ * @returns {{ nodes: object[], edges: object[], dropped: string[] }}
+ * @throws {DanglingEdgeError} when any non-dropped edge points at an unknown code
+ */
+export function buildGraph({ nodes, rawEdges, knownCodes }) {
+  const known = knownCodes instanceof Set ? knownCodes : new Set(knownCodes || []);
+
+  const dropped = [];
+  const kept = new Map(); // id -> rendered node
+  for (const n of nodes) {
+    if (DROP_STATUSES.has(n.status)) {
+      dropped.push(n.id);
+      continue;
+    }
+    kept.set(n.id, renderNode(n));
+  }
+
+  const dangling = [];
+  const seen = new Set();
+  const edges = [];
+  for (const e of rawEdges) {
+    // Dangling = endpoint not a known feature anywhere (typo / never existed).
+    const fromUnknown = !known.has(e.from);
+    const toUnknown = !known.has(e.to);
+    if (fromUnknown || toUnknown) {
+      dangling.push({ from: e.from, to: e.to, kind: e.type });
+      continue;
+    }
+    // Known but not rendered (dropped by status) -> silently drop the edge.
+    if (!kept.has(e.from) || !kept.has(e.to)) continue;
+
+    const key = `${e.type}|${e.from}|${e.to}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ source: e.from, target: e.to, type: e.type });
+  }
+
+  if (dangling.length > 0) throw new DanglingEdgeError(dangling);
+
+  const nodeList = [...kept.values()];
+  // kept preserves insertion order (already phase->position->code sorted by caller);
+  // sort edges for deterministic, idempotent output.
+  edges.sort((a, b) =>
+    a.type.localeCompare(b.type) ||
+    a.source.localeCompare(b.source) ||
+    a.target.localeCompare(b.target));
+
+  return { nodes: nodeList, edges, dropped };
+}
+
+function renderNode(n) {
+  const name = n.name || n.id;
+  const status = STATUS_MAP[n.status] || String(n.status || '').toLowerCase();
+  const priority = ['high', 'medium', 'low'].includes(n.priority) ? n.priority : 'medium';
+  const track = n.track || 'standalone';
+  const desc = n.desc || '';
+  // label: code + short name, wrapped by the template at render time.
+  const shortName = name.length > 48 ? name.slice(0, 45) + '…' : name;
+  return { id: n.id, label: `${n.id}\n${shortName}`, name, status, priority, track, desc };
+}
+
+/**
+ * Normalize a feature's deps.yaml into directed raw edges.
+ * @param {string} code
+ * @param {{depends_on?:string[], concurrent_with?:string[], blocks?:string[]}} deps
+ * @returns {RawEdge[]}
+ */
+export function depsToEdges(code, deps) {
+  const out = [];
+  const arr = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x) : []);
+  for (const dep of arr(deps?.depends_on)) out.push({ from: dep, to: code, type: 'dep' });
+  for (const blk of arr(deps?.blocks)) out.push({ from: code, to: blk, type: 'dep' });
+  for (const sib of arr(deps?.concurrent_with)) {
+    // canonicalize undirected concurrent edges so A+B never emit twice
+    const [a, b] = code < sib ? [code, sib] : [sib, code];
+    out.push({ from: a, to: b, type: 'concurrent' });
+  }
+  return out;
+}

package/lib/roadmap-graph/render.js

@@ -0,0 +1,60 @@
+/**
+ * render.js — render the roadmap-graph HTML from the packaged template by
+ * replacing the @generated data regions (COMP-ROADMAP-GRAPH-1).
+ *
+ * Deterministic: identical inputs produce byte-identical output (no wall-clock
+ * timestamps), which underpins the `--check` idempotency guarantee.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_PATH = resolve(__dirname, 'template.html');
+
+const REGIONS = {
+  config: ['/* @generated:config:start */', '/* @generated:config:end */'],
+  nodes: ['/* @generated:nodes:start */', '/* @generated:nodes:end */'],
+  edges: ['/* @generated:edges:start */', '/* @generated:edges:end */'],
+};
+
+/**
+ * @param {{ nodes: object[], edges: object[], config: object }} input
+ * @returns {string} full HTML document
+ */
+export function renderGraphHtml({ nodes, edges, config }) {
+  let html = readFileSync(TEMPLATE_PATH, 'utf-8');
+  const cfg = {
+    title: config?.title || 'Roadmap Dependency Graph',
+    subtitle: config?.subtitle || '',
+    tracks: config?.tracks || {},
+  };
+  html = replaceRegion(html, 'config', `const GRAPH_CONFIG = ${stable(cfg)};`);
+  html = replaceRegion(html, 'nodes', `const nodes = ${stable(nodes)};`);
+  html = replaceRegion(html, 'edges', `const edges = ${stable(edges)};`);
+  return html;
+}
+
+function replaceRegion(html, key, body) {
+  const [start, end] = REGIONS[key];
+  const s = html.indexOf(start);
+  const e = html.indexOf(end);
+  if (s === -1 || e === -1 || e < s) {
+    throw new Error(`roadmap-graph template missing @generated:${key} region`);
+  }
+  return html.slice(0, s + start.length) + '\n' + body + '\n' + html.slice(e);
+}
+
+// Stable JSON serialization with sorted object keys for deterministic output.
+function stable(value) {
+  return JSON.stringify(sortKeys(value), null, 2);
+}
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}

package/lib/roadmap-graph/template.html

@@ -0,0 +1,194 @@
+<!DOCTYPE html>
+<!--
+  Roadmap Dependency Graph — generated by `compose roadmap graph` (COMP-ROADMAP-GRAPH-1).
+  DO NOT hand-edit the @generated data regions below; they are overwritten on
+  every run. Re-generate with: compose roadmap graph
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Roadmap Dependency Graph</title>
+<script src="https://cdn.jsdelivr.net/npm/cytoscape@3.28.1/dist/cytoscape.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dagre@0.8.5/dist/dagre.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/cytoscape-dagre@2.5.0/cytoscape-dagre.min.js"></script>
+<style>
+  :root { --bg:#0f172a; --panel:#1e293b; --ink:#e2e8f0; --muted:#94a3b8; --line:#334155; }
+  * { box-sizing: border-box; }
+  html, body { margin:0; height:100%; background:var(--bg); color:var(--ink);
+    font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; }
+  header { padding:12px 18px; border-bottom:1px solid var(--line); display:flex;
+    align-items:baseline; gap:14px; flex-wrap:wrap; }
+  header h1 { font-size:15px; margin:0; font-weight:600; }
+  header .sub { color:var(--muted); font-size:12px; }
+  header .controls { margin-left:auto; display:flex; gap:6px; }
+  button { background:var(--panel); color:var(--ink); border:1px solid var(--line);
+    border-radius:6px; padding:4px 9px; font-size:12px; cursor:pointer; }
+  button:hover { border-color:#64748b; }
+  #cy { position:absolute; top:49px; bottom:0; left:0; right:0; }
+  #legend { position:absolute; left:14px; bottom:14px; background:rgba(30,41,59,.92);
+    border:1px solid var(--line); border-radius:8px; padding:10px 12px; font-size:11px;
+    color:var(--muted); line-height:1.7; z-index:5; }
+  #legend b { color:var(--ink); }
+  .swatch { display:inline-block; width:9px; height:9px; border-radius:2px; margin-right:5px;
+    vertical-align:middle; }
+  #tracks { position:absolute; right:14px; bottom:14px; background:rgba(30,41,59,.92);
+    border:1px solid var(--line); border-radius:8px; padding:10px 12px; font-size:11px;
+    color:var(--muted); max-height:45vh; overflow:auto; z-index:5; }
+  #tooltip { position:absolute; display:none; max-width:320px; background:#020617;
+    border:1px solid var(--line); border-radius:8px; padding:10px 12px; font-size:12px;
+    color:var(--ink); z-index:10; pointer-events:none; box-shadow:0 8px 24px rgba(0,0,0,.5); }
+  #tooltip .tid { font-weight:600; }
+  #tooltip .badges { margin:4px 0; }
+  #tooltip .badge { display:inline-block; font-size:10px; padding:1px 6px; border-radius:10px;
+    background:#1e293b; margin-right:4px; color:var(--muted); }
+  #tooltip .d { color:var(--muted); margin-top:5px; max-height:140px; overflow:hidden; }
+  #empty { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
+    color:var(--muted); font-size:13px; }
+</style>
+</head>
+<body>
+<header>
+  <h1 id="title">Roadmap Dependency Graph</h1>
+  <span class="sub" id="subtitle"></span>
+  <div class="controls">
+    <button id="fit">Fit</button>
+    <button id="zin">+</button>
+    <button id="zout">−</button>
+  </div>
+</header>
+<div id="cy"></div>
+<div id="empty" style="display:none">No active features to graph.</div>
+<div id="legend">
+  <div><b>Status</b></div>
+  <div><span class="swatch" style="background:#3b82f6"></span>planned</div>
+  <div><span class="swatch" style="background:#22c55e"></span>in&nbsp;progress</div>
+  <div><span class="swatch" style="background:#f59e0b"></span>partial</div>
+  <div><span class="swatch" style="background:#ef4444"></span>blocked</div>
+  <div><span class="swatch" style="background:#6b7280"></span>parked</div>
+  <div style="margin-top:6px"><b>Edges</b></div>
+  <div>→ depends on &nbsp;·&nbsp; ⇢ concurrent</div>
+  <div style="margin-top:4px">border weight = priority</div>
+</div>
+<div id="tracks"></div>
+<div id="tooltip"></div>
+<script>
+/* @generated:config:start */
+const GRAPH_CONFIG = {};
+/* @generated:config:end */
+/* @generated:nodes:start */
+const nodes = [];
+/* @generated:nodes:end */
+/* @generated:edges:start */
+const edges = [];
+/* @generated:edges:end */
+
+const STATUS_BORDER = { planned:'#3b82f6', in_progress:'#22c55e', partial:'#f59e0b',
+  blocked:'#ef4444', parked:'#6b7280' };
+
+function hexToRgb(h){ const m=/^#?([0-9a-f]{6})$/i.exec(h||''); if(!m) return [100,116,139];
+  const n=parseInt(m[1],16); return [(n>>16)&255,(n>>8)&255,n&255]; }
+function darken(h,f){ const [r,g,b]=hexToRgb(h);
+  return 'rgb('+Math.round(r*f)+','+Math.round(g*f)+','+Math.round(b*f)+')'; }
+
+document.getElementById('title').textContent = GRAPH_CONFIG.title || 'Roadmap Dependency Graph';
+document.getElementById('subtitle').textContent = GRAPH_CONFIG.subtitle || '';
+
+const tracks = GRAPH_CONFIG.tracks || {};
+const trackStyles = Object.keys(tracks).map(t => ({
+  selector: 'node[track="'+t+'"]',
+  style: { 'background-color': darken(tracks[t], 0.22) }
+}));
+
+const elements = [
+  ...nodes.map(n => ({ data: n })),
+  ...edges.map(e => ({ data: e })),
+];
+
+if (nodes.length === 0) { document.getElementById('empty').style.display = 'flex'; }
+
+const cy = cytoscape({
+  container: document.getElementById('cy'),
+  elements,
+  wheelSensitivity: 0.2,
+  style: [
+    { selector: 'node', style: {
+      'label':'data(label)','text-valign':'center','text-halign':'center','font-size':'9px',
+      'font-weight':'500','color':'#e2e8f0','text-wrap':'wrap','text-max-width':'92px',
+      'width':'112px','height':'48px','shape':'round-rectangle','background-color':'#1e293b',
+      'border-color':'#3b82f6','border-width':2,'border-style':'solid' } },
+    ...trackStyles,
+    { selector: 'node[status="planned"]', style:{ 'border-color': STATUS_BORDER.planned } },
+    { selector: 'node[status="in_progress"]', style:{ 'border-color': STATUS_BORDER.in_progress } },
+    { selector: 'node[status="partial"]', style:{ 'border-color': STATUS_BORDER.partial } },
+    { selector: 'node[status="blocked"]', style:{ 'border-color': STATUS_BORDER.blocked } },
+    { selector: 'node[status="parked"]', style:{ 'border-color': STATUS_BORDER.parked, 'opacity':0.78 } },
+    { selector: 'node[priority="high"]', style:{ 'border-width':3 } },
+    { selector: 'node[priority="medium"]', style:{ 'border-width':2 } },
+    { selector: 'node[priority="low"]', style:{ 'border-width':1 } },
+    { selector: 'edge[type="dep"]', style:{ 'width':1.5,'line-color':'#475569',
+      'target-arrow-color':'#475569','target-arrow-shape':'triangle','arrow-scale':0.9,
+      'curve-style':'bezier' } },
+    { selector: 'edge[type="concurrent"]', style:{ 'width':1.4,'line-color':'#64748b',
+      'line-style':'dashed','line-dash-pattern':[6,3],'target-arrow-shape':'none',
+      'curve-style':'bezier' } },
+    { selector: '.dim', style:{ 'opacity':0.12 } },
+  ],
+  layout: { name:'dagre', rankDir:'LR', nodeSep:28, rankSep:68, edgeSep:10, padding:20,
+    animate:false, fit:true },
+});
+
+// track panel
+const tp = document.getElementById('tracks');
+const usedTracks = [...new Set(nodes.map(n => n.track))].filter(Boolean).sort();
+if (usedTracks.length) {
+  tp.innerHTML = '<div><b style="color:var(--ink)">Tracks</b></div>' + usedTracks.map(t =>
+    '<div><span class="swatch" style="background:'+(tracks[t]||'#64748b')+'"></span>'+t+'</div>').join('');
+} else { tp.style.display = 'none'; }
+
+// tooltip
+const tip = document.getElementById('tooltip');
+cy.on('mouseover', 'node', (ev) => {
+  const d = ev.target.data();
+  // depends-on / unblocks are directed 'dep' edges only; concurrent edges are
+  // undirected (canonicalized order) so list their peers separately.
+  const deps = ev.target.incomers('edge[type="dep"]').sources().map(n => n.data('id'));
+  const unblocks = ev.target.outgoers('edge[type="dep"]').targets().map(n => n.data('id'));
+  const concurrent = ev.target.connectedEdges('edge[type="concurrent"]')
+    .connectedNodes().filter(n => n.id() !== ev.target.id()).map(n => n.data('id'));
+  tip.innerHTML = '<div class="tid">'+esc(d.id)+'</div>'
+    + '<div>'+esc(d.name||'')+'</div>'
+    + '<div class="badges"><span class="badge">'+esc(d.status)+'</span>'
+    + '<span class="badge">'+esc(d.priority)+'</span><span class="badge">'+esc(d.track)+'</span></div>'
+    + (deps.length ? '<div class="d"><b>depends on:</b> '+esc(deps.join(', '))+'</div>' : '')
+    + (unblocks.length ? '<div class="d"><b>unblocks:</b> '+esc(unblocks.join(', '))+'</div>' : '')
+    + (concurrent.length ? '<div class="d"><b>concurrent with:</b> '+esc(concurrent.join(', '))+'</div>' : '')
+    + (d.desc ? '<div class="d">'+esc(d.desc)+'</div>' : '');
+  tip.style.display = 'block';
+});
+cy.on('mouseout', 'node', () => { tip.style.display = 'none'; });
+cy.on('mousemove', (ev) => {
+  if (tip.style.display !== 'block') return;
+  const x = ev.originalEvent.clientX + 14, y = ev.originalEvent.clientY + 14;
+  tip.style.left = Math.min(x, window.innerWidth - 340) + 'px';
+  tip.style.top = Math.min(y, window.innerHeight - 160) + 'px';
+});
+
+// click to highlight dependency chain
+cy.on('tap', 'node', (ev) => {
+  const n = ev.target;
+  const chain = n.predecessors().union(n.successors()).union(n);
+  cy.elements().addClass('dim');
+  chain.removeClass('dim');
+});
+cy.on('tap', (ev) => { if (ev.target === cy) cy.elements().removeClass('dim'); });
+
+document.getElementById('fit').onclick = () => cy.fit(undefined, 30);
+document.getElementById('zin').onclick = () => cy.zoom(cy.zoom() * 1.2);
+document.getElementById('zout').onclick = () => cy.zoom(cy.zoom() / 1.2);
+
+function esc(s){ return String(s).replace(/[&<>"]/g, c =>
+  ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+</script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.25-beta",
+  "version": "0.2.26-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/compose-mcp-tools.js

@@ -457,6 +457,57 @@ export async function toolValidateProject(args = {}) {
   return { ...finalResult, reconcile };
 }
 
+// COMP-ROADMAP-GRAPH-1: generate / verify the roadmap dependency graph HTML.
+// Returns small summaries only (counts + warning/dangling lists) — never the
+// HTML body, which would blow the MCP response token cap.
+export async function toolRoadmapGraph({ project, out } = {}) {
+  const { generateRoadmapGraph } = await import('../lib/roadmap-graph/index.js');
+  const cwd = project || getTargetRoot();
+  try {
+    const r = generateRoadmapGraph(cwd, { out });
+    return {
+      path: r.path,
+      nodeCount: r.nodeCount,
+      edgeCount: r.edgeCount,
+      droppedCount: r.droppedCount,
+      warnings: r.warnings,
+    };
+  } catch (err) {
+    if (err && err.code === 'DANGLING_EDGE') {
+      const e = new Error(err.message);
+      e.code = 'DANGLING_EDGE';
+      e.dangling = err.dangling;
+      throw e;
+    }
+    throw err;
+  }
+}
+
+export async function toolRoadmapGraphCheck({ project, out } = {}) {
+  const { checkRoadmapGraph } = await import('../lib/roadmap-graph/index.js');
+  const cwd = project || getTargetRoot();
+  try {
+    const r = checkRoadmapGraph(cwd, { out });
+    return {
+      matches: r.matches,
+      exists: r.exists,
+      path: r.path,
+      diffSummary: r.diffSummary,
+      nodeCount: r.nodeCount,
+      edgeCount: r.edgeCount,
+      warnings: r.warnings,
+    };
+  } catch (err) {
+    if (err && err.code === 'DANGLING_EDGE') {
+      const e = new Error(err.message);
+      e.code = 'DANGLING_EDGE';
+      e.dangling = err.dangling;
+      throw e;
+    }
+    throw err;
+  }
+}
+
 export async function toolBindSession({ featureCode, profile } = {}) {
   let result;
   try {

package/server/compose-mcp.js

@@ -59,6 +59,8 @@ import {
   toolGetCompletions,
   toolValidateFeature,
   toolValidateProject,
+  toolRoadmapGraph,
+  toolRoadmapGraphCheck,
   toolSetWorkspace,
   toolGetWorkspace,
   toolWriteCheckpoint,
@@ -383,6 +385,28 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'roadmap_graph',
+    description: 'COMP-ROADMAP-GRAPH-1: generate a self-contained roadmap dependency-graph HTML from feature.json status/phase + per-feature deps.yaml edges + display frontmatter. Drops COMPLETE/SUPERSEDED/KILLED nodes; refuses (DANGLING_EDGE) when any edge points at an unknown feature. Deterministic/idempotent. Returns a small summary (path + counts + warnings), never the HTML body.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project root path. Default: current workspace.' },
+        out: { type: 'string', description: 'Output HTML path (relative to project root unless absolute). Default: compose.json#roadmap_graph.out or roadmap-graph.html.' },
+      },
+    },
+  },
+  {
+    name: 'roadmap_graph_check',
+    description: 'COMP-ROADMAP-GRAPH-1: render the roadmap graph in-memory and diff against the on-disk HTML without writing. Returns { matches, exists, diffSummary, counts, warnings }. matches:false means the file is stale/missing — run roadmap_graph. Raises DANGLING_EDGE on a bad edge.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project root path. Default: current workspace.' },
+        out: { type: 'string', description: 'Output HTML path to compare against. Default: compose.json#roadmap_graph.out or roadmap-graph.html.' },
+      },
+    },
+  },
   {
     name: 'propose_followup',
     description: 'File a follow-up feature against a parent. Auto-numbers the next code in the parent\'s namespace (parent_code-N), adds the ROADMAP row, links surfaced_by from new → parent, and scaffolds design.md with a "## Why" rationale block. Idempotent on (parent_code, idempotency_key); resumes across partial failures via an inflight ledger.',
@@ -709,6 +733,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_completions':          result = await toolGetCompletions(args); break;
       case 'validate_feature':         result = await toolValidateFeature(args); break;
       case 'validate_project':         result = await toolValidateProject(args); break;
+      case 'roadmap_graph':            result = await toolRoadmapGraph(args); break;
+      case 'roadmap_graph_check':      result = await toolRoadmapGraphCheck(args); break;
       case 'propose_followup':         result = await toolProposeFollowup(args); break;
       case 'write_checkpoint':         result = await toolWriteCheckpoint(args); break;
       case 'compose_resume':           result = await toolComposeResume(args); break;

package/server/mcp-tool-policy.js

@@ -34,7 +34,7 @@ const REVIEWER_ALLOW = [
   'get_vision_items', 'get_item_detail', 'get_phase_summary', 'get_blocked_items',
   'get_current_session', 'get_feature_lifecycle', 'get_feature_artifacts', 'get_feature_links',
   'get_pending_gates', 'get_changelog_entries', 'get_journal_entries', 'get_completions',
-  'validate_feature', 'validate_project', 'roadmap_diff', 'assess_feature_artifacts',
+  'validate_feature', 'validate_project', 'roadmap_diff', 'roadmap_graph_check', 'assess_feature_artifacts',
   'set_workspace', 'get_workspace', 'bind_session',
 ];