@zenera/cli 1.1.16 → 1.1.17

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

@@ -0,0 +1,197 @@
+---
+name: zen-spec-sync
+description: Running `/sync-with-spec` 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 `/sync-with-spec`, 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 `/update-spec-from-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.

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

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+#
+# The committed record of what the last completed /sync-with-spec pass applied.
+#
+#   snapshot.sh status    full | incremental | tampered, and what differs
+#   snapshot.sh diff      the difference the next pass has to work
+#   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
+# `zen init` and `zen open` fix. The baseline is written last and only last —
+# see .github/skills/zen-spec-sync/SKILL.md for why that is the whole point.
+
+set -eu
+cd "$(dirname "$0")/../../../.."
+
+STATE=.spec-sync
+BASE="$STATE/baseline"
+HISTORY="$STATE/history"
+MANIFEST="$BASE/manifest.txt"
+SCRATCH=.tmp/spec-sync
+
+# The intent: what the project is meant to be, and what was asked back about it.
+INTENT="SPECIFICATION.md SPECIFICATION-FEEDBACK.md"
+
+# The implementation: the wiring, and every instruction, prompt and skill file
+# under agents/. One of those edited since the last pass is a change the pass
+# has to account for, the same as a changed requirement is.
+WIRING=agents.yaml
+TREE=agents
+
+# The history entry this baseline belongs to, hashed like the rest of it.
+APPLIED=applied.txt
+
+if [ ! -f "$WIRING" ] && [ ! -f SPECIFICATION.md ]; then
+    echo "snapshot.sh: no agents.yaml or SPECIFICATION.md in $PWD" >&2
+    exit 2
+fi
+
+# Git cannot carry an empty directory, so these are made rather than expected.
+mkdir -p "$BASE" "$HISTORY"
+
+# Every path the record covers, on the working-tree side.
+present() {
+    {
+        for file in $INTENT $WIRING; do
+            if [ -f "$file" ]; then echo "$file"; fi
+        done
+        if [ -d "$TREE" ]; then find "$TREE" -type f ! -name .DS_Store; fi
+    } | sort -u
+}
+
+# The same, from both sides, so a file added or deleted since the last pass is
+# a difference rather than a path nobody walks.
+scope() {
+    {
+        present
+        for file in $INTENT $WIRING; do
+            if [ -f "$BASE/$file" ]; then echo "$file"; fi
+        done
+        if [ -d "$BASE/$TREE" ]; then
+            (cd "$BASE" && find "$TREE" -type f ! -name .DS_Store)
+        fi
+    } | sort -u
+}
+
+# A file that is not there counts as an empty one, so adding or deleting it
+# reads as a difference rather than as an error.
+side() {
+    if [ -f "$1" ]; then echo "$1"; else echo /dev/null; fi
+}
+
+differs() {
+    ! cmp -s "$(side "$BASE/$1")" "$(side "$1")"
+}
+
+# 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() {
+    (cd "$BASE" && shasum -a 256 -c manifest.txt 2>/dev/null || true) |
+        sed -n 's/: FAILED.*$//p'
+}
+
+# The stamps sort chronologically by name, which is the point of the format —
+# an mtime would make a fast pass look like no pass at all.
+newest() {
+    ls "$HISTORY"/*.md 2>/dev/null | sort | tail -1 || true
+}
+
+status() {
+    if [ ! -f "$MANIFEST" ]; then
+        echo "mode: full"
+        echo "reason: no baseline, so no pass has ever completed here"
+        return 0
+    fi
+    failed="$(broken)"
+    if [ -n "$failed" ]; then
+        echo "mode: tampered"
+        while IFS= read -r file; do
+            if [ -n "$file" ]; then echo "unsound: $BASE/$file"; fi
+        done <<EOF
+$failed
+EOF
+        echo "reason: the baseline does not match its own manifest"
+        return 0
+    fi
+    echo "mode: incremental"
+    if [ -f "$BASE/$APPLIED" ]; then
+        echo "applied: $(cat "$BASE/$APPLIED")"
+    fi
+    while IFS= read -r file; do
+        if [ -n "$file" ] && differs "$file"; then
+            echo "changed: $file"
+        fi
+    done <<EOF
+$(scope)
+EOF
+}
+
+show_diff() {
+    while IFS= read -r file; do
+        if [ -n "$file" ] && differs "$file"; then
+            diff -u -L "baseline/$file" -L "$file" \
+                "$(side "$BASE/$file")" "$(side "$file")" || true
+        fi
+    done <<EOF
+$(scope)
+EOF
+}
+
+commit() {
+    entry="$(newest)"
+    if [ -z "$entry" ]; then
+        echo "snapshot.sh: write $HISTORY/<stamp>.md before moving the baseline" >&2
+        exit 1
+    fi
+    stamp="$(basename "$entry" .md)"
+    if [ -f "$BASE/$APPLIED" ] && [ "$stamp" = "$(cat "$BASE/$APPLIED")" ]; then
+        echo "snapshot.sh: the baseline already names $stamp — this pass wrote no entry" >&2
+        exit 1
+    fi
+
+    staged="$(present)"
+    rm -rf "$SCRATCH"
+    mkdir -p "$SCRATCH"
+    echo "$stamp" >"$SCRATCH/$APPLIED"
+    : >"$SCRATCH/manifest.txt"
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            mkdir -p "$SCRATCH/$(dirname "$file")"
+            cp "$file" "$SCRATCH/$file"
+        fi
+    done <<EOF
+$staged
+EOF
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            (cd "$SCRATCH" && shasum -a 256 "$file") >>"$SCRATCH/manifest.txt"
+        fi
+    done <<EOF
+$APPLIED
+$staged
+EOF
+
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            mkdir -p "$BASE/$(dirname "$file")"
+            mv "$SCRATCH/$file" "$BASE/$file"
+        fi
+    done <<EOF
+$APPLIED
+$staged
+EOF
+    # Everything in scope that still exists has just been staged, so a baseline
+    # file with no working copy is one this pass deleted.
+    while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" != "$APPLIED" ] && [ ! -f "$file" ]; then
+            rm -f "$BASE/$file"
+        fi
+    done <<EOF
+$(cd "$BASE" && find . -type f ! -name manifest.txt | sed 's|^\./||')
+EOF
+    find "$BASE" -mindepth 1 -type d -empty -delete
+    # Last, so an interrupted commit leaves a baseline that reports itself as
+    # tampered rather than one that claims a pass it never finished.
+    mv "$SCRATCH/manifest.txt" "$MANIFEST"
+    rm -rf "$SCRATCH"
+
+    echo "applied: $stamp"
+    echo "recorded: $(printf '%s\n' "$staged" | sed '/^$/d' | wc -l | tr -d ' ') files"
+}
+
+case "${1:-status}" in
+    status) status ;;
+    diff) show_diff ;;
+    commit) commit ;;
+    *)
+        echo "usage: snapshot.sh [status|diff|commit]" >&2
+        exit 2
+        ;;
+esac

package/templates/editor/.vscode/settings.json

@@ -1,11 +1,51 @@
 {
     "chat.useNestedAgentsMdFiles": false,
     "chat.tools.terminal.enableAutoApprove": true,
-    "chat.tools.terminal.ignoreDefaultAutoApproveRules": true,
     "chat.tools.edits.autoApprove": true,
     "chat.tools.terminal.autoApprove": {
-        "^(?:(?:export\\s+[A-Za-z_][A-Za-z0-9_]*(?:=[^;\\s]+)?\\s*;\\s*)|(?:[A-Za-z_][A-Za-z0-9_]*=[^;\\s]+\\s+))*(?:cat|echo|head|ls|pwd|rg|tail|which)(?:\\s|$)": true,
-        "^(?:(?:export\\s+[A-Za-z_][A-Za-z0-9_]*(?:=[^;\\s]+)?\\s*;\\s*)|(?:[A-Za-z_][A-Za-z0-9_]*=[^;\\s]+\\s+))*(?:git\\s+(?:branch|diff|log|show|status)|npm\\s+(?:run\\s+(?:build|format:check|lint|test|typecheck)|test)|tsc)(?:\\s|$)": true,
-        "^(?:(?:export\\s+[A-Za-z_][A-Za-z0-9_]*(?:=[^;\\s]+)?\\s*;\\s*)|(?:[A-Za-z_][A-Za-z0-9_]*=[^;\\s]+\\s+))*(?:zen|zn|zenera)(?:\\s|$)": true
+        "awk": true,
+        "basename": true,
+        "cat": true,
+        "cd": true,
+        "comm": true,
+        "cut": true,
+        "date": true,
+        "diff": true,
+        "dirname": true,
+        "du": true,
+        "echo": true,
+        "env": true,
+        "file": true,
+        "find": true,
+        "grep": true,
+        "head": true,
+        "jq": true,
+        "ls": true,
+        "nl": true,
+        "printf": true,
+        "pwd": true,
+        "realpath": true,
+        "rg": true,
+        "sed": true,
+        "sort": true,
+        "stat": true,
+        "tail": true,
+        "tr": true,
+        "tree": true,
+        "uniq": true,
+        "wc": true,
+        "which": true,
+        "tsc": true,
+        "zen": true,
+        "zn": true,
+        "zenera": true,
+        "/^git (branch|diff|log|show|status)\\b/": true,
+        "/^npm (test|run (build|format:check|lint|test|typecheck))\\b/": true,
+        "/\\bfind\\b[^|;]*\\s-(exec|execdir|ok|okdir|delete)\\b/": false,
+        "/\\bsed\\b[^|;]*\\s-[A-Za-z]*i/": false,
+        "/\\bawk\\b[^|;]*\\b(system|print\\s*>|printf\\s*>)/": false,
+        "/^\\.?\\/?scripts\\/[A-Za-z0-9_.-]+\\.sh\\b/": true,
+        "/^\\.?\\/?\\.github\\/skills\\/[A-Za-z0-9_-]+\\/scripts\\/[A-Za-z0-9_.-]+\\.sh\\b/": true,
+        "podman": true
     }
 }

package/templates/parts/memory-terms.yaml.tmpl

@@ -0,0 +1,16 @@
+# What the agents work out, kept with the project rather than in the session
+# that found it out. `agents/memory-instructions.md` is what they read about
+# using it, and `zen memory` is how you look at it from the outside.
+#
+# Recall ranks by term overlap here, which finds a memory phrased the way the
+# question was and misses the rest. This project's provider publishes no
+# embeddings API; add one that does and point the store at it to rank by
+# meaning instead:
+#
+#   memory:
+#       embedding: main
+#
+#   embeddings:
+#       main: openai:text-embedding-3-small
+memory:
+    dir: memory

package/templates/parts/memory.yaml.tmpl

@@ -0,0 +1,12 @@
+# What the agents work out, kept with the project rather than in the session
+# that found it out. `agents/memory-instructions.md` is what they read about
+# using it, and `zen memory` is how you look at it from the outside.
+memory:
+    dir: memory
+    # Recall by meaning rather than by the words a question happened to reuse.
+    # The width is learned from the first response, so swapping this model
+    # later is refused rather than quietly mixing two vector spaces.
+    embedding: main
+
+embeddings:
+    main: {{embedding}}

package/templates/project/SPECIFICATION.md.tmpl

@@ -18,18 +18,25 @@ something in it — and report what was done in enough detail to be checked.
 - `default` — the entry point and the only agent; nobody to hand work to.
     - Establishes what it is looking at before it acts: reads a file before
       changing it, runs a command rather than predicting its output.
+    - Remembers what it worked out, so a later session starts from it rather
+      than from nothing.
 
 ## Tools and boundaries
 
 - Files — read, search, create, edit, move, delete. The workspace is the only
   writable thing, symlinks included.
 - Shell — commands run in the container, on that same workspace.
+- Memory — a graph of what earlier runs established, recalled before new
+  questions and added to deliberately. What goes in it, and what does not, is
+  `agents/memory-instructions.md`.
 - `assets/` is reference material, and read-only.
 {{web}}
 
 ## Environment
 
 - Model: `{{modelRef}}`, one for the whole project.
+- Memory: `memory/`, kept with the project and committed except for its
+  vectors, which are derived.
 - Sandbox: built from `sandbox/Dockerfile`, persists between runs, and can
   reach the network. What the work always needs belongs in the image, not in an
   instruction that reinstalls it on every run.