ArchitectureAdrADR-0014: Validation and Evidence Automation

ADR-0014: Validation and Evidence Automation

ADR-0014: Validation and Evidence Automation

Status: PROPOSED
Date: 2026-01-10
Author: Codex (Gatekeeper)
Related: docs/agent_ops/INBOX_PROTOCOL.md, docs/agent_ops/SCHEMA_VERSIONING.md

Context

The current multi-agent workflow relies on manual checks for INBOX message structure and OUTBOX evidence quality. This creates drift risk (missing fields, inconsistent status) and slows reviews. We need a minimal, automation-friendly layer that:

  • validates INBOX message structure,
  • enforces basic OUTBOX hygiene,
  • remains lightweight and easy to update.

Options

  1. Minimal scripts + schema (recommended)

    • Add a simple schema file for INBOX messages.
    • Add a validation script that checks required fields and evidence hygiene.
    • Optionally wire the script into CI later.

  2. Full schema validation in CI

    • Define JSON Schema/YAML schema files for all coordination artifacts.
    • Validate with a schema engine in CI on every PR.
    • Higher rigor, but adds runtime dependencies.

  3. Workflow engine (e.g., Conductor/Temporal)

    • Move coordination to an orchestration layer.
    • Highest automation, but highest ops overhead.

Decision

Adopt Option 1: minimal schema + validation script.

  • Create docs/agent_ops/schemas/inbox_message.schema.yaml (v1.1.0).
  • Add scripts/validate-inbox-outbox.sh for lightweight checks.
  • Keep validation opt-in (STRICT mode) until existing evidence is cleaned.

Consequences

Pros

  • Low overhead, fast rollout.
  • Improves consistency without blocking work.
  • CI-ready when STRICT mode is enabled.

Cons

  • Not full schema validation.
  • Some hygiene checks remain manual.

Follow-ups

  • Add a schema registry entry for inbox_message once SCHEMA_VERSIONING is accepted.
  • Decide when to enable STRICT mode in CI.