# Eval

> Checkpoint a change against its spec's acceptance criteria — run the machine-checks, adjudicate the prose ones, and gate ship until every criterion passes. Opt-in; not wired into the default pipeline. Use late in Verify, alongside /test and /verify.

- Skill: `vasuag09/eval` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vasuag09/eval`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vasuag09/eval/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: vasuag09 (https://skillmd.com/u/vasuag09)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/vasuag09/eval

---


# /eval — acceptance-criteria checkpoint

Goal: prove the work satisfies *the spec it was built against*, criterion by criterion.
Green tests show the code runs; this shows it meets what was promised.

> **Opt-in.** This skill is not invoked by any default-pipeline skill or hook. Running it
> is always explicit; it changes no baseline behavior. (Fulfills v0.4 AC-6 / v0.3 AC-E5.)

## Do this
1. **Locate the spec.** Default to the latest `docs/specs/*.md`; let the user name one if
   the change targets an older spec. Confirm it's the spec this change was built against.
2. **Run the deterministic gate:**
   ```
   node scripts/eval/checkpoint.js [spec.md]
   ```
   It prints a per-criterion table (PASS / FAIL / MANUAL) and exits **0** (all PASS, none
   manual) · **1** (a check FAILED) · **2** (no failures, but MANUAL criteria remain).
   - Each criterion may carry an inline ` ```eval ` fenced shell command — that's its
     machine-check. Add one to an AC when a deterministic check exists (port it from the
     spec's own test commands).
3. **On FAIL (exit 1):** the criterion is objectively unmet. Fix the implementation (not
   the criterion) and re-run. Do not proceed while any check FAILs.
4. **Adjudicate MANUAL (exit 2):** for each prose criterion the script can't decide, gather
   concrete evidence (run the app, read the diff, check `.claude/traces/` for what fired)
   and judge PASS or FAIL yourself. The script never auto-passes prose — closing these is
   your job. If a MANUAL criterion is genuinely verifiable, prefer adding an ` ```eval `
   fence so it's deterministic next time.
5. **Gate.** Ship only when every criterion is PASS — checks green *and* every MANUAL
   adjudicated PASS with evidence. Report the verdict criterion by criterion.

## Security & trust
- **` ```eval ` fences are shell-executed** (via `_lib.sh` → `execSync`) with your privileges.
  They are author-authored, committed markdown — trust them exactly like the repo's own test
  scripts or build hooks. **Review specs from untrusted branches/PRs before running `/eval`.**
- `checkpoint.js --list` is the safe inspect-before-run path: it parses and shows which ACs
  carry a check, but executes nothing.
- **Secret-safe:** a check's output is never printed. On FAIL the report shows only the exit
  code + the command (committed text), so you re-run it yourself to inspect output.
- Each check is bounded by a 60s timeout.

## Notes
- Self-contained: the runner is pure Node and needs no companions (mgrep/graph/context7).
- Complements `harness-claude:test` (suite + coverage) and `harness-claude:verify`
  (observe real behavior); this one ties the change back to its acceptance criteria.

## Exit criterion
Every acceptance criterion in the spec is PASS (machine-checked or evidence-adjudicated).
Then `harness-claude:ship`.