@turri-dev/cli 0.1.27 → 0.1.28-next.d5f2680

package/docs/test-advisor.md

@@ -0,0 +1,110 @@
+# The test advisor
+
+Which functional specs need explicit testing scenarios is not obvious, and not every one should be tested - only the functionality that matters. The test advisor decides for you: when a functional spec is new or its text changed and it has no scenarios - or when the chat asks - turri checks in the background whether it needs testing. When it does, the chat you are looking at tells you so and writes what testing it takes - the \*\*\*test reqs\*\*\*, the conformance testing script and its scenarios - so the module's conformance pulse runs once its code is built. The advisor decides; the chat is the only writer of the \*\*\*plain. You are never asked anything.
+
+## When it runs
+
+**Only with conformance tests on.** The advisor is there to say which functional specs need scenarios, and scenarios are only tested with `conformance-tests: true` ([config](config.md#conformance-tests)): off - as it is unset - the advisor is off too, by itself and when asked: the chat has no `evaluate_tests`, and a host's `evaluateTests` throws, saying how they are turned on.
+
+**Two ways in.** By itself, for every new or changed functional spec without scenarios, as below - what `test-advisor: false` turns off. And when the chat asks, with `evaluate_tests`, whatever the setting - see [asking for an evaluation](#asking-for-an-evaluation).
+
+**Only in the chat and a host.** Never in a headless command - `turri regenerate`, `conform`, `change-plain` and the rest - and never in [pi](https://pi.dev)'s print, json and rpc modes (`turri -p`), which end when the answer is printed. That is decided where the session starts: the terminal's chat and a host's session have one, nothing else does.
+
+**What it looks at by itself:** a functional spec, in any module, that is new or whose text changed since its code was built - measured against the code record, what the code was built from: text that differs from the record, or a functional spec not built yet. Then against the advisor's file: a text already looked at, under its hash, is not looked at again. So a fresh project's first functional specs are looked at, and a project already built that has no advisor file gets no backlog: only what changes from now on is.
+
+**What it leaves alone:**
+- a functional spec with scenarios of any kind - [today's review](regenerating.md#conformance-tests) of its scenarios covers it when its text changes
+- the standard library's templates, which have no functional specs
+
+**When:** by itself, as soon as the work loop sees a \*\*\*plain change - a `change_plain`, a `regenerate`, a pulse ending - beside the code pulse it plans. The functional spec is marked `pending` in the advisor's file there and then, so quitting loses nothing: the next start in the chat or a host picks up every `pending` entry.
+
+**Two at a time at most,** outside `parallel-jobs` and the lanes: it never takes a pulse's slot, no pulse waits for it, and it never steers or stops one.
+
+**A text that changes while it runs throws the work away,** whoever changed it - you, the chat's `change_plain`, a skill: what it had judged for the old text is dropped (`advisor.dropped`), and the new text starts again.
+
+A failure - a model error, a call that never answered - is dropped quietly: the entry says `failed` and why, `advisor.failed` goes into the ledger, and the same text is not tried again. Nothing is shown.
+
+## What you see
+
+**Being evaluated.** A change's result - `regenerate`'s, `change_plain`'s - names the functional specs the advisor has just taken up, as `evaluate_tests` names the ones it was asked for, and the chat says in a line that testing scenarios are being evaluated for them, and goes on: there is nothing to wait for.
+
+**A yes** comes back to the chat you are looking at as a message that starts a turn. It holds the report - the questions that were a yes with their evidence, and the inputs to cover - and the chat, asking you nothing, tells you in a line:
+
+> core:clear-tasks needs testing scenarios - a wrong implementation could look right. Writing them now.
+
+Then it writes, with `change_plain`, whatever the [step-7 guard](regenerating.md#the-steps-of-adding-tests) would refuse the scenarios for, in turn and only what is missing: the \*\*\*test reqs\*\*\* of the module it is tested in - the top of its chain, where its conformance tests live - the stack's conformance template, `stdlib/<kind>/conformance/<stack>`, imported, or the module's own; the conformance testing script for its stack, with `implement-conformance-testing-script` - in the background, the chat going straight on; then the scenarios, in `tests/<module>/<func-id>.plain`. They cover the report's inputs that are this functional spec's - an agreed one with the readers' output, never a placeholder - and a split one is settled by the reading most consistent with the functional spec and its module, the chat saying which it took. The change is visible as any is, and the conformance pulse follows once the code is built.
+
+**A no** is one line turri draws itself, starting no turn and reaching no model:
+
+> core:list-tasks doesn't need testing scenarios - nothing silent to get wrong.
+
+**Never an interruption.** A verdict that arrives while the chat is busy - its agent working, or you typing - waits until it is idle; verdicts that arrive meanwhile come together, as one turn for every yes and a line for each no. One whose functional spec changed meanwhile, or was given scenarios, is let go. A yes is kept in the advisor's file until a chat has it: one that arrives with no chat open, or whose session ends first, is delivered at the next start, as `pending` work is picked up.
+
+Asked for scenarios - "write conformance scenarios for core:add-task" - the chat decides and writes them itself, as a \*\*\*plain change you see, whatever `test-advisor` says.
+
+A host gets the verdicts in its chats the same way - see [hosting](hosting.md).
+
+## Asking for an evaluation
+
+The chat has a tool of its own, `evaluate_tests`: the functional specs as `module:func-id`s - or func-ids, with `plain_file` - and an optional `reason`. It returns at once - "Testing scenarios for core:add-task are being evaluated in the background; the verdict comes back to this chat." - and the verdict comes back as any verdict does. The chat calls it:
+
+- when you ask whether something needs tests - "does add-task need tests?";
+- on its own, as another way of saying what a functional spec means: when pulses keep failing on a complicated one, say, scenarios may pin down what it should do.
+
+It evaluates even a text the advisor already judged. A functional spec being evaluated already is not started twice, and one that has scenarios is answered at once as such and not evaluated. It works whatever `test-advisor` says. The `reason` - "the coding agent failed three times to implement it" - reaches the classifier as context, never as evidence.
+
+## How it decides
+
+Every step is a plain model call on the advisor's model, answered through one tool and checked by turri - none of them is a skill, and none can touch the project. Each is given the functional spec, its module whole - and for a module below, the tip its scenarios are tested in, whose own functional specs show in the same commands - and the project's own words on what matters: its `AGENTS.md`, and what you said in the conversation about how the work is to be planned. There is no keyword filter and no confidence score.
+
+**Classifying** is one call with four questions, each yes backed by evidence:
+
+| question | a yes needs |
+| --- | --- |
+| silent failure: could a wrong implementation give output that looks right? | one such wrong output |
+| divergence: is there an input two reasonable readings answer differently? | the input, and both outputs |
+| revisited: is it likely to be changed or built on later? | what would change |
+| cost: would a bug cost money, expose something, lose data or harm users' trust? | the consequence |
+
+A yes whose evidence is empty or malformed - two readings that are the same - counts as no. The verdict is **yes** when silent failure, divergence or cost is a yes; revisited alone, or all four no, is **no**: the coding agent's unit tests are the regression protection there. A no costs one call, and ends there.
+
+**On a yes, the inputs** the scenarios are to cover are picked by readers that disagree on purpose:
+
+1. **Probes:** one call writes concrete boundary inputs, as many as the functional spec has real boundaries - one to ten, never padded to a number - limits, empty and missing values, the cases the wording leaves open - and the divergence's input joins them. Only inputs the functional spec bears on: never a command, flag or alias it does not name.
+2. **Readers:** each predicts every probe's output. There are three - a literal reader, an edge-case hunter, and a reader from another domain - the same call on the same model, differing only by their system prompt. Two run first; when they already disagree on a probe, the third is spared. A reader answers `unspecified` for an input the functional spec says nothing about.
+3. **Comparing,** in code: the outputs are compared with whitespace and case left aside, and any disagreement makes the input a candidate - the union of the readers, never a majority.
+4. **Verifying:** one last call keeps, of each candidate, the readings a reasonable person could hold. A candidate left with one is an agreed input; one left with none is dropped. An input whose `unspecified` holds - every reader's, or one the verifier keeps - is left out: a scenario on it would pin a guess, testing more than the functional spec says.
+
+The **report** is what the advisor's file keeps: the questions that were a yes with their evidence, and each input, either agreed - with the readers' output - or split, with its readings.
+
+## The setting and its model
+
+`test-advisor: true | false` in `config.turri.yaml`, `true` when it is left out - `/turri-config` sets it. `false` turns off only the advisor's own start: `evaluate_tests` still works, and asked for scenarios, the chat writes them as it always has, whatever the setting says.
+
+Every call the advisor makes runs on `models.advisor` - see [models per role](config.md#models-per-role). Without one it runs on `default`'s model, else the coding model alone, thinking low.
+
+## What it keeps
+
+What the advisor made of each functional spec is in `.turri/advisor/<module>.json`, in the project - local to this machine, as all of `.turri/` is: another machine starts with none, and looks only at what changes there. One entry a functional spec, by its func-id:
+
+| | |
+| --- | --- |
+| `hash` | a hash of the functional spec's text: the entry is about that text, and stale once it changes |
+| `state` | `pending` - seen, not finished; `yes`; `no`; or `failed` |
+| `report` | the verdict, the questions that were a yes with their evidence, and on a yes the inputs to cover |
+| `model`, `at` | what it ran on, and when |
+| `tip` | the module at the top of its chain, where its scenarios are tested |
+| `undelivered` | a yes no chat has had yet: delivered at the next start |
+| `asked` | pending at the chat's asking, with its reason: picked up at the next start whatever `test-advisor` says |
+
+Deleting the folder loses only what the advisor knows: an entry that is not there is a functional spec it has not looked at.
+
+## In the ledger
+
+Three facts go into [the ledger](using.md#the-ledger), the report staying in the advisor's file:
+
+| event | |
+| --- | --- |
+| `advisor.classified` | the functional spec, `module:func-id`, its verdict, the questions that were a yes, and whether the chat asked for it (`asked: true`) or a change started it |
+| `advisor.dropped` | the work on a functional spec thrown away, its text changed while it ran |
+| `advisor.failed` | why it failed |

package/docs/theming.md

@@ -70,7 +70,7 @@ With tool rows carrying no background, their state is signalled by the title and
 
 ## \*\*\*plain diffs
 
-A \*\*\*plain diff in the panels is not painted with the theme's colours for code: those are made for code, and the turri themes' backgrounds are all the surface colour, so a diff drawn with them would have no fills and hardly any highlighting. It has a palette of its own (`src/regenerate/plain-palette.ts`), one for a dark theme and one for a light, picked by the theme's appearance: a hue for each piece of \*\*\*plain - a section's header, a concept, a link, text in quotes or backticks, a front matter key, a module, a comment - at least 7:1 on the surface, and a fill behind each added and removed line: on a dark theme blue whale and eggplant, on a light one neon hover and siesta tan. Every colour reads at least 4.8:1 on blue whale and 5:1 on the light fills; eggplant, the design system's only warm dark fill, takes the pinks and grauzone down to 3.7:1.
+A \*\*\*plain diff in the panels is not painted with the theme's colours for code: those are made for code, and the turri themes' backgrounds are all the surface colour, so a diff drawn with them would have no fills and hardly any highlighting. It has a palette of its own (`src/regenerate/plain-palette.ts`), one for a dark theme and one for a light, picked by the theme's appearance: a hue for each piece of \*\*\*plain - a section's header, the `# <id>` heading of a functional spec or a scenario (neon, bold; eggplant, bold, on a light theme), a concept, a link, text in quotes or backticks, a front matter key, a module, a comment - at least 7:1 on the surface, and a fill behind each added and removed line: on a dark theme blue whale and eggplant, on a light one neon hover and siesta tan. Every colour reads at least 4.8:1 on blue whale and 5:1 on the light fills; eggplant, the design system's only warm dark fill, takes the pinks and grauzone down to 3.7:1.
 
 ## The font
 

package/docs/using.md

@@ -9,7 +9,7 @@ turri
 
 That is [pi](https://pi.dev), with turri's tools, skills and themes loaded - `turri` alone, or with [pi](https://pi.dev)'s options (`turri -c`, `turri --harness-model <m>`). It holds several chats side by side, each working while another is shown: `/chat new` or `alt+n` opens one, `alt+1` … `alt+9` switch, and `turri -c` opens them all again - see [chats](chats.md). It opens with turri's own banner - the jellyfish it is named after, regenerating until the conversation fills the screen: a pixel polyp on the sea floor grows into the jellyfish - a bell from pink down to indigo, an orange gut, neon tentacles - which swims a while, sinks back to the floor, and the polyp grows again, round and round - and once the conversation fills the screen, comes to rest swimming, whole: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn at a third of the size in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, ported from the design system's pixel kit, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than [pi](https://pi.dev)'s startup header and resource list; `turri --verbose` shows those too. [pi](https://pi.dev)'s "Update Available" notice is left out - turri's [pi](https://pi.dev) is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not [pi](https://pi.dev)'s `π`. Talk to it: ask it to add a feature to \*\*\*plain, regenerate a module, fix a module's \*\*\*plain. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
 
-To start a project, just say what you want - `create a small server in Java Spring Boot` - and turri starts it in the conversation, without asking how: it takes the stack you named, or chooses one this machine can build, and says it in a line; writes the module importing the stack from the standard library, `config.turri.yaml` (conformance tests off unless you ask for them) and the unit testing script (with `implement-unit-testing-script`, unless there is one); then the smallest thing that runs, regenerated at once, and while it regenerates the main thing you described and at most one more, on their happy path - nothing you did not describe. You say `go on`, or what to change, and every change after is \*\*\*plain it writes and regenerates (`src/new-project.ts`).
+To start a project, just say what you want - `create a small server in Java Spring Boot` - and turri starts it in the conversation, without asking how: it takes the stack you named, or chooses one this machine can build, and says it in a line; writes the module importing the stack from the standard library, `config.turri.yaml` (conformance tests off unless you ask for them) and the unit testing script (with `implement-unit-testing-script`, unless there is one - in the background, on the coding model, while the first pulse waits for it); then the smallest thing that runs, regenerated at once, and while it regenerates the main thing you described and at most one more, on their happy path - nothing you did not describe. You say `go on`, or what to change, and every change after is \*\*\*plain it writes and regenerates (`src/new-project.ts`).
 
 Peeking is safe while a question is open - a skill's or the chat's: `ctrl+h` opens the side panel over the question, which waits under it as it was - the panel says `your question is waiting`, and `ctrl+h` or `esc` takes you back to answer it. (The question has the keys, so turri catches `ctrl+h` itself while one is open.) The dialog holds the question alone - no hint and no invitation; the `ctrl+h` under the job panel breathes until it is first pressed.
 
@@ -26,7 +26,9 @@ While a skill runs, a line above the input shows its phases, every one by name -
 | `glimpse` | the pulse a module's codebases would start next, and the whole prompt its coding agent would get - starting nothing |
 | `steer` | say how the work is planned - which functional specs go together, what first - for the project or one module, for the session; the next plan follows it, beside what AGENTS.md says under a heading naming the queue |
 | `conform` | write and run conformance tests for functional specs - now, or ahead of their code: every one tested in one conformance pulse, as far as a size guardrail lets (or one a functional spec, or a pulse each of groups you name - 1-3 and 4-6 - when you ask for that), started once every one named is regenerated; whatever the config says |
-| `validate` | validate \*\*\*plain, regenerating nothing |
+| `evaluate_tests` | have the [test advisor](test-advisor.md) judge whether functional specs need explicit testing scenarios, in the background - returning at once, the verdict coming back to the chat; whatever `test-advisor` says |
+| `turn_on_conformance_tests` | turn conformance tests on for the project - `conformance-tests: true`, for this session and the next - once you asked for them, or agreed when the chat offered them. The chat has it while they are off, and `conform` and `evaluate_tests` while they are on |
+| `parse` | parse \*\*\*plain - its syntax and structure, never its code or tests - regenerating nothing - a module whose functional specs have scenarios but which has no test reqs, or no conformance testing script for its stack, passes with a warning naming the next step (see [the steps of adding tests](regenerating.md#the-steps-of-adding-tests)) |
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
 | `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
@@ -53,10 +55,10 @@ A regeneration takes minutes, so in the TUI every tool that regenerates starts t
 
 - **The panel** above the input, while something runs, shows on top what finished - a line a module, the module that finished last on top, its pulses newest first, each with its mark (green, red or amber, as in the side panel), number and kind - what it regenerated is in the side panel - `cognio  ✓ 4 conformance · ✓ 3 regenerate · … 2 earlier`, the newest that fit the width - then a rule, and under it each running pulse, the newest first - `cognio · regenerate pulse 5`, `cognio · conformance pulse 6` - its time and cost, and what its agents are doing. A module whose work is being planned into pulses shows at once, before any pulse runs - `shorty · planning the pulses · 12s` - from the moment it is asked for: while its code is deleted for a start from scratch and what is left to regenerate is worked out, as well as while the planner, an agent, cuts it into pulses; a `/regenerate` says it began the moment it is sent. A \*\*\*plain change is looked at quietly, and shows only once the planner runs. Pulses are numbered within their module, as regen numbers them. `ctrl+o` expands the agents' trace alone; what finished stays a line a module. The line of keys under it - `ctrl+o to expand the trace · ctrl+h to peek at regen` - has each key breathing, fully there to a little faint and back, until it is first pressed: once `ctrl+o` has opened the trace, or the side panel has been opened, that key is still for the rest of the session and the other breathes on. What waits is not in it, and it shows no \*\*\*plain diff - the side panel has both. With nothing running it is gone.
 - **A pulse's change** is what its agent works from, not a text diff of the module's file: the items `<spec change>` gives the agent - only what the pulse's functional specs use, an import's items as well as the module's own, a code pulse's without the test reqs - each in the file it is written in, under its section, in the file's order (`change-view.ts`).
-- **A \*\*\*plain diff**, in the side panel, reads as an editor shows a diff: its [\*\*\*plain](https://plainlang.org/docs/) highlighted as [plyn](https://github.com/plainlang/plyn) highlights it - section headers, concepts, names in backticks, text in quotes, links, the front matter - each added line filled green and each removed one red, the text on top, the fill the width of the panel ([colours](theming.md#plain-diffs)). It is shown file by file, each file's lines together under its name, with what it adds and takes out - the module being regenerated first, the rest by name, and none the diff does not change. Each line has its number in that file: a \*\*\*plain diff is of \*\*\*plain as read, with what it imports laid in, so a line is placed in the file it is written in - its links read as the parser renders them - and a removed line, in no file now, goes with the change it is part of and has no number. A line is never put in a file on a guess: one that cannot be placed is listed last, under "not found in the spec's files". Where lines of a file are not in the diff, `↕ 28 lines` says how many, as GitHub does - `↑` above the first - and names the section the lines under it are in when it is another than the one above, `↕ 28 lines · ***functional specs***`, as GitHub names a hunk's function: each section is named once.
+- **A \*\*\*plain diff**, in the side panel, reads as an editor shows a diff: its [\*\*\*plain](https://plainlang.org/docs/) highlighted by turri's own grammar, which started from [plyn](https://github.com/plainlang/plyn)'s - section headers, the `# <id>` heading of a functional spec or a scenario, concepts, names in backticks, text in quotes, links, the front matter - each added line filled green and each removed one red, the text on top, the fill the width of the panel ([colours](theming.md#plain-diffs)). It is shown file by file, each file's lines together under its name, with what it adds and takes out - the module being regenerated first, the rest by name, and none the diff does not change. Each line has its number in that file: a \*\*\*plain diff is of \*\*\*plain as read, with what it imports laid in, so a line is placed in the file it is written in - its links read as the parser renders them - and a removed line, in no file now, goes with the change it is part of and has no number. A line is never put in a file on a guess: one that cannot be placed is listed last, under "not found in the spec's files". Where lines of a file are not in the diff, `↕ 28 lines` says how many, as GitHub does - `↑` above the first - and names the section the lines under it are in when it is another than the one above, `↕ 28 lines · ***functional specs***`, as GitHub names a hunk's function: each section is named once.
 - **The side panel** (`ctrl+h`, as it was left - but on the pulse that last failed, stopped or did not pass, when one has since it was last opened: the live panel that showed it is gone with the last pulse, and its announcement in the chat says `ctrl+h shows this pulse`; **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty keyboard protocol sends as a line feed, the same as `shift+enter`, and which a dialog takes for `enter`; both stay [pi](https://pi.dev)'s new-line keys. `ctrl+h` is the byte old terminals sent for backspace; a terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time - or, `s`, sits beside the chat: the chat on the left, the panel in the right half of the screen, and `s` again over the whole screen. It opens as it was last left, for the conversation; a terminal under 104 columns - 100 inside the screen's padding, a blank row above and below everything and two columns either side - has no room for both and shows the panel over the whole screen. It opens on **regen**: the module's \*\*\*plain itself, in full, with how much of it the code has been regenerated from drawn onto it.
 
-  Every item of the module's \*\*\*plain - a definition, a req, a functional spec with its sub-bullets and acceptance tests, what turri plans and diffs by - is a row in the file's order, its \*\*\*plain highlighted as plyn highlights it (as a \*\*\*plain diff is) and wrapped to the width, never cut short. The map has two columns, each headed on the line over it with a line of space under it: **status**, a mark a row - its rung on a ladder every item climbs - and the module's file, its \*\*\*plain. The top of the panel is where it is seen first: the top line, the module tabs, and the keys - each view's, `d talk it through in the chat` first when the module needs you - wrapped, never cut short, a line of space between the top line and the keys; then straight under them a rule, a line of space, and the columns' headings. The pulses view has its keys at the top too, and a line of space under its rule. The legend is a box of its own in the upper right corner, over what is under it, a line a mark, up the ladder. It names every rung, whatever the page shows - to take out only where something is - and a panel under 60 columns wide has none.
+  Every item of the module's \*\*\*plain - a definition, a req, a functional spec with its body and its scenarios, what turri plans and diffs by - is a row in the file's order - a functional spec's row is as its file writes it, its `# <func-id>` heading and its body's first line under it; opened, its scenarios follow, `***conformance tests***` and `***acceptance tests***` and the scenarios under them indented one step under the functional spec, a line of space after each scenario - its \*\*\*plain highlighted as a \*\*\*plain diff is and wrapped to the width, never cut short. The map has two columns, each headed on the line over it with a line of space under it: **status**, a mark a row - its rung on a ladder every item climbs - and the module's file, its \*\*\*plain. The top of the panel is where it is seen first: the top line, the module tabs, and the keys - each view's, `d talk it through in the chat` first when the module needs you - wrapped, never cut short, a line of space between the top line and the keys; then straight under them a rule, a line of space, and the columns' headings. The pulses view has its keys at the top too, and a line of space under its rule. The legend is a box of its own in the upper right corner, over what is under it, a line a mark, up the ladder. It names every rung, whatever the page shows - to take out only where something is - and a panel under 60 columns wide has none.
 
   | Mark | Legend | Means |
   | --- | --- | --- |
@@ -68,13 +70,13 @@ A regeneration takes minutes, so in the TUI every tool that regenerates starts t
   | `!` | needs you | in the pulse that did not land and halted the module, or the planner found no plan |
   | `−` | to take out | taken out of \*\*\*plain, still in the code - a struck-through red ghost, with the code record's text, until the pulse that takes it out lands |
 
-  `◇` and `◆` are both green, and mean the same whatever `conformance-tests:` says: a functional spec regenerated and not conformed is `◇` with its conformance tests on, off or not chosen, so changing the setting changes no mark. Tests written for an earlier text leave it at `◇`. Definitions and reqs are never conformed: `◇` is as far as they go. Test reqs are shown only where conformance tests are on - `conformance-tests:` is not `false`, or `conform` turned them on this session. A test req is the conformance tests', never built into the code: `◆` once they follow it as it reads now, the green `⠋` while a conformance pulse writes them for it, `○` until then - and no mark where no conformance test is written at all. No pulse numbers are drawn in the gutter - they move whenever the plan is made again; `p` on an item goes to the pulse that brings it.
+  `◇` and `◆` are both green: a functional spec regenerated and not conformed is `◇` - and one with no scenarios stays there, its last rung, not tested. Tests written for an earlier text, or for scenarios that changed since, leave it at `◇`. Items and pulses are matched by func-id, and the cursor stays on a functional spec by its func-id whatever is written above it. Definitions and reqs are never conformed: `◇` is as far as they go. Test reqs are always shown; where no functional spec of the module has scenarios, nothing uses them, and the first says `not used: no scenarios`. A test req is the conformance tests', never built into the code: `◆` once they follow it as it reads now, the green `⠋` while a conformance pulse writes them for it, `○` until then - and no mark where no conformance test is written at all. No pulse numbers are drawn in the gutter - they move whenever the plan is made again; `p` on an item goes to the pulse that brings it.
 
   **Needs you.** The top line ends `! needs you`, in red, and under the first `!` of the module is what for, and how: `needs you - pulse 3 didn't land - its unit tests never passed · d to talk it through in the chat`. `d` closes the panel and asks the chat, in your words, what went wrong and what to do about it, with turri's reason for the halt; the chat works it out with you - a diagnosis, a change to \*\*\*plain, the machine set up - and regenerates. Pulses are numbered as they start in a module, from 1 each session.
 
-  A changed item shows what changed in it: its first line word by word - what is gone struck through in red, what is new in green, what is kept highlighted as it reads now - and, under it, only the sub-bullets that changed. \*\*\*plain never built that is taken out is simply gone. The top line has a strip of the module's functional specs - built, regenerating, planned, waiting - and how many are built, then what is happening: `pulse 3 of 8 regenerating`, or why nothing is - `not asked to build - regenerate plans it` (turri was just opened, or nothing has asked for the module: the plan lives in memory and is made again on the next regeneration), `planning`, `waits for backend`, or `! needs you`. `enter` opens an item: all of its text against the code's, and its acceptance tests. Where it stands is beside its mark, and is not said again under it.
+  A changed item shows what changed in it: its first line word by word - what is gone struck through in red, what is new in green, what is kept highlighted as it reads now - and, under it, only the sub-bullets that changed. \*\*\*plain never built that is taken out is simply gone. The top line has a strip of the module's functional specs - built, regenerating, planned, waiting - and how many are built, then what is happening: `pulse 3 of 8 regenerating`, or why nothing is - `not asked to build - regenerate plans it` (turri was just opened, or nothing has asked for the module: the plan lives in memory and is made again on the next regeneration), `planning`, `waits for backend`, or `! needs you`. A module whose functional specs have scenarios but which skipped a step of adding tests has it said after that - `· scenarios not tested: no test reqs`, or `· scenarios not tested: no conformance testing script` - until the step is taken ([the steps of adding tests](regenerating.md#the-steps-of-adding-tests)). `enter` opens an item: all of its text against the code's, and its acceptance tests. Where it stands is beside its mark, and is not said again under it.
 
-  One module is shown at a time, with a tab for each module of the chain on the line under the top line, in the chain's order - the module it is built on to the left: `d365_version_api  [d365_http_client]  d365_utils 12 ›`. A tab regenerating spins, one stuck says `!`; what does not fit is counted at either end. `←` `→` go from one tab to the next. The module shown is the one in focus - the one regenerating now, else the one asked for, else the first - until you pick another tab; it goes back to following once another module is in focus, or the one in focus starts regenerating. Under the module's own text is what it imports, under **imported**, a folded block a file, `▸ from stdlib/backend/python-fastapi · 7 reqs · all built`, closed until opened. The modules it requires are tabs of their own: a chain of many modules is never drawn nested, one in the next. A map longer than the screen has a minimap down its right edge, a cell a slice in the colour of its most pressing mark, the slice shown solid. The map is read from the files - the code record, the `.plain` files, the tests record - so it is right the moment turri opens a project, before anything runs; the work loop's plan adds the pulses on top. It maps the files asked to build this conversation, else `module:` in `config.turri.yaml`, else the `.plain` files of the folder that no other one there imports or requires - the folder's files looked at again only once one of them, or its config, changes. `↑` `↓` move row by row, `enter` or `space` open and close an item or an import block - a functional spec opens to its sub-bullets and its `***acceptance tests***`, nested under it as \*\*\*plain has them - `←` `→` go to the next module's tab, `o` and `c` open or close everything shown, `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom.
+  One module is shown at a time, with a tab for each module of the chain on the line under the top line, in the chain's order - the module it is built on to the left: `d365_version_api  [d365_http_client]  d365_utils 12 ›`. A tab regenerating spins, one stuck says `!`; what does not fit is counted at either end. `←` `→` go from one tab to the next. The module shown is the one in focus - the one regenerating now, else the one asked for, else the first - until you pick another tab; it goes back to following once another module is in focus, or the one in focus starts regenerating. Under the module's own text is what it imports, under **imported**, a folded block a file, `▸ from stdlib/backend/python-fastapi · 7 reqs · all built`, closed until opened. The modules it requires are tabs of their own: a chain of many modules is never drawn nested, one in the next. A map longer than the screen has a minimap down its right edge, a cell a slice in the colour of its most pressing mark, the slice shown solid. The map is read from the files - the code record, the `.plain` files, the tests record - so it is right the moment turri opens a project, before anything runs; the work loop's plan adds the pulses on top. It maps the files asked to build this conversation, else `module:` in `config.turri.yaml`, else the `.plain` files of the folder that no other one there imports or requires - the folder's files looked at again only once one of them, or its config, changes. `↑` `↓` move row by row, `enter` or `space` open and close an item or an import block - a functional spec opens to the rest of its body and its scenarios, under `***conformance tests***` and `***acceptance tests***`, each `# <scenario-id>` and its text, as its test plain file has them - `←` `→` go to the next module's tab, `o` and `c` open or close everything shown, `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom.
 
   `p` goes to the **pulses** - and back - onto the pulse that regenerates the item under the cursor, and back onto the first item the pulse under the cursor regenerates. The pulses are every pulse as three sections - running, queued, finished - each opened and closed on its own (running and queued start open), the newest first in each - running by when it started, queued by when it was queued, finished by when it ended - and a fourth, **earlier sessions**, closed, when the [ledger](#the-ledger) has pulses of sessions before this one: its last three runs', each pulse read only - opened, what the ledger says of it (how it ended, its rounds and test runs, the healers, what turri refused and committed, its last stages and its log), and under it a row for each file its \*\*\*plain diff changes, as a pulse of this session has - and a line for how many more runs it has. A pulse is one line: its module, kind and number (`hubspot · regenerate pulse 1`, `hubspot · conformance pulse 2`) - so it is named wherever a pulse is named in a line (the job panel, the `pulses` tool, `/halt`, the command line), never by what it regenerates, which is in it, opened - its time (none while it is queued: it has not started) and its cost - a finished one's mark green when it passed, red when it failed or did not pass, amber when it was stopped. Opened, a running one shows what it is doing; a queued one, what it waits for; a finished one, its agents and what each spent, and whether it did not pass. Under it is a row for each file its \*\*\*plain diff changes - the file of the module being regenerated first and open, the rest by name and closed - each opening onto that file's lines. A file with nothing added or taken out is not listed. `↑` `↓` move, `enter` or `space` open and close what is under the cursor, `→` `←` open and close (`←` on a closed pulse goes to its section, on a closed file to its pulse), `o` and `c` open or close every pulse of the section - or, on a file, every file of its pulse - `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom. The cursor stays on its row when the pulse under it moves on; a pulse opened closes when it moves to another section. What is open is kept while the panel is closed. What the agents said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
 
@@ -83,12 +85,12 @@ A regeneration takes minutes, so in the TUI every tool that regenerates starts t
 - **`/turri-config`** changes a setting of the project's `config.turri.yaml` - the models, review, conformance tests, any key - and says when it takes effect: now, at your next message, or at the next pulse; never only after a restart. See [changing it from the chat](config.md#changing-it-from-the-chat).
 - **`/sentinel`** says whether the [sentinel](sentinel.md) checks every pulse that finishes: `ask` - you are asked before it first opens in a session - `on`, or `off`; written to `config.turri.yaml`.
 - **`/stack`** chooses the stack everything is built with from then on, in a project whose parts are on different stacks: a list of the project's stacks, or `/stack backend`, `/stack none`. The stack's `config.turri.<stack>.yaml` is laid over `config.turri.yaml` - its testing scripts, toolchains, models - for the session; a module already asked for keeps the stack it was asked for with. The chat model switches it too when you ask - and, to build one part, passes that part's stack to `regenerate` instead, leaving the session's as it is. See [stacks](config.md#stacks).
-- **`/regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its \*\*\*plain as it is now, as the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few together or the whole module in one, as the planner judges - and the first starts. Words after the module are guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is that module - `/regenerate d365_function executor` is `d365_function_executor`. With no module named: the one `module:` in `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`, `start over`, `delete the module` - it starts at once, with nothing to confirm: it deletes the module's code and conformance tests in every codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its \*\*\*plain, built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch, the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not with `--dry-run`. Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their \*\*\*plain did not change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's `regenerate` with `functionalities`.
+- **`/regenerate [module | file.plain] [module:func-id ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its \*\*\*plain as it is now, as the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few together or the whole module in one, as the planner judges - and the first starts. Words after the module are guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is that module - `/regenerate d365_function executor` is `d365_function_executor`. With no module named: the one `module:` in `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`, `start over`, `delete the module` - it starts at once, with nothing to confirm: it deletes the module's code and conformance tests in every codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its \*\*\*plain, built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch, the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not with `--dry-run`. Functional specs named after the module, each as `<module>:<func-id>` - `/regenerate shorty shorty:shorten shorty:expand` - are regenerated though their \*\*\*plain did not change, on the model chosen for functionalities: as `turri regenerate shorty.plain shorty:shorten shorty:expand` does, and the chat's `regenerate` with `funcIds`. A bare func-id is refused: the module is always named. Code built before functional specs had func-ids - its record numbers them - is never built on: the module's whole chain has to be regenerated from scratch, and the chat asks you first, as for a start over.
 - **`/halt <id>`** halts a pulse - a queued one never starts - **`/halt <module>`** (or a planned row's id) halts a module's planned pulses until you ask for it again, a \*\*\*plain change not starting it, and **`/halt activated <name>`** halts a server `activate` started; it lists all three when no id is given.
 - **What these commands show you, the chat knows.** What `/regenerate` and `/halt activated` tell you - \*\*\*plain that does not parse, the pulses planned, a server halted - stays in the chat under the command, and since a slash command runs outside the conversation, it is put in the conversation as well: say "fix it" next and turri knows what you are looking at. Once `/regenerate` has started pulses, turri says so in the chat too - what runs and what is planned, and that you need not wait for it - without starting anything more for it; a module already up to date gets the plan's answer alone. A halted pulse reaches it as every pulse's end does.
 - **Nothing is queued.** What is left to build is worked out from what each codebase is built from and \*\*\*plain as it is now - again whenever a pulse ends or \*\*\*plain changes - and the first pulse of it runs; see [a whole module](regenerating.md#a-whole-module). Changes that overlap never pile up: the next pulse builds \*\*\*plain as it is. The pulses planned after the one running are listed behind it, as queued, and so is each module waiting for the one it is built on - "waits for base" - until it can be planned. A change inside what the running pulse regenerates - a functional spec it regenerates reworded or given a sub-bullet, a definition or req it is given, a file they link - steers it: its agent is told, and it lands \*\*\*plain as it is now there, twice a pulse at most. Otherwise a pulse building something \*\*\*plain no longer wants is stopped and rolled back - unless `allow-to-stop-jobs: false` in `config.turri.yaml`, which has it land first and the change regenerated on top. To drop something, take it out of \*\*\*plain - one \*\*\*plain diff. Stopping a pulse leaves its change in \*\*\*plain: the codebase waits until its \*\*\*plain changes or it is asked for again.
 - **A change to a module below** is made in the codebase at the tip of the chain, where its code lives; the codebase below is left as it was, and is brought up to its own \*\*\*plain only when a new module is to start from it. \*\*\*plain moved into a module the code was not built on stops the codebase: no change to its code brings that module in, so it has to be started over - its code and conformance tests taken out, kept in its history, and built again from the bottom of the chain. That is never done unasked: the chat asks you, saying why, and regenerates it from scratch once you agree; on the command line `turri regenerate` asks at the terminal, and `--start-over` agrees in advance.
-- **Conformance tests are a track of their own.** A code pulse lands once its unit tests pass and are reviewed. Then, before the next one builds on it, a conformance pulse writes and runs the tests of what it built - from the test reqs and acceptance tests - with the whole suite the module inherits, and, where one fails, fixes the test or the code, whichever is wrong; what they are written for is recorded in `tests/.turri.json`. With `conformance-tests: false` none is written until you ask - `conform`, for a module or some of its functional specs - but those there are are kept up to date: a functional spec that has conformance tests and is regenerated gets a conformance pulse for it alone. A conformance pulse that does not pass is undone whole and halts the conformance tests alone: the code goes on being built.
+- **Conformance tests are a track of their own.** A code pulse lands once its unit tests pass and are reviewed. Then, before the next one builds on it, a conformance pulse writes and runs the tests of what it built - the scenarios of its functional specs, by the test reqs - with the whole suite the module inherits, and, where one fails, fixes the test or the code, whichever is wrong; what they are written for is recorded in `tests/.turri.json`. A functional spec with no test plain file, or an empty one, gets none: to have it tested, ask for conformance tests, or let the [test advisor](test-advisor.md) find that it needs them - either way the chat writes its scenarios with `change_plain`, and the loop tests them once the code is built. `conform` runs them now, for a module or some of its functional specs. A conformance pulse that does not pass is undone whole and halts the conformance tests alone: the code goes on being built.
 - **A pulse that fails** - its work errors, or it does not pass - is run once more; one stopped on what only you can fix - the machine lacks something, a testing script no code could pass - is not. Failing again, it stops, and so does every pulse queued behind it on the same module, without running - the other modules' pulses go on. The harness then works out why: an agent that can read the project's \*\*\*plain, code, tests, testing scripts and logs, and turri's own source, skills and rules, says what happened, why, whether the fix belongs in \*\*\*plain, the environment, the code or turri itself, and exactly what to do.
 - **When a pulse finishes** the transcript shows its line - `✓`, `✗` or `■`, its module, kind and number, how long it took and what it cost, never what it regenerated - `✓ shorty · conformance pulse 4 finished after 3m 47s · 488.6k tok · $0.02` - and the chat, which gets its whole report, reacts then and there, whatever else is running or queued, without waiting for you to speak: at once when it is idle, else as soon as the reply it is in ends. It does what the project's guidance says to do when a pulse finishes - release what was built, say - or tells you what finished and what it means. Ask to try it ("let me try it") and the chat releases what is built to `dist/<module>` and starts it on your machine, even while other pulses run. See [deploy](deploy.md). The chat reacts to it then and there, whatever else is running or queued, without waiting for you to speak - at once when it is idle, else as soon as the reply it is in ends: it does what the project's guidance says to do when a pulse finishes (release what was built, say), or tells you in a line or two what finished.
 - **When a pulse stops** - a gate still failing after 20 attempts - it says where it stopped, why in plain words, and what to change in \*\*\*plain - which section, and how. Running the same build again picks up from there.
@@ -97,7 +99,7 @@ In `print`, `json` and `rpc` modes the process ends when the answer is written,
 
 ## The project's config.turri.yaml
 
-The chat reads the project's `config.turri.yaml` afresh every turn and follows it: its agent is told what it sets, and the tools that regenerate default to it - `module` when you ask to build without naming one, `conformance-tests: false` to regenerate without writing new conformance tests unless you ask for them (the ones there are kept up to date), `coding-model` for what regenerations run on, and the testing scripts. `harness-model` is what `turri` starts on. What you ask for in the conversation wins. Every key, what happens without it, and how the models inherit: [the project config](config.md).
+The chat reads the project's `config.turri.yaml` afresh every turn and follows it: its agent is told what it sets, and the tools that regenerate default to it - `module` when you ask to build without naming one, `coding-model` for what regenerations run on, and the testing scripts. `harness-model` is what `turri` starts on. What you ask for in the conversation wins. Every key, what happens without it, and how the models inherit: [the project config](config.md).
 
 A project whose parts are on different stacks gives each stack its own `config.turri.<stack>.yaml` beside `config.turri.yaml` - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - with its testing scripts, models and conformance over the project's. A stack named after its module builds it - `config.turri.backend.yaml` builds `backend.plain` - with nothing to choose, so a backend and a frontend are each built with their own, side by side; for a stack named otherwise the chat's model passes it as `stack`, or choose one for the session with `/stack backend`. The chat is told each stack's and which is chosen, and the status bar shows it. See [stacks](config.md#stacks).
 
@@ -179,7 +181,7 @@ It is in `.turri/ledger/` in the project, a JSON line an event, one file a run -
 | --- | --- |
 | runs | `run.started` (how it was started, turri's version and commit, the machine), `run.ended` |
 | pulses | `job.queued` (with the functional specs it covers, by case), `job.diff` (its \*\*\*plain diff, whole, and where its lines are written - again each time steering moves it), `job.started`, every `job.stage`, `job.retried`, `job.finished` - its status, whether it landed, how long it ran, what it cost, how it ended |
-| the work loop | `loop.halted`, `loop.stopped` (a pulse \*\*\*plain moved on from), `planner.failed`, `planner.fellBack` |
+| the work loop | `loop.halted`, `loop.stopped` (a pulse \*\*\*plain moved on from), `loop.renamed` (a pure rename turri made itself - a func-id or a scenario-id, from and to), `planner.failed`, `planner.fellBack` |
 | the model | `model.call` (time and tokens), `model.turn`, `model.compaction`, `provider.retry`, `provider.stall`, `provider.error`, `turn.stopped` (a turn turri ended itself, and why) |
 | tools and tests | `tool.call` (the tool, how long, whether it failed - never its arguments or result), `script.run` (the testing script, its exit, how long, whether the time limit stopped it, the failure's fingerprint, and `mutated` for a `can_it_fail` run on code broken on purpose) |
 | the gates | `gate.round`, `review.verdict`, `arbiter.ruling`, `judge.verdict` |
@@ -200,19 +202,19 @@ It is for looking up, never for deciding: what to build comes from the records a
 The same work, without a conversation. Run it from the directory that holds the module's \*\*\*plain, so its linked resources resolve the way the parser expects. For a long run - a whole module's \*\*\*plain overnight - see [running unattended](headless.md).
 
 ```bash
-turri validate <file.plain>            # validate a spec - no model, no API key
+turri parse <file.plain>            # parse ***plain, its syntax and structure - no model, no API key
 turri drift <file.plain>               # what is left to regenerate - no model, starts nothing
 turri regenerate <file.plain>              # regenerate what the code is not built from yet, and what it requires
 turri glimpse <file.plain>             # plan it, and print the first job's prompt - starts nothing
-turri regenerate <file.plain> 2            # regenerate functionality 2 again, changed or not
+turri regenerate <file.plain> app:add-task   # regenerate a functional spec again, changed or not
 turri regenerate <file.plain> --from-scratch   # delete the module's code and tests (its lineage keeps them), regenerate all of it
 turri regenerate <file.plain> --from-scratch-chain   # the same for every module of its requires chain, from the bottom
 turri change-plain <file.plain> <diff>    # apply a ***plain diff, and regenerate it
-turri conform <file.plain> 1           # black-box tests for functionality 1
+turri conform <file.plain> app:add-task   # black-box tests for one functional spec
 turri lineage <module>                 # what each regeneration changed in a module, and when
 turri ledger [pulse]                   # what turri did here: the last runs and their pulses, or one pulse
 turri cultivate debug-specs            # run a skill directly - by name, the project's too, or by its folder
 turri release <file.plain>             # release what is regenerated to dist/<module>, and activate it here
 ```
 
-The ones that build take `--model provider/model-id`; `regenerate` also takes `--build-dir` and `--dry-run`, which plans the work, prints the prompt of each codebase's first pulse and starts nothing. Template directories come from `PLAIN_TEMPLATE_DIRS`. `--help` on any of them lists the rest.
+`turri cultivate` runs a skill on the project's harness model, as the chat does, unless `--model` names another. The ones that build take `--model provider/model-id`; `regenerate` also takes `--build-dir` and `--dry-run`, which plans the work, prints the prompt of each codebase's first pulse and starts nothing. Template directories come from `PLAIN_TEMPLATE_DIRS`. `--help` on any of them lists the rest.

package/genome/rules/bullet-continuation.md

@@ -1,10 +1,10 @@
 ---
-description: Bullet and continuation syntax for every section in .plain files
+description: Bullet and continuation syntax for the definitions, implementation reqs and test reqs of .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 functional spec, and of a scenario in a test plain file, is free text: these rules do not apply there (see `func-specs.md` and `test-plain-files.md`).
 
 ## No line-length limit
 
@@ -15,17 +15,17 @@ These rules apply to every section and to concept explanations.
 
 ## One statement per line
 
-This is the preferred `.plain` authoring convention, not something the renderer enforces. A line break in a section means one of exactly two things: a new `- ` statement, or a nested `- ` clarification of the statement above it. There is no third, typographic reason to break a line.
+This is the preferred `.plain` authoring convention, not something turri enforces. A line break in these sections means one of exactly two things: a new `- ` statement, or a nested `- ` clarification of the statement above it. There is no third, typographic reason to break a line.
 
 - Write each statement on a single line, however long
 - Never break a line just for width: a bare continuation (an indented line without `- `) adds a line break that carries no structure — to every future reader and editing agent it is 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 turri 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.
@@ -34,7 +34,7 @@ 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.
 ```
@@ -42,7 +42,7 @@ GOOD — one valid list item:
 BEST — separate clarifications expressed as nested bullets:
 
 ```plain
-***functional specs***
+***definitions***
 
 - :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle().
   - The method returns a list of :EventEnvelope: dicts.
@@ -52,7 +52,7 @@ BEST — separate clarifications expressed as nested bullets:
 ## 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, functional specs 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