geneseed 5.2.0 → 5.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +54 -0
- package/README.md +4 -4
- package/SHIPPED.md +1 -1
- package/adapters/bob/README.md +31 -18
- package/adapters/claude-code/README.md +27 -22
- package/adapters/openclaude/README.md +18 -8
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +8 -3
- package/adapters/opencode/plugins/geneseed-activity.js +20 -21
- package/adapters/opencode/plugins/geneseed-context.js +224 -71
- package/adapters/opencode/plugins/geneseed-guard.js +420 -203
- package/adapters/opencode/plugins/geneseed-workflow.js +3 -2
- package/adapters/opencode/workflows/_runtime.js +3 -2
- package/bin/geneseed-cli.mjs +61 -16
- package/bin/geneseed-hook.mjs +94 -12
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +2 -2
- package/docs/concepts/factories.md +40 -6
- package/docs/concepts/footprint.md +11 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/hook-gates.md +3 -3
- package/docs/concepts/host-matrix.md +22 -4
- package/docs/concepts/loop-gates.md +1 -1
- package/docs/concepts/loops.md +2 -2
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/design-history.md +148 -0
- package/docs/extending.md +97 -163
- package/docs/guides/install-bob.md +2 -2
- package/docs/guides/install-openclaude.md +1 -1
- package/docs/guides/run-a-factory.md +15 -2
- package/docs/guides/upgrade.md +2 -2
- package/docs/guides/verify.md +12 -0
- package/docs/reference/environment.md +1 -0
- package/docs/reference/factory-actions.md +6 -5
- package/docs/reference/troubleshoot-doctor.md +1 -1
- package/docs/reference/troubleshoot-update.md +1 -1
- package/docs/token-footprint.md +66 -2
- package/docs/understand/design-choices-hosts.md +1 -1
- package/docs/understand/design-choices-shape.md +1 -0
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/understand/machine-bob.md +1 -1
- package/docs/web-ui.md +21 -3
- package/harness.config.json +1 -1
- package/js/README.md +7 -5
- package/js/build/args.mjs +4 -4
- package/js/build/driver.mjs +1 -1
- package/js/build/emit-claude.mjs +1 -1
- package/js/build/generate.mjs +5 -14
- package/js/build/render.mjs +44 -24
- package/js/cli-table.json +135 -59
- package/js/factory/cli.mjs +24 -5
- package/js/factory/graph.mjs +13 -9
- package/js/factory/metrics.mjs +93 -0
- package/js/factory/registry.mjs +37 -12
- package/js/factory/state.mjs +25 -6
- package/js/hosts/done-checks.mjs +6 -0
- package/js/hosts/geneseed-dir.mjs +3 -2
- package/js/hosts/gitref.mjs +5 -3
- package/js/hosts/hook-tap.mjs +104 -0
- package/js/hosts/hooks-context.mjs +30 -3
- package/js/hosts/hooks-learn.mjs +47 -16
- package/js/hosts/hooks-prims.mjs +52 -3
- package/js/hosts/hooks.mjs +69 -42
- package/js/hosts/hosts.mjs +80 -12
- package/js/hosts/installs.mjs +7 -0
- package/js/hosts/loss.mjs +6 -1
- package/js/hosts/native.mjs +14 -5
- package/js/hosts/owned.mjs +7 -6
- package/js/hosts/ownership-gate.mjs +14 -1
- package/js/hosts/settings.mjs +245 -103
- package/js/hosts/shim.mjs +4 -4
- package/js/hosts/usage.mjs +9 -3
- package/js/inspect/checks-probe.mjs +66 -5
- package/js/inspect/checks-repo.mjs +196 -2
- package/js/inspect/cost.mjs +34 -2
- package/js/inspect/diff.mjs +16 -1
- package/js/inspect/doctor.mjs +13 -4
- package/js/inspect/excludes.mjs +18 -6
- package/js/inspect/status.mjs +35 -7
- package/js/inspect/validate.mjs +44 -21
- package/js/lib/machine-dir.mjs +1 -1
- package/js/lib/node-floor.mjs +46 -6
- package/js/maintain/uninstall.mjs +70 -17
- package/js/maintain/update.mjs +31 -7
- package/js/ui/cli.mjs +34 -4
- package/js/ui/menu.mjs +1 -1
- package/js/ui/tui.mjs +11 -14
- package/js/web/actions.mjs +3 -9
- package/js/web/api.mjs +28 -10
- package/js/web/daemon.mjs +0 -1
- package/js/web/server.mjs +1 -0
- package/js/web/state.mjs +37 -16
- package/package.json +1 -1
- package/src/AGENT.md.tmpl +23 -17
- package/src/agents/_template.md +1 -1
- package/src/agents/advocate.md +1 -1
- package/src/agents/developer.md +12 -3
- package/src/agents/empiricist.md +1 -1
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/bricks/intake.md +10 -3
- package/src/bricks/retro.md +13 -3
- package/src/doctrines/comms.md +1 -1
- package/src/doctrines/ops.md +1 -1
- package/src/doctrines/process.md +7 -5
- package/src/factories/analysis-to-build.json +1 -0
- package/src/factories/bug-report-to-fix.json +1 -0
- package/src/factories/issue-to-pr.json +1 -0
- package/src/laws/universal.md +2 -2
- package/src/modes/foreman.md +8 -14
- package/src/skills/commit.md +7 -2
- package/src/skills/debug.md +1 -1
- package/src/skills/diagram-design/SKILL.md +1 -1
- package/src/skills/diagram-design/VENDOR.md +3 -1
- package/src/skills/factory-forge.md +5 -3
- package/src/skills/factory.md +22 -1
- package/src/skills/geneseed.md +1 -1
- package/src/skills/handoff.md +1 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +6 -6
- package/src/skills/plan.md +7 -3
- package/src/skills/spring-testing.md +1 -1
- package/themes/biker.json +78 -78
- package/themes/commentator.json +81 -81
- package/themes/cyberpunk.json +79 -79
- package/themes/gamer.json +77 -77
- package/themes/imperial.json +82 -82
- package/themes/joker.json +79 -79
- package/themes/marvin.json +82 -82
- package/themes/mean.json +82 -82
- package/themes/military.json +78 -78
- package/themes/neutral.json +78 -78
- package/themes/pirate.json +79 -79
- package/themes/sports.json +79 -79
- package/themes/verstappen.json +78 -78
- package/themes/wizard.json +79 -79
- package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
- package/web/dist/assets/Activity-WQ3ykgxU.js +1 -0
- package/web/dist/assets/ActivityDetail-7rt04SkS.js +1 -0
- package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-BBl4XXqs.js} +1 -1
- package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-Beven8yn.js} +1 -1
- package/web/dist/assets/Dashboard-BgLArtgu.js +2 -0
- package/web/dist/assets/Docs-B5aHp86J.js +5 -0
- package/web/dist/assets/Factories-BjqzXAw8.js +1 -0
- package/web/dist/assets/GreenhouseView-Bce212qd.js +1 -0
- package/web/dist/assets/Installs-B1OsrHXF.js +3 -0
- package/web/dist/assets/JournalView-CV4omyww.js +1 -0
- package/web/dist/assets/Kits-CW1e7xNa.js +1 -0
- package/web/dist/assets/Laws-1Ckf1lbs.js +4 -0
- package/web/dist/assets/LibRows-Dag1s0ZX.js +1 -0
- package/web/dist/assets/Library-B3FuFLel.js +3 -0
- package/web/dist/assets/Loops-CwqgnLNw.js +2 -0
- package/web/dist/assets/Markdown-CxkA7940.js +71 -0
- package/web/dist/assets/OperatorHudView-JmYY1pBR.js +1 -0
- package/web/dist/assets/Personal-DKLgLa7Z.js +2 -0
- package/web/dist/assets/Settings-BwErnh-R.js +1 -0
- package/web/dist/assets/Tabs-8zsyEPSK.js +1 -0
- package/web/dist/assets/index-CRWqKxfY.css +1 -0
- package/web/dist/assets/index-Ce6qF2nG.js +6 -0
- package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
- package/web/dist/index.html +2 -2
- package/adapters/claude-code/settings.json +0 -52
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
- package/web/dist/assets/Activity-DlQ30znB.js +0 -1
- package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
- package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
- package/web/dist/assets/Docs-CisVnYqv.js +0 -5
- package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
- package/web/dist/assets/GreenhouseView-y9WAfcc_.js +0 -1
- package/web/dist/assets/Installs-m4GElwFW.js +0 -3
- package/web/dist/assets/JournalView-DeBLRNGc.js +0 -1
- package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
- package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
- package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
- package/web/dist/assets/Library-Dg0ScciC.js +0 -3
- package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
- package/web/dist/assets/Markdown-0ORz7tAc.js +0 -69
- package/web/dist/assets/OperatorHudView-2ujVMjq1.js +0 -1
- package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
- package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
- package/web/dist/assets/Tabs-But5R6_r.js +0 -1
- package/web/dist/assets/index-Ck42AbRX.js +0 -6
- package/web/dist/assets/index-PG_ukkh6.css +0 -1
- package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
package/docs/design-history.md
CHANGED
|
@@ -1347,3 +1347,151 @@ Geneseed did make are listed in [Why Geneseed works this way](understand/design-
|
|
|
1347
1347
|
anchor stays. A runtime toggle that works beside the anchor, without replacing it, remains
|
|
1348
1348
|
possible. See
|
|
1349
1349
|
[Foreman mode](concepts/foreman-mode.md).
|
|
1350
|
+
- **A chat mode that switches the harness off for a quick question** (2026-11-12): a slash
|
|
1351
|
+
command, a ready-made excluded folder, or a `geneseed chat` verb. Measured on the real hosts,
|
|
1352
|
+
the harness adds 11–14k tokens per session at lean and 18–21k at full, billed in full once
|
|
1353
|
+
where the provider caches prompts. No host can unload it inside a conversation, an excluded
|
|
1354
|
+
folder leaves the skill listings (and removes nothing on OpenCode), and on Claude Code and
|
|
1355
|
+
OpenCode 2 a toggle on resume loads the harness twice. The hosts' own launch switches differ
|
|
1356
|
+
per host and per version, so a verb would have to track them. See
|
|
1357
|
+
[Token footprint](token-footprint.md#why-there-is-no-chat-mode).
|
|
1358
|
+
|
|
1359
|
+
---
|
|
1360
|
+
|
|
1361
|
+
## Extending guide — settled history (moved 2026-11-11)
|
|
1362
|
+
|
|
1363
|
+
[docs/extending.md](extending.md) carried these sections while they were live. Each one was
|
|
1364
|
+
settled, so they moved here as a record; the rules that still hold stayed in the guide. Section
|
|
1365
|
+
numbers below are the guide's numbers at the time, and "today" means the date in each heading.
|
|
1366
|
+
|
|
1367
|
+
### 5.1 ✅ A fifth hook verb — resolved 2026-08-19
|
|
1368
|
+
|
|
1369
|
+
**This was a hard blocker and it is now open.** Recorded here because the shape of the problem
|
|
1370
|
+
recurs: any gate whose expected value lives in an artifact nothing can re-make will eventually
|
|
1371
|
+
stop a legitimate change, and the fix is never to delete the artifact.
|
|
1372
|
+
|
|
1373
|
+
`tests/unit/hook_cli.test.mjs` asserted a strict equality between the hook verbs the frozen
|
|
1374
|
+
matrix covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test
|
|
1375
|
+
already exempted a named `NATIVE` list; the hook half exempted nothing — so a fifth hook verb
|
|
1376
|
+
failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
|
|
1377
|
+
correctly forbids deleting cells to pass.
|
|
1378
|
+
|
|
1379
|
+
`NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
|
|
1380
|
+
than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
|
|
1381
|
+
carries — so a name that stops meaning anything fails rather than sitting there.
|
|
1382
|
+
|
|
1383
|
+
**To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
|
|
1384
|
+
`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
|
|
1385
|
+
absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
|
|
1386
|
+
to stay in step; there is one copy now, so there is nothing to keep in step.
|
|
1387
|
+
|
|
1388
|
+
### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
|
|
1389
|
+
|
|
1390
|
+
Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
|
|
1391
|
+
be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
|
|
1392
|
+
red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
|
|
1393
|
+
cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
|
|
1394
|
+
|
|
1395
|
+
Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
|
|
1396
|
+
detection and nothing checks it.
|
|
1397
|
+
|
|
1398
|
+
### 5.4 ✅ Expected values are written out — resolved 2026-08-23
|
|
1399
|
+
|
|
1400
|
+
This section used to say that a snapshot red was a finding rather than a step: the recordings under
|
|
1401
|
+
`tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
|
|
1402
|
+
and a change that moved a recorded byte left only two honest options — revert it, or argue in
|
|
1403
|
+
writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
|
|
1404
|
+
blocks a change, move the logic to the nearest caller that is not frozen*.
|
|
1405
|
+
|
|
1406
|
+
**None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
|
|
1407
|
+
only way back to them), and every expected value now lives in the test file that asserts it, above
|
|
1408
|
+
a sentence saying which decision it pins. The rule is correspondingly ordinary:
|
|
1409
|
+
|
|
1410
|
+
> **Change the expectation and the sentence that explains it in the same commit, and say why in
|
|
1411
|
+
> the message.**
|
|
1412
|
+
|
|
1413
|
+
A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
|
|
1414
|
+
the cost that keeps the tables honest, and far cheaper than the one it replaced.
|
|
1415
|
+
|
|
1416
|
+
The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
|
|
1417
|
+
text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
|
|
1418
|
+
`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
|
|
1419
|
+
holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
|
|
1420
|
+
29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
|
|
1421
|
+
`tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
|
|
1422
|
+
`README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
|
|
1423
|
+
|
|
1424
|
+
### 7 — Stale on 2026-08-18, fixed on 2026-08-19
|
|
1425
|
+
|
|
1426
|
+
Nine items were found while writing this file, and fixed the next day. They are recorded as a
|
|
1427
|
+
list rather than left as a diff, because the PATTERN is the useful part: every one was a document
|
|
1428
|
+
or a comment pointing a reader at something that is not there, and in each case the gate that
|
|
1429
|
+
should have caught it either did not cover that file — or was itself the frozen copy of a wrong
|
|
1430
|
+
answer.
|
|
1431
|
+
|
|
1432
|
+
**Fixed.**
|
|
1433
|
+
|
|
1434
|
+
1. **`DESIGN.md` taught the deleted Python build.** Its header promises *"the spec behind the
|
|
1435
|
+
harness — read this before changing structure"*, and under it sat the six-edit checklist for
|
|
1436
|
+
adding a Law, naming a deleted generator, `rituals/_harness_tui.py` for `LAW_CLASS`, and an
|
|
1437
|
+
invocation of a program that no longer exists. Worse, `tests/unit/no_python.test.mjs` exempted
|
|
1438
|
+
the file as a *historical record* — so the gate that hunts pointers-to-nothing was looking away
|
|
1439
|
+
from the one document most likely to hold one. **Split**: the 190-line standing contract keeps
|
|
1440
|
+
the name and is now scanned; the 1,290-line port narrative moved to
|
|
1441
|
+
the port narrative above, which is exempt on the merits, and its dead links were
|
|
1442
|
+
repaired because a link is a pointer whatever the prose around it says.
|
|
1443
|
+
2. **`doctor` printed a command that errors.** The theme-parity tip named
|
|
1444
|
+
`./geneseed build --sync-themes`; `cmdBuild` forwards `--theme` and nothing else. The comment
|
|
1445
|
+
above the tip argued that spelling on a premise the port had quietly stopped satisfying. It now
|
|
1446
|
+
names `geneseed-build --sync-themes`, which is what README and SETUP said all along.
|
|
1447
|
+
3. **User-facing output named a program that does not exist.** `tui` and `uninstall` told users to
|
|
1448
|
+
run `harness setup` / `harness uninstall` — the reference's name, dropped in P0. Five sites.
|
|
1449
|
+
One of them was **pinned verbatim by a test**, so a gate was holding the wrong string in place;
|
|
1450
|
+
that assertion is now a property — every backticked command a refusal offers must be a verb
|
|
1451
|
+
`js/cli-table.json` declares — which is strictly stronger and fires on the next rename too.
|
|
1452
|
+
4. **The `tui` help promised a "full-screen curses control panel"** for a verb that returns 1 on
|
|
1453
|
+
every path. `docs/limits.md` listed this as permanently unfixable, on the grounds that the help
|
|
1454
|
+
corpus is frozen — but `formatHelp` never reads `cmd.help`, so it was an ordinary edit all
|
|
1455
|
+
along. The limits row went with the fix.
|
|
1456
|
+
5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
|
|
1457
|
+
tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
|
|
1458
|
+
named as `cli`, which was removed).
|
|
1459
|
+
6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
|
|
1460
|
+
`choices` before anything renders, which is why its own refusal read as an unreachable nicety.
|
|
1461
|
+
It is not in `choicesFor`; that refusal is the only one there is, on every path.
|
|
1462
|
+
7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
|
|
1463
|
+
the corpora — three test files justified their own design by pointing at a gate that is gone.
|
|
1464
|
+
Plus a skip message naming a `record-corpus` CI job that no longer exists.
|
|
1465
|
+
8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
|
|
1466
|
+
URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
|
|
1467
|
+
`geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
|
|
1468
|
+
9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
|
|
1469
|
+
the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
|
|
1470
|
+
a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
|
|
1471
|
+
there is one file.
|
|
1472
|
+
|
|
1473
|
+
### 10 — What to settle before the next wave
|
|
1474
|
+
|
|
1475
|
+
Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
|
|
1476
|
+
stop a change today, and all of them cost a contributor a wrong turn until they are done.
|
|
1477
|
+
|
|
1478
|
+
1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
|
|
1479
|
+
Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
|
|
1480
|
+
`DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
|
|
1481
|
+
reach. It keeps catching them.
|
|
1482
|
+
2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
|
|
1483
|
+
CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
|
|
1484
|
+
Either answer is fine; discovering the question mid-feature is not.
|
|
1485
|
+
3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
|
|
1486
|
+
is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
|
|
1487
|
+
and today nothing warns you before the snapshot goes red.
|
|
1488
|
+
4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
|
|
1489
|
+
`adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
|
|
1490
|
+
5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
|
|
1491
|
+
config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
|
|
1492
|
+
chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
|
|
1493
|
+
|
|
1494
|
+
The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
|
|
1495
|
+
deliberately keeps tables and prose hand-written and gates them from the source tree. The
|
|
1496
|
+
recommendations above are about the places where the gate is missing, wrong, or pointed at a file
|
|
1497
|
+
that no longer exists.
|
package/docs/extending.md
CHANGED
|
@@ -63,9 +63,10 @@ badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` ho
|
|
|
63
63
|
The baseline is whatever these commands report on your checkout — run them; no count is
|
|
64
64
|
written here, because a typed count is stale by the next commit.
|
|
65
65
|
|
|
66
|
-
CI
|
|
67
|
-
|
|
68
|
-
|
|
66
|
+
CI (`.github/workflows/ci.yml`) runs `validate` on Linux (Node 22 under c8, and Node 24) and on
|
|
67
|
+
Windows (the suite in shards, which `suite-count` sums), `node-cells` on Linux *and* Windows, and
|
|
68
|
+
`package-no-python`, `web`, `audit` and `links` on Linux; `ci-ok` is the one required check. From
|
|
69
|
+
the repo root — never from a worktree, see §5.3:
|
|
69
70
|
|
|
70
71
|
```bash
|
|
71
72
|
node bin/geneseed-cli.mjs doctor --all
|
|
@@ -97,13 +98,15 @@ cd web && npm ci && npm run lint && npm run format:check && npm test && npm run
|
|
|
97
98
|
|
|
98
99
|
Notes that matter:
|
|
99
100
|
|
|
100
|
-
- The root `package.json` has
|
|
101
|
+
- The root `package.json` has two scripts, `lint` and `typecheck`, and no pre-commit hook, Makefile or
|
|
101
102
|
justfile exists. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run
|
|
102
103
|
by hand with the glob above. `npm ci` once per clone installs the devDependencies `lint` needs
|
|
103
104
|
— it pulls no runtime dependency, because there are none.
|
|
104
|
-
- `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N
|
|
105
|
-
|
|
106
|
-
|
|
105
|
+
- `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N`, at
|
|
106
|
+
least 90 % of the `test(`/`it(` calls written in the tracked test files; the Windows shards are
|
|
107
|
+
held to it as a sum) because `node --test` over a glob that matches nothing prints `# tests 0`
|
|
108
|
+
and **exits 0**. Node's default reporter changed between majors, which is how a green 1043-test
|
|
109
|
+
suite once reported zero.
|
|
107
110
|
- `--cli` runs the ~320-cell CLI/hook matrix against the expectations written in each cell —
|
|
108
111
|
the only end-to-end gate on what a verb prints. CI runs it in `node-cells` on both platforms.
|
|
109
112
|
A cell that needs a broken checkout plants its fault as an **edit of the real file**
|
|
@@ -114,7 +117,7 @@ Notes that matter:
|
|
|
114
117
|
- **A local pass is weaker than CI.** ~18 tests in `tests/unit/package_manifest.test.mjs` carry
|
|
115
118
|
`{ skip: NO_NPM }` (`:83`) — every tarball, install and rename gate. On a machine without `npm`
|
|
116
119
|
on PATH they report *skipped* and the run is green.
|
|
117
|
-
- CI additionally re-runs the packaging suite under `npm@
|
|
120
|
+
- CI additionally re-runs the packaging suite under `npm@11`, the release's npm (Linux, last in the job), and
|
|
118
121
|
packs the tarball into a `node:22-slim` container with no interpreter. Neither is reproducible
|
|
119
122
|
from the seven commands; the container one is reachable locally through
|
|
120
123
|
`tests/helpers/no-python-container.sh` with a docker daemon.
|
|
@@ -134,7 +137,6 @@ Notes that matter:
|
|
|
134
137
|
Its *anchors* are now in CI (`--verify`, above): a row whose anchor a refactor has moved counts
|
|
135
138
|
as a **survivor**, not a skip, and until 2026-08-19 that only showed up for whoever ran the
|
|
136
139
|
matrix by hand — which nothing did.
|
|
137
|
-
- **Node 24.** No CI job runs it; `publish.yml` does. See §8.
|
|
138
140
|
- **`tests/golden.mjs`** is absent from the publish path entirely.
|
|
139
141
|
|
|
140
142
|
### Gates that fire on changes you would not expect to be gated
|
|
@@ -142,10 +144,10 @@ Notes that matter:
|
|
|
142
144
|
- **A new subprocess anywhere in `js/` or `bin/`** — `tests/unit/spawn_hygiene.test.mjs` requires
|
|
143
145
|
capturing spawns to set `windowsHide` and inheriting spawns not to. (`adapters/` is *not*
|
|
144
146
|
scanned, so a plugin that spawns is on its own.)
|
|
145
|
-
- **Editing `.github/workflows/*.yml`** —
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
files.
|
|
147
|
+
- **Editing `.github/workflows/*.yml`** — structural assertions in `tests/unit/docs.test.mjs`
|
|
148
|
+
gate `publish.yml`'s shape (found by `publishWorkflow`), and the test *every workflow that
|
|
149
|
+
count-gates `node --test` pins the TAP reporter* discovers every workflow with a test-count gate
|
|
150
|
+
and pins `--test-reporter=tap` on each `node --test` line. A unit test gates the CI files.
|
|
149
151
|
- **Adding any tracked file** — `tests/unit/package_manifest.test.mjs:401` demands every tracked
|
|
150
152
|
path fall on exactly one side of a declared partition, *with a written reason*. Adding this very
|
|
151
153
|
document required a `SHIPS` row; without one the tarball test fails, and it fails **before** the
|
|
@@ -205,8 +207,8 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
|
|
|
205
207
|
node bin/build-driver.mjs --sync-themes
|
|
206
208
|
```
|
|
207
209
|
|
|
208
|
-
⚠
|
|
209
|
-
|
|
210
|
+
⚠ `geneseed-build --sync-themes` is the same command; `geneseed build --sync-themes` is not —
|
|
211
|
+
`cmdBuild` (`BUILD_FORWARD`) does not forward `--sync-themes`. Then restyle all
|
|
210
212
|
fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
|
|
211
213
|
`RESTYLE these`; a shipped placeholder passes every gate.
|
|
212
214
|
4. `CHANGELOG.md`.
|
|
@@ -370,7 +372,7 @@ emit leaves the prior install intact.
|
|
|
370
372
|
5. `registry.json` — a row keyed `skills/<name>` or `agents/<name>` with `status` ∈
|
|
371
373
|
{`experimental`, `approved`, `deprecated`}, a semver `version`, a non-blank `owner`, an ISO
|
|
372
374
|
`added`, and `last_verified: ""`. **This is the most forgettable step**: four hand-typed fields,
|
|
373
|
-
and the gate fires in both directions (`js/inspect/
|
|
375
|
+
and the gate fires in both directions (`registryProblems`, `js/inspect/checks-repo.mjs`).
|
|
374
376
|
6. `README.md` — the badge, the `**🤖 Agents** (N)` / `**🛠 Skills** (N)` count, and for a skill the
|
|
375
377
|
`·`-separated name in the 🛠 row (that enumeration is gated two ways, unlike the laws' one).
|
|
376
378
|
7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
|
|
@@ -533,7 +535,7 @@ every pack, so a kit there would switch itself on in every install built before
|
|
|
533
535
|
|
|
534
536
|
---
|
|
535
537
|
|
|
536
|
-
## 4 — Adding a PLUGIN, a HOOK verb,
|
|
538
|
+
## 4 — Adding a PLUGIN, a HOOK verb, a doc page, or a HOST
|
|
537
539
|
|
|
538
540
|
### 4a — An OpenCode plugin
|
|
539
541
|
|
|
@@ -560,12 +562,12 @@ No `registry.json` row, no `package.json` edit — `files[]` ships `adapters/` w
|
|
|
560
562
|
|
|
561
563
|
### 4b — A hook verb (claude + bob)
|
|
562
564
|
|
|
563
|
-
⚠ **Read §5 first. A fifth hook verb has no green path today.**
|
|
564
|
-
|
|
565
565
|
The mechanical part: implement `cmd<Verb>` in `js/hosts/hooks.mjs`; wire the command string in
|
|
566
|
-
`claudeHookGroups` (`js/hosts/settings.mjs
|
|
567
|
-
shape); add the entry to `bin/geneseed-hook.mjs
|
|
568
|
-
a row to `js/cli-table.json` with a help string over 20 characters.
|
|
566
|
+
`claudeHookGroups` (`js/hosts/settings.mjs`, spelled `` `${run} <verb> …` `` — the gate scrapes that
|
|
567
|
+
shape); add the entry to `VERBS` in `bin/geneseed-hook.mjs` with **exactly two-space indent**; add
|
|
568
|
+
a row to `js/cli-table.json` with a help string over 20 characters. Then give the verb an absolute
|
|
569
|
+
unit gate, or name it in `NATIVE` (`tests/unit/hook_cli.test.mjs`), which holds a verb to the
|
|
570
|
+
structural rules instead; the reverse check refuses a `NATIVE` name no entry point carries.
|
|
569
571
|
|
|
570
572
|
### 4c — A documentation page
|
|
571
573
|
|
|
@@ -604,6 +606,54 @@ the page renders, wrong, with nothing red.
|
|
|
604
606
|
|
|
605
607
|
---
|
|
606
608
|
|
|
609
|
+
### 4d — A host
|
|
610
|
+
|
|
611
|
+
**A host is not one row.** `HOSTS` (`js/hosts/hosts.mjs`) is the table two maps are derived
|
|
612
|
+
from (`EMIT_HOST_SCOPE` and `EMIT_FOR` in `js/hosts/installs.mjs`, and `CLAUDE_STYLE`). Every
|
|
613
|
+
other site below is typed by hand. `tests/unit/host_tables.test.mjs` fails for the tables marked
|
|
614
|
+
*(pinned)*; the rest have no gate, which is why this list exists.
|
|
615
|
+
|
|
616
|
+
Decide first: is the host **Claude-shaped** (a settings file that runs hook commands, a root
|
|
617
|
+
instruction file, `SKILL.md` skills) or does it need its own engine, as OpenCode does? A
|
|
618
|
+
Claude-shaped host rides `js/build/emit-claude.mjs`; anything else is a new emitter and a much
|
|
619
|
+
larger change than this list.
|
|
620
|
+
|
|
621
|
+
1. `HOSTS` in `js/hosts/hosts.mjs`: the row (`host`, `family`, `configDir`, `projectMarker`,
|
|
622
|
+
`agentFile`, `catalog`), a `<host>ConfigDir()` beside the others, and `CARRIERS` /
|
|
623
|
+
`carriersFor` if the root file sits somewhere new. Set `catalog.agents` only for what you
|
|
624
|
+
have seen the host list to the model by itself.
|
|
625
|
+
2. `EMITS` in `js/build/args.mjs` *(pinned)*: `<host>` and `<host>-global`.
|
|
626
|
+
3. `CLAUDE_SHAPED` and the two dispatch tables under it in `js/build/driver.mjs`: one row per
|
|
627
|
+
scope, with the summary line the emit prints. Name the settings file by its real path.
|
|
628
|
+
4. `claudeHookGroups` in `js/hosts/settings.mjs`: the hook groups in the host's own events and
|
|
629
|
+
verdict dialect, and `--host <id>` on each command. A host that cannot ask (Bob) needs its
|
|
630
|
+
block set decided in `BLOCK_RULES` (`js/hosts/hooks.mjs`).
|
|
631
|
+
5. `js/hosts/native.mjs`: the agent and skill frontmatter dialect, and how a user-only skill
|
|
632
|
+
is hidden from the model.
|
|
633
|
+
6. The gate-config markers: `GATE_CONFIG_MARKERS` in `js/hosts/hooks.mjs` *(pinned)* and its
|
|
634
|
+
hand copy in `adapters/opencode/plugins/geneseed-guard.js`, which leaves out `.opencode`.
|
|
635
|
+
A write under the new host's project layer can switch a gate off.
|
|
636
|
+
7. `NATIVE_ROOT` in `js/hosts/hooks-context.mjs` *(pinned)*: the root file the host loads by
|
|
637
|
+
itself, so the context hook does not inject it a second time.
|
|
638
|
+
8. `mcpConfigFor` in `js/hosts/mcp.mjs` *(pinned)*: where the host reads MCP servers from.
|
|
639
|
+
9. `PROBED_VERB` and `probeShell` in `js/inspect/checks-probe.mjs` *(pinned)*: which verb
|
|
640
|
+
refuses on this host, under which shell, and `probesFor` if the host sends its own payload
|
|
641
|
+
shapes.
|
|
642
|
+
10. `HOST_LABELS` in `js/inspect/checks-repo.mjs` *(pinned)*, then a column in
|
|
643
|
+
`docs/concepts/host-matrix.md` and `docs/concepts/enforcement-table.md` (`geneseed doctor`
|
|
644
|
+
fails without them), and a row in `## What is verified` saying how the host was checked.
|
|
645
|
+
11. `DOC_HOSTS` in `js/web/docs.mjs` *(pinned)*: the Docs selector's entry and family.
|
|
646
|
+
12. The setup menu, `js/maintain/setup.mjs`: `EMIT_OPTIONS` *(pinned)*, appended after the
|
|
647
|
+
last entry because the menu is answered by number; the host's display name, and its row in
|
|
648
|
+
the "is it installed" detection table.
|
|
649
|
+
13. `js/inspect/cost.mjs` (`userOnlyTest`, `catalogueChars`), `js/inspect/excludes.mjs` and
|
|
650
|
+
`js/inspect/status.mjs`: each branches on the host id.
|
|
651
|
+
14. `tests/host_canary.mjs`: a `HOSTS` entry if the host is on npm. If it is not, say so in
|
|
652
|
+
the docblock and in `## What is verified`, and write the by-hand steps into
|
|
653
|
+
`docs/guides/verify.md`. `GENESEED_HOOK_TAP` records what the host really sends.
|
|
654
|
+
15. `tests/golden.mjs`: the emit cells. `adapters/<host>/README.md`, a
|
|
655
|
+
`docs/guides/install-<host>.md`, and the README's matrix.
|
|
656
|
+
|
|
607
657
|
## 4bis — Adding a RUNTIME DEPENDENCY
|
|
608
658
|
|
|
609
659
|
**Short answer: you vendor it, or you do not add it.** A dependency arrives as tracked source under
|
|
@@ -653,41 +703,16 @@ specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the
|
|
|
653
703
|
exception above. The invariant already held; it had simply never been written down. A library that
|
|
654
704
|
would delete fewer lines than its vendored source adds is not a saving.
|
|
655
705
|
|
|
656
|
-
## 5 —
|
|
657
|
-
|
|
658
|
-
These are not checklist items. They are structural, and each one should be settled *before* the
|
|
659
|
-
change that needs it, not during.
|
|
660
|
-
|
|
661
|
-
### 5.1 ✅ A fifth hook verb — resolved 2026-08-19
|
|
662
|
-
|
|
663
|
-
**This was a hard blocker and it is now open.** Recorded here because the shape of the problem
|
|
664
|
-
recurs: any gate whose expected value lives in an artifact nothing can re-make will eventually
|
|
665
|
-
stop a legitimate change, and the fix is never to delete the artifact.
|
|
666
|
-
|
|
667
|
-
`tests/unit/hook_cli.test.mjs` asserted a strict equality between the hook verbs the frozen
|
|
668
|
-
matrix covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test
|
|
669
|
-
already exempted a named `NATIVE` list; the hook half exempted nothing — so a fifth hook verb
|
|
670
|
-
failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
|
|
671
|
-
correctly forbids deleting cells to pass.
|
|
672
|
-
|
|
673
|
-
`NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
|
|
674
|
-
than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
|
|
675
|
-
carries — so a name that stops meaning anything fails rather than sitting there.
|
|
676
|
-
|
|
677
|
-
**To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
|
|
678
|
-
`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
|
|
679
|
-
absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
|
|
680
|
-
to stay in step; there is one copy now, so there is nothing to keep in step.
|
|
706
|
+
## 5 — Rules that cost something to learn
|
|
681
707
|
|
|
682
|
-
|
|
708
|
+
These are not checklist items. The numbers are kept because code cites §5.3; §5.1 (the hook-verb
|
|
709
|
+
gate, now in §4b) was settled, and the history of all four is in [design history](design-history.md).
|
|
683
710
|
|
|
684
|
-
|
|
685
|
-
be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
|
|
686
|
-
red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
|
|
687
|
-
cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
|
|
711
|
+
### 5.2 Theme text is free to edit
|
|
688
712
|
|
|
689
|
-
|
|
690
|
-
|
|
713
|
+
Theme text is held only by `doctor --all` — key presence, cross-theme parity, and no unresolved
|
|
714
|
+
tokens — which is a claim about structure, not wording. Restyle freely. What still bites is
|
|
715
|
+
`LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme detection and nothing checks it.
|
|
691
716
|
|
|
692
717
|
### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
|
|
693
718
|
|
|
@@ -727,24 +752,14 @@ remains the cheapest thing to run.
|
|
|
727
752
|
Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
|
|
728
753
|
stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
|
|
729
754
|
|
|
730
|
-
### 5.4
|
|
755
|
+
### 5.4 Expected values are written out
|
|
731
756
|
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
and a change that moved a recorded byte left only two honest options — revert it, or argue in
|
|
735
|
-
writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
|
|
736
|
-
blocks a change, move the logic to the nearest caller that is not frozen*.
|
|
737
|
-
|
|
738
|
-
**None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
|
|
739
|
-
only way back to them), and every expected value now lives in the test file that asserts it, above
|
|
740
|
-
a sentence saying which decision it pins. The rule is correspondingly ordinary:
|
|
757
|
+
Every expected value lives in the test file that asserts it, above a sentence saying which
|
|
758
|
+
decision it pins. There is no snapshot directory and no `--record`, so a red test is a step:
|
|
741
759
|
|
|
742
760
|
> **Change the expectation and the sentence that explains it in the same commit, and say why in
|
|
743
761
|
> the message.**
|
|
744
762
|
|
|
745
|
-
A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
|
|
746
|
-
the cost that keeps the tables honest, and far cheaper than the one it replaced.
|
|
747
|
-
|
|
748
763
|
The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
|
|
749
764
|
text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
|
|
750
765
|
`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
|
|
@@ -770,75 +785,24 @@ only, at best, on its presence.
|
|
|
770
785
|
| Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
|
|
771
786
|
| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
|
|
772
787
|
| `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
|
|
773
|
-
| `adapters/claude-code/settings.json` | — | nothing compares it to what the emitter writes; **it is already divergent** |
|
|
774
|
-
| `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
|
|
775
788
|
| The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs` (`const CEILING`) | a hand-transcribed measurement |
|
|
776
|
-
| Stale docblock counts | `js/build/themes.mjs:62` ("137 values" → 140), `js/build/render.mjs:116` ("145 tokens" → 148) | nothing |
|
|
777
789
|
|
|
778
790
|
---
|
|
779
791
|
|
|
780
|
-
## 7 —
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
should have caught it either did not cover that file — or was itself the frozen copy of a wrong
|
|
786
|
-
answer.
|
|
787
|
-
|
|
788
|
-
**Fixed.**
|
|
789
|
-
|
|
790
|
-
1. **`DESIGN.md` taught the deleted Python build.** Its header promises *"the spec behind the
|
|
791
|
-
harness — read this before changing structure"*, and under it sat the six-edit checklist for
|
|
792
|
-
adding a Law, naming a deleted generator, `rituals/_harness_tui.py` for `LAW_CLASS`, and an
|
|
793
|
-
invocation of a program that no longer exists. Worse, `tests/unit/no_python.test.mjs` exempted
|
|
794
|
-
the file as a *historical record* — so the gate that hunts pointers-to-nothing was looking away
|
|
795
|
-
from the one document most likely to hold one. **Split**: the 190-line standing contract keeps
|
|
796
|
-
the name and is now scanned; the 1,290-line port narrative moved to
|
|
797
|
-
[design-history.md](design-history.md), which is exempt on the merits, and its dead links were
|
|
798
|
-
repaired because a link is a pointer whatever the prose around it says.
|
|
799
|
-
2. **`doctor` printed a command that errors.** The theme-parity tip named
|
|
800
|
-
`./geneseed build --sync-themes`; `cmdBuild` forwards `--theme` and nothing else. The comment
|
|
801
|
-
above the tip argued that spelling on a premise the port had quietly stopped satisfying. It now
|
|
802
|
-
names `geneseed-build --sync-themes`, which is what README and SETUP said all along.
|
|
803
|
-
3. **User-facing output named a program that does not exist.** `tui` and `uninstall` told users to
|
|
804
|
-
run `harness setup` / `harness uninstall` — the reference's name, dropped in P0. Five sites.
|
|
805
|
-
One of them was **pinned verbatim by a test**, so a gate was holding the wrong string in place;
|
|
806
|
-
that assertion is now a property — every backticked command a refusal offers must be a verb
|
|
807
|
-
`js/cli-table.json` declares — which is strictly stronger and fires on the next rename too.
|
|
808
|
-
4. **The `tui` help promised a "full-screen curses control panel"** for a verb that returns 1 on
|
|
809
|
-
every path. `docs/limits.md` listed this as permanently unfixable, on the grounds that the help
|
|
810
|
-
corpus is frozen — but `formatHelp` never reads `cmd.help`, so it was an ordinary edit all
|
|
811
|
-
along. The limits row went with the fix.
|
|
812
|
-
5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
|
|
813
|
-
tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
|
|
814
|
-
named as `cli`, which was removed).
|
|
815
|
-
6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
|
|
816
|
-
`choices` before anything renders, which is why its own refusal read as an unreachable nicety.
|
|
817
|
-
It is not in `choicesFor`; that refusal is the only one there is, on every path.
|
|
818
|
-
7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
|
|
819
|
-
the corpora — three test files justified their own design by pointing at a gate that is gone.
|
|
820
|
-
Plus a skip message naming a `record-corpus` CI job that no longer exists.
|
|
821
|
-
8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
|
|
822
|
-
URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
|
|
823
|
-
`geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
|
|
824
|
-
9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
|
|
825
|
-
the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
|
|
826
|
-
a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
|
|
827
|
-
there is one file.
|
|
828
|
-
|
|
829
|
-
**Still open.**
|
|
830
|
-
|
|
831
|
-
- **`adapters/claude-code/settings.json` is divergent documentation.** It writes
|
|
832
|
-
`node bin/geneseed-hook.mjs <verb>` on seven lines, including one the emitter does not produce
|
|
833
|
-
at all, and carries none of the flags `claudeHookGroups` emits. Nothing compares the two; the
|
|
834
|
-
only reference to it anywhere is the error message that sends users to it. Either gate it
|
|
835
|
-
against the emitter, or delete it.
|
|
792
|
+
## 7 — Still open
|
|
793
|
+
|
|
794
|
+
Each is small, and each costs a contributor a wrong turn until it is done. What was found and
|
|
795
|
+
fixed here before is recorded in [design history](design-history.md).
|
|
796
|
+
|
|
836
797
|
- **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
|
|
837
798
|
extractability; this one's parity test was retired. Reformat the declaration in
|
|
838
799
|
`geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
|
|
839
800
|
- **The fenced-command gate skips the maintainer docs.** `tests/unit/docs.test.mjs` validates
|
|
840
801
|
every `geneseed <verb> <flags>` line against `js/cli-table.json` in `README.md`, `SHIPPED.md`
|
|
841
802
|
and the user docs tree — not in `DESIGN.md` or the `docs/*.md` maintainer pages.
|
|
803
|
+
- **No `verify` script.** The root `package.json` has `lint` and `typecheck`; the rest of what CI
|
|
804
|
+
runs is still reassembled by hand from §1. A script chaining lint, typecheck, the suite and
|
|
805
|
+
doctor would make §1 executable rather than descriptive.
|
|
842
806
|
|
|
843
807
|
---
|
|
844
808
|
|
|
@@ -862,18 +826,16 @@ gh workflow run publish.yml -f dry_run=true
|
|
|
862
826
|
|
|
863
827
|
Two structural facts worth carrying:
|
|
864
828
|
|
|
865
|
-
- **`publish.yml`
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
829
|
+
- **`publish.yml` runs Node 24 and `npm@11`**, because trusted publishing requires them. Toolchain
|
|
830
|
+
defaults that differ from Node 22's broke the release twice: `npm pack --json` changed its
|
|
831
|
+
container between majors, and Node 24's default test reporter made the count gate read zero on
|
|
832
|
+
a green suite. `ci.yml` now meets both before a release does — a `validate` leg on Node 24, the
|
|
833
|
+
packaging suite re-run under `npm@11`, and the TAP reporter pinned in both workflows.
|
|
870
834
|
- **Renaming `publish.yml` breaks publishing silently** — npm keys the trusted publisher on the
|
|
871
835
|
filename.
|
|
872
836
|
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
Node 24 at all**, so the release still executes a runtime nothing exercises — and `publish.yml`
|
|
876
|
-
never runs `tests/golden.mjs`, so the two self-comparisons are absent from the release path.
|
|
837
|
+
`publish.yml` never runs `tests/golden.mjs`, so the two self-comparisons are absent from the
|
|
838
|
+
release path; they run only in `ci.yml`'s `node-cells`.
|
|
877
839
|
|
|
878
840
|
A sweep-and-replace version bump must not touch `registry.json`'s per-entity `"version": "1.0.0"`
|
|
879
841
|
rows, nor `web/package.json`.
|
|
@@ -913,31 +875,3 @@ port is therefore stopped with `--port`, never with a bare `web stop` — that o
|
|
|
913
875
|
the record names, usually the live console on 4747.
|
|
914
876
|
|
|
915
877
|
When the preferred port is taken, `clearPort` (`js/web/daemon.mjs`) asks `/api/ping` who holds it. The ping carries `rootId()`, a hash of the checkout root. A holder with our root is asked for a nonce (`/api/ping?shutdown=1`), then asked to shut down on `/api/shutdown` with `X-Geneseed-Nonce` and `X-Geneseed-Secret`: a MAC of the port and the nonce under the install secret in `.geneseed-web-secret` (32 random bytes, created once next to the daemon record; mode 0600 on POSIX, the folder's inherited ACL on Windows). The console accepts each nonce it minted once, within 30 seconds, so a proof that an impostor collects is good nowhere later. The secret itself is never sent, and no pid is ever signalled, so a listener that only claims our root cannot cause harm. A holder of our root that answers `nonce: null` holds no secret (a foreground console, or a daemon that could not read its secret), and one that answers no `nonce` predates the handshake; both are named and left alone. Any other answer is left alone and named. A console older than the field has no root, so it is never assumed to be ours.
|
|
916
|
-
|
|
917
|
-
---
|
|
918
|
-
|
|
919
|
-
## 10 — What to settle before the next wave
|
|
920
|
-
|
|
921
|
-
Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
|
|
922
|
-
stop a change today, and all of them cost a contributor a wrong turn until they are done.
|
|
923
|
-
|
|
924
|
-
1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
|
|
925
|
-
Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
|
|
926
|
-
`DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
|
|
927
|
-
reach. It keeps catching them.
|
|
928
|
-
2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
|
|
929
|
-
CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
|
|
930
|
-
Either answer is fine; discovering the question mid-feature is not.
|
|
931
|
-
3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
|
|
932
|
-
is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
|
|
933
|
-
and today nothing warns you before the snapshot goes red.
|
|
934
|
-
4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
|
|
935
|
-
`adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
|
|
936
|
-
5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
|
|
937
|
-
config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
|
|
938
|
-
chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
|
|
939
|
-
|
|
940
|
-
The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
|
|
941
|
-
deliberately keeps tables and prose hand-written and gates them from the source tree. The
|
|
942
|
-
recommendations above are about the places where the gate is missing, wrong, or pointed at a file
|
|
943
|
-
that no longer exists.
|
|
@@ -13,9 +13,9 @@ geneseed build --emit bob-global # ~/.bob
|
|
|
13
13
|
geneseed build --emit bob --out /path/to/repo --root /path/to/repo # one repo
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2
|
|
16
|
+
Bob is shaped like Claude Code, so it gets the same agents and skills. A read-only agent is limited with Bob's own `groups:` key, because Bob ignores Claude's `disallowedTools`. Per repo, the preamble goes into a root `AGENTS.md` and the rest into `.bob/`. Globally, everything goes under `~/.bob` (`$BOB_CONFIG_DIR` moves it), and the preamble rides `rules/geneseed.md`, because Bob does not auto-load a global `AGENTS.md`. Bob's hooks refuse an action with exit code 2. Bob has no `SubagentStop` event; Bob 2.2.3 does have `PreCompact` and `PostCompact`, which Geneseed does not wire.
|
|
17
17
|
|
|
18
|
-
Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request.
|
|
18
|
+
Both scopes open Bob's carrier with a short first-reply override, so the theme's readiness line (for example "🧬 Gene-seed implanted…") starts the first reply. Without it, Bob's own greeting outranked the instruction lower in the file. A bare greeting such as "hi" still gets Bob's fixed welcome; the line appears on the first real request. For what was checked against Bob itself, and when, see [What is verified](../concepts/host-matrix.md#what-is-verified); [Verify it works](verify.md) has the steps to check your own install by hand.
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
@@ -18,7 +18,7 @@ geneseed build --emit openclaude --out /path/to/repo --root /path/to/repo # one
|
|
|
18
18
|
- Per repo, the preamble is written to `.openclaude/CLAUDE.md` rather than a root file, and the hooks go into `.openclaude/settings.local.json`.
|
|
19
19
|
- `$OPENCLAUDE_CONFIG_DIR` moves the global directory (default `~/.openclaude`).
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
For what was checked against OpenClaude itself, see [What is verified](../concepts/host-matrix.md#what-is-verified).
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
@@ -43,7 +43,19 @@ Run the analysis-to-build factory on this request: add CSV export to the report
|
|
|
43
43
|
On Claude Code, `/factory` with the same words is the explicit form: it loads the `factory`
|
|
44
44
|
skill directly. The console's **Factories** page shows the request for each factory, ready to copy.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
To pick from the issues that wait, ask for the queue:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
Show me the factory queue
|
|
50
|
+
Run the factory queue with the label ready-to-build
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The agent lists the open issues that carry the label `factory` (or the label you name), with
|
|
54
|
+
`gh issue list` or `glab issue list`. Pick one, several or all. Several picks run one after the
|
|
55
|
+
other, in your order, each in its own worktree, and each ends with its own merge question. A run
|
|
56
|
+
that waits for you holds the ones after it.
|
|
57
|
+
|
|
58
|
+
For each run, the agent then:
|
|
47
59
|
|
|
48
60
|
1. Creates a worktree on a new branch, `git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, and works from there. Your own checkout is not touched. The slug never holds the word `git`, `commit` or `push`: `factory init` refuses it.
|
|
49
61
|
2. Runs `geneseed factory init --title … --requirement … --factory bug-report-to-fix --input <issue or text>`. This writes `FACTORY.md` at the worktree root and registers the run.
|
|
@@ -95,6 +107,7 @@ run the analysis-to-build factory on docs/analysis/export-csv.md
|
|
|
95
107
|
| Moment | What you decide |
|
|
96
108
|
| --- | --- |
|
|
97
109
|
| `intake` reports `needs-info` | The work item leaves a question only you can answer. The agent shows its numbered questions, each with the assumption it would make. Answer them (`amend`, three times at most), say `ok` to go on with the assumptions, or `no` to stop. |
|
|
110
|
+
| `intake` reports `reject` | The item should not be built: it is already done, a duplicate, or against a rule the project states. The agent shows the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` with your reason runs `intake` again to build it, `no` stops too. Nothing is posted on the issue. |
|
|
98
111
|
| `checks` reports `error` | Every check passed, but the branch changed a locked path: the done list, CI config, or a factory, loop or brick. `ok` lets it through (the run report names it), `no` stops. Or the finding starts `environment:`: the fetch failed, no default branch was found, or a check timed out or its tool is missing. The loop cannot fix that: fix the environment and answer `amend` to run the checks again, or `no` to stop; `ok` goes on without them. |
|
|
99
112
|
| `checks` reports `none` | The base branch has no done list, or an empty one. The agent shows the one it proposes (or says no manifest gave one). On your yes it commits the file in a temporary worktree on its own branch, `geneseed/done-list-<slug>`, pushes that branch and opens a PR to the base branch (each step asks). You merge that PR. Once the file is on the base, `ok` runs the checks again. |
|
|
100
113
|
| The `spec` gate (`analysis-to-build`) | The task list: `ok` starts the first task, `amend` revises the spec, `no` stops the run. The spec commit after your `ok` asks too. |
|
|
@@ -109,7 +122,7 @@ Red CI does not stop for you: it sends the work back to the run's loop (`bugfix`
|
|
|
109
122
|
|
|
110
123
|
## When it ends
|
|
111
124
|
|
|
112
|
-
On success the agent reports the PR (merged on your yes, or open), every stage with its outcome, each rework and why, and the run report at `.geneseed/factory-runs/<slug>.md`. On a stop it reports the reason and still writes the run report; the branch and `FACTORY.md` stay as they were, so you can see where it stopped. After a crash, ask the agent to resume: it runs `geneseed factory next` in the worktree.
|
|
125
|
+
On success the agent reports the PR (merged on your yes, or open), every stage with its outcome, each rework and why, and the run report at `.geneseed/factory-runs/<slug>.md`. The run report has a table with one row per stage: its runs, its reworks, its work time and its tokens, where the host reports them. It also gives the time the run waited for you. To read the same numbers while a run is going, run `geneseed factory report` in its worktree, or open the console's **Factories › Active** board: the runs that wait for you come first, and a card opens the run's timeline. On a stop it reports the reason and still writes the run report; the branch and `FACTORY.md` stay as they were, so you can see where it stopped. After a crash, ask the agent to resume: it runs `geneseed factory next` in the worktree.
|
|
113
126
|
|
|
114
127
|
---
|
|
115
128
|
|