stack/docs/ADMIN-GUIDE/quality-gate-registry.md

Gate Registry Operations

Routine verification

Run pnpm gate:verify from a dependency-installed checkout. Exit zero means registry observations matched their declared actual values; it does not assert required-behavior conformance while deltas remain. Open DEFECT records are checked descriptions of current behavior with tracked owners, never successful gate outcomes.

Investigate any of these immediately:

• GATE VERIFY FAILED — registry structure, observed behavior, provenance, claim binding, source/deployment identity, or negative-control detection changed.
• unregistered gate — an executable appeared under a declared gate root without a registry entry.
• no negative control — a gate has no must-fail case.
• DEPLOYED IDENTITY UNAVAILABLE — the runner cannot reach the installed enforcing copy. The pinned observation is checked, but live equality is not asserted.
• PROVIDER EVIDENCE ... ABSENT — retained external history was unavailable; do not infer merge-time success.

Updating a gate

1. Add or change the criterion and exact case.
2. Observe the case fail for its own stated reason.
3. Declare an exact inerting mutation and observe the verifier detect it.
4. If required and actual behavior differ, add a tracked remediation owner and justification.
5. If meaning changed, append provenance; never replace the original silently.
6. For an installed counterpart, verify live byte identity and update the observed digest only from measured evidence.
7. Run focused verifier tests, pnpm gate:verify, and the repository baseline gates.

Do not add an ownerless exception or describe an open delta as pass/green/OK.

CI behavior

Woodpecker runs gate-verify on every pull request and protected-main push without path filtering. This is deliberate: changes outside gate files can make a gate inert. The step unshallows the checkout first because prospective ancestry and own-tree replay require complete commit history; a shallow boundary must never be interpreted as non-ancestry.

Provider evidence input is an optional JSON array of normalized pipeline records containing commit, unique integer pipeline number, pipeline status, and a gate-verify step status. The highest numbered rerun is authoritative; ambiguous duplicates fail. Its retention window is provider-controlled and is not overstated by this repository.

Prior commit replay performs a frozen offline install from each commit's own lockfile before running that commit's verifier. Bubblewrap clears the environment, hides operator-home credentials, isolates process namespaces, and disables networking for historical lifecycle and verifier code. Archived files are snapshotted before install and must remain byte/type/mode-identical afterward. A missing cached dependency, source mutation, or unavailable sandbox fails replay; current dependencies are never substituted.