geneseed 3.3.0 → 3.5.0

package/src/skills/research.md

@@ -11,7 +11,10 @@ stop and report it ({{LAW}} V); never substitute recall for verified research.
 
 ## Procedure
 1. State the question and what a complete answer must contain. Break a broad question
-   into specific sub-questions.
+   into specific sub-questions. Where the host runs subagents, hand the sub-questions
+   to the [researcher {{AGENT}}](../{{DIR_AGENTS}}/researcher.md) — it runs steps 2–5
+   in its own context and returns only the sourced findings ({{DOCTRINE}} process 3);
+   otherwise carry on here.
 2. Search the web — use the host's web-search tool or a connected search provider
    ({{DOCTRINE}} ops 1). Query from several angles; one search is not research,
    and one empty result is not absence ({{LAW}} III). If the host
@@ -30,15 +33,4 @@ stop and report it ({{LAW}} V); never substitute recall for verified research.
 - The question is answered, every material claim is traceable to a cited,
   cross-checked source, and remaining uncertainties are flagged explicitly.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/review-response.md

@@ -22,15 +22,4 @@ are about to act on it.
 - Every comment has a reasoned response and either an applied change or a justified
   decline, and the resulting changes are verified.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/roast-me.md

@@ -14,15 +14,4 @@
 ## Done when
 - Findings are severity-ranked, every one carries a fix, and the highest-impact change is named.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/rule.md

@@ -86,15 +86,4 @@ adoption.
   {{LAWS}}, consented to explicitly, with any promoted source memory archived. The
   {{ONTOLOGY}}, {{LAWS}} and {{DOCTRINES}} files are untouched either way.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/security-audit.md

@@ -0,0 +1,51 @@
+# {{SKILL}}: security-audit
+
+> {{DESC_SECURITY_AUDIT}}
+
+**Trigger:** a change touches the security surface — authentication, authorisation,
+session or token handling, input from outside the trust boundary, file or shell
+access, cryptography, secrets, a new dependency, a network-facing endpoint — or the
+user asks for a "security review", "threat model", or "is this safe". The
+[geneseed-code-review {{SKILL}}](geneseed-code-review.md) reviews a diff for
+correctness first; this one asks a different question of the same diff: *how would
+this be attacked, and what does it leak*. Run both before shipping anything on the
+surface.
+
+## Procedure
+1. **Draw the surface.** From the diff and the code it lands in, name the trust
+   boundaries the change crosses (user input, another service, the filesystem, a
+   subprocess, the network), what an attacker controls on each, and the assets behind
+   them (data, credentials, the host). No boundary crossed → say so, verdict *not on
+   the surface*, stop.
+2. **Dispatch the [security {{AGENT}}](../{{DIR_AGENTS}}/security.md)** with the surface
+   from step 1 and the diff — read-only, in its own context so the main one stays
+   clean ({{DOCTRINE}} process 3). It runs the passes below; for a small change you may
+   run them yourself.
+3. **Pass 1 — the classic classes**, each checked against the actual code, not
+   assumed: injection (SQL, shell, path, template), broken auth or missing authz on
+   a new route, unsafe deserialisation, SSRF, insecure defaults, missing rate or size
+   limits, error messages that leak internals. Verify by reading the handling at the
+   boundary and, where a test can exercise it, by running one ({{LAW}} III).
+4. **Pass 2 — secrets and data.** Nothing sensitive in code, config, logs, fixtures,
+   or the commit itself ({{LAW}} I); PII handled and logged to the project's policy;
+   tokens scoped and expiring. Grep the diff for key-shaped strings, and check what the
+   new code *logs*.
+5. **Pass 3 — the supply chain.** A new or bumped dependency: who publishes it, how
+   maintained, what it pulls in transitively, any advisory against the pinned version
+   (the [deps-audit {{SKILL}}](deps-audit.md) carries the tooling). A destructive
+   capability exposed to an agent or a tool: its guard is enforced server-side, at the
+   boundary the call crosses, never left to the caller's judgement ({{DOCTRINE}} rigor 5).
+6. **Report, don't fix.** Each finding as `file:line — attack — impact — fix`, ranked
+   critical → high → medium → note, with the evidence that made it a finding. Then the
+   verdict — **ship / fix-then-ship / block** — and, for anything above medium, the
+   test that would pin the fix. Applying fixes is a [develop {{SKILL}}](develop.md)
+   task on its own commit ({{LAW}} II); a review that quietly edits the code it judges
+   has stopped being a review.
+
+## Done when
+- The trust boundaries the change crosses are named, each class was checked against
+  the real code with evidence, no secret or unguarded destructive path rides along,
+  and a ranked findings list ends in a ship / fix-then-ship / block verdict — with no
+  code changed by the review itself.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/ship.md

@@ -35,15 +35,4 @@ request or merge the branch.
 - The PR is open (or the branch is merged) with a body stating what / why / how it
   was tested, and nothing unrelated rides along.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/skill-forge.md

@@ -0,0 +1,59 @@
+# {{SKILL}}: skill-forge
+
+> {{DESC_SKILL_FORGE}}
+
+**Trigger:** a task has repeated and no {{SKILL}} covers it; a {{SKILL}}'s
+self-improvement loop produced an edit worth making; the user says "make this a
+skill", "write a skill for…", "fix the trigger of…"; or two {{SKILLS}} keep
+disambiguating against each other and should merge. Meta by nature: it edits the
+apparatus, so every step ends in the user's assent ({{LAW}} II, {{LAW}} IV).
+
+## Procedure
+1. **Reuse before authoring** ({{DOCTRINE}} craft 1, craft 4). Read the catalogue — the
+   host's skill list, or AGENT.md §4 — and the nearest existing {{SKILL}} in full. If
+   its domain already covers the need, the change is an *edit* to that file (a step,
+   a trigger phrase, a done-when), not a new file. Name the skill by its domain, not
+   the situation that prompted it.
+2. **Write the trigger first, then the procedure.** Start from
+   `{{DIR_SKILLS}}/_template.md`. The purpose line says *what*; the **Trigger** line
+   says *when*, in the words a user would actually say and the situations the model
+   would actually meet — the emitted `description:` is purpose + trigger, and it is
+   the only text the host matches a task against. Then the numbered procedure (each
+   step an action with a verification), and a **Done when** that a stranger could
+   check. Keep it to one coherent domain; a "Requires:" line only for a hard external
+   prerequisite. When only the user should ever open it (a teaching drill, a tool
+   gated on an environment the model cannot see), put the `invocation: user` HTML
+   comment on the line after the purpose blockquote — the template shows it. Never
+   quote that marker inside another skill's body: the emit matches it anywhere in the
+   text, and the quoting skill silently drops out of the model's catalogue.
+   A name the host already owns as a built-in command (Claude Code ships
+   `security-review`, `code-review`, `simplify`, `init`) is shadowed — pick another.
+3. **Test the trigger against its neighbours.** For three real asks the skill should
+   catch and two it should not, decide from the descriptions alone which skill fires.
+   A wrong pick is a trigger to sharpen — or a sign two skills should be one. A trigger
+   that needs a "not this, use that" clause to be safe is a trigger with a fuzzy edge;
+   fix the edge rather than adding the clause.
+4. **Register it where the host expects.** In an *installed* harness: the file under
+   `{{DIR_SKILLS}}/`, one row in AGENT.md §4's table, then `geneseed doctor` — it fails
+   if the table and the files disagree. In the *Geneseed source repo* the cost is the
+   full satellite set (`docs/extending.md` §3): the file, the §4 row, `DESC_<NAME>` in
+   every theme, `SKILL_CLASS`, a `registry.json` row, the README enumeration, then
+   `doctor --all` and the suites. A skill that bundles a script or several files is a
+   folder skill (`<name>/SKILL.md` + `VENDOR.md`), listed in `VENDORED_SKILL_DIRS`.
+5. **Merge or retire honestly.** When two skills fold into one: keep the best steps of
+   each, rewrite the exit so the survivor routes to what the retired one led to, and
+   remove the retired file and *every* reference to it (table row, sibling links, theme
+   tokens, registry, README) — a dangling link is a build failure, a dangling trigger
+   phrase is a silent miss. Retirement is deletion; get consent ({{LAW}} IV).
+6. **Verify by rendering.** Build or re-emit, open the emitted `SKILL.md`, read the
+   frontmatter description as the host will, and confirm the body carries no
+   unresolved token or dead link (`doctor`, or `geneseed-build --validate-only`).
+   Show the user the diff and the emitted description before it lands ({{LAW}} II).
+
+## Done when
+- The need is met by an edit to an existing {{SKILL}} or by one new file in its own
+  domain; the emitted description names both purpose and trigger and wins its five
+  test asks against the neighbours; every satellite the host or the repo demands is in
+  place, `doctor` is green, and the user saw and accepted the change.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/teach.md

@@ -0,0 +1,50 @@
+# {{SKILL}}: teach
+
+> {{DESC_TEACH}}
+
+<!-- invocation: user -->
+
+**Trigger:** the user wants to *learn* something and asks you to teach — "teach me X",
+"get me up to speed on X", "this is confusing, break it down", "explain this passage",
+"how do I get to X in N days". Three shapes, picked from the ask: a **crash course**
+(from zero to functional, fast), a **decode** (confusing material handed over, make it
+click), or a **path** (a specific result by a deadline, day by day). To *test* what the
+user already knows rather than teach it, use the [quiz {{SKILL}}](quiz.md); to gather
+facts from the web first, [research](research.md); to convert a PDF or web page into
+readable form, [ingest](ingest.md).
+
+## Procedure
+1. Pin the footing before teaching anything: what the user wants to be able to *do*
+   afterwards, how much time they have, and what they already know. Ask once if any of
+   the three is missing, then proceed — do not plan around "learn X in general".
+2. Pick the shape and run it:
+   - **Crash course** — act as a teacher who has only this one session and will never
+     see them again; the sole objective is *functional* before time runs out. Name
+     three things explicitly: **what to learn first**, **what to ignore completely**
+     (for now), and **the single exercise that, done once, puts them ahead of most
+     people who have studied this for months**. No theory without immediate use, no
+     bare lists. Have them do the exercise — or set it up so they can — rather than
+     read about it.
+   - **Decode** — read what they are stuck on and, before explaining anything, find the
+     one keystone sentence that makes the rest fall into place. Explain only that
+     sentence first, with an everyday analogy and no technical terms; confirm it
+     landed; then let the rest follow from it instead of re-explaining every line.
+   - **Path** — build a day-by-day route to the stated result. Each day carries exactly
+     three things: one task that fits the stated time budget (default 45 minutes), a
+     concrete criterion so they can tell they did it right, and one explicit
+     *what-not-to-do* that day. Trace the whole path against the goal; if finishing
+     every day would not deliver the result, rebuild it until it does.
+3. Check it took: ask three questions only someone who understood could answer (a
+   crash course or decode), or walk the first day together (a path). A miss goes back
+   to the analogy or the exercise — re-anchor, don't hand over the answer.
+4. Close by naming what to practise next and the gap most likely to trip them, so the
+   learning continues without you; offer the [quiz {{SKILL}}](quiz.md) for when they
+   want it tested.
+
+## Done when
+- The user is functional (crash course), has the keystone idea in plain terms and
+  passed the three questions (decode), or holds a dated path whose every day has a
+  timed task, a criterion and a what-not-to-do (path) — and knows what to practise
+  next.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/tickets.md

@@ -30,15 +30,4 @@ tracker issues that fresh sessions can pick up independently.
 - Every slice of the spec is a published ticket with explicit blockers, each
   sized for one session, and at least one unblocked ticket exists to start on.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/wayfinder.md

@@ -35,15 +35,4 @@ the destination can be named but the route to it cannot; the user says
 - Every decision ticket is closed, the map indexes them all, and someone could
   pursue the destination without a single further decision.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/wiki.md

@@ -54,15 +54,4 @@ truth.
 - anything written follows the wiki's `conventions`, links into the graph,
   sits in the right folder (or the `inbox`), and touches nothing `protected`.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/workflow.md

@@ -2,37 +2,93 @@
 
 > {{DESC_WORKFLOW}}
 
-**Trigger:** a task that benefits from *deterministic* multi-agent orchestration — fan-out across independent units, a staged find→verify pipeline, or a loop that accumulates to a target — **and** the host provides the `workflow` tool (OpenCode). When the host has no such tool, use [parallel-agents](parallel-agents.md) or [council](council.md) instead — those are *model-driven*; this {{SKILL}} is *code-driven*.
+**Trigger:** a task that benefits from *deterministic* multi-agent orchestration — a
+fan-out across independent units, a staged find→verify pipeline, a fresh-context
+handoff between phases, or a loop that accumulates to a target — **and** the host
+exposes a workflow tool. When it does not, use [parallel-agents](parallel-agents.md)
+or [council](council.md) instead — those are *model-driven*; this {{SKILL}} is
+*code-driven*.
 
 ## What it is
 
-A `workflow` is a saved script that orchestrates subagents in **code**, not prose. The script — not the model — decides what fans out, what runs in sequence, and what verifies. The host runs it and hands you back the distilled result. Use it when the control flow should be exact and repeatable rather than re-improvised each time.
+A workflow is a script that orchestrates subagents in **code**, not prose. The
+script — not the model — decides what fans out, what runs in sequence, and what
+verifies; the host runs it and hands back a distilled result. Use it when the control
+flow should be exact and repeatable rather than re-improvised each time, and when the
+work is worth a crew: a one-file tweak or a question never is.
 
-Saved workflows live in the host's workflows directory — on OpenCode that is `.opencode/workflows/` in the repo, or `workflows/` under the global config (see the adapter README) — and you run one **by name**, you do not author one inline. To add a new workflow, copy an existing script and register it there.
+## The hosts
+
+| Host | Tool | Scripts | Opt-in |
+|---|---|---|---|
+| OpenCode | `workflow` (the `geneseed-workflow` plugin) | **saved only** — `<name>.js` in `.opencode/workflows/` per repo or `<config>/workflows/` global (`GENESEED_WORKFLOWS_DIR` overrides); nothing inline is eval'd | none — call it when the shape fits |
+| Claude Code | `Workflow` (native) | a saved `.claude/workflows/<name>` by `name`, **or** an inline `script` you author | **required** — the tool refuses unless the user opted in for this task ("use a workflow", "ultracode", a skill that says so) |
+| Bob, Copilot | none | — | fall back to [parallel-agents](parallel-agents.md) / [council](council.md) |
+| any, under Orca | Orca orchestration (`orca skills get orchestration`) | tasks, not scripts — each task spec names its target, change, ownership and acceptance | the user asked to supervise or coordinate workers |
+
+Both runtimes speak the same primitives — `agent()`, `parallel()`, `pipeline()`,
+`phase()`, `args` — and every script opens with a literal `export const meta = { name,
+description, phases }`. The four shipped scripts are OpenCode-saved today; on Claude
+Code the same shapes are authored inline (the host's `workflow-authoring` reference
+carries the script API — load it before writing one).
+
+## The shipped shapes
+
+- **review** — sweep a change across dimensions, then adversarially verify each
+  finding before reporting (the canonical find→verify pipeline: a dimension's findings
+  verify as soon as that dimension returns, no barrier).
+- **research-plan-implement** — three clean phases, each in its own child context,
+  carrying only the distilled output of the prior phase.
+- **council** — the [council](council.md) debate on rails: seat the stance {{AGENTS}},
+  gather positions in parallel, chair synthesises, dissent preserved.
+- **dispatch** — decompose a multi-domain goal, route each subtask to its owning
+  capability {{AGENT}}, converge (model-driven fallback: [parallel-agents](parallel-agents.md)).
 
 ## Procedure
-1. Confirm the host exposes the `workflow` tool. If not, fall back to [parallel-agents](parallel-agents.md) / [council](council.md) and stop here.
-2. Pick the saved workflow that fits the shape of the work — call `workflow` with no `name`, or an unknown one, to list what is available:
-   - **review** — sweep a change across dimensions, then adversarially verify each finding before reporting (the canonical find→verify pipeline).
-   - **research-plan-implement** — three clean phases with fresh-context handoffs between them.
-   - **council** — the [council](council.md) debate as deterministic code: seat the stance {{AGENTS}}, gather positions in parallel, synthesise a verdict.
-   - **dispatch** — decompose a multi-domain goal, route each subtask to its owning capability {{AGENT}}, converge the results (the live-orchestrator shape; model-driven fallback: [parallel-agents](parallel-agents.md)).
-3. Run it: `workflow({ name, args })`. Pass the task-specific inputs (target paths, the motion, the question) as `args` — the script reads them.
-4. Read the returned summary. The full structured result and a phase-by-phase trace are written to the run's progress file; point the user at it if they want the detail.
-5. Act on the result yourself — the workflow gathers and verifies, but committing, pushing, or merging stays with you ({{DOCTRINE}} process 5).
+1. **Confirm the host and the opt-in.** OpenCode: the `workflow` tool is present. Claude
+   Code: the tool is present *and* the user opted in — if the shape plainly warrants a
+   workflow but they have not, describe it in two lines with its rough cost (how many
+   agents) and ask; never call the tool on your own judgement. No tool at all → fall
+   back and stop here.
+2. **Confirm the task is crew-sized** and the shape is one of the four above (or a
+   plain variation). Sequential work with shared state is a [plan](plan.md); a
+   dev↔test loop in an isolated tree is a [pipeline](pipeline.md), which itself runs on
+   a workflow where one exists.
+3. **Pick saved over inline.** List what is available first — OpenCode: call `workflow`
+   with no `name`; Claude Code: read `.claude/workflows/`. A saved script has been run
+   before; an inline one has not. Author inline only when no saved shape fits, keep it
+   to the primitives, and hold to the host's size guideline unless the user asked for
+   more.
+4. **Give every editing agent a write set, and isolate parallel editors** ({{DOCTRINE}}
+   process 8). Name in each editing `agent()` prompt the files it may change and have it
+   return the files it did change; overlapping sets run in sequence, not in one
+   `parallel()`. Pass `isolation: 'worktree'` to each agent that edits in parallel — both
+   runtimes take it; read-only agents need none. After the fan-out, compare the changed
+   files in plain script code (OpenCode hands them to you as `overlaps()`) — a file two
+   agents touched goes to one merge agent, never to whoever wrote last.
+5. **Pass the task as `args`, never baked in** — target paths, the motion, the question,
+   any timestamp. Scripts stay deterministic: no wall clock, no randomness, nothing
+   read from the environment that the next run would see differently, so a run is a
+   pure function of (script, args, child replies) and can be replayed.
+6. **Run it and wait for the result, not the transcript.** The run is asynchronous on
+   Claude Code (a task notification arrives; `/workflows` watches it live) and
+   synchronous on OpenCode. Read the returned summary; the full structured result and
+   the phase-by-phase trace are in the run's progress file — point the user there for
+   detail, do not paste it. Never fabricate a result for a run that has not returned.
+7. **On failure, resume — don't rerun.** A script that died mid-way keeps its completed
+   `agent()` results; fix the script or the args and resume from the run id where the
+   host supports it, so finished stages are not paid twice. A stage that keeps failing
+   is a finding about the task, not a reason to loop.
+8. **Exit — carry the conclusion yourself.** The workflow gathers and verifies;
+   committing, pushing, merging, or opening anything outward stays with you
+   ({{DOCTRINE}} process 5, {{LAW}} IV). State what the run concluded, what you are
+   doing with it, and where the trace lives.
 
 ## Done when
-- The right saved workflow ran to completion, its result was read, and you have carried its conclusion forward — or, where no `workflow` tool exists, the equivalent model-driven {{SKILL}} was used instead.
-
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+- The right shape ran to completion on the host's tool (with the user's opt-in where
+  the host demands one), its summary was read and its trace is locatable, a failed run
+  was resumed rather than restarted, and you — not the script — have carried its
+  conclusion into the next {{SKILL}} or the commit gate. Or: no tool existed, and the
+  model-driven equivalent ran instead.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/worktree.md

@@ -0,0 +1,52 @@
+# {{SKILL}}: worktree
+
+> {{DESC_WORKTREE}}
+
+**Trigger:** work must not share a working tree with what is already in flight — a
+[pipeline](pipeline.md) crew needs its own tree, a second task starts while the first
+is uncommitted, another agent or session is editing this checkout, a risky migration
+or rewrite needs a disposable copy, or the user says "worktree", "isolate this",
+"don't touch my checkout". Also the first thing to reach for when `git status` shows
+changes you did not make.
+
+## Procedure
+1. **Look before you branch** ({{LAW}} III). `git status` and `git worktree list`
+   first. Uncommitted changes you did not author mean someone else owns this tree —
+   never `checkout -b` from it (that moves *their* HEAD onto your branch) and never
+   stash or revert it. Note the branch they are on; you will not touch it.
+2. **Create the tree beside the repo, from a clean base:**
+   ```
+   git worktree add -b <type>/<slug> ../<repo>-<slug> <base>
+   ```
+   `<base>` is the integration branch (`main`, or `origin/main` after a `git fetch`),
+   never the dirty tree's HEAD. One worktree per task; name the directory after the
+   branch so `git worktree list` reads as a task list.
+3. **Make it runnable.** A worktree shares the repository, not the untracked files:
+   install dependencies (`npm ci`, the project's equivalent) or link the ones that are
+   large and pure; copy no `.env` — secrets are the user's to place ({{LAW}} I). Run
+   the project's checks once in the new tree and read the output before changing
+   anything, so a later red is yours.
+4. **Work only in the worktree.** Every edit, test, commit and `doctor`/lint run
+   happens under its path — use absolute paths in tools whose cwd resets. The
+   original checkout stays as found. Host hooks or shims that write machine-wide
+   state (a global config, a hook shim) run from the worktree only when they resolve
+   the repo through it; verify with the tool's own status command rather than assume.
+5. **Integrate through the normal gate** — commit via the [commit {{SKILL}}](commit.md),
+   ship via [ship](ship.md). A worktree earns no exemption from per-commit and
+   per-push consent ({{DOCTRINE}} process 5). Expect conflicts with a sibling tree that
+   touched the same files; resolve them on the branch, not in the other tree.
+6. **Clean up when the branch is merged or abandoned** — with consent, since removal
+   is deletion ({{LAW}} IV):
+   ```
+   git worktree remove ../<repo>-<slug>
+   git branch -d <type>/<slug>
+   ```
+   `git worktree prune` after a directory was deleted by hand. Leave nothing listed
+   that no task owns.
+
+## Done when
+- The task ran to its commit or PR entirely inside its own tree from a clean base,
+  the original checkout is byte-for-byte as it was found, and the worktree is either
+  still listed with a live task or removed with its branch.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/themes/_TEMPLATE.json

@@ -7,7 +7,6 @@
   "EPI_LAWS": "<epigraph above the Laws section, themed>",
   "EPI_DOCTRINES": "<epigraph above the Doctrines section, themed>",
   "PACT": "<noun for the mutual user–agent contract, e.g. Pact>",
-  "EPI_PACT": "<epigraph above the Pact section, themed>",
   "EPI_AGENTS": "<epigraph above the Agents section, themed>",
   "EPI_SKILLS": "<epigraph above the Skills section, themed>",
   "EPI_MEMORY": "<epigraph above the Memory section, themed>",
@@ -23,6 +22,7 @@
   "DESC_DOCS": "<one-line description: writes user-facing docs after code lands>",
   "DESC_SECURITY": "<one-line description: audits changes touching the security surface>",
   "DESC_EXPLORER": "<one-line description: reads/searches widely, returns only distilled findings>",
+  "DESC_RESEARCHER": "<one-line description: searches and fetches the open web, cross-checks every claim, returns sourced findings>",
   "DESC_ADVOCATE": "<council seat: argues the strongest case FOR the proposal>",
   "DESC_SKEPTIC": "<council seat: devil's advocate — failure modes and hidden assumptions>",
   "DESC_PRAGMATIST": "<council seat: weighs cost, effort, complexity vs payoff>",
@@ -42,7 +42,6 @@
   "DESC_COMMIT": "<one-line description: stage the right paths and write a focused commit>",
   "DESC_CODE_REVIEW": "<one-line description: review a diff/PR — correctness first, quality second>",
   "DESC_BRAINSTORM": "<one-line description: turn a raw idea into an approved design before code>",
-  "DESC_CLARIFY": "<one-line description: interview the user to pin goal, scope, success criteria>",
   "DESC_CODEBASE_DESIGN": "<one-line description: design deep modules behind small interfaces at deliberate seams>",
   "DESC_DOMAIN_MODELING": "<one-line description: maintain the domain glossary and record decisions as ADRs>",
   "DESC_WAYFINDER": "<one-line description: map an oversized effort as decision tickets and resolve them until the route is clear>",
@@ -57,19 +56,20 @@
   "DESC_PONYTAIL": "<one-line description: force the laziest working solution — minimal, shortest path, stdlib/native before custom code; lite/full/ultra intensity>",
   "DESC_PARALLEL_AGENTS": "<one-line description: fan independent subtasks to concurrent subagents, then converge>",
   "DESC_PIPELINE": "<one-line description: spawn a small crew — analyst, developer, tester — to work a substantial task in isolation, merging only on mechanical proof (tests + lint green)>",
-  "DESC_TDD": "<one-line description: drive implementation with a failing test first>",
   "DESC_DEVELOP": "<one-line description: drive a code change through cover-and-verify — smallest change, tests written for it, affected suite green, committed slice by slice>",
+  "DESC_TEACH": "<one-line description: teach toward a result — crash course, decode confusing material, or a day-by-day path to a deadline>",
+  "DESC_QUIZ": "<one-line description: test what the user knows instead of explaining — drill, explain-it-back check, or mastery claim stress-tested>",
+  "DESC_SECURITY_AUDIT": "<one-line description: review a change for how it would be attacked and what it leaks, ending in ship / fix / block>",
+  "DESC_SKILL_FORGE": "<one-line description: author, sharpen, merge, or retire a skill — reuse first, trigger tested, every satellite registered>",
+  "DESC_WORKTREE": "<one-line description: isolate a task in its own git worktree from a clean base, integrate through the normal gate, remove when merged>",
+  "DESC_CI_FIX": "<one-line description: turn a red CI run green at the cause — read the log, reproduce under CI's conditions, fix, watch the re-run>",
+  "DESC_DEPS_AUDIT": "<one-line description: survey dependencies — outdated, vulnerable, abandoned, unused — into a risk-ordered upgrade plan, installing nothing>",
+  "DESC_CONSOLIDATE_MEMORY": "<one-line description: tend the memory set — verify facts against the live repo, merge, retire, promote, rebuild the index>",
   "DESC_HANDOFF": "<one-line description: snapshot task state so a fresh context can resume in one read>",
   "DESC_SHIP": "<one-line description: open a PR with a structured body, or finish and merge a branch>",
   "DESC_RELEASE": "<one-line description: cut a release — bump, changelog, tag, kept in sync>",
   "DESC_INGEST": "<one-line description: convert a PDF/Office/web doc into clean markdown before reading>",
   "DESC_RESEARCH": "<one-line description: answer from the open web, verifying each claim against independent sources>",
-  "DESC_LEARNING_PATH": "<one-line description: turn a goal+deadline into a day-by-day path — daily timed task, correctness criterion, what not to do>",
-  "DESC_GAP_DETECTOR": "<one-line description: stress-test a mastery claim with five simple-looking questions, blunt verdict on the gaps>",
-  "DESC_FEYNMAN": "<one-line description: explain-it-simply check, caught on jargon/skipped steps/over-simplification, readout of what isn't solid>",
-  "DESC_CRASH_COURSE": "<one-line description: go from zero to functional in a skill fast — what to learn first, what to ignore, the one exercise that puts you ahead>",
-  "DESC_DRILL": "<one-line description: turn shaky knowledge into reflex — real situations, questioned through your mistakes, answer withheld until you've tried>",
-  "DESC_DECODE": "<one-line description: make confusing material click — one keystone sentence, an everyday analogy, then a comprehension check>",
   "DESC_HERDR": "<one-line description: drive herdr from inside it — split panes, spawn agents, read panes>",
   "DESC_RULE": "<one-line description: ask whether the user wants a standing rule or a durable memory, then write the memory, or pressure-test the rule until it is generic and adopt it in user-rules.md>",
   "DESC_PROFILE": "<one-line description: interview the user and draft or refresh PROFILE.md — who they are, how they work, how they like answers pitched; identity only, rules go to user-rules.md>",
@@ -83,9 +83,9 @@
   "LEX_VI": "<themed title for Law VI (Data, Not Orders)>",
   "LEX_VII": "<themed title for Law VII (Least Privilege)>",
   "LEX_VIII": "<themed title for Law VIII (Cure the Cause)>",
-  "LEX_IX": "<themed title for Law IX (External Gate)>",
+  "LEX_IX": "<themed title for the retired Law IX (External Gate), ending in (retired)>",
   "LEX_X": "<themed title for Law X (Echo the Intent)>",
-  "LEX_XI": "<themed title for Law XI (Absence Is a Claim)>",
+  "LEX_XI": "<themed title for the retired Law XI (Absence Is a Claim), ending in (retired)>",
   "PACK_CRAFT": "<display name of the craft doctrine pack — how code is written>",
   "PACK_RIGOR": "<display name of the rigor doctrine pack — how work is proven>",
   "PACK_OPS": "<display name of the ops doctrine pack — how the machine is driven>",
@@ -96,6 +96,7 @@
   "DOC_CRAFT_4": "<themed title for craft doctrine 4 (Search Before Creating)>",
   "DOC_CRAFT_5": "<themed title for craft doctrine 5 (Respect Conventions)>",
   "DOC_CRAFT_6": "<themed title for craft doctrine 6 (Smallest Viable Diff)>",
+  "DOC_CRAFT_7": "<themed title for craft doctrine 7 (One Writer Per Value)>",
   "DOC_RIGOR_1": "<themed title for rigor doctrine 1 (Idempotent by Default)>",
   "DOC_RIGOR_2": "<themed title for rigor doctrine 2 (Honest Tests)>",
   "DOC_RIGOR_3": "<themed title for rigor doctrine 3 (Cover and Verify)>",
@@ -107,6 +108,7 @@
   "DOC_OPS_4": "<themed title for ops doctrine 4 (Complete the Teardown)>",
   "DOC_OPS_5": "<themed title for ops doctrine 5 (Record the Probe, Not the Snapshot)>",
   "DOC_OPS_6": "<themed title for ops doctrine 6 (Restart Is Not Reload)>",
+  "DOC_OPS_7": "<themed title for ops doctrine 7 (Serialize Against a Rationed Resource)>",
   "DOC_PROCESS_1": "<themed title for process doctrine 1 (Persist Insight)>",
   "DOC_PROCESS_2": "<themed title for process doctrine 2 (Plan Before Acting)>",
   "DOC_PROCESS_3": "<themed title for process doctrine 3 (Context Economy)>",
@@ -114,13 +116,14 @@
   "DOC_PROCESS_5": "<themed title for process doctrine 5 (Consent Before Push)>",
   "DOC_PROCESS_6": "<themed title for process doctrine 6 (Bound the Loop)>",
   "DOC_PROCESS_7": "<themed title for process doctrine 7 (Codes That Persist)>",
+  "DOC_PROCESS_8": "<themed title for process doctrine 8 (One Writer Per File)>",
   "INTRO_DOC": "<themed intro: this file is the entry point an AI agent reads in this repo>",
   "INTRO_AGENTS": "<themed intro to the Agents section — delegate focused work to a specialist>",
   "INTRO_SKILLS": "<themed intro to the Skills section — run the written procedure before improvising>",
   "INTRO_WORKSPACE": "<themed intro to the Workspace section — the install dir is shared>",
   "INTRO_SCRIPTS": "<themed intro to the Scripts section — everything above works on self-discipline alone>",
   "BANNER": "<multi-line ASCII banner shown at the top of AGENT.md; use \\n for line breaks>",
-  "ONTOLOGY": "<noun for the always-on worldview tier, e.g. Ontology — a bare noun with no leading article, since it is read inline mid-sentence>",
+  "ONTOLOGY": "<noun for the always-on worldview tier, e.g. Ethos — a bare noun with no leading article, since it is read inline mid-sentence>",
   "LAW": "<singular noun for a rule in this theme, e.g. Rule / Dictate / Law>",
   "LAWS": "<plural of LAW>",
   "DOCTRINE": "<SINGLE-WORD singular noun for one optional doctrine rule, e.g. Doctrine — a space in this value breaks the heading parser silently>",