docs: add review workflow checks

.githooks/pre-commit

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+git diff --cached --check
+./scripts/check-repository.sh --staged

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,12 +21,23 @@ assignees: ""
 ## Actual Behavior
 
 
+## Evidence
+
+- Logs, screenshots, traces, or failing command:
+- First known bad version or commit:
+- Workaround, if any:
+
 ## Environment
 
 - OS:
 - Runtime:
 - Version:
 
-## Additional Context
+## Impact
 
+- User-visible impact:
+- Data, security, or compatibility risk:
+- Release or rollback urgency:
+
+## Additional Context
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -12,6 +12,18 @@ assignees: ""
 ## Proposed Solution
 
 
+## Acceptance Criteria
+
+-
+
+## Validation Plan
+
+- Format:
+- Lint:
+- Test:
+- Build:
+- Package or release dry-run:
+
 ## Alternatives Considered
 
 
@@ -21,4 +33,5 @@ assignees: ""
 - Configuration:
 - Compatibility:
 - Documentation:
-
+- Security or privacy:
+- Rollout and rollback:

.github/pull_request_template.md

@@ -1,16 +1,46 @@
+Title format: `type(scope): summary`
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
+
 ## Summary
 
 -
 
+## Motivation
+
+-
+
+## Implementation Notes
+
+-
+
 ## Validation
 
+- [ ] Repository checks: `./scripts/check-repository.sh`
+- [ ] PR title: `./scripts/check-pr-title.sh "<title>"`
 - [ ] Format:
 - [ ] Lint:
 - [ ] Test:
 - [ ] Build:
 - [ ] Package or release dry-run:
 
-## Follow-up Risks
+Skipped gates and reasons:
 
 -
 
+## Evidence
+
+- Linked issue/task/RFC:
+- Logs, screenshots, package output, or deployed artifact:
+- Reviewer notes that changed the final scope:
+
+## 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 behavior, docs, changelog, migrations, or rollback notes are updated when relevant.
+- [ ] The branch is current enough for review, and the remote head matches the intended commit.
+
+## Follow-up Risks
+
+-

.github/workflows/review.yml

@@ -0,0 +1,25 @@
+name: Review
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize, ready_for_review]
+  push:
+    branches: [main]
+
+jobs:
+  repository-checks:
+    name: repository checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./scripts/check-repository.sh
+
+  pr-title:
+    name: conventional PR title
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./scripts/check-pr-title.sh "$PR_TITLE"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}

.gitignore

@@ -3,4 +3,21 @@
 .env.*
 *.log
 .omx/
+.codex/
+.claude/settings.local.json
 
+# Dependency and tool caches
+node_modules/
+.cache/
+.turbo/
+.next/
+.vite/
+.pytest_cache/
+__pycache__/
+
+# Generated output
+dist/
+build/
+coverage/
+tmp/
+temp/

.gitlab/merge_request_templates/default.md

@@ -0,0 +1,46 @@
+Title format: `type(scope): summary`
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
+
+## Summary
+
+-
+
+## Motivation
+
+-
+
+## Implementation Notes
+
+-
+
+## Validation
+
+- [ ] Repository checks: `./scripts/check-repository.sh`
+- [ ] MR title: `./scripts/check-pr-title.sh "<title>"`
+- [ ] Format:
+- [ ] Lint:
+- [ ] Test:
+- [ ] Build:
+- [ ] Package or release dry-run:
+
+Skipped gates and reasons:
+
+-
+
+## Evidence
+
+- Linked issue/task/RFC:
+- Logs, screenshots, package output, or deployed artifact:
+- Reviewer notes that changed the final scope:
+
+## 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 behavior, docs, changelog, migrations, or rollback notes are updated when relevant.
+- [ ] The branch is current enough for review, and the remote head matches the intended commit.
+
+## Follow-up Risks
+
+-

AGENTS.md

@@ -13,9 +13,21 @@ This repository is intended to become a maintainable, publishable project. Treat
 
 ## Project-Specific Commands
 
-Replace these placeholders after choosing the project stack:
+Keep the generic review commands active, and replace the remaining placeholders after choosing the project stack:
 
 ```bash
+# Install local Git hooks:
+./scripts/install-git-hooks.sh
+
+# Repository checks:
+./scripts/check-repository.sh
+
+# PR/MR title check:
+./scripts/check-pr-title.sh "docs: update project template"
+
+# GitHub repository setup dry run:
+./scripts/configure-github-repository.sh --repo OWNER/REPO
+
 # Format:
 
 # Lint:
@@ -26,17 +38,40 @@ Replace these placeholders after choosing the project stack:
 
 # Package or release dry-run:
 
-# Security or hygiene scan:
+# Security or package-specific hygiene scan:
 ```
 
 Do not claim implementation work is complete until the relevant commands pass, or until skipped commands are explained with concrete blockers.
 
+## Development Workflow
+
+For non-trivial changes:
+
+1. Understand the requested behavior, affected domain concepts, ownership boundaries, and data flow.
+2. Decide whether the change needs an RFC before implementation.
+3. Keep the implementation scoped to the task and nearby code.
+4. Update tests and documentation when behavior, public contracts, or workflow expectations change.
+5. Ensure local Git hooks are installed for the checkout when practical.
+6. Run repository checks, title checks, and project-specific validation gates.
+7. For a newly created GitHub repository, configure branch protection with `scripts/configure-github-repository.sh --repo OWNER/REPO --apply` using an admin-authorized account.
+8. Open or update the PR/MR with motivation, implementation notes, exact validation, skipped gates, evidence, and risks.
+
+## Repository Architecture
+
+- Organize code by domain boundaries, layer boundaries, and test boundaries before mechanical one-file-per-export preferences.
+- Keep domain rules, application services, infrastructure adapters, UI/CLI entrypoints, persistence, and test fixtures separated when those responsibilities exist.
+- Do not introduce a shared abstraction unless it removes real duplication, clarifies a boundary, or matches an existing project pattern.
+- When a file starts mixing multiple responsibilities or layers, split by responsibility rather than by arbitrary size.
+- Substantial changes to public behavior, configuration shape, trust boundaries, release process, or repository structure should be proposed in `rfcs/` first.
+
 ## Documentation
 
 - Keep `README.md` focused on orientation, quick start, and current user-facing behavior.
 - Use `CONTRIBUTING.md` for contribution workflow.
 - Use `rfcs/` for substantial design proposals.
+- Use `docs/` for durable current-state knowledge such as architecture, development guides, operational runbooks, references, and onboarding tutorials.
 - Update `CHANGELOG.md` for user-facing changes unless the change is docs-only or repository-only.
+- When behavior, configuration, commands, APIs, deployment, architecture, or operations change, update the relevant docs in the same PR/MR or explain why no docs changed.
 
 ## AI Delivery Workflow
 
@@ -50,6 +85,14 @@ When an AI agent completes implementation work:
 6. Create or reuse a GitHub Pull Request when the task is not landing directly on `main`.
 7. Include a delivery summary with motivation, implementation notes, validation, and follow-up risks.
 
+## Review Evidence
+
+- PR/MR titles must follow `type(scope): summary`; use `scripts/check-pr-title.sh` to verify them.
+- PR/MR descriptions must include motivation, implementation notes, exact validation commands, skipped gates with reasons, and follow-up risks.
+- If a claim depends on logs, screenshots, package output, deployed behavior, or generated artifacts, attach or link the evidence in the PR/MR.
+- Update the PR/MR description after substantial code changes, review-driven revisions, rebases that change behavior, or validation reruns.
+- Keep GitHub PR and GitLab MR templates in sync if the project uses both hosting styles.
+
 ## Git
 
 - Branch names should be short and descriptive, such as `feat/release-source`.
@@ -69,4 +112,3 @@ rg --hidden --no-ignore -n "private-token|secret|internal-domain.example|HOME_PA
   --glob '!CONTRIBUTING.md' \
   --glob '!SECURITY.md'
 ```
-

CHANGELOG.md

@@ -3,4 +3,8 @@
 ## Unreleased
 
 - Initial project template.
-
+- Added a generic review workflow for repository checks and conventional PR titles.
+- Added local and CI-friendly repository checks for required template files, tracked local artifacts, obvious secrets, private paths, and review-template drift.
+- Added installable local pre-commit hooks for staged whitespace and staged repository checks.
+- Added a post-create GitHub repository setup script for default branch protection.
+- Added documentation standards, contribution and agent guidance for review evidence, validation gates, and repository architecture maintenance.