@smartmemory/compose 0.1.4-beta → 0.1.5-beta

package/lib/build.js

@@ -27,7 +27,8 @@ import { CliProgress } from './cli-progress.js';
 import { BuildStreamWriter } from './build-stream-writer.js';
 import { resolveAgentConfig } from './agent-string.js';
 import { installFactoryShim } from './connector-factory-shim.js';
-import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers } from './sections.js';
+import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers, analyzeRollup, writeRollup } from './sections.js';
+import { SECTIONS_DIR } from './constants.js';
 
 import YAML from 'yaml';
 import { updateFeature, readFeature, writeFeature } from './feature-json.js';
@@ -937,6 +938,7 @@ export async function runBuild(featureCode, opts = {}) {
           // COMP-PLAN-SECTIONS T7: append "What Was Built" trailers to all
           // section files after a successful ship. No-op if sections/ doesn't
           // exist. Wrapped so trailer-append failure never fails the ship.
+          let postShipAnalysis = null;
           try {
             if (shipResult.commit) {
               const trailerResult = appendSectionTrailers({
@@ -945,18 +947,44 @@ export async function runBuild(featureCode, opts = {}) {
                 filesChanged: shipResult.filesChanged ?? [],
                 cwd: agentCwd,
               });
+              // COMP-PLAN-SECTIONS-REPORT T4: read-only analyzer feeds the
+              // trailer event with `unattributed` and primes writeRollup.
+              const sectionsDir = join(featureDir, SECTIONS_DIR);
+              postShipAnalysis = analyzeRollup({
+                sectionsDir,
+                filesChanged: shipResult.filesChanged ?? [],
+              });
               if (trailerResult.trailed?.length > 0) {
-                streamWriter.write({
+                const payload = {
                   type: 'build_sections_trailed',
                   featureCode,
                   count: trailerResult.trailed.length,
                   sections: trailerResult.trailed,
-                });
+                };
+                if (postShipAnalysis && Array.isArray(postShipAnalysis.unattributed)) {
+                  payload.unattributed = postShipAnalysis.unattributed;
+                }
+                streamWriter.write(payload);
               }
             }
           } catch (err) {
             try { streamWriter.write({ type: 'build_error', message: `sections trailer append failed: ${err.message}`, stepId: 'ship' }); } catch { /* ignore */ }
           }
+          // COMP-PLAN-SECTIONS-REPORT T4: roll-up write isolated in its own
+          // try/catch — failure must not suppress the trailer-success event.
+          try {
+            if (shipResult.commit && postShipAnalysis) {
+              const today = new Date().toISOString().slice(0, 10);
+              writeRollup({
+                featureDir,
+                analysis: postShipAnalysis,
+                commit: shipResult.commit,
+                date: today,
+              });
+            }
+          } catch (err) {
+            try { streamWriter.write({ type: 'build_error', message: `sections rollup write failed: ${err.message}`, stepId: 'ship' }); } catch { /* ignore */ }
+          }
           // COMP-HEALTH: collect plan_completion signal from ship result (if present)
           if (shipResult.planCompletionPct != null || shipResult.plan_completion_pct != null) {
             buildSignals.plan_completion = {

package/lib/feature-events.js

@@ -0,0 +1,114 @@
+/**
+ * feature-events.js — append-only audit log for feature-management mutations.
+ *
+ * One JSONL row per mutation. Filed by COMP-MCP-FEATURE-MGMT writers
+ * (add_roadmap_entry, set_feature_status, etc.) and read by `roadmap_diff`
+ * plus future `validate_feature`.
+ *
+ * File: <cwd>/.compose/data/feature-events.jsonl
+ *
+ * Event row shape (additive — extra fields are allowed and preserved by
+ * readers, so individual writers can attach context-specific metadata):
+ *   {
+ *     ts: ISO string,
+ *     tool: 'add_roadmap_entry' | 'set_feature_status' | ...,
+ *     code?: string,
+ *     from?: string,         // status transitions
+ *     to?: string,
+ *     reason?: string,
+ *     actor: string,         // process.env.COMPOSE_ACTOR || 'mcp:agent'
+ *     idempotency_key?: string,
+ *     ...
+ *   }
+ */
+
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+function eventsFile(cwd) {
+  return join(cwd, '.compose', 'data', 'feature-events.jsonl');
+}
+
+function actor() {
+  return process.env.COMPOSE_ACTOR || 'mcp:agent';
+}
+
+/**
+ * Append an event to the audit log. Caller supplies tool + payload; ts and
+ * actor are stamped here.
+ *
+ * @param {string} cwd
+ * @param {object} event - must include `tool`; other fields are passed through
+ * @returns {object} the row that was written (with ts + actor stamped)
+ */
+export function appendEvent(cwd, event) {
+  if (!event || typeof event.tool !== 'string' || !event.tool) {
+    throw new Error('feature-events.appendEvent: event.tool is required');
+  }
+
+  const path = eventsFile(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+
+  const row = {
+    ts: new Date().toISOString(),
+    actor: actor(),
+    ...event,
+  };
+  appendFileSync(path, JSON.stringify(row) + '\n');
+  return row;
+}
+
+/**
+ * Read events from the audit log, optionally filtered.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string|number|Date} [opts.since] - ISO date, ms since epoch, Date,
+ *   or shorthand '24h' / '7d'. Default: read all.
+ * @param {string} [opts.code] - filter to events with `code === <value>`
+ * @param {string} [opts.tool] - filter to events with `tool === <value>`
+ * @returns {Array<object>}
+ */
+export function readEvents(cwd, opts = {}) {
+  const path = eventsFile(cwd);
+  if (!existsSync(path)) return [];
+
+  const sinceMs = normalizeSince(opts.since);
+  const text = readFileSync(path, 'utf-8');
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (sinceMs !== null) {
+      const ts = Date.parse(row.ts);
+      if (Number.isNaN(ts) || ts < sinceMs) continue;
+    }
+    if (opts.code && row.code !== opts.code) continue;
+    if (opts.tool && row.tool !== opts.tool) continue;
+    out.push(row);
+  }
+  return out;
+}
+
+/**
+ * Normalize a since value to milliseconds-since-epoch, or return null for
+ * "no filter".
+ */
+export function normalizeSince(since) {
+  if (since === undefined || since === null) return null;
+  if (since instanceof Date) return since.getTime();
+  if (typeof since === 'number') return since;
+  if (typeof since !== 'string') return null;
+
+  // Shorthand: "24h" | "7d" | "30m"
+  const m = since.match(/^(\d+)([hdm])$/);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    const mult = m[2] === 'h' ? 3600_000 : m[2] === 'd' ? 86_400_000 : 60_000;
+    return Date.now() - n * mult;
+  }
+
+  const parsed = Date.parse(since);
+  return Number.isNaN(parsed) ? null : parsed;
+}

package/lib/feature-writer.js

@@ -0,0 +1,265 @@
+/**
+ * feature-writer.js — typed writers for ROADMAP / feature.json mutations.
+ *
+ * First sub-ticket of COMP-MCP-FEATURE-MGMT (COMP-MCP-ROADMAP-WRITER).
+ *
+ * Three operations:
+ *   addRoadmapEntry(cwd, args)  — register a new feature, regenerate ROADMAP
+ *   setFeatureStatus(cwd, args) — flip status with transition policy enforcement
+ *   roadmapDiff(cwd, args)      — read the audit log for a window
+ *
+ * All writes go through feature.json (canonical) + writeRoadmap()
+ * (regenerates ROADMAP.md). Mutations append to the feature-events.jsonl
+ * audit log. Idempotency keys protect against retries.
+ *
+ * No HTTP, no transport awareness — pure data + IO so the same writers can
+ * be called from MCP tools, the CLI, or future REST routes.
+ */
+
+import { readFeature, writeFeature, listFeatures, updateFeature } from './feature-json.js';
+// eslint-disable-next-line no-unused-vars
+const _listFeatures = listFeatures;
+import { writeRoadmap } from './roadmap-gen.js';
+import { appendEvent, readEvents } from './feature-events.js';
+import { checkOrInsert } from './idempotency.js';
+
+// ---------------------------------------------------------------------------
+// Status / transition policy
+// ---------------------------------------------------------------------------
+
+const STATUSES = new Set([
+  'PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE',
+  'BLOCKED', 'KILLED', 'PARKED', 'SUPERSEDED',
+]);
+
+// COMPLETE -> SUPERSEDED is force-only (per design Decision 6); not in the
+// normal transitions list. Force flag bypasses the policy and is recorded in
+// audit.
+const TRANSITIONS = {
+  PLANNED:     ['IN_PROGRESS', 'KILLED', 'PARKED'],
+  IN_PROGRESS: ['PARTIAL', 'COMPLETE', 'BLOCKED', 'KILLED', 'PARKED'],
+  PARTIAL:     ['IN_PROGRESS', 'COMPLETE', 'KILLED'],
+  COMPLETE:    [],
+  BLOCKED:     ['IN_PROGRESS', 'KILLED', 'PARKED'],
+  PARKED:      ['PLANNED', 'KILLED'],
+  KILLED:      [],
+  SUPERSEDED:  [],
+};
+
+const COMPLEXITIES = new Set(['S', 'M', 'L', 'XL']);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
+
+function validateCode(code) {
+  if (typeof code !== 'string' || !FEATURE_CODE_RE.test(code)) {
+    throw new Error(`feature-writer: invalid feature code "${code}" — must match ${FEATURE_CODE_RE}`);
+  }
+}
+
+function maybeIdempotent(args, fn) {
+  if (args.idempotency_key) {
+    return checkOrInsert(args.cwd, args.idempotency_key, fn).then(({ result }) => result);
+  }
+  return Promise.resolve().then(fn);
+}
+
+// ---------------------------------------------------------------------------
+// addRoadmapEntry
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.code
+ * @param {string} args.description
+ * @param {string} args.phase
+ * @param {string} [args.complexity]
+ * @param {string} [args.status]
+ * @param {number} [args.position]
+ * @param {string} [args.parent]
+ * @param {string[]} [args.tags]
+ * @param {string} [args.idempotency_key]
+ */
+export async function addRoadmapEntry(cwd, args) {
+  validateCode(args.code);
+  if (!args.description) throw new Error('feature-writer: description is required');
+  if (!args.phase) throw new Error('feature-writer: phase is required');
+  if (args.complexity && !COMPLEXITIES.has(args.complexity)) {
+    throw new Error(`feature-writer: invalid complexity "${args.complexity}"`);
+  }
+  const status = args.status ?? 'PLANNED';
+  if (!STATUSES.has(status)) {
+    throw new Error(`feature-writer: invalid status "${status}"`);
+  }
+
+  return maybeIdempotent({ ...args, cwd }, () => {
+    const existing = readFeature(cwd, args.code);
+    if (existing) {
+      throw new Error(`feature-writer: feature "${args.code}" already exists`);
+    }
+
+    const today = new Date().toISOString().slice(0, 10);
+    const feature = {
+      code: args.code,
+      description: args.description,
+      status,
+      phase: args.phase,
+      created: today,
+      updated: today,
+    };
+    if (args.complexity) feature.complexity = args.complexity;
+    feature.position = args.position !== undefined
+      ? args.position
+      : nextPositionInPhase(cwd, args.phase);
+    if (args.parent) feature.parent = args.parent;
+    if (args.tags && args.tags.length) feature.tags = args.tags;
+
+    writeFeature(cwd, feature);
+    const roadmapPath = writeRoadmap(cwd);
+
+    safeAppendEvent(cwd, {
+      tool: 'add_roadmap_entry',
+      code: args.code,
+      to: status,
+      phase: args.phase,
+      idempotency_key: args.idempotency_key,
+    });
+
+    return {
+      code: args.code,
+      phase: args.phase,
+      position: feature.position,
+      roadmap_path: roadmapPath,
+    };
+  });
+}
+
+// Default position for a new feature: max existing position in the same
+// phase, plus 1. Falls back to 1 when the phase is empty.
+function nextPositionInPhase(cwd, phase) {
+  const peers = _listFeatures(cwd).filter(f => f.phase === phase);
+  if (peers.length === 0) return 1;
+  const maxPos = peers.reduce((m, f) => {
+    const p = typeof f.position === 'number' ? f.position : 0;
+    return p > m ? p : m;
+  }, 0);
+  return maxPos + 1;
+}
+
+// Audit-log writes are best-effort: a failed append must NOT roll back a
+// committed mutation (per design Decision 2 and docs/mcp.md). Log a warning
+// and continue.
+function safeAppendEvent(cwd, event) {
+  try {
+    appendEvent(cwd, event);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[feature-writer] audit append failed for ${event.tool} ${event.code ?? ''}: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// setFeatureStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.code
+ * @param {string} args.status
+ * @param {string} [args.reason]
+ * @param {string} [args.commit_sha]
+ * @param {boolean} [args.force]
+ * @param {string} [args.idempotency_key]
+ */
+export async function setFeatureStatus(cwd, args) {
+  validateCode(args.code);
+  if (!STATUSES.has(args.status)) {
+    throw new Error(`feature-writer: invalid status "${args.status}" — must be one of ${[...STATUSES].join(', ')}`);
+  }
+
+  return maybeIdempotent({ ...args, cwd }, () => {
+    const feature = readFeature(cwd, args.code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.code}" not found`);
+    }
+
+    const from = feature.status;
+    const to = args.status;
+
+    if (from === to) {
+      return { code: args.code, from, to, ts: new Date().toISOString(), noop: true };
+    }
+
+    const allowed = TRANSITIONS[from] ?? [];
+    if (!allowed.includes(to) && !args.force) {
+      throw new Error(
+        `feature-writer: invalid transition for ${args.code}: ${from} → ${to}. ` +
+        `Allowed from ${from}: [${allowed.join(', ') || 'none'}]. ` +
+        `Pass force: true to override.`
+      );
+    }
+
+    const updates = { status: to };
+    if (args.commit_sha) updates.commit_sha = args.commit_sha;
+    updateFeature(cwd, args.code, updates);
+    writeRoadmap(cwd);
+
+    const event = {
+      tool: 'set_feature_status',
+      code: args.code,
+      from,
+      to,
+      idempotency_key: args.idempotency_key,
+    };
+    if (args.reason) event.reason = args.reason;
+    if (args.commit_sha) event.commit_sha = args.commit_sha;
+    if (args.force && !allowed.includes(to)) event.forced = true;
+    safeAppendEvent(cwd, event);
+
+    return { code: args.code, from, to, ts: new Date().toISOString() };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// roadmapDiff
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} cwd
+ * @param {object} [args]
+ * @param {string|number|Date} [args.since='24h']
+ * @param {string} [args.feature_code]
+ * @param {string} [args.tool]
+ */
+export function roadmapDiff(cwd, args = {}) {
+  const since = args.since ?? '24h';
+  const events = readEvents(cwd, {
+    since,
+    code: args.feature_code,
+    tool: args.tool,
+  });
+
+  const added = [];
+  const status_changed = [];
+  for (const e of events) {
+    if (e.tool === 'add_roadmap_entry' && e.code) {
+      added.push(e.code);
+    }
+    if (e.tool === 'set_feature_status' && e.code && e.from !== e.to) {
+      status_changed.push({ code: e.code, from: e.from, to: e.to });
+    }
+  }
+
+  return { events, added, status_changed };
+}
+
+// ---------------------------------------------------------------------------
+// Exports for tests / introspection
+// ---------------------------------------------------------------------------
+
+export const _internals = { TRANSITIONS, STATUSES, COMPLEXITIES };

package/lib/idempotency.js

@@ -0,0 +1,138 @@
+/**
+ * idempotency.js — caller-provided idempotency keys with persistent cache.
+ *
+ * Used by the feature-management writers (COMP-MCP-FEATURE-MGMT) so that the
+ * same logical operation invoked twice with the same key returns the first
+ * result without re-mutating state.
+ *
+ * Cache file: <cwd>/.compose/data/idempotency-keys.jsonl
+ * Lock file:  <cwd>/.compose/data/idempotency-keys.lock  (advisory mkdir lock)
+ *
+ * Each cache row is JSON: { key, result, ts }.
+ * Cap at MAX_ENTRIES (default 1000). When the cap is exceeded, the oldest
+ * entries are dropped on the next write. No background sweep — drop happens
+ * inline so we never block on large rewrites unnecessarily.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+
+const MAX_ENTRIES = 1000;
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_MS = 25;
+
+function cacheFile(cwd) {
+  return join(cwd, '.compose', 'data', 'idempotency-keys.jsonl');
+}
+
+function lockFile(cwd) {
+  return join(cwd, '.compose', 'data', 'idempotency-keys.lock');
+}
+
+function ensureDir(file) {
+  mkdirSync(dirname(file), { recursive: true });
+}
+
+/**
+ * Acquire an advisory lock by creating a directory (atomic on POSIX). Caller
+ * is responsible for releasing via the returned function. Stale locks older
+ * than LOCK_TIMEOUT_MS are forcibly cleared so a crashed prior holder can't
+ * deadlock the next caller.
+ */
+async function acquireLock(cwd) {
+  const path = lockFile(cwd);
+  ensureDir(path);
+
+  const start = Date.now();
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      mkdirSync(path);
+      return () => {
+        try { rmSync(path, { recursive: true, force: true }); } catch { /* best-effort */ }
+      };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      // Stale lock recovery: if older than timeout, clear and retry.
+      try {
+        const { mtimeMs } = (await import('fs')).statSync(path);
+        if (Date.now() - mtimeMs > LOCK_TIMEOUT_MS) {
+          rmSync(path, { recursive: true, force: true });
+          continue;
+        }
+      } catch { /* stat raced; loop and retry */ }
+
+      if (Date.now() - start > LOCK_TIMEOUT_MS) {
+        throw new Error(`idempotency lock timeout after ${LOCK_TIMEOUT_MS}ms: ${path}`);
+      }
+      await new Promise(r => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+}
+
+function readEntries(cwd) {
+  const path = cacheFile(cwd);
+  if (!existsSync(path)) return [];
+  const text = readFileSync(path, 'utf-8');
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function writeEntries(cwd, entries) {
+  const path = cacheFile(cwd);
+  ensureDir(path);
+  const trimmed = entries.length > MAX_ENTRIES
+    ? entries.slice(entries.length - MAX_ENTRIES)
+    : entries;
+  const body = trimmed.map(e => JSON.stringify(e)).join('\n') + (trimmed.length ? '\n' : '');
+  writeFileSync(path, body);
+}
+
+/**
+ * Run computeFn() at most once for a given key. If the key has been seen
+ * before, return the cached result without invoking computeFn. Caller must
+ * supply a stable key derived from the operation's intent.
+ *
+ * Intentionally async because the lock acquisition is async; computeFn may
+ * be sync or async.
+ *
+ * @param {string} cwd
+ * @param {string} key
+ * @param {() => any | Promise<any>} computeFn
+ * @returns {Promise<{ result: any, cached: boolean }>}
+ */
+export async function checkOrInsert(cwd, key, computeFn) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('idempotency: key must be a non-empty string');
+  }
+
+  const release = await acquireLock(cwd);
+  try {
+    const entries = readEntries(cwd);
+    const hit = entries.find(e => e.key === key);
+    if (hit) {
+      return { result: hit.result, cached: true };
+    }
+
+    const result = await computeFn();
+    entries.push({ key, result, ts: new Date().toISOString() });
+    writeEntries(cwd, entries);
+    return { result, cached: false };
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Test/diagnostic helper: clear the cache. Not exposed via MCP.
+ */
+export function _resetIdempotency(cwd) {
+  const path = cacheFile(cwd);
+  if (existsSync(path)) rmSync(path);
+  const lock = lockFile(cwd);
+  if (existsSync(lock)) rmSync(lock, { recursive: true, force: true });
+}

package/lib/roadmap-parser.js

@@ -5,7 +5,9 @@
  * from the markdown table format used by Compose roadmaps.
  */
 
-const SKIP_STATUSES = new Set(['COMPLETE', 'SUPERSEDED', 'PARKED']);
+// Statuses that exclude a feature from the buildable list. KILLED is
+// terminal; BLOCKED isn't buildable until unblocked.
+const SKIP_STATUSES = new Set(['COMPLETE', 'SUPERSEDED', 'PARKED', 'KILLED', 'BLOCKED']);
 
 const PHASE_HEADING_RE = /^##\s+(.+?)(?:\s+—\s+(.+))?$/;
 const MILESTONE_HEADING_RE = /^###\s+(.+?)(?:\s*:\s*(.+))?$/;

package/lib/sections.js

@@ -323,3 +323,191 @@ export function appendTrailers({ featureDir, commit, filesChanged, cwd, diffStat
 
   return result;
 }
+
+// ---------- COMP-PLAN-SECTIONS-REPORT: roll-up ----------
+
+const SECTION_FILE_RE = /^section-(\d+)-.+\.md$/;
+const ROLLUP_HEADING_RE = /^## Section Roll-up\b/m;
+const ROLLUP_NEXT_HEADING_RE = /^## /m;
+
+function parseSectionTitle(content, filename) {
+  // Expect H1 like: `# Section NN — <title>`. Fallback to filename slug.
+  const m = content.match(/^#\s+Section\s+\d+\s*[—\-:.]\s*(.+?)\s*$/m);
+  if (m && m[1]) return m[1].trim();
+  // Filename slug fallback: strip section-NN- prefix and .md suffix.
+  const fm = filename.match(/^section-\d+-(.+)\.md$/);
+  return fm ? fm[1] : filename;
+}
+
+function todayIso() {
+  const d = new Date();
+  const y = d.getFullYear();
+  const mo = String(d.getMonth() + 1).padStart(2, '0');
+  const da = String(d.getDate()).padStart(2, '0');
+  return `${y}-${mo}-${da}`;
+}
+
+/**
+ * analyzeRollup({ sectionsDir, filesChanged }) — read-only analyzer.
+ *
+ * Returns null when sectionsDir is absent OR contains no `section-NN-*.md`
+ * files. Otherwise returns:
+ *   {
+ *     sections: [{ filename, title, declared, changed, missing }],
+ *     unattributed: string[],
+ *     sectionCount: number,
+ *     sectionsWithChanges: number,    // declared.length > 0 && changed.length === declared.length
+ *     sectionsAllUnchanged: number,   // declared.length > 0 && changed.length === 0
+ *   }
+ */
+export function analyzeRollup({ sectionsDir, filesChanged } = {}) {
+  if (!sectionsDir || !fs.existsSync(sectionsDir)) return null;
+
+  const entries = fs
+    .readdirSync(sectionsDir)
+    .filter(f => SECTION_FILE_RE.test(f))
+    .sort();
+  if (entries.length === 0) return null;
+
+  const changedSet = new Set(Array.isArray(filesChanged) ? filesChanged : []);
+  const declaredUnion = new Set();
+  const sections = [];
+  let sectionsWithChanges = 0;
+  let sectionsAllUnchanged = 0;
+
+  for (const filename of entries) {
+    const fullPath = path.join(sectionsDir, filename);
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const declared = readDeclaredFiles(content);
+    for (const f of declared) declaredUnion.add(f);
+    const changed = declared.filter(f => changedSet.has(f));
+    const missing = declared.filter(f => !changedSet.has(f));
+    const title = parseSectionTitle(content, filename);
+    if (declared.length > 0 && changed.length === declared.length) sectionsWithChanges++;
+    if (declared.length > 0 && changed.length === 0) sectionsAllUnchanged++;
+    sections.push({ filename, title, declared, changed, missing });
+  }
+
+  const unattributed = [];
+  for (const f of changedSet) {
+    if (!declaredUnion.has(f)) unattributed.push(f);
+  }
+
+  return {
+    sections,
+    unattributed,
+    sectionCount: sections.length,
+    sectionsWithChanges,
+    sectionsAllUnchanged,
+  };
+}
+
+/**
+ * renderRollupBlock({ analysis, commit, date }) — pure markdown renderer.
+ * No I/O. Returns the full `## Section Roll-up` block with trailing newline.
+ */
+export function renderRollupBlock({ analysis, commit, date } = {}) {
+  const shortSha = commit && typeof commit === 'string' && commit.length > 0
+    ? `\`${commit.slice(0, 7)}\``
+    : '(commit unavailable)';
+  const dateStr = date && typeof date === 'string' && date ? date : todayIso();
+
+  const sections = analysis?.sections ?? [];
+  const unattributed = analysis?.unattributed ?? [];
+  const sectionCount = analysis?.sectionCount ?? 0;
+  const sectionsWithChanges = analysis?.sectionsWithChanges ?? 0;
+  const sectionsAllUnchanged = analysis?.sectionsAllUnchanged ?? 0;
+
+  // Section NN derived from filename prefix.
+  const indexLines = sections.map(s => {
+    const numMatch = s.filename.match(/^section-(\d+)-/);
+    const nn = numMatch ? numMatch[1] : '??';
+    const changedCount = s.changed?.length ?? 0;
+    const declaredCount = s.declared?.length ?? 0;
+    return `- [Section ${nn} — ${s.title}](sections/${s.filename}) — \`${changedCount}/${declaredCount}\` files changed`;
+  });
+
+  const unattribLines = unattributed.length
+    ? unattributed.map(f => `- \`${f}\``)
+    : ['None'];
+
+  const lines = [
+    `## Section Roll-up`,
+    ``,
+    `**Commit:** ${shortSha}`,
+    `**Date:** ${dateStr}`,
+    `**Sections:** ${sectionCount} total — ${sectionsWithChanges} with changes / ${sectionsAllUnchanged} with no declared changes`,
+    ``,
+    `### Index`,
+    ``,
+    ...indexLines,
+    ``,
+    `### Unattributed files this commit`,
+    ``,
+    ...unattribLines,
+    ``,
+    `### Deviations summary`,
+    ``,
+    `- **Sections with all declared files changed:** ${sectionsWithChanges}`,
+    `- **Sections with declared files that did NOT change:** ${sectionsAllUnchanged}`,
+    `- **Files changed but undeclared:** ${unattributed.length}`,
+    ``,
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * writeRollup({ featureDir, analysis, commit, date }) — atomic same-directory
+ * temp+rename writer for `<featureDir>/report.md`.
+ *
+ * Returns null when analysis is null OR sectionCount === 0.
+ * Otherwise replaces an existing `## Section Roll-up` block in place
+ * (boundary: heading → next `^## ` heading or EOF) or appends if absent.
+ * Returns { written: true, path }.
+ */
+export function writeRollup({ featureDir, analysis, commit, date } = {}) {
+  if (!featureDir) return null;
+  if (!analysis || analysis.sectionCount === 0) return null;
+
+  const block = renderRollupBlock({ analysis, commit, date });
+  const reportPath = path.join(featureDir, 'report.md');
+  const tmpPath = path.join(featureDir, 'report.md.tmp');
+
+  let existing = '';
+  if (fs.existsSync(reportPath)) {
+    existing = fs.readFileSync(reportPath, 'utf8');
+  }
+
+  let next;
+  const headingMatch = existing.match(ROLLUP_HEADING_RE);
+  if (headingMatch && typeof headingMatch.index === 'number') {
+    const start = headingMatch.index;
+    const after = existing.slice(start + headingMatch[0].length);
+    const nextMatch = after.match(ROLLUP_NEXT_HEADING_RE);
+    let endRel;
+    if (nextMatch && typeof nextMatch.index === 'number') {
+      endRel = start + headingMatch[0].length + nextMatch.index;
+    } else {
+      endRel = existing.length;
+    }
+    const before = existing.slice(0, start);
+    const tail = existing.slice(endRel);
+    next = before + block + (tail.startsWith('\n') || !tail ? tail : '\n' + tail);
+  } else if (existing.length === 0) {
+    next = block;
+  } else {
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    next = existing + sep + block;
+  }
+
+  fs.mkdirSync(featureDir, { recursive: true });
+  try {
+    fs.writeFileSync(tmpPath, next);
+    fs.renameSync(tmpPath, reportPath);
+  } catch (err) {
+    try { if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+
+  return { written: true, path: reportPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.4-beta",
+  "version": "0.1.5-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

@@ -196,6 +196,26 @@ export async function toolGetCurrentSession({ featureCode } = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Roadmap writers — COMP-MCP-ROADMAP-WRITER
+// Pure file-based mutations via lib/feature-writer.js. No HTTP delegation.
+// ---------------------------------------------------------------------------
+
+export async function toolAddRoadmapEntry(args) {
+  const { addRoadmapEntry } = await import('../lib/feature-writer.js');
+  return addRoadmapEntry(getTargetRoot(), args);
+}
+
+export async function toolSetFeatureStatus(args) {
+  const { setFeatureStatus } = await import('../lib/feature-writer.js');
+  return setFeatureStatus(getTargetRoot(), args);
+}
+
+export async function toolRoadmapDiff(args) {
+  const { roadmapDiff } = await import('../lib/feature-writer.js');
+  return roadmapDiff(getTargetRoot(), args);
+}
+
 export async function toolBindSession({ featureCode }) {
   const postData = JSON.stringify({ featureCode });
   return new Promise((resolve, reject) => {

package/server/compose-mcp.js

@@ -43,6 +43,9 @@ import {
   toolIterationStart,
   toolIterationReport,
   toolIterationAbort,
+  toolAddRoadmapEntry,
+  toolSetFeatureStatus,
+  toolRoadmapDiff,
 } from './compose-mcp-tools.js';
 
 // ---------------------------------------------------------------------------
@@ -258,6 +261,57 @@ const TOOLS = [
   },
   // `agent_run` tool removed 2026-04-18 (STRAT-DEDUP-AGENTRUN v1); LLM-facing
   // dispatch goes through `mcp__stratum__stratum_agent_run`.
+
+  // -------------------------------------------------------------------------
+  // Roadmap writers — COMP-MCP-ROADMAP-WRITER
+  // -------------------------------------------------------------------------
+  {
+    name: 'add_roadmap_entry',
+    description: 'Register a new feature in the project. Writes feature.json and regenerates ROADMAP.md (audit-log append is best-effort). Use this instead of editing ROADMAP.md by hand.',
+    inputSchema: {
+      type: 'object',
+      required: ['code', 'description', 'phase'],
+      properties: {
+        code: { type: 'string', description: 'Unique feature code (e.g. "COMP-FOO-1"). Must be uppercase A-Z, digits, dashes; cannot start or end with a dash.' },
+        description: { type: 'string', description: 'One-line description for the ROADMAP cell' },
+        phase: { type: 'string', description: 'Phase heading (e.g. "Phase 6: MCP Writers"). Required.' },
+        complexity: { type: 'string', enum: ['S', 'M', 'L', 'XL'] },
+        status: { type: 'string', enum: ['PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE', 'BLOCKED', 'KILLED', 'PARKED', 'SUPERSEDED'], description: 'Initial status (default PLANNED)' },
+        position: { type: 'number', description: 'Sort order within phase' },
+        parent: { type: 'string', description: 'Parent feature code, for cross-references' },
+        tags: { type: 'array', items: { type: 'string' } },
+        idempotency_key: { type: 'string', description: 'Optional caller-provided key. Same key replays return the cached result without re-mutating.' },
+      },
+    },
+  },
+  {
+    name: 'set_feature_status',
+    description: 'Flip a feature status. Updates feature.json and regenerates ROADMAP.md. Enforces a transition policy (use force: true to bypass). Appends an audit event (best-effort).',
+    inputSchema: {
+      type: 'object',
+      required: ['code', 'status'],
+      properties: {
+        code: { type: 'string' },
+        status: { type: 'string', enum: ['PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE', 'BLOCKED', 'KILLED', 'PARKED', 'SUPERSEDED'] },
+        reason: { type: 'string', description: 'Free-form reason persisted in the audit event' },
+        commit_sha: { type: 'string', description: 'Optional commit binding' },
+        force: { type: 'boolean', description: 'Bypass the transition policy. Recorded in audit.' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'roadmap_diff',
+    description: 'Read the feature-management audit log for a window. Returns events plus derived added[] and status_changed[] arrays.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'string', description: 'Window: shorthand like "24h"/"7d"/"30m", or an ISO date. Default 24h.' },
+        feature_code: { type: 'string' },
+        tool: { type: 'string', description: 'Filter to one tool name, e.g. "set_feature_status"' },
+      },
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -295,6 +349,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'scaffold_feature':         result = toolScaffoldFeature(args); break;
       case 'approve_gate':             result = await toolApproveGate(args); break;
       case 'get_pending_gates':        result = toolGetPendingGates(args); break;
+      case 'add_roadmap_entry':        result = await toolAddRoadmapEntry(args); break;
+      case 'set_feature_status':       result = await toolSetFeatureStatus(args); break;
+      case 'roadmap_diff':             result = await toolRoadmapDiff(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:
         return {