Migrate docs heading checks to repo-guard

[konard]

Fixes #18

Summary

• Moves documentation heading traceability from scripts/validate-docs-headings.js into repo-policy.json with heading-specific repo-guard anchor types and must_resolve trace rules.
• Removes the bespoke heading validator from CI and runs the pinned netkeep80/repo-guard Action in check-diff mode from the requirements workflow.
• Updates the README, PR template, and repo-guard workflow validator so repo-policy.json is documented and checked as the source of truth for heading traceability.
• Reworks the heading experiment to verify repo-guard catches missing, unbracketed, and unresolved requirement links in headings.

Change Contract

change_type: requirements-policy
scope:
  - "repo-policy.json"
  - ".github/workflows/requirements.yml"
  - ".github/PULL_REQUEST_TEMPLATE.md"
  - "README.md"
  - "scripts/**"
  - "experiments/**"
budgets:
  max_new_files: 1
  max_new_docs: 0
  max_net_added_lines: 260
anchors:
  affects:
    - FR-006
  implements: []
  verifies:
    - FR-006
must_touch:
  - "repo-policy.json"
  - ".github/workflows/requirements.yml"
  - "experiments/test-docs-headings-validation.sh"
must_not_touch:
  - "requirements/**/*.json"
expected_effects:
  - repo-guard fails when required documentation headings are missing requirement links.
  - repo-guard fails when heading requirement links do not resolve to requirement JSON IDs.
  - pjson CI no longer depends on the bespoke heading-only validator script.

Reproduction

Before the change, removing the requirement link from docs/pmm_requirements.md heading ### HeapStorage [NFR-001](../requirements/nonfunctional/NFR-001.json) made node scripts/validate-docs-headings.js fail, but repo-guard --repo-root <temp-clone> check-diff --format summary still passed with 0 unresolved anchors.

After the change, bash experiments/test-docs-headings-validation.sh verifies repo-guard fails for headings without bracketed requirement links, headings with bare IDs such as FR-001, and headings linking to nonexistent IDs such as FR-999.

Verification

• node scripts/validate-requirements.js
• node scripts/validate-repo-guard-workflow.js
• node /tmp/repo-guard/src/repo-guard.mjs --repo-root .
• node /tmp/repo-guard/src/repo-guard.mjs --repo-root . --enforcement blocking check-diff --base upstream/main --head HEAD --format summary
• bash experiments/test-validation.sh
• bash experiments/test-docs-headings-validation.sh — 8/8 cases passed
• git diff --check upstream/main...HEAD

[konard]

Solution summary

Implemented and pushed the fix.

PR 22 is ready for review: #22
Commit: 48a5e4f (Migrate docs heading checks to repo-guard)

What changed:

• Added heading-specific repo-guard anchors and trace rules in repo-policy.json.
• Removed the bespoke scripts/validate-docs-headings.js validator.
• Updated requirements CI to run pinned netkeep80/repo-guard in check-diff mode in .github/workflows/requirements.yml.
• Updated README and PR template to make repo-policy.json the documented source of truth.
• Reworked experiments/test-docs-headings-validation.sh so repo-guard verifies missing, bare, and unresolved heading requirement links.

Verified locally:

• node scripts/validate-requirements.js
• node scripts/validate-repo-guard-workflow.js
• node /tmp/repo-guard/src/repo-guard.mjs --repo-root .
• node /tmp/repo-guard/src/repo-guard.mjs --repo-root . --enforcement blocking check-diff --base upstream/main --head HEAD --format summary
• bash experiments/test-validation.sh
• bash experiments/test-docs-headings-validation.sh — 8/8 cases passed
• git diff --check upstream/main...HEAD

Remote status:

• PR is no longer draft.
• PR merge state is CLEAN.
• GitHub Actions are passing: requirements workflow succeeded on the fork, and upstream repo-guard policy check succeeded.
• Local working tree is clean.

Next useful steps:

1. Review and merge PR 22.
2. Later, consider adding a first-class repo-guard heading extractor if this regex-based policy grows beyond these two docs.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Model: GPT-5.4
• Provider: OpenAI
• Public pricing estimate: $4.366895

📊 Context and tokens usage:

• 6.3M / 1.1M (601%) input tokens, 28.0K / 128K (22%) output tokens

Total: (129.6K + 6.2M cached) input tokens, 28.0K output tokens, $4.366895 cost

🤖 Models used:

• Tool: OpenAI Codex
• Requested: gpt-5.4
• Model: GPT-5.4 (gpt-5.4)

📎 Log file uploaded as Repository (30591KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag