@nebulacomponents/citable 1.19.0 → 1.21.0

package/src/commands/compareSnapshots.js

@@ -1,63 +1,171 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJson } from '../shared/io.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
+import { normalizeUrlIdentity } from '../crawler/urlIdentity.js';
 
-/**
- * `citable compare-snapshots [runA runB]` — regression comparison between two audit runs.
- * Defaults to the two most recent runs containing findings.json.
- */
-export function compareSnapshots(root, { runA, runB } = {}) {
-  const runsDir = path.join(root, '.citable', 'runs');
-  if (!fs.existsSync(runsDir)) throw new Error('no runs recorded yet');
-  const runs = fs.readdirSync(runsDir)
-    .filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json')))
-    .sort();
-  if (!runA || !runB) {
-    if (runs.length < 2) throw new Error(`need two runs with findings to compare; found ${runs.length}`);
-    runB = runB ?? runs[runs.length - 1];
-    runA = runA ?? runs[runs.length - 2];
+export const COMPARISON_STATES = Object.freeze([
+  'persisted', 'resolved', 'new', 'changed', 'not_comparable', 'not_reobserved', 'indeterminate',
+]);
+
+function normalizeCandidate(value) {
+  if (!value) return null;
+  try { return normalizeUrlIdentity(String(value)); } catch { return String(value); }
+}
+
+/** Keep effective/requested identity distinct; canonical is never fetch identity. */
+export function resourceIdentityFor(findingOrPage) {
+  const subject = findingOrPage?.subject || findingOrPage || {};
+  const identity = subject.urlIdentity || subject.url_identity || {};
+  const ids = new Set([
+    subject.resource_id, identity.resource_id,
+    subject.classification?.resource_id, subject.evaluation?.resource_id,
+    ...(findingOrPage?.evidence_scope?.resource_ids || []),
+  ].filter(Boolean).map(String));
+  const requested = normalizeCandidate(identity.requested?.normalized_url || identity.requested?.url || subject.requested_url);
+  const effective = normalizeCandidate(identity.effective?.normalized_url || identity.effective?.url
+    || subject.effective_url || subject.normalized_url || subject.url || subject.identifier);
+  const canonical = normalizeCandidate(identity.canonical?.normalized_url || identity.canonical?.url || subject.canonical_url);
+  const fallback = new Set([requested, effective, normalizeCandidate(subject.url || subject.identifier)].filter(Boolean));
+  return { resourceIds: ids, requested, effective, canonical, fallbackUrls: fallback };
+}
+
+export function sameResourceIdentity(left, right) {
+  const a = resourceIdentityFor(left); const b = resourceIdentityFor(right);
+  if (a.resourceIds.size && b.resourceIds.size) {
+    return [...a.resourceIds].some((id) => b.resourceIds.has(id));
   }
-  const load = (r) => {
-    const dir = path.join(runsDir, r);
-    if (!fs.existsSync(path.join(dir, 'findings.json'))) throw new Error(`run ${r} has no findings.json`);
-    return {
-      findings: readJson(path.join(dir, 'findings.json')),
-      manifest: readJson(path.join(dir, 'manifest.json')),
-    };
-  };
-  const a = load(runA);
-  const b = load(runB);
-  const changedKeys = (left = {}, right = {}) => [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+  if (a.effective && b.effective) return a.effective === b.effective;
+  if (a.requested && b.requested) return a.requested === b.requested;
+  // URL fallback is allowed only when each side has exactly one candidate.
+  return a.fallbackUrls.size === 1 && b.fallbackUrls.size === 1
+    && [...a.fallbackUrls][0] === [...b.fallbackUrls][0];
+}
+
+function findingKey(finding) {
+  const identity = resourceIdentityFor(finding);
+  const id = identity.resourceIds.size ? [...identity.resourceIds].sort().join(',')
+    : identity.effective || identity.requested || (identity.fallbackUrls.size === 1 ? [...identity.fallbackUrls][0] : JSON.stringify(finding?.subject || {}));
+  return `${finding?.detector_id || ''}|${id}`;
+}
+
+function loadCoverage(dir) {
+  const file = path.join(dir, 'coverage.json');
+  return fs.existsSync(file) ? readJson(file) : null;
+}
+
+function coverageResource(coverage, finding) {
+  if (!Array.isArray(coverage?.resources)) return null;
+  const target = resourceIdentityFor(finding);
+  const byId = coverage.resources.filter((resource) => {
+    const ids = resourceIdentityFor(resource).resourceIds;
+    return [...target.resourceIds].some((id) => ids.has(id));
+  });
+  if (target.resourceIds.size) return byId.length === 1 ? byId[0] : null;
+  const byUrl = coverage.resources.filter((resource) => sameResourceIdentity(finding, resource));
+  return byUrl.length === 1 ? byUrl[0] : null;
+}
+
+export function assessReobservation(finding, coverage) {
+  if (!coverage) return { state: 'not_reobserved', reason: 'comparison_run_has_no_coverage_artifact' };
+  const resource = coverageResource(coverage, finding);
+  if (!resource) return { state: 'not_reobserved', reason: 'resource_not_reobserved_in_comparison_run' };
+  if (['failed', 'indeterminate', 'unvisited', 'valid_but_unevaluated'].includes(resource.state)) {
+    return { state: resource.state === 'indeterminate' ? 'indeterminate' : 'not_reobserved', reason: `resource_state_${resource.state}`, resource };
+  }
+  if (resource.state !== 'evaluated') return { state: 'not_reobserved', reason: `resource_state_${resource.state || 'unknown'}`, resource };
+  if (finding?.evidence_scope?.requirement === 'exhaustive_requested_scope' && coverage.coverage_status !== 'complete') {
+    return { state: 'indeterminate', reason: 'exhaustive_scope_coverage_incomplete', resource };
+  }
+  return { state: 'resolved', reason: 'resource_reobserved_with_sufficient_coverage', resource };
+}
+
+function changedKeys(left = {}, right = {}) {
+  return [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+}
+
+function comparabilityFor(a, b) {
   const changeDimensions = {
     resource_changed: changedKeys(a.manifest.input_hashes, b.manifest.input_hashes),
     evidence_artifacts_changed: changedKeys(a.manifest.output_hashes, b.manifest.output_hashes),
     detector_set_changed: JSON.stringify(a.manifest.detectors_run) !== JSON.stringify(b.manifest.detectors_run),
     configuration_changed: a.manifest.configuration_hash !== b.manifest.configuration_hash,
-    observation_method_changed: a.manifest.command !== b.manifest.command || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv) || a.manifest.target?.kind !== b.manifest.target?.kind,
+    observation_method_changed: a.manifest.command !== b.manifest.command
+      || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv)
+      || a.manifest.target?.kind !== b.manifest.target?.kind,
     tool_changed: a.manifest.tool_version !== b.manifest.tool_version,
     external_system_may_have_changed: a.manifest.target?.kind === 'url' || b.manifest.target?.kind === 'url',
   };
-  const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
-  const aKeys = new Map(a.findings.map((f) => [key(f), f]));
-  const bKeys = new Map(b.findings.map((f) => [key(f), f]));
-  const regressions = [...bKeys.entries()].filter(([k]) => !aKeys.has(k)).map(([, f]) => f);
-  const resolved = [...aKeys.entries()].filter(([k]) => !bKeys.has(k)).map(([, f]) => f);
-  const persisting = [...bKeys.entries()].filter(([k]) => aKeys.has(k)).map(([, f]) => f);
   return {
-    runA, runB,
-    baseline_timestamp: a.manifest.timestamp,
-    comparison_timestamp: b.manifest.timestamp,
-    regressions, resolved, persisting,
-    comparability: {
-      comparable: !changeDimensions.detector_set_changed && !changeDimensions.configuration_changed && !changeDimensions.observation_method_changed && !changeDimensions.tool_changed,
-      change_dimensions: changeDimensions,
-      limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
-    },
-    summary: {
-      new_findings: regressions.length,
-      resolved_findings: resolved.length,
-      persisting_findings: persisting.length,
-      regression_critical_or_high: regressions.filter((f) => ['critical', 'high'].includes(f.classification.severity)).length,
-    },
+    comparable: !changeDimensions.detector_set_changed
+      && !changeDimensions.configuration_changed
+      && !changeDimensions.observation_method_changed
+      && !changeDimensions.tool_changed,
+    change_dimensions: changeDimensions,
+    limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
+  };
+}
+
+function withState(finding, state, reason, extra = {}) {
+  return { ...finding, comparison_state: state, comparison_provenance: { reason, ...extra } };
+}
+
+/** Compare findings only after checking that their responsible resource was reobserved. */
+export function compareSnapshots(root, { runA, runB } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runsDir)) throw new Error('no runs recorded yet');
+  const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort();
+  if (!runA || !runB) {
+    if (runs.length < 2) throw new Error(`need two runs with findings to compare; found ${runs.length}`);
+    runB = runB ?? runs[runs.length - 1];
+    runA = runA ?? runs[runs.length - 2];
+  }
+  const load = (runId) => {
+    const dir = path.join(runsDir, runId);
+    if (!fs.existsSync(path.join(dir, 'findings.json'))) throw new Error(`run ${runId} has no findings.json`);
+    const loaded = loadVerifiedRun(dir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    return { findings: loaded.findings, manifest: loaded.manifest, coverage: loaded.coverage };
+  };
+  const a = load(runA); const b = load(runB);
+  const comparability = comparabilityFor(a, b);
+  const aFindings = a.findings;
+  const bFindings = b.findings;
+  const matchedA = new Set();
+  const result = {
+    runA, runB, baseline_timestamp: a.manifest.timestamp, comparison_timestamp: b.manifest.timestamp,
+    regressions: [], resolved: [], persisting: [], new: [], changed: [], not_comparable: [], not_reobserved: [], indeterminate: [],
+    comparability,
+  };
+  for (const finding of bFindings) {
+    const priorIndex = aFindings.findIndex((candidate, index) => !matchedA.has(index)
+      && candidate.detector_id === finding.detector_id && sameResourceIdentity(candidate, finding));
+    const prior = priorIndex >= 0 ? aFindings[priorIndex] : null;
+    if (priorIndex >= 0) matchedA.add(priorIndex);
+    if (!prior) {
+      const item = withState(finding, 'new', 'finding_not_present_in_baseline');
+      result.new.push(item); result.regressions.push(item); continue;
+    }
+    if (!comparability.comparable) result.not_comparable.push(withState(finding, 'not_comparable', 'run_envelopes_not_comparable'));
+    else if (JSON.stringify(prior.observation) !== JSON.stringify(finding.observation)) result.changed.push(withState(finding, 'changed', 'finding_observation_changed'));
+    else result.persisting.push(withState(finding, 'persisted', 'finding_observation_persisted'));
+  }
+  for (let index = 0; index < aFindings.length; index += 1) {
+    const finding = aFindings[index];
+    if (matchedA.has(index)) continue;
+    if (!comparability.comparable) { result.not_comparable.push(withState(finding, 'not_comparable', 'run_envelopes_not_comparable')); continue; }
+    const state = assessReobservation(finding, b.coverage);
+    const item = withState(finding, state.state, state.reason, {
+      resource: state.resource?.normalized_url || null, comparison_coverage_status: b.coverage?.coverage_status || 'not_available',
+    });
+    if (state.state === 'resolved') result.resolved.push(item);
+    else if (state.state === 'indeterminate') result.indeterminate.push(item);
+    else result.not_reobserved.push(item);
+  }
+  result.summary = {
+    new_findings: result.new.length, changed_findings: result.changed.length, resolved_findings: result.resolved.length,
+    persisting_findings: result.persisting.length, not_comparable_findings: result.not_comparable.length,
+    not_reobserved_findings: result.not_reobserved.length, indeterminate_findings: result.indeterminate.length,
+    regression_critical_or_high: result.regressions.filter((f) => ['critical', 'high'].includes(f.classification?.severity)).length,
   };
+  return result;
 }

package/src/commands/connect.js

@@ -79,16 +79,37 @@ export async function syncConnection(root, { connectionId, startDate, endDate, a
     }
     throw error;
   }
+  // Connector collection may preserve a partial result even when the provider
+  // reports an authorization/quota state. Keep the result available to direct
+  // connector callers, while retaining the command's legacy state transition.
+  if (result.connectorError?.connectorState) {
+    const error = result.connectorError;
+    const failed = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: error.connectorState, limitations: [...(result.collection?.errors || []), 'Connector synchronization did not complete; inspect collection errors.'] } : item) };
+    saveRegistry(root, 'connections', failed);
+    throw error;
+  }
+  const collection = result.collection || {
+    schema_version: 1,
+    items: result.rows,
+    pagination_state: { pages_requested: 1, pages_retrieved: 1 },
+    provider_reported_total: null,
+    retrieved_total: result.rows.length,
+    coverage_status: 'indeterminate',
+    continuation_state: null,
+    limitations: ['Connector did not provide a collection contract.'],
+    errors: [],
+  };
+  const collectionLimitations = [...collection.limitations, ...collection.errors];
   const observations = result.rows.map((row) => envelope('metric', {
     metric_id: row.metric.metric_id, provider: connector.provider, external_name: row.metric.external_name,
     value: Number(row.value), unit: row.metric.unit === 'custom' ? row.metric.custom_unit : row.metric.unit,
     aggregation: row.metric.aggregation, observed_at: row.observed_at, period_start: row.observed_at,
     period_end: row.observed_at, dimensions: row.dimensions,
-  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...result.limitations] }));
+  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...collectionLimitations] }));
   const run = observationRun(root, 'connect sync', loaded.connection.property_id, observations);
-  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: result.limitations } : item) };
+  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: ['truncated', 'indeterminate'].includes(collection.coverage_status) ? 'partial' : 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: collectionLimitations } : item) };
   saveRegistry(root, 'connections', updated);
-  return { ...run, connection_id: connectionId, provider: connector.provider };
+  return { ...run, connection_id: connectionId, provider: connector.provider, collection };
 }
 
 export async function readCmsContent(root, { connectionId, targetId, accessToken, env, fetchImpl } = {}) {
@@ -119,4 +140,3 @@ export async function applyCmsRemediation(root, { connectionId, input, write = f
 
 export { submitIndexNow, verifyHostKey, buildIndexNowPayload, normalizeHost, parseUrlsInput } from '../connectors/indexnow.js';
 export { collectMcpEvidence } from '../connectors/mcp/pilot.js';
-

package/src/commands/context.js

@@ -4,8 +4,44 @@ import { readYaml, readJson, sha256, parseRefDate } from '../shared/io.js';
 import { loadRegistries } from '../registries/index.js';
 import { buildSiteFromDir, buildSiteFromUrl } from '../extractor/site.js';
 
+const AUDIT_BUDGET_DEFAULTS = Object.freeze({ maxPages: 500, timeBudgetSeconds: 1800 });
+
+function validateBudget(value, name, maximum) {
+  if (!Number.isInteger(value) || value < 1 || value > maximum) {
+    throw new Error(`${name} must be an integer from 1 to ${maximum}; received ${String(value)}`);
+  }
+  return value;
+}
+
+/** Resolve bounded network collection budgets: command options > config > safe defaults. */
+export function resolveAuditBudgets(config = {}, options = {}) {
+  const configured = config.audit ?? {};
+  const maxPagesFromOptions = options.maxPages !== undefined;
+  const timeBudgetFromOptions = options.timeBudgetSeconds !== undefined;
+  const maxPages = maxPagesFromOptions
+    ? options.maxPages
+    : configured.max_pages !== undefined ? configured.max_pages : AUDIT_BUDGET_DEFAULTS.maxPages;
+  const timeBudgetSeconds = timeBudgetFromOptions
+    ? options.timeBudgetSeconds
+    : configured.time_budget_seconds !== undefined
+      ? configured.time_budget_seconds
+      : AUDIT_BUDGET_DEFAULTS.timeBudgetSeconds;
+
+  return {
+    maxPages: validateBudget(maxPages, maxPagesFromOptions ? '--max-pages' : 'audit.max_pages', 10_000),
+    timeBudgetSeconds: validateBudget(
+      timeBudgetSeconds,
+      timeBudgetFromOptions ? '--time-budget-seconds' : 'audit.time_budget_seconds',
+      86_400,
+    ),
+  };
+}
+
 /** Assemble the shared execution context used by audit-family commands. */
-export async function buildContext(root, { target, baseUrl, refDate, viewport = null } = {}) {
+export async function buildContext(root, {
+  target, baseUrl, refDate, viewport = null,
+  maxPages, timeBudgetSeconds, fetcher, concurrency = 1,
+} = {}) {
   const warnings = [];
   const configFile = path.join(root, '.citable', 'config.yaml');
   const config = fs.existsSync(configFile) ? readYaml(configFile) : { version: 1 };
@@ -13,10 +49,12 @@ export async function buildContext(root, { target, baseUrl, refDate, viewport =
   warnings.push(...problems);
 
   let site = null;
+  let auditBudgets = null;
   const resolvedBase = baseUrl ?? config.site?.base_url ?? 'https://example.test';
   if (target) {
     if (/^https?:\/\//.test(target)) {
-      site = await buildSiteFromUrl(target);
+      auditBudgets = resolveAuditBudgets(config, { maxPages, timeBudgetSeconds });
+      site = await buildSiteFromUrl(target, { ...auditBudgets, fetcher, concurrency });
     } else if (fs.existsSync(target)) {
       site = buildSiteFromDir(target, { baseUrl: resolvedBase });
     } else {
@@ -70,6 +108,7 @@ export async function buildContext(root, { target, baseUrl, refDate, viewport =
     promptResults: promptResults.length ? promptResults : null,
     observations: observations.length ? observations : null,
     snapshots,
+    auditBudgets,
     refDate: parseRefDate(refDate),
     viewport,
     hashPage: (p) => sha256(p.text),

package/src/commands/croSuite.js

@@ -9,6 +9,7 @@ import { analyzeBehavioralTelemetry } from '../analysis/behavioral.js';
 import { generateExperimentBacklog, formatBacklogMarkdown } from './croBacklog.js';
 import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
 import { buildCroRoadmap, formatCroRoadmapMarkdown } from '../analysis/croRoadmap.js';
+import { downstreamEnvelope, completeLocalCoverage } from '../evidence/downstream.js';
 
 /**
  * Full End-to-End CRO Intelligence Suite Audit
@@ -22,6 +23,8 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
   const { findings } = runDetectors(croDetectors, ctx);
 
   const pages = indexTargets(ctx);
+  const coverage = ctx.coverage || (pages.length > 0 ? completeLocalCoverage(pages, ctx.site.baseUrl) : null);
+  const evidence = downstreamEnvelope(coverage);
 
   // 2. Above-the-fold clarity, trust, cognitive load, offer architecture per page
   const auditedPages = pages.map((page) => auditPageCro(page, ctx));
@@ -33,21 +36,29 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
   });
   const targetGroup = commercialPages.length > 0 ? commercialPages : auditedPages;
 
-  const avgAtfClarity = targetGroup.length > 0
+  const avgAtfClarity = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.atf_clarity.score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
-  const avgTrustScore = targetGroup.length > 0
+  const avgTrustScore = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.trust_and_credibility.score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
-  const avgConversionReadiness = targetGroup.length > 0
+  const avgConversionReadiness = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.conversion_readiness_score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
   // 3. End-to-end Funnel and Conversion-Path Analysis
   const declaredFunnel = (ctx.registries?.funnels?.entries || []).find((f) => funnelId ? f.funnel_id === funnelId : true) || null;
   const funnelAnalysis = analyzeConversionFunnel(ctx.site.pages, declaredFunnel);
+  const qualify = (value) => evidence.determination_status === 'supported' ? value : null;
+  const qualifiedFunnel = {
+    ...funnelAnalysis,
+    funnel_health_score: qualify(funnelAnalysis.funnel_health_score),
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   // 4. Behavioral Evidence Analysis (if telemetry file provided)
   let behavioralAnalysis = null;
@@ -65,9 +76,26 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
 
   // 5. Experiment Backlog with Falsifiable Hypotheses
   const experimentBacklog = generateExperimentBacklog(findings);
+  const qualifiedExperimentBacklog = {
+    ...experimentBacklog,
+    total_experiments: qualify(experimentBacklog.total_experiments),
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   // 6. Impact / Effort / Confidence (ICE) Prioritization Matrix
   const iceMatrix = buildIceMatrix(findings, { type: 'findings' });
+  const qualifiedIceMatrix = {
+    ...iceMatrix,
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+    summary: {
+      ...iceMatrix.summary,
+      quick_wins_count: qualify(iceMatrix.summary.quick_wins_count),
+    },
+  };
 
   // 7. 30 / 90 / 180-Day CRO Strategic Roadmap tied to Measurable Conversion Outcomes
   const targetDomain = ctx.site.baseUrl ? new URL(ctx.site.baseUrl).hostname : 'target-site';
@@ -75,26 +103,36 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
     findings,
     targetDomain,
   });
+  const qualifiedRoadmap = {
+    ...croRoadmap,
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   const result = {
     fact_status: 'modeled_cro_evaluation',
     target: ctx.site.baseUrl || target,
     total_pages_audited: pages.length,
+    coverage_status: evidence.coverage_status,
+    determination_status: evidence.determination_status,
+    evidence_scope: evidence.evidence_scope,
+    limitations: evidence.limitations,
     summary: {
       conversion_readiness_score: avgConversionReadiness,
       atf_clarity_score: avgAtfClarity,
       trust_credibility_score: avgTrustScore,
-      funnel_health_score: funnelAnalysis.funnel_health_score,
+      funnel_health_score: qualifiedFunnel.funnel_health_score,
       total_cro_findings: findings.length,
-      planned_experiments: experimentBacklog.total_experiments,
-      quick_wins_count: iceMatrix.summary.quick_wins_count,
+      planned_experiments: qualifiedExperimentBacklog.total_experiments,
+      quick_wins_count: qualifiedIceMatrix.summary.quick_wins_count,
     },
-    funnel_analysis: funnelAnalysis,
+    funnel_analysis: qualifiedFunnel,
     pages: auditedPages,
     behavioral_telemetry: behavioralAnalysis,
-    experiment_backlog: experimentBacklog,
-    ice_matrix: iceMatrix,
-    strategic_roadmap: croRoadmap,
+    experiment_backlog: qualifiedExperimentBacklog,
+    ice_matrix: qualifiedIceMatrix,
+    strategic_roadmap: qualifiedRoadmap,
     findings: findings.map((f) => ({
       detector_id: f.detector_id,
       severity: f.classification.severity,

package/src/commands/delivery.js

@@ -6,6 +6,7 @@ import { compareSnapshots } from './compareSnapshots.js';
 import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
 import { loadRegistries } from '../registries/index.js';
 import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
 
@@ -114,12 +115,11 @@ function annotationLevel(severity) {
 export function projectGithub(root, { runId } = {}) {
   if (!runId) throw new Error('projection requires a source run id');
   const runDir = path.join(root, '.citable', 'runs', runId);
-  const findingsFile = path.join(runDir, 'findings.json');
-  const manifestFile = path.join(runDir, 'manifest.json');
-  if (!fs.existsSync(findingsFile) || !fs.existsSync(manifestFile)) throw new Error(`run ${runId} is missing findings or manifest evidence`);
-  const findingsBytes = fs.readFileSync(findingsFile);
-  const manifestBytes = fs.readFileSync(manifestFile);
-  const annotations = JSON.parse(findingsBytes).map((finding) => ({
+  const loaded = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const findingsHash = loaded.artifactHashes?.['findings.json'];
+  const manifestHash = loaded.artifactHashes?.['manifest.json'];
+  if (!findingsHash || !manifestHash) throw new Error(`run ${runId} has no loader-verified findings or manifest hash`);
+  const annotations = loaded.findings.map((finding) => ({
     level: annotationLevel(finding.classification.severity),
     title: `${finding.detector_id}: ${finding.classification.severity}`,
     message: finding.observation.summary,
@@ -127,7 +127,7 @@ export function projectGithub(root, { runId } = {}) {
     line: finding.subject.source_location ? Number(String(finding.subject.source_location).match(/\d+/)?.[0]) || null : null,
     finding_id: finding.finding_id,
   }));
-  const projection = { source_run_id: runId, source_manifest_hash: sha256(manifestBytes), source_findings_hash: sha256(findingsBytes), generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
+  const projection = { source_run_id: runId, source_manifest_hash: manifestHash, source_findings_hash: findingsHash, generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
   const dir = path.join(root, '.citable', 'projections', 'github', runId);
   writeJson(path.join(dir, 'annotations.json'), projection);
   return { ...projection, dir };

package/src/commands/governance.js

@@ -1,8 +1,8 @@
-import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { createRun } from '../evidence/run.js';
 import { loadRegistries, checkReferentialIntegrity } from '../registries/index.js';
-import { readJson, sha256, parseRefDate } from '../shared/io.js';
+import { sha256, parseRefDate } from '../shared/io.js';
 
 function recordHash(value) {
   return sha256(JSON.stringify(value));
@@ -79,8 +79,8 @@ export function validateGovernance(root, { refDate } = {}) {
   const evidence = new Map(registries.evidence.entries.map((item) => [item.evidence_id, item]));
   const activeByFinding = new Map();
   for (const exception of registries.exceptions.entries) {
-    const file = path.join(root, '.citable', 'runs', exception.source_run_id, 'findings.json');
-    const findings = new Map(fs.existsSync(file) ? readJson(file).map((item) => [item.finding_id, item]) : []);
+    const runDir = path.join(root, '.citable', 'runs', exception.source_run_id);
+    const findings = new Map(loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.map((item) => [item.finding_id, item]));
     const exceptionIssues = exceptionProblems(exception, policies.get(exception.policy_id), reviewers, findings, evidence, reference);
     problems.push(...exceptionIssues.map((problem) => `exceptions/${exception.exception_id}: ${problem}`));
     if (exceptionIssues.length === 0) {
@@ -98,10 +98,9 @@ export function validateGovernance(root, { refDate } = {}) {
 
 export function evaluateDispositions(root, { runId, refDate } = {}) {
   if (!runId) throw new Error('source run id is required');
-  const findingsFile = path.join(root, '.citable', 'runs', runId, 'findings.json');
-  if (!fs.existsSync(findingsFile)) throw new Error(`source findings not found for run ${runId}`);
-  const sourceBytes = fs.readFileSync(findingsFile);
-  const sourceFindings = JSON.parse(sourceBytes);
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const sourceRun = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const sourceFindings = sourceRun.findings;
   const findings = new Map(sourceFindings.map((item) => [item.finding_id, item]));
   const { registries, problems } = loadRegistries(root);
   const integrity = checkReferentialIntegrity(registries);
@@ -130,8 +129,8 @@ export function evaluateDispositions(root, { runId, refDate } = {}) {
       problems: matches.flatMap((item) => item.problems),
     };
   });
-  const run = createRun(root, { command: 'governance evaluate', argv: [runId], target: { kind: 'registries', location: findingsFile } });
-  run.addInput('source-findings', sourceBytes);
+  const run = createRun(root, { command: 'governance evaluate', argv: [runId], target: { kind: 'registries', location: path.join(runDir, 'findings.json') } });
+  run.manifest.input_hashes['source-findings'] = sourceRun.artifactHashes['findings.json'];
   run.addInput('exceptions', registries.exceptions);
   run.addInput('review-policies', registries.review_policies);
   run.writeArtifact('dispositions.json', dispositions);

package/src/commands/implementationKit.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { readJson, nowIso } from '../shared/io.js';
 import { remediateCommand } from './remediate.js';
 
@@ -76,7 +77,7 @@ export async function exportImplementationKit(root, options = {}) {
   if (!runId || !fs.existsSync(path.join(runDir, 'findings.json'))) {
     throw new Error(`source run not found: .citable/runs/${runId || '(none)'}`);
   }
-  const findings = readJson(path.join(runDir, 'findings.json'));
+  const findings = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
   const matches = findings.filter((f) =>
     (f.detector_id || '').toUpperCase() === String(finding || '').toUpperCase()
     && (!subject || (f.subject?.identifier || f.subject?.url) === subject));

package/src/commands/init.js

@@ -89,7 +89,14 @@ export function init(root, { force = false, seed = null } = {}) {
         package_manager: detected.package_manager,
         build_command: detected.build_commands[0] ?? null, test_command: detected.test_commands[0] ?? null,
       },
-      audit: { index_target_default: true, max_crawl_depth: 4, thin_content_words: 120, fetch_external: false },
+      audit: {
+        index_target_default: true,
+        max_pages: 500,
+        time_budget_seconds: 1800,
+        max_crawl_depth: 4,
+        thin_content_words: 120,
+        fetch_external: false,
+      },
     };
     const { valid, errors } = validateAgainst('config.schema.json', config);
     if (!valid) throw new Error(`generated config invalid: ${errors.join('; ')}`);

package/src/commands/previewCro.js

@@ -167,7 +167,7 @@ export function generateCroPreviewHtml({
     </div>
 
     <div class="findings-list">
-      <h3>Resolved CRO Defects (${findingItems.length})</h3>
+      <h3>Observed CRO Findings (${findingItems.length})</h3>
       ${findingItems.map((f) => `
         <div class="finding-row">
           <span><strong>${f.detector_id}</strong>: ${f.summary}</span>

package/src/commands/prioritize.js

@@ -13,6 +13,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
@@ -96,7 +97,7 @@ function initiativeMatrix(file, root, rest = []) {
   if (runId) {
     const findingsPath = path.join(root, '.citable', 'runs', runId, 'findings.json');
     if (!fs.existsSync(findingsPath)) throw new Error(`run ${runId} findings.json not found`);
-    const findings = JSON.parse(fs.readFileSync(findingsPath, 'utf8'));
+    const findings = loadVerifiedRun(path.dirname(findingsPath), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
     const matrix = buildIceMatrix(findings, { type: 'findings' });
     return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
   }
@@ -106,7 +107,7 @@ function initiativeMatrix(file, root, rest = []) {
   if (fs.existsSync(runsDir)) {
     const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort().reverse();
     if (runs.length > 0 && rest.includes('--findings')) {
-      const findings = JSON.parse(fs.readFileSync(path.join(runsDir, runs[0], 'findings.json'), 'utf8'));
+      const findings = loadVerifiedRun(path.join(runsDir, runs[0]), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
       const matrix = buildIceMatrix(findings, { type: 'findings' });
       return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
     }