geneseed 5.0.3 → 5.0.4
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 +38 -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 +151 -0
- package/docs/concepts/hooks.md +1 -1
- package/docs/concepts/host-matrix.md +1 -0
- package/docs/concepts/loop-gates.md +3 -0
- package/docs/concepts/loops.md +1 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/extending.md +5 -1
- package/docs/guides/autostart.md +2 -0
- package/docs/guides/run-a-factory.md +88 -0
- package/docs/guides/set-up-ownership.md +1 -0
- 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 +35 -2
- package/harness.config.json +1 -1
- package/js/README.md +20 -2
- package/js/build/args.mjs +14 -2
- package/js/build/source.mjs +19 -0
- package/js/cli-table.json +166 -2
- package/js/factory/cli.mjs +153 -0
- package/js/factory/graph.mjs +245 -0
- package/js/factory/registry.mjs +71 -0
- package/js/factory/state.mjs +429 -0
- package/js/hosts/activity.mjs +3 -3
- 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/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 +24 -12
- package/js/loop/cli.mjs +21 -15
- package/js/loop/graph.mjs +13 -4
- package/js/loop/registry.mjs +65 -28
- package/js/loop/state.mjs +18 -8
- package/js/web/api.mjs +43 -1
- package/js/web/catalog.mjs +38 -2
- package/js/web/daemon.mjs +136 -6
- package/js/web/handler.mjs +14 -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/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 +18 -0
- package/src/bricks/merge-gate.md +22 -0
- package/src/bricks/pr-open.md +21 -0
- package/src/bricks/retro.md +17 -0
- 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 +34 -0
- package/src/factories/bug-report-to-fix.json +32 -0
- package/src/factories/issue-to-pr.json +49 -0
- package/src/skills/_checkpoints.md +1 -0
- package/src/skills/adhd.md +1 -1
- package/src/skills/factory-forge.md +97 -0
- package/src/skills/factory.md +126 -0
- 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-BaoxwVFH.js} +1 -1
- package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-C_bFD0rW.js} +1 -1
- package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-B01lLf0m.js} +1 -1
- package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-Bc66KPyA.js} +1 -1
- package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
- package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-LRYVnGLG.js} +2 -2
- package/web/dist/assets/Factories-ARenKBiP.js +1 -0
- package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-CfWR2-sX.js} +1 -1
- package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-nfFHnovH.js} +3 -3
- package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-lpOHcHKK.js} +1 -1
- package/web/dist/assets/{Kits-XQHsazCN.js → Kits-Bw5EQl_i.js} +1 -1
- package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
- package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
- package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
- package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
- package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-CggG0_sK.js} +1 -1
- package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-BObvlb70.js} +2 -2
- package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-BFfPMPc9.js} +1 -1
- package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-B594Pad_.js} +1 -1
- package/web/dist/assets/api-DLDVY3K-.js +1 -0
- package/web/dist/assets/{index-BNttaGQb.js → index-DsLmKHw0.js} +3 -3
- package/web/dist/assets/index-DvPjphz0.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,48 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [5.0.4] — 2026-11-09
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
- **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.
|
|
15
|
+
- **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`.
|
|
16
|
+
- **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.
|
|
17
|
+
- **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`.
|
|
18
|
+
- **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.
|
|
19
|
+
- **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.
|
|
20
|
+
- **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.
|
|
21
|
+
- **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.
|
|
22
|
+
- **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.
|
|
23
|
+
- **`geneseed loop init --factory <slug>`** stores on the loop's registry row the factory run the loop is a stage of.
|
|
24
|
+
- **`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.
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
- **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.
|
|
28
|
+
- **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.
|
|
29
|
+
- **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.
|
|
30
|
+
- **The loop engine ignores `FACTORY.md`** in its scoring and porcelain checks, as it ignores `LOOP.md`. Loop behaviour is otherwise unchanged.
|
|
31
|
+
- **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.
|
|
32
|
+
- **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.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
- **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.
|
|
36
|
+
- **`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.
|
|
37
|
+
- **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".
|
|
38
|
+
- **`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.
|
|
39
|
+
- **`geneseed loop init --note-file <path>`** now reads the starting note from the file, as `record` does. Before, `init` ignored the flag.
|
|
40
|
+
- **`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.
|
|
41
|
+
- **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.
|
|
42
|
+
- **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.
|
|
43
|
+
- **`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.
|
|
44
|
+
- **The docs list Factory actions after Loop actions.** The two pages had the same `order:`.
|
|
45
|
+
- **`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.
|
|
46
|
+
|
|
11
47
|
## [5.0.3] — 2026-11-08
|
|
12
48
|
|
|
13
49
|
### Added
|
|
14
50
|
|
|
51
|
+
- **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.
|
|
52
|
+
- **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
53
|
- **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
54
|
- **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
55
|
- **`--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.0.4**.
|
|
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 (comms 5 merged into comms 1 on 2026-11-08), the rebuild prints a WARN, drops that address, and goes on. 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,151 @@
|
|
|
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, see [Run a factory](../guides/run-a-factory.md).
|
|
11
|
+
|
|
12
|
+
A **factory** carries one work item (a request, a document or analysis, or a GitHub or GitLab
|
|
13
|
+
issue) through a graph of **stages** to an open pull request with green CI. A stage is a
|
|
14
|
+
[brick](loop-bricks.md) or a whole [loop](loops.md). `geneseed factory` is the state machine: it
|
|
15
|
+
decides every transition, cycle count and stop, and the `factory` [skill](skills.md) runs the stage
|
|
16
|
+
it is handed. **A run never merges.** It ends at "PR open, CI green", and the merge is yours.
|
|
17
|
+
|
|
18
|
+
> **You already know this:** a ticket moving across a board — triaged, worked, reviewed, shipped
|
|
19
|
+
> for review. A failed check sends the card back a column, but only so many times before someone
|
|
20
|
+
> has to look at it.
|
|
21
|
+
|
|
22
|
+
## Stages, and the routes back
|
|
23
|
+
|
|
24
|
+
A factory is the loop graph one level up. Each stage reports an outcome, and each outcome has
|
|
25
|
+
one edge: to the next stage, to `$close`, or to `$stop`. A `loop:<name>` stage runs a whole loop
|
|
26
|
+
in the same worktree and reports `pass` when that loop closed, `fail` when it stopped.
|
|
27
|
+
|
|
28
|
+
A failure may route back to an earlier stage: red CI at `merge-gate` sends the work back to the
|
|
29
|
+
loop that wrote it. Every such route sits inside a declared **cycle** with a `max` (5 at most).
|
|
30
|
+
Each lap back to the cycle's first stage spends one; past the `max`, the run stops. A route back
|
|
31
|
+
always starts a **fresh** loop: a new `LOOP.md`, whose first note is the reason the last lap
|
|
32
|
+
failed. When two cycles share that first stage, the lap spends the smallest one that holds the
|
|
33
|
+
stage it came from: a failed `holdout` spends `holdout`, a red `merge-gate` spends `ci`. The commits made before stay on the branch. A run also stops after 30 stage transitions,
|
|
34
|
+
whatever its cycles say.
|
|
35
|
+
|
|
36
|
+
`geneseed factory check` refuses a factory before any stage runs: an unknown brick or loop, an
|
|
37
|
+
outcome with no edge, a `$close` nothing reaches, a cycle with no `max`, a cycle entered anywhere
|
|
38
|
+
but its first stage, or a route back that spends no cycle.
|
|
39
|
+
|
|
40
|
+
## Forks and lanes
|
|
41
|
+
|
|
42
|
+
A **fork** is where the work takes one way or another. It is a brick that declares **named
|
|
43
|
+
outcomes**, any outcome other than `pass`, `fail`, `error` or `none`. `triage` is one: `bug`,
|
|
44
|
+
`feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
|
|
45
|
+
stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
|
|
46
|
+
hands the fork its `lanes`: each outcome with the stage it leads to.
|
|
47
|
+
|
|
48
|
+
Not every factory runs a loop, and not every lane is one. A loop is the lane for work that
|
|
49
|
+
changes code, because the loop carries the test → fix → verify proof. A brick is the lane where a
|
|
50
|
+
loop adds nothing: in `issue-to-pr`, `docs` goes to the `docs-update` brick, which commits its own
|
|
51
|
+
change. Every lane joins the same path after it: `holdout`, then `pr-open` and `merge-gate`.
|
|
52
|
+
|
|
53
|
+
A route back after a fork targets **`$lane`**: the stage the run's most recent fork chose. The
|
|
54
|
+
engine records it in `FACTORY.md` when the fork's outcome is recorded, and an edge to `$lane` goes
|
|
55
|
+
there. A cycle may start at `$lane` too, and each route back to it spends one lap, as any route
|
|
56
|
+
back does. `check` refuses `$lane` in a factory with no fork, or where some path reaches it before
|
|
57
|
+
any fork. In its other checks, `$lane` stands for every lane, so a graph that passes holds for the
|
|
58
|
+
lane any run takes.
|
|
59
|
+
|
|
60
|
+
A factory written before forks used a `loop:$triaged` stage and a `loops` list. Both are retired:
|
|
61
|
+
`check` names each with its replacement, and the doctor reports it. Nothing rewrites your file.
|
|
62
|
+
|
|
63
|
+
## One worktree, two state files
|
|
64
|
+
|
|
65
|
+
A run works on its own branch, `loop/factory-<slug>`, in its own worktree. `FACTORY.md` at the
|
|
66
|
+
root holds the run's state; while a loop stage runs, its `LOOP.md` sits beside it. The loop
|
|
67
|
+
engine treats `FACTORY.md` as bookkeeping, as it treats `LOOP.md`: it never scores it. A stage
|
|
68
|
+
that is not a loop records only on a clean worktree, and `factory record` refuses a dirty tree
|
|
69
|
+
after one. A brick that changes files, such as a `docs-update` lane, commits them first. The one
|
|
70
|
+
exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it, and
|
|
71
|
+
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
|
|
72
|
+
names the run it belongs to.
|
|
73
|
+
|
|
74
|
+
## The shipped factories
|
|
75
|
+
|
|
76
|
+
| Factory | Stages |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| `analysis-to-build` | `intake` → `spec` → `holdout-write` → `loop:feature` → `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, and one PR opens at the end. A failed `holdout` or a red `merge-gate` sends the work back to `loop:feature` as one extra task, twice at most each (cycles `holdout` and `ci`) |
|
|
79
|
+
| `bug-report-to-fix` | `intake` → `holdout-write` → `loop:bugfix` → `holdout` → `pr-open` → `merge-gate` → `retro` → `$close`. A failed `holdout` or a red `merge-gate` sends the fix back to `loop:bugfix`, twice at most each (cycles `holdout` and `ci`) |
|
|
80
|
+
| `issue-to-pr` | `intake` → `holdout-write` → `triage`, a fork → one lane → `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 `holdout` or a red `merge-gate` sends the work back to `$lane`, that same lane, twice at most each (cycles `holdout` and `ci`) |
|
|
81
|
+
|
|
82
|
+
The bricks they add:
|
|
83
|
+
|
|
84
|
+
| Brick | Does | Outcomes |
|
|
85
|
+
| --- | --- | --- |
|
|
86
|
+
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria | `pass`, `fail` |
|
|
87
|
+
| `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` |
|
|
88
|
+
| `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` |
|
|
89
|
+
| `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` |
|
|
90
|
+
| `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
|
|
91
|
+
| `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 | `pass`, `fail`, `none` |
|
|
92
|
+
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
|
|
93
|
+
|
|
94
|
+
`analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
|
|
95
|
+
`spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
|
|
96
|
+
docs lane.
|
|
97
|
+
|
|
98
|
+
The run report is git-ignored by the `.geneseed/.gitignore` Geneseed seeds. Where no such file is
|
|
99
|
+
in the worktree, `retro` writes the report to the OS temp directory instead, so the tree stays
|
|
100
|
+
clean. The report lives in the worktree and goes when you remove it.
|
|
101
|
+
|
|
102
|
+
## Holdout scenarios
|
|
103
|
+
|
|
104
|
+
A loop's tests are written by the same agent that writes the code, so they can share its
|
|
105
|
+
blind spots. A factory therefore keeps a second set of checks the developer never sees. After
|
|
106
|
+
`intake` (or `spec`), the `holdout-write` stage writes 3 to 8 scenarios in plain prose, each a
|
|
107
|
+
`Given` / `When` / `Then`, to `~/.config/geneseed/holdout/<slug>/` (under `$XDG_CONFIG_HOME` when
|
|
108
|
+
it is set): outside the worktree, so no commit, diff or loop note carries them. After the loop,
|
|
109
|
+
the `holdout` stage plays each scenario against the change as built and reports.
|
|
110
|
+
|
|
111
|
+
- **On a failure**, the work goes back to the loop with one sentence per failed scenario: what was
|
|
112
|
+
observed against what was expected. Never the scenario's text. That lap spends the `holdout`
|
|
113
|
+
cycle, twice at most.
|
|
114
|
+
- **On `error`**, the run stops: the diff touches the holdout folder, or a scenario cannot be
|
|
115
|
+
played.
|
|
116
|
+
- **One folder per slug.** `holdout-write` reports `fail` when the folder already holds files from
|
|
117
|
+
an earlier run with the same slug; clear it yourself, then run again.
|
|
118
|
+
- **Who sees them.** Both stages run as the `tester` agent. The `factory` skill never puts holdout
|
|
119
|
+
content or the folder's path into a brief, a note or a carry.
|
|
120
|
+
- **No hook refuses a read of it**, on any host. A Claude Code read gate was built but is not
|
|
121
|
+
shipped: it would run a hook process on every Read, Grep and Glob of every session (about 90 ms
|
|
122
|
+
each on Windows) for a protection only a factory run uses. The folder is protected only by its place
|
|
123
|
+
outside the worktree, by `holdout`'s `error`, and by the skill's rule. A shell command such as
|
|
124
|
+
`cat` is not covered on any host.
|
|
125
|
+
|
|
126
|
+
## In the console
|
|
127
|
+
|
|
128
|
+
The console's **Factories** page (in the Build group, after Loops) draws each factory as a
|
|
129
|
+
graph: its stages left to right, a `loop:` stage as a block that holds its loop's ring, each
|
|
130
|
+
route back as an arc above the row with its cycle and `max`, and `close` and `stop` as end caps.
|
|
131
|
+
Its **Active** tab lists every registered run, with the current stage lit, the laps spent on
|
|
132
|
+
each cycle and the child loop's current step. 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
|
|
133
|
+
agent's session.
|
|
134
|
+
|
|
135
|
+
## Your own factories
|
|
136
|
+
|
|
137
|
+
Factories load from three levels, as bricks and loop templates do, and a later level overrides
|
|
138
|
+
an earlier one by name: shipped, global (`~/.config/geneseed/factories/`), and project
|
|
139
|
+
(`<repo>/.geneseed/factories/`).
|
|
140
|
+
|
|
141
|
+
To compose or change one, use the `factory-forge` skill — ask it. It interviews you for the
|
|
142
|
+
stages, the routes back and their `max`, writes the file at project or global level and runs
|
|
143
|
+
`geneseed factory check` until it passes. When a stage needs a brick that does not exist, it
|
|
144
|
+
offers the `brick-forge` skill: that skill alone writes bricks.
|
|
145
|
+
|
|
146
|
+
## Read on
|
|
147
|
+
|
|
148
|
+
- [Run a factory](../guides/run-a-factory.md): how to start one, and what it asks you.
|
|
149
|
+
- [Loops](loops.md): what runs inside a `loop:` stage.
|
|
150
|
+
- [Human gates](loop-gates.md): the stages that wait for a person.
|
|
151
|
+
- [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,9 @@ 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
|
+
`merge-gate` (holds on `none` — the repo runs no CI on the PR) is the shipped one.
|
|
18
|
+
|
|
16
19
|
`geneseed loop decide --verdict ok|no|amend` answers it:
|
|
17
20
|
|
|
18
21
|
- **`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)).
|
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 to shut down on `/api/shutdown` with `X-Geneseed-Secret`: a MAC of the port under the install secret in `.geneseed-web-secret` (32 random bytes, mode 0600, created once next to the daemon record). The secret itself is never sent, and no pid is ever signalled, so a listener that only claims our root cannot cause harm. 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:
|
|
@@ -0,0 +1,88 @@
|
|
|
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. The run never merges: the PR is yours to review and merge.
|
|
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 a run
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
run the bug-report-to-fix factory on issue 412
|
|
34
|
+
take this bug report through the factory: totals round the wrong way on refunds
|
|
35
|
+
run the issue-to-pr factory on issue 418
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The agent then:
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
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.
|
|
42
|
+
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, `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 scenario or red CI then sends the work back to that lane.
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
## Build from an analysis
|
|
47
|
+
|
|
48
|
+
`analysis-to-build` takes a larger piece of work: a design document, an analysis pasted into the
|
|
49
|
+
chat, or a plain request. It splits the work into tasks that you approve, then builds them one by
|
|
50
|
+
one in the same worktree, and opens one PR at the end.
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
run the analysis-to-build factory on docs/analysis/export-csv.md
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
1. `intake` writes the work item from the document.
|
|
57
|
+
2. `spec` writes `specs/<slug>/spec.md`: the scope, acceptance criteria in EARS form, and an
|
|
58
|
+
ordered task list (20 tasks at most). The run then stops for you. Read the spec and answer
|
|
59
|
+
`ok`, `no`, or `amend` with your corrections; an amend rewrites the spec.
|
|
60
|
+
3. After your `ok`, the agent commits the spec (the commit asks you), `holdout-write` writes the
|
|
61
|
+
holdout scenarios from it, and the agent runs the `feature` loop once per task, in order.
|
|
62
|
+
`geneseed factory next` names each one as `task <i>/<n>`.
|
|
63
|
+
4. After the last task, `holdout` plays the scenarios, `pr-open` opens one PR for all of them,
|
|
64
|
+
and `merge-gate` waits for CI.
|
|
65
|
+
5. A failed scenario sends the work back to the `feature` loop as one extra task, with one
|
|
66
|
+
sentence per failure (observed against expected) as its first note. Red CI does the same, with
|
|
67
|
+
the failing checks as the note: "make CI green". Each is twice at most; a third failure stops
|
|
68
|
+
the run.
|
|
69
|
+
|
|
70
|
+
## Where it stops for you
|
|
71
|
+
|
|
72
|
+
| Moment | What you decide |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| 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. |
|
|
75
|
+
| A push | Every push that is not a loop's own commit asks you, `pr-open`'s included. |
|
|
76
|
+
| A loop gate | Anything the `bugfix` loop asks you, as in [While a loop runs](loop-running.md). |
|
|
77
|
+
| `merge-gate` reports `none` | The repo runs no CI on the PR: `ok` goes on to `retro`, `no` stops the run. |
|
|
78
|
+
| 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. |
|
|
79
|
+
|
|
80
|
+
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. A holdout `error` stops the run: the diff touched the holdout folder, or a scenario could not be played.
|
|
81
|
+
|
|
82
|
+
## When it ends
|
|
83
|
+
|
|
84
|
+
On success the agent reports the PR, 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.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
**Next:** [Factories](../concepts/factories.md)
|