Authored by Claude Opus 4.7 (Claude Code). Session 8b31fd62-6a53-40b5-aae2-c5288f8ced09.

Resolves #10826 Related: #10822 (Epic — Config substrate cleanup; this PR satisfies AC3 of the Epic) Related: #10733 (Epic — Cognitive-load audit; this PR aligns with the byte-reduction direction)

Outcome (post-calibration 2026-05-06 ~16:50Z)

Codifies the Clean-Slate Sunset Rule for env-var renames in pull-request-workflow.md §1.1.1. Sets the discipline gate at PR-authoring time so authors apply the rule before the deprecation chain ships.

The rule (1 sentence): env-var renames must rename code + .env + tests in ONE PR; no legacyEnvVar parameters, no console.warn deprecation chains, no multi-layer fallback — operators take the small migration cost ONCE per rename. Released-version compat exception gated on explicit sunset trigger documentation.

Empirical anchor: PRs #10808 / #10810 / #10814 each added env-var deprecation chains protecting users-who-don't-exist (legacy vars never shipped in a released npm version). AGENTS.md §13 substrate-accretion-defense was empirically not enforced at PR-authoring time; this PR codifies the gate at the workflow surface where it's actionable.

Calibration (2026-05-06 ~16:50Z)

Operator-relayed hard decline on Cycle 1's pr-review-guide.md §7.6 anti-patterns row addition. Per learn/agentos/measurements/cognitive-load-baseline-2026-05.md, pr-review-guide.md is 45,210 bytes / 436 lines loaded every PR review across the swarm — high-traffic always-loaded payload. Per Progressive Disclosure pattern (skill-authoring-guide.md §"Slot-Rule Discriminator" / §"Byte Budget", origin summary_d87e357e 2026-04-04 #9698 + #9701), the §7.6 row should have rated compress-to-trigger not keep (trigger-frequency: every-PR-review; failure-severity: moderate; env-var-rename PRs are low-frequency relative to total review surface).

Cycle 2 commit 56ee8bdf1 reverts the §7.6 row entirely. Substrate (rule body in pull-request-workflow.md §1.1.1) fires at PR-authoring time which is the right moment. Reviewers covering env-var-rename PRs already trigger §1.1 Substrate-Mutation Pre-Flight Gate (touches .agents/skills/** etc.), so the §7.6 row was over-engineering the always-loaded reviewer surface.

Revised diff scope: 21 lines added to pull-request-workflow.md only (the substrate file where this rule lives). Aligns with Epic #10733 cognitive-load byte-reduction direction.

Slot Rationale (§1.1 substrate-mutation pre-flight gate)

This PR mutates one substrate file under .agents/skills/**. Per AGENTS.md §13 decay-mitigation:

Cycle 1's pr-review-guide.md §7.6 row reverted in Cycle 2 per operator calibration above. No other substrate files touched.

Test Evidence

No automated tests — doc-only PR (skill reference file, not runtime code). Verification path:

• git diff --check origin/dev...HEAD — no whitespace issues
• Static prose review — rule body internally consistent + cross-references existing §1.1 Substrate-Mutation Pre-Flight Gate
• Cognitive-load alignment — Cycle 2 calibration reduces the always-loaded reviewer surface compared to Cycle 1

Post-Merge Validation

• First future env-var-rename PR is reviewed against §1.1.1 — author applies the rule at PR-authoring time
• If a deprecation-chain PR is filed post-merge, reviewer cites §1.1.1 directly
• Memory anchor surfaces the rule via query_raw_memories(query="clean-slate sunset rule env-var rename") — landed via end-of-turn consolidated memory save

Files Touched

• .agents/skills/pull-request/references/pull-request-workflow.md — +21 lines (new §1.1.1)

(Cycle 1 also touched .agents/skills/pr-review/references/pr-review-guide.md — reverted in Cycle 2 per calibration above.)

Cross-Family Mandate (§6.1)

Substrate-mutation PR. Cross-family review approved by @neo-gemini-pro at Cycle 1 (commentId IC_kwDODSospM8AAAABBZRy_g equivalent — verified live; Status: Approved per pr-review-template structure). Cycle 2 calibration is a substrate reduction (purely-removal of pr-review-guide.md addition); per peer-review-protocol the existing approval should stand because the change reduces blast radius rather than expanding it. A2A sent to reviewer noting the change.

Commits

• 780a588a6 — feat(skills): codify clean-slate sunset rule for env-var renames (#10826)
• 56ee8bdf1 — fix(skills): revert pr-review-guide §7.6 anti-patterns row addition (#10826)

Evolution

Cycle 1 → Cycle 2 calibration: Initial implementation added a row to pr-review-guide.md §7.6 anti-patterns table to provide a reviewer-side cross-reference back to pull-request-workflow.md §1.1.1. Operator-relayed direction: that pattern enhances the always-loaded high-traffic skill payload massively; cognitive-load-baseline measurements (Epic #10733) actively target byte-reduction across these surfaces. The right shape per Progressive Disclosure is substrate at PR-authoring time, no addition to PR-review time. Reverted §7.6 row entirely; substrate at workflow.md §1.1.1 is sufficient.

Cycle 3 + 3.5 Calibration (post-merge-eligible state)

Cycle 2 was wrong: I reverted the §7.6 row (which was the trigger) and kept the 21-line body in the workflow file. That inverted the right shape.

Cycle 3 corrected architecture (per operator-relayed Progressive Disclosure):

• New file .agents/skills/pull-request/references/env-var-rename-rule.md (30 lines) — atlas content, conditionally loaded
• pull-request-workflow.md §1.1: 1-line trigger **Env-var changes** → read [env-var-rename-rule.md](./env-var-rename-rule.md) (replaces 21-line body)
• pr-review-guide.md §7.6: 1-line trigger row pointing at the same atlas

Cycle 3.5 framing fix (per operator):

• Removed harness-private citation (feedback_neo_is_engine_not_framework — Claude Code memory file, not a public anchor)
• Replaced engine-vs-framework framing with accurate Neo identity per README.md (operator population = swarm + selected partners deploying the Agent OS)

Final substrate impact:

• Net delta on always-loaded substrate: -18 lines (workflow lost 19, pr-review gained 1)
• New 30-line conditional payload in env-var-rename-rule.md (only loaded when env-var trigger fires)
• Aligns with Epic #10733 cognitive-load audit byte-reduction direction

File rename rationale: not *sunset* per operator — that namespace is reserved for /session-sunset skill. env-var-rename-rule.md preserves "env vars in general" topic.