Skip to content

Chapter 19: Engineering the Quality Gate

From a Pile of Checks to One Gate Estate

Every team ends up with checks. Lint, tests, a vulnerability scan, a migration guard. Each was added after something went wrong, and each one earns its place.

What rewards design is not the check. It is the set: which decisions a change must pass, where in the work each decision is made, and what evidence lets a person act on it. A team that designs that set runs fewer checks, finds failures earlier, and can answer the question every incident review asks — would this have been caught?

This chapter builds that set. It starts from the decisions rather than the checks, places each decision at a moment in the work, and ends with an estate you can draw on one page.


1. The Pile You Have

Every check in a pipeline has a story. A release shipped a defect a test would have caught, so the test was added. A credential reached a log, so the scan was added. A migration broke a neighbouring table, so the guard was added.

Each addition was right on the day it landed. Nobody could argue against it, and nobody did.

The difficulty is what the additions make together. A pipeline assembled that way has no owner and no design: one question gets answered by two commands with different bodies, a check ends up in whichever file was easy to edit, and some stop running when the workflow around them changes. Nothing announces the loss. A check that no longer runs looks exactly like a check that passes.

🎯 What You'll Learn

  • What a gate, a moment and a gate estate are, in words you can use in a review
  • Why a check's name and a check's body drift apart, and what that costs on every change
  • How to place every check you have at one of four moments, and name the ones nothing runs

Four Words, Defined Here

Word What it means What it is not
check one thing a machine verifies — lint, the tests, a secret scan, a type check not a verdict; a check produces a result
gate a check a change must pass before it may proceed not a report, a dashboard or a notification
gate estate all the gates of one organisation, taken as a set not one gate or one repository's gates
estate everything one person operates: repositories, services, hosts not the gates — the estate is what the gates protect

The cost of a pile is not the minutes the checks take. It is that two questions have no answer. Would the last incident have been caught? and which command do I run before I merge? When both answers are "it depends who you ask", the checks are measuring the pipeline rather than protecting the estate.

A gate estate is the other thing: the small set of decisions a change must pass, each with a name, a place in the work, and evidence a person can read. The set is small because decisions are few — merge, deploy, release — while checks are many.

This is the book's third structure made executable. The prompt structure states what must be true, the engineering structure decides how it is checked, and the workflow structure is where those checks become decisions a change cannot pass without. A gate estate is the workflow structure written down, and this chapter builds it one decision at a time.

💰 Cost Check: an undesigned pipeline is not paid for once. It is paid on every change — a wait for a gate that could not fail, a review that argues again over which command is authoritative, an incident that a check would have caught if the check still ran. The minutes are the smallest part.


2. A Gate Is a Contract, and It Declares Five Things

A gate is a place work cannot pass without a decision. Four things are needed for that decision to mean anything: what must be true before it runs, what it checks, what it concludes, and what may happen next.

Most pipelines implement the second and skip the first. A check reads something — a file, a table, a deployed address — and reports on it. Whether that something was the right thing is assumed, and the assumption is where green results come from that mean nothing.

It happened to GitLab on 31 January 2017. An engineer working late on a database server removed the wrong directory, and a few hundred gigabytes of production data went with it. Five recovery mechanisms existed and each failed in a different way, including routine backups whose upload had been failing quietly for some time; the data was restored from an older staging snapshot, and six hours of work was gone. The recovery gate existed and had been believed for years. Its precondition — this copy is the database — had never been written down, so nothing checked it.

The five declarations are what a gate promises, and a green result is only as good as the part the reader checked.

Declaration The question it answers The failure when it is missing
Precondition what must be true before it runs a green result about a world that was not there
Invariant what must always be true nobody knows why the gate exists, so nobody can delete or extend it
Scope exactly what it reads and what it ignores the reader assumes it covered more than it did
Verdict pass, fail, or not-verified — and what each means "not run" is read as "passed"
Cost how long it takes, and on which moment it drifts onto a moment whose budget it violates

Precondition is the one nobody writes down, and it produces the false greens. A gate that reads a copy has a precondition: the copy exists, and it is current. A gate that probes an address has one: the deployment happened. A gate that compares a table against a declaration has one: the declaration was read, not defaulted. Precondition is not scope — scope is what the gate looks at, precondition is what had to be true for looking at it to mean anything.

Invariant is the sentence the gate exists to keep true: "no credential is committed", "every endpoint has a test". Without it the gate has no reason to exist, and nobody can tell whether a change made it obsolete or merely inconvenient.

Verdict has three states. A gate that can only say pass or fail will eventually say pass about something it could not read — a file it lacked permission for, a service that was down, a check it skipped. Not verified is a verdict, and it is different from pass.

Scope is the expensive one. A gate's name suggests a scope; its body reads a scope. When the two disagree, the gate is honest code wearing a dishonest name, and the reader inherits the claim without the check. A command called validate that runs the content checks and the syntax checks will be read as validating the change, including the parts it never reads.

Write It Down in Five Sentences

precondition: the staged file list was read, not defaulted
invariant:    no credential reaches the repository
scope:        every staged file; ignores vendored/ and *.min.*
verdict:      pass | fail | not-verified (a scan that could not read a file)
cost:         under 2s — atomic moment

Five lines, in the file where the gate lives. When one is wrong, the argument about the gate becomes a conversation about a sentence instead of a memory.

✅ What to Check

  • Take your slowest gate. Write its invariant. If you cannot, it exists because of an incident nobody remembers.
  • Name the exact paths your gate does not read. If the name suggests otherwise, the name is the defect.
  • Name the gate's precondition. If it reads a copy, say which copy and how you know it is current.

3. A Gate Has a Name, a Moment and an Environment

Three questions describe any gate, and a team that answers all three can place a check in a sentence:

Question The word for it Example
what does it decide? its name deployment gate
when does it fire? its moment commit, full, scheduled
where does it run? its environment local, staging, production

The Five Names

Five decisions cover most of what a delivery estate needs. Each has the name the industry already uses, so a reader joining the team knows what it means before the first stand-up.

The gate The command The decision it makes
commit gate pre-commit may this be committed? — the staged diff, in seconds
merge gate ci may this land? — the whole tree, the pipeline's own gate
deployment gate deployment-gate env=local would this deploy, and did it?
smoke test smoke env=staging does the deployed system do the one thing it exists for?
release gate orch release tag=v1.4.0 may this become a version?

Two naming rules follow. Commands name actions: pre-commit is what you do, deployment-gate is what runs. Environments are arguments: the same command judges staging and production, and the argument says which.

The Four Moments

A gate moment is when in a change's life a gate fires. Each moment carries a budget — the most time it may take before it stops helping — and the budget grows as the change moves later:

flowchart LR
    A["Atomic<br/>ms–s"] --> B["Commit<br/>seconds"]
    B --> C["Full<br/>minutes"]
    C --> D["Scheduled<br/>hours"]

What this shows: the journey a change makes. The arrow is time, not a dependency between checks.

Moment The question it answers Fits
Atomic is this one thing right, right now? lint, types, formatting
Commit can the author still fix this cheaply? the commit gate, unit tests on changed files
Full does the whole change hold together? the merge gate, integration tests
Scheduled is anything rotting that a change would not reveal? dependency audits, clean-checkout builds

A moment is when, never where. Staging is a place a build runs; full is the moment a change is judged as a whole. Keeping the two apart is what lets the same gate run in three environments without its meaning changing.

Your CI has stages; this book has moments, and the difference is worth thirty seconds. A stage is a phase a pipeline groups jobs into, and the jobs inside it may run in parallel. A moment is when a gate fires. A pipeline has stages whether or not it has gates, and a gate has a moment whether or not a pipeline runs it. The two are easy to merge in conversation, and merging them is how a scheduled job comes to be treated as a merge gate.

Most engineers arrive with their own names for these moments. They are the same four, and this table is the translation:

Your CI calls it This book calls it The moment is A gate there answers
pre-commit hook, pre-push, on save atomic any time, one concern, milliseconds is this one file right, right now?
commit hook, staged check commit as the change is recorded can the author still fix it cheaply?
ci job, the PR check, the merge gate full the whole change is complete does it all hold together?
nightly, cron, scheduled workflow scheduled the clock decides is anything rotting that a change would not reveal?

Two rules of placement keep a moment meaningful. A check lives at exactly one moment: two copies will drift apart, and when they disagree nobody knows which one is authoritative. And a moment is not a place: moving a check to a different environment changes where it runs, never when it fires.

"Release" is an event, not a moment. A moment is when; a release is something a person decides, and what runs at it is the release gate in an environment. Keeping the word for the event separate from the word for the moment is what stops a release checklist from being mistaken for a gate.

✅ What to Check

  • For every check, name its moment. One moment per check; two is a drift waiting to happen.
  • Read your own prose: every use of "gate" without a name from the five is a sentence that will not survive a handover.
  • Time the commit moment. Over a minute means something is sitting where it does not fit.

4. The Workflow, and the Gates Between Its Stages

A change does not pass four moments in the abstract. It passes stages of work, and each gate sits between two of them:

flowchart LR
    A["edit<br/>a file"] --> G1{"atomic"}
    G1 --> B["record<br/>a commit"]
    B --> G2{"commit"}
    G2 --> C["integrate<br/>a branch"]
    C --> G3{"full"}
    G3 --> D["operate<br/>a host"]
    D --> G4{"scheduled"}

What this shows: the box is work; the diamond is a gate. The work arrives at a stage, and a decision stands between it and the next stage — which is why a gate is a transition and a stage is a place. The arrow is the change moving, not a dependency between checks.

The four moments are positions in that flow, not a timetable. And the gates a change actually meets are five, because two of them judge a deployment and a release — levels of their own, not moments:

# The gate Fires at Sits between What has to be true when it passes
1 commit gate the commit moment a file and the repository the staged change is sound — it may be committed
2 merge gate the full moment a branch and the trunk the whole tree holds — it may be pushed
3 deployment gate its own level — it judges a deployment, not a change the trunk and a host this would deploy — it may go to a host
4 smoke test the deployment level, after it a host and a reader the address serves a reader, and the one thing the system exists for works
5 release gate an event an estate and a version it may become a version — clean tree, gates green, tag pushed

Read the table as a sequence, not a menu. Each gate answers a question the next one assumes: a release is safe because the smoke test passed, which is possible because the deployment gate produced a deployable artefact, which depended on the merge gate's verdict, which began with a commit that passed its own gate. Skip a row and the next row is a guess.

Which Test Belongs at Which Gate

A reader's suite is not a pile of checks; it is a set of tests at different levels, and the level decides the gate. The rule is one sentence: a test belongs to the earliest gate whose environment contains everything the test needs to see. Earlier is cheaper; later is the only place some things are visible at all.

Test level What it can possibly prove Its gate Why there, and not earlier
static analysis · lint · types the code is well-formed commit (atomic) milliseconds, and it needs only the file
unit one function is right commit cheap enough to run constantly; it cannot see a database
contract two components still agree merge (full) needs both sides present
integration components work together merge (full) needs the real dependencies
system / end-to-end the deployed system does the thing smoke (deployment level) needs a running environment; a file cannot show it
dependency audit · migration reversibility · secret scan nothing is rotting scheduled the answer changes with the calendar, not with the diff
acceptance · a person's judgement a human says yes release a person cannot be in the pipeline

The test you cannot place is the finding. A check that fits no row is either measuring something no gate needs — delete it — or it is measuring something real that nothing is positioned to act on, which is a hole in the workflow, not a spare test.

✅ What to Check

  • Can you draw your own flow — the stages work actually passes through, and the gate between each pair?
  • Take each test in your suite and name the gate it belongs to. A test you cannot place is a finding.
  • Does any gate judge an environment it was not given? A merge gate that reads a deployed address is measuring the wrong stage.
  • Is any stage ungated — work arriving somewhere that nothing judges?

5. The Deployment Gate: the Level That Fails Your Pushes

A push that goes red in CI is usually not a defect in the code. It is a defect in the path — the workflow that runs, the tool that changed, the artefact that was built differently from the one that was published, the route a reader takes that nobody exercised.

A gate that reads the code cannot see any of that. The deployment gate can, and it is the level that pays for itself fastest.

The failure you meet Can a code gate see it? The check that catches it
the workflow no longer parses, or names a job that no longer exists no a workflow-schema and job-graph check
the platform tool now requires a flag it never required no a local run of the same command the deploy runs
a route answers 404 after the switch no a check that the route exists before the URL moves
the build produced one directory and the deploy published another no a check comparing what is built with what is published
a reader typing the site's own address gets an error page no a smoke test of the journey a person takes

The Local Tier, and Its Ceiling

The deployment gate runs in three environments, and the cheapest one proves the most per second.

Question Local (ENVIRONMENT=local) Staging / production What local costs
does the workflow parse, and does the job graph still name the jobs? ✅ ✅ seconds
does the strict build produce the deployable artefact? ✅ ✅ a minute
does the built site carry what the deploy would upload? ✅ ✅ included in the build
do the worker bindings and the Worker bundle? ✅ ✅ seconds
does the generated audio match the page it narrates? ✅ ✅ tens of minutes per chapter
do permissions, secrets, DNS and TLS work? ❌ ✅ —
does the real address serve a reader? ❌ ✅ (the smoke test) —

The last cost is the one to plan around. A local text-to-speech render is free, private, and takes longer than everything else in the gate combined — so the check that a page edit has not invalidated its narration is worth having, and the re-render it asks for is worth scheduling rather than doing on every save. A gate is not free because it runs on your machine.

That table is also the honest edge. Local proves would this deploy; the deployed environment proves it is deployed and serving. A team that runs only the first has a fast gate and an unverified address.

The Command

deployment-gate env=local          # your wrapper — make, npm run, task — is your project's choice

The gate replays the path: the deploy-path checks (workflow schema, job graph, worker bundle, and the local stack where one exists), the strict build, and the comparison between what was built and what would be published.

deployment-gate env=staging        # the same artefact, on a real host
smoke env=staging                  # is the deployed address working?

Where the Loop Finishes

Validation starts local: fast, free, private, and it proves what a build would do. It stops being enough when the question is about the destination — permissions, secrets, DNS, TLS, the address a reader reaches.

So the loop moves to an environment closer to that destination: the same deploy path, the same configuration surface, the same kind of address. That is what makes the iteration accurate rather than approximate, and it is the reason to keep such an environment at all.

Four properties keep that environment cheap to destroy and rebuild, and they are the same four that make it useful:

  • defined in the repository — infrastructure, configuration and seed data as files, so an environment can be created again from nothing;
  • a dataset that can be reloaded — synthetic, or a scrubbed copy, so the database can be thrown away;
  • one command to create and one to destroy — the same commands the pipeline uses, not a runbook;
  • nothing critical depends on it — no customer data, no resource production shares.

An environment with those four can be discarded when a run damages it and rebuilt inside the time the loop can afford. Because the interruption is cheap, the loop can run there unattended — an agent may converge on this environment; production stays a person's decision.

What a Smoke Test Proves — and What It Must Do When It Fails

The smoke test is the only gate that judges the system a reader actually reaches, so its scope is the reason it exists. The address answering is its precondition, not its verdict. A static page answers 200 with the application behind it dead: the load balancer is healthy, the HTML renders, the status code is correct, and the interaction the estate sells returns a failure. A smoke test that checks only the address certifies exactly the state it was built to detect.

So it exercises journeys, not URLs — the three or four interactions the business exists on. It asserts a contract, not a status code: that a query returns documents, that a request returns the response shape its clients parse, that a sign-in yields a session. It is read-only, deterministic and finished inside a minute, because a gate that mutates data is a second incident and a gate that takes five minutes is one people start skipping. It does not depend on anything the estate does not control — an AI model provider, a third-party widget — or it reports that dependency's health as if it were the estate's.

Its failure has an edge, and the edge is the point. A smoke test that fails describes a deployment that is already live and already wrong, so the sequence stops: the release gate does not run, and the environment returns to the version that last passed this gate — automatically, not after a discussion. That is why the rollback is rehearsed (§18, §25): a rollback nobody has executed is a plan, and the moment it is needed is the worst moment to learn it does not work. A smoke test whose failure has no consequence is not a gate. It is a dashboard with a status code.

The edge has one honest exception, and stating it is part of the design: a change that cannot be reversed has no rollback to take. A migration that dropped a column, a provider that was cut over, a schema that was rewritten — for those, the failure edge is a roll-forward path, and the thing to prepare before the deploy is the fix, not the return. The gate is not weaker for saying so; it is weaker when a team discovers it during the incident, so the irreversible changes are named in the gate's own record and the roll-forward path is rehearsed like any other.

The edge also has a precondition, and it is the one most easily left implicit. A rollback is a return to something that still exists: an artefact the platform kept, a schema that accepts the older code, a copy of the data that has been restored at least once. So the deployment gate declares its way back before it runs, and the declaration names which layer it returns through — the artefact, the schema, or the data. A copy nobody has restored is a hypothesis, not a recovery (§18). The three layers have different costs, and a design that has only the first is the common one: the artefact rolls back in minutes, the schema rolls back only if the migration was additive, and the data does not roll back at all unless someone rehearsed it.

The Irreversible Release, as a Named Class

Some changes have no way back, and the estate is stronger when it says so than when it pretends otherwise. An irreversible change — a dropped column, a truncated table, a provider cut over — is not an exception to the gate; it is a class with a procedure, and the procedure has three facts that must be true before it runs. Without them, "declared" means "someone wrote a reason", which is how a ban becomes a formality.

The fact What it proves Where it is recorded
The observation window has elapsed the previous phase has been live long enough that the data being removed is no longer needed the change's own record
The data is archived, and the archive has been restored once "we copied it" is a hypothesis until a drill has read it back (§18) the drill's output
The decision is forward-only, and owned after this deploy there is no return, so the decision is made before, by a named person the signature on the change

Those three facts are what §15's ban means by "declared, reviewed and owned": declared is the window and the archive, reviewed is the drill, owned is the signature. The gate refuses destruction; the procedure is how destruction is allowed.

Order carries the safety, and it is the reason the class is safe. Destructive work belongs to the last phase of expand → migrate → contract (§25), one deploy per phase, and never in the same deploy as the code that stops using the old shape. The window exists so that the rollback stays available while the new shape proves itself; shortening it by one release converts a reversible change into an unrehearsed one.

✅ What to Check

  • Name the last three deploy failures you had. How many would a code gate have caught?
  • Does your local build produce the same shape as your deploy build? If not, the local gate is measuring something else.
  • For each deploy-path check you cannot run locally, write the reason down. An unstated reason becomes an assumption.
  • List the journeys your smoke test exercises. If it names a URL rather than an interaction, it is a liveness probe, not a smoke test — and it will pass while the product is down.
  • Say what happens when it fails. Name the command that restores the previous version, and the last time you ran it. If either answer is missing, the sequence has no edge.
  • Name your last irreversible change. State its window, its archive's restore date and its owner. All three, or the change was not declared.

6. How the Gates Compose

Three Words First

Word What it means What it is not
entry point a command a person types to run "the checks" — ci, test, validate not the checks themselves
composition which checks run under which command, declared in one place not a habit, not a README
slice a command that runs part of a gate, on purpose not the whole gate, and never named as if it were

The Seven Rules

Each rule is written in four beats: the practice, what it gives you, where it lives, and the signature of its absence.

1 · One name means one thing. It gives you: a verdict that travels — "it passed" means the same thing in every repository, so a handover keeps its meaning. Where it lives: the naming rule every repository reads. Its absence looks like: ci runs four checks in one repository and seven in another, and both are called green.

2 · A slice says what it skips. It gives you: a fast command you can trust, because it tells you what it left out before it tells you the verdict. Where it lives: the slice's own output — before the verdict, not in a document beside it. Its absence looks like: validate skips the tests, and the person who ran it believes it did not.

3 · The same command locally and in CI. It gives you: a local pass that predicts a pipeline pass, which is the whole reason a developer runs anything before pushing. Where it lives: the one composition file both the pipeline and the developer invoke. Its absence looks like: a deploy fails on lint, in files the change never touched, because the author ran the fast slice.

4 · A gate proves it ran. It gives you: a verdict with a count and an artefact behind it, so the next reader can audit it and a silent skip cannot pass as success. Where it lives: the gate's own output and its log — the numbers, not the adjective. Its absence looks like: "passed" with no number, or a check that matched zero rows and reported success.

5 · One command is the whole gate. It gives you: one word that answers "did you run the checks?", and every other command visibly a subset of it. Where it lives: the single composition file that defines the whole gate as the union of its named parts. Its absence looks like: four entry points with overlapping subsets — ci runs everything, check runs two, test runs lint, security runs validate — and each one believes it is the gate.

6 · A failure names the fix. It gives you: a failure line that sends its reader to the file, the line and the reason, instead of to a log. Where it lives: the failure line itself, in the same shape everywhere. Its absence looks like: exit 1 and nothing else, so the next reader greps.

7 · Debt is declared, printed and expiring. It gives you: a check that cannot exist yet, recorded as a decision with a reason and a date — and a registry that prints itself on every run. Where it lives: an exemption registry, regenerated with the gate. Its absence looks like: a skipped check nobody recorded, discovered during an incident.

Eight Questions Before the Next Gate

# The question A thin answer looks like
1 What invariant does this keep true? "it catches bugs"
2 Which moment can afford it? "we'll put it in CI"
3 What exactly does it read, and what does it ignore? nobody has looked at the ignore list
4 What does it say when it cannot read? a colour
5 What would make us delete it? silence
6 Who owns it when it breaks? "whoever wrote it"
7 Does an existing gate already cover this? not asked
8 What does a false positive cost here? not measured

Question 5 is the one that keeps an estate from only growing. A gate nobody can imagine deleting is either essential or forgotten, and the question tells you which.

✅ What to Check

  • Pick the rule your estate most needs; make it true before adding the next gate.
  • For each rule, name the file where it is enforced.
  • Count the entry points that claim to run "the checks". One definition is the goal; two is the next piece of work.

7. What the Set Pays Back

The chapter asks for a set of decisions, and every one of them pays on the day it is needed. The table states the payment, not the bill.

The practice What it gives you The moment it pays
the five declarations (§2) a gate whose name and whose body agree, so a reader can act on its verdict when a deploy fails and the first question is what did this actually check?
the third verdict a gate that says not verified instead of passing on something it could not read when the service is down and the check cannot reach it
one name, one meaning "it passed" that survives a handover when someone new asks what to run before merging
declared exemptions skips you know about, with a reason and a date, instead of skips you discover when an incident review asks why a class of defect was never caught
liveness every gate has a crafted case that turns it red, so a silent skip cannot impersonate a pass the first time someone changes a gate and assumes it still works
the deploy-path level failures found before a push, on the path rather than in the code the ten minutes you would otherwise spend reading a CI log

The pattern in every row is the same: the estate either tells you the truth or it tells you nothing. A gate that cannot fail does not warn you — it reports success, which is the one thing you cannot recover from.

✅ What to Check

  • Take the last three incidents in your estate. Which row of that table would have changed the outcome?
  • Ask of each gate: if it were deleted tomorrow, what would break, and who would notice?

8. How It Is Implemented

The chapter is advice until it is a file. These are the files.

1 · The composition file — one definition of the whole gate:

# the merge gate: the union of its named parts, in one place
ci: validate lint test security-scan
    @echo "ci: 4 checks — the same four the pipeline runs"

2 · The exemption registry — every skipped check, with its reason, printed on every run:

# config/gate-exemptions.yaml — debt that expires, never silence
exemptions:
  ci: a composition of validate + lint + test + security, each proven separately

3 · The liveness proof — for each gate, one crafted case that makes it fail:

test-<gate>                  # plants the defect that gate names, asserts the refusal

4 · The generated table — the audit, as an artefact rather than a meeting:

gate-estate                  # → a generated table: gate · moment · what it promises · proven by

The generator reads three sources that already exist — the command surface (the Makefile), the pipeline (the workflow file), and the gate scripts — so the table cannot disagree with them. A gate that appears in one and not the others is the finding.

The first run of an audit like this is usually instructive rather than comfortable. A gate estate that has grown for a few years will have gates whose moment is —, gates whose failing case is missing, and at least one gate nobody can say the purpose of. That is not a failure of the audit; it is the audit doing its job, and every row it names is a five-minute decision.

✅ What to Check

  • Does a new reader find the whole gate in one file? Open it and look.
  • Does every gate name the case that fails it? If not, which exemption is missing?
  • Does the table regenerate, or is it a document that was true the day it was written?

9. Four Anti-Patterns the Design Prevents

An anti-pattern is a way of building that looks reasonable locally and fails systematically. You do not recognise it from a single instance — you recognise it from the shape it leaves across an estate.

Anti-pattern What it looks like The design that prevents it
Many entry points, one promise several commands claim to run "the checks"; people pick the cheapest one name per decision, and every other command a declared subset
The gate that reads its own output it reports defects in generated files no change can fix scope drawn around what the change owns
The context-sensitive gate it does more in CI than locally, and nobody knows which ran one behaviour; scope declared, never inferred from the environment
The copy-paste gate the same gate in a dozen repositories as a dozen slightly different bodies one standard implementation, and a conformance check between them

Two further shapes belong to Chapter 2 §10 rather than here: the gate that cannot fail, and the gate that fails on everything. Both are alive in most estates, and both are cheap to fix once named.

Common Mistakes to Avoid

  1. Adding a check without naming its invariant and its moment.
  2. Letting a name promise more than the body runs.
  3. Reading a build product and calling it the source.
  4. Copying a gate into a new repository without a conformance check.

✅ What to Check

  • Pick the anti-pattern you recognise in your own estate, and name the design change that would have prevented it.
  • For each of the four, ask whether one of §6's rules would have stopped it. If none would, the rule set has a gap.

10. Build the Workbench

Artefacts

Artefact What it is for Where it lives
deployment gate would this deploy? — the path, checked locally deployment-gate env=local
gate table every gate: its name, moment, promise and proof docs/gates.md, generated
composition file the one definition of the whole gate Makefile or the CI workflow
exemption registry every skipped check, with reason and expiry config/gate-exemptions.yaml
liveness record for each gate, the case that fails it the gate's own self-test

Decisions

Choice Default What changes if you choose otherwise
one composition file yes several definitions of "everything", which is the defect
moment per check exactly one two copies that drift
verdict states pass · fail · not-verified "not run" read as "passed"
exemptions declared, printed, expiring silent skips discovered during incidents
the table generated a document true the day it was written

Sequence

  1. Inventory — list the commands and what each runs. Checkpoint: one table, one line per repository.
  2. Name — the five names; one command per decision. Checkpoint: ci means one thing everywhere.
  3. Place — one moment per check; move the misfits. Checkpoint: the commit moment is under a minute.
  4. Prove — a failing case for each gate. Checkpoint: a planted defect turns it red.
  5. Watch the path — the deployment gate, local first. Checkpoint: a planted workflow error fails locally.
  6. Generate — build the table from the repository. Checkpoint: the audit runs in the gate.

Done When

  • One command is the whole gate, and every other command is a visible subset of it.
  • Every gate can name the defect it would catch.
  • A planted defect in the deploy path fails locally, before a push.
  • The table is generated, and a gate with no failing case fails the run.

11. 🔑 Chapter Summary

The gates a team has are an accident; the gates a team designs are an asset.

  1. Checks accumulate because each one is reasonable and the set is never reviewed. The estate is the set, and a set can be designed.
  2. A gate is a contract: precondition, invariant, scope, verdict, cost. Scope and precondition are the two whose absence produces a confident, meaningless green.
  3. A gate has a name, a moment and an environment — five names (commit · merge · deployment · smoke · release), four moments (atomic · commit · full · scheduled), and the environment as an argument.
  4. The deployment gate is the level that catches the path. Local proves would this deploy; the deployed environment proves it is deployed and serving.
  5. Seven rules compose an estate: one name one meaning · a slice says what it skips · local equals CI · a gate proves it ran · one command is the whole gate · a failure names the fix · debt is declared, printed and expiring.
  6. Silence is the failure mode to design against: an unearned green, a scope assumed, a skip unrecorded, a gate that cannot fail.
  7. Four artefacts make it real: the composition file, the exemption registry, a failing case per gate, the generated table.
  8. Four anti-patterns belong to composition — many entry points, reading its own output, context sensitivity, copy-paste.

The orchestrator's test: ask which command runs everything. If the answer is one word, and it means the same thing in every repository, the estate has a definition. If the answer takes a sentence, it has a tradition.