@nebulacomponents/citable 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -71,7 +71,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.22.2"
+    "node": ">=24.0.0"
   },
   "license": "Apache-2.0",
   "repository": {

package/schemas/exception.schema.json

@@ -0,0 +1,70 @@
+{
+  "$id": "citable://schemas/exception.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Governed exception registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "exceptions" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["exception_id", "policy_id", "policy_hash", "status", "source_run_id", "finding_ids", "finding_hashes", "reason", "risk_statement", "residual_risk", "compensating_controls", "evidence_ids", "evidence_hashes", "owner_reviewer_id", "reviewer_assignments", "reviewer_independence", "created_at", "expires_at", "renewal_count", "renewal_limit", "invalidation_conditions", "audit_history"],
+        "properties": {
+          "exception_id": { "type": "string", "pattern": "^EXCEPTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "policy_id": { "type": "string", "pattern": "^POLICY-" },
+          "policy_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "status": { "type": "string", "enum": ["proposed", "approved", "revoked", "superseded"] },
+          "source_run_id": { "type": "string", "minLength": 1 },
+          "finding_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "finding_hashes": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+          "reason": { "type": "string", "minLength": 1 },
+          "risk_statement": { "type": "string", "minLength": 1 },
+          "residual_risk": { "type": "string", "enum": ["documented", "not_documented"] },
+          "compensating_controls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+          "evidence_ids": { "type": "array", "items": { "type": "string" } },
+          "evidence_hashes": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+          "owner_reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+          "reviewer_assignments": {
+            "type": "array", "minItems": 1,
+            "items": {
+              "type": "object", "additionalProperties": false, "required": ["reviewer_id", "role"],
+              "properties": {
+                "reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+                "role": { "type": "string", "enum": ["technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor", "remediation_implementer", "content_author"] }
+              }
+            }
+          },
+          "reviewer_independence": { "type": "string", "enum": ["established", "not_established", "conflicted"] },
+          "created_at": { "type": "string", "format": "date-time" },
+          "expires_at": { "type": "string", "format": "date-time" },
+          "renewal_count": { "type": "integer", "minimum": 0 },
+          "renewal_limit": { "type": "integer", "minimum": 0 },
+          "invalidation_conditions": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["finding_changed", "evidence_changed", "policy_changed", "resource_changed", "intervention_changed"] }
+          },
+          "related_intervention_id": { "type": ["string", "null"] },
+          "supersedes_exception_id": { "type": ["string", "null"] },
+          "superseded_by_exception_id": { "type": ["string", "null"] },
+          "audit_history": {
+            "type": "array", "minItems": 1,
+            "items": {
+              "type": "object", "additionalProperties": false, "required": ["timestamp", "actor_reviewer_id", "action", "note"],
+              "properties": {
+                "timestamp": { "type": "string", "format": "date-time" },
+                "actor_reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+                "action": { "type": "string", "enum": ["proposed", "approved", "renewed", "revoked", "superseded"] },
+                "note": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/review-policy.schema.json

@@ -0,0 +1,35 @@
+{
+  "$id": "citable://schemas/review-policy.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Review policy registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "review_policies" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["policy_id", "name", "status", "required_roles", "separation_rules", "max_exception_days", "max_renewals"],
+        "properties": {
+          "policy_id": { "type": "string", "pattern": "^POLICY-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["active", "deprecated"] },
+          "required_roles": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor"] }
+          },
+          "separation_rules": {
+            "type": "array", "uniqueItems": true,
+            "items": { "type": "string", "enum": ["author_cannot_verify_own_claim", "implementer_cannot_solely_verify", "commercial_owner_requires_independent_benefit_review", "risk_acceptor_must_be_authorized"] }
+          },
+          "max_exception_days": { "type": "integer", "minimum": 1, "maximum": 366 },
+          "max_renewals": { "type": "integer", "minimum": 0, "maximum": 20 }
+        }
+      }
+    }
+  }
+}

package/schemas/reviewer.schema.json

@@ -0,0 +1,32 @@
+{
+  "$id": "citable://schemas/reviewer.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Reviewer registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "reviewers" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reviewer_id", "name", "status", "roles", "authorized_scopes", "conflicts"],
+        "properties": {
+          "reviewer_id": { "type": "string", "pattern": "^REVIEWER-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["active", "inactive"] },
+          "roles": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["content_author", "evidence_owner", "technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor", "remediation_implementer"] }
+          },
+          "authorized_scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+          "conflicts": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  }
+}

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.7.0
+version: 1.8.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -108,6 +108,8 @@ citable connect disconnect --connection-id <id> [--write]
 citable objectives init --input <json|yaml> [--write]
 citable objectives validate
 citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
+citable governance validate [--ref-date YYYY-MM-DD]
+citable governance evaluate <run-id> [--ref-date YYYY-MM-DD]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -165,8 +167,9 @@ mandatory.
 ## Registries are the source of truth
 
 `.citable/` holds YAML registries for queries, prompts, entities, claims,
-evidence, pages, crawlers, competitors, experiments, metrics, objectives,
-interventions, and optional connection state, all schema-validated
+  evidence, pages, crawlers, competitors, experiments, metrics, objectives,
+  interventions, optional connection state, reviewers, review policies, and
+  governed exceptions, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in
@@ -175,6 +178,9 @@ interventions, and optional connection state, all schema-validated
   competitors, pricing). Mark entities `incomplete` and list `required_input`.
 - Claim status transitions toward `verified` require existing verified evidence
   plus human semantic review; automation only downgrades (fail-closed).
+- Never encode an accepted exception as a passed or resolved finding. Validate
+  reviewer authority and separation of duties, bind approval to exact source
+  finding/policy/evidence hashes, and report enforcement disposition separately.
 
 ## Fail-closed behaviour
 

package/skill/commands/README.md

@@ -27,6 +27,7 @@ intent, not executability, so statuses are strict:
 | /citable metrics import | implemented — validates declared CSV/JSON metrics and writes immutable observations |
 | /citable objectives init / validate | implemented — user-owned metric selection, cohorts, windows, and guardrails |
 | /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |
+| /citable governance validate / evaluate | implemented — validates reviewer and exception authority and emits immutable dispositions without changing failed findings |
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |

package/skill/commands/governance.md

@@ -0,0 +1,17 @@
+# Governance validation and exception evaluation
+
+Use `citable governance validate` before relying on any accepted exception. It
+validates reviewer roles and scopes, conflicts, policy requirements, separation
+of duties, source bindings, expiry, renewal, and referential integrity.
+
+Use `citable governance evaluate <run-id>` to create a new immutable evidence
+package. The command never edits the source run. Every source finding retains
+`technical_state: failed`; a valid exception is represented only as
+`enforcement_disposition: accepted_exception` with active validity and
+documented residual risk.
+
+Refuse authorization when policy, finding, or evidence hashes have changed;
+the exception is expired, revoked, superseded, conflicted, unauthorized, or
+over-renewed; required roles are absent; or more than one active exception
+matches a finding. Reviewer records are declarations and do not independently
+prove real-world identity, competence, independence, or legal authority.

package/skill/references/capability-boundaries.md

@@ -13,12 +13,17 @@ Use the narrowest supported state. Never promote evidence across rows.
 | Cited | Import or disclosed adapter | Complete `observe citations` answer with citation URL and product/adapter mode |
 | Materially supports answer | Human review required | `citation_review` maps answer claim to source passage and names the reviewer |
 | Recommended | Operator supplied + review | Explicit recommendation, constraints, provider/mode/locale/time |
+| Accepted exception | Governed owner record | Active policy, authorized reviewers, separation-of-duty checks, exact finding/policy/evidence hashes, expiry, controls, and documented residual risk |
 
 URL audit mode alone does not prove crawler identity, WAF allowlisting,
 production-log access, index presence, selected canonical, rendered DOM parity,
 or provider citation behavior. Observation collectors can supply narrower
 evidence for these states; unavailable inputs remain `not_evidenced`.
 
+An accepted exception changes enforcement disposition only. It does not change
+the source finding, prove remediation, or establish that reviewer identity,
+competence, independence, or legal authority was externally authenticated.
+
 Primary-source lineage for these boundaries:
 
 - Perplexity documents separate `PerplexityBot` and `Perplexity-User` purposes,

package/src/cli/index.js

@@ -17,6 +17,7 @@ import { applyRemediation } from '../commands/applyRemediation.js';
 import { monitor } from '../commands/monitor.js';
 import { evaluateObjective, importMetrics, initializeObjective, validateObjectives } from '../commands/measurement.js';
 import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
+import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -53,6 +54,8 @@ Commands
   objectives init           Validate/add one objective from --input (--write to save)
   objectives validate       Validate objective contracts and metric references
   evaluate [objective-id]   Compare objective baseline and evaluation windows
+  governance validate       Validate reviewer, policy, and exception controls
+  governance evaluate [run] Produce immutable enforcement dispositions without changing findings
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -238,6 +241,20 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args, `evaluate ${r.objective_id}: ${r.status}\n` + r.metrics.map((metric) => `  ${metric.metric_id}: ${metric.state}${metric.state === 'observed' ? ` (${metric.baseline} → ${metric.evaluation})` : ''}`).join('\n') + `\n${r.interpretation}`, r);
         break;
       }
+      case 'governance': {
+        const mode = args._[0];
+        if (mode === 'validate') {
+          const r = validateGovernance(root, { refDate: args.refDate });
+          out(args, `governance validate: ${r.ok ? 'OK' : 'PROBLEMS'} (${r.counts.reviewers} reviewer(s), ${r.counts.policies} policy/policies, ${r.counts.exceptions} exception(s))${r.problems.length ? `\n${r.problems.map((problem) => `  - ${problem}`).join('\n')}` : ''}`, r);
+          if (!r.ok) process.exitCode = 1;
+        } else if (mode === 'evaluate') {
+          const r = evaluateDispositions(root, { runId: args._[1], refDate: args.refDate });
+          const accepted = r.dispositions.filter((item) => item.enforcement_disposition === 'accepted_exception').length;
+          out(args, `governance evaluate ${r.source_run_id}: ${r.dispositions.length} failed finding(s), ${accepted} accepted exception(s)\nEvidence package: ${r.dir}`, r);
+          if (r.dispositions.some((item) => item.enforcement_disposition === 'blocked_ambiguous_exception')) process.exitCode = 1;
+        } else throw new Error('usage: citable governance <validate|evaluate [run-id]> [--ref-date YYYY-MM-DD]');
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/governance.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRun } from '../evidence/run.js';
+import { loadRegistries, checkReferentialIntegrity } from '../registries/index.js';
+import { readJson, sha256, parseRefDate } from '../shared/io.js';
+
+function recordHash(value) {
+  return sha256(JSON.stringify(value));
+}
+
+function assigned(exception, role) {
+  return exception.reviewer_assignments.filter((item) => item.role === role).map((item) => item.reviewer_id);
+}
+
+function reviewerCanAct(reviewer, role, finding) {
+  if (!reviewer || reviewer.status !== 'active' || !reviewer.roles.includes(role)) return false;
+  const scopes = reviewer.authorized_scopes || [];
+  return scopes.includes('*') || scopes.includes(finding.detector_id) || scopes.includes(finding.subject.identifier);
+}
+
+function exceptionProblems(exception, policy, reviewers, findings, evidence, refDate) {
+  const problems = [];
+  if (!policy || policy.status !== 'active') problems.push('review policy is missing or inactive');
+  if (exception.status !== 'approved') problems.push(`exception status is ${exception.status}`);
+  if (exception.residual_risk !== 'documented') problems.push('residual risk is not documented');
+  if (new Date(exception.expires_at) < refDate) problems.push('exception is expired');
+  if (exception.renewal_count > exception.renewal_limit) problems.push('exception renewal limit exceeded');
+  if (policy && exception.renewal_limit > policy.max_renewals) problems.push('exception renewal limit exceeds policy');
+  if (policy && new Date(exception.expires_at) - new Date(exception.created_at) > policy.max_exception_days * 86400000) problems.push('exception duration exceeds policy');
+  if (policy && recordHash(policy) !== exception.policy_hash) problems.push('policy changed since approval');
+  if (exception.superseded_by_exception_id) problems.push('exception is superseded');
+  const owner = reviewers.get(exception.owner_reviewer_id);
+  if (!owner || owner.status !== 'active') problems.push('exception owner is missing or inactive');
+
+  for (const findingId of exception.finding_ids) {
+    const finding = findings.get(findingId);
+    if (!finding) problems.push(`source finding ${findingId} is unavailable`);
+    else if (recordHash(finding) !== exception.finding_hashes[findingId]) problems.push(`source finding ${findingId} changed since approval`);
+  }
+  for (const evidenceId of exception.evidence_ids) {
+    const item = evidence.get(evidenceId);
+    if (!item) problems.push(`evidence ${evidenceId} is unavailable`);
+    else if (recordHash(item) !== exception.evidence_hashes[evidenceId]) problems.push(`evidence ${evidenceId} changed since approval`);
+  }
+
+  if (policy) {
+    for (const role of policy.required_roles) {
+      const actors = assigned(exception, role);
+      if (actors.length === 0) problems.push(`required role ${role} is unassigned`);
+      for (const actor of actors) {
+        const reviewer = reviewers.get(actor);
+        const scoped = exception.finding_ids.every((id) => findings.has(id) && reviewerCanAct(reviewer, role, findings.get(id)));
+        if (!scoped) problems.push(`${actor} is not active and authorized for role ${role} across the exception scope`);
+      }
+    }
+    const authors = new Set(assigned(exception, 'content_author'));
+    const implementers = new Set(assigned(exception, 'remediation_implementer'));
+    const verifiers = new Set([...assigned(exception, 'technical_reviewer'), ...assigned(exception, 'subject_matter_reviewer'), ...assigned(exception, 'independent_reviewer')]);
+    if (policy.separation_rules.includes('author_cannot_verify_own_claim') && [...authors].some((id) => verifiers.has(id))) problems.push('content author also verifies the scoped finding');
+    if (policy.separation_rules.includes('implementer_cannot_solely_verify') && verifiers.size === 1 && [...implementers].some((id) => verifiers.has(id))) problems.push('remediation implementer is the sole verifier');
+    if (policy.separation_rules.includes('commercial_owner_requires_independent_benefit_review') && exception.reviewer_independence !== 'established') problems.push('independent review is not established');
+    if (policy.separation_rules.includes('risk_acceptor_must_be_authorized') && assigned(exception, 'risk_acceptor').length === 0) problems.push('authorized risk acceptor is missing');
+  }
+  for (const assignment of exception.reviewer_assignments) {
+    const reviewer = reviewers.get(assignment.reviewer_id);
+    if (!reviewer) continue;
+    if (reviewer.status !== 'active' || !reviewer.roles.includes(assignment.role)) problems.push(`${reviewer.reviewer_id} is not active in assigned role ${assignment.role}`);
+    if ((reviewer.conflicts || []).some((scope) => exception.finding_ids.some((id) => findings.get(id)?.subject.identifier === scope))) problems.push(`${reviewer.reviewer_id} has a declared conflict with the exception scope`);
+  }
+  return [...new Set(problems)];
+}
+
+export function validateGovernance(root, { refDate } = {}) {
+  const { registries, problems: schemaProblems } = loadRegistries(root);
+  const problems = [...schemaProblems, ...checkReferentialIntegrity(registries)];
+  const reference = parseRefDate(refDate);
+  const reviewers = new Map(registries.reviewers.entries.map((item) => [item.reviewer_id, item]));
+  const policies = new Map(registries.review_policies.entries.map((item) => [item.policy_id, item]));
+  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 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) {
+      for (const findingId of exception.finding_ids) {
+        const key = `${exception.source_run_id}:${findingId}`;
+        activeByFinding.set(key, [...(activeByFinding.get(key) || []), exception.exception_id]);
+      }
+    }
+  }
+  for (const [scope, exceptionIds] of activeByFinding) {
+    if (exceptionIds.length > 1) problems.push(`ambiguous active exceptions for ${scope}: ${exceptionIds.join(', ')}`);
+  }
+  return { ok: problems.length === 0, problems, counts: { reviewers: reviewers.size, policies: policies.size, exceptions: registries.exceptions.entries.length } };
+}
+
+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 findings = new Map(sourceFindings.map((item) => [item.finding_id, item]));
+  const { registries, problems } = loadRegistries(root);
+  const integrity = checkReferentialIntegrity(registries);
+  if (problems.length || integrity.length) throw new Error(`registry validation failed: ${[...problems, ...integrity].join('; ')}`);
+  const reviewers = new Map(registries.reviewers.entries.map((item) => [item.reviewer_id, item]));
+  const policies = new Map(registries.review_policies.entries.map((item) => [item.policy_id, item]));
+  const evidence = new Map(registries.evidence.entries.map((item) => [item.evidence_id, item]));
+  const reference = parseRefDate(refDate);
+  const applicable = registries.exceptions.entries.filter((item) => item.source_run_id === runId);
+  const evaluations = applicable.map((exception) => {
+    const exceptionProblemsList = exceptionProblems(exception, policies.get(exception.policy_id), reviewers, findings, evidence, reference);
+    return { exception, validity: exceptionProblemsList.length ? 'invalid' : 'active', problems: exceptionProblemsList };
+  });
+  const dispositions = sourceFindings.map((finding) => {
+    const matches = evaluations.filter((item) => item.exception.finding_ids.includes(finding.finding_id));
+    const active = matches.filter((item) => item.validity === 'active');
+    return {
+      finding_id: finding.finding_id,
+      detector_id: finding.detector_id,
+      subject: finding.subject,
+      technical_state: 'failed',
+      enforcement_disposition: active.length === 1 ? 'accepted_exception' : active.length > 1 ? 'blocked_ambiguous_exception' : 'enforce',
+      exception_validity: active.length === 1 ? 'active' : matches.length ? (active.length > 1 ? 'ambiguous' : 'invalid') : 'not_applicable',
+      exception_id: active.length === 1 ? active[0].exception.exception_id : null,
+      residual_risk: active.length === 1 ? active[0].exception.residual_risk : 'not_documented',
+      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);
+  run.addInput('exceptions', registries.exceptions);
+  run.addInput('review-policies', registries.review_policies);
+  run.writeArtifact('dispositions.json', dispositions);
+  run.writeArtifact('exception-evaluations.json', evaluations.map(({ exception, ...evaluation }) => ({ exception_id: exception.exception_id, ...evaluation })));
+  run.manifest.warnings.push('Accepted exceptions alter enforcement disposition only; source findings remain failed and immutable.');
+  run.finalize(dispositions.some((item) => item.enforcement_disposition === 'blocked_ambiguous_exception') ? 'incomplete' : 'completed_with_warnings');
+  return { runId: run.runId, dir: run.dir, source_run_id: runId, dispositions, exception_evaluations: evaluations.length };
+}
+
+export { recordHash };

package/src/commands/selfUpgrade.js

@@ -21,7 +21,7 @@ const FETCH_TIMEOUT_MS = 10_000;
 
 /**
  * Fetch the latest published version from the npm registry.
- * Uses Node's built-in fetch (Node 22+); no extra dependencies.
+ * Uses Node's built-in fetch (Node 24+); no extra dependencies.
  *
  * @returns {Promise<string>} latest semver string
  */

package/src/registries/index.js

@@ -17,6 +17,9 @@ export const REGISTRY_SPECS = [
   { file: 'objectives.yaml', kind: 'objectives', schema: 'objective.schema.json', idField: 'objective_id' },
   { file: 'interventions.yaml', kind: 'interventions', schema: 'intervention.schema.json', idField: 'intervention_id' },
   { file: 'connections.yaml', kind: 'connections', schema: 'connection.schema.json', idField: 'connection_id' },
+  { file: 'reviewers.yaml', kind: 'reviewers', schema: 'reviewer.schema.json', idField: 'reviewer_id' },
+  { file: 'review-policies.yaml', kind: 'review_policies', schema: 'review-policy.schema.json', idField: 'policy_id' },
+  { file: 'exceptions.yaml', kind: 'exceptions', schema: 'exception.schema.json', idField: 'exception_id' },
 ];
 
 export function contextDir(root) {
@@ -104,6 +107,20 @@ export function checkReferentialIntegrity(registries) {
   for (const intervention of registries.interventions?.entries || []) {
     for (const ref of intervention.objective_ids || []) if (!objectiveIds.has(ref)) problems.push(`interventions/${intervention.intervention_id}: references unknown objective id "${ref}"`);
   }
+  const reviewerIds = ids.reviewers || new Set();
+  const policyIds = ids.review_policies || new Set();
+  const evidenceIds = ids.evidence || new Set();
+  const interventionIds = ids.interventions || new Set();
+  const exceptionIds = ids.exceptions || new Set();
+  for (const exception of registries.exceptions?.entries || []) {
+    const prefix = `exceptions/${exception.exception_id}`;
+    if (!policyIds.has(exception.policy_id)) problems.push(`${prefix}: references unknown review policy id "${exception.policy_id}"`);
+    const reviewerRefs = [exception.owner_reviewer_id, ...(exception.reviewer_assignments || []).map((item) => item.reviewer_id), ...(exception.audit_history || []).map((item) => item.actor_reviewer_id)];
+    for (const ref of reviewerRefs) if (ref && !reviewerIds.has(ref)) problems.push(`${prefix}: references unknown reviewer id "${ref}"`);
+    for (const ref of exception.evidence_ids || []) if (!evidenceIds.has(ref)) problems.push(`${prefix}: references unknown evidence id "${ref}"`);
+    if (exception.related_intervention_id && !interventionIds.has(exception.related_intervention_id)) problems.push(`${prefix}: references unknown intervention id "${exception.related_intervention_id}"`);
+    for (const ref of [exception.supersedes_exception_id, exception.superseded_by_exception_id]) if (ref && !exceptionIds.has(ref)) problems.push(`${prefix}: references unknown exception id "${ref}"`);
+  }
   return problems;
 }