specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.specify.md

@@ -0,0 +1,1449 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs:
+  - label: Build Technical Plan
+    agent: specpro-plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: specpro-clarify
+    prompt: Clarify specification requirements
+    send: true
+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.
+  - artifact: specs/spec.md
+    unit: "whole file - template structure and section order preserved; plus the per-item Lifecycle fields"
+  - artifact: specs/assumptions.md
+    unit: "A0NN entries (Status / Answer / Resolution) plus the Decision Path and Summary sections"
+  - artifact: specs/implement_issues.md
+    unit: "the [specify] section -> its own entries marked [x]; the statistics table (**its own row only** — seven commands declare this artifact); appended ISS-NNN entries in any section — registration is routing; only [x]-marking is section-scoped"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — detect the artifact, default to incremental** ⚠️ [settled 2026-09-13]:
+
+**Before writing `specs/spec.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/spec.md ] && echo EXISTS || echo NEW    # -s: exists AND non-empty (an empty placeholder counts as NEW)
+```
+
+| Detection | Mode |
+|-----------|------|
+| **NEW** (absent or empty) | **Initial** — generate from scratch |
+| **EXISTS** | **Incremental** — evolve it; **never silently regenerate from scratch** |
+
+**Overwriting an existing artifact requires explicit, confirmed intent:**
+1. Only when the user *explicitly* asks (in their own words) does the initial path run on an existing artifact.
+2. **Even then, confirm once more before writing** — name the artifact that will be replaced and what will be lost; wait for the answer.
+3. **Silence is not consent.** An unspecified run on an existing artifact is ALWAYS incremental.
+
+> **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 (`EXISTING_SPEC` check · "creates a NEW file" · `NEVER overwrite` · "incremental regeneration" · `AUTO_MODE=false`), and **three had none at all** — not by decision, but because the discipline had no shared carrier. Overwriting an artifact the user has been evolving is not recoverable within the session; the cost of asking is one prompt.
+
+
+### 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
+
+**Artifact Language Rule** 🌐 [CRITICAL — applies to ALL generated content]:
+- **Prose content** (descriptions, rationale, scenario text, guidance) follows the project's **Artifact Language** setting — from `specs/constitution.md` → **Artifact Language** field; default `en` when absent
+- **Structural anchors are ALWAYS English**, regardless of the artifact language: section headings from the template, item ID prefixes (US/FR), status enums, and table column names — exactly as written in the template
+- **Entry field labels are structural anchors too** (`source:`, `Evidence:`, `Fix Direction:`) — never translated, even when the surrounding prose is not English. They exist to be **searched**: an entry's fields must be greppable across artifacts and projects, and a translated label silently drops out of every consumer's scan.
+- Rationale: fixed anchors keep artifacts machine-parseable across specpro commands and keep instructions ↔ artifacts aligned for review
+
+The text the user typed after `/specpro-specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Check for --review-issues argument** 🆕:
+
+   **Purpose**: Process implement issues submitted from the implement phase
+
+   a. **Parse arguments**:
+      - If `$ARGUMENTS` contains `--review-issues`:
+  * **Skip the question below**; proceed directly to step 1b (review issues)
+- Else: **detect, then ask** ⚠️ [settled 2026-09-13]:
+  * Check the `[specify]` section of `specs/implement_issues.md` for open `[ ]` entries
+  * **None** → continue with normal specification generation (step 2+). **No prompt.**
+  * **Some** → **ask**: "N open `[specify]` issues in specs/implement_issues.md. Process them first, or run normally?"
+    - *Process first* → proceed to step 1b (review issues)
+    - *Run normally* → continue with normal specification generation (step 2+)
+  * **Rationale**: the flag used to be the whole switch — not passing it left pending issues **silently unprocessed**, passing it meant overriding the work the user actually wanted, and **which issues were pending was invisible until the command ran**. Detect-then-ask makes it an explicit choice; the flag now only means *"I already know — don't ask"*.
+    (Same model as `/specpro-implement` and `/specpro-test-plan` — see TOOL-008.)
+
+   b. **Review implement issues**:
+      - Read `specs/implement_issues.md`
+      - Extract all issues from `[specify]` section
+      - Filter for issues marked `[ ]` (pending) only
+      - If no pending issues found:
+        * Display: "✓ No pending [specify] issues to process"
+        * Exit
+
+      - Display issue summary:
+        ```markdown
+        📋 [specify] Issues Review
+
+        Found N pending [specify] issues:
+        1. [ ] ISS-XXX: Issue description
+        2. [ ] ISS-XXX: Issue description
+        ...
+        ```
+
+      - For each pending issue:
+        * Read issue details (description, problem, suggestion)
+        * Determine appropriate action:
+          - **Add new requirement**: Insert new FR into spec.md
+          - **Clarify existing requirement**: Update existing FR description
+          - **Resolve conflict**: Modify conflicting FRs
+        * Apply the change to spec.md
+        * Mark issue as `[x]` in implement_issues.md
+        * Display: "✓ Processed ISS-XXX: [action taken]"
+
+      - Update the statistics table at the **top** of `implement_issues.md` (its position is deliberate — see the note below)
+      - **Edit order and idempotency check** ⚠️ [a silent false-skip, observed 2026-09-13]: write the **entry body first** (into its own section), then the derived summaries (statistics table + `Last Updated`) — never the reverse. A derived summary written first introduces the new ID into the file's text before the entry exists, so an idempotency guard that greps the file for that ID falsely concludes "already present" and **skips the entry**, while the summaries still claim it landed. For the same reason the guard MUST match the entry body's **line-start pattern**, never a full-text keyword search:
+        ```bash
+        grep -qE '^- \[[x ]\] ISS-<N>:' specs/implement_issues.md   # correct — matches an ENTRY, not a mention
+        # grep -q 'ISS-<N>' …                                        # wrong — also matches the statistics Pending-Items column, the Last Updated line, cross-references
+        ```
+  - **General rule: every grep/awk example shown in an instruction or template must itself obey the line-start pattern** (TOOL-009) — the executing side copies examples verbatim, so an example that uses a whole-file match propagates the same misjudgment to everyone who copies it. This file has already corrected its own sentinel self-check command under this rule.
+        `.specpro/scripts/bash/verify-ledger.sh` reports the resulting inconsistency as a count mismatch — but only if it is run, and by then the entry is already missing.
+      - **Entry placement**: append new entries to the end of their own section, never to the end of the file. The file's statistics block sits at the top precisely so that "append to the end" lands inside the last section rather than between sections; moving or duplicating a section header breaks that and produces an orphaned section no `--review-issues` run will read.
+      - **Verify mechanically after writing**: run `.specpro/scripts/bash/verify-ledger.sh` — it checks entry section membership, statistics-vs-actual counts, and the trailing newline in one pass (non-zero exit names the violation). Marking issues `[x]` changes the counts, so this applies to this command too, not only to commands that append. A pre-commit hook enforces the same check.
+
+      c. **Run quality validation on updated spec** 🆕:
+         ```bash
+         echo ""
+         echo "📋 Running quality validation on updated spec.md..."
+         echo "   Validating against the checklist's quality criteria..."
+         echo "   QC rebuilds the checklist and queues every non-passing item for THIS command."
+         echo ""
+
+         # ⚠️ **No `--auto`, no authorisation parameter** (2026-09-19 ruling, FR-058).
+         # This command used to delegate the REPAIR to `/specpro-qc` and call it a
+         # quality gate. ⚠️ That made the judge the repairer, and it is why the caller
+         # had to say which artifact it owned — a parameter that existed only to make a
+         # boundary violation declareable. **The repair is this command's own job**, and
+         # the check's job is to produce the list of what needs repairing.
+         # ⚠️ **The loop closes here, and it is short on purpose**: qc queues its
+         # non-passing items into the `[specify]` section — **the very section this
+         # command consumes** — so the fix path is "read the queue, fix the spec,
+         # re-run the check", not "hope the checker also repairs".
+         /specpro-qc --scope="incremental"
+
+         QC_EXIT_CODE=$?
+
+         if [[ $QC_EXIT_CODE -eq 0 ]]; then
+             echo ""
+             echo "✅ Quality validation PASSED"
+             echo "   All quality criteria met."
+             echo "   specs/checklists/requirements.md rebuilt for this run"
+         else
+             echo ""
+             echo "❌ Quality validation FAILED"
+             echo "   One or more criteria did not pass. **The non-passing ones are now"
+             echo "   entries in the [specify] queue** (FR-059) — that is this command's"
+             echo "   own queue, so they are fixed HERE, by the spec's producer."
+             echo ""
+             echo "Check specs/checklists/requirements.md for the per-item verdicts."
+             echo "Then process the queued entries with --review-issues."
+             exit 1
+         fi
+         ```
+
+      d. **Display completion summary**:
+         ```markdown
+         ✅ Completed [specify] issues review and quality validation
+
+         Processed: N issues
+         Updated: specs/spec.md
+         Validated: Quality check passed — no criterion failed (`FR-061`)
+         Marked as [x] in implement_issues.md
+
+         ⚠️ IMPORTANT: Next steps
+
+         1. Run /specpro-plan to update technical design
+         2. Run /specpro-tasks to update task list
+         3. Then you can process [plan] or [tasks] issues
+
+         Do NOT process [plan] or [tasks] issues yet.
+         They require the plan/tasks update first.
+         ```
+2. **Pre-flight Checks** ✨ (Fast-fail validation before core logic):
+
+   **Purpose**: Verify environment and prerequisites before executing specification generation
+
+   a. **Required files check**:
+      ```bash
+      CONSTITUTION="specs/constitution.md"
+      SPEC_TEMPLATE=".specpro/templates/spec-template.md"
+      ASSUMP_TEMPLATE=".specpro/templates/assumptions-template.md"
+
+      if [[ ! -f "$CONSTITUTION" ]]; then
+          echo "❌ ERROR: Constitution not found at $CONSTITUTION"
+          echo "Please run /specpro-constitution to create the project constitution first."
+          exit 1
+      fi
+
+      if [[ ! -f "$SPEC_TEMPLATE" ]]; then
+          echo "❌ ERROR: Spec template not found at $SPEC_TEMPLATE"
+          exit 1
+      fi
+
+      if [[ ! -f "$ASSUMP_TEMPLATE" ]]; then
+          echo "❌ ERROR: Assumptions template not found at $ASSUMP_TEMPLATE"
+          exit 1
+      fi
+      ```
+
+   b. **Directory permissions check**:
+      ```bash
+      # After running create-new-feature.sh to get FEATURE_DIR
+      if [[ ! -d "$FEATURE_DIR" ]]; then
+          echo "❌ ERROR: Feature directory not writable: $FEATURE_DIR"
+          exit 1
+      fi
+
+      # Test write permission
+      touch "$FEATURE_DIR/.test_write" 2>/dev/null || {
+          echo "❌ ERROR: Cannot write to $FEATURE_DIR"
+          exit 1
+      }
+      rm -f "$FEATURE_DIR/.test_write"
+      ```
+
+   c. **Constitution validation**:
+      ```bash
+      # Verify Constitution is not empty
+      CONSTITUTION_SIZE=$(wc -c < "$CONSTITUTION")
+      if [[ $CONSTITUTION_SIZE -lt 100 ]]; then
+          echo "⚠️  WARNING: Constitution appears to be empty or very small"
+          echo "Please verify specs/constitution.md has content"
+      fi
+
+      # Count principles/articles
+      PRINCIPLE_COUNT=$(grep -c "^##\|^###\|^#" "$CONSTITUTION" 2>/dev/null || true)
+      : "${PRINCIPLE_COUNT:=0}"
+      if [[ $PRINCIPLE_COUNT -lt 2 ]]; then
+          echo "⚠️  WARNING: Constitution has fewer than 2 sections"
+          echo "Consider adding more principles before proceeding"
+      fi
+      ```
+
+   d. **Report check completion**:
+      ```markdown
+      ✓ Pre-flight checks passed
+      - Constitution: ✅ ($PRINCIPLE_COUNT sections)
+      - Templates: ✅ (spec, assumptions)
+      - Permissions: ✅ (writable)
+      ```
+
+   **Fast-fail**: If any check fails, abort immediately with clear error message
+
+1. **Generate a concise short name** (2-4 words) for tracking:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "user-auth", "plugin-architecture")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, protocol acronyms)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+
+2. **Check existing specification and determine operation mode**:
+
+   a. **Check if spec.md exists**:
+      ```bash
+      SPEC_FILE="specs/spec.md"
+
+      if [[ -f "$SPEC_FILE" ]]; then
+          EXISTING_SPEC=true
+          # Read existing spec to gather statistics
+          # ⚠️ **All three of the old patterns were anchored on forms the template never
+          # emits** (T094/ISS-63) — measured on a spec built from `spec-template.md`:
+          # US 0 ≠ 11 · FR 0 ≠ 57. The User-Story heading is `### US1 - …`; the FR line is an
+          # INDENTED bold list item (`  - **FR-XXX**: …`), so a line-start anchor `^- ` misses
+          # every one of them. Both now use the same patterns as `status.md` — that file
+          # documents this format contract in a comment and MUST stay consistent with `qc`.
+          US_COUNT=$(grep -cE '^### US[0-9]+ ' "$SPEC_FILE" 2>/dev/null || true)
+          FR_COUNT=$(grep -cE '^[[:space:]]*- \*\*FR-[0-9]+[A-E]?\*\*:' "$SPEC_FILE" 2>/dev/null || true)
+          : "${US_COUNT:=0}"
+          : "${FR_COUNT:=0}"
+          # ⚠️ A third counter, `ASSUMP_COUNT`, used to sit here. It is **removed, not
+          # fixed**: (a) its pattern (`^### **[A-`) matched nothing, (b) it scanned
+          # `$SPEC_FILE` while assumptions live in `specpro.assumptions.md` — the wrong
+          # artifact — and (c) it was **never read** by anything (not in the statistics
+          # display below). A wrong predicate inside a value nobody reads is pure liability
+          # (the shape this project keeps finding: 写了却从未被调用的东西).
+
+          # Extract current version
+          CURRENT_VERSION=$(grep "^**Version**:" "$SPEC_FILE" | head -1 | awk '{print $2}')
+      else
+          EXISTING_SPEC=false
+      fi
+      ```
+
+   b. **Determine operation mode**:
+
+      **If NO existing spec** (`$EXISTING_SPEC = false`):
+      - This is **initial specification**
+      - Set `UPDATE_MODE=false`
+      - Set `SPEC_VERSION="0.1"`
+      - Run script: `.specpro/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"`
+      - Proceed to step 3 (load Constitution, generate spec)
+
+      **If existing spec EXISTS** (`$EXISTING_SPEC = true`):
+      - This is an **evolution iteration**
+      - Ask user for intent:
+        ```markdown
+        ## Existing Specification Detected
+
+        You already have a specification for this application:
+
+        **Current Spec**: Version $CURRENT_VERSION
+        **Statistics**:
+        - User Stories: $US_COUNT
+        - Functional Requirements: $FR_COUNT
+
+        **Your Input**: "$ARGUMENTS"
+
+        **What do you want to do?**
+
+        1. **UPDATE** existing spec (evolve the application)
+           - Keep all existing content
+           - Add new features/requirements
+           - Update existing sections if specified
+           - Preserve validated constraints
+           - Generate Change Summary with [create]/[update]/[deprecated] tags (changed items only — unchanged items are not logged)
+           - Auto-commit to preserve history
+
+        2. **VIEW** current spec first
+           - Display summary of current specification
+           - Show User Stories, Requirements, Constraints
+           - Then ask again
+
+        Your choice (1/2):
+        ```
+
+      - **If user chooses 1 (UPDATE)**:
+        - Set `UPDATE_MODE=true`
+        - Parse current version (e.g., "0.1")
+        - Increment version: `NEW_VERSION=$(echo "0.1" | awk -F. '{print $1"."$2+1}')`
+        - Set `SPEC_VERSION=$NEW_VERSION`
+        - Run script to get SPEC_FILE path: `.specpro/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"`
+        - Proceed to step 3 with merge logic
+
+      - **If user chooses 2 (VIEW)**:
+        - Display current spec summary:
+          ```markdown
+          ## Current Specification Summary
+
+          ### User Stories ($US_COUNT total)
+          [List first 10 stories with priorities]
+
+          ### Key Functional Requirements
+          [List key requirements]
+
+          ### Constitution Constraints
+          [List key constraints]
+          ```
+        - Ask again for choice 1/2
+
+2.5. **Dynamic assumption resolution** (for initial specification only):
+
+   **Purpose**: Identify and resolve CRITICAL architectural assumptions that MUST be clarified BEFORE spec generation. Unlike clarifications (which improve spec quality post-generation), these assumptions block spec generation because they fundamentally affect the architecture and direction.
+
+   **This step ONLY applies to UPDATE_MODE=false (initial specification)**. Skip this step if UPDATE_MODE=true.
+
+   a. **Initial analysis of user input**:
+      - Analyze the user's feature description for CRITICAL architectural decisions
+      - Identify decisions that affect: architecture, scope, platform, deployment, data model
+      - Ask: "What is the MOST CRITICAL unresolved decision without which we cannot proceed?"
+      - Examples of critical decisions:
+         * "Notepad" → Local vs Web? (affects architecture, data model, deployment)
+         * "Chat app" → Real-time vs Async? (affects protocol, infrastructure)
+         * "Multi-user" → Single-device vs Collaborative? (affects sync, backend)
+         * "High performance" → What's the target scale? (affects architecture choices)
+      - Load `.specpro/templates/assumptions-template.md` to understand the required format
+
+   b. **Generate first-level assumptions** (if any):
+      - If CRITICAL assumptions are identified:
+         1. Create `specs/assumptions.md` using the template
+         2. Add 1-3 initial assumptions to the file
+         3. For each assumption, include:
+            - Status: [ ] Pending
+            - Context: What led to this question (user input)
+            - Impact: What this affects (architecture, scope, platform, etc.)
+            - Question: Clear, specific question
+            - Options: 2-4 mutually exclusive options with implications
+            - Recommended: Best option based on context with reasoning
+         4. Display blocking message:
+            ```markdown
+            ## 🔑 Critical Assumptions Detected
+
+            Before I can generate the specification, I need to clarify these CRITICAL decisions
+            that affect the architecture and direction of the feature:
+
+            **Assumptions File**: specs/assumptions.md
+            - Total: N critical assumptions
+
+            These MUST be resolved before spec generation can proceed.
+
+            Let's resolve them one by one...
+            ```
+      - If NO critical assumptions are identified (user input is clear):
+         - Skip assumption resolution
+         - Proceed directly to Step 3 (Load Constitution)
+         - Note: "No critical assumptions detected. User input is sufficiently clear to proceed."
+
+   c. **Interactive resolution loop** ✨ ENHANCED with progress tracking:
+
+      **WHILE** there are pending assumptions (status `[ ]`):
+
+      1. **Present ONE current assumption**:
+         - Display assumption with:
+           - Progress indicator: "### Question [current]/[total]: [ID]"
+           - ID, Question, Context, Impact
+           - Options table (if applicable)
+           - Recommended option with reasoning
+         - Format:
+           ```markdown
+           ### Question [ID]: [Question Summary]
+
+           **Context**: [What led to this question]
+
+           **Impact**: [What this affects]
+
+           **Question**:
+           [Full question text]
+
+           **Options** (if applicable):
+           | Option | Description | Implications |
+           |--------|-------------|--------------|
+           | A | [Option A] | [Implications] |
+           | B | [Option B] | [Implications] |
+           | C | [Option C] | [Implications] |
+
+           **Recommended**: Option [X] - [Reasoning]
+
+           Your answer (option letter or custom):
+           ```
+
+      2. **Wait for user response**
+         - Accept: option letter (A/B/C), "yes"/"recommended" for recommendation, or custom answer
+         - Validate response maps to options or is appropriate
+
+      3. **Update assumptions.md immediately**:
+         - Mark assumption as `[x]` Resolved
+         - Fill in "Answer" field with user's response
+         - Fill in "Resolution" field with:
+           - How this answer guides spec generation
+           - Related architectural decisions
+           - Next assumptions that may emerge (see step 3d)
+         - Save file (atomic write)
+         - Display progress: "✓ Resolved [current]/[total] assumptions"
+
+      4. **Contextual re-analysis** (KEY STEP):
+         - Based on ALL previous answers + user input
+         - Ask: "Based on this answer, what's the NEXT critical decision?"
+         - Identify NEW assumptions that emerge:
+           * Check if previous decisions reveal new critical questions
+           * Check if decisions eliminate previously planned questions
+         - Generate next assumption (if any):
+           * Add to assumptions.md with updated context
+           * Include "Context": Previous decisions that led to this
+           * Mark as `[ ]` Pending
+         - If NO new assumptions emerge:
+           * Continue loop (there may be other pending assumptions)
+
+      5. **Check loop condition**:
+         - If there are still pending assumptions → Continue to next iteration (back to step c.1)
+         - If ALL assumptions resolved → Exit loop
+
+   d. **Completion of assumption resolution**:
+
+      1. **Display summary**:
+         ```markdown
+         ✓ All critical assumptions resolved
+
+         **Total Assumptions Resolved**: N
+         **Assumptions File**: specs/assumptions.md
+
+         **Decision Path**:
+         - A001: [Answer] → [Impact]
+         - A002: [Answer] → [Impact] (emerged after A001)
+         - A003: [Answer] → [Impact] (emerged after A001, A002)
+
+         **Architectural Direction**:
+         - [Summary of decisions]
+         - [Key implications for spec generation]
+
+         Proceeding with spec generation based on these decisions...
+         ```
+
+      2. **Update assumptions.md**:
+         - Add "Decision Path" section showing complete decision history
+         - Add "Summary" section with totals
+         - Update "Status": Resolved
+         - Mark "Ready for Spec Generation": YES
+
+      3. **Store context for spec generation**:
+         - Keep all resolved assumptions accessible
+         - Use these decisions to guide Step 5 (specification generation)
+         - Reference when generating FRs, User Stories, architecture decisions
+
+   e. **Skip assumption resolution** (if UPDATE_MODE=true or no critical assumptions):
+      - This step is skipped for UPDATE_MODE=true (updating existing spec)
+      - For initial specs with no critical assumptions, skip and proceed
+      - Note: Existing specs should have already resolved assumptions during initial creation
+
+3. **Load Constitution and identify applicable principles** ✨ ENHANCED with incremental caching:
+
+   **Purpose**: Ensure the feature specification complies with project principles defined in the Constitution, regardless of Constitution structure or version.
+
+   a. **Detect operation mode** ✨ NEW:
+      ```bash
+      CACHE_FILE=".specpro/cache/constitution-matching.md"
+
+      # ⚠️ **The cache is keyed on the CONSTITUTION's CONTENT, not on the file's existence**
+      # (`T236` / `ISS-209`). The constitution is **amended** — its `**Version**` /
+      # `**Last Amended**` move — and a hit keyed on nothing would then serve a principle set
+      # that no longer holds, **silently**, because the steps that would have re-derived it are
+      # the ones being skipped. The key is what makes reuse safe: a moved constitution is a MISS.
+      # `shasum` (macOS/BSD) and `sha256sum` (GNU) — the repository's usual portability pair.
+      CONSTITUTION_HASH=$( (shasum -a 256 specs/constitution.md 2>/dev/null \
+                            || sha256sum specs/constitution.md 2>/dev/null) | cut -d' ' -f1)
+
+      if [[ "$UPDATE_MODE" = "false" ]]; then
+          # Initial spec: Full Constitution matching
+          CACHE_MODE="generate"
+      elif [[ -n "$CONSTITUTION_HASH" ]] && [ -f "$CACHE_FILE" ] \
+           && grep -qF "**Constitution Hash**: $CONSTITUTION_HASH" "$CACHE_FILE"; then
+          # Hit AND the constitution is unchanged since the cache was written.
+          CACHE_MODE="reuse"
+      else
+          # Absent — or written against a constitution that has since moved ⇒ regenerate.
+          CACHE_MODE="generate"
+      fi
+      ```
+
+   a2. **On a cache HIT, the matching is already done — read it, do not re-derive** ⚠️:
+      ```bash
+      if [[ "$CACHE_MODE" = "reuse" ]]; then
+          echo "✓ Reusing Constitution matching from cache (constitution unchanged: ${CONSTITUTION_HASH:0:12})"
+          cat "$CACHE_FILE"
+      fi
+      ```
+
+      ⇒ **When `CACHE_MODE=reuse`, SKIP steps b through f.** The matched domains, principles and
+      constraints are exactly what the cache holds, so re-deriving them is the work the cache
+      exists to avoid. Continue at `g`, which on a reuse leaves the file untouched.
+
+      ⚠️ **Before this step existed, `CACHE_MODE` was written and never read** (`T236` / `ISS-209`):
+      `g` decided only *whether to write*, so a hit could not change any behaviour, and the
+      `✓ Reusing Constitution matching from cache` line was the mechanism's only consumer. A cache
+      nothing reads is not a cache — it is a file that grows and a branch nothing takes. ⚠️ **The
+      repo names this shape directly** (`CLAUDE.md` → 「改机制前先核验它是否接在执行链上」: "写了却从未被调用的缓存").
+
+   b. **Read Constitution**:
+      - Load `specs/constitution.md`
+      - Parse ALL principles, requirements, and governance rules
+      - Do NOT assume any specific structure (Articles, Sections, etc.)
+      - Store for domain-based matching
+
+   c. **Identify feature domains** from the user's feature description:
+      - Analyze the user's input description for key terms
+      - Map to feature domains using these keyword patterns:
+
+        | Domain | Trigger Keywords | Constitution Search Terms |
+        |--------|-----------------|---------------------------|
+        | **Network/Connectivity** | connect, network, socket, remote, server, client, tcp, udp | network, async, blocking, I/O, performance, concurrent, connection |
+        | **Multiplatform** | Android, iOS, Desktop, cross-platform, platform, shared | multiplatform, platform, shared module, common, expect, actual |
+        | **Security/Privacy** | password, authentication, encrypt, credentials, token, secret, oauth, login | security, privacy, encryption, credential, logging, sensitive, secure |
+        | **Protocol/Codec** | encoding, decoding, protocol, codec, format, parse, serialize, compress | protocol, test, coverage, risk, high-risk, test-first, encoding, decoding |
+        | **UI/UX** | interface, display, render, screen, view, component, widget, button, dialog | UI, interface, user, experience, low-risk, interface component |
+        | **Data/Persistence** | database, storage, save, load, persist, cache, file, record | data, persistence, storage, database, serialization |
+        | **Performance** | speed, latency, throughput, concurrent, optimize, fast, slow | performance, resource, latency, throughput, optimization |
+
+   c. **Match feature domains to Constitution principles** (keyword-based, NOT article-number-based):
+      - For each identified domain, search Constitution content for related principles:
+        - Use the "Constitution Search Terms" from the table above
+        - Search in principle titles, requirement text, and governance sections
+        - Do NOT rely on article numbers or section names
+      - Example matching logic:
+        ```
+        If "Network/Connectivity" domain detected:
+            Search for principles containing: "network", "async", "blocking", "I/O", "performance"
+            Match might be: "Article V: Performance & Resource Management"
+            OR: "Section 3: Network Operations"
+            OR: Any principle with "network I/O MUST use async patterns"
+
+        If "Protocol/Codec" domain detected:
+            Search for principles containing: "protocol", "test", "coverage", "risk", "high-risk"
+            Match might be: "Article IV: Risk-Based Quality Assurance"
+            OR: "Section: Testing Requirements"
+            OR: Any principle with "Protocol implementations require Test-First"
+        ```
+
+   d. **Extract matched principle requirements**:
+      - For each matched principle, extract:
+        - Principle title/heading
+        - Specific MUST/SHOULD requirements
+        - Risk level (if defined, e.g., "High-Risk Module")
+        - Testing requirements (if defined, e.g., "Test-First MANDATORY")
+      - Create a constraint summary for spec.md
+
+   e. **Generate Constitution Constraints section** (to be inserted into spec.md):
+      - Format matched principles as constraints:
+        ```markdown
+        ## Constitution Constraints
+
+        This feature must comply with the following principles from the project Constitution:
+
+        ### [Principle Title]
+        - **Requirement**: [Specific MUST/SHOULD statement from Constitution]
+        - **Source**: Constitution - [Principle Section]
+        - **Risk Level**: [If defined, e.g., "High-Risk Module (Network Transport)"]
+        - **Implications**: [What this means for the feature]
+
+        ### [Another Principle Title]
+        - **Requirement**: [Specific requirement from Constitution]
+        - **Source**: Constitution - [Principle Section]
+        - **Risk Level**: [If defined]
+        - **Implications**: [What this means for the feature]
+        ```
+      - If NO principles match the feature domains, document this:
+        ```markdown
+        ## Constitution Constraints
+
+        No specific Constitution principles were identified as applicable to this feature based on the domain analysis.
+        ```
+
+   f. **Apply constraints to Functional Requirements** (during step 5.c generation):
+      - When generating functional requirements, incorporate Constitution constraints
+      - Example: If Constitution requires "Network I/O MUST use async patterns" and feature involves "connect to server":
+        - FR-xxx: System MUST connect to the server using non-blocking async I/O (per Constitution)
+
+   g. **Cache Constitution matching results** ✨ NEW:
+      ```bash
+      CACHE_FILE=".specpro/cache/constitution-matching.md"
+      CACHE_DIR=".specpro/cache"
+
+      # Create cache directory if not exists
+      mkdir -p "$CACHE_DIR"
+
+      # If CACHE_MODE=generate, save matching results
+      # ⚠️ On `reuse` this block is SKIPPED — rewriting an unchanged cache would be churn, and
+      # the hash it carries is what `a` will key on next time (`T236` / `ISS-209`).
+      if [[ "$CACHE_MODE" = "generate" ]]; then
+          cat > "$CACHE_FILE" <<EOF
+      # Constitution Matching Cache
+
+      **Feature**: [FEATURE_NAME]
+      **Generated**: [DATE]
+      **Spec Version**: [VERSION]
+      **Constitution Hash**: $CONSTITUTION_HASH
+
+      ## Matched Domains
+      [List of domains detected]
+
+      ## Matched Principles
+      [List of matched Constitution principles with constraints]
+
+      ## Last Modified
+      [TIMESTAMP]
+EOF
+          echo "✓ Constitution matching cached to $CACHE_FILE"
+      else
+          echo "✓ Reusing Constitution matching from cache"
+      fi
+      ```
+
+4. Load `.specpro/templates/spec-template.md` to understand required sections.
+
+5. **Generate or update specification** ✨ ENHANCED with progress tracking:
+
+   **If UPDATE_MODE=false** (initial specification):
+
+   a. **Parse user description from Input** 📋 [1/6]
+   b. **Extract key concepts** 📋 [2/6]
+   c. **Generate specification based on resolved assumptions** 📋 [3/6]:
+      - Load `specs/assumptions.md` (if exists, created in Step 2.5)
+      - Use resolved assumptions to guide:
+         * Architecture decisions
+         * Platform choices (e.g., local vs web, desktop vs mobile)
+         * Scope boundaries
+         * Feature priorities
+         * Technology direction
+      - For remaining unclear aspects (non-critical):
+         * Make informed guesses based on:
+           - Constitution principles
+           - Context from resolved assumptions
+           - Industry standards
+           - Common patterns
+         * Convert ALL assumptions (both resolved and inferred) into Functional Requirements
+         * Examples:
+           - Instead of "Assume LAN <10ms", write "System MUST operate in LAN environments with <10ms latency"
+           - Instead of "Assume 8GB RAM", write "System MUST support teacher devices with 8GB RAM minimum"
+         * DO NOT use [NEEDS CLARIFICATION] markers - all ambiguity detection is deferred to /specpro-clarify --scan
+   d. **Fill User Scenarios & Testing** 📋 [4/6]:
+      - Generate user stories with format:
+        ```markdown
+        ### US[ID] - [Title] (Priority: PX)
+
+        **Lifecycle**: [specify:create][plan:create][tasks:create]
+
+        [Description]
+
+        **Why this priority**: [Rationale]
+
+        **Independent Test**: [Test strategy]
+
+        **Acceptance Scenarios**:
+        1. Given...When...Then...
+        ```
+      - Each new user story gets Lifecycle field: `[specify:create][plan:create][tasks:create]`
+
+   e. **Generate Functional Requirements** 📋 [5/5]:
+      - Generate FRs grouped by User Story with format:
+        ```markdown
+        #### [User Story Title] (US[ID])
+
+          - **FR-XXX**: [Requirement Title]
+            **Lifecycle**: [specify:create][plan:create][tasks:create]
+            System MUST [requirement].
+
+          - **FR-XXX**: [Requirement Title]
+            **Lifecycle**: [specify:create][plan:create][tasks:create]
+            System MUST [requirement].
+        ```
+      - Each new FR gets Lifecycle field: `[specify:create][plan:create][tasks:create]`
+      - Group FRs by their associated User Story for clear traceability
+
+   f. **Generate Change Summary** (for initial spec):
+      ```markdown
+      ## Change Summary
+
+      **Version**: 0.1
+      **Update Type**: Initial
+      **Changes Overview**:
+      - **Added**: Initial specification with N User Stories, M Requirements
+      ```
+
+   g. **Return**: SUCCESS (spec ready for planning)
+
+   **If UPDATE_MODE=true** (update existing specification):
+
+   a. **Parse existing spec.md** 📋 [1/5]:
+      - Extract ALL User Stories with:
+        - ID (US1, US2, etc.)
+        - Title
+        - Priority (P1, P2, P3)
+        - Acceptance Criteria
+        - **Lifecycle**: [specify:<status>][plan:<status>][tasks:<status>]
+      - Extract ALL Functional Requirements
+        - ID (FR-xxx, FR-yyy, etc.)
+        - Title
+        - **Lifecycle**: [specify:<status>][plan:<status>][tasks:<status>]
+      - Extract ALL Constitution Constraints
+
+   b. **Analyze user input for changes** 📋 [2/5]:
+      - Identify **new features** to add (not in existing spec)
+      - Identify **modifications** to existing features
+      - Identify **deprecations** (features to mark as deprecated)
+
+   c. **Detect architectural conflicts** 📋 [3/5]:
+      - Load existing spec.md and extract critical architectural decisions:
+         * Application type: Local vs Web vs Hybrid
+         * Platform scope: Desktop vs Mobile vs Cross-platform
+         * Deployment model: Single-tenant vs Multi-tenant
+         * Data storage: Local vs Cloud vs Hybrid
+         * Collaboration model: Single-user vs Multi-user vs Real-time collaborative
+         * Performance model: Batch vs Real-time vs Stream processing
+      - Compare user's new input ($ARGUMENTS) against existing architectural decisions
+      - Detect **architectural conflicts** that would invalidate large portions of existing spec:
+         * **Local → Web** OR **Web → Local**: Completely different architecture, data model, deployment
+         * **Single-user → Collaborative**: Requires sync, conflict resolution, backend
+         * **Desktop → Mobile** OR **Mobile → Desktop**: Platform-specific changes, UI framework
+         * **Single-platform → Cross-platform**: Requires significant refactoring
+         * **Online → Offline** OR **Offline → Online**: Major architectural shift
+      - If architectural conflicts detected:
+         1. List specific conflicts identified
+         2. Calculate estimated impact (percentage of FRs that would be deprecated)
+         3. Display **RESTART recommended** message:
+            ```markdown
+            ## ⚠️ Architectural Conflict Detected
+
+            Your new input conflicts with the current architectural direction:
+
+            **Current Spec**: Version $CURRENT_VERSION
+            **Current Architecture**: [Summary of current architecture]
+
+            **Your Input**: "$ARGUMENTS"
+
+            **Conflicts Identified**:
+            - [Conflict 1]: [Current] → [Requested] (Impact: [X]% of FRs deprecated)
+            - [Conflict 2]: [Current] → [Requested] (Impact: [Y]% of FRs deprecated)
+            ...
+
+            **Estimated Impact**:
+            - Approximately Z% of existing Functional Requirements would be deprecated
+            - Major architectural changes required
+
+            **Recommendations**:
+            1. **RESTART** (Recommended) - Start fresh with new architectural direction
+               - Clean slate, no deprecated baggage
+               - Version reset to 0.1
+               - Current spec preserved in Git history
+
+            2. **UPDATE** - Continue with evolution (will deprecate conflicting items)
+               - Many existing FRs marked as [deprecated]
+               - Change Summary will show extensive deprecations
+               - Version incremented to $NEW_VERSION
+
+            Your choice (1/2):
+            ```
+         4. If user chooses 1 (RESTART):
+            - Ask for confirmation: "⚠️ Are you sure? This will DELETE the current spec.md and start fresh. Type 'RESTART' to confirm:"
+            - If confirmed:
+              * Delete existing spec.md
+              * Set `UPDATE_MODE=false`
+              * Set `SPEC_VERSION="0.1"` (reset to initial)
+              * Proceed to Step 2.5 (Dynamic Assumption Resolution) as if initial spec
+            - Else:
+              * Return to choice 1/2
+         5. If user chooses 2 (UPDATE):
+            * Set `UPDATE_MODE=true`
+            * Proceed to Step 5.d with extensive deprecations
+            * Note: User has been warned about impact
+
+      - If NO architectural conflicts:
+         * Proceed to Step 5.d (normal update flow)
+
+   d. **Generate Change Summary** 📋 [4/5] (if no conflicts or user chose UPDATE):
+      - Count changes:
+        - Added: N new items
+        - Modified: X items
+        - Deprecated: Y items
+      - Determine update type:
+        - Feature Addition: Added features without breaking changes
+        - Refactor: Restructured existing functionality
+        - Breaking Change: Incompatible changes
+        - Bug Fix: Fixed issues
+      - ⚠️ **不要产出逐项变更表**（`T239` / `ISS-212`）：模板里那个 `### Detailed Changes` 块**已删除**，因为它**没有任何消费者**、且与每项的 `**Lifecycle**:` 字段和 `### Changes Overview` **复述同一事实**。要逐项细节，读**该项自己的 Lifecycle 字段**。
+
+   e. **Merge and generate updated spec.md** 📋 [5/5]:
+
+      **Lifecycle Update Rules**:
+
+      **For ALL items that CARRY a Lifecycle — which is User Stories and Functional Requirements, and nothing else** ⚠️ (`T239` / `ISS-212`):
+      ⚠️ **`## Constitution Constraints` is NOT in this scope, and that is an adjudication, not an omission.** Evidence: ① `templates/spec-template.md`'s `## Constitution Constraints` section is `[Add constitution constraints if any]` — it **emits no `**Lifecycle**:` field**; ② the plan-layer reader (`commands/specpro.plan.md` → `4.a`) enumerates **two** classes (US, FR), not three; ③ measured on `specs/spec.md`: **73** `**Lifecycle**:` lines = 11 US + 62 FR — **zero** belong to a Constitution Constraint. ⇒ A rule written for a class that cannot carry the field is a rule nothing can follow; **this line used to name three**. ⚠️ **Do not "fix" it by adding Lifecycle fields to that section**: nothing reads them (no command parses a constraint's lifecycle), so the field would be a value with no consumer — and the section is a *reference* to the constitution, not a tracked requirement.
+
+      a. **New items** (not in existing spec):
+         - Add to spec with Lifecycle:
+           ```markdown
+           **Lifecycle**: [specify:create][plan:create][tasks:create]
+           ```
+         - specifyStatus = "create"
+         - planStatus = "create"
+         - tasksStatus = "create"
+         - In Change Summary: marked as **[create]**
+
+      b. **Modified items** (content changed):
+         - Update content in spec
+         - **Update Lifecycle** (all three stages):
+           ```markdown
+           **Lifecycle**: [specify:update][plan:update][tasks:update]
+           ```
+           - specifyStatus = "update"
+           - planStatus = "update" (triggers plan regeneration)
+           - tasksStatus = "update"
+         - **Note**: Do NOT check/preserve previous planStatus or tasksStatus
+         - **Rationale**: Any content change invalidates previous plan/tasks
+         - In Change Summary: marked as **[update]**
+
+      c. **Deprecated items** (no longer needed):
+         - Update content in spec
+         - **Update Lifecycle** (all three stages):
+           ```markdown
+           **Lifecycle**: [specify:delete][plan:delete][tasks:delete]
+           ```
+         - All three fields: specify="delete", plan="delete", tasks="delete"
+         - Move to Deprecated Items section at end of spec
+         - In Change Summary: marked as **[deprecated]**
+         - **Note**: DO NOT preserve old planStatus/tasksStatus values
+
+      d. **Preserved items** (no changes):
+         - **DO NOT update Lifecycle field** - preserve all three values as-is
+         - DO NOT include in Change Summary (no status marker)
+
+      **For User Stories**:
+      - **[create]**: Add new User Stories
+      - **[update]**: Update existing Story
+      - **[deprecated]**: Mark Story as deprecated
+      - (unchanged Stories: no Lifecycle update, NOT logged in Change Summary)
+
+      **For Functional Requirements**:
+      - **[create]**: Add new FRs
+      - **[update]**: Update existing FRs with new version
+      - **[deprecated]**: Mark FRs as deprecated with migration path
+      - (unchanged FRs: no Lifecycle update, NOT logged in Change Summary)
+
+      ⚠️ **Constitution Constraints: no Lifecycle block here** (`T239` / `ISS-212`). A three-line `**For Constitution Constraints**:` block used to sit at this spot, mirroring the US/FR rules — but that section **carries no `**Lifecycle**:` field** and nothing reads one if it did (evidence in the note at the head of these rules). ⇒ **Constraints are added or updated as prose in `## Constitution Constraints`; they are never marked, never logged in the Change Summary, and never propagate downstream.** Re-adding the block would recreate a rule for a class that cannot follow it.
+
+      **For Deprecated Items section**:
+      - Move all deprecated items to this section
+      - Include:
+        - Original content
+        - Deprecation reason
+        - Migration path (if applicable)
+
+   f. **Write updated spec.md**:
+      - Include Change Summary at top
+      - Include all active (non-deprecated) items
+      - Include Deprecated Items section at end
+
+   g. **Update version metadata**:
+      ```markdown
+      # Feature Specification: [FEATURE_NAME]
+
+      **Version**: 0.2
+      **Last Updated**: [DATE]
+      **Status**: Draft
+      ```
+
+   h. **Return**: SUCCESS (spec updated and ready for planning)
+
+6. **Write the specification to SPEC_FILE** using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+7. **Auto-scan for clarifications** ✨ ENHANCED with conditional logic:
+
+   a. **Determine scan necessity** ✨ NEW:
+      ```bash
+      if [[ "$UPDATE_MODE" = "false" ]]; then
+          # Initial spec: Always run scan
+          RUN_SCAN=true
+          echo "📋 Running clarification scan on initial spec..."
+      else
+          # Update spec: Check if there are new/modified FRs
+          ADDED_FR_COUNT=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:create\]' "$SPEC_FILE" 2>/dev/null | grep -cE "FR-[0-9]+[A-E]?" || true)
+          : "${ADDED_FR_COUNT:=0}"
+          MODIFIED_FR_COUNT=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:update\]' "$SPEC_FILE" 2>/dev/null | grep -cE "FR-[0-9]+[A-E]?" || true)
+          : "${MODIFIED_FR_COUNT:=0}"
+
+          if [[ $ADDED_FR_COUNT -gt 0 ]] || [[ $MODIFIED_FR_COUNT -gt 0 ]]; then
+              RUN_SCAN=true
+              echo "📋 Running clarification scan ($ADDED_FR_COUNT added, $MODIFIED_FR_COUNT modified)..."
+          else
+              RUN_SCAN=false
+              echo "ℹ️  No new/modified FRs, skipping clarification scan"
+          fi
+      fi
+      ```
+
+   b. **Invoke clarification scan** (conditional):
+      ```bash
+      if [[ "$RUN_SCAN" = "true" ]]; then
+          /specpro-clarify --scan
+      else
+          # Load existing clarifications.md
+          if [[ -f "specs/clarifications.md" ]]; then
+              echo "✓ Loaded existing clarifications.md"
+          else
+              echo "⚠️  No clarifications.md found (expected for preserved-only update)"
+          fi
+      fi
+      ```
+      This scans spec.md for ambiguities and generates/updates `specs/clarifications.md` with categorized questions.
+
+   c. **Wait for scan completion** (if scan was run): Do not proceed until the scan is complete and clarifications.md is generated.
+
+   d. **Verify clarifications.md** (if scan was run): Confirm that `specs/clarifications.md` was created successfully. If scan failed, warn user but proceed to commit.
+
+8. **Auto-invoke clarify if needed** 🆕 REDESIGNED:
+
+   **Purpose**: Automatically check clarifications.md and invoke clarify if [Must Clarify] items exist
+
+   **Key Changes**:
+   - No user choice required - automatic based on clarifications.md content
+   - If [Must Clarify] items exist → automatically invoke clarify (interactive)
+   - If no [Must Clarify] items → skip to Step 9
+   - Seamless user experience - no decision point
+
+   a. **Read clarifications.md statistics**:
+      ```bash
+      # ⚠️ **BIND THE PATH FIRST — this line is the whole fix** (`T236` / `ISS-209`): everything
+      # below reads `$CLARIFICATIONS_FILE`, and **nothing in this repository ever assigned it**
+      # (measured 2026-09-20: 5 uses, 0 assignments). With the variable unset, `[[ ! -f "" ]]` is
+      # **true**, so this step printed "✓ No clarifications needed" and returned **before**
+      # `$MUST_CLARIFY_COUNT` was ever computed ⇒ the `[Must Clarify]`-driven `/specpro-clarify`
+      # hand-off — the entire reason this step exists — was **unreachable by construction**.
+      # The literal below is the same one this file already uses at Step 7.c.
+      CLARIFICATIONS_FILE="specs/clarifications.md"
+
+      # Check if clarifications.md exists
+      if [[ ! -f "$CLARIFICATIONS_FILE" ]]; then
+          echo "✓ No clarifications needed (clarifications.md not found)"
+          echo "  Proceeding to quality validation..."
+          # Skip to Step 9
+          return 0
+      fi
+
+      # Count items in each category — ⚠️ **ANCHORED ON THE ENTRY FORM, and that is the whole
+      # fix** (`T244` / `ISS-217`): the pattern used to be the bare `"\[<label>\]"`, which
+      # matches **every mention** — the template's own definitions block, its
+      # `### [Must Clarify] Items` heading, the `## Progress Tracking` rows, the
+      # `**Completion Criteria**` line. Measured on a freshly-generated artifact:
+      # **Must Clarify 9 · Suggested Clarify 3 · Can Infer 8** against **1 item each**.
+      # ⚠️ **That is not cosmetic**: `MUST_CLARIFY_COUNT > 0` is the trigger for the
+      # auto-invoked `/specpro-clarify` hand-off below ⇒ an inflated count fires the hand-off
+      # on an artifact with **no** must-clarify items, every time, and nothing reports it.
+      # An entry is `- **[<label>] - <id>** - …` (note the ` - `, which the definition line
+      # `- **[<label>]**: …` does not have, and no mention line starts with `- **`).
+      # ⚠️ Per TOOL-009 this example is itself line-anchored: a copied unanchored pattern is
+      # how the same misjudgment propagates.
+      CLARIFY_ENTRY='^- \*\*\['
+      MUST_CLARIFY_COUNT=$(grep -cE "${CLARIFY_ENTRY}Must Clarify\] - " "$CLARIFICATIONS_FILE" 2>/dev/null || true)
+      : "${MUST_CLARIFY_COUNT:=0}"
+      SUGGESTED_CLARIFY_COUNT=$(grep -cE "${CLARIFY_ENTRY}Suggested Clarify\] - " "$CLARIFICATIONS_FILE" 2>/dev/null || true)
+      : "${SUGGESTED_CLARIFY_COUNT:=0}"
+      CAN_INFER_COUNT=$(grep -cE "${CLARIFY_ENTRY}Can Infer\] - " "$CLARIFICATIONS_FILE" 2>/dev/null || true)
+      : "${CAN_INFER_COUNT:=0}"
+      TOTAL_ITEMS=$((MUST_CLARIFY_COUNT + SUGGESTED_CLARIFY_COUNT + CAN_INFER_COUNT))
+      ```
+
+   b. **Display clarification summary**:
+      ```markdown
+      ## Specification Created ✓
+
+      **Spec File**: [SPEC_FILE path]
+      **Clarifications**: [specs/clarifications.md path]
+
+      **Clarification Summary**:
+      - [Must Clarify]: M items
+      - [Suggested Clarify]: N items
+      - [Can Infer]: K items
+      - **Total**: TOTAL items
+      ```
+
+   c. **Auto-invoke clarify if [Must Clarify] items exist**:
+      ```bash
+      if [[ $MUST_CLARIFY_COUNT -gt 0 ]]; then
+          echo ""
+          echo "🔄 Found $MUST_CLARIFY_COUNT [Must Clarify] items"
+          echo "   Automatically starting clarification process..."
+          echo ""
+          echo "   AI will ask questions one by one, integrating answers into spec.md"
+          echo "   You can also type 'skip' to skip specific questions"
+          echo ""
+
+          # Auto-invoke clarify (interactive mode)
+          /specpro-clarify
+
+          # After clarify completes, check if all [Must Clarify] items are resolved
+          # ⚠️ **This is a BLOCK scan, not a line count** (`T244` / `ISS-217`, same round as the
+          # counts above). Two things were wrong with the one-liner it replaces
+          # (`grep -c "\[Must Clarify\]"`): ① it counted **mentions** (see above), and ② it
+          # counted **entries**, not **unresolved** ones — so with any must-clarify item at all,
+          # `REMAINING_MUST` was **always > 0** and the `✅ All … resolved` branch below was
+          # **unreachable**. The stated intent ("check if all … are resolved") needs each
+          # item's own `**Status**:` line, which is a per-item block read.
+          # ⚠️ The status anchor carries **`[[:space:]]*`** and that is not cosmetic: the
+          # template emits the line **indented** (`  **Status**: [ ]`), so a line-start anchor
+          # matches **nothing** and the count comes back a constant 0 — a false "all resolved"
+          # that is indistinguishable from a real one. (Measured while writing this: the first
+          # version of this very fix shipped with the wrong anchor and reported 0 on a fixture
+          # holding an unresolved item.)
+          REMAINING_MUST=$(awk '
+            /^- \*\*\[Must Clarify\] - / { in_item = 1; next }
+            in_item && /^[[:space:]]*\*\*Status\*\*:/ { if ($0 ~ /\[[ ]\]/) unresolved++; in_item = 0 }
+            END { print unresolved + 0 }
+          ' "$CLARIFICATIONS_FILE" 2>/dev/null || true)
+          : "${REMAINING_MUST:=0}"
+
+          if [[ $REMAINING_MUST -gt 0 ]]; then
+              echo ""
+              echo "⚠️  Clarification completed with $REMAINING_MUST unresolved [Must Clarify] items"
+              echo "   These will be addressed during quality validation (Step 9)"
+              echo "   Proceeding to quality validation..."
+          else
+              echo ""
+              echo "✅ All [Must Clarify] items resolved"
+              echo "   Proceeding to quality validation..."
+          fi
+      else
+          echo ""
+          echo "✓ No [Must Clarify] items found"
+          echo "  Clarifications.md contains only [Suggested Clarify] and [Can Infer] items"
+          echo "  These can be resolved manually or during quality validation"
+          echo "  Proceeding to quality validation..."
+      fi
+      ```
+
+   d. **Inform user about next steps**:
+      ```markdown
+      **What to Expect Next**:
+      - Step 9: Quality validation (specpro.qc)
+        * Validates spec.md against the checklist's quality criteria
+        * Rebuilds specs/checklists/requirements.md from the template, every run
+        * Queues every non-passing criterion into the [specify] section of the ledger
+        * Reports a verdict and stops — no repair, no loop (`FR-058` / `FR-060`)
+        * ⚠️ The queued entries are THIS command's to fix, on the next --review-issues run
+
+      - After validation: Git commit with spec.md + clarifications.md + requirements.md
+
+      - Final step: Ready for `/specpro-plan` (technical planning)
+      ```
+
+   **User Experience**:
+   - **No user intervention required**: clarify is invoked automatically when needed
+   - **Seamless flow**: User watches as clarify asks questions and updates spec.md
+   - **No decision point**: No need to choose "clarify now or later"
+   - **Flexibility preserved**: User can still type 'skip' during clarify to skip questions
+
+   **Backward Compatibility**:
+   - If user manually runs `/specpro-clarify` before this step, it will detect no [Must Clarify] items and skip
+   - If user wants to review spec.md first, they can run `/specpro-specify --update` later
+9. **Specification Quality Validation** 🆕 REDESIGNED with specpro.qc [MANDATORY - CRITICAL GATE]:
+
+   **Purpose**: Validate the FINAL spec.md (after all clarifications) against the checklist's quality criteria using automated qc command
+
+   ⚠️ **CRITICAL: This step is MANDATORY and NON-SKIPPABLE**
+   - Quality validation CANNOT be bypassed
+   - QC execution is enforced automatically
+   - requirements.md generation is verified post-QC
+   - Workflow BLOCKS if quality validation fails
+
+   **Key Changes** ⚠️ [rewritten 2026-09-19: two of the five lines below described the
+   *repair* behaviour that `FR-058` removed — a command document claiming its callee
+   repairs is how the delegation stayed invisible for as long as it did]:
+   - Quality validation is a dedicated `/specpro-qc` command, not inline logic here
+   - **qc checks and reports; THIS command repairs** — the spec's producer is the only
+     party that writes the spec (`FR-058`)
+   - **qc queues what did not pass into the `[specify]` section** (`FR-059`) — which is
+     this command's own queue, so the fix path stays inside one chain
+   - qc runs **once**, rebuilds the checklist, and stops (`FR-060`); there is no repair
+     loop and therefore no "converged / not feasible" verdict for it to pronounce
+   - No "continue despite issues" option - quality is not compromisable
+   - Post-QC verification ensures requirements.md is generated successfully
+
+   a. **Detect validation scope**:
+      ```bash
+      if [[ "$UPDATE_MODE" = "false" ]]; then
+          # Initial spec: Full validation
+          VALIDATION_SCOPE="full"
+          echo "📋 Running full quality validation (initial spec)..."
+      else
+          # Update spec: Validate only modified/added items
+          ADDED_FR_COUNT=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:create\]' "$SPEC_FILE" 2>/dev/null | grep -cE "FR-[0-9]+[A-E]?" || true)
+          : "${ADDED_FR_COUNT:=0}"
+          MODIFIED_FR_COUNT=$(grep -B1 '\*\*Lifecycle\*\*:.*\[specify:update\]' "$SPEC_FILE" 2>/dev/null | grep -cE "FR-[0-9]+[A-E]?" || true)
+          : "${MODIFIED_FR_COUNT:=0}"
+
+          if [[ $ADDED_FR_COUNT -gt 0 ]] || [[ $MODIFIED_FR_COUNT -gt 0 ]]; then
+              VALIDATION_SCOPE="incremental"
+              echo "📋 Running incremental validation ($ADDED_FR_COUNT added, $MODIFIED_FR_COUNT modified)..."
+          else
+              VALIDATION_SCOPE="skip"
+              echo "ℹ️  No new/modified FRs, skipping quality validation"
+              echo "✓ Loading existing quality checklist..."
+              # Skip to Step 10
+          fi
+      fi
+      ```
+
+   b. **Run /specpro-qc** 🆕:
+      ```bash
+      if [[ "$VALIDATION_SCOPE" != "skip" ]]; then
+          echo "📋 Starting quality validation with specpro.qc..."
+          echo "   Validating against the checklist's quality criteria..."
+          echo "   QC rebuilds the checklist and queues every non-passing item for THIS command."
+
+          # ⚠️ **FR-062's obligation is discharged HERE**: the check runs on the spec's
+          # first creation and on every update, and the trigger is the spec's change —
+          # not the caller's memory. ⚠️ And it is run **flag-less**, because the repair
+          # is not the checker's to perform (FR-058): qc queues the non-passing items
+          # into `[specify]`, and THIS command — the spec's producer — resolves them.
+          /specpro-qc --scope="$VALIDATION_SCOPE"
+
+          QC_EXIT_CODE=$?
+
+          if [[ $QC_EXIT_CODE -eq 0 ]]; then
+              echo ""
+              echo "✅ Quality validation PASSED"
+              echo "   No criterion failed."
+              echo "   specs/checklists/requirements.md: rebuilt for this run"
+          else
+              echo ""
+              echo "❌ Quality validation FAILED"
+              echo "   The non-passing criteria are now entries in the [specify] queue"
+              echo "   (FR-059) — this command's own queue, to be fixed by this command."
+              echo ""
+              echo "Check specs/checklists/requirements.md for the per-item verdicts."
+              echo "Then run --review-issues to process the queued entries."
+              exit 1
+          fi
+      else
+          echo "✓ Quality validation skipped (no changes to validate)"
+      fi
+      ```
+
+   c. **Post-QC Verification** 🆕 [MANDATORY - CRITICAL GATE]:
+      ```bash
+      # This step verifies that QC successfully generated requirements.md
+      # If verification fails, the workflow is BLOCKED
+
+      echo ""
+      echo "📋 Post-QC Verification: Checking requirements.md generation..."
+
+      # Derive from the spec file, not from an absolute specs path: in a layout where the
+      # specs directory is its own repository, an absolute path can resolve outside the
+      # tree this run actually wrote to.
+      SPECS_DIR="$(cd "$(dirname "$SPEC_FILE")" && pwd)"
+      REQUIREMENTS_FILE="$SPECS_DIR/checklists/requirements.md"
+
+      if [[ ! -f "$REQUIREMENTS_FILE" ]]; then
+          echo ""
+          echo "❌ CRITICAL: requirements.md not found after QC execution"
+          echo "   Expected: $REQUIREMENTS_FILE"
+          echo "   Current: File not found"
+          echo ""
+          echo "This indicates a critical workflow failure."
+          echo "Quality validation (QC) should have generated requirements.md but failed to do so."
+          echo ""
+          echo "Workflow is BLOCKED. Please diagnose the issue:"
+          echo "1. Run /specpro-qc manually to check for errors"
+          echo "2. Check if QC is generating requirements.md correctly"
+          echo "3. Verify SPECS_DIR path: $SPECS_DIR"
+          exit 1
+      fi
+
+      # 完成度按「Status 取值」判定，不按复选框——模板即 `- [ ] **Status**: …`，
+      # 「诚实跳过」与「未做」在复选框上完全同形（工具缺陷 #10）
+      QC_UNRESOLVED=$(grep -E '^- \[[ x]\] \*\*Status\*\*:' "$REQUIREMENTS_FILE" 2>/dev/null \
+          | grep -vE '\*\*Status\*\*:[[:space:]]*(x|⊘[[:space:]]*Skipped)[[:space:]]*$' || true)
+
+      if [ -n "$QC_UNRESOLVED" ]; then
+          echo ""
+          echo "❌ CRITICAL: requirements.md has unresolved items after QC execution"
+          echo "   Expected: every item is either 'x' (passed) or '⊘ Skipped'"
+          echo ""
+          echo "This indicates QC did not complete successfully."
+          echo ""
+          echo "Unresolved items:"
+          echo "$QC_UNRESOLVED" | head -5
+          echo ""
+          echo "Workflow is BLOCKED. Please diagnose the issue:"
+          echo "1. Run /specpro-qc manually to check for errors"
+          echo "2. Check specs/checklists/requirements.md for details"
+          exit 1
+      fi
+
+      echo "✅ Post-QC Verification PASSED"
+      echo "   requirements.md exists with every item marked [x]"
+      echo "   Quality validation artifact verified successfully"
+      ```
+
+   **What specpro.qc does** ⚠️ [corrected 2026-09-19 — every line below used to describe
+   the *repair* behaviour that `FR-058` removed]:
+   - Validates spec.md against the checklist's quality criteria:
+     * P0: Content Quality (2 items) - No implementation details, functional not technical
+     * P0: Completeness (3 items) - Mandatory sections, acceptance scenarios, scenarios are functional
+     * P1: Consistency (4 items) - US consistency, FR consistency, US→FR mapping, reference integrity
+     * P1: Traceability (2 items) - Constitution constraints, external dependencies
+   - **Rebuilds** `specs/checklists/requirements.md` from the template, **every run** (`FR-060`)
+   - **Queues every non-passing criterion** into the `[specify]` section of
+     `specs/implement_issues.md` (`FR-059`) — deduped by check id, so repeated runs do
+     not flood the queue
+   - **Reports a verdict and stops** (`FR-061`): passing means "no `✗`"; a `⊘ Skipped`
+     item is neither a pass nor a failure
+   - ⚠️ **It does NOT fix anything, does NOT write `spec.md`, does NOT touch
+     `clarifications.md`, and does NOT loop** — see the write-surface note at the top of
+     `commands/specpro.qc.md`. The repair is **this** command's job.
+
+   **No user intervention required**:
+   - User does not need to call /specpro-qc manually
+   - User does not need to fix issues manually
+   - All interactions happen through clarify (AI asks questions)
+   - If qc cannot resolve issues, project is marked as not feasible
+
+10. **Create Git commit** (after writing spec.md, clarifications.md, and checklists/requirements.md):
+
+   a. **Resolve the repository that owns the spec artifacts** ⚠️:
+      The artifacts this step commits may not live in the same repository as the project root. A project may keep its plan/task artifacts in a **separate repository** — e.g. a nested repo mounted at the specs directory — and a commit issued from the project root would then see them as untracked-ignored or not at all.
+
+      Derive the specs directory from the spec file itself, then resolve the owning repository from that path — do not assume the project root, and do not rely on a `SPECS_DIR` variable this command never sets:
+      ```bash
+      SPECS_DIR="$(cd "$(dirname "$SPEC_FILE")" && pwd)"
+      SPECS_REPO="$(git -C "$SPECS_DIR" rev-parse --show-toplevel 2>/dev/null)" || SPECS_REPO=""
+      if [ -z "$SPECS_REPO" ]; then
+          echo "ℹ️  The specs directory is not under version control — skipping commit"
+          SPEC_COMMIT_SKIP=true
+      else
+          SPEC_COMMIT_SKIP=false
+      fi
+
+      # Relative-path helper. Use the Python form directly — macOS `realpath(1)` has no
+      # `--relative-to`.
+      #
+      # ⚠️ **`os.path.realpath` on BOTH sides is the whole point, not a nicety** (ISS-144):
+      # `os.path.relpath` only compares literal prefixes. `git rev-parse --show-toplevel` returns
+      # the PHYSICAL path (symlinks resolved) while `$SPECS_DIR` below comes from `cd … && pwd`
+      # (logical) — so when a project is reached through a symlink the two do not share a prefix
+      # and relpath walks ABOVE the repository. Reproduced: with `/tmp` → `/private/tmp`,
+      # `relpath` produced `../../../../tmp/.../specs/spec.md` for a file inside the repo, and
+      # `git add` then refused it as outside the repository. Resolving both sides collapses the
+      # difference. ⚠️ Copied verbatim in `specpro.implement.md` and `specpro.test-implement.md`
+      # — change all three together.
+      relpath() { python3 -c 'import os,sys;print(os.path.relpath(os.path.realpath(sys.argv[2]),os.path.realpath(sys.argv[1])))' "$1" "$2"; }
+      ```
+      🔴 **`SPECS_REPO=""` means STOP — and the empty string is a trap, not a sentinel.** `git -C ""` does **not** mean "no repository"; it means **the current directory**, so it silently resolves to whatever repository the cwd happens to be in. Verified 2026-09-18: `git -C "" rev-parse --show-toplevel` → the cwd's repository, **exit 0**. ⇒ With `SPECS_REPO=""`, every step below would run against the **wrong** repository while the line above says "skipping" — the failure is not an error but a **silent commit into the wrong repo**. **If `SPEC_COMMIT_SKIP=true`, do NOT run steps 10b–10e at all.** Report it and end this step: the artifacts stay uncommitted, which is the honest outcome (**FR-030** — 明确报告并跳过，而非以一个不解析的路径失败).
+
+      All git commands below run against `$SPECS_REPO`, not `$REPO_ROOT`. Each artifact path is expressed **relative to that repository** — never as a literal `specs/...` path, which is only correct when the project root *is* the owning repository:
+      ```bash
+      SPEC_FILE_REL="$(relpath "$SPECS_REPO" "$SPEC_FILE")"
+      ```
+
+   b. **Check if in Git repository** — ⛔ **GUARD FIRST: if `$SPEC_COMMIT_SKIP` is `true`, skip steps 10b–10e entirely** (see 10a's trap note — an empty `$SPECS_REPO` makes every `git -C` below act on the cwd's repository):
+      ```bash
+      [ "${SPEC_COMMIT_SKIP:-false}" = true ] && echo "⛔ SPEC_COMMIT_SKIP — steps 10b–10e are skipped (FR-030)"
+      # ...and do not run the lines below when that printed.
+      if git -C "$SPECS_REPO" rev-parse --git-dir > /dev/null 2>&1; then
+          IN_GIT_REPO=true
+      else
+          IN_GIT_REPO=false
+      fi
+      ```
+
+   c. **Check if spec.md has changes**:
+      ```bash
+      if git -C "$SPECS_REPO" diff --quiet -- "$SPEC_FILE_REL" 2>/dev/null; then
+          echo "ℹ️  No changes to spec.md, skipping commit"
+      else
+          SPEC_CHANGED=true
+      fi
+      ```
+
+   d. **Generate commit message**:
+      ```bash
+      if [ "$UPDATE_MODE" = true ]; then
+          # For updates, include version and summary
+          CHANGE_SUMMARY=$(grep "^### Changes Overview" "$SPEC_FILE" -A 10 | head -15)
+          COMMIT_MSG="spec: update to v${SPEC_VERSION}
+
+${CHANGE_SUMMARY}"
+      else
+          # For initial spec
+          COMMIT_MSG="spec: initial specification v${SPEC_VERSION}"
+      fi
+      ```
+
+   e. **Create commit** (in the owning repository, with paths relative to it) — ⛔ **the write step, wrapped so an unowned path cannot reach it**:
+      ```bash
+      if [ "${SPEC_COMMIT_SKIP:-false}" = true ]; then
+          echo "⛔ refused: no owning repository — nothing is committed (FR-030)"
+      else
+          git -C "$SPECS_REPO" add -- \
+              "$SPEC_FILE_REL" \
+              "$(relpath "$SPECS_REPO" "$SPECS_DIR/clarifications.md")" \
+              "$(relpath "$SPECS_REPO" "$SPECS_DIR/checklists/requirements.md")"
+          git -C "$SPECS_REPO" commit -m "$COMMIT_MSG"
+      fi
+      ```
+      ⚠️ **The `if` is the point, not decoration**: it makes "commit into the wrong repository" **unreachable by construction** rather than dependent on the reader having followed the prose in 10a. Branching on a flag set where the repository was resolved is what FR-030 asks for — 明确报告并跳过，而不是继续走到一个解析不出来的路径上。
+      ⚠️ If the artifacts span **more than one repository** (e.g. the spec lives in one repo and a checklist in another), issue **one commit per repository**, each with a message describing that repository's change. A single commit cannot span repositories.
+
+   f. **Optional: Create tag**:
+      ```bash
+      echo "Consider creating a tag for this version:"
+      echo "  git tag -a v${SPEC_VERSION}-spec -m \"Specification v${SPEC_VERSION}\""
+      ```
+
+   g. **Commit successful message**:
+      ```markdown
+      ✓ Specification committed successfully
+
+      **Commit Hash**: [commit hash]
+      **Message**: $COMMIT_MSG
+
+      **Documents Committed**:
+      - specs/spec.md (specification)
+      - specs/clarifications.md (clarification questions)
+      - specs/checklists/requirements.md (quality validation)
+
+      **Clarification Summary**:
+      - [Must Clarify]: M items
+      - [Suggested Clarify]: N items
+      - [Can Infer]: K items
+
+      **Quality Validation Summary** (fields verbatim from `specs/checklists/requirements.md`):
+      - Status: [PASS | BLOCK]
+      - Total Items: X
+      - Passed: Y
+      - Skipped: S
+      - Failed: Z
+
+      **Important**:
+      - If you ran clarification, your spec.md has been significantly updated
+      - Please review specs/spec.md to verify the changes
+      - Please review specs/checklists/requirements.md for quality issues
+
+**Upstream status reconciliation** ⚠️ [MANDATORY before any "ready to continue" — Constraint 6 / FR-045]
+
+**"Ready to continue" is a claim about the whole chain, not about the stage speaking.** So
+before this report states any "can continue / ready" conclusion, it MUST **read** each upstream
+stage's pending status on the entries that stage produced, and **state** what it found. The
+over-declaration this replaces: `/specpro-tasks` closed with "✅ Ready to continue
+implementation" while the design side had not taken a single step (`specs/plan.md` → Constraint 6).
+
+**Two things, neither optional**:
+
+1. **Say it when the status is clean too.** "Nothing was mentioned" and "nothing is pending"
+   are different statements, and the first cannot be told apart from "forgot to look".
+2. **Skipped and processed counts are listed separately** — never merged into one "handled" number.
+
+**Report shape** — every upstream gets a line, **including when it has nothing pending**
+(indented, not fenced: several of these blocks sit inside an enclosing fence, and a nested
+fence would close the outer one early):
+
+    Upstream reconciliation (Constraint 6)
+      <upstream>: N pending · M processed
+      Verdict: <clear to continue | upstream debts listed above>
+
+⚠️ **Report — do not block.** The mechanism self-heals: an upstream that completes marks its
+downstream `update`. Blocking would need a judgement of "what counts as a debt", and that
+judgement *is* the downstream reading its upstreams — reporting is its only legitimate form.
+
+⚠️ **Copied verbatim across `specpro.{specify,plan,tasks,test-plan,test-implement}.md`** (five
+sites; do not exist as one because each command document is deployed and read on its own).
+Only the "This stage's upstreams" line below differs per file — **change all five together**.
+
+**This stage's upstreams**: `constitution` — pending means a constraint it states is not
+carried into this spec (`specs/constitution.md` → the constraint list).
+
+      **Next Steps**:
+      1. Review specs/spec.md to verify the updates
+      2. Review specs/checklists/requirements.md for quality issues
+      3. Run /specpro-plan to create technical plan
+         - Note: /specpro-plan will auto-invoke clarification if [Must Clarify] items remain
+      ```
+
+---
+
+## Protocol Codec Module Rules 🌐 [CONDITIONAL — FRs touching a wire format]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — triggers T1/T2 (a byte-level protocol anchor or a named protocol in the requirement text) put an FR in scope for that field. "Partially protocol" is not a category: a requirement touching one wire field is in scope for that field. The verdict is recorded per §6.4, not left implicit — producing neither the artifacts nor an explicit not-active verdict is the failure the gate exists to catch. When activated, the FR text MUST meet the requirements below.
+
+- A protocol FR MUST state three specifications explicitly: **stream semantics** (continuous single stream vs per-message independent stream); **byte-packing rules** (which layer owns bit-depth decisions, where dynamic branch selection happens, and known peer-implementation differences); and **peer diversity** (the measured list of differences between peer implementations).
+- The wording MUST NOT infer stream-internal byte counts by translating a parameter such as bits-per-pixel — stream-internal format follows what the encoder or peer actually emits, and every such claim MUST carry its source layer (L1 specification / L2 reference implementation / L3 captured stream; definitions in `.specpro/templates/protocol-golden-bytes-guide.md` §2).
+- The protocol-point inventory itself is a plan-layer design decision; the spec's job is to state the requirement that such an inventory exists.
+