@smartmemory/compose 0.2.20-beta → 0.2.21-beta

package/bin/compose.js

@@ -1628,6 +1628,9 @@ if (cmd === 'validate') {
   let blockOn = 'error'
   let asJson = false
   let externalXref = false
+  let doFix = false
+  let doApply = false
+  let fixClasses = null
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--help' || a === '-h') {
@@ -1639,15 +1642,23 @@ Options:
   --block-on=LEVEL            Exit non-zero if any finding >= LEVEL (default: error)
                               LEVEL: error | warning | info
   --json                      Emit findings as JSON (default: human-readable)
+  --fix                       Reconcile mechanical drift (dry-run: prints a fix plan)
+  --apply                     With --fix, write the fixes (default is dry-run)
+  --fix-class=CSV             Override the fix class set, e.g.
+                              dangling_link,invalid_link_kind,status_fj_vision,
+                              partial_age,roadmap_status_rewrite,invalid_link_kind_repair
 
 Exit codes:
   0   no findings >= block-on threshold
   1   findings >= block-on threshold present
-  2   usage error`)
+  2   usage error (or reconcile refused on a non-local provider)`)
       process.exit(0)
     }
     if (a === '--json') { asJson = true; continue }
     if (a === '--external') { externalXref = true; continue }
+    if (a === '--fix') { doFix = true; continue }
+    if (a === '--apply') { doApply = true; continue }
+    if (a.startsWith('--fix-class=')) { fixClasses = a.slice('--fix-class='.length).split(',').map((s) => s.trim()).filter(Boolean); continue }
     if (a.startsWith('--scope=')) scope = a.slice('--scope='.length)
     else if (a === '--scope') scope = args[++i]
     else if (a.startsWith('--code=')) code = a.slice('--code='.length)
@@ -1695,13 +1706,64 @@ Exit codes:
     process.exit(2)
   }
 
+  // --fix: reconcile mechanical drift. Dry-run prints a plan; --apply writes and
+  // re-validates so the exit code reflects what's left after the fixes.
+  let reconcile = null
+  if (doFix) {
+    const { reconcileProject } = await import('../lib/feature-reconciler.js')
+    reconcile = await reconcileProject(valCwd, {
+      apply: doApply,
+      classes: fixClasses,
+      scope,
+      code,
+      external: externalXref,
+    })
+    if (reconcile.refused === 'non_local_provider') {
+      console.error('compose validate --fix: reconcile is local-provider only (this workspace uses a remote tracker). No changes made.')
+      process.exit(2)
+    }
+    if (doApply) {
+      // Re-validate so findings/exit reflect the post-fix state.
+      result = scope === 'feature'
+        ? await validateFeature(valCwd, code)
+        : await validateProject(valCwd, { external: externalXref })
+    }
+    if (!asJson) {
+      const verb = doApply ? 'applied' : 'would apply'
+      const total = reconcile.plan.length
+      console.log(`compose validate --fix (${doApply ? 'apply' : 'dry-run'}): ${verb} ${total} fix(es)`)
+      for (const e of reconcile.plan) {
+        const cls = e.classes.join(',')
+        console.log(`  [${cls}] ${e.feature_code}: ${e.action}`)
+        console.log(`    before: ${Array.isArray(e.before) ? e.before.join(', ') : e.before}`)
+        console.log(`    after:  ${Array.isArray(e.after) ? e.after.join(', ') : e.after}`)
+      }
+      for (const s of reconcile.skipped_classes || []) {
+        console.log(`  (skipped class ${s.class}: ${s.reason})`)
+      }
+      if (doApply) {
+        const failed = (reconcile.applied || []).filter((a) => !a.ok)
+        if (failed.length) {
+          console.log(`  ${failed.length} fix(es) failed:`)
+          for (const f of failed) console.log(`    ${f.feature_code} ${f.action}: ${f.error}`)
+        }
+        const noops = (reconcile.applied || []).filter((a) => a.ok && a.noop)
+        if (noops.length) {
+          console.log(`  ${noops.length} fix(es) made no change (refused as unsafe/ambiguous; left for manual review):`)
+          for (const n of noops) console.log(`    ${n.feature_code} ${n.action}`)
+        }
+      }
+      console.log('')
+    }
+  }
+
   // Threshold: findings at or above this severity block the exit code
   const SEV_RANK = { error: 3, warning: 2, info: 1 }
   const threshold = SEV_RANK[blockOn]
   const blocking = result.findings.filter((f) => SEV_RANK[f.severity] >= threshold)
 
   if (asJson) {
-    console.log(JSON.stringify(result, null, 2))
+    console.log(JSON.stringify(reconcile ? { ...result, reconcile } : result, null, 2))
   } else {
     const byKind = {}
     for (const f of result.findings) {

package/lib/feature-json.js

@@ -6,7 +6,7 @@
  * ROADMAP.md is generated from these files.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
 import { readdirSync } from 'fs';
 import { assertValidLinkShape, assertLinkTargetsExist } from './feature-write-guard.js';
@@ -70,7 +70,17 @@ export function writeFeature(cwd, feature, featuresDir = 'docs/features', opts =
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'feature.json');
   feature.updated = new Date().toISOString().slice(0, 10);
-  writeFileSync(path, JSON.stringify(feature, null, 2) + '\n');
+  // Atomic write: temp + rename so a crash mid-write can't leave a half-written
+  // feature.json (a bulk reconcile may touch many features). Mirrors
+  // VisionWriter._atomicWrite / LocalFileProvider.putChangelog.
+  const tmp = `${path}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(feature, null, 2) + '\n');
+    renameSync(tmp, path);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* tmp may not exist */ }
+    throw err;
+  }
 }
 
 // Sentinel for absent / non-numeric positions: sorts them after any real

package/lib/feature-reconciler.js

@@ -0,0 +1,358 @@
+/**
+ * feature-reconciler.js — COMP-MCP-VALIDATE-2 `compose validate --fix`.
+ *
+ * Turns the detect-only validator into a closed loop. Reuses the validator's
+ * context builders (loadValidationContext / loadFeatureContext) and its emitted
+ * findings, derives the canonical fix for the mechanical drift classes, and —
+ * on apply — executes each fix through a typed writer (rewriteLinks,
+ * resyncRoadmap, setFeatureStatus, VisionWriter).
+ *
+ * Design decisions (see docs/features/COMP-MCP-VALIDATE-2/blueprint.md):
+ *  - Validator stays detect-only; this is a sibling pass, not a mutation hook.
+ *  - Status/ROADMAP classes dispatch on the validator's findings (post-projection,
+ *    narrative-suppressed); link + partial classes derive from ctx (no clean
+ *    finding exists). This honors the validator's exact semantics.
+ *  - v1 is local-provider only: GitHubProvider's putFeature/renderRoadmap skip the
+ *    local existence + narrative-no-op guarantees the fixes rely on.
+ *  - Dry-run by default; per-class opt-in; destructive/heuristic classes off by
+ *    default.
+ */
+
+import { readFileSync } from 'fs';
+
+import {
+  loadValidationContext,
+  loadFeatureContext,
+  validateProject,
+} from './feature-validator.js';
+import {
+  getProvider,
+  isLocalProvider,
+  rewriteLinks,
+  setRoadmapRowStatus,
+  setFeatureStatus,
+  _internals,
+} from './feature-writer.js';
+import { featureStatusToVisionStatus } from './status-projection.js';
+
+const VALID_LINK_KINDS = new Set([..._internals.LINK_KINDS, 'external']);
+const CANONICAL_DOCS = new Set([
+  'design.md', 'prd.md', 'architecture.md', 'blueprint.md', 'plan.md', 'report.md',
+]);
+
+// Class registry. `default` = enabled by a bare --fix; opt-in classes require
+// explicit selection. `mutatesFeatureJson` classes are dropped when
+// featureJsonMode is false (feature.json is not canonical in legacy mode).
+export const FIX_CLASSES = {
+  dangling_link:          { default: true,  mutatesFeatureJson: true,  group: 'link' },
+  invalid_link_kind:      { default: true,  mutatesFeatureJson: true,  group: 'link' },
+  // Modifier on invalid_link_kind: repair to nearest allowed instead of dropping.
+  invalid_link_kind_repair: { default: false, mutatesFeatureJson: true, group: 'link' },
+  status_fj_vision:       { default: true,  mutatesFeatureJson: false, group: 'status_vision' },
+  partial_age:            { default: false, mutatesFeatureJson: true,  group: 'partial' },
+  roadmap_status_rewrite: { default: false, mutatesFeatureJson: false, group: 'roadmap' },
+};
+
+export function defaultClasses() {
+  return Object.entries(FIX_CLASSES).filter(([, v]) => v.default).map(([k]) => k);
+}
+
+// ---------------------------------------------------------------------------
+// nearestLinkKind — edit-distance repair for an invalid link kind
+// ---------------------------------------------------------------------------
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...new Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Nearest allowed link kind to `bad`, or null if ambiguous / too far.
+ * Conservative: distance must be ≤ 2 and the minimum must be unique.
+ * Never targets 'external' (a structural kind, not a typo of the rest).
+ */
+export function nearestLinkKind(bad) {
+  if (typeof bad !== 'string' || !bad) return null;
+  let best = null, bestD = Infinity, tie = false;
+  for (const k of _internals.LINK_KINDS) {
+    const d = levenshtein(bad.toLowerCase(), k);
+    if (d < bestD) { bestD = d; best = k; tie = false; }
+    else if (d === bestD) { tie = true; }
+  }
+  if (bestD <= 2 && !tie) return best;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Derive — build the dry-run fix plan from ctx + findings
+// ---------------------------------------------------------------------------
+
+function changelogMentions(ctx, code) {
+  let text = '';
+  try { text = readFileSync(ctx.paths.changelog, 'utf8'); } catch { return false; }
+  const re = new RegExp(`^###\\s+${code}(?:\\s|$)`, 'm');
+  return re.test(text);
+}
+
+// Per-feature link rewrite covering dangling_link + invalid_link_kind. Returns a
+// single plan entry per feature whose links[] needs changes, or null.
+function deriveLinkFix(ctx, code, active) {
+  const fctx = loadFeatureContext(ctx.cwd, code, ctx);
+  const links = fctx.featureJson?.links;
+  if (!Array.isArray(links) || links.length === 0) return null;
+
+  const dropDangling = active.has('dangling_link');
+  const fixKind = active.has('invalid_link_kind');
+  const repair = active.has('invalid_link_kind_repair');
+  if (!dropDangling && !fixKind) return null;
+
+  const next = [];
+  const changes = [];
+  for (const link of links) {
+    // Dangling: a to_code that resolves in no source. Mirrors the validator's
+    // cross-feature check EXACTLY (feature-validator.js:593-601) — including that
+    // it does not special-case kind:"external". A well-formed external link
+    // carries no to_code (provider/repo/issue/url instead), so this guard skips
+    // it; only a malformed external link with an unresolved to_code is dropped,
+    // which is precisely what the validator flags. Matching the validator
+    // guarantees --fix converges on every DANGLING_LINK_FEATURES_TARGET it emits.
+    const isDangling = dropDangling && link.to_code
+      && !ctx.foldersByCode.has(link.to_code)
+      && !ctx.roadmapByCode.has(link.to_code)
+      && !ctx.visionByCode.has(link.to_code);
+    if (isDangling) {
+      changes.push({ op: 'drop', reason: 'dangling', kind: link.kind, to_code: link.to_code });
+      continue;
+    }
+    // Invalid kind.
+    if (fixKind && !VALID_LINK_KINDS.has(link.kind)) {
+      const repaired = repair ? nearestLinkKind(link.kind) : null;
+      if (repaired) {
+        changes.push({ op: 'repair', from_kind: link.kind, to_kind: repaired, to_code: link.to_code });
+        next.push({ ...link, kind: repaired });
+      } else {
+        changes.push({ op: 'drop', reason: 'invalid_kind', kind: link.kind, to_code: link.to_code });
+      }
+      continue;
+    }
+    next.push(link);
+  }
+  if (changes.length === 0) return null;
+  return {
+    feature_code: code,
+    group: 'link',
+    classes: [...new Set(changes.map((c) => c.reason === 'invalid_kind' || c.op === 'repair' ? 'invalid_link_kind' : 'dangling_link'))],
+    action: 'rewrite_links',
+    before: links.map((l) => `${l.kind}→${l.to_code ?? '(external)'}`),
+    after: next.map((l) => `${l.kind}→${l.to_code ?? '(external)'}`),
+    changes,
+    _links: next,
+  };
+}
+
+function deriveStatusVisionFix(ctx, finding) {
+  const code = finding.feature_code;
+  if (!code) return null;
+  const fctx = loadFeatureContext(ctx.cwd, code, ctx);
+  const fjStatus = fctx.featureJson?.status;
+  const visStatus = featureStatusToVisionStatus(fjStatus);
+  if (!visStatus) return null;
+  const vision = ctx.visionByCode.get(code);
+  return {
+    feature_code: code,
+    group: 'status_vision',
+    classes: ['status_fj_vision'],
+    action: 'update_vision_status',
+    before: vision?.status ?? null,
+    after: visStatus,
+    _visStatus: visStatus,
+  };
+}
+
+function deriveRoadmapFix(ctx, finding) {
+  const code = finding.feature_code;
+  if (!code) return null;
+  const fctx = loadFeatureContext(ctx.cwd, code, ctx);
+  const canonical = fctx.featureJson?.status;
+  if (!canonical) return null;
+  // Only plan a fix when the ROADMAP's parsed "status" is itself a recognized
+  // status token. When it is not (e.g. a row whose description contains an
+  // escaped pipe, so the validator parsed prose into the status column), the
+  // surgical writer would refuse the edit anyway — so planning it would produce
+  // a misleading dry-run that promises a change apply won't make. Keep the
+  // planner as conservative as the writer: structural row problems are left for
+  // manual review, not auto-"fixed".
+  const before = ctx.roadmapByCode.get(code)?.status ?? null;
+  if (!before || !_internals.STATUSES.has(String(before).toUpperCase())) return null;
+  return {
+    feature_code: code,
+    group: 'roadmap',
+    classes: ['roadmap_status_rewrite'],
+    action: 'set_roadmap_row_status',
+    before,
+    after: canonical,
+    _status: canonical,
+  };
+}
+
+function derivePartialFix(ctx, code) {
+  const fctx = loadFeatureContext(ctx.cwd, code, ctx);
+  const status = (fctx.featureJson?.status || '').toUpperCase();
+  if (status !== 'PARTIAL') return null;
+  const folder = fctx.folder;
+  if (!folder) return null;
+  const hasCanonicalDoc = [...folder.files].some((f) => CANONICAL_DOCS.has(f));
+  const hasArtifacts = Array.isArray(fctx.featureJson?.artifacts) && fctx.featureJson.artifacts.length > 0;
+  if (hasCanonicalDoc || hasArtifacts || changelogMentions(ctx, code)) return null;
+  return {
+    feature_code: code,
+    group: 'partial',
+    classes: ['partial_age'],
+    action: 'set_status',
+    before: 'PARTIAL',
+    after: 'PLANNED',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Apply — execute a single plan entry through a typed writer
+// ---------------------------------------------------------------------------
+
+// Returns { changed } — changed:false means the writer made no change (e.g. a
+// guarded refusal or already-correct), so callers don't report it as applied.
+async function applyEntry(cwd, entry) {
+  switch (entry.action) {
+    case 'rewrite_links':
+      await rewriteLinks(cwd, { from_code: entry.feature_code, links: entry._links });
+      return { changed: true };
+    case 'update_vision_status': {
+      const { VisionWriter } = await import('./vision-writer.js');
+      const { join } = await import('path');
+      const writer = new VisionWriter(join(cwd, '.compose', 'data'));
+      const item = await writer.findFeatureItem(entry.feature_code);
+      if (!item) return { changed: false };
+      await writer.updateItemStatus(item.id, entry._visStatus);
+      return { changed: true };
+    }
+    case 'set_status':
+      await setFeatureStatus(cwd, { code: entry.feature_code, status: entry.after, derived: true });
+      return { changed: true };
+    case 'set_roadmap_row_status': {
+      const r = await setRoadmapRowStatus(cwd, { code: entry.feature_code, status: entry._status });
+      return { changed: r.changed !== false };
+    }
+    default:
+      throw new Error(`feature-reconciler: unknown action "${entry.action}"`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// reconcileProject — the public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {boolean} [opts.apply=false]      Write fixes (default: dry-run).
+ * @param {string[]} [opts.classes]         Enabled class keys (default: defaultClasses()).
+ * @param {string} [opts.scope='project']   'project' | 'feature'.
+ * @param {string} [opts.code]              Required when scope='feature'.
+ * @param {boolean} [opts.featureJsonMode]  Forwarded to the validator/context.
+ * @param {string[]} [opts.externalPrefixes]
+ * @param {boolean} [opts.external]
+ * @returns {Promise<object>} { scope, plan, counts, applied?, refused?, skipped_classes? }
+ */
+export async function reconcileProject(cwd, opts = {}) {
+  const apply = opts.apply === true;
+  const scope = opts.scope === 'feature' ? 'feature' : 'project';
+
+  // Provider guard (C8): v1 reconcile is local-provider only.
+  const provider = await getProvider(cwd);
+  if (!isLocalProvider(provider)) {
+    return { scope, refused: 'non_local_provider', plan: [], counts: {} };
+  }
+
+  const valOpts = {
+    featureJsonMode: opts.featureJsonMode,
+    externalPrefixes: opts.externalPrefixes,
+    external: opts.external === true,
+  };
+  const { findings } = await validateProject(cwd, valOpts);
+  const ctx = loadValidationContext(cwd, valOpts);
+
+  // Active class set, with mode guard (C7).
+  let active = new Set(
+    (opts.classes && opts.classes.length ? opts.classes : defaultClasses())
+      .filter((k) => FIX_CLASSES[k]),
+  );
+  const skipped_classes = [];
+  if (ctx.featureJsonMode === false) {
+    for (const k of [...active]) {
+      if (FIX_CLASSES[k].mutatesFeatureJson) {
+        active.delete(k);
+        skipped_classes.push({ class: k, reason: 'feature_json_mode_off' });
+      }
+    }
+  }
+
+  const codeFilter = (c) => scope === 'feature' ? c === opts.code : true;
+  const codes = [...ctx.foldersByCode.keys()].filter(codeFilter);
+  const plan = [];
+
+  // Link classes (ctx-derived, per-feature single rewrite).
+  if (active.has('dangling_link') || active.has('invalid_link_kind')) {
+    for (const code of codes) {
+      const entry = deriveLinkFix(ctx, code, active);
+      if (entry) plan.push(entry);
+    }
+  }
+  // partial_age (ctx-derived).
+  if (active.has('partial_age')) {
+    for (const code of codes) {
+      const entry = derivePartialFix(ctx, code);
+      if (entry) plan.push(entry);
+    }
+  }
+  // Finding-sourced classes.
+  for (const f of findings) {
+    if (!codeFilter(f.feature_code)) continue;
+    if (active.has('status_fj_vision') && f.kind === 'STATUS_MISMATCH_FEATUREJSON_VS_VISION_STATE') {
+      const e = deriveStatusVisionFix(ctx, f);
+      if (e) plan.push(e);
+    }
+    if (active.has('roadmap_status_rewrite') && f.kind === 'STATUS_MISMATCH_ROADMAP_VS_FEATUREJSON') {
+      const e = deriveRoadmapFix(ctx, f);
+      if (e) plan.push(e);
+    }
+  }
+
+  const counts = {};
+  for (const e of plan) for (const c of e.classes) counts[c] = (counts[c] || 0) + 1;
+
+  if (!apply) {
+    return { scope, dry_run: true, plan, counts, skipped_classes };
+  }
+
+  const applied = [];
+  for (const entry of plan) {
+    try {
+      const { changed } = await applyEntry(cwd, entry);
+      // ok = "did not error"; noop = "made no change" (a guarded refusal, e.g. a
+      // malformed/escaped-pipe ROADMAP row the surgical writer declined). Surfacing
+      // noop honestly means --fix never claims a repair it didn't make; the caller
+      // re-validates to confirm actual convergence.
+      applied.push({ feature_code: entry.feature_code, action: entry.action, ok: true, noop: changed === false });
+    } catch (err) {
+      applied.push({ feature_code: entry.feature_code, action: entry.action, ok: false, error: err.message });
+    }
+  }
+  return { scope, dry_run: false, plan, counts, applied, skipped_classes };
+}

package/lib/feature-validator.js

@@ -124,7 +124,7 @@ function resolveProjectPaths(cwd) {
 // Context loading
 // ---------------------------------------------------------------------------
 
-function loadValidationContext(cwd, options = {}) {
+export function loadValidationContext(cwd, options = {}) {
   const paths = resolveProjectPaths(cwd);
 
   // ROADMAP — direct table-row scan. Validator can't depend on parseRoadmap()
@@ -267,12 +267,12 @@ function loadValidationContext(cwd, options = {}) {
 // Effective status for per-feature checks. feature.json is canonical; the parsed
 // ROADMAP row is only a fallback — and NOT even that on a narrative-owned
 // workspace, where the row is hand-authored prose (#39).
-function effectiveStatus(fctx, ctx) {
+export function effectiveStatus(fctx, ctx) {
   return normalizeStatus(fctx.featureJson?.status)
     || (ctx?.narrativeOwned ? null : normalizeStatus(fctx.roadmap?.status));
 }
 
-function loadFeatureContext(cwd, code, ctx) {
+export function loadFeatureContext(cwd, code, ctx) {
   const folder = ctx.foldersByCode.get(code);
   let featureJson = null;
   if (folder?.hasFeatureJson && ctx.featureJsonMode) {

package/lib/feature-writer.js

@@ -16,7 +16,7 @@
  * be called from MCP tools, the CLI, or future REST routes.
  */
 
-import { existsSync, realpathSync, statSync, readFileSync } from 'fs';
+import { existsSync, realpathSync, statSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import { resolve, normalize, sep, basename, dirname, join } from 'path';
 
 import { readEvents } from './feature-events.js';
@@ -29,7 +29,7 @@ import { knownFeatureCodes, FeatureWriteValidationError } from './feature-write-
 // providerFor is imported lazily (inside each function) to break the
 // module-load-time cycle: factory.js → local-provider.js → feature-writer.js.
 // Dynamic import resolves at call time, after all modules have loaded.
-async function getProvider(cwd) {
+export async function getProvider(cwd) {
   const { providerFor } = await import('./tracker/factory.js');
   return providerFor(cwd);
 }
@@ -209,7 +209,7 @@ function partialWriteError(message, cause) {
 // wrapping GitHubProvider otherwise — name() resolves correctly through both.
 // Test mock providers that don't model the local file tracker won't report
 // 'local', so the guard is correctly skipped for them.
-function isLocalProvider(provider) {
+export function isLocalProvider(provider) {
   return typeof provider?.name === 'function' && provider.name() === 'local';
 }
 
@@ -647,6 +647,161 @@ export async function linkFeatures(cwd, args) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// rewriteLinks — replace a feature's entire links[] array in one write
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace `feature.links` wholesale. Unlike linkFeatures (add/upsert-only), this
+ * is the removal/repair primitive the reconciler (COMP-MCP-VALIDATE-2) needs:
+ * dropping danglings and repairing invalid kinds in a SINGLE write so the
+ * whole-array validation in putFeature can't block one fix behind another.
+ * The caller computes the corrected array; this persists it through the same
+ * VALIDATE-1 guard (delta-aware existence) and audit chokepoint as the other
+ * link writers.
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.from_code
+ * @param {Array<{kind:string,to_code?:string,note?:string,provider?:string}>} args.links
+ * @param {boolean} [args.allowForwardRefs] — permit a known-good forward ref target
+ * @param {string} [args.idempotency_key]
+ */
+export async function rewriteLinks(cwd, args) {
+  validateCode(args.from_code);
+  if (!Array.isArray(args.links)) {
+    throw new Error('feature-writer: rewriteLinks requires args.links to be an array');
+  }
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+    const feature = await provider.getFeature(args.from_code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.from_code}" not found`);
+    }
+    const before = Array.isArray(feature.links) ? feature.links.length : 0;
+    await provider.putFeature(
+      args.from_code,
+      { ...feature, links: args.links },
+      { allowForwardRefs: args.allowForwardRefs === true },
+    );
+    await safeAppendEvent(cwd, {
+      tool: 'rewrite_links',
+      code: args.from_code,
+      before_count: before,
+      after_count: args.links.length,
+      idempotency_key: args.idempotency_key,
+    });
+    return { from_code: args.from_code, before_count: before, after_count: args.links.length };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// setRoadmapRowStatus — surgical single-cell ROADMAP status edit
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace ONLY the Status cell of a feature's ROADMAP.md table row, leaving every
+ * other byte of the file untouched. Used by the reconciler to heal a
+ * ROADMAP-row↔feature.json status drift when feature.json is already canonical.
+ *
+ * A full renderRoadmap() is unsafe here: on any ROADMAP that is not already in
+ * exact generated form it appends a generated section beside the hand-authored
+ * one, producing duplicate conflicting rows (COMP-MCP-VALIDATE-2 finding). This
+ * surgical edit mirrors the validator's column-aware row parser
+ * (feature-validator.js:139-203): it locates the table by header (Feature/Status
+ * columns), finds the data row whose code matches, and rewrites just the status
+ * token in that cell — preserving spacing and any emphasis markers.
+ *
+ * ROADMAP uses the same UPPERCASE status vocabulary as feature.json, so `status`
+ * is written verbatim (no projection).
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.code
+ * @param {string} args.status — canonical UPPERCASE status (e.g. 'IN_PROGRESS')
+ * @param {string} [args.idempotency_key]
+ * @returns {Promise<{code:string, changed:boolean, from?:string, to?:string}>}
+ */
+export async function setRoadmapRowStatus(cwd, args) {
+  validateCode(args.code);
+  if (!STATUSES.has(args.status)) {
+    throw new Error(`feature-writer: invalid status "${args.status}"`);
+  }
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const roadmapPath = join(cwd, 'ROADMAP.md');
+    let text;
+    try { text = readFileSync(roadmapPath, 'utf-8'); }
+    catch { return { code: args.code, changed: false }; }
+
+    const lines = text.split('\n');
+    let codeIdx = -1, statusIdx = -1, inTable = false, sawSeparator = false;
+    // Record the LAST matching row, not the first: the validator builds
+    // roadmapByCode = new Map(rows.map(...)) so a later duplicate row wins
+    // (feature-validator.js:206). Patching the first occurrence on a ROADMAP with
+    // duplicate rows would leave the validator's (last) row mismatched → no
+    // convergence. Mirror its last-wins semantics.
+    let target = null; // { line, cellPos, from }
+
+    for (let i = 0; i < lines.length; i++) {
+      const rawLine = lines[i];
+      if (/^##\s+/.test(rawLine)) { inTable = false; sawSeparator = false; codeIdx = statusIdx = -1; continue; }
+      const rowMatch = rawLine.match(/^\|(.+)\|\s*$/);
+      if (!rowMatch) { inTable = false; sawSeparator = false; continue; }
+      const cols = rowMatch[1].split('|').map((c) => c.trim());
+      const lower = cols.map((c) => c.toLowerCase());
+      const fCol = lower.findIndex((c) => ['feature', 'code', 'item', 'name'].includes(c));
+      const sCol = lower.findIndex((c) => ['status', 'state'].includes(c));
+      if (fCol >= 0 && sCol >= 0) { codeIdx = fCol; statusIdx = sCol; inTable = true; sawSeparator = false; continue; }
+      if (cols.every((c) => /^[-:]+$/.test(c))) { if (inTable) sawSeparator = true; continue; }
+      if (!inTable || !sawSeparator || codeIdx < 0 || statusIdx < 0) continue;
+      if (codeIdx >= cols.length || statusIdx >= cols.length) continue;
+
+      const codeRaw = cols[codeIdx].replace(/\*/g, '').replace(/`/g, '').trim();
+      if (codeRaw !== args.code) continue;
+
+      // Refuse rows containing an escaped pipe: `\|` splits a logical cell in two,
+      // so the header-derived column index can land mid-prose. Skipping such a
+      // row avoids the only realistic corruption vector (the validator mis-parses
+      // it too — surfaced honestly as an unfixed mismatch rather than mangled).
+      if (rawLine.includes('\\|')) continue;
+
+      // inner-cell index → raw-line index: rawLine.split('|') = ['', ...innerCells, '']
+      // so innerCells[statusIdx] === rawCells[statusIdx+1]. The validator reads the
+      // same header-identified cell, so overwriting it converges — including when
+      // the current value is a non-canonical alpha status (e.g. "Done").
+      const rawCells = rawLine.split('|');
+      const cellPos = statusIdx + 1;
+      if (cellPos >= rawCells.length) continue;
+      const tok = rawCells[cellPos].match(/[A-Za-z_]+/);
+      // Require an alpha status token. An empty / purely-numeric cell is too
+      // ambiguous to safely rewrite, so skip it (reported as changed:false).
+      if (!tok) continue;
+      target = { line: i, cellPos, from: tok[0] };
+    }
+
+    if (!target) return { code: args.code, changed: false };
+    const fromStatus = target.from;
+    if (fromStatus === args.status) return { code: args.code, changed: false, from: fromStatus, to: args.status };
+    const rawCells = lines[target.line].split('|');
+    rawCells[target.cellPos] = rawCells[target.cellPos].replace(/[A-Za-z_]+/, args.status);
+    lines[target.line] = rawCells.join('|');
+
+    const out = lines.join('\n');
+    const tmp = `${roadmapPath}.tmp.${process.pid}`;
+    try { writeFileSync(tmp, out); renameSync(tmp, roadmapPath); }
+    catch (err) { try { unlinkSync(tmp); } catch { /* noop */ } throw err; }
+
+    await safeAppendEvent(cwd, {
+      tool: 'set_roadmap_row_status',
+      code: args.code,
+      from: fromStatus,
+      to: args.status,
+      idempotency_key: args.idempotency_key,
+    });
+    return { code: args.code, changed: true, from: fromStatus, to: args.status };
+  });
+}
+
 const XREF_PROVIDERS = new Set(['github', 'local', 'url', 'jira', 'linear', 'notion', 'obsidian']);
 const XREF_URL_CLASS = new Set(['url', 'jira', 'linear', 'notion', 'obsidian']);
 const URI_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;

package/package.json

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

@@ -431,12 +431,30 @@ export async function toolValidateFeature(args = {}) {
 
 export async function toolValidateProject(args = {}) {
   const { validateProject } = await import('../lib/feature-validator.js');
-  const { external_prefixes, feature_json_mode, external } = args;
-  return validateProject(getTargetRoot(), {
+  const { external_prefixes, feature_json_mode, external, fix, apply, fix_classes } = args;
+  const opts = {
     externalPrefixes: external_prefixes,
     featureJsonMode: feature_json_mode,
     external: external === true,
+  };
+  const result = await validateProject(getTargetRoot(), opts);
+  if (!fix) return result;
+  // COMP-MCP-VALIDATE-2: reconcile mechanical drift. Forwards the same validate
+  // options so the fixer operates on the same context that was validated.
+  const { reconcileProject } = await import('../lib/feature-reconciler.js');
+  const reconcile = await reconcileProject(getTargetRoot(), {
+    apply: apply === true,
+    classes: fix_classes,
+    featureJsonMode: feature_json_mode,
+    externalPrefixes: external_prefixes,
+    external: external === true,
   });
+  // When fixes were applied, re-validate so the returned findings reflect the
+  // post-fix state (closed loop).
+  const finalResult = (apply === true && !reconcile.refused)
+    ? await validateProject(getTargetRoot(), opts)
+    : result;
+  return { ...finalResult, reconcile };
 }
 
 export async function toolBindSession({ featureCode, profile } = {}) {

package/server/compose-mcp.js

@@ -377,6 +377,9 @@ const TOOLS = [
         external_prefixes: { type: 'array', items: { type: 'string' } },
         feature_json_mode: { type: 'boolean' },
         external: { type: 'boolean', description: 'Resolve github external refs over the network (read-only). Default false: github refs degrade to XREF_RESOLUTION_SKIPPED.' },
+        fix: { type: 'boolean', description: 'COMP-MCP-VALIDATE-2: reconcile mechanical drift. Returns a fix plan under `reconcile` (dry-run unless apply:true). Local-provider only.' },
+        apply: { type: 'boolean', description: 'With fix:true, write the fixes and re-validate. Default false (dry-run plan only).' },
+        fix_classes: { type: 'array', items: { type: 'string' }, description: 'Override the enabled fix classes: dangling_link, invalid_link_kind, status_fj_vision, partial_age, roadmap_status_rewrite, invalid_link_kind_repair. Default: the non-destructive set.' },
       },
     },
   },