specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.status.md

@@ -0,0 +1,863 @@
+---
+description: Display a comprehensive dashboard of project status, Lifecycle tracking, and quality metrics.
+handoffs: []
+writes: []
+  # Read-only: this command produces no artifact.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — read-only** ⚠️ [settled 2026-09-13]:
+
+This command **writes no project artifact**. It reads the artifacts and renders a dashboard. The shared rerun rule (*detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent*) governs the commands that produce them.
+
+The dashboard is derived output: it is never a source, and refreshing it never replaces anything.
+
+> **Why a shared rule rather than per-command courtesy**: nine of the twelve non-implementation commands already had some protection, but each wrote it its own way, and three had none — not by decision, but because the discipline had no shared carrier. The rule everywhere else is: **detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent.** This command's read-only posture means it never triggers the third clause.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Outline
+
+Goal: Provide a visual, comprehensive status dashboard showing all aspects of the specification-driven development workflow, including Lifecycle tracking, quality metrics, and progress indicators.
+
+---
+
+## Execution Steps
+
+**Step 1: Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root and parse paths.
+
+**Step 2: Load specification status**:
+
+```bash
+# Load spec.md
+FEATURE_SPEC="specs/spec.md"
+
+# Extract version
+# Format contract: version line is a bold text line `**Version**: X.Y.Z`
+SPEC_VERSION=$(grep '^\*\*Version\*\*:' "$FEATURE_SPEC" | head -1 | awk '{print $2}')
+
+# Extract update statistics
+# ⚠️ **The User-Story heading is `### US1 - [Brief Title] (Priority: P1)`** — see
+# `templates/spec-template.md`. It was never `### User Story`, so this count was **0 on
+# every spec built from the template** and the panel showed "0" for a file with 11 stories
+# (T094/ISS-63). ⚠️ Same defect appears in `qc.md`'s `check_cp002` (count AND its
+# line-number lookup) and in `specpro.specify.md`'s existing-spec statistics — all four
+# move together, or the next reader writes the predicate from whichever copy they find.
+US_COUNT=$(grep -cE '^### US[0-9]+ ' "$FEATURE_SPEC" 2>/dev/null || true)
+: "${US_COUNT:=0}"
+# FR line format contract: indented bold list item (see spec-template).
+# qc and status MUST stay consistent. Anchored on the trailing colon to
+# avoid matching FR mentions in prose. Supports sub-numbers like FR-xxxA.
+# ⚠️ `|| echo "0"` was WRONG even here, where the PATTERN is right: `grep -c` prints `0`
+# AND exits 1, so the idiom produced the two-line string "0\n0". `|| true` + `:=` keeps the
+# value a single number (T093/T094).
+FR_COUNT=$(grep -cE '^[[:space:]]*- \*\*FR-[0-9]+[A-E]?\*\*:' "$FEATURE_SPEC" 2>/dev/null || true)
+: "${FR_COUNT:=0}"
+```
+
+**Step 3: Parse Lifecycle fields**:
+
+```markdown
+Load spec.md and extract ALL Lifecycle fields:
+- User Stories: ID, Title, Priority, Lifecycle: [specify] [plan] [tasks]
+- Functional Requirements: ID, Title, Lifecycle: [specify] [plan] [tasks]
+<!-- ⚠️ **Those two are the whole list** (`T249` / `ISS-225`): a third line here used to name
+     `Constitution Constraints: Text, Lifecycle: [specify] [plan] [tasks]`, and **that section
+     carries no `**Lifecycle**:` field** — the template emits none, so the line described a
+     class this scan would look for and never find. Adjudication + evidence:
+     `commands/specpro.specify.md` → *Lifecycle Update Rules* (`T239` / `ISS-212`).
+     ⚠️ **Do not add it back**, and do not "fix" it by giving that section the field —
+     nothing parses a constraint's lifecycle, so it would be a value with no consumer.
+     The counting below is **per segment** (specify / plan / tasks), not per class, so it is
+     unaffected by the removal. -->
+
+⚠️ CRITICAL: Use NEW status labels (create/update/delete/processed/deprecated):
+- **specify**: create | update | delete | processed | deprecated
+- **plan**: create | update | delete | processed | deprecated
+- **tasks**: create | update | delete | processed | deprecated
+
+Calculate statistics:
+- Specify stage: How many items per specifyStatus (create, update, delete, processed, deprecated)
+- Plan stage: How many items per planStatus (create, update, delete, processed, deprecated)
+- Tasks stage: How many items per tasksStatus (create, update, delete, processed, deprecated)
+- Overall completion: Percentage of items with planStatus = processed AND tasksStatus = processed
+```
+
+**Step 4: Load quality checklist** (if exists):
+
+```bash
+QUALITY_CHECKLIST="specs/checklists/requirements.md"
+
+if [[ -f "$QUALITY_CHECKLIST" ]]; then
+    # Extract quality score
+    # ⚠️ **读清单真实携带的那三个字段**（`T174`）：本节此前读的是 `Overall Quality` 外加一个
+    # `[0-9]/[0-9]` 的**分数形** —— 而 `templates/requirements-template.md` **从不产出这个字段**，
+    # 那个形状在本仓库的任何清单上都匹配不到。清单真正有的是：`**Status**: PASS|BLOCK`、
+    # `**Total Items**`、`**Passed**`、`**Failed**`，以及逐条的 `**Status**: x|⊘ Skipped|✗ Failed`。
+    QUALITY_STATUS=$(grep -m1 -oE '\*\*Status\*\*: *[A-Z]+' "$QUALITY_CHECKLIST" | sed 's/.*: *//')
+    QUALITY_TOTAL=$(grep -m1 -oE '\*\*Total Items\*\*: *[0-9]+' "$QUALITY_CHECKLIST" | grep -oE '[0-9]+')
+    QUALITY_PASSED=$(grep -m1 -oE '\*\*Passed\*\*: *[0-9]+' "$QUALITY_CHECKLIST" | grep -oE '[0-9]+')
+    QUALITY_SCORE="${QUALITY_PASSED:-?}/${QUALITY_TOTAL:-?}"
+
+    # Count issues
+    # ⚠️ 失败数取清单自己写的 `**Failed**`，不取 `❌ FAIL` 字面（`T174`）—— 后者没有生产者。
+    FAIL_COUNT=$(grep -m1 -oE '\*\*Failed\*\*: *[0-9]+' "$QUALITY_CHECKLIST" | grep -oE '[0-9]+')
+    : "${FAIL_COUNT:=0}"
+    # ⚠️ **`⚠️ WARNING` 这一类在清单里根本不存在**：模板只有 PASS|BLOCK 与 x|⊘ Skipped|✗ Failed
+    # 三种取值，没有 warning 档。⇒ 那个计数**永远为 0**，而一个恒为 0 的指标读起来像"没有警告"。
+    # ⇒ 删掉它，而不是保留一个只会返回 0 的数（`T174`）。
+else
+    QUALITY_SCORE="N/A"
+    FAIL_COUNT="0"
+    QUALITY_STATUS="(no checklist)"
+fi
+```
+
+**Step 5: Load contract coverage**:
+
+```bash
+CONTRACTS_DIR="specs/contracts/"
+
+if [[ -d "$CONTRACTS_DIR" ]]; then
+    # Count contracts by User Story
+    P1_CONTRACTS=$(find "$CONTRACTS_DIR" -name "*.md" -exec grep -l "Priority.*P1" {} \; 2>/dev/null | wc -l)
+    P2_CONTRACTS=$(find "$CONTRACTS_DIR" -name "*.md" -exec grep -l "Priority.*P2" {} \; 2>/dev/null | wc -l)
+    P3_CONTRACTS=$(find "$CONTRACTS_DIR" -name "*.md" -exec grep -l "Priority.*P3" {} \; 2>/dev/null | wc -l)
+
+    TOTAL_CONTRACTS=$(find "$CONTRACTS_DIR" -name "*.md" | wc -l)
+else
+    P1_CONTRACTS=0
+    P2_CONTRACTS=0
+    P3_CONTRACTS=0
+    TOTAL_CONTRACTS=0
+fi
+```
+
+**Step 6: Load tasks status**:
+
+```bash
+TASKS_FILE="specs/tasks.md"
+
+if [[ -f "$TASKS_FILE" ]]; then
+    # Count total tasks
+    TOTAL_TASKS=$(grep -c "^- \[ \]" "$TASKS_FILE" 2>/dev/null || true)
+    : "${TOTAL_TASKS:=0}"
+    COMPLETED_TASKS=$(grep -c "^- \[x\]" "$TASKS_FILE" 2>/dev/null || true)
+    : "${COMPLETED_TASKS:=0}"
+
+    # Calculate completion percentage
+    if [[ $TOTAL_TASKS -gt 0 ]]; then
+        TASK_PERCENT=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
+    else
+        TASK_PERCENT=0
+    fi
+else
+    TOTAL_TASKS=0
+    COMPLETED_TASKS=0
+    TASK_PERCENT=0
+fi
+```
+
+**Step 6.2: Load test tasks status** 🆕 (if exists):
+
+```bash
+TEST_TASKS_FILE="specs/test-tasks.md"
+
+if [[ -f "$TEST_TASKS_FILE" ]]; then
+    TEST_TASKS_EXISTS=true
+
+    # Count high-level test tasks by prefix (INF/IT/CE/AE), EXCLUDING [DELETED] stale entries
+    REMAINING_TEST_TASKS=$(grep -E "^- \[ \] (INF|IT|CE|AE)-" "$TEST_TASKS_FILE" 2>/dev/null | grep -cv "\[DELETED\]" || true)
+    : "${REMAINING_TEST_TASKS:=0}"
+    COMPLETED_TEST_TASKS=$(grep -E "^- \[x\] (INF|IT|CE|AE)-" "$TEST_TASKS_FILE" 2>/dev/null | grep -cv "\[DELETED\]" || true)
+    : "${COMPLETED_TEST_TASKS:=0}"
+
+    # Completion percentage (over done + pending)
+    TEST_TASK_TOTAL=$((REMAINING_TEST_TASKS + COMPLETED_TEST_TASKS))
+    if [[ $TEST_TASK_TOTAL -gt 0 ]]; then
+        TEST_TASK_PERCENT=$((COMPLETED_TEST_TASKS * 100 / TEST_TASK_TOTAL))
+    else
+        TEST_TASK_PERCENT=0
+    fi
+
+    # Coverage matrix stats — ⚠️ anchor the status column at END OF LINE (`| <status> |$`):
+    # the status column is the LAST cell of each matrix row. Plain substring matches FALSE-count
+    # layer cells (a pending-impl row has 4 layer cells reading "| pending-impl |"). The optional `( \(.*\))?`
+    # group absorbs annotated statuses like "not-started (decode sub-item pending)". Do NOT use `[^|]*$`-
+    # style classes here — they over-match across cells.
+    MATRIX_FR_TOTAL=$(grep -cE "^\| FR-[0-9]+[A-E]? \|" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_TOTAL:=0}"
+    MATRIX_FR_PENDING_IMPL=$(grep -cE "\| pending-impl \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_PENDING_IMPL:=0}"
+    MATRIX_FR_MANUAL=$(grep -cE "\| manual \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_MANUAL:=0}"
+    MATRIX_FR_NOT_APPLICABLE=$(grep -cE "\| not-applicable \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_NOT_APPLICABLE:=0}"
+    MATRIX_FR_DEPRECATED=$(grep -cE "\| deprecated \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_DEPRECATED:=0}"
+    MATRIX_FR_NOT_STARTED=$(grep -cE "\| not-started( \(.*\))? \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_NOT_STARTED:=0}"
+    MATRIX_FR_IN_PROGRESS=$(grep -cE "\| in-progress( \(.*\))? \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_IN_PROGRESS:=0}"
+    MATRIX_FR_COMPLETED=$(grep -cE "\| completed( \(.*\))? \|$" "$TEST_TASKS_FILE" 2>/dev/null || true)
+    : "${MATRIX_FR_COMPLETED:=0}"
+
+    # Active FRs = rows this workflow tracks to completion
+    # (excludes planning verdicts: pending-impl / manual / not-applicable / deprecated)
+    MATRIX_FR_ACTIVE=$((MATRIX_FR_TOTAL - MATRIX_FR_PENDING_IMPL - MATRIX_FR_MANUAL - MATRIX_FR_NOT_APPLICABLE - MATRIX_FR_DEPRECATED))
+else
+    TEST_TASKS_EXISTS=false
+fi
+
+# 🆕 Lightweight alerts for the Test Task Progress section (S5 — status stays read-only;
+# these are hints, not a health score; thresholds adjustable).
+S5_WARN_PENDING_IMPL=false
+S5_WARN_LAGGING=false
+TESTPLAN_LAST_RUN="N/A"
+
+if [[ "$TEST_TASKS_EXISTS" == "true" ]]; then
+    # Alert 1: large backlog of FRs planned but never implemented
+    if [[ $MATRIX_FR_PENDING_IMPL -gt 10 ]]; then
+        S5_WARN_PENDING_IMPL=true
+    fi
+
+    # Alert 2: execution-tracked FRs exist but the matrix has not been refreshed
+    # for more than 7 days. `find -mtime -7` (POSIX) = modified within 7 days;
+    # empty result → stale. test-tasks.md mtime doubles as "last test-plan run".
+    if [[ $((MATRIX_FR_NOT_STARTED + MATRIX_FR_IN_PROGRESS)) -gt 0 ]]; then
+        if [[ -z "$(find "$TEST_TASKS_FILE" -mtime -7 2>/dev/null)" ]]; then
+            S5_WARN_LAGGING=true
+            # ⚠️ 兜底链必须在**同一行内**（契约规则二的豁免细则第 2 条）：跨行 if/else 不算
+            # 兜底链、不豁免 —— 而 `stat -c` 是 GNU 专有，macOS 的 BSD `stat` 不认。
+            # `||` 的优先级低于管道，故右半是 `stat -c … | cut …` 一整条（正是要的）。
+            TESTPLAN_LAST_RUN=$(stat -f '%Sm' -t '%Y-%m-%d' "$TEST_TASKS_FILE" 2>/dev/null || stat -c %y "$TEST_TASKS_FILE" 2>/dev/null | cut -d' ' -f1)
+            TESTPLAN_LAST_RUN=${TESTPLAN_LAST_RUN:-N/A}
+        fi
+    fi
+fi
+```
+
+**Step 6.5: Load analysis results** 🆕 (if exists):
+
+```bash
+ANALYSIS_DIR="specs/analysis/"
+
+if [[ -d "$ANALYSIS_DIR" ]]; then
+    # Find most recent analysis
+    # Portable: `ls -t` instead of GNU-only `find -printf '%T+'`
+    LATEST_ANALYSIS=$(ls -t "$ANALYSIS_DIR"analysis-*.md 2>/dev/null | head -1)
+
+    if [[ -f "$LATEST_ANALYSIS" ]]; then
+        # Extract metrics from latest analysis
+        # Portable mtime — ⚠️ **单行**兜底链（BSD 优先、GNU 兜底）。跨行的 if/else **不是**
+        # 兜底链、不豁免（契约规则二豁免细则第 2 条），而 `stat -c` 是 GNU 专有。
+        ANALYSIS_DATE=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M:%S' "$LATEST_ANALYSIS" 2>/dev/null || stat -c %y "$LATEST_ANALYSIS" 2>/dev/null | cut -d'.' -f1)
+
+        # Parse JSON metrics snapshot
+        CRITICAL_COUNT=$(grep -o '"critical": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${CRITICAL_COUNT:=0}"
+        HIGH_COUNT=$(grep -o '"high": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${HIGH_COUNT:=0}"
+        MEDIUM_COUNT=$(grep -o '"medium": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${MEDIUM_COUNT:=0}"
+        LOW_COUNT=$(grep -o '"low": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${LOW_COUNT:=0}"
+        COVERAGE_PERCENT=$(grep -o '"coverage_percent": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${COVERAGE_PERCENT:=0}"
+
+        # Test-First violations
+        TEST_FIRST_HIGH=$(grep -o '"high_risk": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${TEST_FIRST_HIGH:=0}"
+        TEST_FIRST_MEDIUM=$(grep -o '"medium_risk": [0-9]*' "$LATEST_ANALYSIS" | head -1 | grep -o '[0-9]*' || true)
+        : "${TEST_FIRST_MEDIUM:=0}"
+
+        # Check for trend data (multiple analyses)
+        ANALYSIS_COUNT=$(find "$ANALYSIS_DIR" -name "analysis-*.md" -type f | wc -l)
+
+        # Load trend data if available
+        if [[ $ANALYSIS_COUNT -gt 1 ]]; then
+            # Extract trend table from latest analysis
+            TREND_TABLE=$(sed -n '/## Quality Trend/,/^\*\*Improvement\*\*/p' "$LATEST_ANALYSIS" | head -n -1)
+        else
+            TREND_TABLE=""
+        fi
+    else
+        ANALYSIS_DATE="N/A"
+        CRITICAL_COUNT="N/A"
+        HIGH_COUNT="N/A"
+        MEDIUM_COUNT="N/A"
+        LOW_COUNT="N/A"
+        COVERAGE_PERCENT="N/A"
+        TEST_FIRST_HIGH="N/A"
+        TEST_FIRST_MEDIUM="N/A"
+        TREND_TABLE=""
+    fi
+else
+    ANALYSIS_DATE="No analysis run"
+    CRITICAL_COUNT="N/A"
+    HIGH_COUNT="N/A"
+    MEDIUM_COUNT="N/A"
+    LOW_COUNT="N/A"
+    COVERAGE_PERCENT="N/A"
+    TEST_FIRST_HIGH="N/A"
+    TEST_FIRST_MEDIUM="N/A"
+    TREND_TABLE=""
+fi
+```
+
+**Step 6.7: Derived dashboard metrics** 🆕 (Overall Completion, artifact timestamps, recommended actions):
+
+```bash
+PLAN_FILE="specs/plan.md"
+
+# --- Overall Completion ---
+# Per Implementation Notes formula: percentage of items with planStatus = processed
+# AND tasksStatus = processed. Grounded format: every US/FR carries exactly one
+# `**Lifecycle**:` line (indented bold line under its item), so the denominator is
+# the count of Lifecycle lines and the numerator those carrying both plan:processed
+# and tasks:processed.
+LIFECYCLE_TOTAL=$(grep -cE '\*\*Lifecycle\*\*:' "$FEATURE_SPEC" 2>/dev/null || true)
+: "${LIFECYCLE_TOTAL:=0}"
+LIFECYCLE_DONE=$(grep -cE '\*\*Lifecycle\*\*:.*\[plan:processed\]\[tasks:processed\]' "$FEATURE_SPEC" 2>/dev/null || true)
+: "${LIFECYCLE_DONE:=0}"
+if [[ $LIFECYCLE_TOTAL -gt 0 ]]; then
+    OVERALL_PERCENT=$((LIFECYCLE_DONE * 100 / LIFECYCLE_TOTAL))
+else
+    OVERALL_PERCENT=0
+fi
+
+# --- Per-stage counts for the Lifecycle Summary table (`T231` / `ISS-204` / user ruling 2026-09-20) ---
+# ⚠️ **Read as STATE, from the one artifact that carries the fields** — same discipline as Rule 1
+# below (`T246`): `spec.md` is the only carrier, and the anchor is the field's own line start, so
+# prose that merely *mentions* a marker is not counted.
+LIFECYCLE_FIELD_STAGE='^[[:space:]]*\*\*Lifecycle\*\*:'
+TOTAL=$LIFECYCLE_TOTAL
+PLAN_PROCESSED=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[plan:processed\]"  "$FEATURE_SPEC" 2>/dev/null || true)
+: "${PLAN_PROCESSED:=0}"
+PLAN_PENDING=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[plan:(create|update|delete)\]" "$FEATURE_SPEC" 2>/dev/null || true)
+: "${PLAN_PENDING:=0}"
+TASK_PROCESSED=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[tasks:processed\]"  "$FEATURE_SPEC" 2>/dev/null || true)
+: "${TASK_PROCESSED:=0}"
+TASK_PENDING=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[tasks:(create|update|delete)\]" "$FEATURE_SPEC" 2>/dev/null || true)
+: "${TASK_PENDING:=0}"
+pct() { [ "${2:-0}" -gt 0 ] && echo $(( $1 * 100 / $2 )) || echo 0; }
+PLAN_PCT=$(pct "$PLAN_PROCESSED" "$TOTAL")
+TASK_PCT=$(pct "$TASK_PROCESSED" "$TOTAL")
+# ⚠️ **The Spec row has no processed/pending pair, and that is a conclusion, not a gap** (`T246`):
+# `[specify:…]` records **how an item entered** the spec (`FR-046`), and its terminal value
+# `[specify:processed]` **has no writer anywhere in the toolchain** ⇒ that segment cannot express
+# "done" or "outstanding", so the row renders `N/A` with this reason. **Do not synthesise a number
+# for it** — a fabricated count reads exactly like a real one.
+SPEC_PROCESSED="N/A"; SPEC_PENDING="N/A"; SPEC_PCT="N/A"
+NEW_ITEMS_LIST=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[specify:create\]" "$FEATURE_SPEC" 2>/dev/null || true)
+MODIFIED_ITEMS_LIST=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[specify:update\]" "$FEATURE_SPEC" 2>/dev/null || true)
+DELETED_ITEMS_LIST=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*\[specify:delete\]" "$FEATURE_SPEC" 2>/dev/null || true)
+DEPRECATED_ITEMS_LIST=$(grep -cE "${LIFECYCLE_FIELD_STAGE}.*deprecated\]" "$FEATURE_SPEC" 2>/dev/null || true)
+: "${NEW_ITEMS_LIST:=0}";  : "${MODIFIED_ITEMS_LIST:=0}"
+: "${DELETED_ITEMS_LIST:=0}"; : "${DEPRECATED_ITEMS_LIST:=0}"
+
+# --- Last artifact update timestamps (Recent Activity) ---
+# Portable mtime: BSD `stat -f` first, fall back to GNU `stat -c`
+last_mtime() {
+  local f="$1"
+  if [[ ! -f "$f" ]]; then
+    echo "N/A"; return
+  fi
+  local ts
+  # ⚠️ **单行**兜底链（BSD 优先、GNU 兜底）—— 跨行的 if/else 不是兜底链、不豁免。
+  ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$f" 2>/dev/null || stat -c %y "$f" 2>/dev/null | cut -d'.' -f1)
+  echo "${ts:-N/A}"
+}
+LAST_SPEC_UPDATE=$(last_mtime "$FEATURE_SPEC")
+LAST_PLAN_UPDATE=$(last_mtime "$PLAN_FILE")
+LAST_TASKS_UPDATE=$(last_mtime "$TASKS_FILE")
+
+# --- Recommended Actions (Next Steps) ---
+# Rule table: every matching rule contributes one action line; none match → "No pending actions".
+RECOMMENDED_ACTIONS=""
+
+# Rule 1: pending Lifecycle items — read as STATE, from the ONE artifact that carries the fields
+# ⚠️ **Three corrections, one finding** (`T246` / `ISS-219`, 形态 4 的活实例). The rule used to
+# count markers and got **73 on a fully-settled project**; the acceptance criterion it must meet
+# is `spec.md` → US9 scenario 6 (a settled project MUST NOT be reported as pending, and a
+# genuinely-unprocessed item MUST be).
+#   ① **The fields live in `FEATURE_SPEC` only** — the three segments sit on the spec items.
+#      Measured: `spec.md` 73 `**Lifecycle**:` lines · `plan.md` **0** · `tasks.md` 3 (and those
+#      three are PROSE inside task descriptions, not fields). The old form read each segment out
+#      of a different file ⇒ `PLAN_PENDING_COUNT` was **structurally 0** — it read a file that
+#      carries no field at all, and a zero from an empty scan is indistinguishable from a real 0.
+#   ② **Line-start anchor** (`^[[:space:]]*\*\*Lifecycle\*\*:`). Without it the scan counts any
+#      prose that *mentions* the field — and this repository has such prose in both files (a task
+#      description quoting a defect, an acceptance scenario citing an example). A mention is not
+#      an item.
+#   ③ **The `specify` segment is NOT a pending signal** — `FR-046`: "标记记录的是「一个条目怎么
+#      进来的」，不是「它现在在哪」". `[specify:create|update|delete]` records *entry mode*, so a
+#      predicate over it matches **every** item (measured 73/73), and its terminal value
+#      `[specify:processed]` has **no writer anywhere in the tree** ⇒ that segment cannot express
+#      "pending". `plan` / `tasks` CAN: their terminal values are written by `/specpro-plan` and
+#      `/specpro-tasks` respectively. ⚠️ **Do not restore a `SPEC_PENDING_COUNT` term** — a count
+#      over entry mode is not a count of anything owed.
+LIFECYCLE_FIELD='^[[:space:]]*\*\*Lifecycle\*\*:'
+PLAN_PENDING_COUNT=$(grep -cE "${LIFECYCLE_FIELD}.*\[plan:(create|update|delete)\]" "$FEATURE_SPEC" 2>/dev/null || true)
+: "${PLAN_PENDING_COUNT:=0}"
+TASKS_PENDING_COUNT=$(grep -cE "${LIFECYCLE_FIELD}.*\[tasks:(create|update|delete)\]" "$FEATURE_SPEC" 2>/dev/null || true)
+: "${TASKS_PENDING_COUNT:=0}"
+LIFECYCLE_PENDING=$((PLAN_PENDING_COUNT + TASKS_PENDING_COUNT))
+if [[ $LIFECYCLE_PENDING -gt 0 ]]; then
+  RECOMMENDED_ACTIONS+="- Run \`/specpro-plan\` or \`/specpro-tasks\` to process $LIFECYCLE_PENDING pending Lifecycle item(s)
+"
+fi
+
+# Rule 2: open quality checklist issues
+if [[ ${FAIL_COUNT:-0} -gt 0 ]]; then
+  RECOMMENDED_ACTIONS+="- Resolve ${FAIL_COUNT} checklist issue(s) via \`/specpro-qc\`
+"
+fi
+
+# Rule 3: no high-level test plan
+if [[ "$TEST_TASKS_EXISTS" != "true" ]]; then
+  RECOMMENDED_ACTIONS+="- Run \`/specpro-test-plan\` to build the coverage matrix
+"
+fi
+
+# Rule 4: analysis missing or stale (> 30 days). POSIX `-mtime` keeps this portable.
+ANALYSIS_RECENT=""
+if [[ -d "$ANALYSIS_DIR" ]]; then
+  ANALYSIS_RECENT=$(find "$ANALYSIS_DIR" -name "analysis-*.md" -mtime -30 2>/dev/null | head -1)
+fi
+if [[ -z "$ANALYSIS_RECENT" ]]; then
+  RECOMMENDED_ACTIONS+="- Run \`/specpro-analyze\` (last analysis missing or older than 30 days)
+"
+fi
+
+[[ -z "$RECOMMENDED_ACTIONS" ]] && RECOMMENDED_ACTIONS="- No pending actions"
+```
+
+**Step 7: Generate dashboard**:
+
+```markdown
+## 📊 Project Status Dashboard
+
+**Specification**: Version $SPEC_VERSION
+**Last Updated**: $(date +%Y-%m-%d)
+**Working Directory**: $(pwd)
+
+---
+
+### 🏗️ Feature Registry Overview (FR-018 · v0.23)
+
+读取 `specs/features.md`(登记文件,feature 机制唯一登记载体)。**每个 feature 的进度由它自己的产物推导**(`specs/fNNN-简称/` 内 spec/plan/tasks 的勾选态),不读母规格链:
+
+```text
+Feature Registry: N feature(s)
+  f001 <name>      [active]     spec ✓ plan ✓ tasks ▓▓▓░ 12/18
+  f002 <name>      [delivered]  spec ✓ plan ✓ tasks ✓ 交付完成
+  ⚠️ 缺件: f003 缺 plan.md
+  ⚠️ 孤儿: specs/f004-x/ 目录存在但未登记
+  ⚠️ 失联: 登记含 f005 但目录不存在
+```
+
+**三类一致性发现**(FR-018,双向): ① **在册无目录** · ② **有目录未在册** · ③ **缺件**(缺 spec/plan/tasks 任一项)。任一发现 MUST 列出并标注,不静默。
+
+---
+
+### 🎯 Overall Progress
+
+┌─────────────────────────────────────────────────────────────────┐
+│ Specification: Example Plugin Architecture                        │
+│ Version: $SPEC_VERSION                                           │
+│ User Stories: $US_COUNT                                         │
+│ Functional Requirements: $FR_COUNT                               │
+└─────────────────────────────────────────────────────────────────┘
+
+**Overall Completion**: $OVERALL_PERCENT%
+
+---
+
+### 📈 Lifecycle Summary
+
+┌─────────────┬──────────┬──────────────┬──────────────┬──────────────┐
+│ Stage       │ Total    │ Processed    │ Pending      │ Percentage   │
+├─────────────┼──────────┼──────────────┼──────────────┼──────────────┤
+│ **Spec**    │ $TOTAL   │ $SPEC_PROCESSED │ $SPEC_PENDING │ $SPEC_PCT%   │
+│ **Plan**    │ $TOTAL   │ $PLAN_PROCESSED │ $PLAN_PENDING │ $PLAN_PCT%   │
+│ **Tasks**   │ $TOTAL   │ $TASK_PROCESSED │ $TASK_PENDING │ $TASK_PCT%   │
+└─────────────┴──────────┴──────────────┴──────────────┴──────────────┘
+
+**Legend**:
+- **Total**: Number of items (User Stories + FRs)
+- **Processed**: Items with specifyStatus/planStatus/tasksStatus = "processed"
+- **Pending**: Items with specifyStatus/planStatus/tasksStatus = "create" or "update" or "delete"
+- **Percentage**: Processed / Total * 100
+
+---
+
+### 🔀 Modified Items (Need Re-processing)
+
+**New Items** (specifyStatus = create, planStatus/tasksStatus = create):
+$NEW_ITEMS_LIST
+
+**Modified Items** (specifyStatus/planStatus/tasksStatus = update):
+$MODIFIED_ITEMS_LIST
+
+**Deleted Items** (specifyStatus/planStatus/tasksStatus = delete):
+$DELETED_ITEMS_LIST
+
+**Action Required**:
+```
+```
+$specpro.plan    # Re-plan modified items
+$specpro.tasks   # Re-breakdown modified items
+```
+
+---
+
+### ⚠️ Deprecated Items
+
+$DEPRECATED_ITEMS_LIST
+
+---
+
+### ✅ Quality Status
+
+**Quality** (from `specs/checklists/requirements.md`): $QUALITY_STATUS — $QUALITY_SCORE passed
+
+**Issues**:
+- ✗ Failed: $FAIL_COUNT  (清单的 `**Failed**` 字段；⚠️ **没有 warning 档** —— 模板只有三种取值)
+
+**Defect status** (FR-050 — see the wording rule below the dashboard sections): [**无已知缺陷** —
+<N> shapes all exercised, 0 hits | <N> known instance(s) | ⚠️ **coverage incomplete** — <M> shape(s)
+could not be exercised at all, so that part is **unproven, NOT clean**]
+⚠️ The counts above measure the **artifacts**; this line is the only place the **tool's** defect status
+is stated, and it may be written as 「无已知缺陷」 **only** with the coverage declaration attached.
+
+**Quality Checklist**: specs/checklists/requirements.md *(Produced by /specpro-qc)*
+
+---
+
+**缺陷状态的表述规则** ⚠️ [FR-050 —— 本段在两个命令里**逐字相同**（`specpro.status.md` · `specpro.analyze.md`）；改一处 MUST 同轮改另一处，否则它就是它所防的那种分叉（形态 3）]
+
+**任何「有没有缺陷」的陈述 MUST 表述为「无已知缺陷」，MUST NOT 表述为「无缺陷」。** 两者是不同的断言，只有前者可核验：
+
+| 表述 | 它声称什么 | 可否核验 |
+|---|---|---|
+| **无已知缺陷** | **登记表中每一个形态都已对它跑过检出，且已知实例为零** | ✅ 可核验 —— 重跑检出即得结论 |
+| **无缺陷** | 一个关于**未被检视的那一部分**的断言 | ❌ 不可核验 —— 没有人对它做过测量 |
+
+**定义即判据**：只有当**每一个形态都已被检出过**（没有一个落 `⊘`）**且命中数为零**时，才可以表述为「无已知缺陷」；否则 MUST 写出未检视的那部分。
+
+⚠️ **MUST 随附覆盖声明**：任何缺陷状态陈述 MUST 声明**所覆盖的范围** —— 哪些形态检出过、哪些**没能检出**（`⊘`）。⚠️ **「没有提到」与「没有欠账」是两句不同的话，而前者与「忘了看」无从区分**（`FR-036` 对覆盖主张施加的是同一条纪律：**声称通过而基线未覆盖，不构成通过**）。
+
+⚠️ **工具侧报告用英文，同一断言照此对应**：`no known instance` ✅ / `no defects` · `defect-free` ❌。两个形态说的是**同一件事**，只在语言上不同 —— 若只钉住中文那一侧，英文报告会**照旧声称「无缺陷」而没有任何东西报错**（形态 3）。
+
+**机制（可复跑的形态）**：`scripts/bash/verify-shapes.sh`（PowerShell 对等：`scripts/powershell/verify-shapes.ps1`）就是这条判据的载体 —— 收尾报告给出 `N hit`（已知实例数）与 `M not executable`（没跑起来的组数）。**命中数不为零 ⇒ 不得表述为「无已知缺陷」；有 `⊘` ⇒ MUST 连带声明那一部分未证实，而不是干净。**
+
+### 🔍 Cross-Artifact Analysis 🆕
+
+**Last Analysis**: $ANALYSIS_DATE
+
+**Issue Summary**:
+- 🔴 CRITICAL: $CRITICAL_COUNT
+- 🟠 HIGH: $HIGH_COUNT
+- 🟡 MEDIUM: $MEDIUM_COUNT
+- 🟢 LOW: $LOW_COUNT
+
+**Coverage**: $COVERAGE_PERCENT%
+
+**Test-First Compliance** (Constitution Article IV):
+- High-Risk Violations: $TEST_FIRST_HIGH
+- Medium-Risk Violations: $TEST_FIRST_MEDIUM
+
+**Analysis Directory**: specs/analysis/
+
+**Actions**:
+```bash
+# Run new analysis
+/specpro-analyze
+
+# Save for trend tracking
+/specpro-analyze --persist
+
+# Quick summary
+/specpro-analyze --summary
+```
+
+**Quality Trend** 🆕 (if multiple analyses exist):
+$TREND_TABLE
+
+---
+
+### 📄 Contract Coverage
+
+**Total Contracts**: $TOTAL_CONTRACTS
+
+**Contracts by Priority** (generated counts):
+┌──────────┬───────────────┐
+│ Priority │ Generated     │
+├──────────┼───────────────┤
+│ P1       │ $P1_CONTRACTS │
+│ P2       │ $P2_CONTRACTS │
+│ P3       │ $P3_CONTRACTS │
+└──────────┴───────────────┘
+
+> Required baseline not defined — add a contract plan (required counts per priority)
+> to plan.md to enable coverage % tracking.
+
+**Contract Directory**: specs/contracts/
+
+---
+
+### ✅ Task Progress
+
+**Total Tasks**: $TOTAL_TASKS
+**Completed**: $COMPLETED_TASKS
+**Remaining**: $((TOTAL_TASKS - COMPLETED_TASKS))
+
+**Task Completion**: $TASK_PERCENT%
+
+```text
+[████████████████████████████░░░░░░░] $TASK_PERCENT%
+```
+
+**Tasks File**: specs/tasks.md
+
+---
+
+### 🧪 Test Task Progress 🆕
+
+<!-- Render this section only when specs/test-tasks.md exists.
+     If TEST_TASKS_EXISTS=false, show:
+     "> ℹ️ No high-level test plan found (specs/test-tasks.md).
+     > Run `/specpro-test-plan` to generate the coverage matrix and integration / E2E test tasks."
+     and skip the stats below. -->
+
+**Total Test Tasks**: $TEST_TASK_TOTAL (INF + IT + CE + AE)
+**Completed**: $COMPLETED_TEST_TASKS
+**Remaining**: $REMAINING_TEST_TASKS
+<!-- ⚠️ 变量名与其含义（`T174`）：本行此前读的是 `TOTAL_TEST_TASKS`，而它的定义**只数 `- [ ]`**
+     ⇒ 它装的是**剩余**，不是总量（总量是 `TEST_TASK_TOTAL = 剩余 + 已完成`）。
+     两个 `**Remaining**` 的算法本来就是同一个意思（`$((总量 - 已完成))` ≡ 剩余），
+     错的是**名字**：名字反了 ⇒ 下一个读的人会把它当总量用。已改名为 `REMAINING_TEST_TASKS`。 -->
+
+**Test Task Completion**: $TEST_TASK_PERCENT%
+
+```text
+[████████████████████████░░░░░░░░░░░] $TEST_TASK_PERCENT%
+```
+
+**Coverage Matrix** (specs/test-tasks.md):
+- FRs tracked: $MATRIX_FR_TOTAL | **Active** (execution-tracked): $MATRIX_FR_ACTIVE
+- Execution states: not-started $MATRIX_FR_NOT_STARTED | in-progress $MATRIX_FR_IN_PROGRESS | completed $MATRIX_FR_COMPLETED
+- Planning verdicts: pending-impl $MATRIX_FR_PENDING_IMPL | manual $MATRIX_FR_MANUAL | not-applicable $MATRIX_FR_NOT_APPLICABLE | deprecated $MATRIX_FR_DEPRECATED
+
+**Test Tasks File**: specs/test-tasks.md
+**Planned by**: /specpro-test-plan | **Executed by**: /specpro-test-implement
+
+<!-- Lightweight alerts (S5): render ONLY the lines whose condition holds; skip both if none. -->
+<!-- If S5_WARN_PENDING_IMPL == true:
+⚠️ $MATRIX_FR_PENDING_IMPL FRs awaiting implementation (pending-impl) — consider an incremental /specpro-test-plan pass -->
+<!-- If S5_WARN_LAGGING == true:
+⚠️ Test execution lagging (last run $TESTPLAN_LAST_RUN) — re-run /specpro-test-implement to advance open FRs -->
+
+---
+
+### 📅 Recent Activity
+
+**Last Plan Update**: $LAST_PLAN_UPDATE
+**Last Tasks Update**: $LAST_TASKS_UPDATE
+**Last Spec Update**: $LAST_SPEC_UPDATE
+
+---
+
+### 🚀 Next Steps
+
+Based on current status:
+
+**Recommended Actions**:
+$RECOMMENDED_ACTIONS
+
+---
+
+## Dashboard Legend
+
+**Status Indicators**:
+- ✅ **Complete**: All items processed
+- ⚠️ **In Progress**: Some items pending
+- ❌ **Blocking**: Issues need attention
+- 📊 **On Track**: Good progress
+
+**Lifecycle Status Codes** (NEW - create/update/delete/processed/deprecated):
+- **create**: New item, never processed
+- **update**: Item changed since last processing (needs re-processing)
+- **delete**: Item marked for deletion (will be removed)
+- **processed**: Item successfully processed at this stage
+- **deprecated**: Item removed from active development
+
+**Lifecycle Stage Mapping**:
+- **[specify]**: Specification stage (spec.md status)
+- **[plan]**: Planning stage (plan.md status)
+- **[tasks]**: Implementation stage (tasks.md status)
+
+⚠️ **The example must be a value combination that can actually occur** (`T247` / `ISS-220`). This used to read `[specify:processed][plan:update][tasks:create]` — `processed` is **never written to the `specify` segment by anything** (measured: 0 occurrences across the tree, and the segments that DO reach `processed` are `plan` and `tasks`, written by `/specpro-plan` and `/specpro-tasks`). ⇒ The example taught a shape the toolchain cannot produce, and a reader copying it would write a field nobody maintains.
+
+**Example**: `**Lifecycle**: [specify:update][plan:processed][tasks:processed]`
+- Specification: update (item content changed since it entered the spec)
+- Planning: processed (design has caught up with that change)
+- Tasks: processed (task breakdown has caught up too)
+
+---
+
+**Generated**: $(date)
+**Command**: /specpro-status
+```
+
+**Step 8: Display dashboard**:
+- Output the formatted dashboard
+- Use markdown tables for structured data
+- Use progress bars for visual completion
+- Use emoji for quick scanning
+
+---
+
+## Examples
+
+### Example 1: New Project (No Processing)
+
+```markdown
+## 📊 Project Status Dashboard
+
+**Specification**: Version 0.1
+**Last Updated**: 2026-02-07
+
+### 🎯 Overall Progress
+**Overall Completion**: 0%
+
+### 📈 Lifecycle Summary
+┌─────────────┬──────────┬──────────────┬──────────────┐
+│ Stage       │ Total    │ Processed    │ Pending      │
+├─────────────┼──────────┼──────────────┼──────────────┤
+│ specify     │ 161      │ 0            │ 161 (100%)   │
+│ plan        │ 161      │ 0            │ 161 (100%)   │
+│ tasks       │ 161      │ 0            │ 161 (100%)   │
+└─────────────┴──────────┴──────────────┴──────────────┘
+
+### 🔀 Modified Items (Need Re-processing)
+**New Items**: 161 (all items - specifyStatus=create)
+
+**Recommended Actions**:
+1. Run /specpro-plan to start planning
+2. Run /specpro-tasks after planning complete
+```
+
+### Example 2: In Progress Project
+
+```markdown
+## 📊 Project Status Dashboard
+
+**Specification**: Version 1.1.1
+**Last Updated**: 2026-02-07
+
+### 🎯 Overall Progress
+**Overall Completion**: 97%
+
+### 📈 Lifecycle Summary
+┌─────────────┬──────────┬──────────────┬──────────────┐
+│ Stage       │ Total    │ Processed    │ Pending      │
+├─────────────┼──────────┼──────────────┼──────────────┤
+│ specify     │ 161      │ 161          │ 0 (0%)       │
+│ plan        │ 161      │ 157          │ 4 (3%)       │
+│ tasks       │ 161      │ 157          │ 4 (3%)       │
+└─────────────┴──────────┴──────────────┴──────────────┘
+
+### 🔀 Modified Items (Need Re-processing)
+**New Items** (specifyStatus=create):
+- FR-xxxA: [encoder implementation]
+- FR-xxxB: [protocol extensions]
+- FR-xxxC: [automatic sub-encoding]
+- FR-xxxD: [performance tuning]
+
+**Modified Items** (specifyStatus=update):
+None
+
+**Deleted Items** (specifyStatus=delete):
+None
+
+### 🚀 Next Steps
+**Recommended**:
+1. Run /specpro-plan to process 4 new items (specifyStatus=create)
+2. Run /specpro-tasks to regenerate tasks
+3. Continue implementation
+```
+
+---
+
+## Use Cases
+
+1. **Quick Status Check**: Get instant overview of project progress
+2. **Before Planning**: See what needs to be planned
+3. **Before Implementation**: Verify all prerequisites are met
+4. **Team Meetings**: Share project status with team
+5. **Progress Tracking**: Monitor completion over time
+
+---
+
+## Integration with Other Commands
+
+- **/specpro-status** → Display dashboard (this command)
+- **/specpro-plan** → Update planStatus, see changes in dashboard
+- **/specpro-tasks** → Update tasksStatus, see changes in dashboard
+- **/specpro-specify** → Update all Lifecycle fields (specify/plan/tasks), see changes in dashboard
+- **/specpro-analyze** → Run cross-artifact analysis, populate analysis section in dashboard 🆕
+
+---
+
+## Implementation Notes
+
+**Parsing Lifecycle Fields** (NEW format):
+- Use regex to extract: `**Lifecycle**: \[specify:(.*?)\]\[plan:(.*?)\]\[tasks:(.*?)\]`
+  ⚠️ **组间无空格**（`T174`）：本节此前写的是 `\] \[` —— 要求三组之间**有空格**，而 `templates/spec-template.md`
+  与 `commands/specpro.specify.md` 写入的是**紧邻**形式 `[specify:create][plan:create][tasks:create]` ⇒ 逐字执行时
+  这个正则**在本仓库的全部产物上都匹配不到**，而匹配不到与「该项没有 Lifecycle 字段」同形。
+  ⚠️ **上面那对取值于 2026-09-20 更正**（`T243` / `ISS-216`）：本节此前把"紧邻形式"举例为**三个段中后两个为空**的写法，
+  而那是 **`T143` 修复之前**的模板形态 —— 实测 `commands/specpro.specify.md` 写的是三个段**都取 `create`**（**6 处**），
+  空值 **0 处**。**该注的观察（"组间无空格"）自始成立，错的只是它引的取值。**
+  ⚠️ **此处刻意不把那三个空段照抄出来** —— `templates/spec-template.md` → `## Change Summary` 的规则说得很直接：
+  「**do not quote what was removed**, not even as a quotation in backticks —— a value sitting in prose is
+  **indistinguishable from a real Lifecycle field to any mechanical reader** (a `grep`, a leg count, a
+  propagation scan)」。**本轮第一版正是照抄了它**，随后被自查按同一条规则改掉。
+- Group 1: specifyStatus (create | update | delete | processed | deprecated)
+- Group 2: planStatus (create | update | delete | processed | deprecated)
+- Group 3: tasksStatus (create | update | delete | processed | deprecated)
+
+⚠️ IMPORTANT: Single system-wide vocabulary — create | update | delete | processed | deprecated.
+No legacy verb labels exist anywhere in the toolchain (create is the only "new item" tag,
+update the only "changed item" tag): the Lifecycle field is the only status carrier, and
+Change Summary entries use the same tags (changed items only).
+- **create**: New item
+- **update**: Modified item (needs re-processing downstream)
+- **delete**: Item to be deleted
+- **processed**: Successfully processed at this stage
+- **deprecated**: Removed from development
+
+**Color Coding** (for terminal output):
+- ✅ Green: Complete, on track
+- ⚠️ Yellow: Warnings, in progress
+- ❌ Red: Blocking issues
+- 📊 Blue: Information
+
+**Performance**:
+- Dashboard generation: <1 second
+- Minimal I/O (read 4-5 files)
+- No external dependencies