Release Readiness

---
name: "release-readiness"
description: "Make a provider-neutral merge, release, deploy, or hold decision. Records Builder publish-learn CI merge-readiness in trust.bundle."
---

# Release Readiness

## Role

This is a Builder step skill.

Release Readiness turns confidence and published-change evidence into an explicit
`MERGE`, `RELEASE`, `DEPLOY`, `HOLD`, or `ROLLBACK_REQUIRED` decision. It does
not fix code, publish a change, or deploy without explicit authorization.

## Binding

| Context | Binding | Flow expectation |
| --- | --- | --- |
| Active Builder run | Parent `builder.build` projection at composed `builder.publish-learn` step `merge-ready-ci` | `ci-merge-readiness` |
| Standalone invocation | No Flow binding | No workflow mutation. |

For an active run, confirm the binding before making the Flow claim:

The steering hook injects the run state at session start and re-injects it whenever it changes; if a steering state block appears anywhere in your context and you have not recorded evidence or a critique since it appeared, it is current. Run `flow-agents workflow status --session-dir <session-dir> --json` only after such a write or when no steering state block appears in your context at all; the write itself refuses an unbound, stale, or wrong-step binding either way.

Public status reports the parent definition as `builder.build`. Only that parent
run at `merge-ready-ci`, whose Flow Definition composes the step from
`builder.publish-learn`, may publish `ci-merge-readiness`.

## Inputs

- The evidence-gate confidence report and acceptance evidence.
- Published-change state from `ChangeProvider` and repository scope from
  `RepositoryAdapter`.
- Check and review state from `CheckProvider`.
- Release and deployment capabilities from `ReleaseProvider` and `DeployProvider`.
- Risk, rollback, observability, ownership, and authorization information.
- Repo-local governance evidence when `.veritas/repo-map.json` is present. The
  stable input is the `software-readiness-verdict` claim in the trust bundle
  written by `veritas readiness`; do not inspect or reproduce Veritas policy
  evaluation inside Builder Kit.

No provider is assumed. A change record, check, release record, or deployment
record may be unavailable because the repository or provider does not offer it.
Record the capability and its impact rather than substituting provider-specific
terms or treating absence as success.

## Decision Work

1. Confirm the confidence report remains applicable to the proposed scope.
2. Reconcile current provider checks and review state with the revision covered
   by acceptance evidence. Stale or mismatched evidence is `NOT_VERIFIED`.
   A validated `CodexPullRequestReview` from the optional Builder Codex PR
   review action is a `CheckProvider` review observation for the exact published
   head. It is distinct from the pre-publication `review-work` critique and from
   deterministic verification. Confirm its repository, PR, base/head SHA, diff
   digest, reviewer runtime/model, coverage, findings, gaps, and integrity
   fields. A critical/high finding, or a medium finding whose validated
   `requires_change` field is true, records failed
   `ci-merge-readiness` evidence with `--route-reason implementation_defect`;
   an unavailable or incomplete required review records failed readiness with
   `--route-reason missing_evidence`. The artifact's own `not_verified` verdict
   remains visible even though the readiness expectation fails to select the
   declared route-back. A changed PR head makes the observation stale.
   When the repository has `.veritas/repo-map.json`, run the repository's
   installed Veritas engine for the same base/head revision (prefer
   `npx --no @kontourai/veritas readiness --check evidence
   --changed-from <base> --changed-to <head> --format json`; it refuses rather
   than fetching when Veritas is not installed, which is an unavailable verdict),
   follow its returned `reportArtifactPath`, and record the
   `software-readiness-verdict` claim plus that artifact reference in
   `release.json`. If the Veritas Governance Kit is active, its
   `veritas-governance.readiness-check` flow may supply the same claim as a
   gate-ready trust bundle. Never parse console prose or import Veritas runtime
   internals.
   During an explicitly recorded Observe/advisory rollout, a rejected or
   unavailable governance verdict is a visible residual risk and
   `NOT_VERIFIED` gap, not an automatic Builder `HOLD`. Once the repository has
   separately promoted Veritas governance to blocking enforcement, a missing,
   stale, or non-verified verdict is required evidence and therefore routes to
   `HOLD`.
   If committing or publishing the reviewed change makes the canonical critique
   or verification snapshot stale, record `NOT_VERIFIED` with route reason
   `missing_evidence`; `merge-ready-ci` routes back to `verify` so the exact
   committed head can be reviewed and verified before terminal delivery.
3. Evaluate change publication, release and deployment implications through the
   available providers. Before `RELEASE` or `DEPLOY`, require an owner, an
   executable rollback or recovery path, observable success and failure
   signals, and a bounded post-release or post-deploy verification plan.
4. Require explicit authorization for merge, release, deploy, or rollback.
   Readiness evidence and an available provider capability are not authority to
   perform the operation. After learning, publish terminal delivery on the same
   source branch, commit/push its delivery-only companions, and refresh provider
   required checks for that exact terminal head. A separately authorized configured
   `change.merge` provider may then run `flow-agents merge-change execute`; a
   provisional delivery and its earlier checks never authorize a merge. The
   merge operation fails closed if no required checks are returned or its
   completed-run, active-assignment, and terminal-companion bindings drift.
5. Use `HOLD` for unresolved required evidence, ownership, rollback,
   observability, post-operation verification, or authority. Use
   `NOT_VERIFIED` for evidence that cannot be collected; it cannot be promoted
   to a clean merge, release, or deploy decision without an explicit accepted gap.
   Use `ROLLBACK_REQUIRED` when observed outcomes cross the recorded rollback
   threshold.
6. On a matching active run, publish the resulting evidence through the public
   CLI:

```bash
flow-agents workflow evidence --session-dir <session-dir> \
  --expectation ci-merge-readiness \
  --status <pass|fail|not_verified> \
  [--route-reason <implementation_defect|missing_evidence>] \
  --summary "Release-readiness decision and residual risks are recorded." \
  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/release.json","summary":"Release-readiness decision, authorization, rollback, and observability state."}'
```

`--route-reason` is used only with `--status fail`. Do not route a clean or
advisory-only review, and do not let the reviewer invoke the repair itself. The
separate implementation actor follows the Flow-projected `next_action`, pushes
a new head, and requires a fresh provider review.

## Output

Record the decision as the `ci-merge-readiness` slice in `trust.bundle`. It
includes assessed scope, confidence evidence, provider capability and check
state, risks, rollback and observability plan, required authorization, and
unresolved `NOT_VERIFIED` gaps. For release or deployment decisions, also record
the owner, success/failure signals, rollback threshold, and post-operation
verification commands or observations.

When acceptance behavior is summarized, include a readable `Acceptance
Evidence` table:

| AC id | Status | Command/Test Evidence | Source Evidence | Gaps |
| --- | --- | --- | --- | --- |

The claim supports the next Builder step; it does not itself merge, release, or
deploy anything.