PerfectPan · PerfectPan · Jul 8, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.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
 
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.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:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -2,15 +2,40 @@
 
 -
 
+## Motivation
+
+-
+
+## Implementation Notes
+
+-
+
 ## Validation
 
+- [ ] Repository hygiene: `./scripts/repository-check.sh`
 - [ ] 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
+
+-
diff --git a/.github/workflows/repository-hygiene.yml b/.github/workflows/repository-hygiene.yml
@@ -0,0 +1,14 @@
+name: Repository Hygiene
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  repository-hygiene:
+    name: repository hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./scripts/repository-check.sh
diff --git a/.gitignore b/.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/
diff --git a/.gitlab/merge_request_templates/default.md b/.gitlab/merge_request_templates/default.md
@@ -0,0 +1,41 @@
+## Summary
+
+-
+
+## Motivation
+
+-
+
+## Implementation Notes
+
+-
+
+## Validation
+
+- [ ] Repository hygiene: `./scripts/repository-check.sh`
+- [ ] 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
+
+-
diff --git a/AGENTS.md b/AGENTS.md
@@ -13,9 +13,12 @@ This repository is intended to become a maintainable, publishable project. Treat
 
 ## Project-Specific Commands
 
-Replace these placeholders after choosing the project stack:
+Keep the repository-hygiene command active, and replace the remaining placeholders after choosing the project stack:
 
 ```bash
+# Repository hygiene:
+./scripts/repository-check.sh
+
 # Format:
 
 # Lint:
@@ -26,7 +29,7 @@ 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.
@@ -50,6 +53,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.
 
+## Delivery and Review Evidence
+
+- Treat `docs/delivery.md`, the PR/MR template, and CI as one shared delivery contract.
+- 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 +80,3 @@ rg --hidden --no-ignore -n "private-token|secret|internal-domain.example|HOME_PA
   --glob '!CONTRIBUTING.md' \
   --glob '!SECURITY.md'
 ```
-
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,4 +3,5 @@
 ## Unreleased
 
 - Initial project template.
-
+- Added a generic delivery and review contract for PR/MR evidence, validation gates, and repository hygiene.
+- Added local and CI-friendly repository checks for required template files, tracked local artifacts, obvious secrets, private paths, and review-template drift.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,6 +5,9 @@
 Replace this section with project-specific setup instructions.
 
 ```bash
+# run repository hygiene checks
+./scripts/repository-check.sh
+
 # install dependencies
 # run tests
 # run local app or CLI
@@ -18,7 +21,8 @@ Replace this section with project-specific setup instructions.
 4. Add or update tests for behavior changes.
 5. Update `CHANGELOG.md` for user-facing changes.
 6. Run format, lint, test, and build checks.
-7. Open a pull request with motivation, implementation notes, validation, and follow-up risks.
+7. Run repository hygiene checks before review.
+8. Open a pull request or merge request with motivation, implementation notes, validation, and follow-up risks.
 
 Small typo corrections, narrow documentation fixes, and repository metadata updates do not need an RFC.
 
@@ -27,6 +31,9 @@ Small typo corrections, narrow documentation fixes, and repository metadata upda
 Replace these placeholders after choosing the project stack:
 
 ```bash
+# Repository hygiene:
+./scripts/repository-check.sh
+
 # Format:
 
 # Lint:
@@ -54,20 +61,25 @@ RFCs should describe the problem, goals, non-goals, proposed design, alternative
 
 ## Pull Request Expectations
 
-Every PR should answer:
+Every PR or MR should answer:
 
 - What changed?
 - Why is this change needed?
 - How was this tested?
 - Are there follow-up tasks or risks?
+- What evidence proves the behavior, packaging, or deployment claim?
+- Which validation gates were skipped, and why?
+
+Update the description when review feedback, rebases, or follow-up commits change the scope or validation result. Reviewers should be able to understand the final state from the PR/MR without reconstructing it from comments.
 
 ## Repository Hygiene
 
 Do not commit private tokens, local config, generated workspaces, internal hostnames, or personal filesystem paths.
 
 Keep package or deploy contents intentional. If a file should ship, verify it appears in the package or deployment dry-run.
 
+Run `./scripts/repository-check.sh` locally before opening review. This generic check does not replace stack-specific tests, but it catches missing template files, tracked local artifacts, obvious secrets, private paths, and drift in review templates.
+
 ## Security Reports
 
 Use `SECURITY.md` for vulnerability reporting guidance. Do not include secrets, exploit details, or private infrastructure in public issues or pull requests.
-
diff --git a/README.md b/README.md
@@ -10,21 +10,26 @@ Use this template when creating a new project that should have consistent contri
 2. Replace this README with the new project's name, purpose, and quick start.
 3. Fill in the project-specific validation commands in `AGENTS.md` and `CONTRIBUTING.md`.
 4. Choose the actual implementation stack and add the source layout.
-5. Update `CHANGELOG.md` for the first release.
-6. Keep or replace `LICENSE` according to the project needs.
+5. Enable or replace the stack-specific CI example in `.github/workflows/ci.yml.example`.
+6. Run `./scripts/repository-check.sh` and keep it in CI as a generic repository-hygiene gate.
+7. Update `CHANGELOG.md` for the first release.
+8. Keep or replace `LICENSE` according to the project needs.
 
 ## Included
 
 - `AGENTS.md` for agent workflow rules.
 - `CLAUDE.md` for Claude Code entrypoint instructions.
 - `CONTRIBUTING.md` for human contribution flow.
 - `SECURITY.md` for vulnerability and sensitive data reporting.
+- `docs/delivery.md` for the cross-project delivery and evidence contract.
 - `.github/pull_request_template.md` for PR summaries and validation.
 - `.github/ISSUE_TEMPLATE/` for bug and feature reports.
+- `.github/workflows/repository-hygiene.yml` for generic repository-hygiene checks.
+- `.gitlab/merge_request_templates/default.md` for GitLab-style MR summaries.
 - `rfcs/0000-template.md` for substantial design changes.
+- `scripts/repository-check.sh` for local and CI repository hygiene checks.
 - `.editorconfig` for consistent text formatting.
 
 ## Template Maintenance
 
 Keep this repository generic. Do not add language-specific package files, framework defaults, generated output, or project-specific business logic.
-
diff --git a/docs/delivery.md b/docs/delivery.md
@@ -0,0 +1,49 @@
+# Delivery Contract
+
+This template keeps delivery and review expectations technology-agnostic. A new project should replace stack-specific placeholders, but keep the evidence, validation, and repository hygiene contract intact.
+
+## Required Project Wiring
+
+Every project created from this template should define:
+
+- project purpose and quick start in `README.md`
+- setup, contribution, and validation commands in `CONTRIBUTING.md`
+- agent workflow and required commands in `AGENTS.md`
+- vulnerability and sensitive-data reporting in `SECURITY.md`
+- a PR or MR template that asks for motivation, implementation notes, validation, evidence, and risks
+- CI that runs `./scripts/repository-check.sh` plus stack-specific format, lint, test, build, and package or release dry-run commands
+- an RFC path for changes that affect public behavior, trust boundaries, configuration shape, rollout, rollback, or repository structure
+
+## Review Evidence Standard
+
+PRs and MRs should be reviewable from their final description. The description should name:
+
+- what changed and why
+- domain boundaries, data flow, or public contracts touched by the change
+- exact commands run, with skipped gates and concrete blockers
+- logs, screenshots, package output, deployed URLs, or other artifacts that prove user-visible claims
+- compatibility, migration, rollout, rollback, and follow-up risks
+
+When review feedback changes the code or validation result, update the PR/MR description instead of leaving the final state buried in comments.
+
+## Repository Hygiene Gate
+
+`./scripts/repository-check.sh` is intentionally small and stack-neutral. It checks:
+
+- required template files exist
+- GitHub PR and GitLab MR templates keep the same required sections
+- local artifacts and generated output are not tracked
+- obvious credentials, private keys, local filesystem paths, and placeholder private references do not appear in tracked content
+
+This gate does not replace project-specific tests. It is the baseline every project can run before choosing a stack.
+
+## First-Project Checklist
+
+After creating a real project from this template:
+
+- replace placeholder validation commands in `AGENTS.md` and `CONTRIBUTING.md`
+- keep `.github/workflows/repository-hygiene.yml` enabled unless the project has an equivalent hygiene gate
+- copy or adapt `.github/workflows/ci.yml.example` into a real stack CI workflow
+- add `.env.example` or equivalent configuration documentation if runtime configuration is needed
+- run format, lint, tests, build, package or release dry-run, and `./scripts/repository-check.sh`
+- update `CHANGELOG.md` for the first user-facing release