@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/lib/roadmap-gen.js

@@ -5,10 +5,9 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { listFeatures, positionSortKey } from './feature-json.js';
 import { parseStatusToken } from './roadmap-parser.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 import {
   readPhaseOverrides,
   readAnonymousRows,
@@ -207,7 +206,7 @@ export function generateRoadmapFromBase(baseText, features, opts = {}) {
  * @returns {string} - Generated ROADMAP.md content
  */
 export function generateRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
 
   // Narrative-owned workspace: ROADMAP.md is hand-authored. Return it verbatim
@@ -513,7 +512,7 @@ function buildKeyDocs(features, featuresDir) {
  * @param {object} [opts]
  */
 export function writeRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
 
   // Narrative-owned workspace: never overwrite hand-authored ROADMAP.md (#39).
   // No-op + warn; the existing file on disk is the source of truth.

package/lib/roadmap-graph/collect.js

@@ -12,7 +12,7 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { listFeatures } from '../feature-json.js';
-import { loadFeaturesDir, loadExternalPrefixes } from '../project-paths.js';
+import { resolveFeaturesPath, resolveRoadmapPath, loadExternalPrefixes } from '../project-paths.js';
 import { parseRoadmap } from '../roadmap-parser.js';
 import { SchemaValidator } from '../../server/schema-validator.js';
 import { depsToEdges } from './model.js';
@@ -28,7 +28,7 @@ const FM_KEYS = ['name', 'priority', 'track', 'desc'];
  * @param {string} [featuresDir] relative features dir (default from compose.json)
  * @returns {{ nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings: string[] }}
  */
-export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
+export function collectGraphInputs(cwd, featuresDir = resolveFeaturesPath(cwd)) {
   const warnings = [];
   const depsValidator = new SchemaValidator(DEPS_SCHEMA);
   const fmValidator = new SchemaValidator(FRONTMATTER_SCHEMA);
@@ -48,7 +48,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
     // An external-prefixed folder is a cross-project reference living here —
     // known (so edges resolve) but never rendered as one of THIS project's nodes.
     if (isExternal(f.code)) { externalCodes.add(f.code); continue; }
-    const folder = join(cwd, featuresDir, f.code);
+    const folder = join(featuresDir, f.code);
     const fm = readDisplayMetadata(folder, f, fmValidator, warnings);
     universe.set(f.code, {
       id: f.code,
@@ -62,7 +62,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   }
 
   // (b) ROADMAP.md rows — fallback for features not registered as folders.
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   if (existsSync(roadmapPath)) {
     let entries = [];
     try { entries = parseRoadmap(readFileSync(roadmapPath, 'utf-8')); } catch { /* ignore */ }
@@ -88,7 +88,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   for (const f of features) {
     if (!f || typeof f.code !== 'string') continue;
     if (isExternal(f.code)) continue;
-    const depsPath = join(cwd, featuresDir, f.code, 'deps.yaml');
+    const depsPath = join(featuresDir, f.code, 'deps.yaml');
     if (!existsSync(depsPath)) continue;
     let deps;
     try {

package/lib/roadmap-graph/index.js

@@ -10,7 +10,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
 import { join, isAbsolute, dirname } from 'node:path';
-import { loadFeaturesDir } from '../project-paths.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 import { collectGraphInputs } from './collect.js';
 import { buildGraph } from './model.js';
 import { renderGraphHtml } from './render.js';
@@ -22,7 +22,7 @@ import { loadGraphConfig } from './config.js';
  * @returns {{ html: string, nodes: object[], edges: object[], dropped: string[], warnings: string[], config: object }}
  */
 export function buildRoadmapGraph(cwd) {
-  const featuresDir = loadFeaturesDir(cwd);
+  const featuresDir = resolveFeaturesPath(cwd);
   const inputs = collectGraphInputs(cwd, featuresDir);
   const graph = buildGraph(inputs); // throws DanglingEdgeError
   const config = loadGraphConfig(cwd);

package/lib/roadmap-parser.js

@@ -192,7 +192,7 @@ export function parseRoadmap(text) {
  *   3-col: ID | Item | Status            → code=ID, desc=Item
  *   3-col: # | Item | Status             → anonymous (# is a row number, not a code)
  */
-function detectColumnLayout(headerCells) {
+export function detectColumnLayout(headerCells) {
   const lower = headerCells.map(c => c.toLowerCase());
 
   // 4+ columns: look for a Feature column as the code source

package/lib/state-migrations.js

@@ -27,7 +27,7 @@ import {
   renameSync, unlinkSync, readdirSync,
 } from 'fs';
 import { join } from 'path';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { writeFeature } from './feature-json.js';
 
 /**
@@ -283,8 +283,8 @@ export function runStateMigrations(cwd, opts = {}) {
 
   // --- feature.json walk -----------------------------------------------------
   if (featurePending.length > 0) {
-    const featuresDir = loadFeaturesDir(cwd); // honors paths.features override
-    const featuresRoot = join(cwd, featuresDir);
+    const featuresDir = resolveFeaturesPath(cwd); // absolute; honors paths.features override
+    const featuresRoot = featuresDir;
     // Own directory walk — do NOT use listFeatures(): it silently skips unreadable
     // files, which would hide exactly the cold-data corruption we must surface.
     let dirs = [];

package/lib/test-bootstrap.js

@@ -119,7 +119,10 @@ export function detectTestFramework(cwd) {
         framework: 'go-test',
         runner: 'go',
         configFile: 'go.mod',
-        command: 'go test ./...',
+        // -v emits per-test "--- PASS:/FAIL:" verdicts so parseTestSummary can
+        // count tests (COMP-TEST-BOOTSTRAP-4); plain `go test` prints only a
+        // package-level ok/FAIL with no counts.
+        command: 'go test -v ./...',
       };
     }
   }
@@ -298,7 +301,8 @@ export function scaffoldTestFramework(cwd, language) {
         framework: 'go-test',
         configFile: 'golden_test.go',
         testDir: '.',
-        command: 'go test ./...',
+        // -v so parseTestSummary can count per-test verdicts (COMP-TEST-BOOTSTRAP-4).
+        command: 'go test -v ./...',
       };
     }
 
@@ -399,3 +403,162 @@ export function scaffoldTestFramework(cwd, language) {
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// COMP-TEST-BOOTSTRAP-4-1: isTestFile
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether a repo-relative path looks like a test file. Used to scope the
+ * post-coverage test-review pass to the tests the coverage step produced.
+ * Conservative: matches conventional test locations/suffixes across the
+ * frameworks detectTestFramework knows, and avoids substring false positives
+ * (e.g. "contest", "greatest").
+ *
+ * @param {string} p - repo-relative file path
+ * @returns {boolean}
+ */
+export function isTestFile(p) {
+  if (typeof p !== 'string' || p.length === 0) return false;
+  return (
+    /(^|\/)(tests?|__tests__|spec)\//.test(p) ||  // test/ tests/ __tests__/ spec/ dirs
+    /\.(test|spec)\.[mc]?[jt]sx?$/.test(p) ||      // *.test.* / *.spec.* (js/ts/jsx/tsx/mjs/cjs)
+    /_test\.go$/.test(p) ||                         // go
+    /(^|\/)test_[^/]*\.py$/.test(p) ||              // pytest test_*.py
+    /_test\.py$/.test(p)                            // pytest *_test.py
+  );
+}
+
+// ---------------------------------------------------------------------------
+// COMP-TEST-BOOTSTRAP-4: parseTestSummary
+// ---------------------------------------------------------------------------
+
+const _UNPARSED = Object.freeze({ test_count: 0, pass_rate: 0, parsed: false });
+
+/** Strip ANSI color/escape codes so regexes match raw text. */
+function _stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/** First capture group as an int, or null if no match. */
+function _int(m) {
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * Build a result from pass/fail counts. The denominator is passed+failed only —
+ * skipped/pending/ignored tests are excluded from the rate (a fully-skipped run
+ * is not "100% passing"; a run with zero verdicts degrades to parsed:false).
+ */
+function _fromCounts(passed, failed) {
+  const total = passed + failed;
+  if (total <= 0) return _UNPARSED;
+  // Round to 2 decimals; an all-pass run yields exactly 100.
+  const pass_rate = Math.round((passed / total) * 10000) / 100;
+  return { test_count: total, pass_rate, parsed: true };
+}
+
+function _parseVitest(out) {
+  // "      Tests  2 failed | 10 passed (12)"  /  "      Tests  12 passed (12)"
+  // Match the "Tests" line specifically, not the "Test Files" line.
+  const line = out.match(/^[^\S\n]*Tests[^\S\n]+(.+)$/m);
+  if (!line) return _UNPARSED;
+  const passed = _int(line[1].match(/(\d+)\s+passed/));
+  const failed = _int(line[1].match(/(\d+)\s+failed/));
+  if (passed === null && failed === null) return _UNPARSED;
+  return _fromCounts(passed ?? 0, failed ?? 0);
+}
+
+function _parseJest(out) {
+  // "Tests:       2 failed, 10 passed, 12 total"
+  const line = out.match(/^[^\S\n]*Tests:[^\S\n]+(.+)$/m);
+  if (!line) return _UNPARSED;
+  const passed = _int(line[1].match(/(\d+)\s+passed/));
+  const failed = _int(line[1].match(/(\d+)\s+failed/));
+  if (passed === null && failed === null) return _UNPARSED;
+  return _fromCounts(passed ?? 0, failed ?? 0);
+}
+
+function _parseMocha(out) {
+  // "  10 passing (24ms)" + optional "  2 failing"; pending excluded.
+  const passed = _int(out.match(/(\d+)\s+passing/));
+  const failed = _int(out.match(/(\d+)\s+failing/));
+  if (passed === null && failed === null) return _UNPARSED;
+  return _fromCounts(passed ?? 0, failed ?? 0);
+}
+
+function _parsePytest(out) {
+  // "===== 2 failed, 9 passed, 1 error, 1 skipped in 0.50s =====" / "12 passed in 0.34s"
+  const passed = _int(out.match(/(\d+)\s+passed/));
+  const failed = _int(out.match(/(\d+)\s+failed/));
+  const errors = _int(out.match(/(\d+)\s+error/)); // "error"/"errors"
+  if (passed === null && failed === null && errors === null) return _UNPARSED;
+  return _fromCounts(passed ?? 0, (failed ?? 0) + (errors ?? 0));
+}
+
+function _parseGoTest(out) {
+  // Requires verbose output (`go test -v`): per-test "--- PASS:" / "--- FAIL:" lines.
+  // Without -v there are no per-test verdicts to count → degrade.
+  const passed = (out.match(/^[^\S\n]*--- PASS:/gm) || []).length;
+  const failed = (out.match(/^[^\S\n]*--- FAIL:/gm) || []).length;
+  if (passed + failed === 0) return _UNPARSED;
+  return _fromCounts(passed, failed);
+}
+
+function _parseCargo(out) {
+  // Sum every "test result: <ok|FAILED>. N passed; M failed; ..." line
+  // (a crate emits one per unit/integration/doc target).
+  const re = /test result:\s+\w+\.\s+(\d+)\s+passed;\s+(\d+)\s+failed/g;
+  let passed = 0, failed = 0, found = false, m;
+  while ((m = re.exec(out)) !== null) {
+    passed += parseInt(m[1], 10);
+    failed += parseInt(m[2], 10);
+    found = true;
+  }
+  if (!found) return _UNPARSED;
+  return _fromCounts(passed, failed);
+}
+
+/**
+ * Extract a structured test-result summary from raw test-runner stdout.
+ *
+ * Pure and total: any framework it can't read — or output it can't recognize —
+ * degrades to `{ test_count: 0, pass_rate: 0, parsed: false }` rather than
+ * guessing. Callers MUST treat `parsed:false` as "no signal" and never as a
+ * failing gate (see lib/build.js ship path).
+ *
+ * @param {string|null} framework - value from detectTestFramework().framework
+ *   (vitest | jest | mocha | pytest | go-test | cargo-test; others degrade)
+ * @param {string|null} stdout - combined stdout+stderr of the test run
+ * @returns {{ test_count: number, pass_rate: number, parsed: boolean }}
+ */
+export function parseTestSummary(framework, stdout) {
+  if (!framework || typeof stdout !== 'string' || stdout.length === 0) return _UNPARSED;
+  const out = _stripAnsi(stdout);
+  switch (framework) {
+    case 'vitest': return _parseVitest(out);
+    case 'jest': return _parseJest(out);
+    case 'mocha': return _parseMocha(out);
+    case 'pytest': return _parsePytest(out);
+    case 'go-test': return _parseGoTest(out);
+    case 'cargo-test': return _parseCargo(out);
+    default: return _UNPARSED; // ava, tap, unknown
+  }
+}
+
+/**
+ * The ship gate: derive a `tests_pass` boolean from a parsed summary.
+ *
+ * - parsed:  pass only when at least one test ran AND every test passed.
+ * - unparsed (or absent): degrade to `true` — an unreadable summary is "no
+ *   signal", never a failing gate. This is the safety valve that keeps the
+ *   gate from misfiring on frameworks/output the parser can't read.
+ *
+ * @param {{ test_count: number, pass_rate: number, parsed: boolean }|null} summary
+ * @returns {boolean}
+ */
+export function deriveTestsPass(summary) {
+  if (!summary || !summary.parsed) return true;
+  return summary.test_count >= 1 && summary.pass_rate === 100;
+}

package/lib/tracker/local-provider.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameS
 import { join, dirname } from 'path';
 
 import { readFeature, listFeatures as listFeaturesRaw, writeFeature } from '../feature-json.js';
-import { loadFeaturesDir } from '../project-paths.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 import { TrackerProvider, CAP } from './provider.js';
 
 import { setFeatureStatus, addRoadmapEntry as addRoadmapEntryRaw } from '../feature-writer.js';
@@ -38,7 +38,7 @@ export class LocalFileProvider extends TrackerProvider {
 
   async init(cwd) {
     this.cwd = cwd;
-    this.featuresDir = loadFeaturesDir(cwd);
+    this.featuresDir = resolveFeaturesPath(cwd);
     return this;
   }
 

package/lib/triage.js

@@ -11,6 +11,8 @@
 
 import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { resolveFeaturesPath } from './project-paths.js';
+import { resolvePathValue } from './paths-core.js';
 
 // ---------------------------------------------------------------------------
 // Tier definitions
@@ -185,8 +187,8 @@ function deriveProfile(signals) {
  */
 export async function runTriage(featureCode, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const featuresDir = opts.featuresDir ?? 'docs/features';
-  const featureDir = join(cwd, featuresDir, featureCode);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
+  const featureDir = join(resolvePathValue(cwd, featuresDir, 'features'), featureCode);
 
   // Collect content from key files
   const candidateFiles = ['plan.md', 'blueprint.md', 'design.md', 'prd.md', 'architecture.md'];
@@ -234,11 +236,11 @@ export async function runTriage(featureCode, opts = {}) {
  *
  * @param {string} cwd - Project root
  * @param {string} featureCode - Feature code
- * @param {string} [featuresDir] - Relative path to features dir (default: docs/features)
+ * @param {string} [featuresDir] - Path to features dir (absolute or relative; default: resolved features path)
  * @returns {boolean}
  */
-export function isTriageStale(cwd, featureCode, featuresDir = 'docs/features') {
-  const featureDir = join(cwd, featuresDir, featureCode);
+export function isTriageStale(cwd, featureCode, featuresDir = resolveFeaturesPath(cwd)) {
+  const featureDir = join(resolvePathValue(cwd, featuresDir, 'features'), featureCode);
   const featureJsonPath = join(featureDir, 'feature.json');
 
   if (!existsSync(featureJsonPath)) return true;

package/lib/vocabulary-inject.js

@@ -0,0 +1,103 @@
+/**
+ * STRAT-VOCAB-3 — Compose integration for vocabulary enforcement.
+ *
+ * Wires the already-shipped Stratum `vocabulary_compliance` ensure builtin
+ * (stratum-mcp/src/stratum_mcp/spec.py) into the compose lifecycle:
+ *   - VOCABULARY_TEMPLATE        : starter contracts/vocabulary.yaml (compose init)
+ *   - vocabularyEnabled()        : gate — capability not disabled AND a vocab file exists
+ *   - injectVocabularyEnsure()   : append the vocab ensure to the build flow's `review` step
+ *   - tagVocabularyViolations()  : mark vocab violation strings as must-fix for display
+ *
+ * Design: docs/features/STRAT-VOCAB-3/design.md
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Project-relative location of the vocabulary file (also the path baked into the ensure). */
+export const VOCABULARY_FILE = 'contracts/vocabulary.yaml';
+
+/**
+ * The ensure expression injected into the build flow's `review` step.
+ * Empty-list literal + git_fallback=True: never references a possibly-missing
+ * `result.*` attribute; scans the uncommitted working-tree diff vs HEAD (the
+ * implementation changes are merged but not yet committed at review time).
+ * Python-evaluated by the Stratum executor — hence `[]` and `True`.
+ */
+export const VOCABULARY_ENSURE = `vocabulary_compliance('${VOCABULARY_FILE}', [], True)`;
+
+/** Starter vocabulary file: all comments, so `_load_vocabulary` returns {} (inert) until edited. */
+export const VOCABULARY_TEMPLATE = `# contracts/vocabulary.yaml — project naming vocabulary (STRAT-VOCAB)
+#
+# Declare canonical names and the aliases that must NOT appear in code. During
+# \`compose build\`, the review step scans the files changed by the build for any
+# rejected alias (whole-word, case-sensitive) and fails until each is replaced
+# with its canonical name. An empty / comments-only file is a no-op.
+#
+# Format — a flat map of canonical_name -> { reject: [...], reason: "..." }:
+#
+#   auth_token:
+#     reject: [jwt, accessToken, JwtToken, authToken]
+#     reason: "use auth_token everywhere for the session credential"
+#
+#   user_id:
+#     reject: [uid, userId, UserId]
+#
+# Rules: canonical names and aliases must be identifiers; an alias may not also
+# be a canonical name or be repeated across entries; \`reason\` is optional.
+# Uncomment and edit the examples above (or add your own) to enable enforcement.
+`;
+
+/**
+ * Is vocabulary enforcement active for this project?
+ * Default-ON (honoring the roadmap's "by default") but gated on the file existing,
+ * so the generated spec is byte-identical for any project without a vocab file.
+ * Opt out with capabilities.vocabularyCompliance === false.
+ */
+export function vocabularyEnabled(cwd, composeConfig) {
+  if (composeConfig?.capabilities?.vocabularyCompliance === false) return false;
+  return existsSync(join(cwd, VOCABULARY_FILE));
+}
+
+/**
+ * Append the vocabulary ensure to the EXECUTED flow's `review` step (idempotent).
+ * Mutates and returns specObj. No-op when that flow has no `review` step.
+ *
+ * `flowName` must be the flow Stratum will actually run (build.js resolves it via
+ * extractFlowName). Targeting it precisely matters because a sub-flow
+ * (`review_check`) ALSO has a step id'd `review`; injecting there would be wrong.
+ * When `flowName` is omitted/unknown, fall back to the `build` flow (or the first),
+ * matching the shipped templates.
+ */
+export function injectVocabularyEnsure(specObj, flowName) {
+  const flows = specObj?.flows ?? {};
+  const keys = Object.keys(flows);
+  const flowKey = flowName && keys.includes(flowName)
+    ? flowName
+    : (keys.includes('build') ? 'build' : keys[0]);
+  const steps = flows[flowKey]?.steps ?? [];
+  const review = steps.find((s) => s?.id === 'review');
+  if (!review) return specObj;
+  if (!Array.isArray(review.ensure)) review.ensure = [];
+  if (!review.ensure.includes(VOCABULARY_ENSURE)) review.ensure.push(VOCABULARY_ENSURE);
+  return specObj;
+}
+
+/**
+ * Tag vocabulary failure strings as must-fix for the findings display.
+ * The cli-progress parser classifies a string by keyword (defaults to `nit`);
+ * vocab failures carry no marker, so prefix them with `must-fix:` — the parser
+ * then classifies must-fix AND still extracts the file:line, and strips the
+ * prefix for a clean description. Non-string / non-vocab items pass through
+ * unchanged. Returns a new array (does not mutate input or stored violations).
+ *
+ * Matches every string the builtin emits — both alias hits
+ * ("vocabulary violation: …") and a broken vocab file
+ * ("vocabulary.yaml malformed: …" / "vocabulary.yaml schema error: …") — all of
+ * which block the step and so deserve must-fix, not nit.
+ */
+export function tagVocabularyViolations(violations) {
+  if (!Array.isArray(violations)) return violations;
+  return violations.map((v) =>
+    typeof v === 'string' && /^vocabulary[ .]/i.test(v) ? `must-fix: ${v}` : v
+  );
+}

package/lib/xref-push.js

@@ -17,7 +17,7 @@
 
 import { readdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { resolveSiblingRoot } from './xref-local.js';
 
 const GITHUB_STATES = new Set(['open', 'closed']);
@@ -145,7 +145,7 @@ function localResolve(link, cwd) {
   const sib = resolveSiblingRoot(cwd, link.repo);
   if (sib.skipped) return sib;
   try {
-    const fjPath = join(sib.root, loadFeaturesDir(sib.root), link.to_code, 'feature.json');
+    const fjPath = join(resolveFeaturesPath(sib.root), 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, root: sib.root };
   } catch (e) { return { skipped: true, reason: `unreadable local target: ${e.message}` }; }
@@ -171,13 +171,13 @@ function localResolve(link, cwd) {
  * @returns {Promise<{pushed: Array, skipped: Array, unchanged: number, scanned: number}>}
  */
 export async function pushExternalRefs(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
   const clientOpts = { transport: opts.githubTransport ?? null, auth: opts.githubAuth };
   const ghResolve = opts.resolve ?? ((link) => defaultResolve(link, clientOpts));
   const ghWrite = opts.write ?? ((link, patch) => defaultWrite(link, patch, clientOpts));
   const setStatus = opts.setStatus ?? defaultSetStatus;
   const apply = opts.apply === true;
-  const dir = join(cwd, featuresDir);
+  const dir = featuresDir;
 
   const pushed = [];
   const skipped = [];

package/lib/xref-sync.js

@@ -16,7 +16,7 @@
 import { readdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { writeFeature } from './feature-json.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { resolveSiblingRoot } from './xref-local.js';
 
 const RESOLVABLE = new Set(['github', 'local']);
@@ -80,7 +80,7 @@ async function defaultResolve(link, cwd, featuresDir) {
     const citedRoot = sib.root;
     // 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');
+      const fjPath = join(resolveFeaturesPath(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}` }; }
@@ -100,9 +100,9 @@ async function defaultResolve(link, cwd, featuresDir) {
  * @returns {Promise<{synced: Array, skipped: Array, unchanged: number, scanned: number}>}
  */
 export async function syncExternalRefs(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
   const resolve = opts.resolve ?? defaultResolve;
-  const dir = join(cwd, featuresDir);
+  const dir = featuresDir;
 
   const synced = [];
   const skipped = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.49-beta",
+  "version": "0.2.51-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "dev": "node server/supervisor.js 2>&1 | tee /tmp/compose-server.log",
     "dev:server": "node server/supervisor.js",
     "dev:server:bare": "node server/index.js",
+    "dev:watch": "bash scripts/watch-server.sh",
     "dev:client": "vite",
     "build": "vite build",
     "preview": "vite preview",