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.
Files changed (128) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +3 -3
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +5 -1
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  7. package/adapters/opencode/workflows/_runtime.js +1 -1
  8. package/bin/geneseed-cli.mjs +3 -0
  9. package/bin/geneseed-hook.mjs +10 -2
  10. package/docs/PRD.md +1 -1
  11. package/docs/README.md +4 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/exclusions.md +1 -1
  14. package/docs/concepts/factories.md +151 -0
  15. package/docs/concepts/hooks.md +1 -1
  16. package/docs/concepts/host-matrix.md +1 -0
  17. package/docs/concepts/loop-gates.md +3 -0
  18. package/docs/concepts/loops.md +1 -0
  19. package/docs/concepts/rules.md +1 -1
  20. package/docs/extending.md +5 -1
  21. package/docs/guides/autostart.md +2 -0
  22. package/docs/guides/run-a-factory.md +88 -0
  23. package/docs/guides/set-up-ownership.md +1 -0
  24. package/docs/reference/factory-actions.md +22 -0
  25. package/docs/reference/loop-actions.md +1 -1
  26. package/docs/reference/plugin-activity.md +1 -1
  27. package/docs/web-ui.md +35 -2
  28. package/harness.config.json +1 -1
  29. package/js/README.md +20 -2
  30. package/js/build/args.mjs +14 -2
  31. package/js/build/source.mjs +19 -0
  32. package/js/cli-table.json +166 -2
  33. package/js/factory/cli.mjs +153 -0
  34. package/js/factory/graph.mjs +245 -0
  35. package/js/factory/registry.mjs +71 -0
  36. package/js/factory/state.mjs +429 -0
  37. package/js/hosts/activity.mjs +3 -3
  38. package/js/hosts/geneseed-dir.mjs +1 -1
  39. package/js/hosts/gitref.mjs +21 -0
  40. package/js/hosts/hooks-context.mjs +63 -9
  41. package/js/hosts/hooks-prims.mjs +1 -1
  42. package/js/hosts/settings.mjs +5 -4
  43. package/js/inspect/checks-authoring.mjs +11 -1
  44. package/js/inspect/cost.mjs +91 -5
  45. package/js/inspect/doctor.mjs +2 -1
  46. package/js/inspect/inventory.mjs +1 -1
  47. package/js/loop/catalog.mjs +24 -12
  48. package/js/loop/cli.mjs +21 -15
  49. package/js/loop/graph.mjs +13 -4
  50. package/js/loop/registry.mjs +65 -28
  51. package/js/loop/state.mjs +18 -8
  52. package/js/web/api.mjs +43 -1
  53. package/js/web/catalog.mjs +38 -2
  54. package/js/web/daemon.mjs +136 -6
  55. package/js/web/handler.mjs +14 -5
  56. package/js/web/routes.mjs +10 -3
  57. package/js/web/server.mjs +4 -1
  58. package/package.json +1 -1
  59. package/registry.json +14 -0
  60. package/src/AGENT.md.tmpl +5 -7
  61. package/src/bricks/docs-update.md +5 -0
  62. package/src/bricks/holdout-write.md +23 -0
  63. package/src/bricks/holdout.md +25 -0
  64. package/src/bricks/intake.md +18 -0
  65. package/src/bricks/merge-gate.md +22 -0
  66. package/src/bricks/pr-open.md +21 -0
  67. package/src/bricks/retro.md +17 -0
  68. package/src/bricks/test.md +4 -1
  69. package/src/bricks/triage.md +19 -0
  70. package/src/doctrines/comms.md +29 -41
  71. package/src/doctrines/craft.md +3 -10
  72. package/src/doctrines/ops.md +4 -15
  73. package/src/doctrines/rigor.md +1 -5
  74. package/src/factories/analysis-to-build.json +34 -0
  75. package/src/factories/bug-report-to-fix.json +32 -0
  76. package/src/factories/issue-to-pr.json +49 -0
  77. package/src/skills/_checkpoints.md +1 -0
  78. package/src/skills/adhd.md +1 -1
  79. package/src/skills/factory-forge.md +97 -0
  80. package/src/skills/factory.md +126 -0
  81. package/src/skills/parallel-agents.md +1 -1
  82. package/src/skills/workflow.md +2 -1
  83. package/themes/_TEMPLATE.json +4 -2
  84. package/themes/biker.json +4 -2
  85. package/themes/commentator.json +4 -2
  86. package/themes/cyberpunk.json +4 -2
  87. package/themes/gamer.json +4 -2
  88. package/themes/imperial.json +4 -2
  89. package/themes/joker.json +4 -2
  90. package/themes/marvin.json +4 -2
  91. package/themes/mean.json +4 -2
  92. package/themes/military.json +4 -2
  93. package/themes/neutral.json +4 -2
  94. package/themes/pirate.json +4 -2
  95. package/themes/sports.json +4 -2
  96. package/themes/verstappen.json +4 -2
  97. package/themes/wizard.json +4 -2
  98. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  99. package/web/dist/assets/{Activity-Ck_Xffpo.js → Activity-BaoxwVFH.js} +1 -1
  100. package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-C_bFD0rW.js} +1 -1
  101. package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-B01lLf0m.js} +1 -1
  102. package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-Bc66KPyA.js} +1 -1
  103. package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
  104. package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-LRYVnGLG.js} +2 -2
  105. package/web/dist/assets/Factories-ARenKBiP.js +1 -0
  106. package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-CfWR2-sX.js} +1 -1
  107. package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-nfFHnovH.js} +3 -3
  108. package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-lpOHcHKK.js} +1 -1
  109. package/web/dist/assets/{Kits-XQHsazCN.js → Kits-Bw5EQl_i.js} +1 -1
  110. package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
  111. package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
  112. package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
  113. package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
  114. package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-CggG0_sK.js} +1 -1
  115. package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-BObvlb70.js} +2 -2
  116. package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-BFfPMPc9.js} +1 -1
  117. package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-B594Pad_.js} +1 -1
  118. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  119. package/web/dist/assets/{index-BNttaGQb.js → index-DsLmKHw0.js} +3 -3
  120. package/web/dist/assets/index-DvPjphz0.css +1 -0
  121. package/web/dist/index.html +3 -3
  122. package/web/dist/assets/Dashboard-BUdUTjbB.js +0 -2
  123. package/web/dist/assets/Laws-B6A55S-2.js +0 -4
  124. package/web/dist/assets/Library-D7L0Wdbh.js +0 -3
  125. package/web/dist/assets/Loops-C0loS73u.js +0 -2
  126. package/web/dist/assets/RailCats-BGZnJ6fa.js +0 -1
  127. package/web/dist/assets/api-BMFDSXoB.js +0 -1
  128. package/web/dist/assets/index-BEI5ugYQ.css +0 -1
@@ -16,8 +16,10 @@ import { existsSync, readdirSync } from 'node:fs';
16
16
  import path from 'node:path';
17
17
 
18
18
  import { GLOBAL_MANIFEST, isGlobalInstall, resolvePath } from '../hosts/hosts.mjs';
19
- import { doctrinesForBuild, excludedRulesOfDir, readMaybe } from '../hosts/installs.mjs';
20
- import { frontmatter, readFacts } from '../hosts/memory-files.mjs';
19
+ import { EMIT_HOST_SCOPE, doctrinesForBuild, excludedRulesOfDir, readMaybe } from '../hosts/installs.mjs';
20
+ import { frontmatter, parseRules, readFacts } from '../hosts/memory-files.mjs';
21
+ import { emittedHost, sessionFiles } from '../hosts/hooks-context.mjs';
22
+ import { agentLoadout } from '../inspect/cost.mjs';
21
23
  import {
22
24
  SKILL_CLASS, entityStatus, loadRegistry, tuiInventory,
23
25
  } from '../inspect/inventory.mjs';
@@ -801,3 +803,37 @@ export function apiItem(state, type, name, fleet = [{ install: null, state }]) {
801
803
  }
802
804
  throw new NotFound(type);
803
805
  }
806
+
807
+ /**
808
+ * `GET /api/loadout` (the primary) and `/api/loadout/<agent>`: what one agent of the named install
809
+ * loads, and the rules it follows (spec 2026-11-08, agent loadout). The blocks are `agentLoadout`'s,
810
+ * the one writer of those figures (js/inspect/cost.mjs); this adds what only the install's
811
+ * inventory knows. `rules`: the Dictates, the doctrine rules built in (pack on, rule not excluded),
812
+ * and each user-rules layer's rules by their `R<n>` ids, as `/api/rules` parses them. An Adept's
813
+ * `citedBySpec` marks a rule its rendered spec cites: the render writes a citation as `*<Principle>*`,
814
+ * matched against this install's own rule names, so an unmatched name marks nothing. `noun` is the
815
+ * theme's name for the primary agent. An agent the install lacks, or no carrier, is a 404.
816
+ */
817
+ export function apiLoadout(state, agent = 'primary') {
818
+ // The catalogue is the allowlist: the name becomes a path, and this GET carries no token.
819
+ if (agent !== 'primary' && !state.inventory.agents.some((a) => a.name === agent)) throw new NotFound(agent);
820
+ const [host] = EMIT_HOST_SCOPE.get(state.emit || '') ?? ['opencode'];
821
+ const loadout = agentLoadout({ host, root: state.root ?? state.target, dir: state.target, agent });
822
+ if (!loadout) throw new NotFound(agent);
823
+ const inv = state.inventory;
824
+ const body = agent === 'primary' ? '' : (inv.agents.find((a) => a.name === agent)?.body ?? '');
825
+ const cited = (title) => Boolean(body) && body.includes(`*${title.split(' \u00b7 ').pop()}*`);
826
+ const rules = [
827
+ ...inv.laws.map((l) => ({ kind: 'dictate', id: l.num, title: l.title, citedBySpec: cited(l.title) })),
828
+ ...(inv.doctrines ?? []).filter((p) => p.active).flatMap((p) => p.rules.filter((r) => r.active !== false)
829
+ .map((r) => ({ kind: 'doctrine', id: `${r.pack}.${r.n}`, title: r.title, citedBySpec: cited(r.title) }))),
830
+ ];
831
+ let layers = [];
832
+ try { layers = sessionFiles(state.target, emittedHost(host)).filter((s) => s.rel === 'user-rules.md'); } catch { /* none */ }
833
+ for (const s of layers) {
834
+ for (const r of parseRules(s.text)[0]) {
835
+ rules.push({ kind: 'user', id: `R${r.id}`, title: r.title, layer: s.label || 'install', citedBySpec: false });
836
+ }
837
+ }
838
+ return { ...loadout, rules, noun: loadTheme(makeCfg(), state.theme).PRIMARY_AGENT ?? 'Primary agent' };
839
+ }
package/js/web/daemon.mjs CHANGED
@@ -13,8 +13,9 @@ import { printOut, writeText } from '../lib/fs.mjs';
13
13
  import { isTruthy, jsonDumpsCompact } from '../lib/json.mjs';
14
14
  import { webState } from './state.mjs';
15
15
  import { spawn } from 'node:child_process';
16
- import { createHash } from 'node:crypto';
17
- import { chmodSync, mkdirSync, openSync, readFileSync, unlinkSync } from 'node:fs';
16
+ import { createHash, createHmac, randomBytes } from 'node:crypto';
17
+ import { chmodSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
18
+ import { createServer } from 'node:net';
18
19
  import { join, resolve as pathResolve } from 'node:path';
19
20
 
20
21
  const ROOT = pathResolve(import.meta.dirname, '..', '..');
@@ -44,6 +45,20 @@ export function daemonStale(record, root = ROOT) {
44
45
  export const STALE_LINE = '[web] running OLD code (started before the last upgrade) — '
45
46
  + 'geneseed web restart';
46
47
 
48
+ /** The port a console asks for when none is named. */
49
+ export const DEFAULT_PORT = 4747;
50
+
51
+ /**
52
+ * Which install a console belongs to: a hash of this checkout's root, carried in `/api/ping` so a
53
+ * port holder can be told apart from a console of ANOTHER install without exposing a path. A
54
+ * console older than this field answers without one — its install is unknown, never assumed.
55
+ */
56
+ export function rootId(root = ROOT) {
57
+ const p = pathResolve(root);
58
+ return createHash('sha256').update(process.platform === 'win32' ? p.toLowerCase() : p)
59
+ .digest('hex').slice(0, 12);
60
+ }
61
+
47
62
  const statePath = (target) => join(target, '.geneseed-web.json');
48
63
 
49
64
  export function readDaemon(target) {
@@ -75,7 +90,7 @@ export function clearDaemon(target) {
75
90
  //
76
91
  // `geneseed web start|stop|status|restart`. The running server records pid/port/token/url
77
92
  // in a small JSON file and control is over HTTP, so nothing here needs OS process-kill
78
- // semantics, only a localhost request with the token.
93
+ // semantics, only a localhost request with the token (or, for a console whose record is gone, the install secret).
79
94
  //
80
95
  // * Every function below that touches the network is `async` (`fetch` has no
81
96
  // synchronous equivalent), and `cmdWeb` awaits it.
@@ -106,12 +121,93 @@ export async function probe(url, timeout = 1.5) {
106
121
  }
107
122
  }
108
123
 
124
+ /**
125
+ * Is the answer on `port` a Geneseed console, and whose? `null` when nothing answers a console's
126
+ * ping (nothing there, or some other program). Otherwise `{ pid, root }`, `root` null for a
127
+ * console older than the field. The shape is the proof: `ok`, a string `theme` and an integer
128
+ * `pid`, which no foreign server has a reason to send.
129
+ */
130
+ export async function identify(port, timeout = 0.5) {
131
+ try {
132
+ const res = await fetch(`http://127.0.0.1:${port}/api/ping`, {
133
+ signal: AbortSignal.timeout(Math.round(timeout * 1000)),
134
+ });
135
+ const body = res.status === 200 ? await res.json() : null;
136
+ await res.body?.cancel().catch(() => {});
137
+ if (body?.ok !== true || typeof body.theme !== 'string' || !validPid(body.pid)) return null;
138
+ return { pid: body.pid, root: typeof body.root === 'string' ? body.root : null };
139
+ } catch {
140
+ return null;
141
+ }
142
+ }
143
+
144
+ /** A pid worth showing: an integer above 1. 0, 1 and negatives are never a console. */
145
+ const validPid = (p) => Number.isInteger(p) && p > 1;
146
+
147
+ /**
148
+ * The install's shutdown secret: 32 random bytes in an owner-only file next to the daemon
149
+ * record, created once and never rewritten. It lets a LATER `web start` end a console of this
150
+ * install whose record (and token) is gone. It is never sent: callers send `secretProof`, bound
151
+ * to the port, so a listener that merely claims our root learns nothing it can reuse elsewhere.
152
+ * `null` when the file can be neither read nor created — the feature is then off.
153
+ */
154
+ export function webSecret(target) {
155
+ const p = join(target, '.geneseed-web-secret');
156
+ const read = () => { try { return readFileSync(p, 'utf-8').trim() || null; } catch { return null; } };
157
+ const have = read();
158
+ if (have) return have;
159
+ try {
160
+ mkdirSync(target, { recursive: true });
161
+ writeFileSync(p, randomBytes(32).toString('base64url'), { flag: 'wx', mode: 0o600 });
162
+ } catch { /* lost a race, or unwritable: read decides */ }
163
+ return read();
164
+ }
165
+
166
+ /** What a caller sends in `X-Geneseed-Secret`: a MAC of the port under the secret, not the secret. */
167
+ export const secretProof = (secret, port) => createHmac('sha256', secret).update(`shutdown:${port}`).digest('hex');
168
+
169
+ /** Can a server bind `port` on loopback right now? `true` means something else holds it. */
170
+ export const portTaken = (port) => new Promise((resolve) => {
171
+ const s = createServer();
172
+ s.once('error', () => resolve(true));
173
+ s.listen(port, '127.0.0.1', () => s.close(() => resolve(false)));
174
+ });
175
+
176
+ /**
177
+ * Free `port` for a new console, or say why not. `null` when it is free (possibly after ending
178
+ * the previous console of THIS install, found by its root id in the ping); otherwise a phrase
179
+ * naming the holder, and nothing touched. Another install's console, a console too old to name
180
+ * its install, and any other program are never ended.
181
+ *
182
+ * "Ends" means asking it to shut down with this install's secret (`secretProof`) and waiting for
183
+ * the port. A listener that only CLAIMS our root cannot honour the request, so nothing is ever
184
+ * ended on a claim, and no pid is ever signalled.
185
+ */
186
+ export async function clearPort(port, target) {
187
+ if (!await portTaken(port)) return null;
188
+ const c = await identify(port);
189
+ if (c && c.root === rootId()) {
190
+ const secret = webSecret(target);
191
+ const asked = secret !== null && await postShutdown(`http://127.0.0.1:${port}`, '', 3.0,
192
+ { 'X-Geneseed-Secret': secretProof(secret, port) });
193
+ for (let i = 0; asked && i < 50 && await portTaken(port); i += 1) await sleep(100);
194
+ if (asked && !await portTaken(port)) {
195
+ printOut(`[web] ended the previous console of this install on port ${port} (pid ${c.pid}).\n`);
196
+ return null;
197
+ }
198
+ return `held by a console (pid ${c.pid}) that claims this install but did not shut down on request`;
199
+ }
200
+ if (!c) return 'held by another program';
201
+ return `held by a Geneseed console (pid ${c.pid}) of ${c.root ? 'another install'
202
+ : 'an unknown install (older code) — end that pid yourself'}`;
203
+ }
204
+
109
205
  /** The token-carrying POST `geneseed web stop` and the in-page Stop button both send. */
110
- async function postShutdown(url, token, timeout = 3.0) {
206
+ async function postShutdown(url, token, timeout = 3.0, extra = {}) {
111
207
  try {
112
208
  const res = await fetch(`${url}/api/shutdown`, {
113
209
  method: 'POST',
114
- headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json' },
210
+ headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json', ...extra },
115
211
  body: '{}',
116
212
  signal: AbortSignal.timeout(Math.round(timeout * 1000)),
117
213
  });
@@ -198,6 +294,13 @@ export function restartArgs(theme) {
198
294
  * to stop, started a fresh daemon on 4747 while this process still held it, lost the bind,
199
295
  * fell back to a random port, and left a background console nobody had asked for.
200
296
  */
297
+ export function restartRefusal(theme) {
298
+ const rec = readDaemon(webState(theme).target);
299
+ if (!isTruthy(rec) || !validPid(rec.pid)) return 'foreground server: restart it from its terminal';
300
+ return `this console (pid ${process.pid}) is not the recorded daemon — that one is on ${none(rec.url)} `
301
+ + `(pid ${rec.pid}). Restart it there, or end pid ${process.pid}.`;
302
+ }
303
+
201
304
  export function requestRestart(theme) {
202
305
  const target = webState(theme).target;
203
306
  if (readDaemon(target)?.pid !== process.pid) return false;
@@ -272,6 +375,9 @@ export async function startDaemon(theme, port, openBrowser = true) {
272
375
  return 0;
273
376
  }
274
377
  clearDaemon(target);
378
+ const held = await clearPort(port, target);
379
+ if (held) printOut(`[web] port ${port} is ${held} — not touching it; the console will use another port.
380
+ `);
275
381
  const log = join(target, '.geneseed-web.log');
276
382
  spawnDetached(daemonArgs(port, theme), log);
277
383
  // Twelve seconds for the child to bind and write its record (60 * 200ms). The probe
@@ -282,6 +388,8 @@ export async function startDaemon(theme, port, openBrowser = true) {
282
388
  if (rec && isTruthy(rec.url) && await probe(rec.url, 0.5)) {
283
389
  printOut(`[web] Geneseed UI on ${rec.url} (theme: ${none(rec.theme)}, `
284
390
  + `pid ${none(rec.pid)})\n`);
391
+ if (rec.port !== port) printOut(`[web] asked for port ${port}, serving on port ${rec.port} instead.
392
+ `);
285
393
  printOut('[web] running in the background — `geneseed web stop` to stop it.\n');
286
394
  if (openBrowser) openUrl(rec.url);
287
395
  return 0;
@@ -355,19 +463,41 @@ export async function stopDaemon(theme = null, port = null) {
355
463
  return 0;
356
464
  }
357
465
 
358
- export async function statusDaemon(theme = null, port = null) {
466
+ /** Every Geneseed console answering on the recorded port or `ports`, each once. */
467
+ export async function findConsoles(target, ports) {
468
+ const rec = readDaemon(target);
469
+ const all = [...new Set([isTruthy(rec) ? Number(rec.port) : null, ...ports].filter(Number.isInteger))];
470
+ const found = [];
471
+ for (const p of all) {
472
+ // eslint-disable-next-line no-await-in-loop
473
+ const c = await identify(p);
474
+ if (c) found.push({ port: p, url: `http://127.0.0.1:${p}`, pid: c.pid, root: c.root,
475
+ recorded: isTruthy(rec) && rec.pid === c.pid && Number(rec.port) === p });
476
+ }
477
+ return found;
478
+ }
479
+
480
+ const whose = (c) => (c.root === null ? 'older code, install unknown' : c.root === rootId() ? 'this install' : 'another install');
481
+
482
+ export async function statusDaemon(theme = null, port = null, scan = [DEFAULT_PORT]) {
359
483
  const { target } = webState(theme);
360
484
  const refused = await portRefusal(readDaemon(target), port, 'status');
361
485
  if (refused !== null) return refused;
362
486
  const st = await liveDaemon(target);
487
+ // Unnamed port only: `--port` already scoped this call to one daemon (`portRefusal`).
488
+ const others = port === null ? (await findConsoles(target, scan)).filter((c) => !(st && c.recorded)) : [];
489
+ const listOthers = () => others.forEach((c) => printOut(
490
+ `[web] also found a Geneseed console at ${c.url} (pid ${c.pid}, not recorded — ${whose(c)})\n`));
363
491
  if (st) {
364
492
  printOut(`[web] running on ${st.url} (theme: ${none(st.theme)}, pid ${none(st.pid)})\n`);
365
493
  if (daemonStale(st)) printOut(`${STALE_LINE}\n`);
494
+ listOthers();
366
495
  return 0;
367
496
  }
368
497
  // EXIT 1, which is the verb's whole contract for a script. The snapshot's `<exit>`
369
498
  // column is what gates it.
370
499
  printOut('[web] not running.\n');
500
+ listOthers();
371
501
  return 1;
372
502
  }
373
503
 
@@ -19,7 +19,7 @@ import {
19
19
  rebuildCmds,
20
20
  } from './actions.mjs';
21
21
  import { BadRequest, NotFound } from './catalog.mjs';
22
- import { openFolder, requestRestart } from './daemon.mjs';
22
+ import { openFolder, requestRestart, restartRefusal, rootId, secretProof } from './daemon.mjs';
23
23
  import { apiDocs, apiDocsPage } from './docs.mjs';
24
24
  import { actionCommands, updatePlan } from './jobs.mjs';
25
25
  import {
@@ -71,8 +71,11 @@ export function securityHeaders(nonce) {
71
71
  * - `/api/*`: a cross-site or same-site fetch, or a foreign `Origin`, is refused even on GET —
72
72
  * the reads expose paths and memories. A request with neither header (curl, Node) passes.
73
73
  * - Any non-GET: the CSRF token, compared in constant time so its bytes cannot be timed out.
74
+ * `/api/shutdown` alone also takes `X-Geneseed-Secret`: a MAC of this socket's port under the
75
+ * install secret (`secretProof`), so `web start` can end its own unrecorded console. Same Host and
76
+ * Origin guards above, same constant-time compare; a wrong proof falls through to the token check.
74
77
  */
75
- export function requestGuard(req, token) {
78
+ export function requestGuard(req, token, secret = null) {
76
79
  const host = req.headers.host || '';
77
80
  // Exact `name:port`, not `localHost` + a suffix test: that pair let `[::1]x.evil:4747` and
78
81
  // `localhost:1:4747` through. Lower-cased the way browsers send it.
@@ -91,6 +94,12 @@ export function requestGuard(req, token) {
91
94
  }
92
95
  }
93
96
  if (req.method !== 'GET') {
97
+ const proof = req.headers['x-geneseed-secret'];
98
+ if (secret && path === '/api/shutdown' && typeof proof === 'string') {
99
+ const have = Buffer.from(proof, 'utf-8');
100
+ const need = Buffer.from(secretProof(secret, req.socket.localPort), 'utf-8');
101
+ if (have.length === need.length && timingSafeEqual(have, need)) return null;
102
+ }
94
103
  const got = Buffer.from(String(req.headers['x-geneseed-token'] ?? ''), 'utf-8');
95
104
  const want = Buffer.from(token, 'utf-8');
96
105
  if (got.length !== want.length || !timingSafeEqual(got, want)) {
@@ -222,7 +231,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
222
231
  // `pid` is what a restarting client waits on: the OLD server keeps answering this ping for
223
232
  // a moment after `/api/restart` returns, and a reload onto it fetches the old token.
224
233
  if (path === '/api/ping') {
225
- return sendJson(res, { ok: true, theme: state.theme, pid: process.pid }, 200, ae);
234
+ return sendJson(res, { ok: true, theme: state.theme, pid: process.pid, root: rootId() }, 200, ae);
226
235
  }
227
236
  for (const [prefix, handler] of PREFIX_ROUTES) {
228
237
  if (path.startsWith(prefix)) return sendJson(res, handler(st, path, state), 200, ae);
@@ -268,7 +277,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
268
277
  if (jm.busy) return sendJson(res, BUSY, 409, ae);
269
278
  if (!requestRestart(state.theme)) {
270
279
  return sendJson(res,
271
- { error: 'foreground server: restart it from its terminal' }, 409, ae);
280
+ { error: restartRefusal(state.theme) }, 409, ae);
272
281
  }
273
282
  return sendJson(res, { restarting: true }, 200, ae);
274
283
  }
@@ -447,7 +456,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
447
456
  const path = (req.url || '').split('?', 1)[0];
448
457
  try {
449
458
  // GUARD FIRST, BODY SECOND: a refused request is DISCARDED (`resume`, nothing buffered).
450
- const refused = requestGuard(req, token);
459
+ const refused = requestGuard(req, token, holder?.secret);
451
460
  if (refused) {
452
461
  sendJson(res, refused.body, refused.code, ae);
453
462
  return req.resume();
package/js/web/routes.mjs CHANGED
@@ -20,10 +20,10 @@ import { percentDecode } from '../lib/text.mjs';
20
20
  import { apiAutostart, apiExcludesMutate, apiInstallToggle, apiLoopsPresetMutate, apiMcp, apiMemoryDelete, targetView } from './actions.mjs';
21
21
  import { apiActivity, apiActivityDetail, apiActivityToggle } from './activity.mjs';
22
22
  import {
23
- apiDefaultInstallSet, apiDiff, apiDoctor, apiExcludes, apiFleet, apiInstalls, apiKits, apiLoops, apiLoopsActive, apiOverview, memoCounts,
23
+ apiDefaultInstallSet, apiDiff, apiDoctor, apiExcludes, apiFleet, apiInstalls, apiKits, apiLoops, apiLoopsActive, apiFactoriesCatalog, apiFactoriesActive, apiOverview, memoCounts,
24
24
  apiRecent, apiSetup, apiThemes, activeInstalls, apiUpdate,
25
25
  } from './api.mjs';
26
- import { FLEET_SECTIONS, NotFound, apiCatalog, apiItem } from './catalog.mjs';
26
+ import { FLEET_SECTIONS, NotFound, apiCatalog, apiItem, apiLoadout } from './catalog.mjs';
27
27
  import { apiUsage } from './usage-api.mjs';
28
28
  import { fleetSort } from './state.mjs';
29
29
  import { apiGates } from './gates-api.mjs';
@@ -90,7 +90,7 @@ export const VIEW_POSTS = new Set(['/api/activity', '/api/memory/delete', '/api/
90
90
  * section, and `/api/item/`, stay install-scoped (`PREFIX_ROUTES`).
91
91
  */
92
92
  export const MACHINE_GETS = new Set(['/api/update', '/api/installs', '/api/fleet', '/api/migrate/preview', '/api/kits',
93
- '/api/usage', '/api/gates', '/api/excludes', '/api/mcp', '/api/loops/active', '/api/activity',
93
+ '/api/usage', '/api/gates', '/api/excludes', '/api/mcp', '/api/loops/active', '/api/factories/active', '/api/activity',
94
94
  '/api/catalog/skills', '/api/catalog/agents', '/api/catalog/memory', '/api/catalog/notebook',
95
95
  '/api/catalog/wiki', '/api/catalog/config']);
96
96
 
@@ -184,6 +184,9 @@ export const PREFIX_ROUTES = [
184
184
  const fleet = m[1] !== 'law' ? fleetOf(base) : undefined;
185
185
  return apiItem(state, m[1], percentDecode(m[2]), fleet);
186
186
  }],
187
+ // /api/loadout/<agent> — one Adept's loadout in the named install (`apiLoadout`); the primary
188
+ // is the bare `/api/loadout`, since it is no catalogue item.
189
+ ['/api/loadout/', (state, p) => apiLoadout(state, percentDecode(p.slice('/api/loadout/'.length)) || 'primary')],
187
190
  // The sid is passed through unquoted — `apiActivityDetail`'s safe-name scheme is what
188
191
  // makes the lookup safe, rather than a check out here.
189
192
  ['/api/activity/', (state, p) => apiActivityDetail(
@@ -220,7 +223,11 @@ export const STATE_ROUTES = {
220
223
  // line indices, and the fingerprint every mutation must send back is what this GET
221
224
  // answers — a daemon whose POST worked and whose GET 501'd would have no way to obtain one.
222
225
  '/api/rules': apiRules,
226
+ '/api/loadout': (state) => apiLoadout(state),
223
227
  '/api/mcp': apiMcp,
224
228
  '/api/loops': apiLoops,
225
229
  '/api/loops/active': apiLoopsActive,
230
+ // The spec's names (C11): the catalogue is install-scoped like `/api/loops`, runs machine-wide.
231
+ '/api/factories/catalog': apiFactoriesCatalog,
232
+ '/api/factories/active': apiFactoriesActive,
226
233
  };
package/js/web/server.mjs CHANGED
@@ -29,7 +29,7 @@ import { parseIntStrict } from '../lib/text.mjs';
29
29
  import { promptLine } from '../lib/prompt.mjs';
30
30
  import { deployed } from './catalog.mjs';
31
31
  import { defaultView, warmDoctor, webState } from './state.mjs';
32
- import { clearDaemon, codeStamp, openUrl, readDaemon, restartDaemon, startDaemon, statusDaemon, stopDaemon, writeDaemon } from './daemon.mjs';
32
+ import { clearDaemon, codeStamp, openUrl, webSecret, readDaemon, restartDaemon, startDaemon, statusDaemon, stopDaemon, writeDaemon } from './daemon.mjs';
33
33
  import { makeHandler } from './handler.mjs';
34
34
  import { JobManager } from './jobs.mjs';
35
35
  import { spawnSync } from 'node:child_process';
@@ -165,9 +165,12 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
165
165
  srv.requestTimeout = 30_000;
166
166
  srv.headersTimeout = 10_000;
167
167
  holder.srv = srv;
168
+ // The install's shutdown secret, only when a daemon: a foreground server is not ended by `web start`.
169
+ if (daemon) holder.secret = webSecret(home);
168
170
  return new Promise((done) => {
169
171
  srv.on('error', () => {
170
172
  // On a listen error, retry with port 0 so the OS picks a free one.
173
+ printOut(`[web] port ${port} is taken by another process — using a free port instead.\n`);
171
174
  srv.listen(0, '127.0.0.1', () => ready());
172
175
  });
173
176
  srv.listen(port, '127.0.0.1', () => ready());
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin`, `exports` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
3
3
  "name": "geneseed",
4
- "version": "5.0.3",
4
+ "version": "5.0.4",
5
5
  "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
6
6
  "keywords": [
7
7
  "ai",
package/registry.json CHANGED
@@ -302,6 +302,20 @@
302
302
  "added": "2026-09-30",
303
303
  "last_verified": "2026-10-13"
304
304
  },
305
+ "skills/factory": {
306
+ "status": "experimental",
307
+ "version": "0.1.0",
308
+ "owner": "Guillaume Lemer",
309
+ "added": "2026-11-08",
310
+ "last_verified": ""
311
+ },
312
+ "skills/factory-forge": {
313
+ "status": "experimental",
314
+ "version": "0.1.0",
315
+ "owner": "Guillaume Lemer",
316
+ "added": "2026-11-08",
317
+ "last_verified": ""
318
+ },
305
319
  "skills/forge-mcp": {
306
320
  "status": "approved",
307
321
  "version": "1.0.0",
package/src/AGENT.md.tmpl CHANGED
@@ -265,7 +265,9 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
265
265
  | [workflow]({{DIR_SKILLS}}/workflow.md) | deterministic, code-driven orchestration of subagents (fan-out, find→verify, phased handoff) and the host exposes a workflow tool |
266
266
  | [pipeline]({{DIR_SKILLS}}/pipeline.md) | the user asks for a crew, or foreman mode needs several specialists (analyst → developer → tester) on one, isolated in its own worktree and merged on mechanical proof |
267
267
  | [loop]({{DIR_SKILLS}}/loop.md) | the user asks to run a loop |
268
+ | [factory]({{DIR_SKILLS}}/factory.md) | carry one work item to an open PR through a factory |
268
269
  | [brick-forge]({{DIR_SKILLS}}/brick-forge.md) | a new or adapted loop brick |
270
+ | [factory-forge]({{DIR_SKILLS}}/factory-forge.md) | a new or changed factory of bricks and loops |
269
271
  | [wiki]({{DIR_SKILLS}}/wiki.md) | consulting or growing the user's machine-wide knowledge base declared in `geneseed-wiki.jsonc` (§8) |
270
272
  | [rule]({{DIR_SKILLS}}/rule.md) | anything the user wants to outlive this session — a standing rule of their own (§1) or a durable fact to remember (§5); also tending the {{MEMORY}} set — duplicates, stale facts, a recurring lesson due for promotion |
271
273
  | [profile]({{DIR_SKILLS}}/profile.md) | the user wants the agent to know who they are — creating or refreshing the `PROFILE.md` identity file (§1) through a short interview |
@@ -306,11 +308,8 @@ the file, or to {{MEMORY}} ({{DOCTRINE:persist-insight}}).
306
308
 
307
309
  <!-- LEAN:begin -->
308
310
  Persistent facts live in {{LINK_MEMORY}} — one fact per file, indexed by a
309
- local `MEMORY.md`, a session file (**Session start**, above); write a new memory
310
- whenever the conversation yields a durable fact, a correction, or a decision worth
311
- keeping — on your own; the user sees each memory later in the web console. A standing
312
- rule goes to the user, through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}
313
- ({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
311
+ local `MEMORY.md`, a session file (**Session start**, above). Write a fact on your own; a standing rule goes
312
+ only through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
314
313
  never committed or shared; to share knowledge, put it in code, docs, or the
315
314
  project's `user-rules.md` (§1). When the same feedback lesson keeps recurring,
316
315
  propose promoting it into a standing rule — the [rule]({{DIR_SKILLS}}/rule.md)
@@ -322,8 +321,7 @@ the session — memory, notebook, notes, commits, docs — cite a rule by its pr
322
321
  ("Verify Before Asserting"), never its number: numbers are positional. Full convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
323
322
  <!-- LEAN:else -->
324
323
  Durable facts live in {{LINK_MEMORY}}, one per file, indexed by
325
- `MEMORY.md`, a session file. Write one on your own; the user sees it in the web
326
- console. A standing rule goes through the
324
+ `MEMORY.md`, a session file. Write a fact on your own; a standing rule goes only through the
327
325
  [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The directory is
328
326
  **personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
329
327
  (§1). In anything that outlives the session, cite a rule by its principle ("Verify Before
@@ -13,5 +13,10 @@ prose, reorganize a page, or fix an unrelated staleness you happen to notice whi
13
13
  Keep each doc in the format it is already in (Markdown or AsciiDoc) — never convert one; a new
14
14
  page follows the `Docs format:` line in the root `AGENTS.md`.
15
15
 
16
+ As a factory's docs lane, there is no iteration diff: the stage hands you the work item as
17
+ `carry` (and, when a later stage sent the work back, the reason). Make the doc change the work
18
+ item asks for, under the same limits, then commit the files you changed: the factory records a
19
+ stage only on a clean tree.
20
+
16
21
  Report `pass` once every doc the diff touched is back in sync, naming the files you changed — or
17
22
  that none needed it, if the diff left nothing stale.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: holdout-write
3
+ description: Write 3 to 8 holdout scenarios for the work item, outside the worktree, where the developer never reads them.
4
+ effect: read
5
+ agent: tester
6
+ outcomes: pass, fail
7
+ ---
8
+ The stage hands you the work item's file (or the spec) as `carry`. Read it in full, then the code
9
+ it names. Write 3 to 8 scenarios that a correct change must pass and a careless one may not: each
10
+ one a short prose file with three lines, `Given` (the starting state), `When` (one act a user or a
11
+ caller takes) and `Then` (the behaviour a user can see), concrete enough to play by hand or with a
12
+ command. Cover the acceptance criteria, plus the edges they imply but do not name.
13
+
14
+ Write them to the holdout folder, `$XDG_CONFIG_HOME/geneseed/holdout/<slug>/` (by default
15
+ `~/.config/geneseed/holdout/<slug>/`), one `NN-<name>.md` per scenario; `<slug>` is this branch's
16
+ name after `loop/factory-`. Never write into the worktree, never into any brief, note or carry.
17
+ When that folder already holds files (an earlier run with the same slug), write nothing and report
18
+ `fail`: the user decides whether to clear it.
19
+
20
+ Report `pass` with the `carry` you were handed, unchanged: the next stage needs the work item, and
21
+ must never get the scenarios' content or the folder's path. Report `fail` when the work item gives
22
+ too little to write three scenarios, or the folder is not empty — say why in a file in the OS temp
23
+ directory, and report its path.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: holdout
3
+ description: Play the holdout scenarios against the built change and report each one; a failure carries one sentence, never the scenario.
4
+ effect: read
5
+ agent: tester
6
+ outcomes: pass, fail, error
7
+ ---
8
+ Read every scenario in the holdout folder, `$XDG_CONFIG_HOME/geneseed/holdout/<slug>/` (by default
9
+ `~/.config/geneseed/holdout/<slug>/`; `<slug>` is this branch's name after `loop/factory-`). Play
10
+ each one against the change as built on this branch: run the app, the tests or the commands its
11
+ `Given` and `When` describe, and compare what you observe with its `Then`. Never edit a file. Leave
12
+ `git status` exactly as you found it: remove any build output or log a run left in the worktree.
13
+
14
+ First read the branch's diff against the default branch it started from (`git merge-base HEAD
15
+ origin/<default>`; `gh repo view --json defaultBranchRef` or `git remote show origin` names it).
16
+ Report `error` when a changed file resolves under the holdout folder, or an added line holds that
17
+ folder's resolved absolute path (a docs line naming `~/.config/geneseed/holdout/` in general is
18
+ not a leak). Report `error` too when the folder is missing or holds no scenario (nothing played is
19
+ not a pass), or a scenario cannot be played (a tool or a service it needs is missing).
20
+
21
+ Report `pass` when every scenario passes. Report `fail` otherwise, with a file in the OS temp
22
+ directory, never in the holdout folder or the worktree, that holds ONE sentence per failed
23
+ scenario: what you observed against what was expected, e.g. "Rounding 2.5 gave 3; expected 2".
24
+ Never copy a scenario's text, its name or its `Given`/`When` into that file: it goes back to the
25
+ developer, who must never see the scenarios. Report that file's path.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: intake
3
+ description: Read the work item — a request, a document or an issue — and write it down as one clear item for the run.
4
+ effect: read
5
+ agent: explorer
6
+ outcomes: pass, fail
7
+ ---
8
+ The stage hands you the run's `requirement` and its `input`: free text, a file path, or an issue (a
9
+ GitHub URL or `#<n>`: `gh issue view <n> --json title,body,comments,labels`; a GitLab one:
10
+ `glab issue view <n> --comments`). Read the input in full, then the code it names. Never edit any
11
+ file, and never post on the issue.
12
+
13
+ Write the work item to a file in the OS temp directory, never inside the worktree: a one-line
14
+ title, what happens now, what should happen, how to reproduce it, the files it likely touches,
15
+ and the acceptance criteria, each one testable. Quote the source for each claim (issue comment,
16
+ document section, file:line). Report `pass` with that file's path. Report `fail` when the input
17
+ cannot be read, or says too little to state one testable criterion — list the open questions in
18
+ such a file and report its path.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: merge-gate
3
+ description: Wait for the pull request's CI, at most 30 minutes, and report green, red, or no CI at all. Never merges.
4
+ effect: read
5
+ agent: tester
6
+ gate: human
7
+ gateOn: none
8
+ outcomes: pass, fail, none
9
+ ---
10
+ Wait with a command that returns by itself, never a foreground `sleep`: `gh pr checks <pr> --watch
11
+ --interval 30`, or `glab ci status --wait --branch <this branch>`. Bound each call under 10
12
+ minutes, by your shell tool's timeout or `timeout 540` in a POSIX shell, and repeat it up to 30
13
+ minutes in all. Then read the verdict once: `gh pr checks <pr> --json name,bucket,link` (exit 8:
14
+ pending), or `glab ci status --branch <this branch>`. A PR pushed moments ago may show no checks
15
+ yet, and a watch then returns at once: re-check for about 2 minutes before you conclude it has
16
+ none. Never merge, re-run or cancel a check, and never edit any file.
17
+
18
+ Report `pass` when every check is green. Report `fail` when one is red — for each failing check,
19
+ its name and the cause read from its log (`gh run view <id> --log-failed`), never guessed from its
20
+ title — or with "CI pending after 30 minutes" when checks still run at the bound. Report `none`
21
+ when the repo runs no CI on this PR: the user decides whether the run goes on. Write the findings
22
+ to a file in the OS temp directory and report that file's path.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: pr-open
3
+ description: Push the run's branch and open its pull request, or update the one already open. Never merges.
4
+ effect: read
5
+ skill: ship
6
+ outcomes: pass, fail
7
+ ---
8
+ Follow the `ship` skill's pull-request path only: never merge, never enable auto-merge, never
9
+ push to any branch but this worktree's own. First look for a PR already open on this branch
10
+ (`gh pr view --json url,state` or `glab mr view`): after a rework lap it exists, and this stage
11
+ only pushes the new commits to it.
12
+
13
+ Push with `git push -u origin HEAD:<this branch>`. The push asks the user: wait for that answer,
14
+ never work around it. With no PR yet, open one (`gh pr create` / `glab mr create`) titled from the
15
+ run's title, its body built from the run's `requirement` and `input` (as `next` gives them) and
16
+ the branch's commit subjects (`git log --oneline origin/<default>..HEAD`; the loop's notes left
17
+ with its `LOOP.md`), naming the issue it closes when the input was one. Change no file in the worktree.
18
+
19
+ Report `pass` with the PR URL in a file in the OS temp directory — report that file's path. Report
20
+ `fail` when the push is refused or fails, or the PR cannot be opened, with the exact error in
21
+ such a file.
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: retro
3
+ description: Write the factory run's report — what failed, what was reworked — and keep only a durable lesson in memory.
4
+ effect: read
5
+ agent: docs
6
+ outcomes: pass
7
+ ---
8
+ Read `FACTORY.md` (stage history, cycle counters, reason, carry) and the notes of the run's loops,
9
+ then write the run report to `.geneseed/factory-runs/<slug>.md` at the worktree root, `<slug>`
10
+ being the branch name after `loop/factory-`. First run `git check-ignore -q <that path>`: when it
11
+ exits non-zero the path is not ignored, so write the report to the OS temp directory instead.
12
+ The report holds the work item, the PR URL, every stage with its outcome, each rework and its
13
+ reason, and how the run ended (closed, or stopped and why).
14
+
15
+ Change nothing else: no tracked file, no commit. Only a lesson that will hold beyond this run —
16
+ a cause that will recur, a check this project lacks — goes into memory, one entry, under Persist
17
+ Insight; a fact about this run alone stays in the report. Report `pass` with the report's path.
@@ -15,7 +15,10 @@ brick only observes; a fix belongs in `apply`, not here.
15
15
  3. **Full suite** — only when everything above passed; otherwise `SKIPPED (an earlier check failed)`.
16
16
 
17
17
  List every check on its own line as `<check>: <status>`, the status one of `PASS`, `FAIL`, `ERROR`
18
- or `SKIPPED (reason)` — one that did not run is never left out, and silence is never a pass.
18
+ or `SKIPPED (reason)` — one that did not run is never left out, and silence is never a pass. A
19
+ check this project does not have at all (no linter configured, no build step) is not skipped:
20
+ list it as `<check>: N/A (not configured)`. It neither passes nor blocks; never use it for a
21
+ check that exists but was not run.
19
22
  Write each failure as four lines: the check's purpose, the property it guards, a one-line
20
23
  diagnostic (not the raw log), and the command that reruns it alone. Keep full logs in a file.
21
24
  Write the list to a file in the OS temp directory (never inside the worktree) and report that
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: triage
3
+ description: Pick the lane that fits the work item, from the lanes the factory offers, and say why.
4
+ effect: read
5
+ agent: explorer
6
+ outcomes: bug, feature, deps, refactor, docs, fail
7
+ ---
8
+ The stage hands you the work item's file as `carry` and the factory's lanes as `lanes`: each
9
+ outcome you may report, with the stage it leads to. Read the work item in full, then the code it
10
+ names. Pick the one outcome that fits: `bug` for a defect with a way to reproduce it, `feature`
11
+ for new behaviour, `deps` for a dependency to raise, `refactor` for a change of structure with no
12
+ change of behaviour, `docs` for a change to the documentation alone. Never report an outcome that
13
+ is not in `lanes`, and never edit any file.
14
+
15
+ Write a file in the OS temp directory, never inside the worktree: one paragraph on why the lane
16
+ fits and why the next-best one does not, then the work item copied in full, so the lane starts
17
+ from it. Report the outcome that names the lane, with that file's path. Report `fail` when no lane
18
+ fits the work item, or it mixes two kinds of work that need two runs — say which, in such a file,
19
+ and report its path.