@zenera/cli 1.1.19 → 1.1.21

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

@@ -0,0 +1,151 @@
+---
+requires: [fork]
+---
+
+# Forking
+
+These rules are for agents that can fork. If `fork` is not among your tools,
+work that looks parallel stays sequential here.
+
+Forking runs work in separate conversations and brings back only the answers.
+
+A branch is a run of its own: its own conversation, its own tool calls, its own
+reasoning. None of that returns. What returns is each branch's final answer, as
+the result of your `fork` call — so whatever you will need afterwards has to be
+_in_ that answer, and the branch only knows it if your instructions say so. Work
+whose value is the trace rather than the conclusion should not be forked at all.
+
+The instructions you write are the entire assignment. A branch cannot ask you a
+question, cannot see what its siblings are doing, and cannot be corrected once
+it starts. Say what it must do, what it must leave alone, and the exact shape of
+what it must hand back.
+
+**One branch is delegation**: the work happens elsewhere and you get the
+conclusion instead of the transcript. Use it when another agent is better suited
+to the job, or when the job would otherwise fill this conversation with material
+you have no use for afterwards — a long file survey, a noisy build loop, an
+exploration down a path that may go nowhere. **Several branches are a fan-out**:
+independent parts of one task, worked at the same time, merged by you. It is the
+same call either way; the number of branches is the only difference.
+
+Do not fork a sequence. Branches run at once and can exchange nothing, so a step
+that needs the step before it has to stay in this conversation.
+
+## When it is worth it
+
+One question decides it: **could this be finished by someone who cannot ask you
+anything, and would a written answer be all you want back?** If either half is
+no, the work stays here.
+
+| The work in front of you                                                                     | What it is                                               |
+| -------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| The same question asked of twenty things — files, endpoints, regions, candidate fixes        | A fan-out: one branch each, merged by you                |
+| One task whose parts need different skills and none of them the others                       | A fan-out too: each branch on the agent that fits        |
+| A job another agent is plainly better at                                                     | Delegation: one branch, on that agent                    |
+| Long and noisy with a short verdict — a build loop, a bisect, a survey that may find nothing | Delegation: you get the verdict, not the noise           |
+| Find the config, then change it, then test it                                                | Not a fork. Each step needs the one before it            |
+| A change you would want to steer while it happens                                            | Not a fork. A branch cannot be corrected once it starts  |
+| One read, one search, one command                                                            | Not a fork. A whole conversation to save yourself a line |
+| Two jobs that would write the same file                                                      | Not a fork until they write different files — see below  |
+
+## Fanning out
+
+Branches run at the same time, so a fan-out costs about as long as its slowest
+branch instead of the sum of all of them. That alone is reason enough: work you
+would otherwise grind through one item at a time, whose items do not need each
+other, is a fan-out. It is the most ordinary use of this tool.
+
+Which agent runs a branch is set per branch, and that is what tells the two
+shapes apart.
+
+**One job, many subjects.** The same work repeated over different material, so
+every branch runs the agent that would have done it anyway — usually you. Write
+the assignment once, then vary the subject and the destination:
+
+> `auth` — Audit `/workspace/src/auth/**` for calls that bypass the rate
+> limiter. Write the hits to `/workspace/reports/audit-auth.md`, one line each
+> as `file:line — call — why`. Return how many and the worst one.
+>
+> `billing` — The same, over `/workspace/src/billing/**`, to
+> `/workspace/reports/audit-billing.md`.
+>
+> `admin` — The same, over `/workspace/src/admin/**`, to
+> `/workspace/reports/audit-admin.md`.
+
+**One job, many trades.** The task divides by what each part demands rather than
+by what it is about, so the branches differ from each other and each names the
+agent that fits:
+
+> `tests`, on the agent that runs the suite — Run it against the current tree.
+> Return every failure with the first assertion of each, and nothing else.
+>
+> `security`, on the agent that reviews for security — Review the change in
+> `/workspace/src/auth/**`. Return findings worst first, file and line for each.
+> Change nothing.
+>
+> `docs`, on the writing agent — Bring `/workspace/docs/auth.md` in line with
+> the code as it now stands. Return the path and a one-line note per section you
+> touched.
+
+Both shapes hold to the same two rules. Divide so that nothing is covered twice
+and nothing is left out: overlap is paid for twice over, and a gap comes back as
+silence rather than as a complaint. And repeat in each branch's instructions
+whatever that branch needs, because a sibling's finding will never reach it.
+
+## Choosing `context`
+
+`context` decides what each branch starts from. It is one setting for the whole
+call, chosen per call:
+
+- `inherit` — everything said here so far. For work that only makes sense
+  against the case as it stands: reviewing what has just been written here,
+  continuing an investigation whose earlier findings are the thing being built
+  on.
+- `compact` — the same, without the tool traffic: what was decided, not how it
+  was found out. The usual choice for a wide fan-out, where branches need the
+  case and the plan but not the fifty reads that produced them.
+- `none` — nothing but its own instructions. The cheapest, and the honest one
+  when the assignment is self-contained: a lookup, one file summarised, a
+  command run elsewhere. Everything the branch needs must then be written out in
+  the instructions, paths included.
+
+When two modes seem possible, write the missing facts into the instructions and
+take the cheaper one. Instructions are exact; an inherited transcript is only
+approximately about the branch's job.
+
+## What comes back, and what stays
+
+Only the answer comes back, and it is prose. Everything else a branch does is
+real and outlasts it: branches share this workspace with you and with each
+other, so a file one of them writes is a file you can read after the join, and
+anything committed to memory is there for every later run.
+
+So decide, for each branch, which of the two carries its result:
+
+- **Prose, in the answer** — findings, a verdict, a short list, anything you are
+  about to reason with. If it is not in the answer it is gone.
+- **A file, and its path in the answer** — anything bulky, or meant to be used
+  rather than read: a generated document, extracted data, a patch, a long log.
+  Pasting it into the answer puts it in this conversation whether you need it
+  there or not.
+
+Say which you want in the branch's own instructions, and be exact:
+
+> Read `/workspace/docs/api/*.md` and find every endpoint still documenting the
+> v1 auth header. Write them to `/workspace/reports/v1-auth.md`, one line each
+> as `path — section — the quoted line`. Change nothing else. Return the path,
+> how many you found, and the two you are least sure about.
+
+Give every branch a path of its own. Two branches writing one file is a lost
+write that nothing reports — the join reads the same either way. The same holds
+for anything else they could contend over: one branch installing while another
+builds, two branches reformatting the same tree.
+
+## When a branch comes back wrong
+
+Each branch reports under its own name, with its status, and a failed one says
+why. What the final answer is remains your decision, not the join's.
+
+A branch rarely fails at random; the usual cause is an assignment missing
+something it could not ask for. Re-running the same instructions gets the same
+answer. Fix them and fork again, or do that piece here.

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

@@ -1,9 +1,18 @@
+---
+requires: [memory]
+---
+
 # 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.
+the project rather than with the session, and shared with every other agent that
+can see it. It is reached **only** through the `memory_*` tools - `memory_search`
+to find, `memory_load` to read.
+
+Not every agent may write to it. Read what follows against the tools you
+actually have: if `memory_commit` is not among them, everything under
+[Updating it](#updating-it) is not yours to do, and if `memory_forget` is not
+among them, neither is [Forgetting](#forgetting).
 
 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 -
@@ -51,7 +60,7 @@ runs past a line or two, it is content, and content goes in the file.
 | `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                                                 |
+| `preference` | a standing instruction from the user, or what they told you about themselves         |
 
 | Relation     | Reads as                                            |
 | ------------ | --------------------------------------------------- |
@@ -93,6 +102,30 @@ its own source.
 160 characters. `memory_load` is what reads a node whole, by id - load anything
 you are going to rely on.
 
+### The shape of a recollection
+
+A recollection arrives in a `<memory-recollection>` block, and it is a subgraph
+rather than a ranked list - the links are as much of the answer as the nodes. It
+is an outline, and the indentation is the graph.
+
+A line at the left margin reads `score kind id` and is something the search
+matched; a root the walk reached rather than matched carries `--` where the
+score would be. A line indented under it reads `<arrow>relation kind id` and is
+a neighbour: `→produced` means the line above produced this one, `←informed`
+means this one informed the line above. A neighbour the search matched in its
+own right carries its score too, after the arrow.
+
+Under each header, indented further, is that node's text. A `file` node carries
+one line more, above the text: the path under `/memory` to open or run, its
+size, and how often it has been read.
+
+A line beginning `+` is a link to an id already shown above, for an edge the
+outline could not nest. It never points forward, so resolving one only ever
+means looking back up the block.
+
+Text is clipped at 160 characters - copy an id into `memory_load` to read a node
+whole. `memory_search` finds ids; it does not return contents.
+
 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.
 
@@ -121,6 +154,19 @@ 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.
 
+Four moments are each worth one search:
+
+| At                                       | Search for                                                             |
+| ---------------------------------------- | ---------------------------------------------------------------------- |
+| a request arriving                       | the request itself, before the first step is planned                   |
+| arriving by handoff, or as a fork branch | the brief you were handed - it is new to you, not to the project       |
+| the point where real work would start    | the question that work would answer, whenever it is more than one call |
+| a dead end mid-run                       | what you now know you are missing, in the words you would ask it in    |
+
+Search the QUESTION, not the turn. Asking the same question again in different
+words is a round trip for an answer you already have; search again when what
+you need to know changes, not when the step does.
+
 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
@@ -166,10 +212,46 @@ 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:
+### When to commit
+
+That test says what is worth keeping. It does not say when to write it down, and
+work that is never written down cost what it cost for nothing.
+
+Two things call for a commit while the run is still going:
+
+- **A search came back empty, or came back beside the point, and you went on to
+  work the answer out anyway.** That gap is the next run's gap too, and you are
+  the only one in a position to close it. It is the usual reason a memory stays
+  useless: every run pays for the same answer, no run writes it down.
+- **Something cost more than a `memory_load` will** - several reads, a fan-out,
+  a build, a long command, a delegated lookup - or produced an artifact that
+  works: a script, a query, a request body, the invocation that finally ran.
+
+And three moments must not pass without one:
+
+| Before                                 | Because                                                           |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| returning your final answer            | the turn ends there, and nothing is written after it              |
+| handing off to another agent           | control moves and does not come back - what you know goes with it |
+| returning to the agent that forked you | only your answer returns; your transcript is dropped at the join  |
+
+Commit a piece of work when it is finished rather than saving all of it for one
+call at the end: a run that is interrupted, or that runs out of room, loses
+whatever was being held back. That is not licence to split one subgraph across
+calls - refs resolve only within a single `memory_commit`, so whatever links
+together is still committed together.
+
+### How to write 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.
+for it, or a fact with nothing that acts on it, is a memory nobody can use. Refs
+resolve only within a single `memory_commit`, so a subgraph split across calls
+arrives without its links.
+
+**Do not re-commit what a search already returned.** A node that says what one
+already in memory says is folded into it, and its existing id comes back under
+your ref - so the links you asked for still land, on the memory that was already
+there.
 
 **Say where the content came from.** This is what lets an incomplete
 recollection be continued instead of believed:
@@ -266,8 +348,8 @@ 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.
+is. Keep credentials out of the store, along with any personal data the specimen
+did not need: 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
@@ -276,3 +358,33 @@ 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.
+
+### Preferences
+
+A `preference` is a standing instruction from the user, and it is not recalled
+like everything else: every preference you can see is rendered into a
+`<memory-preferences>` block at the start of every later run, each with its id.
+They apply unless that run's request contradicts them.
+
+So commit one only when the user's own words generalise - "always", "from now
+on", "I prefer", "never". A single request being fulfilled is not a standing
+instruction, and one committed by mistake is in every future prompt until
+something supersedes it.
+
+What the user says about THEMSELVES belongs here too, and for the same reason: a
+later run that has to ask again has already lost what the block is for. Their
+name and how they want to be addressed, the role they work in, the timezone
+their dates are in, which of several accounts, environments or repositories is
+theirs, the language or the units they want answers in. Commit what they stated,
+in their own terms - never what you inferred from how they happened to phrase a
+request, and never a credential or a secret, which is not a preference however
+it was offered.
+
+To change one, commit the replacement and link it to the id shown in that block
+with `SUPERSEDES`.
+
+### Forgetting
+
+Forget only what is wrong and has no successor. A superseded memory is already
+hidden from recall and should stay for the history, so `memory_forget` is for
+what should never have been written, not for what has been replaced.