Documentation · Task
Decisions and approvals
Read a decision, act on its reasons and next actions, and understand what is preserved when a new build arrives.
What a decision applies to
Marketplace V1 — publicly listed
A decision belongs to a Change Set, identified by repositoryRef, commitSha, buildRef and environmentRef. It says whether the proof for that exact build is enough. It is not a statement about the branch or the repository in general.
Deterministic policy owns clearance. An external tool's green status, approval or score is evidence; it is never CLEARED. AI can assist an explanation but cannot set or override a decision.
The five states
| State | Meaning | Gate exit |
|---|---|---|
| CLEARED | Required proof is satisfied under policy for this exact build. | 0 |
| CI announced a run for this build and its evidence is still within the allowed window (default 60 minutes). An announcement is never evidence. | 1 | |
| HELD | A deterministic blocking condition exists, such as failing evidence, stale or missing proof, conflicting results, a blocking defect or an overdue run. | 1 |
| NEEDS APPROVAL | The applicable contract requires a human approval. | 1 |
| INCOMPLETE | TestWarden cannot evaluate the change honestly: context, contract, policy or evidence is missing, malformed or too large. | 1 |
The API spells the fourth state NEEDS_APPROVAL. progressionAllowed is true only for CLEARED.
The default contract
- A complete, current-build automated test run, with evidence no older than 24 hours.
- Any failed, error or skipped observation prevents a pass. A skipped test holds the build.
- Scanner and reviewer passes are recorded but cannot satisfy the test obligation. Agent evidence cannot satisfy the CI-run requirement.
- Evidence producers are identified by provider type, name, source system and run ID. Only CI holds tokens.
Customer-authored contracts are not available. Every installation uses the default contract (currently labelled Contract v1 and Policy v1 in decisions).
Reason codes
Reason codes are fixed. A decision lists the ones that apply.
| Code | Meaning |
|---|---|
evidence_satisfied | Required proof is present and passing. |
evidence_failed | A required observation failed. For JUnit the receipt names up to 10 failing tests in report order. |
only_stale_evidence | Matching evidence exists but is older than the 24-hour window. |
no_matching_evidence | No evidence matches the contract for this exact build. |
conflicting_evidence | Passing and failing results contradict each other for the build. |
open_blocking_defect | A recorded blocking defect is open. |
missing_required_approval | The contract requires a human approval that has not been recorded. |
verification_run_in_progress | An announced run is still inside its window. |
verification_run_overdue | The announced run did not deliver evidence in time. |
no_conclusive_evidence | Matching evidence exists but proves nothing either way, for example only skipped tests. |
no_active_contract, authoritative_defect_context_unavailable, evidence_set_truncated | The Warden has no active contract, authoritative defect context or complete evidence set to evaluate against, so it does not guess. |
Next actions
Each hold names an action you can take. Examples you will see in gate output, the Developer API and the GitHub summary:
| Next action | What to do |
|---|---|
resolve_failing_evidence, fix_failing_tests_and_resubmit_fresh_evidence | Fix the failing test and let CI submit fresh evidence for the new build. |
resolve_conflicting_evidence | Resolve contradictory results for this commit and verify again. |
resubmit_fresh_evidence_for_this_build | Re-run the required tests for this exact commit, build and environment. |
produce_required_evidence, submit_required_evidence | Run the verification the active contract requires. |
resolve_blocking_defect | Resolve the defect and submit fresh independent CI proof. |
await_verification_run | Wait for the current run to finish. It is not cleared. |
investigate_overdue_verification_run | Find out why the announced run never delivered evidence, then re-run CI. |
request_human_approval_in_jira, obtain_required_approval | An authorized human must approve. Automation and AI cannot. |
rerun_trusted_verification | Restore trusted CI authentication and re-run the exact commit. |
See a full HELD response with its reason and next action in held-response.json.
History and new builds
- Decisions are append-only. A HELD decision is never rewritten, even after a fix.
- Fresh passing evidence for a new build produces a new decision. The decision history shows the hold, the failure and the new clearance side by side.
- The verification target only moves forward. Evidence for an older build is kept as history and answered
submissionSuperseded; it never clears the change. - Exact retries are idempotent. Changed or conflicting evidence is stored as a new receipt, never overwritten.
- History, receipts and decisions are per installation. There is no cross-customer pooling.
Approvals
An approval is a recorded, scope-bound decision by an authorized human. The default contract requires none, and the current product has no customer-facing way to author a contract that does or to grant one, so you will not normally see NEEDS APPROVAL.
state or progressionAllowed field. Submissions that include them are rejected.Where to read a decision
- In Jira: open Changes, then the change. See The Warden and quality decisions.
- In CI: the gate output, see Submit CI evidence.
- In a terminal or agent: API, CLI and MCP.
- Roles and scopes: Permissions.
Related tasks
- Onboarding
Choose a path, enable access, confirm the first change appears.
- CI evidence
Submit JUnit, SARIF or JSON and gate on the exact build.
- API, CLI and MCP
Read status, obligations and explanations from a terminal or agent.
- Permissions
Roles, custom scopes and who can read, write or request.
- AI and data handling
What is optional, what is consented and what never changes a decision.