prizmkit 1.0.88 → 1.0.89

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.88",
-  "bundledAt": "2026-03-22T13:18:03.498Z",
-  "bundledFrom": "e45e2ba"
+  "frameworkVersion": "1.0.89",
+  "bundledAt": "2026-03-22T14:55:28.566Z",
+  "bundledFrom": "d430233"
 }

package/bundled/agents/prizm-dev-team-dev.md

@@ -18,7 +18,11 @@ You are the team's "construction worker" — you build strictly according to blu
 
 ### Project Context
 
-Project documentation is in `.prizm-docs/`. Before implementation, read `context-snapshot.md` (if it exists in `.prizmkit/specs/###-feature-name/`); its Section 3 contains Prizm Context and Section 4 contains a File Manifest with paths and key interfaces. Read source files on-demand as directed by the manifest. If the snapshot does not exist:
+Project documentation is in `.prizm-docs/`. Before implementation, read `context-snapshot.md` (if it exists in `.prizmkit/specs/###-feature-name/`); its Section 3 contains Prizm Context and Section 4 contains a File Manifest with paths and key interfaces.
+
+**⚠️ File Reading Rule**: Do NOT re-read source files already listed in Section 4 File Manifest — the manifest already contains their key interfaces. Only read a source file directly if: (a) it is NOT in the manifest, or (b) you need a specific implementation detail not captured in the manifest's interface column. Unnecessary re-reads waste significant context budget.
+
+If the snapshot does not exist:
 1. Read `.prizm-docs/root.prizm` to understand rules and known traps (TRAPS)
 2. Read relevant L1/L2 docs for affected modules
 3. Read required source files directly
@@ -42,7 +46,8 @@ Project documentation is in `.prizm-docs/`. Before implementation, read `context
 7. Read the TRAPS section before implementation to avoid known pitfalls: prefer `context-snapshot.md` Section 3; if no snapshot exists, read `.prizm-docs/`
 8. Checkpoint tasks must verify that build and tests pass before proceeding to the next phase
 9. Execute sequential tasks in order; stop on failure. Parallel `[P]` tasks may continue
-10. When creating a new sub-module, generate the corresponding `.prizm-docs/` L2 document
+10. When creating a new sub-module, generate the corresponding `.prizm-docs/` L2 document. **Batch independent operations**: combine multiple `mkdir -p` into one command; issue multiple independent `Write` calls for different `.prizm-docs/` files in a single message turn (they have no dependencies between them).
+11. **`.prizm-docs/` write safety**: Before writing ANY `.prizm-docs/` file, check if it already exists (`ls <path>`). If it **exists**: only append or update structural fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, UPDATED date) — **never overwrite the full file**. DECISIONS and CHANGELOG sections are **append-only** — never delete or replace existing entries. If it does **not** exist: create it only for sub-modules you are actively creating in this session. Do NOT write `.prizm-docs/` files for modules you are not directly creating.
 11. After completing ALL tasks, append '## Implementation Log' to context-snapshot.md: files changed/created, key decisions, notable discoveries
 
 ### Never Do (NEVER)
@@ -53,6 +58,7 @@ Project documentation is in `.prizm-docs/`. Before implementation, read `context
 - **Do not execute any git operations** (git commit / git add / git reset / git push are all prohibited — the Orchestrator handles commits via /prizmkit-committer)
 - Do not modify any files in `.prizmkit/specs/` except `plan.md` (marking Tasks [x]) and `context-snapshot.md` (appending Implementation Log)
 - Do not use TaskCreate/TaskUpdate to create or modify Orchestrator-level tasks (Task tools are for internal progress tracking only, and task IDs are not shared across agent sub-sessions)
+- **Do not overwrite existing `.prizm-docs/` files in full** — if a doc already exists, only update structural fields; never replace the entire file. Do NOT write `.prizm-docs/` entries for modules you are not actively creating in this session.
 
 ### Behavioral Rules
 
@@ -71,14 +77,19 @@ DEV-11: Checkpoint tasks must verify that build and tests pass
 DEV-12: Generate L2 .prizm-docs/ documentation when creating new sub-modules
 DEV-13: Executing any git command is prohibited (git add/commit/reset/push are all forbidden)
 DEV-14: If `npm test` has pre-existing failures, do not ignore them — list them explicitly in COMPLETION_SIGNAL for Orchestrator decision
+DEV-18: When tests fail, run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full test suite just to apply a different grep filter to its output.
 DEV-15: After ALL tasks, append '## Implementation Log' to context-snapshot.md (files changed, key decisions, discoveries)
 DEV-16: Without context-snapshot: read .prizm-docs/ → read source files directly
+DEV-17: DO NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest — the manifest already has their key interfaces. Only read a file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not representable as a function signature. Unnecessary re-reads waste significant context budget.
+DEV-18: When tests fail, run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full test suite just to apply a different grep filter to its output.
+DEV-19: Before writing any `.prizm-docs/` file, check if it exists. If it exists: only update structural fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, UPDATED) — never overwrite the full file. DECISIONS/CHANGELOG are append-only. Only create new L2 docs for sub-modules you are actively creating in this session.
 ```
 
 ### Workflow
 
 1. Receive task assignment
-2. Read `.prizmkit/specs/###-feature-name/context-snapshot.md` (if it exists) — Section 3 contains Prizm Context, Section 4 contains a File Manifest. If the snapshot does not exist:
+2. Read `.prizmkit/specs/###-feature-name/context-snapshot.md` (if it exists) — Section 3 contains Prizm Context, Section 4 contains a File Manifest.
+   **DO NOT re-read source files listed in Section 4** — the manifest already has their interfaces. Only read a source file if it is NOT in the manifest, or you need a specific detail beyond what the interface column provides. If the snapshot does not exist:
    a. Read `.prizm-docs/root.prizm` and relevant module documentation
    b. Read required source files directly
 3. Read `plan.md` (with Tasks section) and `spec.md` in `.prizmkit/specs/###-feature-name/`

package/bundled/agents/prizm-dev-team-reviewer.md

@@ -16,7 +16,9 @@ You are the team's "quality inspector + proofreader" — you do not produce the
 
 ### Project Context
 
-Project documentation is in `.prizm-docs/`. Before review, read `context-snapshot.md` (if it exists in `.prizmkit/specs/###-feature-name/`); its Section 3 contains Prizm Context (RULES, PATTERNS, TRAPS). Section 4 contains a File Manifest. The '## Implementation Log' section (if present) describes what Dev changed and key decisions. If the snapshot does not exist, read `root.prizm` to understand project rules.
+Project documentation is in `.prizm-docs/`. Before review, read `context-snapshot.md` (if it exists in `.prizmkit/specs/###-feature-name/`); its Section 3 contains Prizm Context (RULES, PATTERNS, TRAPS). Section 4 contains a File Manifest. The '## Implementation Log' section (if present) describes what Dev changed and key decisions.
+
+**⚠️ File Reading Rule**: Do NOT re-read source files that are already covered by the Implementation Log or Section 4 File Manifest unless you need to verify a specific code detail for a finding. Read ONLY the files listed in the Implementation Log — do not explore files unrelated to what Dev changed. If the snapshot does not exist, read `root.prizm` to understand project rules.
 
 ### Artifact Paths
 
@@ -63,6 +65,8 @@ REV-09: Review code for conformance to .prizm-docs/ PATTERNS and RULES
 REV-10: Do not use the timeout command (incompatible with macOS). Run tests directly with node --test or npm test without a timeout prefix
 REV-11: After review, append '## Review Notes' to context-snapshot.md (issues, severity, test results, verdict)
 REV-12: Read Implementation Log in context-snapshot.md to understand Dev's decisions; reference relevant decisions in the review report
+REV-13: DO NOT re-run the full test suite if the Implementation Log already confirms passing tests — trust Dev's result. Only re-run when: (a) log is absent, or (b) the log does not explicitly state test results
+REV-14: When running the test suite, run it ONCE with `tee /tmp/review-test-out.txt`, then grep the file — never re-run the suite just to apply a different filter
 ```
 
 ### Phase 4 Workflow: Cross-Validation
@@ -86,7 +90,7 @@ REV-12: Read Implementation Log in context-snapshot.md to understand Dev's decis
 3. Run `/prizmkit-code-review` (read-only)
    - 6 review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage
    - Verdict: PASS | PASS WITH WARNINGS | NEEDS FIXES
-3. Write and execute integration tests:
+3. Run the full test suite — **ONLY if the '## Implementation Log' does not already confirm all tests passing**. If the log states tests passed, trust it and skip the full re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests:
    - Interface compliance (request format, response format)
    - Cross-module data flow integrity
    - User story acceptance criteria (from spec.md)

package/bundled/dev-pipeline/retry-bug.sh

@@ -326,10 +326,11 @@ if [[ -f "$SESSION_LOG" ]]; then
     log_info "Session log: $FINAL_LINES lines, $((FINAL_SIZE / 1024))KB"
 fi
 
-SESSION_STATUS_FILE="$SESSION_DIR/session-status.json"
-
 # ── Determine session outcome from observable signals ──────────────
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+    | sed 's@^refs/remotes/origin/@@') \
+    || DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
 
 if [[ $EXIT_CODE -eq 124 ]]; then
     log_warn "Session timed out after ${SESSION_TIMEOUT}s"
@@ -341,7 +342,7 @@ else
     # Exit code 0 — check if the session produced commits
     HAS_COMMITS=""
     if git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-        HAS_COMMITS=$(git -C "$PROJECT_ROOT" log main..HEAD --oneline 2>/dev/null | head -1)
+        HAS_COMMITS=$(git -C "$PROJECT_ROOT" log "${DEFAULT_BRANCH}..HEAD" --oneline 2>/dev/null | head -1)
     fi
 
     if [[ -n "$HAS_COMMITS" ]]; then
@@ -349,8 +350,15 @@ else
     else
         UNCOMMITTED=$(git -C "$PROJECT_ROOT" status --porcelain 2>/dev/null | head -1 || true)
         if [[ -n "$UNCOMMITTED" ]]; then
-            log_warn "Session exited cleanly but produced no commits (uncommitted changes found)"
-            SESSION_STATUS="commit_missing"
+            log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
+            git -C "$PROJECT_ROOT" add -A 2>/dev/null || true
+            if git -C "$PROJECT_ROOT" commit --no-verify -m "chore($BUG_ID): auto-commit session work" 2>/dev/null; then
+                log_info "Auto-commit succeeded"
+                SESSION_STATUS="success"
+            else
+                log_warn "Auto-commit failed — no changes to commit"
+                SESSION_STATUS="crashed"
+            fi
         else
             log_warn "Session exited cleanly but produced no commits and no changes"
             SESSION_STATUS="crashed"
@@ -365,14 +373,9 @@ if [[ "$SESSION_STATUS" == "success" ]]; then
         if [[ -n "$DIRTY_FILES" ]]; then
             log_info "Auto-committing remaining session artifacts..."
             git -C "$PROJECT_ROOT" add -A 2>/dev/null || true
-            git -C "$PROJECT_ROOT" commit --no-verify -m "chore($BUG_ID): include remaining session artifacts" 2>/dev/null || true
-        fi
-
-        DIRTY_FILES=$(git -C "$PROJECT_ROOT" status --porcelain 2>/dev/null || true)
-        if [[ -n "$DIRTY_FILES" ]]; then
-            log_error "Git working tree still not clean after auto-commit."
-            echo "$DIRTY_FILES" | sed 's/^/  - /'
-            SESSION_STATUS="failed"
+            git -C "$PROJECT_ROOT" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                || git -C "$PROJECT_ROOT" commit --no-verify -m "chore($BUG_ID): include remaining session artifacts" 2>/dev/null \
+                || true
         fi
     fi
 fi

package/bundled/dev-pipeline/retry-feature.sh

@@ -338,10 +338,11 @@ if [[ -f "$SESSION_LOG" ]]; then
     log_info "Session log: $FINAL_LINES lines, $((FINAL_SIZE / 1024))KB"
 fi
 
-SESSION_STATUS_FILE="$SESSION_DIR/session-status.json"
-
 # ── Determine session outcome from observable signals ──────────────
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+    | sed 's@^refs/remotes/origin/@@') \
+    || DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
 
 if [[ $EXIT_CODE -eq 124 ]]; then
     log_warn "Session timed out after ${SESSION_TIMEOUT}s"
@@ -353,7 +354,7 @@ else
     # Exit code 0 — check if the session produced commits
     HAS_COMMITS=""
     if git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-        HAS_COMMITS=$(git -C "$PROJECT_ROOT" log main..HEAD --oneline 2>/dev/null | head -1)
+        HAS_COMMITS=$(git -C "$PROJECT_ROOT" log "${DEFAULT_BRANCH}..HEAD" --oneline 2>/dev/null | head -1)
     fi
 
     if [[ -n "$HAS_COMMITS" ]]; then
@@ -361,8 +362,15 @@ else
     else
         UNCOMMITTED=$(git -C "$PROJECT_ROOT" status --porcelain 2>/dev/null | head -1 || true)
         if [[ -n "$UNCOMMITTED" ]]; then
-            log_warn "Session exited cleanly but produced no commits (uncommitted changes found)"
-            SESSION_STATUS="commit_missing"
+            log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
+            git -C "$PROJECT_ROOT" add -A 2>/dev/null || true
+            if git -C "$PROJECT_ROOT" commit --no-verify -m "chore($FEATURE_ID): auto-commit session work" 2>/dev/null; then
+                log_info "Auto-commit succeeded"
+                SESSION_STATUS="success"
+            else
+                log_warn "Auto-commit failed — no changes to commit"
+                SESSION_STATUS="crashed"
+            fi
         else
             log_warn "Session exited cleanly but produced no commits and no changes"
             SESSION_STATUS="crashed"
@@ -377,14 +385,9 @@ if [[ "$SESSION_STATUS" == "success" ]]; then
         if [[ -n "$DIRTY_FILES" ]]; then
             log_info "Auto-committing remaining session artifacts..."
             git -C "$PROJECT_ROOT" add -A 2>/dev/null || true
-            git -C "$PROJECT_ROOT" commit --no-verify -m "chore($FEATURE_ID): include remaining session artifacts" 2>/dev/null || true
-        fi
-
-        DIRTY_FILES=$(git -C "$PROJECT_ROOT" status --porcelain 2>/dev/null || true)
-        if [[ -n "$DIRTY_FILES" ]]; then
-            log_error "Git working tree still not clean after auto-commit."
-            echo "$DIRTY_FILES" | sed 's/^/  - /'
-            SESSION_STATUS="failed"
+            git -C "$PROJECT_ROOT" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                || git -C "$PROJECT_ROOT" commit --no-verify -m "chore($FEATURE_ID): include remaining session artifacts" 2>/dev/null \
+                || true
         fi
     fi
 fi

package/bundled/dev-pipeline/run-bugfix.sh

@@ -168,6 +168,10 @@ spawn_and_wait_session() {
     local session_status
     local project_root
     project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local default_branch
+    default_branch=$(git -C "$project_root" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+        | sed 's@^refs/remotes/origin/@@') \
+        || default_branch=$(git -C "$project_root" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
 
     if [[ $exit_code -eq 124 ]]; then
         log_warn "Session timed out after ${SESSION_TIMEOUT}s"
@@ -179,7 +183,7 @@ spawn_and_wait_session() {
         # Exit code 0 — check if the session actually produced commits
         local has_commits=""
         if git -C "$project_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-            has_commits=$(git -C "$project_root" log main..HEAD --oneline 2>/dev/null | head -1)
+            has_commits=$(git -C "$project_root" log "${default_branch}..HEAD" --oneline 2>/dev/null | head -1)
         fi
 
         if [[ -n "$has_commits" ]]; then
@@ -188,8 +192,15 @@ spawn_and_wait_session() {
             local uncommitted=""
             uncommitted=$(git -C "$project_root" status --porcelain 2>/dev/null | head -1 || true)
             if [[ -n "$uncommitted" ]]; then
-                log_warn "Session exited cleanly but produced no commits (uncommitted changes found)"
-                session_status="commit_missing"
+                log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
+                git -C "$project_root" add -A 2>/dev/null || true
+                if git -C "$project_root" commit --no-verify -m "chore($bug_id): auto-commit session work" 2>/dev/null; then
+                    log_info "Auto-commit succeeded"
+                    session_status="success"
+                else
+                    log_warn "Auto-commit failed — no changes to commit"
+                    session_status="crashed"
+                fi
             else
                 log_warn "Session exited cleanly but produced no commits and no changes"
                 session_status="crashed"
@@ -205,14 +216,9 @@ spawn_and_wait_session() {
             if [[ -n "$dirty_files" ]]; then
                 log_info "Auto-committing remaining session artifacts..."
                 git -C "$project_root" add -A 2>/dev/null || true
-                git -C "$project_root" commit --no-verify -m "chore($bug_id): include remaining session artifacts" 2>/dev/null || true
-            fi
-
-            dirty_files=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
-            if [[ -n "$dirty_files" ]]; then
-                log_error "Git working tree still not clean after auto-commit."
-                echo "$dirty_files" | sed 's/^/  - /'
-                session_status="failed"
+                git -C "$project_root" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                    || git -C "$project_root" commit --no-verify -m "chore($bug_id): include remaining session artifacts" 2>/dev/null \
+                    || true
             fi
         fi
     fi

package/bundled/dev-pipeline/run.sh

@@ -190,6 +190,10 @@ spawn_and_wait_session() {
     local session_status
     local project_root
     project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local default_branch
+    default_branch=$(git -C "$project_root" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+        | sed 's@^refs/remotes/origin/@@') \
+        || default_branch=$(git -C "$project_root" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
 
     if [[ $exit_code -eq 124 ]]; then
         log_warn "Session timed out after ${SESSION_TIMEOUT}s"
@@ -201,7 +205,7 @@ spawn_and_wait_session() {
         # Exit code 0 — check if the session actually produced commits
         local has_commits=""
         if git -C "$project_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-            has_commits=$(git -C "$project_root" log main..HEAD --oneline 2>/dev/null | head -1)
+            has_commits=$(git -C "$project_root" log "${default_branch}..HEAD" --oneline 2>/dev/null | head -1)
         fi
 
         if [[ -n "$has_commits" ]]; then
@@ -212,8 +216,15 @@ spawn_and_wait_session() {
             local uncommitted=""
             uncommitted=$(git -C "$project_root" status --porcelain 2>/dev/null | head -1 || true)
             if [[ -n "$uncommitted" ]]; then
-                log_warn "Session exited cleanly but produced no commits (uncommitted changes found)"
-                session_status="commit_missing"
+                log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
+                git -C "$project_root" add -A 2>/dev/null || true
+                if git -C "$project_root" commit --no-verify -m "chore($feature_id): auto-commit session work" 2>/dev/null; then
+                    log_info "Auto-commit succeeded"
+                    session_status="success"
+                else
+                    log_warn "Auto-commit failed — no changes to commit"
+                    session_status="crashed"
+                fi
             else
                 log_warn "Session exited cleanly but produced no commits and no changes"
                 session_status="crashed"
@@ -230,30 +241,9 @@ spawn_and_wait_session() {
             if [[ -n "$dirty_files" ]]; then
                 log_info "Auto-committing remaining session artifacts..."
                 git -C "$project_root" add -A 2>/dev/null || true
-                git -C "$project_root" commit --no-verify -m "chore($feature_id): include remaining session artifacts" 2>/dev/null || true
-            fi
-
-            # Re-check: if still dirty after auto-commit, flag as commit_missing
-            dirty_files=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
-            if [[ -n "$dirty_files" ]]; then
-                log_warn "Git working tree still not clean after auto-commit."
-                echo "$dirty_files" | sed 's/^/  - /'
-                session_status="commit_missing"
-            else
-                # Bugfix commits (fix: / fix(scope):) are exempt from docs check.
-                local last_commit_subject=""
-                last_commit_subject=$(git -C "$project_root" log -1 --pretty=%s 2>/dev/null || true)
-                if [[ "$last_commit_subject" =~ ^fix(\(|:) ]]; then
-                    log_info "Detected bugfix commit prefix; skipping docs check."
-                else
-                    local docs_changed=""
-                    docs_changed=$(git -C "$project_root" log --name-only --format="" -1 2>/dev/null \
-                        | grep -E '\.prizm-docs/' | head -1 || true)
-                    if [[ -z "$docs_changed" ]]; then
-                        log_warn "Session committed but no .prizm-docs changes detected."
-                        session_status="docs_missing"
-                    fi
-                fi
+                git -C "$project_root" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                    || git -C "$project_root" commit --no-verify -m "chore($feature_id): include remaining session artifacts" 2>/dev/null \
+                    || true
             fi
         fi
     fi

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

@@ -41,6 +41,7 @@ You are running in headless mode with a FINITE context window. Exceeding it will
 4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
 6. **Incremental commits when possible** — If a feature has multiple independent tasks, commit after each completed task rather than one big commit at the end.
+7. **Capture test output once** — When running the test suite, 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.
 
 ---
 
@@ -99,11 +100,22 @@ If plan.md missing, write it directly:
 
 ### Phase 3: Implement + Test
 
+**Before starting**: detect the test command and record baseline:
+```bash
+# Try in order, use first that exits 0
+node --test tests/**/*.test.js 2>&1 | tail -3   # Node built-in
+npm test 2>&1 | tail -3                          # npm fallback
+```
+Record the working command as `TEST_CMD`. Then record baseline failures (if any):
+```bash
+$TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
+```
+
 For each task in plan.md Tasks section:
 1. Read the relevant section from `context-snapshot.md` (no need to re-read individual files)
 2. Write/edit the code
-3. Run tests after each task
-3. Mark task `[x]` in plan.md Tasks section immediately
+3. Run tests after each task: `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20` — then grep `/tmp/test-out.txt` for failure details; never re-run just to apply a different filter
+4. Mark task `[x]` in plan.md Tasks section immediately
 
 After all tasks complete:
 1. Run the full test suite to ensure nothing is broken

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

@@ -41,6 +41,7 @@ You are running in headless mode with a FINITE context window. Exceeding it will
 4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
 6. **Incremental commits when possible** — If a feature has multiple independent tasks, commit after each completed task rather than one big commit at the end.
+7. **Capture test output once** — When running the test suite, 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.
 
 ---
 
@@ -125,10 +126,11 @@ Spawn Dev subagent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_backg
 Prompt:
 > "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
 > **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces. Read source files on-demand as directed by the manifest.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+>    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** Only read a source file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not captured in the interface column.
 > 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 > 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands.
+> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
 > 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
 >    - Files changed/created (with paths)
 >    - Key implementation decisions and rationale
@@ -159,7 +161,7 @@ Prompt:
 >    - Section 4: File Manifest (original file structure)
 >    - '## Implementation Log': what Dev changed, key decisions, discoveries
 > 2. Run prizmkit-code-review: spec compliance (against spec.md), code quality, correctness. Read ONLY files listed in Implementation Log.
-> 3. Run the full test suite using `TEST_CMD=<TEST_CMD>`. Write and execute integration tests covering all user stories.
+> 3. Run the full test suite — **ONLY if the Implementation Log does not already confirm all tests passing**. If the log states tests passed, trust it and skip the re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all user stories.
 > 4. Append '## Review Notes' to context-snapshot.md: issues found (with severity), test results, final verdict.
 > Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
 

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

@@ -73,6 +73,7 @@ You are running in headless mode with a FINITE context window. Exceeding it will
 4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
 6. **Incremental commits when possible** — If a feature has multiple independent tasks, commit after each completed task rather than one big commit at the end.
+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.
 
 ---
 
@@ -118,9 +119,11 @@ Record the working command as `TEST_CMD`. If both fail, record `TEST_CMD="npm te
 
 **Step 2 — Record pre-existing failure baseline**:
 ```bash
-$TEST_CMD 2>&1 | tail -20
+$TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 ```
 Save the list of **pre-existing failing tests** (if any) as `BASELINE_FAILURES`. These are known failures that existed before this session — Dev must NOT be blamed for them, but must list them in COMPLETION_SIGNAL.
+
+> **⚠️ Test Output Rule**: Always capture test output to a temp file (`tee /tmp/test-out.txt`). Then grep the file instead of re-running the suite. Never run `npm test` multiple times just to apply different grep filters to the output.
 {{END_IF_INIT_DONE}}
 
 ### Step 1: Initialize
@@ -242,10 +245,11 @@ Append the following to the Dev agent prompt:
 Prompt:
 > "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
 > **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces. Read source files on-demand as directed by the manifest.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+>    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** The manifest already contains their key interfaces. Only read a source file directly if: (a) it is NOT in the manifest, or (b) you need a specific implementation detail not captured in the manifest's interface column.
 > 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 > 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands.
+> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
 > 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
 >    - Files changed/created (with paths)
 >    - Key implementation decisions and rationale
@@ -300,7 +304,7 @@ Prompt:
 >    - Section 4: File Manifest (original file structure)
 >    - '## Implementation Log': what Dev changed, key decisions, discoveries
 > 2. Run prizmkit-code-review: spec compliance (against spec.md), code quality, correctness. Read ONLY files listed in Implementation Log.
-> 3. Run the full test suite using `TEST_CMD=<TEST_CMD>`. Write and execute integration tests covering all user stories from spec.md.
+> 3. Run the full test suite using `TEST_CMD=<TEST_CMD>` — **ONLY if the Implementation Log does not already confirm all tests passing**. If Implementation Log states tests passed, trust it and skip the re-run. 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. Write and execute integration tests covering all user stories from spec.md.
 > 4. Append '## Review Notes' to context-snapshot.md: issues found (with severity), test results, final verdict.
 > Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
 

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.88",
+  "version": "1.0.89",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.88",
+  "version": "1.0.89",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {