@zenera/cli 1.1.24 → 1.1.25

package/templates/editor/.github/copilot-instructions.md

@@ -47,7 +47,10 @@ visible in `agents.yaml` and that `zen check` does not report.** Before
 reviewing or changing a project, list the capabilities it has turned on and load
 the editor skill for each one - `zen-memory` for a `memory:` block,
 `zen-sandbox` for sandbox configuration or shell tools, `zen-rag-schema` or
-`zen-rag-docs` for an index, `zen-sandbox-capacity` before any `zen run batch`,
+`zen-rag-docs` for an index, `zen-code-python` for an agent that writes or runs
+code, `zen-topology` for `handoffs:` or `fork:` on any agent,
+`zen-sandbox-capacity` before any `zen run batch`
+(except under `zen-finetune`, which sets its own concurrency),
 `zen-cli` always. A capability that is already
 configured and already passing `zen check` is exactly the case that looks
 finished and is not: the obligation lives in the skill, so a review that never
@@ -63,6 +66,14 @@ three those are, where a project's own rules on the same subjects go instead,
 how `requires:` conditions a document, and what filename order decides. None of
 that is visible in the file being edited.
 
+**Load `zen-code-python` before writing, editing or reviewing any prompt, skill
+or house rule for an agent that writes or runs code** - any agent holding
+`sandbox:*` or `run_command` - and before shipping a script inside a skill.
+Code an agent writes must be a reusable tool, so that memory can keep it and the
+next similar question runs it instead of writing it again. The skill holds the
+coding rules and decides where they go: a section of a dedicated code agent's
+system prompt, or a coding skill for generic agents that sometimes run code.
+
 First determine whether the target project uses RAG: a `zen rag` command in an
 agent prompt or skill, RAG tools supplied by its host, or a documentation or
 schema index it is expected to consult all count. When it does, also load the
@@ -1430,108 +1441,23 @@ multi-agent instinct suggests.
 
 ### 6.3 Handoffs
 
-- `description:` on the target agent is what the model reads when deciding.
-  Write it as a routing condition: _"Applies the written peril policies to a
-  claim and explains the outcome."_ - not _"The adjuster agent."_
-- Handoffs are bare name strings; there is no per-edge configuration.
-- Self-handoff is a load error.
-- **Every handoff must be returnable.** For every `A → B` there must be a path
-  from `B` back to `A`. Indirect counts - `B → C → A` is a way home - so the
-  rule is that every handoff edge lies on a cycle. `zen check` warns
-  (`handoff.one-way`) on any edge that does not.
-- Handoff collapses history by policy: the receiving agent sees a selection, not
-  the full transcript. Do not assume it saw a detail three turns back; if it
-  matters, put it in the handoff.
-
-**Why the return edge is not optional.** A handoff is a one-way door: control
-moves and stays moved. Nothing hands it back, so an agent reached by a dead-end
-edge owns the conversation for the rest of the session - the next question,
-whatever it is about, is answered by the specialist the router sent the user to.
-The drawn architecture holds for one turn and then quietly stops being the
-architecture.
-
-**Forks are the exception, and the alternative.** A branch runs, answers, and
-control returns to the agent that forked it; the return is the mechanism, not an
-edge anyone has to declare. So there are two shapes and they are not
-interchangeable:
-
-- The other agent should **own the conversation from here** → `handoffs:`, and
-  something on the far side has to lead back.
-- This agent needs **an answer and then carries on** → `fork:`. Never a handoff:
-  a handoff spends the conversation to get the answer. One branch is enough -
-  a fork of one is exactly "ask the specialist and continue".
-
-But the return is **condensed**: `A → fork → B` rejoins as one tool result
-holding B's answer, so A never sees the steps B took - no tool calls, no files
-read, no intermediate reasoning. That is what makes fanning out cheap, and it is
-what to design around: whatever A will need must be _in_ the answer, so say so in
-B's prompt. Work whose value is the trace rather than the conclusion does not
-survive a fork.
+`handoffs: [name, ...]` on an agent gives it one `transfer_to_<name>` tool per
+entry, described by the target's `description:`. Control moves to the target
+and **stays moved** - the target sees the whole transcript and answers every
+later turn until it hands off itself - so every edge needs a path back, and
+`zen check` warns `handoff.one-way` on one that has none.
 
 ### 6.4 Forking (fan-out / join)
 
-Forking is **opt-in per agent**. Without the key the agent is never offered the
-`fork` tool and cannot split, however obviously parallel the work looks:
-
-```yaml
-agents:
-    - name: trunk
-      fork: true # unrestricted: any agent, any number of branches
-
-    - name: sweep
-      fork:
-          agents: [prober] # every branch runs the specialist
-          maxBranches: 6
-```
+`fork:` on an agent - `true`, or `{ agents, maxBranches }` - gives it the `fork`
+tool: N branches, run at once, rejoin as one tool result holding each branch's
+answer. One branch is delegation; several are a fan-out. Without the key the
+agent cannot split, however obviously parallel the work looks.
 
-| Field         | Default              | Meaning                               |
-| ------------- | -------------------- | ------------------------------------- |
-| `agents`      | every declared agent | Which agents a branch may run         |
-| `maxBranches` | unlimited            | Cap on branches per call; minimum `1` |
-
-The **model** decides the split: it names N branches, each with self-contained
-instructions. They run truly concurrently and rejoin as **one tool call and one
-tool result** in the parent's history - so N branches cost the parent
-O(N × summary), not O(N × full history).
-
-Rules worth knowing before you write the key:
-
-- `agents:` **may include the forking agent itself** - unlike `handoffs:`, that
-  is not an error, and one role fanned out over ten items is the common shape.
-  The list reaches the model as an `enum`, so a name outside it cannot even be
-  decoded.
-- A fork of **one** branch is delegation, and it is valid: one assignment run
-  elsewhere, its conclusion returned, its transcript left out of this
-  conversation. Use it when another agent suits the job better, or when the job
-  would fill the caller's context with material it has no use for afterwards.
-- **Branches cannot talk to each other.** If branch B needs branch A's answer,
-  it is a sequence, not a fork - keep it in one conversation.
-- Nesting is capped by the run's `maxForkDepth` (2 by default), so a branch may
-  fork again but not without bound.
-- Fork vs handoff: a handoff is _one_ conversation changing owner; a fork is the
-  _same_ question asked N times at once and merged. **A fork returns; a handoff
-  does not** - which is why a handoff needs a return path (§6.3) and a fork
-  needs nothing.
-
-Choose `context:` deliberately - the model sets it per call, so say in the
-agent's prompt which one this work wants:
-
-- `inherit` - branch gets the full prefix. For work that depends on the case.
-- `compact` - prefix minus tool calls, tool results and recalls: _what was
-  decided_, not the raw noise. **The default for wide fan-outs.**
-- `none` - system prompt plus instructions only. Cheapest; for independent
-  lookups.
-
-Declaring `fork:` only makes the tool available. What a fork costs and what
-survives the join is in `agents/fork-instructions.md`, which carries
-`requires: [fork]` and so reaches exactly the agents holding the key. That file
-is `zen`'s, not yours - `zen check --fix` replaces it, editing it or carrying an
-older copy is reported as `rules.stale`, and deleting it leaves your forking
-agents with the tool schema alone (`fork.uninstructed`). What is
-left to you is _when_, in the terms of this domain - _"When the request covers
-more than one region, fork one branch per region and merge their findings"_ - or
-a weaker model will work through the list serially and never call it. Project
-policy on forking goes in a topic file of your own beside it.
+**Load `zen-topology` before adding or changing either key, and before writing
+a prompt line that says when to delegate.** It holds the key reference, hand-off
+versus fork, which `context` a branch should start from, what each choice costs
+in tokens, prompt cache and time, and how a recorded run shows each mistake.
 
 ### 6.5 Termination
 
@@ -1969,7 +1895,7 @@ Before finishing any change here:
 - [ ] Each `agents/<topic>-instructions.md` is about one capability, and is true
       of every agent it reaches - `requires:` if it is about one of them
 - [ ] If any agent has file tools, `agents/files-instructions.md` is present - §3.6
-- [ ] If any agent has `fork:`, `agents/fork-instructions.md` is present - §6.4
+- [ ] If any agent has `fork:`, `agents/fork-instructions.md` is present - zen-topology §8
 - [ ] No `rules.stale`: the four files that are `zen`'s rather than yours say
       what this version of the runtime does, and `zen check --fix` replaces them
 - [ ] Any change to an `agents/*instructions.md` was made with the
@@ -2004,6 +1930,9 @@ candidates; these are the judgements to make about each one)**
 - [ ] Catalog >~30 entries → `discovery: search`
 - [ ] A skill that ships a script writes its `/skills/<name>/...` path, the agent
       holds `sandbox:*`, and the sandbox image already has the interpreter
+- [ ] Every agent that writes or runs code has the `zen-code-python` rules -
+      in its prompt if it is the dedicated code agent, as a skill otherwise -
+      and nothing else restates or softens them - §0.1
 - [ ] A skill whose procedure needs particular tools, an index or a mounted file
       opens by naming them and says what to do without them - rather than naming
       the agents allowed to load it, which `agents.yaml` already decides - §0.1
@@ -2085,10 +2014,10 @@ candidates; these are the judgements to make about each one)**
 | Answers instead of routing                    | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist                | The target agents' `description:` fields                            |
 | Gets stuck in the agent it routed to          | The target needs a handoff back - §6.3                              |
-| Loses a detail after a handoff                | Say it in the handoff; check the collapse policy                    |
+| Loses a detail after a handoff                | The target sees the whole transcript; its prompt must say to use it |
 | Works through N independent items serially    | `fork:` on that agent, and a prompt line - §6.4                     |
 | Forks when the steps actually depend          | Prompt line: branches cannot see each other                         |
-| Forks a sequence, or loses a branch's working | `agents/fork-instructions.md` is missing or empty - §6.4            |
+| Forks a sequence, or loses a branch's working | `agents/fork-instructions.md` is missing or empty - zen-topology §8 |
 | Edits files blindly or breaks patches         | `agents/files-instructions.md` is missing or empty - §3.6           |
 | Slow and expensive on trivial cases           | Demote that agent's model tier / reasoning effort                   |
 | Fails only on genuinely hard cases            | Promote that agent's tier, or split the hard path out               |

package/templates/editor/.github/prompts/analyze.prompt.md

@@ -0,0 +1,31 @@
+---
+description: Analyze one recorded run of this project - its health, what it wasted, and what to change in the instructions. Name the run (directory or id) after the command, or get the most recent one.
+---
+
+Load the **zen-analyze-run** skill and follow it to analyze one run of this
+project. Everything about how to analyze it is in the skill. If `agents.yaml`
+has a `memory:` key anywhere (`grep -n 'memory:' agents.yaml`), load the
+**zen-memory** skill with it, before you read the run: the memory areas of the
+audit cannot be graded without it.
+
+## Which run
+
+The last line of this prompt may name the run - a run directory or a run id.
+If it does, use it. Words after it like `case=<id> ... feedback=<file>` mean
+the tuning loop sent you: follow section 7 of the skill and write that file.
+
+If it does not, list this project's most recent runs, newest first:
+
+```sh
+zen list --runs --json --limit 500 \
+  | jq -r --arg p "$PWD/" '[.[] | select(.dir | startswith($p))][:5][]
+      | "\(.id)  \(.agent // "-")  \(.error // .stopReason // "-")  \(.dir)"'
+```
+
+- If there are none, stop and say this project has no runs yet.
+- If you can ask the user a question, show that list and ask which run to
+  analyze, with the newest as the default.
+- If you cannot ask, take the newest. Say which run you picked, and that it was
+  picked as the most recent, at the top of the report.
+
+Then give the run to the skill.

package/templates/editor/.github/prompts/dataset.prompt.md

@@ -0,0 +1,108 @@
+---
+description: Build or refresh this project's dataset - every case read from its sources with a class, complexity, tags, a verbatim rubric and an anchor - re-reading only the sections that changed since the last revision. Name a source after the command to add it, `rebuild` to read everything again, or a case and what to fix.
+---
+
+Keep `dataset/` in step with its sources. **Load the `zen-dataset` skill before
+anything else**, and `zen-cli` for the command reference. The skill holds the
+extraction rules and every verb; this prompt is the order of the work. If
+loading a skill fails, read `.github/skills/<name>/SKILL.md` with your file tool
+before going on.
+
+You never run cases, never edit `agents/`, and never edit a source. Only
+`zen meta dataset` writes `dataset/` - never a file tool, never a script.
+
+This prompt is **reentrant**: the state on disk says what to do, so running it
+twice in a row does nothing the second time.
+
+## 1. Where things stand
+
+```sh
+zen meta dataset status
+zen meta dataset drift
+zen meta dataset ls --note rubric-suspect
+```
+
+Say in three lines: the revision and case count, the sources, and how many
+sections are `changed`, `gone` or `uncovered`.
+
+## 2. What to do
+
+The last line of this prompt may hold words. Then read the table top down and
+take the first row that fits:
+
+| State                                    | Do                                                                    |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| the words name a case and a fix          | that fix only, with `update`, `retire` or `reanchor` - then section 6 |
+| the words say `rebuild`                  | read every source in full, as a whole proposal - section 3            |
+| the words name a source file             | read that file in full, add it as a `--partial` proposal - section 3  |
+| no dataset, and no source named anywhere | **stop**: say which training set to name. The only stop               |
+| no dataset                               | read every source `SPECIFICATION.md` points at - section 3            |
+| drift reports anything                   | read only the drifted sections - section 3                            |
+| drift is clean                           | nothing to do: report the status and stop                             |
+
+Never ask a question mid-run - nobody is there to answer it. What you could not
+decide goes into the report and onto the case as a note.
+
+## 3. Read the sections
+
+Read each section yourself and write the cases out by the skill's rules: the
+rubric **verbatim**, class from the source's own distinctions, complexity from
+the trajectory the query demands, an anchor on every case, and **the id a case
+already has** when you re-read its section. Write them to
+`.tmp/dataset/proposal.json`.
+
+On a refresh, the proposal holds only the cases of the drifted sections, and is
+applied `--partial`. A case whose section changed but which still asks, expects
+and is judged the same goes in unchanged - that is how its drift is settled.
+
+## 4. Settle what is gone and what is new
+
+Every `gone` and `uncovered` line from step 1 gets an answer, or the next drift
+check reports it again:
+
+- **gone** - the section was deleted: `retire <id> --why "…"`. It was renamed
+  or moved: `reanchor <id> --heading "…" --why "…"`.
+- **uncovered** - it holds queries: they are new cases in the proposal. It does
+  not (an introduction, a glossary): `ignore <file> --heading "…" --why "…"`.
+
+## 5. Apply
+
+```sh
+zen meta dataset apply .tmp/dataset/proposal.json [--partial] --dry-run
+```
+
+Check the dry run against what you meant before writing anything:
+
+- nothing `retired` you did not intend - a whole proposal retires every case it
+  leaves out
+- no id changed for a case you only re-read
+- every `restarted` case is one whose input, rubric or expected answer really
+  changed in the source
+
+Then the same command without `--dry-run`, with `--why` naming what changed in
+the source.
+
+## 6. Check
+
+```sh
+zen meta dataset drift
+zen meta dataset status
+```
+
+Drift must be clean. The count per class must match a count you take from the
+source by hand. Every media path must exist - apply refuses one that does not,
+so a refusal here is a path to fix, not a step to skip.
+
+## 7. Report
+
+- the revision, and what changed: added, updated, retired, restored and
+  **restarted** cases, by id
+- cases per class and per complexity, and how many have a rubric
+- what restarted means for whoever runs the cases next: their earlier results
+  are about a different question - `zen meta dataset sample --restarted` lists
+  them
+- every case with an open `rubric-suspect` note, and what the source would
+  need to say
+- what you could not decide, each with the case or section it is about; leave
+  each one on its case as well:
+  `zen meta dataset note <id> --kind observation -m "…"`

package/templates/editor/.github/prompts/finetune-apply.prompt.md

@@ -0,0 +1,91 @@
+---
+description: Apply a batch of improvement requests from the tuning loop to the project's prose - merge them into patterns, edit prompts, skills and policy files, and record what was done with each. Run by `zen meta finetune`; the last line names the apply directory.
+---
+
+The tuning loop has collected improvement requests from several cases and
+wants them applied **together**. The last line of this prompt names the apply
+directory. Load the `zen-instructions` skill before you edit anything under
+`agents/`, `zen-memory` when any request is from a run with memory, and
+`zen-code-python` when any request touches an agent that writes or runs code.
+
+## What you are given
+
+- `<apply dir>/inputs.json` - the requests: each has `id` (`<case>@<phase>-<attempt>`),
+  `case`, `phase` (`nomem` or `mem`), `summary`, `improvements` (each with `id`,
+  `kind`, `file`, `change`, `why`, `expect`) and `file`, the feedback it came from.
+  The analysis behind each is `analysis.md` beside that file - read it when an
+  improvement is unclear.
+- Every earlier `finetune/applies/*/decisions.json` and `changes.md` - what
+  was already tried. Do not re-apply a rule an earlier apply added and a later
+  run showed did not work; change it instead.
+- `<apply dir>/check.log`, if it exists: your previous attempt left the project
+  failing `zen check`, and the edit was undone. Read it first.
+
+## What to do
+
+1. **Merge before editing.** Group the improvements by the behaviour they fix.
+   Several cases asking for the same thing in different words is one rule.
+   Two that contradict each other: decide, and say why.
+2. **Generalise.** Every rule must hold for queries no case asked. Never write
+   a case's answer, its ids or its data into the prose - if a request only
+   makes sense for its one case, reject it.
+3. **Edit** prompts under `agents/prompts/`, skills under `agents/skills/`,
+   `agents/instructions.md` and `agents/<topic>-policy-instructions.md`
+   (create the policy file when the rule belongs to one capability). Requests
+   from runs **with memory** change only the memory policy -
+   `agents/memory-policy-instructions.md` - or the memory paragraph a request
+   names.
+4. **Never edit** `agents.yaml`, `agents/memory-instructions.md`,
+   `agents/tools-instructions.md`, `agents/fork-instructions.md` or
+   `agents/files-instructions.md`, nor anything outside `agents/`. A request
+   that needs one of those is **structural**: record it, do not apply it.
+5. **Check**: `zen check --no-models --no-sandbox` must pass when you finish.
+
+## What to write
+
+- `<apply dir>/changes.md` - read by a person deciding whether to trust this
+  apply, so leave nothing out. One section per file you touched:
+
+    ```markdown
+    ## agents/prompts/default.md
+
+    **Answers:** plan-day@nomem-1 i1, long-list-3@nomem-1 i1 (merged)
+
+    **The pattern:** what the cases did wrong, in one paragraph, with the node
+    ids from their analyses - not a case's answer.
+
+    **Before:** the sentence or section as it was, quoted (or "new section").
+
+    **After:** the text as it is now, quoted.
+
+    **Why it generalises:** which queries beyond these cases it changes, and
+    which it must not.
+
+    **Expect:** what the next run's graph should show if it worked.
+    ```
+
+    Then a section **Not applied**: every rejected or structural improvement, with
+    why.
+
+- `<apply dir>/decisions.json` - a decision for **every** improvement of every
+  request, nothing skipped:
+
+```json
+{
+    "plan-day@nomem-1": {
+        "i1": { "decision": "applied", "note": "agents/prompts/default.md - planning section" },
+        "i2": { "decision": "merged", "note": "same rule as long-list-3@nomem-1 i1" }
+    },
+    "long-list-3@nomem-1": {
+        "i1": { "decision": "applied", "note": "agents/pagination-policy-instructions.md" },
+        "i2": { "decision": "structural", "note": "needs a tool in agents.yaml" },
+        "i3": { "decision": "rejected", "note": "only true for this case's data" }
+    }
+}
+```
+
+`decision` is one of `applied`, `merged`, `rejected`, `structural`. The note is
+one line a person reads in the case's FEEDBACK.md.
+
+Your answer is a short summary: how many rules, which files, and anything
+structural the user must decide.