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.
Files changed (163) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +1 -1
  4. package/adapters/opencode/README.md +4 -3
  5. package/adapters/opencode/plugins/geneseed-context.js +82 -29
  6. package/adapters/opencode/plugins/geneseed-guard.js +118 -8
  7. package/bin/geneseed-cli.mjs +64 -16
  8. package/bin/geneseed-hook.mjs +37 -3
  9. package/docs/concepts/exclusions.md +1 -1
  10. package/docs/concepts/factories.md +40 -6
  11. package/docs/concepts/footprint.md +1 -1
  12. package/docs/concepts/foreman-mode.md +2 -2
  13. package/docs/concepts/host-matrix.md +1 -1
  14. package/docs/concepts/loop-gates.md +1 -1
  15. package/docs/concepts/loops.md +2 -2
  16. package/docs/concepts/shared-tier.md +1 -1
  17. package/docs/design-history.md +140 -0
  18. package/docs/extending.md +54 -162
  19. package/docs/guides/run-a-factory.md +15 -2
  20. package/docs/guides/setup-doctrines.md +1 -1
  21. package/docs/guides/upgrade.md +2 -2
  22. package/docs/reference/factory-actions.md +6 -5
  23. package/docs/reference/troubleshoot-update.md +1 -1
  24. package/docs/understand/enforced-vs-asked.md +1 -1
  25. package/docs/web-ui.md +16 -3
  26. package/harness.config.json +1 -1
  27. package/js/README.md +10 -7
  28. package/js/build/args.mjs +10 -4
  29. package/js/build/bundle.mjs +122 -23
  30. package/js/build/driver.mjs +32 -12
  31. package/js/build/emit-claude.mjs +2 -1
  32. package/js/build/emit-common.mjs +2 -2
  33. package/js/build/emit-opencode.mjs +22 -10
  34. package/js/build/export.mjs +431 -0
  35. package/js/build/generate.mjs +3 -0
  36. package/js/build/render.mjs +44 -24
  37. package/js/build/source.mjs +6 -1
  38. package/js/cli-table.json +232 -57
  39. package/js/factory/cli.mjs +24 -5
  40. package/js/factory/graph.mjs +13 -9
  41. package/js/factory/metrics.mjs +93 -0
  42. package/js/factory/registry.mjs +37 -12
  43. package/js/factory/state.mjs +25 -6
  44. package/js/hosts/hooks-context.mjs +26 -1
  45. package/js/hosts/hooks-done.mjs +8 -2
  46. package/js/hosts/hooks-prims.mjs +52 -3
  47. package/js/hosts/hooks.mjs +155 -33
  48. package/js/hosts/hosts.mjs +2 -4
  49. package/js/hosts/installs.mjs +28 -0
  50. package/js/hosts/loss.mjs +25 -3
  51. package/js/hosts/native.mjs +30 -2
  52. package/js/hosts/owned.mjs +55 -1
  53. package/js/hosts/ownership-gate.mjs +5 -5
  54. package/js/hosts/settings.mjs +83 -33
  55. package/js/inspect/diff.mjs +16 -1
  56. package/js/inspect/doctor.mjs +7 -3
  57. package/js/inspect/excludes.mjs +18 -6
  58. package/js/inspect/status.mjs +35 -7
  59. package/js/inspect/validate.mjs +44 -21
  60. package/js/lib/managed-block.mjs +74 -0
  61. package/js/maintain/uninstall.mjs +85 -15
  62. package/js/maintain/update.mjs +31 -7
  63. package/js/ui/cli.mjs +34 -4
  64. package/js/ui/menu.mjs +1 -1
  65. package/js/ui/tui.mjs +11 -14
  66. package/js/web/actions.mjs +5 -0
  67. package/js/web/api.mjs +32 -11
  68. package/js/web/daemon.mjs +0 -1
  69. package/js/web/server.mjs +1 -0
  70. package/js/web/state.mjs +37 -16
  71. package/package.json +1 -1
  72. package/src/AGENT.md.tmpl +23 -17
  73. package/src/agents/_template.md +1 -1
  74. package/src/agents/advocate.md +1 -1
  75. package/src/agents/developer.md +12 -3
  76. package/src/agents/empiricist.md +1 -1
  77. package/src/agents/framer.md +1 -1
  78. package/src/agents/historian.md +1 -1
  79. package/src/agents/operator.md +1 -1
  80. package/src/agents/pragmatist.md +1 -1
  81. package/src/agents/researcher.md +1 -1
  82. package/src/agents/skeptic.md +1 -1
  83. package/src/agents/steward.md +1 -1
  84. package/src/agents/user-advocate.md +1 -1
  85. package/src/agents/visionary.md +1 -1
  86. package/src/bricks/intake.md +10 -3
  87. package/src/bricks/retro.md +13 -3
  88. package/src/doctrines/comms.md +1 -1
  89. package/src/doctrines/ops.md +1 -1
  90. package/src/doctrines/process.md +7 -5
  91. package/src/factories/analysis-to-build.json +1 -0
  92. package/src/factories/bug-report-to-fix.json +1 -0
  93. package/src/factories/issue-to-pr.json +1 -0
  94. package/src/laws/universal.md +2 -2
  95. package/src/modes/foreman.md +8 -14
  96. package/src/skills/commit.md +7 -2
  97. package/src/skills/debug.md +1 -1
  98. package/src/skills/diagram-design/SKILL.md +1 -1
  99. package/src/skills/diagram-design/VENDOR.md +3 -1
  100. package/src/skills/factory-forge.md +5 -3
  101. package/src/skills/factory.md +22 -1
  102. package/src/skills/geneseed.md +1 -1
  103. package/src/skills/handoff.md +1 -1
  104. package/src/skills/parallel-agents.md +1 -1
  105. package/src/skills/pipeline.md +6 -6
  106. package/src/skills/plan.md +7 -3
  107. package/src/skills/spring-testing.md +1 -1
  108. package/themes/biker.json +78 -78
  109. package/themes/commentator.json +81 -81
  110. package/themes/cyberpunk.json +79 -79
  111. package/themes/gamer.json +77 -77
  112. package/themes/imperial.json +82 -82
  113. package/themes/joker.json +79 -79
  114. package/themes/marvin.json +82 -82
  115. package/themes/mean.json +82 -82
  116. package/themes/military.json +78 -78
  117. package/themes/neutral.json +78 -78
  118. package/themes/pirate.json +79 -79
  119. package/themes/sports.json +79 -79
  120. package/themes/verstappen.json +78 -78
  121. package/themes/wizard.json +79 -79
  122. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  123. package/web/dist/assets/Activity-CqJiquEq.js +1 -0
  124. package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
  125. package/web/dist/assets/{Bonsai-hiG_gGNU.js → Bonsai-Bfpb6W-1.js} +1 -1
  126. package/web/dist/assets/{CopyButton-DUIUfNp6.js → CopyButton-ByIntFtB.js} +1 -1
  127. package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
  128. package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
  129. package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
  130. package/web/dist/assets/{GreenhouseView-BKxy5apE.js → GreenhouseView-GpBsYn50.js} +1 -1
  131. package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
  132. package/web/dist/assets/{JournalView-ChFitHjo.js → JournalView-iLuLrOxE.js} +1 -1
  133. package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
  134. package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
  135. package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
  136. package/web/dist/assets/Library-B4K-1iNF.js +3 -0
  137. package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
  138. package/web/dist/assets/{OperatorHudView-BO0aIKPL.js → OperatorHudView-BAXwCEvY.js} +1 -1
  139. package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
  140. package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
  141. package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
  142. package/web/dist/assets/index-CsAZq0BQ.css +1 -0
  143. package/web/dist/assets/index-How7SzDZ.js +6 -0
  144. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  145. package/web/dist/index.html +2 -2
  146. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  147. package/web/dist/assets/Activity-CpkBwpu7.js +0 -1
  148. package/web/dist/assets/ActivityDetail-DTPziZWM.js +0 -1
  149. package/web/dist/assets/Dashboard-Dnw6EyX7.js +0 -2
  150. package/web/dist/assets/Docs-BEET_l16.js +0 -5
  151. package/web/dist/assets/Factories-D6KXkfWw.js +0 -1
  152. package/web/dist/assets/Installs-CnFVlVD0.js +0 -3
  153. package/web/dist/assets/Kits-CcR-OlwQ.js +0 -1
  154. package/web/dist/assets/Laws-B1s5idOg.js +0 -4
  155. package/web/dist/assets/LibRows-BZgdbI1l.js +0 -1
  156. package/web/dist/assets/Library-x6TkkEVF.js +0 -3
  157. package/web/dist/assets/Loops-BH93KKxn.js +0 -2
  158. package/web/dist/assets/Personal-CE_0Vhh0.js +0 -2
  159. package/web/dist/assets/Settings-CbpZvVN_.js +0 -1
  160. package/web/dist/assets/Tabs-C2oW7oEj.js +0 -1
  161. package/web/dist/assets/index-BQwOmbor.js +0 -6
  162. package/web/dist/assets/index-CuIop_pO.css +0 -1
  163. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
@@ -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 { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
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 lists `Object.keys(VERBS)` IN THIS ORDER (no cell asserts the list
77
- * verbatim any more) — the order is the old table's and is not alphabetical.
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
- // P7b, and it is the twenty-fifth and last. `cmd_tui`'s FIRST arm is `if not sys.stdin.
119
- // isatty()`, so off a TTY — which is every cell there is — the verb is one line and an
120
- // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
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, VALIDATE_USAGE }, { parseDriverArgs }] = await Promise.all([
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(VALIDATE_USAGE);
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
- return die(2, `invalid choice: '${verb}'. This entry point carries only `
346
- + `${Object.keys(VERBS).join(', ')}; the six hook verbs live in `
347
- + 'bin/geneseed-hook.mjs.');
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
@@ -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
- const rc = (await spec.load())[spec.fn](parsed.args);
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 existing `opencode.json` keeps its Law IV keys.** Switching off does not remove `permission.bash` entries already written — Geneseed cannot tell its own from yours — so the build warns that it keeps them and they keep asking. Delete them by hand.
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 `needs-info`. `triage` is one: `bug`,
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 lists every
183
- registered run, with the current stage lit, the laps spent on each cycle and the child loop's
184
- current step, written `at <node>` in the current stage's box. The page changes nothing in a run (its poll only drops finished runs older than 7 days from `factories.json`, as Loops does); you answer a run in the
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). Each layer ends with a pointer to its complete text 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.
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, uncommitted run for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
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
- When a crew is done, it hands back its worktree **uncommitted**. A worker hands back its branch: the local commits from its own 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:
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 and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it. A `permission.skill` deny is different: Geneseed records each one it writes, and a rebuild or uninstall takes back only those, never a deny you set yourself.
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
 
@@ -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, uncommitted until
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
 
@@ -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.