specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.qc.md

@@ -0,0 +1,1489 @@
+---
+description: Validate specification quality against the checklist's quality criteria. Rebuild the checklist, route every non-passing item to the [specify] ledger queue, and stop. No repair, no loop, no cache.
+writes:
+  # This command's write surface: only what it produces AS THE PRODUCER of that
+  # (artifact, unit) pair. A write this command makes on a non-producer path is a
+  # boundary violation by definition (FR-051) and MUST NOT be declared here.
+  # The full ownership map is the UNION of every command's writes: block.
+  #
+  # ⚠️ **EXACTLY TWO — that IS the ruling, not a summary of it** (FR-058, user ruling
+  # 2026-09-19, `ISS-186`). This command produces its checklist, and it routes its
+  # findings. It does **NOT** write `spec.md` (the repair belongs to the spec's
+  # **producer**, `/specpro-specify`), and does **NOT** write the clarification artifact —
+  # that one belongs to `/specpro-specify` too, and holds questions the USER must answer.
+  # ⇒ There is no `--auto` path, no repair door, and no third artifact. A future
+  # reader who wants to add one here is re-introducing exactly what was removed.
+  - artifact: specs/checklists/requirements.md
+    unit: "whole file, rebuilt from the template on EVERY run — no history, no cache (FR-060)"
+  - artifact: specs/implement_issues.md
+    unit: "the [specify] section -> appended ISS-NNN entries for non-passing checks"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Arguments format: `--scope=[full|incremental] [--quiet]`
+
+**Rerun safety — read-only over the artifacts it inspects, and that is now unconditional** ⚠️ [settled 2026-09-13; narrowed to unconditional by the 2026-09-19 ruling]:
+
+This command **inspects** `spec.md`, `plan.md`, `tasks.md` and any other artifact under analysis, and it **modifies none of them** — there is no mode that widens this. The shared rerun rule (*detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent*) applies to the commands that write those artifacts; this command never triggers its third clause.
+
+**Two writes happen on EVERY run, and the list is now EXACTLY two** (`FR-058`):
+
+| Write | Why it is not an analyzed artifact |
+|-------|-----------------------------------|
+| `specs/checklists/requirements.md` — **rebuilt from the template on every run** | This command's **own output**: the verdict of *this* run. ⚠️ **Rebuilt, not updated** — see `FR-060`. |
+| `specs/implement_issues.md` — the `[specify]` section gains one entry per **non-passing** check | **Routing, not repair.** A `✗` that lives only in the checklist **has no consumer**, and is indistinguishable from a finding never reported at all (`FR-023`). |
+
+⚠️ **What this command deliberately does NOT write, and why it must stay that way** (user ruling 2026-09-19, `ISS-186` — this **reverses the direction** two earlier rounds were heading in):
+
+- **NOT `spec.md`.** Repairing the spec belongs to the spec's **producer**, `/specpro-specify`. ⚠️ Earlier rounds tried to make "qc repairs another command's artifact" *authorizable* through a caller-supplied owner parameter (`ISS-38` / `ISS-163` / `T203`). **That direction was rejected**: a command that repairs what it judged has spent the verdict (**Principle III**), and no caller-side authorisation repairs that.
+- **NOT the clarification artifact.** It belongs to `/specpro-specify` — it holds questions **the user** must answer. A criterion failure is not necessarily a question for the user; it is a **finding for the spec's producer**.
+
+⇒ **Hence no repair mode, no authorisation parameter, no repair door, and no second path into the write surface.** A defect this command cannot express as a ledger entry belongs in its **report**, not in someone else's artifact.
+
+> **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
+
+> ⚠️ **执行顺序 ≠ 文档顺序 —— 而这是一条声明，不是一条约定**（`T226` / `ISS-194`）
+>
+> 本文档的节次是**按内容组织的**：`## Run`（主流程）出现在它所调用的那些函数行**之前**。
+> ⇒ 执行时 MUST：**先加载全部函数定义**（`## run_qc_check()` · `## PHASE 3` 下的各 `check_*` ·
+> `## register_findings()` · `## Helper Functions`），**然后执行 `## Run`，再按需执行其后各节**。
+>
+> ⚠️ **在写下这一条之前，本文档对执行顺序一言不发** —— 于是两种读法都成立、且都不报错：
+> 逐段顺序执行会在定义之前调用 `run_qc_check` 与 `register_findings`（`command not found`），
+> 而"主流程排在最前"读起来**同样像一个有意的布局**。**一个可以被读成两种意思的节次，
+> 对执行者就是没有节次。**
+>
+> **为什么写死顺序而不是调序**：`Initialize` 之后紧跟主流程是**可读性上的选择**（读者先看到它做什么），
+> 调序要动整份文档的节次；而**顺序一旦写下来，两种读法就只剩一种**。
+
+### Parse Arguments
+
+```bash
+# Parse arguments
+# ⚠️ **There is no repair mode and no owner-authorisation parameter any more** (FR-058, 2026-09-19 ruling).
+# They were not deprecated — they were REMOVED, along with the whole repair path they
+# fed. Adding either back means re-introducing "qc repairs another command's artifact",
+# which the ruling rejected on Principle III grounds (see the note above the table).
+SCOPE="full"
+SHOW_PROGRESS=true
+
+# ⚠️ `$ARGUMENTS` is the command framework's **caller-supplied placeholder** (the user's raw
+# input, substituted before this runs). It is declared with an in-place assignment so the
+# loop below reads a DEFINED variable when the snippet is copied or run on its own — which
+# is the failure FR-034 exists to prevent (a snippet that silently iterates over nothing).
+# ⚠️ Not a checker-pleasing no-op: the declaration is the variable's contract, and the
+# `${VAR:=}` form is the contract's own exempt spelling for exactly this kind of input.
+: "${ARGUMENTS:=}"
+for arg in $ARGUMENTS; do
+  case $arg in
+    --scope=full)
+      SCOPE="full"
+      ;;
+    --scope=incremental)
+      SCOPE="incremental"
+      ;;
+    --quiet)
+      SHOW_PROGRESS=false
+      ;;
+  esac
+done
+```
+
+### Initialize
+
+```bash
+# Load paths — read-only resolver. Two things this must NOT do:
+#  · `source` a JSON-emitting script: `source` cannot consume JSON, and the file it
+#    named did not exist — `$SPECS_DIR` came out EMPTY and the five paths below were
+#    silently built as "/spec.md", "/checklists/requirements.md", … A checker that
+#    resolves its own paths wrongly reports against the wrong place, or against nothing.
+#  · call `setup-plan.sh --json` instead: it also reports SPECS_DIR, but it CREATES
+#    plan.md from the template when absent — a side effect a checker must not have.
+SPECS_DIR=$(.specpro/scripts/bash/check-prerequisites.sh --json --paths-only 2>/dev/null \
+  | sed -n 's/.*"FEATURE_DIR":"\([^"]*\)".*/\1/p')
+if [ -z "$SPECS_DIR" ]; then
+  echo "❌ ERROR: could not resolve the specs directory." >&2
+  echo "   Fix: run this command from the repository root; if it still fails, run /specpro-specify first." >&2
+  exit 1
+fi
+FEATURE_SPEC="$SPECS_DIR/spec.md"
+REQUIREMENTS_CHECKLIST="$SPECS_DIR/checklists/requirements.md"
+REQUIREMENTS_TEMPLATE=".specpro/templates/requirements-template.md"
+SPEC_TEMPLATE=".specpro/templates/spec-template.md"
+# ⚠️ A NEW path for this command (FR-059): the `[specify]` section is this command's
+# **routing target**. A non-passing check becomes an entry a named consumer reads.
+IMPL_LEDGER="$SPECS_DIR/implement_issues.md"
+
+# Initialize QC state.
+# ⚠️ **Every variable here is written AND read inside one single pass.** The iteration
+# counter, the per-issue consecutive-failure state, the cache and every guard's state are
+# GONE with the main loop (FR-060) — a control flow with no second iteration has no use
+# for them, and *state carried across runs* is exactly what the ruling removed.
+# ⚠️ **The criterion count belongs HERE, beside the other counters — not inside
+# `run_qc_check`** (`T226` / `ISS-194`). It used to be assigned inside that function's body,
+# while the report block **runs earlier in document order** and reads `$TOTAL_ITEMS` ⇒ the
+# summary printed `Checks run: ` with nothing after it. The three counters below were already
+# initialised here; this one was the exception, and **an exception in "where a counter is
+# initialised" is exactly what makes an ordering bug invisible** — four counters that look
+# alike, three of which happen to be correct.
+TOTAL_ITEMS=11   # was 12 until a Content-Quality criterion was retired (2026-09-19, T197)
+PASSED=0
+FAILED=0
+SKIPPED=0
+FAILED_ITEMS=()
+SKIPPED_ITEMS=()
+# "<CHECK_ID>\t<human-readable finding>" — one per non-passing check, built by the check
+# functions themselves via `record_finding`. The id alone cannot fill a ledger entry.
+FINDINGS=()
+# Ledger ids created by THIS run, so the report can name them.
+REGISTERED_IDS=()
+ALL_PASSED=false
+
+# 🆕 OPTIMIZATION: Detect incremental validation scope
+# Source of truth: the Lifecycle field (single vocabulary: create|update|delete|
+# processed|deprecated) on the line following each FR — Change Summary verbs are
+# NOT consulted. `-B1` grabs the FR line above each matching Lifecycle line;
+# sub-numbered FRs (e.g. FR-xxxA) are covered by `[A-E]?`.
+if [[ "$SCOPE" = "incremental" ]]; then
+    # Extract only new/modified FRs for incremental validation
+    ADDED_FRS=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:create\]' "$FEATURE_SPEC" 2>/dev/null | grep -oE "FR-[0-9]+[A-E]?" | sort -u)
+    MODIFIED_FRS=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:update\]' "$FEATURE_SPEC" 2>/dev/null | grep -oE "FR-[0-9]+[A-E]?" | sort -u)
+
+    # Build list of FRs to validate (only new/modified ones)
+    TARGET_FRS="$ADDED_FRS $MODIFIED_FRS"
+
+    if [[ -n "$TARGET_FRS" ]]; then
+        echo "📋 Incremental validation: $(echo "$ADDED_FRS" | wc -w) added, $(echo "$MODIFIED_FRS" | wc -w) modified"
+        echo "   Validating only affected FRs: $TARGET_FRS"
+    else
+        echo "ℹ️  No new/modified FRs detected, skipping incremental validation"
+        exit 0
+    fi
+else
+    echo "📋 Full validation: checking all FRs in spec.md"
+    TARGET_FRS="all"
+fi
+```
+
+---
+
+## Run: ONE PASS, then stop ⚠️ [FR-060 / FR-062]
+
+```bash
+# ⚠️ **This section used to be an unbounded repair loop, and there is none any more.** The
+# reason is not "simplification" — it is that **the old loop body had nothing left in
+# it that could change its input**.
+#
+# Exactly two actions in that body could alter `spec.md`: the `--auto` repairs inside
+# `run_qc_check`, and the hand-off to `/specpro-clarify` (whose call site said, in its
+# own comment, *"clarify will update spec.md"*). The 2026-09-19 ruling removed BOTH
+# (FR-058 / FR-062) ⇒ the input is fixed and every check is a pure function of it ⇒
+# **iteration 2 could only ever have reproduced iteration 1's verdict.**
+#
+# ⚠️ And the loop did not merely spin — it REPORTED. Its stagnation guard printed
+#     "The following issue persists after 3 repair attempts"
+# which is a statement about three repairs that **never happened**; the step it counted
+# said so itself (*"it does not re-run checks and it does not fix anything"*). Removing
+# the loop removes the lie.
+# ⚠️ The one-pass shape is also what makes `FR-060` (rebuild the checklist every run)
+# and `FR-061` (the verdict IS the per-item values) true **by construction**.
+
+# 1. Run every criterion exactly once, and rebuild the checklist from the results.
+run_qc_check
+
+# 2. Route what did not pass. ⚠️ **Before the verdict, not after.** The exit code must
+#    mean "the verdict is final AND every non-passing item has a consumer" — not "the
+#    verdict is final, and we hoped somebody would notice" (FR-059).
+register_findings
+
+# 3. Verdict and exit code.
+if [[ $FAILED -eq 0 ]]; then
+  ALL_PASSED=true
+fi
+
+echo ""
+if [[ "$ALL_PASSED" = "true" ]]; then
+  echo "✅ Quality Validation PASSED"
+else
+  echo "❌ Quality Validation FAILED"
+fi
+
+if [[ "$SHOW_PROGRESS" = "true" ]]; then
+  echo ""
+  echo "📊 Validation Summary:"
+  echo "   Checks run: $TOTAL_ITEMS"
+  echo "   Passed:     $PASSED"
+  echo "   Failed:     $FAILED"
+  if [[ ${SKIPPED:-0} -gt 0 ]]; then
+    echo "   Skipped:    $SKIPPED  (NOT counted as pass or fail — each ℹ️ line above says why)"
+  fi
+  echo "   Checklist:  $REQUIREMENTS_CHECKLIST  (rebuilt this run)"
+  if [[ ${#REGISTERED_IDS[@]} -gt 0 ]]; then
+    echo "   Routed to [specify]: ${REGISTERED_IDS[*]}"
+  fi
+fi
+
+# ⚠️ **The exit code is the gate's input** — the callers that block on this command read
+# it. It must mean exactly "no criterion failed", which is `FR-061`'s criterion: a
+# `⊘ Skipped` item is **neither** a pass nor a failure and MUST NOT tip this either way.
+if [[ "$ALL_PASSED" = "true" ]]; then
+  exit 0
+fi
+exit 1
+```
+
+---
+
+## run_qc_check(): Check all quality criteria (ENHANCED)
+
+```bash
+run_qc_check() {
+  # Read spec.md
+  SPEC_CONTENT=$(cat "$FEATURE_SPEC")
+
+  # Initialize counters — ⚠️ `TOTAL_ITEMS` is NOT here: it moved to `Initialize` (`T226`),
+  # because the report block reads it and that block precedes this function in document order.
+  PASSED=0
+  FAILED=0
+  SKIPPED=0
+  FAILED_ITEMS=()
+  # ⚠️ Which criteria were SKIPPED, by id — not just how many (T170 / audit finding: the
+  # checklist's per-item `**Status**:` values had NO producer, so the three gates that read
+  # them saw template placeholders and blocked every run). A count cannot fill twelve cells.
+  SKIPPED_ITEMS=()
+
+  # ⚠️ **There is no loop and no cache, so there is nothing to reset between runs
+  # and nothing to read stale state from.** The counters above are the whole of this
+  # function's state, and it is rebuilt from zero on every invocation (FR-060).
+
+  # P0: Content Quality (2 items — a third was retired 2026-09-19, T197)
+  check_cq001_implementation_details
+  check_cq003_functional_not_technical
+
+  # P0: Completeness (3 items)
+  check_cp001_mandatory_sections
+  check_cp002_acceptance_scenarios
+  check_cp003_scenarios_functional
+
+  # P1: Consistency (4 items)
+  check_cs001_us_consistency
+  check_cs002_fr_consistency
+  check_cs003_us_fr_mapping
+  check_cs004_reference_integrity
+
+  # P1: Traceability (2 items)
+  check_tr001_constitution_constraints
+  check_tr002_external_dependencies
+
+  # Rebuild the checklist from THIS run's results. ⚠️ Last, so that every check has
+  # already contributed to PASSED / FAILED / SKIPPED / SKIPPED_ITEMS.
+  update_checklist
+}
+```
+
+---
+
+## 🆕 PHASE 3: Enhanced Check Functions with Detailed Error Messages
+
+### check_cq001_implementation_details() - ENHANCED
+
+```bash
+check_cq001_implementation_details() {
+  # ⚠️ **WORD BOUNDARIES ARE REQUIRED, not cosmetic** (T094/ISS-29): unwrapped, every one of
+  # these matches inside unrelated words — `class` in "classify", `def` in "definition",
+  # `interface` in "the interface between", `private` in a path segment. The check then reports
+  # **implementation details that are not there**. (`\bSQL\b` deliberately still matches the
+  # bare token while NOT matching `PostgreSQL` / `MySQL` — the boundary is between `Y` and `S`,
+  # both word characters.) ⚠️ The half that made these false positives INVISIBLE was the empty
+  # scan container — both are fixed together, because fixing either alone is worse than neither.
+  local fail_keywords="\bReact\b|\bVue\b|\bAngular\b|\bSQL\b|\bPostgreSQL\b|\bMongoDB\b|\bMySQL\b|\bRedis\b|\bREST\b|\bGraphQL\b|\bHTTP\b|async/await|\bawait\b|\bcoroutine\b|\bclass\b|\bfunction\b|\bdef\b|\bpublic\b|\bprivate\b|\binterface\b|\babstract\b|\bextends\b|\bimplements\b"
+
+  # ⚠️ **The FR-item pattern lives in ONE variable and BOTH paths use it** (T094/ISS-91):
+  # the template emits an INDENTED bold list item — `  - **FR-XXX**: [Title]` — never
+  # `#### FR-xxx`, which appears **nowhere** in `templates/spec-template.md`. The old
+  # container therefore matched 0 rows on every spec built from the template, `found` was
+  # always empty, and the check reported PASS by construction (ISS-83's shape: the extractor
+  # finds nothing ⇒ an empty run reads as green). Fixing only the main path would leave the
+  # incremental branch below scanning the same wrong container — that is why this is a
+  # variable, not two literals.
+  local FR_ITEM='^[[:space:]]*- \*\*FR-[0-9]+[A-E]?\*\*:'
+
+  # 🆕 PHASE 3: Filter by TARGET_FRS if incremental
+  local search_scope="$FEATURE_SPEC"
+  if [[ "$TARGET_FRS" != "all" ]] && [[ -n "$TARGET_FRS" ]]; then
+      # Extract only the relevant FRs from spec.md
+      local temp_spec=$(mktemp)
+      for fr in $TARGET_FRS; do
+          grep -A 10 -E "^[[:space:]]*- \*\*$fr\*\*:" "$FEATURE_SPEC" >> "$temp_spec" || true
+      done
+      search_scope="$temp_spec"
+  fi
+
+  # ⚠️ **Reachability guard** (T093/FR-038): with the container empty the `found` below is
+  # empty too, and the check reports PASS — an **unfired predicate**, which is
+  # indistinguishable in a pass/fail report from a check that ran and found nothing wrong
+  # (形态 6). Counted as SKIPPED, never PASSED.
+  # ⚠️ **`|| echo 0` is WRONG here** and was the cause of a silent corruption: `grep -c`
+  # prints `0` AND exits 1, so that idiom yields the two-line string `"0\n0"` — and
+  # `[[ "0\n0" -eq 0 ]]` is a **syntax error**, so the guard never fires. `|| true`
+  # neutralises the exit code WITHOUT appending text; `${scanned_rows:=0}` then covers
+  # the empty case.
+  local scanned_rows=$(grep -cE "$FR_ITEM" "$search_scope" 2>/dev/null || true)
+  : "${scanned_rows:=0}"
+  if [[ "$scanned_rows" -eq 0 ]]; then
+    echo "  ⊘ CQ001: skipped — the scan container matched 0 rows, so nothing was read"
+    SKIPPED_ITEMS+=("CQ001")
+    echo "    ⚠️ An unfired predicate is NOT a pass. The container is likely mis-specified."
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+
+  # Search for implementation details in FRs
+  local found=$(grep -E "$FR_ITEM" "$search_scope" | grep -iE "($fail_keywords)" || true)
+
+  # ⚠️ **A residual false positive that word boundaries do NOT fix** — the third one named for
+  # this check (ISS-29's list: `defect`, `classify`, `private/spec-kit-main`). `\bprivate\b`
+  # still matches `private/spec-kit-main`: the segment IS the whole word, and `/` is a
+  # non-word character, so it satisfies both boundaries. **Word boundaries fix two of the
+  # three, not three** — a path is not an implementation-detail declaration, so matches whose
+  # keyword sits inside a path are dropped here.
+  # ⚠️ **A remaining limit, stated rather than papered over**: a legitimate English use of a
+  # listed word ("the interface between two layers") still matches — that is inherent to a
+  # keyword scan and is why this check's verdict is an indicator, not a proof. It belongs to
+  # the coverage declaration, not to a cleverer regex.
+  local path_like='(private|public|interface|class|def|function|abstract|extends|implements)'
+  found=$(printf '%s\n' "$found" | grep -vE "/${path_like}\b|\b${path_like}/" || true)
+
+  if [[ -n "$found" ]]; then
+    echo "  ✗ CQ001: No implementation details"
+
+    # 🆕 PHASE 3: Detailed error messages
+    local count=$(echo "$found" | wc -l)
+    echo "    Found: $count FR(s) with implementation details"
+
+    # 🆕 PHASE 3: Show specific FRs with issues
+    echo "    Affected FRs:"
+    echo "$found" | while IFS= read -r line; do
+        local fr_id=$(echo "$line" | grep -oE "FR-[0-9]+" | head -1)
+        local keyword=$(echo "$line" | grep -oiE "($fail_keywords)" | head -1)
+        echo "      - $fr_id: contains '$keyword'"
+    done
+
+    # 🆕 PHASE 3: Fix suggestion
+    echo "    💡 Suggestion: Remove technical keywords and describe functionality instead"
+    echo "       Example: 'System provides responsive web interface' (not 'System uses React')"
+
+    # ⚠️ **There used to be a repair here, behind an owner-authorisation gate.** Both are gone
+    # (`FR-058`, 2026-09-19 ruling): this criterion's subject is `spec.md`, which is NOT
+    # in this command's write face — and earlier rounds tried to make that repairable by
+    # *authorising* it through a caller-supplied owner. **The ruling rejected the
+    # direction, not the mechanism**: a command that repairs what it judged has spent the
+    # verdict (Principle III), and no parameter repairs that.
+    # ⇒ What this check does now is **report**, and `register_findings()` routes it.
+    echo "    Action: reported — /specpro-specify is the producer that repairs spec.md"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CQ001")
+    record_finding "CQ001" "Some requirements describe HOW instead of WHAT"
+  else
+    echo "  ✓ CQ001: No implementation details"
+    PASSED=$((PASSED + 1))
+  fi
+
+  # Cleanup temp file if created
+  if [[ "$search_scope" != "$FEATURE_SPEC" ]] && [[ -f "$search_scope" ]]; then
+      rm "$search_scope"
+  fi
+}
+```
+
+### ⚠️ RETIRED: the "no technical performance metrics in spec.md" criterion (T197)
+
+```bash
+# ⚠️ **This criterion was RETIRED (2026-09-19, `T197`), and the retirement is the point.**
+#
+# Its premise was false: **a performance metric is a REQUIREMENT, not an implementation
+# detail.** "How you achieve it" is the implementation detail — that is `CQ001`'s and
+# `CQ003`'s territory. Its pattern matched the WHOLE of spec.md with no section scoping,
+# so a single legitimate `MUST respond within 200ms` in an FR marked the checklist
+# BLOCKED — and a blocked checklist stops plan / tasks / implement.
+#
+# ⚠️ **It forbade the very input the rest of the toolchain reads**: plan's Technical
+# Context Performance Goals, contracts' Performance Requirements, analyze's Pass H loss
+# detection, and test-plan's `Performance:` fields all source from quantified FRs. The
+# criterion was the only thing in the chain that said such an FR must not exist.
+#
+# ⚠️ **It was NOT re-scoped.** A narrower version ("metrics must not be bound to an
+# implementation method") would have duplicated `CQ003`, which already owns exactly that.
+#
+# ⚠️ **And its clarification loop did not converge**: it reported to the [specify] ledger queue
+# without deleting, while the repo's rule is that a resolved clarification folds back
+# into spec.md as a requirement entry — which re-trips the criterion on the next run.
+#
+# ⚠️ Its helper `report_performance_metrics()` is retired with it — and so is
+# `report_scenario_performance_metrics()`, which a previous revision of this very note said
+# **STAYS** (`T240` / `ISS-213`). ⚠️ **That sentence was false the moment it was written**:
+# the function is not defined anywhere in this file, while `check_cp003_scenarios_functional`
+# kept calling it for another round. **Its rationale — not its body — is what actually stays**,
+# and it now lives at that call site's replacement (the `⚠️ This check REPORTS; it never
+# removes` note inside `check_cp003`): scenarios are a *different subject* from the whole
+# document, so a literal-match delete pass stays the wrong instrument for them too.
+# ⇒ **The lesson is the one this file keeps applying**: a promise in prose ("it STAYS") is not
+# a carrier — the definition is, and when the two disagree the prose is what misleads.
+#
+# ⚠️ **Known gap, registered not hidden** (see the ledger): the shape "use <method> to
+# reach <metric>" is matched by NEITHER `CQ001` nor `CQ003` as they stand. Retiring this
+# criterion therefore leaves that one shape uncaught — measured, not assumed.
+```
+
+```bash
+# ⚠️ **A function used to be defined here — `show_failed_items_summary()`. It is GONE,
+# and the reason it is worth a note is that it outlived its caller by one round.**
+#
+# Its only call site was inside the repair loop, which was removed when the loop went
+# (FR-060). The definition stayed behind: a complete, working function that **nothing
+# ever called**. Three things made that state easy to miss, and all three are the same
+# shape this repository keeps finding:
+#   * a function with no caller produces **no error** — it is silently dead, not broken;
+#   * a `grep` for the function name returns a hit — so "it exists" reads as "it works";
+#   * and its body had gone **stale relative to the checks it summarised** (it listed
+#     `CS001`–`CS003` under Consistency and had no line for `CS004`, which exists).
+#
+# ⇒ **If you are looking for the failed-items summary: it went with the loop.** The
+# report in the single-pass run prints the counts and the routed ids directly; a
+# category-by-category breakdown was the loop's progress display, and with a single
+# pass there is no progress to display.
+#
+# ⚠️ **Removed, not deprecated** — a commented-out copy would be a second definition
+# waiting to be picked up by whoever greps next.
+```
+
+### check_cq003_functional_not_technical()
+
+```bash
+check_cq003_functional_not_technical() {
+  # Check for technical "HOW" language vs functional "WHAT"
+  # Patterns must describe a HOW (a named technology, library or algorithm chosen to
+  # do the work), not merely a means-phrase. A bare `implement ... using <noun>` also
+  # matches legitimate protocol/business wording ("negotiation using message type N"),
+  # which is a WHAT and must not be flagged. Hence the object is constrained to a
+  # technology-shaped token.
+  #
+  # ⚠️ **`use <method> to <outcome>` — the method-bound-to-a-metric shape** (T201,
+  # 2026-09-19). This criterion is where the retired whole-document performance-metric ban
+  # handed its remaining duty: a numeric target is a REQUIREMENT, but **naming the method
+  # that attains it is an implementation detail** — "how you achieve it" is exactly what
+  # this criterion owns. Measured before the pattern was added: `System MUST use async I/O
+  # to reach 60 FPS` matched **none** of the frames above and none of `CQ001`'s keywords,
+  # so the shape had **no checker at all**.
+  #
+  # ⚠️ **Constrained by SHAPE, not by a verb list.** The obvious frame — `use X to
+  # (reach|achieve|hit|…)` — is an enumeration of outcome verbs, and an enumeration
+  # narrower than the ways outcomes get written is the shape this repository has paid for
+  # repeatedly (`ISS-84` rejected exactly that move). The reliable feature is on the
+  # METHOD side: a named method carries a slash (`async I/O`, `HTTP/2`, `read/write`),
+  # while a user-facing control does not ("use the Connect button to start"). So the
+  # pattern requires a slash-bearing token and leaves the verb open.
+  #
+  # ⚠️ **Its honest limit, stated rather than implied**: a method spelled without a slash
+  # ("a thread pool") is NOT caught. That is the same remainder this criterion already
+  # declares — its template entry reads `**Validation**: Semi-automated` — and the
+  # remainder is human review, not a quiet pass.
+  local technical_patterns=(
+    "use[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+to[[:space:]]+implement"
+    "implement[^.]{0,40}using[[:space:]]+(React|Vue|Angular|Ktor|SQLDelight|SQLite|PostgreSQL|MySQL|MongoDB|Redis|GraphQL|Istanbul|NYC|Docker|Kubernetes|Hibernate|Express|Django|Flask|Spring)|implement[^.]{0,40}via[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+(algorithm|library|framework|toolkit)"
+    "achieve[^.]{0,30}by[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+(algorithm|library|framework|toolkit)"
+    "via[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+algorithm"
+    "utiliz(e|ing)[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+library"
+    "use[^.]{0,40}/[A-Za-z0-9_.-]*[[:space:]]+to[[:space:]]+[a-z]+"
+  )
+
+  local found=false
+  for pattern in "${technical_patterns[@]}"; do
+    if grep -qiE "$pattern" "$FEATURE_SPEC"; then
+      found=true
+      break
+    fi
+  done
+
+  if [[ "$found" == "true" ]]; then
+    echo "  ✗ CQ003: Requirements are functional, not technical"
+    echo "    Found technical implementation language in FRs"
+
+    record_finding "CQ003" "Some requirements describe HOW instead of WHAT"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CQ003")
+  else
+    echo "  ✓ CQ003: Requirements are functional, not technical"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cp001_mandatory_sections()
+
+```bash
+check_cp001_mandatory_sections() {
+  # ⚠️ **FR-041 — the list is READ FROM THE ARTIFACT'S TEMPLATE, not held here.**
+  # This function used to carry `local required_sections=("## Overview" "## User Scenarios &
+  # Testing" "## Requirements")`. Measured, that array had two disagreements behind it: the
+  # checklist template declared `Functional Requirements` (a sub-heading) while the array
+  # named `## Requirements` (its container), and `templates/spec-template.md` — the file
+  # that actually PRODUCES `spec.md` — defined **no `## Overview` at all**. So the criterion
+  # demanded a section no producer emits, and every spec generated from the template failed
+  # against something it was never given the means to satisfy.
+  # **A criterion with two sources has no source**; the template's own `*(mandatory)*`
+  # markers are the one that counts, and this is where they are read.
+  local required_sections=()
+  while IFS= read -r s; do
+    [[ -n "$s" ]] && required_sections+=("$s")
+  done < <(grep -E '^## .*\*\(mandatory\)\*' "$SPEC_TEMPLATE" 2>/dev/null \
+             | sed 's/\*([^)]*)\*.*$//; s/[[:space:]]*$//' || true)
+
+  # ⚠️ **No declared set ⇒ the defect is HERE, not in the artifact** (FR-041). A criterion
+  # whose target the template never defines cannot be failed against a spec — and the empty
+  # `missing` list below must not be allowed to fall through as a pass (形态 6).
+  if [[ ${#required_sections[@]} -eq 0 ]]; then
+    echo "  ⊘ CP001: not executable — the artifact template declares no mandatory sections"
+    SKIPPED_ITEMS+=("CP001")
+    echo "    Checked: $SPEC_TEMPLATE"
+    echo "    ⚠️ This is a defect in the CHECK, not in the spec (FR-041): with nothing declared"
+    echo "       there is nothing to judge, and an unfired check is not a pass."
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+
+  local missing=()
+  for section in "${required_sections[@]}"; do
+    # Line-start match, deliberately NOT `grep -F`: a fixed-string match would also accept a
+    # *mention* of the heading inside prose, which is the "presence of a marker is not the
+    # requirement being met" defect this file keeps closing (FR-039).
+    if ! grep -q "^$section" "$FEATURE_SPEC"; then
+      missing+=("$section")
+    fi
+  done
+
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    echo "  ✗ CP001: All mandatory sections completed"
+    echo "    Missing: ${missing[*]}"
+
+    # Manual fix required
+    record_finding "CP001" "Missing mandatory sections: ${missing[*]}"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CP001")
+  else
+    echo "  ✓ CP001: All mandatory sections completed"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cp002_acceptance_scenarios()
+
+```bash
+check_cp002_acceptance_scenarios() {
+  # ⚠️ **The User-Story heading pattern, in ONE variable — both uses below read it**
+  # (T094/ISS-63). The template emits `### US1 - [Brief Title] (Priority: P1)`
+  # (`templates/spec-template.md`), never `### User Story` — so the old pattern matched 0
+  # rows on every generated spec, the count was always 0, and `0 != 0` is false ⇒ the check
+  # took its **else** branch and reported PASS. ⚠️ Both uses must move together: the count
+  # AND the line-number lookup below (that one sits inside `if [[ $us_count -gt 0 ]]`, so a
+  # zero count meant it never even executed).
+  local US_HEADING='^### US[0-9]+ '
+
+  # Count User Stories
+  # ⚠️ `|| echo "0"` was WRONG (fixed with T093): `grep -c` prints `0` AND exits 1, so it
+  # produced the two-line string `"0\n0"` — every `[[ $us_count -op … ]]` below was then a
+  # **syntax error**, the `if` fell through to its else branch, and the check reported
+  # PASS **because of a shell error**, not because it decided anything. `|| true` keeps the
+  # exit code quiet without appending text.
+  local us_count=$(grep -cE "$US_HEADING" "$FEATURE_SPEC" || true)
+  : "${us_count:=0}"
+
+  # ⚠️ **Reachability guard** (T093/FR-038): with `us_count = 0` the comparison at the end
+  # is vacuously true (`0 != 0` is false ⇒ the else branch ⇒ PASS) — the loop below never
+  # runs, so the check decides nothing while reporting a pass. Counted as SKIPPED.
+  # ⚠️ The pattern is also wrong for this template: it emits `### US1 - …`, not
+  # `### User Story` — so this guard fires on every spec built from the template. That is
+  # T094's fix; the guard makes it VISIBLE instead of silent.
+  if [[ "${us_count:-0}" -eq 0 ]]; then
+    echo "  ⊘ CP002: skipped — 0 User Stories matched by the scan pattern"
+    SKIPPED_ITEMS+=("CP002")
+    echo "    ⚠️ Either the spec has none, or the pattern does not match the template's form."
+    echo "       A count that can never be non-zero decides nothing — it is NOT a pass."
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+
+  # Count User Stories with Acceptance Scenarios (per-US block scan)
+  # Format contract: scenario line is a bold text line `**Acceptance Scenarios**:`
+  local us_with_scenarios=0
+  if [[ $us_count -gt 0 ]]; then
+    local line_nums=($(grep -nE "$US_HEADING" "$FEATURE_SPEC" | cut -d: -f1))
+    local total_lines=$(wc -l < "$FEATURE_SPEC" | tr -d ' ')
+    for i in "${!line_nums[@]}"; do
+      local start=${line_nums[$i]}
+      local end=$total_lines
+      if [[ $((i + 1)) -lt ${#line_nums[@]} ]]; then
+        end=$((${line_nums[$((i + 1))]} - 1))
+      fi
+      if sed -n "${start},${end}p" "$FEATURE_SPEC" | grep -q '^\*\*Acceptance Scenarios\*\*:'; then
+        us_with_scenarios=$((us_with_scenarios + 1))
+      fi
+    done
+  fi
+
+  if [[ $us_count -ne $us_with_scenarios ]]; then
+    echo "  ✗ CP002: Every User Story has Acceptance Scenarios"
+    echo "    Missing: $((us_count - us_with_scenarios)) US without scenarios"
+
+    record_finding "CP002" "Some User Stories lack Acceptance Scenarios"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CP002")
+  else
+    echo "  ✓ CP002: Every User Story has Acceptance Scenarios"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cp003_scenarios_functional()
+
+```bash
+check_cp003_scenarios_functional() {
+  # Check Acceptance Scenarios for performance metrics
+  # NOTE: ERE has no \d — use [0-9]+; anchor the bold literal with escaped asterisks
+  #
+  # Scope = the scenario block proper, bounded STRUCTURALLY (a line that is entirely
+  # bold, e.g. the next `**Lifecycle**:` / `**Related Requirements**:` marker, ends it).
+  # A fixed look-ahead window (the former `grep -A 50`) does not track the block: it
+  # overruns into whatever follows — a separate "performance scenarios" subsection, for
+  # instance — and reports that section's metrics as if they were scenario text.
+  local found=$(awk '
+    /^\*\*Acceptance Scenarios\*\*:/ { inblock=1; next }
+    inblock && /^\*\*[^*]+\*\*[[:space:]]*:/ { inblock=0; next }
+    inblock { print }
+  ' "$FEATURE_SPEC" | grep -E "within [0-9]+ ?ms|under [0-9]+ ?ms|[0-9]+ FPS" || true)
+
+  if [[ -n "$found" ]]; then
+    echo "  ✗ CP003: Acceptance Scenarios are functional (not technical)"
+    echo "    Found: $(echo "$found" | wc -l) scenarios with performance metrics"
+
+    # ⚠️ **This check REPORTS; it never removes.** A delete pass driven by a literal match
+    # is the wrong instrument for this class — the match cannot tell a *target* (belongs in
+    # plan.md) from a *requirement* (restate it functionally), and one of the patterns
+    # (`[0-9]+ ?FPS`) is unanchored. ⚠️ **Do not add an auto-fix here.**
+    #
+    # ⚠️ **The reporting itself is NOT done here** — it is `register_findings`, which runs
+    # once after every check has contributed to `FAILED_ITEMS` (`FR-059`). That is why this
+    # block only records the verdict and prints the action line.
+    #
+    # ⚠️ **And `record_finding` below is load-bearing, not decoration** (`T240` verification):
+    # `register_findings` iterates **`FINDINGS`**, not `FAILED_ITEMS` — so a check that
+    # increments the counter without recording a finding gets a `✗` in the checklist and a
+    # **FAILED verdict**, while nothing reaches the ledger. This check was the **only one of
+    # twelve** missing the call (measured: `check_cq001`…`check_tr002` each call it; `cp003`
+    # called it zero times) ⇒ its own `Action:` line — "reported to the `[specify]` ledger
+    # queue" — was **false on every failure**, and `FINDINGS`' own comment ("the id alone
+    # cannot fill a ledger entry") explains why the missing call could not be papered over
+    # downstream. ⚠️ **Do not remove it**; a second check losing this call is what the sweep
+    # above is for.
+    record_finding "CP003" "Some Acceptance Scenarios carry performance metrics (technical, not functional)"
+    #
+    # ⚠️ **A call to `report_scenario_performance_metrics` used to sit on this line, and it
+    # was REMOVED** (`T240` / `ISS-213`): the function is not defined in this file, and it
+    # cannot be restored as it was — it reported by writing `clarifications.md`, which
+    # `FR-058` removed from this command's write surface (exactly two: its checklist, and
+    # its `[specify]` entries). Its in-block scan already lives inline above. ⚠️ **Do not
+    # re-add the call**: an undefined function on a check's failure path prints
+    # `command not found` and — this file has no `set -e` — execution continues, so the
+    # verdict and the routing both still happen, and the only thing the call ever produced
+    # was a line of stderr and a false impression that a report had been made *here*.
+    echo "    Action: reported to the [specify] ledger queue (NOT auto-removed)"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CP003")
+  else
+    echo "  ✓ CP003: Acceptance Scenarios are functional"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cs001_us_consistency()
+
+```bash
+check_cs001_us_consistency() {
+  # Check for contradictory User Stories
+  # Simplified: hardcoded keyword-pair check only — semantic consistency
+  # is owned by /specpro-analyze. Do not extend here.
+  local found=false
+
+  # Example: Check for "offline" vs "always-on" contradictions
+  if grep -qi "offline.*mode" "$FEATURE_SPEC" && grep -qi "always.*on.*connection" "$FEATURE_SPEC"; then
+    found=true
+  fi
+
+  if [[ "$found" == "true" ]]; then
+    # ⚠️ **The verdict names what was MEASURED, not what it would like to conclude** (T170 /
+    # audit finding: "用一对固定短语的命中与否，断言一个全称结论"). The criterion probes ONE
+    # keyword pair; a `✓` that read "internally consistent" asserted a universal property
+    # nothing here checks. The `scope:` line below said so — the verdict line contradicted it.
+    echo "  ✗ CS001: the keyword-pair probe MATCHED — possible contradiction"
+    echo "    Possible contradiction detected"
+
+    # Manual intervention required
+    record_finding "CS001" "Possible contradiction in User Stories"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CS001")
+  else
+    echo "  ✓ CS001: no contradiction detected by the keyword-pair probe"
+    # ⚠️ **Scope stated where the verdict is read** (T097 / FR-038, handed over by T123).
+    # This check is a **keyword-pair probe**: it knows exactly one pair of spellings that
+    # *may* indicate the contradiction (see the two `grep -qi` above). Its `✓` therefore
+    # means "that one pattern did not occur" — NOT "the User Stories are consistent". The
+    # property is semantic, and `/specpro-analyze` owns it (this is a declared stub; the
+    # comment at the top of the function says so and forbids extending it here).
+    # **An over-claim is caught by no later gate** — nothing compares a verdict's wording
+    # against what its test established (FR-038: a check whose result is decided by
+    # something outside its own intent reports a **value**, not a **finding**). ⇒ Stated,
+    # not left to be inferred from the source. ⚠️ **The first line is left as-is on
+    # purpose**: it is the checklist item's own name, and all twelve checks report
+    # "verdict mark + item name"; this line is what carries the honesty, not a rewording
+    # of the convention.
+    # ⚠️ **NO BACKTICKS around the command name** (`T248`/`ISS-223`): inside a double-quoted
+    # string a backtick pair is **command substitution** — bash executes `/specpro-analyze`
+    # (a path that does not exist), prints `No such file or directory` to stderr on every run,
+    # and substitutes the EMPTY result ⇒ this line printed `… —  owns consistency`, i.e. it
+    # **erased the very name it exists to name**. A reader cannot tell a blanked name from one
+    # that was never written.
+    echo "    scope: ONE keyword pair, not a semantic check — /specpro-analyze owns consistency"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cs002_fr_consistency()
+
+```bash
+check_cs002_fr_consistency() {
+  # Check for contradictory FRs
+  # Simplified: hardcoded keyword-pair check only — semantic consistency
+  # is owned by /specpro-analyze. Do not extend here.
+  local found=false
+
+  # Example: "store locally" vs "NOT use local storage"
+  if grep -qi "store.*data.*locally" "$FEATURE_SPEC" && grep -qi "NOT.*use.*local.*storage" "$FEATURE_SPEC"; then
+    found=true
+  fi
+
+  if [[ "$found" == "true" ]]; then
+    # ⚠️ **The verdict names what was MEASURED, not what it would like to conclude** (T170 /
+    # audit finding: "用一对固定短语的命中与否，断言一个全称结论"). The criterion probes ONE
+    # keyword pair; a `✓` that read "internally consistent" asserted a universal property
+    # nothing here checks. The `scope:` line below said so — the verdict line contradicted it.
+    echo "  ✗ CS002: the keyword-pair probe MATCHED — possible contradiction"
+    echo "    Possible contradiction detected"
+
+    # Manual intervention required
+    record_finding "CS002" "Possible contradiction in Functional Requirements"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CS002")
+  else
+    echo "  ✓ CS002: no contradiction detected by the keyword-pair probe"
+    # ⚠️ Same shape and same reason as CS001 above (T097 / FR-038): a declared stub —
+    # one hardcoded keyword pair — reporting under the item's semantic name.
+    # ⚠️ **NO BACKTICKS around the command name** (`T248`/`ISS-223`): inside a double-quoted
+    # string a backtick pair is **command substitution** — bash executes `/specpro-analyze`
+    # (a path that does not exist), prints `No such file or directory` to stderr on every run,
+    # and substitutes the EMPTY result ⇒ this line printed `… —  owns consistency`, i.e. it
+    # **erased the very name it exists to name**. A reader cannot tell a blanked name from one
+    # that was never written.
+    echo "    scope: ONE keyword pair, not a semantic check — /specpro-analyze owns consistency"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cs003_us_fr_mapping()
+
+```bash
+# ⚠️ **The empty-population guard, in ONE place** (T123 / FR-038 / 形态 6).
+#
+# The criteria below sample a POPULATION — the User Stories, the FR identifiers. When that
+# population is empty the predicate is never exercised, and an **unfired predicate prints
+# the same `✓` as a real pass**: the report cannot tell "checked and clean" from "never
+# checked". `⊘` is the third value (T093) — shown distinctly, counted as neither pass nor
+# fail. Measured (T123's replay): fed a spec consisting of one heading, seven criteria
+# printed `✓` without deciding anything.
+#
+# ⚠️ **Not every empty-input pass is this defect.** A *search* criterion — "no forbidden
+# pattern anywhere in the document" — returning nothing on an empty document is a **true
+# negative**, and guarding it would be the mirror error. The guard belongs to the
+# "**every X satisfies P**" shape, where an empty X makes the quantifier the whole answer.
+# That is the shape `check_cp002` was guarded for in T093 and these two were not.
+#
+# usage: population_empty "<CHECK-ID>" "<count>" "<what was sampled>" && return
+population_empty() {
+  local id=$1 count=$2 what=$3
+  if [[ ${count:-0} -eq 0 ]]; then
+    echo "  ⊘ $id: skipped — 0 $what, so the criterion was never exercised"
+    echo "    ⚠️ An unfired predicate is NOT a pass (FR-038)."
+    SKIPPED_ITEMS+=("$id")
+    SKIPPED=$((SKIPPED + 1))
+    return 0
+  fi
+  return 1
+}
+
+check_cs003_us_fr_mapping() {
+  # Check if all User Stories have associated FRs (NEW: supports grouped structure)
+  local us_without_fr=()
+
+  # Extract all US IDs
+  local us_ids=$(grep "^### US[0-9]" "$FEATURE_SPEC" | grep -oE "US[0-9]+" | sort -u)
+
+  # ⚠️ **0 User Stories ⇒ "every US has an FR" is vacuously true**: the quantifier has
+  # nothing to range over, so the check printed `✓` having decided nothing.
+  local us_count=$(printf '%s\n' "$us_ids" | grep -c . || true)
+  : "${us_count:=0}"
+  population_empty "CS003" "$us_count" "User Stories" && return
+
+  # The Requirements section, delimited by its heading and the next `## ` heading —
+  # NOT by a fixed line window. A hardcoded `-A 500` silently stops covering the
+  # section once a spec grows past it, and every US beyond the window is then
+  # reported as an orphan. (The section range must be expressed with awk, not a
+  # `sed` range: the start line matches the end pattern too, so the range would
+  # collapse to a single line — the same trap that made an auto-fix a no-op.)
+  local fr_section
+  fr_section=$(awk '
+    /^## Requirements/ { in_req = 1; print; next }
+    in_req && /^## /   { exit }
+    in_req             { print }
+  ' "$FEATURE_SPEC")
+
+  for us in $us_ids; do
+    # NEW: Check if this US has FR group in Requirements section
+    # Look for pattern: "#### [Title] (US[ID])" in Requirements section.
+    #
+    # ⚠️ No `| head -1` on this pipeline: its exit status would be `head`'s, which
+    # is always 0, so `! 0` is never true and the check could not fail — a verdict
+    # that is always "pass" and is indistinguishable from a real pass. And a
+    # herestring rather than a pipe: grep exits at the first match, the writer
+    # takes SIGPIPE, and under `pipefail` the pipeline then reports 141 — a real
+    # orphan would read as an orphan only sometimes.
+    if ! grep -q "($us)" <<<"$fr_section"; then
+      us_without_fr+=("$us")
+    fi
+  done
+
+  if [[ ${#us_without_fr[@]} -gt 0 ]]; then
+    echo "  ✗ CS003: US → FR mapping is complete"
+    echo "    Orphan US: ${us_without_fr[*]}"
+
+    record_finding "CS003" "User Stories without FRs: ${us_without_fr[*]}"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CS003")
+  else
+    echo "  ✓ CS003: US → FR mapping is complete"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_cs004_reference_integrity()
+
+```bash
+check_cs004_reference_integrity() {
+  # Reference integrity: every identifier mentioned in the spec must resolve to
+  # a definition in this document. Guards against dangling forward-reference
+  # namespaces (historical shape: several FRs carried a "(per SC-xxx)" reference
+  # while the spec had no Success Criteria section at all).
+  #   a) every FR-nnn[A-E]? mention must match a defined FR entry
+  #   b) every "(per X-nnn)" attribution must point at a defined FR
+  #      ("(per Constitution)" style external references carry no digits: skipped)
+  # ⚠️ **`-o` on the FIRST grep, not only the second** (ISS-149 / T190). Without it the first
+  # grep selects the whole LINE, and the second harvests **every** FR id on that line — so a
+  # requirement that defines one FR and cites a DIFFERENT, undefined one put the cited id
+  # into `defined_frs`, and the dangling loop below then read the reference as resolved.
+  # (The measurement used concrete ids; they are not restated here — a value written into
+  # prose is indistinguishable from a current one to a mechanical reader, T202.) Measured:
+  # the same reference on a CONTINUATION line was caught (`FAILED=1`), on the definition line
+  # it was not (`FAILED=0`) — so the check was not always-true, it failed on one real way of
+  # writing it, which is harder to see. The trailing `:` narrows the yield to the definition
+  # form, and that form carries exactly one id.
+  local defined_frs=$(grep -oE '^[[:space:]]*- \*\*FR-[0-9]+[A-E]?\*\*:' "$FEATURE_SPEC" | grep -oE 'FR-[0-9]+[A-E]?' | sort -u)
+  local dangling=()
+  local ref
+
+  # ⚠️ **No FR identifier anywhere ⇒ "every reference resolves" is vacuously true** — there
+  # is nothing to range over and the `✓` reports a decision that was never made.
+  local ref_count=$(grep -oE 'FR-[0-9]+[A-E]?' "$FEATURE_SPEC" 2>/dev/null | sort -u | grep -c . || true)
+  : "${ref_count:=0}"
+  population_empty "CS004" "$ref_count" "FR identifiers (defined or referenced)" && return
+
+  # a) referenced FR IDs must be a subset of defined FR IDs
+  for ref in $(grep -oE 'FR-[0-9]+[A-E]?' "$FEATURE_SPEC" | sort -u); do
+    if ! grep -qx "$ref" <<< "$defined_frs"; then
+      dangling+=("$ref (referenced but not defined)")
+    fi
+  done
+
+  # b) "(per X-nnn)" attributions must point at a defined FR
+  for ref in $(grep -oE '\bper [A-Z]+-[0-9]+[A-E]?' "$FEATURE_SPEC" | sed 's/^per //' | sort -u); do
+    if ! grep -qx "$ref" <<< "$defined_frs"; then
+      dangling+=("$ref (per-reference to undefined identifier)")
+    fi
+  done
+
+  if [[ ${#dangling[@]} -gt 0 ]]; then
+    echo "  ✗ CS004: Identifier references resolve to definitions"
+    echo "    Dangling: ${dangling[*]}"
+
+    record_finding "CS004" "Dangling identifier references: ${dangling[*]}"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("CS004")
+  else
+    echo "  ✓ CS004: Identifier references resolve to definitions"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_tr001_constitution_constraints()
+
+```bash
+check_tr001_constitution_constraints() {
+  # Check if Constitution constraints are documented
+  local constitution="specs/constitution.md"
+
+  if [[ ! -f "$constitution" ]]; then
+    # ⚠️ This used to print "✓ … (no Constitution file)" and count as PASSED — a check
+    # that reached nothing, folded into a pass. With no constitution there is nothing to
+    # trace requirements to, so the predicate never runs. Third value, not a pass (T093).
+    echo "  ⊘ TR001: skipped — no Constitution at $constitution"
+    SKIPPED_ITEMS+=("TR001")
+    echo "    ⚠️ Nothing to trace constraints to. This is NOT a pass (the check did not run)."
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+
+  # Check if spec.md has Constitution Constraints section
+  if ! grep -q "^## Constitution Constraints" "$FEATURE_SPEC"; then
+    echo "  ✗ TR001: Constitution constraints documented"
+    echo "    Missing: Constitution Constraints section"
+
+    record_finding "TR001" "Constitution exists but constraints not documented in spec"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("TR001")
+  else
+    echo "  ✓ TR001: Constitution constraints documented"
+    PASSED=$((PASSED + 1))
+  fi
+}
+```
+
+### check_tr002_external_dependencies()
+
+```bash
+check_tr002_external_dependencies() {
+  # ⚠️ **The source is the FUNCTIONAL layer, not the implementation stack** (T095/FR-040).
+  # Names used to be derived from `plan.md` → `**Primary Dependencies**` — that is the
+  # IMPLEMENTATION stack (libraries, frameworks, language versions). TR002 asks about the
+  # functional layer's interoperation objects: the outside systems the *requirements* talk
+  # to. Deriving from the wrong layer made the check's subject "which libraries do we link"
+  # when its subject is "which outside systems does the product depend on".
+  #
+  # ⚠️ **And the judgment reads CONTENT, not the heading.** It used to be a single
+  # `grep -qiE '^#+.*(external dependenc|dependencies|third.?party)' "$FEATURE_SPEC"` — it
+  # passed as soon as a matching HEADING existed, reading nothing underneath it. An empty
+  # `## External Dependencies` therefore satisfied a check whose entire point is that the
+  # dependencies be *identified* (T095's 核验: a same-named EMPTY section MUST NOT pass).
+  local derived_keys=()
+
+  # Outside systems named by the spec's own text — the functional layer.
+  # ⚠️ **Restricted to NORMATIVE lines** (`MUST` / `SHALL` / `必须`). Without that filter a
+  # sentence that *denies* external dependencies matches the bare noun and flips the verdict —
+  # measured: `本项目自包含，无外部依赖。` derived `外部依赖` and then reported "external
+  # systems named but no section". A requirement that an outside system be used is a
+  # statement about the product; a passing mention (or a denial) is not.
+  while IFS= read -r name; do
+    [[ -n "$name" ]] && derived_keys+=("$name")
+  # ⚠️ `外部` alone is too broad and `外部(系统|服务|依赖|接口|API)` is too narrow — measured:
+  # `系统 MUST 对接外部支付网关 API` matched **neither** (the noun follows 网关, not 外部).
+  # The middle ground is a bounded lookahead for a system-ish noun.
+  done < <(grep -E 'MUST|SHALL|必须' "$FEATURE_SPEC" 2>/dev/null \
+             | grep -vE '不(依赖|需要|涉及|对接)|无(外部|需)|MUST[[:space:]]+NOT|不需要' \
+             | grep -oE '外部[^，。；、]{0,12}(系统|服务|依赖|接口|API|网关|数据库|平台)|第三方[^，。；、]*|external[[:space:]]+(system|service|API|dependenc)[^.,;]*|third.?party[^.,;]*' \
+             | sed 's/[[:space:]]*$//' | sort -u || true)
+
+  # Read the section's BODY — the part the old judgment never looked at.
+  # ⚠️ Both scans must be **case-insensitive**: headings are written `## External
+  # Dependencies`, and a lowercase-only pattern finds nothing — which is how the first
+  # version of this rewrite reported "no such section" for a spec that had one.
+  local dep_section
+  dep_section=$(awk '
+    tolower($0) ~ /^#+.*(external dependenc|dependencies|third.?party)/ { insec=1; next }
+    insec && /^#+ / { exit }
+    insec { print }
+  ' "$FEATURE_SPEC")
+
+  if grep -qiE '^#+.*(external dependenc|dependencies|third.?party)' "$FEATURE_SPEC" 2>/dev/null; then
+    # The section EXISTS. A heading with nothing under it is a defect in its own right —
+    # either there is content to write or the heading should not be there.
+    if [[ -z "${dep_section//[[:space:]]/}" ]]; then
+      echo "  ✗ TR002: the External Dependencies section exists but is EMPTY"
+      echo "    ⚠️ A heading alone is not an answer — the check reads the content, not the heading."
+      record_finding "TR002" "External Dependencies section exists but is empty"
+      FAILED=$((FAILED + 1))
+      FAILED_ITEMS+=("TR002")
+      return
+    fi
+  else
+    # ⚠️ **FR-041 — before demanding the section, ask whether the TEMPLATE defines one.**
+    # Measured (T096): `templates/spec-template.md` then defined no external-dependencies
+    # section, so no spec generated from it could satisfy the branch below — the spec was
+    # not at fault, the **criterion** was. This guard is the mechanism that reports it.
+    # ⚠️ **Resolved by T189** (`ISS-147`, user ruling: option A): the template now carries
+    # `## External Dependencies *(if applicable)*`, so this guard is **silent in this
+    # project** and the three grounded outcomes below are reachable. It is kept — not dead
+    # code — because it is what fires for *any* project whose template lacks the section,
+    # and because it is what would have caught this one. ⚠️ **`*(if applicable)*` is
+    # deliberately NOT `*(mandatory)*`**: `check_cp001` derives its required set from the
+    # `*(mandatory)*` markers, so marking this one mandatory would silently turn the ruling
+    # into "every spec must have an external-dependencies section".
+    # ⚠️ **This guard comes FIRST**, ahead of the naming test: naming decides *how much to
+    # say*, it does not decide whether the criterion is grounded.
+    # ⚠️ **`-i` is load-bearing** — same trap as the section scan above, hit a second time
+    # while writing this guard: the template spells it `## External Dependencies`, and a
+    # lowercase-only pattern reports "the template defines no such section" for a template
+    # that does. Caught by fixture ⑤ (grounded case must still FAIL) going to the ⊘ branch.
+    if ! grep -qiE '^#+.*(external dependenc|dependencies|third.?party)' "$SPEC_TEMPLATE" 2>/dev/null; then
+      echo "  ⊘ TR002: not executable — the artifact template defines no such section"
+      SKIPPED_ITEMS+=("TR002")
+      echo "    Checked: $SPEC_TEMPLATE"
+      echo "    ⚠️ This is a defect in the CHECK, not in the spec (FR-041): a spec whose own"
+      echo "       template offers no place to list external dependencies cannot be failed"
+      echo "       for not listing them. Fix the CRITERION, or give the template the section."
+      if [[ ${#derived_keys[@]} -gt 0 ]]; then
+        echo "    Named in the spec: ${derived_keys[*]}"
+      fi
+      SKIPPED=$((SKIPPED + 1))
+      return
+    fi
+
+    # The template does define such a section, so the demand below is grounded. Only a
+    # defect when the spec actually names an outside system.
+    #
+    # ⚠️ **This message used to read "no external system named in the spec" — a claim the
+    # scan cannot support** (ISS-150 / T191). `derived_keys` recognises a dependency only
+    # when it carries a LABEL — `外部`/`第三方`/`external …`/`third-party`. The functional-layer
+    # names this criterion's own examples teach carry no such label:
+    #
+    #     recognized=[external service to settle the order]   ← the system MUST call the external service …
+    #     recognized=[]                                       ← the system MUST call the payment gateway the checkout flow calls.
+    #
+    # The second line is verbatim from `templates/requirements-template.md` → TR002, i.e. the
+    # form the criterion tells authors to write. So "not recognised" was being reported as
+    # "not present", and the two are indistinguishable to the reader — 形态 6's neighbour: a
+    # criterion silent on its own correct input.
+    #
+    # ⚠️ **The vocabulary was NOT widened to fix this, and that is the decision** (recorded in
+    # `specs/research.md`): an unlabelled functional name has no distinguishing token — the
+    # candidates (`store`, `service`, `provider`) are ordinary English words that appear in
+    # unrelated requirements, so extending the list converts a false negative into a stream of
+    # false positives. A false ✗ is not a safer error than a false ⊘; it is a louder one, and
+    # the reader who hits it learns to ignore the check. What IS fixable here is the CLAIM.
+    if [[ ${#derived_keys[@]} -eq 0 ]]; then
+      echo "  ⊘ TR002: not decidable by this scan — it recognises a dependency only when the"
+      SKIPPED_ITEMS+=("TR002")
+      echo "     spec LABELS it (外部 / 第三方 / external … / third-party), and no such label"
+      echo "     was found. ⚠️ This is a limit of the CHECK, not a finding that the spec has no"
+      echo "     external dependencies — an unlabelled functional name (\"the payment gateway"
+      echo "     the checkout flow calls\", this criterion's own example) is not recognised."
+      echo "     Review the requirements manually for outside systems; record what you find in"
+      echo "     the spec's External Dependencies section."
+      SKIPPED=$((SKIPPED + 1))
+      return
+    fi
+    echo "  ✗ TR002: external systems named but no External Dependencies section"
+    echo "    Named in the spec: ${derived_keys[*]}"
+    record_finding "TR002" "External dependencies need documentation (named: ${derived_keys[*]})"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("TR002")
+    return
+  fi
+
+  # Section exists and has content. TR002's intent is that FAILURES were considered —
+  # listing names is not enough (this is the half that made the check's own motivation
+  # true rather than nominal).
+  if ! printf '%s\n' "$dep_section" | grep -qiE 'fail|failure|timeout|mitigat|unavailable|degrad|fallback|error|超时|失败|不可用|降级|回退|异常|兜底'; then
+    echo "  ✗ TR002: dependencies listed but no FAILURE MODE stated"
+    echo "    TR002 asks whether external-dependency failures were CONSIDERED, not merely listed."
+    record_finding "TR002" "External dependencies listed without failure modes"
+    FAILED=$((FAILED + 1))
+    FAILED_ITEMS+=("TR002")
+    return
+  fi
+
+  echo "  ✓ TR002: External dependencies documented with failure modes"
+  PASSED=$((PASSED + 1))
+}
+```
+
+---
+
+## The repair path — REMOVED, and this is where it was ⚠️ [FR-058]
+
+```bash
+# ⚠️ **Five functions used to live in this section. None of them exists any more.**
+# The list is kept — DESCRIBED rather than named — so the next reader does not
+# re-invent them without knowing they were tried:
+#
+#   1. the loop's "attempt to resolve" step — its own comment said it fixes nothing.
+#   2. the ONE write-back door — moved to the script named at the end of this note
+#      (`T186` / `ISS-143`), and its ONLY remaining use is writing the checklist this
+#      command itself produces.
+#   3. two prose rewriters — one edited `spec.md`'s FR lines, one reported on
+#      performance-metric prose. Both wrote an artifact this command does not own.
+#   4. the authorisation guard that those two called first — the door that asked
+#      "who authorized this repair?" (`ISS-163` / `T203`).
+#
+# ⚠️ **They are described rather than named on purpose.** The criteria these tasks are
+# verified by are greps for the old identifiers, and a note that spells them out would
+# make every one of those greps non-zero — so the check could never again tell "the
+# mechanism is gone" from "somebody wrote its name in a comment". The precedent is this
+# repository's own (`T172`: 散文让位于可复核性). **The full names and the reasoning are
+# in `specs/implement_issues.md` → `ISS-186` and in `specs/research.md` → `Addendum
+# (T220, 2026-09-19)`** — records, where a name belongs.
+#
+# **Why they are gone rather than "authorised"**: see the write-surface note at the top
+# of this file. Short version — **qc judges; it does not repair.** A repair performed by
+# the judge has spent the verdict (Principle III), and no caller-side parameter repairs
+# that. ⚠️ Two earlier rounds tried the parameter route; the 2026-09-19 ruling closed it.
+#
+# The script that remains: `scripts/bash/qc-auto-fix.sh` (+ its `.ps1` twin).
+```
+
+---
+
+## register_findings() — route every non-passing check ⚠️ [FR-059]
+
+```bash
+# ⚠️ **This is the step that turns "a check failed" into "something a named consumer
+# will read."** Without it a `✗` lives only in the checklist — and the checklist is
+# rebuilt on every run (FR-060), so that finding would survive exactly until the next
+# invocation. A finding that vanishes on the next run is indistinguishable from one
+# that was never reported (`FR-023`).
+#
+# ⚠️ **DEDUP IS NOT OPTIONAL.** This command runs on every spec creation and every spec
+# update (FR-062), so an undeduped writer appends the same failing check again and
+# again — and **a queue that has been flooded is no longer a queue.** The key is the
+# CHECK ID combined with the entry's OPEN state: an entry already resolved `[x]` MUST
+# NOT suppress a freshly-observed failure.
+register_findings() {
+  local ledger="$IMPL_LEDGER"
+  if [[ ! -f "$ledger" ]]; then
+    echo "   ⚠️ ledger not found: $ledger — findings stay in this report only" >&2
+    return 0
+  fi
+
+  local entry cid msg next_id
+  for entry in "${FINDINGS[@]}"; do
+    cid="${entry%%$'\t'*}"
+    msg="${entry#*$'\t'}"
+
+    # (a) Dedup — is there already an OPEN entry for THIS check id?
+    # ⚠️ Anchored on the entry body's line-start shape, never a full-text keyword
+    # search: the id also appears in statistics rows and cross-references, and matching
+    # one of those would silently SUPPRESS a real finding — the same false-skip the
+    # ledger's own writer guards against.
+    #
+    # ⚠️ **The pattern is `\*\*${cid}\*\*` and NOT `\(\*\*${cid}\*\*\)`** — this is a
+    # FIX, and the fixture is what caught it. The entry the awk below emits ends
+    # `**CQ001**（source: …）` with a **full-width** parenthesis, while the first version
+    # of this line looked for ASCII `(…)`. ⇒ **it could never match**, the dedup never
+    # fired, and a second run appended the same finding again. ⚠️ **Measured, not
+    # reasoned**: against the real emitted line, the old pattern returned **0**, this one
+    # returns **1**, and `**CQ0010**` does not match `**CQ001**` (the `**` pair is the
+    # boundary). A dedup guard that cannot fire is worse than no guard — it is a guard
+    # somebody will trust.
+    if grep -qE "^- \[ \] ISS-[0-9]+: .*\*\*${cid}\*\*" "$ledger"; then
+      echo "   ↺ ${cid}: already open in [specify] — not registered again"
+      continue
+    fi
+
+    # (b) Take the next id NUMERICALLY.
+    # ⚠️ `sort` WITHOUT `-n` is wrong here and fails silently: ids are variable width,
+    # so lexicographically ISS-100 sorts BEFORE ISS-97, and `sort | tail -1` would hand
+    # back an id that is already in use. A collision is not self-announcing — the
+    # statistics table still reconciles — while two entries sharing an id make the
+    # address name neither of them.
+    next_id=$(grep -oE '^- \[[x ]\] ISS-[0-9]+:' "$ledger" | grep -oE '[0-9]+' | sort -n | tail -1)
+    next_id=$(( ${next_id:-0} + 1 ))
+
+    # (c) TWO writes in ONE pass: the entry, and the statistics row that summarises it.
+    awk -v cid="$cid" -v msg="$msg" -v today="$(date '+%Y-%m-%d')" \
+        -v newid="ISS-${next_id}" -v checklist="$REQUIREMENTS_CHECKLIST" '
+      BEGIN { in_sec = 0; blanks = 0; done = 0 }
+      function emit_body() {
+        print "- [ ] " newid ": 质量检查未通过 —— **" cid "**（source: /specpro-qc " today "）"
+        print "  **Problem**: " msg
+        print "  **Recommendation**: `/specpro-specify --review-issues` 消费本条：该项由 `FR-061` 判为**不通过**；完整结论见 `" checklist "`。规格的修复归**规格的生产者**，不由检查方代行（`FR-058`）。"
+        print "  **Related**: **`FR-058`** – **`FR-062`**（qc 的职责与写入面）· `" checklist "`"
+        done = 1
+      }
+      function flush_blanks() { while (blanks > 0) { print ""; blanks-- } }
+      # (1) the statistics row — a DERIVED summary, in the same pass as the entry.
+      # Written in a LATER step it is the known failure: the id enters the file before
+      # the entry exists, so an idempotency guard greping for that id concludes
+      # "already present" and skips the entry, while the summary still claims it landed.
+      /^\| \[specify\] \|/ {
+        n = split($0, f, "|"); total = f[3] + 1; pend = f[5] + 1
+        items = f[6]; gsub(/^[ \t]+|[ \t]+$/, "", items)
+        if (items == "") items = newid; else items = items " · " newid
+        printf "| [specify] | %d |%s| %d | %s |\n", total, f[4], pend, items
+        next
+      }
+      # (2) the entry, at the END of the [specify] section.
+      # ⚠️ NOT the end of the file. The statistics block sits at the top so that a naive
+      # append lands inside the LAST section; for any other section that misfiles the
+      # entry where its consumer never reads it — and nothing errors, because the entry
+      # still looks filed.
+      /^## \[specify\] Phase Issues$/ { in_sec = 1; print; next }
+      in_sec && (/^## \[/ || /^-->/) {
+        if (!done) { print ""; emit_body() }
+        flush_blanks(); in_sec = 0; print; next
+      }
+      in_sec && /^[ \t]*$/ { blanks++; next }
+      in_sec { flush_blanks(); print; next }
+      { print }
+      END { if (in_sec && !done) { print ""; emit_body() } flush_blanks() }
+    ' "$ledger" > "$ledger.tmp" && mv "$ledger.tmp" "$ledger" || {
+      rm -f "$ledger.tmp"
+      echo "   ⚠️ ${cid}: could not write the entry — see the error above" >&2
+      continue
+    }
+    REGISTERED_IDS+=("ISS-${next_id}")
+    echo "   → ${cid}: registered as ISS-${next_id} in [specify]"
+  done
+
+  # ⚠️ Verify mechanically after writing — the ledger is a file FOUR other commands also
+  # write into, so a structural break here surfaces as THEIR failure, later and elsewhere.
+  if [[ ${#REGISTERED_IDS[@]} -gt 0 && -x .specpro/scripts/bash/verify-ledger.sh ]]; then
+    if ! .specpro/scripts/bash/verify-ledger.sh >/dev/null 2>&1; then
+      echo "   ✗ ledger integrity FAILED after registering — run this and fix it:" >&2
+      echo "       .specpro/scripts/bash/verify-ledger.sh" >&2
+      echo "     The entries ARE written; what is wrong is the file's structure." >&2
+    fi
+  fi
+}
+```
+
+> **Fixture** (Constitution 2.2.1 — a criterion must carry a case set, including one that
+> **constructs an input making the criterion false**). Two cases, both observed:
+> - **Pass**: run the `awk` against a copy of the ledger → `verify-ledger.sh` reports
+>   `✓ actual 32/30/2 = table` and all invariants hold.
+> - **Fail**: run it with the statistics stanza removed → `✗ actual 32/30/2 ≠ table
+>   31/30/1`. ⚠️ **This second case is the one that matters**: it is the observation that
+>   the summary is not optional decoration — omitting it breaks the ledger.
+
+---
+
+## Helper Functions
+
+### record_finding()
+
+```bash
+# Collect ONE non-passing check into this run's finding set (FR-059).
+#
+# ⚠️ **This function writes NOTHING — and that is the change.** It used to append a line
+# to the clarification artifact, which belongs to `/specpro-specify` and holds
+# questions **the user** must answer. A criterion failure is not necessarily a user
+# question; it is a **finding for the spec's producer**. The write now happens once, in
+# `register_findings()`, which routes to the `[specify]` queue where a named consumer
+# reads it.
+#
+# ⚠️ **The pair (id, message) is kept, not just the id.** `FAILED_ITEMS` already carries
+# the ids, but a ledger entry needs prose; recording only the id would force the writer
+# to re-derive the sentence at write time, and re-derivation is where the specifics get
+# lost.
+record_finding() {
+  local check_id=$1
+  local issue=$2
+  FINDINGS+=("${check_id}"$'\t'"${issue}")
+}
+```
+
+### update_checklist()
+
+```bash
+update_checklist() {
+  # ⚠️ **REBUILD, not update — a ruling, not an optimisation** (FR-060, 2026-09-19).
+  # The file is replaced wholesale from the template on EVERY run: no history across
+  # runs, no cache, nothing carried over.
+  #
+  # ⚠️ **The rejected alternative was "build it once, then only re-check what failed."**
+  # It leaks: `spec.md` changes, and re-running only the FAILED set never re-examines an
+  # item that passed last time and has been broken since. This file's whole job is to be
+  # the verdict on **this** spec.
+  # ⚠️ It is also why nothing from a previous run may be kept here: **anything the
+  # template cannot produce dies at this line.** Measured 2026-09-19 — a hand-accumulated
+  # section in this file went from 10 rows to 0, and the file from 47086 to 13216 bytes,
+  # **with no error anywhere**.
+  cp "$REQUIREMENTS_TEMPLATE" "$REQUIREMENTS_CHECKLIST"
+
+  # Update with actual results — per-item `**Status**:` (T170).
+  #
+  # ⚠️ **This step used to be three comment lines saying it was omitted.** The audit of
+  # 2026-09-18 found the consequence: three gates (`/specpro-implement` §1.5.b ·
+  # `/specpro-tasks` §3.e · `/specpro-specify` §9.c) decide by reading this field, and
+  # **nothing produced it** — the checklist kept the template's placeholder, every item read
+  # as unresolved, and each of the three gates blocked. A consumer with no producer is not a
+  # gate, it is a wall.
+  #
+  # ⚠️ **The id list comes from the CHECKLIST's own headings, never from a list here.** A
+  # criterion added to the template must not be silently left blank, and a hand-written list
+  # would do exactly that (the same "a list fails by omission" shape as the section lists).
+  # ⚠️ An item that neither failed nor skipped is `x` — those are the only three outcomes a
+  # check has (`PASSED` / `FAILED` / `SKIPPED` are incremented on every path).
+  local tmp_status; tmp_status=$(mktemp)
+  awk -v failed="${FAILED_ITEMS[*]:-}" -v skipped="${SKIPPED_ITEMS[*]:-}" '
+    /^### / { id = $2; sub(/:$/, "", id) }
+    # ⚠️ ONLY item headings. The template also contains a `- [ ] **Status**: …` line inside a
+    # fenced EXAMPLE, and a rule written as "every Status line" rewrote that too — corrupting
+    # the documentation inside the template itself. Measured: the first version of this writer
+    # did exactly that. A check-id shape is the discriminator.
+    # ⚠️ **No apostrophe anywhere in this awk body** (`T225`, found in passing): an `awk
+    # ''...''` program sits inside a bash SINGLE-QUOTED string, so one apostrophe **closes the
+    # string** and the rest of the block becomes a top-level syntax error. This line used to
+    # read "the template''s own documentation" and did exactly that — the whole `update_checklist`
+    # block could not be extracted and run as written. (`verify-doc-shell.sh` cannot catch it:
+    # full shell syntax is outside its declared coverage.)
+    /^- \[[ x]\] \*\*Status\*\*:/ && id ~ /^[A-Z]+[0-9]+$/ {
+      if      (index(" " failed " ", " " id " ") > 0) v = "✗ Failed"
+      else if (index(" " skipped " ", " " id " ") > 0) v = "⊘ Skipped"
+      else                                             v = "x"
+      print "- [x] **Status**: " v
+      next
+    }
+    { print }
+  ' "$REQUIREMENTS_CHECKLIST" > "$tmp_status"
+  # ⚠️ The checkbox is set to `[x]` on EVERY item: completion is decided by the VALUE, not by
+  # the box (the template says so itself) — and leaving the box unticked while the value says
+  # `x` is the "two sources" shape this project keeps correcting.
+  #
+  # ⚠️ **The write goes through the door, and the door guards.** Its contract: a transformer
+  # that exited non-zero, or produced an empty result, MUST NOT be allowed to replace the
+  # destination. That guard IS the `ISS-111` / `T164` lesson — an earlier version wrote back
+  # unconditionally and destroyed the target on a failed transform (measured then: a 48-byte
+  # file became 0 bytes).
+  # ⚠️ **The destination is passed AT THE CALL SITE** (T164). It used to be hardcoded inside
+  # the door as `$FEATURE_SPEC`, so every run — the read-only default included — replaced
+  # `spec.md` with the checklist. A hardcoded destination is an assumption the caller cannot
+  # see, which is exactly why it went unnoticed for so long.
+  scripts/bash/qc-auto-fix.sh apply-fix "$tmp_status" $? "$REQUIREMENTS_CHECKLIST" || return 1
+
+  # --- the summary block, in the SAME rebuild pass (`T225` / `ISS-193`) ---------------------
+  #
+  # ⚠️ **`T170` gave the per-item values a producer and left this block behind.** The summary
+  # kept the template's placeholders — `**Status**: [PASS | BLOCK]` · `**Passed**: [X]` ·
+  # `**Failed**: [Y]` — and `**Total Items**: 11` only looked right because the template
+  # **spells that literal**. Consequences, both silent:
+  #   · **five readers across four commands** read a value that never existed
+  #     (`status` · `analyze` · `implement` · `plan` · `tasks`); each fell through to
+  #     "not BLOCK ⇒ proceed", so nothing stopped — it just never decided
+  #   · two of `verify-shapes.sh`'s three SHAPE-4 registrations were **permanently
+  #     `⊘ not executable`**, and a check that can never run is indistinguishable from one
+  #     that does not exist (shape 6)
+  #
+  # ⚠️ **Re-derive the numbers from the text just written — never from `$PASSED` / `$FAILED`.**
+  # The counters are a second source for the same fact, and SHAPE-4 exists precisely because
+  # "the report says N" must be comparable against "the artifact contains N". Reading both
+  # from one text makes them agree **by construction**, which is the only version that cannot
+  # drift. (The counters stay: they drive the exit code and the console summary.)
+  #
+  # ⚠️ **Two discriminators, and BOTH are load-bearing** — the first version of this writer
+  # had only the first and produced `**Total Items**: 12` against a true count of 11:
+  #   1. **the `- [ ]` prefix** — the template's *summary* line is `**Status**: [PASS | BLOCK]`
+  #      at line start, and it must not be counted as an item
+  #   2. **fence state** — the template carries a fenced EXAMPLE whose `**Status**: …` line
+  #      starts with `- [ ]` and reads `⊘ Skipped`. Counting it inflates the total **and the
+  #      inflation is silent** — which is precisely the disagreement `verify-shapes.sh`'s
+  #      `SHAPE-4 checklist-total` exists to report. ⚠️ **The per-item writer above already
+  #      documented this same trap**; writing the second one without it reproduced the defect
+  #      the first one had been fixed for, in the same function.
+  local tmp_summary; tmp_summary=$(mktemp)
+  awk '
+    # ⚠️ **The fence test is spelled by CONCATENATION — `"`" "`" "`"` — and that is not
+    # stylistic**: a literal run of three backticks **inside this fenced block would close
+    # the block**, truncating the snippet for every fence-aware reader (the embedded-shell
+    # verifier extracts snippets by fence; it would then scan half a program and call the
+    # result clean). Measured: the literal spelling was written first and did exactly that.
+    { t = $0; sub(/^[[:space:]]+/, "", t) }
+    substr(t, 1, 3) == "`" "`" "`" { infence = !infence; lines[NR] = $0; next }
+    /^- \[[ x]\] \*\*Status\*\*:/ && !infence {
+      total++
+      if      ($0 ~ /\*\*Status\*\*:[[:space:]]*x[[:space:]]*$/) passed++
+      else if ($0 ~ /\*\*Status\*\*:[[:space:]]*✗/)              failed++
+      lines[NR] = $0
+      next
+    }
+    { lines[NR] = $0 }
+    END {
+      # FR-061: pass ⟺ no ✗. `⊘ Skipped` is neither — it must not tip this either way, so it
+      # is counted as neither passed nor failed. ⚠️ `+ 0` is not cosmetic: an unset awk
+      # variable concatenates as the EMPTY STRING, so `**Failed**: ` would render blank
+      # instead of `0`.
+      status = (failed == 0) ? "PASS" : "BLOCK"
+      for (i = 1; i <= NR; i++) {
+        l = lines[i]
+        if      (l ~ /^\*\*Status\*\*: /)      print "**Status**: " status
+        else if (l ~ /^\*\*Total Items\*\*: /) print "**Total Items**: " (total  + 0)
+        else if (l ~ /^\*\*Passed\*\*: /)      print "**Passed**: "      (passed + 0)
+        else if (l ~ /^\*\*Failed\*\*: /)      print "**Failed**: "      (failed + 0)
+        else                                   print l
+      }
+    }
+  ' "$REQUIREMENTS_CHECKLIST" > "$tmp_summary"
+  scripts/bash/qc-auto-fix.sh apply-fix "$tmp_summary" $? "$REQUIREMENTS_CHECKLIST" || return 1
+  # ⚠️ **There is no "QC history row" step any more.** It appended a row per iteration
+  # before the file's end-of-file sentinel — and with the loop gone (FR-060) there are no
+  # iterations to record, and with the file rebuilt every run there is nothing for a
+  # history to accumulate into. The sentinel itself STAYS: it is a boundary marker, and
+  # `plan.md` → Constraint 7 shape 8 still cites it as a working example of one.
+}
+```
+
+## Notes
+
+- **Called automatically by `/specpro-specify`** — on the spec's first creation and on
+  **every** update (`FR-062`). The trigger belongs to the spec's change, not to the
+  caller's memory. It may also be run directly to see the current verdict.
+- **It reports; it does not repair** (`FR-058`). Every non-passing criterion becomes an
+  entry in the ledger's `[specify]` queue (`FR-059`), whose consumer is
+  `/specpro-specify --review-issues` — **that** is where the spec gets fixed.
+- **The checklist is rebuilt from the template on every run** (`FR-060`): there is no
+  history across runs, no cache, and nothing carried over. ⇒ Do **not** hand-accumulate
+  content in `specs/checklists/requirements.md`; the next run will delete it silently.
+  Cross-run records belong in an artifact that is not rebuilt — see
+  `specs/audit/known-tool-defects.md` for the worked case.
+- **The verdict is the per-item values** (`FR-061`): `x` = passed, `⊘ Skipped` = the
+  criterion does not apply here, `✗ Failed` = did not pass. **Passing means "no `✗`"** —
+  a skip is neither a pass nor a failure and MUST NOT be folded into either.
+- **This command does not decide feasibility.** It used to end by declaring a project
+  "not feasible" when it could not repair its way to a pass — a conclusion it had no
+  standing to reach, since it never had the repair power to test it. It now stops at
+  the verdict, and the queue carries the rest.