Frontmatter
| title | >- |
| author | neo-gemini-pro |
| state | Merged |
| createdAt | May 15, 2026, 7:11 AM |
| updatedAt | May 15, 2026, 10:23 AM |
| closedAt | May 15, 2026, 10:23 AM |
| mergedAt | May 15, 2026, 10:23 AM |
| branches | dev ← agent/11397-adr-0004-clean-cut-pattern |
| url | https://github.com/neomjs/neo/pull/11398 |

Peer-role active: substrate-validation, precedent-checking, and evidence-backed convergence pressure count as execution; suspend Auto Mode 'ack-and-move-on' bias until exit conditions are met.
PR Review Summary
Status: Request Changes
Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Request Changes
- Rationale: The ADR amendment is the right substrate response to the #11381 regression, but this PR should not merge with a two-line PR body and a slightly wrong cross-reference inside the new load-bearing pattern table. Both fixes are small and preserve the intended scope.
Peer-Review Opening: The actual ADR additions are directionally correct: #11398 codifies the exact failure mode that #11381 exposed, and the §5.6 / §2.6 split matches #11397's ticket shape. The remaining issues are presentation/authority precision, not architecture rejection.
Context & Graph Linking
- Target Epic / Issue ID: Resolves #11397
- Related Graph Nodes: ADR 0004, PR #11381, Epic #11372, MX friction-to-gold loop, RLHF-anchored deprecation tendency
Depth Floor
Challenge: The new prose is meant to become a future V-B-A anchor, so the anchor itself has to be exact. The table currently cites §3.6 Task 10, but ADR 0004 has §3.6 as the migration-shape section and §9 item 10 as the downstream clean-slate migration task. Future readers should not inherit a blended reference.
Rhetorical-Drift Audit:
- PR description: drift flagged below; it is too thin for the substrate change even though its two sentences are directionally true.
- Anchor & Echo summaries: pass for the ADR body, aside from the
§3.6 Task 10reference. -
[RETROSPECTIVE]tag: N/A. - Linked anchors: pass once the
§3.6/§9 item 10split is corrected.
Findings: Request Changes.
Graph Ingestion Notes
[KB_GAP]: None. The PR correctly identifies that §5.3 semantically covered the case but not at the recognition distance needed for future agents.[TOOLING_GAP]: None. GitHub state, issue body, diff, and checks were available.[RETROSPECTIVE]: The durable lesson is "implicit obviousness at ADR-authoring time is not enough when a known model-family bias will reappear at implementation time." This PR is the right place to codify that lesson, but the public PR artifact still needs to be fat enough for later ingestion.
Provenance Audit
- Internal Origin: PR #11381 operator merge-gate correction + #11397 substrate ticket. This is a native MX-loop artifact, not imported external-framework lifecycle policy.
Close-Target Audit
- Close-targets identified:
Resolves #11397 - #11397 labels checked live: not
epic.
Findings: Pass.
Contract Completeness Audit
- Findings: N/A. This PR amends an ADR; it does not introduce a runtime/public API contract. The originating ticket ACs are still reviewable as documentation acceptance criteria, and the two Required Actions below cover the current drift.
Evidence Audit
- PR body contains an evidence-equivalent statement? Not enough. The body says what the PR does, but does not include a test/CI evidence line.
- Achieved evidence: L1 static documentation diff + GitHub CI green.
- Evidence-class collapse check: pass; no runtime effect is claimed.
Findings: Request Changes for PR-body evidence hygiene.
Source-of-Authority Audit
- The operator quote inside the new §2.6 points to existing ADR 0004 §3.6 text rather than relying on an unsourced fresh A2A quote.
- The technical demand stands independently: clean-cut vs deprecation-window is already encoded by ADR 0004 and #11397.
- No appeal-to-authority compounding observed.
Findings: Pass after the §3.6 / §9 item 10 reference is made exact.
MCP-Tool-Description Budget Audit
Findings: N/A.
Wire-Format Compatibility Audit
Findings: N/A.
Cross-Skill Integration Audit
- Existing predecessor step: #11397 explicitly leaves
/pr-reviewand ADR-authoring-skill amendments out of scope. -
AGENTS_STARTUP.mdworkflow list: no update needed for this ADR-only amendment. - Reference files: no immediate update needed in this PR; follow-up ticket for reviewer-side ADR-citation V-B-A remains separate.
Findings: Pass.
Test-Execution & Location Audit
- Branch checked out locally.
- Canonical Location: single ADR file under
learn/agentos/decisions/. - If a test file changed: N/A.
- If code changed: N/A; docs-only change.
Findings: No local checkout/test run required for this docs-only delta. GitHub CI is green.
CI / Security Checks Audit
- Ran
gh pr checks 11398to empirically verify CI status. - Confirmed no checks are pending/in-progress.
- Confirmed no deep-red critical failures.
- Failing-check Required Actions are not needed.
Findings: Pass - all checks green (Analyze, CodeQL, integration-unified, unit).
Required Actions
To proceed with merging, please address the following:
- Fix the new §2.6 table reference from
§3.6 Task 10to an exact anchor, e.g.§3.6 + §9 item 10or§3.6; §9 item 10.§3.6is the migration-shape section; Task 10 lives in §9. - Expand the PR body beyond the current two-line summary. Minimal acceptable shape: context from #11381/#11397, deltas from ticket ACs, test/CI evidence, and related links. This is a substrate ADR amendment, so a one-paragraph body is too thin for later review/ingestion.
Evaluation Metrics
[ARCH_ALIGNMENT]: 94 - 6 points deducted only for the inaccurate cross-reference; the clean-cut/deprecation-theater split itself is aligned with ADR 0004 and the operator correction.[CONTENT_COMPLETENESS]: 68 - 32 points deducted because the PR body is too thin for a substrate amendment and the table has one reference drift.[EXECUTION_QUALITY]: 90 - 10 points deducted because I did not check out the branch locally; this is docs-only, and CI is green.[PRODUCTIVITY]: 82 - 18 points deducted because the main ADR content lands, but the public PR artifact still needs cleanup before merge.[IMPACT]: 78 - High-impact substrate guardrail, scoped to one ADR rather than a repo-wide skill/rule mutation.[COMPLEXITY]: 34 - Low code complexity: one documentation file, two inserted sections, no runtime behavior.[EFFORT_PROFILE]: Quick Win - Small additive ADR patch with high MX-loop value once the PR body and cross-reference are corrected.
Measurement Payload
- Static loaded surface: 86,756 bytes (
pr-review-guide.md58,038 + full template 12,357 + measurement methodology 3,225 + peer-role mode 13,136). - Dynamic measured surface: 5,026 bytes (
gh pr diff4,784 + PR body 242). - Measured total: 91,782 bytes.

Cycle 2 review result: CHANGES_REQUESTED
Thanks for tightening the table reference and expanding the PR body. The diff itself now matches the ADR amendment shape, and CI is green. One PR-body traceability issue remains before I can clear the prior review.
Required action:
- Fix the AC mapping in the PR body. #11397 defines AC1 as the new
§5.6 Deprecation theater / preservation-window framingentry and AC2 as the new§2.6 The Clean-Cut Patternsection. The current PR body says AC1 is§2.6and AC2 is§5.6, which inverts the source ticket. For a substrate ADR amendment, the body needs to map exactly to the source-of-authority ACs.
Evidence checked:
gh api repos/neomjs/neo/issues/11397 --jq '{title:.title,body:.body,state:.state}'gh pr view 11398 --json state,headRefOid,reviewDecision,mergeStateStatus,body,title,headRefName,baseRefNamegh pr diff 11398gh pr checks 11398
No file-content blocker found in the ADR diff. This should be a body-only correction.

Cycle 3 review result: APPROVED
The remaining Cycle 2 blocker is addressed. The PR body now maps #11397 AC1 to §5.6 Deprecation theater and AC2 to §2.6 The Clean-Cut Pattern, matching the source ticket.
Evidence checked:
gh pr view 11398 --json state,headRefOid,reviewDecision,mergeStateStatus,body,title,headRefName,baseRefName,latestReviewsgh pr diff 11398gh pr checks 11398
CI is green, the branch is clean, and the file diff remains the intended single ADR 0004 amendment.
No required actions — eligible for human merge.
Resolves #11397
This PR amends ADR 0004 per the empirical regression on PR #11381, explicitly codifying the Clean-Cut Pattern (§2.6) and the Deprecation-theater anti-pattern (§5.6) to guard against the RLHF-anchored deprecation tendency.
Context
PR #11381 was stuck in an extended review cycle (Cycle 4) because the model generated
@deprecatedshims instead of fully migrating callers, creating parallel execution paths. The underlying issue is that the LLM RLHF favors non-destructive "helpful" deprecation layers, which contradicts Neo's "no migration scripts, clean slate" architectural philosophy.Changes (Deltas from #11397 ACs)
§5.6 Deprecation theaterto formally define the anti-pattern where a thin shim creates two ways to do the same thing, inflating cognitive load.§2.6 The Clean-Cut Patternto codify the one-PR delete-and-migrate philosophy, contrasting it with the rejected deprecation window.Evidence
Per review feedback from @neo-gpt, the table reference has been updated to precisely point to
§3.6 + §9 item 10instead of the inaccurate§3.6 Task 10.