prizmkit 1.1.100 → 1.1.102

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -84,6 +84,11 @@ def parse_args():
         required=True,
         help="Output path for the rendered prompt",
     )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help="AI-visible project root used for rendered prompt paths",
+    )
     parser.add_argument(
         "--template",
         default=None,
@@ -479,6 +484,14 @@ def resolve_project_root(script_dir):
     return os.path.abspath(pipeline_parent)
 
 
+def _args_project_root(args, script_dir):
+    """Return explicit AI-visible project root or script-layout default."""
+    explicit = getattr(args, "project_root", None)
+    if explicit:
+        return os.path.abspath(explicit)
+    return resolve_project_root(script_dir)
+
+
 def process_conditional_blocks(content, resume_phase):
     """Handle conditional blocks based on resume_phase.
 
@@ -663,7 +676,7 @@ def determine_pipeline_mode(complexity):
 SECTION_TO_SKILL = {
     "phase0-init": ("prizmkit-init", "Project Bootstrap",
                     [".prizmkit/prizm-docs/root.prizm", ".prizmkit/config.json"]),
-    "phase0-test-baseline": ("test-baseline", "Test Baseline", []),
+    "phase0-test-baseline": ("test-baseline", "Detect Test Commands", []),
     "phase-context-snapshot": ("context-snapshot", "Build Context Snapshot",
                                [".prizmkit/specs/{slug}/context-snapshot.md"]),
     "phase-specify-plan": ("context-snapshot-and-plan", "Specify & Plan",
@@ -1324,10 +1337,12 @@ def _tier_header(pipeline_mode):
             "No normal work subagents. No TeamCreate.\n",
         ),
         "standard": (
-            "# Dev-Pipeline Session Bootstrap — Tier 2 (Dual Agent)\n",
-            "**Tier 2 — Dual Agent**: You handle context + planning "
-            "directly. Then spawn Dev and Reviewer subagents. Spawn Dev "
-            "and Reviewer agents via the Agent tool.\n",
+            "# Dev-Pipeline Session Bootstrap — Tier 2 "
+            "(Orchestrator + Critic/Reviewer)\n",
+            "**Tier 2 — Orchestrator + Critic/Reviewer**: You handle "
+            "context + planning + implementation directly. Critic challenges "
+            "plan (if enabled), Reviewer reviews. No Dev subagent — "
+            "orchestrator implements directly (P0-6).\n",
         ),
         "full": (
             "# Dev-Pipeline Session Bootstrap — Tier 3 (Full Team)\n",
@@ -1363,16 +1378,14 @@ def _tier_reminders(pipeline_mode, critic_enabled=False):
         ]
     elif pipeline_mode == "standard":
         specific = [
-            "- Tier 2: orchestrator builds context+plan, Analyzer checks "
-            "consistency, Dev implements, Reviewer reviews+tests — use "
-            "direct Agent spawn for agents",
+            "- Tier 2: orchestrator builds context+plan, Critic challenges "
+            "plan (if enabled), orchestrator implements directly (no Dev "
+            "subagent), Reviewer reviews — see P0-6",
             "- context-snapshot.md is append-only: orchestrator writes "
-            "Sections 1-4, Dev appends Implementation Log, Reviewer "
-            "appends Review Notes",
-            "- Gate checks enforce Implementation Log and Review Notes are "
-            "written before proceeding",
-            "- Do NOT use `run_in_background=true` when spawning normal work "
-            "subagents",
+            "Sections 1-4 + Implementation Log, Reviewer appends Review Notes",
+            "- Gate checks enforce Implementation Log (with Gate Evidence) "
+            "and Review Notes are written before proceeding",
+            "- Do NOT use `run_in_background=true` when spawning Reviewer",
             "- On timeout: check snapshot + git diff HEAD → model:lite → "
             "remaining steps only → max 2 retries per phase → "
             "orchestrator fallback",
@@ -1546,6 +1559,18 @@ def assemble_sections(pipeline_mode, sections_dir, init_done, is_resume,
                           load_section(sections_dir,
                                        "phase-implement-agent.md")))
 
+    # Verification Gates are included in Task Contract. Keep AC in one place so
+    # background context and implementation prompts cannot redefine scope.
+    # --- Review ---
+    if pipeline_mode == "full":
+        sections.append(("phase-review",
+                          load_section(sections_dir,
+                                       "phase-review-full.md")))
+    else:
+        sections.append(("phase-review",
+                          load_section(sections_dir,
+                                       "phase-review-agent.md")))
+
     # --- Test Failure Recovery Protocol (tier-specific) ---
     if pipeline_mode == "lite":
         sections.append(("test-failure-recovery",
@@ -1561,18 +1586,6 @@ def assemble_sections(pipeline_mode, sections_dir, init_done, is_resume,
                       load_section(sections_dir,
                                    "phase-prizmkit-test.md")))
 
-    # Verification Gates are included in Task Contract. Keep AC in one place so
-    # background context and implementation prompts cannot redefine scope.
-    # --- Review (only for agent tiers) ---
-    if pipeline_mode == "full":
-        sections.append(("phase-review",
-                          load_section(sections_dir,
-                                       "phase-review-full.md")))
-    elif pipeline_mode == "standard":
-        sections.append(("phase-review",
-                          load_section(sections_dir,
-                                       "phase-review-agent.md")))
-
     # --- Browser Verification (conditional, tool-aware) ---
     if browser_enabled:
         if browser_tool == "opencli":
@@ -1697,7 +1710,7 @@ def validate_rendered(content):
 
 def build_replacements(args, feature, features, global_context, script_dir):
     """Build the full dict of placeholder -> replacement value."""
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
 
     # Resolve paths - platform-aware agent/team resolution
     platform = os.environ.get("PRIZMKIT_PLATFORM", "")
@@ -1768,13 +1781,17 @@ def build_replacements(args, feature, features, global_context, script_dir):
     validator_scripts_dir = os.path.join(project_root, ".prizmkit", "dev-pipeline", "scripts")
     init_script_path = os.path.join(validator_scripts_dir, "init-dev-team.py")
 
-    # Session status path (relative to project root)
-    session_status_path = os.path.join(
-        ".prizmkit", "state", "features", args.feature_id,
-        "sessions", args.session_id, "session-status.json",
+    # Session status is controlled by the main runner state dir, even when
+    # rendered project paths are AI-visible worktree paths.
+    state_dir = (
+        os.path.abspath(args.state_dir)
+        if args.state_dir
+        else os.path.join(project_root, ".prizmkit", "state", "features")
+    )
+    session_status_abs = os.path.join(
+        state_dir, args.feature_id, "sessions", args.session_id,
+        "session-status.json",
     )
-    # Make it absolute from project root
-    session_status_abs = os.path.join(project_root, session_status_path)
 
     # Compute feature slug for per-feature directory naming
     feature_slug = compute_feature_slug(
@@ -2147,9 +2164,7 @@ def main():
         emit_failure(err)
 
     # ── Generate checkpoint file ──────────────────────────────────────
-    project_root = resolve_project_root(
-        os.path.dirname(os.path.abspath(__file__))
-    )
+    project_root = _args_project_root(args, script_dir)
     feature_slug = replacements.get("{{FEATURE_SLUG}}", "")
     checkpoint_path = ""
     checkpoint = {}

package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py

@@ -44,6 +44,7 @@ def parse_args():
     parser.add_argument("--resume-phase", required=True, help='Phase to resume from, or "null" for fresh start')
     parser.add_argument("--state-dir", default=None, help="State directory (default: .prizmkit/state/bugfix)")
     parser.add_argument("--output", required=True, help="Output path for the rendered prompt")
+    parser.add_argument("--project-root", default=None, help="AI-visible project root used for rendered prompt paths")
     parser.add_argument("--template", default=None, help="Custom template path. Defaults to {script_dir}/../templates/bugfix-bootstrap-prompt.md")
     parser.add_argument("--mode", default=None, help="Pipeline execution mode override: lite, standard, full")
     parser.add_argument("--critic", default=None, help="Enable critic agent: true/false")
@@ -273,9 +274,17 @@ def resolve_project_root(script_dir):
     return os.path.abspath(pipeline_parent)
 
 
+def _args_project_root(args, script_dir):
+    """Return explicit AI-visible project root or script-layout default."""
+    explicit = getattr(args, "project_root", None)
+    if explicit:
+        return os.path.abspath(explicit)
+    return resolve_project_root(script_dir)
+
+
 def build_replacements(args, bug, global_context, script_dir):
     """Build the full dict of placeholder -> replacement value."""
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
 
     # Platform-aware agent/team path resolution
     platform = os.environ.get("PRIZMKIT_PLATFORM", "")
@@ -305,10 +314,16 @@ def build_replacements(args, bug, global_context, script_dir):
     dev_subagent = os.path.join(agents_dir, f"prizm-dev-team-dev{agent_ext}")
     reviewer_subagent = os.path.join(agents_dir, f"prizm-dev-team-reviewer{agent_ext}")
 
-    # Session status path
+    # Session status is controlled by the main runner state dir, even when
+    # rendered project paths are AI-visible worktree paths.
+    state_dir = (
+        os.path.abspath(args.state_dir)
+        if args.state_dir
+        else os.path.join(project_root, ".prizmkit", "state", "bugfix")
+    )
     session_status_path = os.path.join(
-        project_root, ".prizmkit", "state", "bugfix", args.bug_id,
-        "sessions", args.session_id, "session-status.json"
+        state_dir, args.bug_id, "sessions", args.session_id,
+        "session-status.json",
     )
 
     # Error source
@@ -662,7 +677,7 @@ def main():
         emit_failure(err)
 
     # Generate checkpoint file
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
     checkpoint_path = os.path.join(project_root, checkpoint_rel)
     checkpoint_dir = os.path.dirname(checkpoint_path)
     os.makedirs(checkpoint_dir, exist_ok=True)

package/bundled/dev-pipeline/scripts/generate-recovery-prompt.py

@@ -153,7 +153,7 @@ Invoke `/feature-pipeline-launcher` skill:
 
 If `/feature-pipeline-launcher` is not available, run the pipeline directly:
 ```bash
-./.prizmkit/dev-pipeline/run-feature.sh run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
 ```""",
     ),
     4: (
@@ -196,7 +196,7 @@ Invoke `/refactor-pipeline-launcher` skill:
 
 If `/refactor-pipeline-launcher` is not available, run the pipeline directly:
 ```bash
-./.prizmkit/dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
 ```""",
     ),
     4: (

package/bundled/dev-pipeline/scripts/parse-stream-progress.py

@@ -175,6 +175,7 @@ class ProgressTracker:
     def __init__(self, session_log=None):
         self.session_log_path = Path(session_log).expanduser() if session_log else None
         self.message_count = 0
+        self.event_type_counts = Counter()
         self.current_tool = None
         self.current_tool_input_summary = ""
         self.current_phase = None
@@ -196,6 +197,10 @@ class ProgressTracker:
         self._subagent_spawn_count = 0
         self.codex_child_thread_ids = set()
         self.cb_session_id = ""
+        self.result_subtype = ""
+        self.stop_reason = ""
+        self.has_usage = False
+        self.permission_denials = []
         self.cb_cwd = ""
         self.claude_session_id = ""
         self.claude_cwd = ""
@@ -227,7 +232,10 @@ class ProgressTracker:
            with sessionId/cwd metadata, function_call for tool invocations).
         """
         event_type = event.get("type", "")
+        if event_type:
+            self.event_type_counts[str(event_type)] += 1
         self._detect_structured_terminal_fields(event)
+        self._record_usage_and_permission_metadata(event)
 
         # ── Codex exec --json JSONL format ──────────────────────────
         if event_type in (
@@ -529,6 +537,8 @@ class ProgressTracker:
                     self._update_claude_subagent_status_counts()
 
         elif event_type == "result":
+            self.result_subtype = str(event.get("subtype") or event.get("result_subtype") or "")
+            self.stop_reason = str(event.get("stop_reason") or "")
             self.event_format = self.event_format or "stream-json"
             self.is_active = False
             result_text = event.get("result") or event.get("message") or ""
@@ -638,6 +648,27 @@ class ProgressTracker:
             pass
 
 
+    def _record_usage_and_permission_metadata(self, event):
+        """Record additive metadata required by Python runtime parity tests."""
+        if not isinstance(event, dict):
+            return
+        if event.get("usage") not in (None, "", {}):
+            self.has_usage = True
+        denial_text = json.dumps(event, ensure_ascii=False).lower()
+        if any(
+            marker in denial_text
+            for marker in (
+                "permission denied",
+                "permission_denied",
+                "permission denial",
+                "denied by user",
+                "user denied",
+                "not permitted",
+            )
+        ):
+            self.permission_denials.append(json.dumps(event, ensure_ascii=False)[:500])
+            self.permission_denials = self.permission_denials[-10:]
+
     def _detect_structured_terminal_fields(self, event):
         """Detect provider-neutral terminal/context errors before format routing."""
         if not isinstance(event, dict):
@@ -1201,6 +1232,13 @@ class ProgressTracker:
         return {
             "updated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
             "event_format": self.event_format,
+            "event_type_counts": dict(self.event_type_counts),
+            "claude_session_id": self.claude_session_id,
+            "result_subtype": self.result_subtype,
+            "stop_reason": self.stop_reason,
+            "has_usage": self.has_usage,
+            "permission_denial_count": len(self.permission_denials),
+            "permission_denials": self.permission_denials[-10:],
             "message_count": self.message_count,
             "current_tool": self.current_tool,
             "current_tool_input_summary": self.current_tool_input_summary,
@@ -1257,6 +1295,7 @@ def tail_and_parse(session_log, progress_file, poll_interval=0.5):
     def state_key(state):
         return (
             state["message_count"],
+            tuple(sorted(state.get("event_type_counts", {}).items())),
             state["current_tool"],
             state["current_phase"],
             state["total_tool_calls"],

package/bundled/dev-pipeline/templates/agent-prompts/dev-implement.md

@@ -1,4 +1,10 @@
-"Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+"<!-- DEPRECATED (P0-6): This prompt was injected into a Dev subagent spawn.
+The orchestrator now implements directly (see phase-implement-agent.md / phase-implement-full.md).
+This file is retained only so load_agent_prompts() does not break; it is no longer referenced
+by any phase section. Do not add new rules here — add them to the phase-implement-* sections instead.
+The rules below are the legacy Dev-subagent version, kept for reference only. -->
+
+Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
 
 ## Task Summary Card
 
@@ -55,7 +61,7 @@ Before returning, append `## Implementation Log` to `context-snapshot.md` with:
 - Do not run git commands; staging and commit are handled by the orchestrator.
 - **Edit safety**: If an Edit fails with 'String to replace not found', grep for the target text before retrying. Never guess file offsets — verify them with a Read or grep first.
 - **Read safety**: If 3 consecutive Reads to the same file return 'shorter than offset' or 'Wasted call', STOP and report BLOCKED.
-- **Test early**: Run `{{TEST_CMD}}` after every 3 successful Edit operations. Capture output to /tmp/test-out.txt and grep for failures.
+- **Test gate placement**: Do not run mandatory periodic or full-suite tests here. The scoped/full test gate runs after code review; only use tiny targeted checks when needed for local debugging.
 
 Do not return success unless:
 1. implementation tasks are complete;

package/bundled/dev-pipeline/templates/agent-prompts/reviewer-review.md

@@ -2,6 +2,6 @@
 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` (if it exists) for goals and Verification Gates; if spec.md does not exist, read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` Section 1 Task Contract instead
 2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
 3. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/. The skill will run its internal review-fix loop (Reviewer → filter → Dev fix, max 3 rounds) and write review-report.md.
-4. Run the full test suite using `{{TEST_CMD}}`. When running tests: `({{TEST_CMD}}) 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep `/tmp/review-test-out.txt` for details — do NOT re-run the suite multiple times.
+4. Do not run test suites here. The orchestrator runs `/prizmkit-test` after review completes and then fixes code/tests until the scoped gate passes.
 5. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
 Report: verdict (PASS/NEEDS_FIXES), number of rounds, findings fixed/rejected."

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

@@ -30,9 +30,9 @@ Infer what needs to be done from the feature context above and follow the standa
 
 3. **Implement**: Run `/prizmkit-implement` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to execute the plan using TDD (write tests first, then implement).
 
-4. **Test**: Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate and verify tests only for this feature's changed scope. Do not use bugfix/refactor artifact directories for this gate.
+4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to review and auto-fix changes against the spec (internal review-fix loop, max 3 rounds).
 
-5. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to review and auto-fix changes against the spec (internal review-fix loop, max 3 rounds).
+5. **Test**: Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate and verify tests only for this feature's changed scope after review. Do not use bugfix/refactor artifact directories for this gate.
 
 6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` with code changes.
 
@@ -44,3 +44,7 @@ Infer what needs to be done from the feature context above and follow the standa
 - Do NOT push to remote — the user will push manually.
 - Write all artifacts to `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 - If a step fails after 3 attempts, write a status report and stop.
+- **Anti re-read**: once you read a file into context, do NOT read it again — use `grep -n`/`sed -n` for specific lines. 3 full Reads of same file → report BLOCKED.
+- **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.
+- **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.

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

@@ -51,6 +51,11 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-3. All changes are committed once at the end in Phase 4 via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `($TEST_CMD) 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
+8. **Scaffold / generated file awareness** — Files created by scaffolding tools (`npm init`, `npx create-*`, etc.) are boilerplate. Tag them, record in context-snapshot.md, and NEVER re-read them. If you need to modify one, edit directly without reading first.
+9. **Package version verification (BLOCKING)** — Before writing ANY dependency version, verify it exists via registry query (`npm view <pkg> dist-tags.latest`, `pip index versions <pkg>`, etc.). NEVER guess version numbers.
+10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`. Never commit binaries/build output.
+11. **Anti re-read hard rule (BLOCKING)** — Once you have read a file into context, do NOT read the full file again. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for specific lines. **20-step window**: full Read forbidden within 20 tool calls of last read. **3-strike**: 3 full Reads of same file → report BLOCKED. Applies to orchestrator AND subagents.
+12. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
 
 ---
 
@@ -140,18 +145,19 @@ You know this project's tech stack. Identify ALL test commands that apply (e.g.,
 **3b.** Run `/prizmkit-implement` — this handles the full implementation cycle:
 - Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
 - Reads context from `context-snapshot.md` (Prizm docs, TRAPS, file manifest)
-- Implements task-by-task with TDD, marking each `[x]` immediately
+- Implements task-by-task, marking each `[x]` immediately
 - Creates/updates L2 `.prizm` docs when creating new modules or significantly modifying existing ones — AI selectively decides which modules warrant L2 based on complexity and importance
-- Runs tests using `TEST_CMD` after each task
+- Defers scoped/full test execution until after review
 - Writes '## Implementation Log' to `context-snapshot.md`
 
 **3b-checkpoint.** Context management — if plan.md has more than 5 tasks, update durable checkpoints/artifacts after every 3 tasks, minimize output, and continue. If context overflow occurs in a headless run, the runner starts a fresh continuation session from those checkpoints and artifacts. In an interactive Claude Code session operated manually outside the headless pipeline, `/compact` may be used as an optional convenience only.
 
 **3c.** After implement completes, verify:
 1. All tasks in plan.md are `[x]`
-2. Run the full test suite to ensure nothing is broken
-3. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
-4. If any criterion is not met, fix it now using the convergence-based recovery loop below
+2. **Verification Gate Self-Check**: for each acceptance criterion, write one line of evidence (test name / file:line / fixture path). Any gate without evidence is BLOCKED, not success.
+3. **Layered test strategy**: do not run mandatory periodic/full-suite tests during implementation. Use only tiny targeted checks when needed for local debugging; the scoped feature test gate runs after review.
+4. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
+5. If any criterion is not met, fix it now using the convergence-based recovery loop below
 
 **CP-2**: All acceptance criteria met, all tests pass.
 
@@ -165,10 +171,12 @@ When tests fail, use convergence recovery — keep fixing while progress is bein
 
 **Key rule**: If failures decrease (even by 1), plateau counter resets. Do NOT block commit for unresolved failures — document and defer to next session.
 
+**Hard Round Cap (BLOCKING)**: After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: read full relevant source section ONCE (via `grep -n`+`sed -n`, never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
+
 
 ### Scoped Feature Test Gate — PrizmKit Test
 
-Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after implementation and before review/commit.
+Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
 Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
 

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

@@ -57,6 +57,11 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `($TEST_CMD) 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
+8. **Scaffold / generated file awareness** — Files created by scaffolding tools are boilerplate. Tag them, record in context-snapshot.md, NEVER re-read. Edit directly without reading first.
+9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
+10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
+11. **Anti re-read hard rule (BLOCKING)** — Once you have read a file into context, do NOT read the full file again. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for specific lines. **20-step window**: full Read forbidden within 20 tool calls of last read. **3-strike**: 3 full Reads of same file → report BLOCKED. Applies to orchestrator AND subagents — subagents re-reading files in context-snapshot.md Section 4 are wasting context.
+12. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
 
 ---
 
@@ -277,9 +282,14 @@ Prompt:
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
 > 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
 > 3. If plan.md has more than 5 tasks: update durable checkpoints/artifacts after every 3 tasks, minimize output, and rely on runner continuation if context overflow occurs. In an interactive Claude Code session operated manually outside the headless pipeline, `/compact` may be used as an optional convenience only.
-> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
-> 5. Do NOT execute any git commands (no git add/commit/reset/push).
-> Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
+> 4. **Verification Gate Self-Check (BLOCKING)**: before returning, write a `### Gate Evidence` section to Implementation Log — one evidence line per gate (test name / file:line / fixture path). Any gate without evidence is BLOCKED, not success.
+> 5. **Layered test strategy**: debug with single-file tests (`npx vitest run <file> -t '<name>'`), only run full suite as gate when single-file is green. Never run full suite while a single-file test is still red.
+> 6. **Anti re-read**: 20-step window (full Read forbidden within 20 tool calls of last read), 3-strike (3 full Reads same file → BLOCKED). Use `grep -n`+`sed -n` for specific lines.
+> 7. **Read offset safety**: if Read returns "shorter than offset"/"empty"/"wasted" — run `wc -l` then `sed -n`, do NOT retry same offset. 2 consecutive → STOP Reading that file.
+> 8. **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Write failure-log. Switch to read-once-then-rewrite strategy. Do NOT exceed 7 rounds.
+> 9. After implement completes, verify the '## Implementation Log' section (with Gate Evidence) was written to context-snapshot.md.
+> 10. Do NOT execute any git commands (no git add/commit/reset/push).
+> Do NOT exit until all tasks are [x] and the '## Implementation Log' section (with Gate Evidence) is written in context-snapshot.md."
 
 Wait for Dev to return. All tasks must be `[x]`, tests pass.
 
@@ -292,7 +302,7 @@ If GATE:MISSING — send message to Dev (re-spawn if needed): "Write the '## Imp
 
 ### Scoped Feature Test Gate — PrizmKit Test
 
-Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after implementation and before review/commit.
+Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
 Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
 

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

@@ -57,6 +57,11 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Batch independent operations** — Issue multiple independent `Write`/`Read` calls in a single message turn when they have no dependencies. Combine multiple `mkdir -p` into one command. Never run `npm test` twice just to apply a different grep filter — capture output to `/tmp/test-out.txt` once and grep the file.
+8. **Scaffold / generated file awareness** — Files created by scaffolding tools are boilerplate. Tag them, record in context-snapshot.md, NEVER re-read. Edit directly without reading first.
+9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
+10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
+11. **Anti re-read hard rule (BLOCKING)** — Once you have read a file into context, do NOT read the full file again. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for specific lines. **20-step window**: full Read forbidden within 20 tool calls of last read. **3-strike**: 3 full Reads of same file → report BLOCKED. Applies to orchestrator AND subagents.
+12. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
 
 ---
 
@@ -285,9 +290,14 @@ Prompt:
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
 > 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
 > 3. If plan.md has more than 5 tasks: update durable checkpoints/artifacts after every 3 tasks, minimize output, and rely on runner continuation if context overflow occurs. In an interactive Claude Code session operated manually outside the headless pipeline, `/compact` may be used as an optional convenience only.
-> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
-> 5. Do NOT execute any git commands (no git add/commit/reset/push).
-> Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
+> 4. **Verification Gate Self-Check (BLOCKING)**: before returning, write a `### Gate Evidence` section to Implementation Log — one evidence line per gate (test name / file:line / fixture path). Any gate without evidence is BLOCKED, not success.
+> 5. **Layered test strategy**: debug with single-file tests (`npx vitest run <file> -t '<name>'`), only run full suite as gate when single-file is green. Never run full suite while a single-file test is still red.
+> 6. **Anti re-read**: 20-step window (full Read forbidden within 20 tool calls of last read), 3-strike (3 full Reads same file → BLOCKED). Use `grep -n`+`sed -n` for specific lines.
+> 7. **Read offset safety**: if Read returns "shorter than offset"/"empty"/"wasted" — run `wc -l` then `sed -n`, do NOT retry same offset. 2 consecutive → STOP Reading that file.
+> 8. **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Write failure-log. Switch to read-once-then-rewrite strategy. Do NOT exceed 7 rounds.
+> 9. After implement completes, verify the '## Implementation Log' section (with Gate Evidence) was written to context-snapshot.md.
+> 10. Do NOT execute any git commands (no git add/commit/reset/push).
+> Do NOT exit until all tasks are [x] and the '## Implementation Log' section (with Gate Evidence) is written in context-snapshot.md."
 
 **Gate Check — Implementation Log**:
 After Dev agent returns, verify the Implementation Log was written:
@@ -310,7 +320,7 @@ All tasks `[x]`, tests pass.
 
 ### Scoped Feature Test Gate — PrizmKit Test
 
-Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after implementation and before review/commit.
+Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
 Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
 

package/bundled/dev-pipeline/templates/sections/context-budget-rules.md

@@ -32,3 +32,5 @@ You are running in **headless non-interactive mode** with a FINITE context windo
    - **This is a BLOCKING gate**: do NOT run `npm install` / `pip install` / `cargo build` / `go mod tidy` until ALL versions in the manifest have been verified or use open constraints
    - Batch version lookups: query multiple packages in parallel to save time (e.g., run multiple `npm view` commands concurrently)
 10. **Build artifact hygiene** — After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary, build directory, generated bundle, or cache directory is ignored by git before the commit phase. Never commit compiled binaries, build output, or generated artifacts.
+11. **Anti re-read hard rule (BLOCKING)** — Re-reading the same file is the #1 context burner in long sessions. Once you have read a file into context (directly or via context-snapshot.md Section 4), do NOT read the full file again. Instead use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for specific lines. **20-step window**: full Read forbidden within 20 tool calls of last read. **3-strike**: 3 full Reads of same file → report BLOCKED. Never full-file Read a file already summarized in context-snapshot.md Section 4.
+12. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.

package/bundled/dev-pipeline/templates/sections/log-size-awareness.md

@@ -1,41 +1,20 @@
 ## Session Log Budget Awareness (CHECKPOINT GUIDANCE)
 
-Your session log grows with every tool call and agent interaction. Use this
-section as passive checkpoint guidance only; do not spawn a background helper for
-log-size checks.
+This section provides passive checkpoint guidance for checkpoint/continuation only. Context-saving rules (anti re-read, output filtering) live in Context Budget Rules above — do not duplicate.
 
 ### Checkpoint Before Large Work Batches
 
-- `MAX_LOG_SIZE` controls whether this advisory section is included. It is not a
-  runtime recovery mechanism.
-- Before major phases or large task batches, update durable artifacts that a
-  continuation session can trust: plan/task checkboxes, context snapshots,
-  implementation or review notes, workflow checkpoints, session status, and test
-  reports where applicable.
-- Keep command output small. Capture large outputs to temporary files and read
-  only filtered summaries needed for the current decision.
-- Prefer already-built context snapshots and manifests over broad source-file
-  re-reads.
+- `MAX_LOG_SIZE` controls whether this advisory section is included.
+- Before major phases or large task batches, update durable artifacts: plan/task checkboxes, context snapshots, implementation/review notes, workflow checkpoints, session status, test reports.
+- Checkpoint often so automatic continuation can resume from durable state.
 
 ### Headless Recovery Source of Truth
 
-- Headless recovery must rely on durable checkpoints and artifacts, not an
-  interactive slash command.
-- If context overflow still occurs, the runner detects the overflow and starts a
-  fresh continuation session from checkpoint files and durable artifacts.
-- Durable checkpoint files and artifacts are the source of truth for what was
-  completed, what remains, and the tests or review gates already run.
+- Headless recovery must rely on durable checkpoints and artifacts, not interactive slash commands.
+- If context overflow occurs, the runner detects it and starts a fresh continuation session from checkpoint files and durable artifacts.
+- Durable checkpoint files are the source of truth for what was completed, what remains, and which gates were already run.
 
 ### Interactive Claude Code Note
 
-- `/compact` may help when a human is manually operating an interactive Claude
-  Code session.
-- `/compact` is optional interactive convenience only. It must not be required
-  for headless recovery and must not be delegated to a background helper.
-
-### Log Growth Reduction Tips
-
-- Reuse context-snapshot.md instead of re-reading files already summarized there.
-- Filter command output before loading it into context.
-- Keep agent prompts focused and avoid unnecessary transcript expansion.
-- Checkpoint often so automatic continuation can resume from durable state.
+- `/compact` may help when a human is manually operating an interactive Claude Code session.
+- `/compact` is optional interactive convenience only — not required for headless recovery.

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-agent-suffix.md

@@ -1,14 +1,22 @@
    - **Section 3 — Key TRAPS & RULES**: extract only relevant TRAPS/RULES from prizm-docs. Do NOT copy full L0/L1/L2 content — the orchestrator already loaded them.
-   - **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:
+   - **Section 4 — File Manifest**: For each file, list: path, why needed, and a **key-content summary** so you do NOT need to re-read the file. Format depends on file type:
+     - **Code files** (JS/TS/Python/Go): function signatures. Example: `config` (Zod object), `loadConfig(path)→Config`.
+     - **Shell scripts** (`.sh`): command-line args, key behavior branches, sourced libs, critical line ranges. Example: `args: --feature-id; sources lib/common.sh; lines 120-180 worktree logic`.
+     - **Config/manifest** (`package.json`, `tsconfig.json`, `.env`): key scripts/fields/deps/env vars. Example: `scripts:{dev,test}, deps:{vitest}, env:USE_WORKTREE`.
+     - **Docs/README**: section headings + 2-3 relevant sections only.
+     - **Test files**: test names + what each tests (1 line each).
+     Format:
      ### Files to Modify
-     | File | Why Needed | Key Interfaces |
-     |------|-----------|----------------|
-     | `<source-dir>/config.js` | Add runtime config layer | `config` (Zod object), `configSchema` |
+     | File | Why Needed | Key Content Summary |
+     |------|-----------|---------------------|
+     | `<src>/config.js` | Add config layer | `config`, `configSchema`, `loadConfig(p)→Config` |
+     | `dev-pipeline/run-feature.sh` | Remove shell entry | args:--feature-id; lines 120-180 worktree |
 
      ### Files for Reference
-     | File | Why Needed | Key Interfaces |
-     |------|-----------|----------------|
-     | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
+     | File | Why Needed | Key Content Summary |
+     |------|-----------|---------------------|
+     | `<src>/permission-guard.js` | Perm check | `checkPermission(uid,cmd)→bool` |
+     | `package.json` | Test cmd+deps | scripts:{test:vitest}, deps:{vitest} |
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>