@turri-dev/cli 0.1.4-next.afc43a8 → 0.1.4-next.d6e59a8

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.

package/genome/skills/brood/references/intent.md

@@ -1,11 +1,8 @@
 # the intent phase — What is the intent?
 
-Extract the user's intent before creating files or decomposing the product into specifications.
-Keep this phase short. Ask exactly five core questions, one at a time, and do not write to disk.
+Extract the user's intent before creating files or decomposing the product into specifications. Keep this phase short. Ask exactly five core questions, one at a time, and do not write to disk.
 
-The harness has already asked the first question of this phase: how many questions the stack and
-product phases may ask - light (3), medium (5), thorough (10) or best judgement. Do not ask it
-again; this phase's own questions are not capped by it.
+The harness has already asked the first question of this phase: how many questions the stack and product phases may ask - light (3), medium (5), thorough (10) or best judgement. Do not ask it again; this phase's own questions are not capped by it.
 
 ## Questions
 
@@ -15,8 +12,7 @@ again; this phase's own questions are not capped by it.
 4. **Success criterion** — What observable result would make the first version useful?
 5. **Initial boundary** — What should the first version deliberately leave out?
 
-Ask one focused follow-up only when an answer is too vague to summarize. Do not explore features,
-entities, technology, architecture, or testing yet; those belong to later phases.
+Ask one focused follow-up only when an answer is too vague to summarize. Do not explore features, entities, technology, architecture, or testing yet; those belong to later phases.
 
 ## Intent brief
 
@@ -28,8 +24,4 @@ Summarize the answers in five short bullets:
 - Observable success criterion
 - Initial boundary and explicit exclusions
 
-Ask the user to confirm or correct the brief with one `ask_user` question, the five bullets passed whole as its
-`context` - the dialog shows only the question, its options and its `context`. The intent phase finishes only after
-explicit confirmation.
-Carry the confirmed brief into the stack and product phases so their questions refine it instead of restarting intent
-discovery.
+Ask the user to confirm or correct the brief with one `ask_user` question, the five bullets passed whole as its `context` - the dialog shows only the question, its options and its `context`. The intent phase finishes only after explicit confirmation. Carry the confirmed brief into the stack and product phases so their questions refine it instead of restarting intent discovery.

package/genome/skills/brood/references/product.md

@@ -1,101 +1,49 @@
 # the product phase — What does it do?
 
-The whole product interview, in one phase, walked **feature by feature** - not section by
-section. There is no pass that fills in the definitions and then another that writes the
-functional specs. Each question is about the product: a feature, a step in a flow, a rule.
-Its answer becomes one spec change that touches whatever sections that answer needs - the
-concepts the feature introduces, a policy it needs, its functional spec - and every spec change
-is built the moment it is written.
+The whole product interview, in one phase, walked **feature by feature** - not section by section. There is no pass that fills in the definitions and then another that writes the functional specs. Each question is about the product: a feature, a step in a flow, a rule. Its answer becomes one spec change that touches whatever sections that answer needs - the concepts the feature introduces, a policy it needs, its functional spec - and every spec change is built the moment it is written.
 
 Carry the confirmed intent brief and the settled stack in. Do not restart either.
 
 ## How many questions
 
-The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best
-judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level walks
-all the topics below: light in a few broad questions - the features and their order in one, what
-they do end to end in another, with what fits the brief proposed for the person to confirm or
-correct; thorough in narrow ones, a feature, rule or edge case each. The level limits the
-questions, never the spec changes:
-
-- **Every answer is a spec change**, at every level: written with `write_spec_diff` and built at
-  once, before the next question - `ask_user` refuses the next question until it is. A broad
-  answer covering several features is a change for each.
-- **What the questions leave open is yours** - the details under a broad answer, and everything
-  still open once the questions are over (the cap reached, or `end_questions` called). Each
-  feature, edge case and rule you decide is its own spec change, written with `write_spec_diff`
-  with no answer needed before it, and said in one line. Write as many as the product needs.
-  Decide from the intent brief and the answers so far; leave out what they do not call for rather
-  than invent scope.
+The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level walks all the topics below: light in a few broad questions - the features and their order in one, what they do end to end in another, with what fits the brief proposed for the person to confirm or correct; thorough in narrow ones, a feature, rule or edge case each. The level limits the questions, never the spec changes:
+
+- **Every answer is a spec change**, at every level: written with `write_spec_diff` and built at once, before the next question - `ask_user` refuses the next question until it is. A broad answer covering several features is a change for each.
+- **What the questions leave open is yours** - the details under a broad answer, and everything still open once the questions are over (the cap reached, or `end_questions` called). Each feature, edge case and rule you decide is its own spec change, written with `write_spec_diff` with no answer needed before it, and said in one line. Write as many as the product needs. Decide from the intent brief and the answers so far; leave out what they do not call for rather than invent scope.
 
 ## One question, one answer, a spec change, a render
 
 Every iteration is exactly this, at every questioning level:
 
-1. **Ask one question** with `ask_user`, about the product: a feature, its trigger and outcome,
-   one of its edge cases or rules, the next step of a flow - as broad as the level says. Never bundle two, and never ask about
-   a spec section ("what concepts are there?", "what reqs apply?") - ask about what the product
-   does, and let the answer decide which sections change.
+1. **Ask one question** with `ask_user`, about the product: a feature, its trigger and outcome, one of its edge cases or rules, the next step of a flow - as broad as the level says. Never bundle two, and never ask about a spec section ("what concepts are there?", "what reqs apply?") - ask about what the product does, and let the answer decide which sections change.
 2. **Turn the answer into a spec change** - one for each feature it covers - everything it calls for, across sections:
-   - a concept the feature introduces, into `***definitions***`, following `add-concept`, defined
-     in the same change as the functional spec that first uses it;
+   - a concept the feature introduces, into `***definitions***`, following `add-concept`, defined in the same change as the functional spec that first uses it;
    - a technology-free policy the answer states, into `***implementation reqs***`;
-   - the functional spec for the feature, or the change to one already written, following
-     `add-functional-spec`.
-   Write it as a git diff of the `.plain` file(s): `diff --git a/<file> b/<file>`,
-   `--- a/<file>`, `+++ b/<file>`, then the hunks with a few lines of unchanged context. Paths
-   are relative to the project root.
-3. **Write it with `write_spec_diff`.** It applies the diff and starts a render spec diff job for
-   it in the same call - whatever the change touches, a definition alone included. Write every
-   change the answer calls for before the next question - `ask_user` refuses it until then - and
-   any you decide yourself beside them. Move straight on to the next question; never wait for a
-   build.
-
-**One answer, at least one change.** A follow-up about the same feature - an edge case, a
-validation rule - is its own answer and its own change to that feature's spec. An answer that
-describes two features is two changes, both written before the next question. A change never
-carries both an answer and something you decided: what you decide is a change of its own.
-
-**Fix contradictions in place.** When a later answer refines or contradicts something already
-written, write the correction as its own diff with `fixes_earlier` set, before the next
-question. It is rendered like any other change.
-
-**Never edit the `.plain` files with `write` or `edit` in this phase.** A change that does not
-go through `write_spec_diff` is a change nothing renders.
+   - the functional spec for the feature, or the change to one already written, following `add-functional-spec`. Write it as a git diff of the `.plain` file(s): `diff --git a/<file> b/<file>`, `--- a/<file>`, `+++ b/<file>`, then the hunks with a few lines of unchanged context. Paths are relative to the project root.
+3. **Write it with `write_spec_diff`.** It applies the diff and starts a render spec diff job for it in the same call - whatever the change touches, a definition alone included. Write every change the answer calls for before the next question - `ask_user` refuses it until then - and any you decide yourself beside them. Move straight on to the next question; never wait for a build.
+
+**One answer, at least one change.** A follow-up about the same feature - an edge case, a validation rule - is its own answer and its own change to that feature's spec. An answer that describes two features is two changes, both written before the next question. A change never carries both an answer and something you decided: what you decide is a change of its own.
+
+**Fix contradictions in place.** When a later answer refines or contradicts something already written, write the correction as its own diff with `fixes_earlier` set, before the next question. It is rendered like any other change.
+
+**Never edit the `.plain` files with `write` or `edit` in this phase.** A change that does not go through `write_spec_diff` is a change nothing renders.
 
 ## What a change may contain
 
-- **`***definitions***`** - the concepts the change needs, each defined before, or in the same
-  change as, what first uses it.
-- **`***functional specs***`** - at most one new functionality per change: ≤200 lines of code
-  change, language-agnostic, in chronological build order, externally explicit where it has an
-  interface.
-- **`***implementation reqs***`** - only technology-free policy: an error-handling or retry
-  policy, an ordering guarantee, a data-format rule. The technology was settled in the stack
-  phase; an answer that needs a new technology is a stack answer - note it and steer back.
+- **`***definitions***`** - the concepts the change needs, each defined before, or in the same change as, what first uses it.
+- **`***functional specs***`** - at most one new functionality per change: ≤200 lines of code change, language-agnostic, in chronological build order, externally explicit where it has an interface.
+- **`***implementation reqs***`** - only technology-free policy: an error-handling or retry policy, an ordering guarantee, a data-format rule. The technology was settled in the stack phase; an answer that needs a new technology is a stack answer - note it and steer back.
 
-Leave the `***test reqs***` as the testing phase wrote them, and write no `***acceptance tests***`.
-With conformance on, every change is built with its conformance tests - from the test reqs as they
-stand.
+Leave the `***test reqs***` as the testing phase wrote them, and write no `***acceptance tests***`. With conformance on, every change is built with its conformance tests - from the test reqs as they stand.
 
 ## Topics (in order)
 
-1. **Product description** - propose a one-sentence description from the confirmed intent brief,
-   state it back in one line, and write it into the frontmatter as the first change.
-2. **Features, one at a time, in build order** - the smallest thing that is useful first, then
-   what builds on it. For each feature: one question for what triggers it and what comes out,
-   then one per edge case, validation rule or permission that is not obvious. Each answer is a
-   change: the first brings the feature's concepts and its functional spec; the follow-ups refine
-   them. A feature too large for one functional spec is split *with the user* - that is the next
-   question.
-3. **User flows** - walk the product from the user's side: what happens first, what next, and at
-   each decision point. Each missing step is a feature, taken the same way.
-4. **User interface (optional)** - skip entirely if there is none. Otherwise per screen or
-   interaction: what the user sees and what it does, still language- and framework-agnostic.
+1. **Product description** - propose a one-sentence description from the confirmed intent brief, state it back in one line, and write it into the frontmatter as the first change.
+2. **Features, one at a time, in build order** - the smallest thing that is useful first, then what builds on it. For each feature: one question for what triggers it and what comes out, then one per edge case, validation rule or permission that is not obvious. Each answer is a change: the first brings the feature's concepts and its functional spec; the follow-ups refine them. A feature too large for one functional spec is split *with the user* - that is the next question.
+3. **User flows** - walk the product from the user's side: what happens first, what next, and at each decision point. Each missing step is a feature, taken the same way.
+4. **User interface (optional)** - skip entirely if there is none. Otherwise per screen or interaction: what the user sees and what it does, still language- and framework-agnostic.
 5. **Anything else** - anything the user wants to add or change that has not been covered.
 
 ## Reporting builds
 
-Report each build result between questions, in one sentence. A failed build does not stop the
-interview - note it and carry on, unless it shows the spec itself is wrong, in which case fix
-the spec with a diff and `fixes_earlier`.
+Report each build result between questions, in one sentence. A failed build does not stop the interview - note it and carry on, unless it shows the spec itself is wrong, in which case fix the spec with a diff and `fixes_earlier`.

package/genome/skills/brood/references/stack.md

@@ -2,14 +2,7 @@
 
 Gather the technical stack **and** the project's structure/architecture. This phase affects only `***implementation reqs***`, and ends with the unit testing script every build needs — the rest of testing comes later. Run the core loop from `SKILL.md` for each topic below, in order: ask, then write the requirement into the `.plain` file with the ordinary file tools. Nothing is built in this phase. When the user has no preference, propose a sensible default that fits earlier answers and ask them to confirm.
 
-The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best
-judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level reaches
-all the topics, in order: light in a few broad questions - the stack, say, then storage and
-outside services together, then the remaining constraints, each with what fits the brief
-proposed; thorough a topic or two a question, with follow-ups. Every topic left unasked once the
-questions are over gets the default that fits the intent brief and the answers so far, written as a
-requirement like any other and named as your choice in the closing summary. The unit testing script
-is written whatever the level.
+The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level reaches all the topics, in order: light in a few broad questions - the stack, say, then storage and outside services together, then the remaining constraints, each with what fits the brief proposed; thorough a topic or two a question, with follow-ups. Every topic left unasked once the questions are over gets the default that fits the intent brief and the answers so far, written as a requirement like any other and named as your choice in the closing summary. The unit testing script is written whatever the level.
 
 ## Author target for this phase
 
@@ -22,27 +15,12 @@ Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — t
 
 ## First: a stack from the standard library
 
-Before the topics, settle what kind of software each module is - a backend, a frontend, a
-command-line tool, a library - and offer the standard library's stacks for that kind (the stdlib
-rule, in `<plain-rules>`, lists them) that this machine can build: `<toolchains on this machine>`, in
-your instructions, says which languages it can build now. The agents use its toolchains and install
-none, so a stack in a language it lacks stops at its first build. Ask with `ask_user`: those stacks
-as options, the one that fits earlier answers first, and "Something else…" for a stack of the user's
-own. A stack the user names in a language the machine lacks: say what to install first and that
-`turri doctor` checks it, and ask whether to wait for that or choose another.
-
-- **A stack from the standard library.** Import it into the module's frontmatter as
-  `stdlib/<kind>/<stack>`, and read the templates it brings: the stack, its `stdlib/lang/<language>`
-  and its kind's `common` - the folder is in the stdlib rule. They settle topics 1, 2 and 5, error handling and
-  logging in topic 6, and the unit-test framework in topic 8: do not ask about those, and write no
-  requirement that restates them. Say in one line what the stack settles - its language, framework,
-  layout, how it reports errors and logs - so the user knows what they chose. Then walk only topics
-  3, 4, 6 (what the stack leaves open), 7, and the unit testing script in 8.
-- **Something else.** Walk every topic below. When the language is one the standard library has, its
-  `stdlib/lang/<language>` template can still be imported for the language-wide conventions.
-
-A user who wants something the stack settles done differently - another framework, another layout -
-has chosen something else: an import cannot be taken back in part.
+Before the topics, settle what kind of software each module is - a backend, a frontend, a command-line tool, a library - and offer the standard library's stacks for that kind (the stdlib rule, in `<plain-rules>`, lists them) that this machine can build: `<toolchains on this machine>`, in your instructions, says which languages it can build now. The agents use its toolchains and install none, so a stack in a language it lacks stops at its first build. Ask with `ask_user`: those stacks as options, the one that fits earlier answers first, and "Something else…" for a stack of the user's own. A stack the user names in a language the machine lacks: say what to install first and that `turri doctor` checks it, and ask whether to wait for that or choose another.
+
+- **A stack from the standard library.** Import it into the module's frontmatter as `stdlib/<kind>/<stack>`, and read the templates it brings: the stack, its `stdlib/lang/<language>` and its kind's `common` - the folder is in the stdlib rule. They settle topics 1, 2 and 5, error handling and logging in topic 6, and the unit-test framework in topic 8: do not ask about those, and write no requirement that restates them. Say in one line what the stack settles - its language, framework, layout, how it reports errors and logs - so the user knows what they chose. Then walk only topics 3, 4, 6 (what the stack leaves open), 7, and the unit testing script in 8.
+- **Something else.** Walk every topic below. When the language is one the standard library has, its `stdlib/lang/<language>` template can still be imported for the language-wide conventions.
+
+A user who wants something the stack settles done differently - another framework, another layout - has chosen something else: an import cannot be taken back in part.
 
 ## Topics (in order)
 

package/genome/skills/brood/references/testing.md

@@ -1,56 +1,25 @@
 # the testing phase — How is what was built checked from the outside?
 
-Decide whether the project has conformance tests, and if it does, say in `***test reqs***` how they
-are written and run, and give it the script that runs them. This comes before the product phase, and
-nothing here is built: a change to the test reqs is not a spec diff, so it is written with the
-ordinary file tools, never `write_spec_diff`. What is settled here is what every build of the
-product phase follows - with conformance on, each spec change is built with its conformance tests.
-Run the core loop for each topic below, in order: ask, then write. When the user has no preference,
-propose a default that fits the stack and the intent brief and ask them to confirm.
-
-Conformance tests are black-box tests written from the spec: for each functional spec, tests that
-run the built software from the outside - as a command, over HTTP, through its public entry point -
-and check it does what the spec says, kept apart from the spec's acceptance tests. The harness runs
-the whole suite after every spec change, so they catch one change breaking another. They cost time
-and tokens on every build.
+Decide whether the project has conformance tests, and if it does, say in `***test reqs***` how they are written and run, and give it the script that runs them. This comes before the product phase, and nothing here is built: a change to the test reqs is not a spec diff, so it is written with the ordinary file tools, never `write_spec_diff`. What is settled here is what every build of the product phase follows - with conformance on, each spec change is built with its conformance tests. Run the core loop for each topic below, in order: ask, then write. When the user has no preference, propose a default that fits the stack and the intent brief and ask them to confirm.
+
+Conformance tests are black-box tests written from the spec: for each functional spec, tests that run the built software from the outside - as a command, over HTTP, through its public entry point - and check it does what the spec says, kept apart from the spec's acceptance tests. The harness runs the whole suite after every spec change, so they catch one change breaking another. They cost time and tokens on every build.
 
 ## Author target for this phase
 
-- `***test reqs***` - one `:ConformanceTests:` requirement per fact, on the template if one exists
-  (shared by every module), otherwise on the module. Follow `genome/rules/test-reqs.md`.
-- `config.turri.yaml` at the project root - the `conformance-tests:` decision. Change only that key, and
-  create the file if there is none; everything else in it stays as it is. When the project has only a
-  `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to
-  `config.turri.<name>.yaml` - and write the copy: `config.yaml` may be another tool's, and is never
-  written.
+- `***test reqs***` - one `:ConformanceTests:` requirement per fact, on the template if one exists (shared by every module), otherwise on the module. Follow `genome/rules/test-reqs.md`.
+- `config.turri.yaml` at the project root - the `conformance-tests:` decision. Change only that key, and create the file if there is none; everything else in it stays as it is. When the project has only a `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to `config.turri.<name>.yaml` - and write the copy: `config.yaml` may be another tool's, and is never written.
 - `test_scripts/` - the conformance testing script.
 
 Write no `***acceptance tests***`, no functional specs and no `***implementation reqs***` here.
 
 ## Topics (in order)
 
-1. **Conformance on or off** - ask it explicitly, with what it costs and what it catches; it is a
-   recorded decision, never an inference. Ask it even when `config.turri.yaml` already has
-   `conformance-tests:` - offer what it says as the first option. Write it to `config.turri.yaml` as `conformance-tests: true` or
-   `conformance-tests: false`. Off: say that no conformance tests will be written or run until it
-   is turned on, and go to the end of the phase.
-2. **Framework** - e.g. pytest, JUnit, Jest, Go's `testing`; one that fits the stack. Author it as a
-   `:ConformanceTests:` requirement.
-3. **How the tests reach the software** - as a subprocess of the CLI, over HTTP against a server the
-   tests start, through the public entry point it exports. Author it.
-4. **Setup and outside services** - fixtures, test data, databases, third-party APIs: started for
-   real, faked, or mocked at the boundary. Author each decision as its own requirement.
+1. **Conformance on or off** - ask it explicitly, with what it costs and what it catches; it is a recorded decision, never an inference. Ask it even when `config.turri.yaml` already has `conformance-tests:` - offer what it says as the first option. Write it to `config.turri.yaml` as `conformance-tests: true` or `conformance-tests: false`. Off: say that no conformance tests will be written or run until it is turned on, and go to the end of the phase.
+2. **Framework** - e.g. pytest, JUnit, Jest, Go's `testing`; one that fits the stack. Author it as a `:ConformanceTests:` requirement.
+3. **How the tests reach the software** - as a subprocess of the CLI, over HTTP against a server the tests start, through the public entry point it exports. Author it.
+4. **Setup and outside services** - fixtures, test data, databases, third-party APIs: started for real, faked, or mocked at the boundary. Author each decision as its own requirement.
 5. **How the whole suite is run** - the one command that discovers every test. Author it.
-6. **The conformance testing script** - if turri already finds one (named by
-   `conformance-tests-script:` in `config.turri.yaml`, or the one `run_conformance_tests*.sh` in the
-   project root or in `test_scripts/`), check it runs the suite the way the test reqs now say, and
-   keep it. Otherwise write `test_scripts/run_conformance_tests_<language>.sh` with
-   `implement-conformance-testing-script`, to match the test reqs. Never link it from the specs.
-   If `test_scripts/` would hold two of a kind, name the one to use in `config.turri.yaml`. In a
-   project whose parts are on different stacks, name each stack's script in its own
-   `config.turri.<stack>.yaml` (`conformance-tests-script:`), and tell the user to choose the stack
-   with `/stack <stack>` (`--stack <stack>` on the command line) before building that part.
+6. **The conformance testing script** - if turri already finds one (named by `conformance-tests-script:` in `config.turri.yaml`, or the one `run_conformance_tests*.sh` in the project root or in `test_scripts/`), check it runs the suite the way the test reqs now say, and keep it. Otherwise write `test_scripts/run_conformance_tests_<language>.sh` with `implement-conformance-testing-script`, to match the test reqs. Never link it from the specs. If `test_scripts/` would hold two of a kind, name the one to use in `config.turri.yaml`. In a project whose parts are on different stacks, name each stack's script in its own `config.turri.<stack>.yaml` (`conformance-tests-script:`), and tell the user to choose the stack with `/stack <stack>` (`--stack <stack>` on the command line) before building that part.
 7. **Anything else** - anything about testing the user wants to add or change.
 
-Run `validate` on every module you changed. The product phase's first build needs the test reqs
-and the conformance testing script both there: without them it stops before it starts.
+Run `validate` on every module you changed. The product phase's first build needs the test reqs and the conformance testing script both there: without them it stops before it starts.