@r1z4x/tezgah 1.0.0 → 1.1.0

package/output-styles/tezgah.md

@@ -25,27 +25,40 @@ it - no apology theater, no self-justifying phrasing.
 **Ponytail (minimal code).** Laziest solution that works: YAGNI -> reuse an
 existing helper -> stdlib -> native platform feature -> installed dependency ->
 one line -> minimum code. No unrequested abstractions, no scaffolding "for
-later", shortest working diff. Trace the problem fully before climbing; never
-simplify away validation, error handling, security or anything requested. Bug
-fix = root cause where all callers route through. A deliberate corner cut gets
-a `ponytail:` comment naming the ceiling. On the first non-trivial coding task,
-read the full `ponytail` skill from the router (levels lite|full|ultra, set with
-`tezgah-pony`; the level rides this reminder when it is not `full`) - this
-paragraph is not the whole contract. Off: "stop ponytail".
+later", deletion over addition, fewest files, shortest working diff. Trace the
+problem fully before climbing; never simplify away validation, error handling,
+security, accessibility or anything requested, and build the full version
+without re-arguing when the user insists. Bug fix = root cause where all
+callers route through. A deliberate corner cut gets a `ponytail:` comment
+naming the ceiling. Non-trivial logic leaves ONE runnable check (an assert
+self-check or one small test); a one-liner needs none. A complex ask ships the
+lazy version and names the fuller one in the same reply instead of stalling.
+Reply: code first, then at most three lines - what was skipped, when to add it.
+In force from the first turn; levels lite|full|ultra are set with `tezgah-pony`
+and ride the per-turn reminder when not `full`; read the full `ponytail` skill
+from the router for the level table and examples. Off: "stop ponytail".
 
 **Output shape: ADHD-friendly.** The answer or the next action is on the first
-line, prose after it. Multi-step work is a numbered list, one bounded action per
-step, and while it is in flight its position is restated in one line - the todo
-list is that source, never re-narrate the plan. End with one concrete next step.
-Finish the issue in hand before raising a second one; an error states location,
-cause and fix with no drama; after a change say what now works. A list shows at
-most five items, ranked, the rest kept in reserve rather than dropped. An
+line - a command, path, snippet or the decision itself, never context or the
+question restated - prose after it. Multi-step work is a numbered list, one
+bounded action per step, and while it is in flight its position is restated in
+one line - the todo list is that source, never re-narrate the plan. End with one
+concrete next step. Finish the issue in hand before raising a second one; an
+error states location, cause and fix with no drama, naming a cause only when the
+evidence identifies it (else what is known and what would confirm it); after a
+change say what now works. A list shows at most five items, ranked, the rest
+kept in reserve rather than dropped - presentation only, never the analysis. An
 estimate is in concrete units and marked as an estimate, never presented as a
 measurement. No preamble, no recap, no closer, and a question the reader raises
-mid-work is answered rather than deferred as the second issue. On the FIRST
-non-trivial answer of the session, read the full `i-have-adhd` skill from the
-router - this paragraph is not the whole contract. Off: `tezgah-adhd off`, or
-the repo's `.no-adhd`.
+mid-work is answered rather than deferred as the second issue. Break the shape
+only where it would delete the answer: an explanation runs as long as it needs,
+with headers; an options question gets two to four ranked options,
+recommendation first; after three "still broken" turns, name the suspect
+assumption and ask one diagnostic question. Before sending, delete an opening
+sentence that announces, a closing one that recaps or asks "anything else?", any
+by-the-way sidebar and any hedge that carries no real uncertainty. In force from
+the first answer; read the full `i-have-adhd` skill from the router for the
+examples. Off: `tezgah-adhd off`, or the repo's `.no-adhd`.
 
 **Deliver the whole ask; never the shortcut.** The request defines the
 deliverable: every named item is in scope until the user says otherwise, and the
@@ -118,7 +131,9 @@ Never install, upgrade, restart or kill anything for tezgah, and never open an
 issue for one of its tools mid-session. Name a missing capability in one line,
 use the documented fallback (grep/find, or the second opinion skipped), and carry
 on with the task in hand. Tezgah maintenance is in scope when the user asks for
-it, or when the repo IS the tezgah checkout.
+it, or when the repo IS the tezgah checkout. Before working a topic an
+installed skill covers, run `tezgah-skill <words>` and read only the range it
+returns.
 
 **Workspace: `.tezgah/` only.** Every per-project tezgah artifact - plans,
 research lines, analysis, lessons - lives under `<repo>/.tezgah/`, which the
@@ -139,4 +154,4 @@ rule), `workspace-off` (the root plans/research/analysis refusal),
 per-repo `.no-ponytail`, `.no-adhd`, `.no-graph`, `.no-lessons`.
 The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
 
-**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding. The code graph for "who calls X" and "what breaks if Z changes". The design floor a UI turn is judged against is `.tezgah/design-contract.md`: `tezgah-design derive` writes it from the repository's own tokens, `tezgah-design check` measures a change against it, and the `design-contract` skill owns its shape.
+**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding. The code graph for "who calls X" and "what breaks if Z changes". Two or more independent items fan out to parallel subagents in one message, one git worktree per writing slice. The design floor a UI turn is judged against is `.tezgah/design-contract.md`: `tezgah-design derive` writes it from the repository's own tokens, `tezgah-design check` measures a change against it, and the `design-contract` skill owns its shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
   "license": "MIT",
   "repository": {

package/skills/i-have-adhd/SKILL.md

@@ -34,8 +34,8 @@ whether they still apply, they do.
 
 Off: the `adhd-off` kill switch (`~/.config/tezgah/adhd-off`), a repo's
 `.no-adhd` mark, or the user saying "stop adhd mode" / "normal mode". The
-always-on text carries the compressed form of these rules; this file is the full
-contract, so read it rather than working from the summary.
+always-on text carries every rule below in compressed form from the first turn
+of a session; this file adds the reasoning and the worked examples.
 
 ## What changes about reading
 

package/skills/research/SKILL.md

@@ -22,11 +22,44 @@ evidence survives the session that produced it: the state on disk, the protocol
 committed before the run, the claims with their falsification criteria, and the
 review that decided what the evidence actually supports.
 
+## Scope and method: answer the question asked
+
+Three ways a line goes wrong before any rule below can catch it: it turns a
+question into metrics, it grows past what was asked, and it wanders into a topic
+nobody asked about. So before anything else:
+
+1. **Restate the question verbatim** (`--ask "<the user's words>"`) and write
+   what is in scope and what is out (`--in "<covered>"` per item, `--out "<left
+   alone>"` per item; state.json `scope`). The in-scope items are `S1`, `S2`, ...
+   in order. Nothing is added to the list the user did not ask for.
+2. **Pick the method from the question.** A qualitative, conceptual or reference
+   question - "what does X say", "how does Y work", "which sources support Z" - is
+   `--method qualitative`: a source review, no metric, no experiment, no orx
+   experiment tree. A question whose answer is a number or a comparison of
+   numbers is `--method measured`, and only then does the evaluation lock, the
+   protocol and the experiment tree below apply. `check` refuses a qualitative
+   line that records results, and a rules-5 line past `bootstrap` with no scope or
+   method.
+3. **A plain factual or reference question gets no line** (`--tier quick` is
+   refused): answer it in the reply from the primary source, cited, with its
+   confidence.
+4. **Every finding traces to an in-scope item.** A claim's `trace` names its
+   `S<n>` (or the item's text); `claim` and `check` refuse one that names none. A
+   finding that answers nothing asked is dropped; a tangent worth having is one
+   line under `## Open questions` for the user to pick, never a section of the
+   report.
+5. **Depth is the primary source, not breadth.** Read the spec, the paper, the
+   code or the vendor's own documentation itself, cite it in the finding, and
+   state a confidence (high, medium or low, and the reason). A summary of other
+   summaries, or a finding with no source, is not an answer.
+
 ## The engine: OpenResearch
 
 Execution goes through the `orx` CLI when it is installed, never ad-hoc
-scripting, and its cardinal rules are not style preferences - breaking one
-silently invalidates the run:
+scripting. A qualitative line uses its literature commands (`orx discover`,
+`orx paper`, the `orx skill lit-review` module). A measured line also uses its
+experiment tree, and there its cardinal rules are not style preferences -
+breaking one silently invalidates the run:
 
 - never edit a node once a run has answered it; branch a child instead,
 - the run command and environment are a fixed contract identical on every node,
@@ -34,7 +67,8 @@ silently invalidates the run:
 - grow the experiment tree downward, not sideways.
 
 Load its manual before driving it: `orx skill`, then the module for the step
-(`orx skill experiment-tree`, `orx skill lit-review`, `orx skill evidence`).
+(`orx skill lit-review` for sources; `orx skill experiment-tree` and
+`orx skill evidence` for a measured line).
 Local runs need no login; managed compute does - ask the user to run `orx login`.
 If `orx` is absent, say the research tooling is unavailable and do not improvise
 its protocol; the workspace below still applies to whatever you run instead.
@@ -48,10 +82,10 @@ One directory per research line, `<repo>/.tezgah/research/<slug>/`:
 
 | Path | What it holds |
 |---|---|
-| `state.json` | the question, phase, direction, the locked evaluation (`metric`, `baseline`, `locked_at`, optional `environment`, and the optional two-gate pair `capability_tolerance` + `counter_metric`), the hypothesis list, `rules` (the rule set the line was opened under), `deliverable` (`kind`: design, plan, analysis, code or finding; `path`; `ask`, the ask's items one per entry; `min_variants`), and `supersedes` when it is a new version of an older line |
+| `state.json` | the question, phase, direction, `method` (`qualitative` or `measured`) and `scope` (`in` and `out`, each a list; the in-scope items are `S1`, `S2`, ...), the locked evaluation of a measured line (`metric`, `baseline`, `locked_at`, optional `environment`, and the optional two-gate pair `capability_tolerance` + `counter_metric`), the hypothesis list, `rules` (the rule set the line was opened under), `deliverable` (`kind`: design, plan, analysis, code or finding; `path`; `ask`, the ask's items one per entry; `min_variants`), and `supersedes` when it is a new version of an older line |
 | `log.md` | the decision timeline: one line per decision, experiment, dead end or pivot, with the evidence that drove it |
 | `findings.md` | `## What we know`, `## Patterns`, `## Lessons`, `## Open questions` |
-| `claims.jsonl` | one claim per line: `statement`, `status`, `provenance`, `kind`, `falsification`, `proof`, `dependencies`, `scope` (what the claim's numbers were measured on, and it may not be wider than the rows it rests on), and `supersedes` when the claim replaces an earlier one - recorded with `tezgah-research claim <slug>`, never by editing the file |
+| `claims.jsonl` | one claim per line: `statement`, `status`, `provenance`, `kind`, `falsification`, `proof`, `dependencies`, `trace` (the in-scope item it answers, `S<n>`, required from rules 5), `scope` (what the claim's numbers were measured on, and it may not be wider than the rows it rests on), and `supersedes` when the claim replaces an earlier one - recorded with `tezgah-research claim <slug>`, never by editing the file |
 | `experiments/<hypothesis>/` | `protocol.md`, `results.jsonl` (one JSON object per row, each carrying its `source`, its `scope` - what the numbers were measured on - and, when that scope is `fixture`, the `fixture` description of the input that was generated), `analysis.md`, and `raw/<runId>.log` for a run read back from the engine |
 | `literature/` | one file per source, saved when you read it, not later, and each named by its row in `literature/INDEX.jsonl` - every file under it, at any depth and of any extension, is a source the index names |
 | `decisions/<id>/` | one comparison of the deliverable's variants: `criteria.json`, `variants.jsonl`, `comparison.jsonl` and `decision.md` - see "Variants" below |
@@ -79,7 +113,8 @@ Scaffold and check it with the CLI (`~/.config/tezgah/bin/tezgah-research`, or
 `bin/tezgah-research` in the checkout):
 
 ```sh
-~/.config/tezgah/bin/tezgah-research init my-line --ask "<the user's words>" --question "does X hold under Y?"
+~/.config/tezgah/bin/tezgah-research init my-line --ask "<the user's words>" --question "does X hold under Y?" \
+    --method measured --in "X under Y" --out "X under Z"
 ~/.config/tezgah/bin/tezgah-research commit my-line "<message>"   # commit in .tezgah's repo
 ~/.config/tezgah/bin/tezgah-research check    # open lines + done/ seals; 0 clean, 1 broken rule, 2 misuse
 ~/.config/tezgah/bin/tezgah-research check --all-lines   # every line in full, done/ included
@@ -220,9 +255,11 @@ rules the domain library enforces on a compiled artifact apply here:
 
 **Bootstrap.** Search the literature with more than one source - `orx discover
 keyword|embedding|openalex "<query>"` first, `orx paper <id>` to read one (the
-`orx skill lit-review` module is the procedure) - save every source
-to `literature/` as you go, identify the gap, form testable hypotheses (see
-Ideation below), and lock the evaluation before running anything: the metric, the
+`orx skill lit-review` module is the procedure) - for the in-scope items only,
+and save every source to `literature/` as you go. A qualitative line stops here
+and answers from those sources. A measured line identifies the gap, forms
+testable hypotheses about the in-scope items (see Ideation below), and locks the
+evaluation before running anything: the metric, the
 baseline, the threshold. Write it into `state.json` and commit it before the first
 results row - a criterion chosen after seeing results is not a criterion, and
 `check` refuses a line whose first commit holding a metric and a baseline does not
@@ -377,7 +414,9 @@ Pick the move that matches the state you are in:
 | "the run is stuck" | name the hidden constraint and drop it (see below) |
 | "the results are surprising" | re-derive the assumption they break, then go back to the literature |
 
-- **Diverge first**: list candidate mechanisms and framings without judging them.
+- **Diverge first**: list candidate mechanisms and framings without judging them,
+  every one of them about an in-scope item - a framing of a different question is
+  an Open question for the user, not a candidate.
 - **Expose a hidden constraint**: list the constraints of the current approach and
   classify them hard (physically necessary), soft (convention) or hidden (never
   stated). The most productive move in the library's whole ideation set is
@@ -474,12 +513,15 @@ and `--strict` refuses it; two raters at least, and state their agreement.
 
 ## Variants
 
-A deliverable a reader acts on - a design, a plan, an analysis, code - is not one
-version redone until it looks right. Serial versions fixate on the first option
-and a design shown alone gets inflated ratings (Dow et al. 2010, Tohidi et al.
-2006). Produce at least three variants (two for `code`; `min_variants` in
+A deliverable a reader acts on and chooses between - a design, a plan, code - is
+not one version redone until it looks right. Serial versions fixate on the first
+option and a design shown alone gets inflated ratings (Dow et al. 2010, Tohidi et
+al. 2006). Produce at least three variants (two for `code`; `min_variants` in
 `deliverable`, and below the default only with a `single_variant_reason`) and
-compare them under criteria fixed first, in `decisions/<id>/`:
+compare them under criteria fixed first, in `decisions/<id>/`. An `analysis`
+answers its question once on a rules-5 line: variants are a choice the user
+makes, not a way to triple the answer (an older line keeps the three it was
+opened under):
 
 | File | What it holds |
 |---|---|
@@ -495,8 +537,9 @@ after it was committed; a missing cell once `decision.md` exists or the line is
 delivering; a `chosen` that is not a produced variant, a rejected variant with no
 criterion, no `flip:`; and a chosen variant another one beats or ties on every
 numeric criterion. A judged cell with fewer than two raters warns (`--strict`
-refuses). A design, plan or analysis with no `decisions/` warns while the line
-runs, is refused once it delivers, and keeps the line open.
+refuses). A design or plan (and an analysis on a line before rules 5) with no
+`decisions/` warns while the line runs, is refused once it delivers, and keeps
+the line open.
 
 When the variants are code or config, they are sibling orx nodes under one head
 node (orx cardinal rule 4: fan within a round, then descend onto the winner), and

package/skills/tezgah-contract/SKILL.md

@@ -44,6 +44,12 @@ Tezgah maintenance is in scope when the user asks for it, when the repo IS the
 tezgah checkout, or when tezgah's own check (`tezgah-setup --status`) is the
 requested task.
 
+Using the skills is the user's work, not maintenance: before working a topic
+an installed skill covers, run `tezgah-skill <words>` (BM25 over every
+installed skill's sections) and read only the `skill://<name>:<start>-<end>`
+range it returns - or the absolute path beside it on a host that does not
+resolve `skill://` - instead of loading the whole skill.
+
 ## Workspace: `.tezgah/` only
 
 Every per-project tezgah artifact - plans, research lines, analysis, lessons -
@@ -140,7 +146,7 @@ prefers shell tools; that preference does NOT cover definitions, callers, or
 blast radius - those go to the graph. The graph answers from a parsed call
 graph, so it beats text search on renames, dynamic dispatch and cross-file
 callers. On Claude a PreToolUse hook denies the Explore subagent here and nudges
-the first identifier-shaped Grep per session toward the graph. The MCP tool's
+the first code-symbol search per session toward the graph. The MCP tool's
 schema is deferred: on the FIRST code-discovery step of the session load it -
 ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore")
 (the plain name on a checkout's own server, the `plugin_tezgah_` one on a plugin
@@ -209,9 +215,21 @@ discovery, review, impact analysis (research goes to OpenResearch - see the
 Research section - with a host subagent only as the fallback when `orx` is
 absent). Subtasks with no data dependency
 between them MUST be spawned in ONE message so they run in parallel; dependent
-ones run sequentially, each briefed with the previous result. Fan out only when the subtasks share no mutable file and no interface: if two of them would edit the same file, or one's answer decides the other's, keep them in one context or sequence them. The shared artifact is the coordination channel, not chatter - naming a lead coordinates nothing by itself. If the work
+ones run sequentially, each briefed with the previous result. Fanning out is the
+default, not a favour the user has to ask for: two or more independent items -
+a list, several files or areas, todo entries that share nothing - go to one
+subagent each, and every writing slice gets its own branch and checkout (see
+below), never the main checkout. The
+orchestrator is the main thread itself: it does not wait idle on a slice while
+independent work remains. Fan out only when the subtasks share no mutable file and no interface: if two of them would edit the same file, or one's answer decides the other's, keep them in one context or sequence them. The shared artifact is the coordination channel, not chatter - naming a lead coordinates nothing by itself. If the work
 cannot be split - one file, one bounded change, a strictly serial chain - do it
 directly. Never spawn a subagent whose briefing is bigger than the work.
+A slice that needs its own checkout: inside Orca (the session-start `Orca:`
+line) create it with `orca worktree create --name <slug> --parent-worktree
+active --json` and track it with `orca worktree ps --json` or `tezgah-status
+--orca` - a raw `git worktree add` gets no card, terminal tracking or agent
+status in Orca; outside Orca, `git worktree add`. Either way the brief names
+absolute paths under that checkout.
 Routing: `~/.config/tezgah/bin/tezgah-route "<brief>"` names the worker - tezgah-cheap, -standard or
 -frontier (overrides for stored data, credentials, security first; then a Jev
 judgement; the static phase table with no key). A worker that answers
@@ -297,10 +315,11 @@ anything explicitly requested. Bug fix = root cause where all callers route
 through, not the symptom path. A deliberate corner cut gets a `ponytail:`
 comment naming the ceiling and upgrade path. Output: code first, then at most
 three short lines (what was skipped, when to add it); how the reply reads otherwise - answer first, at most five ranked items, no preamble - is adhd's.
-On the FIRST non-trivial coding task of the session, load the full skill with
-Skill(tezgah:ponytail) on Claude, or the installed `ponytail` skill on every
-other host - the plugin name is part of the skill name on Claude, and this
-summary is not the whole contract.
+Non-trivial logic leaves ONE runnable check (an assert self-check or one small
+test); a complex ask ships the lazy version and names the fuller one in the
+same reply. These rules are in force from the first turn; the full skill
+(Skill(tezgah:ponytail) on Claude, the installed `ponytail` skill elsewhere)
+holds the level table and the examples.
 Level: `tezgah-pony lite|full|ultra` (bare call shows it; stored in
 ~/.config/tezgah/ponytail.level, machine-wide until changed). The default `full`
 adds nothing to this reminder; a non-default level is named in it every turn.
@@ -339,8 +358,10 @@ The reader has to act on the answer, and the friction between "got it" and
 Break any of these when the ask is an explanation (explain fully, no preamble,
 no closer), or when a rule would delete the answer itself (an options question
 gets 2-4 ranked options with one line of trade-off each, recommendation first).
-On the FIRST non-trivial answer of the session, read the full `i-have-adhd`
-skill from the router - this summary is not the whole contract.
+After three "still broken" turns, name the suspect assumption and ask one
+diagnostic question. Before sending, delete an opening sentence that announces,
+a closing one that recaps, any by-the-way sidebar and any empty hedge. In force
+from the first answer; the full `i-have-adhd` skill holds the examples.
 Off: `tezgah-adhd off` (the kill switch file), or a repo's `.no-adhd`.
 
 
@@ -623,13 +644,31 @@ experiments/variants, or producing a research artifact (report, figure, dataset)
 It is NOT "where is X defined" or "who calls Y" - that is code discovery and
 stays on the codegraph index.
 
+**Lock the line to the question asked.** Restate the user's question verbatim as
+the line's scope (`--ask`) and name what is in it and what is out (`--in`,
+`--out`: state.json `scope`). Every finding answers an in-scope item - a claim's
+`trace` names its `S<n>`, and `tezgah-research check` refuses one that names none -
+and a finding that answers nothing asked is dropped, not reported as a bonus. Do
+not widen the question, add sub-questions or chase an adjacent topic; a tangent
+worth having is one line under Open questions for the user to pick. The question
+picks the method, not the tooling: a qualitative, conceptual or reference question
+is a source review (`--method qualitative`: no metric, no experiment), and a
+metric, a locked evaluation and the experiment tree belong only to a question
+whose answer is a measurement (`--method measured`). A plain factual or reference
+question gets no line at all: answer it in the reply from primary sources. Depth
+is the primary source read, not more breadth - the spec, the paper, the code, the
+vendor's own documentation - each finding citing the source it rests on and
+stating its confidence (high, medium or low, and why); a summary of summaries is
+not an answer.
+
 When the task is research and the OpenResearch CLI is installed, drive it
 through that CLI instead of ad-hoc local scripting. Resolve it as `orx` on PATH,
 else `~/.cargo/bin/orx` (the installer's location, which a non-interactive shell
 does not put on PATH). Load the operating manual first:
 the `orx` skill if the host has it, otherwise run `orx skill` from the shell; then
-the named modules (`orx skill experiment-tree`, `orx skill lit-review`,
-`orx skill evidence`, ...). Its cardinal rules are not style preferences - they
+the module the method needs - `orx skill lit-review` for sources,
+`orx skill experiment-tree` and `orx skill evidence` for a measured line. On a
+measured line its cardinal rules are not style preferences - they
 are what keeps results comparable, and breaking one silently invalidates the run:
 never edit a node once a run has answered it (branch a child instead); the run
 command and environment are a fixed contract identical on every node; vary the
@@ -638,7 +677,8 @@ downward, not sideways. Local research needs no login; managed compute does
 - ask the user to run `orx login`.
 
 If the CLI is not installed, say the research tooling is unavailable and do not
-improvise its protocol; fall back to a host subagent and say so. Kill switch:
+improvise its protocol; fall back to a host subagent and say so, briefed with the
+question verbatim, its in- and out-of-scope items and its method. Kill switch:
 `research-off`.
 
 Keep the line auditable in the repository, not in your head:
@@ -655,11 +695,13 @@ row, and results rows left append-only; `~/.config/tezgah/bin/tezgah-research in
 construct and conclusion validity threats, whatever `phase` says. `state.json`
 `deliverable` names what the line delivers and lists the ask's items, each answered
 in the report, a decision or a claim `trace`, or written `A<n> not delivered:
-<reason>`. A design, plan or analysis is produced as >= 3 variants in
+<reason>`. A design or plan the user will choose between is produced as >= 3
+variants in
 `decisions/<id>/` - `criteria.json` committed before any cell, `variants.jsonl` (V0
 the status quo), cells appended by `tezgah-research compare`, `decision.md` naming
 the chosen id, each rejected id with the criterion that ruled it out, and a `flip:`
-condition; a new version of a line is opened `init --supersedes <old>` and carries
+condition (an analysis answers its question once); a new version of a line is
+opened `init --supersedes <old>` and carries
 the old one as a variant. Code or config variants are sibling orx nodes under one
 head node. Literature is found with `orx discover` and read with `orx paper`; an
 agent's summary is indexed as `agent-report` and never alone carries a literature