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

package/docs/authoring-plain.md

@@ -158,13 +158,15 @@ an agent has to decide to go and read.
 | `import-modules.md`, `requires-modules.md` | the two ways modules build on each other |
 | `exported-concepts.md`, `required-concepts.md` | which concepts cross module boundaries |
 | `integrations.md` (+ standalone, embedded, embedded testing) | specs for REST API integrations, deployed standalone or embedded in an existing codebase |
+| `turri-regeneration.md` | how turri regenerates a spec change - as a spec diff, wherever it sits, in the chain's tip - so a spec is placed by what it means, never to spare regeneration |
 | `stdlib.md` | the standard library: when to import which template, and every template with what it is and where it is, read from `stdlib/` |
 
 The ones that shape a spec most:
 
 - **One functionality is at most ~200 lines of code.** A bigger one is split before it is written
   (`analyze-if-func-spec-too-complex`, `break-down-func-spec`).
-- **Functional specs are in build order.** Each is rendered on top of the ones before it.
+- **Functional specs are in build order.** Each is rendered on top of the ones before it - which is
+  what a spec may assume, not what a change costs: a spec inserted anywhere is regenerated alone.
 - **They state facts, with a concrete subject.** "A :User: can add a :Task:" - not "Implement
   adding tasks", not "The system should…".
 - **Nothing a test cannot check.** No `robust`, `seamless`, `as appropriate`; state the checkable

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/project-model.md

@@ -75,9 +75,11 @@ 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;

package/genome/rules/turri-regeneration.md

@@ -0,0 +1,36 @@
+---
+description: How turri regenerates the code from a spec change - by spec diff, in the chain's tip - so a spec is placed by what it means, never by what regenerating it would cost
+---
+
+# 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 is never decided by a wrong idea of what it costs.
+
+## 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
+
+## So place a spec by what it means
+
+- Put a functional spec where it belongs: in the module that owns the concern, at the point in its
+  order where what it relies on has been said
+- Never put a spec at the end of a module, or in the tip, only to spare regeneration - it spares none
+- What does cost more is asked for outright, never brought on by placement: regenerating a functional
+  spec again, or a module or chain from scratch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.4-next.5a94e68",
+  "version": "0.1.4-next.afc43a8",
   "license": "MIT",
   "type": "module",
   "repository": {