docs: complete pull request workflow

[boh5]

Summary

• document the complete Agent PR state machine and authorization boundaries
• require latest-head validation and review after every pushed fix
• document merge guards, local main synchronization, and release verification
• add git diff --check to contributor and PR checklists

Why

The existing guidance described the repository gates, but it did not fully capture the review-fix loop, latest-head merge guard, post-merge synchronization, or the distinction between requested GitHub state changes. This made it possible for an Agent to stop early or merge based on stale review state.

Validation

• bun run typecheck
• bun run test
• bun run build when the production package or Web UI is affected — not required for documentation-only changes
• git diff --check

Documentation and security

• I updated user-facing documentation when behavior, setup, or configuration changed.
• No product behavior changed, so no tests needed to be added or updated.
• I did not commit credentials, tokens, private configuration, or generated secrets.
• This documentation-only change has no security or trust-boundary impact.

Related issue

None

Summary by CodeRabbit

• Documentation
  • Added whitespace validation to the pull request checklist and required validation commands.
  • Expanded contribution guidance for fork-specific remotes, post-push reviews, pre-merge checks, and post-merge branch synchronization.
  • Clarified repository workflow steps, including CI review, conversation checks, branch selection, and release verification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e5644abe-e6bc-4c91-abe0-d980d61c88e9

📥 Commits

Reviewing files that changed from the base of the PR and between b8153c1 and 1d05fd0.

📒 Files selected for processing (3)

• .github/pull_request_template.md
• AGENTS.md
• CONTRIBUTING.md

🚧 Files skipped from review as they are similar to previous changes (2)

• .github/pull_request_template.md
• CONTRIBUTING.md

---

📝 Walkthrough

Walkthrough

The pull request updates repository guidance for git diff --check, fork remotes, post-push review, pre-merge verification, post-merge synchronization, and release verification.

Changes

PR workflow guidance

Layer / File(s)	Summary
Validation requirements .github/pull_request_template.md, CONTRIBUTING.md	The PR checklist and validation commands now require git diff --check. Fork contributors can use upstream instead of origin.
PR and release lifecycle controls AGENTS.md, CONTRIBUTING.md	The workflow guidance now covers scope checks, post-push reviews, pre-merge verification, post-merge synchronization, and release verification.

Possibly related PRs

• boh5/archcode#2: This PR extends the same contribution workflow documentation and pull request template.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the documentation changes that complete the pull request workflow.
Description check	✅ Passed	The description follows the repository template and includes the change summary, rationale, validation, security, and related issue status.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/pull_request_template.md:
- Line 16: Update the git diff --check command in
.github/pull_request_template.md at line 16, CONTRIBUTING.md at line 71, and
AGENTS.md at line 524 to inspect staged changes using git diff --cached --check
(or the complete pending diff with git diff HEAD --check), keeping all three
locations consistent.

In `@AGENTS.md`:
- Line 523: Use one fork-aware canonical remote consistently throughout the
workflow: update AGENTS.md lines 523-523 to use the selected canonical remote
when creating the feature branch, update CONTRIBUTING.md lines 108-115 to fetch
and fast-forward from that same remote when working from a fork, and update
AGENTS.md lines 528-528 to reuse it for post-merge synchronization. Keep the
existing distinction between requested state-changing actions unchanged.
- Line 529: Update the release verification guidance near the release workflow
checks to require comparing the release tag target with the exact intended
merged commit, rather than only verifying that tag_commit is an ancestor of
origin/$DEFAULT_BRANCH. Alternatively, narrow the claim in AGENTS.md so it no
longer asserts exact merged-commit verification.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9c2679ef-dc54-4aa3-a915-bbb853df2ac5

📥 Commits

Reviewing files that changed from the base of the PR and between 3dd05f7 and b8153c1.

📒 Files selected for processing (3)

• .github/pull_request_template.md
• AGENTS.md
• CONTRIBUTING.md

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>