docs: enforce main-only release protocol

[mohanagy]

Summary

• Adds a tracked release protocol for every agent and maintainer.
• Requires the only release promotion to be development → main; feature branches and development cannot publish.
• Keeps trusted publishing as the GitHub Actions npm publish --access public --provenance command authenticated with OIDC, never NPM_TOKEN.
• Requires the release tag and GitHub Release to resolve to the exact current main commit.

Security impact

• Prevents publishing an older commit that is merely reachable from main.
• Explicitly prohibits setting, committing, or relying on NPM_TOKEN in the release path.
• Preserves the protected GitHub npm environment and provenance requirement.

Validation

• Focused release workflow and policy contract tests
• npm run lint
• npm run typecheck

Checklist

• Added or updated regression contracts before implementation
• PR base is development
• Current-head CI and review approval are required before merge

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds repository workflow and release protocol guidance in AGENTS.md and CONTRIBUTING.md, then adds Vitest contract tests covering branch restrictions, trusted publishing, provenance, workflow settings, verification, and deprecation requirements.

Changes

Release policy

Layer / File(s)	Summary
Release policy documentation AGENTS.md, CONTRIBUTING.md	Documents SemVer selection, branch promotion rules, trusted OIDC publishing, post-publish verification, and deprecation procedures.
Release policy contract tests tests/release-policy-contract.test.ts	Loads repository documentation and workflow configuration, then asserts the required release and publishing rules are present.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• mohanagy/miftah#42: Covers the publish workflow and trusted publishing requirements referenced by these release-policy tests.

Poem

A rabbit reads the release decree,
“Main-bound tags shall set us free!”
OIDC hops, provenance shines,
Tests guard all the publishing lines.
Thump, thump—safe releases spring!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No pull request description was provided, so the required Summary, Security impact, and Validation sections are missing.	Add the template sections with a focused summary, security impact assessment, and exact validation commands/results.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title is concise and accurately highlights the main change: documenting a stricter main-only release protocol.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-protocol

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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 36-39: Normalize the ordered-list markers for items 8–11 in the
AGENTS.md section to match the repository-configured markdownlint MD029 style,
preserving the existing item order and content.
- Line 1: Update the opening heading in AGENTS.md from the second-level `madar`
heading to a top-level `#` heading, preserving the existing heading text.
- Around line 60-64: Pin the release contract to the exact reviewed promotion
commit instead of ancestry alone: update .github/workflows/publish.yml to
compare the release tag with the intended main commit, and update
tests/release-policy-contract.test.ts (lines 34-37) to enforce that exact-match
behavior. Keep AGENTS.md (lines 60-64) and CONTRIBUTING.md (lines 48-52) aligned
with the exact-commit requirement; do not weaken the documentation to permit any
ancestor tag.

In `@tests/release-policy-contract.test.ts`:
- Around line 12-21: Update the release-policy contract tests around the
instruction list and publish workflow assertions to explicitly prohibit use of
the long-lived NPM_TOKEN. Add the prohibition to the documented rules and assert
that the loaded workflow does not contain “NPM_TOKEN”, while preserving the
existing positive trusted-publishing and provenance checks.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bc38761b-92f8-4756-85e3-9f76483c805f

📥 Commits

Reviewing files that changed from the base of the PR and between f8666ae and 4903354.

📒 Files selected for processing (3)

• AGENTS.md
• CONTRIBUTING.md
• tests/release-policy-contract.test.ts