@r1z4x/tezgah 1.0.0 → 1.2.0

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