geneseed 5.0.4 → 5.1.1

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 (76) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/SHIPPED.md +2 -2
  3. package/docs/concepts/exclusions.md +1 -1
  4. package/docs/concepts/factories.md +67 -15
  5. package/docs/concepts/loop-gates.md +5 -2
  6. package/docs/concepts/shared-tier.md +14 -0
  7. package/docs/extending.md +1 -1
  8. package/docs/guides/migrate.md +1 -1
  9. package/docs/guides/run-a-factory.md +41 -13
  10. package/docs/guides/upgrade-to-5.md +2 -2
  11. package/docs/reference/factory-actions.md +7 -7
  12. package/docs/web-ui.md +18 -6
  13. package/harness.config.json +1 -1
  14. package/js/README.md +3 -2
  15. package/js/build/args.mjs +34 -14
  16. package/js/build/emit-claude.mjs +3 -0
  17. package/js/build/emit-opencode.mjs +4 -0
  18. package/js/build/retired-skills.mjs +158 -0
  19. package/js/build/source.mjs +31 -11
  20. package/js/cli-table.json +32 -5
  21. package/js/factory/cli.mjs +49 -8
  22. package/js/factory/graph.mjs +72 -8
  23. package/js/factory/state.mjs +109 -27
  24. package/js/hosts/done-checks.mjs +3 -2
  25. package/js/hosts/memory-files.mjs +7 -2
  26. package/js/loop/catalog.mjs +16 -10
  27. package/js/loop/cli.mjs +16 -10
  28. package/js/maintain/memory.mjs +27 -2
  29. package/js/maintain/migrate.mjs +39 -25
  30. package/js/web/daemon.mjs +69 -14
  31. package/js/web/handler.mjs +22 -9
  32. package/package.json +1 -1
  33. package/src/agents/memory-curator.md +4 -4
  34. package/src/bricks/checks.md +62 -0
  35. package/src/bricks/intake.md +15 -6
  36. package/src/bricks/merge-gate.md +17 -8
  37. package/src/bricks/retro.md +8 -3
  38. package/src/bricks/review-panel.md +43 -0
  39. package/src/bricks/spec.md +20 -6
  40. package/src/factories/analysis-to-build.json +25 -7
  41. package/src/factories/bug-report-to-fix.json +25 -7
  42. package/src/factories/issue-to-pr.json +29 -11
  43. package/src/memory/README.md +1 -1
  44. package/src/skills/factory-forge.md +23 -5
  45. package/src/skills/factory.md +95 -25
  46. package/src/skills/geneseed.md +1 -1
  47. package/src/skills/loop.md +3 -2
  48. package/src/skills/rule/consolidate.md +1 -1
  49. package/src/skills/rule.md +1 -1
  50. package/themes/_TEMPLATE.json +1 -1
  51. package/web/dist/assets/{Activity-BaoxwVFH.js → Activity-CpkBwpu7.js} +1 -1
  52. package/web/dist/assets/{ActivityDetail-C_bFD0rW.js → ActivityDetail-DTPziZWM.js} +1 -1
  53. package/web/dist/assets/{Bonsai-B01lLf0m.js → Bonsai-hiG_gGNU.js} +1 -1
  54. package/web/dist/assets/{CopyButton-Bc66KPyA.js → CopyButton-DUIUfNp6.js} +1 -1
  55. package/web/dist/assets/{Dashboard-X7GZzGJp.js → Dashboard-Dnw6EyX7.js} +2 -2
  56. package/web/dist/assets/{Docs-LRYVnGLG.js → Docs-BEET_l16.js} +1 -1
  57. package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
  58. package/web/dist/assets/{GreenhouseView-CfWR2-sX.js → GreenhouseView-BKxy5apE.js} +1 -1
  59. package/web/dist/assets/{Installs-nfFHnovH.js → Installs-CnFVlVD0.js} +1 -1
  60. package/web/dist/assets/{JournalView-lpOHcHKK.js → JournalView-ChFitHjo.js} +1 -1
  61. package/web/dist/assets/{Kits-Bw5EQl_i.js → Kits-CcR-OlwQ.js} +1 -1
  62. package/web/dist/assets/{Laws-CnZJ0wjZ.js → Laws-B1s5idOg.js} +1 -1
  63. package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
  64. package/web/dist/assets/Library-x6TkkEVF.js +3 -0
  65. package/web/dist/assets/{Loops-ZaHC5MVl.js → Loops-BH93KKxn.js} +1 -1
  66. package/web/dist/assets/{OperatorHudView-CggG0_sK.js → OperatorHudView-BO0aIKPL.js} +1 -1
  67. package/web/dist/assets/{Personal-BObvlb70.js → Personal-CE_0Vhh0.js} +1 -1
  68. package/web/dist/assets/{Settings-BFfPMPc9.js → Settings-CbpZvVN_.js} +1 -1
  69. package/web/dist/assets/{Tabs-B594Pad_.js → Tabs-C2oW7oEj.js} +1 -1
  70. package/web/dist/assets/{index-DsLmKHw0.js → index-BQwOmbor.js} +2 -2
  71. package/web/dist/assets/{index-DvPjphz0.css → index-CuIop_pO.css} +1 -1
  72. package/web/dist/index.html +2 -2
  73. package/adapters/claude-code/skills/geneseed/SKILL.md +0 -76
  74. package/web/dist/assets/Factories-ARenKBiP.js +0 -1
  75. package/web/dist/assets/LibRows-Hqvf1beK.js +0 -1
  76. package/web/dist/assets/Library-JaSsp6Yr.js +0 -3
@@ -29,7 +29,8 @@ import path from 'node:path';
29
29
 
30
30
  import { main as driverMain } from '../build/driver.mjs';
31
31
  import { foldHost, foldSummary } from '../build/fold.mjs';
32
- import { RETIRED_SKILL_IDS, ROOT, knownSkillIds, skillAliases } from '../build/source.mjs';
32
+ import { ROOT } from '../build/source.mjs';
33
+ import { ownsRel, retiredArchiveOf, retiredSkillFolders } from '../build/retired-skills.mjs';
33
34
  import { CLAUDE_STYLE, isCanonical, settingsFile } from '../hosts/hosts.mjs';
34
35
  import {
35
36
  claudeCfg, claudeReadManifest, EMIT_HOST_SCOPE, installState, installTargets,
@@ -130,31 +131,39 @@ function foldPreview(rows) {
130
131
  }
131
132
 
132
133
  /**
133
- * M5 — files no manifest owns, so no emit will ever prune them: the root `AGENT.md` and the folder
134
- * of a skill that no longer ships under its own name. An earlier build likely wrote them, but an
135
- * alias is a plain word and a folder under it may be the user's own, so nothing claims which.
136
- * REPORTED, never moved: they go aside on the user's word.
134
+ * M5 — files no manifest owns, so no emit's ordinary prune will ever reach them: the root
135
+ * `AGENT.md` and the folder of a skill that no longer ships under its own name. The skill
136
+ * folders split the way the next canonical emit treats them (`retiredSkillFolders`,
137
+ * `js/build/retired-skills.mjs`): `prunes`, a plain Geneseed render it moves aside, and
138
+ * `orphans`, everything it leaves — `AGENT.md`, a link, a folder without the render's
139
+ * fingerprint — because an alias is a plain word and such a folder may be the user's own.
137
140
  *
138
141
  * The candidate names come from what git history already settled and the source still records —
139
- * `RETIRED_SKILL_IDS` and the `aliases:` markers — because the CLI may not spawn `git`. Each
140
- * candidate is checked before it is listed: a live skill is never an orphan (`teach` is live,
141
- * `quiz` is its alias), and a path the manifest owns is not one either — the next emit prunes it.
142
+ * `RETIRED_SKILL_IDS` and the `aliases:` markers — because the CLI may not spawn `git`. A live
143
+ * skill is never a candidate (`teach` is live, `quiz` is its alias), and a path the manifest
144
+ * owns is not one either — the ordinary prune handles it.
142
145
  */
143
- export function orphanFindings(cfg, owned, { live = knownSkillIds(), aliases = skillAliases() } = {}) {
144
- const owns = (rel) => owned.some((o) => o === rel || o.startsWith(`${rel}/`));
145
- const names = [...new Set([...aliases.keys(), ...Object.keys(RETIRED_SKILL_IDS)])].filter((n) => !live.includes(n));
146
- return ['AGENT.md', ...names.map((n) => `skills/${n}`)]
147
- .filter((rel) => !owns(rel) && existsSync(path.join(cfg, rel)))
148
- .map((rel) => path.join(cfg, rel));
146
+ export function orphanFindings(cfg, owned, opts = {}) {
147
+ return orphanSplit(cfg, owned, opts).orphans;
149
148
  }
150
149
 
151
- /** The `--dry-run` half of M5: the orphans of each global Claude-style install. */
150
+ function orphanSplit(cfg, owned, opts = {}) {
151
+ const { prune, keep } = retiredSkillFolders(cfg, owned, opts);
152
+ const agent = !ownsRel(owned, 'AGENT.md') && existsSync(path.join(cfg, 'AGENT.md')) ? [path.join(cfg, 'AGENT.md')] : [];
153
+ return { prunes: prune, orphans: [...agent, ...keep] };
154
+ }
155
+
156
+ /** The `--dry-run` half of M5, for each canonical global install of every host. */
152
157
  function orphanPreview(rows) {
153
- return rows.filter(({ host, scope, root }) => scope === 'global' && CLAUDE_STYLE.includes(host) && isCanonical(root, host))
154
- .flatMap(({ root }) => {
155
- const owned = claudeReadManifest(root).owned;
156
- return orphanFindings(root, Array.isArray(owned) ? owned : []);
157
- });
158
+ const out = { prunes: [], orphans: [] };
159
+ for (const { host, scope, root } of rows) {
160
+ if (scope !== 'global' || !isCanonical(root, host)) continue;
161
+ const owned = claudeReadManifest(root).owned;
162
+ const { prunes, orphans } = orphanSplit(root, Array.isArray(owned) ? owned : []);
163
+ out.prunes.push(...prunes);
164
+ out.orphans.push(...orphans);
165
+ }
166
+ return out;
158
167
  }
159
168
 
160
169
  /** The fold and orphan half of `--dry-run`, as the CLI prints it. */
@@ -163,20 +172,25 @@ function printPreview(rows) {
163
172
  printOut(summary ? `[migrate] would fold ${host}: ${summary}\n` : `[migrate] ${host}: nothing to fold\n`);
164
173
  for (const f of failed) printOut(`[migrate] ${host}: the fold would stop at ${f}\n`);
165
174
  }
166
- for (const p of orphanPreview(rows)) {
175
+ const { prunes, orphans } = orphanPreview(rows);
176
+ for (const p of prunes) {
177
+ printOut(`[migrate] would prune: ${p} (Geneseed rendered it and no longer ships it; the next emit moves it to `
178
+ + `${retiredArchiveOf(path.dirname(path.dirname(p)), path.basename(p))})\n`);
179
+ }
180
+ for (const p of orphans) {
167
181
  printOut(`[migrate] orphan: ${p} (no manifest owns it; an earlier build may have written it, or it may be yours). Nothing moves it: if it is not yours, move it by hand.\n`);
168
182
  }
169
183
  }
170
184
 
171
185
  /**
172
- * What the next rebuild would do, for the console: `{folds: [{host, summary, failed}], orphans}`.
173
- * Writes nothing. A marker `migrate` refuses is in here too: `rebuild-all` coerces it, so that
174
- * install still folds. No `would re-emit` plan: that is this verb's, and a clone has none to run.
186
+ * What the next rebuild would do, for the console: `{folds: [{host, summary, failed}], prunes,
187
+ * orphans}`. Writes nothing. A marker `migrate` refuses is in here too: `rebuild-all` coerces it,
188
+ * so that install still folds. No `would re-emit` plan: that is this verb's, and a clone has none.
175
189
  */
176
190
  export function migratePreview() {
177
191
  const { rows, unrecognised } = migrateSurvey({ prune: false });
178
192
  const all = [...rows, ...unrecognised];
179
- return { folds: foldPreview(all), orphans: orphanPreview(all) };
193
+ return { folds: foldPreview(all), ...orphanPreview(all) };
180
194
  }
181
195
 
182
196
  /** A stash key that cannot collide across drives, and is a legal file name on both platforms. */
package/js/web/daemon.mjs CHANGED
@@ -125,17 +125,20 @@ export async function probe(url, timeout = 1.5) {
125
125
  * Is the answer on `port` a Geneseed console, and whose? `null` when nothing answers a console's
126
126
  * ping (nothing there, or some other program). Otherwise `{ pid, root }`, `root` null for a
127
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.
128
+ * `pid`, which no foreign server has a reason to send. `shutdown` asks for a shutdown nonce too:
129
+ * `nonce` is then a string (a daemon), `null` (a console without the secret) or `undefined` (a
130
+ * console older than the handshake).
129
131
  */
130
- export async function identify(port, timeout = 0.5) {
132
+ export async function identify(port, timeout = 0.5, shutdown = false) {
131
133
  try {
132
- const res = await fetch(`http://127.0.0.1:${port}/api/ping`, {
134
+ const res = await fetch(`http://127.0.0.1:${port}/api/ping${shutdown ? '?shutdown=1' : ''}`, {
133
135
  signal: AbortSignal.timeout(Math.round(timeout * 1000)),
134
136
  });
135
137
  const body = res.status === 200 ? await res.json() : null;
136
138
  await res.body?.cancel().catch(() => {});
137
139
  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 };
140
+ return { pid: body.pid, root: typeof body.root === 'string' ? body.root : null,
141
+ nonce: typeof body.nonce === 'string' || body.nonce === null ? body.nonce : undefined };
139
142
  } catch {
140
143
  return null;
141
144
  }
@@ -145,10 +148,13 @@ export async function identify(port, timeout = 0.5) {
145
148
  const validPid = (p) => Number.isInteger(p) && p > 1;
146
149
 
147
150
  /**
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.
151
+ * The install's shutdown secret: 32 random bytes in a file next to the daemon record, created
152
+ * once and never rewritten. On POSIX the file is owner-only (mode 0600); on Windows the mode does
153
+ * nothing, and the file has the ACL it inherits from the folder it is in. It lets a LATER
154
+ * `web start` end a console of this install whose record (and token) is gone. It is never sent:
155
+ * callers send `secretProof`, bound to the port and to a nonce the console minted and accepts
156
+ * once, for a short time. A listener that merely claims our root can only hand out a nonce of its
157
+ * own, which no real console accepts, so the proof it collects is good nowhere, then or later.
152
158
  * `null` when the file can be neither read nor created — the feature is then off.
153
159
  */
154
160
  export function webSecret(target) {
@@ -163,8 +169,42 @@ export function webSecret(target) {
163
169
  return read();
164
170
  }
165
171
 
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');
172
+ /**
173
+ * What a caller sends in `X-Geneseed-Secret`: a MAC of the port and a nonce the console minted
174
+ * (`X-Geneseed-Nonce`) under the secret, never the secret itself.
175
+ */
176
+ export const secretProof = (secret, port, nonce) => createHmac('sha256', secret)
177
+ .update(`shutdown:${port}:${nonce}`).digest('hex');
178
+
179
+ /** How long a minted shutdown nonce stays good. `clearPort` spends it within a second. */
180
+ export const NONCE_TTL_MS = 30_000;
181
+ const NONCE_CAP = 8;
182
+
183
+ /**
184
+ * One console's shutdown nonces: minted by `GET /api/ping?shutdown=1`, each taken once and only
185
+ * while fresh. At most `NONCE_CAP` outstanding, oldest dropped first, so a flood of pings cannot
186
+ * grow it. Per server (the handler's closure), never module-wide: one process may run several.
187
+ */
188
+ export function nonceBook(now = Date.now) {
189
+ const live = new Map();
190
+ return {
191
+ issue() {
192
+ const t = now();
193
+ for (const [n, exp] of live) if (exp <= t) live.delete(n);
194
+ // A local ping flood can evict a nonce: that `web start` is refused, and nothing shuts down.
195
+ while (live.size >= NONCE_CAP) live.delete(live.keys().next().value);
196
+ const n = randomBytes(16).toString('hex');
197
+ live.set(n, t + NONCE_TTL_MS);
198
+ return n;
199
+ },
200
+ /** `true` once for a nonce this book minted and that has not expired; it is spent either way. */
201
+ take(n) {
202
+ const exp = live.get(n);
203
+ live.delete(n);
204
+ return exp !== undefined && exp > now();
205
+ },
206
+ };
207
+ }
168
208
 
169
209
  /** Can a server bind `port` on loopback right now? `true` means something else holds it. */
170
210
  export const portTaken = (port) => new Promise((resolve) => {
@@ -179,17 +219,32 @@ export const portTaken = (port) => new Promise((resolve) => {
179
219
  * naming the holder, and nothing touched. Another install's console, a console too old to name
180
220
  * its install, and any other program are never ended.
181
221
  *
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.
222
+ * "Ends" means a challenge and a response: ask it for a fresh nonce (`/api/ping?shutdown=1`),
223
+ * send `secretProof` over the port and that nonce, and wait for the port. A listener that only
224
+ * CLAIMS our root cannot honour the request, so nothing is ever ended on a claim, and no pid is
225
+ * ever signalled.
226
+ *
227
+ * A console older than the handshake answers no `nonce` and gets no proof at all: the only proof
228
+ * it could check is the fixed, replayable one this handshake replaced, and an impostor can pose
229
+ * as old as easily as new. It is named and left alone, like a console too old to name its root.
185
230
  */
186
231
  export async function clearPort(port, target) {
187
232
  if (!await portTaken(port)) return null;
188
233
  const c = await identify(port);
189
234
  if (c && c.root === rootId()) {
235
+ const n = (await identify(port, 0.5, true))?.nonce;
236
+ if (n === null) {
237
+ return `held by a console (pid ${c.pid}) of this install without the shutdown secret (a foreground `
238
+ + '`geneseed web`, or a daemon that could not read its secret) — stop it in its terminal (Ctrl+C), '
239
+ + 'or end that pid yourself';
240
+ }
241
+ if (typeof n !== 'string') {
242
+ return `held by an older console (pid ${c.pid}) of this install, from before the shutdown handshake `
243
+ + '— end that pid yourself';
244
+ }
190
245
  const secret = webSecret(target);
191
246
  const asked = secret !== null && await postShutdown(`http://127.0.0.1:${port}`, '', 3.0,
192
- { 'X-Geneseed-Secret': secretProof(secret, port) });
247
+ { 'X-Geneseed-Nonce': n, 'X-Geneseed-Secret': secretProof(secret, port, n) });
193
248
  for (let i = 0; asked && i < 50 && await portTaken(port); i += 1) await sleep(100);
194
249
  if (asked && !await portTaken(port)) {
195
250
  printOut(`[web] ended the previous console of this install on port ${port} (pid ${c.pid}).\n`);
@@ -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, restartRefusal, rootId, secretProof } from './daemon.mjs';
22
+ import { nonceBook, 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,11 +71,13 @@ 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
+ * `/api/shutdown` alone also takes `X-Geneseed-Secret`: a MAC of this socket's port and an
75
+ * `X-Geneseed-Nonce` this console minted, under the install secret (`secretProof`), so
76
+ * `web start` can end its own unrecorded console. The nonce is spent on the attempt, right or
77
+ * wrong, so a proof is good once. Same Host and Origin guards above, same constant-time
78
+ * compare; a wrong proof falls through to the token check.
77
79
  */
78
- export function requestGuard(req, token, secret = null) {
80
+ export function requestGuard(req, token, secret = null, nonces = null) {
79
81
  const host = req.headers.host || '';
80
82
  // Exact `name:port`, not `localHost` + a suffix test: that pair let `[::1]x.evil:4747` and
81
83
  // `localhost:1:4747` through. Lower-cased the way browsers send it.
@@ -95,9 +97,11 @@ export function requestGuard(req, token, secret = null) {
95
97
  }
96
98
  if (req.method !== 'GET') {
97
99
  const proof = req.headers['x-geneseed-secret'];
98
- if (secret && path === '/api/shutdown' && typeof proof === 'string') {
100
+ const nonce = req.headers['x-geneseed-nonce'];
101
+ if (secret && nonces && path === '/api/shutdown' && typeof proof === 'string'
102
+ && typeof nonce === 'string' && nonces.take(nonce)) {
99
103
  const have = Buffer.from(proof, 'utf-8');
100
- const need = Buffer.from(secretProof(secret, req.socket.localPort), 'utf-8');
104
+ const need = Buffer.from(secretProof(secret, req.socket.localPort, nonce), 'utf-8');
101
105
  if (have.length === need.length && timingSafeEqual(have, need)) return null;
102
106
  }
103
107
  const got = Buffer.from(String(req.headers['x-geneseed-token'] ?? ''), 'utf-8');
@@ -139,6 +143,8 @@ export function makeHandler(state, jm, token, dist, holder = null) {
139
143
  // syscall against the readFileSync + gzipSync it saves. `gz` is the gzipped body,
140
144
  // computed once on the first gzip-accepting request instead of per request.
141
145
  const staticCache = new Map();
146
+ // This console's shutdown nonces (`nonceBook`), minted by `/api/ping?shutdown=1`.
147
+ const nonces = nonceBook();
142
148
  // `dist` RESOLVED ONCE, because every path compared against it below is resolved too.
143
149
  // `resolvePath` is `realpathSync.native`, so a checkout reached by any path that is not its
144
150
  // canonical one — a symlink, a Windows junction, a `subst` or mapped drive, an 8.3 short name,
@@ -230,8 +236,15 @@ export function makeHandler(state, jm, token, dist, holder = null) {
230
236
  }
231
237
  // `pid` is what a restarting client waits on: the OLD server keeps answering this ping for
232
238
  // a moment after `/api/restart` returns, and a reload onto it fetches the old token.
239
+ // `?shutdown=1` adds `nonce` for `clearPort`: a fresh one when this console holds the install
240
+ // secret, `null` when it does not (a foreground `geneseed web`, or a daemon that could not read
241
+ // its secret), so the caller can tell.
233
242
  if (path === '/api/ping') {
234
- return sendJson(res, { ok: true, theme: state.theme, pid: process.pid, root: rootId() }, 200, ae);
243
+ const body = { ok: true, theme: state.theme, pid: process.pid, root: rootId() };
244
+ if (new URLSearchParams((req.url || '').split('?')[1] || '').has('shutdown')) {
245
+ body.nonce = holder?.secret ? nonces.issue() : null;
246
+ }
247
+ return sendJson(res, body, 200, ae);
235
248
  }
236
249
  for (const [prefix, handler] of PREFIX_ROUTES) {
237
250
  if (path.startsWith(prefix)) return sendJson(res, handler(st, path, state), 200, ae);
@@ -456,7 +469,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
456
469
  const path = (req.url || '').split('?', 1)[0];
457
470
  try {
458
471
  // GUARD FIRST, BODY SECOND: a refused request is DISCARDED (`resume`, nothing buffered).
459
- const refused = requestGuard(req, token, holder?.secret);
472
+ const refused = requestGuard(req, token, holder?.secret, nonces);
460
473
  if (refused) {
461
474
  sendJson(res, refused.body, refused.code, ae);
462
475
  return req.resume();
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.4",
4
+ "version": "5.1.1",
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",
@@ -6,7 +6,7 @@
6
6
  - The {{MEMORY}} store needs tidying in bulk. The session context says so in one
7
7
  line when a topic holds over 40 facts or a `misc` topic exists; or the user asks
8
8
  to tidy, dedupe or re-topic their memory.
9
- - `geneseed learn --consolidate` reported duplicate descriptions that need a merge.
9
+ - `geneseed memory consolidate` reported duplicate descriptions that need a merge.
10
10
 
11
11
  ## When NOT to dispatch
12
12
  - A handful of facts to review — the rule {{SKILL}}'s consolidation flow does
@@ -19,8 +19,8 @@
19
19
  scope: the whole store, or named topics only.
20
20
 
21
21
  ## Allowed tools
22
- - **Read + write to the {{MEMORY}} store only.** May run `geneseed memory` and
23
- `geneseed learn --consolidate`. A write into the store meets no prompt at the tool boundary
22
+ - **Read + write to the {{MEMORY}} store only.** May run `geneseed memory`
23
+ (`list`, `rm`, `consolidate`). A write into the store meets no prompt at the tool boundary
24
24
  (memory is written freely), but bulk curation reworks facts the user already keeps, so it still
25
25
  shows each topic's plan and applies it with the user's consent.
26
26
  <!-- bash: allow -->
@@ -51,7 +51,7 @@
51
51
  and run `geneseed memory rm <name> --archived --purge` only for the codes the user
52
52
  approves. A fact holding a secret, live or archived, is proposed for `--purge` on sight
53
53
  ({{LAW:sealed-secrets}}).
54
- 7. Finish with `geneseed learn --consolidate --memory <the store's path>`, so both
54
+ 7. Finish with `geneseed memory consolidate --memory <the store's path>`, so both
55
55
  index levels match the files.
56
56
 
57
57
  ## Output contract
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: checks
3
+ description: Run the repo's done list as the base branch holds it, then refuse a diff that changes a locked path. Never trusts the branch's own copy.
4
+ effect: read
5
+ agent: tester
6
+ outcomes: pass, fail, error, none
7
+ gate: human
8
+ gateOn: error, none
9
+ ---
10
+ Never commit. Write every finding to a file in the OS temp directory, never inside the worktree,
11
+ and report that file's path. Run `git fetch origin`, then find the default branch (`gh repo view
12
+ --json defaultBranchRef`, or `git remote show origin`) and the base, `git merge-base HEAD
13
+ origin/<default>`. When the fetch fails or no default branch is found, report `error` and start
14
+ the finding with `environment:` and the cause. An environment failure is never a `fail`: a `fail`
15
+ goes back to the loop, whose code cannot fix it, and `error` holds for the user.
16
+
17
+ Read the done list from the base, never from this branch: `git show
18
+ origin/<default>:.geneseed/done-checks.txt`, one command per line, `#` lines ignored. When the base
19
+ has no such file, or it holds no command, propose one from the BASE's manifests (`git show
20
+ origin/<default>:<file>`), never this branch's:
21
+ - `package.json`: its `test`, `lint` and `typecheck` scripts, each only when present, and `test`
22
+ not when it is npm's `no test specified` stub. The first lockfile found, in this order, names
23
+ the package manager: `bun.lockb` or `bun.lock` → `bun run test`, `bun run lint`,
24
+ `bun run typecheck`; `pnpm-lock.yaml` → `pnpm test`, `pnpm lint`, `pnpm typecheck`;
25
+ `yarn.lock` → `yarn test`, `yarn lint`, `yarn typecheck`; none → `npm test`, `npm run lint`,
26
+ `npm run typecheck`.
27
+ - `pom.xml`: `mvn test`. `build.gradle` or `build.gradle.kts`: `gradle test`, as `./gradlew test`
28
+ when the repo has the wrapper. `Cargo.toml`: `cargo test`. `go.mod`: `go test ./...`.
29
+ - `pyproject.toml`: `pytest`, only where pytest shows (a `[tool.pytest` section, `pytest.ini`,
30
+ `conftest.py` or a `tests` folder).
31
+ - No manifest: propose nothing, and say so.
32
+ Put the proposal in the finding as one fenced block, one command per line and nothing else in it;
33
+ explain outside the block. Report `none`.
34
+
35
+ The tree is clean before you run anything. Run each command from the worktree root, in order, each
36
+ bounded under 10 minutes by your shell tool's timeout.
37
+
38
+ Environment failures come first, and they take precedence over a non-zero exit. A command that
39
+ times out, or whose tool is missing (exit 127, or "command not found" / "is not recognized"), is
40
+ an environment failure, never a red check: stop there, and report `error` with the finding
41
+ starting `environment:`, naming the command and the cause. When an earlier command was already
42
+ red, the environment failure still wins: report `error`, and name the red command and its last 40
43
+ lines in the same finding. The loop cannot fix the environment, so a `fail` would spend a lap
44
+ and meet the same failure again; once the user fixes it, an `amend` re-runs every command, and a
45
+ command still red then reports `fail`.
46
+
47
+ Otherwise, run every command, and report `fail` when one exits non-zero: name the first failing
48
+ command and copy the last 40 lines of its output. Report `fail` too when a command changed a
49
+ tracked file, naming each file: a lint that fixes what it finds hides what it found.
50
+
51
+ Afterwards, on every outcome (`pass`, `fail` and `error` alike), put the tree back: restore every
52
+ tracked file the commands changed (`git restore --staged --worktree -- <path>`) and delete every
53
+ untracked file they created, naming each one in the finding. Never touch `FACTORY.md` or
54
+ `LOOP.md`: they are the run's state, not a command's output.
55
+
56
+ Only when every command passes, list the files the branch changed: `git diff --name-only
57
+ --no-renames <merge-base> HEAD` (`--no-renames` lists a rename's old path too, so moving a locked
58
+ file out of place is seen). A path is locked when it equals an entry below, or lies under an entry
59
+ that ends in `/`: `.geneseed/done-checks.txt`, `.gitlab-ci.yml`, `.github/workflows/`,
60
+ `.geneseed/factories/`, `.geneseed/loops/`, `.geneseed/bricks/`, and each entry of the stage's
61
+ `protected` list. Tests are not locked. Report `error` when any changed path is locked, naming each
62
+ one: the user decides whether the run goes on. Else report `pass`.
@@ -1,18 +1,27 @@
1
1
  ---
2
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.
3
+ description: Read the work item — a request, a document or an issue — and write it down as one clear item for the run, or ask the user what only they can answer.
4
4
  effect: read
5
5
  agent: explorer
6
- outcomes: pass, fail
6
+ outcomes: pass, fail, needs-info
7
+ gate: human
8
+ gateOn: needs-info
7
9
  ---
8
10
  The stage hands you the run's `requirement` and its `input`: free text, a file path, or an issue (a
9
11
  GitHub URL or `#<n>`: `gh issue view <n> --json title,body,comments,labels`; a GitLab one:
10
12
  `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.
13
+ file, and never post on the issue. On a re-run the `carry` holds the user's answers: first read
14
+ your previous finding, the `carry` of the latest `intake` entry in `FACTORY.md`'s `history`, so
15
+ each answer meets its question, then build on them.
12
16
 
13
17
  Write the work item to a file in the OS temp directory, never inside the worktree: a one-line
14
18
  title, what happens now, what should happen, how to reproduce it, the files it likely touches,
15
19
  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.
20
+ document section, file:line). End it with two lines the review reads: `size: small`, `medium` or
21
+ `large` (small: a few lines in one or two files; large: several modules, a new interface or a data
22
+ migration; medium between), and `areas:` with any of `security`, `performance`, `ui`, `data`, or
23
+ `none`.
24
+
25
+ Report `pass` with that file's path. Report `needs-info` when a question blocks the work and only
26
+ the user can answer it: write the questions in that file, numbered, each with the assumption you
27
+ would build on without an answer, and report its path. Report `fail` when the input cannot be read.
@@ -1,6 +1,6 @@
1
1
  ---
2
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.
3
+ description: Wait for the pull request's CI, at most 30 minutes, and report green, red, or no verdict (no CI, or none readable). Never merges.
4
4
  effect: read
5
5
  agent: tester
6
6
  gate: human
@@ -10,13 +10,22 @@ outcomes: pass, fail, none
10
10
  Wait with a command that returns by itself, never a foreground `sleep`: `gh pr checks <pr> --watch
11
11
  --interval 30`, or `glab ci status --wait --branch <this branch>`. Bound each call under 10
12
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.
13
+ minutes in all. Then read the verdict once: `gh pr checks <pr> --json name,bucket,link`, or
14
+ `glab ci status --branch <this branch>`. A PR pushed moments ago may show no checks yet, and a
15
+ watch then returns at once: re-check for about 2 minutes before you conclude it has none. Never
16
+ merge, re-run or cancel a check, and never edit any file.
17
+
18
+ The verdict is each check's `bucket` (`pass`, `fail`, `pending`, `skipping`, `cancel`), or each
19
+ job's state in `glab`'s output, never the exit code. `gh pr checks` exits non-zero on a readable
20
+ verdict: 1 when a check is red, 8 when one is pending. That is a verdict, not an environment
21
+ failure: read the output it printed.
17
22
 
18
23
  Report `pass` when every check is green. Report `fail` when one is red — for each failing check,
19
24
  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.
25
+ title. Report `none` when the repo runs no CI on this PR: the user decides whether the run goes
26
+ on. Report `none` too, with the finding starting `environment:` and the cause, when no verdict
27
+ can be read: checks still pending after 30 minutes, `gh`/`glab` missing or unusable (not logged
28
+ in, no access to the repo), or output you cannot read as checks and their states. An
29
+ environment failure is never a `fail`: a `fail` goes back to the loop, whose code cannot fix it,
30
+ and `none` holds for the user. Write the findings to a file in the OS temp directory and report
31
+ that file's path.
@@ -5,12 +5,17 @@ effect: read
5
5
  agent: docs
6
6
  outcomes: pass
7
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>`
8
+ Read `FACTORY.md` (stage history, cycle counters, reason, carry) and the notes of the run's loops.
9
+ A loop's notes leave with its `LOOP.md`, which its close commit removes; read each from git. Find
10
+ the base (`git merge-base HEAD origin/<default>`), list the commits that removed `LOOP.md`, newest
11
+ first: `git log --format=%H --diff-filter=D <merge-base>..HEAD -- LOOP.md`, and read each loop's
12
+ last `LOOP.md` from its parent: `git show <commit>^:LOOP.md`. A `LOOP.md` that was never
13
+ committed (a loop that made no commit) is gone: say so in the report. Then write the run report to `.geneseed/factory-runs/<slug>.md` at the worktree root, `<slug>`
10
14
  being the branch name after `loop/factory-`. First run `git check-ignore -q <that path>`: when it
11
15
  exits non-zero the path is not ignored, so write the report to the OS temp directory instead.
12
16
  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).
17
+ reason, each held outcome the user let through with `ok` (above all a locked path `checks`
18
+ reported), and how the run ended (closed, or stopped and why).
14
19
 
15
20
  Change nothing else: no tracked file, no commit. Only a lesson that will hold beyond this run —
16
21
  a cause that will recur, a check this project lacks — goes into memory, one entry, under Persist
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: review-panel
3
+ description: Review the branch's change with a panel of seats sized to the work item, each blind to how it was built, and merge their verdicts into one.
4
+ effect: read
5
+ skill: factory
6
+ outcomes: pass, fail
7
+ ---
8
+ You run this stage yourself and chair it; the seats are agents you dispatch. Never edit a file;
9
+ only put the tree back, as below.
10
+
11
+ Read `size:` and `areas:` from the latest `carry` an `intake` entry left in `FACTORY.md`'s
12
+ `history`, always; a missing or unknown size counts as `large`. That carry is also the work item,
13
+ except in `analysis-to-build`, where the work item text is the approved `specs/<slug>/spec.md`.
14
+ Pick the seats from the factory's `review.seats` in `FACTORY.md`: the list for that size, plus
15
+ the list for each area, each agent once. With no `review.seats`, seat `reviewer` alone.
16
+
17
+ Run `git fetch origin`, find the default branch (`gh repo view --json defaultBranchRef`, or `git
18
+ remote show origin`), then the base, `git merge-base HEAD origin/<default>`, and take the diff
19
+ without the engine files, which the loops commit: `git diff <merge-base> HEAD -- . ':!FACTORY.md'
20
+ ':!LOOP.md'`. Dispatch every seat in one parallel batch, each in its own context.
21
+ Each brief holds the work item, the factory's `rules` and the diff (inline for a seat that has no
22
+ shell, such as `steward` or `user-advocate`; else the base commit and that diff command, engine
23
+ files excluded), and states
24
+ three rules: read only the diff and the files it touches, never the history past the diff,
25
+ `LOOP.md`, `FACTORY.md` or the holdout folder; edit no file; return a verdict and its findings,
26
+ nothing else. Never add a loop note, the developer's reasoning or anything from the holdout folder
27
+ to a brief.
28
+
29
+ Chair. These verdicts fail the panel: `reviewer` `block` or `fix-then-ship`; `security`
30
+ `fix-required`; `tester` `STATUS: OK` with a failing test or an acceptance criterion it names
31
+ without a passing test. These pass: `reviewer` `ship`, `security` `safe to ship`, `tester` `STATUS:
32
+ OK` with neither. Advisory, never failing alone: `performance` (`within budget`, `fix-recommended`
33
+ or `cannot-measure`), `steward` and `user-advocate`. No verdict: `tester` `BLOCKED`, `ERROR` or
34
+ `OUT_OF_SCOPE`, a `reviewer` or `security` seat that declines to give one, or a seat that returns
35
+ nothing. Dispatch a seat with no verdict once more; a second time without one fails the panel.
36
+
37
+ Before you record, put the tree back as it was: restore every tracked file a seat changed (`git
38
+ restore --staged --worktree -- <path>`) and delete every untracked file a seat created (a test
39
+ run's output), naming each one in the finding. Never touch `FACTORY.md` or `LOOP.md`: they are
40
+ the run's state. Write one file in the OS temp directory: each
41
+ seat's verdict, then the findings that fail it (`file:line`, what is wrong, what to do instead),
42
+ then the advisory points. Pass on only findings about the diff, and never quote holdout text.
43
+ Report `fail` when any seat failed, else `pass`, with that file's path.
@@ -6,13 +6,27 @@ agent: architect
6
6
  gate: human
7
7
  outcomes: pass, fail
8
8
  ---
9
- Write `specs/<slug>/spec.md` (the slug of the loop's title) and touch nothing else — no code: the
10
- problem, what is out of scope, acceptance criteria in EARS form ("WHEN <trigger> THE SYSTEM SHALL
11
- <response>"), each one testable, and an ordered task list sized to one `identify` card apiece,
12
- ending with an end-to-end verification task. A gate amendment in LOOP.md's notes answers your
13
- open questions or corrects the spec: revise the spec to follow it.
9
+ Write `specs/<slug>/spec.md` and touch nothing else — no code. The slug is the run's: in a factory,
10
+ the factory run's `<slug>` (it never holds the words git, commit or push); in a loop, the slug
11
+ of the loop's title. Write the problem, what is out
12
+ of scope, acceptance criteria in EARS form ("WHEN <trigger> THE SYSTEM SHALL <response>"), each one
13
+ testable, and an ordered task list sized to one `identify` card apiece, ending with an end-to-end
14
+ verification task.
14
15
 
15
- The user reviews the spec before the loop continues. Report `pass` once every criterion is
16
+ Write the task list in the one form a factory counts. Put it under the spec's first heading that
17
+ contains the word `task` or `tasks` (any case, such as `## Tasks`). Under it, write each task as one
18
+ numbered item, `1.` or `1)`, indented 3 spaces at most; keep every task at the same indent. An
19
+ item indented as far as the text of the task above it (3 spaces under `1. `), numbered or not, is
20
+ a sub-item, not a task. A fenced code block (```` ``` ```` or `~~~`) neither ends the list nor
21
+ adds a task. A deeper heading keeps the list open; the next heading of the same or a higher level
22
+ ends it, `#` or underlined alike. List one task at least, and no more than the factory's task limit: a factory refuses a
23
+ longer list and names its limit (Geneseed's Factory actions reference states it), so split the
24
+ requirement instead.
25
+
26
+ An amendment answers your open questions or corrects the spec: in a factory it arrives as this
27
+ stage's `carry`, in a loop as a note in LOOP.md. Revise the spec to follow it.
28
+
29
+ The user reviews the spec before the work continues. Report `pass` once every criterion is
16
30
  testable, with the spec's path and its criteria count in a file in the OS temp directory — report
17
31
  that file's path. Report `fail` if a criterion cannot be stated testably: list the open questions
18
32
  in such a file and report its path; the user answers them with an amend.