geneseed 5.0.3 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +83 -0
- package/README.md +3 -3
- package/SHIPPED.md +2 -2
- package/adapters/claude-code/README.md +5 -1
- package/adapters/openclaude/README.md +3 -1
- package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
- package/adapters/opencode/workflows/_runtime.js +1 -1
- package/bin/geneseed-cli.mjs +3 -0
- package/bin/geneseed-hook.mjs +10 -2
- package/docs/PRD.md +1 -1
- package/docs/README.md +4 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/factories.md +203 -0
- package/docs/concepts/hooks.md +1 -1
- package/docs/concepts/host-matrix.md +1 -0
- package/docs/concepts/loop-gates.md +6 -0
- package/docs/concepts/loops.md +1 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/concepts/shared-tier.md +14 -0
- package/docs/extending.md +5 -1
- package/docs/guides/autostart.md +2 -0
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/run-a-factory.md +116 -0
- package/docs/guides/set-up-ownership.md +1 -0
- package/docs/guides/upgrade-to-5.md +2 -2
- package/docs/reference/factory-actions.md +22 -0
- package/docs/reference/loop-actions.md +1 -1
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/web-ui.md +47 -2
- package/harness.config.json +1 -1
- package/js/README.md +21 -2
- package/js/build/args.mjs +44 -12
- package/js/build/emit-claude.mjs +3 -0
- package/js/build/emit-opencode.mjs +4 -0
- package/js/build/retired-skills.mjs +158 -0
- package/js/build/source.mjs +41 -2
- package/js/cli-table.json +193 -3
- package/js/factory/cli.mjs +194 -0
- package/js/factory/graph.mjs +309 -0
- package/js/factory/registry.mjs +71 -0
- package/js/factory/state.mjs +511 -0
- package/js/hosts/activity.mjs +3 -3
- package/js/hosts/done-checks.mjs +3 -2
- package/js/hosts/geneseed-dir.mjs +1 -1
- package/js/hosts/gitref.mjs +21 -0
- package/js/hosts/hooks-context.mjs +63 -9
- package/js/hosts/hooks-prims.mjs +1 -1
- package/js/hosts/memory-files.mjs +4 -2
- package/js/hosts/settings.mjs +5 -4
- package/js/inspect/checks-authoring.mjs +11 -1
- package/js/inspect/cost.mjs +91 -5
- package/js/inspect/doctor.mjs +2 -1
- package/js/inspect/inventory.mjs +1 -1
- package/js/loop/catalog.mjs +30 -12
- package/js/loop/cli.mjs +27 -15
- package/js/loop/graph.mjs +13 -4
- package/js/loop/registry.mjs +65 -28
- package/js/loop/state.mjs +18 -8
- package/js/maintain/migrate.mjs +39 -25
- package/js/web/api.mjs +43 -1
- package/js/web/catalog.mjs +38 -2
- package/js/web/daemon.mjs +191 -6
- package/js/web/handler.mjs +27 -5
- package/js/web/routes.mjs +10 -3
- package/js/web/server.mjs +4 -1
- package/package.json +1 -1
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +5 -7
- package/src/bricks/checks.md +62 -0
- package/src/bricks/docs-update.md +5 -0
- package/src/bricks/holdout-write.md +23 -0
- package/src/bricks/holdout.md +25 -0
- package/src/bricks/intake.md +27 -0
- package/src/bricks/merge-gate.md +31 -0
- package/src/bricks/pr-open.md +21 -0
- package/src/bricks/retro.md +22 -0
- package/src/bricks/review-panel.md +43 -0
- package/src/bricks/spec.md +20 -6
- package/src/bricks/test.md +4 -1
- package/src/bricks/triage.md +19 -0
- package/src/doctrines/comms.md +29 -41
- package/src/doctrines/craft.md +3 -10
- package/src/doctrines/ops.md +4 -15
- package/src/doctrines/rigor.md +1 -5
- package/src/factories/analysis-to-build.json +52 -0
- package/src/factories/bug-report-to-fix.json +50 -0
- package/src/factories/issue-to-pr.json +67 -0
- package/src/skills/_checkpoints.md +1 -0
- package/src/skills/adhd.md +1 -1
- package/src/skills/factory-forge.md +115 -0
- package/src/skills/factory.md +196 -0
- package/src/skills/loop.md +3 -2
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/workflow.md +2 -1
- package/themes/_TEMPLATE.json +4 -2
- package/themes/biker.json +4 -2
- package/themes/commentator.json +4 -2
- package/themes/cyberpunk.json +4 -2
- package/themes/gamer.json +4 -2
- package/themes/imperial.json +4 -2
- package/themes/joker.json +4 -2
- package/themes/marvin.json +4 -2
- package/themes/mean.json +4 -2
- package/themes/military.json +4 -2
- package/themes/neutral.json +4 -2
- package/themes/pirate.json +4 -2
- package/themes/sports.json +4 -2
- package/themes/verstappen.json +4 -2
- package/themes/wizard.json +4 -2
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
- package/web/dist/assets/{Activity-Ck_Xffpo.js → Activity-CpkBwpu7.js} +1 -1
- package/web/dist/assets/{ActivityDetail-CBxVS4mU.js → ActivityDetail-DTPziZWM.js} +1 -1
- package/web/dist/assets/{Bonsai-BlOwsvW6.js → Bonsai-hiG_gGNU.js} +1 -1
- package/web/dist/assets/{CopyButton-DFMOIGbe.js → CopyButton-DUIUfNp6.js} +1 -1
- package/web/dist/assets/Dashboard-Dnw6EyX7.js +2 -0
- package/web/dist/assets/{Docs-D_2Jt6gU.js → Docs-BEET_l16.js} +2 -2
- package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
- package/web/dist/assets/{GreenhouseView-WalcX5bp.js → GreenhouseView-BKxy5apE.js} +1 -1
- package/web/dist/assets/{Installs-UGiPDMDt.js → Installs-CnFVlVD0.js} +3 -3
- package/web/dist/assets/{JournalView-CZtXQz-v.js → JournalView-ChFitHjo.js} +1 -1
- package/web/dist/assets/{Kits-XQHsazCN.js → Kits-CcR-OlwQ.js} +1 -1
- package/web/dist/assets/Laws-B1s5idOg.js +4 -0
- package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
- package/web/dist/assets/Library-x6TkkEVF.js +3 -0
- package/web/dist/assets/Loops-BH93KKxn.js +2 -0
- package/web/dist/assets/{OperatorHudView-CeDw5qMB.js → OperatorHudView-BO0aIKPL.js} +1 -1
- package/web/dist/assets/{Personal-PVmGA2-M.js → Personal-CE_0Vhh0.js} +2 -2
- package/web/dist/assets/{Settings-DWuxwh4i.js → Settings-CbpZvVN_.js} +1 -1
- package/web/dist/assets/{Tabs-d2RIRAKT.js → Tabs-C2oW7oEj.js} +1 -1
- package/web/dist/assets/api-DLDVY3K-.js +1 -0
- package/web/dist/assets/{index-BNttaGQb.js → index-BQwOmbor.js} +3 -3
- package/web/dist/assets/index-CuIop_pO.css +1 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Dashboard-BUdUTjbB.js +0 -2
- package/web/dist/assets/Laws-B6A55S-2.js +0 -4
- package/web/dist/assets/Library-D7L0Wdbh.js +0 -3
- package/web/dist/assets/Loops-C0loS73u.js +0 -2
- package/web/dist/assets/RailCats-BGZnJ6fa.js +0 -1
- package/web/dist/assets/api-BMFDSXoB.js +0 -1
- package/web/dist/assets/index-BEI5ugYQ.css +0 -1
package/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,148 @@ 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. `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).
|
|
131
|
+
*/
|
|
132
|
+
export async function identify(port, timeout = 0.5, shutdown = false) {
|
|
133
|
+
try {
|
|
134
|
+
const res = await fetch(`http://127.0.0.1:${port}/api/ping${shutdown ? '?shutdown=1' : ''}`, {
|
|
135
|
+
signal: AbortSignal.timeout(Math.round(timeout * 1000)),
|
|
136
|
+
});
|
|
137
|
+
const body = res.status === 200 ? await res.json() : null;
|
|
138
|
+
await res.body?.cancel().catch(() => {});
|
|
139
|
+
if (body?.ok !== true || typeof body.theme !== 'string' || !validPid(body.pid)) return 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 };
|
|
142
|
+
} catch {
|
|
143
|
+
return null;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** A pid worth showing: an integer above 1. 0, 1 and negatives are never a console. */
|
|
148
|
+
const validPid = (p) => Number.isInteger(p) && p > 1;
|
|
149
|
+
|
|
150
|
+
/**
|
|
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.
|
|
158
|
+
* `null` when the file can be neither read nor created — the feature is then off.
|
|
159
|
+
*/
|
|
160
|
+
export function webSecret(target) {
|
|
161
|
+
const p = join(target, '.geneseed-web-secret');
|
|
162
|
+
const read = () => { try { return readFileSync(p, 'utf-8').trim() || null; } catch { return null; } };
|
|
163
|
+
const have = read();
|
|
164
|
+
if (have) return have;
|
|
165
|
+
try {
|
|
166
|
+
mkdirSync(target, { recursive: true });
|
|
167
|
+
writeFileSync(p, randomBytes(32).toString('base64url'), { flag: 'wx', mode: 0o600 });
|
|
168
|
+
} catch { /* lost a race, or unwritable: read decides */ }
|
|
169
|
+
return read();
|
|
170
|
+
}
|
|
171
|
+
|
|
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
|
+
}
|
|
208
|
+
|
|
209
|
+
/** Can a server bind `port` on loopback right now? `true` means something else holds it. */
|
|
210
|
+
export const portTaken = (port) => new Promise((resolve) => {
|
|
211
|
+
const s = createServer();
|
|
212
|
+
s.once('error', () => resolve(true));
|
|
213
|
+
s.listen(port, '127.0.0.1', () => s.close(() => resolve(false)));
|
|
214
|
+
});
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Free `port` for a new console, or say why not. `null` when it is free (possibly after ending
|
|
218
|
+
* the previous console of THIS install, found by its root id in the ping); otherwise a phrase
|
|
219
|
+
* naming the holder, and nothing touched. Another install's console, a console too old to name
|
|
220
|
+
* its install, and any other program are never ended.
|
|
221
|
+
*
|
|
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.
|
|
230
|
+
*/
|
|
231
|
+
export async function clearPort(port, target) {
|
|
232
|
+
if (!await portTaken(port)) return null;
|
|
233
|
+
const c = await identify(port);
|
|
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
|
+
}
|
|
245
|
+
const secret = webSecret(target);
|
|
246
|
+
const asked = secret !== null && await postShutdown(`http://127.0.0.1:${port}`, '', 3.0,
|
|
247
|
+
{ 'X-Geneseed-Nonce': n, 'X-Geneseed-Secret': secretProof(secret, port, n) });
|
|
248
|
+
for (let i = 0; asked && i < 50 && await portTaken(port); i += 1) await sleep(100);
|
|
249
|
+
if (asked && !await portTaken(port)) {
|
|
250
|
+
printOut(`[web] ended the previous console of this install on port ${port} (pid ${c.pid}).\n`);
|
|
251
|
+
return null;
|
|
252
|
+
}
|
|
253
|
+
return `held by a console (pid ${c.pid}) that claims this install but did not shut down on request`;
|
|
254
|
+
}
|
|
255
|
+
if (!c) return 'held by another program';
|
|
256
|
+
return `held by a Geneseed console (pid ${c.pid}) of ${c.root ? 'another install'
|
|
257
|
+
: 'an unknown install (older code) — end that pid yourself'}`;
|
|
258
|
+
}
|
|
259
|
+
|
|
109
260
|
/** The token-carrying POST `geneseed web stop` and the in-page Stop button both send. */
|
|
110
|
-
async function postShutdown(url, token, timeout = 3.0) {
|
|
261
|
+
async function postShutdown(url, token, timeout = 3.0, extra = {}) {
|
|
111
262
|
try {
|
|
112
263
|
const res = await fetch(`${url}/api/shutdown`, {
|
|
113
264
|
method: 'POST',
|
|
114
|
-
headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json' },
|
|
265
|
+
headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json', ...extra },
|
|
115
266
|
body: '{}',
|
|
116
267
|
signal: AbortSignal.timeout(Math.round(timeout * 1000)),
|
|
117
268
|
});
|
|
@@ -198,6 +349,13 @@ export function restartArgs(theme) {
|
|
|
198
349
|
* to stop, started a fresh daemon on 4747 while this process still held it, lost the bind,
|
|
199
350
|
* fell back to a random port, and left a background console nobody had asked for.
|
|
200
351
|
*/
|
|
352
|
+
export function restartRefusal(theme) {
|
|
353
|
+
const rec = readDaemon(webState(theme).target);
|
|
354
|
+
if (!isTruthy(rec) || !validPid(rec.pid)) return 'foreground server: restart it from its terminal';
|
|
355
|
+
return `this console (pid ${process.pid}) is not the recorded daemon — that one is on ${none(rec.url)} `
|
|
356
|
+
+ `(pid ${rec.pid}). Restart it there, or end pid ${process.pid}.`;
|
|
357
|
+
}
|
|
358
|
+
|
|
201
359
|
export function requestRestart(theme) {
|
|
202
360
|
const target = webState(theme).target;
|
|
203
361
|
if (readDaemon(target)?.pid !== process.pid) return false;
|
|
@@ -272,6 +430,9 @@ export async function startDaemon(theme, port, openBrowser = true) {
|
|
|
272
430
|
return 0;
|
|
273
431
|
}
|
|
274
432
|
clearDaemon(target);
|
|
433
|
+
const held = await clearPort(port, target);
|
|
434
|
+
if (held) printOut(`[web] port ${port} is ${held} — not touching it; the console will use another port.
|
|
435
|
+
`);
|
|
275
436
|
const log = join(target, '.geneseed-web.log');
|
|
276
437
|
spawnDetached(daemonArgs(port, theme), log);
|
|
277
438
|
// Twelve seconds for the child to bind and write its record (60 * 200ms). The probe
|
|
@@ -282,6 +443,8 @@ export async function startDaemon(theme, port, openBrowser = true) {
|
|
|
282
443
|
if (rec && isTruthy(rec.url) && await probe(rec.url, 0.5)) {
|
|
283
444
|
printOut(`[web] Geneseed UI on ${rec.url} (theme: ${none(rec.theme)}, `
|
|
284
445
|
+ `pid ${none(rec.pid)})\n`);
|
|
446
|
+
if (rec.port !== port) printOut(`[web] asked for port ${port}, serving on port ${rec.port} instead.
|
|
447
|
+
`);
|
|
285
448
|
printOut('[web] running in the background — `geneseed web stop` to stop it.\n');
|
|
286
449
|
if (openBrowser) openUrl(rec.url);
|
|
287
450
|
return 0;
|
|
@@ -355,19 +518,41 @@ export async function stopDaemon(theme = null, port = null) {
|
|
|
355
518
|
return 0;
|
|
356
519
|
}
|
|
357
520
|
|
|
358
|
-
|
|
521
|
+
/** Every Geneseed console answering on the recorded port or `ports`, each once. */
|
|
522
|
+
export async function findConsoles(target, ports) {
|
|
523
|
+
const rec = readDaemon(target);
|
|
524
|
+
const all = [...new Set([isTruthy(rec) ? Number(rec.port) : null, ...ports].filter(Number.isInteger))];
|
|
525
|
+
const found = [];
|
|
526
|
+
for (const p of all) {
|
|
527
|
+
// eslint-disable-next-line no-await-in-loop
|
|
528
|
+
const c = await identify(p);
|
|
529
|
+
if (c) found.push({ port: p, url: `http://127.0.0.1:${p}`, pid: c.pid, root: c.root,
|
|
530
|
+
recorded: isTruthy(rec) && rec.pid === c.pid && Number(rec.port) === p });
|
|
531
|
+
}
|
|
532
|
+
return found;
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
const whose = (c) => (c.root === null ? 'older code, install unknown' : c.root === rootId() ? 'this install' : 'another install');
|
|
536
|
+
|
|
537
|
+
export async function statusDaemon(theme = null, port = null, scan = [DEFAULT_PORT]) {
|
|
359
538
|
const { target } = webState(theme);
|
|
360
539
|
const refused = await portRefusal(readDaemon(target), port, 'status');
|
|
361
540
|
if (refused !== null) return refused;
|
|
362
541
|
const st = await liveDaemon(target);
|
|
542
|
+
// Unnamed port only: `--port` already scoped this call to one daemon (`portRefusal`).
|
|
543
|
+
const others = port === null ? (await findConsoles(target, scan)).filter((c) => !(st && c.recorded)) : [];
|
|
544
|
+
const listOthers = () => others.forEach((c) => printOut(
|
|
545
|
+
`[web] also found a Geneseed console at ${c.url} (pid ${c.pid}, not recorded — ${whose(c)})\n`));
|
|
363
546
|
if (st) {
|
|
364
547
|
printOut(`[web] running on ${st.url} (theme: ${none(st.theme)}, pid ${none(st.pid)})\n`);
|
|
365
548
|
if (daemonStale(st)) printOut(`${STALE_LINE}\n`);
|
|
549
|
+
listOthers();
|
|
366
550
|
return 0;
|
|
367
551
|
}
|
|
368
552
|
// EXIT 1, which is the verb's whole contract for a script. The snapshot's `<exit>`
|
|
369
553
|
// column is what gates it.
|
|
370
554
|
printOut('[web] not running.\n');
|
|
555
|
+
listOthers();
|
|
371
556
|
return 1;
|
|
372
557
|
}
|
|
373
558
|
|
package/js/web/handler.mjs
CHANGED
|
@@ -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 { 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,8 +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 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.
|
|
74
79
|
*/
|
|
75
|
-
export function requestGuard(req, token) {
|
|
80
|
+
export function requestGuard(req, token, secret = null, nonces = null) {
|
|
76
81
|
const host = req.headers.host || '';
|
|
77
82
|
// Exact `name:port`, not `localHost` + a suffix test: that pair let `[::1]x.evil:4747` and
|
|
78
83
|
// `localhost:1:4747` through. Lower-cased the way browsers send it.
|
|
@@ -91,6 +96,14 @@ export function requestGuard(req, token) {
|
|
|
91
96
|
}
|
|
92
97
|
}
|
|
93
98
|
if (req.method !== 'GET') {
|
|
99
|
+
const proof = req.headers['x-geneseed-secret'];
|
|
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)) {
|
|
103
|
+
const have = Buffer.from(proof, 'utf-8');
|
|
104
|
+
const need = Buffer.from(secretProof(secret, req.socket.localPort, nonce), 'utf-8');
|
|
105
|
+
if (have.length === need.length && timingSafeEqual(have, need)) return null;
|
|
106
|
+
}
|
|
94
107
|
const got = Buffer.from(String(req.headers['x-geneseed-token'] ?? ''), 'utf-8');
|
|
95
108
|
const want = Buffer.from(token, 'utf-8');
|
|
96
109
|
if (got.length !== want.length || !timingSafeEqual(got, want)) {
|
|
@@ -130,6 +143,8 @@ export function makeHandler(state, jm, token, dist, holder = null) {
|
|
|
130
143
|
// syscall against the readFileSync + gzipSync it saves. `gz` is the gzipped body,
|
|
131
144
|
// computed once on the first gzip-accepting request instead of per request.
|
|
132
145
|
const staticCache = new Map();
|
|
146
|
+
// This console's shutdown nonces (`nonceBook`), minted by `/api/ping?shutdown=1`.
|
|
147
|
+
const nonces = nonceBook();
|
|
133
148
|
// `dist` RESOLVED ONCE, because every path compared against it below is resolved too.
|
|
134
149
|
// `resolvePath` is `realpathSync.native`, so a checkout reached by any path that is not its
|
|
135
150
|
// canonical one — a symlink, a Windows junction, a `subst` or mapped drive, an 8.3 short name,
|
|
@@ -221,8 +236,15 @@ export function makeHandler(state, jm, token, dist, holder = null) {
|
|
|
221
236
|
}
|
|
222
237
|
// `pid` is what a restarting client waits on: the OLD server keeps answering this ping for
|
|
223
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.
|
|
224
242
|
if (path === '/api/ping') {
|
|
225
|
-
|
|
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);
|
|
226
248
|
}
|
|
227
249
|
for (const [prefix, handler] of PREFIX_ROUTES) {
|
|
228
250
|
if (path.startsWith(prefix)) return sendJson(res, handler(st, path, state), 200, ae);
|
|
@@ -268,7 +290,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
|
|
|
268
290
|
if (jm.busy) return sendJson(res, BUSY, 409, ae);
|
|
269
291
|
if (!requestRestart(state.theme)) {
|
|
270
292
|
return sendJson(res,
|
|
271
|
-
{ error:
|
|
293
|
+
{ error: restartRefusal(state.theme) }, 409, ae);
|
|
272
294
|
}
|
|
273
295
|
return sendJson(res, { restarting: true }, 200, ae);
|
|
274
296
|
}
|
|
@@ -447,7 +469,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
|
|
|
447
469
|
const path = (req.url || '').split('?', 1)[0];
|
|
448
470
|
try {
|
|
449
471
|
// GUARD FIRST, BODY SECOND: a refused request is DISCARDED (`resume`, nothing buffered).
|
|
450
|
-
const refused = requestGuard(req, token);
|
|
472
|
+
const refused = requestGuard(req, token, holder?.secret, nonces);
|
|
451
473
|
if (refused) {
|
|
452
474
|
sendJson(res, refused.body, refused.code, ae);
|
|
453
475
|
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
|
|
4
|
+
"version": "5.1.0",
|
|
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)
|
|
310
|
-
|
|
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
|
|
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
|
|
@@ -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`.
|
|
@@ -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,27 @@
|
|
|
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, or ask the user what only they can answer.
|
|
4
|
+
effect: read
|
|
5
|
+
agent: explorer
|
|
6
|
+
outcomes: pass, fail, needs-info
|
|
7
|
+
gate: human
|
|
8
|
+
gateOn: needs-info
|
|
9
|
+
---
|
|
10
|
+
The stage hands you the run's `requirement` and its `input`: free text, a file path, or an issue (a
|
|
11
|
+
GitHub URL or `#<n>`: `gh issue view <n> --json title,body,comments,labels`; a GitLab one:
|
|
12
|
+
`glab issue view <n> --comments`). Read the input in full, then the code it names. Never edit any
|
|
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.
|
|
16
|
+
|
|
17
|
+
Write the work item to a file in the OS temp directory, never inside the worktree: a one-line
|
|
18
|
+
title, what happens now, what should happen, how to reproduce it, the files it likely touches,
|
|
19
|
+
and the acceptance criteria, each one testable. Quote the source for each claim (issue comment,
|
|
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.
|