verify-completion

/verify-completion

Goal

Re-check a completion claim from a context that did not build the work (the hooks-mastery builder-validator pattern), so "the builder says it's done" is never the last word. It answers one question with evidence: does the claim match reality? — and defaults to REFUTED on any doubt.

Two layers, and you run both:

1. Deterministic — core/infra/completion-verify.py mechanically checks that every cited file exists (and contains its declared substring), every cited test exits 0, and every cited assertion holds. This catches the common failure ("claimed file X" when X does not exist; "tests pass" when they fail) and cannot be argued with.
2. Semantic — a refute-by-default judgment that scripts cannot make: does the code actually do what the claim says, are the tests meaningful (not trivially-green), does the artifact match the stated intent? This is the LLM-judge layer of the eval harness.

Both emit the same verdict schema (docs/scoring-convention.md).

This skill's verdict stays advisory — whether/how to enforce it is a consumer decision (docs/scoring-convention.md "Consuming a verdict": "That choice belongs to each consumer"). The first BLOCKING consumer is core/infra/completion-gate.sh (docs/gate-registry.md completion-gate row), invoked from /supervise's wave-audit step with --verify-blocking; it wraps completion-verify.py --require-evidence --diff-base behind a liveness canary and a hard AGENT_VERIFY_BLOCKING=block mode. This skill and that gate are complementary, not redundant: the gate is the deterministic hard stop, this skill's semantic pass is what a needs_semantic claim (one the gate cannot mechanically refute or confirm) gets routed to next.

The claim

A claim is a JSON/YAML file (by convention .agent/claims/<slug>.yml) the builder writes, or that you reconstruct from the builder's report:

claim:
  summary: "what the task asserts it accomplished"
  files:                       # each must exist; optional substring must be present
    - { path: "core/hooks/x.py", contains: "def new_guard" }
  tests:                       # each command must exit 0
    - "bash core/tests/x-test.sh"
  assertions:                  # mechanical claim<->artifact checks (each exits 0)
    - "grep -q start_new_session core/hooks/x.py"