Skip to content

Agent release protocol

This protocol supplements docs/release.md. It converts the maintainer's release expectations into auditable gates for a named version and frozen commit.

Evidence vocabulary

Every check has one status:

  • PASS: executed successfully against the frozen commit and required environment;
  • FAIL: executed and did not satisfy acceptance criteria;
  • SKIP: required but not executed; include reason and owner;
  • N/A: not applicable to the release scope; include rationale;
  • UNVERIFIED: evidence is stale, incomplete, inaccessible, or not attributable to the frozen commit.

SKIP, mocked success, and stale evidence are never PASS.

For each item record command/workflow, commit, environment, timestamp, observed result, artifact path, owner, and blocking decision.

R1 — CLI correctness and UX

Build the command/option inventory from the executable CLI and generated reference. Do not attempt an unbounded Cartesian product. Use:

  1. equivalence classes for values and modes;
  2. boundary values;
  3. negative and mutually exclusive combinations;
  4. pairwise coverage for interacting options;
  5. exhaustive coverage only for small, high-risk groups.

Verify help/version/import without optional SDKs, exit codes, stdout/stderr, JSON and file output, encoding, atomicity/overwrite policy, non-TTY behavior, invalid configuration, actionable errors, and no durable side effect before validation succeeds.

R2 — run CLI/Python parity

For representative manifests compare semantic behavior, not decorative output:

  • normalized manifest and execution plan;
  • selected source, sink, strategy, and capabilities;
  • identities, counts, state/checkpoint changes, and evidence;
  • dry-run side effects;
  • error classification and recovery guidance.

R3 — hierarchical identity and nested normalization

Verify deterministic root/row/parent identity, lineage at every depth, naming and collision rules, missing/null/empty object/empty array semantics, arrays of objects/primitives, deep nesting, type fidelity, schema evolution, retry/replay stability, and absence of orphaned children.

R4 — source-to-sink × strategy matrix

Generate the matrix from authoritative capability metadata. Every cell is supported, unsupported with reason, experimental, or certification-required.

For supported scope verify capability negotiation, type/schema mapping, row counts or reconciliation, strategy semantics, checkpoint/evidence ordering, retry/resume, quarantine/recovery, and understandable artifacts. Separate mocked contract evidence from live route certification.

R5 — contracts and guardrails

Run import, architecture, module-size, graph, compatibility, schema, state, evidence, security, and fail-closed checks. Confirm no gate or threshold was weakened to make the release pass.

R6 — documentation and CJM

Run strict docs checks, validate YAML/examples/links, compare CLI and schema reference to executable behavior, update architecture and diagrams, and walk the first-time-user journey. Decompose monolithic pages when audience/task boundaries justify it; do not split mechanically.

R7 — Airflow and dbt

Verify supported version ranges, import/parse behavior, serialization/templating, configuration and secret handling, retries/cancellation/logs/artifacts, upgrade compatibility, first-run UX, and documented production deployment. Use relevant current official Airflow, dbt, Astronomer Cosmos, and gusty behavior as research inputs, not as unsupported marketing claims.

R8 — packaging, dependency, security, and supply chain

Verify clean builds, metadata, wheels/sdists, fresh-environment installs, base and extras, optional import isolation, dependency review, secret scanning, SBOM and provenance/evidence, and public resolver visibility according to docs/release.md. For a public release, retain the canonical annotated-tag report and live required-check report for the exact commit. Compare the complete four-package candidate wheel/sdist inventory with PyPI by filename and SHA-256. For the runtime image, retain the GHCR digest, pull and smoke by digest, verify the installed dpone version and pip check, and retain package inventories, SPDX SBOM, provenance, and SBOM attestations. A visible version or mutable image tag without byte identity is UNVERIFIED, not PASS.

The exact-commit evidence is produced by tools/agent_policy/release_identity_gate.py and tools/agent_policy/release_commit_gate.py. The first binds the annotated tag, four package versions, exact internal dependency pins, changelog and protected base ancestry. The protected base is always origin/<branch> from the frozen branch-protection policy (never a caller-selected HEAD); evidence records protected_base_sha and policy_sha256. It reads package, changelog, and policy bytes directly from the frozen commit and never falls back to the worktree. The second reads .agents/policy/github-branch-protection.yml only via git show <commit>:<path>, binds policy_sha256 in its JSON report, queries the live ruleset plus check-runs for that full SHA, and validates the configured producer identity; legacy commit statuses are diagnostic only. Caller-selected policy bytes and worktree policy edits cannot influence the gate. Static policy files or a screenshot of green checks cannot replace either machine-readable report.

Before archive inspection, attestations, or upload, run the closed candidate inventory gate. It must prove exactly eight regular artifacts: one wheel and one .tar.gz sdist for each of the four public distributions, all at the requested version. Duplicate variants, .zip, unrelated files, directories, and symlinks are blockers. Keep the deterministic JSON inventory with filenames and SHA-256 digests as release evidence, then validate archive members, run bounded tenant hygiene on frozen source and exact archive bodies with the CI-owned TENANT_HYGIENE_POLICY secret, and run a fresh dpone[full,accel] install plus pip check.

Immediately before PyPI publication and again before creating the GitHub Release, recheck that the annotated tag object still peels to the release commit. A preflight-only tag check is not sufficient after a long build.

R9 — recovery, observability, and performance

Verify crash/retry/resume/replay, cancellation, state/evidence recovery, quarantine/repair, log/metric/lineage completeness, performance regressions, resource bounds, and documented operating limits for changed critical paths.

Existing executable checklist

After underlying evidence exists, produce the repository checklist described in docs/release.md:

uv run dpone ops pre-release-checklist \
  --release vX.Y.Z \
  --release-type minor \
  --check cli_help_surface=true \
  --check cli_output_contracts=true \
  --check run_cli_manifest=true \
  --check run_python_api_manifest=true \
  --check nested_hierarchical_identity=true \
  --check nested_parent_child_integrity=true \
  --check source_sink_strategy_matrix=true \
  --check source_sink_artifacts=true \
  --check docker_live_routes=true \
  --check contracts_guardrails=true \
  --check documentation_yaml_examples=true \
  --check documentation_links=true \
  --check documentation_mkdocs=true \
  --check ci_cd_quality=true \
  --check package=true \
  --output-dir test_artifacts/release/vX.Y.Z/pre-release \
  --format json

The booleans summarize previously gathered evidence; they are not permission to assert checks without executing them.

Release decision

  • Any blocking FAIL or required SKIP/UNVERIFIED means NO-GO.
  • N/A requires scope rationale.
  • GO names the exact commit and lists residual non-blocking risks.
  • A new commit invalidates the decision until affected gates are rerun.