feat(policy): enforce strict PR ready contract

[ArchonVII]

Summary

• Add the shared PR contract validator and JSON/text CLI.
• Add agent:close-preflight and agent:pr-ready wrappers so agents cannot promote malformed PRs through the blessed path.
• Route repo-required-gate and pr-policy through the shared validator, and gate expensive PR jobs behind the cheap PR contract while preserving the explicit opt-out path.
• Make bot PR body auto-injection scaffold-only so incomplete scaffolds cannot pass accidentally.

Verification

• npm test

command: npm test
location: local
result: 5 files passed, 76 assertions completed successfully
timestamp: 2026-05-31T21:46:56Z

• PR contract CLI smoke

command: node scripts/pr-contract.mjs --event-path $env:TEMP\pr-contract-event-valid.json --files-json '["scripts/pr-contract.mjs",".github/workflows/repo-required-gate.yml"]'
location: local
result: PR contract passed
timestamp: 2026-05-31T21:46:56Z

• Agent wrapper smoke

command: npm run agent:close-preflight -- --repo ArchonVII/github-workflows --pr 39 --json; npm run agent:pr-ready -- --repo ArchonVII/github-workflows --pr 39 --dry-run --json
location: local
result: both wrappers returned ok=true against PR #39
timestamp: 2026-05-31T21:46:56Z

• YAML parse smoke

command: python -c "import yaml; [yaml.safe_load(open(p, encoding='utf-8')) for p in ['.github/workflows/repo-required-gate.yml','.github/workflows/pr-policy.yml','.github/workflows/pr-body-autoinject.yml','examples/repo-required-gate.yml','examples/pr-policy.yml']]"
location: local
result: all targeted workflow YAML files parsed successfully
timestamp: 2026-05-31T21:46:56Z

• Whitespace check

command: git diff --check
location: local
result: no whitespace errors; Git emitted line-ending normalization warnings for two touched files only
timestamp: 2026-05-31T21:46:56Z

Verification Notes

Vitest completed locally with 5 files and 76 assertions. The PR-contract CLI accepted a valid synthetic pull_request payload. The close-preflight and pr-ready wrapper scripts both validated PR #39 successfully; pr-ready was run with --dry-run. PyYAML parsed the modified reusable workflows and caller examples. actionlint was unavailable locally through PATH, npx actionlint, and Go tooling in this environment, so syntax coverage uses YAML parsing plus repository tests.

Docs / Changelog

README and contracts/pr-template.md document the new wrapper path and canonical scaffold. This repo does not currently use changelog fragments.

Linked Issue

Closes #36