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

package/genome/rules/project-model.md

@@ -1,5 +1,5 @@
 ---
-description: The ***plain project model - the specs as source of truth, the repository layout, generated output, template parameters, and what an earlier test failing after a render means
+description: The ***plain project model - the ***plain as source of truth, the repository layout, generated output, template parameters, and what an earlier test failing after a regeneration means
 ---
 
 # The ***plain project model
@@ -9,28 +9,29 @@ This rule covers the project as a whole. Section content is owned by the per-sec
 ## Source of truth
 
 - The `.plain` files are the source of truth. They state what the software does, how it is built, and how it is tested; the code is generated from them
-- Every change to the software is a change to a `.plain` file, which the next render builds. A fix made anywhere else is lost the next time the code is regenerated
+- Every change to the software is a change to a `.plain` file, which the next regeneration builds. A fix made anywhere else is lost the next time the code is regenerated
 
 ## Repository layout
 
 ```text
 *.plain                  # root modules: what the software does
 template/*.plain         # import modules: shared definitions and reqs
-resources/               # files specs link to: schemas, API specs, fixtures
+tests/<module>/<func-id>.plain  # test plain files: the scenarios of each functional spec
+resources/               # files ***plain links to: schemas, API specs, fixtures
 test_scripts/            # unit and conformance runners, found by turri (not linked)
-config.turri.yaml        # the project's build decisions: models, conformance tests, the scripts in use
+config.turri.yaml        # the project's build decisions: models, the scripts in use
 plain_modules/           # generated - one folder per module
   <module>/code/         #   implementation and unit tests
   <module>/tests/        #   the whole conformance suite of the module
 ```
 
-Follow `module-structure.md`, `import-modules.md` and `linked-resources.md` for what these directories may contain and how a spec refers to them.
+Follow `module-structure.md`, `import-modules.md` and `linked-resources.md` for what these directories may contain and how ***plain refers to them.
 
 ## The config records the build decisions
 
-`config.turri.yaml`, at the project root beside the specs, is where the project's decisions about how it is built live: the models, whether conformance tests are written (`conformance-tests:`), and the scripts it uses (`unittests-script:`, `conformance-tests-script:`, `prepare-environment-script:`). turri can find a script by its name, but the config is what a person reads to see how the project is set up, and what they change.
+`config.turri.yaml`, at the project root beside the ***plain, is where the project's decisions about how it is built live: the models, and the scripts it uses (`unittests-script:`, `conformance-tests-script:`, `prepare-environment-script:`). turri can find a script by its name, but the config is what a person reads to see how the project is set up, and what they change.
 
-- Settle a decision, write it into the config in the same step - never leave it to be inferred from what is on disk. A testing script you write or keep is named by its key, by path from the root (`unittests-script: test_scripts/run_unittests_python.sh`); conformance tests turned on or off are `conformance-tests: true` or `false`
+- Settle a decision, write it into the config in the same step - never leave it to be inferred from what is on disk. A testing script you write or keep is named by its key, by path from the root (`unittests-script: test_scripts/run_unittests_python.sh`)
 - Change only the keys you settled. Where the file has a key's example commented out, uncomment that line and set it; keep every other line and comment as it is
 - A project whose parts are on different stacks keeps each stack's scripts in its own `config.turri.<stack>.yaml` beside it; what the stacks share stays in `config.turri.yaml`
 - A project with only a `config.yaml` has it copied to `config.turri.yaml` first, and each `config.<name>.yaml` to `config.turri.<name>.yaml`; `config.yaml` may be another tool's, and is never written
@@ -38,13 +39,13 @@ Follow `module-structure.md`, `import-modules.md` and `linked-resources.md` for
 
 ## Generated output is read-only
 
-Everything under `plain_modules/` is generated - `code/` and `tests/` alike. Read it, run it, debug it; never edit it. Fix the spec instead, in the section that owns the fact:
+Everything under `plain_modules/` is generated - `code/` and `tests/` alike. Read it, run it, debug it; never edit it. Fix the ***plain instead, in the section that owns the fact:
 
 - behaviour, implementation or unit-test guidance → definitions, functional specs, or implementation reqs
-- conformance-test guidance → test reqs
-- acceptance-test guidance → the acceptance tests nested under their functional spec
+- how conformance and acceptance tests are written and run → test reqs
+- what a conformance or acceptance test checks → the scenarios in its functional spec's test plain file (`test-plain-files.md`)
 
-Then render again.
+Then regenerate.
 
 ## Template inclusion with parameters
 
@@ -56,12 +57,12 @@ Besides frontmatter `import`, a template can be included with parameters:
 
 Parameters are key-value pairs; the template reads them as `{{ variable_name }}`. Templates live in `template/`. One is worth writing only for text more than one `.plain` file repeats, differing only in values the parameters carry; text used once stays inline.
 
-## When an earlier test fails after a render
+## When an earlier test fails after a regeneration
 
-Each functional spec is written knowing the ones before it and none after it - a required module's specs count as before - so a spec may rely on what earlier ones say, never on later ones. This is about what a spec may assume, not what a change costs (`turri-regeneration.md`). After each render every conformance test so far runs again. A test that passed before and fails now means one of:
+Each functional spec is written knowing the ones before it and none after it - a required module's functional specs count as before - so a functional spec may rely on what earlier ones say, never on later ones. This is about what a functional spec may assume, not what a change costs (`turri-regeneration.md`). After each regeneration every conformance test so far runs again. A test that passed before and fails now means one of:
 
-1. the new code does not satisfy its spec;
-2. the test does not test its spec accurately;
-3. the new spec and an earlier one conflict.
+1. the new code does not satisfy its functional spec;
+2. the test does not test its scenario accurately;
+3. the new functional spec and an earlier one conflict.
 
-The harness triages the first two and repairs the code. The third is a spec problem: resolve it in the `.plain` files with `resolve-spec-conflict`, and trace a misbehaving build back to its spec with `debug-specs` - never by editing generated output.
+turri triages the first two and repairs the code. The third is a problem in the ***plain: resolve it in the `.plain` files with `resolve-spec-conflict`, and trace a misbehaving build back to its ***plain with `debug-specs` - never by editing generated output.

package/genome/rules/required-concepts.md

@@ -17,7 +17,7 @@ When adding or editing `required_concepts` in a `.plain` file's frontmatter, alw
 
 ## Importing module must satisfy the contract
 - Every concept listed in `required_concepts` must be defined somewhere visible to the importing module — in its own `***definitions***` section or in another module it imports
-- If the importing module does not define a required concept, the spec is invalid
+- If the importing module does not define a required concept, the module is invalid
 - Check `required_concepts` of all imported modules before finalizing a module
 
 ## Do not define required concepts locally

package/genome/rules/requires-modules.md

@@ -13,6 +13,7 @@ When creating or editing a `.plain` file that uses `requires`, or one that is re
 - The `***functional specs***` of the required module **and of all its ancestors** become visible as **previous functional specs** — this visibility **is transitive** down the whole chain
 - Of a required module's definitions, only the concepts listed in its `exported_concepts` are visible; the module's other definitions stay internal. Each exported concept arrives with its full definition text
 - Export visibility **is not transitive**: an ancestor's exports are visible only if that ancestor is itself listed in `requires`
+- The test plain files of a required module stay with that module; the current module never holds scenarios for a required module's functional spec (see `test-plain-files.md`)
 
 ## Chain topology
 
@@ -24,7 +25,7 @@ When creating or editing a `.plain` file that uses `requires`, or one that is re
 
 ## Tech stack must match (hard rule)
 
-- Because the required module's generated code is copied as the starting point and the renderer continues building on top of it with a single toolchain, two modules can only be linked with `requires` when they target the **same language, framework, and runtime**
+- Because the required module's generated code is copied as the starting point and the coding agent continues building on top of it with a single toolchain, two modules can only be linked with `requires` when they target the **same language, framework, and runtime**
 - A runtime / network dependency between systems is **not** a reason to use `requires`
 - Example of the mistake: a React frontend that talks to a Python/FastAPI backend over HTTP must **not** `requires: [backend]` — the stacks differ
 - Model that pair as two independent root modules (each with its own test scripts) and express the contract through a shared API schema in `resources/` or shared concepts in an `import`ed module — never through `requires`
@@ -33,12 +34,12 @@ When creating or editing a `.plain` file that uses `requires`, or one that is re
 
 - The current module does not need to functionally extend the required module — it may address a completely different concern
 - Even so, the two are never independent artifacts: the current module's output physically contains the required module's code, because both are stages of one accumulating codebase
-- Use `requires` to place a module at the right point in that lineage, whether or not it builds on the required module's functionality
+- Use `requires` to place a module at the right point in that lineage, whether or not it builds on the required module's functional specs
 
 ## Conflict prevention
 
-- The current module's functional specs must not conflict with the specs of **any module in its ancestor chain** — all of them are previous functional specs
-- The renderer sees the whole chain's specs as prior requirements/context when rendering the current module
+- The current module's functional specs must not conflict with the functional specs of **any module in its ancestor chain** — all of them are previous functional specs
+- The coding agent sees the whole chain's functional specs as prior requirements/context when regenerating the current module
 - Review the ancestor chain's functional specs before adding new ones
 
 ## Exports are the only visible definitions
@@ -51,7 +52,7 @@ When creating or editing a `.plain` file that uses `requires`, or one that is re
 
 ## File locations
 
-- Modules that use `requires` live at the **repository root** — they are functional modules with specs
+- Modules that use `requires` live at the **repository root** — they are functional modules with functional specs
 - `requires` paths point to other root-level modules (e.g., `auth`, `messaging`)
 - Never `require` an import module — import modules are for `import` only
 

package/genome/rules/semantic-ids.md

@@ -0,0 +1,49 @@
+---
+description: Syntax, uniqueness and use of func-ids and scenario-ids in .plain files
+---
+
+# Rules for func-ids and scenario-ids
+
+Every functional spec in `***functional specs***` and every scenario in a test plain file carries an id: its name, given by the author and never by its position. turri knows a functional spec by its func-id - in the code record, in its pulses, in the conformance tests' labels and in what it tells the person - and a scenario by its scenario-id. Always follow these rules when writing or reading one.
+
+## Two kinds of id
+
+| id | Written as | Names | Unique within |
+|---|---|---|---|
+| func-id | a `# <func-id>` heading in `***functional specs***` of a module | one functional spec | its module |
+| scenario-id | a `# <scenario-id>` heading in `***conformance tests***` or `***acceptance tests***` of a test plain file | one scenario | its functional spec, across every test plain file bound to it |
+
+## Syntax
+- Lowercase letters, digits and hyphens only: `add-task`, `export-csv-2`, `ctrl-d-exit`
+- The heading is `# ` (a hash and one space) followed by the id and nothing else
+- Make the id short kebab-case from what the functional spec or scenario means (`add-task`, never `spec-3`)
+
+## Uniqueness
+- A func-id is unique in its module; two modules may use the same func-id
+- A scenario-id is unique among its functional spec's scenarios, once every test plain file bound to it is merged; two functional specs may use the same scenario-id
+- Before adding an id, search the module (or the functional spec's test plain files) for the same heading; a duplicate is an error `turri parse` reports
+
+## Stability
+- An id is an identity, not a label: a functional spec keeps its func-id for as long as it exists, even when its text changes
+- A pure rename is cheap: a func-id renamed with nothing else changed - its body, its links and its scenarios as they were, only the `# <func-id>` heading and `func_id:` in its test plain files - is renamed by turri in its records and its tests' labels, and nothing is regenerated. The same holds for a scenario-id renamed with its text as it was
+- A rename together with any other change rebuilds: to turri it is one functional spec taken out and another added, its code built anew and its tests written anew (`turri-regeneration.md`). So rename in a ***plain diff of its own, never in the same edit as a change to the body or the scenarios
+- Rename only when the person asks, then rename `func_id:` in every test plain file bound to it, and the file with it
+- Never renumber or reorder ids: the order of the headings in the module is the order of its functional specs, and the id carries no order
+
+## Naming a functional spec
+- Name a functional spec by its func-id - `<module>:<func-id>` outside its module (`todo:add-task`) - in questions to the person, in what you show them and in turri's tools; never by its position ("the third functional spec")
+- Pick the func-id before writing the functional spec, check that it is unique in the module, then write the heading and the body (see `func-specs.md`)
+- Everything about one functional spec is found through its func-id: its heading, the test plain files whose frontmatter names it, and the conformance tests labelled with it
+- A conformance or acceptance test carries the scenario-id of the scenario it implements: when one fails, its label leads back to the scenario
+
+## Format
+
+```plain
+***functional specs***
+
+# add-task
+A :User: can add a :Task:. Only valid :Task: items are added.
+
+# delete-task
+A :User: can delete a :Task:.
+```

package/genome/rules/stdlib.md

@@ -10,7 +10,6 @@ turri ships a standard library of import modules that settle everything about a
 ---
 import:
   - stdlib/backend/python-flask
-  - stdlib/backend/conformance/python-flask
 ---
 ```
 
@@ -24,15 +23,15 @@ import:
 
 - When the person wants a backend, a frontend, a command-line tool or a library, import the stack that fits instead of writing its implementation reqs yourself.
 - Pick the stack from what the person said, the project's other modules, and what the module talks to. With nothing to go on: `stdlib/backend/python-fastapi`, `stdlib/frontend/react-vite`, `stdlib/cli/python-typer`, `stdlib/library/python`.
-- Import the conformance template only when the module has conformance tests - the person asked for them, and the project's config does not turn them off (`conformance-tests: false`). Without it the module has no test reqs, and no conformance tests are written or run for it. Turning them on later is adding that one import.
-- Read the templates a module imports before writing its specs - the folder is named below - and write no requirement they already make (see `concise-specs.md`).
+- Import the stack alone. Nothing about testing exists until the person asks for it: the first time they ask for tests in a module, import the stack's conformance template, `stdlib/<kind>/conformance/<stack>` - the module's test reqs - then write the conformance testing script if the project has none for the stack, then the scenarios, in that order (*Writing scenarios* in `test-plain-files.md`).
+- Read the templates a module imports before writing its ***plain - the folder is named below - and write no requirement they already make (see `concise-specs.md`).
 - Write a functional spec's errors in the templates' terms: a backend's failure by its status and `error.code` - `not_found`, `conflict`, `validation_error`, `unauthenticated`, `forbidden`, or a code of the module's own - and a command-line tool's by its exit code and message.
 - Add a requirement on top for what the module needs beyond its stack - storage, an outside service, a library it must use. When the module differs from its stack on something the stack settles - another framework, another layout - write the stack yourself instead: an import cannot be taken back in part. For a language with no stack of the kind wanted, import its `stdlib/lang/<language>` and write the rest.
-- `stdlib/` is a reserved name. An import that starts with it is always the standard library's template, and a project module at such a path - `stdlib/backend/python-fastapi.plain` in the spec's folder, its `template/` folder or `PLAIN_TEMPLATE_DIRS` - is an error. Never write a module under a `stdlib/` folder of the project; a project's own shared template goes in `template/` under a name of its own.
+- `stdlib/` is a reserved name. An import that starts with it is always the standard library's template, and a project module at such a path - `stdlib/backend/python-fastapi.plain` in the module's folder, its `template/` folder or `PLAIN_TEMPLATE_DIRS` - is an error. Never write a module under a `stdlib/` folder of the project; a project's own shared template goes in `template/` under a name of its own.
 
 ## What it does not do
 
 - It defines no concepts: its requirements are on the predefined `:Implementation:`, `:UnitTests:` and `:ConformanceTests:` only, so it never collides with the module's own definitions.
 - It holds no storage: a module with a database says which, and how it is reached, on top.
-- It holds no testing scripts. The module still needs its unit testing script, and its conformance testing script when it has conformance tests - written with the `implement-unit-testing-script` and `implement-conformance-testing-script` skills for the stack's language and test framework. Each runs the static checks of what it tests - the formatter, linter and type checker its language template names, on the code or on the conformance tests - and they count as the tests do.
+- It holds no testing scripts. The module still needs its unit testing script, written with the `implement-unit-testing-script` skill for the stack's language and test framework; its conformance testing script is written with `implement-conformance-testing-script` when its first tests are asked for. Each runs the static checks of what it tests - the formatter, linter and type checker its language template names, on the code or on the conformance tests - and they count as the tests do.
 - It names its stack's toolchain - Python 3.12, Node.js 24, Java 21, Go 1.25, Rust - which the agents use from the machine turri runs on; they install none, so `turri doctor` says when the machine lacks it.

package/genome/rules/test-plain-files.md

@@ -0,0 +1,130 @@
+---
+description: Test plain files - where they live, their two sections, their scenarios, keeping them in step with the functional specs, and writing scenarios when the person asks for tests
+---
+
+# Rules for test plain files
+
+A test plain file holds the test scenarios of one functional spec. Conformance scenarios test its expected use; acceptance scenarios, the use that is not expected. The conformance agent writes the conformance and acceptance tests from these scenarios and from nothing else: each scenario becomes at least one test that does what it says, and it invents none. A functional spec whose test plain file is empty is not tested. Always follow these rules when creating or editing one.
+
+## Where it lives
+- Every test plain file of a module lives in `tests/<module>/`, with `tests/` beside the module (`test-dir:` in `config.turri.yaml` can name another folder). This is a rule, not a convention: a file's folder matches its `module:`, and a `.plain` file in `tests/` outside a module's folder is an error `turri parse` reports
+- Name the file after its functional spec, `tests/<module>/<func-id>.plain`; the name is convention, the frontmatter is what binds it
+- A functional spec with no scenarios has no test plain file: it is not tested. Write one only to give a functional spec scenarios, and never an empty one - an empty file is a syntax error, as an empty section is
+- When turri's test advisor's yes arrives for a functional spec, you add its test plain file, with the test reqs and conformance testing script it needs (see `turri-regeneration.md`) - as below, asking nothing
+- More than one test plain file may bind to one functional spec: their scenarios are merged, and the scenario-ids must be unique across them. Write one file per functional spec, and keep a person's extra files as they are
+- A test plain file is never a module: never import or require one, and never name one where a module is asked for
+
+## File skeleton
+- YAML frontmatter, then `***conformance tests***`, then `***acceptance tests***`, each section heading at the start of a line
+- A section is there only with at least one scenario under it: a section with none is a syntax error - leave it out. A file with no section at all is one too: a functional spec with no scenarios has no test plain file
+- The frontmatter has exactly two keys, both required:
+  - `module:` - the module the functional spec is in: its file name without `.plain`
+  - `func_id:` - the functional spec's func-id (see `semantic-ids.md`)
+- The two must name a functional spec that exists
+- No other section: no `***definitions***`, `***implementation reqs***`, `***test reqs***` or `***functional specs***`
+- Comment lines starting with `>` are allowed, as in a module
+
+The minimum - one scenario, its section alone:
+
+```plain
+---
+module: todo
+func_id: add-task
+---
+
+***conformance tests***
+
+# add-valid-task
+Adding a :Task: named "Buy milk" to an empty :TaskList: shows one :Task: named "Buy milk".
+```
+
+## Scenarios
+- A scenario is a `# <scenario-id>` heading (see `semantic-ids.md`) followed by free text that says what is done and what result is expected
+- No line of its body starts with `# ` (that starts the next scenario) or with `***`
+- A scenario may use every concept its module sees: its own definitions, its `import` modules' and the `exported_concepts` of its `requires` modules. It defines none
+- Scenarios are language-agnostic and black box: they act through the interface the functional spec names - a command line, HTTP, files, a UI - and never name a function, class or file of the code
+- A scenario is a direct consequence of its functional spec: it does not contradict, narrow or extend it
+- Each scenario states one concrete, checkable outcome; "works correctly" is not an outcome
+- Values that matter to the check are concrete (`named "Buy milk"`, `exits with status 0`), never descriptive (`a valid name`)
+- Scenario text follows `concise-specs.md`: no narration, no rationale, no step a reader would assume
+- `***conformance tests***` holds the expected use: the main path, with valid input, the expected caller and the data present
+- `***acceptance tests***` holds the use that is not expected: invalid input, wrong or missing authentication, missing data, a dependency that fails
+- The kind of use decides the section, not how many functional specs a scenario touches
+
+## Scenarios across functional specs
+- A scenario may use functional specs written before the one it is bound to, for its setup or as steps of a longer path
+- It is bound to the last functional spec it exercises, since the earlier ones exist when it runs
+- It goes under `***conformance tests***` when every step is expected use, and under `***acceptance tests***` when any step is not; write one only when the person asks for it
+
+## Keeping test plain files in step
+Only scenarios that exist are kept in step: a change to a functional spec never calls for new ones. In the same ***plain diff as the change:
+- A new functional spec gets no test plain file, unless the person asks for its tests
+- A functional spec whose body changes has its scenarios, if it has any, reviewed: one that no longer follows from it is changed or taken out, and your reply says so
+- The last scenario of a section taken out: the section is taken out with it. The last scenario of the file: the file is deleted
+- A functional spec split into several: each part gets its own test plain file, and each scenario moves to the part it tests
+- A functional spec taken out: its test plain file, if it has one, is deleted
+- A functional spec moved to another module: its test plain file moves to that module's folder, with `module:` changed
+- A func-id renamed: `func_id:` is renamed in every test plain file bound to it, and the file with it
+
+## Writing scenarios
+Nothing about testing exists until the person asks for it, or the test advisor's yes arrives: a module imports no conformance template, and its functional specs have no test plain files. The first time the person asks for tests in a module, or the advisor's yes arrives for one of its functional specs, do three things, in this order, each a visible change - only what is missing:
+1. **Test reqs:** import the stack's conformance template, `stdlib/<kind>/conformance/<stack>` (see `stdlib.md`), or write the module's own `***test reqs***` when it has no stack from the standard library (see `test-reqs.md`)
+2. **The conformance testing script:** write it with `implement-conformance-testing-script`, if the project has none for the module's stack
+3. **The scenarios**, as below
+
+Then, and for every later request:
+- Decide in prose which scenarios each functional spec named needs, then write them with `change_plain`, conformance and acceptance in one change where both were asked for. Ask for no further confirmation: the change is visible, and turri starts the conformance pulses itself
+- Write scenarios only for the functional specs the person named. Scenarios in one functional spec imply nothing about another, in the same module or not: the person may test one thoroughly and leave the rest untested
+- Write acceptance scenarios only when the person asks for them
+- On the test advisor's yes, the functional spec it names is named, and its report says what to cover: each input that is this functional spec's, an agreed one with the readers' output and never a placeholder, a split one by the reading most consistent with the functional spec and its module - say which you took. Leave out an input it does not settle rather than ask; ask the person nothing
+- One conformance scenario per expected use the functional spec states: its main path first, then each valid variant it names - another input shape, an optional parameter. Stop when each has one, and never write the same outcome twice in different words
+- Write no outcome the functional spec does not state. When a needed one is missing, ask the person, and put the answer in the functional spec first
+- A scenario that needs a dependency to fail - a backend that does not answer, a database that is down - is written only when the test reqs let a test cause that failure, with a local mock of it, say; otherwise ask the person whether to add such a test req or leave the scenario out
+- The body is one statement line naming the action and its expected result, with concrete values; when that is not enough, `- ` bullets under it, in order: the state before, the one action under test, then each observable result, one fact a bullet
+- A framework, a run command or a network policy belongs in `***test reqs***`, never in a scenario
+
+```plain
+Functional spec:
+# list-resources
+:Resource: items are returned sorted by creation date in descending order.
+
+Good - follows from the functional spec:
+# newest-first
+After three :Resource: items are created one after another, listing them returns the last one created first.
+
+Bad - contradicts it (the functional spec says descending):
+# oldest-first
+The first :Resource: listed is the oldest.
+
+Bad - extends it (the functional spec says nothing about a limit):
+# at-most-fifty
+At most 50 :Resource: items are listed.
+```
+
+The conformance agent writes exactly the scenarios: each one becomes at least one test, labelled with its scenario-id, and no test is written from the functional spec itself or invented beside them.
+
+## Relation to `***test reqs***`
+- The module's `***test reqs***` - its own, or a conformance template's - say how `:ConformanceTests:` and `:AcceptanceTests:` are written and run: framework, command, network policy. The scenarios say what they check
+- Test reqs and scenarios reach the conformance agent only, never the coding agent
+- A fact about the framework or the run command never goes into a scenario, and a scenario never goes into `***test reqs***`
+
+## Format
+
+```plain
+---
+module: todo
+func_id: add-task
+---
+
+***conformance tests***
+
+# add-valid-task
+Adding a :Task: named "Buy milk" to an empty :TaskList: shows one :Task: named "Buy milk".
+
+***acceptance tests***
+
+# reject-short-name
+Adding a :Task: named "Go" to an empty :TaskList: is rejected.
+- :App: shows the error "Name must be at least 3 characters".
+- :TaskList: stays empty.
+```

package/genome/rules/test-reqs.md

@@ -9,15 +9,15 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 ## Conformance tests only
 - Test reqs specify how **conformance tests** should be written and run
 - Unit test guidance goes in `***implementation reqs***`, not here
-- Acceptance tests are nested under individual functional specs, not here
+- Test scenarios, conformance and acceptance, live in test plain files, not here - see `test-plain-files.md`
 - Behavioral requirements go in `***functional specs***`, not here
 
 ## `:ConformanceTests:` lives here (hard rule)
 - **Everything** about `:ConformanceTests:` goes in `***test reqs***` — paths, approach, packages, framework, execution command, mocking / network policy, fixtures, pass criteria, environment prerequisites
 - `:ConformanceTests:` live outside the generated codebase, in one folder, `plain_modules/<module>/tests/` - the module's whole conformance suite, so requirements that shape them belong in test reqs by definition
-- The conformance-test generator reads **only** `***test reqs***` — anything about `:ConformanceTests:` placed elsewhere (e.g. `***implementation reqs***`) is silently ignored
+- The conformance agent reads how to write and run the tests **only** from `***test reqs***` — anything about `:ConformanceTests:` placed elsewhere (e.g. `***implementation reqs***`) is silently ignored
 - Phrase each `:ConformanceTests:` requirement in terms of `:ConformanceTests:` so the partition stays visible at a glance
-- Do not link the conformance testing script here (or anywhere in the specs; a link to it is ignored). turri finds it in the project root - `conformance-tests-script:` in `config.turri.yaml`, else the one `run_conformance_tests*.sh` in the root, else the one in `test_scripts/` - and shows it to the agents that write the conformance tests itself. Describe the framework and execution command here in words
+- Do not link the conformance testing script here (or anywhere in the ***plain; a link to it is ignored). turri finds it in the project root - `conformance-tests-script:` in `config.turri.yaml`, else the one `run_conformance_tests*.sh` in the root, else the one in `test_scripts/` - and shows it to the agents that write the conformance tests itself. Describe the framework and execution command here in words
 
 ## What belongs here
 - Test framework: which framework to use (e.g., pytest, Unittest, xUnit)
@@ -28,11 +28,11 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 
 ## Test type reference
 
-| Test type | Where to specify | Generated | Purpose |
-|-----------|-----------------|-----------|---------|
-| Unit tests | `***implementation reqs***` | Automatically | Test individual functionalities in isolation |
-| Conformance tests | `***test reqs***` | Automatically | Verify each functionality's implementation against its functional spec |
-| Acceptance tests | `***acceptance tests***` under a functional spec | Manually | Verify implementation of a functional spec through a specific end-to-end scenario |
+| Test type | Where to specify | Written from | Purpose |
+|-----------|-----------------|--------------|---------|
+| Unit tests | `***implementation reqs***` | the functional specs, by the coding agent with the code | Test each functional spec's code in isolation |
+| Conformance tests | how: `***test reqs***`; what: `***conformance tests***` of the functional spec's test plain file | exactly its conformance scenarios, by the conformance agent - at least one test each, none invented | Verify the expected use of one functional spec, its main path |
+| Acceptance tests | how: `***test reqs***`; what: `***acceptance tests***` of the functional spec's test plain file | exactly its acceptance scenarios, the same way | Verify one functional spec under use that is not expected: invalid input, wrong or missing authentication, missing data |
 
 ## No duplication
 - Do not duplicate guidance already present in the file or its imports

package/genome/rules/turri-regeneration.md

@@ -10,33 +10,48 @@ The other rules say what a spec means. This one says what turri does with a chan
 
 - turri regenerates the code from spec diffs: what changed between the spec the code was built from and the spec now
 - A functional spec added, changed or taken out is that change alone, wherever it sits - first, in the middle or last of its module
-- The specs around it are not regenerated because their position or numbering moved, and nothing after it is built again. A spec inserted in the middle is one addition
+- A functional spec is known by its module and its func-id, `<module>:<func-id>`: the specs around it are not regenerated because their position moved, and nothing after it is built again. A spec inserted in the middle is one addition; one moved to another place with its text as it was is no change at all
+- A func-id renamed, and nothing else with it, regenerates nothing: turri renames it in its records and relabels its tests itself. Renamed together with any other change - its text, a scenario - it is a functional spec taken out and another added: its code is removed and built anew. Keep a func-id once it is built, and change the text under it
+- Code built before functional specs had func-ids is never built on: its whole chain is regenerated from scratch, never done without the person agreeing
 - "Specs render top to bottom, each knowing only the ones before it" is about what a spec may assume (`func-specs.md`), not about what a change costs
 
 ## A change is regenerated in the chain's tip
 
 - A chain's code lives in its tip - the furthest module built on it. The modules below it keep the code they were built with
 - A change to any module of the chain, the base's included, is regenerated in the tip's code - not in the module the change was made in
+- A functional spec of a module below is added, patched or taken out in the tip just as the tip's own are, named `<module>:<func-id>`. Its conformance tests are in the tip's suite too, and are kept up to date there
 - Putting a change in a lower module costs no more than putting it in the tip, and saves nothing either
-- Moving specs between modules of the chain renders nothing. Moving specs into a module the code was never built on is the exception: no change to the code brings that module in, so the chain has to be regenerated from scratch - never done without the person agreeing
+- Moving specs between modules of the chain regenerates nothing. Moving specs into a module the code was never built on is the exception: no change to the code brings that module in, so the chain has to be regenerated from scratch - never done without the person agreeing
 
 ## What each kind of change sets off
 
 - A functional spec added is built, with its unit tests; one changed is patched in place; one taken out has its code, and the tests only it had, removed
-- A definition changed patches every functional spec that uses its concept, directly or through other definitions. So does a change to a linked resource: the spec or definition linking it is changed though its text is not. A widely used definition is the costly edit - not a spec's position
-- Implementation reqs alone, or definitions no functional spec uses, are a mechanical change: the code adapts, and no test is written or changes what it asserts
-- Test reqs and acceptance tests reach the conformance tests only, never the code
+- A definition changed patches every functional spec of the chain that uses its concept, directly or through other definitions - a module below's as well as the tip's own. So does a change to a linked resource: the spec or definition linking it is changed though its text is not. A widely used definition is the costly edit - not a spec's position
+- Implementation reqs alone, or definitions no functional spec of the chain uses, are a mechanical change: the code adapts, and no test is written or changes what it asserts
+- Test reqs and scenarios - a functional spec's conformance and acceptance scenarios, in its test plain file - reach the conformance tests only, never the code. A scenario changed alone regenerates no code
 - A functional spec regenerated again by name has its code taken out and built anew - never left as it was, even where it already does what the spec says; a pulse that changes nothing does not land. Its conformance tests, when it has them, are run on its new code once it lands: those that pass are kept as they are; one that fails is judged against the spec - what it checks that the spec leaves open, a path, a field, a message the old code chose, goes by the new code
-- `conformance-tests: false` writes no new conformance tests, but keeps those there are up to date: a functional spec that has conformance tests and is changed, regenerated again or taken out gets a conformance pulse for it alone once its code lands. One with none gets none
-- Definitions moved to a common module and reqs reordered are recorded, not rendered
+- What is conformance tested is the scenarios: each conformance and acceptance scenario of a functional spec gets at least one test, and nothing else is tested - a functional spec with no test plain file, or an empty one, has no conformance tests. Its tests are written or changed once its code lands, whenever a scenario is added, changed or taken out, its text changes, it is regenerated again or taken out; one whose scenarios are all taken out loses its tests. It goes scenario by scenario, by scenario-id: a scenario added gets its tests, one changed has them rewritten, one taken out loses them, and an unchanged one keeps them - run on the new code when the functional spec's code changed. A scenario-id renamed with its text as it was has its tests relabelled, nothing rewritten; renamed with any other change, or moved between conformance and acceptance, it is one taken out and one added. To have something checked end to end, write it as a scenario
+- Scenarios are tested only once the module has test reqs - its own, or the stack's conformance template imported - and the project has a conformance testing script for its stack. For a module another requires, that is the tip of the chain: its conformance tests are written there, from the tip's test reqs, so the template goes into the tip. Without either, turri starts no conformance pulse there, by itself or from `conform`: it refuses, naming the step missing, the module waits on it until the `.plain` files or the scripts change, and `turri parse` warns. Take the steps in order - test reqs, the script, then the scenarios - and a module with no scenarios needs neither
+- Definitions moved to a common module and reqs reordered are recorded, not regenerated
 - A functional spec written on its happy path and hardened later - its validation, edge cases and errors added to it - is patched in place each time: growing a spec a step at a time costs no more than writing it whole up front
 - A module's first pulse, when it builds one functional spec - the project set up and the smallest thing that runs - lands on its unit tests with no review
 
+## The test advisor
+
+- Conformance tests are the project's choice: `conformance-tests:` in config.turri.yaml, off when unset. Off, no scenarios are tested and the test advisor is off - write no test plain file, test reqs or conformance testing script unless the person asks for tests; their asking, or their yes when the chat offers them, turns them on first
+- In the chat and a host, turri's test advisor looks at each functional spec that is new, or whose text changed since its code was built, and that has no scenarios - in the background, beside the pulses, taking no slot of theirs and never stopping one. It asks whether a wrong implementation could give output that looks right, whether two reasonable readings give different outputs for some input, whether it is likely to be built on later, and whether a bug in it would be costly. A yes to the first, the second or the last, with evidence, means the functional spec needs testing; built on later alone does not
+- It writes nothing in the ***plain: you are its only writer. A functional spec with scenarios of any kind is not looked at by it; its scenarios go through the usual review when its text changes
+- A change's result names the functional specs the advisor is checking: tell the person in a line that testing scenarios are being evaluated for them, and go on
+- Its yes comes to you as a message, once the chat is idle, with its report: tell the person in a line, then write with `change_plain` what testing the functional spec needs - its test reqs, the conformance testing script, its scenarios, in that order and only what is missing - the script written in the background, so you go straight on to the scenarios - as the rules on test plain files say, asking the person nothing. Its no is a line turri draws: nothing for you to do
+- `evaluate_tests` asks the advisor yourself, for functional specs you name with why, even a text it judged already: it returns at once, and the verdict comes back the same way. Call it when the person asks whether a functional spec needs tests, and on your own as another way of expressing intent - when pulses keep failing on a complicated functional spec, scenarios may pin down what it should do. A functional spec with scenarios is not evaluated
+- When the person asks for scenarios, write them yourself, as the rules on test plain files say. `test-advisor: false` turns off only what a change starts, never `evaluate_tests`; the advisor never runs in a headless run
+
 ## What a coding agent sees
 
-- A coding agent sees its prompt and its module's code - nothing else. It cannot read `.plain` files, this conversation, AGENTS.md or the person
+- A coding agent sees its prompt and its module's code - nothing else. It cannot read `.plain` files, this conversation, AGENTS.md or the person. It never sees a functional spec's scenarios: those are the conformance tests'
 - What the code needs to know has to be in the spec. A fact said only in the conversation, AGENTS.md or notes never reaches the code, and is lost at the next regeneration
 - Steering reaches the agents that plan the work - how it is cut and in what order - not what the code does. What the code does is changed in the spec
+- A codebase that requires no module may start from a base folder (`base-folder:` in config.turri.yaml): an existing codebase, files to use - images, animations - or both, copied in once before its first pulse and up the chain with the code. The agents that change and review its code are told what came from it, and keep it unless a functional spec asks otherwise. Refer to what is in it in the spec - in words, or by a link into the folder, relative to the module's file as every link is - for the code to use it: a file it holds that no functional spec names is kept, never used. A change to the folder later reaches the code only when the module is regenerated from scratch
 
 ## How bad code is fixed
 

package/genome/skills/analyze-2-func-specs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: analyze-2-func-specs
 description: >-
-  Analyze two functional specs from a ***plain spec file to determine if they
+  Analyze two functional specs from a .plain file to determine if they
   conflict. Use when the user wants to check whether two specific functional
   requirements are compatible, or when debugging a suspected conflict between
   two specs.
@@ -12,26 +12,29 @@ allowed-tools: [read, ls, grep, find]
 
 ## Input
 
-Two functional specs from a `.plain` file (or across `requires` modules). The user provides them directly or points to them by location in a file.
+Two functional specs from a `.plain` file (or across `requires` modules). The user provides them directly or names them by func-id - `<module>:<func-id>` across modules. Name each by its func-id while you work; a draft that has none yet is Spec A or Spec B.
 
 ## Workflow
 
 1. **Read both functional specs** and the `***definitions***` section so all referenced `:Concepts:` are understood.
-2. **Determine chronological order** — which spec comes first? The earlier spec was rendered first and the later spec was rendered with the earlier one in context.
+2. **Determine chronological order** — which functional spec comes first? The earlier one was regenerated first and the later one was regenerated with the earlier one in context.
 3. **Run the conflict analysis** using the checklist below.
 4. **Output the verdict and nothing else** — either `COMPATIBLE` or `CONFLICTING`. No reasoning, no category labels, no resolution suggestions.
 
 ## Conflict Analysis Checklist
 
-Work through each question. If any answer is "yes", the specs likely conflict.
+Work through each question. If any answer is "yes", the functional specs likely conflict.
 
 ### 1. Direct Contradiction
 
-Do the two specs make mutually exclusive assertions about the same behavior?
+Do the two functional specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: :Resource: items are returned sorted by name in ascending order.
-Spec B: :Resource: items are returned sorted by creation date in descending order.
+# sort-by-name
+:Resource: items are returned sorted by name in ascending order.
+
+# sort-by-date
+:Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -40,34 +43,43 @@ satisfy both unless scoped to different contexts.
 
 ### 2. State or Data Conflict
 
-Does one spec set a state or value that the other spec assumes is different?
+Does one functional spec set a state or value that the other assumes is different?
 
 ```
-Spec A: :TaskList: is initially empty.
-Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
+# empty-task-list
+:TaskList: is initially empty.
+
+# welcome-task
+:TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
 
 ### 3. Behavioral Override
 
-Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
+Does the later functional spec silently replace behavior established by the earlier one without acknowledging it?
 
 ```
-Spec A: :User: credentials are validated using an API key.
-Spec B: :User: credentials are validated using OAuth 2.0.
+# api-key-auth
+:User: credentials are validated using an API key.
+
+# oauth-auth
+:User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
-different approaches. The later spec overrides the earlier one.
+different approaches. The later one overrides the earlier one.
 ```
 
 ### 4. Scope Ambiguity
 
-Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
+Are the two functional specs ambiguous enough that a coding agent could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: All :Resource: items are returned.
-Spec B: Only active :Resource: items are returned.
+# list-resources
+All :Resource: items are returned.
+
+# list-active-resources
+Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -75,13 +87,16 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 
 ### 5. Shared Concept, Different Constraints
 
-Do both specs impose constraints on the same `:Concept:` that cannot coexist?
+Do both functional specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: is 100 items.
-Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
+# default-batch-size
+:BatchSize: is 100 items.
+
+# attachment-batch-size
+:BatchSize: is 50 items for :Resource: types with attachments.
 
-Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+Verdict: COMPATIBLE — attachment-batch-size adds a conditional refinement, not a contradiction.
 ```
 
 ## Output Format