chore: Capture release-automation knowledge in docs and slim AGENTS.md#1889
Conversation
…reference Capture the release-automation knowledge from the 2026-07-21 dispatcher realignment (PR #1888) so future agents do not have to rediscover it: - Add docs/version-series-realignment.md covering when and how to rewind a component's release-please version series, why the sync script cannot see a fix-titled realignment commit while dispatcher-publish self-heals the missing release from the contract at HEAD, and which pin fields must never be hand-edited. - Update the AGENTS.md Project Runner Pin section, which still described the pin as having two required fields; document dispatcherReleaseTag and dispatcherArchiveManifest as automation-stamped fields.
Anthropic's guidance for CLAUDE.md/AGENTS.md is to keep the always-loaded memory file under ~200 lines because longer files consume context on every session and dilute instruction adherence. AGENTS.md had grown to 203 lines, and four of its sections only matter for specific tasks. Move the full content of those sections verbatim into docs/ and leave a short trigger-plus-pointer paragraph in AGENTS.md (203 -> 153 lines): - Unity Freeze Prevention -> docs/unity-editmode-test-guardrails.md - Dead Code Scanner -> docs/dead-code-scanner.md - Windows Compatibility Guardrails -> docs/windows-compatibility.md - Shared Release Inputs and Triggers -> docs/shared-release-inputs.md docs/ was chosen over .claude/rules so the moved content stays reachable for every agent that reads AGENTS.md, not only Claude Code. The pin field bullet added in the previous commit is also compressed to a doc reference.
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughDocumentation guidance was revised for protocol compatibility, project-runner pins, shared release triggers, version realignment, dead-code scanning, Windows compatibility, native CLI validation, and Unity EditMode test execution. Seven documentation pages were added, while related ChangesDocumentation guidance updates
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…variants Second slimming pass on AGENTS.md (153 -> 112 lines). The protocol version, project runner pin, and Go CLI validation sections mixed always-relevant invariants with background detail that only matters when actually performing those tasks. Keep the hard rules inline (declarations must stay equal, never bump or edit stamped versions by hand, pin is additive-only, use the dist binary and check-go-cli.sh) and move bump criteria, release sequencing, and pin field rationale to docs/protocol-version.md and docs/project-runner-pin.md.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 104-106: Update the release guidance in AGENTS.md to preserve the
manual-edit prohibition while explicitly exempting the documented version-series
realignment procedure, including dispatcherVersion and component changelogs.
In `@docs/version-series-realignment.md`:
- Around line 3-9: Update the dispatcher realignment reference in the document
to use the correct historical date, or explicitly label the 2026-07-21 entry as
a planned example rather than a completed event. Keep the described release
sequence and PR `#1888` reference unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 664ba576-2d71-470f-8dba-5c1d270c3453
📒 Files selected for processing (6)
AGENTS.mddocs/dead-code-scanner.mddocs/shared-release-inputs.mddocs/unity-editmode-test-guardrails.mddocs/version-series-realignment.mddocs/windows-compatibility.md
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 89-95: Update the native CLI example in AGENTS.md to avoid
hardcoding dist/darwin-arm64/uloop; use a platform-specific binary placeholder
that accounts for Windows .exe suffixes, or reference scripts/build-go-cli.sh
for selecting the correct built target while preserving the instruction to run
the checkout’s rebuilt binary.
- Around line 37-38: Qualify the automation-only release-version rule in
AGENTS.md lines 37-38 with an explicit exception for the documented
version-series-realignment procedure. Apply the same exception to pin fields in
AGENTS.md lines 45-47 while preserving additive-only evolution and the
prohibition on deleting or renaming fields.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e9fc5f31-31e3-4465-a532-6cd2758da4bb
📒 Files selected for processing (3)
AGENTS.mddocs/project-runner-pin.mddocs/protocol-version.md
…s date Address CodeRabbit review on PR #1889: the always-loaded AGENTS.md said "never bump them by hand" without the realignment exception documented in docs/, and the realignment doc's date was timezone-ambiguous — identify the case by its release tag instead.
… CLI example platform-neutral Address CodeRabbit round 2 on PR #1889: the CLI / Unity Package Compatibility section also said "never edit them by hand" without the version-series-realignment exception, and the Native Go CLI Validation example hardcoded the macOS ARM64 binary path without a platform note. The pin-field prohibition stays unqualified on purpose: the realignment procedure itself forbids hand-editing the automation-stamped pin fields.
Summary
User Impact
fix:commit is invisible to the release sync script, how dispatcher-publish self-heals a missing release, why pin fields must never be hand-edited) lived only in one conversation. AGENTS.md had also drifted (it described the pin as having two required fields while the real pin has four) and mixed always-relevant invariants with task-specific detail.docs/version-series-realignment.mdcaptures the full procedure with the 2026-07-21 case as a worked example, the pin field reference is complete, and AGENTS.md loads ~45% less always-on context. Every moved rule remains reachable through a task-triggered pointer, and the hard invariants (protocol declarations stay equal, stamped versions are never hand-edited, pin is additive-only, EditMode tests are single-flight) stay inline.Changes
docs/version-series-realignment.md: when and how to rewind a component's release-please version series, which automations self-heal the missing release, and what must not be touched.docs/unity-editmode-test-guardrails.mddocs/dead-code-scanner.mddocs/windows-compatibility.mddocs/shared-release-inputs.mddocs/protocol-version.mddocs/project-runner-pin.mddispatcherReleaseTag/dispatcherArchiveManifestfields (AGENTS.md previously listed only two fields).docs/was chosen over Claude-specific rule/skill directories so the content stays reachable for every agent that reads AGENTS.md (and.claude//.agents/remain generated-only).Verification
grep -rln 'AGENTS.md\|CLAUDE.md' scripts/ cli/ .github/returns nothing — no script or CI asserts AGENTS.md content.