@zenera/cli 1.1.15 → 1.1.17

package/templates/editor/.github/prompts/new-agent.prompt.md

@@ -14,8 +14,8 @@ true, and you should say which:
 - its instructions **contradict** an existing agent's rather than extend them
 - it is a **parallel branch** target for a `fork:`
 
-If none holds, propose the smaller change instead — a skill, a prompt line, a
-tool grant — and stop. Adding an agent to solve a prompt problem is the failure
+If none holds, propose the smaller change instead - a skill, a prompt line, a
+tool grant - and stop. Adding an agent to solve a prompt problem is the failure
 mode this project cares most about.
 
 If it is warranted:
@@ -23,18 +23,18 @@ If it is warranted:
 1. Pick a name matching `^[a-z0-9]+(?:[-_][a-z0-9]+)*$`. It reaches the model as
    `transfer_to_<name>`, so the name is part of the routing surface.
 2. Write `agents/prompts/<name>.md`: one sentence of identity, a short procedure
-   or three to five rules, then what it must **not** do — especially the
+   or three to five rules, then what it must **not** do - especially the
    neighbouring agent's job. Second person, imperative, failure paths stated.
    No frontmatter, no meta-talk about the runtime.
-3. Add the `agents.yaml` entry. `description:` is written **for the model** — it
+3. Add the `agents.yaml` entry. `description:` is written **for the model** - it
    is the whole of what a sibling sees when deciding to hand off. Grant the
    narrowest `tools:` the job needs.
 4. Wire the return edge. A handoff does not come back on its own, so every
-   `A → B` needs a path from B back to A — directly, or through another agent.
+   `A → B` needs a path from B back to A - directly, or through another agent.
    `zen check` warns on an edge that has none. If what this agent really wants
    is an _answer_ rather than to give up the conversation, declare `fork:`
    instead: a branch returns by itself.
-5. Add a one-line comment above the entry saying why this agent exists — its
+5. Add a one-line comment above the entry saying why this agent exists - its
    job or its tier, not what the keys mean.
 
 Then run `zen check` and report what it said. If it fails, fix the file it

package/templates/editor/.github/prompts/new-skill.prompt.md

@@ -3,29 +3,29 @@ mode: agent
 description: Add a skill under agents/skills, with a description that routes.
 ---
 
-Add a skill to this project. A skill is curated instruction content — and
-optionally tools — loaded on demand instead of sitting in every system prompt.
+Add a skill to this project. A skill is curated instruction content - and
+optionally tools - loaded on demand instead of sitting in every system prompt.
 Reach for one whenever a rule applies only sometimes, or holds a fact that will
 change without the prompt changing.
 
 Ask what the skill must say and when it applies, if I have not already said.
 
 1. Create `agents/skills/<name>/SKILL.md`. That is the only skill layout there
-   is — a bare `agents/skills/<name>.md` fails `zen check` — and the folder is
+   is - a bare `agents/skills/<name>.md` fails `zen check` - and the folder is
    what lets the skill carry companions later: a rate table, an example letter,
    a schema, a script.
 2. Write the `description`. This is the routing key and the only thing the model
    sees before deciding to load the skill, so write it as **the condition under
    which the skill is needed**, not as a title. `Water policy` is a title;
-   `Escape of water from plumbing and tanks — and the freezing exclusion` is a
+   `Escape of water from plumbing and tanks - and the freezing exclusion` is a
    condition. If two skills could both match a case, sharpen both until they
    cannot.
 3. Write the body as instructions the model can act on: thresholds, exact
    wording, the boundaries of the rule, and what to do when the case falls
-   outside it. Put the facts here rather than in a prompt — that is the point of
+   outside it. Put the facts here rather than in a prompt - that is the point of
    the file.
 4. Put anything the rule computes or looks up in a file beside `SKILL.md` and
-   name it from the body by its absolute path — `python
+   name it from the body by its absolute path - `python
 /skills/<name>/scripts/calculate.py <id>`, not `scripts/calculate.py`. The
    folder is mounted read-only at `/skills/<name>/`, so the script writes
    nothing there; the agent needs `sandbox:*` to run it, and the interpreter has
@@ -37,7 +37,7 @@ Ask what the skill must say and when it applies, if I have not already said.
 6. Leave `name` out unless it must differ from the folder name, and leave
    `version`/`tags` out unless something uses them.
 
-Do not `preload:` it unless every case genuinely needs it — a preloaded skill is
+Do not `preload:` it unless every case genuinely needs it - a preloaded skill is
 a longer prompt, paid for on every call. Bind it under `agents[].skills.allow`
 if the agent's catalog is restricted.
 

package/templates/editor/.github/prompts/review-project.prompt.md

@@ -4,32 +4,71 @@ description: Review the project against the checklist before committing.
 ---
 
 Review this project the way a maintainer would, then report. Read
-`agents.yaml`, `INSTRUCTIONS.md`, every file under `agents/prompts/` and the
-skill descriptions under `agents/skills/` before saying anything.
+`agents.yaml`, every `agents/*instructions.md`, every file under
+`agents/prompts/` and the skill descriptions under `agents/skills/` before
+saying anything.
 
-Work the checklist in §9 of the copilot instructions. In particular:
+**Run the mechanical checks first, and report what they say:**
+
+```sh
+.github/skills/zen-review/scripts/review.sh
+```
+
+That is `zen check`, the §2.5 path sweep, the memory house-rules copy and the
+spec-sync record, in the order they matter. Load the `zen-review` skill for what
+each one owns and how to read its output. Do not re-verify by hand anything it
+already decided, and do not go further while `zen check` fails - nothing below
+matters until it passes.
+
+**Then list the capabilities this project turns on** — a `memory:` block, a
+`zen rag` index, a sandbox, a `SPECIFICATION.md` — and load the editor skill
+for each before judging it. The obligations live in the skill, not in
+`agents.yaml`, and `zen check` reports none of them. A capability that is
+already configured and already passing is exactly the case that looks finished
+and is not.
+
+Everything that follows is what no tool can see:
 
-- **Loads.** Run `zen check`. Nothing else in this review matters if it fails.
 - **One job each.** Can you state every agent's job in one sentence? If not,
   say which agent and what the two jobs are.
 - **Prompts.** Second person, imperative, failure paths stated, no hedging, no
-  politeness padding, no meta-talk about the runtime. Nothing in
-  `INSTRUCTIONS.md` that is true of only one agent.
+  politeness padding, no meta-talk about the runtime. Nothing in the house rules
+  that is true of only one agent, and nothing in `agents/instructions.md` that
+  belongs in a `<topic>-instructions.md` of its own because it only applies when
+  one capability is on.
 - **Facts.** Any number, threshold, fee or date living in a prompt is in the
   wrong file. Name it and say which skill it belongs in.
-- **Paths.** Work the checklist in §2.5 over `INSTRUCTIONS.md`,
-  `agents/prompts/*.md` and `agents/skills/*/SKILL.md`. Every absolute path must
-  be under `/workspace`, `/assets`, `/skills` or `/memory`; nothing may name a
-  project file the agent cannot open, and nothing may assume the workspace is
-  this directory.
+- **Paths.** For each candidate `check-paths.sh` printed: is it a path the
+  agent cannot open, or noise? Say which, and for a real one say what it should
+  have been. Judge the rest of the §2.5 checklist yourself — that no instruction
+  assumes the workspace is this directory, that every `/assets/…` and
+  `/skills/<name>/…` names a committed file, and that the agent holding the
+  prompt has the tool the path implies.
+- **Memory.** Anything this project decides for itself belongs in
+  `agents/memory-policy-instructions.md`, not in the copy — and it should say
+  something. Audiences that exist because an agent would be _misled_ by the
+  other slice, not merely because it does not need it.
 - **Skill descriptions.** Each one a condition, not a title; no two overlapping.
+  Every skill a folder with a `SKILL.md`, and a skill that ships a script writes
+  its `/skills/<name>/…` path.
 - **Tools.** Every grant justified by the agent's job; nothing mutating held by
-  an agent that only reads; every granted tool mentioned by the prompt.
-- **Routing.** Handoff targets have descriptions written for the model. No
-  ping-pong edges. No router that answers.
+  an agent that only reads; every granted tool mentioned by the prompt. An agent
+  with no `skills:` key indexes the whole catalog - check that every agent can
+  actually follow the skills it is offered.
+- **Sandbox.** `persist: true` unless a throwaway rootfs is wanted on purpose.
+  What the work always needs is in the image, not installed by a prompt on every
+  run.
+- **Control flow.** Whichever this project uses. A handoff moves the
+  conversation and must have a path back; a fork returns by itself and condenses
+  to one result, so whatever the caller needs must be in the branch's answer.
+  Wanting one lookup and spending the conversation on it is a fork, not a
+  handoff. No router that answers.
 - **Models.** Each agent on the cheapest tier that is right, not the safest.
-- **Cache.** Nothing volatile — dates, ids, counts — in the stable prefix.
+- **Cache.** Nothing volatile - dates, ids, counts - in the stable prefix.
 - **Secrets.** No key inlined anywhere; `.env` ignored, `sessions/` ignored.
+- **Specification.** Where a `SPECIFICATION.md` exists, `review.sh` reported the
+  record's mode. Judge the rest: the newest history entry's "Still open" is
+  honest, its baseline names that entry, and `.spec-sync/` is committed.
 
 Report as a list of findings, each naming the file and the line, ordered by how
 much it will cost to leave. Say plainly if you find nothing worth changing.

package/templates/editor/.github/prompts/sync-with-spec.prompt.md

@@ -3,24 +3,55 @@ description: Bring the project into compliance with SPECIFICATION.md, and record
 ---
 
 Make this project match `SPECIFICATION.md`. The specification is the intent;
-the files are the implementation. Where they disagree, the specification wins —
+the files are the implementation. Where they disagree, the specification wins -
 except where it is ambiguous, contradictory or impossible, which is what
 `SPECIFICATION-FEEDBACK.md` is for.
 
+## 0. Decide the size of this pass
+
+Load the `zen-spec-sync` skill first, before anything else and whatever state
+the project is in - a project with no baseline is the one that needs it most,
+because this pass has to make the first. Then, from the project root:
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh status
+.github/skills/zen-spec-sync/scripts/snapshot.sh diff
+```
+
+`status` answers `full`, `incremental` or `tampered`. Say which in the chat
+before reading anything, and on an incremental pass state the scope you drew
+from the diffs - the skill says how. `full` and `tampered` both mean the whole
+prompt as written below, from nothing.
+
+The diff covers both sides. `SPECIFICATION.md` and `SPECIFICATION-FEEDBACK.md`
+say what has been **asked for** since the last pass; `agents.yaml` and every
+file under `agents/` say what has been **built or hand-edited** since then. The
+first narrows the pass to the work nobody has done; the second only widens it,
+because a prompt or skill someone changed outside a pass still has to be
+accounted for against the specification.
+
+The scope decides what you **read and edit**. It never decides what you
+**verify**: §6, §7 and the four checks in the skill run at full size on every
+pass, however small the diff.
+
 ## 1. Read before changing anything
 
 Read, in this order, and do not edit until all of it is read:
 
-1. `SPECIFICATION.md` — what the system is meant to be.
-2. `agents.yaml` — providers, models, embeddings, agents, tools, handoffs,
+1. `SPECIFICATION.md` - what the system is meant to be.
+2. `agents.yaml` - providers, models, embeddings, agents, tools, handoffs,
    skills, sandbox.
-3. `INSTRUCTIONS.md` and every file under `agents/prompts/`.
+3. Every `agents/*instructions.md` and every file under `agents/prompts/`.
 4. Every `agents/skills/*/SKILL.md`, plus what each skill folder ships.
 5. `assets/`, `sandbox/Dockerfile` and every script under `scripts/`, starting
    with `scripts/_setup.sh`.
-6. `SPECIFICATION-FEEDBACK.md`, if it exists — do not re-raise something already
+6. `SPECIFICATION-FEEDBACK.md`, if it exists - do not re-raise something already
    open there.
 
+On an incremental pass this list narrows to the artefacts the scope implicates,
+and to the changed hunks of the specification rather than all of it. The
+narrowing is a claim: name what you skipped and why the diff does not reach it.
+
 Run `zen check` first and record what it said. A project that does not load is
 the first thing to fix.
 
@@ -29,11 +60,11 @@ the first thing to fix.
 Produce a difference list before touching a file. For every item in the
 specification, decide which of these it is:
 
-- **present and correct** — leave it alone
-- **missing** — the specification asks for it and nothing implements it
-- **divergent** — implemented, but not as specified
-- **extra** — implemented, and the specification does not ask for it
-- **unclear** — the specification does not say enough to implement it
+- **present and correct** - leave it alone
+- **missing** - the specification asks for it and nothing implements it
+- **divergent** - implemented, but not as specified
+- **extra** - implemented, and the specification does not ask for it
+- **unclear** - the specification does not say enough to implement it
 
 Check at least: the model and embedding ids and which agent uses which; that
 every agent named in the specification exists with that job and no second job;
@@ -41,25 +72,31 @@ handoff edges and fork permissions; the tools each agent holds; every skill the
 specification implies; and every setup step, index or asset it depends on.
 
 Then build the difference the other way, because the list above can only find
-what the specification asked for and nothing implements. Read `INSTRUCTIONS.md`,
-each `agents/prompts/*.md` and each `SKILL.md` **line by line**, and for every
-line name the specification item it serves. A line serving none is an **extra** —
-the category covers a single sentence in a prompt, not only a whole file. Three
-things to look for while reading, none of which the forward pass can see:
+what the specification asked for and nothing implements. Read every
+`agents/*instructions.md`, each `agents/prompts/*.md` and each `SKILL.md` **line
+by line**, and for every line name the specification item it serves. A line
+serving none is an **extra** - the category covers a single sentence in a prompt,
+not only a whole file. Three things to look for while reading, none of which the
+forward pass can see:
 
 - **A line that contradicts another file.** One prompt against another, a prompt
-  against `INSTRUCTIONS.md`, or a prompt against `agents.yaml` — an instruction
+  against the house rules, or a prompt against `agents.yaml` - an instruction
   to use a tool the agent does not hold, to hand to an agent that is not in its
   `handoffs:`, or to load a skill outside its `allow:`.
 - **A line that asks for something the system already supplies.** A question put
   to the user about a value that arrives from the environment, a file or an
   earlier step is unanswerable, and the answer would be discarded.
-- **A line the agent cannot carry out** — naming a path it cannot reach, a tool
+- **A line the agent cannot carry out** - naming a path it cannot reach, a tool
   it was not granted, or an agent it cannot transfer to.
 
 These are bugs whatever the specification says: fix them in place and report each
 one. An extra that is merely unspecified is reported under `➕`, not removed.
 
+On an incremental pass this reverse reading covers every file this pass touched
+plus every file the implementation diff in §0 named - an edit made in this
+session, or made by hand since the last pass, is exactly where a fresh
+contradiction comes from. On a full pass it is the whole tree, as above.
+
 ## 3. Change the smallest thing that closes the gap
 
 Apply the fixes in the order the copilot instructions prefer: a prompt or skill
@@ -83,19 +120,19 @@ the model to compute or remember. Specifically:
 Never delete an **extra** without saying so. Report it, say why the
 specification does not cover it, and leave it unless I tell you to remove it.
 
-Do not invent a value the specification does not state — a model id, a limit, a
+Do not invent a value the specification does not state - a model id, a limit, a
 retry count, a file path. That is an entry in `SPECIFICATION-FEEDBACK.md`, not a
 guess.
 
 ## 4. Every setup step is a script
 
-Anything the project needs done before it can run — building an index, fetching
-a document, generating a file, warming the sandbox image — is a shell script,
+Anything the project needs done before it can run - building an index, fetching
+a document, generating a file, warming the sandbox image - is a shell script,
 not a paragraph of instructions for a human.
 
 - One step per file, under `scripts/`, named after the step:
   `scripts/build-schema-index.sh`, `scripts/fetch-api-docs.sh`.
-- `scripts/_setup.sh` is the **only** entry point — the leading underscore is
+- `scripts/_setup.sh` is the **only** entry point - the leading underscore is
   what separates the runner from the steps it runs. It runs the steps in the
   order they depend on each other and is the single command that initialises the
   project. `zen init` writes it; adding a step is adding `scripts/<name>.sh` and
@@ -114,7 +151,7 @@ not a paragraph of instructions for a human.
 - **It must be watchable.** `scripts/_setup.sh` tees each step's output to
   `.tmp/logs/setup-<step>.log`, prints a heartbeat line while a long step runs,
   and finishes with one line per step: `ok`, `skipped`, or `failed`.
-- **Everything transient goes under `.tmp/`** — logs, scratch files, downloads,
+- **Everything transient goes under `.tmp/`** - logs, scratch files, downloads,
   test output, and the temporary path a step writes to before moving its
   artefact into place. Nothing else in the tree is a scratch directory, and
   `.tmp/` is git-ignored: add it to `.gitignore` if it is not there already.
@@ -132,44 +169,175 @@ anything in the
 specification is unclear, contradictory, impossible, or wrong. If there is
 nothing to raise, say so in the chat and do not create the file.
 
-Group entries under these headings, and omit a heading that has no entries.
-The file is scanned before it is read, so keep the emoji on every heading:
+**It is a questionnaire, and answering it must take one gesture.** Every
+question carries two to four written-out answers, each with a `[ ]` box in its
+heading. The reader marks the box of the one they want - `[x]` - and deletes the
+others, then sends `/update-spec-from-feedback`, which folds what survived into
+`SPECIFICATION.md`. Either gesture alone is enough, and the file says so in
+every question.
+
+Two rules that come before everything else in this section:
+
+- **No markdown tables anywhere in this file.** A table is unreadable the moment
+  a pane is narrow or a cell wraps, and this is a file people read in a side
+  panel. Every list is a list.
+- **Never write a question the reader has to do work to answer.** No paragraph
+  ending in "is that what you meant?", nothing that requires reading the
+  implementation, and no answer phrased as a decision still to be made. If you
+  cannot write two answers a reader could pick between, you have not understood
+  the problem well enough to ask about it yet.
+
+The file opens with one short paragraph: how many questions are open, and how to
+answer them - put an `x` in the box of the answer you want, delete the answers
+you do not want, or replace them all with a sentence of your own, then send
+`/update-spec-from-feedback`. Then a contents list, one line per question: its
+number as an anchor link, the question in under ten words, and what is built in
+the meantime. Then the questions, grouped under these headings, omitting any
+heading with no questions. The file is scanned before it is read, so keep the
+emoji on every heading:
 
 ```markdown
 # Feedback on SPECIFICATION.md
 
-## 🛑 Blocking — cannot implement without an answer
+## 🛑 Blocking - cannot implement without an answer
 
-## ❓ Ambiguous — implemented one way, confirm the choice
+## ❓ Ambiguous - implemented one way, confirm the choice
 
 ## ⚡ Contradictions
 
 ## ✏️ Errors and typos
 
-## ➕ Out of scope — implemented but unspecified
+## ➕ Out of scope - implemented but unspecified
+
+## ✅ Answered - folded into the specification
+```
+
+`✅` is written by `/update-spec-from-feedback`, not by you. Leave what is there
+alone except to strike an entry this pass has actually implemented, and say in
+the chat which ones you closed.
+
+### The shape of one question
+
+Each question is its own `###` heading - the emoji of its section, `Q` and a
+number, then the question itself, ending in a question mark. Under it, in this
+order:
+
+- **Where it comes from** - the specification text quoted as a blockquote,
+  introduced by a link to the exact line,
+  `[SPECIFICATION.md#L66](SPECIFICATION.md#L66)`, plus the section name. Link
+  every line you quote; a reader must reach it in one click. For a question
+  about something the specification does not say at all, link the section it
+  would belong to and say that it is silent there.
+- **Why it is a problem** - two or three sentences on what goes wrong, in terms
+  of behaviour: what an agent does, what a run produces, what breaks. Not
+  "unclear" or "ambiguous", which describe the sentence rather than the damage.
+- **Built in the meantime** - what the implementation does now, and the one fact
+  that made it the default. Or "Nothing - blocked."
+- **To answer** - the same sentence on every question, word for word: put an `x`
+  in one box below and delete the other answers, either one is enough.
+
+Then two to four answers, each its own `####` heading of the form
+`#### [ ] A. <the answer in one line, as the reader would say it>`. The one that
+is implemented comes first and is marked `_(built)_`, so the file reads as "this
+is what happens if you change nothing"; mark one `_(recommended)_` where it is
+better for a reason the reader can check. Under each answer heading:
+
+- **What it changes** - one or two sentences on the consequence of choosing it:
+  what the system would then do differently, and what it costs.
+- **The specification text**, in a fenced block, introduced by where it goes -
+  "replace line 66", "add after line 21", "delete lines 30-32". Written in the
+  specification's own voice and format so it can be pasted without editing.
+
+Every answer carries its own box and its own text. They are alternatives that
+will be read alone, so nothing may be shared between them and nothing may refer
+to a sibling ("as above", "same as A"). Where an answer needs a value only the
+reader has, put a `<placeholder>` in the block and say in **What it changes**
+what to substitute.
+
+Two rules on the answers themselves:
+
+- **An answer is a real alternative**, not a restatement of the question or a
+  hedge. "Decide later" is not an answer; "leave it unspecified, and the
+  reviewer keeps using whatever the default agent uses" is.
+- **Never write only one answer.** A question with nothing to choose between is
+  not a question. Even an `✏️` typo has two: the correction, and leaving it as
+  written with a line saying what stays wrong.
+
+Under `➕` the two answers are fixed: keep it, whose block is the specification
+text that would cover what was built, and remove it, whose **What it changes**
+says what removing it would cost and which files would go.
+
+### One question, written out
+
+Copy this shape exactly - the outer fence is four backticks only so the example
+can contain its own:
+
+````markdown
+### ❓ Q4. Do the three agents share one memory, or keep their own?
+
+**Where it comes from** - [SPECIFICATION.md#L14](SPECIFICATION.md#L14), _Common
+memory strategies_:
+
+> use memory to save plans of answering what was delegated to what
+
+**Why it is a problem** - the specification says what each agent writes and
+never says who may read it. Memory is one graph with an audience on every node,
+so this decides whether the orchestrator can plan from what a specialist
+resolved last week, or re-derives it every time.
+
+**Built in the meantime** - one shared slice: `memory: true` on all three, so
+anything one agent writes, another can recall. Chosen because nothing in the
+specification separates them.
+
+**To answer** - put an `x` in one box below and delete the other answers. Either
+one is enough.
+
+#### [ ] A. All three agents share one memory _(built)_
+
+**What it changes** - a lookup is paid for once for the whole system, and every
+agent's recall competes with every other agent's notes for the same few slots.
+
+Add under _Common memory strategies_, after line 17:
+
+```markdown
+All three agents read and write one shared memory: whatever one of them
+discovers is recallable by the others.
 ```
 
-Each entry is one bullet, opening with the emoji of the heading it sits under,
-then four parts in this order:
+#### [ ] B. Each agent keeps its own memory
 
-- **What the specification says**, quoted, with the section it is in.
-- **Why it cannot be implemented as written** — the specific gap, not "unclear".
-- **What was done in the meantime**, or "nothing — blocked".
-- **The question**, phrased so a one-line answer unblocks it.
+**What it changes** - recall gets sharper and cheaper because an agent only ever
+sees its own kind of note, and the same lookup is repeated by whoever did not do
+it first.
 
-Use no other emoji anywhere in the file — one per entry is what makes them
-scannable. Keep entries factual and short. Do not editorialise about the
-specification's quality, do not restate the runtime, and do not copy the whole
-section in.
-Append to the existing file rather than rewriting it; strike an entry only when
-this pass has actually resolved it, and say in the chat which ones you closed.
+Add under _Common memory strategies_, after line 17:
+
+```markdown
+Each agent reads and writes only its own memory. A finding one agent needs from
+another travels as part of the hand-off, not through the store.
+```
+````
+
+Use no emoji except the one on each heading. Keep the prose short. Do not
+editorialise about the specification's quality, do not restate the runtime, and
+do not copy a whole section in.
+
+Append to the existing file rather than rewriting it, keeping the numbering and
+the contents list in step. Numbers are never reused: a struck question's number
+retires with it.
+
+Read the feedback diff from §0 before writing: a question the human answered
+since the last pass is work to close, not a question to ask again. If a question
+has a box marked `[x]`, or one answer left under it, and no `✅` entry, the
+reader answered it and never ran `/update-spec-from-feedback` - implement that
+answer, fold its text into `SPECIFICATION.md` yourself, and say so in the chat.
 
 ## 6. Run `scripts/_setup.sh` and watch it finish
 
 After `zen check` passes, run `scripts/_setup.sh` yourself. A pass is not done
 until it has run to completion in this session.
 
-It is slow — an embedding index is minutes, not seconds — so start it in the
+It is slow - an embedding index is minutes, not seconds - so start it in the
 background and follow the logs instead of waiting blind:
 
 - Tail `.tmp/logs/setup-*.log` and check the output artefact is still growing.
@@ -182,7 +350,7 @@ background and follow the logs instead of waiting blind:
 - Do not kill a quiet step. Confirm the process is dead or the log and the
   output have both stopped growing before calling it stuck.
 - On failure, read that step's log, fix the cause, and run `scripts/_setup.sh`
-  again — re-running is the fix path, not a reset. If the same step fails twice
+  again - re-running is the fix path, not a reset. If the same step fails twice
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
@@ -196,10 +364,29 @@ fail. Then report in the chat:
 
 - what changed, file by file, and which specification item each change closes
 - every prompt or skill line that served no specification item, and what became
-  of it — corrected, or reported and left alone
+  of it - corrected, or reported and left alone
 - the outcome of every `scripts/_setup.sh` step, and what each one produced
 - what is still open, with a pointer to its `SPECIFICATION-FEEDBACK.md` entry
 - anything you found that the specification does not cover at all
 
+## 8. Record the pass
+
+Last, and only once §6 and §7 have actually passed. Write
+`.spec-sync/history/<stamp>.md` in the format the `zen-spec-sync` skill gives -
+including `Still open`, which is the only place the next pass learns that an
+unchanged specification line is not yet implemented - and then:
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh commit
+```
+
+In that order, never the other way. Moving the baseline before the pass has
+finished records a specification as applied that was not: the next pass diffs
+against it, sees nothing to do, and the work is never done by anybody. A pass
+that fails with the baseline unmoved costs one repeat.
+
+A pass that changed nothing still writes a history file and still commits. Say
+in the chat which history file you wrote and that the baseline moved.
+
 Do not report a specification item as done unless the file that implements it
 exists, `zen check` passes, and `scripts/_setup.sh` completed every step it owns.