geneseed 5.1.1 → 5.3.0
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 +52 -0
- package/README.md +2 -2
- package/SHIPPED.md +1 -1
- package/adapters/opencode/README.md +4 -3
- package/adapters/opencode/plugins/geneseed-context.js +82 -29
- package/adapters/opencode/plugins/geneseed-guard.js +118 -8
- package/bin/geneseed-cli.mjs +64 -16
- package/bin/geneseed-hook.mjs +37 -3
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/factories.md +40 -6
- package/docs/concepts/footprint.md +1 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/host-matrix.md +1 -1
- 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 +140 -0
- package/docs/extending.md +54 -162
- package/docs/guides/run-a-factory.md +15 -2
- package/docs/guides/setup-doctrines.md +1 -1
- package/docs/guides/upgrade.md +2 -2
- package/docs/reference/factory-actions.md +6 -5
- package/docs/reference/troubleshoot-update.md +1 -1
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/web-ui.md +16 -3
- package/harness.config.json +1 -1
- package/js/README.md +10 -7
- package/js/build/args.mjs +10 -4
- package/js/build/bundle.mjs +122 -23
- package/js/build/driver.mjs +32 -12
- package/js/build/emit-claude.mjs +2 -1
- package/js/build/emit-common.mjs +2 -2
- package/js/build/emit-opencode.mjs +22 -10
- package/js/build/export.mjs +431 -0
- package/js/build/generate.mjs +3 -0
- package/js/build/render.mjs +44 -24
- package/js/build/source.mjs +6 -1
- package/js/cli-table.json +232 -57
- 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/hooks-context.mjs +26 -1
- package/js/hosts/hooks-done.mjs +8 -2
- package/js/hosts/hooks-prims.mjs +52 -3
- package/js/hosts/hooks.mjs +155 -33
- package/js/hosts/hosts.mjs +2 -4
- package/js/hosts/installs.mjs +28 -0
- package/js/hosts/loss.mjs +25 -3
- package/js/hosts/native.mjs +30 -2
- package/js/hosts/owned.mjs +55 -1
- package/js/hosts/ownership-gate.mjs +5 -5
- package/js/hosts/settings.mjs +83 -33
- package/js/inspect/diff.mjs +16 -1
- package/js/inspect/doctor.mjs +7 -3
- package/js/inspect/excludes.mjs +18 -6
- package/js/inspect/status.mjs +35 -7
- package/js/inspect/validate.mjs +44 -21
- package/js/lib/managed-block.mjs +74 -0
- package/js/maintain/uninstall.mjs +85 -15
- 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 +5 -0
- package/js/web/api.mjs +32 -11
- 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-CqJiquEq.js +1 -0
- package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
- package/web/dist/assets/{Bonsai-hiG_gGNU.js → Bonsai-Bfpb6W-1.js} +1 -1
- package/web/dist/assets/{CopyButton-DUIUfNp6.js → CopyButton-ByIntFtB.js} +1 -1
- package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
- package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
- package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
- package/web/dist/assets/{GreenhouseView-BKxy5apE.js → GreenhouseView-GpBsYn50.js} +1 -1
- package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
- package/web/dist/assets/{JournalView-ChFitHjo.js → JournalView-iLuLrOxE.js} +1 -1
- package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
- package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
- package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
- package/web/dist/assets/Library-B4K-1iNF.js +3 -0
- package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
- package/web/dist/assets/{OperatorHudView-BO0aIKPL.js → OperatorHudView-BAXwCEvY.js} +1 -1
- package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
- package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
- package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
- package/web/dist/assets/index-CsAZq0BQ.css +1 -0
- package/web/dist/assets/index-How7SzDZ.js +6 -0
- package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
- package/web/dist/assets/Activity-CpkBwpu7.js +0 -1
- package/web/dist/assets/ActivityDetail-DTPziZWM.js +0 -1
- package/web/dist/assets/Dashboard-Dnw6EyX7.js +0 -2
- package/web/dist/assets/Docs-BEET_l16.js +0 -5
- package/web/dist/assets/Factories-D6KXkfWw.js +0 -1
- package/web/dist/assets/Installs-CnFVlVD0.js +0 -3
- package/web/dist/assets/Kits-CcR-OlwQ.js +0 -1
- package/web/dist/assets/Laws-B1s5idOg.js +0 -4
- package/web/dist/assets/LibRows-BZgdbI1l.js +0 -1
- package/web/dist/assets/Library-x6TkkEVF.js +0 -3
- package/web/dist/assets/Loops-BH93KKxn.js +0 -2
- package/web/dist/assets/Personal-CE_0Vhh0.js +0 -2
- package/web/dist/assets/Settings-CbpZvVN_.js +0 -1
- package/web/dist/assets/Tabs-C2oW7oEj.js +0 -1
- package/web/dist/assets/index-BQwOmbor.js +0 -6
- package/web/dist/assets/index-CuIop_pO.css +0 -1
- package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
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.
|
|
@@ -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
|
|
|
@@ -653,41 +655,16 @@ specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the
|
|
|
653
655
|
exception above. The invariant already held; it had simply never been written down. A library that
|
|
654
656
|
would delete fewer lines than its vendored source adds is not a saving.
|
|
655
657
|
|
|
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.
|
|
658
|
+
## 5 — Rules that cost something to learn
|
|
681
659
|
|
|
682
|
-
|
|
660
|
+
These are not checklist items. The numbers are kept because code cites §5.3; §5.1 (the hook-verb
|
|
661
|
+
gate, now in §4b) was settled, and the history of all four is in [design history](design-history.md).
|
|
683
662
|
|
|
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.
|
|
663
|
+
### 5.2 Theme text is free to edit
|
|
688
664
|
|
|
689
|
-
|
|
690
|
-
|
|
665
|
+
Theme text is held only by `doctor --all` — key presence, cross-theme parity, and no unresolved
|
|
666
|
+
tokens — which is a claim about structure, not wording. Restyle freely. What still bites is
|
|
667
|
+
`LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme detection and nothing checks it.
|
|
691
668
|
|
|
692
669
|
### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
|
|
693
670
|
|
|
@@ -727,24 +704,14 @@ remains the cheapest thing to run.
|
|
|
727
704
|
Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
|
|
728
705
|
stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
|
|
729
706
|
|
|
730
|
-
### 5.4
|
|
707
|
+
### 5.4 Expected values are written out
|
|
731
708
|
|
|
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:
|
|
709
|
+
Every expected value lives in the test file that asserts it, above a sentence saying which
|
|
710
|
+
decision it pins. There is no snapshot directory and no `--record`, so a red test is a step:
|
|
741
711
|
|
|
742
712
|
> **Change the expectation and the sentence that explains it in the same commit, and say why in
|
|
743
713
|
> the message.**
|
|
744
714
|
|
|
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
715
|
The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
|
|
749
716
|
text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
|
|
750
717
|
`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
|
|
@@ -770,75 +737,30 @@ only, at best, on its presence.
|
|
|
770
737
|
| Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
|
|
771
738
|
| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
|
|
772
739
|
| `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
|
|
773
|
-
| `adapters/claude-code/settings.json`
|
|
774
|
-
| `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
|
|
740
|
+
| The hand-wiring copy of the Claude hooks | `adapters/claude-code/settings.json` — it ships (`files[]` takes `adapters/` whole), and `js/hosts/settings.mjs` sends a user whose `settings.json` has comments to it | nothing compares it with what `claudeHookGroups` emits (§7) |
|
|
775
741
|
| 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
742
|
|
|
778
743
|
---
|
|
779
744
|
|
|
780
|
-
## 7 —
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
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.
|
|
745
|
+
## 7 — Still open
|
|
746
|
+
|
|
747
|
+
Each is small, and each costs a contributor a wrong turn until it is done. What was found and
|
|
748
|
+
fixed here before is recorded in [design history](design-history.md).
|
|
749
|
+
|
|
750
|
+
- **`adapters/claude-code/settings.json` has no gate.** It ships, and the refusal for a commented
|
|
751
|
+
`settings.json` tells users to copy hooks from it. It writes `node bin/geneseed-hook.mjs <verb>`,
|
|
752
|
+
a path that resolves only from a checkout root, and none of the `--no-*-gate` flags
|
|
753
|
+
`claudeHookGroups` emits. Nothing compares the two. Either gate it against the emitter, or point
|
|
754
|
+
the refusal at an emitted file and delete it.
|
|
836
755
|
- **`AGENT_LESSON_PROMPT` has no drift gate.** Its sibling `LEARN_PROMPT_HEAD` is checked for
|
|
837
756
|
extractability; this one's parity test was retired. Reformat the declaration in
|
|
838
757
|
`geneseed-learn.js` and the per-agent lesson prompt silently degrades to a two-line fallback.
|
|
839
758
|
- **The fenced-command gate skips the maintainer docs.** `tests/unit/docs.test.mjs` validates
|
|
840
759
|
every `geneseed <verb> <flags>` line against `js/cli-table.json` in `README.md`, `SHIPPED.md`
|
|
841
760
|
and the user docs tree — not in `DESIGN.md` or the `docs/*.md` maintainer pages.
|
|
761
|
+
- **No `verify` script.** The root `package.json` has `lint` and `typecheck`; the rest of what CI
|
|
762
|
+
runs is still reassembled by hand from §1. A script chaining lint, typecheck, the suite and
|
|
763
|
+
doctor would make §1 executable rather than descriptive.
|
|
842
764
|
|
|
843
765
|
---
|
|
844
766
|
|
|
@@ -862,18 +784,16 @@ gh workflow run publish.yml -f dry_run=true
|
|
|
862
784
|
|
|
863
785
|
Two structural facts worth carrying:
|
|
864
786
|
|
|
865
|
-
- **`publish.yml`
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
787
|
+
- **`publish.yml` runs Node 24 and `npm@11`**, because trusted publishing requires them. Toolchain
|
|
788
|
+
defaults that differ from Node 22's broke the release twice: `npm pack --json` changed its
|
|
789
|
+
container between majors, and Node 24's default test reporter made the count gate read zero on
|
|
790
|
+
a green suite. `ci.yml` now meets both before a release does — a `validate` leg on Node 24, the
|
|
791
|
+
packaging suite re-run under `npm@11`, and the TAP reporter pinned in both workflows.
|
|
870
792
|
- **Renaming `publish.yml` breaks publishing silently** — npm keys the trusted publisher on the
|
|
871
793
|
filename.
|
|
872
794
|
|
|
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.
|
|
795
|
+
`publish.yml` never runs `tests/golden.mjs`, so the two self-comparisons are absent from the
|
|
796
|
+
release path; they run only in `ci.yml`'s `node-cells`.
|
|
877
797
|
|
|
878
798
|
A sweep-and-replace version bump must not touch `registry.json`'s per-entity `"version": "1.0.0"`
|
|
879
799
|
rows, nor `web/package.json`.
|
|
@@ -913,31 +833,3 @@ port is therefore stopped with `--port`, never with a bare `web stop` — that o
|
|
|
913
833
|
the record names, usually the live console on 4747.
|
|
914
834
|
|
|
915
835
|
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.
|
|
@@ -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
|
|
|
@@ -32,7 +32,7 @@ The packs always load in the same order (craft, rigor, ops, process, comms), wha
|
|
|
32
32
|
**Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
|
|
33
33
|
|
|
34
34
|
- On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
|
|
35
|
-
- On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, entries
|
|
35
|
+
- On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, the entries Geneseed recorded adding are removed. Entries you typed, and those on an install made before 5.2.0, are left in place and reported; build once with `--prune-gates` to remove the second kind.
|
|
36
36
|
|
|
37
37
|
The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
|
|
38
38
|
|
package/docs/guides/upgrade.md
CHANGED
|
@@ -19,7 +19,7 @@ geneseed rebuild-all # rebuild every install with its own settings
|
|
|
19
19
|
|
|
20
20
|
`rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
|
|
21
21
|
|
|
22
|
-
`upgrade
|
|
22
|
+
`upgrade` and `update` (and the deprecated `bootstrap`) are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
|
|
23
23
|
|
|
24
24
|
## Installed from a clone
|
|
25
25
|
|
|
@@ -36,7 +36,7 @@ geneseed upgrade imperial # the same, switching the theme
|
|
|
36
36
|
|
|
37
37
|
If the `doctor` pass cannot finish, for example on a busy machine after 300 seconds, `upgrade` keeps the pull, rebuilds nothing, and exits 1. The pulled source is unchecked, not bad. Run `geneseed upgrade` again: it runs `doctor` first, rebuilds on a pass, and rolls back to the last checked commit on a failure.
|
|
38
38
|
|
|
39
|
-
A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme. `
|
|
39
|
+
A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme (as an argument or `--theme`). `upgrade --setup` does the same and then opens the setup wizard; `bootstrap`, its old name, still works for one release and says so.
|
|
40
40
|
|
|
41
41
|
## The Update button in the web console
|
|
42
42
|
|
|
@@ -6,16 +6,17 @@ kind: "concept"
|
|
|
6
6
|
section: "CLI & environment"
|
|
7
7
|
description: "The geneseed factory actions, one line each."
|
|
8
8
|
---
|
|
9
|
-
The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none
|
|
9
|
+
The actions of `geneseed factory`, the state machine that carries one work item through a graph of stages to an open PR. A stage is a brick or a whole loop (`loop:<template>`). A **fork** is a brick that declares a named outcome (one other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`), each outcome with its own edge to its own lane. An edge target or a cycle node may be `$lane`: the stage the run's most recent fork chose. The run state lives in `FACTORY.md` at the worktree root, beside the child loop's `LOOP.md` ([Loop actions](loop-actions.md)). Each action prints one JSON object and exits 1 on a refusal.
|
|
10
10
|
|
|
11
11
|
| action | what it does |
|
|
12
12
|
|---|---|
|
|
13
|
-
| `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error` and `needs-info` may go without one: `error` then
|
|
13
|
+
| `check` | checks every factory in the catalogue, or one factory (`--factory <name or .json file>`): the factory has a name and no stage twice, every stage exists, every outcome has one edge (`error`, `reject` and `needs-info` may go without one: `error` and `reject` then stop the run, and `needs-info` follows the stage's `pass` edge), `$close` is reachable, every cycle is declared with a `max` from 1 to 5, each cycle is entered only at its first stage, and every route back targets the first stage of a cycle that holds its source. `$lane` needs a fork on every path to it, and a fork's own edge never targets it. In those checks, `$lane` stands for every lane of every fork. A factory that still uses the retired `loop:$triaged` stage or `loops` list gets a problem that names the replacement; nothing rewrites the file. An optional `protected` must be a list of non-empty paths. An outcome on which a brick reports environment failures (`checks` `error`, `merge-gate` `none`) never routes to a `loop:` stage or `$lane`: no loop can fix a failed fetch, a missing tool or CI pending at the bound. An optional `review.seats` needs a non-empty list of agents for each of `small`, `medium` and `large`, and `areas`, when present, maps each area to such a list; every seat must name a shipped agent (`review.seats.medium: no agent named <name>`). A project factory overrides a global or shipped one of the same name, and a global one a shipped one: `check` lists each in `overridden`. A file that does not load is a problem that names its level (`factories/<name>.json (project): not JSON`), and it drops the factory of that name from lower levels, so `init` refuses with that problem instead of running another graph |
|
|
14
14
|
| `list` | lists the factories of the three origins (shipped, global, project), with description, category and origin |
|
|
15
|
-
| `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text)
|
|
15
|
+
| `init` | writes a fresh `FACTORY.md` from a factory, under a title, a requirement and an optional `--input` (an issue URL, a file path or pasted text), and stamps the time as the run's `started`. A factory that fails `check` is refused before any stage runs, and so is a run branch `loop/factory-<slug>` whose slug holds the word `git`, `commit` or `push`: the slug lands on lines the git gate reads. Each `init` also registers the run in `factories.json`, beside the loop registry |
|
|
16
16
|
| `next` | returns the next thing to do: run a brick stage, run a loop (with `notes` to start it with, and the `task` when a spec set tasks: the spec's `path`, the task `count` and this task's `index`), answer an `awaiting` gate, or a terminal. A fork stage also gets `lanes`: each outcome it may report, with the stage it leads to. Every stage gets the factory's `rules`, and its `protected` paths when it declares any. Refused while a `LOOP.md` exists that is not `done` or `stopped` (an unreadable one counts as running): the child loop finishes first. On a loop stage, refused while any `LOOP.md` is left: `git rm -f LOOP.md` and commit that removal before `geneseed loop init`. On a loop stage, `next` also records the launch in `FACTORY.md`: the loop template, the HEAD commit and the time. When a later stage routes back to the loop stage that ran the tasks, after its last task passed (a failed `checks`, `review-panel` or `holdout`, or red CI at `merge-gate`), `next` hands out one extra task: the last `index` again, with `extra` set to the stage and outcome that sent it back (`"merge-gate reported fail"`). That lap spends the route's cycle and the transition ceilings like any other, and gives no fresh budget |
|
|
17
|
-
| `record` | records the current stage's outcome and follows its edge. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
|
|
18
|
-
| `decide` | answers a held `gate: human` stage
|
|
17
|
+
| `record` | records the current stage's outcome and follows its edge. The history entry it writes carries the time as `at`. `--tokens <n>` stores on that entry the token count the host reported for the agent that ran the stage: a positive integer written in digits, anything else is refused before the state changes. Leave it out when the host gave no count; nothing estimates one. A loop stage reports `pass` (its loop closed) or `fail` (it stopped), and only after `next` launched it. While its `LOOP.md` is still there, that file must name the stage's template, a `stopped` one admits only `fail`, and a `done` one only `pass`. With no `LOOP.md` left, `pass` and `fail` both need a HEAD that moved since `next`: the loop's close commit, or the commit that removes a stopped loop's `LOOP.md`. That is enough for `fail`. `pass` also needs the loop registry to show a `geneseed loop init` in this worktree after `next`. Without it, `pass` is refused: record it while the `done` `LOOP.md` is still at the root, or report `fail`. The registry does not keep a loop's final status, so a stopped loop whose `LOOP.md` was removed by hand can still pass. `--carry` hands a reason to the next stage; a re-entered loop starts with it as a note. `--carry-file <file>` reads it from a file instead (CRLF folded, trimmed), for free text, which never goes on the command line: the skill writes it with the host's file tool, never the shell, to a file it names uniquely. Every path argument (`--spec`, `--factory <file>`, `--carry-file`, `--note-file`) is relative to the current directory; only `FACTORY.md` is found at the git root. On a fork, the outcome names the lane: the stage its edge reaches is stored as the run's `lane`, and an edge to `$lane` goes there. A route to `$lane` with no lane on record is refused. `--spec <path>` records the run's spec, which must be at `specs/<slug>/spec.md` (any other path is refused before the state changes): the first loop stage recorded after it runs once per numbered item (`1.` or `1)`, indented 3 spaces at most) under its first heading that contains the word `task` or `tasks`, up to the next heading of the same or a higher level (`#`, indented 3 spaces at most, or a setext heading), 20 at most. As in CommonMark, a numbered item indented as far as the text of the task above it is a sub-item, and a fenced block (```` ``` ```` or `~~~`) is skipped whole. Until the first task loop launches (the first loop after a spec is on record; a loop that ran before any spec does not count), each `--spec` sets the count again, so a spec amended at its gate may list more tasks. From that launch the count is frozen: a later `--spec` may keep or lower it, never raise it. After a stage outside a loop, pipe it `git status --porcelain --untracked-files=all` in one command: `git status --porcelain --untracked-files=all | geneseed factory record …`. PowerShell pipes the same way; the CRLF that Windows PowerShell 5.1 adds, and the leading BOM it adds when `$OutputEncoding` is UTF-8, are stripped. The git gate asks on any line that holds the word `git` and the word `commit` or `push`, so a record line whose spec path, carry path or outcome holds `commit` or `push` asks: a false alarm the user can answer yes to. `init` refuses a slug with those words, which removes the commonest case. Plain `--porcelain` shows a new directory as one line (`?? specs/`), so a new spec is refused. The tree must be clean (a `mutate` brick such as a `docs-update` lane commits its change first), with two exceptions: engine files, and the run's spec at `specs/<slug>/spec.md` (the one recorded now, else the one on record). No stdin at all (a terminal) is refused. An empty pipe reads as a clean tree. Refused, as `next` is, while a child loop owns the worktree. Every state action also refuses a `FACTORY.md` that does not parse, or one that holds any of these: counters that are not non-negative integers, a run-wide ceiling above 1200, a gate amend count above 3, a `lane` that no fork of the factory leads to, a current stage, task-owning stage, launched loop or held gate that the factory does not hold, an `awaiting` that does not match the status, an unknown status, a `history` or `cycles` that is not a list, or a factory that no longer passes `check` |
|
|
18
|
+
| `decide` | answers a held `gate: human` stage, and stamps the time on its history entry as `at`: `ok` follows the edge (an edge to `$lane` goes to the lane on record), `no` stops, `amend` re-runs the stage with the `--note` as its carry (three times at most). On `intake`'s `reject`, `ok` accepts the refusal: the edge goes to `$stop`, and the run stops with the reason `intake reported reject`. `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
|
|
19
|
+
| `report` | prints the run's numbers as one JSON object and writes nothing. `stages` lists each stage the run recorded, in the order it first ran, with its `runs`, its `reworks` (an outcome that spent a cycle; a held outcome counts only once you answer `ok`), its `workMs` and its `tokens`. `workMs`, `waitMs`, `tokens` and `transitions` are the run's totals; `waitMs` counts a wait once its gate is answered, and `openWaitMs` is the wait still open while the run is held at a gate (the time now minus that record's time; `null` when no gate is held), and `entries` gives, for each history entry in order, its duration `ms`, whether it is waiting time (`wait`) and whether it is a rework. A duration is an entry's `at` minus the `at` of the entry before it (`started` for the first): work time on a `record` entry, waiting time on a `decide` entry. An entry with no time, as in a `FACTORY.md` written before times were stamped, gives `null`, and so does every total that holds it: never 0. `tokens` adds the counts recorded, and is `null` when none was. There is no cost in money |
|
|
19
20
|
|
|
20
21
|
A route back into a cycle spends the cycle whose first stage is the route's target; past its `max` the run stops. A run stops too after 60 stage transitions, counted again for each spec task the run reaches for the first time, and after 60 transitions per task of the spec (60 without a spec) over the whole run. That run-wide ceiling follows the spec's task count until the first task loop launches (the first spec sets it even after an earlier loop), and never changes after.
|
|
21
22
|
|
|
@@ -26,7 +26,7 @@ The upgrade is a `git pull`, so it first checks the folder. Each refusal says wh
|
|
|
26
26
|
|
|
27
27
|
| What you see | Cause and fix |
|
|
28
28
|
| --- | --- |
|
|
29
|
-
| `geneseed: error:
|
|
29
|
+
| `geneseed: error: unknown command 'sync-self'. See geneseed --help.` | The verb is gone. Run `geneseed upgrade`. |
|
|
30
30
|
| `geneseed: error: unrecognized arguments: imperial` from `upgrade main imperial` | `upgrade` takes only a theme. Run `geneseed upgrade imperial`. |
|
|
31
31
|
| A host's `memory/` folder holds only its seed | Expected: [the fold](../concepts/shared-tier.md#the-fold) moved the facts to `~/.config/geneseed/memory/`. `geneseed memory list` shows them, and the old store is in `archived-memory/<stamp>/`. |
|
|
32
32
|
| `[shared] <host>: … rules to approve` | Those rules wait in `user-rules.draft.md` and still bind from the host file. Ask the agent to review the pending rules; the `rule` skill decides them. |
|
|
@@ -44,7 +44,7 @@ On OpenCode, two mechanisms enforce rules:
|
|
|
44
44
|
- **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `git reflog expire`, `git gc --prune` and a force-push or delete of `main`/`master`, and, when the **process** pack is on, before every commit and push.
|
|
45
45
|
- **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), every other real data loss (the same state-aware decisions as the hook), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through. And in an application repo with no `## Ownership` section in its root `AGENTS.md`, it refuses the session's first write once, so the agent proposes the [ownership](../concepts/ownership.md) setup (off with `mode: off`, a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`, or `--no-ownership-gate`).
|
|
46
46
|
|
|
47
|
-
The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack:
|
|
47
|
+
The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: a rebuild without the pack removes the `git commit*` entry only when Geneseed recorded adding it. An entry you typed, or one from an install made before 5.2.0, stays and is reported; `--prune-gates` removes the second kind.
|
|
48
48
|
|
|
49
49
|
<!--/harness-->
|
|
50
50
|
|
package/docs/web-ui.md
CHANGED
|
@@ -359,7 +359,7 @@ screen the run list stacks above the detail.
|
|
|
359
359
|
grey block, a fork amber, a `loop:` stage a teal box that names its loop (without `loop:`)
|
|
360
360
|
over `whole loop`, or `not in catalogue` when this install lacks it; the ring itself is on the
|
|
361
361
|
Loops page. A fork is what the engine calls one: a brick that declares a named outcome
|
|
362
|
-
(one outside `pass`, `fail`, `error`, `none
|
|
362
|
+
(one outside `pass`, `fail`, `error`, `none`, `needs-info` and `reject`), never a `loop:` stage, however
|
|
363
363
|
many stages its edges reach. The targets of a fork share a row, side by side, each lane labelled with its outcome,
|
|
364
364
|
and join again at the first stage every lane reaches. Each route back (an edge into a cycle's
|
|
365
365
|
first stage, the edge that spends a lap, `$lane` included) is a rail on the left labelled
|
|
@@ -376,13 +376,26 @@ screen the run list stacks above the detail.
|
|
|
376
376
|
factory's rules. It reads `GET /api/factories/catalog` for the install the *Install:* picker
|
|
377
377
|
names. **Active** is every run `geneseed factory init` registered on this machine
|
|
378
378
|
(`GET /api/factories/active`, polled every 5 s, the graph read from each run's `FACTORY.md`),
|
|
379
|
-
|
|
379
|
+
shown as a **board** while no run is selected: three columns of cards, **Waits for you** (a
|
|
380
|
+
held gate, or a `FACTORY.md` that cannot be read), **Running**, and **Ended** (stopped, closed,
|
|
381
|
+
or its `FACTORY.md` gone). A card gives the run's title, its factory, and one line of facts: where it
|
|
382
|
+
stands (a held gate as `stage · outcome`), its task as `i/n`, its work time so far, the wait
|
|
383
|
+
still open at its gate (`waiting 25 min`), and each cycle spent above 0 as `name n/max`. A
|
|
384
|
+
run with no state says why instead. The list beside it groups the runs under the same three
|
|
385
|
+
names, each row with the same facts under its factory, and while a run is open the list's
|
|
386
|
+
header names it by its title. A card opens the run: the reader
|
|
387
|
+
shows the run's stage, transitions, task number, its
|
|
380
388
|
child loop's step and iteration, what it awaits, and its graph with the current stage lit,
|
|
381
389
|
the lane its last fork took (the run's `lane`, else read from its `history`) lit, the child
|
|
382
390
|
loop's node named under the current stage (`at <node>`) and each cycle's laps as `n / max`. A
|
|
383
391
|
run carries its graph but no bricks or loops: the graph borrows those from the catalogue of the
|
|
384
392
|
install the Templates tab's picker names, which the run's project may not share, and the reader
|
|
385
|
-
says which.
|
|
393
|
+
says which. Under the graph, a **timeline** has one row per history entry: the stage, its
|
|
394
|
+
outcome or your answer at a gate, the time it was recorded (UTC), its duration (waiting time on
|
|
395
|
+
an answer) and a rework mark. A held run names its gate's stage, its outcome and the path of
|
|
396
|
+
its note; the console does not read the note. The numbers are the ones `geneseed factory report`
|
|
397
|
+
prints, and a time nobody recorded reads `unknown`. The board changes nothing: you answer a gate
|
|
398
|
+
in the agent's session. No run reports tab: a run's report lives in its own worktree.
|
|
386
399
|
- **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
|
|
387
400
|
per file: the shared one every global install reads, tagged `shared`, and each project
|
|
388
401
|
install's own. Opens rendered; **Edit** is a whole-file editor. The save carries
|
package/harness.config.json
CHANGED
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
"_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
|
|
3
3
|
"theme": "neutral",
|
|
4
4
|
"product": "Geneseed",
|
|
5
|
-
"version": "5.
|
|
5
|
+
"version": "5.3.0"
|
|
6
6
|
}
|