For engineers
Proof you can act on
Clear obligations, actionable HELD reasons, an exact-build decision and preserved history, in your pipeline, your terminal and your coding agent.
What you get
Know what stands between your commit and CLEARED.
Bring every verifier you already use. The Warden decides whether their combined proof is enough.
Clear obligations
The default contract is explicit: a complete, current-build automated test run, no older than 24 hours, with no failed, error or skipped observation. You know what must be proven before you push.
Actionable HELD reasons
A hold carries a fixed reason code and a next action. For a failing JUnit report it names up to 10 failing tests in report order, so you do not open CI logs to find the cause.
An exact-build decision
Every decision applies to one repository, commit, build and environment. Evidence for an older build is kept as history and can never clear the current one.
Preserved history
Decisions are append-only. Fixing a failure produces a new decision for the new build; the earlier HELD decision stays on the record.
Exit-code behavior
HELD stops the pipeline. CLEARED lets it through.
The gate exits zero only when the decision is a structurally valid CLEARED that matches the exact repository, commit, build and environment you submitted. Everything else exits 1.
Marketplace V1 — publicly listed
$ node scripts/warden-gate.mjs --file test-results/junit.xml --format junit The Warden: HELD resolve_failing_evidence $ echo $? 1
$ node scripts/warden-gate.mjs --file test-results/junit.xml --format junit The Warden: CLEARED $ echo $? 0
A HELD response
This is the shape of --json output for a failing test run on the fictional repository acme/checkout-service, formatted for reading. The reason code says what failed, the next action says what to do, the obligation points at the receipt, and the response is tied to the exact build. Download it: held-response.json.
{
"schemaVersion": 1,
"state": "HELD",
"progressionAllowed": false,
"changeSetId": "00000000-0000-4000-8000-00000000c0de",
"qualityDecisionId": "00000000-0000-4000-8000-00000000d0c1",
"reasonCodes": ["evidence_failed"],
"nextActions": ["resolve_failing_evidence"],
"obligations": {
"schemaVersion": 1,
"items": [
{
"kind": "Failed",
"itemId": "illustrative-contract-item-1",
"evidenceRef": "illustrative-receipt-0001",
"reasonCodes": ["evidence_failed"],
"approvalRole": null
}
],
"observedCount": 1,
"truncated": false
},
"verification": {
"contractVersion": 1,
"policyVersion": 1,
"policyEngineVersion": 1,
"evidenceCount": 2,
"blockingFailureCount": 1,
"missingProofCount": 0,
"conflictCount": 0,
"staleEvidenceCount": 0,
"requiredApprovalCount": 0
},
"submission": {
"transport": "rest",
"targetBinding": "response-checked",
"repositoryRef": "acme/checkout-service",
"commitSha": "3f9a1c7e5b2d4a6081f3c9e7d5b1a3c2e4f60718",
"buildRef": "build-20261018-0002",
"environmentRef": "development",
"providerRunId": "run-20261018-0002",
"envelopeSha256": "0000000000000000000000000000000000000000000000000000000000000000"
}
}Fix the test and let CI submit evidence for the new build. A new decision is recorded and the HELD decision is never rewritten. All codes are listed in Decisions and approvals.
CI evidence
Send the report you already produce.
JUnit XML for the test run, SARIF 2.1.0 for scans, or a bounded JSON envelope of 1 to 20 observations. Each submission names the exact repository, commit, build and environment.
Marketplace V1 — publicly listed
Compatible reports
Playwright and Cypress write JUnit XML. Semgrep writes SARIF. Any tool that emits those formats works. These are compatible reports, not first-party vendor integrations, and a tool's own green result is evidence, never CLEARED. Test-management connectors are covered on Integrations.
Gate on the build
The gate retries only transient failures, never relabels older results as a new build, and fails closed when the response is unknown or malformed. A CI run announcement shows VERIFYING while evidence is on its way.
Commands, environment variables, limits and troubleshooting: Submit CI evidence.
API, CLI and MCP
Ask The Warden about the commit you are on.
One authenticated Developer API serves a PowerShell client and an MCP server. Repository and commit are inferred from your Git workspace, so there are no change IDs to copy.
Developer preview — live acceptance pending
Read-only operations
- warden.statusGET /developer/v1/status
- verification.obligationsGET /developer/v1/obligations
- verification.plan.getGET /developer/v1/plan
- evidence.listGET /developer/v1/evidence
- quality.explainGET /developer/v1/explain
All five read with the custom scope read:warden-developer:custom as the signed-in Jira user, with a current role of tester or higher and a repository grant. quality.explain is deterministic and quiet when the change is CLEARED.
.\scripts\testwarden.ps1 status .\scripts\testwarden.ps1 obligations .\scripts\testwarden.ps1 explain .\scripts\testwarden.ps1 explain -Format json
The MCP server exposes the same operations as typed tools for VS Code, Claude Code, Codex and other MCP clients. It has no shell, SQL, clearance or approval tool, and tokens reach it only through the launcher environment. Download mcp-config.json.
Setup and errors: API, CLI and MCP. Developer preview, live acceptance pending. Access is arranged during pilot onboarding:request it.
GitHub workflow
HELD feedback where the pull request lives.
A reusable composite action wraps the gate. It derives repository, commit, run, attempt and branch from GitHub, writes a job summary listing the obligations to resolve, and keeps one sticky pull-request comment current.
Developer preview — live acceptance pending
- name: Submit evidence to The Warden
uses: ./.github/actions/warden-verify
with:
endpoint: ${{ vars.WARDEN_ENDPOINT }}
environment: development
evidence-file: test-results/junit.xml
format: junit
access-token: ${{ secrets.WARDEN_TOKEN }}You supply the endpoint, the target environment, the evidence file and its format. The job fails unless the Warden decision is CLEARED for that exact build.
An optional exact-commit check run is available with check-run: true and the checks: write permission.
Download the full workflow: github-workflow.yml.
Governed AI explanation
Policy decides. AI can only help explain.
Deterministic policy owns clearance. An optional AI explanation can describe a HELD change in plain language and can never set, change or override a decision.
Developer preview — live acceptance pending
Optional and off by default
A site administrator enables AI. Nothing is sent to a model before then.
Consented and budget-capped
Consent is required and a spending cap stops requests at the limit.
Validated and fail-closed
Output must be one JSON object with citations that match real references. Anything else shows no AI text.
Facts without AI
With AI off, status, obligations and the explanation still render deterministically from recorded evidence.
The Marketplace V1 listing has no AI and declares no external egress. Details in AI and data handling.
Quality Memory history
Every decision, kept.
Quality Memory is your own immutable record: evidence receipts with content digests, decisions with their contract and policy versions, and the reasons for each. It is history you can read. It is not trained on and not pooled across customers.
A failing build, the fix and the new clearance sit side by side in the decision history of the change. Re-running only an old gate resubmits that attempt unchanged, so it cannot relabel older results as a fresh build.
Agent boundaries
Agents can read, submit and propose. They cannot clear.
Coding agents and the planned Quality Agent work inside the same authority model as every other producer.
Authorized reads
An agent reads obligations, evidence and decisions through the Developer API or MCP as a signed-in Jira user, subject to that user’s role and repository grant.
Evidence, not authority
An agent can submit evidence as an agent producer. It cannot satisfy the CI-run requirement, and no endpoint accepts a caller-selected state or approval.
No CI credentials
Only CI holds the credentials that announce a run or submit CI evidence. Agents are never given them.
Fresh proof after a repair
A repaired change gets a new decision for the new build. It needs fresh independent evidence, and the earlier HELD decision stays on record.
The Quality Agent is in development: it is designed to investigate quality problems and recommend maintenance or repairs only in workflows an administrator has explicitly authorized, and it never certifies its own work.
Not yet available
What is out of scope today.
- Approved rerun dispatch from the client or MCP. No dispatcher is installed yet.
- Repair adapters and autonomous repair, and customer-authored contracts.
- Live connectors for AIO Tests, Xray, Zephyr Scale, TestRail and Azure DevOps. Read-only collectors are in source and under acceptance; see Integrations.