@smartmemory/compose 0.2.17-beta → 0.2.18-beta

package/bin/compose.js

@@ -2328,14 +2328,16 @@ if (cmd === 'build') {
     const featuresRel = ibConfig.paths?.features || 'docs/features'
     const featuresDir = join(ibCwd, featuresRel, resolvedCode)
     if (!existsSync(featuresDir)) {
-      mkdirSync(featuresDir, { recursive: true })
-      writeFileSync(join(featuresDir, 'feature.json'), JSON.stringify({
+      // COMP-MCP-VALIDATE-1: route through the validated writer (schema-guarded)
+      // instead of a raw writeFileSync.
+      const { writeFeature } = await import('../lib/feature-json.js')
+      writeFeature(ibCwd, {
         code: resolvedCode,
         description: idea.title,
         status: 'PLANNED',
         promotedFrom: ideaId,
         createdAt: new Date().toISOString(),
-      }, null, 2))
+      }, featuresRel)
       console.log(`Created feature folder: ${featuresRel}/${resolvedCode}/`)
     }
 

package/lib/feature-json.js

@@ -9,6 +9,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, basename } from 'path';
 import { readdirSync } from 'fs';
+import { assertValidLinkShape, assertLinkTargetsExist } from './feature-write-guard.js';
 
 /**
  * @typedef {object} FeatureJson
@@ -48,8 +49,23 @@ export function readFeature(cwd, code, featuresDir = 'docs/features') {
  * @param {string} cwd - Project root
  * @param {FeatureJson} feature
  * @param {string} [featuresDir]
+ * @param {{validate?: boolean, allowForwardRefs?: boolean}} [opts] - Write-time
+ *   validation (COMP-MCP-VALIDATE-1). Validates by default; `validate: false`
+ *   skips all guarding (migration/back-fill tooling only); `allowForwardRefs`
+ *   permits a known-good forward-reference link target.
  */
-export function writeFeature(cwd, feature, featuresDir = 'docs/features') {
+export function writeFeature(cwd, feature, featuresDir = 'docs/features', opts = {}) {
+  if (opts.validate !== false) {
+    assertValidLinkShape(feature);
+    // Pass the on-disk version's links so existence is checked only for links
+    // this write INTRODUCES (delta-aware) — a forced forward-ref persisted
+    // earlier must not make later writes throw. Read prior only when there are
+    // same-project targets to check (keeps the common write zero-I/O).
+    const hasTargets = Array.isArray(feature.links)
+      && feature.links.some((l) => l && l.kind !== 'external' && typeof l.to_code === 'string');
+    const priorLinks = hasTargets ? (readFeature(cwd, feature.code, featuresDir)?.links) : undefined;
+    assertLinkTargetsExist(cwd, feature, { allowForwardRefs: opts.allowForwardRefs, priorLinks });
+  }
   const dir = join(cwd, featuresDir, feature.code);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'feature.json');

package/lib/feature-write-guard.js

@@ -0,0 +1,201 @@
+/**
+ * feature-write-guard.js — Write-time feature.json validation (COMP-MCP-VALIDATE-1).
+ *
+ * The feature.json schema (contracts/feature-json.schema.json) and the
+ * cross-reference existence rule were historically enforced ONLY on read, by
+ * lib/feature-validator.js. This module enforces the SAME rules at write time so
+ * malformed shape / invalid link kind / dangling to_code is rejected before
+ * commit — closing the source of FEATURE_JSON_SCHEMA_VIOLATION and
+ * DANGLING_LINK_FEATURES_TARGET.
+ *
+ * Layering: imports only the Ajv SchemaValidator (server/) and the feature-code
+ * regex. It does NOT import feature-json.js, feature-validator.js, or
+ * feature-writer.js — those import this module, so this stays a leaf to keep the
+ * graph acyclic.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { SchemaValidator } from '../server/schema-validator.js';
+import { FEATURE_CODE_RE_STRICT } from './feature-code.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = resolve(__dirname, '../contracts/feature-json.schema.json');
+
+// Memoize the compiled validator (the schema is static). This is the only thing
+// safe to cache — code-existence sources change at runtime and are read fresh.
+let _validator = null;
+function validator() {
+  if (!_validator) _validator = new SchemaValidator(SCHEMA_PATH);
+  return _validator;
+}
+
+/**
+ * Thrown when a feature.json write would persist invalid data.
+ * `kind` mirrors the read validator's finding kinds so callers can branch.
+ */
+export class FeatureWriteValidationError extends Error {
+  /**
+   * @param {'FEATURE_JSON_SCHEMA_VIOLATION'|'DANGLING_LINK_FEATURES_TARGET'} kind
+   * @param {string[]} violations
+   */
+  constructor(kind, violations) {
+    super(`${kind}: ${violations.join('; ')}`);
+    this.name = 'FeatureWriteValidationError';
+    this.kind = kind;
+    this.violations = violations;
+  }
+}
+
+/**
+ * Validate a feature's `links[]` against the canonical JSON schema. Throws
+ * FeatureWriteValidationError('FEATURE_JSON_SCHEMA_VIOLATION') for any link-shape
+ * violation (bad `kind` enum, missing `to_code` on a non-external link, malformed
+ * external-link provider fields, …).
+ *
+ * SCOPE (COMP-MCP-VALIDATE-1): only `/links/*` violations are enforced at write
+ * time. Whole-object schema tightening — `complexity` enum convergence, the
+ * `artifacts[].type` enum, `additionalProperties` — is **deliberately deferred**
+ * to COMP-MCP-VALIDATE-SCHEMA-TIGHTEN (see contracts/feature-json.schema.json
+ * field comments), and the writers legitimately produce values that pass only
+ * the permissive read schema today. -1 closes the link-kind / link-shape source
+ * named in its charter, nothing wider.
+ *
+ * @param {object} feature
+ */
+export function assertValidLinkShape(feature) {
+  const { valid, errors } = validator().validateRoot(feature);
+  if (valid) return;
+  const linkErrors = (errors || []).filter((e) => (e.instancePath || '').startsWith('/links'));
+  if (linkErrors.length === 0) return;
+  throw new FeatureWriteValidationError(
+    'FEATURE_JSON_SCHEMA_VIOLATION',
+    linkErrors.map((e) => `${e.instancePath}: ${e.message}`),
+  );
+}
+
+function resolvePaths(cwd) {
+  let featuresRel = 'docs/features';
+  try {
+    const cfg = JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
+    if (cfg?.paths?.features) featuresRel = cfg.paths.features;
+  } catch { /* no config — use defaults (mirrors resolveProjectPaths) */ }
+  return {
+    features: join(cwd, featuresRel),
+    roadmap: join(cwd, 'ROADMAP.md'),
+    visionState: join(cwd, '.compose', 'data', 'vision-state.json'),
+  };
+}
+
+/**
+ * Strict feature codes present in a ROADMAP.md table. Self-contained, lean
+ * mirror of the validator's column-aware scan (lib/feature-validator.js:144-202)
+ * — NOT extracted from it, because that loop is dual-purpose (it also builds
+ * citationRows for XREF parsing). We need only the code set.
+ *
+ * @param {string} roadmapPath
+ * @returns {string[]}
+ */
+export function scanRoadmapRows(roadmapPath) {
+  const codes = [];
+  let text;
+  try { text = readFileSync(roadmapPath, 'utf8'); } catch { return codes; }
+
+  let codeIdx = -1, statusIdx = -1;
+  let inTable = false, sawSeparator = false;
+  for (const rawLine of text.split('\n')) {
+    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 featureColIdx = lower.findIndex((c) => ['feature', 'code', 'item', 'name'].includes(c));
+    const statusColIdx = lower.findIndex((c) => ['status', 'state'].includes(c));
+    if (featureColIdx >= 0 && statusColIdx >= 0) {
+      codeIdx = featureColIdx; statusIdx = statusColIdx; inTable = true; sawSeparator = false; continue;
+    }
+    if (cols.every((c) => /^[-:]+$/.test(c))) { if (inTable) sawSeparator = true; continue; }
+    if (!inTable || !sawSeparator || codeIdx < 0 || codeIdx >= cols.length) continue;
+    const codeRaw = cols[codeIdx].replace(/\*/g, '').replace(/`/g, '').trim();
+    if (FEATURE_CODE_RE_STRICT.test(codeRaw)) codes.push(codeRaw);
+  }
+  return codes;
+}
+
+/**
+ * The set of feature codes that "exist" in any authoritative source — feature
+ * folders, ROADMAP rows, or vision-state items. Mirrors the union the read
+ * validator's dangling-link check consults (foldersByCode ∪ roadmapByCode ∪
+ * visionByCode). Read fresh every call (no memo): ROADMAP and vision-state
+ * change independently of feature writes in long-lived processes.
+ *
+ * @param {string} cwd
+ * @returns {Set<string>}
+ */
+export function knownFeatureCodes(cwd) {
+  const paths = resolvePaths(cwd);
+  const codes = new Set();
+
+  // Feature folders
+  if (existsSync(paths.features)) {
+    for (const dirent of readdirSync(paths.features, { withFileTypes: true })) {
+      if (dirent.isDirectory() && FEATURE_CODE_RE_STRICT.test(dirent.name)) codes.add(dirent.name);
+    }
+  }
+
+  // ROADMAP rows
+  for (const code of scanRoadmapRows(paths.roadmap)) codes.add(code);
+
+  // Vision-state items
+  try {
+    const vs = JSON.parse(readFileSync(paths.visionState, 'utf8'));
+    for (const item of (Array.isArray(vs.items) ? vs.items : [])) {
+      const code = item?.lifecycle?.featureCode || item?.featureCode;
+      if (code && FEATURE_CODE_RE_STRICT.test(code)) codes.add(code);
+    }
+  } catch { /* missing vision-state — folders/roadmap still apply */ }
+
+  return codes;
+}
+
+/**
+ * Assert every same-project link target (non-external to_code) that this write
+ * INTRODUCES exists. No-op (zero I/O) when the feature carries no such links —
+ * the common write.
+ *
+ * Delta-aware: only links not already present in `opts.priorLinks` (the on-disk
+ * version) are checked. This is the correct write-time semantic — reject new
+ * drift, not pre-existing state — and it makes a legitimately forced
+ * forward-reference durable: once persisted, later unrelated writes (status,
+ * completions, build lifecycle) re-run this guard but skip the now-existing
+ * link, so they don't spuriously throw `DANGLING_LINK_FEATURES_TARGET`.
+ *
+ * Throws FeatureWriteValidationError('DANGLING_LINK_FEATURES_TARGET') for any
+ * newly-introduced missing target unless opts.allowForwardRefs is set (the
+ * explicit force path that introduces the forward-reference in the first place).
+ *
+ * @param {string} cwd
+ * @param {object} feature
+ * @param {{allowForwardRefs?: boolean, priorLinks?: Array}} [opts]
+ */
+export function assertLinkTargetsExist(cwd, feature, opts = {}) {
+  if (opts.allowForwardRefs) return;
+  const links = Array.isArray(feature?.links) ? feature.links : [];
+  const prior = Array.isArray(opts.priorLinks) ? opts.priorLinks : [];
+  const isPrior = (l) => prior.some((p) => p.kind === l.kind && p.to_code === l.to_code);
+  const targets = links
+    .filter((l) => l && l.kind !== 'external' && typeof l.to_code === 'string')
+    .filter((l) => !isPrior(l)) // only newly-introduced links
+    .map((l) => l.to_code);
+  if (targets.length === 0) return; // cheap path — no scan
+
+  const known = knownFeatureCodes(cwd);
+  const missing = targets.filter((code) => code !== feature.code && !known.has(code));
+  if (missing.length > 0) {
+    throw new FeatureWriteValidationError(
+      'DANGLING_LINK_FEATURES_TARGET',
+      missing.map((code) => `${code} does not exist in any source`),
+    );
+  }
+}

package/lib/feature-writer.js

@@ -24,6 +24,7 @@ import { checkOrInsert } from './idempotency.js';
 import { loadFeaturesDir } from './project-paths.js';
 import { checkRoundtrip } from './roadmap-roundtrip.js';
 import { isNarrativeOwned, narrativeOwnedMessage } from './roadmap-config.js';
+import { knownFeatureCodes, FeatureWriteValidationError } from './feature-write-guard.js';
 
 // providerFor is imported lazily (inside each function) to break the
 // module-load-time cycle: factory.js → local-provider.js → feature-writer.js.
@@ -580,17 +581,34 @@ export async function linkFeatures(cwd, args) {
       l => l.kind === args.kind && l.to_code === args.to_code
     );
 
+    // Re-issuing an existing link without force is a no-op — it introduces no
+    // new state, so it short-circuits BEFORE the dangling guard (otherwise an
+    // idempotent retry of a previously-forced forward-ref would wrongly throw).
     if (matchIdx !== -1 && !args.force) {
       return { from_code: args.from_code, to_code: args.to_code, kind: args.kind, noop: true };
     }
 
+    // COMP-MCP-VALIDATE-1: reject a dangling target for genuinely new/updated
+    // links. Checked after the source-existence guard (a missing source is the
+    // more fundamental error). `force` overrides for intentional forward-refs
+    // (link A→B before B is scaffolded).
+    const targetMissing = !knownFeatureCodes(cwd).has(args.to_code);
+    if (targetMissing && !args.force) {
+      throw new FeatureWriteValidationError(
+        'DANGLING_LINK_FEATURES_TARGET',
+        [`${args.to_code} does not exist in any source (pass force to override)`],
+      );
+    }
+
     const entry = { kind: args.kind, to_code: args.to_code };
     if (args.note) entry.note = args.note;
 
     if (matchIdx !== -1) links[matchIdx] = entry;
     else links.push(entry);
 
-    await provider.putFeature(args.from_code, { ...feature, links });
+    // allowForwardRefs only matters when the target is missing (force path);
+    // when it exists the chokepoint existence re-check passes anyway.
+    await provider.putFeature(args.from_code, { ...feature, links }, { allowForwardRefs: targetMissing });
 
     await safeAppendEvent(cwd, {
       tool: 'link_features',
@@ -599,6 +617,7 @@ export async function linkFeatures(cwd, args) {
       kind: args.kind,
       note: args.note,
       forced: matchIdx !== -1 ? true : undefined,
+      forced_dangling: (args.force && targetMissing) ? true : undefined,
       idempotency_key: args.idempotency_key,
     });
 

package/lib/tracker/github-provider.js

@@ -5,6 +5,7 @@ import { GitHubApi } from './github-api.js';
 import { OpLog, Cache, ConflictLedger, Reconciler } from './sync-engine.js';
 import { generateRoadmapFromBase } from '../roadmap-gen.js';
 import { spliceChangelog } from '../changelog-writer.js';
+import { assertValidLinkShape } from '../feature-write-guard.js';
 
 const META_RE = /<!--compose-feature\n([\s\S]*?)\n-->/;
 function encodeBody(obj) {
@@ -107,7 +108,8 @@ export class GitHubProvider extends TrackerProvider {
       );
   }
 
-  async createFeature(code, obj) {
+  async createFeature(code, obj, opts = {}) {
+    if (opts.validate !== false) assertValidLinkShape(obj);
     return this._lock(code, async () => {
       // Idempotent: if already in cache, return it.
       const existing = await this.cache.get(code);
@@ -120,7 +122,11 @@ export class GitHubProvider extends TrackerProvider {
     });
   }
 
-  async putFeature(code, obj) {
+  async putFeature(code, obj, opts = {}) {
+    // COMP-MCP-VALIDATE-1: enforce link-shape on the GitHub backend too (same
+    // rule as the local chokepoint). Existence is local-folder semantics and is
+    // not applied here. `validate:false` opts out (migration/fixture planting).
+    if (opts.validate !== false) assertValidLinkShape(obj);
     return this._lock(code, async () => {
       const cur = await this.cache.get(code);
       if (cur && obj.status && obj.status !== cur.status) {
@@ -140,7 +146,8 @@ export class GitHubProvider extends TrackerProvider {
   }
 
   // Raw write that allows status change (used by setStatus / policy layers).
-  async persistFeatureRaw(code, obj) {
+  async persistFeatureRaw(code, obj, opts = {}) {
+    if (opts.validate !== false) assertValidLinkShape(obj);
     return this._lock(code, async () => {
       await this.cache.put(code, obj, { pending: true });
       await this.cache.markPending(code);

package/lib/tracker/local-provider.js

@@ -62,12 +62,12 @@ export class LocalFileProvider extends TrackerProvider {
     return readFeature(this.cwd, code, this.featuresDir);
   }
 
-  async putFeature(code, obj) {
+  async putFeature(code, obj, opts = {}) {
     const cur = readFeature(this.cwd, code, this.featuresDir);
     if (cur && Object.prototype.hasOwnProperty.call(obj, 'status') && obj.status !== cur.status) {
       throw new Error(`putFeature: status delta (${cur.status}->${obj.status}) not allowed; use setStatus`);
     }
-    writeFeature(this.cwd, { ...obj, code }, this.featuresDir);
+    writeFeature(this.cwd, { ...obj, code }, this.featuresDir, opts);
     return readFeature(this.cwd, code, this.featuresDir);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.17-beta",
+  "version": "0.2.18-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/feature-scan.js

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { getTargetRoot, resolveProjectPath } from './project-root.js';
+import { assertValidLinkShape } from '../lib/feature-write-guard.js';
 
 // ---------------------------------------------------------------------------
 // Metadata extraction
@@ -395,6 +396,18 @@ export function writeFeatureGroupToDisk(item, newGroup, featuresDir) {
     spec.updated = new Date().toISOString().slice(0, 10);
   }
 
+  // COMP-MCP-VALIDATE-1: never persist a malformed link shape via the vision
+  // route. Existence (DANGLING) is intentionally NOT checked here: this path
+  // only mutates `group`, so it cannot introduce a new dangling link, and
+  // re-validating existence would wrongly block a group rename on a feature that
+  // already carries a (possibly legitimately forced) forward-ref.
+  try {
+    assertValidLinkShape(spec);
+  } catch (err) {
+    console.warn(`[feature-scan] writeFeatureGroupToDisk: invalid feature.json at ${specPath}, not writing: ${err.message}`);
+    return false;
+  }
+
   try {
     const tmp = path.join(featureDir, `feature.json.tmp.${Date.now()}.${process.pid}`);
     fs.writeFileSync(tmp, JSON.stringify(spec, null, 2) + '\n', 'utf-8');

package/server/ideabox-routes.js

@@ -23,6 +23,7 @@ import {
   updateIdea,
   addDiscussion,
 } from '../lib/ideabox.js'
+import { writeFeature } from '../lib/feature-json.js'
 import { IdeaboxCache } from './ideabox-cache.js'
 
 /**
@@ -182,14 +183,15 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
       }
       const featuresDir = path.join(projectRoot, featuresRel, resolvedCode)
       if (!fs.existsSync(featuresDir)) {
-        fs.mkdirSync(featuresDir, { recursive: true })
-        fs.writeFileSync(path.join(featuresDir, 'feature.json'), JSON.stringify({
+        // COMP-MCP-VALIDATE-1: route through the validated writer instead of a
+        // raw fs.writeFileSync so the promoted feature.json is schema-guarded.
+        writeFeature(projectRoot, {
           code: resolvedCode,
           description: sourceIdea.title,
           status: 'PLANNED',
           promotedFrom: sourceIdea.id,
           createdAt: new Date().toISOString(),
-        }, null, 2))
+        }, featuresRel)
       }
 
       promoteIdea(parsed, id, resolvedCode)