diff --git a/changelog.d/20260418_223900_docs_registry_guard.md b/changelog.d/20260418_223900_docs_registry_guard.md new file mode 100644 index 00000000..1b916c4a --- /dev/null +++ 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 index 864dba4a..eb928731 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,7 @@ -# 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 @@ -8,19 +9,10 @@ Single entry point for all PMM documentation. Each topic is covered by exactly o |----------|------| | [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 | @@ -28,9 +20,22 @@ Single entry point for all PMM documentation. Each topic is covered by exactly o | 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 index 0c2cb503..a1c0cad9 100644 --- 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 index 18cac57a..c03b5ccc 100644 --- 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 index 563f86c2..d3d10399 100755 --- 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