@smartmemory/compose 0.1.7-beta → 0.1.8-beta

package/lib/roadmap-preservers.js

@@ -0,0 +1,353 @@
+/**
+ * Preservation helpers for typed-writer regen of ROADMAP.md.
+ *
+ * COMP-MCP-MIGRATION-2-1-1 (Option A — hand-rolled augmentation).
+ *
+ * Three pure functions with no I/O. Each scans an existing ROADMAP.md
+ * source string and returns a Map of curated content for the writer to
+ * splice back during regen, so typed-writer flips don't destroy:
+ *
+ *   - phase-status overrides like `PARKED (Claude Code dependency)`
+ *   - anonymous historical rows with `—` in the Feature column
+ *   - non-feature sections wrapped in `<!-- preserved-section: <id> -->`
+ */
+
+const PHASE_HEADING_RE = /^##\s+(.+?)\s+—\s+(.+?)\s*$/;
+const FENCE_RE = /^```/;
+const TABLE_HEADER_RE = /^\|.*\|$/;
+const TABLE_DIVIDER_RE = /^\|[\s|:-]+\|$/;
+const TABLE_ROW_RE = /^\|.+\|$/;
+const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
+
+const PRESERVED_OPEN_RE = /^<!--\s*preserved-section:\s*([a-z][a-z0-9-]*)\s*-->\s*$/;
+const PRESERVED_CLOSE_RE = /^<!--\s*\/preserved-section\s*-->\s*$/;
+
+/**
+ * Scan ROADMAP.md text and return a Map of phaseId → override text.
+ *
+ * Override is the substring after `— ` in any `## ...` heading line.
+ * Headings without an em-dash override are not included.
+ * Headings inside fenced code blocks are ignored.
+ *
+ * @param {string} text
+ * @returns {Map<string, string>}
+ */
+export function readPhaseOverrides(text) {
+  const out = new Map();
+  let inFence = false;
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = line.match(PHASE_HEADING_RE);
+    if (m) out.set(m[1].trim(), m[2].trim());
+  }
+  return out;
+}
+
+/**
+ * Scan ROADMAP.md text and return a Map of phaseId → AnonRow[].
+ *
+ * AnonRow shape: { rawLine, predecessorCode }
+ * - rawLine: the full table-row line as it appears in source.
+ * - predecessorCode: feature code of the prior typed row in the same phase
+ *   table, or null if this anon row was at the table head (no typed predecessor).
+ *
+ * A row is "anonymous" if its Feature column (detected by header) is `—` or
+ * doesn't match FEATURE_CODE_RE. The current parser regex (looser, requires
+ * trailing -<digits>) is NOT used here; we use the strict regex for accurate
+ * classification (anon means truly no feature code, not the parser's regex bug).
+ * For the 3-col anonymous form (`# | Item | Status`), all rows are anon.
+ *
+ * @param {string} text
+ * @returns {Map<string, Array<{rawLine: string, predecessorCode: string|null}>>}
+ */
+export function readAnonymousRows(text) {
+  const out = new Map();
+  let inFence = false;
+  let currentPhaseId = null;
+  let inTable = false;
+  let codeColIdx = -1; // -1 means anonymous-form (3-col) table
+  let lastTypedCode = null;
+
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    // Phase heading resets table state.
+    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    if (phaseMatch && line.startsWith('## ')) {
+      currentPhaseId = phaseMatch[1].trim();
+      inTable = false;
+      codeColIdx = -1;
+      lastTypedCode = null;
+      continue;
+    }
+
+    if (!currentPhaseId) continue;
+    if (!TABLE_ROW_RE.test(line.trim())) {
+      inTable = false;
+      codeColIdx = -1;
+      lastTypedCode = null;
+      continue;
+    }
+
+    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+
+    // Header row — detect column layout.
+    if (!inTable) {
+      const lower = cells.map(c => c.toLowerCase());
+      const featureIdx = lower.findIndex(c => c === 'feature');
+      if (featureIdx !== -1) {
+        codeColIdx = featureIdx;
+      } else if (lower[0] === 'id') {
+        codeColIdx = 0;
+      } else {
+        codeColIdx = -1; // anonymous form
+      }
+      inTable = true;
+      lastTypedCode = null;
+      continue;
+    }
+
+    // Skip divider rows.
+    if (TABLE_DIVIDER_RE.test(line.trim())) continue;
+
+    // Data row.
+    let isAnon = false;
+    if (codeColIdx === -1) {
+      isAnon = true;
+    } else {
+      const codeCell = cells[codeColIdx] ?? '';
+      if (codeCell === '—' || codeCell === '' || !FEATURE_CODE_RE.test(codeCell)) {
+        isAnon = true;
+      }
+    }
+
+    if (isAnon) {
+      const arr = out.get(currentPhaseId) ?? [];
+      arr.push({ rawLine: line, predecessorCode: lastTypedCode });
+      out.set(currentPhaseId, arr);
+    } else {
+      lastTypedCode = cells[codeColIdx];
+    }
+  }
+  return out;
+}
+
+/**
+ * Scan ROADMAP.md text and return a Map of preserved-section id → rawSource.
+ *
+ * rawSource includes both open and close markers and everything between.
+ * Markers inside fenced code blocks are ignored. Unbalanced markers (open
+ * without matching close) are excluded.
+ *
+ * @param {string} text
+ * @returns {Map<string, string>}
+ */
+export function readPreservedSections(text) {
+  const out = new Map();
+  let inFence = false;
+  let openId = null;
+  let openLineIdx = -1;
+  const lines = text.split('\n');
+
+  // Track byte offsets to slice rawSource.
+  // Compute cumulative offsets per line (start-of-line offsets).
+  const lineOffsets = new Array(lines.length + 1);
+  lineOffsets[0] = 0;
+  for (let i = 0; i < lines.length; i++) {
+    lineOffsets[i + 1] = lineOffsets[i] + lines[i].length + 1; // +1 for newline
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const openMatch = line.match(PRESERVED_OPEN_RE);
+    if (openMatch) {
+      openId = openMatch[1];
+      openLineIdx = i;
+      continue;
+    }
+    if (openId !== null && PRESERVED_CLOSE_RE.test(line)) {
+      const startOffset = lineOffsets[openLineIdx];
+      const endOffset = lineOffsets[i + 1] - 1; // exclude trailing newline of close marker line
+      out.set(openId, text.slice(startOffset, endOffset));
+      openId = null;
+      openLineIdx = -1;
+    }
+  }
+  // Unbalanced open is silently dropped (could log, but tests expect empty/missing).
+  return out;
+}
+
+/**
+ * For each `## ` phase heading in source, capture the entire phase block —
+ * heading line + everything up to (but not including) the next `## ` heading,
+ * `<!-- preserved-section: ... -->` open marker, or EOF. Trailing `---`
+ * separator and surrounding blank lines before the next boundary are excluded.
+ *
+ * Used by the writer as a fallback for phases that have no feature.json
+ * features — emit the raw block verbatim so curated prose, exit text, and
+ * legacy table formatting all survive regen.
+ *
+ * Headings inside fenced code blocks are ignored.
+ *
+ * @param {string} text
+ * @returns {Map<string, string>}
+ */
+export function readPhaseBlocks(text) {
+  const out = new Map();
+  let inFence = false;
+  let inPreserved = false;
+  let currentPhaseId = null;
+  let currentStartLineIdx = -1;
+  const lines = text.split('\n');
+
+  const finalize = (endLineIdx) => {
+    if (currentPhaseId === null || currentStartLineIdx < 0) return;
+    // Walk back over trailing blank lines and a single `---` separator.
+    let endIdx = endLineIdx;
+    while (endIdx > currentStartLineIdx && lines[endIdx - 1].trim() === '') endIdx--;
+    if (endIdx > currentStartLineIdx && lines[endIdx - 1].trim() === '---') endIdx--;
+    while (endIdx > currentStartLineIdx && lines[endIdx - 1].trim() === '') endIdx--;
+    const block = lines.slice(currentStartLineIdx, endIdx).join('\n');
+    out.set(currentPhaseId, block);
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    if (PRESERVED_OPEN_RE.test(line)) {
+      finalize(i);
+      currentPhaseId = null;
+      currentStartLineIdx = -1;
+      inPreserved = true;
+      continue;
+    }
+    if (PRESERVED_CLOSE_RE.test(line)) {
+      inPreserved = false;
+      continue;
+    }
+    if (inPreserved) continue;
+
+    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    if (phaseMatch && line.startsWith('## ')) {
+      finalize(i);
+      currentPhaseId = phaseMatch[1].trim();
+      currentStartLineIdx = i;
+    }
+  }
+  finalize(lines.length);
+
+  return out;
+}
+
+/**
+ * Return the array of phaseIds in their order of appearance in source.
+ *
+ * Used by the writer to preserve original phase order when emitting phases
+ * that exist only in the source (no feature.json features). Headings inside
+ * fenced code blocks or inside open preserved-section markers are ignored.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function readPhaseOrder(text) {
+  const out = [];
+  let inFence = false;
+  let inPreserved = false;
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    if (PRESERVED_OPEN_RE.test(line)) {
+      inPreserved = true;
+      continue;
+    }
+    if (PRESERVED_CLOSE_RE.test(line)) {
+      inPreserved = false;
+      continue;
+    }
+    if (inPreserved) continue;
+
+    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    if (phaseMatch && line.startsWith('## ')) {
+      out.push(phaseMatch[1].trim());
+    }
+  }
+  return out;
+}
+
+/**
+ * For each preserved section, find the phaseId of the most recent `## ` heading
+ * before its open marker. Returns Map<id, phaseId|null>.
+ *
+ * Used by the writer to splice preserved sections back into the regenerated
+ * output at the correct sequential position relative to phases.
+ *
+ * - `null` anchor means the preserved section appeared at the top of the
+ *   file before any phase heading (e.g. Roadmap Conventions).
+ * - Markers inside fenced code blocks are ignored (false-positive guard).
+ * - Open markers without a matching close are excluded.
+ *
+ * @param {string} text
+ * @returns {Map<string, string|null>}
+ */
+export function readPreservedSectionAnchors(text) {
+  const out = new Map();
+  let inFence = false;
+  let currentPhaseId = null;
+  let openId = null;
+  let openAnchor = null;
+
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    // Phase headings inside an open preserved-section do NOT advance the anchor.
+    if (openId === null) {
+      const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+      if (phaseMatch && line.startsWith('## ') && !PRESERVED_OPEN_RE.test(line) && !PRESERVED_CLOSE_RE.test(line)) {
+        currentPhaseId = phaseMatch[1].trim();
+        continue;
+      }
+    }
+
+    const openMatch = line.match(PRESERVED_OPEN_RE);
+    if (openMatch) {
+      openId = openMatch[1];
+      openAnchor = currentPhaseId;
+      continue;
+    }
+    if (openId !== null && PRESERVED_CLOSE_RE.test(line)) {
+      out.set(openId, openAnchor);
+      openId = null;
+      openAnchor = null;
+    }
+  }
+  return out;
+}

package/lib/step-prompt.js

@@ -93,6 +93,21 @@ export function buildStepPrompt(stepDispatch, context) {
     }
   }
 
+  // COMP-MCP-MIGRATION: typed-tool enforcement (prompt-only in v1).
+  // When `enforcement.mcpForFeatureMgmt` is true in .compose/compose.json,
+  // inject a hard instruction telling the agent to use typed MCP tools
+  // instead of free-text Edit/Write for ROADMAP/CHANGELOG/feature.json.
+  if (context.enforceMcpForFeatureMgmt) {
+    sections.push(
+      '## Enforcement\n' +
+      'Do NOT use Edit, Write, or any shell write that targets `ROADMAP.md`, ' +
+      '`CHANGELOG.md`, or any `feature.json` under `docs/features/`. Use the ' +
+      'typed MCP tools instead: `add_roadmap_entry`, `set_feature_status`, ' +
+      '`add_changelog_entry`, `record_completion`, `propose_followup`, ' +
+      '`link_features`, `link_artifact`, `write_journal_entry`.'
+    );
+  }
+
   const ctxLines = [
     `Working directory: ${context.cwd}`,
     `Feature: ${context.featureCode}`,

package/lib/triage.js

@@ -185,7 +185,8 @@ function deriveProfile(signals) {
  */
 export async function runTriage(featureCode, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const featureDir = join(cwd, 'docs', 'features', featureCode);
+  const featuresDir = opts.featuresDir ?? 'docs/features';
+  const featureDir = join(cwd, featuresDir, featureCode);
 
   // Collect content from key files
   const candidateFiles = ['plan.md', 'blueprint.md', 'design.md', 'prd.md', 'architecture.md'];

package/lib/version-check.js

@@ -0,0 +1,110 @@
+/**
+ * Version drift detection — fetch latest @smartmemory/compose from npm
+ * and compare to the locally-installed version.
+ *
+ * Cached 24h at ~/.compose/version-cache.json. Never throws; returns null
+ * on any failure (network, parse, etc.) so it never breaks `compose doctor`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { homedir } from 'os'
+
+const PACKAGE_NAME = '@smartmemory/compose'
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000  // 24h
+const FETCH_TIMEOUT_MS = 3000
+
+function cachePath() {
+  return join(homedir(), '.compose', 'version-cache.json')
+}
+
+function readCache() {
+  try {
+    const raw = readFileSync(cachePath(), 'utf-8')
+    const parsed = JSON.parse(raw)
+    if (typeof parsed?.fetchedAt !== 'number' || typeof parsed?.latest !== 'string') return null
+    if (Date.now() - parsed.fetchedAt > CACHE_TTL_MS) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function writeCache(latest) {
+  try {
+    const path = cachePath()
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify({ fetchedAt: Date.now(), latest }, null, 2))
+  } catch {
+    // best-effort cache; ignore failures
+  }
+}
+
+async function fetchLatest() {
+  if (typeof fetch !== 'function') return null
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
+    const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } })
+    if (!res.ok) return null
+    const data = await res.json()
+    return typeof data?.version === 'string' ? data.version : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Compare semver-ish strings. Returns:
+ *   -1 if a < b, 0 if equal, 1 if a > b, null if either unparseable.
+ * Treats prerelease tags conservatively: "0.1.7-beta" < "0.1.7".
+ */
+export function compareVersions(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return null
+  const parse = (s) => {
+    const [core, pre] = s.split('-')
+    const parts = core.split('.').map(n => Number.parseInt(n, 10))
+    if (parts.length !== 3 || parts.some(n => Number.isNaN(n))) return null
+    return { parts, pre: pre ?? null }
+  }
+  const pa = parse(a)
+  const pb = parse(b)
+  if (!pa || !pb) return null
+  for (let i = 0; i < 3; i++) {
+    if (pa.parts[i] < pb.parts[i]) return -1
+    if (pa.parts[i] > pb.parts[i]) return 1
+  }
+  // cores equal — prerelease < release
+  if (pa.pre && !pb.pre) return -1
+  if (!pa.pre && pb.pre) return 1
+  if (pa.pre === pb.pre) return 0
+  return pa.pre < pb.pre ? -1 : 1
+}
+
+/**
+ * Returns { current, latest, behind, source } or null on failure.
+ *   behind: true if current < latest, false otherwise.
+ *   source: 'cache' | 'network'
+ */
+export async function checkLatestVersion(currentVersion, { force = false } = {}) {
+  if (!currentVersion) return null
+
+  if (!force) {
+    const cached = readCache()
+    if (cached) {
+      const cmp = compareVersions(currentVersion, cached.latest)
+      if (cmp === null) return null
+      return { current: currentVersion, latest: cached.latest, behind: cmp < 0, source: 'cache' }
+    }
+  }
+
+  const latest = await fetchLatest()
+  if (!latest) return null
+  writeCache(latest)
+  const cmp = compareVersions(currentVersion, latest)
+  if (cmp === null) return null
+  return { current: currentVersion, latest, behind: cmp < 0, source: 'network' }
+}

package/package.json

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

@@ -236,6 +236,15 @@ export async function toolGetFeatureLinks(args) {
   return getFeatureLinks(getTargetRoot(), args);
 }
 
+// ---------------------------------------------------------------------------
+// Follow-up filing — COMP-MCP-FOLLOWUP
+// ---------------------------------------------------------------------------
+
+export async function toolProposeFollowup(args) {
+  const { proposeFollowup } = await import('../lib/followup-writer.js');
+  return proposeFollowup(getTargetRoot(), args);
+}
+
 // ---------------------------------------------------------------------------
 // Changelog writer — COMP-MCP-CHANGELOG-WRITER
 // ---------------------------------------------------------------------------
@@ -397,8 +406,13 @@ export async function toolKillFeature({ id, reason }) {
   return _postLifecycle(id, 'kill', { reason });
 }
 
-export async function toolCompleteFeature({ id }) {
-  return _postLifecycle(id, 'complete', {});
+export async function toolCompleteFeature({ id, commit_sha, tests_pass, files_changed, notes }) {
+  const body = {};
+  if (commit_sha !== undefined) body.commit_sha = commit_sha;
+  if (tests_pass !== undefined) body.tests_pass = tests_pass;
+  if (files_changed !== undefined) body.files_changed = files_changed;
+  if (notes !== undefined) body.notes = notes;
+  return _postLifecycle(id, 'complete', body);
 }
 
 export async function toolIterationStart({ id, loopType, maxIterations }) {

package/server/compose-mcp.js

@@ -50,6 +50,7 @@ import {
   toolLinkFeatures,
   toolGetFeatureArtifacts,
   toolGetFeatureLinks,
+  toolProposeFollowup,
   toolAddChangelogEntry,
   toolGetChangelogEntries,
   toolWriteJournalEntry,
@@ -175,11 +176,15 @@ const TOOLS = [
   },
   {
     name: 'complete_feature',
-    description: 'Mark a feature as complete. Only callable from the ship phase.',
+    description: 'Mark a feature as complete. Only callable from the ship phase. When commit_sha is provided, the lifecycle endpoint also writes a commit-bound completion record via record_completion (which atomically flips feature.status to COMPLETE and regenerates ROADMAP.md). Without commit_sha, the lifecycle transitions but no completion record is written; a `cockpit_completion_skipped` decision event explains the skip.',
     inputSchema: {
       type: 'object',
       properties: {
         id: { type: 'string', description: 'Item ID' },
+        commit_sha: { type: 'string', description: 'Full 40-char commit SHA. Required to write a completion record.' },
+        tests_pass: { type: 'boolean', description: 'Defaults to true when commit_sha is provided.' },
+        files_changed: { type: 'array', items: { type: 'string' }, description: 'Repo-relative paths committed in the SHA.' },
+        notes: { type: 'string', description: 'One-line note for the completion record.' },
       },
       required: ['id'],
     },
@@ -348,6 +353,23 @@ const TOOLS = [
       },
     },
   },
+  {
+    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.',
+    inputSchema: {
+      type: 'object',
+      required: ['parent_code', 'description', 'rationale'],
+      properties: {
+        parent_code: { type: 'string', description: 'Parent feature code (e.g. "COMP-MCP-MIGRATION"). Must exist; must not be KILLED/SUPERSEDED.' },
+        description: { type: 'string', description: 'One-line description for the ROADMAP cell.' },
+        rationale: { type: 'string', description: 'Why this follow-up exists. Persisted as a "## Why" block in the new design.md and in the audit event.' },
+        complexity: { type: 'string', enum: ['S', 'M', 'L', 'XL'] },
+        phase: { type: 'string', description: 'Phase heading. Defaults to the parent\'s phase if omitted.' },
+        status: { type: 'string', enum: ['PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE', 'BLOCKED', 'KILLED', 'PARKED', 'SUPERSEDED'] },
+        idempotency_key: { type: 'string', description: 'Optional retry-safety key. Without it, repeated calls allocate new codes.' },
+      },
+    },
+  },
 
   // -------------------------------------------------------------------------
   // Linker — COMP-MCP-ARTIFACT-LINKER
@@ -582,6 +604,7 @@ 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 'propose_followup':         result = await toolProposeFollowup(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:
         return {

package/server/vision-routes.js

@@ -338,7 +338,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/complete', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/complete', async (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
@@ -360,7 +360,56 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (complete)
       emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
-      res.json({ completedAt: now });
+
+      // COMP-MCP-MIGRATION: reconcile cockpit complete with record_completion
+      // (commit-bound completion writer). Best-effort: failures emit a decision
+      // event but never roll back the lifecycle transition.
+      const featureCode = item.lifecycle.featureCode;
+      const completionResult = { partial: false };
+      if (featureCode) {
+        const { commit_sha, tests_pass, files_changed, notes } = req.body || {};
+        if (commit_sha) {
+          try {
+            const { recordCompletion } = await import('../lib/completion-writer.js');
+            await recordCompletion(projectRoot, {
+              feature_code: featureCode,
+              commit_sha,
+              tests_pass: tests_pass ?? true,
+              files_changed: files_changed ?? [],
+              notes: notes ?? `cockpit lifecycle: ${featureCode} complete`,
+            });
+          } catch (err) {
+            completionResult.partial = true;
+            const eventType = err.code === 'STATUS_FLIP_AFTER_COMPLETION_RECORDED'
+              ? 'cockpit_completion_partial_status_flip'
+              : 'cockpit_completion_failed';
+            completionResult.completion_failed = err.code || 'UNKNOWN';
+            completionResult.message = err.message;
+            try {
+              emitDecisionEvent(broadcastMessage, {
+                type: eventType,
+                featureCode,
+                timestamp: now,
+                error: { code: err.code, message: err.message },
+              });
+            } catch { /* decision event emit best-effort */ }
+            // eslint-disable-next-line no-console
+            console.warn(`[lifecycle/complete] record_completion ${eventType} for ${featureCode}: ${err.message}`);
+          }
+        } else {
+          // No SHA — emit a skip event so validate_feature can flag drift later
+          try {
+            emitDecisionEvent(broadcastMessage, {
+              type: 'cockpit_completion_skipped',
+              featureCode,
+              timestamp: now,
+              reason: 'no_commit_sha',
+            });
+          } catch { /* decision event emit best-effort */ }
+        }
+      }
+
+      res.json({ completedAt: now, ...completionResult });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
       res.status(status).json({ error: err.message });

package/templates/ROADMAP.md

@@ -5,6 +5,7 @@
 
 ---
 
+<!-- preserved-section: roadmap-conventions -->
 ## Roadmap Conventions
 
 - **Status:** `PLANNED` | `IN_PROGRESS` | `PARTIAL` | `COMPLETE` | `SUPERSEDED` | `PARKED`
@@ -12,6 +13,8 @@
 - Items are numbered sequentially across all phases — never reuse a number.
 - Cross-reference stable IDs (e.g. `FEAT-1`, `Phase 2`) not section headings.
 
+<!-- /preserved-section -->
+
 ---
 
 ## Phase 1: Foundation — PLANNED
@@ -37,6 +40,7 @@ Bootstrap: establish the core structure and first working milestone.
 
 ---
 
+<!-- preserved-section: dogfooding-milestones -->
 ## Dogfooding Milestones
 
 | Milestone | Description | Status |
@@ -44,3 +48,5 @@ Bootstrap: establish the core structure and first working milestone.
 | D0: Bootstrap | Manual, out-of-band. | PLANNED |
 | D1: [First self-use milestone] | [Description] | PLANNED |
 | D2: [Second self-use milestone] | [Description] | PLANNED |
+
+<!-- /preserved-section -->