@zenera/cli 1.1.16 → 1.1.18

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 /spec-sync-project 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

@@ -13,27 +13,57 @@ something in it — and report what was done in enough detail to be checked.
 - One request at a time, in one workspace, with the person who asked it present.
 - No schedule, no queue, nothing that outlives the session it was asked in.
 
+## Models
+
+- `{{modelRef}}` — one model for the whole project, used by every agent.
+- Named once in `agents.yaml` so it can be swapped in one place. Nothing here
+  depends on which model it is; a project that later needs a cheaper model for
+  one job adds a second alias rather than scattering the choice.
+
+## Setup
+
+- Run once, before any session: whatever has to exist before work can start —
+  an index built, a document fetched, a file generated.
+- `scripts/_setup.sh` is the one command that does it, and `scripts/<name>.sh`
+  are the steps it runs in order. A step is safe to run twice and reports
+  `skipped` the second time.
+- Currently: no steps. Nothing has to be prepared before a run.
+
 ## Agents
 
 - `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.
-- Setup: none. `scripts/_setup.sh` is where a step would go, and it has none.
+
+## Testing
+
+- `zen check` passes: the project loads, and every model, tool and skill an
+  agent is given resolves. It says nothing about whether the prose is right.
+- `scripts/_setup.sh` run twice in a row reports every step `skipped` the
+  second time.
+- A run against a real request: the workspace holds the change described, and
+  the reply's account of it matches what is on disk.
 
 ## Done means
 

package/templates/project/agents/memory-instructions.md

@@ -0,0 +1,278 @@
+# Memory
+
+This project has a memory: a graph of what earlier runs worked out, kept with
+the project rather than with the session. It is reached **only** through the
+`memory_*` tools - `memory_search` to find, `memory_load` to read,
+`memory_commit` to write.
+
+It exists to make the next run cheaper. Work that cost something - a long
+investigation, a fan-out of searches, a build, an invocation found by trial -
+should be paid for once. A recollection is a cache hit: check it, do not
+rebuild it.
+
+## What belongs in it
+
+One question decides both what to keep and how far to trust it:
+
+**Can the next run get this itself, cheaply and current?**
+
+| When the answer is                                                                    | Keep                                                                |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| one read, one call, one command away                                                  | the way to get it - the route, the call, the script, the invocation |
+| assembled from several sources, with a judgement on top                               | what you concluded, and a pointer to every source it came from      |
+| out of something that cannot change - a released spec, a pinned or versioned document | the finding itself, whole, in a file that names where it came from  |
+| a reading of the moment - an API response, a query result, what a script printed      | the call that produces it, never the reading                        |
+
+Remember the **route** when the answer is cheap, the **answer** when the route
+is expensive, and never a value that is stale by the next run.
+
+## How it is organised
+
+A node is one thing worth keeping. It carries a `kind`, a `text` - the only
+thing searched - and optionally a remembered file. An edge says how one node led
+to another.
+
+The two halves do different jobs, and the split is the same every time: the
+**text is how the node is found** - what it is, what it establishes, where it
+came from - and the **file is what the node holds**. Only the text is searched,
+and only its first 160 characters are ever shown, so content written into it is
+both unfindable and in the way. Once something is worth committing at all, the
+usual shape is therefore a short description and a file behind it.
+
+A node with no file is for what fits on **one line** - a path and a line range,
+a command, a standing instruction, a single stated fact. If what you are keeping
+runs past a line or two, it is content, and content goes in the file.
+
+| Kind         | Is                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `task`       | the request that started a piece of work                                             |
+| `plan`       | an approach that worked and would work again                                         |
+| `fact`       | a durable truth about this codebase, API or environment                              |
+| `snippet`    | a few lines of code or configuration                                                 |
+| `file`       | an artifact kept whole - a script to re-run, an answer or passage too big for a text |
+| `operation`  | an external call that was made - endpoint, command, query. The call, not its answer  |
+| `preference` | a standing instruction from the user                                                 |
+
+| Relation     | Reads as                                            |
+| ------------ | --------------------------------------------------- |
+| `PRODUCED`   | the source led to the target being made             |
+| `CALLS`      | the source invokes the target                       |
+| `SUPERSEDES` | the source replaces the target; the target is stale |
+| `INFORMED`   | the source was context the target was built from    |
+
+So a remembered piece of work is a subgraph, not a row:
+
+```
+task       the request that started this
+  PRODUCED → file | snippet | operation     what came out of it
+  INFORMED ← fact                            what had to be known first
+file
+  CALLS    → operation                       what it calls
+```
+
+What you are shown is ranked, masked and clipped. **Assume a recollection is
+part of the answer, never all of it.**
+
+Relation is what decides where the clipping falls. Everything reached across
+`PRODUCED`, `CALLS` or `SUPERSEDES` is the work itself; everything reached
+across `INFORMED` is context, and context is what a short recollection drops
+first - so the answer degrades by losing its background rather than by being cut
+in half. Attach with `INFORMED` what **explains** a node, never what the next run
+needs in order to **use** it: the endpoint a script calls, or the request that
+produced it, belongs on the spine, where it is still there when the budget is
+tight.
+
+`INFORMED` also reads in a direction - from the background to the work it fed,
+so a `fact` informs an answer and never the other way round. Written backwards
+it still traverses, and still renders; it just says the answer was context for
+its own source.
+
+## Reading it
+
+`memory_search` hands back an outline of a subgraph with each node's text cut to
+160 characters. `memory_load` is what reads a node whole, by id - load anything
+you are going to rely on.
+
+A remembered file appears at `/memory/<id>.<ext>`. Open it or run it, but arrive
+at that path through `memory_load`, never by looking around in the directory.
+
+**Never read the store directly.** `/memory` holds `graph.json`, `vectors.f32`,
+`vectors.json` and `manifest.json` - its internal format. Do not open, list,
+grep, `cat` or `find` them, and do not point a shell command at that directory:
+
+- it is ranked by **meaning**, so substring matching misses the hits;
+- `graph.json` is every node ever committed, as one line;
+- a raw read bypasses the audience mask and serves **superseded** nodes -
+  corrections that were withdrawn - as if they were current;
+- it records no use, so the ranking that decides what gets recalled next decays;
+- another run may be writing, and the manifest is written last.
+
+A memory is a record, not an authority - but checking one is not the same as
+redoing it. Every node names where its content came from, so confirm the
+recollection there: the named lines still say what the node says, the route
+still resolves, the command still exists. Work it out from nothing only when
+that check fails, when the source is one that changes under you, or when being
+wrong is expensive. A check that costs what the original investigation cost is
+not a check - it is the investigation again, and the memory bought nothing.
+
+## Searching it
+
+Search **before** paying for anything: an investigation, an index query, a
+build, a long command. The point is not to find a pointer - it is to arrive at
+the answer without buying it twice.
+
+One `memory_load` is not cheaper than re-reading the single file a node names.
+It is far cheaper than redoing what produced that node: several documents read
+in sequence, a fan-out of searches, a delegated lookup, a long run. Price a
+recollection against what it **saves**, never against one read.
+
+Phrase the query as the question you are actually asking, in the words a person
+would use - node texts are written to be found that way. Narrow with `kinds`,
+`newer_than`, `limit`, `max_hops` and `max_nodes` when a recollection comes back
+broad rather than wrong.
+
+Recalling nothing is not proof of anything: work it out normally, then commit
+the result so the next run does not repeat it.
+
+## Updating it
+
+Commit when **the next run would otherwise have to work this out again** and
+working it out cost more than a `memory_load` will. The measure is what the
+answer COST, not what kind of thing it is: one cheap tool call away, do not;
+five reads, a fan-out and a judgement, commit the judgement and not only the
+five paths.
+
+| Worth committing                                                  | Not worth committing                                                |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
+| The route through the codebase to a recurring question            | A verbatim copy of one living file, which a read gives current      |
+| What a schema or docs search resolved to, and what you made of it | The ranked guesses it returned on the way there                     |
+| The call or command sequence that turned out to be necessary      | A single tool call that answers in milliseconds                     |
+| The exact invocation that finally worked, with its directory      | The request restated, or notes on progress                          |
+| A working script or request body, committed whole                 | What running it printed - a reading, which the script gives current |
+| An interface that behaved differently from its documentation      | What a call returned, which the call gives current                  |
+| The passage itself, when its source cannot change under you       | A passage quoted out of something that can                          |
+| A proven absence - looked here and here, it is not there          | Anything not actually verified                                      |
+
+A search over a schema or a documentation index costs a round trip and comes
+back ranked, so it is the thing most worth not paying for twice. Commit what it
+**resolved to** - the operation and its shape, or the document, heading and line
+range - **and what you concluded from reading it**. The pointers alone make the
+next run repeat the reading; the conclusion alone cannot be checked. Both, in
+one subgraph, and the next run answers at once and verifies cheaply.
+
+When the index is over something pinned - a released spec, a versioned reference
+tree - go one further and carry the passage itself in a `file` node, headed with
+the documents and line ranges it was taken from. The pointer says where to look
+and the conclusion says what it meant, but only the passage saves the next run
+from opening the sources to find out what they actually said.
+
+Then the rules for writing it down:
+
+**Commit the whole subgraph in one call.** A script with no record of what asked
+for it, or a fact with nothing that acts on it, is a memory nobody can use.
+
+**Say where the content came from.** This is what lets an incomplete
+recollection be continued instead of believed:
+
+| The node holds                  | Name                                                                                                                          |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| A fact about this codebase      | the file and the line range it was read from - `src/models/factory.ts:120-168`                                                |
+| Anything spanning several files | every one of them, each with its range, in the order they are read                                                            |
+| An API route or a behaviour     | the document and operation id, or the request sent and the status that came back                                              |
+| Something a document states     | document, heading and line range, next to what it states - the pointer is how the passage is checked, not a substitute for it |
+| Something a command established | the exact command, its arguments, and the directory it ran in                                                                 |
+| A plan                          | the steps, and where each step's target lives                                                                                 |
+| A negative result               | where you looked, so the search is not repeated                                                                               |
+
+**Write the text as the question.** Not the way the system that produced it
+names things, and with the identifying facts first - only the first 160
+characters appear in a recollection.
+
+| Instead of        | Write                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `fix for the 409` | `A duplicate customer email returns 409, not 422 - retry is wrong (src/billing.ts:88-104)` |
+| `retry.ts`        | `Where retries are configured: one policy for all adapters, src/models/factory.ts:40-96`   |
+
+**Put the content in a file, not in the text.** This is the usual shape, not a
+special case: a script, a config, a query, a request body, a rendered table of
+findings, a passage worth keeping whole, an answer that took several sources to
+assemble - all of it is a `file` node split in two. The `text` describes the
+content and says where it came from; the file holds the content itself, whole
+and exactly as it was - the entire block, not a summary of it. Content in a file
+costs nothing until a `memory_load` asks for it, and comes back at
+`/memory/<id>.<ext>` to be read or run. Commit a node with no file only when the
+whole of what you know is one line long.
+
+**Name the sources inside the file as well as in the text.** The two halves
+arrive separately - a recollection shows the text, and only a later
+`memory_load` opens the file - so a file read on its own is an assertion with
+nothing behind it. Open it with a header naming every document, heading and line
+range the content came from, and when it was taken, then the content verbatim:
+
+```markdown
+<!-- reference-docs-1.4/overview.html.md:112-160 and
+     reference-docs-1.4/architecture.html.md:38-91
+     pinned 1.4 reference tree, read 2026-04-09 -->
+
+...the passages, whole and unedited...
+```
+
+Use whatever comment form the file's own format takes. A header costs two lines
+and is the difference between a copy that can be re-checked against its source
+and one that can only be believed.
+
+Make the file self-contained - it will be opened in a different workspace, so it
+takes its inputs as arguments and reads credentials from the environment - and
+say so in the text. **Give it a configurable output path.** `/memory` is
+read-only: a script that writes beside itself fails, while one that takes
+`--out` writes into the workspace and is reusable unchanged. Use a `snippet`
+only for the few lines that are read rather than run.
+
+A remembered script runs from where it is - the mount is readable, so
+`python3 /memory/<id>.py` or `node /memory/<id>.js` needs no copy first:
+
+```
+python3 /memory/01JD9Q7X8N2K4M6P8R0T2V4W6Y.py --out ./report.csv
+```
+
+**Read it before running it.** It is code an earlier run wrote, recalled by
+similarity: `memory_load` returns its contents, or its path when it is large, in
+which case read the file. Confirm it is the thing you want, and that its
+arguments are what you think, before executing anything.
+
+**Commit what produces the answer, not the material it was made from.** This is
+about what to keep, not what form to keep it in - whatever survives the test
+still goes in a file. A file the project holds: the pointer, never a copy - a
+copy goes stale silently and looks exactly as authoritative when it is wrong. An
+external call: the `operation` - route, auth, the parameters that mattered, the
+status a case returns - never the body that came back. A script: the file and
+the invocation that worked, never its output. What a run ESTABLISHED belongs in
+the node's text - that it works, what it was run against, the verdict that was
+the point; the rows it emitted do not.
+
+Two things fall outside that. An answer you assembled from several sources is a
+copy of none of them and exists nowhere in the project, so commit it, with a
+pointer node per source `INFORMED`ing it. And a source that cannot change under
+you (a released specification, a pinned dependency, a versioned reference tree)
+does not go stale silently, so the finding may be kept whole.
+
+When it is kept whole, keep it as a `file` node rather than as a longer `text`:
+the text says what the passage establishes and names the documents it came from,
+the file carries the whole block behind its provenance header. Say in the text
+which kind of source it was, so a later run can see why a copy was allowed. A
+pointer alone, with nothing of what the source said, makes the next run open all
+of it again - which is the reading the memory was supposed to buy.
+
+A body or a result set may still be worth keeping as a SPECIMEN - a shape to
+write against, a case to reproduce. Commit it as a `file` node whose text says
+what was asked, when, and that it is what came back then, never what the data
+is. Keep credentials and personal data out of the store: it outlives the
+session and every later run can read it.
+
+**Correct by superseding, never by editing.** Commit the new node and link it to
+the old one with `SUPERSEDES`. Recall then stops serving the wrong answer
+without destroying the record of why it changed.
+
+**Ask whether it will still be true next month.** Memory has no expiry and no
+reviewer. A durable fact about this project survives; a fact about this
+afternoon's state is how a graph becomes confidently wrong.

package/templates/project/agents.yaml.tmpl

@@ -1,8 +1,8 @@
 # Who exists, and what they may reach for.
 #
-# This implements the Agents, Tools and boundaries, and Environment sections of
-# SPECIFICATION.md. Change what the system does there first, then bring this
-# file to match it — `/sync-with-spec` in your editor does exactly that.
+# This implements the Models, Agents, Tools and boundaries, and Environment
+# sections of SPECIFICATION.md. Change what the system does there first, then bring this
+# file to match it — `/spec-sync-project` in your editor does exactly that.
 #
 version: 1
 
@@ -29,12 +29,21 @@ sandbox:
     build:
         dockerfile: sandbox/Dockerfile
 
+{{memory}}
+
 agents:
     - name: default
       description: The entry point.
       # Instructions live in agents/prompts/<name>.md and are picked up by
       # convention — no need to name the file here.
       #
+      # The memory store above is opened for this agent: it can search, load
+      # and commit, and it recalls on its own before answering something new.
+      # The block form narrows that — `memory:` with `access: read` lets it use
+      # what is there without adding to it. Drop the line and it never sees the
+      # store at all.
+      memory: true
+      #
       # workspace:* is every file tool at once, sandbox:* is the shell. Name
       # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
       #