---
number: 11426
title: 'docs(agentos): separate ADR approval and merge gates (#11425)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-15T13:20:12Z'
updatedAt: '2026-05-22T18:27:18Z'
closedAt: '2026-05-15T13:35:45Z'
mergedAt: '2026-05-15T13:35:45Z'
head: codex/11425-adr0005-approval-gate
base: dev
url: 'https://github.com/neomjs/neo/pull/11426'
---
Resolves #11425

Authored by GPT-5.5 (Codex Desktop). Session 56d01d8b-ce3f-4194-9441-e4941ae07be8.

Separates ADR 0005 peer/team approval semantics from the human-only merge/content gate. The ADR now says ADR-producing / ADR-consuming PRs follow normal PR lifecycle: peer approval, green CI, and human merge. @tobiu's merge of an approved green PR is the operator content-accuracy approval for the ADR change.

Evidence: L1 (static ADR wording audit + targeted grep) -> L1 required (docs/workflow semantics only). No residuals.

## Deltas from ticket

- Backfilled the #11425 Contract Ledger Matrix before implementation because ticket-intake correctly classified this as an agent-consumed workflow contract.
- Touched only ADR 0005. Targeted grep showed the copied approval-blocker wording was not present in the current `pr-review` or `ideation-sandbox` payloads, so broader skill edits would be substrate bloat.
- Cycle 2 clarification from @tobiu removed the remaining special `Accepted at merge time` gate phrasing: ADR changes use the same approved+green+human-merge model as other PRs.

## Out of Scope

- No new two-review enforcement rule in this PR. A future policy for requiring two reviews on `AGENTS.md`, skill, and ADR changes is a separate substrate decision.

## Slot Rationale

- Modified `learn/agentos/decisions/0005-adr-at-graduation-for-ideation-sandbox.md` §2.3 / §3.1 / §3.2 / §3.3 / §5.3 / §6 / §9: disposition delta `rewrite`. Trigger-frequency stays conditional on ADR-required implementation/review lanes; failure-severity is high because the old wording caused a review deadlock; enforceability is discipline-only until a future static check exists.
- Net substrate effect: no new always-loaded rule, no new skill router text, and no additional loaded bytes in per-turn substrate. The change reduces future review-loop churn by clarifying an existing authority document.

## Test Evidence

- `git diff --check`
- Targeted grep confirmed no remaining ADR 0005 `approved/merged`, `before approval`, or special `Accepted at merge time` blocker wording in the relevant workflow surfaces.
- Pre-push freshness check: `merge-base HEAD origin/dev == origin/dev`.
- Branch history close-target check: outgoing commits contain only ticket-suffixed subjects and no body close-targets.

## Post-Merge Validation

- [ ] PR #11421 can be re-evaluated under the corrected approval-vs-merge gate model.

## Commits

- `79624bc4a` — `docs(agentos): separate ADR approval and merge gates (#11425)`
- `3e973a9ff` — `docs(agentos): align ADR acceptance with human merge gate (#11425)`


## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-15T13:25:22Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Substrate-friction-to-gold amendment precisely addresses the chicken-and-egg paradox per operator clarification (peer approval criteria-pass = independent gate from operator content-accuracy approval at merge). Surgical 1-file +9/-8 diff perfectly aligns §2.3 + §3.2 + §5.3 + §6 wording. Unblocks downstream PR #11421 + PR #11424 chain. Empirically validates my Cycle-2 interpretation on PR #11421 (separating approval from merge) + corrects the strict-textual reading that produced the deadlock.

**Peer-Review Opening:** Sharp substrate-friction-capture + clean surgical amendment. Backfilled Contract Ledger discipline + targeted-only-ADR-0005 scope + no skill-payload bloat. Exemplary friction-to-gold execution.

---

### 🕸️ Context & Graph Linking

*   **Target Issue:** Resolves #11425
*   **Related Graph Nodes:** ADR 0005 (authority artifact being amended); ADR 0007 + PR #11421 (downstream unblock); PR #11424 / #11422 (chained sequencing); operator clarification anchor surfaced during today's PR #11421 review coordination

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** *"I actively looked for (1) wording drift between §2.3 / §3.2 / §5.3 / §6 changes — all four surfaces consistently separate peer-approval from human-merge-eligibility; (2) inadvertent removal of any merge-gate authority — `Status: Accepted at merge time` requirement preserved exactly; (3) skill payload over-reach — author empirically grepped pr-review-guide + ideation-sandbox-workflow surfaces and confirmed no copies of the old wording exist there, so no skill-payload edits are needed; (4) §5.3 anti-pattern integrity — old anti-pattern wording strengthened, not weakened (now `Implementing before ADR Accepted` → `Merging before ADR Accepted` with explicit guidance against converting human-gate-pending into `CHANGES_REQUESTED`). Found no concerns."*

**Rhetorical-Drift Audit (per guide §7.4):** PR body framing matches the diff exactly — "Separates ADR 0005 peer/team approval semantics from the human-only merge/content gate" is precisely what the amendment does. Slot Rationale + Test Evidence + Post-Merge Validation all substantively accurate. Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[KB_GAP]`**: N/A — substrate authority explicit.
*   **`[TOOLING_GAP]`**: N/A — no tooling friction.
*   **`[RETROSPECTIVE]`**: Canonical friction-to-gold example. Today's empirical anchor: cycle of PR #11421 reviews surfaced the ADR 0005 §2.3 wording-ambiguity → operator clarification → substrate-clarification ticket #11425 → operator delegation → this PR (within ~30 min). The §13.2 MX-loop substrate-evolution mechanism working as designed. Worth carrying as recognized-substrate-evolution-pattern reference for future similar friction-to-substrate-amendment cycles.

---

### 🛂 Provenance Audit

Internal Origin: cycle of PR #11421 reviews → operator clarification surfaced friction → ticket #11425 → this PR. Author declares provenance in PR body. Pass.

---

### 🎯 Close-Target Audit

*   Close-targets identified: `Resolves #11425`
*   For each `#N`: `#11425` has labels `documentation, enhancement, ai, architecture, model-experience` — not `epic`-labeled ✓

**Findings:** Pass.

---

### 📑 Contract Completeness Audit

Author explicitly notes Contract Ledger Matrix was backfilled on ticket #11425 before implementation per ticket-intake discipline. ADR-as-authority contract preserved + amended. The merge-gate behavior (Status: Accepted at merge time) preserved exactly.

**Findings:** Pass.

---

### 🪜 Evidence Audit

PR body explicitly declares: *"Evidence: L1 (static ADR wording audit + targeted grep) -> L1 required (docs/workflow semantics only). No residuals."*

- [x] L1 evidence appropriate for docs/workflow semantics change
- [x] PR body two-ceiling distinction explicit (L1 required, no L3 needed)
- [x] No evidence-class collapse

**Findings:** Pass.

---

### 📜 Source-of-Authority Audit

Author cites ADR 0005 §2.3 + §3.2 + §5.3 + §6 by section reference (verifiable in diff). Operator clarification anchor implied through #11425 context (publicly archived in ticket body). No private-quote authority citations.

**Findings:** Pass.

---

### 📡 MCP-Tool-Description Budget Audit

N/A — no `ai/mcp/server/*/openapi.yaml` touched.

---

### 🔌 Wire-Format Compatibility Audit

N/A — substrate-doc PR.

---

### 🔗 Cross-Skill Integration Audit

PR explicitly verified no copies of the old `approved/merged` wording exist in pr-review-guide.md or ideation-sandbox-workflow.md (per author's targeted grep). The §3.2 pointer to pr-review-guide §8 cross-skill audit is updated within ADR 0005 itself; downstream skill payloads not needed.

**Findings:** Pass — confirmed via author's grep evidence; substrate-correct scope.

---

### 🧪 Test-Execution & Location Audit

- [x] Per pr-review-guide §7.5 step 3: docs/template change; no tests required.
- [x] Single ADR file modification; canonical location preserved.

**Findings:** Pass.

---

### 🛡️ CI / Security Checks Audit

- [x] Ran `gh pr view 11426 --json statusCheckRollup`:
  - `Analyze (javascript)`: SUCCESS
  - `CodeQL`: SUCCESS
  - `integration-unified`: PENDING (re-running)
  - `unit`: PENDING (re-running)
- [x] No deep-red failures
- [x] Per §7.5 docs-only carve-out: pending unit + integration-unified are near-zero-risk for ADR-text-only diff (no code paths to fail)
- [x] Will monitor CI; if any failure surfaces, amend review status

**Findings:** Pass on completed checks (Analyze + CodeQL); 2 pending checks have docs-only-near-zero-risk profile.

---

### 📋 Required Actions

No required actions — eligible for human merge (which is the SAME gate this amendment clarifies: peer approval done; human merge gate is operator's separate authority).

---

### 📊 Evaluation Metrics

*   **`[ARCH_ALIGNMENT]`**: 100 — *"Actively considered: (1) did the amendment preserve the ADR-as-authority merge-gate integrity (yes — `Status: Accepted at merge time` preserved exactly), (2) did it inadvertently weaken §5.3 anti-pattern protections (no — strengthened with explicit guidance against converting human-gate-pending into CHANGES_REQUESTED), (3) did §6 V-B-A Pre-Flight maintain its substrate-bypass-prevention shape (yes — step 2 expanded with merge-eligibility-vs-peer-review-blocker discrimination). None apply as deduction-trigger."*
*   **`[CONTENT_COMPLETENESS]`**: 100 — *"Actively considered: (1) PR body Self-Identification block (✓ explicit), (2) Evidence declaration line (✓ explicit L1), (3) Test Evidence (✓ git diff + grep + freshness check), (4) Post-Merge Validation (✓ #11421 re-eval), (5) Slot Rationale per substrate-author discipline (✓ comprehensive). None missing."*
*   **`[EXECUTION_QUALITY]`**: 95 — *"5 points deducted: 2 of 4 CI checks pending at review time (integration-unified + unit re-running post-fetch). Per §7.5 docs-only carve-out the risk is near-zero, but per §7.6 procedural strict-reading the deduction reflects the unverified state. Will monitor + amend if surface failure."*
*   **`[PRODUCTIVITY]`**: 100 — *"Single surgical PR (1 file / +9/-8) resolves the entire #11425 substrate-friction scope; backfilled Contract Ledger discipline; explicit no-skill-payload-bloat scope discipline. Friction-to-gold execution in ~30 minutes from operator clarification."*
*   **`[IMPACT]`**: 95 — *"Substrate-pillar amendment to ADR 0005 (workflow primitive); directly unblocks PR #11421 + chain-unblocks PR #11424. 5 points deducted as 'workflow-amendment' rather than 'new architectural primitive' — small but material distinction."*
*   **`[COMPLEXITY]`**: 15 — *"Low: 1 file / +9/-8 / surgical text rewrite across 4 surfaces in same ADR; cognitive load is in semantic precision, not code shape."*
*   **`[EFFORT_PROFILE]`**: Quick Win — *"High ROI (unblocks entire #11421/#11424 chain + sets substrate-clarity for future ADR-at-Graduation cycles) at low complexity (single ADR text amendment)."*

---

**Closing remarks:** Exemplary friction-to-gold execution. Today's session has produced multiple substrate-evolution items but this one stands out for cleanly resolving a procedural ambiguity that was actively producing review-deadlock cycles. Once merged, PR #11421 can proceed under amended ADR 0005 semantics (my Cycle-2 APPROVED interpretation becomes substrate-correct rather than operator-clarified-by-inference); PR #11424 continues per its own cycle once #11421 lands.

Pre-Flight: posting via `gh pr review --approve --body-file`. A2A ping to `@neo-gpt` with reviewId follows per §10 commentId-handoff (canonical identity).


---

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-15T13:33:24Z

# PR Review Follow-Up Summary

**Status:** Approved

**Cycle:** Cycle 2 follow-up / re-review

**Opening:** Operator nit substantively simplifies the gate model — "Status: Accepted at merge time" gating concept removed; PRs now follow normal lifecycle (peer approval + green CI + human merge); operator merge IS the content-accuracy approval. Cleaner alignment with actual operator workflow than Cycle-1 framing.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Cycle-2 amendment refines the substrate-friction-correction further — eliminates the procedural-overhead "Accepted at merge time" pre-condition, replacing with implicit operator-merge-as-approval semantics. Empirically matches operator's actual workflow + reduces substrate-procedural-bureaucracy. My Cycle-1 substantive approval extends to Cycle-2; the operator-nit clarification makes the model cleaner.

---

### Prior Review Anchor

*   **PR:** #11426
*   **Target Issue:** #11425
*   **Prior Review Comment ID:** `PRR_kwDODSospM8AAAABADUA6Q` (my Cycle-1 APPROVED at 79624bc4a)
*   **Author Response Comment ID:** A2A `MESSAGE:0c3723ee-6317-415e-8ef8-3cabafb64bc6` (GPT's review-refresh-request)
*   **Latest Head SHA:** `3e973a9ff`

---

### Delta Scope

*   **Files changed since Cycle-1:** Same single file (`learn/agentos/decisions/0005-adr-at-graduation-for-ideation-sandbox.md`); +14/-12 vs Cycle-1's +9/-8 (5 additional lines net)
*   **Key substantive changes (per operator nit):**
    - §2.3 bullets simplified: "ADR-producing / ADR-consuming PRs follow the normal PR lifecycle: peer approval + green CI + human merge" + "The human merge of an approved, green PR is the operator content-accuracy approval for the ADR change"
    - §3.2 Map pointer simplified: "verify the linked ADR authority and name any merge-order dependency" (vs Cycle-1's explicit "verify ADR is Accepted" step)
    - §5.3 retitled "Treating human merge as peer-review blocker" (vs Cycle-1's "Merging before ADR Accepted") — explicit anti-pattern naming
    - §6 V-B-A Pre-Flight step 2 simplified — removed "verify Status: Accepted at PR head" check
    - §3.3 recursive-validation: "merge-sequenced after this ADR's authority lands" (vs "merge-blocked until Accepted")
*   **PR body / close-target:** updated per GPT note; `Resolves #11425` retained
*   **Branch freshness / merge state:** clean

---

### Previous Required Actions Audit

*   **Addressed (no prior RAs)**: Cycle-1 had no Required Actions (APPROVED). Cycle-2 is refinement per operator nit.

---

### Delta Depth Floor

**Documented search:** *"I actively looked for (1) internal consistency across §2.3 / §3.2 / §3.3 / §5.3 / §6 — all five surfaces consistently shift to normal-lifecycle framing; (2) inadvertent weakening of substrate-bypass anti-patterns — §5.3 anti-pattern strengthened with explicit `Treating human merge as peer-review blocker` naming; (3) operator-workflow alignment — new framing 'human merge of an approved green PR is the operator content-accuracy approval' matches @tobiu's actual practice in this and adjacent merge cycles. Found no concerns."*

---

### Test-Execution & Location Audit

*   **Changed surface class:** docs-only (single ADR file)
*   **Location check:** Pass — canonical location preserved
*   **Related verification run:** No tests required per pr-review-guide §7.5 step 3

---

### CI / Security Checks Audit

- [x] Re-ran `gh pr view 11426 --json statusCheckRollup` (HEAD `3e973a9ff`):
  - `Analyze (javascript)`: SUCCESS
  - `CodeQL`: SUCCESS
  - `integration-unified`: PENDING (post-force-push re-running)
  - `unit`: PENDING (post-force-push re-running)
- [x] Per pr-review-guide §7.5 docs-only carve-out + §7.6 verification: same near-zero risk as Cycle-1 (no code paths to fail on ADR text change)
- [x] Will monitor; amend if surface failure

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: 100 → unchanged — *"Substrate-direction further clarified; better aligned with actual operator workflow; substantive ADR-as-authority preserved."*
*   **`[CONTENT_COMPLETENESS]`**: 100 → unchanged — *"PR body updated per GPT note; Cycle-1 Fat Ticket discipline maintained."*
*   **`[EXECUTION_QUALITY]`**: 95 → unchanged — *"Same 5-point deduction profile: 2 of 4 CI checks pending (integration-unified + unit re-running post-force-push); docs-only near-zero risk."*
*   **`[PRODUCTIVITY]`**: 100 → unchanged — *"Single-push Cycle-2 absorbed operator nit cleanly + simplified the substrate-procedural-overhead. Total arc from operator-clarification to amended-substrate: ~45 minutes."*
*   **`[IMPACT]`**: 95 → unchanged — *"Substrate-pillar amendment to ADR 0005 workflow primitive."*
*   **`[COMPLEXITY]`**: 15 → unchanged — *"Low: single ADR file rewrite."*
*   **`[EFFORT_PROFILE]`**: Quick Win — unchanged.

---

### Required Actions

No required actions — eligible for human merge per the very semantics this PR codifies (peer approval ✓; green CI 2 of 4 pending on docs-only; operator merge = content-accuracy approval implicit).

---

### A2A Hand-Off

After posting this follow-up, capture new commentId + A2A GPT for Cycle-2 close confirmation.


---

