prizmkit 1.1.7 → 1.1.9

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

@@ -60,12 +60,12 @@ def parse_args():
     parser.add_argument(
         "--feature-list",
         required=True,
-        help="Path to the feature-list.json file",
+        help="Path to the .prizmkit/plans/feature-list.json file",
     )
     parser.add_argument(
         "--state-dir",
         required=True,
-        help="Path to the state/ directory",
+        help="Path to the state directory (default: .prizmkit/state/features)",
     )
     parser.add_argument(
         "--action",
@@ -159,7 +159,7 @@ def load_feature_status(state_dir, feature_id, feature_list_status=None):
     If the file does not exist, return a default pending status.
 
     If feature_list_status is a terminal status (completed, failed, skipped),
-    it overrides the status field from status.json. This makes feature-list.json
+    it overrides the status field from status.json. This makes .prizmkit/plans/feature-list.json
     the single source of truth for terminal statuses, while all other fields
     (retry_count, sessions, etc.) still come from status.json.
     """
@@ -195,7 +195,7 @@ def load_feature_status(state_dir, feature_id, feature_list_status=None):
             "created_at": now,
             "updated_at": now,
         }
-    # feature-list.json wins for terminal statuses
+    # .prizmkit/plans/feature-list.json wins for terminal statuses
     if feature_list_status in TERMINAL_STATUSES:
         data["status"] = feature_list_status
     return data
@@ -210,7 +210,7 @@ def save_feature_status(state_dir, feature_id, status_data):
 
 
 def update_feature_in_list(feature_list_path, feature_id, new_status):
-    """Update a feature's status field in feature-list.json.
+    """Update a feature's status field in .prizmkit/plans/feature-list.json.
 
     Reads the whole file, modifies the target feature's status, writes back.
     Returns an error string on failure, None on success.
@@ -226,7 +226,7 @@ def update_feature_in_list(feature_list_path, feature_id, new_status):
             found = True
             break
     if not found:
-        return "Feature '{}' not found in feature-list.json".format(feature_id)
+        return "Feature '{}' not found in .prizmkit/plans/feature-list.json".format(feature_id)
     return write_json_file(feature_list_path, data)
 
 
@@ -336,13 +336,13 @@ def auto_skip_blocked_features(feature_list_path, state_dir, failed_feature_id):
     by marking those blocked features as auto_skipped, allowing the pipeline to
     continue processing unblocked features and eventually reach PIPELINE_COMPLETE.
 
-    Re-reads feature-list.json from disk to get the latest state (including the
+    Re-reads .prizmkit/plans/feature-list.json from disk to get the latest state (including the
     just-written failed status from update_feature_in_list).
 
-    NOTE: This function performs a read-modify-write on feature-list.json without
-    file locking. The caller (action_update) also writes to feature-list.json
+    NOTE: This function performs a read-modify-write on .prizmkit/plans/feature-list.json without
+    file locking. The caller (action_update) also writes to .prizmkit/plans/feature-list.json
     immediately before calling this. Safe for single-pipeline execution, but if
-    multiple pipeline instances share the same feature-list.json concurrently,
+    multiple pipeline instances share the same .prizmkit/plans/feature-list.json concurrently,
     a race condition may cause lost writes. Add file locking if parallel pipelines
     are introduced.
     """
@@ -383,7 +383,7 @@ def auto_skip_blocked_features(feature_list_path, state_dir, failed_feature_id):
     if not to_skip:
         return []
 
-    # Batch-write to feature-list.json
+    # Batch-write to .prizmkit/plans/feature-list.json
     for f in features:
         if isinstance(f, dict) and f.get("id") in to_skip:
             f["status"] = "auto_skipped"
@@ -605,26 +605,31 @@ def action_update(args, feature_list_path, state_dir):
         fs["resume_from_phase"] = None
         err = update_feature_in_list(feature_list_path, feature_id, "completed")
         if err:
-            error_out("Failed to update feature-list.json: {}".format(err))
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
             return
     elif session_status in ("commit_missing", "docs_missing", "merge_conflict"):
-        # Degraded outcome: keep artifacts for retry and expose specific status.
+        # Degraded outcome: keep artifacts for retry.
+        # Store granular reason in status.json (internal state),
+        # but write only schema-valid status to feature-list.json.
         fs["retry_count"] = fs.get("retry_count", 0) + 1
 
         if fs["retry_count"] >= max_retries:
             fs["status"] = "failed"
             target_status = "failed"
         else:
+            # status.json keeps the granular degraded reason for diagnostics
             fs["status"] = session_status
-            target_status = session_status
+            # feature-list.json gets schema-valid "pending" (will be retried)
+            target_status = "pending"
 
+        fs["degraded_reason"] = session_status
         fs["resume_from_phase"] = None
         fs["sessions"] = []
         fs["last_session_id"] = None
 
         err = update_feature_in_list(feature_list_path, feature_id, target_status)
         if err:
-            error_out("Failed to update feature-list.json: {}".format(err))
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
             return
     else:
         # crashed / failed / timed_out — preserve all artifacts for debugging.
@@ -646,7 +651,7 @@ def action_update(args, feature_list_path, state_dir):
 
         err = update_feature_in_list(feature_list_path, feature_id, target_status)
         if err:
-            error_out("Failed to update feature-list.json: {}".format(err))
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
             return
 
     if session_status == "success" and session_id:
@@ -707,11 +712,12 @@ BOX_WIDTH = 68
 
 
 def _calc_feature_duration(state_dir, feature_id):
-    """计算已完成 Feature 的耗时（秒）。
+    """Calculate the duration (in seconds) of a completed feature.
 
-    通过 status.json 的 created_at 和 updated_at 来计算。
-    如果有 session 记录，尝试用第一个 session 的 started_at 到最后更新时间来计算。
-    返回 None 如果无法计算。
+    Computes duration from status.json's created_at and updated_at fields.
+    If session records exist, attempts to use the first session's started_at
+    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")
     if not os.path.isfile(fs_path):
@@ -730,7 +736,7 @@ def _calc_feature_duration(state_dir, feature_id):
         t_start = datetime.strptime(created_at, fmt)
         t_end = datetime.strptime(updated_at, fmt)
         delta = (t_end - t_start).total_seconds()
-        # 过滤异常值：少于 10 秒或超过 24 小时的忽略
+        # Filter outliers: ignore durations less than 10s or more than 24h
         if delta < 10 or delta > 86400:
             return None
         return delta
@@ -739,7 +745,7 @@ def _calc_feature_duration(state_dir, feature_id):
 
 
 def _format_duration(seconds):
-    """将秒数格式化为人类可读的时间字符串。"""
+    """Format seconds into a human-readable duration string."""
     if seconds is None:
         return "N/A"
     seconds = int(seconds)
@@ -756,17 +762,18 @@ def _format_duration(seconds):
 
 
 def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None):
-    """基于已完成 Feature 的历史耗时，按 complexity 加权预估剩余时间。
+    """Estimate remaining time based on completed feature durations, weighted by complexity.
 
-    策略:
-    1. 收集所有已完成 Feature 的耗时，按 complexity 分组
-    2. 对剩余的 pending/in_progress Feature，用对应 complexity 的平均耗时估算
-    3. 如果某个 complexity 没有历史数据，用全局平均值兜底
+    Strategy:
+    1. Collect durations of all completed features, grouped by complexity
+    2. For remaining pending/in_progress features, estimate using the average duration
+       of the corresponding complexity level
+    3. If no historical data exists for a complexity level, fall back to the global average
 
-    返回 (estimated_seconds, confidence) 元组。
-    confidence: "high" (>=50% 已完成), "medium" (>=25%), "low" (<25%)
+    Returns an (estimated_seconds, confidence) tuple.
+    confidence: "high" (>=50% completed), "medium" (>=25%), "low" (<25%)
     """
-    # complexity 权重（用于没有历史数据时的估算）
+    # Complexity weights (used for estimation when no historical data is available)
     COMPLEXITY_WEIGHT = {"low": 1.0, "medium": 2.0, "high": 4.0}
 
     # Build feature-list status map for terminal status override
@@ -776,7 +783,7 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
             if isinstance(f, dict) and f.get("id"):
                 fl_status_map[f["id"]] = f.get("status")
 
-    # 按 complexity 分组收集已完成 Feature 的耗时
+    # Collect completed feature durations grouped by complexity
     duration_by_complexity = {}  # complexity -> [duration_seconds]
     feature_complexity_map = {}  # feature_id -> complexity
 
@@ -811,13 +818,13 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
     if not all_durations:
         return None, "low"
 
-    # 计算各 complexity 的平均耗时
+    # Calculate average duration per complexity level
     avg_by_complexity = {}
     for c, durations in duration_by_complexity.items():
         avg_by_complexity[c] = sum(durations) / len(durations)
     global_avg = sum(all_durations) / len(all_durations)
 
-    # 估算剩余 Feature 的耗时
+    # Estimate duration for remaining features
     remaining_seconds = 0.0
     remaining_count = 0
     for feature in features:
@@ -835,12 +842,12 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
         if complexity in avg_by_complexity:
             remaining_seconds += avg_by_complexity[complexity]
         else:
-            # 没有该 complexity 的历史数据，用全局均值 × 权重比例估算
+            # No historical data for this complexity; estimate using global avg × weight ratio
             weight = COMPLEXITY_WEIGHT.get(complexity, 2.0)
             base_weight = COMPLEXITY_WEIGHT.get("medium", 2.0)
             remaining_seconds += global_avg * (weight / base_weight)
 
-    # 计算置信度
+    # Calculate confidence level
     total = len([f for f in features if isinstance(f, dict) and f.get("id")])
     completed = counts.get("completed", 0)
     if total > 0:
@@ -860,7 +867,7 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
 def action_status(feature_list_data, state_dir, feature_filter=None):
     """Print a formatted overview of all features and their status.
 
-    Status is read exclusively from feature-list.json (the single source of
+    Status is read exclusively from .prizmkit/plans/feature-list.json (the single source of
     truth).  state_dir is only used for ETA estimation when session history
     is available.
     """
@@ -882,12 +889,10 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
         "pending": 0,
         "skipped": 0,
         "auto_skipped": 0,
-        "commit_missing": 0,
-        "docs_missing": 0,
     }
     feature_lines = []
 
-    # Build status map from feature-list.json only
+    # Build status map from .prizmkit/plans/feature-list.json only
     status_map = {}
     for feature in features:
         if not isinstance(feature, dict):
@@ -897,6 +902,19 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             continue
         status_map[fid] = feature.get("status", "pending")
 
+    # Build degraded_reason map from status.json (internal pipeline state)
+    degraded_reason_map = {}
+    for feature in features:
+        if not isinstance(feature, dict):
+            continue
+        fid = feature.get("id")
+        if not fid:
+            continue
+        fs = load_feature_status(state_dir, fid, feature.get("status"))
+        dr = fs.get("degraded_reason")
+        if dr:
+            degraded_reason_map[fid] = dr
+
     for feature in features:
         if not isinstance(feature, dict):
             continue
@@ -906,6 +924,7 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             continue
 
         fstatus = feature.get("status", "pending")
+        degraded_reason = degraded_reason_map.get(fid)
 
         # Count statuses
         if fstatus in counts:
@@ -914,7 +933,14 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             counts["pending"] += 1
 
         # Build status indicator and color
-        if fstatus == "completed":
+        # Show degraded reason via icon when a pending feature has one
+        if fstatus == "pending" and degraded_reason == "commit_missing":
+            icon = COLOR_RED + "[↑]" + COLOR_RESET
+        elif fstatus == "pending" and degraded_reason == "docs_missing":
+            icon = COLOR_RED + "[D]" + COLOR_RESET
+        elif fstatus == "pending" and degraded_reason == "merge_conflict":
+            icon = COLOR_RED + "[⚡]" + COLOR_RESET
+        elif fstatus == "completed":
             icon = COLOR_GREEN + "[✓]" + COLOR_RESET
         elif fstatus == "in_progress":
             icon = COLOR_YELLOW + "[→]" + COLOR_RESET
@@ -924,16 +950,22 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             icon = COLOR_GRAY + "[—]" + COLOR_RESET
         elif fstatus == "auto_skipped":
             icon = COLOR_GRAY + "[⊘]" + COLOR_RESET
-        elif fstatus == "commit_missing":
-            icon = COLOR_RED + "[↑]" + COLOR_RESET
-        elif fstatus == "docs_missing":
-            icon = COLOR_RED + "[D]" + COLOR_RESET
         else:
             icon = COLOR_GRAY + "[ ]" + COLOR_RESET
 
         # Build detail suffix
         detail = ""
-        if fstatus == "pending":
+        if fstatus == "pending" and degraded_reason:
+            detail = " ({}, retrying)".format(degraded_reason)
+            # Also check if blocked by dependencies
+            deps = feature.get("dependencies", [])
+            blocking = [
+                d for d in deps
+                if status_map.get(d, "pending") != "completed"
+            ]
+            if blocking:
+                detail = " ({}, blocked by {})".format(degraded_reason, ", ".join(blocking))
+        elif fstatus == "pending":
             # Check if blocked by dependencies
             deps = feature.get("dependencies", [])
             blocking = [
@@ -950,6 +982,8 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             ]
             if blockers:
                 detail = " (auto-skipped: blocked by {})".format(", ".join(blockers))
+        elif fstatus == "failed" and degraded_reason:
+            detail = " (last failure: {})".format(degraded_reason)
 
         # Apply color to the whole line content
         if fstatus == "completed":
@@ -964,7 +998,7 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
             line_content = "{} {} {}{}".format(
                 fid, icon, COLOR_RED + title + COLOR_RESET, detail
             )
-        elif fstatus in ("commit_missing", "docs_missing"):
+        elif degraded_reason:
             line_content = "{} {} {}{}".format(
                 fid, icon, COLOR_RED + title + COLOR_RESET, detail
             )
@@ -978,16 +1012,16 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
     total = len(features)
     completed = counts["completed"]
 
-    # 计算百分比
+    # Calculate percentage
     if total > 0:
         percent = round(completed / total * 100, 1)
     else:
         percent = 0.0
 
-    # 生成进度条
+    # Generate progress bar
     progress_bar = _build_progress_bar(percent, width=24)
 
-    # 预估剩余时间
+    # Estimate remaining time
     est_remaining, confidence = _estimate_remaining_time(
         features, state_dir, counts, feature_list_data
     )
@@ -998,11 +1032,18 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
     summary_line2 = "Failed: {} | Pending: {} | Skipped: {} | Auto-skipped: {}".format(
         counts["failed"], counts["pending"], counts["skipped"], counts["auto_skipped"]
     )
-    summary_line3 = "Commit Missing: {} | Docs Missing: {}".format(
-        counts["commit_missing"], counts["docs_missing"]
+
+    # Count degraded features (pending with a degraded_reason from status.json)
+    degraded_count = sum(
+        1 for fid, dr in degraded_reason_map.items()
+        if status_map.get(fid) == "pending" and dr
     )
+    if degraded_count > 0:
+        summary_line3 = "Degraded (retrying): {}".format(degraded_count)
+    else:
+        summary_line3 = None
 
-    # 构建预估剩余时间行
+    # Build estimated remaining time line
     CONFIDENCE_ICONS = {"high": "●", "medium": "◐", "low": "○"}
     if est_remaining is not None:
         eta_str = _format_duration(est_remaining)
@@ -1021,7 +1062,8 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
     print("║" + pad_right("  Project: {}".format(app_name), inner) + " ║")
     print("║" + pad_right("  {}".format(summary_line), inner) + " ║")
     print("║" + pad_right("  {}".format(summary_line2), inner) + " ║")
-    print("║" + pad_right("  {}".format(summary_line3), inner) + " ║")
+    if summary_line3:
+        print("║" + pad_right("  {}".format(summary_line3), inner) + " ║")
     print("╠" + "─" * BOX_WIDTH + "╣")
     print("║" + pad_right("  Progress: {}".format(progress_bar), inner) + " ║")
     print("║" + pad_right("  {}".format(eta_line), inner) + " ║")
@@ -1038,7 +1080,7 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
 def action_start(args, feature_list_path, state_dir):
     """Mark a feature as in_progress at session start.
 
-    This keeps feature-list.json/state status in sync during execution,
+    This keeps .prizmkit/plans/feature-list.json/state status in sync during execution,
     instead of only updating after session end.
     """
     feature_id = args.feature_id
@@ -1059,7 +1101,7 @@ def action_start(args, feature_list_path, state_dir):
 
     err = update_feature_in_list(feature_list_path, feature_id, "in_progress")
     if err:
-        error_out("Failed to update feature-list.json: {}".format(err))
+        error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
         return
 
     result = {
@@ -1080,7 +1122,7 @@ def action_reset(args, feature_list_path, state_dir):
     """Reset a feature to pending state.
 
     Resets status.json (status -> pending, retry_count -> 0, clear sessions,
-    clear resume_from_phase) and updates feature-list.json status to pending.
+    clear resume_from_phase) and updates .prizmkit/plans/feature-list.json status to pending.
     Does NOT delete any files on disk.
     """
     feature_id = args.feature_id
@@ -1107,10 +1149,10 @@ def action_reset(args, feature_list_path, state_dir):
         error_out("Failed to save feature status: {}".format(err))
         return
 
-    # Update feature-list.json
+    # Update .prizmkit/plans/feature-list.json
     err = update_feature_in_list(feature_list_path, feature_id, "pending")
     if err:
-        error_out("Failed to update feature-list.json: {}".format(err))
+        error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
         return
 
     result = {
@@ -1202,7 +1244,7 @@ def action_clean(args, feature_list_path, state_dir):
 
     err = update_feature_in_list(feature_list_path, feature_id, "pending")
     if err:
-        error_out("Failed to update feature-list.json: {}".format(err))
+        error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
         return
 
     result = {
@@ -1248,7 +1290,7 @@ def action_unskip(args, feature_list_path, state_dir):
                 target = f
                 break
         if not target:
-            error_out("Feature '{}' not found in feature-list.json".format(feature_id))
+            error_out("Feature '{}' not found in .prizmkit/plans/feature-list.json".format(feature_id))
             return
         if target.get("status") not in ("failed", "skipped", "auto_skipped"):
             error_out(
@@ -1328,7 +1370,7 @@ def action_unskip(args, feature_list_path, state_dir):
         error_out("No features to unskip")
         return
 
-    # Reset all collected features in feature-list.json
+    # Reset all collected features in .prizmkit/plans/feature-list.json
     reset_details = []
     for f in features:
         if isinstance(f, dict) and f.get("id") in to_reset:
@@ -1342,7 +1384,7 @@ def action_unskip(args, feature_list_path, state_dir):
 
     err = write_json_file(feature_list_path, data)
     if err:
-        error_out("Failed to write feature-list.json: {}".format(err))
+        error_out("Failed to write .prizmkit/plans/feature-list.json: {}".format(err))
         return
 
     # Reset status.json for each feature