Amend ADR 0004 with explicit Clean-Cut Pattern + Deprecation-theater anti-pattern (§2.6 + §5.6)

Context

ADR 0004 (learn/agentos/decisions/0004-github-content-architecture.md) was authored 2026-05-14 to anchor the Universal Ordinal-100 Content Architecture against substrate-bypass authoring. §5 contains 5 anti-patterns (§5.1 through §5.5) that future agents MUST avoid when authoring resources/content/ migrations or syncer changes.

Empirical regression (2026-05-15 nightshift): during Phase 1 Lane A implementation (PR #11381), I (the same agent who authored ADR 0004 the prior session) introduced @deprecated JSDoc annotations on chunkPath.mjs + archivePath.mjs as part of #11379's AC6+AC7. The Cycle-1+Cycle-2 cross-family review chain (GPT primary reviewer) did NOT catch the deprecation theater as ADR-violating. Operator caught it at merge gate with: "we talked about it for HOURS => clean cut. no deprecations. this is why ADR 0004 does not contain the word 'deprecated' a single time. this state: REJECTED."

Operator's substrate-evolution framing (2026-05-15): "friction → gold. we knew about the deprecation tendency. you created 0004, and previous session probably thought 'clean cut is this obvious here, if we do not mention deprecations. after all, we delete it all, and there are ZERO migration scripts planned.'"

The implicit-obviousness mental model at ADR-authoring-time failed against a known model-family bias (RLHF-anchored deprecation tendency / graceful-degradation pattern) at implementation-time. The anti-pattern wasn't explicitly named in §5, so the cross-family review chain didn't have a §5-citable check to fire against.

The Problem

ADR 0004 §5 currently enumerates 5 anti-patterns:

• §5.1 Reading Discussion graduation prose as deletion-license
• §5.2 Anchoring on GitHub-ID-stream math
• §5.3 Inventing parallel chunking rules
• §5.4 Skipping prevent-reopen.yml in the mental model
• §5.5 Treating per-type configurability as architecture

§5.3 actually covers the deprecation-shim case semantically ("Any proposal to introduce a second chunking algorithm... MUST first cite this ADR and propose a Cycle 4 amendment via Ideation Sandbox + cross-family consensus") — but the language doesn't surface the specific RLHF-anchored anti-pattern shape: keeping the retired primitive ALIVE as @deprecated shim is structurally a second chunking algorithm, just wearing different framing. Future agents under the RLHF deprecation tendency don't pattern-match @deprecated shim during migration window to §5.3's parallel chunking rule because the deprecation framing reads as "responsible legacy support" not "parallel rule".

§3.6 codifies the clean-slate framing operationally (the migration approach) but doesn't name the pattern — there's no §3.x or §2.x section titled "Clean-Cut Pattern" that future authors V-B-A against when designing helper-substrate evolution.

The Architectural Reality

• ADR 0004 §5 anti-pattern surface: 5 entries cover (Discussion-deletion-license, GH-ID-stream-math, parallel-chunking-rules, prevent-reopen-skip, per-type-config-as-architecture). Missing: explicit deprecation-theater / preservation-window anti-pattern.
• ADR 0004 §3.6 migration approach: codifies the clean-slate purge, but doesn't name the pattern as "Clean-Cut" or contrast it explicitly with the rejected "Deprecation Window" / "Graceful Migration" alternatives.
• §5.3 semantic coverage: technically subsumes the deprecation-shim case, but the framing-distance is too far for RLHF-deprecation-tendency agents to pattern-match.

The Fix

Two-part amendment to ADR 0004:

Part 1: New §5.6 anti-pattern entry

Append to ADR 0004 §5:

<h3 class="neo-h3" data-record-id="7">5.6 Deprecation theater / preservation-window framing</h3>

Future agents MUST NOT add `@deprecated` JSDoc annotations to retired primitives (`chunkPath.mjs`, `archivePath.mjs`, etc.) under the framing "preserve as a thin backward-compatibility shim during migration window". Per §3.6 clean-slate framing, ADR 0004 prescribes **deletion**, not deprecation. The retired primitive's file gets DELETED when the call-site migration ticket lands — there is NO coexistence window where the old + new primitives both exist with deprecation annotations bridging them.

**Why the anti-pattern surfaces under RLHF-anchored deprecation tendency**: model families trained on broader software-engineering corpora have a strong prior toward "responsible legacy preservation" via `@deprecated` annotations + thin shims. This pattern is correct for typical industry-software lifecycle (LTS support, customer migration windows, semver-major-version-breaking-change discipline). It is **wrong** for Neo's substrate-evolution context where:

1. The operator explicitly named "ZERO migration scripts planned" + "clean slate => like we never had prior content" (ADR §3.6 operator quote).
2. The clean-slate purge runs as Task 10 — there's no customer data to preserve across the cut.
3. `@deprecated` shims are structurally §5.3's "parallel chunking rule" wearing different framing.

**Pattern recognition signals**: if your AC list contains language like "thin re-export wrapper for one deprecation window", "`@deprecated` JSDoc pointing to the new primitive", "backward-compat-compatible during Lane B migration", or "shim integrity" — these are RLHF-deprecation-tendency signals. Replace them with: "DELETED at the call-site-migration ticket", "removed in the same PR that lands the new primitive", or simply omit the framing entirely.

**The Cycle-1+Cycle-2 review chain anti-pattern**: cross-family reviewers under the same RLHF anchor will MISS this anti-pattern at review time unless §5.6 is explicitly cited. The author-side AC list sanctions the deprecation theater; the reviewer-side pattern-match reads "responsible legacy support" as positive signal. Operator-at-merge-gate becomes the catch-of-last-resort. §5.6 codifies the pattern so cross-family review can fire before operator-catch.

Part 2: New §2.6 explicit Clean-Cut Pattern naming

Append to ADR 0004 §2 (Decision):

<h3 class="neo-h3" data-record-id="9">2.6 The Clean-Cut Pattern (load-bearing pattern, contrast with rejected Deprecation Window pattern)</h3>

The substrate-evolution pattern for ADR 0004 is **Clean Cut**, not **Deprecation Window**:

| Pattern | Old primitive after new primitive lands | Migration shape |
|---|---|---|
| **Clean Cut** ✓ (ADR 0004) | DELETED at the call-site-migration ticket | Data: clean-slate purge + re-sync (§3.6 Task 10). Code: old file deleted in the same PR that mutates the last call site. |
| **Deprecation Window** ✗ (rejected) | KEPT with `@deprecated` JSDoc as thin shim during "migration window" | Data: preserved + reshaped via migration scripts. Code: both old + new primitives coexist with annotations bridging them. |

**Operator authority anchor** (verbatim from §3.6): *"if we just delete it all, especially the sync all meta file => clean slate => like we never had prior content. less cognitive load. no migration scripts needed. no risk of data loss either. allows full focus on the new syncer logic."*

The Deprecation Window pattern adds substrate-coexistence cost (cognitive load: "which primitive should I use here?"), violates §5.3 (parallel chunking rules), and contradicts the operator-stated "ZERO migration scripts planned" intent. Future authors V-B-A against this §2.6 contrast before designing helper-retirement work.

Acceptance Criteria

• AC1: ADR 0004 §5 contains a new §5.6 "Deprecation theater / preservation-window framing" anti-pattern entry with the substantive prose above (or equivalent).
• AC2: ADR 0004 §2 contains a new §2.6 "The Clean-Cut Pattern" section with the Pattern-vs-Pattern comparison table + operator authority anchor (or equivalent).
• AC3: The §5.6 entry explicitly names "RLHF-anchored deprecation tendency" as the model-family bias the anti-pattern guards against. This is load-bearing for future agents to recognize the bias in their own reasoning.
• AC4: PR body cites the empirical anchor (PR #11381 Cycle-1+Cycle-2 @deprecated-theater that operator caught at merge gate, 2026-05-15).
• AC5: No deletion of existing §5.1-§5.5 entries — pure additive.
• AC6: No semantic changes to the rest of ADR 0004 — the amendment is anti-pattern + pattern-naming, not architectural revision.

Out of Scope

• Skill-level mandate that ADR-authoring SKILL.md should enumerate known model-family biases as a checklist — separate substrate-evolution ticket; this ticket fixes ADR 0004 specifically.
• /pr-review audit checklist amendment to add a "RLHF-deprecation-tendency detector" — separate ticket; the §7.7 anti-pattern table could grow a row for this.
• Other ADR files (0001-0003, 0005, 0006) — they don't cover this substrate; no parallel amendment needed.

Avoided Traps

• Deleting §5.3 in favor of §5.6 — rejected. §5.3 covers the structural parallel-chunking-rule case; §5.6 covers the specific RLHF-anchored framing. They're complementary, not redundant.
• Folding the Clean-Cut Pattern into §3.6 directly — rejected. §3.6 is the operational migration approach; §2.6 is the architectural pattern name. They serve different cognitive purposes (operational-procedure vs pattern-recognition).
• Adding the anti-pattern only to pr-review-guide.md §7.7 — rejected as substrate misrouting. The anti-pattern is specifically about ADR 0004 substrate authoring; it belongs IN the ADR. The pr-review guide can cross-reference §5.6 separately.

Related

• Authority artifact: ADR 0004 (learn/agentos/decisions/0004-github-content-architecture.md) — the document being amended.
• Empirical anchor: PR #11381 Cycle-1+Cycle-2 commit history (commits 9fef2459c + 3668f803b introduced @deprecated; commit 9c12f072a reverted them post-operator-correction).
• Operator correction context: 2026-05-15 nightshift operator A2A [WTF] PR #11381 ... clean cut. no deprecations. framing + follow-up "friction → gold. we knew about the deprecation tendency."
• Related substrate-evolution observation (worth separate ticket): known model-family biases (deprecation tendency, completion bias, etc.) should be enumerated as a load-bearing pattern in ticket-create-workflow.md §5 Avoided Traps mandate — explicit-anti-pattern-enumeration is the substrate-discipline-correct guard against RLHF anchors. Out of scope here; file as follow-up.

Origin Session

• Origin Session ID: e095c569-beac-4743-998f-e07d4344492e
• Cross-session anchor: the ADR 0004 author session (2026-05-14, prior session) is the substrate-evolution context that produced the implicit-obviousness gap this ticket closes.

Retrieval Hint

Search for ADR 0004 clean-cut pattern deprecation theater RLHF anchor preservation-window §5.6 §2.6.