@smartmemory/compose 0.1.4-beta → 0.1.6-beta

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.6-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -8,6 +8,10 @@
   "bin": {
     "compose": "./bin/compose.js"
   },
+  "exports": {
+    "./mcp": "./server/compose-mcp.js",
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "dev": "node server/supervisor.js 2>&1 | tee /tmp/compose-server.log",
     "dev:server": "node server/supervisor.js",

package/server/compose-mcp-tools.js

@@ -196,6 +196,88 @@ 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 toolLinkArtifact(args) {
+  const { linkArtifact } = await import('../lib/feature-writer.js');
+  return linkArtifact(getTargetRoot(), args);
+}
+
+export async function toolLinkFeatures(args) {
+  const { linkFeatures } = await import('../lib/feature-writer.js');
+  return linkFeatures(getTargetRoot(), args);
+}
+
+export async function toolGetFeatureArtifacts(args) {
+  const { getFeatureArtifacts } = await import('../lib/feature-writer.js');
+  return getFeatureArtifacts(getTargetRoot(), args);
+}
+
+export async function toolGetFeatureLinks(args) {
+  const { getFeatureLinks } = await import('../lib/feature-writer.js');
+  return getFeatureLinks(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Changelog writer — COMP-MCP-CHANGELOG-WRITER
+// ---------------------------------------------------------------------------
+
+export async function toolAddChangelogEntry(args) {
+  const { addChangelogEntry } = await import('../lib/changelog-writer.js');
+  return addChangelogEntry(getTargetRoot(), args);
+}
+
+export async function toolGetChangelogEntries(args) {
+  const { getChangelogEntries } = await import('../lib/changelog-writer.js');
+  return getChangelogEntries(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Journal writer — COMP-MCP-JOURNAL-WRITER
+// ---------------------------------------------------------------------------
+
+export async function toolWriteJournalEntry(args) {
+  const { writeJournalEntry } = await import('../lib/journal-writer.js');
+  return writeJournalEntry(getTargetRoot(), args);
+}
+
+export async function toolGetJournalEntries(args) {
+  const { getJournalEntries } = await import('../lib/journal-writer.js');
+  return getJournalEntries(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Completion writer — COMP-MCP-COMPLETION
+// ---------------------------------------------------------------------------
+
+export async function toolRecordCompletion(args) {
+  const { recordCompletion } = await import('../lib/completion-writer.js');
+  return recordCompletion(getTargetRoot(), args);
+}
+
+export async function toolGetCompletions(args) {
+  const { getCompletions } = await import('../lib/completion-writer.js');
+  return getCompletions(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,19 @@ import {
   toolIterationStart,
   toolIterationReport,
   toolIterationAbort,
+  toolAddRoadmapEntry,
+  toolSetFeatureStatus,
+  toolRoadmapDiff,
+  toolLinkArtifact,
+  toolLinkFeatures,
+  toolGetFeatureArtifacts,
+  toolGetFeatureLinks,
+  toolAddChangelogEntry,
+  toolGetChangelogEntries,
+  toolWriteJournalEntry,
+  toolGetJournalEntries,
+  toolRecordCompletion,
+  toolGetCompletions,
 } from './compose-mcp-tools.js';
 
 // ---------------------------------------------------------------------------
@@ -258,6 +271,239 @@ 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"' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Linker — COMP-MCP-ARTIFACT-LINKER
+  // -------------------------------------------------------------------------
+  {
+    name: 'link_artifact',
+    description: 'Register a non-canonical artifact (snapshot, journal entry, finding, etc.) on a feature. Canonical artifacts (design.md, plan.md, …) inside the feature folder are auto-discovered and rejected here. Stores in feature.json artifacts[]; dedups on (type, path); appends an audit event (best-effort).',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code', 'artifact_type', 'path'],
+      properties: {
+        feature_code: { type: 'string' },
+        artifact_type: { type: 'string', description: 'e.g. "journal", "snapshot", "finding", "report-supplement", "link", "external"' },
+        path: { type: 'string', description: 'Repo-relative path. Must exist; cannot contain ".." after normalization.' },
+        status: { type: 'string', enum: ['current', 'superseded', 'historical'] },
+        force: { type: 'boolean', description: 'Overwrite an existing entry with the same (type, path)' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'link_features',
+    description: 'Register a typed cross-feature relationship. Stores on the source feature; query the inverse via get_feature_links(direction:"incoming"). Closed enum on kind; self-links rejected; dedups on (kind, to_code).',
+    inputSchema: {
+      type: 'object',
+      required: ['from_code', 'to_code', 'kind'],
+      properties: {
+        from_code: { type: 'string' },
+        to_code: { type: 'string', description: 'Target feature code. Need not exist yet (you can link to a code you are about to create).' },
+        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related'] },
+        note: { type: 'string' },
+        force: { type: 'boolean' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_feature_artifacts',
+    description: 'Read both canonical (auto-discovered: design.md, plan.md, …) and linked (snapshots, journals, findings) artifacts for a feature in one call. Each linked entry includes a current existence check.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code'],
+      properties: {
+        feature_code: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_feature_links',
+    description: 'Read outgoing and/or incoming feature links. Default returns both directions; filter by kind if needed.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code'],
+      properties: {
+        feature_code: { type: 'string' },
+        direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'] },
+        kind: { type: 'string' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Changelog writer — COMP-MCP-CHANGELOG-WRITER
+  // -------------------------------------------------------------------------
+  {
+    name: 'add_changelog_entry',
+    description: 'Insert (or replace, with force: true) a typed entry in compose/CHANGELOG.md. Idempotent on (date_or_version, code) at storage level; optional caller-supplied idempotency_key for retry safety. Audit-log append is best-effort. Use this instead of editing CHANGELOG.md by hand.',
+    inputSchema: {
+      type: 'object',
+      required: ['date_or_version', 'code', 'summary'],
+      properties: {
+        date_or_version: { type: 'string', description: 'ISO date "YYYY-MM-DD" or semver "vX.Y.Z"' },
+        code: { type: 'string', description: 'Feature code (e.g. "COMP-FOO-1"). Uppercase A-Z, digits, dashes; cannot start or end with a dash.' },
+        summary: { type: 'string', description: 'One-line summary; renders as the "— summary" tail of the entry header.' },
+        body: { type: 'string', description: 'Free paragraphs between header and labeled subsections.' },
+        sections: {
+          type: 'object',
+          description: 'Optional labeled subsections; emitted in fixed order Added → Changed → Fixed → Snapshot.',
+          properties: {
+            added:    { type: 'array', items: { type: 'string' } },
+            changed:  { type: 'array', items: { type: 'string' } },
+            fixed:    { type: 'array', items: { type: 'string' } },
+            snapshot: { type: 'array', items: { type: 'string' } },
+          },
+          additionalProperties: false,
+        },
+        force: { type: 'boolean', description: 'If true and an entry with the same (date_or_version, code) exists, replace it in place.' },
+        idempotency_key: { type: 'string', description: 'Optional caller-supplied key. Same key replays return the cached result without re-mutating.' },
+      },
+    },
+  },
+  {
+    name: 'get_changelog_entries',
+    description: 'Read parsed entries from compose/CHANGELOG.md. Filter by code (exact) or since (shorthand "24h"/"7d"/"30m" or ISO date — date-only; version surfaces always pass through).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'string', description: 'Window: shorthand like "24h"/"7d"/"30m" or ISO date. Date-only filter; version surfaces are always returned.' },
+        code: { type: 'string' },
+        limit: { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Journal writer — COMP-MCP-JOURNAL-WRITER
+  // -------------------------------------------------------------------------
+  {
+    name: 'write_journal_entry',
+    description: 'Write a typed entry to compose/docs/journal/ with auto-numbered global session and inserted index row. Idempotent on (date, slug) at storage level; optional caller idempotency_key for retry safety. Audit-log append is best-effort.',
+    inputSchema: {
+      type: 'object',
+      required: ['date', 'slug', 'sections', 'summary_for_index'],
+      properties: {
+        date: { type: 'string', description: 'ISO date "YYYY-MM-DD".' },
+        slug: { type: 'string', description: 'Kebab-case slug for the filename, e.g. "mcp-journal-writer".' },
+        sections: {
+          type: 'object',
+          required: ['what_happened', 'what_we_built', 'what_we_learned', 'open_threads'],
+          properties: {
+            what_happened:   { type: 'string' },
+            what_we_built:   { type: 'string' },
+            what_we_learned: { type: 'string' },
+            open_threads:    { type: 'string' },
+          },
+          additionalProperties: false,
+        },
+        summary_for_index: { type: 'string', description: 'Single-line summary for the README index row. No newlines, no "|".' },
+        feature_code:      { type: 'string', description: 'Optional feature code stamped in entry frontmatter.' },
+        closing_line:      { type: 'string', description: 'Optional final italicized one-liner.' },
+        force:             { type: 'boolean', description: 'If true and an entry with the same (date, slug) exists, overwrite in place.' },
+        idempotency_key:   { type: 'string', description: 'Optional caller-supplied key. Same key replays return the cached result without re-mutating.' },
+      },
+    },
+  },
+  {
+    name: 'get_journal_entries',
+    description: 'Read parsed entries from compose/docs/journal/. Filter by feature_code (exact), session (exact), or since (shorthand "24h"/"7d"/"30m" or ISO date).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since:        { type: 'string' },
+        feature_code: { type: 'string' },
+        session:      { type: 'number' },
+        limit:        { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
+  // -------------------------------------------------------------------------
+  // Completion writer — COMP-MCP-COMPLETION
+  // -------------------------------------------------------------------------
+  {
+    name: 'record_completion',
+    description: 'Record a completion bound to a commit SHA. Stores in feature.json completions[]; idempotent on (feature_code, commit_sha); when set_status:true (default) also flips status to COMPLETE via set_feature_status. Audit append best-effort. Status-flip failure rethrows as STATUS_FLIP_AFTER_COMPLETION_RECORDED with err.cause; the completion record is still persisted.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code', 'commit_sha', 'tests_pass', 'files_changed'],
+      properties: {
+        feature_code:    { type: 'string' },
+        commit_sha:      { type: 'string', description: 'Full 40-char hex SHA (Decision 9). Short prefixes are rejected on write. Stored verbatim; commit_sha_short is derived for display only.' },
+        tests_pass:      { type: 'boolean' },
+        files_changed:   { type: 'array', items: { type: 'string' } },
+        notes:           { type: 'string' },
+        set_status:      { type: 'boolean', description: 'Default true. When true, flips status to COMPLETE via set_feature_status.' },
+        force:           { type: 'boolean', description: 'If true and a record with the same (feature_code, commit_sha) exists, replace it in place.' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_completions',
+    description: 'Read completion records from feature.json files. Filter by feature_code (exact), commit_sha (short or full prefix), or since (shorthand or ISO date).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        feature_code: { type: 'string' },
+        commit_sha:   { type: 'string' },
+        since:        { type: 'string' },
+        limit:        { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -295,6 +541,19 @@ 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;
+      case 'link_artifact':            result = await toolLinkArtifact(args); break;
+      case 'link_features':            result = await toolLinkFeatures(args); break;
+      case 'get_feature_artifacts':    result = await toolGetFeatureArtifacts(args); break;
+      case 'get_feature_links':        result = await toolGetFeatureLinks(args); break;
+      case 'add_changelog_entry':      result = await toolAddChangelogEntry(args); break;
+      case 'get_changelog_entries':    result = await toolGetChangelogEntries(args); break;
+      case 'write_journal_entry':      result = await toolWriteJournalEntry(args); break;
+      case 'get_journal_entries':      result = await toolGetJournalEntries(args); break;
+      case 'record_completion':        result = await toolRecordCompletion(args); break;
+      case 'get_completions':          result = await toolGetCompletions(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:
         return {
@@ -306,8 +565,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
     };
   } catch (err) {
+    // Surface typed error codes (e.g. INVALID_INPUT, CHANGELOG_FORMAT) when
+    // tools attach them, so MCP callers can branch deterministically. Plain
+    // errors fall back to the original "Error: <message>" shape.
+    // When err.cause is an Error-shaped object, append it so callers can
+    // distinguish partial-write sub-errors (e.g. rollback succeeded vs failed).
+    let text = err && err.code
+      ? `Error [${err.code}]: ${err.message}`
+      : `Error: ${err.message}`;
+    if (err && err.cause && typeof err.cause.message === 'string') {
+      text += err.cause.code
+        ? `\n  Caused by [${err.cause.code}]: ${err.cause.message}`
+        : `\n  Caused by: ${err.cause.message}`;
+    }
     return {
-      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      content: [{ type: 'text', text }],
       isError: true,
     };
   }