specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.test-implement.md

@@ -0,0 +1,462 @@
+---
+description: Execute high-level test tasks from specs/test-tasks.md (infra → integration → component E2E → app E2E)
+handoffs:
+  - label: Analyze For Consistency
+    agent: specpro-analyze
+    prompt: Run a project analysis for consistency including test matrix gaps
+    send: false
+  - label: Resolve Test-plan Findings
+    agent: specpro-test-plan
+    prompt: Run test-plan in incremental mode to resolve the [test-plan] issues recorded in specs/implement_issues.md (update specs/test-tasks.md, then mark those issues [x])
+    send: false
+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: <test source files named by each task Location>
+    unit: "the test class/files each INF/IT/CE/AE task names, produced exactly as specified"
+  - artifact: specs/test-tasks.md
+    unit: "the executed task's checkbox [ ] -> [x]; the coverage-matrix Status column; the Progress Statistics section"
+  - artifact: specs/fix-tasks.md
+    unit: "FT-NNN entries: created on first defect; blocked-tests/evidence updated; marked [x] on PASS"
+  - artifact: specs/implement_issues.md
+    unit: "appended [test-plan] and [specify] design-feedback issues; the statistics table (**its own row only** — seven commands declare this artifact)"
+  - artifact: docs/test/**
+    unit: "the whole document set: PROJECT_NAVIGATION.md, {topic}/index.md, fix/verification/summary/run-guide documents"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — the artifact is produced ELSEWHERE; this command advances it** ⚠️ [settled 2026-09-13; **adapted to this command's write surface 2026-09-20** (`T235` / `ISS-208`)]:
+
+**`specs/test-tasks.md` is `/specpro-test-plan`'s product.** This command **executes** it. ⇒ The shared rerun rule's first branch — *"absent or empty ⇒ generate from scratch"* — **does not apply here**: generating that file is outside this command's write surface (see `writes:` above, and `**NEVER writes**: specs/test-tasks.md's **PLANNING content**` in the boundaries section), and its matrix verdict cells, rows, Peer Diversity Registry and two logs are **read-only** to this command.
+
+```bash
+[ -s specs/test-tasks.md ] && echo EXISTS || echo "ABSENT or EMPTY — /specpro-test-plan must run first"
+```
+
+| Detection | Mode |
+|-----------|------|
+| **EXISTS** (non-empty) | **Execute** — advance the executed task's checkbox, the coverage-matrix `Status` column and the Progress Statistics; **never rewrite the planning content** |
+| **ABSENT or EMPTY** | ⛔ **STOP** — Step 1's pre-flight below prints `❌ ERROR: specs/test-tasks.md not found. Fix: run /specpro-test-plan first.` and exits 1. **Do NOT create the file.** |
+
+⚠️ **The predicate is `-s` in BOTH places, and that is load-bearing**: an empty placeholder has no matrix and no tasks, so "execute it" would be execution over nothing. ⚠️ **The two sites used to disagree** — this block tested `-s` (empty ⇒ NEW ⇒ *generate*) while Step 1's pre-flight tested `-f` (empty ⇒ pass ⇒ continue). Both readings were actionable and they pointed in opposite directions (`T235`). They are now the same predicate and the same outcome.
+
+> **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.
+
+**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 test task, then exit
+- `--count N`: Execute N test tasks, then exit
+- `--layer LAYER`: Execute tasks of a specific layer (`infra` | `integration` | `ce2e` | `ae2e`)
+- `--group <domain>`: Execute tasks of a specific scenario/domain group (e.g., `--group handshake`)
+- Combine: `--layer integration --count 3` is valid
+
+
+### 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
+
+## Test Implement Responsibility Boundaries ⚖️ [CRITICAL]
+
+**Purpose**: This command EXECUTES the test plan; it does not re-plan it.
+
+**1. STRICT EXECUTION of test-tasks.md** ✅
+- **MUST**: Implement exactly the test described by the task (Location, Source, Mock/Environment, Validates)
+- **MUST NOT**: Invent additional test scenarios not in the task (report them as findings in the completion report — extra scenarios are test-plan scope, decided by `/specpro-test-plan`; record the recurring ones as `[test-plan]` issues per Step 11)
+- **MUST NOT**: Change what the test validates to make it pass — a failing Validates criterion is a FINDING, not an obstacle
+- **NO Test-First interception logic**: unlike `/specpro-implement`, this command's products ARE tests. There is no implementation task to guard; do not search for related implementation tests or warn about TDD ordering
+
+**2. Implementation discretion** 🎨
+- Test code style, fixtures organization, assertion helpers, test data builders: FREE discretion
+- Following existing test conventions in the target module (naming, base classes): REQUIRED (read sibling tests first)
+
+**3. Product code: NEVER modified** ⚠️ [CRITICAL — two-AI separation of duties]:
+- This command NEVER modifies product code (anything outside test modules). The testing AI and the implementing AI may be DIFFERENT sessions; judging and fixing are deliberately separated
+- Product defects are **DISPATCHED**: each finding becomes an `FT-XXX` fix task in `specs/fix-tasks.md` (file created on first defect), executed later by `/specpro-implement`
+- Acceptance authority stays HERE: an FT counts as fixed only when this command RE-RUNS the source test and it passes (re-verification) — implement marking the FT `[x]` is a claim, not a verdict
+- test-tasks.md checkbox/matrix write-back for affected tasks happens ONLY after re-verification passes
+
+**4. Skip semantics** ⚠️ [CRITICAL]:
+- E2E tasks (CE/AE) depend on external environments (Docker, real servers). Use **environment guards**: probe the environment in `@BeforeAll`/setup; if unavailable, **skip the test** (the `assumeTrue` port-probe pattern: probe in `@BeforeAll`, skip with a message naming the remediation) — a skip is NOT a failure
+- A task whose test was written and runs (pass or skip-with-guard) is completable. A task whose test FAILS is NOT completable
+
+**5. Ledger and planning-artifact write scope** ⚠️ [CRITICAL — verified write boundaries]:
+- **Governing rule**: a **planning error is fixed by the planner, an implementation error by the implementer** — recording an issue into a section whose owner is not the planner of the offending artifact is a boundary violation (the issue is filed where no one will legitimately consume it)
+- **MAY write**: `specs/fix-tasks.md` (create/update FT-XXX, Step 8) · `specs/implement_issues.md` — **append** new `[test-plan]`
+   - **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.
+ issues and `[specify]` design-feedback issues (Steps 8, 11)
+- **NEVER writes**: `specs/test-tasks.md`'s **PLANNING content** — coverage-matrix **verdict cells**, rows, the Peer Diversity Registry, the Test-plan Runs log, the Matrix Change Log (all `/specpro-test-plan`-owned) · `specs/spec.md` · `specs/plan.md` · `specs/tasks.md`
+  ⚠️ **This list previously read "in any part", which contradicted Step 6.c two pages below it** (2026-09-17). Step 6.c mandates the executed task's **checkbox** (`- [ ]` → `- [x]`) and the **Progress Statistics** section; both are *execution state*, not planning. The list now names what is genuinely off-limits — **planning content** — instead of a whole file, so the sentence and the step agree.
+- **NEVER marks any issue `[x]`** in `implement_issues.md` — issue resolution belongs to each section's owning command (`[specify]` → `/specpro-specify --review-issues`; `[plan]` → `/specpro-plan --review-issues`; `[tasks]` → `/specpro-tasks --review-issues`; `[test-plan]` → next incremental `/specpro-test-plan`; `[constitution]` → `/specpro-constitution --review-issues`)
+- **Exception — the one matrix write this command owns**: advancing a matrix row's status (`not-started` → `in-progress` → `completed`) for tasks it executed, per Step 6. That is status write-back, not planning: never change a row's verdict cells or add/remove rows
+
+---
+
+## Implementation Steps
+
+1. **Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR. 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").
+
+   **Pre-flight check**:
+   ```bash
+   TEST_TASKS_FILE="$FEATURE_DIR/test-tasks.md"
+   # ⚠️ `-s`, NOT `-f` (`T235` / `ISS-208`): an EMPTY test-tasks.md has no matrix and no
+   # tasks, so continuing would be execution over nothing — and the rerun-safety block at
+   # the top of this file already reads "absent or empty" as the same state. The two sites
+   # used to disagree (`-s` there, `-f` here), and both readings were actionable.
+   if [[ ! -s "$TEST_TASKS_FILE" ]]; then
+     ❌ ERROR: specs/test-tasks.md not found (or empty).
+      Fix: Run /specpro-test-plan first to generate the high-level test plan.
+      EXIT 1
+   fi
+   ```
+
+2. **Load test-tasks.md** 📋: Read the full file:
+   - **Coverage matrix** (FR × layer × task ID × status) — needed for status write-back. Note the status enum semantics: `pending-impl` / `manual` / `not-applicable` / `deprecated` are PLANNING verdicts (read-only for this command, immutable during execution); `not-started` → `in-progress` → `completed` are EXECUTION states (this command advances them, derived from task checkboxes)
+   - **Test tasks** in all sections: Test Infrastructure Tasks (INF-xxx) → Integration Test Tasks (IT-xxx) → Component E2E Tasks (CE-xxx) → Application E2E Tasks (AE-xxx); tasks marked `[DELETED]` are stale entries awaiting physical removal by test-plan — never execute them
+   - **Test-plan Runs log + Matrix Change Log** — informational only; both logs are OWNED by `/specpro-test-plan` and this command NEVER writes them
+   - **Progress statistics** section — updated after execution
+
+3. **Scan for pending tasks** 🎯 [TASK DISCOVERY]:
+   - Read test-tasks.md top to bottom per section in **execution order: INF → IT → CE → AE** (default when the matrix declares no explicit dependencies)
+   - Skip tasks marked `[x]` (completed) and tasks marked `[DELETED]` (superseded/stale)
+   - **Blocked tasks** ⚠️ [DEADLOCK PREVENTION]: a task carrying a `→ FT-xxx` note consults `specs/fix-tasks.md`: if the FT is still `[ ]` → SKIP during scan (do NOT stop on it — otherwise `--once` mode spins forever on the first blocked task) and report "blocked by FT-xxx"; if the FT is `[x]` (implement claims fixed) → RE-EXECUTE the task as re-verification (rules in Step 8)
+   - **Blocked is a task attribute, independent of selection mode** ⚠️: `--layer`/`--group`/batch modes SKIP blocked tasks exactly like the default scan. A user who wants fresh evidence for a blocked test runs the test command MANUALLY (outside this command's bookkeeping) — this command re-runs a blocked task only for re-verification after its FT is `[x]`
+   - Stop at first task marked `[ ]` (pending) that is NOT blocked
+   - Extract: task ID, layer, domain group, description, FR annotations, Location, Source, Mock/Environment/Setup, Validates, Teardown, Performance
+
+4. **Interactive execution mode selection** 🎯 [USER EXPERIENCE]:
+
+   **Skip this step** if user provided arguments (`$ARGUMENTS` is not empty)
+
+   a. **Analyze task status**: count total / completed `[x]` / pending `[ ]` per layer (INF/IT/CE/AE) and overall progress
+
+   b. **Display execution mode menu**:
+   ```markdown
+   📋 Test Implementation Session Setup
+
+   **Test Task Status**:
+   - Infrastructure (INF): X done / Y total
+   - Integration (IT): X done / Y total
+   - Component E2E (CE): X done / Y total
+   - App E2E (AE): X done / Y total
+
+   **Select Execution Mode**:
+
+   1️⃣ **Single Task** (Recommended) — execute 1 task, then pause
+   2️⃣ **Small Batch** (3 tasks)
+   3️⃣ **By Layer** — all pending tasks of one layer (choose: infra/integration/ce2e/ae2e)
+   4️⃣ **By Group** — all pending tasks of one scenario/domain group
+   5️⃣ **Continue All** (⚠️ ADVANCED ONLY — context overflow risk)
+
+   Your choice (1-5):
+   ```
+   c. Map selection to execution mode (`once` / `count` / `layer` / `group` / `continue`)
+
+   d. **Dependency check**: if the selected task's layer has incomplete INF prerequisites (e.g., an IT task whose Mock depends on an unfinished INF mock-server task), warn and offer to execute the prerequisite INF task first
+
+5. **Load task-specific context** 🎯 [ON-DEMAND]:
+   - **Always**: the target test task details; sibling test files in the target module (conventions: naming, fixtures, guard patterns)
+   - **If task has FR annotation**: the relevant FR section from spec.md (Independent Test, Acceptance Scenarios) and the mapped implementation tasks/files from tasks.md (what the test underwrites)
+   - **If IT task**: the Mock infrastructure (e.g., in-process mock server fixtures — read their APIs)
+   - **If CE/AE task**: the Environment container list (docker-compose files), existing guard patterns in the target E2E test module (port-probe `assumeTrue` pattern); **AE additionally**: the app build command (from the app module's build config), the launch/driver mechanism (app-launch harness fixture API if an INF task provides one), display-environment requirements (virtual display for headless runs)
+   - Do NOT load the whole codebase — keyword-match the modules named in the task
+
+6. **Incremental task execution** 🔄 [CORE LOOP]:
+
+   For each selected task (in INF → IT → CE → AE order):
+
+   a. **Write the test code**:
+      - Verify the task's `Location` module exists (it must — test-plan grounding guarantees this); create the test file/package as needed
+      - Follow sibling test conventions; implement the scenario from `Source`, the simulation from `Mock` (IT) or environment from `Environment`/`Setup` (CE/AE)
+      - Assert the observable results from `Validates`
+      - **For CE/AE**: implement the environment guard FIRST (probe ports/services; `assumeTrue`-skip when unavailable)
+
+   b. **Run and verify** ⚠️ [ACCEPTANCE PROCEDURE — evidence, not assumption]:
+      - **Grounded run command**: confirm the module's actual test-runner command from its build config BEFORE running (e.g., the module's test task as declared in its Gradle build script) — NEVER invent a task path (same grounding iron rule as run guides)
+      - **IT / INF**: the NEW task's own tests must PASS with a MEASURED duration against the <30s target (time it and report the measured number — never estimate). The 30s target applies to the task's own test execution, NOT to a full-module re-run including recompilation — measure and report that separately
+      - **Module regression (IT)** ⚠️ — **条件在前、强度在后**（`T174`）：**`if` 本任务动过共享夹具（如脚本化的 mock-server 夹具）⇒ 整个 integration-test 模块 MUST 在 `[x]` 之前跑一遍，本条 `MANDATORY`**；`else` ⇒ 只跑本任务自己的测试。
+        ⚠️ **本节此前把两句话写在同一段里**：开头是**无条件**的 `before marking an IT task [x], run the WHOLE integration-test module`，句尾才是 `MANDATORY whenever the task touched a shared fixture` ⇒ **读前半句是"每个 IT 任务都跑整模块"，读后半句是"只在动过共享夹具时"**，而**照哪半句做都说得通** —— 与它紧邻的姊妹条（CE/AE 的 `Module regression (shared e2e fixtures)`）用的却是**条件句**。⇒ 统一为条件句。
+        **理由**：一条新测试通过而**兄弟测试回归**（共享夹具破损，如 mock-server 脚本格式变了）**是失败的验收**。在完成报告里给出**模块总数**（如 `N/N passed`）。
+      - **IT has NO skip semantics**: mocks are in-process and always available — an IT test has exactly two outcomes, PASS or FAIL. Environment-guard skip applies to CE/AE ONLY; an IT "skip" means a broken fixture, which is a failure
+      - **CE / AE** ⚠️ [ACCEPTANCE PROCEDURE — evidence, not assumption]:
+        * **Grounded environment start**: start containers per the task's Environment/Setup fields (e.g., the compose up command the Environment field names) and WAIT for readiness before judging — respect the compose healthcheck window (`start_period` 20~30s) or retry the port probe; a probe fired immediately after `up -d` yields a FALSE "unavailable"
+        * **Environment available → PASS required**: the new task's tests must PASS, including Performance-field targets. Measure with multiple samples + warmup (e.g., 5 samples, judge by the median). A measured Performance miss is a Step-8 finding, not tolerable noise — repeat once to rule out environment noise and record BOTH runs in the report
+        * **Skip = evidence, not assumption**: guard-skip is a valid completion ONLY when the environment is GENUINELY unavailable — report WHICH probe failed and why (docker daemon down / image unpullable / port held by another process). The skip message must name the remediation (e.g., the compose up command). An evidence-less skip is NOT acceptable
+        * **Module regression (shared e2e fixtures)**: if the task added/changed a shared fixture in the e2e-test module (base class, container orchestrator, guard helper), run the WHOLE module before `[x]` — sibling SKIPS are skips (environment-dependent), sibling FAILURES are regressions
+        * **AE additionally (app side)** ⚠️:
+          * "Environment available" for AE = containers ready AND the app builds (grounded build command from the app module's build config) AND the display environment is ready (headless/CI: virtual display per the task's Environment field) — all three present → PASS required, same multi-sample rule for Performance targets
+          * **App build failure or crash-on-launch is a FINDING, NEVER a skip** — route per Step 8 (product defect → FT dispatch). Only genuinely absent infrastructure (containers / display) yields a guard skip
+          * Visual-rendering Validates MUST produce machine-checkable evidence (screenshot + pixel assertion, or UI-tree assertion); cite the evidence path in the report — an unevidenced "screen renders" claim is NOT acceptance
+          * Teardown runs EVEN ON FAILURE — destructive scenarios (stopping containers, killing connections) must restore/clean the environment before the task ends, or sibling tasks inherit a broken environment (applies to CE too)
+      - A failing test = task NOT done (see Step 8)
+
+   c. **Write back `[x]` AND sync the matrix** ⚠️ [CRITICAL — dual write-back]:
+      - Mark the task checkbox `- [ ]` → `- [x]` in its section
+      - **Update the coverage matrix**: for every FR listed in the task's annotation, advance the matrix row `Status` column — status is DERIVED from the FR's hooked task checkboxes (Task IDs column):
+        * ALL hooked tasks `[x]` → `completed`
+        * SOME tasks `[x]` (not all) → `in-progress`
+        * NO tasks done yet → stays `not-started`
+      - **Boundary ⚠️**: only rows in `not-started`/`in-progress` may be advanced. NEVER modify rows in state `pending-impl` / `manual` / `not-applicable` / `deprecated` — these are planning verdicts owned by `/specpro-test-plan` and immutable during execution. If a task annotation references such a row, that is a test-plan defect: record it in `implement_issues.md` `[test-plan]` for the next `/specpro-test-plan` run (see Step 8 routing and Step 11), do NOT write the matrix
+      - Update the **Progress Statistics** section (layer counts, completion rate, matrix coverage)
+      - Both writes happen together; a checkbox without matrix sync is an inconsistency
+      - Do NOT append to the Test-plan Runs log or the Matrix Change Log — both are maintained exclusively by `/specpro-test-plan`
+
+   d. **Loop control**: continue per execution mode (`once`/`count`/`layer`/`group`/`continue`); exit when limit reached or no pending tasks remain in scope
+
+7. **Skip and environment handling** ⚠️:
+   - Environment unavailable + guard in place → test SKIPS; count as "skipped", task completable, matrix status may be set `completed` with note "environment-guard skip" in the task line — **the note and the completion report must carry the skip REASON** (which probe failed, why); a skip-completed task is weaker evidence than PASS: note in the report that a re-run with the environment available upgrades the evidence
+   - If a CE/AE task has NO environment guard implemented, add one as part of the task (Setup field requires it)
+
+8. **Error handling and recovery** ⚠️:
+   - Test fails → **Do NOT mark `[x]`**, do NOT update matrix to `completed`; display test output; classify the failure by ROOT CAUSE and route accordingly ⚠️ [CRITICAL ROUTING]:
+     * **Test bug** (assertion/mock/fixture-usage error — the test itself is wrong) → fix the test code and re-run (within implementation discretion; no recording needed)
+     * **Product bug** (test is correct, implementation violates Validates, and the Validates criterion itself is reasonable) → an EXECUTION defect: **do NOT modify product code** (Boundaries §3 — the testing AI never fixes implementation). DISPATCH instead:
+       - **Search BEFORE create** ⚠️: before creating any FT, FIRST search `specs/fix-tasks.md` for a pending FT already covering this task (Blocked-Tests match) or the same root cause (Evidence/Location match) — if found, UPDATE its Evidence and Blocked-Tests instead of creating a new entry
+       - Create/update `specs/fix-tasks.md` (create the file on first defect): one `FT-XXX` per ROOT CAUSE; multiple source tests with the same root cause merge into one FT's `Blocked-Tests` list; NEVER duplicate an FT that is still pending
+       - Append `→ FT-XXX` to the source test task line; the task stays `[ ]`, matrix untouched
+       - FT fields: description · Evidence (failing assertion, expected vs actual) · Location (suspected root-cause `file:line`) · Fix Direction (optional hint — HOW is implement's discretion) · Validates (re-run the named source test PASS, WITHOUT modifying that test's code) · Blocked-Tests (list of test task IDs)
+         ⚠️ **`Location` is a POINTER, not evidence — and that distinction is deliberate** (`T224`, ruling (a)): it exists so the **fixer** can find the suspect root cause, which is a different job from *a reader checking the finding without re-deriving it*. The evidence field is `Evidence`, and **that one must be durable** (`FR-022`): a failing assertion with expected vs actual, or a command and its observed output. ⚠️ **Do not "align" the two by making `Location` also an anchor** — that would bind "where to change" to the durability burden and force it to be rewritten on every refactor, which is exactly the cost the distinction avoids.
+       - Report the FT id prominently in the completion report Findings
+     * **Requirement/design defect** (the test proved the Validates criterion or the underlying FR itself is wrong, ambiguous, or unimplementable) → record in `specs/implement_issues.md` `[specify]` section (`- [ ] ISS-XXX: description`) — this IS design feedback; the fix flows back via `/specpro-specify --review-issues`
+     * **Test-plan defect** (task hooks a planning-verdict matrix row, wrong Location, duplicates an existing asset, matrix row missing / stale relative to spec, task annotation inconsistent with the matrix, etc.) → record in `specs/implement_issues.md` `[test-plan]` section (`- [ ] ISS-XXX: description`) **and** report it in the completion report Findings; the fix lands in `specs/test-tasks.md`, which is test-plan-owned — see **Step 11** for the full recording workflow
+   - Compilation errors → Do NOT mark `[x]`; display errors
+   - **Re-verification of fixed FTs** ⚠️: when re-executing a task whose `→ FT-xxx` note points at an FT marked `[x]` in fix-tasks.md: re-run its source test → PASS → mark the task `[x]`, advance the matrix, append `re-verify PASS YYYY-MM-DD` to the FT line (checkbox stays as implement left it); FAIL → **REJECT the fix**: uncheck the FT and append `re-verify FAIL YYYY-MM-DD: <evidence>` (do NOT create a duplicate FT), task stays `[ ]`
+
+9. **Test Development Process Documentation** 📝 [WHEN NEEDED]:
+
+   **Purpose**: Document complex test problems, difficult debugging, and important learnings produced while executing test tasks — the test-workflow counterpart of `/specpro-implement`'s Development Process Documentation
+
+   **Location**: `docs/test/` (NOT `docs/implement/` — implementation docs and test docs stay separated)
+
+   a. **When to create** (NOT for every task):
+      - ✅ **ALWAYS create** for:
+        * Complex test infrastructure (in-process mock server byte-format decisions, Docker container orchestration, environment-guard patterns)
+        * Bugs that took >2 hours to solve (flaky tests, timing/race issues inside tests, mock ↔ client byte-stream mismatches)
+        * Issues requiring multiple attempts (E2E environment broken/unavailable, container image mismatches, port conflicts)
+        * Cross-module test debugging (matrix sync anomalies, FT dispatch chains spanning multiple source tests)
+        * Performance benchmarking methodology with measurable results (throughput/latency measurement setup for CE/AE `Performance:` fields)
+        * Real-server quirks discovered during CE/AE execution that future tasks must know about
+      - ❌ **DO NOT create** for:
+        * Simple test additions following existing sibling conventions
+        * Trivial fixes (typo in assertion, renamed helper)
+        * Routine test-code refactoring
+        * Environment-guard skips (the "environment-guard skip" note in the task line is sufficient)
+
+   b. **Document types** (test-flavored; adapt names as needed):
+      1. **MOCK_{PROTOCOL}_FORMAT.md**: byte-level format spec of a mock peer built for IT tasks (e.g., `MOCK_RFB_SERVER_FORMAT.md`)
+      2. **FLAKY_TEST_ROOT_CAUSE.md**: root cause analysis for flaky or failing tests
+      3. **E2E_ENVIRONMENT_DEBUG.md**: debug guide for Docker/real-server/app-launch environments (per-container ports, credentials, known quirks; app build failures, launch crashes, virtual-display issues)
+      4. **{TOPIC}_FIX.md**: solution record after fixing test infrastructure
+      5. **VERIFICATION.md**: re-verification evidence for fixed FTs (blocked tests)
+      6. **SUMMARY.md**: summary after completing a test domain (e.g., all `[handshake]` IT tasks)
+      7. **{TOPIC}_RUN_GUIDE.md**: operational run guide for a test suite or environment 🧪 [WHO / WHEN / WHAT / WHERE]
+         * WHO (writer): `/specpro-test-implement` — run guides are work products of test-tasks.md execution (INF/IT/CE/AE)
+         * WHEN (trigger): MANDATORY at **TWO** points — ⚠️ both carry the same obligation weight:
+           (1) when the FIRST INF/IT/CE/AE task of a test module completes → **create** that module's run guide (do not defer);
+           (2) when **EVERY later task of the SAME module** completes → **extend the SAME guide in the same closing pass** (new test classes / new grounded commands / new environment facts).
+           `(ONE guide file per test module, never per task)` governs **file count only, NOT update frequency** — "one file" must never be read as "rarely touched": skipping the per-task extension is a workflow violation (same class as skipping the matrix write-back).
+         * WHAT (minimum content): (1) suite inventory — test class ↔ task ID ↔ FR ↔ matrix status; (2) how to run all / single class / single method / by package (grounded commands only); (3) test-environment usage — mock-infrastructure APIs (fixture APIs, script format) for IT modules; container-environment usage for CE/AE modules (compose files, healthcheck/start_period wait, port map, credentials, debug helpers such as a liveViewer task); app-side usage for AE modules (grounded build command, launch/driver mechanism, virtual-display setup, screenshot/debug-evidence locations); (4) expected output on success; (5) how to view test reports; (6) failure debugging steps; (7) FAQ / quick reference
+         * WHERE (location): `docs/test/` — never `docs/implement/`. **Grounding iron rule ⚠️**: every command executed and its output observed BEFORE being written into the guide
+         * Example: `RUN_INTEGRATION_TESTS_GUIDE.md`
+      8. **PROJECT_NAVIGATION.md**: main index (fixed name) at `docs/test/PROJECT_NAVIGATION.md`, create up-front or when the first test document is produced (multi-document assumed)
+      9. **{topic}/index.md**: topic navigation at `docs/test/{topic}/index.md` (3+ documents per topic)
+
+   c. **Ownership boundaries** ⚠️:
+      - The **Test-plan Runs log** and **Matrix Change Log** in test-tasks.md are PLANNING records owned by `/specpro-test-plan` — never copy, restructure, or mirror them into `docs/test/`
+      - Product-bug evidence lives in `specs/fix-tasks.md` (FT Evidence field); `docs/test/` records the debugging KNOWLEDGE around it (how the failure was diagnosed, environment reproducers, measurement methodology)
+      - `docs/test/` receives ONLY documentation produced by executing test-tasks.md tasks (INF/IT/CE/AE). Documentation produced by DEVELOPMENT tasks (tasks.md — including unit tests and their run guides, e.g., a unit-test run guide) is development-work documentation and belongs to `docs/implement/`, maintained by `/specpro-implement`. Decision rule: document LOCATION follows the ownership of the work that produced it, NOT the document's topic — never write into `docs/implement/` from this command
+
+   d. **Navigation maintenance**: follow the same conventions as `/specpro-implement` (`docs/implement/PROJECT_NAVIGATION.md` templates): Topic Index table + reverse indexes (by FR, by test layer INF/IT/CE/AE, by keyword); 5-step update procedure (update Topic Index → By-FR → By-layer → By-keyword → verify consistency)
+
+   e. **Quality checklist** before saving: problem clearly described · evidence included (logs, assertion output, container state) · reproducible steps · cross-references to related test task IDs (INF/IT/CE/AE) · filename follows conventions · document placed under `docs/test/`
+
+9.5. **Git commit at session closure** 🆕 [PERSISTENCE]:
+   - **Purpose**: Persist test artifacts at controlled granularity — same failure class as `/specpro-implement` Step 13.5 (see that step for the full dual-trigger rules: internal cadence at logical-group boundaries + MANDATORY session-closure commit, decoupled from the execution mode).
+   - **What to commit** — grouped by which repository it belongs to ⚠️ (the artifacts below may live in different repositories; a single commit cannot span repositories, so **issue one commit per repository that has changes**):
+     - **In the repository holding the test tasks/matrix**: the test task list (checkbox + matrix status updates) and the fix-task list (FT evidence / status updates)
+     - **In the repository holding the test code** (often the project root, possibly different from the above): test sources/harnesses written or executed (`tests/...`), test infrastructure files (docker-compose, scripts)
+     - **Wherever the documentation lives**: `docs/test/` documentation created by Step 9
+   - **Path form — every path is expressed relative to its owning repository** ⚠️ (FR-027): a **different obligation** from the grouping above. 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/...`). ⚠️ Resolve `R` from the path's **own containing directory**, not from the project root (FR-026) — the grouping above can be right while the path form is still wrong.
+     ```bash
+     # 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.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 NOT to commit**: gitignored test outputs (`test-output/`, `*.exec`, `jacoco/`), environment-local files; respect the project's `.gitignore` policy, never `git add -f`
+   - **Commit message** (written per repository, not reused across them): `test(<scope>): <task-range> <one-line summary> — <verdict>`
+     Example: `test(handshake): IT-001~IT-007 protocol version branches — 7/7 green`
+     For the test-task/matrix repository, state the same range against what changed there, e.g. `test-tasks: IT-001~IT-007 marked green — 7/7`.
+   - **If nothing to commit**: state it and move on.
+
+10. **Completion report** ✨:
+
+**Upstream status reconciliation** ⚠️ [MANDATORY before any "ready to continue" — Constraint 6 / FR-045]
+
+**"Ready to continue" is a claim about the whole chain, not about the stage speaking.** So
+before this report states any "can continue / ready" conclusion, it MUST **read** each upstream
+stage's pending status on the entries that stage produced, and **state** what it found. The
+over-declaration this replaces: `/specpro-tasks` closed with "✅ Ready to continue
+implementation" while the design side had not taken a single step (`specs/plan.md` → Constraint 6).
+
+**Two things, neither optional**:
+
+1. **Say it when the status is clean too.** "Nothing was mentioned" and "nothing is pending"
+   are different statements, and the first cannot be told apart from "forgot to look".
+2. **Skipped and processed counts are listed separately** — never merged into one "handled" number.
+
+**Report shape** — every upstream gets a line, **including when it has nothing pending**
+(indented, not fenced: several of these blocks sit inside an enclosing fence, and a nested
+fence would close the outer one early):
+
+    Upstream reconciliation (Constraint 6)
+      <upstream>: N pending · M processed
+      Verdict: <clear to continue | upstream debts listed above>
+
+⚠️ **Report — do not block.** The mechanism self-heals: an upstream that completes marks its
+downstream `update`. Blocking would need a judgement of "what counts as a debt", and that
+judgement *is* the downstream reading its upstreams — reporting is its only legitimate form.
+
+⚠️ **Copied verbatim across `specpro.{specify,plan,tasks,test-plan,test-implement}.md`** (five
+sites; do not exist as one because each command document is deployed and read on its own).
+Only the "This stage's upstreams" line below differs per file — **change all five together**.
+
+**This stage's upstreams**: `test-plan` — pending means a task's matrix row changed after the
+task was generated, or a `[test-plan]` issue is still open.
+
+   ```markdown
+   ## ✅ Test Implementation Complete
+
+   **This session**: N tasks completed (INF: a, IT: b, CE: c, AE: d), M skipped (environment guard)
+
+   **test-tasks overall progress**: X/Y tasks ([P]%)
+   ┌────────┬──────┬──────┬───────┐
+   │ Layer  │ Done │ Total│ Rate  │
+   ├────────┼──────┼──────┼───────┤
+   │ INF    │      │      │       │
+   │ IT     │      │      │       │
+   │ CE     │      │      │       │
+   │ AE     │      │      │       │
+   └────────┴──────┴──────┴───────┘
+
+   **Matrix coverage change**:
+   - FRs newly fully covered: [list or none]
+   - FRs now partial: [list or none]
+   - Findings (product bugs [→ FT-xxx dispatched in specs/fix-tasks.md] / design defects [→ implement_issues.md `[specify]`] / test-plan defects [→ implement_issues.md `[test-plan]`, ISS-XXX; see Step 11]): [list or none]
+   - Blocked tasks (pending FT): [list or none]
+   ```
+
+11. **Issue reporting and feedback** 🔄 [WORKFLOW CLOSURE]:
+   - **Purpose**: record **test-plan defects** discovered while executing test tasks, so they flow back to `/specpro-test-plan` instead of being lost in a report
+   - **When to use**: when execution reveals that `specs/test-tasks.md` itself is wrong — not when the product or the spec is wrong
+   - **Governing rule** ⚖️ [PLANNING vs IMPLEMENTATION]: **a planning error is fixed by the planner, an implementation error by the implementer.** Ask which one is wrong before recording anything — the answer picks the channel:
+     * **Planning error** — the *plan* is wrong: the artifact says to do the wrong thing. Planner of that artifact fixes it.
+     * **Implementation error** — the *plan* was right but the execution of it is wrong. Implementer fixes it in place (within discretion) or dispatches it (product code → FT).
+   - **Not to be confused** ⚠️ [FOUR CLASSES, FOUR OWNERS]:
+     * **Product bug** — implementation error in product code (test is right, implementation violates Validates) → `specs/fix-tasks.md` (FT-XXX, Step 8) — fixer is `/specpro-implement`
+     * **Test-code bug** — implementation error in *this command's own* test/harness code (wrong assertion, fixture or mock-loop defect, bad test-data builder) → **fix in place and re-run** (Step 8, within implementation discretion); no ledger entry. If the defect is systemic enough to need tracking, it belongs to that task's **planner** (see next row), not to `[test-plan]` by default
+     * **Requirement/design defect** — planning error upstream of the test plan (the FR or design artifact itself is wrong, ambiguous, unimplementable) → the design-artifact channel, i.e. `implement_issues.md` `[specify]` per Step 8 — fixer is `/specpro-specify --review-issues`
+     * **Test-plan defect** — planning error in `specs/test-tasks.md` (INF/IT/CE/AE task content or coverage-matrix rows): task hooks a planning-verdict matrix row, wrong/ungrounded Location, duplicates an existing asset, matrix row missing or stale relative to spec, task annotation inconsistent with the matrix cells, missing INF prerequisite, etc. → `implement_issues.md` `[test-plan]` section — fixer is `/specpro-test-plan` (incremental). **This command never fixes test-tasks.md and never marks these issues `[x]`**
+   - **Scope boundary** ⚠️: this section is for **planning errors in test-tasks.md only**. Test-infrastructure work that was planned outside this artifact — e.g. codec test-matrix / golden-fixture / test-host tasks dispatched to `tasks.md` as `[Quality]` tasks by `/specpro-tasks` on a `/specpro-plan` design section — is **not** test-plan's planning surface: a planning error there goes to `[tasks]` / `[plan]`, and an implementation error there is the implementer's (i.e. `/specpro-implement`), never `[test-plan]`
+
+   a. **Check if issues exist**:
+      - Review the test-plan problems encountered during execution
+      - Confirm it is genuinely a test-plan defect rather than one of the other two channels above
+      - Examples of `[test-plan]` defects:
+        * Task's `Validates` asserts a behaviour the matrix cell contradicts
+        * Task `Location` points at a module/package that does not exist, or duplicates an asset the grounding scan already registered
+        * A matrix row is missing for an FR that spec.md declares (or a row's verdict is stale relative to the current spec)
+        * Task annotation `(FR-xxx)` disagrees with the row's `Task IDs` cell
+        * A task depends on an INF prerequisite that was never registered
+
+   b. **Record issues in `specs/implement_issues.md`** (create the section if absent):
+      ```markdown
+      ## [test-plan] Phase Issues
+
+      Issues related to test planning: coverage-matrix rows, task location/source/verdicts, task-annotation consistency, etc.
+      - [ ] ISS-XXX: [Issue description]
+      ```
+
+   b2. **Entry placement** ⚠️ [a silent-corruption failure mode, observed 2026-09-12]:
+      - Append the new entry to the **end of its own section** — after that section's last existing entry, **before** the next `## […] Phase Issues` heading. **Never append to the end of the file.**
+      - This bites hardest for exactly the sections a command does *not* own: "append to the file's end" happens to be correct only for whichever section is last, and is silently wrong for every other one. The observed instance: a `[tasks]`-side issue appended to the file end landed in `[test-plan]`, where its consumer had no mandate to act on it.
+      - **Verify mechanically after writing**:
+        ```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 — for an entry you just wrote, the section reported must be `[test-plan]`; anything else is a misfiling. A pre-commit hook enforces the same check.
+      - **Update the statistics table's `[test-plan]` row** at the top (Total +1, Pending +1). An entry count that disagrees with the statistics row is the same defect in another form — `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 — **continue the file-wide sequence**, do not restart per section (001, 002, 003, ...)
+      - A useful description carries: (1) the FR / task ID affected, (2) the observed vs expected matrix or task content, (3) the evidence that makes it reproducible — either **an anchor plus the quoted text it points at** (a task / FR / section identifier, never a line number alone) or **a command and its observed output**. ⚠️ **A bare `file:line` is not evidence** (`FR-022`): the artifacts under test keep evolving, so a stale line number **opens on someone else's text and does not error**. Same discipline as the other channels.
+        ⚠️ **This clause used to read "(a command, a `file:line`, a test output)"** — that made the line number sufficient, which was the pre-`FR-022` standard (`T224` / `ISS-197`).
+      - Example: `- [ ] ISS-xxx: task IT-022 annotation names FR-xxx but that FR's matrix row lists no IT task — row and annotation disagree`
+
+   d. **After recording issues**:
+      - Display summary: "⚠️ N test-plan issues recorded in specs/implement_issues.md"
+      - Provide next steps:
+        ```markdown
+        **Test-plan issues recorded during execution**
+
+        To fix these issues:
+        1. /specpro-test-plan   (incremental run — reads [test-plan] issues, updates specs/test-tasks.md, marks them [x])
+        2. /specpro-test-implement   (continue execution against the corrected test plan)
+
+        Only /specpro-test-plan marks [test-plan] issues as [x] — test-implement reports, it does not resolve.
+        ```
+
+   e. **Issue resolution workflow**:
+      - **NOT in scope**: this command neither fixes test-tasks.md nor edits the ledger's issue checkboxes
+      - **Owner**: `/specpro-test-plan`, on its next **incremental** run — it is the only writer of `test-tasks.md` (coverage matrix, both logs, Peer Diversity Registry) and therefore the only party that may mark `[test-plan]` issues `[x]`
+      - **Note on entry point**: unlike `[specify]` / `[plan]` / `[tasks]` / `[constitution]`, this section has no `--review-issues` flag to invoke — a plain incremental `/specpro-test-plan` run is the resolution path
+      - Issues that turn out to be product bugs or spec defects on closer inspection MUST be re-routed to their own channel (Step 8), not left in `[test-plan]`
+
+   f. **Do NOT halt execution**:
+      - Continue executing remaining tasks when a test-plan defect is found
+      - Record it for later resolution; only halt for CRITICAL blocking conditions (Step 8 compilation errors, unavailable environment with no guard)
+      - If the defect blocks the current task specifically, leave that task `[ ]`, note the `→ ISS-XXX` on the task line, and report it in the completion report
+
+Context for test implementation: $ARGUMENTS
+
+---
+
+## Protocol Codec Mock Rules 🌐 [CONDITIONAL — active when building a protocol mock peer]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — trigger T5 (constructing a mock protocol peer whose byte script asserts on or emits raw wire bytes). Consume the verdict recorded upstream (§6.4); do not re-judge it. When activated, the rules below govern how the mock is built and how evidence is taken from it. **Decide the verification path — and therefore the test host — before writing the first case**: a codec matrix hosted end-to-end inherits timing coupling unrelated to the protocol (connect races, consume-window competition, timeout tuning under load) and reports alternating PASS/FAIL with no code change, which destroys its value as a regression guard. Feed the codec layer directly first; end-to-end and real-peer cases do conformance spot-checks only (guide §3, *Layering*).
+
+- **Golden bytes over implementation output**: a mock peer's byte script MUST use spec-anchored golden bytes — hand-derived and annotated by source layer, per `.specpro/templates/protocol-golden-bytes-guide.md` §2. Using **the implementation under test's own output** as the peer's behaviour spec is forbidden: it is a self-confirming loop that mirrors the implementation's bug back as "correct".
+- **Verification-method semantic review**: for continuous-stream formats, verify with a reuse-style decode path. `incomplete` reported by a one-shot full-buffer decode is a normal artefact of a continuous stream, not defect evidence — a mismatch between the verification method and the stream semantics produces false defect conclusions. Any evidence conclusion MUST be cross-checked against the currently confirmed defect state before it is reported.
+- **Peer-diversity registration**: before asserting "peer X behaves as Y", consult the **Peer Diversity Registry** in `specs/test-tasks.md` — the closed set of *measured* peer behaviours. A row there is the only licence to write such an expectation; **unmeasured peer behaviour MUST NOT be frozen into a conclusion**. Differences you discover while executing are report-only for this command (you do not write the registry) — record them in the completion report so the next incremental `test-plan` run registers them.
+- **Consume / wait logic**: a mock peer's consume loop MUST block until the target message arrives. A silent-exit window is unreliable under load — when the client's message arrives slowly the loop exits early and produces a **zero-frame artefact**. Teardown between tests MUST leave no server / client / thread residue.
+- See `.specpro/templates/protocol-golden-bytes-guide.md` §3–§4 and §6 for the matrix shape, the lateral-audit criteria, and the activation verdict / GAP format.
+