@pknx/waterfall-cli 0.1.0

package/prompts/items/tst-document-structure.md

@@ -0,0 +1,55 @@
+# TST document structure — required sections, plus TC table shape
+
+This guide defines the canonical markdown shape of a TST:
+`tests/TST-<NNN>-<slug>/TST-<NNN>.md`
+
+## Rule
+
+TST markdown is the verification spec. It must be navigable from identity, declare which **UC** / **`TC-*`** it verifies (**typed ids**), and present each testcase as a structured `TC-*` section with a consistent table schema. Do **not** use **`### Upstream`**.
+
+## Required identity block
+
+Your `TST-<NNN>.md` should start with:
+
+1. A title heading like `# TST-<NNN> — <human description>`
+2. Identity fields (present verbatim, one per line):
+   - `**Id:** TST-<NNN>`
+   - `**Status:** <pending|...>` (or current lifecycle status)
+   - `Test type: <manual|automated|...>`
+
+## Links and dependencies
+
+Include:
+
+1. `## Links and dependencies`
+2. `### Verified artifacts` — bullet list of **UC-<NNN>** and **`TC-*`** ids this TST exercises (typed ids only; no “upstream” wording)
+3. `### Downstream references` — **typed ids only** for produced **`STORY-*`** / **`BUG-*`** (no path-based links — **[`before-changing-spec.md`](../global/before-changing-spec.md)**)
+
+## Required top-level sections
+
+1. `## Objective`
+2. `## Environment and data` (or equivalent)
+3. A set of `## TC-<NNN>-<seq> — ...` sections
+
+## TC section table shape (common)
+
+Each testcase section should contain:
+
+1. Optional `*Source: ...*` line citing **`UC-<NNN>`** and **`TC-<NNN>-<seq>`** by **id only** (no file paths — **[`before-changing-spec.md`](../global/before-changing-spec.md)**)
+2. A table with header:
+   - `Field | Detail`
+3. Typical rows:
+   - `Objective`
+   - `Preconditions`
+   - `Steps`
+   - `Expected outcome`
+
+## Structural constraints
+
+1. TC ids must remain consistent with what the UC `## TC-...` sections declare.
+2. Don’t redefine UC behavior; this pass only states verification tasks and expected results.
+
+## Downstream references (required)
+
+Whenever TEST → STORY or TEST → BUG happens, append the produced **`STORY-*`** / **`BUG-*`** ids under `### Downstream references`.
+

package/prompts/items/uc-document-structure.md

@@ -0,0 +1,38 @@
+# UC document structure — one main file, no separate description
+
+## Rule
+
+A use case is documented in **`requirements/RQ-…/UC-…/UC-<NNN>.md`** as the **single** human-readable source for:
+
+- identity (id, status, priority),
+- **links and dependencies** (including downstream references),
+- **actors**, **goal**, **preconditions**, **postconditions**,
+- **main flow** (specific, **actionable** steps — not RQ-level generalities),
+- **exceptions**, **non-functional expectations**,
+- **acceptance testcases** — **`## TC-<NNN>-<seq> — …`** sections with ids and tables that **prove** the UC is satisfied (see [`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)),
+- and any **description / context / background** that would otherwise live in a sidecar “description” file.
+
+**Do not** add a second markdown file whose only role is “UC description” (e.g. `UC-<NNN>-Description.md`). **Do not** add **`UC-<NNN>-Testcases.md`** — testcases live **in** **`UC-<NNN>.md`**. If you need a long narrative, add a section in **`UC-<NNN>.md`**, for example:
+
+```markdown
+## Context and description
+
+*(Prose, diagrams-as-links, constraints, glossary pointers — all here.)*
+```
+
+## What stays separate (unchanged)
+
+- **Supplementary non-executable** files **under the same UC folder** (diagrams, static samples) per **`CURSOR.md`** — not a duplicate “description” doc.
+
+## Links and dependencies (shape)
+
+Include **`### Downstream references`** only — **no** **`### Upstream`**. Owning **RQ** is implied by folder path; cite **RQ-** / **CR-** by **typed id** in prose if needed.
+
+## Downstream references (required)
+
+Inside `## Links and dependencies`, include a `### Downstream references` subsection.
+
+Append **one bullet per child id** whenever this UC produces implementation stories (**`STORY-*`**), formal tests (**`TST-*`**), or other directly derived items — **typed ids only**, no path-based markdown links (**[`before-changing-spec.md`](../global/before-changing-spec.md)**).
+
+In **body sections** (actors, flows, exceptions), cite other artifacts by **typed id** only — not repository paths.
+

package/spec-template/README.md

@@ -0,0 +1,11 @@
+# Spec scaffold templates
+
+Templates for **`waterfall spec init --title "…" --full`** live in **`full/`**.
+
+## Regenerating / editing the full scaffold
+
+1. Change files only under **`full/`** (paths mirror the target spec repo).
+2. Run **`npm test`** in `waterfall-cli` (see `lib/cli/spec/spec-init.test.ts`).
+3. New checkouts: `waterfall spec init --title "…" --full [DIR]`.
+
+The CLI copies this tree **after** creating `pom.json`, the minimal dirs, `number.json`, and `CURSOR.md`, so do not put `pom.json`, `number.json`, or `CURSOR.md` here (they stay in code as the single source for minimal + extended law text).

package/spec-template/full/doc/spec-structure.md

@@ -0,0 +1,16 @@
+# Spec tree (reference)
+
+This file is **non-normative**. Authoritative rules are **`CURSOR.md`** and your team’s change process.
+
+| Path | Role |
+|------|------|
+| `pom.json` | Project metadata: **`title`** (required; used by `waterfall export pdf` and for display); more fields may be added later |
+| `changerequests/` | **CR-*** — CLI scaffolds `CR-<NNN>-<slug>/CR-<NNN>.md` on `cr start` |
+| `requirements/` | **RQ-*** themes with nested **UC-*** |
+| `technical/` | **SYS-*** subsystems, **STORY-***, **BUG-*** |
+| `technical/horizontals/` | **HOR-*** cross-cutting aggregates |
+| `tests/` | **TST-*** test specifications |
+| `prompts/` | Spec-local workflow index + pointers (full scaffold only) |
+| `number.json` | Next ids: `CR`, `RQ`, `UC`, `SYS`, `STORY`, `BUG`, `TST`, `HOR` |
+
+Regenerate the **`prompts/`** stubs and this file by editing **`waterfall-cli/spec-template/full/`** and re-running **`waterfall spec init --title "…" --full`** in a fresh directory (or merge changes manually).

package/spec-template/full/prompts/before-changing-spec.md

@@ -0,0 +1,7 @@
+# Before changing spec (pointer)
+
+The full **cross-artifact editing rules** (typed ids, `develop` diff habits, hint policy) live in the Waterfall CLI package:
+
+**`waterfall-cli/prompts/global/before-changing-spec.md`**
+
+This stub exists so links from **`CURSOR.md`** resolve inside this repository. Operators using **embed** delivery already receive that body from the CLI; with **`--prompt-delivery reference`**, agents open the absolute path under the CLI install.

package/spec-template/full/prompts/workflows.md

@@ -0,0 +1,25 @@
+# Workflow prompt index
+
+This file is the **spec-local** index for how work flows through **CR → RQ → UC → SYS / STORY → TST**. Keep it short; normative repository law is **`CURSOR.md`**.
+
+## CLI-shipped checklists
+
+Transition prompts (**scope of edits**, strict typing) ship with the **Waterfall CLI** (not duplicated here):
+
+| Step | Typical CLI command | Prompt file (inside CLI install) |
+|------|---------------------|----------------------------------|
+| Start CR | `waterfall cr start "…"` | *(scaffold only; see CLI docs)* |
+| CR → RQ | `waterfall cr to rq "…"` | `prompts/commands/cr-to-rq.md` |
+| RQ → UC | `waterfall rq to uc "…"` | `prompts/commands/rq-to-uc.md` |
+| UC → story | `waterfall uc to story "…"` | `prompts/commands/uc-to-story.md` |
+| UC → test | `waterfall uc to test "…"` | `prompts/commands/uc-to-test.md` |
+| Test → story | `waterfall test to story "…"` | `prompts/commands/test-to-story.md` |
+| Story close | `waterfall story close STORY-NNN` | `prompts/commands/story-close.md` |
+| CR finish | `waterfall cr finish` | `prompts/commands/cr-finish.md` |
+
+Orchestration: `waterfall cr all`, `rq all`, `uc all`, `test all` — see the **CLI orchestration** section in each edge prompt.
+
+## This tree
+
+- **`workflows.md`** (this file) — index.
+- **`before-changing-spec.md`** — pointer to global rules; keeps `CURSOR.md` links valid in-repo.