geneseed 2.0.0 → 3.0.0

package/js/web/api.mjs

@@ -61,7 +61,7 @@ import { doctorCollect } from '../doctor.mjs';
 import { excludesSnapshot } from '../excludes.mjs';
 import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir, pyResolve } from '../hosts.mjs';
 import {
-  footprintOfDir, installState, installTargets, installedDefaults, modeOfDir,
+  doctrinesForBuild, footprintOfDir, installState, installTargets, installedDefaults, modeOfDir,
   postureOfDir, readJsonMaybe, readMaybe, themeOfDir,
 } from '../installs.mjs';
 import { frontmatter } from '../hooks.mjs';
@@ -273,16 +273,22 @@ export function specEntries(root, nested) {
  * `_web_core._deployed_inventory` — the agents and skills actually installed at
  * `state.target`, not a fresh render of `src/`.
  *
- * Laws still come from the render: once deployed they live inside AGENT.md rather than as
- * separate files, so the deployed arm replaces two of the three and not all three. A
- * deployed spec file carries neither a category nor a lifecycle status, so each is tagged
- * BY NAME from the same two sources the source render uses — and an entity the registry
- * does not know reads "personal" for both, which is the honest answer rather than a
- * borrowed one: filing it under the `build` fallback would claim a Geneseed taxonomy slot
- * it was never given.
+ * All three constitutional tiers still come from the render: once deployed they live inside
+ * AGENT.md rather than as separate files, so the deployed arm replaces the two ENTITY rosters
+ * and none of the constitution. A deployed spec file carries neither a category nor a
+ * lifecycle status, so each is tagged BY NAME from the same two sources the source render
+ * uses — and an entity the registry does not know reads "personal" for both, which is the
+ * honest answer rather than a borrowed one: filing it under the `build` fallback would claim
+ * a Geneseed taxonomy slot it was never given.
+ *
+ * ⚠ THE PACK SELECTION IS THE ONE THING THE RENDER CANNOT KNOW. `renderAll` emits all four
+ * pack files whatever `cfg.doctrines` says — measured: `makeCfg({doctrines:['craft']})` yields
+ * the same 105 items — because the filtering happens when AGENT.md's §2 is assembled, not in
+ * the walk. So the catalogue is always whole, and which packs this INSTALL built in comes from
+ * its own carrier via `doctrinesForBuild`, which resolves "no marker" to every pack.
  */
 export function deployedInventory(state) {
-  const render = tuiInventory(state.theme);
+  const render = tuiInventory(state.theme, doctrinesForBuild(state.target));
   const registry = loadRegistry();
   const skills = specEntries(path.join(state.target, 'skills'), true);
   for (const e of skills) {
@@ -292,7 +298,12 @@ export function deployedInventory(state) {
   }
   const agents = specEntries(path.join(state.target, 'agents'), false);
   for (const e of agents) e.status = entityStatus(registry, `agents/${e.name}`);
-  return { agents, skills, laws: render.laws, theme: state.theme };
+  return { agents,
+    skills,
+    laws: render.laws,
+    ontology: render.ontology,
+    doctrines: render.doctrines,
+    theme: state.theme };
 }
 
 /** `WebState.inventory` — the deployed record when there is one, else the source render. */
@@ -592,9 +603,53 @@ function configManifest(name, p) {
   return null;
 }
 
-/** `_web_core.SECTIONS` — a closed list; anything else is a 404. */
+/**
+ * `_web_core.SECTIONS` — a closed list; anything else is a 404.
+ *
+ * ⚠ `laws` STAYS ONE SECTION FOR ALL THREE TIERS, and that is a decision rather than an
+ * oversight. The console has ONE Constitution entry, not three, so a reader keeps the "read it
+ * top to bottom" property; the id stays `laws` because `tests/helpers/cli_golden.mjs`
+ * hard-requires `web/src/pages/Laws.jsx` and because a route rename buys nothing and costs a
+ * redirect. The tier lives on the ITEM (`tier: 'ontology' | 'invariant' | 'doctrine'`), which
+ * is where a consumer can act on it.
+ */
 export const SECTIONS = ['agents', 'skills', 'laws', 'memory', 'notebook', 'wiki', 'config'];
 
+/**
+ * The `laws` section's items — the whole constitution, in constitutional order, one flat list.
+ *
+ * FLAT AND NOT NESTED, because every other section is `{section, items}` and a second shape
+ * for one section is a second client path for one roster. The pack's grouping metadata rides
+ * on each doctrine row (`pack`, `packTitle`, `packDesc`, `active`), so a consumer groups by
+ * `pack` and has everything a header needs without a second fetch.
+ *
+ * Names are ADDRESSES and the three shapes cannot collide: `ont:<slug>` carries a colon no
+ * numeral has, an invariant is `[IVXLCDM]+`, a doctrine rule is `<pack>.<n>`. `apiItem`
+ * resolves all three off the same list.
+ */
+function constitutionItems(inv) {
+  return [
+    ...(inv.ontology ?? []).map((e) => ({ name: `ont:${e.id}`, title: e.title, desc: '',
+      tier: 'ontology' })),
+    ...inv.laws.map((e) => ({ name: e.num, title: `Rule ${e.num} — ${e.title}`, desc: '',
+      klass: e.klass ?? 'craft', tier: 'invariant' })),
+    ...(inv.doctrines ?? []).flatMap((p) => p.rules.map((r) => ({
+      name: `${r.pack}.${r.n}`,
+      title: `Doctrine ${r.pack} ${r.n} — ${r.title}`,
+      desc: '',
+      klass: r.klass ?? p.pack,
+      tier: 'doctrine',
+      pack: p.pack,
+      packTitle: p.title,
+      packDesc: p.desc,
+      // ⚠ EVERY RULE IS LISTED WHETHER OR NOT ITS PACK IS BUILT IN. An inactive pack that
+      // vanished from the payload would be indistinguishable from one that never shipped, and
+      // the console could not then offer the command that turns it back on.
+      active: p.active,
+    }))),
+  ];
+}
+
 /** `_web_catalog.api_catalog`. */
 export function apiCatalog(state, section) {
   if (!SECTIONS.includes(section)) throw new NotFound(section);
@@ -607,8 +662,7 @@ export function apiCatalog(state, section) {
     items = inv.skills.map((e) => ({ name: e.name, title: e.name, desc: e.desc,
       source: e.source ?? null, klass: e.klass ?? 'build', status: e.status ?? 'unknown' }));
   } else if (section === 'laws') {
-    items = inv.laws.map((e) => ({ name: e.num, title: `Rule ${e.num} — ${e.title}`,
-      desc: '', klass: e.klass ?? 'craft' }));
+    items = constitutionItems(inv);
   } else if (section === 'memory') {
     items = memoryItems(state);
   } else if (section === 'notebook') {
@@ -634,10 +688,21 @@ export function apiItem(state, type, name) {
     return out;
   }
   if (type === 'law') {
-    const e = inv.laws.find((x) => x.num === name);
+    // ONE ARM FOR THREE TIERS, resolved off the same list the catalogue publishes — so a name
+    // that appears in `/api/catalog/laws` always opens, and one that does not always 404s.
+    // Building the list twice is what would let the two drift.
+    const e = constitutionItems(inv).find((x) => x.name === name);
     if (!e) throw new NotFound(name);
-    return { type, name, title: `Rule ${e.num} — ${e.title}`, desc: '', body: e.body,
-      links: [], klass: e.klass ?? 'craft' };
+    const body = e.tier === 'ontology'
+      ? (inv.ontology.find((s) => `ont:${s.id}` === name)?.body ?? '')
+      : (e.tier === 'invariant'
+        ? (inv.laws.find((x) => x.num === name)?.body ?? '')
+        : (inv.doctrines.flatMap((p) => p.rules)
+          .find((r) => `${r.pack}.${r.n}` === name)?.body ?? ''));
+    // `links: []` — a constitution body is not link-resolved. It cites its siblings by
+    // ADDRESS (`Rule IV`, `Doctrine ops 1`, `Ontology: Telos`), not by path, and there is no
+    // file behind those to resolve to.
+    return { ...e, type, name, body, links: [] };
   }
   if (type === 'memory' || type === 'notebook') {
     flatName(name);
@@ -795,7 +860,21 @@ export function apiOverview(state) {
     counts: {
       agents: inv.agents.length,
       skills: inv.skills.length,
+      // ⚠ `laws` STAYS THE INVARIANT COUNT. The rail badge reads it, `docCounts` mirrors it as
+      // `{N_LAWS}`, and the doctor's frozen `proseMirrorProblems` compares README and
+      // SHIPPED.md prose against the same number. Widening it to "the whole constitution"
+      // would silently move all four at once.
       laws: inv.laws.length,
+      ontology: (inv.ontology ?? []).length,
+      // The tier's own summary, kept out of the section counts because it is not a section:
+      // `active`/`total` is the fraction the dashboard shows, `rules` counts only the packs
+      // this install built in — what it is bound by, not what its bundle carries.
+      doctrines: {
+        active: (inv.doctrines ?? []).filter((p) => p.active).length,
+        total: (inv.doctrines ?? []).length,
+        rules: (inv.doctrines ?? []).filter((p) => p.active)
+          .reduce((n, p) => n + p.rules.length, 0),
+      },
       memory: memoryItems(state).length,
       notebook: notebookItems(state).length,
       wiki: wikiItems(state).length,

package/js/web/docs.mjs

@@ -130,8 +130,15 @@ export function docGroups() {
  * the one-line description. A key of `null` marks a term no theme renames.
  */
 const GLOSSARY_KEYS = [
-  ['Rule (Law)', 'LAW', 'the governance rules the agent obeys'],
-  ['Rules (Laws)', 'LAWS', 'the body of governance rules'],
+  // The three tiers, in constitutional order and before the entities — a reader who does not
+  // know what an Ontology is here cannot read the rest of the glossary's first rows.
+  ['Ontology', 'ONTOLOGY', 'the always-on worldview under the rules — telos, evidence, '
+    + 'decisions, conduct; it holds the Pact'],
+  ['Rule (Law)', 'LAW', 'one of the nine always-on invariants: what is never done'],
+  ['Rules (Laws)', 'LAWS', 'the body of always-on invariants'],
+  ['Doctrine', 'DOCTRINE', 'one practice rule, cited `<pack> <n>` — how work is done here'],
+  ['Doctrines', 'DOCTRINES', 'the practice packs, chosen at build time; inactive packs still '
+    + 'ship in the bundle'],
   ['Agent', 'AGENT', 'a capability specialist'],
   ['Agents', 'AGENTS', 'the roster of specialists'],
   ['Skill', 'SKILL', 'a repeatable workflow'],
@@ -139,7 +146,10 @@ const GLOSSARY_KEYS = [
   ['Memory', 'MEMORY', 'durable, one-fact-per-file knowledge'],
   ['Notebook', 'NOTEBOOK', "the agent's sovereign space"],
   ['Wiki', 'WIKI', 'the machine-wide knowledge base'],
-  ['Pact', 'PACT', 'the two-way collaboration contract'],
+  // Still a token, still themed, but it names a CONCEPT INSIDE the ontology's Telos now
+  // rather than a peer of the Rules — `src/postures/peer.md` cites it and the section that
+  // used to carry it is the Ontology.
+  ['Pact', 'PACT', "the two-way collaboration contract, stated in the Ontology's Telos"],
   ['Posture', null, 'the relationship register the agent works in '
     + '(peer, mentor, expert, assistant, artisan)'],
   ['Mode', null, 'how work gets executed — direct (the agent works every '
@@ -156,8 +166,14 @@ const GLOSSARY_KEYS = [
 
 // ---- counts substituted into concept bodies -------------------------------------------
 
-/** `_web_docs._doc_counts`. */
-function docCounts(state) {
+/**
+ * `_web_docs._doc_counts`.
+ *
+ * Exported so the tier tokens can be gated on the day they are ADDED rather than on the day a
+ * page first spends one. Only one page carries `{N_LAWS}` today; a test that could only reach
+ * these through a rendered body would leave four of the seven untested until Task 6.2.
+ */
+export function docCounts(state) {
   const inv = state.inventory;
   const plugins = path.join(ROOT, 'adapters', 'opencode', 'plugins');
   let n = 0;
@@ -165,11 +181,23 @@ function docCounts(state) {
     n = readdirSync(plugins).filter((f) => f.startsWith('geneseed-') && f.endsWith('.js'))
       .length;
   } catch { n = 0; }
+  // `{N_LAWS}` IS THE INVARIANT COUNT AND NOTHING ELSE. The doctor's frozen
+  // `proseMirrorProblems` holds README and SHIPPED.md prose to the same number, so a token
+  // that quietly meant "the whole constitution" would put the docs and the gate at odds with
+  // no way to re-bless either. The other three tiers get their own tokens.
+  const packs = inv.doctrines ?? [];
+  const on = packs.filter((p) => p.active);
   return {
     '{N_LAWS}': (inv.laws || []).length,
     '{N_AGENTS}': (inv.agents || []).length,
     '{N_SKILLS}': (inv.skills || []).length,
     '{N_PLUGINS}': n,
+    '{N_ONTOLOGY}': (inv.ontology ?? []).length,
+    '{N_PACKS}': packs.length,
+    '{N_PACKS_ACTIVE}': on.length,
+    // Rules in the packs this install BUILT IN — the number a reader of these pages is
+    // actually bound by. The catalogue always ships whole, so it is never the smaller claim.
+    '{N_DOCTRINE_RULES}': on.reduce((t, p) => t + p.rules.length, 0),
   };
 }
 

package/js/web/jobs.mjs

@@ -107,7 +107,7 @@ import { statSync } from 'node:fs';
 import { StringDecoder } from 'node:string_decoder';
 import path from 'node:path';
 
-import { ROOT } from '../checkout.mjs';
+import { ROOT, PACK_ORDER } from '../checkout.mjs';
 import { setupBuildArgs } from '../generate.mjs';
 import { isDict } from '../mcp.mjs';
 import { jsonDumpsCompact, parseJson, pyTruthy, readText, writeText } from '../lib/fs.mjs';
@@ -444,11 +444,20 @@ export const NOT_PORTED_ACTIONS = new Set();
  */
 export const INLINE_ACTIONS = ['restore', 'install', 'deploy'];
 
+/**
+ * ⚠ `doctrines` DEFAULTS TO THE FULL SET, and it is the one axis here whose default is not the
+ * generator's own. `theme`/`emit`/`footprint`/`posture`/`mode` fall back to a frozen literal
+ * that costs nothing when it is wrong; a missing `--doctrines` falls through to
+ * `harness.config.json`, and a `{"doctrines":["craft"]}` there re-emits the deployed install
+ * without its commit/push consent gate. So a caller that forgets the axis gets ALL packs —
+ * unknown resolves to the full set, never to a config value (`doctrinesForBuild`).
+ */
 function actionTable({
   theme = 'neutral', emit = 'opencode-global', footprint = 'full',
-  posture = 'peer', mode = 'direct',
+  posture = 'peer', mode = 'direct', doctrines = [...PACK_ORDER],
 } = {}) {
-  const buildArgv = setupBuildArgs(theme, emit, null, null, footprint, posture, mode);
+  const buildArgv = setupBuildArgs(theme, emit, null, null, footprint, posture, mode,
+    doctrines);
   return {
     doctor: [[NODE(), CLI(), 'doctor']],
     build: [[NODE(), GEN(), ...buildArgv]],

package/js/web/server.mjs

@@ -45,7 +45,7 @@ import {
   existsSync, readFileSync, statSync, unlinkSync, chmodSync, mkdirSync, openSync,
 } from 'node:fs';
 import { createServer, request as httpRequest } from 'node:http';
-import { join, resolve as pathResolve, extname, basename, sep } from 'node:path';
+import { join, resolve as pathResolve, dirname, extname, basename, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gzipSync } from 'node:zlib';
 
@@ -60,11 +60,12 @@ import { promptLine } from '../setup.mjs';
 // which resolves because everything either side needs of the other is a hoisted function
 // declaration, not a value read at module-evaluation time.
 import { preflight } from '../update.mjs';
+import { doctrinesForBuild } from '../installs.mjs';
 import { NotFound, PREFIX_ROUTES, STATE_ROUTES, webState } from './api.mjs';
 import {
   apiDeployCmd, apiExcludesMutate, apiInstallCmd, apiInstallToggle, apiMcpToggle,
   apiMemoryDelete, apiProfileSave,
-  apiRestore, apiRulesMutate, apiRulesPromote, apiSelectView, buildOverride,
+  apiRestore, apiRulesMutate, apiRulesPromote, apiSelectView, buildOverride, mcpTargetPaths,
 } from './actions.mjs';
 import { apiActivityToggle } from './activity.mjs';
 import { apiDocs, apiDocsPage } from './docs.mjs';
@@ -248,6 +249,29 @@ export const PORTED_INLINE = ['/api/ping', '/api/docs', '/api/docs/page/',
 export const PORTED_POST_INLINE = ['/api/shutdown', '/api/restart', '/api/jobs/',
   '/api/actions/'];
 
+/**
+ * POST routes THAT NEVER EXISTED ON THE REFERENCE — the first of them, and the reason this set
+ * has to exist at all.
+ *
+ * `test_every_post_route_is_either_ported_or_declared_unported` asserts SET EQUALITY against
+ * `REF_POST`, a frozen literal of the paths the Python daemon answered. That was exactly right
+ * while the port was in flight: a route on one side and not the other was a defect either way.
+ * The port is finished and the reference is deleted, so the assertion now says something else —
+ * "this daemon may never grow a route" — which is a rule nobody chose.
+ *
+ * SO THE PARTITION GAINS A FOURTH PART RATHER THAN LOSING ITS EQUALITY. Widening `REF_POST` would
+ * have been the cheap edit and it would have been a lie: that list is a RECORD of what the
+ * reference answered, and a route added in 2026 was never in it. Keeping the record honest and
+ * declaring the additions beside it keeps both claims checkable — the reference's surface is
+ * still pinned, and everything past it is enumerated here instead of merely appearing.
+ *
+ * A route belongs here only once it is dispatched below; the dispatcher probe is what keeps this
+ * from becoming a declaration nobody honours.
+ */
+export const POST_BEYOND_REF = new Set([
+  '/api/reveal',
+]);
+
 function notPorted(path) {
   return NOT_PORTED.has(path) || NOT_PORTED_PREFIXES.some((p) => path.startsWith(p));
 }
@@ -419,6 +443,34 @@ export function makeHandler(state, jm, token, dist, holder = null) {
       requestRestart(state.theme);
       return sendJson(res, { restarting: true }, 200, ae);
     }
+    if (path === '/api/reveal') {
+      // "It asks for a token and a URL and I don't know where to put them." The screen already
+      // PRINTS the config path above each target's rows; what it could not do is take you there.
+      //
+      // THE ALLOWLIST IS THE WHOLE SECURITY OF THIS ENDPOINT, same as the toggle beside it, and
+      // it is the same allowlist — `mcpTargetPaths()`, one function with two callers rather than
+      // two copies that drift. An unlisted path is a 404 before anything is opened. Without it
+      // this is "ask the desktop to open any path on the machine", behind a CSRF token and
+      // nothing else, and on Windows `openUrl` interpolates into a `cmd` command line with
+      // `windowsVerbatimArguments` — so the exact-match lookup is also what bounds the strings
+      // that can ever reach a shell to the ones the machine's own install registry produced.
+      //
+      // THE FOLDER, NOT THE FILE. `open`/`start`/`xdg-open` on a `.json` hands it to whatever
+      // claims that extension — which on a stock Windows box is a browser, i.e. a read-only view
+      // of the exact file the user is trying to EDIT. The containing folder lands in Explorer /
+      // Finder / the file manager every time, and the filename is already on screen beside the
+      // button.
+      const want = String(readJsonBody(body).path ?? '');
+      if (!mcpTargetPaths().has(want)) {
+        return sendJson(res, { error: `not found: ${want || '(none)'}` }, 404, ae);
+      }
+      const dir = dirname(want);
+      // `openUrl` SWALLOWS EVERY FAILURE BY DESIGN (a headless box has no opener), so `ok` here
+      // means "the path was allowed and the request was made", never "a window appeared". The
+      // response says which directory, so the UI can print it as the fallback instruction.
+      openUrl(dir);
+      return sendJson(res, { ok: true, dir }, 200, ae);
+    }
     const route = POST_ROUTES.get(path);
     if (route !== undefined) {
       const [fn, okIs409] = route;
@@ -498,8 +550,13 @@ export function makeHandler(state, jm, token, dist, holder = null) {
     // install, so a re-theme preserves lean/full, the register and the operating mode.
     const [theme, emit] = action === 'build'
       ? buildOverride(state, body) : [state.theme, state.emit];
+    // The pack selection follows the install like footprint/posture/mode, and is read here
+    // rather than left to the table's default: a console Build must re-emit the constitution
+    // the deployment already carries. Unknown (no `Active packs:` marker) resolves to ALL
+    // packs — never to `harness.config.json`, which would drop the consent gate.
     const cmds = actionCommands(action, {
       theme, emit, footprint: state.footprint, posture: state.posture, mode: state.mode,
+      doctrines: doctrinesForBuild(state.target),
     });
     if (!pyTruthy(cmds)) {
       return sendJson(res, { error: `unknown action ${action}` }, 404, ae);

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",