chore: enforce pull request release flow

.gitignore

@@ -45,3 +45,7 @@ Thumbs.db
 *.key
 *.p12
 interference.json
+AGENTS.override.md
+.agents/
+agents.md
+.codex

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to interference
+
+Thanks for contributing. This repository is public: you do not need to join a GitHub team or receive
+write access to propose a change.
+
+## External contributors
+
+1. Fork `ricciviero/interference` on GitHub.
+2. Clone your fork and create a focused branch.
+3. Make the change and run the relevant checks:
+
+   ```bash
+   bun run typecheck
+   bun test ./src
+   ```
+
+4. Push the branch to your fork and open a Pull Request to this repository's `main` branch.
+5. Address CI failures and review comments. A maintainer merges the Pull Request after the required
+   `test` check passes and all conversations are resolved.
+
+Do not commit secrets, API keys, generated local state, or files that are already ignored by the
+repository.
+
+## Maintainers
+
+- Work daily on `dev` or a focused branch, then open a Pull Request to `main`.
+- Do not push directly to `main`: the branch is protected for everyone, including administrators.
+- The `test` GitHub Actions check must pass and all Pull Request conversations must be resolved.
+- No approving review is required while the project has one maintainer; this does not bypass the
+  Pull Request or CI requirements.
+- Force-pushes and deletion of `main` are disabled. GitHub's automatic deletion of merged branches
+  is intentionally disabled.
+
+## Releases
+
+Prepare a release in a `release/vX.Y.Z` branch from current `dev`. Update `CHANGELOG.md`, then run
+`npm --no-git-tag-version version <patch|minor|major>` so the version change is reviewed in a Pull
+Request. After that PR has been merged into `main`, create and push the annotated `vX.Y.Z` tag from
+that merged commit. Never push a release tag before the release PR is merged.
+
+`npm publish` remains a manual maintainer action with OTP. See the release section in
+[README.md](README.md#releasing-maintainers).

README.md

@@ -84,20 +84,37 @@ bun install -g interference-agent@latest   # or: npm i -g interference-agent@lat
 
 interference checks npm for new versions and shows a discreet notice when one is available; run `/update` from inside the app to upgrade.
 
+## Contributing
+
+Contributions are welcome. You do not need to be a member of a GitHub team: fork the repository,
+make your change in a branch, and open a Pull Request. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+the complete workflow.
+
 ## Releasing (maintainers)
 
-Releases are tag-driven. `npm version` runs typecheck and tests, creates the version commit and tag,
-then pushes them through the `postversion` hook. The tag workflow validates the release and attempts
-a provenance publish; the maintainer completes npm publication manually with OTP:
+`main` accepts changes only through a passing Pull Request. Releases are tag-driven, so prepare the
+version in a short-lived release branch, merge its PR into `main`, then create the tag from that
+merged commit:
 
 ```bash
-npm version minor                    # patch|minor|major
-npm publish                          # maintainer only; complete the OTP prompt
-npm view interference-agent version # verify the public version
+git checkout dev && git pull --ff-only
+git checkout -b release/vX.Y.Z
+# Update CHANGELOG.md first.
+npm --no-git-tag-version version minor  # patch|minor|major; runs the preversion checks
+git add package.json CHANGELOG.md
+git commit -m "chore: release vX.Y.Z"
+git push -u origin release/vX.Y.Z
+# Open and merge a PR to main after CI passes.
+git checkout main && git pull --ff-only
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+npm publish                            # maintainer only; complete the OTP prompt
+npm view interference-agent version   # verify the public version
 ```
 
-An npm Automation token in the `NPM_TOKEN` repository secret can enable unattended publishing, but
-the current release procedure does not depend on it. See `CHANGELOG.md`.
+The tag workflow validates the release and attempts a provenance publish. The manual `npm publish`
+step remains the release authority; an npm Automation token in `NPM_TOKEN` is optional. Sync `main`
+back into `dev` after the release. See `CHANGELOG.md`.
 
 ## Screenshot
 

package.json

@@ -35,8 +35,7 @@
     "typecheck": "bunx tsc --noEmit",
     "build": "bun build src/cli.ts --compile --minify --sourcemap --outfile dist/interference",
     "test": "bun test ./src",
-    "preversion": "bun run typecheck && bun run test",
-    "postversion": "git push && git push --tags"
+    "preversion": "bun run typecheck && bun run test"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0.1",