/verify

name: verify
description: Verify any change surface against approved acceptance criteria, run the real system, and preserve the report and test artifacts.

/verify

Verify that a change does what its plan said. Report what you observe and keep the receipts. Never fix the code being judged.

This workflow has exactly two halves. Half one creates acceptance criteria and stops for approval. Half two runs only after the user approves those criteria by saying `go` or an equally explicit instruction.

Hard rules

• Never fix what you judge. Report only.
• Mutation is allowed. Writing to shared or staging systems needs the user to say yes first.
• Provisioning anything that costs money needs the user to say yes first.
• `Not checked` is always printed, even when empty.
• Expense is not a reason to skip. If a criterion can be driven but costs real setup, say what it would take and let the user decide. Never decide that on their behalf.
• A `Not checked` reason states why it was not driven. It never asserts that something else covers it, unless it names that thing and says plainly this run did not re-run it.
• Drive the system the way a user does. This workflow does not read or run the repository's unit tests.
• An expectation comes from the plan or from the base commit. Never from the diff. The diff can only expose gaps, and a gap is a question for the user, not a criterion you answer yourself.
• Generated tests stay under the run's `tests/` directory until the user explicitly chooses to check them in.
• Make one observation per approved criterion. Do not collapse a harness failure into a behavior failure.

Engine calls

The engine is a local TypeScript package with no installed `verify` binary. Every invocation must be self-contained because shell variables and working directories do not survive between tool calls.

Use this exact resolution rule at every call site, replacing the verb and arguments as needed:

VERIFY_PIPELINE="${VERIFY_PIPELINE:-$CLAUDE_PLUGIN_ROOT/pipeline}"
(cd "$VERIFY_PIPELINE" && npx --no-install tsx src/cli.ts <verb> [arguments])

`CLAUDE_PLUGIN_ROOT` is set by Claude Code for an installed plugin. Set `VERIFY_PIPELINE` yourself only when running from a development checkout. Never hardcode a path to someone's home directory; if neither variable resolves, stop and say so rather than guessing.

The environment helpers are bash scripts resolved the same way:

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
bash "$VERIFY_SCRIPTS/<name>.sh" [arguments]

**Once per machine, install the engine's dependencies.** The plugin ships TypeScript source and no `node_modules`, so the first call fails without this. It is a lockfile-pinned install inside the plugin's own directory, it touches nothing in the target repository, and it is safe to re-run:

VERIFY_PIPELINE="${VERIFY_PIPELINE:-$CLAUDE_PLUGIN_ROOT/pipeline}"
if [ ! -x "$VERIFY_PIPELINE/node_modules/.bin/tsx" ]; then
  (cd "$VERIFY_PIPELINE" && npm ci)
fi

Run that before the first engine call of a session. Do not fall back to plain `npx`, which would fetch an unpinned package from the network.

**Optional recorder garnish.** Driven criteria get an engine-recorded transcript from their receipts; no PTY is involved. `asciinema` and `agg` are attempted only for hand-driven flows, under hard wall-clock limits. A missing, hanging, or broken recorder never blocks verification: record it under `Not checked` and continue. On a fresh box: `brew install asciinema agg`, or the equivalent for the platform.

The skill runs in the target repository, not the plugin repository. Resolve every target-repository path with `pwd -P` and pass absolute paths for `--repo`, `--dir`, `--criteria`, `--results`, and `--claims`.

Half one: criteria, then stop

0. The setup contract

First pull anything a fresh worktree is missing from the per-repo shared store (captured login state; a fallback env file stays in the store and is picked up automatically by the environment scripts):

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
bash "$VERIFY_SCRIPTS/shared-store.sh" pull

`.verify/setup.json` records how this repo boots, seeds, and reports health (written once by `/verify-setup` from sniffed candidates). If it is missing, ask once: "No setup contract found. Run `/verify-setup` (recommended), or continue in plain-command mode without a managed stack?" On plain-command consent, write a minimal contract inline:

{"mode": "none", "compose_file": null, "boot": "", "teardown": "", "seed": [],
 "seed_data_files": [], "health_url": "", "base_url": "", "env_file": "",
 "observe": {}, "probes": {}}

Never silently proceed without one. Verify never asks for or stores sensitive credentials; the contract may at most name one of the repo's own local `.env` files.

1. Find the plan

Look in this order:

1. The current conversation, including an explicit path supplied with `/verify`. 2. `docs/plans/`. 3. `.omx/plans/`. 4. The current pull request body, when available.

Use the newest plan that clearly describes the current change. If no plan is available, ask the user for one and stop. Do not derive criteria from the diff alone.

**The diff raises questions. It never answers them.**

This is the line that keeps verification black box. An expectation comes from the plan, or from the behavior that existed before the change, or from an assumption you label `invented` so the user can correct it. Never from the implementation you are verifying.

That is what the `source` field records, and why `invented` is a legitimate value rather than an admission of failure. A plan that says "field values persist" without naming a field leaves you a choice. Making it and flagging it loudly is honest. Resolving it by opening the code and testing whatever it happens to do is not, because that criterion cannot fail.

So do not go reading the implementation for things to test. If