AIV Canonical Specification

Auditable Verification Standard for AI-Assisted Code Changes

Document Control

Table of Contents

1. Purpose and Scope
   • 1.1 Purpose
   • 1.2 Problem Statement
   • 1.3 Scope
   • 1.4 Relationship to Existing Standards
   • 1.5 Conformance Claims
   • 1.6 Conformance Scopes
   • 1.7 Adoption Ladder (Informative)
2. Normative References
3. Terms and Definitions
4. Threat Model
5. Risk Classification
6. Evidence Requirements
   • 6.1 Evidence Class Summary
   • 6.2 Class A — Execution Evidence
   • 6.3 Class B — Referential Evidence
   • 6.4 Class C — Negative Evidence
   • 6.5 Class D — Differential Evidence
   • 6.6 Class E — Intent Evidence
   • 6.7 Class F — Provenance Evidence
   • 6.8 Class G — Cognitive Evidence (Optional)
   • 6.9 Evidence Item Structure
   • 6.10 Evidence Retention
7. Verification Process
8. Compliance Levels
9. Gating Rules
10. Exception Protocol
11. Evidence Integrity Controls
12. Security Considerations
13. Privacy Considerations
14. Conformance Testing
15. Governance and Versioning

Appendices

• Appendix A — Auditor Checklist
• Appendix B — Packet Schema
• Appendix C — Validation Rules
• Appendix D — Finding Severity Taxonomy
• Appendix E — Immutability Mechanisms
• Appendix F — Profiles and Extensions

1. Purpose and Scope

1.1 Purpose

This standard defines minimum verifiable evidence requirements for code changes that include AI-authored or AI-assisted content.

AIV is not meant to make all code safer. It is meant to make high-velocity AI code auditable at scale.

Organizations shipping AI-generated code without conforming to this standard lack auditable assurance that changes were verified prior to deployment. Non-conformance represents unquantified risk exposure.

Critical Distinction: AIV does not claim to prove correctness. It claims to prove:

• What was verified
• By whom (accountable identity)
• When (immutable timestamp)
• Against what evidence (auditable artifacts)

This aligns AIV with established accountability models in financial auditing, aviation safety cases, and medical device validation—fields that survive precisely because they separate correctness from accountability.

1.2 Problem Statement

AI-assisted development increases code production throughput beyond what humans can reliably comprehend line-by-line. Organizations increasingly ship changes validated by proxy signals (tests, CI checks) rather than verified understanding. This creates systemic risk:

• Orphan Code: Logic exists in repositories but in no human's mental model
• Debug Inability: Engineers cannot troubleshoot code they did not understand when approving
• Verification Theater: Green CI badges provide false assurance without semantic comprehension
• Cognitive Debt: Accumulated unverified changes compound into systemic fragility

AIV addresses these risks through two complementary mechanisms:

Classes A–F solve the auditability problem: replacing "someone reviewed it" with "here is the immutable evidence of what was verified." This is sufficient for compliance, audit trails, and accountability.

Class G solves the cognitive problem: ensuring that verification involves actual understanding, not rubber-stamp approval. This is optional for base compliance but essential for organizations concerned about long-term maintainability and cognitive atrophy.

Organizations may adopt AIV incrementally:

1. Start with A–F for audit compliance and evidence integrity
2. Add Class G when ready to enforce cognitive engagement

1.3 Scope

This standard applies to:

• Pull requests / merge requests containing AI-generated or AI-assisted code
• Changes produced by LLMs, code generation tools, or autonomous agents
• Repositories using CI/CD pipelines capable of artifact retention

This standard does not apply to:

• Model training, fine-tuning, or RLHF governance
• Runtime monitoring or observability systems
• Threat modeling or design review processes
• Non-code artifacts (documentation-only changes may use reduced requirements per §5.1)

Positioning: AIV is intentionally downstream of code generation tools and model choices. AIV does not evaluate which AI models are "safer" or how code should be generated. It evaluates whether the resulting code was verified with auditable evidence before deployment.

1.4 Relationship to Existing Standards

AIV formalizes practices implicit in existing compliance frameworks:

1.4.1 Relationship to AI-Specific Standards (Informative)

AIV is designed to complement emerging AI governance frameworks:

Positioning: These frameworks answer different questions:

AIV does not compete with these frameworks. AIV provides the evidence specification that makes their requirements auditable at the code-change level.

1.5 Conformance Claims

An organization MAY claim AIV conformance at a specified Compliance Level (L1–L3) when:

1. All applicable requirements for that level are satisfied for changes in scope
2. Evidence artifacts are retained per §6.9
3. Conformance is validated per §14
4. Governance controls per §15 are documented

WARNING: Claims of conformance without validated evidence constitute misrepresentation and may expose the organization to liability.

1.6 Conformance Scopes

AIV requirements operate at two distinct scopes. Auditors and validators MUST understand which scope applies to each requirement.

1.6.1 Per-Change Requirements

Per-Change Requirements are validated against individual AIV Packets. A single change (PR/MR) either satisfies these requirements or it does not.

Sections containing primarily Per-Change Requirements:

• §5 Risk Classification (classification record)
• §6 Evidence Requirements (evidence classes A-F, evidence items)
• §7 Verification Process (attestation, known limitations)
• §8 Compliance Levels (level determination per change)
• §9.1–9.2 Gating Rules (merge gates)

1.6.2 Program Requirements

Program Requirements are validated against the organization's AIV implementation as a whole. They cannot be assessed by examining a single packet.

Sections containing primarily Program Requirements:

• §6.9 Evidence Retention (retention policy implementation)
• §9.3 Automated Enforcement (CI/CD configuration)
• §10 Exception Protocol (exception metrics, thresholds)
• §11.4 Audit Sampling (sampling implementation)
• §14.3 Conformance Claim Requirements (program-level thresholds)
• §15 Governance and Versioning (policy documentation)

1.6.3 Scope Markers

Throughout this specification, requirements are marked with scope indicators where ambiguity might arise:

• [Per-Change] — Requirement validated per packet
• [Program] — Requirement validated at organizational level

Where no marker is present, context determines scope: requirements about packet contents are Per-Change; requirements about organizational controls are Program.

1.7 Adoption Ladder (Informative)

This section is non-normative. It illustrates a typical adoption progression to help organizations understand that AIV conformance is incremental, not all-or-nothing.

┌─────────────────────────────────────────────────────────────────┐
│  ADOPTION LADDER                                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Level 0: No AIV                                                │
│    → AI code ships with green CI only                           │
│    → Risk: Unquantified, unauditable                            │
│                                                                 │
│  Level 1: AIV-L1 (Classes A + B + E)                            │
│    → Auditability without friction                              │
│    → Proves: Tests ran, code is traceable, intent documented    │
│    → Effort: Minimal (can be automated)                         │
│                                                                 │
│  Level 2: AIV-L2 (Classes A + B + C + E)                        │
│    → Production-grade AI changes                                │
│    → Adds: Negative evidence (no forbidden patterns)            │
│    → Effort: Moderate (requires test integrity tooling)         │
│                                                                 │
│  Level 3: AIV-L3 (Classes A – F)                                │
│    → Regulated / critical systems                               │
│    → Adds: Differential evidence, cryptographic provenance      │
│    → Effort: Significant (requires immutable storage, signing)  │
│                                                                 │
│  Level 4: AIV-L3 + Class G                                      │
│    → Cognitive ownership enforced                               │
│    → Adds: Prediction, trace, adversarial probe, ownership      │
│    → Effort: High (requires workflow changes, not just tooling) │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Recommendation: Most organizations should start at Level 1, stabilize tooling, then progress based on risk appetite and regulatory requirements.

2. Normative References

The following documents are referenced normatively. For dated references, only the edition cited applies. For undated references, the latest edition applies.

2.1 Normative Keyword Definitions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

For clarity:

• MUST / REQUIRED: Absolute requirement; non-compliance is a blocking finding
• MUST NOT: Absolute prohibition; violation is a blocking finding
• SHOULD / RECOMMENDED: Strong recommendation; deviation requires documented justification
• SHOULD NOT: Strong discouragement; use requires documented justification
• MAY / OPTIONAL: Truly optional; no justification required for either choice

3. Terms and Definitions

3.1 Change Terminology

3.2 Artifact Terminology

3.3 Immutability Definition

An artifact is considered immutable for AIV purposes if it satisfies ALL of the following criteria:

1. Content Integrity: The artifact content cannot be modified after creation without detection
2. Reference Stability: The reference (URL, path, ID) resolves to the same content indefinitely
3. Deletion Protection: The artifact cannot be deleted during the retention period without audit trail
4. Verification Method: A mechanism exists to verify the artifact has not been modified

Acceptable immutability mechanisms (see Appendix E for implementation details):

NOT acceptable as immutable:

• Branch-based URLs (content changes with branch)
• "Latest" links (content changes over time)
• Mutable issue tracker links without snapshot
• CI artifacts without retention guarantee
• Any reference that can be silently modified

3.4 Protocol Terminology

3.5 Classification Terminology

3.6 Role Terminology

4. Threat Model

4.1 Failure Modes AIV Addresses

AIV is designed to reduce risk from the following failure modes:

4.2 Failure Modes AIV Does NOT Address

AIV does not guarantee protection against:

4.3 Trust Boundaries

AIV assumes the following trust boundaries:

5. Risk Classification

5.1 Risk Tier Definitions

Every change subject to AIV MUST be classified into exactly one Risk Tier. If classification is uncertain, the change MUST be classified at the higher applicable tier.

5.2 Critical Surfaces (Mandatory R3 Escalation)

A change MUST be classified as R3 regardless of other factors if it modifies code in any of the following critical surfaces:

Finding (5.2-F1): Change touching critical surface classified below R3.

5.3 Blast Radius Assessment

For changes not touching critical surfaces, Risk Tier is informed by blast radius:

5.4 Separation of Duties Requirements

Finding (5.4-F1): SoD violation — Author and Verifier are same identity for R2+ change.

5.4.1 Identity Definition

Two identities are considered "different" if they correspond to different natural persons. The following do NOT satisfy SoD requirements:

• Shared accounts used by the same person in both roles
• Role accounts or service accounts operated by the same person
• Automation accounts acting on behalf of the same person
• Different usernames that map to the same natural person

5.4.2 Identity Verification Requirements

Organizations MUST document how Author and Verifier identities are verified as belonging to different natural persons. The AIV Policy (§15.1) MUST specify:

5.4.3 Edge Cases

5.4.4 Automated SoD Validation

Validators SHOULD implement automated SoD checks where possible:

# Example: SoD validation using email domain
sod_validation:
  method: "email_identity"
  author_identity: "alice@example.com"
  verifier_identity: "bob@example.com"
  same_person: false
  validation_source: "corporate_sso"

Where automated validation is not possible, the Verifier attestation MUST include an explicit declaration:

attestations:
  - verifier_id: "bob@example.com"
    sod_declaration: "I confirm I am not the same natural person as the Author (alice@example.com)"

Finding (5.4-F2): SoD verification method not documented in organizational policy. Finding (5.4-F3): Cross-platform identity mapping not documented for multi-platform workflow.

5.5 Classification Record

The AIV Packet MUST include a classification record with the following fields:

classification:
  risk_tier: R0 | R1 | R2 | R3 # REQUIRED
  sod_mode: S0 | S1 # REQUIRED
  critical_surfaces: [] # REQUIRED for R3; list of surfaces touched
  blast_radius: local | component | service | cross-service | organization # REQUIRED
  classification_rationale: string # REQUIRED; explanation of tier assignment
  classified_by: string # REQUIRED; identity performing classification
  classified_at: ISO-8601 timestamp # REQUIRED

Finding (5.5-F1): Missing or incomplete classification record. Finding (5.5-F2): Classification rationale missing or inadequate.

6. Evidence Requirements

6.1 Evidence Class Summary

Legend: ✓ = Required | ○ = Optional | (blank) = Not applicable

Note on Class G: Class G is optional for all compliance levels (L1–L3). Organizations seeking enhanced assurance of cognitive engagement SHOULD implement Class G, particularly for R3 changes. See §6.8 for full specification.

6.2 Class A — Execution Evidence

Purpose: Proves the change was executed in a controlled environment and automated checks passed.

6.2.1 Required Artifacts

6.2.2 Validation Rules

6.2.3 Findings

6.3 Class B — Referential Evidence

Purpose: Proves traceability from claims to exact code locations.

6.3.1 Required Artifacts

6.3.2 Validation Rules

6.3.3 Findings

6.4 Class C — Negative Evidence

Purpose: Proves absence of disallowed patterns and conservation of existing constraints.

6.4.1 Required Artifacts

6.4.2 Test Integrity Requirements

For R2+ changes, the packet MUST include evidence that test integrity was preserved:

IMPORTANT: Test integrity checks MUST use semantic analysis appropriate to the language/framework. Simple grep patterns are insufficient and MUST NOT be used as the sole verification method.

6.4.2.1 Semantic Analysis Minimum Criteria

A test integrity check qualifies as "semantic analysis" if it satisfies ALL of the following:

1. Structural Awareness: The method understands code structure (functions, classes, blocks), not just text patterns
2. Change Detection Granularity: Can detect individual assertion/test additions and removals, not just file-level changes
3. Framework Recognition: Recognizes the testing framework's assertion patterns (e.g., assert, expect, should, matchers)
4. Deterministic Output: Produces the same result when run multiple times on the same inputs
5. Machine-Readable Results: Outputs structured data (JSON, XML, etc.) suitable for automated validation

Acceptable methods with qualification:

Not acceptable as sole method:

Profile Requirement: If no language-specific AIV Profile exists for the project's language/framework, the packet MUST include:

1. Documentation of the semantic analysis method used
2. Justification that the method satisfies the minimum criteria above
3. Example output demonstrating structural awareness

6.4.3 Validation Rules

6.4.4 Findings

6.5 Class D — Differential Evidence

Purpose: Proves change impact beyond what tests capture, including API surface, dependencies, and data schemas.

6.5.1 Required Artifacts (R3)

For R3 changes, the packet MUST include differential evidence for each category of surface touched:

NOTE: "At least one" differential artifact is NOT sufficient. The packet MUST include artifacts for each category that applies to the change.

6.5.2 Validation Rules

6.5.3 Findings

6.6 Class E — Intent Evidence

Purpose: Proves implementation aligns with upstream requirement or specification.

6.6.1 Required Artifacts

6.6.2 Immutable Requirement Reference

The requirement reference MUST be immutable per §3.3. Acceptable mechanisms include:

Implementation Guidance: Organizations SHOULD establish a standard mechanism for creating immutable requirement references. Common approaches:

1. Spec-in-Repo: Requirements tracked as markdown files in the repository; reference by commit SHA
2. Snapshot Export: Issue/ticket exported to immutable storage; hash recorded in packet
3. Version Tagging: Issue tracker configured to create immutable versions; reference specific version ID

6.6.2.1 Transitional Pathway for Requirement Immutability

Recognizing that many organizations use mutable issue trackers (GitHub Issues, Jira, Linear, etc.) without snapshot infrastructure, AIV provides a transitional pathway:

For L1/L2 with mutable references:

When a mutable requirement reference is used at L1 or L2, the packet MUST include:

requirement_reference:
  url: "https://github.com/org/repo/issues/42" # Mutable URL
  immutable: false
  snapshot_obligation:
    required_by: ISO-8601 # Within 30 days of merge
    snapshot_method: "pdf_export | api_export | archive_org"
    responsible_party: string
  content_summary: string # Brief summary of requirement at time of verification
  verified_at: ISO-8601 # When verifier confirmed requirement content

Post-Merge Snapshot Requirement:

For L2 conformance claims, organizations MUST:

1. Create an immutable snapshot within 30 days of merge
2. Update the packet or create a supplement with the snapshot reference
3. Track snapshot completion rate as a program metric

Finding (E-F1a): Mutable requirement reference at L3 (BLOCK). Finding (E-F1b): Mutable requirement reference at L1/L2 without snapshot obligation (WARN). Finding (E-F6): Snapshot obligation not fulfilled within deadline (WARN → BLOCK after 30 days).

6.6.3 Validation Rules

6.6.4 Findings

6.7 Class F — Provenance Evidence

Purpose: Proves artifact integrity and chain-of-custody; establishes that evidence was not forged.

6.7.1 Required Artifacts (R3)

6.7.2 Acceptable Provenance Mechanisms

6.7.3 Validation Rules

6.7.4 Findings

6.8 Class G — Cognitive Evidence (Optional)

Purpose: Proves that human verification involved semantic comprehension, not just approval. Class G addresses the cognitive problem that Classes A–F cannot solve: ensuring the verifier actually understood the change.

Status: Optional for all compliance levels (L1–L3). RECOMMENDED for R3 changes. Organizations seeking enhanced assurance of cognitive engagement SHOULD implement Class G.

6.8.1 The Cognitive Problem

Classes A–F prove that verification occurred and that evidence exists. They do not prove that the verifier understood the change. This creates a failure mode:

Class G addresses this gap by requiring evidence of cognitive work product—artifacts that could only be produced by someone who understood the change.

Critical Framing: Class G does not guarantee deep understanding. No artifact can prove what someone truly comprehends. What Class G does guarantee is that:

1. Someone incurred cognitive cost — producing predictions, traces, and probes requires mental effort
2. Someone accepted ownership — the ownership declaration creates personal accountability
3. A paper trail exists — if the code fails, there is a named person who attested to understanding it

This reframes Class G as ownership enforcement, not epistemic purity. The goal is not to prove the verifier is brilliant—it is to ensure the code is owned, not orphaned.

6.8.2 Required Artifacts (When Implemented)

When an organization implements Class G, packets MUST include:

6.8.3 The Four-Phase Verification Process (SVP)

Class G artifacts follow the Systematic Verifier Protocol (SVP):

Phase 1: Black Box Prediction Before examining implementation, the verifier documents:

• Expected behavior based on requirements
• Predicted approach to solving the problem
• Anticipated edge cases

Phase 2: Mental Trace While examining code, the verifier documents:

• Execution flow for primary use case
• State transformations at each step
• Where predictions matched or diverged

Phase 3: Adversarial Probe After understanding implementation, the verifier documents:

• At least 3 edge cases considered
• At least 1 potential failure mode
• How implementation handles (or fails to handle) each

Phase 4: Ownership Lock The verifier attests:

• "I could debug this code without AI assistance"
• "I could explain this code to another engineer"
• "I could modify this code to handle a new requirement"

6.8.4 Evidence Structure

evidence_items:
  - id: "EV-G-001"
    class: G
    description: "Cognitive verification evidence"
    artifacts:
      - type: prediction_document
        reference: string # URL or content-addressed ID
        created_before_code_review: boolean # MUST be true
        timestamp: ISO-8601
        content_hash: string # SHA-256 of prediction content

      - type: mental_trace
        reference: string
        lines_referenced: [string] # Specific line numbers traced
        functions_traced: [string] # Function names in trace

      - type: adversarial_probe
        edge_cases_count: integer # Minimum 3
        failure_modes_count: integer # Minimum 1
        reference: string

      - type: ownership_declaration
        attestations:
          - can_debug_without_ai: boolean
          - can_explain_to_peer: boolean
          - can_modify_for_new_requirement: boolean
        verifier_signature: string

6.8.5 Validation Rules

6.8.6 Findings

6.8.7 Gaming Resistance

Class G is inherently more susceptible to gaming than Classes A–F because cognitive work cannot be machine-verified. Mitigations include:

Audit Sampling for Class G: Organizations implementing Class G SHOULD conduct periodic spot-checks where verifiers are asked to explain or modify code they previously verified.

6.8.8 When to Implement Class G

Organizational Adoption Path:

1. Start with Classes A–F for all changes
2. Add Class G for R3 changes only
3. Expand to R2 as tooling matures
4. Evaluate whether R1 benefits from Class G

6.9 Evidence Item Structure

Each evidence item in the packet MUST conform to this structure:

evidence_items:
  - id: string # Unique identifier within packet
    class: A | B | C | D | E | F | G # Evidence class
    description: string # Human-readable description
    claim_refs: [string] # IDs of claims this evidence supports
    artifacts:
      - type: string # ci_run | permalink | search_output | diff | attestation | prediction_document | mental_trace | etc.
        reference: string # URL or content-addressed ID
        immutability_mechanism: string # How immutability is achieved (§3.3)
        canonical_form: string # How artifact was canonicalized for hashing (§6.9.1)
        sha256: string # SHA-256 hash of canonical form (REQUIRED for R3)
        retrieved_at: ISO-8601 # When artifact was retrieved/created
    scope: string # What this evidence covers
    validation_method: string # How to verify this evidence
    limitations: [string] # Known limitations of this evidence

6.9.1 Artifact Canonicalization for Hashing

Artifact hashes MUST be computed on a canonical, stable representation of the artifact content. Hashing raw HTTP responses or rendered HTML is NOT acceptable because these contain dynamic elements (timestamps, session tokens, ads, etc.) that change on each retrieval.

Canonicalization Requirements:

Canonicalization Rules:

1. Export over scrape: Use API exports or file downloads, not scraped HTML
2. Deterministic format: Output format must produce identical bytes for identical content
3. Strip dynamic elements: Remove timestamps, session IDs, or other volatile fields before hashing (document what was stripped)
4. Document the form: The canonical_form field MUST describe how the artifact was canonicalized

Example Canonical Forms:

# GOOD - CI run exported as JSON via API
canonical_form: "GitHub Actions API JSON export (workflow run endpoint)"
sha256: "abc123..."

# GOOD - Test output captured from framework
canonical_form: "pytest --json-report output file"
sha256: "def456..."

# BAD - HTML page scraped
canonical_form: "Downloaded HTML from CI URL"  # NOT ACCEPTABLE - HTML contains dynamic content

Finding (6.9-F1): Artifact hash computed on non-canonical form. Finding (6.9-F2): Canonical form not documented. Finding (6.9-F3): Hash verification failed due to dynamic content in canonical form.

6.10 Evidence Retention

6.10.1 Default Retention Periods

The following are default minimum retention periods for organizations without regulatory requirements. These defaults align with common compliance frameworks:

6.10.2 Organizational Override

Organizations MAY specify different retention periods in their AIV Policy (§15.1), subject to the following constraints:

NOTE: Organizations subject to specific regulations (SOX, HIPAA, PCI-DSS, etc.) MUST comply with those regulations regardless of AIV defaults. The AIV defaults are designed for organizations without such requirements.

6.10.3 Retention by Artifact Type

6.10.4 Storage Requirements for R3

• Artifacts MUST be stored in immutable storage (WORM, Object Lock, or equivalent)
• Access logs MUST be retained for the same period
• Deletion MUST require documented approval and audit trail
• Organizations using override periods <7 years MUST document regulatory analysis justifying the shorter period

Finding (6.10-F1): Evidence retention below minimum for tier (or organizational override floor). Finding (6.10-F2): R3 artifacts not in immutable storage. Finding (6.10-F3): Retention override without documented policy.

7. Verification Process

7.1 Verifier Obligations

For all changes requiring verification (all tiers except where organizational policy explicitly overrides for R0), the Verifier MUST:

7.2 Verification Decision

The Verifier MUST record exactly one decision:

7.3 Conditional Decision Constraints

CRITICAL: A CONDITIONAL decision MUST NOT be used to bypass BLOCK-severity findings.

CONDITIONAL is permitted ONLY when:

1. ALL BLOCK-severity validation rules pass
2. One or more WARN-severity findings exist
3. A remediation plan is documented for each WARN finding
4. Remediation deadline does not exceed 30 days
5. Responsible party is identified for remediation

Finding (7.3-F1): CONDITIONAL decision used to bypass BLOCK-severity finding.

7.4 Attestation Record

The AIV Packet MUST include a Verifier attestation with the following structure:

attestations:
  - id: string # Unique attestation ID
    verifier_id: string # Verifier identity (REQUIRED)
    verifier_identity_type: string # github | email | oidc | etc.
    decision: COMPLIANT | CONDITIONAL | NON-COMPLIANT # (REQUIRED)
    timestamp: ISO-8601 # When attestation was created (REQUIRED)

    # Verification details
    evidence_classes_validated: [A, B, C, D, E, F] # Which classes were checked
    validation_rules_checked: [string] # Rule IDs that were validated
    findings: [Finding] # Any findings discovered

    # Conditional decision details (REQUIRED if CONDITIONAL)
    conditions:
      - finding_id: string
        remediation_plan: string
        remediation_deadline: ISO-8601
        responsible_party: string

    # Non-compliant decision details (REQUIRED if NON-COMPLIANT)
    blocking_findings: [string] # Finding IDs that block merge
    rationale: string # Explanation of non-compliance

    # Cryptographic binding (REQUIRED for R3)
    signature_method: GPG | OIDC | sigstore | unsigned
    signature: string # If signed
    signed_fields: [string] # Which fields are covered by signature

Finding (7.4-F1): Missing Verifier attestation. Finding (7.4-F2): Attestation incomplete (missing required fields). Finding (7.4-F3): R3 attestation unsigned.

7.5 Known Limitations

Every AIV Packet MUST include a known_limitations section.

This section MUST NOT be empty. If no limitations are identified, it MUST explicitly state: ["No limitations identified. Full evidence coverage achieved for declared scope."]

Limitations SHOULD include:

• Untested scenarios or edge cases
• Partial coverage areas
• Non-reproducible elements (with justification)
• Deferred validations
• Environmental assumptions

Finding (7.5-F1): known_limitations field missing or genuinely empty (not explicitly stating none).

8. Compliance Levels

8.1 Level Definitions

8.2 Tier-to-Level Minimum Mapping

A change MUST NOT claim a compliance level below its risk tier minimum:

Finding (8.2-F1): Compliance level below minimum for risk tier.

8.3 Level Requirements Matrix

9. Gating Rules

9.1 Merge Gate

A change MUST NOT merge if any of the following conditions are true:

9.2 Artifact Immutability Gate

Finding (9.2-F1): Mutable artifact reference in required evidence. Finding (9.2-F2): R3 evidence artifact without verifiable hash.

9.3 Automated Enforcement [Program]

Scope: This section defines Program Requirements, not Per-Change Requirements. These are validated during organizational audits, not per-packet validation.

Organizations SHOULD implement automated gate enforcement via:

• CI/CD pipeline integration
• Branch protection rules
• Policy-as-code validators (e.g., OPA, Kyverno)

Automated enforcement MUST:

• Execute on every PR/MR update
• Block merge on any BLOCK-severity finding
• Produce machine-readable results conforming to §14.2
• Log all gate decisions to audit trail

Finding (9.3-F1): [Program] Automated enforcement not implemented for repository.

10. Exception Protocol

10.1 Purpose

The exception protocol (break-glass) exists to handle genuine emergencies where evidence cannot be produced without unacceptable harm. It is NOT a mechanism for bypassing verification on a routine basis.

10.2 Exception Conditions

An exception MAY be invoked ONLY when ALL of the following are true:

1. A production incident or security vulnerability requires immediate remediation
2. Delay to produce required evidence would cause measurable harm (downtime, data loss, security exposure)
3. The harm from delay exceeds the risk of reduced verification
4. A Designated Exception Approver (§10.3) authorizes the exception

10.3 Designated Exception Approver

Organizations MUST define Designated Exception Approvers in their AIV policy. The designation MUST specify:

Minimum authorization requirements:

10.4 Exception Record

When an exception is invoked, the packet MUST include:

exception:
  invoked: true

  # Justification (REQUIRED)
  incident_reference: string # Link to incident ticket/page
  harm_description: string # What harm would delay cause
  harm_severity: string # Quantified impact if possible

  # Approval (REQUIRED)
  approver_id: string # Identity of approver
  approver_role: string # Functional role, not job title
  approval_timestamp: ISO-8601
  approval_method: string # How approval was recorded (Slack, PagerDuty, etc.)

  # Scope (REQUIRED)
  evidence_classes_waived: [A, B, C, D, E, F] # Which classes are incomplete
  validation_rules_waived: [string] # Which rules are not enforced

  # Time bounds (REQUIRED)
  exception_start: ISO-8601
  validity_window_hours: integer # MUST NOT exceed 72
  exception_expires: ISO-8601 # Calculated from start + window

  # Follow-up (REQUIRED)
  follow_up_obligation: string # What must be done within window
  follow_up_deadline: ISO-8601 # MUST be within validity window
  follow_up_owner: string # Identity responsible for follow-up

  # Resolution (populated after exception period)
  resolution_status: pending | completed | reverted
  resolution_timestamp: ISO-8601
  resolution_evidence: string # Link to completed evidence or revert commit

10.5 Exception Constraints

10.6 Exception Metrics and Thresholds

Organizations MUST track exception metrics:

Finding (10.6-F1): Exception invoked without required approvals. Finding (10.6-F2): Exception validity window exceeded without resolution. Finding (10.6-F3): Exception not logged to audit trail. Finding (10.6-F4): Exception rate exceeds threshold without documented review.

11. Evidence Integrity Controls

11.1 Purpose

Evidence integrity controls prevent "verification theater" — situations where packets exist but do not actually prove claims. These controls operate as meta-verification of the verification process itself.

11.2 Required Controls by Tier

11.3 Test Integrity Validation

For R2+ changes, test integrity MUST be validated using semantic analysis:

Implementation Note: Organizations MUST use language-appropriate tooling. The AIV-Python and AIV-Node profiles (Appendix F) provide specific tool recommendations.

Finding (11.3-F1): Test integrity validation used inadequate method. Finding (11.3-F2): Test integrity degradation detected without justification.

11.4 Audit Sampling [Program]

Scope: This section defines Program Requirements, not Per-Change Requirements. These are validated during organizational audits, not per-packet validation.

For R3 changes, organizations MUST implement audit sampling:

Audit Checklist (per sampled change):

1. Retrieve all evidence artifacts using only packet references
2. Verify each artifact hash matches packet record
3. Verify CI run executed at recorded commit SHA
4. Verify test results match CI run output
5. Verify negative evidence searches are reproducible
6. Verify requirement reference is retrievable and immutable
7. Verify provenance signatures are valid
8. Document any discrepancies as findings

Finding (11.4-F1): [Program] Audit sampling not implemented for R3 changes. Finding (11.4-F2): [Program] Audit sampling rate below 10%. Finding (11.4-F3): [Program] Audit findings not resolved.

12. Security Considerations

12.1 Packet Security

12.2 Evidence Security

12.3 CI/CD Security

12.4 Secret Scanning

Evidence artifacts MUST NOT contain:

• API keys or tokens
• Passwords or credentials
• Private keys or certificates
• Connection strings with credentials
• PII beyond minimum necessary

Organizations SHOULD implement automated secret scanning on evidence artifacts before packet finalization.

13. Privacy Considerations

13.1 Data Minimization

Evidence artifacts SHOULD contain the minimum data necessary to support claims. Specifically:

• Logs SHOULD be filtered to relevant entries
• Stack traces SHOULD be truncated to relevant frames
• Test output SHOULD exclude verbose debugging
• Screenshots SHOULD be cropped to relevant areas

13.2 PII Handling

13.3 Retention and Deletion

• Retention periods (§6.9) represent MINIMUM retention
• Organizations MAY retain longer if permitted by applicable law
• Deletion requests MUST be handled per applicable privacy regulations
• Audit trails of deletions MUST be maintained

14. Conformance Testing

14.1 Validator Requirements

A conforming AIV validator MUST be able to verify:

14.2 Validation Output Schema

A conforming validator MUST produce machine-readable output:

validation_result:
  # Identification
  validator_id: string # Validator name and version
  packet_id: string # Packet being validated
  repository: string
  pr_id: integer
  head_sha: string
  validated_at: ISO-8601

  # Results
  overall_result: PASS | FAIL
  compliance_level: L1 | L2 | L3 | NON-COMPLIANT
  risk_tier_validated: R0 | R1 | R2 | R3

  # Detailed results
  evidence_class_results:
    - class: A | B | C | D | E | F
      required: boolean
      present: boolean
      valid: boolean
      findings: [Finding]

  validation_rule_results:
    - rule_id: string
      result: PASS | FAIL | SKIP
      finding_id: string # If FAIL

  # Findings
  findings:
    - id: string
      severity: BLOCK | WARN | INFO
      rule_id: string
      description: string
      remediation: string

  # Summary
  block_count: integer
  warn_count: integer
  info_count: integer

14.3 Conformance Claim Requirements

An organization MAY claim AIV conformance when:

Conformance claim format:

"[Organization] claims AIV v1.0.0 conformance at Level [L1/L2/L3] for [scope description], validated as of [date], with audit evidence available at [reference]."

15. Governance and Versioning

15.1 Organizational Policy Requirements

Organizations implementing AIV MUST document:

15.2 Specification Versioning

AIV specification versions follow Semantic Versioning (SemVer):

• MAJOR: Breaking changes to packet schema or evidence class definitions
• MINOR: New optional features, new profiles, clarifications
• PATCH: Bug fixes, typo corrections, non-normative clarifications

15.3 Backward Compatibility

15.4 Deprecation Policy

• Deprecated features MUST be announced at least one minor version before removal
• Deprecated features MUST include migration guidance
• Removed features MUST increment major version

Appendix A — Auditor Checklist

A.1 Per-Change Verification Checklist

A.2 Program-Level Audit Checklist

Appendix B — Packet Schema

B.1 Complete Packet Schema

# AIV Packet Schema v1.0.0
# This schema is normative. Packets MUST conform to this structure.

aiv_version: "1.0.0" # REQUIRED - AIV spec version
packet_schema_version: "1.0.0" # REQUIRED - This schema version

# ============================================================================
# IDENTIFICATION
# ============================================================================
identification:
  repository: string # REQUIRED - Canonical repo identifier (e.g., "github.com/org/repo")
  pr_id: integer # REQUIRED - PR/MR number
  pr_url: string # REQUIRED - PR URL as identifier (NOTE: PR content is mutable; evidence artifacts must be immutable per §3.3)
  branch: string # REQUIRED - Source branch name
  base_branch: string # REQUIRED - Target branch name
  head_sha: string # REQUIRED - HEAD commit SHA (40 or 64 hex chars) - THIS is the immutable anchor
  base_sha: string # REQUIRED - Base commit SHA
  created_at: ISO-8601 # REQUIRED - Packet creation timestamp
  created_by: string # REQUIRED - Identity creating packet

# ============================================================================
# CLASSIFICATION (§5)
# ============================================================================
classification:
  risk_tier: R0 | R1 | R2 | R3 # REQUIRED
  sod_mode: S0 | S1 # REQUIRED
  critical_surfaces: # REQUIRED if R3
    - string # List of critical surfaces touched
  blast_radius: local | component | service | cross-service | organization # REQUIRED
  classification_rationale: string # REQUIRED - Explanation of tier assignment
  classified_by: string # REQUIRED - Identity performing classification
  classified_at: ISO-8601 # REQUIRED

# ============================================================================
# CLAIMS
# ============================================================================
claims:
  - id: string # REQUIRED - Stable unique identifier (e.g., "CLM-001")
    type: # REQUIRED - At least one type
      - functional | structural | dependency | interface | security | performance | operational
    statement: string # REQUIRED - Testable assertion
    risk_surfaces: # REQUIRED if security-relevant
      - string # auth | payments | secrets | crypto | pii | data_integrity | api | privilege
    scope:
      files: [string] # Files this claim applies to
      functions: [string] # Functions/methods this claim applies to
    evidence_refs: [string] # REQUIRED - Evidence item IDs supporting this claim

# ============================================================================
# EVIDENCE (§6)
# ============================================================================
evidence_items:
  - id: string # REQUIRED - Unique identifier (e.g., "EV-A-001")
    class: A | B | C | D | E | F # REQUIRED - Evidence class
    description: string # REQUIRED - Human-readable description
    claim_refs: [string] # REQUIRED - Claim IDs this evidence supports

    artifacts: # REQUIRED - At least one artifact
      - type: string # REQUIRED - ci_run | permalink | search_output | diff | attestation | coverage | sbom | etc.
        reference: string # REQUIRED - URL or content-addressed ID
        immutability_mechanism: string # REQUIRED - How immutability is achieved
        canonical_form: string # REQUIRED for R3 - How artifact was canonicalized for hashing (§6.8.1)
        sha256: string # REQUIRED for R3 - SHA-256 hash of canonical form
        retrieved_at: ISO-8601 # REQUIRED - When artifact was retrieved/created
        retention_verified: boolean # SHOULD - Has retention been confirmed

    scope: string # REQUIRED - What this evidence covers
    validation_method: string # REQUIRED - How to verify this evidence
    limitations: [string] # Any known limitations

# ============================================================================
# VERIFICATION (§7)
# ============================================================================
attestations:
  - id: string # REQUIRED - Unique attestation ID
    verifier_id: string # REQUIRED - Verifier identity
    verifier_identity_type: string # REQUIRED - github | email | oidc | corporate_sso
    decision: COMPLIANT | CONDITIONAL | NON-COMPLIANT # REQUIRED
    timestamp: ISO-8601 # REQUIRED

    evidence_classes_validated: # REQUIRED
      - A | B | C | D | E | F
    validation_rules_checked: [string] # REQUIRED - Rule IDs validated

    findings: # REQUIRED - May be empty array
      - id: string
        severity: BLOCK | WARN | INFO
        rule_id: string
        description: string
        remediation: string

    # For CONDITIONAL decisions
    conditions: # REQUIRED if decision is CONDITIONAL
      - finding_id: string
        remediation_plan: string
        remediation_deadline: ISO-8601
        responsible_party: string

    # For NON-COMPLIANT decisions
    blocking_findings: [string] # REQUIRED if decision is NON-COMPLIANT
    rationale: string # REQUIRED if decision is NON-COMPLIANT

    # Cryptographic binding
    signature_method: GPG | OIDC | sigstore | unsigned # REQUIRED
    signature: string # REQUIRED if not unsigned
    signed_fields: [string] # REQUIRED if not unsigned

# ============================================================================
# KNOWN LIMITATIONS (§7.5)
# ============================================================================
known_limitations: # REQUIRED - MUST NOT be empty
  - string # Each limitation as a string
    # If none: ["No limitations identified. Full evidence coverage achieved for declared scope."]

# ============================================================================
# EXCEPTION (§10) - Only if exception invoked
# ============================================================================
exception:
  invoked: boolean # REQUIRED - true if exception active

  # Justification
  incident_reference: string # REQUIRED if invoked
  harm_description: string # REQUIRED if invoked
  harm_severity: string # REQUIRED if invoked

  # Approval
  approver_id: string # REQUIRED if invoked
  approver_role: string # REQUIRED if invoked
  approval_timestamp: ISO-8601 # REQUIRED if invoked
  approval_method: string # REQUIRED if invoked

  # Scope
  evidence_classes_waived: [A, B, C, D, E, F] # REQUIRED if invoked
  validation_rules_waived: [string] # REQUIRED if invoked

  # Time bounds
  exception_start: ISO-8601 # REQUIRED if invoked
  validity_window_hours: integer # REQUIRED if invoked (max 72)
  exception_expires: ISO-8601 # REQUIRED if invoked

  # Follow-up
  follow_up_obligation: string # REQUIRED if invoked
  follow_up_deadline: ISO-8601 # REQUIRED if invoked
  follow_up_owner: string # REQUIRED if invoked

  # Resolution
  resolution_status: pending | completed | reverted # Updated after resolution
  resolution_timestamp: ISO-8601
  resolution_evidence: string

# ============================================================================
# METADATA
# ============================================================================
metadata:
  generator: string # Tool that generated this packet
  generator_version: string
  generation_timestamp: ISO-8601
  packet_hash: string # SHA-256 of packet content (excluding this field)

B.2 Schema Hash

The canonical schema definition above has the following SHA-256 hash for verification:

Schema Version: 1.0.0
SHA-256: [To be computed on final publication]

Organizations MAY verify schema integrity by computing SHA-256 of the schema YAML above (excluding this B.2 section).

Appendix C — Validation Rules

C.1 Complete Rule Index

C.2 Finding Index

Appendix D — Finding Severity Taxonomy

D.1 Severity Definitions

D.2 Finding Rate Calculation

The finding rate for conformance metrics is calculated as:

finding_rate = (changes_with_BLOCK_or_WARN_findings / total_changes_audited) × 100

Where:

• changes_with_BLOCK_or_WARN_findings = count of audited changes with at least one BLOCK or WARN finding
• total_changes_audited = count of changes in audit sample
• INFO findings are excluded from rate calculation

D.3 Threshold Definitions

Appendix E — Immutability Mechanisms

E.1 Acceptable Mechanisms

This appendix provides implementation guidance for achieving artifact immutability per §3.3.

E.1.1 Git Commit SHA Binding

Mechanism: Reference artifacts by commit SHA, not branch name.

Implementation:

# NOT ACCEPTABLE (mutable)
https://github.com/org/repo/blob/main/src/file.py

# ACCEPTABLE (immutable)
https://github.com/org/repo/blob/abc123def456.../src/file.py#L10-L20

Verification: Git commit SHAs are cryptographically bound to content; modification changes the SHA.

Limitations: Does not prevent repository deletion; requires retention policy.

E.1.2 Content-Addressed Storage

Mechanism: Store artifacts in content-addressed storage where the identifier is derived from content hash.

Implementation:

# OCI Registry with digest
registry.example.com/artifacts@sha256:abc123...

# IPFS
ipfs://QmXyz...

# Git LFS with SHA
git-lfs://sha256:abc123...

Verification: Retrieve artifact, compute hash, compare to identifier.

Limitations: Requires access to storage system; does not prevent deletion without retention policy.

E.1.3 Signed Attestations

Mechanism: Cryptographically sign artifact with key controlled by trusted party.

Implementation:

# Sigstore (Cosign)
cosign verify --key cosign.pub artifact.tar.gz

# GPG
gpg --verify artifact.tar.gz.sig artifact.tar.gz

# In-toto
in-toto-verify --layout layout.json --layout-keys key.pub

Verification: Verify signature against trusted public key.

Limitations: Requires key management; signature proves creation, not prevention of deletion.

E.1.4 WORM Storage

Mechanism: Store artifacts in Write-Once-Read-Many storage with retention lock.

Implementation:

# AWS S3 Object Lock
aws s3api put-object-retention --bucket artifacts --key evidence/packet.json \
  --retention '{"Mode":"GOVERNANCE","RetainUntilDate":"2028-01-01"}'

# Azure Immutable Blob
az storage blob immutability-policy set --container artifacts --name packet.json \
  --expiry-time 2028-01-01 --policy-mode Locked

Verification: Storage policy prevents modification; audit logs show no changes.

Limitations: Requires cloud provider; retention must exceed AIV retention requirement.

E.1.5 Hash Manifest

Mechanism: Record SHA-256 hash in packet; store artifact separately.

Implementation:

artifacts:
  - reference: "https://ci.example.com/jobs/12345/artifacts/report.html"
    sha256: "abc123def456..."

Verification: Retrieve artifact, compute SHA-256, compare to recorded hash.

Limitations: Does not prevent artifact deletion; requires artifact to remain available.

E.2 Immutability Verification Checklist

E.3 Requirement Reference Immutability

For Class E (Intent Evidence), requirement references require special handling because most issue trackers are mutable by default.

E.3.1 Acceptable Approaches

E.3.2 NOT Acceptable

Appendix F — Profiles and Extensions

F.1 Profile Framework

AIV MAY be extended via Profiles that provide language-specific, framework-specific, or industry-specific guidance.

F.1.1 Profile Constraints

Profiles MUST NOT:

• Redefine Evidence Classes A–G
• Reduce minimum requirements for any tier
• Remove required fields from packet schema
• Weaken validation rules
• Make Class G required for L1/L2 (only AIV-Regulated profile may require Class G universally)

Profiles MAY:

• Add sub-requirements to evidence classes
• Specify recommended tools for evidence generation
• Define language-specific test integrity checks
• Add additional evidence artifacts
• Define industry-specific critical surfaces
• Extend Class G with domain-specific requirements (see F.3)

F.1.2 Profile Structure

profile:
  id: string # e.g., "AIV-Python"
  name: string
  version: string
  aiv_version_compatibility: string # e.g., ">=1.0.0"
  scope: string # What this profile applies to

  # Additional requirements
  evidence_class_extensions:
    A:
      additional_artifacts: []
      recommended_tools: []
    C:
      test_integrity_tools: []
      patterns: []

  # Additional critical surfaces
  critical_surfaces: []

  # Tool recommendations
  tooling:
    ci_integration: []
    static_analysis: []
    coverage: []

F.2 Registered Profiles

F.3 Class G — Cognitive Evidence Profiles

Status: Class G is now defined in the main specification (§6.8). This appendix describes Profile extensions for Class G.

Class G is optional for all compliance levels (L1–L3). Profiles MAY extend Class G with language-specific or industry-specific cognitive verification requirements.

F.3.1 Profile Extensions for Class G

Profiles extending Class G MAY specify:

F.3.2 Class G Applicability by Profile

F.3.3 Future Enhancements (Planned for v1.1+)

• Verifier scoring / ELO ratings based on audit sampling
• Cognitive artifact quality metrics
• Automated coherence checking for mental traces
• Cross-change cognitive continuity tracking

Organizations requiring enhanced cognitive verification assurance SHOULD implement §6.8 and monitor profile development.

F.4 Extension: R4 — Regulated Tier (Preview)

Status: Planned for AIV-Regulated Profile

R4 extends AIV for environments subject to regulatory compliance (SOX, HIPAA, PCI-DSS, etc.).

F.4.1 Proposed R4 Requirements

Document History

Acknowledgments

This standard incorporates concepts and aligns with practices from:

• SLSA (Supply-chain Levels for Software Artifacts)
• SOC 2 Trust Services Criteria
• NIST Secure Software Development Framework (SSDF)
• OpenSSF Security Scorecards
• ISO/IEC 27001:2022

Contact

For questions, feedback, or contributions to this specification:

• Specification Repository: [To be established]
• Issue Tracker: [To be established]
• Mailing List: [To be established]

End of AIV Canonical Specification v1.0.0