@zenera/cli 1.1.16 → 1.1.18

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 `/project-review` 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 `/project-review`, 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 `/project-review`, 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 /project-review, 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"

package/templates/editor/.github/skills/zen-spec-sync/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: zen-spec-sync
+description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, the four checks a narrow pass may never skip, the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
+---
+
+# Syncing a project with its specification, one change at a time
+
+`SPECIFICATION.md` is the intent and the files are the implementation, so
+bringing the two together is a pass over the whole project. Done from nothing
+every time, that pass re-reads every prompt, re-derives every decision the last
+one already made, and re-raises questions someone has already answered.
+
+A pass is worth repeating cheaply, so it keeps a record of **what it applied**.
+The next pass diffs the specification against that record and works the
+difference. What it must not do is confuse a narrow diff with a narrow
+obligation: the record scopes what you _read and edit_, never what you _verify_.
+
+## What this owns
+
+Everything is committed. `.spec-sync/` is a record, not scratch - `.tmp/` is
+scratch.
+
+```
+.spec-sync/
+├── baseline/
+│   ├── SPECIFICATION.md              the spec the last completed pass applied
+│   ├── SPECIFICATION-FEEDBACK.md     the questions it had open, if any
+│   ├── agents.yaml                   the wiring it left behind
+│   ├── agents/                       and every instruction, prompt and skill
+│   ├── applied.txt                   the history entry this baseline belongs to
+│   └── manifest.txt                  sha256 of every file above
+└── history/
+    └── 2026-09-13T104500Z.md         one file per pass, never edited after
+```
+
+The baseline mirrors the paths it records, so `baseline/agents/skills/x/SKILL.md`
+is that skill as the last completed pass left it. Both sides are there on
+purpose: the specification and the feedback say what was **asked for**, the
+wiring and the `agents/` tree say what was **built**, and a pass has to know
+which of the two moved.
+
+The baseline is **not a copy of the current specification**. It is the
+specification as the last completed pass left it, which is what makes the
+difference between the two mean "work nobody has done yet".
+
+`zen init` creates `baseline/` and `history/` empty, and git does not carry an
+empty directory, so **the presence of `.spec-sync/` proves nothing**. The
+manifest is the signal: no `manifest.txt` means no pass has ever completed.
+
+## Deciding the size of the pass
+
+Run this first, from the project root:
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh status
+```
+
+It prints one `mode:` line, the `applied:` stamp the baseline belongs to, and a
+`changed:` line per file that differs - specification, feedback, `agents.yaml`
+or anything under `agents/`:
+
+| Mode          | Means                                      | Do                                                                                    |
+| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `full`        | no manifest - no pass has ever completed   | the whole prompt as written, then write the first baseline                            |
+| `incremental` | a baseline is there and the files differ   | scope from the four inputs below                                                      |
+| `tampered`    | a baseline file does not match its own sha | treat as `full`, and say in the chat which file and that the baseline was not trusted |
+
+`tampered` is either a baseline edited by hand or a pass that died between
+copying the files and writing the manifest. Both mean the record is not
+evidence. Do not rewrite `manifest.txt` to make the message go away - that
+asserts a pass happened that did not.
+
+`snapshot.sh diff` then prints the unified diffs, and is where the pass
+actually starts.
+
+## The four scope inputs
+
+An incremental pass is scoped by the union of these. Write the union down before
+editing anything, and report it in the chat as the pass's scope.
+
+1. **The `SPECIFICATION.md` diff.** The primary input: added, changed and
+   deleted requirements. A deleted requirement is work too - what implemented it
+   is now an **extra**, to be reported under `➕` rather than quietly deleted.
+2. **The `SPECIFICATION-FEEDBACK.md` diff.** The file is a questionnaire the
+   human answers by ticking one answer's `[ ]` box or deleting the answers they
+   do not want. A question that has moved under `✅ Answered` was folded into the
+   specification by `/spec-apply-feedback`, and its **Still to implement**
+   line is the work. A question with a box marked `[x]`, or one answer left
+   under it, and no `✅` entry was answered and never folded in - implement it,
+   put its text into `SPECIFICATION.md`, and say so. A new question someone else
+   raised is work too. Close what this pass resolves rather than re-raising it.
+3. **What the last pass left open.** The `Still open` section of the entry named
+   by `applied:`, in `.spec-sync/history/`. A specification line that has not
+   changed since the baseline is **not therefore implemented**: the baseline
+   records what the pass applied, and a pass can complete with items open. This
+   is the only place that says which.
+4. **The implementation diff.** `agents.yaml` and every file under `agents/` -
+   instructions, prompts and skills. This side is what was built rather than
+   what was asked for, so it never narrows a pass: it says what moved under you
+   since the last one. An agent, tool grant, handoff, model, house rule, prompt
+   or skill edited outside a pass **widens** the pass to everything that names
+   what changed, and the edit is itself an item - either the specification
+   covers it, and you say which line, or it does not, and it is an **extra**
+   reported under `➕`.
+
+## The four checks a narrow pass may never skip
+
+However small the diff:
+
+1. **`zen check` passes.** Run it before the first edit and again after the
+   last.
+2. **`scripts/_setup.sh` has run to completion in this session, and re-runs
+   clean.** A one-line specification change can still break a setup step, and a
+   pass that did not run it does not know.
+3. **§9 of the copilot instructions, worked as a checklist**, group by group.
+4. **The capability obligations in §0.1.** For every capability the project has
+   turned on, load that capability's skill and re-check what it requires - in
+   particular that `agents/memory-instructions.md` is still byte-identical to
+   `.github/skills/zen-memory/references/memory-instructions.md`. `zen init` and
+   `zen open` rewrite the reference, so this drifts without anybody editing the
+   project.
+
+A narrow diff narrows reading and editing. It does not narrow verification.
+
+## What else an incremental pass still owes
+
+The reverse pass of §2 - reading each line and naming the specification item it
+serves - runs over every file this pass touched, plus every file the
+implementation diff named. It is the only pass that finds a line contradicting
+another file, and an edit made this session, or made by hand since the last
+pass, is exactly where a new contradiction comes from.
+
+## The history entry
+
+One file per pass, `.spec-sync/history/<stamp>.md`, where the stamp is UTC and
+filename-safe: `date -u +%Y-%m-%dT%H%M%SZ`. Never edit a file that is already
+there; a pass that did nothing still writes one saying so.
+
+These headings, in this order, because the next pass reads them:
+
+```markdown
+# Sync pass 2026-09-13T104500Z
+
+- **Mode** - incremental
+- **Spec sha** - 3f9a… (`shasum -a 256 SPECIFICATION.md`)
+
+## Scope
+
+What drove the pass: the diff hunks, the feedback entries, what the last pass
+left open. `full` if it was a full pass.
+
+## Changed
+
+One row per file changed, and the specification item it closes.
+
+## Feedback
+
+Entries opened and entries closed, by number.
+
+## Still open
+
+Every specification item this pass did **not** close, with its
+`SPECIFICATION-FEEDBACK.md` anchor. Empty means empty - this is what the next
+pass trusts.
+
+## Checks
+
+`zen check`, each `scripts/_setup.sh` step, and the §9 groups: pass or fail.
+```
+
+## Write the baseline last
+
+The one rule that must not be got wrong.
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh commit
+```
+
+runs **after** `zen check` passes, **after** `scripts/_setup.sh` has completed,
+and **after** the history file is on disk. It takes the newest entry in
+`.spec-sync/history/` - the stamps sort chronologically by name - records it in
+`applied.txt`, and writes `manifest.txt` last of all. It refuses to run when
+there is no history file, and when the newest one is the entry `applied.txt`
+already names: that means this pass wrote no entry of its own.
+
+A pass that moves the baseline early and then fails records a specification as
+applied that was never applied - and the next pass diffs against it, sees
+nothing, and skips the work for good. Failing with the baseline unmoved costs
+one repeated pass; failing with it moved costs a requirement that is never
+implemented and that nothing will report. Say in the chat which history file was
+written and that the baseline moved.
+
+## The first pass on a project that has no baseline
+
+`mode: full`, so run the prompt as written, end to end. Then write the history
+file and commit the baseline exactly as any other pass does - a project only
+becomes incremental by having completed one full pass.