plain-forge 1.0.23 → 1.0.24-next.019bba8

package/forge/skills/forge-plain/references/checklist.md

@@ -37,7 +37,7 @@ A box is met only when its source confirms it. Return `APPROVED` only when every
 - [ ] **[disk]** `.plain` module structure created with YAML frontmatter; template (if any) has no `***functional specs***`.
 - [ ] **[both]** Every concept authored in `***definitions***` via `add-concept`, defined before use.
 - [ ] **[both]** Every feature authored as functional specs via `add-functional-spec(s)`, each ≤200 LOC, in chronological build order.
-- [ ] **[disk]** No `***test reqs***` or `***acceptance tests***` written in this phase.
+- [ ] **[disk]** No `***test reqs***` or test plain files written in this phase.
 - [ ] **[disk]** Every `***implementation reqs***` bullet written this phase is technology-free policy — none names a language, framework, library, storage engine, or deployment target.
 - [ ] **[record]** Summarized the full feature list and module/concept layout; got explicit overall confirmation.
 
@@ -45,7 +45,7 @@ A box is met only when its source confirms it. Return `APPROVED` only when every
 
 - [ ] **[record]** Read `references/phase-2-tech.md` and walked its topics in order (language, frameworks, storage, external services, structure/architecture, other constraints, anything else).
 - [ ] **[disk]** Every requirement authored into `***implementation reqs***` at the right scope (shared → template, module-specific → module).
-- [ ] **[disk]** No `***test reqs***` or `***acceptance tests***` written in this phase.
+- [ ] **[disk]** No `***test reqs***` or test plain files written in this phase.
 - [ ] **[record]** Summarized the tech stack and architecture; got explicit overall confirmation.
 
 ## Phase 3 — How is testing done?
@@ -54,7 +54,7 @@ A box is met only when its source confirms it. Return `APPROVED` only when every
 - [ ] **[disk]** Honored the hard partition — every `:UnitTests:` fact in `***implementation reqs***`, every `:ConformanceTests:` fact in `***test reqs***`; never shared a bullet.
 - [ ] **[record]** Walked topics in order (unit framework, unit types/architecture, conformance decision, prepare-environment decision, layout, execution, other constraints, anything else).
 - [ ] **[disk]** Generated the needed scripts under `test_scripts/` via the `implement-*-script` skills and added each `*-script:` entry to the right `config.yaml`.
-- [ ] **[both]** Conformance decision was asked explicitly; if yes, walked every Phase-1 functional spec one at a time for acceptance tests via `add-acceptance-test` (acceptance tests present on disk when the decision was yes).
+- [ ] **[both]** Conformance decision was asked explicitly; if yes, walked every Phase-1 functionality one at a time via `add-test-scenarios` (a test plain file with at least one conformance scenario on disk for every functionality when the decision was yes).
 - [ ] **[record]** Prepare-environment decision was asked explicitly and recorded.
 - [ ] **[record]** Recapped the testing strategy; got explicit overall confirmation.
 - [ ] **[record]** Ran `check-plain-env`; it returned `PASS`, or `WARN`/`FAIL` with each remaining item explicitly acknowledged by the user (re-invoked after any install).

package/forge/skills/forge-plain/references/phase-1-product.md

@@ -10,10 +10,10 @@ The moment the user answers, write the resulting snippet to disk using the right
 
 - **Module structure** — create or update the `.plain` file(s) (single module, template + modules, or chained modules). Set up YAML frontmatter (`import`, `requires`, `description`) and the proposed module name. If a template is used, create it in `template/` **without** a `***functional specs***` section. Use the `create-import-module` skill where applicable.
 - **`***definitions***`** — add or refine concepts (entities, attributes, relationships). Define every concept before it is referenced. Use the `add-concept` skill.
-- **`***functional specs***`** — translate each answer into a single chronological, incremental spec (≤200 lines of code change, language-agnostic, no conflicts). Use `add-functional-spec` for one new spec; use `add-functional-specs` only when a single answer naturally decomposes into a tight cluster of specs flowing from the same answer (e.g. list / create / delete CRUD on one entity). **Never hand-author the `***functional specs***` section directly.**
+- **`***functional specs***`** — translate each answer into a single chronological, incremental spec (≤200 lines of code change, language-agnostic, no conflicts), headed by a func-id per `semantic-ids.md`. Use `add-functional-spec` for one new spec; use `add-functional-specs` only when a single answer naturally decomposes into a tight cluster of specs flowing from the same answer (e.g. list / create / delete CRUD on one entity). **Never hand-author the `***functional specs***` section directly.**
 - **`***implementation reqs***`** — only a requirement that can be stated without naming a technology: an error-handling or retry policy, an idempotency or ordering guarantee, a data-format or precision rule. Use the `add-implementation-requirement` skill, on the module whose behavior it constrains. The moment stating it takes a language, framework, library, storage engine, or deployment target, it is a Phase 2 answer — note it and steer back.
 
-Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — they belong to later phases.
+Do **not** add `***test reqs***` or test plain files in this phase — they belong to later phases.
 
 ## Topics (in order)
 

package/forge/skills/forge-plain/references/phase-2-tech.md

@@ -9,7 +9,7 @@ Write each requirement into `***implementation reqs***`:
 - Shared, stack-wide reqs (language, framework, architecture, coding standards) go on the template module if one exists.
 - Module-specific reqs (e.g. a data-storage choice or an external integration only one module uses) go on the module that needs them.
 
-Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — they belong to later phases.
+Do **not** add `***test reqs***` or test plain files in this phase — they belong to later phases.
 
 ## Topics (in order)
 

package/forge/skills/forge-plain/references/phase-3-testing.md

@@ -1,6 +1,6 @@
 # Phase 3 — How should testing be done?
 
-Gather the testing strategy. This phase covers `***test reqs***`, `***acceptance tests***`, the scripts under `test_scripts/`, and the `config.yaml` file(s) that wire them in. Run the core loop (ask → author → review) from `SKILL.md` for each topic below, in order. When the user has no preference, propose a default that fits the language and stack chosen in Phase 2 and ask them to confirm.
+Gather the testing strategy. This phase covers `***test reqs***`, the test plain files, the scripts under `test_scripts/`, and the `config.yaml` file(s) that wire them in. Run the core loop (ask → author → review) from `SKILL.md` for each topic below, in order. When the user has no preference, propose a default that fits the language and stack chosen in Phase 2 and ask them to confirm.
 
 ## Hard partition (applies to every topic)
 
@@ -36,10 +36,10 @@ template_dir: template
    - Author a `:UnitTests:` framework requirement in `***implementation reqs***` at the appropriate scope (template if shared, otherwise on the module) — e.g. "`:UnitTests:` should use pytest" plus "`:UnitTests:` are run via `pytest tests/`". Generate `run_unittests` (and any framework config it needs, e.g. `pytest.ini`, `jest.config.js`) via `implement-unit-testing-script`. Add the `unittests-script:` entry to the relevant `config.yaml`(s), creating each file if it doesn't exist yet.
    - Review the framework req, the generated script paths, and the new `config.yaml` entry.
 2. **Unit-test types and architecture mapping** — which of unit tests and integration tests the user wants, and how tests map to the Phase 2 architectural layers (e.g. one test module per service, repository tests with an in-memory store). Author a `:UnitTests:` scope / architecture requirement in `***implementation reqs***`, phrased in terms of `:UnitTests:` so the partition is visible. Review that requirement.
-3. **Conformance testing** — explicitly ask whether conformance / end-to-end tests should be part of the project. This drives whether `run_conformance_tests` is generated and whether `***acceptance tests***` are authored. If the user is unsure, briefly explain the tradeoff (extra scripts + per-spec acceptance tests vs. lighter setup) and let them choose.
-   - If **yes**: author a conformance-testing requirement in `***test reqs***` (framework, execution command, any constraints); generate `run_conformance_tests` via `implement-conformance-testing-script`; add the `conformance-tests-script:` entry to the relevant `config.yaml`(s); then **walk every functional spec authored in Phase 1, one at a time** — for each spec, ask one `AskUserQuestion` whether it needs concrete verification, and if yes author one acceptance test under that spec via `add-acceptance-test`, then review that acceptance test as a snippet before moving to the next spec. Never bulk-write acceptance tests; never ask about more than one spec per call.
-   - If **no**: record the decision; skip the conformance script, its config entry, and acceptance-test authoring entirely.
-   - Review the conformance req (if any), the new script and config entry (if any), and each acceptance test snippet (if any).
+3. **Conformance testing** — explicitly ask whether conformance / end-to-end tests should be part of the project. This drives whether `run_conformance_tests` is generated and whether test plain files with conformance scenarios are authored. If the user is unsure, briefly explain the tradeoff (extra scripts + one test plain file per functionality vs. lighter setup) and let them choose.
+   - If **yes**: author a conformance-testing requirement in `***test reqs***` (framework, execution command, any constraints); generate `run_conformance_tests` via `implement-conformance-testing-script`; add the `conformance-tests-script:` entry to the relevant `config.yaml`(s); then **walk every functionality authored in Phase 1, one at a time** — for each one, invoke `add-test-scenarios` to write its test plain file with at least one conformance scenario, then review those scenarios as a snippet with one `AskUserQuestion` and apply the answer before moving to the next functionality. Never bulk-write scenarios; never ask about more than one functionality per call.
+   - If **no**: record the decision; skip the conformance script, its config entry, and test plain file authoring entirely.
+   - Review the conformance req (if any), the new script and config entry (if any), and each test plain file snippet (if any).
 4. **Environment preparation script** — explicitly ask whether a `prepare_environment` script should be generated. It is the single entry point for installing dependencies and setting up fixtures/services before tests run. If the user is unsure, note it is recommended when there are dependencies to install or services to start, and skippable when the project genuinely has nothing to prepare.
    - If **yes**: generate `prepare_environment` via `implement-prepare-environment-script`; add the `prepare-environment-script:` entry to the relevant `config.yaml`(s); if the script's responsibilities are non-trivial and worth pinning in the spec, add a brief `***test reqs***` entry describing what `prepare_environment` is responsible for.
    - If **no**: record the decision; skip the script and the config entry.

package/forge/skills/init-config-file/SKILL.md

@@ -53,7 +53,7 @@ These keys reflect choices made in Phase 3 of `forge-plain`:
 | `conformance-tests-script` | path (string) | — | Include when the user opted into conformance testing in Phase 3. |
 | `prepare-environment-script` | path (string) | — | Include only when both (a) the user opted into a prepare-environment script and (b) `conformance-tests-script` is also set. Setting prepare without conformance is a hard `plain-healthcheck` failure. |
 | `test-script-timeout` | int (seconds) | `120` | Include only when the user explicitly raised/lowered the default. |
-| `template-dir` | path (string) | — | Include whenever the project has an `import` module or a custom template directory (e.g. `template/`). Required for projects with shared templates. `plain-parser check` reads it too, so `plain-healthcheck` finds the templates. |
+| `template-dir` | path (string) | — | Include whenever the project has an import module or a custom template directory (e.g. `template/`). Required for projects with shared templates. `plain-parser check` reads it too, so `plain-healthcheck` finds the templates. |
 | `build-folder` | string | `plain_modules` | Include only when the user picked a non-default folder name. Must differ from `build-dest`. The renderer writes `<build-folder>/<module>/code` (implementation + unit tests) and `<build-folder>/<module>/tests` (conformance tests, one folder per functional spec). |
 | `build-dest` | string | `dist` | **Always include with the value `dist`.** This skill pins the output destination explicitly so every project's `config.yaml` has the same, predictable target folder, visible in the file. Must differ from `build-folder`. |
 
@@ -73,7 +73,7 @@ Before emitting anything, state the planned split to the user (e.g. "I'll emit `
 
 ### Step 1 — Inventory
 
-1. List every `.plain` file in the repo and identify the top modules (modules not `requires`-ed by anything else) — same procedure as `plain-healthcheck` Step 1.
+1. List every `.plain` file in the repo and identify the top modules (modules not `requires`-ed by any other module) — same procedure as `plain-healthcheck` Step 1.
 2. For each top module, determine which part it belongs to (single-stack → one part; multi-part → one part per top module).
 3. List every script under `test_scripts/` and group them by part (e.g. `*_python.sh` belongs to the backend part, `*_js.sh` belongs to the frontend part).
 4. Identify the template directory (typically `template/`) and any custom resource directories (typically `resources/`).

package/forge/skills/init-plain-project/SKILL.md

@@ -13,16 +13,16 @@ description: >-
 
 # Init Plain Project
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Scope
 
-This skill is intentionally **minimal**. It produces a runnable project skeleton — not a complete spec. **No `***definitions***` sections are written by this skill — not in the template module, not in the top module.** No functional specs, no concepts, no acceptance tests, no validation. The user will fill those in afterwards with `add-feature`, `add-concept`, `add-functional-spec`, etc.
+This skill is intentionally **minimal**. It produces a runnable project skeleton — not a complete spec. **No `***definitions***` sections are written by this skill — not in the template module, not in the top module.** No functional specs, no concepts, no test plain files, no validation. The user will fill those in afterwards with `add-feature`, `add-concept`, `add-functional-spec`, etc.
 
 What this skill writes:
 
 - `template/base.plain` — an import module with the project's base `***implementation reqs***` and `***test reqs***`.
-- `<project>.plain` — a top-level module that imports `base`. Frontmatter only — no body sections. The user adds `***functional specs***` later.
+- `<project>.plain` — a top-level module that imports `base`. Frontmatter only — no body sections. The user adds `***functional specs***` later, each with its test plain file.
 - `test_scripts/run_unittests_<lang>.<sh|ps1>` — always.
 - `test_scripts/run_conformance_tests_<lang>.<sh|ps1>` — only if conformance testing is enabled.
 - `test_scripts/prepare_environment_<lang>.<sh|ps1>` — only if conformance testing is enabled **and** the user opts in.
@@ -31,7 +31,7 @@ What this skill writes:
 What this skill does **not** do:
 
 - Run `plain-healthcheck`.
-- Author concepts, functional specs, or acceptance tests.
+- Author concepts, functional specs, or test plain files.
 - Probe the host environment (`check-plain-env` is a separate step the user can run later).
 
 ## Workflow
@@ -51,7 +51,7 @@ Follow up with a free-form prompt for anything the options didn't cover (e.g. sp
 Use **AskUserQuestion** for one tight batch covering:
 
 - **Unit testing framework** — propose the canonical one for the chosen language (pytest, Jest, Go `testing`, JUnit, ...) and let the user override.
-- **Conformance testing** — enabled or not. If the user is unsure, briefly explain it adds a `run_conformance_tests` script and per-spec acceptance tests later.
+- **Conformance testing** — enabled or not. If the user is unsure, briefly explain it adds a `run_conformance_tests` script and, for every functionality added later, a test plain file with conformance scenarios.
 - **Prepare-environment script** — only ask this if conformance testing was enabled in the previous question. Generate one or skip. Recommend "yes" when dependencies need installing (most stacks); recommend "skip" when there is genuinely nothing to set up. If conformance testing is disabled, skip this question entirely and do not generate a prepare-environment script.
 
 ### 3. Author `template/base.plain`
@@ -118,7 +118,7 @@ Do **not** invoke `init-config-file` or `plain-healthcheck` here — keeping thi
 Tell the user what was created and what's next:
 
 - Files written: `template/base.plain`, `<project>.plain`, the test scripts, `config.yaml`.
-- Suggested next steps: add concepts with `add-concept`, add functional specs with `add-functional-spec` or `add-functional-specs`, or jump straight into `add-feature`.
+- Suggested next steps: add concepts with `add-concept`, add functional specs with `add-functional-spec` or `add-functional-specs` (each new functionality gets its test plain file when conformance testing is enabled), or jump straight into `add-feature`.
 - Mention that the project has not been validated — they can run `plain-healthcheck` when they want validation.
 
 ## Validation checklist

package/forge/skills/load-plain-reference/SKILL.md

@@ -2,15 +2,16 @@
 name: load-plain-reference
 description: >-
   Loads the applicable ***plain authoring rules and operational references for the current task.
-  Covers section ownership, concepts, modules, resources, integrations, rendering, and testing
+  Covers section ownership, concepts, func-ids, test plain files, modules, resources, integrations, rendering, and testing
   without loading unrelated guidance. Use when authoring, editing, reviewing,
   or debugging .plain files, or before invoking another skill that reads or writes .plain content.
 ---
 
 # Load the ***plain reference
 
-Load only the rules and references required for the current task. Files under `../../rules/` are
-the source of truth for `.plain` syntax and authoring constraints. Do not restate or override them.
+Load only the rules and references required for the current task. Files under `rules/`, next to
+this `SKILL.md`, are the source of truth for `.plain` syntax and authoring constraints. Do not
+restate or override them.
 
 **First, confirm the rules about to be loaded are current.** On the first invocation of this skill in
 a session, invoke `check-forge-version` before loading any rule file. A stale plain-forge ships stale
@@ -26,10 +27,7 @@ Skip the check on later invocations in the same session, and skip it when the ne
 
 ## 1. Account for rules already loaded
 
-- In Claude Code, applicable `.claude/rules/*.md` files are loaded natively. Do not read those rule
-  files again.
-- In another agent, do not reread a rule whose full content is already present in the current
-  context.
+- Do not reread a rule whose full content is already present in the current context.
 - Otherwise, read the applicable files from the routing table below before inspecting or changing
   `.plain` content.
 
@@ -39,19 +37,21 @@ All paths are relative to this `SKILL.md`.
 
 | Task or content | Rule files |
 |---|---|
-| New module, file skeleton, section placement, or comments | `../../rules/module-structure.md` |
-| Moving facts between sections (see `resolve-section-ownership`) | `../../rules/module-structure.md`, plus the rule file of each section involved |
-| Definitions or concept usage | `../../rules/definitions.md` |
-| Functional specs or acceptance tests | `../../rules/func-specs.md` |
-| Implementation requirements or unit tests | `../../rules/impl-reqs.md` |
-| Test requirements or conformance tests | `../../rules/test-reqs.md` |
-| `import` modules | `../../rules/import-modules.md` |
-| `requires` modules | `../../rules/requires-modules.md` |
-| `required_concepts` | `../../rules/required-concepts.md` |
-| `exported_concepts` | `../../rules/exported-concepts.md` |
-| Linked files or `resources/` | `../../rules/linked-resources.md` |
-| Any `.plain` text or example | `../../rules/bullet-continuation.md`, `../../rules/concise-specs.md` |
-| Drafting or trimming spec wording, or reviewing a spec for verbosity | `../../rules/concise-specs-examples.md` |
+| New module, file skeleton, section placement, or comments | `rules/module-structure.md` |
+| Moving facts between sections (see `resolve-section-ownership`) | `rules/module-structure.md`, plus the rule file of each section involved |
+| Definitions or concept usage | `rules/definitions.md` |
+| Functional specs | `rules/func-specs.md`, `rules/semantic-ids.md` |
+| Test plain files or scenarios | `rules/test-plain-files.md`, `rules/semantic-ids.md` |
+| Implementation requirements or unit tests | `rules/impl-reqs.md` |
+| Test requirements or conformance tests | `rules/test-reqs.md` |
+| `import` modules | `rules/import-modules.md` |
+| `requires` modules | `rules/requires-modules.md` |
+| `required_concepts` | `rules/required-concepts.md` |
+| `exported_concepts` | `rules/exported-concepts.md` |
+| Linked files or `resources/` | `rules/linked-resources.md` |
+| Definitions, implementation reqs, or test reqs text | `rules/bullet-continuation.md` |
+| Any `.plain` text or example | `rules/concise-specs.md` |
+| Drafting or trimming spec wording, or reviewing a spec for verbosity | `rules/concise-specs-examples.md` |
 
 For a whole-file review or a task spanning several sections, load the union of the applicable rule
 files. Do not load every rule by default.
@@ -60,16 +60,16 @@ files. Do not load every rule by default.
 
 For an integration spec, always read:
 
-- `../../rules/integrations.md`
+- `rules/integrations.md`
 
 Then read the rule matching the integration shape:
 
-- Embedded integration: `../../rules/integration-embedded.md`
-- Standalone integration: `../../rules/integration-standalone.md`
-- Embedded integration test scripts: `../../rules/integration-embedded-testing.md`
+- Embedded integration: `rules/integration-embedded.md`
+- Standalone integration: `rules/integration-standalone.md`
+- Embedded integration test scripts: `rules/integration-embedded-testing.md`
 
 When drafting or trimming the wording of an integration spec, also read
-`../../rules/concise-specs-integration-examples.md`.
+`rules/concise-specs-integration-examples.md`.
 
 Do not load integration rules for ordinary non-integration specs.
 

package/forge/skills/load-plain-reference/references/project-model.md

@@ -14,10 +14,11 @@ those specifications.
 ```text
 *.plain                  # Root specification modules
 template/*.plain         # Reusable import modules
+tests/<module>/<func-id>.plain   # Test plain files, one per functionality (conventional location)
 resources/               # Linked text artifacts such as schemas and fixtures
 plain_modules/           # Generated output, one directory per module
   <module>/code/         #   implementation and unit tests
-  <module>/tests/        #   conformance tests, one folder per functional spec
+  <module>/tests/        #   conformance tests, one folder per functionality, one test per scenario
 test_scripts/            # Unit, environment-preparation, and conformance runners
 config.yaml              # renderer configuration
 ```

package/forge/skills/load-plain-reference/references/rendering-and-testing.md

@@ -6,8 +6,10 @@ Functional specs render from top to bottom. When rendering one functional spec,
 the previous specs but not future specs. A required module's functional specs also count as previous
 specs according to the module rules.
 
-Each functional spec receives its own conformance-test folder. After a new spec renders, the
-renderer runs conformance tests for previous specs to detect regressions. A new failure can mean:
+The renderer reads the test plain files and generates exactly the scenarios they hold,
+one labelled test per scenario-id; it never adds a test of its own. Each functionality receives its own
+conformance-test folder, named by its func-id. After a new spec renders, the renderer runs conformance
+tests for previous specs to detect regressions. A new failure can mean:
 
 1. The generated implementation does not satisfy the specification.
 2. The generated conformance test does not accurately test the specification.
@@ -24,7 +26,7 @@ and debugged, but never edited directly. Apply fixes as follows:
 - Behavior or implementation/unit-test guidance: edit definitions, functional specs, or
   implementation requirements as appropriate.
 - Conformance-test guidance: edit test requirements.
-- Acceptance-test guidance: edit the acceptance tests nested under their owning functional spec.
+- Scenario guidance: edit the scenarios in the functionality's test plain file with `add-test-scenarios`.
 
 Re-render after correcting the source specification.
 
@@ -37,7 +39,7 @@ Test scripts are renderer entry points as well as developer utilities:
 - `prepare_environment_<lang>` optionally prepares a reusable system-temporary environment for
   conformance testing once per render.
 - `run_conformance_tests_<lang>` receives the generated build folder and one functionality's
-  conformance-test folder (`plain_modules/<module_name>/tests/<functionality>`). It may run repeatedly during a render.
+  conformance-test folder (`plain_modules/<module_name>/tests/<func-id>`). It may run repeatedly during a render.
 
 Invoke the corresponding `implement-*-script` skill when creating or changing a test script. Those
 skills own exact staging, cleanup, dependency-installation, shell, and exit-code contracts.
@@ -50,7 +52,7 @@ Run project scripts from the repository root, using the filenames configured for
 ./test_scripts/run_unittests.sh plain_modules/<module_name>/code
 ./test_scripts/prepare_environment.sh plain_modules/<module_name>/code
 ./test_scripts/run_conformance_tests.sh \
-  plain_modules/<module_name>/code plain_modules/<module_name>/tests/<functionality>
+  plain_modules/<module_name>/code plain_modules/<module_name>/tests/<func-id>
 ```
 
 The renderer resolves script arguments to absolute paths. Test scripts must treat input directories

package/forge/{rules → skills/load-plain-reference/rules}/bullet-continuation.md

@@ -4,7 +4,7 @@ description: Bullet and continuation syntax for every section in .plain files
 
 # Rules for bullets and continuations in `.plain` files
 
-These rules apply to every section and to concept explanations.
+These rules apply to `***definitions***`, `***implementation reqs***`, and `***test reqs***`, and to concept explanations. The body of a functionality and a scenario in a test plain file are free text; these rules do not apply there (see `func-specs.md` and `test-plain-files.md`).
 
 ## No line-length limit
 
@@ -25,14 +25,14 @@ clarification of the statement above it. There is no third, typographic reason t
   indistinguishable from a deliberate sub-point
 - The test: if content deserves its own line, it deserves its own `- ` bullet; if it doesn't,
   keep it on the parent's line
-- What the renderer does enforce is the top level: every statement in a section must be a `- `
-  list item — a flush-left prose line is a syntax error. A bare continuation, by contrast, is
-  accepted and folded into its parent item verbatim
+- What the renderer does enforce is the top level of `***definitions***`, `***implementation reqs***`,
+  and `***test reqs***`: every statement there must be a `- ` list item — a flush-left prose line is
+  a syntax error. A bare continuation, by contrast, is accepted and folded into its parent item verbatim
 
 BAD — line broken for width (bare continuation):
 
 ```plain
-***functional specs***
+***definitions***
 
 - :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle(),
   which returns a list of :EventEnvelope: dicts conforming to the gateway contract.
@@ -41,25 +41,25 @@ BAD — line broken for width (bare continuation):
 GOOD — one valid list item:
 
 ```plain
-***functional specs***
+***definitions***
 
 - :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle(), which returns a list of :EventEnvelope: dicts conforming to the gateway contract.
 ```
 
-BEST — separate clarifications expressed as nested bullets:
+BEST — separate clarifications, each as its own bullet:
 
 ```plain
-***functional specs***
+***definitions***
 
 - :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle().
-  - The method returns a list of :EventEnvelope: dicts.
-  - The dicts conform to the gateway's :EventEnvelope: contract.
+- The method returns a list of :EventEnvelope: dicts.
+- The dicts conform to the gateway's :EventEnvelope: contract.
 ```
 
 ## Presenting `.plain` examples
 
 - Show every example under its owning section header
-- Separate top-level list items with one blank line
+- Separate top-level list items, functionalities, and scenarios with one blank line
 - Keep nested clarifications directly under their parent without a blank line
 - BAD, WRONG, `Before:`, and `Too complex:` examples may intentionally demonstrate invalid syntax