Evaluation Contract Specification
Normative semantics for project contracts, evidence, criteria, findings, uncertainty, feedback, security, and conformance.
Foundation 0.1.0 is the contract, the decision policy, the schemas, and the validators for judging training data.
Copy the example contract, author each criterion in the template and shadow the system before autonomous decisions.
Schema, contract and decision-policy versions change independently, and an evaluation records the exact contract and policy it used.
The foundation package is a project-agnostic contract and benchmark for judging human-produced training data. It doesn't prescribe a model provider or framework.
It defines three conformance levels, and autonomous acceptance or rejection shouldn't be enabled until a system reaches Level B. Download it and run the included script to validate the examples.
A conforming implementation keeps ten distinctions apart, such as truth versus support and severity versus action. The minimal evaluator pipeline validates and freezes inputs first and persists the complete audit record last.
JSON Schemas are the runtime check, and the TypeScript interfaces aren't a trust boundary. Autonomous acceptance or rejection shouldn't run below Level B, which adds calibrated confidence and explicit abstention.
The current release leaves model choice, retrieval, prompts, chunking, calibration and the reviewer-competence model open. The package says to decide them by measurement once the contract and benchmark are stable. A case references an exact contract version and content hash.
A project-agnostic contract and benchmark package for evaluating human-produced AI-training data and the human annotations applied to it.
The package defines the stable domain boundary for an AutoQA system. It intentionally does not prescribe a model provider, orchestration framework, database, or Vercel implementation. Those components can change while the evaluation objects, proof obligations, decision policy, and benchmark remain versioned and auditable.
AutoQA evaluates two different objects:
It does not reduce evaluation to a single score. The core unit is a criterion assertion:
Criterion C applies.
Attempt span A exhibits behavior B.
Evidence E supports, contradicts, or is insufficient for B.
B does or does not satisfy C.
The project decision policy assigns consequence S.
A conforming implementation preserves these distinctions:
The engine may be project-agnostic. Its judgments may not be criterion-agnostic. Every production project must supply an approved, versioned evaluation contract.
.
+-- README.md
+-- CONTRACT_SPEC.md
+-- BENCHMARK_PROTOCOL.md
+-- DECISION_POLICY.md
+-- CHANGELOG.md
+-- VERSION
+-- schemas/
| +-- common.schema.json
| +-- project-contract.schema.json
| +-- case-input.schema.json
| +-- evaluation-output.schema.json
| +-- benchmark-item.schema.json
| +-- human-resolution-packet.schema.json
+-- types/
| +-- autoqa.ts
| +-- tsconfig.json
+-- examples/
| +-- project-contract.example.json
| +-- case-input.example.json
| +-- evaluation-output.example.json
| +-- benchmark-item.example.json
| +-- human-resolution-packet.example.json
+-- templates/
| +-- criterion-authoring-template.csv
| +-- gold-set-template.csv
| +-- model-bakeoff-template.csv
+-- validation/
+-- hash_utils.py
+-- validate_examples.py
+-- validate_package.py
CONTRACT_SPEC.md defines the normative semantics, lifecycle, invariants, and conformance requirements.BENCHMARK_PROTOCOL.md defines how to build adjudicated gold data, calibrate evaluators, run ablations, set launch gates, and monitor drift.DECISION_POLICY.md defines the recommended rule engine, action semantics, human-resolution trigger, and policy trace.Runtime input and output validation should use the JSON Schemas. TypeScript interfaces are provided for application development but are not a runtime trust boundary.
Validate the included examples:
python validation/validate_package.py
Type-check the TypeScript domain model:
cd types
tsc -p tsconfig.json
Recommended adoption sequence:
examples/project-contract.example.json and replace the synthetic instructions and criteria.templates/criterion-authoring-template.csv before converting it to JSON.case_input documents from historical production work.BENCHMARK_PROTOCOL.md.1. Validate and freeze inputs
2. Compile/load the approved project contract
3. Run deterministic integrity and compliance checks
4. Extract claims and expected elements
5. Map claims and requirements to evidence
6. Generate positive, negative, omission, and warrant observations
7. Challenge material observations
8. Adjudicate each criterion
9. Evaluate global qualities
10. Audit the human annotation independently
11. Apply the versioned decision policy
12. Ask at most one decision-changing human question when necessary
13. Generate and validate audience-specific feedback
14. Persist the complete audit record
The implementation validates inputs and outputs, uses an approved project contract, produces criterion-level assessments, and records evidence-linked findings.
Level A plus empirical confidence calibration, risk-coverage reporting, explicit abstention/escalation, and locked test suites.
Level B plus independent annotation auditing, one-interaction human resolution, shadow deployment, drift monitoring, replay, appeals, and restricted use of reviewer analytics.
Autonomous acceptance or rejection should not be enabled below Level B.
The included example contains a high-quality attempt that correctly concludes that the evidence does not establish a primary causal relationship. A human reviewer fails it for not choosing a forced yes/no answer. The project contract explicitly permits an inconclusive conclusion. The example evaluation therefore:
This demonstrates why attempt quality and annotation fidelity must be separate outputs.
Three versions may change independently:
A case must reference an exact contract version and content hash. An evaluation must record the exact case, contract, prompt, source snapshots, model runs, calibration profile, and decision-policy version used.
These should be decided empirically after the contract and benchmark are stable.
| File | Format | Size | SHA-256 |
|---|---|---|---|
| autoqa-foundation-v0.1.0.zip | ZIP | 78.3 KB | e020f1e46f91 |
Normative semantics for project contracts, evidence, criteria, findings, uncertainty, feedback, security, and conformance.
A target-specific rule engine for accept, rework, reject, and escalate decisions, including the bounded human interaction.
How to construct adjudicated gold data, calibrate evaluators, run ablations, set launch gates, and monitor drift.
Runtime schema for adjudicated truth, acceptable actions, ambiguity, challenge attributes, and leakage controls.
Runtime schema for task, evidence bundle, attempt, human review, references, and provenance.
Shared runtime definitions used by the project, case, evaluation, benchmark, and resolution schemas.
Runtime schema for claims, evidence relationships, findings, criterion assessments, decisions, annotation audit, and feedback.
Runtime schema for one bounded, decision-changing human question and its context.
Runtime schema for approved project instructions, criteria, evidence policy, decision policy, and calibration requirements.
Adjudicated benchmark record for the synthetic case, including acceptable outcomes and ambiguity metadata.
A strong attempt incorrectly failed by a human reviewer for not forcing an unsupported binary conclusion.
Complete AutoQA result accepting the attempt, returning the annotation for rework, and generating audience-specific feedback.
A bounded precedence question that hides the provisional decision and asks only what can change the outcome.
Synthetic closed-world evidence project with positive-proof requirements, anchors, severity, and explicit decision rules.
CSV template for drafting criterion intent, proof standards, failure anchors, evidence requirements, severity, and governance.
CSV template for building an adjudicated calibration and test set.
CSV template for comparing evaluator configurations by criterion family.
Strict TypeScript types for project contracts, cases, evaluations, benchmarks, findings, decisions, feedback, and human resolution.
Compiler configuration for the package's type definitions.
Current package version identifier.
Machine-readable inventory and hashes for the complete package.
Canonical content hashing utilities used by the validation suite.
Python validator for the package's example documents.
Cross-document, schema, hash, proof-invariant, policy, and package integrity checks.
Date: 2026-07-14 Status: Draft v1, synthesized from Question Inventory and Research Atlas. Every principle carries its evidence anchor; positions the evidence does not settle are marked [default] (my recommended posture, reversible) or [open decision] (needs your call). Scope: Project-agnostic foundation for QA of human-annotated AI training data.
Human attempters produce evaluative work products (annotations, ratings, critiques with rationales) under project instructions. Human reviewers who QA them exhibit unexplained variance in pass/fail rates and reasons. Root causes, ranked: (1) subjective interpretation of evaluation axes, (2) expertise gaps, (3) attention to detail. Attempters are mandatory; the QA layer is what we augment.
The psychometric literature sharpens this: after training, raters' global severity differences persist but are a minor variance component - the dominant variance is rater x item x criterion interaction: which reviewer, on which submission, on which criterion, this time. That variance cannot be fixed by better rubrics or calibration meetings alone. It can only be attacked by verifying each specific claim on each specific item against evidence - which is exactly what an LLM layer can do at scale and humans at scale cannot. That is the reason this system should exist, stated in the field's own terms. (Atlas Section 26)
Quality = satisfaction of the written project instructions + grounding in the defined evidence record. Not "would the median reviewer pass this." Human-consensus prediction caps the system's validity at the reviewers' own (unmeasured, evidently low) reliability ceiling; instruction-satisfaction lets the AutoQA be more valid than the layer it augments, and makes every verdict traceable to a clause and a span. (Atlas Section 16-18; peer-reviewed rating-indeterminacy work (NeurIPS 2025) shows forced-choice consensus gold labels can heavily bias judge selection - empirically up to 31% worse [AJ-02] - when criteria admit multiple valid readings.)
Consequences of this choice:
P1 - Claims, not vibes. The unit of analysis is the typed claim, not the item. Attempter writeups are decomposed into claims of distinct types, each verified in the lane built for it, each verdict carrying quoted evidence. Item verdicts are transparent, auditable roll-ups. (Holistic judging of subjective quality measurably fails: near-orthogonal judge/human axes; ~55% on hard per-criterion checks [AJ-04]; long-form instability. Decomposed per-criterion reasoning buys +7-12pp [AJ-04] and lower cross-judge variance.)
P2 - The claim ontology is the type system. Every extracted statement is triaged before any verification: (a) grounding claims (cited evidence exists and says this), (b) entailment claims (evidence supports the conclusion drawn), (c) calibration claims (stated severity/confidence matches evidence strength), (d) completeness/absence claims ("no errors," "fully addresses"), (e) opinions - never truth-scored, but checked with real machinery via two reusable passes: stance-contradiction (the evidence the attempter cites must not contradict the stated stance) and stance-calibration (stance strength must not exceed evidence strength - type-(c) machinery). Opinion verdicts are consistent / inconsistent-with-cited-evidence (a fail-able finding: the opinion's warrant fails grounding, not the opinion itself) / uncheckable (never penalized) - (f) undecidable-given-evidence. Each type has different machinery and a different reliability ceiling, reported per type.
Entailment standard [default]: reasonable-expert support, not strict logical entailment - three-way output per claim (supported / contradicted / unsupported), where contradicted is the high-confidence fail trigger and unsupported alone triggers an evidence request or escalation rather than an automatic fail. Strict entailment fails nearly all competent human prose; loose support reintroduces the variance we're removing - so the false-flag rate under this standard is a measured ship-gate output (Section 4.3), not an assumption. (VeriScore/FactBench triage is field-standard; FACTS shows the positive-class asymmetry; AbsenceBench caps type (d).)
P3 - Evidence closure is explicit and judge priors are not evidence. Every project config defines the evidence record: what the attempter saw, what they cited, what's in scope. Verdicts must quote spans from that record to be admissible; "true in the world but unsupported in the record" is unsupported, not pass. Checks are routed by whether they are read-checkable or recompute-checkable - judge confidence is untrustworthy on checks that exceed its own solving ability, where it silently re-solves and trusts itself over the record. [default - provisional: the re-solving evidence is a single under-review 2026 study; experiment 3 replicates it internally before this hard-gates routing.] Cherry-picking is caught by running both span-closed and context-closed citation checks. The judge gets the same evidence surface the attempter had - architecture beats model. (Auditing-by-Re-Solving; CiteEval; agent-judge/the banking meta-eval.)
P4 - Positive claims are verified by enumerated class, with honest labels. "Warranted praise" verification is restricted to checkable praise types compiled per project (accuracy-praise -> grounding check; completeness-praise -> enumerable checklist; clarity-praise -> opinion class). Absence claims get a seeded-defect protocol: unless the judge's planted-flaw recall on this project materially exceeds the attempter population's, its concurrence is labeled not-contradicted, never verified. A vacuousness/eligibility gate precedes grounding checks so hedged empty writeups can't pass by asserting nothing. (FACTS eligibility gate; AbsenceBench; zero published praise-verification numbers - this is the first in-house measurement.)
P5 - Typed verdicts; abstention and contestation are first-class. The verdict set is pass / fail / unable-to-verify / instructions-underdetermine. High vote-entropy across k samples, cross-family judge disagreement, and clustered reviewer disagreement route items to the contested class - which feeds the instruction-gap channel and never penalizes the attempter. This is how the system enforces consistency where consistency is real, without laundering one arbitrary reading of a contested criterion into false objectivity. (Toloka's deployed Pass/Fail/Unable-to-verify; CoVal; NUTMEG; rating indeterminacy.)
P6 - The human touch is spent where it compounds, and it is blind. Routing is confidence-calibrated three-lane (auto-verdict / stronger judge / human) with the human budget derived from a target residual error rate, not a fixed per-item quota. The escalated human sees the claim, the criterion clause, and the judge's collected evidence spans - not its verdict or rationale (verdict-visible review produces measured over-reliance; evidence-only is the sole format that helps when the AI is right without hurting when it's wrong). Escalation routes the contested claim, not the whole item. Every human adjudication writes back - in two tiers that keep the ground-truth hierarchy honest: a single-touch adjudication produces candidate artifacts (logged claims, provisional exemplars), and only panel-adjudicated or owner-signed artifacts enter judge calibration and compiled config; the standing audit channel batch-promotes candidates. In enforcement mode the human budget is max(target-residual-error escalations, consequential-fail volume - Section 5); under a pace-bound profile (P11) capacity binds instead, and the residual error rate becomes the reported output rather than the target - never pretend to optimize both. The evidence-only-for-adjudicators result is measured; combining it with full critiques to attempters (P9) is an inferred, untested split [default], A/B'd in experiment 6. Overturn-rate monitoring proves the human lane adds signal; an overturn rate at the judge's error floor means rubber-stamping, and the naive human-verifies-AI design is the modal failure in the literature. (Trust-or-Escalate/HyPAC; DeepMind complementarity; Vaccaro meta-analysis; Braintrust/LangChain/micro1 write-back practice.)
P7 - The QA layer is measured exactly like what it measures. The judge is enrolled as one more rater facet in the same measurement model as the humans (MFRM-style severity/centrality/fit per rater, human or machine, per project). Scope honestly: MFRM needs 3-5 ratings/output of rater-item linkage, so it runs fully on the dual-review pilot and continuously on the judge facet (which rates everything); production human-reviewer severity is estimable only where deliberate overlap is injected - a low-rate stream of double-reviewed seeded items, a budgeted cost, not a free byproduct. All reporting uses chance-corrected statistics, per-class recall at fixed prevalence, and PPI-corrected population estimates with dual-uncertainty CIs - raw percent-agreement and single-number "accuracy vs humans" are banned artifacts. Feedback passes the same grounding gate it enforces before delivery (fail-closed). Validation stratifies by measured human-agreement level; verdict-agreement alone never certifies a judge, because right-verdict-wrong-rationale poisons feedback and trust (in one benchmark, 24.8% of items got the right verdict with a low-quality critique - RealCritic [CM-08]). Staging [default]: v1 ships chance-corrected agreement, PPI-corrected point estimates with CIs, and k-sample entropy routing; MFRM production enrollment, anytime-valid e-processes, and conformal routing are phase-2 refinements - the full stack is the target, not the launch gate. (MFRM-for-LLM-judges; kappa-deflation cohort; BeyondCorrelation; RealCritic; MetaCritique.)
P8 - Adversarial by construction, from day one. Attempters are paid optimizers; some are agents. Defenses are structural, not detective: stakes-sterile judge prompts (consequence framing measurably softens verdicts with zero CoT trace); comparative/anchored scoring over absolute scales (transfer attacks inflate absolute scores blind); evidence-perturbation probes as a standing citation-theater detector (swap the cited span -> verdict must flip); blind seeded gold injected into live queues (indistinguishability is the binding constraint); the divergence sensor - attempter scores rising on the AutoQA while flat on held-out human-graded goldens - as the canonical Goodhart alarm; spam defense that is economics/provenance-based (throttling, work-history consistency, worker-level peer-prediction scoring, randomized deep audits), with content detection demoted to a weak auxiliary signal. Never score anyone on agreement-with-final-verdict - consensus-rewarded auditing trains your best dissenters to conform exactly where independent judgment matters most. (Evaluation Faking; universal adversarial phrases; TSPA; Westwood PNAS; Community Notes conformity study.)
P9 - Feedback is an instrumented intervention, not decoration and not free. The feedback unit is the 4-tuple: quoted claim, evidence span, criterion clause, concrete fix - task-referenced always, person- or rank-referenced never (a third of feedback interventions reduce performance [CG-19]; high-information task feedback roughly doubles the effect of bare verdicts [CG-22]). Benchmark against exemplar work, never ranked peers. No stylistic guidance by default - feedback is a homogenization pump aimed at the diversity the training data exists to capture, so a population-level output-diversity drift metric ships with the channel. Efficacy is measured per-attempter (repeat-error-rate per criterion, pre/post), expecting modest median effects concentrated in low performers, and separating within-attempter learning from attrition. If high-information feedback doesn't move repeat-error rates in a defined window, conclude decoration and reallocate. (Kluger & DeNisi; Wisniewski; Cochrane 2025; Dow CSCW 2012; monoculture evidence.)
P10 - Everything drifts; every moving part gets its own sensor. Frozen human-labeled anchor sets interleaved into the live stream attribute drift (judge moved vs population moved) with anytime-valid statistics. Judge versions are pinned per project with golden-set regression gates on upgrade; rubric revision is a versioned loop with explicit retroactive re-scoring policy (adaptation lives in the compilation layer, pinning at the judge layer - that's the resolution of the static-vs-co-evolving fork). Reviewer calibration decays within a session, so reviewer-effect estimates run in rolling windows with hard-item interleaving and order randomization; graduated projects carry randomized, unpredictable audit rates with automatic de-graduation triggers. Queue composition is managed (seeded known-verdict items, easy-case dilution) because prefiltered queues measurably shift reviewer strictness. (Anchor-set e-process work; DRIFT/OSCE; Pinterest dual monitors; content-moderation practice.)
P11 - Quality is a priced dial on disposition, never on perception. Contractual pace sometimes makes the standard quality threshold unaffordable; the system supports that honestly instead of forcing the loosening to happen off the books. The judge always measures the same way - dial-sterile prompts, same claim verification, same evidence dossier (consequence framing measurably corrupts verdicts with zero CoT trace, and a "be lenient" judge destroys score comparability, calibration, and the divergence sensor simultaneously). Leniency is applied downstream, as thresholds over the continuous scores the pipeline already emits. A project's active operating profile (e.g., strict / standard / expedited) moves exactly four things: aggregation cutoffs (how many/how severe findings fail an item), routing thresholds (escalation rate, human budget), verification depth (k-samples, deep-verify sampling fraction, expensive lanes like context-closed citation checks), and enforcement disposition (findings -> fail vs findings -> coaching-only). Two constraints can bind: in error-target mode the residual error rate is the target and human budget is the output; in pace-bound mode (contractual throughput) capacity binds and the residual error rate becomes the reported output - either way the number is computed and stamped, never hidden, with CIs that honestly widen when verification depth is thinned. Because measurement persists under every profile, the dial has two independent consumers: the attempter-disposition dial (prospective only, logged, announced - the bar people are judged against never moves silently or retroactively) and the dataset-admission dial (re-tunable at any time - an expedited batch can be re-filtered to any strictness later from the recorded scores, without re-running QA; the data buyer's strictness is not coupled to the deadline that produced the batch). Floors the dial can never touch: integrity-class verdicts (fabrication, spam, falsehood), seeded-gold injection and audit sampling, the divergence sensor (which conditions on the active profile and reads seeded/audit outcomes, not pass rates), and the Section 5 legal floor. Every delivered batch carries its profile and its corrected residual-error estimate - leniency becomes a contractual artifact instead of quiet degradation. (Evaluation Faking -> dial-sterile prompts; CriticGPT's FSBS precision/comprehensiveness dial as the precedent for inference-time operating points; Trust-or-Escalate's coverage dial; HyPAC error budgets; corrected-estimator reporting.)
This section is published once, on System.
A project's judge config ships only after:
Beyond go/no-go, the ship gate's data product is the operating-point curve - thresholds -> fail-class recall and false-pass rate at pilot prevalence. This is what calibrates P11's dial profiles, so even the expedited setting ships with a priced, not guessed, error rate.
These are design notes on how the cited law could constrain a QA system, not legal advice.
Gate first [open decision]: determine whether the attempter population includes EU-resident workers. If yes, this section is a launch constraint; if the pilot is US-only, treat it as forward-looking scope and revisit before any EU expansion. From 2026-12-02 (Platform Work Directive transposition), for attempters in the EU - employee or self-employed, platform established anywhere:
Convenient truth: the legally mandated design (meaningful human on adverse decisions, explanations, appeals) is the same design the complementarity evidence recommends anyway.
verified label on absence claims without seeded-recall evidence.Lineage: brainstorm (92 questions, 7 lenses) -> taxonomy (9 themes, 8 tensions) -> 9-domain recency-biased sweep + 27 adversarial verifications + 4 gap-fill literatures -> this synthesis. Full provenance in domain reports.
Source: documents/view/foundation-readme-md.html