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. Preserve recursive closed-schema validation for every nested object; new fields require explicit key and type handling.
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, globally unique integer pipeline number, pipeline status, and a gate-verify step status. Collection-wide identity/type validation occurs before commit filtering; a duplicate number across two commits fails subject binding. The highest numbered valid rerun for one commit is authoritative. Its retention window is provider-controlled and is not overstated by this repository.

Do not add or update an activation SHA in the manifest. The verifier derives the audited feature range from Git's merge-base with provider target refs/remotes/origin/main, so commits before a delayed registry introduction remain covered. HEAD, HEAD's parent, the introduction commit, and delayed introduction after a gate change are registered rejected constructions.

DOES: The merge-base is outside branch-author control when main cannot be rewritten. DOES NOT: This bootstrap cannot protect a compromised or rewritten main; Builds 1-2 own that residual. Production verification also requires non-empty criteria/gates/prose/scenario populations and anchors the seven required gate IDs to canonical sources before any “all registered” claim.

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.