@r1z4x/tezgah 1.0.0 → 1.2.0

package/hosts/cursor/hook.py

@@ -48,11 +48,12 @@ from tezgah_guard import attest_session, import_failed, safe  # noqa: E402
 try:
     from tezgah_context import (  # noqa: E402
         command_text, context_for, record, shell_kind, slug, under)
-    from tezgah_gate import decision, explored  # noqa: E402
+    from tezgah_gate import decision, explored, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, bind_session, note, note_tool, ran_nothing, report_bytes,
         stop_reason)
     from tezgah_paths import cache_dir, off  # noqa: E402
+    from tezgah_taste import write_note  # noqa: E402
     from tezgah_untrusted import marks  # noqa: E402
 except Exception as exc:
     import_failed(exc)
@@ -318,9 +319,16 @@ def dispatch(payload):
         if (kind in ("graph", "consult") and under(cwd) and not quiet
                 and first_time(session_id, "graph")):
             reinforce = REINFORCE
-        # both are one line for the model, on the result they belong to; a turn
-        # that earns both reads them together rather than one replacing the other
-        text = "\n".join(t for t in (notice, reinforce) if t)
+        # the gate's graph line for a code-symbol search (graph_advice) rides
+        # the same channel; all three are one line each for the model, on the
+        # result they belong to, read together rather than one replacing another
+        advice = (graph_advice(gate_name(payload.get("tool_name", "")), inp, cwd,
+                               "cursor") if under(cwd) and not quiet else None)
+        # the opt-in taste note for the first write to this file type
+        # (hooks/tezgah_taste.write_note)
+        taste = (write_note(session_id, inp, cwd, gate_name(payload.get("tool_name", "")))
+                 if under(cwd) and not call_failed(payload) else None)
+        text = "\n".join(t for t in (notice, reinforce, advice, taste) if t)
         out = {"additional_context": text} if text else {}
     elif event == "postToolUseFailure":
         if kind:

package/hosts/omp/hook.py

@@ -19,7 +19,8 @@ the same code every other host runs.
     {"event": "user_prompt", "cwd": ..., "prompt": ...}
         -> {"context": <reminder + the rules this prompt arms>}
     {"event": "pre_tool_use", "cwd": ..., "tool": ..., "input": {...}}
-        -> {"deny": reason}
+        -> {"deny": reason} | {"advice": line} (the graph line the bridge hands
+           the model with this call's result; never a block)
     {"event": "post_tool_use", "cwd": ..., "tool": ..., "input": {...},
      "failed": bool, "idx": glyph}
         -> {"status": "pony✓ ...", "idx": glyph, "label": one line}
@@ -57,11 +58,12 @@ try:
     from tezgah_context import (  # noqa: E402
         color_default, command_text, context_for, health_segments, record,
         render_tiers, shell_kind, skill_read_kind)
-    from tezgah_gate import decision  # noqa: E402
+    from tezgah_gate import decision, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, bind_session, note, note_tool, stop_reason, untrusted_label,
         untrusted_source)
     from tezgah_paths import off, root_for  # noqa: E402
+    from tezgah_taste import write_note  # noqa: E402
     from tezgah_untrusted import marks  # noqa: E402
 except Exception as exc:
     import_failed(exc)
@@ -142,9 +144,12 @@ def handle(payload):
         # answered at every turn boundary
         return answered(*status_line(cwd, session_id))
     if event == "pre_tool_use":
-        reason = decision(payload.get("tool", ""), payload.get("input") or {},
-                          cwd, session_id)
-        return {"deny": reason} if reason else {}
+        tool, inp = payload.get("tool", ""), payload.get("input") or {}
+        reason = decision(tool, inp, cwd, session_id)
+        if reason:
+            return {"deny": reason}
+        advice = graph_advice(tool, inp, cwd, "omp")
+        return {"advice": advice} if advice else {}
     if not root_for(cwd):
         return {}
     if event == "session_start":
@@ -179,7 +184,9 @@ def handle(payload):
                               with_core=False)
         return {"context": context} if context else {}
     if event == "user_prompt":
-        context = context_for("user_prompt", cwd, payload)
+        # host="omp": the skill hint drops the absolute path, since omp's
+        # read tool resolves the skill:// address on its own
+        context = context_for("user_prompt", cwd, dict(payload, host="omp"))
         return {"context": context} if context else {}
     if event == "post_tool_use":
         tool = payload.get("tool", "")
@@ -240,6 +247,11 @@ def handle(payload):
         # deny: the bridge puts it in front of the content itself, so the model
         # reads where the text came from - or, on an effect after such a read,
         # the taint notice - while it reads the result.
+        # the opt-in taste note for the first write to this file type
+        # (hooks/tezgah_taste.write_note) rides the same label
+        taste = (safe(session_id, write_note, session_id, inp, cwd, tool)
+                 if failed is not True else None)
+        label = "\n".join(t for t in (label, taste) if t)
         if label:
             out["label"] = label
         return out

package/hosts/omp/tezgah-hook.ts.in

@@ -263,11 +263,17 @@ function skillRead(tool: string, args: any): boolean {
 
 // The gate is only consulted for the tools the shared rule knows: the refusal
 // of the grep-only explorer (task/agent), the anti-shortcut and attribution
-// checks (bash), and the test-skip check (the edit/write names). An MCP tool is
+// checks (bash), the test-skip check (the edit/write names), and the code-graph
+// nudge on omp's search tools (grep, find, search, ast_grep). An MCP tool is
 // consulted when its name carries an effect verb (MCP_EFFECT, see `tool_call`).
-const GATED = ["grep", "bash", "shell", "command", "task", "agent", "edit",
-  "write", "multiedit", "notebookedit", "apply_patch", "edit_file", "write_file",
-  "search_replace", "powershell", "pwsh"];
+const GATED = ["grep", "find", "search", "ast_grep", "bash", "shell", "command",
+  "task", "agent", "edit", "write", "multiedit", "notebookedit", "apply_patch",
+  "edit_file", "write_file", "search_replace", "powershell", "pwsh"];
+
+// The gate's non-blocking graph line (tezgah_gate.graph_advice), held from the
+// call to its result: `tool_call` can only block, `tool_result` can hand the
+// model `additionalContext`, and carrying it across costs no second spawn.
+const ADVICE = new Map<string, string>();
 
 // The effect verbs of tezgah_integrity.MCP_VERBS, as one pattern: a read-only
 // MCP call (a code-graph query) reaches no content rule, so it pays no spawn.
@@ -647,15 +653,22 @@ export default function tezgahOmp(pi: any): void {
       return undefined;  // a hook that cannot answer cannot refuse either
     }
     if (res.deny) return { block: true, reason: res.deny };
+    if (res.advice && event?.toolCallId != null) {
+      ADVICE.set(String(event.toolCallId), String(res.advice));
+    }
     return undefined;
   });
 
   pi.on("tool_result", async (event: any, ctx: any) => {
     const tool = String(event?.toolName ?? "");
     const args = event?.input ?? {};
+    const id = event?.toolCallId != null ? String(event.toolCallId) : "";
+    const advice = ADVICE.get(id);
+    ADVICE.delete(id);
+    const graph = advice ? { additionalContext: advice } : undefined;
     if (!WATCHED.includes(tool.toLowerCase()) && !tool.startsWith("mcp__")
         && !skillRead(tool, args)) {
-      return;
+      return graph;
     }
     // Tri-state: an unread outcome must never be written as a passed check,
     // because the Stop rule below reads this ledger as evidence.
@@ -680,9 +693,9 @@ export default function tezgahOmp(pi: any): void {
     // place; every other result is left exactly as the host produced it.
     if (res.label) {
       const content = labelled(event?.content, res.label);
-      if (content) return { content };
+      if (content) return { content, ...graph };
     }
-    return undefined;
+    return graph;
   });
 
   pi.on("session_stop", async (event: any, ctx: any) => {

package/hosts/opencode/plugins/tezgah.js

@@ -105,7 +105,8 @@ const SETUP_BIN = join(CONFIG, "bin", "tezgah-setup")
 const CONTEXT_BIN = join(CONFIG, "bin", "tezgah-context")
 const CAPTURE_BIN = join(CONFIG, "bin", "tezgah-capture")
 const GATE_BIN = join(CONFIG, "bin", "tezgah-gate")
-const IDENT = /^[A-Za-z_][A-Za-z0-9_]{2,}$/
+const SEARCH_SYMBOL =
+  /^(?:\\b)?(?:(def|class|function|func|fn|interface|struct|type)\s+)?([A-Za-z_][A-Za-z0-9_]{2,})(\\?\()?(?:\\b)?$/
 // A hung core must not hold a tool call open. Every awaited core CLI runs
 // through `collect`, which gives it a deadline and answers a timeout with the
 // same fail-open value a missing binary or a non-zero exit gets: a core that
@@ -1265,9 +1266,10 @@ async function recordEvidence(sessionID, tool, args, result, workspace, cwd,
   // hooks/tezgah_taste.note_write in process, and this host writes its edit row
   // here, so the same call goes to that module through a process. The marker
   // lives where the kill switches do (tezgah_paths.armed), so off it costs two
-  // stats and spawns nothing.
+  // stats and spawns nothing. The process prints the taste note for the first
+  // write to this file type (tezgah_taste.write_note), returned to the caller.
   if (kind === "edit" && row.exit !== 1 && off("taste-on")) {
-    await noteTaste(sessionID, row.id, args, cwd)
+    return await noteTaste(sessionID, row.id, args, cwd)
   }
 }
 
@@ -2111,10 +2113,12 @@ function ledgerStem(sessionID) {
 }
 
 // The nearest enclosing project that holds a codegraph index. The answer is the
-// indexed directory itself, which is what the nudge names.
+// indexed directory itself, which is what the nudge names; a `.no-graph` met
+// first is the repo's own switch (hooks/tezgah_gate.index_slug), so no index.
 function indexSlug(dir) {
   let d = dir
   for (;;) {
+    if (existsSync(join(d, ".no-graph"))) return null
     if (existsSync(join(d, GRAPH_DB))) return d
     const parent = d.replace(/\/[^/]+\/?$/, "")
     if (!parent || parent === d) return null
@@ -2122,17 +2126,23 @@ function indexSlug(dir) {
   }
 }
 
+// hooks/tezgah_gate.symbol_in: a code symbol (inner underscore, a lower-to-upper
+// step, or any identifier in a `def x` / `x(` pattern); a plain word such as
+// `TODO` is literal text and is never nudged.
+function symbolIn(text) {
+  const m = String(text || "").trim().replace(/^['"]+|['"]+$/g, "").match(SEARCH_SYMBOL)
+  if (!m) return null
+  const tok = m[2]
+  const shaped = tok.replace(/^_+|_+$/g, "").includes("_") || /[a-z][A-Z]/.test(tok)
+  return m[1] || m[3] || shaped ? tok : null
+}
+
 function identifierFrom(tool, args) {
-  if (tool === "grep") {
-    const p = String(args.pattern || "")
-    return IDENT.test(p) ? p : null
-  }
+  if (tool === "grep") return symbolIn(args.pattern)
   if (tool === "bash" || tool === "shell") {
     const cmd = String(args.command || "")
     const m = cmd.match(/(?:^|[|;&(]\s*|\s)(?:grep|rg)\s+((?:-\S+\s+)*)(\S+)/)
-    if (!m) return null
-    const tok = m[2].replace(/^['"]|['"]$/g, "")
-    return IDENT.test(tok) ? tok : null
+    return m ? symbolIn(m[2]) : null
   }
   return null
 }
@@ -2365,7 +2375,8 @@ function captureSnapshot(tool, args, dir, sessionID) {
 
 // hooks/tezgah_taste.py's own entry point, found beside the bin the snapshot
 // capture runs (the installed bins are links into the checkout, which holds no
-// copy of hooks/ under CONFIG). Best effort and silent, like captureSnapshot.
+// copy of hooks/ under CONFIG). Best effort, like captureSnapshot: a failure is
+// ignored. It resolves to the taste note the process printed, else undefined.
 function noteTaste(sessionID, id, args, cwd) {
   let script
   try {
@@ -2374,7 +2385,8 @@ function noteTaste(sessionID, id, args, cwd) {
   } catch { return undefined }
   return collect([script, JSON.stringify({
     session_id: sessionID, id, input: args, cwd, host: "opencode" })],
-  { stdio: "ignore" }, null, () => undefined)
+  { stdio: ["ignore", "pipe", "ignore"] }, null,
+  (code, out) => (code === 0 && out.trim() ? out.trim() : undefined))
 }
 
 export const Tezgah = async ({ directory }) => {
@@ -2727,8 +2739,9 @@ export const Tezgah = async ({ directory }) => {
         if (notice) labelResult(output, notice)
         const kind = await classify(tool, args)
         if (kind) await record(sessionID, kind)
-        await recordEvidence(sessionID, tool, args, output, workspace, dir,
-                             own || inherited)
+        const taste = await recordEvidence(sessionID, tool, args, output, workspace,
+                                           dir, own || inherited)
+        if (taste) labelResult(output, taste)
       } catch {}
     },
 

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.2.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