prizmkit 1.1.98 → 1.1.100

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

@@ -43,6 +43,8 @@ SESSION_STATUS_VALUES = [
     "crashed",
     "timed_out",
     "infra_error",
+    "context_overflow",
+    "stalled_context_continuation",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -90,6 +92,12 @@ def parse_args():
     parser.add_argument("--max-retries", type=int, default=3, help="Maximum code retry count (default: 3)")
     parser.add_argument("--max-infra-retries", type=int, default=3, help="Maximum infrastructure retry count (default: 3)")
     parser.add_argument("--project-root", default=None, help="Project root directory. Required for 'clean' action.")
+    parser.add_argument("--active-dev-branch", default=None, help="Development branch preserved for continuation after context overflow.")
+    parser.add_argument("--base-branch", default=None, help="Original/base branch for continuation branch reuse.")
+    parser.add_argument("--last-fatal-error-code", default=None, help="Fatal runtime error code associated with continuation.")
+    parser.add_argument("--continuation-summary-path", default=None, help="Optional continuation summary artifact path.")
+    parser.add_argument("--no-progress-count", type=int, default=None, help="Consecutive context-overflow sessions without objective progress.")
+    parser.add_argument("--progress-fingerprint", default=None, help="JSON progress fingerprint captured after the session.")
     return parser.parse_args()
 
 
@@ -122,7 +130,7 @@ def load_refactor_status(state_dir, refactor_id):
     The 'status' field is NOT included — status lives exclusively
     in refactor-list.json.
     """
-    status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
+    status_path = os.path.join(state_dir, refactor_id, "status.json")
     if not os.path.isfile(status_path):
         return _default_status(refactor_id)
     data, err = load_json_file(status_path)
@@ -137,7 +145,7 @@ def save_refactor_status(state_dir, refactor_id, status_data):
     """Write the status.json for a refactor (runtime fields only)."""
     # Defensively strip status — it belongs in refactor-list.json
     status_data.pop("status", None)
-    status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
+    status_path = os.path.join(state_dir, refactor_id, "status.json")
     return write_json_file(status_path, status_data)
 
 
@@ -168,6 +176,128 @@ def update_refactor_in_list(refactor_list_path, refactor_id, new_status):
     return write_json_file(refactor_list_path, data)
 
 
+CONTINUATION_PENDING_FIELDS = [
+    "active_dev_branch",
+    "base_branch",
+    "continuation_pending",
+    "continuation_reason",
+    "last_context_overflow_session_id",
+    "previous_session_id",
+    "last_fatal_error_code",
+    "continuation_summary_path",
+    "no_progress_count",
+    "last_progress_fingerprint",
+    "needs_attention",
+    "stalled_context_continuation",
+    "stalled_reason",
+]
+
+CONTINUATION_COUNTER_FIELDS = [
+    "context_overflow_count",
+    "continuation_count",
+]
+
+
+def has_pending_continuation_metadata(status_data):
+    """Return True when runtime state still has pending continuation metadata."""
+    return any(key in status_data for key in CONTINUATION_PENDING_FIELDS)
+
+
+def clear_pending_continuation_metadata(status_data):
+    """Clear branch/pending continuation fields while preserving observability counters."""
+    for key in CONTINUATION_PENDING_FIELDS:
+        status_data.pop(key, None)
+
+
+def reset_continuation_metadata(status_data):
+    """Clear all continuation runtime metadata, including manual-reset counters."""
+    clear_pending_continuation_metadata(status_data)
+    for key in CONTINUATION_COUNTER_FIELDS:
+        status_data.pop(key, None)
+
+
+STALL_REASON = "context_overflow_without_git_checkpoint_or_artifact_progress"
+
+
+def _load_progress_fingerprint(raw):
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return {"unparsed": str(raw)}
+
+
+def _set_continuation_common(status_data, args, session_id):
+    if args.active_dev_branch:
+        status_data["active_dev_branch"] = args.active_dev_branch
+    if args.base_branch:
+        status_data["base_branch"] = args.base_branch
+    status_data["last_context_overflow_session_id"] = session_id
+    status_data["previous_session_id"] = session_id
+    status_data["last_fatal_error_code"] = args.last_fatal_error_code or "context_overflow"
+    if args.continuation_summary_path:
+        status_data["continuation_summary_path"] = args.continuation_summary_path
+    else:
+        status_data.pop("continuation_summary_path", None)
+    if args.no_progress_count is not None:
+        status_data["no_progress_count"] = max(0, args.no_progress_count)
+    fingerprint = _load_progress_fingerprint(args.progress_fingerprint)
+    if fingerprint is not None:
+        status_data["last_progress_fingerprint"] = fingerprint
+    status_data["last_infra_error_session_id"] = None
+    status_data["resume_from_phase"] = None
+    if session_id:
+        status_data["last_session_id"] = session_id
+
+
+def set_context_overflow_continuation_metadata(status_data, args, session_id):
+    """Record continuation metadata for a context-overflow outcome in status.json."""
+    status_data["context_overflow_count"] = status_data.get("context_overflow_count", 0) + 1
+    status_data["continuation_count"] = status_data.get("continuation_count", 0) + 1
+    status_data["continuation_pending"] = True
+    status_data["continuation_reason"] = "context_overflow"
+    status_data.pop("needs_attention", None)
+    status_data.pop("stalled_context_continuation", None)
+    status_data.pop("stalled_reason", None)
+    _set_continuation_common(status_data, args, session_id)
+
+
+def set_stalled_context_continuation_metadata(status_data, args, session_id):
+    """Record no-progress context-overflow stall without consuming retry budgets."""
+    status_data["context_overflow_count"] = status_data.get("context_overflow_count", 0) + 1
+    status_data["continuation_count"] = status_data.get("continuation_count", 0) + 1
+    _set_continuation_common(status_data, args, session_id)
+    status_data["continuation_pending"] = False
+    status_data["continuation_reason"] = STALL_REASON
+    status_data["needs_attention"] = True
+    status_data["stalled_context_continuation"] = True
+    status_data["stalled_reason"] = STALL_REASON
+    if args.no_progress_count is None or args.no_progress_count < 2:
+        status_data["no_progress_count"] = 2
+
+
+def continuation_metadata_summary(status_data):
+    """Return additive continuation fields for CLI JSON outputs."""
+    return {
+        "active_dev_branch": status_data.get("active_dev_branch"),
+        "base_branch": status_data.get("base_branch"),
+        "continuation_pending": status_data.get("continuation_pending", False),
+        "continuation_reason": status_data.get("continuation_reason"),
+        "last_context_overflow_session_id": status_data.get("last_context_overflow_session_id"),
+        "last_fatal_error_code": status_data.get("last_fatal_error_code"),
+        "previous_session_id": status_data.get("previous_session_id"),
+        "context_overflow_count": status_data.get("context_overflow_count", 0),
+        "continuation_count": status_data.get("continuation_count", 0),
+        "no_progress_count": status_data.get("no_progress_count", 0),
+        "last_progress_fingerprint": status_data.get("last_progress_fingerprint"),
+        "needs_attention": status_data.get("needs_attention", False),
+        "stalled_context_continuation": status_data.get("stalled_context_continuation", False),
+        "stalled_reason": status_data.get("stalled_reason"),
+        "continuation_summary_path": status_data.get("continuation_summary_path"),
+    }
+
+
 # ---------------------------------------------------------------------------
 # Action: get_next
 # ---------------------------------------------------------------------------
@@ -275,6 +405,7 @@ def action_get_next(refactor_list_data, state_dir):
         "infra_error_count": chosen_status_data.get("infra_error_count", 0),
         "resume_from_phase": chosen_status_data.get("resume_from_phase", None),
     }
+    result.update(continuation_metadata_summary(chosen_status_data))
     print(json.dumps(result, indent=2, ensure_ascii=False))
 
 
@@ -298,12 +429,15 @@ def action_update(args, refactor_list_path, state_dir):
 
     rs = load_refactor_status(state_dir, refactor_id)
 
+    current_list_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
+
     # Track what status we write to refactor-list.json
-    new_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
+    new_status = current_list_status
 
     if session_status == "success":
         rs["infra_error_count"] = 0
         rs["last_infra_error_session_id"] = None
+        clear_pending_continuation_metadata(rs)
         new_status = "completed"
         rs["resume_from_phase"] = None
         err = update_refactor_in_list(refactor_list_path, refactor_id, "completed")
@@ -335,7 +469,7 @@ def action_update(args, refactor_list_path, state_dir):
         rs["infra_error_count"] = infra_error_count
         rs["last_infra_error_session_id"] = session_id
         rs["max_infra_retries"] = max_infra_retries
-        rs["degraded_reason"] = "infra_error"
+        rs["degraded_reason"] = session_status
         if session_id:
             rs["last_session_id"] = session_id
         rs["resume_from_phase"] = None
@@ -347,6 +481,23 @@ def action_update(args, refactor_list_path, state_dir):
         else:
             new_status = "pending"
 
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
+            return
+    elif session_status == "context_overflow":
+        # Context overflow is continuation state, not code or infra retry state.
+        set_context_overflow_continuation_metadata(rs, args, session_id)
+        new_status = "in_progress"
+        if current_list_status != "in_progress":
+            err = update_refactor_in_list(refactor_list_path, refactor_id, "in_progress")
+            if err:
+                error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
+                return
+    elif session_status == "stalled_context_continuation":
+        # No-progress context-overflow stall pauses automation without consuming retry budgets.
+        set_stalled_context_continuation_metadata(rs, args, session_id)
+        new_status = "failed"
         err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
@@ -415,6 +566,14 @@ def action_update(args, refactor_list_path, state_dir):
         summary["restart_policy"] = "infra_retry"
         summary["infra_error_count"] = rs.get("infra_error_count", 0)
         summary["artifacts_preserved"] = True
+    elif session_status == "context_overflow":
+        summary["restart_policy"] = "context_overflow_continuation"
+        summary.update(continuation_metadata_summary(rs))
+        summary["artifacts_preserved"] = True
+    elif session_status == "stalled_context_continuation":
+        summary["restart_policy"] = "needs_attention"
+        summary.update(continuation_metadata_summary(rs))
+        summary["artifacts_preserved"] = True
     elif session_status != "success":
         summary["restart_policy"] = "full_restart"
         summary["cleanup_performed"] = cleaned
@@ -442,7 +601,7 @@ def cleanup_refactor_artifacts(state_dir, refactor_id, project_root=None):
     cleaned = []
 
     # 1) Remove all session history
-    sessions_dir = os.path.join(state_dir, "refactors", refactor_id, "sessions")
+    sessions_dir = os.path.join(state_dir, refactor_id, "sessions")
     sessions_deleted = 0
     if os.path.isdir(sessions_dir):
         for entry in os.listdir(sessions_dir):
@@ -453,7 +612,7 @@ def cleanup_refactor_artifacts(state_dir, refactor_id, project_root=None):
         cleaned.append("Deleted {} session(s) from {}".format(sessions_deleted, sessions_dir))
 
     # 2) Remove transient files under refactor dir (keep status.json)
-    refactor_dir = os.path.join(state_dir, "refactors", refactor_id)
+    refactor_dir = os.path.join(state_dir, refactor_id)
     if os.path.isdir(refactor_dir):
         for entry in os.listdir(refactor_dir):
             if entry == "status.json" or entry == "sessions":
@@ -481,9 +640,47 @@ def cleanup_refactor_artifacts(state_dir, refactor_id, project_root=None):
     return cleaned
 
 
+def _resolve_project_file(project_root, path):
+    if not path:
+        return None
+    if os.path.isabs(path):
+        target = os.path.abspath(path)
+    else:
+        target = os.path.abspath(os.path.join(project_root, path))
+    root = os.path.abspath(project_root)
+    try:
+        rel = os.path.relpath(target, root)
+    except ValueError:
+        return None
+    if rel == os.pardir or rel.startswith(os.pardir + os.sep):
+        return None
+    return target
+
+
+def cleanup_continuation_artifacts(project_root, status_data, candidate_paths=None):
+    """Delete durable continuation handoff files for a manual clean reset."""
+    candidates = []
+    if isinstance(status_data, dict):
+        candidates.append(status_data.get("continuation_summary_path"))
+    candidates.extend(candidate_paths or [])
+
+    cleaned = []
+    seen = set()
+    for candidate in candidates:
+        target = _resolve_project_file(project_root, candidate)
+        if not target or target in seen:
+            continue
+        seen.add(target)
+        if os.path.basename(target) != "continuation-summary.md":
+            continue
+        if os.path.isfile(target):
+            os.remove(target)
+            cleaned.append("Deleted continuation artifact {}".format(target))
+    return cleaned
+
+
 def load_session_status(state_dir, refactor_id, session_id):
-    session_status_path = os.path.join(
-        state_dir, "refactors", refactor_id, "sessions",
+    session_status_path = os.path.join(state_dir, refactor_id, "sessions",
         session_id, "session-status.json"
     )
     data, err = load_json_file(session_status_path)
@@ -757,6 +954,7 @@ def action_reset(args, refactor_list_path, state_dir):
     rs["sessions"] = []
     rs["last_session_id"] = None
     rs["resume_from_phase"] = None
+    reset_continuation_metadata(rs)
     rs["updated_at"] = now_iso()
 
     err = save_refactor_status(state_dir, refactor_id, rs)
@@ -797,7 +995,7 @@ def action_clean(args, refactor_list_path, state_dir):
     cleaned = []
 
     # 1. Delete session history
-    sessions_dir = os.path.join(state_dir, "refactors", refactor_id, "sessions")
+    sessions_dir = os.path.join(state_dir, refactor_id, "sessions")
     sessions_deleted = 0
     if os.path.isdir(sessions_dir):
         for entry in os.listdir(sessions_dir):
@@ -824,12 +1022,19 @@ def action_clean(args, refactor_list_path, state_dir):
     old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
     old_retry = rs.get("retry_count", 0)
 
+    continuation_candidates = [
+        os.path.join(".prizmkit", "refactor", refactor_id, "continuation-summary.md"),
+        os.path.join(".prizmkit", "specs", refactor_id, "continuation-summary.md"),
+    ]
+    cleaned.extend(cleanup_continuation_artifacts(project_root, rs, continuation_candidates))
+
     rs["retry_count"] = 0
     rs["infra_error_count"] = 0
     rs["last_infra_error_session_id"] = None
     rs["sessions"] = []
     rs["last_session_id"] = None
     rs["resume_from_phase"] = None
+    reset_continuation_metadata(rs)
     rs["updated_at"] = now_iso()
 
     err = save_refactor_status(state_dir, refactor_id, rs)
@@ -905,10 +1110,11 @@ def action_start(args, refactor_list_path, state_dir):
         error_out("Failed to save refactor status: {}".format(err))
         return
 
-    err = update_refactor_in_list(refactor_list_path, refactor_id, "in_progress")
-    if err:
-        error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
-        return
+    if old_status != "in_progress":
+        err = update_refactor_in_list(refactor_list_path, refactor_id, "in_progress")
+        if err:
+            error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
+            return
 
     result = {
         "action": "start",
@@ -1060,6 +1266,7 @@ def action_unskip(args, refactor_list_path, state_dir):
         rs["sessions"] = []
         rs["last_session_id"] = None
         rs["resume_from_phase"] = None
+        reset_continuation_metadata(rs)
         rs["updated_at"] = now_iso()
         save_refactor_status(state_dir, rid, rs)
 

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

@@ -35,7 +35,7 @@ Test command:
 Known baseline failures:
 `{{BASELINE_FAILURES}}`
 
-If plan.md has more than 5 tasks, run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+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.
 
 ## Required Outputs
 

package/bundled/dev-pipeline/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 normal work subagents; the log-size monitor is the only allowed persistent background subagent. No TeamCreate.
+**Tier 1 — Single Agent**: You handle everything directly. No normal work subagents. No TeamCreate.
 
 ### Feature Description
 
@@ -145,7 +145,7 @@ You know this project's tech stack. Identify ALL test commands that apply (e.g.,
 - Runs tests using `TEST_CMD` after each task
 - Writes '## Implementation Log' to `context-snapshot.md`
 
-**3b-compact.** Context management — if plan.md has more than 5 tasks, run `/compact` after completing every 3 tasks during implementation. This prevents context window exhaustion in long sessions. If `/compact` is not available (non-Claude CLI), skip this step.
+**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]`

package/bundled/dev-pipeline/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 normal work subagents, wait for each to finish (run_in_background=false). The log-size monitor is the only allowed persistent background subagent.
+**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).
 
 **Tier 2 — Dual Agent**: You handle context + planning directly. Then spawn Dev and Reviewer subagents. Spawn Dev and Reviewer agents via the Agent tool.
 
@@ -276,7 +276,7 @@ Prompt:
 > ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
 > 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: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 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."
@@ -604,7 +604,7 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 - 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 normal work subagents; the log-size monitor is the only allowed persistent background subagent
+- Do NOT use `run_in_background=true` when spawning normal work subagents
 - **NEVER delete, modify, or touch any file under `.prizmkit/state/`** — those are pipeline runtime files managed by the runner
 - NEVER run `rm -rf`, `git clean`, or any destructive filesystem operations
 - `/prizmkit-committer` is mandatory, and must not be replaced with manual git commit commands

package/bundled/dev-pipeline/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 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.
+**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). 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.
 
@@ -284,7 +284,7 @@ Prompt:
 > ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
 > 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: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 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."
@@ -638,7 +638,7 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 - 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 normal work agents; the log-size monitor is the only allowed persistent background subagent
+- Do NOT use `run_in_background=true` when spawning normal work agents
 - Commit phase must use `/prizmkit-committer`; do NOT replace with manual git commit commands
 - **NEVER delete, modify, or touch any file under `.prizmkit/state/`** — those are pipeline runtime files managed by the runner
 - NEVER run `rm -rf`, `git clean`, or any destructive filesystem operations

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

@@ -13,7 +13,7 @@ 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`.
+**SUBAGENT LIFECYCLE**: Any normal work subagent must be awaited with `run_in_background=false`. Do not spawn persistent background subagents for headless recovery.
 
 **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.
 

package/bundled/dev-pipeline/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 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.
+**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. 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.
 
@@ -185,7 +185,7 @@ Evidence must cover affected UI render, primary user interactions, behavior-sens
 
 {{END_IF_BROWSER_INTERACTION}}
 
-  7. If the refactor involves multiple files: run `/compact` after completing half the tasks to free context budget. If `/compact` is unavailable, continue without it.
+  7. If the refactor involves multiple files: update durable checkpoints/artifacts at the midpoint, 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.
   8. After all tasks complete, run the full test suite one final time
   "
 - **Wait for Dev to return**
@@ -337,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 normal work agents; the log-size monitor is the only allowed persistent background subagent
+- Do NOT use `run_in_background=true` when spawning normal work agents

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

@@ -1,76 +1,41 @@
-## Session Log Budget Monitoring (PROACTIVE)
+## Session Log Budget Awareness (CHECKPOINT GUIDANCE)
 
-Your session log grows with every tool call and subagent spawn.
-To prevent context exhaustion, **spawn a background monitoring subagent at session start**.
+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.
 
-### How to Set Up the Monitor
+### Checkpoint Before Large Work Batches
 
-1. **AS THE VERY FIRST ACTION** (before Phase 0), spawn a monitoring subagent
-   with `run_in_background: true` and this task:
+- `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.
 
-   ```
-   Run this command and keep it running:
-   bash {{LOG_MONITOR_SCRIPT}} {{SESSION_LOG_PATH}} {{MAX_LOG_SIZE}} {{LOG_MONITOR_POLL_INTERVAL}} {{LOG_MONITOR_STATUS_FILE}} {{LOG_MONITOR_BASELINE_FILE}}
-   ```
+### Headless Recovery Source of Truth
 
-   The subagent MUST use `run_in_background: true`. It writes a JSON status
-   file every {{LOG_MONITOR_POLL_INTERVAL}} seconds.
+- 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.
 
-2. **BEFORE EACH MAJOR PHASE** (Phase 0, 1, 2, ...), read the status:
+### Interactive Claude Code Note
 
-   ```bash
-   cat {{LOG_MONITOR_STATUS_FILE}} 2>/dev/null || echo '{"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:
-   ```bash
-   status=$(jq -r '.status' {{LOG_MONITOR_STATUS_FILE}})
-   effective=$(jq -r '.effective_bytes' {{LOG_MONITOR_STATUS_FILE}})
-   overage=$(jq -r '.overage_bytes' {{LOG_MONITOR_STATUS_FILE}})
-   usage=$(jq -r '.usage_pct' {{LOG_MONITOR_STATUS_FILE}})
-   ```
-
-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`:
-     ```bash
-     wc -c < {{SESSION_LOG_PATH}} > {{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
+- `/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
 
-- **Re-read context-snapshot.md instead of source files** — already in context
-- **Filter command output** — pipe to `tail -20` or `grep`, 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
+- 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.

package/bundled/dev-pipeline/templates/session-status-schema.json

@@ -15,7 +15,7 @@
     },
     "status": {
       "type": "string",
-      "enum": ["success", "partial", "failed", "commit_missing", "docs_missing", "merge_conflict"]
+      "enum": ["success", "partial", "failed", "commit_missing", "docs_missing", "merge_conflict", "context_overflow"]
     },
     "completed_phases": {
       "type": "array",

package/bundled/dev-pipeline/tests/conftest.py

@@ -24,5 +24,6 @@ def _load_hyphenated_module(module_name, filename):
 # Register hyphenated script files so tests can import them with underscores.
 _load_hyphenated_module("generate_bootstrap_prompt", "generate-bootstrap-prompt.py")
 _load_hyphenated_module("generate_bugfix_prompt", "generate-bugfix-prompt.py")
+_load_hyphenated_module("generate_refactor_prompt", "generate-refactor-prompt.py")
 _load_hyphenated_module("prizmkit_test_gate", "prizmkit-test-gate.py")
 _load_hyphenated_module("update_feature_status", "update-feature-status.py")