A policy gate denied every entry of a CI matrix job. How do you tell a rule defect from a real violation?

## Two very different problems wearing the same message A denial tells you a rule fired. It does not tell you whether the world is wrong or the rule is wrong. The two outcomes need opposite responses - one changes the job, the other changes the rule - and the cost of guessing is high in both directions. Wave through a real violation and the guardrail was theatre; force a team to contort a correct job around a rule defect and you have taught them that policy is an obstacle to route around. When an entire matrix job is denied at once, the prior shifts sharply toward rule defect. A single denied entry among many usually reflects something specific to that entry. Everything denied at once means the rule is reacting to a property of the *shape* the expansion produced, not to a property any human authored. ## Reconstruct what the engine read The authored block is not what was judged. A matrix takes one block and produces N concrete jobs, and along the way it interpolates variables into names, attaches shared blocks such as credential or service definitions, applies platform defaults, and sometimes flattens or re-nests structures. So the artifact to look at is the evaluated document for a denied entry. Then get a contrast case: the same rule passing somewhere else, ideally a non-matrix job of the same kind. Diff the two documents. You are looking for one of three findings: - **The field is present with a forbidden value.** Real violation. The job declares something the rule forbids. - **The field is present but at a different path.** Rule defect. The author wrote against the shape they saw in the source, and expansion moved it. - **The field is simply absent.** This is the interesting one, and it is where most of these investigations land. ## Absent is not the same as wrong Consider a rule that says any build job able to reach production credentials must declare an egress allowlist. The author pictured a job with a `credentials` list and a `network.egress_allowlist` list, and wrote the rule to deny when credentials are present and the allowlist is missing or empty. Now the matrix expands. One entry inherits the shared credential block - so the rule's trigger condition is satisfied - while the allowlist, which the author declared once at the top of the source block, did not survive expansion into every entry, or landed under a per-entry `network` object that the expansion created empty. Every entry now looks, to the rule, like a job holding production credentials with no allowlist. The rule fires correctly on the document it was given and refuses work that is not actually dangerous. The diagnostic point is that *absent* carries two contradictory meanings which the rule cannot distinguish: "this job deliberately declares nothing" and "this document does not represent that concept at all". A rule that treats absence as a violation will be right about the first and wrong about the second, and it will be wrong every time the surface it reads changes shape. This is why the reconstruction has to start from the evaluated document rather than from an argument about intent. ## Confirm the hypothesis before you act Do not stop at a plausible story. Replay the denied document off the enforcement path, then perturb it: insert the allowlist at exactly the path the rule reads and confirm the denial clears. If it clears, you have proven both what the rule wants and where it expects it. If it does not, your hypothesis is wrong and there is a second condition you have not found. The same perturbation tells you which fix is right. If the only way to clear the denial is to write a field that has no meaning in the expanded form, the rule is asking for something the surface cannot express, and the rule must change. If the field is meaningful and the team simply did not set it per entry, the job changes. ## What the fix looks like on the rule side When it is a rule defect, the repair is usually not "exclude matrix jobs". It is to make the rule's trigger and its check read the same subject: decide deliberately what the rule does when the field is absent, and either look for the concept everywhere it can legitimately live in this surface, or narrow the trigger so the rule only fires on documents whose shape it actually understands. Then add the expanded document that caused the denial to the rule's fixture set, so the shape the author never pictured is now a shape the rule is tested against forever. ## And say so out loud Whichever way it lands, write the finding in one sentence - *this rule denied because the expanded entry has no field at path X, which the source declares once at the block level* - and put it where the blocked team can read it. A team that watched a gate refuse six jobs will remember whether the answer arrived as an explanation or as a shrug.