prizmkit 1.1.159 → 1.1.160

package/bundled/skills/prizmkit-deploy/references/verification-and-recovery.md

@@ -0,0 +1,164 @@
+# Deployment Verification and Recovery Contract
+
+Use this contract after each planned step, after any failure or interruption, and before selecting a terminal status. Verification observes actual state; it does not infer success from a command exit, API acceptance, or user action alone.
+
+## Layered Verification
+
+Evaluate all five layers and record each named layer exactly once:
+
+```text
+PASSED, FAILED, INACCESSIBLE, NOT_APPLICABLE
+```
+
+| Layer | Evidence | Applicability rule |
+|---|---|---|
+| `command_or_platform` | Exit/result plus target-native operation identity and completion state, not merely request acceptance | Applicable to every executed automated action; manual-only operations explain `NOT_APPLICABLE`. |
+| `runtime_or_release` | Intended process/service/container/release exists, has expected identity/version, and is in the required state | Applicable when the operation creates, starts, stops, restarts, promotes, or rolls back a runtime/release. |
+| `configured_health` | Every configured required project health check meets its explicit expectation | Applicable when a health boundary exists; absence is reported and never replaced with an invented endpoint. |
+| `external_url` | Intended externally observed endpoint reaches the expected release/behavior through the real traffic path | Applicable when an external URL is configured and accessible from the controller boundary. |
+| `startup_logs` | Bounded, redacted project-owned startup window contains no planned fatal condition | Applicable when startup output exists and access is authorized; specify time and/or line bound. |
+
+For every layer store whether it is required and a concise redacted evidence statement. `INACCESSIBLE` and `NOT_APPLICABLE` are not passes. A required layer must be `PASSED` for `SUCCEEDED`; required `FAILED`, `INACCESSIBLE`, or `NOT_APPLICABLE` prevents success. Optional inaccessible or inapplicable layers remain visible in residual risk. Before persisting or trusting the result, validate the complete record with both `${SKILL_DIR}/references/deploy-record-schema.json` and `${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind record` so omitted, duplicate, or contradictory layers fail closed.
+
+A configured required health check failing after an otherwise successful command makes the operation `FAILED`. Do not downgrade it to a warning.
+
+## Evidence Rules
+
+- Re-observe state after the action; do not reuse pre-action evidence as proof of a postcondition.
+- Bind release/runtime observations to the intended target profile and release identity.
+- Distinguish controller result, target-control-plane result, and target workload state.
+- Use actual configured ports/endpoints and target-native identities.
+- Bound all output. Persist only concise summaries, never raw command output or full logs.
+- Redact Secret-bearing URLs, headers, environment assignments, tokens, keys, cookies, connection strings, and user-identified patterns before display or storage.
+- If evidence may be sensitive and reliable redaction is unavailable, mark the layer `INACCESSIBLE` and provide a manual verification action.
+
+## Terminal Status Decision
+
+Exactly one terminal status is returned:
+
+| Status | Required condition |
+|---|---|
+| `SUCCEEDED` | All planned steps completed, all required applicable verification layers are `PASSED`, no effect remains unknown, and the required sole-record update was verified. |
+| `FAILED` | Confirmed execution occurred but a step, required verification layer, rollback attempt, cleanup required for correctness, or required local-record update failed. Report actual live state. |
+| `BLOCKED` | Safe continuation cannot be established because capability/evidence/authorization is absent, input conflicts, plan validity changed, an unknown effect remains indeterminate, or destructive impact cannot be bounded. |
+| `WAITING_USER` | Execution is safely paused for an exact confirmation, login, MFA, browser approval, manual action, or separately authorized test boundary. Minimal recovery is available when its write was confirmed. |
+| `CANCELLED` | The operator cancelled; no further unconfirmed action ran, and confirmed safe cleanup plus residual-resource reporting completed. |
+
+Partial completion is never `SUCCEEDED`. A release can be live while the operation is `FAILED`; say both. A control-plane “accepted,” queued, or zero-exit response is not success until required layers pass.
+
+## Final Result
+
+Return and, when confirmed, persist the complete terminal result defined by `${SKILL_DIR}/references/deploy-record-schema.json` and accepted by the shipped semantic validator:
+
+- terminal status and operation;
+- target profile and immutable plan identity;
+- start/finish boundary and concise summary;
+- observed live state and release identity;
+- rollback availability: `VERIFIED`, `UNVERIFIED`, `ABSENT`, `UNKNOWN`, or `NOT_APPLICABLE`;
+- every verification layer with required flag, status, and evidence;
+- residual releases, processes, artifacts, locks, migrations, traffic state, and other project-owned resources;
+- local-record update result;
+- exact recovery guidance and relevant next operations.
+
+Report inaccessible or inapplicable layers explicitly. Never fill missing evidence with `PASSED`.
+
+## Failure Handling
+
+At the first failed step or required layer:
+
+1. stop dependent actions and plan expansion;
+2. bound and redact the failure evidence;
+3. observe current target/release/runtime/data/traffic state read-only;
+4. classify every planned write as proven applied, proven not applied, or indeterminate;
+5. perform only cleanup already authorized by the immutable plan and safe in the observed state;
+6. determine rollback availability from current evidence;
+7. select `FAILED`, `BLOCKED`, or `WAITING_USER` truthfully;
+8. preserve residual resources needed for diagnosis unless confirmed cleanup says otherwise.
+
+Never automatically replay an indeterminate write. Follow the `unknown_outcome_inspection` step. Only proven read-only or idempotent actions may use bounded retry.
+
+### Failure Before Any Write
+
+If a precondition or capability fails before execution, live state remains unchanged. Return `BLOCKED` when continuation lacks evidence/authorization or `FAILED` when confirmed execution itself failed. Do not create a misleading release/history event file.
+
+### Failure After a Write
+
+State the applied/unknown effects, current live release, health, traffic, data state, residual resources, and whether old/new units coexist. A healthy previous release does not erase a failed candidate operation.
+
+### Failed Health
+
+Required health failure always fails the operation. If traffic/live selection changed, inspect actual live state and apply only a pre-confirmed verified rollback; otherwise stop and offer the verified rollback or manual recovery.
+
+### Local Record Failure
+
+If the live target changed but the required `.prizmkit/deploy/deploy.json` update or read-back validation failed:
+
+- return `FAILED`;
+- report that the target may be live and local state is stale;
+- preserve the candidate temporary/legacy evidence without overwriting uncertain files;
+- require read-only target rediscovery before any later record repair or deployment;
+- never replay the deployment to repair the record.
+
+## Rollback
+
+A rollback is `VERIFIED` only when current evidence establishes:
+
+- exact prior release/configuration/data identity;
+- required artifacts/state still exist and match the target;
+- rollback action and authorization are available;
+- compatibility with the current persistent-data state;
+- rollback verification and restore-on-rollback-failure behavior.
+
+`UNVERIFIED`, `UNKNOWN`, or `ABSENT` rollback is not offered as an automated safety guarantee.
+
+A rollback may run automatically only when it was explicitly part of the confirmed immutable failure plan and its preconditions still match. Otherwise show the exact rollback plan/effects and obtain confirmation. Rollback itself uses all applicable verification layers. Failed rollback leaves the operation `FAILED` and reports both attempted states.
+
+When rollback is absent, do not block a deploy that received exact `NO_RELIABLE_ROLLBACK` risk acceptance. On failure, provide live-state evidence, residual resources, the earliest safe manual stop point, and a concrete manual recovery procedure. Do not claim the old release can be restored.
+
+## Interruption and Unknown Remote State
+
+A process/session interruption does not reveal whether the target wrote state. On recovery:
+
+1. validate the sole local record with both schema and semantic validation without dropping unknown data;
+2. load only `plan_id`, Secret-free plan digest, operation/profile, last proven step, minimal confirmation receipts, pending checkpoint, and bounded observations from `recovery`;
+3. rediscover project revision, target identity, authentication identity, tool capability/version, native configuration, actual ports, live/release/runtime/data/traffic state, health boundary, and rollback evidence affected by the plan;
+4. recompile the complete candidate plan from current authoritative evidence and compare its Secret-free digest with the stored immutable digest; never reconstruct actions from history summaries;
+5. inspect each possibly executed write before replay;
+6. continue only from the first unproven step when earlier postconditions are proven and every required confirmation receipt matches the digest; when a receipt is absent or cannot be validated, request fresh confirmation;
+7. compile and preview a new plan when identity, command/action, effect, risk, scope, or evidence assumption changed;
+8. clear recovery only after a verified terminal result is safely recorded.
+
+Do not reconstruct commands from history summaries. Do not infer “not applied” from a missing client response. Do not claim concurrent session safety; this procedure assumes one operator.
+
+## Human Checkpoint Recovery
+
+For login, MFA, browser approval, confirmation, or another manual action:
+
+- record `WAITING_USER`, exact non-sensitive action, and expected postcondition;
+- never store a password, token, challenge, browser cookie, one-time code, approval URL containing credentials, or raw authentication output;
+- after the user reports completion, re-run the planned read-only identity/authorization/postcondition probes;
+- remain `WAITING_USER` or become `BLOCKED` when revalidation fails;
+- resume only when the immutable plan and target identity still match.
+
+The user's “done” is a signal to revalidate, not verification itself.
+
+## Bounded Retry
+
+Retry only when the immutable plan identifies the action as proven read-only or idempotent, the error as transient, the maximum attempts as greater than the current attempt, and the stop condition as unmet. Report each attempt without a duration promise.
+
+Never retry automatically after authentication denial, invalid input, migration uncertainty, destructive failure, required health failure, plan mismatch, or an indeterminate write.
+
+## Deterministic Recovery Cases
+
+| Observed case | Terminal/result behavior |
+|---|---|
+| Command result passed; required configured health failed | `FAILED`; report actual live state and verified rollback availability |
+| External URL required but controller cannot access it | `FAILED` or `BLOCKED` according to whether execution occurred; layer is `INACCESSIBLE`, never `PASSED` |
+| Startup logs do not exist for this target | Layer is `NOT_APPLICABLE` with reason |
+| Login or browser approval is required | `WAITING_USER`; persist minimal checkpoint only after confirmed record write |
+| Possible write timed out; inspection proves applied | Do not replay; continue verification from the proven postcondition |
+| Possible write timed out; inspection proves not applied | Retry only within confirmed idempotent policy |
+| Possible write timed out; inspection is indeterminate | `BLOCKED` or `WAITING_USER`; replay needs dedicated confirmation |
+| Rollback is verified after failed required health | Offer or run only according to confirmed rollback policy, then verify rollback |
+| Rollback is absent after partial release | `FAILED` with live state, residual resources, and manual recovery |
+| Live release is healthy but sole-record write failed | `FAILED`; state target-live/local-record-stale and rediscover before repair |

package/bundled/skills/prizmkit-deploy/scripts/validate-deploy-artifact.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""Validate non-sensitive semantic invariants for PrizmKit Deploy artifacts.
+
+This companion validator is intentionally read-only and standard-library-only.
+JSON Schema validation remains mandatory; this script enforces cross-field and
+host-neutral path rules that are awkward to express or easy to regress in a
+schema alone. Diagnostics contain stable codes and JSON paths, never values.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import stat
+import sys
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+MAX_INPUT_BYTES = 1024 * 1024
+MAX_ERRORS = 50
+VERIFICATION_LAYERS = {
+    "command_or_platform",
+    "runtime_or_release",
+    "configured_health",
+    "external_url",
+    "startup_logs",
+}
+FORBIDDEN_FIELDS = {
+    "value",
+    "secret_value",
+    "password",
+    "token",
+    "private_key",
+    "connection_string",
+    "raw_output",
+    "raw_logs",
+}
+_SAFE_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+_DRIVE_PREFIX = re.compile(r"^[A-Za-z]:")
+
+
+class DuplicateKeyError(ValueError):
+    """Raised for a duplicate object key without retaining its key or value."""
+
+
+@dataclass(frozen=True, order=True)
+class ValidationError:
+    code: str
+    path: str
+
+    def as_dict(self) -> dict[str, str]:
+        return {"code": self.code, "path": self.path}
+
+
+class ErrorCollector:
+    """Collect a bounded deterministic set of non-sensitive diagnostics."""
+
+    def __init__(self) -> None:
+        self._errors: set[ValidationError] = set()
+
+    def add(self, code: str, path: str) -> None:
+        if len(self._errors) >= MAX_ERRORS:
+            return
+        self._errors.add(ValidationError(code=code, path=path))
+
+    def result(self) -> list[dict[str, str]]:
+        return [error.as_dict() for error in sorted(self._errors)]
+
+
+def _strict_object(pairs: Sequence[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise DuplicateKeyError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _load_json(path: Path) -> tuple[Any | None, list[dict[str, str]]]:
+    try:
+        metadata = path.lstat()
+    except OSError:
+        return None, [{"code": "INPUT_UNREADABLE", "path": "$"}]
+    if path.is_symlink() or not stat.S_ISREG(metadata.st_mode):
+        return None, [{"code": "INPUT_NOT_REGULAR_FILE", "path": "$"}]
+    if metadata.st_size > MAX_INPUT_BYTES:
+        return None, [{"code": "INPUT_TOO_LARGE", "path": "$"}]
+    try:
+        content = path.read_text(encoding="utf-8")
+        return json.loads(content, object_pairs_hook=_strict_object), []
+    except DuplicateKeyError:
+        return None, [{"code": "DUPLICATE_KEY", "path": "$"}]
+    except (OSError, UnicodeError, json.JSONDecodeError, RecursionError):
+        return None, [{"code": "INVALID_JSON", "path": "$"}]
+
+
+def _is_project_relative_path(value: Any, *, allow_root: bool = False) -> bool:
+    if not isinstance(value, str) or not value or len(value) > 512:
+        return False
+    if value == ".":
+        return allow_root
+    if value.startswith("/") or _DRIVE_PREFIX.match(value) or "\\" in value:
+        return False
+    if any(unicodedata.category(character) in {"Cc", "Cs"} for character in value):
+        return False
+    parts = value.split("/")
+    return all(part not in {"", ".", ".."} for part in parts)
+
+
+def _is_legacy_deploy_path(value: Any) -> bool:
+    return _is_project_relative_path(value) and str(value).startswith(".prizmkit/deploy/")
+
+
+def _iter_list(value: Any) -> Iterable[tuple[int, Any]]:
+    if not isinstance(value, list):
+        return ()
+    return enumerate(value)
+
+
+def _check_path_list(
+    value: Any,
+    path: str,
+    errors: ErrorCollector,
+    *,
+    legacy: bool = False,
+) -> None:
+    predicate = _is_legacy_deploy_path if legacy else _is_project_relative_path
+    for index, item in _iter_list(value):
+        if not predicate(item):
+            errors.add("UNSAFE_MANAGED_PATH", f"{path}[{index}]")
+
+
+def _check_forbidden_fields(value: Any, path: str, errors: ErrorCollector) -> None:
+    pending: list[tuple[Any, str]] = [(value, path)]
+    while pending:
+        current, current_path = pending.pop()
+        if isinstance(current, Mapping):
+            for key, child in current.items():
+                child_path = (
+                    f"{current_path}.{key}"
+                    if _SAFE_KEY.fullmatch(str(key))
+                    else f"{current_path}.[unknown]"
+                )
+                if str(key).lower() in FORBIDDEN_FIELDS:
+                    errors.add("FORBIDDEN_SENSITIVE_FIELD", child_path)
+                pending.append((child, child_path))
+        elif isinstance(current, list):
+            pending.extend(
+                (child, f"{current_path}[{index}]")
+                for index, child in enumerate(current)
+            )
+
+
+def _check_unique_names(
+    value: Any,
+    path: str,
+    field: str,
+    code: str,
+    errors: ErrorCollector,
+) -> set[str]:
+    seen: set[str] = set()
+    for index, item in _iter_list(value):
+        if not isinstance(item, Mapping):
+            continue
+        identity = item.get(field)
+        if not isinstance(identity, str):
+            continue
+        if identity in seen:
+            errors.add(code, f"{path}[{index}].{field}")
+        seen.add(identity)
+    return seen
+
+
+def _check_profile_reference(
+    value: Any,
+    path: str,
+    profiles: set[str],
+    errors: ErrorCollector,
+) -> None:
+    if value is not None and isinstance(value, str) and value not in profiles:
+        errors.add("DANGLING_PROFILE_REFERENCE", path)
+
+
+def _check_terminal_result(value: Any, path: str, errors: ErrorCollector) -> None:
+    if not isinstance(value, Mapping):
+        return
+    verification = value.get("verification")
+    if not isinstance(verification, list):
+        errors.add("VERIFICATION_LAYER_SET", f"{path}.verification")
+        return
+
+    layers: list[str] = []
+    for item in verification:
+        if isinstance(item, Mapping) and isinstance(item.get("layer"), str):
+            layers.append(item["layer"])
+    if len(verification) != len(VERIFICATION_LAYERS) or set(layers) != VERIFICATION_LAYERS:
+        errors.add("VERIFICATION_LAYER_SET", f"{path}.verification")
+    if len(layers) != len(set(layers)):
+        errors.add("DUPLICATE_VERIFICATION_LAYER", f"{path}.verification")
+
+    if value.get("status") == "SUCCEEDED":
+        for index, item in _iter_list(verification):
+            if (
+                isinstance(item, Mapping)
+                and item.get("required") is True
+                and item.get("status") != "PASSED"
+            ):
+                errors.add(
+                    "SUCCEEDED_REQUIRED_LAYER_NOT_PASSED",
+                    f"{path}.verification[{index}]",
+                )
+
+
+def _validate_record(data: Any, errors: ErrorCollector) -> None:
+    if not isinstance(data, Mapping):
+        errors.add("ROOT_NOT_OBJECT", "$")
+        return
+
+    project = data.get("project")
+    if isinstance(project, Mapping):
+        _check_path_list(
+            project.get("native_config_files"),
+            "$.project.native_config_files",
+            errors,
+        )
+
+    profiles_value = data.get("profiles")
+    profiles = _check_unique_names(
+        profiles_value,
+        "$.profiles",
+        "id",
+        "DUPLICATE_PROFILE_ID",
+        errors,
+    )
+    for index, profile in _iter_list(profiles_value):
+        if isinstance(profile, Mapping):
+            _check_path_list(
+                profile.get("native_config_files"),
+                f"$.profiles[{index}].native_config_files",
+                errors,
+            )
+
+    _check_unique_names(
+        data.get("secret_references"),
+        "$.secret_references",
+        "name",
+        "DUPLICATE_SECRET_REFERENCE",
+        errors,
+    )
+
+    current = data.get("current")
+    if isinstance(current, Mapping):
+        _check_profile_reference(
+            current.get("profile_id"),
+            "$.current.profile_id",
+            profiles,
+            errors,
+        )
+
+    latest = data.get("latest_result")
+    if isinstance(latest, Mapping):
+        _check_profile_reference(
+            latest.get("profile_id"),
+            "$.latest_result.profile_id",
+            profiles,
+            errors,
+        )
+        _check_terminal_result(latest, "$.latest_result", errors)
+
+    for index, history in _iter_list(data.get("history")):
+        if isinstance(history, Mapping):
+            _check_profile_reference(
+                history.get("profile_id"),
+                f"$.history[{index}].profile_id",
+                profiles,
+                errors,
+            )
+
+    recovery = data.get("recovery")
+    if isinstance(recovery, Mapping):
+        _check_profile_reference(
+            recovery.get("profile_id"),
+            "$.recovery.profile_id",
+            profiles,
+            errors,
+        )
+
+    legacy = data.get("legacy_migration")
+    if isinstance(legacy, Mapping):
+        sources = legacy.get("sources")
+        for index, source in _iter_list(sources):
+            if isinstance(source, Mapping) and not _is_legacy_deploy_path(source.get("path")):
+                errors.add("UNSAFE_MANAGED_PATH", f"$.legacy_migration.sources[{index}].path")
+        _check_path_list(
+            legacy.get("preserved_paths"),
+            "$.legacy_migration.preserved_paths",
+            errors,
+            legacy=True,
+        )
+
+
+def _validate_declaration(data: Any, errors: ErrorCollector) -> None:
+    if not isinstance(data, Mapping):
+        errors.add("ROOT_NOT_OBJECT", "$")
+        return
+
+    _check_path_list(data.get("native_config_files"), "$.native_config_files", errors)
+    _check_unique_names(
+        data.get("profile_hints"),
+        "$.profile_hints",
+        "id",
+        "DUPLICATE_PROFILE_ID",
+        errors,
+    )
+    _check_unique_names(
+        data.get("secret_references"),
+        "$.secret_references",
+        "name",
+        "DUPLICATE_SECRET_REFERENCE",
+        errors,
+    )
+
+    for index, command in _iter_list(data.get("commands")):
+        if (
+            isinstance(command, Mapping)
+            and not _is_project_relative_path(command.get("working_directory"), allow_root=True)
+        ):
+            errors.add("UNSAFE_MANAGED_PATH", f"$.commands[{index}].working_directory")
+
+    for index, hint in _iter_list(data.get("capability_hints")):
+        if isinstance(hint, Mapping):
+            _check_path_list(
+                hint.get("evidence_files"),
+                f"$.capability_hints[{index}].evidence_files",
+                errors,
+            )
+
+
+def validate(kind: str, data: Any) -> list[dict[str, str]]:
+    errors = ErrorCollector()
+    _check_forbidden_fields(data, "$", errors)
+    if kind == "record":
+        _validate_record(data, errors)
+    else:
+        _validate_declaration(data, errors)
+    return errors.result()
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Validate semantic invariants for one PrizmKit Deploy artifact."
+    )
+    parser.add_argument("--kind", choices=("record", "declaration"), required=True)
+    parser.add_argument("path", type=Path)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    data, load_errors = _load_json(args.path)
+    errors = load_errors or validate(args.kind, data)
+    output = {"valid": not errors, "errors": errors}
+    print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled/skills/prizmkit-implement/SKILL.md

@@ -36,8 +36,8 @@ Before editing:
 
 1. Read `plan.md`, `spec.md`, and only relevant companion artifacts.
 2. Read `.prizmkit/prizm-docs/root.prizm` when present.
-3. Follow its pointers to only the relevant module and detail documentation.
-4. If relevant detail documentation is missing, read the target source files as fallback and record that detailed context was unavailable. Context loading does not create or modify documentation.
+3. Follow its pointers to only the relevant direct-child module index and nested detail documentation. Before modifying source, read the complete relevant detail plus the complete parent/child documents needed to resolve its pointers; grep-only fragments are insufficient modification context.
+4. If relevant detail documentation is missing, inspect only bounded target source files and narrowly implicated callers/contracts as fallback, record that detailed context was unavailable, and proceed without creating a placeholder. Context loading never creates or modifies documentation.
 5. Read referenced layer rules when present. If a rule conflicts with the plan, stop and ask the user unless the plan clearly supersedes the rule.
 
 ## Optional Inline Delegation

package/bundled/skills/prizmkit-init/SKILL.md

@@ -25,7 +25,7 @@ Recommended project initialization skill. Scans any brownfield or greenfield pro
 
 ### Artifact Ownership
 
-All paths under `.prizmkit/` are framework-internal and remain outside automated task commits. Initialization must not stage or commit them. Root instruction or platform-support files written during setup also remain support data rather than task-owned source.
+`.prizmkit/**` is the PrizmKit framework directory. Initialization may read and write only its declared managed artifacts, but it does not stage, commit, force-add, change or interpret `.gitignore`, require Git history, or decide whether those paths are ignored, untracked, or tracked. The project controls Git visibility; initialization behavior is otherwise identical. Root instruction and platform-support files remain support data rather than initialization-owned commit output.
 
 ## Host-Neutral Interaction and Discovery
 
@@ -81,8 +81,8 @@ BROWNFIELD WORKFLOW (existing project):
 2. Map directory structure using a TWO-TIER model — flat structures lose the nesting relationships that AI needs to navigate the codebase:
    - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
    - SUB-MODULES: directories INSIDE a top-level module (e.g. `src/routes/`, `src/models/`)
-   - A sub-module maps to `.prizmkit/prizm-docs/<M>/<S>.prizm`, never to `.prizmkit/prizm-docs/<S>.prizm` — flattening would create ambiguous paths when two modules have identically-named sub-modules
-   - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.prizmkit/`
+   - Exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); sub-module S maps to nested `.prizmkit/prizm-docs/<M>/<S>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
+   - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
    - **Bounded discovery contract** — use the current Host's available directory-listing or file-search capability to enumerate at most two directory levels, apply the exclusions above before analysis, preserve parent/child relationships, and report the resulting project-relative structure. Do not require a POSIX shell pipeline or any other operating-system-specific command.
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
@@ -179,12 +179,12 @@ After Infrastructure Quick Scan completes, check if `detected_layers` is non-emp
 
 **Phase 5: Prizm Documentation Generation**
 Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
-  - Create `.prizmkit/prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizmkit/prizm-docs/<top-level>/`)
-  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
-  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
-  - Generate L1 docs for top-level modules at `.prizmkit/prizm-docs/<M>.prizm` and for sub-modules at `.prizmkit/prizm-docs/<M>/<S>.prizm`
-  - Skip L2 (lazy generation) — L2 is created later by `/prizmkit-retrospective` when a changed module has meaningful behavior or durable knowledge. During implementation, if an affected L2 is missing, `/prizmkit-implement` reads the target source files as fallback instead of blocking.
-  - Do not create auxiliary `changelog.prizm`, 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; git history is the source of change history
+  - Create only documentation directories needed by complete documents; do not create placeholder sub-module files.
+  - Generate exact `root.prizm` (L0) with `PRIZM_VERSION: 4`, project meta, and MODULE_INDEX listing only top-level modules. If module count > 15 or measured capacity requires it, use MODULE_GROUPS.
+  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include only high-value intent tags and a pointer to one direct-child L1 at `.prizmkit/prizm-docs/<M>.prizm`.
+  - Generate one direct-child L1 structural index for each top-level module. Record source submodules structurally, but emit a SUBDIRS pointer only when its complete nested L2 exists.
+  - Skip all L2 during Init. Before later source modification, read a complete existing relevant L2 and complete resolving pointer documents; if absent, inspect bounded relevant source as fallback without creating a placeholder. `/prizmkit-retrospective` may later create a complete Value-Gate-qualified L2.
+  - Do not create auxiliary `changelog.prizm`, 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; temporal history is outside Prizm memory
 
 **Phase 6: Workspace Initialization**
 6a. Create `.prizmkit/` directory structure (if missing):
@@ -308,15 +308,15 @@ Rules Quick Entry:
   Matched layers: frontend (React), backend (Express.js), database (Prisma) → no rule profiles enabled yet
 
 Modules discovered:
-  src/routes/     → .prizmkit/prizm-docs/routes.prizm (12 files)
-  src/models/     → .prizmkit/prizm-docs/models.prizm (8 files)
-  src/services/   → .prizmkit/prizm-docs/services.prizm (15 files)
-  src/middleware/  → .prizmkit/prizm-docs/middleware.prizm (5 files)
+  src/            → .prizmkit/prizm-docs/src.prizm (top-level L1)
+  src/routes/     → nested source submodule (no placeholder L2 during Init)
+  src/models/     → nested source submodule (no placeholder L2 during Init)
+  src/services/   → nested source submodule (no placeholder L2 during Init)
 
 Project brief: inferred from codebase → confirmed by user
   → .prizmkit/plans/project-brief.md
 
-Generated: root.prizm + 4 L1 docs
+Generated: root.prizm + 1 direct-child L1 doc
 Saved: .prizmkit/config.json (tech_stack + detected_layers + enabled_rule_profiles recorded)
 
 Next: Use /prizmkit-plan to start your first feature
@@ -345,9 +345,9 @@ Tech stack changes detected:
   = frontend: React (unchanged)
 
 Documentation gap-fill:
-  + app/share/[token].prizm (L2) — created (3 source files, meaningful logic)
-  = routes.prizm (L1) — up to date
-  ~ models.prizm (L1) — FILES count updated (8 → 10)
+  = app.prizm (direct-child L1) — up to date
+  source fallback: app/share/[token] (nested L2 absent; no placeholder created)
+  ~ app.prizm (L1) — concise source summary updated
 
 Project brief: inferred from codebase → confirmed by user
   → .prizmkit/plans/project-brief.md (generated)

package/bundled/skills/prizmkit-init/references/update-supplement.md

@@ -2,8 +2,8 @@
 
 Runs after tech stack merge in Update mode:
 
-1. **Module scan**: Re-scan project directories using the same TWO-TIER model from Step 1. Compare discovered modules against existing MODULE_INDEX in root.prizm.
-2. **Missing L1 check**: For any discovered module with no corresponding L1 `.prizm` doc → create L1 immediately and add to MODULE_INDEX.
-3. **Missing L2 check**: For any module/sub-module that has source files with meaningful logic but no L2 `.prizm` doc → create L2 using the L2 GENERATION TEMPLATE. Judgment call: skip trivial wrapper directories or single-config modules.
-4. **Stale L1 check**: For existing L1 docs, verify FILES count and KEY_FILES are still accurate. Update if source directory contents have changed significantly.
-5. **Report**: Include in the Update report: modules added, L1 docs created, L2 docs created, stale docs refreshed.
+1. **Bounded module scan**: Re-scan only the registered top-level source modules and concrete structural gaps using the same two-tier model. Exclude the complete `.prizmkit/` framework directory, including installed `.prizmkit/dev-pipeline/`, but do not exclude a repository's canonical top-level `dev-pipeline/` source module.
+2. **Missing L1 check**: For a discovered top-level module with no direct-child L1, build one complete Value-Gate-filtered structural candidate at `.prizmkit/prizm-docs/<M>.prizm` and add a resolving root pointer only after the candidate validates.
+3. **Missing L2 context**: For an affected source submodule with no nested L2, inspect only the bounded source files and narrowly implicated contracts needed to determine the gap. Do not create a placeholder. A complete L2 may be created only when current durable facts pass the Value Gate and mirrored/semantic identity, ownership, pointer, format, and capacity checks all pass.
+4. **Existing target reconciliation**: Read every complete affected target and complete resolving parent/child pointer document. Apply Cleanup by semantic meaning, preserve protected knowledge, build candidates bottom-up, skip byte-identical replacements, and re-read actual bytes after writes.
+5. **Failure and report**: If any post-write check fails, restore exact pre-write bytes and remove invalid new targets before reporting a blocker. Report modules/details added, skipped source fallbacks, stale summaries reconciled, and capacity/pointer validation. Never stage, commit, force-add, change or interpret `.gitignore`, require Git history, or classify tracking state as documentation health.