macalbert/envilder/common-verification-first

Verification-First Engineering

This is the normative policy for planning, implementing, reviewing, and verifying repository changes across every Envilder stack.

Core Principle

The implementation must not define its own success criteria.

Expected results derive from approved requirements, invariants, acceptance criteria, architecture constraints, and stable external contracts. Control the correctness of the result without prescribing the microscopic process used to produce it.

A passing command is evidence. It is not proof that the requirement was interpreted correctly.

Distinct Concepts

• TDD controls how implementation evolves through Red, minimal Green, and

Refactor. An Implementer may use that loop when useful, but this workflow does not require it.

• Test-first establishes a test before implementation. The ordering can

separate expected behavior from solution generation, but physical ordering alone does not guarantee independence.

• Automated testing executes test-based evidence against a system.
• Verification-first establishes the strongest practical,

implementation-independent oracle before solution edits when meaningful. The oracle may be a test, compiler, type checker, schema validator, policy check, contract check, generated-artifact check, or direct workflow.

The goal is reliable evidence of correctness, not the maximum number of tests.

Two Independent Dimensions

Classify every task by both intent and verification strategy. Neither dimension mechanically determines the other.

Intent

Choose exactly one:

Infrastructure, configuration, migrations, generated artifacts, and test infrastructure are subjects of work, not extra intents. Classify what the change means, not which directory it touches.

Verification Strategy

Select one or more strategies justified by the requirement:

Prefer the fastest deterministic strategy that directly exercises the important boundary. Add broader gates when a narrow oracle cannot expose integration risk.

Role Ownership

Change Orchestrator

• Owns one coherent approved change, its classification, routing, and final

judgment.

• Preserves the approved requirement, invariants, scope, constraints, and

limitations.

• Never edits artifacts or executes repository commands.
• Routes implementation defects to the Implementer, contract defects to the

Contract Verifier, and semantic changes to human approval.

Contract Verifier

• Is the sole editor of verification-contract artifacts.
• Selects, reuses, updates, or creates the required executable oracle before

implementation.

• Never derives expected behavior from the candidate implementation.

Final Verifier

• Has read-only tools and cannot edit verification or solution artifacts.
• Reassesses the exact reviewed candidate against the original approved intent

and independent contract in a fresh context.

• Returns BLOCKED when required final evidence needs command execution that

the read-only profile cannot perform.

• Never derives expected behavior from the candidate implementation.

Implementer

• Is the sole editor of solution artifacts: production code, configuration,

documentation, migrations, refactors, and test infrastructure.

• Never edits or weakens the established verification contract.
• May inspect, compile, test, debug, iterate, and refactor freely.
• Does not need to follow microscopic Red/Green/Refactor cycles.

Reviewer

• Is strictly read-only and evaluates final artifacts rather than implementation

history.

• Supports candidate-review for one orchestrated candidate and

change-set-review for a staged, unstaged, branch, commit-range, or pull-request diff.

• Never edits or delegates fixes.
• May return no findings when the candidate is already correct and well

factored.

Artifact Ownership

Verification-contract artifacts encode success criteria: behavioral, regression, contract, architecture, or acceptance tests; expectation snapshots; and dedicated validation scripts or specifications created to express the approved contract.

Solution artifacts include production code, configuration, documentation, migrations, refactors, fixtures, builders, seeders, mocks, containers, data loaders, runner setup, and other test infrastructure.

The Contract Verifier may edit only verification-contract artifacts while establishing a contract. The Implementer may edit only solution artifacts. The Reviewer and Final Verifier edit nothing.

Capability Exposure and Inheritance

On filtering hosts, a descendant's effective tools are limited by its own profile and every ancestor's exposed tools. Change Orchestrator, Content Designer, and PR Resolver therefore each declare the explicit inheritance envelope [read, search, edit, execute, agent]. Every ancestor must expose all required descendant tools, including agent for nested delegation.

Exposure does not grant semantic authority: coordinators never edit artifacts, and Change Orchestrator never executes repository commands. Contract Verifier owns verification-contract edits; Implementer owns solution edits. Host approval gates remain in force; never use wildcard tool grants or bypass approvals to repair propagation.

Workers retain their own limits: Contract Verifier and Implementer use [read, search, edit, execute], Reviewer uses [read, search, execute], and Final Verifier uses [read, search]. None delegates. A broader ancestor envelope must not expand a worker's effective boundary.

These common aliases are portability defaults, not universal host tool names or support guarantees. Preflight actual tool exposure, nested delegation, and worker boundaries; return BLOCKED with the missing capability when required support cannot be established. Implementer diagnoses missing read/edit/execute and may use execute-based search when no dedicated search tool is exposed.

Semantic Handoffs

Fresh contexts provide separation of responsibilities and independent evaluation. Fresh does not mean starved of context.

Every worker receives the approved semantic inputs it needs:

• requirement and observable outcome;
• intent and verification strategy;
• invariants and exact in-scope and out-of-scope boundaries;
• architecture, compatibility, security, and operational constraints;
• assumptions and explicit limitations;
• relevant repository context, commands, prior evidence, and required gates;
• the current VerificationContract;
• the exact candidate diff and path set when a candidate exists; and
• the latest relevant ImplementationResult, ReviewResult, or

FinalVerificationResult.

Do not propagate transcripts, raw command logs, failed attempts, temporary hypotheses, private reasoning, or obsolete result histories. Communicate semantic results, not full working trajectories.

Verification-First Workflow

1. Approve the requirement, observable outcome, invariants, scope, and

constraints.

1. Classify intent and choose the verification strategy independently.
2. Delegate a fresh Contract Verifier.
3. Confirm the VerificationContract derives from approved semantics and uses

the narrowest credible oracle.

1. Delegate a fresh Implementer to produce the coherent solution.
2. Run a fresh read-only Reviewer in candidate-review mode unless the strict

omission rule applies.

1. Route findings to their owner and repeat only the affected downstream

stages.

1. Delegate a new fresh Final Verifier.
2. Only an explicit Final result: PASS in FinalVerificationResult for the

exact current reviewed candidate permits Change Orchestrator completion judgment. PASS is necessary, not sufficient: all existing acceptance conditions still apply.

If any candidate artifact changes after review or final verification, invalidate the affected results and rerun the necessary review and final verification against the new candidate.

Final Result Gate and Recovery

• FAIL prevents acceptance. Route implementation defects to a fresh

Implementer and contract defects to a fresh Contract Verifier, then repeat affected downstream stages. Changes to approved semantics, invariants, scope, or requirements require human approval.

• BLOCKED propagates a reason-bearing ChangeResult with final judgment

BLOCKED; callers must not claim successful completion, publish PR replies, or resolve threads. Unavailable required evidence alone is not an instruction to edit the solution.

• An approved limitation cannot replace final PASS or waive FAIL or

BLOCKED. A legitimately approved limitation strategy can still receive PASS when the approved contract is actually satisfied and assessable.

• A genuinely resolved blocker, including independently owned contract repair,

requires reassessment of the corrected contract/candidate, appropriate review, and fresh final verification. Only a fresh explicit PASS reopens judgment.

• Missing, unknown, or ambiguous final results cannot pass the gate. Neither

another role's success nor passing commands establish final PASS.

Callers must require this qualifying final PASS for each artifact-changing action, even if its ChangeResult nominally claims success. All approved actions must succeed before batch publication; prepared but held replies are not published success. Aggregate validation and remote availability are additional gates, not substitutes for final PASS. Direct no-artifact answers and approved skips retain their existing workflow and applicable exemptions.

Review Omission

Candidate review may be omitted only when every condition is true:

• intent is exactly NON_BEHAVIORAL_CHANGE;
• scope is trivial;
• the edit is mechanical;
• the subject is not infrastructure, configuration, migration, a generated

artifact, or test infrastructure; and

• definitive artifact-appropriate validation passed.

Record the rationale, evidence, and residual risk. Any uncertainty requires review. A lifecycle-level or complete change-set review may still be required by the caller.

Rules by Intent

NEW_BEHAVIOR

• Identify the absent observable behavior and its invariants.
• Reuse verification that already expresses the requirement.
• Add verification only for uncovered behavior.
• Establish a meaningful expected-failure or absence signal when the oracle can

do so.

• Use integration evidence when wiring or cross-layer collaboration is part of

the risk.

BEHAVIOR_CHANGE

• Update the existing behavioral contract before implementation when one

exists.

• Remove or replace contradictory expectations.
• Add verification only for an uncovered part of the approved change.
• Record how current behavior differs from the newly approved expectation.

BUG_FIX