> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgtex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Branching and Pull Requests

> The concise contract and protected path for Corgtex changes.

## Branching

* New work starts from current `origin/main` in a clean task branch/worktree.
* Continue an existing branch only when the task explicitly names that work.
* Never reset, stash, overwrite, or mix unrelated work.
* Default to one branch and PR for one complete outcome. Split only at independently
  useful, safe, testable, deployable, and rollbackable boundaries.

## PR contract

Copy [`/.agents/plan-template.md`](https://github.com/Corgtexdotcom/corgtex/blob/main/.agents/plan-template.md)
into the PR body and keep these sections current:

* outcome;
* `low`, `standard`, `high`, or `critical` risk;
* scope and file allowlist;
* concrete acceptance checklist;
* executable tests;
* actual visual proof for frontend paths; and
* realistic risk and rollback.

Before a PR exists, an ignored local copy may live at `.agents/plans/<branch>.md`.
The PR body is public metadata: never include secrets, credentials, or private client
facts.

## CI and review

Every PR runs:

* `Lint, Typecheck & Test`;
* `Database Sync`;
* database-independent `Build`;
* `Docs Validation`;
* `PR Policy`;
* `PR Metadata Policy`;
* `Secret Scan`; and
* `Client Data Scan`.

`PR Policy` checks the contract, declared files, critical handling of protected
paths, acceptance completion, domain tests, frontend proof, environment files, and
forbidden executable patterns. It does not enforce arbitrary line or file limits.
Head, PR-body, label, draft-state, and merge-group changes refresh the distinct
trusted metadata policy status without rerunning expensive code checks. Invalid
metadata removes the PR from the queue. The legacy snapshot gate remains required
during staged activation and is removed only after the replacement is proven.

The independent reviewer reads the complete current diff and requests changes only
for objective blockers. Native GitHub rules dismiss stale approvals, require the
latest push to be approved, require conversations and status checks to pass, and
send the result through the merge queue.

## Frontend proof

Run the application and capture the actual changed behavior. Keep captures under
ignored `.artifacts/`, upload with `node scripts/upload-build-artifacts.mjs`, and
paste the link into the PR. Use a private artifact when the proof contains private
data. Never commit generated screenshots or recordings.

## Labels

* `halt-agents`: stop work and review.
* `needs-replan`: the bounded correction loop reached a genuine impasse.
* `auto-revert`: a protected recovery PR.
* `force-merge`: rare explicit human bypass with a public audit comment.

Labels do not waive secrets, tests, data safety, `prisma db push`, or `--no-verify`.