@turri-dev/cli 0.1.4-next.5a94e68 → 0.1.4-next.8254fbc

package/genome/rules/bullet-continuation.md

@@ -15,19 +15,12 @@ These rules apply to every section and to concept explanations.
 
 ## One statement per line
 
-This is the preferred `.plain` authoring convention, not something the renderer enforces. A line
-break in a section means one of exactly two things: a new `- ` statement, or a nested `- `
-clarification of the statement above it. There is no third, typographic reason to break a line.
+This is the preferred `.plain` authoring convention, not something the renderer enforces. A line break in a section means one of exactly two things: a new `- ` statement, or a nested `- ` clarification of the statement above it. There is no third, typographic reason to break a line.
 
 - Write each statement on a single line, however long
-- Never break a line just for width: a bare continuation (an indented line without `- `) adds a
-  line break that carries no structure — to every future reader and editing agent it is
-  indistinguishable from a deliberate sub-point
-- The test: if content deserves its own line, it deserves its own `- ` bullet; if it doesn't,
-  keep it on the parent's line
-- What the renderer does enforce is the top level: every statement in a section must be a `- `
-  list item — a flush-left prose line is a syntax error. A bare continuation, by contrast, is
-  accepted and folded into its parent item verbatim
+- Never break a line just for width: a bare continuation (an indented line without `- `) adds a line break that carries no structure — to every future reader and editing agent it is indistinguishable from a deliberate sub-point
+- The test: if content deserves its own line, it deserves its own `- ` bullet; if it doesn't, keep it on the parent's line
+- What the renderer does enforce is the top level: every statement in a section must be a `- ` list item — a flush-left prose line is a syntax error. A bare continuation, by contrast, is accepted and folded into its parent item verbatim
 
 BAD — line broken for width (bare continuation):
 
@@ -65,5 +58,4 @@ BEST — separate clarifications expressed as nested bullets:
 
 ## Content that belongs in resources
 
-Long URLs, schema fragments, and example payloads belong in `resources/` because they are external
-artifacts, not because of their character count. Follow `linked-resources.md`.
+Long URLs, schema fragments, and example payloads belong in `resources/` because they are external artifacts, not because of their character count. Follow `linked-resources.md`.

package/genome/rules/concise-specs-examples.md

@@ -208,8 +208,7 @@ GOOD:
 - :ConformanceTests: mock every external HTTP call.
 ```
 
-Every hedge hands the renderer a decision the spec was supposed to make. A spec states one
-behavior.
+Every hedge hands the renderer a decision the spec was supposed to make. A spec states one behavior.
 
 ## Ornate vocabulary
 
@@ -427,5 +426,4 @@ GOOD:
   - :ProjectList: contains exactly one :Project:, named `Apollo`.
 ```
 
-One narrated paragraph becomes an ordered set of checkable steps, and "everything worked as
-expected" becomes an assertion.
+One narrated paragraph becomes an ordered set of checkable steps, and "everything worked as expected" becomes an assertion.

package/genome/rules/concise-specs-integration-examples.md

@@ -221,9 +221,7 @@ GOOD:
 - :ProviderClient: uses :AuthTokenManager: to cache and refresh :AccessToken:.
 ```
 
-The grant type, endpoint, body encoding, and response fields are in the security scheme. What
-survives is the policy the scheme does not describe: the env-var names, the refresh margin, the
-retry-once-on-401 rule, and the concurrency behavior.
+The grant type, endpoint, body encoding, and response fields are in the security scheme. What survives is the policy the scheme does not describe: the env-var names, the refresh margin, the retry-once-on-401 rule, and the concurrency behavior.
 
 Almost all of it is implementation reqs — acquisition, caching, and refresh are machinery a caller never sees. Not all of it, though, and the rewrite has to name a component to say the rest. :ProviderAuth: performs the grant and has no observable surface; :AuthTokenManager: is what consumes it and hands tokens to :ProviderClient:, so it is the concept a functional spec can take as its subject. Without that consumer the section is left with a subject-less bullet, which `func-specs.md` rules out — and that one spec is the only line here a live conformance test can assert.
 
@@ -265,6 +263,4 @@ GOOD:
   - The `429` and forced-`5xx` paths mock that endpoint alone; every other path is live.
 ```
 
-A policy that holds for every endpoint is stated once. Enumerate an endpoint only where it departs
-from the policy — here, the two paths that cannot be exercised live safely, which
-`integrations.md` requires to be documented explicitly.
+A policy that holds for every endpoint is stated once. Enumerate an endpoint only where it departs from the policy — here, the two paths that cannot be exercised live safely, which `integrations.md` requires to be documented explicitly.

package/genome/rules/concise-specs.md

@@ -27,8 +27,7 @@ Do not write:
 - 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")
 
-Worked pairs for every item above — padding, rationale, defaults, technology behavior,
-meta-commentary, and duplication of an `import` — are in `concise-specs-examples.md`.
+Worked pairs for every item above — padding, rationale, defaults, technology behavior, meta-commentary, and duplication of an `import` — are in `concise-specs-examples.md`.
 
 ## Use plain words
 

package/genome/rules/func-specs.md

@@ -65,6 +65,7 @@ GOOD — statements of fact with concrete subjects:
 - 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 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`)
 
 ## No conflicts
 - The new spec must not contradict any existing functional spec

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

@@ -4,10 +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 rendering and testing workflow.
 
 ## Staging model (read this first)
 

package/genome/rules/integrations.md

@@ -63,8 +63,7 @@ Integrations exist to talk to a real third-party (or internal) API. Their `:Conf
 - The integration's `:ConformanceTests:` **must** make real network calls to the provider (typically a sandbox / staging environment, occasionally production for read-only paths). Recorded responses may back unit tests, but they are **not** a substitute for live conformance
 - The only exceptions are paths that **cannot** be exercised live safely:
   - **Rate-limit (429) tests** — must not exhaust the live quota; use a local mock for that specific endpoint
-  - **Deliberately destructive failure modes** (forced 5xx) the provider doesn't let you trigger — same; mock the specific endpoint
-  Document each exception explicitly in `***test reqs***`; everything else is live by default
+  - **Deliberately destructive failure modes** (forced 5xx) the provider doesn't let you trigger — same; mock the specific endpoint Document each exception explicitly in `***test reqs***`; everything else is live by default
 
 ### Secrets come from the environment
 

package/genome/rules/project-model.md

@@ -4,15 +4,12 @@ description: The ***plain project model - the specs as source of truth, the repo
 
 # The ***plain project model
 
-This rule covers the project as a whole. Section content is owned by the per-section rule files;
-file structure by `module-structure.md`.
+This rule covers the project as a whole. Section content is owned by the per-section rule files; file structure by `module-structure.md`.
 
 ## 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
+- 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
 
 ## Repository layout
 
@@ -27,37 +24,23 @@ plain_modules/           # generated - one folder per module
   <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 a spec 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.
-
-- 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`
-- 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
+`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.
+
+- 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`
+- 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
 - Say in your summary which lines you wrote
 
 ## 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 spec instead, in the section that owns the fact:
 
-- behaviour, implementation or unit-test guidance → definitions, functional specs, or implementation
-  reqs
+- 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
 
@@ -75,14 +58,10 @@ Parameters are key-value pairs; the template reads them as `{{ variable_name }}`
 
 ## When an earlier test fails after a render
 
-Functional specs render in order, each knowing the ones before it and none after it - a required
-module's specs count as before. 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 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:
 
 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.
 
-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.
+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.

package/genome/rules/stdlib.md

@@ -4,11 +4,7 @@ description: The ***plain standard library - import modules for a backend, a fro
 
 # Rules for the standard library
 
-turri ships a standard library of import modules that settle everything about a generic piece
-of software on one stack except what it does: its language and framework, its layout, its
-configuration, how it handles errors, how it logs, how it stops, and how it is tested. A module that
-imports one writes only what is its own - its concepts and its functional specs - and a requirement
-only for what its stack does not settle.
+turri ships a standard library of import modules that settle everything about a generic piece of software on one stack except what it does: its language and framework, its layout, its configuration, how it handles errors, how it logs, how it stops, and how it is tested. A module that imports one writes only what is its own - its concepts and its functional specs - and a requirement only for what its stack does not settle.
 
 ```plain
 ---
@@ -20,54 +16,23 @@ import:
 
 ## How it is built up
 
-- Each stack imports its language's template - `stdlib/lang/python` - and its kind's `common` -
-  `stdlib/backend/common` - so importing the stack brings all three.
-- Each stack's conformance tests are a template of their own, `stdlib/<kind>/conformance/<stack>`,
-  which imports `stdlib/<kind>/conformance/common`.
-- The `common` of a kind settles what every stack of it shares. For a backend: settings from the
-  environment, checked at start; handler, service and repository layers; domain errors turned into
-  one error body `{"error": {"code", "message"}}` with fixed codes and statuses; JSON logs with a
-  request id; shutdown on a signal. For a command-line tool: `Error: <message>` on standard error,
-  exit codes 0, 1, 2 and 130, logs on standard error with `--verbose` and `--debug`. For a frontend:
-  one API layer with an `ApiError`, errors shown in place or at the root, one logger module. For a
-  library: one public entry point, one base error type, no output of its own.
+- Each stack imports its language's template - `stdlib/lang/python` - and its kind's `common` - `stdlib/backend/common` - so importing the stack brings all three.
+- Each stack's conformance tests are a template of their own, `stdlib/<kind>/conformance/<stack>`, which imports `stdlib/<kind>/conformance/common`.
+- The `common` of a kind settles what every stack of it shares. For a backend: settings from the environment, checked at start; handler, service and repository layers; domain errors turned into one error body `{"error": {"code", "message"}}` with fixed codes and statuses; JSON logs with a request id; shutdown on a signal. For a command-line tool: `Error: <message>` on standard error, exit codes 0, 1, 2 and 130, logs on standard error with `--verbose` and `--debug`. For a frontend: one API layer with an `ApiError`, errors shown in place or at the root, one logger module. For a library: one public entry point, one base error type, no output of its own.
 
 ## When to use it
 
-- 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`).
-- 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.
+- 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`).
+- 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.
 
 ## 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 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 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.
+- 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 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/turri-regeneration.md

@@ -0,0 +1,48 @@
+---
+description: How turri regenerates the code from a spec change - by spec diff, in the chain's tip - what each kind of change sets off, what a coding agent sees, how bad code is fixed and where the cost really is, so a spec is placed and written by what it means, never by a guess at what regenerating it costs
+---
+
+# How turri regenerates the code
+
+The other rules say what a spec means. This one says what turri does with a change to it, so that where a change goes, and how it is made, is never decided by a wrong idea of how turri works. Each section ends in the same place: decide by what the spec means.
+
+## A change is regenerated as a spec diff
+
+- 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
+- "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
+- 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
+
+## 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
+- Definitions moved to a common module and reqs reordered are recorded, not rendered
+
+## 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
+- 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
+
+## How bad code is fixed
+
+- Never edit the code under `plain_modules/`: the next regeneration does not keep it, and the code record no longer says what the code is
+- In order of cost: change the spec where it is wrong or silent; regenerate the functional specs whose code went bad again, by name; regenerate the module from scratch, or its whole chain - only when the person asks for it or agrees to it
+- A pulse that does not land is rolled back whole - code, tests and record together - and its module waits until the spec changes or the module is asked for again. Running it again unchanged usually ends the same way: look at why it did not land first
+
+## Where the cost is
+
+- The cost is the work regenerated: how many functional specs a change touches, directly or through the definitions they use, cut into pulses of at most `max-specs-per-pulse`
+- Regenerating functional specs again, or a module or chain from scratch, costs most, and is only ever asked for outright
+- Placement never adds cost. Put a functional spec in the module that owns the concern, at the point in its order where what it relies on has been said; never at the end of a module, or in the tip, only to spare regeneration - it spares none
+- Never write placement for cost into AGENTS.md, a skill or notes: what is written there is read back later as how the project works

package/genome/skills/add-implementation-requirement/SKILL.md

@@ -49,8 +49,7 @@ Implementation reqs are free-form instructions that steer code generation. Commo
 
 ## Key Principle: HOW vs WHAT
 
-`***implementation reqs***` describe HOW the software should be built.
-`***functional specs***` describe WHAT the software should do.
+`***implementation reqs***` describe HOW the software should be built. `***functional specs***` describe WHAT the software should do.
 
 If the requirement describes observable behavior (endpoints, business rules, user-facing features), it belongs in functional specs. If it describes internal structure, technology, or coding guidance, it belongs here.
 

package/genome/skills/analyze-if-func-spec-too-complex/SKILL.md

@@ -32,14 +32,9 @@ Work through each indicator. A single "yes" does not automatically mean the spec
 
 ### 0. First-Spec Bootstrap Cost
 
-Is this the first functional spec in a new root module with no implementation baseline supplied by
-`requires`? If so, include the implicit cost of creating the project structure, package metadata,
-framework configuration, entry point, initial source files, and unit-test infrastructure.
-
-The first spec must be substantially simpler than a later spec. It should expose one minimal,
-deterministic capability that can be invoked and tested. Setup without an observable result is not
-acceptable, but combining bootstrap work with persistence, integrations, multiple interfaces,
-branching workflows, or cross-cutting behavior is a strong `TOO COMPLEX` signal.
+Is this the first functional spec in a new root module with no implementation baseline supplied by `requires`? If so, include the implicit cost of creating the project structure, package metadata, framework configuration, entry point, initial source files, and unit-test infrastructure.
+
+The first spec must be substantially simpler than a later spec. It should expose one minimal, deterministic capability that can be invoked and tested. Setup without an observable result is not acceptable, but combining bootstrap work with persistence, integrations, multiple interfaces, branching workflows, or cross-cutting behavior is a strong `TOO COMPLEX` signal.
 
 ### 1. Number of Distinct Behaviors
 

package/genome/skills/brood/SKILL.md

@@ -31,9 +31,7 @@ metadata:
 
 # Brood
 
-Load the `***plain` syntax rules before writing anything — they are in the system prompt
-under `<plain-rules>`; read `genome/rules/<name>.md` for the full text of any rule you need
-to quote or follow closely.
+Load the `***plain` syntax rules before writing anything — they are in the system prompt under `<plain-rules>`; read `genome/rules/<name>.md` for the full text of any rule you need to quote or follow closely.
 
 ## Role
 
@@ -45,25 +43,15 @@ The testing phase is the exception: it changes only `***test reqs***`, and comes
 
 ## Phase discipline
 
-**Finish each phase — its specs on disk and the user's confirmation given — before starting
-the next.** Do not draft, or even ask about, later-phase content while a phase is open: if an
-answer drifts ahead, acknowledge it briefly, note it for later, and steer back.
+**Finish each phase — its specs on disk and the user's confirmation given — before starting the next.** Do not draft, or even ask about, later-phase content while a phase is open: if an answer drifts ahead, acknowledge it briefly, note it for later, and steer back.
 
-When entering a phase, read its reference file and walk its topics **in order**. Skip a
-topic only if it genuinely does not apply, and say so explicitly.
+When entering a phase, read its reference file and walk its topics **in order**. Skip a topic only if it genuinely does not apply, and say so explicitly.
 
-Between phases — and only between phases — summarize what was written and get one explicit
-confirmation before continuing. That single confirmation replaces per-change approval; do
-not ask for both. Do not ask the user to approve each spec change: they are answering
-questions, not running a review queue. After each change, say in one line what went into the
-spec, and carry straight on.
+Between phases — and only between phases — summarize what was written and get one explicit confirmation before continuing. That single confirmation replaces per-change approval; do not ask for both. Do not ask the user to approve each spec change: they are answering questions, not running a review queue. After each change, say in one line what went into the spec, and carry straight on.
 
 ## How many questions
 
-The first question of the intent phase is the harness's own, not yours: how many questions the
-**stack** and **product** phases may ask. The person picks one level, and it holds for each of
-them. The level sets how many questions there are and so how broad each is - never what they
-cover:
+The first question of the intent phase is the harness's own, not yours: how many questions the **stack** and **product** phases may ask. The person picks one level, and it holds for each of them. The level sets how many questions there are and so how broad each is - never what they cover:
 
 | level | questions a phase | each question |
 | --- | --- | --- |
@@ -72,21 +60,9 @@ cover:
 | thorough | at most 10 | narrow: one feature, rule or edge case, with follow-ups on the ones that matter |
 | best judgement | as many as you judge the phase needs | as broad or as narrow as each area needs |
 
-At every level the questions reach all of the phase's topics; fewer questions only go less deep.
-The intent and testing phases are not capped. Follow-ups count; the closing confirmation of a
-phase - asked with `confirms_phase: true` - does not. Past the cap `ask_user` refuses the question.
-To stop sooner, or under best judgement once the phase is settled enough to build, call
-`end_questions`.
-
-The level limits the questions, never the spec changes. In the product phase **every answer is a
-spec change**, whatever the level: written with `write_spec_diff` and built at once, before the
-next question - `ask_user` refuses the next one until it is. A broad answer that covers several
-features is several changes, one a feature, and you write them all. What the questions leave
-open - the details of a light answer, what is left once they are over - is yours to decide, as a
-careful engineer would, in the light of the intent brief: each decision a spec change of its own,
-written with `write_spec_diff` with no answer needed before it, and said in one line. Write as many
-as the product needs. The phase's summary names every decision you made yourself, so the
-confirmation is where the person can change it.
+At every level the questions reach all of the phase's topics; fewer questions only go less deep. The intent and testing phases are not capped. Follow-ups count; the closing confirmation of a phase - asked with `confirms_phase: true` - does not. Past the cap `ask_user` refuses the question. To stop sooner, or under best judgement once the phase is settled enough to build, call `end_questions`.
+
+The level limits the questions, never the spec changes. In the product phase **every answer is a spec change**, whatever the level: written with `write_spec_diff` and built at once, before the next question - `ask_user` refuses the next one until it is. A broad answer that covers several features is several changes, one a feature, and you write them all. What the questions leave open - the details of a light answer, what is left once they are over - is yours to decide, as a careful engineer would, in the light of the intent brief: each decision a spec change of its own, written with `write_spec_diff` with no answer needed before it, and said in one line. Write as many as the product needs. The phase's summary names every decision you made yourself, so the confirmation is where the person can change it.
 
 ## Question style
 
@@ -104,126 +80,60 @@ confirmation is where the person can change it.
 
 ### intent
 
-The harness has asked how many questions the stack and product phases may ask before this phase
-starts; its note beside these instructions gives the answer. Do not ask it again.
+The harness has asked how many questions the stack and product phases may ask before this phase starts; its note beside these instructions gives the answer. Do not ask it again.
 
-Read `references/intent.md` and ask its five core questions one at a time via `ask_user`.
-Ask at most one focused follow-up when an answer is too vague to summarize.
+Read `references/intent.md` and ask its five core questions one at a time via `ask_user`. Ask at most one focused follow-up when an answer is too vague to summarize.
 
-Write nothing to disk in this phase — no project files, no specification files. Keep
-entities, features, technology and testing for the phases that own them.
+Write nothing to disk in this phase — no project files, no specification files. Keep entities, features, technology and testing for the phases that own them.
 
-Summarize the problem, the primary user, the desired outcome, the observable success
-criterion, and the initial boundary with its explicit exclusions. Get explicit confirmation
-of that brief - the bullets passed whole as `ask_user`'s `context`, which the dialog shows above the
-question - and carry it into every later phase.
+Summarize the problem, the primary user, the desired outcome, the observable success criterion, and the initial boundary with its explicit exclusions. Get explicit confirmation of that brief - the bullets passed whole as `ask_user`'s `context`, which the dialog shows above the question - and carry it into every later phase.
 
 This phase ends on the user's confirmation.
 
 ### stack
 
-**This comes before any functionality, so that every spec change in the product phase can be
-built the moment it is written.** A functionality cannot be rendered without knowing the
-language it is written in and the framework its tests use.
+**This comes before any functionality, so that every spec change in the product phase can be built the moment it is written.** A functionality cannot be rendered without knowing the language it is written in and the framework its tests use.
 
-Read `references/stack.md` and walk its topics in order, within the questioning level (see "How
-many questions"): language, frameworks, storage,
-external services, structure and architecture, other constraints, anything else, and last the
-unit tests - generated code needs them from the first functionality onward.
+Read `references/stack.md` and walk its topics in order, within the questioning level (see "How many questions"): language, frameworks, storage, external services, structure and architecture, other constraints, anything else, and last the unit tests - generated code needs them from the first functionality onward.
 
-Offer the standard library's stacks first, those in a language this machine can build now (the stdlib
-rule, in `<plain-rules>`, `<toolchains on this machine>`, and the first section of
-`references/stack.md`): a stack from it is one import, and only what it leaves open -
-storage, external services, other constraints - is asked and written.
+Offer the standard library's stacks first, those in a language this machine can build now (the stdlib rule, in `<plain-rules>`, `<toolchains on this machine>`, and the first section of `references/stack.md`): a stack from it is one import, and only what it leaves open - storage, external services, other constraints - is asked and written.
 
-Create the module structure and frontmatter so there is a `.plain` file to build into, and
-author every requirement into `***implementation reqs***` at the right scope — shared
-requirements into the template, module-specific ones into the module. Write these with the
-ordinary file tools; **nothing is built in this phase**, and `write_spec_diff` is not used here.
+Create the module structure and frontmatter so there is a `.plain` file to build into, and author every requirement into `***implementation reqs***` at the right scope — shared requirements into the template, module-specific ones into the module. Write these with the ordinary file tools; **nothing is built in this phase**, and `write_spec_diff` is not used here.
 
 Write no definitions, no functional specs, no `***test reqs***` and no `***acceptance tests***`.
 
-End the phase with the unit tests: their framework, as a `:UnitTests:` requirement, and the unit
-testing script, which every build needs from the first one on. If turri already finds a
-script - named by `unittests-script:` in `config.turri.yaml` at the project root, or the one
-`run_unittests*.sh` in the root or in `test_scripts/` - keep it. Otherwise write
-`test_scripts/run_unittests_<language>.sh` with the `implement-unit-testing-script` skill, for the
-language and framework just settled. Do not link it from the specs. Without it, every build stops
-before it starts. When this module sits in a project beside another on a different stack - a
-frontend beside a backend, sharing only an imported module - its script is its stack's: name it in
-that stack's `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`) -
-`config.turri.frontend.yaml` for the stack `frontend` - not in `config.turri.yaml`, which is the
-project's and holds what the stacks share. A stack is chosen, never worked out: tell the user to
-choose it with `/stack <stack>` (`--stack <stack>` on the command line) before building this module.
-
-The unit testing script runs the static checks too - the formatter, linter and type checker the stack
-names, which count as the unit tests do; `implement-unit-testing-script` says which for each language.
-There is no separate static checks script.
-
-Run `turri validate` on the module before finishing, so the product phase does not start
-on top of a file that does not parse.
-
-Finish by summarizing the stack, the architecture, the unit testing script and the static checks it runs - marking each
-choice you made without asking - and getting explicit confirmation, with `confirms_phase: true`. The user
-reading the stack back is the check.
+End the phase with the unit tests: their framework, as a `:UnitTests:` requirement, and the unit testing script, which every build needs from the first one on. If turri already finds a script - named by `unittests-script:` in `config.turri.yaml` at the project root, or the one `run_unittests*.sh` in the root or in `test_scripts/` - keep it. Otherwise write `test_scripts/run_unittests_<language>.sh` with the `implement-unit-testing-script` skill, for the language and framework just settled. Do not link it from the specs. Without it, every build stops before it starts. When this module sits in a project beside another on a different stack - a frontend beside a backend, sharing only an imported module - its script is its stack's: name it in that stack's `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`) - `config.turri.frontend.yaml` for the stack `frontend` - not in `config.turri.yaml`, which is the project's and holds what the stacks share. A stack is chosen, never worked out: tell the user to choose it with `/stack <stack>` (`--stack <stack>` on the command line) before building this module.
+
+The unit testing script runs the static checks too - the formatter, linter and type checker the stack names, which count as the unit tests do; `implement-unit-testing-script` says which for each language. There is no separate static checks script.
+
+Run `turri validate` on the module before finishing, so the product phase does not start on top of a file that does not parse.
+
+Finish by summarizing the stack, the architecture, the unit testing script and the static checks it runs - marking each choice you made without asking - and getting explicit confirmation, with `confirms_phase: true`. The user reading the stack back is the check.
 
 ### testing
 
-Read `references/testing.md`. Carry the intent brief and the stack in; ask about neither again. Walk
-its topics in order. Nothing is built yet, and nothing is built in this phase.
+Read `references/testing.md`. Carry the intent brief and the stack in; ask about neither again. Walk its topics in order. Nothing is built yet, and nothing is built in this phase.
 
-First the decision: are there conformance tests at all? Ask it explicitly - even when
-`config.turri.yaml` already says, ask, offering what it says first - and write the answer to
-`config.turri.yaml` as `conformance-tests:` - the chat and every build follow it. A project with
-only a `config.yaml` has it copied to `config.turri.yaml` first; never write `config.yaml`. Off, and the phase is
-done once the user confirms: the product phase's builds then write and run no conformance tests.
+First the decision: are there conformance tests at all? Ask it explicitly - even when `config.turri.yaml` already says, ask, offering what it says first - and write the answer to `config.turri.yaml` as `conformance-tests:` - the chat and every build follow it. A project with only a `config.yaml` has it copied to `config.turri.yaml` first; never write `config.yaml`. Off, and the phase is done once the user confirms: the product phase's builds then write and run no conformance tests.
 
-On: when the stack came from the standard library, import its conformance template
-(`stdlib/<kind>/conformance/<stack>`) and ask only about what it does not settle. Each answer about how the
-tests are written and run becomes a `:ConformanceTests:` requirement in `***test reqs***`, written
-with the ordinary file tools. A change to the test reqs is not a spec
-diff: never use `write_spec_diff` in this phase. Then make sure the project has its conformance
-testing script - `implement-conformance-testing-script` writes it into `test_scripts/` when
-turri finds none - and run `validate` on what you changed. Without both, the first build of
-the product phase stops before it starts.
+On: when the stack came from the standard library, import its conformance template (`stdlib/<kind>/conformance/<stack>`) and ask only about what it does not settle. Each answer about how the tests are written and run becomes a `:ConformanceTests:` requirement in `***test reqs***`, written with the ordinary file tools. A change to the test reqs is not a spec diff: never use `write_spec_diff` in this phase. Then make sure the project has its conformance testing script - `implement-conformance-testing-script` writes it into `test_scripts/` when turri finds none - and run `validate` on what you changed. Without both, the first build of the product phase stops before it starts.
 
-Finish by summarizing the decision, the test reqs and the script, and saying that from the first
-spec change on, every build writes and runs its conformance tests. Get explicit confirmation.
+Finish by summarizing the decision, the test reqs and the script, and saying that from the first spec change on, every build writes and runs its conformance tests. Get explicit confirmation.
 
 ### product
 
-Read `references/product.md`. Carry the intent brief, the stack and the testing decisions in;
-restart none of them. This
-is the whole product interview, walked **feature by feature** - never section by section. Do
-not fill in the definitions first and the functional specs after: that is not this skill.
+Read `references/product.md`. Carry the intent brief, the stack and the testing decisions in; restart none of them. This is the whole product interview, walked **feature by feature** - never section by section. Do not fill in the definitions first and the functional specs after: that is not this skill.
 
-Walk its topics in order, and run this loop while the questioning level allows (see "How many
-questions") - each question as broad as the level says:
+Walk its topics in order, and run this loop while the questioning level allows (see "How many questions") - each question as broad as the level says:
 
-1. **Ask** one question with `ask_user` - about a feature, a step of a flow, a rule; never about
-   a spec section.
+1. **Ask** one question with `ask_user` - about a feature, a step of a flow, a rule; never about a spec section.
 2. The user **answers**.
-3. **Make the spec change** the answer calls for, as one git diff of the `.plain` files - across
-   every section it needs: the concepts it introduces, a policy it states, the functional spec it
-   adds or changes.
-4. **Write it with `write_spec_diff`**, which applies it and starts a render spec diff job for it,
-   whatever it touches. With conformance on, that build also writes and runs the change's
-   conformance tests. An answer that covers several features is a change for each: write them
-   all. Then the changes for what you decide yourself around it, if any.
+3. **Make the spec change** the answer calls for, as one git diff of the `.plain` files - across every section it needs: the concepts it introduces, a policy it states, the functional spec it adds or changes.
+4. **Write it with `write_spec_diff`**, which applies it and starts a render spec diff job for it, whatever it touches. With conformance on, that build also writes and runs the change's conformance tests. An answer that covers several features is a change for each: write them all. Then the changes for what you decide yourself around it, if any.
 5. Move straight on to the next question; never wait for a build.
 
-Every answer, at least one spec change and one render spec diff job, written before the next
-question - at every level. Once the questions are over, write what is left of the product the same
-way - one decision of yours, one spec change - with no answer between. Correct something already
-written with
-a diff and `fixes_earlier`, before the next question. Never change a `.plain` file in this
-phase by any other means than `write_spec_diff`.
-
-Report each build result between questions, in one sentence. Use `drift` when the
-user asks how the builds are going.
-
-Finish by summarizing the concepts and the features in build order, marking what you decided without
-asking, saying what is built and what is still queued, getting explicit confirmation with
-`confirms_phase: true`. The summary is for the person to take in at a glance: a line a feature, a few
-words a concept, each decision you made yourself in a few words - about fifteen lines at most, never
-the specs' wording or every rule; they are in the spec.
+Every answer, at least one spec change and one render spec diff job, written before the next question - at every level. Once the questions are over, write what is left of the product the same way - one decision of yours, one spec change - with no answer between. Correct something already written with a diff and `fixes_earlier`, before the next question. Never change a `.plain` file in this phase by any other means than `write_spec_diff`.
+
+Report each build result between questions, in one sentence. Use `drift` when the user asks how the builds are going.
+
+Finish by summarizing the concepts and the features in build order, marking what you decided without asking, saying what is built and what is still queued, getting explicit confirmation with `confirms_phase: true`. The summary is for the person to take in at a glance: a line a feature, a few words a concept, each decision you made yourself in a few words - about fifteen lines at most, never the specs' wording or every rule; they are in the spec.