geneseed 5.1.1 → 5.3.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 +52 -0
- package/README.md +2 -2
- package/SHIPPED.md +1 -1
- package/adapters/opencode/README.md +4 -3
- package/adapters/opencode/plugins/geneseed-context.js +82 -29
- package/adapters/opencode/plugins/geneseed-guard.js +118 -8
- package/bin/geneseed-cli.mjs +64 -16
- package/bin/geneseed-hook.mjs +37 -3
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/factories.md +40 -6
- package/docs/concepts/footprint.md +1 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/host-matrix.md +1 -1
- package/docs/concepts/loop-gates.md +1 -1
- package/docs/concepts/loops.md +2 -2
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/design-history.md +140 -0
- package/docs/extending.md +54 -162
- package/docs/guides/run-a-factory.md +15 -2
- package/docs/guides/setup-doctrines.md +1 -1
- package/docs/guides/upgrade.md +2 -2
- package/docs/reference/factory-actions.md +6 -5
- package/docs/reference/troubleshoot-update.md +1 -1
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/web-ui.md +16 -3
- package/harness.config.json +1 -1
- package/js/README.md +10 -7
- package/js/build/args.mjs +10 -4
- package/js/build/bundle.mjs +122 -23
- package/js/build/driver.mjs +32 -12
- package/js/build/emit-claude.mjs +2 -1
- package/js/build/emit-common.mjs +2 -2
- package/js/build/emit-opencode.mjs +22 -10
- package/js/build/export.mjs +431 -0
- package/js/build/generate.mjs +3 -0
- package/js/build/render.mjs +44 -24
- package/js/build/source.mjs +6 -1
- package/js/cli-table.json +232 -57
- package/js/factory/cli.mjs +24 -5
- package/js/factory/graph.mjs +13 -9
- package/js/factory/metrics.mjs +93 -0
- package/js/factory/registry.mjs +37 -12
- package/js/factory/state.mjs +25 -6
- package/js/hosts/hooks-context.mjs +26 -1
- package/js/hosts/hooks-done.mjs +8 -2
- package/js/hosts/hooks-prims.mjs +52 -3
- package/js/hosts/hooks.mjs +155 -33
- package/js/hosts/hosts.mjs +2 -4
- package/js/hosts/installs.mjs +28 -0
- package/js/hosts/loss.mjs +25 -3
- package/js/hosts/native.mjs +30 -2
- package/js/hosts/owned.mjs +55 -1
- package/js/hosts/ownership-gate.mjs +5 -5
- package/js/hosts/settings.mjs +83 -33
- package/js/inspect/diff.mjs +16 -1
- package/js/inspect/doctor.mjs +7 -3
- package/js/inspect/excludes.mjs +18 -6
- package/js/inspect/status.mjs +35 -7
- package/js/inspect/validate.mjs +44 -21
- package/js/lib/managed-block.mjs +74 -0
- package/js/maintain/uninstall.mjs +85 -15
- package/js/maintain/update.mjs +31 -7
- package/js/ui/cli.mjs +34 -4
- package/js/ui/menu.mjs +1 -1
- package/js/ui/tui.mjs +11 -14
- package/js/web/actions.mjs +5 -0
- package/js/web/api.mjs +32 -11
- package/js/web/daemon.mjs +0 -1
- package/js/web/server.mjs +1 -0
- package/js/web/state.mjs +37 -16
- package/package.json +1 -1
- package/src/AGENT.md.tmpl +23 -17
- package/src/agents/_template.md +1 -1
- package/src/agents/advocate.md +1 -1
- package/src/agents/developer.md +12 -3
- package/src/agents/empiricist.md +1 -1
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/bricks/intake.md +10 -3
- package/src/bricks/retro.md +13 -3
- package/src/doctrines/comms.md +1 -1
- package/src/doctrines/ops.md +1 -1
- package/src/doctrines/process.md +7 -5
- package/src/factories/analysis-to-build.json +1 -0
- package/src/factories/bug-report-to-fix.json +1 -0
- package/src/factories/issue-to-pr.json +1 -0
- package/src/laws/universal.md +2 -2
- package/src/modes/foreman.md +8 -14
- package/src/skills/commit.md +7 -2
- package/src/skills/debug.md +1 -1
- package/src/skills/diagram-design/SKILL.md +1 -1
- package/src/skills/diagram-design/VENDOR.md +3 -1
- package/src/skills/factory-forge.md +5 -3
- package/src/skills/factory.md +22 -1
- package/src/skills/geneseed.md +1 -1
- package/src/skills/handoff.md +1 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +6 -6
- package/src/skills/plan.md +7 -3
- package/src/skills/spring-testing.md +1 -1
- package/themes/biker.json +78 -78
- package/themes/commentator.json +81 -81
- package/themes/cyberpunk.json +79 -79
- package/themes/gamer.json +77 -77
- package/themes/imperial.json +82 -82
- package/themes/joker.json +79 -79
- package/themes/marvin.json +82 -82
- package/themes/mean.json +82 -82
- package/themes/military.json +78 -78
- package/themes/neutral.json +78 -78
- package/themes/pirate.json +79 -79
- package/themes/sports.json +79 -79
- package/themes/verstappen.json +78 -78
- package/themes/wizard.json +79 -79
- package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
- package/web/dist/assets/Activity-CqJiquEq.js +1 -0
- package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
- package/web/dist/assets/{Bonsai-hiG_gGNU.js → Bonsai-Bfpb6W-1.js} +1 -1
- package/web/dist/assets/{CopyButton-DUIUfNp6.js → CopyButton-ByIntFtB.js} +1 -1
- package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
- package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
- package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
- package/web/dist/assets/{GreenhouseView-BKxy5apE.js → GreenhouseView-GpBsYn50.js} +1 -1
- package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
- package/web/dist/assets/{JournalView-ChFitHjo.js → JournalView-iLuLrOxE.js} +1 -1
- package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
- package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
- package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
- package/web/dist/assets/Library-B4K-1iNF.js +3 -0
- package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
- package/web/dist/assets/{OperatorHudView-BO0aIKPL.js → OperatorHudView-BAXwCEvY.js} +1 -1
- package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
- package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
- package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
- package/web/dist/assets/index-CsAZq0BQ.css +1 -0
- package/web/dist/assets/index-How7SzDZ.js +6 -0
- package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
- package/web/dist/assets/Activity-CpkBwpu7.js +0 -1
- package/web/dist/assets/ActivityDetail-DTPziZWM.js +0 -1
- package/web/dist/assets/Dashboard-Dnw6EyX7.js +0 -2
- package/web/dist/assets/Docs-BEET_l16.js +0 -5
- package/web/dist/assets/Factories-D6KXkfWw.js +0 -1
- package/web/dist/assets/Installs-CnFVlVD0.js +0 -3
- package/web/dist/assets/Kits-CcR-OlwQ.js +0 -1
- package/web/dist/assets/Laws-B1s5idOg.js +0 -4
- package/web/dist/assets/LibRows-BZgdbI1l.js +0 -1
- package/web/dist/assets/Library-x6TkkEVF.js +0 -3
- package/web/dist/assets/Loops-BH93KKxn.js +0 -2
- package/web/dist/assets/Personal-CE_0Vhh0.js +0 -2
- package/web/dist/assets/Settings-CbpZvVN_.js +0 -1
- package/web/dist/assets/Tabs-C2oW7oEj.js +0 -1
- package/web/dist/assets/index-BQwOmbor.js +0 -6
- package/web/dist/assets/index-CuIop_pO.css +0 -1
- package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
package/bin/geneseed-cli.mjs
CHANGED
|
@@ -55,7 +55,8 @@
|
|
|
55
55
|
// whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
|
|
56
56
|
// FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
|
|
57
57
|
import '../js/lib/node-floor.mjs';
|
|
58
|
-
import {
|
|
58
|
+
import { readFileSync } from 'node:fs';
|
|
59
|
+
import { cliCommand, cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
|
|
59
60
|
import { parseIntStrict } from '../js/lib/text.mjs';
|
|
60
61
|
import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
61
62
|
|
|
@@ -73,8 +74,8 @@ import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
|
73
74
|
*
|
|
74
75
|
* IT IS STILL A TABLE and still the DISPATCH rather than a declaration beside one.
|
|
75
76
|
* `tests/unit/hook_cli.test.mjs` scrapes `const VERBS = {` for its matrix gates, and
|
|
76
|
-
* `main`'s refusal
|
|
77
|
-
*
|
|
77
|
+
* `main`'s unknown-verb refusal draws its nearest-match suggestion from `Object.keys(VERBS)`
|
|
78
|
+
* (it no longer prints the list) — the order is the old table's and is not alphabetical.
|
|
78
79
|
*
|
|
79
80
|
* FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
|
|
80
81
|
* is now a thunk that imports the command's module and resolves to its function, so the one
|
|
@@ -115,13 +116,9 @@ const VERBS = {
|
|
|
115
116
|
// argues both.
|
|
116
117
|
menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
|
|
117
118
|
home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
|
|
118
|
-
//
|
|
119
|
-
//
|
|
120
|
-
//
|
|
121
|
-
// `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
|
|
122
|
-
// panel-unavailable line rather than inventing a second full-screen UI, and
|
|
123
|
-
// `tests/unit/no_panel.test.mjs` asserts that no panel lies behind it — the module paints
|
|
124
|
-
// nothing and refuses on a TTY too — rather than leaving that merely untested.
|
|
119
|
+
// RETIRED: there was never a panel behind it, so it refused on every terminal. Kept one
|
|
120
|
+
// release as an alias that prints one line pointing at `menu` and exits 0, as `menu` does off
|
|
121
|
+
// a terminal; `tests/unit/no_panel.test.mjs` asserts the module still paints nothing.
|
|
125
122
|
tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
|
|
126
123
|
// THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
|
|
127
124
|
// than by alphabet: every row above is the twin of a subparser, and these three are not.
|
|
@@ -146,12 +143,43 @@ const VERBS = {
|
|
|
146
143
|
// The factory engine, the loop engine one level up: native like `loop`, gated absolutely by
|
|
147
144
|
// tests/unit/factory_cli.test.mjs.
|
|
148
145
|
factory: () => import('../js/factory/cli.mjs').then((m) => m.cmdFactory),
|
|
146
|
+
// Native too: a render for a library that is not an install. Its absolute gate is
|
|
147
|
+
// tests/unit/export.test.mjs.
|
|
148
|
+
export: () => import('../js/build/export.mjs').then((m) => m.cmdExport),
|
|
149
149
|
// A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
|
|
150
150
|
// (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
|
|
151
151
|
// tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
|
|
152
152
|
scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
|
|
153
153
|
};
|
|
154
154
|
|
|
155
|
+
/** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
|
|
156
|
+
function editDistance(a, b) {
|
|
157
|
+
let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
|
|
158
|
+
for (let i = 1; i <= a.length; i += 1) {
|
|
159
|
+
const cur = [i];
|
|
160
|
+
for (let j = 1; j <= b.length; j += 1) {
|
|
161
|
+
cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
162
|
+
}
|
|
163
|
+
prev = cur;
|
|
164
|
+
}
|
|
165
|
+
return prev[b.length];
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The closest verb to a mistyped one, or null when nothing is close. Close is at most a third
|
|
170
|
+
* of the typed word's length (and at least 1), so `stauts` finds `status` and `frobnicate`
|
|
171
|
+
* finds nothing: a suggestion for every typo is noise, not help.
|
|
172
|
+
*/
|
|
173
|
+
function nearestVerb(typed, verbs) {
|
|
174
|
+
let best = null;
|
|
175
|
+
let bestD = Math.max(1, Math.floor(typed.length / 3)) + 1;
|
|
176
|
+
for (const v of verbs) {
|
|
177
|
+
const d = editDistance(typed, v);
|
|
178
|
+
if (d < bestD) { best = v; bestD = d; }
|
|
179
|
+
}
|
|
180
|
+
return best;
|
|
181
|
+
}
|
|
182
|
+
|
|
155
183
|
function die(code, msg) {
|
|
156
184
|
// CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse writes
|
|
157
185
|
// this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
|
|
@@ -290,11 +318,24 @@ async function main(argv) {
|
|
|
290
318
|
// Bare = `home`, as both launchers (`geneseed`, `geneseed.cmd`) already did — but the npm
|
|
291
319
|
// `bin` names THIS file, so a bare `geneseed` off PATH used to die asking for a verb.
|
|
292
320
|
if (!argv.length) argv = ['home'];
|
|
321
|
+
// The package version, which `geneseed version` does NOT print: that verb compares the
|
|
322
|
+
// install's build fingerprint with this source's. Read off the package.json beside this file,
|
|
323
|
+
// so it is the version npm installed, and answered before the shim check.
|
|
324
|
+
if (argv[0] === '--version' || argv[0] === '-V') {
|
|
325
|
+
const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
326
|
+
printOut(`geneseed ${pkg.version}\n`);
|
|
327
|
+
return 0;
|
|
328
|
+
}
|
|
329
|
+
// `help` and `help <verb>` are spellings of `--help` and `<verb> --help`, and nothing more:
|
|
330
|
+
// a rewrite here rather than a VERBS row, because a row would owe the table a subcommand.
|
|
331
|
+
// `help help` is the listing too: `help` is not a VERBS row, so it has no help of its own.
|
|
332
|
+
if (argv[0] === 'help') argv = argv.length > 1 && argv[1] !== 'help' ? [argv[1], '--help'] : ['--help'];
|
|
293
333
|
const verb = argv[0];
|
|
294
334
|
if (verb === '-h' || verb === '--help') {
|
|
295
|
-
return printVerbList('geneseed', [...Object.keys(VERBS), 'validate'], {
|
|
335
|
+
return printVerbList('geneseed', [...Object.keys(VERBS), 'validate', 'help'], {
|
|
296
336
|
update: 'an alias of upgrade',
|
|
297
337
|
validate: "check the source tree without emitting (the generator's --validate-only)",
|
|
338
|
+
help: "this list; help <command> prints that command's help",
|
|
298
339
|
});
|
|
299
340
|
}
|
|
300
341
|
// A DEAD HOOK SHIM, SAID ON EVERY RUN. The shim is machine-wide, so one stale write turns off
|
|
@@ -320,12 +361,12 @@ async function main(argv) {
|
|
|
320
361
|
if (verb === 'validate') {
|
|
321
362
|
// Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
|
|
322
363
|
// generator driver in, and every OTHER verb was paying for it.
|
|
323
|
-
const [{ cmdValidate,
|
|
364
|
+
const [{ cmdValidate, validateUsage }, { parseDriverArgs }] = await Promise.all([
|
|
324
365
|
import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
|
|
325
366
|
]);
|
|
326
367
|
// Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
|
|
327
368
|
if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
|
|
328
|
-
printOut(
|
|
369
|
+
printOut(validateUsage());
|
|
329
370
|
return 0;
|
|
330
371
|
}
|
|
331
372
|
try {
|
|
@@ -342,9 +383,16 @@ async function main(argv) {
|
|
|
342
383
|
// named, the two entry points now cover every subcommand there is, so the clause was not
|
|
343
384
|
// just about to become false — it was already claiming a third place for verbs that do
|
|
344
385
|
// not exist.
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
386
|
+
//
|
|
387
|
+
// A hook verb (`context`, `tool-gate`, …) is in the table but not here: the emitted
|
|
388
|
+
// settings call it through `geneseed-hook`, and saying so beats "unknown command".
|
|
389
|
+
if (cliCommand(verb) !== null) {
|
|
390
|
+
return die(2, `'${verb}' is a hook verb: the host runs it through geneseed-hook `
|
|
391
|
+
+ '(bin/geneseed-hook.mjs), not this command. See geneseed --help.');
|
|
392
|
+
}
|
|
393
|
+
const near = nearestVerb(verb, [...Object.keys(VERBS), 'validate', 'help']);
|
|
394
|
+
return die(2, `unknown command '${verb}'.${near ? ` Did you mean '${near}'?` : ''} `
|
|
395
|
+
+ 'See geneseed --help.');
|
|
348
396
|
}
|
|
349
397
|
// `js/cli-table.json`, the CLI as data. A verb this table dispatches and the file does not
|
|
350
398
|
// describe is a REFUSAL and not a parse with no rules: an empty spec would accept every
|
package/bin/geneseed-hook.mjs
CHANGED
|
@@ -50,10 +50,10 @@
|
|
|
50
50
|
import '../js/lib/node-floor.mjs';
|
|
51
51
|
// Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
|
|
52
52
|
// edge only loads early a file the process would load anyway.
|
|
53
|
-
import { printErr } from '../js/lib/fs.mjs';
|
|
53
|
+
import { printErr, printOut } from '../js/lib/fs.mjs';
|
|
54
54
|
// Also not a new module: every verb's module imports it. It carries the activity switch, so the
|
|
55
55
|
// off path costs one file read and no import of the writer.
|
|
56
|
-
import { activityOn, readStdin } from '../js/hosts/hooks-prims.mjs';
|
|
56
|
+
import { activityOn, askDecision, gateSafe, readStdin } from '../js/hosts/hooks-prims.mjs';
|
|
57
57
|
import { isatty } from 'node:tty';
|
|
58
58
|
import path from 'node:path';
|
|
59
59
|
|
|
@@ -163,6 +163,35 @@ async function trackActivity(verb, args) {
|
|
|
163
163
|
} catch { /* the activity view is best-effort; a hook that fails is a tool call that fails */ }
|
|
164
164
|
}
|
|
165
165
|
|
|
166
|
+
/**
|
|
167
|
+
* A verb whose module failed to load, or threw past its own guard. `guardGate` only covers a gate
|
|
168
|
+
* once its module has loaded; a module that cannot (a file missing mid-`git pull` under the shared
|
|
169
|
+
* shim, a syntax error) used to exit 1 with nothing on stdout, which Claude reads as "the gate
|
|
170
|
+
* deferred". So a gate verb gives the gate-error verdict `guardGate` gives — an ask on Claude and
|
|
171
|
+
* OpenClaude, a stderr warning on Bob, where gate-error is never a block — built from
|
|
172
|
+
* `./hooks-prims.mjs`, which the entry has already loaded. Not ledgered: the ledger's writer is
|
|
173
|
+
* in the module that failed. Every other verb exits 0 with stdout empty and one stderr line, so a
|
|
174
|
+
* broken context hook shows in the host's hook log: stdout is the only channel any host reads as
|
|
175
|
+
* a decision, and on Bob too a stderr line with exit 0 is a log entry (the gates' Bob warnings
|
|
176
|
+
* already are). The residual limit: a
|
|
177
|
+
* module this file imports statically (`fs.mjs`, `hooks-prims.mjs`) fails at link time, before
|
|
178
|
+
* any of this runs.
|
|
179
|
+
*/
|
|
180
|
+
function verbFailed(verb, args, e) {
|
|
181
|
+
let name = e;
|
|
182
|
+
try { name = e.message || e; } catch { /* `gateSafe` meets `e` as it is */ }
|
|
183
|
+
if (!GATE_VERBS.has(verb)) {
|
|
184
|
+
try { printErr(`[geneseed-hook] ${verb} failed: ${name}\n`); } catch { /* an unprintable error says nothing */ }
|
|
185
|
+
return 0;
|
|
186
|
+
}
|
|
187
|
+
if (args.host === 'bob') {
|
|
188
|
+
printErr(`[geneseed] ${gateSafe('gate-error', 'warned', { name })}\n`);
|
|
189
|
+
return 0;
|
|
190
|
+
}
|
|
191
|
+
printOut(askDecision(gateSafe('gate-error', 'ask', { name })));
|
|
192
|
+
return 0;
|
|
193
|
+
}
|
|
194
|
+
|
|
166
195
|
function die(code, msg) {
|
|
167
196
|
// CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
|
|
168
197
|
// writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
|
|
@@ -270,7 +299,12 @@ async function main(argv) {
|
|
|
270
299
|
if (verb === 'context' && !isatty(0)) {
|
|
271
300
|
try { parsed.args.event = JSON.parse(readStdin() || '{}').hook_event_name ?? null; } catch { /* not JSON: SessionStart */ }
|
|
272
301
|
}
|
|
273
|
-
|
|
302
|
+
let rc;
|
|
303
|
+
try {
|
|
304
|
+
rc = (await spec.load())[spec.fn](parsed.args);
|
|
305
|
+
} catch (e) {
|
|
306
|
+
return verbFailed(verb, parsed.args, e);
|
|
307
|
+
}
|
|
274
308
|
await trackActivity(verb, parsed.args);
|
|
275
309
|
await baselineStores(verb, parsed.args);
|
|
276
310
|
return rc;
|
|
@@ -95,7 +95,7 @@ What stops asking, per host: the real-loss check of `git-gate` (Claude Code, Ope
|
|
|
95
95
|
Limits:
|
|
96
96
|
- **OpenCode reads the switch at start.** The guard plugin reads `Deletion gate:` from the install's `AGENT.md` once, when OpenCode loads it: restart OpenCode after flipping it.
|
|
97
97
|
- **A global install beside a project install.** On Claude Code and OpenClaude the global `git-gate` stands down for a project install, so the project's switch decides. Bob's `tool-gate` and the OpenCode guard do not stand down: an armed global install still refuses real loss inside a project whose own install is off.
|
|
98
|
-
- **An
|
|
98
|
+
- **An older `opencode.json` keeps its Law IV keys.** Switching off removes the `permission.bash` entries the manifest records Geneseed adding (`bash_gates`, since 5.2.0). An install made before that has no record, so the build warns that it keeps them and they keep asking. Run the build once with `--prune-gates` to remove those still set as Geneseed writes them, or delete them by hand. An entry you changed always stays, and a commented `opencode.jsonc` is never rewritten: the build names the entries to remove.
|
|
99
99
|
- **An older hook shim silences the whole gate.** The flag is new. While the machine's shared hook shim still points at an older checkout, that checkout refuses the flag and the gate verb lets every call through on a disarmed install — on Claude Code and OpenClaude the root-scan and consent checks too, on Bob also *Sealed Secrets* and *External Gate*. Update the checkout the shim points at (`geneseed rebuild-all`) before switching the gate off.
|
|
100
100
|
|
|
101
101
|
### Law I secrets gate and Law III done gate — on or off
|
|
@@ -44,7 +44,7 @@ but its first stage, or a route back that spends no cycle.
|
|
|
44
44
|
## Forks and lanes
|
|
45
45
|
|
|
46
46
|
A **fork** is where the work takes one way or another. It is a brick that declares **named
|
|
47
|
-
outcomes**, any outcome other than `pass`, `fail`, `error`, `none` or `
|
|
47
|
+
outcomes**, any outcome other than `pass`, `fail`, `error`, `none`, `needs-info` or `reject`. `triage` is one: `bug`,
|
|
48
48
|
`feature`, `deps`, `refactor`, `docs` and `fail`. Each named outcome has its own edge to its own
|
|
49
49
|
stage, its **lane**, and the outcome the brick reports picks the lane. `geneseed factory next`
|
|
50
50
|
hands the fork its `lanes`: each outcome with the stage it leads to.
|
|
@@ -76,6 +76,37 @@ exception is the run's spec, `specs/<slug>/spec.md`: the `spec` stage writes it,
|
|
|
76
76
|
it is committed once you approve it, before the first loop. Each run is listed in `factories.json` beside the loop registry, and each child loop's row
|
|
77
77
|
names the run it belongs to.
|
|
78
78
|
|
|
79
|
+
## The queue, and a refused item
|
|
80
|
+
|
|
81
|
+
A run takes one work item. To pick from several, ask the agent for the **queue**: it lists the
|
|
82
|
+
open issues that carry the label `factory` (or a label you name), and you pick one, several or
|
|
83
|
+
all. Several picks run one after the other, in the order you gave, each as its own run in its
|
|
84
|
+
own worktree, each with its own merge question. A run that holds a gate holds the queue. An
|
|
85
|
+
issue's text is the run's input, never an instruction to the agent. No file configures the queue,
|
|
86
|
+
and nothing starts a run by itself.
|
|
87
|
+
|
|
88
|
+
`intake` may also **refuse** an item, with the outcome `reject`: it is already done, it duplicates
|
|
89
|
+
another issue or pull request, or it goes against a rule the project states. The run holds and
|
|
90
|
+
shows you the reason and its evidence. `ok` accepts the refusal and stops the run, `amend` runs
|
|
91
|
+
`intake` again with your reason to build it, and `no` stops too. In each shipped factory the
|
|
92
|
+
`reject` edge goes to `$stop`; a factory of your own that has no such edge stops the same way.
|
|
93
|
+
|
|
94
|
+
## What a run measures
|
|
95
|
+
|
|
96
|
+
Every `record` and `decide` writes the time on its history entry, and `init` writes when the run
|
|
97
|
+
started. From those, `geneseed factory report` gives each stage its runs, its reworks, its work
|
|
98
|
+
time and its tokens, and the run its work time and the time it waited for you at a gate. The time
|
|
99
|
+
between a held outcome and your answer is waiting time, never the stage's. A rework is an outcome
|
|
100
|
+
that spent a cycle: a failed `checks`, `review-panel` or `holdout`, or red CI.
|
|
101
|
+
|
|
102
|
+
Tokens are recorded only where the host reports a count for the agent that ran the stage
|
|
103
|
+
(`record --tokens <n>`); nothing estimates one, and a loop stage carries none. There is no cost in
|
|
104
|
+
money: Geneseed holds no price table. A number nobody recorded is `null` in the report, never 0,
|
|
105
|
+
so a `FACTORY.md` written before times were stamped still runs and reports `unknown`.
|
|
106
|
+
|
|
107
|
+
The `retro` stage copies those numbers into the run report, and adds, for each `review-panel`
|
|
108
|
+
seat, how many rounds it failed.
|
|
109
|
+
|
|
79
110
|
## The shipped factories
|
|
80
111
|
|
|
81
112
|
| Factory | Stages |
|
|
@@ -88,7 +119,7 @@ The bricks they add:
|
|
|
88
119
|
|
|
89
120
|
| Brick | Does | Outcomes |
|
|
90
121
|
| --- | --- | --- |
|
|
91
|
-
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions (`gate: human`) | `pass`, `fail`, `needs-info` |
|
|
122
|
+
| `intake` | Reads the request, the document or the issue (`gh issue view`, `glab issue view`) and writes one clear work item with testable criteria, its `size` and its `areas`. `needs-info` holds for your answers to its questions, and `reject` holds when it finds the item already done, a duplicate, or against a rule the project states, with the reason and its evidence (`gate: human`). It never posts on the issue | `pass`, `fail`, `needs-info`, `reject` |
|
|
92
123
|
| `holdout-write` | Writes 3 to 8 prose scenarios (given / when / then) for the work item into the holdout folder, outside the worktree, and hands the work item on unchanged | `pass`, `fail` |
|
|
93
124
|
| `holdout` | Plays every scenario against the built change. `fail` carries one sentence per failed scenario, observed against expected; `error` when the diff touches the holdout folder or a scenario cannot be played | `pass`, `fail`, `error` |
|
|
94
125
|
| `checks` | Runs the done list as the base branch holds it, never the branch's copy. `error` holds when the diff touches a locked path, or on an environment failure (a failed fetch, a timeout, a missing tool); `none` holds with a proposed list when the base has none | `pass`, `fail`, `error`, `none` |
|
|
@@ -96,7 +127,7 @@ The bricks they add:
|
|
|
96
127
|
| `triage` | A fork: reads the work item and reports the outcome that names its lane, with its reason. `fail` when no lane fits | `bug`, `feature`, `deps`, `refactor`, `docs`, `fail` |
|
|
97
128
|
| `pr-open` | Pushes the branch (the push asks you) and opens the PR, or updates the one already open | `pass`, `fail` |
|
|
98
129
|
| `merge-gate` | Waits for the PR's CI with a watch that returns by itself (each call under 10 minutes), 30 minutes at most. A repo with no CI reports `none`, and you decide; so does CI still pending at the bound, or a `gh`/`glab` that is missing or fails | `pass`, `fail`, `none` |
|
|
99
|
-
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, and keeps only a lasting lesson in memory | `pass` |
|
|
130
|
+
| `retro` | Writes the run report to `.geneseed/factory-runs/<slug>.md`, with the numbers of `geneseed factory report`, and keeps only a lasting lesson in memory | `pass` |
|
|
100
131
|
|
|
101
132
|
`analysis-to-build` also uses the loops' own `spec` brick (`gate: human`), the one the
|
|
102
133
|
`spec-first-feature` loop starts with, and `issue-to-pr` the loops' `docs-update` brick as its
|
|
@@ -179,9 +210,12 @@ graph: its stages top to bottom, a fork's lanes side by side, a `loop:` stage as
|
|
|
179
210
|
that names its loop over `whole loop`, each route back as a rail on the left with its cycle and
|
|
180
211
|
`max`, and `close` and `stop` as end caps.
|
|
181
212
|
Each factory shows how to start it: the request to give the agent, and the commands to start it
|
|
182
|
-
by hand, the worktree first and then `geneseed factory init`. Its **Active** tab
|
|
183
|
-
registered run,
|
|
184
|
-
|
|
213
|
+
by hand, the worktree first and then `geneseed factory init`. Its **Active** tab is a board of every
|
|
214
|
+
registered run, in three columns: **Waits for you**, **Running** and **Ended**. A card shows where
|
|
215
|
+
the run stands, its task, the laps spent on each cycle, and its work and waiting time. A card
|
|
216
|
+
opens the run: its graph with the current stage lit, the laps spent on each cycle, the child
|
|
217
|
+
loop's current step, written `at <node>` in the current stage's box, and a timeline of every
|
|
218
|
+
stage with its outcome, its time, its duration and each rework. The page changes nothing, neither a run nor `factories.json`: the next `geneseed factory init` on the machine drops a run whose worktree is gone, and a closed run 7 days after that init first saw it closed. You answer a run in the
|
|
185
219
|
agent's session.
|
|
186
220
|
|
|
187
221
|
## Your own factories
|
|
@@ -14,7 +14,7 @@ link: {"hash": "#/installs/hosts", "label": "Change it on Installs →"}
|
|
|
14
14
|
### The difference
|
|
15
15
|
|
|
16
16
|
- **Full** — the instructions file carries the Ethos, every Rule and every rule of the active doctrine packs at complete length, reasoning included, every turn.
|
|
17
|
-
- **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off).
|
|
17
|
+
- **Lean** — each Rule and each doctrine rule is carried as its heading plus a short form written by hand (the rule and how it works, not the first sentence cut off). One pointer after the doctrine packs names where the complete text of both layers is on disk, and the agent reads the reasoning when a rule's application is unclear. The Ethos gets one hand-written short form for the whole layer, because it is flowing prose rather than numbered rules. Lean also drops the voice's flourish: a heading names the rule by its plain principle (`Dictate I — Sealed Secrets`, not `Dictate I — Arcana Sigillata · Sealed Secrets`), and no section opens with an italic epigraph. Full keeps both, and so do the complete files on disk.
|
|
18
18
|
|
|
19
19
|
Neither setting hides text from the agent. They decide what is in front of it on *every* turn.
|
|
20
20
|
|
|
@@ -11,7 +11,7 @@ link: {"hash": "#/installs/hosts", "label": "Set the mode on Installs →"}
|
|
|
11
11
|
|
|
12
12
|
> **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
|
|
13
13
|
|
|
14
|
-
Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot
|
|
14
|
+
Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a task worker or a pipeline is a one-shot run for a single task, committed only on its own branch and merged by the session once you accept; a loop is a long-running state machine that commits each validated iteration on its own branch.
|
|
15
15
|
|
|
16
16
|
### direct — the default
|
|
17
17
|
|
|
@@ -70,7 +70,7 @@ Inside the crew, the developer implements and the tester runs the tests and lint
|
|
|
70
70
|
|
|
71
71
|
### Nothing lands beyond the worker's branch
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
A worker or crew commits only in its own worktree, never pushes, and never merges outside its own branch. When it is done, it hands back that branch: its local commits (its own, and its sub-workers' merges) and any uncommitted work. Each comes with the raw test and lint output and the list of files it changed. Then the session:
|
|
74
74
|
|
|
75
75
|
1. re-runs the tests and lint itself — its log is its own account, not proof;
|
|
76
76
|
2. shows you the diff from the base it recorded, and the green output;
|
|
@@ -38,6 +38,6 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
38
38
|
|
|
39
39
|
The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
|
|
40
40
|
|
|
41
|
-
One OpenCode asymmetry: Geneseed shares `opencode.json` with you
|
|
41
|
+
One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way, and uninstall takes those back too; uninstall leaves the `permission.bash` gates.
|
|
42
42
|
|
|
43
43
|
In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
|
|
@@ -15,7 +15,7 @@ committed or counted against a ring budget while it waits.
|
|
|
15
15
|
|
|
16
16
|
A [factory](factories.md) stage holds the same way, answered with `geneseed factory decide`.
|
|
17
17
|
Three shipped bricks do: `intake` (holds on `needs-info` — it has questions only you can
|
|
18
|
-
answer), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
|
|
18
|
+
answer — and on `reject` — it refuses the item as already done, a duplicate or against a rule), `checks` (holds on `error` — the branch changed a locked path — and on `none` — the
|
|
19
19
|
base branch has no done list yet) and `merge-gate` (holds on `none` — the repo runs no CI on the
|
|
20
20
|
PR).
|
|
21
21
|
|
package/docs/concepts/loops.md
CHANGED
|
@@ -83,7 +83,7 @@ evidence was never wired — no verdict is not a failure to repair.
|
|
|
83
83
|
## Not foreman mode
|
|
84
84
|
|
|
85
85
|
A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
|
|
86
|
-
they solve different problems. A pipeline is a one-shot crew for a single task
|
|
87
|
-
you accept it. A loop is a long-running, self-scoring state machine that commits each validated
|
|
86
|
+
they solve different problems. A pipeline is a one-shot crew for a single task; it commits only on its
|
|
87
|
+
own branch, and nothing lands beyond it until you accept it. A loop is a long-running, self-scoring state machine that commits each validated
|
|
88
88
|
iteration on its own branch as it goes, and only stops for a person when the risk crosses a
|
|
89
89
|
threshold.
|
|
@@ -36,7 +36,7 @@ The same folder already held the install registry, your own loop bricks and temp
|
|
|
36
36
|
| `PROFILE.md`, `geneseed-wiki.jsonc` | Whole file. A host file that is no longer its seed replaces the shared one. `$GENESEED_WIKI` overrides both |
|
|
37
37
|
| `excludes.json` | A global install reads the union of the shared list and its own |
|
|
38
38
|
|
|
39
|
-
When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
|
|
39
|
+
When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. In `user-rules.md`, the seed's explanation above the first `## R<n>` rule is skipped too while it is unchanged: only the rules are sent. Text you wrote above the rules, or an edited explanation, is sent as it is. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
|
|
40
40
|
|
|
41
41
|
A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules or draft passes the same [rule gate](hooks.md) as a local one; the shared memory, like a local one, is written freely.
|
|
42
42
|
|
package/docs/design-history.md
CHANGED
|
@@ -1347,3 +1347,143 @@ Geneseed did make are listed in [Why Geneseed works this way](understand/design-
|
|
|
1347
1347
|
anchor stays. A runtime toggle that works beside the anchor, without replacing it, remains
|
|
1348
1348
|
possible. See
|
|
1349
1349
|
[Foreman mode](concepts/foreman-mode.md).
|
|
1350
|
+
|
|
1351
|
+
---
|
|
1352
|
+
|
|
1353
|
+
## Extending guide — settled history (moved 2026-11-11)
|
|
1354
|
+
|
|
1355
|
+
[docs/extending.md](extending.md) carried these sections while they were live. Each one was
|
|
1356
|
+
settled, so they moved here as a record; the rules that still hold stayed in the guide. Section
|
|
1357
|
+
numbers below are the guide's numbers at the time, and "today" means the date in each heading.
|
|
1358
|
+
|
|
1359
|
+
### 5.1 ✅ A fifth hook verb — resolved 2026-08-19
|
|
1360
|
+
|
|
1361
|
+
**This was a hard blocker and it is now open.** Recorded here because the shape of the problem
|
|
1362
|
+
recurs: any gate whose expected value lives in an artifact nothing can re-make will eventually
|
|
1363
|
+
stop a legitimate change, and the fix is never to delete the artifact.
|
|
1364
|
+
|
|
1365
|
+
`tests/unit/hook_cli.test.mjs` asserted a strict equality between the hook verbs the frozen
|
|
1366
|
+
matrix covers and the verbs `bin/geneseed-hook.mjs` carries. The CLI half of the same test
|
|
1367
|
+
already exempted a named `NATIVE` list; the hook half exempted nothing — so a fifth hook verb
|
|
1368
|
+
failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
|
|
1369
|
+
correctly forbids deleting cells to pass.
|
|
1370
|
+
|
|
1371
|
+
`NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
|
|
1372
|
+
than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
|
|
1373
|
+
carries — so a name that stops meaning anything fails rather than sitting there.
|
|
1374
|
+
|
|
1375
|
+
**To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
|
|
1376
|
+
`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
|
|
1377
|
+
absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
|
|
1378
|
+
to stay in step; there is one copy now, so there is nothing to keep in step.
|
|
1379
|
+
|
|
1380
|
+
### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
|
|
1381
|
+
|
|
1382
|
+
Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
|
|
1383
|
+
be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
|
|
1384
|
+
red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
|
|
1385
|
+
cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
|
|
1386
|
+
|
|
1387
|
+
Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
|
|
1388
|
+
detection and nothing checks it.
|
|
1389
|
+
|
|
1390
|
+
### 5.4 ✅ Expected values are written out — resolved 2026-08-23
|
|
1391
|
+
|
|
1392
|
+
This section used to say that a snapshot red was a finding rather than a step: the recordings under
|
|
1393
|
+
`tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
|
|
1394
|
+
and a change that moved a recorded byte left only two honest options — revert it, or argue in
|
|
1395
|
+
writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
|
|
1396
|
+
blocks a change, move the logic to the nearest caller that is not frozen*.
|
|
1397
|
+
|
|
1398
|
+
**None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
|
|
1399
|
+
only way back to them), and every expected value now lives in the test file that asserts it, above
|
|
1400
|
+
a sentence saying which decision it pins. The rule is correspondingly ordinary:
|
|
1401
|
+
|
|
1402
|
+
> **Change the expectation and the sentence that explains it in the same commit, and say why in
|
|
1403
|
+
> the message.**
|
|
1404
|
+
|
|
1405
|
+
A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
|
|
1406
|
+
the cost that keeps the tables honest, and far cheaper than the one it replaced.
|
|
1407
|
+
|
|
1408
|
+
The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
|
|
1409
|
+
text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
|
|
1410
|
+
`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
|
|
1411
|
+
holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
|
|
1412
|
+
29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
|
|
1413
|
+
`tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
|
|
1414
|
+
`README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
|
|
1415
|
+
|
|
1416
|
+
### 7 — Stale on 2026-08-18, fixed on 2026-08-19
|
|
1417
|
+
|
|
1418
|
+
Nine items were found while writing this file, and fixed the next day. They are recorded as a
|
|
1419
|
+
list rather than left as a diff, because the PATTERN is the useful part: every one was a document
|
|
1420
|
+
or a comment pointing a reader at something that is not there, and in each case the gate that
|
|
1421
|
+
should have caught it either did not cover that file — or was itself the frozen copy of a wrong
|
|
1422
|
+
answer.
|
|
1423
|
+
|
|
1424
|
+
**Fixed.**
|
|
1425
|
+
|
|
1426
|
+
1. **`DESIGN.md` taught the deleted Python build.** Its header promises *"the spec behind the
|
|
1427
|
+
harness — read this before changing structure"*, and under it sat the six-edit checklist for
|
|
1428
|
+
adding a Law, naming a deleted generator, `rituals/_harness_tui.py` for `LAW_CLASS`, and an
|
|
1429
|
+
invocation of a program that no longer exists. Worse, `tests/unit/no_python.test.mjs` exempted
|
|
1430
|
+
the file as a *historical record* — so the gate that hunts pointers-to-nothing was looking away
|
|
1431
|
+
from the one document most likely to hold one. **Split**: the 190-line standing contract keeps
|
|
1432
|
+
the name and is now scanned; the 1,290-line port narrative moved to
|
|
1433
|
+
the port narrative above, which is exempt on the merits, and its dead links were
|
|
1434
|
+
repaired because a link is a pointer whatever the prose around it says.
|
|
1435
|
+
2. **`doctor` printed a command that errors.** The theme-parity tip named
|
|
1436
|
+
`./geneseed build --sync-themes`; `cmdBuild` forwards `--theme` and nothing else. The comment
|
|
1437
|
+
above the tip argued that spelling on a premise the port had quietly stopped satisfying. It now
|
|
1438
|
+
names `geneseed-build --sync-themes`, which is what README and SETUP said all along.
|
|
1439
|
+
3. **User-facing output named a program that does not exist.** `tui` and `uninstall` told users to
|
|
1440
|
+
run `harness setup` / `harness uninstall` — the reference's name, dropped in P0. Five sites.
|
|
1441
|
+
One of them was **pinned verbatim by a test**, so a gate was holding the wrong string in place;
|
|
1442
|
+
that assertion is now a property — every backticked command a refusal offers must be a verb
|
|
1443
|
+
`js/cli-table.json` declares — which is strictly stronger and fires on the next rename too.
|
|
1444
|
+
4. **The `tui` help promised a "full-screen curses control panel"** for a verb that returns 1 on
|
|
1445
|
+
every path. `docs/limits.md` listed this as permanently unfixable, on the grounds that the help
|
|
1446
|
+
corpus is frozen — but `formatHelp` never reads `cmd.help`, so it was an ordinary edit all
|
|
1447
|
+
along. The limits row went with the fix.
|
|
1448
|
+
5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
|
|
1449
|
+
tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
|
|
1450
|
+
named as `cli`, which was removed).
|
|
1451
|
+
6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
|
|
1452
|
+
`choices` before anything renders, which is why its own refusal read as an unreachable nicety.
|
|
1453
|
+
It is not in `choicesFor`; that refusal is the only one there is, on every path.
|
|
1454
|
+
7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
|
|
1455
|
+
the corpora — three test files justified their own design by pointing at a gate that is gone.
|
|
1456
|
+
Plus a skip message naming a `record-corpus` CI job that no longer exists.
|
|
1457
|
+
8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
|
|
1458
|
+
URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
|
|
1459
|
+
`geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
|
|
1460
|
+
9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
|
|
1461
|
+
the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
|
|
1462
|
+
a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
|
|
1463
|
+
there is one file.
|
|
1464
|
+
|
|
1465
|
+
### 10 — What to settle before the next wave
|
|
1466
|
+
|
|
1467
|
+
Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
|
|
1468
|
+
stop a change today, and all of them cost a contributor a wrong turn until they are done.
|
|
1469
|
+
|
|
1470
|
+
1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
|
|
1471
|
+
Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
|
|
1472
|
+
`DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
|
|
1473
|
+
reach. It keeps catching them.
|
|
1474
|
+
2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
|
|
1475
|
+
CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
|
|
1476
|
+
Either answer is fine; discovering the question mid-feature is not.
|
|
1477
|
+
3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
|
|
1478
|
+
is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
|
|
1479
|
+
and today nothing warns you before the snapshot goes red.
|
|
1480
|
+
4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
|
|
1481
|
+
`adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
|
|
1482
|
+
5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
|
|
1483
|
+
config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
|
|
1484
|
+
chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
|
|
1485
|
+
|
|
1486
|
+
The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
|
|
1487
|
+
deliberately keeps tables and prose hand-written and gates them from the source tree. The
|
|
1488
|
+
recommendations above are about the places where the gate is missing, wrong, or pointed at a file
|
|
1489
|
+
that no longer exists.
|