@smartmemory/compose 0.1.44-beta → 0.2.1-beta

package/lib/roadmap-roundtrip.js

@@ -0,0 +1,137 @@
+/**
+ * roadmap-roundtrip.js — prove ROADMAP.md is a deterministic fixed point of
+ * feature.json. Pure: no filesystem, no event/stderr side effects.
+ *
+ * COMP-ROADMAP-RT.
+ */
+
+import { generateRoadmapFromBase } from './roadmap-gen.js';
+import { parseRoadmap } from './roadmap-parser.js';
+import { isFeatureCode } from './feature-code.js';
+
+export const MAX_REGEN_PASSES = 3;
+
+/**
+ * Human-readable labels for the lossless (LOSSLESS_*) diff kinds. Shared by the
+ * CLI (`roadmap check`) and the project validator (ROADMAP_LOSSY findings) so the
+ * two surfaces can't drift in their wording.
+ */
+export const LOSSY_LABELS = {
+  LOSSLESS_MISSING: 'roadmap missing a row for feature.json entry',
+  LOSSLESS_EXTRA: 'roadmap row not backed by feature.json',
+  LOSSLESS_CHANGED: 'roadmap row disagrees with feature.json',
+};
+
+/** Human-readable one-line description of a lossless diff. */
+export function describeLossyDiff(d) {
+  const label = LOSSY_LABELS[d.kind] ?? d.kind;
+  const code = d.code ? ` ${d.code}` : '';
+  const detail = d.detail ? `: ${d.detail}` : '';
+  return `${label}${code}${detail}`;
+}
+
+/**
+ * @typedef {{ kind: string, phaseId?: string, code?: string, detail?: string }} Diff
+ * @typedef {{ fixedPoint: boolean, lossless: boolean, canonical: string, passes: number, diffs: Diff[] }} RoundtripResult
+ */
+
+/**
+ * @param {string} baseText  Existing ROADMAP.md content ('' for a fresh file)
+ * @param {Array}  features  feature.json feature objects
+ * @param {object} [opts]    { now, maxPasses, projectName, projectDescription, externalPrefixes }
+ * @param {string[]} [opts.externalPrefixes]  Code prefixes (e.g. ['STRAT-']) for
+ *   features owned by OTHER projects, present in this roadmap only as
+ *   cross-project references. A parsed code matching any prefix is NOT flagged
+ *   LOSSLESS_EXTRA. Defaults to [].
+ * @returns {RoundtripResult}
+ */
+export function checkRoundtrip(baseText, features, opts = {}) {
+  const maxPasses = opts.maxPasses ?? MAX_REGEN_PASSES;
+  const externalPrefixes = opts.externalPrefixes ?? [];
+  const isExternal = (code) => externalPrefixes.some(p => code.startsWith(p));
+  // Pure: never pass cwd (so no drift I/O); suppressDrift belt-and-suspenders.
+  const genOpts = { ...opts, cwd: undefined, suppressDrift: true };
+  const diffs = [];
+
+  // --- Fixed point: iterate gen until output stabilizes. ---
+  // Each pass regenerates from the previous output; convergence = next === canonical.
+  // On non-convergence within maxPasses, emit exactly one FIXED_POINT_DIVERGENCE
+  // diff comparing the last two distinct passes. canonical is always the last pass.
+  let canonical = generateRoadmapFromBase(baseText, features, genOpts);
+  let passes = 1;
+  let fixedPoint = false;
+  while (passes < maxPasses) {
+    const next = generateRoadmapFromBase(canonical, features, genOpts);
+    passes++;
+    if (next === canonical) { fixedPoint = true; break; }
+    const prev = canonical;
+    canonical = next;
+    if (passes === maxPasses) {
+      diffs.push({ kind: 'FIXED_POINT_DIVERGENCE', detail: firstDiffLine(prev, canonical) });
+    }
+  }
+
+  // --- Losslessness: parse canonical, aggregate by code, exclude anon. ---
+  const parsed = parseRoadmap(canonical);
+  const byCode = new Map();
+  for (const e of parsed) {
+    if (e.code.startsWith('_anon_') || !isFeatureCode(e.code)) continue;
+    const arr = byCode.get(e.code) ?? [];
+    arr.push(e);
+    byCode.set(e.code, arr);
+  }
+
+  const featureCodes = new Set();
+  for (const f of features) {
+    featureCodes.add(f.code);
+    const group = byCode.get(f.code);
+    if (!group || group.length === 0) {
+      diffs.push({ kind: 'LOSSLESS_MISSING', code: f.code, phaseId: f.phase });
+      continue;
+    }
+    const hasItems = Array.isArray(f.items) && f.items.length > 0;
+    if (hasItems) {
+      const want = f.items.map(i => up(i.status ?? f.status)).sort();
+      const got = group.map(e => up(e.status)).sort();
+      if (want.length !== got.length || want.some((s, i) => s !== got[i])) {
+        diffs.push({ kind: 'LOSSLESS_CHANGED', code: f.code, phaseId: f.phase,
+          detail: `items: want [${want}] got [${got}]` });
+      }
+    } else {
+      const e = group[0];
+      if (up(e.status) !== up(f.status)) {
+        diffs.push({ kind: 'LOSSLESS_CHANGED', code: f.code, phaseId: f.phase,
+          detail: `status: want ${up(f.status)} got ${up(e.status)}` });
+      }
+      // feature.json stores a FLAT phase, but the parser yields a full
+      // milestone path ("Phase > Milestone") for ### sub-headings. Compare on
+      // the top-level phase only; surface the full parsed phaseId in detail so
+      // genuine drift stays legible.
+      const topPhase = e.phaseId ? e.phaseId.split(' > ')[0].trim() : e.phaseId;
+      if (f.phase && topPhase && topPhase !== f.phase) {
+        diffs.push({ kind: 'LOSSLESS_CHANGED', code: f.code, phaseId: f.phase,
+          detail: `phase: want ${f.phase} got ${e.phaseId}` });
+      }
+    }
+  }
+  for (const code of byCode.keys()) {
+    if (!featureCodes.has(code) && !isExternal(code)) diffs.push({ kind: 'LOSSLESS_EXTRA', code });
+  }
+
+  const lossless = !diffs.some(d => d.kind.startsWith('LOSSLESS_'));
+  return { fixedPoint, lossless, canonical, passes, diffs };
+}
+
+function up(s) { return String(s ?? '').toUpperCase().trim(); }
+
+/** First differing line between two texts, for FIXED_POINT_DIVERGENCE.detail. */
+function firstDiffLine(a, b) {
+  const al = a.split('\n'), bl = b.split('\n');
+  const n = Math.max(al.length, bl.length);
+  for (let i = 0; i < n; i++) {
+    // The ?? '' padding means any length difference surfaces as a line mismatch,
+    // so the loop always returns when a !== b (the only caller's precondition).
+    if (al[i] !== bl[i]) return `line ${i + 1}: "${al[i] ?? ''}" → "${bl[i] ?? ''}"`;
+  }
+  return '';
+}

package/lib/vision-writer.js

@@ -16,6 +16,24 @@ import { probeServer } from './server-probe.js';
 
 const EMPTY_STATE = () => ({ items: [], connections: [], gates: [] });
 
+/**
+ * Locate the vision item a featureCode refers to, tolerant of UI-created items
+ * that have no lifecycle yet (#31). Priority order: lifecycle.featureCode (the
+ * canonical binding), then the raw item id, then a top-level item.featureCode.
+ * A lifecycle match anywhere in the list beats an id/featureCode match, so the
+ * three passes are evaluated in order rather than first-item-wins.
+ *
+ * @param {Array<object>} items
+ * @param {string} featureCode
+ * @returns {object|null}
+ */
+function matchFeatureItem(items, featureCode) {
+  return items.find(item => item.lifecycle?.featureCode === featureCode)
+    || items.find(item => item.id === featureCode)
+    || items.find(item => item.featureCode === featureCode)
+    || null;
+}
+
 /** Canonical outcome normalization — maps legacy past-tense to imperative */
 function normalizeOutcome(outcome) {
   const map = { approved: 'approve', killed: 'kill', revised: 'revise' };
@@ -150,14 +168,15 @@ export class VisionWriter {
 
   async _restFindFeatureItem(featureCode) {
     const state = await this._fetch('/api/vision/items');
-    const items = state.items || [];
-    return items.find(item => item.lifecycle?.featureCode === featureCode) || null;
+    return matchFeatureItem(state.items || [], featureCode);
   }
 
-  async _restEnsureFeatureItem(featureCode, title) {
+  async _restEnsureFeatureItem(featureCode, title, mode = 'feature') {
     const existing = await this._restFindFeatureItem(featureCode);
     if (existing) {
-      // Partial repair: item exists but no lifecycle — start lifecycle
+      // Partial repair: item exists (e.g. UI-created, matched by id or
+      // featureCode) but no lifecycle — start lifecycle so the next CLI run
+      // finds it by lifecycle.featureCode (#31).
       if (!existing.lifecycle?.featureCode) {
         await this._fetch(`/api/vision/items/${existing.id}/lifecycle/start`, {
           method: 'POST',
@@ -169,7 +188,7 @@ export class VisionWriter {
     const item = await this._fetch('/api/vision/items', {
       method: 'POST',
       body: JSON.stringify({
-        type: 'feature',
+        type: mode === 'bug' ? 'bug' : 'feature',
         title: title || featureCode,
         description: '',
         status: 'planned',
@@ -238,20 +257,29 @@ export class VisionWriter {
 
   _directFindFeatureItem(featureCode) {
     const state = this._load();
-    return state.items.find(item => item.lifecycle?.featureCode === featureCode) || null;
+    return matchFeatureItem(state.items, featureCode);
   }
 
-  _directEnsureFeatureItem(featureCode, title) {
-    const existing = this._directFindFeatureItem(featureCode);
-    if (existing) return existing.id;
-
+  _directEnsureFeatureItem(featureCode, title, mode = 'feature') {
     const state = this._load();
+    const existing = matchFeatureItem(state.items, featureCode);
+    if (existing) {
+      // Partial repair: a UI-created item matched by id/featureCode but has no
+      // lifecycle yet — seed lifecycle.featureCode so the next CLI run binds by
+      // the canonical key (#31).
+      if (!existing.lifecycle?.featureCode) {
+        existing.lifecycle = { ...(existing.lifecycle || {}), featureCode, currentPhase: existing.lifecycle?.currentPhase || 'explore_design' };
+        this._atomicWrite(state);
+      }
+      return existing.id;
+    }
+
     // Derive group from featureCode (same logic as vision-store.js deriveGroup)
     const groupMatch = (title || featureCode).match(/^([A-Z]+-[A-Z]+|[A-Z]+)(?=-\d)/);
     const group = groupMatch ? groupMatch[1] : featureCode;
     const item = {
       id: crypto.randomUUID(),
-      type: 'feature',
+      type: mode === 'bug' ? 'bug' : 'feature',
       title: title || featureCode,
       description: '',
       status: 'planned',
@@ -348,11 +376,11 @@ export class VisionWriter {
     return this._directFindFeatureItem(featureCode);
   }
 
-  async ensureFeatureItem(featureCode, title) {
+  async ensureFeatureItem(featureCode, title, mode = 'feature') {
     if (await this._serverAvailable()) {
-      return this._restEnsureFeatureItem(featureCode, title);
+      return this._restEnsureFeatureItem(featureCode, title, mode);
     }
-    return this._directEnsureFeatureItem(featureCode, title);
+    return this._directEnsureFeatureItem(featureCode, title, mode);
   }
 
   async updateItemStatus(itemId, status) {

package/lib/xref-sync.js

@@ -0,0 +1,160 @@
+/**
+ * xref-sync.js — COMP-ROADMAP-XREF-SYNC v1 (PULL reconciliation).
+ *
+ * Turns the read-only XREF_DRIFT warning (COMP-MCP-XREF-VALIDATE #16) into an
+ * applied fix: for every feature.json external link that carries an `expect=`,
+ * resolve the live target and rewrite `expect` to match reality. This is a
+ * PULL — it reconciles the LOCAL citation to the EXTERNAL truth and NEVER writes
+ * to an external system (closing a GitHub issue etc. is a separate, deliberate
+ * capability — see docs/features/COMP-ROADMAP-XREF-SYNC/design.md).
+ *
+ * Operates on the structured `links[].kind === 'external'` carrier (the
+ * post-migration source of truth), so it never rewrites markdown or perturbs the
+ * ROADMAP roundtrip fixed point. Resolution is injectable for testability.
+ */
+
+import { readdirSync, existsSync, readFileSync, realpathSync } from 'fs';
+import { join, resolve as resolvePath, dirname } from 'path';
+import { writeFeature } from './feature-json.js';
+import { loadFeaturesDir } from './project-paths.js';
+
+const RESOLVABLE = new Set(['github', 'local']);
+
+/**
+ * Pure reconciliation: should `ref.expect` be rewritten to `liveState`?
+ *
+ * @param {{expect: string|null}} ref
+ * @param {string|null} liveState  resolved live state, or null if unresolved
+ * @returns {{changed: boolean, from?: string, to?: string}}
+ */
+export function reconcileExpect(ref, liveState) {
+  if (!ref.expect) return { changed: false };        // nothing to pull
+  if (liveState == null) return { changed: false };  // unresolved → leave as-is
+  if (ref.expect === liveState) return { changed: false };
+  return { changed: true, from: ref.expect, to: liveState };
+}
+
+/**
+ * Resolve a single external link to its live state using the same primitives as
+ * the validator. Returns { state } on success, { skipped, reason } on a degrade
+ * (offline / no-token / rate-limit / missing target), mirroring the read-only
+ * checker's per-ref degrade semantics — never guesses a state.
+ *
+ * @param {object} link   feature.json external link
+ * @param {string} cwd
+ * @param {string} featuresDir
+ */
+async function defaultResolve(link, cwd, featuresDir) {
+  if (link.provider === 'github') {
+    if (!link.repo || link.issue == null) return { skipped: true, reason: 'incomplete github ref' };
+    let GitHubApi;
+    try { ({ GitHubApi } = await import('./tracker/github-api.js')); }
+    catch (e) { return { skipped: true, reason: `github client unavailable: ${e.message}` }; }
+    let gh;
+    try {
+      // auth.token from env if present, else the client falls back to `gh auth token`.
+      gh = new GitHubApi({ repo: link.repo, auth: { token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN } });
+    } catch (e) {
+      return { skipped: true, reason: (e && e.message) || 'no GitHub auth' };
+    }
+    try {
+      const r = await gh.getIssueResult(link.issue);
+      if (r.status === 404) return { skipped: true, reason: `target ${link.repo}#${link.issue} missing (404)` };
+      if (r.status < 200 || r.status >= 300) return { skipped: true, reason: `HTTP ${r.status}` };
+      const state = r.body && r.body.state;
+      if (state !== 'open' && state !== 'closed') return { skipped: true, reason: 'no parseable issue state' };
+      return { state };
+    } catch (e) {
+      return { skipped: true, reason: e && e.rateLimit ? 'rate limit' : (e && e.message) || 'resolution error' };
+    }
+  }
+  if (link.provider === 'local') {
+    // The target feature lives in a sibling repo; its status is the live state.
+    if (!link.repo || !link.to_code) return { skipped: true, reason: 'incomplete local ref' };
+    // Containment guard (parity with feature-validator resolveLocalRef): the
+    // repo token must resolve to a DIRECT sibling of cwd — lexical check first,
+    // then realpath to defeat a valid-named sibling symlinked outside the parent.
+    const parentDir = resolvePath(cwd, '..');
+    const citedRoot = resolvePath(parentDir, String(link.repo));
+    if (/[\\/]/.test(link.repo) || link.repo === '.' || link.repo === '..'
+        || dirname(citedRoot) !== parentDir) {
+      return { skipped: true, reason: `local repo token "${link.repo}" is not a valid sibling` };
+    }
+    try {
+      if (dirname(realpathSync(citedRoot)) !== realpathSync(parentDir)) {
+        return { skipped: true, reason: `local repo "${link.repo}" escapes the workspace parent` };
+      }
+    } catch { return { skipped: true, reason: `local target ${link.repo} not found` }; }
+    // Resolve the SIBLING's own features dir (it may have its own paths.features).
+    try {
+      const fjPath = join(citedRoot, loadFeaturesDir(citedRoot), link.to_code, 'feature.json');
+      if (!existsSync(fjPath)) return { skipped: true, reason: `local target ${link.repo}/${link.to_code} not found` };
+      return { state: JSON.parse(readFileSync(fjPath, 'utf8')).status || null };
+    } catch (e) { return { skipped: true, reason: `unreadable local target: ${e.message}` }; }
+  }
+  return { skipped: true, reason: `unresolvable provider: ${link.provider}` };
+}
+
+/**
+ * Pull-reconcile every feature.json external link's `expect` to live target state.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {boolean} [opts.dryRun]      report changes without writing
+ * @param {string}  [opts.featuresDir]
+ * @param {(link: object, cwd: string, featuresDir: string) => Promise<{state?: string|null, skipped?: boolean, reason?: string}>} [opts.resolve]
+ *   injectable resolver (defaults to github-api + local feature.json)
+ * @returns {Promise<{synced: Array, skipped: Array, unchanged: number, scanned: number}>}
+ */
+export async function syncExternalRefs(cwd, opts = {}) {
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const resolve = opts.resolve ?? defaultResolve;
+  const dir = join(cwd, featuresDir);
+
+  const synced = [];
+  const skipped = [];
+  let unchanged = 0;
+  let scanned = 0;
+
+  if (!existsSync(dir)) return { synced, skipped, unchanged, scanned };
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const fjPath = join(dir, entry.name, 'feature.json');
+    if (!existsSync(fjPath)) continue;
+    let fj;
+    try { fj = JSON.parse(readFileSync(fjPath, 'utf8')); } catch { continue; }
+    if (!Array.isArray(fj.links)) continue;
+
+    let mutated = false;
+    for (const link of fj.links) {
+      if (!link || link.kind !== 'external') continue;
+      // Only resolvable providers that carry an explicit expectation can drift.
+      if (!RESOLVABLE.has(link.provider) || !link.expect) continue;
+      scanned++;
+
+      const r = await resolve(link, cwd, featuresDir);
+      if (r.skipped) {
+        skipped.push({ code: fj.code, provider: link.provider, target: targetLabel(link), reason: r.reason });
+        continue;
+      }
+      const verdict = reconcileExpect(link, r.state ?? null);
+      if (!verdict.changed) { unchanged++; continue; }
+
+      synced.push({ code: fj.code, provider: link.provider, target: targetLabel(link), from: verdict.from, to: verdict.to });
+      if (!dryRun(opts)) { link.expect = verdict.to; mutated = true; }
+    }
+
+    if (mutated && !dryRun(opts)) writeFeature(cwd, fj, featuresDir);
+  }
+
+  return { synced, skipped, unchanged, scanned };
+}
+
+function dryRun(opts) { return opts.dryRun === true; }
+
+function targetLabel(link) {
+  if (link.provider === 'github') return `${link.repo}#${link.issue}`;
+  if (link.provider === 'local') return `${link.repo}/${link.to_code}`;
+  return link.url || '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.44-beta",
+  "version": "0.2.1-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.js

@@ -316,6 +316,7 @@ const TOOLS = [
         position: { type: 'number', description: 'Sort order within phase' },
         parent: { type: 'string', description: 'Parent feature code, for cross-references' },
         tags: { type: 'array', items: { type: 'string' } },
+        force: { type: 'boolean', description: 'Bypass the pre-commit roundtrip guard (commit even if ROADMAP.md would not be a generation fixed point).' },
         idempotency_key: { type: 'string', description: 'Optional caller-provided key. Same key replays return the cached result without re-mutating.' },
       },
     },
@@ -331,7 +332,7 @@ const TOOLS = [
         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.' },
+        force: { type: 'boolean', description: 'Bypass the transition policy AND the roundtrip fixed-point guard (commits even if ROADMAP.md would not be a generation fixed point). Recorded in audit.' },
         idempotency_key: { type: 'string' },
       },
     },

package/server/vision-store.js

@@ -7,7 +7,7 @@ import { v4 as uuidv4 } from 'uuid';
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const VALID_TYPES = ['feature', 'track', 'idea', 'decision', 'question', 'thread', 'artifact', 'task', 'spec', 'evaluation'];
+export const VALID_TYPES = ['feature', 'bug', 'track', 'idea', 'decision', 'question', 'thread', 'artifact', 'task', 'spec', 'evaluation'];
 export const VALID_STATUSES = ['planned', 'ready', 'in_progress', 'review', 'complete', 'blocked', 'parked', 'killed'];
 export const VALID_CONNECTION_TYPES = ['informs', 'blocks', 'supports', 'contradicts', 'implements'];
 export const VALID_PHASES = ['vision', 'specification', 'planning', 'implementation', 'verification', 'release'];