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

package/genome/rules/concise-specs.md

@@ -1,16 +1,16 @@
 ---
-description: Conciseness and plain-language rules that keep .plain specs reviewable by a human
+description: Conciseness and plain-language rules that keep ***plain reviewable by a human
 ---
 
-# Rules for keeping `.plain` specs concise
+# Rules for keeping `.plain` files concise
 
-These rules apply to every section, to concept explanations, and to acceptance tests. `concise-specs-examples.md` holds a worked BAD to GOOD pair for each failure mode named here, and `concise-specs-integration-examples.md` covers the failure modes specific to integration specs.
+These rules apply to every section, to concept explanations, and to scenarios in test plain files. `concise-specs-examples.md` holds a worked BAD to GOOD pair for each failure mode named here, and `concise-specs-integration-examples.md` covers the failure modes specific to integration specs.
 
 ## Why this matters
 
-- A spec is the source of truth, so a human has to be able to review it
-- A long, dense, or ornate spec is skipped rather than reviewed — an unreviewed spec is an unverified spec, however correct it happens to be
-- Length is not a proxy for rigor: a spec earns trust by being checkable, not by being thorough-looking
+- ***plain is the source of truth, so a human has to be able to review it
+- Long, dense, or ornate ***plain is skipped rather than reviewed — unreviewed ***plain is unverified ***plain, however correct it happens to be
+- Length is not a proxy for rigor: ***plain earns trust by being checkable, not by being thorough-looking
 - Conciseness is about removing what carries no information, never about removing required detail — the deterministic-interface, disambiguation, and testability rules always win (see `func-specs.md`)
 
 ## Do not write the obvious
@@ -21,11 +21,11 @@ Do not write:
 
 - Restatements of a concept's own name (`:UserEmail: is the email address of a :User:.` adds nothing beyond what `definitions.md` already requires the concept to carry)
 - Universal software defaults: that invalid input is rejected, that errors are reported, that data is saved when saving is the point of the operation
-- Rationale, motivation, benefits, or background — the spec states what is, not why it was chosen
+- Rationale, motivation, benefits, or background — ***plain states what is, not why it was chosen
 - Standard behavior of a technology already named in `***implementation reqs***` (an HTTP framework parses HTTP; a database driver opens connections)
 - Restatements of a nearby bullet in different words, or of anything already stated in an `import`ed or `require`d module
-- Anything about work the spec is not about ("no changes to the existing UI")
-- Meta-commentary about the spec itself ("this spec is intentionally small", "as described above")
+- Anything about work the ***plain is not about ("no changes to the existing UI")
+- Meta-commentary about the ***plain itself ("this spec is intentionally small", "as described above")
 
 Worked pairs for every item above — padding, rationale, defaults, technology behavior, meta-commentary, and duplication of an `import` — are in `concise-specs-examples.md`.
 
@@ -35,7 +35,7 @@ Worked pairs for every item above — padding, rationale, defaults, technology b
 - Write short sentences: one clause plus, at most, one qualifier
 - Use the same word for the same thing every time — synonym variety reads as two different things
 - Do not use adverbs and adjectives that no test can check: `robust`, `seamless`, `efficient`, `scalable`, `comprehensive`, `modern`, `properly`, `gracefully`, `as appropriate`, `where applicable`, `best practices`. Either state the checkable fact (`a response is returned within 200 ms`) or delete the word
-- Do not hedge: `should ideally`, `may optionally`, `typically`, `generally`, `if possible`. A spec states one behavior; a hedge tells the renderer to guess
+- Do not hedge: `should ideally`, `may optionally`, `typically`, `generally`, `if possible`. A functional spec states one behavior; a hedge tells the coding agent to guess
 
 | Do not write | Write |
 |---|---|
@@ -52,20 +52,21 @@ Worked pairs for every item above — padding, rationale, defaults, technology b
 
 ## Keep the shape small
 
+- The bullet rules here apply to `***definitions***`, `***implementation reqs***`, and `***test reqs***`; the body of a functional spec and of a scenario is free text
 - One statement per bullet, one bullet per fact (see `bullet-continuation.md`)
 - Nest a sub-bullet only to remove a real ambiguity; a sub-bullet that merely elaborates is filler
-- Consecutive specs that share a subject are usually one spec: if a top-level bullet only tells part of the story of one operation, merge the set, lead with the operation's result, and demote the steps and failure modes to sub-bullets (see *One operation fragmented into several specs* in `concise-specs-integration-examples.md`)
+- Consecutive functional specs that share a subject are usually one: if a functional spec only tells part of the story of one operation, merge the set, lead with the operation's result, and demote the steps and failure modes to detail under it (see *One operation fragmented into several functional specs* in `concise-specs-integration-examples.md`)
 - Tables, prose paragraphs, and code blocks do not belong in a section; external artifacts are linked from `resources/` (see `linked-resources.md`)
-- A bullet that answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* is not one fact — split it across the sections that own those facts, which reads better and is the only way the renderer sees each part (see `module-structure.md`, and *Split one crowded bullet across its owning sections* in `concise-specs-examples.md`)
+- A bullet that answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* is not one fact — split it across the sections that own those facts, which reads better and is the only way each part is read where it belongs (see `module-structure.md`, and *Split one crowded bullet across its owning sections* in `concise-specs-examples.md`)
 
 ## Terse is not a defect
 
-A finished spec usually reads as abrupt: clipped bullets, no connective tissue, no lead-ins. That is the intended shape, not something to smooth out afterwards.
+Finished ***plain usually reads as abrupt: clipped bullets, no connective tissue, no lead-ins. That is the intended shape, not something to smooth out afterwards.
 
 - Add a word only to make a line correct, unambiguous, or checkable — never to make it read better
 - Do not merge short bullets into one sentence for rhythm, and do not open a section or a bullet with a lead-in
-- The bar is the other rules — correct, intent intact, reviewable, testable. A spec that clears them is finished however clipped it sounds
-- Filler is not neutral: the renderer reads every line as a requirement, so a line written for flow can invent one
+- The bar is the other rules — correct, intent intact, reviewable, testable. ***plain that clears them is finished however clipped it sounds
+- Filler is not neutral: the coding agent reads every line as a requirement, so a line written for flow can invent one
 
 ## Review pass before writing to disk
 
@@ -76,4 +77,4 @@ Read the drafted lines once more and apply, in order:
 3. **The duplication test** — cut anything already stated in this file, an `import`, or a `requires` chain
 4. **The read-aloud test** — a line you cannot read aloud in one breath is either two facts or one padded one
 
-If a cut would remove an interface detail, a boundary case, or a disambiguation, keep the fact and shorten the wording instead — see *Do not over-cut* in `concise-specs-examples.md` for what a spec cut past its content looks like.
+If a cut would remove an interface detail, a boundary case, or a disambiguation, keep the fact and shorten the wording instead — see *Do not over-cut* in `concise-specs-examples.md` for what ***plain cut past its content looks like.

package/genome/rules/definitions.md

@@ -12,12 +12,12 @@ When writing or editing a `***definitions***` section in a `.plain` file, always
 - Valid characters: letters, digits, `+`, `-`, `.`, `_`
 
 ## Uniqueness
-- Concept names must be globally unique across the spec and all its imports
+- Concept names must be globally unique across the module and all its imports
 - Check for collisions with concepts coming from `import` and `requires` modules before adding
 
 ## Predefined concepts (do not redefine)
 - ***plain ships several predefined concepts that are available in every module without being defined
-- Never add a `***definitions***` entry for any of them — the renderer treats redefinitions as conflicts
+- Never add a `***definitions***` entry for any of them — turri treats redefinitions as conflicts
 
 | Predefined concept | Meaning |
 |--------------------|---------|
@@ -27,9 +27,9 @@ When writing or editing a `***definitions***` section in a `.plain` file, always
 | `:plainTestReqs:` | Content of the `***test reqs***` section |
 | `:Implementation:` | The system implementing `:plainFunctionality:` |
 | `:plainImplementationCode:` | The generated implementation code |
-| `:UnitTests:` | Auto-generated unit tests for individual functionalities |
-| `:ConformanceTests:` | Auto-generated tests verifying conformance to the spec |
-| `:AcceptanceTest:` / `:AcceptanceTests:` | Tests validating specific aspects of the implementation |
+| `:UnitTests:` | The unit tests the coding agent writes with each functional spec's code |
+| `:ConformanceTests:` | The black-box tests written from the functional specs' conformance scenarios, run by the conformance testing script |
+| `:AcceptanceTest:` / `:AcceptanceTests:` | The black-box tests written from the functional specs' acceptance scenarios, run by the conformance testing script |
 
 ## Conciseness
 - A definition is one plain sentence plus, where needed, its attributes — see `concise-specs.md`

package/genome/rules/examples/integration-embedded-testing/run_conformance_tests_java.sh

@@ -22,7 +22,7 @@ fi
 current_dir=$(pwd)
 
 # Resolve the conformance tests folder to an absolute path ($2 may be relative
-# on older renderers; newer renderers pass it as an absolute path).
+# on older harnesses; turri passes it as an absolute path).
 case "$2" in
   /*) CONFORMANCE_TESTS_SOURCE="$2" ;;
   *)  CONFORMANCE_TESTS_SOURCE="$current_dir/$2" ;;

package/genome/rules/func-specs.md

@@ -1,16 +1,22 @@
 ---
-description: Rules for writing ***functional specs*** and ***acceptance tests*** in .plain files
+description: Rules for writing ***functional specs*** in .plain files
 ---
 
 # Rules for writing `***functional specs***`
 
 When writing or editing a `***functional specs***` section in a `.plain` file, always follow these rules:
 
+## Shape
+- Each functional spec is a `# <func-id>` heading followed by its body; the func-id follows `semantic-ids.md`
+- The body is free text that describes the behaviour: its first line states it, and prose or `- ` bullets under that line add the detail
+- No body line starts with `# ` (that starts the next functional spec) or with `***`
+- A functional spec's test scenarios live in its test plain file, never in this section (see `test-plain-files.md`)
+
 ## Voice
 - Write each functional spec as a **statement of fact** — present tense, indicative mood — describing what the software *is* or *does* once built, not as a command telling a developer what to build
 - **Name a concrete subject**: an actor (`A :User: can …`), a named component or concept (`:PdfRenderer: lays out …`, `:Order: processing depends on …`), or the affected data in passive voice (`All :Resource: items are returned`)
 - **Avoid the vague subject "The system …"** — it says nothing about *which* part does the work. Prefer the concrete component/concept, or passive voice with the affected concept as the subject
-- **Never open a spec with an imperative** like "Implement …", "Add …", "Create …", "Show …", "Display …", "Build …" — those read as instructions, not specifications
+- **Never open a functional spec with an imperative** like "Implement …", "Add …", "Create …", "Show …", "Display …", "Build …" — those read as instructions, not as what the software does
 - Do **not** use "should" / "should be able to" in a functional spec — that is requirement-modal voice; state the fact directly
 
 BAD — imperative commands, or the vague "The system":
@@ -18,11 +24,14 @@ BAD — imperative commands, or the vague "The system":
 ```plain
 ***functional specs***
 
-- Implement the entry point for :App:.
+# entry-point
+Implement the entry point for :App:.
 
-- The system shows :TaskList:.
+# show-task-list
+The system shows :TaskList:.
 
-- Add :Task:.
+# add-task
+Add :Task:.
 ```
 
 GOOD — statements of fact with concrete subjects:
@@ -30,71 +39,75 @@ GOOD — statements of fact with concrete subjects:
 ```plain
 ***functional specs***
 
-- :App: has an entry point.
+# entry-point
+:App: has an entry point.
 
-- The :TaskList: is displayed.
+# show-task-list
+The :TaskList: is displayed.
 
-- A :User: can add a :Task:. Only valid :Task: items are added.
+# add-task
+A :User: can add a :Task:. Only valid :Task: items are added.
 ```
 
 ## Conciseness
-- A functional spec that a human will not read is not reviewed, so every spec must be as short as its content allows — see `concise-specs.md`
+- A functional spec that a human will not read is not reviewed, so every one must be as short as its content allows — see `concise-specs.md`
 - Cut anything obvious, any rationale, and every uncheckable adjective; keep every interface detail, boundary case, and disambiguation
 - Shorten the wording, never the facts: the rules below always win over brevity
 
 ## Complexity limit
 - The complexity limit is about breaking software into small, independently understandable behavior slices that people and AI can reason about, implement, and test reliably
 - The current mechanism for enforcing the complexity limit is that each functional spec must imply a **maximum of 200 changed lines of code**.
-- Smaller slices produce focused test failures, reduce hidden coupling and regression surface, and make review and incremental rendering more predictable
-- If a spec is too large, use `break-down-func-spec` to split it into multiple smaller, independent specs
-- Judge a spec's size yourself before inserting it: estimate the code it implies - new files, functions, data model changes, UI components, error paths, boilerplate, its unit tests - and treat more than ~150 lines as too big, leaving the renderer headroom
-- Signs a spec is too big - one is not proof, several are:
+- Smaller slices produce focused test failures, reduce hidden coupling and regression surface, and make review and incremental regeneration more predictable
+- If a functional spec is too large, use `break-down-func-spec` to split it into multiple smaller, independent ones
+- Judge a functional spec's size yourself before inserting it: estimate the code it implies - new files, functions, data model changes, UI components, error paths, boilerplate, its unit tests - and treat more than ~150 lines as too big, leaving the coding agent headroom
+- Signs a functional spec is too big - one is not proof, several are:
   - more than one independently testable behavior ("create, edit, delete and archive")
   - more than three new constructs at once - data structures, UI components, endpoints
   - several modes or conditional paths, each with its own behavior
   - core behavior bundled with cross-cutting concerns - retries, pagination, caching, logging
   - a whole screen with several interactive elements and state transitions
   - multi-step transformations, joins or aggregations across entities
-  - a substantial technical component it must build as well as use - an engine, parser, scheduler, layout algorithm, state machine, sync mechanism; it counts toward the limit, and goes in a spec of its own before the one that uses it
-- Use `analyze-func-specs` to check a spec (or a batch of specs) against all relevant existing specs in a single batched call; use `resolve-spec-conflict` for each conflicting pair it reports
+  - a substantial technical component it must build as well as use - an engine, parser, scheduler, layout algorithm, state machine, sync mechanism; it counts toward the limit, and goes in a functional spec of its own before the one that uses it
+- Use `analyze-func-specs` to check a functional spec (or a batch of them) against all relevant existing ones in a single batched call; use `resolve-spec-conflict` for each conflicting pair it reports
 
 ## First-spec bootstrap cost
 - The first functional spec in a new root module carries implicit implementation cost even when its text describes little behavior
-- The renderer may need to create the project structure, package metadata, framework configuration, entry point, initial source files, and unit-test infrastructure before implementing the behavior
-- Count that bootstrap work toward the 200-changed-line limit; it is not free setup outside the spec
-- Make the first spec the module's simplest useful, independently observable capability
-- The first spec must still imply a testable outcome; setup alone is not a functional spec
+- The coding agent may need to create the project structure, package metadata, framework configuration, entry point, initial source files, and unit-test infrastructure before implementing the behavior
+- Count that bootstrap work toward the 200-changed-line limit; it is not free setup outside the functional spec
+- Make the first functional spec the module's simplest useful, independently observable capability
+- The first functional spec must still imply a testable outcome; setup alone is not a functional spec
 - Prefer one minimal entry point or public operation with a deterministic result that can be invoked and verified
-- Defer persistence, integrations, multiple interfaces, branching workflows, and cross-cutting behavior until later specs can build on the generated baseline
-- A spec may start on its happy path and be hardened later - validation, edge cases and errors added to it by changing it - once the software has been tried; it must still say exactly what it does for the input it covers
+- Defer persistence, integrations, multiple interfaces, branching workflows, and cross-cutting behavior until later functional specs can build on the generated baseline
+- A functional spec may start on its happy path and be hardened later - validation, edge cases and errors added to it by changing it - once the software has been tried; it must still say exactly what it does for the input it covers
 - This extra bootstrap cost applies when no previous implementation baseline exists; a module that continues from a `requires` module may already inherit the necessary scaffold
 
 ## Chronological ordering
-- Specs are rendered incrementally, top to bottom
-- The renderer has **no knowledge of future specs** — only previously rendered specs are in context
-- A new spec can reference behavior from earlier specs but cannot assume anything about specs that come after it
+- Functional specs are regenerated incrementally, top to bottom
+- The coding agent has **no knowledge of later functional specs** — only those before it are in context
+- A new functional spec can reference behavior from earlier ones but cannot assume anything about those that come after it
 - Functional specs from `requires` modules are treated as previous requirements — transitively, across the whole ancestor chain
-- This order is about what a spec may assume, not what a change costs: turri regenerates a change as a spec diff wherever it sits (`turri-regeneration.md`)
+- This order is about what a functional spec may assume, not what a change costs: turri regenerates a change as a ***plain diff wherever it sits (`turri-regeneration.md`)
 
 ## No conflicts
-- The new spec must not contradict any existing functional spec
-- Before adding, review all existing specs and verify compatibility
+- A new functional spec must not contradict any existing one
+- Before adding, review all existing functional specs and verify compatibility
 - If ambiguity exists, add explicit detail to eliminate any conflicting interpretation
 
 ## Adding a functional spec
 Every new functional spec - one or a batch - is checked before it is written into the file:
 1. Draft it, then trim it per `concise-specs.md` to the shortest wording that keeps every fact
 2. Judge its size against the complexity limit; when it is too big, split it with `break-down-func-spec` and check each part from step 1
-3. Check it for conflicts with **one** `analyze-func-specs` call over the new spec and every existing functional spec in the file and its `requires` chain - never pair by pair. Resolve each conflicting pair it reports with `resolve-spec-conflict`, then run it again over what changed until it is compatible
-4. Only then write it in, where it belongs (see Placement)
+3. Check it for conflicts with **one** `analyze-func-specs` call over the new functional spec and every existing one in the file and its `requires` chain - never pair by pair. Resolve each conflicting pair it reports with `resolve-spec-conflict`, then run it again over what changed until it is compatible
+4. Pick its func-id per `semantic-ids.md`, unique in the module - and in the batch
+5. Only then write it in, where it belongs (see Placement), as its `# <func-id>` heading and body - with no test plain file, unless the person asks for its tests (see `test-plain-files.md`)
 
-A batch is checked one spec at a time, in order: each spec's conflict check includes the specs of the batch already written in. Never write the whole batch in first and check it afterwards - a bad spec already in the file skews every later check. A few specs are no reason to skip a check.
+A batch is checked one functional spec at a time, in order: each one's conflict check includes those of the batch already written in. Never write the whole batch in first and check it afterwards - a bad functional spec already in the file skews every later check. A few functional specs are no reason to skip a check.
 
 ## Placement
-Put a new spec where it fits the module as it reads, not at the end by default:
-- **Below every spec it builds on** - each one whose behaviour it references or extends, and the first to use each concept it relies on
-- **Above every spec that builds on it** - one that already assumes what it adds
-- **Within those bounds, beside the specs of its feature** - usually straight after the last one it extends
+Put a new functional spec where it fits the module as it reads, not at the end by default:
+- **Below every functional spec it builds on** - each one whose behaviour it references or extends, and the first to use each concept it relies on
+- **Above every functional spec that builds on it** - one that already assumes what it adds
+- **Within those bounds, beside the functional specs of its feature** - usually straight after the last one it extends
 - **At the end** only when it starts something new or fits nowhere better
 
 ## Language agnosticism
@@ -102,68 +115,50 @@ Put a new spec where it fits the module as it reads, not at the end by default:
 - Avoid language-specific terminology: generics syntax, framework annotations, language-specific collection types, decorator syntax, base-class keywords, framings like "POJO" or "dataclass"
 - General technical terms that are not language-specific are fine: null values, JSON types, HTTP status codes, REST endpoints, etc.
 - **Naming concrete components is encouraged.** Functional specs can and should refer to concrete domain components, services, or entities (e.g., `:PaymentProcessor:`, `:UserRepository:`, `:DataConverter:`) and their operations (e.g., `:ChargeCard:`, `:FindById:`), pinning down their inputs, outputs, and error behavior. Those names are part of the public contract and survive a language switch. What they must **not** do is bake in how the contract is realized (`@staticmethod`, `class Foo extends Bar`, `List<T>`, `async def`, etc.)
-- **Litmus test:** if the project switched from Python to Java (or vice versa), would the functional spec read correctly with only `***implementation reqs***` updated? If yes, the spec is language-agnostic. If the spec itself would need rewording, the construct belongs in implementation reqs.
+- **Litmus test:** if the project switched from Python to Java (or vice versa), would the functional spec read correctly with only `***implementation reqs***` updated? If yes, it is language-agnostic. If the functional spec itself would need rewording, the construct belongs in implementation reqs.
 
 ## Disambiguation
-- Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation
-- If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail
-- Nested lines clarify the parent spec — they do not introduce separate functionality
-- Even with nested detail, the spec must still imply ≤ 200 lines of code
+- Each functional spec must be unambiguous — the coding agent should have only one reasonable interpretation
+- If the statement line is not enough to fully disambiguate the behavior, add `- ` bullets or sentences under it to add detail
+- The detail clarifies the statement - it does not introduce separate behaviour
+- Even with the detail, the functional spec must still imply ≤ 200 lines of code
 
 ## Testability
 - Every functional spec must describe behavior that can be verified through an observable interface
 - State the triggering input or action and the deterministic outcome a test can observe
 - Include relevant outputs, state changes, errors, or externally visible side effects
 - Do not rely on generated implementation details as the only way to verify the behavior
-- If a black-box conformance test cannot be derived from the spec, make the behavior more explicit
-- Testability does not require an acceptance test; acceptance tests are reserved for full workflows
+- If a black-box conformance scenario could not be written from the functional spec, make the behavior more explicit
 
 ## Deterministic interface
-- Specs must be detailed enough that a developer can use the built software without reading the generated code
+- Functional specs must be detailed enough that a developer can use the built software without reading the generated code
 - All external interfaces must be explicit: REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc.
-- Never leave interface details up to the renderer's discretion
+- Never leave interface details up to the coding agent's discretion
 
 ## Encapsulation
-- Functionality must be self-contained in the spec text
+- Behaviour must be self-contained in the functional spec's text
 - `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs, so do not rely on implementation reqs to convey behavior
 - Behavior that downstream modules need must be expressed in functional specs, not elsewhere
 
-## Acceptance tests
-- Nest `***acceptance tests***` under a functional spec when verification criteria are needed
-- Each acceptance test must be a **full workflow test** — a specific scenario that exercises the functional spec end-to-end, not a unit-level check of a single field or condition
-- Do not restate the obvious behavior from the functional spec — simple, direct verifications are already auto-generated as conformance tests. Acceptance tests must go beyond that: multi-step workflows, interactions between concepts, edge-case scenarios, or end-to-end sequences that prove the feature works in a realistic context
-- Each acceptance test must be a direct logical consequence of the parent spec — it illustrates, not extends
-- Acceptance tests must describe concrete, verifiable outcomes — not vague qualities
-- Acceptance tests must not contradict, narrow, or extend beyond the parent spec
-
-```plain
-Functional spec:
-- :Resource: items are returned sorted by creation date in descending order.
-
-Good - follows from the spec:
-- After three :Resource: items are created one after another, listing them returns the last one created first.
-
-Bad - contradicts it (the spec says descending):
-- The first :Resource: listed is the oldest.
-
-Bad - extends it (the spec says nothing about a limit):
-- At most 50 :Resource: items are listed.
-```
+## Test scenarios live in test plain files
+- A module never holds a `***conformance tests***` or `***acceptance tests***` section, nested or top-level
+- A functional spec's conformance and acceptance scenarios go into its test plain file, `tests/<module>/<func-id>.plain`, and are written only when the person asks for tests (see *Writing scenarios* in `test-plain-files.md`)
+- A functional spec and its test plain file change together, in the same ***plain diff: a new one gets none, unless its tests are asked for; a changed one has its scenarios, if any, reviewed; a split, moved, renamed or deleted one takes its test plain file, if it has one, with it (see *Keeping test plain files in step* in `test-plain-files.md`)
 
 ## Format
 
 ```plain
 ***functional specs***
 
-- :App: has an entry point.
-
-- A :User: can add a :Task:. Only valid :Task: items are added.
+# entry-point
+:App: has an entry point.
 
-- A :User: can send a :Message: to a :Conversation:.
-  - A :Message: must have non-empty content.
-  - The :Message: is appended to the end of the :Conversation:.
-  - All :Participant: members of the :Conversation: can see the new :Message:.
+# add-task
+A :User: can add a :Task:. Only valid :Task: items are added.
 
-  ***acceptance tests***
-  - Sending a :Message: to a :Conversation: with three participants should make the message visible to all three.
+# send-message
+A :User: can send a :Message: to a :Conversation:.
+- A :Message: must have non-empty content.
+- The :Message: is appended to the end of the :Conversation:.
+- All :Participant: members of the :Conversation: can see the new :Message:.
 ```

package/genome/rules/impl-reqs.md

@@ -14,7 +14,7 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 ## `:UnitTests:` lives here (hard rule)
 - **Everything** about `:UnitTests:` goes in `***implementation reqs***` — paths, approach, packages, framework, conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates
 - `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/code/` alongside the implementation), so requirements that shape them are implementation reqs by definition
-- The unit-test generator reads **only** `***implementation reqs***` — anything about `:UnitTests:` placed elsewhere (e.g. `***test reqs***`) is silently ignored
+- The coding agent reads how to write the unit tests **only** from `***implementation reqs***` — anything about `:UnitTests:` placed elsewhere (e.g. `***test reqs***`) is silently ignored
 - Phrase each `:UnitTests:` requirement in terms of `:UnitTests:` so the partition stays visible at a glance
 
 ## What belongs here
@@ -32,13 +32,13 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 - Behavior and features → `***functional specs***`
 - Concept definitions → `***definitions***`
 - **Conformance-test guidance** → `***test reqs***`
-- **Acceptance-test scenarios** → `***acceptance tests***` nested under the relevant functional spec
+- **Test scenarios**, conformance and acceptance → the functional spec's test plain file (see `test-plain-files.md`)
 
 ## Unit tests vs conformance tests (common mistake)
 - Unit-test guidance (`:UnitTests:` framework, structure, mocking) goes **here**, not in `***test reqs***`
 - `***test reqs***` is exclusively for `:ConformanceTests:` — framework, execution command, mocking policy, environment setup
-- Putting unit-test guidance in `***test reqs***` is one of the most common authoring mistakes; the rendered code will silently miss those requirements because the unit-test generator only reads `***implementation reqs***`
-- Do not link the unit testing script here (or anywhere in the specs; a link to it is ignored). turri finds it in the project root - `unittests-script:` in `config.turri.yaml`, else the one `run_unittests*.sh` in the root, else the one in `test_scripts/` - and shows it to the coding agent itself. Describe the framework and run command here in words
+- Putting unit-test guidance in `***test reqs***` is one of the most common authoring mistakes; the regenerated code will silently miss those requirements because the coding agent reads unit-test guidance only from `***implementation reqs***`
+- Do not link the unit testing script here (or anywhere in the ***plain; a link to it is ignored). turri finds it in the project root - `unittests-script:` in `config.turri.yaml`, else the one `run_unittests*.sh` in the root, else the one in `test_scripts/` - and shows it to the coding agent itself. Describe the framework and run command here in words
 
 ## Encapsulation warning
 - `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs

package/genome/rules/integration-embedded-testing.md

@@ -4,7 +4,7 @@ description: Rules for authoring the two test scripts that an embedded ***plain
 
 # Rules for embedded-integration test scripts
 
-When an embedded integration ships its two `test_scripts/` (unit, conformance), these rules apply on top of the contracts in the corresponding `implement-*-testing-script` skills. `project-model.md` covers the rendering and testing workflow.
+When an embedded integration ships its two `test_scripts/` (unit, conformance), these rules apply on top of the contracts in the corresponding `implement-*-testing-script` skills. `project-model.md` covers the regenerating and testing workflow.
 
 ## Staging model (read this first)
 
@@ -24,7 +24,7 @@ This deliberately writes into the host's `src/main/...` and `src/test/...` (or t
 
 This rule covers the **mechanics each script must obey** regardless of language: argument handling, exit codes, idempotency, path resolution, output parsing, and the "what NOT to put here" guard rails. The language-specific install / test commands come from the skills; the contract below is invariant.
 
-## What the `.plain` spec must declare
+## What the `.plain` file must declare
 
 The two scripts are generated from facts in the integration's spec. For an embedded integration, those facts cannot be inferred — they have to be **declared explicitly** in the right section, partitioned by which predefined concept they describe:
 
@@ -77,7 +77,7 @@ These reqs feed `run_conformance_tests_<lang>`. At minimum, declare:
 2. **`:ConformanceTests:` framework and execution command** — `mvn test --no-transfer-progress`, `pytest`, `npm test`, `go test ./...`, etc., with any flags / profiles the project requires
 3. **Fully qualified `:ConformanceTests:` package** (or path / pattern) used to scope discovery, if the runner needs one
 4. **`:ConformanceTests:` network and secrets policy** — by default the suite runs against the **live provider** (see [`integrations.md`](integrations.md) → *`:ConformanceTests:` always run against the live integration*). Declare the env-var names the script reads (e.g. `<PROVIDER>_API_KEY`), whether the script loads a `.env` file before running, and any specific endpoints that are mocked because they can't be exercised live safely (429, forced 5xx)
-5. **`:ConformanceTests:` pass criteria** — the strict criteria from [*Pass criteria (strict)*](#pass-criteria-strict): at least one test ran AND zero failures / errors / skipped. Reaffirm this in the spec so the renderer knows the runner must parse the test tool's stdout
+5. **`:ConformanceTests:` pass criteria** — the strict criteria from [*Pass criteria (strict)*](#pass-criteria-strict): at least one test ran AND zero failures / errors / skipped. Reaffirm this in the ***plain so the script's author knows the runner must parse the test tool's stdout
 6. **`:ConformanceTests:` build / install needs** — anything the conformance project needs before `mvn test` (or equivalent) will work: the host build / install command the script runs first, dependencies, fixtures, schema files, generated stubs
 
 Author the conformance facts as one or more entries, phrased in terms of `:ConformanceTests:`:
@@ -115,10 +115,10 @@ output=$(mvn test --no-transfer-progress 2>&1)
 
 - **The paths must agree across reqs.** The `:UnitTests:` source path, the `:UnitTests:` package, and the integration source path describe the same module from three angles. Same for the `:ConformanceTests:` location and its package. A mismatch (e.g. test path `src/test/java/com/example/foo` but test package `com.example.bar`) silently produces a green build with stale or zero tests
 - **Paths are host-relative**, not absolute. `MAIN_PROJECT_FOLDER` comes from `HOST_CODEBASE_ROOT` (declared in the configuration concept); the paths above join onto it
-- **The renderer's output folder `$1` mirrors the same layout.** `$1/<integration source path>/*` exists because the renderer emits the generated code into the same package directories it'll be copied into — the `cp -R` is a straight overlay, not a path translation
-- **Each fact lives in one place.** If two `***implementation reqs***` entries declare slightly different `:UnitTests:` paths (or two `***test reqs***` entries declare slightly different `:ConformanceTests:` packages), the renderer can't tell which to use. Author each group as a tight cluster (one bullet with sub-bullets) so a future reviewer sees them together
-- **Never duplicate a fact across sections.** `:UnitTests:` facts belong **only** in `***implementation reqs***`; `:ConformanceTests:` facts belong **only** in `***test reqs***`. The two groups never overlap — the script generators read each from its own section
-- **For non-Java languages**, the facts have language-specific equivalents — Python: `src/foo/`, `tests/foo/`, `tests.foo`; Node: `src/foo/`, `test/foo/`, `test/foo/**/*.test.ts`. The `implement-*-testing-script` skills know the mapping per language, but the spec still has to declare the host-relative paths and packages so the skill knows what to put in the script bodies
+- **The coding agent's output folder `$1` mirrors the same layout.** `$1/<integration source path>/*` exists because the coding agent emits the generated code into the same package directories it'll be copied into — the `cp -R` is a straight overlay, not a path translation
+- **Each fact lives in one place.** If two `***implementation reqs***` entries declare slightly different `:UnitTests:` paths (or two `***test reqs***` entries declare slightly different `:ConformanceTests:` packages), the coding agent can't tell which to use. Author each group as a tight cluster (one bullet with sub-bullets) so a future reviewer sees them together
+- **Never duplicate a fact across sections.** `:UnitTests:` facts belong **only** in `***implementation reqs***`; `:ConformanceTests:` facts belong **only** in `***test reqs***`. The two groups never overlap — the agents read each from its own section
+- **For non-Java languages**, the facts have language-specific equivalents — Python: `src/foo/`, `tests/foo/`, `tests.foo`; Node: `src/foo/`, `test/foo/`, `test/foo/**/*.test.ts`. The `implement-*-testing-script` skills know the mapping per language, but the ***plain still has to declare the host-relative paths and packages so the skill knows what to put in the script bodies
 
 ## Common contract (both scripts)
 
@@ -131,17 +131,17 @@ Both scripts are invoked by turri with positional arguments, on the person's mac
    - `69` — unrecoverable environment failure (missing toolchain, cannot enter working folder, install failed)
    - Any other non-zero code — propagated verbatim from the underlying build / test tool
 
-   turri passes `$1` (and `$2` for the conformance runner) as **absolute paths** (older renderer versions passed relative ones). Never build a derived path by concatenating a raw argument (`.tmp/$1`, `<lang>_$1`, `$current_dir/$2`) — with an absolute argument that produces a doubled path (`/project//abs/path/...`). Use the argument as-is where a path is needed, take its `basename` when naming a scratch folder, and resolve `$2` to absolute (if it isn't already) before any `cd`
+   turri passes `$1` (and `$2` for the conformance runner) as **absolute paths** (older harnesses passed relative ones). Never build a derived path by concatenating a raw argument (`.tmp/$1`, `<lang>_$1`, `$current_dir/$2`) — with an absolute argument that produces a doubled path (`/project//abs/path/...`). Use the argument as-is where a path is needed, take its `basename` when naming a scratch folder, and resolve `$2` to absolute (if it isn't already) before any `cd`
 3. **Echo the toolchain home at the top** — the first thing a developer checks when CI breaks. For Java: `JAVA_HOME`. For Python: the active interpreter (`python --version` / `which python`). For Node: `node --version`. For Go: `go env GOROOT`. Pick the variable whose value most often explains "why does it work locally but not on the CI runner?"
 4. **Respect `VERBOSE=1`.** Gate chatty diagnostic prints behind `if [ "${VERBOSE:-}" = "1" ]` (and the PowerShell equivalent). Errors and key step markers print unconditionally
-5. **Resolve paths relative to the script, not `$PWD`.** Use `"$(cd "$(dirname "$0")/<relative-path-to-anchor>" && pwd)"`. Hard-coded `../../` chains break the moment the renderer's `cwd` changes
+5. **Resolve paths relative to the script, not `$PWD`.** Use `"$(cd "$(dirname "$0")/<relative-path-to-anchor>" && pwd)"`. Hard-coded `../../` chains break the moment turri's `cwd` changes
 6. **Create destination directories before copying.** `mkdir -p` before any `cp -R` / `rsync` / `robocopy` — most copy commands do not create intermediate directories and fail silently in some shells
 7. **Scope destructive operations narrowly.** Any `rm -rf` (or `Remove-Item -Recurse -Force`) targets only the module's own package path inside the working folder — never the host's `src/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. The conformance script cleans the host's build-output directory (e.g. `./target`) only as part of its own build / install step, and removes its system-temp scratch folder on exit
 8. **Print where you are before you `cd`.** `echo "Moving to: $DIR"` saves an hour of debugging when paths are wrong. PowerShell: `Write-Host "Moving to: $DIR"`
 
 ## 1. `run_unittests_<lang>` — copy into the host, then run unit tests there
 
-Receives one positional argument: the renderer's build output folder (`plain_modules/<module>/code/`, absolute).
+Receives one positional argument: the build output folder (`plain_modules/<module>/code/`, absolute).
 
 Purpose: stage the generated code **into the host codebase at the module's package path** and run the module's unit tests + language-appropriate quality gates against the host project from inside the host root.
 
@@ -162,17 +162,17 @@ Required steps:
 Hard rules:
 
 - **Self-contained.** The script stages `$1` itself on every run; it never relies on another script having run first
-- **Never run the full test suite** when scoping is possible. A per-module script that runs the entire host's tests wastes minutes on every render iteration
+- **Never run the full test suite** when scoping is possible. A per-module script that runs the entire host's tests wastes minutes on every regeneration
 
 ## 2. `run_conformance_tests_<lang>` — copy into the host, build it, then run the external suite
 
-Receives two positional arguments: the renderer's build output folder (`$1`, `plain_modules/<module>/code/`) and the conformance-tests folder (`$2`, `plain_modules/<module>/tests/` — the module's whole conformance suite), both absolute.
+Receives two positional arguments: the build output folder (`$1`, `plain_modules/<module>/code/`) and the conformance-tests folder (`$2`, `plain_modules/<module>/tests/` — the module's whole conformance suite), both absolute.
 
-Purpose: stage the generated code into the host, build / install the host, and run the whole conformance suite in `$2` against that build. The conformance suite is a separate project that consumes the integration as a dependency from a local cache (`~/.m2`, `node_modules`, the language equivalent), so the script installs the host itself first — otherwise the suite links against whatever was last built, which may not be the renderer's most recent output. turri runs it once per check, and its exit code decides whether the conformance tests pass.
+Purpose: stage the generated code into the host, build / install the host, and run the whole conformance suite in `$2` against that build. The conformance suite is a separate project that consumes the integration as a dependency from a local cache (`~/.m2`, `node_modules`, the language equivalent), so the script installs the host itself first — otherwise the suite links against whatever was last built, which may not be the most recent regenerated code. turri runs it once per check, and its exit code decides whether the conformance tests pass.
 
 Required steps:
 
-1. Validate `$1` and `$2`. Resolve `$2` to an absolute path if it isn't one already (newer renderers pass it absolute; older ones passed it relative to the invocation directory)
+1. Validate `$1` and `$2`. Resolve `$2` to an absolute path if it isn't one already (turri passes it absolute; older harnesses passed it relative to the invocation directory)
 2. Resolve the host codebase root from the configured env var, `rm -rf` the module's main + test package directories under the host's source tree, `mkdir -p` the destination directories, and copy `$1/src/...` into the host's source tree at the module's package path — **the same staging as `run_unittests`**
 3. `cd` into the host codebase root, verify with an explicit exit-code check
 4. Clean the host's build-output directory before compiling — stale class / object files from a previous build cause confusing link-time mismatches when the contract has changed. Maven: `rm -rf ./target`. Cargo: `cargo clean -p <pkg>`. Go: `go clean -cache` (usually unnecessary, but mention if applicable). For npm projects with incremental builds disabled, wipe the relevant `dist/` / `build/` folder
@@ -195,7 +195,7 @@ Required steps:
    - Bash: `output=$(mvn test --no-transfer-progress 2>&1)` (or the language equivalent)
    - PowerShell: `$output = & <cmd> 2>&1 | Out-String`
 10. **Parse the captured output strictly** (see *Pass criteria* below) — don't trust the test tool's exit code alone
-11. On the failure path: print the captured output unconditionally so the renderer (and the user) can see what failed
+11. On the failure path: print the captured output unconditionally so turri (and the user) can see what failed
 12. On the success path: print the output only if `VERBOSE=1`
 
 ### Secrets and `.env` handling
@@ -238,15 +238,15 @@ These are the **only** valid pass criteria. Anything outside this list is a fail
 
 Failure cases — each must be detected explicitly:
 
-- `Tests run: 0` (or the language equivalent) → **failure**. The renderer must never be told "green" when nothing ran. Exit `1` per the shared testing-script rules (the "no tests discovered" exit code)
+- `Tests run: 0` (or the language equivalent) → **failure**. turri must never be told "green" when nothing ran. Exit `1` per the shared testing-script rules (the "no tests discovered" exit code)
 - Any non-zero `Failures:`, `Errors:`, or `Skipped:` count → **failure**. Dump the captured output and propagate the test tool's exit code
 - The test tool exited non-zero but the summary line shows `Tests run: 0` → still a `1` (no-tests-discovered), not the tool's own exit code
 
-**Why parse stdout instead of trusting the test tool's exit code.** Every major test runner returns `0` when zero test classes match a filter. Maven Surefire, pytest with no collected tests, `go test ./pkg/that/has/no/_test.go/files`, Jest with an empty pattern — all green-by-default. The renderer's contract is "tests must run AND must pass" — the exit code alone cannot express that.
+**Why parse stdout instead of trusting the test tool's exit code.** Every major test runner returns `0` when zero test classes match a filter. Maven Surefire, pytest with no collected tests, `go test ./pkg/that/has/no/_test.go/files`, Jest with an empty pattern — all green-by-default. turri's contract is "tests must run AND must pass" — the exit code alone cannot express that.
 
 ## Cross-cutting rules
 
-- **No secrets in scripts.** Read credentials from env vars the renderer (or the user's shell) already sets. If a required env var is missing, fail fast with a clear `Error: $FOO is required for ...` and exit `69`. Never hardcode an API key, never read from a checked-in file
+- **No secrets in scripts.** Read credentials from env vars turri (or the user's shell) already sets. If a required env var is missing, fail fast with a clear `Error: $FOO is required for ...` and exit `69`. Never hardcode an API key, never read from a checked-in file
 - **Mirror the package / module path exactly.** A typo in the package segment (e.g. one wrong directory in `com/example/foo/...` or `host_pkg/foo/bar/...`) makes `rm -rf` silently do nothing and the subsequent copy put files in the wrong place. Both produce a **green** build with stale code. Derive the package path from the `host-codebase` concept; never retype it inline
 - **Don't add cleverness to the script that belongs in the build.** If you're tempted to `grep` the test output for more than the pass/fail summary, change the test or the test-runner config instead. The script is a thin contract — keep it that way
 - **Don't use shortcut profiles that skip quality gates.** Maven's `-Pfast`, Gradle's `-x check`, npm's `--ignore-scripts`, pytest's `--no-cov`, `-DskipTests` anywhere except the conformance script's two build / install steps (the host install and the conformance project's compile, where the tests run right after) — all defeat the purpose of these scripts. The build's full quality gate (tests + lint + coverage thresholds) must run for unit and conformance
@@ -267,7 +267,7 @@ Use them as a template when adding a new embedded integration in Java / Maven
 1. Copy the two scripts from a working embedded-integration module into the project's `test_scripts/`
 2. Search-and-replace the package segment everywhere it appears — including the test-filter argument (the most commonly missed spot)
 3. `chmod +x` both (and verify ACLs on Windows for the `.ps1` siblings)
-4. Do not link them from the specs: turri finds them in the project root - `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`), else the one of each kind in the root, else in `test_scripts/` - and shows them to the agents itself. If `test_scripts/` ends up with two scripts of one kind, name the one to use in `config.turri.yaml`.
-5. Smoke-test by running each script manually with the renderer's output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what the renderer expects
+4. Do not link them from the ***plain: turri finds them in the project root - `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`), else the one of each kind in the root, else in `test_scripts/` - and shows them to the agents itself. If `test_scripts/` ends up with two scripts of one kind, name the one to use in `config.turri.yaml`.
+5. Smoke-test by running each script manually with the build output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what turri expects
 
 For non-Java languages, the skills [`implement-unit-testing-script`](../skills/implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../skills/implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.