specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.scenarios.md

@@ -0,0 +1,154 @@
+---
+description: Generate or update the User Scenarios view (specs/scenarios.md) — the full scenario set from spec.md in one readable pass, for a human checking requirements during development
+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/scenarios.md
+    unit: "whole file - every User Story (Independent Test + Acceptance Scenarios) plus the provenance block, rebuilt in full each run"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — fully derived, rebuilt in full on every run** ⚠️ [settled 2026-09-16]:
+
+`specs/scenarios.md` is a **pure projection of `spec.md`**: every line in it is derived, and nothing in it is authored by hand or evolved across runs. Rebuilding it wholesale therefore destroys no work of the user's — which is why this command **does not** take the shared incremental rule that governs the spec-class artifacts (*detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent*). That rule exists to protect edits the detection check cannot see; here there are none to protect.
+
+**What must survive every run** is the provenance block — `Last updated`, `Source`, `Generated by` — so that a reader can always tell how old the projection is and what it was derived from.
+
+**Artifact Language Rule** 🌐 [CRITICAL — applies to ALL generated content]:
+- **Prose content** (scenario text, preconditions, expected outcomes, notes) 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 below, User Story / FR IDs, scenario type labels (Happy Path / Error / Edge / Permission), and the meta labels (`Last updated` / `Source` / `Generated by`)
+- **Entry field labels are structural anchors too** (`Given`, `When`, `Then`, `Verification Steps`, `Related Requirements`) — 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
+
+
+### 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/`。
+
+## Purpose
+
+Create or update `specs/scenarios.md` — the **User Scenarios view**: the full scenario set (Independent Test + Acceptance Scenarios, verbatim from `spec.md`) in one readable pass, with the spec's technical apparatus (FR tables, Lifecycle markers, quantified-requirement sections) left out.
+
+**Who reads it** ⚠️: a **human, checking requirements during development** — "what is this system supposed to do, along which paths?" It is not an input to any command's mechanics:
+
+- Manual scenario execution lives in `specs/manual-test-tasks.md` (via `/specpro-manual-test`)
+- End-user acceptance lives in `specs/acceptance.md` (generated only at the acceptance gate)
+- Coverage obligations live in `specs/test-tasks.md` (via `/specpro-test-plan`)
+
+**It carries no authored content** ⚠️: every line is derived from `spec.md`, and every run rebuilds it in full. It is **not a second home for requirements** — nothing here may be invented, and nothing added here survives. A requirement that exists only in this file does not exist; `spec.md` remains the single carrier.
+
+**Why this is a command of its own**: `spec.md` keeps evolving, so the checking view must be refreshable **on demand** without re-running the whole planning stage. `/specpro-plan` generates it once — on its initial run only — so the planning artifact set is complete out of the box; from then on this command owns it, and `/specpro-plan` never touches it again.
+
+## Execution Steps
+
+### 1. Setup
+
+Run `.specpro/scripts/bash/check-prerequisites.sh --json` from repo root and parse for `FEATURE_DIR` and `AVAILABLE_DOCS`. All paths must be absolute.
+
+### 2. Load the scenario source
+
+Read `spec.md` and extract, for each User Story:
+- the **Independent Test** (verbatim)
+- every **Acceptance Scenario** (Given-When-Then, verbatim)
+- the scenario type of each: **Happy Path / Error / Edge / Permission**
+- the FRs each scenario relates to
+
+**`spec.md` is the ONLY source.** Do not invent scenarios that are not in it, and do not carry over scenarios the spec no longer contains.
+
+### 3. Scope: always the whole file
+
+**Every run processes every User Story in `spec.md`.** This document is a projection of the spec's User Scenarios and has no incremental mode — a run rebuilds it in full from the current spec.
+
+Two consequences, accepted deliberately:
+
+- A User Story **removed** from `spec.md` disappears from the output. There are no `[DELETED]` tombstones: tombstones exist to preserve an audit trail of *decisions*, and a derived view records no decisions of its own.
+- Text anyone edited by hand in `scenarios.md` **is lost**. That is the intended trade: the file is a view and the spec is the source of truth. A durable, hand-maintained variant belongs somewhere other than this file.
+
+### 4. Generate / update the file
+
+```markdown
+# User Scenarios
+
+> **Last updated**: [DATE]
+> **Source**: spec.md → User Scenarios & Testing
+> **Generated by**: specpro.scenarios
+
+## Overview
+
+[What this document is for, and the fact that it is a presentation layer — the execution
+documents are manual-test-tasks.md and acceptance.md]
+
+**Total Scenarios**: N
+**User Stories**: M
+
+---
+
+## US<N> - [Title] (P<N>)
+
+[Independent Test, verbatim from spec.md]
+
+#### Scenario N: [Name] ([Type])
+
+**User Story**: USN - [Title]
+
+**Given** [Preconditions]:
+- [System state before the action]
+
+**When** [Action]:
+- [User action or event]
+
+**Then** [Expected Outcome]:
+- [Observable result]
+
+**Verification Steps**:
+1. [Concrete step]
+
+**Related Requirements**:
+- [FR-xxx: description]
+
+**Notes**:
+- [Constraints or follow-ups]
+
+---
+```
+
+**Scenario type coverage** — per User Story, aim for the distribution `spec.md` itself targets: Happy Path 1–2 · Error 2–3 · Edge 1–2 · Permission 1–2. Warn (do not fail) when a type is missing, or when a story has fewer than 5 or more than 9 scenarios.
+
+### 5. Validate
+
+1. Count the scenarios written, in total and per User Story
+2. Check the type distribution across the four types
+3. Confirm every scenario carries a `User Story` line and at least one `Related Requirements` entry
+4. Confirm Given-When-Then consistency
+5. Confirm the provenance block is present and stamped with this run's date
+
+### 6. Report
+
+```markdown
+## scenarios.md Summary
+
+**Total Scenarios**: N
+**User Stories**: M
+
+**Scenario Type Breakdown**: Happy Path X · Error Y · Edge Z · Permission W
+**Rebuilt in full**: all M User Stories (this command has no incremental mode)
+**Dropped — no longer in spec.md**: [US list, or "—"]
+```
+
+## Boundaries
+
+- **This command writes exactly one file**: `specs/scenarios.md`. It never edits `spec.md`, `plan.md`, `tasks.md`, or any test artifact.
+- **It does not judge scenario quality.** Missing scenarios, weak Given-When-Then, or requirement gaps are findings for `/specpro-analyze`, not for this command.
+- **It does not execute anything.** Scenario execution belongs to `/specpro-manual-test` (the manual layer) and `/specpro-test-plan` (the automated layers).
+- **Staleness is a symptom, not a duty.** A `scenarios.md` older than `spec.md` is expected when nobody has run this command — the consumer that reads it decides what to do about that; this command only makes refreshing cheap.