prizmkit 1.1.96 → 1.1.97

package/bundled/dev-pipeline-windows/scripts/monitor-log.ps1

@@ -0,0 +1,102 @@
+#!/usr/bin/env pwsh
+# monitor-log.ps1 — Background log size monitor for AI session subagent (PowerShell)
+#
+# Polls session.log size, computes effective size (current - baseline),
+# and writes a structured JSON status file. Intended to be run by a
+# background subagent inside the AI CLI session.
+#
+# Usage:
+#   pwsh -NoProfile -File monitor-log.ps1 <session_log> <max_size> <poll_interval> <status_file> <baseline_file>
+#   powershell.exe -NoProfile -File monitor-log.ps1 <session_log> <max_size> <poll_interval> <status_file> <baseline_file>
+#
+# Status file format (JSON, rewritten each poll cycle):
+#   {
+#     "status": "OK" | "COMPACT_NEEDED",
+#     "total_bytes": <current session.log size>,
+#     "baseline_bytes": <size after last /compact>,
+#     "effective_bytes": <total - baseline>,
+#     "threshold_bytes": <compact threshold>,
+#     "overage_bytes": <effective - threshold, 0 if not exceeded>,
+#     "usage_pct": <effective / threshold * 100>
+#   }
+
+param(
+    [Parameter(Mandatory=$true)] [string]$SessionLog,
+    [Parameter(Mandatory=$true)] [long]$MaxSize,
+    [Parameter(Mandatory=$true)] [int]$PollInterval,
+    [Parameter(Mandatory=$true)] [string]$StatusFile,
+    [Parameter(Mandatory=$true)] [string]$BaselineFile
+)
+
+if ($MaxSize -lt 0) {
+    Write-Error "ERROR: MaxSize must be a non-negative integer"
+    exit 1
+}
+if ($PollInterval -le 0) {
+    Write-Error "ERROR: PollInterval must be a positive integer"
+    exit 1
+}
+
+# Ensure status directory exists
+$statusDir = Split-Path -Parent $StatusFile
+if (-not (Test-Path $statusDir)) {
+    New-Item -ItemType Directory -Path $statusDir -Force | Out-Null
+}
+
+Write-Error "[monitor-log] Starting log monitor: max=$MaxSize interval=${PollInterval}s"
+Write-Error "[monitor-log] Watching: $SessionLog"
+
+while ($true) {
+    # Read current log size
+    if (Test-Path $SessionLog) {
+        $size = (Get-Item $SessionLog).Length
+    } else {
+        $size = 0
+    }
+
+    # Read baseline (resets after each /compact)
+    $baseline = 0
+    if (Test-Path $BaselineFile) {
+        try {
+            $baseline = [long](Get-Content $BaselineFile -Raw).Trim()
+        } catch {
+            $baseline = 0
+        }
+    }
+
+    # Effective size = growth since last compact
+    $effective = $size - $baseline
+    if ($effective -lt 0) {
+        $effective = 0
+    }
+
+    # Determine status (MaxSize=0 disables monitoring)
+    if ($MaxSize -gt 0 -and $effective -gt $MaxSize) {
+        $status = "COMPACT_NEEDED"
+        $overage = $effective - $MaxSize
+        Write-Error "[monitor-log] COMPACT_NEEDED: effective=$effective overage=$overage (threshold=$MaxSize)"
+    } else {
+        $status = "OK"
+        $overage = 0
+    }
+
+    # Usage percentage
+    if ($MaxSize -gt 0) {
+        $usagePct = [Math]::Floor($effective * 100 / $MaxSize)
+    } else {
+        $usagePct = 0
+    }
+
+    # Write structured JSON status
+    @{
+        status = $status
+        total_bytes = $size
+        baseline_bytes = $baseline
+        effective_bytes = $effective
+        threshold_bytes = $MaxSize
+        overage_bytes = $overage
+        usage_pct = $usagePct
+    } | ConvertTo-Json -Compress | Out-File -FilePath $StatusFile -NoNewline
+
+    Start-Sleep -Seconds $PollInterval
+}

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

@@ -12,7 +12,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and committed.
 
-**Tier 1 — Single Agent**: You handle everything directly. No subagents, no TeamCreate.
+**Tier 1 — Single Agent**: You handle everything directly. No normal work subagents; the log-size monitor is the only allowed persistent background subagent. No TeamCreate.
 
 ### Feature Description
 
@@ -54,6 +54,9 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 ---
 
+{{LOG_SIZE_AWARENESS}}
+---
+
 ## PrizmKit Directory Convention
 
 ```

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

@@ -10,7 +10,7 @@
 
 You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATURE_TITLE}}".
 
-**CRITICAL**: You MUST NOT exit until ALL work is complete and committed. When you spawn subagents, wait for each to finish (run_in_background=false).
+**CRITICAL**: You MUST NOT exit until ALL work is complete and committed. When you spawn normal work subagents, wait for each to finish (run_in_background=false). The log-size monitor is the only allowed persistent background subagent.
 
 **Tier 2 — Dual Agent**: You handle context + planning directly. Then spawn Dev and Reviewer subagents. Spawn Dev and Reviewer agents via the Agent tool.
 
@@ -60,6 +60,9 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 ---
 
+{{LOG_SIZE_AWARENESS}}
+---
+
 ## PrizmKit Directory Convention
 
 ```
@@ -699,7 +702,7 @@ Remove-Item -Force -ErrorAction SilentlyContinue .prizmkit/specs/{{FEATURE_SLUG}
 - Build context-snapshot.md FIRST; all subagents read it instead of re-reading source files
 - 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 subagents
+- Do NOT use `run_in_background=true` when spawning normal work subagents; the log-size monitor is the only allowed persistent background subagent
 - `/prizmkit-committer` is mandatory, and must not be replaced with manual git commit commands
 - Do NOT run `git add`/`git commit` during Phase 1-5 — all changes are committed once in Phase 6
 - If any files remain after the commit, amend the existing commit — do NOT create a follow-up commit

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

@@ -10,7 +10,7 @@
 
 You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATURE_TITLE}}".
 
-**CRITICAL**: You MUST NOT exit until ALL work is complete and committed. When you spawn subagents, wait for each to finish (run_in_background=false). Do NOT spawn agents in background and exit — that kills the session.
+**CRITICAL**: You MUST NOT exit until ALL work is complete and committed. When you spawn normal work subagents, wait for each to finish (run_in_background=false). The log-size monitor is the only allowed persistent background subagent. Do NOT spawn work agents in background and exit — that kills the session.
 
 **Tier 3 — Full Team**: For complex features, use the full pipeline (Phase 0–6) with Dev + Reviewer agents spawned via the Agent tool.
 
@@ -60,6 +60,9 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 ---
 
+{{LOG_SIZE_AWARENESS}}
+---
+
 ## PrizmKit Directory Convention
 
 ```
@@ -780,7 +783,7 @@ Remove-Item -Force -ErrorAction SilentlyContinue .prizmkit/specs/{{FEATURE_SLUG}
 - Tier 3: full team — Dev (implementation) → Reviewer (review) — spawn agents directly via Agent tool
 - 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 agents
+- Do NOT use `run_in_background=true` when spawning normal work agents; the log-size monitor is the only allowed persistent background subagent
 - Commit phase must use `/prizmkit-committer`; do NOT replace with manual git commit commands
 - Do NOT run `git add`/`git commit` during Phase 1-5 — all changes are committed once in Phase 6
 - If any files remain after the commit, amend the existing commit — do NOT create a follow-up commit

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

@@ -13,6 +13,8 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and committed.
 
+**SUBAGENT LIFECYCLE**: The log-size monitor is the only allowed persistent background subagent. Any normal work subagent must be awaited with `run_in_background=false`.
+
 **NON-INTERACTIVE MODE**: There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input. Make decisions autonomously and move forward.
 
 ### Bug Description
@@ -51,6 +53,7 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 4. **Minimize tool output** — Capture to temp file, scan first/last lines, filter with Select-String, regex matching, or PowerShell object filtering. Never load full output.
 5. **No intermediate commits** — All changes committed once at the end via `/prizmkit-committer`.
 
+{{LOG_SIZE_AWARENESS}}
 ## Bug Fix Artifacts Directory
 
 ```

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

@@ -12,7 +12,7 @@
 
 You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}: "{{REFACTOR_TITLE}}".
 
-**CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. Do NOT spawn an agent in the background and exit — that kills the session.
+**CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn normal work subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. The log-size monitor is the only allowed persistent background subagent. Do NOT spawn a work agent in the background and exit — that kills the session.
 
 **NON-INTERACTIVE MODE**: You are running in headless non-interactive mode. There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
 
@@ -78,6 +78,7 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 ## Execution Instructions
 
+{{LOG_SIZE_AWARENESS}}
 **YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
 
 **Agent spawn failure policy (all Agent tool calls)**:
@@ -336,4 +337,4 @@ Write to: `{{SESSION_STATUS_PATH}}`
 - **Commit with** `refactor(<scope>):` prefix, NOT `feat:` or `fix:`
 - **Run full retrospective** (Job 1 + Job 2) — refactoring changes code structure
 - ALWAYS write session-status.json before exiting
-- Do NOT use `run_in_background=true` when spawning agents
+- Do NOT use `run_in_background=true` when spawning normal work agents; the log-size monitor is the only allowed persistent background subagent

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

@@ -0,0 +1,78 @@
+## Session Log Budget Monitoring (PROACTIVE)
+
+Your session log grows with every tool call and subagent spawn.
+To prevent context exhaustion, **spawn a background monitoring subagent at session start**.
+
+### How to Set Up the Monitor
+
+1. **AS THE VERY FIRST ACTION** (before Phase 0), spawn a monitoring subagent
+   with `run_in_background: true` and this task:
+
+   ```
+   Run this command and keep it running:
+   $psHost = if (Get-Command pwsh -ErrorAction SilentlyContinue) { 'pwsh' } else { 'powershell.exe' }
+   & $psHost -NoProfile -File {{LOG_MONITOR_SCRIPT}} {{SESSION_LOG_PATH}} {{MAX_LOG_SIZE}} {{LOG_MONITOR_POLL_INTERVAL}} {{LOG_MONITOR_STATUS_FILE}} {{LOG_MONITOR_BASELINE_FILE}}
+   ```
+
+   The subagent MUST use `run_in_background: true`. It writes a JSON status
+   file every {{LOG_MONITOR_POLL_INTERVAL}} seconds.
+
+2. **BEFORE EACH MAJOR PHASE** (Phase 0, 1, 2, ...), read the status:
+
+   ```powershell
+   if (Test-Path {{LOG_MONITOR_STATUS_FILE}}) { Get-Content {{LOG_MONITOR_STATUS_FILE}} } else { '{"status":"OK"}' }
+   ```
+
+   The status file contains structured diagnostics:
+
+   ```json
+   {
+     "status": "OK | COMPACT_NEEDED",
+     "total_bytes": <current session.log size>,
+     "baseline_bytes": <size after last /compact>,
+     "effective_bytes": <total - baseline, incremental growth>,
+     "threshold_bytes": <{{MAX_LOG_SIZE}}>,
+     "overage_bytes": <effective - threshold, 0 when OK>,
+     "usage_pct": <effective / threshold * 100>
+   }
+   ```
+
+   Extract fields for decision-making:
+   ```powershell
+   $data = Get-Content {{LOG_MONITOR_STATUS_FILE}} | ConvertFrom-Json
+   $status = $data.status
+   $effective = $data.effective_bytes
+   $overage = $data.overage_bytes
+   $usage = $data.usage_pct
+   ```
+
+3. **On COMPACT_NEEDED** (effective_bytes > {{MAX_LOG_SIZE}} bytes, {{MAX_LOG_SIZE_HUMAN}}):
+   - Check `overage_bytes` to decide urgency:
+     - **Minor overage** (< 512KB): complete the current sub-step, update durable workflow checkpoint artifacts, write baseline, `/compact`
+     - **Major overage** (>= 512KB): update durable workflow checkpoint artifacts, write baseline, `/compact` — do NOT start new work
+   - Write baseline before `/compact`:
+     ```powershell
+     (Get-Item {{SESSION_LOG_PATH}}).Length | Out-File -NoNewline {{LOG_MONITOR_BASELINE_FILE}}
+     ```
+   - Execute `/compact`
+   - Continue the workflow after `/compact`; re-read this status file before the next major phase
+
+### How the Baseline Prevents Infinite Compaction Loops
+
+- Before the first `/compact`: baseline = 0, effective = full log size → triggers when log exceeds threshold
+- After `/compact`: baseline = current log size, effective ≈ 0 → status resets to OK
+- The monitor only triggers again when **new** log growth since the last compact exceeds the threshold
+- Each `/compact` resets the baseline, breaking the infinite loop
+
+### Log Growth Reduction Tips
+
+- **Re-read context-snapshot.md instead of source files** — already in context
+- **Filter command output** — pipe to `Select-Object -Last 20` or `Select-String`, never full output
+- **Limit subagent prompts** — shorter, focused prompts = shorter transcripts
+- **Checkpoint often** — update durable workflow checkpoint artifacts before `/compact`
+
+### What Survives
+
+- All git commits are permanent
+- The workflow checkpoint is preserved and auto-resumed
+- `/compact` compresses context without losing progress

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.96",
+  "version": "1.1.97",
   "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.1.96",
+  "version": "1.1.97",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {