@smartmemory/compose 0.3.7 → 0.4.0

package/lib/new.js

@@ -13,6 +13,7 @@ import { promptGate } from './gate-prompt.js';
 import { VisionWriter } from './vision-writer.js';
 import { readFlowRound } from './flow-state.js';
 import { validateStep } from './step-validator.js';
+import { tsCompatibilityOf, quarantineMessage } from './pipeline-compat.js';
 
 const KICKOFF_VALIDATION = new Map([
   ['research', {
@@ -81,7 +82,18 @@ export async function runNew(intent, opts = {}) {
     throw new Error(`Kickoff spec not found: ${specPath}. Run 'compose init' to get default pipelines.`);
   }
 
-  const spec = YAML.parse(readFileSync(specPath, 'utf-8'));
+  // COMP-PIPELINE-QUARANTINE follow-up: `compose new` has its own runner and
+  // calls stratum.plan directly, so it never passed through runBuild's
+  // compatibility check. An existing workspace pinning an old new.stratum.yaml
+  // (init never overwrites one) still got the opaque engine rejection this check
+  // exists to replace.
+  const specText = readFileSync(specPath, 'utf-8');
+  const specCompat = tsCompatibilityOf(specText);
+  if (!specCompat.compatible) {
+    throw new Error(quarantineMessage(specPath, specCompat));
+  }
+
+  const spec = YAML.parse(specText);
   if (opts.skipResearch) {
     const research = spec.flows?.new?.steps?.find((step) => step.id === 'research');
     if (research) research.when = 'false';

package/lib/pipeline-compat.js

@@ -0,0 +1,104 @@
+/**
+ * TS-engine spec compatibility.
+ *
+ * COMP-PIPELINE-QUARANTINE: STRAT-PY-RETIRE converted only the two production
+ * pipelines (build, gsd) from the v0.3 dialect to TS v1 — see compose commit
+ * 9221548, "Both production pipelines (build, gsd) are re-authored as TS v1".
+ * Everything else in pipelines/ and presets/ stayed behind — most on v0.3,
+ * bug-fix on v0.1 — and the older execution paths were deleted, so those specs
+ * cannot run at all: the engine
+ * refuses them at `stratum_plan` with a bare `MCP error -32602: spec validation
+ * failed`, which tells the user nothing about why.
+ *
+ * This module is the single place that answers "can the TS engine run this
+ * spec". It reads the spec's OWN version stamp rather than consulting a list of
+ * pipeline names — so migrating a spec to `version: 1` lifts its quarantine
+ * automatically, with nothing here to remember to update.
+ */
+
+import { parse as parseYaml } from 'yaml';
+
+/** The only spec dialect the TS engine accepts. */
+export const TS_SPEC_VERSION = 1;
+
+/**
+ * The specs `compose init` seeds into a workspace's pipelines/ directory.
+ *
+ * Shared with resolveTemplatePath, which deliberately does NOT fall back to the
+ * bundled copy for these: their absence means the workspace was never
+ * initialized, and failing loudly with "Lifecycle spec not found" is the honest
+ * answer. Silently running Compose's own bundled build pipeline against an
+ * uninitialized project would be worse than the error. Every OTHER shipped
+ * pipeline (content, coverage-sweep, refactor, research, review-fix) is never
+ * copied by init, so the bundled copy is its only source and the fallback is the
+ * only way `--template research` can resolve at all.
+ */
+export const INIT_PROVISIONED_SPECS = Object.freeze([
+  'build',
+  'build-quick',
+  'bug-fix',
+  'new',
+  'plan',
+]);
+
+/**
+ * Classify a spec's engine compatibility.
+ *
+ * Deliberately shallow: a `version: 1` stamp means "authored for this engine",
+ * not "valid". Full validation belongs to the engine, which reports precise
+ * errors. This exists to turn the common, uninformative failure — a spec from
+ * the retired dialect — into a message that names the cause.
+ *
+ * @param {string} specText  Raw spec YAML
+ * @returns {{compatible: boolean, version: unknown, reason: string|null}}
+ */
+export function tsCompatibilityOf(specText) {
+  let parsed;
+  try {
+    parsed = parseYaml(specText);
+  } catch (err) {
+    return { compatible: false, version: null, reason: `spec is not parseable YAML: ${err.message}` };
+  }
+  const version = parsed?.version ?? null;
+  if (version === TS_SPEC_VERSION) return { compatible: true, version, reason: null };
+  if (version === null) {
+    return { compatible: false, version, reason: 'spec declares no `version`' };
+  }
+  return {
+    compatible: false,
+    version,
+    reason: `spec declares version ${JSON.stringify(version)}, but the TS engine only runs version ${TS_SPEC_VERSION}`,
+  };
+}
+
+/** True iff the TS engine will accept this spec's dialect. */
+export function isTsEngineSpec(specText) {
+  return tsCompatibilityOf(specText).compatible;
+}
+
+/**
+ * The message shown when a quarantined pipeline is invoked. Names the spec, the
+ * cause, and the only two ways forward — never a raw engine error code.
+ *
+ * @param {string} specPath  Absolute path of the offending spec
+ * @param {{reason: string|null}} compat  Result of tsCompatibilityOf
+ */
+export function quarantineMessage(specPath, compat) {
+  // Only a spec that declares an OLDER dialect gets the migration story. A
+  // malformed or version-less spec is far more likely to be a fresh typo, and
+  // telling its author it was "left behind by STRAT-PY-RETIRE" is a confident
+  // false history that sends them looking in the wrong place.
+  const isRetiredDialect = typeof compat.version === 'string' && /^0\./.test(compat.version);
+  const lines = [
+    `This pipeline cannot run: ${specPath}`,
+    `  ${compat.reason}.`,
+  ];
+  if (isRetiredDialect) {
+    lines.push(
+      '  It was left on a retired dialect when STRAT-PY-RETIRE cut the engine over to TS v1 and',
+      '  deleted the older execution path, so it has been unrunnable since that cutover.',
+    );
+  }
+  lines.push(`  The spec must declare \`version: ${TS_SPEC_VERSION}\` and use the TS v1 dialect.`);
+  return lines.join('\n');
+}

package/lib/policy-catalog.js

@@ -0,0 +1,295 @@
+/**
+ * policy-catalog.js — COMP-POLICY-CHECK-1: local detection-pattern catalog loader.
+ *
+ * Reads the `## Detection patterns` fenced-yaml convention out of a Claude Code
+ * memory directory (`<memory-dir>/feedback_*.md`) and turns it into data. This
+ * mirrors SmartMemory's Python loader
+ * (`smart-memory-core/smartmemory/adherence/detection.py`) field-for-field —
+ * SmartMemory's `memory_get_violation_patterns` MCP tool is a thin wrapper over
+ * that same parse, and Compose's engine is plain Node with no MCP client, so we
+ * parse the markdown directly rather than fetching it.
+ *
+ * Pure parsing + caching. No enforcement, no response inspection: that is
+ * `lib/policy-check.js`.
+ *
+ * Degradation contract:
+ *   - memory dir absent            → empty catalog, silent (opt-in feature)
+ *   - file without a block         → skipped, silent (the section is opt-in)
+ *   - block present but malformed  → skipped with a WARNING (authored intent
+ *     that produced nothing must be visible — no-silent-degradation rule)
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import YAML from 'yaml';
+
+// Leading `---` ... `---` frontmatter block.
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+
+// `## Detection patterns` heading followed by the first fenced code block.
+// The fence language tag (```yaml / ```yml / ```) is optional.
+const DETECTION_RE = /^##[ \t]+Detection patterns[ \t]*\n+```(?:ya?ml)?[ \t]*\n([\s\S]*?)\n```/im;
+
+const PATTERN_KEYS = ['regex', 'phrase', 'exclude_regex'];
+const DEFAULT_SCAN_TARGET = 'response';
+const DEFAULT_RECENT_TURN_WINDOW = 1;
+const DEFAULT_RULE_TYPE = 'feedback';
+
+/** dir → { key, catalog } — per-process, invalidated on max-mtime/file-count change. */
+const catalogCache = new Map();
+
+/**
+ * Read `.compose/compose.json` → `policyCheck` block. Uncached direct read,
+ * try/catch → {} on missing/malformed (same shape as smartmemory-config.js).
+ *
+ * An ABSENT block means enabled: the check ships as the Compose default and is
+ * structurally inert without a catalog. `enabled: false` is the kill switch.
+ *
+ * @param {string} cwd
+ * @returns {{ enabled?: boolean, memoryDir?: string }}
+ */
+export function getPolicyCheckConfig(cwd) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
+    const block = cfg.policyCheck;
+    return block && typeof block === 'object' && !Array.isArray(block) ? block : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {object} [config] pre-read config block (avoids a second file read)
+ * @returns {boolean} false only when the kill switch is explicitly set
+ */
+export function isPolicyCheckEnabled(cwd, config = getPolicyCheckConfig(cwd)) {
+  return config.enabled !== false;
+}
+
+/** Expand a leading `~` against the current user's home directory. */
+function expandHome(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Claude Code's project-directory encoding: the absolute project path with `/`
+ * and `.` replaced by `-` (so `/Users/x/reg/my/App` → `-Users-x-reg-my-App`).
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function encodeProjectDir(cwd) {
+  return resolve(cwd).replace(/[/.]/g, '-');
+}
+
+/**
+ * Resolve the memory directory for a project: config override (absolute, `~`,
+ * or cwd-relative) → the default Claude Code project memory dir.
+ *
+ * @param {string} cwd
+ * @param {object} [config]
+ * @returns {string} absolute path (existence not checked)
+ */
+export function resolveMemoryDir(cwd, config = getPolicyCheckConfig(cwd)) {
+  if (typeof config.memoryDir === 'string' && config.memoryDir.length > 0) {
+    const expanded = expandHome(config.memoryDir);
+    return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+  }
+  return join(homedir(), '.claude', 'projects', encodeProjectDir(cwd), 'memory');
+}
+
+/**
+ * Normalize a YAML list into the `{regex|phrase|exclude_regex: string}`
+ * contract. Non-list → []. Items are reduced to recognized string-valued keys;
+ * an item with no such key is dropped, so garbage never reaches consumers that
+ * assume string patterns.
+ */
+function validPatternItems(value) {
+  if (!Array.isArray(value)) return [];
+  const items = [];
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+    const cleaned = {};
+    for (const key of PATTERN_KEYS) {
+      if (typeof item[key] === 'string') cleaned[key] = item[key];
+    }
+    if (Object.keys(cleaned).length > 0) items.push(cleaned);
+  }
+  return items;
+}
+
+function parseFrontmatter(text) {
+  const m = FRONTMATTER_RE.exec(text);
+  if (!m) return {};
+  try {
+    const data = YAML.parse(m[1]);
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Return the parsed detection block, or null when absent/unusable.
+ * Absent → null, silently. Present-but-broken → null plus a WARNING.
+ */
+function parseDetectionBlock(text, sourceFile) {
+  const m = DETECTION_RE.exec(text);
+  if (!m) return null; // no block — normal, not an error
+
+  let data;
+  try {
+    data = YAML.parse(m[1]);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[policy-catalog] invalid YAML in detection block of ${sourceFile}: ${err.message}`);
+    return null;
+  }
+
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    // eslint-disable-next-line no-console
+    console.warn(`[policy-catalog] detection block in ${sourceFile} is not a mapping; skipping`);
+    return null;
+  }
+  if (validPatternItems(data.patterns).length === 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[policy-catalog] detection block in ${sourceFile} has no valid 'patterns' ` +
+      "(need {regex|phrase|exclude_regex: str}); skipping"
+    );
+    return null;
+  }
+  return data;
+}
+
+function safeInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.trunc(n) : fallback;
+}
+
+/**
+ * Load `## Detection patterns` records from a memory directory.
+ *
+ * @param {string} memoryDir
+ * @param {object} [opts]
+ * @param {string} [opts.ruleType='feedback'] filename prefix to scan; also the
+ *   fallback rule type when a file's frontmatter omits `type`
+ * @returns {Array<{name: string, description: string, ruleType: string,
+ *   patterns: object[], suppressionSignals: object[], scanTarget: string,
+ *   recentTurnWindow: number, sourceFile: string}>}
+ */
+export function loadCatalog(memoryDir, { ruleType = DEFAULT_RULE_TYPE } = {}) {
+  let names;
+  try {
+    names = readdirSync(memoryDir);
+  } catch {
+    // Absent (or unreadable) memory dir: the feature is opt-in, so an empty
+    // catalog here is the expected no-op rather than a degradation.
+    return [];
+  }
+
+  const files = names
+    .filter(n => n.startsWith(`${ruleType}_`) && n.endsWith('.md'))
+    .sort();
+
+  const out = [];
+  for (const name of files) {
+    const path = join(memoryDir, name);
+    let text;
+    try {
+      text = readFileSync(path, 'utf-8');
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`[policy-catalog] could not read ${path}: ${err.message}`);
+      continue;
+    }
+
+    const block = parseDetectionBlock(text, path);
+    if (block === null) continue;
+
+    try {
+      const fm = parseFrontmatter(text);
+      const metadata = block.metadata && typeof block.metadata === 'object' && !Array.isArray(block.metadata)
+        ? block.metadata
+        : {};
+      out.push({
+        name: String(fm.name || name.replace(/\.md$/, '')),
+        description: String(fm.description || ''),
+        ruleType: String(fm.type || fm?.metadata?.type || ruleType),
+        patterns: validPatternItems(block.patterns),
+        suppressionSignals: validPatternItems(block.suppression_signals),
+        scanTarget: String(metadata.scan_target || DEFAULT_SCAN_TARGET),
+        recentTurnWindow: safeInt(metadata.recent_turn_window, DEFAULT_RECENT_TURN_WINDOW),
+        sourceFile: path,
+      });
+    } catch (err) {
+      // Defensive: one bad file must not sink the batch.
+      // eslint-disable-next-line no-console
+      console.warn(`[policy-catalog] failed to build record for ${path}: ${err.message}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Cache key for a directory: a digest over the sorted (path, mtimeMs, size) of
+ * every rule file. Per-file rather than count + max-mtime, because that older
+ * key could not see an edit to an OLDER file while a newer one sat untouched —
+ * the max mtime never moved, so a real rule change went unnoticed for the life
+ * of the process.
+ */
+function cacheKey(memoryDir, ruleType) {
+  let names;
+  try {
+    names = readdirSync(memoryDir);
+  } catch {
+    return 'missing';
+  }
+  const parts = [];
+  for (const name of names.filter(n => n.startsWith(`${ruleType}_`) && n.endsWith('.md')).sort()) {
+    try {
+      const { mtimeMs, size } = statSync(join(memoryDir, name));
+      parts.push(`${name}:${mtimeMs}:${size}`);
+    } catch {
+      // Raced deletion between readdir and stat — record the absence so the key
+      // still changes rather than silently matching the previous digest.
+      parts.push(`${name}:gone`);
+    }
+  }
+  return createHash('sha1').update(parts.join('\n')).digest('hex');
+}
+
+/**
+ * Resolve + load the catalog for a project, cached per process and invalidated
+ * when any rule file changes. Returns [] when the kill switch is set or no
+ * catalog exists.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string} [opts.memoryDir] explicit override (skips config resolution)
+ * @param {string} [opts.ruleType='feedback']
+ * @returns {Array<object>} catalog records (see loadCatalog)
+ */
+export function getCatalog(cwd, { memoryDir, ruleType = DEFAULT_RULE_TYPE } = {}) {
+  const config = getPolicyCheckConfig(cwd);
+  if (!isPolicyCheckEnabled(cwd, config)) return [];
+
+  const dir = memoryDir ?? resolveMemoryDir(cwd, config);
+  const key = `${ruleType}|${cacheKey(dir, ruleType)}`;
+  const cached = catalogCache.get(dir);
+  if (cached && cached.key === key) return cached.catalog;
+
+  const catalog = loadCatalog(dir, { ruleType });
+  catalogCache.set(dir, { key, catalog });
+  return catalog;
+}
+
+/** Test hook: drop the per-process catalog cache. */
+export function _clearCatalogCache() {
+  catalogCache.clear();
+}

package/lib/process-termination.js

@@ -0,0 +1,98 @@
+/**
+ * process-termination.js — graceful teardown for a spawned agent child process.
+ *
+ * Compose spawns the Claude Code CLI itself (see `lib/local-claude-connector.js`)
+ * so that a cancelled run tears down the WHOLE process tree, not just the leader.
+ * The child is spawned `detached: true`, which makes it a process-group leader;
+ * signalling `-pid` reaches every descendant.
+ *
+ * Only what compose uses lives here. The teardown contract is:
+ *   SIGTERM the group → wait up to the grace period → SIGKILL anything still
+ *   alive → await leader close and group disappearance (bounded at 2 seconds).
+ *
+ * Grace period: `COMPOSE_CANCEL_GRACE_MS` (default 5000ms).
+ */
+
+const DEFAULT_GRACE_MS = 5000;
+
+/** Read the configured cancellation grace period. */
+function graceMsFromEnv(env = process.env) {
+  const raw = env.COMPOSE_CANCEL_GRACE_MS;
+  if (raw === undefined || raw === '') return DEFAULT_GRACE_MS;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error('COMPOSE_CANCEL_GRACE_MS must be a nonnegative number');
+  }
+  return value;
+}
+
+/**
+ * Own the teardown of a spawned child, separately from `child.kill()`, so SDK
+ * cleanup cannot bypass the grace period.
+ *
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {boolean} group — signal the whole process group (child was detached)
+ * @param {number} [graceMs]
+ * @returns {{ close: Promise<void>, terminate: () => Promise<void>, finish: () => Promise<void> }}
+ */
+export function processTermination(child, group, graceMs = graceMsFromEnv(), reapTimeoutMs = 2000) {
+  let closed = false;
+  const close = new Promise((resolve) => child.once('close', () => { closed = true; resolve(); }));
+  let teardown;
+
+  const send = (signal) => {
+    if (group && child.pid) {
+      try {
+        process.kill(-child.pid, signal);
+      } catch (error) {
+        if (error.code !== 'ESRCH') throw error;
+      }
+    } else if (!closed) {
+      child.kill(signal);
+    }
+  };
+
+  // The group outlives the leader: `close` firing does not mean the descendants
+  // are gone, so liveness is probed with signal 0 against the group.
+  const alive = () => {
+    if (!group || !child.pid) return !closed;
+    try {
+      process.kill(-child.pid, 0);
+      return true;
+    } catch (error) {
+      if (error.code === 'ESRCH') return false;
+      throw error;
+    }
+  };
+
+  const terminate = () => {
+    teardown ??= (async () => {
+      send('SIGTERM');
+      let timer;
+      try {
+        await Promise.race([
+          new Promise((resolve) => { timer = setTimeout(resolve, graceMs); }),
+          // A leader that closed while its group lives must still wait out the
+          // grace period, so that branch parks on a never-settling promise.
+          close.then(() => (alive() ? new Promise(() => {}) : undefined)),
+        ]);
+        if (alive()) send('SIGKILL');
+        await close;
+        const deadline = Date.now() + reapTimeoutMs;
+        while (group && alive()) {
+          if (Date.now() >= deadline) throw Object.assign(new Error(`Process group still exists after ${reapTimeoutMs}ms reap deadline`), { code: 'CANCELLATION_TEARDOWN_TIMEOUT' });
+          await new Promise(resolve => setTimeout(resolve, 10));
+        }
+      } catch (error) {
+        if (error.code !== 'CANCELLATION_TEARDOWN_TIMEOUT') error.code = 'CANCELLATION_UNCONFIRMED';
+        throw error;
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    })();
+    void teardown.catch(() => {});
+    return teardown;
+  };
+
+  return { close, terminate, finish: () => teardown ?? Promise.resolve() };
+}

package/lib/resolve-workspace.js

@@ -1,7 +1,11 @@
 /**
  * resolve-workspace.js — single resolver chain for compose workspaces.
  *
- * Precedence:
+ * MCP effective precedence: explicit workspaceId > session binding > COMPOSE_TARGET
+ * > discovery. compose-mcp promotes its session binding to hint.workspaceId before
+ * calling this resolver, so an established session wins over the process default.
+ *
+ * Generic resolver precedence (including CLI callers):
  *   1. explicit hint.workspaceId  (cheap upward walk first; falls back to discovery)
  *   2. COMPOSE_TARGET env         (absolute path bypasses discovery; id routes through it)
  *   3. hint.getBinding() (MCP binding)