Skip to content

feat(pr): org-wide PR template kit v1.0.0 with intent reconciliation and gates - #15

Merged
cryptoxdog merged 10 commits into
mainfrom
feat/pr-templates
Jul 29, 2026
Merged

feat(pr): org-wide PR template kit v1.0.0 with intent reconciliation and gates#15
cryptoxdog merged 10 commits into
mainfrom
feat/pr-templates

Conversation

@cryptoxdog

@cryptoxdog cryptoxdog commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Problem

The org has a single flat PULL_REQUEST_TEMPLATE.md with no enforcement — PR quality (problem statement, risk assessment, evidence) depends entirely on author discipline.

Fix

Deploys pr-template-kit v1.0.0 (sha256-verified against MANIFEST.json):

  • .github/pull_request_template.md — default template: Problem → Fix → Risk → Evidence → Gates → Reviewer focus → Changes by intent → Files touched
  • .github/PULL_REQUEST_TEMPLATE/EXAMPLE.md — fully worked reference PR
  • .github/PULL_REQUEST_TEMPLATE/infra.md — terraform plan, blast radius, IAM gates
  • .github/PULL_REQUEST_TEMPLATE/release.md — changelog, version-bump gates
  • .github/workflows/pr-files.yml — writes Files touched block, reconciles intent vs diff
  • .github/workflows/pr-gates.yml — validates Problem/Risk/Evidence/Gates
  • docs/DEPLOY.md — 5-step rollout + rollback runbook
  • docs/DESIGN.md — rationale for each section

Both workflows ship with minimal top-level permissions: blocks and actions pinned to full commit SHAs (actions/checkout@11bd719, actions/github-script@60a0d83).

Risk

  • Low — templates only take effect for new PRs opened after merge.
  • Existing repos with local templates are unaffected (local overrides win).
  • Workflows in this .github repo do not auto-run for other repos; distribution requires workflow_call callers or sync (see rollout).
  • The legacy root PULL_REQUEST_TEMPLATE.md is left in place; GitHub prefers .github/pull_request_template.md, so this PR's template wins. Delete or merge the legacy governance checklist in a follow-up.

Evidence

$ python3 verify_manifest.py kit/dot-github
MANIFEST.json sha256 verification: 10/10 PASS
pr-files.yml  remote sha256 b7185315...742fec9  == MANIFEST  MATCH
pr-gates.yml  remote sha256 6ab39da7...91ea04   == MANIFEST  MATCH
yaml.safe_load: 2/2 workflows parse OK
  • All 10 kit files verified against MANIFEST.json sha256 + byte counts before install.
  • Both workflows parse as valid YAML.
  • Remote branch copies re-verified byte-identical to kit checksums:
    • pr-files.yml b7185315…742fec9
    • pr-gates.yml 6ab39da7…91ea04

Changes by intent

  • Templates: .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE/EXAMPLE.md, .github/PULL_REQUEST_TEMPLATE/infra.md, .github/PULL_REQUEST_TEMPLATE/release.md
  • Enforcement workflows: .github/workflows/pr-gates.yml, .github/workflows/pr-files.yml
  • Documentation: docs/DEPLOY.md, docs/DESIGN.md

Rollout (from docs/DEPLOY.md)

  1. Merge to main — templates take effect immediately for new PRs.
  2. Distribute workflows via workflow_call callers pinned to @v1 (see ops/tag-v1.sh).
  3. Warn-only week first (comment out core.setFailed), then make PR gates / check and PR files touched / annotate required via org ruleset.
  4. Smoke test: an untouched template should fail gates (empty Problem, no Risk box, no Evidence).

Files touched

8 files — 8 files changed, 604 insertions(+)

.github/

  • pull_request_template.md — added

.github/PULL_REQUEST_TEMPLATE/

  • EXAMPLE.md — added
  • infra.md — added
  • release.md — added

.github/workflows/

  • pr-files.yml — added
  • pr-gates.yml — added

docs/

  • DEPLOY.md — added
  • DESIGN.md — added

@sonarqubecloud

Copy link
Copy Markdown

@cryptoxdog
cryptoxdog merged commit 4f98218 into main Jul 29, 2026
5 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant