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

[ArchonVII]

Summary

Substance-only PR verification contract (owner decision, 2026-07-01 friction arc): the parser now requires that something substantive is recorded in ## Verification — a plain bullet or a checkbox both count — and stops hard-failing on exact format. June data motivating this: PR-body format failures caused multi-round fix-commit loops, and each round re-ran the full 6–7-workflow fan-out per consumer PR.

• scripts/pr-contract.mjs: missing_verification_item (replaces missing_checked_verification) fires only when zero substantive items exist; unchecked boxes → advisory unchecked_verification_item; missing evidence fence after a checked item → advisory missing_evidence_block; heading presence/order → advisory (substance checks still locate sections by name and hard-fail when content is missing); placeholder + generic-claim ("tests pass"/"CI green") rejection unchanged; fenced content inside Verification is masked so evidence output is never misread as a claim; advisories now print on success.
• Behavior reaches every consumer at the next @v1 retag (owner-gated) — the gate's pr-contract job imports this script from the checked-out library; no caller-input changes needed (require-checked-box name kept).
• Templates/docs reconciled: mislabeled .github/PULL_REQUEST_TEMPLATE.md fixed (claimed to be repo-template's and denied this repo's vitest CI surface); contracts/pr-template.md now passes the gate it models; README inventory 19→20 + contract description updated; retired persona language removed from AGENTS.md; pr-policy.yml header/description comments updated.

Verification

• Ran the full vitest suite in the lane worktree: 9 files / 168 tests / 168 pass (baseline pre-change: 159; +9 net new cases covering bullets-count, *-bullets, unchecked-warns, evidence-warns, order-advisory-passes, renamed-heading-still-fails-via-substance, fence-masking, generic-bullet-fails, advisories-print-on-success).

  command: npm test
  location: local
  result: Test Files 9 passed (9); Tests 168 passed (168)
  timestamp: 2026-07-02T00:30:18Z
  

• Exercised the CLI against this very PR body shape: node scripts/pr-contract.mjs --body-file - accepts a bullets-plus-evidence body and rejects an items-free body with missing_verification_item (covered by the body-file acceptance tests in scripts/pr-contract.test.mjs).

Verification Notes

The acceptance table from the #81/#82/#91 work is preserved unchanged — the "still fails" cases (placeholder wording in Summary, an unfilled command field inside a real evidence fence, a generic checked claim, a docs section containing only a not-applicable marker) all still fail, so the parser is more tolerant of format, not weaker on substance. validatePrTemplate still passes on the shipped templates.

Docs / Changelog

Changelog fragment: .changelog/unreleased/99-substance-only-contract.md. Update-log entry appended to docs/repo-update-log.md (includes the propagation plan). README + AGENTS.md updated in this PR.

Plan/status artifacts: friction-arc plan is owner-side (C:\Users\josep\.claude\plans\please-review-what-is-fluttering-lobster.md); no repo plan docs created or used by this lane.

Owner decisions this lane: appended — substance-only relaxation ratified by owner 2026-07-01 (AskUserQuestion session record).

Linked Issue

Closes #99

Risks

• Risk level: Medium — this changes gate behavior for every consumer at the next @v1 retag. Mitigations: substance checks unchanged or strengthened (fence masking), acceptance-table regression tests preserved, error-code rename verified unreferenced outside this repo's own test (repo-template's vendored copy is re-vendored in the next lane).
• Rollback: revert the three commits and retag @v1 back; no schema or state changes.
• Follow-ups: repo-template re-vendor + parity test (next friction-arc lane); archon-setup snapshot refresh; @v1 retag is owner-gated and should ride after this merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70f984293b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Sync auto-inject with plain-bullet verification

With this regex a plain - Ran npm test line now satisfies the PR contract, but I checked .github/workflows/pr-body-autoinject.yml and its skip test still requires checked: /-\s+\[[xX]\]/ before it avoids prepending the TODO scaffold. For bot-authored non-doc PRs that already have the new valid plain-bullet verification, the reusable auto-inject workflow will still add TODO placeholders, and the same contract then fails on placeholder_text; update the auto-inject satisfiability check and stub to use the new item semantics.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Align evidence enforcement with advisory semantics

This demotes missing evidence to a PR-contract warning, but in .github/workflows/pr-policy.yml the separate Evidence check still calls parseEvidence, whose missing-evidence result remains an error and calls core.setFailed when enforce-evidence is true. Consumers that opted into enforce-evidence: true and follow the new template/docs by using a checked item without an evidence block will still have the reusable workflow fail, so the evidence parser/workflow needs the same advisory semantics or the docs must exclude enforce-evidence callers.

Useful? React with 👍 / 👎.