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

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 (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.

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 (steps 7-9) and 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}