docs: add review workflow checks

[PerfectPan]

Summary

• Add a generic review workflow with repository checks and conventional PR title validation.
• Add installable local pre-commit hooks that run staged whitespace and staged repository checks.
• Add a post-create GitHub repository setup script for default branch protection.
• Strengthen agent, contribution, RFC, and docs guidance around review evidence, validation gates, documentation standards, and repository architecture maintenance.

Motivation

This template should make the reusable project workflow explicit without overloading terms like harness or delivery. The core template needs local commit-time guardrails, a clear review path, conventional PR/MR titles, repository checks, documentation boundaries, architecture stewardship guidance, and a concrete place to configure branch protection after each repository is created.

Implementation Notes

• .githooks/pre-commit runs git diff --cached --check and ./scripts/check-repository.sh --staged before local commits.
• scripts/install-git-hooks.sh installs the local hook by setting core.hooksPath to .githooks and refuses to overwrite an existing custom hooks path unless --force is provided.
• .github/workflows/review.yml runs repository checks on pushes to main and PRs, and runs conventional PR title when PRs are opened, edited, reopened, synchronized, or marked ready for review.
• scripts/check-repository.sh checks required template files, tracked generated/local artifacts, obvious secrets/private paths, and PR/MR template drift. It supports a --staged mode for commit hooks.
• scripts/check-pr-title.sh enforces type(scope): summary with conventional types.
• scripts/configure-github-repository.sh is the post-create setup entrypoint for GitHub branch protection. It defaults to dry-run, infers the GitHub default branch when gh is available, requires --branch when it cannot infer, and only updates GitHub when called with --apply.
• docs/README.md defines the docs boundary: current architecture, development guides, operational runbooks, references, and onboarding tutorials belong in docs/; proposals and decision history belong in rfcs/; collaboration policy and AI-agent instructions stay in CONTRIBUTING.md and AGENTS.md.

Validation

• Repository checks: ./scripts/check-repository.sh
• Staged repository checks: ./scripts/check-repository.sh --staged
• Pre-commit success path: .githooks/pre-commit
• PR title check: ./scripts/check-pr-title.sh "docs: add review workflow checks"
• Invalid title check rejects Update docs
• Git hooks install/overwrite behavior: scripts/install-git-hooks.sh preserves an existing custom core.hooksPath unless --force is passed
• GitHub setup dry run with gh: ./scripts/configure-github-repository.sh --repo PerfectPan/project-template
• GitHub setup dry run without gh but explicit branch: PATH=/usr/bin:/bin ./scripts/configure-github-repository.sh --repo PerfectPan/project-template --branch main
• GitHub setup without gh and without branch fails with a concrete error
• Whitespace checks: git diff --check and git diff --cached --check
• Residual naming scan for old harness, delivery.md, and repository-hygiene terms
• Format: skipped, no project formatter is configured in this stack-neutral template.
• Lint: skipped, no project linter is configured in this stack-neutral template.
• Test: skipped, no stack-specific test runner is configured.
• Build: skipped, no build command is configured.
• Package or release dry-run: skipped, no package command is configured.

Evidence

• Commit amend output showed the installed pre-commit hook running check-repository: ok (staged).
• Setup dry-run prints branch protection for main, requiring one approving review, stale review dismissal, last-push approval, linear history, resolved conversations, and the repository checks / conventional PR title status checks.
• The no-gh dry-run path fails unless --branch is passed, so it does not silently guess main in environments that cannot inspect GitHub.
• Residual naming scan for harness, delivery.md, repository-hygiene, and old script paths returned no matches.

Safety Checklist

• No credentials, tokens, private hostnames, personal filesystem paths, or generated logs are included.
• Local config, generated output, build artifacts, and temporary workspaces are not staged.
• User-facing template docs and changelog are updated.
• Branch name and PR title use review workflow naming.
• Branch protection setup is documented and dry-run by default, not applied implicitly by CI.

Follow-up Risks

• Projects still need to replace stack-specific command placeholders after choosing their language/framework.
• Git hooks are local and can be missing or bypassed; CI and branch protection remain the authoritative enforcement.
• GitLab MR title enforcement is documented through the shared script/template, but no GitLab CI example is included yet.
• GitHub branch protection setup requires a GitHub account or token with permission to edit repository settings.