@nebulacomponents/citable 1.12.0 → 1.13.0

package/src/artifacts/interchange.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalJson } from '../release/governance.js';
+import { nowIso, readJson, sha256, sha256File, writeJson } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const PACKAGE = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
+const ENVELOPE = 'citable-artifact.json';
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function safeRelativePath(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && !path.isAbsolute(value)
+    && !value.includes('\\')
+    && !value.split('/').includes('..')
+    && !/^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+
+function filesUnder(dir, current = dir, result = []) {
+  for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+    const absolute = path.join(current, entry.name);
+    const relative = path.relative(dir, absolute).split(path.sep).join('/');
+    if (entry.isSymbolicLink()) throw new Error(`artifact package cannot contain symbolic links: ${relative}`);
+    if (entry.isDirectory()) filesUnder(dir, absolute, result);
+    else if (entry.isFile()) result.push(relative);
+    else throw new Error(`artifact package contains unsupported filesystem entry: ${relative}`);
+  }
+  return result.sort();
+}
+
+function validateRunPackage(runDir) {
+  if (!fs.existsSync(runDir) || !fs.statSync(runDir).isDirectory()) throw new Error(`run package not found: ${runDir}`);
+  const manifestFile = path.join(runDir, 'manifest.json');
+  const checksumsFile = path.join(runDir, 'checksums.json');
+  if (!fs.existsSync(manifestFile) || !fs.existsSync(checksumsFile)) throw new Error('run package requires manifest.json and checksums.json');
+  const manifest = readJson(manifestFile);
+  const manifestCheck = validateAgainst('run.schema.json', manifest);
+  if (!manifestCheck.valid) throw new Error(`run manifest invalid: ${manifestCheck.errors.join('; ')}`);
+  const checksums = readJson(checksumsFile);
+  if (!checksums || Array.isArray(checksums) || typeof checksums !== 'object') throw new Error('checksums.json must be an object');
+  const actualFiles = filesUnder(runDir).filter((name) => name !== ENVELOPE);
+  const expectedFiles = [...Object.keys(checksums), 'checksums.json'].sort();
+  if (new Set(expectedFiles).size !== expectedFiles.length) throw new Error('checksums.json contains duplicate package paths');
+  for (const rel of Object.keys(checksums)) {
+    if (!safeRelativePath(rel) || rel === ENVELOPE || rel === 'checksums.json') throw new Error(`unsafe checksum path: ${rel}`);
+    const file = path.join(runDir, ...rel.split('/'));
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`checksummed artifact is missing: ${rel}`);
+    if (!/^[a-f0-9]{64}$/.test(checksums[rel]) || sha256File(file) !== checksums[rel]) throw new Error(`artifact checksum mismatch: ${rel}`);
+  }
+  const extras = actualFiles.filter((name) => !expectedFiles.includes(name));
+  const missing = expectedFiles.filter((name) => !actualFiles.includes(name));
+  if (extras.length || missing.length) throw new Error(`run package completeness failure${extras.length ? `; unsealed: ${extras.join(', ')}` : ''}${missing.length ? `; missing: ${missing.join(', ')}` : ''}`);
+  if (checksums['manifest.json'] !== sha256File(manifestFile)) throw new Error('manifest.json is not bound by checksums.json');
+  return { manifest, files: actualFiles };
+}
+
+function artifactRecords(dir, files) {
+  return files.map((relative) => {
+    const file = path.join(dir, ...relative.split('/'));
+    return { path: relative, sha256: sha256File(file), bytes: fs.statSync(file).size };
+  });
+}
+
+function packageHash(envelope) {
+  return sha256(canonicalJson({ ...envelope, package_hash: '' }));
+}
+
+export function verifyArtifactPackage(input) {
+  const dir = path.resolve(input ?? '');
+  const envelopeFile = path.join(dir, ENVELOPE);
+  if (!fs.existsSync(envelopeFile)) throw new Error(`artifact interchange envelope not found: ${envelopeFile}`);
+  const envelope = readJson(envelopeFile);
+  const envelopeCheck = validateAgainst('artifact-interchange.schema.json', envelope);
+  if (!envelopeCheck.valid) throw new Error(`artifact interchange envelope invalid: ${envelopeCheck.errors.join('; ')}`);
+  if (packageHash(envelope) !== envelope.package_hash) throw new Error('artifact interchange package hash mismatch');
+  const { manifest, files } = validateRunPackage(dir);
+  if (manifest.run_id !== envelope.run.run_id) throw new Error('artifact run id does not match run manifest');
+  if (manifest.command !== envelope.run.command || manifest.status !== envelope.run.status || manifest.timestamp !== envelope.run.timestamp) throw new Error('artifact run metadata does not match run manifest');
+  if (manifest.tool_version !== envelope.run.tool_version || manifest.skill_version !== envelope.run.skill_version) throw new Error('artifact source versions do not match run manifest');
+  if (sha256File(path.join(dir, 'manifest.json')) !== envelope.run.manifest_sha256) throw new Error('artifact manifest hash mismatch');
+  if (sha256File(path.join(dir, 'checksums.json')) !== envelope.run.checksums_sha256) throw new Error('artifact checksums hash mismatch');
+  const records = artifactRecords(dir, files);
+  if (canonicalJson(records) !== canonicalJson(envelope.artifacts)) throw new Error('artifact inventory does not match package contents');
+  return { valid: true, dir, envelope, manifest, artifacts: records };
+}
+
+export function exportArtifactPackage(root, { runId, output }) {
+  if (!runId) throw new Error('usage: citable artifacts export <run-id> --output <directory>');
+  if (!SAFE_RUN_ID.test(runId)) throw new Error('artifact export requires a safe run id');
+  if (!output) throw new Error('artifact export requires --output <directory>');
+  const source = path.join(root, '.citable', 'runs', runId);
+  const validated = validateRunPackage(source);
+  if (validated.manifest.run_id !== runId) throw new Error('requested run id does not match run manifest');
+  const destination = path.resolve(root, output);
+  if (fs.existsSync(destination)) throw new Error(`artifact export destination already exists: ${destination}`);
+  if (destination === source || destination.startsWith(`${source}${path.sep}`)) throw new Error('artifact export destination cannot be inside the source run package');
+  const parent = path.dirname(destination);
+  fs.mkdirSync(parent, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(parent, `.${path.basename(destination)}-`));
+  try {
+    for (const relative of validated.files) {
+      const sourceFile = path.join(source, ...relative.split('/'));
+      const targetFile = path.join(stage, ...relative.split('/'));
+      fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+      fs.copyFileSync(sourceFile, targetFile);
+    }
+    const artifacts = artifactRecords(stage, validated.files);
+    const envelope = {
+      contract: 'citable-artifact-interchange',
+      contract_version: 1,
+      created_at: nowIso(),
+      producer: { tool: 'citable', tool_version: PACKAGE.version, skill_version: PACKAGE.version },
+      run: {
+        run_id: validated.manifest.run_id,
+        command: validated.manifest.command,
+        status: validated.manifest.status,
+        timestamp: validated.manifest.timestamp,
+        tool_version: validated.manifest.tool_version,
+        skill_version: validated.manifest.skill_version,
+        manifest_sha256: sha256File(path.join(stage, 'manifest.json')),
+        checksums_sha256: sha256File(path.join(stage, 'checksums.json')),
+      },
+      artifacts,
+      package_hash: '',
+      limitations: [
+        'Checksums establish preservation of exported bytes, not source authenticity, completeness of external observations, or outcome causality.',
+        'This portable package does not grant hosted storage, tenant, authentication, billing, or dashboard authority.',
+      ],
+    };
+    envelope.package_hash = packageHash(envelope);
+    writeJson(path.join(stage, ENVELOPE), envelope);
+    verifyArtifactPackage(stage);
+    fs.renameSync(stage, destination);
+    return { output: destination, envelope, artifacts: artifacts.length };
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function importArtifactPackage(root, { input }) {
+  if (!input) throw new Error('artifact import requires --input <directory>');
+  const verified = verifyArtifactPackage(input);
+  if (!SAFE_RUN_ID.test(verified.manifest.run_id)) throw new Error('artifact import requires a safe run id');
+  const runsDir = path.join(root, '.citable', 'runs');
+  const destination = path.join(runsDir, verified.manifest.run_id);
+  if (fs.existsSync(destination)) {
+    let existing;
+    try {
+      existing = validateRunPackage(destination);
+    } catch (error) {
+      throw new Error(`run collision: ${verified.manifest.run_id} already exists but is not a valid sealed package (${error.message})`);
+    }
+    const existingRecords = artifactRecords(destination, existing.files);
+    if (canonicalJson(existingRecords) === canonicalJson(verified.artifacts)) return { status: 'already_present', run_id: verified.manifest.run_id, destination };
+    throw new Error(`run collision: ${verified.manifest.run_id} already exists with different artifacts`);
+  }
+  fs.mkdirSync(runsDir, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(runsDir, '.artifact-import-'));
+  try {
+    for (const relative of verified.artifacts.map((item) => item.path)) {
+      const sourceFile = path.join(verified.dir, ...relative.split('/'));
+      const targetFile = path.join(stage, ...relative.split('/'));
+      fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+      fs.copyFileSync(sourceFile, targetFile);
+    }
+    validateRunPackage(stage);
+    fs.renameSync(stage, destination);
+    return { status: 'imported', run_id: verified.manifest.run_id, destination, source_package_hash: verified.envelope.package_hash };
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export const ARTIFACT_INTERCHANGE_ENVELOPE = ENVELOPE;

package/src/cli/index.js

@@ -10,7 +10,7 @@ import { inspect } from '../commands/inspect.js';
 import { schemaCommand } from '../commands/schemaCmd.js';
 import { compareSnapshots } from '../commands/compareSnapshots.js';
 import { isInstallerCommand, runInstallerCommand } from '../installer/index.js';
-import { selfUpgradeCommand, selfUpgradeExitCode } from '../commands/selfUpgrade.js';
+import { projectGithub, runSchedule } from '../commands/delivery.js';
 import { actionPlan } from '../commands/actionPlan.js';
 import { observe } from '../commands/observe.js';
 import { applyRemediation } from '../commands/applyRemediation.js';
@@ -19,7 +19,24 @@ import { evaluateObjective, importMetrics, initializeObjective, validateObjectiv
 import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
 import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 import { evaluateReviews, initializeSamplingPlan, prioritizeReviews, queueReviews, selectSample } from '../commands/reviews.js';
-import { projectGithub, runSchedule } from '../commands/delivery.js';
+import { selfUpgradeCommand, selfUpgradeExitCode } from '../commands/selfUpgrade.js';
+// Executive reporting suite
+import { kpiCommand } from '../commands/kpi.js';
+import { varianceCommand } from '../commands/variance.js';
+import { outcomesCommand } from '../commands/outcomes.js';
+import { riskCommand } from '../commands/risk.js';
+import { executiveReviewCommand } from '../commands/executiveReview.js';
+import { boardReportCommand } from '../commands/boardReport.js';
+import { decisionMemoCommand } from '../commands/decisionMemo.js';
+import { assumptionAuditCommand } from '../commands/assumptionAudit.js';
+import { scenarioCommand } from '../commands/scenario.js';
+import { prioritizeCommand } from '../commands/prioritize.js';
+import { competitiveIntelCommand } from '../commands/competitiveIntel.js';
+import { executiveCommand } from '../commands/executive.js';
+import { evaluateCorpus, publishCorpus } from '../commands/corpus.js';
+import { createAcceptanceReceipt, readAndCompareAcceptanceReceipts } from '../acceptance/reproducibility.js';
+import { readJson } from '../shared/io.js';
+import { exportArtifactPackage, importArtifactPackage, verifyArtifactPackage } from '../artifacts/interchange.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -43,7 +60,7 @@ Commands
   compare-snapshots [a b]   Regression diff between two audit runs
   action-plan [run]         Turn audit findings into ordered remediation work
   observe <mode>            Collect render, index, citation, log, Bing, passage,
-                            consensus, performance, corroboration, or media evidence
+                            consensus, performance, corroboration, media evidence, or representation evidence
   apply                     Apply a reviewed, hash-locked remediation spec
   monitor [runA runB]       Compare observation runs and emit regression alerts
   metrics import            Import declared metric observations from CSV/JSON
@@ -65,13 +82,34 @@ Commands
   reviews evaluate          Detect stale decisions and require disagreement adjudication
   schedules run [id]        Execute an active version-pinned audit schedule
   project github [run]      Render non-authoritative GitHub annotations from a run
+  corpus evaluate           Evaluate a disclosed real-property acceptance corpus
+  corpus publish            Validate and project an owner-authorized public corpus
+  corpus receipt            Create a reproducibility receipt for a sealed run
+  corpus compare-receipts   Compare two acceptance-run receipt envelopes
+  artifacts export         Export one sealed run as a portable verified directory
+  artifacts verify         Verify an exported artifact interchange directory
+  artifacts import         Import a verified run without changing its canonical bytes
   self-upgrade              Check for a newer version and upgrade the npx cache
+  kpi [list|show|validate]  KPI architecture — govern metric definitions, sources, targets
+  variance [list|validate|material]  Variance analysis — explain target-vs-actual without narrative smoothing
+  outcomes [list|summary|validate]   Customer outcomes — separate activity from validated impact
+  risk [list|top|validate]  Risk register — top risks, controls, residual exposure, KRIs
+  executive-review [--period YYYY-MM]  Monthly executive operating review (evidence-first)
+  board-report [--quarter YYYY-QN]     Quarterly board pack (governed statements only)
+  decision-memo [list|show|validate|new]  Bounded decision record with trade-offs and evidence
+  assumption-audit [list|expired|critical|validate]  Assumption validity tracking
+  scenario [list|show|triggers|validate]  Compound risk scenario war room
+  prioritize [list|rank|validate]     Initiative prioritization with transparent scoring
+  competitive-intel [list|stale|validate]  Competitive intelligence (provenance-controlled)
+  executive <request>       Chief-of-staff router — routes to the correct reporting skill
 
 Options
   --target <dir|url>        Built output directory or deployed URL to audit
   --base-url <url>          Base URL for path resolution of a built output dir
   --ref-date <YYYY-MM-DD>   Reference date for expiry/staleness checks (default: today)
-  --input <file>            Import file or remediation specification
+  --input <file>            Import evidence, remediation, or browser plan
+  --output <path>           Explicit output path for a corpus or artifact export
+  --run <run-id>            Sealed run used to create an acceptance receipt
   --provider <name>         Provider label for imported observations
   --dataset <name>          Provider export dataset (for example ai_performance)
   --connection-id <id>      Connection registry identifier
@@ -86,6 +124,9 @@ Options
   --repeat <count>          Repetitions per prompt for citation experiments
   --interactions            Exercise bounded disclosure, tab, and load-more controls
   --resume-run <run-id>     Reuse successful immutable render profiles
+  --surface-id <id>         Controlled publisher surface for representation evidence
+  --region <label>          Disclosed collector region for representation evidence
+  --user-agent <value>      Disclosed request identity for representation evidence
   --lighthouse              Run local, repeated Lighthouse lab observations
   --ocr                     Explicitly request optional OCR for media images
   --write                   Persist registry changes (map-claims, substantiate)
@@ -107,6 +148,8 @@ function parseArgs(argv) {
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
     else if (a === '--input') args.input = argv[++i];
+    else if (a === '--output') args.output = argv[++i];
+    else if (a === '--run') args.runId = argv[++i];
     else if (a === '--provider') args.provider = argv[++i];
     else if (a === '--dataset') args.dataset = argv[++i];
     else if (a === '--connection-id') args.connectionId = argv[++i];
@@ -120,6 +163,9 @@ function parseArgs(argv) {
     else if (a === '--endpoint') args.endpoint = argv[++i];
     else if (a === '--repeat') args.repeat = Number(argv[++i]);
     else if (a === '--resume-run') args.resumeRun = argv[++i];
+    else if (a === '--surface-id') args.surfaceId = argv[++i];
+    else if (a === '--region') args.region = argv[++i];
+    else if (a === '--user-agent') args.userAgent = argv[++i];
     else if (a === '--timeout') args.timeout = Number(argv[++i]);
     else if (a === '--force') args.force = true;
     else args._.push(a);
@@ -295,12 +341,105 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args,`project github ${r.source_run_id}: ${r.annotations.length} annotation(s)\nProjection: ${path.join(r.dir,'annotations.json')}`,r);
         break;
       }
+      case 'corpus': {
+        const mode = args._[0];
+        if (mode === 'evaluate') {
+          const r = evaluateCorpus(root, { input: args.input });
+          out(args, `corpus evaluate ${r.metrics.corpus_id}: ${r.metrics.population.detector_cases} detector case(s)\nEvidence package: ${r.dir}`, r);
+        } else if (mode === 'publish') {
+          const r = publishCorpus(root, { input: args.input, output: args.output });
+          out(args, `corpus publish ${r.receipt.corpus_id}: ${r.receipt.property_ids.length} approved property record(s)\nCorpus: ${r.output}\nMetrics: ${r.metricsFile}\nReport: ${r.reportFile}\nReceipt: ${r.receiptFile}\nEvidence package: ${r.dir}`, r);
+        } else if (mode === 'receipt') {
+          const context = args.input ? readJson(args.input) : {};
+          const r = createAcceptanceReceipt(root, { runId: args.runId, context });
+          out(args, `corpus receipt ${r.receipt.receipt_id}\nFingerprint: ${r.receipt.reproducibility.fingerprint}\nReceipt: ${r.output}${r.receipt.execution.partial ? '\nStatus: partial' : ''}`, r);
+        } else if (mode === 'compare-receipts') {
+          const r = readAndCompareAcceptanceReceipts(args._[1], args._[2]);
+          out(args, `corpus compare-receipts ${r.receipt_a} → ${r.receipt_b}\nComparable envelope: ${r.comparable}\nFingerprint equal: ${r.fingerprint_equal}\nPartial runs: ${r.partial_runs.length}`, r);
+        } else throw new Error('usage: citable corpus <evaluate|publish|receipt|compare-receipts> [options]');
+        break;
+      }
+      case 'artifacts': {
+        const mode = args._[0];
+        if (mode === 'export') {
+          const r = exportArtifactPackage(root, { runId: args._[1], output: args.output });
+          out(args, `artifacts export ${r.envelope.run.run_id}: ${r.artifacts} sealed file(s)\nPackage: ${r.output}\nPackage hash: ${r.envelope.package_hash}`, r);
+        } else if (mode === 'verify') {
+          const r = verifyArtifactPackage(args.input);
+          out(args, `artifacts verify ${r.manifest.run_id}: valid\nArtifacts: ${r.artifacts.length}\nPackage hash: ${r.envelope.package_hash}`, { valid: r.valid, run_id: r.manifest.run_id, artifacts: r.artifacts.length, package_hash: r.envelope.package_hash });
+        } else if (mode === 'import') {
+          const r = importArtifactPackage(root, { input: args.input });
+          out(args, `artifacts import ${r.run_id}: ${r.status}\nRun package: ${r.destination}`, r);
+        } else throw new Error('usage: citable artifacts <export <run-id> --output <directory>|verify --input <directory>|import --input <directory>>');
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);
         process.exitCode = selfUpgradeExitCode(output);
         break;
       }
+      // Executive reporting suite
+      case 'kpi': {
+        const r = await kpiCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'variance': {
+        const r = await varianceCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'outcomes': {
+        const r = await outcomesCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'risk': {
+        const r = await riskCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'executive-review': {
+        const r = await executiveReviewCommand(argv.slice(1), root);
+        out(args, typeof r === 'string' ? r : JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'board-report': {
+        const r = await boardReportCommand(argv.slice(1), root);
+        out(args, typeof r === 'string' ? r : JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'decision-memo': {
+        const r = await decisionMemoCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'assumption-audit': {
+        const r = await assumptionAuditCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'scenario': {
+        const r = await scenarioCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'prioritize': {
+        const r = await prioritizeCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'competitive-intel': {
+        const r = await competitiveIntelCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'executive': {
+        const r = await executiveCommand(argv.slice(1), root);
+        out(args, JSON.stringify(r, null, 2), r);
+        break;
+      }
       case undefined:
         console.log(HELP);
         break;

package/src/commands/assumptionAudit.js

@@ -0,0 +1,111 @@
+/**
+ * assumption-audit command — Assumption Registry
+ *
+ * Tracks which commercial and product assumptions remain valid.
+ * Feeds both board reporting and roadmap prioritization.
+ *
+ * Usage:
+ *   citable assumption-audit list [--status <status>]
+ *   citable assumption-audit show <assumption_id>
+ *   citable assumption-audit validate
+ *   citable assumption-audit expired   — assumptions past expiry date
+ *   citable assumption-audit critical  — critical importance assumptions
+ */
+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';
+
+export async function assumptionAuditCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'assumptions.yaml');
+
+  switch (subcommand) {
+    case 'show':     return assumptionShow(file, rest[0]);
+    case 'validate': return assumptionValidate(file);
+    case 'expired':  return assumptionExpired(file, parseAsOf(args));
+    case 'critical': return assumptionList(file, { importance: 'critical' });
+    case 'list':
+    default: {
+      const statusFilter = rest[rest.indexOf('--status') + 1] ?? null;
+      return assumptionList(file, { statusFilter });
+    }
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'assumptions');
+}
+
+function assumptionList(file, { statusFilter = null, importance = null } = {}) {
+  const data = load(file);
+  let entries = data.entries;
+  if (statusFilter) entries = entries.filter(a => a.current_status === statusFilter);
+  if (importance)   entries = entries.filter(a => a.importance === importance);
+  return {
+    assumptions: entries.map(a => ({
+      assumption_id:  a.assumption_id,
+      statement:      a.statement,
+      category:       a.category,
+      importance:     a.importance,
+      current_status: a.current_status,
+      confidence:     a.confidence,
+      owner:          a.owner,
+      expiry:         a.expiry ?? 'none',
+    })),
+    total: entries.length,
+    by_status: statusDist(data.entries),
+  };
+}
+
+function assumptionShow(file, id) {
+  if (!id) return { error: 'assumption_id required' };
+  const data = load(file);
+  const a = data.entries.find(e => e.assumption_id === id);
+  if (!a) return { error: `Assumption not found: ${id}` };
+  return { assumption: a };
+}
+
+function assumptionExpired(file, asOf) {
+  const data = load(file);
+  const expired = data.entries.filter(a => a.expiry && new Date(a.expiry) < asOf);
+  return {
+    expired: expired.map(a => ({
+      assumption_id: a.assumption_id, statement: a.statement,
+      expiry: a.expiry, current_status: a.current_status, owner: a.owner,
+    })),
+    total: expired.length,
+    as_of: dateOnly(asOf),
+  };
+}
+
+function assumptionValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('assumption.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const a of data.entries) {
+    // Validated assumptions need supporting evidence
+    if (['validated_within_scope','partially_validated'].includes(a.current_status) && (!a.evidence_for || a.evidence_for.length === 0))
+      problems.push(`${a.assumption_id}: status "${a.current_status}" requires evidence_for`);
+    // Contradicted/invalidated need counter-evidence
+    if (['contradicted','invalidated'].includes(a.current_status) && (!a.evidence_against || a.evidence_against.length === 0))
+      problems.push(`${a.assumption_id}: status "${a.current_status}" requires evidence_against`);
+    // Critical assumptions need a next_test date
+    if (a.importance === 'critical' && !a.next_test)
+      problems.push(`${a.assumption_id}: critical importance requires next_test date`);
+    // Contradicted critical assumptions must have decision dependencies flagged
+    if (a.importance === 'critical' && a.current_status === 'contradicted' && (!a.decision_dependency || a.decision_dependency.length === 0))
+      problems.push(`${a.assumption_id}: critical contradicted assumption has no decision_dependency — escalate to decision-memo`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}
+
+function statusDist(entries) {
+  const dist = {};
+  for (const a of entries) dist[a.current_status] = (dist[a.current_status] ?? 0) + 1;
+  return dist;
+}

package/src/commands/audit.js

@@ -34,6 +34,11 @@ export async function audit(root, { target, scope, baseUrl, refDate } = {}) {
   if (ctx.site?.fetchErrors?.length) {
     run.manifest.errors.push(...ctx.site.fetchErrors);
   }
+  if (ctx.site?.crawl?.truncated) {
+    run.manifest.incomplete_checks.push(
+      `URL collection reached the ${ctx.site.crawl.maxPages}-page limit with ${ctx.site.crawl.pendingUrlCount} discovered URL(s) pending; sitemap absence checks are incomplete.`
+    );
+  }
 
   const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(detectors, ctx);
   run.manifest.detectors_run = detectorsRun;
@@ -65,6 +70,7 @@ export async function audit(root, { target, scope, baseUrl, refDate } = {}) {
     target: run.manifest.target, scope: scope ?? 'all',
     registry_counts: Object.fromEntries(Object.entries(ctx.registries).map(([k, v]) => [k, v.entries.length])),
     pages_audited: ctx.site?.pages.length ?? 0,
+    crawl_coverage: ctx.site?.crawl ?? null,
   });
   run.writeArtifact('environment.json', {
     node: process.version, platform: process.platform, cwd: root,