ADR-028: Three-Tier Verification Pyramid Architecture

Date: September 2, 2025 Status: Accepted Authors: Lead Developer (Claude Sonnet 4), Code Agent Reviewers: Chief Architect, PM

Context

AI agent coordination in the Piper Morgan project suffered from “verification theater” - agents claiming task completion without providing concrete evidence of functionality. This led to:

The core problem: agents could say “I implemented X” and we would accept that claim without requiring verifiable proof.

Decision

We implement a Three-Tier Verification Pyramid as the foundational framework for all agent coordination, requiring systematic evidence at each level before proceeding.

Architecture Overview

Level 3: Evidence Collection (Concrete Proof Required)
    ↑
Level 2: Integration Verification (Coordination Validated)
    ↑
Level 1: Pattern Discovery (Archaeological Search)

Tier 1: Pattern Discovery

Problem: 60-80% of requested features already exist in some form Solution: Mandatory archaeological search before any implementation Implementation:

Tier 2: Integration Verification

Problem: Features work in isolation but break system coordination Solution: Validate coordination requirements and dependencies Implementation:

Tier 3: Evidence Collection

Problem: Claims without verifiable proof lead to verification theater Solution: Concrete evidence required for all completion claims Implementation:

Implementation Details

Core Framework (methodology/verification/pyramid.py)

class VerificationPyramid:
    async def verify(self, task: Dict[str, Any]) -> VerificationResult:
        # Level 1: Pattern verification (find existing)
        # Level 2: Integration verification (validate coordination)
        # Level 3: Evidence verification (prove completion)

Evidence Requirements by Task Type

Pattern Discovery Protocol

DISCOVERY_COMMANDS = {
    'python': ['grep -r "{pattern}" --include="*.py"'],
    'architecture': ['find docs/ -name "*.md" -exec grep -l "{pattern}" {} \\;'],
    'methodology': ['grep -r "{pattern}" methodology/']
}

Consequences

Positive

Negative

Risks and Mitigations

Risk: Agents circumvent verification requirements Mitigation: Framework integrated into core agent coordination protocols

Risk: Verification overhead slows legitimate work Mitigation: Caching and pattern recognition optimize repeat searches

Risk: Evidence requirements become bureaucratic Mitigation: Evidence types tailored to task types, automated where possible

Implementation Strategy

Phase 1: Foundation (Completed)

Phase 2: Evidence Refinement (Next)

Phase 3: Integration

Validation Criteria

Framework Operational: When agents cannot claim success without evidence Pattern Discovery: Finds existing implementations before allowing rebuilds Integration Assurance: Validates coordination requirements before deployment Evidence Standards: Concrete proof required, no theoretical solutions accepted

Alternative Approaches Considered

Option A: Trust-Based Coordination

Rejected: Led to the verification theater problem we’re solving

Option B: Manual Review Process

Rejected: Doesn’t scale with AI agent speed and volume

Option C: Automated Testing Only

Rejected: Misses coordination failures and duplicate work prevention

Option D: Three-Tier Verification Pyramid (Selected)

Rationale: Addresses all three core problems (theater, duplication, integration) with systematic approach

Success Metrics

Review and Evolution

This ADR will be reviewed after Phase 2 implementation and full integration deployment. Framework will evolve based on:

Next Steps: Deploy Phase 2 evidence collection refinement, then integrate framework into active agent coordination workflows.