specpro-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,206 @@
+---
+description: Manual acceptance testing (Four-Layer Ownership, Manual layer) - generate the AI-driven manual test task document (specs/manual-test-tasks.md), then interactively guide the human through each scenario, record verdicts, and route failures
+handoffs:
+  - label: Analyze For Consistency
+    agent: specpro-analyze
+    prompt: Run a project analysis including manual acceptance routing results
+    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/manual-test-tasks.md
+    unit: "## Task Definitions (MA-NNN) and ## Execution State (per-MA status/evidence/notes/timestamp/routed-to)"
+  - artifact: specs/acceptance.md
+    unit: "whole file - generated only at the acceptance gate"
+  - artifact: specs/implement_issues.md
+    unit: "the [tasks] section -> appended ISS-NNN entries for product bugs (scenario ref + repro + evidence)"
+---
+
+## 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/manual-test-tasks.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/manual-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.
+
+
+### 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: AI-Driven Manual Acceptance 🧪 [CRITICAL]
+
+This command implements the **Manual layer** of the Four-Layer Test Ownership (see `/specpro-test-plan`). Manual acceptance covers FRs whose verification is subjective/exploratory or requires real devices/environments — exactly the rows the coverage matrix marked `manual` and routed here.
+
+**Division of labor** [CRITICAL]:
+- **AI is the DRIVER**: AI does EVERYTHING AI can do — launch/stop the app, probe the environment, inspect processes/logs, trigger screenshot tooling, relay instructions, record verdicts, route failures, compute statistics. Do not ask the human for anything AI can do itself.
+- **The technical operator is the CO-EXECUTOR**: the human in this session (developer/QA) performs ONLY what AI cannot — subjective verdicts (visual aesthetics, latency feel, accessibility experience), real-peripheral operation, reaching remote machines. Together with AI they CLOSE the testing loop.
+- **The end user is the ACCEPTOR**: final acceptance is performed by the end user, NOT in this session — they read `specs/acceptance.md` (generated only at the acceptance gate) and verify in their own terms. Acceptance items MUST be phrased in end-user language, never technical assertions.
+
+**The document's audience is AI, not humans**: `specs/manual-test-tasks.md` is the "tasks.md for manual testing" — AI reads it to drive the manual testing session, exactly as `/specpro-implement` reads tasks.md. Do NOT write it as a human-readable acceptance guide.
+
+**Artifact Language Rule** 🌐: prose follows the project's **Artifact Language** (from `specs/constitution.md`); structural anchors (section headings, `MA-xxx` IDs, status enum) stay English.
+
+## Phase Detection
+
+| Condition | Mode |
+|-----------|------|
+| `specs/manual-test-tasks.md` does NOT exist | **Generation Mode** — build the task document, then stop and report |
+| exists | **Execution Mode** — resume guided execution |
+
+In Execution Mode: read the Execution State section FIRST, resume from the first unresolved scenario (breakpoint resume). NEVER overwrite existing execution records.
+
+## Generation Mode
+
+1. **Setup**: Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root.
+   - **spec.md REQUIRED** — missing: ❌ ERROR "Run /specpro-specify first", EXIT 1
+   - **test-tasks.md REQUIRED** — missing: ❌ ERROR "Run /specpro-test-plan first (matrix manual rows are the sole entry)", EXIT 1
+
+2. **Extract manual rows** 📋: From the coverage matrix, take every FR with status `manual`. For each, collect:
+   - FR id + title, matrix rationale (why it was routed to manual)
+   - spec.md **Acceptance Scenarios + Independent Test** (verbatim, per FR)
+   - linked Task IDs (the FR's automation legs, from the matrix Task IDs column)
+
+3. **Dependency check** 🔗: For each FR, look up its automation-leg tasks in `specs/test-tasks.md`: any leg unchecked → mark the scenario `Blocked-By: <task-ids>`. The scenario is still generated, but Execution Mode must verify the block is cleared (or get explicit human approval) before running it.
+
+4. **Ground launch commands** 🔍 [CRITICAL — never invent]: For scenarios that need the app running, grounding-scan the REAL launch command (desktop-app build config, quickstart.md, existing run scripts). If no grounded command exists, classify the scenario `human-environment` and note the gap.
+
+5. **Classify execution mode** per scenario:
+   - `ai-launchable` — AI launches the app, human operates the UI (dialogs, popups, settings flows)
+   - `human-environment` — real peripherals / remote machine / pure subjective judgment (audio latency feel, screen reader, native look-and-feel, real-server smoke); AI guides preparation and records
+
+6. **Generate `specs/manual-test-tasks.md`** 📋 with exactly two sections (see formats below):
+   - **Task Definitions** (frozen at generation; updated only by incremental regeneration)
+   - **Execution State** (written ONLY during Execution Mode; empty at generation)
+   - Header: Manual FR count, generation date, source matrix run reference
+   - Number scenarios `MA-001, MA-002, ...` in matrix row order; every scenario carries `(FR-XXX)` annotation
+
+7. **Report** ✨: scenario count per execution mode, blocked list (with blocking legs), launch commands found/gaps, and the instruction: "Run /specpro-manual-test again to start the guided manual testing session."
+
+8. **Incremental regeneration** 🔄: If the matrix `manual` set changed since the generation header reference, add/mark scenarios accordingly (`[DELETED]` kept for audit, same convention as tasks.md) — never touch existing execution records.
+
+## Execution Mode
+
+1. **Locate resume point**: first scenario whose Execution State is missing or `pending`.
+
+2. **Scenario loop** — for the current scenario:
+   a. **AI does everything AI can** (do not ask): pre-checks, launch the app (grounded command), probe environment (audio device present? screen reader running?), prepare screenshot tooling, tail relevant logs
+   b. **Instruct**: relay the numbered steps **in the project's Artifact Language** (`specs/constitution.md` → `**Artifact Language**`; default `en`), with the expected observable result for each step. ⚠️ 本节此前写死「in Chinese」（`T174`）—— 与本文件自己的 **Artifact Language Rule** 直接冲突：该条款说 prose follows the project's Artifact Language，而这一步**对任何** `Artifact Language ≠ zh` 的项目都会说错语言，且**不报错**
+   c. **Collect verdict** from the human: `pass` / `fail` / `blocked` + free-text description (+ evidence: screenshot paths, observed behavior)
+   d. **Record**: write back to Execution State (status, evidence, notes, timestamp) — immediately, before moving on
+   e. **Route failures immediately** (see Failure Routing)
+   f. Human decides: next scenario or pause (state is saved — safe to stop anytime)
+
+3. **Wrap-up & Acceptance Gate** ✨: statistics (pass / fail / blocked / pending), failures routed (with ISS refs).
+   - **Gate**: ALL scenarios `pass` AND all `Blocked-By` automation legs cleared → generate `specs/acceptance.md` (see Acceptance Guide below)
+   - Otherwise: do NOT generate it; report "acceptance prerequisites not met" + outstanding items
+
+4. **Boundaries** ⚠️ [CRITICAL]:
+   - Matrix `manual` rows are planning-final — NEVER modify `specs/test-tasks.md`
+   - NEVER modify product code; never edit spec.md / plan.md / tasks.md directly (routing channels only)
+   - Environment unavailable mid-session → status `blocked` with reason (mirrors CE environment-guard semantics), not `fail`
+
+## Task Definition Format
+
+```markdown
+### MA-001 [ai-launchable] Popup z-order & DND interaction (FR-xxx)
+
+**Matrix rationale**: pure UI interaction; popup z-order and DND behavior routed to manual
+**Blocked-By**: — (or IT-xxx / CE-xxx, noting incomplete legs)
+**Launch**: `<grounded command>` (or human-environment: environment preparation guidance)
+
+**Source** (spec.md verbatim):
+- Given: ... / When: ... / Then: ...
+- Independent Test: ...
+
+**Steps**:
+1. <instruction> → Expect: <observable result>
+2. ...
+
+**Pass Criteria**:
+- [ ] <observable pass criterion 1>
+- [ ] <observable pass criterion 2>
+```
+
+## Execution State Format
+
+```markdown
+## Execution State
+
+### MA-001
+- **Status**: pending | pass | fail | blocked
+- **Evidence**: <screenshot paths / observed behavior>
+- **Notes**: <key points of human feedback>
+- **Timestamp**: <date time>
+- **Routed-To**: <ISS-xxx / clarify prompt / —>
+```
+
+## Failure Routing
+
+| Finding | Route |
+|---------|-------|
+| Product bug | Append to the **`[tasks]` section** of `specs/implement_issues.md` (ISS-xxx: scenario ref + repro steps + evidence); continue or pause per human decision. ⚠️ **Route per the table in `/specpro-analyze`'s "Routing — by which stage owns the fix"** — a defect in the product of a `tasks.md` task belongs to `[tasks]`. ⚠️ **The section was unnamed here until 2026-09-17**, which left the write surface undecidable. |
+| Suspected requirement defect | Record in scenario notes + prompt to run `/specpro-clarify` for spec write-back |
+| Environment unavailable | Status `blocked` + reason; retry later |
+
+## Acceptance Guide (`specs/acceptance.md`)
+
+Generated ONLY at the acceptance gate. **Audience: the end user** — they do not participate in AI sessions and verify in their own terms. The generated document's prose follows the project's **Artifact Language**; structural anchors below stay English.
+
+```markdown
+# Acceptance Document: <feature name>
+
+**Acceptance Prerequisites**: testing loop completed (technical operator × AI collaboration)
+- Automated tests: <matrix summary — X completed / Y planning verdicts (manual/not-applicable/pending-impl)>
+- Manual testing: MA-001~0NN all pass (execution records in manual-test-tasks.md)
+
+**Acceptance Checklist** (per FR, end-user language, sourced from spec.md Independent Test / user value):
+- [ ] <end-user verifiable item, no technical assertions>
+
+**Outstanding Issues**: <blocked items / conditional-pass items, if any>
+
+**Acceptance Verdict**:
+- [ ] ✅ Pass
+- [ ] ⚠️ Conditional pass (conditions: <...>)
+- [ ] ❌ Reject (reason: <...>)
+
+**End-user Signature**: ________ Date: ________
+```
+
+If MA/matrix state changes after `acceptance.md` exists → prompt regeneration (the acceptance document follows prerequisite state).
+
+## Anti-Patterns
+
+- ❌ AI substituting its own judgment for a human subjective verdict
+- ❌ Overwriting existing execution records — breakpoint resume is MANDATORY
+- ❌ Asking the human to do anything AI can do (launching, log inspection, screenshots, recording)
+- ❌ Writing the document as a human-readable acceptance guide (audience is the AI driver)
+- ❌ Recording a `fail` without routing it
+- ❌ Inventing launch commands or environment facts (must be grounded)
+- ❌ Modifying matrix manual rows, product code, or upstream artifacts directly
+- ❌ Addressing the acceptance guide to engineers or phrasing acceptance items as technical assertions (audience is the end user)