Skip to content

feat(pr-contract): substance-only verification contract + template/doc reconciliation #99

Description

@ArchonVII

Owner decision (2026-07-01 friction-arc session): the verification contract costs paid CI re-runs on pure formatting. Multiple real PRs needed 2-3 fix-commit rounds because a plain bullet in ## Verification is invisible to the parser (missing_checked_verification), the template's own seeded - [ ] hard-fails if left (unchecked_required_box), and each - [x] demands an immediately-following ```evidence fence (missing_evidence_block). Every such failure re-runs the full workflow fan-out on the PR. The owner directive: require that something substantive be there; stop failing on the exact format.

Scope

scripts/pr-contract.mjs (canonical validator; propagates to all consumers via @v1 retag — no caller changes needed):

  1. A verification item = any non-empty -/* bullet or checkbox line in ## Verification. Require ≥1 item (error missing_verification_item, replacing missing_checked_verification).
  2. Unchecked - [ ]warning (unchecked_verification_item), no longer an error; it still counts as an item.
  3. missing_evidence_blockwarning (evidence stays the recommended shape; validated when present via the existing parse-evidence lane, which is already advisory by default in pr-policy).
  4. Heading order/presence (missing_heading) → warning; substance checks (empty_summary, empty_verification_notes, empty_docs_changelog) still hard-fail by finding sections by name.
  5. Keep hard: placeholder markers, generic claims ("tests pass"/"CI green") as items or notes, missing/empty ## Verification content, issue link, Conventional title, branch pattern, docs-only skip.
  6. formatPrContractResult prints advisories on success too (today warnings only surface on failure).
  7. Update fixtures + vitest suite; update workflow header comments describing the old - [x] rule.

Template/doc reconciliation in the same lane (all github-workflows-local):

  • .github/PULL_REQUEST_TEMPLATE.md header claims it is for ArchonVII/repo-template and that this repo has "no language-runtime CI surface" (false — vitest self-test). Fix and align to the canonical scaffold.
  • contracts/pr-template.md is labeled canonical but omits the evidence block/Risks/Plan-artifacts lines the shipped templates carry — reconcile so filling the canonical scaffold verbatim passes the gate.
  • AGENTS.md still instructs retired personas (Issue-Admiral / Project-Captain / Project-Lieutenant / Release-Admiral), contradicting README lines 11-14/174-182. Remove.
  • README.md says 19 reusables; the directory has 20. Fix, and update the PR-contract description to the substance-only rules.

Acceptance Criteria

  • Bullets-only ## Verification body passes; empty/placeholder-only body fails; generic-only claim fails.
  • Unchecked box and missing evidence produce warnings, not errors; warnings appear in the job summary on success.
  • npm test green with new fixtures covering each rule above.
  • Templates/docs reconciled as listed; validatePrTemplate still passes on all shipped templates.
  • Follow-ups filed for the repo-template re-vendor + parity test (executes as the next lane of the friction arc).

Refs the friction-arc plan (owner-approved 2026-07-01). Successor to the closed #81.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions