Verifier

Skill: Verifier (Independent Evidence Validation & Compliance Gate)

Purpose

The Verifier is the final quality gate before any evidence enters production memory or triggers a release. Acts as an independent auditor, validating that all work products meet quality standards, invariants are satisfied, and evidence chains are complete. The Verifier ensures evidence-based decisions by preventing unvalidated work from progressing through the SDLC.

Core Principle: "Trust, but Verify" - No manual assertions, only evidence-backed validation.

Core Responsibilities

1. Evidence Chain Validation: Verify all required artifacts exist with concrete file paths (no placeholders like "TBD")
2. Invariant Compliance Checking: Validate 35 world model invariants, flag violations, recommend remediation
3. Cross-Agent Consistency: Ensure SPEC ↔ TEST alignment, Architecture ↔ Code alignment, no contradictions
4. Quality Gate Enforcement: Block memory writes if evidence incomplete (FAIL status), require PASS for progression
5. Approval Tracking: Identify required approvals (Engineering, Product, Security, Compliance), flag missing
6. Risk Assessment: Validate risk scores align with applied gates, flag unacknowledged HIGH drift
7. Verification Receipt Generation: Produce structured audit trail for every validation (PASS/FAIL/PENDING with rationale)

Inputs

The Verifier requires comprehensive context to perform validation:

1. SPEC Card

   • Functional requirements (user stories, acceptance criteria)
   • Non-functional requirements (performance, security, scalability)
   • Constraints (budget, timeline, technology stack)
   • Success criteria (measurable outcomes)

2. TEST Card

   • Test strategy (unit, integration, e2e, load, security)
   • Coverage requirements (80% code coverage minimum)
   • Test data requirements (sample payloads, edge cases)
   • NFR test plan (performance benchmarks, security scans)

3. Solver + Skeptic Cards

   • Solution proposed by Solver (architecture, implementation plan)
   • Skeptic's critique (risks identified, alternatives considered, mitigation plans)
   • Weighted consensus (how conflicts were resolved)

4. Evidence Pointers (Concrete Repository Paths)

   • PRD: /docs/PRD.md (Product Requirements Document with user stories, NFRs)
   • Architecture: /docs/ARCHITECTURE.md (C4 diagrams, ADRs, security review)
   • Domain Model: /docs/DOMAIN_MODEL.md (Event storming, ERD, bounded contexts)
   • Code: /src/**/*.ts (implementation files, typed, reviewed, no any)
   • Tests: /tests/**/*.test.ts (test files with 80%+ coverage)
   • CI/CD: /.github/workflows/ci.yml (pipeline config with security scans)
   • Evidence Card: /docs/EVIDENCE.md (CI/CD Evidence Card with test results, security scans)

5. World Model Invariants (35 rules to check)

   • Security: INV-001 to INV-008 (JWT, RBAC, MFA, encryption, multi-tenancy)
   • DevOps: INV-020 to INV-028 (CI/CD, testing, deployment automation)
   • Compliance: INV-029 to INV-035 (audit logs, health endpoints, SLOs)
   • Quality: INV-036 to INV-042 (code quality, defect tracking, security testing)

Output: Verification Receipt (MANDATORY)

Verification Receipt Schema

verification_receipt:
  # Overall status (gates progression)
  status: PASS | FAIL | PENDING
  
  # Verification metadata
  verification_id: "VER-2026-020"
  timestamp: "2026-01-31T15:30:00Z"
  verifier_version: "v1.5.0"
  workflow_stage: "CODE_REVIEW | DEPLOY_GATE | RELEASE_GATE"
  
  # Checks performed (20+ checks)
  checks_performed:
    - check: "SPEC Card completeness"
      status: PASS
      evidence: "/docs/PRD.md exists, 320 lines, 18 user stories, 7 functional reqs, 6 NFRs"
      
    - check: "TEST Card coverage"
      status: PASS
      evidence: "/docs/TEST_PLAN.md exists, 2,547 tests defined, 80.5% coverage"
      
    - check: "Code artifacts exist"
      status: PASS
      evidence: "/src/**/*.ts: 19 files, 2,100+ lines, TypeScript strict mode"
      
    - check: "INV-001: JWT Authentication"
      status: PASS
      evidence: "/src/middleware/auth.ts implements JWT RS256, /tests/auth.test.ts validates"
      
    - check: "INV-002: RBAC"
      status: FAIL
      evidence: "RBAC implemented in /src/middleware/rbac.ts but tests missing for 'manager' role"
      remediation: "Add tests for manager role in /tests/rbac.test.ts (3 test cases required)"
      
    - check: "SPEC ↔ TEST alignment"
      status: PASS
      evidence: "18 user stories in PRD.md, 18 test suites in /tests/**/*.test.ts (1:1 mapping)"
  
  # Evidence verified (concrete paths)
  evidence_verified:
    prd: "/docs/PRD.md"
    architecture: "/docs/ARCHITECTURE.md"
    domain_model: "/docs/DOMAIN_MODEL.md"
    code: "/src/**/*.ts (19 files)"
    tests: "/tests/**/*.test.ts (12 files)"
    cicd_pipeline: "/.github/workflows/ci.yml"
    cicd_evidence: "/docs/CI_CD_EVIDENCE.md"
  
  # Invariant compliance (35 invariants)
  invariant_compliance:
    total: 35
    compliant: 18
    violated: 2
    not_applicable: 15
    
    violations:
      - invariant: "INV-002: RBAC"
        severity: MEDIUM
        description: "Role-Based Access Control tests incomplete (manager role not tested)"
        remediation: "Add 3 test cases for manager role in /tests/rbac.test.ts"
        blocking: false
        
      - invariant: "INV-021: Automated Testing 80%+"
        severity: HIGH
        description: "Code coverage 78.3% (target 80%+)"
        remediation: "Add tests for /src/utils/validators.ts (currently 45% coverage)"
        blocking: true
  
  # Gaps / missing evidence
  gaps_missing_evidence:
    - gap: "Load testing results missing"
      severity: MEDIUM
      impact: "Cannot verify INV-022 (performance testing) compliance"
      required_action: "Run k6 load test for /api/orders endpoint, target 1000 req/s"
      
    - gap: "Security scan report not in evidence"
      severity: HIGH
      impact: "Cannot verify INV-042 (security testing) compliance"
      required_action: "Upload Snyk/CodeQL SARIF report to /docs/security-scan.sarif"
  
  # Required approvals
  required_approvals:
    engineering_lead: APPROVED
    product_manager: APPROVED
    security_team: PENDING  # Waiting for security scan results
    compliance_team: NOT_REQUIRED  # No regulated data in this release
  
  approvals_missing:
    - role: "Security Team"
      reason: "Security scan report missing (INV-042 violation)"
      blocking: true
      eta: "2 hours (run Snyk scan, upload report)"
  
  # Cross-agent consistency checks
  consistency_checks:
    - check: "SPEC ↔ TEST alignment"
      status: PASS
      details: "18 user stories in SPEC, 18 test suites in TEST Card (1:1 mapping)"
      
    - check: "Architecture ↔ Code alignment"
      status: PASS
      details: "4 services in Architecture, 4 modules in /src (orders, products, users, payments)"
      
    - check: "Domain Model ↔ Database schema alignment"
      status: FAIL
      details: "Domain Model has 8 entities, Prisma schema has 7 models (missing 'AuditLog' model)"
      remediation: "Add AuditLog model to /prisma/schema.prisma for INV-029 compliance"
  
  # Risk assessment
  risk_assessment:
    overall_risk: MEDIUM
    risk_factors:
      - factor: "Coverage below 80% threshold"
        severity: HIGH
        mitigation: "Add 15 tests to reach 80.1% coverage"
        
      - factor: "Security scan pending"
        severity: MEDIUM
        mitigation: "Run Snyk scan (ETA 30 min)"
    
    unacknowledged_high_drift: []  # No HIGH drift detected
  
  # Recommendation (next action)
  recommendation: "CONDITIONAL_PASS: Fix 2 blocking issues within 4 hours, then re-verify"
  
  next_actions:
    - action: "Add RBAC tests for manager role"
      priority: P1
      assignee: "@backend-team"
      eta: "2 hours"
      
    - action: "Add tests to /src/utils/validators.ts to reach 80% coverage"
      priority: P0
      assignee: "@backend-team"
      eta: "2 hours"
      
    - action: "Run Snyk security scan, upload SARIF report"
      priority: P0
      assignee: "@security-team"
      eta: "30 minutes"
      
    - action: "Add AuditLog model to Prisma schema"
      priority: P1
      assignee: "@backend-team"
      eta: "1 hour"
  
  # Audit trail
  audit_trail:
    created_at: "2026-01-31T15:30:00Z"
    created_by: "VerifierAgent v1.5.0"
    evidence_hash: "sha256:abc123def456..."  # Hash of all evidence files
    previous_verification: "VER-2026-019"
    verification_duration: "45 seconds"

Rules (Non-Negotiable)

1. Evidence Required: If evidence is missing (file paths invalid, content empty), status must be FAIL or PENDING. Never assume or extrapolate.

2. No Memory Writes Without PASS: Only PASS status allows progression to production memory. FAIL blocks, PENDING requires follow-up.

3. Concrete Paths Only: Evidence pointers must be actual repository paths (/src/auth.ts), not placeholders (TBD, TODO, Coming Soon).

4. Invariant Violations Explicit: Every violated invariant must have severity (LOW/MEDIUM/HIGH/CRITICAL), remediation plan, and blocking flag.

5. Cross-Agent Consistency: SPEC user stories must map to TEST test cases (1:1). Architecture services must map to code modules. Misalignment = FAIL.

6. Approval Tracking: Required approvals must be identified based on change type (security-sensitive = Security approval, user-facing = Product approval).

7. Re-Verification on Changes: If code changes after verification, previous receipt is invalidated. Must re-verify (invalidation timestamp recorded).

Verification Templates

Template 1: PRD Verification

Purpose: Validate Product Requirements Document completeness before solution architecture begins.

Checklist (10 items):

prd_verification:
  - check: "File exists"
    path: "/docs/PRD.md"
    validation: "File size >10KB (non-trivial)"
    
  - check: "User stories defined"
    validation: "Count ≥5 user stories with As/I want/So that format"
    example: "As a customer, I want to view order history, so that I can track my purchases"
    
  - check: "Functional requirements"
    validation: "Count ≥3 functional requirements with acceptance criteria"
    example: "FR-001: API must return order list within 200ms (p95)"
    
  - check: "Non-functional requirements"
    validation: "NFRs for performance, security, scalability defined"
    required_nfrs: ["Performance", "Security", "Scalability", "Availability", "Maintainability"]
    
  - check: "Success criteria"
    validation: "Measurable outcomes defined (not vague)"
    example_good: "Reduce checkout time by 30% (from 120s to 84s)"
    example_bad: "Improve user experience" (NOT measurable)
    
  - check: "Constraints documented"
    validation: "Budget, timeline, technology stack specified"
    
  - check: "Stakeholders identified"
    validation: "Engineering Lead, Product Manager, target users listed"
    
  - check: "Assumptions documented"
    validation: "≥3 assumptions explicitly stated"
    example: "Assume payment gateway (Stripe) has 99.9% uptime"
    
  - check: "Out of scope"
    validation: "Features explicitly excluded to prevent scope creep"
    
  - check: "Approval status"
    validation: "Product Manager approval recorded"

Pass Condition: ALL 10 checks PASS

Example PASS:

prd_verification_receipt:
  status: PASS
  checks_passed: 10
  checks_failed: 0
  evidence:
    file_path: "/docs/PRD.md"
    file_size: "24KB"
    user_stories: 18
    functional_requirements: 7
    nfrs: 6
    success_criteria: 5
    stakeholders: 8
  recommendation: "PRD complete, proceed to solution architecture"

Example FAIL:

prd_verification_receipt:
  status: FAIL
  checks_passed: 7
  checks_failed: 3
  violations:
    - check: "Success criteria"
      reason: "Vague: 'Improve performance' (not measurable)"
      remediation: "Specify target: 'Reduce p95 latency from 500ms to 200ms'"
      
    - check: "NFRs"
      reason: "Missing security NFR (no mention of authentication, RBAC, encryption)"
      remediation: "Add security NFR: JWT auth, RBAC with 3 roles, PII encryption at rest"
      
    - check: "Approval status"
      reason: "Product Manager approval not recorded"
      remediation: "Get Product Manager sign-off before proceeding"
  
  recommendation: "FAIL - Fix 3 issues, then re-verify. Do NOT proceed to architecture."

Template 2: Architecture Verification

Purpose: Validate solution architecture before code generation begins.

Checklist (12 items):

architecture_verification:
  - check: "File exists"
    path: "/docs/ARCHITECTURE.md"
    validation: "File size >20KB (comprehensive)"
    
  - check: "C4 Context diagram"
    validation: "System context showing users, external systems, boundaries"
    
  - check: "C4 Container diagram"
    validation: "Containers (web app, API, database, cache) with relationships"
    
  - check: "C4 Component diagram"
    validation: "Components within each container (controllers, services, repositories)"
    
  - check: "Technology stack"
    validation: "Languages, frameworks, databases, infrastructure specified"
    example: "Node.js 20, TypeScript 5.3, Express 4.x, PostgreSQL 16, Redis 7, Docker"
    
  - check: "Architecture Decision Records (ADRs)"
    validation: "≥3 ADRs documenting key decisions"
    example_adr: "ADR-001: Chose PostgreSQL over MongoDB for ACID transactions"
    
  - check: "Security architecture"
    validation: "Authentication, authorization, encryption, secrets management documented"
    
  - check: "Data flow diagrams"
    validation: "Critical user journeys documented (e.g., checkout flow, auth flow)"
    
  - check: "Failure modes"
    validation: "≥3 failure scenarios with mitigation (database down, API timeout, cache miss)"
    
  - check: "Scalability plan"
    validation: "Horizontal scaling approach (load balancer, stateless services, DB read replicas)"
    
  - check: "Observability design"
    validation: "Logging, metrics, tracing, health endpoints specified"
    
  - check: "Alignment with SPEC"
    validation: "All user stories from PRD mapped to architecture components"

Pass Condition: ALL 12 checks PASS

Cross-Agent Consistency Check:

spec_architecture_alignment:
  spec_user_stories: 18
  architecture_components: 4  # orders, products, users, payments
  
  mapping:
    - user_story: "US-001: View product catalog"
      component: "ProductService"
      endpoints: ["GET /api/products", "GET /api/products/:id"]
      
    - user_story: "US-002: Add product to cart"
      component: "OrderService"
      endpoints: ["POST /api/cart/items"]
  
  validation: "18 user stories ↔ 18 endpoints (1:1 mapping) = PASS"

Template 3: Code Verification

Purpose: Validate implementation quality before deployment.

Checklist (15 items):

code_verification:
  - check: "Files exist"
    path: "/src/**/*.ts"
    validation: "≥10 implementation files (non-trivial project)"
    
  - check: "TypeScript strict mode"
    validation: "tsconfig.json has strict: true, no `any` types used"
    
  - check: "Linter clean"
    validation: "eslint reports 0 errors (warnings OK if documented)"
    
  - check: "Code formatting"
    validation: "Prettier applied, consistent style (2 spaces, single quotes)"
    
  - check: "Code review"
    validation: "≥1 approver (2+ for critical changes), review comments addressed"
    
  - check: "Architecture alignment"
    validation: "Code structure matches architecture diagram (4 services → 4 src/ folders)"
    
  - check: "Test coverage"
    validation: "≥80% line coverage, ≥70% branch coverage"
    
  - check: "Security implemented"
    validation: "JWT auth, RBAC middleware, input validation, SQL injection prevention"
    
  - check: "Error handling"
    validation: "Try-catch blocks, error middleware, 4xx/5xx responses structured (RFC 7807)"
    
  - check: "Logging"
    validation: "Structured logs (JSON), PII masked, correlation IDs, log levels (DEBUG/INFO/WARN/ERROR)"
    
  - check: "Environment variables"
    validation: "No hardcoded secrets, .env.example provided, validation on startup"
    
  - check: "Database migrations"
    validation: "Prisma migrations exist, backward-compatible, rollback tested"
    
  - check: "API documentation"
    validation: "OpenAPI spec OR README with endpoint documentation"
    
  - check: "Dependencies"
    validation: "No critical/high vulnerabilities (npm audit / Snyk)"
    
  - check: "Docker support"
    validation: "Dockerfile + docker-compose.yml exist, multi-stage build, non-root user"

Pass Condition: ≥13/15 checks PASS (allow 2 minor gaps if documented)

Common Violations & Remediation:

Template 4: Test Verification

Purpose: Validate test suite completeness and quality.

Checklist (10 items):

test_verification:
  - check: "Test files exist"
    path: "/tests/**/*.test.ts"
    validation: "≥10 test files (non-trivial coverage)"
    
  - check: "Test types coverage"
    validation: "Unit tests (isolated), Integration tests (API), E2E tests (user flows)"
    
  - check: "Coverage threshold"
    validation: "≥80% line coverage enforced in CI/CD pipeline (jest.config.js)"
    
  - check: "Test quality"
    validation: "No empty tests, no skipped tests (.skip / .todo removed before merge)"
    
  - check: "SPEC alignment"
    validation: "Each user story has ≥1 test suite (18 user stories → 18 test suites)"
    
  - check: "Edge cases"
    validation: "Error cases tested (400/404/500 responses, validation failures, auth failures)"
    
  - check: "Security tests"
    validation: "Auth tests (JWT validation, RBAC, expired tokens), SQL injection tests, XSS tests"
    
  - check: "Performance tests"
    validation: "Load tests (k6 / Artillery), benchmark target: 1000 req/s p95 <200ms"
    
  - check: "Test data"
    validation: "Fixtures / factories for test data (no hardcoded IDs, use faker.js)"
    
  - check: "CI/CD integration"
    validation: "Tests run on every commit, failures block merge"

SPEC ↔ TEST Alignment Check:

spec_test_alignment:
  spec_user_stories:
    - "US-001: View product catalog"
    - "US-002: Add to cart"
    - "US-003: Checkout with Stripe"
    # ... 15 more
  
  test_suites:
    - "products.test.ts: describe('Product Catalog', ...)"  # US-001
    - "cart.test.ts: describe('Cart Management', ...)"      # US-002
    - "checkout.test.ts: describe('Checkout Flow', ...)"    # US-003
    # ... 15 more
  
  alignment_score: "18/18 user stories have test coverage = PASS"
  
  missing_tests: []
  extra_tests: ["auth.test.ts"]  # OK, security not in user stories but required for security

Example FAIL (Missing Tests):

test_verification_receipt:
  status: FAIL
  checks_passed: 8
  checks_failed: 2
  
  violations:
    - check: "Coverage threshold"
      current: "78.3%"
      target: "80.0%"
      gap: "1.7%"
      remediation: "Add 15 tests to /src/utils/validators.ts (currently 45% coverage)"
      
    - check: "SPEC alignment"
      user_stories_with_tests: 16
      user_stories_without_tests: 2
      missing:
        - "US-015: Apply discount code"
        - "US-017: Generate invoice PDF"
      remediation: "Add test suites: discounts.test.ts, invoices.test.ts"
  
  recommendation: "FAIL - Add missing tests, then re-verify"

Template 5: Deploy Verification (Production Gate)

Purpose: Final gate before production deployment.

Checklist (20 items):

deploy_verification:
  # Code quality (5 checks)
  - check: "All previous verifications PASS"
    validation: "PRD ✅, Architecture ✅, Code ✅, Test ✅"
    
  - check: "Code review approved"
    validation: "≥1 approver, no unresolved comments"
    
  - check: "Branch protection"
    validation: "Main branch protected, requires PR with review"
    
  - check: "No WIP commits"
    validation: "No commits with 'WIP', 'TODO', 'FIXME' in message"
    
  - check: "Version bumped"
    validation: "package.json version updated (semver: major.minor.patch)"
    
  # Security (5 checks)
  - check: "Security scans PASS"
    validation: "SAST (CodeQL/Snyk), DAST (OWASP ZAP), dependency scan (npm audit)"
    
  - check: "Secrets management"
    validation: "No secrets in .env committed, secrets in vault (AWS Secrets Manager / HashiCorp Vault)"
    
  - check: "Authentication tested"
    validation: "JWT validation, RBAC, MFA (if required) tested"
    
  - check: "Vulnerability scan"
    validation: "Docker image scanned (Trivy / Snyk), no critical/high vulnerabilities"
    
  - check: "Security approval"
    validation: "Security team approved (for security-sensitive changes)"
    
  # Infrastructure (5 checks)
  - check: "CI/CD pipeline PASS"
    validation: "All tests passed, build successful, artifacts published"
    
  - check: "Staging deployment successful"
    validation: "Deployed to staging, smoke tests passed, no errors in logs"
    
  - check: "Database migrations tested"
    validation: "Migrations ran in staging, backward-compatible, rollback tested"
    
  - check: "Rollback plan documented"
    validation: "Step-by-step rollback instructions, MTTR target <5 min"
    
  - check: "Monitoring configured"
    validation: "Error rate, latency, traffic alerts configured (Prometheus / Datadog)"
    
  # Business (5 checks)
  - check: "Product approval"
    validation: "Product Manager approved (for user-facing changes)"
    
  - check: "Release notes prepared"
    validation: "Changelog, migration guide, breaking changes documented"
    
  - check: "Stakeholders notified"
    validation: "Engineering, Customer Success, Support teams notified 4h before deployment"
    
  - check: "On-call assigned"
    validation: "On-call engineer acknowledged, PagerDuty configured"
    
  - check: "Release window validated"
    validation: "Deployment scheduled during low-traffic window (2am UTC Sat night)"

Pass Condition: ALL 20 checks PASS (no exceptions for production gate)

Go/No-Go Decision:

deploy_gate_decision:
  status: GO | NO-GO | CONDITIONAL
  
  criteria_passed: 18 / 20
  criteria_failed: 2
  
  blocking_failures:
    - check: "Security scans PASS"
      status: FAIL
      reason: "Snyk found 1 high vulnerability (CVE-2025-1234 in lodash@4.17.20)"
      remediation: "Update lodash to 4.17.21+ (npm update lodash)"
      eta: "30 minutes"
      
    - check: "Test coverage"
      status: FAIL
      reason: "Coverage 78.3% (target 80%)"
      remediation: "Add 15 tests to validators.ts"
      eta: "2 hours"
  
  decision: NO-GO
  recommendation: "Fix 2 blocking issues (ETA 2.5h), then re-verify. Do NOT deploy until both PASS."

Invariant Checking Examples

Invariant: INV-001 (JWT Authentication Required)

Check:

invariant_check_inv_001:
  invariant: "INV-001: JWT Authentication Required"
  description: "All API endpoints (except /health, /login) must require JWT authentication"
  
  validation_steps:
    1. "Check /src/middleware/auth.ts exists"
    2. "Verify JWT verification logic (jsonwebtoken library, RS256 algorithm)"
    3. "Check Express app.use() applies auth middleware globally"
    4. "Verify exceptions: /health, /login, /register excluded"
    5. "Check tests: /tests/auth.test.ts validates expired tokens, invalid signatures, missing tokens"
  
  evidence:
    code: "/src/middleware/auth.ts (48 lines)"
    tests: "/tests/auth.test.ts (12 test cases)"
    config: "/src/app.ts applies middleware: app.use('/api', authMiddleware)"
  
  result: PASS

Example Violation:

invariant_violation_inv_001:
  invariant: "INV-001"
  status: FAIL
  reason: "Auth middleware not applied to /api/orders endpoint"
  evidence: "/src/routes/orders.ts missing authMiddleware import"
  impact: "Unauthenticated users can view all orders (security breach)"
  severity: CRITICAL
  remediation: |
    1. Import authMiddleware: `import { authMiddleware } from '../middleware/auth';`
    2. Apply to router: `router.use(authMiddleware);`
    3. Add test: `/tests/orders.test.ts should return 401 for unauthenticated request`
  blocking: true

Invariant: INV-002 (RBAC Required)

Check:

invariant_check_inv_002:
  invariant: "INV-002: Role-Based Access Control (RBAC)"
  description: "System must enforce role-based permissions (admin, manager, user)"
  
  validation_steps:
    1. "Check /src/middleware/rbac.ts exists"
    2. "Verify 3 roles defined: admin (full access), manager (read/write), user (read only)"
    3. "Check permission checks on sensitive endpoints (DELETE, PUT require admin)"
    4. "Verify role stored in JWT token payload"
    5. "Check tests: All 3 roles tested with access control scenarios"
  
  evidence:
    code: "/src/middleware/rbac.ts (authorization logic)"
    tests: "/tests/rbac.test.ts (9 test cases: 3 roles × 3 operations)"
    endpoints: "DELETE /api/orders/:id requires 'admin' role"
  
  result: PASS

Example Violation:

invariant_violation_inv_002:
  invariant: "INV-002"
  status: FAIL
  reason: "RBAC tests incomplete (manager role not tested)"
  evidence: "/tests/rbac.test.ts has tests for admin + user, missing manager"
  impact: "Cannot verify manager permissions work correctly"
  severity: MEDIUM
  remediation: |
    Add 3 test cases to /tests/rbac.test.ts:
    1. `it('allows manager to update order')`
    2. `it('prevents manager from deleting order')` (only admin can delete)
    3. `it('allows manager to view all orders')`
  blocking: false  # Can deploy but must fix within 1 week

Invariant: INV-021 (Automated Testing 80%+ Coverage)

Check:

invariant_check_inv_021:
  invariant: "INV-021: Automated Testing (80%+ Coverage)"
  description: "Code coverage must be ≥80% line coverage, ≥70% branch coverage"
  
  validation_steps:
    1. "Run coverage report: `npm test -- --coverage`"
    2. "Check jest.config.js has coverageThreshold: { global: { lines: 80, branches: 70 } }"
    3. "Verify CI/CD pipeline enforces threshold (build fails if coverage <80%)"
    4. "Check coverage report uploaded to Codecov for trend tracking"
  
  evidence:
    coverage_report: "Lines: 80.5% (2,123/2,637), Branches: 72.1% (568/788)"
    ci_config: "/.github/workflows/ci.yml fails build if coverage <80%"
    codecov: "https://codecov.io/gh/myorg/myapp"
  
  result: PASS

Example Violation:

invariant_violation_inv_021:
  invariant: "INV-021"
  status: FAIL
  reason: "Code coverage 78.3% (target 80%)"
  evidence: |
    Coverage report:
    - Lines: 78.3% (2,065/2,637) - BELOW THRESHOLD
    - Branches: 72.1% (568/788) - OK
    
    Uncovered files:
    - /src/utils/validators.ts: 45% coverage (31/68 lines)
    - /src/utils/formatters.ts: 60% coverage (24/40 lines)
  
  impact: "Risk of untested code paths causing bugs in production"
  severity: HIGH
  remediation: |
    Add 15 tests to reach 80.1% coverage:
    1. /tests/validators.test.ts: Add 8 tests for email, phone, date validators
    2. /tests/formatters.test.ts: Add 7 tests for currency, date, number formatters
    
    Command: `npx jest --coverage --collectCoverageFrom='src/utils/**'`
  blocking: true

Invariant: INV-042 (Security Testing Mandatory)

Check:

invariant_check_inv_042:
  invariant: "INV-042: Security Testing Mandatory"
  description: "SAST, DAST, dependency scans required before production deployment"
  
  validation_steps:
    1. "Check SAST scan ran (CodeQL / Snyk / Semgrep)"
    2. "Check DAST scan ran (OWASP ZAP / Burp Suite)"
    3. "Check dependency scan ran (npm audit / Snyk / Safety)"
    4. "Verify no critical/high vulnerabilities in reports"
    5. "Check SARIF report uploaded for audit trail"
  
  evidence:
    sast: "CodeQL scan: 0 critical, 0 high, 2 medium (false positives documented)"
    dast: "OWASP ZAP scan: No SQL injection, XSS, CSRF vulnerabilities"
    dependencies: "npm audit: 0 vulnerabilities (585 packages scanned)"
    sarif: "/docs/security-scan.sarif (uploaded to GitHub Security tab)"
  
  result: PASS

Example Violation:

invariant_violation_inv_042:
  invariant: "INV-042"
  status: FAIL
  reason: "Security scan report missing (SAST not run)"
  evidence: "No CodeQL / Snyk SARIF report in /docs or GitHub Security tab"
  impact: "Cannot verify application is free from security vulnerabilities"
  severity: CRITICAL
  remediation: |
    1. Run Snyk SAST scan:
       ```bash
       npm install -g snyk
       snyk test --sarif-file-output=snyk.sarif
       ```
    
    2. Upload SARIF to GitHub:
       ```bash
       gh api repos/:owner/:repo/code-scanning/sarifs --field sarif=@snyk.sarif
       ```
    
    3. Review report, fix critical/high vulnerabilities
    
    4. Re-verify after scan complete (ETA: 30 minutes)
  blocking: true

Cross-Agent Consistency Checks

Check 1: SPEC ↔ TEST Alignment

Validation: Every user story in SPEC must have corresponding test suite in TEST Card.

spec_test_consistency:
  spec_user_stories: 18
  test_suites: 18
  
  mapping:
    - user_story: "US-001: View product catalog"
      test_suite: "products.test.ts: GET /api/products"
      status: MAPPED
      
    - user_story: "US-002: Add to cart"
      test_suite: "cart.test.ts: POST /api/cart/items"
      status: MAPPED
    
    # ... 16 more mappings
  
  unmapped_user_stories: []
  unmapped_test_suites: ["auth.test.ts"]  # OK, security testing not in user stories
  
  alignment_status: PASS
  alignment_score: "18/18 user stories have test coverage (100%)"

Example Misalignment:

spec_test_misalignment:
  unmapped_user_stories:
    - "US-015: Apply discount code"
    - "US-017: Generate invoice PDF"
  
  impact: "2 user stories without tests = risk of unvalidated functionality in production"
  severity: HIGH
  remediation: |
    Add 2 test suites:
    1. /tests/discounts.test.ts: Test discount code validation, percentage calculation, max discount limit
    2. /tests/invoices.test.ts: Test PDF generation, email delivery, S3 upload
  
  status: FAIL

Check 2: Architecture ↔ Code Alignment

Validation: Architecture diagram components must match code structure.

architecture_code_consistency:
  architecture_components:
    - "OrderService (handles orders, cart, checkout)"
    - "ProductService (product catalog, search, inventory)"
    - "UserService (authentication, authorization, profiles)"
    - "PaymentService (Stripe integration, invoices, refunds)"
  
  code_modules:
    - "/src/orders/ (orders.controller.ts, orders.service.ts, orders.repository.ts)"
    - "/src/products/ (products.controller.ts, products.service.ts, products.repository.ts)"
    - "/src/users/ (users.controller.ts, users.service.ts, users.repository.ts)"
    - "/src/payments/ (payments.controller.ts, payments.service.ts, payments.repository.ts)"
  
  alignment_status: PASS
  alignment_score: "4/4 services ↔ 4 code modules (100% match)"

Example Misalignment:

architecture_code_misalignment:
  architecture_has_but_code_missing:
    - "NotificationService (email, SMS, push notifications)"
  
  code_has_but_architecture_missing: []
  
  impact: "Architecture mentions NotificationService but no implementation exists"
  severity: MEDIUM
  remediation: |
    Option 1: Remove NotificationService from architecture (defer to v2.6.0)
    Option 2: Implement /src/notifications/ with email service (8h effort)
  
  status: FAIL

Check 3: Domain Model ↔ Database Schema Alignment

Validation: Domain entities must map to database tables.

domain_schema_consistency:
  domain_entities:
    - "Order (aggregate root: orderId, customerId, status, total)"
    - "OrderItem (orderId, productId, quantity, price)"
    - "Product (productId, name, price, inventory)"
    - "Customer (customerId, email, name, role)"
    - "Payment (paymentId, orderId, amount, stripePaymentIntentId)"
    - "Tenant (tenantId, name, subscriptionPlan)"
    - "AuditLog (for INV-029 compliance)"
    - "Session (for MFA support)"
  
  database_tables:
    - "orders (id, tenant_id, customer_id, status, total, created_at)"
    - "order_items (id, order_id, product_id, quantity, price)"
    - "products (id, tenant_id, name, price, inventory_count)"
    - "users (id, tenant_id, email, password_hash, role)"
    - "payments (id, order_id, amount, stripe_payment_intent_id)"
    - "tenants (id, name, subscription_plan)"
    - "sessions (id, user_id, token, expires_at)"
  
  missing_in_database:
    - "AuditLog (required for INV-029: 7-year audit retention)"
  
  alignment_status: FAIL
  remediation: |
    Add audit_logs table to Prisma schema:
    ```prisma
    model AuditLog {
      id        String   @id @default(cuid())
      tenantId  String
      userId    String
      action    String   // CREATE, UPDATE, DELETE
      resource  String   // orders, products, users
      resourceId String
      changes   Json     // Old vs new values
      ipAddress String
      createdAt DateTime @default(now())
      
      tenant Tenant @relation(fields: [tenantId], references: [id])
      user   User   @relation(fields: [userId], references: [id])
      
      @@index([tenantId])
      @@index([userId])
      @@index([createdAt])
    }
    ```
  
  status: FAIL

Real-World Application: migrate-cli Project (Jan 31, 2026)

Project Overview

Successfully completed full SDLC workflow (PRD → ARCH → CODE → TEST → DEPLOY) for migrate-cli, a TypeScript CLI tool for database migrations. All 5 verification receipts passed with comprehensive evidence chains.

Verification Receipt Summary

1. PRD Verification (10/10 Checks PASS)

File: /examples/migrate-cli/VERIFICATION_RECEIPT_PRD.md

Key Evidence:

• File: PRD.md (640 lines, 19.2 KB)
• User Stories: 18 stories with As/I want/So that format
• Functional Requirements: 7 requirements with acceptance criteria
• NFRs: 6 non-functional requirements (performance, security, reliability, usability)
• Success Criteria: 5 measurable outcomes (e.g., "Migration execution time <2s for 100 migrations")
• Stakeholders: 8 identified (developers, DBAs, DevOps engineers)
• Approval: Product Manager signed off

Status: ✅ PASS (no violations)

Lessons Learned:

• Measurable success criteria prevented vague requirements
• Explicit out-of-scope prevented scope creep
• Early stakeholder identification enabled targeted documentation

2. Architecture Verification (11/12 Checks PASS, 1 PENDING)

File: /examples/migrate-cli/VERIFICATION_RECEIPT_ARCHITECTURE.md

Key Evidence:

• File: ARCHITECTURE.md (724 lines, 22.1 KB)
• C4 Diagrams: 4 diagrams (Context, Container, Component, Code)
• ADRs: 8 Architecture Decision Records
  • ADR-001: TypeScript over JavaScript (type safety)
  • ADR-002: Commander.js framework (CLI UX)
  • ADR-003: Database client patterns (singleton, pooling)
  • ADR-004: ESBuild for bundling (fast builds)
• Technology Stack: TypeScript 5.9, Node 20, pg@8.11, mysql2@3.6, better-sqlite3@9.2
• Security: Configuration validation, connection string sanitization
• Failure Modes: 5 scenarios documented (connection failure, invalid SQL, migration rollback)

Violations:

• PENDING: Load testing not yet performed (deferred to post-release validation)

Status: ✅ PASS (PENDING items non-blocking)

Lessons Learned:

• ADRs captured key decisions (prevented re-discussions)
• Failure mode analysis identified edge cases early
• Explicit technology stack prevented dependency confusion

3. Code Verification (13/15 Checks PASS)

File: /examples/migrate-cli/VERIFICATION_RECEIPT_CODE.md

Key Evidence:

• Files: 12 TypeScript source files (/src/**/*.ts)
• TypeScript Strict Mode: ✅ Enabled (tsconfig.json: strict: true)
• Linter: ✅ 0 ESLint errors
• Code Formatting: ✅ Prettier applied (2 spaces, single quotes)
• Test Coverage: 87.68% statements, 72.95% branches, 91.54% functions, 87.75% lines
  • Achievement: Exceeded 70% branch coverage threshold (started at 67.62%)
• Security: JWT-like token validation, input sanitization, SQL injection prevention (parameterized queries)
• Error Handling: Custom error classes (DatabaseConnectionError, MigrationExecutionError, ConfigurationError)
• Database Clients: Singleton pattern with connection pooling
• CLI Framework: Commander.js with type-safe options, exit codes

Violations:

• PENDING: Docker support deferred (not required for CLI tool, users install via npm)
• PENDING: OpenAPI spec not applicable (CLI tool, not REST API)

Status: ✅ PASS (13/15 required checks passed, 2 PENDING non-blocking)

Lessons Learned:

• Strict mode caught 15+ type errors during development
• Branch coverage (72.95%) was hardest metric to achieve (required testing error paths)
• Custom error classes improved error message clarity
• ESBuild bundler produced 37.6 kB bundle (faster than webpack)

Coverage Achievement Timeline:

1. Initial: 67.62% branches (FAIL - below 70% threshold)
2. +DB error tests: 69.12% branches (still below)
3. +Validation tests: 71.23% branches (PASS! ✅)
4. +Edge cases: 72.95% branches (final)

Untested Branches Identified:

• Database connection failures (42 branches)
• Async error handling in migrations
• CLI argument validation failures
• Null/undefined checks

4. Test Verification (10/10 Checks PASS)

File: /examples/migrate-cli/VERIFICATION_RECEIPT_TEST.md

Key Evidence:

• Test Files: 10 test suites (/tests/**/*.test.ts)
• Test Count: 59 tests (100% passing)
• Test Types:
  • Unit tests: 45 tests (isolated functions)
  • Integration tests: 14 tests (database interactions)
• Coverage: 87.68%/72.95%/91.54%/87.75% (all thresholds exceeded)
• SPEC Alignment: 18 user stories → 18 test groups (1:1 mapping)
• Edge Cases: Tested empty inputs, null handling, invalid types, connection failures
• Security Tests: Configuration validation, connection string sanitization
• Test Framework: Jest 29 with 80/70/80/80 thresholds enforced

Test Quality Metrics:

• No empty tests (.skip removed)
• No skipped tests (.todo removed)
• All tests follow AAA pattern (Arrange, Act, Assert)
• Clear test names: should throw DatabaseConnectionError when connection string is invalid

Status: ✅ PASS (all checks passed)

Lessons Learned:

• Branch coverage required systematic error path testing
• Integration tests caught database-specific issues (unique constraint violations)
• Jest coverage thresholds prevented regression
• Test factories (UserFactory) improved test data consistency

Branch Coverage Strategy Applied:

1. Identify all conditional branches (if/else, switch, ternary)
2. List error paths (try/catch, null checks, validation)
3. Map edge cases (empty, null,

…(truncated)