docs(adr): codify repository governance threat model, trusted-base execution and protected transitions

[qnbs]

Context

The 2026-09-28 deep audit and the #857–#869 governance sequence established a substantial trust architecture, but its threat model and authority boundaries are distributed across workflow comments, issues and recovery history.

This issue owns a post-release ADR, not another pre-release governance mutation.

Goal

Write one durable architecture decision record explaining:

• what the repository is defending against;
• what is trusted and why;
• what is merely advisory;
• how protected transitions are authorized;
• why self-authorizing PRs are forbidden;
• how branch protection/rulesets complete the trust boundary;
• where human/admin authority begins.

Inputs

The ADR must consume the terminal evidence from:

• W0 / governance(protection): prove required-check binding, workflow origin and bypass policy before further hardening #875;
• W1 / governance(bootstrap): retire remaining PR-head fallback paths without triggering another pin cascade #876;
• governance(changelog): replace heuristic fallback ambiguity with a deterministic contract for unnumbered governed commits #675/QNB-68 final reconciliation;
• the protected-transition mechanism introduced by ci(governance): evolve the evaluator graph only through base-owned protected transitions #868;
• the post-ci(governance): retire the workflow-policy introducing-transition fallback #869 trusted-base workflow behavior;
• current branch-protection/ruleset truth at ADR-writing time.

Do not write the ADR from historical assumptions if W0 later disproves them.

Required sections

Actors / threat model

Classify at minimum:

EXTERNAL_UNTRUSTED_CONTRIBUTOR
AUTHORIZED_MAINTAINER
AUTONOMOUS_CODING_AGENT_WITH_REPO_ACCESS
GITHUB_ACTIONS_BASE_OWNED_WORKFLOW
THIRD_PARTY_REVIEWER_APP
HUMAN_ADMIN

State which actors can create commits, PRs, workflow changes, settings changes and merges.

Trust roots and evaluator graph

Document:

• trusted roots;
• evaluator/import closure;
• protected-transition verifier and base-owned manifest semantics;
• why the PR head cannot authorize its own protected change;
• replay/stale-transition prevention;
• what remains policy-constrained immutable.

Branch protection / rulesets

Document the actual live protection contract proven by #875:

• required contexts/workflows;
• identity semantics;
• conversation/review requirements;
• admin/bypass behavior;
• limitations of classic status-context matching if still used.

If the binding contract is imperfect, say so explicitly rather than describing intended policy as actual enforcement.

Declared reviewer policy vs effective enforcement

The ADR must distinguish durable reviewer-policy declarations from live merge enforcement.

At minimum document these states separately:

DIRECT_REQUIRED
TRANSITIVE_REQUIRED
POLICY_REQUIRED_BUT_NOT_PLATFORM_BOUND
ADVISORY_ONLY
UNKNOWN_EXTERNAL

The ADR must explain how config/reviewer-registry.json relates to:

• branch-protection / ruleset required contexts;
• required aggregate workflows such as ✅ CI Success and their needs closure;
• vendor/dashboard behavior that can affect GitHub status or review disposition;
• base-owned versus PR-controlled workflow origin;
• maintainer/admin bypass semantics.

A registry field such as blockingAuthority is a declaration of intended governance semantics, not standalone evidence that GitHub currently enforces that provider directly.

Consume the terminal reconciliation evidence from #780 and #875. If live platform state disagrees with repository policy, state the drift explicitly; do not rewrite history or present aspiration as enforcement.

Also codify the pull_request_target invariant: privileged/base-owned target workflows may inspect PR content only as untrusted data and must not execute PR-controlled code/dependencies under secrets or write credentials.

Bootstrap history vs permanent design

Explain which #857-era bootstrap mechanisms are historical, which were retired, which remain structurally dormant, and why some cannot be removed without a protected transition.

Do not turn historical recovery scaffolding into normative design merely because it still exists.

Operational rules for agents

Codify:

• no admin merge;
• no protection bypass;
• no self-authorization;
• no function-wrapper/control-flow bypass;
• exact-SHA resulting-main proof;
• anti-cascade / batched-push review convergence;
• read-before-write and stop-at-human-boundary behavior.

Acceptance

• ADR matches live implementation and settings, not aspirational prose;
• every authority claim is traceable to code/settings/evidence;
• superseded bootstrap details are clearly marked historical;
• AGENTS.md / reviewer-governance docs point to the ADR rather than duplicating its full architecture;
• no CI/protection mutation is required merely to publish the ADR;
• any newly discovered implementation defect is split to its own issue rather than silently fixed inside documentation work.

Sequencing

Post-v1.29.0. Perform after the first post-release mutation/toolchain owners chosen ahead of documentation have terminal evidence, so the ADR records a stable architecture rather than another transient state.

Related: #675, #780, #875, #876, #873, #872.

[qnbs]

DEV.to follow-up incorporated — 2026-09-29

The ADR scope now explicitly requires a distinction between durable reviewer-policy declarations and effective merge enforcement:

DIRECT_REQUIRED / TRANSITIVE_REQUIRED / POLICY_REQUIRED_BUT_NOT_PLATFORM_BOUND / ADVISORY_ONLY / UNKNOWN_EXTERNAL.

It must consume #780's registry/effective-authority reconciliation and #875's live protection evidence, and codify the strict pull_request_target rule that PR-controlled code/dependencies never execute under privileged base-owned credentials.