prizmkit 1.1.159 → 1.1.160

package/bundled/templates/hooks/validate-prizm-docs.py

@@ -1,17 +1,20 @@
 #!/usr/bin/env python3
-"""Validate .prizmkit/prizm-docs files for PrizmKit projects."""
+"""Validate canonical Prizm v4 documentation snapshots."""
 
 from __future__ import annotations
 
 import re
 import subprocess
 import sys
+import unicodedata
 from dataclasses import dataclass
 from functools import cmp_to_key
 from pathlib import Path, PurePosixPath
+from typing import Mapping
 
 DOCS_ROOT = Path(".prizmkit/prizm-docs")
-ROOT_PRIZM = DOCS_ROOT / "root.prizm"
+DOCS_ROOT_POSIX = PurePosixPath(DOCS_ROOT.as_posix())
+ROOT_PATH = f"{DOCS_ROOT.as_posix()}/root.prizm"
 VALID_MODES = {"--all", "--staged"}
 
 AUXILIARY_METADATA_RE = re.compile(
@@ -75,55 +78,44 @@ BRANCH_SIMPLE_FIELD_RE = re.compile(
     r"[ \t]*(#.*)?$",
     re.IGNORECASE | re.MULTILINE,
 )
+HEADER_RE = re.compile(r"^([A-Z][A-Z0-9_]*):(.*)$")
+CONCERN_RE = re.compile(r"^(.+?)\s*\|\s*SLUG:\s*([^\s|]+)\s*$")
+DETAILS_ENTRY_RE = re.compile(r"^\s*-\s+([^:]+):\s+.+?\s+->\s+`?([^`\s]+)`?\s*$")
+TRAP_RE = re.compile(r"^-\s+(?:\[REVIEW\])?\[(CRITICAL|HIGH|LOW)\]\s+.+\|\s+FIX:\s+.+")
+
+ROOT_REQUIRED = {"PRIZM_VERSION", "PROJECT", "LANG", "RULES"}
+L1_REQUIRED = {"MODULE", "FILES", "RESPONSIBILITY", "DEPENDENCIES"}
+L1_PROHIBITED = {"CONCERN", "INTERFACES", "DATA_FLOW", "TRAPS", "DECISIONS"}
+L2_REQUIRED = {
+    "MODULE", "FILES", "RESPONSIBILITY", "INTERFACES", "KEY_FILES", "DEPENDENCIES", "TRAPS",
+}
+SEMANTIC_REQUIRED = L2_REQUIRED | {"CONCERN", "DATA_FLOW", "RULES", "DECISIONS"}
 
 
 def emit_error(file_path: str, message: str) -> None:
     print(f"ERROR: {file_path} {message}", file=sys.stderr)
 
 
-def run_git(args: list[str], *, capture: bool = True) -> subprocess.CompletedProcess[str]:
+def run_git(args: list[str], *, binary: bool = False) -> subprocess.CompletedProcess:
     return subprocess.run(
         ["git", *args],
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        stdout=subprocess.PIPE if capture else subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=not binary,
+        encoding=None if binary else "utf-8",
+        errors=None if binary else "replace",
         check=False,
     )
 
 
-def collect_files(mode: str) -> list[str]:
-    if mode == "--all":
-        return sorted(path.as_posix() for path in DOCS_ROOT.rglob("*.prizm") if path.is_file())
-
-    result = run_git(["diff", "--cached", "--name-only"])
-    if result.returncode != 0:
-        return []
-    return [line.strip() for line in result.stdout.splitlines() if line.strip().endswith(".prizm")]
-
-
-def read_check_content(file_path: str, mode: str) -> tuple[bytes, str] | None:
-    if mode == "--staged":
-        exists = run_git(["cat-file", "-e", f":{file_path}"], capture=False)
-        if exists.returncode != 0:
-            return None
-        blob = subprocess.run(
-            ["git", "show", f":{file_path}"],
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        if blob.returncode != 0:
-            return None
-        raw = blob.stdout
-    else:
-        path = Path(file_path)
-        if not path.is_file():
-            return None
-        raw = path.read_bytes()
-
-    return raw, raw.decode("utf-8", errors="replace")
+@dataclass(frozen=True)
+class Document:
+    path: str
+    raw: bytes
+    text: str
+    level: str
+    sections: Mapping[str, tuple[str, ...]]
+    fields: Mapping[str, str]
 
 
 @dataclass(frozen=True)
@@ -138,48 +130,40 @@ class CapacityDiagnostic:
     actions: str
 
 
-def is_root_doc(file_path: str) -> bool:
-    return PurePosixPath(file_path) == PurePosixPath(ROOT_PRIZM.as_posix())
-
-
-def is_l1_doc(file_path: str) -> bool:
-    parent = PurePosixPath(file_path).parent.as_posix()
-    return parent == DOCS_ROOT.as_posix()
-
-
-def size_limit(file_path: str) -> tuple[int, str, str]:
-    if is_root_doc(file_path):
-        return (
-            4096,
-            "L0",
-            "trim: lower-priority global wording; "
-            "deduplicate: repeated RULES or module summaries; "
-            "move-to-child: module detail into an L1 document; "
-            "semantic-split: broad module groups into focused L1 documents",
+@dataclass(frozen=True)
+class Pointer:
+    source: str
+    section: str
+    line: str
+    target: str
+
+
+def document_level(file_path: str) -> str:
+    path = PurePosixPath(file_path)
+    if path == PurePosixPath(ROOT_PATH):
+        return "L0"
+    if path.parent == DOCS_ROOT_POSIX:
+        return "L1"
+    return "L2"
+
+
+def size_policy(level: str) -> tuple[int, str]:
+    if level == "L0":
+        return 4096, (
+            "trim: lower-priority global wording; deduplicate: repeated RULES or module summaries; "
+            "move-to-child: module detail into direct L1; semantic-split: use capacity-safe MODULE_GROUPS"
         )
-    if is_l1_doc(file_path):
-        return (
-            4096,
-            "L1",
-            "trim: low-value module summaries; "
-            "deduplicate: repeated interfaces, rules, or traps; "
-            "move-to-child: implementation detail into an L2 document; "
-            "semantic-split: distinct submodules into focused L2 documents",
+    if level == "L1":
+        return 4096, (
+            "trim: low-value module summaries; deduplicate: repeated structure or RULES; "
+            "move-to-child: behavioral detail into nested L2; semantic-split: stable concerns into sibling L2 documents"
         )
-    return (
-        5120,
-        "L2",
-        "trim: stale or derivable detail; "
-        "deduplicate: repeated implementation notes; "
-        "move-to-child: one coherent detail set into a focused child document; "
-        "semantic-split: unrelated responsibilities into focused L2 documents",
+    return 5120, (
+        "trim: stale or derivable detail; deduplicate: repeated meanings; "
+        "move-to-child: not applicable because L2 is terminal; semantic-split: unrelated stable concerns into sibling L2 documents"
     )
 
 
-def ceil_percent(limit: int, percent: int) -> int:
-    return (limit * percent + 99) // 100
-
-
 def capacity_band(size: int, limit: int) -> str:
     if size > limit:
         return "error"
@@ -190,15 +174,19 @@ def capacity_band(size: int, limit: int) -> str:
     return "normal"
 
 
-def capacity_diagnostic(file_path: str, size: int) -> CapacityDiagnostic | None:
-    limit, level, actions = size_limit(file_path)
-    band = capacity_band(size, limit)
+def ceil_percent(limit: int, percent: int) -> int:
+    return (limit * percent + 99) // 100
+
+
+def capacity_diagnostic(document: Document) -> CapacityDiagnostic | None:
+    limit, actions = size_policy(document.level)
+    band = capacity_band(len(document.raw), limit)
     if band == "normal":
         return None
     return CapacityDiagnostic(
-        file_path=file_path,
-        level=level,
-        size=size,
+        file_path=document.path,
+        level=document.level,
+        size=len(document.raw),
         limit=limit,
         band=band,
         target_low=ceil_percent(limit, 80),
@@ -210,15 +198,9 @@ def capacity_diagnostic(file_path: str, size: int) -> CapacityDiagnostic | None:
 def compare_capacity(left: CapacityDiagnostic, right: CapacityDiagnostic) -> int:
     left_ratio = left.size * right.limit
     right_ratio = right.size * left.limit
-    if left_ratio > right_ratio:
-        return -1
-    if left_ratio < right_ratio:
-        return 1
-    if left.file_path < right.file_path:
-        return -1
-    if left.file_path > right.file_path:
-        return 1
-    return 0
+    if left_ratio != right_ratio:
+        return -1 if left_ratio > right_ratio else 1
+    return -1 if left.file_path < right.file_path else (1 if left.file_path > right.file_path else 0)
 
 
 def utilization_percent(size: int, limit: int) -> str:
@@ -227,71 +209,114 @@ def utilization_percent(size: int, limit: int) -> str:
 
 
 def emit_capacity(diagnostic: CapacityDiagnostic) -> None:
-    severity = {
-        "warning": "WARNING",
-        "strong-warning": "STRONG WARNING",
-        "error": "ERROR",
-    }[diagnostic.band]
+    severity = {"warning": "WARNING", "strong-warning": "STRONG WARNING", "error": "ERROR"}[
+        diagnostic.band
+    ]
     print(
-        f"{severity}: {diagnostic.file_path} capacity "
-        f"level={diagnostic.level} bytes={diagnostic.size}B limit={diagnostic.limit}B "
+        f"{severity}: {diagnostic.file_path} capacity level={diagnostic.level} "
+        f"bytes={diagnostic.size}B limit={diagnostic.limit}B "
         f"utilization={diagnostic.size}/{diagnostic.limit} "
-        f"({utilization_percent(diagnostic.size, diagnostic.limit)}) "
-        f"band={diagnostic.band} "
+        f"({utilization_percent(diagnostic.size, diagnostic.limit)}) band={diagnostic.band} "
         f"target={diagnostic.target_low}-{diagnostic.target_high}B (80% to <90%) "
         f"actions={diagnostic.actions}",
         file=sys.stderr,
     )
 
 
-def contains_root_field(text: str, field: str) -> bool:
-    return re.search(rf"^{re.escape(field)}:", text, re.MULTILINE) is not None
-
+def _is_doc_path(value: str) -> bool:
+    normalized = value.strip().replace("\\", "/")
+    return normalized.startswith(f"{DOCS_ROOT.as_posix()}/") and normalized.endswith(".prizm")
 
-def validate_file(file_path: str, raw: bytes, text: str) -> tuple[int, CapacityDiagnostic | None]:
-    errors = 0
 
-    if re.search(r"^#{1,6} ", text, re.MULTILINE):
-        emit_error(file_path, "contains markdown headers (##). Use KEY: value format.")
-        errors += 1
+def collect_snapshot(mode: str) -> tuple[dict[str, bytes], bool, str]:
+    if mode == "--all":
+        active = DOCS_ROOT.exists()
+        snapshot = {
+            path.as_posix(): path.read_bytes()
+            for path in sorted(DOCS_ROOT.rglob("*.prizm"))
+            if path.is_file()
+        } if active else {}
+        return snapshot, active, ""
+
+    changed = run_git(["diff", "--cached", "--name-only", "-z", "--diff-filter=ACMRD"])
+    if changed.returncode != 0:
+        return {}, True, "git_index_unavailable"
+    changed_docs = [path for path in changed.stdout.split("\0") if _is_doc_path(path)]
+    if not changed_docs:
+        return {}, False, ""
+
+    indexed = run_git(["ls-files", "--cached", "-z", "--", DOCS_ROOT.as_posix()])
+    if indexed.returncode != 0:
+        return {}, True, "git_index_unavailable"
+    snapshot: dict[str, bytes] = {}
+    for file_path in indexed.stdout.split("\0"):
+        if not _is_doc_path(file_path):
+            continue
+        blob = run_git(["show", f":{file_path}"], binary=True)
+        if blob.returncode != 0:
+            return {}, True, f"git_index_blob_unavailable:{file_path}"
+        snapshot[file_path] = blob.stdout
+    return snapshot, True, ""
+
+
+def parse_document(file_path: str, raw: bytes) -> tuple[Document, list[str]]:
+    errors: list[str] = []
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("utf-8", errors="replace")
+        errors.append("is not valid UTF-8")
+
+    fields: dict[str, str] = {}
+    sections: dict[str, list[str]] = {}
+    current_section = ""
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        header = HEADER_RE.match(line)
+        if header:
+            current_section = header.group(1)
+            fields.setdefault(current_section, header.group(2).strip())
+            sections.setdefault(current_section, [])
+            continue
+        if stripped.startswith("- "):
+            if not current_section:
+                errors.append(f"line {line_number} is a list item outside a section")
+            else:
+                sections.setdefault(current_section, []).append(stripped)
+            continue
+        if line.startswith((" ", "\t")) and re.match(r"^[ \t]+[A-Za-z0-9_-]+:\s*$", line):
+            if current_section != "MODULE_GROUPS":
+                errors.append(f"line {line_number} has a nested key outside MODULE_GROUPS")
+            continue
+        errors.append(f"line {line_number} is not KEY: value or a section list item")
 
-    if re.search(r"^```", text, re.MULTILINE):
-        emit_error(file_path, "contains code blocks. Use file_path:line_number reference.")
-        errors += 1
+    frozen_sections = {key: tuple(value) for key, value in sections.items()}
+    return Document(file_path, raw, text, document_level(file_path), frozen_sections, fields), errors
 
-    base_name = PurePosixPath(file_path).name.lower()
-    if base_name in {"changelog.prizm", "changelog-archive.prizm"} or (
-        "changelog" in base_name and base_name.endswith(".prizm")
-    ):
-        emit_error(file_path, "is auxiliary history. Use git history instead of changelog .prizm files.")
-        errors += 1
 
+def _metadata_errors(document: Document) -> list[str]:
+    text = document.text
+    errors: list[str] = []
+    if re.search(r"^#{1,6}\s", text, re.MULTILINE):
+        errors.append("contains markdown headers")
+    if re.search(r"^```", text, re.MULTILINE):
+        errors.append("contains code blocks")
+    if re.search(r"^\s*---+\s*$", text, re.MULTILINE):
+        errors.append("contains horizontal rules")
+    base_name = PurePosixPath(document.path).name.lower()
+    if "changelog" in base_name and base_name.endswith(".prizm"):
+        errors.append("is auxiliary history")
     if AUXILIARY_METADATA_RE.search(text):
-        emit_error(
-            file_path,
-            "contains auxiliary history metadata. Use durable KEY: value sections only; git tracks history.",
-        )
-        errors += 1
-
+        errors.append("contains auxiliary history metadata")
     if WORKFLOW_ID_RE.search(text) or WORKFLOW_FIELD_RE.search(text) or WORKFLOW_COMPOUND_FIELD_RE.search(text):
-        emit_error(
-            file_path,
-            "contains workflow metadata. Translate IDs, branch names, worktree paths, and pipeline artifacts into durable product/domain language.",
-        )
-        errors += 1
-
-    normalized_text = text.replace("\\", "/")
-    if ARTIFACT_PATH_RE.search(normalized_text):
-        emit_error(
-            file_path,
-            "contains PrizmKit artifact paths. Translate specs/dev-pipeline references into durable product/domain language.",
-        )
-        errors += 1
-
-    if ABSOLUTE_PATH_RE.search(normalized_text):
-        emit_error(file_path, "contains absolute worktree paths. Use repository-relative source paths only.")
-        errors += 1
-
+        errors.append("contains workflow metadata")
+    normalized = text.replace("\\", "/")
+    if ARTIFACT_PATH_RE.search(normalized):
+        errors.append("contains PrizmKit artifact paths")
+    if ABSOLUTE_PATH_RE.search(normalized):
+        errors.append("contains absolute worktree paths")
     if (
         BRANCH_EXACT_FIELD_RE.search(text)
         or BRANCH_UPPER_FIELD_RE.search(text)
@@ -299,54 +324,255 @@ def validate_file(file_path: str, raw: bytes, text: str) -> tuple[int, CapacityD
         or BRANCH_TITLE_FIELD_RE.search(text)
         or BRANCH_SIMPLE_FIELD_RE.search(text)
     ):
-        emit_error(file_path, "contains branch names. Describe durable product/domain context instead.")
-        errors += 1
-
-    diagnostic = capacity_diagnostic(file_path, len(raw))
-    if diagnostic is not None and diagnostic.band == "error":
-        errors += 1
-
-    if is_root_doc(file_path):
-        for field in ["PRIZM_VERSION", "PROJECT", "LANG", "RULES"]:
-            if not contains_root_field(text, field):
-                emit_error(file_path, f"missing required field {field}:")
-                errors += 1
-        if not contains_root_field(text, "MODULE_INDEX") and not contains_root_field(text, "MODULE_GROUPS"):
-            emit_error(file_path, "missing required field MODULE_INDEX: or MODULE_GROUPS:")
-            errors += 1
-
-    return errors, diagnostic
+        errors.append("contains branch names")
+    traps = document.sections.get("TRAPS", ())
+    for trap in traps:
+        if not TRAP_RE.fullmatch(trap):
+            errors.append("contains a TRAPS entry without valid severity and FIX")
+            break
+    return errors
+
+
+def _shape_errors(document: Document) -> list[str]:
+    names = set(document.fields)
+    errors: list[str] = []
+    if document.level == "L0":
+        missing = sorted(ROOT_REQUIRED - names)
+        if missing:
+            errors.append(f"missing required root fields: {', '.join(missing)}")
+        if document.fields.get("PRIZM_VERSION") != "4":
+            errors.append("requires exact PRIZM_VERSION: 4")
+        indexes = {name for name in ("MODULE_INDEX", "MODULE_GROUPS") if name in names}
+        if len(indexes) != 1:
+            errors.append("requires exactly one of MODULE_INDEX or MODULE_GROUPS")
+    elif document.level == "L1":
+        missing = sorted(L1_REQUIRED - names)
+        if missing:
+            errors.append(f"missing required L1 fields: {', '.join(missing)}")
+        prohibited = sorted(L1_PROHIBITED & names)
+        if prohibited:
+            errors.append(f"contains prohibited L1 behavioral fields: {', '.join(prohibited)}")
+        if len(document.sections.get("RULES", ())) > 3:
+            errors.append("contains more than three L1 RULES entries")
+    else:
+        semantic = "CONCERN" in names
+        required = SEMANTIC_REQUIRED if semantic else L2_REQUIRED
+        missing = sorted(required - names)
+        if missing:
+            kind = "semantic L2" if semantic else "mirrored L2"
+            errors.append(f"missing required {kind} fields: {', '.join(missing)}")
+    return errors
+
+
+def _normalize_slug(value: str) -> str:
+    normalized = unicodedata.normalize("NFKC", value).lower()
+    pieces: list[str] = []
+    pending_hyphen = False
+    for char in normalized:
+        valid = char.isalpha() or unicodedata.category(char) == "Nd"
+        if valid:
+            if pending_hyphen and pieces:
+                pieces.append("-")
+            pieces.append(char)
+            pending_hyphen = False
+        else:
+            pending_hyphen = True
+    return "".join(pieces).strip("-")
+
+
+def _field_items(document: Document, field: str) -> tuple[str, ...]:
+    inline = document.fields.get(field, "").strip()
+    values: list[str] = []
+    if inline and inline.lower() != "none":
+        values.extend(part.strip() for part in inline.split(",") if part.strip())
+    for item in document.sections.get(field, ()):
+        value = item[2:].strip()
+        if value and value.lower() != "none":
+            values.append(value.split(":", 1)[0].strip())
+    return tuple(values)
+
+
+def _safe_owned_path(value: str) -> bool:
+    text = value.replace("\\", "/").strip()
+    if not text or text.startswith("/") or re.match(r"^[A-Za-z]:/", text):
+        return False
+    path = PurePosixPath(text)
+    return not path.is_absolute() and all(part not in {"", ".", ".."} for part in path.parts)
+
+
+def _resolve_pointer_target(raw_target: str) -> str | None:
+    target = raw_target.strip().strip("`").replace("\\", "/")
+    if target.startswith("./"):
+        target = target[2:]
+    if target.startswith(f"{DOCS_ROOT.as_posix()}/"):
+        candidate = PurePosixPath(target)
+    else:
+        candidate = DOCS_ROOT_POSIX / PurePosixPath(target)
+    if candidate.is_absolute() or any(part in {"", ".", ".."} for part in candidate.parts):
+        return None
+    if not candidate.as_posix().endswith(".prizm"):
+        return None
+    try:
+        candidate.relative_to(DOCS_ROOT_POSIX)
+    except ValueError:
+        return None
+    return candidate.as_posix()
 
 
-def main(argv: list[str]) -> int:
-    mode = argv[1] if len(argv) > 1 else "--staged"
-    if len(argv) > 2 or mode not in VALID_MODES:
-        print("Usage: validate-prizm-docs.py [--all | --staged]", file=sys.stderr)
+def collect_pointers(document: Document) -> tuple[list[Pointer], list[str]]:
+    pointers: list[Pointer] = []
+    errors: list[str] = []
+    pointer_sections = (
+        {"MODULE_INDEX", "MODULE_GROUPS"}
+        if document.level == "L0"
+        else ({"SUBDIRS", "DETAILS"} if document.level == "L1" else set())
+    )
+    for section, lines in document.sections.items():
+        if section not in pointer_sections:
+            continue
+        for line in lines:
+            if "->" not in line:
+                continue
+            target_text = line.split("->", 1)[1].strip().split()[0].strip("`") if line.split("->", 1)[1].strip() else ""
+            target = _resolve_pointer_target(target_text)
+            if target is None:
+                errors.append(f"has unsafe or invalid pointer in {section}: {line}")
+                continue
+            pointers.append(Pointer(document.path, section, line, target))
+    return pointers, errors
+
+
+def validate_snapshot(snapshot: Mapping[str, bytes], active: bool, snapshot_error: str) -> int:
+    if snapshot_error:
+        emit_error(ROOT_PATH, snapshot_error)
         return 1
-
-    if not ROOT_PRIZM.is_file():
+    if not active:
         return 0
+    if ROOT_PATH not in snapshot:
+        emit_error(ROOT_PATH, "missing exact root document from validation snapshot")
+        return 1
 
     errors = 0
+    documents: dict[str, Document] = {}
     capacity_entries: list[CapacityDiagnostic] = []
-    for file_path in collect_files(mode):
-        content = read_check_content(file_path, mode)
-        if content is None:
-            continue
-        raw, text = content
-        file_errors, diagnostic = validate_file(file_path, raw, text)
-        errors += file_errors
+    for file_path in sorted(snapshot):
+        document, parse_errors = parse_document(file_path, snapshot[file_path])
+        documents[file_path] = document
+        for message in [*parse_errors, *_metadata_errors(document), *_shape_errors(document)]:
+            emit_error(file_path, message)
+            errors += 1
+        diagnostic = capacity_diagnostic(document)
         if diagnostic is not None:
             capacity_entries.append(diagnostic)
+            if diagnostic.band == "error":
+                errors += 1
+
+    pointers: list[Pointer] = []
+    for document in documents.values():
+        found, pointer_errors = collect_pointers(document)
+        pointers.extend(found)
+        for message in pointer_errors:
+            emit_error(document.path, message)
+            errors += 1
+
+    inbound_l2: dict[str, list[Pointer]] = {}
+    for pointer in pointers:
+        source = documents[pointer.source]
+        target = documents.get(pointer.target)
+        if target is None:
+            emit_error(pointer.source, f"pointer does not resolve in snapshot: {pointer.target}")
+            errors += 1
+            continue
+        if source.level == "L0" and target.level != "L1":
+            emit_error(pointer.source, f"root pointer must resolve to direct-child L1: {pointer.target}")
+            errors += 1
+        if source.level == "L1":
+            if target.level != "L2":
+                emit_error(pointer.source, f"L1 pointer must resolve to nested L2: {pointer.target}")
+                errors += 1
+            else:
+                inbound_l2.setdefault(pointer.target, []).append(pointer)
+            semantic_target = "CONCERN" in target.fields
+            if pointer.section == "SUBDIRS" and semantic_target:
+                emit_error(pointer.source, f"SUBDIRS must target mirrored L2 without CONCERN: {pointer.target}")
+                errors += 1
+            if pointer.section == "DETAILS":
+                match = DETAILS_ENTRY_RE.match(pointer.line)
+                if not match:
+                    emit_error(pointer.source, f"invalid DETAILS pointer grammar: {pointer.line}")
+                    errors += 1
+                elif not semantic_target:
+                    emit_error(pointer.source, f"DETAILS must target semantic L2: {pointer.target}")
+                    errors += 1
+                elif match.group(1).strip() != PurePosixPath(pointer.target).stem:
+                    emit_error(pointer.source, f"DETAILS slug disagrees with target path: {pointer.target}")
+                    errors += 1
+
+    semantic_ownership: dict[str, dict[str, str]] = {}
+    for document in documents.values():
+        if document.level != "L2":
+            continue
+        inbound = inbound_l2.get(document.path, [])
+        if not inbound:
+            emit_error(document.path, "has no resolving direct-child L1 pointer")
+            errors += 1
+        if "CONCERN" not in document.fields:
+            continue
+        if len(inbound) != 1 or inbound[0].section != "DETAILS":
+            emit_error(document.path, "semantic L2 requires exactly one resolving L1 DETAILS pointer")
+            errors += 1
+        concern_match = CONCERN_RE.match(document.fields.get("CONCERN", ""))
+        if not concern_match:
+            emit_error(document.path, "requires CONCERN: <identity> | SLUG: <slug>")
+            errors += 1
+            continue
+        identity, slug = concern_match.group(1).strip(), concern_match.group(2).strip()
+        expected_slug = _normalize_slug(identity)
+        if not expected_slug or slug != expected_slug or slug != PurePosixPath(document.path).stem:
+            emit_error(document.path, "semantic CONCERN identity, normalized slug, and filename disagree")
+            errors += 1
+        if inbound:
+            parent = documents[inbound[0].source]
+            if document.fields.get("MODULE", "").strip() != parent.fields.get("MODULE", "").strip():
+                emit_error(document.path, "semantic MODULE disagrees with resolving L1 MODULE")
+                errors += 1
+        owned = _field_items(document, "FILES")
+        if not owned:
+            emit_error(document.path, "semantic FILES ownership must be non-empty")
+            errors += 1
+        owner_map = semantic_ownership.setdefault(document.fields.get("MODULE", "").strip(), {})
+        for owned_path in owned:
+            if not _safe_owned_path(owned_path):
+                emit_error(document.path, f"semantic FILES contains unsafe ownership path: {owned_path}")
+                errors += 1
+                continue
+            previous = owner_map.get(owned_path)
+            if previous and previous != document.path:
+                emit_error(document.path, f"semantic FILES overlaps {previous}: {owned_path}")
+                errors += 1
+            owner_map[owned_path] = document.path
 
     for diagnostic in sorted(capacity_entries, key=cmp_to_key(compare_capacity)):
         emit_capacity(diagnostic)
 
-    if errors > 0:
-        print(f"PrizmKit: {errors} format error(s) in .prizm files. Fix before committing.", file=sys.stderr)
+    if errors:
+        print(f"PrizmKit: {errors} validation error(s) in the selected Prizm snapshot.", file=sys.stderr)
         return 1
     return 0
 
 
+def main(argv: list[str]) -> int:
+    mode = argv[1] if len(argv) > 1 else "--staged"
+    if len(argv) > 2 or mode not in VALID_MODES:
+        print("Usage: validate-prizm-docs.py [--all | --staged]", file=sys.stderr)
+        return 1
+    try:
+        snapshot, active, error = collect_snapshot(mode)
+    except OSError as exc:
+        emit_error(ROOT_PATH, f"snapshot read failed: {exc}")
+        return 1
+    return validate_snapshot(snapshot, active, error)
+
+
 if __name__ == "__main__":
     raise SystemExit(main(sys.argv))