[governance/repo-guard] Align canonical docs registry

[konard]

Fixes #283

Summary

• Shrinks repo-policy.json paths.canonical_docs from the broad mixed list to the canonical docs published in docs/index.md.
• Updates docs/index.md so canonical docs, supporting docs, and archive docs are visibly separate.
• Stops docs/repository_shape.md from duplicating a second canonical registry.
• Extends scripts/check-docs-consistency.sh so docs/index.md and repo-policy.json cannot drift silently.
• Adds a patch changelog fragment because the docs-consistency script is source-owned by CI.
• Removes the placeholder .gitkeep, which is forbidden by repository policy.

Canonical registry before

• README.md
• CONTRIBUTING.md
• CHANGELOG.md
• docs/architecture.md
• docs/api_reference.md
• docs/pmm_avl_forest.md
• docs/block_and_treenode_semantics.md
• docs/bootstrap.md
• docs/free_tree_forest_policy.md
• docs/recovery.md
• docs/thread_safety.md
• docs/mutation_ordering.md
• docs/storage_seams.md
• docs/core_invariants.md
• docs/diagnostics_taxonomy.md
• docs/validation_model.md
• docs/verify_repair_contract.md

Canonical registry after

• docs/pmm_target_model.md
• docs/pmm_transformation_rules.md
• docs/block_and_treenode_semantics.md
• docs/architecture.md
• docs/api_reference.md
• docs/validation_model.md
• docs/atomic_writes.md
• docs/thread_safety.md

Reclassified as supporting / governance

• Supporting docs in docs/index.md: AVL forest model, core invariants, bootstrap, free-tree policy, recovery, verify/repair contract, diagnostics taxonomy, storage seams, mutation ordering, repository shape, deletion policy, comment policy, code reduction report, compatibility audit, internal structure, and test matrix.
• Governance plumbing remains under repo-policy.json paths.governance_paths instead of the canonical docs registry.
• Root release/contribution docs are no longer mixed into the docs canonical registry.

Surface contract

• New markdown files: 1 changelog fragment required by CI for scripts/** changes; no new governance docs.
• Generated files touched: no
• Code surface touched: no
• Net documentation/governance markdown delta, excluding changelog fragment: non-positive (docs/index.md +3, docs/repository_shape.md -6, net -3)
• Overall diff: 5 files changed, 59 insertions, 45 deletions

Verification

• ./scripts/check-changelog-fragment.sh
• ./scripts/check-docs-consistency.sh
• ./scripts/check-repo-guard-rollout.sh
• ./scripts/check-file-size.sh
• git diff --check
• cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
• cmake --build build
• ctest --test-dir build --output-on-failure (82/82 passed)

[konard]

Solution summary

Implemented and pushed the fix for issue #283.

PR: #284

What changed:

• Aligned docs/index.md and repo-policy.json around one canonical docs registry.
• Reduced the canonical set from the broad mixed list to:
  • docs/pmm_target_model.md
  • docs/pmm_transformation_rules.md
  • docs/block_and_treenode_semantics.md
  • docs/architecture.md
  • docs/api_reference.md
  • docs/validation_model.md
  • docs/atomic_writes.md
  • docs/thread_safety.md
• Reclassified the wider documentation set as supporting docs in docs/index.md.
• Updated docs/repository_shape.md so it no longer duplicates a second canonical registry.
• Extended scripts/check-docs-consistency.sh to fail when docs/index.md and repo-policy.json drift.
• Added the required changelog fragment for the script change.
• Removed the auto-created .gitkeep, which repo policy forbids.

Verification run locally:

• ./scripts/check-changelog-fragment.sh
• ./scripts/check-docs-consistency.sh
• ./scripts/check-repo-guard-rollout.sh
• ./scripts/check-file-size.sh
• git diff --check
• cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
• cmake --build build
• ctest --test-dir build --output-on-failure with 82/82 passing

PR #284 is marked ready for review. Current remote checks show docs consistency, repo-guard, changelog fragment, formatting, cppcheck, file size, and single-header checks passing; the matrix build/test jobs were still in progress at the final poll.

Next useful follow-ups:

1. Watch the remaining CI matrix jobs on PR [governance/repo-guard] Align canonical docs registry #284 until they finish.
2. If any matrix job fails, pull its log and fix only that specific failure.

---

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: unknown
• Token usage: 111,686 input, 13,769 output, 4,013,440 cache read

📊 Context and tokens usage:

Total: (111.7K + 4.0M cached) input tokens, 13.8K output tokens

🤖 Models used:

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

📎 Log file uploaded as Gist (23854KB)

• 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