docs: load Git guidance on demand [skip ci]

.gitignore

@@ -117,6 +117,8 @@ docs/**
 !docs/bug-reproductions/
 !docs/bug-reproductions/**
 !docs/STYLEGUIDE.md
+!docs/reference/
+!docs/reference/git-workflow.md
 !docs/audits/
 !docs/audits/crashpad-read-limit/
 !docs/audits/crashpad-read-limit/source-hashes.json

AGENTS.md

@@ -41,10 +41,6 @@ Avoid type assertions except `as const`. Unavoidable casts need a line-specific
 - **Lint**: `oxlint`, or `pnpm run check:code-quality:changed` for changed files (full `pnpm lint` is slow); format with `pnpm format`
 - **Design system**: `pnpm run lint:design-system` for the full renderer report (not a gate); the changed-lines gate above is what CI enforces
 
-## Merging Pull Requests
-
-Before merging, verify that the required checks and aggregate gate in the full PR workflow have pass.
-
 # Considerations
 
 ## Worktree Safety
@@ -86,20 +82,6 @@ The execution host owns agent status in one store, the hook server's, and every
 
 Clients and remote Orca servers update independently, so mixed versions are the normal state.
 
-## Git Binary Compatibility
+## Git and Review Work
 
-Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline.
-
-## Git Scan Safety
-
-- Never enumerate every ref and then run `git ls-tree -r` or `git show` once per ref. That ref × tree fan-out can retain gigabytes of output before a downstream `sort -u` or search can make progress.
-- Prefer `rg` over the checked-out files for source searches. For history or refs, use a named ref, an explicit namespace/path, `--max-count`, and a bounded output; do not use an unqualified `--all` scan as a first diagnostic.
-- Keep repository-wide commands targeted to the current repository and worktree. If an unbounded scan is genuinely required, measure the ref count first, explain the cost, and get confirmation before running it.
-
-## Git Provider Compatibility
-
-Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
-
-## GitHub CLI Usage
-
-Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
+Before running Git or `gh` commands, changing source-control or review behavior, or merging a pull request, read [`docs/reference/git-workflow.md`](./docs/reference/git-workflow.md).

docs/reference/git-workflow.md

@@ -0,0 +1,23 @@
+# Git and Review Work
+
+## Git Binary Compatibility
+
+Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline.
+
+## Git Scan Safety
+
+- Never enumerate every ref and then run `git ls-tree -r` or `git show` once per ref. That ref × tree fan-out can retain gigabytes of output before a downstream `sort -u` or search can make progress.
+- Prefer `rg` over the checked-out files for source searches. For history or refs, use a named ref, an explicit namespace/path, `--max-count`, and a bounded output; do not use an unqualified `--all` scan as a first diagnostic.
+- Keep repository-wide commands targeted to the current repository and worktree. If an unbounded scan is genuinely required, measure the ref count first, explain the cost, and get confirmation before running it.
+
+## Git Provider Compatibility
+
+Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
+
+## GitHub CLI Usage
+
+Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
+
+## Merging Pull Requests
+
+Before merging, verify that the required checks and aggregate gate in the full PR workflow have pass.