@zenera/cli 1.1.21 → 1.1.22

package/dist/tui/markdown.js

@@ -0,0 +1,259 @@
+// ---------------------------------------------------------------------------
+// Terminal Markdown Formatter
+//
+// Formats markdown text into styled ANSI terminal lines wrapped to a width.
+//
+// Consumes the block and span AST from `wrap.ts` and applies terminal styling
+// from `term.ts` (bold, italic, green for code, underline for links, dimmed
+// borders and markers). Line wrapping measures plain characters, so ANSI
+// escape codes never cause lines to wrap early or misalign borders.
+// ---------------------------------------------------------------------------
+import { bold, cut, dim, green, italic, plain, styled, underline } from "../term.js";
+import { blocksOf, gridOf, inlineOf } from "./wrap.js";
+function renderPiece(piece) {
+    if (!styled()) {
+        return piece.text;
+    }
+    let t = piece.text;
+    if (piece.code) {
+        t = green(t);
+    }
+    if (piece.italic) {
+        t = italic(t);
+    }
+    if (piece.bold) {
+        t = bold(t);
+    }
+    if (piece.href) {
+        t = underline(t);
+    }
+    return t;
+}
+function sameStyle(a, b) {
+    return (!!a.bold === !!b.bold &&
+        !!a.italic === !!b.italic &&
+        !!a.code === !!b.code &&
+        a.href === b.href);
+}
+function mergePieces(pieces) {
+    const out = [];
+    for (const p of pieces) {
+        if (!p.text)
+            continue;
+        const last = out[out.length - 1];
+        if (last && sameStyle(last, p)) {
+            last.text += p.text;
+        }
+        else {
+            out.push({ ...p });
+        }
+    }
+    return out;
+}
+function wordsOf(spans) {
+    const words = [];
+    let currentPieces = [];
+    let currentLen = 0;
+    for (const span of spans) {
+        const style = {
+            ...(span.bold ? { bold: true } : {}),
+            ...(span.italic ? { italic: true } : {}),
+            ...(span.code ? { code: true } : {}),
+            ...(span.href ? { href: span.href } : {}),
+        };
+        const parts = span.text.split(/(\s+)/);
+        for (const part of parts) {
+            if (!part)
+                continue;
+            if (/^\s+$/.test(part)) {
+                if (currentPieces.length > 0) {
+                    words.push({ pieces: currentPieces, length: currentLen });
+                    currentPieces = [];
+                    currentLen = 0;
+                }
+            }
+            else {
+                currentPieces.push({ text: part, ...style });
+                currentLen += part.length;
+            }
+        }
+    }
+    if (currentPieces.length > 0) {
+        words.push({ pieces: currentPieces, length: currentLen });
+    }
+    return words;
+}
+function sliceWord(word, at) {
+    const leftPieces = [];
+    const rightPieces = [];
+    let taken = 0;
+    for (const p of word.pieces) {
+        if (taken + p.text.length <= at) {
+            leftPieces.push(p);
+            taken += p.text.length;
+        }
+        else if (taken < at) {
+            const cutIndex = at - taken;
+            leftPieces.push({ ...p, text: p.text.slice(0, cutIndex) });
+            rightPieces.push({ ...p, text: p.text.slice(cutIndex) });
+            taken = at;
+        }
+        else {
+            rightPieces.push(p);
+        }
+    }
+    return [
+        { pieces: leftPieces, length: at },
+        { pieces: rightPieces, length: word.length - at },
+    ];
+}
+export function wrapSpans(spans, width, prefix = '', subsequentPrefix = '') {
+    const w = Math.max(1, width);
+    const words = wordsOf(spans);
+    if (words.length === 0) {
+        return prefix ? [prefix] : [''];
+    }
+    const lines = [];
+    let currentWords = [];
+    const prefixLen = plain(prefix).length;
+    const subLen = plain(subsequentPrefix).length;
+    let currentLen = prefixLen;
+    const flush = () => {
+        if (currentWords.length === 0)
+            return;
+        const linePieces = [];
+        for (let i = 0; i < currentWords.length; i++) {
+            const word = currentWords[i];
+            if (i > 0) {
+                const prev = currentWords[i - 1];
+                const prevPiece = prev.pieces[prev.pieces.length - 1];
+                const nextPiece = word.pieces[0];
+                const sharedStyle = prevPiece && nextPiece && sameStyle(prevPiece, nextPiece)
+                    ? { ...prevPiece, text: ' ' }
+                    : { text: ' ' };
+                linePieces.push(sharedStyle);
+            }
+            linePieces.push(...word.pieces);
+        }
+        const p = lines.length === 0 ? prefix : subsequentPrefix;
+        lines.push(p + mergePieces(linePieces).map(renderPiece).join(''));
+        currentWords = [];
+        currentLen = subLen;
+    };
+    for (let word of words) {
+        const available = lines.length === 0 ? w - prefixLen : w - subLen;
+        while (word.length > available && available > 0) {
+            if (currentWords.length > 0) {
+                flush();
+            }
+            const [head, tail] = sliceWord(word, available);
+            const p = lines.length === 0 ? prefix : subsequentPrefix;
+            lines.push(p + mergePieces(head.pieces).map(renderPiece).join(''));
+            word = tail;
+            currentLen = subLen;
+        }
+        const spaceNeeded = currentWords.length > 0 ? 1 : 0;
+        if (currentLen + spaceNeeded + word.length <= w) {
+            currentWords.push(word);
+            currentLen += spaceNeeded + word.length;
+        }
+        else {
+            flush();
+            currentWords.push(word);
+            const p = lines.length === 0 ? prefix : subsequentPrefix;
+            currentLen = plain(p).length + word.length;
+        }
+    }
+    flush();
+    return lines;
+}
+/**
+ * Render a sequence of AST `Block`s into styled terminal lines wrapped to `width`.
+ */
+export function formatBlocks(blocks, width = 80) {
+    const lines = [];
+    let previous;
+    for (const block of blocks) {
+        if (previous && !(block.kind === 'item' && previous.kind === 'item')) {
+            lines.push('');
+        }
+        previous = block;
+        if (block.kind === 'code') {
+            lines.push(dim(`\u250c\u2500${block.title ? ` ${block.title}` : ''}`));
+            lines.push(...(block.lines ?? []).map((l) => `${dim('\u2502')} ${cut(l, Math.max(0, width - 2))}`));
+            lines.push(dim('\u2514\u2500'));
+        }
+        else if (block.kind === 'table') {
+            for (const [j, row] of gridOf(block).entries()) {
+                let formatted;
+                if (block.align !== undefined && j === 0) {
+                    formatted = row
+                        .map((s) => s.text === '| ' || s.text === ' | ' || s.text === ' |'
+                        ? dim(s.text)
+                        : renderPiece({ ...s, bold: true }))
+                        .join('');
+                }
+                else if (block.align !== undefined && j === 1) {
+                    formatted = dim(row.map((s) => s.text).join(''));
+                }
+                else {
+                    formatted = row
+                        .map((s) => s.text === '| ' || s.text === ' | ' || s.text === ' |'
+                        ? dim(s.text)
+                        : renderPiece(s))
+                        .join('');
+                }
+                lines.push(cut(formatted, width));
+            }
+        }
+        else if (block.kind === 'heading') {
+            const headingSpans = (block.spans ?? []).map((s) => ({ ...s, bold: true }));
+            lines.push(...wrapSpans(headingSpans, width));
+        }
+        else if (block.kind === 'item') {
+            const indentLevel = block.level ?? 0;
+            const marker = block.marker ?? '\u2022';
+            const leadSpaces = '  '.repeat(indentLevel);
+            const prefix = `${leadSpaces}${dim(marker)} `;
+            const subPrefix = `${leadSpaces}${' '.repeat(marker.length + 1)}`;
+            lines.push(...wrapSpans(block.spans ?? [], width, prefix, subPrefix));
+        }
+        else if (block.kind === 'quote') {
+            const quoteSpans = (block.spans ?? []).map((s) => ({ ...s, italic: true }));
+            lines.push(...wrapSpans(quoteSpans, width, `${dim('\u2502')} `, `${dim('\u2502')} `));
+        }
+        else if (block.kind === 'rule') {
+            lines.push(dim('\u2500'.repeat(width)));
+        }
+        else if (block.lines) {
+            lines.push(...block.lines.map((l) => cut(l, width)));
+        }
+        else {
+            lines.push(...wrapSpans(block.spans ?? [], width));
+        }
+    }
+    return lines;
+}
+/**
+ * Format markdown text into styled ANSI terminal lines wrapped to `width`.
+ */
+export function formatMarkdown(text, width = 80) {
+    return formatBlocks(blocksOf(text), width);
+}
+/**
+ * Format inline markdown text (bold, italic, code, links) into a styled ANSI string.
+ * Markers like backticks and asterisks are resolved and removed.
+ */
+export function formatInline(text) {
+    const spans = inlineOf(text);
+    return mergePieces(spans.map((s) => ({
+        text: s.text,
+        ...(s.bold ? { bold: true } : {}),
+        ...(s.italic ? { italic: true } : {}),
+        ...(s.code ? { code: true } : {}),
+        ...(s.href ? { href: s.href } : {}),
+    })))
+        .map(renderPiece)
+        .join('');
+}
+//# sourceMappingURL=markdown.js.map

package/dist/tui/theme.js

@@ -168,7 +168,7 @@ async function queryBackground(timeoutMs = 300) {
         stdout.write(QUERY);
     });
 }
-/** Components come back as 1–4 hex digits, so each is scaled by its own width. */
+/** Components come back as 1-4 hex digits, so each is scaled by its own width. */
 function appearanceOf(r, g, b) {
     const channel = (hex) => parseInt(hex, 16) / (16 ** hex.length - 1);
     const luminance = 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);

package/dist/tui/wrap.d.ts

@@ -154,7 +154,7 @@ export type Align = 'left' | 'right' | 'center';
  */
 export interface Block {
     kind: BlockKind;
-    /** `heading`: its depth, 1–6. `item`: how deep it is nested. */
+    /** `heading`: its depth, 1-6. `item`: how deep it is nested. */
     level?: number;
     /** the fence's info string, when it had one */
     title?: string;

package/dist/validate.js

@@ -15,24 +15,87 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 const AGENTS_DIR = 'agents';
 const HOUSE_RULES = 'agents/instructions.md';
 const INSTRUCTIONS_SUFFIX = '-instructions.md';
+/** How file tools are used; without it the model has schemas only. */
+const FILE_RULES = 'agents/files-instructions.md';
 /** The only place memory is explained to a model; the runtime composes none of it. */
 const MEMORY_RULES = 'agents/memory-instructions.md';
 /** The only place forking is explained to a model; the same holds. */
 const FORK_RULES = 'agents/fork-instructions.md';
 /** The conditioned documents `zen` ships, which land whether or not they apply. */
-const OURS = new Set([MEMORY_RULES, FORK_RULES]);
+const OURS = new Set([FILE_RULES, MEMORY_RULES, FORK_RULES]);
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
 const SKILL_FILE = 'SKILL.md';
 const ASSETS_DIR = 'assets';
 /** What `allow:` and `preload:` accept, so a skill outside it cannot be named. */
 const REFERABLE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+const FILE_TOOLS = [
+    'read_file',
+    'list_dir',
+    'find_files',
+    'write_file',
+    'apply_patch',
+    'move_file',
+    'delete_file',
+];
+const FILE_WRITE_TOOLS = new Set(['write_file', 'apply_patch', 'move_file', 'delete_file']);
+function activeFileTools(selectors) {
+    const active = new Set();
+    if (!selectors?.length) {
+        return active;
+    }
+    for (const raw of selectors) {
+        const drop = raw.startsWith('-');
+        const selector = (drop ? raw.slice(1) : raw).trim();
+        if (selector === '*' || selector === 'files:*' || selector === 'workspace:*') {
+            for (const t of FILE_TOOLS) {
+                if (drop) {
+                    active.delete(t);
+                }
+                else {
+                    active.add(t);
+                }
+            }
+            continue;
+        }
+        const colon = selector.lastIndexOf(':');
+        const name = colon >= 0 ? selector.slice(colon + 1) : selector;
+        const group = colon >= 0 ? selector.slice(0, colon) : undefined;
+        if (FILE_TOOLS.includes(name)) {
+            if (!group || group === 'files' || group === 'workspace') {
+                if (drop) {
+                    active.delete(name);
+                }
+                else {
+                    active.add(name);
+                }
+            }
+        }
+    }
+    return active;
+}
+function hasFileTools(spec) {
+    return activeFileTools(spec.tools).size > 0;
+}
+function hasFileWriteTools(spec) {
+    const active = activeFileTools(spec.tools);
+    for (const t of FILE_WRITE_TOOLS) {
+        if (active.has(t)) {
+            return true;
+        }
+    }
+    return false;
+}
 /** What `requires:` may name. Mirrors `CAPABILITIES` in the loader. */
 const CAPABILITIES = {
     fork: (spec) => Boolean(spec.fork),
     memory: (spec) => Boolean(spec.memory),
     'memory-write': (spec) => spec.memory?.access === 'read-write' || spec.memory?.access === 'full',
     'memory-forget': (spec) => spec.memory?.access === 'full',
+    files: (spec) => hasFileTools(spec),
+    'files-write': (spec) => hasFileWriteTools(spec),
+    workspace: (spec) => hasFileTools(spec),
+    'workspace-write': (spec) => hasFileWriteTools(spec),
 };
 /**
  * Mirrors `readHouseRules` in the loader, in the same order:
@@ -276,7 +339,23 @@ export async function validateProject(opts) {
             });
         }
     }
-    // Present is not the same as current. These three files are copies of ours
+    // The same again for file operations: the file tools need instructions on
+    // discovery, safe reading, and patching. Without them the tools are granted
+    // with only their schemas to explain them.
+    if (config.agents.some((a) => hasFileTools(a))) {
+        const path = join(root, FILE_RULES);
+        if (!existsSync(path) || empty(path)) {
+            add({
+                severity: 'error',
+                code: 'files.uninstructed',
+                where: FILE_RULES,
+                message: 'an agent has file tools, but nothing tells it how to use them — ' +
+                    'the tools are granted with only their schemas to explain them',
+                fix: 'zen check --fix, which writes the current rules back',
+            });
+        }
+    }
+    // Present is not the same as current. These files are copies of ours
     // and nobody is meant to be maintaining them, so bytes that differ are an
     // older `zen`'s — prose about a runtime that has since moved, which reads
     // exactly as authoritative as the version that is true. The frontmatter
@@ -605,7 +684,7 @@ function checkAgent(root, config, spec, entry, available, rules, record, add) {
         try {
             tools = selectTools(available, [...selectors], {
                 where: `${where}.tools`,
-                hint: 'this CLI provides the workspace and sandbox groups',
+                hint: 'this CLI provides the files and sandbox groups',
             }).map((t) => t.name);
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.21",
+    "version": "1.1.22",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.21",
+        "@zenera/neo": "^1.1.22",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

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

@@ -45,12 +45,22 @@ not reconstruct `zen` arguments from memory or call `--help` to discover them.
 **Every runtime capability a project turns on carries obligations that are not
 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-rag-
-schema` or `zen-rag-docs` for an index, `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 opens the skill cannot find what is missing. This applies whatever
-prompted the change - a task scoped to `SPECIFICATION.md` does not narrow it.
+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-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
+opens the skill cannot find what is missing. This applies whatever prompted the
+change - a task scoped to `SPECIFICATION.md` does not narrow it.
+
+**Load `zen-instructions` before writing, editing, reviewing or deleting any
+`agents/*instructions.md`.** They are the house rules, prepended to every
+agent's prompt, and three of them are `zen`'s own copies rather than the
+project's: an edit made inside one is lost at the next `zen check --fix`, `zen
+init` or `zen open`, with no diff to show for it. The skill is what says which
+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.
 
 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
@@ -222,6 +232,7 @@ my-project/
 ├── agents.yaml                   who exists, what they may reach for
 ├── agents/
 │   ├── instructions.md            house rules, prepended to every agent
+│   ├── files-instructions.md      and more - how files are handled
 │   ├── fork-instructions.md       more of them - any `<topic>-instructions.md`
 │   ├── memory-instructions.md     and more - how the graph is used
 │   ├── tools-instructions.md      and more - how tools are called
@@ -631,9 +642,19 @@ follow. So:
 - Anything only one agent needs goes in that agent's prompt instead. If you find
   yourself writing "if you are the router…", you are in the wrong file.
 
-Target 20–60 lines each. If one exceeds ~100, split the stable half out into a
+Target 20-60 lines each. If one exceeds ~100, split the stable half out into a
 preloaded skill.
 
+Four of these documents are **`zen`'s, not the project's** -
+`tools-instructions.md`, `files-instructions.md`, `memory-instructions.md` and
+`fork-instructions.md`. They are replaced by `zen check --fix`, and a copy that
+differs is reported as `rules.stale`. This project's own rules on any of those
+subjects go in a topic file beside them - `agents/files-policy-instructions.md`,
+`agents/memory-policy-instructions.md` and the like, carrying the same
+`requires:`. The `zen-instructions` skill is the full treatment: the two owners,
+the naming and ordering that keeps a policy after the rules it qualifies, and
+every finding these files can produce. Load it before touching one.
+
 ### 3.3 `agents/prompts/<name>.md`
 
 Plain Markdown, no frontmatter. This is the agent's _job description_, appended
@@ -644,7 +665,7 @@ Structure that works:
 ```markdown
 <one sentence: who this agent is and what it owns>
 
-<what it does, as a short numbered procedure or 3–5 rules>
+<what it does, as a short numbered procedure or 3-5 rules>
 
 <what it must NOT do - especially the neighbouring agent's job>
 
@@ -677,7 +698,7 @@ already did, §3.2), never repeats one of them, and never describes the runtime.
 Every line should be an instruction the model can act on or a boundary it can
 check itself against.
 
-Target 10–40 lines. A 200-line prompt is a skill catalog that has not been split
+Target 10-40 lines. A 200-line prompt is a skill catalog that has not been split
 yet.
 
 ### 3.4 Skills
@@ -798,21 +819,21 @@ Three rules follow:
 
 - **Grant the narrowest set the job needs.** An agent that only reviews should
   not be holding the tools that overwrite files.
-- **Grant by group, then subtract.** Write `workspace:*` and take away what this
-  agent must not have - not a hand-picked list of names. The tools in a group are
-  designed to be used together, and a list assembled one name at a time leaves out
-  the companion the model reaches for next: `write_file` without `apply_patch`
-  turns every one-line edit into a whole-file rewrite, and `read_file` without
-  `list_dir` and `find_files` leaves it guessing at paths. A group also tracks the
-  runtime - a tool added to it later reaches the agent, where an enumerated list
-  silently stays behind.
+- **Grant by group, then subtract.** Write `files:*` (or `workspace:*`) and take
+  away what this agent must not have - not a hand-picked list of names. The tools
+  in a group are designed to be used together, and a list assembled one name at
+  a time leaves out the companion the model reaches for next: `write_file`
+  without `apply_patch` turns every one-line edit into a whole-file rewrite, and
+  `read_file` without `list_dir` and `find_files` leaves it guessing at paths. A
+  group also tracks the runtime - a tool added to it later reaches the agent,
+  where an enumerated list silently stays behind.
 - **Say in the prompt when to reach for what.** A granted tool the prompt never
   mentions is used at the model's discretion, which is not the same as never.
 
 Skills can own tools too - `tools:` in a skill's frontmatter (§3.4) names tools
 that refuse to run until that skill is active.
 
-### 3.6 The workspace tools (`workspace:*`)
+### 3.6 The file tools (`files:*`, alias `workspace:*`)
 
 `zen run` builds this set for you, rooted at the session's workspace directory.
 Nothing else reaches the file system, so an agent whose `tools:` does not name
@@ -841,27 +862,27 @@ container involved there is no second name and everything stays relative.
 
 **Selecting them.** A `tools:` entry is a selector, not only a name:
 
-| Selector              | Selects                                           |
-| --------------------- | ------------------------------------------------- |
-| `read_file`           | that one tool                                     |
-| `workspace:read_file` | the same tool, written out in full                |
-| `workspace:*`         | every tool in the group                           |
-| `'*'`                 | every tool the runtime provides                   |
-| `-<any>`              | removes what it matches from the selection so far |
+| Selector                        | Selects                                           |
+| ------------------------------- | ------------------------------------------------- |
+| `read_file`                     | that one tool                                     |
+| `files:read_file`               | the same tool, written out in full                |
+| `files:*` (alias `workspace:*`) | every tool in the group                           |
+| `'*'`                           | every tool the runtime provides                   |
+| `-<any>`                        | removes what it matches from the selection so far |
 
 ```yaml
 agents:
     - name: editor
-      tools: [workspace:*]
+      tools: [files:*]
 
     - name: reviewer
       # Everything except the four that can change something.
-      tools: [workspace:*, -write_file, -apply_patch, -move_file, -delete_file]
+      tools: [files:*, -write_file, -apply_patch, -move_file, -delete_file]
 ```
 
 Selectors apply in the order written, so a `-` line reads as an exception to the
 line above it. Quote a lone `'*'`: unquoted, YAML reads it as an alias and
-refuses the file. `workspace:*` needs no quoting. There is no name globbing -
+refuses the file. `files:*` (and `workspace:*`) needs no quoting. There is no name globbing -
 `read_*` is an unknown tool, because a selector should track a declared set, not
 a naming habit.
 
@@ -983,12 +1004,12 @@ sandbox:
 
 agents:
     - name: builder
-      tools: [workspace:*, sandbox:*]
+      tools: [files:*, sandbox:*]
       sandbox:
           image: docker.io/library/node:22-bookworm-slim
           memory: 8192
     - name: analyst
-      tools: [workspace:*, sandbox:*] # shares the project's container
+      tools: [files:*, sandbox:*] # shares the project's container
 ```
 
 **Write `persist: true` unless you have a reason not to.** By default the
@@ -1053,7 +1074,7 @@ over several pages, and wastes it when a specific document is wanted.
 ```yaml
 agents:
     - name: researcher
-      tools: [exa:*, workspace:*]
+      tools: [exa:*, files:*]
 
     - name: fact-checker
       # Find and read, but never let a model on the far side do the reasoning.
@@ -1839,6 +1860,9 @@ input`, or tools quietly unused). This is not a config error and `zen check`
   publishes no embeddings API. Point it at another provider - §3.1.1.
 - **Changing `dimensions:` on an embedding invalidates every stored vector.**
   Widths are not comparable, so anything already indexed has to be re-embedded.
+  For a `zen rag` index that is `zen rag <subject> restore --dimensions <n>`,
+  which rebuilds from the copies the index already holds rather than from the
+  documents; the same command with `--embedding <ref>` moves it to another model.
 
 ### 7.8 How to choose, in practice
 
@@ -1940,9 +1964,13 @@ Before finishing any change here:
 - [ ] Nothing duplicated between a house-rules file and an agent prompt
 - [ ] 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
-- [ ] No `rules.stale`: the three files that are `zen`'s rather than yours say
+- [ ] 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
+      `zen-instructions` skill loaded, and nothing of this project's was written
+      into one of `zen`'s - §3.2
 - [ ] Every tool and agent referenced by its exact name
 - [ ] Failure paths stated for every instruction that can fail
 - [ ] No facts, rates or figures embedded in a prompt
@@ -1984,7 +2012,7 @@ candidates; these are the judgements to make about each one)**
 - [ ] No agent holds `write_file` without `apply_patch`, or `read_file` without
       `list_dir` and `find_files`
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
-      `move_file` or `delete_file` - subtract them from `workspace:*`
+      `move_file` or `delete_file` - subtract them from `files:*` (or `workspace:*`)
 - [ ] `sandbox:*` is granted only where a shell is actually needed
 - [ ] `sandbox.persist: true`, unless a throwaway rootfs is wanted on purpose
 - [ ] The `sandbox:` image carries what the work needs, rather than the prompt
@@ -2056,6 +2084,7 @@ candidates; these are the judgements to make about each one)**
 | 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            |
+| 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               |
 | Shows no reasoning while it works             | Turn summaries on for that model - §7.6                             |