jev — Jev document-quality checks for AI-DLC

An AI-DLC plugin that adds three approval-gate checks to the planning stages, using TypeSafe's Jev classifier. Jev returns typed judgments with calibrated probabilities instead of text, so the checks can score a document piece by piece without asking a large model to read it.

jev-quality and jev-blocking run when these stages open their approval gate: Intent Capture, Scope Definition, Requirements Analysis, User Stories, Units Generation and Delivery Planning. jev-gaps runs at the Requirements Analysis gate, on requirements.md. Requirement checks run only on requirements.md and story checks only on stories.md; elsewhere those IDs are references, so only sections are checked.

Jev is a small-context classifier, not a reasoning model, so the checks never send it a whole document:

• Code splits each document into requirements, stories and sections, and handles anything a pattern can decide (Given/When/Then, the "As a … I want … so that" form, empty and TBD sections).
• Each piece goes to Jev as one request with named fields (project_intent, document_type, section, item) and every question about that piece asked together.
• Graded judgments use Score questions and yes/no conditions use Noul questions, with boundary cases written into the criteria.
• Code decides from the answer probabilities; scores such as measurable 7/8 are counted in code, never by the model.

jev-quality and jev-blocking check the quality of what is written. jev-gaps looks for what is left out, without asking Jev to reason about it:

• The checklist of concerns comes from code: AI-DLC's requirements completeness checklist, plus ownership, reference data and record lifecycle.
• For each concern Jev answers two narrow questions: is it addressed anywhere (a requirement, constraint, assumption, out-of-scope line or open question), and how much does the product in the intent statement depend on it (not at its stated size, good practice only, or its main flow depends on it).
• A gap is a concern that matters and is not addressed. The relevance question keeps a proof of concept from being told it lacks pagination or localisation.

It reports concerns that are missing, not whether an addressed concern is handled well; that stays with jev-quality and the reviewer.

Requires AI-DLC 2.10 or later.

Build the host projection with the AI-DLC plugin tools, then install it through your harness's plugin mechanism (see the AI-DLC plugin guide):

bun <aidlc-tools-dir>/aidlc-plugin-validate.ts jev
bun <aidlc-tools-dir>/aidlc-plugin-build.ts jev claude

Check the install with /aidlc --doctor: it confirms the plugin's files are composed and warns when no API key is set.

The variables must be visible to the environment AI-DLC's hooks run in.

The default thresholds were tuned on the small labelled samples in tests/fixtures/ (for jev-gaps, three requirements documents in tests/fixtures/gaps/). Check them against your own documents before relying on the blocking check.

jev-quality and jev-gaps report that they could not run and pass. jev-blocking still enforces its code checks (missing acceptance criteria, empty or TBD sections), skips the Jev check, passes, and says why in its result. No approval gate is held up by a missing key or an outage.

Enabling this plugin sends planning-document text (requirements, stories, section bodies and a short excerpt of the intent statement) to TypeSafe, or to OpenRouter if configured. Do not enable it for documents you cannot share with that provider.

Blocking results always stop the gate and show their findings. Advisory results reach the approval question once AI-DLC shows advisory gate-sensor results there (proposed upstream as sensor_notices); on earlier versions they are recorded in the audit log and the detail files under <record>/.aidlc-engine/sensors/<stage>/.

bun test tests/                  # offline tests
JEV_LIVE=1 bun test tests/       # also runs the labelled sample through the API

CI runs the offline tests, the compose test for every harness, and (on main, manually and weekly) the live sample when the TYPESAFE_API_KEY repository secret is set. Codex is allowed to fail until AI-DLC fixes its Codex compose hook.

Tool versions (bun, prek, pinact) live in mise.toml, with checksums pinned in mise.lock. CI installs them the same way through jdx/mise-action.

mise install                      # bun, prek and pinact at the pinned versions
mise run test                     # offline tests
GITHUB_TOKEN=$(gh auth token) mise run lint     # all prek hooks
mise run compose -- claude 2.10.0 # compose-test one harness (needs gh)
mise exec -- prek install         # run the hooks before each commit

Hooks: actionlint, zizmor, shellcheck, gitleaks, pinact and basic file checks. Actions are pinned to commit SHAs with verified version comments. Update them with mise exec -- pinact run -u; .pinact.yaml and Dependabot both hold back releases younger than 7 days.

MIT. See LICENSE.