@nebulacomponents/citable 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.7.0",
+  "version": "1.9.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-item.schema.json

@@ -0,0 +1,12 @@
+{
+  "$id":"citable://schemas/review-item.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Semantic review item registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
+  "properties":{"version":{"const":1},"kind":{"const":"review_items"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,
+    "required":["review_item_id","source_run_id","finding_id","finding_hash","review_type","status","priority_inputs","priority_score","priority_tier","missing_inputs","policy_id","assigned_reviewer_ids","decisions","created_at"],
+    "properties":{"review_item_id":{"type":"string","pattern":"^REVIEW-[A-Z0-9][A-Z0-9_-]*$"},"source_run_id":{"type":"string"},"finding_id":{"type":"string"},"finding_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},
+      "review_type":{"type":"string","enum":["claim_support","citation_correctness","passage_integrity","narrative_accuracy","recommendation_eligibility","comparison_fairness","intent_alignment","evidence_strength","general_semantic_review"]},
+      "status":{"type":"string","enum":["queued","assigned","in_review","adjudication_required","completed","withdrawn"]},
+      "priority_inputs":{"type":"object","additionalProperties":false,"required":["business_importance","citation_frequency","evidence_age_days","source_authority","regulatory_exposure","intervention_impact","change_magnitude","disagreement_history"],"properties":{"business_importance":{"type":["integer","null"],"minimum":0,"maximum":5},"citation_frequency":{"type":["integer","null"],"minimum":0},"evidence_age_days":{"type":["integer","null"],"minimum":0},"source_authority":{"type":["integer","null"],"minimum":0,"maximum":5},"regulatory_exposure":{"type":["integer","null"],"minimum":0,"maximum":5},"intervention_impact":{"type":["integer","null"],"minimum":0,"maximum":5},"change_magnitude":{"type":["integer","null"],"minimum":0,"maximum":5},"disagreement_history":{"type":["integer","null"],"minimum":0}}},
+      "priority_score":{"type":"number","minimum":0},"priority_tier":{"type":"string","enum":["urgent","high","normal","insufficient_inputs"]},"missing_inputs":{"type":"array","items":{"type":"string"}},"policy_id":{"type":"string","pattern":"^POLICY-"},"assigned_reviewer_ids":{"type":"array","uniqueItems":true,"items":{"type":"string","pattern":"^REVIEWER-"}},
+      "decisions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["reviewer_id","verdict","rubric","evidence_refs","rationale","decided_at","review_item_hash"],"properties":{"reviewer_id":{"type":"string","pattern":"^REVIEWER-"},"verdict":{"type":"string","enum":["supported","partially_supported","unsupported","inconclusive","not_applicable"]},"rubric":{"type":"string"},"evidence_refs":{"type":"array","minItems":1,"items":{"type":"string"}},"rationale":{"type":"string","minLength":1},"decided_at":{"type":"string","format":"date-time"},"review_item_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}},"adjudication":{"type":["object","null"],"additionalProperties":false,"required":["reviewer_id","verdict","evidence_refs","rationale","decided_at","review_item_hash"],"properties":{"reviewer_id":{"type":"string","pattern":"^REVIEWER-"},"verdict":{"type":"string","enum":["supported","partially_supported","unsupported","inconclusive","not_applicable"]},"evidence_refs":{"type":"array","minItems":1,"items":{"type":"string"}},"rationale":{"type":"string","minLength":1},"decided_at":{"type":"string","format":"date-time"},"review_item_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"created_at":{"type":"string","format":"date-time"}
+    }}}}
+}

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/schemas/sampling-plan.schema.json

@@ -0,0 +1,4 @@
+{
+  "$id":"citable://schemas/sampling-plan.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Semantic review sampling plan registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
+  "properties":{"version":{"const":1},"kind":{"const":"sampling_plans"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["sampling_plan_id","status","method","population_statuses","review_types","sample_size","seed","inclusion_criteria","exclusion_criteria","reviewer_assignment_method","extrapolation_limits","population_hash","selected_item_ids","created_at"],"properties":{"sampling_plan_id":{"type":"string","pattern":"^SAMPLE-[A-Z0-9][A-Z0-9_-]*$"},"status":{"type":"string","enum":["draft","selected","completed"]},"method":{"type":"string","enum":["census","simple_random"]},"population_statuses":{"type":"array","minItems":1,"items":{"type":"string","enum":["queued","assigned","in_review","adjudication_required","completed"]}},"review_types":{"type":"array","items":{"type":"string"}},"sample_size":{"type":"integer","minimum":1},"seed":{"type":"string","minLength":1},"inclusion_criteria":{"type":"array","items":{"type":"string"}},"exclusion_criteria":{"type":"array","items":{"type":"string"}},"reviewer_assignment_method":{"type":"string","minLength":1},"extrapolation_limits":{"type":"array","minItems":1,"items":{"type":"string"}},"population_hash":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$"},"selected_item_ids":{"type":"array","uniqueItems":true,"items":{"type":"string","pattern":"^REVIEW-"}},"created_at":{"type":"string","format":"date-time"}}}}}
+}

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.9.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -108,6 +108,13 @@ 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]
+citable reviews queue <run-id> <policy-id> [--write]
+citable reviews prioritize [--write]
+citable reviews plan --input <json|yaml> [--write]
+citable reviews sample <sampling-plan-id> [--write]
+citable reviews evaluate
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -165,8 +172,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, semantic review items, and sampling plans, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in
@@ -175,6 +183,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,8 @@ 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 reviews queue / prioritize / plan / sample / evaluate | implemented — materiality queues, reproducible sampling, stale-decision checks, and independent disagreement adjudication |
 | /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/commands/reviews.md

@@ -0,0 +1,18 @@
+# Semantic review queues and sampling
+
+Use `reviews queue` to create hash-bound review work from heuristic or
+review-required findings. Newly queued items expose all missing materiality
+inputs and remain `insufficient_inputs`; model confidence alone never controls
+priority. After authorized operators supply business importance, citation
+frequency, evidence age and authority, regulatory exposure, intervention
+impact, change magnitude, and disagreement history, use `reviews prioritize`.
+
+Sampling plans support only `census` and reproducible `simple_random` methods.
+Every selection records its seed, population hash, inclusion/exclusion criteria,
+assignment method, and extrapolation limits. Do not present sampled review as
+complete validation or generalize beyond the recorded population.
+
+`reviews evaluate` rejects stale or unauthorized decisions. Distinct verdicts
+produce `adjudication_required`; vote counting never establishes semantic truth.
+Completion requires an evidence-linked, hash-bound decision from an active
+independent reviewer.

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,8 @@ 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';
+import { evaluateReviews, initializeSamplingPlan, prioritizeReviews, queueReviews, selectSample } from '../commands/reviews.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -53,6 +55,13 @@ 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
+  reviews queue [run policy] Create semantic review work from heuristic findings
+  reviews prioritize        Rank review work from explicit materiality inputs
+  reviews plan              Validate/add a sampling plan from --input
+  reviews sample [plan]     Select a reproducible census or seeded random sample
+  reviews evaluate          Detect stale decisions and require disagreement adjudication
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -238,6 +247,31 @@ 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 'reviews': {
+        const mode=args._[0]; let r;
+        if(mode==='queue') r=queueReviews(root,{runId:args._[1],policyId:args._[2],write:args.write});
+        else if(mode==='prioritize') r=prioritizeReviews(root,{write:args.write});
+        else if(mode==='plan') r=initializeSamplingPlan(root,{input:args.input,write:args.write});
+        else if(mode==='sample') r=selectSample(root,{planId:args._[1],write:args.write});
+        else if(mode==='evaluate') { r=evaluateReviews(root); if(!r.ok) process.exitCode=1; }
+        else throw new Error('usage: citable reviews <queue|prioritize|plan|sample|evaluate> [options]');
+        out(args,`reviews ${mode}: ${r.created?.length ?? r.items?.length ?? r.selected_item_ids?.length ?? r.results?.length ?? 1} item(s)${args.write?' written':' (dry run)'}`,r);
+        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/reviews.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRegistries, saveRegistry } from '../registries/index.js';
+import { readJson, readYaml, sha256, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const INPUTS = ['business_importance','citation_frequency','evidence_age_days','source_authority','regulatory_exposure','intervention_impact','change_magnitude','disagreement_history'];
+const SEVERITY = { critical: 25, high: 20, medium: 12, low: 6, informational: 2, experimental: 1 };
+
+export function reviewBindingHash(item) {
+  const { decisions, status, adjudication, ...bound } = item;
+  return sha256(JSON.stringify(bound));
+}
+
+function priority(item, finding) {
+  const missing = INPUTS.filter((key) => item.priority_inputs[key] == null);
+  const p = item.priority_inputs;
+  const score = (SEVERITY[finding?.classification?.severity] || 0) + (p.business_importance || 0) * 4 + Math.min(p.citation_frequency || 0, 10) + Math.min((p.evidence_age_days || 0) / 30, 10) + (5 - (p.source_authority ?? 5)) * 2 + (p.regulatory_exposure || 0) * 5 + (p.intervention_impact || 0) * 3 + (p.change_magnitude || 0) * 2 + Math.min((p.disagreement_history || 0) * 3, 12);
+  return { score, tier: missing.length ? 'insufficient_inputs' : score >= 60 ? 'urgent' : score >= 35 ? 'high' : 'normal', missing };
+}
+
+export function queueReviews(root, { runId, policyId, write = false }) {
+  if (!runId || !policyId) throw new Error('reviews queue requires <run-id> <policy-id>');
+  const file = path.join(root,'.citable','runs',runId,'findings.json');
+  if (!fs.existsSync(file)) throw new Error(`source findings not found for run ${runId}`);
+  const findings = readJson(file);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  if (!registries.review_policies.entries.some((p) => p.policy_id === policyId && p.status === 'active')) throw new Error(`active review policy not found: ${policyId}`);
+  const existing = new Set(registries.review_items.entries.map((i) => `${i.source_run_id}:${i.finding_id}`));
+  const candidates = findings.filter((f) => !f.classification.deterministic || f.remediation.review_required).filter((f) => !existing.has(`${runId}:${f.finding_id}`));
+  const created = candidates.map((finding) => {
+    const item = { review_item_id:`REVIEW-${sha256(`${runId}:${finding.finding_id}`).slice(0,12).toUpperCase()}`,source_run_id:runId,finding_id:finding.finding_id,finding_hash:sha256(JSON.stringify(finding)),review_type:'general_semantic_review',status:'queued',priority_inputs:Object.fromEntries(INPUTS.map((k)=>[k,null])),priority_score:0,priority_tier:'insufficient_inputs',missing_inputs:[...INPUTS],policy_id:policyId,assigned_reviewer_ids:[],decisions:[],adjudication:null,created_at:nowIso() };
+    const ranked = priority(item,finding); item.priority_score=ranked.score; item.priority_tier=ranked.tier; item.missing_inputs=ranked.missing; return item;
+  });
+  if (write && created.length) saveRegistry(root,'review_items',{...registries.review_items,entries:[...registries.review_items.entries,...created]});
+  return { source_run_id:runId, created, written:write };
+}
+
+export function prioritizeReviews(root, { write = false } = {}) {
+  const { registries, problems } = loadRegistries(root); if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const cache = new Map();
+  const entries = registries.review_items.entries.map((item) => { const file=path.join(root,'.citable','runs',item.source_run_id,'findings.json'); if(!cache.has(file)) cache.set(file,fs.existsSync(file)?new Map(readJson(file).map(f=>[f.finding_id,f])):new Map()); const ranked=priority(item,cache.get(file).get(item.finding_id)); return {...item,priority_score:ranked.score,priority_tier:ranked.tier,missing_inputs:ranked.missing}; });
+  if(write) saveRegistry(root,'review_items',{...registries.review_items,entries});
+  return { items:entries.sort((a,b)=>b.priority_score-a.priority_score), written:write };
+}
+
+export function initializeSamplingPlan(root,{input,write=false}) {
+  if(!input || !fs.existsSync(input)) throw new Error('reviews plan requires --input <json|yaml>');
+  const plan=path.extname(input).match(/ya?ml/i)?readYaml(input):readJson(input); const {registries}=loadRegistries(root);
+  const candidate={...registries.sampling_plans,entries:[...registries.sampling_plans.entries,plan]};
+  const check=validateAgainst('sampling-plan.schema.json',candidate); if(!check.valid) throw new Error(`sampling plan violates contract: ${check.errors.join('; ')}`);
+  if(write) saveRegistry(root,'sampling_plans',candidate);
+  return { plan, written:write };
+}
+
+export function selectSample(root,{planId,write=false}) {
+  const {registries,problems}=loadRegistries(root); if(problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const plan=registries.sampling_plans.entries.find(p=>p.sampling_plan_id===planId); if(!plan) throw new Error(`sampling plan not found: ${planId}`);
+  const population=registries.review_items.entries.filter(i=>plan.population_statuses.includes(i.status) && (!plan.review_types.length||plan.review_types.includes(i.review_type))).sort((a,b)=>a.review_item_id.localeCompare(b.review_item_id));
+  if(!population.length) throw new Error('sampling population is empty');
+  if(plan.method==='simple_random' && plan.sample_size>population.length) throw new Error('sample_size exceeds population');
+  const selected=plan.method==='census'?population:[...population].sort((a,b)=>sha256(`${plan.seed}:${a.review_item_id}`).localeCompare(sha256(`${plan.seed}:${b.review_item_id}`))).slice(0,plan.sample_size);
+  const updated={...plan,status:'selected',population_hash:sha256(JSON.stringify(population.map(i=>[i.review_item_id,reviewBindingHash(i)]))),selected_item_ids:selected.map(i=>i.review_item_id)};
+  if(write) saveRegistry(root,'sampling_plans',{...registries.sampling_plans,entries:registries.sampling_plans.entries.map(p=>p.sampling_plan_id===planId?updated:p)});
+  return { plan:updated,population_size:population.length,selected_item_ids:updated.selected_item_ids,written:write };
+}
+
+export function evaluateReviews(root) {
+  const {registries,problems}=loadRegistries(root); const reviewers=new Map(registries.reviewers.entries.map(r=>[r.reviewer_id,r])); const results=[];
+  for(const item of registries.review_items.entries){const issues=[];const binding=reviewBindingHash(item);const source=path.join(root,'.citable','runs',item.source_run_id,'findings.json');const finding=fs.existsSync(source)?readJson(source).find(f=>f.finding_id===item.finding_id):null;if(!finding||sha256(JSON.stringify(finding))!==item.finding_hash)issues.push('source finding is unavailable or changed');for(const d of item.decisions){const r=reviewers.get(d.reviewer_id);const reviewRole=r?.roles.some(role=>['technical_reviewer','subject_matter_reviewer','independent_reviewer'].includes(role));if(!r||r.status!=='active'||!reviewRole||!item.assigned_reviewer_ids.includes(d.reviewer_id))issues.push(`${d.reviewer_id} is not an active assigned semantic reviewer`);if(d.review_item_hash!==binding)issues.push(`${d.reviewer_id} decision is stale`);}const verdicts=[...new Set(item.decisions.map(d=>d.verdict))];let state=item.decisions.length?'completed':'review_required';if(verdicts.length>1){state='adjudication_required';const a=reviewers.get(item.adjudication?.reviewer_id);if(item.adjudication&&a?.status==='active'&&a.roles.includes('independent_reviewer')&&item.adjudication.review_item_hash===binding)state='completed';else issues.push('reviewer disagreement requires a current decision from an active independent adjudicator');}results.push({review_item_id:item.review_item_id,state,verdict:state==='completed'&&!issues.length?(item.adjudication?.verdict||verdicts[0]):null,issues});}
+  return {ok:problems.length===0&&results.every(r=>!r.issues.length),problems,results};
+}

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
  */