@zenera/cli 1.1.43 → 1.1.45

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

@@ -1,6 +1,7 @@
 ---
 name: zen-inspect
 description: 'Use when an LLM agent must diagnose a recorded Zenera run non-interactively: read `zen inspect graph`, open selected nodes, replay an `llm_call` with `zen inspect ask`, identify loops, failed tools, wrong prompts, missed skills, early hand-offs, failed branches, compaction, latency, or token waste. Requires explicit run, node, and question arguments so commands remain deterministic and never prompt.'
+user-invocable: false
 ---
 
 # Diagnose a run non-interactively

package/templates/editor/.github/skills/zen-inspect-ask/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-inspect-ask
 description: 'Use when formulating a question for `zen inspect ask` about an `llm_call` node of a recorded Zenera run - especially a "why did you NOT do X" question (why no `memory_search` first, why no `fork` for independent research branches, why no skill, why no test run). Covers choosing the node, ruling out missing tools before asking, wording the counterfactual so the answer quotes the instruction that blocked the better behaviour, and verifying that quote against the recorded request.'
+user-invocable: false
 ---
 
 # Asking a run why it did not do the better thing

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

@@ -1,6 +1,7 @@
 ---
 name: zen-instructions
 description: The house rules - `agents/instructions.md` and every `agents/<topic>-instructions.md` prepended to every agent's system prompt. How the set is discovered and ordered, the `requires:` frontmatter and its closed vocabulary (`files`, `files-write`, `fork`, `memory`, `memory-write`, `memory-forget`), which four documents are `zen`'s own and are replaced by `zen check --fix`, how a project writes its own customisable topic prompts beside them (`files-policy-instructions.md`, `memory-policy-instructions.md`, `fork-<topic>-instructions.md`, `tools-<topic>-instructions.md`) without losing the copy, what belongs in a house rule as against an agent prompt or a skill, and every `zen check` finding these files can produce. Load before creating, editing, reviewing or deleting any `agents/*instructions.md`, before adding a capability whose rules arrive as one, and whenever `rules.stale`, `rules.unreached`, `files.uninstructed`, `memory.uninstructed` or `fork.uninstructed` is reported.
+user-invocable: false
 ---
 
 # House rules

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

@@ -1,6 +1,7 @@
 ---
 name: zen-memory
 description: Agent memory in Zenera projects - the `memory:` block and per-agent `access`/`sees`/`writes`/`autoRecall`, the five `memory_*` tools (when to use `memory_grep` instead of `memory_search`), kinds, relations and how recall ranks, inspecting a graph with `zen memory`, designing a memory strategy, `agents/memory-instructions.md` vs `agents/memory-policy-instructions.md`, remembering files under `/memory`, and putting memory in front of a `zen rag` index.
+user-invocable: false
 ---
 
 # Memory

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

@@ -1,6 +1,7 @@
 ---
 name: zen-memory-warmup
 description: Pre-populating an agent project's memory graph before production by running a curated file of seed queries through `zen run batch` — one parallel batch instead of a hand-rolled fan-out, with per-item workspaces and per-item memories the command makes for you, choosing the source graph with --memory, bounding the parallelism with --concurrency, warming with a stronger --model, reading what each query learned from batch.json and per-item output.json, folding it all back with zen memory merge, validating with zen memory stats, atomic promotion into the project, and generating the population script in scripts/memory_warmup.sh.
+user-invocable: false
 ---
 
 # Memory Warmup

package/templates/editor/.github/skills/zen-rag-docs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-rag-docs
 description: What a document index is, how to build one from a folder of `.md` files with `zen rag docs index` (or `npx @zenera/cli`), and how to ask it something - searching by meaning and narrowing to a release, a heading or a table, listing and grepping it exactly instead of reaching for shell `grep`/`rg`, reading a section back verbatim, giving it to an agent as tools, and writing the project skill that a wired-in index requires. For an OpenAPI description instead of prose, see `zen-rag-schema`.
+user-invocable: false
 ---
 
 # The document index

package/templates/editor/.github/skills/zen-rag-schema/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-rag-schema
 description: What a schema index is, how it finds the right call inside a large OpenAPI/Swagger document, and how to build and query one with `zen rag schema` (or `npx @zenera/cli`) - searching it by meaning, listing and grepping it exactly instead of reaching for shell `grep`/`rg`, tracing a field up to the operations that carry it, giving it to an agent as tools, and writing the project skill that a wired-in index requires. For a pile of markdown instead of an API description, see `zen-rag-docs`.
+user-invocable: false
 ---
 
 # The schema index

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

@@ -1,6 +1,7 @@
 ---
 name: zen-review
 description: Checking a project before committing - the three mechanical checks `/project-review` makes before any judgement (`zen check`, the §2.5 path sweep, the spec-sync record), what each one owns, what their exit codes mean, which findings hand off to `zen-instructions`, 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.
+user-invocable: false
 ---
 
 # Reviewing a project
@@ -40,6 +41,39 @@ nothing about the model id it is spent on.
 Nothing below matters while `zen check` fails. Report what it said and fix that
 first.
 
+## Reusing a check within the same pass
+
+Instead of calling `zen check` separately and repeating it in the review, run:
+
+```sh
+.github/skills/zen-review/scripts/review.sh check full --fix
+.github/skills/zen-review/scripts/review.sh --skip-check
+```
+
+`check` runs only the CLI check and saves a receipt in `.tmp/review-check.json`
+on success. `--skip-check` verifies that receipt, then still runs the path sweep
+and spec-sync checks. It fails explicitly for a missing, failed, stale or
+insufficient check; it never silently treats a skipped check as success.
+
+Receipts cover project file contents, permissions, additions and deletions, and the CLI
+version. They exclude only root `.git/`, `.tmp/` and `.spec-sync/`, so writing
+history does not invalidate a result. Symlinks and special files are unsupported:
+run the ordinary review instead. Hashing includes assets and dependencies and
+can itself be costly for large projects; the ordinary review remains available.
+
+This is same-pass reuse, not a persistent health cache. Do not reuse after
+changing credentials, environment variables, external files, ignored scratch
+inputs or remote resources: those are not certified by the receipt. Run a fresh
+check instead. Only use reuse for a self-contained project's stable inputs.
+
+`check no-sandbox` and `--skip-check no-sandbox` are for the spec-sync skill's
+eligible model-reference-only pass. They still probe models. `check fast` and
+`--skip-check fast` omit both expensive probes and are for iteration only.
+A full receipt covers either partial mode, but a partial receipt cannot stand
+in for a full one. If a partial check repairs or otherwise changes files, no
+reusable receipt is issued: run `check full`, because a repair may have changed
+the sandbox pin. Finish setup and all edits before saving the final receipt.
+
 ## The script this skill ships
 
 ### `check-paths.sh` - the §2.5 sweep

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

@@ -38,7 +38,7 @@ NOISE='^(and/or|he/she|his/her|input/output|read/write|w/o|n/a|N/A|24/7|km/h)$|^
 # second half is indistinguishable from a real absolute path once it is alone.
 #
 # A meta agent command, `zen meta run /spec-edit`, goes the same way: its
-# `/<name>` is a stored prompt, not a file the running agent is told to open.
+# `/<name>` is a command (a skill), not a file the running agent is told to open.
 strip_urls() {
     sed -E -e 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' \
         -e 's#(zen meta run( [A-Za-z0-9_.-]+)?) /[A-Za-z0-9_-]+#\1#g' "$1"

package/templates/editor/.github/skills/zen-review/scripts/check-receipt.mjs

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const [action, mode = 'full', fix] = process.argv.slice(2);
+const modes = {
+    full: [],
+    'no-sandbox': ['--no-sandbox'],
+    fast: ['--no-models', '--no-sandbox'],
+};
+const receipt = '.tmp/review-check.json';
+
+function fingerprint() {
+    const hash = createHash('sha256');
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+            a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+        )) {
+            if (dir === '.' && ['.git', '.tmp', '.spec-sync'].includes(entry.name)) continue;
+            const path = `${dir}/${entry.name}`;
+            hash.update(JSON.stringify([path, entry.isDirectory(), lstatSync(path).mode]));
+            if (entry.isDirectory()) walk(path);
+            else if (entry.isFile())
+                hash.update(createHash('sha256').update(readFileSync(path)).digest('hex'));
+            else throw new Error(`cannot reuse validation with a symlink or special file: ${path}`);
+        }
+    }
+    walk('.');
+    return hash.digest('hex');
+}
+
+function version() {
+    const result = spawnSync('zen', ['--version'], { encoding: 'utf8' });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error('zen --version failed');
+    return result.stdout.trim();
+}
+
+try {
+    if (
+        !Object.hasOwn(modes, mode) ||
+        !['run', 'verify'].includes(action) ||
+        (fix !== undefined && (action !== 'run' || fix !== '--fix')) ||
+        process.argv.length > 5
+    ) {
+        throw new Error('usage: check-receipt.mjs run|verify full|no-sandbox|fast [--fix]');
+    }
+    if (action === 'run') {
+        mkdirSync('.tmp', { recursive: true });
+        // Invalidate the previous result before trying a new check.
+        writeFileSync(receipt, 'null\n');
+        const before = fingerprint();
+        const result = spawnSync('zen', ['check', ...modes[mode], ...(fix ? [fix] : [])], {
+            stdio: 'inherit',
+        });
+        if (result.error) throw result.error;
+        if (result.status !== 0) process.exit(result.status ?? 1);
+        const after = fingerprint();
+        if (mode !== 'full' && before !== after) {
+            throw new Error(
+                'files changed during a partial check (possibly a sandbox pin repair); run check full before reusing validation',
+            );
+        }
+        writeFileSync(
+            receipt,
+            JSON.stringify({
+                root: resolve('.'),
+                mode,
+                version: version(),
+                fingerprint: after,
+            }) + '\n',
+        );
+        console.log(`check receipt: ${receipt}`);
+    } else {
+        const saved = JSON.parse(readFileSync(receipt, 'utf8'));
+        const covers =
+            saved &&
+            (saved.mode === 'full' ||
+                saved.mode === mode ||
+                (saved.mode === 'no-sandbox' && mode === 'fast'));
+        if (
+            !covers ||
+            saved.root !== resolve('.') ||
+            saved.version !== version() ||
+            saved.fingerprint !== fingerprint()
+        ) {
+            throw new Error('check receipt is stale or lacks required probes; run a fresh check');
+        }
+        console.log(`zen check: reusing successful ${saved.mode} check`);
+    }
+} catch (error) {
+    console.error(`check receipt: ${error.message}`);
+    process.exitCode = 1;
+}

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

@@ -4,6 +4,8 @@
 #
 #   review.sh            zen check, then paths and the spec-sync record
 #   review.sh fast       the same, with `zen check --no-models --no-sandbox`
+#   review.sh check [full|no-sandbox|fast] [--fix]   check and save a receipt
+#   review.sh --skip-check [full|no-sandbox|fast]   verify and reuse that receipt
 #
 # 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
@@ -20,15 +22,34 @@ cd "$(dirname "$0")/../../../.."
 
 SKILLS=.github/skills
 CHECK_FLAGS=""
+REUSE=0
+RECEIPT="$SKILLS/zen-review/scripts/check-receipt.mjs"
+
+if [ "${1:-}" = check ]; then
+    shift
+    if [ "${1:-}" = --fix ]; then
+        set -- full "$@"
+    fi
+    exec node "$RECEIPT" run "$@"
+fi
+if [ "${1:-}" = --skip-check ]; then
+    REUSE=1
+    shift
+fi
 
 case "${1:-full}" in
     full) ;;
+    no-sandbox) CHECK_FLAGS="--no-sandbox" ;;
     fast) CHECK_FLAGS="--no-models --no-sandbox" ;;
     *)
-        echo "usage: review.sh [full|fast]" >&2
+        echo "usage: review.sh [check|--skip-check] [full|no-sandbox|fast] [--fix (check only)]" >&2
         exit 2
         ;;
 esac
+if [ "$#" -gt 1 ]; then
+    echo "review.sh: unexpected arguments" >&2
+    exit 2
+fi
 
 SUMMARY=""
 WORST=0
@@ -47,7 +68,11 @@ step() {
 }
 
 step 'zen check'
-if command -v zen >/dev/null 2>&1; then
+if [ "$REUSE" -eq 1 ]; then
+    node "$RECEIPT" verify "${1:-full}"
+    rc=$?
+    verdict 'zen check' "receipt exit $rc" "$rc"
+elif 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

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

@@ -1,6 +1,7 @@
 ---
 name: zen-sandbox
-description: How the container sandbox works, when and how to configure it in `agents.yaml` (`sandbox:` and `agents[].sandbox`), the four `sandbox:*` tools, mount layout (/workspace, $HOME, /tmp, /run/zenera/keys), lifecycle and persistence (`persist: true`), credential forwarding by name, resource ceilings (cpus, memory, pids), standard vs strict hardening profiles, path rules, and debugging container issues with `zen sandbox`. Refers to `zen-cli` (`.github/skills/zen-cli/references/sandbox.md`).
+description: 'How the container sandbox works, when and how to configure it in `agents.yaml` (`sandbox:` and `agents[].sandbox`), the four `sandbox:*` tools, mount layout (/workspace, $HOME, /tmp, /run/zenera/keys), lifecycle and persistence (`persist: true`), credential forwarding by name, resource ceilings (cpus, memory, pids), standard vs strict hardening profiles, path rules, and debugging container issues with `zen sandbox`. Refers to `zen-cli` (`.github/skills/zen-cli/references/sandbox.md`).'
+user-invocable: false
 ---
 
 # The Container Sandbox

package/templates/editor/.github/skills/zen-sandbox-capacity/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-sandbox-capacity
-description: Whether the machine can actually run the batch you are about to start. The podman VM is the ceiling and it is sized once, at 2 GiB by default, whatever the host has - so N concurrent containers over a multi-gigabyte index thrash and are OOM-killed while the host sits idle. Covers the three layers (host, VM, container) and which one can add memory, the exit-code table (137 is always capacity, 124 is usually 137 in disguise, and raising `timeout:` converts one into the other and hides the fault), the memory budget and how to measure its terms instead of assuming them, separating `local` probes from `embed` ones so a starved index is never mistaken for a throttled provider, recording the machine spec so two rounds' token counts are comparable at all, and `scripts/preflight_sandbox.sh` as the gate that answers it in under a minute. Load before any `zen run batch`, before raising `--concurrency` above 1, on exit 137, on a `killed` message from the shell, on an exit 124 from a `zen rag` call, when a batch is slow or timed out, and before comparing tokens or wall-clock between two rounds. Not for a single interactive `zen run` - one container is not a capacity problem.
+description: 'Whether the machine can run the batch you are about to start: the podman VM (2 GiB by default) is the ceiling, so concurrent containers over a large index are OOM-killed while the host sits idle. Covers the host/VM/container layers, the exit codes (137 is capacity, 124 is usually 137 in disguise), measuring the memory budget, separating `local` from `embed` probes, recording the machine spec so rounds compare, and `scripts/preflight_sandbox.sh` as the gate. Load before any `zen run batch`, before `--concurrency` above 1, on exit 137 or 124 from `zen rag`, on a `killed` message, when a batch is slow or timed out, and before comparing tokens or wall-clock between rounds. Not for a single interactive `zen run`.'
+user-invocable: false
 ---
 
 # Capacity

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

@@ -1,6 +1,7 @@
 ---
 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, which input wins when they disagree, the five checks a narrow pass may never skip, which skills a pass must load before editing (`zen-instructions` for any house rule it touches), 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.
+description: Running `/spec-sync-project` incrementally - the committed `.spec-sync` baseline, scope and precedence, spec-only and model-reference-only verification tiers, affected capability skills, generated-rule maintenance, reusable validation, explicit history recording and why the baseline moves last. Load before every `/spec-sync-project`, including a project's first pass.
+user-invocable: false
 ---
 
 # Syncing a project with its specification, one change at a time
@@ -13,7 +14,8 @@ 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_.
+obligation: the record scopes what you _read and edit_. The tiers below also
+scope verification, with explicit escalation when the work reaches further.
 
 ## What this owns
 
@@ -59,6 +61,14 @@ 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/`:
 
+The four generated `agents/{files,fork,memory,tools}-instructions.md` copies
+print as `maintenance:` rather than `changed:`. Their diffs remain visible and
+their bytes remain in the baseline. They are not project implementation edits:
+`zen check` checks them against this version's templates, and `--fix` replaces
+them. Account for repairs in history, but do not widen the pass merely because
+one of these copies moved. A project requirement found in one must be moved to
+a project-owned topic file; that is substantive work and widens the pass.
+
 | Mode          | Means                                      | Do                                                                                    |
 | ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
 | `full`        | no manifest - no pass has ever completed   | the whole prompt as written, then write the first baseline                            |
@@ -94,7 +104,7 @@ editing anything, and report it in the chat as the pass's scope.
    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/` -
+4. **The implementation diff.** `agents.yaml` and project-owned files 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
@@ -158,12 +168,68 @@ answers:
 That is the whole of the work. A version mismatch is not a reason to look for
 anything else.
 
-## The five checks a narrow pass may never skip
+## Choose a verification tier before loading capability skills
+
+Use `full` for a missing or untrusted baseline. On an incremental pass, first
+read the diffs and the applied entry's `Still open`, then choose `spec-only`,
+`model-reference-only`, or the normal incremental checks below. Unresolved
+items or feedback requiring other work disqualify a narrow tier. Say the tier,
+its scope and the omitted work in the chat. Escalate as soon as the actual work
+exceeds that scope; a small original diff is not permission to skip new work.
+
+### The model-reference-only pass
+
+All of these must hold:
 
-However small the diff - with the one narrowing for a spec-only pass below:
+- The only substantive requirement change replaces an existing **chat model
+  reference**, with an explicit replacement in the specification or user input.
+- The only project implementation change is that corresponding scalar in
+  `agents.yaml`, either pending or already edited. No agent assignment, provider
+  configuration, tool, prompt, skill, capability or setup step changes.
+- There is no other outstanding work from feedback or `Still open`.
 
-1. **`zen check` passes.** Run it before the first edit and again after the
-   last.
+Embedding references are not eligible: indexes may need rebuilding. Version
+pins are not model references; a pin repair requires sandbox validation.
+
+Read only the affected requirement hunks, wiring and their direct references.
+Load no capability skill for a model swap alone. After editing, run:
+
+```sh
+.github/skills/zen-review/scripts/review.sh check no-sandbox
+scripts/_setup.sh --check
+.github/skills/zen-review/scripts/review.sh --skip-check no-sandbox
+```
+
+The check still validates the whole configuration and probes its models; do not
+also run `zen models test`. Every tier must resolve `rules.stale` and sandbox
+pin findings before completion, even when the CLI reports them as warnings.
+`--no-sandbox` is allowed only after confirming the
+sandbox configuration, Dockerfile and build context are unchanged. Compare
+them with git, inspect pending edits and account for any setup-generated build
+inputs: the spec-sync baseline does not track those paths. If that cannot be
+established, use `check full`. Use maintenance diffs and, when needed, a cheap
+`zen check --no-models --no-sandbox` diagnostic to identify repairs before
+probing models. If rules or pins need repair, load
+`zen-instructions` only if a project-owned house rule needs editing, then run
+`review.sh check full --fix`. It repairs before validating, including the
+sandbox. No separate pre-repair model probe is required.
+
+Work only the §9 **Models** and **Specification** groups, plus any group reached
+by additional work (which may require escalation). If setup is empty, one
+successful `--check` is all the setup proof. If existing steps all report
+`skipped`, that also suffices for this tier; otherwise run setup, prove
+re-entrancy and repeat the final check. Finish all builds before recording.
+
+### The normal incremental checks
+
+Outside the two narrow tiers:
+
+1. **`zen check` passes after the last edit and setup.** Use
+   `review.sh check full --fix` to repair generated copies and pins before
+   validating. When an initial diagnostic is needed, use
+   `zen check --no-models --no-sandbox`; do not repeat expensive probes before
+   and after editing. Reuse the final receipt with `review.sh --skip-check`
+   rather than invoking a third check during review.
 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. Then `scripts/_setup.sh --check` must
@@ -171,15 +237,16 @@ However small the diff - with the one narrowing for a spec-only pass below:
    doing the work, which is what tells a real `skipped` from a step that only
    looked done. A step that tests for a committed `manifest.json` skips on a
    fresh clone whose git-ignored `lance/` vectors are missing, and the project
-   cannot search.
+   cannot search. When `STEPS` is empty, one successful `--check` is sufficient;
+   there is no execution or re-entrancy work to prove.
 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 `zen check` reports no `rules.stale`: a newer `zen` ships
-   newer house rules, so they drift without anybody editing the project.
-5. **`zen-instructions` is loaded before any house rule is touched.** A pass
+4. **The capability obligations in §0.1.** Load a capability skill only when
+   changed requirements, files, keys or unresolved work reach that capability.
+   For a full pass, every enabled capability is in scope. `zen check` must
+   still report no `rules.stale`, whether or not its capability was in scope.
+5. **`zen-instructions` is loaded before editing a project-owned house rule.** A pass
    whose scope reaches `agents/*instructions.md` - and input 4 puts it there
-   whenever one of them moved - has to know that `tools-instructions.md`,
+   whenever a project-owned one moved - has to know that `tools-instructions.md`,
    `files-instructions.md`, `memory-instructions.md` and `fork-instructions.md`
    are `zen`'s and are replaced by `zen check --fix`. A pass that writes a
    requirement into one of them has implemented nothing: the next `open` reverts
@@ -188,7 +255,8 @@ However small the diff - with the one narrowing for a spec-only pass below:
 
 ### The spec-only pass
 
-A pass qualifies when **all** of the following hold:
+A pass qualifies when **all** of the following hold, and no outstanding
+feedback or `Still open` item requires implementation work:
 
 - the implementation diff (input 4) is empty
 - the pass edits nothing except `SPECIFICATION.md`, `SPECIFICATION-FEEDBACK.md`
@@ -196,10 +264,14 @@ A pass qualifies when **all** of the following hold:
 - no changed specification hunk names an agent, tool, model, embedding, skill,
   house rule, handoff, memory, index, asset or setup step
 
+Generated copies and the editor tree repaired by `--fix` are maintenance, not
+project implementation edits for this test.
+
 A pass like that changes nothing an agent reads, so it has no capability
 obligation to re-check. Checks 4 and 5 drop out: load no capability skill and no
-`zen-instructions`. `zen check` still runs before and after, and it still
-reports `rules.stale`. Check 2 shrinks to `scripts/_setup.sh --check`, which
+`zen-instructions`. One final `review.sh check full --fix` repairs generated
+copies and pins, validates the result and saves a reusable receipt. Check 2
+shrinks to `scripts/_setup.sh --check`, which
 must report every step `skipped`. If it reports anything else, run
 `scripts/_setup.sh` in full as written. Check 3 shrinks to the §9
 **Specification** group and the groups covering any file the pass edited.
@@ -208,15 +280,18 @@ Decide this before loading anything, and say it in the chat - "spec-only pass:"
 followed by the reason. If any edit turns out to reach further, the pass is no
 longer spec-only: run all five checks.
 
-A narrow diff narrows reading and editing. It does not narrow verification.
+Verification is narrowed only by these explicit tier rules.
 
 ## 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
+serves - runs over every project-owned 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.
+Do not audit generated house-rule copies or the generated editor tree line by
+line; byte comparison and repair belong to `zen check`. Inspect maintenance
+diffs only to identify any project policy that must be preserved in an owned file.
 
 ## The history entry
 
@@ -226,6 +301,26 @@ there; a pass that did nothing still writes one saying so.
 
 These headings, in this order, because the next pass reads them:
 
+Prefer `snapshot.sh record` over writing boilerplate by hand. Every section
+must be supplied explicitly; repeat section flags for multiple items, and use
+`None` for an empty section. Review the applied entry's unresolved items and
+carry forward each one not closed; the script never silently copies or closes
+them.
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh record \
+  --mode incremental \
+  --scope "model-reference-only: replace the main chat model" \
+  --changed "agents.yaml: model reference now matches the specification" \
+  --feedback "None" \
+  --still-open "None" \
+  --checks "configuration and models pass; setup check passes; Models and Specification reviewed"
+```
+
+This fills in the UTC stamp and specification hash, refuses to overwrite an
+entry and leaves the baseline unchanged. It does not run checks or certify the
+claims supplied to it. Run `commit` separately, only after verification.
+
 ```markdown
 # Sync pass 2026-09-13T104500Z
 
@@ -264,7 +359,7 @@ The one rule that must not be got wrong.
 .github/skills/zen-spec-sync/scripts/snapshot.sh commit
 ```
 
-runs **after** `zen check` passes, **after** `scripts/_setup.sh` has completed,
+runs **after** `zen check` passes, **after** setup satisfies the selected tier,
 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

package/templates/editor/.github/skills/zen-spec-sync/scripts/snapshot.sh

@@ -4,6 +4,7 @@
 #
 #   snapshot.sh status    full | incremental | tampered, and what differs
 #   snapshot.sh diff      the difference the next pass has to work
+#   snapshot.sh record    write a history entry, without moving the baseline
 #   snapshot.sh commit    move the baseline on, once the pass has finished
 #
 # Run it from anywhere; it finds the project root from its own location, which
@@ -73,6 +74,13 @@ differs() {
     ! cmp -s "$(side "$BASE/$1")" "$(side "$1")"
 }
 
+owned() {
+    case "$1" in
+        agents/files-instructions.md|agents/fork-instructions.md|agents/memory-instructions.md|agents/tools-instructions.md) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
 # Which baseline files no longer hash to what the manifest says they do.
 # `FAILED` covers a changed file; `FAILED open or read` covers a missing one.
 broken() {
@@ -109,7 +117,11 @@ EOF
     fi
     while IFS= read -r file; do
         if [ -n "$file" ] && differs "$file"; then
-            echo "changed: $file"
+            if owned "$file"; then
+                echo "maintenance: $file"
+            else
+                echo "changed: $file"
+            fi
         fi
     done <<EOF
 $(scope)
@@ -127,6 +139,74 @@ $(scope)
 EOF
 }
 
+record() {
+    mode=""
+    scope_text=""
+    changed_text=""
+    feedback_text=""
+    open_text=""
+    checks_text=""
+    while [ "$#" -gt 0 ]; do
+        if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+            echo "snapshot.sh record: every option needs a non-empty value" >&2
+            return 2
+        fi
+        case "$1" in
+            --mode)
+                case "$2" in
+                    full|incremental) mode="$2" ;;
+                    *) echo "snapshot.sh record: mode must be full or incremental" >&2; return 2 ;;
+                esac
+                ;;
+            --scope) scope_text="$scope_text- $2
+" ;;
+            --changed) changed_text="$changed_text- $2
+" ;;
+            --feedback) feedback_text="$feedback_text- $2
+" ;;
+            --still-open) open_text="$open_text- $2
+" ;;
+            --checks) checks_text="$checks_text- $2
+" ;;
+            *) echo "snapshot.sh record: unknown option $1" >&2; return 2 ;;
+        esac
+        shift 2
+    done
+    if [ -z "$mode" ] || [ -z "$scope_text" ] || [ -z "$changed_text" ] ||
+        [ -z "$feedback_text" ] || [ -z "$open_text" ] || [ -z "$checks_text" ]; then
+        echo "usage: snapshot.sh record --mode full|incremental --scope <text> --changed <text> --feedback <text> --still-open <text> --checks <text> (repeat sections as needed; use 'None' explicitly)" >&2
+        return 2
+    fi
+    if [ ! -f SPECIFICATION.md ]; then
+        echo "snapshot.sh record: SPECIFICATION.md is missing" >&2
+        return 1
+    fi
+    spec_sum="$(shasum -a 256 SPECIFICATION.md)"
+    spec_sha="${spec_sum%% *}"
+    stamp="$(date -u +%Y-%m-%dT%H%M%SZ)"
+    entry="$HISTORY/$stamp.md"
+    draft="$(mktemp "$HISTORY/.record.XXXXXX")"
+    trap 'rm -f "$draft"' EXIT
+    {
+        printf '# Sync pass %s\n\n' "$stamp"
+        printf -- '- **Mode** - %s\n- **Spec sha** - %s\n' "$mode" "$spec_sha"
+        printf '\n## Scope\n\n%s' "$scope_text"
+        printf '\n## Changed\n\n%s' "$changed_text"
+        printf '\n## Feedback\n\n%s' "$feedback_text"
+        printf '\n## Still open\n\n%s' "$open_text"
+        printf '\n## Checks\n\n%s' "$checks_text"
+    } >"$draft"
+    # Linking refuses to replace an existing entry, even within the same second.
+    if ! ln "$draft" "$entry"; then
+        echo "snapshot.sh record: could not create $entry; no entry was overwritten" >&2
+        return 1
+    fi
+    rm -f "$draft"
+    trap - EXIT
+    echo "history: $entry"
+    echo "baseline: unchanged (run snapshot.sh commit only after verification)"
+}
+
 commit() {
     entry="$(newest)"
     if [ -z "$entry" ]; then
@@ -192,9 +272,10 @@ EOF
 case "${1:-status}" in
     status) status ;;
     diff) show_diff ;;
+    record) shift; record "$@" ;;
     commit) commit ;;
     *)
-        echo "usage: snapshot.sh [status|diff|commit]" >&2
+        echo "usage: snapshot.sh [status|diff|record|commit]" >&2
         exit 2
         ;;
 esac