@smartmemory/compose 0.3.7 → 0.4.0

package/lib/tool-inventory.js

@@ -0,0 +1,122 @@
+/**
+ * tool-inventory.js — COMP-COVERAGE-GATE slice 1.
+ *
+ * The single derived answer to "which MCP tools change state, and what canon do
+ * they write". Pure, no I/O (shape template: server/mcp-tool-policy.js).
+ *
+ * WHY THIS EXISTS. Compose kept three hand-maintained lists that each partially
+ * described the mutating surface — canon-registry's TOOLS_FOR_* /
+ * JUDGMENT_WRITE_TOOLS, and mcp-tool-policy's IMPLEMENTER_DENY / REVIEWER_ALLOW
+ * — and NONE of them was the inventory. Nothing enumerated every mutating tool,
+ * and nothing cross-checked the three against the tool definitions themselves.
+ * A tool added to server/compose-mcp.js was enforced only where an author
+ * remembered to name it. Same shape as COMP-COMPLETION-GATE, where guard
+ * coverage turned out to be 0/321 — discovered by audit, not by a check.
+ *
+ * The fix is to put the declaration ON the tool definition (`effect`, `writes`)
+ * and DERIVE the sets from it. A side list is a fourth thing to forget; a
+ * required field on the definition cannot be added without the author seeing it.
+ *
+ * FAIL-CLOSED HERE, FAIL-OPEN AT RUNTIME. A tool with no `effect` is reported as
+ * `undeclared` and fails validate_project. That is safe because this module runs
+ * at validate time and never in a request path — unlike canon-guard.js, which
+ * fails open so a malformed input can never wedge a session.
+ */
+
+/** Valid `effect` values on a tool definition. */
+export const EFFECTS = /** @type {const} */ (['read', 'mutating', 'setup']);
+
+/**
+ * Canon path ids a `writes` entry may name — the `id` field of each
+ * lib/canon-registry.js REGISTRY entry. Kept as a literal rather than imported
+ * so this module stays dependency-free and pure; `checkAuthorizationCoverage`
+ * (slice 2) validates `writes` against the live registry, which is where a
+ * drifted id must be caught. This set is only for the shape check below.
+ */
+export const CANON_IDS = new Set([
+  'roadmap', 'changelog', 'feature-json', 'judgment',
+  'override-ledger', 'override-attest', 'override-grants',
+]);
+
+/**
+ * Partition tool definitions by declared effect.
+ *
+ * @param {Array<{name?: string, effect?: string, writes?: string[]}>} toolDefs
+ * @returns {{
+ *   read: string[], mutating: string[], setup: string[],
+ *   undeclared: Array<{ name: string, reason: string }>,
+ *   writesByTool: Record<string, string[]>,
+ * }}
+ */
+export function loadToolInventory(toolDefs) {
+  const read = [];
+  const mutating = [];
+  const setup = [];
+  const undeclared = [];
+  /** @type {Record<string, string[]>} */
+  const writesByTool = {};
+
+  if (!Array.isArray(toolDefs)) return { read, mutating, setup, undeclared, writesByTool };
+
+  for (const def of toolDefs) {
+    const name = def && typeof def.name === 'string' ? def.name : null;
+    if (!name) {
+      undeclared.push({ name: '<unnamed>', reason: 'tool definition has no name' });
+      continue;
+    }
+
+    const effect = def.effect;
+    if (!EFFECTS.includes(effect)) {
+      undeclared.push({
+        name,
+        reason: effect === undefined
+          ? 'no `effect` field'
+          : `unknown effect '${effect}' (expected ${EFFECTS.join('|')})`,
+      });
+      continue;
+    }
+
+    if (effect === 'read') { read.push(name); continue; }
+    if (effect === 'setup') { setup.push(name); continue; }
+
+    // effect === 'mutating' — `writes` is required, `[]` being a real answer
+    // ("mutates state, but no CANON path"). Distinguishing "declared empty"
+    // from "forgot to declare" is the entire point of requiring the field.
+    if (!Array.isArray(def.writes)) {
+      undeclared.push({ name, reason: 'mutating tool has no `writes` array (use [] for non-canon writes)' });
+      continue;
+    }
+    const bad = def.writes.filter((w) => !CANON_IDS.has(w));
+    if (bad.length > 0) {
+      undeclared.push({ name, reason: `\`writes\` names unknown canon id(s): ${bad.join(', ')}` });
+      continue;
+    }
+    mutating.push(name);
+    writesByTool[name] = [...def.writes];
+  }
+
+  return { read, mutating, setup, undeclared, writesByTool };
+}
+
+/**
+ * The derived mutating set. Deliberately a function of the definitions rather
+ * than a literal — a literal is exactly the drift this feature exists to stop.
+ *
+ * @param {Array<{name?: string, effect?: string, writes?: string[]}>} toolDefs
+ * @returns {Set<string>}
+ */
+export function mutatingTools(toolDefs) {
+  return new Set(loadToolInventory(toolDefs).mutating);
+}
+
+/**
+ * Tools that write a given canon path id, derived from `writes`.
+ *
+ * @param {Array<{name?: string, effect?: string, writes?: string[]}>} toolDefs
+ * @param {string} canonId
+ * @returns {string[]}
+ */
+export function toolsWritingCanon(toolDefs, canonId) {
+  const { writesByTool } = loadToolInventory(toolDefs);
+  return Object.keys(writesByTool).filter((t) => writesByTool[t].includes(canonId)).sort();
+}

package/lib/version-check.js

@@ -6,7 +6,7 @@
  * on any failure (network, parse, etc.) so it never breaks `compose doctor`.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync } from 'fs'
 import { join, dirname } from 'path'
 import { homedir } from 'os'
 
@@ -14,38 +14,48 @@ const PACKAGE_NAME = '@smartmemory/compose'
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000  // 24h
 const FETCH_TIMEOUT_MS = 3000
 
-function cachePath() {
-  return join(homedir(), '.compose', 'version-cache.json')
+export function cachePath() {
+  return process.env.COMPOSE_VERSION_CACHE || join(homedir(), '.compose', 'version-cache.json')
 }
 
-function readCache() {
+function readCacheDoc(file) {
   try {
-    const raw = readFileSync(cachePath(), 'utf-8')
-    const parsed = JSON.parse(raw)
-    if (typeof parsed?.fetchedAt !== 'number' || typeof parsed?.latest !== 'string') return null
-    if (Date.now() - parsed.fetchedAt > CACHE_TTL_MS) return null
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    // Legacy cache is exactly { fetchedAt: <number>, latest: <string> }.
+    // A package named `latest` is valid and would otherwise be mistaken for that shape.
+    if (typeof parsed.fetchedAt === 'number' && typeof parsed.latest === 'string') return {}
     return parsed
   } catch {
-    return null
+    return {}
   }
 }
 
-function writeCache(latest) {
+function readCache(pkg, file) {
+  const entry = readCacheDoc(file)[pkg]
+  if (typeof entry?.fetchedAt !== 'number' || typeof entry?.latest !== 'string') return null
+  if (Date.now() - entry.fetchedAt > CACHE_TTL_MS) return null
+  return entry
+}
+
+function writeCache(pkg, latest, file) {
   try {
-    const path = cachePath()
-    mkdirSync(dirname(path), { recursive: true })
-    writeFileSync(path, JSON.stringify({ fetchedAt: Date.now(), latest }, null, 2))
+    mkdirSync(dirname(file), { recursive: true })
+    const doc = readCacheDoc(file)
+    doc[pkg] = { fetchedAt: Date.now(), latest }
+    writeFileSync(file, JSON.stringify(doc, null, 2))
   } catch {
     // best-effort cache; ignore failures
   }
 }
 
-async function fetchLatest() {
+async function fetchLatest(pkg) {
+  if (process.env.COMPOSE_VERSION_CHECK_OFFLINE === '1') return null
   if (typeof fetch !== 'function') return null
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
   try {
-    const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
+    const url = `https://registry.npmjs.org/${pkg}/latest`
     const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } })
     if (!res.ok) return null
     const data = await res.json()
@@ -89,11 +99,12 @@ export function compareVersions(a, b) {
  *   behind: true if current < latest, false otherwise.
  *   source: 'cache' | 'network'
  */
-export async function checkLatestVersion(currentVersion, { force = false } = {}) {
+export async function checkPackageVersion(pkg, currentVersion, opts) {
+  const { force = false, fetchImpl = fetchLatest, cacheFile = cachePath(), cacheOnly = false } = opts ?? {}
   if (!currentVersion) return null
 
   if (!force) {
-    const cached = readCache()
+    const cached = readCache(pkg, cacheFile)
     if (cached) {
       const cmp = compareVersions(currentVersion, cached.latest)
       if (cmp === null) return null
@@ -101,10 +112,71 @@ export async function checkLatestVersion(currentVersion, { force = false } = {})
     }
   }
 
-  const latest = await fetchLatest()
+  // cacheOnly callers accept a miss rather than pay for the network. Used by the
+  // CLI nudge for non-interactive callers, where a courtesy line is not worth a
+  // request — and where concurrent spawns once left the fetch unsettled.
+  if (cacheOnly) return null
+
+  let latest = null
+  try {
+    latest = await fetchImpl(pkg)
+  } catch {
+    return null
+  }
   if (!latest) return null
-  writeCache(latest)
+  writeCache(pkg, latest, cacheFile)
   const cmp = compareVersions(currentVersion, latest)
   if (cmp === null) return null
   return { current: currentVersion, latest, behind: cmp < 0, source: 'network' }
 }
+
+/** Compose's own check. Shape and behavior unchanged — `compose doctor` and its
+ * --json consumers depend on this exact object. */
+export async function checkLatestVersion(currentVersion, opts = {}) {
+  return checkPackageVersion(PACKAGE_NAME, currentVersion, opts ?? {})
+}
+
+/** The version stratum ACTUALLY resolved to, read from node_modules.
+ *
+ * Deliberately not the range declared in compose's package.json. Compose 0.3.7
+ * moved that declaration from an exact pin to `^0.3.3`, and npm does not
+ * re-resolve a caret unless something triggers an install — so the declared
+ * range and the installed version drift apart, and the installed one is the
+ * only one that tells the user anything true.
+ *
+ * Absent stratum is a normal state (not installed, capabilities.stratum off),
+ * not an error. */
+export function resolveStratumVersion(packageRoot) {
+  try {
+    const manifest = join(packageRoot, 'node_modules', '@smartmemory', 'stratum', 'package.json')
+    const version = JSON.parse(readFileSync(manifest, 'utf-8')).version
+    return typeof version === 'string' ? version : null
+  } catch {
+    return null
+  }
+}
+
+/** Zero or one lines. Pure: no network, no filesystem, no clock — so every
+ * branch is decidable in a unit test.
+ *
+ * Silence is the default. A nudge that prints on every run gets filtered out by
+ * the reader, at which point it has negative value. */
+export function formatDriftNudge(arg = {}) {
+  if (!arg || typeof arg !== 'object') return []
+  const { compose = null, stratum = null } = arg
+  const composeRecord = compose && typeof compose === 'object' ? compose : null
+  const stratumRecord = stratum && typeof stratum === 'object' ? stratum : null
+  const valid = (record) =>
+    record &&
+    record.behind === true &&
+    typeof record.current === 'string' &&
+    record.current !== '' &&
+    typeof record.latest === 'string' &&
+    record.latest !== ''
+
+  const parts = []
+  if (valid(composeRecord)) parts.push(`compose ${compose.current} → ${compose.latest}`)
+  if (valid(stratumRecord)) parts.push(`stratum ${stratum.current} → ${stratum.latest}`)
+  if (parts.length === 0) return []
+  return [`⚠ update available: ${parts.join(', ')} — run: compose update`]
+}

package/lib/vision-writer.js

@@ -401,12 +401,99 @@ export class VisionWriter {
   }
 
   async updateItemStatus(itemId, status) {
-    if (await this._serverAvailable()) {
+    const up = await this._serverAvailable();
+    // COMP-COMPLETION-GATE slice 3 (AC-16, path 14): `complete` is not a status
+    // this general writer sets on a managed build-mode feature item, in EITHER
+    // transport. The legitimate write is `completeItem` — the self-verifying
+    // seam of §2.3b, which re-reads canonical state before writing. Fix/plan
+    // items, UI items with no lifecycle, and the `compose new` kickoff item
+    // (build mode, no feature.json) are not feature completions and keep this
+    // path (§2.3d). In REST mode the server's PATCH refuses too (AC-10); the
+    // pre-check here makes the refusal the writer's own, with the writer's message.
+    if (status === 'complete') {
+      const item = up ? await this._restGetItem(itemId) : this._load().items.find(i => i.id === itemId);
+      const { isManagedBuildItem } = await import('../server/completion-projection.js');
+      if (item && isManagedBuildItem(item, this._workspaceRoot())) {
+        const e = new Error(
+          `VisionWriter.updateItemStatus: refusing to mark ${itemId} (${item.lifecycle.featureCode}) ` +
+          `complete — a managed build-mode feature completes through the completion gate, which ` +
+          `projects it via completeItem() after verifying the commit, tests and guard ledger.`,
+        );
+        e.code = 'COMPLETE_VIA_GATE_ONLY';
+        throw e;
+      }
+    }
+    if (up) {
       return this._restUpdateItemStatus(itemId, status);
     }
     return this._directUpdateItemStatus(itemId, status);
   }
 
+  /**
+   * COMP-COMPLETION-GATE slice 3 (§2.3b, AC-4b): the ONLY path that writes
+   * `status: 'complete'` on a managed build-mode feature item. It carries no
+   * authority: in REST mode the server re-reads feature.json + the guard ledger
+   * before writing (`POST …/completion-projection`); in direct mode the same
+   * predicate runs here. Either way a completion that canonical state does not
+   * already record is refused.
+   *
+   * @param {string} itemId
+   * @param {object} evidence
+   * @param {string} evidence.featureCode
+   * @param {string} [evidence.cwd]        workspace root; derived from dataDir when omitted
+   * @param {string} [evidence.commitSha]
+   * @param {string} [evidence.ledgerRef]
+   * @returns {Promise<{ok:true, itemId:string, verified_by:string}>}
+   */
+  async completeItem(itemId, evidence = {}) {
+    if (!evidence.featureCode) throw new Error('VisionWriter.completeItem: evidence.featureCode is required');
+    if (await this._serverAvailable()) {
+      const r = await this._fetch(`/api/vision/items/${itemId}/completion-projection`, {
+        method: 'POST',
+        body: JSON.stringify({
+          featureCode: evidence.featureCode,
+          commitSha: evidence.commitSha ?? null,
+          ledgerRef: evidence.ledgerRef ?? null,
+        }),
+      });
+      return { ok: true, itemId, verified_by: r.verified_by, transport: 'rest' };
+    }
+    return this._directCompleteItem(itemId, { ...evidence, cwd: evidence.cwd || this._workspaceRoot() });
+  }
+
+  /** The workspace root this writer's dataDir belongs to (`<root>/.compose/data`). */
+  _workspaceRoot() {
+    return path.resolve(this._dataDir, '..', '..');
+  }
+
+  async _restGetItem(itemId) {
+    try {
+      return await this._fetch(`/api/vision/items/${itemId}`);
+    } catch {
+      return null;
+    }
+  }
+
+  async _directCompleteItem(itemId, evidence) {
+    const state = this._load();
+    const item = state.items.find(i => i.id === itemId);
+    if (!item) throw new Error(`VisionWriter.completeItem: item not found: ${itemId}`);
+    const { verifiedCompleteProjection, projectionStamp } = await import('../server/completion-projection.js');
+    const v = await verifiedCompleteProjection({
+      item, featureCode: evidence.featureCode, cwd: evidence.cwd, consultGuard: true,
+    });
+    if (!v.ok) {
+      const e = new Error(`VisionWriter.completeItem: projection refused — ${v.reasons.join('; ')}`);
+      e.code = 'PROJECTION_REFUSED';
+      e.reasons = v.reasons;
+      throw e;
+    }
+    item.status = 'complete';
+    item.completion_projection = projectionStamp(v, { ...evidence, source: 'direct' });
+    this._atomicWrite(state);
+    return { ok: true, itemId, verified_by: v.verified_by, transport: 'direct' };
+  }
+
   async updateItemPhase(itemId, stepId) {
     if (await this._serverAvailable()) {
       return this._restUpdateItemPhase(itemId, stepId);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.3.7",
-  "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
+  "version": "0.4.0",
+  "description": "Structured AI dev pipeline: your agent writes the code, Compose makes it prove it. Gated design decisions, enforced postconditions, and independent review from goal to shipped code.",
   "author": "SmartMemory",
   "license": "MIT",
   "type": "module",
@@ -20,11 +20,11 @@
     "dev:client": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --import ./test/suppress-expected-drift.js --test --test-timeout=120000 test/*.test.js test/comp-obs-branch/*.test.js test/integration/*.test.js && npm run test:ui && npm run test:tracker",
+    "test": "node --import ./test/suppress-expected-drift.js --test --test-timeout=300000 test/*.test.js test/comp-obs-branch/*.test.js test/integration/*.test.js test/golden/*.test.js && npm run test:ui && npm run test:tracker",
     "test:ui": "vitest run",
     "test:tracker": "vitest run --config vitest.tracker.config.js",
-    "test:integration": "node --test --test-timeout=120000 test/integration/*.test.js",
-    "test:wave-6": "node --test --test-timeout=120000 test/wave-6-integration.test.js test/wave-6-contract-compliance.test.js",
+    "test:integration": "node --test --test-timeout=300000 test/integration/*.test.js",
+    "test:wave-6": "node --test --test-timeout=300000 test/wave-6-integration.test.js test/wave-6-contract-compliance.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -85,7 +85,8 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@smartmemory/stratum": "^0.3.3",
+    "@smartmemory/sdk-js": "^1.4.60",
+    "@smartmemory/stratum": "^0.4.5",
     "@tanstack/react-virtual": "^3.13.23",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",