specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.tasks.md

@@ -0,0 +1,1207 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: specpro-analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: specpro-implement
+    prompt: Start the implementation in phases
+    send: true
+writes:
+  # This command's write surface: only what it produces AS THE PRODUCER of that
+  # (artifact, unit) pair. A write this command makes on a non-producer path is a
+  # boundary violation by definition (FR-051) and MUST NOT be declared here.
+  # The full ownership map is the UNION of every command's writes: block.
+  - artifact: specs/tasks.md
+    unit: "whole task sections, the dependency graph, parallel-execution examples, and the ## Deprecated Items block; **except** the completion checkbox of a task line -> [x], which is /specpro-implement's (it is the ONE part of a task section this command does not own)"
+  - artifact: specs/spec.md
+    unit: "per-FR Lifecycle fields -> [tasks:processed|deprecated]"
+  - artifact: specs/implement_issues.md
+    unit: "the [tasks] section -> task descriptions fixed/added/reordered; its own entries marked [x]; the statistics table (**its own row only** — seven commands declare this artifact); appended ISS-NNN entries in any section — registration is routing; only [x]-marking is section-scoped"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — detect the artifact, default to incremental** ⚠️ [settled 2026-09-13]:
+
+**Before writing `specs/tasks.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/tasks.md ] && echo EXISTS || echo NEW    # -s: exists AND non-empty (an empty placeholder counts as NEW)
+```
+
+| Detection | Mode |
+|-----------|------|
+| **NEW** (absent or empty) | **Initial** — generate from scratch |
+| **EXISTS** | **Incremental** — evolve it; **never silently regenerate from scratch** |
+
+**Overwriting an existing artifact requires explicit, confirmed intent:**
+1. Only when the user *explicitly* asks (in their own words) does the initial path run on an existing artifact.
+2. **Even then, confirm once more before writing** — name the artifact that will be replaced and what will be lost; wait for the answer.
+3. **Silence is not consent.** An unspecified run on an existing artifact is ALWAYS incremental.
+
+> **Why a shared rule rather than per-command courtesy**: nine of the twelve non-implementation commands already had some protection, but each wrote it its own way (`EXISTING_SPEC` check · "creates a NEW file" · `NEVER overwrite` · "incremental regeneration" · `AUTO_MODE=false`), and **three had none at all** — not by decision, but because the discipline had no shared carrier. Overwriting an artifact the user has been evolving is not recoverable within the session; the cost of asking is one prompt.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Key Concept: FR-Level Incremental Task Updates 📋 [CRITICAL]
+
+**Design Principle**: Tasks are generated and updated based on **Functional Requirements (FRs)**, not just User Stories.
+
+### Why FR-Level Granularity?
+
+User Stories contain multiple FRs. When a single FR is modified:
+- ✅ **OLD APPROACH (WRONG)**: Skip entire US if US.TasksStatus = "processed"
+  → FR modifications are ignored ❌
+
+- ✅ **NEW APPROACH (CORRECT)**: Check each FR's TasksStatus independently
+  → Only update tasks for modified FRs, preserve completed tasks from other FRs ✅
+
+### Update Scenarios:
+
+1. **US.TasksStatus = "create"**:
+   - Generate tasks for ALL FRs in this US
+
+2. **US.TasksStatus = "update"**:
+   - Regenerate tasks for ALL FRs in this US
+   - Preserve completed tasks from previous iteration
+
+3. **US.TasksStatus = "processed"** but some **FR.TasksStatus = "update"**:
+   - **Partial update**: Only regenerate tasks for those specific FRs
+   - **Preserve** all completed tasks from other FRs
+   - **US.TasksStatus remains "processed"** until US itself is modified
+
+### Task Format Requirement:
+Every task MUST end with `(FR-XXX)` annotation to enable FR-level tracking:
+```markdown
+- [ ] T-xxx [US1] Implement plugin discovery (FR-xxx)
+```
+
+## 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/T/INF/IT/CE/AE), 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
+
+1. **Check for --review-issues argument** 🆕:
+
+   **Purpose**: Process implement issues submitted from the implement phase
+
+   a. **Parse arguments**:
+      - If `$ARGUMENTS` contains `--review-issues`:
+  * **Skip the question below**; proceed directly to step 1b (review issues)
+- Else: **detect, then ask** ⚠️ [settled 2026-09-13]:
+  * Check the `[tasks]` section of `specs/implement_issues.md` for open `[ ]` entries
+  * **None** → continue with normal task generation (step 2+). **No prompt.**
+  * **Some** → **ask**: "N open `[tasks]` issues in specs/implement_issues.md. Process them first, or run normally?"
+    - *Process first* → proceed to step 1b (review issues)
+    - *Run normally* → continue with normal task generation (step 2+)
+  * **Rationale**: the flag used to be the whole switch — not passing it left pending issues **silently unprocessed**, passing it meant overriding the work the user actually wanted, and **which issues were pending was invisible until the command ran**. Detect-then-ask makes it an explicit choice; the flag now only means *"I already know — don't ask"*.
+    (Same model as `/specpro-implement` and `/specpro-test-plan` — see TOOL-008.)
+
+   b. **Review implement issues**:
+      - Read `specs/implement_issues.md`
+      - Extract all issues from `[tasks]` section
+      - Filter for issues marked `[ ]` (pending) only
+      - If no pending issues found:
+        * Display: "✓ No pending [tasks] issues to process"
+        * Exit
+
+      - Display issue summary:
+        ```markdown
+        📋 [tasks] Issues Review
+
+        Found N pending [tasks] issues:
+        1. [ ] ISS-XXX: Issue description
+        2. [ ] ISS-XXX: Issue description
+        ...
+        ```
+
+      - For each pending issue:
+        * Read issue details:
+          - Problem description
+          - Current task (what's wrong)
+          - Suggested fix (what should be)
+          - Related task IDs
+        * Determine appropriate action:
+          - **Fix task description**: Update task description
+          - **Delete duplicate task**: Remove duplicate task
+          - **Add missing task**: Insert new task
+          - **Reorder tasks**: Adjust task order to fix dependencies
+          - **Split/merge tasks**: Combine or divide tasks as needed
+        * Apply the change to tasks.md
+        * Mark issue as `[x]` in implement_issues.md
+        * Display: "✓ Processed ISS-XXX: [action taken]"
+
+      - Update the statistics table at the **top** of `implement_issues.md` (its position is deliberate — see the note below)
+      - **Edit order and idempotency check** ⚠️ [a silent false-skip, observed 2026-09-13]: write the **entry body first** (into its own section), then the derived summaries (statistics table + `Last Updated`) — never the reverse. A derived summary written first introduces the new ID into the file's text before the entry exists, so an idempotency guard that greps the file for that ID falsely concludes "already present" and **skips the entry**, while the summaries still claim it landed. For the same reason the guard MUST match the entry body's **line-start pattern**, never a full-text keyword search:
+        ```bash
+        grep -qE '^- \[[x ]\] ISS-<N>:' specs/implement_issues.md   # correct — matches an ENTRY, not a mention
+        # grep -q 'ISS-<N>' …                                        # wrong — also matches the statistics Pending-Items column, the Last Updated line, cross-references
+        ```
+  - **General rule: every grep/awk example shown in an instruction or template must itself obey the line-start pattern** (TOOL-009) — the executing side copies examples verbatim, so an example that uses a whole-file match propagates the same misjudgment to everyone who copies it. This file has already corrected its own sentinel self-check command under this rule.
+        `.specpro/scripts/bash/verify-ledger.sh` reports the resulting inconsistency as a count mismatch — but only if it is run, and by then the entry is already missing.
+      - **Entry placement**: append new entries to the end of their own section, never to the end of the file. The file's statistics block sits at the top precisely so that "append to the end" lands inside the last section rather than between sections; moving or duplicating a section header breaks that and produces an orphaned section no `--review-issues` run will read.
+      - **Verify mechanically after writing**: run `.specpro/scripts/bash/verify-ledger.sh` — it checks entry section membership, statistics-vs-actual counts, and the trailing newline in one pass (non-zero exit names the violation). Marking issues `[x]` changes the counts, so this applies to this command too, not only to commands that append. A pre-commit hook enforces the same check.
+
+      - Display completion summary:
+        ```markdown
+        ✅ Completed [tasks] issues review
+
+        Processed: N issues
+        Updated: specs/tasks.md
+        Marked as [x] in implement_issues.md
+
+        ⚠️ **This is not an unqualified "ready".** This summary covers the `[tasks]` queue;
+        "ready to continue" is a claim about the **chain** (Constraint 6 / FR-045). State each
+        upstream stage's pending status before making it — see *Upstream status reconciliation*
+        in the main report below.
+
+        You can now run /specpro-implement to continue implementation.
+        All implement issues have been addressed.
+        ```
+
+2. **Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+3. **Pre-flight Checks** ✨ (Fast-fail validation before core logic):
+
+   **Purpose**: Verify environment and prerequisites before executing task generation
+
+   a. **Required files check**:
+      ```bash
+      Check these files exist:
+      - ✅ $FEATURE_SPEC (specs/spec.md)
+      - ✅ $IMPL_PLAN (specs/plan.md)
+
+      If missing:
+      ❌ ERROR: Required file missing: $file
+         Fix: Run /specpro-plan first or verify installation
+         EXIT 1
+      ```
+
+   b. **Directory permissions check**:
+      ```bash
+      Check writable directories:
+      - ✅ $SPECS_DIR (specs/) is writable
+      - ✅ $FEATURE_DIR (specs/) can create tasks.md
+
+      If not writable:
+      ❌ ERROR: No write permission to $directory
+         Fix: chmod +w $directory or run with appropriate permissions
+         EXIT 1
+      ```
+
+   c. **Spec.md format validation**:
+      ```bash
+      Check spec.md has Lifecycle fields:
+      - ✅ Contains "**Lifecycle**:" markers
+
+      If missing:
+      ⚠️ WARNING: spec.md missing Lifecycle fields
+         Impact: 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):
+      ```
+
+   d. **Plan.md existence check**:
+      ```bash
+      Check if plan.md was generated:
+      - ✅ plan.md exists with Technical Context
+
+      If missing or incomplete:
+      ❌ ERROR: plan.md not found or incomplete
+         Fix: Run /specpro-plan first
+         Task generation requires plan.md for tech stack and architecture
+         EXIT 1
+      ```
+
+   e. **Quality gate: requirements.md validation** 🆕 [ENFORCED - AUTO-REPAIR]:
+      ```bash
+      Check specs/checklists/requirements.md:
+      - ✅ File exists
+      - ✅ Every item marked `[x]` (passed)   ← ⚠️ **不在此处印条数**（`T238` / `ISS-211`）：条数的真源是 `requirements-template.md` 的 `**Total Items**` 与清单自身；在这里重述一个数字即制造第二个来源。此处曾印 `12`，而**真值早已是 11** —— 它漂过一次而无人察觉，正是"重述"这件事的代价。⚠️ **该 MUST 现在有触发点**：`verify-shapes.sh` 的 `SHAPE-4 req-template-total` 比对模板字面量与模板自己的准则条数。
+
+      ⚠️ 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 "   Task generation 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 task generation..."
+         ```
+      fi
+
+      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]"
+         ```
+      fi
+
+      ✓ Quality validation passed
+      ```
+   **Benefits**:
+   - ✅ Fast failure: Detect issues before execution, avoid waste
+   - ✅ Clear error guidance: Each error has explicit fix steps
+   - ✅ Improved reliability: After pre-flight checks pass, execution is more reliable
+
+2. **Load design documents** 📋 [2/7]: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+2.5. **Load quality recommendations** 📋 [3/7]: Load quality checklist recommendations and create tasks for quality issues ✨
+
+   **Purpose**: Load quality checklist recommendations and create tasks for quality issues
+
+   a. **Check if checklists/requirements.md exists**:
+      - Read `specs/checklists/requirements.md`
+      - If file doesn't exist, note: "No quality checklist found. Proceeding without quality recommendations..."
+        - Proceed to step 3
+
+   b. **Parse checklist for quality issues**:
+      - Read the checklist's **own** fields — verbatim, and only these:
+        * `**Status**`: `PASS` | `BLOCK` — the producer sets `PASS` ⟺ `**Failed**` == 0
+        * per-item rows: `- [ ] **Status**: x | ⊘ Skipped | ✗ Failed`
+      - The blocking set = the rows whose per-item value is `✗ Failed`
+      - ⚠️ Do **not** look for `❌ FAIL` / `⚠️ WARNING` items:
+        `templates/requirements-template.md` emits neither ⇒ this step would find
+        nothing on **every** checklist and produce no `[Quality]` task, ever.
+      - Check if plan.md addressed these issues
+
+   c. **Create tasks for quality issues**:
+      - For each `✗ Failed` item not addressed in plan.md:
+         * Create task: "TXXX: [Quality] Fix [specific issue] from checklist"
+         * Priority: High (P0)
+         * Add to Phase 1 (Foundational) or appropriate phase
+         * Example: "T-xxx: [Quality][P0] Add test coverage requirement for the wire protocol (>90% per Constitution Article IV)"
+      - ⚠️ **`⊘ Skipped` items generate no task**: the template's rule is that an
+        honest skip is a conclusion, not a debt — turning one into a task converts
+        "not applicable here" back into an obligation, which is exactly the
+        conflation the `⊘` value was introduced to end.
+
+   d. **Report quality tasks created**:
+      ```markdown
+      ## Quality Tasks Created
+
+      **Quality Issues Found**: 1
+      - ✗ Failed: 1 blocking issue
+      - ⊘ Skipped: 2 (non-blocking — no task generated)
+
+      **Tasks Created**:
+      - T-xxx: [Quality][P0] Add test coverage requirement for the wire protocol (from ✗ Failed)
+
+      These tasks will be integrated into the task breakdown.
+      ```
+
+   e. **Store recommendations for task context**:
+      - Keep recommendations accessible during task generation
+      - Apply recommendations to relevant user stories/FRs
+      - Example: For FR-xxx (Display remote screen), add edge case task from recommendation
+
+3. **Load spec items and process according to Lifecycle status** 📋 [4/7]:
+
+   **Purpose**: Track which spec items have been broken down into tasks and re-breakdown only modified items.
+
+   a. **Parse spec.md for Lifecycle fields**:
+      - Load spec.md (from FEATURE_DIR)
+      - 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>]
+         ⚠️ **Those two are the whole list** (`T249` / `ISS-225`): `## Constitution Constraints` **carries no `**Lifecycle**:` field**, and a third bullet naming it used to sit here. ⚠️ **Do not add it back** — the adjudication and its three pieces of evidence are in `commands/specpro.specify.md` → *Lifecycle Update Rules* (`T239` / `ISS-212`); the short version: the template emits no such field there, the plan-layer reader enumerates two classes, and measured on `specs/spec.md` all 73 Lifecycle lines belong to a US or an FR. A class listed here but absent from the artifact is a class this step would scan for and never find — and "found none" reads the same as "there were none".
+
+      **b. Extract Independent Test and Acceptance Scenarios** 🆕:
+      - For each User Story (from filtered list where tasksStatus != "processed" && tasksStatus != "deprecated"):
+         * **Extract Independent Test** (verbatim copy - preserve exact wording from spec.md)
+         * **Extract 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
+           - All 4 types should be represented
+           - Warn if scenario count is outside expected range
+         * **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)
+
+   c. **Categorize items by TasksStatus**:
+      - **Items needing breakdown**: tasksStatus != "processed" && tasksStatus != "deprecated"
+         * tasksStatus = "create": New items, never broken down
+         * tasksStatus = "update": Items modified since last Tasks breakdown
+         * tasksStatus = "delete": Items deleted, need removal (will become deprecated after Plan processing)
+         * tasksStatus = "deprecated": Already processed in previous iteration, skip
+      - **Items to skip**: TasksStatus = "processed"
+         * Already broken down and unchanged, skip task generation
+
+   d. **Report processing statistics**:
+      ```markdown
+      ## Lifecycle Processing Summary
+
+      **Total Items**: N
+      - **New items**: X (tasksStatus = "create")
+      - **Modified items**: Y (tasksStatus = "update")
+      - **Deprecated items**: Z (tasksStatus = "deprecated")
+      - **Skipping**: M (already Processed)
+
+      Breaking down X+Y items into tasks, removing Z items...
+      ```
+
+   e. **Filter items for workflow**:
+      - Create filtered list containing only:
+         * Items where tasksStatus != "processed" && tasksStatus != "deprecated"
+         * These are the ONLY items to include in task breakdown
+      - Items with tasksStatus = "processed" or tasksStatus = "deprecated" are excluded from task generation
+
+4. **Execute task generation workflow** 📋 [5/7]:
+
+   **CRITICAL: Use TasksStatus to support incremental task generation**
+
+   a. **Load plan.md and extract** 🏗️ [ENHANCED - Architecture-Aware]:
+      - Tech stack, libraries, project structure
+      - **Architecture Patterns** (from plan.md Architecture Patterns section):
+        * Read all architecture patterns with their Key Points
+        * Extract pattern names, descriptions, and key capabilities
+        * Store for architecture pattern task generation
+      - **Layered Architecture** (from plan.md Layered Architecture section):
+        * Read all layers with their Responsibilities, Contains, and Constraints
+        * Extract layer definitions and MUST/MUST NOT constraints
+        * Store for cross-platform task generation and constraint validation
+      - **Component Interaction** (from plan.md Component Interaction section):
+        * Read all interaction patterns and their constraints
+        * Extract interaction mechanisms (e.g., EventBus, PluginContext)
+        * Store for interaction mechanism task generation
+      - **Critical Constraints** (from plan.md Critical Constraints section):
+        * Read all constraints with their Requirements and Architecture Impact
+        * Extract performance requirements, resource limits, operational constraints
+        * Store for constraint validation task generation
+      - Performance requirements and constraints (general)
+
+   b. **Load ONLY spec items filtered in Step 3.e** (where tasksStatus != "processed" && tasksStatus != "deprecated"):
+      - **SKIP items where TasksStatus = "processed" or TasksStatus = "deprecated"**
+      - These items have already been broken down into tasks in previous iterations (processed) or removed (deprecated)
+      - Do NOT regenerate tasks for these items
+      - Do NOT add to tasks.md
+
+   c. **Extract user stories with their priorities** (P1, P2, P3, etc.) from filtered list:
+      - Only include stories where tasksStatus != "processed" && tasksStatus != "deprecated"
+      - Mark stories as:
+        * **New story**: TasksStatus = "create" (never broken down)
+        * **Modified story**: tasksStatus = "update" (regenerate all FR tasks in this US, preserve completed tasks from other FRs)
+
+   d. **Extract functional requirements from filtered list** 📋 [CRITICAL]:
+      - **Purpose**: Identify which FRs need task generation/updates
+      - Extract ALL FRs from filtered list (where tasksStatus != "processed" && tasksStatus != "deprecated")
+      - Group FRs by their parent User Story (from spec.md structure)
+      - For each US, categorize its FRs:
+        * **New FRs**: tasksStatus = "create" (generate new tasks)
+        * **Modified FRs**: tasksStatus = "update" (regenerate tasks for this FR only)
+        * **Deleted FRs**: tasksStatus = "delete" (remove tasks for this FR)
+      - Store FR-US mapping for task organization in Step 4.h
+
+   e. **For data-model.md**:
+      - If exists: Extract entities and map to user stories
+      - Check TasksStatus for each entity to skip already processed ones
+
+   f. **For contracts/**:
+      - If exists: Map endpoints to user stories
+      - Check TasksStatus for each contract to skip already processed ones
+
+   g. **For research.md**:
+      - If exists: Extract decisions for setup tasks
+      - Only include setup tasks for incomplete/new items
+
+   h. **Generate tasks organized by user story** 📋 [CRITICAL - FR-BASED]:
+      - Follow Task Generation Rules (below)
+      - **CRITICAL: Task generation is driven by FR TasksStatus, not just US TasksStatus**
+
+      **Update Logic**:
+      1. **For USs with tasksStatus = "create"**: Generate tasks for ALL FRs in that US
+      2. **For USs with tasksStatus = "update"**: Regenerate tasks for ALL FRs in that US, preserve completed subtasks
+      3. **For USs with tasksStatus = "processed"**:
+         - Check individual FRs' TasksStatus from Step 4.d
+         - If any FR has tasksStatus = "update" or "create":
+           * Generate/update tasks ONLY for those specific FRs
+           * Preserve all completed tasks from other FRs
+         - If no FRs need updates, skip this US entirely
+
+      **Task Format**:
+      - Every task MUST end with `(FR-XXX)` annotation
+      - Example: `- [ ] T-xxx [US1] Implement plugin discovery (FR-xxx)`
+      - This enables precise FR-level task tracking and updates
+
+   i. **Generate architecture-aware tasks** 🏗️ [NEW - Architecture-Aware]:
+      **Purpose**: Generate tasks for architecture patterns, layers, interactions, and constraints
+
+      **CRITICAL**: Architecture content from plan.md MUST drive task generation to ensure completeness
+
+      **i-1. Generate Architecture Pattern tasks**:
+      For each Architecture Pattern extracted in Step 4.a:
+      - **Phase assignment** ⚠️ [settled 2026-09-13]: architecture tasks go to **Phase 2 (Foundational)** — they are infrastructure work, not User Story work — and therefore carry **NO `(FR-xxx)` annotation** (the format rule: Setup / Foundational / Polish phases have no FR annotation). Anchor them by the **pattern name** instead. Do NOT copy the `(FR-xxx)` shape from the examples below — an earlier revision of this step showed it and the examples pulled generated tasks into the wrong phase.
+      - **Identify pattern components**: Extract Key Points to identify required implementations
+      - **Generate tasks for pattern components**:
+        * Example: "Plugin Pattern (Microkernel + Plugins)"
+          - TXXX: [P] Implement the plugin manager with framework integration — Validates: Microkernel + Plugins pattern
+          - TXXX: [P] Implement plugin discovery from plugins directory — Validates: Microkernel + Plugins pattern
+          - TXXX: [P] Implement plugin lifecycle management (initialize, start, stop, shutdown) — Validates: Microkernel + Plugins pattern
+          - TXXX: [P] Implement hot-reload support for development mode — Validates: Microkernel + Plugins pattern
+          - TXXX: [P] Implement plugin dependency resolution — Validates: Microkernel + Plugins pattern
+        * Example: "Repository Pattern"
+          - TXXX: [P] Define repository interfaces in shared/commonMain — Validates: Repository pattern
+          - TXXX: [P] Implement the concrete repositories against the project's storage layer — Validates: Repository pattern
+          - TXXX: [P] Add repository mocks for unit testing — Validates: Repository pattern
+        * Example: "Event Bus Pattern"
+          - TXXX: [P] Implement EventBus with publish/subscribe mechanism — Validates: Event Bus pattern
+          - TXXX: [P] Implement async event delivery via coroutines — Validates: Event Bus pattern
+          - TXXX: [P] Add event filtering and routing — Validates: Event Bus pattern
+      - **See references**: Include "See: research.md Section [X]" in task notes for detailed design
+
+      **i-2. Generate Layered Architecture tasks** (from plan.md Layered Architecture):
+      For each Layer extracted in Step 4.a:
+      - **Phase assignment** ⚠️: **Phase 2 (Foundational)**; **NO `(FR-xxx)` annotation** — same rule as i-1. Anchor by the **layer name**.
+      - **Generate tasks for each platform layer** (if expect/actual pattern documented):
+        * Example: "Shared Business/Domain Layer"
+          - TXXX: [P] Create expect interface in commonMain — Validates: Shared/Core layer
+          - TXXX: [P] Create actual implementation for Android in androidMain — Validates: Shared/Core layer
+          - TXXX: [P] Create actual implementation for iOS in iosMain — Validates: Shared/Core layer
+          - TXXX: [P] Create actual implementation for Desktop in desktopMain — Validates: Shared/Core layer
+      - **Generate layer constraint validation tasks**:
+        * For each "MUST NOT" or "MUST" constraint:
+          - TXXX: [Quality] Validate [constraint description] (e.g., "Platform Layer MUST NOT contain business logic") — Validates: [constraint description]
+          - Add linting or code review task to enforce constraint
+      - **Apply cross-platform completeness**: Ensure all platform-specific layers are included
+
+      **i-3. Generate Component Interaction tasks** (from plan.md Component Interaction):
+      For each interaction pattern extracted in Step 4.a:
+      - **Phase assignment** ⚠️: **Phase 2 (Foundational)**; **NO `(FR-xxx)` annotation** — same rule as i-1. Anchor by the **interaction pattern name**.
+      - **Generate tasks for interaction mechanisms**:
+        * Example: "Plugin → Core via EventBus"
+          - TXXX: [P] Implement EventBus core with publish API — Validates: Plugin → Core interaction
+          - TXXX: [P] Implement EventBus subscription mechanism — Validates: Plugin → Core interaction
+          - TXXX: [P] Implement PluginContext eventBus exposure — Validates: Plugin → Core interaction
+          - TXXX: [P] Add interaction constraint validation: "Plugins MUST NOT call Core directly" — Validates: Plugin → Core interaction
+      - **Generate interaction constraint tasks**:
+        * For each constraint: Add validation task to ensure constraint is enforced
+
+      **i-4. Generate Critical Constraint validation tasks** (from plan.md Critical Constraints):
+      For each Critical Constraint extracted in Step 4.a:
+      - **Phase assignment** ⚠️: **Phase 2 (Foundational)**; **NO `(FR-xxx)` annotation** — same rule as i-1. Anchor by the **constraint description** (the `Validates:` field already carries it).
+      - **Generate validation task** for each constraint:
+        * Example: "Real-Time Responsiveness: <500ms input-to-display latency"
+          - TXXX: [Quality] Add performance test: Input-to-display latency <500ms — Validates: Real-Time Responsiveness constraint
+          - Location: [REAL test source set, see Location grounding below]
+        * Example: "Bounded Resource Usage: 8GB RAM, 4 CPU cores"
+          - TXXX: [Quality] Add resource monitoring: RAM usage <8GB — Validates: Bounded Resource Usage constraint
+          - TXXX: [Quality] Add resource monitoring: CPU usage <4 cores — Validates: Bounded Resource Usage constraint
+          - Location: [REAL test source set]
+        * Example: "LAN-Only Operation: No cloud dependencies"
+          - TXXX: [Quality] Verify no cloud API calls in dependency graph — Validates: LAN-Only Operation constraint
+          - Location: [REAL test source set]
+      - **Mark constraint validation tasks as [Quality] priority**
+      - **Include constraint reference**: "Validates: [constraint description from plan.md]"
+      - **Constraint grounding** ⚠️: the constraint description MUST be one that **exists in plan.md's Critical Constraints** at generation time — a constraint cited from memory becomes an untraceable ghost requirement (same discipline as the Task Generation Rules' constraint-citation grounding)
+      - **Location grounding**: the example Locations above are ILLUSTRATIVE — every generated task's Location must point to the project's REAL test source set (apply the j-4 Location grounding rules)
+
+      **Validation**: All architecture patterns, layers, interactions, and constraints have corresponding tasks; **none of these tasks carries a `(FR-xxx)` annotation** (they are Foundational, not User-Story work).
+
+   j. **Apply test coverage requirements by risk level** 🧪 [NEW - Risk-Based Quality Assurance]:
+      **Purpose**: Apply code test coverage requirements based on plan.md Quality Targets (which derive from Constitution Article IV)
+
+      **⚠️ CRITICAL DISTINCTION**:
+      - **High-Level Test Coverage** (integration / component E2E / app E2E): Planned via `/specpro-test-plan` in `specs/test-tasks.md` - NOT generated in tasks.md
+      - **Code Test Coverage** (this step): Line/branch coverage percentage for code modules (varies by risk level and project type)
+      - These are **different metrics** for different quality dimensions
+
+      **j-1. Read Quality Targets from plan.md** ⚠️ [DO NOT HARDCODE]:
+      Read from plan.md Section "Quality Targets" → "Risk-Based Coverage Targets" table:
+      - **Project Type**: Check project type classification (MVP/Personal/Enterprise/Platform/Financial)
+      - **Coverage Targets Table**: Extract coverage percentages for each risk level
+      - **Example for Platform Application**:
+        * HIGH-RISK → >90% coverage (from plan.md table)
+        * MEDIUM-RISK → >70% coverage (from plan.md table)
+        * LOW-RISK → Optional (from plan.md table)
+
+      **⚠️ DO NOT hardcode coverage percentages** in tasks instruction!
+      - Coverage targets are **project-specific** and defined in plan.md
+      - Different project types have different coverage requirements
+      - Always read from plan.md Quality Targets section
+
+      **j-1a. If that table carries NO numeric target** (`T250` / `ISS-226`) — read this before step `j-3`:
+      ⚠️ **The table can legitimately hold something other than a percentage.** A project whose deliverable is not measurable code (pure text · no build artifacts · no executable) MUST NOT be given a number it cannot verify; its constitution says so and that table carries the **replacement standard** instead (clause ids, a named manual procedure — whatever that project chose).
+      When the three cells are not numbers:
+      - **MUST follow the standard the table actually states** — it is the project's quality target, and it is binding exactly as a percentage would be.
+      - **MUST state it explicitly** in the generated material: *"this project does not use coverage percentages as its standard — see `plan.md` → Quality Targets"*, quoting the table's own wording.
+      - **MUST NOT emit a `>XX%` placeholder** anywhere (task annotations, `[Quality]` task titles, `Purpose` lines, the `#### Quality Checkpoints` block) — a threshold nobody can compute is the *"unverifiable declaration"* such a constitution forbids, and it **reads exactly like a real threshold**.
+      - **MUST NOT stay silent about the item either** — dropping it without a word is the other way to make "no target" indistinguishable from "not checked".
+      **判据（可跑）**：产出的 `tasks.md` 里**不出现 `XX%`**，且**出现**上面那句明确陈述。
+      ⚠️ **This is not the same case as "no table at all"**: `/specpro-implement` §14 already covers *"no targets defined anywhere"*. Here the target **exists** — it is simply not a percentage.
+
+      **j-2. Determine FR risk level from `Quality Targets → Risk Classification`** —— ⚠️ **不是 `Constitution Check`**（`T232` ②）：后者住在 `plan-overview.md`、且 `plan.md §5.3.f` **明令**那张逐 FR 风险表**不得放在那里**（它是 `tasks` 的**机器输入**，必须与覆盖率表同处 Part I）。本标题此前把读者指向一个被禁止的落点。:
+      For each FR, check its risk classification in plan.md Section "Quality Targets" → "Risk Classification":
+      - **HIGH-RISK Modules**: Protocol implementations, cryptography, network transport, critical data operations
+      - **MEDIUM-RISK Modules**: Business logic, data models, platform API bindings
+      - **LOW-RISK Modules**: UI components, utilities, helpers
+
+      **j-3. Annotate implementation tasks with risk level**:
+      For each FR implementation task generated in previous steps:
+      - **HIGH-RISK FRs** → Add annotation: `(HIGH-RISK - Test-First required, >XX% coverage per plan.md Quality Targets)`
+      - **MEDIUM-RISK FRs** → Add annotation: `(MEDIUM-RISK - Test-First recommended, >XX% coverage per plan.md Quality Targets)`
+      - **LOW-RISK FRs** → No test requirement annotation (optional tests allowed)
+      - **Example** (for Platform Application with >90% target):
+        ```
+        - [ ] T-xxx [P] [US1] [S1,S2,S5] Implement plugin hot-reload support (FR-xxx)
+          (HIGH-RISK - Test-First required, >90% coverage per plan.md Quality Targets)
+        ```
+
+      **j-4. Generate test tasks based on risk level and project type**:
+      For each FR that requires testing, generate test tasks with **project-specific coverage targets**:
+
+      **Unit test task template** (replace XX% with actual target from plan.md):
+      ```markdown
+      - [ ] TXXX [Quality] [US#] Unit tests (>XX% coverage per plan.md Quality Targets) for [FR title]
+        ⚠️ **不带 `[S#]` 场景标签**（T173）：本节下方「**No scenario labels on task lines**」已把那个机制
+        **明令退役**，而本模板此前仍带着它 —— **同一份文档里一处禁止、另一处示范**。场景→覆盖的追溯
+        现在在 `/specpro-test-plan` 的 `specs/test-tasks.md` 矩阵里。
+        Location: [REAL unit-test source set of the module under test — from plan.md project structure / build config / existing sibling tests, e.g. tests/core-test/src/jvmTest/kotlin/.../[Feature]Test.kt]
+        Purpose: Achieve >XX% line/branch coverage for [risk-level] modules
+      ```
+      **Location grounding ⚠️** [prevents imagined paths]:
+      - NEVER invent `tests/unit/` or similar placeholder paths — Location MUST be the project's actual unit-test source set, verified against plan.md project structure, build config sourceSets, or existing sibling test files
+      - If the target module has NO unit-test source set yet → the task must explicitly create/register it first (state this in the task), or record an issue
+      - **Integration / E2E test tasks are NOT generated here** — they belong to `/specpro-test-plan` (specs/test-tasks.md). tasks.md generates unit-test tasks ONLY (four-layer test ownership)
+
+      **Coverage Target Substitution** (from plan.md Quality Targets):
+      - **HIGH-RISK FRs**: Substitute XX% with target from plan.md (e.g., >90% for Platform, >95% for Financial)
+      - **MEDIUM-RISK FRs**: Substitute XX% with target from plan.md (e.g., >70% for Platform, >80% for Financial)
+      - **LOW-RISK FRs**: Use "(optional)" instead of percentage
+
+      ⚠️ **j-5 was REMOVED — this step no longer produces a `#### Quality Checkpoints` block** (`T232` ③):
+      - **No reader**: `grep -rn 'Quality Checkpoints' commands/ templates/` returned the producer and nothing else — and this repository's own `tasks.md` carries **0** such blocks, i.e. it was never even generated here. A checklist nobody reads is the shape this repository keeps removing, and `plan.md` §5.6b's standing ruling on the sibling section is *"**No checkboxes**"* — this is the same call.
+      - **What replaces it**: the per-phase coverage obligations are already carried by (a) each `[Quality]` task's own `Purpose:` line, and (b) `/specpro-implement` §14, which compares **per module** against the thresholds. A phase-level aggregate checkbox added a third, weaker copy.
+      ⚠️ **Do not re-add it.** If a phase-level roll-up is ever genuinely needed, it must arrive with a named reader in the same change.
+      **Implementation Notes**:
+      - Code test coverage is measured by tools like JaCoCo (line/branch coverage percentage)
+      - Scenario automation is measured by counting scenarios with automated tests (different metric)
+      - Both dimensions are important: scenario coverage ensures feature validation, code coverage ensures implementation quality
+      - Risk-based approach ensures testing effort is proportional to module criticality
+      - **Project-specific**: Coverage targets vary by project type (MVP < Personal < Enterprise < Platform < Financial)
+
+   k. **Generate database evolution tasks** 🗄️ [NEW - Schema Evolution]:
+      **Purpose**: Generate tasks for database schema evolution (V2, V3... migrations) when entities change
+
+      **⚠️ TERMINOLOGY**: Use "Schema Evolution" NOT "database migration"
+      - ✅ **Schema Evolution**: Modifying database schema within SAME system (ALTER TABLE ADD COLUMN, etc.)
+      - ✅ **Data Migration**: Moving data from ONE database system to ANOTHER (Oracle → PostgreSQL)
+      - ❌ **DO NOT use "database migration"** for adding fields → Use "schema evolution" instead
+
+      **k-1. Detect database requirement**:
+      Read plan.md Technical Context → Storage:
+      - IF Storage contains "SQLDelight" OR "SQLite" OR "PostgreSQL" OR "MySQL":
+        → Database required, proceed to Step k-2
+      - ELSE:
+        → Skip this step (no database needed)
+
+      **k-2. Check for schema evolution requirements**:
+      Read data-model.md Section "Entity Changes" (if present):
+      - IF section exists AND has "Updated Entities":
+        → Schema evolution required, proceed to Step k-3
+      - ELSE:
+        → Only initial schema needed, skip to Step k-7
+
+      **k-3. Generate schema evolution tasks for each changed entity**:
+      For each entity in "Updated Entities" list:
+      1. **Detect change type**:
+         - 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 → Generate "CREATE TABLE" migration
+         - DROPPED table → Generate "DROP TABLE" migration
+
+      2. **Generate schema evolution tasks**:
+         Task template:
+         ```markdown
+         - [ ] TXXX [DB] {[US#] + (FR-XXX) —— 仅当本组落在**某个 User Story 阶段**时} Create V{N}__{Description}.sq schema evolution migration
+           Purpose: [Explanation of change: Add/remove/rename field or table]
+           Change type: [ALTER TABLE ADD COLUMN | DROP COLUMN | RENAME COLUMN | CREATE TABLE | DROP TABLE]
+           Migration file: shared/commonMain/sqldelight/com/example/db/migrations/V{N}__{Description}.sq
+           SQL:
+           ```sql
+           -- V{N}__{Description}
+           -- Generated: [DATE]
+           -- Purpose: [Explanation]
+
+           [SQL statement - e.g., ALTER TABLE plugin ADD COLUMN author TEXT;]
+           ```
+           Related entity: [EntityName]
+           Previous version: V{N-1}
+           New version: V{N}
+           Breaking change: [yes/no]
+         ```
+
+      3. **Generate .sq file update task**:
+         ```markdown
+         - [ ] TXXX [DB] [US#] Update [EntityName].sq with new schema (FR-XXX)
+           File: shared/commonMain/sqldelight/com/example/db/[EntityName].sq
+           Changes:
+           - [List changes: Added field X, renamed field Y, etc.]
+           Verify: SQL syntax, foreign keys, indexes
+         ```
+
+      4. **Generate DAO update task** (if applicable):
+         ```markdown
+         - [ ] TXXX [DB] [US#] Update [EntityName]Dao for new schema (FR-XXX)
+           File: shared/commonMain/src/[package]/dao/[EntityName]Dao.kt
+           Changes:
+           - Add [newField] to INSERT query
+           - Add [newField] to UPDATE query
+           - Update SELECT queries if needed
+           Test: Verify DAO compiles with new schema
+         ```
+
+      5. **Generate migration test task**:
+         ```markdown
+         - [ ] TXXX [DB] {[US#] + (FR-XXX) —— 仅当落在 User Story 阶段时} Test V{N} schema evolution migration
+           File: shared/commonTest/src/[package]/migration/V{N}MigrationTest.kt
+           Test cases:
+           - [ ] Verify migration applies without errors
+           - [ ] Verify existing data preserved
+           - [ ] Verify new column has correct default value (if applicable)
+           - [ ] Verify foreign key constraints maintained
+           - [ ] Verify indexes created/dropped correctly
+         ```
+
+      **k-4. Organize schema evolution tasks by migration version**:
+      Group tasks by migration version (V2, V3, V4...):
+      - V2 tasks must complete before V3 tasks can start
+      - Each version: Create migration file → Update .sq file → Update DAO → Test migration
+      - Add version dependencies in task descriptions
+
+      **k-5. Add schema evolution to Phase 2 (Foundational) or appropriate User Story phase**:
+      ⚠️ **阶段决定注解，注解不得写死**（T173 / audit finding：「放到 Foundational 阶段的 schema 任务，
+      该不该带 `(FR-XXX)` 与 `[US#]`」）：本节上面的模板此前**逐条写死**了 `[US#]` 与 `(FR-XXX)`，
+      而**格式规则明写 Foundational 阶段两者都不带** —— 照模板生成、再按本节把它放进 Phase 2，
+      产出的就是一条**违反格式规则**的任务。⇒ **判据**：落在 **Phase 2（Foundational）** ⇒
+      **两个都不带**，用 `[DB]` 与描述锚定；落在**某个 User Story 阶段** ⇒ **两个都带**。
+      - IF schema evolution affects ALL entities (e.g., global change):
+        * Add to Phase 2 (Foundational tasks)
+      - ELSE IF schema evolution affects specific User Story entities:
+        * Add to affected User Story phase
+      - Mark with [DB] priority tag
+      - Place schema evolution tasks BEFORE entity implementation tasks
+        (schema must be updated before entity code can use new fields)
+
+      **k-6. Verify schema evolution task completeness**:
+      For each changed entity:
+      - [ ] Migration file creation task generated (V{N}__*)
+      - [ ] .sq file update task generated
+      - [ ] DAO update task generated (if DAO exists)
+      - [ ] Migration test task generated
+      - [ ] Tasks ordered correctly (migration → .sq → DAO → test)
+      - [ ] Dependencies set correctly (V2 before V3)
+
+      **k-7. Initial schema tasks** (if no schema evolution required):
+      If data-model.md has no "Entity Changes" section (initial specification):
+      Generate initial database setup tasks:
+      ```markdown
+      - [ ] TXXX [DB] [P0] Generate initial database schema files (.sq) from data-model.md (FR-XXX)
+        Purpose: Create the schema files for all entities using the project's database framework
+        Output: shared/commonMain/sqldelight/com/example/db/*.sq
+        Entities: [List entities from data-model.md]
+        Verify: All entities have .sq files, foreign keys valid, indexes created
+
+      - [ ] TXXX [DB] [P0] Create V1__InitialSchema.sq migration file (FR-XXX)
+        File: shared/commonMain/sqldelight/com/example/db/migrations/V1__InitialSchema.sq
+        Content: CREATE TABLE statements for all entities, indexes, foreign keys
+        Verify: SQL syntax, valid schema
+
+      - [ ] TXXX [DB] [P0] Setup database driver and connection (FR-XXX)
+        File: shared/commonMain/src/[package]/db/DatabaseFactory.kt
+        Driver: [e.g., SQLDelight driver, Android SQLite driver]
+        Verify: Database file created, connection successful
+
+      - [ ] TXXX [DB] [P0] Test initial database setup (FR-XXX)
+        File: shared/commonTest/src/[package]/db/DatabaseSetupTest.kt
+        Test cases:
+        - [ ] Verify database file created
+        - [ ] Verify all tables created
+        - [ ] Verify foreign key constraints enforced
+        - [ ] Verify indexes exist
+      ```
+
+      **k-8. Add database terminology documentation task**:
+      ```markdown
+      - [ ] TXXX [DB] [P0] Document database schema evolution workflow
+        File: docs/database-evolution.md
+        Content:
+        - How to add new field (modify entity → run plan → generate V2 migration)
+        - How to rename column (modify entity → run plan → generate V2 migration)
+        - How to verify migration (test cases, manual verification)
+        - Database Evolution vs Data Migration terminology explanation
+        Purpose: Ensure team uses consistent terminology
+      ```
+
+      **Validation**:
+      - All changed entities have corresponding schema evolution tasks
+      - Tasks follow correct order (migration → .sq → DAO → test)
+      - Tasks marked with [DB] priority tag
+      - Terminology correct: "Schema Evolution" NOT "database migration"
+      - Migration versions numbered correctly (V2, V3, V4...)
+
+   l. **Generate dependency graph** showing user story completion order
+
+   m. **Create parallel execution examples** per user story
+
+   n. **Validate task completeness** (each user story has all needed tasks, independently testable)
+
+5. **Generate tasks.md** 📋 [6/7]: Use `.specpro/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - **CHECK TasksStatus for each FR before generating tasks** 📋 [CRITICAL]:
+     * If FR.TasksStatus = "processed" → SKIP (do not generate/update tasks for this FR)
+     * If FR.TasksStatus = "deprecated" → SKIP (already removed in previous iteration)
+     * If FR.TasksStatus = "create", "update", or "delete" → GENERATE/UPDATE tasks for this FR
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+     - **ONLY include FRs filtered in Step 3.e and Step 4.d**
+     - If US has no FRs needing updates, skip this US phase entirely
+   - **For each User Story phase** 🆕:
+     * **Copy Independent Test** from spec.md (verbatim)
+     * **List Acceptance Scenarios Summary**:
+       - Total scenarios: X
+       - Breakdown: Happy (Y), Error (Z), Edge (W), Permission (V)
+     * **No scenario labels on task lines** ⚠️ [settled 2026-09-13]: the per-task scenario-label mechanism (`[S1,S3,S4,S7]`) and the `scenario-coverage.md` mapping it depended on **were retired** with the scenario-system restructure — **the "verbatim copy" idea behind them was inherited by the `/specpro-test-plan` system**, which is where scenario→coverage traceability now lives (`specs/test-tasks.md` matrix). The labels had no consumer on the task side: nothing reads them. Do NOT re-add them, and do NOT reference `specs/scenario-coverage.md` — **that file has no producer and no consumer**, so a pointer to it is a dead link.
+   - **High-level tests (integration / component E2E / app E2E)**: NOT in tasks.md - planned by `/specpro-test-plan` into `specs/test-tasks.md`, executed by `/specpro-test-implement`
+   - **MARK completed tasks** from previous iterations:
+     * If regenerating a modified FR, preserve completed tasks from other FRs as [x]
+     * Only add new/modified tasks for the specific FR being updated as [ ]
+     * Mark deleted FR tasks with [DELETED] and remove in next pass
+   - **PRESERVE the FRs you did NOT process** ⚠️ [settled 2026-09-13]: the filter above (`ONLY include FRs filtered`) governs **which FRs get (re)generated** — it does NOT say the un-filtered ones should disappear. Tasks belonging to FRs whose `tasksStatus = "processed"` are carried over **verbatim** into the new file. Concretely: **`tasks.md` is merged, never regenerated** — dropping the un-filtered FRs would silently delete the entire task history of a mature project (a run in which every FR is `processed` filters to an EMPTY set, and an overwrite would leave an empty file). The same rule as everywhere else: absent → initial, present → incremental.
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format with FR annotations (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+6. **Update Lifecycle fields after task generation** 📋 [7/7]:
+
+   a. **Update spec.md with new TasksStatus** for FRs 📋 [CRITICAL]:
+      - For each processed **FR** (from Step 3.d filtered list and Step 4.d):
+         * **If FR.SpecStatus IN ("create", "update")**:
+           - Update FR.TasksStatus to "processed"
+           - Format: `**Lifecycle**: [specify:<status>][plan:<status>][tasks:processed]`
+           - FR.SpecStatus and FR.PlanStatus preserved
+         * **If FR.SpecStatus = "delete"**（⚠️ 本条与 `plan.md` 的同一分支的关系，T173 已厘清）:
+           - ⚠️ **触发看的是上游写下的那个标记**：`/specpro-plan` 在它的 `6.a` 里把这类条目的 `tasks` 段写成
+             **`delete`** 并注明「**Keep delete until Tasks processes it**」 —— **那是一个移交标记，不是终态**。
+             本节此前写的是「Ensure TasksStatus = "deprecated"」，**跳过了"处理"这一步就直接写终态**：
+             两处对同一件事给出相反的取值，且**产出的 `Lifecycle` 字符串不同**（`[tasks:delete]` vs `[tasks:deprecated]`）。
+           - **本阶段是链路末端**，所以顺序是：① **先做**——`Remove all tasks for this FR from tasks.md`；
+             ② **再写终态**——`FR.TasksStatus = "deprecated"`。
+           - Lifecycle 终值：`**Lifecycle**: [specify:delete][plan:deprecated][tasks:deprecated]`
+             （⚠️ **中途那一格 `[tasks:delete]` 由 plan 写、由本阶段消费**；两者是**同一件事的两个时刻**，
+             不是一个事实的两个来源）
+
+      - **NOTE**: User Story TasksStatus is NOT automatically updated when individual FRs are processed
+        * US.TasksStatus updates only when ALL FRs in that US are processed
+        * OR when US itself is modified (US.SpecStatus = "update")
+        * This enables FR-level incremental updates
+
+   b. **Write updated spec.md**:
+      - Update Lifecycle fields for all processed FRs
+      - Check if all FRs in a US are processed → update US.TasksStatus
+      - Preserve all other spec content
+      - Atomic write (overwrite entire file)
+
+   c. **Handle deprecated items in tasks.md**:
+      - Remove all task sections related to deprecated items
+      - Examples:
+         * Remove entire User Story phase for deprecated US
+         * Remove tasks for deprecated FRs
+         * Update dependency graph to remove deprecated items
+      - Add deprecation notice if needed:
+        ```markdown
+        ## Deprecated Items
+
+        The following items were deprecated and have been removed from tasks:
+        - FR-XXX: [Title] (deprecated in spec v0.X)
+        - USY: [Title] (deprecated in spec v0.X)
+        ```
+
+7. **Report & Next Steps** ✨ ENHANCED (Clear user guidance):
+
+**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` and `plan` — pending means an entry's `[tasks: ]` marker
+is not `processed`, or a `[plan]`-side design decision is not yet reflected here.
+
+
+   **7.1 Generated Artifacts Report** ✨ NEW:
+
+   ```markdown
+   ## ✅ Task Generation Complete
+
+   **Tasks File**: specs/tasks.md
+
+   **Generated Tasks**: N tasks (X new, Y preserved, Z removed)
+   - **New tasks**: X (from new/modified items)
+   - **Preserved tasks**: Y (from previous iterations)
+   - **Removed tasks**: Z (from deprecated items)
+
+   **FR-Level Processing**:
+   - **Total FRs**: M
+   - **FRs processed**: A (create/update/delete)
+   - **FRs skipped**: B (already processed)
+   - **FRs deprecated**: C (removed)
+   - **User Stories with partial FR updates**: D (US already processed, but individual FRs updated)
+
+   **Lifecycle Processing**:
+   - **New items**: A (tasksStatus = "create" → Processed)
+   - **Modified items**: B (tasksStatus = "update" → Processed)
+   - **Deprecated items**: C (removed from tasks.md)
+   - **Skipping**: D (already Processed, preserved)
+
+   **Quality Tasks Created** (if any):
+   - T0XX: [Quality][P0] Fix [issue] (from `✗ Failed`)
+   - T0YY: [Quality][P1] Address [issue] (from `✗ Failed`)
+   ⚠️ **`❌ FAIL` 与 `⚠️ WARNING` 都不是清单能产的取值**（`2.5.b` 明令不要按它们找）：这里此前把它们当成任务的**来源标注**印在示例里 —— 而示例是被照抄的（`TOOL-009`），下一个照它写的人会去找一个不存在的档。**能产的只有 `✗ Failed`**（`⊘ Skipped` 不生成任务）。
+
+   **Parallel Opportunities**: M tasks can run in parallel
+   **MVP Scope**: P1 User Stories (recommended for first iteration)
+   ```
+
+   **7.2 Next Options** ✨ NEW (CLEAR USER GUIDANCE):
+
+   ```markdown
+   Your task breakdown is complete! Choose your next action:
+
+   ### Option 1: Start Implementation (Recommended) ⚡
+   Execute tasks in dependency order, beginning with Phase 1.
+
+   ```bash
+   /specpro-implement
+   ```
+
+   **What this does**:
+   - Execute tasks in phases (Setup → Foundational → User Stories → Polish)
+   - Update task checkboxes as progress
+   - Provide real-time progress tracking
+   - Suitable for: All projects, ready to code
+
+   **Estimated time**: 2-6 hours (depending on project scope)
+
+   ---
+
+   ### Option 2: Review & Adjust Tasks (Manual) 🔍
+   Review generated tasks before proceeding.
+
+   ```bash
+   # Review the task breakdown
+   cat specs/tasks.md
+
+   # Check specific phases
+   grep -A 20 "## Phase 1" specs/tasks.md
+   grep -A 20 "## Phase 2" specs/tasks.md
+   ```
+
+   **After review**:
+   - If satisfied: Choose Option 1 to start implementation
+   - If adjustments needed: Edit tasks.md manually, then proceed
+
+   **Estimated time**: 5-15 minutes (depending on depth of review)
+
+   ---
+
+   ### Option 3: Update Plan First (Optional) 📐
+   Regenerate plan with detailed Phase 2-7 breakdown before tasks.
+
+   ```bash
+   /specpro-plan --continue
+   ```
+
+   **What this does**:
+   - Generate detailed implementation plan (Phase 2-7)
+   - Expand milestones and timeline
+   - Add risk management strategies
+   - Suitable for: Large projects, team coordination
+
+   **Estimated time**: 5-10 minutes, then return to tasks
+
+   ---
+
+   ### Recommended Path 🎯
+
+   Based on your task breakdown:
+   - **Total Tasks**: N (X new, Y preserved)
+   - **Complexity**: [Low/Medium/High] (based on task count and dependencies)
+   - **Parallel Opportunities**: M tasks can run simultaneously
+
+   **Recommended**:
+   ```
+   1. Quick review (Option 2) - 5 minutes
+      → Verify task breakdown looks correct
+      → Check critical path and dependencies
+
+   2. Start implementation (Option 1) - Begin coding
+      → /specpro-implement
+      → Execute Phase 1 (Setup) first
+      → Continue through phases incrementally
+   ```
+
+   **Total estimated time to code**: [X hours] (based on task count)
+   ```
+
+   **7.3 Execution Time Summary** ✨ NEW:
+
+   ```markdown
+   **Command**: /specpro-tasks
+   **Duration**: [Time taken]
+   **Items Processed**: [N new/modified, M skipped]
+   **Tasks Generated**: [X new, Y preserved]
+
+   **Performance Breakdown**:
+   - Load documents: [time]
+   - Quality checks: [time]
+   - Lifecycle parsing: [time]
+   - Task generation: [time]
+   - Write files: [time]
+   ```
+
+   **Benefits**:
+   - ✅ Clear next steps guidance (3 options)
+   - ✅ Recommended path (based on project scale)
+   - ✅ Observable execution time
+   - ✅ Prevent user confusion (explicit next steps)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## High-Level Testing (Out of Scope for tasks.md)
+
+High-level tests (integration / component E2E / app E2E) are OUT of tasks.md scope: planned by `/specpro-test-plan` (artifact `specs/test-tasks.md`: coverage matrix + INF/IT/CE/AE test tasks) and executed by `/specpro-test-implement`.
+
+Unit tests remain in tasks.md scope (see Step 4.j and `[Quality]` tasks). Manual acceptance is owned by `/specpro-manual-test`.
+
+---
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+
+**Phase 1-5 Tests**: Only generate if explicitly requested (legacy behavior).
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+6. **[FR-XXX] annotation**: REQUIRED for all tasks derived from functional requirements
+   - Format: Task description followed by `(FR-XXX)` at the end
+   - Setup phase: NO FR annotation (infrastructure tasks)
+   - Foundational phase: NO FR annotation (shared tasks)
+   - User Story phases: MUST have FR annotation for each task
+   - Polish phase: NO FR annotation (cross-cutting tasks)
+   - **CRITICAL**: This enables FR-level incremental task updates
+7. **Constraint citation grounding** [CRITICAL]: when a task description cites a constraint or platform limitation ("per <X>", "requires <X>", "view-only per <X>"), the cited source MUST exist in spec.md / constitution.md / plan.md at generation time — NEVER cite constraints from memory or hearsay. If the constraint is real but unwritten, first register it in the spec (clarify/specify), then reference it by ID; uncited-name constraints become untraceable ghost requirements downstream
+8. **Location coverage — the acceptance evidence's landing point** [CRITICAL] [settled 2026-09-19]: a Location is chosen by asking *where does the implementation body land*, which is a **different question** from *where does this task's acceptance evidence land*. The two can be disjoint — and then the generated task **cannot be completed as written**: it mandates evidence it has nowhere to put. This is the **existence** half's sibling (the Location-grounding rule: never invent placeholder paths); this one is the **coverage** half.
+   - **The check** ⚠️: if completing the task requires evidence to be **created or registered** (a new case, a new fixture, a new regression row), that evidence's landing point MUST also be in the Location. ⚠️ **Re-running evidence that already exists does not widen it** — a grep over a file already named, or a re-run of an already-registered check, writes nothing new. Only obligations this task must **place** count. Without that clause the rule catches everything and therefore decides nothing.
+   - **What counts as a landing point** — state the criterion, not just its known forms: **a place where this project stores acceptance evidence and something reads it back**. The qualifier carries the weight: *"this project stores"* excludes imagined paths (the same discipline as the Location-grounding rule), and *"something reads it back"* excludes a file that merely mentions the evidence. Known forms: a **test file** · a **fixture tree** (the case files *and* the runner that reads them) · a **regression table in a contract** — that last one **only when the contract is bound to the unit under test**; naming a similarly-named contract because the right one is missing is the symptom, not the fix. ⚠️ **The three are a sample of what the criterion admits, not the criterion** — an enumeration narrower than the distribution is this repository's most-repeated defect, so a fourth form gets **added here** when it appears, never bent to fit one of the three.
+   - **How to apply it** (per generated task, once the description is written): list the task's acceptance obligations → for each, name where the evidence must live → assert every one of those is in the Location. A task whose evidence has no home yet has a **Location gap**; the fix is to **widen the Location**, never to soften the obligation. ⚠️ **Both bounds are part of the check, not just the first**: take only obligations the task must **discharge to be accepted** — a side effect it also performs (registering a finding in the ledger, updating a log, citing a file) is **not** one. Reading the rule as "name every file the task touches" inflates every Location and makes the field useless; reading it as "the body's path is enough" produces tasks that cannot be completed. The check is the pair.
+   - ⚠️ **This is a rule, not a roster.** Do not maintain a list of tasks that missed it: the Locations already carry that fact, and a second copy of it drifts.
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py (FR-xxx)`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py (FR-xxx)`
+- ❌ WRONG: `- [ ] Create User model` (missing ID, Story label, and FR annotation)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox and FR annotation)
+- ❌ WRONG: `- [ ] [US1] Create User model (FR-xxx)` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path and FR annotation)
+
+### Task Organization
+
+1. **From Functional Requirements (FRs)** - PRIMARY GENERATION SOURCE 📋 [CRITICAL]:
+   - **Each FR generates one or more tasks based on its requirements**
+   - Group tasks by parent User Story for phase organization
+   - Every task MUST be annotated with its source FR: `(FR-XXX)`
+   - Mark FR dependencies (some FRs depend on other FRs)
+   - **FR TasksStatus drives incremental updates**: Only generate/update tasks for FRs with tasksStatus = "create" or "update"
+
+2. **From User Stories** - PHASE ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Organize FR-derived tasks into their parent US phases
+   - Each phase title: "## Phase X: User Story Y - [Title] (Priority: P#)"
+   - Each subsection title: "### [Feature Name] (FR-XXX through FR-YYY)"
+   - Mark story dependencies (most stories should be independent)
+
+3. **From Contracts**:
+   - Map each contract/endpoint → to the user story it serves
+   - Contract-conformance testing is NOT generated here — mock-based contract verification belongs to the Integration layer of `/specpro-test-plan` (four-layer test ownership; contract-test assets are registered in the coverage matrix as IT-layer coverage)
+
+4. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+5. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+
+---
+
+## 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/T5 (a byte stream to encode/decode, or tests asserting on raw bytes). Consume the verdict recorded upstream (§6.4); do not re-judge it. When activated, task generation MUST produce the systematic four-part test matrix — not a single test task — and MUST carry forward every GAP row from the plan-layer inventory as an explicit task or an explicit deferral.
+
+- **The four-part matrix** (each protocol point from the plan-layer inventory maps to coverage):
+  1. **Decode matrix**: message/tile type × full-frame vs incremental context × parameters — assert byte-by-byte or pixel-by-pixel.
+  2. **Encode reverse matrix**: `encoder(pixels) → bytes` compared against the golden anchor, byte by byte.
+  3. **Shared golden-bytes fixture**: all anchors constructed in one place, shared by the encoder and decoder matrices.
+  4. **Property-test extension**: randomized content / length / combinations, fixed seed, with a failure output that reproduces the failing parameters.
+- **Matrix inputs are built from anchored golden bytes — never from the implementation under test.** Deriving the input byte stream from the implementation's own parse semantics is a behaviour lock, not a protocol test: it mirrors the implementation's reading of the format back as "correct", so any misreading is baked into the fixture and every assertion passes by construction. Anchor both directions — the input bytes (§2) and the expected output — or record the row as a GAP (§6.3). A protocol point with no reachable anchor becomes an explicit GAP row, not a silently absent one.
+- Extension-chain boundary values — continuation markers, maximum-length encodings — MUST be specified as **byte-level examples** (see guide §1), never by prose name: "skip the marker" and "accumulate the marker" describe different streams. Runs whose length lands exactly on a marker boundary MUST have a case.
+- **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) in the matrix tasks. "Unspecified" is not an answer; it is the shape of the next latent defect — an undecided skip-and-continue path is exactly such a case.
+