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
package/CHANGELOG.md
CHANGED
|
@@ -8,10 +8,93 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [5.1.0] — 2026-11-09
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
- **Every shipped factory checks the work after the loop, and the `checks` and `review-panel` bricks.** `checks` (as `tester`) runs the repo's done list as the base branch holds it, never the branch's copy; a red command or a command that changes a tracked file fails it; a timeout, a missing tool, a failed fetch or no default branch is an `error` whose finding starts `environment:` and holds for you; the tree is restored afterwards, whatever the outcome. Once every command passes, a diff that touches a locked path holds for you. The locked paths are the done list, `.github/workflows/`, `.gitlab-ci.yml`, `.geneseed/factories/`, `loops/`, `bricks/`, and each path in the factory's new `protected` list, a rename's old path included. At that gate, `ok` lets it through, `no` stops. With no done list on the base, `checks` proposes one from the base's manifests and holds; on your yes it goes to the base by a PR of its own for you to merge, and `checks` runs again once. `review-panel` seats agents by the work item's size and areas from the factory's new `review.seats` table (default: `reviewer`, plus `tester` for medium, plus `steward` for large; `security`, `performance` or `user-advocate` by area), each blind to how the change was built, and merges their verdicts. The order is now loop → `checks` → `review-panel` → `holdout` → `pr-open` → `merge-gate` → `retro`; a failed check or review sends the work back to the loop, twice at most each (cycles `checks` and `review`). `geneseed factory check` refuses a seat that names no shipped agent (a project's own agents are not seats), a size with no list, and a malformed `protected`.
|
|
15
|
+
- **`intake` can ask.** It reports `needs-info` when a question only you can answer blocks the work, and holds: answer with `amend` (three times at most), go on with its stated assumptions with `ok`, or stop with `no`. `needs-info` names no lane, so `intake` is not a fork. It also rates the work item's `size` and `areas` for the review panel. Factories written before keep working, and so do runs in progress: the `needs-info` edge is optional, and without one, `ok` follows intake's `pass` edge. Add the edge only to route `needs-info` elsewhere.
|
|
16
|
+
- **The merge is proposed at the end.** After the close commit, when CI is green, the `factory` skill shows the PR, the CI state and the review verdicts, and asks you once whether to merge; on yes it squash-merges. A run still never merges without that yes, and never enables auto-merge.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
- **A reinstall or upgrade moves aside the skills an old build left behind.** Every global emit (so `rebuild-all`, `upgrade` and `migrate` too) moves each `skills/<name>` folder that an earlier build rendered under a name that no longer ships (an old alias or a retired skill), and that no manifest owns, to `<config dir>/archived-skills/<name>/<timestamp>/`, on Claude Code, Bob, OpenClaude and OpenCode, with one `pruned retired skill` line each. A folder moves only when it is a plain, readable directory with no links in it and its `SKILL.md` has the Geneseed render shape (`name:`, a JSON-quoted `description:`, and outside code fences a `# <theme skill label>: <name or the skill it aliases>` heading); a same-name skill of your own stays, and `migrate --dry-run` still lists it as an orphan.
|
|
20
|
+
- **`geneseed migrate --dry-run` prints `would prune`** for each folder the next emit moves, now for OpenCode too; `/api/migrate/preview` gains a `prunes` list, and `orphans` lists only what stays.
|
|
21
|
+
- **The Factories page draws every `loop:` stage as a compact box.** On the main path as in a fork's lanes, a loop stage names its loop over `whole loop` (or `not in catalogue`), and during a run `at <node>` names the child loop's step. The ring no longer sits inside the factory graph; the Loops page still draws it.
|
|
22
|
+
- **The factory transition ceiling is 60 per task** (was 30), and so at most 1200 over a run, for the two new stages and their laps.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
- **The factory counts spec tasks as CommonMark reads the list.** A numbered line nests only from the text of the task above it, so tasks indented 1 or 2 spaces, or under a two-digit marker, are no longer lost; a backtick fence whose info string holds a backtick no longer hides the tasks under it; a heading indented 1–3 spaces, or a setext heading, now ends the list; and a task's own indented paragraph, `---` or `##` no longer ends it.
|
|
26
|
+
- **`geneseed factory record --spec` says what it checks:** a `spec.md` one folder under `specs/`.
|
|
27
|
+
- **A hand-edited `FACTORY.md` is refused for every stage it names** that the factory graph does not hold, and for an `awaiting` that does not match the status; `decide` on such a file gives the readable-state error, not a TypeError.
|
|
28
|
+
- **Every `geneseed factory` path argument is relative to the current directory.** `--spec` used to resolve against the git root.
|
|
29
|
+
- **`geneseed factory record --carry-file` and `decide --note-file`:** free text (your words, a stop reason) is written by the agent's file tool to a file, never put on the command line.
|
|
30
|
+
- **The factory skill pipes the porcelain into `geneseed factory record` in one command** (`git status --porcelain --untracked-files=all | geneseed factory record …`), in a POSIX shell and in PowerShell; `record` strips the CRLF and the leading BOM Windows PowerShell 5.1 can add. A record line whose spec path, carry path or outcome holds `commit` or `push` still makes the git gate ask: a false alarm, answer yes. `factory init` refuses a slug holding `git`, `commit` or `push`, which removes the commonest case.
|
|
31
|
+
- **A project factory that shadows a shipped one is named** in `geneseed factory check` (`overridden`), a factory parse problem names its level, and a project file that does not load makes `factory init` refuse instead of running the shipped graph of that name.
|
|
32
|
+
- **`geneseed factory check` refuses an environment outcome routed to a loop:** `checks` `error` and `merge-gate` `none` may not lead to a `loop:` stage or `$lane`.
|
|
33
|
+
- **An amended fork no longer keeps its old lane**, and **an amend at the spec gate may add tasks even after a loop that ran before the spec**: only the first task loop freezes the count.
|
|
34
|
+
- **A spec under a non-ASCII slug records:** the engine unquotes git's quoted porcelain paths.
|
|
35
|
+
- **`merge-gate` reads CI from the checks' states, never the exit code**; a red (1) or pending (8) exit is a verdict, not an environment failure.
|
|
36
|
+
- **The review panel no longer reviews `FACTORY.md` and `LOOP.md`**, and **the run report finds the notes of closed loops in git**.
|
|
37
|
+
- **The merge proposal states its guard truthfully:** `gh pr merge` runs only on your explicit yes in chat; no Geneseed gate asks before it.
|
|
38
|
+
- **The factory docs state the transition ceilings right** (60 per task, 1200 at most over a run, gated against the engine), the `factory-forge` example lists the stages of the factory it names, and a done-list branch that already exists on the remote is reported, not pushed over.
|
|
39
|
+
- **`geneseed web start` ends an unrecorded console of this install by challenge and response.** The console hands out a single-use nonce that lives 30 s, and the proof covers the port and that nonce, so a proof an impostor collects while the console is down can no longer shut the real console down later. A console from before this change gets no proof: it is named and left running, to be ended by hand once.
|
|
40
|
+
- **`geneseed web start` names a console of this install without the shutdown secret** (a foreground `geneseed web`, or a daemon that could not read its secret) and says how to stop it, instead of reading as an impostor.
|
|
41
|
+
- **An `--exclude-rules "comms 5"` exclusion (the retired *Mark the Ask*) says what it stopped doing:** the ask markers now bind inside comms 1, so the exclusion no longer removes them.
|
|
42
|
+
- **A rule exclusion whose address once belonged to a retired rule, and now belongs to a different live rule, warns loudly at build time**, naming both rules.
|
|
43
|
+
- **The Factories graph draws a fork only where the engine sees one**: a brick that declares a named outcome. A `loop:` stage, or a brick whose pass/fail edges reach two stages, is no longer drawn as lanes. Many routes back into one stage now land inside its box instead of overflowing it.
|
|
44
|
+
- **Factories › Active** says which install's catalogue drew a run's bricks and loops, shows "No runs yet" when the active-runs payload has no `factories` list instead of loading forever, and a catalogue payload without `factories` no longer crashes the page.
|
|
45
|
+
- **Stacked library list:** a click on the open row no longer keeps the list open for a later Ctrl-K jump from outside, and ArrowDown from the filter unfolds a folded list before it focuses the first row.
|
|
46
|
+
- **The pinned Primary agent row follows the text, category and Show filters**, so "No matches" and the picker count agree with the rows; its loadout is read once. "Show all rules" in the Loadout panel collapses again when you open another agent.
|
|
47
|
+
- **`docs/web-ui.md`** describes both ways to start a factory (the agent request and the by-hand worktree command), the fork definition, and the catalogue the Active tab borrows.
|
|
48
|
+
- **A loop's discard no longer stashes `FACTORY.md`.** The `loop` skill's discard kept only `LOOP.md` out of the stash, so a loop run as a factory stage stashed the factory's state with the attempt: an untracked `FACTORY.md` was lost, and a tracked one rolled its counters back. The discard now keeps both engine files, and the `checks` and `review-panel` bricks, which delete the untracked files their commands created, never touch either.
|
|
49
|
+
- **`geneseed factory record --spec` refuses a spec that is not at `specs/<slug>/spec.md`.** It took any path inside the worktree and stored it, and every later action then refused `FACTORY.md` as unreadable. The refusal now comes first, names the required shape, and leaves the state as it was. The `--spec` help names the shape too.
|
|
50
|
+
- **An amend at the spec gate may add tasks.** The factory froze the task count at the first `--spec` record, which comes before the spec's human gate, so a spec amended to list more tasks was refused. The count, and the run-wide ceiling with it, now follow each `--spec` record until the first loop launches; from then on they are frozen as before. The amend cap of 3, the per-task ceiling and the 20-task cap still bound every run.
|
|
51
|
+
- **A factory run with no loop closes cleanly.** The `factory` skill closed every run with `git rm -f FACTORY.md`, which fails in the `docs` lane of `issue-to-pr`: no loop runs there, so `FACTORY.md` is never tracked. The close step now deletes an untracked `FACTORY.md`, and commits and pushes only when there is a removal to commit; with no close commit, the final CI state is the one `merge-gate` read.
|
|
52
|
+
- **The `spec` brick states the task format the factory counts.** It now names the heading the engine looks for, the numbered-item forms, the indentation and where the list ends, and refers to the factory's task limit. In a factory it names the run's slug (it said the loop's title) and takes an amendment from the stage's carry (it said LOOP.md's notes); in a loop it keeps both as before. The count now matches it: a numbered sub-item (` 1.` under `1.`) is no longer counted as a task, and a fenced block in the list no longer ends it at a `# comment` line.
|
|
53
|
+
- **An environment failure no longer goes back to the loop.** `checks` reported a failed fetch, no default branch, a timeout or a missing tool as a `fail`, and `merge-gate` reported CI still pending after 30 minutes as a `fail`; every factory routes `fail` back to the loop, whose code cannot fix them, so each one burned laps and cycles. `checks` now reports them as `error` and `merge-gate` as `none`, each with a finding that starts `environment:`. Both outcomes already hold for you: `amend` runs the stage again once the environment is fixed, `no` stops. No factory graph changes. The `factory-forge` skill says never to route those outcomes to a loop.
|
|
54
|
+
- **A proposed done list reaches the base by PR, never by a push to it.** At `checks` `none`, the `factory` skill pushed the done list straight to the default branch, against the rule every factory gives every stage: push only your own branch. It now commits the file in a separate worktree on its own branch, `geneseed/done-list-<slug>`, pushes that branch and opens a PR for you to merge; `ok` still waits until the file is on the base.
|
|
55
|
+
|
|
56
|
+
## [5.0.4] — 2026-11-09
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
- **The Factories page draws a factory vertically, with its forks.** Stages run top to bottom; the lanes of a fork sit side by side, each labelled with its outcome, and join again at the first stage they all reach. Routes back are rails on the left (`↺ <cycle> · max N`), stop edges one rail on the right; a live run lights the lane it took and the stage it stands on. A loop stage's ring is about twice its old size. The graph never scrolls sideways: in a narrower pane its rails become tags and its lanes shrink to compact boxes, and only below about 524 px do the lanes stack.
|
|
60
|
+
- **The factory engine and `geneseed factory`.** A factory carries one work item through a graph of stages, each a brick or a whole loop (`loop:<name>`). A failure may route back to an earlier stage, but only through a declared cycle with its `max` (5 at most). The state lives in `FACTORY.md` beside the child loop's `LOOP.md`. Every run ends by construction: 30 stage transitions per task, and a run-wide ceiling fixed at the first spec record (20 tasks at most). The CLI has the actions `check`, `list`, `init`, `next`, `record` and `decide`. It refuses an outcome that contradicts the child loop's `LOOP.md`, a dirty tree after a stage outside a loop, and a hand-edited `FACTORY.md` past the engine's bounds. See `docs/reference/factory-actions.md`.
|
|
61
|
+
- **The first shipped factory, `bug-report-to-fix`, and the `factory` skill.** The factory runs `intake` → `loop:bugfix` → `pr-open` → `merge-gate` → `retro`, and red CI at `merge-gate` sends the fix back to the loop, twice at most. The run ends at an open PR with green CI; the merge stays yours. The `factory` skill creates the run's worktree on `loop/factory-<slug>`, steps the engine, and runs each loop stage through the `loop` skill in that same worktree. Four new bricks: `intake` (reads a request, a document, or a GitHub or GitLab issue), `pr-open` (pushes, which asks, and opens or updates the PR), `merge-gate` (waits for CI, 30 minutes at most, and asks you when the repo has no CI) and `retro` (writes the run report to `.geneseed/factory-runs/<slug>.md`). Each run is registered in `factories.json` beside the loop registry. See `docs/concepts/factories.md` and `docs/guides/run-a-factory.md`. Run `geneseed rebuild-all` to get the skill.
|
|
62
|
+
- **A Factories page in the console**, in the rail's Build group after Loops. **Templates** lists the factories an install resolves and draws the selected one as a graph: its stages as blocks left to right, joined by lines labelled with their outcomes; each `loop:` stage as a block holding its loop's ring; each route back as an arc above the row with its cycle and `max`; `close` and `stop` as end caps. **Active** lists every registered run, polled, and draws it with its current stage lit, its cycle laps, its task number, and the child loop's current node. It reads `GET /api/factories/catalog` and `GET /api/factories/active`. It changes nothing in a run; the Active poll only drops finished runs older than 7 days from `factories.json`, as Loops › Active does for `loops.json`.
|
|
63
|
+
- **A second shipped factory, `issue-to-pr`, and the `triage` brick.** The factory runs `intake` → `holdout-write` → `triage` → one lane → `holdout` → `pr-open` → `merge-gate` → `retro`. `triage` is a fork: it reads the work item and reports the outcome that names its lane (`bug`, `feature`, `deps`, `refactor` for the matching loop, `docs` for the `docs-update` brick). A failed scenario or red CI sends the work back to that same lane, twice at most each. The merge stays yours.
|
|
64
|
+
- **Factory forks, named outcomes and `$lane`.** A brick that declares an outcome other than `pass`, `fail`, `error` or `none` is a fork: each outcome has its own edge to its own lane, a loop or a brick. `geneseed factory next` hands a fork its `lanes`, and the outcome recorded names the lane taken, kept in `FACTORY.md` as `lane`. An edge target or a cycle node may be `$lane`, the stage the run's most recent fork chose, so a route back returns to the lane the run took. `geneseed factory check` refuses `$lane` with no fork, or before any fork on some path; cycles, their `max` and the transition ceilings are unchanged. The `loop:$triaged` stage, the factory's `loops` list and `record --loop` are retired: `check` (and so the doctor) names each with its replacement, and never rewrites a user's file.
|
|
65
|
+
- **The `factory-forge` skill.** It composes bricks and loops into a factory of your own. It interviews you for the input, the stages, the human gates, the failures that route back and their `max` (5 at most), then writes `.geneseed/factories/<name>.json` (project) or `~/.config/geneseed/factories/<name>.json` (global). It runs `geneseed factory check` until the file passes and explains each rule a problem names. When a stage needs a brick that does not exist, it offers the `brick-forge` skill or runs it: `brick-forge` stays the only skill that writes bricks. Then it hands the factory to the `factory` skill. Run `geneseed rebuild-all` to get the skill.
|
|
66
|
+
- **A third shipped factory, `analysis-to-build`.** The factory runs `intake` → `spec` → `loop:feature` → `pr-open` → `merge-gate` → `retro`. The `spec` stage writes `specs/<slug>/spec.md` with an ordered task list, and you approve it at its gate; the spec is then committed, and `loop:feature` runs once per task, in order, in one worktree, with one PR at the end. Red CI after the last task sends the work back to the loop as one extra task: `geneseed factory next` hands out the last task's index with `extra` set to the stage that sent it back (`"merge-gate reported fail"`). That lap spends cycle `ci` (twice at most) and the transition ceilings, and gives no fresh budget.
|
|
67
|
+
- **Holdout scenarios in every shipped factory, and the `holdout-write` and `holdout` bricks.** After `intake` (or `spec`), `holdout-write` writes 3 to 8 prose scenarios (given / when / then) to `~/.config/geneseed/holdout/<slug>/`, outside the worktree. After the loop, `holdout` plays them against the built change, before `pr-open`. A failed scenario sends the work back to the loop with one sentence per failure (observed against expected, never the scenario's text), twice at most (cycle `holdout`). `error` stops the run, for example when the diff touches the holdout folder. Both stages run as `tester`, and the `factory` skill never hands holdout content to the developer. No hook refuses a read of the folder on any host: it is protected by its place outside the worktree, by `holdout`'s `error` and by the skill's rule.
|
|
68
|
+
- **`geneseed loop init --factory <slug>`** stores on the loop's registry row the factory run the loop is a stage of.
|
|
69
|
+
- **`geneseed loop init --note <text>`** starts the new loop's notes with that text, so a factory can hand on the reason a stage failed.
|
|
70
|
+
|
|
71
|
+
### Changed
|
|
72
|
+
- **The console's Library, Loops and Factories pages stack their panes when the page is narrow.** When the page has less than 1174 px for these panes (for example half a window), the reader could not keep 560 px beside the rail and the list. The panes now go one under the other, each block only as tall as its content. Under the page header comes a toolbar card: the sections as one row of buttons with their counts (the open one filled with the accent), the filter with the usage filter beside it, and the categories as chips (only for a section with categories). Next comes a picker card: its header shows how many entries the filter leaves and which one is open; under it, about five rows scroll on their own. Picking a row keeps the picker open, so the next entry is one click away. A link to an entry from outside the list opens with the picker closed, and a section opens with it open. The entry comes last, as a plain card. A locked Library (Personal › Memory, Notebook) stacks only under 942 px. The reader no longer scrolls sideways: the start command and code blocks wrap, a source path breaks after a slash, and a loop ring scales up to its own drawn width (it was capped at 680 px, which drew the widest shipped ring at 82%). The ring takes the width that keeps its labels at 11 px or more before "How it runs" sits beside it; a reader narrower than that still shrinks them. The Constitution's packs column and the Docs map's piece panel go under their content when it runs out of room, not at a fixed 1180 px window width.
|
|
73
|
+
- **The Library's Loadout panel, redrawn.** The total in tokens comes first, with the install it was read from and the delta against the primary as pills. The bar shows three groups (Constitution, Catalogues, This agent) instead of one slice per block, each with its own card; the Constitution card is folded for an Adept. The rules start with the ones the agent's spec cites, then one pill per pack, and the full list sits behind "Show all". What is not counted moves to a footnote.
|
|
74
|
+
- **The Constitution table's last columns read Status, Rule text, Enforced by, Hook gate**, so each switch sits beside what it acts on. When the table is narrower than 760 px, Status and Enforced by still fold into chips under the rule name.
|
|
75
|
+
- **The loop engine ignores `FACTORY.md`** in its scoring and porcelain checks, as it ignores `LOOP.md`. Loop behaviour is otherwise unchanged.
|
|
76
|
+
- **Doctrine comms 5, *Mark the Ask*, merged into comms 1, now *Codes and Markers*.** Both rules set the reply format and shared one example, so one rule now holds the reference codes and the ask markers. The id `mark-the-ask` is retired and never reused; the doctrines now hold 30 rules. An install that excluded `comms 5` gets a warning ("comms 5 was retired") and excludes nothing; the rebuild does not fail. *Automate Repetition* (craft 1) and *Search Before Creating* (craft 4) lose the sentences that repeated each other, and the Memory section points to *Persist Insight* instead of restating it. The lean root is about 900 characters shorter. Run `geneseed rebuild-all` to get it.
|
|
77
|
+
- **Five situational rules keep one line in the lean root.** *Edit the Source, Not the Surface*, *Record the Probe, Not the Snapshot*, *Restart Is Not Reload*, *Serialize Against a Rationed Resource* (ops 3, 5, 6, 7) and *External Gate* (rigor 5) now carry one trigger sentence in a lean install; the full text stays in the pack file, which the root already points to. The full footprint does not change. The `parallel-agents` and `workflow` skills cite *Serialize Against a Rationed Resource* at their fan-out step. The lean root is about 1 200 characters shorter, and the lean size ceiling drops from 41 612 to 40 312. Run `geneseed rebuild-all` to get it.
|
|
78
|
+
|
|
79
|
+
### Fixed
|
|
80
|
+
- **A loop can pass in a project with no linter.** The `test` brick listed a check the project does not have as `SKIPPED`, which the engine rightly refuses for a `pass`, so `bugfix` and `feature` could never close on such a repo (found by the factory end-to-end run). The brick now lists it as `<check>: N/A (not configured)`; a check that exists but did not run is still `SKIPPED` and still blocks.
|
|
81
|
+
- **`pr-open` builds the PR body from what it is given.** It asked for the loop's notes, which leave with `LOOP.md` when the loop closes; it now uses the run's `requirement` and `input` and the branch's commit subjects.
|
|
82
|
+
- **The Loadout panel no longer counts user rules a sub-agent never receives.** On a host with no SubagentStart wiring (Bob, OpenCode), or an install emitted before it, the user rules render muted with the reason and are left out of "Rules it follows".
|
|
83
|
+
- **`geneseed factory record` no longer accepts `pass` from a loop stage on a HEAD move alone.** With no `LOOP.md` left, `pass` now also needs the loop registry to show a `geneseed loop init` in the worktree after `factory next`. `next` stores the launch time, and each `loop init` stamps the registry row with a new `initAt`. Without that evidence only `fail` is accepted.
|
|
84
|
+
- **`geneseed loop init --note-file <path>`** now reads the starting note from the file, as `record` does. Before, `init` ignored the flag.
|
|
85
|
+
- **`FACTORY.md` is checked more strictly.** A gate amend count above 3, a chosen loop outside the factory's `loops`, an unknown status, or a `history` or `cycles` that is not a list is refused as unreadable. A `cycles: {}` no longer makes `record` crash. The fourth gate amend still stops the run, but now stores 3, so the stopped `FACTORY.md` stays readable.
|
|
86
|
+
- **Project factories at `.geneseed/factories/` are no longer git-ignored.** The `.geneseed/.gitignore` Geneseed seeds now lets `factories/` back in, as it does `bricks/` and `loops/`. A repo seeded before keeps its file: add the line `!/factories/` to it by hand.
|
|
87
|
+
- **The factory's close commit no longer leaves the CI state unread.** Its push re-runs CI after `merge-gate` saw it green; the `factory` skill now reads the checks once more, with the same 30-minute bound, and the run report and the final report give that state.
|
|
88
|
+
- **`merge-gate` waits with a command that returns by itself.** It polled once a minute, but hosts refuse a foreground `sleep`. It now runs `gh pr checks <pr> --watch --interval 30` or `glab ci status --wait`, each call bounded under 10 minutes, repeated up to 30 minutes, then reads the verdict once.
|
|
89
|
+
- **The docs list Factory actions after Loop actions.** The two pages had the same `order:`.
|
|
90
|
+
- **`geneseed web restart` no longer leaves the old console running on the preferred port.** When port 4747 is taken, `web start` and `web restart` now identify the holder through `/api/ping`, which carries a hash of the install root. A console of the same install is asked to shut down with an install secret (an owner-only file next to the daemon record, never sent as such) and the port taken; no process is ever signalled by pid. Another program, a console of another install, or a console too old to carry the root are never touched: the command prints a line naming the port and the holder, then says which port it served on instead. A foreground `geneseed web` that loses the bind says so too. The Restart button of a console that is no longer the recorded daemon says that, with the recorded address, instead of "foreground server". `web status` also lists a console on 4747 that is not the recorded one.
|
|
91
|
+
|
|
11
92
|
## [5.0.3] — 2026-11-08
|
|
12
93
|
|
|
13
94
|
### Added
|
|
14
95
|
|
|
96
|
+
- **Sub-agents now receive your `user-rules.md`.** No sub-agent ever got the SessionStart output, so rules written for sub-agents reached none. On Claude Code and OpenClaude, `SubagentStart` now runs `geneseed-hook context` (it ran `activity` before; the Activity record still runs), which reads the event name and injects every `user-rules.md` layer (shared tier, install, project root) as one JSON `hookSpecificOutput.additionalContext`, under the same 9 000-character budget and cut as SessionStart. The profile and project context are not injected: the root file already reaches a sub-agent. The budget holds for the JSON line itself, after escaping. The project-root layer is the `user-rules.md` at the root SessionStart discovers from (`$GENESEED_ROOT`, else `$CLAUDE_PROJECT_DIR`, else the hook's working dir), not the git root of the payload's `cwd`. OpenCode follows in a later release; Bob has no `SubagentStart` event. Re-emit an install to wire it. A global install emitted with this change stands down on `SubagentStart` in a project whose earlier-emitted project install already runs `context` (on SessionStart), so that project's sub-agents get no rules, and the Loadout panel shows it as not wired, until the project install is re-emitted too.
|
|
97
|
+
- **The Library shows what each agent loads.** Agents gets a pinned first row for the main agent (neutral **Primary agent**, imperial **Servant**, a new `PRIMARY_AGENT` theme noun) with a **base** pill, and every agent's detail gets a **Loadout** panel: a stacked bar of what it loads (the root file by section, the session files or the user rules, both catalogues, an Adept's spec), the delta against the primary, and the rules it follows, grouped by kind, each linking to its Laws row and marked when the Adept's spec cites it. The figures come from `agentLoadout` (`js/inspect/cost.mjs`), which shares its measurements with the Overview's always-on cost; `GET /api/loadout` and `/api/loadout/<agent>` serve them. An install emitted before this release shows its user rules as not wired until it is re-emitted.
|
|
15
98
|
- **Two new opt-in kits, `ci-pipelines` and `docker`.** `ci-pipelines` adds the `jenkins-pipeline` skill (declarative `Jenkinsfile`, shared libraries, CPS and `@NonCPS`, sandbox approval, credentials, `parallel` and `when`, JenkinsPipelineUnit) and the `gitlab-ci` skill (`rules:`, `needs:`, `include:` and `extends:`, caching and artifacts, protected and masked variables, environments, CI lint), with rules and a banned list for GitLab's older job-condition keywords, which GitLab no longer actively develops. `docker` adds the `compose-ops` skill for running any Compose stack: health-ordered startup, volumes, pinned images, secrets, restart, limits, logging, networks, lean non-root images, and safe updates with rollback. The spring-boot kit's `docker-expert` now says it covers the image and its dev Compose file only. Both kits are off by default, so installs without them are unchanged. To turn one on, run `geneseed build --emit <target> --kits ci-pipelines` (or `docker`), or use **Installs → Kits** in the web console.
|
|
16
99
|
- **The Constitution page repeats its column header under every open band.** Ethos, Dictates and each doctrine pack get their own compact header row (No., Rule, Latin name, Status, Enforced by, plus the two switch columns where they exist); a folded pack has none. The single header above the Dictates is gone.
|
|
17
100
|
- **`--no-external-gate` stops the protected-check and gate-configuration asks** on every host: `rule-gate`, the shell path in `git-gate`, Bob's `tool-gate`, the OpenCode guard and OpenCode 2's `evaluate` ask. Other gates keep running, and OpenCode's own `permission.edit` keys stay. With it off the agent can edit the other gates' wiring unasked.
|
package/README.md
CHANGED
|
@@ -11,9 +11,9 @@
|
|
|
11
11
|
[](package.json)
|
|
12
12
|
[](package.json)
|
|
13
13
|
[](themes/)
|
|
14
|
-
[](src/skills/)
|
|
15
15
|
[](src/agents/)
|
|
16
|
-
[](src/doctrines/)
|
|
17
17
|
[](adapters/opencode/plugins/)
|
|
18
18
|
[](#-supported-harnesses)
|
|
19
19
|
|
|
@@ -180,7 +180,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
|
|
|
180
180
|
| **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
|
|
181
181
|
| **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
|
|
182
182
|
| **🤖 Agents** (20) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `performance`, `explorer`, `researcher`, `developer`, `memory-curator` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
|
|
183
|
-
| **🛠 Skills** (
|
|
183
|
+
| **🛠 Skills** (51) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **adhd** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **deck** · **prose** · **ingest** · **research** · **teach** · **learn-mode** · **ownership** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **pipeline** · **loop** · **factory** · **factory-forge** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** · **diagram-design** |
|
|
184
184
|
| **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
|
|
185
185
|
| **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
|
|
186
186
|
| **🔗 Shared tier** (`~/.config/geneseed`) | one machine-wide home for memory, your rules, profile, wiki manifest, exclude paths and notes, read by every global install on every host; existing stores [fold into it](docs/guides/upgrade-to-5.md) on the next global rebuild, and a project install opts in with `--shared-tier on` |
|
package/SHIPPED.md
CHANGED
|
@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
|
|
|
20
20
|
> **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
|
|
21
21
|
> human-readable label only. The canonical identity of an installed harness is the
|
|
22
22
|
> **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
|
|
23
|
-
> string. Current label: **5.0
|
|
23
|
+
> string. Current label: **5.1.0**.
|
|
24
24
|
|
|
25
25
|
## Capabilities
|
|
26
26
|
|
|
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names the design record.
|
|
|
29
29
|
| Capability | What it is | Spec |
|
|
30
30
|
| --- | --- | --- |
|
|
31
31
|
| **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
|
|
32
|
-
| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 20 agents,
|
|
32
|
+
| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 20 agents, 51 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
|
|
33
33
|
| **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Ownership, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
|
|
34
34
|
| **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
|
|
35
35
|
| **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |
|
|
@@ -78,7 +78,11 @@ absolute-path hooks instead — `geneseed setup` does that for you.) It:
|
|
|
78
78
|
and auto-compaction is the moment that window is about to be summarised away.
|
|
79
79
|
This captures memory *before* the summary; the SessionStart `context` hook (which
|
|
80
80
|
also fires on the `compact` source) re-seeds context *after* it.
|
|
81
|
-
- on **
|
|
81
|
+
- on **SubagentStart**, runs `geneseed-hook context`, which reads the event name and hands the
|
|
82
|
+
sub-agent your `user-rules.md` layers (tier, install, project root) as one JSON
|
|
83
|
+
`hookSpecificOutput.additionalContext`. No sub-agent receives the SessionStart output, so this
|
|
84
|
+
is the only way your rules reach one.
|
|
85
|
+
- on **UserPromptSubmit** and **SessionEnd**, runs `geneseed-hook activity`, which decides
|
|
82
86
|
nothing and prints nothing: it records the session for the web console's Activity view.
|
|
83
87
|
Every other hook above feeds that view too, after it has decided. `GENESEED_ACTIVITY=off`
|
|
84
88
|
(or the console's toggle) turns it off; see `docs/reference/plugin-activity.md`.
|
|
@@ -58,7 +58,9 @@ global config file.
|
|
|
58
58
|
The Claude group set, unchanged: `PreToolUse` (git gate on `Bash|PowerShell`, rule gate on
|
|
59
59
|
writes), `SessionStart` (context on every source — one matcher-less group covers
|
|
60
60
|
`startup`, `resume`, `clear`, `compact` and `fork` alike), `Stop`,
|
|
61
|
-
`SubagentStop` and `PreCompact` (learn),
|
|
61
|
+
`SubagentStop` and `PreCompact` (learn), `SubagentStart` (`context`, which hands a sub-agent
|
|
62
|
+
your `user-rules.md` layers as `hookSpecificOutput.additionalContext`; OpenClaude 0.32.0's
|
|
63
|
+
bundle reads that field for this event), and `UserPromptSubmit` and `SessionEnd`
|
|
62
64
|
(`activity`, which feeds the web console's Activity view). OpenClaude reads Claude's
|
|
63
65
|
`hookSpecificOutput.permissionDecision`, so the gates **ask** where Claude asks.
|
|
64
66
|
The context hook carries `--host openclaude` for one reason. It tells the hook
|
|
@@ -125,7 +125,7 @@ function isolationReport(stats) {
|
|
|
125
125
|
// user's own edit survives; its failure never costs the trace. The same string lives in
|
|
126
126
|
// `workflows/_runtime.js` (a plugin cannot share a file — V2 loads every .js here as a
|
|
127
127
|
// plugin — and the runtime is imported lazily, from a configurable dir); tests pin both.
|
|
128
|
-
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
128
|
+
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
129
129
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
130
130
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
131
131
|
async function writeGitignore(file) {
|
|
@@ -198,7 +198,7 @@ async function runChildSession(client, { prompt, agent, model, title, directory
|
|
|
198
198
|
// (bricks, loops, check lists) allowed back. Anchored `/*`, because a bare `*` matches at
|
|
199
199
|
// every depth and would hide `bricks/x.md` even under `!bricks/`. Same string as
|
|
200
200
|
// GENESEED_GITIGNORE in plugins/geneseed-workflow.js; both are pinned by tests.
|
|
201
|
-
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
201
|
+
const GENESEED_GITIGNORE = "/*\n!/.gitignore\n!/bricks/\n!/loops/\n!/factories/\n!/protected-checks.txt\n!/done-checks.txt\n"
|
|
202
202
|
// Create-if-absent; a file holding only `*` is Geneseed's former output (it hid team bricks),
|
|
203
203
|
// never a user edit, so it is upgraded. Any other content is the user's. Never throws.
|
|
204
204
|
async function writeGitignore(file) {
|
package/bin/geneseed-cli.mjs
CHANGED
|
@@ -143,6 +143,9 @@ const VERBS = {
|
|
|
143
143
|
// Task 5. A fourth native verb: a state machine with
|
|
144
144
|
// no recorded cell to compare against, only the absolute gates named beside it in `NATIVE`.
|
|
145
145
|
loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
|
|
146
|
+
// The factory engine, the loop engine one level up: native like `loop`, gated absolutely by
|
|
147
|
+
// tests/unit/factory_cli.test.mjs.
|
|
148
|
+
factory: () => import('../js/factory/cli.mjs').then((m) => m.cmdFactory),
|
|
146
149
|
// A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
|
|
147
150
|
// (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
|
|
148
151
|
// tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -125,7 +125,9 @@ const VERBS = {
|
|
|
125
125
|
*/
|
|
126
126
|
async function baselineStores(verb, args) {
|
|
127
127
|
try {
|
|
128
|
-
|
|
128
|
+
// A SubagentStart carries the PARENT's session_id: a baseline there would reset the parent's.
|
|
129
|
+
if (verb !== 'context' || !args.root || args.event === 'SubagentStart' || process.env.GENESEED_LEARN_CHILD
|
|
130
|
+
|| isatty(0)) return;
|
|
129
131
|
const raw = readStdin();
|
|
130
132
|
if (!raw.includes('session_id')) return;
|
|
131
133
|
const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
|
|
@@ -175,7 +177,7 @@ function die(code, msg) {
|
|
|
175
177
|
*/
|
|
176
178
|
function parse(spec, argv) {
|
|
177
179
|
const args = {
|
|
178
|
-
root: null, host: null, memory: null, consolidate: false, noConsent: false,
|
|
180
|
+
root: null, host: null, event: null, memory: null, consolidate: false, noConsent: false,
|
|
179
181
|
noDeletionGate: false, noSecretsGate: false, noDoneGate: false, noOwnershipGate: false,
|
|
180
182
|
noExternalGate: false, noTestNote: false, noRuleStore: false, noRootScan: false, file: null,
|
|
181
183
|
};
|
|
@@ -262,6 +264,12 @@ async function main(argv) {
|
|
|
262
264
|
// `hooks.md`, "Stop, SubagentStop, TaskCompleted, and TeammateIdle").
|
|
263
265
|
return die(1, parsed.error);
|
|
264
266
|
}
|
|
267
|
+
// `context` answers SessionStart and SubagentStart (settings.mjs), told apart by the payload's
|
|
268
|
+
// event name. Read here, not in the verb, so an in-process caller never blocks on fd 0; the read
|
|
269
|
+
// is cached, so `trackActivity` reuses it. A terminal sends no payload.
|
|
270
|
+
if (verb === 'context' && !isatty(0)) {
|
|
271
|
+
try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
|
|
272
|
+
}
|
|
265
273
|
const rc = (await spec.load())[spec.fn](parsed.args);
|
|
266
274
|
await trackActivity(verb, parsed.args);
|
|
267
275
|
await baselineStores(verb, parsed.args);
|
package/docs/PRD.md
CHANGED
|
@@ -103,7 +103,7 @@ sequenceDiagram
|
|
|
103
103
|
| NFR-001 | No runtime dependencies. | 0 installed; vendored only | `tests/unit/dependency_policy.test.mjs` | ✅ | `js/vendor/` |
|
|
104
104
|
| NFR-002 | The hook is cheap: it loads on every tool call. | ~14 ms to load | Stated in `AGENTS.md`; no automated budget found, `⚠ to confirm` | ◐ | `bin/geneseed-hook.mjs` |
|
|
105
105
|
| NFR-003 | Context hook output stays under the host's cap. | 9 000 characters | `OUTPUT_BUDGET` | ✅ | `js/hosts/hooks-context.mjs` |
|
|
106
|
-
| NFR-004 | The rules file stays within its size ceiling. |
|
|
106
|
+
| NFR-004 | The rules file stays within its size ceiling. | 40 312 lean, 66 432 full | `CARRIER_CEILING` | ✅ | `js/inspect/cost.mjs` |
|
|
107
107
|
| NFR-005 | The generator and hook path cannot spawn beyond what is declared. | No `child_process` on the generator; one spawn site on the hook path | Closure walks | ✅ | `tests/unit/hook_cli.test.mjs` |
|
|
108
108
|
| NFR-006 | The upgrade doctor gate is bounded. | 300 s | A timeout reports a gate that did not finish | ✅ | `js/maintain/update.mjs` |
|
|
109
109
|
| NFR-007 | The console serves only this machine. | Local port 4747 by default, with request guards | [Web console security](web-ui.md#security-model) | ✅ | `js/web/server.mjs` |
|
package/docs/README.md
CHANGED
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
| Set up | [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
|
|
30
30
|
| Set up | [MCP servers](guides/mcp.md) · [MarkItDown](guides/mcp-markitdown.md) · [GitLab](guides/mcp-gitlab.md) · [Filesystem](guides/mcp-filesystem.md) · [Reading non-markdown docs](guides/read-non-markdown.md) | Where the config lives, the three presets, and reading PDF and Office files |
|
|
31
31
|
| Loops | [Run a loop](guides/run-a-loop.md) · [Which loop template](guides/loop-which-template.md) · [While a loop runs](guides/loop-running.md) · [Finish a loop](guides/loop-finish.md) | Working a requirement as small, validated, committed iterations |
|
|
32
|
+
| Factories | [Run a factory](guides/run-a-factory.md) | Carrying one bug report or issue to an open PR with green CI |
|
|
32
33
|
| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
|
|
33
34
|
| Keep it running | [Upgrade to 5.0](guides/upgrade-to-5.md) | A 4.x machine reaching 5.0: what moves, what to check, how to go back |
|
|
34
35
|
| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
|
|
@@ -49,9 +50,11 @@
|
|
|
49
50
|
|
|
50
51
|
**Loops** — [Loops](concepts/loops.md) · [Templates](concepts/loop-templates.md) · [Bricks and their origins](concepts/loop-bricks.md) · [Notes and rules](concepts/loop-notes.md) · [Risk, trust and validation levels](concepts/loop-risk.md) · [Human gates](concepts/loop-gates.md) · [Contracts and ignored deletions](concepts/loop-contracts.md) · [LOOP.md, trailers and the loop branch](concepts/loop-branch.md)
|
|
51
52
|
|
|
53
|
+
**Factories** — [Factories](concepts/factories.md)
|
|
54
|
+
|
|
52
55
|
## 4 · Reference
|
|
53
56
|
|
|
54
|
-
**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
|
|
57
|
+
**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Factory actions](reference/factory-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
|
|
55
58
|
|
|
56
59
|
**Troubleshooting** (by symptom) — [Overview](reference/troubleshooting.md) · [Install](reference/troubleshoot-install.md) · [Hooks, context and memory](reference/troubleshoot-hooks.md) · [Model, agents and MCP](reference/troubleshoot-tools.md) · [Updating](reference/troubleshoot-update.md) · [Doctor findings](reference/troubleshoot-doctor.md) · [Web console](reference/troubleshoot-web.md)
|
|
57
60
|
|
|
@@ -97,7 +97,7 @@ follow them, not because a tool call was ever inspected.
|
|
|
97
97
|
`prove-the-gate`.
|
|
98
98
|
|
|
99
99
|
**Doctrine: comms** — `codes-that-persist` · `structure-beside-prose` · `declare-the-judgment-calls` ·
|
|
100
|
-
`simplified-technical-english
|
|
100
|
+
`simplified-technical-english`.
|
|
101
101
|
|
|
102
102
|
---
|
|
103
103
|
|
|
@@ -56,7 +56,7 @@ The finer switch removes a single doctrine rule from an install while keeping th
|
|
|
56
56
|
geneseed build --emit claude-global --exclude-rules "process 7"
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded.
|
|
59
|
+
The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. If a later version retires the rule, the rebuild prints a WARN, drops that address, and goes on. The WARN says what the exclusion no longer does: comms 5 (*Mark the Ask*) merged into comms 1 on 2026-11-08, so excluding `comms 5` no longer removes the ask markers, which now bind inside comms 1. If a new rule later takes a retired rule's address, an old exclusion of that address removes the new rule; the build then prints a loud WARN that names both rules, and the exclusion still applies until you remove it. The always-on Rules and the Ethos cannot be excluded.
|
|
60
60
|
|
|
61
61
|
**A hook goes with its rule.** Three doctrine rules are also enforced by a hook with no switch of its own, and excluding the rule, or building without its pack, drops that hook in the same rebuild. Including the rule again re-arms it at the next rebuild.
|
|
62
62
|
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: concepts
|
|
3
|
+
kind: "concept"
|
|
4
|
+
section: "Factories"
|
|
5
|
+
order: 24.5
|
|
6
|
+
title: "Factories"
|
|
7
|
+
link: {"hash":"#/docs/factory-actions","label":"The geneseed factory actions →"}
|
|
8
|
+
description: "What a factory is: one work item carried through bricks and whole loops to an open PR, with routes back when CI fails."
|
|
9
|
+
---
|
|
10
|
+
To run one, ask the agent in plain words ("Run the bug-report-to-fix factory on issue 412"). See
|
|
11
|
+
[Run a factory](../guides/run-a-factory.md#start-one-by-asking-the-agent).
|
|
12
|
+
|
|
13
|
+
A **factory** carries one work item (a request, a document or analysis, or a GitHub or GitLab
|
|
14
|
+
issue) through a graph of **stages** to an open pull request with green CI. A stage is a
|
|
15
|
+
[brick](loop-bricks.md) or a whole [loop](loops.md). `geneseed factory` is the state machine: it
|
|
16
|
+
decides every transition, cycle count and stop, and the `factory` [skill](skills.md) runs the stage
|
|
17
|
+
it is handed. **No stage merges.** A run ends at "PR open, CI green"; then the agent asks you once
|
|
18
|
+
whether to merge, and merges only on your yes.
|
|
19
|
+
|
|
20
|
+
> **You already know this:** a ticket moving across a board — triaged, worked, reviewed, shipped
|
|
21
|
+
> for review. A failed check sends the card back a column, but only so many times before someone
|
|
22
|
+
> has to look at it.
|
|
23
|
+
|
|
24
|
+
## Stages, and the routes back
|
|
25
|
+
|
|
26
|
+
A factory is the loop graph one level up. Each stage reports an outcome, and each outcome has
|
|
27
|
+
one edge: to the next stage, to `$close`, or to `$stop`. A `loop:<name>` stage runs a whole loop
|
|
28
|
+
in the same worktree and reports `pass` when that loop closed, `fail` when it stopped.
|
|
29
|
+
|
|
30
|
+
A failure may route back to an earlier stage: red CI at `merge-gate` sends the work back to the
|
|
31
|
+
loop that wrote it. Every such route sits inside a declared **cycle** with a `max` (5 at most).
|
|
32
|
+
Each lap back to the cycle's first stage spends one; past the `max`, the run stops. A route back
|
|
33
|
+
always starts a **fresh** loop: a new `LOOP.md`, whose first note is the reason the last lap
|
|
34
|
+
failed. When two cycles share that first stage, the lap spends the smallest one that holds the
|
|
35
|
+
stage it came from: a failed `holdout` spends `holdout`, a red `merge-gate` spends `ci`. The commits made before stay on the branch. Whatever its cycles say, a run also stops after 60
|
|
36
|
+
stage transitions for one task (the count starts again for each spec task it reaches), and after
|
|
37
|
+
60 transitions per spec task over the whole run: a spec lists 20 tasks at most, so no run passes
|
|
38
|
+
1200.
|
|
39
|
+
|
|
40
|
+
`geneseed factory check` refuses a factory before any stage runs: an unknown brick or loop, an
|
|
41
|
+
outcome with no edge, a `$close` nothing reaches, a cycle with no `max`, a cycle entered anywhere
|
|
42
|
+
but its first stage, or a route back that spends no cycle.
|
|
43
|
+
|
|
44
|
+
## Forks and lanes
|
|
45
|
+
|
|
46
|
+
A **fork** is where the work takes one way or another. It is a brick that declares **named
|
|
47
|
+
outcomes**, any outcome other than `pass`, `fail`, `error`, `none` or `needs-info`. `triage` is one: `bug`,
|
|
48
|
+
`feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
|
|
49
|
+
stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
|
|
50
|
+
hands the fork its `lanes`: each outcome with the stage it leads to.
|
|
51
|
+
|
|
52
|
+
Not every factory runs a loop, and not every lane is one. A loop is the lane for work that
|
|
53
|
+
changes code, because the loop carries the test → fix → verify proof. A brick is the lane where a
|
|
54
|
+
loop adds nothing: in `issue-to-pr`, `docs` goes to the `docs-update` brick, which commits its own
|
|
55
|
+
change. Every lane joins the same path after it: `checks`, `review-panel` and `holdout`, then
|
|
56
|
+
`pr-open` and `merge-gate`.
|
|
57
|
+
|
|
58
|
+
A route back after a fork targets **`$lane`**: the stage the run's most recent fork chose. The
|
|
59
|
+
engine records it in `FACTORY.md` when the fork's outcome is recorded, and an edge to `$lane` goes
|
|
60
|
+
there. A cycle may start at `$lane` too, and each route back to it spends one lap, as any route
|
|
61
|
+
back does. `check` refuses `$lane` in a factory with no fork, or where some path reaches it before
|
|
62
|
+
any fork. In its other checks, `$lane` stands for every lane, so a graph that passes holds for the
|
|
63
|
+
lane any run takes.
|
|
64
|
+
|
|
65
|
+
A factory written before forks used a `loop:$triaged` stage and a `loops` list. Both are retired:
|
|
66
|
+
`check` names each with its replacement, and the doctor reports it. Nothing rewrites your file.
|
|
67
|
+
|
|
68
|
+
## One worktree, two state files
|
|
69
|
+
|
|
70
|
+
A run works on its own branch, `loop/factory-<slug>`, in its own worktree. `FACTORY.md` at the
|
|
71
|
+
root holds the run's state; while a loop stage runs, its `LOOP.md` sits beside it. The loop
|
|
72
|
+
engine treats `FACTORY.md` as bookkeeping, as it treats `LOOP.md`: it never scores it. A stage
|
|
73
|
+
that is not a loop records only on a clean worktree, and `factory record` refuses a dirty tree
|
|
74
|
+
after one. A brick that changes files, such as a `docs-update` lane, commits them first. The one
|
|
75
|
+
exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it, and
|
|
76
|
+
it is committed once you approve it, before the first loop. Each run is listed in `factories.json` beside the loop registry, and each child loop's row
|
|
77
|
+
names the run it belongs to.
|
|
78
|
+
|
|
79
|
+
## The shipped factories
|
|
80
|
+
|
|
81
|
+
| Factory | Stages |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `analysis-to-build` | `intake` → `spec` → `holdout-write` → `loop:feature` → `checks` → `review-panel` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `spec` writes `specs/<slug>/spec.md` with an ordered task list, and you approve it at its gate. `loop:feature` then runs once per task, in order, in the same worktree; `checks` and `review-panel` run once, after the last task, and one PR opens at the end. A failed `checks`, `review-panel` or `holdout`, or a red `merge-gate`, sends the work back to `loop:feature` as one extra task, twice at most each (cycles `checks`, `review`, `holdout` and `ci`) |
|
|
84
|
+
| `bug-report-to-fix` | `intake` → `holdout-write` → `loop:bugfix` → `checks` → `review-panel` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. A failed `checks`, `review-panel` or `holdout`, or a red `merge-gate`, sends the fix back to `loop:bugfix`, twice at most each (cycles `checks`, `review`, `holdout` and `ci`) |
|
|
85
|
+
| `issue-to-pr` | `intake` → `holdout-write` → `triage`, a fork → one lane → `checks` → `review-panel` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. `triage` reports the lane: `bug` → `loop:bugfix`, `feature` → `loop:feature`, `deps` → `loop:deps-upgrade`, `refactor` → `loop:refactor`, `docs` → the `docs-update` brick. A failed `checks`, `review-panel` or `holdout`, or a red `merge-gate`, sends the work back to `$lane`, that same lane, twice at most each (cycles `checks`, `review`, `holdout` and `ci`) |
|
|
86
|
+
|
|
87
|
+
The bricks they add:
|
|
88
|
+
|
|
89
|
+
| Brick | Does | Outcomes |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions (`gate: human`) | `pass`, `fail`, `needs-info` |
|
|
92
|
+
| `holdout-write` | Writes 3 to 8 prose scenarios (given / when / then) for the work item into the holdout folder, outside the worktree, and hands the work item on unchanged | `pass`, `fail` |
|
|
93
|
+
| `holdout` | Plays every scenario against the built change. `fail` carries one sentence per failed scenario, observed against expected; `error` when the diff touches the holdout folder or a scenario cannot be played | `pass`, `fail`, `error` |
|
|
94
|
+
| `checks` | Runs the done list as the base branch holds it, never the branch's copy. `error` holds when the diff touches a locked path, or on an environment failure (a failed fetch, a timeout, a missing tool); `none` holds with a proposed list when the base has none | `pass`, `fail`, `error`, `none` |
|
|
95
|
+
| `review-panel` | The `factory` skill seats a panel sized to the work item, each seat blind to how the change was built, and merges their verdicts | `pass`, `fail` |
|
|
96
|
+
| `triage` | A fork: reads the work item and reports the outcome that names its lane, with its reason. `fail` when no lane fits | `bug`, `feature`, `deps`, `refactor`, `docs`, `fail` |
|
|
97
|
+
| `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
|
|
98
|
+
| `merge-gate` | Waits for the PR's CI with a watch that returns by itself (each call under 10 minutes), 30 minutes at most. A repo with no CI reports `none`, and you decide; so does CI still pending at the bound, or a `gh`/`glab` that is missing or fails | `pass`, `fail`, `none` |
|
|
99
|
+
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
|
|
100
|
+
|
|
101
|
+
`analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
|
|
102
|
+
`spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
|
|
103
|
+
docs lane.
|
|
104
|
+
|
|
105
|
+
The run report is git-ignored by the `.geneseed/.gitignore` Geneseed seeds. Where no such file is
|
|
106
|
+
in the worktree, `retro` writes the report to the OS temp directory instead, so the tree stays
|
|
107
|
+
clean. The report lives in the worktree and goes when you remove it.
|
|
108
|
+
|
|
109
|
+
## Checks and the review panel
|
|
110
|
+
|
|
111
|
+
A loop proves its work with commands it can also edit. After the loop, two stages check it from
|
|
112
|
+
outside.
|
|
113
|
+
|
|
114
|
+
- **`checks` reads the done list from the base branch** (`.geneseed/done-checks.txt` there, read
|
|
115
|
+
with `git show`), never from the branch, and runs it against the branch. A red command is a
|
|
116
|
+
`fail`. A timeout, a missing tool, a failed fetch or no default branch is an **environment
|
|
117
|
+
failure**: the loop's code cannot fix it, so it never goes back to the loop. It is an `error`
|
|
118
|
+
whose finding starts `environment:`, and it holds for you: fix the environment and answer
|
|
119
|
+
`amend` to run `checks` again, or `no` to stop (`ok` goes on without the done list). The same
|
|
120
|
+
rule holds at `merge-gate`: CI still pending after 30 minutes, or `gh`/`glab` missing, is a
|
|
121
|
+
`none` that holds for you, and `amend` waits again. A command that changes a tracked file is a `fail` too
|
|
122
|
+
(a lint that fixes what it finds hides what it found). Whatever the outcome, `checks` then
|
|
123
|
+
restores every file its commands changed and deletes what they created, so the tree stays clean.
|
|
124
|
+
- **Locked paths.** Only when every command passes, `checks` lists the paths the branch changed,
|
|
125
|
+
a rename's old path included, and looks for a **locked path**: the done list,
|
|
126
|
+
`.github/workflows/`, `.gitlab-ci.yml`, `.geneseed/factories/`, `.geneseed/loops/`,
|
|
127
|
+
`.geneseed/bricks/`, plus each entry of the factory's `protected` list. A path is locked when it
|
|
128
|
+
equals an entry, or lies under an entry that ends in `/`. That `error` holds for you: `ok` lets
|
|
129
|
+
the change through and the run report names it, `no` stops. Tests are not locked; the review
|
|
130
|
+
judges a weakened test.
|
|
131
|
+
- **No done list on the base**, or one with no command. `checks` proposes one, inferred from the
|
|
132
|
+
base's manifests as the done gate infers checks, and holds; with no manifest it proposes nothing
|
|
133
|
+
and says so. On your yes, the agent commits the file in a temporary worktree on its own branch,
|
|
134
|
+
pushes that branch and opens a PR to the base branch: every factory stage pushes only its own
|
|
135
|
+
branch, never the base. You merge the PR; once the file is on the base, `ok` runs `checks`
|
|
136
|
+
again, once.
|
|
137
|
+
- **`review-panel` seats agents by the work item's size and areas.** `intake` rates the `size`
|
|
138
|
+
(`small`, `medium`, `large`) and the `areas` (`security`, `performance`, `ui`, `data`). The
|
|
139
|
+
factory's `review.seats` maps them to agents; the shipped default is `reviewer` for small, plus
|
|
140
|
+
`tester` for medium, plus `steward` for large, with `security` for security or data,
|
|
141
|
+
`performance` for performance and `user-advocate` for ui. Each seat gets only the work item,
|
|
142
|
+
the diff and the factory's rules, in its own context: never the loop's notes or the holdout
|
|
143
|
+
scenarios, and it edits nothing. A failing verdict from `reviewer`, `security` or `tester`
|
|
144
|
+
fails the stage; `performance`, `steward` and `user-advocate` advise. A seat may name only an
|
|
145
|
+
agent Geneseed ships: `geneseed factory check` refuses any other, a project's own agents
|
|
146
|
+
included.
|
|
147
|
+
|
|
148
|
+
A failed check or review sends the work back to the loop, twice at most each (cycles `checks` and
|
|
149
|
+
`review`).
|
|
150
|
+
|
|
151
|
+
## Holdout scenarios
|
|
152
|
+
|
|
153
|
+
A loop's tests are written by the same agent that writes the code, so they can share its
|
|
154
|
+
blind spots. A factory therefore keeps a second set of checks the developer never sees. After
|
|
155
|
+
`intake` (or `spec`), the `holdout-write` stage writes 3 to 8 scenarios in plain prose, each a
|
|
156
|
+
`Given` / `When` / `Then`, to `~/.config/geneseed/holdout/<slug>/` (under `$XDG_CONFIG_HOME` when
|
|
157
|
+
it is set): outside the worktree, so no commit, diff or loop note carries them. After the loop,
|
|
158
|
+
the `holdout` stage plays each scenario against the change as built and reports.
|
|
159
|
+
|
|
160
|
+
- **On a failure**, the work goes back to the loop with one sentence per failed scenario: what was
|
|
161
|
+
observed against what was expected. Never the scenario's text. That lap spends the `holdout`
|
|
162
|
+
cycle, twice at most.
|
|
163
|
+
- **On `error`**, the run stops: the diff touches the holdout folder, or a scenario cannot be
|
|
164
|
+
played.
|
|
165
|
+
- **One folder per slug.** `holdout-write` reports `fail` when the folder already holds files from
|
|
166
|
+
an earlier run with the same slug; clear it yourself, then run again.
|
|
167
|
+
- **Who sees them.** Both stages run as the `tester` agent. The `factory` skill never puts holdout
|
|
168
|
+
content or the folder's path into a brief, a note or a carry.
|
|
169
|
+
- **No hook refuses a read of it**, on any host. A Claude Code read gate was built but is not
|
|
170
|
+
shipped: it would run a hook process on every Read, Grep and Glob of every session (about 90 ms
|
|
171
|
+
each on Windows) for a protection only a factory run uses. The folder is protected only by its place
|
|
172
|
+
outside the worktree, by `holdout`'s `error`, and by the skill's rule. A shell command such as
|
|
173
|
+
`cat` is not covered on any host.
|
|
174
|
+
|
|
175
|
+
## In the console
|
|
176
|
+
|
|
177
|
+
The console's **Factories** page (in the Build group, after Loops) draws each factory as a
|
|
178
|
+
graph: its stages top to bottom, a fork's lanes side by side, a `loop:` stage as a compact box
|
|
179
|
+
that names its loop over `whole loop`, each route back as a rail on the left with its cycle and
|
|
180
|
+
`max`, and `close` and `stop` as end caps.
|
|
181
|
+
Each factory shows how to start it: the request to give the agent, and the commands to start it
|
|
182
|
+
by hand, the worktree first and then `geneseed factory init`. Its **Active** tab lists every
|
|
183
|
+
registered run, with the current stage lit, the laps spent on each cycle and the child loop's
|
|
184
|
+
current step, written `at <node>` in the current stage's box. The page changes nothing in a run (its poll only drops finished runs older than 7 days from `factories.json`, as Loops does); you answer a run in the
|
|
185
|
+
agent's session.
|
|
186
|
+
|
|
187
|
+
## Your own factories
|
|
188
|
+
|
|
189
|
+
Factories load from three levels, as bricks and loop templates do, and a later level overrides
|
|
190
|
+
an earlier one by name: shipped, global (`~/.config/geneseed/factories/`), and project
|
|
191
|
+
(`<repo>/.geneseed/factories/`).
|
|
192
|
+
|
|
193
|
+
To compose or change one, use the `factory-forge` skill — ask it. It interviews you for the
|
|
194
|
+
stages, the routes back and their `max`, writes the file at project or global level and runs
|
|
195
|
+
`geneseed factory check` until it passes. When a stage needs a brick that does not exist, it
|
|
196
|
+
offers the `brick-forge` skill: that skill alone writes bricks.
|
|
197
|
+
|
|
198
|
+
## Read on
|
|
199
|
+
|
|
200
|
+
- [Run a factory](../guides/run-a-factory.md): how to start one, and what it asks you.
|
|
201
|
+
- [Loops](loops.md): what runs inside a `loop:` stage.
|
|
202
|
+
- [Human gates](loop-gates.md): the stages that wait for a person.
|
|
203
|
+
- [Factory actions](../reference/factory-actions.md): the `geneseed factory` commands.
|
package/docs/concepts/hooks.md
CHANGED
|
@@ -24,7 +24,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
24
24
|
| `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
|
|
25
25
|
| `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; prints nothing | off with `GENESEED_ACTIVITY=off` |
|
|
26
26
|
| `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
|
|
27
|
-
| `SubagentStart` | a subagent starts | `geneseed-hook
|
|
27
|
+
| `SubagentStart` | a subagent starts | `geneseed-hook context` | injects your `user-rules.md` layers into the subagent (as JSON `additionalContext`, under the same 9 000-character budget), and records the subagent as a branch of its session | the Activity record only, with `GENESEED_ACTIVITY=off` |
|
|
28
28
|
|
|
29
29
|
Every hook above also feeds the [Activity view](../reference/plugin-activity.md) after it has decided, unless tracking is off: one file per session under `activity/` beside the install. The gates' verdicts never wait on it.
|
|
30
30
|
|
|
@@ -13,6 +13,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
13
13
|
| Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
|
|
14
14
|
| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
|
|
15
15
|
| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
|
|
16
|
+
| Your `user-rules.md` handed to each sub-agent | — (later) | 🪝 hook | — (no `SubagentStart`) | 🪝 hook² |
|
|
16
17
|
| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
|
|
17
18
|
| Live sessions in the web console's [Activity view](../reference/plugin-activity.md) | ⚙️ plugin | 🪝 hook, files per subagent, context size | 🪝 hook, per tool call only (no transcript, no context size, subagent files not attributed)¹ | 🪝 hook, files per subagent, context size² |
|
|
18
19
|
| Real data loss (force-push to `main`, discarding uncommitted work, `rm` of untracked files…) | ⚙️ block³ · 🔒 ask (reflog, gc) | 🪝 ask | 🪝 block¹ | 🪝 ask² |
|
|
@@ -13,6 +13,12 @@ this way: the loop reports `{awaiting}` with `kind: "gate"` before the edge that
|
|
|
13
13
|
normally follow is taken at all — **the gate holds the whole transition**, so nothing is scored,
|
|
14
14
|
committed or counted against a ring budget while it waits.
|
|
15
15
|
|
|
16
|
+
A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`.
|
|
17
|
+
Three shipped bricks do: `intake` (holds on `needs-info` — it has questions only you can
|
|
18
|
+
answer), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
|
|
19
|
+
base branch has no done list yet) and `merge-gate` (holds on `none` — the repo runs no CI on the
|
|
20
|
+
PR).
|
|
21
|
+
|
|
16
22
|
`geneseed loop decide --verdict ok|no|amend` answers it:
|
|
17
23
|
|
|
18
24
|
- **`ok`** follows the edge the brick's reported outcome actually points to. On a brick gated on
|
package/docs/concepts/loops.md
CHANGED
|
@@ -78,6 +78,7 @@ evidence was never wired — no verdict is not a failure to repair.
|
|
|
78
78
|
- [Contracts and ignored deletions](loop-contracts.md): the globs that raise or ignore risk.
|
|
79
79
|
- [LOOP.md, trailers and the loop branch](loop-branch.md): the state file, the commit trailers, and why merging always asks.
|
|
80
80
|
- [Loop actions](../reference/loop-actions.md): the `geneseed loop` commands.
|
|
81
|
+
- [Factories](factories.md): one work item carried through bricks and whole loops to an open PR.
|
|
81
82
|
|
|
82
83
|
## Not foreman mode
|
|
83
84
|
|
package/docs/concepts/rules.md
CHANGED
|
@@ -23,7 +23,7 @@ When two instructions disagree, the higher one wins.
|
|
|
23
23
|
|
|
24
24
|
1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Ownership, Conduct): what the agent is for, how it weighs evidence, how it decides, who owns the code it writes, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
|
|
25
25
|
2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
|
|
26
|
-
3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
|
|
26
|
+
3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. Sub-agents get it too: on Claude Code and OpenClaude the `SubagentStart` hook injects every layer of it into each sub-agent, because no sub-agent receives the session-start output (OpenCode follows; Bob has no such event). The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
|
|
27
27
|
4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
|
|
28
28
|
5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a crew — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
|
|
29
29
|
6. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
|