---
name: verification-gate
description: You MUST use this when work is about to be called complete, done, fixed, ready, or mergeable - before a completion claim, a merge or pull request, a branch finish, or a handoff report.
metadata:
  author: Ihor Orlovskyi
  version: "1.0.0"
license: MIT
---

# Verification Gate

## When to use and responsibility

Apply this gate before calling material work complete, fixed, ready, or mergeable,
including review completion, PR creation, branch finishing, and handoff reports.

```text
NO COMPLETION CLAIM WITHOUT FRESH EVIDENCE
```

Input: the proposed completion claims, requirements, expected scope, and current tree.
Output: an attributable evidence matrix and a verdict for that exact claim set and tree.
Reading this skill or finishing its checklist supplies no evidence of the work's success.

Non-goals: implementation, debugging methodology, test-framework guidance, code review,
branch management, deployment, and subagent orchestration. Route these to their owners.
Keep evidence in the current session or the active workflow's existing record. Do not
create `.sdd/` or any persistent verification state, directory, ledger, or cache.

## 1. Enumerate claims before choosing commands

Ask what is about to be claimed. Split broad statements into observable promises, each
with its acceptance boundary: tests pass, the original bug no longer occurs, the build
succeeds, the feature works in a browser, or a migration preserves data.

```text
claim -> required evidence -> verification method
```

In the report, write a separate numbered `Claims` block before the matrix or any
check selection. Each item must be one observable promise, including completion and
merge-readiness when both are being claimed. Matrix row labels do not replace this
claim list.

For each claim, name the result that would prove it and what would falsify it. A claim
of complete implementation includes all required acceptance criteria and constraints.
Do not narrow that claim silently to the subset covered by existing tests.

## 2. Choose proportional depth

A trivial non-code edit means spelling, punctuation, or formatting in human-facing prose
with no change to meaning, behavior, commands, links, policy, agent instructions, public
contracts, generated inputs, or configuration. Confirm its exact diff and tree identity,
check the edited text, and report that limited evidence directly; skip the full matrix
and broader workflow. A small agent-instruction or executable-config edit is material.

For material work, choose depth from impact and reach:

| Risk | Required depth |
| --- | --- |
| LOW | Targeted checks of the changed behavior or artifact |
| MEDIUM | LOW plus relevant typecheck, lint, build, and affected-area regression |
| HIGH | MEDIUM plus broader regression, integration or end-to-end where appropriate, security and data boundary checks, and rollback validation where relevant |

State why the tier fits. Read [verification-depth.md](references/verification-depth.md)
when risk spans components, equivalence is uncertain, or verification can mutate state.
Destructive or production-impacting checks require authorization. Before any mutating
check, record side effects, reversibility, rollback, and the authorization that covers it.

## 3. Resolve current-tree integrity

Before collecting evidence, identify the repository, branch, worktree, `HEAD`, and intended
boundary. Inspect staged, unstaged, and untracked state independently:

```bash
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --short --branch --untracked-files=all
git diff --cached --name-status
git diff --name-status
git ls-files --others --exclude-standard
```

A detached HEAD is an identity to record. For branch-wide claims, resolve the intended
base and include committed changes since that base. A working-tree claim also includes
the index, working files, and relevant untracked inputs; a commit SHA alone is insufficient.
Record the included paths and content fingerprint of those changes. Include relevant
ignored inputs and submodule state when they affect the result. Preserve unrelated work.

Recheck identity after verification and immediately before the verdict. Material drift
invalidates affected evidence. If the target cannot be resolved, record the gap and return
an incomplete or blocked verdict. Read
[evidence-provenance.md](references/evidence-provenance.md) for fingerprint and scope details.

## 4. Require fresh evidence

Each selected check needs a completed run against the resolved current tree and an
interpretation of its full output, exit status, failures, skips, and coverage limits.
Record the exact command or observation procedure, result summary, capture time, and tree
identity. A running, truncated, skipped, or empty check cannot prove its intended claim.

These six sources are not authoritative on their own:

- pre-fix test output;
- prior-session output;
- a reviewer statement;
- an implementer report;
- green CI for another commit;
- a pre-change screenshot.

Freshness requires evidence from this verification pass after the last relevant change,
with matching inputs and conditions. CI evidence must identify the exact verified revision,
job, and environment; it cannot cover local changes absent from that job. A material change
to an artifact, dependency, configuration, environment, or acceptance boundary makes
affected evidence stale. Rerun those checks and retain only evidence whose applicability
and identity remain established.

A current-session or active-workflow check record may support `✓ passed` for its narrow
claim when it identifies the check, result, exact current tree, and relevant conditions.
Do not infer neighboring claims from that record. A vague success statement without those
identifiers remains `? not verified`.

## 5. Check verification equivalence

Before running an important check or relying on its method, ask:

```text
Does this verification observe the same relevant object,
under the same relevant conditions, at the same boundary
as the behavior being claimed?
```

Inspect the tested object, actors and privileges, inputs, state, environment, and observed
outcome. Common mismatches involve auth, permissions, filesystem, network, browser,
database, migrations, privileged operations, external services, and environment-specific
behavior. An unrelated green result leaves the intended claim unverified.

Read project manifests, scripts, configuration, and CI definitions to discover actual
tooling before choosing commands. Use applicable specialists for mechanics; the gate
owns whether their evidence proves the claim. Browser interaction, console, network,
DOM, rendering, and runtime claims require real runtime evidence through `web-debug`.
Record subjective visual acceptance as `? not verified` until explicit visual or human
assessment exists. Unit mocks and screenshots alone cannot establish every visual promise.
Read [runtime-verification.md](references/runtime-verification.md) for these cases and
[verification-depth.md](references/verification-depth.md) for worked equivalence contrasts.

## 6. Build the verification matrix

Use one row per applicable claim or check. Include requirements, scope, tree integrity,
impact, and any required review closure alongside applicable tests and quality checks.

| Claim or check | Required evidence and method | Status | Result, identity, or gap |
| --- | --- | --- | --- |
| `<observable promise>` | `<method that reaches its boundary>` | `<one status below>` | `<attributable evidence or missing proof>` |

Use these exact statuses:

| Status | Meaning |
| --- | --- |
| `✓ passed` | Fresh equivalent evidence establishes this row's claim. |
| `✗ failed` | Valid verification produced negative evidence for this row. |
| `— not applicable` | This check does not apply to the agreed claim set; state why. |
| `? not verified` | An applicable claim lacks sufficient evidence; name the gap. |

Unavailable tooling, skipped execution, and missing access are unverified gaps. They do
not justify `not applicable`. Give each gap its impact, next action, and responsible owner.
Keep partial successes visible without inferring other rows from them; the implication
table in [evidence-provenance.md](references/evidence-provenance.md) lists common mistakes.

## 7. Verify requirements and acceptance separately

Re-read plan intent, acceptance criteria, required behaviors, user-requested constraints,
and explicit non-functional requirements. Map each to evidence, including error paths and
limits that the requirement names. Test results support specific criteria; they do not
replace this comparison. Record an uncovered criterion explicitly, including whether it
needs a manual observation. An optional suggestion must stay separate from required work.

When review output exists, inspect its current target and resolution record for open
blocking findings. A confirmed unresolved blocker prevents PASS. An unclear or stale
disposition remains unverified and routes to its review owner. If the active workflow
requires review and its closure evidence is missing, record that gap. Do not conduct a
new code review or decide finding validity here.

## 8. Verify scope against the expected change

Compare the intended file and behavior boundary with deterministic Git inspection:

```bash
git status --short --branch --untracked-files=all
git diff --stat
git diff --name-only
git diff --cached --stat
git diff --cached --name-only
```

Include the resolved base-to-HEAD diff for branch claims and inspect selected untracked
files explicitly, since `git diff` omits them. Examine actual content for debug logs,
temporary files, generated artifacts, secrets, unrelated edits, and accidental dependency
changes. Avoid printing secret values. Detect, explain, and evaluate unexpected paths;
an unexpected file is a signal requiring explanation rather than an automatic failure.
An unexplained material change remains a gap; a confirmed scope violation is a failure.

## 9. Verify change impact

Ask what existing behavior these changes could affect. Trace consumers of shared helpers,
types, public APIs, base components, parsers, config, schemas, build configuration, and
common dependencies. Add relevant affected-area regression and compatibility checks.
Explain the inspected reach and remaining uncertainty. Broaden verification for actual
impact without requiring the entire repository suite for every change.

## 10. Obtain independent evidence for delegated work

For delegated implementation, the controller inspects the integrated diff and current
tree and obtains final authoritative evidence directly. Implementer reports help locate
checks; their success statements cannot establish the final verdict. Inspect attributable
command output or runtime evidence independently and rerun the selected final checks on
the integrated target. Repeating every local micro-test is unnecessary when the final
selection covers its claims and affected interactions. The active executor owns dispatch.

## 11. Run checks in useful order

Run the selected checks after defining their claims, equivalence, and required coverage.
Wait for each to finish and read its full output before assigning a matrix status.
Order checks from cheap, high-signal evidence to expensive checks, respecting dependencies.
A possible order is scope sanity, targeted checks, typecheck, lint, integration, build,
end-to-end, and manual or visual assessment. Move compilation earlier if other checks
depend on it. Stop dependent expensive checks when a prerequisite fails; mark them
unverified. Preserve independent results. After a fix, refresh affected evidence and
recheck the target before continuing.

## 12. Return the verdict

| Verdict | Meaning |
| --- | --- |
| `PASS` | Every applicable claim and required check has sufficient fresh successful evidence for the current tree; all exclusions are justified and no blocking finding remains. |
| `FAIL` | Valid verification establishes a defect, unmet requirement, scope violation, or confirmed unresolved blocking finding. |
| `INCOMPLETE VERIFICATION` | Evidence is missing, stale, non-equivalent, or partial; verification can continue within the active workflow. |
| `BLOCKED` | The gate itself cannot make meaningful progress because an external dependency, access, authorization, or necessary input is unavailable. |

Material unknowns forbid `PASS`. Any applicable unverified row prevents full PASS for the
claim set. When failures and gaps coexist, report FAIL and retain every gap and blocker.
When an external obstacle leaves one or more rows open while other verification can continue,
use INCOMPLETE VERIFICATION and name the blocker, next action, and owner. Use BLOCKED when
the gate itself cannot make meaningful progress. Neither incomplete nor blocked means the
implementation is known defective.

Return the verdict, claim set, tree identity, matrix, concise command/result evidence,
and limitations with their next owner. Use the summary shape in
[evidence-provenance.md](references/evidence-provenance.md) when reporting several checks.
A narrow verified claim can be reported alongside gaps with its exact scope stated.
Completion or merge readiness requires PASS for the full required claim set. PASS is an
integration precondition; it grants no permission to commit, push, merge, deploy, or publish.
Material changes after PASS, including conflict resolution, require fresh affected checks.

## 13. Route failures and bound the verify/fix loop

Classify the result and return evidence to the owner:

| Situation | Route |
| --- | --- |
| Understood local implementation defect | Active executor for a scoped fix |
| Unknown, confusing, or unstable failure | `debugging` for root cause |
| Resurfaced review finding or unclear blocking disposition | `review-resolution` |
| Browser-only failure | `debugging` with `web-debug` runtime evidence |
| Missing service, access, authorization, or required input | Active workflow controller with the exact blocker |

The gate evaluates again after the owner supplies a fix; it does not implement the fix.
Use the active workflow's retry bound. If none exists, allow at most two corrective
rounds after the initial verification. Escalate sooner if the same failure recurs without
new causal evidence. At the bound, report the current verdict, attempts, remaining gaps,
and the decision or evidence needed. Repeated runs until one turns green do not establish
reliability. Root-cause work and further execution belong to the active workflow.

## Composition boundaries

| Skill | Boundary |
| --- | --- |
| `scope-triage` | Routes the request; a completion claim on material work still passes this gate. |
| `plan-crafting` | Supplies acceptance criteria; this skill checks them against evidence. |
| `inline-plan-dev` | Performs local verification during implementation; delegates the final authoritative gate here. |
| `subagent-plan-dev` | Owns task orchestration; its implementer reports are input, not evidence. |
| `tdd` | Proves behavior during implementation; GREEN is local evidence and not final proof. |
| `debugging` | Owns root cause when a failure is not understood. |
| `review-request` | Obtains findings; a review verdict does not replace verification evidence. |
| `review-resolution` | Resolves findings; this skill checks that no blocking finding remains open. |
| `web-debug` | Supplies real browser and runtime evidence when the claim concerns browser behavior. |
| `frontend-crafting` | Supplies visual and design judgment; subjective claims are not automated away. |
| `vitest` | Supplies test-runner mechanics for the project's actual tooling. |
| `typescript` | Supplies typecheck mechanics and diagnostics. |
| `workspace-isolation` | Reports which workspace is under verification; this skill verifies that tree. |
| `branch-finish` | Consumes the verdict as a merge precondition; it does not invent its own verification. |

## Anti-patterns

- Calling work done before gathering and interpreting evidence.
- Trusting old output, an implementer success report, or a review PASS as final proof.
- Running irrelevant checks and calling their green result evidence for another boundary.
- Treating passing tests as satisfied requirements or a build as a working feature.
- Ignoring untracked or uncommitted changes, or leaving unexpected scope unexplained.
- Repeating unstable checks until green without understanding the failure.
- Calling a skipped check `not applicable` without justification.
- Using browser unit mocks as proof of real browser behavior or inventing visual approval.
- Claiming full PASS with material unknowns or after a relevant tree change.

For design lineage and license provenance, see
[attribution.md](references/attribution.md); it is maintainer context for this package.