@nebulacomponents/citable 1.8.0 → 1.9.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/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.9.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -110,6 +110,11 @@ 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
@@ -169,7 +174,7 @@ 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, 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

package/skill/commands/README.md

@@ -28,6 +28,7 @@ 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 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/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,7 @@ 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
 
@@ -56,6 +57,11 @@ 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
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -255,6 +261,17 @@ 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 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

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,8 @@ 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' },
 ];
 
 export function contextDir(root) {
@@ -121,6 +123,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;
 }