@smartmemory/compose 0.1.0 → 0.1.2-beta

package/lib/connector-factory-shim.js

@@ -0,0 +1,167 @@
+/**
+ * connector-factory-shim.js — Backward-compatibility adapter for tests that
+ * pass a legacy `connectorFactory(agentType, opts)` returning an object with
+ * an async-generator `run(prompt)` that yields `{type: 'assistant'|'tool_use'
+ * |'tool_use_summary'|'usage'|'error'|'result', ...}` events.
+ *
+ * After STRAT-DEDUP-AGENTRUN-V3 the consumer pipeline calls
+ * `stratum.agentRun(...)` and consumes BuildStreamEvent envelopes via
+ * `stratum.onEvent(correlationId, '_agent_run', handler)`. This shim adapts
+ * the legacy factory to dispatch envelopes through the StratumMcpClient's
+ * onEvent pathway so existing tests continue to assert wire-level behavior.
+ *
+ * Used only when `opts.stratum` is NOT injected directly. Production paths
+ * never instantiate this shim.
+ */
+
+/**
+ * Install fake `agentRun`, `runAgentText`, `cancelAgentRun` methods on a
+ * StratumMcpClient instance backed by a legacy connector factory.
+ *
+ * @param {object} stratum         - StratumMcpClient (uses its #dispatchEvent path indirectly via internal subscribers).
+ * @param {Function} factory       - legacy `factory(agentType, opts)` returning {run(prompt), interrupt(), isRunning}
+ * @param {string}   defaultCwd
+ */
+export function installFactoryShim(stratum, factory, defaultCwd) {
+  // We dispatch via the public onEvent subscribers map. There's no public
+  // emit method, so we synthesize the same JSON-string-via-progress path the
+  // real client uses by directly invoking subscribed handlers.
+  function emit(correlationId, kind, metadata, seq) {
+    // Replicate the dispatch path: lookup `${flow}::${step}` subscribers and
+    // hand them a parsed envelope. This mirrors `#dispatchEvent` (private)
+    // but works against the public `onEvent` registry implicitly because we
+    // only run inside a single tool-call lifecycle.
+    const env = {
+      schema_version: '0.2.5',
+      flow_id: correlationId,
+      step_id: '_agent_run',
+      task_id: null,
+      seq,
+      ts: new Date().toISOString(),
+      kind,
+      metadata,
+    };
+    // Lean on the stratum client's existing #makeProgressHandler-style path:
+    // re-encode and feed via a shadow handler is overkill — we instead reach
+    // into the onEvent subscribers via a dispatch closure attached on first
+    // install.
+    if (!stratum._shimDispatch) {
+      // Fallback: directly walk subscribers if dispatch closure not wired.
+      // Here we expose a temporary dispatcher by hijacking onEvent's contract:
+      // each subscribe call adds to a map; we mirror lookups via a private
+      // tracker. The simpler approach is to wrap `onEvent` to also register
+      // with our own map. Done at install time below.
+    }
+    stratum._shimDispatch(env);
+  }
+
+  // Wrap onEvent to keep a parallel registry we can dispatch into.
+  if (!stratum._shimSubs) {
+    const subs = new Map();
+    stratum._shimSubs = subs;
+    const realOnEvent = stratum.onEvent.bind(stratum);
+    stratum.onEvent = (flowId, stepId, handler) => {
+      const key = `${flowId}::${stepId}`;
+      let set = subs.get(key);
+      if (!set) { set = new Set(); subs.set(key, set); }
+      set.add(handler);
+      const realUnsub = realOnEvent(flowId, stepId, handler);
+      return () => {
+        const s = subs.get(key);
+        if (s) { s.delete(handler); if (s.size === 0) subs.delete(key); }
+        realUnsub();
+      };
+    };
+    stratum._shimDispatch = (env) => {
+      const set = subs.get(`${env.flow_id}::${env.step_id}`);
+      if (!set) return;
+      for (const h of set) {
+        try { h(env); } catch (err) { console.error('[shim] handler threw:', err); }
+      }
+    };
+  }
+
+  stratum.agentRun = async (agentType, prompt, agentOpts = {}) => {
+    const correlationId = agentOpts.correlationId ?? `mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const connector = factory(agentType, { cwd: agentOpts.cwd ?? defaultCwd });
+    const parts = [];
+    let seq = 0;
+    let interruptHook = null;
+    if (typeof connector.interrupt === 'function') {
+      interruptHook = () => { try { connector.interrupt(); } catch { /* best-effort */ } };
+    }
+    // Hook for cancelAgentRun: stash the interrupt function under correlationId.
+    if (!stratum._shimInterrupts) stratum._shimInterrupts = new Map();
+    if (interruptHook) stratum._shimInterrupts.set(correlationId, interruptHook);
+    try {
+      for await (const ev of connector.run(prompt, {})) {
+        if (ev.type === 'assistant' && ev.content) {
+          parts.push(ev.content);
+          stratum._shimDispatch({
+            schema_version: '0.2.5',
+            flow_id: correlationId, step_id: '_agent_run', task_id: null,
+            seq: seq++, ts: new Date().toISOString(),
+            kind: 'agent_relay',
+            metadata: { role: 'assistant', text: ev.content },
+          });
+        } else if (ev.type === 'result' && ev.content && parts.length === 0) {
+          parts.push(ev.content);
+          stratum._shimDispatch({
+            schema_version: '0.2.5',
+            flow_id: correlationId, step_id: '_agent_run', task_id: null,
+            seq: seq++, ts: new Date().toISOString(),
+            kind: 'agent_relay',
+            metadata: { role: 'assistant', text: ev.content },
+          });
+        } else if (ev.type === 'tool_use' && ev.tool) {
+          stratum._shimDispatch({
+            schema_version: '0.2.5',
+            flow_id: correlationId, step_id: '_agent_run', task_id: null,
+            seq: seq++, ts: new Date().toISOString(),
+            kind: 'tool_use_summary',
+            metadata: { tool: ev.tool, input: ev.input ?? {}, summary: '', output: '' },
+          });
+        } else if (ev.type === 'tool_use_summary') {
+          stratum._shimDispatch({
+            schema_version: '0.2.5',
+            flow_id: correlationId, step_id: '_agent_run', task_id: null,
+            seq: seq++, ts: new Date().toISOString(),
+            kind: 'tool_use_summary',
+            metadata: { tool: ev.tool ?? '', input: ev.input ?? {}, summary: ev.summary ?? '', output: ev.output ?? '' },
+          });
+        } else if (ev.type === 'usage') {
+          stratum._shimDispatch({
+            schema_version: '0.2.5',
+            flow_id: correlationId, step_id: '_agent_run', task_id: null,
+            seq: seq++, ts: new Date().toISOString(),
+            kind: 'step_usage',
+            metadata: {
+              input_tokens: ev.input_tokens ?? 0,
+              output_tokens: ev.output_tokens ?? 0,
+              cache_creation_input_tokens: ev.cache_creation_input_tokens ?? 0,
+              cache_read_input_tokens: ev.cache_read_input_tokens ?? 0,
+              cost_usd: ev.cost_usd ?? null,
+              model: ev.model ?? null,
+            },
+          });
+        } else if (ev.type === 'error') {
+          throw new Error(ev.message);
+        }
+      }
+    } finally {
+      stratum._shimInterrupts?.delete(correlationId);
+    }
+    return { text: parts.join(''), correlation_id: correlationId };
+  };
+
+  stratum.runAgentText = async (agentType, prompt, agentOpts = {}) => {
+    const r = await stratum.agentRun(agentType, prompt, agentOpts);
+    return r.text;
+  };
+
+  stratum.cancelAgentRun = async (correlationId) => {
+    const hook = stratum._shimInterrupts?.get(correlationId);
+    if (hook) hook();
+    return { status: hook ? 'cancelled' : 'not_found', correlation_id: correlationId };
+  };
+}

package/lib/constants.js

@@ -43,6 +43,24 @@ export const GATE_ARTIFACTS = {
   report_gate: 'report.md',
 };
 
+/**
+ * Subdirectory under a feature folder where per-task section files live.
+ * Emitted only when a plan exceeds the section threshold.
+ */
+export const SECTIONS_DIR = 'sections';
+
+/**
+ * Read the section-emission threshold from env.
+ * Default 5; unparseable falls back to default; finite is clamped to >= 1.
+ */
+export function getSectionsThreshold() {
+  const envVal = process.env.COMPOSE_PLAN_SECTIONS_THRESHOLD;
+  if (envVal === undefined || envVal === null || envVal === '') return 5;
+  const raw = parseInt(envVal, 10);
+  if (!Number.isFinite(raw)) return 5;
+  return Math.max(1, raw);
+}
+
 /**
  * Title-case a step ID for display when no label exists.
  * e.g. "some_step" -> "Some Step"

package/lib/debug-discipline.js

@@ -14,25 +14,44 @@ import { join } from 'node:path';
 // Fix-Chain Detector
 // ---------------------------------------------------------------------------
 
+const FEATURE_MODE_KEY = '__feature_mode__';
+const LEGACY_KEY = '__legacy__';
+
 /**
  * Tracks which files are modified across fix iterations.
  * Detects thrashing: same file touched in multiple iterations.
+ *
+ * Per-bug keying (COMP-FIX-HARD T9): state is namespaced by bug code.
+ * Legacy flat API (recordIteration/detect/iteration) delegates to a
+ * synthetic `__feature_mode__` key for feature-mode builds.
  */
 export class FixChainDetector {
   constructor() {
-    this.fileHits = new Map();
-    this.iteration = 0;
+    /** @type {Map<string, { iteration: number, fileHits: Map<string, number> }>} */
+    this.byBug = new Map();
   }
 
-  recordIteration(filesChanged) {
-    this.iteration++;
+  _slot(bugCode) {
+    let s = this.byBug.get(bugCode);
+    if (!s) {
+      s = { iteration: 0, fileHits: new Map() };
+      this.byBug.set(bugCode, s);
+    }
+    return s;
+  }
+
+  recordIterationForBug(bugCode, filesChanged) {
+    const s = this._slot(bugCode);
+    s.iteration++;
     for (const file of filesChanged) {
-      this.fileHits.set(file, (this.fileHits.get(file) ?? 0) + 1);
+      s.fileHits.set(file, (s.fileHits.get(file) ?? 0) + 1);
     }
   }
 
-  detect() {
-    return [...this.fileHits.entries()]
+  detectForBug(bugCode) {
+    const s = this.byBug.get(bugCode);
+    if (!s) return [];
+    return [...s.fileHits.entries()]
       .filter(([, count]) => count >= 2)
       .map(([file, count]) => ({
         file,
@@ -41,17 +60,74 @@ export class FixChainDetector {
       }));
   }
 
+  getIterationForBug(bugCode) {
+    return this.byBug.get(bugCode)?.iteration ?? 0;
+  }
+
+  resetForBug(bugCode) {
+    this.byBug.delete(bugCode);
+  }
+
+  // --- Legacy global API (feature mode) ----------------------------------
+
+  recordIteration(filesChanged) {
+    this.recordIterationForBug(FEATURE_MODE_KEY, filesChanged);
+  }
+
+  detect() {
+    return this.detectForBug(FEATURE_MODE_KEY);
+  }
+
+  get iteration() {
+    return this.getIterationForBug(FEATURE_MODE_KEY);
+  }
+
+  set iteration(v) {
+    this._slot(FEATURE_MODE_KEY).iteration = v;
+  }
+
+  get fileHits() {
+    return this._slot(FEATURE_MODE_KEY).fileHits;
+  }
+
+  set fileHits(map) {
+    this._slot(FEATURE_MODE_KEY).fileHits = map instanceof Map ? map : new Map(Object.entries(map ?? {}));
+  }
+
+  // --- Serialization ------------------------------------------------------
+
   toJSON() {
-    return {
-      iteration: this.iteration,
-      fileHits: Object.fromEntries(this.fileHits),
-    };
+    const out = {};
+    for (const [key, s] of this.byBug.entries()) {
+      out[key] = {
+        iteration: s.iteration,
+        fileHits: Object.fromEntries(s.fileHits),
+      };
+    }
+    return out;
   }
 
   static fromJSON(json) {
     const d = new FixChainDetector();
-    d.iteration = json.iteration ?? 0;
-    d.fileHits = new Map(Object.entries(json.fileHits ?? {}));
+    if (!json || typeof json !== 'object') return d;
+    // Legacy detection: flat shape has top-level `iteration` and/or `fileHits`
+    // and no per-bug sub-objects with the per-bug shape.
+    // Salvage any top-level legacy fields. Fold into __feature_mode__ so the
+    // existing global-API getters (recordIteration / detect / iteration getter)
+    // continue to surface it. If there's already a per-bug subkey for
+    // __feature_mode__ in the same JSON, the explicit subkey wins.
+    if ('iteration' in json || 'fileHits' in json) {
+      const slot = d._slot(FEATURE_MODE_KEY);
+      slot.iteration = json.iteration ?? 0;
+      slot.fileHits = new Map(Object.entries(json.fileHits ?? {}));
+    }
+    for (const [key, sub] of Object.entries(json)) {
+      if (key === 'iteration' || key === 'fileHits') continue; // top-level legacy, already folded
+      if (!sub || typeof sub !== 'object') continue;
+      const slot = d._slot(key);
+      slot.iteration = sub.iteration ?? 0;
+      slot.fileHits = new Map(Object.entries(sub.fileHits ?? {}));
+    }
     return d;
   }
 }
@@ -65,42 +141,115 @@ const VISUAL_EXTENSIONS = /\.(css|scss|jsx|tsx)$/i;
 /**
  * Tracks fix attempts and enforces thresholds with escalation.
  * Visual bugs escalate at attempt 2; all bugs escalate at attempt 5.
+ *
+ * Per-bug keying (COMP-FIX-HARD T9): state is namespaced by bug code.
+ * Legacy flat API (record/getIntervention/count/isVisual) delegates to a
+ * synthetic `__feature_mode__` key for feature-mode builds.
  */
 export class AttemptCounter {
   constructor() {
-    this.count = 0;
-    this.isVisual = false;
+    /** @type {Map<string, { count: number, isVisual: boolean }>} */
+    this.byBug = new Map();
   }
 
-  record({ filesChanged = [], isVisual = null }) {
-    this.count++;
+  _slot(bugCode) {
+    let s = this.byBug.get(bugCode);
+    if (!s) {
+      s = { count: 0, isVisual: false };
+      this.byBug.set(bugCode, s);
+    }
+    return s;
+  }
+
+  recordForBug(bugCode, { filesChanged = [], isVisual = null } = {}) {
+    const s = this._slot(bugCode);
+    s.count++;
     if (isVisual !== null) {
-      this.isVisual = isVisual;
+      s.isVisual = isVisual;
     } else if (filesChanged.some(f => AttemptCounter.isVisualFile(f))) {
-      this.isVisual = true;
+      s.isVisual = true;
     }
   }
 
-  getIntervention() {
-    if (this.count >= 5) return 'escalate';
-    if (this.count >= 3 && !this.isVisual) return 'trace_refresh';
-    if (this.count >= 2 && this.isVisual) return 'escalate';
-    if (this.count >= 2) return 'trace_reminder';
+  getCountForBug(bugCode) {
+    return this.byBug.get(bugCode)?.count ?? 0;
+  }
+
+  getInterventionForBug(bugCode) {
+    const s = this.byBug.get(bugCode);
+    if (!s) return null;
+    if (s.count >= 5) return 'escalate';
+    if (s.count >= 3 && !s.isVisual) return 'trace_refresh';
+    if (s.count >= 2 && s.isVisual) return 'escalate';
+    if (s.count >= 2) return 'trace_reminder';
     return null;
   }
 
+  resetForBug(bugCode) {
+    this.byBug.delete(bugCode);
+  }
+
+  // --- Legacy global API (feature mode) ----------------------------------
+
+  record(opts) {
+    this.recordForBug(FEATURE_MODE_KEY, opts ?? {});
+  }
+
+  getIntervention() {
+    return this.getInterventionForBug(FEATURE_MODE_KEY);
+  }
+
+  get count() {
+    return this.getCountForBug(FEATURE_MODE_KEY);
+  }
+
+  set count(v) {
+    this._slot(FEATURE_MODE_KEY).count = v;
+  }
+
+  get isVisual() {
+    return this.byBug.get(FEATURE_MODE_KEY)?.isVisual ?? false;
+  }
+
+  set isVisual(v) {
+    this._slot(FEATURE_MODE_KEY).isVisual = !!v;
+  }
+
   static isVisualFile(file) {
     return VISUAL_EXTENSIONS.test(file);
   }
 
+  // --- Serialization ------------------------------------------------------
+
   toJSON() {
-    return { count: this.count, isVisual: this.isVisual };
+    const out = {};
+    for (const [key, s] of this.byBug.entries()) {
+      out[key] = { count: s.count, isVisual: s.isVisual };
+    }
+    return out;
   }
 
   static fromJSON(json) {
     const c = new AttemptCounter();
-    c.count = json.count ?? 0;
-    c.isVisual = json.isVisual ?? false;
+    if (!json || typeof json !== 'object') return c;
+    // Legacy detection: flat shape has top-level `count`/`isVisual` and
+    // no per-bug sub-objects with the per-bug shape.
+    // Salvage any top-level legacy fields. Fold into __feature_mode__ so the
+    // existing global-API getters (count getter, getIntervention, etc.)
+    // continue to surface it. If an explicit __feature_mode__ subkey is also
+    // present, it wins (loop below).
+    if ('count' in json || 'isVisual' in json) {
+      const slot = c._slot(FEATURE_MODE_KEY);
+      slot.count = json.count ?? 0;
+      slot.isVisual = json.isVisual ?? false;
+    }
+    for (const [key, sub] of Object.entries(json)) {
+      if (key === 'count' || key === 'isVisual') continue; // top-level legacy, already handled
+      if (!sub || typeof sub !== 'object') continue;
+      const slot = c._slot(key);
+      slot.count = sub.count ?? 0;
+      slot.isVisual = sub.isVisual ?? false;
+    }
     return c;
   }
 }

package/lib/deps.js

@@ -0,0 +1,205 @@
+/**
+ * COMP-DEPS-PACKAGE — external skill dependency manifest helpers.
+ *
+ * Three exported functions used by `bin/compose.js` (and tested in
+ * `test/comp-deps-package.test.js`):
+ *
+ *   loadDeps(packageRoot)                — load and validate .compose-deps.json
+ *   checkExternalSkills(deps, home?)     — scan disk, return present/missing dep records
+ *   printDepReport(result, opts?)        — human or JSON output, returns true if all required deps present
+ *
+ * Manifest schema is documented in docs/features/COMP-DEPS-PACKAGE/blueprint.md.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+/**
+ * Load .compose-deps.json from `packageRoot`. Returns the parsed manifest with
+ * invalid entries filtered out (skip-and-warn), or null if the manifest file
+ * is missing/unparseable/structurally invalid.
+ */
+export function loadDeps(packageRoot) {
+  const manifestPath = join(packageRoot, '.compose-deps.json')
+  if (!existsSync(manifestPath)) return null
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+  } catch (e) {
+    console.warn(`Warning: failed to parse .compose-deps.json: ${e.message}`)
+    return null
+  }
+  if (raw.version !== 1) {
+    console.warn(`Warning: .compose-deps.json version ${raw.version} unsupported (expected 1)`)
+    return null
+  }
+  if (!Array.isArray(raw.external_skills)) {
+    console.warn('Warning: .compose-deps.json external_skills must be an array')
+    return null
+  }
+  const valid = []
+  for (const dep of raw.external_skills) {
+    const idOk = typeof dep?.id === 'string'
+    const reqOk = Array.isArray(dep?.required_for) && dep.required_for.every(v => typeof v === 'string')
+    const installOk = typeof dep?.install === 'string'
+    const fallbackOk = dep?.fallback === null || typeof dep?.fallback === 'string'
+    const optOk = typeof dep?.optional === 'boolean'
+    if (!(idOk && reqOk && installOk && fallbackOk && optOk)) {
+      console.warn(`Warning: skipping invalid dep entry in .compose-deps.json: ${JSON.stringify(dep)}`)
+      continue
+    }
+    valid.push(dep)
+  }
+  return { ...raw, external_skills: valid }
+}
+
+/**
+ * Scan disk for installed skills and commands matching the manifest's deps.
+ * Returns { present: [...], missing: [...], scannedPaths: [...] }.
+ *
+ * Scans:
+ *   - <home>/.claude/skills/<id>/SKILL.md                                 (bare-name skills)
+ *   - <home>/.claude/plugins/marketplaces/<m>/plugins/<p>/skills/<s>/SKILL.md   (pattern A)
+ *   - <home>/.claude/plugins/marketplaces/<m>/plugins/<p>/commands/<n>.md       (pattern A')
+ *   - <home>/.claude/plugins/marketplaces/<m>/.claude/skills/<s>/SKILL.md       (pattern B)
+ *   - <home>/.claude/plugins/marketplaces/<m>/.claude/commands/<n>.md           (pattern B')
+ *   - <home>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills/<s>/SKILL.md  (pattern C)
+ */
+export function checkExternalSkills(deps, home = homedir()) {
+  const userSkillsRoot = join(home, '.claude', 'skills')
+  const marketplacesRoot = join(home, '.claude', 'plugins', 'marketplaces')
+  const cacheRoot = join(home, '.claude', 'plugins', 'cache')
+  const scannedPaths = [userSkillsRoot, marketplacesRoot, cacheRoot]
+
+  const bareInstalled = new Set()
+  const namespacedInstalled = new Set()
+  const addNs = (ns, leaf) => namespacedInstalled.add(`${ns}:${leaf}`)
+
+  // Helpers: list only entries of a given dirent kind, swallow scandir errors.
+  const listDirs = (path) => {
+    if (!existsSync(path)) return []
+    try {
+      return readdirSync(path, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+    } catch { return [] }
+  }
+  const listFiles = (path) => {
+    if (!existsSync(path)) return []
+    try {
+      return readdirSync(path, { withFileTypes: true })
+        .filter(e => e.isFile())
+        .map(e => e.name)
+    } catch { return [] }
+  }
+
+  // 1. Bare-name user skills
+  for (const entry of listDirs(userSkillsRoot)) {
+    if (existsSync(join(userSkillsRoot, entry, 'SKILL.md'))) bareInstalled.add(entry)
+  }
+
+  // 2. Marketplaces — skills (A, B) and commands (A', B')
+  for (const m of listDirs(marketplacesRoot)) {
+    // Pattern A / A': marketplaces/<m>/plugins/<p>/{skills,commands}/...
+    const pluginsDir = join(marketplacesRoot, m, 'plugins')
+    for (const p of listDirs(pluginsDir)) {
+      const skillsDir = join(pluginsDir, p, 'skills')
+      for (const s of listDirs(skillsDir)) {
+        if (existsSync(join(skillsDir, s, 'SKILL.md'))) addNs(p, s)
+      }
+      const commandsDir = join(pluginsDir, p, 'commands')
+      for (const f of listFiles(commandsDir)) {
+        if (f.endsWith('.md')) addNs(p, f.slice(0, -3))
+      }
+    }
+    // Pattern B / B': marketplaces/<m>/.claude/{skills,commands}/...
+    const dotSkillsDir = join(marketplacesRoot, m, '.claude', 'skills')
+    for (const s of listDirs(dotSkillsDir)) {
+      if (existsSync(join(dotSkillsDir, s, 'SKILL.md'))) addNs(m, s)
+    }
+    const dotCommandsDir = join(marketplacesRoot, m, '.claude', 'commands')
+    for (const f of listFiles(dotCommandsDir)) {
+      if (f.endsWith('.md')) addNs(m, f.slice(0, -3))
+    }
+  }
+
+  // 3. Cache — pattern C: cache/<marketplace>/<plugin>/<version>/skills/<s>/SKILL.md
+  for (const marketplace of listDirs(cacheRoot)) {
+    for (const plugin of listDirs(join(cacheRoot, marketplace))) {
+      for (const version of listDirs(join(cacheRoot, marketplace, plugin))) {
+        const skillsDir = join(cacheRoot, marketplace, plugin, version, 'skills')
+        for (const s of listDirs(skillsDir)) {
+          if (existsSync(join(skillsDir, s, 'SKILL.md'))) addNs(plugin, s)
+        }
+      }
+    }
+  }
+
+  const present = []
+  const missing = []
+  for (const dep of deps.external_skills) {
+    const isNamespaced = dep.id.includes(':')
+    const found = isNamespaced ? namespacedInstalled.has(dep.id) : bareInstalled.has(dep.id)
+    if (found) present.push(dep); else missing.push(dep)
+  }
+
+  return { present, missing, scannedPaths }
+}
+
+/**
+ * Print human or JSON dep report. Returns true if all required (non-optional) deps present.
+ *
+ * opts:
+ *   json    — emit JSON with full dep records (id, required_for, install, fallback, optional)
+ *   verbose — also list scanned paths in human mode
+ */
+export function printDepReport(result, opts = {}) {
+  const projectDep = (d) => ({
+    id: d.id,
+    required_for: d.required_for,
+    install: d.install,
+    fallback: d.fallback ?? null,
+    optional: d.optional,
+  })
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      present: result.present.map(projectDep),
+      missing: result.missing.map(projectDep),
+      scannedPaths: result.scannedPaths,
+    }, null, 2))
+    return result.missing.every(d => d.optional)
+  }
+
+  console.log('\nExternal skill dependencies:')
+  for (const dep of result.present) {
+    console.log(`  ✓ ${dep.id}`)
+  }
+
+  const missingRequired = result.missing.filter(d => !d.optional)
+  const missingOptional = result.missing.filter(d => d.optional)
+
+  for (const dep of missingRequired) {
+    console.log(`  ✗ ${dep.id}  — install: ${dep.install}`)
+  }
+  for (const dep of missingOptional) {
+    console.log(`  ○ ${dep.id} (optional) — install: ${dep.install}`)
+  }
+
+  const total = result.present.length + result.missing.length
+  if (result.missing.length === 0) {
+    console.log(`\nAll ${total} deps present.`)
+  } else {
+    console.log(`\n${result.missing.length} of ${total} deps missing (${missingRequired.length} required, ${missingOptional.length} optional).`)
+    if (missingRequired.length > 0) {
+      console.log('Lifecycle will run in degraded mode for affected phases. See SKILL.md §Dependencies for fallback paths.')
+    }
+  }
+
+  if (opts.verbose) {
+    console.log('\nScanned paths:')
+    for (const p of result.scannedPaths) console.log(`  ${p}`)
+  }
+
+  return missingRequired.length === 0
+}

package/lib/health-score.js

@@ -3,7 +3,7 @@
  *
  * Aggregates signals from existing build artifacts into a 0-100 composite
  * health score. No new data sources — only aggregates what already exists:
- *   - Review findings from parallel_review's MergedReviewResult
+ *   - Review findings from parallel_review's ReviewResult (canonical — STRAT-CLAUDE-EFFORT-PARITY)
  *   - Test pass/fail from coverage_check result
  *   - Contract compliance from Stratum ensure results
  *   - Doc freshness from lib/staleness.js
@@ -52,19 +52,19 @@ export function scoreTestCoverage(testResult) {
 }
 
 /**
- * Score review findings from a MergedReviewResult.
+ * Score review findings from a ReviewResult.
  *
  * Severity breakdown:
  *   must-fix  → -20 per finding
  *   should-fix → -5 per finding
  *   nit        → -1 per finding
  *
- * @param {object|null} mergedResult  { findings: [{severity, ...}] }
+ * @param {object|null} mergedResult  ReviewResult: { findings: [{severity, ...}] }
  * @returns {number} 0-100 (floored at 0)
  */
 export function scoreReviewFindings(mergedResult) {
   if (mergedResult == null) return 50; // neutral — no data
-  const findings = mergedResult.findings ?? mergedResult.all_findings ?? [];
+  const findings = mergedResult.findings ?? [];
   if (findings.length === 0) return 100;
 
   let score = 100;