@nebulacomponents/citable 1.19.0 → 1.21.0

package/schemas/research-dataset.schema.json

@@ -0,0 +1,27 @@
+{
+  "$id": "citable://schemas/research-dataset.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Immutable research dataset",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dataset_id", "dataset_version", "declared_purpose", "declared_population", "population_size", "inclusion_criteria", "exclusion_criteria", "collection", "source_references", "observation_references", "normalization", "derivation_references", "coverage", "coverage_status", "limitations", "dataset_hash"],
+  "properties": {
+    "dataset_id": { "type": "string", "minLength": 1 },
+    "dataset_version": { "type": "integer", "minimum": 1 },
+    "declared_purpose": { "type": "string", "minLength": 1 },
+    "declared_population": { "type": "object", "additionalProperties": false, "required": ["type", "id"], "properties": { "type": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "size": { "type": ["integer", "null"], "minimum": 0 } } },
+    "population_size": { "type": ["integer", "null"], "minimum": 0 },
+    "inclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "exclusion_criteria": { "type": "array", "items": { "type": "string" } },
+    "collection": { "type": "object", "additionalProperties": false, "required": ["started_at", "ended_at"], "properties": { "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" } } },
+    "source_references": { "type": "array", "items": { "type": "string" } },
+    "source_retrieval_timestamps": { "type": "array", "items": { "type": "string", "format": "date-time" } },
+    "observation_references": { "type": "array", "items": { "type": "string" } },
+    "normalization": { "type": "object", "additionalProperties": false, "required": ["method", "version"], "properties": { "method": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } } },
+    "derivation_references": { "type": "array", "items": { "type": "string" } },
+    "coverage": { "type": "object", "additionalProperties": false, "required": ["declared", "retrieved", "evaluated", "unavailable", "failed"], "properties": { "declared": { "type": "integer", "minimum": 0 }, "retrieved": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } },
+    "coverage_status": { "type": "string", "enum": ["complete_for_declared_population", "partial", "truncated", "indeterminate", "error"] },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "dataset_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/run.schema.json

@@ -5,6 +5,7 @@
   "type": "object",
   "required": ["run_id", "command", "tool_version", "skill_version", "timestamp", "target", "status"],
   "properties": {
+    "schema_version": { "type": "integer", "enum": [1, 2] },
     "run_id": { "type": "string" },
     "command": { "type": "string" },
     "argv": { "type": "array", "items": { "type": "string" } },
@@ -31,6 +32,18 @@
     "incomplete_checks": { "type": "array", "items": { "type": "string" } },
     "errors": { "type": "array", "items": { "type": "string" } },
     "warnings": { "type": "array", "items": { "type": "string" } },
-    "status": { "type": "string", "enum": ["completed", "completed_with_warnings", "incomplete", "failed"] }
-  }
+    "status": { "type": "string", "enum": ["completed", "completed_with_warnings", "incomplete", "failed"] },
+    "execution_status": { "type": "string", "enum": ["completed", "completed_with_warnings", "failed"] },
+    "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+    "determination_status": { "type": "string", "enum": ["supported", "qualified", "indeterminate", "not_applicable"] }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["schema_version"],
+        "properties": { "schema_version": { "const": 2 } }
+      },
+      "then": { "required": ["execution_status", "coverage_status", "determination_status"] }
+    }
+  ]
 }

package/schemas/search-discovery-data.schema.json

@@ -0,0 +1,20 @@
+{
+  "$id": "citable://schemas/search-discovery-data.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Search discovery observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["query", "page", "interval", "metrics", "request", "coverage_status", "evidence_origin"],
+  "properties": {
+    "query": { "type": ["string", "null"] },
+    "page": { "type": ["string", "null"], "format": "uri" },
+    "interval": { "type": "object", "additionalProperties": false, "required": ["start_date", "end_date"], "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } },
+    "metrics": { "type": "object", "additionalProperties": false, "required": ["impressions", "clicks", "ctr", "average_position"], "properties": { "impressions": { "type": ["number", "null"], "minimum": 0 }, "clicks": { "type": ["number", "null"], "minimum": 0 }, "ctr": { "type": ["number", "null"], "minimum": 0 }, "average_position": { "type": ["number", "null"], "minimum": 0 } } },
+    "dimensions": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": ["string", "null"] }, "device": { "type": ["string", "null"] }, "search_appearance": { "type": ["string", "null"] }, "date": { "type": ["string", "null"], "format": "date" } } },
+    "request": { "type": "object", "additionalProperties": false, "required": ["property_id", "dimensions", "filters", "row_limit"], "properties": { "property_id": { "type": "string", "minLength": 1 }, "dimensions": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "row_limit": { "type": "integer", "minimum": 1, "maximum": 25000 } } },
+    "provider_reported": { "type": "object", "additionalProperties": false, "properties": { "row_count": { "type": ["integer", "null"], "minimum": 0 }, "page_start": { "type": "integer", "minimum": 0 } } },
+    "response_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "coverage_status": { "type": "string", "enum": ["complete", "truncated", "indeterminate", "provider_bounded"] },
+    "evidence_origin": { "type": "string", "enum": ["LIVE_PROVIDER", "RECORDED_FIXTURE", "SYNTHETIC_TEST"] }
+  }
+}

package/schemas/search-report.schema.json

@@ -90,7 +90,14 @@
         "source_identifier": { "type": ["string", "null"] },
         "source_findings_count": { "type": "integer", "minimum": 0 },
         "integrity_hash": { "type": ["string", "null"] },
-        "synthetic_evidence": { "type": "boolean" }
+        "synthetic_evidence": { "type": "boolean" },
+        "package_verified": { "type": "boolean" },
+        "integrity_mode": { "type": "string" },
+        "legacy": { "type": "boolean" },
+        "coverage_status": { "type": "string" },
+        "determination_status": { "type": "string" },
+        "evaluated": { "type": ["integer", "null"], "minimum": 0 },
+        "eligible": { "type": ["integer", "null"], "minimum": 0 }
       },
       "additionalProperties": false
     }

package/schemas/summary.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "citable://schemas/summary.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Run summary",
+  "type": "object",
+  "required": ["coverage", "posture"],
+  "properties": {
+    "coverage": {
+      "type": ["object", "null"],
+      "required": ["status", "populations", "stop_reason"],
+      "properties": {
+        "status": { "enum": ["complete", "truncated", "indeterminate", "not_applicable"] },
+        "populations": { "$ref": "citable://schemas/audit-coverage.schema.json#/properties/populations" },
+        "stop_reason": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "posture": {
+      "type": "object",
+      "required": ["retrieval_eligibility", "source_extraction_and_support", "observed_citation_behavior"],
+      "properties": {
+        "retrieval_eligibility": { "$ref": "#/definitions/posture" },
+        "source_extraction_and_support": { "$ref": "#/definitions/posture" },
+        "observed_citation_behavior": { "$ref": "#/definitions/posture" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "posture": {
+      "type": "object",
+      "required": ["result"],
+      "properties": {
+        "result": { "type": "string" },
+        "coverage_status": { "enum": ["complete", "truncated", "indeterminate", "not_applicable"] }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.19.0
+version: 1.21.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -69,6 +69,15 @@ Every report must keep these top-level states separate:
 3. **Observed citation behavior** — only controlled, timestamped provider
    observations; absent observations are `not_evidenced`, never inferred.
 
+Presentation language must preserve those boundaries. An empty finding list,
+legacy package, unverified artifact, incomplete crawl, or indeterminate
+determination must not be described as `clean`, `complete`, `verified`,
+`resolved`, `100%`, or `site-wide`. State the evaluated population and the
+limitation instead (for example, "No findings were produced for the 217
+successfully evaluated resources; corpus-wide absence is not established").
+Positive local observations may remain supported, but they must not be widened
+to pages or resources that were not observed.
+
 Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
 `observed_in_production_logs`, `indexed`, and `returned_by_retrieval`. Within
 citation testing, distinguish mention, citation, material support, canonical
@@ -86,7 +95,7 @@ prefer running it over re-deriving its checks by hand:
 
 ```
 citable init                        # initialize .citable/ (non-destructive)
-citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
+citable audit [scope] --target <dir|url> [--base-url <url>] [--max-pages <1..10000>] [--time-budget-seconds <1..86400>] [--ref-date YYYY-MM-DD]
 citable plan-audit --target <dir|url> [--base-url <url>]
 citable sweep technical --target <dir|url> # Technical SEO sweep + Core Web Vitals metrics
 citable inspect <page> --target <dir|url>

package/src/acceptance/reproducibility.js

@@ -1,8 +1,8 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import { canonicalJson } from '../release/governance.js';
-import { nowIso, readJson, sha256, sha256File, writeJson } from '../shared/io.js';
+import { nowIso, readJson, sha256, writeJson } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const INCLUDED_FIELDS = [
   'property.target', 'property.source_commit', 'property.content_hashes',
@@ -37,25 +37,6 @@ function normalizedArguments(argv = []) {
   return normalized;
 }
 
-function verifyRunPackage(runDir, manifest) {
-  const manifestCheck = validateAgainst('run.schema.json', manifest);
-  if (!manifestCheck.valid) throw new Error(`run manifest violates contract: ${manifestCheck.errors.join('; ')}`);
-  const checksumsFile = path.join(runDir, 'checksums.json');
-  if (!fs.existsSync(checksumsFile)) throw new Error(`run ${manifest.run_id} has no checksums.json`);
-  const checksums = readJson(checksumsFile);
-  if (!checksums || Array.isArray(checksums) || typeof checksums !== 'object') throw new Error('run checksums must be an object');
-  const failures = [];
-  for (const [relative, expected] of Object.entries(checksums)) {
-    const file = path.resolve(runDir, relative);
-    if (path.isAbsolute(relative) || (!file.startsWith(`${path.resolve(runDir)}${path.sep}`))) failures.push(`${relative} escapes the run package`);
-    else if (!/^[a-f0-9]{64}$/.test(expected)) failures.push(`${relative} has an invalid checksum`);
-    else if (!fs.existsSync(file)) failures.push(`${relative} is missing`);
-    else if (sha256File(file) !== expected) failures.push(`${relative} checksum differs`);
-  }
-  if (failures.length) throw new Error(`run package integrity failed: ${failures.join('; ')}`);
-  return checksums;
-}
-
 function fingerprintPayload(receipt) {
   return {
     property: { target: receipt.property.target, source_commit: receipt.property.source_commit, content_hashes: receipt.property.content_hashes },
@@ -74,11 +55,10 @@ export function createAcceptanceReceipt(root, { runId, context = {}, createdAt =
   const contextCheck = validateAgainst('acceptance-run-context.schema.json', context);
   if (!contextCheck.valid) throw new Error(`acceptance context violates contract: ${contextCheck.errors.join('; ')}`);
   const runDir = path.join(root, '.citable', 'runs', runId);
-  const manifestFile = path.join(runDir, 'manifest.json');
-  if (!fs.existsSync(manifestFile)) throw new Error(`run ${runId} not found`);
-  const manifest = readJson(manifestFile);
+  const verified = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const manifest = verified.manifest;
   if (manifest.run_id !== runId) throw new Error(`run manifest id ${manifest.run_id} does not match requested run ${runId}`);
-  const checksums = verifyRunPackage(runDir, manifest);
+  const checksums = verified.artifactHashes;
   const canonicalArtifacts = sortedObject(Object.fromEntries(
     Object.entries(checksums).filter(([name]) => name !== 'manifest.json'),
   ));

package/src/analysis/croRoadmap.js

@@ -18,10 +18,10 @@ export function buildCroRoadmap({ findings = [], targetDomain = 'example.com', d
       'Mobile Tap Sizing: Expand diminutive mobile CTA touch targets to >= 48px standard (CRO-015)',
     ],
     target_outcomes: [
-      '100% conversion funnel continuity intact across all declared paths',
+      'Conversion funnel continuity observed across the declared paths in scope',
       'Keystroke Effort Index: Form completion friction reduced by >= 40%',
-      'Above-the-fold information scent match verified across all primary landing pages',
-      'Zero mobile touch target defects under 48px',
+      'Above-the-fold information scent match observed on evaluated primary landing pages',
+      'No mobile touch-target findings in the evaluated pages',
     ],
     measurable_conversion_kpi: 'Form Completion Rate (+8% to +15% expected relative lift)',
     experiments: backlog.experiments.filter((e) => ['CRO-007', 'CRO-005', 'CRO-015', 'CRO-017', 'CRO-018'].includes(e.detector_id) || e.ice_prioritization.effort <= 3),

package/src/analysis/strategicRoadmap.js

@@ -24,9 +24,9 @@ export function buildStrategicRoadmap({ findings = [], initiatives = [], targetD
     ],
     exit_criteria: [
       'Zero critical-severity technical findings in citable audit technical',
-      'Static CLS readiness: 100% of body images have explicit dimensions',
-      'All major answer engine bots verified allowed in robots directives',
-      'Baseline Organization schema live with verified @id',
+      'Static CLS readiness: every evaluated body image has explicit dimensions',
+      'Major answer engine bot access observed as allowed in robots directives',
+      'Baseline Organization schema live with an observed @id',
     ],
     actions: [],
   };

package/src/artifacts/interchange.js

@@ -5,6 +5,7 @@ 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';
+import { verifyRunPackage } from '../shared/runPackageVerifier.js';
 
 const PACKAGE = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
 const ENVELOPE = 'citable-artifact.json';
@@ -37,18 +38,13 @@ function validateRunPackage(runDir) {
   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');
+  verifyRunPackage(runDir, { requireFindings: false, requireCompleted: false, requireChecksums: true, ignoredFiles: [ENVELOPE] });
   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));

package/src/cli/index.js

@@ -185,6 +185,8 @@ Commands
 
 Options
   --target <dir|url>        Built output directory or deployed URL to audit
+  --max-pages <count>       Maximum unique page URLs attempted for a URL audit (default: 500)
+  --time-budget-seconds <seconds>  Whole-run URL collection limit (default: 1800)
   --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 evidence, remediation, or browser plan
@@ -233,7 +235,7 @@ Options
 No output of this tool guarantees crawling, indexing, ranking, citation,
 recommendation, inclusion, sentiment, or conversion outcomes.`;
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -243,6 +245,8 @@ function parseArgs(argv) {
     else if (a === '--interactions') args.interactions = true;
     else if (a === '--lighthouse') args.lighthouse = true;
     else if (a === '--target') args.target = argv[++i];
+    else if (a === '--max-pages') args.maxPages = Number(argv[++i]);
+    else if (a === '--time-budget-seconds') args.timeBudgetSeconds = Number(argv[++i]);
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
     else if (a === '--viewport') args.viewport = argv[++i];
@@ -411,8 +415,16 @@ ${r.findings.map((f) => `  [${f.rule_id}] (${f.severity}) ${f.summary}\n    Fix:
           break;
         }
         const scope = args._[0];
-        const r = await audit(root, { target: args.target, scope, baseUrl: args.baseUrl, refDate: args.refDate, viewport: args.viewport });
-        out(args, `Audit ${r.runId}: ${r.summary.total} finding(s) [${Object.entries(r.summary.by_severity).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nReport: ${path.join(r.dir, 'report.md')}\nStatus: ${r.manifest.status}${r.manifest.incomplete_checks.length ? `\nIncomplete: ${r.manifest.incomplete_checks.join('; ')}` : ''}`, { runId: r.runId, dir: r.dir, summary: r.summary, status: r.manifest.status });
+        const r = await audit(root, {
+          target: args.target,
+          scope,
+          baseUrl: args.baseUrl,
+          refDate: args.refDate,
+          viewport: args.viewport,
+          maxPages: args.maxPages,
+          timeBudgetSeconds: args.timeBudgetSeconds,
+        });
+        out(args, `Audit ${r.runId}: ${r.summary.total} finding(s) [${Object.entries(r.summary.by_severity).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nReport: ${path.join(r.dir, 'report.md')}\nStatus: ${r.manifest.status}\nExecution: ${r.manifest.execution_status}\nCoverage: ${r.manifest.coverage_status}\nDetermination: ${r.manifest.determination_status}${r.manifest.incomplete_checks.length ? `\nIncomplete: ${r.manifest.incomplete_checks.join('; ')}` : ''}`, { runId: r.runId, dir: r.dir, summary: r.summary, status: r.manifest.status, execution_status: r.manifest.execution_status, coverage_status: r.manifest.coverage_status, determination_status: r.manifest.determination_status });
         break;
       }
       case 'plan-audit': {

package/src/commands/actionPlan.js

@@ -2,7 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, sha256, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { downstreamEnvelope } from '../evidence/downstream.js';
+import { REQUIREMENTS, evaluateRequirement } from '../evidence/determination.js';
 import { checklistItem, toStringArray } from '../shared/checklist.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const SEVERITY = { critical: 0, high: 1, medium: 2, low: 3, informational: 3, experimental: 3 };
 const PHASE = { unblock: 0, governance: 1, content: 2, optimization: 3 };
@@ -46,6 +49,7 @@ function renderPlan(plan) {
     '# Citable action plan', '',
     `- Source audit: \`${plan.source_run_id}\``,
     `- Actions: ${plan.summary.total_actions}; ready: ${plan.summary.ready}; blocked: ${plan.summary.blocked}`,
+    `- Evidence coverage: ${plan.source_coverage.coverage_status}; determination: ${plan.source_coverage.determination_status}`,
     '',
     '> This plan prioritizes observed findings. It does not guarantee ranking, citation, recommendation, or conversion outcomes.',
     '',
@@ -61,6 +65,7 @@ function renderPlan(plan) {
       lines.push(`- Decision owner: ${action.decision_owner ?? 'unassigned'}`);
       lines.push(`- Dependencies: ${action.depends_on_action_ids.length ? action.depends_on_action_ids.join(', ') : 'none established'}`);
       if (action.required_input.length) lines.push(`- Required input: ${action.required_input.join(', ')}`);
+      if (action.limitations.length) lines.push(`- Evidence limitations: ${action.limitations.join('; ')}`);
       if (action.semantic_gates.length) lines.push(`- Semantic gates: ${action.semantic_gates.join(', ')}`);
       lines.push(`- Failure condition: ${action.failure_condition}`);
       lines.push(`- Leading indicators: ${action.leading_indicators.length ? action.leading_indicators.join(', ') : 'none established'}`);
@@ -78,13 +83,37 @@ export function actionPlan(root, { runId } = {}) {
   const sourceDir = path.join(runsDir, sourceRunId);
   const findingsFile = path.join(sourceDir, 'findings.json');
   if (!fs.existsSync(findingsFile)) throw new Error(`run ${sourceRunId} has no findings.json`);
-  const rawFindings = fs.readFileSync(findingsFile, 'utf8');
-  const findings = JSON.parse(rawFindings);
-  const manifest = readJson(path.join(sourceDir, 'manifest.json'));
+  const loaded = loadVerifiedRun(sourceDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const findings = loaded.findings;
+  const rawFindings = JSON.stringify(findings);
+  const manifest = loaded.manifest;
+  const coverage = loaded.coverage;
+  const sourceCoverage = downstreamEnvelope(coverage, {
+    artifact: coverage ? 'coverage.json' : null,
+  });
   const target = manifest.target?.location;
   const actions = findings.map((finding) => {
     const owner = finding.remediation.owner ?? null;
-    const blocked = finding.remediation.review_required && !owner;
+    const findingScope = finding.evidence_scope || {
+      requirement: 'evaluated_subset',
+      satisfaction: sourceCoverage.determination_status,
+      coverage_ref: coverage ? 'coverage.json' : null,
+      resource_ids: [],
+    };
+    const requirement = findingScope.requirement || REQUIREMENTS.EVALUATED_SUBSET;
+    let requirementResult;
+    try {
+      requirementResult = evaluateRequirement(requirement, coverage, finding.subject);
+    } catch (error) {
+      requirementResult = { status: 'indeterminate', reason: `invalid_evidence_requirement: ${error.message}` };
+    }
+    const scopeSatisfied = ['supported', 'qualified'].includes(requirementResult.status);
+    const effectiveDetermination = sourceCoverage.determination_status === 'indeterminate'
+      || sourceCoverage.determination_status === 'not_applicable'
+      || !scopeSatisfied
+      ? 'indeterminate'
+      : (sourceCoverage.determination_status === 'qualified' || requirementResult.status === 'qualified' ? 'qualified' : 'supported');
+    const blocked = (finding.remediation.review_required && !owner) || !scopeSatisfied || effectiveDetermination === 'indeterminate';
     const scope = finding.discipline.length === 1 && ['aeo', 'geo', 'seo'].includes(finding.discipline[0]) ? ` ${finding.discipline[0]}` : '';
     return {
       action_id: `ACT-${finding.finding_id.replace(/^F-/, '')}`,
@@ -97,7 +126,18 @@ export function actionPlan(root, { runId } = {}) {
       owner,
       decision_owner: owner,
       status: blocked ? 'blocked' : 'ready',
-      required_input: blocked ? toStringArray([checklistItem('owner', 'accountable owner')]) : [],
+      evidence_scope: { ...findingScope, satisfaction: effectiveDetermination },
+      coverage_status: sourceCoverage.coverage_status,
+      determination_status: effectiveDetermination,
+      limitations: [
+        ...sourceCoverage.limitations,
+        ...(finding.reasoning?.limitations || []),
+        ...(requirementResult.reason ? [`evidence requirement: ${requirementResult.reason}`] : []),
+      ].filter((item, index, all) => all.indexOf(item) === index),
+      required_input: blocked ? toStringArray([
+        ...(finding.remediation.review_required && !owner ? [checklistItem('owner', 'accountable owner')] : []),
+        ...(!scopeSatisfied || effectiveDetermination === 'indeterminate' ? ['sufficient comparable evidence for the declared scope'] : []),
+      ]) : [],
       semantic_gates: semanticGates(finding),
       unsafe_shortcuts: finding.remediation.unsafe_shortcuts || [],
       failure_condition: `${finding.verification.detector_to_rerun} still reports the exact subject, or verification cannot complete with sufficient evidence`,
@@ -120,6 +160,7 @@ export function actionPlan(root, { runId } = {}) {
       ready: actions.filter((action) => action.status === 'ready').length,
       blocked: actions.filter((action) => action.status === 'blocked').length,
     },
+    source_coverage: sourceCoverage,
     actions,
   };
   const validation = validateAgainst('action-plan.schema.json', plan);

package/src/commands/applyRemediation.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRun } from '../evidence/run.js';
 import { readJson, sha256 } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 function inside(root, candidate) {
   const base = path.resolve(root) + path.sep;
@@ -19,11 +20,10 @@ export function applyRemediation(root, { input, write = false } = {}) {
   const spec = readJson(input);
   const valid = validateAgainst('remediation-spec.schema.json', spec);
   if (!valid.valid) throw new Error(`remediation spec invalid: ${valid.errors.join('; ')}`);
-  const manifestFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'manifest.json');
-  if (!fs.existsSync(manifestFile)) throw new Error(`source run not found: ${spec.source_run_id}`);
-  const findingsFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'findings.json');
-  if (!fs.existsSync(findingsFile)) throw new Error(`source run has no findings: ${spec.source_run_id}`);
-  const sourceFindingIds = new Set(readJson(findingsFile).map((finding) => finding.finding_id));
+  const sourceDir = path.join(root, '.citable', 'runs', spec.source_run_id);
+  if (!fs.existsSync(sourceDir)) throw new Error(`source run not found: ${spec.source_run_id}`);
+  const source = loadVerifiedRun(sourceDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const sourceFindingIds = new Set(source.findings.map((finding) => finding.finding_id));
   const results = [];
   const pending = [];
   for (const operation of spec.operations) {

package/src/commands/audit.js

@@ -10,10 +10,16 @@ import { writeJson, sha256 } from '../shared/io.js';
 import { extractModified } from '../detectors/lifeMeas.js';
 import { buildEntityGraph } from '../observations/entityGraph.js';
 import { buildSourceIdentityChain } from '../observations/sourceIdentity.js';
+import { pageArtifactRecord } from '../evidence/hashes.js';
 
 /** `citable audit [scope]` — run detectors and produce an evidence package. */
-export async function audit(root, { target, scope, baseUrl, refDate, viewport = null } = {}) {
-  const ctx = await buildContext(root, { target, baseUrl, refDate, viewport });
+export async function audit(root, {
+  target, scope, baseUrl, refDate, viewport = null,
+  maxPages, timeBudgetSeconds, fetcher, concurrency = 1,
+} = {}) {
+  const ctx = await buildContext(root, {
+    target, baseUrl, refDate, viewport, maxPages, timeBudgetSeconds, fetcher, concurrency,
+  });
   const detectors = selectDetectors({ scope });
 
   const run = createRun(root, {
@@ -36,10 +42,32 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   if (ctx.site?.fetchErrors?.length) {
     run.manifest.errors.push(...ctx.site.fetchErrors);
   }
-  if (ctx.site?.crawl?.truncated) {
+  if (ctx.site?.crawl?.stopReason === 'page_budget_exhausted') {
     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.`
     );
+  } else if (ctx.site?.crawl?.stopReason === 'time_budget_exhausted') {
+    run.manifest.incomplete_checks.push(
+      `URL collection reached the ${ctx.site.crawl.timeBudgetSeconds}-second time budget; sitemap absence checks are incomplete.`
+    );
+  }
+
+  // Establish and persist the collection contract before detectors execute.
+  // Detectors receive this exact provisional evidence envelope through ctx so
+  // they cannot infer completeness from page-array length or legacy crawl data.
+  let coverage = null;
+  if (ctx.site?.previewCoverage) {
+    try {
+      coverage = ctx.site.previewCoverage();
+      run.manifest.coverage_status = coverage.coverage_status;
+      run.writeArtifact('coverage.json', coverage);
+      ctx.coverage = coverage;
+    } catch (error) {
+      run.manifest.execution_status = 'failed';
+      run.manifest.errors.push(`coverage: ${error.message}`);
+      run.finalize('failed');
+      throw error;
+    }
   }
 
   const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(detectors, ctx);
@@ -47,6 +75,27 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   run.manifest.detectors_skipped = detectorsSkipped;
   run.manifest.errors.push(...errors);
 
+  // Seal the ledger after detector evaluation so the same artifact records
+  // evaluated resources while retaining the pre-detector persistence proof.
+  if (ctx.site?.finalizeCoverage) {
+    try {
+      coverage = ctx.site.finalizeCoverage({ evaluated: true });
+      run.manifest.coverage_status = coverage.coverage_status;
+      run.manifest.determination_status = coverage.coverage_status === 'complete' ? 'supported' : 'qualified';
+      run.writeArtifact('coverage.json', coverage);
+      if (coverage.coverage_status !== 'complete') {
+        run.manifest.incomplete_checks.push(
+          `Coverage is ${coverage.coverage_status}; conclusions are limited to the successfully observed corpus.`,
+        );
+      }
+    } catch (error) {
+      run.manifest.execution_status = 'failed';
+      run.manifest.errors.push(`coverage: ${error.message}`);
+      run.finalize('failed');
+      throw error;
+    }
+  }
+
   // Validate every finding against the data contract; a contract breach fails the run.
   const invalid = [];
   for (const f of findings) {
@@ -66,6 +115,7 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     detectorsSkipped,
     promptResults: ctx.promptResults || [],
     targetOrigin: ctx.site?.baseUrl ? new URL(ctx.site.baseUrl).origin : null,
+    coverage,
   });
   run.writeArtifact('summary.json', summary);
   run.writeArtifact('inputs.json', {
@@ -73,6 +123,8 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     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,
+    coverage_status: coverage?.coverage_status ?? 'not_applicable',
+    coverage_populations: coverage?.populations ?? null,
   });
   run.writeArtifact('environment.json', {
     node: process.version, platform: process.platform, cwd: root,
@@ -80,9 +132,8 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   });
   if (ctx.site) {
     run.writeArtifact('pages/index.json', ctx.site.pages.map((p) => ({
-      url: p.url, status: p.status, title: p.title, canonicals: p.canonicals,
-      noindex: p.noindex, wordCount: p.wordCount, sourceFile: p.sourceFile,
-      contentHash: ctx.hashPage(p),
+      ...pageArtifactRecord(p),
+      artifact_hash: p.artifact_hash ?? null,
     })));
     if (ctx.site.robotsText != null) run.writeArtifact('robots/robots.txt', ctx.site.robotsText);
     for (const sm of ctx.site.sitemaps) {
@@ -102,14 +153,26 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     }
   }
 
-  const report = renderMarkdownReport({ findings, manifest: run.manifest, summary, detectorsSkipped });
+  const report = renderMarkdownReport({ findings, manifest: run.manifest, summary, detectorsSkipped, coverage });
   run.writeArtifact('report.md', report);
 
   // Update the latest page snapshot for regression/freshness comparison
   if (ctx.site) {
     const snap = { taken_at: run.manifest.timestamp, run_id: run.runId, pages: {} };
     for (const p of ctx.site.pages) {
-      snap.pages[p.url] = { contentHash: ctx.hashPage(p), dateModified: extractModified(p), status: p.status };
+      snap.pages[p.url] = {
+        contentHash: p.extracted_text_hash ?? ctx.hashPage(p),
+        hash_semantics: 'extracted_text_v1',
+        extracted_text_hash: p.extracted_text_hash ?? ctx.hashPage(p),
+        response_body_hash: p.response_body_hash ?? null,
+        structured_data_hash: p.structured_data_hash ?? null,
+        evidence_hash: p.evidence_hash ?? null,
+        artifact_hash: p.artifact_hash ?? null,
+        resource_id: p.urlIdentity?.resource_id ?? null,
+        url_identity: p.urlIdentity ?? null,
+        dateModified: extractModified(p),
+        status: p.status,
+      };
     }
     const snapDir = path.join(root, '.citable', 'snapshots');
     fs.mkdirSync(snapDir, { recursive: true });
@@ -121,6 +184,10 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
 
   const status = run.manifest.errors.length ? 'completed_with_warnings'
     : run.manifest.incomplete_checks.length ? 'incomplete' : 'completed';
+  // Successful persistence/execution is independent from collection coverage
+  // and legacy warning status. A run with fetch warnings can still complete as
+  // an execution while its coverage remains indeterminate or truncated.
+  run.manifest.execution_status = 'completed';
   const dir = run.finalize(status);
   return { runId: run.runId, dir, findings, summary, manifest: run.manifest, report };
 }

package/src/commands/ciWorkflow.js

@@ -33,9 +33,14 @@ jobs:
 `;
 }
 
-export function formatPrReviewComment(findings = []) {
+export function formatPrReviewComment(findings = [], determination = null) {
   if (findings.length === 0) {
-    return '### ✅ Citable CRO Sentinel: All conversion funnels and components verified clean with zero detected friction.';
+    const status = determination?.determination_status || 'indeterminate';
+    if (status !== 'supported') {
+      const coverage = determination?.coverage_status ? ` (coverage: ${determination.coverage_status})` : '';
+      return `### ⚠️ Citable CRO Sentinel: No determination can be made from the available evidence${coverage}; insufficient evidence for a clean determination. No finding was observed in the evaluated subset; this is not a verified result.`;
+    }
+    return '### ✅ Citable CRO Sentinel: No findings were observed over the supported evidence scope.';
   }
 
   const lines = [