geneseed 5.0.4 → 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 +45 -0
- package/SHIPPED.md +1 -1
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/factories.md +67 -15
- package/docs/concepts/loop-gates.md +5 -2
- package/docs/concepts/shared-tier.md +14 -0
- package/docs/extending.md +1 -1
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/run-a-factory.md +41 -13
- package/docs/guides/upgrade-to-5.md +2 -2
- package/docs/reference/factory-actions.md +7 -7
- package/docs/web-ui.md +18 -6
- package/harness.config.json +1 -1
- package/js/README.md +2 -1
- package/js/build/args.mjs +34 -14
- 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 +31 -11
- package/js/cli-table.json +29 -3
- package/js/factory/cli.mjs +49 -8
- package/js/factory/graph.mjs +72 -8
- package/js/factory/state.mjs +109 -27
- package/js/hosts/done-checks.mjs +3 -2
- package/js/hosts/memory-files.mjs +4 -2
- package/js/loop/catalog.mjs +16 -10
- package/js/loop/cli.mjs +16 -10
- package/js/maintain/migrate.mjs +39 -25
- package/js/web/daemon.mjs +69 -14
- package/js/web/handler.mjs +22 -9
- package/package.json +1 -1
- package/src/bricks/checks.md +62 -0
- package/src/bricks/intake.md +15 -6
- package/src/bricks/merge-gate.md +17 -8
- package/src/bricks/retro.md +8 -3
- package/src/bricks/review-panel.md +43 -0
- package/src/bricks/spec.md +20 -6
- package/src/factories/analysis-to-build.json +25 -7
- package/src/factories/bug-report-to-fix.json +25 -7
- package/src/factories/issue-to-pr.json +29 -11
- package/src/skills/factory-forge.md +23 -5
- package/src/skills/factory.md +95 -25
- package/src/skills/loop.md +3 -2
- package/themes/_TEMPLATE.json +1 -1
- package/web/dist/assets/{Activity-BaoxwVFH.js → Activity-CpkBwpu7.js} +1 -1
- package/web/dist/assets/{ActivityDetail-C_bFD0rW.js → ActivityDetail-DTPziZWM.js} +1 -1
- package/web/dist/assets/{Bonsai-B01lLf0m.js → Bonsai-hiG_gGNU.js} +1 -1
- package/web/dist/assets/{CopyButton-Bc66KPyA.js → CopyButton-DUIUfNp6.js} +1 -1
- package/web/dist/assets/{Dashboard-X7GZzGJp.js → Dashboard-Dnw6EyX7.js} +2 -2
- package/web/dist/assets/{Docs-LRYVnGLG.js → Docs-BEET_l16.js} +1 -1
- package/web/dist/assets/Factories-D6KXkfWw.js +1 -0
- package/web/dist/assets/{GreenhouseView-CfWR2-sX.js → GreenhouseView-BKxy5apE.js} +1 -1
- package/web/dist/assets/{Installs-nfFHnovH.js → Installs-CnFVlVD0.js} +1 -1
- package/web/dist/assets/{JournalView-lpOHcHKK.js → JournalView-ChFitHjo.js} +1 -1
- package/web/dist/assets/{Kits-Bw5EQl_i.js → Kits-CcR-OlwQ.js} +1 -1
- package/web/dist/assets/{Laws-CnZJ0wjZ.js → Laws-B1s5idOg.js} +1 -1
- package/web/dist/assets/LibRows-BZgdbI1l.js +1 -0
- package/web/dist/assets/Library-x6TkkEVF.js +3 -0
- package/web/dist/assets/{Loops-ZaHC5MVl.js → Loops-BH93KKxn.js} +1 -1
- package/web/dist/assets/{OperatorHudView-CggG0_sK.js → OperatorHudView-BO0aIKPL.js} +1 -1
- package/web/dist/assets/{Personal-BObvlb70.js → Personal-CE_0Vhh0.js} +1 -1
- package/web/dist/assets/{Settings-BFfPMPc9.js → Settings-CbpZvVN_.js} +1 -1
- package/web/dist/assets/{Tabs-B594Pad_.js → Tabs-C2oW7oEj.js} +1 -1
- package/web/dist/assets/{index-DsLmKHw0.js → index-BQwOmbor.js} +2 -2
- package/web/dist/assets/{index-DvPjphz0.css → index-CuIop_pO.css} +1 -1
- package/web/dist/index.html +2 -2
- package/web/dist/assets/Factories-ARenKBiP.js +0 -1
- package/web/dist/assets/LibRows-Hqvf1beK.js +0 -1
- package/web/dist/assets/Library-JaSsp6Yr.js +0 -3
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
|
|
149
|
-
*
|
|
150
|
-
*
|
|
151
|
-
*
|
|
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
|
-
/**
|
|
167
|
-
|
|
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
|
|
183
|
-
* the port
|
|
184
|
-
* ended on a claim, and no pid is
|
|
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`);
|
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, 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
|
|
75
|
-
* install secret (`secretProof`), so
|
|
76
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
"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",
|
|
@@ -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`.
|
package/src/bricks/intake.md
CHANGED
|
@@ -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).
|
|
17
|
-
|
|
18
|
-
|
|
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.
|
package/src/bricks/merge-gate.md
CHANGED
|
@@ -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
|
|
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
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
21
|
-
|
|
22
|
-
|
|
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.
|
package/src/bricks/retro.md
CHANGED
|
@@ -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
|
-
|
|
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,
|
|
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.
|
package/src/bricks/spec.md
CHANGED
|
@@ -6,13 +6,27 @@ agent: architect
|
|
|
6
6
|
gate: human
|
|
7
7
|
outcomes: pass, fail
|
|
8
8
|
---
|
|
9
|
-
Write `specs/<slug>/spec.md`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
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.
|
|
@@ -1,22 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "analysis-to-build",
|
|
3
|
-
"description": "Turn an analysis (a document, pasted text or a request) into a spec whose task list you approve, build each task in turn with the feature loop in one worktree, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed scenario or red CI sends the work back to the loop as one more task, twice at most each.
|
|
3
|
+
"description": "Turn an analysis (a document, pasted text or a request) into a spec whose task list you approve, build each task in turn with the feature loop in one worktree, run the base branch's checks and a review panel, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the work back to the loop as one more task, twice at most each. At the end it asks you once whether to merge.",
|
|
4
4
|
"category": "development",
|
|
5
5
|
"rules": [
|
|
6
|
-
"Never merge
|
|
6
|
+
"Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
|
|
7
7
|
"Push only this worktree's own branch."
|
|
8
8
|
],
|
|
9
|
-
"stages": ["intake", "spec", "holdout-write", "loop:feature", "holdout", "pr-open", "merge-gate", "retro"],
|
|
9
|
+
"stages": ["intake", "spec", "holdout-write", "loop:feature", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
|
|
10
10
|
"start": "intake",
|
|
11
11
|
"edges": [
|
|
12
12
|
{ "from": "intake", "on": "pass", "to": "spec" },
|
|
13
13
|
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
|
+
{ "from": "intake", "on": "needs-info", "to": "spec" },
|
|
14
15
|
{ "from": "spec", "on": "pass", "to": "holdout-write" },
|
|
15
16
|
{ "from": "spec", "on": "fail", "to": "$stop" },
|
|
16
17
|
{ "from": "holdout-write", "on": "pass", "to": "loop:feature" },
|
|
17
18
|
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
18
|
-
{ "from": "loop:feature", "on": "pass", "to": "
|
|
19
|
+
{ "from": "loop:feature", "on": "pass", "to": "checks" },
|
|
19
20
|
{ "from": "loop:feature", "on": "fail", "to": "$stop" },
|
|
21
|
+
{ "from": "checks", "on": "pass", "to": "review-panel" },
|
|
22
|
+
{ "from": "checks", "on": "fail", "to": "loop:feature" },
|
|
23
|
+
{ "from": "checks", "on": "error", "to": "review-panel" },
|
|
24
|
+
{ "from": "checks", "on": "none", "to": "checks" },
|
|
25
|
+
{ "from": "review-panel", "on": "pass", "to": "holdout" },
|
|
26
|
+
{ "from": "review-panel", "on": "fail", "to": "loop:feature" },
|
|
20
27
|
{ "from": "holdout", "on": "pass", "to": "pr-open" },
|
|
21
28
|
{ "from": "holdout", "on": "fail", "to": "loop:feature" },
|
|
22
29
|
{ "from": "holdout", "on": "error", "to": "$stop" },
|
|
@@ -28,7 +35,18 @@
|
|
|
28
35
|
{ "from": "retro", "on": "pass", "to": "$close" }
|
|
29
36
|
],
|
|
30
37
|
"cycles": [
|
|
31
|
-
{ "name": "
|
|
32
|
-
{ "name": "
|
|
33
|
-
|
|
38
|
+
{ "name": "done-list", "nodes": ["checks"], "max": 1 },
|
|
39
|
+
{ "name": "checks", "nodes": ["loop:feature", "checks"], "max": 2 },
|
|
40
|
+
{ "name": "review", "nodes": ["loop:feature", "checks", "review-panel"], "max": 2 },
|
|
41
|
+
{ "name": "holdout", "nodes": ["loop:feature", "checks", "review-panel", "holdout"], "max": 2 },
|
|
42
|
+
{ "name": "ci", "nodes": ["loop:feature", "checks", "review-panel", "holdout", "pr-open", "merge-gate"], "max": 2 }
|
|
43
|
+
],
|
|
44
|
+
"review": {
|
|
45
|
+
"seats": {
|
|
46
|
+
"small": ["reviewer"],
|
|
47
|
+
"medium": ["reviewer", "tester"],
|
|
48
|
+
"large": ["reviewer", "tester", "steward"],
|
|
49
|
+
"areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] }
|
|
50
|
+
}
|
|
51
|
+
}
|
|
34
52
|
}
|
|
@@ -1,20 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bug-report-to-fix",
|
|
3
|
-
"description": "Take one bug report, fix it with the bugfix loop, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed scenario or red CI sends the fix back to the loop, twice at most each.
|
|
3
|
+
"description": "Take one bug report, fix it with the bugfix loop, run the base branch's checks and a review panel, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed check, review or scenario, or red CI, sends the fix back to the loop, twice at most each. At the end it asks you once whether to merge.",
|
|
4
4
|
"category": "development",
|
|
5
5
|
"rules": [
|
|
6
|
-
"Never merge
|
|
6
|
+
"Never merge or enable auto-merge without the user's yes, asked once at the end of the run.",
|
|
7
7
|
"Push only this worktree's own branch."
|
|
8
8
|
],
|
|
9
|
-
"stages": ["intake", "holdout-write", "loop:bugfix", "holdout", "pr-open", "merge-gate", "retro"],
|
|
9
|
+
"stages": ["intake", "holdout-write", "loop:bugfix", "checks", "review-panel", "holdout", "pr-open", "merge-gate", "retro"],
|
|
10
10
|
"start": "intake",
|
|
11
11
|
"edges": [
|
|
12
12
|
{ "from": "intake", "on": "pass", "to": "holdout-write" },
|
|
13
13
|
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
|
+
{ "from": "intake", "on": "needs-info", "to": "holdout-write" },
|
|
14
15
|
{ "from": "holdout-write", "on": "pass", "to": "loop:bugfix" },
|
|
15
16
|
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
16
|
-
{ "from": "loop:bugfix", "on": "pass", "to": "
|
|
17
|
+
{ "from": "loop:bugfix", "on": "pass", "to": "checks" },
|
|
17
18
|
{ "from": "loop:bugfix", "on": "fail", "to": "$stop" },
|
|
19
|
+
{ "from": "checks", "on": "pass", "to": "review-panel" },
|
|
20
|
+
{ "from": "checks", "on": "fail", "to": "loop:bugfix" },
|
|
21
|
+
{ "from": "checks", "on": "error", "to": "review-panel" },
|
|
22
|
+
{ "from": "checks", "on": "none", "to": "checks" },
|
|
23
|
+
{ "from": "review-panel", "on": "pass", "to": "holdout" },
|
|
24
|
+
{ "from": "review-panel", "on": "fail", "to": "loop:bugfix" },
|
|
18
25
|
{ "from": "holdout", "on": "pass", "to": "pr-open" },
|
|
19
26
|
{ "from": "holdout", "on": "fail", "to": "loop:bugfix" },
|
|
20
27
|
{ "from": "holdout", "on": "error", "to": "$stop" },
|
|
@@ -26,7 +33,18 @@
|
|
|
26
33
|
{ "from": "retro", "on": "pass", "to": "$close" }
|
|
27
34
|
],
|
|
28
35
|
"cycles": [
|
|
29
|
-
{ "name": "
|
|
30
|
-
{ "name": "
|
|
31
|
-
|
|
36
|
+
{ "name": "done-list", "nodes": ["checks"], "max": 1 },
|
|
37
|
+
{ "name": "checks", "nodes": ["loop:bugfix", "checks"], "max": 2 },
|
|
38
|
+
{ "name": "review", "nodes": ["loop:bugfix", "checks", "review-panel"], "max": 2 },
|
|
39
|
+
{ "name": "holdout", "nodes": ["loop:bugfix", "checks", "review-panel", "holdout"], "max": 2 },
|
|
40
|
+
{ "name": "ci", "nodes": ["loop:bugfix", "checks", "review-panel", "holdout", "pr-open", "merge-gate"], "max": 2 }
|
|
41
|
+
],
|
|
42
|
+
"review": {
|
|
43
|
+
"seats": {
|
|
44
|
+
"small": ["reviewer"],
|
|
45
|
+
"medium": ["reviewer", "tester"],
|
|
46
|
+
"large": ["reviewer", "tester", "steward"],
|
|
47
|
+
"areas": { "security": ["security"], "performance": ["performance"], "ui": ["user-advocate"], "data": ["security"] }
|
|
48
|
+
}
|
|
49
|
+
}
|
|
32
50
|
}
|