@zenera/cli 1.1.24 → 1.1.26

package/dist/tui/sandbox.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ---------------------------------------------------------------------------
+// zen sandbox top
+//
+// The resource report, redrawn on a timer. Nothing here measures anything or
+// decides what a figure means: resources.ts samples and lays out, and this
+// file only colours the lines it is handed and owns the keys.
+//
+// The frame is cut to the terminal's height before Ink sees it — a frame
+// taller than the screen scrolls its own top away and every repaint leaves a
+// copy of it behind (see tui/app.tsx).
+// ---------------------------------------------------------------------------
+import { Box, render, Text, useApp, useInput, useStdout } from 'ink';
+import React, { useEffect, useState } from 'react';
+import { layout, SORTS, } from "../resources.js";
+import { resolveTheme } from "./theme.js";
+const message = (err) => (err instanceof Error ? err.message : String(err));
+function styleOf(tone, theme) {
+    switch (tone) {
+        case 'strong':
+            return { bold: true };
+        case 'heading':
+            return { bold: true, color: theme.accent };
+        case 'dim':
+            return { color: theme.chrome.color };
+        case 'good':
+            return { color: theme.code.color };
+        case 'warn':
+            return { color: theme.warn };
+        case 'bad':
+            return { color: theme.line.error.color };
+        case 'accent':
+            return { color: theme.accent };
+        default:
+            return {};
+    }
+}
+function Painted({ line, theme }) {
+    if (line.length === 0) {
+        return _jsx(Text, { children: " " });
+    }
+    return (_jsx(Text, { wrap: "truncate-end", children: line.map((span, i) => (_jsx(Text, { ...styleOf(span.tone, theme), children: span.text }, i))) }));
+}
+function Top({ sampler, intervalMs, explain: start, palette }) {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const [size, setSize] = useState({ columns: stdout.columns || 80, rows: stdout.rows || 24 });
+    useEffect(() => {
+        const resized = () => setSize({ columns: stdout.columns || 80, rows: stdout.rows || 24 });
+        stdout.on('resize', resized);
+        return () => {
+            stdout.off('resize', resized);
+        };
+    }, [stdout]);
+    const [view, setView] = useState();
+    const [failure, setFailure] = useState();
+    const [explain, setExplain] = useState(start);
+    const [sort, setSort] = useState('memory');
+    const [paused, setPaused] = useState(false);
+    useEffect(() => {
+        if (paused) {
+            return;
+        }
+        let stopped = false;
+        let timer;
+        const tick = async () => {
+            try {
+                const next = await sampler.next();
+                if (!stopped) {
+                    setView(next);
+                    setFailure(undefined);
+                }
+            }
+            catch (err) {
+                if (!stopped) {
+                    setFailure(message(err));
+                }
+            }
+            if (!stopped) {
+                timer = setTimeout(() => void tick(), intervalMs);
+            }
+        };
+        void tick();
+        return () => {
+            stopped = true;
+            clearTimeout(timer);
+        };
+    }, [sampler, intervalMs, paused]);
+    useInput((input, key) => {
+        // A pasted or piped key can arrive with a newline behind it.
+        const k = input.trim()[0];
+        if (k === 'q' || key.escape) {
+            exit();
+        }
+        else if (k === 'e' || k === '?') {
+            setExplain((on) => !on);
+        }
+        else if (k === 's') {
+            setSort((now) => SORTS[(SORTS.indexOf(now) + 1) % SORTS.length]);
+        }
+        else if (k === 'p' || input === ' ') {
+            setPaused((on) => !on);
+        }
+    });
+    // One row for the keys, one spare so the frame never reaches the bottom.
+    const rows = Math.max(4, size.rows - 2);
+    const lines = view
+        ? layout(view, {
+            width: size.columns - 1,
+            rows: failure ? rows - 1 : rows,
+            explain,
+            sort,
+            live: intervalMs / 1000,
+        })
+        : [[{ text: 'asking podman…', tone: 'dim' }]];
+    const keys = [
+        `e notes ${explain ? 'off' : 'on'}`,
+        `s sort: ${sort}`,
+        paused ? 'p resume' : 'p pause',
+        'q quit',
+    ].join(' · ');
+    return (_jsxs(Box, { flexDirection: "column", children: [lines.map((line, i) => (_jsx(Painted, { line: line, theme: palette }, i))), failure ? (_jsx(Text, { wrap: "truncate-end", color: palette.line.error.color, children: `  ✗ ${failure}` })) : null, _jsx(Text, { wrap: "truncate-end", color: palette.chrome.color, children: paused ? `paused · ${keys}` : keys })] }));
+}
+/** Runs the live screen until the person leaves it. */
+export async function watch(options) {
+    // Asked before Ink takes the terminal, as tui/app.tsx does.
+    const palette = await resolveTheme(options.theme);
+    const instance = render(_jsx(Top, { ...options, palette: palette }));
+    await instance.waitUntilExit();
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/tui/wrap.d.ts

@@ -15,6 +15,11 @@ export declare function windowOf(text: string, width: number, rows: number): str
 export declare function clip(text: string, width: number): string;
 /** Word wrap. Every returned row is at most `width` columns wide. */
 export declare function wrap(text: string, width: number): string[];
+/**
+ * The first row of a scrolled list, moved as little as possible so that row
+ * `selected` is inside a window of `height` rows over `count` of them.
+ */
+export declare function scrollTop(selected: number, top: number, height: number, count: number): number;
 /** The three footer rows, its margin, the prompt, and a row in hand. */
 export declare const CHROME_ROWS = 7;
 /**

package/dist/tui/wrap.js

@@ -74,6 +74,18 @@ export function wrap(text, width) {
     }
     return out;
 }
+/**
+ * The first row of a scrolled list, moved as little as possible so that row
+ * `selected` is inside a window of `height` rows over `count` of them.
+ */
+export function scrollTop(selected, top, height, count) {
+    const h = Math.max(1, height);
+    let first = Math.min(top, selected);
+    if (selected >= first + h) {
+        first = selected - h + 1;
+    }
+    return Math.max(0, Math.min(first, count - h));
+}
 // ---------------------------------------------------------------------------
 // Dividing the frame
 //

package/dist/usage.d.ts

@@ -0,0 +1,78 @@
+import type { ModelUsage, TokenUsage } from '@zenera/neo';
+/** Set by `zen meta` for everything its agent runs, so all of it lands in one ledger. */
+export declare const LEDGER_ENV = "ZENERA_USAGE_LEDGER";
+/** The meta session whose agent started this process, if one did. */
+export declare const META_SESSION_ENV = "ZENERA_META_SESSION";
+/** The stored prompt that meta session was started with, if any. */
+export declare const META_PROMPT_ENV = "ZENERA_META_PROMPT";
+/**
+ * Where this project's usage goes: the variable when set, else the fine-tuning's
+ * own ledger when the project is being tuned. Elsewhere nothing is recorded.
+ */
+export declare function ledgerPath(projectDir: string): string | undefined;
+interface RowBase {
+    /** when the thing ended */
+    ts: string;
+}
+export interface MetaCallRow extends RowBase {
+    kind: 'meta.call';
+    session?: string;
+    model: string;
+    usage: TokenUsage;
+    cacheWriteTokens?: number;
+    startedAt: string;
+    durationMs: number;
+    traceId?: string;
+    spanId?: string;
+}
+export interface MetaSessionRow extends RowBase {
+    kind: 'meta.session';
+    session: string;
+    /** copilot's own totals for the whole session so far - cumulative across resumes */
+    models: ModelUsage[];
+    exitCode: number;
+    resumes: number;
+    startedAt: string;
+    durationMs: number;
+}
+export interface RunRow extends RowBase {
+    kind: 'run';
+    runDir?: string;
+    session?: string;
+    batchDir?: string;
+    item?: string;
+    ok: boolean;
+    error?: string;
+    stopReason?: string;
+    durationMs?: number;
+    models: ModelUsage[];
+}
+export interface BatchRow extends RowBase {
+    kind: 'batch';
+    batchDir: string;
+    input: string;
+    items: number;
+    ok: number;
+    failed: number;
+    concurrency: number;
+    memory: string;
+    startedAt: string;
+    durationMs: number;
+    models: ModelUsage[];
+}
+export interface AskRow extends RowBase {
+    kind: 'ask';
+    runDir: string;
+    node: string;
+    nodeAgent: string;
+    nodeModel: string;
+    model: string;
+    usage?: TokenUsage;
+    startedAt: string;
+    durationMs: number;
+}
+export type UsageRow = MetaCallRow | MetaSessionRow | RunRow | BatchRow | AskRow;
+/** Appends one row. Never throws: losing a line of accounting must not fail a run. */
+export declare function appendUsage(projectDir: string, row: UsageRow): void;
+export {};
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.js

@@ -0,0 +1,51 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { warn } from "./term.js";
+// ---------------------------------------------------------------------------
+// The usage ledger
+//
+// One JSON line per thing that spent tokens: a meta agent call, a run, a batch,
+// an `inspect ask`. Append-only, so several processes - the meta agent, the
+// batch it started, the ask it is grading with - can write to one file at once.
+// Reports are folded out of it later; nothing here aggregates.
+// ---------------------------------------------------------------------------
+/** Set by `zen meta` for everything its agent runs, so all of it lands in one ledger. */
+export const LEDGER_ENV = 'ZENERA_USAGE_LEDGER';
+/** The meta session whose agent started this process, if one did. */
+export const META_SESSION_ENV = 'ZENERA_META_SESSION';
+/** The stored prompt that meta session was started with, if any. */
+export const META_PROMPT_ENV = 'ZENERA_META_PROMPT';
+/**
+ * Where this project's usage goes: the variable when set, else the fine-tuning's
+ * own ledger when the project is being tuned. Elsewhere nothing is recorded.
+ */
+export function ledgerPath(projectDir) {
+    const set = process.env[LEDGER_ENV]?.trim();
+    if (set) {
+        return set;
+    }
+    return existsSync(join(projectDir, 'finetune'))
+        ? join(projectDir, 'finetune', 'usage', 'ledger.jsonl')
+        : undefined;
+}
+let warned = false;
+/** Appends one row. Never throws: losing a line of accounting must not fail a run. */
+export function appendUsage(projectDir, row) {
+    const path = ledgerPath(projectDir);
+    if (!path) {
+        return;
+    }
+    const meta = process.env[META_SESSION_ENV]?.trim();
+    const line = { v: 1, ...row, project: projectDir, pid: process.pid, ...(meta ? { meta } : {}) };
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify(line)}\n`);
+    }
+    catch (err) {
+        if (!warned) {
+            warned = true;
+            warn(`could not record usage in ${path} - ${err.message}`);
+        }
+    }
+}
+//# sourceMappingURL=usage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.24",
+    "version": "1.1.26",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -52,11 +52,13 @@
         "@google/genai": "^2.18.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.2.80",
-        "@zenera/neo": "^1.1.24",
+        "@zenera/neo": "^1.1.26",
+        "@zenera/view": "^1.1.26",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",
         "react": "^19.2.8",
+        "yaml": "^2.9.0",
         "yauzl": "^3.4.0",
         "yazl": "^3.3.1"
     },

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
@@ -102,29 +113,20 @@ tool access; give tool-based RAG users the configured RAG tools instead. Run
 `zen check` after adding or changing the skill.
 
 Memory has one such obligation and it is absolute: **a project with a `memory:`
-block carries the `zen-memory` skill's `references/memory-instructions.md` in its
-own `agents/memory-instructions.md`.** `zen init` writes both, since it scaffolds
-memory on; what needs watching is a project that deleted the file, or one whose
-copy has fallen behind the reference. Do not read the two files against each
-other - they drift by trailing whitespace inside tables, which is invisible.
-The skill ships the check:
-
-```sh
-.github/skills/zen-memory/scripts/check-instructions.sh       # the verdict
-.github/skills/zen-memory/scripts/check-instructions.sh fix   # copy the reference over
-```
-
-It is a copy, never a transcription - the reference ships inside the project,
-because `zen init` and `zen open` write this whole `.github/` tree, so `fix` is
-just `cp` from one to the other.
+block carries `agents/memory-instructions.md` exactly as `zen` ships it.**
+`zen init` writes it, since it scaffolds memory on; what needs watching is a
+project that deleted the file, or one whose copy has fallen behind. `zen check`
+reports the first as `memory.uninstructed` and the second as `rules.stale` -
+by bytes, so trailing whitespace inside a table, invisible on screen, is caught
+too - and `zen check --fix` repairs both.
 
 Nothing else tells a running agent how the store works, so without it nothing
 forbids an agent from pointing `grep` or `cat` at `/memory` - a read that
-bypasses the audience mask and serves superseded nodes as current. Keep the copy
-byte-identical and put this project's own memory policy in a second topic file,
-`agents/memory-policy-instructions.md`, which is read straight after it: then the
-copy can be re-run after any `zen init` or `zen open` refreshes the reference,
-without losing anything. Never paraphrase the reference into prose of your own.
+bypasses the audience mask and serves superseded nodes as current. Leave the
+file untouched and put this project's own memory policy in a second topic file,
+`agents/memory-policy-instructions.md`, which is read straight after it: then
+`zen check --fix` can replace the first after any upgrade without losing
+anything. Never paraphrase it into prose of your own.
 See §5.3.
 
 A project with a `SPECIFICATION.md` carries one more: **`.spec-sync/` records
@@ -1323,13 +1325,11 @@ derived from `access` and are never listed in `tools:`.
 
 **Memory comes on.** `zen init` writes the block above, `memory: true` on the
 default agent, and the half nobody would guess was part of it:
-`agents/memory-instructions.md`, a copy of the `zen-memory` skill's
-`references/memory-instructions.md`, which the project already holds. Adding
-memory to a project that has none is both of those edits, and a copy that was
-lost or went stale is one command:
+`agents/memory-instructions.md`. Adding memory to a project that has none is
+both of those edits, and a file that was lost or went stale is one command:
 
 ```sh
-.github/skills/zen-memory/scripts/check-instructions.sh fix
+zen check --fix
 ```
 
 It is what tells the agent that the store is reached only through the tools, that
@@ -1341,19 +1341,17 @@ what a node must carry to be worth having, and that a correction is a
 with it - and it carries `requires: [memory]`, so an agent without the store
 never reads a word of it.
 
-**Leave that file as a pure copy.** Anything this project decides for itself -
+**Leave that file untouched.** Anything this project decides for itself -
 which audience holds what, what must never be written down, what an agent is
 expected to commit at the end of a job - goes in
 `agents/memory-policy-instructions.md`. Topic files are read in filename order,
-so the policy lands directly after the rules it qualifies, and the copy stays
-re-runnable: the reference is rewritten by every `zen init` and `zen open`, and
-keeping up with it is then the same one-line command rather than a hand-patch.
+so the policy lands directly after the rules it qualifies, and the file stays
+replaceable: keeping up with a newer `zen` is then `zen check --fix` rather
+than a hand-patch.
 
-`zen check` validates the `memory:` block and says nothing about the rules'
-absence, so this is checked every time, by
-`.github/skills/zen-memory/scripts/check-instructions.sh` and never by reading
-the two files against each other: they drift by trailing whitespace inside a
-table, and the script is what can see that.
+`zen check` reports a missing file as `memory.uninstructed` and any differing
+byte as `rules.stale`. Never compare the file by eye: it drifts by trailing
+whitespace inside a table, and only a byte comparison sees that.
 
 Do not treat memory as a database. It is for things learned that should
 persist. Anything authoritative - a rate, a policy clause, a procedure - belongs
@@ -1430,108 +1428,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
 
@@ -1939,8 +1852,8 @@ ok, `1` failed, `2` usage, `3` invalid project, `4` no usable credential.
 
 ## 9. Review checklist
 
-Four of these are decidable, and are one command - `zen check`, the path sweep,
-the memory copy, the spec-sync record, in that order:
+Three of these are decidable, and are one command - `zen check`, the path sweep,
+the spec-sync record, in that order:
 
 ```sh
 .github/skills/zen-review/scripts/review.sh
@@ -1969,7 +1882,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
@@ -1979,10 +1892,9 @@ Before finishing any change here:
 - [ ] Failure paths stated for every instruction that can fail
 - [ ] No facts, rates or figures embedded in a prompt
 - [ ] No hedging, no meta-talk about the runtime
-- [ ] If any agent has `memory:`,
-      `.github/skills/zen-memory/scripts/check-instructions.sh` exits zero -
-      `agents/memory-instructions.md` is the reference byte for byte - and
-      anything project-specific is in `agents/memory-policy-instructions.md` - §5.3
+- [ ] If any agent has `memory:`, `zen check` reports neither
+      `memory.uninstructed` nor `rules.stale` - and anything project-specific
+      is in `agents/memory-policy-instructions.md` - §5.3
 
 **Paths (§2.5 - `.github/skills/zen-review/scripts/check-paths.sh` finds the
 candidates; these are the judgements to make about each one)**
@@ -2004,6 +1916,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 +2000,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               |
@@ -2115,10 +2030,10 @@ candidates; these are the judgements to make about each one)**
   the turn that follows it - §2.5.
 - **Arithmetic in prose.** A skill that walks the model through a calculation it
   will get wrong, in a folder that could have held the script - §3.4.1.
-- **The unguarded store.** `memory:` turned on and the skill's
-  `references/memory-instructions.md` never copied to
+- **The unguarded store.** `memory:` turned on and no
   `agents/memory-instructions.md`, so nothing tells the agent the store is
-  reached only through the tools - and `zen check` passes throughout - §5.3.
+  reached only through the tools - `zen check` fails with
+  `memory.uninstructed`, and `zen check --fix` writes it - §5.3.
 - **Reviewing a capability without its skill.** A project whose memory, index or
   sandbox was configured by an earlier pass looks finished because it loads. The
   obligations are in the editor skill, not in `agents.yaml` - §0.1.

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

@@ -0,0 +1,33 @@
+---
+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 line after 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.
+A `## The brief` section below that line is what the loop already ran for
+you: section 1 of the skill says how to use it.
+
+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.