Codify clean-slate sunset rule in pull-request-workflow §1.1

Authored by @neo-opus-4-7 (Claude Opus 4.7, Claude Code). Session 8b31fd62-6a53-40b5-aae2-c5288f8ced09. Sub-issue of Epic #10822 — Config substrate cleanup. Resolves AC3 of the Epic.

Context

Three recent substrate-mutation PRs (#10808 / #10810 / #10814) each added one env-var-resolver layer with multi-window deprecation chains; none net-reduced loaded bytes; none cited concrete sunset triggers. AGENTS.md §13 substrate-accretion-defense was empirically not enforced at PR-review time. The defense exists in writing; no PR was rejected for failing it.

The Epic #10822 graduates Discussion #10819 which surfaced this empirically. To prevent the substrate-accretion class from recurring post-Epic, this sub-issue codifies the clean-slate sunset rule in pull-request-workflow.md §1.1 so reviewers reject deprecation chains immediately at PR-review time, before merge.

The Problem

AGENTS.md §13 "Self-Evolving Systems" mandates:

Substrate Accretion Defense: Every substrate-mutation PR MUST EITHER net-reduce loaded-bytes OR cite future-decay-mitigation rationale (sunset condition, slot disposition, retirement trigger).

This is an authoring-time mandate — but the enforcement gate fires at PR-review time. Without an explicit reviewer-side rule pointing at the same standard, the gate is implicit and was missed three times in two weeks.

The Architectural Reality

pull-request-workflow.md §1.1 already exists as the Substrate-Mutation Pre-Flight Gate for PRs touching AGENTS.md, AGENTS_ATLAS.md, .agents/skills/**, or learn/agentos/**. It mandates a slot-rationale section in PR bodies. This sub-issue extends it to an env-var-rename clean-slate clause that reviewers explicitly check before approval.

File: .agents/skills/pull-request/references/pull-request-workflow.md (workflow §1.1)

Adjacent enforcement surface: pr-review-guide.md §7.6 anti-patterns table can reference the new rule for symmetric reviewer-side awareness.

The Fix

Add an explicit clean-slate sunset rule subsection under pull-request-workflow.md §1.1 Substrate-Mutation Pre-Flight Gate:

<h3 class="neo-h3" data-record-id="6">1.1.1 The Clean-Slate Sunset Rule</h3>

If your PR adds, removes, or renames an env-var that the substrate reads from `process.env`,
you MUST follow the clean-slate hard-cut rule rather than ship a deprecation chain.

**Hard-cut rule:** rename in code + rename in `.env` + rename in tests + ship together in
ONE PR. No `legacyEnvVar` parameters, no `'deprecated; use X'` warnings on boot, no fallback
chains. Operators take the small migration cost ONCE per rename.

**Why no deprecation chains:**
- Engine-class deployments (~4 swarm + selected partners) don't have thousands of users
  to protect across release windows; framework-class deprecation patterns are wrong-shape.
- Empirical anchor: legacy env-vars deprecated in #10808 / #10810 / #10814 were never
  shipped in a released npm version; "compatibility window" was protecting users-who-don't-exist.
- KISS over backwards-compat-without-released-users.

**Reviewer enforcement:** PRs that introduce `legacyEnvVar` parameters, `console.warn`
deprecation calls in resolvers, or multi-layer fallback chains for env-var renames get
**Request Changes** at first cycle. The author either:
- (a) Refactors to hard-cut (rename + `.env` migration in same PR), OR
- (b) Documents an explicit released-version compat contract that the chain protects
  (cite the released npm version + the user surface area).

**Exception**: if the env-var IS in a released npm version's documented operator surface
AND a real user migration window is needed, reviewer + author MUST file an `epic` ticket
with explicit sunset trigger (commit SHA / version / N-cycles-from-merge) before merging
the deprecation chain. The "deprecation window" semantics get a concrete end-state, not
indefinite drift.

Cross-link this rule from pr-review-guide.md §7.6 anti-patterns table:

| PR adds env-var deprecation chain without released-version contract | §1.1.1 Clean-Slate Sunset Rule violated; substrate-accretion-defense bypass |

Acceptance Criteria

• AC1: pull-request-workflow.md §1.1.1 subsection added with the clean-slate sunset rule body
• AC2: pr-review-guide.md §7.6 anti-patterns table includes the cross-link to §1.1.1
• AC3: At least one example reviewer-side Required Action template referencing §1.1.1 for future PR cycles
• AC4: Memory anchor created (or existing one updated) referencing the rule by name for cross-session retrieval

Out of Scope

• Retroactive enforcement on already-merged PRs (#10808 / #10810 / #10814) — those are addressed via Epic #10822 sub-issue #2 (legacy alias deletion in one PR). The clean-slate rule applies to FUTURE PRs.
• Wider AGENTS.md §13 substrate-accretion-defense formalization beyond env-vars — this sub-issue scopes specifically to env-var renames where the failure mode was empirically observed. Other substrate-accretion classes (config-key additions, JSDoc bloat, doc accretion) stay covered by AGENTS.md §13 general framing.
• Tooling automation (e.g., a CI check that grep-detects legacyEnvVar parameter additions) — substantive idea but separate-ticket scope. This sub-issue ships the documented rule + cross-link only.
• pull-request-workflow.md Progressive Disclosure restructure — out of scope; this sub-issue ADDS a subsection without restructuring the file's progressive-disclosure router.

Avoided Traps

• Over-reaching to ban ALL deprecation chains in any context — the rule explicitly carves out a released-version compat exception with concrete sunset triggers. Engine-class default is hard-cut; framework-class with real released users is still possible if needed, just with explicit sunset documentation.
• Adding the rule only to pr-review-guide.md — author-side enforcement at PR-AUTHORING time is the load-bearing surface. pull-request-workflow.md is read by the author before drafting the PR; pr-review-guide.md is read by the reviewer during review. Both surfaces matter; the primary is the author-side workflow.
• Codifying the rule without an exception clause — released-version contract paths are real (e.g., a hypothetical future v13.x.y point release that needed to add a compat shim for a v13.0 user). Hard-banning them creates substrate inflexibility. The exception is gated on explicit sunset documentation.

Related

• Parent: #10822 Config substrate cleanup
• Originating: Discussion #10819 §3 Three principles + §5 Avoided Traps
• Substrate: AGENTS.md §13 Self-Evolving Systems / substrate-accretion-defense
• Empirical anchors (PRs that violated the implicit rule): #10808, #10810, #10814

Origin Session ID

8b31fd62-6a53-40b5-aae2-c5288f8ced09

Handoff Retrieval Hints

• query_raw_memories(query="config substrate cleanup KISS three-tier model engine-class no-deprecation-chains") — surfaces the Discussion #10819 graduation context
• query_raw_memories(query="substrate-accretion-defense AGENTS.md §13 enforcement gate not enforced") — surfaces the empirical anchor sessions
• Discussion #10819 §3 Three principles → Principle 2 ("No deprecation chains") is the substrate of this sub-issue
• Epic #10822 AC3 is satisfied by this sub-issue's AC1+AC2

Co-authored-by: Claude Opus 4.7 neo-opus-4-7@neomjs.com