godpowers 0.15.0

package/lib/cost-tracker.js

@@ -0,0 +1,325 @@
+/**
+ * Cost Tracker - token + dollar accounting for godpowers runs.
+ *
+ * The model.call event already exists in the vocabulary. This module
+ * adds a typed recorder, per-tier / per-agent / per-model aggregation,
+ * and a savings counter (cache hits = tokens that would have been
+ * spent but weren't).
+ *
+ * Token costs surface in two places:
+ *   1. Real spend: every LLM call records tokens_in / tokens_out / cost_usd
+ *   2. Avoided spend: cache.hit events record savings_tokens / savings_usd
+ *
+ * Public API:
+ *   recordCost(handle, attrs) - emit a cost.recorded event
+ *   recordCacheHit(handle, attrs) - emit a cache.hit event with savings
+ *   recordCacheMiss(handle, attrs) - emit a cache.miss event
+ *   aggregate(projectRoot, runIds?) -> { perTier, perAgent, perModel, totals }
+ *   priceTokens({model, in, out}) -> usd estimate
+ *
+ * Pricing table is approximate, in USD per 1M tokens, May 2026 ballpark.
+ * Overridable via opts.pricing in aggregate().
+ */
+
+const events = require('./events');
+
+const DEFAULT_PRICING = {
+  // Per 1M tokens (input, output). Keep approximate; user can override.
+  'claude-3-5-sonnet':     { in: 3.00,  out: 15.00 },
+  'claude-3-5-haiku':      { in: 0.80,  out: 4.00 },
+  'claude-3-opus':         { in: 15.00, out: 75.00 },
+  'claude-4':              { in: 5.00,  out: 25.00 },     // estimate
+  'gpt-4o':                { in: 2.50,  out: 10.00 },
+  'gpt-4o-mini':           { in: 0.15,  out: 0.60 },
+  'gpt-4-turbo':           { in: 10.00, out: 30.00 },
+  'gpt-5':                 { in: 5.00,  out: 20.00 },     // estimate
+  'gemini-1.5-pro':        { in: 3.50,  out: 10.50 },
+  'gemini-1.5-flash':      { in: 0.075, out: 0.30 },
+  'o1':                    { in: 15.00, out: 60.00 },
+  'o3-mini':               { in: 3.00,  out: 12.00 },
+  // Fallback bucket
+  '_unknown':              { in: 5.00,  out: 15.00 }
+};
+
+/**
+ * Compute USD cost from token counts.
+ */
+function priceTokens({ model, in: inTok, out: outTok, pricing }) {
+  const table = pricing || DEFAULT_PRICING;
+  const p = table[model] || table[normalizeModel(model)] || table._unknown;
+  const inCost  = (inTok || 0)  * p.in  / 1_000_000;
+  const outCost = (outTok || 0) * p.out / 1_000_000;
+  return Number((inCost + outCost).toFixed(6));
+}
+
+function normalizeModel(m) {
+  if (!m) return '_unknown';
+  const s = String(m).toLowerCase();
+  // Order matters: "gemini" contains "mini" as a substring, and "claude" can
+  // contain "o" etc. Check the most specific tokens first.
+  if (s.includes('haiku')) return 'claude-3-5-haiku';
+  if (s.includes('sonnet')) return 'claude-3-5-sonnet';
+  if (s.includes('opus')) return 'claude-3-opus';
+  if (s.includes('flash')) return 'gemini-1.5-flash';
+  if (s.includes('gemini')) return 'gemini-1.5-pro';
+  if (s.includes('claude')) return 'claude-4';
+  if (s.includes('4o-mini') || s.endsWith('-mini')) return 'gpt-4o-mini';
+  if (s.includes('4o')) return 'gpt-4o';
+  if (s.includes('gpt-5') || s === 'gpt5') return 'gpt-5';
+  if (s.includes('gpt-4') || s === 'gpt4') return 'gpt-4-turbo';
+  if (s.includes('o3')) return 'o3-mini';
+  if (s.includes('o1')) return 'o1';
+  return '_unknown';
+}
+
+/**
+ * Record a real cost (spend that happened). The caller has a handle
+ * from events.startRun.
+ *
+ * attrs: {
+ *   model, tokens_in, tokens_out,
+ *   agent?, tier?,
+ *   cost_usd?  (optional explicit override),
+ *   source?    ('live' | 'estimated', default 'estimated')
+ * }
+ *
+ * The `source` field distinguishes real per-call token counts reported
+ * by the AI tool ('live') from heuristic byte-based estimates the
+ * orchestrator computes itself ('estimated'). `/god-cost --strict`
+ * uses this to fail loudly when any record is estimated.
+ */
+function recordCost(handle, attrs) {
+  const source = attrs.source === 'live' ? 'live' : 'estimated';
+  const cost_usd = attrs.cost_usd != null
+    ? attrs.cost_usd
+    : priceTokens({ model: attrs.model, in: attrs.tokens_in, out: attrs.tokens_out, pricing: attrs.pricing });
+  handle.emit({
+    span_id: attrs.span_id || handle.rootSpanId,
+    name: 'cost.recorded',
+    attrs: {
+      model: attrs.model,
+      tokens_in: attrs.tokens_in || 0,
+      tokens_out: attrs.tokens_out || 0,
+      cost_usd,
+      agent: attrs.agent,
+      tier: attrs.tier,
+      source
+    }
+  });
+  return cost_usd;
+}
+
+/**
+ * Canonical entry point for AI tools that have actual per-call token
+ * counts from the provider's API response. Records a 'live' cost.
+ *
+ * attrs: { model, tokens_in, tokens_out, agent?, tier?, cost_usd? }
+ *
+ * Use this rather than recordCost() directly when you have real
+ * usage numbers; the `source: 'live'` tag is what lets /god-cost
+ * --strict trust the totals.
+ */
+function recordModelCall(handle, attrs) {
+  return recordCost(handle, { ...attrs, source: 'live' });
+}
+
+/**
+ * Record a cache hit. Estimates the savings as what the spend would
+ * have been if the agent had been spawned.
+ */
+function recordCacheHit(handle, attrs) {
+  const savings_usd = attrs.savings_usd != null
+    ? attrs.savings_usd
+    : priceTokens({
+        model: attrs.model,
+        in: attrs.would_have_spent_in || 0,
+        out: attrs.would_have_spent_out || 0,
+        pricing: attrs.pricing
+      });
+  handle.emit({
+    span_id: attrs.span_id || handle.rootSpanId,
+    name: 'cache.hit',
+    attrs: {
+      cache_key: attrs.cache_key,
+      agent: attrs.agent,
+      tier: attrs.tier,
+      model: attrs.model,
+      savings_tokens: (attrs.would_have_spent_in || 0) + (attrs.would_have_spent_out || 0),
+      savings_usd
+    }
+  });
+  return savings_usd;
+}
+
+function recordCacheMiss(handle, attrs) {
+  handle.emit({
+    span_id: attrs.span_id || handle.rootSpanId,
+    name: 'cache.miss',
+    attrs: {
+      cache_key: attrs.cache_key,
+      agent: attrs.agent,
+      tier: attrs.tier,
+      reason: attrs.reason || 'no-entry'
+    }
+  });
+}
+
+/**
+ * Aggregate cost events across one or all runs.
+ *
+ * Returns:
+ *   {
+ *     totals: {
+ *       spent_usd, spent_tokens, saved_usd, saved_tokens,
+ *       cache_hits, cache_misses, hit_rate, calls
+ *     },
+ *     perTier: { 'tier-1': {spent_usd, spent_tokens, calls, ...}, ... },
+ *     perAgent: { 'god-pm': {...}, ... },
+ *     perModel: { 'claude-3-5-sonnet': {...}, ... }
+ *   }
+ */
+function aggregate(projectRoot, runIds) {
+  if (!runIds) runIds = events.listRuns(projectRoot);
+  if (!Array.isArray(runIds)) runIds = [runIds];
+
+  const totals = {
+    spent_usd: 0, spent_tokens: 0,
+    saved_usd: 0, saved_tokens: 0,
+    cache_hits: 0, cache_misses: 0, hit_rate: 0,
+    calls: 0,
+    // Split by data source. live = AI tool reported real token counts;
+    // estimated = orchestrator's heuristic byte-based estimate.
+    live_calls: 0, live_usd: 0, live_tokens: 0,
+    estimated_calls: 0, estimated_usd: 0, estimated_tokens: 0
+  };
+  const perTier = {};
+  const perAgent = {};
+  const perModel = {};
+
+  function bump(bucket, key, fields) {
+    if (!bucket[key]) {
+      bucket[key] = { spent_usd: 0, spent_tokens: 0, saved_usd: 0,
+                      saved_tokens: 0, calls: 0, cache_hits: 0 };
+    }
+    for (const [k, v] of Object.entries(fields)) {
+      bucket[key][k] = (bucket[key][k] || 0) + v;
+    }
+  }
+
+  for (const runId of runIds) {
+    for (const e of events.readRun(projectRoot, runId)) {
+      if (e.name === 'cost.recorded') {
+        const a = e.attrs || {};
+        const usd = a.cost_usd || 0;
+        const tok = (a.tokens_in || 0) + (a.tokens_out || 0);
+        const source = a.source === 'live' ? 'live' : 'estimated';
+        totals.spent_usd += usd;
+        totals.spent_tokens += tok;
+        totals.calls += 1;
+        if (source === 'live') {
+          totals.live_calls += 1;
+          totals.live_usd += usd;
+          totals.live_tokens += tok;
+        } else {
+          totals.estimated_calls += 1;
+          totals.estimated_usd += usd;
+          totals.estimated_tokens += tok;
+        }
+        if (a.tier)   bump(perTier,   a.tier,   { spent_usd: usd, spent_tokens: tok, calls: 1 });
+        if (a.agent)  bump(perAgent,  a.agent,  { spent_usd: usd, spent_tokens: tok, calls: 1 });
+        if (a.model)  bump(perModel,  a.model,  { spent_usd: usd, spent_tokens: tok, calls: 1 });
+      } else if (e.name === 'cache.hit') {
+        const a = e.attrs || {};
+        const usd = a.savings_usd || 0;
+        const tok = a.savings_tokens || 0;
+        totals.saved_usd += usd;
+        totals.saved_tokens += tok;
+        totals.cache_hits += 1;
+        if (a.tier)  bump(perTier,  a.tier,  { saved_usd: usd, saved_tokens: tok, cache_hits: 1 });
+        if (a.agent) bump(perAgent, a.agent, { saved_usd: usd, saved_tokens: tok, cache_hits: 1 });
+      } else if (e.name === 'cache.miss') {
+        totals.cache_misses += 1;
+      }
+    }
+  }
+
+  const attempts = totals.cache_hits + totals.cache_misses;
+  totals.hit_rate = attempts > 0 ? totals.cache_hits / attempts : 0;
+  for (const m of ['spent_usd', 'saved_usd', 'live_usd', 'estimated_usd']) {
+    totals[m] = Number(totals[m].toFixed(6));
+  }
+
+  return { totals, perTier, perAgent, perModel };
+}
+
+/**
+ * Check whether every cost.recorded event has source: 'live'.
+ *
+ * Returns { strict: bool, live_calls, estimated_calls, total_calls }.
+ * Used by /god-cost --strict to fail when any record is estimated.
+ */
+function isStrictLive(projectRoot, runIds) {
+  const agg = aggregate(projectRoot, runIds);
+  const t = agg.totals;
+  return {
+    strict: t.calls > 0 && t.estimated_calls === 0,
+    live_calls: t.live_calls,
+    estimated_calls: t.estimated_calls,
+    total_calls: t.calls
+  };
+}
+
+/**
+ * Format an aggregate as a readable report.
+ */
+function formatReport(agg) {
+  const t = agg.totals;
+  const lines = [];
+  lines.push('GODPOWERS COST REPORT');
+  lines.push('');
+  lines.push(`Spent: $${t.spent_usd.toFixed(4)} across ${t.calls} model calls (${t.spent_tokens} tokens)`);
+  if (t.live_calls > 0 || t.estimated_calls > 0) {
+    lines.push(`  Live:      $${t.live_usd.toFixed(4)} (${t.live_calls} calls, ${t.live_tokens} tokens)`);
+    lines.push(`  Estimated: $${t.estimated_usd.toFixed(4)} (${t.estimated_calls} calls, ${t.estimated_tokens} tokens)`);
+  }
+  lines.push(`Saved: $${t.saved_usd.toFixed(4)} via ${t.cache_hits} cache hits (${t.saved_tokens} tokens)`);
+  lines.push(`Cache hit rate: ${(t.hit_rate * 100).toFixed(1)}% (${t.cache_hits}/${t.cache_hits + t.cache_misses})`);
+  lines.push('');
+  if (Object.keys(agg.perTier).length > 0) {
+    lines.push('Per tier:');
+    for (const [k, v] of Object.entries(agg.perTier).sort()) {
+      lines.push(`  ${k}: $${v.spent_usd.toFixed(4)} (${v.calls} calls, ${v.cache_hits} hits, $${v.saved_usd.toFixed(4)} saved)`);
+    }
+    lines.push('');
+  }
+  if (Object.keys(agg.perAgent).length > 0) {
+    lines.push('Per agent (top 10 by spend):');
+    const sorted = Object.entries(agg.perAgent)
+      .sort((a, b) => b[1].spent_usd - a[1].spent_usd)
+      .slice(0, 10);
+    for (const [k, v] of sorted) {
+      lines.push(`  ${k}: $${v.spent_usd.toFixed(4)} (${v.calls} calls)`);
+    }
+    lines.push('');
+  }
+  if (Object.keys(agg.perModel).length > 0) {
+    lines.push('Per model:');
+    for (const [k, v] of Object.entries(agg.perModel).sort()) {
+      lines.push(`  ${k}: $${v.spent_usd.toFixed(4)} (${v.calls} calls)`);
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  recordCost,
+  recordModelCall,
+  recordCacheHit,
+  recordCacheMiss,
+  aggregate,
+  isStrictLive,
+  formatReport,
+  priceTokens,
+  normalizeModel,
+  DEFAULT_PRICING
+};

package/lib/cross-artifact-impact.js

@@ -0,0 +1,162 @@
+/**
+ * Cross-Artifact Impact
+ *
+ * Generalizes the per-pair impact pattern (DESIGN -> code) to
+ * artifact-to-artifact relationships:
+ *   PRD -> ARCH (requirement removal may leave containers over-spec'd)
+ *   ARCH -> DESIGN (container split may need DESIGN component re-binding)
+ *   ARCH -> ROADMAP (container removal may invalidate milestones)
+ *   STACK -> ARCH (dep change may force ADR flip-point review)
+ *   STACK -> DESIGN (UI lib change may force token review)
+ *   PRD -> ROADMAP (requirement change may invalidate milestone gates)
+ *
+ * Public API:
+ *   forArtifactPair(projectRoot, sourceType, oldContent, newContent, targetType, targetContent)
+ *     -> { impacts, severity }
+ *   suggestArtifactReviews(projectRoot, sourceType, oldContent, newContent)
+ *     -> [{ targetType, reason, severity }]
+ */
+
+const impact = require('./impact');
+
+/**
+ * Define which target artifacts may be impacted by a source artifact change.
+ */
+const IMPACT_RULES = {
+  prd: [
+    {
+      target: 'arch',
+      check: (idDiff) => idDiff.removed.length > 0,
+      reason: (idDiff) => `${idDiff.removed.length} PRD requirement(s) removed; ARCH containers may be over-spec'd`,
+      severity: 'warning'
+    },
+    {
+      target: 'roadmap',
+      check: (idDiff) => idDiff.removed.length > 0 || idDiff.added.length > 0,
+      reason: (idDiff) => `PRD requirements changed; ROADMAP milestone gates may need updating`,
+      severity: 'warning'
+    },
+    {
+      target: 'design',
+      check: (idDiff, sectionChanges) => sectionChanges.some(c => c.section && c.section.match(/Target Users|Brand|Register/i)),
+      reason: () => `PRD target users / register changed; DESIGN PRODUCT.md may need re-aligning`,
+      severity: 'info'
+    }
+  ],
+  arch: [
+    {
+      target: 'design',
+      check: (idDiff) => idDiff.removed.some(id => id.startsWith('C-')),
+      reason: (idDiff) => `ARCH container removed; DESIGN components bound to it may need re-binding`,
+      severity: 'warning'
+    },
+    {
+      target: 'roadmap',
+      check: (idDiff) => idDiff.removed.length > 0,
+      reason: () => `ARCH structure changed; ROADMAP milestone gates may reference removed elements`,
+      severity: 'info'
+    }
+  ],
+  stack: [
+    {
+      target: 'arch',
+      check: (idDiff) => idDiff.removed.length > 0 || idDiff.added.length > 0,
+      reason: () => `STACK changes; ADR flip-points may need review`,
+      severity: 'warning'
+    },
+    {
+      target: 'design',
+      check: (idDiff, sectionChanges, oldContent, newContent) => {
+        // Check if a UI framework changed
+        const oldUi = /react|vue|svelte|next|nuxt|angular|solid|qwik|astro|tailwind|shadcn|mui|chakra/i;
+        const newUi = oldUi;
+        const hadUi = oldContent && oldUi.test(oldContent);
+        const hasUi = newContent && newUi.test(newContent);
+        return hadUi !== hasUi || (hadUi && hasUi && oldContent !== newContent);
+      },
+      reason: () => `STACK UI library may have changed; DESIGN tokens may need recomputation`,
+      severity: 'info'
+    }
+  ],
+  design: [
+    {
+      target: 'arch',
+      check: (idDiff) => idDiff.added.some(id => id.startsWith('D-')) || idDiff.removed.some(id => id.startsWith('D-')),
+      reason: () => `DESIGN components changed; ARCH UI surface descriptions may need updating`,
+      severity: 'info'
+    }
+  ],
+  roadmap: [
+    // Roadmap changes are usually informational; rarely break upstream
+  ]
+};
+
+/**
+ * For a given source artifact change, suggest which downstream artifacts
+ * to review.
+ *
+ * Returns: [{ targetType, reason, severity }]
+ */
+function suggestArtifactReviews(projectRoot, sourceType, oldContent, newContent) {
+  const rules = IMPACT_RULES[sourceType] || [];
+  const idDiff = impact.diffIds(sourceType, oldContent, newContent);
+  const results = [];
+
+  // Compute section diff for prose-driven rules
+  const artifactDiff = require('./artifact-diff');
+  const sectionDiffResult = artifactDiff.diffArtifacts(oldContent || '', newContent || '');
+  const sectionChanges = sectionDiffResult.changes || [];
+
+  for (const rule of rules) {
+    let triggered;
+    try {
+      triggered = rule.check(idDiff, sectionChanges, oldContent, newContent);
+    } catch (e) {
+      triggered = false;
+    }
+    if (triggered) {
+      results.push({
+        targetType: rule.target,
+        reason: rule.reason(idDiff, sectionChanges),
+        severity: rule.severity
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Specific pairwise impact: given a source change AND a target artifact
+ * content, report what specifically might need to change in the target.
+ */
+function forArtifactPair(projectRoot, sourceType, oldContent, newContent, targetType, targetContent) {
+  const suggestions = suggestArtifactReviews(projectRoot, sourceType, oldContent, newContent);
+  const matched = suggestions.find(s => s.targetType === targetType);
+  if (!matched) {
+    return { impacts: [], severity: 'info' };
+  }
+
+  // Extract IDs from both source and target
+  const sourceDiff = impact.diffIds(sourceType, oldContent, newContent);
+  const targetIds = impact.extractIds(targetType, targetContent || '');
+
+  // Find target IDs that mention removed source IDs
+  const impacts = [];
+  for (const removed of sourceDiff.removed) {
+    if (targetContent && targetContent.includes(removed)) {
+      impacts.push({
+        kind: 'cross-reference',
+        sourceId: removed,
+        targetReference: 'mentioned in target',
+        message: `Source ${removed} was removed; target ${targetType} still mentions it.`
+      });
+    }
+  }
+  return { impacts, severity: matched.severity, summary: matched.reason };
+}
+
+module.exports = {
+  IMPACT_RULES,
+  suggestArtifactReviews,
+  forArtifactPair
+};

package/lib/cross-repo-linkage.js

@@ -0,0 +1,150 @@
+/**
+ * Cross-Repo Linkage
+ *
+ * Extends the per-repo linkage map (lib/linkage.js) to span multiple
+ * repos in a Mode D suite. IDs are repo-qualified to prevent collisions:
+ *   <repo-name>:<id>      e.g.,  shared-libs:C-auth-service
+ *
+ * Public API:
+ *   qualifyId(repoName, id) -> string
+ *   parseQualifiedId(qid) -> { repo, id } | null
+ *   readForwardSuite(hubPath) -> { 'qualified-id': [files] }
+ *   crossRepoOrphans(hubPath, knownIds) -> [...]
+ *   crossRepoImpact(hubPath, qualifiedId) -> [{ repo, files }]
+ *   collectAllIds(hubPath) -> { id, repo, declared, implemented }[]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const linkage = require('./linkage');
+const detector = require('./multi-repo-detector');
+
+/**
+ * Qualify a stable ID with its repo name.
+ */
+function qualifyId(repoName, id) {
+  return `${repoName}:${id}`;
+}
+
+/**
+ * Parse a qualified ID. Returns null if not qualified.
+ */
+function parseQualifiedId(qid) {
+  if (!qid || typeof qid !== 'string') return null;
+  const idx = qid.indexOf(':');
+  if (idx === -1) return null;
+  return {
+    repo: qid.slice(0, idx),
+    id: qid.slice(idx + 1)
+  };
+}
+
+/**
+ * Read each sibling's forward map and build a qualified map for the suite.
+ */
+function readForwardSuite(hubPath) {
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return {};
+  const out = {};
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+  for (const sib of siblings) {
+    if (!fs.existsSync(sib.path)) continue;
+    const fwd = linkage.readForward(sib.path);
+    for (const [id, files] of Object.entries(fwd)) {
+      const qid = qualifyId(sib.name, id);
+      out[qid] = files.map(f => `${sib.name}/${f}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Find IDs that are declared but have no implementing file across all
+ * repos.
+ *
+ * `knownIds` is a list of qualified IDs (e.g., ['shared:C-auth', 'app:P-MUST-01']).
+ */
+function crossRepoOrphans(hubPath, knownIds) {
+  const fwd = readForwardSuite(hubPath);
+  return knownIds.filter(qid => !fwd[qid] || fwd[qid].length === 0);
+}
+
+/**
+ * Given a qualified ID, find files across the suite that depend on it.
+ * Useful when removing a token from one repo: scans all sibling repos
+ * for usage of the qualified token reference.
+ */
+function crossRepoImpact(hubPath, qualifiedId) {
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return [];
+  const parsed = parseQualifiedId(qualifiedId);
+  if (!parsed) return [];
+
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+
+  const result = [];
+  for (const sib of siblings) {
+    if (!fs.existsSync(sib.path)) continue;
+    const reverse = linkage.readReverse(sib.path);
+    const matches = [];
+    for (const [file, ids] of Object.entries(reverse)) {
+      if (ids.includes(qualifiedId) || ids.includes(parsed.id)) {
+        matches.push(file);
+      }
+    }
+    if (matches.length > 0) {
+      result.push({ repo: sib.name, files: matches });
+    }
+  }
+  return result;
+}
+
+/**
+ * Walk all repos and collect every linked ID with its repo origin.
+ * Returns deduplicated list:
+ *   [{ qualifiedId, repo, id, fileCount }, ...]
+ */
+function collectAllIds(hubPath) {
+  const fwd = readForwardSuite(hubPath);
+  const result = [];
+  for (const [qid, files] of Object.entries(fwd)) {
+    const parsed = parseQualifiedId(qid);
+    if (parsed) {
+      result.push({
+        qualifiedId: qid,
+        repo: parsed.repo,
+        id: parsed.id,
+        fileCount: files.length
+      });
+    }
+  }
+  return result.sort((a, b) => a.qualifiedId.localeCompare(b.qualifiedId));
+}
+
+/**
+ * Compute coverage across the suite: percent of declared IDs that are
+ * implemented in at least one repo.
+ */
+function suiteCoverage(hubPath, knownIds) {
+  if (knownIds.length === 0) return 1;
+  const fwd = readForwardSuite(hubPath);
+  const linked = knownIds.filter(qid => fwd[qid] && fwd[qid].length > 0).length;
+  return linked / knownIds.length;
+}
+
+module.exports = {
+  qualifyId,
+  parseQualifiedId,
+  readForwardSuite,
+  crossRepoOrphans,
+  crossRepoImpact,
+  collectAllIds,
+  suiteCoverage
+};