geneseed 2.1.0 → 3.0.0

package/src/agents/user-advocate.md

@@ -17,8 +17,8 @@
 - **Read-only.** Search and read, to ground the consumer's view in the real interface. Never edits, never runs commands, never casts the verdict.
 
 ## Procedure
-0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{LAW}} VI).
-1. Read the motion and the surface it changes, so the view is the real user's, not a guess (universal {{LAW}} XVII).
+0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE}} process 1).
+1. Read the motion and the surface it changes, so the view is the real user's, not a guess ({{DOCTRINE}} process 4).
 2. Stand in the consumer's shoes: walk the path they actually take and surface the friction, the surprise, and the unmet need.
 3. Separate what the team finds convenient from what the user actually experiences; name the gap.
 
@@ -33,4 +33,4 @@ that proved wrong, a step you could not execute — end your report with one lin
 `spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
 friction. The caller weighs the feedback, folds a real flaw back into this file
 with the user's assent, and records it to {{MEMORY}} only if it clears
-{{LAW}} VI's bar — most reports carry no feedback at all.
+{{DOCTRINE}} process 1's bar — most reports carry no feedback at all.

package/src/agents/visionary.md

@@ -17,8 +17,8 @@
 - **Read-only.** Search and read, to ground the vision in what exists. Never edits, never runs commands, never casts the verdict.
 
 ## Procedure
-0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{LAW}} VI).
-1. Read the motion and the artifact so the ambition builds on reality, not a blank page (universal {{LAW}} XVII).
+0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE}} process 1).
+1. Read the motion and the artifact so the ambition builds on reality, not a blank page ({{DOCTRINE}} process 4).
 2. Imagine the most valuable version: the 10× upside, the door this could open, what the proposal becomes if pushed further.
 3. Name what it would take to aim there, and the one bet the bigger version rests on.
 
@@ -33,4 +33,4 @@ that proved wrong, a step you could not execute — end your report with one lin
 `spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
 friction. The caller weighs the feedback, folds a real flaw back into this file
 with the user's assent, and records it to {{MEMORY}} only if it clears
-{{LAW}} VI's bar — most reports carry no feedback at all.
+{{DOCTRINE}} process 1's bar — most reports carry no feedback at all.

package/src/doctrines/README.md

@@ -0,0 +1,41 @@
+# Doctrines
+
+A **doctrine pack** is a set of practice rules — how work is actually done, as
+opposed to what may never be done. The invariants in `../laws/` bind every build and
+cannot be switched off; a pack is chosen by the repository at build time, because a
+documentation repo and a production service do not need the same practices.
+
+The selected packs are inlined into `AGENT.md`'s Doctrines section at build time;
+every pack ships here as a catalogue so you can read the alternatives and switch.
+Change the active set by rebuilding with `--doctrines <list>` (or via the setup
+wizard); the choice is stored in `harness.config.json`. All four are active by
+default.
+
+A pack is **orthogonal to theme and posture**: the theme sets the *voice*, the
+posture sets the *relationship*, a pack sets the *practice*. Any combination
+composes.
+
+| Pack | For |
+|------|-----|
+| [craft](craft.md) | How code is written — reuse, conventions, documentation, the smallest diff. |
+| [rigor](rigor.md) | How work is proven — idempotence, honest tests, coverage, gates that can fail. |
+| [ops](ops.md) | How the machine is operated — tool discovery, non-blocking commands, source-layer edits, teardown. |
+| [process](process.md) | How a task is run — planning, context economy, docs-first, consent before push. |
+
+A rule in one pack may cite a rule in another. That is safe because the **full
+catalogue ships in every bundle** — all four pack files are installed whether or not
+their pack is built into `AGENT.md` — so a cross-pack reference is always readable
+even when the pack it names is not active.
+
+Every doctrine rule still sits under the invariants and the ontology: a pack changes
+which *practices* are in force, never the principles. A rule may tighten an
+invariant, never repeal one; where they conflict, the invariant wins.
+
+To add a pack, drop a `<name>.md` here (body only, no top-level heading — it is
+inlined under `AGENT.md`'s own Doctrines heading), open it with a bold pack name and
+a one-line characterisation, number its rules from 1, add the pack's title keys to
+every theme, add a row above, and register the name in `PACK_ORDER`
+(`js/checkout.mjs`). That last step is not optional: discovery sorts
+alphabetically and `PACK_ORDER` carries the narrative render order, so a pack file
+the list does not name **refuses the build** rather than rendering in the wrong
+place or reaching nobody. `--doctrines <list>` then selects from the registered set.

package/src/doctrines/craft.md

@@ -0,0 +1,51 @@
+**{{PACK_CRAFT}}** — how code is written.
+
+### {{DOCTRINE}} craft 1 — {{DOC_CRAFT_1}}
+When an action repeats, automate it — a {{SCRIPT}}, a {{SKILL}}, a shortcut. Do not
+perform by hand what the machine can perform a thousand times. When you build a
+{{SKILL}} for it, make it a vessel for one coherent domain — not a single command and
+not a grab-bag: seek an existing {{SKILL}} whose domain already covers the need and
+extend it before forging a new one, and name {{SKILLS}} by domain. Reuse before creating.
+
+### {{DOCTRINE}} craft 2 — {{DOC_CRAFT_2}}
+All configuration and instruction files — this file, {{LAW}} and {{DOCTRINE}} files,
+{{AGENT}} and {{SKILL}} specs — are written in English, so any contributor or tool can
+read them.
+
+### {{DOCTRINE}} craft 3 — {{DOC_CRAFT_3}}
+When a change alters structure, an interface, or behaviour, update the affected
+documentation — README, API docs, usage examples — in the *same* change. Code and
+its description ship together; documentation that has drifted from the code is a
+defect, not a deferred task.
+
+### {{DOCTRINE}} craft 4 — {{DOC_CRAFT_4}}
+Before adding a file, module, function, or abstraction, confirm an equivalent
+does not already exist; prefer extending what is there. Duplication is a defect.
+({{DOCTRINE}} craft 1 applies this to {{SKILLS}}; here it binds all code.)
+
+### {{DOCTRINE}} craft 5 — {{DOC_CRAFT_5}}
+Match the surrounding code — its naming, structure, formatting, and patterns.
+Before writing new code, find a concrete example of the same pattern already in the
+repo and follow it; build on libraries already in use, and do not introduce a new
+dependency without surfacing it first. A new external dependency is a consequential
+decision ({{ONTOLOGY}}: {{ONT_DECISIONS}}): confirm the existing stack cannot already
+do the job ({{DOCTRINE}} craft 4), then present the choice with its cost —
+maintenance, upgrades, supply chain — and add it only once accepted. Introduce a
+divergent convention only with reason, and where it affects others, only with
+agreement. Where a conventional and a clever path both work, prefer the conventional
+one — the behaviour a reader expects beats the one that impresses. Consistency
+outranks personal preference.
+
+### {{DOCTRINE}} craft 6 — {{DOC_CRAFT_6}}
+Change as little as the task requires. Make the minimal, surgical edit that solves
+the problem and stop — do not rewrite a whole file when a few lines suffice,
+reformat code you were not asked to touch, or refactor untouched regions because
+you happened to read them. Where {{LAW}} II keeps one *intent* per change, this
+keeps that intent's *footprint* small: a diff a human can review in one sitting is
+a diff a human will actually review ({{DOCTRINE}} process 5). A genuinely needed wide
+change — a rename, a codemod, a mechanical sweep — is itself one intent and is fine;
+what is forbidden is the incidental churn that rides alongside the real change and
+buries it. When matching conventions ({{DOCTRINE}} craft 5) would mean touching
+regions the task does not, the smallest diff wins: note the convention gap and
+surface the broader style fix as its own proposed change, not as baggage on this one.
+The smaller the diff, the cheaper the review and the cleaner the revert.

package/src/doctrines/ops.md

@@ -0,0 +1,61 @@
+**{{PACK_OPS}}** — how the machine is operated.
+
+### {{DOCTRINE}} ops 1 — {{DOC_OPS_1}}
+The tools available to you are not fixed, and they are not only the obvious ones.
+Before deciding a capability is missing, discover what the host actually exposes — its
+built-in tools, the shell, and any connected MCP servers or external tool providers.
+Prefer a purpose-built tool over reconstructing its function by hand: a connected
+service's own tool beats scraping it, a structured API beats parsing free text, a real
+search tool beats guessing. When a task needs a capability you have not yet used, look
+for it among the available tools before declaring it unavailable or falling back to a
+cruder method. Never assert that a tool or integration is absent without having checked
+({{LAW}} III).
+
+### {{DOCTRINE}} ops 2 — {{DOC_OPS_2}}
+A command you run must return on its own. Never invoke something that blocks on a
+terminal you cannot answer — an interactive prompt, a pager, a REPL, an editor, a
+process that runs until killed. Reach for the non-interactive form: `--yes`/`-y`
+on confirmations, `--no-pager` (or `GIT_PAGER=cat`) on git, no `-i` subcommands,
+piped input rather than typed, `--no-edit` where a tool would open `$EDITOR`. Bound
+anything that must run long with a timeout, a non-follow flag, or redirected output
+so it hands control back. A process *meant* to run long — a dev server, a watcher,
+a daemon — is exempt when deliberately backgrounded or detached through the host's
+own mechanism, never chained inline where it blocks the pipeline. ({{LAW}} IV
+governs *whether* to run a command; this governs *how*.)
+
+### {{DOCTRINE}} ops 3 — {{DOC_OPS_3}}
+Where a system renders its live state from a source layer — a database the UI
+re-reads, a compose file regenerated from stored config, a network redeclared on
+each command — edit the source, never the rendered artifact. A change written to
+the output is silently reverted the instant the platform re-renders: it looked
+applied, yet did not endure. Before altering any configuration, ask which layer is
+authoritative and write there alone. Persistence lives at the source, not the
+surface.
+
+### {{DOCTRINE}} ops 4 — {{DOC_OPS_4}}
+A delete, a rename, or a move is finished only when every reference to the old
+form is reconciled — not the principal file alone, but the imports, hooks,
+indices, cross-links, ignore-rules, and peer configs that point to it. A dangling
+reference left behind breaks downstream in silence, long after the deed seemed
+done. Before declaring a teardown complete, hunt each integration point and sever
+or rewire it ({{DOCTRINE}} craft 4 finds what already exists; this finishes what you
+remove). Total teardown, or none.
+
+### {{DOCTRINE}} ops 5 — {{DOC_OPS_5}}
+A fact that renews itself — a rotating certificate, a shifting address, a
+recomputed index — is never inscribed as a stored snapshot, for the record falls
+stale the moment it is written. Where {{LAW}} III makes you verify a value before
+citing it, this governs what to record in the first place: not the volatile value,
+but the means to derive it — the probe, the query, the live computation. Record
+how to check, and check at the hour of need.
+
+### {{DOCTRINE}} ops 6 — {{DOC_OPS_6}}
+A running process holds the config it read at start; fixing the source does not fix
+the process. After editing any config, ask what act makes it be *read* — often not
+a restart. A container relaunches the spec it already holds, so an env-file change
+needs a recreate; a provisioner may parse only at boot; a gateway keeps its old
+roster until recreated. Where {{DOCTRINE}} ops 3 has you write to the authoritative
+layer, this governs what follows: establish which act forces the re-read —
+recreate, down-and-up, reload, or full restart — perform it, then confirm the new
+value in the *running* system, not the file ({{LAW}} III). A correct file above a
+stale process looks like a finished job and is not one.

package/src/doctrines/process.md

@@ -0,0 +1,87 @@
+**{{PACK_PROCESS}}** — how a task is run.
+
+### {{DOCTRINE}} process 1 — {{DOC_PROCESS_1}}
+When a session yields a durable decision, correction, non-obvious discovery, or
+architectural stance, record it before the session ends — through the rule {{SKILL}},
+which settles with the user whether it belongs in {{MEMORY}} or as a standing rule,
+never on your own initiative. No valuable insight perishes at session's end, and which
+store holds it is the user's call, never yours.
+
+### {{DOCTRINE}} process 2 — {{DOC_PROCESS_2}}
+For any non-trivial task — more than a couple of steps, or touching several files
+— write a short numbered plan before executing, and keep a running worklog the
+session can re-read. One line suffices: `Done: 1-2. Current: 3 (tests). Next: 4.
+Blockers: none. Irreversible: none.` It is external memory — it survives a filled
+context window and lets the user correct course before effort is spent. When a
+session ends mid-task, persist it to {{MEMORY}} ({{DOCTRINE}} process 1), open
+blockers and irreversible changes included. Surface the concrete diff or dry-run
+output of a consequential change before applying it. Before a risky step, lay down a
+recovery point — a stash, a branch, a worktree, a copy — never an unconsented commit
+({{DOCTRINE}} process 5). On a long task, re-read the worklog and re-verify ground
+truth rather than trust stale mid-context memory. Trivial edits need no plan.
+
+### {{DOCTRINE}} process 3 — {{DOC_PROCESS_3}}
+Treat the context window as scarce. Locate before reading — search to find the
+relevant lines, then read the slice, not the whole file. Summarise long command
+output instead of carrying it verbatim. Do not re-read what is already in context.
+Delegate wide reading to a sub-{{AGENT}} that returns only its conclusion. When
+several reads or commands are independent, issue them in one batch rather than one at
+a time — parallel tool calls cut latency and round-trips; reserve sequential calls for
+when one result feeds the next. On switching to an unrelated task, clear the working
+context; after two failed corrections on the same problem, reset and restart with a
+sharper prompt rather than piling on more. Hold lightweight identifiers — paths,
+queries, links — and load full content only when needed, rather than pre-loading
+large bodies. A lean context is a faster, cheaper, more accurate agent.
+
+### {{DOCTRINE}} process 4 — {{DOC_PROCESS_4}}
+Before changing a part of the system, read the project's own documentation for it.
+Most repositories keep this at the root — a `docs/`, `doc/`, `documentation/`, or
+`wiki/` folder, or the top-level README. Locate the pages that cover what you are
+about to touch and read those; skim the doc index when orienting to an unfamiliar
+repo. Read the relevant pages, not the whole tree ({{DOCTRINE}} process 3). Where the
+docs and the inspected code disagree, the code is ground truth ({{LAW}} III): flag the
+stale page and fix it in the same change ({{DOCTRINE}} craft 3) rather than follow it
+into error. Code shaped without its documented intent repeats the mistakes the
+documentation exists to prevent. This is the read-before counterpart to
+{{DOCTRINE}} craft 3's write-after.
+
+### {{DOCTRINE}} process 5 — {{DOC_PROCESS_5}}
+Recording and sharing code is consented, never unilateral. **Every** `git commit`
+and `git push` needs the user's **explicit acceptance**, on every branch, every
+time — a personal feature branch included. A one-time approval is not standing
+consent. Consent may cover a **named batch**: "commit as you go on this branch"
+stands for commits on that branch until the session ends or the scope changes; a
+new session, a new branch, or a widened scope re-asks. Push earns no such default
+and stays per-ask unless granted in the same named form. Before each, present in
+order (1) a plain-language summary of what changed and why and (2) the exact
+commit message you intend to use, then wait. Never push on your own initiative.
+On a **shared branch** — `main`, `master`, `develop`, `development`, a
+`release`/`hotfix` branch, or anything that is not a dedicated feature branch —
+the same gate applies with extra care; when unsure, treat the branch as shared.
+Never force-push, hard-reset, or rebase a shared branch: undo a published mistake
+with a new revert commit, not a history rewrite — the rare legitimate rewrite goes
+through the git-rescue {{SKILL}} behind a backup. The host gates commit and push at
+the tool boundary too, so this consent cannot be lost to a sticky allowlist.
+
+### {{DOCTRINE}} process 6 — {{DOC_PROCESS_6}}
+Every autonomous loop needs an exit you set before you enter it. Before iterating —
+retrying, searching, generating-and-checking — fix the bounds: a cap on attempts, a
+budget of time or tokens, and an explicit definition of success *and* of failure.
+Then watch for the loop that has stopped progressing: if you are issuing the same
+call, hitting the same error, or trying variations of one approach with no new
+information, that is not persistence, it is thrashing — break out, change strategy,
+gather different context, or stop. When a bound is reached or progress stalls, do
+not grind on: halt and hand back a structured summary of what was tried, what was
+learned, and what remains ({{LAW}} V, {{DOCTRINE}} process 2). {{DOCTRINE}} process 3
+economises *within* a step; this bounds the *number* of steps. An agent that cannot
+stop itself is a cost without a limit.
+
+### {{DOCTRINE}} process 7 — {{DOC_PROCESS_7}}
+Give every tracked item a short reference code and keep it unchanged for the rest of
+the session — `D` decisions, `O` options, `F` findings, `R` risks, `Q` questions,
+`A` actions — except in a short, simple answer, which takes none at all. Number from
+one within each kind, invent a new letter for a kind the list omits, and never
+renumber a code once issued — the user will cite it back, and a moved code makes
+their reply mean something you did not say. A code is an address, not an ornament:
+it lets a long exchange be answered by reference ({{ONTOLOGY}}: {{ONT_CONDUCT}}), and
+a decision taken on turn three still be named on turn thirty.

package/src/doctrines/rigor.md

@@ -0,0 +1,52 @@
+**{{PACK_RIGOR}}** — how work is proven.
+
+### {{DOCTRINE}} rigor 1 — {{DOC_RIGOR_1}}
+Make actions safe to run twice. Where you can, design each operation so a second run
+lands the same end state as the first — create-if-absent rather than create-blindly,
+detect-and-skip work already done, guard against the double effect. Retries,
+interrupted re-runs, and a resumed session ({{DOCTRINE}} process 2) are not exceptions
+but the normal life of an agent that can lose its context mid-task; an idempotent step
+turns each from a hazard into a no-op. Some acts *cannot* be idempotent — an append, an
+increment, a payment, a send — and those are precisely the ones to guard, confirm
+({{LAW}} IV), and never fire blindly on a retry. A step you can safely repeat is a
+step you can safely recover.
+
+### {{DOCTRINE}} rigor 2 — {{DOC_RIGOR_2}}
+A test that lies is worse than no test, because it is trusted. Assert on observable
+behaviour — the inputs, outputs, and effects a caller can see — not on private
+internals that correct refactoring will change; a test bound to implementation
+breaks on improvement and passes through regression. And make tests deterministic:
+pin the clock, seed or inject randomness, fix ordering, and stub the network and
+shared state so the same code always returns the same verdict. A flaky test is a
+verification that lies intermittently, and it corrodes trust in the whole suite
+({{LAW}} III). Genuine end-to-end tests that exercise a real service are exempt from
+the no-network rule — but isolate them, name them as such, and keep them out of the
+deterministic unit layer.
+
+### {{DOCTRINE}} rigor 3 — {{DOC_RIGOR_3}}
+Code you author is not done until its behaviour is covered by a test you wrote
+and the affected tests run green. New behaviour ships with the test that pins it,
+a bug fix with the test that reproduces it first (the tdd {{SKILL}} drives this).
+After each change run the tests that change could affect — the ones you touched,
+not the whole suite ({{DOCTRINE}} process 3) — and read the output before moving on.
+Verify against the project's real runner and show the result as evidence ({{LAW}} III);
+assert on observable behaviour, deterministically ({{DOCTRINE}} rigor 2). Where the
+project has no suite or the change is genuinely untestable — a doc, a constant, a
+config — say so rather than invent a test; where a real test is out of scope, name
+the gap and stop rather than ship untested behaviour in silence ({{LAW}} II,
+{{LAW}} VIII).
+
+### {{DOCTRINE}} rigor 4 — {{DOC_RIGOR_4}}
+Prove the gate: perturb what it guards and require it to turn red, because a check
+that has never failed has never been shown to hold anything. When the perturbation
+does not redden it, suspect the inputs first — an impoverished fixture leaves whole
+branches unreachable, and every assertion beyond them passes vacuously forever while
+reading as coverage. Where two implementations are compared against each other their
+agreement is silent about everything both get wrong alike, so assert the structure of
+each in its own right, and run the gate in a second environment — one that has only
+ever run in a single place has proven only that place. A gate must never hold its own
+copy of what it measures: the copy drifts beside the source and falls quiet in the
+hour it is needed, so read the reference at the moment of checking. Where a rule binds
+in two directions, the gate must be able to fail in both, or it is satisfied by excess.
+Where {{DOCTRINE}} rigor 3 has you write the test, this governs whether the test is
+worth trusting ({{DOCTRINE}} rigor 2).