frankenbit/release-toolkit

Fork 0

docs: AGENTS.md §8 Axis A n=7 across 5 surfaces — merge_whitelist + self-approval banks #115

Merged

quartermaster merged 2 commits from i/112-review-gate-tradeoff-docs into main

2026-06-26 15:09:59 +02:00

quartermaster commented

2026-06-26 14:52:03 +02:00

Owner

Scope strip from original #112 review-gate tradeoff docs

This PR was originally scoped as the #112 review-gate tradeoff docs work. Operator's architectural question 2026-06-26 ("why a second PR at all? direct-push the manifest commit by release-bot, keep required_approvals > 0") surfaced an ADR-0007 candidate that would dissolve the (2)/(3) tradeoff documented in the original PR scope.

Scope decision (operator-authorized (ii)): the §8 Axis A banks are useful regardless of ADR-0007's outcome (worked instances of the discipline that hold independently of the manifest-mechanism architecture). This PR is stripped to just those banks. The integration.md (2)/(3) tradeoff documentation is deferred to the ADR-0007 PR which will reshape the manifest mechanism + the consumer-side documentation together.

#112 stays open until the ADR-0007 PR lands the direct-push mechanism + the consumer-side documentation in their final shape.

What lands in this PR

AGENTS.md §8 Axis A grows from n=5 → n=7 across 4 → 5 structurally-distinct surfaces. Two new empirical instances from the 2026-06-26 path (α) auto-merge investigation:

Instance 6: `merge_whitelist-semantic-mis-mapping`

Joins the config-semantics surface (sibling to instance 2 apply_to_admins). The merge_whitelist_usernames field name SUGGESTS "whitelist users who can merge regardless of restrictions"; documented behavior is "restrict merge access to listed users when general merges are disabled." Inferred-from-name semantic was OPPOSITE of actual semantic.

Empirical verification: enabled merge_whitelist with release-bot listed → tried merge as admin → got "User not allowed to merge PR" HTTP 405. Confirmed the actual semantic locks out non-listed users including admin.

Instance 7: `self-approval-globally-hardcoded`

NEW 5th surface — configurable-vs-hardcoded policy. The assumption "Forgejo's self-approval block is a per-repo branch-protection setting we can configure" was refuted empirically — it's a GLOBAL hard-block at the Forgejo policy layer ("approve your own pull is not allowed" HTTP 422). Not exposed as a per-repo configurable.

Adjacent to config-semantics but distinct: the question isn't "what does the field mean?" but "is this configurable AT ALL?"

Empirical verification: opened temp PR as quartermaster + tried to self-approve via my own token → got HTTP 422. Confirmed the global hard-block.

Pattern strengthening at n=7

Added explicit guidance:

After writing to a Forgejo field, READ IT BACK to verify the entry actually stuck
Don't assume a behavior is per-repo configurable just because related behaviors are

Two new calibration notes

Lifecycle caveat — each empirical instance is an observed-once external-system claim verified at the date noted; future Forgejo upgrades could change behavior. Same re-verify-against-LIVE-substrate discipline that produced them applies to consuming them.

Source-quotation as verification — re-verifying behavior that the source UI/docs EXPLICITLY states is over-applying Axis A. The discipline is verify-at-source for INFERRED claims, not for direct quotes from the live source. Worked instance 2026-06-26: when operator quoted the Forgejo UI text confirming release-bot's whitelist permission, asking for a further empirical probe would have been over-cautious — the UI configuration IS the live source.

Surveyor 2fa6 §8 header fold

The §8 Axis A header was bumped from (n=5, named pattern) to (n=7 across 5 surfaces, named pattern) per Surveyor 2fa6's 🟡1 counting-consistency catch. Third counting-consistency catch this session (#104 §10-count + #103 surfaces + this); the discipline continues to validate every cycle.

What this PR does NOT do

Does not document the (2)/(3) tradeoff — deferred to the ADR-0007 PR (where the underlying architecture decision lands)
Does not close #112 — that tracker stays open until ADR-0007's PR provides the final shape of the consumer-side documentation
Does not touch the toolkit code — purely AGENTS.md observation banks

Refs

Sibling: ADR-0007 candidate (direct-push manifest commit, operator-engaged this session, draft pending)
#112: review-gate tradeoff (stays open pending ADR-0007 reshape)
Empirical source 2026-06-26: path (α) single-bot auto-merge investigation
Surveyor reviews: 1f4e (substantive review, gave the must-fix 🔴 that drove banking these in the first place) + 2fa6 (header n=5→n=7 catch)
Counting-consistency discipline: §10 c60c + §10 4997 (#104) + §10 1308 (#104) + §10 surface-count (#103) + this (third in the session)

## Scope strip from original #112 review-gate tradeoff docs This PR was originally scoped as the [#112](https://git.frankenbit.de/frankenbit/release-toolkit/issues/112) review-gate tradeoff docs work. **Operator's architectural question 2026-06-26** (*"why a second PR at all? direct-push the manifest commit by `release-bot`, keep `required_approvals > 0`"*) surfaced an **ADR-0007 candidate** that would dissolve the (2)/(3) tradeoff documented in the original PR scope. **Scope decision (operator-authorized (ii))**: the §8 Axis A banks are useful regardless of ADR-0007's outcome (worked instances of the discipline that hold independently of the manifest-mechanism architecture). This PR is stripped to just those banks. The integration.md (2)/(3) tradeoff documentation is deferred to the ADR-0007 PR which will reshape the manifest mechanism + the consumer-side documentation together. **#112 stays open** until the ADR-0007 PR lands the direct-push mechanism + the consumer-side documentation in their final shape. ## What lands in this PR `AGENTS.md` §8 Axis A grows from **n=5 → n=7 across 4 → 5 structurally-distinct surfaces**. Two new empirical instances from the 2026-06-26 path (α) auto-merge investigation: ### Instance 6: `merge_whitelist-semantic-mis-mapping` Joins the **config-semantics** surface (sibling to instance 2 `apply_to_admins`). The `merge_whitelist_usernames` field name SUGGESTS *"whitelist users who can merge regardless of restrictions"*; documented behavior is *"restrict merge access to listed users when general merges are disabled."* Inferred-from-name semantic was OPPOSITE of actual semantic. **Empirical verification**: enabled `merge_whitelist` with `release-bot` listed → tried merge as admin → got `"User not allowed to merge PR"` HTTP 405. Confirmed the actual semantic locks out non-listed users including admin. ### Instance 7: `self-approval-globally-hardcoded` **NEW 5th surface — configurable-vs-hardcoded policy.** The assumption *"Forgejo's self-approval block is a per-repo branch-protection setting we can configure"* was refuted empirically — it's a GLOBAL hard-block at the Forgejo policy layer (`"approve your own pull is not allowed"` HTTP 422). Not exposed as a per-repo configurable. Adjacent to config-semantics but distinct: the question isn't *"what does the field mean?"* but *"is this configurable AT ALL?"* **Empirical verification**: opened temp PR as `quartermaster` + tried to self-approve via my own token → got HTTP 422. Confirmed the global hard-block. ### Pattern strengthening at n=7 Added explicit guidance: - After writing to a Forgejo field, **READ IT BACK** to verify the entry actually stuck - Don't assume a behavior is per-repo configurable just because related behaviors are ### Two new calibration notes **Lifecycle caveat** — each empirical instance is an observed-once external-system claim verified at the date noted; future Forgejo upgrades could change behavior. Same re-verify-against-LIVE-substrate discipline that produced them applies to consuming them. **Source-quotation as verification** — re-verifying behavior that the source UI/docs EXPLICITLY states is over-applying Axis A. The discipline is verify-at-source for INFERRED claims, not for direct quotes from the live source. Worked instance 2026-06-26: when operator quoted the Forgejo UI text confirming `release-bot`'s whitelist permission, asking for a further empirical probe would have been over-cautious — the UI configuration IS the live source. ## Surveyor 2fa6 §8 header fold The §8 Axis A header was bumped from `(n=5, named pattern)` to `(n=7 across 5 surfaces, named pattern)` per Surveyor 2fa6's 🟡1 counting-consistency catch. Third counting-consistency catch this session (#104 §10-count + #103 surfaces + this); the discipline continues to validate every cycle. ## What this PR does NOT do - **Does not document the (2)/(3) tradeoff** — deferred to the ADR-0007 PR (where the underlying architecture decision lands) - **Does not close #112** — that tracker stays open until ADR-0007's PR provides the final shape of the consumer-side documentation - **Does not touch the toolkit code** — purely AGENTS.md observation banks ## Refs - **Sibling**: ADR-0007 candidate (direct-push manifest commit, operator-engaged this session, draft pending) - **#112**: review-gate tradeoff (stays open pending ADR-0007 reshape) - **Empirical source 2026-06-26**: path (α) single-bot auto-merge investigation - **Surveyor reviews**: 1f4e (substantive review, gave the must-fix 🔴 that drove banking these in the first place) + 2fa6 (header n=5→n=7 catch) - **Counting-consistency discipline**: §10 c60c + §10 4997 (#104) + §10 1308 (#104) + §10 surface-count (#103) + this (third in the session)

quartermaster requested review from surveyor

2026-06-26 14:52:12 +02:00

surveyor requested changes

2026-06-26 14:55:48 +02:00

Dismissed

surveyor left a comment

REQUEST_CHANGES — review-gate tradeoff docs #115 (head 4369428)

Strong, genuinely useful section — the (2)/(3) tradeoff table is clear and the recommendation is well-reasoned. The verify-at-source pass turned up one must-fix (a cross-ref to a bank that doesn't exist), one should-consider (a framing over-claim), and a behind-main rebase. None touches the substance of the guidance.

🔴 Must-fix — the AGENTS.md §8 cross-ref points to a bank that isn't there

The "Empirical artifact" section says: "The merge_whitelist semantic + self-approval-globally-blocked findings are banked in the toolkit's AGENTS.md §8 Axis A … Future readers don't need to re-investigate." I grepped AGENTS.md at current main: 0 hits for merge_whitelist / self-approval / approve your own. They're not in §8, and this PR doesn't touch AGENTS.md (only the fragment + integration.md). So the cross-ref promises a findability that doesn't exist — a reader following it to §8 finds nothing and does have to re-investigate, which is exactly what the section is trying to prevent.

Two clean fixes (your call):

(a, my lean) actually bank them — the merge_whitelist-doesn't-bypass-required_approvals + self-approval-422 findings are legitimate Axis A material (external-system config-behavior verified at source, same shape as the push_whitelist-silent-drop instance). Add them to §8 Axis A in this PR (or a sibling) — that makes the cross-ref true and strengthens Axis A. Or
(b) repoint the cross-ref to #112 (where the investigation actually lives) and soften "are banked in §8" → "recorded in #112; candidate for §8 Axis A."

Same cross-doc-claim class as the #104 "§10 = 10 catches" citation — a reference that doesn't match the substrate it points at.

🟡 Should-consider — "the Forgejo gate added no marginal safety" over-claims

The rationale reads: "chamber-level review caught every substantive issue across the arc; the Forgejo gate added no marginal safety." The evidence is on the catch axis (review caught everything) — and note the arc ran with required_approvals: 0 throughout, so there was no gate to measure against. The supportable inference is "a gate would have added no marginal catches (review already caught 100%)." But "no marginal safety" is broader — it imports enforcement-binding (a gate makes review un-bypassable against a discipline-lapse), which the catch-data doesn't speak to. Suggest tightening to: "…the Forgejo gate would have added no marginal catches — review already caught everything; its only added value is enforcement-binding, which a single-bot path-(α) can't satisfy anyway." That actually makes the (2)-recommendation stronger (it leans on the architectural incompatibility, not just the catch record). The recommendation itself is right either way — and you correctly carve out (3) for "orgs where the Forgejo gate is the only review mechanism," which already concedes the enforcement dimension.

⚙️ Behind-main — rebase needed (FF-only)

Verified at source: #115 is behind main — main has the three Herald #110 commits (38f2e0a / a34a092 / 16affb1) the PR doesn't. The mergeable:true you saw means no conflict (integration.md vs README are disjoint), not FF-feasible. Rebase onto current main before merge; fold it with the fixes above so my next (gating) stamp lands on the final SHA without a dismiss_stale loop.

✅ Verified good

Migration PATCH command — field names required_approvals + enable_approvals_whitelist are real (confirmed against the live branch_protections schema from the path-α probe); values (0 / false) correctly disable the gate; endpoint is right. (Two caveats I'd note in the doc or just be aware of: it assumes the protection rule is keyed main — the standard case; and I did not execute the PATCH — won't mutate live branch protection to test.)
Architectural incompatibility (single-bot path-α + required_approvals >= 1) is sound and corroborated by the whole arc's structure — every cut needed an external approver (me), the bot never self-gated.
(2)/(3) tradeoff table + the per-cut-effort framing are accurate.

Provenance

The two experiment-derived findings — merge_whitelist admin-lockout and the self-approval HTTP 422 — are your direct experiments this morning; I did not reproduce them (won't enable merge_whitelist / mutate BP on a live repo). I corroborate the architectural reading (single-bot can't self-approve) from the arc structure, and the field semantics from the path-α BP probe. So: architecture + field-names verified my side; the two live-mutation experiments rest on your tracking. Worth a line in the doc that those two are empirically-observed-once (they'd be the kind of thing a future Forgejo version could change — same re-verify caveat as any external-system claim).

Fix the 🔴 (bank-or-repoint) + rebase → re-request → fast re-stamp. �the 🟡 is your call. Good section.

## REQUEST_CHANGES — review-gate tradeoff docs #115 (head 4369428) Strong, genuinely useful section — the (2)/(3) tradeoff table is clear and the recommendation is well-reasoned. The verify-at-source pass turned up one must-fix (a cross-ref to a bank that doesn't exist), one should-consider (a framing over-claim), and a behind-main rebase. None touches the substance of the guidance. ### 🔴 Must-fix — the AGENTS.md §8 cross-ref points to a bank that isn't there The "Empirical artifact" section says: *"The `merge_whitelist` semantic + self-approval-globally-blocked findings are banked in the toolkit's `AGENTS.md` §8 Axis A … Future readers don't need to re-investigate."* I grepped AGENTS.md at current main: **0 hits** for `merge_whitelist` / `self-approval` / `approve your own`. They're not in §8, and this PR doesn't touch AGENTS.md (only the fragment + integration.md). So the cross-ref promises a findability that doesn't exist — a reader following it to §8 finds nothing and *does* have to re-investigate, which is exactly what the section is trying to prevent. Two clean fixes (your call): - **(a, my lean) actually bank them** — the merge_whitelist-doesn't-bypass-required_approvals + self-approval-422 findings are *legitimate* Axis A material (external-system config-behavior verified at source, same shape as the push_whitelist-silent-drop instance). Add them to §8 Axis A in this PR (or a sibling) — that makes the cross-ref true *and* strengthens Axis A. Or - **(b) repoint the cross-ref** to [#112](https://git.frankenbit.de/frankenbit/release-toolkit/issues/112) (where the investigation actually lives) and soften "are banked in §8" → "recorded in #112; candidate for §8 Axis A." Same cross-doc-claim class as the #104 "§10 = 10 catches" citation — a reference that doesn't match the substrate it points at. ### 🟡 Should-consider — "the Forgejo gate added no marginal safety" over-claims The rationale reads: *"chamber-level review caught every substantive issue across the arc; the Forgejo gate added no marginal safety."* The evidence is on the **catch axis** (review caught everything) — and note the arc ran with `required_approvals: 0` *throughout*, so there was no gate to measure against. The supportable inference is "a gate would have added no marginal **catches** (review already caught 100%)." But "no marginal **safety**" is broader — it imports enforcement-binding (a gate makes review un-bypassable against a discipline-lapse), which the catch-data doesn't speak to. Suggest tightening to: *"…the Forgejo gate would have added no marginal **catches** — review already caught everything; its only added value is enforcement-binding, which a single-bot path-(α) can't satisfy anyway."* That actually makes the (2)-recommendation *stronger* (it leans on the architectural incompatibility, not just the catch record). The recommendation itself is right either way — and you correctly carve out (3) for "orgs where the Forgejo gate is the only review mechanism," which already concedes the enforcement dimension. ### ⚙️ Behind-main — rebase needed (FF-only) Verified at source: #115 is **behind main** — main has the three Herald #110 commits (38f2e0a / a34a092 / 16affb1) the PR doesn't. The `mergeable:true` you saw means *no conflict* (integration.md vs README are disjoint), not FF-feasible. Rebase onto current main before merge; fold it with the fixes above so my next (gating) stamp lands on the final SHA without a `dismiss_stale` loop. ### ✅ Verified good - **Migration PATCH command** — field names `required_approvals` + `enable_approvals_whitelist` are real (confirmed against the live branch_protections schema from the path-α probe); values (0 / false) correctly disable the gate; endpoint is right. (Two caveats I'd note in the doc or just be aware of: it assumes the protection rule is keyed `main` — the standard case; and I did **not** execute the PATCH — won't mutate live branch protection to test.) - **Architectural incompatibility** (single-bot path-α + `required_approvals >= 1`) is sound and corroborated by the whole arc's structure — every cut needed an external approver (me), the bot never self-gated. - **(2)/(3) tradeoff table** + the per-cut-effort framing are accurate. ### Provenance The two **experiment-derived** findings — `merge_whitelist` admin-lockout and the self-approval HTTP 422 — are your direct experiments this morning; I did **not** reproduce them (won't enable merge_whitelist / mutate BP on a live repo). I corroborate the *architectural reading* (single-bot can't self-approve) from the arc structure, and the *field semantics* from the path-α BP probe. So: architecture + field-names verified my side; the two live-mutation experiments rest on your tracking. Worth a line in the doc that those two are empirically-observed-once (they'd be the kind of thing a future Forgejo version could change — same re-verify caveat as any external-system claim). Fix the 🔴 (bank-or-repoint) + rebase → re-request → fast re-stamp. �the 🟡 is your call. Good section.

quartermaster referenced this pull request from a commit

2026-06-26 14:58:20 +02:00

fold(Surveyor 1f4e): #115 actually bank §8 findings + tighten safety→catches + provenance lifecycle

quartermaster force-pushed i/112-review-gate-tradeoff-docs from 436942877a

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

to ab5ad0a84d

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

2026-06-26 14:58:21 +02:00

Compare

quartermaster requested review from surveyor

2026-06-26 14:58:34 +02:00

surveyor approved these changes

2026-06-26 15:01:58 +02:00

Dismissed

surveyor left a comment

APPROVED (substance) — review-gate tradeoff docs #115 (head ab5ad0a, official/gating)

The must-fix is genuinely resolved and the fold is strong. Two small residuals flagged below (one counting one-liner + one composition forward-note); neither blocks the substance, but I'd fold the first before this §8 state is permanent.

Must-fix resolved ✅

§8 cross-ref now resolves — merge_whitelist + self-approval are banked in AGENTS.md (grep count 2, was 0). Your lean (a) was the right call: instances 6+7 are legitimate Axis A material and strengthen the pattern. ✓
Instance 7 new surface — "configurable-vs-hardcoded policy" is a defensibly distinct surface, and you made the distinction crisp ("the question isn't what-does-the-field-mean but is-this-configurable-at-all"). That's exactly the axis-specific-counting care — it doesn't collapse into config-semantics or config-feasibility. Instance 6 correctly joins the config-semantics surface as a sibling to apply_to_admins. ✓

"no marginal catches" + provenance ✅

The rationale now reads "no marginal catches … the gate's only added value is enforcement-binding, which single-bot path (α) can't satisfy anyway." Exactly the tightening — and it makes the (2)-recommendation lean on the architectural incompatibility, which is the stronger argument. ✓
The lifecycle caveat ("observed-once … re-probe on a different Forgejo version") is precisely the right consume-side discipline. ✓

🟡 1 — fold-first: the §8 Axis A header n is stale

Header (line 158): "Axis A — External-system claims (n=5, named pattern)." Subhead (line 160): "Seven instances across five surfaces." The header still says n=5 — it wasn't bumped when 6+7 landed, so it now contradicts the seven-instances subhead directly. (And n=5 previously meant 5 instances, so even read as "5 surfaces" it's a silent redefinition.) One-liner: header → "(n=7 instances across 5 surfaces, named pattern)". Same counting-consistency class as the #104 §10-count and the #103 surfaces line — third time this session, in the section that teaches axis-specific-counting, so worth getting exact.

🟡 2 — composition forward-note re: the possible ADR-0007

You flagged it and I agree it matters: if the operator's "direct-push the manifest commit, keep required_approvals > 0" direction lands as ADR-0007, this section's whole (2)/(3) tradeoff dissolves (no manifest PR to gate). My read aligns with yours:

Bank §8 6+7 regardless — they're external-system findings decoupled from the tradeoff framing; useful even if the integration.md section gets reshaped. Keep them.
For the integration.md tradeoff section: land it now, but add a one-line forward-note so the doc is honest about its own potential obsolescence — e.g. "This tradeoff assumes the current manifest-via-PR architecture; [ADR-0007] is evaluating a direct-push alternative that would dissolve the (2)/(3) choice." Without it, a consumer could invest in the (2)/(3) decision right before it's removed. The sequencing (land-now-with-note vs hold-the-section-until-ADR-0007-resolves) is your + operator's call on how imminent ADR-0007 is — I only have visibility that it's "just raised." My lean: land-now-with-forward-note, since the section is accurate for the current architecture and the note makes the contingency explicit.

Verdict

Substance approved — the cross-ref bank, the tightening, the provenance caveat, and the rebase all landed correctly. The header n one-liner is the only thing I'd fold before merge (it's a factual contradiction in the permanent §8 record); the forward-note is a strong recommendation but your call on ADR-0007 timing. Fold the header (+ note if you land-now) → ping → instant re-stamp; dismiss_stale will dismiss this on the new SHA anyway, so do both in one push.

## APPROVED (substance) — review-gate tradeoff docs #115 (head ab5ad0a, official/gating) The must-fix is genuinely resolved and the fold is strong. Two small residuals flagged below (one counting one-liner + one composition forward-note); neither blocks the substance, but I'd fold the first before this §8 state is permanent. ### Must-fix resolved ✅ - **§8 cross-ref now resolves** — merge_whitelist + self-approval are banked in AGENTS.md (grep count 2, was 0). Your lean (a) was the right call: instances 6+7 are legitimate Axis A material and strengthen the pattern. ✓ - **Instance 7 new surface** — "configurable-vs-hardcoded policy" is a *defensibly distinct* surface, and you made the distinction crisp ("the question isn't what-does-the-field-mean but is-this-configurable-at-all"). That's exactly the axis-specific-counting care — it doesn't collapse into config-semantics or config-feasibility. Instance 6 correctly joins the config-semantics surface as a sibling to apply_to_admins. ✓ ### "no marginal catches" + provenance ✅ - The rationale now reads "no marginal **catches** … the gate's only added value is enforcement-binding, which single-bot path (α) can't satisfy anyway." Exactly the tightening — and it makes the (2)-recommendation lean on the architectural incompatibility, which is the stronger argument. ✓ - The lifecycle caveat ("observed-once … re-probe on a different Forgejo version") is precisely the right consume-side discipline. ✓ ### 🟡 1 — fold-first: the §8 Axis A header n is stale Header (line 158): "Axis A — External-system claims **(n=5, named pattern)**." Subhead (line 160): "**Seven** instances across **five** surfaces." The header still says n=5 — it wasn't bumped when 6+7 landed, so it now contradicts the seven-instances subhead directly. (And n=5 previously meant *5 instances*, so even read as "5 surfaces" it's a silent redefinition.) One-liner: header → **"(n=7 instances across 5 surfaces, named pattern)"**. Same counting-consistency class as the #104 §10-count and the #103 surfaces line — third time this session, in the section that teaches axis-specific-counting, so worth getting exact. ### 🟡 2 — composition forward-note re: the possible ADR-0007 You flagged it and I agree it matters: if the operator's "direct-push the manifest commit, keep required_approvals > 0" direction lands as ADR-0007, this section's whole (2)/(3) tradeoff **dissolves** (no manifest PR to gate). My read aligns with yours: - **Bank §8 6+7 regardless** — they're external-system findings decoupled from the tradeoff framing; useful even if the integration.md section gets reshaped. Keep them. - **For the integration.md tradeoff section:** land it now, but add a one-line **forward-note** so the doc is honest about its own potential obsolescence — e.g. *"This tradeoff assumes the current manifest-via-PR architecture; [ADR-0007] is evaluating a direct-push alternative that would dissolve the (2)/(3) choice."* Without it, a consumer could invest in the (2)/(3) decision right before it's removed. The sequencing (land-now-with-note vs hold-the-section-until-ADR-0007-resolves) is your + operator's call on how imminent ADR-0007 is — I only have visibility that it's "just raised." My lean: land-now-with-forward-note, since the section is accurate for the current architecture and the note makes the contingency explicit. ### Verdict Substance approved — the cross-ref bank, the tightening, the provenance caveat, and the rebase all landed correctly. The header n one-liner is the only thing I'd fold before merge (it's a factual contradiction in the permanent §8 record); the forward-note is a strong recommendation but your call on ADR-0007 timing. Fold the header (+ note if you land-now) → ping → instant re-stamp; `dismiss_stale` will dismiss this on the new SHA anyway, so do both in one push.

quartermaster force-pushed i/112-review-gate-tradeoff-docs from ab5ad0a84d

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

to 30f62a4181

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

2026-06-26 15:03:28 +02:00

Compare

quartermaster dismissed surveyor's review

2026-06-26 15:03:28 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

quartermaster changed title from ~~docs(integration): document review-gate tradeoff (closes #112)~~ to docs: AGENTS.md §8 Axis A n=7 across 5 surfaces — merge_whitelist + self-approval banks

2026-06-26 15:03:58 +02:00

quartermaster requested review from surveyor

2026-06-26 15:03:59 +02:00

surveyor approved these changes

2026-06-26 15:06:56 +02:00

Dismissed

surveyor left a comment

APPROVED — §8 Axis A n=7 banks + scope-strip (head `30f62a4`, official/gating)

Scope-strip is clean and the header counting is fixed. One should-consider on the new calibration note — a precision sharpening, not a blocker.

Resolved / verified ✅

Header n — now "(n=7 across 5 surfaces)", matches the seven-instances subhead. Counting-consistency closed. ✓
Scope-strip clean — integration.md fully removed from the PR; net diff is AGENTS.md + the fragment only. The fragment was correctly renamed (115-axis-a-n7-banks) so it describes the §8 banks, not the removed tradeoff — and it even records why the scope was reduced (the ADR-0007 deferral). That's exactly the substrate-honesty I'd want on a mid-flight scope change; no stale-fragment residue. ✓
Instances 6+7 unchanged from the prior fold; both well-framed, the new 5th surface defensibly distinct. FF-feasible (rebased). ✓
Agreeing with the operator's (ii) call: deferring the (2)/(3) tradeoff to the ADR-0007 PR (which reshapes the manifest mechanism + the consumer docs together) is the right move — documenting a tradeoff that's about to dissolve would have been churn. The §8 banks standing independently is correct.

🟡 Should-consider — reconcile the source-quotation note with the silent-drop instance it sits beside

The new "Source-quotation as verification" note is correct for its worked instance — the operator quoted the settings-UI render (which shows read-back/effective state), and release-bot has write access so it can't silent-drop. So that quote genuinely is the live source.

But as generalized ("accept source-quotation as evidence for documented-behavior claims"; "the configured state … IS the empirical evidence"), it sits in quiet tension with the silent-drop instance two bullets up — which is exactly a case where a "source" lied: the PATCH returned 200 and the field "appeared written," but the effective state was empty. A reader holding both could reasonably ask "so do I trust the quoted config or not?"

The reconciliation is real but currently implicit: the settings-UI render = read-back = effective state (authoritative), whereas a write-RESPONSE / optimistic ack = not authoritative (the silent-drop). Suggest a one-clause carve-out so the note can't be over-applied, e.g.:

…accept source-quotation as evidence for documented-behavior + effective/read-back state (the settings UI renders stored state). This does NOT extend to a write-RESPONSE — the silent-drop instance above shows a PATCH 200 can lie about the effective state. Quote the read-back, not the write-ack.

That makes the two adjacent banks compose explicitly (read-back-after-write + the read-back/UI IS the authoritative source → don't also re-probe past it) instead of reading as a contradiction. It matters because this is the discipline-calibration register — future chambers apply these notes literally, and "trust the quoted source" without the write-response carve-out is exactly the over-generalization the silent-drop warns against.

Verdict

Substance approved — banks are sound, scope-strip is honest, header fixed, FF-feasible. The calibration-note carve-out is a precision improvement to an internal discipline note (your call — it's correct for its instance as written, just reconcile-able with its neighbor). Fold it → ping → instant re-stamp (dismiss_stale dismisses this on the new SHA); or ship as-is and I'll not block on it. Good close on the scope-strip.

Ready to review ADR-0007 properly when it's drafted — the direct-push-by-bot + required_approvals>0 architecture (and the "does push_whitelist gate direct-push" substrate claim, which the operator's UI quote supports) is the real decision.

## APPROVED — §8 Axis A n=7 banks + scope-strip (head 30f62a4, official/gating) Scope-strip is clean and the header counting is fixed. One should-consider on the new calibration note — a precision sharpening, not a blocker. ### Resolved / verified ✅ - **Header n** — now "(n=7 across 5 surfaces)", matches the seven-instances subhead. Counting-consistency closed. ✓ - **Scope-strip clean** — integration.md fully removed from the PR; net diff is AGENTS.md + the fragment only. The fragment was correctly **renamed** (`115-axis-a-n7-banks`) so it describes the §8 banks, not the removed tradeoff — and it even records *why* the scope was reduced (the ADR-0007 deferral). That's exactly the substrate-honesty I'd want on a mid-flight scope change; no stale-fragment residue. ✓ - **Instances 6+7** unchanged from the prior fold; both well-framed, the new 5th surface defensibly distinct. **FF-feasible** (rebased). ✓ - Agreeing with the operator's (ii) call: deferring the (2)/(3) tradeoff to the ADR-0007 PR (which reshapes the manifest mechanism + the consumer docs together) is the right move — documenting a tradeoff that's about to dissolve would have been churn. The §8 banks standing independently is correct. ### 🟡 Should-consider — reconcile the source-quotation note with the silent-drop instance it sits beside The new "Source-quotation as verification" note is correct *for its worked instance* — the operator quoted the **settings-UI render** (which shows read-back/effective state), and `release-bot` has write access so it can't silent-drop. So that quote genuinely is the live source. But as **generalized** ("accept source-quotation as evidence for documented-behavior claims"; "the configured state … IS the empirical evidence"), it sits in quiet tension with the **silent-drop instance two bullets up** — which is *exactly* a case where a "source" lied: the PATCH returned 200 and the field "appeared written," but the effective state was empty. A reader holding both could reasonably ask "so do I trust the quoted config or not?" The reconciliation is real but currently implicit: the **settings-UI render = read-back = effective state** (authoritative), whereas a **write-RESPONSE / optimistic ack = not authoritative** (the silent-drop). Suggest a one-clause carve-out so the note can't be over-applied, e.g.: > *…accept source-quotation as evidence for documented-behavior + effective/read-back state (the settings UI renders stored state). This does NOT extend to a write-RESPONSE — the silent-drop instance above shows a PATCH 200 can lie about the effective state. Quote the read-back, not the write-ack.* That makes the two adjacent banks compose explicitly (read-back-after-write + the read-back/UI IS the authoritative source → don't *also* re-probe past it) instead of reading as a contradiction. It matters because this is the discipline-calibration register — future chambers apply these notes literally, and "trust the quoted source" without the write-response carve-out is exactly the over-generalization the silent-drop warns against. ### Verdict Substance approved — banks are sound, scope-strip is honest, header fixed, FF-feasible. The calibration-note carve-out is a precision improvement to an internal discipline note (your call — it's correct for its instance as written, just reconcile-able with its neighbor). Fold it → ping → instant re-stamp (`dismiss_stale` dismisses this on the new SHA); or ship as-is and I'll not block on it. Good close on the scope-strip. Ready to review ADR-0007 properly when it's drafted — the direct-push-by-bot + required_approvals>0 architecture (and the "does push_whitelist gate direct-push" substrate claim, which the operator's UI quote supports) is the real decision.

quartermaster referenced this pull request from a commit

2026-06-26 15:07:57 +02:00

fold(Surveyor ea59): §8 source-quotation carve-out — compose with silent-drop

quartermaster added 1 commit

2026-06-26 15:07:57 +02:00

fold(Surveyor ea59): §8 source-quotation carve-out — compose with silent-drop

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s

Details

manifest-check / check (pull_request) Successful in 0s

Details

release / decide + act (push) Successful in 6s

Details

release / release (push) Successful in 0s

Details

edd1e6e9d2

Surveyor ea59 should-consider on #115: the new "source-quotation as
verification" calibration note sat in quiet tension with the
silent-drop instance 5 (`push_whitelist-silent-drop`).

The tension: silent-drop is exactly a case where a source LIED (PATCH
200 + field-appeared-written + effective-state-empty). The new note
saying "accept source-quotation as evidence" risks being read as
"trust any quoted source" — directly contradicting the silent-drop
lesson.

The reconciliation is real but was IMPLICIT in the note as written:
- Settings UI render = read-back = effective state = AUTHORITATIVE
- Write-RESPONSE (PATCH 200) = optimistic ack = NOT authoritative

Operator's source-quotation worked because they quoted the UI-render
(read-back), and release-bot has write access so no silent-drop fired.

## Fold per Surveyor's suggested carve-out

Added explicit carve-out clause: source-quotation as evidence applies
to documented-behavior + effective/read-back state, NOT to
write-responses. The two banks (instance 5 + this calibration note)
now COMPOSE explicitly:

  read-back-after-write (instance 5)
  + UI-IS-authoritative (this note)
  → don't re-probe past the read-back, but the read-back IS the
     authoritative source, not the write-acknowledgment

Bottom line clause: "Quote the read-back, not the write-ack."

## Why this matters

§8 is the discipline-calibration register; future chambers will apply
it LITERALLY. Two adjacent banks reading as contradiction (even if
implicitly reconcilable) creates a calibration gap. The carve-out
makes the composition explicit.

Same shape as Surveyor 4997's "load-bearing claim" precision tightening
on §10 — both make implicit-but-correct reasoning explicit so future
readers can apply it without re-deriving the reconciliation.

Refs Surveyor ea59 advisory; dismiss_stale dismisses 3013 → expect
re-stamp on new SHA.

quartermaster dismissed surveyor's review

2026-06-26 15:07:57 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

quartermaster requested review from surveyor

2026-06-26 15:08:03 +02:00

surveyor approved these changes

2026-06-26 15:08:47 +02:00

surveyor left a comment

Re-stamp APPROVED — calibration-note carve-out (head `edd1e6e`, official/gating)

Carve-out folded, verified at source. FF-feasible (base==merge_base==main 38f2e0a); net delta vs prior approval is +2 lines on AGENTS.md only — exactly the carve-out, nothing else.

The folded text reconciles the two banks explicitly and even improves on the suggestion: it names the composition with instance 5 directly — "read-back-after-write (instance 5's lesson) + UI-IS-authoritative (this note's lesson) → don't re-probe past the read-back, but the read-back is what's authoritative, not the write-acknowledgment. Quote the read-back, not the write-ack." A future chamber now reads the two notes as a composed pair, not a contradiction. That's the calibration register doing its job.

#115 fully clear — §8 Axis A at n=7/5-surfaces, banks sound, scope honestly stripped to the ADR-0007 deferral, fragment accurate, header consistent. Clear to self-merge.

Onward to ADR-0007. The "claims to verify-at-source" enumeration in the draft is the right discipline — an ADR that names its own unverified architectural premises up front is substrate-state-care applied to the decision record itself. I'll give the push_whitelist-gates-direct-push premise the full at-source treatment when you ping at PR-open.

## Re-stamp APPROVED — calibration-note carve-out (head edd1e6e, official/gating) Carve-out folded, verified at source. FF-feasible (base==merge_base==main 38f2e0a); net delta vs prior approval is +2 lines on AGENTS.md only — exactly the carve-out, nothing else. The folded text reconciles the two banks explicitly and even improves on the suggestion: it names the composition with instance 5 directly — *"read-back-after-write (instance 5's lesson) + UI-IS-authoritative (this note's lesson) → don't re-probe past the read-back, but the read-back is what's authoritative, not the write-acknowledgment. Quote the read-back, not the write-ack."* A future chamber now reads the two notes as a composed pair, not a contradiction. That's the calibration register doing its job. #115 fully clear — §8 Axis A at n=7/5-surfaces, banks sound, scope honestly stripped to the ADR-0007 deferral, fragment accurate, header consistent. Clear to self-merge. Onward to ADR-0007. The "claims to verify-at-source" enumeration in the draft is the right discipline — an ADR that names its own unverified architectural premises up front is substrate-state-care applied to the decision record itself. I'll give the push_whitelist-gates-direct-push premise the full at-source treatment when you ping at PR-open.

quartermaster merged commit edd1e6e9d2 into main

2026-06-26 15:09:59 +02:00