specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.plan.md

@@ -0,0 +1,3284 @@
+---
+description: "Execute the implementation planning workflow using the plan template to generate design artifacts. ✨ OPTIMIZED: Pre-flight checks, incremental updates, clear next steps."
+handoffs:
+  - label: Create Tasks
+    agent: specpro-tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: specpro-checklist
+    prompt: Create a checklist for the following domain...
+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/plan.md
+    unit: "## Technical Context, ## Quality Targets, ## Architecture (b-d), ## Project Structure, ## Deprecated Items"
+  - artifact: specs/plan-overview.md
+    unit: "## Summary, ## Constitution Check, ## Implementation Plan, ## Complexity Tracking"
+  - artifact: specs/research.md
+    unit: "whole file - every NEEDS CLARIFICATION decision resolved; **not** the appended ## Addendum sections, which are /specpro-implement's"
+  - artifact: specs/data-model.md
+    unit: "entity blocks; incremental mode updates only the entities of planStatus=update stories"
+  - artifact: specs/contracts/<name>.md
+    unit: "whole file per contract; regenerated/merged when its source moves"
+  - artifact: specs/quickstart.md
+    unit: "whole file"
+  - artifact: specs/scenarios.md
+    unit: "whole file - INITIAL RUN ONLY; ownership then passes to /specpro-scenarios"
+  - artifact: specs/spec.md
+    unit: "per-item Lifecycle fields -> [plan:processed|deprecated]"
+  - artifact: specs/implement_issues.md
+    unit: "the [plan] section -> appended ISS-NNN entries; 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"
+  - artifact: CLAUDE.md (or AGENTS.md / .cursorrules / equivalent)
+    unit: "thin pointer only - created if missing; entries added or fixed only when missing or contradictory"
+---
+
+## 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/plan.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/plan.md ] && echo EXISTS || echo NEW    # -s: exists AND non-empty (an empty placeholder counts as NEW)
+```
+
+**This command produces several artifacts** (`data-model.md`, `plan-overview.md`, `research.md`, `contracts/`, and — **on the initial run only** — `scenarios.md`). `plan.md` is the sentinel: when it is present the run is incremental, and the same rule governs every companion artifact produced in that run. **`scenarios.md` is the exception** ⚠️: once the initial run creates it, ownership passes to `/specpro-scenarios`, and this command never rewrites it.
+
+| 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/`。
+
+## Optimization Summary
+
+This optimized version includes:
+- ✅ **Pre-flight Checks** (Step 1.5) - Fail fast, clear error messages
+- ✅ **One-time Lifecycle Cache** (Step 4) - Eliminate redundant spec.md reads
+- ✅ **Contract Pre-validation** (Phase 1 Step 2.0) - Generate only missing contracts
+- ✅ **Progress Indicators** - Clear visibility into execution progress
+- ✅ **Enhanced Next Steps** (Step 7) - Clear guidance after Phase 2
+
+**Performance Impact**: 20-30% faster for incremental updates, clearer UX
+
+## 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
+
+### **Step 0: Check for --review-issues argument** 🆕
+
+**Purpose**: Process implement issues submitted from the implement phase
+
+**0.1 Parse arguments**:
+- If `$ARGUMENTS` contains `--review-issues`:
+  * **Skip the question below**; proceed directly to step 0.2 (review issues)
+- Else: **detect, then ask** ⚠️ [settled 2026-09-13]:
+  * Check the `[plan]` section of `specs/implement_issues.md` for open `[ ]` entries
+  * **None** → continue with normal plan generation (Step 1+). **No prompt.**
+  * **Some** → **ask**: "N open `[plan]` issues in specs/implement_issues.md. Process them first, or run normally?"
+    - *Process first* → proceed to step 0.2 (review issues)
+    - *Run normally* → continue with normal plan generation (Step 1+)
+  * **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.)
+
+**0.2 Review implement issues**:
+
+**a. Read issues file**:
+- Read `specs/implement_issues.md`
+- Extract all issues from `[plan]` section
+- Filter for issues marked `[ ]` (pending) only
+- If no pending issues found:
+  * Display: "✓ No pending [plan] issues to process"
+  * Exit
+
+**b. Display issue summary**:
+```markdown
+📋 [plan] Issues Review
+
+Found N pending [plan] issues:
+1. [ ] ISS-XXX: Issue description
+2. [ ] ISS-XXX: Issue description
+...
+```
+
+**c. Process each issue**:
+For each pending issue:
+* Read issue details:
+  - Problem description
+  - Current plan (what's wrong)
+  - Suggested plan (what should be)
+  - Related tasks/modules
+* Determine appropriate action:
+  - **Update design**: Modify design section in plan.md
+  - **Change technology**: Update technology stack
+  - **Adjust architecture**: Modify architecture section
+  - **Add missing design**: Insert new design section
+  - **Fix contract**: Correct the affected file under `specs/contracts/`
+* Apply the change to the artifact the action targets — plan.md, or the contract file
+* Mark issue as `[x]` in implement_issues.md
+* Display: "✓ Processed ISS-XXX: [action taken]"
+
+**Ownership of contract findings** 🌐: this command owns `specs/contracts/` — a contract is a plan-phase artifact, and a finding against one is fixed here rather than by the audit that reported it. `/specpro-analyze` reports and stays read-only by default; it does not edit contracts.
+
+Route by *which link is broken*:
+
+| The finding says | Broken link | Fixed here by |
+|------------------|-------------|---------------|
+| The contract misstates what its cited source says | contract | correcting the contract |
+| The contract has no citation, or cites a source that cannot cover the claim | contract | adding a supportable citation — and if no source can support it, the item is a design choice and MUST be recorded as one |
+| The contract correctly reflects a source that is itself wrong or missing | the source (spec / FR / upstream artifact) | correcting the contract to match reality in the near term, **and** raising the upstream artifact as a `[specify]` issue — a contract MUST NOT be left stating a wrong fact merely because its source is wrong |
+| The contract reflects the implementing code (self-witness) | contract | replacing the citation with an independent source; if none exists, record the item as unverified rather than asserting it |
+
+When fixing a contract, apply the source-attribution requirements of the contract content rules (source layer and version for every asserted fact; no implementation-as-source).
+
+**Handing work downstream — the obligation, and the form it must take** ⚠️ [FR-048 / ISS-110 · ISS-93]
+
+A resolution may conclude that the work belongs to a later stage. When it does, **this round MUST
+also register the entry, in the target section, in the same pass** — a decision that says the work
+moved, with nothing arriving at the target, is indistinguishable from a decision that was never
+acted on.
+
+⚠️ **Why this is written down at all**: the channel was never missing. 登记即路由 — any command may
+append to any section, and that is the ledger's only routing act. What was missing was the
+**obligation** to append, and a point where its absence stops something. The observed case: a
+resolution closed with "hand this to `/specpro-tasks --review-issues`", created no `[tasks]` entry,
+and that command read an **empty queue** and exited having done nothing — while the resolution read
+as complete.
+
+**The form** — write the hand-off on its own line, inside the resolving entry, exactly like this:
+
+    **移交**: <target section> → ISS-NNN
+
+- `<target section>` is a section name **as the contract spells it** — `tasks`, `specify`, `test-plan`,
+  … A name the contract does not define has no consumer, and a hand-off there is a dead end.
+- `ISS-NNN` is the entry **written into that section in this same round**.
+- ⚠️ **The form is fixed, and that is the only reason this can be judged mechanically.** An
+  intention scattered through prose has no shape to test. `scripts/bash/verify-ledger.sh`
+  (and its PowerShell twin) asserts it: for every **completed** entry carrying such a line, the
+  named ID must exist **in the named section**, and the named section must be one the contract
+  defines. The check is a commit-time gate — the pre-commit hook runs that verifier.
+- ⚠️ **Only `[x]` entries are checked.** An entry still `[ ]` has not handed anything off yet;
+  requiring its target to exist would punish the correct order of work.
+- A hand-off line **without** a registration is the failure this rule exists to stop. If the work
+  genuinely does not belong to a later stage, do not write the line.
+
+**裁定触及工具源时：授权边界不动，改走移交** ⚠️ [FR-051 · ISS-119 · ISS-153 · T169]
+
+`plan` 层的裁定**经常**需要同时改两处：契约（`specs/contracts/`，**在本命令的写入面内 ✓**）与
+**工具源**（`commands/` · `templates/` · `scripts/` · `tools/`，**不在 ✗**）。
+成例是 `ISS-115`：它的裁定要求同时改契约与 `tools/specpro.dev-audit.md`。
+
+**处置 —— 不动写入面，改走 `[tasks]` 移交：**
+
+1. 在**写入面内**做完能做的：更正契约、更正本命令自己的产物。
+2. **同轮**按上面的**移交形态**登记一条 `[tasks]` 条目（`**移交**: [tasks] → ISS-NNN`），
+   条目里**点名工具源的那个文件**，并写明缺的是哪一步。
+3. ⚠️ **指向与登记必须同轮**：在契约里写一句"此事由某任务承接"却**不登记**，那句话就
+   **指不到任何能动它的任务**（`ISS-153` 的形态 —— 它当时指向一条 Location 不含该文件的在办任务）。
+   登记之后，`scripts/bash/verify-ledger.sh` 的移交检查**会核这条点名**：点名的条目不存在即**报错**。
+
+⚠️ **为什么不把工具源加进 `writes:`**（这是本条被反复重推的那个岔口，一次写死）：
+`writes:` 块**自己的判据**是"本命令**作为生产者**产出什么"，而本命令**不是**工具源的生产者
+—— 加进去会与该判据直接冲突。FR-051 要的是"**越界不发生**"，而不是"越界被声明"；
+**把一处越界写进声明，不使它成为不越界**，只是把它从可发现变成已登记。
+⇒ 工具源的生产者**仍然是任务**（`/specpro-implement` 执行一条 Location 点名了该文件的任务）。
+
+**d. Update statistics**:
+- 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.
+- Count: [plan] issues processed, remaining
+
+**e. Display completion summary**:
+```markdown
+✅ Completed [plan] issues review
+
+Processed: N issues
+Updated: specs/plan.md
+Marked as [x] in implement_issues.md
+
+⚠️ IMPORTANT: Next steps
+
+1. Run /specpro-tasks to regenerate task list
+2. Then you can process [tasks] issues
+
+Do NOT process [tasks] issues yet.
+They require the tasks update first.
+```
+
+### **Step 1: Setup & Pre-flight Validation** ✨ ENHANCED
+
+**1.1 Run setup script**:
+```bash
+.specpro/scripts/bash/setup-plan.sh --json
+```
+Parse JSON output to extract:
+- `FEATURE_SPEC`: Path to specs/spec.md
+- `IMPL_PLAN`: Path to specs/plan.md
+- `SPECS_DIR`: Path to specs/ directory
+
+**Progress**: 📋 [1/8] Setting up plan environment...
+
+**1.5 Pre-flight Validation** ✨ NEW (FAIL FAST):
+
+**Purpose**: Validate environment before executing expensive operations
+
+**a. Required files check**:
+```markdown
+Check these files exist:
+- ✅ $FEATURE_SPEC (specs/spec.md)
+- ✅ $IMPL_PLAN_TEMPLATE (.specpro/templates/plan-template.md)
+- ✅ $IMPL_PLAN_OVERVIEW_TEMPLATE (.specpro/templates/plan-overview-template.md)
+- ✅ $CONSTITUTION (specs/constitution.md)
+
+If any missing:
+❌ ERROR: Required file missing: $file
+   Fix: Run /specpro-specify or check installation
+   EXIT 1
+```
+
+**b. Directory permissions check**:
+```markdown
+Check writable directories:
+- ✅ $SPECS_DIR (specs/) is writable
+- ✅ $CONTRACTS_DIR (specs/contracts/) can be created
+
+If not writable:
+❌ ERROR: No write permission to $directory
+   Fix: chmod +w $directory or run with appropriate permissions
+   EXIT 1
+```
+
+**c. Bash scripts executable check**:
+```markdown
+Check scripts are executable:
+- ✅ setup-plan.sh
+
+If not executable:
+⚠️ WARNING: Script not executable, attempting to fix...
+   chmod +x $script
+```
+
+**d. Quality gate: requirements.md validation** 🆕 [ENFORCED - AUTO-REPAIR]:
+```markdown
+Check specs/checklists/requirements.md:
+- ✅ File exists
+- ✅ Every item marked `[x]` (passed)   ← ⚠️ **不在此处印条数**（`T238` / `T229` ③）：条数的真源是 `requirements-template.md` 的 `**Total Items**` 与清单自身，**在这里重述一个数字即制造第二个来源** —— 它已经漂过一次（此处曾印 `12`，而真值早已不是）。要看条数，去读清单自己的那份字段。
+
+⚠️ CRITICAL: This is a mandatory quality gate - QC execution is enforced automatically
+
+Check file exists:
+if [[ ! -f "$SPECS_DIR/checklists/requirements.md" ]]; then
+  ❌ AUTO-REPAIR TRIGGERED: Missing requirements.md
+
+   Problem: Spec quality validation not completed.
+   Required: specs/checklists/requirements.md (all items marked [x])
+   Current: File not found
+
+   Action: Auto-running QC to generate requirements.md...
+   ```
+   # Auto-run QC to fix missing requirements.md
+   echo ""
+   echo "🔄 AUTO-REPAIR: Running QC to generate requirements.md..."
+   /specpro-qc --scope="full"
+   # ⚠️ **No `--auto` here, and this is a decision, not an omission** (`T203` / `ISS-163`):
+   # this command's `writes:` unit for `spec.md` is its **Lifecycle fields**, so a
+   # repair of the FR PROSE is outside its write face — and delegating the repair to
+   # `/specpro-qc` does not widen it (it only moves the violation one level up, where
+   # it is harder to see). The checklist below is still produced: that happens on
+   # EVERY qc run, independently of any flag. ⇒ **Every qc call in this file is
+   # flag-less for this reason — and so is every other caller's** (`T136`): the
+   # `--fix-owner` parameter used to name the artifact whose owner was authorised to
+   # repair it, and `FR-058` removed the repair path itself ⇒ there is no such
+   # parameter to pass and **no caller that passes one**. ⚠️ **Do not restore the old
+   # wording**: an authorisation parameter whose subject no longer exists still reads
+   # as a live interface, so a reader who greps for it finds it here — and only here.
+
+   # Verify QC succeeded
+   if [[ ! -f "$SPECS_DIR/checklists/requirements.md" ]]; then
+       echo ""
+       echo "❌ AUTO-REPAIR FAILED: QC could not generate requirements.md"
+       echo "   This indicates the spec may have critical quality issues."
+       echo "   Please run /specpro-qc manually to diagnose issues."
+       exit 1
+   fi
+
+   echo "✓ AUTO-REPAIR COMPLETE: requirements.md generated"
+   ```
+
+Check all items passed:
+# 完成度按「Status 取值」判定，不按复选框——模板即 `- [ ] **Status**: …`，
+# 「诚实跳过」与「未做」在复选框上完全同形（工具缺陷 #10）
+QC_UNRESOLVED=$(grep -E '^- \[[ x]\] \*\*Status\*\*:' "$SPECS_DIR/checklists/requirements.md" 2>/dev/null \
+    | grep -vE '\*\*Status\*\*:[[:space:]]*(x|⊘[[:space:]]*Skipped)[[:space:]]*$' || true)
+if [ -n "$QC_UNRESOLVED" ]; then
+  ❌ AUTO-REPAIR TRIGGERED: Incomplete requirements.md
+
+   Problem: Spec quality validation not completed.
+   Required: specs/checklists/requirements.md (all items marked [x])
+   Current: Some items are still unchecked [ ]
+
+   Action: Auto-running QC to fix issues...
+   ```
+   # Auto-run QC to fix unchecked items
+   echo ""
+   echo "🔄 AUTO-REPAIR: Running QC to fix unchecked items..."
+   /specpro-qc --scope="incremental"
+
+   # Verify QC succeeded
+   # 完成度按「Status 取值」判定，不按复选框——模板即 `- [ ] **Status**: …`，
+   # 「诚实跳过」与「未做」在复选框上完全同形（工具缺陷 #10）
+   QC_UNRESOLVED=$(grep -E '^- \[[ x]\] \*\*Status\*\*:' "$SPECS_DIR/checklists/requirements.md" 2>/dev/null \
+       | grep -vE '\*\*Status\*\*:[[:space:]]*(x|⊘[[:space:]]*Skipped)[[:space:]]*$' || true)
+   if [ -n "$QC_UNRESOLVED" ]; then
+       echo ""
+       echo "❌ AUTO-REPAIR FAILED: QC could not resolve all issues"
+       echo "   Check specs/checklists/requirements.md for details."
+       echo "   Please run /specpro-qc manually to diagnose issues."
+       exit 1
+   fi
+
+   echo "✓ AUTO-REPAIR COMPLETE: All items now marked [x]"
+   ```
+
+✓ Quality validation passed
+```
+
+**e. Spec.md format validation**:
+```markdown
+Check spec.md has Lifecycle fields:
+- ✅ Contains "**Lifecycle**:" markers
+
+If missing:
+⚠️ WARNING: spec.md missing Lifecycle fields
+   This may cause incremental processing to fail
+   Recommendation: Run /specpro-specify to add Lifecycle tracking
+
+Your choice:
+1. Continue anyway (may encounter issues)
+2. Exit and fix Lifecycle fields first
+
+Your choice (1/2):
+```
+
+**All checks passed**: ✓ Continue to Step 2
+**Any check failed**: ❌ STOP with clear error message
+
+---
+
+### **Step 2: Load Context**
+
+**Progress**: 📋 [2/8] Loading context files...
+
+Load required files:
+- Read `FEATURE_SPEC` (specs/spec.md)
+- Read `specs/constitution.md`
+- Load `IMPL_PLAN` template (already copied by setup script)
+
+**b. Extract Acceptance Scenarios from spec.md** 🆕:
+   - For each User Story in spec.md, extract:
+     * **Independent Test** (verbatim copy - preserve exact wording)
+     * **Acceptance Scenarios** (all Given-When-Then scenarios)
+     * **Categorize scenarios by type**:
+       - Happy Path (1-2 scenarios): Core success case
+       - Error Scenarios (2-3 scenarios): Error handling and recovery
+       - Edge Cases (1-2 scenarios): Boundary conditions, constraints
+       - Permission Scenarios (1-2 scenarios): Access control, authentication
+   - **Count and validate scenarios**:
+     * Each story should have 5-9 scenarios (warn if outside range)
+     * All 4 types should be represented (warn if missing type)
+   - **Generate scenario labels**: S1, S2, S3... for each scenario in story order
+   - **Report scenario statistics**:
+     * Total scenarios per story
+     * Breakdown by type (Happy, Error, Edge, Permission)
+     * Validation warnings if applicable
+
+**Validation**: All files loaded successfully, Acceptance Scenarios extracted
+
+---
+
+### **Step 3: Quality Gates**
+
+**Progress**: 📋 [3/8] Checking quality gates...
+
+#### **3.0 Clarifications Quality Gate**
+
+**a. Check if clarifications.md exists**:
+- Read `specs/clarifications.md`
+- If file doesn't exist:
+  ```markdown
+  ⚠️ No clarifications.md found. Running /specpro-clarify --scan...
+  ```
+  - Automatically invoke: `/specpro-clarify --scan`
+  - After scan completes, re-check clarifications.md
+
+**b. Parse clarifications.md**:
+- Extract all clarification items
+- Count by category and status:
+  * [Must Clarify] with `[ ]` (unresolved)
+  * [Must Clarify] with `[x]` (resolved)
+  * [Must Clarify] with `[inferred]` (auto-inferred)
+  * [Suggested Clarify] (any status)
+  * [Can Infer] (any status)
+
+**c. Quality gate enforcement**:
+- **If ANY [Must Clarify] items are unresolved**:
+  ```markdown
+  ⛔ PLAN BLOCKED: Unresolved [Must Clarify] items
+
+  The following [Must Clarify] items must be resolved:
+  - Q[XXX]: [Question summary]
+  - Q[YYY]: [Question summary]
+
+  Total: N unresolved items
+
+  Auto-invoking /specpro-clarify...
+  ```
+  - Automatically invoke: `/specpro-clarify` (interactive mode)
+  - After clarification completes, re-check clarifications.md
+  - **MAX 3 ATTEMPTS** (new safeguard):
+    * After 3rd failed clarification attempt, require manual intervention
+    * Display: "⚠️ Maximum clarification attempts reached. Please manually resolve items in specs/clarifications.md and re-run /specpro-plan"
+
+- **If ALL [Must Clarify] items are resolved**:
+  ```markdown
+  ✓ Clarification quality gate passed
+
+  **Clarifications Status**:
+  - [Must Clarify]: N/M resolved (✓ all required items)
+  - [Suggested Clarify]: X/Y resolved or inferred
+  - [Can Infer]: P/Q resolved or inferred
+
+  Proceeding with planning...
+  ```
+  - Continue to Step 3.5
+
+**d. Optional auto-inference prompt** (if non-Must items remain):
+```markdown
+Some [Suggested Clarify] or [Can Infer] items remain unresolved.
+Auto-infer these now? (yes/no)
+```
+- If yes: Process all remaining items using auto-inference
+- If no: Proceed to planning (these items are optional)
+
+#### **3.5 Quality Validation Status** ✨ ENHANCED
+
+**Purpose**: Load and display quality checklist status, load recommendations into planning context
+
+**Progress**: 📋 [3.5/8] Checking quality validation status...
+
+**a. Check if checklists/requirements.md exists** 🆕 [ENFORCED - AUTO-REPAIR]:
+- Read `specs/checklists/requirements.md`
+- If file doesn't exist:
+  ```markdown
+  ❌ AUTO-REPAIR TRIGGERED: Missing requirements.md
+
+  Problem: Quality validation not completed before planning.
+  Required: specs/checklists/requirements.md (quality validation artifact)
+  Current: File not found
+
+  Action: Auto-running QC to generate requirements.md...
+  ```
+  # Auto-run QC to fix missing requirements.md
+  echo ""
+  echo "🔄 AUTO-REPAIR: Running QC to generate requirements.md..."
+  /specpro-qc --scope="full"
+
+  # Verify QC succeeded
+  if [[ ! -f "$SPECS_DIR/checklists/requirements.md" ]]; then
+      echo ""
+      echo "❌ AUTO-REPAIR FAILED: QC could not generate requirements.md"
+      echo "   Planning is BLOCKED without quality validation."
+      echo "   Please run /specpro-qc manually to diagnose issues."
+      exit 1
+  fi
+
+  echo "✓ AUTO-REPAIR COMPLETE: requirements.md generated, proceeding with planning..."
+  ```
+  - Continue to Step 4 (quality validation complete)
+
+**b. Parse checklist for validation results**:
+- Read the checklist's **own** fields — verbatim, and only these:
+  * `**Status**`: `PASS` | `BLOCK` — the producer sets `PASS` ⟺ `**Failed**` == 0
+  * `**Total Items**` · `**Passed**` · `**Failed**`
+  * per-item rows: `- [ ] **Status**: x | ⊘ Skipped | ✗ Failed`
+- ⚠️ Do **not** look for `Overall Quality`, a `N/M` score, or a warning tier:
+  `templates/requirements-template.md` emits none of them ⇒ a reader keyed on
+  them finds nothing on **every** checklist and reports "no warnings", which is
+  indistinguishable from a clean pass.
+- The blocking set = the rows whose per-item value is `✗ Failed`.
+- The `⊘ Skipped` rows are **non-blocking**: the template's rule is that an honest
+  skip is a conclusion, not a debt. Surface them; never gate on them.
+
+**c. Display quality status summary** (fields verbatim from the checklist):
+```markdown
+## Quality Validation Status
+
+**Status**: PASS | BLOCK
+**Passed**: 22 / 25
+
+**Blocking (✗ Failed)**:
+- "Protocol implementation test-first"
+  - Constitution Article IV requires >90% test coverage
+  - But FR-xxx~FR-yyy (the wire-protocol requirements) do not specify testing requirements
+
+**Skipped (⊘)** — non-blocking; listed so the skips stay visible:
+- "Edge cases not identified"
+- "Assumptions not converted to FRs"
+```
+
+**d. Handle blocking issues**:
+- **If `**Status**: BLOCK`** (any `✗ Failed` row):
+  ```markdown
+  **Blocking Issues Detected** (N issues)
+
+  Fix issues before planning, or proceed despite issues? (fix/proceed)
+  ```
+  - If fix: Wait for user to update spec.md, then re-run validation
+  - If proceed: Mark as ⚠️ "Proceeding despite blocking issues" and continue
+
+- **If `**Status**: PASS`**: display the summary from **c** — including the
+  `⊘ Skipped` rows — and continue. ⚠️ A `⊘ Skipped` row does **not** open the
+  "proceed despite" prompt above: an honest skip needs no risk acknowledgment.
+
+**e. Load recommendations into planning context**:
+- Extract all recommendations from checklist
+- Categorize by priority (High/Medium/Low)
+- Store for use in Phase 0 (Research) and Phase 1 (Design)
+- Examples:
+  * "High Priority: Add test coverage requirement for the wire-protocol module (Constitution)"
+  * "Medium Priority: Add 4K streaming performance edge cases"
+  * "Medium Priority: Explicitly state LAN latency assumption in FR-xxx"
+
+---
+
+### **Step 4: Load Lifecycle Status (One-Time Cache)** ✨ OPTIMIZED
+
+**Purpose**: Create lifecycle_cache ONCE, avoid redundant spec.md reads
+
+**Progress**: 📋 [4/8] Loading Lifecycle status...
+
+**4.a Parse ALL Lifecycle fields from spec.md** (ONE TIME READ):
+```markdown
+Load FEATURE_SPEC and extract ALL items with Lifecycle fields:
+- User Stories: ID, Title, Priority, Lifecycle: [specify:<status>][plan:<status>][tasks:<status>]
+- Functional Requirements: ID, Title, Lifecycle: [specify:<status>][plan:<status>][tasks:<status>]
+
+Status values: create, update, delete, processed, deprecated
+Example: **Lifecycle**: [specify:create][plan:processed][tasks:processed]
+
+Create lifecycle_cache object:
+```
+
+**4.b Create lifecycle_cache**:
+```javascript
+lifecycle_cache = {
+  version: "1.0",
+  generated_at: "YYYY-MM-DD HH:MM:SS",
+  statistics: {
+    total_items: 0,
+    new_items: 0,        // planStatus = "create"
+    modified_items: 0,   // planStatus = "update"
+    deprecated_items: 0, // planStatus = "deprecated"
+    completed_items: 0   // planStatus = "processed"
+  },
+  items: [
+    {
+      id: "FR-xxx",
+      type: "FR",
+      title: "Plugin API",
+      specStatus: "create",
+      planStatus: "processed",  // Already planned
+      tasksStatus: "processed"  // Already task-broken
+    },
+    {
+      id: "FR-xxx",
+      type: "FR",
+      title: "Connection Manager",
+      specStatus: "create",
+      planStatus: "create",     // ← NEW, needs planning
+      tasksStatus: "create"     // ← NEW, needs task breakdown
+    },
+    // ... all items
+  ],
+
+  // Helper methods
+  byPlanStatus: function(status) {
+    return this.items.filter(item => item.planStatus === status);
+  },
+
+  bySpecStatus: function(status) {
+    return this.items.filter(item => item.specStatus === status);
+  },
+
+  needsProcessing: function() {
+    // Items needing planning: planStatus != "processed" && planStatus != "deprecated"
+    return this.items.filter(item =>
+      item.planStatus !== "processed" && item.planStatus !== "deprecated"
+    );
+  }
+}
+```
+
+**4.c Categorize items by PlanStatus**:
+```markdown
+Processing categories:
+- New items: N (planStatus = "create") → NEED planning
+- Modified items: M (planStatus = "update") → NEED re-planning
+- Deprecated items: Z (planStatus = "deprecated") → NEED cleanup
+- Skipping: K (planStatus = "processed") → PRESERVE [x]
+```
+
+**4.d Report processing statistics**:
+```markdown
+## Lifecycle Processing Summary
+
+**Total Items**: N
+- **New items**: X (need planning, PlanStatus empty)
+- **Modified items**: Y (need re-planning, PlanStatus Modified)
+- **Deprecated items**: Z (need cleanup, PlanStatus Deprecated)
+- **Skipping**: M (already Processed, will mark as [x])
+
+Processing X+Y items, preserving M items, removing Z items...
+```
+
+**4.e Filter items for workflow**:
+- Create `filtered_items` list containing only:
+  * Items where PlanStatus != "Processed"
+  * These are the ONLY items to include in plan generation
+- Items with PlanStatus = "Processed" are:
+  * Marked as [x] in plan.md
+  * Excluded from design generation
+  * Preserved for reference
+
+**KEY OPTIMIZATION**: All subsequent steps (5-7) MUST use `lifecycle_cache`, NOT re-read spec.md
+
+---
+
+### **Step 5: Generate Plan.md** (Using lifecycle_cache)
+
+**Progress**: 📋 [5/8] Generating plan.md sections...
+
+**5.0 Load Lifecycle Status from Cache** ✨ OPTIMIZED:
+```markdown
+**DO NOT re-read spec.md** - Use lifecycle_cache from Step 4
+
+a. Create completion status map:
+   - Load from lifecycle_cache.items
+   - Map: itemId → { planStatus, specStatus, tasksStatus }
+
+b. ⚠️ **[x]/[ ] 标记规则只适用于 §5.x 那批 Part I 小节 —— 不适用于 Part II**（T171 修正）：
+   本节此前给出「Mark as [x] / Mark as [ ]」的规则，并在 `c` 里要求把它用到 **Implementation Plan
+   阶段**上；而 **§5.6 明令该章节不得出现复选框**（`**No checkboxes. No ✅/⚠️/❌. No "status" column.**`
+   · `**Validation**: … no checkbox syntax`）——**同一份文档里，一处指示写、另一处禁止写**。
+   ⇒ **§5.6 是后出的裁决，本节服从它**：那里的进度由 `lifecycle_cache` 在**生成时**决定
+   （FR 是 `create`/`update` 就重跑，`processed` 就跳过），**不落成复选框**。
+   ⇒ Part I 小节的 `- [x]` 标记照旧（那些是机器读的交付物清单，`tasks` 按它取件）。
+
+Example:
+```markdown
+#### Phase 2: Core Infrastructure
+**Deliverables**:
+- [x] PluginManager (FR-xxx) ← planStatus = "processed"
+- [x] ProtocolHandler (FR-xxx) ← planStatus = "processed"
+- [ ] ConnectionManager (FR-xxx) ← planStatus = "create" (new)
+```
+```
+
+**Validation**: lifecycle_cache loaded successfully, map created
+
+### **Part assignment and two standing rules** ⚠️ [read before generating any §5.x section]
+
+**Part assignment — TWO FILES, not two halves of one file** (settled 2026-09-13). Each §5.x step below carries a marker saying **which file it writes**:
+
+| Marker | File | Template | Standing |
+|--------|------|----------|----------|
+| 🅼 **[Machine-Read]** | **`specs/plan.md`** | `.specpro/templates/plan-template.md` | Consumed by downstream commands, which extract **by section**. MUST be mechanically parseable. No checkboxes, no status, no decision narrative. |
+| 🅷 **[Human-Read]** | **`specs/plan-overview.md`** | `.specpro/templates/plan-overview-template.md` | For people; *sufficient useful information is enough.* **No command reads it** — and **no command may reference its section names**. |
+
+**Why two files rather than one file with two halves.** The rule "implement never reads the human half" would otherwise be a *convention* that holds only as long as every reader extracts by section. A reader that loads a whole file would silently pull the human half into a task's context, and nothing would report it. Separate files make it **structural**: the human half is not in the file being read. This follows the boundary-declaration discipline: *a constraint with no enforcement point is a statement, not a constraint.*
+
+> **Cross-file references are one-way.** `plan.md` MUST NOT reference `plan-overview.md` section names either — a machine-read artifact that points at a human-read one reintroduces the coupling the split removes. Pointing at the *file* by path is fine (the reader can choose to open it); pointing at a *section* is not.
+
+> **The generation order of the §5.x steps is NOT the file order.** All §5.x steps run before Phase 0 (they "write the document"), and Step 6.5 backfills afterwards. The **file order is the template's** — Part I sections first, then Part II. Do not reorder the file to match the steps.
+
+**Standing rule 0 — every section declares its purpose and consumers** (settled 2026-09-13).
+
+**Every `##` and `###` section MUST open with a one-line `*Purpose · Consumers*` note.** Write it before the content, from the template's own line for that section — do not leave it blank, and do not write a vague one.
+
+Three requirements on that line:
+1. **Name the consumers concretely** — the command and the step that reads it (`tasks` §4.j-2), not "downstream" or "the workflow".
+2. **Say what is done with it** — extracted for task generation? used as an acceptance threshold? a grounding reference? A consumer named without a use is not a declaration.
+3. **If no machine consumer exists, say so plainly** — and then ask whether the section belongs in Part I at all. **A section in Part I with no machine consumer is a Part-assignment error** (see below), not a labelling problem.
+
+⚠️ **Cover sub-sections too, not just top-level sections.** The failure this rule prevents: top-level sections get the line, sub-sections do not — and the sub-sections are exactly what the per-subsection extractions (`§4.i-1..i-4`, `§4.j-1..j-3`) read. A reader then cannot tell which sub-section feeds which downstream step.
+
+**Standing rule 1 — no upstream-reads-downstream.** This stage MUST NOT read a later stage's artifact to refresh its own content. If a piece of information's source of truth is downstream (test assets, coverage reports, task state), it MUST NOT be written into plan.md at all: this stage has no way to keep it current, so it would freeze at the value it had when written while downstream consumers act on that stale value. Two known instances of this trap: per-phase checkboxes (§5.6b) and the protocol inventory's coverage-status column (§5.4g).
+
+**Standing rule 2 — change propagation.** When a **Part I** section changes, the change MUST reach `tasks` — but only through the FR state, because that is the only channel `tasks` reads:
+
+- **Record the change**: a technology or architecture change MUST leave a record — as a `[plan]` issue entry in `specs/implement_issues.md` when it was driven by one, or as an entry in `## Complexity Tracking` (§5.7) when it came from a user decision or this stage's own reasoning. **An unrecorded design change is the failure this rule exists to prevent.**
+- **Stay within SDD**: spec.md remains the sole source of requirements. This is not a licence to invent requirements here.
+- **Judge the blast radius yourself — this is deliberately not mechanical.** By change type: a spec item change → that item; a technology swap → the FRs that rely on that technology for their satisfaction (swapping the network library touches the network-transport FRs, not FR text — the FR says "non-blocking async I/O" and does not name a library); a threshold change → the FRs in that threshold's risk band; a new/changed constraint → the constraint's scope; a placement change → the tasks whose paths match the pattern. **A purely editorial or structural change (wording, ordering, de-duplication) changes nothing downstream — issue no signal.**
+- **Update the state**: set `[tasks:update]` on each affected FR/US so `tasks` regenerates their tasks.
+- **If you cannot identify the blast radius**, the change has **no FR anchor** — that is the signal to register it as an issue for the appropriate stage instead of writing it silently.
+
+**Why this is a rule and not a mechanism:** a change made here that never reaches `tasks` leaves `tasks.md` built on the old design — and because `tasks` gates on FR state, even a manual re-run will not produce new tasks for it. There is no mechanical detector for "changed but not signalled"; the four steps above are the backstop.
+
+---
+
+#### **5.1 Generate Summary Section** 🅷 **→ `specs/plan-overview.md`**
+
+**Progress**: 📋 [5.1/8] Generating Summary section...
+
+Extract from spec.md:
+- Paragraph 1: What is being built (from Overview)
+- Paragraph 2: Technical approach (**from research.md** — see note below)
+- Paragraph 3: Key outcomes (from Overview and quantified FRs)
+
+> ⚠️ **Paragraph 2's input does not exist yet when this step runs** (settled 2026-09-13). This section is written in the §5.x block, which runs **before** Phase 0 Research — so on an initial run `research.md` is absent. In initial mode write paragraph 2 from what is available and **mark it for backfill**; **Step 6.5 backfills it** once research.md exists. Leaving it without a backfill leaves a technical-approach paragraph with no source, and nothing detects it afterwards.
+
+**Validation**: 2-3 paragraphs, includes "what" and "how"; paragraph 2's source is either research.md (incremental run) or scheduled for Step 6.5 backfill (initial run).
+
+#### **5.2 Generate Technical Context Section** 🅼 **→ `specs/plan.md`**
+
+**Progress**: 📋 [5.2/8] Generating Technical Context...
+
+For each field, use extraction rules:
+
+| Field | Extraction Rule | Default if Not Found |
+|-------|----------------|---------------------|
+| **Language/Version** | Check spec.md for "Kotlin", "Python", etc. | NEEDS CLARIFICATION |
+| **Primary Dependencies** | Extract from research.md "Dependencies" | NEEDS CLARIFICATION |
+| **Storage** | Check spec.md for persistence requirements | N/A |
+| **Testing** | Extract from research.md "Testing Framework" | NEEDS CLARIFICATION |
+| **Target Platform** | Extract from spec.md Overview | NEEDS CLARIFICATION |
+| **Project Type** | Infer from Technical Context | single |
+| **Performance Goals** | Extract quantified targets from spec.md FRs (latency / throughput / capacity) | NEEDS CLARIFICATION |
+| **Constraints** | Extract from research.md + Constitution | NEEDS CLARIFICATION |
+| **Scale/Scope** | Extract from spec.md Overview | NEEDS CLARIFICATION |
+
+**Validation**: All 9 fields filled (can have NEEDS CLARIFICATION)
+
+#### **5.3 Generate Constitution Check Section** 🅷 **→ `specs/plan-overview.md`**
+
+**Progress**: 📋 [5.3/8] Generating Constitution Check...
+
+**a. Load Constitution**: Read `specs/constitution.md`
+
+**b. Identify Applicable Principles**:
+- Use keyword matching from spec.md
+- Example mappings:
+  * "network", "connect" → Principle V (Performance & Resource Management)
+  * "protocol", "encoding" → Article IV (Risk-Based Quality Assurance)
+  * "multiplatform", "Android", "iOS" → Platform-specific principles
+  * "security", "encryption" → Security principles
+
+**c. For Each Applicable Principle**:
+- Extract requirement text
+- Evaluate compliance against spec.md and plan.md
+- Document status: ✅ PASS or ❌ FAIL
+- If FAIL: Provide justification (requires Complexity Tracking section)
+
+**d. Format Output**:
+```markdown
+### ✅ [Principle Name]
+
+**Requirement**: [Specific requirement]
+**Status**: PASS | ⚠️ PARTIAL | ❌ FAIL
+
+**Compliance**:
+- ✅ [Evidence 1]
+- ✅ [Evidence 2]
+
+### Overall Constitution Compliance: ✅ PASS (X/Y principles)
+```
+
+**e. State the level explicitly when a gap exists** ⚠️ (settled 2026-09-13): a design can satisfy a principle **at the design level** while an **integration-level** gap remains tracked. Write both levels out — `Overall … PASS (6/6)` alongside a principle marked `⚠️ PARTIAL — component-level PASS, integration gap tracked` is **not** a contradiction *if the qualifier is stated*; without it, the two lines read as contradictory and the reader cannot tell which one is current. Never let a principle's own status and the overall line disagree in silence: if the overall line means "at the design level", say so on that line.
+
+**f. FR-level risk enumeration is NOT here** ⚠️ (settled 2026-09-13): the per-FR risk split (`HIGH-RISK: FR-011~024E …` / `MEDIUM-RISK: …` / `LOW-RISK: …`) **belongs in `Quality Targets → Risk Classification` (§5.3.1)**, next to the coverage table it pairs with — because it is a **machine input** (`tasks` §4.j-2 reads it to classify each FR), not a compliance statement. Put it here and it sits in a human-read section that no command extracts.
+
+**Validation**: All applicable principles evaluated; overall assessment provided; when any principle is PARTIAL or FAIL, the level qualifier (design-level vs integration-level) is stated on both the principle and the overall line.
+
+#### **5.3.1 Generate Quality Targets Section** ✨ NEW 🅼 **→ `specs/plan.md`**
+
+**Progress**: 📋 [5.3.1/8] Generating Quality Targets...
+
+**Purpose**: Automatically determine project type and set appropriate test coverage targets based on Constitution Article IV principles
+
+**a. Infer Project Type** 📋 [CRITICAL]:
+Analyze spec.md and technical context to determine project type:
+
+**Decision Logic** (in order of priority):
+
+1. **Medical/Life-Critical** (Highest priority):
+   - Keywords: "medical", "health", "patient", "clinical", "diagnostic", "FDA", "IEC 62304"
+   - Impact: Life-safety or health-critical
+   - → Project Type: **Medical Application**
+
+2. **Financial/Trading**:
+   - Keywords: "financial", "trading", "payment", "banking", "transaction", "SEC", "FINRA", "PCI-DSS"
+   - Impact: Direct monetary loss or regulatory compliance
+   - → Project Type: **Financial/Trading Application**
+
+3. **Platform/Framework**:
+   - Keywords: "platform", "framework", "SDK", "library", "API", "plugin", "multi-application"
+   - Impact: Multiple applications depend on this codebase
+   - → Project Type: **Platform Application**
+
+4. **Enterprise/Business**:
+   - Keywords: "enterprise", "business", "SaaS", "B2B", "team", "organization", "company"
+   - Impact: Business processes depend on this software
+   - → Project Type: **Enterprise Application**
+
+5. **MVP/Prototype**:
+   - Keywords: "MVP", "prototype", "proof of concept", "validate", "experiment", "hackathon"
+   - Impact: Early-stage, high rate of change
+   - → Project Type: **MVP/Prototype**
+
+6. **Personal Application** (Default):
+   - Keywords: "personal", "individual", "hobby", "personal productivity"
+   - Impact: Single user
+   - → Project Type: **Personal Application**
+
+**Inference Process**:
+- Check spec.md Overview for keywords
+- Check spec.md quantified FRs for impact statements
+- Check Technical Context for deployment model
+- Default to "Enterprise Application" if unclear
+
+**b. Select Coverage Targets** 📋 [CRITICAL]:
+Based on the inferred project type, **copy the coverage targets from the constitution's Quality Assurance Matrix** — ⚠️ **they are NOT listed here** (`T242` / `ISS-215`):
+
+- **Read** `specs/constitution.md` → the Quality Assurance Matrix (one row per project type) and take that project type's three targets.
+- **Then classify this project's modules** by risk level (step `c` below) and fill `### Risk-Based Coverage Targets` (plan.md) and `### Risk Classification` with them.
+
+⚠️ **This step used to carry its own copy of the matrix**, and the toolchain had **three copies of the same defaults in total** (this one, the plan template's, and the constitution command's matrix). The two plan-side copies agreed with each other and **disagreed with the source in five of six rows** (Platform: 90/70/0 here vs 95/85/50 in the matrix) — a restated default is a source that drifts without reporting, which is why this copy is gone rather than corrected. **Do not paste a table back here**: if the defaults need to change, they change in the matrix.
+
+**c. Identify Risk Level Examples** — produce the **`### Risk Classification`** subsection:
+For each risk level, enumerate the **FR ids** (not just module descriptions):
+
+| Risk level | Test-First | FR list |
+|------------|-----------|---------|
+| HIGH-RISK | MANDATORY | [FR-xxx, FR-yyy …] |
+| MEDIUM-RISK | RECOMMENDED | [FR-xxx …] |
+| LOW-RISK | OPTIONAL | [FR-xxx …] |
+
+- **HIGH-RISK** — protocol implementations (if "protocol"/"encoding" in spec.md) · cryptography/security (if "encryption"/"authentication") · network transport (if "network"/"connection") · critical data operations · financial calculations (if Financial project type)
+- **MEDIUM-RISK** — business logic and orchestration · data models and repositories · platform API bindings (if "multiplatform")
+- **LOW-RISK** — UI components (if "UI"/"frontend") · utilities and helpers · dev tools
+
+⚠️ **FR ids are mandatory here** (settled 2026-09-13): `tasks` §4.j-2 reads this table **per FR** to classify each requirement, and §4.j-3 annotates the generated tasks from it. A table of module descriptions with no FR ids cannot be consumed — the reader would have to re-derive the mapping the table was supposed to supply.
+⚠️ **This subsection is where the FR-level risk split lives** — it was previously written into `## Constitution Check` (Part II, human-read) where nothing extracted it. See §5.3f.
+
+**d. Format Output**:
+```markdown
+## Quality Targets
+
+*PURPOSE: Define project-specific quality standards based on Constitution principles and project type*
+
+### Project Type Classification
+
+**Project Type**: **[Inferred Type]** [Emoji]
+
+**Rationale**:
+- [Why this project type was chosen based on spec.md analysis]
+- [Impact of bugs/failures on users]
+- [Stability and reliability requirements]
+
+**Impact on Quality Standards**:
+- [How project type influences coverage targets]
+- [Trade-offs between velocity and quality]
+
+### Risk-Based Coverage Targets
+
+| Risk Level | Coverage Target | Test Approach | Example Modules |
+|------------|----------------|---------------|-----------------|
+| **HIGH-RISK** | **>XX%** | MANDATORY Test-First | [Examples from spec.md] |
+| **MEDIUM-RISK** | **>YY%** | RECOMMENDED Test-First | [Examples from spec.md] |
+| **LOW-RISK** | **Optional** | Manual testing acceptable | [Examples from spec.md] |
+
+### Constitution Compliance
+
+**Constitution Reference**: Article IV (Risk-Based Quality Assurance)
+
+**Alignment**:
+- ✅ Coverage targets proportional to module risk level
+- ✅ HIGH-RISK modules: Test-First MANDATORY with >XX% coverage
+- ✅ MEDIUM-RISK modules: Test-First RECOMMENDED with >YY% coverage
+- ✅ LOW-RISK modules: Testing OPTIONAL (manual acceptable)
+
+### Quality Validation Strategy
+
+**Per User Story Phase** (executed by `/specpro-tasks` Step j — unit-test tasks ONLY; integration / component E2E / app E2E are planned separately by `/specpro-test-plan` into specs/test-tasks.md):
+- Generate unit test tasks (`[Quality]` tasks) based on FR risk level (tasks Step j-4)
+- Annotate implementation tasks with risk level and coverage requirement (tasks Step j-3)
+- Add quality checkpoint to verify coverage targets met (tasks Step j-5)
+
+**Measurement**:
+- Code coverage measured via [coverage tool based on language]
+- Scenario automation measured via test scenario count (target: 85-90% of scenarios)
+- Both dimensions tracked independently
+
+**Quality Gates**:
+- HIGH-RISK FRs must achieve >XX% unit-test coverage before merge
+- MEDIUM-RISK FRs recommended >YY% unit-test coverage before merge
+- All tests must pass — unit tests via tasks.md; contract / integration / E2E via specs/test-tasks.md
+```
+
+**e. Language-Specific Coverage Tools**:
+Select coverage tool based on Technical Context:
+- **Kotlin/JVM**: JaCoCo
+- **Kotlin Multiplatform**: JaCoCo (JVM targets) + platform-specific tools
+- **TypeScript/JavaScript**: Istanbul/NYC
+- **Python**: Coverage.py or pytest-cov
+- **Go**: Built-in coverage
+- **Java**: JaCoCo
+- **Rust**: tarpaulin or cargo-llvm-cov
+
+**Validation**: Quality Targets section complete with:
+- ✅ Project type inferred from spec.md
+- ✅ Coverage targets selected based on project type
+- ✅ Example modules extracted from spec.md
+- ✅ Constitution compliance documented
+- ✅ Measurement strategy defined
+- ✅ Coverage tool specified
+- ✅ ⚠️ **`### Risk Classification` 的每一档都带 FR ids，且**逐档抽样核对**：抽到的号确实
+  出现在 `spec.md`（T171 / audit finding：「plan 要求某表必须有 FR ids，而其自身验证不含该性质」）。
+  **判据**：把该表三档里的 FR 号**逐个**与 `spec.md` 的定义对一遍 —— 数"表里有几个号"证明不了
+  它们**是**东西；而这张表正是 `tasks` §4.j-2 **逐 FR** 读它来分类的那一张。
+
+#### **5.4 Generate Architecture Section** 🅼 **→ `specs/plan.md`** — except (a), which goes to `plan-overview.md` (see below)
+
+**Progress**: 📋 [5.4/8] Generating Architecture...
+
+> ⚠️ **This section spans both parts** (settled 2026-09-13):
+> - **(a) System Overview → Part II** (human-read). It is the runtime component-stack view.
+> - **(b)–(g) → Part I** (machine-read). They are the source-set ownership view plus the protocol spec, and `tasks` §4.i-1..i-4 extracts from them per subsection.
+>
+> Both views MUST carry a view-semantics line so a reader — human or machine — never has to guess which model a layering claim belongs to.
+
+**a. System Overview** 🅷 **→ `specs/plan-overview.md`**:
+- Architecture diagram or text description
+- Major subsystems and relationships
+- Core architecture pattern (e.g., microkernel + plugins)
+- 2-3 sentence summary
+- **MUST state the view semantics**: this view is the **runtime component stack**; the Layered Architecture below is the **source-set ownership** view. They answer different questions and MUST NOT be applied to each other. Without this line a project can end up with a diagram whose layering contradicts the prose — and the prose is what `tasks` §4.i-2 extracts from, so the human reader and the machine would be working from two different layer models.
+
+**b. Layered Architecture** 🅼 **[Part I · Machine-Read]**:
+- Define 2-4 major layers
+- For each layer:
+  * Responsibilities
+  * Contains (specific components)
+  * Constraints (Must/Must not) — **each constraint MUST carry its source anchor** (an FR id, or `Constitution Principle N`). A constraint with no anchor is not grounded: state where it comes from or drop it.
+
+**c. Component Interaction** 🅼 **[Part I · Machine-Read]**:
+- How major components interact
+- Key interaction patterns (e.g., Plugin → Core)
+- **Coverage criterion — the RELATIONSHIPS must be complete, not the count.** MUST cover at least: plugin↔core · plugin↔plugin · any cross-process or cross-device interaction. Do not treat "one pattern is enough" as satisfied: a constraint that regulates a relationship (e.g. "plugins MUST communicate via the event bus") presupposes that relationship is itself a registered pattern — a constraint over an unregistered pattern is a dangling rule.
+- Interaction constraints — **each MUST carry its source anchor** (FR id or `Constitution Principle N`), same rule as (b).
+
+**d. Architecture Patterns** (CRITICAL: Keep concise):
+- Document 2-5 critical patterns
+- **NO** detailed Problem/Solution/Trade-offs (those belong in research.md)
+- For each pattern:
+  * **Description**: Brief description
+  * **Key Points**: What it provides, how it's used
+  * **See**: Reference to research.md section for detailed analysis
+
+**e. Critical Constraints**:
+- Define architecture-level constraints
+- For each: Requirement, Architecture Impact
+
+**f. Shared/Platform Boundary Declaration** 🌐 [CONDITIONAL — only when the constitution contains a shared-code / multiplatform / core-logic principle]
+
+**Why this subsection exists**: a layered-architecture description names layers but does not say which concrete source set each layer OWNS. Left unstated, module placement follows whichever directory is nearest at implementation time, and two components with the same role drift into different locations — the layered diagram still looks correct throughout, so nothing detects the drift. The declaration below closes that gap by making the boundary a checkable product, in the same shape as the protocol Activation Gate: state the verdict, make it mechanically reproducible.
+
+**f.1 Read the constitution principles first.** For every principle that mandates shared code, core logic, a shared protocol, or a cross-platform module, extract:
+- the **mandated scope** — the categories it says MUST be shared (e.g. business logic, core protocol, data models)
+- the **excluded scope** — what it says platform layers may contain (e.g. platform bindings, UI rendering, hardware integration)
+
+**f.2 Emit the declaration table** (one row per principle-scope pair):
+
+| Planned home | Constitutional basis | Category (protocol / business logic / data model / platform abstraction) | Owning layer | Corpus set — the shared source set mandatory for that layer | Path pattern |
+|---|---|---|---|---|---|
+| `XxxProtocol` | Principle \<N\> | protocol | shared | `commonMain` (or the build's equivalent) | `core/src/commonMain/.../protocol/...` |
+| `XxxBinding` | Principle \<N\> | platform abstraction | platform-specific | platform source sets | `core/src/{platform}Main/...` |
+
+Two columns carry the weight and MUST NOT be left vague:
+- **Corpus set** — the *shared* source set the layer is mandatory in, AND the platform source sets that merely *may* extend it. A layer marked shared but landing only in a platform set never reaches the other platforms; the requirement is not "exists somewhere" but "lives in the corpus set".
+- **Path pattern** — a concrete path, not a name. A scope claimed without a location cannot be audited.
+
+**f.3 State the dependency boundary the corpus set must honour.** For each shared layer, record what it MUST NOT depend on. Draw these from the architecture's own layers: a protocol layer MUST NOT depend on a transport-layer object (a live socket, connection, or session holder) — a handler that takes one cannot be constructed without a real network, which makes independent testing impossible and forces every verification end-to-end, where timing coupling masquerades as test flakiness.
+
+**f.4 State the platform-abstraction requirement.** When the shared layer needs a capability the platform provides (compression, image codec, file system, crypto), declare it as an expect/actual pair: the declaration lives in the corpus set, the implementation in each platform set. Listing the capability without its abstraction means the shared layer cannot compile for the other platforms — and the failure surfaces only at build time on a platform the author may not be running.
+
+**Validation**: the declaration table exists whenever the constitution carries a shared-code principle; every shared code category named in that principle traces to a row; every row has both a corpus set and a path pattern; shared layers that consume platform capabilities have a corresponding expect/actual pair declared. A plan with a multiplatform constitution and no boundary declaration is incomplete — record it as a gap rather than omitting the subsection.
+
+**g. Protocol Codec Design Artifacts** 🌐 [CONDITIONAL — only when the Activation Gate is ACTIVE or ACTIVE-WITH-GAPS] 🅼 **[Part I · Machine-Read]**:
+
+**Hosting (settled 2026-09-13)**: these artifacts live **here, under `## Architecture`** — they are design specification, not quality targets. The protocol rules in the seven commands require the design output to contain them but do not name a host section; without one they end up parked wherever space is free (in one project: under `## Quality Targets`, which is semantically wrong and — because that section carried no validation — went unnoticed).
+
+Produce, per `.specpro/templates/protocol-golden-bytes-guide.md`:
+- **`**Verdict record (§6.4)**`** — the stage/verdict/trigger/evidence/artifacts table. One row per consuming stage.
+- **`#### Protocol-Point Inventory` (§1)** — one row per protocol point, granularity to the **branch**; ambiguous semantics recorded as **byte-level examples, never prose**.
+  ⚠️ **The last column is `Coverage method`, NOT coverage status.** It states the testing *means* the point requires (matrix cases / property tests / incremental-context cases / environment annotations) — a design specification, fixed when the row is written. Which points are covered *right now* is a **downstream** fact (the actual test assets) and MUST NOT be recorded here: this stage cannot keep it current without reading downstream artifacts, and downstream consumers would act on a stale value. **Anchor reachability** IS recorded here — an unreachable anchor is a **GAP** (§6.3), because only the stage that did the anchoring knows whether the source was reachable.
+- **`#### Golden-Bytes Strategy` (§2)** — L1→L2→L3 cross-anchoring, each anchor stating its source layer and protocol version.
+- **`#### Test Matrix` (§3)** — the four-part shape for codec modules: decode matrix · encode reverse matrix · shared golden-bytes fixture · property-test extension. Two requirements carry the weight:
+  - **Error paths are part of the matrix** — truncated stream, invalid control byte, over-long run, out-of-range index: each MUST have a **decided** expected behaviour (reject vs tolerate). "Unspecified" is not an answer.
+  - **Admissibility of a shared fixture anchor** ⚠️: every anchor MUST first pass §2's three-layer check (source layer + protocol version), or be recorded as a GAP (§6.3). **A constructor whose semantics came from the implementation under test MUST NOT be promoted into the shared fixture** — generalising it copies the same misreading into both the encoder and the decoder side, so every assertion passes by construction (§3.1's self-confirming loop). A project that has such a "behaviour-lock" constructor already (built for a pilot matrix) MUST say so here and forbid its promotion.
+- **`#### Stream-Semantics Comparison` (MANDATORY when one client speaks several encoders)** — continuous single stream vs per-message independent stream. ⚠️ **No single guide section owns this** — the rule is distributed across the guide: continuous-stream segmented verification uses a **reuse-style decode path** (§2), the lateral audit scans sibling functions for the same stream-semantics defect (§4, L1), and a fix's lesson MUST NOT be transferred to another encoder by default because the semantics may be opposite (§7). Cite those, not a non-existent section.
+
+**g2. Shared-Layer Relocation Design** 🌐 [CONDITIONAL — only when the boundary declaration and the build disagree] 🅼 **[Part I · Machine-Read]**:
+
+**When**: `f` produced a declaration but an audit (`analyze` Pass M) found the build disagrees — shared-mandated code in a platform-only source set, a handler constructed from a live transport object, a platform dialect imported into a shared file. The declaration states intent; **it does not state how to get from here to there**. No disagreement → omit.
+
+Produce, under `### Shared-Layer Relocation Design`:
+- **Design decisions the declaration does not cover** — the dependency shape a shared component MUST NOT take, and the platform abstractions it consumes. Each with its **rejected alternative** (this is where "the handler must not take a live connection" and *why the simpler route was insufficient* belong).
+- **Migration plan** — ordered steps: what moves, from where to where, what depends on it, how the move is verified.
+- **Rulings** — decisions taken along the way: what was decided · what was rejected · why · evidence. A ruling that changes an earlier statement MUST say so explicitly rather than silently superseding it.
+- **Dispatch breakdown** — which work items this design produces for `/specpro-tasks`. ⚠️ **These items are NOT task IDs** — plan MUST NOT invent an ID prefix; `/specpro-tasks` assigns `T-nnn`. They carry no FR, so the FR-driven generation path does not apply.
+
+**Validation**: every design decision carries a rejected alternative; every migration step names its verification; the dispatch breakdown uses plain numbered items with no invented ID prefix.
+
+**Validation**: when the gate is ACTIVE or ACTIVE-WITH-GAPS, all four items are present; the inventory's last column contains **no** ✅/⚠️/❌ status; every unroutable anchor is a GAP row rather than an invented byte sequence.
+
+**Validation (subsection completeness)**: every subsection this step defines is present and non-empty. ⚠️ The authoritative subsection list is the **template's `## Architecture`**, never a hand-written enumeration here — a hard-coded count goes stale the moment the template gains or loses a subsection (and a stale count silently mis-directs whoever reads it next). The chapter-level check is §5.8's job.
+
+#### **5.5 Generate Project Structure Section** 🅼 **→ `specs/plan.md`**
+
+**Progress**: 📋 [5.5/8] Generating Project Structure...
+
+**Three rules for this section** (settled 2026-09-13; each comes from an observed failure):
+
+1. **Granularity — directories and path patterns, never file names.** File names are an implementation choice and belong to whoever implements. A plan that enumerates them goes stale the moment anything is renamed or merged, and a stale placement list **looks like a fact** — in one project the tree still showed the protocol core under `commonMain` long after it had landed in `jvmMain`, which made a constitution-level deviation read as compliant.
+2. **Single authority for the shared/platform boundary.** `## Architecture → ### Shared/Platform Boundary Declaration` is the **only** place that states which layer owns which code; that table is what the Pass M audit checks against the build. This section records **repository module layout only** and MUST NOT restate the boundary — two descriptions of the same boundary means one of them is unaudited, and the unaudited one will be the one that lies.
+3. **Currency — state that this is a point-in-time convention.** Once implementation lands, the authoritative placement is the **build config and the actual repository**. Say so in the section, and tell downstream Location grounding to prefer build config and existing sibling files.
+
+**a. Documentation Structure**:
+- ⚠️ **不要写 "Copy from plan-template.md"**（T171）：该模板的 `## Project Structure` 下**只有**
+  `### Source Code (repository root)`，**没有** Documentation Structure 一节 ⇒ 照它抄会抄到一个
+  不存在的东西。本节的内容**按下面两行现列**，并从 `spec.md` / `contracts/` 的**实际**产物取
+- List all spec files
+- List contracts/ directory
+
+**b. Source Code Structure**:
+- Determine project type from Technical Context:
+  * Single project → "Option 1: Single project"
+  * Web application → "Option 2: Web application"
+  * Mobile + API → "Option 3: Mobile + API"
+- Remove unused options
+- Fill in real module/package names
+
+**c. Structure Decision**:
+- Document selected type and reasoning
+
+**d. Test Module Structure Design** ✨ NEW (generic lessons from real project experience):
+
+**Purpose**: Test locations decided here directly constrain task file paths in tasks.md.
+A test placed in a directory without build configuration can NEVER be executed by the build system.
+
+**Test Module Placement Decision** (choose one, document in Structure Decision):
+
+| Strategy | Layout | When to Use |
+|----------|--------|-------------|
+| **In-module tests** (DEFAULT) | `<module>/src/test/...` following the module's OWN build type | Small projects, few test types |
+| **Separated test modules** | `tests/<type>-test/` as independent build modules | Test types need independent CI execution, independent dependencies, or merged coverage reports |
+
+**Test Type Module Separation** (for separated strategy):
+- `tests/unit-test/` (or `core-test/`) — fast, mock-based, run on every commit
+- `tests/contract-test/` — API contract verification, run on every PR
+- `tests/integration-test/` — component integration using mocks, CI-friendly (<30s per suite)
+- `tests/e2e-test/` — real external systems, may require container environment, nightly/weekly runs
+
+**Layer ownership note**: which test LAYER each module hosts follows the "Typical module" conventions in `/specpro-test-plan` Layer Assignment Rules — the authoritative layer semantics. One module may host multiple layers (e.g. `tests/e2e-test/` hosts CE real-peer packages and the AE app package) and one layer may span modules (IT in `tests/integration-test/` and `tests/contract-test/`). This section decides LAYOUT MECHANICS only (in-module vs separated strategy, module registration, source-set correctness); it does not redefine layer semantics.
+
+**Parent Test Module Shared Configuration** (for separated strategy):
+- Central test framework setup, execution logging, and coverage tool configuration in the `tests/` parent build script (applied to all submodules)
+- Provide a merged coverage report task aggregating all submodules
+
+**⚠️ CRITICAL Rules (each from a real build failure)**:
+1. **Standard source directories per build type** — NEVER copy source-set conventions from sibling modules with a different build type:
+   * Single-platform build plugins use `src/test/...` style directories
+   * Multi-platform build plugins use per-target source sets (e.g., `src/jvmTest/`, `src/commonTest/`) that DO NOT exist in single-platform builds — reusing them causes silent `NO-SOURCE` (tests never run) or build errors
+   * Other ecosystems: Maven `src/test/java`, pytest `tests/test_*.py`, Go `*_test.go` alongside source, Rust top-level `tests/`, Jest `__tests__/` — always follow the chosen build system's own convention
+2. **Build module registration** — every new test module MUST be registered in the workspace/project manifest (settings file / workspace config / solution file), otherwise it is invisible to the build
+3. **No version re-declaration in submodules** — build plugin versions declared at the root MUST NOT be re-declared with a version number in submodules (causes classpath conflicts)
+4. **No mixed test framework adapters** — do not combine test adapters targeting different engine generations in one module (causes capability conflicts)
+5. **Task locations follow this decision** — test file paths generated later in tasks.md MUST resolve to a registered build module with the correct source directory; otherwise `/specpro-implement` will create tests that compile nowhere
+
+**Concrete Example: a multi-target project** (illustrates the rules above; principles apply to any build system):
+
+```text
+# Rule 1 illustration — source sets differ by build plugin type:
+
+core/                               # KMP plugin module → per-target source sets
+└── src/
+    ├── commonMain/kotlin/          # shared code
+    ├── commonTest/kotlin/          # shared tests      (KMP plugin ONLY)
+    └── jvmTest/kotlin/             # JVM-target tests  (KMP plugin ONLY)
+
+tests/integration-test/             # plain single-target JVM plugin module → standard source sets
+└── src/
+    ├── test/kotlin/                # ✅ CORRECT: executed by `gradle test`
+    └── jvmTest/kotlin/             # ❌ WRONG: copied from core/ convention
+                                     #    → "KotlinSourceSet 'jvmTest' not found" build error,
+                                     #    or silent NO-SOURCE (tests never run)
+```
+
+*Typical failure pattern*: a test placed at `src/jvmTest/kotlin/...` inside a
+plain JVM-plugin module is invisible to the build — it either triggers a
+"KotlinSourceSet not found" build error or silently reports `NO-SOURCE` with
+zero tests executed. The fix is to place it at `src/test/kotlin/...`, matching
+that module's build type.
+
+```text
+# Rules 2-4 illustration — separated test modules in a KMP project:
+
+# settings.gradle.kts (workspace manifest — Rule 2: register every test module):
+include(":core")                        // KMP plugin, per-target source sets
+include(":tests:core-test")             // plain JVM plugin
+include(":tests:contract-test")         // plain JVM plugin
+include(":tests:integration-test")      // plain JVM plugin
+include(":tests:e2e-test")              // plain JVM plugin
+
+# tests/build.gradle.kts (parent module — shared config: framework, logging, Jacoco;
+# plus a jacocoMergedReport task aggregating all submodules)
+
+# tests/integration-test/build.gradle.kts (Rule 3 + 4):
+plugins {
+    kotlin("jvm")                       // ✅ no version — root already declares it
+    // kotlin("jvm") version "1.9.23"   // ❌ "plugin already on the classpath" error
+}
+dependencies {
+    testImplementation(kotlin("test"))  // ✅ single engine
+    // + kotlin-test-junit AND kotlin-test-junit5  ❌ capability conflict error
+}
+```
+
+**Validation**: Both documentation and source code structure included; test module strategy documented and all future test paths will resolve to configured, executable locations
+
+#### **5.6 Generate Implementation Plan Section** 🅷 **→ `specs/plan-overview.md`**
+
+**Progress**: 📋 [5.6/8] Generating Implementation Plan...
+
+**a. Phase Overview**:
+- Define phases (typically 0-2 for initial plan)
+- For each phase in table:
+  * Phase number and name
+  * Goal
+  * Key Deliverables
+  * Estimate (weeks)
+  * Dependencies
+
+**b. Detailed Phase Breakdown** 🅷 **[Part II · Human-Read]** ⚠️ [NO CHECKBOXES — settled 2026-09-13]:
+
+> **This subsection replaced the old per-phase checkbox lists.** Two independent findings forced the change:
+>
+> 1. **A checkbox here has no possible owner.** Whatever it would show is either (a) already carried by `spec.md`'s `[plan:*]` field, or (b) a **downstream** fact (is the code written? is coverage met?) whose source of truth is a later artifact. Case (a) is a redundant re-render of a field; case (b) cannot be maintained from here at all — this stage does not read downstream artifacts, so the box freezes at whatever it said when written while downstream consumers act on a stale value. In one project 226 boxes sat unticked against FRs that were all `processed`, and the maintenance rule (which keyed off `[plan:*]`) had never once run on them.
+> 2. **The criteria were the wrong thing to track anyway.** Of the unticked leftovers in that project, most were not tasks but **acceptance criteria** (coverage thresholds, latency budgets, an audit) — and criteria had no judge.
+
+For each phase:
+
+* **Goal**: What this phase achieves
+
+* **Acceptance Criteria and Judges**: a table — **one row per criterion**:
+
+  | Criterion | Judge | State lives in |
+  |-----------|-------|----------------|
+  | [what must hold — a verifiable proposition] | [the command or role that decides it] | [the judge's own artifact] |
+
+  - **Every criterion MUST name its judge.** A criterion you cannot assign to a judge is **not yet a criterion** — it is a gap. Record it as one (`[plan]` issue) rather than leaving an unjudgeable line in the plan.
+  - **No checkboxes. No ✅/⚠️/❌. No "status" column.** The judge holds the state in its own artifact; this file MUST NOT carry acceptance state.
+  - A **human role is an acceptable judge** when the criterion is not mechanically decidable — what is *not* acceptable is leaving it blank. Do not manufacture a fake judge to avoid "TBD": if nobody can decide it yet, say so explicitly.
+  - Common judges: coverage acceptance → `/specpro-implement` §14; performance / integration → `/specpro-test-plan` → `/specpro-test-implement`; this plan's own steps → `/specpro-plan`.
+
+* **Key Activities**: Numbered list — an **activity description, not a task queue**.
+  - **No checkboxes.**
+  - **MUST NOT restate an acceptance criterion** ⚠️ [settled 2026-09-13]: the two subsections have different jobs — a **criterion** states a verifiable proposition ("coverage ≥90%"), an **activity** states an action ("write the protocol unit tests"). A line that could sit in either place means the split has collapsed: one of them is now a second copy that will drift, and neither has a single owner. The failure this rule prevents: an earlier revision required the *same six strings* in both subsections of a phase, so every generated plan carried each of them twice, verbatim.
+  - **Gating is by `lifecycle_cache`, not by anything ticked here**: an activity is stale when the FR state it serves is `create`/`update`; skip it when that FR is `processed`. Do **not** re-introduce a per-deliverable checklist to decide this — that is exactly the unmaintainable state described above.
+
+* **Estimate**: Weeks
+* **Dependencies**: Prerequisites
+* **Risks**: Potential issues
+* **Mitigation**: How to address
+
+**⚠️ FR-anchor rule for everything written in this subsection** (settled 2026-09-13): **anything phrased as "to be done" MUST carry an FR anchor, or live in a task queue** (`specs/tasks.md` / `test-tasks.md` / `fix-tasks.md`). An item with no FR anchor has no legitimate owner: no command will ever pick it up, yet it reads as pending. In one project three such deliverables (push notifications, iOS APNs, a security audit) sat in the plan with no FR behind them — unmatchable to any requirement and permanently unattachable. **When you cannot anchor an item, that is the signal to register it as an issue against the appropriate stage — not to write it here.**
+
+**Validation**: every phase has all subsections; **no checkbox syntax (`- [ ]` / `- [x]`) appears anywhere in this section**; every acceptance criterion has a non-empty judge; every "to be done" item traces to an FR or a task queue.
+
+**c. Dependencies and Critical Path**:
+- Dependency graph or table
+- Identify critical path
+- Specify duration in weeks
+- Identify parallel opportunities
+
+**d. Risk Management**:
+- Tables: Technical Risks, Project Risks, Quality Risks
+- For each: Description, Probability, Impact, Mitigation
+
+**e. Milestones**:
+- Table with: Name, Target, Deliverables, Acceptance Criteria
+
+**Validation**: every subsection this step defines is present and non-empty. ⚠️ The authoritative subsection list is the **template's `## Implementation Plan`** — not a count written here (see §5.8 Check 1 for why).
+
+#### **5.7 Generate Complexity Tracking Section** (CONDITIONAL) 🅷 **→ `specs/plan-overview.md`**
+
+**Progress**: 📋 [5.7/8] Generating Complexity Tracking (if violations or justified decisions)...
+
+**Scope — wider than "violations"** (settled 2026-09-13): this section records **design complexity that needs justifying**, which is two cases, not one:
+1. **A constitutional principle violation** that must be justified.
+2. **A decision that rejected a simpler alternative** — the question it answers is the same one: *why wasn't the simpler route enough?* In one project this section carried a TLS-wiring route decision of exactly this kind, placed here deliberately by the issue that dispatched it — so the practice was already wider than the rule, and the rule was corrected to match rather than the other way round.
+
+- Generate when **either** case applies — not only on ❌ FAIL.
+- For each entry:
+  * **Violation / Decision**: which principle, or what the decision was
+  * **Why Needed**: business/technical justification
+  * **Simpler Alternative Rejected Because**: what was rejected and why it was insufficient
+- **If neither case applies**: omit the section, or write `Not applicable`.
+- **Recording a technology or architecture change** (e.g. "swap the network library"): this section is the place — see **`**Standing rule 2 — change propagation**`** (this file, where the rule is actually stated). ⚠️ This pointer used to name *"§5.8's 'Change propagation' note"* — **§5.8 is Chapter Validation and carries no such note** (`T229` ②): the pointer named a section that does not hold the rule, so a reader following it lands somewhere that cannot answer the question. The entry is the record that the change happened; the FR state update is what makes `tasks` act on it.
+
+**Validation**: every entry names either a violated principle or an explicitly rejected alternative; no entry is a bare description with no "why not the simpler way".
+
+#### **5.8 Chapter Validation** 🅼 **→ both files**
+
+**Progress**: 📋 [5.8/8] Validating plan.md completeness...
+
+After generating plan.md, validate — **against the template, not against a list written here**:
+
+> ⚠️ **Why the checklist below is not an enumeration** (settled 2026-09-13): a hand-written list of sections goes stale the moment the template gains or loses one, and it fails **silently** — the validator keeps passing while a whole section goes unchecked. In one project `## Quality Targets`, the section consumed by more downstream commands than any other, was missing from this checklist from the day it was introduced: nothing ever validated it, and unrelated content accumulated there unnoticed for months. **The template's top-level section list is the authority — read the template and iterate that.**
+
+**Check 1 — section presence (template-driven, BOTH files)**: iterate each template's top-level sections and check the corresponding **file**:
+- `.specpro/templates/plan-template.md` → `specs/plan.md`
+- `.specpro/templates/plan-overview-template.md` → `specs/plan-overview.md`
+
+Each section from each template MUST be present in its file with all of *its* defined subsections present and non-empty. **Both checks are required** — checking only one file leaves the other half unvalidated, which is the same silent-pass shape as the missing-section gap described above. Conditional sections are checked for the right condition, not for presence. **Do not iterate a list from memory.**
+
+**Check 1b — the split is structural, verify it held** ⚠️:
+- `specs/plan.md` MUST NOT contain any `##` section belonging to `plan-overview-template.md` (Summary / System Overview / Constitution Check / Implementation Plan / Documentation Layout / Complexity Tracking), and vice versa.
+- `specs/plan.md` MUST NOT reference any `plan-overview.md` section name (file-path references are fine).
+- If either fails, the split leaked — the file boundary is the enforcement point for "implement never reads the human half", and a leaked section silently returns to being read.
+
+**Check 2 — per-section content rules**: each generation step §5.1–§5.7 states its own `**Validation**`; run those. In particular:
+- Technical Context: all 9 fields filled (may contain NEEDS CLARIFICATION)
+- Constitution Check: all applicable principles evaluated, each with a stated basis
+- Implementation Plan: every acceptance criterion names a judge; **no checkbox syntax anywhere in the section**
+- Complexity Tracking: present only when there is a violation or a rejected-simpler-alternative decision
+- **Standing rule 0 — `*Purpose · Consumers*`**: **every `##` and `###` section of BOTH files opens
+  with that one-line note**, naming the consumers concretely (§5 "Standing rule 0").
+  ⚠️ **This check is new, and it closes a rule that had no reader** (T171 / audit finding: 「`Purpose ·
+  Consumers` 全文档仅此 1 处，§5.8 的三项检查都不读它」). A MUST with no check is a declaration
+  (宪法 I) — the rule was written, the generator was told to obey it, and **nothing ever looked**.
+  ⚠️ Cover **sub-sections too**: `§4.i-1..i-4` / `§4.j-1..j-3` extract *per subsection*, and a
+  top-level-only check is blind to exactly the ones they read.
+
+**Check 3 — cross-section consistency** ⚠️ [structurally invisible to per-section validation]:
+- Sections MUST NOT contradict one another. Specifically: the layer division in `## System Overview` (runtime component stack) and in `### Layered Architecture` (source-set ownership) MUST NOT be readable as two competing models — each MUST carry its view-semantics line; any section stating a count or scope MUST agree with the section that enumerates it.
+- **A contradiction between two sections passes every per-section check by construction** — each section is internally coherent. That is exactly why this check exists separately, and why it cannot be delegated to the per-section validations.
+
+**If validation fails**:
+- Re-generate missing chapter
+- Or mark "INCOMPLETE" and continue with warning
+
+---
+
+### **Phase 0: Research**
+
+**Progress**: 📋 [6/8] Executing Phase 0: Research...
+
+#### **Phase 0: Research**
+
+**0.1 Extract unknowns from Technical Context**:
+- For each NEEDS CLARIFICATION → research task
+- For each dependency → best practices task
+- For each integration → patterns task
+
+**0.2 Generate and dispatch research agents**:
+```text
+For each unknown:
+  Task: "Research {unknown} for {feature context}"
+For each technology:
+  Task: "Find best practices for {tech} in {domain}"
+```
+
+**0.3 Consolidate findings** in `research.md`:
+- Decision: What was chosen
+- Rationale: Why chosen
+- Alternatives considered: What else evaluated
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+**Progress**: ✓ Phase 0 complete: research.md generated
+
+---
+
+### **Step 6.5: Backfill everything that depends on research.md** ✨ NEW (CRITICAL FIX)
+
+**Purpose**: After Phase 0 research completes, update plan.md Technical Context with decisions
+
+**Progress**: 📋 [6.5/8] Updating Technical Context from research.md...
+
+**Why This Step Is Critical**:
+- The whole §5.x block runs **before** Phase 0 Research
+- At that time, research.md doesn't exist yet (in initial mode)
+- Technical Context lives in **plan.md**, not research.md — plan.md is the single source of truth for the technology stack
+- If Technical Context isn't updated, agents get empty/incorrect tech stack
+
+**⚠️ Backfill ALL research-dependent sections, not just Technical Context** (settled 2026-09-13):
+
+> This step was originally scoped to Technical Context alone — and that narrow scoping was the defect. The root cause ("this section's input doesn't exist yet when the section is written") is a **class**, not an instance, so patching it section-by-section guarantees the next member of the class is missed. Two were: `§5.1 Summary` paragraph 2 is specified as coming "from research.md after Phase 0", and `§5.4c Architecture Patterns` requires each pattern to carry a `**See**: research.md section` anchor. Neither had a backfill step.
+
+**Backfill list** (keep this list in sync — a new section that takes research.md as input MUST be added here when it is introduced; that obligation is part of this step):
+
+| Section | What to backfill |
+|---------|------------------|
+| **Technical Context** (§5.2) | all 9 fields — technology choices, versions, best practices |
+| **Summary** (§5.1) | paragraph 2 (technical approach) — it is specified as sourced from research.md, which does not exist when §5.1 first runs |
+| **Architecture Patterns** (§5.4c) | each pattern's `**See**: research.md section` anchor — the anchor cannot be written before the section exists |
+
+Then continue with 6.5.b onward for the Technical Context field mapping.
+
+**6.5.a Read research.md**:
+```markdown
+Read specs/research.md
+Extract all decisions:
+- Technology choices (Language, Framework, Storage, etc.)
+- Versions selected
+- Best practices identified
+```
+
+**6.5.b Map research decisions to Technical Context fields**:
+```markdown
+For each decision in research.md:
+  → Update corresponding field in plan.md Technical Context
+
+Example mappings:
+- "Decision: [Language] [version]"
+  → **Language/Version**: [Language] [version]
+
+- "Decision: [framework] [version] for the plugin layer"
+  → **Primary Dependencies**: [framework] [version], [Language] [version]
+
+- "Decision: [database] with the [driver] driver"
+  → **Storage**: [database] [version] with the [driver] driver
+
+- "Decision: [UI toolkit] [version]"
+  → **Primary Dependencies**: Add [UI toolkit] [version]
+```
+
+**6.5.c Update plan.md Technical Context**:
+```markdown
+For each field in Technical Context:
+1. Read plan.md Technical Context field
+2. If value is "NEEDS CLARIFICATION":
+   - Find corresponding decision in research.md
+   - Update field with decision text
+3. If value already filled:
+   - Compare with research.md decision
+   - Update if different (research is authoritative)
+4. Mark field as updated
+```
+
+**6.5.d Validation**:
+```markdown
+After update:
+1. Count "NEEDS CLARIFICATION" remaining in Technical Context
+2. If > 0:
+   - WARNING: "X Technical Context fields still unresolved"
+   - List unresolved fields
+   - Check if corresponding decisions exist in research.md
+3. If 0:
+   - ✓ SUCCESS: "All Technical Context fields resolved"
+```
+
+**6.5.e Report update summary**:
+```markdown
+## Technical Context Update Summary
+
+**Fields Updated**: N
+- Language/Version: NEEDS CLARIFICATION → [Language] [version]
+- Primary Dependencies: NEEDS CLARIFICATION → [framework] [version], [UI toolkit] [version]
+- Storage: NEEDS CLARIFICATION → [database] [version] with the [driver] driver
+
+**Fields Unresolved**: M
+- Testing: NEEDS CLARIFICATION (no decision found in research.md)
+- Performance Goals: NEEDS CLARIFICATION (needs clarification)
+
+✓ Technical Context ready for Phase 1 Design
+```
+
+**Progress**: ✓ Technical Context updated with N research decisions
+
+---
+
+### **Step 6.6: Phase 0 Completion Checkpoint** ✨ NEW
+
+**Purpose**: Verify Phase 0 research quality before proceeding to Phase 1
+
+**Progress**: 📋 [6.6/8] Verifying Phase 0 completion...
+
+**6.6.a research.md completeness check**:
+```markdown
+Verify research.md contains:
+- [ ] All NEEDS CLARIFICATION items from Technical Context resolved
+- [ ] Technology stack decisions documented
+- [ ] Version numbers specified
+- [ ] Rationale for each decision
+- [ ] Alternatives considered
+- [ ] Trade-offs documented
+
+If any missing:
+  WARNING: "research.md incomplete, missing: [list missing items]"
+  Recommendation: "Review research.md and ensure all decisions are documented"
+  Choice: "Continue anyway (yes/no)"
+```
+
+**6.6.b Technical Context consistency check**:
+```markdown
+Verify consistency between research.md and plan.md Technical Context:
+- For each decision in research.md:
+  - Corresponding Technical Context field updated?
+  - Values match (or at least consistent)?
+
+If inconsistency found:
+  WARNING: "Inconsistency detected: research.md says 'X', Technical Context says 'Y'"
+  Recommendation: "Update Technical Context to match research.md"
+```
+
+**6.6.c Gate check**:
+```markdown
+Preliminary gate evaluation (before Phase 1):
+- Check if any Constitution violations introduced by technology choices
+- Early detection of issues
+```
+
+**Checkpoint Result**:
+```markdown
+✓ Phase 0 completion verified
+- research.md: Complete
+- Technical Context: Updated and consistent
+- Constitution: No new violations
+
+Proceeding to Phase 1...
+```
+
+**Progress**: ✓ Phase 0 checkpoint passed
+
+---
+
+### **Phase 1: Design & Contracts** ✨ OPTIMIZED
+
+**Prerequisites**: research.md complete, Technical Context updated
+
+**Progress**: 📐 [7/8] Phase 1: Generating design artifacts...
+
+**1.0 Extract entities** → `data-model.md` ✨ ENHANCED (Incremental Update):
+
+**a. Detect operation mode**:
+```markdown
+⚠️ UPDATE_MODE is DERIVED, not passed in (settled 2026-09-13): it was previously read in five places and
+assigned nowhere, so which path ran was left to the executor's guess — and the initial path regenerates
+`data-model.md` from scratch. Derive it from the shared rerun rule at the top of this command:
+
+    [ -s specs/data-model.md ] → UPDATE_MODE = true  (incremental: evolve the existing model)
+    absent / empty            → UPDATE_MODE = false (initial: generate from scratch)
+
+When it already exists, the SAME confirmation as the shared rule applies: the initial path runs on an
+existing artifact only on explicit request, re-confirmed.
+
+- IF UPDATE_MODE = false (initial specification):
+  → Generate complete data-model.md from scratch
+  → Proceed to Step 1.b
+
+- IF UPDATE_MODE = true (evolution iteration):
+  → Check which User Stories are modified
+  → Apply incremental update strategy
+  → Proceed to Step 1.c
+```
+
+**b. Generate complete data-model.md** (INITIAL MODE):
+```markdown
+Extract all entities from spec.md:
+- Entity name, fields, relationships
+- Validation rules from requirements
+- State transitions if applicable
+- Map entities to User Stories
+
+**From Acceptance Scenarios - Edge Cases** 🆕:
+   - Identify boundary conditions → validation rules and constraints
+   - Map each Edge Case to data model fields:
+     * "Account locked after 5 attempts"
+       → User.failed_attempts (int, max_value=5)
+       → User.locked_until (timestamp, nullable)
+       → User.status (enum: active, locked)
+     * "Token expires in 30 days"
+       → Session.created_at (timestamp)
+       → Session.expires_at (timestamp, +30 days)
+     * "Connection timeout within 3 seconds"
+       → Connection.timeout (int, 3000ms)
+   - Document state transitions if applicable
+
+**From Acceptance Scenarios - Error Scenarios** 🆕:
+   - Identify error conditions → status fields and error handling
+   - Map each Error Scenario to data model needs:
+     * "Network disconnect detected within 10 seconds"
+       → ConnectionState.last_heartbeat (timestamp)
+       → ConnectionMonitor.timeout (int, 10000ms)
+     * "Plugin initialization fails gracefully"
+       → PluginState enum: CREATED, RESOLVED, STARTED, FAILED
+       → Plugin.error_message (string, nullable)
+     * "Invalid server address"
+       → ConnectionResult.error_code (enum)
+       → ConnectionResult.user_message (string)
+
+**From Acceptance Scenarios - Permission Scenarios** 🆕:
+   - Identify access control needs → ownership and role fields
+   - Map each Permission Scenario to data model:
+     * "User can only access own data"
+       → Resource.user_id (foreign key, indexed)
+       → Resource.is_public (boolean, default=false)
+     * "Admin can access all data"
+       → User.role (enum: user, admin, super_admin)
+     * "Password-protected server"
+       → Connection.requires_auth (boolean)
+       → Connection.auth_password (encrypted, nullable)
+
+- Create file: specs/data-model.md
+
+**Progress**: 📐 [1/4] data-model.md generated (initial)...
+```
+
+**c. Incremental entity updates** ✨ NEW (EVOLUTION MODE):
+```markdown
+**Purpose**: Update only modified User Story entities, preserve unchanged ones
+
+**1. Identify modified User Stories**:
+- Read lifecycle_cache
+- Filter User Stories where planStatus = "update"
+- Extract associated entities
+
+**2. Smart merge strategy**:
+For each entity in data-model.md:
+- **Preserve**: Entities from unchanged User Stories (planStatus = "processed")
+- **Update**: Entities from modified User Stories (planStatus = "update")
+  * Add new fields from new FRs
+  * Update validation rules if changed
+  * Add new relationships
+  * Mark as [Updated] in change log
+- **Add**: New entities from new User Stories (planStatus = "create")
+  * Mark as [New] in change log
+- **Remove**: Entities from deprecated User Stories (planStatus = "deprecated")
+  * Mark as [Removed] in change log
+
+**3. Change tracking**:
+Add section to data-model.md:
+```markdown
+## Entity Changes (v{NEW_VERSION})
+
+### New Entities
+- [New] XxxSubEncoding (from FR-xxxB)
+  → Added for sub-encoding format support
+
+### Updated Entities
+- [Updated] EncodingType (from FR-xxxA, FR-xxxB)
+  → Added JPEG, PNG, ZLIB sub-encodings
+
+### Removed Entities
+- [Removed] LegacyAuth (deprecated in v0.3)
+  → Replaced by OAuth2
+```
+
+**4. Preserve completed entity status**:
+- Keep [x] markers for implemented entities
+- Mark new/updated entities as [ ]
+- Update entity relationships
+
+**5. Validation**:
+- Validate entity relationships after updates
+- Ensure no orphaned references
+- Check for duplicate fields
+
+**Progress**: 📐 [1/4] data-model.md updated (incremental)...
+```
+
+**Benefits**:
+- ✅ Avoid full overwrite of data-model.md
+- ✅ Preserve completed status of implemented entities
+- ✅ Update only changed sections
+- ✅ Clear change tracking
+
+**1.5 Generate Database Schema Files** ✨ NEW (Database Evolution):
+
+**Purpose**: Auto-generate database schema files (.sq) and initial migration from data-model.md entities
+
+**Progress**: 📐 [1.25/4] Database schema files generated...
+
+**Why This Step Is Critical**:
+- Converts entity definitions into executable SQL schema
+- Provides version-controlled database schema (V1__InitialSchema.sq)
+- Enables Database Evolution with migration files
+- Follows the project's chosen database framework's schema conventions
+
+**1.5.a Detect Database Requirement**:
+```markdown
+Check Technical Context → Storage field:
+- IF Storage contains "SQLDelight" OR "SQLite" OR "PostgreSQL" OR "MySQL":
+  → Database required, proceed to Step 1.5.b
+- ELSE:
+  → Skip this step (no database needed)
+  → Proceed to Step 2.0
+```
+
+**1.5.b Generate .sq Schema Files** (INITIAL MODE):
+```markdown
+**Purpose**: Generate the schema files (.sq) from data-model.md entities using the project's database framework
+
+**For each entity in data-model.md**:
+1. **Extract entity metadata**:
+   - Entity name (e.g., "Plugin", "Connection", "Session")
+   - Fields with types (e.g., "id: TEXT", "created_at: INTEGER")
+   - Primary key (usually "id" field)
+   - Foreign keys (relationships between entities)
+   - Indexes (for query optimization)
+   - Constraints (UNIQUE, NOT NULL, DEFAULT)
+
+2. **Generate .sq file content**:
+   - File path: `shared/commonMain/sqldelight/com/example/db/[Entity].sq`
+   - Content format:
+     ```sql
+     CREATE TABLE [EntityName] (
+       [FieldName] [DataType]([Size]) [Constraints],
+       ...
+       PRIMARY KEY ([PrimaryKeyField]),
+       FOREIGN KEY ([ForeignKeyField]) REFERENCES [RelatedEntity]([RelatedField])
+     );
+
+     CREATE INDEX idx_[EntityName]_[FieldName] ON [EntityName]([FieldName]);
+
+     -- Sample queries
+     selectAll:
+     SELECT * FROM [EntityName];
+
+     selectById:
+     SELECT * FROM [EntityName] WHERE id = ?;
+
+     insert:
+     INSERT INTO [EntityName] VALUES (?, ?, ...);
+
+     update:
+     UPDATE [EntityName] SET [field1] = ?, [field2] = ? WHERE id = ?;
+
+     delete:
+     DELETE FROM [EntityName] WHERE id = ?;
+     ```
+
+3. **Create directory structure** (if not exists):
+   - `shared/commonMain/sqldelight/com/example/db/`
+
+4. **Write .sq files**:
+   - Create file: `[EntityName].sq`
+   - Add table definition
+   - Add indexes (for frequently queried fields)
+   - Add common queries (SELECT, INSERT, UPDATE, DELETE)
+
+5. **Validate generated schemas**:
+   - Check all entities have .sq files
+   - Verify foreign key relationships are valid
+   - Verify indexes are created for indexed fields
+   - Check for SQL syntax errors
+```
+
+**1.5.c Generate Initial Migration V1__InitialSchema.sq**:
+```markdown
+**Purpose**: Generate versioned initial migration file
+
+**Migration file**:
+- File path: `shared/commonMain/sqldelight/com/example/db/migrations/V1__InitialSchema.sq`
+- Content format:
+  ```sql
+  -- V1__InitialSchema
+  -- Generated: [DATE]
+  -- Purpose: Initial database schema for [FEATURE_NAME]
+
+  -- Create all tables
+  CREATE TABLE plugin (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    version TEXT NOT NULL,
+    enabled INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE vnc_connection (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    host TEXT NOT NULL,
+    port INTEGER NOT NULL DEFAULT 5900,
+    password TEXT,
+    created_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE session (
+    id TEXT PRIMARY KEY,
+    connection_id TEXT NOT NULL,
+    started_at INTEGER NOT NULL,
+    ended_at INTEGER,
+    status TEXT NOT NULL,
+    FOREIGN KEY (connection_id) REFERENCES vnc_connection(id) ON DELETE CASCADE
+  );
+
+  -- Create indexes
+  CREATE INDEX idx_plugin_enabled ON plugin(enabled);
+  CREATE INDEX idx_session_connection ON session(connection_id);
+  CREATE INDEX idx_session_status ON session(status);
+
+  -- Migration complete
+  ```
+
+**Versioning convention**:
+- V1__InitialSchema.sq (first version)
+- V2__AddPasswordField.sq (schema evolution)
+- V3__RenameStatusColumn.sq (schema evolution)
+  See Step 1.5.e for schema evolution
+```
+
+**1.5.d Schema Evolution Detection** (EVOLUTION MODE):
+```markdown
+**Purpose**: Detect entity changes and generate schema evolution migrations
+
+**Trigger**: UPDATE_MODE = true AND data-model.md has entity changes
+
+**For each changed entity** (from Step 1.c "Entity Changes"):
+1. **Compare old vs new schema**:
+   - Old schema: Existing .sq file content
+   - New schema: New entity definition from updated data-model.md
+
+2. **Detect change types**:
+   - **NEW field added**: Generate ALTER TABLE ADD COLUMN migration
+   - **REMOVED field**: Generate ALTER TABLE DROP COLUMN migration
+   - **RENAMED field**: Generate ALTER TABLE RENAME COLUMN migration
+   - **TYPE changed**: Generate ALTER TABLE ALTER COLUMN migration
+   - **NEW table added**: Generate CREATE TABLE migration
+   - **DROPPED table**: Generate DROP TABLE migration
+
+3. **Generate schema evolution migration file**:
+   - File: `V{N}__[ChangeDescription].sq`
+   - Example: `V2__AddPluginAuthorField.sq`
+   - Example: `V3__RenameStatusToState.sq`
+   - Content format:
+     ```sql
+     -- V{N}__{ChangeDescription}
+     -- Generated: [DATE]
+     -- Purpose: {Explanation of change}
+
+     ALTER TABLE plugin ADD COLUMN author TEXT;
+     -- or
+     ALTER TABLE session RENAME COLUMN status TO state;
+     -- or
+     CREATE INDEX idx_plugin_author ON plugin(author);
+     ```
+
+4. **Update .sq files**:
+   - Overwrite existing .sq files with new schema
+   - Preserve migration files (V1, V2, V3...)
+```
+
+**1.5.e Database Evolution vs Data Migration - Terminology**:
+```markdown
+**IMPORTANT CLARIFICATION**:
+
+**Database Evolution** (or **Schema Evolution**):
+- Definition: Modifying database schema within the SAME database system
+- Examples:
+  * Adding a new field to existing table (SQL: ALTER TABLE ADD COLUMN)
+  * Renaming a column (SQL: ALTER TABLE RENAME COLUMN)
+  * Changing data type (SQL: ALTER TABLE ALTER COLUMN)
+  * Adding new table (SQL: CREATE TABLE)
+  * Adding index (SQL: CREATE INDEX)
+- Migration files: V1__InitialSchema.sq, V2__AddField.sq, V3__RenameColumn.sq
+- Framework: SQLDelight, Flyway, Liquibase
+- Purpose: Evolve database schema incrementally as application grows
+
+**Data Migration** (or **System Migration**):
+- Definition: Moving data from ONE database system to ANOTHER database system
+- Examples:
+  * Oracle → PostgreSQL
+  * MySQL → SQLite
+  * SQL Server → MongoDB
+  * On-premises → Cloud database
+- Tools: ETL tools, custom export/import scripts
+- Purpose: Change database technology stack
+
+**DO NOT confuse these terms**:
+- ❌ "Database migration" for adding a field → Use "Schema evolution" instead
+- ✅ "Database migration" for Oracle → PostgreSQL → Correct usage
+
+**Why terminology matters**:
+- "Schema evolution" clearly indicates incremental changes within same system
+- "Data migration" clearly indicates system-wide technology change
+- Different concepts require different tools and approaches
+```
+
+**1.5.f Generate Database Setup Documentation**:
+```markdown
+**Purpose**: Add database setup section to quickstart.md (see Step 4.3)
+
+**Database Setup section content**:
+- Prerequisites (database framework version, database driver)
+- Schema files location (`shared/commonMain/sqldelight/`)
+- Migration files location (`shared/commonMain/sqldelight/com/example/db/migrations/`)
+- Initial database setup commands (if applicable)
+- Schema evolution workflow (how to add V2, V3 migrations)
+- Verification steps (how to verify schema is correct)
+```
+
+**Progress**: 📐 [1.25/4] Database schema files generated...
+
+**Example Output**:
+```markdown
+## Database Schema Files Generated
+
+**.sq Schema Files**: N files
+- shared/commonMain/sqldelight/com/example/db/Plugin.sq
+- shared/commonMain/sqldelight/com/example/db/Connection.sq
+- shared/commonMain/sqldelight/com/example/db/Session.sq
+
+**Migration Files**: 1 file
+- shared/commonMain/sqldelight/com/example/db/migrations/V1__InitialSchema.sq
+
+**Schema Evolution Files**: M files (if UPDATE_MODE = true)
+- shared/commonMain/sqldelight/com/example/db/migrations/V2__AddPluginAuthorField.sq
+- shared/commonMain/sqldelight/com/example/db/migrations/V3__RenameStatusToState.sq
+
+**Database Setup Section**: Added to quickstart.md (Step 4.3)
+```
+
+**1.5.g Update Technical Context**:
+```markdown
+Add to Technical Context → Storage:
+- **Schema Files**: Path to .sq files
+- **Migration Framework**: [the project's database framework] (or other)
+- **Initial Schema**: V1__InitialSchema.sq
+- **Schema Evolution**: V2, V3... migration files location
+```
+
+**2.0 Pre-generation Contract Coverage Check** ✨ NEW (OPTIMIZATION):
+
+**Purpose**: Generate ONLY missing contracts, avoid regeneration
+
+**a. Scan existing contracts/**:
+```markdown
+Scan specs/contracts/ directory:
+- List all existing .md files
+- Parse to identify which User Stories they cover
+```
+
+**b. Calculate current coverage** ✨ ENHANCED (Modified User Story detection):
+```markdown
+For each User Story in spec.md:
+- Check if dedicated contract exists in specs/contracts/
+- **NEW**: Check User Story's planStatus from lifecycle_cache
+  * planStatus = "processed" → Contract exists, check if needs update
+  * planStatus = "update" → **Contract needs regeneration** ⚠️
+  * planStatus = "create" → Contract missing, needs generation
+  * planStatus = "deprecated" → Skip (User Story deprecated)
+- Categorize by priority:
+  * P1 User Stories: Need 100% coverage
+  * P2 User Stories: Need 70% coverage
+  * P3 User Stories: Need 30% coverage
+
+Current coverage:
+- P1: X/Y contracts (Z%)
+- P2: A/B contracts (C%)
+- P3: D/E contracts (F%)
+
+**NEW**: Modified Items (need contract regeneration):
+- US2: remote-viewing.md (planStatus=update, 5 new FRs added)
+- US3: multi-view-grid.md (planStatus=update, performance requirements updated)
+
+**c. Source-reference staleness** ⚠️ [the second, independent trigger]:
+
+A contract is written against *facts that come from somewhere*. When those somewhere's change, the contract silently goes stale — its User Story can be untouched while a fact it asserts has moved. Regenerating by User Story alone therefore misses exactly the drift that matters most: a contract still stating a value its source no longer says.
+
+Detect per **contract section**, not per contract file: a contract typically anchors different sections to different sources, and only the affected sections are stale.
+
+```markdown
+For each contract under specs/contracts/:
+- Read its source attributions (the per-fact source layer + version markers)
+- Resolve each attribution to its source artifact:
+  * L1 / spec-sourced fact   → the cited FR (or spec section)
+  * L2 implementation-sourced fact → the cited implementation and version
+  * L3 capture-sourced fact  → the cited capture record
+- Flag the SECTION when any of these hold:
+  * the cited FR's planStatus is create/update (its content moved) → stale
+  * the cited implementation's version no longer matches the attribution → stale
+  * an asserted fact carries no attribution at all → unverifiable, not merely stale
+- Report stale sections alongside the User-Story-driven regeneration list; both feed the same
+  regeneration pass, and non-stale sections are preserved verbatim
+```
+
+An unattributed asserted fact is the worse case: it cannot go stale because it was never tied to anything — it can only be wrong. Report it as a finding, not as a regeneration item.
+```
+
+**c. Identify missing AND modified contracts** ✨ ENHANCED:
+```markdown
+Missing P1 Contracts (MUST generate):
+- US1: plugin-lifecycle.md (planStatus=create, new User Story)
+- US2: connection-manager.md (planStatus=create, new User Story)
+
+Modified P1 Contracts (MUST regenerate):
+- US3: multi-view-grid.md (planStatus=update, 4 new FRs added)
+  → Existing contract exists but needs update for new FRs
+
+Missing P2 Contracts (SHOULD generate):
+- US6: authentication-security.md (planStatus=create)
+
+Missing P3 Contracts (MAY generate):
+- US4: remote-control-input.md (planStatus=create)
+
+**Summary**:
+- Missing: 4 contracts (need initial generation)
+- Modified: 1 contract (needs regeneration) ⚠️
+- Total to generate: 5 contracts
+```
+
+**d. Report and confirm** ✨ ENHANCED:
+```markdown
+## Contract Pre-Generation Coverage Report
+
+**Current Coverage**:
+- P1: 67% (2/3) - 1 missing, 1 modified
+- P2: 0% (0/1) - 1 missing
+- P3: 0% (0/3) - 1 missing
+
+**Contracts to Generate**:
+
+### Missing Contracts (Initial Generation)
+- [P1] US1: plugin-lifecycle.md (MUST)
+- [P1] US2: connection-manager.md (MUST)
+- [P2] US6: authentication-security.md (SHOULD)
+- [P3] US4: remote-control-input.md (OPTIONAL)
+
+### Modified Contracts (Regeneration Required) ⚠️
+- [P1] US3: multi-view-grid.md
+  → Reason: 4 new FRs added (FR-xxxA~FR-xxxD)
+  → Impact: New APIs and performance requirements
+  → Action: Regenerate with new content
+
+**Action Plan**:
+1. Generate missing P1 contracts (required)
+2. Regenerate modified P1 contracts (required) ⚠️ NEW
+3. Generate missing P2 contracts (recommended)
+4. Generate P3 contracts (optional, may skip)
+
+Generate missing + modified P1 + P2 contracts now? (yes/no)
+```
+
+**Progress**: 📐 [2/4] Contract pre-validation complete...
+
+**2.1 Generate ONLY Missing AND Modified Contracts** ✨ ENHANCED:
+
+**a. Foundational Contracts** (shared infrastructure):
+```markdown
+Generate if NOT exists:
+- plugin-api.md
+- ui-components.md
+- wire-protocol.md
+
+Skip if already exists (preserve existing contracts)
+```
+
+**b. Domain-Specific Contracts** (PER USER STORY) ✨ ENHANCED:
+```markdown
+Generate contracts identified in Step 2.0.c:
+
+**Category 1: Missing Contracts** (Initial Generation)
+For each missing contract (planStatus = "create"):
+- Extract API surfaces from Functional Requirements
+- Map acceptance scenarios to contract methods
+- **Extract performance requirements from quantified FRs**
+- Define validation rules and edge cases
+- Create file: specs/contracts/[user-story-name].md
+
+**Category 2: Modified Contracts** (Regeneration) ⚠️ NEW
+For each modified contract (planStatus = "update"):
+- **Backup existing contract**: cp old.md old.md.bak
+- **Smart merge strategy**:
+  * Preserve: Existing structure, non-obsolete APIs
+  * Update: Add new APIs from new FRs
+  * Update: Add new performance requirements
+  * Remove: Obsolete APIs (if FR deprecated)
+- **Regenerate**: Create updated contract with merged content
+- **Validate**: Ensure all new FRs are covered
+- Overwrite: specs/contracts/[user-story-name].md
+- Remove backup: rm old.md.bak (if successful)
+
+**Skip**: Unchanged contracts (planStatus = "processed")
+```
+
+**c. Cross-Cutting Contracts** (shared concerns):
+```markdown
+Generate for features used by multiple User Stories:
+- event-bus.md (plugins)
+- memory-management.md (viewing, grid)
+```
+
+**d. Contract Content Requirements**:
+Each contract MUST include:
+- **API Signatures**: Method/function signatures with types
+- **Return Types**: Explicit return types and error conditions
+- **Performance Requirements** (from spec.md quantified FRs):
+  * Extract: "within 200ms", "<100ms", "30-60 FPS"
+  * Encode as: "MUST complete within X ms" or "MUST maintain Y FPS"
+
+**Fact-source attribution** 🌐 [MANDATORY for every asserted fact]:
+
+A contract item is one of two kinds, and the contract MUST make the difference visible:
+
+| Kind | Examples | Attribution |
+|------|----------|-------------|
+| **Design choice** — the contract's own decision | API signatures; decomposition into methods; naming; which codes this implementation advertises; error-message wording | NOT required — the decision is legible as the contract's own |
+| **Asserted fact** — a claim about how the world is | protocol type codes; field widths; control-byte bit allocation; wire order; version-dependent behaviour; what a peer requires or tolerates; "is/is not supported"; "compatible with X" | **REQUIRED** — a reader must be able to check it without trusting the author |
+
+The distinction matters because an unattributed assertion is indistinguishable from a guess. A reader cannot tell whether a value was read from a source or recalled — and a wrong value, once in a contract, is copied downstream as though authoritative.
+
+**Where attribution lives — inline, never in a collected section** ⚠️:
+
+An attribution MUST sit **immediately above the fact (or fact block) it covers**, in the same section. A collected "sources" table at the end of the file is **not acceptable**: it separates each fact from its source, and that distance is exactly where drift happens — editing one of the two no longer forces addressing the other, so a stale pairing survives review. Inline placement makes the fact/source relation visible at the point of reading and forces both to be touched together.
+
+**Format**:
+
+```markdown
+> Source: <L1 standard §<section> | L2 <implementation> <version> [<file/section>] | L3 <capture: peer + version>>
+```
+
+- **Area of effect**: the marker covers the block that immediately follows it, up to the next marker or section heading — one fact list, one table, one code block. A second marker is required when the source changes.
+- **No marker = no attribution.** A fact block carrying no marker is unattributed by definition — that is the N1 finding, not a formatting preference.
+- A bare protocol name does not satisfy the marker (see the non-satisfying list below): the marker must reach a section or a versioned implementation.
+- Where the base standard does not define the detail (sub-encoding layouts, packing rules, continuation chains), the marker MUST point at the authoritative implementation — a standard citation for something the standard omits is itself a finding.
+
+**Worked example** (the shape generated contracts MUST follow — a table of values, preceded by its source):
+
+```markdown
+### Encoding Types
+
+> Source: L2 <reference implementation> <version> (`src/…/<file>.c`)
+
+| Type | Meaning |
+|------|---------|
+| `0` | Raw |
+| `1` | Solid |
+| `2–127` | Palette-coded (`numColors = type + 2`) |
+```
+
+Contract prose, reasoning and design decisions need no marker — only facts do.
+
+**Attribution content** — record the source layer and version.
+
+The three-layer model is **domain-agnostic** — it is not specific to one protocol. Any domain a contract asserts facts about has the same shape, and the same obligations:
+
+| Layer | What it is | Protocol example | WebRTC example | Platform-API example |
+|-------|-----------|------------------|----------------|----------------------|
+| **L1** | A published standard (numbered, immutable) | the standard, cited by section | RFC 8829 (JSEP), RFC 6716 (Opus) | — (platform APIs are not standardised across vendors) |
+| **L2** | A named reference implementation, **with version** | the reference implementation, with its version | the deployed peer implementation, per FR-nnn | Windows Graphics Capture API (Windows 10+) |
+| **L3** | A captured stream from a real peer | a capture from one peer | browser ↔ peer capture | runtime measurement |
+
+Choose the layer by *where the fact was actually read from*, not by convenience: a fact taken from an implementation's behaviour is L2, even when an L1 standard also exists and says something similar — the two can disagree, and the attribution must name the one that was used. A domain with no L1 coverage (platform APIs) still has L2 and L3 available; what it does not have is the option to assert without either.
+
+For protocol-bearing claims, `.specpro/templates/protocol-golden-bytes-guide.md` §2 gives the same model in fuller form.
+
+- An implementation-sourced fact MUST name the implementation **and its version**; without a version the fact is not checkable against a later version of the same source. An immutable published document (a numbered standard) is the one exception: its number *is* its version, so cite it by number and section — `L1 RFC 6143 §7.5.1`. Mutable documents (living specs, vendor docs) follow the implementation rule and MUST carry a version or retrieval date.
+
+**Sources that do NOT satisfy the requirement**:
+
+- "common knowledge" / no attribution at all;
+- an assertion sourced from the implementing code itself — the implementation cannot witness its own correctness (same rule as §2's anchor prohibition);
+- "obvious" / "standard practice" — these read as claims but cannot be checked;
+- **a bare protocol name or version** — naming the protocol (or a version of it) identifies *which protocol*, not *which part of it* or *how it was read*. The attribution MUST resolve to a section of the standard, or to a named implementation with its version. A reader given only a protocol name still cannot check the claim without re-deriving it from the whole document.
+
+**Cross-contract references are acceptable sources — under an audit condition**: a contract may source a fact by pointing at another contract, provided **the referenced section is itself audited** (its own facts carry resolving attributions, and it is covered by the contract-fact audit). A chain that terminates in an unattributed section is not a source — it merely relocates the unverified claim. Where a contract is the designated authority for a fact class (e.g. the wire-protocol contract for message layouts), dependants SHOULD point at that contract's specific section rather than restating the fact, so the fact has one place to be right.
+
+**Peer-behaviour assertions**: a claim that a named peer requires, tolerates, or rejects something is admissible only with a measured row in the Peer Diversity Registry (see the protocol rules' peer-diversity requirement). Absent that row, record the item as unverified rather than asserting it.
+
+**From Acceptance Scenarios - API Responses** 🆕:
+   - **For each Happy Path Scenario**:
+     * Success response with all observable results from Independent Test
+     * Response body structure
+     * Status code: 200 or 201
+
+   - **For each Error Scenario**:
+     * Error condition (from scenario)
+     * Error response body:
+       - error: string (specific error code)
+       - message: string (user-friendly message from scenario)
+       - suggested_action: string (actionable suggestion from scenario)
+     * Status code: 400, 401, 403, 404, 408, 423, etc.
+     * Include error recovery guidance if applicable
+
+   - **For each Edge Scenario**:
+     * Special handling response
+     * Constraint validation messages
+     * Boundary condition handling
+     * Status code: 200 (with warning), 206, etc.
+
+   - **For each Permission Scenario**:
+     * Authentication requirements
+     * Authorization checks
+     * Redirect URLs (if applicable)
+     * Status code: 401, 403, 302, etc.
+
+   Example mapping:
+   Scenario: "Given an invalid address is entered, When Connect is clicked, Then a friendly error message appears within 5 seconds"
+   → Error Response:
+     ```json
+     {
+       "error": "CONNECTION_FAILED",
+       "message": "Cannot connect to the server. Please check: 1) the server address, 2) that the server is running, 3) the network connection",
+       "suggested_action": "Verify the server address and network connection, then retry"
+     }
+     ```
+     Status: 408 (Request Timeout)
+
+- **Validation Rules**: Preconditions, postconditions, invariants
+- **Edge Cases**: Error handling, boundary conditions
+- **References**: Link to spec.md User Stories and FRs
+
+**Progress**: 📐 [2.5/4] contracts generated (P1: 100%, P2: 70%, P3: 30%)...
+
+**3. Post-generation Coverage Validation**:
+
+**a. Re-calculate coverage**:
+```markdown
+After generation:
+- P1 User Stories: 100% coverage required ✓
+- P2 User Stories: 70% coverage recommended
+- P3 User Stories: 30% coverage optional
+```
+
+**b. Display final report**:
+```markdown
+## Final Contract Coverage Report
+
+**P1 Coverage**: 100% (3/3) ✅
+**P2 Coverage**: 70% (1/1) ✅
+**P3 Coverage**: 33% (1/3) ⚠️
+
+**Overall**: 87% coverage
+
+✓ P1 coverage requirement met
+✓ All performance requirements contract-verified
+```
+
+**c. Handle insufficient P1 coverage**:
+- If P1 < 100%:
+  ```markdown
+  ❌ P1 Coverage Below 100%
+
+  Missing P1 Contracts:
+  - US1: plugin-lifecycle.md
+  - US2: connection-manager.md
+
+  This violates Constitution Article III (Test-First).
+  Generate missing P1 contracts now? (yes/no)
+  ```
+  - If yes: Generate, re-validate
+  - If no: Display warning, continue (user assumes risk)
+
+**Progress**: 📐 [3/4] Contract coverage validated...
+
+**4.0 Constitution Gate Evaluation** ✨ NEW (CRITICAL):
+
+**Purpose**: Evaluate all Constitution violations and reject unjustified ones
+
+**Progress**: 📐 [3.5/4] Evaluating Constitution gates...
+
+**Why This Step Is Critical**:
+- Initial Constitution Check (Step 5.3) was done **before** Phase 1 design
+- Phase 1 may have introduced new design decisions that violate principles
+- Must verify all violations have explicit justification
+- Unjustified violations must be rejected or fixed
+
+**4.0.a Load Constitution Check**:
+```markdown
+Read the `## Constitution Check` section — ⚠️ **它在 `specs/plan-overview.md`，不在 `plan.md`** (T171)
+Extract all items whose **Status is `❌ FAIL`**
+```
+⚠️ **这条闸门读的取值曾是一个没有生产者的字面量**（`T229` ④）：它此前写 `Extract all items marked ⚠️ VIOLATION`，而**全工具链没有任何东西产出 `VIOLATION`** —— `grep -rn 'VIOLATION' templates/ commands/`（除本文件外）**零命中**；本命令的 `§5.3.c` 写的是「Document status: **✅ PASS or ❌ FAIL**；**If FAIL: Provide justification**」，`plan-overview-template.md` 的 `## Constitution Check` 写的是「status (**PASS / PARTIAL / FAIL**)」。⇒ 照旧取值提取，**恒为空**，而"没有违规"与"没读到违规"在报告上同形。**取值以 `§5.3` 为准，本处不另立词汇。**
+⚠️ **`⚠️ PARTIAL` 不归这条闸门**：它不是"违规"，而是"设计层面满足、集成层留有缺口" ⇒ 由 **`§5.3.e`** 要求**把层级写明**（原理行与总体行各写一次），不是要一份 justification。
+
+**4.0.b Evaluate Each Failing Item**:
+```markdown
+For each `❌ FAIL` item:
+  1. Check Justification field exists
+  2. Validate Justification completeness:
+     - ✅ Contains "Why" (business justification)
+     - ✅ Contains "Alternatives Considered"
+     - ✅ Contains "Trade-offs"
+     - ✅ Contains "Reversibility"
+  3. If Justification missing or incomplete:
+     - ERROR: "Unjustified violation: [PRINCIPLE_NAME]"
+     - Display violation details
+     - Display what's missing from justification
+     - ABORT or require user confirmation
+```
+
+**4.0.c Gate Evaluation Logic** (Pseudo-code):
+> ⚠️ **围栏是 `text` 而非 `bash`，这是更正不是降级**：本块**自己写着 "(Pseudo-code)"**，而内容里
+> `for each principle in constitution:` **不是合法 shell**。⇒ 标签与内容不符的是**围栏**，不是内容。
+> 按 `bash` 标签它会以 shell 的身份受检，而它**从来不是** shell —— 判据的对象是"文档里内嵌的 shell 片段"，
+> 这一块不在其中。⇒ 改为 `text`：**它不再被检，也不再被误读作可执行代码**（`T168`）。
+```text
+VIOLATION_COUNT=0
+UNJUSTIFIED_COUNT=0
+
+for each principle in constitution:
+    if check_status == "FAIL":     # ⚠️ §5.3 产的取值是 PASS / PARTIAL / FAIL —— 此前比的是没有生产者的 "VIOLATION" (T229 ④)
+        VIOLATION_COUNT=$((VIOLATION_COUNT + 1))
+        justification=$(get_justification $principle)
+
+        if is_empty "$justification"; then
+            UNJUSTIFIED_COUNT=$((UNJUSTIFIED_COUNT + 1))
+            echo "❌ FAIL: $principle"
+            echo "   Reason: No justification provided"
+            echo "   Action: Fix design or provide justification"
+        elif ! is_justification_complete "$justification"; then
+            UNJUSTIFIED_COUNT=$((UNJUSTIFIED_COUNT + 1))
+            echo "❌ FAIL: $principle"
+            echo "   Reason: Justification incomplete"
+            echo "   Missing: $(get_missing_fields $justification)"
+            echo "   Action: Complete justification or fix design"
+        fi
+    fi
+
+if [ $UNJUSTIFIED_COUNT -gt 0 ]; then
+    echo "❌ GATE EVALUATION FAILED"
+    echo "Found $UNJUSTIFIED_COUNT unjustified violations"
+    echo "Total violations: $VIOLATION_COUNT"
+    echo ""
+    echo "Options:"
+    echo "1. Fix unjustified violations and re-evaluate"
+    echo "2. Provide justifications and re-evaluate"
+    echo "3. Abort and review design"
+    echo ""
+    echo "Your choice (1/2/3):"
+
+    # Read user choice
+    # If 1 or 2: Allow fixes, then re-run gate evaluation
+    # If 3: ABORT workflow
+    exit 1
+else
+    echo "✅ GATE EVALUATION PASSED"
+    echo "All $VIOLATION_COUNT violations have sufficient justification"
+    echo "Proceeding to next step..."
+fi
+```
+
+**4.0.d Gate Evaluation Result**:
+```markdown
+## Constitution Gate Evaluation Result
+
+**Total Violations**: N
+**Unjustified Violations**: M
+
+If M > 0:
+  ❌ GATE EVALUATION FAILED
+  Blocking workflow. Fix violations or provide justifications.
+
+If M = 0:
+  ✅ GATE EVALUATION PASSED
+  All violations justified. Proceeding...
+```
+
+**Progress**: 📐 [3.75/4] Gate evaluation complete
+
+---
+
+**4.1 Re-evaluate Constitution Check** ✨ NEW:
+
+**Purpose**: After Phase 1 design complete, check for new Constitution violations
+
+**Progress**: 📐 [3.8/4] Re-evaluating Constitution compliance...
+
+**Why This Step Is Critical**:
+- Initial Constitution Check (Step 5.3) was done **before** Phase 1
+- Phase 1 generated data-model.md and contracts/
+- These design artifacts may introduce new violations
+- Must re-evaluate with actual design, not just plan
+
+**4.1.a Load Design Artifacts**:
+```markdown
+Read:
+- data-model.md (entities, relationships, validation rules)
+- specs/contracts/*.md (API contracts, error responses, validation)
+- plan.md Architecture section
+```
+
+**4.1.b Re-evaluate Each Principle**:
+```markdown
+For each principle in constitution:
+  1. Check initial evaluation (from Step 5.3)
+  2. Evaluate against new design artifacts:
+     - data-model.md: Check entities, relationships
+     - contracts/: Check API responses, error handling
+     - Architecture: Check technology choices
+  3. Compare with initial evaluation
+  4. If status changed:
+     - Document new evaluation
+     - Update the `## Constitution Check` section in `plan-overview.md`
+  5. If new violation found:
+     - Require justification
+     - Add to the `## Constitution Check` section in `plan-overview.md`
+```
+
+**4.1.c Re-evaluation Example**:
+```markdown
+### II. User Experience & Accessibility
+
+**Initial Evaluation** (Step 5.3):
+- Status: ✅ PASS
+- Reason: "spec.md mentions desktop and mobile support"
+
+**Re-evaluation after Phase 1**:
+- Check data-model.md: ✅ No issues
+- Check contracts/:
+  - ❌ FOUND: Error responses lack user-friendly messages
+  - contracts/connection-manager.md line 45: "error: CONN_FAILED"
+  - Missing: User-friendly message and suggested action
+- Status: ❌ FAIL
+- Justification Required:
+  - Why: Technical constraints (error codes mandated by the wire protocol)
+  - Alternatives: Considered mapping table (rejected: too complex)
+  - Trade-offs: Protocol compliance vs UX clarity
+  - Reversibility: Can add client-side mapping later
+
+**Action**: Update Constitution Check with new violation
+```
+
+**4.1.d Update Constitution Check Section**:
+```markdown
+If new violations found:
+1. Add to the `## Constitution Check` section in `specs/plan-overview.md`
+2. Mark as ❌ FAIL
+3. Add Justification (if available)
+4. If no justification:
+   - WARNING: "New violation found, justification required"
+   - Prompt user to provide justification
+
+If existing violations resolved:
+1. Update status from ❌ FAIL to ✅ PASS
+2. Note: "Resolved in Phase 1 design"
+```
+
+**4.1.e Re-evaluation Summary**:
+```markdown
+## Constitution Re-evaluation Summary
+
+**Initial Violations**: N (from Step 5.3)
+**New Violations**: M (found during re-evaluation)
+**Resolved Violations**: K (fixed during Phase 1)
+
+**Net Change**: M - K violations
+
+If M > K:
+  ⚠️ WARNING: "Phase 1 introduced $(M-K) new violations"
+  Review new violations and provide justifications
+
+If M = K:
+  ✅ SUCCESS: "No new violations introduced"
+  All design decisions are Constitution-compliant
+```
+
+**Progress**: 📐 [3.9/4] Constitution re-evaluation complete
+
+---
+
+**4.2 Generate scenarios.md (Acceptance Test Scenarios)** — INITIAL RUN ONLY ✨
+
+**Condition** ⚠️: run this step **only when `specs/scenarios.md` is absent**. On every later run, skip it and note in the summary: `scenarios.md not touched — refresh with /specpro-scenarios when needed`.
+
+**Action**: generate it by following `/specpro-scenarios` — that command holds the template, the scenario type-coverage rules, the validation steps and the report format, and it rebuilds the file in full from `spec.md` on every run. **This command keeps no copy of them**: one definition, one owner. Read the `/specpro-scenarios` command document — resolve it by name through the agent's own command resolution, **never by a hardcoded install path** (the install layout is a deployment concern and may change; skills-form installs do not keep the old path) — and execute its Steps 2, 4, 5 and 6 against the scenarios already extracted in Step 2.b of this run.
+
+**Why the split** ⚠️: `spec.md` keeps evolving after planning ends. While this step was owned by `plan`, the only way to refresh the scenario view was to re-run the whole planning stage — so in practice nobody did, and the file silently aged (a presentation view that nobody re-runs drifts arbitrarily far behind its source, while downstream consumers keep preferring it). Ownership passes to `/specpro-scenarios` the moment this step creates the file; `plan` never rewrites it afterwards.
+
+**This is the presentation layer, NOT an execution document** — manual scenario execution lives in `specs/manual-test-tasks.md` (via `/specpro-manual-test`); end-user acceptance lives in `specs/acceptance.md` (generated only at the acceptance gate); coverage obligations live in `specs/test-tasks.md` (via `/specpro-test-plan`).
+
+**Progress**: 📐 [3.95/4] Generating scenarios.md (initial run only)...
+
+---
+
+**4.3 Generate quickstart.md (Developer Guide)** ✨ NEW
+
+**Purpose**: Create developer quickstart guide for environment setup, building, and running
+
+**Progress**: 📐 [3.99/4] Generating quickstart.md...
+
+**Why This Step Is Critical**:
+- Helps new developers get started quickly
+- Documents environment setup and build process
+- Provides essential commands for daily development
+- Reduces onboarding time for contributors
+
+**Target Audience**:
+- New developers joining the project
+- DevOps engineers setting up CI/CD
+- Contributors building from source
+- Anyone setting up development environment
+
+**4.3.a Extract Technical Context**:
+From plan.md Section "Technical Context":
+- **Language/Version**: (e.g., Kotlin 1.9.22+, Python 3.11+)
+- **Primary Dependencies**: (e.g., Compose Multiplatform, Ktor, Django)
+- **Build System**: (e.g., Gradle, npm, cargo)
+- **Target Platforms**: (e.g., Android, iOS, Web, Desktop)
+
+**4.3.b quickstart.md Template**:
+```markdown
+# Quick Start Guide: [FEATURE_NAME]
+
+**Feature**: [feature-name]
+**Last Updated**: [DATE]
+**Tech Stack**: [Language] + [Framework]
+
+## Overview
+
+This guide provides step-by-step instructions for setting up, building, and running [FEATURE_NAME].
+
+**Prerequisites**:
+- [Language/Version] (e.g., Kotlin 1.9.22+)
+- [Build Tool] (e.g., Gradle 8.5+)
+- [Platform-specific tools] (e.g., Android Studio, Xcode)
+
+---
+
+## Prerequisites
+
+### Required Software
+
+| Software | Minimum Version | Recommended | Purpose |
+|----------|----------------|-------------|---------|
+| **[Language]** | [min] | [recommended] | Development |
+| **[Build Tool]** | [min] | [recommended] | Build system |
+| **[IDE]** | [min] | [recommended] | Development |
+
+### Platform-Specific Requirements
+
+[If applicable, list platform-specific requirements]
+
+---
+
+## 1. Project Setup
+
+### Clone Repository
+
+```bash
+git clone <repository-url> [project-name]
+cd [project-name]
+```
+
+### Install Dependencies
+
+```bash
+[Install command based on build system]
+# Example for Gradle:
+./gradlew dependencies
+
+# Example for npm:
+npm install
+
+# Example for Python:
+pip install -r requirements.txt
+```
+
+### Configure Environment
+
+```bash
+# Create configuration file
+cp .env.example .env
+
+# Edit .env with your settings
+vim .env
+```
+
+---
+
+## 2. Building the Project
+
+### Build All Targets
+
+```bash
+[Build command]
+# Example:
+./gradlew build
+```
+
+### Build Specific Platform
+
+[If applicable]
+
+**Platform A**:
+```bash
+[command]
+```
+
+**Platform B**:
+```bash
+[command]
+```
+
+---
+
+## 3. Database Setup 🆕 (Conditional)
+
+> **NOTE**: This section is included ONLY if Technical Context → Storage contains database (SQLDelight, SQLite, PostgreSQL, MySQL)
+
+### Database Overview
+
+[FEATURE_NAME] uses [Database Name] for persistent storage.
+
+**Database Framework**: [e.g., SQLDelight X.Y.Z, SQLAlchemy, Django ORM]
+
+**Schema Files Location**:
+```
+[Path to schema files]
+# Example:
+shared/commonMain/sqldelight/com/example/db/
+├── Plugin.sq
+├── Connection.sq
+├── Session.sq
+└── migrations/
+    ├── V1__InitialSchema.sq
+    ├── V2__AddPluginAuthorField.sq (schema evolution)
+    └── V3__RenameStatusToState.sq (schema evolution)
+```
+
+### Initial Database Setup
+
+**First-time setup** (creates database from initial schema):
+
+```bash
+[Database initialization command]
+# Example for SQLDelight:
+./gradlew generateSqlDelightInterface
+
+# Example for Django:
+python manage.py migrate
+
+# Example for Node.js with Prisma:
+npx prisma migrate dev --name init
+```
+
+**Verify database created**:
+```bash
+[Verification command]
+# Example:
+ls -la .database/data.db
+# or
+psql -c "\dt" [database_name]
+```
+
+### Schema Evolution (Adding V2, V3 Migrations)
+
+> **IMPORTANT**: Use "Schema Evolution" terminology, NOT "database migration"
+
+**When to create schema evolution**:
+- Adding new field to existing table
+- Renaming column
+- Changing data type
+- Adding new table
+- Adding index
+
+**Schema evolution workflow**:
+```bash
+# 1. Modify entity in data-model.md
+# 2. Re-run plan to generate schema evolution migration
+# 3. New migration file created: V{N}__{Description}.sq
+
+# Example:
+# V2__AddPluginAuthorField.sq
+# V3__RenameStatusToState.sq
+
+# Apply schema evolution
+./gradlew generateSqlDelightInterface  # Regenerates database code
+./gradlew migrate                      # Applies new migrations
+```
+
+**Verify schema evolution applied**:
+```bash
+[Verification command]
+# Example:
+sqlite3 .database/data.db ".schema plugin"
+```
+
+### Database Evolution vs Data Migration - Terminology 📖
+
+**Schema Evolution** (what we do here):
+- Modifying database schema **within the SAME database system**
+- Examples: ALTER TABLE ADD COLUMN, RENAME COLUMN, CREATE INDEX
+- Files: V2__AddField.sq, V3__RenameColumn.sq
+- Framework: SQLDelight, Flyway, Liquibase
+
+**Data Migration** (different concept):
+- Moving data **from ONE database system to ANOTHER**
+- Examples: Oracle → PostgreSQL, MySQL → SQLite
+- Tools: ETL tools, custom export/import scripts
+
+**Do NOT confuse**:
+- ❌ "Database migration" for adding a field → Use "Schema evolution" instead
+- ✅ "Database migration" for Oracle → PostgreSQL → Correct usage
+
+### Common Database Issues
+
+**Issue**: Schema version mismatch
+```
+Error: Schema version 2 required, but version 1 found
+```
+**Solution**: Run pending schema evolution migrations
+```bash
+./gradlew migrate
+```
+
+**Issue**: Foreign key constraint error
+```
+Error: FOREIGN KEY constraint failed
+```
+**Solution**: Ensure related records exist before inserting
+
+**Issue**: Migration file not found
+```
+Error: V2__AddField.sq not found
+```
+**Solution**: Re-run plan to regenerate schema files
+
+---
+
+## 4. Running the Application
+
+### Development Mode
+
+```bash
+[Run command]
+# Example:
+./gradlew run
+
+# Example:
+npm run dev
+```
+
+Visit [URL] (e.g., http://localhost:5173)
+
+### Production Build
+
+```bash
+[Build command]
+# Example:
+./gradlew assembleRelease
+npm run build
+```
+
+---
+
+## 5. Development Workflow
+
+### Run Tests
+
+```bash
+[Test command]
+# Example:
+./gradlew test
+
+npm test
+
+pytest
+```
+
+### Code Style
+
+```bash
+[Format command]
+# Example:
+./gradlew ktlintFormat
+
+npm run format
+```
+
+### Hot Reload
+
+[Describe hot-reload capabilities]
+
+---
+
+## 6. Project Structure
+
+```
+[project-name]/
+├── src/                    # Source code
+├── tests/                  # Test files
+├── docs/                   # Documentation
+├── build.gradle.kts        # Build configuration
+└── README.md               # Project overview
+```
+
+---
+
+## 7. Common Issues
+
+### Issue: [Common problem 1]
+
+**Solution**: [Fix]
+
+### Issue: [Common problem 2]
+
+**Solution**: [Fix]
+
+---
+
+## 8. Next Steps
+
+1. Read the [feature spec](./spec.md) for requirements
+2. Review the [data model](./data-model.md) for entities
+3. Check [implementation plan](./plan.md) for architecture
+4. Start with [first task](./tasks.md)
+
+---
+
+## 9. Additional Resources
+
+- **Documentation**: [link to docs]
+- **API Reference**: [link to API docs]
+- **Contributing**: [link to CONTRIBUTING.md]
+
+---
+
+**Last Updated**: [DATE]
+**Status**: Ready for Development
+```
+
+**4.3.c Generate File**:
+```markdown
+Create file: specs/quickstart.md
+Content:
+- Overview and prerequisites
+- Project setup instructions
+- Building and running commands
+- Database setup 🆕 (conditional - only if Storage = SQLDelight/SQLite/PostgreSQL/MySQL)
+  * Database overview
+  * Initial database setup
+  * Schema evolution workflow (V2, V3 migrations)
+  * Database Evolution vs Data Migration terminology
+  * Common database issues
+- Development workflow
+- Project structure
+- Troubleshooting guide
+- Additional resources
+```
+
+**4.3.d Validation**:
+```markdown
+After generation:
+1. Verify all prerequisite software listed
+2. Check all commands are accurate
+3. Ensure platform-specific sections included (if applicable)
+4. Validate build/run commands work
+5. Confirm database setup section included (if project uses database) 🆕
+6. Verify schema evolution workflow documented (if applicable) 🆕
+7. Confirm troubleshooting section covers common issues
+```
+
+**Progress**: 📐 [4/4] quickstart.md generated (developer guide)
+
+---
+
+**4.4 Agent context check**:
+Check the AI-agent context file for the detected terminal (`CLAUDE.md` for Claude Code; `AGENTS.md` / `.cursorrules` / equivalent for others). Timing: after plan.md is written — run this check on EVERY `/specpro-plan` run that produces or updates plan.md (NOT limited to the first run; the check is idempotent — equivalent content is left untouched). Logic is inlined here; NO external update script.
+
+- **a. File missing or empty** → CREATE it from **`.specpro/templates/agent-context-template.md`** (read that file for the full template, rendering rules, and content discipline). Rule summary:
+  * Structural anchors stay in English as written; prose rendered in the project's Artifact Language
+  * The ONLY project-specific content is the Project Overview sentence (application scope + "built with SDD") — the generated file contains NO other project-internal references
+  * The Project Navigation section links `docs/implement/PROJECT_NAVIGATION.md` — **may not exist** (created by `/specpro-implement` up-front or with the first technical document); include it only when the file is present
+  * NO module lists, NO directory trees, NO tech-stack detail — they rot into misinformation, and AI agents can explore the repo / read plan.md themselves. Technology architecture single source: plan.md
+
+- **b. File exists** → CHECK whether its content is equivalent to **`.specpro/templates/agent-context-template.md`** (project overview with application scope + SDD statement, specpro-workflow coding rules, specs/-as-source-of-truth pointer, Project Navigation when present). Equivalent → leave the file untouched. Entries missing or contradictory → add/fix ONLY those entries; never restructure, never rewrite user-authored content.
+
+- **c. NEVER append machine-maintained sections** — "Active Technologies" / "Recent Changes" style incremental logs are forbidden. The agent context file stays a thin, human-owned pointer.
+
+**Progress**: 📐 [4/4] agent context checked (created if missing)
+
+**Output**:
+- ✓ data-model.md
+- ✓ Database schema files (.sq) and migrations 🆕
+  * Schema files: shared/commonMain/sqldelight/com/example/db/*.sq
+  * Initial migration: V1__InitialSchema.sq
+  * Schema evolution files: V2, V3... (if UPDATE_MODE=true)
+- ✓ specs/contracts/* (P1: 100%, P2: 70%, P3: 30%)
+- ✓ specs/scenarios.md (N scenarios, M User Stories) ✨ (initial run only — refresh on demand with /specpro-scenarios)
+- ✓ specs/quickstart.md (developer guide with database setup) ✨ NEW
+- ✓ agent context file (checked; created if missing)
+- ✓ Constitution re-evaluated ✨ NEW
+- ✓ Technical Context updated ✨ NEW
+
+**Progress**: ✓ Phase 1 complete: All design artifacts generated
+
+---
+
+### **Step 7: Update Lifecycle Fields** ✨ ENHANCED
+
+**Progress**: 📋 [7/8] Updating Lifecycle fields...
+
+**6.a Update spec.md with new PlanStatus**:
+```markdown
+For each processed item in lifecycle_cache.needsProcessing():
+  IF specStatus IN ("create", "update"):
+    - Update planStatus to "processed"
+    - Update tasksStatus to "update" (signals tasks need regeneration)
+    - Format: **Lifecycle**: [specify:create|update][plan:processed][tasks:update]
+    - specifyStatus preserved
+
+  ELSE IF specStatus = "delete":
+    - Ensure planStatus = "deprecated"
+    - Ensure tasksStatus = "delete"  ← Keep delete until Tasks processes it
+    - Remove all design content from plan.md
+    - Lifecycle remains: **Lifecycle**: [specify:delete][plan:deprecated][tasks:delete]
+```
+
+**6.b Write updated spec.md**:
+```markdown
+- Update Lifecycle fields for all processed items
+- Preserve all other spec content
+- Atomic write (overwrite entire file)
+```
+
+**6.c Handle deprecated items in plan.md**:
+```markdown
+Remove all design sections related to deprecated items:
+- Remove Data Model entities
+- Remove API contracts
+- Remove architectural discussions
+
+Add deprecation notice (if needed):
+## Deprecated Items
+The following items were deprecated and removed from the plan:
+- FR-XXX: [Title] (deprecated in spec v0.X)
+- USY: [Title] (deprecated in spec v0.X)
+```
+
+**Validation**: All processed items have updated planStatus
+
+---
+
+### **Step 8: Report & Next Steps** ✨ COMPLETELY REWRITTEN
+
+**Progress**: 📋 [8/8] Generating completion report...
+
+#### **7.1 Generated Artifacts Report** ✨ NEW
+
+```markdown
+## ✅ Phase 0 & 1 Complete
+
+### Phase 0: Research
+- ✅ research.md generated
+  → Resolved N NEEDS CLARIFICATION items from Technical Context
+  → Documented technology stack decisions
+  → Identified best practices for dependencies
+
+### Phase 1: Design & Contracts
+- ✅ data-model.md generated
+  → Defined M entities with relationships
+  → Documented validation rules
+  → Specified state transitions
+
+- ✅ contracts/ generated (P1: 100%, P2: 70%, P3: 30%)
+  → Generated K new contracts (details below)
+  → All P1 User Stories covered (100% ✓)
+  → Performance requirements contract-verified
+
+- ✅ scenarios.md generated (initial run only — this command never rewrites it again)
+  → Acceptance test scenarios (Given-When-Then format)
+  → N scenarios across M User Stories
+  → Scenario type distribution (Happy, Error, Edge, Permission)
+  → Related Requirements mapping
+  → Later refreshes: /specpro-scenarios
+
+- ✅ quickstart.md generated
+  → Developer quickstart guide
+  → Setup instructions
+  → Build and run commands
+  → Development workflow
+  → Troubleshooting guide
+
+- ✅ Agent context checked
+  → CLAUDE.md or agent-specific file
+  → created if missing (thin pointer: application scope + SDD statement + specs/ links)
+  → left untouched when equivalent content already present
+  → no incremental log sections ever (legacy behavior removed)
+
+### Plan.md Structure
+⚠️ **This list is `specs/plan.md` (Part I, machine-read) ONLY** — `T229` ①。它此前混进了三个**属于 `plan-overview.md`（Part II）**的节名，而 `§5.8` 的 **Check 1b** 明令它们 **MUST NOT** 出现在 `plan.md` 里：照那份清单核对，会把一份**违规的**产物判成合规。子节集合的**真源是 `templates/plan-template.md`**（`grep -nE '^#{2,3} ' templates/plan-template.md`），本清单只列**节的种类**、不重述其内容。
+- ✅ Technical Context (9 fields)
+- ✅ Quality Targets (Project Type Classification · Risk-Based Coverage Targets · Risk Classification · Constitution Compliance · Quality Validation Strategy) —— ⚠️ **此前整节漏列**，而它是 `tasks` §4.j-2 的**机器输入**（每 FR 的风险等级就从这里读）。
+- ✅ Architecture — **4 个无条件子节**：Layered Architecture · Component Interaction · Architecture Patterns · Critical Constraints；**另有 3 个条件子节**（有宪法条款 / 构建与声明不一致 / 激活门为 ACTIVE 时才产）：Shared/Platform Boundary Declaration · Shared-Layer Relocation Design · Protocol Codec Design Artifacts。
+- ✅ Project Structure (docs + source code)
+- ✅ Deprecated Items (Z items)
+
+**MUST NOT appear in `plan.md`**（均为 `plan-overview.md` 的节，`§5.8` Check 1b）：
+- 🅷 Summary · 🅷 Constitution Check · 🅷 Implementation Plan · 🅷 Complexity Tracking
+⚠️ **`Constitution Check` 尤其容易写错**：它是 §5.3 的产物、且 `Step 4.0` 的宪法门要读它 —— 但**读的位置是 `specs/plan-overview.md`**（`T171`）。把它放进 `plan.md` 既违规，也会让那个门去读一份不存在的东西。
+
+### Lifecycle Updates
+- ✅ N items: planStatus "create" → "processed", tasksStatus → "update"
+- ✅ M items: planStatus "update" → "processed", tasksStatus → "update"
+- ✅ Z items: planStatus → "deprecated", tasksStatus → "deprecated"
+- ✅ K items: Preserved with [x] marking (already processed)
+
+**Files Modified**:
+- specs/spec.md (Lifecycle fields updated)
+- specs/plan.md (incrementally updated)
+- specs/research.md (generated)
+- specs/data-model.md (generated)
+- specs/contracts/* (K contracts generated)
+- specs/quickstart.md (generated)
+- [agent-specific context file] (updated)
+```
+
+#### **7.2 Next Options** ✨ NEW (CLEAR USER GUIDANCE)
+
+```markdown
+**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**: `specify` — pending means an entry's `[plan: ]` marker is not
+`processed`, or an entry was not yet broken down.
+
+## 🎯 Next Steps
+
+Your planning phase is complete! Choose your next action:
+
+### Option 1: Continue Planning (Recommended) ⭐
+Generate detailed Implementation Plan (Phase 2-7) with breakdown of all deliverables.
+
+```bash
+/specpro-plan --continue
+```
+
+**What this does**:
+- Expands Phase 2-7 with detailed deliverables
+- Creates comprehensive timeline with milestones
+- Adds risk management and mitigation strategies
+- Suitable for: Large projects, team coordination, project management
+
+**Estimated time**: 5-10 minutes
+
+---
+
+### Option 2: Start Task Breakdown (Fast Track) ⚡
+Skip detailed planning, directly break down User Stories into actionable tasks.
+
+```bash
+/specpro-tasks
+```
+
+**What this does**:
+- Breaks User Stories into dependency-ordered tasks
+- Creates tasks.md with T001, T002, etc.
+- Identifies critical path and parallel opportunities
+- Suitable for: Small to medium projects, individual developers
+
+**Estimated time**: 3-5 minutes
+
+---
+
+### Option 3: Review & Adjust (Manual) 🔍
+Review generated artifacts before proceeding.
+
+```bash
+# Review the plan
+cat specs/plan.md
+
+# Review technical decisions
+cat specs/research.md
+
+# Review contracts
+ls specs/contracts/
+cat specs/contracts/plugin-lifecycle.md
+
+# Review data model
+cat specs/data-model.md
+```
+
+**After review**:
+- If satisfied: Choose Option 1 or Option 2
+- If adjustments needed: Update specs manually, then re-run `/specpro-plan`
+
+**Estimated time**: 5-15 minutes (depending on depth of review)
+
+---
+
+### Recommended Path 🎯
+
+Based on your project profile:
+- **Project Size**: Large (50+ FRs, 7 User Stories)
+- **Team**: Multi-person (needs coordination)
+- **Complexity**: High (plugin architecture, cross-platform)
+
+**Recommended**:
+```
+1. Review artifacts (Option 3) - 10 minutes
+   → Verify technical decisions in research.md
+   → Check contract coverage meets requirements
+   → Confirm Architecture section reflects your vision
+
+2. Continue planning (Option 1) - 10 minutes
+   → /specpro-plan --continue
+   → Generate detailed Phase 2-7 plan
+   → Review milestones and timeline
+
+3. Break down tasks (Option 2) - 5 minutes
+   → /specpro-tasks
+   → Generate actionable task list
+   → Start implementation
+```
+
+**Total estimated time**: 25 minutes to full task breakdown
+```
+
+#### **7.3 Verification Checklist** ✨ NEW (QUALITY GATE)
+
+```markdown
+## ✓ Pre-Continuation Verification
+
+Before proceeding to Option 1, 2, or 3, verify:
+
+### Critical Items (MUST verify)
+- [ ] **research.md resolved all NEEDS CLARIFICATION**
+  → Check Technical Context in plan.md
+  → All fields should have values (not "NEEDS CLARIFICATION")
+
+- [ ] **contracts/ covers all P1 User Stories (100%)**
+  → 判据：把 `spec.md` 里 **P1** 的 US 逐个拿来，在 `specs/contracts/` 里找到**点名了它**的契约。
+  ⚠️ **此前这里写的是一条测不到该结论的命令**（`grep -c "P1" specs/contracts/*.md`）：它数的是
+  "契约文件里出现过 `P1` 这个字符串"——**既不知道有几个 P1 US，也不知道谁没被覆盖**，
+  返回一个非零计数就"通过"了。**一条与它所声称的结论无关的判据，与没有判据同形**（T171）。
+
+- [ ] **data-model.md defines all key entities**
+  → Check entity count matches spec.md Data Model Entities FRs (FR-xxx~FR-yyy)
+  → Relationships documented
+
+- [ ] **Constitution Check has no ❌ FAIL** (or risk explicitly accepted)
+  → Review the `## Constitution Check` section in `specs/plan-overview.md` (not plan.md)
+  → If ❌ FAIL present, ensure risk was explicitly accepted
+
+### Recommended Items (should verify)
+- [ ] **Architecture section reflects technical approach**
+  → System Overview matches your vision
+  → Technology Decisions align with your stack
+
+- [ ] **Implementation Plan phases are realistic**
+  → Estimates (weeks) seem achievable
+  → Dependencies are correctly identified
+
+- [ ] **Deprecated Items are correctly handled**
+  → If Z > 0, review Deprecated Items section
+  → Confirm migration paths are documented
+
+### Optional Items (nice to verify)
+- [ ] **quickstart.md is accurate for your environment**
+- [ ] **Agent context file is a thin pointer** (application scope + SDD statement; NO stale module/tech lists)
+- [ ] **Project Structure matches your repository layout**
+
+---
+
+## ✅ Ready to Proceed? — **only after the upstream reconciliation above**
+
+⚠️ "Ready to proceed" is a claim about the **chain**, not about this planning stage
+(Constraint 6 / FR-045). Before offering the choice below, **state** each upstream stage's
+pending status — **including when it has none** (silence cannot be told apart from
+"forgot to look"), with skipped and processed counts listed separately.
+
+If all critical items verified, choose your next option:
+
+**1.** /specpro-plan --continue (Generate detailed plan)
+**2.** /specpro-tasks (Break down into tasks)
+**3.** I'll review first (Manual review)
+
+Your choice (1/2/3):
+```
+
+#### **7.4 Execution Time Summary** ✨ NEW (PERFORMANCE MONITORING):
+
+```markdown
+## ⏱️ Execution Summary
+
+**Command**: /specpro-plan
+**Duration**: [TOTAL_TIME]
+**Timestamp**: [YYYY-MM-DD HH:MM:SS]
+
+**Items Processed**:
+- New items: N (planStatus "create" → "processed", tasksStatus → "update")
+- Modified items: M (planStatus "update" → "processed", tasksStatus → "update")
+- Deprecated items: Z (planStatus → "deprecated", tasksStatus → "deprecated")
+- Skipped items: K (Already processed, preserved)
+
+**Files Modified**:
+- specs/spec.md (Lifecycle fields)
+- specs/plan.md (incrementally updated)
+- specs/research.md (generated)
+- specs/data-model.md (generated/updated)
+- specs/contracts/* (K contracts)
+- specs/quickstart.md (generated)
+
+**Performance Breakdown**:
+```
+┌──────────────────────────┬─────────────┬──────────────┐
+│ Step                      │ Time        │ Percentage   │
+├──────────────────────────┼─────────────┼──────────────┤
+│ Pre-flight Checks        │ [T1]        │ [P1]%        │
+│ Load context files       │ [T2]        │ [P2]%        │
+│ Quality gate             │ [T3]        │ [P3]%        │
+│ Lifecycle parsing         │ [T4]        │ [P4]%        │
+│ Phase 0 (Research)        │ [T5]        │ [P5]%        │
+│ Phase 1 (Design)          │ [T6]        │ [P6]%        │
+│ Lifecycle field updates   │ [T7]        │ [P7]%        │
+│ Report generation         │ [T8]        │ [P8]%        │
+└──────────────────────────┴─────────────┴──────────────┘
+```
+
+**Bottlenecks**:
+- Slowest step: [STEP_NAME] ([TIME])
+- Recommendation: [OPTIMIZATION_SUGGESTION]
+
+**Memory Usage**:
+- Lifecycle cache: [SIZE] items
+- Peak memory: ~[PEAK_MEMORY]
+
+**Next Run Optimization**:
+- Incremental mode: YES (only 4 items to process)
+- Estimated next run time: [ESTIMATED_TIME]
+- Time saved: ~[SAVED_TIME] vs full regeneration
+```
+
+**Benefits**:
+- ✅ Observable execution time
+- ✅ Performance bottleneck identification
+- ✅ Quantified optimization effects
+- ✅ Estimated next run time
+
+## Phases (Reference)
+
+### Phase 0: Research & Technology
+- Resolve NEEDS CLARIFICATION from Technical Context
+- Document technology stack decisions
+- Identify best practices
+
+### Phase 1: Design & Contracts
+- Generate data-model.md
+- Generate API contracts (P1: 100%, P2: 70%, P3: 30%)
+- Check agent context (create if missing; never incrementally rewrite)
+
+### Phase 2-7: Implementation Planning (via --continue)
+- Phase 2: Core Infrastructure
+- Phase 3: Core Plugins (P1)
+- Phase 4: Feature Plugins (P2)
+- Phase 5: Feature Plugins (P3)
+- Phase 6: Platform Integration
+- Phase 7: Testing & Hardening
+
+---
+
+## Key Rules ✨ OPTIMIZED
+
+- ✅ **Fail Fast**: Pre-flight checks catch issues early
+- ✅ **One-Time Read**: Load Lifecycle once, cache for reuse
+- ✅ **Incremental Updates**: Only process PlanStatus != "Processed"
+- ✅ **Clear Next Steps**: Explicit guidance after Phase 2
+- ✅ **Quality Gates**: Clarifications + Checklist validation
+- ✅ **Contract Optimization**: Generate only missing contracts
+- ✅ **Progress Visibility**: Clear indicators throughout
+- ✅ **Error Recovery**: Max 3 clarification attempts, manual intervention after
+
+---
+
+## Optimization Benefits
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| **Setup reliability** | 85% | 99% (+14%) | Pre-flight catches issues |
+| **Incremental update speed** | Baseline | 20-30% faster | One-time Lifecycle read |
+| **Contract generation** | All regenerated | Only missing | Avoids redundant work |
+| **User clarity** | Unclear next steps | Explicit options | Reduced confusion |
+| **Error recovery** | Infinite loops | Max 3 attempts | Prevents hang |
+
+---
+
+**Status**: ✅ OPTIMIZED VERSION READY
+**Version**: 2.0
+**Last Updated**: 2026-01-28
+
+---
+
+## Protocol Codec Module Rules 🌐 [CONDITIONAL — wire-format / protocol modules only]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — triggers T3/T4 (the design encodes/decodes a byte stream, or interoperates with a peer over a wire format). Consume the verdict recorded by `specify` (§6.4) rather than re-judging it; if this stage finds a trigger the earlier stage missed, record the discrepancy as a finding — do not silently override. Do not infer the gate from the presence of a network or a client/server split: those are transport, not wire format. When activated, the design output MUST contain the three items below, plus the verdict row.
+
+- **Protocol-point inventory** (design output): field- and branch-level enumeration — control-byte bit semantics, run-length extension chains, bit-packing order, payload byte-count branches, stream lifecycle. Granularity is the branch, not the message type: message-level tests pass while a branch-level defect stays latent. Semantics that are ambiguous in prose (extension chains, packing order, control-byte bits) MUST be recorded as **byte-level examples**, not by name. Format: `.specpro/templates/protocol-golden-bytes-guide.md` §1.
+- **Golden-bytes strategy** (three-layer cross-anchoring): L1 specification (structure) → L2 reference-implementation source (bit-level semantics) → L3 captured stream (final arbitration). Every anchor records its source layer and the protocol version it came from; when the layers conflict, L3 wins and the corrected understanding is written back. An anchor whose source cannot be reached is recorded as a **GAP** (§6.3) — never as an invented byte sequence. See `.specpro/templates/protocol-golden-bytes-guide.md` §2.
+- **Stream-semantics comparison** (MANDATORY when one client speaks several encoders): produce a comparison of the stream semantics across the codecs that client supports — a continuous single stream in one codec vs an independent per-message stream in another. Its purpose is to stop a fix's lesson from being carried across codecs whose semantics are opposite.
+