@nebulacomponents/citable 1.11.0 → 1.13.0

package/src/commands/executive.js

@@ -0,0 +1,167 @@
+/**
+ * executive command — Chief-of-Staff Router
+ *
+ * Routes reporting and decision requests to the correct specialized skill.
+ * Built last deliberately — orchestration without strong underlying skills
+ * only coordinates weak outputs.
+ *
+ * Routing table:
+ *   quarterly reporting      → board-report
+ *   monthly reporting        → executive-review
+ *   bounded decision         → decision-memo
+ *   material uncertainty     → scenario
+ *   risk request             → risk
+ *   metric dispute           → kpi
+ *   commercial premise       → assumption-audit
+ *   customer value question  → outcomes
+ *   roadmap priority         → prioritize
+ *   competitor change        → competitive-intel
+ *
+ * Controls:
+ *   - Max orchestration depth: 1 (no recursive routing)
+ *   - Circular-call prevention: command registry checked before dispatch
+ *   - Explicit conflict surfacing — conflicts not smoothed over
+ *   - Decision logging to .citable/executive-log.yaml
+ *
+ * Usage:
+ *   citable executive <request>
+ *   citable executive --route <command>   Force a specific route
+ *   citable executive --log              Show recent routing decisions
+ */
+import { contextDir } from '../registries/index.js';
+import { readYaml, writeYaml, nowIso } from '../shared/io.js';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const ROUTES = [
+  { patterns: [/quarterly|board.pack|board.report/i],        command: 'board-report',         reason: 'Quarterly board pack' },
+  { patterns: [/monthly|operating.review|exec.review/i],     command: 'executive-review',     reason: 'Monthly executive operating review' },
+  { patterns: [/decision|decide|approve|memo/i],             command: 'decision-memo',        reason: 'Bounded decision record' },
+  { patterns: [/scenario|war.room|compound.risk|cascade/i],  command: 'scenario',             reason: 'Compound risk scenario' },
+  { patterns: [/risk.register|residual.risk|risk.list/i],    command: 'risk',                 reason: 'Risk register' },
+  { patterns: [/kpi|metric.definition|metric.dispute/i],     command: 'kpi',                  reason: 'KPI architecture' },
+  { patterns: [/assumption|premise|still.valid/i],            command: 'assumption-audit',     reason: 'Assumption validity' },
+  { patterns: [/customer.outcome|customer.value|impact/i],   command: 'outcomes',             reason: 'Customer outcomes' },
+  { patterns: [/variance|miss|why.did.we/i],                 command: 'variance',             reason: 'Variance analysis' },
+  { patterns: [/prioriti|roadmap|what.to.build|rank/i],      command: 'prioritize',           reason: 'Initiative prioritization' },
+  { patterns: [/competitor|competitive|market.change/i],     command: 'competitive-intel',    reason: 'Competitive intelligence' },
+];
+
+const MAX_DEPTH = 1;
+let _callDepth = 0;
+
+export async function executiveCommand(args, root = process.cwd()) {
+  const forceRoute = argVal(args, '--route');
+  const showLog = args.includes('--log');
+
+  if (showLog) return executiveLog(root);
+
+  if (_callDepth >= MAX_DEPTH) {
+    return { error: 'Maximum orchestration depth reached — circular routing prevented' };
+  }
+
+  const request = args.filter(a => !a.startsWith('--')).join(' ');
+
+  const route = forceRoute
+    ? ROUTES.find(r => r.command === forceRoute)
+    : resolveRoute(request);
+
+  if (!route) {
+    return {
+      unresolved: true,
+      request,
+      available_commands: ROUTES.map(r => ({ command: r.command, reason: r.reason })),
+      message: 'Could not determine the appropriate skill. Use --route <command> to force a route, or run the specific command directly.',
+    };
+  }
+
+  // Log the routing decision
+  logDecision(root, { request, routed_to: route.command, reason: route.reason, at: nowIso() });
+
+  _callDepth++;
+  try {
+    // Lazy-import to avoid circular deps — commands are imported at call time
+    const mod = await import(`./${commandToModule(route.command)}.js`);
+    const fn = mod[commandToExport(route.command)];
+    if (!fn) {
+      return { error: `No handler for command: ${route.command}` };
+    }
+    const downstreamArgs = args.filter((arg, index) => arg !== '--route' && args[index - 1] !== '--route');
+    const result = await fn(downstreamArgs, root);
+    return {
+      routed_to: route.command,
+      reason: route.reason,
+      result,
+    };
+  } finally {
+    _callDepth--;
+  }
+}
+
+function resolveRoute(request) {
+  if (!request) return null;
+  for (const route of ROUTES) {
+    if (route.patterns.some(p => p.test(request))) return route;
+  }
+  return null;
+}
+
+function commandToModule(cmd) {
+  const MAP = {
+    'board-report':       'boardReport',
+    'executive-review':   'executiveReview',
+    'decision-memo':      'decisionMemo',
+    'scenario':           'scenario',
+    'risk':               'risk',
+    'kpi':                'kpi',
+    'assumption-audit':   'assumptionAudit',
+    'outcomes':           'outcomes',
+    'variance':           'variance',
+    'prioritize':         'prioritize',
+    'competitive-intel':  'competitiveIntel',
+  };
+  return MAP[cmd] ?? cmd;
+}
+
+function commandToExport(cmd) {
+  const MAP = {
+    'board-report':       'boardReportCommand',
+    'executive-review':   'executiveReviewCommand',
+    'decision-memo':      'decisionMemoCommand',
+    'scenario':           'scenarioCommand',
+    'risk':               'riskCommand',
+    'kpi':                'kpiCommand',
+    'assumption-audit':   'assumptionAuditCommand',
+    'outcomes':           'outcomesCommand',
+    'variance':           'varianceCommand',
+    'prioritize':         'prioritizeCommand',
+    'competitive-intel':  'competitiveIntelCommand',
+  };
+  return MAP[cmd] ?? cmd + 'Command';
+}
+
+function logDecision(root, entry) {
+  const dir = contextDir(root);
+  const logFile = path.join(dir, 'executive-log.yaml');
+  let log = { version: 1, kind: 'executive-log', entries: [] };
+  if (fs.existsSync(logFile)) {
+    try { log = readYaml(logFile) ?? log; } catch {}
+  }
+  log.entries.push(entry);
+  // Keep last 100 entries
+  if (log.entries.length > 100) log.entries = log.entries.slice(-100);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  writeYaml(logFile, { ...log, updated: nowIso() });
+}
+
+function executiveLog(root) {
+  const logFile = path.join(contextDir(root), 'executive-log.yaml');
+  if (!fs.existsSync(logFile)) return { log: [], message: 'No routing decisions logged yet.' };
+  const log = readYaml(logFile) ?? { entries: [] };
+  return { log: (log.entries ?? []).slice(-20) };
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/executiveReview.js

@@ -0,0 +1,206 @@
+/**
+ * executive-review command — Monthly Executive Operating Review
+ *
+ * Generates an evidence-first operating review. Produces an evidence
+ * ledger first, then derives the narrative. Never generates a polished
+ * positive summary when data is absent or ungoverned.
+ *
+ * Four-act invariant (mandatory):
+ *   1. Where management said the company would be
+ *   2. Where it actually is
+ *   3. Why the variance exists
+ *   4. What management is doing about it
+ *
+ * Usage:
+ *   citable executive-review [--period <YYYY-MM>] [--json]
+ */
+import { checkReferentialIntegrity, loadRegistries } from '../registries/index.js';
+import { nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { dateOnly, parseAsOf } from '../shared/asOf.js';
+
+
+/** Filter registry entries to only those that pass schema validation. */
+function validEntries(entries, schemaName) {
+  if (!entries?.length) return [];
+  return entries.filter(e => {
+    const { valid } = validateAgainst(schemaName, { version: 1, kind: schemaName.replace('.schema.json','s'), entries: [e] });
+    return valid;
+  });
+}
+
+function validReferences(entries, kind, idField, problems) {
+  return entries.filter(entry => !problems.some(problem => problem.startsWith(`${kind}/${entry[idField]}:`)));
+}
+
+export async function executiveReviewCommand(args, root = process.cwd()) {
+  const asOf  = parseAsOf(args);
+  const period = argVal(args, '--period') ?? currentPeriod(asOf);
+  const asJson = args.includes('--json');
+
+  const { registries, problems: regProblems } = loadRegistries(root);
+  const refProblems = checkReferentialIntegrity(registries);
+
+  const report = buildReview(registries, period, [...regProblems, ...refProblems], refProblems);
+  report.generated_at = nowIso();
+  report.as_of = dateOnly(asOf);
+
+  return asJson ? report : formatReview(report);
+}
+
+function buildReview(registries, period, regProblems, refProblems) {
+  // Filter to schema-valid and referentially valid governed evidence.
+  const kpis = validReferences(validEntries(registries.kpis?.entries, 'kpi.schema.json'), 'kpis', 'metric_id', refProblems);
+  const validVariances = validReferences(validEntries(registries.variances?.entries, 'variance.schema.json'), 'variances', 'variance_id', refProblems);
+  const variances = validVariances.filter(v => v.period === period);
+  const outcomes = validReferences(validEntries(registries['customer-outcomes']?.entries, 'customer-outcome.schema.json'), 'customer-outcomes', 'outcome_id', refProblems);
+  const risks = validReferences(validEntries(registries.risks?.entries, 'risk.schema.json'), 'risks', 'risk_id', refProblems);
+  const decisions = validReferences(validEntries(registries.decisions?.entries, 'decision.schema.json'), 'decisions', 'decision_id', refProblems);
+
+  const invalidTotal =
+    ((registries.kpis?.entries?.length ?? 0) - kpis.length) +
+    ((registries.variances?.entries?.length ?? 0) - validVariances.length) +
+    ((registries['customer-outcomes']?.entries?.length ?? 0) - outcomes.length) +
+    ((registries.risks?.entries?.length ?? 0) - risks.length) +
+    ((registries.decisions?.entries?.length ?? 0) - decisions.length);
+
+
+  // Evidence ledger — raw facts before narrative
+  const ledger = {
+    period,
+    governed_metrics: kpis.length,
+    variances_this_period: variances.length,
+    material_variances: variances.filter(v => ['material','critical'].includes(v.materiality)).length,
+    customer_outcomes_total: outcomes.length,
+    outcomes_customer_confirmed: outcomes.filter(o => o.customer_confirmed).length,
+    outcomes_causal_established: outcomes.filter(o => o.outcome_stage === 'causal_relationship_established').length,
+    board_visible_risks: risks.filter(r => r.board_visibility).length,
+    critical_risks: risks.filter(r => r.residual_exposure === 'critical').length,
+    deteriorating_risks: risks.filter(r => r.trend === 'deteriorating').length,
+  };
+
+  // Commercial section
+  const commercial = buildSection('commercial', kpis, variances, [
+    'ARR','MRR','bookings','pipeline_coverage','win_rate','sales_cycle','customer_concentration',
+  ]);
+
+  // Customer section
+  const customer = buildSection('customer', kpis, variances, [
+    'active_customers','onboarding_time','renewal_risk','findings_acted_upon','unresolved_escalations',
+  ]);
+
+  // Product section
+  const product = buildSection('product', kpis, variances, [
+    'active_properties','audits_run','completed_valid_audits','installation_success','feature_adoption',
+  ]);
+
+  // Quality section — Citable-specific
+  const quality = buildSection('quality', kpis, variances, [
+    'detector_precision','confirmed_false_positives','known_false_negatives','expired_evidence','stale_registries',
+  ]);
+
+  // Operations section
+  const operations = buildSection('operations', kpis, variances, [
+    'failed_runs','incomplete_evidence_packages','crawler_access_failures','release_regressions',
+  ]);
+
+  // Management section
+  const openDecisions = decisions.filter(d => d.status === 'open');
+  const management = {
+    open_decisions: openDecisions.length,
+    decisions_requiring_action: openDecisions.map(d => ({
+      id: d.decision_id, title: d.title, owner: d.owner, deadline: d.deadline,
+    })),
+  };
+
+  return {
+    report_type: 'executive-operating-review',
+    period,
+    registry_problems: regProblems,
+    invalid_entries_excluded: invalidTotal > 0 ? invalidTotal : undefined,
+    ledger,
+    four_act_required: buildFourActPrompt(variances),
+    sections: { commercial, customer, product, quality, operations, management },
+    ungoverned_warning: ledger.governed_metrics === 0
+      ? 'BLOCKED: No governed KPIs. Register metrics with `citable kpi add` before generating narrative.'
+      : null,
+  };
+}
+
+function buildSection(name, kpis, variances, relevantNames) {
+  const sectionKpis = kpis.filter(k =>
+    relevantNames.some(n => k.metric_id?.toLowerCase().includes(n.toLowerCase()) || k.name?.toLowerCase().includes(n.toLowerCase()))
+  );
+  const sectionVariances = variances.filter(v =>
+    sectionKpis.some(k => k.metric_id === v.metric_id)
+  );
+  return {
+    section: name,
+    governed_metrics: sectionKpis.length,
+    variances: sectionVariances.length,
+    material_variances: sectionVariances.filter(v => ['material','critical'].includes(v.materiality)).length,
+    ungoverned_warning: sectionKpis.length === 0
+      ? `No governed KPIs for ${name} — narrative cannot be generated from ungoverned data`
+      : null,
+  };
+}
+
+function buildFourActPrompt(variances) {
+  if (variances.length === 0) return { status: 'no_variances_this_period' };
+  const material = variances.filter(v => ['material','critical'].includes(v.materiality));
+  return {
+    status: 'required',
+    material_variances: material.length,
+    template: {
+      act_1: 'Where management said the company would be: [state targets and forecasts from KPI registry]',
+      act_2: 'Where it actually is: [state actuals from variance records]',
+      act_3: 'Why the variance exists: [state primary_driver from each material variance — vague causes rejected]',
+      act_4: 'What management is doing about it: [state management_response from each material variance]',
+    },
+  };
+}
+
+function formatReview(report) {
+  const lines = [
+    `# Executive Operating Review — ${report.period}`,
+    `Generated: ${report.generated_at}`,
+    '',
+  ];
+  if (report.ungoverned_warning) {
+    lines.push(`⛔ ${report.ungoverned_warning}`, '');
+  }
+  if (report.registry_problems?.length) {
+    lines.push(`⚠️  Registry problems (${report.registry_problems.length}):`);
+    for (const p of report.registry_problems.slice(0, 5)) lines.push(`   ${p}`);
+    lines.push('');
+  }
+  const l = report.ledger;
+  lines.push(
+    '## Evidence Ledger',
+    `- Governed metrics: ${l.governed_metrics}`,
+    `- Variances this period: ${l.variances_this_period} (${l.material_variances} material)`,
+    `- Customer outcomes: ${l.customer_outcomes_total} (${l.outcomes_customer_confirmed} confirmed, ${l.outcomes_causal_established} causal)`,
+    `- Board-visible risks: ${l.board_visible_risks} (${l.critical_risks} critical, ${l.deteriorating_risks} deteriorating)`,
+    '',
+    '## Four-Act Reporting Requirement',
+  );
+  const fa = report.four_act_required;
+  if (fa.status === 'required') {
+    for (const [act, text] of Object.entries(fa.template)) {
+      lines.push(`**${act.replace('_',' ').toUpperCase()}:** ${text}`);
+    }
+  } else {
+    lines.push('No variances registered for this period.');
+  }
+  return lines.join('\n');
+}
+
+function currentPeriod(asOf) {
+  const d = asOf ?? new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/init.js

@@ -15,6 +15,19 @@ const DEFAULT_CRAWLERS = [
   ['CRAWLER-CLAUDEBOT', 'ClaudeBot', 'Anthropic', 'model_training'],
 ];
 
+function hasSchemaSignal(text) {
+  if (/application\/ld\+json/i.test(text)) return true;
+  for (const match of text.matchAll(/https?:\/\/[^\s"'<>]+/gi)) {
+    try {
+      const hostname = new URL(match[0]).hostname.toLowerCase();
+      if (hostname === 'schema.org' || hostname === 'www.schema.org') return true;
+    } catch {
+      // Ignore malformed URL-like source text during best-effort project discovery.
+    }
+  }
+  return false;
+}
+
 function detectFramework(root) {
   const detected = {
     framework: null, rendering_model: null, package_manager: null,
@@ -47,7 +60,7 @@ function detectFramework(root) {
   for (const f of listFiles(root, (p) => /sitemap.*\.(xml|ts|js|mjs)$/.test(p))) detected.sitemap_sources.push(path.relative(root, f));
   for (const f of listFiles(root, (p) => /\.(html|jsx?|tsx?|astro|vue|svelte)$/.test(p)).slice(0, 400)) {
     const text = fs.readFileSync(f, 'utf8');
-    if (text.includes('application/ld+json') || text.includes('schema.org')) detected.schema_sources.push(path.relative(root, f));
+    if (hasSchemaSignal(text)) detected.schema_sources.push(path.relative(root, f));
     if (/gtag\(|googletagmanager|plausible|posthog|umami|matomo/i.test(text)) detected.analytics.push(path.relative(root, f));
   }
   if (detected.rendering_model === null) unresolved.push('Rendering model could not be determined from manifests.');

package/src/commands/kpi.js

@@ -0,0 +1,86 @@
+/**
+ * kpi command — KPI Architecture registry management
+ *
+ * Usage:
+ *   citable kpi list     List all governed metrics
+ *   citable kpi show <id> Show a single KPI
+ *   citable kpi validate  Validate all KPI records
+ */
+import { loadRegistries, contextDir } from '../registries/index.js';
+import { readYaml, writeYaml, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const REQUIRED_COMPARISON = true; // every KPI must have a comparison basis
+
+export async function kpiCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const dir = contextDir(root);
+  const file = path.join(dir, 'kpis.yaml');
+
+  switch (subcommand) {
+    case 'list': return kpiList(file);
+    case 'show': return kpiShow(file, rest[0]);
+    case 'validate': return kpiValidate(file);
+    case 'add': return { error: '`citable kpi add` is not yet implemented; edit kpis.yaml directly and run `citable kpi validate`' };
+    default:
+      return kpiList(file);
+  }
+}
+
+function loadKpis(file) {
+  if (!fs.existsSync(file)) return { version: 1, kind: 'kpis', entries: [] };
+  return readYaml(file) ?? { version: 1, kind: 'kpis', entries: [] };
+}
+
+function kpiList(file) {
+  const data = loadKpis(file);
+  if (!data.entries.length) return { kpis: [], message: 'No KPIs registered. Edit .citable/kpis.yaml, then run `citable kpi validate`.' };
+  return {
+    kpis: data.entries.map(k => ({
+      metric_id: k.metric_id,
+      name: k.name,
+      owner: k.owner,
+      cadence: k.reporting_cadence,
+      target: k.target ?? 'NOT SET',
+      comparison_required: k.comparison_required ?? REQUIRED_COMPARISON,
+      limitations: (k.known_limitations ?? []).length,
+    })),
+    total: data.entries.length,
+  };
+}
+
+function kpiShow(file, id) {
+  if (!id) return { error: 'metric_id required' };
+  const data = loadKpis(file);
+  const kpi = data.entries.find(k => k.metric_id === id);
+  if (!kpi) return { error: `KPI not found: ${id}` };
+  return { kpi };
+}
+
+function kpiValidate(file) {
+  const data = loadKpis(file);
+  const problems = [];
+  const { valid, errors } = validateAgainst('kpi.schema.json', data);
+  if (!valid) problems.push(...errors);
+  // Citable-specific checks
+  for (const k of data.entries) {
+    if (!k.known_limitations || k.known_limitations.length === 0)
+      problems.push(`${k.metric_id}: known_limitations is empty — every metric must document its measurement constraints`);
+    if (k.comparison_required !== false && !k.comparison_basis)
+      problems.push(`${k.metric_id}: comparison_basis required when comparison_required is true`);
+    if (!k.restatement_policy)
+      problems.push(`${k.metric_id}: restatement_policy missing — how will historical data be corrected?`);
+    // Citable metric distinction checks
+    if (/installs?/i.test(k.name) && !/active/i.test(k.name))
+      problems.push(`${k.metric_id}: "installs" vs "active_installations" must be distinct metrics`);
+    if (/audit/i.test(k.name) && !/valid|complete/i.test(k.executive_definition ?? ''))
+      problems.push(`${k.metric_id}: audits_run vs completed_valid_audits must be distinguished in executive_definition`);
+  }
+  return {
+    valid: problems.length === 0,
+    problems,
+    checked: data.entries.length,
+  };
+}

package/src/commands/monitor.js

@@ -11,6 +11,7 @@ function observations(dir) {
 function key(item) {
   const d = item.data || {};
   if (item.kind === 'citation') return [item.kind, d.provider, d.product_mode, d.prompt_id, d.run_index].join(':');
+  if (item.kind === 'representation_drift') return [item.kind, d.manifest_hash, d.surface_id, d.retrieval_path, d.region, d.request_identity].join(':');
   return [item.kind, d.url || d.citation_url || d.prompt_id || d.timestamp || item.observation_id].join(':');
 }
 
@@ -30,6 +31,14 @@ export function monitor(root, { runA, runB } = {}) {
     if (current.kind === 'index' && previous?.data?.indexed === true && current.data.indexed === false) alerts.push({ severity: 'high', type: 'index_loss', key: k });
     if (current.kind === 'canonical_freshness' && previous?.data?.canonical_consensus === true && current.data.canonical_consensus === false) alerts.push({ severity: 'high', type: 'canonical_regression', key: k });
     if (current.kind === 'citation' && previous?.data?.property_cited === true && current.data.property_cited === false) alerts.push({ severity: 'medium', type: 'citation_presence_change', key: k });
+    if (current.kind === 'representation_drift' && previous) {
+      const from = previous.data.representation_state, to = current.data.representation_state;
+      if (from !== 'divergent' && to === 'divergent') alerts.push({ severity: 'high', type: 'representation_divergence_observed', key: k, previous_state: from, current_state: to, authority: 'external_unverified', gates_release_finalization: false });
+      if (from === 'divergent' && to === 'consistent') {
+        const duration = new Date(current.collected_at) - new Date(previous.collected_at);
+        alerts.push({ severity: 'informational', type: 'representation_convergence_observed', key: k, previous_state: from, current_state: to, observed_interval_ms: Number.isFinite(duration) && duration >= 0 ? duration : null, authority: 'external_unverified', gates_release_finalization: false });
+      }
+    }
   }
   for (const k of before.keys()) if (!after.has(k)) alerts.push({ severity: 'medium', type: 'observation_missing', key: k });
   const result = { generated_at: nowIso(), run_a: a, run_b: b, summary: { alerts: alerts.length, critical_or_high: alerts.filter((x) => ['critical', 'high'].includes(x.severity)).length }, alerts };