prizmkit 1.1.140 → 1.1.142

package/bundled/dev-pipeline/scripts/update-checkpoint.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Atomically update one semantic L4 workflow checkpoint."""
+"""Atomically update one semantic pipeline workflow checkpoint."""
 
 import argparse
 import json
@@ -15,12 +15,16 @@ if _PIPELINE_ROOT not in sys.path:
 from prizmkit_runtime.checkpoint_state import (  # noqa: E402
     MAX_OUTER_REPAIR_ROUNDS,
     REVIEW_RESULTS,
+    SKILL_WORKFLOW_STAGES,
     STEP_ID_PATTERN,
     TERMINAL_STEP_STATUSES,
     TEST_RESULTS,
     VALID_CHECKPOINT_STATUSES,
+    VALID_STAGE_RESULTS,
     VALID_REPAIR_SCOPES,
     VALID_TERMINAL_STATUSES,
+    expected_status_for_stage_result,
+    stage_result_allowed_for_skill,
     load_checkpoint_state,
     semantic_state_key,
     validate_checkpoint_data,
@@ -120,13 +124,11 @@ def _mandatory_predecessor_verdict_error(steps, index, workflow_type):
     return None
 
 def _normalize_semantic_update(semantic_update):
-    values = dict(semantic_update or {})
-    evidence = values.pop("authoritative_evidence_paths", None)
-    if evidence is not None:
-        evidence = {key: value for key, value in evidence.items() if value}
-        if evidence:
-            values["authoritative_evidence_paths"] = evidence
-    return {key: value for key, value in values.items() if value is not None}
+    return {
+        key: value
+        for key, value in dict(semantic_update or {}).items()
+        if value is not None
+    }
 
 
 def _validate_semantic_update(step, semantic_update):
@@ -136,6 +138,12 @@ def _validate_semantic_update(step, semantic_update):
         return "Review verdicts may only be recorded on prizmkit-code-review"
     if stage_result in TEST_RESULTS and skill != "prizmkit-test":
         return "Test verdicts may only be recorded on prizmkit-test"
+    if not stage_result_allowed_for_skill(skill, stage_result):
+        return "{} cannot record stage result {}".format(skill, stage_result)
+    expected_status = expected_status_for_stage_result(stage_result)
+    if expected_status is not None and semantic_update.get("status") is not None:
+        if semantic_update["status"] != expected_status:
+            return "{} requires status={}".format(stage_result, expected_status)
     repair_scope = semantic_update.get("repair_scope")
     if repair_scope is not None and repair_scope not in VALID_REPAIR_SCOPES:
         return "Invalid repair_scope '{}'".format(repair_scope)
@@ -145,28 +153,29 @@ def _validate_semantic_update(step, semantic_update):
     terminal_status = semantic_update.get("terminal_status")
     if terminal_status is not None and terminal_status not in VALID_TERMINAL_STATUSES:
         return "Invalid terminal_status '{}'".format(terminal_status)
-    evidence = semantic_update.get("authoritative_evidence_paths")
-    if evidence is not None and set(evidence) != {"manifest", "verdict", "validation"}:
-        return "Authoritative test evidence requires manifest, verdict, and validation paths"
     if terminal_status == "WORKFLOW_BLOCKED" and not semantic_update.get("blocked_reason"):
         return "WORKFLOW_BLOCKED requires blocked_reason"
     return None
 
 
 def _apply_repair_policy(l4_state, stage_result, repair_scope):
-    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_FAIL", "TEST_BLOCKED"}:
-        return
+    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
+        return False
     current_round = l4_state.get("repair_round", 0)
     if not isinstance(current_round, int) or isinstance(current_round, bool):
         current_round = MAX_OUTER_REPAIR_ROUNDS
-    if stage_result == "TEST_BLOCKED":
+    if stage_result in {"TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
         l4_state.update(
             terminal_status="WORKFLOW_BLOCKED",
-            blocked_reason="test_blocked",
+            blocked_reason=(
+                "test_needs_fixes"
+                if stage_result == "TEST_NEEDS_FIXES"
+                else "test_blocked"
+            ),
             current_stage=None,
             next_stage=None,
         )
-        return
+        return False
     if current_round >= MAX_OUTER_REPAIR_ROUNDS:
         l4_state.update(
             repair_round=MAX_OUTER_REPAIR_ROUNDS,
@@ -175,7 +184,7 @@ def _apply_repair_policy(l4_state, stage_result, repair_scope):
             current_stage=None,
             next_stage=None,
         )
-        return
+        return False
     if repair_scope not in VALID_REPAIR_SCOPES:
         l4_state.update(
             terminal_status="WORKFLOW_BLOCKED",
@@ -183,14 +192,15 @@ def _apply_repair_policy(l4_state, stage_result, repair_scope):
             current_stage=None,
             next_stage=None,
         )
-        return
+        return False
     l4_state["repair_round"] = current_round + 1
     l4_state["terminal_status"] = None
     l4_state["blocked_reason"] = None
     l4_state["next_stage"] = "prizmkit-implement"
+    return True
 
 
-def _sync_cursor(data, l4_state):
+def _sync_cursor(data, l4_state, preserve_next_stage=False):
     active = next(
         (step for step in data["steps"] if step.get("status") not in TERMINAL_STEP_STATUSES),
         None,
@@ -199,11 +209,9 @@ def _sync_cursor(data, l4_state):
         l4_state["current_stage"] = None
         l4_state["next_stage"] = None
         return
+    routed_stage = l4_state.get("next_stage") if preserve_next_stage else None
     l4_state["current_stage"] = active.get("skill") if active else None
-    l4_state["next_stage"] = active.get("skill") if active else None
-
-
-
+    l4_state["next_stage"] = routed_stage or (active.get("skill") if active else None)
 
 def _checkpoint_project_root(checkpoint_path):
     """Resolve the project root from a conventional .prizmkit checkpoint path."""
@@ -213,69 +221,6 @@ def _checkpoint_project_root(checkpoint_path):
             return str(parent.parent)
     return str(path.parent)
 
-def _discover_test_evidence_paths(checkpoint_path, data):
-    """Discover the latest finalized test package from the artifact handoff pointer."""
-    project_root = Path(_checkpoint_project_root(checkpoint_path))
-    candidates = []
-    artifact_dir = data.get("artifact_dir")
-    if isinstance(artifact_dir, str) and artifact_dir:
-        candidates.append(project_root / artifact_dir)
-    for state_key in ("feature_state", "bugfix_state", "refactor_state"):
-        state = data.get(state_key)
-        if isinstance(state, dict) and isinstance(state.get("artifact_dir"), str):
-            candidates.append(project_root / state["artifact_dir"])
-    item_slug = data.get("item_slug")
-    if isinstance(item_slug, str) and item_slug:
-        candidates.append(project_root / ".prizmkit" / "specs" / item_slug)
-        candidates.append(project_root / ".prizmkit" / "bugfix" / item_slug)
-        candidates.append(project_root / ".prizmkit" / "refactor" / item_slug)
-
-    for artifact in candidates:
-        pointer = artifact / "test-report-path.txt"
-        try:
-            report = Path(pointer.read_text(encoding="utf-8").strip()).resolve()
-        except (OSError, ValueError):
-            continue
-        evidence_dir = report.parent
-        evidence_root = (project_root / ".prizmkit" / "test" / "evidence").resolve()
-        try:
-            relative_evidence = evidence_dir.resolve().relative_to(evidence_root)
-        except (OSError, ValueError):
-            continue
-        if len(relative_evidence.parts) != 1:
-            continue
-        paths = {
-            "manifest": evidence_dir / "manifest.json",
-            "verdict": evidence_dir / "verdict.json",
-            "validation": evidence_dir / "validation.json",
-        }
-        if not all(path.is_file() for path in paths.values()):
-            continue
-        try:
-            manifest = json.loads(paths["manifest"].read_text(encoding="utf-8"))
-            verdict = json.loads(paths["verdict"].read_text(encoding="utf-8"))
-            validation = json.loads(paths["validation"].read_text(encoding="utf-8"))
-        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
-            continue
-        if not all(isinstance(record, dict) for record in (manifest, verdict, validation)):
-            continue
-        if (
-            manifest.get("evidence_id") != evidence_dir.name
-            or manifest.get("final_verdict") != "TEST_BLOCKED"
-            or verdict.get("verdict") != "TEST_BLOCKED"
-            or validation.get("result") != "passed"
-            or validation.get("verdict") != "TEST_BLOCKED"
-        ):
-            continue
-        try:
-            return {
-                key: str(path.resolve().relative_to(project_root.resolve()))
-                for key, path in paths.items()
-            }
-        except (OSError, ValueError):
-            continue
-    return None
-
 
 def _finalize_semantics(checkpoint_path, data, state_key):
     """Derive a deterministic terminal status after an atomic mutation."""
@@ -313,7 +258,7 @@ def update_checkpoint(
     note=None,
     semantic_update=None,
 ):
-    """Update one step and its cohesive semantic L4 state atomically."""
+    """Update one step and its cohesive semantic pipeline state atomically."""
     if new_status not in VALID_STATUSES:
         return {
             "ok": False,
@@ -350,24 +295,11 @@ def update_checkpoint(
             return {"ok": False, "error": verdict_error}
 
     semantic_update = _normalize_semantic_update(semantic_update)
-    if semantic_update.get("stage_result") == "TEST_BLOCKED" and not semantic_update.get("authoritative_evidence_paths"):
-        discovered = _discover_test_evidence_paths(checkpoint_path, data)
-        if discovered:
-            semantic_update["authoritative_evidence_paths"] = discovered
     semantic_error = _validate_semantic_update(step, semantic_update)
     if semantic_error:
         return {"ok": False, "error": semantic_error}
 
     stage_result = semantic_update.get("stage_result")
-    if step.get("skill") == "prizmkit-test" and stage_result in TEST_RESULTS:
-        evidence = semantic_update.get("authoritative_evidence_paths") or step.get("authoritative_evidence_paths")
-        if stage_result != "TEST_BLOCKED" and (
-            not isinstance(evidence, dict) or set(evidence) != {"manifest", "verdict", "validation"}
-        ):
-            return {
-                "ok": False,
-                "error": "Every terminal test verdict requires manifest, verdict, and validation evidence paths",
-            }
     if new_status == "completed" and step.get("skill") == "prizmkit-code-review":
         stage_result = stage_result or step.get("stage_result")
         if stage_result != "REVIEW_PASS":
@@ -376,9 +308,12 @@ def update_checkpoint(
         stage_result = stage_result or step.get("stage_result")
         if stage_result != "TEST_PASS":
             return {"ok": False, "error": "Test completion requires TEST_PASS"}
-        evidence = semantic_update.get("authoritative_evidence_paths") or step.get("authoritative_evidence_paths")
-        if not isinstance(evidence, dict) or set(evidence) != {"manifest", "verdict", "validation"}:
-            return {"ok": False, "error": "Test completion requires all authoritative evidence paths"}
+    expected_status = expected_status_for_stage_result(stage_result)
+    if expected_status is not None and new_status != expected_status:
+        return {
+            "ok": False,
+            "error": "{} requires status={}".format(stage_result, expected_status),
+        }
 
     old_status = step.get("status", "unknown")
     step["status"] = new_status
@@ -386,20 +321,8 @@ def update_checkpoint(
         step["note"] = note
     if stage_result:
         step["stage_result"] = stage_result
-    if semantic_update.get("authoritative_evidence_paths"):
-        step["authoritative_evidence_paths"] = semantic_update["authoritative_evidence_paths"]
-    if new_status == "completed" and step.get("skill") == "prizmkit-test":
-        candidate = validate_checkpoint_data(
-            data,
-            path=checkpoint_path,
-            exists=True,
-            project_root=_checkpoint_project_root(checkpoint_path),
-        )
-        if not candidate.valid or not candidate.semantic.evidence_valid:
-            return {
-                "ok": False,
-                "error": "Test completion requires validator-attested authoritative evidence",
-            }
+    else:
+        step.pop("stage_result", None)
 
     workflow_type = str(data.get("workflow_type") or "")
     state_key = semantic_state_key(workflow_type)
@@ -410,7 +333,6 @@ def update_checkpoint(
         "stage_result",
         "repair_scope",
         "repair_round",
-        "authoritative_evidence_paths",
         "blocked_reason",
         "terminal_status",
     ):
@@ -418,12 +340,19 @@ def update_checkpoint(
             l4_state[key] = semantic_update[key]
     l4_state["schema_version"] = 1
     l4_state["orchestrator"] = "prizmkit-l4"
+    skill = step.get("skill")
+    l4_state["stage"] = SKILL_WORKFLOW_STAGES.get(skill, skill)
+    l4_state["status"] = new_status
     if stage_result:
         l4_state["stage_result"] = stage_result
-    if semantic_update.get("authoritative_evidence_paths"):
-        l4_state["authoritative_evidence_paths"] = semantic_update["authoritative_evidence_paths"]
-    _apply_repair_policy(l4_state, stage_result, semantic_update.get("repair_scope") or l4_state.get("repair_scope"))
-    _sync_cursor(data, l4_state)
+    else:
+        l4_state.pop("stage_result", None)
+    repair_route_selected = _apply_repair_policy(
+        l4_state,
+        stage_result,
+        semantic_update.get("repair_scope") or l4_state.get("repair_scope"),
+    )
+    _sync_cursor(data, l4_state, preserve_next_stage=repair_route_selected)
     _finalize_semantics(checkpoint_path, data, state_key)
 
     final_state = validate_checkpoint_data(
@@ -462,12 +391,9 @@ def main():
     parser.add_argument("--step", required=True)
     parser.add_argument("--status", required=True, choices=sorted(VALID_STATUSES))
     parser.add_argument("--note", default=None)
-    parser.add_argument("--stage-result", choices=sorted(REVIEW_RESULTS | TEST_RESULTS), default=None)
+    parser.add_argument("--stage-result", choices=sorted(VALID_STAGE_RESULTS), default=None)
     parser.add_argument("--repair-scope", choices=sorted(VALID_REPAIR_SCOPES), default=None)
     parser.add_argument("--repair-round", type=int, default=None)
-    parser.add_argument("--manifest-path", default=None)
-    parser.add_argument("--verdict-path", default=None)
-    parser.add_argument("--validation-path", default=None)
     parser.add_argument("--blocked-reason", default=None)
     parser.add_argument("--terminal-status", choices=sorted(VALID_TERMINAL_STATUSES), default=None)
 
@@ -476,11 +402,6 @@ def main():
         "stage_result": args.stage_result,
         "repair_scope": args.repair_scope,
         "repair_round": args.repair_round,
-        "authoritative_evidence_paths": {
-            "manifest": args.manifest_path,
-            "verdict": args.verdict_path,
-            "validation": args.validation_path,
-        },
         "blocked_reason": args.blocked_reason,
         "terminal_status": args.terminal_status,
     }

package/bundled/dev-pipeline/scripts/update-feature-status.py

@@ -51,6 +51,7 @@ SESSION_STATUS_VALUES = [
     "context_overflow",
     "stalled_context_continuation",
     "workflow_blocked",
+    "workflow_skipped",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -156,7 +157,7 @@ def parse_args():
     parser.add_argument(
         "--checkpoint-state",
         default=None,
-        help="JSON semantic L4 checkpoint snapshot captured after the session.",
+        help="JSON semantic pipeline checkpoint snapshot captured after the session.",
     )
     return parser.parse_args()
 
@@ -370,7 +371,6 @@ SEMANTIC_CHECKPOINT_FIELDS = (
     "stage_result",
     "repair_scope",
     "repair_round",
-    "authoritative_evidence_paths",
     "blocked_reason",
     "terminal_status",
 )
@@ -1022,6 +1022,20 @@ def action_update(args, feature_list_path, state_dir):
             if err:
                 error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
                 return
+    elif session_status == "workflow_skipped":
+        # A completed AI CLI session without authoritative workflow evidence is
+        # skipped, not crashed. Preserve diagnostics and spend no retry budget.
+        new_status = "skipped"
+        fs["continuation_pending"] = False
+        fs.pop("continuation_reason", None)
+        fs.pop("terminal_status", None)
+        fs.pop("blocked_reason", None)
+        fs["needs_attention"] = True
+        fs["skipped_reason"] = "workflow_completion_evidence_invalid"
+        err = update_feature_in_list(feature_list_path, feature_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
+            return
     elif session_status == "workflow_blocked":
         # Semantic terminal state: preserve partial work without consuming any retry budget.
         new_status = "failed"
@@ -1120,6 +1134,11 @@ def action_update(args, feature_list_path, state_dir):
         summary["restart_policy"] = "context_overflow_continuation"
         summary.update(continuation_metadata_summary(fs))
         summary["artifacts_preserved"] = True
+    elif session_status == "workflow_skipped":
+        summary["restart_policy"] = "terminal_skipped"
+        summary.update(continuation_metadata_summary(fs))
+        summary["checkpoint_state"] = semantic_checkpoint
+        summary["artifacts_preserved"] = True
     elif session_status == "workflow_blocked":
         summary["restart_policy"] = "terminal_blocked"
         summary.update(continuation_metadata_summary(fs))

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -48,6 +48,7 @@ SESSION_STATUS_VALUES = [
     "context_overflow",
     "stalled_context_continuation",
     "workflow_blocked",
+    "workflow_skipped",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -101,7 +102,7 @@ def parse_args():
     parser.add_argument("--continuation-summary-path", default=None, help="Optional continuation summary artifact path.")
     parser.add_argument("--no-progress-count", type=int, default=None, help="Consecutive context-overflow sessions without objective progress.")
     parser.add_argument("--progress-fingerprint", default=None, help="JSON progress fingerprint captured after the session.")
-    parser.add_argument("--checkpoint-state", default=None, help="JSON semantic L4 checkpoint snapshot captured after the session.")
+    parser.add_argument("--checkpoint-state", default=None, help="JSON semantic pipeline checkpoint snapshot captured after the session.")
     return parser.parse_args()
 
 
@@ -260,7 +261,6 @@ SEMANTIC_CHECKPOINT_FIELDS = (
     "stage_result",
     "repair_scope",
     "repair_round",
-    "authoritative_evidence_paths",
     "blocked_reason",
     "terminal_status",
 )
@@ -598,6 +598,20 @@ def action_update(args, refactor_list_path, state_dir):
             if err:
                 error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
                 return
+    elif session_status == "workflow_skipped":
+        # A completed AI CLI session without authoritative workflow evidence is
+        # skipped, not crashed. Preserve diagnostics and spend no retry budget.
+        new_status = "skipped"
+        rs["continuation_pending"] = False
+        rs.pop("continuation_reason", None)
+        rs.pop("terminal_status", None)
+        rs.pop("blocked_reason", None)
+        rs["needs_attention"] = True
+        rs["skipped_reason"] = "workflow_completion_evidence_invalid"
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
+            return
     elif session_status == "workflow_blocked":
         # Semantic terminal state: preserve partial work without consuming any retry budget.
         new_status = "failed"
@@ -691,6 +705,11 @@ def action_update(args, refactor_list_path, state_dir):
         summary["restart_policy"] = "context_overflow_continuation"
         summary.update(continuation_metadata_summary(rs))
         summary["artifacts_preserved"] = True
+    elif session_status == "workflow_skipped":
+        summary["restart_policy"] = "terminal_skipped"
+        summary.update(continuation_metadata_summary(rs))
+        summary["checkpoint_state"] = semantic_checkpoint
+        summary["artifacts_preserved"] = True
     elif session_status == "workflow_blocked":
         summary["restart_policy"] = "terminal_blocked"
         summary.update(continuation_metadata_summary(rs))

package/bundled/dev-pipeline/templates/bootstrap-prompt.md

@@ -24,7 +24,7 @@ Infer what needs to be done from the feature context above and follow the active
 
 ### Execution Steps
 
-1. **Read context**: Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs to understand the codebase.
+1. **Read context**: Read `.prizmkit/prizm-docs/root.prizm` and the relevant module indexes and detail docs to understand the codebase.
 
 2. **Plan**: Run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to produce `spec.md` and `plan.md`.
 
@@ -32,7 +32,7 @@ Infer what needs to be done from the feature context above and follow the active
 
 4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and follow the skill's current review contract for review execution, repairs, verification, evidence, and handoff. Require the last `## Final Result`. `REVIEW_PASS` proceeds to test; `REVIEW_NEEDS_FIXES` increments the shared outer repair round and routes implement → code-review → test. Do not invoke another review entry point or add a second review path outside the skill contract.
 
-5. **Test**: After review passes, run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Treat the Markdown report only as a derived view. Consume `.prizmkit/test/evidence/<evidence-id>/manifest.json`, `verdict.json`, and `validation.json`; verify identity/scope, every manifest hash, verdict/validator agreement, and current target hashes before accepting `TEST_PASS`. `TEST_FAIL/test-infrastructure` routes implement → test; production/runtime/schema/dependency/public-interface routes implement → code-review → test; unknown unsafe scope blocks. `TEST_BLOCKED` allows bounded environment recovery or a test-stage resume but never speculative production edits. Stop outer repairs after three rounds; preserve evidence and truthful recovery metadata.
+5. **Test**: After review passes, run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Consume the sibling `test-report.md` and `test-result.json`; they must agree. `TEST_PASS` proceeds to retrospective. `TEST_NEEDS_FIXES` or `TEST_BLOCKED` preserves its known correction or blocker and stops truthfully. Do not require an evidence package, reinterpret a testing result as a runtime crash, or recreate the skill's bounded review and repair loops.
 
 6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` with code changes.
 
@@ -46,5 +46,5 @@ Infer what needs to be done from the feature context above and follow the active
 - If a step fails after 3 attempts, write a status report and stop.
 - **Never re-read unmodified files**: once you read a file into context, do NOT read it again unless it was modified by an Edit/Write after your last read — use `grep -n`/`sed -n` for specific lines. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Follow the active skill and runtime contracts when an execution unit is created; do not infer its permissions, continuation, or retry behavior from this fallback prompt.
 - **Read offset safety**: if Read returns "shorter than offset"/"empty" — run `wc -l` then `sed -n`, do NOT retry same offset.
-- **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Switch to read-once-then-rewrite. Do NOT exceed 7 rounds.
+- Follow each skill's own bounded loops; do not add a second cross-skill test-fix loop in this fallback prompt.
 - **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -128,7 +128,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
-1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and the relevant module indexes and detail docs
 2. Detect source code directories from KEY_FILES and STRUCTURE sections in `root.prizm`; if root docs are unavailable, use the helper to list likely source files:
    ```bash
    {{RUNTIME_HELPER_CMD}} artifact source-files . --json
@@ -138,7 +138,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description (2-3 lines) + acceptance criteria (copy from above)
    - **Section 2 — Verification Gates**: copy the gate checklist from the Task Contract above
-   - **Section 3 — Key TRAPS & RULES**: extract only relevant TRAPS/RULES from prizm-docs that apply to files in this scope. Do NOT copy full L0/L1/L2 content.
+   - **Section 3 — Key TRAPS & RULES**: extract only relevant TRAPS/RULES from the loaded Prizm docs that apply to files in this scope. Do NOT copy complete documentation files.
    - **Section 4 — File Manifest**: For each file relevant to this feature, list: file path, why it's needed (modify/reference/test), key interface signatures (function names + params + return types). Do NOT include full file content — agents read files on-demand. Format:
      ### Files to Modify
      | File | Why Needed | Key Interfaces |
@@ -151,7 +151,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
      | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
-     - <trap entries extracted from L1/L2 docs>
+     - <trap entries extracted from the loaded Prizm docs>
 4. Confirm: `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 **After Step A**: Use context-snapshot.md Section 4 File Manifest to guide targeted file reads. Do NOT scan directories or read unrelated files.
@@ -237,7 +237,7 @@ For each Verification Gate from the Task Contract, write one evidence line to Im
 
 Review the completed implementation before the full Feature test gate. Run `/prizmkit-code-review artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and follow the skill's current review contract for review execution, repairs, verification, evidence, and handoff. Do not invoke another review skill or add a second review path outside that contract.
 
-- `REVIEW_PASS` → record `stage=code-review`, `status=REVIEW_PASS`, `stage_result=PASS`, `next_stage=prizmkit-test`, and `resume_from=prizmkit-test`; then run the test gate.
+- `REVIEW_PASS` → record `stage=code-review`, `status=completed`, `stage_result=REVIEW_PASS`, `next_stage=prizmkit-test`, and `resume_from=prizmkit-test`; then run the test gate.
 - `REVIEW_NEEDS_FIXES` → increment the shared outer `repair_round` and route `prizmkit-implement` → `prizmkit-code-review` → `prizmkit-test`.
 - Stop as `WORKFLOW_BLOCKED` when the outer repair round is already three. The Main-Agent review loop has its separate limit of up to ten completed rounds.
 
@@ -252,26 +252,15 @@ Only `REVIEW_PASS` can proceed to the structured Feature test gate. `REVIEW_INCO
 
 ### Scoped Feature Test Gate — PrizmKit Test
 
-Create the current-run marker, then invoke the Feature gate:
-
-```bash
-{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
-{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
-```
+Invoke the Feature test gate:
 
 ```text
 /prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/
 ```
 
-The Markdown `test-report.md` is a derived view only. Locate its package through `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt` and consume authoritative `.prizmkit/test/evidence/<evidence-id>/manifest.json`, `verdict.json`, and `validation.json`. Before accepting `TEST_PASS`, verify evidence identity/scope, every manifest file hash, final-verdict agreement, validator result and payload hash, current inventory target hashes, and the compatibility value `legacy-test-report-interface-not-supported`. Never accept a Markdown-only PASS.
-
-Repair routes:
-- `TEST_FAIL` with `repair_scope=test-infrastructure` → implement → test, without speculative production edits.
-- `TEST_FAIL` with production/runtime/schema/dependency/public-interface scope → implement → code-review → test.
-- Unknown unsafe scope → `WORKFLOW_BLOCKED`; do not guess a production edit.
-- `TEST_BLOCKED` → preserve evidence/artifacts, perform bounded environment recovery, then resume from test or finish terminal `WORKFLOW_BLOCKED`; never edit production speculatively.
+Consume `.prizmkit/specs/{{FEATURE_SLUG}}/test-report.md` and `test-result.json`. They must agree. `TEST_PASS` completes the gate; `TEST_NEEDS_FIXES` preserves a known correction or delta-review requirement and stops truthfully; `TEST_BLOCKED` preserves the blocker and becomes `WORKFLOW_BLOCKED`. Do not require an evidence package, manifest, hashes, attestation, or test-internal checkpoint, and do not reinterpret a testing result as an AI CLI crash.
 
-Record `stage`, `status`, `stage_result`, `repair_scope`, `repair_round`, structured evidence paths, `next_stage`, and `resume_from` in truthful recovery metadata. Keep L1 workflow state separate from L4 `workflow-checkpoint.json`. The outer repair round stops after three and is independent of the internal review loop.
+Record only caller-owned `stage`, `status`, `stage_result`, `repair_scope`, `repair_round`, `next_stage`, and `resume_from` in recovery metadata. Keep testing reports/results separate from `workflow-checkpoint.json`. The skill owns its internal ten-round Main-Agent review, five-response optional independent review, and three-round execution-failure repair budgets.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification — MANDATORY
@@ -448,7 +437,7 @@ git log --oneline
 **6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizmkit/prizm-docs/` architecture index):
 - **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
 - **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizmkit/prizm-docs/`
-- **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
+- **Detail-doc coverage check**: For any module/sub-module with source files created or significantly modified in this session but no detail `.prizm` doc — evaluate whether one is warranted and create it when needed. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
 - Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -104,7 +104,7 @@ Use this protocol only when the bug is UI/frontend-reproducible. Evidence must c
 
 **Step 1 — Diagnose the bug**:
 
-1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules
+1. Read `.prizmkit/prizm-docs/root.prizm` and the relevant module indexes and detail docs for affected modules
 2. Trace the bug:
    - Classify error type (Runtime / Network / Auth / Data / Logic / Config / External)
    - Check `.prizmkit/prizm-docs/` TRAPS sections for matching known issues
@@ -203,18 +203,18 @@ Handle `REVIEW_PASS` and `REVIEW_NEEDS_FIXES` according to task policy. `REVIEW_
 
 ### Phase 4: Post-Review Test Gate — PrizmKit Test
 
-After a valid code-review PASS, run the mandatory authoritative test gate against the same artifact root:
+After a valid code-review PASS, run the mandatory test gate against the same artifact root:
 
 ```text
 /prizmkit-test scope=this-change artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/
 ```
 
-Read the current structured `manifest.json`, `verdict.json`, and `validation.json`; Markdown alone is never completion authority. `TEST_FAIL` with `test-infrastructure` returns through implementation directly to test. Production/runtime/schema/dependency/public-interface fixes return through implementation, fresh review, and test. Unknown scope is blocked. `TEST_BLOCKED` permits bounded automatic environment recovery at the test stage or terminal `WORKFLOW_BLOCKED`, never speculative production edits. The shared outer repair cap is three.
+Read the sibling `test-report.md` and `test-result.json`; they must agree. `TEST_PASS` proceeds to retrospective and commit. `TEST_NEEDS_FIXES` preserves the known correction or delta-review requirement and stops truthfully. `TEST_BLOCKED` preserves its blocker and records `WORKFLOW_BLOCKED`. Do not require a manifest/attestation package, reinterpret the testing result as a runtime crash, or recreate the skill's internal loops.
 
-Only validated `TEST_PASS` may proceed to commit.
+Only `TEST_PASS` may proceed to commit.
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
-**MANUAL/HYBRID AUTOMATION**: This L4 session is always headless. Execute manual/hybrid verification with available deterministic browser, CLI/API, fixture, or test tooling. Document the method and evidence, then continue through `/prizmkit-retrospective` and `/prizmkit-committer`; never ask for UAT, wait for a user, or stop as `partial`.
+**MANUAL/HYBRID AUTOMATION**: This pipeline session is always headless. Execute manual/hybrid verification with available deterministic browser, CLI/API, fixture, or test tooling. Document the method and verification basis, then continue through `/prizmkit-retrospective` and `/prizmkit-committer`; never ask for UAT, wait for a user, or stop as `partial`.
 - Do not write `verifying` to the external bug-list status field; fine-grained verification is session/checkpoint metadata, while the external list status remains one of `pending`, `in_progress`, `completed`, `failed`, `skipped`, or `needs_info`.
 {{END_IF_VERIFICATION_MANUAL_OR_HYBRID}}
 
@@ -224,7 +224,7 @@ Only validated `TEST_PASS` may proceed to commit.
 
 ### Headless Commit Authorization
 
-This pipeline launch authorizes one local task commit only after review and authoritative test evidence pass. Never ask a question, wait for input, or request confirmation. Invoke `/prizmkit-committer` with `mode=l4-headless`, `owner=prizmkit-l4`, and `local_commit_authorized=true`. The runtime controls any optional remote publication after the local commit; do not make a publication decision in this session.
+This pipeline launch authorizes one local task commit only after Code Review and a consistent `TEST_PASS` report/result pair. Never ask a question, wait for input, or request confirmation. Invoke `/prizmkit-committer` with `mode=l4-headless`, `owner=prizmkit-l4`, and `local_commit_authorized=true`. The runtime controls any optional remote publication after the local commit; do not make a publication decision in this session.
 
 **Bug Fix Documentation Policy**:
 - **DEFAULT**: Run `/prizmkit-retrospective` with structural sync only (Job 1). Skip knowledge injection.

package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md

@@ -159,15 +159,15 @@ Handle `REVIEW_PASS` and `REVIEW_NEEDS_FIXES` according to behavior-preservation
 
 ### Phase 5: Post-Review Test Gate — PrizmKit Test
 
-After a valid code-review PASS, run the mandatory authoritative test gate against the same artifact root:
+After a valid code-review PASS, run the mandatory test gate against the same artifact root:
 
 ```text
 /prizmkit-test scope=this-change artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/
 ```
 
-Behavior-preservation checks remain supporting evidence and never replace current structured `manifest.json`, `verdict.json`, and `validation.json`. `TEST_FAIL` with `test-infrastructure` returns through implementation directly to test. Production/runtime/schema/dependency/public-interface fixes return through implementation, fresh review, and test. Unknown scope is blocked. `TEST_BLOCKED` permits bounded automatic environment recovery at the test stage or terminal `WORKFLOW_BLOCKED`, never speculative production edits. The shared outer repair cap is three.
+Behavior-preservation context remains supporting input. Read the sibling `test-report.md` and `test-result.json`; they must agree. `TEST_PASS` proceeds to browser verification or retrospective. `TEST_NEEDS_FIXES` preserves the known correction or delta-review requirement and stops truthfully. `TEST_BLOCKED` preserves its blocker and records `WORKFLOW_BLOCKED`. Do not require a manifest/attestation package, reinterpret the testing result as a runtime crash, or recreate the skill's internal loops.
 
-Only validated `TEST_PASS` may proceed to browser verification or commit.
+Only `TEST_PASS` may proceed to browser verification or commit.
 
 ---
 
@@ -187,7 +187,7 @@ Record tool choice, URL, steps, screenshot path if available, result, and cleanu
 
 ### Headless Commit Authorization
 
-This pipeline launch authorizes one local task commit only after review, authoritative test evidence, and required behavior-preservation gates pass. Never ask a question, wait for input, or request confirmation. Invoke `/prizmkit-committer` with `mode=l4-headless`, `owner=prizmkit-l4`, and `local_commit_authorized=true`. The runtime controls any optional remote publication after the local commit; do not make a publication decision in this session.
+This pipeline launch authorizes one local task commit only after Code Review, a consistent `TEST_PASS` report/result pair, and required behavior-preservation gates pass. Never ask a question, wait for input, or request confirmation. Invoke `/prizmkit-committer` with `mode=l4-headless`, `owner=prizmkit-l4`, and `local_commit_authorized=true`. The runtime controls any optional remote publication after the local commit; do not make a publication decision in this session.
 
 Run `/prizmkit-retrospective` using the current working tree and staged changes as input context. Do not rely only on `git diff --cached`.
 
@@ -266,7 +266,7 @@ Before exiting, write `{{SESSION_STATUS_PATH}}`:
 
 ## Reminders
 
-- Use L1 skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-retrospective`, `/prizmkit-committer`.
+- Use the atomic skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-retrospective`, `/prizmkit-committer`.
 - Follow the active skills and runtime contracts; they determine execution topology, review ownership, and delegation boundaries
 - On execution-unit timeout, preserve the active checkout and artifacts and follow the owning contract's recovery or downgrade path
 - Behavior preservation is the first priority.