@turri-dev/cli 0.1.3-next.26f08c5 → 0.1.3-next.420ce7e

package/genome/skills/bud/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: bud
 description: >-
-  Add a feature to an existing ***plain project the way `brood` builds one: a short
-  feature-intent interview, then product questions one at a time - a trigger and its outcome, an
-  edge case, a rule - where every answer becomes one spec change, written as a git diff of the
+  Add a feature to an existing ***plain project the way `brood` builds one: it first asks how many
+  questions the product phase may ask - light, medium, thorough or best judgement, broader with
+  fewer - then a short feature-intent interview, then product questions - a trigger and its outcome,
+  an edge case, a rule - where every answer becomes a spec change, written as a git diff of the
   .plain files and built the moment it is written, so the feature appears while the interview is
-  still going. A change that touches what is already specified or being built is a spec diff too: what
+  still going. What the questions leave open it decides itself, each decision a spec change of its
+  own. A change that touches what is already specified or being built is a spec diff too: what
   is left to build is worked out again from the spec. Use when the user wants to add a
   feature to an existing project. Not for starting a new project (use `brood`, or `spawn`
   to start fast) or for editing generated code (the .plain specs are the source of truth).
@@ -16,7 +18,12 @@ metadata:
     intent: "what the feature is for, who it serves, and what it leaves out"
     scope: "finds where the feature goes in the spec, and what is built already"
     product: "the feature, question by question - each answer starts a regenerate pulse"
-    review: "checks the changed spec holds together, then hands over"
+  # The phase the questioning level caps, asked by the harness as the first question: light 3,
+  # medium 5, thorough 10, best judgement as many as turri judges the phase needs.
+  questioning: [product]
+  # Every answer in the product phase is a spec change: the next question waits until it is
+  # written with write_spec_diff. Changes turri decides itself need no answer before them.
+  spec-diff-per-answer: [product]
 ---
 
 # Bud
@@ -37,10 +44,36 @@ the spec."
 This is `brood`'s product phase, scoped to one feature, on top of what is there: the stack,
 the testing setup and every earlier feature are settled - read them, build on them, restart none.
 
+## How many questions
+
+The first question of the intent phase is the harness's own, not yours: how many questions the
+**product** phase may ask. The level sets how many questions there are and so how broad each is -
+never what they cover:
+
+| level | product questions | each question |
+| --- | --- | --- |
+| light | at most 3 | broad: the whole feature at once - what it does end to end, its main rules - with what fits the brief proposed, for the person to confirm or correct |
+| medium | at most 5 | one part of the feature, with its main rules |
+| thorough | at most 10 | narrow: one trigger, rule or edge case, with follow-ups on the ones that matter |
+| best judgement | as many as you judge the feature needs | as broad or as narrow as each part needs |
+
+The intent phase is not capped. Follow-ups count; the closing confirmation - asked with
+`confirms_phase: true` - does not. Past the cap `ask_user` refuses the question. To stop sooner, or
+under best judgement once the feature is settled enough to build, call `end_questions`.
+
+The level limits the questions, never the spec changes. **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 behaviours is several changes,
+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 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. The closing summary names every decision you made yourself, so the
+confirmation is where the person can change it.
+
 ## Question style
 
-- Ask with `ask_user`, one question per call, and pass `options` so the user picks rather than
-  types - concrete choices, plus the free-form catch-all the tool adds. Reserve `free_form: true`
+- Ask with `ask_user`, one question per call, as broad as the level says, and pass `options` so
+  the user picks rather than types - concrete choices, plus the free-form catch-all the tool adds. Reserve `free_form: true`
   for a genuinely open question.
 - Ask about the product - a trigger and its outcome, an edge case, a rule, a permission, a step of
   a flow - never about a spec section ("which concepts?", "what reqs?"). Let the answer decide which
@@ -55,6 +88,9 @@ the testing setup and every earlier feature are settled - read them, build on th
 
 ### intent
 
+The harness has asked how many questions the product phase 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 with `ask_user`. Ask at
 most one focused follow-up when an answer is too vague to summarize. If what the user has already
 said answers a question, confirm it in one line instead of asking.
@@ -81,8 +117,8 @@ Say in one line where the feature goes, and move on. Write nothing to disk.
 
 ### product
 
-The feature, walked question by question. Run this loop until the user says the feature is fully
-covered:
+The feature, walked question by question. Run this loop while the questioning level allows (see
+"How many questions"):
 
 1. **Ask** one product question with `ask_user`.
 2. The user **answers**.
@@ -106,14 +142,17 @@ covered:
    Write it as a git diff: `diff --git a/<file> b/<file>`, `--- a/<file>`, `+++ b/<file>`, then the
    hunks with a few lines of unchanged context, paths from the project root. A new functional spec
    goes where it belongs in build order - after what it builds on, usually at the end.
-4. **Write it with `write_spec_diff`.** It applies the diff and queues a render spec diff job for
-   it; with conformance on, its conformance tests follow it. Say in one line what went into the
-   spec - "added `:Note:` and functional spec 7" - and what became of the build, as the tool says,
-   then ask the next question. Never wait for a build, and never ask the user to approve a change.
-
-**One answer, one change.** A follow-up about the same behavior - an edge case, a validation rule -
-is its own answer and its own change. An answer that describes two behaviors is two: write the
-first, then ask about the second. A change never carries anything the user was not asked about.
+4. **Write it with `write_spec_diff` at once**, before anything else. It applies the diff and starts
+   a render spec diff job for it; with conformance on, its conformance tests follow it. An answer
+   that covers several behaviours is a change for each: write them all. Then the changes for what
+   you decide yourself around it, if any. Say in one line what went into the spec - "added `:Note:`
+   and functional spec 7" - and what became of the build, as the tool says, then ask the next
+   question. Never wait for a build, and never ask the user to approve a change.
+
+**One answer, at least one change.** A follow-up about the same behaviour - an edge case, a
+validation rule - is its own answer and its own change. An answer that describes two behaviours 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.
 
 **What already exists.** When an answer - or the conflict check - means changing something already
 specified: a definition, a req, a functional spec, built or still queued, the next question is
@@ -127,22 +166,14 @@ is taken out, one it touches renders the spec as it now is.
 **Fix your own mistakes in place.** When a later answer refines or contradicts a change you wrote in
 this feature, write the correction as its own diff with `fixes_earlier`, before the next question.
 
-When the loop reaches the end of what the brief covers, ask whether the feature is fully covered.
-Yes: go to the review. No: the next question.
-
-### review
-
-A short consistency pass over what the feature changed, then the handover.
-
-1. Read the modified `.plain` file(s) whole, and check: every new concept defined before use, with
-   no cycles; build order right end to end - no spec depends on one after it; functional specs
-   language-agnostic; every external interface explicit (paths, methods, arguments, formats);
-   acceptance tests consistent with their functional specs.
-2. Run `validate` on every module the feature touched.
-3. Fix what either finds with a spec diff and `fixes_earlier` - never by editing the file. Ask the
-   user only when a fix is a decision the brief and the answers do not settle.
-
-Walk `references/checklist.md` once, as a self-audit. Then hand over in a few lines: the feature's
-spec changes in order, the builds they queued and how they stand (`drift`), and that any
-further change is asked for in the conversation - each one a spec diff, and what is left to build is
-worked out again from the spec. The next feature starts again from the intent.
+Once the questions are over - the cap reached, or `end_questions` called - write what is left of
+the feature the same way: one decision of yours, one spec change, with no answer between. Then run
+`validate` on every module the feature touched, and fix what it finds with a spec diff and
+`fixes_earlier`.
+
+Finish by summarizing the feature's spec changes in build order, marking what you decided without
+asking, saying what is built and what is still queued (`drift`), and getting explicit confirmation
+with `confirms_phase: true`. The summary is for the person to take in at a glance - a line a change,
+each decision you made yourself in a few words, about fifteen lines at most, never the specs'
+wording. Any further change is asked for in the conversation, each one a spec diff; the next
+feature starts again from the intent.

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

@@ -3,6 +3,10 @@
 Extract the intent of this feature before choosing files or authoring specifications. 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 product
+phase 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
 
 1. **Motivation** — What problem or limitation should this feature address?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3-next.26f08c5",
+  "version": "0.1.3-next.420ce7e",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,8 +33,8 @@
     "grammar:sync": "node scripts/sync-plyn-grammar.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@langchain/langgraph": "1.4.15",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.2",

package/genome/skills/bud/references/checklist.md

@@ -1,44 +0,0 @@
-# Bud Checklist
-
-Use this to verify the workflow was followed - never as a substitute for it. Walk it once in the
-review step, before the handover. A box counts only when the change is in the `.plain` files, not
-merely discussed; an unmet box is completed with a spec diff before finishing.
-
-## Intent
-
-- [ ] Asked the five core questions of `references/intent.md` one at a time - or confirmed in one
-  line what the user had already said - with at most one clarification for a vague answer.
-- [ ] Wrote nothing to disk before the brief was confirmed.
-- [ ] Summarized motivation, affected user, desired outcome, observable success criterion, and
-  boundary with explicit exclusions; got explicit confirmation.
-
-## Scope
-
-- [ ] Read the target `.plain` file(s) whole, with their `import` and `requires` chains, and the
-  config that says whether conformance tests are on.
-- [ ] Asked which module only when it was genuinely ambiguous.
-
-## Every product question
-
-- [ ] Asked exactly one question via `ask_user`, about the product - a trigger and outcome, an edge
-  case, a rule, a permission, a step of a flow - never about a spec section.
-- [ ] Turned the answer into exactly one spec change, across every section it needed, and wrote it
-  with `write_spec_diff` - never with `write` or `edit`.
-- [ ] Concepts defined in the same change as, or before, what first uses them; no cycles.
-- [ ] Every functional spec follows `add-functional-spec`'s rules, passed its complexity and
-  conflict checks, and sits in build order; one too big was split with the user.
-- [ ] Every change to something already specified - built or still queued - was put to the user
-  first (keep / augment / replace) and written as a diff with `fixes_earlier`.
-- [ ] Every correction of this feature's own changes was a diff with `fixes_earlier`, before the
-  next question.
-- [ ] `***test reqs***` and `***acceptance tests***` only with conformance tests on.
-- [ ] Asked whether the feature is fully covered before leaving the loop.
-
-## Review
-
-- [ ] Read the modified `.plain` file(s) whole and checked: concepts defined before use, no cycles,
-  build order right end to end, functional specs language-agnostic, every external interface
-  explicit, acceptance tests consistent with their functional specs.
-- [ ] Ran `validate` on every module touched, and fixed what it reported with spec diffs.
-- [ ] Handed over: the spec changes in order, the builds they queued and how they stand, and that
-  further changes are asked for in the conversation as spec diffs.