@zenera/cli 1.1.24 → 1.1.26

package/templates/editor/.github/skills/zen-inspect/SKILL.md

@@ -1,20 +1,30 @@
 ---
 name: zen-inspect
-description: Diagnosing a run you did not watch - the `zen inspect graph` → read → `zen inspect node` loop, how to name the run (`--dir`, `--run`, `--session`, and why `node` takes ids only), how to read every part of the graph format (the `%%` header rows and what each count is evidence of, the anatomy of a node line, the label each node kind produces, shapes and colours, the `flow`/`branches`/`calls` edge blocks, branch subgraphs, and what `hidden by` and `ERROR` mean), how to open individual nodes by id or range and read the `===`/`--- part` framing, which payload parts and facts each kind carries, how `zen inspect ask` replays one `llm_call` to a model with a question when reading the node did not settle why it acted, and recipes for the usual faults - a loop, a failing tool, a prompt that was assembled differently from how it reads, a hand-off that fired early, a skill that never activated, a branch that failed, tokens spent where you did not expect. Load before reading any run trajectory, before answering "why did the agent do that", and whenever a run directory is all you have.
+description: 'Use when an LLM agent must diagnose a recorded Zenera run non-interactively: read `zen inspect graph`, open selected nodes, replay an `llm_call` with `zen inspect ask`, identify loops, failed tools, wrong prompts, missed skills, early hand-offs, failed branches, compaction, latency, or token waste. Requires explicit run, node, and question arguments so commands remain deterministic and never prompt.'
 ---
 
-# Reading a run
+# Diagnose a run non-interactively
 
 A run leaves behind everything it did, and that is the problem: a trajectory of
 a few hundred nodes is far too big to read and far too repetitive to need to.
 `zen inspect` answers it in two halves.
 
-| Command                 | For     | Gives                                           |
-| ----------------------- | ------- | ----------------------------------------------- |
-| `zen inspect report`    | a human | `report.html` - every message, payload and cost |
-| `zen inspect graph`     | you     | the whole run as one Mermaid flowchart          |
-| `zen inspect node <id>` | you     | those nodes in full, payloads resolved          |
-| `zen inspect ask <id>`  | you     | that call replayed to a model, with a question  |
+This skill is for an agent process without a TTY. Every invocation must be
+fully specified. Never run bare `zen inspect` or `zen inspect node`: without a
+run named they read whichever run is newest. Never run `zen inspect ask`
+without a question: that is the interactive mode, for a person, and it fails
+without a terminal. With a question it is one-shot - no banner, no prompt,
+only the answer on stdout.
+
+For a whole-run audit - health, memory, delegation, forking, tool use, and
+what to change in the instructions - load **zen-analyze-run**, which drives
+this skill end to end.
+
+| Command                                                    | Gives                                         |
+| ---------------------------------------------------------- | --------------------------------------------- |
+| `zen inspect graph --dir <run-dir>`                        | the whole run as one model-readable flowchart |
+| `zen inspect node <id...> --dir <run-dir>`                 | selected nodes, payloads resolved             |
+| `zen inspect ask <id> --question-file <f> --dir <run-dir>` | one replay answer on stdout, then exit        |
 
 **`graph` and `node` are the pair you use.** The graph is an index: one line per
 node, short sequential ids, the whole run in a few hundred lines. `node` is the
@@ -26,8 +36,26 @@ pay for what you open.
 run's own model why it did what it did. Open the node first - most questions are
 answered by reading what it was given.
 
-`report` is for a person with a browser. Print its path and hand it over; do not
-try to read the HTML.
+To get one answer without prompts, pass all three inputs:
+
+```sh
+zen inspect ask <llm-node-id> --question-file <question file> --dir <run-dir>
+```
+
+- `<llm-node-id>` is an `nN` id from `zen inspect graph` whose label starts
+  with `llm`.
+- `<question file>` holds the complete question, written with your
+  file-editing tool to `.tmp/ask/<run-id>/<node>-<topic>.md`. The shell never
+  parses it, so quotes, backticks and `$` arrive as written. Never pass the
+  question as a quoted argument, a heredoc or `$(cat ...)`, and never wrap
+  `zen` in a script.
+- `--dir <run-dir>` identifies the run. Instead, a caller may use `--run
+<run-id>` with `--session <session-id>` and, when outside the project,
+  `--project <name-or-dir>`.
+
+Exactly one raw Markdown answer is written to stdout, then the command exits.
+Omit `--model` to use the model that made the recorded call; pass `--model
+<ref>` only for a second opinion.
 
 ## The loop
 
@@ -39,7 +67,8 @@ zen inspect graph --dir <run dir>
 zen inspect node n13 n17..n19 --dir <run dir>
 
 # 3. only if reading them did not settle it, ask the model itself
-zen inspect ask n17 "why run python -c when the skill says npm test?" --dir <run dir>
+#    (.tmp/ask/<run-id>/n17-tests.md: "Why run python -c when the skill says npm test?")
+zen inspect ask n17 --question-file .tmp/ask/<run-id>/n17-tests.md --dir <run dir>
 ```
 
 That is the whole method. Never start by opening nodes - without the header
@@ -48,26 +77,26 @@ at a time is the failure the graph exists to prevent.
 
 ### Naming the run
 
-| You have                | Use                                                    |
-| ----------------------- | ------------------------------------------------------ |
-| a run directory         | `--dir <dir>` - the handle a program holds             |
-| `zen run --json` output | `--dir "$(… \| jq -r .run.dir)"`                       |
-| a run id                | `zen inspect graph <run-id>` or `--run <id>`           |
-| nothing                 | omit everything: the newest run that actually recorded |
-| a session               | `--session <id>`, listed by `zen list --sessions`      |
+| You have                | Use                                               |
+| ----------------------- | ------------------------------------------------- |
+| a run directory         | `--dir <dir>` - the handle a program holds        |
+| `zen run --json` output | `--dir "$(… \| jq -r .run.dir)"`                  |
+| a run id                | `zen inspect graph <run-id>` or `--run <id>`      |
+| a session               | `--session <id>`, listed by `zen list --sessions` |
+
+Always identify the run. Prefer `--dir`, because `zen run --json` returns it
+without requiring the caller to reconstruct project, session and run ids. If
+the task supplies no run handle, obtain one before inspecting; do not rely on
+the newest run implicitly.
 
 **`node` has no room for a run.** Every positional it takes is a node id, so
 name the run with `--dir`, `--run` or `--session`. `zen inspect node <run-id> n13`
-reads the run id as an id and fails. `ask` is the same: one node id, then the
-question.
+reads the run id as an id and fails. Explicit `ask` arguments are the same: one
+node id, then the question.
 
 For `graph` the positional is a run id unless it contains a `/`, in which case
 it is a directory - a run id is a stamp and never has a separator.
 
-With nothing to ask on - a script, `--json`, an agent - `zen inspect` takes the
-newest run of the newest session **that recorded one**. A session exists before
-its first run, so the literally newest session is routinely empty.
-
 ### Reading it cheaply
 
 `--no-style` drops the colour statements and `--no-timing` drops the clock;
@@ -121,6 +150,8 @@ diagram would make you count by eye.
 | `dir`       | the run directory                                    | paste into `--dir`, no reconstruction needed              |
 | `workspace` | the files the run worked on                          | where to go and check what actually changed               |
 | `memory`    | the memory graph the run read                        | absent when the run read none                             |
+|             | recall · search · grep · load · commit, zeros kept   | `commit 0` is nothing saved, whatever the answer says     |
+|             | `nothing committed after N workspace file writes`    | a script or file that worked and was not kept             |
 | `agent`     | the agent it ended on · the one it started as        | two different names means a hand-off happened             |
 | `phase`     | `done`, or the phase and the error                   | an error here is the verdict; the graph is the story      |
 | `nodes`     | total · llm · tool calls · forks                     | the shape and the size of what follows                    |
@@ -247,9 +278,22 @@ zen inspect node n11 --part thinking --part text --dir <run dir>
 zen inspect node n11 --full --dir <run dir>
 ```
 
+An `llm_call` carries two more parts read out of its request, held back the
+same way: `tools`, the tool names that call was offered, one per line, and
+`messages`, the conversation it saw, one clipped line per message with its
+tool calls under it. They answer "was the tool offered" and "what had it seen"
+without opening the request. For the request itself as JSON, `--raw` prints
+one part of one node with no framing, ready for `jq`:
+
+```sh
+zen inspect node n11 --part tools --dir <run dir>
+zen inspect node n11 --part request --raw --dir <run dir> | jq '.messages'
+```
+
 `--part` is repeatable and matches a **prefix**, so `--part call` catches a part
 named `call run_command (toolu_01A…)` without your typing the id. A name that
-matches nothing is an error listing the parts the node does carry.
+matches nothing is reported in a `#` line; when no name matches at all it is an
+error listing the parts the nodes do carry.
 
 ```
 # zen inspect node · 1/41 nodes of run 20260825-143012-a7f3 · ids from `zen inspect graph`
@@ -304,7 +348,7 @@ bug in the node.
 ## Asking the model
 
 ```sh
-zen inspect ask n17 "which instruction made you avoid the test command?" --dir <run dir>
+zen inspect ask n17 --question-file .tmp/ask/<run-id>/n17-tests.md --dir <run dir>
 ```
 
 One `llm_call`, replayed: its recorded system prompt, its messages and its tool
@@ -331,6 +375,10 @@ The questions it is good at are the ones about intent, where the node shows what
 happened but not why: which of two instructions won, why a skill that was
 loaded was not followed, why a tool was used the way it was.
 
+Before writing the question, load skill **zen-inspect-ask**: which node to ask, what
+to rule out first, and how to word a "why did you not..." question so the answer
+quotes the instruction that blocked the better behaviour.
+
 ## Diagnosing
 
 Match the symptom to the row of the header, then open the two or three nodes

package/templates/editor/.github/skills/zen-inspect-ask/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: zen-inspect-ask
+description: 'Use when formulating a question for `zen inspect ask` about an `llm_call` node of a recorded Zenera run - especially a "why did you NOT do X" question (why no `memory_search` first, why no `fork` for independent research branches, why no skill, why no test run). Covers choosing the node, ruling out missing tools before asking, wording the counterfactual so the answer quotes the instruction that blocked the better behaviour, and verifying that quote against the recorded request.'
+---
+
+# Asking a run why it did not do the better thing
+
+`zen inspect ask` replays one recorded `llm_call` - its system prompt, messages
+and tool schemas, byte for byte - with tool calling off and a preamble that
+permits the model to quote its own instructions. Load **zen-inspect** for the
+mechanics (graph, node, flags). This skill is about the one thing that decides
+whether the call is worth its cost: **the question**.
+
+The goal of every question here is the same: **find the sentence in the
+assembled prompt that prevented the good behaviour**, or prove that no sentence
+asked for it. That sentence is what you are about to edit. An answer that does
+not name one is a wasted call.
+
+Non-interactive rule, as in zen-inspect: always pass the node, the question and
+the run. The question is always a file (section 3):
+
+```sh
+zen inspect ask <llm-node-id> --question-file <question file> --dir <run-dir>
+```
+
+Each non-interactive call is a **fresh replay**. It does not remember your
+previous question. A follow-up must restate what it builds on.
+
+## 1. Rule out the cheap causes first
+
+A "why didn't you" question is only about instructions if the model could have
+done it. Check these from the graph and the node before spending a model call -
+each one is a finding on its own, and asking the model about it produces an
+invented rationale.
+
+| Check                                  | How                                                                                     | If it fails, the cause is                          |
+| -------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| The tool was offered on that call      | `--part tools` of that call (below)                                                     | `agents.yaml` - tool not granted, or depth cap hit |
+| The instruction file was in the prompt | the `system_prompt` label lists files: `fork-instructions.md`, `memory-instructions.md` | missing file, or its `requires:` not met           |
+| The skill was loaded                   | a `load_skills` node naming it, or the skill index in `request`                         | binding in `agents.yaml` (`skills:`)               |
+| Memory was already recalled for it     | a `memory_recall` node before the call; `recall 0 nodes`                                | memory content, not behaviour                      |
+| The context still held what it needed  | no `compaction` before the node, or the item is not `hidden by` one                     | compaction, not instructions                       |
+
+```sh
+zen inspect node n9 --part tools --dir <run-dir> | grep -xE 'fork|memory_search|memory_grep'
+```
+
+Only when every row passes is the question "which instruction stopped you".
+
+## 2. Pick the node where the decision was made
+
+The replay ends at the chosen node: the model sees everything up to and
+including that call's own answer, and **nothing after it**. So ask the call that
+made the choice, not the one where the consequence showed up.
+
+| Missing behaviour               | Ask the `llm_call` that...                                                          |
+| ------------------------------- | ----------------------------------------------------------------------------------- |
+| never searched memory           | issued the first tool call of the task (usually the first `llm` after `user input`) |
+| ran independent work in series  | issued the **first** of the sequential calls - it already had the whole plan        |
+| never loaded / followed a skill | chose the substitute action (the `python -c`, the hand-rolled grep)                 |
+| handed off too early            | carries `calls transfer_to_<name>`                                                  |
+| gave up / answered too early    | the last `llm` before `final output`                                                |
+| repeated a failed call          | the one right after the first `ERROR` result                                        |
+
+If the choice repeated (four serial searches), ask **once**, not per step. Ask
+the first call when the question is why it started that way - it already had
+the whole plan. Ask the last call of the sequence when the question is about
+the sequence as a whole - its replay holds every step. Never ask a middle one:
+that gets "I was continuing the pattern I had started", which names no
+instruction.
+
+## 3. Formulate the question
+
+### What the replayed model can see
+
+The model you are asking sees **only its own raw context** at that call: the
+system prompt, the messages up to that point, the tool descriptions, and the
+answer it gave - its text and its tool calls. That is all. So:
+
+- **No node ids, no graph words.** `n7`, `llm_call`, `tool_result`, "branch
+  n12" are your index, not its world. Name what it did by its content: "you
+  ran `grep -rn invoice /workspace/src`", "your first tool call was
+  `read_file` on `src/export.ts`".
+- **Refer to earlier steps by what they were**, as it saw them in its
+  messages: "after `memory_search` returned the export node", "after the
+  third `run_command` failed with exit code 1".
+- **Describe anything after the call yourself, in plain words.** The replay
+  ends at that call; it cannot see what followed. "You then searched three
+  more topics one after another" is something it can only learn from you.
+
+### What the preamble already does
+
+`ask` puts a preamble in front of the replayed system prompt, and it already
+makes the model do the following:
+
+- cite every reason as `[<kind>: <name> › <heading or parameter>] "<verbatim quote>"`,
+  where kind is system prompt, skill, tool description or message
+- trace the decision: the options it could see, which one it took, and which
+  text tipped it
+- say which instruction it followed, which it missed, which two conflicted, and
+  any exception it judged to apply
+- write "no instruction — my own default" instead of making up a source
+- use the answer format the question asks for
+
+**Do not restate any of that in the question.** Asking again for verbatim
+quotes or sources adds a second, differently worded copy of the rule, and the
+model follows whichever it read last.
+
+### The three parts
+
+The question supplies only what the preamble cannot know. Leave a part out and
+the answer drifts to a generic apology.
+
+1. **What it did, by content.** The action as it appears in its own answer,
+   stated as a fact, not an accusation.
+2. **Why not the better action - asked directly.** "Why didn't you use
+   `memory_search` to look up the invoice export first?" Name the action
+   concretely - the tool as it appears in its tool list, and the arguments or
+   branches it could have used - and say it was available. Never ask "did you
+   consider...": its own answer already shows it did not take that path, and
+   the question invites a yes that explains nothing.
+3. **A fixed answer shape.** So answers can be compared across calls and
+   runs, and so an answer without a citation is visibly empty. The shape uses
+   the preamble's citation form.
+
+Write the question to a file with your file-editing tool, then hand `zen` the
+file. The shell never parses the question, so quotes, apostrophes, backticks and
+`$` arrive as written. End the file with this shape, verbatim:
+
+```text
+<the question>
+
+Answer in this shape:
+options: <what you could see at that point, and which one you took>
+steered-by: [<kind>: <name> › <heading or parameter>] "<quote>"   (one per line, or: no instruction — my own default)
+should-have-applied: [<kind>: <name> › <heading or parameter>] "<quote>"   (or: none found)
+exception: [<kind>: <name> › <heading or parameter>] "<quote>"   (or: none)
+conflict: <the two citations that pulled in different directions, or: none>
+missing: <the sentence that, added where, would have made you do it>
+```
+
+```sh
+zen inspect ask n9 --question-file .tmp/ask/<run-id>/n9-memory.md --dir <run-dir>
+```
+
+- One file per question, at `.tmp/ask/<run-id>/<node>-<topic>.md`. `.tmp/` is
+  the project's git-ignored scratch. A tuning loop's brief names its own `ask/`
+  folder instead: use that one.
+- `--question-file` is the only way the question reaches `zen`. Never a quoted
+  argument, a heredoc, `$(cat ...)`, or a Python or Node script around `zen`.
+- A retry (section 5, step 1) or a second opinion (step 4) reuses the same
+  file: add `--model <ref>` and change nothing else.
+
+### Wording rules
+
+- **Ask why not, directly.** "Why didn't you fork the four lookups?" - not
+  "did you consider forking?", not "would forking have been better?".
+- **Do not lead.** "Didn't fork-instructions tell you to parallelise?" gets
+  "yes, I should have" - agreement, not a cause. Name the action, never the
+  instruction you suspect.
+- **Do not ask what it should have done.** That produces a lecture on best
+  practice written from general knowledge, not from its prompt.
+- **One behaviour per question.** Memory and forking in one question get one
+  shallow answer each. Ask twice.
+- **Name the alternative as an action, not a virtue.** "Why didn't you
+  `memory_search` for 'invoice export endpoint'?" - not "why weren't you more
+  efficient?".
+- **Keep the exception line.** A rule with an escape hatch ("unless...", "only
+  when...", "for simple tasks...") is the most common blocker. The preamble asks
+  for exceptions, but a model will not volunteer that it granted itself one
+  unless an empty `exception:` line is waiting for it.
+
+## 4. Templates
+
+The question bodies below replace `<the question>` in the file of section 3.
+Replace every command, tool argument and topic with the run's own. None of them
+mentions a node id: the id goes on the command line, never in the question.
+
+### Did not use memory
+
+```text
+Your first step for this task was run_command `grep -rn 'export' /workspace/src`.
+Why didn't you use memory_search or memory_grep to look up the invoice export
+endpoint first? Both are in your tool list, and an earlier run may already have
+worked it out. What in your instructions, or missing from them, made the
+workspace the first place to look?
+```
+
+### Recalled memory, then redid the work
+
+```text
+memory_search returned a node describing the invoice export endpoint and where
+it is implemented. Your next step was to grep the workspace for the same
+endpoint. Why didn't you use what memory returned, or memory_load that node to
+read it whole? What made the recalled text not enough?
+```
+
+### Did not save what it learned
+
+```text
+To answer this you read eleven files and ran four commands, and your answer
+names facts a later run would need again. memory_commit is in your tool list.
+Why didn't you commit what you worked out before answering?
+```
+
+### Did not fork independent research
+
+```text
+From this point you researched four things one after another: (A) the auth
+flow, (B) the billing schema, (C) the retry policy, (D) the webhook format.
+None of the later lookups used an earlier result. Why didn't you call fork once
+with a branch for each of A-D? fork is in your tool list.
+```
+
+### Did not follow a loaded skill
+
+```text
+You called run_command with `python3 -c` to check the output. The skill
+run-tests is in your context and says to run `npm test`. Why didn't you run
+`npm test`? What made the inline script look acceptable here?
+```
+
+### Misused a tool
+
+```text
+You called memory_commit three times with a `refs` array naming nodes from an
+earlier commit, and each call failed. Why did you expect refs to reach nodes
+committed earlier? Which words in the memory_commit description led you there,
+or what was missing from it?
+```
+
+The same skeleton covers any missing behaviour: **what it did, by content ->
+why not the better action, available -> shape.** The preamble does the rest.
+
+## 5. Verify the answer
+
+The answer is testimony. It is useful because it points at a sentence; it is
+only a finding once the sentence is confirmed.
+
+1. **Grep each quote in the recorded request** - the text between the double
+   quotes of each `[...] "..."` citation.
+    ```sh
+    zen inspect node n9 --part request --dir <run-dir> | grep -F 'Do not fork a sequence'
+    ```
+    A quote that is not there is invented - discard the answer, not just the
+    quote. Ask once more; if it invents again, ask another model (step 4).
+2. **Find every copy.** The blocker often exists twice - once in a house rule,
+   once in a skill with a softer tail. Grep the whole request for a distinctive
+   phrase of it, then grep the project's `agents/` tree for the file to edit.
+3. **Check it is the project's file.** `fork-instructions.md`,
+   `memory-instructions.md`, `tools-instructions.md` are zen's own copies; load
+   **zen-instructions** before changing where that rule lives.
+4. **Second opinion when the self-report is thin.** The model that made the
+   call rationalises; another model reading the same replay often names the
+   conflict more plainly: `--model <ref>`. Ask the identical question: the same
+   question file.
+5. **Reproduce.** After the edit, rerun the case and check the graph: the
+   `tools` header row shows `fork x1` or `memory_search x1` where it did not
+   before. The answer predicted a fix; the graph confirms it.
+
+## 6. Reading the answer
+
+| Answer says                                                | Means                                       | Fix                                                               |
+| ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
+| `should-have-applied: none found`                          | nothing asked for it                        | add a mechanical rule at the point of decision                    |
+| `steered-by: no instruction — my own default`              | the model's habit filled a gap              | add a mechanical rule at the point of decision                    |
+| a rule quoted as `should-have-applied`, nothing against it | the rule is there but not reachable in time | move it earlier, or into the skill loaded for that task           |
+| a `steered-by` quote that argues against the better action | an instruction argued against it            | narrow or remove the blocker, do not add a counter-rule beside it |
+| `conflict:` names two rules                                | two instructions disagree                   | delete one; two copies of a rule is how drift starts              |
+| an exception is quoted as applying                         | a self-judged escape hatch                  | remove the hatch or make its condition checkable                  |
+| no citation at all, general reasoning only                 | the question was too open, or led           | rewrite with the three parts; do not act on it                    |

package/templates/editor/.github/skills/zen-instructions/SKILL.md

@@ -185,7 +185,7 @@ open something, and a running agent sees four: `/workspace`, `/assets`,
 
 It reads `agents/*instructions.md` and exits `1` on any candidate.
 `agents/memory-instructions.md` is exempt: it is worked examples by design, and
-`check-instructions.sh` is the check it actually needs.
+`rules.stale` is the check it actually needs.
 
 ## What `zen check` reports
 
@@ -210,17 +210,9 @@ is quietly a project whose agents were never told how to call a tool. And
 `rules.unreached` deliberately never fires for ours, because they land in every
 project whether the capability is used or not.
 
-The memory copy has a check of its own, byte for byte, because the two files
-drift by trailing whitespace inside tables and that is invisible on screen:
-
-```sh
-.github/skills/zen-memory/scripts/check-instructions.sh        # the verdict
-.github/skills/zen-memory/scripts/check-instructions.sh diff   # every differing line
-.github/skills/zen-memory/scripts/check-instructions.sh fix    # copy the reference over
-```
-
-Never read the two against each other by eye, and never paraphrase the reference
-into prose of your own.
+`rules.stale` compares bytes, so it catches the usual drift - trailing
+whitespace inside a table, invisible on screen. Never compare one of ours
+against anything by eye, and never paraphrase one into prose of your own.
 
 ## Related