geneseed 2.0.0 → 2.1.0

package/README.md

@@ -4,6 +4,7 @@
 
 **A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.**
 
+[![npm](https://img.shields.io/npm/v/geneseed?color=cb3837&logo=npm)](https://www.npmjs.com/package/geneseed)
 [![CI](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml/badge.svg)](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
@@ -11,7 +12,7 @@
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
 [![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-17-orange)](src/agents/)
-[![Laws](https://img.shields.io/badge/laws-37-critical)](src/laws/universal.md)
+[![Laws](https://img.shields.io/badge/laws-40-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · Copilot · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20Copilot%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
@@ -50,7 +51,7 @@ geneseed-build --theme imperial  # Warhammer 40k voice, identical structure
 
 ### ⚡ The short way — `npx`
 
-One command, nothing cloned, nothing else to install. The only prerequisite is **Node ≥ 22.3**.
+The harness is published on npm as **[`geneseed`](https://www.npmjs.com/package/geneseed)** — three commands (`geneseed`, `geneseed-hook`, `geneseed-build`), zero dependencies. One command, nothing cloned, nothing else to install. The only prerequisite is **Node ≥ 22.3**.
 
 ```bash
 npx geneseed setup            # the guided wizard
@@ -88,13 +89,11 @@ cd Geneseed
 
 Both launchers are thin shims over the Node CLI: they need `node` (22.3+) on `PATH`, and nothing else. Set `GENESEED_NODE` to an absolute path if `node` is not on `PATH` — under a version manager that only patches interactive shells, say. The wizard is plain text prompts on every console, old or new.
 
-**Already installed from a clone?** `geneseed migrate` moves every install you have onto the npm shape in one pass, all-or-nothing, without touching hooks or login items it did not write. Your old clone keeps working for a full release — there is no cliff. See [Migrate an existing install](docs/web/migrate.md).
-
 ### 🟩 One runtime — Node, and nothing else
 
-Node ≥ 22.3 is the entire dependency list. Every subcommand, all four hooks, every web-console endpoint and both generators run from it, and what each of them emits is replayed against frozen recordings on every commit, across every theme × host × footprint. So an install needs no second interpreter — not for the harness, and not for anything it ships.
+Node ≥ 22.3 is the entire dependency list. Every subcommand, all four hooks, every web-console endpoint and both generators run from it, and every commit runs the whole unit suite plus `doctor --all` across every theme × host × footprint, on Linux and Windows both. So an install needs no second interpreter — not for the harness, and not for anything it ships. (Until 2026-08-17 the generator's output was also replayed byte for byte against recordings taken from the Python implementation. Those were retired — see [`docs/limits.md`](docs/limits.md) for the measurement that licensed it and the coverage it cost.)
 
-- **0 commands have no Node twin**: 25 of the 25 subcommands, and all four hook verbs, answer from the Node entry points. `catalog`, `mcp` and `memory` are Node-native faces the CLI table declares on top of that roster. There is no full-screen browse panel — `geneseed tui` and `geneseed menu` are verbs that refuse it by name and print the command list instead. Off a terminal, which is how scripts and CI run them, the bytes and the exit code are the recorded ones.
+- **0 commands have no Node twin**: 25 of the 25 subcommands, and all four hook verbs, answer from the Node entry points. `catalog`, `mcp` and `memory` are Node-native faces the CLI table declares on top of that roster. There is no full-screen browse panel — `geneseed tui` and `geneseed menu` are verbs that refuse it by name and print the command list instead, off a terminal as well as on one.
 - **Nothing you install needs an interpreter.** The `token-report` skill is a script rather than prose, and it ships as `scripts/token_report.mjs`, run with `node`; `daydream` and `herdr` hand their inline code to `node -e`. So **every bundle carries** nothing that needs one: no Python file, and no skill that shells out to an interpreter, on any host, theme or footprint. Three tests freeze that — one scans every tracked file for inline code handed to an interpreter, one globs the bundle source, and one replays the report script over seeded transcripts for all four hosts and compares the bytes.
 - **`upgrade` / `update` / `sync-self` / `bootstrap` are for a git checkout.** They `git pull` the install's own origin. From an npm install they stop before touching anything and name `npm install -g geneseed@latest` as the update instead.
 
@@ -153,7 +152,7 @@ The harness ships as a small set of layers, mirrored one-for-one in the web cons
 
 | Layer | What it is |
 | --- | --- |
-| **🛡️ Rules** (`laws/`) | 37 universal laws the agent obeys — secrets, scope, verify-before-assert, surface-failures, context economy, load-the-docs, tool-discovery, non-interactive-shell, untrusted-content, least-privilege, external-gate, root-cause, idempotency, calibrated-honesty, source-over-surface, restart-is-not-reload, total-teardown, cover-and-verify… |
+| **🛡️ Rules** (`laws/`) | 40 universal laws the agent obeys — secrets, scope, verify-before-assert, surface-failures, context economy, load-the-docs, tool-discovery, non-interactive-shell, untrusted-content, least-privilege, external-gate, root-cause, idempotency, calibrated-honesty, source-over-surface, restart-is-not-reload, total-teardown, cover-and-verify, prove-the-gate, answer-shape, stable-reference-codes… |
 | **🤖 Agents** (17) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
 | **🛠 Skills** (47) | repeatable workflows: brainstorm · **clarify** · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · tdd · **develop** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · geneseed-code-review · **fresh-eyes** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **learning-path** · **gap-detector** · **feynman** · **crash-course** · **drill** · **decode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **opencode-theme** · **herdr** · **pipeline** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
@@ -261,7 +260,8 @@ Geneseed/
 │   └── notebook/         the agent's own freeform space — convention + index
 ├── themes/               voice token maps (14 themes shipped)
 ├── web/                  Vite + React UI source; the committed web/dist/ build is what ships
-├── tests/                Node test suites + the frozen corpora they replay (tests/__snapshots__/)
+├── tests/                Node test suites + the pure-function/help recordings they replay
+│                         (tests/__snapshots__/ — the emit/cli/web corpora retired 2026-08-17)
 ├── docs/                 guides (web-ui, wiki, …) + docs/web/ (the console's Docs pages);
 │                         specs/, reviews/, superpowers/ are local working docs — git-ignored
 ├── adapters/             per-host glue (opencode/, claude-code/, bob/, copilot/)
@@ -294,8 +294,6 @@ geneseed rebuild-all   # re-render every registered install in its own theme + m
 ./geneseed upgrade     # just the content refresh (remembers theme + emit mode)
 ```
 
-**Moving from a clone to npm** — `geneseed migrate` re-emits every install you already have onto the npm shape, all-or-nothing, and reports (never rewrites) the hooks and login items it did not write. `--dry-run` prints the plan first. See [Migrate an existing install](docs/web/migrate.md).
-
 **Local edits survive.** The self-improvement loops let the agent refine its deployed agent/skill files in place. Before setup, re-theme, or upgrade overwrites them, any drift is auto-exported to a markdown **improvements file** under `improvements/` *inside the deployed harness dir* (e.g. `~/.config/opencode/improvements/` for the global install) — beside the install it describes, untouched by rebuilds and uninstall. Hand it to an agent in this repo to back-port the changes into `src/`. On demand: `./geneseed diff --out FILE`, or the **Changes** page in the web console.
 
 Details and precedence rules: [SETUP.md → Upgrade](SETUP.md#upgrade).

package/SETUP.md

@@ -100,9 +100,11 @@ hand? Pick a path below.
 > **Every `geneseed-build …` below is the generator.** `npm install -g geneseed` puts it
 > on your `PATH`; without installing anything, `npx -p geneseed geneseed-build --emit
 > opencode-global` is the same command. From a checkout it is
-> `node bin/geneseed.mjs` with the same flags. Its output is replayed byte for byte
-> against frozen recordings on every commit, across every theme × host × footprint
-> combination.
+> `node bin/geneseed.mjs` with the same flags. Every commit re-emits with it across every
+> theme × host × footprint combination and checks the result with `doctor --all`, on Linux
+> and Windows both. Until 2026-08-17 that output was also compared byte for byte against
+> recordings taken from the Python implementation; those were retired, and `docs/limits.md`
+> says why and what it cost.
 
 ---
 
@@ -602,7 +604,9 @@ command serves gitlab.com and any private instance.
 scopes `api` and `read_repository`. Treat it like a password.
 
 **2. Register one entry per instance** — same command, different `GITLAB_API_URL`
-and token. Two instances (e.g. gitlab.com plus a self-hosted server) → two entries:
+and token. Two instances (e.g. gitlab.com plus a self-hosted server) → two entries.
+The MCP screen ships a one-click row for the **first** entry only; a second instance is a
+hand-added copy of that block, which is all it ever was:
 
 <!--harness:opencode-->
 On OpenCode, under the `mcp` key of `opencode.json`:
@@ -642,6 +646,11 @@ The entry key is just a label — name them `gitlab` / `gitlab-2`, or after each
 (`gitlab`, `gitlab-acme`). What separates the two is the `GITLAB_API_URL` + token pair;
 keep the `/api/v4` suffix on the URL.
 
+**Don't know where this file lives?** Run `geneseed web`, open **Harnesses**, and expand an
+active install — each MCP target prints the full path of the config file it writes, right
+above its server rows. That is the file the token and the URL go into. From the terminal,
+`geneseed mcp` prints the same paths without starting anything.
+
 #### Filesystem
 
 Give the agent scoped file access via
@@ -981,9 +990,8 @@ anything, naming the `npm install -g` line above instead.
 **Installed from a clone:**
 
 ```
-./geneseed upgrade                 # track main; keep the remembered theme + emit mode
-./geneseed upgrade v1.0.0          # pin to a tag
-./geneseed upgrade main imperial   # force a theme
+./geneseed upgrade                 # track the checkout's current branch; keep theme + emit mode
+./geneseed upgrade imperial        # force a theme
 ```
 
 It git-pulls the install's own origin (fast-forward only), validates it (a blocking

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical pointers, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **2.0.0**.
+> string. Current label: **2.1.0**.
 
 > **Spec status audit (2026-06-15).** Every dated spec authored before today was
 > verified against the source tree and confirmed implemented (code + tests + docs);
@@ -35,7 +35,7 @@ Every row below is present in the tree today; "Spec" links the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 37 laws, 17 agents, 47 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
+| **Laws / Agents / Skills / Memory / Notebook** | 40 laws, 17 agents, 47 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | [theme-aware doctor/diff](docs/specs/2026-06-07-theme-aware-doctor-diff.md) |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | [improvements-export](docs/specs/2026-06-12-improvements-export.md) |
 | **`status` / `version`** | Headless dashboard + fingerprint verdict (no TUI needed) | [status-command](docs/specs/2026-06-07-status-command.md) · [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
@@ -48,7 +48,7 @@ Every row below is present in the tree today; "Spec" links the design record.
 | **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | [collaboration-layer](docs/specs/2026-07-12-collaboration-layer.md) |
 | **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Law VI carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | [rule-front-door](docs/specs/2026-07-30-rule-front-door.md) |
 | **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | [entity-registry](docs/specs/2026-07-31-entity-registry.md) |
-| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all four hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. What each of them emits is replayed against frozen recordings on every commit, across every theme × host × footprint. It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | [npx-distribution](docs/specs/2026-08-06-npx-distribution.md) |
+| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all four hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (`docs/limits.md`). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | [npx-distribution](docs/specs/2026-08-06-npx-distribution.md) |
 | **Runtime awareness** | MCP discovery, web research, tool-call batching, review discipline baked into the laws | [runtime-awareness](docs/specs/2026-06-07-runtime-awareness-and-review-discipline.md) |
 | **Run from anywhere / uninstall** | `link`/`unlink` onto PATH; global uninstall that keeps the memory store | [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
 

package/adapters/opencode/opencode.json

@@ -26,15 +26,6 @@
       },
       "enabled": false
     },
-    "gitlab-2": {
-      "type": "local",
-      "command": ["npx", "-y", "@zereight/mcp-gitlab"],
-      "environment": {
-        "GITLAB_PERSONAL_ACCESS_TOKEN": "",
-        "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
-      },
-      "enabled": false
-    },
     "filesystem": {
       "type": "local",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],

package/bin/geneseed.mjs

@@ -387,7 +387,7 @@ function warnBobGlobalOverProject() {
     + "(doubled context) unless Bob's workspace rules truly shadow the global "
     + "one there. Review and remove what you don't want:\n");
   for (const root of survivors) {
-    process.stderr.write(`  - ${root}  ->  harness uninstall --target "${root}"\n`);
+    process.stderr.write(`  - ${root}  ->  geneseed uninstall --target "${root}"\n`);
   }
 }
 
@@ -501,7 +501,7 @@ function warnCopilotGlobalOverProject() {
     + '(doubled context): Copilot stacks ~/.copilot/copilot-instructions.md on top '
     + "of a repo's own AGENTS.md. Review and remove what you don't want:\n");
   for (const root of survivors) {
-    process.stderr.write(`  - ${root}  ->  harness uninstall --target "${root}"\n`);
+    process.stderr.write(`  - ${root}  ->  geneseed uninstall --target "${root}"\n`);
   }
 }
 

package/docs/declined.md

@@ -8,6 +8,16 @@ The reference has been deleted, so "the reference does X" is no longer an argume
 re-run. What is recorded in `tests/__snapshots__/` is the reference's answer, frozen; what is
 listed here is where this implementation answers differently on purpose.
 
+**The recording is smaller than it was.** On **2026-08-17** the emit, cli and web corpora were
+retired — 1381 cells, produced by an implementation that no longer exists and re-recordable by
+nothing, so they reddened on every deliberate content change while saying nothing about a defect
+that happened to be stable. What licensed it was a measurement: all five mutations whose only
+declared gate was a corpus replay are killed by `tests/unit/` alone. `docs/limits.md` carries the
+full argument and what it cost. **The consequence for this page is narrow and worth stating: an
+entry whose "how it stays honest" half named one of those three corpora now names a weaker gate, or
+none.** The help fixtures under `tests/__snapshots__/help/`, which most of this page rests on, are
+untouched.
+
 ---
 
 ## `--help`: the prog is `geneseed`, not `harness`
@@ -101,8 +111,14 @@ entry above and readers keep finding it separately.
 
 argparse printed a usage block around every parse failure and prefixed it `harness: error:`; both
 entries state the fault on one line prefixed `geneseed: error:` / `geneseed-hook: error:`. See
-`bin/geneseed-cli.mjs`'s `parse` docblock. What IS gated is every error a command's own body
-raises — those are in the recorded CLI corpus, replayed by `tests/cli_golden.mjs`.
+`bin/geneseed-cli.mjs`'s `parse` docblock.
+
+**What used to be gated beside it no longer is.** Every error a command's own body raises was in
+the recorded CLI corpus, replayed cell by cell; that corpus was retired on 2026-08-17 and the
+per-verb error texts are now covered only where `tests/unit/` happens to drive the verb. The
+divergence declared here is unchanged — the port has never reproduced argparse's wording and does
+not start now — but the *neighbouring* claim, that the rest of the error surface is pinned byte for
+byte, has expired.
 
 ---
 
@@ -147,3 +163,38 @@ docblock this as "argparse's own rule". It is not — that generalised from `dif
 which works only because an UNKNOWN option is deferred to the end of `parse_known_args`. Two of
 that test's four cases are cases where the reference errors instead, so the test pins a
 divergence; its docblock now says which cases those are and points here.
+
+## A verb that postdates the recorder is exempted from the cell matrix by name
+
+**Status:** ACCEPTED, 2026-08-19. This widens an existing exemption rather than minting a second
+one, and it changes a TEST, not the product.
+
+**What differs.** `tests/unit/hook_cli.test.mjs`'s `the matrix covers every verb each entry
+claims` asserted a strict equality between the hook verbs `tests/helpers/matrix/cli.*.json`
+covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test already
+exempted a named `NATIVE` list; the hook half exempted nothing. Both halves now filter through
+the same list.
+
+**Why the recording could not be kept as the whole answer.** The matrix was exported by the
+reference implementation, which was deleted on 2026-08-17 along with every recorder that could
+write a cell. So the covered set is frozen at four hook verbs for good. A fifth hook verb —
+wired in `js/settings.mjs`, carried in `bin/geneseed-hook.mjs`, declared in `js/cli-table.json` —
+would fail this equality with **no green path**: the corpus cannot grow, and the failure message
+correctly forbids deleting cells to pass. The gate had become a wall, and a wall that stops a
+legitimate change is not protection, it is an accident of when the recorder died.
+
+The reason the three CLI verbs were exempted in the first place — *the reference had nothing to
+compare against, and authoring one would be recording a copy of the value under test* — is
+exactly the reason a verb that postdates the reference has no cell. Same reason, same exemption.
+
+**What was lost, measured.** Nothing that another gate does not already hold. The only property
+the frozen hook half carried beyond `NATIVE` was *"a hook verb cannot be removed by a coordinated
+edit of three files"* — and `tests/unit/hook_cli.test.mjs`'s own literal (`sorted(wired)` against
+the four names) plus its `verbsOf(HOOK) === wired` equality are two editable copies of that same
+set, twelve lines above. `tests/mutate.mjs`'s M8 plants the one-file removal and is killed there,
+not here.
+
+**How it stays honest.** The exemption is a NAMED list, not a containment: a new verb has to be
+written into `NATIVE` deliberately, in two files that read each other's source, and the reverse
+check refuses an exemption for a verb neither entry point carries. So the next new verb still
+fails loudly until someone decides about it — which is the whole point of the original design.