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. The verifier aggregates independent phase failures, so repair the responsible stable-ID diagnostics as well as any accompanying stale-fixture error; do not treat the generic error as a substitute.
• 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, its exact criterion-side caseRefs, and matching case-side criterionIds.
2. Observe the must-fail case fail for its own stated reason; moving the binding to any undeclared case must fail verification.
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 so activation ancestry and historical manifest provenance can be checked; 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.

PR CI executes current-tree verification only, unprivileged and fail-closed. It does not execute isolated own-tree replay: RM-60 must provide a protected launcher or runner-level rootless sandbox before any PR-controlled executable/configuration is evaluated. Repo-only code cannot safely grant itself the capability intended to contain itself.

The deferred replay implementation remains hard-fail when its sandbox cannot be established; it is not silently skipped as a successful replay. Tests recognize unavailability only from parent-generated Bubblewrap-launch provenance combined with proof that the sandbox entry command did not run. A denial-looking string from child-controlled output is not evidence. When RM-60 activates replay under protected authority, it uses frozen own-tree dependencies, namespace/environment isolation, and archived-file identity checks. A post-merge failure triggers quarantine and revert. This is detection, not pre-merge prevention.