version: "1.0.1" name: common-verification-first description: >- Normative verification-first policy for all change intents. Defines independent verification contracts, strategy selection, evidence rules, role ownership, and final evaluation without prescribing microscopic implementation steps. user-invocable: false

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

• Investigate the symptom, trigger, root cause, affected scope, and existing

coverage.

• Reuse or update existing verification when it reproduces the real defect.
• Otherwise add one focused regression at the lowest level that crosses the

failing boundary.

• Demonstrate the defect on the pre-fix state whenever practical.
• Confirm that any failing signal matches the reported behavioral defect rather

than a compilation, setup, dependency, or environment failure.

• Stop when the defect cannot be reproduced; do not guess at a fix.
• Keep regression protection and run the broader relevant suite.

PURE_REFACTOR

• Establish a green baseline with existing behavioral verification.
• Keep behavioral verification unchanged.
• Preserve outputs, side effects, contracts, compatibility, and architecture

invariants.

• If behavioral expectations must change, stop and reclassify the task.

NON_BEHAVIORAL_CHANGE

• Use artifact-appropriate lint, parser, schema, reference, dry-run, or build

checks.

• Establish a baseline only when comparison is meaningful.
• Do not create a test, force a failure, or run an unrelated suite for ceremony.
• Report when no automated validator exists.

Infrastructure and Configuration

Classify by intent first, then choose the natural oracle. Appropriate evidence can include workflow or configuration schema validation, policy validation, migration checks, API or event contract validation, compiler checks, type checking, lint, and generated-code consistency.

Do not force infrastructure behavior into a shallow unit test when policy, contract, plan, or migration evidence expresses the real system property more directly.

Test Infrastructure

Fixtures, builders, mocks, stubs, seeders, containers, data loaders, and test-runner configuration are solution artifacts.

Use this order:

1. Run a production-behavior consumer test that uses the support artifact.
2. Reproduce the affected test workflow directly when needed.
3. Add the smallest focused test of a stable support contract only when the

first two paths cannot localize the defect with enough diagnostic precision.

The focused support test is diagnostic instrumentation, not a coverage target. Record why consumer or workflow evidence was insufficient.

Oracle Effectiveness

Physical test-first ordering is only a proxy for independence. The stronger question is:

Can the verification meaningfully reject an incorrect or previous behavior?

Useful effectiveness evidence may include:

• a focused failing regression;
• a known counterexample;
• a contract, schema, policy, or generated-artifact mismatch;
• a mutation that the oracle rejects; or
• another meaningful negative signal.

A failing signal counts only when its observed reason matches the expected absent, previous, or defective behavior. Compilation, setup, dependency, and environment failures are limitations to resolve or report, not evidence that the behavioral oracle is effective.

Do not require visible Red merely as ritual. For critical behavior, consider stronger techniques such as property-based testing, mutation testing, boundary analysis, concurrency scenarios, contract validation, and independent review.

Behavioral Test Strategy

Inside-out and outside-in are both valid ways to discover behavioral verification. Neither dictates how the Implementer must construct the solution.

Use the lowest test level that can prove the requirement without mocking away the risk:

Behavioral verification should be isolated, order-independent, deterministic, readable as a requirement, specific enough to localize failure, insensitive to private structure, and maintainable in proportion to the protected risk.

Coverage and test count are diagnostics, not goals. Prefer observable results and required side effects over private methods, trivial storage, framework registration in isolation, or mock interactions as ends in themselves.

Compact Result Shapes

These are the canonical workflow envelopes. Role agents may add task-specific detail but must not rename, remove, or contradict these fields.

VerificationContract
 
Intent and strategy:
Behaviors and invariants:
Verification artifacts:
Targeted commands:
Pre-state effectiveness evidence:
Broader gates:
Assumptions:
Result:
Risks or limitations:

ImplementationResult
 
Intent and strategy:
VerificationContract received:
Solution artifacts changed:
Candidate paths:
Design decisions:
Targeted command and result:
Broader gates and results:
Contract status: SATISFIED | UNSATISFIED | BLOCKED
Unresolved concerns or risks:

ReviewResult
 
Mode and scope:
Summary:
Prioritized findings:
No-finding rationale:
Verification observations and commands:
Contract assessment: <assessment | NOT_PROVIDED>
Verdict: APPROVE | COMMENT | REQUEST_CHANGES | BLOCKED
Remaining risks:

FinalVerificationResult
 
Candidate paths assessed:
Approved semantics assessed:
Review disposition assessment:
Behaviors and invariants assessed:
Targeted command results:
Broader gate results:
Contract assessment:
Final result: PASS | FAIL | BLOCKED
Risks or limitations:

ChangeResult
 
Approved specification:
Intent and strategy:
VerificationContract:
Changed paths and candidate scope:
Latest ImplementationResult:
Latest ReviewResult or ReviewOmission:
FinalVerificationResult:
Final judgment:
Limitations and residual risks:

What Remains Strict

• Approved requirements, invariants, scope, and constraints precede

implementation.

• Expected behavior is established independently of the candidate

implementation.

• Verification-contract artifacts remain Contract Verifier-owned.
• Bug fixes reproduce the defect whenever practical.
• Pure refactors preserve behavior and behavioral verification.
• Test infrastructure uses consumer or direct-workflow evidence first.
• Required targeted and broader gates run before completion.
• Missing, failed, skipped, or unavailable evidence is reported honestly.
• Candidate review is mandatory except for the strict non-behavioral omission.
• A fresh final evaluator reassesses evidence against original intent.

What Remains Flexible

• Whether the oracle is a test.
• Whether verification is new, updated, or reused.
• Whether an effectiveness signal is a failing test or another negative signal.
• The test level and inside-out or outside-in perspective.
• How many files or local implementation iterations are needed.
• When the Implementer compiles, tests, debugs, or refactors.
• Whether review finds anything; no findings is valid.

Never require a new test, a failing test, or a separate cleanup phase merely to satisfy a ritual. Require independent criteria, appropriate evidence, sound architecture, and a credible final judgment.