geneseed 3.11.0 → 3.13.0

package/docs/web-ui.md

@@ -51,7 +51,7 @@ The left rail mirrors the harness's own shape:
 | Group | Views |
 | --- | --- |
 | *(ungrouped)* | Dashboard |
-| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Docs |
+| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Loops · Docs |
 | **🩺 Care** | Activity · Changes · Doctor |
 | **🎨 Setup** | Harness · Settings |
 
@@ -111,16 +111,47 @@ streams the output of background jobs and keeps their history across reloads.
   **Promote to rule** control turns a recurring lesson into a trial rule in
   `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
   twice — landing you on the Rules page.
+- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only, laid out
+  like the Library: a rail of sections (**Templates**, **Bricks**, **Active**, each with its
+  count; `#/loops/<section>/<item>` opens an entry), with the selected section's groups
+  nested under it in the rail (template categories, brick origins, run statuses — pick one to
+  narrow the list), a filterable list, and a reader.
+  **Templates** are grouped by their `category` (architecture, tests, development,
+  refactoring, day-to-day, then *Other*), a *human gate* pill on any that stops for you. The
+  reader draws the selected template as a ring: the iteration turning clockwise from its head,
+  each inner retry loop hung outside on its head node, the ⛨ *validate* gate the engine adds
+  before the first mutate step, setup entering from the left and `done → close` leaving from
+  the head; its `rules` follow, then a compact row per brick (effect, agent or skill, outcomes,
+  human gate), and clicking a node scrolls to and lights its row. A graph a ring cannot draw
+  cleanly (more than eight iteration steps, a node in more than three loops) falls back to
+  left-to-right boxes. **Bricks** are grouped by origin (project / global / shipped), pilled
+  for *mutate*, *human gate*, what they override and *unavailable*; the reader shows the
+  frontmatter facts (outcomes as pills, availability with its reason), then the body rendered as
+  markdown, with a **View source** toggle for the file as parsed, frontmatter and all. Templates and
+  Bricks read `GET /api/loops`, resolved from the selected install's root, so a project
+  install shows its `.geneseed/` bricks and templates. **Active** is every loop
+  `geneseed loop init` registered on this machine (`GET /api/loops/active`, polled every
+  5 s), grouped awaiting, running, done/stopped, finished/unreadable; the reader shows its
+  branch, `iteration N / max`, current node and a preset picker (`POST /api/loops/preset`,
+  the page's only write), what an awaiting loop waits on (launch / declared / actual / a
+  human gate, with its node) — the answer is given in the agent's session, never here — and
+  its ring with the current node filled, with its iteration history under it.
 - **Profile** (`#/profile`) — `PROFILE.md` beside the deployed AGENT.md: who you are and
   how you like to work. Opens rendered; **Edit** is a whole-file editor. The save carries
   the fingerprint it loaded — if an agent session changed the file first, your edit stays
   on screen and a second Save replaces the newer version.
 - **Skills** (`#/skills`) and **Agents** (`#/agents`) — the deployed catalogue, each entry
-  with its purpose line and full spec.
+  with its purpose line and full spec. While Skills is selected, its skill types sit nested
+  under it in the rail, each with its count, above a thin bar of their shares; pick one to
+  narrow the list.
 - **Docs** (`#/docs`) — rendered documentation: markdown pages, concept pages, a CLI
-  reference (generated from the harness argument parser), and a glossary, grouped into
-  Get started / Core concepts / How-to / MCP servers / Plugins / Reference / Deeper. Filtered
-  for one host family (OpenCode, or Claude Code — which Bob and OpenClaude share); with no
+  reference (generated from the harness argument parser), and a glossary, in the Library's
+  three panes: the parts (Understand / Guides / Concepts / Reference) with their page counts,
+  the open part's sections nested under it in the rail (pick one to narrow the list), the
+  part's pages under their sections with a filter, and the page with its breadcrumb,
+  outline and Previous / Next within the section. Filtered for one host (OpenCode, Claude
+  Code, Bob or OpenClaude; Claude-family pages show to all three Claude-engine hosts, a page
+  tagged with a list of hosts only to those); with no
   choice stored it follows the deployed install.
 
 ### 🩺 Care

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.11.0"
+  "version": "3.13.0"
 }

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Fifty-seven modules in seven folders. This page is the address book: **what each one owns**, and
+Sixty-one modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -20,6 +20,7 @@ js/build/     src/ + themes/  →  rendered text  →  a bundle  →  a per-host
 js/hosts/     where it stops being a renderer and touches the machine
 js/inspect/   the read-only half: doctor, status, diff, validate, catalog
 js/lib/       primitives, every one a deliberate divergence from the Node default
+js/loop/      `geneseed loop` — the state machine over LOOP.md, and what it steps through
 js/maintain/  lifecycle verbs that change an install that already exists
 js/ui/        what it prints at a terminal
 js/web/       the `geneseed web` console
@@ -68,10 +69,11 @@ user co-owns, and the hook verbs those emitted configs then run.
 |---|---|
 | `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), plus `resolvePath`/`expanduser` |
 | `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), `learn`. `--host` picks the verdict dialect |
+| `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
 | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
 | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
 | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
-| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture and mode |
+| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
 
@@ -125,6 +127,34 @@ float `1.0` into one double, and that value gets written into a user's file. Do
 library for `udiff.mjs`: it is not Myers, ties resolve to the earliest match. Every function in
 `paths.mjs` branches on `process.platform`, so green on one OS proves nothing about the other.
 
+## `js/loop/` — the loop engine
+
+`geneseed loop` — a state machine over a brick graph, persisted as a JSON block in `LOOP.md` at
+the git root. The model only ever runs the node it is handed and reports an outcome; every
+transition, score and stop is computed here.
+
+| module | owns |
+|---|---|
+| `graph.mjs` | `checkGraph` — the rules a loop graph must satisfy before a node runs: nodes name real bricks, edges cover every outcome, `$close` is reachable, every cycle is inside a declared loop |
+| `score.mjs` | The risk arithmetic: `WEIGHTS`, `PRESETS`, `declaredRisk`/`actualRisk`/`decide`, `parseNumstat`. Pure — no import but node builtins |
+| `catalog.mjs` | `loadCatalog` — bricks and loop templates from shipped/global/project origins, later overrides earlier BY NAME |
+| `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
+| `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
+| `registry.mjs` | `loops.json` under XDG — the launched-loop identity list `loop init` records into and the Active tab's `activeLoops`/`setLoopPreset` read and rewrite |
+
+**Before editing:** `score.mjs` is imported by the build driver (the `--trust` choices), so it must
+stay free of every import but node builtins and `graph.mjs`. `state.mjs` excludes `LOOP.md` itself
+(and its own atomic-write sibling, `LOOP.md.tmp`) from every score and every read-brick porcelain
+check — it is the engine's own bookkeeping, never part of the work being scored. Every LOOP.md
+write goes through `state.mjs`'s `writeLoopFile`, never a bare `writeText`, so a killed process
+cannot leave a torn file. `cli.mjs` may not spawn: git output is piped in on stdin by the model,
+never read by this entry. `registry.mjs` swallows its own errors on `recordLoop`/`activeLoops` on
+purpose, like `js/inspect/registry.mjs` — a registry hiccup must never fail `loop init` or a
+read — but `setLoopPreset` does not: a preset change the caller asked for must be reported when it
+fails. `activeLoops` saves the registry back only when the kept set actually changed (a pruned
+root, a loop newly seen finished or seen running again) — a routine poll from the Active tab must
+never be a write.
+
 ## `js/maintain/` — lifecycle
 
 Verbs that change an install that already exists, as opposed to rendering one.

package/js/build/driver.mjs

@@ -65,6 +65,9 @@ import {
 // registry to find every install it must re-emit, and a CLI verb may not reach into a driver
 // for a reader. See js/inspect/registry.mjs.
 import { registryRecord, registryRoots } from '../inspect/registry.mjs';
+// The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
+// what lets it sit inside this driver's total `child_process` ban.
+import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
 
 // P2. `--sync-themes` crossed into its own module rather than into this file: it is 90 lines
 // of textual surgery over committed files with a corpus of its own, and it is the half of the
@@ -111,8 +114,8 @@ export function resolveOut(raw) {
  */
 function configDefaults() {
   const d = {
-    theme: 'neutral', posture: 'peer', mode: 'direct', doctrines: [...PACK_ORDER],
-    excludeRules: [],
+    theme: 'neutral', posture: 'peer', mode: 'direct', trust: DEFAULT_PRESET,
+    doctrines: [...PACK_ORDER], excludeRules: [],
   };
   if (!existsSync(CONFIG)) return d;
   try {
@@ -163,7 +166,7 @@ function configDefaults() {
  * flag is added to one and not the other, and nothing downstream would say so.
  */
 const VALUED = {
-  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode',
+  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode', '--trust': 'trust',
   '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules',
   '--out': 'out', '--target': 'out', '--emit': 'emit',
   '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
@@ -194,13 +197,13 @@ const FLAG_BY_NAME = Object.fromEntries(
 );
 
 /**
- * The four flags `choice` validates, as ONE table for the same anti-drift reason.
+ * The five flags `choice` validates, as ONE table for the same anti-drift reason.
  *
- * A function and not a constant because two of the four read the checkout: `discoverNames`
+ * A function and not a constant because two of the five read the checkout: `discoverNames`
  * scans `postures/` and `modes/`, so the answer depends on the source tree this driver is
  * standing in and cannot be frozen at import.
  *
- * `--doctrines` is DELIBERATELY not a fifth row. Every consumer of this table treats an
+ * `--doctrines` is DELIBERATELY not a sixth row. Every consumer of this table treats an
  * entry as one value drawn from a closed list — `choice` refuses anything else, and
  * `usage`'s metavar prints the list as the whole legal surface. `--doctrines` takes a comma
  * LIST plus the sentinel `none`, so a row here would have refused `craft,rigor` outright and
@@ -213,6 +216,7 @@ function choicesFor() {
     '--footprint': ['lean', 'full'],
     '--posture': discoverNames('postures', 'peer'),
     '--mode': discoverNames('modes', 'direct'),
+    '--trust': Object.keys(PRESETS),
   };
 }
 
@@ -340,6 +344,7 @@ function usage() {
 function parseArgs(argv, defaults) {
   const args = {
     theme: defaults.theme, posture: defaults.posture, mode: defaults.mode,
+    trust: defaults.trust,
     doctrines: defaults.doctrines,
     excludeRules: defaults.excludeRules,
     out: 'Harness', emit: 'files', footprint: 'lean', root: null,
@@ -1035,7 +1040,7 @@ export function buildInto({ theme, out, footprint = 'lean' }) {
 }
 
 export function emitGlobalInto(host, {
-  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null,
+  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null, trust = null,
 }) {
   // `build.HOSTS.get(host, build.HOSTS["opencode"])` — an unknown host falls back rather than
   // raising, because the host comes from a marker file a user can edit.
@@ -1058,7 +1063,8 @@ export function emitGlobalInto(host, {
       // at `[]`, so the key is OMITTED instead of passed through — `makeCfg`'s own default is
       // the fail-closed answer and an explicit `doctrines: null` would not reach it.
       makeCfg({
-        posture: posture || 'peer', mode: mode || 'direct', ...(doctrines ? { doctrines } : {}),
+        posture: posture || 'peer', mode: mode || 'direct', trust: trust || DEFAULT_PRESET,
+        ...(doctrines ? { doctrines } : {}),
       }),
       { theme, footprint, root: null, cfgDir }, out,
     ),

package/js/build/generate.mjs

@@ -34,11 +34,12 @@ import path from 'node:path';
 
 import { main as driverMain } from './driver.mjs';
 import { makeCfg, PACK_ORDER } from './source.mjs';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
   excludedRulesOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
-  readMaybe, themeOfDir,
+  readMaybe, themeOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
 import { renderAll } from './render.mjs';
@@ -93,7 +94,7 @@ function sysExit(msg) {
  */
 const BUILD_FORWARD = [
   ['theme', '--theme'], ['emit', '--emit'], ['footprint', '--footprint'],
-  ['posture', '--posture'], ['mode', '--mode'], ['doctrines', '--doctrines'],
+  ['posture', '--posture'], ['mode', '--mode'], ['trust', '--trust'], ['doctrines', '--doctrines'],
   ['excludeRules', '--exclude-rules'], ['out', '--out'], ['root', '--root'],
   ['configDir', '--config-dir'],
 ];
@@ -114,7 +115,7 @@ export function cmdBuild(args) {
  * The elision rules are not symmetric and the Python says why: `footprint` is ALWAYS passed,
  * because omitting it when it matched the generator's default silently coupled the answer to
  * whatever that default happened to be — the moment the default moved, picking the old one
- * produced the new one. `posture` and `mode` still elide at theirs, and neither has moved.
+ * produced the new one. `posture`, `mode` and `trust` still elide at theirs, and none has moved.
  *
  * ⚠ `doctrines` DOES NOT ELIDE, AND THAT IS THE SAFETY DECISION, NOT A STYLE ONE. It used to
  * elide on the full set, by analogy with posture and mode — but those two compare against a
@@ -137,7 +138,7 @@ export function cmdBuild(args) {
  */
 export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
   posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER,
-  excludeRules = null) {
+  excludeRules = null, trust = DEFAULT_PRESET) {
   const argv = ['--theme', theme, '--emit', emit];
   if (!emit.endsWith('-global')) {
     if (out) argv.push('--out', out);
@@ -146,6 +147,7 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
   if (footprint) argv.push('--footprint', footprint);
   if (posture && posture !== 'peer') argv.push('--posture', posture);
   if (mode && mode !== 'direct') argv.push('--mode', mode);
+  if (trust && trust !== DEFAULT_PRESET) argv.push('--trust', trust);
   if (Array.isArray(doctrines)) {
     // Emitted in `allPacks` order, not the order handed in: a caller may legitimately pass an
     // unsorted list, and the flag has to be canonical for the same reason the driver
@@ -199,6 +201,8 @@ export function installProfile(host, scope, root) {
   const footprint = footprintOfDir(root);
   const posture = postureOfDir(root) || defaultPosture();
   const mode = modeOfDir(root) || defaultMode();
+  // Read off the deployed loop skill; no config fallback — `DEFAULT_PRESET` is the engine's.
+  const trust = trustOfDir(root) || DEFAULT_PRESET;
   // A rebuild that defaulted the pack selection would re-emit an install into a constitution
   // its owner did not choose — and in one direction that is not merely surprising: dropping
   // the process pack takes the commit/push consent RULES out of AGENT.md while
@@ -213,7 +217,7 @@ export function installProfile(host, scope, root) {
   const excludeRules = excludedRulesOfDir(root);
   const out = scope === 'global' ? null : root;
   const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
-    PACK_ORDER, excludeRules);
+    PACK_ORDER, excludeRules, trust);
   // A GLOBAL ROW NAMES ITS OWN DIR. `root` came from the host's config-dir resolver, which
   // honours env overrides (`OPENCODE_CONFIG_DIR`, `CLAUDE_CONFIG_DIR`…); without the flag the
   // same argv run from a shell lacking that variable re-emits into the DEFAULT dir — a second
@@ -221,7 +225,7 @@ export function installProfile(host, scope, root) {
   if (scope === 'global') argv.push('--config-dir', root);
   return {
     host, scope, root, state: installState(root, host, scope),
-    emit, theme, footprint, posture, mode, doctrines, excludeRules, argv,
+    emit, theme, footprint, posture, mode, trust, doctrines, excludeRules, argv,
   };
 }
 

package/js/build/render.mjs

@@ -35,6 +35,7 @@ import { parseJson } from '../lib/json.mjs';
 import { normcase, comparePaths } from '../lib/paths.mjs';
 // `js/build/source.mjs` imports nothing but node builtins, so this direction cannot cycle.
 import { PACK_ORDER, readPackText, resolveRuleIds } from './source.mjs';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 
 /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
 export const STRUCTURE = {
@@ -391,6 +392,10 @@ export function effectiveTheme(cfg, themeName, { footprint = 'full', lawsPrefix
   const theme = { ...loadTheme(cfg, themeName), ...(cfg.structure ?? STRUCTURE) };
   theme.POSTURE_BODY = registerBody(cfg, theme, 'postures', cfg.posture ?? 'peer', 'peer');
   theme.MODE_BODY = registerBody(cfg, theme, 'modes', cfg.mode ?? 'direct', 'direct');
+  // The loop skill's default trust preset (`--trust`), raw for `--preset` and capitalised for
+  // the `Default trust preset: **<Label>**` line `trustOfDir` reads back off an install.
+  theme.TRUST = cfg.trust ?? DEFAULT_PRESET;
+  theme.TRUST_LABEL = theme.TRUST[0].toUpperCase() + theme.TRUST.slice(1);
   // The doctrines pair is threaded, not read off `cfg`: `footprint` is a per-RENDER value
   // (`renderAll`'s option, and the same cfg renders both ways in one process), so parking it
   // on cfg would make the terse/full choice sticky across calls. An options object rather

package/js/build/source.mjs

@@ -26,6 +26,7 @@
  */
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 
 /**
  * One doctrine pack file used to be read three times per render — the survives gate and the
@@ -256,7 +257,8 @@ export function knownRuleIds() {
  * `PACK_ORDER` for the whole process.
  */
 export function makeCfg({
-  posture = 'peer', mode = 'direct', doctrines = PACK_ORDER, excludeRules = [],
+  posture = 'peer', mode = 'direct', trust = DEFAULT_PRESET, doctrines = PACK_ORDER,
+  excludeRules = [],
 } = {}) {
   return {
     root: ROOT,
@@ -268,6 +270,8 @@ export function makeCfg({
     workflowSrc: WORKFLOW_SRC,
     posture,
     mode,
+    // The loop skill's default preset (`--trust`); the skill is its only reader.
+    trust,
     doctrines: Array.isArray(doctrines) ? [...doctrines] : [...PACK_ORDER],
     // ⚠ THE SECOND DOCTRINE AXIS, AND ITS DEFAULT IS THE OPPOSITE WAY ROUND. `doctrines`
     // defaults to EVERYTHING because an unknown selection must bind the most; `excludeRules`

package/js/cli-table.json

@@ -133,6 +133,21 @@
           "type": null,
           "hidden": false
         },
+        {
+          "names": [
+            "--trust"
+          ],
+          "dest": "trust",
+          "metavar": null,
+          "help": "default loop trust preset: how much a loop may do before it stops to ask (default balanced)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
         {
           "names": [
             "--doctrines"
@@ -623,6 +638,252 @@
       "options": [],
       "mutex": []
     },
+    {
+      "name": "loop",
+      "help": "run a loop: check graphs, start one in LOOP.md, and step its state machine (next/score/record/decide)",
+      "description": "",
+      "positionals": [
+        {
+          "names": [],
+          "dest": "action",
+          "metavar": null,
+          "help": "",
+          "choices": [
+            "check",
+            "init",
+            "next",
+            "score",
+            "record",
+            "decide"
+          ],
+          "default": null,
+          "required": true,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "options": [
+        {
+          "names": ["--graph"],
+          "dest": "graph",
+          "metavar": null,
+          "help": "a loop template name or a .json graph file",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--brick"],
+          "dest": "brick",
+          "metavar": null,
+          "help": "check one brick file instead of the whole catalogue",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--title"],
+          "dest": "title",
+          "metavar": null,
+          "help": "the loop's title, written into LOOP.md",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--requirement"],
+          "dest": "requirement",
+          "metavar": null,
+          "help": "the requirement the loop exists to satisfy",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--preset"],
+          "dest": "preset",
+          "metavar": null,
+          "help": "the risk preset to run under (default: balanced)",
+          "choices": [
+            "prudent",
+            "balanced",
+            "aggressive"
+          ],
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--contracts"],
+          "dest": "contracts",
+          "metavar": null,
+          "help": "comma-separated contract globs appended to the template's own (init)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--declared"],
+          "dest": "declared",
+          "metavar": null,
+          "help": "score the card just declared, before it runs",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--diff"],
+          "dest": "diff",
+          "metavar": null,
+          "help": "score the actual diff, read as numstat on stdin",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--actions"],
+          "dest": "actions",
+          "metavar": null,
+          "help": "comma-separated declared action kinds (new-file, logic, api, ...)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--write-set"],
+          "dest": "write_set",
+          "metavar": null,
+          "help": "comma-separated files the declared card expects to touch",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--intent"],
+          "dest": "intent",
+          "metavar": null,
+          "help": "a short label for what the declared card is doing",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--outcome"],
+          "dest": "outcome",
+          "metavar": null,
+          "help": "the brick's reported outcome, one of its declared outcomes",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--card"],
+          "dest": "card",
+          "metavar": null,
+          "help": "a JSON card to record alongside the outcome",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--verdict"],
+          "dest": "verdict",
+          "metavar": null,
+          "help": "the user's answer to an awaiting validation",
+          "choices": [
+            "ok",
+            "no",
+            "amend"
+          ],
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--note"],
+          "dest": "note",
+          "metavar": null,
+          "help": "a note attached to a record or a decide verdict, written into LOOP.md so it survives the unit",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--note-file"],
+          "dest": "note_file",
+          "metavar": null,
+          "help": "record's note read from this file instead of the command line (CRLF folded, trimmed) — for a multi-line note or one that mentions git commit/push",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "mutex": []
+    },
     {
       "name": "mcp",
       "help": "list the MCP servers wired into each active install, and the presets available to add",