AcceptedFebruary 2026

Verification Contract

Evidence-based step acceptance that enforces concrete proof before completion, replacing optimistic prose validation with a deterministic acceptance state machine.

Context

Lex workflows relied on agent result blocks, but step completion could still be accepted from optimistic prose instead of concrete evidence. Steps could be marked done without proving required tool calls happened, mutating changes could pass without proof of validation artifacts, and acceptance behavior varied across workflows.

Core Decisions

1. Verification Block Is the Source of Truth

Each step may declare a verification block with:

  • evidence - payload fields and expected values
  • toolCalls - required tool usage with optional conditions
  • onMissingEvidence - reject-and-retry, reject-and-abort, or warn
  • retryPrompt - explicit corrective instructions for the next attempt

2. Acceptance State Machine Is Mandatory

For any successful agent response, Lex follows this flow:

Acceptance Flow

1

Parse Result Payload

Extract the subagent's result block from the response.

2

Evaluate Verification Rules

Check all evidence fields and tool call requirements for the current step.

3

Accept or Reject

Accept only when all checks pass. If checks fail, apply onMissingEvidence policy.

4

Retry or Abort

If retry budget remains, retry with retryPrompt. Otherwise, execute the onFailure action.

Core Decisions (continued)

3. Verification Happens Before Step Completion

Lex cannot report a step as complete until verification passes. Agent self-reported success is advisory only; contract checks are authoritative.

This is a hard guarantee: no step progresses without evidence, regardless of what the agent claims in its response.

4. Mutating Path Defaults Are Stricter

Policy config requires stronger verification for mutating workflows. Exemptions must be explicit and test-visible.

5. Verification Is CI-Enforced

Tests validate schema compatibility, policy compliance, and behavior for missing evidence and retry handling.

Example Verification Block

verification:
  onMissingEvidence: reject-and-retry
  retryPrompt: "Return missing screenshots and validation details."
  evidence:
    - path: visualVerification.performed
      expect: true
      rejectMessage: "Visual verification was not executed."
    - path: storybookInstance.url
      expect: present
      rejectMessage: "Storybook URL is missing."
  toolCalls:
    - name: open_simple_browser

Key References

.github/agents/@lex.agent.md.github/agents/resources/workflow.schema.json.github/agents/resources/workflow.policies.json.github/tests/workflows.test.ts.github/tests/workflow-policies.test.ts

Trade-offs

Step acceptance is evidence-based and deterministic. Missing proof is caught immediately rather than after merge. Retry behavior is consistent across workflows.
Overly strict requirements can increase retry churn. Weak rejectMessage guidance can make retries less effective. Excessive exemptions can erode guarantees.

Related Documentation