Define a clean-build gate

1231. Lesson identity

Module

3.10 — Build pipeline

Lesson

Define a clean-build gate

Academic type

Guided Build

Schema type

practical

Order

Lesson 2 in the module

Estimated time

50–65 minutes, including practice

1232. Learning objective

After this lesson, you can write and execute a clean-build checklist that maps a verified clean state and declared inputs to an identifiable artifact, observable acceptance criteria, and evidence for each gate decision.

1233. Why this matters

A build gate turns a build from an informal demonstration into a decision record. It tells you what was built, from which inputs, in which environment, and what evidence is required before the artifact can move forward. This matters when AI-assisted changes increase the number of possible edits and make memory an unreliable source of truth. The gate does not guarantee that a game is good; it establishes whether this build is valid for the stated test.

1234. Prior knowledge

You should be able to:

• Apply the I-A-E-G model from the previous lesson: inputs, artifact, environment, and gate.
• Distinguish a successful local launch from reproducible build evidence.
• Identify the intended build target and the basic launch path for the project.
• Identify a known Git commit or tag that can be recorded as the source revision for the build.

1235. Core concept

A clean-build gate is documented with four connected elements: M-A-C-E.

1. Matrix: the declared combinations of target, configuration, environment, and relevant inputs that will be tested.
2. Artifact: the exact output under evaluation, with a distinguishable identity linked to its source revision and build conditions.
3. Criteria: observable conditions that determine pass, fail, or blocked status.
4. Evidence: records that prove the declared clean state, inputs, artifact identity, environment, and result of each criterion.

The four elements must agree. A matrix without an artifact identity cannot prove what was tested. An artifact without criteria cannot establish whether the result is acceptable. Criteria without declared inputs or evidence cannot support reproduction. A clean-state definition belongs in the inputs and evidence of the gate; it is not a substitute for the matrix, artifact identity, or acceptance criteria.

A clean state is a workspace in which no prior generated artifact, temporary build output, or unlisted local modification can be mistaken for the output under evaluation. Define the source revision, dependencies or packages, configuration, generated-output treatment, and cache or temporary-data treatment relevant to the target. “The folder looked normal” is not a sufficient definition.

Clean-state definition and clean-state verification are separate. The definition states what must be true. Verification records how you checked that it was true before building, what you observed, and where the evidence can be found. Running a clean command alone does not prove the resulting state.

A clean build also separates two decisions:

• Build result: did the toolchain produce an artifact?
• Gate result: does that artifact satisfy the declared criteria in the declared environment, with sufficient evidence?

A build can succeed while the gate fails or remains blocked. For example, an artifact may be produced but fail to launch, omit a required entry point, or lack evidence that it came from the declared clean state and source revision.

1236. Mental model

Use M-A-C-E for every gate:

The previous lesson's I-A-E-G model describes the system. M-A-C-E is the working document you create to operate its gate. A useful gate row has this shape:

Matrix → clean-state definition and declared inputs → artifact identity → test action → expected result → evidence → status

Do not treat “no error appeared” as an acceptance criterion. State what the player, tester, or build operator can observe.

1237. Concrete example

Suppose a small game has one supported web target and a production configuration. A weak record says:

Build passed. It runs in the browser.

A stronger M-A-C-E record says:

Matrix: Web / production / supported browser class
Clean state and inputs: source revision COMMIT_OR_TAG; declared dependencies present; no unlisted local modifications or prior generated output included; relevant cache treatment recorded
Artifact: contraband-web-build / COMMIT_OR_TAG / checksum when available
Criteria:
  1. The artifact loads without a fatal startup error.
  2. The intended entry point becomes visible.
  3. The primary player action produces the specified response.
  4. A reload returns to the defined initial state.
Evidence: clean-state verification record, build output, recorded Git commit or tag, environment, launch result, action-result notes, and artifact identifier
Status: PASS only when the clean state, identity, environment, and all four criteria are evidenced

The example does not claim that the game is complete. It makes one build decision inspectable and repeatable.

1238. AI-native workflow

AI can draft the document; it cannot supply evidence that you did not verify. Give the AI the target, configuration, intended environment, known source revision, and the acceptance claim. Ask it to propose M-A-C-E checklist steps and failure hypotheses. Do not give it secrets, tokens, private keys, or unredacted sensitive configuration.

Then inspect every proposal against the actual project and run. Correct the matrix if the environment or inputs are wrong; correct the artifact section if the output cannot be distinguished; correct the criteria if they are not observable; and correct the evidence section if it does not show clean-state verification, source identity, environment, outputs, or secret boundaries. The learner—not the AI—assigns PASS, FAIL, or BLOCKED.

A useful prompt is:

Draft a M-A-C-E clean-build checklist for this target and configuration. Propose observable acceptance criteria and failure hypotheses. Do not invent evidence, commits, artifact identifiers, environment details, or secret values. Mark unknowns for verification.

Treat the response as a draft. Replace placeholders with observed evidence, remove unsupported assumptions, and record which proposed failure hypotheses were tested or rejected.

1239. Common mistake

The common mistake is to write a checklist as a sequence of tool commands rather than as a testable contract. “Clean the folder, run the build, open the result” describes activity but not acceptance. It does not say what clean means, how the clean state was verified, which inputs were used, how the artifact is identified, or what must be observed after launch.

Another frequent mistake is allowing a single successful build to stand in for every matrix row. Each row represents a distinct claim. If the target, configuration, environment, clean state, or source revision changes, the evidence must be associated with that row rather than copied from another result.

1240. Guided practice

Create and execute a clean-build gate for one real build target in your project. Do not begin by writing commands. Begin by writing the decision the gate must support.

1241. Step 1: Define the matrix

Complete this table with the smallest useful matrix for the current milestone:

If only one row is justified, keep one row. Do not add platforms or configurations merely to make the matrix look complete. Mark each row as required or out of scope, and state why an out-of-scope row is excluded.

1242. Step 2: Define and verify the clean state

For every required row, write a tool-agnostic clean-state definition before selecting an execution command. State:

• Which known Git commit or tag is the source revision.
• Which dependencies, packages, or generated inputs are allowed.
• Which configuration and target settings are required.
• Which prior generated artifacts, temporary outputs, or local modifications must be absent, excluded, or explicitly regenerated.
• Which caches or temporary data are permitted, cleared, or irrelevant to this claim.
• Which secret boundaries apply: no secret values should be copied into the checklist, logs, screenshots, prompts, or artifacts.

Then verify the definition before producing the artifact. Record what you inspected, what you observed, and whether it matched the declared state. If the workspace cannot be shown to match the definition, mark the gate BLOCKED until the state is corrected or the scope is explicitly changed. A clean command by itself is not verification.

Use this compact verification record:

Clean-state definition:
Source Git commit or tag:
Allowed dependencies or generated inputs:
Required configuration and target:
Prior outputs, temporary data, and cache treatment:
Secret boundary checked:

Verification check 1:
Expected state:
Observed state:
Result: PASS / FAIL / BLOCKED
Evidence:

Verification check 2:
Expected state:
Observed state:
Result: PASS / FAIL / BLOCKED
Evidence:

1243. Step 3: Define artifact identity

For every required row, record:

• Artifact name.
• Known Git commit or tag used as the source revision. This field is required; if no known commit or tag is available, the row cannot receive a valid PASS.
• Configuration and target.
• Build-output location or package identifier.
• A checksum or equivalent identity when your tooling provides one.
• The date or run label used by your team to distinguish executions.

Do not replace missing identity with “latest build.” The recorded commit or tag must appear both in the artifact identity and in the execution evidence. Do not include secret values in the artifact name, logs, evidence, or AI prompt.

1244. Step 4: Write acceptance criteria

Write three to five criteria using observable language. Include at least:

• Startup or loading behavior.
• The intended entry point or initial state.
• One representative player action and its expected response.
• A defined failure condition, such as a fatal error, missing content, or unresponsive input.

Each criterion must be answerable with PASS, FAIL, or BLOCKED. “Looks fine” is not a valid result.

1245. Step 5: Execute the checklist

Start from the declared and verified clean state and use only the inputs listed in the gate. Produce the artifact, identify it, and test each criterion in order. Record the result and evidence immediately. Include the known Git commit or tag, the environment, the clean-state verification record, and the output identity in the execution evidence. If a step cannot be performed, mark it BLOCKED; do not mark it PASS because the build launched.

Use this execution record:

Gate name:
Target/configuration/environment:
Declared inputs:

Clean-state definition:
Clean-state verification evidence:
Secret boundary:

Source Git commit or tag:
Artifact identity:
Build-output location or package identifier:
Checksum or run label, if available:

Criterion 1:
Result: PASS / FAIL / BLOCKED
Evidence:

Criterion 2:
Result: PASS / FAIL / BLOCKED
Evidence:

Criterion 3:
Result: PASS / FAIL / BLOCKED
Evidence:

Overall gate: PASS / FAIL / BLOCKED
Open questions or follow-up actions:

A PASS requires a verified clean state, a known Git commit or tag, a distinguishable artifact identity, the declared environment, evidence for every required criterion, and no breach of the stated secret boundary. If any of those are absent, use FAIL or BLOCKED according to whether the evidence demonstrates a failed condition or an unverified condition.

1246. Step 6: Make one judgment call

Choose one of these situations, or use an equivalent situation from your run:

• The build succeeds, but one acceptance criterion was not tested.
• The artifact launches, but its identity cannot be distinguished from the previous output.
• The target works in one environment, but the declared environment was not used.
• The artifact was produced, but the workspace clean state or source Git commit or tag was not verified.

Decide whether the overall gate is PASS, FAIL, or BLOCKED. Write two sentences explaining why. The explanation must refer to the missing or observed evidence, not to confidence or intuition.

1247. Validation / evidence

The lesson is complete when you can point to all of the following:

• A build matrix with at least one justified required row.
• A written, tool-agnostic clean-state definition for that row.
• Verification evidence showing whether the declared clean state was present before execution.
• A named artifact with a distinguishable identity linked to a known Git commit or tag.
• The declared environment and output location or package identity.
• Three to five observable acceptance criteria.
• An execution record containing the clean-state verification, source Git commit or tag, environment, secret-boundary check, and evidence for every criterion.
• An overall PASS, FAIL, or BLOCKED decision with a written rationale.

A valid submission does not require a PASS result. A FAIL or BLOCKED result is acceptable when the decision accurately reflects the evidence and identifies the next action. The capability being assessed is the quality of the gate, not the concealment of a build problem.

1248. Key takeaways

• M-A-C-E connects the matrix, artifact identity, criteria, and evidence of a clean-build gate.
• Clean-state definition and clean-state verification are different requirements.
• Build success and gate acceptance are separate decisions.
• A known Git commit or tag, declared environment, distinguishable output, and evidence for each criterion are required for a defensible PASS.
• AI may draft checklist steps and failure hypotheses, but the learner must verify and correct the gate record and must not expose secrets.

1249. Next lesson

Next, continue to 3.11 — Desktop wrappers, the canonical destination after 3.10 — Build pipeline, and carry this gate record forward as build evidence for the next stage of milestone work.

1250. Knowledge check