dispatch-validate

name	dispatch-validate
description	Validate a dispatch contract YAML against ADR-017 §2.2 canonical packet shape + P4 structural + P3 role-canonical + P1 reference resolution; emit conformance diagnostic for pre-launch gating.

Dispatch validate

When to invoke

BEFORE launching any Implementer/Validator/Observer/etc. dispatch. The dispatch contract must conform to the canonical AGENTS.md template + ADR-017 §2.2 role-typing extensions; reference citations must resolve; the role must be canonical (Directive #10 + working-vocabulary registry + tier-overlay-only roles).

What it does

Invokes tools/dispatch-validate.sh to run the P4 + P3 + P1 composition adapter on a contract YAML and emit a JSON diagnostic with conforms + violations + warnings. Exits 0 on conforms (block-severity violations absent); exits 1 on non-conformance (block-severity violations present).

Per ADR-017 §2.4 severity ladder + amnesia-o4fp.1 Task 3.1 Q4 disposition (Option B):

• block-severity violation → conforms:false + exit 1
• warn-severity violation → conforms:true + warnings[] non-empty + exit 0

Composition is Cerberus-aggregate (P4 → P3 → P1 in sequence; no halt-on-first; full diagnostic in a single pass).

Contract with primitive

• Primitive: tools/dispatch-validate.sh
• Flags / inputs:
  • --contract <path> (required; YAML contract path)
  • --json (machine-readable output; default behavior)
  • --pretty (pretty-printed JSON; indent=2)
  • -h / --help (usage)
• Output shape:

  {
    "conforms": true,
    "contract_path": "<input>",
    "dispatch_packet_diagnostic": {
      "valid": true,
      "missing_fields": [],
      "drift": [],
      "role_template_extension": {}
    },
    "role_identity": {"name": "Implementer", "tier": "T2", "canonical_in": "working_vocabulary"},
    "resolved_references": [
      {"kind": "bd_id", "target": "amnesia-o4fp.1", "status": "RESOLVED"}
    ],
    "violations": [],
    "warnings": []
  }
  

• Exit semantics: 0 = conforms (no block-severity violations); 1 = does-not-conform; 2 = invocation error (missing or unknown argument).

Example invocation

tools/dispatch-validate.sh --contract /tmp/my-dispatch-contract.yaml --json
tools/dispatch-validate.sh --contract /tmp/my-dispatch-contract.yaml --pretty

Halt conditions

• halt-contract-yaml-malformed (block; tool-local per Task 3.1 DO Q5): contract YAML parse failure or file not readable.
• halt-anchor-resolution-failure (block): P1 file_path / adr_anchor / memory_binding / commit_sha NOT_FOUND, or P4 structural field missing.
• halt-role-not-canonical (block): P3 role not in DIRECTIVE_10 / WORKING_VOCABULARY / TIER_OVERLAY_ONLY rosters.
• halt-bd-id-stale (warn): P1 bd_id resolves to a CLOSED bd issue; advisory.
• halt-memory-binding-active-pending-codification (warn): P1 memory_binding has ACTIVE_PENDING_CODIFICATION status (per ADR-017 §7.3 R3 trait posture); advisory.

Related

• ADR-017 §2.1 (Layer 3 Invocation pattern; bash + Python subprocess).
• ADR-017 §2.2 (canonical packet shape; CANONICAL_FIELDS + ROLE_TYPING_FIELDS).
• ADR-017 §2.4 (canonical halt-class taxonomy; severity ladder).
• tools/role_schema/cli.py:dispatch_validate (Python implementation; this skill's underlying mechanism).
• Sibling primitives (Phase 3, planned): tools/halt-arm.sh (post-validate; pre-launch arming), tools/assemble-role.sh (role-identity assembly), tools/validate-refs.sh (full 5-class ref service).