@nebulacomponents/citable 1.11.0 → 1.13.0

package/src/commands/observe.js

@@ -8,11 +8,20 @@ import { parse as parseCsv } from 'csv-parse/sync';
 import { crawlerIdentity } from '../observations/crawlerIdentity.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { observeMedia } from '../observations/media.js';
+import { parse as parseHtml } from 'node-html-parser';
+import { verifyManifestIntegrity } from '../release/governance.js';
+import { observeBrowserPlan } from '../observations/browserJourney.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
 const strictDate = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value || '') && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
 
+function visibleHtmlText(html) {
+  const document = parseHtml(String(html || ''));
+  for (const node of document.querySelectorAll('script,style')) node.remove();
+  return document.textContent.replace(/\s+/g, ' ').trim();
+}
+
 function canonicalReview(raw, targetOrigin) {
   const citations = raw.citations || [];
   return citations.map((citation, index) => {
@@ -31,38 +40,61 @@ function canonicalReview(raw, targetOrigin) {
 }
 
 async function observeRender(root, options) {
+  if (options.input) return observeBrowserPlan(root, options);
   if (!options.target || !/^https?:\/\//.test(options.target)) throw new Error('render requires --target <http(s) URL>');
-  let playwright;
-  try { playwright = await import('playwright'); } catch {
-    const item = envelope('render', { url: options.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
-    return observationRun(root, 'observe render', options.target, [item], { incomplete: ['Rendered DOM capture unavailable: install Playwright and a Chromium browser.'] });
+  const profileNames = ['desktop', 'mobile', 'javascript_disabled'];
+  let reused = [], previousRaw = null;
+  if (options.resumeRun) {
+    const previousDir = path.join(root, '.citable', 'runs', options.resumeRun);
+    const observationsDir = path.join(previousDir, 'observations');
+    if (!fs.existsSync(observationsDir)) throw new Error(`resume run ${options.resumeRun} has no observations`);
+    reused = fs.readdirSync(observationsDir).filter((name) => name.endsWith('-render.json')).map((name) => JSON.parse(fs.readFileSync(path.join(observationsDir, name)))).filter((item) => item.state === 'observed' && profileNames.includes(item.data.profile) && item.data.url === options.target && Boolean(item.data.interaction_execution_requested) === Boolean(options.interactions));
+    previousRaw = fs.readFileSync(path.join(previousDir, 'manifest.json'), 'utf8');
+  }
+  let browser = null;
+  let capture = options.captureProfile;
+  if (!capture) {
+    let playwright;
+    try { playwright = await import('playwright'); } catch {
+      const item = envelope('render', { url: options.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
+      return observationRun(root, 'observe render', options.target, [item], { incomplete: ['Rendered DOM capture unavailable: install Playwright and a Chromium browser.'] });
+    }
+    browser = await playwright.chromium.launch({ headless: true });
   }
-  const initial = await fetchUrl(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
-  const browser = await playwright.chromium.launch({ headless: true });
   try {
-    const capture = async (name, viewport, isMobile = false) => {
-      const context = await browser.newContext({ viewport, isMobile });
-      const page = await context.newPage();
-      const failures = [];
-      page.on('requestfailed', (request) => failures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
-      const response = await page.goto(options.target, { waitUntil: 'networkidle', timeout: options.timeout || 30000 });
-      const html = await page.content(), text = await page.locator('body').innerText(), screenshot = await page.screenshot({ fullPage: true });
-      const result = { name, final_url: page.url(), status: response?.status() ?? null, viewport, html, text, screenshot, failed_requests: failures };
-      await context.close();
-      return result;
-    };
-    const desktop = await capture('desktop', { width: 1280, height: 900 });
-    const mobile = await capture('mobile', { width: 390, height: 844 }, true);
-    const initialText = initial.body.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ').replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
-    const data = {
-      url: options.target, initial: { final_url: initial.url, status: initial.status, html_hash: sha256(initial.body), text_hash: sha256(initialText), word_count: words(initialText).length, redirect_chain: initial.redirectChain },
-      desktop: { final_url: desktop.final_url, status: desktop.status, html_hash: sha256(desktop.html), text_hash: sha256(desktop.text), word_count: words(desktop.text).length, failed_requests: desktop.failed_requests },
-      mobile: { final_url: mobile.final_url, status: mobile.status, html_hash: sha256(mobile.html), text_hash: sha256(mobile.text), word_count: words(mobile.text).length, failed_requests: mobile.failed_requests },
-      parity: { initial_to_desktop_word_ratio: words(desktop.text).length ? Number((words(initialText).length / words(desktop.text).length).toFixed(3)) : null, mobile_to_desktop_word_ratio: words(desktop.text).length ? Number((words(mobile.text).length / words(desktop.text).length).toFixed(3)) : null },
-    };
-    const item = envelope('render', data, { method: 'browser', source: 'playwright/chromium', raw: `${initial.body}\n${desktop.html}\n${mobile.html}` });
-    return observationRun(root, 'observe render', options.target, [item], { artifacts: { 'initial/response.html': initial.body, 'rendered/desktop-dom.html': desktop.html, 'rendered/desktop-text.txt': desktop.text, 'rendered/mobile-dom.html': mobile.html, 'rendered/mobile-text.txt': mobile.text, 'screenshots/desktop.png': desktop.screenshot, 'screenshots/mobile.png': mobile.screenshot } });
-  } finally { await browser.close(); }
+    if (!capture) {
+      capture = async (name, viewport, { isMobile = false, javaScriptEnabled = true } = {}) => {
+      const context = await browser.newContext({ viewport, isMobile, javaScriptEnabled });
+      try {
+        const page = await context.newPage();
+        const failures = [];
+        page.on('requestfailed', (request) => failures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+        const response = await page.goto(options.target, { waitUntil: 'networkidle', timeout: options.timeout || 30000 });
+        const discovered = await page.locator('details > summary,[aria-expanded=false],[role=tab][aria-selected=false],button').evaluateAll((nodes) => nodes.map((node) => ({ tag: node.tagName.toLowerCase(), text: (node.textContent || '').trim().slice(0, 120), role: node.getAttribute('role'), expanded: node.getAttribute('aria-expanded') })).filter((item) => item.tag !== 'button' || /load more|show more|view more/i.test(item.text)));
+        const executed = [];
+        if (options.interactions) {
+          const controls = page.locator('details:not([open]) > summary,[aria-expanded=false],[role=tab][aria-selected=false],button');
+          for (let i = 0; i < Math.min(await controls.count(), 20); i++) { const control = controls.nth(i); const label = ((await control.textContent()) || '').trim(); if ((await control.evaluate((node) => node.tagName.toLowerCase())) === 'button' && !/load more|show more|view more/i.test(label)) continue; try { await control.click({ timeout: 2000 }); executed.push(label.slice(0, 120) || `control-${i + 1}`); } catch { executed.push(`failed:${label.slice(0, 100) || i + 1}`); } }
+        }
+        const html = await page.content(), text = await page.locator('body').innerText(), screenshot = await page.screenshot({ fullPage: true });
+        return { name, final_url: page.url(), status: response?.status() ?? null, viewport, javaScriptEnabled, html, text, screenshot, failed_requests: failures, interactions: { discovered, executed } };
+      } finally {
+        await context.close();
+      }
+      };
+    }
+    const initial = await (options.fetchUrl || fetchUrl)(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
+    const initialText = visibleHtmlText(initial.body);
+    const observations = [...reused], artifacts = { 'initial/response.html': initial.body }, incomplete = [];
+    const profiles = [{ name: 'desktop', viewport: { width: 1280, height: 900 } }, { name: 'mobile', viewport: { width: 390, height: 844 }, settings: { isMobile: true } }, { name: 'javascript_disabled', viewport: { width: 1280, height: 900 }, settings: { javaScriptEnabled: false } }];
+    for (const profile of profiles.filter((item) => !reused.some((old) => old.data.profile === item.name))) {
+      try { const result = await capture(profile.name, profile.viewport, profile.settings); const count = words(result.text).length; const data = { url: options.target, profile: profile.name, final_url: result.final_url, status: result.status, viewport: result.viewport, javascript_enabled: result.javaScriptEnabled, interaction_execution_requested: Boolean(options.interactions), html_hash: sha256(result.html), text_hash: sha256(result.text), word_count: count, raw_http_word_ratio: count ? Number((words(initialText).length / count).toFixed(3)) : null, failed_requests: result.failed_requests, interactions: result.interactions }; observations.push(envelope('render', data, { method: 'browser', source: 'playwright/chromium', raw: result.html, limitations: result.interactions.executed.length ? ['Interactions were bounded to disclosure, tab, and load-more-like controls; application-specific journeys remain untested.'] : [] })); artifacts[`rendered/${profile.name}-dom.html`] = result.html; artifacts[`rendered/${profile.name}-text.txt`] = result.text; artifacts[`screenshots/${profile.name}.png`] = result.screenshot; }
+      catch (error) { incomplete.push(`${profile.name} render failed: ${error.message}`); observations.push(envelope('render', { url: options.target, profile: profile.name }, { method: 'browser', source: 'playwright/chromium', state: 'failed', confidence: 'confirmed', raw: `${profile.name}:${error.message}`, limitations: [error.message] })); }
+    }
+    const desktop = observations.find((item) => item.data.profile === 'desktop' && item.state === 'observed'), mobile = observations.find((item) => item.data.profile === 'mobile' && item.state === 'observed');
+    observations.push(envelope('render', { url: options.target, profile: 'parity', raw_http_to_desktop_word_ratio: desktop?.data.raw_http_word_ratio ?? null, mobile_to_desktop_word_ratio: desktop?.data.word_count && mobile?.data.word_count ? Number((mobile.data.word_count / desktop.data.word_count).toFixed(3)) : null, resumed_from_run_id: options.resumeRun || null }, { method: 'static_analysis', source: options.target, state: desktop && mobile ? 'observed' : 'incomplete', confidence: 'high', limitations: desktop && mobile ? [] : ['Desktop/mobile parity is incomplete because one or more profiles failed.'] }));
+    return observationRun(root, 'observe render', options.target, observations, { rawInputs: previousRaw ? { resumed_manifest: previousRaw } : {}, incomplete, warnings: reused.length ? [`${reused.length} successful profile(s) reused from immutable run ${options.resumeRun}; failed, absent, or configuration-mismatched profiles were recollected.`] : options.resumeRun ? [`No compatible successful profiles were reusable from immutable run ${options.resumeRun}; all profiles were recollected.`] : [], artifacts });
+  } finally { if (browser) await browser.close(); }
 }
 
 async function observeIndex(root, options) {
@@ -248,7 +280,75 @@ async function observeConsensus(root, options) {
   return observationRun(root, 'observe consensus', options.target, observations);
 }
 
+const median = (values) => {
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+};
+
+function lighthouseMetrics(lhr) {
+  const audits = lhr.audits || {};
+  const value = (id) => Number.isFinite(audits[id]?.numericValue) ? audits[id].numericValue : null;
+  return {
+    performance_score: Number.isFinite(lhr.categories?.performance?.score) ? lhr.categories.performance.score : null,
+    first_contentful_paint_ms: value('first-contentful-paint'),
+    largest_contentful_paint_ms: value('largest-contentful-paint'),
+    cumulative_layout_shift: value('cumulative-layout-shift'),
+    total_blocking_time_ms: value('total-blocking-time'),
+    speed_index_ms: value('speed-index'),
+  };
+}
+
+async function localLighthouseRunner(target, runIndex, options) {
+  let lighthouse, launcher;
+  try {
+    ({ default: lighthouse } = await import('lighthouse'));
+    launcher = await import('chrome-launcher');
+  } catch {
+    throw new Error('optional lighthouse and chrome-launcher dependencies are not installed');
+  }
+  const chrome = await launcher.launch({ chromeFlags: ['--headless', '--no-sandbox', '--disable-gpu'] });
+  try {
+    const result = await lighthouse(target, { port: chrome.port, output: 'json', logLevel: 'error', formFactor: options.deviceProfile || 'mobile' });
+    return result.lhr;
+  } finally {
+    await chrome.kill();
+  }
+}
+
+async function observeLighthouse(root, options) {
+  if (!/^https?:\/\//.test(options.target || '')) throw new Error('Lighthouse requires --target <http(s) URL>');
+  const repeat = Number.isInteger(options.repeat) && options.repeat >= 1 && options.repeat <= 5 ? options.repeat : 3;
+  const runner = options.lighthouseRunner || localLighthouseRunner;
+  const observations = [], artifacts = {}, incomplete = [];
+  for (let runIndex = 1; runIndex <= repeat; runIndex++) {
+    try {
+      const lhr = await runner(options.target, runIndex, options);
+      const metrics = lighthouseMetrics(lhr);
+      const data = {
+        url: options.target, provider: 'Lighthouse', evidence_type: 'lab', run_index: runIndex, runs_in_series: repeat,
+        lighthouse_version: lhr.lighthouseVersion || null, chrome_user_agent: lhr.userAgent || null, fetched_at: lhr.fetchTime || null,
+        final_url: lhr.finalDisplayedUrl || lhr.finalUrl || options.target,
+        configuration: { form_factor: lhr.configSettings?.formFactor || null, throttling_method: lhr.configSettings?.throttlingMethod || null, screen_emulation: lhr.configSettings?.screenEmulation || null, throttling: lhr.configSettings?.throttling || null },
+        metrics,
+      };
+      observations.push(envelope('performance', data, { method: 'browser', source: 'lighthouse/local', raw: JSON.stringify(lhr), limitations: ['This is controlled lab evidence, not field performance or a guarantee of user experience.'] }));
+      artifacts[`lighthouse/run-${String(runIndex).padStart(2, '0')}.json`] = JSON.stringify(lhr, null, 2);
+    } catch (error) {
+      incomplete.push(`Lighthouse run ${runIndex} failed: ${error.message}`);
+      observations.push(envelope('performance', { url: options.target, provider: 'Lighthouse', evidence_type: 'lab', run_index: runIndex, runs_in_series: repeat }, { method: 'browser', source: 'lighthouse/local', state: 'failed', confidence: 'confirmed', raw: `run-${runIndex}:${error.message}`, limitations: [error.message] }));
+    }
+  }
+  const successful = observations.filter((item) => item.state === 'observed');
+  const metricNames = ['performance_score', 'first_contentful_paint_ms', 'largest_contentful_paint_ms', 'cumulative_layout_shift', 'total_blocking_time_ms', 'speed_index_ms'];
+  const medians = Object.fromEntries(metricNames.map((name) => [name, median(successful.map((item) => item.data.metrics[name]))]));
+  observations.push(envelope('performance', { url: options.target, provider: 'Lighthouse', evidence_type: 'lab_summary', requested_runs: repeat, successful_runs: successful.length, median_metrics: medians }, { method: 'static_analysis', source: 'lighthouse/local', state: successful.length ? 'observed' : 'not_evidenced', confidence: successful.length === repeat ? 'high' : 'low', limitations: ['Medians summarize only successful controlled lab runs; failed runs remain separate evidence.'] }));
+  return observationRun(root, 'observe performance --lighthouse', options.target, observations, { incomplete, artifacts });
+}
+
 async function observePerformance(root, options) {
+  if (options.lighthouse) return observeLighthouse(root, options);
   if (options.input) {
     const input = readInput(options.input);
     const rows = Array.isArray(input.value) ? input.value : [input.value];
@@ -279,6 +379,77 @@ function observeCorroboration(root, options) {
   return observationRun(root, 'observe corroboration', input.file, observations, { rawInputs: { corroboration_export: input.raw } });
 }
 
+async function observeRepresentation(root, options) {
+  const input = readInput(options.input);
+  const manifest = input.value;
+  const integrity = verifyManifestIntegrity(manifest);
+  if (!integrity.ok) throw new Error(`release manifest is invalid: ${integrity.failures.join('; ')}`);
+  if (!options.target) throw new Error('representation observation requires --target <controlled surface URL>');
+  const surface = manifest.controlled_surfaces.find((item) => item.url === options.target || item.surface_id === options.surfaceId);
+  if (!surface) throw new Error('target is not a controlled surface in the release manifest');
+  const expected = manifest.projections.find((item) => item.projection_id === surface.projection_id);
+  if (!expected) throw new Error(`expected projection ${surface.projection_id} is missing`);
+  const collector = options.fetchUrl || fetchUrl;
+  const paths = [
+    { path: 'direct', url: surface.url },
+    { path: 'cache_busted', url: `${surface.url}${surface.url.includes('?') ? '&' : '?'}citable_manifest=${manifest.manifest_hash.slice(0, 16)}` },
+  ];
+  const observations = [];
+  const artifacts = {};
+  const incomplete = [];
+  for (const item of paths) {
+    try {
+      const response = await collector(item.url, { userAgent: options.userAgent || 'CitableRepresentationProbe/1.0', maxRetries: 1 });
+      const responseHash = sha256(response.body);
+      const observedProjectionHash = surface.verification_method === 'exact_response_body'
+        ? responseHash
+        : response.headers?.[surface.verification_header] || null;
+      const representationState = response.status >= 200 && response.status < 300
+        ? !observedProjectionHash ? 'insufficient_evidence' : observedProjectionHash === expected.sha256 ? 'consistent' : 'divergent'
+        : response.status === 403 || response.status === 429 ? 'challenged' : 'failed';
+      const data = {
+        release_id: manifest.release_id,
+        manifest_hash: manifest.manifest_hash,
+        surface_id: surface.surface_id,
+        projection_id: expected.projection_id,
+        retrieval_path: item.path,
+        requested_url: item.url,
+        final_url: response.url,
+        status: response.status,
+        redirect_chain: response.redirectChain || [],
+        headers: response.headers || {},
+        verification_method: surface.verification_method,
+        verification_header: surface.verification_header,
+        expected_projection_hash: expected.sha256,
+        observed_projection_hash: observedProjectionHash,
+        observed_response_hash: responseHash,
+        representation_state: representationState,
+        authority_label: 'external_unverified',
+        gates_release_finalization: false,
+        request_identity: options.userAgent || 'CitableRepresentationProbe/1.0',
+        region: options.region || 'local_unspecified',
+      };
+      observations.push(envelope('representation_drift', data, {
+        method: 'synthetic_fetch', source: item.url, raw: response.body,
+        confidence: 'confirmed',
+        limitations: ['One synthetic retrieval does not represent all caches, indexes, products, accounts, geographies, or users.'],
+        authority: { source_authority: 'unknown', collection_authority: 'synthetic_probe', authenticity_status: 'unverified', representativeness: 'single_observation' },
+      }));
+      artifacts[`representation/${item.path}-response.txt`] = response.body;
+      artifacts[`representation/${item.path}-headers.json`] = response.headers || {};
+    } catch (error) {
+      incomplete.push(`${item.path} representation retrieval failed: ${error.message}`);
+      observations.push(envelope('representation_drift', {
+        release_id: manifest.release_id, manifest_hash: manifest.manifest_hash, surface_id: surface.surface_id,
+        projection_id: expected.projection_id, retrieval_path: item.path, requested_url: item.url,
+        representation_state: 'failed', authority_label: 'external_unverified', gates_release_finalization: false,
+        request_identity: options.userAgent || 'CitableRepresentationProbe/1.0', region: options.region || 'local_unspecified',
+      }, { method: 'synthetic_fetch', source: item.url, state: 'failed', confidence: 'confirmed', raw: error.message, limitations: [error.message], authority: { source_authority: 'unknown', collection_authority: 'synthetic_probe', authenticity_status: 'unverified', representativeness: 'single_observation' } }));
+    }
+  }
+  return observationRun(root, 'observe representation', surface.url, observations, { rawInputs: { release_manifest: input.raw }, incomplete, artifacts });
+}
+
 export async function observe(root, mode, options = {}) {
   switch (mode) {
     case 'render': return observeRender(root, options);
@@ -291,6 +462,7 @@ export async function observe(root, mode, options = {}) {
     case 'performance': return observePerformance(root, options);
     case 'corroboration': return observeCorroboration(root, options);
     case 'media': return observeMedia(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, or media');
+    case 'representation': return observeRepresentation(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, media, or representation');
   }
 }

package/src/commands/outcomes.js

@@ -0,0 +1,113 @@
+/**
+ * outcomes command — Customer Outcomes registry
+ *
+ * Enforces the finding_produced → causal_relationship_established
+ * progression and refuses to conflate activity with validated impact.
+ *
+ * Usage:
+ *   citable outcomes list [--stage <stage>]
+ *   citable outcomes show <outcome_id>
+ *   citable outcomes validate
+ *   citable outcomes summary   — stage distribution summary
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+export const OUTCOME_STAGES = [
+  'finding_produced',
+  'finding_accepted',
+  'finding_remediated',
+  'remediation_validated',
+  'search_result_changed',
+  'answer_engine_changed',
+  'commercial_outcome_changed',
+  'causal_relationship_established',
+];
+
+export async function outcomesCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'customer-outcomes.yaml');
+
+  switch (subcommand) {
+    case 'show':     return outcomeShow(file, rest[0]);
+    case 'validate': return outcomeValidate(file);
+    case 'summary':  return outcomeSummary(file);
+    default:         return outcomeList(file, rest);
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'customer-outcomes');
+}
+
+function outcomeList(file, args) {
+  const data = load(file);
+  const stageFilter = args.find((_, i, a) => a[i-1] === '--stage');
+  let entries = stageFilter
+    ? data.entries.filter(e => e.outcome_stage === stageFilter)
+    : data.entries;
+  return {
+    outcomes: entries.map(e => ({
+      outcome_id:          e.outcome_id,
+      customer:            e.customer,
+      property:            e.property,
+      outcome_stage:       e.outcome_stage,
+      causal_confidence:   e.causal_confidence,
+      customer_confirmed:  e.customer_confirmed,
+      independently_verified: e.independently_verified ?? false,
+    })),
+    total: entries.length,
+  };
+}
+
+function outcomeShow(file, id) {
+  if (!id) return { error: 'outcome_id required' };
+  const data = load(file);
+  const o = data.entries.find(e => e.outcome_id === id);
+  if (!o) return { error: `Outcome not found: ${id}` };
+  return { outcome: o };
+}
+
+function outcomeSummary(file) {
+  const data = load(file);
+  const dist = {};
+  for (const s of OUTCOME_STAGES) dist[s] = 0;
+  for (const e of data.entries) dist[e.outcome_stage] = (dist[e.outcome_stage] ?? 0) + 1;
+  const verified = data.entries.filter(e => e.independently_verified).length;
+  const confirmed = data.entries.filter(e => e.customer_confirmed).length;
+  return {
+    stage_distribution: dist,
+    customer_confirmed: confirmed,
+    independently_verified: verified,
+    total: data.entries.length,
+    warning: dist.finding_produced > 0 && dist.causal_relationship_established === 0
+      ? 'All outcomes at finding_produced stage — no causal relationships established yet'
+      : null,
+  };
+}
+
+function outcomeValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('customer-outcome.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const o of data.entries) {
+    // Cannot claim causal confidence without evidence
+    if (['strong','verified'].includes(o.causal_confidence) && (!o.evidence_package || o.evidence_package.length === 0))
+      problems.push(`${o.outcome_id}: causal_confidence "${o.causal_confidence}" requires evidence_package`);
+    // Cannot mark independently_verified without customer_confirmed first
+    if (o.independently_verified && !o.customer_confirmed)
+      problems.push(`${o.outcome_id}: independently_verified=true but customer_confirmed=false`);
+    // Commercial value requires validated stage
+    if (o.commercial_value && !['commercial_outcome_changed','causal_relationship_established'].includes(o.outcome_stage))
+      problems.push(`${o.outcome_id}: commercial_value set but outcome_stage is "${o.outcome_stage}" — commercial value requires commercial_outcome_changed or causal_relationship_established`);
+    // Publication requires confirmation
+    if (o.publication_permission && !o.customer_confirmed)
+      problems.push(`${o.outcome_id}: publication_permission=true but customer_confirmed=false`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/prioritize.js

@@ -0,0 +1,108 @@
+/**
+ * prioritize command — Initiative Prioritization
+ *
+ * Ranks roadmap and investment choices. Weights must be visible when
+ * weighted scoring is used — no opaque scores.
+ *
+ * Usage:
+ *   citable prioritize [--status proposed|approved]
+ *   citable prioritize show <initiative_id>
+ *   citable prioritize validate
+ *   citable prioritize rank   — ranked list with explicit criteria
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+const SCALE = { none: 0, low: 1, medium: 2, high: 3, critical: 4, validated: 4, transformative: 4, trivial: 0, very_high: 4, negligible: 0, 'n/a': 0 };
+
+export async function prioritizeCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'initiatives.yaml');
+
+  switch (subcommand) {
+    case 'show':     return initiativeShow(file, rest[0]);
+    case 'validate': return initiativeValidate(file);
+    case 'rank':     return initiativeRank(file);
+    case 'list':
+    default: {
+      const statusFilter = rest[rest.indexOf('--status') + 1] ?? null;
+      return initiativeList(file, statusFilter);
+    }
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'initiatives');
+}
+
+function initiativeList(file, statusFilter) {
+  const data = load(file);
+  let entries = statusFilter ? data.entries.filter(i => i.status === statusFilter) : data.entries;
+  return {
+    initiatives: entries.map(i => ({
+      initiative_id:             i.initiative_id,
+      title:                     i.title,
+      customer_demand:           i.customer_demand,
+      revenue_potential:         i.revenue_potential,
+      strategic_differentiation: i.strategic_differentiation,
+      evidence_strength:         i.evidence_strength,
+      engineering_cost:          i.engineering_cost,
+      reversibility:             i.reversibility,
+      status:                    i.status,
+      owner:                     i.owner,
+    })),
+    total: entries.length,
+  };
+}
+
+function initiativeShow(file, id) {
+  if (!id) return { error: 'initiative_id required' };
+  const data = load(file);
+  const i = data.entries.find(e => e.initiative_id === id);
+  if (!i) return { error: `Initiative not found: ${id}` };
+  return { initiative: i };
+}
+
+function initiativeRank(file) {
+  const data = load(file);
+  const scorable = data.entries.filter(i => ['proposed','approved'].includes(i.status));
+
+  // Transparent scoring: benefit - cost, with evidence strength as multiplier
+  const scored = scorable.map(i => {
+    const benefit = (SCALE[i.customer_demand] ?? 0) + (SCALE[i.revenue_potential] ?? 0) + (SCALE[i.strategic_differentiation] ?? 0);
+    const cost    = (SCALE[i.engineering_cost] ?? 0) + (SCALE[i.operating_cost ?? 'none'] ?? 0) + (SCALE[i.legal_risk ?? 'none'] ?? 0);
+    const evidenceMultiplier = { assumption: 0.5, anecdote: 0.6, proxy: 0.7, validated: 0.9, verified: 1.0 }[i.evidence_strength] ?? 0.5;
+    const score   = (benefit - cost) * evidenceMultiplier;
+    return { initiative_id: i.initiative_id, title: i.title, score: Math.round(score * 10) / 10, benefit, cost, evidence_strength: i.evidence_strength, reversibility: i.reversibility, evidence_multiplier: evidenceMultiplier };
+  }).sort((a, b) => b.score - a.score);
+
+  return {
+    ranked: scored,
+    scoring_method: 'transparent: (customer_demand + revenue_potential + strategic_differentiation - engineering_cost - operating_cost - legal_risk) × evidence_multiplier',
+    weights: 'equal weights — override with scoring_weights field per initiative if asymmetric weighting is required',
+    total: scored.length,
+  };
+}
+
+function initiativeValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('initiative.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const i of data.entries) {
+    // Evidence strength required
+    if (i.evidence_strength === 'assumption' && i.revenue_potential === 'transformative')
+      problems.push(`${i.initiative_id}: revenue_potential=transformative with evidence_strength=assumption — requires at least "proxy" evidence`);
+    // One-way decisions need justification
+    if (i.reversibility === 'effectively_one_way' && !i.opportunity_cost)
+      problems.push(`${i.initiative_id}: effectively_one_way initiatives require opportunity_cost`);
+    // Platform dependency documented for platform-dependent initiatives
+    if (!i.platform_dependency && /search.console|bing|openai|google|cloudflare/i.test(i.title))
+      problems.push(`${i.initiative_id}: platform_dependency should be documented for platform-dependent initiatives`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/risk.js

@@ -0,0 +1,104 @@
+/**
+ * risk command — Risk Register
+ *
+ * Usage:
+ *   citable risk list [--board]        List all risks (--board: board-visible only)
+ *   citable risk show <risk_id>
+ *   citable risk validate
+ *   citable risk top                   Top risks by residual_exposure
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+import { dateOnly, parseAsOf } from '../shared/asOf.js';
+
+const EXPOSURE_ORDER = ['low','medium','high','critical'];
+
+export async function riskCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'risks.yaml');
+
+  switch (subcommand) {
+    case 'show':     return riskShow(file, rest[0]);
+    case 'validate': return riskValidate(file, parseAsOf(args));
+    case 'top':      return riskTop(file);
+    case 'list':
+    default:
+      return riskList(file, { boardOnly: rest.includes('--board') });
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'risks');
+}
+
+function riskList(file, { boardOnly = false } = {}) {
+  const data = load(file);
+  let entries = boardOnly ? data.entries.filter(r => r.board_visibility) : data.entries;
+  return {
+    risks: entries.map(r => ({
+      risk_id:          r.risk_id,
+      title:            r.title,
+      category:         r.category,
+      gross_exposure:   r.gross_exposure,
+      residual_exposure:r.residual_exposure,
+      trend:            r.trend,
+      review_date:      r.review_date,
+      board_visibility: r.board_visibility,
+    })),
+    total: entries.length,
+  };
+}
+
+function riskShow(file, id) {
+  if (!id) return { error: 'risk_id required' };
+  const data = load(file);
+  const r = data.entries.find(e => e.risk_id === id);
+  if (!r) return { error: `Risk not found: ${id}` };
+  return { risk: r };
+}
+
+function riskTop(file) {
+  const data = load(file);
+  const sorted = [...data.entries].sort((a, b) =>
+    EXPOSURE_ORDER.indexOf(b.residual_exposure) - EXPOSURE_ORDER.indexOf(a.residual_exposure)
+  );
+  return {
+    top_risks: sorted.slice(0, 10).map(r => ({
+      risk_id:           r.risk_id,
+      title:             r.title,
+      category:          r.category,
+      residual_exposure: r.residual_exposure,
+      trend:             r.trend,
+      control_effectiveness: r.control_effectiveness,
+      trigger_threshold: r.trigger_threshold,
+      response_owner:    r.response_owner,
+    })),
+  };
+}
+
+function riskValidate(file, asOf) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('risk.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const r of data.entries) {
+    // KRIs required for critical/high risks
+    if (['high','critical'].includes(r.residual_exposure) && (!r.key_risk_indicators || r.key_risk_indicators.length === 0))
+      problems.push(`${r.risk_id}: high/critical residual_exposure requires key_risk_indicators`);
+    // Trigger threshold required for board-visible risks
+    if (r.board_visibility && !r.trigger_threshold)
+      problems.push(`${r.risk_id}: board_visibility=true requires trigger_threshold`);
+    // Stale review dates
+    const reviewDate = r.review_date ? new Date(r.review_date) : null;
+    if (reviewDate && reviewDate < asOf)
+      problems.push(`${r.risk_id}: review_date ${r.review_date} is in the past — risk review overdue`);
+    // Controls effectiveness vs gross/residual mismatch
+    if (r.gross_exposure === 'critical' && r.control_effectiveness === 'none' && r.residual_exposure !== 'critical')
+      problems.push(`${r.risk_id}: control_effectiveness=none but residual_exposure < gross_exposure — inconsistent`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length, as_of: dateOnly(asOf) };
+}