# How Oh-My-ClaudeCode's Verification Protocol Enforces Evidence-Driven Completion

> Discover how Oh-My-ClaudeCode's verification protocol enforces evidence-driven completion with type-matched requirements for every check before approval.

- Repository: [Bellman/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- Tags: deep-dive
- Published: 2026-03-27

---

**Oh-My-ClaudeCode's verification protocol enforces completion by requiring fresh, type-matched evidence for every mandatory check before issuing an `approved` verdict, with agents entering persistence loops until all requirements are satisfied.**

The oh-my-claudecode (OMC) framework isolates its quality assurance logic inside a dedicated verification feature (`src/features/verification`) that treats completion as a contractual obligation backed by concrete evidence. This verification protocol operates as a declarative system where workflows define mandatory checks, execute them under configurable constraints, and refuse to finalize until the evidence payload proves all requirements are met.

## Declarative Check Catalog and Protocol Construction

The foundation of the enforcement mechanism rests on the **standard check catalogue** exported as `STANDARD_CHECKS` from [`src/features/verification/index.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/features/verification/index.ts) (lines 27-86). This registry pre-defines mandatory validation categories including build verification, test suites, linting, functional verification, architect approval, TODO completion, and error-free status. Each check declares an `evidenceType` and a boolean `required` flag that determines whether the workflow can complete without it.

To bundle checks into an executable contract, the system uses `createProtocol(name, description, checks, strictMode?)` (lines 92-99). This function assembles an array of `VerificationCheck` objects into a `VerificationProtocol` object. When `strictMode` is enabled, the engine treats any failed required check as fatal, immediately preventing completion regardless of other results.

```typescript
import { createProtocol, STANDARD_CHECKS } from './verification';

const deploymentChecks = [
  STANDARD_CHECKS.BUILD,
  STANDARD_CHECKS.TEST,
  {
    id: 'security-scan',
    name: 'Security Audit',
    evidenceType: 'security_verified',
    required: true,
    command: 'npm audit --audit-level=moderate'
  }
];

const deployProtocol = createProtocol(
  'production-deploy',
  'Pre-deployment verification',
  deploymentChecks,
  true  // strictMode enabled
);

```

## Checklist Instantiation and Evidence Capture

When a workflow initiates verification, `createChecklist(protocol)` (lines 9-16) clones the protocol’s checks into a mutable `VerificationChecklist` that tracks runtime state including `startedAt`, `status`, and `evidence`. This separation between the immutable protocol definition and the mutable checklist instance allows the same protocol to be reused across multiple workflow executions while maintaining independent state tracking.

The `runSingleCheck` function (lines 21-62) executes the optional shell command defined in each check and returns a `VerificationEvidence` object containing the `type`, `passed` boolean, `command` string, `output`, `error`, and timestamp. For checks without an automated command, the system marks them with `requiresManualVerification`, forcing human intervention before the checklist can proceed.

## Execution Engine and Freshness Validation

The `runVerification` orchestrator (lines 66-84) executes checks according to the protocol's configuration, supporting both parallel execution (default) and sequential modes. It respects runtime flags including `failFast` (abort on first failure), `skipOptional` (ignore non-required checks), and per-check timeouts, ensuring the checklist is fully populated before proceeding to validation.

After execution, `checkEvidence` (lines 41-89) validates that each evidence object matches its declared `evidenceType`, reports `passed: true`, and remains **fresh** (younger than 5 minutes). Stale or mismatched evidence generates an actionable issue and triggers a recommendation to re-run the specific check, preventing workflows from completing with outdated validation artifacts.

## Verdict Determination and Completion Enforcement

The `generateSummary` function (lines 95-124) aggregates pass/fail/skip counts and determines the final **verdict** through three distinct states:

- **`approved`** — All required checks passed, no checks were skipped, and (if `strictMode` is active) no failures occurred.
- **`rejected`** — Any required check failed, or any failure occurred when `strictMode` is enabled.
- **`incomplete`** — Required checks remain in skipped or unchecked status.

High-level agents such as **Ralph** and **Autopilot** invoke the protocol through [`skills/ralph/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/ralph/SKILL.md) (steps 7-9) and [`skills/autopilot/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/autopilot/SKILL.md), integrating the verification loop into their persistence architecture. These agents refuse to exit their execution loops until the checklist's `verdict` property equals `approved`. If verification fails, the agent restarts the task, fixes issues, and re-runs the protocol until concrete evidence satisfies all requirements.

```typescript
import { createChecklist, runVerification, generateSummary } from './verification';

async function enforceCompletion() {
  const checklist = createChecklist(deployProtocol);
  await runVerification(checklist, { 
    parallel: true, 
    timeout: 60000,
    failFast: false 
  });
  
  const summary = generateSummary(checklist);
  
  if (summary.verdict !== 'approved') {
    throw new Error(`Verification ${summary.verdict}: ${summary.issues.join(', ')}`);
  }
  
  // Workflow only proceeds past this point with approved status
}

```

## Summary

- **Declarative contracts**: The `createProtocol` function bundles `VerificationCheck` objects with strict typing and `strictMode` enforcement.
- **Fresh evidence requirement**: The `checkEvidence` validator rejects any evidence older than 5 minutes or mismatched against the declared `evidenceType`.
- **Three-state verdicts**: The `generateSummary` logic produces `approved`, `rejected`, or `incomplete` statuses based on required check completion and `strictMode` settings.
- **Agent-level enforcement**: Ralph and Autopilot agents implement persistence loops that refuse workflow completion until `verdict === 'approved'`.
- **Reusable architecture**: The `src/features/verification` module operates across all OMC modes, making evidence-driven completion a core architectural contract.

## Frequently Asked Questions

### What distinguishes required checks from optional checks in the protocol?

**Required checks** set `required: true` in their definition and must pass with fresh evidence for the `generateSummary` function to return an `approved` verdict. Optional checks may fail or remain unexecuted without blocking completion, though they still generate warnings in the final report. When `strictMode` is enabled on the protocol, even optional failures trigger a `rejected` verdict.

### How does the protocol handle verification steps requiring human judgment?

Checks without a defined `command` property are flagged with `requiresManualVerification` during `runSingleCheck` execution. These items pause the automated workflow and wait for manual confirmation through the `VerificationChecklist` interface. The checklist cannot achieve `approved` status until human operators provide explicit evidence confirmation for these manual gates.

### What causes the protocol to return a rejected verdict versus an incomplete status?

The protocol returns **`rejected`** when required checks fail or when any failure occurs under `strictMode`. It returns **`incomplete`** when required checks remain in `skipped` or unstarted states—typically indicating that `runVerification` was called with `skipOptional: true` while required checks were bypassed, or that the execution timed out before completion.

### Can verification checks execute simultaneously, and what controls this behavior?

Yes. The `runVerification` function accepts a `parallel` boolean parameter that defaults to `true`, executing all checks concurrently for faster validation. When `parallel: false` is specified, checks run sequentially. Additional controls include `failFast` (abort on first failure) and per-check timeouts, allowing fine-grained tuning of the execution strategy based on check dependencies or resource constraints.