@nebulacomponents/citable 1.8.0 → 1.10.0

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

@@ -0,0 +1,4 @@
+{
+  "$id":"citable://schemas/schedule.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Audit schedule registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
+  "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
+}

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.8.0
+version: 1.10.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -110,6 +110,13 @@ 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
+citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
+citable project github <run-id>
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -169,7 +176,8 @@ mandatory.
 `.citable/` holds YAML registries for queries, prompts, entities, claims,
   evidence, pages, crawlers, competitors, experiments, metrics, objectives,
   interventions, optional connection state, reviewers, review policies, and
-  governed exceptions, all schema-validated
+  governed exceptions, semantic review items, sampling plans, and audit schedules,
+  all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in

package/skill/commands/README.md

@@ -28,6 +28,8 @@ intent, not executability, so statuses are strict:
 | /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 schedules run / project github | implemented — canonical scheduled audits and hash-bound non-authoritative GitHub projections |
 | /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/delivery.md

@@ -0,0 +1,18 @@
+# Scheduling, projections, and differential delivery
+
+`citable schedules run <schedule-id>` executes the same canonical audit function
+used by direct CLI calls. Schedules are version-pinned and fail closed when
+paused, missing, invalid, or bound to another Citable version. The external
+cron service remains responsible for triggering the command; a declared cron
+does not prove execution. Schedule metadata is stored outside the finalized
+audit package and binds back to its manifest checksum.
+
+`citable project github <run-id>` creates GitHub annotation JSON as a
+non-authoritative projection. It records hashes of the source manifest and
+findings and never edits the run. Dashboards and check annotations must link to
+these artifacts rather than maintain separate finding state.
+
+`compare-snapshots` reports observed comparability dimensions: resource input,
+evidence artifact, detector set, configuration, observation method, tool
+version, and possible external-system change. These dimensions identify why
+runs may not be directly comparable; they do not establish causal attribution.

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/src/cli/index.js

@@ -18,6 +18,8 @@ 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';
+import { projectGithub, runSchedule } from '../commands/delivery.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -56,6 +58,13 @@ Commands
   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
+  schedules run [id]        Execute an active version-pinned audit schedule
+  project github [run]      Render non-authoritative GitHub annotations from a run
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -255,6 +264,29 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         } 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 'schedules': {
+        if(args._[0]!=='run') throw new Error('usage: citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]');
+        const r=await runSchedule(root,{scheduleId:args._[1],refDate:args.refDate});
+        out(args,`schedule ${r.schedule_execution.schedule_id}: audit ${r.runId}\nEvidence package: ${r.dir}\nExecution record: ${r.execution_file}`,r);
+        break;
+      }
+      case 'project': {
+        if(args._[0]!=='github') throw new Error('usage: citable project github <run-id>');
+        const r=projectGithub(root,{runId:args._[1]});
+        out(args,`project github ${r.source_run_id}: ${r.annotations.length} annotation(s)\nProjection: ${path.join(r.dir,'annotations.json')}`,r);
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/compareSnapshots.js

@@ -27,6 +27,16 @@ export function compareSnapshots(root, { runA, runB } = {}) {
   };
   const a = load(runA);
   const b = load(runB);
+  const changedKeys = (left = {}, right = {}) => [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+  const changeDimensions = {
+    resource_changed: changedKeys(a.manifest.input_hashes, b.manifest.input_hashes),
+    evidence_artifacts_changed: changedKeys(a.manifest.output_hashes, b.manifest.output_hashes),
+    detector_set_changed: JSON.stringify(a.manifest.detectors_run) !== JSON.stringify(b.manifest.detectors_run),
+    configuration_changed: a.manifest.configuration_hash !== b.manifest.configuration_hash,
+    observation_method_changed: a.manifest.command !== b.manifest.command || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv) || a.manifest.target?.kind !== b.manifest.target?.kind,
+    tool_changed: a.manifest.tool_version !== b.manifest.tool_version,
+    external_system_may_have_changed: a.manifest.target?.kind === 'url' || b.manifest.target?.kind === 'url',
+  };
   const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
   const aKeys = new Map(a.findings.map((f) => [key(f), f]));
   const bKeys = new Map(b.findings.map((f) => [key(f), f]));
@@ -38,6 +48,11 @@ export function compareSnapshots(root, { runA, runB } = {}) {
     baseline_timestamp: a.manifest.timestamp,
     comparison_timestamp: b.manifest.timestamp,
     regressions, resolved, persisting,
+    comparability: {
+      comparable: !changeDimensions.detector_set_changed && !changeDimensions.configuration_changed && !changeDimensions.observation_method_changed && !changeDimensions.tool_changed,
+      change_dimensions: changeDimensions,
+      limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
+    },
     summary: {
       new_findings: regressions.length,
       resolved_findings: resolved.length,

package/src/commands/delivery.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { audit } from './audit.js';
+import { loadRegistries } from '../registries/index.js';
+import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
+
+const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
+
+export async function runSchedule(root, { scheduleId, refDate } = {}) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const schedule = registries.schedules.entries.find((item) => item.schedule_id === scheduleId);
+  if (!schedule) throw new Error(`schedule not found: ${scheduleId}`);
+  if (schedule.status !== 'active') throw new Error(`schedule ${scheduleId} is ${schedule.status}`);
+  if (schedule.expected_tool_version !== PKG.version) throw new Error(`schedule ${scheduleId} expects Citable ${schedule.expected_tool_version}, current version is ${PKG.version}`);
+  const result = await audit(root, { target: schedule.audit.target, scope: schedule.audit.scope, baseUrl: schedule.audit.base_url, refDate });
+  const execution = { schedule_id: scheduleId, cron: schedule.cron, owner: schedule.owner, executed_at: nowIso(), run_id: result.runId, manifest_hash: sha256(fs.readFileSync(path.join(result.dir, 'manifest.json'))), limitations: schedule.limitations };
+  const executionFile = path.join(root, '.citable', 'schedule-executions', `${result.runId}.json`);
+  writeJson(executionFile, execution);
+  return { ...result, schedule_execution: execution, execution_file: executionFile };
+}
+
+function annotationLevel(severity) {
+  if (['critical', 'high'].includes(severity)) return 'failure';
+  if (severity === 'medium') return 'warning';
+  return 'notice';
+}
+
+export function projectGithub(root, { runId } = {}) {
+  if (!runId) throw new Error('projection requires a source run id');
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const findingsFile = path.join(runDir, 'findings.json');
+  const manifestFile = path.join(runDir, 'manifest.json');
+  if (!fs.existsSync(findingsFile) || !fs.existsSync(manifestFile)) throw new Error(`run ${runId} is missing findings or manifest evidence`);
+  const findingsBytes = fs.readFileSync(findingsFile);
+  const manifestBytes = fs.readFileSync(manifestFile);
+  const annotations = JSON.parse(findingsBytes).map((finding) => ({
+    level: annotationLevel(finding.classification.severity),
+    title: `${finding.detector_id}: ${finding.classification.severity}`,
+    message: finding.observation.summary,
+    path: finding.subject.source_file || null,
+    line: finding.subject.source_location ? Number(String(finding.subject.source_location).match(/\d+/)?.[0]) || null : null,
+    finding_id: finding.finding_id,
+  }));
+  const projection = { source_run_id: runId, source_manifest_hash: sha256(manifestBytes), source_findings_hash: sha256(findingsBytes), generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
+  const dir = path.join(root, '.citable', 'projections', 'github', runId);
+  writeJson(path.join(dir, 'annotations.json'), projection);
+  return { ...projection, dir };
+}

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/registries/index.js

@@ -20,6 +20,9 @@ export const REGISTRY_SPECS = [
   { 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' },
+  { file: 'review-items.yaml', kind: 'review_items', schema: 'review-item.schema.json', idField: 'review_item_id' },
+  { file: 'sampling-plans.yaml', kind: 'sampling_plans', schema: 'sampling-plan.schema.json', idField: 'sampling_plan_id' },
+  { file: 'schedules.yaml', kind: 'schedules', schema: 'schedule.schema.json', idField: 'schedule_id' },
 ];
 
 export function contextDir(root) {
@@ -121,6 +124,13 @@ export function checkReferentialIntegrity(registries) {
     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}"`);
   }
+  for (const item of registries.review_items?.entries || []) {
+    const prefix = `review_items/${item.review_item_id}`;
+    if (!policyIds.has(item.policy_id)) problems.push(`${prefix}: references unknown review policy id "${item.policy_id}"`);
+    for (const ref of [...(item.assigned_reviewer_ids || []), ...(item.decisions || []).map((decision) => decision.reviewer_id), item.adjudication?.reviewer_id].filter(Boolean)) if (!reviewerIds.has(ref)) problems.push(`${prefix}: references unknown reviewer id "${ref}"`);
+  }
+  const reviewItemIds = ids.review_items || new Set();
+  for (const plan of registries.sampling_plans?.entries || []) for (const ref of plan.selected_item_ids || []) if (!reviewItemIds.has(ref)) problems.push(`sampling_plans/${plan.sampling_plan_id}: references unknown review item id "${ref}"`);
   return problems;
 }