prizmkit 1.1.156 → 1.1.160

package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md

@@ -29,12 +29,12 @@ LICENSE: MIT
 
 WHAT: Prizm is a self-maintaining documentation system where AI reads, generates, updates, and loads project context progressively.
 WHY: Reduce AI hallucinations, minimize token waste, ensure AI has accurate project knowledge at all times.
-HOW: Three-level progressive loading (L0 -> L1 -> L2) with conditional retrospective before commits when code changes affect structure, interfaces, dependencies, behavior, or durable project knowledge.
+HOW: Three-level progressive loading (L0 -> L1 -> L2) with task-scoped retrospective when code changes affect structure, interfaces, dependencies, behavior, or durable project knowledge.
 
 CORE_PRINCIPLES:
 - Token efficiency over human readability
 - Progressive disclosure (load only what is needed)
-- Self-updating (docs stay fresh via commit-time hooks)
+- Self-maintaining (framework owners reconcile managed docs without owning project Git policy)
 - Universal (language and framework agnostic)
 - Durable project knowledge over auxiliary history (decisions, traps, interfaces, dependencies)
 - Value-gated retention: before keeping a candidate fact, ask `Could a future AI that lacks this fact make an incorrect modification?`; retain it only when yes, current, durable, non-obvious, and owned at this level
@@ -56,71 +56,59 @@ CORE_PRINCIPLES:
 
 LEVELS:
 - L0: Root index. ALWAYS loaded at session start. Hard limit 4096 raw UTF-8 bytes.
-  FILE: .prizmkit/prizm-docs/root.prizm
+  FILE: exact .prizmkit/prizm-docs/root.prizm only
   CONTAINS: concise project meta, module summaries with pointers, build commands, tech stack, top rules
   DOES NOT CONTAIN: child-owned interfaces, data flow, TRAPS, DECISIONS, full rules, or copied behavioral detail
 
 - L1: Structural index. Loaded ON DEMAND when AI works in a module area. Hard limit 4096 raw UTF-8 bytes each.
-  FILE: .prizmkit/prizm-docs/<mirrored-path>.prizm (mirrors source directory structure)
+  FILE: direct .prizm child of .prizmkit/prizm-docs/, excluding exact root.prizm
   CONTAINS: concise module responsibility, source submodule pointers, semantic detail pointers, key navigation files, dependency summary, critical rules summary (1-3 only)
   DOES NOT CONTAIN: interface signatures, data flow, TRAPS, DECISIONS, full rules, or content already complete in L2
 
-- L2: Behavioral detail. Loaded when AI modifies files in that module OR needs deep understanding. Hard limit 5120 raw UTF-8 bytes each.
-  FILE: mirrored source submodule at .prizmkit/prizm-docs/<module>/<submodule>.prizm, or semantic concern at .prizmkit/prizm-docs/<module>/<concern-slug>.prizm for an eligible flat module
+- L2: Behavioral detail. Loaded completely before modifying its owned source or when deep understanding is required. Hard limit 5120 raw UTF-8 bytes each.
+  FILE: every nested .prizm document below .prizmkit/prizm-docs/, whether mirrored source detail or semantic concern
   CONTAINS: Value-Gate-qualified public interfaces, data flow, rules, TRAPS, DECISIONS, domain-specific sections, and rejected approaches
   IDENTITY: a real source submodule path takes precedence; a semantic concern remains an L2 document and never adds a level
 
+PATH_CLASSIFICATION: Classification depends only on the repository-relative document path: exact root is L0, direct document children are L1, and nested documents are L2. Source depth, filename, module size, and Git state never change the level.
+
 ## 2.2 Directory Layout
 
-STRUCTURE: Mirrors source tree under .prizmkit/prizm-docs/
+STRUCTURE: Direct L1 documents index top-level source modules; nested L2 documents mirror owned source submodules or stable semantic concerns.
 
 EXAMPLE (Go project):
   .prizmkit/prizm-docs/
     root.prizm                            # L0
+    internal.prizm                        # L1 for internal/
     internal/
-      logic.prizm                         # L1 for internal/logic/
-      model.prizm                         # L1 for internal/model/
-      repo.prizm                          # L1 for internal/repo/
-      service.prizm                       # L1 for internal/service/
-      common.prizm                        # L1 for internal/common/
-      logic/
-        statemachine.prizm                # L2 for internal/logic/statemachine/
-        session.prizm                     # L2 for internal/logic/session/
-        ivr.prizm                         # L2 for internal/logic/ivr/
-      repo/
-        rpc.prizm                         # L2 for internal/repo/rpc/
-        store.prizm                       # L2 for internal/repo/store/
-      service/
-        http.prizm                        # L2 for internal/service/http/
-        sso.prizm                         # L2 for internal/service/sso/
+      logic.prizm                         # L2 for internal/logic/
+      model.prizm                         # L2 for internal/model/
+      repo.prizm                          # L2 for internal/repo/
+      service.prizm                       # L2 for internal/service/
 
 EXAMPLE (JS/TS project):
   .prizmkit/prizm-docs/
     root.prizm                            # L0
+    src.prizm                             # L1 for src/
     src/
-      components.prizm                    # L1 for src/components/
-      hooks.prizm                         # L1 for src/hooks/
-      services.prizm                      # L1 for src/services/
-      components/
-        auth.prizm                        # L2 for src/components/auth/
-        dashboard.prizm                   # L2 for src/components/dashboard/
+      components.prizm                    # L2 for src/components/
+      hooks.prizm                         # L2 for src/hooks/
+      services.prizm                      # L2 for src/services/
 
 EXAMPLE (Python project):
   .prizmkit/prizm-docs/
     root.prizm                            # L0
+    app.prizm                             # L1 for app/
     app/
-      models.prizm                        # L1 for app/models/
-      views.prizm                         # L1 for app/views/
-      services.prizm                      # L1 for app/services/
-      services/
-        payment.prizm                     # L2 for app/services/payment/
-    cross-cutting/                          # Optional: cross-module concern details
-      auth.prizm                          # L2-style doc for cross-cutting auth concern
+      models.prizm                        # L2 for app/models/
+      views.prizm                         # L2 for app/views/
+      services.prizm                      # L2 for app/services/
 
-## 2.3 Git Configuration
+## 2.3 Framework Directory and Git Neutrality
 
-COMMIT: .prizmkit/prizm-docs/ MUST be committed to git alongside source code
-RATIONALE: .prizmkit/prizm-docs/ is shared project knowledge that all team members (human and AI) benefit from.
+FRAMEWORK_DIRECTORY: `.prizmkit/**` contains PrizmKit-managed capabilities and artifacts; an owning framework capability may read or write its exact managed paths.
+GIT_POLICY: The project alone decides whether `.prizmkit/**` paths are ignored, untracked, or tracked. Documentation generation, reconciliation, and validation do not add, remove, force-add, stage, commit, or interpret `.gitignore` entries and do not treat tracking state as a documentation error.
+CONSISTENCY: Managed documentation behavior is identical across ignored, untracked, and tracked states apart from ordinary Git visibility.
 
 ## 2.4 Capacity Classification and Remediation
 
@@ -175,9 +163,8 @@ TEMPLATE:
   - infra: <infrastructure: databases, queues, caches, etc.>
 
   MODULE_INDEX:
-  - <source-path>: <file-count> files. <one-line description>. -> .prizmkit/prizm-docs/<mirrored-path>.prizm
-  (Multi-level entries allowed for efficient navigation. No hard depth limit — constrained by L0 4KB.
-   If navigating from L0 to a target module requires 3+ hops, add intermediate entries here.)
+  - <top-level-source-module>: <file-count> files. <one-line description>. -> .prizmkit/prizm-docs/<module>.prizm
+  (Every root pointer resolves to one direct-child L1. L1 then resolves only the relevant nested L2 pointers.)
 
   ENTRY_POINTS:
   - <name>: <file-path> (<protocol/port if applicable>)
@@ -203,7 +190,7 @@ CONSTRAINTS:
 - Hard limit 4096 raw UTF-8 bytes; project size never raises it
 - Every line must be a KEY: value pair or a list item
 - MODULE_INDEX must have arrow pointer (->) for every entry
-- MODULE_INDEX may list entries at any depth needed for efficient navigation (no hard depth limit)
+- MODULE_INDEX and MODULE_GROUPS entries point to direct-child L1 documents only
 - RULES limited to 5-10 most critical conventions
 - No prose paragraphs
 - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
@@ -365,7 +352,7 @@ CONSTRAINTS:
 
 ## 3.4 Metadata Policy
 
-TEMPORAL_INFO: Git history is the authoritative source for change timing and edit history.
+TEMPORAL_INFO: Change timing and edit history are outside Prizm memory; use project history when the project provides it.
 AUXILIARY_FIELDS: Do not generate CHANGELOG or UPDATED fields in .prizm files.
 WORKFLOW_METADATA: Do not write feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths into .prizm files.
 RATIONALE: Keep project memory focused on durable architecture, interfaces, dependencies, traps, rules, and decisions.
@@ -380,7 +367,7 @@ LISTS: Dash-space prefix for items within a section (- item)
 POINTERS: Arrow notation (->) to reference other .prizm files
 NESTING: Indent 2 spaces for sub-keys within a section
 COMMENTS: None. Every line carries information. No comments in .prizm files.
-TIMESTAMPS: No date/time fields in .prizm files. Git is the authoritative source for temporal information. Use `git log` or `git blame` on .prizm files when needed.
+TIMESTAMPS: No date/time fields in .prizm files. Temporal history is outside Prizm memory and is never required for documentation operation.
 
 ---
 
@@ -388,30 +375,31 @@ TIMESTAMPS: No date/time fields in .prizm files. Git is the authoritative source
 
 ## 5.1 Mapping Algorithm
 
-RULE: Mirror the source directory tree under .prizmkit/prizm-docs/
-RULE: L1 file for directory D = .prizmkit/prizm-docs/<D>.prizm
-RULE: L2 file for subdirectory D/S = .prizmkit/prizm-docs/<D>/<S>.prizm
-RULE: Root index = .prizmkit/prizm-docs/root.prizm (always)
+RULE: Root index = exact .prizmkit/prizm-docs/root.prizm (L0)
+RULE: L1 for top-level source module M = direct child .prizmkit/prizm-docs/<M>.prizm
+RULE: Mirrored L2 for source submodule M/S = nested .prizmkit/prizm-docs/<M>/<S>.prizm
+RULE: Semantic L2 for a stable flat-module concern = nested .prizmkit/prizm-docs/<M>/<concern-slug>.prizm
+RULE: Nested source depth never creates L3; the owning nested document remains L2 and uses explicit MODULE/FILES identity
 
 ## 5.2 Examples
 
-SOURCE_PATH                   L1_PRIZM_FILE                            L2_PRIZM_FILES
-internal/logic/               .prizmkit/prizm-docs/internal/logic.prizm         .prizmkit/prizm-docs/internal/logic/*.prizm
-internal/logic/session/       (described in L1 logic.prizm SUBDIRS)    .prizmkit/prizm-docs/internal/logic/session.prizm
-internal/repo/store/          (described in L1 repo.prizm SUBDIRS)     .prizmkit/prizm-docs/internal/repo/store.prizm
-src/components/               .prizmkit/prizm-docs/src/components.prizm         .prizmkit/prizm-docs/src/components/*.prizm
-src/components/auth/          (described in L1 components.prizm)       .prizmkit/prizm-docs/src/components/auth.prizm
-app/services/                 .prizmkit/prizm-docs/app/services.prizm           .prizmkit/prizm-docs/app/services/*.prizm
+SOURCE_PATH                   L1_PRIZM_FILE                         L2_PRIZM_FILE
+internal/                     .prizmkit/prizm-docs/internal.prizm   none until durable detail exists
+internal/logic/               (parent L1 SUBDIRS pointer)           .prizmkit/prizm-docs/internal/logic.prizm
+src/                          .prizmkit/prizm-docs/src.prizm        none until durable detail exists
+src/components/               (parent L1 SUBDIRS pointer)           .prizmkit/prizm-docs/src/components.prizm
+app/                          .prizmkit/prizm-docs/app.prizm        none until durable detail exists
+app/services/                 (parent L1 SUBDIRS pointer)           .prizmkit/prizm-docs/app/services.prizm
 
 ## 5.3 Discovery Rule
 
 FOR any source file at path P:
-  1. Walk up directory tree to find the first ancestor D where .prizmkit/prizm-docs/<D>.prizm exists
-  2. That file is the L1 doc for this source file
-  3. If P is inside a source subdirectory S of D, check `.prizmkit/prizm-docs/<D>/<S>.prizm` first; mirrored source-submodule identity has precedence
-  4. For a flat module, resolve each L1 DETAILS pointer and select the one semantic L2 whose FILES ownership contains P
-  5. If semantic FILES ownership is absent, overlaps, or disagrees with its parent pointer, report ambiguity instead of guessing
-  6. If no .prizm doc found, the module is undocumented (may need retrospective after development or prizmkit-prizm-docs Update for out-of-band repair)
+  1. Resolve its top-level source module M through the root MODULE_INDEX or MODULE_GROUPS pointer to direct-child L1 `.prizmkit/prizm-docs/<M>.prizm`
+  2. Read that complete L1 and resolve the one mirrored SUBDIRS or semantic DETAILS pointer that owns P
+  3. Mirrored source-submodule identity has precedence; for a flat module, semantic FILES ownership selects the detail
+  4. Before modifying P, read the complete selected L2 and complete resolving parent/child pointer documents
+  5. If ownership is absent, overlaps, or disagrees with its pointer, report ambiguity instead of guessing
+  6. If no relevant L2 exists, inspect only the bounded source files needed for P and proceed without creating a placeholder; documentation creation remains an owning retrospective/repair operation
 
 ## 5.4 Deterministic Semantic Concern Identity
 
@@ -450,59 +438,42 @@ POINTER_RESOLUTION:
 ## 6.1 When to Load
 
 ON_SESSION_START:
-  ALWAYS: Read .prizmkit/prizm-docs/root.prizm (L0) if it exists
+  ALWAYS: Read exact .prizmkit/prizm-docs/root.prizm (L0) if it exists
   PURPOSE: Get the project map, understand architecture, know where to look
 
 ON_TASK_RECEIVED:
   IF task references specific file or directory:
-    LOAD: L1 for the containing module (structural index: files, deps, key rules)
-    RESOLVE: a mirrored SUBDIRS pointer first; for a flat module, use the one DETAILS pointer whose semantic L2 FILES ownership contains the source file
-  IF task is broad (e.g., "refactor auth", "improve performance"):
-    LOAD: L1 for all matching modules from MODULE_INDEX
-  IF task is exploratory (e.g., "explain the codebase", "how does X work"):
-    LOAD: L0 only, then navigate via pointers as needed
-  IF task is cross-cutting (e.g., "add logging everywhere"):
-    LOAD: L1 for affected modules, check DEPENDENCIES.imported-by and CROSS_CUTTING in root.prizm
+    LOAD_COMPLETE: direct-child L1 for the containing top-level module
+    RESOLVE: the mirrored SUBDIRS pointer first; for a flat module, use the one DETAILS pointer whose semantic L2 FILES ownership contains the source file
+  IF task is broad:
+    LOAD_COMPLETE: only matching direct-child L1 documents from MODULE_INDEX or MODULE_GROUPS
+  IF task is exploratory:
+    LOAD: L0 only, then navigate through resolving pointers as needed
+  IF task is cross-cutting:
+    LOAD_COMPLETE: direct-child L1 documents for affected modules and only their relevant L2 details
 
 ON_FILE_MODIFICATION:
   BEFORE editing any source file:
-    TARGETED LOAD from L2 (NEVER read the entire L2 file — use grep to extract only needed sections):
-    1. Use Grep tool to search for "^TRAPS:" in the L2 doc, read that section (prevent known mistakes)
-    2. Use Grep tool to search for "^DECISIONS:" and "^REJECTED:", read those sections (understand prior choices)
-    3. Use Grep tool to search for "^INTERFACES:" if you need to understand the public API contract
-    Only load additional L2 sections if the task specifically requires them.
-    IF L2 does not exist: GENERATE L2 from source code analysis, then extract needed sections
+    1. Read the complete relevant L2 document when it exists; partial grep fragments cannot establish all traps, decisions, interfaces, and ownership constraints.
+    2. Read the complete direct L1 and any complete parent/child documents needed to resolve the selected SUBDIRS or DETAILS pointer in both directions.
+    3. Do not load unrelated L1/L2 documents.
+    4. If relevant L2 is absent, inspect only the bounded target source files and narrowly implicated callers/contracts needed for the modification. Proceed without creating a placeholder.
 
 ON_DEEP_READ:
-  WHEN AI needs deep understanding of a module WITHOUT modifying it:
-    TARGETED LOAD from L2 using grep (same approach as ON_FILE_MODIFICATION)
-    IF L2 does not exist: GENERATE L2 from source code analysis, then extract needed sections
-    USE_CASES: code review, architecture analysis, dependency tracing, explaining complex logic
+  WHEN deep understanding is required without modification:
+    READ_COMPLETE: the relevant L2 and resolving pointer documents
+    IF L2 is absent: inspect bounded relevant source without creating documentation merely because it was read
 
 ## 6.2 Loading Rules
 
-NEVER: Load all L1 and L2 docs at session start (defeats progressive loading)
-NEVER: Read entire L2 files — always use grep/search to extract only the sections you need
-NEVER: Load L2 for modules not being modified or deeply analyzed (wastes context window)
-NEVER: Skip L0 (it is the map for everything else)
-PREFER: Load L1 before L2 (understand module context before diving into details)
-PREFER: Load minimum docs and minimum sections needed for the task
-BUDGET: Typical task should consume 3000-5000 tokens of prizm docs total
-
-## 6.3 L2 Targeted Loading Protocol
-
-L2 docs can be up to 5120 raw UTF-8 bytes. Loading them in full defeats the purpose of progressive loading.
-Use targeted grep to extract only the sections relevant to your current task:
-
-COMMAND_PATTERN:
-  Grep tool with pattern "^SECTION_NAME:" and context lines (-A flag) to read a specific section.
-  Stop reading at the next ALL-CAPS section header.
-
-EXAMPLES:
-  - Before editing a file: grep for "^TRAPS:" and "^DECISIONS:" sections
-  - Before changing an API: grep for "^INTERFACES:" section
-  - Before modifying data handling: grep for "^DATA_FLOW:" section
-  - For full module understanding (rare): read the entire L2 (only when task explicitly requires comprehensive analysis)
+NEVER: Load all L1 and L2 docs at session start
+NEVER: Use grep-only fragments as modification context for a relevant L2
+NEVER: Load L2 for unrelated modules
+NEVER: Skip exact root when it exists
+NEVER: Create placeholder L2 during context loading
+MUST: Read relevant L2 and resolving pointer documents completely before source modification
+PREFER: Navigate root -> direct L1 -> nested L2
+PREFER: Keep source fallback bounded to the target and concrete dependency ambiguity
 
 ---
 
@@ -510,7 +481,7 @@ EXAMPLES:
 
 ## 7.1 Trigger
 
-WHEN: During normal development, run `/prizmkit-retrospective` before commits when structure, interfaces, dependencies, behavior, or durable project knowledge changed. Use `prizmkit-prizm-docs Update` only for out-of-band repair/resync after docs drifted outside the normal development loop.
+WHEN: During the normal formal lifecycle, run `/prizmkit-retrospective` after validated source changes when structure, interfaces, dependencies, behavior, or durable project knowledge changed. Use `prizmkit-prizm-docs Update` only for out-of-band repair/resync after docs drifted outside the normal development loop.
 GOAL: Keep prizm docs synchronized with source code without creating multiple competing docs writers.
 
 ## 7.2 Value Gate
@@ -557,7 +528,7 @@ DETAILED_STEPS: → ${SKILL_DIR}/references/op-update.md
 NEVER: Add CHANGELOG sections or changelog.prizm during doc sync.
 NEVER: Add UPDATED/date/time fields to .prizm files.
 NEVER: Add workflow metadata such as feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
-RATIONALE: Git already provides history; .prizm files should store only durable project memory.
+RATIONALE: Temporal and workflow history is outside Prizm memory; .prizm files store only durable project knowledge regardless of Git tracking policy.
 
 ---
 
@@ -621,7 +592,8 @@ HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-modul
 
 CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init does not create semantic or mirrored L2 placeholders; later Update/Rebuild/Migrate may create complete L2 documents when durable knowledge and unambiguous identity exist.
 
-EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizmkit/prizm-docs/, dev-pipeline/
+EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .prizmkit/
+SOURCE_BOUNDARY: Excluding `.prizmkit/` excludes the installed Runtime at `.prizmkit/dev-pipeline/`; never exclude a repository's canonical top-level `dev-pipeline/` source module by basename.
 
 ## 9.2 Post-Init Behavior
 
@@ -630,9 +602,9 @@ After initialization, L2 docs are created incrementally by retrospective when ch
 ON_MODIFY trigger:
 - Before editing a file in sub-module S within module M:
   IF .prizmkit/prizm-docs/<M>/<S>.prizm exists:
-    AI reads the relevant L2 sections.
+    AI reads the complete L2 plus complete resolving pointer documents.
   ELSE:
-    AI reads the target source files as fallback and proceeds with the modification.
+    AI reads bounded relevant source files as fallback, creates no placeholder, and proceeds with the modification.
 - After the change, `/prizmkit-retrospective` creates L2 only when candidate interfaces, data flow, traps, or decisions pass the Value Gate.
 - Real source submodules retain mirrored paths. A flat-module semantic detail follows Sections 3.3 and 5.4 and blocks on ambiguous concern identity, slug collision, or overlapping ownership.
 - This keeps initialization lightweight while still capturing L2 depth when real durable context exists.
@@ -666,54 +638,22 @@ OPERATIONS (all invoked via the prizmkit-prizm-docs skill):
 
 ## 11.1 Mechanism
 
-HOOK_TYPE: command (shell echo, fast and reliable)
-EVENT: UserPromptSubmit
-BEHAVIOR: When matcher detects commit-related keywords, echoes doc update reminder as stdout
-INJECTION: stdout content is injected into AI's context as a system-reminder
-NOTE: Previously used type: prompt (LLM-evaluated), but switched to type: command for reliability — prompt type is prone to timeout and JSON format errors
-
-## 11.2 Configuration Template
-
-Place in: .codebuddy/settings.json (project-level)
-
-JSON:
-{
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "matcher": "(?i)\\b(commit|push|finish|ship|merge|pull request|pr)\\b",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "echo 'PRIZMKIT_MAINTENANCE_CHECK: Before committing, check whether /prizmkit-retrospective applies. Run it when this change affects structure, interfaces, dependencies, behavior, or durable TRAPS/RULES/DECISIONS. Skip it for direct edits with no docs impact. Then proceed with /prizmkit-committer for the actual git commit.'"
-          }
-        ]
-      }
-    ]
-  }
-}
-
-## 11.3 How It Works
-
-FLOW:
-1. User types prompt (e.g., "commit these changes" or "push to main")
-2. UserPromptSubmit hook fires, matcher regex checks for commit-related keywords
-3. IF matcher matches: command hook runs echo, stdout is injected as system-reminder
-   - AI sees the update instructions and executes them before committing
-4. IF matcher does not match: hook does not fire, AI proceeds normally
-
-KEYWORDS_DETECTED: commit, push, finish, done, ship, merge, PR, pull request, /commit, save changes
-
-## 11.4 Adapting for Other AI Tools
-
-The hook configuration above is specific to CodeBuddy Code.
-For other AI coding assistants:
-- Cursor: Use .cursorrules file to add the conditional retrospective protocol as a rule
-- Aider: Use .aider.conf.yml conventions section
-- Continue: Use .continue/config.json customInstructions
-- Generic: Add the conditional retrospective protocol text to whatever system prompt or rules file the tool supports
-
-The core requirement is: before commit, AI must check whether affected `.prizmkit/prizm-docs/` files need retrospective updates. Run `/prizmkit-retrospective` when the change affects structure, interfaces, dependencies, behavior, or durable TRAPS/RULES/DECISIONS; skip it for direct edits with no docs impact.
+VALIDATION_HOOK: The installed pre-commit hook invokes the canonical Python validator through host-neutral interpreter resolution only when staged Prizm documents exist.
+FAILURE: If staged Prizm documents require validation, unavailable validator/interpreter and nonzero validation are fail-closed. With no staged Prizm documents, the hook is a no-op.
+SNAPSHOT: `--staged` validates index blobs and complete index pointer context; it never substitutes unstaged working bytes.
+MAINTENANCE_HOOK: Commit-intent and post-command hooks may remind about the owning retrospective/repair capability, but never stage, force-add, commit, modify ignore policy, require tracking, or append changelog content.
+INSTALLATION: Upgrade replaces only deterministic PrizmKit-managed hook entries/blocks and preserves user-owned settings and hook behavior.
+
+## 11.2 Host-Neutral Invocation
+
+COMMAND: Installed settings invoke `.prizmkit/scripts/run-python-hook.cjs`, which resolves an available Python 3 launcher and propagates the real script exit status.
+PORTABILITY: Platform/provider names and direct `python3` assumptions are not protocol identifiers. A missing candidate may fall through to another supported Python 3 launcher; a real validation failure is never retried as if the interpreter were missing.
+
+## 11.3 Git Neutrality
+
+RULE: Hooks validate only Git-visible staged documentation already selected by the project/user. They never make ignored files visible and never infer that `.prizmkit/**` must be tracked or ignored.
+RULE: Commit-intent output is maintenance guidance, not staging or commit authorization.
+RULE: No hook adds CHANGELOG content or invokes broad `git add .`, `git add -A`, or force-add.
 
 ---
 

package/bundled/skills/prizmkit-prizm-docs/references/op-init.md

@@ -9,9 +9,9 @@ STEPS:
 2. Discover modules using MODULE_DISCOVERY_CRITERIA:
    - A directory qualifies as a module if it contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as a dependency.
    - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
-   - SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the parent L1; if durable L2 is created later, its path mirrors the sub-module.
-   - HIERARCHY RULE: directory X inside top-level module M maps to `.prizmkit/prizm-docs/<M>/<X>.prizm`, never to `.prizmkit/prizm-docs/<X>.prizm`.
-   - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizmkit/prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
+   - SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the direct-child parent L1; if durable L2 is created later, its nested path mirrors the sub-module.
+   - HIERARCHY RULE: exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); directory X inside M maps to nested `.prizmkit/prizm-docs/<M>/<X>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
+   - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
 3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
 4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist. Do not create placeholder detail files.
 5. Generate `root.prizm` (L0) with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
@@ -23,7 +23,8 @@ STEPS:
 8. Measure every generated file with the canonical raw UTF-8 capacity classifier: L0/L1 4096B, L2 5120B. Report warning-range files without failing. If a generated L0/L1 reaches 90% or above, clean or reorganize it toward 3277-3686B without deleting protected knowledge. Any unresolved hard-limit error blocks Init.
 9. Configure UserPromptSubmit hook in platform settings per `${SKILL_DIR}/assets/prizm-docs-format.md` Section 11.
 10. Validate all generated docs: Value Gate, size/band reporting, pointer resolution, no circular dependencies, KEY: value format, parent-summary boundary, no anti-patterns, and no prohibited metadata. Warning-only capacity results pass; hard-limit or format errors fail.
-11. Report modules discovered, L1 docs generated, files/categories omitted by the Value Gate, files excluded, capacity diagnostics in descending utilization, and any required manual decisions.
+11. Write only complete validated candidates bottom-up, compare bytes before replacement, re-read actual bytes, and restore exact pre-write bytes or remove invalid new targets if a post-write check fails.
+12. Report modules discovered, L1 docs generated, files/categories omitted by the Value Gate, files excluded, capacity diagnostics in descending utilization, and any required manual decisions. Do not stage, commit, force-add, change ignore policy, require history, or report tracking state as documentation health.
 
 OUTPUT: List of generated files, module count, Value-Gate omissions by category, capacity results, and validation results.
 
@@ -32,7 +33,7 @@ OUTPUT: List of generated files, module count, Value-Gate omissions by category,
 After initialization, L2 docs are created only when durable context exists:
 
 ON_MODIFY behavior:
-- When an AI modifies a file in sub-module S within module M and `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, the implementation reads the source files in S as fallback context and proceeds.
+- Before modification, read the complete relevant L2 plus complete resolving parent/child pointer documents. When `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, inspect only the bounded relevant source files in S and narrowly implicated contracts as fallback context, create no placeholder, and proceed.
 - Do not block implementation only to create a placeholder L2 doc.
 - After the change, run `/prizmkit-retrospective` when structure, interfaces, dependencies, behavior, or durable TRAPS changed; retrospective creates or updates L2 then only for facts that pass the future-incorrect-modification Value Gate.
 - Preserve the mirrored source-submodule path. For a flat module with multiple stable concerns under repeated L2 capacity pressure, use deterministic semantic L2 identity and explicit non-overlapping FILES ownership; block ambiguous creation.

package/bundled/skills/prizmkit-prizm-docs/references/op-rebuild.md

@@ -5,7 +5,7 @@ Regenerate docs for a specific module from scratch. Requires a module path argum
 PRECONDITION: .prizmkit/prizm-docs/ exists. Module path is valid.
 
 STEPS:
-1. Read the existing module L1, every pointed L2, and the relevant root entry before changing anything. Do not delete first. Snapshot semantic meanings, pointers, paths, and a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
+1. Read the complete existing direct-child module L1, every complete pointed nested L2, and the complete relevant root pointer context before changing anything. Do not delete first. Snapshot semantic meanings, pointers, paths, and a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
 2. Re-scan the current module source for files, public/wire behavior, dependencies, flows, stable concerns, and real source submodules. Treat each observation and each old entry as a candidate under the future-incorrect-modification Value Gate; source-derived, transient, historical, test-inventory, stale, duplicate, procedural, and low-value material is omitted.
 3. Reconstruct the module map in memory, then apply the Cleanup Gate to each existing target: update equivalent meanings in place, merge synonyms, remove stale/derivable/parent-copied content, and add only genuinely new durable knowledge. Append-only growth and delete-first regeneration are prohibited.
 4. Reconcile detail identity:
@@ -16,6 +16,8 @@ STEPS:
 5. Rewrite the existing L1 as a concise structural summary and pointer index only. Preserve SUBDIRS pointers for real source-submodule L2 and DETAILS pointers for semantic L2. Never copy child interfaces, data flow, traps, decisions, or full rules into L1. Remove an obsolete detail only after all still-valid protected knowledge has been preserved in its current owner and its source/concern identity no longer exists.
 6. Update only the equivalent root MODULE_INDEX or MODULE_GROUPS entry in place. Preserve concise pointer-only parent behavior, existing project-wide knowledge, and `PROJECT_BRIEF:`. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within the unchanged 4096B L0 limit; more than 15 modules is a mandatory grouping trigger, not permission for a larger root.
 7. Measure exact raw UTF-8 bytes using hard limits L0/L1 4096B and L2 5120B. Report warning-range results without failing. For any rewritten target at 90% or above, trim low-value material, deduplicate, move child-owned behavior, or safely semantic-split toward 3277-3686B for L0/L1 or 4096-4607B for L2. Never delete protected knowledge for size; unresolved hard-limit or unsafe-split pressure blocks Rebuild.
-8. Validate Value/Cleanup compliance, complete semantic fields, FILES ownership, pointer resolution, hierarchy, parent-summary boundaries, capacity, and format. Warning-only results pass; hard-limit or format errors fail.
+8. Build and validate the complete affected candidate set before replacement, then write bottom-up. Compare candidate/current bytes and do not rewrite byte-identical targets.
+9. Re-read actual bytes and validate Value/Cleanup compliance, complete semantic fields, FILES ownership, pointer resolution in both directions, hierarchy, parent-summary boundaries, capacity, and format. Warning-only results pass; hard-limit or format errors fail.
+10. If any post-write check fails, restore every replaced target to exact pre-write bytes and remove invalid new targets before returning a blocker. Rebuild never stages, commits, force-adds, changes or interprets ignore policy, requires Git history, or treats tracking state as health.
 
 OUTPUT: Rebuilt-document before/after summary listing entries updated in place, merged, removed, added, and protected; sorted capacity diagnostics; semantic identity/ownership decisions; and any blocking ambiguity.

package/bundled/skills/prizmkit-prizm-docs/references/op-status.md

@@ -5,17 +5,16 @@ Check freshness of all .prizm docs.
 PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
 
 STEPS:
-1. Get the last git modification time of `root.prizm` via `git log -1 --format="%ai" -- .prizmkit/prizm-docs/root.prizm`. If history is unavailable, use filesystem timestamps and report reduced freshness accuracy.
-2. Count commits since that time via `git log --since="<timestamp>" --oneline | wc -l`.
-3. For each L1/L2 document, compare its git modification time with the latest source modification in its mapped module. Resolve real source submodules through SUBDIRS and flat semantic concerns through DETAILS plus their authoritative FILES ownership.
-4. Classify freshness as FRESH (doc updated after source), STALE (source newer), or MISSING (durable module/concern exists without a document). An absent placeholder with no Value-Gate-qualified knowledge is not MISSING.
-5. Measure every `.prizm` file from its actual raw UTF-8 bytes and classify the exact path: only `.prizmkit/prizm-docs/root.prizm` is L0 with 4096B; direct children are L1 with 4096B; nested mirrored or semantic documents are L2 with 5120B. Never infer capacity from project size, line count, character count, or filename alone.
-6. Classify capacity as normal (<80%), warning (80% to <90%), strong-warning (90% through 100%), or error (>100%). Sort every non-normal capacity entry by exact descending utilization using integer ratio comparison, then repository-relative path ascending for ties.
-7. For each non-normal entry report `DOC_PATH | LEVEL | BYTES | LIMIT | BAND | TARGET_RANGE | ACTIONS`. Target is 3277-3686B for L0/L1 or 4096-4607B for L2. ACTIONS must include concrete level-appropriate trim, deduplicate, move-to-child, and semantic-split guidance consistent with the canonical F-063 classifier.
-8. Status is read-only. A warning or strong warning is not "oversize" and does not force a split. An error is over the hard limit. Recommend semantic split only for an eligible flat module with multiple stable concerns after Value/Cleanup filtering; otherwise recommend the applicable non-destructive actions or manual decision.
-9. When inspecting representative or named documents, use their current measured bytes and detected level. Do not special-case paths or repeat stale measurements in guidance.
+1. Read exact `root.prizm` and resolve registered direct-child L1 and nested L2 pointers from current filesystem content. Status never requires Git history and never inspects whether managed paths are ignored, untracked, or tracked.
+2. For each L1/L2 document, compare its filesystem modification time with current mapped source files only as an advisory freshness signal. Resolve real source submodules through SUBDIRS and flat semantic concerns through DETAILS plus authoritative FILES ownership.
+3. Classify freshness as FRESH (doc not older than source), STALE (source newer), or MISSING (a required resolving pointer or Value-Gate-qualified documented concern lacks a complete target). An absent placeholder with no Value-Gate-qualified knowledge is not MISSING.
+4. Measure every `.prizm` file from its actual raw UTF-8 bytes and classify the exact path: only `.prizmkit/prizm-docs/root.prizm` is L0 with 4096B; direct children are L1 with 4096B; nested mirrored or semantic documents are L2 with 5120B. Never infer capacity from project size, line count, character count, filename, source depth, or Git state.
+5. Classify capacity as normal (<80%), warning (80% to <90%), strong-warning (90% through 100%), or error (>100%). Sort every non-normal capacity entry by exact descending utilization using integer ratio comparison, then repository-relative path ascending for ties.
+6. For each non-normal entry report `DOC_PATH | LEVEL | BYTES | LIMIT | BAND | TARGET_RANGE | ACTIONS`. Target is 3277-3686B for L0/L1 or 4096-4607B for L2. ACTIONS include concrete level-appropriate trim, deduplicate, move-to-child, and semantic-split guidance.
+7. Status is read-only. A warning or strong warning is not "oversize" and does not force a split. An error is over the hard limit. Recommend semantic split only for an eligible flat module with multiple stable concerns after Value/Cleanup filtering; otherwise recommend the applicable non-destructive actions or manual decision.
+8. When inspecting representative or named documents, use their current measured bytes and detected level. Do not special-case paths or repeat stale measurements in guidance.
 
 OUTPUT:
-- Freshness table: `DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD`.
+- Freshness table: `DOC_PATH | LEVEL | STATUS | PRIZM_FILESYSTEM_MOD | SOURCE_FILESYSTEM_MOD` (advisory; no Git-history requirement).
 - Capacity table: non-normal entries in descending utilization with `DOC_PATH | LEVEL | BYTES | LIMIT | BAND | TARGET_RANGE | ACTIONS`.
 - Summary counts for normal, warning, strong-warning, and error. Status reports errors but does not mutate documents.

package/bundled/skills/prizmkit-prizm-docs/references/op-update.md

@@ -7,10 +7,10 @@ PRECONDITION: `.prizmkit/prizm-docs/` exists with `root.prizm`.
 Use this operation for manual edits, merges, rebases, branch switches, generated code movement, or other changes that did not pass through `/prizmkit-retrospective`. During ordinary feature/bugfix/refactor work, use `/prizmkit-retrospective` instead.
 
 STEPS:
-1. Identify drift source. Prefer explicit user context; otherwise inspect git changes with `git diff --cached --name-status`, then `git diff --name-status`. If no git changes exist, run a bounded rescan comparing code structure against existing docs.
+1. Identify drift source from explicit user context when supplied; otherwise run a bounded source/document rescan over registered modules and concrete missing/stale pointers. Do not require Git history, inspect tracking state, or change behavior because managed files are ignored, untracked, or tracked.
 2. Map changed files to modules through MODULE_INDEX or MODULE_GROUPS in `root.prizm`, then resolve mirrored SUBDIRS or flat-module DETAILS ownership from the relevant L1.
 3. Classify each source change as A, D, M, or R, but do not mechanically turn changes into documentation. Treat every possible file, interface, dependency, flow, trap, decision, rule, and summary as a candidate and apply the future-incorrect-modification Value Gate.
-4. Before writing any existing L2, L1, or L0 target, read that target and its resolving parent/child pointers. Build a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
+4. Before writing any existing L2, L1, or L0 target, read that complete target and complete resolving parent/child pointer documents. Build a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
 5. Apply the Cleanup Gate by semantic meaning:
    - update an equivalent entry in place rather than appending alternate wording
    - merge synonymous entries into one shortest complete meaning
@@ -27,8 +27,9 @@ STEPS:
    - semantic details require the complete CONCERN terminal shape, explicit non-empty/non-overlapping FILES ownership, and one resolving L1 DETAILS entry
    - ambiguous concern identity, empty normalization, mirrored-path/slug collision, or overlapping ownership blocks creation and reports the manual decision; never use task IDs or numeric suffixes
 11. Measure all affected targets by exact raw UTF-8 bytes with L0/L1 4096B and L2 5120B limits. Natural content below 80% remains unchanged; warning-range content is valid and reported. Clean, move, or safely split rewritten targets at 90% or above toward 3277-3686B for L0/L1 or 4096-4607B for L2. If a hard-limit error or repeated pressure cannot be resolved without deleting protected knowledge, block the write.
-12. Validate Value/Cleanup compliance, parent-summary boundaries, semantic ownership/identity, pointers, hierarchy, capacity, memory hygiene, and format. Warning-only capacity results pass; hard-limit or format errors fail.
-13. Report updated, created, removed, merged, protected, and skipped facts/docs with reasons plus capacity diagnostics ordered by descending utilization.
-14. Stage updated `.prizm` files with `git add .prizmkit/prizm-docs/` only after reviewing the repair summary.
+12. Preflight complete candidate bytes, write validated targets bottom-up, compare each candidate with current bytes, and skip byte-identical replacements.
+13. Re-read actual bytes and validate Value/Cleanup compliance, parent-summary boundaries, semantic ownership/identity, pointers in both directions, hierarchy, capacity, memory hygiene, and format. Warning-only capacity results pass; hard-limit or format errors fail.
+14. If any post-write check fails, restore every existing target to its exact pre-write bytes and remove invalid new targets before returning a blocker.
+15. Report updated, created, removed, merged, protected, and skipped facts/docs with reasons plus capacity diagnostics ordered by descending utilization. Do not stage, commit, force-add, modify or interpret ignore policy, or require Git history.
 
 OUTPUT: List updated, created, removed, merged, protected, and skipped docs/facts with reasons; sorted capacity diagnostics; ambiguity blockers; and an explicit statement that this was out-of-band repair/resync, not a normal development retrospective.