docs(repo): define branch lifecycle

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,19 @@
 ### Description
 Please include a summary of the change and which issue is fixed. Also include relevant motivation and context.
 
+### Slice
+
+- Issue: #
+- Scope / owning surface:
+- Dependencies or overlapping PRs: None
+
 <details>
 <summary>Checklist</summary>
 
+- [ ] This branch started from current `staging` and does not include another unmerged PR unless it is named above.
+- [ ] This is one independently reviewable slice; unrelated cleanup or refactors are in separate PRs.
+- [ ] I checked open PRs for overlapping files, contracts, schemas, or deployment configuration and made any dependency explicit above.
+- [ ] This PR targets `staging`; after it closes, this branch will not be reused for another change.
 - [ ] My code follows the style guidelines of this project
 - [ ] I have performed a self-review of my code
 - [ ] I have commented my code, particularly in hard-to-understand areas
@@ -12,4 +22,4 @@ Please include a summary of the change and which issue is fixed. Also include re
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes 
 
-</details>
+</details>

AGENTS.md

@@ -153,7 +153,15 @@ For picker controls, use the component that matches the interaction:
   - For broad migrations, follow the repo’s existing pattern: one commit per meaningful area, e.g. `feat(dashboard): migrate home, events, insights, and links pages to shared UI components`.
   - Before committing, check `git diff --stat` and `git status --short`; if the diff mixes unrelated intents, split it.
   - Only make a single snapshot commit for the whole worktree when the user explicitly asks to include everything as-is.
-- **PRs**: Open against `staging` branch (not `main`).
+
+## Branch and PR Lifecycle
+
+- **One task, one branch, one PR**: Keep a branch to one independently reviewable and reversible slice. If work can land separately, split it before it becomes a mixed PR.
+- **Start fresh**: Check for an existing PR that owns the same surface, public contract, schema, or deployment configuration, then create the branch from an up-to-date `origin/staging`. Do not use an unmerged feature branch as a base unless the dependency is explicit, approved, and named as `Depends on #…` in both PRs.
+- **Make ownership visible**: Push and open a draft PR against `staging` once the slice has a first commit. State its scope, dependencies, and known overlaps.
+- **Keep integration linear**: Rebase a slice onto current `origin/staging` before it is ready for review; do not merge `staging` into the slice merely to refresh it. Request fresh review when a rebase changes reviewed code.
+- **Isolate parallel work**: Use one worktree per active branch. Never let two agents or contributors mutate the same branch or reuse a task branch for a different concern.
+- **Retire completed work**: Merged PR source branches are automatically deleted. Delete closed PR branches manually, remove clean finished worktrees, and create a new branch from current `staging` for any follow-up—never revive or repurpose an old PR branch.
 
 ## CI and Review Lessons
 

CONTRIBUTING.md

@@ -100,42 +100,72 @@ You can also `cd` into any package and run its scripts directly.
 
 ### Development Workflow
 
-1. Create a new branch:
+#### Branch and PR lifecycle
+
+Keep each branch short-lived: one branch, one independently reviewable and
+revertible slice, one pull request. Do not use a branch as a general work
+queue.
+
+1. Before starting, check open pull requests for the same surface, public
+   contract, schema, or deployment configuration. Update `staging`, then create
+   a fresh branch from it:
 
 ```bash
-git checkout -b feature/your-feature
+git switch staging
+git pull --ff-only origin staging
+git switch -c codex/short-slice
 ```
 
-2. Make your changes
+   Do not branch from another feature branch. An exception needs an explicit
+   `Depends on #…` in both PRs and agreement from its owner; land the
+   prerequisite first.
+
+2. Keep the branch to its stated slice. If a change can be reviewed or reverted
+   independently, open a separate branch and PR; leave unrelated cleanup and
+   refactors out of the current one.
+
+3. Push early and open a draft PR against `staging`. State the problem being
+   solved and any dependency or known overlap. This makes ownership visible
+   before parallel work drifts into the same files.
+
+4. Before requesting review, rebase onto the current `origin/staging` and
+   resolve the conflicts in the slice. Do not merge `staging` into a feature
+   branch just to refresh it. If the rebase changes reviewed code, request a
+   fresh review.
 
-3. Run tests:
+5. Run the relevant checks:
 
 ```bash
 bun run test
 ```
 
-4. Create a changeset:
+6. Create a changeset when the change affects a published package:
 
 ```bash
 bun run changeset
 ```
 
-5. Commit your changes:
+7. Commit your changes:
 
 ```bash
 git add .
 git commit -m "feat: your feature"
 ```
 
-6. Push your changes:
+8. Push your changes:
 
 ```bash
-git push origin feature/your-feature
+git push -u origin codex/short-slice
 ```
 
-Note: Open a pull request to the STAGING branch
+9. When the PR is merged or closed, retire the branch. GitHub automatically
+   deletes merged source branches; delete a closed branch manually. Never
+   repurpose or reopen an old branch for a new slice—start again from current
+   `staging`.
 
-7. Create a Pull Request
+For parallel work, use one worktree per branch and never have two people or
+agents mutate the same branch. Remove a worktree only after its work is merged,
+closed, or safely moved to a new branch.
 
 
 ## Code Style