@turri-dev/cli 0.1.3 → 0.1.4-next.01530aa

package/docs/using.md

@@ -50,7 +50,7 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 
 | tool | |
 | --- | --- |
-| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - only when you ask, or agree |
+| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - `"chain"` for every module of its requires chain too, built again from the bottom - only when you ask, or agree |
 | `drift` | what is left to regenerate: how far the code and its conformance tests have drifted from the spec, starting nothing |
 | `glimpse` | the pulse a module's codebases would start next, and the whole prompt its coding agent would get - starting nothing |
 | `steer` | say how the work is planned - which functional specs go together, what first - for the project or one module, for the session; the next plan follows it, beside what AGENTS.md says under a heading naming the queue |
@@ -58,12 +58,12 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 | `validate` | validate a spec, regenerating nothing |
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
-| `halt` | halt a pulse, or what `activate` started |
+| `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
 | `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed |
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
 | `release`, `activate` | try what is regenerated: release it to `dist/<module>` and activate it on this machine, installing what it needs - see [deploy](deploy.md) |
-| `ask_user` | put a question to you as a dialog to pick from - several at once, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
+| `ask_user` | put a question to you as a dialog to pick from - several at once, each a box you tick and untick, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
 | `web_search`, `web_fetch` | search the web and read a page as text - documentation, an API, an error; `curl` and the like run in its `bash` |
 
 What each render does, in order, is in [regenerating the code](regenerating.md).
@@ -217,11 +217,10 @@ come waits for a free slot, and says so.
   closes when it moves to another section. What is open is kept while the panel is closed. What the agents
   said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
 
-  `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, a click decides which side has
-  the keys - the chat or the panel, the one clicked, or the one `⌥⌘←` / `⌥⌘→` points at (on a
-  terminal that passes ⌘ on, over the Kitty keyboard protocol - Ghostty, kitty, WezTerm, iTerm2; not Apple's Terminal);
-  the other is drawn faint - and `esc` gives the chat the keys too, the panel staying and
-  following the pulses; `ctrl+h` gives the panel the keys again, and from the panel closes it. (pi's regular screen,
+  `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, one side has the keys and the
+  other is drawn faint: `ctrl+h` switches sides - from the chat to the panel, from the panel to the chat, the panel
+  staying and following the pulses - `esc` gives the chat the keys too, and a click gives them to the side clicked.
+  `ctrl+c` closes the panel; so do `s`, over the whole screen, then `esc`. (pi's regular screen,
   `--tui-mode regular`, reads no mouse: there it is the keys alone.)
   While the panel has the keys, every key is the panel's,
   whatever else happens: a question the chat model asks in the background (`ask_user`) waits in the chat,
@@ -238,7 +237,7 @@ come waits for a free slot, and says so.
   is laid over `config.turri.yaml` - its testing scripts, toolchains, models - for the session; a pulse already
   running keeps the stack it started with. The chat model switches it too when you ask. See
   [stacks](config.md#stacks).
-- **`/regenerate [module | file.plain] [functionality ...] [from scratch] [how to cut the work]`** regenerates a module from its spec as it is now, as
+- **`/regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its spec as it is now, as
   the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few
   together or the whole module in one, as the planner judges - and the first starts. Words after the module are
   guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is
@@ -246,13 +245,19 @@ come waits for a free slot, and says so.
   `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`,
   `start over`, `delete the module` - it asks first, then deletes the module's code and conformance tests in every
   codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its spec,
-  built though nothing in it changed: `/regenerate shorty from scratch`. The chat's `regenerate` does the same with
-  `from_scratch`, when you ask for it; `turri regenerate --from-scratch` on the command line, not with `--dry-run`.
+  built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and
+  the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch,
+  the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole
+  chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was
+  laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or
+  `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not
+  with `--dry-run`.
   Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their spec did not
   change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's
   `regenerate` with `functionalities`.
-- **`/halt <id>`** halts a pulse - a queued one never starts - and **`/halt activated <name>`** halts a
-  server `activate` started; it lists both when no id is given.
+- **`/halt <id>`** halts a pulse - a queued one never starts - **`/halt <module>`** (or a planned row's id) halts a
+  module's planned pulses until you ask for it again, a spec change not starting it, and **`/halt activated <name>`**
+  halts a server `activate` started; it lists all three when no id is given.
 - **What these commands show you, the chat knows.** What `/regenerate` and `/halt activated` tell you - a spec that
   does not parse, the pulses planned, a server halted - stays in the chat under the command, and since a slash command
   runs outside the conversation, it is put in the conversation as well: say "fix it" next and turri knows what you are
@@ -389,7 +394,15 @@ To change pi's own default, in `~/.pi/agent/settings.json`:
 ```
 
 A provider failure - no credits, bad key, rate limit - is raised with the provider's own message,
-rather than surfacing as an agent that said nothing.
+rather than surfacing as an agent that said nothing. One that passes - overloaded, rate limited, unreachable,
+timed out - is waited out first, after pi's own retries: six more tries, the wait doubled each time from 15
+seconds up to five minutes (15s, 30s, 1m, 2m, 4m, 5m, a tenth either way so parallel jobs do not all come back
+at once), the agent carrying on where it was. Each wait - pi's own retries too - is shown as it happens - a
+notification in the chat and the job panel's status, a yellow line in a headless run - and listed in the run
+report's `turn_incidents`. So is a provider stalling: a request to the model that nothing has come back on for two
+minutes (`TURRI_PROVIDER_STALL`, in seconds; 0 never), said once for each silence while the turn goes on waiting.
+A turn turri stops itself - its time up, the agent going round in a circle - is the work's normal course and is not
+said, only listed.
 
 ## Module history
 
@@ -452,6 +465,7 @@ turri regenerate <file.plain>              # regenerate what the code is not bui
 turri glimpse <file.plain>             # plan it, and print the first job's prompt - starts nothing
 turri regenerate <file.plain> 2            # regenerate functionality 2 again, changed or not
 turri regenerate <file.plain> --from-scratch   # delete the module's code and tests (its lineage keeps them), regenerate all of it
+turri regenerate <file.plain> --from-scratch-chain   # the same for every module of its requires chain, from the bottom
 turri spec-diff <file.plain> <diff>    # apply a spec diff, and regenerate it
 turri conform <file.plain> 1           # black-box tests for functionality 1
 turri lineage <module>                 # what each regeneration changed in a module, and when

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,76 @@
+---
+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/refactor-module/SKILL.md

@@ -21,6 +21,8 @@ allowed-tools: [read, write, edit, bash, ls, grep, find]
 
 The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
 
+The spec is structural; the code is not. Once modules are split and specs move between them, the code already built no longer matches the module layout: specs move into modules the code was never built on, and no change to that code brings them in. **After a refactor, the whole requires chain is regenerated from scratch** — the existing code and conformance tests are taken out (their lineage keeps them) and every module is built again from the base of the chain upward. Say so up front: it is part of what the user agrees to (Phase 2e), and it is the last step of the skill (Phase 5).
+
 ## Input
 
 The `.plain` file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).
@@ -90,8 +92,9 @@ Summarize for the user:
 - Any new import module being created
 - Which concepts are exported from each module
 - Confirmation that all original specs are accounted for (none lost)
+- That the whole chain will be **regenerated from scratch** once the split is done: the code and conformance tests built so far are taken out (kept in the lineage) and everything is built again from the base module up — this takes as long and costs as much as building the original module did
 
-Get explicit user confirmation before proceeding.
+Get explicit user confirmation before proceeding — of the split and of regenerating from scratch.
 
 ## Phase 3 — Execute the Split
 
@@ -162,6 +165,19 @@ For each new module:
 
 Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
 
+Validate each new module with `turri validate <module>.plain` (or the `validate` tool) before going on: a module that does not parse cannot be regenerated.
+
+## Phase 5 — Regenerate the Chain from Scratch
+
+The split moves specs between modules, so the code built from the original module cannot be patched into the new layout: the chain is regenerated from scratch. Do not try to keep or reuse the existing code, and do not regenerate only what looks changed — modules have moved, and a codebase built without a module it now requires has to be started over anyway.
+
+1. **Remind the user** what regenerating from scratch does — the code and conformance tests built so far are taken out, committed so the lineage keeps them, and the whole chain is built again from the base up — and that they already agreed to it in Phase 2e. Proceed only on that agreement.
+2. **Regenerate the tip of the chain from scratch, with its whole chain** — the last module, the one everything else is required by. From scratch for the tip alone is not enough: the modules below keep their code, and the tip starts from a copy of it, laid out for the old modules. With the whole chain, every module's code is taken out, the base's included, and the chain is built again from the bottom:
+   - in the chat: the `regenerate` tool on the tip's `.plain` file with `from_scratch: "chain"`, or `/regenerate <tip> from scratch, the whole chain`;
+   - on the command line: `turri regenerate <tip>.plain --from-scratch-chain`.
+3. **Modules that require the chain** (updated in 3d) are regenerated after it, from scratch too (`from_scratch: "module"`): the modules they require are not the ones their code was built on. When the tip's whole chain is regenerated, a module built on top of it is a chain of its own — regenerating it from scratch with its whole chain instead covers the tip's chain too, in one go.
+4. **The original module's codebase** (`plain_modules/<original-module>/`), when the original module was deleted or renamed, is no longer built from anything. Tell the user it is there; it is theirs to delete. Do not delete it unasked.
+
 ## Common Pitfalls
 
 ### Splitting too aggressively
@@ -179,9 +195,12 @@ This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a sp
 ### Losing acceptance tests
 Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
 
+### Regenerating only what changed
+After a split the existing code was built for a module layout that no longer exists. Regenerating incrementally either stops at a codebase that has to be started over or builds on code laid out for the old modules. Regenerate the whole chain from scratch.
+
 ## Validation Checklist
 
-- [ ] User confirmed the split plan before execution
+- [ ] User confirmed the split plan before execution, including regenerating the whole chain from scratch
 - [ ] All original functional specs are present in exactly one new module — none lost
 - [ ] Spec text is identical to the original — no rewording
 - [ ] Acceptance tests moved with their parent specs
@@ -194,3 +213,6 @@ Acceptance tests are nested under their parent functional spec. When moving a sp
 - [ ] Original module removed or updated
 - [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
 - [ ] User approved the final result
+- [ ] Every new module validates
+- [ ] The tip of the chain regenerated from scratch with its whole chain, then any module that requires it
+- [ ] User told about the original module's leftover codebase, if there is one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3",
+  "version": "0.1.4-next.01530aa",
   "license": "MIT",
   "type": "module",
   "repository": {