geneseed 5.0.3 → 5.1.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 +83 -0
- package/README.md +3 -3
- package/SHIPPED.md +2 -2
- package/adapters/claude-code/README.md +5 -1
- package/adapters/openclaude/README.md +3 -1
- package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
- package/adapters/opencode/workflows/_runtime.js +1 -1
- package/bin/geneseed-cli.mjs +3 -0
- package/bin/geneseed-hook.mjs +10 -2
- package/docs/PRD.md +1 -1
- package/docs/README.md +4 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/factories.md +203 -0
- package/docs/concepts/hooks.md +1 -1
- package/docs/concepts/host-matrix.md +1 -0
- package/docs/concepts/loop-gates.md +6 -0
- package/docs/concepts/loops.md +1 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/concepts/shared-tier.md +14 -0
- package/docs/extending.md +5 -1
- package/docs/guides/autostart.md +2 -0
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/run-a-factory.md +116 -0
- package/docs/guides/set-up-ownership.md +1 -0
- package/docs/guides/upgrade-to-5.md +2 -2
- package/docs/reference/factory-actions.md +22 -0
- package/docs/reference/loop-actions.md +1 -1
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/web-ui.md +47 -2
- package/harness.config.json +1 -1
- package/js/README.md +21 -2
- package/js/build/args.mjs +44 -12
- package/js/build/emit-claude.mjs +3 -0
- package/js/build/emit-opencode.mjs +4 -0
- package/js/build/retired-skills.mjs +158 -0
- package/js/build/source.mjs +41 -2
- package/js/cli-table.json +193 -3
- package/js/factory/cli.mjs +194 -0
- package/js/factory/graph.mjs +309 -0
- package/js/factory/registry.mjs +71 -0
- package/js/factory/state.mjs +511 -0
- package/js/hosts/activity.mjs +3 -3
- package/js/hosts/done-checks.mjs +3 -2
- package/js/hosts/geneseed-dir.mjs +1 -1
- package/js/hosts/gitref.mjs +21 -0
- package/js/hosts/hooks-context.mjs +63 -9
- package/js/hosts/hooks-prims.mjs +1 -1
- package/js/hosts/memory-files.mjs +4 -2
- package/js/hosts/settings.mjs +5 -4
- package/js/inspect/checks-authoring.mjs +11 -1
- package/js/inspect/cost.mjs +91 -5
- package/js/inspect/doctor.mjs +2 -1
- package/js/inspect/inventory.mjs +1 -1
- package/js/loop/catalog.mjs +30 -12
- package/js/loop/cli.mjs +27 -15
- package/js/loop/graph.mjs +13 -4
- package/js/loop/registry.mjs +65 -28
- package/js/loop/state.mjs +18 -8
- package/js/maintain/migrate.mjs +39 -25
- package/js/web/api.mjs +43 -1
- package/js/web/catalog.mjs +38 -2
- package/js/web/daemon.mjs +191 -6
- package/js/web/handler.mjs +27 -5
- package/js/web/routes.mjs +10 -3
- package/js/web/server.mjs +4 -1
- package/package.json +1 -1
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +5 -7
- package/src/bricks/checks.md +62 -0
- package/src/bricks/docs-update.md +5 -0
- package/src/bricks/holdout-write.md +23 -0
- package/src/bricks/holdout.md +25 -0
- package/src/bricks/intake.md +27 -0
- package/src/bricks/merge-gate.md +31 -0
- package/src/bricks/pr-open.md +21 -0
- package/src/bricks/retro.md +22 -0
- package/src/bricks/review-panel.md +43 -0
- package/src/bricks/spec.md +20 -6
- package/src/bricks/test.md +4 -1
- package/src/bricks/triage.md +19 -0
- package/src/doctrines/comms.md +29 -41
- package/src/doctrines/craft.md +3 -10
- package/src/doctrines/ops.md +4 -15
- package/src/doctrines/rigor.md +1 -5
- package/src/factories/analysis-to-build.json +52 -0
- package/src/factories/bug-report-to-fix.json +50 -0
- package/src/factories/issue-to-pr.json +67 -0
- package/src/skills/_checkpoints.md +1 -0
- package/src/skills/adhd.md +1 -1
- package/src/skills/factory-forge.md +115 -0
- package/src/skills/factory.md +196 -0
- package/src/skills/loop.md +3 -2
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/workflow.md +2 -1
- package/themes/_TEMPLATE.json +4 -2
- package/themes/biker.json +4 -2
- package/themes/commentator.json +4 -2
- package/themes/cyberpunk.json +4 -2
- package/themes/gamer.json +4 -2
- package/themes/imperial.json +4 -2
- package/themes/joker.json +4 -2
- package/themes/marvin.json +4 -2
- package/themes/mean.json +4 -2
- package/themes/military.json +4 -2
- package/themes/neutral.json +4 -2
- package/themes/pirate.json +4 -2
- package/themes/sports.json +4 -2
- package/themes/verstappen.json +4 -2
- package/themes/wizard.json +4 -2
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
- package/web/dist/assets/{Activity-Ck_Xffpo.js → Activity-CpkBwpu7.js} +1 -1
- package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-DTPziZWM.js} +1 -1
- package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-hiG_gGNU.js} +1 -1
- package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-DUIUfNp6.js} +1 -1
- package/web/dist/assets/Dashboard-Dnw6EyX7.js +2 -0
- package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-BEET_l16.js} +2 -2
- package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
- package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-BKxy5apE.js} +1 -1
- package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-CnFVlVD0.js} +3 -3
- package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-ChFitHjo.js} +1 -1
- package/web/dist/assets/{Kits-XQHsazCN.js → Kits-CcR-OlwQ.js} +1 -1
- package/web/dist/assets/Laws-B1s5idOg.js +4 -0
- package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
- package/web/dist/assets/Library-x6TkkEVF.js +3 -0
- package/web/dist/assets/Loops-BH93KKxn.js +2 -0
- package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-BO0aIKPL.js} +1 -1
- package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-CE_0Vhh0.js} +2 -2
- package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-CbpZvVN_.js} +1 -1
- package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-C2oW7oEj.js} +1 -1
- package/web/dist/assets/api-DLDVY3K-.js +1 -0
- package/web/dist/assets/{index-BNttaGQb.js → index-BQwOmbor.js} +3 -3
- package/web/dist/assets/index-CuIop_pO.css +1 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Dashboard-BUdUTjbB.js +0 -2
- package/web/dist/assets/Laws-B6A55S-2.js +0 -4
- package/web/dist/assets/Library-D7L0Wdbh.js +0 -3
- package/web/dist/assets/Loops-C0loS73u.js +0 -2
- package/web/dist/assets/RailCats-BGZnJ6fa.js +0 -1
- package/web/dist/assets/api-BMFDSXoB.js +0 -1
- package/web/dist/assets/index-BEI5ugYQ.css +0 -1
|
@@ -58,6 +58,20 @@ Each global emit, in the host's own config directory, moves that host's stores i
|
|
|
58
58
|
|
|
59
59
|
Nothing is deleted. After every copy is read back, the old `memory/` moves to `archived-memory/<stamp>/` beside it, and the notes and whole files move to the same kind of folder. The host store returns to its seed and keeps its `README.md`. Hand-written index text and `archive/` stay in that folder, and the report line names every other file that stayed there and did not fold. A store or file already linked to the tier, in either direction, is left alone. If a copy fails, the old store stays readable, the emit reports it on stderr and goes on, and the next emit retries. There is no automatic way back: to downgrade, restore the archived folder by hand.
|
|
60
60
|
|
|
61
|
+
### Retired skills
|
|
62
|
+
|
|
63
|
+
The same global emit also clears retired skills. A skill that Geneseed shipped and then removed or renamed can leave its folder in `skills/` with no manifest that owns it. Before the skill layer writes, the emit moves such a folder to `archived-skills/<name>/<timestamp>/` in the config directory and prints `[geneseed] <host>: pruned retired skill skills/<name> (moved to …)`. It moves the folder only when all of these hold:
|
|
64
|
+
|
|
65
|
+
- The name is an old alias or a retired skill id, and not a live skill.
|
|
66
|
+
- No manifest owns a path under it.
|
|
67
|
+
- The folder, the `skills/` folder, and everything inside it are real entries, not links or junctions, and the emit can read them.
|
|
68
|
+
- Its `SKILL.md` has the shape every Geneseed build wrote:
|
|
69
|
+
- `name: <folder>` on the second line;
|
|
70
|
+
- a `description:` on the third line, written as a JSON-quoted string;
|
|
71
|
+
- outside any code fence, a heading `# <label>: <id>`. The label is the `SKILL` word of a shipped theme, such as `Rite` or `Skill`. The id is the folder name, or the skill that the folder name is an alias of.
|
|
72
|
+
|
|
73
|
+
A folder that fails one check is yours. It stays, and `migrate --dry-run` lists it as an orphan. A folder the emit cannot read also stays, with a warning. A folder that passes all four checks is a `would prune` line there. A second emit finds nothing to move.
|
|
74
|
+
|
|
61
75
|
### The console
|
|
62
76
|
|
|
63
77
|
The console has one hub and no install switch. On the **Personal** page, Rules, Profile and Memory list the shared store once, tagged `shared`, and name no harness; a project install keeps its own entry. Each rule row shows its token cost, and the page shows the total. There is no rule limit. A **Pending** section shows what waits in the draft, with *Approve* and *Reject* on a rule, and the two files with three choices on a profile or wiki pointer. A decision that moves a file offers *Rebuild all*, which removes the host copy. An edit in another session makes the decision reload instead of applying, and no decision applies while a rebuild runs.
|
package/docs/extending.md
CHANGED
|
@@ -327,7 +327,9 @@ render — no citation moves, because none names a number. Then:
|
|
|
327
327
|
1. `RETIRED_RULE_IDS` in `js/build/source.mjs` — add the id with what it was and where its text
|
|
328
328
|
went. `constitutionProblems` refuses a retired id declared again, so an id that meant one rule in
|
|
329
329
|
someone's notes can never come back meaning another. `liveAs` names the one tier that may still
|
|
330
|
-
declare it (Law IX's `external-gate` lives on as a rigor rule).
|
|
330
|
+
declare it (Law IX's `external-gate` lives on as a rigor rule). For a doctrine rule, write `was`
|
|
331
|
+
as its address, `<pack> <n>` (`mark-the-ask` was `comms 5`): `retiredRuleAddresses` reads it, so
|
|
332
|
+
an install that still excludes that address gets a WARN and a rebuild, not a refusal.
|
|
331
333
|
2. Every citation of the removed id — the doctor names each one; point it at the rule that now
|
|
332
334
|
carries the text.
|
|
333
335
|
3. Its `LEX_<ID>`/`DOC_<ID>` key in all fifteen theme files (the equality arm names each).
|
|
@@ -910,6 +912,8 @@ on N, and refuses (exit 1, nothing sent) when it names another port. A test inst
|
|
|
910
912
|
port is therefore stopped with `--port`, never with a bare `web stop` — that one stops whatever
|
|
911
913
|
the record names, usually the live console on 4747.
|
|
912
914
|
|
|
915
|
+
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
|
+
|
|
913
917
|
---
|
|
914
918
|
|
|
915
919
|
## 10 — What to settle before the next wave
|
package/docs/guides/autostart.md
CHANGED
|
@@ -19,6 +19,8 @@ Only one console runs at a time. A second `start` does nothing, so logging in tw
|
|
|
19
19
|
|
|
20
20
|
> **Always use `web start` in a login item, never bare `web`.** Bare `geneseed web` runs in the foreground and leaves no record of itself. `web stop`, `web restart` and `web status` then cannot see it: they report no live server while it keeps serving. A `restart` would then start a second console that cannot take the busy port.
|
|
21
21
|
|
|
22
|
+
**When the port is busy.** `web start` and `web restart` ask for port 4747 first. If something else holds it, they check what it is. A console of this same copy of Geneseed is ended and the port is taken. Anything else is left alone: another program, a console of another copy, or a console too old to say which copy it is. The command then prints a line naming the port and the holder, and serves on a free port instead (and says which). `geneseed web status` also lists a console on 4747 that is not the recorded one. If a page says *this console is not the recorded daemon*, you are on one of those older consoles: use the address `web status` prints, or end the pid it names.
|
|
23
|
+
|
|
22
24
|
## From the web console
|
|
23
25
|
|
|
24
26
|
Open **Settings** and find the **Start at login** row in **Server**. The row shows the file and its state:
|
package/docs/guides/migrate.md
CHANGED
|
@@ -25,7 +25,7 @@ geneseed migrate # do it
|
|
|
25
25
|
|
|
26
26
|
**It runs only from the npm package.** From a git clone or a bundle, a real run has nothing to move: the rebuild would point the shim back at that same copy. So it refuses with exit 3 before it writes anything, and says to use `geneseed update`. An `npx` run refuses too: npm prunes that cache, and the shim would die with it. `--dry-run` works from anywhere. Outside the package it previews the fold, then says a real run would refuse.
|
|
27
27
|
|
|
28
|
-
`--dry-run` also previews [the fold](../concepts/shared-tier.md#the-fold) for each global install, even on a machine that has already migrated, because the fold runs in every global emit. Each host is read against the shared tier as it stands, so two hosts that hold the same new fact both count it.
|
|
28
|
+
`--dry-run` also previews [the fold](../concepts/shared-tier.md#the-fold) for each global install, even on a machine that has already migrated, because the fold runs in every global emit. Each host is read against the shared tier as it stands, so two hosts that hold the same new fact both count it. It also prints `would prune` for each retired skill folder that the next global emit moves aside, and `orphan` for each unowned file it leaves alone ([retired skills](../concepts/shared-tier.md#retired-skills)).
|
|
29
29
|
|
|
30
30
|
## All or nothing
|
|
31
31
|
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: guides
|
|
3
|
+
order: 24.5
|
|
4
|
+
title: "Run a factory"
|
|
5
|
+
kind: "concept"
|
|
6
|
+
section: "Factories"
|
|
7
|
+
description: "Carry a bug report, an issue or an analysis to an open PR with green CI: what you need, how to ask, and where it stops for you."
|
|
8
|
+
---
|
|
9
|
+
A **factory** carries one work item to an open pull request with green CI. Each stage is a brick or a whole loop, and a red CI run sends the work back to the loop, a bounded number of times. You ask in plain words. The agent drives `geneseed factory`, which decides every step. No stage merges: at the end the agent asks you once whether to merge, and merges only on your yes.
|
|
10
|
+
|
|
11
|
+
This page is the how-to. For how the engine works (stages, cycles, state files), see [Factories](../concepts/factories.md).
|
|
12
|
+
|
|
13
|
+
## Before you start
|
|
14
|
+
|
|
15
|
+
| You need | Why |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| An install that carries the `factory` and `loop` skills | The `factory` skill talks to `geneseed factory`, and runs each loop stage through the `loop` skill. After upgrading Geneseed, run `geneseed rebuild-all`. |
|
|
18
|
+
| A git repository with a remote named `origin` | Every loop iteration pushes to `loop/factory-<slug>`, and `pr-open` opens the PR from that branch. |
|
|
19
|
+
| The `gh` CLI (GitHub) or `glab` (GitLab), signed in | `intake` reads an issue with it, `pr-open` opens the PR, `merge-gate` reads the checks. |
|
|
20
|
+
| CI that runs on pull requests | `merge-gate` waits for it. With no CI, it reports `none` and asks you whether the run goes on. |
|
|
21
|
+
| A test command the agent can run | The `bugfix` loop inside the factory needs it, as any loop does. |
|
|
22
|
+
|
|
23
|
+
See the factories your repo can run:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
geneseed factory list
|
|
27
|
+
geneseed factory check
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Start one by asking the agent
|
|
31
|
+
|
|
32
|
+
Name the factory and the work item in plain words, in a session in your repo:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
Run the bug-report-to-fix factory on https://github.com/acme/shop/issues/412
|
|
36
|
+
Take this bug report through bug-report-to-fix: totals round the wrong way on refunds
|
|
37
|
+
Run issue-to-pr on #42
|
|
38
|
+
Take issue 418 through the issue-to-pr factory
|
|
39
|
+
Take this analysis through analysis-to-build: docs/analysis/export-csv.md
|
|
40
|
+
Run the analysis-to-build factory on this request: add CSV export to the report page
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
On Claude Code, `/factory` with the same words is the explicit form: it loads the `factory`
|
|
44
|
+
skill directly. The console's **Factories** page shows the request for each factory, ready to copy.
|
|
45
|
+
|
|
46
|
+
The agent then:
|
|
47
|
+
|
|
48
|
+
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
|
+
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.
|
|
50
|
+
3. Steps the run: `intake` writes the work item, `holdout-write` writes the holdout scenarios outside the worktree, the `bugfix` loop fixes it commit by commit, `checks` runs the base branch's done list against the fix, `review-panel` has a panel of agents review it, `holdout` plays the scenarios against the fix, `pr-open` opens the PR, `merge-gate` waits for CI, and `retro` writes the run report. In `issue-to-pr`, a `triage` stage comes after `holdout-write` and picks the lane: the `bugfix`, `feature`, `deps-upgrade` or `refactor` loop, or the `docs-update` brick for a docs-only change. A failed check, review or scenario, or red CI, then sends the work back to that lane.
|
|
51
|
+
|
|
52
|
+
The holdout scenarios are checks the developer never sees: see [Holdout scenarios](../concepts/factories.md#holdout-scenarios). You can read them yourself in `~/.config/geneseed/holdout/<slug>/`; never paste them into the chat while the run is going, or the developer may see them.
|
|
53
|
+
|
|
54
|
+
## Start one by hand
|
|
55
|
+
|
|
56
|
+
Create the worktree first, then register the run in it. Never run `init` in your own checkout:
|
|
57
|
+
the run then works on your current branch. Keep the three commands as one `&&` chain and
|
|
58
|
+
replace every placeholder: if one command fails, the next ones do not run. Pick a slug without the
|
|
59
|
+
word `git`, `commit` or `push`: `factory init` refuses it.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug> && cd ../<repo>-factory-<slug> && geneseed factory init --factory <name> --title "<title>" --requirement "<requirement>" --input "<issue URL, file path or pasted text>"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`init` alone runs nothing. It writes `FACTORY.md` and registers the run. An agent drives the run
|
|
66
|
+
from there with `geneseed factory next` and `geneseed factory record`: open a session in the
|
|
67
|
+
worktree and ask it to resume the run.
|
|
68
|
+
|
|
69
|
+
## Build from an analysis
|
|
70
|
+
|
|
71
|
+
`analysis-to-build` takes a larger piece of work: a design document, an analysis pasted into the
|
|
72
|
+
chat, or a plain request. It splits the work into tasks that you approve, then builds them one by
|
|
73
|
+
one in the same worktree, and opens one PR at the end.
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
run the analysis-to-build factory on docs/analysis/export-csv.md
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
1. `intake` writes the work item from the document.
|
|
80
|
+
2. `spec` writes `specs/<slug>/spec.md`: the scope, acceptance criteria in EARS form, and an
|
|
81
|
+
ordered task list (20 tasks at most). The run then stops for you. Read the spec and answer
|
|
82
|
+
`ok`, `no`, or `amend` with your corrections; an amend rewrites the spec.
|
|
83
|
+
3. After your `ok`, the agent commits the spec (the commit asks you), `holdout-write` writes the
|
|
84
|
+
holdout scenarios from it, and the agent runs the `feature` loop once per task, in order.
|
|
85
|
+
`geneseed factory next` names each one as `task <i>/<n>`.
|
|
86
|
+
4. After the last task, `checks` and `review-panel` run once, `holdout` plays the scenarios,
|
|
87
|
+
`pr-open` opens one PR for all of them, and `merge-gate` waits for CI.
|
|
88
|
+
5. A failed scenario sends the work back to the `feature` loop as one extra task, with one
|
|
89
|
+
sentence per failure (observed against expected) as its first note. Red CI does the same, with
|
|
90
|
+
the failing checks as the note: "make CI green". Each is twice at most; a third failure stops
|
|
91
|
+
the run.
|
|
92
|
+
|
|
93
|
+
## Where it stops for you
|
|
94
|
+
|
|
95
|
+
| Moment | What you decide |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| `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. |
|
|
98
|
+
| `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
|
+
| `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
|
+
| 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. |
|
|
101
|
+
| A push | Every push that is not a loop's own commit asks you, `pr-open`'s included. |
|
|
102
|
+
| A loop gate | Anything the `bugfix` loop asks you, as in [While a loop runs](loop-running.md). |
|
|
103
|
+
| `merge-gate` reports `none` | The repo runs no CI on the PR: `ok` goes on to `retro`, `no` stops the run. Or the finding starts `environment:`: CI was still pending after 30 minutes, or `gh`/`glab` is missing or failed. `amend` waits again (after you fix the tool), `ok` goes on to `retro` without a green verdict (the close step reads CI once more, and proposes the merge only when it is green), `no` stops. |
|
|
104
|
+
| A `geneseed factory record` line asks | The git gate asks on any command line that holds the word `git` and the word `commit` or `push`. A record line starts with `git status`, so a spec path, a finding's path or an outcome name with `commit` or `push` in it makes the gate ask. On a record line this is a false alarm: answer yes. |
|
|
105
|
+
| The close commit | The last commit removes `FACTORY.md`, and it asks. Its push runs CI again: the agent reads the checks once more and reports the final state. A run with no loop (the `docs` lane) never committed `FACTORY.md`: the agent deletes the file, there is no close commit, and the final state is the one `merge-gate` read. |
|
|
106
|
+
| The merge proposal | Only when that final CI state is green: the agent shows the PR, the CI state and each review seat's verdict, and asks once whether to merge. Only on your explicit yes in chat does it squash-merge (`gh pr merge --squash`); no Geneseed gate asks before that command, so your answer is the only guard. Otherwise the PR stays open. It never turns on auto-merge. |
|
|
107
|
+
|
|
108
|
+
Red CI does not stop for you: it sends the work back to the run's loop (`bugfix`, or the lane `triage` chose) with the failing checks as its first note, twice at most. A third red result stops the run. A failed holdout scenario works the same way, with its own count of two, and so do a failed `checks` and a failed `review-panel`. A holdout `error` stops the run: the diff touched the holdout folder, or a scenario could not be played.
|
|
109
|
+
|
|
110
|
+
## When it ends
|
|
111
|
+
|
|
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.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
**Next:** [Factories](../concepts/factories.md)
|
|
@@ -43,9 +43,9 @@ It writes nothing. It prints one line for each global install, read against the
|
|
|
43
43
|
|
|
44
44
|
**Use only the `--dry-run` form here.** The `would re-emit` lines are the plan of `geneseed migrate` itself, which moves a clone install to [the npm shape](migrate.md). That is not a 5.0 step. From a clone those lines do not appear: the preview ends by saying a real run would refuse, and a real `migrate` there exits 3 and changes nothing.
|
|
45
45
|
|
|
46
|
-
It also lists
|
|
46
|
+
It also lists the folders of retired skills that no manifest owns. A `would prune` line names a folder that a Geneseed build rendered and that no longer ships. The next global emit moves it to `<config dir>/archived-skills/<name>/<timestamp>/`. An `orphan` line names a root `AGENT.md`, or a retired skill folder that is a link, holds a link, or does not look like a Geneseed render. Such a folder may be yours. Geneseed never moves it, so move it by hand if it is not.
|
|
47
47
|
|
|
48
|
-
**In the console.** With no terminal, there is no preview before the first fold: *Update* on a clone pulls and rebuilds in one job, so the fold runs in that click, and a 4.x console has no preview. Nothing is deleted, as step 3 shows. After that, *Preview next rebuild* on the Installs page, beside *Rebuild all*, shows the same fold lines and orphans for any later rebuild, without the `would re-emit` lines, and writes nothing.
|
|
48
|
+
**In the console.** With no terminal, there is no preview before the first fold: *Update* on a clone pulls and rebuilds in one job, so the fold runs in that click, and a 4.x console has no preview. Nothing is deleted, as step 3 shows. After that, *Preview next rebuild* on the Installs page, beside *Rebuild all*, shows the same fold lines and orphans for any later rebuild (not yet the `would prune` folders), without the `would re-emit` lines, and writes nothing.
|
|
49
49
|
|
|
50
50
|
## 3. Upgrade
|
|
51
51
|
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: reference
|
|
3
|
+
order: 2.5
|
|
4
|
+
title: "Factory actions"
|
|
5
|
+
kind: "concept"
|
|
6
|
+
section: "CLI & environment"
|
|
7
|
+
description: "The geneseed factory actions, one line each."
|
|
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` or `needs-info`), 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
|
+
|
|
11
|
+
| action | what it does |
|
|
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 stops 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
|
+
| `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). 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
|
+
| `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: `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). `--note-file <file>` reads the note from a file instead, as `--carry-file` does |
|
|
19
|
+
|
|
20
|
+
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
|
+
Run `geneseed factory --help` for the full flag list.
|
|
@@ -11,7 +11,7 @@ The actions of `geneseed loop`, the state machine behind [Loops](../concepts/loo
|
|
|
11
11
|
| action | what it does |
|
|
12
12
|
|---|---|
|
|
13
13
|
| `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
|
|
14
|
-
| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
|
|
14
|
+
| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset; `--note` or `--note-file <path>` gives the loop the note it starts with (a factory hands its carry here). Each `init` also stamps the worktree's row in the loop registry with the time, which `geneseed factory record` reads ([Factory actions](factory-actions.md)); `--factory <slug>` stores on that row the factory run this loop is a stage of |
|
|
15
15
|
| `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
|
|
16
16
|
| `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
|
|
17
17
|
| `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding into `LOOP.md`'s notes for the bricks after it: a plan survives the unit, and `review` and `mutation-check` findings last until `apply` reports. `test` cannot report `pass` when that note lists a check as `SKIPPED`: the record is refused and `LOOP.md` does not change |
|
|
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
|
|
|
12
12
|
|
|
13
13
|
**When it runs.** On session events. A sub-agent's child session (one with a `parentID`) is folded into its root session: it becomes an `agents[]` row (`{id, type, status: "running" | "done"}`, the child's id and agent), and its files join the root's `files` with `by` set to the child's id. Only learn's throwaway `geneseed-*` sessions are skipped. On OpenCode 2 the files come from `session.step.ended`, which carries no line counts, so those read `null`. A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
|
|
14
14
|
|
|
15
|
-
**Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd`
|
|
15
|
+
**Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
|
|
16
16
|
|
|
17
17
|
**Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
|
|
18
18
|
|
package/docs/web-ui.md
CHANGED
|
@@ -31,6 +31,11 @@ always get the command list.
|
|
|
31
31
|
- **Daemon.** `start` runs the server detached and returns your shell; it's a singleton
|
|
32
32
|
(already running ⇒ just reopens the browser). `stop` and the in-page **Stop** button
|
|
33
33
|
both POST a token-guarded `/api/shutdown`; `status` reports the running instance.
|
|
34
|
+
When the port is held by an unrecorded console of this install, `start` ends it by challenge
|
|
35
|
+
and response: the console hands out a single-use nonce that expires after 30 seconds, and
|
|
36
|
+
`start` answers with a MAC of the port and that nonce under the install secret. A foreground
|
|
37
|
+
`geneseed web` holds no secret, and a console from before this handshake checks no nonce; `start`
|
|
38
|
+
names either one and leaves it running.
|
|
34
39
|
- **Installable (PWA).** A manifest + service worker make it installable as a standalone
|
|
35
40
|
app; immutable assets are cached, while HTML and `/api/*` stay on the network so the
|
|
36
41
|
CSRF token never goes stale.
|
|
@@ -70,7 +75,7 @@ Every `/api/*` read takes and checks the pair, with these exceptions:
|
|
|
70
75
|
- `/api/ping` and `/api/jobs` ignore it.
|
|
71
76
|
- The machine-wide reads also ignore it: `/api/update`, `/api/installs`, `/api/fleet`, `/api/migrate/preview`,
|
|
72
77
|
`/api/kits`, `/api/usage`, `/api/gates`, `/api/excludes`, `/api/mcp`, `/api/loops/active`,
|
|
73
|
-
`/api/activity`, and the Library's skill, agent, memory and notebook lists,
|
|
78
|
+
`/api/factories/active`, `/api/activity`, and the Library's skill, agent, memory and notebook lists,
|
|
74
79
|
`/api/catalog/skills`, `/api/catalog/agents`, `/api/catalog/memory` and
|
|
75
80
|
`/api/catalog/notebook`. Such a read does not check the pair, and its answer does not change
|
|
76
81
|
with the pair. The Activity detail (`/api/activity/<id>`) and the Activity toggle still take
|
|
@@ -91,6 +96,15 @@ it. The order is the host order (OpenCode, Claude Code, Bob, OpenClaude), then g
|
|
|
91
96
|
project. The item's `install` field names the copy, and its `installs` field names every
|
|
92
97
|
install that has the id.
|
|
93
98
|
|
|
99
|
+
Agents opens on a pinned row for the **primary agent** (the theme's `PRIMARY_AGENT` noun), with a
|
|
100
|
+
**base** pill: every agent inherits its root file. Each agent's detail, the primary's included,
|
|
101
|
+
shows a **Loadout** panel: what the agent loads, block by block (the root file by section, the
|
|
102
|
+
session files or, for a sub-agent, your user rules, both catalogues, the Adept's spec), and the
|
|
103
|
+
rules it follows, marked where its spec cites them. `GET /api/loadout` (the primary) and
|
|
104
|
+
`/api/loadout/<agent>` serve it, install-scoped like `/api/item/`; the figures are the same
|
|
105
|
+
measurements as the Overview's always-on cost. The project root's own `user-rules.md` is not
|
|
106
|
+
counted, because it depends on the session's working directory.
|
|
107
|
+
|
|
94
108
|
A request that names no install reads the **default install**: the one you chose on the Installs
|
|
95
109
|
page (*Make default* on an active row), while it stays active. With no choice, it is the first
|
|
96
110
|
active one in the console's one install order (`fleetSort`): host order (opencode, claude, bob,
|
|
@@ -143,7 +157,7 @@ before its data. The Constitution waits for the picked install's own overview to
|
|
|
143
157
|
before it would read as armed.
|
|
144
158
|
|
|
145
159
|
The rail groups its pages under small mono headers, each with a square in the group's tint: the
|
|
146
|
-
Overview alone, then **Govern** (Constitution, Personal), **Build** (Library, Kits, Loops), **Run**
|
|
160
|
+
Overview alone, then **Govern** (Constitution, Personal), **Build** (Library, Kits, Loops, Factories), **Run**
|
|
147
161
|
(Installs, Activity) and **Help** (Docs, Settings). Each icon sits in a 28 px chip tinted by its group
|
|
148
162
|
(`--sb-<group>-bg` and `-ink` in `styles.css`; light mode has pastel chips with deep ink, 5.3:1 or
|
|
149
163
|
better). The lit page gets a raised row and `aria-current="page"`; a count badge is muted mono on the
|
|
@@ -338,6 +352,37 @@ screen the run list stacks above the detail.
|
|
|
338
352
|
the page's only write), what an awaiting loop waits on (launch / declared / actual / a
|
|
339
353
|
human gate, with its node) — the answer is given in the agent's session, never here — and
|
|
340
354
|
its ring with the current node filled, with its iteration history under it.
|
|
355
|
+
- **Factories** (`#/factories`) — the factory catalogue `geneseed factory` runs from, read-only,
|
|
356
|
+
in the Loops page's three panes with two sections. **Templates** are grouped by origin; the
|
|
357
|
+
reader draws the selected factory as a vertical graph (`web/src/lib/factoryFlow.js`): each
|
|
358
|
+
stage on the row of its longest path from `start`, top to bottom, joined by lines; a brick a
|
|
359
|
+
grey block, a fork amber, a `loop:` stage a teal box that names its loop (without `loop:`)
|
|
360
|
+
over `whole loop`, or `not in catalogue` when this install lacks it; the ring itself is on the
|
|
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` and `needs-info`), never a `loop:` stage, however
|
|
363
|
+
many stages its edges reach. The targets of a fork share a row, side by side, each lane labelled with its outcome,
|
|
364
|
+
and join again at the first stage every lane reaches. Each route back (an edge into a cycle's
|
|
365
|
+
first stage, the edge that spends a lap, `$lane` included) is a rail on the left labelled
|
|
366
|
+
`↺ <cycle> · max N`, the smallest cycle that holds it; every stop edge on the main path runs
|
|
367
|
+
into one rail on the right, ending at the `stop` cap, and a lane's own stop edge is a
|
|
368
|
+
`fail → stop` tag under its box. A `gate: human` brick wears the
|
|
369
|
+
person badge. The graph never scrolls sideways: it fits its pane. Lanes side by side come
|
|
370
|
+
first; when the rails do not fit, they become tags under the stage they leave, and the lanes
|
|
371
|
+
shrink to compact boxes (named without `loop:`). Only when even those do not fit (below about
|
|
372
|
+
524 px for five lanes) do the lanes stack as a list. Under it: a legend, the cycles in
|
|
373
|
+
words, two ways to start a run, each with a Copy button — the request to paste to the agent
|
|
374
|
+
(`Run the <factory> factory on <issue URL, file or request>`), then the by-hand command, one
|
|
375
|
+
`&&` chain that adds a worktree, enters it and runs `geneseed factory init` there — and the
|
|
376
|
+
factory's rules. It reads `GET /api/factories/catalog` for the install the *Install:* picker
|
|
377
|
+
names. **Active** is every run `geneseed factory init` registered on this machine
|
|
378
|
+
(`GET /api/factories/active`, polled every 5 s, the graph read from each run's `FACTORY.md`),
|
|
379
|
+
grouped as Loops › Active is; the reader shows the run's stage, transitions, task number, its
|
|
380
|
+
child loop's step and iteration, what it awaits, and its graph with the current stage lit,
|
|
381
|
+
the lane its last fork took (the run's `lane`, else read from its `history`) lit, the child
|
|
382
|
+
loop's node named under the current stage (`at <node>`) and each cycle's laps as `n / max`. A
|
|
383
|
+
run carries its graph but no bricks or loops: the graph borrows those from the catalogue of the
|
|
384
|
+
install the Templates tab's picker names, which the run's project may not share, and the reader
|
|
385
|
+
says which. No run reports tab: a run's report lives in its own worktree.
|
|
341
386
|
- **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
|
|
342
387
|
per file: the shared one every global install reads, tagged `shared`, and each project
|
|
343
388
|
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.0
|
|
5
|
+
"version": "5.1.0"
|
|
6
6
|
}
|
package/js/README.md
CHANGED
|
@@ -21,6 +21,7 @@ js/hosts/ where it stops being a renderer and touches the machine
|
|
|
21
21
|
js/inspect/ the read-only half: doctor, status, diff, validate, catalog
|
|
22
22
|
js/lib/ primitives, every one a deliberate divergence from the Node default
|
|
23
23
|
js/loop/ `geneseed loop` — the state machine over LOOP.md, and what it steps through
|
|
24
|
+
js/factory/ `geneseed factory` — the state machine over FACTORY.md, one level above loops
|
|
24
25
|
js/maintain/ lifecycle verbs that change an install that already exists
|
|
25
26
|
js/ui/ what it prints at a terminal
|
|
26
27
|
js/web/ the `geneseed web` console
|
|
@@ -65,6 +66,7 @@ as a per-host install at project or global scope.
|
|
|
65
66
|
| `emit-opencode.mjs` | The OpenCode emits — a project's `.opencode/` and the global config dir. Deliberate twin of the above |
|
|
66
67
|
| `emit-common.mjs` | Constants, tree walkers, and the three writers BOTH global emits share. Decides no host |
|
|
67
68
|
| `fold.mjs` | The fold: moves a global install's stores into the shared tier, in the emit. Moves aside, never deletes; a second run writes nothing |
|
|
69
|
+
| `retired-skills.mjs` | Skill folders an old build rendered under a name that no longer ships: the canonical global emit moves a plain, fingerprinted, unowned one to `archived-skills/`; `migrate --dry-run` reads the same split |
|
|
68
70
|
| `rule-decide.mjs` | The decisions on the draft: the approval flow of `src/skills/rule/approve.md`, as the console applies it. Write order: target, ledger, draft |
|
|
69
71
|
| `stubs.mjs` | Write-once seed files: context, wiki, rules, excludes, profile, `.gitignore`, memory/notebook indexes |
|
|
70
72
|
| `version.mjs` | The release marker: fingerprint the sources, read/compare/write an install's version, warn on downgrade |
|
|
@@ -103,7 +105,7 @@ user co-owns, and the hook verbs those emitted configs then run.
|
|
|
103
105
|
| `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
|
|
104
106
|
| `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate — the `user-rules.md` parser, the draft's format and the fold's ledger reader. No spawn: the CLI, web console and fold import it |
|
|
105
107
|
| `geneseed-dir.mjs` | The Node writers into a project's `<git root>/.geneseed/`: the personal-by-default `.gitignore` (`GENESEED_GITIGNORE`, pinned to the two OpenCode copies), and the protected-checks seed every project emit runs (`seedProtectedChecks`: seed once when absent, then the user's — never recorded, rewritten or uninstalled). Never throws, never writes through a link. Spawn-free |
|
|
106
|
-
| `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer |
|
|
108
|
+
| `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched`, `headCommit` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer; `headCommit` by `js/factory/cli.mjs` (R2) |
|
|
107
109
|
| `loss.mjs` | Law IV calibrated to real loss: `lossReason` decides whether a command would really lose data (protected branch, unpushed branch, dirty tree, stash, reflog, files git cannot restore) and fails closed. The gate path's one `git` spawn, reached only after `LOSS_CANDIDATE_RE` matched. Twin: the OpenCode guard plugin |
|
|
108
110
|
| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |
|
|
109
111
|
| `shim.mjs` | The machine-wide hook shim: its path, body, liveness (`shimDead`, read on every CLI run), `hookPrefix`/`hookRunnerEntry`; and the web console's login launcher (`autostartState`/`autostartInstall`/`autostartRemove`). Kept cheap to import |
|
|
@@ -185,7 +187,7 @@ transition, score and stop is computed here.
|
|
|
185
187
|
|---|---|
|
|
186
188
|
| `graph.mjs` | `checkGraph` — the rules a loop graph must satisfy before a node runs: nodes name real bricks, edges cover every outcome, `$close` is reachable, every cycle is inside a declared loop |
|
|
187
189
|
| `score.mjs` | The risk arithmetic: `WEIGHTS`, `PRESETS`, `declaredRisk`/`actualRisk`/`decide`, `parseNumstat`. Pure — no import but node builtins |
|
|
188
|
-
| `catalog.mjs` | `loadCatalog` — bricks
|
|
190
|
+
| `catalog.mjs` | `loadCatalog` — bricks, loop templates and factories from shipped/global/project origins, later overrides earlier BY NAME |
|
|
189
191
|
| `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
|
|
190
192
|
| `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
|
|
191
193
|
| `registry.mjs` | `loops.json` under XDG — the launched-loop identity list `loop init` records into and the Active tab's `activeLoops`/`setLoopPreset` read and rewrite |
|
|
@@ -203,6 +205,23 @@ fails. `activeLoops` saves the registry back only when the kept set actually cha
|
|
|
203
205
|
root, a loop newly seen finished or seen running again) — a routine poll from the Active tab must
|
|
204
206
|
never be a write.
|
|
205
207
|
|
|
208
|
+
## `js/factory/` — the factory engine
|
|
209
|
+
|
|
210
|
+
`geneseed factory` — the loop engine one level up: a state machine over a graph of stages (a
|
|
211
|
+
brick or a whole loop; a fork's named outcomes pick its lane), persisted as a JSON block in
|
|
212
|
+
`FACTORY.md` beside `LOOP.md`. A child loop runs through `js/loop/` unchanged.
|
|
213
|
+
|
|
214
|
+
| module | owns |
|
|
215
|
+
|---|---|
|
|
216
|
+
| `graph.mjs` | `checkFactory` — the rules a factory must satisfy before a stage runs: stages exist, edges cover every outcome, `$close` is reachable, every cycle is declared (the loop engine's `undeclaredCycles`), `$lane` only behind a fork, `protected` a list of paths, and every `review.seats` entry a shipped agent. Also the fork helpers the engine shares: `isFork`, `lanesOf`, `laneTargets`, `spentCycle` |
|
|
217
|
+
| `state.mjs` | The engine itself: `initFactory`, `nextStage`, `recordStage`, `decideFactory`, `renderFactoryFile`/`parseFactoryFile`, `validateFactoryState`, `countSpecTasks` |
|
|
218
|
+
| `cli.mjs` | `geneseed factory check\|list\|init\|next\|record\|decide` — the only face of this engine |
|
|
219
|
+
| `registry.mjs` | `factories.json` beside `loops.json`: `recordFactory` (called by `factory init`) and `activeFactories`, on the loop registry's own `loadRows`/`saveRows`/`sweepRows`. A run and its child loop share a root, which is how a reader groups them |
|
|
220
|
+
|
|
221
|
+
**Before editing:** `FACTORY.md` is in `js/loop/state.mjs`'s `ENGINE_FILES`, so a child loop never
|
|
222
|
+
scores it; the clean-tree check after a stage outside a loop filters with that same list. `cli.mjs`
|
|
223
|
+
may not spawn, and refuses `next`/`record` while a `LOOP.md` exists at the root.
|
|
224
|
+
|
|
206
225
|
## `js/maintain/` — lifecycle
|
|
207
226
|
|
|
208
227
|
Verbs that change an install that already exists, as opposed to rendering one.
|
package/js/build/args.mjs
CHANGED
|
@@ -12,7 +12,7 @@ import { withPlatformNewlines } from '../lib/fs.mjs';
|
|
|
12
12
|
import path from 'node:path';
|
|
13
13
|
import {
|
|
14
14
|
CONFIG, discoverNames, GATE_SWITCHES, PACK_ORDER, SRC, knownRuleIds, knownSkillIds, linkedSkillIds, loadKits,
|
|
15
|
-
resolveSkillNames, skillAliases,
|
|
15
|
+
resolveSkillNames, retiredRuleAddresses, reusedRuleAddresses, ruleCanon, skillAliases,
|
|
16
16
|
} from './source.mjs';
|
|
17
17
|
// The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
|
|
18
18
|
// what lets it sit inside this module's `child_process` ban.
|
|
@@ -30,14 +30,14 @@ const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global'
|
|
|
30
30
|
* stays as it was: stderr was once compared byte-for-byte across the two CLIs, and nothing
|
|
31
31
|
* pins it now.
|
|
32
32
|
*/
|
|
33
|
-
export function configDefaults() {
|
|
33
|
+
export function configDefaults(config = CONFIG, rules = ruleCanon(SRC).rules) {
|
|
34
34
|
const d = {
|
|
35
35
|
theme: 'neutral', posture: 'peer', mode: 'direct', trust: DEFAULT_PRESET,
|
|
36
36
|
doctrines: [...PACK_ORDER], excludeRules: [], excludeSkills: [], kits: [],
|
|
37
37
|
};
|
|
38
|
-
if (!existsSync(
|
|
38
|
+
if (!existsSync(config)) return d;
|
|
39
39
|
try {
|
|
40
|
-
const data = JSON.parse(readFileSync(
|
|
40
|
+
const data = JSON.parse(readFileSync(config, 'utf8'));
|
|
41
41
|
if (data && typeof data === 'object' && !Array.isArray(data)) {
|
|
42
42
|
if (data.theme !== undefined) d.theme = data.theme;
|
|
43
43
|
if (data.posture !== undefined) d.posture = data.posture;
|
|
@@ -52,7 +52,7 @@ export function configDefaults() {
|
|
|
52
52
|
if (Array.isArray(data.doctrines) && data.doctrines.every((x) => known.includes(x))) {
|
|
53
53
|
d.doctrines = PACK_ORDER.filter((p) => data.doctrines.includes(p));
|
|
54
54
|
} else {
|
|
55
|
-
process.stderr.write(`[geneseed] WARN: ${path.basename(
|
|
55
|
+
process.stderr.write(`[geneseed] WARN: ${path.basename(config)} "doctrines" is not a `
|
|
56
56
|
+ 'list of known pack names — using all packs.\n');
|
|
57
57
|
}
|
|
58
58
|
}
|
|
@@ -66,23 +66,28 @@ export function configDefaults() {
|
|
|
66
66
|
// passed through lands in the `Excluded rules:` marker, `rebuild-all` hands it back
|
|
67
67
|
// as a flag, and `parseExcludeRules` dies on it — every rebuild of that install,
|
|
68
68
|
// forever. Unknown ids are dropped with a WARN; the known ones still bind.
|
|
69
|
-
const known = knownRuleIds();
|
|
69
|
+
const known = knownRuleIds(rules);
|
|
70
|
+
const retired = retiredRuleAddresses(known);
|
|
70
71
|
const ids = data.excludeRules.map((x) => x.trim().replace(/[ \t]+/, '.'));
|
|
71
|
-
const
|
|
72
|
+
for (const id of ids.filter((x) => retired.has(x))) {
|
|
73
|
+
warnRetiredRule(id, retired, `${path.basename(config)} "excludeRules"`);
|
|
74
|
+
}
|
|
75
|
+
const unknown = ids.filter((id) => !known.includes(id) && !retired.has(id));
|
|
72
76
|
if (unknown.length) {
|
|
73
|
-
process.stderr.write(`[geneseed] WARN: ${path.basename(
|
|
77
|
+
process.stderr.write(`[geneseed] WARN: ${path.basename(config)} "excludeRules" names `
|
|
74
78
|
+ `unknown rule(s) ${unknown.map((id) => `'${id.replace('.', ' ')}'`).join(', ')}`
|
|
75
79
|
+ ' — ignoring them.\n');
|
|
76
80
|
}
|
|
77
81
|
d.excludeRules = [...new Set(ids.filter((id) => known.includes(id)))].sort();
|
|
82
|
+
warnReusedRules(d.excludeRules, `${path.basename(config)} "excludeRules"`, reusedRuleAddresses(rules));
|
|
78
83
|
} else {
|
|
79
|
-
process.stderr.write(`[geneseed] WARN: ${path.basename(
|
|
84
|
+
process.stderr.write(`[geneseed] WARN: ${path.basename(config)} "excludeRules" is `
|
|
80
85
|
+ 'not a list of rule addresses — excluding nothing.\n');
|
|
81
86
|
}
|
|
82
87
|
}
|
|
83
88
|
}
|
|
84
89
|
} catch {
|
|
85
|
-
process.stderr.write(`[geneseed] WARN: ${path.basename(
|
|
90
|
+
process.stderr.write(`[geneseed] WARN: ${path.basename(config)} is unreadable — `
|
|
86
91
|
+ "using theme 'neutral'.\n");
|
|
87
92
|
}
|
|
88
93
|
return d;
|
|
@@ -170,22 +175,49 @@ function choicesFor() {
|
|
|
170
175
|
* can least afford: the user asked for a rule to STOP binding and it would keep binding.
|
|
171
176
|
* Sorted, deduped, for the same marker-stability reason `--doctrines` is.
|
|
172
177
|
*/
|
|
173
|
-
function parseExcludeRules(value) {
|
|
178
|
+
export function parseExcludeRules(value, rules = ruleCanon(SRC).rules) {
|
|
174
179
|
const s = value.trim();
|
|
175
180
|
if (s === 'none' || s === '') return [];
|
|
176
|
-
const known = knownRuleIds();
|
|
181
|
+
const known = knownRuleIds(rules);
|
|
182
|
+
const retired = retiredRuleAddresses(known);
|
|
177
183
|
const out = [];
|
|
178
184
|
for (const raw of s.split(',').map((x) => x.trim()).filter(Boolean)) {
|
|
179
185
|
const id = raw.replace(/[ \t]+/, '.');
|
|
186
|
+
if (retired.has(id)) { warnRetiredRule(id, retired, '--exclude-rules'); continue; }
|
|
180
187
|
if (!known.includes(id)) {
|
|
181
188
|
die(2, `argument --exclude-rules: invalid choice: '${raw}' (choose from `
|
|
182
189
|
+ `${known.map((c) => `'${c.replace('.', ' ')}'`).join(', ')}, or 'none')`);
|
|
183
190
|
}
|
|
184
191
|
out.push(id);
|
|
185
192
|
}
|
|
193
|
+
warnReusedRules(out, '--exclude-rules', reusedRuleAddresses(rules));
|
|
186
194
|
return [...new Set(out)].sort();
|
|
187
195
|
}
|
|
188
196
|
|
|
197
|
+
/**
|
|
198
|
+
* One stderr line for a retired address: it excludes nothing now, and the build goes on. The
|
|
199
|
+
* entry's `effect`, when set, says what the old exclusion no longer does.
|
|
200
|
+
*/
|
|
201
|
+
function warnRetiredRule(id, retired, where) {
|
|
202
|
+
const { note, effect } = retired.get(id);
|
|
203
|
+
process.stderr.write(`[geneseed] WARN: ${where}: '${id.replace('.', ' ')}' was retired `
|
|
204
|
+
+ `(${note})${effect ? `: ${effect}` : ''} — ignoring it.\n`);
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* A loud stderr line for each id in `ids` whose address a retired rule held and a different live
|
|
209
|
+
* rule holds now (`reusedRuleAddresses`): the exclusion binds the NEW rule, which an entry written
|
|
210
|
+
* for the old one never meant. It still binds — the line names both rules so a human decides.
|
|
211
|
+
*/
|
|
212
|
+
export function warnReusedRules(ids, where, reused = reusedRuleAddresses()) {
|
|
213
|
+
for (const id of ids.filter((x) => reused.has(x))) {
|
|
214
|
+
const { old, note, now } = reused.get(id);
|
|
215
|
+
process.stderr.write(`[geneseed] WARN: ${where}: '${id.replace('.', ' ')}' NOW EXCLUDES `
|
|
216
|
+
+ `${now.name} (${now.id}), NOT the retired ${old} (${note}) that held this address before. `
|
|
217
|
+
+ `If this exclusion was written for ${old}, remove it.\n`);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
|
|
189
221
|
/**
|
|
190
222
|
* `--exclude-skills "bruno,openscad"` -> the cfg's skill exclusion array.
|
|
191
223
|
*
|
package/js/build/emit-claude.mjs
CHANGED
|
@@ -17,6 +17,7 @@ import { get, isDict, isTruthy } from '../lib/json.mjs';
|
|
|
17
17
|
import { relPosix } from '../lib/text.mjs';
|
|
18
18
|
import { assertSourceComplete, phaseLog, ensureMemoryStore } from './bundle.mjs';
|
|
19
19
|
import { foldOnEmit } from './fold.mjs';
|
|
20
|
+
import { pruneRetiredSkills } from './retired-skills.mjs';
|
|
20
21
|
import {
|
|
21
22
|
claimAndWrite, globalMemory, globalNotebook, shipLeanLaws, stripCapabilityLinks,
|
|
22
23
|
} from './emit-common.mjs';
|
|
@@ -124,6 +125,8 @@ export function emitClaudeRender(cfg, job) {
|
|
|
124
125
|
// One shared `claim` (see `claimer`): the skills/agents writer and the Bob command writer
|
|
125
126
|
// below both push into the same `owned` list, so a pre-manifest-install warning still
|
|
126
127
|
// prints once across the whole emit rather than once per writer.
|
|
128
|
+
// Before the claim: a retired folder freed here lets this emit write the alias that replaces it.
|
|
129
|
+
if (sharedRoot !== null) pruneRetiredSkills(host, cfgDir, oldOwned);
|
|
127
130
|
const claim = claimer(oldOwned, cfgDir, true, oldHashes);
|
|
128
131
|
const { nAgents, nSkills, written } = writeNativeLayer(
|
|
129
132
|
items, path.join(cfgDir, 'agents'), path.join(cfgDir, 'skills'),
|
|
@@ -21,6 +21,7 @@ import {
|
|
|
21
21
|
claimAndWrite, globalMemory, globalNotebook, shipLeanLaws, stripCapabilityLinks,
|
|
22
22
|
} from './emit-common.mjs';
|
|
23
23
|
import { foldOnEmit } from './fold.mjs';
|
|
24
|
+
import { pruneRetiredSkills } from './retired-skills.mjs';
|
|
24
25
|
import { renderAll } from './render.mjs';
|
|
25
26
|
import {
|
|
26
27
|
ensureExcludesStub, ensureNotebookIndex, ensureProfileStub, ensureRulesStub,
|
|
@@ -220,6 +221,9 @@ export function emitOpencodeGlobalRender(cfg, job) {
|
|
|
220
221
|
// Co-owned, so never in `owned` — see `opencodeSentinelWrite`.
|
|
221
222
|
opencodeSentinelWrite(cfgDir);
|
|
222
223
|
|
|
224
|
+
// As in `emitClaudeRender`: before the skill layer claims anything.
|
|
225
|
+
if (sharedRoot !== null) pruneRetiredSkills('opencode', cfgDir, oldOwned);
|
|
226
|
+
|
|
223
227
|
// `manifestExisted` is deliberately not passed, so
|
|
224
228
|
// the pre-manifest header line is unreachable from this emit.
|
|
225
229
|
const {
|