Skip to content

feat(policy): warn on consumer PR-template drift (template conformance guard)#54

Merged
ArchonVII merged 2 commits into
mainfrom
feat/53-template-conformance-guard
Jun 7, 2026
Merged

feat(policy): warn on consumer PR-template drift (template conformance guard)#54
ArchonVII merged 2 commits into
mainfrom
feat/53-template-conformance-guard

Conversation

@ArchonVII

Copy link
Copy Markdown
Owner

Summary

A consumer repo's .github/PULL_REQUEST_TEMPLATE.md is copied at onboarding and tracked by nothing afterward, so it silently rots out of sync with the strict PR contract. When repo-template adopted the strict structure on 2026-05-31, onboarded repos kept their pre-strict copies — and filling out the repo's own template verbatim then fails repo-required-gate / pr contract with missing_heading: ### Verification Notes. This bit hudson-bend (#43) and was found in archon + jma-ui. Diagnosed via /page-gm.

This adds a warning-first guard:

  • validatePrTemplate + formatPrTemplateResult in scripts/pr-contract.mjs — structure-only (headings present + in order; no checked-box/placeholder/substance checks, which a template legitimately lacks).
  • A warning-only step in repo-required-gate.yml's pr-contract job that fetches the caller's committed template and surfaces drift directly. Never hard-fails (Phase 1, matches the evidence parser). A later opt-in input can promote it to an error.

With this, drift is caught on the first PR after a template change instead of after a confusing gate failure.

Verification

  • npx vitest run — 121 passed (incl. 5 new validatePrTemplate cases)

    command: npx vitest run
    location: local
    result: Test Files 6 passed (6); Tests 121 passed (121)
    timestamp: 2026-06-07T22:20:10Z
    
  • actionlint .github/workflows/repo-required-gate.yml — clean

    command: actionlint .github/workflows/repo-required-gate.yml
    location: local
    result: no errors
    timestamp: 2026-06-07T22:20:00Z
    

Verification Notes

New tests assert the canonical template passes and that a pre-strict template (the exact hudson-bend#43 shape: ## Changelog, no ## Docs / Changelog) and a notes-less template both warn with missing_heading. The workflow step reuses the already-checked-out validator, is gated to non-draft PRs, runs with !cancelled() so drift is reported even when the body check fails, and degrades to core.info/core.warning (never a hard failure) on a 404 / read error / import error.

Docs / Changelog

  • No changelog fragment system in this repo; behavior change is the new warning-only step (no consumer breakage until/unless promoted to hard-fail).

Linked Issue

Closes #53

Risks

  • Risk level: low — warning-only; does not change pass/fail outcomes for any consumer.
  • Reaches consumers only after a @v1 retag — holding that per owner instruction. Until retagged, this is inert for consumers pinned at @v1.
  • Note: agent/codex/36-pr-contract-gate (stale, no PR) also edits repo-required-gate.yml; this diff is additive to ease any future merge.
  • Rollback: revert the PR (and, if already retagged, move v1 back).

ArchonVII and others added 2 commits June 7, 2026 17:20
Add a structure-only validator (and formatter) that checks a committed PR
template has the contract's required headings in the required order, without
the body-fill checks (checked boxes, placeholders, substantive content) that
a template legitimately lacks. Catches the drift class where a repo's own
PULL_REQUEST_TEMPLATE.md cannot itself pass the gate it is subject to.

Refs #53

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a warning-only step to the pr-contract job that fetches the caller repo's
.github/PULL_REQUEST_TEMPLATE.md and validates its structure against the
contract, surfacing drift directly instead of via a confusing body-check
failure. Phase 1 = warning-only (never hard-fails), matching the evidence
parser. Reaches consumers only after a @v1 retag.

Refs #53

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ArchonVII
ArchonVII merged commit c1ad03e into main Jun 7, 2026
1 check passed
@ArchonVII
ArchonVII deleted the feat/53-template-conformance-guard branch June 7, 2026 22:55
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.

feat(policy): guard against consumer PR-template drift (warn when a repo's own template can't pass the contract)

1 participant