@smartmemory/compose 0.1.44-beta → 0.2.1-beta

package/README.md

@@ -32,7 +32,7 @@ compose build TODO-1
 
 ## Quick install
 
-Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum`). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
+Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum-mcp`, requires Python 3.11+). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
 
 The package is published to npm as `@smartmemory/compose`. Pick one install style:
 

package/bin/compose.js

@@ -119,6 +119,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
   console.log('  roadmap migrate    Extract ROADMAP.md entries into feature.json files')
   console.log('  roadmap check      Verify feature.json and ROADMAP.md are in sync')
+  console.log('  roadmap xref-sync  Pull-reconcile feature.json external links to live state')
   console.log('  items              List vision items from local state (no server)')
   console.log('  items show <id>    Show detail for a specific vision item')
   console.log('  triage    Analyze a feature and recommend build profile')
@@ -1036,22 +1037,47 @@ _This is a seed design doc created by \`compose feature\`. The \`compose build\`
 if (cmd === 'roadmap') {
   const subcmd = args[0]
 
-  // compose roadmap generate — regenerate ROADMAP.md from feature.json files
+  // compose roadmap generate — regenerate ROADMAP.md from feature.json files,
+  // converging to a fixed point before finishing.
   if (subcmd === 'generate' || subcmd === 'gen') {
     const { writeRoadmap } = await import('../lib/roadmap-gen.js')
+    const { checkRoundtrip } = await import('../lib/roadmap-roundtrip.js')
+    const { listFeatures } = await import('../lib/feature-json.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
+    const { isNarrativeOwned } = await import('../lib/roadmap-config.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
+    // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not a render
+    // of feature.json. writeRoadmap already no-ops, but the canonicalization pass
+    // below would still overwrite the file (or crash if it's absent) — skip the
+    // whole generate path here so the hand-authored file is never touched.
+    if (isNarrativeOwned(cwd)) {
+      console.log('narrative-owned workspace (roadmap.narrative=true) — ROADMAP.md is hand-authored; generate skipped.')
+      process.exit(0)
+    }
     const path = writeRoadmap(cwd)
-    console.log(`Generated ${path} from feature.json files`)
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    // checkRoundtrip's now:'0000-00-00' is only used to detect/canonicalize
+    // structural non-convergence — once the file has headings, readPreamble
+    // preserves the existing preamble date verbatim, so no sentinel date leaks.
+    const rt = checkRoundtrip(readFileSync(path, 'utf-8'), listFeatures(cwd), { now: '0000-00-00', externalPrefixes })
+    if (!rt.fixedPoint) {
+      writeFileSync(path, rt.canonical)
+      console.log(`Generated ${path} (canonicalized over ${rt.passes} passes)`)
+    } else {
+      console.log(`Generated ${path} from feature.json files`)
+    }
     process.exit(0)
   }
 
   // compose roadmap migrate — extract ROADMAP.md entries into feature.json files
   if (subcmd === 'migrate') {
     const { migrateRoadmap } = await import('../lib/migrate-roadmap.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
     const dryRun = args.includes('--dry-run')
     const overwrite = args.includes('--overwrite')
-    const result = migrateRoadmap(cwd, { dryRun, overwrite })
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    const result = migrateRoadmap(cwd, { dryRun, overwrite, externalPrefixes })
     if (!dryRun) {
       console.log(`Created: ${result.created.length} feature.json files`)
       if (result.created.length > 0) console.log(`  ${result.created.join(', ')}`)
@@ -1059,6 +1085,9 @@ if (cmd === 'roadmap') {
       if (result.updated.length > 0) console.log(`  ${result.updated.join(', ')}`)
       console.log(`Skipped: ${result.skipped.length} (already exist, use --overwrite to replace)`)
       if (result.skipped.length > 0) console.log(`  ${result.skipped.join(', ')}`)
+      const ext = result.skippedExternal ?? []
+      console.log(`Skipped (external, cross-project refs): ${ext.length}`)
+      if (ext.length > 0) console.log(`  ${ext.join(', ')}`)
     }
     process.exit(0)
   }
@@ -1066,49 +1095,56 @@ if (cmd === 'roadmap') {
   // compose roadmap check — verify feature.json ↔ ROADMAP.md consistency
   if (subcmd === 'check') {
     const { listFeatures } = await import('../lib/feature-json.js')
-    const { parseRoadmap } = await import('../lib/roadmap-parser.js')
+    const { checkRoundtrip, describeLossyDiff } = await import('../lib/roadmap-roundtrip.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
     const roadmapPath = join(cwd, 'ROADMAP.md')
     if (!existsSync(roadmapPath)) {
       console.error('No ROADMAP.md found. Run: compose roadmap generate')
       process.exit(1)
     }
-    const features = listFeatures(cwd)
-    const roadmapEntries = parseRoadmap(readFileSync(roadmapPath, 'utf-8'))
-    const roadmapCodes = new Set(roadmapEntries.filter(e => !e.code.startsWith('_anon_')).map(e => e.code))
-    const featureCodes = new Set(features.map(f => f.code))
-
-    let clean = true
-    // Features in feature.json but missing from ROADMAP.md
-    for (const f of features) {
-      if (!roadmapCodes.has(f.code)) {
-        console.log(`MISSING from ROADMAP.md: ${f.code}`)
-        clean = false
-      }
+    // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not a render
+    // of feature.json — the roundtrip would always report false drift. The file
+    // must still EXIST (checked above); we only skip the drift comparison.
+    const { isNarrativeOwned } = await import('../lib/roadmap-config.js')
+    if (isNarrativeOwned(cwd)) {
+      console.log('narrative-owned workspace (roadmap.narrative=true) — ROADMAP.md is hand-authored; roundtrip check skipped.')
+      process.exit(0)
     }
-    // Features in ROADMAP.md but missing feature.json
-    for (const e of roadmapEntries) {
-      if (e.code.startsWith('_anon_')) continue
-      if (!featureCodes.has(e.code)) {
-        console.log(`NO feature.json: ${e.code}`)
-        clean = false
-      }
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    const rt = checkRoundtrip(readFileSync(roadmapPath, 'utf-8'), listFeatures(cwd), { now: '0000-00-00', externalPrefixes })
+    if (rt.fixedPoint && rt.lossless) {
+      console.log('feature.json and ROADMAP.md are in sync (fixed point, lossless).')
+      process.exit(0)
     }
-    // Status mismatches
-    const roadmapMap = new Map(roadmapEntries.map(e => [e.code, e]))
-    for (const f of features) {
-      const rm = roadmapMap.get(f.code)
-      if (rm && rm.status !== f.status) {
-        console.log(`STATUS MISMATCH: ${f.code} — feature.json=${f.status}, ROADMAP.md=${rm.status}`)
-        clean = false
-      }
+    if (!rt.fixedPoint) {
+      const d = rt.diffs.find(x => x.kind === 'FIXED_POINT_DIVERGENCE')
+      console.log(`NOT A FIXED POINT: ${d?.detail ?? 'ROADMAP.md changes on regen'}`)
+    }
+    for (const d of rt.diffs.filter(x => x.kind.startsWith('LOSSLESS_'))) {
+      console.log(describeLossyDiff(d))
     }
+    console.log('\nRun `compose roadmap generate` to regenerate ROADMAP.md from feature.json.')
+    process.exit(1)
+  }
 
-    if (clean) {
-      console.log('feature.json and ROADMAP.md are in sync.')
+  // compose roadmap xref-sync — pull-reconcile feature.json external links'
+  // expect= to live target state (COMP-ROADMAP-XREF-SYNC v1). Never writes external.
+  if (subcmd === 'xref-sync') {
+    const { syncExternalRefs } = await import('../lib/xref-sync.js')
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const dryRun = args.includes('--dry-run')
+    const res = await syncExternalRefs(cwd, { dryRun })
+    const verb = dryRun ? 'would update' : 'updated'
+    if (res.synced.length === 0) {
+      console.log(`No external-link drift to reconcile (${res.scanned} resolvable link(s) checked, ${res.unchanged} already in sync).`)
     } else {
-      console.log('\nRun `compose roadmap generate` to regenerate ROADMAP.md from feature.json.')
-      process.exit(1)
+      console.log(`${dryRun ? 'Would reconcile' : 'Reconciled'} ${res.synced.length} external link(s):`)
+      for (const s of res.synced) console.log(`  ${s.code}  ${s.provider} ${s.target}: expect ${s.from} → ${s.to} (${verb})`)
+    }
+    if (res.skipped.length > 0) {
+      console.log(`\nSkipped ${res.skipped.length} unresolved link(s):`)
+      for (const s of res.skipped) console.log(`  ${s.code}  ${s.provider} ${s.target}: ${s.reason}`)
     }
     process.exit(0)
   }