docs: add release process topic shelf

[flyingrobots]

Summary

• Adds repo-local AGENTS.md guidance for topic shelf upkeep, git rules, Think usage, and local verification.
• Adds docs/topics/release-process/ as the current contract shelf for tag-triggered GitHub Release publication.
• Updates docs indexes and release notes status after v0.1.0-alpha.1 publication.
• Extends cargo xtask contract-check to accept xtask tests as executable evidence, not only crate tests.
• Strengthens the release workflow regression and adds a policy regression for AGENTS.md topic-shelf language.

RED / GREEN Evidence

RED:

• cargo test -p xtask contract_graph_is_valid failed after adding the release-process shelf because release workflow evidence lives in xtask, while the checker only searched crates/ tests.

GREEN:

• cargo test -p xtask release_workflow_publishes_only_main_reachable_tags
• cargo test -p xtask agents_topic_shelf_policy_is_present
• cargo test -p xtask contract_graph_is_valid
• npx --yes markdownlint-cli2 AGENTS.md CHANGELOG.md docs/README.md docs/releases/v0.1.0-alpha.1.md docs/topics/README.md docs/topics/release-process/README.md docs/topics/release-process/test-plan.md
• cargo xtask verify

Topic Shelf Impact

• Added owning shelf for release automation and publication behavior.
• Recorded that release, CI, and publication workflows count as durable contract behavior when they define project behavior.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 40 minutes and 7 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

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, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f0102f63-4737-4979-ba29-c0ab16df59b7

📥 Commits

Reviewing files that changed from the base of the PR and between 93d1aec and f0b5a39.

📒 Files selected for processing (5)

• CHANGELOG.md
• docs/topics/release-process/README.md
• docs/topics/release-process/policy.toml
• docs/topics/release-process/test-plan.md
• xtask/src/main.rs

Walkthrough

Adds AGENTS.md with repository working guidelines covering git rules, Think memory, and Topic Shelf conventions. Introduces a new docs/topics/release-process/ topic shelf (README and test-plan). Expands contract_check evidence discovery to include xtask/ tests. Extends release workflow test assertions and adds a new test for AGENTS.md policy presence. Updates docs index, changelog, and lint config accordingly.

Changes

AGENTS.md Policy, Release-Process Topic Shelf, and xtask Evidence Expansion

Layer / File(s)	Summary
AGENTS.md repository working guidelines AGENTS.md	Adds AGENTS.md defining git operation prohibitions, Think cross-session memory patterns, Topic Shelf update/discipline conventions, and cargo xtask verify as the local readiness gate.
Release-process topic shelf docs/topics/release-process/README.md, docs/topics/release-process/test-plan.md	Adds the release-process README documenting the tag-triggered workflow public surface (tag matching, reachability check, release-notes path, gh release create --verify-tag, prerelease handling, no crates.io publish, tag immutability), the v0.1.0-alpha.1 current-release example, and deferred items. Adds a complete test-plan covering scope, requirements, fixtures, test cases, determinism obligations, and open gaps.
xtask evidence expansion and new assertions xtask/src/main.rs	contract_check extends test-name collection from crates/ to also include xtask/. Release workflow test gains --prerelease/prerelease=true assertions and a cargo publish absence check. New agents_topic_shelf_policy_is_present test validates required AGENTS.md substrings.
Docs index, changelog, lint config, and release notes .markdownlint.json, CHANGELOG.md, docs/README.md, docs/releases/v0.1.0-alpha.1.md, docs/topics/README.md	Adds MD024: siblings_only lint rule. Populates [Unreleased] changelog section with AGENTS.md policy and release-process shelf entries plus the xtask evidence and lint relaxation changes. Updates docs/README.md to link the published alpha release notes and new release-process topic. Marks v0.1.0-alpha.1.md as published. Adds the release-process entry to the topics index.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• flyingrobots/edict#18: Directly touches docs/releases/v0.1.0-alpha.1.md and changelog/index links around the same draft-vs-published release status wording being updated in this PR.

Poem

📜 A shelf was born for every rule,
The agents received their law,
No amend, no rebase, no force-push fool,
And cargo publish? Strike it raw.
The tag is signed, the notes are found—
Topic shelves now: hallowed ground. 🏛️

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add release process topic shelf' accurately summarizes the primary change: introducing a new release process documentation topic shelf in the docs directory.
Description check	✅ Passed	The description comprehensively relates to the changeset, detailing AGENTS.md guidance, the release-process topic shelf addition, documentation updates, xtask contract-check extension, and test verification evidence.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 93d1aec323

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

Code Lawyer Activity Summary

@codex second-opinion loop closed.

#	Severity	Source	File	Issue	Fix Commit	Outcome
1	P2	PR thread	xtask/src/main.rs	Contract evidence test asserted mutable AGENTS.md prose instead of a stable behavior/artifact.	f0b5a39	Replaced prose-locking evidence with docs/topics/release-process/policy.toml, updated the release-process matrix to cite the structured policy, and added release_tag_recovery_policy_is_structured. Thread resolved.

Self-audit result: no additional self-discovered issues beyond the PR thread.

Verification:

• RED: cargo test -p xtask release_tag_recovery_policy_is_structured failed before policy.toml existed.
• GREEN: cargo test -p xtask release_tag_recovery_policy_is_structured
• GREEN: cargo test -p xtask contract_graph_is_valid
• GREEN: npx --yes markdownlint-cli2 AGENTS.md CHANGELOG.md docs/README.md docs/releases/v0.1.0-alpha.1.md docs/topics/README.md docs/topics/release-process/README.md docs/topics/release-process/test-plan.md
• GREEN: cargo xtask verify
• Remote PR checks: Rust MSRV and stable passed; CodeRabbit approved.

Thread resolution:

• PRRT_kwDOS96-Us6LG61C: resolved via GraphQL.

[chatgpt-codex-connector]

Summary

• No follow-up code changes were needed. The trigger reports the second-opinion loop is closed, and the repository is already at the PR head commit f0b5a39.
• I confirmed the reviewer issue was addressed by structured release-tag policy evidence in docs/topics/release-process/policy.toml, which encodes forbidden tag mutation and existing-tag recovery behavior. docs/topics/release-process/policy.tomlL1-L4
• I confirmed the executable evidence now checks the structured policy file instead of locking mutable AGENTS.md prose. xtask/src/main.rsL698-L714
• I confirmed the release-process test plan cites the structured policy artifact and marks the policy guard as implemented evidence. docs/topics/release-process/test-plan.mdL32-L46
• I did not create a commit or pull request because the worktree is clean and no changes were made.

Testing

• ⚠️ cd /workspace/edict && codex-think --remember --json && printf '\n---\n' && find .. -name AGENTS.md -print && git status --short && git rev-parse HEAD && git log --oneline -5 — warning: codex-think is not installed in this environment.
• ✅ cd /workspace/edict && find .. -name AGENTS.md -print && git status --short && git rev-parse HEAD && git log --oneline -5
• ✅ cd /workspace/edict && sed -n '1,140p' AGENTS.md && printf '\n--- policy ---\n' && sed -n '1,160p' docs/topics/release-process/policy.toml && printf '\n--- xtask snippets ---\n' && rg -n "release_tag_recovery_policy_is_structured|policy.toml|contract_graph_is_valid" xtask/src/main.rs docs/topics/release-process/test-plan.md
• ✅ cd /workspace/edict && nl -ba docs/topics/release-process/policy.toml && printf '\n---\n' && nl -ba xtask/src/main.rs | sed -n '690,716p' && printf '\n---\n' && nl -ba docs/topics/release-process/test-plan.md | sed -n '28,48p' && git status --short

View task →