prizmkit 1.1.98 → 1.1.100

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

@@ -46,6 +46,8 @@ SESSION_STATUS_VALUES = [
     "crashed",
     "timed_out",
     "infra_error",
+    "context_overflow",
+    "stalled_context_continuation",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -117,6 +119,37 @@ def parse_args():
         default=None,
         help="Feature filter: comma-separated IDs (F-001,F-003) or range (F-001:F-010), or mixed.",
     )
+    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()
 
 
@@ -167,9 +200,7 @@ def load_feature_status(state_dir, feature_id):
     The 'status' field is NOT included — status lives exclusively
     in feature-list.json.
     """
-    status_path = os.path.join(
-        state_dir, "features", feature_id, "status.json"
-    )
+    status_path = os.path.join(state_dir, feature_id, "status.json")
     if not os.path.isfile(status_path):
         now = now_iso()
         return {
@@ -210,9 +241,7 @@ def save_feature_status(state_dir, feature_id, status_data):
     """Write the status.json for a feature (runtime fields only)."""
     # Defensively strip status — it belongs in feature-list.json
     status_data.pop("status", None)
-    status_path = os.path.join(
-        state_dir, "features", feature_id, "status.json"
-    )
+    status_path = os.path.join(state_dir, feature_id, "status.json")
     return write_json_file(status_path, status_data)
 
 
@@ -248,6 +277,128 @@ def update_feature_in_list(feature_list_path, feature_id, new_status):
     return write_json_file(feature_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.pop("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"),
+    }
+
+
 def _default_project_root():
     # Script lives at <pipeline>/scripts/update-feature-status.py.
     # Pipeline may be either <project>/.prizmkit/dev-pipeline (user install)
@@ -284,6 +435,45 @@ def _get_feature_slug(feature_list_path, feature_id):
     return None
 
 
+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 cleanup_feature_artifacts(feature_list_path, state_dir, feature_id, project_root=None):
     """Delete intermediate artifacts for a failed feature run.
 
@@ -296,7 +486,7 @@ def cleanup_feature_artifacts(feature_list_path, state_dir, feature_id, project_
     cleaned = []
 
     # 1) Remove all session history
-    sessions_dir = os.path.join(state_dir, "features", feature_id, "sessions")
+    sessions_dir = os.path.join(state_dir, feature_id, "sessions")
     sessions_deleted = 0
     if os.path.isdir(sessions_dir):
         for entry in os.listdir(sessions_dir):
@@ -307,7 +497,7 @@ def cleanup_feature_artifacts(feature_list_path, state_dir, feature_id, project_
         cleaned.append("Deleted {} session(s) from {}".format(sessions_deleted, sessions_dir))
 
     # 2) Remove transient files under feature state dir (keep status.json)
-    feature_dir = os.path.join(state_dir, "features", feature_id)
+    feature_dir = os.path.join(state_dir, feature_id)
     if os.path.isdir(feature_dir):
         for entry in os.listdir(feature_dir):
             if entry == "status.json" or entry == "sessions":
@@ -344,8 +534,7 @@ def cleanup_feature_artifacts(feature_list_path, state_dir, feature_id, project_
 
 def load_session_status(state_dir, feature_id, session_id):
     """Load a session's session-status.json file."""
-    session_status_path = os.path.join(
-        state_dir, "features", feature_id, "sessions",
+    session_status_path = os.path.join(state_dir, feature_id, "sessions",
         session_id, "session-status.json"
     )
     data, err = load_json_file(session_status_path)
@@ -580,6 +769,7 @@ def action_get_next(feature_list_data, state_dir, feature_filter=None):
         "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))
 
 
@@ -616,6 +806,8 @@ def action_update(args, feature_list_path, state_dir):
     if session_status == "success":
         fs["infra_error_count"] = 0
         fs["last_infra_error_session_id"] = None
+        pending_continuation_metadata = has_pending_continuation_metadata(fs)
+        clear_pending_continuation_metadata(fs)
         # No-op guard: if this exact successful session was already recorded,
         # avoid rewriting state files again (prevents post-commit dirty changes).
         existing_sessions = fs.get("sessions", [])
@@ -625,7 +817,7 @@ def action_update(args, feature_list_path, state_dir):
             and session_id in existing_sessions
             and fs.get("last_session_id") == session_id
         )
-        if already_completed and (same_session_already_recorded or not session_id):
+        if already_completed and not pending_continuation_metadata and (same_session_already_recorded or not session_id):
             summary = {
                 "action": "update",
                 "feature_id": feature_id,
@@ -678,7 +870,7 @@ def action_update(args, feature_list_path, state_dir):
         fs["infra_error_count"] = infra_error_count
         fs["last_infra_error_session_id"] = session_id
         fs["max_infra_retries"] = max_infra_retries
-        fs["degraded_reason"] = "infra_error"
+        fs["degraded_reason"] = session_status
         if session_id:
             fs["last_session_id"] = session_id
         fs["resume_from_phase"] = None
@@ -690,6 +882,23 @@ def action_update(args, feature_list_path, state_dir):
         else:
             new_status = "pending"
 
+        err = update_feature_in_list(feature_list_path, feature_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
+            return
+    elif session_status == "context_overflow":
+        # Context overflow is continuation state, not code or infra retry state.
+        set_context_overflow_continuation_metadata(fs, args, session_id)
+        new_status = "in_progress"
+        if current_list_status != "in_progress":
+            err = update_feature_in_list(feature_list_path, feature_id, "in_progress")
+            if err:
+                error_out("Failed to update .prizmkit/plans/feature-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(fs, args, session_id)
+        new_status = "failed"
         err = update_feature_in_list(feature_list_path, feature_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
@@ -755,6 +964,14 @@ def action_update(args, feature_list_path, state_dir):
         summary["restart_policy"] = "infra_retry"
         summary["infra_error_count"] = fs.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(fs))
+        summary["artifacts_preserved"] = True
+    elif session_status == "stalled_context_continuation":
+        summary["restart_policy"] = "needs_attention"
+        summary.update(continuation_metadata_summary(fs))
+        summary["artifacts_preserved"] = True
     elif session_status != "success":
         summary["restart_policy"] = "preserve_and_retry"
         summary["artifacts_preserved"] = True
@@ -785,7 +1002,7 @@ def _calc_feature_duration(state_dir, feature_id):
     to the last update time for the calculation.
     Returns None if the duration cannot be calculated.
     """
-    fs_path = os.path.join(state_dir, "features", feature_id, "status.json")
+    fs_path = os.path.join(state_dir, feature_id, "status.json")
     if not os.path.isfile(fs_path):
         return None
     data, err = load_json_file(fs_path)
@@ -1162,10 +1379,11 @@ def action_start(args, feature_list_path, state_dir):
         error_out("Failed to save feature status: {}".format(err))
         return
 
-    err = update_feature_in_list(feature_list_path, feature_id, "in_progress")
-    if err:
-        error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
-        return
+    if old_status != "in_progress":
+        err = update_feature_in_list(feature_list_path, feature_id, "in_progress")
+        if err:
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
+            return
 
     result = {
         "action": "start",
@@ -1207,6 +1425,7 @@ def action_reset(args, feature_list_path, state_dir):
     fs["sessions"] = []
     fs["last_session_id"] = None
     fs["resume_from_phase"] = None
+    reset_continuation_metadata(fs)
     fs["updated_at"] = now_iso()
 
     # Write back status.json
@@ -1261,7 +1480,7 @@ def action_clean(args, feature_list_path, state_dir):
     cleaned = []
 
     # 1. Delete session history
-    sessions_dir = os.path.join(state_dir, "features", feature_id, "sessions")
+    sessions_dir = os.path.join(state_dir, feature_id, "sessions")
     sessions_deleted = 0
     if os.path.isdir(sessions_dir):
         for entry in os.listdir(sessions_dir):
@@ -1296,12 +1515,18 @@ def action_clean(args, feature_list_path, state_dir):
     old_status = get_feature_status_from_list(feature_list_path, feature_id)
     old_retry = fs.get("retry_count", 0)
 
+    continuation_candidates = [
+        os.path.join(".prizmkit", "specs", feature_slug, "continuation-summary.md"),
+    ]
+    cleaned.extend(cleanup_continuation_artifacts(project_root, fs, continuation_candidates))
+
     fs["retry_count"] = 0
     fs["infra_error_count"] = 0
     fs["last_infra_error_session_id"] = None
     fs["sessions"] = []
     fs["last_session_id"] = None
     fs["resume_from_phase"] = None
+    reset_continuation_metadata(fs)
     fs["updated_at"] = now_iso()
 
     err = save_feature_status(state_dir, feature_id, fs)
@@ -1463,6 +1688,7 @@ def action_unskip(args, feature_list_path, state_dir):
         fs["sessions"] = []
         fs["last_session_id"] = None
         fs["resume_from_phase"] = None
+        reset_continuation_metadata(fs)
         fs["updated_at"] = now_iso()
         save_feature_status(state_dir, fid, fs)