docs(agents): add PR bundling rule to cut one-task-one-PR churn

[BigSimmo]

Summary

• Answers "is there a lot of PR churn, and can we bundle more into a single PR?" — yes on both counts. Every newtask/handoff cycle mints a dedicated claude/<task-slug> branch + PR, so a single docs/ledger-append line pays the same required-CI bill as a large change. Currently-open PR CI testing approach review: flake, waste, and when-to-run matrix #1406 sampled the last 500 CI workflow runs (~3 days of PR traffic, 437 PR-triggered): ~40% cancelled mid-run (mostly superseded by a newer push before Production UI finished), burning roughly 12 Production-UI-hours on runs that never completed.
• Adds a "PR bundling" rule to AGENTS.md: before minting a new branch, check whether the task can ride an already-open PR you own, or bundle with other queued low-risk work, instead of opening a new one. Bundling is scoped tightly so it doesn't undermine the reasons this repo currently favors small PRs for risky changes:
  • Every bundled item must be independently low-risk under the repo's own classifier (scripts/pr-policy.mjs — no clinical-risk path, no RAG-ranking-surface path, no auth/privacy/migration/Supabase path).
  • Each item stays its own separately-revertible commit inside the one PR (one PR, multiple commits — never a squashed diff).
  • Each item gets its own bullet in the PR body, so a reviewer (and pr-policy.mjs) can still find any item's own governance/RAG-impact statement.
  • Best candidates: queued docs/branch-review-ledger.md / docs/outstanding-issues.md append-only tasks — no revert risk of their own, always pass the same static gates.
  • Never bundle anything needing its own RAG impact:/Clinical Governance Preflight declaration together with something that doesn't, or anything explicitly scoped "1 PR per work order" (e.g. the maturity backlog, ledger #086).
• Mirrors the rationale + measured evidence into docs/process-hardening.md (next to the existing "Open PR branch sync" entry it complements).
• Adds a one-line nudge to .claude/skills/newtask/SKILL.md pointing at the new rule before a session mints a fresh branch.

Verification

• npm run verify:cheap — exit 0, Test Files 432 passed (432), Tests 4470 passed | 4 skipped (4474)
• npx prettier --check AGENTS.md docs/process-hardening.md .claude/skills/newtask/SKILL.md — clean
• npm run docs:check-links — 1378 repo path references resolve
• npm run check:skills — Database skill catalog valid: 33 canonical skills, 8 aliases
• grep -c "^## Dependency shortcut" AGENTS.md → 1 (that section's own self-check, unaffected by this edit)
• Verification not run: npm run verify:ui — no UI/routing/styling behavior changed. npm run eval:retrieval:quality / check:production-readiness — not applicable; no retrieval, ranking, ingestion, privacy, or Supabase behavior changed.

RAG impact: no retrieval behaviour change — no file under src/lib/rag/**, clinical-search, retrieval-selection, ranking-config, the eval harness, the golden fixture, or the retrieval RPCs is touched; scripts/pr-policy.mjs's own ragRankingPatterns/clinicalRiskPatterns do not match any changed path (AGENTS.md, docs/process-hardening.md, .claude/skills/newtask/SKILL.md).

Risk and rollout

• Risk: none to runtime or CI enforcement — this is a documentation/policy change only. No script, workflow, or gate behavior changed; the rule is guidance for future sessions, not an automated check.
• Rollback: revert the commit; nothing depends on it.
• Provider or production effects: None. No provider-backed command was run.

Clinical Governance Preflight

Not applicable — the diff touches only AGENTS.md, docs/process-hardening.md, and .claude/skills/newtask/SKILL.md. No ingestion, answer generation, search/ranking, source rendering, document access, privacy, production environment, or clinical output behavior is touched.

Notes

• This does not change the "1 PR per work order" convention already used for staged rollouts (e.g. docs/maturity-backlog-workorders.md, ledger #086) — those stay deliberately isolated.
• Bundling saves PR/CI-invocation count, not verification rigor: every bundled item still needs the smallest correct gate run against it before it joins a PR.

---

Generated by Claude Code

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:22 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

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

How do review limits work?

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

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, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 24a5834c-0f39-4af6-bedc-3046d8649b3c

📥 Commits

Reviewing files that changed from the base of the PR and between a4ebe12 and 2d509eb.

📒 Files selected for processing (3)

• .claude/skills/newtask/SKILL.md
• AGENTS.md
• docs/process-hardening.md

---

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

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[BigSimmo]

CI status: ci/circleci: verify failure looks systemic, not from this diff

The only red check right now is the legacy ci/circleci: verify commit status (not part of the required CI / pr-required GitHub Actions aggregate — that one and the other GH Actions checks are green/in-progress). It's currently failing identically across every recently-created open PR I sampled, regardless of diff content:

PR	Diff	CircleCI job	Status
#1397	docs/branch-review-ledger.md only	649	failure
#1406	docs/ledger only	662	failure
#1404	tests/CSS/CI config	668	failure
#1403	docs/outstanding-issues.md + ledger	666	failure
#1408 (this PR)	AGENTS.md / docs/process-hardening.md / newtask SKILL.md only	667	failure

All report the identical generic "Your tests failed on CircleCI" message — including two PRs whose diff is docs/branch-review-ledger.md only, which should hit .circleci/config.yml's docs-only fast-skip path (ci-change-scope.mjs → circleci-agent step halt) and never reach a real test step at all. That pattern points to a shared/environmental break (dependency install, Docker image pull, or a CircleCI-side issue) rather than anything in any one of these diffs.

This session has no CircleCI API/log access, and this status has no associated GitHub check-run ID to pull logs through, so I can't retrieve the actual failing step directly. What I can confirm locally, against this exact commit (752e8d2): npm run verify:cheap passed clean (Test Files 432 passed (432), Tests 4470 passed | 4 skipped (4474)), plus prettier --check, npm run docs:check-links, and npm run check:skills all green. Nothing in this PR's 3-file documentation diff is the cause.

Treating this as a base-level/systemic failure predating this diff rather than something to chase with a content push. I'll re-check when CircleCI recovers and report back if this PR's check clears on its own or turns out to be diff-specific after all.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:3c7cbae849

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:4be220d91f

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:e078477cbf

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:5ecfd97a1c

ℹ️ 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".