From e53a3109774c2ca6e90c4400400bdbc0f3cdc32c Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Sun, 21 Jun 2026 09:55:22 +0200
Subject: [PATCH] docs(agents): require PR-based merges

---
 .agents/workflow.md | 5 ++++-
 AGENTS.md           | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.agents/workflow.md b/.agents/workflow.md
index 98f7ba48b..9f95f7f16 100644
--- a/.agents/workflow.md
+++ b/.agents/workflow.md
@@ -77,6 +77,7 @@ Issue and tracker workflow:
 - Mark tracker items complete only after the scoped work is complete, verified, merged to `main` through a PR, and documented with verification evidence.
 - If the work intentionally remains on an ongoing branch, open a draft PR and record the branch name, PR URL, worktree path, current head commit, and remaining scope in the parent tracker item. Keep the child item open or in progress until the PR is merged or explicitly superseded.
 - If a commit is a self-contained unit of completed, verified work, push it directly to its assigned remote branch instead of leaving it local for handoff. This does not override the rule against pushing directly to `main`.
+- Do not merge feature, worker, or integration branches into local `main` to stage completion. If multiple branches need integration, create an integration branch, push it, and review it through a PR.
 
 GitHub issue flow:
 
@@ -97,7 +98,7 @@ gh pr create --draft --title "<type>(scope): description" --body "Closes #<issue
 ```
 
 - Complete E2E verification before marking a PR ready for review.
-- Never push directly to `main`; always use branches and PRs.
+- Never push directly to `main`, force-push `main`, or merge work into `main` outside GitHub. Every change that reaches `main` must go through a PR with GitHub Actions as the merge gate.
 - GitHub Issues and Projects are external collaboration surfaces, not a substitute for operator-supplied tracker state unless explicitly directed.
 - `bug` marks defects. Issues without `bug` are non-bug work by default.
 - `core`, `wui`, and `tui` are area labels.
@@ -106,6 +107,8 @@ gh pr create --draft --title "<type>(scope): description" --body "Closes #<issue
 
 Pull requests and merges:
 
+- For large or high-risk PRs, keep the PR branch history reviewable: use one meaningful commit per coherent feature, fix, test, docs update, or review-fix slice. Avoid hiding unrelated work behind a single local merge commit or vague "integration" commit.
+- Before marking a large PR ready, replace WIP commits, accidental squash commits, or noisy merge commits on the PR branch with meaningful commits. Use `git push --force-with-lease` only on the PR branch after confirming no one else owns that branch.
 - Always use squash merge when merging PRs to `main`.
 
 ```bash
diff --git a/AGENTS.md b/AGENTS.md
index bb40cb785..0d5ab5a98 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,8 +29,10 @@ Read the full rationale and examples in [.agents/product-boundary.md](.agents/pr
 - Use `bun` for package and script operations.
 - Use the operator-supplied tracker when present. Do not commit tracker runtime state, local coordination config, or other machine-local artifacts.
 - Do not use `git stash` on shared checkouts. Stage explicit paths only, and never push directly to `main`.
+- Every merge to `main` requires a GitHub pull request with passing GitHub Actions. Do not locally merge feature or integration branches into `main` as a substitute for opening a PR.
 - Prefer the primary checkout only for small, clean, bounded work. Use a dedicated worktree from the latest `origin/main` for non-trivial, risky, long-running, or parallel changes.
 - Non-trivial work needs a plan or task list. If the implementation surface starts to balloon, stop and re-plan.
+- Large or high-risk PRs need meaningful, reviewable commits for each coherent change. Rewrite only the PR branch with `git push --force-with-lease` when needed to replace WIP or accidental squashed history before review.
 - Manual red/green UAT is blocking before a branch is ready for review. GitHub Actions is the authoritative merge gate.
 - For browser or screenshot UAT, keep evidence out of the public repo and publish reviewable artifacts to an `agentv-private` evidence branch. See [.agents/verification.md](.agents/verification.md).
 - Wire formats are `snake_case`; internal TypeScript is `camelCase`. Translate only at the boundary.