specpro-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,383 @@
+---
+description: Generate a coverage matrix and high-level test tasks (integration / component E2E / app E2E) in specs/test-tasks.md
+handoffs:
+  - label: Execute Test Tasks
+    agent: specpro-test-implement
+    prompt: Execute the generated high-level test tasks
+    send: false
+  - label: Analyze For Consistency
+    agent: specpro-analyze
+    prompt: Run a project analysis for consistency including test matrix gaps
+    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: specs/test-tasks.md
+    unit: "whole file - the run log, coverage matrix, change log, peer-diversity registry and the INF/IT/CE/AE task sections; **except** the executed task's checkbox and the coverage-matrix Status column, which are /specpro-test-implement's"
+  - artifact: specs/implement_issues.md
+    unit: "the [test-plan] section only -> its own issues marked [x] with a resolution note; appended ISS-NNN entries in any section — registration is routing; only [x]-marking is section-scoped"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — detect the artifact, default to incremental** ⚠️ [settled 2026-09-13]:
+
+**Before writing `specs/test-tasks.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/test-tasks.md ] && echo EXISTS || echo NEW    # -s: exists AND non-empty (an empty placeholder counts as NEW)
+```
+
+| Detection | Mode |
+|-----------|------|
+| **NEW** (absent or empty) | **Initial** — generate from scratch |
+| **EXISTS** | **Incremental** — evolve it; **never silently regenerate from scratch** |
+
+**Overwriting an existing artifact requires explicit, confirmed intent:**
+1. Only when the user *explicitly* asks (in their own words) does the initial path run on an existing artifact.
+2. **Even then, confirm once more before writing** — name the artifact that will be replaced and what will be lost; wait for the answer.
+3. **Silence is not consent.** An unspecified run on an existing artifact is ALWAYS incremental.
+
+> **Why a shared rule rather than per-command courtesy**: nine of the twelve non-implementation commands already had some protection, but each wrote it its own way (`EXISTING_SPEC` check · "creates a NEW file" · `NEVER overwrite` · "incremental regeneration" · `AUTO_MODE=false`), and **three had none at all** — not by decision, but because the discipline had no shared carrier. Overwriting an artifact the user has been evolving is not recoverable within the session; the cost of asking is one prompt.
+
+**Supported arguments**:
+- `--review-issues`: **skip the question and process the pending `[test-plan]` entries** directly. It is *not* what enables the mode: the mode is detected on every run (see below). The flag only means "I already know — don't ask".
+
+**Ledger handling is detected, not opted into** ⚠️ [settled 2026-09-13]:
+
+**On every run, before any normal work, check the `[test-plan]` section of `specs/implement_issues.md` for open `[ ]` entries.**
+
+| Situation | Behaviour |
+|-----------|-----------|
+| No file, or no open `[ ]` entry in `[test-plan]` | Proceed with the normal incremental run. **No prompt.** |
+| Open entries exist | **Ask the user** — "N open `[test-plan]` issues. Process them first (their verdicts land in Step 7), or run normally?" |
+| `--review-issues` passed | **Skip the question and process them directly.** |
+
+> **Why the flag is not the switch** (the failure this replaces): the old semantics — flag = on, no flag = off — pushed the risk onto the user. *Not* passing it risked silently leaving findings unprocessed; passing it risked overriding the incremental work they actually wanted. Neither was safe, and the pending set was invisible until the command ran. **Detect-then-ask makes it an explicit choice; the flag is left doing only "don't ask me again".**
+>
+> ⚠️ **Naming (settled 2026-09-13, TOOL-008)**: earlier drafts of this command carried a `--fix-issues` flag here. It was **removed** — processing the `[test-plan]` section *is* upstream-artifact work, which is exactly what `--review-issues` means everywhere else; a second name for the same action only made the parameter set ambiguous. `/specpro-implement` keeps a separate `--fix-defects` flag, because its other queue fixes **product code** — a genuinely different thing. **Rule of thumb: `review` = upstream artifacts (spec / plan / tasks / test-tasks); `defects` = product code.**
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Key Concept: Four-Layer Test Ownership 🧪 [CRITICAL]
+
+**Design Principle**: The project has FOUR test layers with DISTINCT owners. This command owns THREE of them.
+
+| Layer | Owner | Artifact | Notes |
+|-------|-------|----------|-------|
+| Unit Tests | `/specpro-plan` → `/specpro-tasks` | tasks.md (in-dev tasks, `[Quality]` tasks) + `core/src` embedded tests | NOT in this command's scope |
+| **Integration Tests** | **`/specpro-test-plan` (this command)** | **specs/test-tasks.md (IT-xxx)** | Mock-based, byte-sequence/scripted peers, <30s, CI-friendly |
+| **Component E2E Tests** | **`/specpro-test-plan` (this command)** | **specs/test-tasks.md (CE-xxx)** | Real peers (quirks/timing/perf/concurrency), environment-guarded |
+| **Application E2E Tests** | **`/specpro-test-plan` (this command)** | **specs/test-tasks.md (AE-xxx)** | App assembly, UI rendering chain, input-to-display |
+| Manual Acceptance | `/specpro-manual-test` | manual-test-tasks.md | Subjective/exploratory scenarios, human judgment |
+
+**Core artifact**: `specs/test-tasks.md` — led by a **Coverage Matrix** (FR × layer × task ID × status × rationale) built BEFORE task generation, guaranteeing reverse traceability (every FR is accounted for; every task maps back to FRs).
+
+**Grounding principle**: test-plan MUST scan the ACTUAL codebase. Existing test assets are registered in the matrix as already-covered (never duplicated). Infrastructure gaps (e.g., no in-process mock server) become INF-xxx tasks.
+
+## Layer Assignment Rules 📏 [AUTHORITATIVE]
+
+Apply these rules per FR when building the matrix. The constitution states only high-level principles; THESE rules are the operative detail.
+
+| Layer | Assign when... | Typical module (convention, not a hard rule) | Examples |
+|-------|---------------|----------------------------------------------|----------|
+| **Integration (IT)** | Peer behavior can be **deterministically simulated** with byte sequences / scripted responses. Contract-conformance verification against `specs/contracts/` (mock-based) belongs HERE | `tests/integration-test/`; contract verification may live in `tests/contract-test/` | Handshake version branches, security-type negotiation, message parsing round-trips, encoder↔decoder against scripted peer, contract tests (e.g. `tests/contract-test/` protocol compatibility) |
+| **Component E2E (CE)** | Behavior depends on **real peer quirks / timing / performance / concurrency scale** | `tests/e2e-test/` (real-peer packages) | Real peer auth + full encoding flow, resolution change mid-connection, throughput under real network |
+| **Application E2E (AE)** | Involves **app assembly, UI rendering chain, input-to-display** | `tests/e2e-test/` (app package) | Startup→connect→render, remote-control input latency, grid view with N connections |
+| **Unit (→ tasks.md)** | Single function/class in isolation | tasks.md-specified unit source sets / `tests/core-test/` / plugin `jvmTest` | Register existing tasks.md unit tasks or `core/src` embedded tests in the matrix; do NOT create new unit tasks |
+| **Manual (→ specpro.manual-test)** | **Subjective/exploratory** judgment required — **PREREQUISITE (FR-065): automation MUST be ruled out first** (evaluate against the mechanical carriers; mechanical parts → IT rows; the manual row carries only the subjective remnant, named concretely) | — (human execution, no automated module) | Visual aesthetics, intuitive navigation, exploratory discovery |
+
+**Module–layer mapping is a CONVENTION, not a hard rule**: one module may host multiple layers (e.g. `tests/e2e-test/` hosts CE real-peer packages and the AE app package), and one layer may span modules (IT in `tests/integration-test/` and `tests/contract-test/`). Any deviation is governed by the Location grounding rule (Step 5.e): a task's Location must reference a REAL module from the scan (or an INF task that creates it).
+
+**Special cases**:
+- **FR with no corresponding implementation component yet** → matrix row marked `pending-impl` in all layers; **do NOT generate tasks** (never test things that don't exist)
+- **FR sufficiently covered by existing unit assets** (no high-level test adds value) → matrix row status `not-applicable` with rationale; register the asset in the Unit cell; do NOT generate tasks
+- **FR deleted from spec** (incremental) → matrix row status `deprecated`; associated tasks marked `[DELETED]`; never re-tasked
+- **FR covered by existing assets** → register the asset (test file path / tasks.md task ID) in the matrix cell with rationale; do NOT generate a duplicate task
+- **Pure UI-logic FRs** → typically AE-only; integration/CE cells get rationale "pure UI, app-level" (or project-language equivalent)
+- **In-process UI-component tests (ComposeTestRule-style tools) are component/unit-layer coverage, NOT AE** — AE means the REAL app process launched end-to-end (assembly + rendering chain); framework-less structural "UI tests" (string/structure assertions with no UI framework) count as NO UI coverage — never register them as UI-covered in any matrix cell
+- **Performance NFRs** → attach as `Performance:` field on the CE/AE task that exercises the metric (only when a corresponding NFR exists)
+- **Cross-platform / global-constraint FRs** (claim text covers all platforms or enumerates platforms) → coverage MUST be anchored per platform tier: per-platform cells/scenarios, or a scenario set covering every claimed `full`-tier platform. Anchoring such an FR to a single-platform scenario alone is an assignment error — analyze Pass J flags it (HIGH); on `restricted`-tier platforms, only the FRs inside the spec boundary clause get coverage, the rest of the row follows `pending-impl`/`not-applicable` semantics
+
+## Outline
+
+**Artifact Language Rule** 🌐 [CRITICAL — applies to ALL generated content]:
+- **Prose content** (descriptions, rationale, scenario text, guidance) follows the project's **Artifact Language** setting — from `specs/constitution.md` → **Artifact Language** field; default `en` when absent
+- **Structural anchors are ALWAYS English**, regardless of the artifact language: section headings from the template, task ID prefixes (INF/IT/CE/AE), FR/US IDs, the matrix status enum, and table column names — exactly as written in the template
+- **Entry field labels are structural anchors too** (`source:`, `Evidence:`, `Fix Direction:`) — never translated, even when the surrounding prose is not English. They exist to be **searched**: an entry's fields must be greppable across artifacts and projects, and a translated label silently drops out of every consumer's scan.
+- Rationale: fixed anchors keep artifacts machine-parseable across specpro commands and keep instructions ↔ artifacts aligned for review
+
+1. **Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+   **Pre-flight checks**:
+   - **spec.md REQUIRED** — if missing: ❌ ERROR "Run /specpro-specify first", EXIT 1
+   - **tasks.md RECOMMENDED** — if missing: ⚠️ WARNING "FR→task mapping and module paths unavailable; matrix unit-coverage column will be incomplete. Continue? (y/n)". If 'n': EXIT 0
+   - **plan.md RECOMMENDED** — if missing: ⚠️ WARNING "Risk classification and Quality Targets unavailable; layer assignment will fall back to default rules. Continue? (y/n)". If 'n': EXIT 0
+
+2. **Incremental mode detection** 🔄 (change-log-driven; mirrors spec.md/tasks.md iteration patterns):
+   - If `$FEATURE_DIR/test-tasks.md` **already exists** → enter **incremental mode**:
+     * Read the file-header **Test-plan Runs** log and the **Matrix Change Log** table FIRST — they record what previous runs processed
+     * **Change-log-driven processing scope** = union of:
+       - FRs registered in the Matrix Change Log since the last run (previous incremental entries)
+       - FRs with **SpecStatus changed in spec.md** since the last Test-plan Runs entry (create/update)
+       - FRs **not present in the matrix** / with uncovered cells
+       - Grounding-scan deltas (Step 5): new existing assets → register in matrix cells; new infrastructure gaps → new INF tasks
+       - **Open `[test-plan]` issues in `specs/implement_issues.md`** — planning errors in this artifact reported by `/specpro-test-implement` (its Step 11). Read that section FIRST in every incremental run and resolve it in Step 7; a run that ignores it leaves the reporter's findings uncollected. In **full mode** the section may not exist yet — skip it
+     * All OTHER matrix rows are carried over **verbatim** (rationales, task IDs, statuses) — never re-derived, never re-scanned
+     * For each re-processed FR: re-run layer assignment for its row only; update its matrix cells; if task content must change, **rewrite the task in place (same ID)** or mark superseded tasks `[DELETED]` (same convention as tasks.md: mark now, physically remove on a later pass); **ID numbering never resets**
+     * FRs with SpecStatus = "delete" → mark matrix row `deprecated`, mark associated tasks `[DELETED]`
+     * **Write the logs**: append one row per re-processed FR to Matrix Change Log, and one `[test-plan:incremental <date>]` entry to Test-plan Runs
+   - If not exists → **full mode**: build the matrix from scratch; seed Matrix Change Log with a `create` row; write the first `[test-plan:create <date>]` entry
+
+   **Why no per-row Lifecycle markers**: unlike spec.md (whose FR entries have no other record of which commands processed them), matrix execution progress is **derivable from task checkboxes** — the status column is a human-readable summary of that derived state. Planning-era metadata (which run processed what) lives in the two logs, keeping 156+ rows maintenance-light.
+
+3. **Load requirements side** 📋: From spec.md extract:
+   - **FR full set** (all functional requirements with IDs and Lifecycle status)
+   - **Acceptance Scenarios** (per user story, Given-When-Then; these are the PRIMARY source for test task scenario grouping)
+   - **NFR performance metrics** (e.g., latency, FPS, memory targets) — later attached to CE/AE tasks as `Performance:` fields
+   - **Independent Test** sections (per user story) — inform layer assignment
+
+4. **Load planning side** 🏗️:
+   - From **tasks.md**: FR→task mapping (which tasks implement which FRs — identifies "no implementation component yet" FRs), module/file paths (test Location grounding)
+   - From **plan.md**: architecture boundaries (which modules exist, platform layers), **Quality Targets → Risk Classification** (HIGH/MEDIUM/LOW-RISK FR classification), **Quality Targets** (coverage targets; informs how aggressive layer assignment should be for HIGH-RISK modules)
+
+5. **Codebase grounding scan** 🔍 [CRITICAL — THIS IS WHAT MAKES test-plan REAL]:
+   **Purpose**: Inventory ACTUAL test assets so the matrix reflects reality, not assumptions. This prevents the three-way decoupling (mirrors that don't exist / paths that don't match / silently degraded durations) that high-level planning without grounding produces.
+
+   a. **Scan test modules**: inventory all files under `tests/*` (every test module directory), recording per file: test class name, what it actually tests (from test method names/annotations), whether it RUNS (module has build config + registered in settings) or is an empty/skeleton module
+
+   b. **Scan embedded tests**: inventory test files inside main source trees (e.g., `core/src/**/*Test.kt`, `src/test/**`) — these count as unit coverage
+
+   c. **Scan test infrastructure**: `docker-compose*.yml` (which containers/ports are defined), root-level test scripts, CI workflow files, test fixtures directories — plus **app-side infrastructure for AE**: app module build config (grounded build command + launch entry point), UI-driver toolchain (UI-test frameworks / screenshot / accessibility drivers), display environment for headless runs
+
+   d. **Produce two lists** (report them verbatim in Step 8):
+      - **Existing test asset inventory**: e.g., `XxxDecoderTest → registered as FR-xxx unit-covered`; each asset gets a matrix cell with rationale "existing asset: <path>"
+      - **Infrastructure gaps**: e.g., `tests/integration-test module is EMPTY (no build config or test sources)`, `no in-process mock server exists`, `docker-compose has no server service for CE tests`, `no app-launch harness or UI-driver toolchain exists for AE tasks`. Each gap → candidate INF-xxx task
+
+   e. **Grounding validation for every planned task Location**: a task's Location must reference a REAL module path from the scan (or an INF task that creates it). Never emit a Location under a module that the scan shows doesn't exist without an accompanying INF task.
+
+6. **Layer assignment** 📏: For EACH FR (full set in full mode; changed set in incremental mode):
+   - Apply the **Layer Assignment Rules** (above) per layer cell; record rationale in every non-covered cell
+   - Use plan.md risk classification: HIGH-RISK modules (protocol/crypto/network) should typically get IT + CE coverage; AE where UI chain is involved
+   - FRs with no implementation component (no tasks.md task, no code found in grounding scan) → mark row `pending-impl`, generate NO tasks
+   - Subjective/exploratory aspects → mark cell `manual (/specpro-manual-test)` with reason
+   - Build the coverage matrix COMPLETELY before generating any task (matrix-first, tasks-second)
+
+7. **Generate `specs/test-tasks.md`** 📋: Use `.specpro/templates/test-tasks-template.md` as structure. Section order and sources:
+   - **Test-plan Runs log** (file header) — REQUIRED; append one entry per run (`[test-plan:create <date>]` full mode / `[test-plan:incremental <date>]` incremental mode, summarizing what was processed); never rewrite or delete previous entries
+   - **Coverage Matrix** — from Step 6 (every FR × 4 layers, rationale everywhere, status column); incremental mode: carry over untouched rows verbatim, rewrite only re-processed FRs
+   - **Matrix Change Log** (inside/after matrix section) — REQUIRED; one row per re-processed FR (full mode: single `create` row covering all FRs); this table is the processing record for the next incremental run
+   - **Peer Diversity Registry** — REQUIRED for protocol / wire-format modules, omit otherwise; the closed set of *measured* peer behaviours. Carry existing rows over verbatim; register rows for behaviours measured since the last run (including differences reported by `test-implement`). A row is the only licence for a test to assert "peer X behaves as Y"; absence means unmeasured, and `analyze` Pass L5 audits expectations against it
+   - **Test Infrastructure Tasks (INF-xxx)** — from the grounding scan gap list; ordered FIRST (all test tasks depend on infra); no FR annotation
+   - **Integration Test Tasks (IT-xxx)** — grouped by scenario/domain (e.g., `[handshake]`, `[encoding-negotiation]`); deduplicated against existing assets found in Step 5
+   - **Component E2E Tasks (CE-xxx)** — grouped by scenario/domain; each with Environment + environment-guard requirement
+   - **Application E2E Tasks (AE-xxx)** — grouped by scenario/domain
+   - **Progress Statistics** — per-layer totals + matrix coverage counts (keep updated)
+
+   **Log ownership boundary**: BOTH logs, the coverage matrix, and the Peer Diversity Registry are written ONLY by `/specpro-test-plan`. `/specpro-test-implement` reads them (from the logs it determines nothing — it works from task checkboxes) but never writes them; peer-behaviour differences it discovers are report-only and get registered here on the next incremental run. Superseded tasks are marked `[DELETED]` (kept for audit), physically removed on a later pass — same convention as tasks.md.
+
+   **`[test-plan]` issue resolution** 🔄 [CLOSES THE FEEDBACK LOOP]:
+   - **Governing rule**: *a planning error is fixed by the planner, an implementation error by the implementer.* This artifact (`specs/test-tasks.md`) is planned here, so **planning errors in it are fixed here** — that is the whole meaning of the `[test-plan]` section
+   - **Shared section, split by action**: `/specpro-test-implement` **appends** new issues (`- [ ] ISS-XXX: ...`) and never marks them `[x]`; `/specpro-test-plan` **resolves** them — this command is the only party that marks `[test-plan]` issues `[x]`
+   - **For each open `[test-plan]` issue**, decide and record the verdict in the issue block (mirroring the `**Resolved <date>**` convention used by the other sections):
+     * **Accept** → fix `specs/test-tasks.md` (matrix row/cell, task content, Location, annotation) → mark `[x]` + append `**Resolved <date>**（/specpro-test-plan）: <what changed>`
+     * **Reject** → mark `[x]` + append `**Rejected <date>**: <reason>` — an issue may be closed as unfounded, but never silently dropped
+     * **Re-route** → if on inspection the defect is actually a *product* bug or an *upstream* planning error, do NOT fix it here: mark `[x]` with a `**Re-routed <date>**` note naming the correct channel (`fix-tasks.md` FT / `[specify]` / `[plan]` / `[tasks]`), and say so in the report so the human can carry it there
+   - **Issues about infrastructure planned elsewhere are not yours**: test-infrastructure work dispatched to `tasks.md` as `[Quality]` tasks (e.g. codec test-matrix / golden-fixture / test-host tasks, on a `/specpro-plan` design section) is planned by `/specpro-tasks`, not here. If such an issue appears in `[test-plan]`, re-route it per the bullet above — do not treat that infrastructure as this command's planning surface
+   - **Report the outcome** in Step 8 (count opened / accepted / rejected / re-routed)
+   - **Verify mechanically after writing** ⚠️: run `.specpro/scripts/bash/verify-ledger.sh`. Marking issues `[x]` changes the section's counts, so the statistics table must be updated in the same pass — the script reports any mismatch by name, along with any entry that sits outside a section and a missing trailing newline. A pre-commit hook enforces the same check.
+   - **Edit order and idempotency check** ⚠️ [a silent false-skip, observed 2026-09-13]: write the **entry body first** (its `[x]` + resolution note, in its own section), then the derived summaries (statistics table + `Last Updated`) — never the reverse. A derived summary written first introduces the ID into the file's text before the entry is resolved, so an idempotency guard that greps the file for that ID falsely concludes "already done" and **skips the resolution**, while the summaries still claim it happened. 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 the ENTRY's state, 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.
+
+   **Documentation convention**: test development process documentation produced while executing test tasks (mock-server format specs, flaky-test root causes, E2E environment debug guides) lives under `docs/test/` — written and maintained by `/specpro-test-implement` (see its Test Development Process Documentation step). test-plan itself does NOT write these documents; the two logs above are planning records, not documentation. Development-side docs (tasks.md work, including unit tests and their run guides) stay under `docs/implement/` — location follows the ownership of the work, not the document's topic.
+
+   **Task format** (concise; minimal per-layer differentiation):
+   ```markdown
+   - [ ] IT-001 [handshake] protocol version-branch handshake (FR-xxx)
+       Location: tests/integration-test/src/<target>/.../<Name>IT.kt
+       Source: mock server returns 003.003/003.007/003.008; assert the client uses the matching security handshake format
+       Mock: in-process ServerSocket mock server
+   ```
+   ```markdown
+   - [ ] CE-001 [connection-matrix] Real-server auth + full encoding flow (FR-xxx, FR-yyy)
+       Location: tests/e2e-test/src/test/.../XxxE2ETest.kt
+       Environment: Docker + container manifest
+       Validates: observable results
+   ```
+   - Every IT/CE/AE task MUST end with `(FR-XXX)` annotation (multi-FR allowed: `(FR-xxx, FR-yyy)`)
+   - Every task MUST have a grounded `Location` (see Step 5.e)
+   - Optional extension fields allowed AFTER the required fields (see Templates below)
+
+8. **Report** ✨:
+   ```markdown
+   ## ✅ Test Plan Complete
+
+   **Upstream status reconciliation** ⚠️ [MANDATORY before any "ready to continue" — Constraint 6 / FR-045]
+   
+   **"Ready to continue" is a claim about the whole chain, not about the stage speaking.** So
+   before this report states any "can continue / ready" conclusion, it MUST **read** each upstream
+   stage's pending status on the entries that stage produced, and **state** what it found. The
+   over-declaration this replaces: `/specpro-tasks` closed with "✅ Ready to continue
+   implementation" while the design side had not taken a single step (`specs/plan.md` → Constraint 6).
+   
+   **Two things, neither optional**:
+   
+   1. **Say it when the status is clean too.** "Nothing was mentioned" and "nothing is pending"
+      are different statements, and the first cannot be told apart from "forgot to look".
+   2. **Skipped and processed counts are listed separately** — never merged into one "handled" number.
+   
+   **Report shape** — every upstream gets a line, **including when it has nothing pending**
+   (indented, not fenced: several of these blocks sit inside an enclosing fence, and a nested
+   fence would close the outer one early):
+
+       Upstream reconciliation (Constraint 6)
+         <upstream>: N pending · M processed
+         Verdict: <clear to continue | upstream debts listed above>
+
+   ⚠️ **Report — do not block.** The mechanism self-heals: an upstream that completes marks its
+   downstream `update`. Blocking would need a judgement of "what counts as a debt", and that
+   judgement *is* the downstream reading its upstreams — reporting is its only legitimate form.
+   
+   ⚠️ **Copied verbatim across `specpro.{specify,plan,tasks,test-plan,test-implement}.md`** (five
+   sites; do not exist as one because each command document is deployed and read on its own).
+   Only the "This stage's upstreams" line below differs per file — **change all five together**.
+   
+   **This stage's upstreams**: `specify` · `plan` · `tasks` — pending means a source entry changed
+   after the last `Test-plan Runs` entry, or its matrix row still reads `pending-impl`.
+
+   **Test Tasks File**: specs/test-tasks.md
+
+   **Coverage Matrix**:
+   - FRs total: N | fully/planned covered: X | pending-impl (no component yet): Y | manual: Z
+   - Layer coverage: IT tasks: a | CE tasks: b | AE tasks: c
+   - [Full mode only] Layer coverage RATE: (covered cells / applicable cells)%
+
+   **Existing Assets Registered** (from grounding scan):
+   - [asset path] → [matrix cell]
+
+   **Infrastructure Gaps → INF Tasks** (from grounding scan):
+   - [gap description] → INF-0xx: [task title]
+
+   **Boundary confirmation with tasks.md**:
+   - Unit-test ownership confirmed: [N FRs] registered as tasks.md-unit-covered / core/src-embedded-covered; NO unit tasks created here
+
+   **`[test-plan]` issues** (incremental mode only): [N open on entry] → accepted: a | rejected: b | re-routed: c
+   ```
+
+9. **Do NOT update spec.md** ⚠️ [CRITICAL BOUNDARY]:
+   - test-plan does NOT modify Lifecycle fields (spec/plan/tasks statuses untouched)
+   - Test coverage state is tracked by the **matrix status column inside test-tasks.md itself**, updated by `/specpro-test-implement`
+   - **The one file outside test-tasks.md this command may write**: `specs/implement_issues.md`.
+     ⚠️ **Two acts, and only one of them is section-scoped** (the same split this file's `writes:`
+     unit states): **appending** a finding is **routing** — it goes to whichever section owns
+     the **fix**, not to a section this command owns; **marking `[x]`** is scoped — this command
+     marks **only `[test-plan]` entries** `[x]` with a resolution note (Step 7).
+     ⚠️ **A sentence reading "and only the `[test-plan]` section" collapses the two** and abolishes
+     the routing act. (Truth: `specs/contracts/ledger.md` → `## Write boundary` — pointed at, not
+     restated.)
+     ⇒ **Concretely, the three facts, so that no later edit can re-merge them**:
+       · it **MAY append** a finding to **any** section — that is routing, and a finding is routed
+         to whichever section owns its **fix**, not to a section this command owns;
+       · it marks `[x]` **only** in `[test-plan]` — that, and only that, is section-scoped;
+       · it touches **neither** `specs/spec.md`, `specs/plan.md`, `specs/tasks.md` **nor** any
+         other command's section, beyond the append above.
+     ⚠️ **⚠️ This paragraph was once spliced into the middle of its own first sentence** — the tail
+     `s` (of "entries") was left stranded and the boundary could not be recovered from the text
+     (`T234` / `ISS-207`). If a future edit reflows this bullet, **keep the three facts whole**: a
+     boundary sentence cut in half is worse than no sentence, because it still reads as a rule.
+
+Context for test planning: $ARGUMENTS
+
+---
+
+## Task Templates 🧪 (migrated & simplified from legacy tasks.md Phase 6 testing standards)
+
+**Field philosophy**: Environment/Observability fields are what prevented real incidents (e.g., an E2E task once ran against a nonexistent service because Environment was skippable). Keep those REQUIRED; trim ceremony fields to optional extensions.
+
+### Integration Test Template (IT-xxx)
+
+**Required fields (4)**: `Location`, `Source`, `Mock`, `Validates`
+
+```markdown
+- [ ] IT-XXX [domain] one-line title (FR-XXX[, FR-YYY])
+    Location: tests/integration-test/src/<target>/.../<Name>IT.kt
+    Source: [peer-behavior simulation description, e.g. "mock server returns 003.003/003.007/003.008; assert the client uses the matching security handshake format"]
+    Mock: [simulation approach, e.g. "in-process ServerSocket mock server"]
+    Validates: [observable results, e.g. "all three version branches complete handshake and the timeout path returns the correct error code"]
+    <!-- Optional extensions: Test Cases (Given-When-Then) / Risk Level / Execution Time(<30s) / CI/CD -->
+```
+
+**Validation checklist** (minimal):
+- [ ] Uses deterministic simulation (byte sequences/scripted peer), NOT a real server
+- [ ] Location under a REAL module (grounded; or INF task creates the module)
+- [ ] FR annotation present
+- [ ] At least one error-path case (timeout / invalid response) unless task is trivially happy-path
+- [ ] Test class named per convention: `*IT` suffix for IT test classes (e.g., `ConnectionMatrixIT`), distinguishing them from unit tests (`*Test`) and E2E tests (`*E2ETest`); fixture smoke tests may use `*Test` (e.g., `MockPeerSmokeTest`)
+
+### Component E2E Template (CE-xxx)
+
+**Required fields (5)**: `Location`, `Environment`, `Setup`, `Validates`, `Teardown` (+ `Performance` required only when a corresponding NFR exists)
+
+```markdown
+- [ ] CE-XXX [domain] one-line title (FR-XXX[, FR-YYY])
+    Location: tests/e2e-test/src/test/.../<Name>E2ETest.kt
+    Environment: [real system + container manifest, e.g. "Docker: <peer-service-image> (docker-compose.test.yml)"]
+    Setup: 1. [preparation step] 2. [@BeforeAll port-probe assumeTrue guard — skip when environment unavailable]
+    Validates: [observable results]
+    Teardown: 1. [cleanup step]
+    Performance: [REQUIRED only when a corresponding NFR exists, e.g. "first frame <2s"]
+    <!-- Optional extensions: Test Cases / Dependencies / CI/CD -->
+```
+
+**Validation checklist** (minimal):
+- [ ] Uses REAL external systems (a mock here means it should be an IT task)
+- [ ] Environment-guard specified (skip, not fail, when environment unavailable)
+- [ ] Setup/Teardown present (environment reproducibility + cleanup)
+- [ ] FR annotation present
+- [ ] Test class named per convention: `*E2ETest` suffix for CE/AE test classes (e.g., `RealPeerCompatibilityE2ETest`), distinguishing them from IT (`*IT`) and unit (`*Test`) classes
+
+### Application E2E Template (AE-xxx)
+
+Same required fields as CE-xxx. Additionally:
+- [ ] Exercises the app assembly / UI rendering chain / input-to-display path (not just a protocol flow — that's CE territory)
+- [ ] **App-side grounding in Environment**: the app build command (from the app module's build config), the launch/driver mechanism (or an INF task creates the app-launch harness), and the display environment (virtual display for headless/CI)
+- [ ] Visual-rendering Validates phrased as machine-checkable assertions (screenshot + pixel check / UI-tree check) — never "it looks right"
+
+### Anti-Patterns
+
+- ❌ Location under a module that does not exist in the grounding scan (without an INF task creating it)
+- ❌ Matrix cell left empty without a rationale
+- ❌ Task generated for an FR marked `pending-impl`
+- ❌ Integration task connecting to a real server (should be CE) / E2E task using mocks (should be IT)
+- ❌ Unit test tasks created in this file (unit tests belong to tasks.md)
+- ❌ AE task that never launches the real app process (an in-process UI-component test is component layer, not AE) / a matrix cell registering framework-less structural "UI tests" as UI coverage
+- ❌ Duplicating a test that the grounding scan already registered as an existing asset
+
+---
+
+## Protocol Codec Module Rules 🌐 [CONDITIONAL — wire-format / protocol modules only]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — triggers T3/T5 (the component under test is a wire-format codec or protocol message parser, or tests assert on raw bytes). Consume the verdict recorded upstream (§6.4); do not re-judge it. When activated, the coverage-matrix dimensions and the verification-method semantics MUST satisfy the following.
+
+- **Mandatory matrix dimensions**: message/tile type × full-frame vs incremental context × parameters — combined systematically. A static full-frame test's tile distribution naturally skips low-frequency paths, which is exactly how a branch-level defect stays latent. Every protocol point with no coverage — and every inventory row carried as a GAP (§6.3) — is a matrix finding, not an omission to be tidied away: keep the row, mark the cell.
+- **Test host is a coverage dimension**: an in-memory, network-free host is the default for codec matrices; a case that can only be expressed end-to-end carries timing coupling unrelated to the protocol and MUST be justified as a conformance spot-check rather than counted as protocol coverage (guide §3, *Layering*).
+- **Verification-method semantic review**: the verification technique MUST match the semantics of the stream under test — a continuous stream is verified by feeding segments into a persistent decoder. `incomplete` reported by a one-shot full-buffer decode is a normal artefact of a continuous stream, NOT evidence that the peer truncated its data; a method-semantics mismatch produces false defect conclusions.
+- **Peer-diversity coverage**: known differences between peer implementations are registered in the **Peer Diversity Registry** (see the test-task file's registry section) and drive the environment annotations — guessing unmeasured peer behaviour is forbidden.
+

specpro_cli/assets/commands/specpro.user-manual.md

@@ -0,0 +1,178 @@
+---
+description: Generate the end-user manual (docs/user_manual/user-guide.md) from implemented features - audience is the non-technical end user; chapters trace to US/FR via HTML annotations, implemented-only gating against tasks.md, prose and headings follow Artifact Language
+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: docs/user_manual/user-guide.md
+    unit: "whole file, always rebuilt in full; screenshot REFERENCES are carried over but the image files are never touched"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — fully derived except HUMAN blocks; rebuilt in full on every run** ⚠️ [settled 2026-09-16]:
+
+`docs/user_manual/user-guide.md` is a generated artifact: every chapter is derived from `spec.md` / `tasks.md`, and the file says so in its own header (*"Do not edit generated chapters by hand — wrap manual additions in HUMAN blocks"*). Rebuilding it wholesale therefore destroys no work of the user's — **provided** the two protected carriers below are carried over:
+
+- **`<!-- HUMAN: … -->` … `<!-- /HUMAN -->` blocks** — re-inserted byte-identical at the chapter position they occupied before.
+- **Screenshot files** — real images referenced from the manual are never deleted or repositioned.
+
+This is why this command does **not** take the shared incremental rule (*detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent*). That rule exists to protect edits a detection check cannot see — and here the edits that must survive are **explicitly marked**, not discovered. Protecting them costs a copy (Step 4), not a diff.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Key Concept: End-User Manual 📖 [CRITICAL]
+
+This command generates the **user manual** — the terminal artifact of the SDD chain, written for the non-technical end user (e.g., a teacher operating the classroom-management app). It is a **deliverable, not a process artifact**: no downstream command consumes it, and it never feeds back into the test/acceptance chain.
+
+**Traceability contract** [CRITICAL]: every chapter must trace to spec.md content — feature chapters to User Stories / Acceptance Scenarios, troubleshooting rows to Error/Edge scenario outcomes, performance expectations to quantified FRs. Source annotations use HTML comments (invisible when rendered):
+
+```markdown
+<!-- Source: US2, FR-xxx~FR-yyy -->
+```
+
+**Quality red lines** [CRITICAL]:
+- **No implementation leakage**: programming languages, build tools, protocol names, frameworks, plugin IDs, file paths, issue IDs (ISS-xxx), command names, progress percentages MUST NOT appear in user-visible prose.
+- **Every step has an observable result**: each numbered step derived from an Acceptance Scenario carries that scenario's **Then** clause (rephrased in user language) as the expected outcome.
+- **Implemented-only**: the manual MUST NOT describe behavior the app does not have. Scope is gated against tasks.md completion state (see Generation Steps, step 2).
+
+**Language Rule** 🌐: the manual is a terminal artifact with no downstream grep consumers — prose **and** structural anchors (chapter headings) follow the project's **Artifact Language** (from `specs/constitution.md`). This deliberately differs from spec-class artifacts, whose anchors stay English.
+
+**When it runs** ⚠️: this command has **no automatic trigger** — no other command invokes it, and it has no first-generation hook of its own (unlike `scenarios.md`, which `/specpro-plan` creates once on its initial run). Run it when a manual is wanted; re-run it when the implemented feature set has moved on.
+
+## Material Sourcing Map
+
+### Feature scope (FR-064, v0.23) ⚠️
+
+**扫描面 = 母规格 + 每一个非 `deprecated` feature**（`specs/features.md` 登记文件，`status` ∈ `active`/`delivered`）：各 feature 的 `spec.md`（+ 其 `tasks.md` 完成态）与母规格**一并**纳入 implemented-only 门控——feature 交付的功能若不入扫描面，手册对用户就是假的完整。每章的 HTML 来源标注写明出处（母规格 或 某 `fNNN-简称`）；feature 缺 `tasks.md`（无法判完成态）⇒ 该 feature 的章节列入 "Planned Features" 附录并标注 `spec-only`。
+
+| Manual section | Source | Transform |
+|----------------|--------|-----------|
+| Product introduction | spec.md Overview | one-line positioning + capability list in user language |
+| System requirements | hardware/platform FRs, plan.md Target Platform | teacher-device / student-device table |
+| Quick start | the Happy Path scenario of the primary User Story | shortest path to first success (numbered steps) |
+| Feature guide (body) | one section per implemented User Story + its Acceptance Scenarios | Given-When-Then → numbered steps, each with expected outcome |
+| Troubleshooting | Error/Edge Acceptance Scenarios across all USs | symptom (When) → expected message (Then) → what to do |
+| FAQ | recurring Error scenarios + Independent Test friction points | question → short answer |
+| Security & privacy notes | auth/crypto FRs, user-perceivable surface ONLY | password / encryption / credential notes |
+| Performance reference | quantified FRs | translate to user terms (`<500ms` → "refreshes within about half a second") |
+
+**Do NOT source from**: plan.md implementation phases, tasks.md task text, contracts/, research.md — these encode design/implementation concerns by definition.
+
+## Phase Detection
+
+The manual is **always rebuilt in full** — there is no incremental mode. The two things that must survive a rebuild are **marked explicitly**, not discovered by a diff (see Rerun safety above).
+
+| Condition | What happens |
+|-----------|--------------|
+| `docs/user_manual/user-guide.md` does NOT exist | full build |
+| exists | full rebuild, with HUMAN blocks and screenshot references carried over |
+
+## Generation Steps
+
+1. **Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root.
+   - **spec.md REQUIRED** — missing: ❌ ERROR "Run /specpro-specify first", EXIT 1
+   - **tasks.md REQUIRED** — missing: ❌ ERROR "Run /specpro-tasks first (implemented-only gating needs task status)", EXIT 1
+   - **spec.md's User Scenarios section is the ONLY scenario source** — read the Independent Test and Acceptance Scenarios directly from it. (`scenarios.md` is a human's checking view, not an input here: it may lag the spec, and it holds nothing the spec does not.)
+   - **existing user-guide.md** — if present, read it for its HUMAN blocks and screenshot references (Step 4); **nothing else from it is kept**
+
+2. **Build the implemented-feature inventory** 📋 [CRITICAL gating]: from tasks.md, determine each User Story's implementation state — ⚠️ **per FR-064: enumerate the MOTHER spec's USs first, then each non-`deprecated` feature's USs from `specs/features.md` × `<fNNN-简称>/tasks.md`** —. A US is **implemented** only when ALL of its implementation tasks are `[x]`.'s implementation state. A US is **implemented** only when ALL of its implementation tasks are `[x]`. Unimplemented USs are excluded from the manual body and appear ONLY as single lines (title + one-sentence description, no how-to) in the "Planned Features" appendix section.
+
+3. **Extract per-US material**: for each implemented US collect — title, Acceptance Scenarios (Happy Path → step source; Error/Edge → troubleshooting pool), its FR group annotation, and its quantified FRs (for the performance reference and step outcomes).
+
+4. **Carry over the protected carriers** (only when the manual already exists) 🔒:
+   - every `<!-- HUMAN: <reason> -->` … `<!-- /HUMAN -->` block, **byte-identical**, re-inserted at the chapter position it occupied before
+   - every screenshot reference — the image files themselves are never touched, deleted, or repositioned
+   - a HUMAN block whose chapter no longer exists (its US was removed from the spec) moves to an **"Appendix — retained notes"** section; it is never dropped
+
+5. **Generate `docs/user_manual/user-guide.md`** 📖 per the Chapter Template (below):
+   - prose and headings in Artifact Language
+   - HTML source annotation at every chapter/section head
+   - screenshot placeholders `[Screenshot: <description>]` — real images are added by humans later; never invent image files
+   - header metadata: spec version, generation date, generation command
+
+6. **Quality self-check** (run BEFORE writing the file; fix and re-check until clean):
+   - **Leakage scan**: grep the draft for the project's tech vocabulary (build from plan.md Primary Dependencies + protocol/framework names + `T\d+`/`ISS-\d+`/`FR-\d+` in user-visible text — FR ids are allowed ONLY inside HTML comments)
+   - every numbered step has an expected result
+   - every chapter has a Source annotation
+   - implemented-only gate: no body chapter for an unimplemented US
+   - **protected carriers intact**: every HUMAN block counted in Step 4 is present in the new draft
+
+7. **Report** ✨: implemented US count covered, planned-US list, troubleshooting row count, screenshot placeholder count, **HUMAN blocks carried over**, leakage-scan result, and next-step hint: "Add real screenshots, then run /specpro-manual-test to verify the documented flows against the running app."
+
+## Chapter Template
+
+> Headings below are STRUCTURE NAMES — render them in the Artifact Language. Section order is fixed; omit a section only when no source material exists for it (record the omission in the Report).
+
+```markdown
+# <User Manual: product name>
+
+**Applicable version**: <version>
+**Last Updated**: <date>
+<!-- Generated by /specpro-user-manual from spec.md v<version> on <date>.
+     Do not edit generated chapters by hand — wrap manual additions in HUMAN blocks. -->
+
+## About This Manual
+(who should read it, convention symbols used)
+
+## Product Introduction
+<!-- Source: spec.md Overview -->
+
+## System Requirements
+<!-- Source: <hardware FRs>, plan.md Target Platform -->
+(teacher-device / student-device table)
+
+## Installation & First Launch
+(numbered steps with expected results)
+
+## Quick Start
+<!-- Source: <primary US> Happy Path -->
+(the shortest path to first success — 10 minutes or less)
+
+## Feature Guide
+<!-- one subsection per implemented User Story -->
+### <Feature name>
+<!-- Source: US<n>, FR-xxx~FR-yyy -->
+**What it does**: ...
+**When to use**: ...
+**How to**: numbered steps, each with an expected observable result
+**If something goes wrong**: link to the Troubleshooting rows derived from this US
+
+## Troubleshooting
+<!-- Source: Error/Edge Acceptance Scenarios -->
+| Symptom | Likely cause | What to do |
+|---------|-------------|------------|
+
+## FAQ
+
+## Security & Privacy Notes
+<!-- Source: <auth FRs>, user-perceivable surface only -->
+
+## Performance Reference
+<!-- Source: quantified FRs, translated to user terms -->
+
+## Appendix
+(glossary, keyboard shortcuts — only what the UI actually offers)
+
+## Planned Features
+(single-line list of unimplemented USs — title + one sentence, no how-to)
+```
+
+## Output Metadata
+
+End every run by appending to the Report:
+- **Coverage**: X/Y implemented USs documented, Z FRs traced, N troubleshooting rows, M screenshot placeholders
+- **Excluded (unimplemented)**: US list with blocking task ids
+- **Self-check**: leakage scan PASS/FAIL, steps-with-outcome PASS/FAIL, source-annotation PASS/FAIL