@zenera/cli 1.1.16 → 1.1.17

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

@@ -1,6 +1,6 @@
 ---
 name: zen-memory
-description: How agent memory is organised and how to configure it in `agents.yaml` - the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
+description: How agent memory is organised and how to configure it in `agents.yaml` - the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes the usage rules every memory-enabled project must carry in `agents/memory-instructions.md` (references/memory-instructions.md) and the script that says whether that copy is still current (scripts/check-instructions.sh), what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
 ---
 
 # Memory
@@ -379,11 +379,14 @@ node explaining what it is and the graph cannot acquire orphans. To change a
 remembered file: copy it into the workspace, edit it there, commit the new one
 and link it with `SUPERSEDES` to the old.
 
-| Commit as | When                                                                      |
-| --------- | ------------------------------------------------------------------------- |
-| `file`    | It is runnable, or it is the artifact itself: a script, a config, a query |
-| `snippet` | It is a few lines that only make sense read: a request body, a fragment   |
-| `fact`    | It is a sentence. A file containing one sentence is a fact in a costume   |
+The node text describes and locates; the file carries the content. Reach for a
+node with no file only when the whole of what you know fits on one line.
+
+| Commit as | When                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `file`    | It is content - a script, a config, a query, a passage, an assembled answer |
+| `snippet` | It is a few lines that only make sense read, and nothing will ever run them |
+| `fact`    | It is one line. A file containing one sentence is a fact in a costume       |
 
 ## Memory in front of a `zen rag` index
 
@@ -400,18 +403,26 @@ it is entirely a matter of **what you commit**.
 | Freshness       | as fresh as the last `index`                                    | as stale as it was allowed to get |
 | Cost of a query | one embedding round trip (`search`), or nothing (`list`/`grep`) | already in the prompt             |
 
-So: **never copy index content into memory.** A schema pasted into a node goes
-stale silently and the index already answers in milliseconds; a documentation
-passage quoted into a node outlives the release it was true for and will look
-exactly as authoritative when it is wrong.
+So: **never copy content out of an index that still changes.** A schema pasted
+into a node goes stale silently and the index already answers in milliseconds; a
+documentation passage quoted into a node outlives the release it was true for
+and will look exactly as authoritative when it is wrong.
+
+A **pinned** index is the exception, and a real one. Docs indexed from a
+released version or a versioned reference tree cannot change under the memory,
+so a passage taken out of one stays true as long as the project stays on that
+version. Keep it as a `file` node whose text names the documents and line ranges
+and says which version it was. That is as well as the route, never instead of
+it.
 
-What memory should hold is the **route** - the resolution, not the source:
+What memory should hold first is the **route** - the resolution, not the source:
 
 | Commit                                                                            | Kind               | Because                                                                           |
 | --------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
 | The endpoint that turned out to be the answer, and its shape                      | `operation`        | A `search_api` costs a round trip and returns five ranked guesses; this names one |
 | The sequence of calls that was necessary                                          | `plan`             | No ranking finds an ordering. It is not in the document                           |
 | Where the answer lives in the docs - document name, heading, line range           | `fact`             | `zen rag docs show` reads it back verbatim and current                            |
+| The passage itself, when the index is pinned to a released version                | `file`             | It cannot change under you, and the pointer alone makes the next run re-read it   |
 | A convention the index cannot state - auth, casing, base path, the error envelope | `fact`             | It is not in the graph, and it is wrong to re-derive it every run                 |
 | Where the index itself is                                                         | `fact`             | `-d` or `$ZEN_SCHEMA_DB`. An agent cannot guess a path                            |
 | A working request body, or a script that drives the API                           | `snippet` / `file` | The thing you would otherwise write again                                         |
@@ -451,8 +462,12 @@ cheap and settles it.
 ### The project skill is where this is written down
 
 An index used by a project needs a skill in that project describing it - see
-`zen-rag-schema` and `zen-rag-docs`. Memory policy belongs in the same skill,
-because it is the same subject:
+`zen-rag-schema` and `zen-rag-docs`. The memory policy that is **about the
+index** belongs in that skill, because it is the same subject and it is read at
+the moment the index is. Policy that holds whatever the agent is doing -
+audiences, what must never be written down - goes in
+`agents/memory-policy-instructions.md` instead, which every agent gets whether
+it loads the skill or not.
 
 ```md
 - Recalled routes are a shortcut, not authority. Confirm with `list_api --name`
@@ -460,10 +475,61 @@ because it is the same subject:
 - After solving something the index made you work for, commit it: the
   `operation` you ended on, linked to the `task` that asked and any `fact` you
   had to discover. Phrase the text as the question, not as the operation id.
-- Never commit schema text or documentation passages. Commit the pointer -
-  document, heading, line range - and read it back with `zen rag docs show`.
+- Never commit schema text or documentation passages copied out of a document
+  that still changes. Commit the pointer - document, heading, line range -
+  alongside what you concluded from it, and read the passage back with
+  `zen rag docs show` to check the conclusion still holds.
+- Our docs are indexed from the pinned 1.4 tree, so a passage out of them is
+  safe to keep whole: commit it as a `file` node headed with the documents and
+  line ranges, next to the pointer and the conclusion.
+```
+
+## The house rules
+
+**Every project that enables memory carries `references/memory-instructions.md`
+in its own `agents/memory-instructions.md`**, as part of turning memory on. That
+file is how the agent is told to use the store: read and search it only through
+the tools, never through `/memory` itself, and what a node must carry to still be
+worth having.
+
+`zen init` writes it, because the projects it scaffolds have memory on from the
+first run. Two cases are left to check by hand: a project that turned memory on
+afterwards, and one whose copy has drifted from the reference or was deleted.
+
+Neither is checked by eye. The skill ships the check, and it is one command:
+
+```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
 ```
 
+It says whether this project turns memory on at all, exits non-zero on a copy
+that is missing or stale, and prints the `cp` that repairs it. When the only
+difference is trailing whitespace it says so - that is the usual drift, it is
+invisible on screen, and it is the reason reading the two files side by side
+never caught it.
+
+It is a copy, not a transcription - this reference already sits in the project,
+because `zen init` and `zen open` write the whole `.github/` tree, and they write
+it from the same file the project's copy came from. What `fix` runs, from the
+project root, is exactly:
+
+```sh
+cp .github/skills/zen-memory/references/memory-instructions.md agents/memory-instructions.md
+```
+
+Everything the project keeps under `agents/` named `<topic>-instructions.md` is
+prepended to every agent, in filename order, so this belongs in its own document
+rather than as another section of `agents/instructions.md` - it arrives with
+memory and it leaves with it.
+
+**Keep that file a pure copy.** Project-specific policy - audiences, what must
+never be written down, what an agent commits at the end of a job - goes in
+`agents/memory-policy-instructions.md`, which filename order puts directly after
+it. Then keeping up with a changed reference is the same one command again,
+rather than a hand-patch around prose that has to be preserved.
+
 ## Inspecting and repairing it
 
 ```
@@ -524,6 +590,9 @@ agents:
 
 ## Review checklist
 
+- [ ] `.github/skills/zen-memory/scripts/check-instructions.sh` exits zero, so
+      `agents/memory-instructions.md` is the reference byte for byte - and
+      project policy lives in `agents/memory-policy-instructions.md`.
 - [ ] `memory.embedding` is set, and was set before the graph had content.
 - [ ] Every agent that should learn has a `memory:` binding - the top-level
       block alone enables nothing.
@@ -538,18 +607,21 @@ agents:
 
 ## When it goes wrong
 
-| Symptom                                           | Cause                                                                                                      |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| The `memory_*` tools are missing                  | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
-| `zen memory` says the project has none            | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
-| Recall finds a memory only when reworded          | No embedder. `zen memory stats` says `embedding none`                                                      |
-| Recall finds nothing after changing the embedder  | Refused rather than mixed - a manifest records the model. Re-embed or change it back                       |
-| Vectors fewer than nodes                          | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
-| The graph fills with restated requests            | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
-| A wrong memory keeps coming back                  | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
-| An agent cannot see a node you can                | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
-| "this agent cannot remember files"                | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
-| A remembered file will not run                    | It is not self-contained - it referenced the workspace it was written in                                   |
-| Recollections are large and unhelpful             | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
-| The model recalls a route the API no longer has   | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |
-| A second run of the same project refuses to start | The directory lock. A lock whose process is gone is stale and is taken over                                |
+| Symptom                                             | Cause                                                                                                      |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
+| `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
+| Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                      |
+| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Re-embed or change it back                       |
+| Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
+| The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
+| An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it |
+| A recalled fact cannot be checked or continued      | Nodes were committed with no provenance. The block's "say where it came from" rule is what prevents it     |
+| Recall returns pointers and the run re-reads it all | Content was committed as `text` alone. A node's text describes and locates; the content belongs in a file  |
+| A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
+| An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
+| "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
+| A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                   |
+| Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
+| The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |
+| A second run of the same project refuses to start   | The directory lock. A lock whose process is gone is stale and is taken over                                |

package/templates/editor/.github/skills/zen-memory/scripts/check-instructions.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Whether this project's memory house rules are still the rules.
+#
+#   check-instructions.sh          diff the copy against the reference
+#   check-instructions.sh diff     the same, showing every differing line
+#   check-instructions.sh fix      overwrite the copy from the reference
+#
+# `agents/memory-instructions.md` is a *copy* of the `zen-memory` skill's
+# `references/memory-instructions.md`, and the reference is rewritten by every
+# `zen init` and `zen open`. So the copy goes stale silently, and it drifts by
+# trailing whitespace inside tables, which no one can see by reading. That is
+# the whole reason this is a script and not a checklist line.
+#
+# Run it from anywhere; it finds the project root from its own location.
+
+set -eu
+cd "$(dirname "$0")/../../../.."
+
+COPY=agents/memory-instructions.md
+REFERENCE=.github/skills/zen-memory/references/memory-instructions.md
+REMEDY="cp $REFERENCE $COPY"
+
+if [ ! -f "$REFERENCE" ]; then
+    echo "check-instructions.sh: no $REFERENCE in $PWD" >&2
+    echo "check-instructions.sh: run \`zen open\` to rewrite the .github tree" >&2
+    exit 2
+fi
+
+# The project turns memory on when something declares it — the top-level block
+# or an agent's binding — so any `memory:` key in the configuration counts.
+# The config is found by name, in the order a run finds it.
+config() {
+    for file in agents.yaml agents.yml agents/agents.yaml agents/agents.yml; do
+        if [ -f "$file" ]; then
+            echo "$file"
+            return 0
+        fi
+    done
+}
+
+uses_memory() {
+    # `|| true` because no configuration at all is an answer, not a failure.
+    conf="$(config || true)"
+    if [ -z "$conf" ]; then
+        return 1
+    fi
+    grep -Eq '^[[:space:]]*(-[[:space:]]+)?memory:' "$conf"
+}
+
+# The file with every line's trailing whitespace removed. Two of these being
+# equal is the drift nobody can see by reading, named as such.
+trimmed() {
+    sed 's/[[:space:]]*$//' "$1"
+}
+
+report() {
+    if uses_memory; then
+        echo "memory: on"
+    else
+        echo "memory: off"
+    fi
+
+    if [ ! -f "$COPY" ]; then
+        if uses_memory; then
+            echo "missing: $COPY"
+            echo "remedy: $REMEDY"
+            return 1
+        fi
+        echo "ok: no copy, and nothing needs one"
+        return 0
+    fi
+
+    if cmp -s "$REFERENCE" "$COPY"; then
+        if ! uses_memory; then
+            # Harmless, but it is rules for a capability nothing turned on.
+            echo "note: the copy is current, but no agent has a memory: binding"
+        fi
+        echo "ok: $COPY is the reference, byte for byte"
+        return 0
+    fi
+
+    echo "drift: $COPY differs from the reference"
+    # Said out loud because it is invisible on screen, and is the usual cause:
+    # a trailing space inside a table, or a lost final newline.
+    if [ "$(trimmed "$REFERENCE")" = "$(trimmed "$COPY")" ]; then
+        echo "drift: trailing whitespace only — nothing you could have seen"
+    fi
+    echo "remedy: $REMEDY"
+    return 1
+}
+
+show_diff() {
+    report || true
+    # `-L` names the two sides, since both files are called the same thing.
+    diff -u -L reference -L "$COPY" "$REFERENCE" "$COPY" || true
+    # The report's verdict, not the diff's.
+    report >/dev/null
+}
+
+fix() {
+    cp "$REFERENCE" "$COPY"
+    echo "wrote: $COPY"
+    echo "note: project policy belongs in agents/memory-policy-instructions.md"
+}
+
+case "${1:-status}" in
+    status) report ;;
+    diff) show_diff ;;
+    fix) fix ;;
+    *)
+        echo "usage: check-instructions.sh [status|diff|fix]" >&2
+        exit 2
+        ;;
+esac

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

@@ -0,0 +1,123 @@
+---
+name: zen-review
+description: Checking a project before committing - the four mechanical checks `/review-project` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/review-project`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
+---
+
+# Reviewing a project
+
+A review of an agent project is two jobs wearing one name. One half is
+decidable - a schema is valid or it is not, a path resolves or it does not, a
+copy matches its reference or it does not - and a human doing it by hand gets it
+wrong in the same three places every time. The other half is judgement: whether
+an agent has one job, whether a description routes, whether a number is in the
+wrong file.
+
+This skill owns the first half, so the prompt can be all of the second.
+
+## The one command
+
+From the project root, or anywhere at all:
+
+```sh
+.github/skills/zen-review/scripts/review.sh
+```
+
+It runs four checks in the order a reviewer needs them and prints a summary:
+
+| Step        | Runs                                       | Owns                                         |
+| ----------- | ------------------------------------------ | -------------------------------------------- |
+| `zen check` | the CLI                                    | everything decidable about the configuration |
+| `paths`     | `zen-review/scripts/check-paths.sh`        | paths a running agent cannot open - §2.5     |
+| `memory`    | `zen-memory/scripts/check-instructions.sh` | the house-rules copy, byte for byte - §5.3   |
+| `spec-sync` | `zen-spec-sync/scripts/snapshot.sh status` | whether the record of the last pass is sound |
+
+Every step runs even when an earlier one fails, because a review that stops at
+the first problem is one somebody has to run four times. The exit code is `1` if
+any step wants attention and `0` if none does. `review.sh fast` passes
+`--no-models --no-sandbox` to `zen check`, which is the right call while
+iterating and the wrong one before committing - a key that authenticates says
+nothing about the model id it is spent on.
+
+Nothing below matters while `zen check` fails. Report what it said and fix that
+first.
+
+## The two scripts this skill ships
+
+### `check-paths.sh` - the §2.5 sweep
+
+A running agent's whole world is four paths: `/workspace`, `/assets`, `/skills`
+and `/memory`. Every path-shaped token in `agents/*instructions.md`,
+`agents/prompts/*.md` and a skill's markdown is read by a model as an
+instruction to open something, so anything outside those four is an instruction
+to open a file that is not there.
+
+```sh
+.github/skills/zen-review/scripts/check-paths.sh        # each candidate, with file and line
+.github/skills/zen-review/scripts/check-paths.sh raw    # the tokens alone, unfiltered
+```
+
+It exits `1` whenever it prints a candidate, because the list is meant to be
+emptied or explained rather than skimmed. It strips urls before tokenising, skips
+a handful of English constructions that contain a slash, and leaves
+`agents/memory-instructions.md` out entirely - that file is worked examples by
+design, and `check-instructions.sh` is the check it actually needs.
+
+Everything it does print is either noise the script has not learned yet or a
+real finding. There is no third case. A candidate that is genuinely noise is a
+one-line addition to `NOISE` in the script - **upstream**, see below, not in the
+copy sitting in this project.
+
+`raw` is the sweep with nothing filtered, for when you suspect the filter.
+
+### `check-instructions.sh` - the memory house rules
+
+Lives in the `zen-memory` skill, because it is about memory and it is read at
+the moment that skill is:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh        # the verdict
+.github/skills/zen-memory/scripts/check-instructions.sh diff   # and every differing line
+.github/skills/zen-memory/scripts/check-instructions.sh fix    # copy the reference over
+```
+
+`agents/memory-instructions.md` must be a byte-identical copy of the `zen-memory`
+skill's `references/memory-instructions.md`, and the reference is rewritten by
+every `zen init` and `zen open`, so the copy goes stale without anyone touching
+it. It drifts by **trailing whitespace inside tables**, which is invisible on
+screen - this is the check no one should be asked to make by eye. When the
+difference is whitespace alone the script says so, because that is the usual
+cause and the least believable finding.
+
+`fix` is the one-line `cp` and nothing else. Project policy belongs in
+`agents/memory-policy-instructions.md`, which filename order puts directly after
+the copy - see the `zen-memory` skill.
+
+## What has no check, on purpose
+
+Not because it would be hard, but because the answer would be wrong:
+
+- **Whether an agent has one job.** Read the prompt.
+- **Whether a description routes.** Two overlapping descriptions both parse.
+- **Whether a fact belongs in a skill.** A threshold in a prompt is valid YAML.
+- **Whether a tool grant is justified.** `zen check` confirms the selector
+  resolves, never that the agent needs it.
+- **Whether the newest spec-sync history entry is honest.** A pass can claim
+  anything; only reading the diff says whether it did it.
+
+That list is `/review-project`, and §9 of the copilot instructions is the long
+form. Run the script first so the prompt is spent on this.
+
+## Where these scripts live, and why edits to them vanish
+
+`zen init` and `zen open` rewrite the whole `.github/` tree from the version of
+`zen` in hand. These scripts arrive with it, so a change made to the copy in a
+project is gone at the next `open`. A filter that should hold for every project
+belongs in the distribution - `packages/cli/templates/editor/.github/skills/` in
+the @zenera/neo repository - and reaches this project the next time the tree is
+written.
+
+Do not confuse these with a project's own scripts. `agents/skills/<name>/scripts/`
+is run by **the project's agents**, inside the sandbox, at
+`/skills/<name>/scripts/…`. `.github/skills/<name>/scripts/` is run by **the
+editor's assistant**, on the host, at a workspace path. The two have different
+readers and neither can see the other.

package/templates/editor/.github/skills/zen-review/scripts/check-paths.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Every path-shaped token a running agent would be told to open, minus the ones
+# that exist. The §2.5 sweep, as a script rather than a command to retype.
+#
+#   check-paths.sh          each candidate, with the file and line it is on
+#   check-paths.sh raw      the tokens alone, unfiltered — the sweep itself
+#
+# A running agent sees four paths: /workspace, /assets, /skills and /memory.
+# Everything else printed here is either noise this script has not learned yet
+# or an instruction to open a file that is not there. There is no third case,
+# which is why this exits non-zero whenever it prints one: the list is meant to
+# be emptied or explained, not skimmed.
+#
+# Run it from anywhere; it finds the project root from its own location.
+
+set -eu
+cd "$(dirname "$0")/../../../.."
+
+# What a path looks like in prose. §2.5 of the copilot instructions describes
+# the sweep and sends you here for it, so this is the only copy of the pattern.
+# Every segment after the first is taken too: matched one segment at a time,
+# `/skills/house_style/examples.md` comes back as a mount that resolves *and* a
+# stray `/examples.md`, and that fragment is noise on every run of every project.
+TOKEN='[~.]?/?[A-Za-z0-9_.-]*(/[A-Za-z0-9_.*-]+)+'
+
+# The four mounts, and only those: a token under one of them is a path that
+# resolves.
+MOUNTS='^/(workspace|assets|skills|memory)(/|$)'
+
+# English that happens to contain a slash, and the placeholder paths of a
+# worked example. Add to this rather than teaching a reviewer to skip the same
+# line every run.
+NOISE='^(and/or|he/she|his/her|input/output|read/write|w/o|n/a|N/A|24/7|km/h)$|^(path|foo)/'
+
+# A url, stripped before tokenising rather than filtered after it — the token
+# regex reads `https://acme.dev/docs` as `//acme.dev` *and* `/docs`, and the
+# second half is indistinguishable from a real absolute path once it is alone.
+strip_urls() {
+    sed -E 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' "$1"
+}
+
+# The three trees §2.5 names, prose only: a skill's own script is code the
+# sandbox runs, not text rendered into a prompt, and its paths are its own.
+#
+# `agents/memory-instructions.md` is left out on purpose. It is a copy of the
+# reference, full of worked examples, so it fails this sweep by design and
+# every run of it — and it has a check of its own that a sweep cannot make:
+# .github/skills/zen-memory/scripts/check-instructions.sh
+files() {
+    {
+        if [ -d agents/prompts ]; then find agents/prompts -type f -name '*.md'; fi
+        if [ -d agents/skills ]; then find agents/skills -type f -name '*.md'; fi
+        for file in agents/*instructions.md; do
+            if [ -f "$file" ]; then echo "$file"; fi
+        done
+    } | grep -v '^agents/memory-instructions\.md$' | sort -u
+}
+
+# Every token in those files, urls removed first, and a sentence's full stop
+# trimmed off the end — no path ends in a dot, and `/workspace.` would
+# otherwise read as a mount that does not exist.
+sweep() {
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            strip_urls "$file"
+        fi
+    done <<EOF
+$(files)
+EOF
+}
+
+tokens() {
+    sweep | grep -Eoh "$TOKEN" | sed 's/\.*$//' | sort -u
+}
+
+candidates() {
+    tokens | grep -Ev "$MOUNTS" | grep -Ev "$NOISE" || true
+}
+
+# Where a token came from, so a finding names a file and a line rather than
+# sending someone back to grep for it.
+where() {
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            grep -nF -- "$1" "$file" | sed "s|^|    $file:|" | cut -d: -f1,2
+        fi
+    done <<EOF
+$(files)
+EOF
+}
+
+report() {
+    found=0
+    while IFS= read -r token; do
+        if [ -n "$token" ]; then
+            found=$((found + 1))
+            echo "path: $token"
+            where "$token"
+        fi
+    done <<EOF
+$(candidates)
+EOF
+    if [ "$found" -eq 0 ]; then
+        echo "ok: every path in the three trees is under a mount"
+        return 0
+    fi
+    echo "candidates: $found to explain or fix"
+    return 1
+}
+
+case "${1:-report}" in
+    report) report ;;
+    raw) tokens ;;
+    *)
+        echo "usage: check-paths.sh [report|raw]" >&2
+        exit 2
+        ;;
+esac

package/templates/editor/.github/skills/zen-review/scripts/review.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+#
+# Every check a review can make without judgement, in the order it makes them.
+#
+#   review.sh            zen check, then paths, memory, and the spec-sync record
+#   review.sh fast       the same, with `zen check --no-models --no-sandbox`
+#
+# What it prints is findings. What it cannot see — whether an agent has one job,
+# whether a description is a condition, whether a fact belongs in a skill — is
+# the rest of /review-project, and the reason that prompt still exists.
+#
+# Every step runs even when an earlier one fails: a review that stops at the
+# first problem is one somebody has to run four times. The exit code is 1 if
+# anything wants attention, 0 if nothing does.
+#
+# Run it from anywhere; it finds the project root from its own location.
+
+set -u
+cd "$(dirname "$0")/../../../.."
+
+SKILLS=.github/skills
+CHECK_FLAGS=""
+
+case "${1:-full}" in
+    full) ;;
+    fast) CHECK_FLAGS="--no-models --no-sandbox" ;;
+    *)
+        echo "usage: review.sh [full|fast]" >&2
+        exit 2
+        ;;
+esac
+
+SUMMARY=""
+WORST=0
+
+# Records one step's verdict for the summary, and remembers the worst of them.
+verdict() {
+    SUMMARY="$SUMMARY$1: $2
+"
+    if [ "$3" -ne 0 ]; then
+        WORST=1
+    fi
+}
+
+step() {
+    printf '\n--- %s ---\n' "$1"
+}
+
+step 'zen check'
+if command -v zen >/dev/null 2>&1; then
+    # Unquoted on purpose: empty means no flags rather than one empty argument.
+    # shellcheck disable=SC2086
+    zen check $CHECK_FLAGS
+    rc=$?
+    if [ "$rc" -eq 0 ]; then
+        verdict 'zen check' 'ok' 0
+    else
+        verdict 'zen check' "exit $rc — nothing below matters until this passes" 1
+    fi
+else
+    echo "zen is not on PATH — install it, or run the other three alone"
+    verdict 'zen check' 'not run' 1
+fi
+
+step 'paths'
+"$SKILLS/zen-review/scripts/check-paths.sh"
+rc=$?
+if [ "$rc" -eq 0 ]; then
+    verdict 'paths' 'ok' 0
+else
+    verdict 'paths' 'candidates to explain or fix' 1
+fi
+
+step 'memory'
+"$SKILLS/zen-memory/scripts/check-instructions.sh"
+rc=$?
+if [ "$rc" -eq 0 ]; then
+    verdict 'memory' 'ok' 0
+else
+    verdict 'memory' 'the house rules are missing or stale' 1
+fi
+
+step 'spec-sync'
+if [ -f SPECIFICATION.md ]; then
+    # `status` reports a tampered baseline rather than failing on one, so the
+    # verdict has to read what it said.
+    state="$("$SKILLS/zen-spec-sync/scripts/snapshot.sh" status)"
+    rc=$?
+    printf '%s\n' "$state"
+    if [ "$rc" -ne 0 ]; then
+        verdict 'spec-sync' "exit $rc" 1
+    elif printf '%s' "$state" | grep -q 'mode: tampered'; then
+        verdict 'spec-sync' 'the baseline does not match its own manifest' 1
+    else
+        verdict 'spec-sync' "$(printf '%s' "$state" | sed -n 's/^mode: /mode /p')" 0
+    fi
+else
+    echo "no SPECIFICATION.md — this project keeps no spec-sync record"
+    verdict 'spec-sync' 'not applicable' 0
+fi
+
+step 'summary'
+printf '%s' "$SUMMARY"
+exit "$WORST"