Start Here: From Guardrails to a Passport
What a guardrail, a gate item, a control, an exception, an evidence entry, a passport and a passport check each are, how they fit together, and one change followed from its first check to its deployment with what is recorded at every step.
The idea in one paragraph
When agents write the change, a green build is not enough to release on. You need to know what was checked, who decided each check, and which rules applied — and to be able to show it later. The Studio checks the work at two gates, writes down each check as it happens in a ledger that cannot be edited, and presents that ledger as a passport. When a release is approved the passport is frozen and signed, so that someone outside the Studio — an auditor, a customer, a deployment pipeline — can check it without taking your word for it.
A studio of one can do all of this alone. Nothing in this guide needs a second person or an organisation, except writing an organisation’s guardrail policy. Where two people can be required, it is a setting that is off until someone turns it on.
The pieces, and how they relate
| Piece | What it is | Where it lives |
|---|---|---|
| Gate | A checklist a work package must pass: the Definition of Ready before it is built, the Definition of Done before it completes. | The work package |
| Gate item | One line of a checklist. It names an agent reviewer, a human reviewer role, or both, and is approved only when every side it names has approved. | Work Package Checklists; then each work package |
| Guardrail policy | An organisation’s floor: items every linked studio must carry, rules a release must meet, and who may take an exception. A studio may tighten it and may never loosen it. Enterprise organisations. | Organisation → Guardrail Policies |
| Control | A requirement from a framework — ISO 27001 A.8.29, SOC 2 CC8.1, or one of your own — that a gate item is evidence for. | On the item, under Controls |
| Exception | A person taking responsibility for an item not being met: a waiver, or an override of the reviewer agents. It records who, why and until when; once it expires the item is unmet again. | The gate; the passport; the organisation’s register |
| Evidence entry | One line in a ledger: an assessment, a decision, an exception, a CI result, an approval, a deployment. Written by the server as the thing happens, never afterwards, and never edited. | The evidence ledger of a work package or a release |
| Passport | The ledger for one artefact, presented for a person to read: exceptions, policy, controls, gates, provenance, CI, and what it does not know. Assembled afresh each time you open it. | The Passport tab; the Release plan |
| Issued passport | The passport frozen at one moment and signed. Each issue is a numbered version and none is ever rewritten. | Listed with the live passport |
| Verifier | Whatever checks a signed passport: a small offline script, a public endpoint, or standard signing tools. It needs only the file and the published public keys. | Outside the Studio |
| Deploy token | A token for one repository that lets a pipeline read that repository’s release passports and report its deployments, and nothing else. | Repositories |
| Passport check | A job in a pipeline the Studio generates. It verifies the release’s signed passport before a deploy, and holds the deploy or warns, as the studio owner chose. | The workflow file in your repository |
Read from top to bottom, that is the order things happen in: rules, then checks, then a record of the checks, then a signed copy of the record, then something that refuses to act without it.
One change, start to finish
A team is adding a password-reset flow. Here is what happens, and what is on the record after each step.
| Step | What happens | What is recorded |
|---|---|---|
| 1. The work package is created | It takes its Definition of Ready and Done from the studio’s checklists. If the studio belongs to an organisation with an active guardrail policy, the organisation’s items come first, locked. | The policy version the package was created under. It keeps that version. |
| 2. The Ready gate | The reviewer agents assess each item; a person decides the items that need one, and gives the gate a Go. | One entry per assessment and per decision, each with what it was based on. |
| 3. An item cannot be met | The threat model is not finished. A reviewer waives the item for 14 days with a written reason. | An exception: who, on what authority, why, and its expiry. |
| 4. The work is built | A coding run opens a pull request. | For each head the Studio published: the agent that produced it, the model, and who started the run. |
| 5. The Done gate | Items that read the pull request are assessed against its current head. CI is read at that head. | The assessments, and the CI check runs and statuses as they stood at that head. |
| 6. The release is approved | The work package goes on a release with others. The approver approves it. | The approval, the DPIA it relied on — and a signed passport, version 1, issued in the same step. |
| 7. The pipeline deploys | The tag is pushed. The pipeline’s passport check fetches the signed passport and verifies it on the runner. The waiver from step 3 has two days left, so it still counts as in force and the deploy starts. | The check’s result in the job log. |
| 8. The pipeline reports back | After the deploy succeeds, the pipeline tells the Studio which environment received which commit. | A deployment entry on the release and in its ledger. |
| 9. Three days later | The waiver has expired. Nothing is undone — the deployment stands. But anyone who verifies version 1 of the passport now is told an exception has run out, and the next deploy of that release in an enforced environment is held until the item is met or the waiver renewed and the passport issued again. | Nothing is written at expiry. The state is worked out from the date whenever it is read. |
Three rules that explain most of what you will see
Unknown is never shown as satisfied. If the record does not hold a decision, the passport says Unknown. It does not guess, and it does not round up.
Only an issued version is signed. The passport you read day to day is the live view. It says Chain intact — not signed yet, and those words are deliberate.
A saved change is never rolled back for the sake of its evidence. If the ledger cannot be written at the moment of a save, the change is kept and the gap is put on record. See When Evidence Is Not Recorded.
Where to go next
| You want to | Read |
|---|---|
| Read a passport and understand every word on it | Artefact Passport |
| Make your checklist items count towards ISO 27001 or SOC 2 controls | Map Controls to Checklist Items |
| Waive an item, renew a waiver, or understand what expiry does | Gate Exceptions |
| Give an auditor a passport they can check themselves | Issue, Share and Verify a Passport |
| Stop a deploy that has no valid passport | Wire a Pipeline to the Passport |
| Understand a sample review, a legal hold or a bill of materials | Sample Reviews, Holds and SBOMs |
| Know who is allowed to do each of these | Who May Do What |
| Set rules for every studio in your organisation | Guardrail Policies (Organisation Portal) |
| Look up a word | Passport Glossary |