From b8617fa183627fb114d25852d09bffa76c3e938b Mon Sep 17 00:00:00 2001
From: ArianAr <arian.fawiki@gmail.com>
Date: Thu, 16 Jul 2026 00:44:04 +0300
Subject: [PATCH 1/2] docs: require PR review and full local tests before merge

Codify agent/maintainer workflow: one PR per issue, run CI-equivalent
checks on every change, and complete a code review before merging.
---
 AGENTS.md       | 45 +++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md |  8 ++++++--
 2 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..abbe90c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# Agent / maintainer workflow (PaperCut)
+
+Durable process for automated and human contributors shipping to this repo.
+
+## One PR per issue
+
+- Prefer **one GitHub issue → one feature branch → one PR**.
+- Link with `Closes #N` in the PR body.
+- Keep PRs small and reviewable; do not bundle unrelated work.
+
+## Test every change (before push and before merge)
+
+Behavior changes need tests. Always run the same gates as CI locally:
+
+```bash
+pnpm test
+pnpm lint
+pnpm typecheck
+pnpm build
+# when CLI packaging surface changes:
+pnpm --filter papercut-cli pack:dry-run
+```
+
+Do **not** merge on a red required `ci` check. Fix failures on the branch first.
+
+## Review every PR before merge
+
+1. Open the PR against `main`.
+2. Wait for CI (`ci` aggregate gate) to go green.
+3. Run a **code review** on the PR (reviewer skill / `/review --pr <n>`), post findings as a **PENDING** GitHub review when issues exist, or record a clean review summary when none do.
+4. Address any **bug**-severity findings before merge; treat suggestions proportionally.
+5. Only then squash-merge (and delete the branch).
+
+Reviews are not optional polish — they catch regressions that unit tests miss (UI wiring, security, privacy defaults).
+
+## Privacy and security defaults
+
+- No paste body / IP logging in app code.
+- Opt-in metrics only (`PAPERCUT_METRICS`); counters never include content or IPs.
+- Pins/bookmarks/theme prefs stay in the browser (`localStorage`), not on the server.
+
+## Dependency and release notes
+
+- Prefer latest compatible dependencies; majors in deliberate PRs (see [ROADMAP.md](./ROADMAP.md)).
+- User-facing or security fixes: update [CHANGELOG.md](./CHANGELOG.md) under `[Unreleased]`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a5d9816..a31d2f6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,7 +52,7 @@ echo "hello from papercut" | pnpm cli --url http://localhost:3000
    ```
    Branch prefixes we use: `feat/`, `fix/`, `docs/`, `chore/`, `test/`.
 3. **Implement** with tests for behavior changes.
-4. **Run checks locally** (same as CI):
+4. **Run checks locally** (same as CI) — do this for **every** change before push:
    ```bash
    pnpm test
    pnpm lint
@@ -60,7 +60,11 @@ echo "hello from papercut" | pnpm cli --url http://localhost:3000
    pnpm build
    ```
 5. **Commit** with clear messages (see below).
-6. **Push and open a PR** against `main`.
+6. **Push and open a PR** against `main` (prefer one issue → one PR; use `Closes #N`).
+7. **Review the PR** after CI is green (human or tooling). Fix bug-level findings before merge.
+8. **Merge only when** required `ci` is green and review is done.
+
+Agent automation follows the same bar — see [AGENTS.md](./AGENTS.md).
 
 ### Continuous integration
 

From f0ca74d63b53560b97544349682e7d7f3aef6207 Mon Sep 17 00:00:00 2001
From: ArianAr <arian.fawiki@gmail.com>
Date: Thu, 16 Jul 2026 00:47:15 +0300
Subject: [PATCH 2/2] docs: align issue-link keywords in CONTRIBUTING

Use Closes/Fixes interchangeably in the PR checklist so it matches the
workflow step that prefers Closes #N.
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a31d2f6..1551196 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -110,7 +110,7 @@ test(api): cover password unlock cookie
 ### Pull requests
 
 - Describe **what** changed and **why**.
-- Link related issues (`Fixes #123`).
+- Link related issues (`Closes #N` or `Fixes #N`; either auto-closes the issue on merge).
 - Note any migration or env var changes.
 - Keep the PR reviewable: one logical feature or fix when practical.
 - Ensure CI (when configured) and local tests pass.