specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.implement.md

@@ -0,0 +1,1881 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+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: <product code paths named by each task Location>
+    unit: "the files each task names, up to and including that task's whole deliverable"
+  - artifact: .gitignore / .prettierignore / .npmignore / .terraformignore / .helmignore
+    unit: "whole file when missing; otherwise only the missing critical patterns are appended"
+  - artifact: specs/tasks.md
+    unit: "the executed task lines -> checkbox [ ] -> [x]"
+  - artifact: specs/research.md
+    unit: "appended ## Addendum (<task-id>, <date>) sections - implementation findings"
+  - artifact: specs/implement_issues.md
+    unit: "new ISS-NNN entries in the owning section; the statistics table (**its own row only** — seven commands declare this artifact). ⚠️ **Marking another section's entries `[x]` is NOT in this unit** (T233/ISS-206): `specs/contracts/ledger.md` → Write boundary reads *「标记（`[x]`）= **限于本分区**」* and *「**登记方从不标记他方条目**——承接方是该分区条目的唯一勾选方」*, and it lists this command's write as *'new ISS-NNN entries in the owning section'* alone. The `[tasks]` section is consumed — and therefore marked — by `/specpro-tasks --review-issues` (§ the `--review-issues` entry above)."
+  - artifact: specs/fix-tasks.md
+    unit: "FT-XXX checkbox plus diagnostic notes - never test-task checkboxes; **not** the evidence or the PASS verdict, which are /specpro-test-implement's"
+  - artifact: docs/implement/**
+    unit: "the whole document set: PROJECT_NAVIGATION.md, {topic}/index.md, per-topic work documents and their reverse indexes"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — writes product code and process docs, not design artifacts** ⚠️ [settled 2026-09-13]:
+
+This command **produces no design artifact**. It executes tasks from `tasks.md`, writing product code and the process documents those tasks require. The shared rerun rule (*detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent*) governs the commands that produce design artifacts — `specify`, `plan`, `tasks`, `test-plan` and the rest.
+
+**Progress is carried by the task list, not by regeneration.** Tasks already marked complete are never redone: a re-run resumes from the first unfinished task, and the task list's own incremental semantics (unmodified entries preserved verbatim) do the work the detection check does elsewhere. Resetting a completion state requires the same explicit, re-confirmed intent that overwriting an artifact requires.
+
+> **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. **This command writes no design artifact, so it never triggers the rule's third clause** — its guard against lost work is the task list's completion state, which is likewise never reset silently.
+
+**Execution Mode Selection** (Interactive):
+- If NO arguments provided: Show interactive mode selection menu
+- If arguments provided: Parse and execute directly (skip menu)
+
+**Supported arguments**:
+- `--once`: Execute only one task, then exit
+- `--count N`: Execute N tasks, then exit
+- `--phase PHASE`: Execute all tasks in specific phase
+- `--continue`: Execute all tasks (⚠️ WARNING: Context overflow risk)
+- `--review-issues`: **skip the question** — the `[tasks]` queue is known to be non-empty, proceed with the normal run. ⚠️ **This flag does NOT process that queue** (T172): the `[tasks]` section is owned by `/specpro-tasks --review-issues`, which is the only party that marks its entries `[x]`. This command never writes `specs/tasks.md`.
+- `--fix-defects`: **skip the question and process the pending `FT-xxx` fix tasks** directly (product-code fixes — see below). *(Renamed from `--fix-issues`, settled 2026-09-13: `fix` now unambiguously means product code, `review` means upstream artifacts. The old name was undefined in every command and meant two different things depending on who received it — TOOL-008.)*
+
+**Two pending sets, both detected on every run** ⚠️ [settled 2026-09-13]:
+
+This command has **two independent queues**. Neither is opted into by a flag — a flag only means "I already know, don't ask".
+
+| Queue | Where | What the fix touches — **and who applies it** |
+|-------|-------|--------------------|
+| **Upstream-artifact issues** | the `[tasks]` section of `specs/implement_issues.md` | `specs/tasks.md` — **and the fix is applied by `/specpro-tasks --review-issues`, not by this command**: that command both updates the file and marks the entry `[x]`. This command touches **neither** (`T156` / `ISS-79`: this row used to leave the applier unnamed, and read as *"this command does it"* — while `writes:` declares for `specs/tasks.md` **only** the checkbox of an executed task line). |
+| **Product defects** | pending `[ ]` **FT-xxx** in `specs/fix-tasks.md` | **product code** |
+
+**On every run, before any normal work, check BOTH.** Then:
+
+| Situation | Behaviour |
+|-----------|-----------|
+| Both empty | Proceed with the normal run. **No prompt.** |
+| Either non-empty | **Ask once, covering both** — "N pending items: `[tasks]`-section issues X · product defects (FT) Y. Process which first, or run normally?" The menu above already surfaces defects as option 1️⃣ (*Recommended when offered*); the rule here is that **the pending sets MUST be surfaced, not silently skipped.** |
+| `--review-issues` passed | Skip the question for the `[tasks]` queue. **The queue itself is still processed by `/specpro-tasks --review-issues`** — this flag only says "don't ask me again". |
+| `--fix-defects` passed | Skip the question for the FT queue; process it directly. |
+| Both passed | Skip both questions. |
+
+> **Why the flags are not switches** (the failure this replaces): the old semantics — flag = on, no flag = off — pushed the risk onto the user. *Not* passing one risked silently leaving that queue unprocessed; passing it risked overriding work the user meant to do in the normal mode. Neither was safe, and **which items were pending was invisible until the command ran**. **Detect-then-ask makes it an explicit choice; each flag is left doing only the one thing it is good at: saying "don't ask me again".**
+>
+> ⚠️ **History** (TOOL-008): `--fix-issues` was declared by no command, yet passed repeatedly by habit, and two commands *interpreted it differently* (here: execute FT; in `/specpro-test-plan`: process the `[test-plan]` section — which is what that command's `--review-issues` means, so the name was pure duplication). Anything the executor has to *guess* is neither reviewable nor reproducible.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Outline
+
+## Implement Responsibility Boundaries ⚖️ [CRITICAL]
+
+**Purpose**: Define what implement command MUST do vs. what it CAN decide freely
+
+**SDD Principle**: Specification-Driven Development requires strict separation between:
+- **Specification** (what to build): Defined by spec.md, plan.md, tasks.md
+- **Implementation** (how to build): Executed by implement command
+
+Implement command's job is to **execute specifications**, not to **make design decisions**.
+
+### Core Principles
+
+**1. Function and Flow: STRICT EXECUTION** ✅
+- **MUST**: Execute exactly what tasks.md specifies
+- **MUST NOT**: Add new features not in tasks.md
+- **MUST NOT**: Change design/specification
+- **MUST NOT**: Skip required functionality
+- **SDD rationale**: Features are specified in spec.md, designed in plan.md, broken down in tasks.md. Implement's job is to **execute**, not to **decide**.
+- **Examples**:
+  - ✅ Task: "Implement authentication module" → Implement authentication exactly
+  - ❌ Don't add: "and also authorization" (not in task)
+  - ✅ Task: "Create login form with email/password" → Create form with email/password
+  - ❌ Don't add: "and also social login" (not in task)
+
+**2. UI and Interaction: FREE DISCRETION** 🎨
+- **Layout**: Full freedom (positioning, spacing, alignment)
+- **Style**: Full freedom (colors, fonts, sizes, shapes)
+- **Interaction**: Full freedom (animations, transitions, feedback)
+- **Extra features**: OK to add (undo, batch operations, shortcuts)
+- **No recording needed**: Don't document UI/interaction decisions
+- **SDD rationale**: UI/implementation details are NOT specified in SDD workflow. They are implementation concerns that implement command can decide freely.
+- **Examples**:
+  - ✅ Task: "Create login form" → Choose any layout/style you want
+  - ✅ Task: "Add 'Delete' button" → Position it anywhere, use any color
+  - ✅ OK to add: Confirm dialog, undo operation, keyboard shortcuts
+  - ✅ No need to record: "Changed button from blue to green" or "Added animation"
+
+**3. Implementation-level technology choices: FREE, but MUST be recorded** 📝 (settled 2026-09-13)
+- **What this covers**: choosing *which* API / library / mechanism satisfies a requirement whose FR does not name one. Example: the FR says "platform cryptography APIs"; whether the iOS side uses `CommonCrypto` cinterop or `CryptoKit` is an implementation choice — the FR is satisfied either way.
+- **Why it is free**: the FR states WHAT, not HOW. Picking the mechanism is exactly the implement command's job.
+- **Why it MUST be recorded**: the choice had **alternatives**, and a future reader hitting the same decision will otherwise re-litigate it (or pick differently and silently diverge). The rejected alternatives are the valuable part — they are what stops the same evaluation being redone.
+- **WHERE — the location is fixed, not yours to pick** ⚠️: append to **`specs/research.md`**, under a heading of the form `## Addendum (<task-id>, <date>): <choice> — <alternative> vs <alternative>`. `research.md` is the artifact that carries *why*, and `plan.md`'s `### Architecture Patterns` already points at it with `See: research.md` anchors — so the reasoning lands where the design already says reasoning lives.
+  - **Do NOT** put it in `plan.md` (that records conclusions, not implementation findings — and this command MUST NOT modify plan.md), **do NOT** put it in `tasks.md` (it is not a task), and **do NOT** leave it only in a commit message or a `docs/implement/` note (neither is on the design's reference path).
+- **Trigger — record when BOTH hold**: (a) you selected a mechanism where a reasonable alternative existed, **and** (b) the selection is not derivable from the FR text alone. Routine choices with no real alternative (which data class field name, which collection type) do **not** trigger it.
+- **Minimum content**: what was chosen · what was rejected · why (with evidence, not assertion) · what was deferred or left unimplemented, and under what honest semantics.
+- **SDD rationale**: `plan.md` carries the design conclusion ("use platform crypto APIs"); `research.md` carries the argument for how that conclusion was realised. Keeping the argument there preserves the plan/research division of labour instead of diluting the design artifact with implementation detail.
+
+### Decision Tree
+
+```
+When implementing a task, ask:
+
+Is this about:
+├─ Function/Flow (what the code does)?
+│  ├─ YES → STRICT: Follow tasks.md exactly
+│  └─ NO → Continue
+│
+├─ UI/Interaction (how it looks/feels)?
+│  ├─ YES → FREE: Use your best judgment
+│  └─ NO → Continue
+│
+└─ Which mechanism satisfies the requirement (an API/library/approach the FR does not name)?
+   ├─ YES, and a real alternative existed → FREE to choose, **MUST record in specs/research.md**
+   │                                       (what · rejected · why · deferred — see Principle 3)
+   └─ NO → It's probably function/flow → Be strict
+```
+
+### Examples
+
+**Function/Flow (STRICT)**:
+- ❌ Wrong: Task says "Add user login" but you implement OAuth
+  - **Reason**: OAuth is a different login method, not in task
+- ✅ Correct: Task says "Add user login" → Implement username/password login
+  - **Reason**: This is exactly what task specifies
+
+**UI/Interaction (FREE)**:
+- ✅ OK: Task says "Add button" → You choose red color, rounded corners
+- ✅ OK: Task says "Create form" → You add validation hints
+- ✅ OK: Task says "Show list" → You add pull-to-refresh
+- ✅ No need to record any of these decisions
+
+**Gray Areas (Use Judgment)**:
+- ✅ Task: "Add error handling" → You add user-friendly error messages (FREE - UI)
+- ✅ Task: "Handle network errors" → You implement retry logic (STRICT - function)
+- ✅ Task: "Improve performance" → You optimize algorithms (STRICT - function)
+- ✅ Task: "Make it responsive" → You choose breakpoints and layout (FREE - UI)
+
+### Key Improvements
+
+- ✅ **SDD Compliance**: Implement executes specifications, doesn't make design decisions
+- ✅ **Function/Flow**: Strict execution of tasks.md requirements
+- ✅ **UI/Interaction**: Complete discretion for layout/style/interaction
+- ✅ **No Recording**: Most UI/interaction decisions don't need documentation
+- ✅ **Clear Separation**: Easy to decide what's strict vs. free
+- ✅ **Workflow Integrity**: Problems go through issues feedback, not arbitrary changes
+
+### When in Doubt
+
+- **Ask**: "Does this change WHAT the system does or HOW it looks?"
+  - WHAT = Function/Flow → Strict
+  - HOW = UI/Interaction → Free
+
+- **Ask**: "Would this change require updating tasks.md?"
+  - Yes → It's probably a functional change → Don't do it
+  - No → It's probably a UI/interaction change → Go ahead
+
+---
+
+## Implementation Steps
+
+1. Run `.specpro/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` 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").
+
+
+
+1.5. **Quality gate: requirements.md validation** 🆕 (CRITICAL pre-flight check):
+
+   **Purpose**: Verify spec quality validation completed before implementation begins
+
+   **Rationale**: Implementation should only proceed after spec quality is validated. This prevents implementing requirements with quality issues.
+
+   a. **Check file exists**:
+      ```bash
+      # ⚠️ `$FEATURE_DIR`，不是本文件此前用的那个路径变量（T172）：它在本文件里**出现 2 次、赋值 0 次**，
+      # 而 Step 1 指定的 `check-prerequisites.sh` 只输出 `FEATURE_DIR`。逐字执行时路径会塌成
+      # `/checklists/requirements.md` ⇒ 恒走 "File not found … EXIT 1" 分支，把人挡在实现之外。
+      # ⚠️ **此处刻意不写它的名字**：复核这条发现的命令是 `grep -c <那个名字> <本文件>`，而
+      # **返回 2 曾是该发现的证据** —— 留一个名字在注释里，复核就会永远非零，那条检查也就永远
+      # 分不清"已修"与"未修"。散文让位于可复核性。
+      if [[ ! -f "$FEATURE_DIR/checklists/requirements.md" ]]; then
+        ❌ ERROR: Spec quality validation not completed.
+
+         Required: specs/checklists/requirements.md (all items marked [x])
+         Current: File not found
+
+         Impact: Cannot proceed with implementation without quality validation
+
+         Next steps:
+         1. Run /specpro-specify to complete the specification workflow
+            - This will automatically run clarify and qc
+         2. Then run /specpro-implement again
+
+         For more info: /specpro-specify --help
+         EXIT 1
+      fi
+      ```
+
+   b. **Check all items passed**:
+      ```bash
+      # 完成度按「Status 取值」判定，不按复选框——模板即 `- [ ] **Status**: …`，
+      # 「诚实跳过」与「未做」在复选框上完全同形（工具缺陷 #10）
+      QC_UNRESOLVED=$(grep -E '^- \[[ x]\] \*\*Status\*\*:' "$FEATURE_DIR/checklists/requirements.md" 2>/dev/null \
+          | grep -vE '\*\*Status\*\*:[[:space:]]*(x|⊘[[:space:]]*Skipped)[[:space:]]*$' || true)
+      if [ -n "$QC_UNRESOLVED" ]; then
+        ❌ ERROR: Spec quality validation not completed.
+
+         Required: specs/checklists/requirements.md (all items marked [x])
+         Current: Some items are still unchecked [ ]
+
+         Impact: Cannot proceed with implementation with unresolved quality issues
+
+         Next steps:
+         1. Check specs/checklists/requirements.md for specific issues
+         2. Run /specpro-specify to complete quality validation
+            - This will automatically run clarify and qc to fix remaining issues
+         3. Then run /specpro-implement again
+
+         For more info: Check specs/checklists/requirements.md for details
+         EXIT 1
+      fi
+
+      ✓ Quality validation passed - All quality criteria met
+      ```
+
+   c. **Log quality status**:
+      ```bash
+      echo "✓ Spec quality validation passed"
+      echo "  All quality criteria met"
+      echo "  Proceeding with implementation..."
+      ```
+
+1.6. **Commit gate: repository hooks installed** 🆕 (CRITICAL pre-flight check):
+
+   **Purpose**: Verify the repository's git hooks are actually installed before work begins.
+
+   **Rationale**: git hooks are **not version-controlled** — a fresh clone has none. Command
+   documents state that a pre-commit hook enforces the ledger's structural checks ("a violation
+   blocks the commit rather than being discovered later"). Shipping the hook source and its
+   installer solves only **getting it**; it does not solve **going and installing it**. This
+   step is the call site. **A check that is assumed to exist and does not is worse than no
+   check at all** — every reader who skipped the manual check did so with a clear conscience.
+
+   a. **Run the installer's self-check**:
+      ```bash
+      if ! scripts/install-git-hooks.sh --check; then
+        echo ""
+        echo "❌ ERROR: the commit gate is not installed in this clone."
+        echo ""
+        echo "   Impact: the ledger's structural invariants and the shape-register"
+        echo "           sync are NOT enforced at commit time. A commit can succeed"
+        echo "           while leaving a structurally invalid artifact behind —"
+        echo "           silently, which is the whole reason the gate exists."
+        echo ""
+        echo "   Fix: run scripts/install-git-hooks.sh"
+        echo "        (it installs into every repository in this workspace that"
+        echo "         should carry the hook, and reports what it did)"
+        echo ""
+        exit 1
+      fi
+
+      echo "✓ git hooks installed — commit-time checks are live"
+      ```
+
+   b. **Why exit rather than warn** ⚠️: what this guards is **silent corruption**, and the
+      repair is one command that the message names. A warning inside a long report is passed
+      over — and a gate that is passed over is a statement, not a gate. ⚠️ **When the hook is
+      genuinely absent this stops a session that would otherwise have run to completion**:
+      that is intended, and the exit message is the whole mitigation.
+
+2. **Mandatory Cross-Artifact Analysis** ✨ NEW (enforced quality gate):
+
+   **Purpose**: Run comprehensive cross-artifact analysis before implementation begins
+
+   a. **Execute /specpro-analyze**:
+      - Run analysis automatically (mandatory pre-flight check)
+      - Parse analysis results for CRITICAL and HIGH severity issues
+      - Extract issue counts by category and severity
+
+   b. **Check for CRITICAL issues**:
+      - If CRITICAL issues found:
+        * Display blocking message
+        * Show critical issues summary
+        * Require user acknowledgment before proceeding
+
+      ```markdown
+      🔴 CRITICAL ISSUES DETECTED
+
+      **Cannot proceed with implementation until CRITICAL issues are resolved**
+
+      **Critical Issues** (CRITICAL):
+      1. [Issue summary]
+         - Source: [Constitution/Principle/Standard if applicable]
+         - Impact: [Why this blocks implementation]
+         - Recommendation: [How to fix]
+
+      **Options**:
+      1. Fix issues now → Run the OWNING command's --review-issues (see the note below), then re-run /specpro-implement
+      2. Halt implementation → Fix issues manually, then re-run /specpro-implement
+      3. Proceed with caution → Type 'UNDERSTAND' to acknowledge risks and proceed anyway
+
+      Your choice (1/2/3):
+      ```
+
+      - If user chooses 1: Run the owning command's `--review-issues`, then re-evaluate
+      - If user chooses 2: Halt execution
+      - If user chooses 3: Require 'UNDERSTAND' acknowledgment, then proceed to step 2c
+
+      ⚠️ **There is no auto-fix path here** [settled 2026-09-18, `ISS-141` / `T184`]: option 1 used to read "Run /specpro-analyze --auto-fix". That path is gone — `/specpro-analyze` **reports, it does not repair**. The repair belongs to the command that **owns** the artifact the finding sits in, and `/specpro-analyze` decides *which* command that is per finding. ⚠️ **That mapping has one owner — the routing table in `/specpro-analyze`'s Finding Registration step — and it is POINTED AT here, not restated** (a second copy is a second source, and the two diverge silently: FR-025 / 原则 II).
+      ⚠️ **Why this is not a matter of preference**: a command that repairs what it judged has spent the verdict (**Principle III**), and `/specpro-analyze`'s write surface does not include those artifacts (**FR-051**) — so an option that offers the repair offers a boundary violation, which is why it was removed rather than made conditional.
+
+   c. **Check for HIGH severity issues** (if no CRITICAL):
+      - If HIGH issues found:
+        * Display warning message
+        * Show high-severity issues summary
+        * Require acknowledgment before proceeding
+
+      ```markdown
+      ⚠️ HIGH SEVERITY ISSUES DETECTED
+
+      **Recommended**: Address HIGH issues before implementation for best results
+
+      **High Issues** (HIGH):
+      1. [Issue summary]
+         - Impact: [Potential problems]
+         - Recommendation: [How to fix]
+
+      **Options**:
+      1. Fix now → Run the OWNING command's --review-issues (same routing as option 1 above), then re-run /specpro-implement
+      2. Proceed → Type 'PROCEED' to acknowledge and continue
+      3. Details → Run /specpro-analyze for full report
+
+      Your choice (1/2/3):
+      ```
+
+   d. **Log analysis status for implementation**:
+      - Store analysis results for use during implementation
+      - Highlight risk areas when implementing related features
+      - Track which requirements have coverage issues
+
+3. **Check quality validation status** ✨ (enhanced with content validation):
+
+   **Purpose**: Verify quality checklist status AND validate that issues are addressed in plan/tasks
+
+   a. **Check if checklists/ directory exists**:
+      - If not, proceed to step 3 (no quality gate)
+      - If yes, continue to validation
+
+   b. **Scan the quality checklist** — ⚠️ **`FEATURE_DIR/checklists/requirements.md`, by name** (`T233`/`ISS-206`):
+      - This step used to read *"Scan all *.md files in FEATURE_DIR/checklists/"*. ⚠️ **Only one producer emits the fields read below** — `templates/requirements-template.md`. `templates/checklist-template.md` **emits none of them** (`**Total Items**` / `**Passed**` / `**Failed**` / the per-item `**Status**` rows) ⇒ on every other checklist this step reads **nothing**, and "nothing read" prints the same as "all passed". A directory-wide scan whose fields exist in one file is a scan whose scope is wider than its predicate — narrow the **scope**, never the fields. ⚠️ **If a second checklist template ever gains those fields, widen this back — and widen it by the field, not by the directory.**
+      - 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`
+         * Extract specific problems (not just checkbox counts)
+      - ⚠️ Do **not** look for `Overall Quality`, an `N/M` score, `❌ FAIL` or
+        `⚠️ WARNING`: `templates/requirements-template.md` emits none of them ⇒ a
+        reader keyed on them finds nothing on **every** checklist and reports
+        "all quality checks passed", 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: an honest
+        skip is a conclusion, not a debt) — surface them, never gate on them
+
+   c. **Parse quality issues from checklist** (NEW):
+      - Read `FEATURE_DIR/checklists/requirements.md` — ⚠️ **not "(or equivalent)"**: no other checklist in this toolchain carries these fields (`b` above).
+      - Parse for specific quality issues. The issue text is what the item's
+        **explanation line** says; the value on the row is only the status:
+         * ✗ Failed example: "Critical module lacks test coverage"
+           - Problem: Test coverage below required threshold
+           - Location: [Module/function reference]
+         * ⊘ Skipped example: "Edge cases not identified"
+           - Problem: this item yields no derivation source on this project;
+             recorded as an honest skip, **not** as a pending improvement
+
+   d. **Verify issues are addressed in plan.md/tasks.md** (NEW):
+      - Load plan.md and tasks.md (if exist)
+      - For each `✗ Failed` item:
+         * Search plan.md for design addressing the issue
+         * Search tasks.md for tasks addressing the issue
+         * Example: For "Test coverage insufficient" FAIL:
+           - Check if plan.md includes test strategy
+           - Check if tasks.md includes test tasks for the module
+           - Mark as "Addressed" or "Unaddressed"
+      - ⚠️ `⊘ Skipped` items are **not** verified for coverage: they assert that
+        nothing here needs covering.
+
+   e. **Generate enhanced status table** (columns are the checklist's own fields):
+      ```text
+      | Checklist | Total | Passed | Skipped | Failed | Issues Addressed | Status |
+      |-----------|-------|--------|---------|--------|------------------|--------|
+      | requirements.md | 12 | 10 | 1 | 1 | 0/1 | ⛔ BLOCK |
+      ```
+      ⚠️ **The table has one row because the scan has one subject** (`b` above) **and its numbers are illustrative** — do not read them back as this project's counts (the live values are the checklist's own `**Total Items**` / `**Passed**` / `**Failed**`). This example used to show `ux.md` and `security.md` rows — files **no template in this toolchain produces**, which is how the wider scan stayed invisible: the example made the reader believe there was a family of checklists emitting the same fields.
+      - `Status` is the checklist's own `**Status**` value, copied — not re-derived
+      - `Skipped` is shown for visibility and is **not** an input to that value
+
+   f. **Overall status** — carry the checklists' verdicts, do not re-derive one:
+      - **PASS**: every checklist's `**Status**` is `PASS`
+      - **BLOCK**: any checklist's `**Status**` is `BLOCK`
+      ⚠️ There is no third tier, and no "unaddressed" variant: the checklist is
+      two-valued. `Passed < Total Items` on its own is **not** a reason to warn —
+      the difference is `⊘ Skipped` rows, which its template declares non-blocking;
+      warning on them would push the reader to "fix" an honest skip.
+
+   g. **Handle quality validation results** (ENHANCED):
+
+      **Case 1: All checklists PASS** (ideal scenario)
+      - Display status table showing all passed
+      - Display message: "✓ All quality checks passed. Proceeding with implementation..."
+      - Automatically proceed to step 3
+
+      **Case 2: Any checklist BLOCKs** — the only non-pass case, because the
+      checklist's `**Status**` is two-valued (`PASS` ⟺ `**Failed**` == 0).
+      ⚠️ `⊘ Skipped` rows never reach this case: skips are non-blocking.
+      - Display status table showing the blocking failures
+      - Display the blocking issues, plus the skipped rows for visibility:
+
+        ```markdown
+        🛑 BLOCKING ISSUES DETECTED
+
+        **Status**: BLOCK (the checklist's own verdict — copied, not re-derived)
+        **Issues Addressed**: X of Y
+
+        **Blocking (✗ Failed)**:
+        1. "Critical module lacks test coverage"
+           - Requirement: Project requires [specific %] test coverage for critical modules
+           - Location: [Module name/reference]
+           - Plan.md: No test strategy found
+           - Tasks.md: No test tasks found
+           - **Risk**: Low test coverage, potential bugs in critical path
+
+        **Skipped (⊘)** — non-blocking; these need no risk acknowledgment:
+        2. "Edge cases not identified" (yields no derivation source on this project)
+
+        **Addressed Issues** (Resolved):
+        3. ✓ "Success criteria are measurable" (addressed in plan.md)
+        ```
+
+      - **The checklist's own rule is that a BLOCK must be fixed**: its template
+        reads "Cannot proceed to plan/tasks/implement until all items pass". So the
+        default is to stop; proceeding is an explicit, acknowledged exception.
+      - **CRITICAL: Require explicit risk acknowledgment** to proceed:
+        ```markdown
+        **Some quality issues were NOT addressed in plan.md or tasks.md**.
+
+        This means:
+        - The design may not account for these quality concerns
+        - The implementation may have quality deficiencies
+        - You may need to re-plan or re-task after implementation
+
+        **To proceed despite unaddressed issues**, you must:
+        1. Review each unaddressed issue above
+        2. Acknowledge the risks
+        3. Type 'UNDERSTAND' to confirm you accept these risks
+
+        Your response:
+        ```
+
+      - Wait for user to type 'UNDERSTAND'
+      - If user types 'UNDERSTAND':
+        * Display: "✓ Risks acknowledged. Proceeding with implementation..."
+        * Proceed to step 3
+      - If user types anything else:
+        * Display: "Implementation cancelled. Please address quality issues first."
+        * Halt execution
+
+   h. **Log quality status for implementation** (NEW):
+      **Purpose**: Store quality issues for use during task execution
+
+      **Store as variables** (in memory, not files):
+      - `QUALITY_STATUS`: The checklists' verdict — `"PASS"` / `"BLOCK"` (two values
+        only; see **f**). `"BLOCK"` here means the operator typed `UNDERSTAND` and
+        the run proceeded anyway, so the unaddressed issues below are live.
+      - `UNADDRESSED_ISSUES`: The `✗ Failed` items that **d** marked "Unaddressed"
+        — one entry per issue, quoted from the item's explanation line
+      - `COVERAGE_GAPS`: The keywords under which those unaddressed issues fall
+      - ⚠️ There is no third variable: the retired warning tier was the only source
+        a "non-blocking issue" list could have had, and a list nobody reads is the
+        same as not storing it.
+
+      **How to use during implementation** (see Step 9):
+      - Before executing each task, scan task description for keywords
+      - Match keywords against `UNADDRESSED_ISSUES` and `COVERAGE_GAPS`
+      - If match found: Display context-aware warning
+
+      **Example workflow**:
+      ```markdown
+      Step 3 (Quality validation) stores:
+      - QUALITY_STATUS = "BLOCK"          (the operator typed UNDERSTAND to get here)
+      - UNADDRESSED_ISSUES = ["Critical module lacks test coverage"]
+      - COVERAGE_GAPS = ["streaming", "error handling"]
+
+      Step 9 (Task execution):
+      Task: "Implement streaming data processing"
+
+      System checks:
+      - Task contains "streaming" → Matches COVERAGE_GAPS
+      - Issue exists: "Critical module lacks test coverage"
+
+      Display warning (use PROJECT_LANGUAGE):
+      "⚠️ QUALITY NOTE: This task involves streaming, and quality check
+       flagged 'Critical module lacks test coverage' — which the operator
+       acknowledged as an accepted risk. Consider adding tests for:
+       - Network interruption
+       - Data corruption
+       - Buffer overflow"
+      ```
+
+      **Keyword matching examples**:
+      - Task mentions "streaming" → Check for "Edge cases" issue
+      - Task mentions "performance" → Check for "Performance metrics" issue
+      - Task mentions "authentication" → Check for "Security" issues
+      - Task mentions "error handling" → Check for "Edge cases" issue
+
+      **DO NOT**:
+      - Store in files (not needed between runs)
+      - Block execution on warnings (only BLOCK status should halt)
+      - Re-run quality checks (already done in Step 3)
+
+4. **Load project constitution** 📜 [CRITICAL - DECISION CONTEXT]:
+   **Purpose**: Load project preferences BEFORE any user interaction
+   **Why Early**: Language preference affects ALL user-facing messages
+
+   a. **Check if constitution exists**:
+      - Look for `specs/constitution.md`
+      - If not found: Use defaults (English language)
+      - If found: Proceed to extract language setting
+
+   b. **Extract language preference** 🌐 [AFFECTS ALL USER INTERACTION]:
+      - ⚠️ **读宪法实际声明的那个字段**（T172 修正）：宪法写的是 **`**Artifact Language**: <code>`**，
+        而本节此前叫它 `**Language Preference**` —— **一个字段名、两套标签**：照本节去 `grep`
+        那个名字，在**任何**合规的宪法里都**零命中**，于是永远回落到默认值，而**没有任何东西会报错**。
+      - 取值优先级：① 宪法里 `**Artifact Language**: <code>` 的值 · ② 缺该字段时，检查同文件有无
+        `**Language Preference**:`（历史别名，容错读取）· ③ 两者皆无 ⇒ 默认 `en`
+      - Store as `PROJECT_LANGUAGE` variable
+
+      **Use this for**:
+      - All user-facing messages (errors, warnings, progress reports, menus)
+      - Interactive mode selection menu text
+      - Development process documentation (Step 9.d)
+      - Task completion messages
+
+      **Example**:
+      - If `PROJECT_LANGUAGE = zh`:
+        * Menu: localized "Select Execution Mode" text (in Chinese)
+        * Progress: localized "Completed: [task]" text (in Chinese)
+        * Errors: localized "Quality issues detected" warning text (in Chinese)
+      - If `PROJECT_LANGUAGE = en`: Display in English
+      - If `PROJECT_LANGUAGE = ja`: Display in Japanese
+
+      **Important**:
+      - Technical terms remain in English (API, HTTP, JSON, protocol identifiers, etc.)
+      - Code and file paths remain in English
+      - Section headers remain in English
+
+   c. **Display language confirmation**:
+      ```markdown
+      🌐 Project Language: [language name]
+
+      All user interaction will use this language.
+      ```
+
+   d. **Note on testing and quality principles**:
+      - Constitution principles (testing, security, performance, etc.) primarily influence spec/plan/tasks phases
+      - Implement phase TRUSTS that tasks.md already reflects constitutional requirements
+      - Implement follows task order: if test task exists before implementation task, execute test first
+      - No need to validate constitutional compliance during implementation (already validated in earlier phases)
+
+5. **Scan for first pending task** 🎯 [TASK DISCOVERY]:
+   **Purpose**: Find the next task to execute BEFORE loading detailed context
+
+   a. **Read tasks.md and scan**:
+      - Read from top to bottom
+      - Skip all tasks marked `[x]` (completed)
+      - Stop at first task marked `[ ]` (pending)
+      - Extract task details:
+         * Phase (Setup/Foundational/US-XXX/Polish)
+         * Task description
+         * Parallel marker `[P]` (if present)
+         * File paths mentioned in task
+         * FR annotation `(FR-XXX)` (if present)
+
+   b. **Display next task preview**:
+      ```markdown
+      📍 Next Pending Task Found
+
+      **Phase**: [phase name]
+      **Task**: [task description]
+      **Files**: [file paths from task]
+      ```
+
+6. **Interactive execution mode selection** 🎯 [USER EXPERIENCE]:
+   **Purpose**: Let user choose how many tasks to execute in this session
+
+   **Skip this step** if user provided arguments (`$ARGUMENTS` is not empty)
+
+   a. **Analyze task status**:
+      - Scan tasks.md and count:
+         * Total tasks: X
+         * Completed tasks [x]: Y
+         * Pending tasks [ ]: Z = X - Y
+         * Overall progress: Y/X (Z% complete)
+
+   b. **Display execution mode menu**:
+      ```markdown
+      📋 Implementation Session Setup
+
+      **Task Status**:
+      - Total tasks: X
+      - Completed: Y (Z%)
+      - Remaining: Z
+
+      **Select Execution Mode**:
+
+      1️⃣ **Fix Product Defects** (N pending in specs/fix-tasks.md) (Recommended when offered)
+         - Execute FT-XXX fix tasks dispatched by /specpro-test-implement
+         - Defects before features: fixes unblock blocked test tasks
+         - ONLY shown when specs/fix-tasks.md exists with pending [ ] FT items;
+           when absent, omit this option and number the remaining options 1-5
+
+      2️⃣ **Single Task** (Recommended for first-time users)
+         - Execute 1 task, then pause
+         - Safest option, prevents context overflow
+         - You'll be prompted to continue after each task
+         - Estimated time: 2-5 minutes
+
+      3️⃣ **Small Batch** (3 tasks)
+         - Execute next 3 tasks, then pause
+         - Balanced option for efficiency and safety
+         - Good for small, related tasks
+         - Estimated time: 5-15 minutes
+
+      4️⃣ **Medium Batch** (5 tasks)
+         - Execute next 5 tasks, then pause
+         - For experienced users who know task size is small
+         - Use with caution if tasks are large
+         - Estimated time: 10-25 minutes
+
+      5️⃣ **Phase Execution**
+         - Execute all remaining tasks in current phase
+         - Efficient for completing entire phase
+         - Risk: May execute many tasks (check phase size first)
+         - Estimated time: Varies (see phase details below)
+
+      6️⃣ **Continue All** (⚠️ ADVANCED ONLY)
+         - Execute ALL remaining tasks (Z tasks)
+         - WARNING: High risk of context overflow!
+         - Only use if Z < 10 or you have large context window
+         - Estimated time: Very long (Z × 3 minutes)
+
+      **Current Phase**: [Setup/Foundational/US-XXX/Polish]
+      **Tasks in current phase**: N
+      **Completed in phase**: M
+      **Remaining in phase**: N - M
+
+      ⚠️ **选项 1️⃣ 缺席时，其余各项整体上移一位**（T172 修正）：本节此前只在上面的说明里写了
+      「omit this option and number the remaining options 1-5」，而**下面这组标签是写死的 2️⃣–6️⃣**
+      —— 于是"说明"与"菜单"在**同一屏里**对不上：说明说按 1–5 选，屏幕上只有 2–6。
+      ⇒ 1️⃣ 不在时，屏幕上印的是 **1️⃣ Single Task · 2️⃣ Small Batch · 3️⃣ Medium Batch ·
+      4️⃣ Phase Execution · 5️⃣ Continue All**。
+
+      Your choice (1-6, or 1-5 when no fix tasks are pending — see the note above):
+      ```
+
+   c. **Handle user selection**:
+      - **Choice 1 (Fix Product Defects, only when offered)**: Set `execution_mode = "fix"` (execute ALL pending FT items in specs/fix-tasks.md — procedure in Step 9.a2)
+      - **Choice 2 (Single Task)**: Set `execution_mode = "once"`, `task_limit = 1`
+      - **Choice 3 (Small Batch)**: Set `execution_mode = "count"`, `task_limit = 3`
+      - **Choice 4 (Medium Batch)**: Set `execution_mode = "count"`, `task_limit = 5`
+      - **Choice 5 (Phase Execution)**: Set `execution_mode = "phase"`, `target_phase = current_phase`
+      - **Choice 6 (Continue All)**:
+         * If Z >= 20: Show warning:
+           ```markdown
+           ⚠️ WARNING: You have Z remaining tasks.
+           Executing all tasks will likely exceed context limits.
+
+           Recommended: Choose option 2 or 3 for batch execution.
+
+           Do you want to:
+           1. Proceed with all tasks (understood the risk)
+           2. Switch to Small Batch (3 tasks)
+           3. Switch to Medium Batch (5 tasks)
+
+           Your choice (1-3):
+           ```
+         * If user confirms 1: Set `execution_mode = "continue"`, `task_limit = infinity`
+         * If user chooses 2 or 3: Set corresponding mode
+
+      - **Invalid input**: Display menu again
+
+      - **Note**: ALL modes are subject to the **Checkpoint Gate** (Step 9.e) — when a User Story phase boundary is crossed and test-plan relevance is HIGH, execution pauses even in Phase/Continue modes. This protects the optimal timing for `/specpro-test-plan` (run tests planning right after each story's implementation lands).
+
+   d. **Confirm execution plan**:
+      ```markdown
+      ✅ Execution Plan Confirmed
+
+      **Mode**: [Single Task / Small Batch (3 tasks) / ...]
+      **Tasks to execute**: [N]
+      **Current phase**: [phase name]
+
+      Starting implementation...
+      ```
+
+7. **Load task-specific context** 🎯 [ON-DEMAND]:
+   **Purpose**: Load ONLY the information needed for current task(s)
+   **Key Principle**: Read files based on task requirements, not preemptively
+   **Note**: Constitution already loaded in Step 4, no need to reload here
+
+   a. **Always load** (required for every task):
+      - **plan.md → `## Technical Context`** — the ONLY unconditionally-loaded plan.md section: language/version, dependencies, target platform are general background for any task.
+      - **tasks.md**: Task list and current task details
+
+   a2. **plan.md's other sections: load by keyword, same mechanism as (b)** ⚠️ [settled 2026-09-13]:
+      Do **not** load the whole of plan.md. plan.md is split into **Part I (machine-read)** and **Part II (human-read)**, and they load differently:
+
+      | `specs/plan.md` section | Load when the task description / file paths mention |
+      |-----------------|------------------------------------------------------|
+      | `## Project Structure` → module layout | creating or placing a file · any path |
+      | `## Architecture` → `### Shared/Platform Boundary Declaration` | a layer · a source set · expect/actual · where a file belongs |
+      | `## Architecture` → `### Layered Architecture` | a layer · layer ownership · a MUST/MUST NOT constraint |
+      | `## Architecture` → the pattern / interaction / constraint the task touches | that pattern's, interaction's or constraint's components |
+      | `## Architecture` → `### Protocol Codec Design Artifacts` | a protocol point · encoding/decoding · a byte stream · a wire format |
+      | `## Quality Targets` | the task carries `[Quality]`, or mentions coverage |
+
+      - **Match by keyword in the task text — never by task "type".** Tasks cross boundaries constantly: one task may create a file *and* implement a pattern *and* carry a test obligation. A keyword scan collects every section the task actually touches; a type-based mapping would silently drop the ones it does not anticipate.
+      - **`plan-overview.md` is NEVER loaded** — it is a **separate file** holding the human-read half (`## Summary`, `## System Overview`, `## Constitution Check`, `## Implementation Plan`, `## Documentation Layout`, `## Complexity Tracking`). None of them is an input to executing a task. The file split is what makes this structural: those sections are not *in* the file you read, so no whole-file load can pull them in by accident.
+      - Why this shape (rather than "always load plan.md"): a whole-file load puts the human sections into every task's context while the sections a task genuinely needs are read anyway — the cost is noise, and the benefit was never measurable. The three earlier statements in this step disagreed with each other (`Always load plan.md: Tech stack, architecture, project structure` / `Don't read entire files` / the `plan.md (full …)` example); this replaces all three.
+
+   b. **Load based on task analysis** 📋:
+      Scan task description and file paths for keywords:
+
+      **If task mentions data entities** (User, Product, Order, etc.):
+         * Read **data-model.md** (IF EXISTS)
+         * Extract ONLY relevant entities and relationships
+         * Example: Task says "Implement User authentication" → Read User entity only
+
+      **If task mentions API endpoints** (POST /users, GET /products, etc.):
+         * Read **contracts/** directory (IF EXISTS)
+         * Extract ONLY related API contracts
+         * Example: Task says "Implement login API" → Read auth-related contracts
+
+      **If task mentions complex algorithms** (encoding, compression, crypto, parsing):
+         * Read **research.md** (IF EXISTS)
+         * Extract ONLY relevant technical decisions
+         * Example: Task says "Implement the decoder" → Read the encoding decisions
+
+      **If task mentions integration** (connect to service, external API):
+         * Read **quickstart.md** (IF EXISTS)
+         * Extract ONLY relevant integration scenarios
+
+      **Note**: ⚠️ **Nothing further is loaded here.** Step 4 reads the constitution for its language setting (`PROJECT_LANGUAGE`) and states the division of labour explicitly: implementation **trusts** that `tasks.md` already reflects the constitutional requirements, so no test-requirements variable exists to consult. This note used to read *"use `TESTING_RULES` variable"* — that variable **has no producer anywhere in the tree** (`T233`/`ISS-206`), i.e. it named a binding that was never made. ⚠️ **Do not reintroduce it by defining it**: the thing it would carry is already discharged upstream (Step 4.d).
+
+   c. **Smart extraction strategy** ✨:
+      - **Don't read entire files**: Extract only relevant sections — this applies to **plan.md as much as to any other file** (see a2: only `Technical Context` is unconditional)
+      - **Use keyword matching**: Search for entity names, API paths, feature names
+      - **Build minimal context**: Include only what's needed for this task
+      - **Cache for reuse**: If executing multiple tasks, cache loaded sections
+
+   d. **Example**:
+      ```
+      Task: "Implement User authentication with JWT tokens"
+
+      Context loaded:
+      ✅ plan.md → Technical Context only            (unconditional)
+      ✅ plan.md → Architecture → Boundary + the crypto/security constraint
+                                                     (keywords: authentication, credentials)
+      ✅ tasks.md (current task)
+      ✅ data-model.md → User entity only (not all 50 entities)
+      ✅ contracts/ → auth contracts only (not all API endpoints)
+      ✅ research.md → JWT/auth decisions only
+      ❌ plan-overview.md → never loaded               (separate file, human-read half)
+      ❌ quickstart.md → Not needed (not integration task)
+      ❌ Other entities → Not needed (not mentioned in task)
+      ```
+
+   e. **Context summary for execution**:
+      ```markdown
+      📚 Task Context Loaded
+
+      **Core**: plan.md → Technical Context (+ the Part I sections matched this task)
+      **Entities**: [list of relevant entities]
+      **APIs**: [list of relevant contracts]
+      **Decisions**: [list of relevant research items]
+      ```
+
+8. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+9. **Incremental task parsing and execution** 🔄 [OPTIMIZED]:
+   **Purpose**: Execute task(s) using task-specific context loaded in Step 7 and language preference from Step 4
+
+   a. **Use execution mode from Step 6** (or parse from arguments):
+      - If Step 5 set `execution_mode` and `task_limit`: Use those values
+      - Else if `$ARGUMENTS` provided: Parse from arguments
+         * `--once`: Set `execution_mode = "once"`, `task_limit = 1`
+         * `--count N`: Set `execution_mode = "count"`, `task_limit = N`
+         * `--continue`: Set `execution_mode = "continue"`, `task_limit = infinity`
+         * `--phase PHASE`: Set `execution_mode = "phase"`, `target_phase = PHASE`
+      - Else (should not happen): Default to `execution_mode = "once"`, `task_limit = 1`
+
+   a2. **Fix-task execution** 🛠️ [NEW — when `execution_mode = "fix"`]:
+      **Purpose**: Execute product-defect fix tasks dispatched by `/specpro-test-implement` in `specs/fix-tasks.md`. Two-AI separation of duties: the testing AI never fixes code; this command fixes code but never re-judges tests.
+
+      - Load `specs/fix-tasks.md`. If absent or no pending `[ ]` FT items → report "no pending fix tasks" and fall through to normal task execution
+      - **Pre-enqueue triage** ⚠️ [settled 2026-09-13, TOOL-010]: **before** working an FT, decide whether this command can actually discharge its `Validates`. If discharging it would require **modifying test code**, or any artifact **outside this command's jurisdiction**, do **not** start it — mark it `<unclosable by this command>` and move on. Rationale: the exit below is binary (PASS → `[x]`, FAIL → `[ ]`), so an FT that *cannot* pass by construction pins the queue head with a `[ ]` that no amount of fixing will clear, and every `--fix-defects` run re-does the same diagnosis. The observed case was an FT whose `Validates` depended on a test-side defect while this command is forbidden from touching test code — FAIL was guaranteed.
+      - For each pending FT-XXX (top to bottom):
+        * Load its Evidence / Location / Fix Direction / Validates / Blocked-Tests; locate the root cause in PRODUCT code — the fix target is code, NOT the test
+        * Fix the product code: Function/Flow STRICT to the FT's Validates; no scope creep; NEVER modify the source test's code or its assertions
+        * Run the Validates-named test: PASS → mark the FT `- [x]` in fix-tasks.md; FAIL → leave `[ ]`, display output, iterate the fix or report
+        * **Legal terminal states** ⚠️ [settled 2026-09-13, TOOL-010]: there are **three**, not two — and the third must be stated, never improvised:
+          1. **Fixed** — `Validates` passes → mark `[x]`.
+          2. **Not yet fixed** — the fix is within this command's power; FAIL is informative → leave `[ ]` **with the failing output** and iterate.
+          3. **Not closable here** — the defect is real but its resolution lies outside this command (test-side defect, missing fixture, another owner's artifact). Do **not** leave a bare `[ ]` that reads like "still working on it": leave `[ ]`, **append a diagnostic note to the FT** recording what was found and why this command cannot close it, and **report it for hand-off** (`/specpro-test-plan` → `/specpro-test-implement`, or whichever owner the note names). This keeps the queue honest: the next run can skip it in one glance instead of re-deriving the diagnosis.
+        * Write boundary ⚠️ [CRITICAL]: mark ONLY the FT checkbox in fix-tasks.md. NEVER write `specs/test-tasks.md` — task checkboxes, coverage matrix, and Progress Statistics are `/specpro-test-implement`'s jurisdiction. Re-verification and test-task write-back happen when the user runs `/specpro-test-implement`
+      - After the loop: report fixed / still-open / **not-closable-here** counts, name the FTs in the third bucket with their hand-off target, and remind: "run /specpro-test-implement to re-verify the fixes and complete test-task bookkeeping"
+        ⚠️ **`<unclosable by this command>` 的读取点就是这一句**（T172 / audit finding：「标记被定义，
+        却没有任何读取点」）：上面第 3 条终态要求给这类 FT 打这个标记并附诊断说明，而**在此之前
+        没有任何一步读它** —— 一个只管写、没人读的标记，与不写它同形。⇒ **收尾必须逐个点名它们**，
+        并写出移交目标（`/specpro-test-plan` → `/specpro-test-implement`，或诊断说明里点名的那个）。
+
+   b. **Scan for first pending task**:
+      - Read tasks.md from top to bottom
+      - Skip all tasks marked `[x]` (completed)
+      - Stop at first task marked `[ ]` (pending)
+      - Extract task details:
+         * Phase (Setup/Foundational/US-XXX/Polish)
+         * Task description
+         * Parallel marker `[P]` (if present)
+         * File paths mentioned in task
+         * FR annotation `(FR-XXX)` (if present)
+
+   c. **Determine execution scope**:
+      - **Single sequential task**: No `[P]` marker
+        * Verify previous task in same phase is `[x]`
+        * If not, find and execute previous task first
+        * Execute this single task
+
+      - **Parallel task group** `[P]`: Task has parallel marker
+        * Collect all consecutive `[P]` tasks at same indentation level
+        * Verify no file conflicts (parallel tasks must not affect same files)
+        * Execute all parallel tasks concurrently
+
+   d. **Execute task(s)** 🎯:
+      - **Single task**:
+         * **Identify task type** from task description and file paths:
+           - **Test task**: Task description contains "Test", "test", OR file path ends with `Test.kt`, `Test.java`, `Test.ts`, `test.py`, `*_test.go`, etc.
+           - **Implementation task**: Task contains "Implement", "Create", "Add", "Build", OR file path ends with implementation extension (`.kt`, `.java`, `.ts`, `.py`, `.go`, etc.)
+
+         * **Check quality status warnings** ⚠️ (if QUALITY_STATUS = "BLOCK" — i.e. the run proceeded on an acknowledged `UNDERSTAND`; a `PASS` run has no unaddressed issues to surface):
+           - Extract keywords from task description (e.g., "streaming", "authentication", "performance")
+           - Match keywords against `UNADDRESSED_ISSUES` and `COVERAGE_GAPS` (stored in Step 3h)
+           - **If keyword match found**:
+             - Display quality warning (use `PROJECT_LANGUAGE`):
+               ```markdown
+               ⚠️ QUALITY NOTE
+
+               **Issue**: [Issue description from UNADDRESSED_ISSUES]
+               **Relevance**: This task involves [keyword], which relates to the quality issue
+
+               **Suggestions**:
+               - [Specific suggestions based on issue type]
+
+               **Example**:
+               Issue: "Edge cases not identified"
+               Task: "Implement streaming data processing"
+               Suggestions:
+               - Consider network interruption scenarios
+               - Consider data corruption scenarios
+               - Consider buffer overflow scenarios
+               ```
+             - Ask: "Proceed with implementation? (y/n):"
+             - If user says 'n': Skip task, return to Step 9b to find next task
+             - If user says 'y': Continue with implementation
+           - **If no keyword match**: No warning needed, proceed to next step
+
+         * **Identify target files** from task description
+
+         * **Check Test-First compliance** (if implementation task):
+           - Extract module/class name from implementation task
+           - Search tasks.md for corresponding test task:
+             * Pattern: `ModuleNameTest`, `ModuleName.test`, or similar
+             * Search in tasks before current task (test should come first)
+           - **If test task found and is `[ ]` (not completed)**:
+             - Display warning (use `PROJECT_LANGUAGE`): "⚠️ Test task exists but is not completed. Test-First approach recommends completing tests before implementation."
+             - Show test task ID and description
+             - Ask: "Continue with implementation anyway? (y/n):"
+             - If user says 'n': Skip this task, return to step 9b to execute test task first
+           - **If test task found and is `[x]` (completed)**:
+             - Proceed with implementation (tests already in place)
+           - **If no test task found**:
+             - Proceed with implementation (tasks.md defines test requirements, not implement phase)
+
+         * **For each target file**:
+           - **Check if file exists** (use Glob tool to search)
+           - **If file exists**:
+             - **Read entire file** (use Read tool)
+             - **Analyze existing code**:
+               - Check if task requirements are already implemented
+               - Verify code quality and style
+             - **Decision**:
+               - If fully implemented → Skip this file
+               - If partially implemented → Use Edit tool to add missing parts
+               - If wrong implementation → Use Edit tool to fix
+             - **Preserve existing code structure** (style, patterns)
+           - **If file does not exist**:
+             - **Verify parent directory exists** (create if needed)
+             - **Create new file** (use Write tool)
+
+         * **Execute based on task type**:
+           - **Test task**:
+             - Write test file with appropriate test cases
+             - Run test to verify it fails (RED phase of TDD)
+             - Mark task as `[x]` when test is written and fails as expected
+
+           - **Implementation task** (when tests are in place):
+             - Write implementation code
+             - Run tests to verify they pass (GREEN phase of TDD)
+             - Check test coverage if specified in tasks.md or plan.md
+             - Mark task as `[x]` when implementation passes tests
+
+           - **Implementation task** (when tests are NOT required or not in place):
+             - Write implementation code
+             - Basic verification (compile, lint check if available)
+             - Mark task as `[x]` when implementation is complete
+             - ⚠️ **Platform source-set tasks** [CRITICAL]: if the task writes platform-specific sources (`androidMain/`, `iosMain/`, `wasmMain/`, ...), the owning compilation target MUST be registered in the module build script and the file MUST participate in the compile verification above. If the target is NOT registered, do NOT mark `[x]` — the file would be orphan dead code that silently passes every gate; implement what is verifiable and register an implement issue for the missing target registration
+
+         * **Task already completed check**:
+           - After checking all target files, if ALL files are fully implemented
+           - Mark task as `[x]` in tasks.md
+           - No code changes needed
+
+         * **Create development process documentation** 📝 [WHEN NEEDED]:
+           - **Purpose**: Document complex problems, difficult debugging, and important learnings
+           - **When to create** (NOT for every task):
+             * ✅ **ALWAYS create** for:
+               - Complex algorithms (encoding, compression, crypto, protocol parsing)
+               - Bugs that took >2 hours to solve
+               - Issues requiring multiple attempts to fix
+               - Cross-component debugging (data flow, state synchronization)
+               - Performance optimizations with measurable results
+               - Integration issues with external systems
+             * ❌ **DO NOT create** for:
+               - Simple CRUD operations
+               - Straightforward UI adjustments
+               - Trivial bug fixes (typos, simple logic errors)
+               - Routine refactoring
+
+           - **⚠️ 机制选择记录 —— 这是 §"Implement Responsibility Boundaries" 第 3 条的执行步骤**
+             （T172 / audit finding：「WHERE 写了落点，而没有任何执行步骤」）：
+             **每次**在实现中选了一个"有合理替代方案、且无法从 FR 正文推出"的机制时，**当轮**在
+             `specs/research.md` 追加一节 `## Addendum (<task-id>, <date>): <选择> — <被拒的替代> vs <被拒的替代>`，
+             内容四项：**选了什么 · 否决了什么 · 为什么（证据，不是断言）· 推迟或未做的部分及其诚实语义**。
+             ⚠️ **判据不在"有没有写"，在"它是否落在设计所指的推理路径上"**：`plan.md` 的
+             `### Architecture Patterns` 用 `See: research.md` 指向它 ⇒ **写进提交信息或 `docs/implement/`
+             都不算**（那两处都不在那条路径上，下一个做同样选择的人读不到）。
+
+           - **Document types** (choose based on situation):
+             1. **{FEATURE}_FORMAT.md**: Protocol format or data structure specification
+                * When: Implementing new protocol, encoding, or data format
+                * Content: Format specification, byte structure, examples
+                * Examples: `USER_AUTH_FORMAT.md`, `DATABASE_SCHEMA_FORMAT.md`
+
+             2. **ROOT_CAUSE.md**: Root cause analysis for complex bugs
+                * When: Bug took >2 hours to solve or involved multiple components
+                * Content: Problem description, investigation steps, root cause, evidence
+                * Examples: `MEMORY_LEAK_ROOT_CAUSE.md`, `CONNECTION_TIMEOUT_ROOT_CAUSE.md`
+
+             3. **DEBUG.md**: Debugging guide for specific issues
+                * When: Encountering difficult-to-reproduce or complex issues
+                * Content: Debug steps, log analysis, diagnostic commands
+                * Examples: `API_INTEGRATION_DEBUG.md`, `PERFORMANCE_DEBUG.md`
+
+             4. **FIX.md**: Solution record for specific fixes
+                * When: Implementing a fix after investigation
+                * Content: Problem, solution, code changes, verification
+                * Examples: `AUTH_BYPASS_FIX.md`, `DATA_CORRUPTION_FIX.md`
+
+             5. **VERIFICATION.md**: Verification results and testing
+                * When: Complex verification logic or cross-platform testing
+                * Content: Test methods, results, edge cases covered
+                * Examples: `CROSS_PLATFORM_VERIFICATION.md`, `SECURITY_TEST_VERIFICATION.md`
+
+             6. **SUMMARY.md**: Implementation summary for complete features
+                * When: Completing a major feature or encoding implementation
+                * Content: Overview, files changed, key decisions, lessons learned
+                * Examples: `PAYMENT_SYSTEM_SUMMARY.md`, `FILE_SYNC_SUMMARY.md`
+
+             7. **{TOPIC}_RUN_GUIDE.md**: Operational run guide for a test suite/tool 🧪 [WHO / WHEN / WHAT / WHERE]
+                * WHO (writer): `/specpro-implement` — run guides are work products of development tasks (tasks.md work, including unit tests). NEVER written by test-plan/test-implement
+                * WHEN (trigger): MANDATORY whenever a user story delivered or changed unit tests — create or update the affected test module's run guide BEFORE marking the story complete. NOT one guide per story: ONE guide per test module/source set, incrementally extended as later stories add tests to the same module
+                * WHAT (minimum content): (1) suite inventory — test class ↔ tasks.md task ID ↔ FR; (2) how to run all / single class / single method / by package; (3) expected output on success; (4) how to view test results and coverage reports; (5) failure debugging steps; (6) common problems / FAQ; (7) quick command reference
+                * WHERE (location): `docs/implement/` — never `docs/test/`, never the repository root; register in PROJECT_NAVIGATION.md
+                * **Grounding iron rule ⚠️**: every command in the guide MUST have been actually executed with its output observed BEFORE being written into the guide. Never document an unverified module path, task name, or report path — a decoupled run guide misleads humans and AI alike (the documentation-form of running against nonexistent infrastructure)
+                * Examples: `RUN_UNIT_TESTS_GUIDE.md` (one per unit-test module), `RUN_E2E_SUITE_GUIDE.md`
+
+             8. **PROJECT_NAVIGATION.md**: Development docs main index (fixed name)
+                * When: Create UP-FRONT (when `docs/implement/` is set up) or at the latest when the FIRST technical document is produced — project documentation is assumed to be multi-document, do NOT wait for multiple topics
+                * Content: Topic location table with US/FR/keyword mappings
+                * Location: `docs/implement/PROJECT_NAVIGATION.md` (conventional)
+
+             9. **index.md**: Topic-specific navigation (pattern-based name)
+                * When: Topic has 3+ documents or needs detailed navigation
+                * Content: Document list, status, reading order, task mappings
+                * Location: `docs/implement/{topic}/index.md`
+                * Note: `{topic}` is variable (examples: `authentication/`, `storage/`, `api/`)
+
+           - **Content organization principles**:
+             * **Problem-oriented**: Start with problem, then solution
+             * **Evidence chain**: Include logs, code snippets, test results
+             * **Verifiability**: Provide reproduction steps, test methods
+             * **Timestamps**: Include dates for timeline tracking
+             * **Cross-references**: Link to related documents
+             * **Language**: Follow project constitution's language policy
+
+           - **Navigation maintenance best practices** 📋:
+             * **Start simple**: Begin with just Topic Index table, add reverse indexes later
+             * **Batch updates**: Update all indexes in one edit (not multiple separate edits)
+             * **Use verification checklist**: ALWAYS run Step 5 verification after updates
+             * **Keep keywords minimal**: 3-5 keywords per topic max
+             * **Consistent format**: Use exact same format as template
+             * **Read before write**: Read entire PROJECT_NAVIGATION.md before editing
+             * **Test links**: After update, click each link to verify they work
+
+           - **Directory structure** (illustrative - adapt to your project):
+             ```
+             project-root/
+             ├── specs/                         # SpecPro workflow (spec, plan, tasks, contracts, etc.)
+             ├── docs/                          # All project documentation
+             │   ├── user/                      # User requirements documentation
+             │   │   ├── user-stories.md
+             │   │   └── use-cases.md
+             │   ├── reference/                 # Design reference documentation
+             │   │   ├── architecture.md
+             │   │   ├── data-model.md
+             │   │   └── api-reference.md
+             │   ├── implement/                 # Development process documentation (conventional)
+             │   │   ├── PROJECT_NAVIGATION.md  # Main index (create up-front or with the first document)
+             │   │   ├── authentication/        # Example topic 1 (actual name varies)
+             │   │   │   ├── index.md          # Topic navigation (recommended for 3+ docs)
+             │   │   │   ├── OAUTH_FORMAT.md   # Example doc (pattern-based name)
+             │   │   │   └── AUTH_FIX.md      # Example doc (pattern-based name)
+             │   │   ├── storage/              # Example topic 2 (actual name varies)
+             │   │   │   ├── index.md
+             │   │   │   └── DATABASE_MIGRATION_ROOT_CAUSE.md
+             │   │   └── [other topics]        # Your project's topics
+             │   ├── user_manual/               # User manual
+             │   │   ├── getting-started.md
+             │   │   └── user-guide.md
+             │   └── developer_manual/          # Developer manual
+             │       ├── setup.md
+             │       ├── contribution-guide.md
+             │       └── api-reference.md
+             └── [other project files...]
+             ```
+             **Note**: Topic names (`authentication/`, `storage/`) are EXAMPLES. Use names appropriate for your project.
+             ```
+             *Benefits*: Clear category separation, centralized docs, clean root directory, follows community conventions
+
+             **Structure principles**:
+             - **Centralized in docs/**: All documentation under one directory — NEVER place documents in the repository root (violation example: a run guide left at project root instead of under docs/)
+             - **Categorized by purpose**: user/, reference/, implement/, test/, user_manual/, developer_manual/
+             - **Development docs in implement/**: Grouped by topic/FR
+             - **docs/ root = project-level/stakeholder documents only** (e.g., plain-language overviews of significant changes for non-specialist readers); create ONLY on explicit user request, never spontaneously
+             - **Two-level navigation**: PROJECT_NAVIGATION.md (location) → {topic}/index.md (details)
+             - **Shallow hierarchy**: Max 2-3 levels deep (docs/implement/topic/filename.md)
+             - **Ownership boundary ⚠️**: document LOCATION follows the ownership of the work that produced it, NOT the document's topic. Docs produced by development tasks (tasks.md — including unit tests and their run guides) belong to `docs/implement/`, even when the subject is testing. NEVER write into `docs/test/` from this command — that directory belongs to `/specpro-test-implement` (work products of test-tasks.md execution: INF/IT/CE/AE)
+
+           - **File naming conventions**:
+             * Use `{FEATURE}_{TYPE}.md` pattern for feature-specific docs
+             * Use descriptive names: `MEMORY_LEAK_ROOT_CAUSE.md` (not `fix3.md`)
+             * Avoid numbers in filenames (use dates in content instead)
+             * Keep names under 50 characters for readability
+
+           - **Document templates**:
+
+             **PROJECT_NAVIGATION.md template** (main navigation - location lookup):
+             ```markdown
+             # Development Process Documentation Navigation
+
+             **Last Updated**: [YYYY-MM-DD]
+
+             ---
+
+             ## Topic Index
+
+             | Topic | Location | US | FR | Keywords |
+             |-------|----------|-----|-----|----------|
+             | [{Topic}](topic/index.md) | `docs/implement/topic/` | [US-numbers] | [FR-numbers] | [keyword1, keyword2, ...] |
+
+             ## Reverse Index
+
+             ### By User Story
+             - **US-{N}**: [{Topic}](topic/index.md), [{Topic}](topic2/index.md)
+
+             ### By Functional Requirement
+             - **FR-{N}**: [{Topic}](topic/index.md)
+
+             ### By Keyword
+             - **{keyword}**: [{Topic}](topic/index.md), [{Topic}](topic2/index.md)
+             ```
+
+             **{topic}/index.md template** (topic navigation - detailed information):
+             ```markdown
+             # {Topic} Documentation
+
+             **Related**: US-{N}, FR-{N}
+             **Keywords**: [keyword1, keyword2, ...]
+
+             ---
+
+             ## Documents
+
+             | Document | Type | Status | Purpose | Updated |
+             |----------|------|--------|---------|---------|
+             | [{DOC1}.md]({DOC1}.md) | [Format/Root Cause/Fix/Summary] | [✅ Complete / 🚧 In Progress] | [Purpose] | [YYYY-MM-DD] |
+
+             ## Reading Order
+
+             **Beginners**:
+             1. {DOC}.md
+             2. {DOC}.md
+
+             **Debugging**:
+             1. {DOC}.md
+             2. {DOC}.md
+
+             ## Related Tasks
+
+             - T-{N}: [Task description]
+             - T-{N}: [Task description]
+
+             ## Key Insights
+
+             - [Key point 1]
+             - [Key point 2]
+             ```
+
+             **ROOT_CAUSE.md template**:
+             ```markdown
+             # {Feature} Root Cause Analysis
+
+             ## Problem
+             - **Symptom**: [What went wrong]
+             - **Impact**: [Severity, affected components]
+             - **Timeline**: [When discovered, duration to fix]
+
+             ## Investigation
+             ### Step 1: [Initial approach]
+             - Finding: [What was discovered]
+             - Evidence: [Logs, code snippets]
+
+             ### Step 2: [Next approach]
+             - Finding: [More discoveries]
+             - Evidence: [More evidence]
+
+             ## Root Cause
+             - **Primary cause**: [The actual root cause]
+             - **Contributing factors**: [Other factors]
+
+             ## Solution
+             - **Fix**: [What was changed]
+             - **Files**: [List of modified files]
+             - **Verification**: [How fix was verified]
+             ```
+
+             **SUMMARY.md template**:
+             ```markdown
+             # {Feature} Implementation Summary
+
+             ## Overview
+             - **Feature**: [Feature description]
+             - **Duration**: [Start date] - [End date]
+             - **Status**: [Complete/Incomplete]
+
+             ## Files Changed
+             - `path/to/file1`: [Change description]
+             - `path/to/file2`: [Change description]
+
+             ## Key Decisions
+             1. [Decision 1 with rationale]
+             2. [Decision 2 with rationale]
+
+             ## Challenges Solved
+             1. [Challenge 1 and solution]
+             2. [Challenge 2 and solution]
+
+             ## Lessons Learned
+             - [What to avoid next time]
+             - [Best practices discovered]
+
+             ## Related Documents
+             - [{RELATED_DOC}.md]: [Brief description]
+             ```
+
+           - **When to update docs/implement/PROJECT_NAVIGATION.md**:
+             * When adding a new topic folder
+             * When US/FR/keyword mappings change
+             * Update: Add entry to Topic Index table, update reverse indexes
+
+           - **First-time creation** ⚠️ [UP-FRONT or with the first document]:
+             * Assume project documentation will be multi-document: create `docs/implement/PROJECT_NAVIGATION.md` UP-FRONT (when `docs/implement/` is set up) or at the latest when the FIRST technical document is produced — do NOT wait for multiple topics
+             * If it does not exist yet when an update is needed, CREATE it from the template below BEFORE applying any update step
+             * Start simple: initial content = title + Last Updated + Topic Index table only; add the Reverse Index sections incrementally as topics accumulate
+
+           - **How to update PROJECT_NAVIGATION.md correctly** ⚠️ [CRITICAL]:
+             **Step 1: Update Topic Index table**:
+             - Add row for new topic: `| [{Topic}](topic/index.md) | docs/implement/topic/ | US-{N} | FR-{N}, FR-{N} | keyword1, keyword2 |`
+
+             **Step 2: Update "By User Story" section**:
+             - Find or create entry for US-{N}
+             - Add topic link: `**US-{N}**: [{Existing Topic}](topic1/index.md), [{New Topic}](topic2/index.md)`
+             - Ensure each US links to ALL related topics
+
+             **Step 3: Update "By Functional Requirement" section**:
+             - For EACH FR listed in Topic Index table:
+               * Create entry: `**FR-{N}**: [{Topic}](topic/index.md)`
+               * If FR maps to multiple topics, list all: `**FR-{N}**: [{Topic1}](topic1/index.md), [{Topic2}](topic2/index.md)`
+
+             **Step 4: Update "By Keyword" section**:
+             - For EACH keyword listed in Topic Index table:
+               * Find or create entry for keyword
+               * Add topic link: `**{keyword}**: [{Topic}](topic/index.md), [{Another Topic}](topic2/index.md)`
+               * Keep keyword list short (3-5 per topic)
+
+             **Step 5: Verify consistency** ✅ [QUALITY CHECK]:
+             - For EACH topic in Topic Index table:
+               * US numbers exist in "By User Story" section? ✅/❌
+               * ALL FR numbers exist in "By Functional Requirement" section? ✅/❌
+               * ALL keywords exist in "By Keyword" section? ✅/❌
+             - No orphan entries in reverse indexes (topics not in table)? ✅/❌
+             - Table row count matches number of topics? ✅/❌
+
+           - **When to create docs/implement/{topic}/index.md**:
+             * Topic has 3+ documents
+             * Topic needs detailed navigation (reading order, task mappings)
+             * Create in topic folder, link from PROJECT_NAVIGATION.md
+
+           - **Documentation maintenance**:
+             * Review docs when related features change
+             * Mark obsolete docs as `[DEPRECATED]` at top
+             * Cross-link related docs for better navigation
+             * Use Git history for old versions (don't keep multiple copies)
+
+           - **Quality checklist** before saving:
+             ✅ Problem is clearly described
+             ✅ Evidence/log snippets included
+             ✅ Solution is reproducible
+             ✅ Related docs are cross-referenced
+             ✅ Filename follows naming convention
+             ✅ Document is in correct location
+
+           - **Example: Updating PROJECT_NAVIGATION.md when adding new topic**:
+             **Scenario**: Adding new topic "storage" with docs at `docs/implement/storage/`
+             **Mapping**: US-3, FR-xxx, FR-yyy, Keywords: database, migration, storage
+
+             **Before** (Topic Index table):
+             ```markdown
+             | Topic | Location | US | FR | Keywords |
+             |-------|----------|-----|-----|----------|
+             | [Authentication](authentication/index.md) | docs/implement/authentication/ | 1 | 101, 102 | oauth, login, auth |
+             ```
+
+             **After** (Topic Index table):
+             ```markdown
+             | Topic | Location | US | FR | Keywords |
+             |-------|----------|-----|-----|----------|
+             | [Authentication](authentication/index.md) | docs/implement/authentication/ | 1 | 101, 102 | oauth, login, auth |
+             | [Storage](storage/index.md) | docs/implement/storage/ | 3 | 301, 302 | database, migration, storage |
+             ```
+
+             **Reverse indexes updates**:
+             ```markdown
+             ### By User Story
+             - **US-1**: [Authentication](authentication/index.md)
+             - **US-3**: [Storage](storage/index.md)  # NEW
+
+             ### By Functional Requirement
+             - **FR-xxx**: [Authentication](authentication/index.md)
+             - **FR-xxx**: [Authentication](authentication/index.md)
+             - **FR-xxx**: [Storage](storage/index.md)  # NEW
+             - **FR-xxx**: [Storage](storage/index.md)  # NEW
+
+             ### By Keyword
+             - **oauth**: [Authentication](authentication/index.md)
+             - **database**: [Storage](storage/index.md)  # NEW
+             - **migration**: [Storage](storage/index.md)  # NEW
+             - **storage**: [Storage](storage/index.md)  # NEW
+             ```
+
+             **Verification**:
+             - ✅ Storage row added to table
+             - ✅ US-3 added to User Story index
+             - ✅ FR-xxx, FR-yyy added to FR index
+             - ✅ database, migration, storage added to Keyword index
+             - ✅ No orphan entries
+             - ✅ Table has 2 rows (Authentication + Storage)
+
+      - **Parallel tasks** `[P`:
+         * **For each parallel task**:
+           - Extract target files from task description
+           - Identify task type (test vs implementation)
+           - Check Test-First compliance (same as single task)
+           - Check file existence and read existing code (same as single task)
+           - Verify no file conflicts with other parallel tasks
+           - Execute based on task type (same as single task)
+         * **Mark successful tasks as `[x]`**
+         * **Report failed tasks without halting** (parallel failure tolerance)
+
+   e. **Task completion and exit decision** ⚠️ [CRITICAL - CONTEXT MANAGEMENT]:
+      - **Track executed task count**: Initialize counter at 0, increment after each task completion
+
+      - **Checkpoint Gate** 🧪 [TESTPLAN TIMING — fires when a User Story phase boundary is crossed]:
+        **Purpose**: The optimal moment to run `/specpro-test-plan` is right after a story's implementation lands (newly implemented modules become testable; the incremental mode converts their matrix rows from `pending-impl` to real tasks). Without this gate, continuous modes (`--continue`, `--phase`, large `--count`) would blow through story boundaries and the user loses that timing. Do NOT add pseudo "pause" tasks to tasks.md for this — the gate lives here, in the executor.
+
+        **Trigger detection**: after completing a task, check whether the just-completed task was the LAST pending task of its **User Story phase** (phase with `[US#]` labels — Setup/Foundational/Polish do NOT trigger the gate).
+
+        **If triggered, compute test-plan relevance** (cheap checks, in order):
+        1. `specs/test-tasks.md` does not exist → **HIGH** (test system not built yet)
+        2. `spec.md` last-modified more recently than `specs/test-tasks.md` → **HIGH** (spec changed since last test plan)
+        3. Any FR annotated on tasks completed **in this story** has matrix row status `pending-impl` (or is absent from the matrix) → **HIGH** (newly testable — the exact incremental-mode use case)
+        4. Otherwise → **LOW**
+
+        **On HIGH relevance — PAUSE** (in EVERY mode, including `--continue`/`--phase`) and show the story-completion menu:
+        ```markdown
+        🎯 User Story [US#] implementation complete — Checkpoint
+
+        **Test-plan relevance**: HIGH
+        - [reason: e.g. "spec.md changed after last test-plan run" / "FR-0xx newly testable (matrix row pending-impl)"]
+
+        **Options**:
+        1. Continue to next story
+        2. Run `/specpro-test-plan` (incremental) now, then continue
+        3. Run `/specpro-test-implement` now (execute pending test tasks), then continue
+        4. End this session
+
+        Your choice (1-4):
+        ```
+        - Choice 2: hand off to `/specpro-test-plan` (its change-log-driven incremental mode processes exactly the drifted/newly-testable FRs), then resume this session at the user's discretion
+        - Choice 3: hand off to `/specpro-test-implement` (dual write-back keeps the matrix in sync), then resume
+        - Choice 4: exit via the normal exit path with the completion report
+
+        **On LOW relevance — do NOT interrupt**: set `TESTPLAN_HINT=true` and continue; the hint surfaces in the exit report only.
+
+      - **Check exit conditions** (in order of priority):
+         1. **`--once` mode**: Exit after 1 task completed
+         2. **`--count N` mode**: Exit after N tasks completed
+         3. **`--phase PHASE` mode**: Exit when phase completes or no pending tasks in phase
+         4. **`--continue` mode**: Continue until all tasks complete (⚠️ WARNING: Context may overflow)
+         5. **No more tasks**: Exit when scan finds no `[ ]` tasks (all are `[x]`)
+
+      - **Before exit**:
+         * Report completion summary: "Executed N tasks in this session"
+         * Show remaining progress: "Overall progress: X/Y tasks completed (Z%)"
+         * **If `TESTPLAN_HINT=true` OR the session ended at a User Story boundary**: append the test-timing hint:
+           ```markdown
+           🧪 Test Timing Hint:
+           - A User Story just completed — this is the optimal checkpoint for test planning.
+           - Run `/specpro-test-plan` (incremental if specs/test-tasks.md exists) to register newly
+             testable FRs, then `/specpro-test-implement` to execute pending test tasks.
+           ```
+         * **If tasks remain**: Provide clear instructions:
+           ```markdown
+           ⚠️ Session complete to prevent context overflow.
+
+           **Progress**: X/Y tasks completed (Z%)
+
+           **Next Steps**:
+           - Run `/specpro-implement` again to continue implementation
+           - Progress is preserved (completed tasks marked [x])
+
+           **Or execute multiple tasks**:
+           - `/specpro-implement --count 5` (Execute next 5 tasks)
+           - `/specpro-implement --phase Foundational` (Execute entire Foundational phase)
+           ```
+
+   f. **Final validation** (only when no tasks remain):
+      - When scan finds no `[ ]` tasks (all are `[x]`)
+      - Proceed to step 14 (final validation)
+
+10. **Error handling and recovery** ⚠️:
+   a. **Sequential task failure**:
+      - Halt execution immediately
+      - Display error with context (file, line, error message)
+      - Suggest next steps to fix
+      - **Do NOT mark failed task as `[x]`
+      - User can re-run `/specpro-implement` after fix (task remains `[ ]`)
+
+   b. **Parallel task failure** `[P`:
+      - Continue executing other parallel tasks
+      - Collect all failures
+      - Report summary: "X of Y parallel tasks succeeded"
+      - Mark only successful tasks as `[x]`
+      - Failed tasks remain `[ ]` for next run
+
+   c. **Validation failure**:
+      - Tests fail → Do NOT mark as `[x]`, display test output
+      - Compilation errors → Do NOT mark as `[x]`, display errors
+      - User must fix and re-run
+
+11. **Progress reporting** 📊:
+   - After each task completion: Display "✓ Completed: [task description]" (use `PROJECT_LANGUAGE` from Step 4)
+   - For parallel tasks: Display "✓ Completed X/Y parallel tasks"
+   - Show cumulative count: "Progress: N/M tasks completed"
+   - Display current phase: "Current phase: [Setup/Foundational/US-XXX/Polish]"
+
+12. **Task completion tracking** ✅:
+   - **CRITICAL**: Always mark completed tasks as `[x]` in tasks.md
+   - Use Edit tool to update task status
+   - Preserve task description and metadata
+   - Only change `[ ]` → `[x]`
+   - This enables resumable execution (interrupted runs continue from last `[ ]`)
+
+13. **Issue recording and feedback** 🔄 [WORKFLOW CLOSURE]:
+   - **Purpose**: Record issues found during implementation for feedback to earlier phases
+
+   - **Tool defects route through the ledger, not a side registry** ⚠️ [T089 · FR-023]: if the defect you found is in **specpro itself** (this project's command documents, templates, or support scripts — when a project bootstraps specpro, those **are** the project's product), route it by ONE criterion: **does spec.md already demand the corrected behavior?**
+     1. **Not demanded yet** → establish the requirement FIRST: register a `[specify]` entry naming the tool-source file and the missing requirement. `/specpro-specify --review-issues` amends spec.md; the fix then flows down the chain ([plan] → [tasks]) and returns as an executable task. Bypassing the requirement layer produces a task backed by no requirement — and a task with no requirement behind it cannot be verified against anything.
+     2. **Already demanded** → the requirement exists and the tool fails it: register a `[tasks]` entry naming the tool-source file. `/specpro-implement` discharges it by executing a task whose Location names that file — the same single entry tool source has always had.
+   - **Why no side registry** ⚠️: a defect written to a file no command consumes is indistinguishable from one never reported (FR-023 — a record only human convention reads does not satisfy routing). The former side registry was absorbed into the spec chain and deleted (`T089`); where history needs its entry IDs, cite them as 「原 TOOL-0NN」 — a historical label, never a live pointer.
+   - **When to use**: When implement discovers problems with spec/plan/tasks
+   - **Not to be confused** ⚠️: product-defect FIX TASKS dispatched by `/specpro-test-implement` live in `specs/fix-tasks.md` (FT-XXX, executed via `execution_mode = "fix"` in Step 9.a2). `implement_issues.md` is exclusively for **planning-artifact feedback** — errors in a *plan* (spec / plan / tasks / test-tasks), never errors in *execution* (an execution error is fixed in place, or dispatched as an FT when it is product code)
+   - **Governing rule** ⚖️: **a planning error is fixed by the planner, an implementation error by the implementer.** Record an issue only against an artifact whose planner consumes that section — filing into a section no one legitimately consumes is a boundary violation, not thoroughness
+
+   a. **Check if issues exist**:
+      - Review implementation problems encountered
+      - Classify by phase: [specify], [plan], [tasks], or [constitution] — the sections whose planners are the `--review-issues` commands below
+      - Recognise the remaining section without resolving it: **[test-plan]** holds planning errors in `specs/test-tasks.md`, reported by `/specpro-test-implement` (its Step 11) and fixed by `/specpro-test-plan`. You may **append** a new `[test-plan]` issue if you genuinely find such a defect (that is correct routing to its planner), but you never mark one `[x]`
+      - Examples:
+        * **[specify]**: Missing requirements, unclear specifications, conflicting requirements
+        * **[plan]**: Unreasonable design, impossible to implement, design conflicts
+        * **[tasks]**: Incorrect task descriptions, missing tasks, wrong task order, duplicate tasks
+
+   b. **Record issues in specs/implement_issues.md**:
+      ```markdown
+      ## [specify] Phase Issues
+
+      Issues related to functional requirements: missing, unclear, conflicting, etc.
+      - [ ] ISS-XXX: [Issue description]
+
+      ## [plan] Phase Issues
+
+      Issues related to design approach: unreasonable, conflicting, unachievable, etc.
+      - [ ] ISS-XXX: [Issue description]
+
+      ## [tasks] Phase Issues
+
+      Issues related to task descriptions: incorrect, duplicate, missing, ordering, etc.
+      - [ ] ISS-XXX: [Issue description]
+
+      ## [test-plan] Phase Issues
+
+      Issues related to test planning: coverage-matrix rows, task location/source/verdicts, task-annotation consistency, etc.
+      - [ ] ISS-XXX: [Issue description]
+      ```
+
+      ⚠️ **The template shows the sections in their canonical order — it is NOT a licence to append to the file's end.** The live file may carry additional sections and interleaved content; find the section this issue belongs to and append **inside it**.
+
+   b2. **Entry placement** ⚠️ [a silent-corruption failure mode, observed 2026-09-12]:
+      - Append the new entry to the **end of its own section** — i.e. after that section's last existing entry, and **before** the next `## […] Phase Issues` heading. **Never append to the end of the file.**
+      - **Why this is not cosmetic**: "append to the end of the file" is correct only for whichever section happens to be last. For every other section it silently files the issue where its consuming stage will never read it — the entry looks registered, the statistics table looks plausible, and nothing errors. This exact failure occurred: an `[tasks]`-side issue was appended to the file end and landed in the last section (`[test-plan]`), where that section's consumer has no mandate to act on it.
+      - **Verify mechanically after writing** (one command, no judgement):
+        ```bash
+        .specpro/scripts/bash/verify-ledger.sh
+        ```
+        One pass checks: every entry sits inside a section (nothing past the end-of-file sentinel), the statistics table matches the actual per-section counts, and the file ends with exactly one newline. Non-zero exit names the violation — fix it before continuing. A pre-commit hook enforces the same check, so a violation blocks the commit rather than being discovered later.
+      - **Update that section's row** in the statistics table at the top (Total +1, Pending +1 unless you also resolved it). A section whose entry count and statistics row disagree is the same defect wearing a different hat — `verify-ledger.sh` reports it as a count mismatch.
+      - **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.
+
+   c. **Issue format**:
+      - Use format: `- [ ] ISS-XXX: [Description]`
+      - XXX: Auto-increment number (001, 002, 003, ...)
+        ⚠️ **Take the next number with a NUMERIC sort — this is the command, and the
+        reason is not stylistic** (`T206` / `ISS-166`):
+        ```bash
+        # next ISS id = current maximum + 1
+        grep -oE '^- \[[x ]\] ISS-[0-9]+:' specs/implement_issues.md \
+          | grep -oE '[0-9]+' | sort -n | tail -1
+        ```
+        ⚠️ **`sort` without `-n` is WRONG here and fails silently.** The IDs are
+        **variable width**, so lexicographically `ISS-100` sorts *before* `ISS-97`
+        (`"1" < "9"`). Measured 2026-09-19: `… | sort -u | tail -1` returned `99` while
+        the true maximum was `161` — following it would have **reused an existing ID**.
+        ⚠️ **The former tool-defect clause (原 TOOL-011, deleted by `T089`) used `sort -u`
+        in its example — CORRECT for its subject**: that
+        one numbered fixed-width three-digit IDs, where lexicographic and
+        numeric order coincide. Copying it here is the mistake; the example is not at
+        fault, the copying is. (Same family as `TOOL-009`: an example is copied
+        verbatim, so it must be correct *for the artifact it is applied to*.)
+        ⚠️ **And a collision is not self-announcing**: the IDs are how `--review-issues`
+        runs ADDRESS entries, so two entries sharing one make the address name neither —
+        while the statistics table still reconciles if its counts are bumped to match.
+        `verify-ledger.sh` now carries that invariant (its check 7); this command is the
+        writer side of it.
+      - Description: Clear, concise problem statement
+      - Example: `- [ ] ISS-xxx: FR-xxx missing implementation details for error handling`
+
+   d. **After recording issues**:
+      - Display summary: "⚠️ N issues recorded in specs/implement_issues.md"
+      - Show breakdown: "[specify]: X, [plan]: Y, [tasks]: Z, [test-plan]: W, [constitution]: V" (omit a section when its count is 0)
+      - Provide next steps:
+        ```markdown
+        **Issues recorded during implementation**
+
+        To fix these issues, run commands in order:
+        1. /specpro-specify --review-issues  (Fixes [specify] issues, marks them [x])
+        2. /specpro-plan --review-issues     (Updates plan.md based on changes)
+        3. /specpro-tasks --review-issues    (Updates tasks.md based on changes)
+        4. /specpro-implement                (Continue implementation)
+
+        If any [test-plan] issues were recorded, resolve them separately:
+        /specpro-test-plan   (incremental run — updates specs/test-tasks.md, marks them [x])
+
+        Each command only marks issues in its own section as [x].
+        ```
+
+   e. **Issue resolution workflow**:
+      - **NOT in scope**: Implement command should NOT fix these issues
+      - **User workflow**:
+        1. User reviews issues in implement_issues.md
+        2. User runs `/specpro-specify --review-issues`
+           - Reads [specify] section issues
+           - Applies fixes to spec.md
+           - Marks [specify] issues as [x]
+        3. User runs `/specpro-plan --review-issues`
+           - Detects spec.md changes
+           - Updates plan.md accordingly
+           - Marks [plan] issues as [x]
+        4. User runs `/specpro-tasks --review-issues`
+           - Detects plan.md changes
+           - Updates tasks.md accordingly
+           - Marks [tasks] issues as [x]
+        5. User runs `/specpro-implement` to continue
+        6. If any `[test-plan]` issues exist, the user runs `/specpro-test-plan` (incremental)
+           - Reads the [test-plan] section issues
+           - Updates `specs/test-tasks.md` accordingly
+           - Marks [test-plan] issues as [x]
+           - This is NOT part of the phase order below — it is a separate track that
+             must run before `/specpro-test-implement` resumes against test-tasks.md
+      - **Sequential processing**: Issues must be fixed in phase order (specify → plan → tasks). `[test-plan]` sits outside that chain (test-tasks.md downstream of plan/tasks, not between them)
+
+   f. **Do NOT halt execution**:
+      - Implement should continue even if issues are found
+      - Issues are recorded for later resolution
+      - Only halt for CRITICAL blocking issues (from Step 2 analysis)
+
+13.5. **Git commit at batch boundaries** 🆕 [PERSISTENCE — repo stays buildable & traceable]:
+   - **Purpose**: Persist task outputs to version control at controlled granularity. Prevents the "entire implementation phase completed with zero commits" failure class (fresh clone unbuildable, one giant commit hiding all intermediate states, no regression anchors for incident investigation). This step is part of workflow closure, NOT optional housekeeping.
+
+   **Trigger rules — commit timing is DECOUPLED from the execution mode** (the mode decides session length only; commit granularity is fixed by these two rules):
+   - **a. Internal cadence** [MANDATORY for unbounded mode]: immediately after crossing any logical-group boundary (Phase / user story / task group), commit once. In unbounded mode (no execution-mode argument) this is a HARD requirement — never let an unbounded session accumulate into one giant commit.
+   - **b. Session closure** [MANDATORY for ALL modes — `--once` / `--count N` / `--phase` / unbounded / group]: before the completion report, commit everything the session produced but has not yet committed.
+
+   **Multi-repository layout — one commit per repository, not one commit per trigger** ⚠️:
+   The artifacts this step persists can live in **different repositories**, and a single `git add` + commit **cannot span repositories**. Before committing, determine which repository each changed path belongs to — typically by checking whether the path's containing directory has its own `.git`:
+
+   - Some projects keep plan/task artifacts in a **separate repository** from the implementation source (e.g. a nested repo mounted at the specs directory).
+   - Others keep everything in one repository — in that case the per-repository split below collapses into the single original commit.
+
+   Resolve it per project; do not assume. When a trigger fires, issue **one commit per repository that has changes**, each with a message describing **that repository's** changes. Never use one generic message across repositories — it produces a history that describes nothing.
+
+   **Path form — every path is expressed relative to its owning repository** ⚠️ (FR-027): this is a **different obligation** from the grouping below, and getting the grouping right while still writing `specs/...` fails whenever the project root is not the owning repository. When you commit in repository `R`, every path passed to `git -C "$R" add` MUST be expressed **relative to `R`** — never as an absolute path, and never as a literal prefix that is only correct when the project root *is* `R` (the common instance: a hardcoded `specs/...`).
+   ```bash
+   # $R = the path's owning repository — resolved above, from the path's own containing
+   #      directory, NOT from the project root
+   # Use the Python form directly — macOS `realpath(1)` has no --relative-to.
+   # ⚠️ `os.path.realpath` on BOTH sides is the whole point (ISS-144): `os.path.relpath` only
+   # compares literal prefixes, and `git rev-parse --show-toplevel` returns a PHYSICAL path while
+   # a path built with `cd … && pwd` is logical — reached through a symlink the two share no
+   # prefix and relpath walks ABOVE the repository (reproduced with `/tmp` → `/private/tmp`).
+   # ⚠️ Copied verbatim in `specpro.specify.md` and `specpro.test-implement.md` — change all three.
+   relpath() { python3 -c 'import os,sys;print(os.path.relpath(os.path.realpath(sys.argv[2]),os.path.realpath(sys.argv[1])))' "$1" "$2"; }
+   git -C "$R" add -- "$(relpath "$R" "$ARTIFACT")"
+   ```
+
+   **What to commit** — grouped by which repository it belongs to:
+   - **In the repository holding the plan/task artifacts**: the task list (checkbox + annotation updates) and the issues ledger (if new entries were recorded)
+   - **In the repository holding the implementation** (often the project root, and possibly different from the above): implementation sources and tests written or executed during the batch; build/config files the tasks created or changed
+   - **Wherever the documentation lives**: work documentation produced by the tasks (per docs ownership rules, e.g. `docs/implement/...`)
+
+   **What NOT to commit**:
+   - Debug artifacts already disposed as DELETE (removed), and anything under `tmp/debug/` or gitignored paths
+   - Files excluded by the project's `.gitignore` policy (AI-tool files, local-only artifacts) — respect it, never `git add -f`
+
+   **Commit message**: `<type>(<scope>): <task-range> <one-line summary> — <validation verdict>`
+   Example: `feat(protocol): T-xxx~T-yyy remote viewing — 12/12 tests green`
+   Task range + validation verdict make the git history double as the execution audit trail.
+
+   When the change spans repositories, each message is **written for its own repository**, not reused:
+   - Implementation repository → the `<type>(<scope>)` form above.
+   - Plan/task artifact repository → the same task range, but stated against what changed there, e.g. `tasks: T-xxx~T-yyy marked complete — <verdict>`. Its history must read as the *plan's* history, not as a duplicate of the code repository's.
+
+   **Tracked-deliverable gate** ⚠️ [before the completion report — T150 / ISS-56 ②]:
+   every deliverable the batch produced must actually be **tracked**, not merely written to disk —
+   a file that exists but was never `git add`ed survives on this machine only, and nothing
+   else reports the difference. Run the re-runnable assertion:
+
+   ```bash
+   scripts/bash/verify-deliverables-tracked.sh     # PowerShell twin: scripts/powershell/verify-deliverables-tracked.ps1
+   ```
+
+   Non-zero exit names the untracked deliverable — commit it before closing the batch.
+   (Scope note: the assertion covers the deliverable source dirs and the artifact repos;
+   root-level session transcripts are NOT deliverables and are out of its scope by
+   construction — ISS-75.)
+
+   **If nothing to commit** (pure-analysis batch, or all outputs gitignored): state "nothing to commit" and move on.
+
+14. **Final validation** ✨:
+    - Verify no `[ ]` tasks remain in tasks.md
+    - **Frontmatter-YAML assertion** 🆕 [T152 / ISS-59 ① · ISS-81]: every frontmatter block in `commands/*.md` MUST parse — an unparseable block and a missing block are indistinguishable to every executor (the `handoffs:` topology and the `writes:` ownership map both live there). Run:
+        ```bash
+        scripts/bash/verify-frontmatter-yaml.sh      # PowerShell twin: scripts/powershell/verify-frontmatter-yaml.ps1
+        ```
+        Non-zero exit names the failing file. Templates carry no frontmatter and are out of scope (ISS-81); the deployed mirror is covered by scanning the source side (deployment-verified byte-identical).
+    - Run full test suite: `./gradlew test` or `npm test` or equivalent (detect from project)
+    - **Code coverage acceptance** 🧪 [CONCRETE PROCEDURE — "verify they are met" by assumption is a false completion]:
+      1. **Locate thresholds**: read plan.md "Quality Targets" → "Risk-Based Coverage Targets" table (per risk level); tasks.md `[Quality]` coverage tasks may refine them
+      2. **Produce evidence**: run the project's coverage tooling (e.g., JaCoCo report task) and locate the ACTUAL report file (HTML/XML). Confirm the report path exists before quoting any number — a referenced-but-missing report is a false completion
+      3. **Compare per module**: classify measured modules by risk level and compare measured vs target PER MODULE — never a project-wide average (an average can mask an untested HIGH-RISK module)
+      4. **Verdict**:
+         * All HIGH-RISK / MEDIUM-RISK modules meet targets → record measured numbers + report path in the completion report
+         * Any module below target → do NOT report complete; record an issue in `specs/implement_issues.md` ([plan]/[tasks] as appropriate) and report the gap with measured numbers
+         * Coverage tooling NOT configured despite targets existing → do NOT silently skip; record an issue ([tasks]: coverage measurement infrastructure missing) and surface it to the user
+      5. **No numeric target to compare against** — **two distinct cases, one branch** (`T250` / `ISS-226`):
+         * **(5a) no targets defined anywhere** (no plan.md targets, no `[Quality]` coverage tasks, no constitution mandate) → skip, but state "coverage: no targets defined" explicitly in the report.
+         * **(5b) the target exists but is NOT a number** — the `Risk-Based Coverage Targets` table carries a **replacement standard** instead of percentages (clause ids, a named manual procedure). ⚠️ **This used to fall through**: step 1 reads "the table" as if it held thresholds, steps 2–4 then have nothing to compare against, and the old wording of this step ("*No targets defined anywhere*") does **not** fire because a target *is* defined — just not in the form steps 2–4 assume. ⇒ When the cells are not numbers: **follow the standard the table states** (it is binding exactly as a percentage would be), and **state explicitly** in the completion report that this project does not use coverage percentages — quoting the table's own wording. **MUST NOT** report a `>XX%`-shaped threshold and **MUST NOT** pass over the item in silence.
+         ⚠️ The two cases share one branch **deliberately**: splitting them into parallel steps would make each the other's silent gap, which is the shape this repository keeps removing.
+    - Validate implementation matches spec.md requirements (if spec.md exists)
+    - Validate implementation follows plan.md technical design (if plan.md exists)
+    - Report final status: "✓ Implementation complete: N tasks executed"
+
+Note: This command uses **incremental parsing**, **interactive mode selection**, and **batch execution** for efficiency, safety, and resumability.
+
+**Interactive Mode Selection** 🎯 [DEFAULT]:
+   - **No arguments**: Shows interactive menu with 5 execution modes
+   - **User chooses**: Single task (1), Small batch (3), Medium batch (5), Phase execution, or All tasks
+   - **Safety first**: Menu displays task counts, progress, and warnings for risky options
+   - **Recommended**: Start with "Single Task" mode, then increase batch size as you gain confidence
+
+**Advanced Usage** (Arguments):
+   - `--once`: Skip menu, execute 1 task
+   - `--count N`: Skip menu, execute N tasks
+   - `--phase PHASE`: Skip menu, execute entire phase
+   - `--continue`: Skip menu, execute all tasks (⚠️ risk of context overflow)
+
+**Context Management** ⚠️ [CRITICAL]:
+   - **Default behavior (via menu)**: 1 task per session (safest)
+   - **Small batch (via menu)**: 3 tasks per session (balanced)
+   - **Medium batch (via menu)**: 5 tasks per session (efficient for small tasks)
+   - **Session-based**: Each execution is a session, progress preserved across sessions
+   - **Prevents overflow**: Menu explicitly warns when choosing risky options
+
+**Resumability**:
+   - Each execution finds the next `[ ]` task
+   - Completed tasks are marked `[x]`
+   - Interrupted runs can resume from last `[ ]` task
+   - No need to parse entire task list on each run
+   - Progress is preserved between sessions
+   - **No need to remember arguments**: Menu guides you every time
+
+**Test-First Execution** 🧪 [UNIVERSAL]:
+   - **tasks.md may contain test tasks** (project-dependent)
+   - **Test tasks typically appear BEFORE implementation tasks** (Test-First principle)
+   - **Command checks Test-First compliance**:
+     - If implementation task has corresponding test task that's not completed → Warning
+     - If project constitution exists and requires tests → Warning if missing
+   - **Coverage requirements** (if specified in project):
+     - Read from plan.md "Quality Targets" (authoritative), tasks.md `[Quality]` coverage tasks, or constitution
+     - Acceptance = the concrete evidence procedure in Step 14 (actual report + per-module comparison) — never assumed
+     - No targets defined anywhere → explicit "coverage: no targets defined" line in the report (never a silent skip)
+   - **TDD workflow** (when tests are in place):
+     - Test task: Write test, verify it fails (RED)
+     - Implementation task: Write code, verify tests pass (GREEN)
+   - **Universal test file detection**:
+     - Pattern: `*Test.kt`, `*Test.java`, `*Test.ts`, `*test.py`, `*_test.go`
+     - Detects test files across multiple languages
+
+**Responsibility Boundaries** ⚖️ [CRITICAL]:
+   - **SDD Principle**: Specification-Driven Development requires strict separation
+     * Specification (what): spec.md, plan.md, tasks.md define WHAT to build
+     * Implementation (how): implement command decides HOW to build it
+   - **Function/Flow**: STRICT execution of tasks.md requirements
+     * Implement exactly what tasks.md specifies
+     * Do NOT add features not in tasks.md
+     * Do NOT change design/specification
+   - **UI/Interaction**: FREE discretion
+     * Layout: Full freedom (positioning, spacing, alignment)
+     * Style: Full freedom (colors, fonts, sizes, shapes)
+     * Interaction: Full freedom (animations, transitions, feedback)
+     * Extra features: OK to add (undo, batch operations, shortcuts)
+   - **Decision tree**: "Does it change WHAT (function) or HOW (UI)?"
+     * WHAT = Function → Strict execution
+     * HOW = UI → Free discretion
+   - **No recording**: Most UI/interaction decisions don't need documentation
+   - **Examples**:
+     * ✅ Task: "Add button" → Choose any color/position (FREE - UI)
+     * ❌ Task: "Add login" → Don't add OAuth (STRICT - function)
+   - **See**: "Implement Responsibility Boundaries" section above for full details
+
+**Issue Feedback Mechanism** 🔄 [WORKFLOW CLOSURE]:
+   - **Purpose**: Record **planning-artifact** issues for feedback to the phase whose planner owns them
+   - **Governing rule**: *a planning error is fixed by the planner, an implementation error by the implementer* — an execution error belongs in fix-tasks.md (product code) or is fixed in place; it is never an issue entry
+   - **Location**: `specs/implement_issues.md`
+   - **The sections this command may write into**: [specify] · [plan] · [tasks] · [constitution] · [test-plan]
+     * **[specify] / [plan] / [tasks] / [constitution]** each have a `--review-issues` consumer — the detect-then-ask model applies to all four
+     * **[constitution]** carries defects in `specs/constitution.md` itself: a principle that no longer matches the practice it governs, a carve-out narrower than its intent, a clause with no enforcement point
+     * **[test-plan]** covers planning errors in `specs/test-tasks.md` — normally reported by `/specpro-test-implement` (its Step 11); `/specpro-implement` may append one but never resolves one
+   - **Format**: `- [ ] ISS-XXX: [Description]`
+   - **Workflow**:
+     * Implement records issues when discovered
+     * User runs `/specpro-specify --review-issues` → Fixes [specify] issues
+     * User runs `/specpro-plan --review-issues` → Updates plan.md
+     * User runs `/specpro-tasks --review-issues` → Updates tasks.md
+     * User runs `/specpro-test-plan` (incremental) → Updates specs/test-tasks.md, if any [test-plan] issues exist
+     * Continue with `/specpro-implement`
+   - **Sequential**: Must fix in order (specify → plan → tasks); `[test-plan]` and `[constitution]` resolve on their own tracks (test-tasks.md sits downstream of plan/tasks; the constitution governs all of them), each by the command that owns it
+   - **Each phase marks only its own issues as [x]**
+   - **See**: Step 13 for complete details
+
+**Debug Artifact Management** 📝 [MANDATORY DURING DEBUGGING]:
+
+   **Purpose**: Control where AI-generated debugging scripts/programs live and their lifecycle, preventing temporary files from polluting the repository root or source directories
+
+   **Rules**:
+   1. **Location** — all temporary scripts/programs created during debugging (wrapper scripts, standalone diagnostics, one-off test harnesses, code-surgery scripts) MUST go into a dedicated temporary directory (conventional: `tmp/debug/`), NOT the repository root or source directories
+   2. **Repository hygiene** — the temporary directory SHOULD be listed in `.gitignore` so accidental artifacts never enter version control
+   3. **End-of-session disposal** (three-way decision):
+      * **Decision test FIRST** ⚠️ — before picking a branch, ask: **is this tool tied to a STANDING quality target or an expected future re-run** (e.g., a measurement harness for an ongoing perf/memory target, a validator later tasks will reuse)? YES → PROMOTE; NO → DELETE (findings DOCUMENTed). Do NOT match "job is done" mechanically — every branch presumes the current run is finished; the branches differ ONLY on "will it be run again", not on "is this task complete". Evidence found while working (e.g., you documented future re-measurement scenarios) counts as reuse value
+      * DELETE — one-off scripts with no standing re-run need; code-surgery scripts (those editing source files by line number or pattern) MUST be deleted after use — keeping them risks accidental re-execution against changed code
+      * PROMOTE — tools that passed the decision test. Form is flexible: standalone scripts move to a conventional tools directory (e.g., `tools/`); harnesses depending on a module's test classpath (e.g., JUnit profiling classes reusing module fixtures) stay IN that module with ownership clearly marked in KDoc (task ID, non-matrix status) and get registered in the project's tools index / development docs
+      * DOCUMENT — keep only the findings as a development doc (ROOT_CAUSE/DEBUG/FIX); the script itself is not preserved (naturally combined with DELETE; never applied to a tool that passed the decision test)
+      * **Reversibility tiebreaker** — when genuinely uncertain between branches, choose the REVERSIBLE one: keeping/registering a cheap-to-remove artifact costs near zero, deletion requires rework to restore
+   4. **Forbidden** — creating debug scripts in the repository root, source directories, or documentation directories
+
+**Development Process Documentation** 📝 [WHEN NEEDED]:
+
+   **Purpose**: Document complex problems, difficult debugging, and important learnings
+
+   **Language Policy**: ⚠️ **the constitution's field is `**Artifact Language**`** — `Documentation Language Policy` is a **section name that exists nowhere** (`T233`/`ISS-206`), so the old pointer sent the reader to a heading they cannot find, in a file that has the real one. The single source is that field (`T172` in this file already reads it by that name).
+   - Follow the project constitution's `**Artifact Language**` setting
+   - See `specs/constitution.md` → the `**Artifact Language**` field (its value is the code the Step 4 language section reads)
+
+   **When to Create Docs**:
+   - **NOT for every task**: Only create docs when needed (see Step 9.d for detailed criteria)
+   - **User-facing docs**: Do NOT create unless explicitly required by tasks.md
+     * Examples: README, API docs, user guides, tutorials
+     * These belong in separate documentation phase if needed
+   - **Development docs**: SHOULD create when encountering complex situations
+     * File type examples: ROOT_CAUSE.md, FORMAT.md, DEBUG.md, FIX.md, SUMMARY.md, RUN_GUIDE.md
+     * Focus on: Problem → Investigation → Solution → Verification
+     * Help future developers (and AI assistants) understand complex code
+   - **Quality over quantity**: Better to have fewer high-quality docs than many low-quality ones
+   - **Location boundary**: development-work docs (tasks.md deliverables, including unit tests and their run guides) go under `docs/implement/` — NEVER in the repository root and NEVER in `docs/test/` (owned by `/specpro-test-implement`)
+
+   **Documentation Structure** (when project has many technical docs):
+
+   **Required** (fixed name):
+   - `PROJECT_NAVIGATION.md`: Main index for development process documentation
+     * Location: `docs/implement/PROJECT_NAVIGATION.md` (conventional location)
+     * Purpose: Quick lookup for finding documents by topic/user story/keyword
+     * When to create: UP-FRONT or when the FIRST technical document is produced (project documentation is assumed to be multi-document)
+
+   **Recommended** (pattern-based names):
+   - `{topic}/index.md`: Topic-specific navigation
+     * Location: `docs/implement/{topic}/index.md`
+     * `{topic}`: Replace with actual topic name (examples: `encoding/`, `authentication/`, `storage/`)
+     * Purpose: Document list, status, reading order for that topic
+     * When to create: Topic has 3+ documents or needs detailed navigation
+
+   **Optional** (pattern-based names):
+   - `{FEATURE}_{TYPE}.md`: Feature-specific documentation
+     * Examples: `USER_AUTH_FIX.md`, `DATABASE_MIGRATION_FORMAT.md`
+     * Type examples: ROOT_CAUSE, FORMAT, DEBUG, FIX, SUMMARY, IMPLEMENTATION, RUN_GUIDE
+     * Purpose: Detailed analysis of specific feature or problem
+
+   **Directory Structure Examples** (illustrative - adapt to your project):
+   ```
+   docs/
+   └── implement/                    # Development process documentation (conventional)
+       ├── PROJECT_NAVIGATION.md     # Main index (create up-front or with the first document)
+       ├── authentication/           # Example topic name (actual name varies)
+       │   ├── index.md             # Topic navigation (recommended for 3+ docs)
+       │   ├── OAUTH_FLOW_FIX.md    # Example doc name (follows pattern)
+       │   └── AUTH_DEBUG.md        # Example doc name (follows pattern)
+       ├── storage/                 # Another example topic
+       │   ├── index.md
+       │   └── DATABASE_MIGRATION_ROOT_CAUSE.md
+       └── [other topics]           # Your project's topics
+   ```
+
+   **Note**: Directory names like `authentication/` or `storage/` are EXAMPLES. Use topic names appropriate for your project.
+
+---
+
+## Protocol Codec Implementation Rules 🌐 [CONDITIONAL — wire-format / protocol implementation]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — trigger T3 (implementing or fixing a byte-stream encoder/decoder or protocol message parser). Consume the verdict recorded upstream (§6.4); do not re-judge it. When activated, the following implementation rules apply.
+
+- **Single source of truth for same-semantics branches**: byte-count, packing and stream-semantics branches inside a when/switch family MUST NOT be duplicated across functions — converge them into one helper. A family carrying N duplicated branches means a fix can touch N−1 and leave one latent.
+- **No per-tile or per-message state in decoder member variables**: it leaks across instances. State that genuinely must be shared between callers belongs in a host-side anchor, not inside the decoder.
+- **Byte-count lateral audit**: after fixing a byte-count or stream-semantics defect in one function, you MUST scan sibling functions in the same decoder family for the same-shaped branch. Symptom-driven fixes miss siblings — fixing one codec without scanning its neighbour is how the same defect recurs.
+- **Stream-semantics check before touching an encoder**: verify that encoder's stream semantics (continuous single stream vs per-message independent stream; where the in-stream byte count comes from) before editing. Carrying a lesson between encoders whose semantics are opposite is a high-risk trap.
+- See `.specpro/templates/protocol-golden-bytes-guide.md` §7 for the structural defences in full.
+