netkeep80 · netkeep80 · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/changelog.d/20260418_223900_docs_registry_guard.md b/changelog.d/20260418_223900_docs_registry_guard.md
@@ -0,0 +1,6 @@
+---
+bump: patch
+---
+
+### Changed
+- Enforce alignment between the canonical docs index and repo policy registry.
diff --git a/docs/index.md b/docs/index.md
@@ -1,36 +1,41 @@
-# PersistMemoryManager — Documentation Index
+# PersistMemoryManager Documentation Index
 
-Single entry point for all PMM documentation. Each topic is covered by exactly one canonical document.
+Single entry point for PMM documentation. The canonical set below must match
+`repo-policy.json` `paths.canonical_docs`.
 
 ## Canonical Documents
 
 | Document | Role |
 |----------|------|
 | [PMM Target Model](pmm_target_model.md) | Normative top-level model: PMM as compact persistent storage kernel; boundary vs `pjson` / `pjson_db` / execution / product layers |
 | [PMM Transformation Rules](pmm_transformation_rules.md) | Normative operational rulebook: allowed issue types, atomic-issue / no-mixed-PR / extraction-first / surface-compression rules, PR review semantics |
-| [PMM AVL-Forest](pmm_avl_forest.md) | Canonical architectural model: AVL-forest as first-class abstraction, forest-domains, design constraints |
 | [Block and TreeNode Semantics](block_and_treenode_semantics.md) | Field-level specification of `Block` and `TreeNode` headers |
-| [Core Invariants](core_invariants.md) | Frozen invariant set after issues 01–07: model boundary, block semantics, forest, bootstrap, free-tree, verify/repair |
 | [Architecture](architecture.md) | Layer stack, memory layout, algorithms, storage backends, configuration |
 | [API Reference](api_reference.md) | Complete public API: lifecycle, allocation, containers, I/O, error codes |
-| [Bootstrap](bootstrap.md) | Deterministic 6-step initialization sequence for new PAP images |
-| [Free-Tree Forest Policy](free_tree_forest_policy.md) | Free-tree ordering, weight semantics, best-fit search |
-| [Recovery](recovery.md) | Fault recovery: 5-phase load sequence, block state machine, CRC32, atomic writes |
-| [Verify/Repair Contract](verify_repair_contract.md) | Operational boundary between verify, repair, and load — frozen contract for tasks 08–10 |
-| [Diagnostics Taxonomy](diagnostics_taxonomy.md) | Violation types, severity levels, repair policies, diagnostic entry format |
 | [Validation Model](validation_model.md) | Low-level pointer and block validation: cheap vs full modes, conversion paths, error categories |
-| [Storage Seams](storage_seams.md) | Extension points for encryption, compression, journaling; operating modes; separation from upper layers |
-| [Mutation Ordering](mutation_ordering.md) | Write ordering rules for all critical mutations; crash-consistency analysis; trust anchors vs. derived data |
 | [Atomic Writes](atomic_writes.md) | Write criticality analysis, block state transitions, interruption guarantees |
 | [Thread Safety](thread_safety.md) | Lock policies, operation contracts, resolve() fast path, concurrent patterns |
 
 ## Supporting Documents
 
 | Document | Role |
 |----------|------|
+| [PMM AVL-Forest](pmm_avl_forest.md) | Architectural model for AVL-forest design constraints |
+| [Core Invariants](core_invariants.md) | Frozen invariant set after issues 01-07 |
+| [Bootstrap](bootstrap.md) | Deterministic initialization sequence for new PAP images |
+| [Free-Tree Forest Policy](free_tree_forest_policy.md) | Free-tree ordering, weight semantics, best-fit search |
+| [Recovery](recovery.md) | Fault recovery sequence and block state machine |
+| [Verify/Repair Contract](verify_repair_contract.md) | Operational boundary between verify, repair, and load |
+| [Diagnostics Taxonomy](diagnostics_taxonomy.md) | Violation types, severity levels, repair policies |
+| [Storage Seams](storage_seams.md) | Extension points for encryption, compression, journaling |
+| [Mutation Ordering](mutation_ordering.md) | Write ordering rules and crash-consistency analysis |
 | [Repository Shape](repository_shape.md) | Target directory structure and file placement rules |
 | [Deletion Policy](deletion_policy.md) | Rules for file lifecycle: keep, move, archive, delete |
 | [Comment Policy](comment_policy.md) | Canonical text discipline for comments, docs placement, and text-surface review |
+| [Code Reduction Report](code_reduction_report.md) | Supporting report on code-volume reduction |
+| [Compatibility Audit](compatibility_audit.md) | Supporting compatibility inventory |
+| [Internal Structure](internal_structure.md) | Supporting implementation structure notes |
+| [Test Matrix](test_matrix.md) | Supporting test coverage matrix |
 
 ## Archive
 
@@ -41,12 +46,10 @@ They do not participate in the official reading path.
 
 For newcomers, the recommended path is:
 
-1. **[PMM AVL-Forest](pmm_avl_forest.md)** — understand the core model
-2. **[Core Invariants](core_invariants.md)** — frozen invariant set with traceability to code and tests
+1. **[PMM Target Model](pmm_target_model.md)** — understand the PMM boundary
+2. **[PMM Transformation Rules](pmm_transformation_rules.md)** — understand allowed changes
 3. **[Block and TreeNode Semantics](block_and_treenode_semantics.md)** — understand the data structures
 4. **[Architecture](architecture.md)** — understand the implementation layers
 5. **[API Reference](api_reference.md)** — use the library
-6. **[Bootstrap](bootstrap.md)** / **[Recovery](recovery.md)** — understand lifecycle guarantees
-7. **[Verify/Repair Contract](verify_repair_contract.md)** / **[Diagnostics Taxonomy](diagnostics_taxonomy.md)** — understand verify/repair boundary
-8. **[Storage Seams](storage_seams.md)** / **[Mutation Ordering](mutation_ordering.md)** — understand extension points and crash consistency
-9. **[Thread Safety](thread_safety.md)** — for concurrent usage
+6. **[Validation Model](validation_model.md)** / **[Atomic Writes](atomic_writes.md)** — understand safety checks
+7. **[Thread Safety](thread_safety.md)** — for concurrent usage
diff --git a/docs/repository_shape.md b/docs/repository_shape.md
@@ -163,10 +163,9 @@
 Официальный маршрут чтения:
 
 1. `README.md` — обзор, быстрый старт, ссылки на документацию.
-2. `docs/` index (будет создан в задаче 02) — перечень канонических документов.
-3. Канонические docs: `architecture.md`, `api_reference.md`, `pmm_avl_forest.md`,
-   `block_and_treenode_semantics.md`, `bootstrap.md`, `free_tree_forest_policy.md`,
-   `recovery.md`, `thread_safety.md`, `atomic_writes.md`.
+2. `docs/index.md` — перечень канонических, supporting и архивных документов.
+3. Канонические docs перечислены только в `docs/index.md` и
+   `repo-policy.json` `paths.canonical_docs`; эти списки должны совпадать.
 
 Исторические и архивные документы не входят в маршрут и не должны выглядеть
 как обязательная часть чтения.
@@ -175,20 +174,15 @@
 
 #### Canonical
 
-- `architecture.md` — архитектура и инварианты
-- `api_reference.md` — справочник API
-- `pmm_avl_forest.md` — каноническая модель AVL-forest
-- `block_and_treenode_semantics.md` — семантика Block / TreeNode
-- `bootstrap.md` — инициализация и bootstrap
-- `free_tree_forest_policy.md` — политика free-tree
-- `recovery.md` — recovery и валидация
-- `thread_safety.md` — потокобезопасность
-- `atomic_writes.md` — атомарная запись
+Canonical docs are listed in `docs/index.md` and enforced by
+`repo-policy.json` `paths.canonical_docs`. This document must not duplicate the
+registry.
 
 #### Supporting
 
 - `repository_shape.md` — целевая структура репозитория
 - `deletion_policy.md` — правила удаления и архивации
+- `comment_policy.md` — дисциплина текстовой поверхности
 - `index.md` — единая точка входа в документацию
 
 #### Archive (`docs/archive/`)

diff --git a/repo-policy.json b/repo-policy.json
@@ -17,23 +17,14 @@
       "demo.md"
     ],
     "canonical_docs": [
-      "README.md",
-      "CONTRIBUTING.md",
-      "CHANGELOG.md",
+      "docs/pmm_target_model.md",
+      "docs/pmm_transformation_rules.md",
+      "docs/block_and_treenode_semantics.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"
+      "docs/atomic_writes.md",
+      "docs/thread_safety.md"
     ],
     "governance_paths": [
       "repo-policy.json",

diff --git a/scripts/check-docs-consistency.sh b/scripts/check-docs-consistency.sh
@@ -24,7 +24,7 @@ if [ -f repo-policy.json ]; then
       continue
     fi
     if $in_canonical; then
-      doc_path=$(echo "$line" | grep -oP '"[^"]*\.md"' | tr -d '"')
+      doc_path=$(echo "$line" | grep -oP '"[^"]*\.md"' | tr -d '"' || true)
       if [ -n "$doc_path" ] && [ ! -f "$doc_path" ]; then
         echo "FAIL: canonical doc listed in repo-policy.json does not exist: $doc_path"
         FAILED=1
@@ -33,6 +33,26 @@ if [ -f repo-policy.json ]; then
   done < repo-policy.json
 fi
 
+# --- Canonical docs in docs/index.md must match repo-policy.json ---
+
+if [ -f repo-policy.json ] && [ -f docs/index.md ]; then
+  policy_docs=$(mktemp)
+  index_docs=$(mktemp)
+  trap 'rm -f "$policy_docs" "$index_docs"' EXIT
+
+  sed -n '/"canonical_docs"/,/\]/p' repo-policy.json \
+    | grep -oP '"docs/[^"]*\.md"' | tr -d '"' > "$policy_docs" || true
+
+  sed -n '/^## Canonical Documents/,/^## /p' docs/index.md \
+    | grep -oP '\]\([^)]+\.md\)' \
+    | sed -E 's/.*\]\(([^)]+)\)/docs\/\1/' > "$index_docs" || true
+
+  if ! diff -u <(sort "$policy_docs") <(sort "$index_docs"); then
+    echo "FAIL: docs/index.md canonical documents differ from repo-policy.json paths.canonical_docs"
+    FAILED=1
+  fi
+fi
+
 if [ "$FAILED" -eq 0 ]; then
   echo "OK: all docs-consistency checks passed"
 else