@smartmemory/compose 0.1.0

package/lib/gate-tiers.js

@@ -0,0 +1,194 @@
+/**
+ * gate-tiers.js — COMP-OBS-GATES: tiered gate evaluation with short-circuit.
+ *
+ * Defines the five evaluation tiers used by the review pipeline.
+ * Tiers are ordered cheapest → most expensive. When a tier fails, all
+ * subsequent (more expensive) tiers are skipped — short-circuit.
+ *
+ * Tiers:
+ *   T0  schema     — output contract validation (free, instant)
+ *   T1  lint       — lint/format checks (fast)
+ *   T2  tests      — test suite execution (medium)
+ *   T3  llm-review — Claude multi-lens review (expensive)
+ *   T4  cross-model — Codex cross-model review (very expensive)
+ */
+
+// ---------------------------------------------------------------------------
+// Tier definitions
+// ---------------------------------------------------------------------------
+
+export const GATE_TIERS = [
+  {
+    id: 'T0',
+    name: 'schema',
+    cost: 'free',
+    description: 'Output contract validation',
+  },
+  {
+    id: 'T1',
+    name: 'lint',
+    cost: 'fast',
+    description: 'Lint/format checks',
+  },
+  {
+    id: 'T2',
+    name: 'tests',
+    cost: 'medium',
+    description: 'Test suite execution',
+  },
+  {
+    id: 'T3',
+    name: 'llm-review',
+    cost: 'expensive',
+    description: 'Claude multi-lens review',
+  },
+  {
+    id: 'T4',
+    name: 'cross-model',
+    cost: 'very-expensive',
+    description: 'Codex cross-model review',
+  },
+];
+
+// Map tier ID → index for fast ordering lookups
+const TIER_ORDER = new Map(GATE_TIERS.map((t, i) => [t.id, i]));
+
+// ---------------------------------------------------------------------------
+// Cost estimates (rough USD per invocation)
+// ---------------------------------------------------------------------------
+
+// Base cost constants (USD)
+const TIER_BASE_COST_USD = {
+  T0: 0.00,   // free — purely local contract validation
+  T1: 0.00,   // free — local lint process
+  T2: 0.05,   // test suite: estimate varies; use conservative floor
+  T3: 0.50,   // Opus multi-lens: ~$0.50 per review pass
+  T4: 0.30,   // Codex synthesis: ~$0.30 per cross-model pass
+};
+
+/**
+ * Estimate the cost of running a tier in USD.
+ *
+ * @param {string} tierId       Tier ID (e.g. 'T0', 'T3')
+ * @param {object} [context]    Optional context for future scaling (e.g. file count, lens count)
+ * @param {number} [context.lensCount]  Number of review lenses (scales T3 cost)
+ * @returns {number}            Estimated cost in USD
+ */
+export function estimateTierCost(tierId, context = {}) {
+  const base = TIER_BASE_COST_USD[tierId] ?? 0;
+  if (tierId === 'T3' && typeof context.lensCount === 'number' && context.lensCount > 1) {
+    // Each additional lens beyond 1 adds ~50% of base cost
+    return base + (base * 0.5 * (context.lensCount - 1));
+  }
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Step → tier classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Map of step IDs to their tier.
+ * Step IDs come from .stratum.yaml pipeline specs.
+ */
+const STEP_TIER_MAP = {
+  // T0: schema validation — happens implicitly via Stratum output_contract
+  output_contract: 'T0',
+  schema_check: 'T0',
+  validate: 'T0',
+
+  // T1: lint / format
+  lint: 'T1',
+  format: 'T1',
+  typecheck: 'T1',
+
+  // T2: test suite
+  run_tests: 'T2',
+  coverage: 'T2',
+  coverage_check: 'T2',
+  test: 'T2',
+
+  // T3: LLM review (Claude multi-lens)
+  review: 'T3',
+  parallel_review: 'T3',
+  triage: 'T3',
+  merge: 'T3',
+
+  // T4: cross-model review (Codex)
+  codex_review: 'T4',
+  cross_model: 'T4',
+  cross_model_review: 'T4',
+};
+
+/**
+ * Classify a pipeline step ID as a tier.
+ *
+ * @param {string} stepId  Step ID from the pipeline spec
+ * @returns {string|null}  Tier ID (e.g. 'T3') or null if unmapped
+ */
+export function classifyStepAsTier(stepId) {
+  if (!stepId || typeof stepId !== 'string') return null;
+  return STEP_TIER_MAP[stepId] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Tiered evaluator with short-circuit
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate tier results and short-circuit on the first failure.
+ *
+ * @param {object} tierResults  Map of tier IDs to pass/fail booleans or null (not run).
+ *                              Example: { T0: true, T1: true, T2: false, T3: null, T4: null }
+ * @param {object} [costContext]  Context for cost estimation (e.g. { lensCount: 3 })
+ * @returns {{
+ *   passed: boolean,
+ *   tierThatFailed: string|null,
+ *   tiersRun: string[],
+ *   tiersSkipped: string[],
+ *   costSaved: number
+ * }}
+ */
+export function evaluateTiers(tierResults, costContext = {}) {
+  // Sort tiers by their canonical order
+  const orderedTiers = GATE_TIERS.map(t => t.id);
+
+  const tiersRun = [];
+  const tiersSkipped = [];
+  let tierThatFailed = null;
+  let shortCircuiting = false;
+
+  for (const tierId of orderedTiers) {
+    const result = tierResults[tierId];
+
+    if (shortCircuiting || result === null || result === undefined) {
+      // Either we already failed, or this tier was never run
+      if (shortCircuiting) {
+        tiersSkipped.push(tierId);
+      }
+      // null/undefined = not run, not explicitly skipped — don't count either way
+      continue;
+    }
+
+    tiersRun.push(tierId);
+
+    if (result === false) {
+      tierThatFailed = tierId;
+      shortCircuiting = true;
+    }
+  }
+
+  // Cost saved = sum of estimated costs for skipped tiers
+  const costSaved = tiersSkipped.reduce(
+    (sum, tierId) => sum + estimateTierCost(tierId, costContext),
+    0
+  );
+
+  return {
+    passed: tierThatFailed === null,
+    tierThatFailed,
+    tiersRun,
+    tiersSkipped,
+    costSaved,
+  };
+}

package/lib/health-history.js

@@ -0,0 +1,119 @@
+/**
+ * health-history.js — COMP-HEALTH: Score history persistence (item 120).
+ *
+ * Appends health score records to .compose/data/health-scores.json.
+ * Provides read and trend APIs for UI and gate integration.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Path to health-scores.json for a given project root.
+ * @param {string} cwd  Project root (must contain .compose/)
+ * @returns {string}
+ */
+function historyPath(cwd) {
+  return join(cwd, '.compose', 'data', 'health-scores.json');
+}
+
+/**
+ * Load the full history array from disk. Returns [] on missing/corrupt file.
+ * @param {string} cwd
+ * @returns {Array<object>}
+ */
+function _load(cwd) {
+  const p = historyPath(cwd);
+  if (!existsSync(p)) return [];
+  try {
+    const raw = readFileSync(p, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Persist the full history array to disk (atomic-ish via direct write).
+ * @param {string} cwd
+ * @param {Array<object>} entries
+ */
+function _save(cwd, entries) {
+  const p = historyPath(cwd);
+  mkdirSync(join(cwd, '.compose', 'data'), { recursive: true });
+  writeFileSync(p, JSON.stringify(entries, null, 2), 'utf-8');
+}
+
+/**
+ * Record a health score entry for a feature.
+ *
+ * @param {string} cwd
+ * @param {object} entry
+ * @param {string} entry.featureCode    Feature code (e.g. 'FEAT-1')
+ * @param {string} [entry.phase]        Build phase at scoring time
+ * @param {number} entry.score          Composite score 0-100
+ * @param {object} entry.breakdown      Per-dimension scores
+ * @param {string} [entry.timestamp]    ISO timestamp (default: now)
+ */
+export function recordScore(cwd, { featureCode, phase = null, score, breakdown = {}, timestamp = null }) {
+  const entries = _load(cwd);
+  entries.push({
+    featureCode,
+    phase,
+    score,
+    breakdown,
+    timestamp: timestamp ?? new Date().toISOString(),
+  });
+  _save(cwd, entries);
+}
+
+/**
+ * Read all history entries for a feature, sorted chronologically (oldest first).
+ *
+ * @param {string} cwd
+ * @param {string} featureCode
+ * @returns {Array<object>}
+ */
+export function readHistory(cwd, featureCode) {
+  const all = _load(cwd);
+  return all
+    .filter(e => e.featureCode === featureCode)
+    .sort((a, b) => {
+      const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+      const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+      return ta - tb;
+    });
+}
+
+/**
+ * Compute the trend for a feature based on its two most recent scores.
+ *
+ * @param {string} cwd
+ * @param {string} featureCode
+ * @returns {{ latest: object|null, previous: object|null, delta: number|null, direction: 'improving'|'declining'|'stable'|null }}
+ */
+export function getTrend(cwd, featureCode) {
+  const history = readHistory(cwd, featureCode);
+  if (history.length === 0) {
+    return { latest: null, previous: null, delta: null, direction: null };
+  }
+  if (history.length === 1) {
+    return { latest: history[0], previous: null, delta: null, direction: null };
+  }
+
+  const latest   = history[history.length - 1];
+  const previous = history[history.length - 2];
+  const delta    = latest.score - previous.score;
+
+  let direction;
+  if (delta > 1) {
+    direction = 'improving';
+  } else if (delta < -1) {
+    direction = 'declining';
+  } else {
+    direction = 'stable';
+  }
+
+  return { latest, previous, delta, direction };
+}

package/lib/health-score.js

@@ -0,0 +1,227 @@
+/**
+ * health-score.js — COMP-HEALTH: Quantified Quality Score for Gates (items 117-120).
+ *
+ * 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
+ *   - Test pass/fail from coverage_check result
+ *   - Contract compliance from Stratum ensure results
+ *   - Doc freshness from lib/staleness.js
+ *   - Plan completion from plan_completion ensure builtin
+ *   - Runtime errors from build_step_done violations
+ */
+
+// ---------------------------------------------------------------------------
+// Dimension definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Default dimension weights. Weights sum to 1.0.
+ * @type {Record<string, {weight: number, name: string}>}
+ */
+export const DIMENSIONS = {
+  test_coverage:      { weight: 0.225, name: 'Test Coverage' },
+  review_findings:    { weight: 0.225, name: 'Review Findings' },
+  contract_compliance:{ weight: 0.135, name: 'Contract Compliance' },
+  runtime_errors:     { weight: 0.135, name: 'Runtime Errors' },
+  doc_freshness:      { weight: 0.09,  name: 'Doc Freshness' },
+  plan_completion:    { weight: 0.09,  name: 'Plan Completion' },
+  debug_discipline:   { weight: 0.10,  name: 'Debug Discipline' },
+};
+
+// ---------------------------------------------------------------------------
+// Per-dimension scorers
+// ---------------------------------------------------------------------------
+
+/**
+ * Score test coverage from a coverage_check result.
+ *
+ * @param {object|null} testResult  Coverage result: { passing, failures }
+ * @returns {number} 0-100
+ */
+export function scoreTestCoverage(testResult) {
+  if (testResult == null) return 50; // neutral — no data
+  // Truthy passing with no failures = full pass
+  if (testResult.passing === true && (!testResult.failures || testResult.failures.length === 0)) {
+    return 100;
+  }
+  // Explicitly failing
+  if (testResult.passing === false) return 0;
+  // Mixed or unknown — treat partial
+  return 50;
+}
+
+/**
+ * Score review findings from a MergedReviewResult.
+ *
+ * Severity breakdown:
+ *   must-fix  → -20 per finding
+ *   should-fix → -5 per finding
+ *   nit        → -1 per finding
+ *
+ * @param {object|null} mergedResult  { 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 ?? [];
+  if (findings.length === 0) return 100;
+
+  let score = 100;
+  for (const f of findings) {
+    const sev = (f.severity ?? '').toLowerCase();
+    if (sev === 'must-fix' || sev === 'must_fix') {
+      score -= 20;
+    } else if (sev === 'should-fix' || sev === 'should_fix') {
+      score -= 5;
+    } else if (sev === 'nit') {
+      score -= 1;
+    }
+  }
+  return Math.max(0, score);
+}
+
+/**
+ * Score contract compliance from Stratum ensure results.
+ * Each failed ensure costs -10 points.
+ *
+ * @param {Array<{passed: boolean}>|null} ensureResults
+ * @returns {number} 0-100 (floored at 0)
+ */
+export function scoreContractCompliance(ensureResults) {
+  if (ensureResults == null || !Array.isArray(ensureResults)) return 50;
+  if (ensureResults.length === 0) return 100;
+
+  const failed = ensureResults.filter(e => !e.passed).length;
+  return Math.max(0, 100 - failed * 10);
+}
+
+/**
+ * Score runtime errors from capability violations or build violations.
+ * Each violation costs -15 points.
+ *
+ * @param {Array<string|object>|null} violations
+ * @returns {number} 0-100 (floored at 0)
+ */
+export function scoreRuntimeErrors(violations) {
+  if (violations == null || !Array.isArray(violations)) return 50;
+  if (violations.length === 0) return 100;
+  return Math.max(0, 100 - violations.length * 15);
+}
+
+/**
+ * Score doc freshness from staleness check results.
+ * Each stale doc costs -20 points.
+ *
+ * @param {Array<{stale: boolean}>|null} stalenessResults
+ * @returns {number} 0-100 (floored at 0)
+ */
+export function scoreDocFreshness(stalenessResults) {
+  if (stalenessResults == null || !Array.isArray(stalenessResults)) return 50;
+  if (stalenessResults.length === 0) return 100;
+
+  const staleCount = stalenessResults.filter(r => r.stale).length;
+  if (staleCount === 0) return 100;
+  return Math.max(0, 100 - staleCount * 20);
+}
+
+/**
+ * Score plan completion from a plan_completion ensure result.
+ * Uses planCompletionPct directly, or 50 if no plan data is available.
+ *
+ * @param {object|null} planResult  { planCompletionPct: number } or null
+ * @returns {number} 0-100
+ */
+export function scorePlanCompletion(planResult) {
+  if (planResult == null) return 50;
+  const pct = planResult.planCompletionPct ?? planResult.completion_pct;
+  if (typeof pct !== 'number') return 50;
+  return Math.max(0, Math.min(100, pct));
+}
+
+/**
+ * Score debug discipline from debug ledger signals.
+ *
+ * Penalty breakdown:
+ *   fix_chain_count  → -15 per chain
+ *   untraced_fixes   → -20 per untraced fix
+ *   escalation_count → -10 per escalation
+ *
+ * @param {object|null} signals  { fix_chain_count, untraced_fixes, escalation_count }
+ * @returns {number} 0-100 (floored at 0)
+ */
+export function scoreDebugDiscipline(signals) {
+  if (signals == null) return 50;
+  let score = 100;
+  score -= (signals.fix_chain_count ?? 0) * 15;
+  score -= (signals.untraced_fixes ?? 0) * 20;
+  score -= (signals.escalation_count ?? 0) * 10;
+  return Math.max(0, score);
+}
+
+// ---------------------------------------------------------------------------
+// Composite scorer
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a composite health score from a set of signals.
+ *
+ * Missing dimensions are scored as 50 (neutral) but their weight is
+ * re-normalized out so they don't artificially lower the score — we only
+ * penalize for data we actually have.
+ *
+ * @param {object} signals   Map of dimension key → raw signal data
+ * @param {object} [weights] Override weights (same shape as DIMENSIONS)
+ * @returns {{ score: number, breakdown: Record<string,number>, missing: string[] }}
+ */
+export function computeCompositeScore(signals = {}, weights = {}) {
+  const dimWeights = { ...DIMENSIONS };
+  // Apply any user-supplied weight overrides
+  for (const [key, w] of Object.entries(weights)) {
+    if (dimWeights[key] != null && typeof w === 'number') {
+      dimWeights[key] = { ...dimWeights[key], weight: w };
+    }
+  }
+
+  const scorers = {
+    test_coverage:       () => scoreTestCoverage(signals.test_coverage),
+    review_findings:     () => scoreReviewFindings(signals.review_findings),
+    contract_compliance: () => scoreContractCompliance(signals.contract_compliance),
+    runtime_errors:      () => scoreRuntimeErrors(signals.runtime_errors),
+    doc_freshness:       () => scoreDocFreshness(signals.doc_freshness),
+    plan_completion:     () => scorePlanCompletion(signals.plan_completion),
+    debug_discipline:    () => scoreDebugDiscipline(signals.debug_discipline),
+  };
+
+  const breakdown = {};
+  const missing = [];
+
+  // Score each dimension. A dimension is "present" if its key is in signals.
+  for (const dim of Object.keys(dimWeights)) {
+    if (Object.prototype.hasOwnProperty.call(signals, dim)) {
+      breakdown[dim] = scorers[dim]();
+    } else {
+      missing.push(dim);
+      // Score neutral — excluded from weight normalization below
+    }
+  }
+
+  const presentDims = Object.keys(breakdown);
+
+  if (presentDims.length === 0) {
+    // No signals at all — return neutral
+    return { score: 50, breakdown: {}, missing };
+  }
+
+  // Re-normalize: sum weights of present dimensions only
+  const totalWeight = presentDims.reduce((s, d) => s + dimWeights[d].weight, 0);
+  const score = presentDims.reduce((s, d) => {
+    return s + (breakdown[d] * dimWeights[d].weight) / totalWeight;
+  }, 0);
+
+  return {
+    score: Math.round(score * 10) / 10, // 1 decimal
+    breakdown,
+    missing,
+  };
+}