This dump extends the base requirements machine\n(2026-09-18-opencode-requirements-machine)\ninto a fractal: any module folder can host its own full instance of the machine — its own registry,\nits own tests, its own copy of the coverage script — while the root machine stays aware of its children\nthrough a manifest and a cross-machine aggregator. The module name becomes the ID prefix, so the root's\nand the module's ID grammars can never match each other's IDs; a module is self-contained and extractable\ntogether with its git history.
\nField-tested in two stages: one pilot split (a subsystem module migrated with a full ID rename, suite\ngreen), then about a week of ordinary work on top of it — the module's registry grew from 9 rows to 23\n(including a whole new research group) while the root's ID space stayed clean. Everything\nproject-specific is replaced with placeholders: <project> is the repository root, <module> is one\nmodule folder, <MOD> is its ID prefix, <ROOT> is the root prefix.
The base machine is one REQUIREMENTS.md, one tests/ directory, one req-coverage.js. Its\ngroup-by-prefix IDs already anticipate modules (<ROOT>-TRANSPORT-*, <ROOT>-LLM-*), but physically\neverything lives in two root files. Three pains showed up in a long-running agent-driven project:
LEGACY anchor even documents the \"fresh project\" empty-set case.Design iterated with the human in three rounds; the middle round was worse and is recorded because the\niteration itself is the field note.
\n<ROOT>-<MOD>-*\nIDs; the root would forbid itself from minting under child-owned prefixes, with an explicit allowlist\nfor integration \"seam\" rows. The human rejected this and proposed the better rule: the prefix IS the\nmodule name. The child machine runs with PREFIX=\"<MOD>\" and mints <MOD>-<GROUP>-NN. Consequences,\nall verified in the pilot:<ROOT>-… vs <MOD>-…) cannot match each other's IDs — cross-machine\ncollisions are eliminated by construction, not by a checker;<GROUP> slot is freed for module-internal semantics (transport, synthesis, networking,\ncatalog, logging — the module's own vocabulary);req-machines.json binding folder ↔ prefix. An\nauto-discovered REQUIREMENTS.md that is not in the manifest is a hard failure — machines are\nannounced, not stumbled upon.<module>/tests/; the suite runner learns one\nmore discovery glob. The commit gate remains the FULL suite — module subsets are for iteration speed;\ncross-module regressions are caught by the whole suite plus the aggregator.docs/ideas/ → gate → mint) is unchanged;\nafter the fractal split, a candidate mints IDs only into the module registry after it passes its\ngate. A dead candidate = delete its folder and its manifest row; no dead IDs anywhere.<project>/\n ├── REQUIREMENTS.md # root machine: seams + root-owned groups only\n ├── req-machines.json # manifest: folder ↔ prefix bindings (explicit creation)\n ├── package.json # \"req\": root && children && aggregator\n ├── scripts/\n │ ├── req-coverage.js # base machine — UNTOUCHED\n │ ├── req-aggregate.mjs # cross-machine invariants (this dump)\n │ └── <module>/ # a module = machine instance root\n │ ├── req-coverage.js # copy of the base script, knobs set\n │ ├── REQUIREMENTS.md # module registry, IDs <MOD>-<GROUP>-NN\n │ ├── <module code> … # module implementation\n │ └── tests/*_test.* # module tests (any extension your runner knows)\n └── tests/ # root tests (seams/glue live here)\n<module>/req-coverage.js is the base scripts/req-coverage.js verbatim except the knobs and the header.\nThe changed block:
// <module>/req-coverage.js — machine INSTANCE for the <module> module (fractal machine:\n// a copy of the template scripts/req-coverage.js with the module's knobs). Keep in sync\n// with the template when it changes. The root machine does NOT scan this module; the link\n// is req-machines.json + scripts/req-aggregate.mjs. Standalone it also works inside an\n// extracted module repo (fresh project: the empty LEGACY anchor).\n// If your base script validates named flows, import its flow palette here and adjust the\n// relative path.\n\nconst ROOT = fileURLToPath(new URL(\".\", import.meta.url)) // the module dir, not the repo root\nconst PREFIX = \"<MOD>\" // ← module name IS the ID prefix\nconst TESTS_DIR = join(ROOT, \"tests\")\n// LEGACY: same frozen empty anchor as a fresh project — a new module has no legacy rows.\nEverything else — row grammar, ✅ without a test / test uses unknown ID checks, flow validation,\nlegacy anchor — is the base machine's logic and stays byte-identical. On a fresh module the instance must\nexit 0 immediately (the base script's \"empty registry\" case).
<project>/req-machines.json{\n \"$comment\": \"Folder<->prefix bindings for child requirements machines (fractal machine). A child machine is created explicitly: module folder + REQUIREMENTS.md + req-coverage.js instance + a row HERE. Cross-checks: node scripts/req-aggregate.mjs (part of npm run req).\",\n \"children\": [\n { \"dir\": \"scripts/<module>\", \"prefix\": \"<MOD>\" }\n ]\n}\n<project>/scripts/req-aggregate.mjsPer-machine integrity (coverage, flow, legacy) stays in each machine instance; the aggregator only owns\nwhat is visible across registries at once — five invariants:
\nREQUIREMENTS.md outside the root that is\nNOT in the manifest fails (machines are created explicitly);#!/usr/bin/env node\n// scripts/req-aggregate.mjs — cross-machine invariants of the fractal requirements machine.\n// Per-machine integrity (coverage/flow/legacy) belongs to the instances (req-coverage.js\n// in the root and in each module); this script owns only what is visible ACROSS all registries.\n// Row grammar — one-to-one with the template req-coverage.js (one truth for the grammar;\n// when you change the template, sync deliberately).\nimport { readFileSync, readdirSync, statSync, existsSync } from \"node:fs\"\nimport { join, relative, sep } from \"node:path\"\nimport { fileURLToPath, pathToFileURL } from \"node:url\"\n\nconst ROOT = fileURLToPath(new URL(\"..\", import.meta.url))\nconst REGISTRY = \"REQUIREMENTS.md\"\nconst ROW = /^-\\s*(✅|🟧|⬜|❓)\\s*\\*\\*([A-Z][A-Z0-9]*-[A-Z0-9]+-\\d+)\\*\\*/gm\nconst TEST_FILE = /_test\\.[^./]+$/ // ← adapt to your stack (\".test.js\", \"_test.py\", …)\n\nfunction rowsOf(text) {\n return [...text.matchAll(ROW)].map((m) => m[2])\n}\n\nfunction walk(dir, skip, out) {\n for (const name of readdirSync(dir)) {\n if (skip.has(name)) continue\n const p = join(dir, name)\n if (statSync(p).isDirectory()) walk(p, skip, out)\n else if (name === REGISTRY) out.push(p)\n }\n}\n\nfunction main() {\n const problems = []\n const manifest = JSON.parse(readFileSync(join(ROOT, \"req-machines.json\"), \"utf8\"))\n const children = manifest.children ?? []\n // Normalize EVERY path comparison to forward slashes — see \"What worked / what didn't\".\n const byDir = new Map(children.map((c) => [c.dir.split(sep).join(\"/\"), c]))\n const childPrefixes = new Set(children.map((c) => c.prefix))\n\n for (const [dir] of byDir) {\n if (!existsSync(join(ROOT, dir, REGISTRY))) problems.push(`manifest child has no ${REGISTRY}: ${dir}`)\n }\n\n const discovered = []\n // skip set: VCS/vendor/scratch/output dirs — list YOURS; a stray tmp/ lab folder tripped v1.\n walk(ROOT, new Set([\".git\", \"node_modules\", \"tmp\", \"<your build/output dirs>\"]), discovered)\n for (const file of discovered) {\n const dir = relative(ROOT, join(file, \"..\")).split(sep).join(\"/\")\n if (dir === \"\") continue // the root registry is its own machine, checked by its instance\n if (!byDir.has(dir)) problems.push(`unregistered requirements machine (add to req-machines.json): ${dir}`)\n }\n\n const seen = new Map() // id -> registry dir\n const rootText = readFileSync(join(ROOT, REGISTRY), \"utf8\")\n for (const id of rowsOf(rootText)) {\n if (childPrefixes.has(id.split(\"-\")[0])) problems.push(`root registry uses child-owned prefix: ${id}`)\n if (seen.has(id)) problems.push(`duplicate ID across machines: ${id} (${seen.get(id)} and .)`)\n else seen.set(id, \".\")\n }\n\n for (const [dir, cfg] of byDir) {\n const text = readFileSync(join(ROOT, dir, REGISTRY), \"utf8\")\n for (const id of rowsOf(text)) {\n if (id.split(\"-\")[0] !== cfg.prefix) problems.push(`${dir}: row outside module prefix ${cfg.prefix}-*: ${id}`)\n if (seen.has(id)) problems.push(`duplicate ID across machines: ${id} (${seen.get(id)} and ${dir})`)\n else seen.set(id, dir)\n }\n }\n\n for (const prefix of childPrefixes) {\n const token = new RegExp(`${prefix}-[A-Z0-9]+-\\\\d+`, \"g\")\n const testsDir = join(ROOT, \"tests\")\n if (existsSync(testsDir)) {\n ;(function walkTests(d) {\n for (const name of readdirSync(d)) {\n const p = join(d, name)\n if (statSync(p).isDirectory()) walkTests(p)\n else if (TEST_FILE.test(name)) {\n for (const m of readFileSync(p, \"utf8\").matchAll(token)) {\n problems.push(`root test references child prefix ${prefix}: ${m[0]} in ${relative(ROOT, p).split(sep).join(\"/\")}`)\n }\n }\n }\n })(testsDir)\n }\n }\n\n if (problems.length) {\n console.error(\"req-aggregate FAILED:\\n \" + problems.join(\"\\n \"))\n process.exit(1)\n }\n console.log(`req-aggregate OK (machines=${children.length + 1}, ids=${seen.size})`)\n}\n\nconst isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url\nif (isMain) main()\nThe change is one extra discovery pass in whatever lists your test files. Semantics, stack-neutral:\nlist <module>/tests/** for every direct child of the folder that holds your modules, keep only files\nmatching your test-file pattern, and merge them into the same list the root tests/ produces (sorted,\nso the order is stable):
const files = [...rootTests(\"tests/\")] // your existing root discovery\nfor (const module of subdirs(\"<modules root>\")) { // e.g. \"scripts\" — the folders that can own a machine\n files.push(...testFilesUnder(`${module}/tests/`)) // same test-file pattern as the root pass\n}\nfiles.sort() // lexical, stable\nIn the pilot this was three directory-listing passes (tests/, then <modules root>/*/tests/); the\nshape is identical in any stack. The point is not the code but that the global npm test keeps covering\nmodule tests — a split that hides module tests from the gate is worse than no split.
\"req\": \"node scripts/req-coverage.js && node scripts/<module>/req-coverage.js && node scripts/req-aggregate.mjs\"\n(Extend with one <module>/req-coverage.js term per module; the aggregator is always last.)
# <module> — requirements registry (child requirements machine)\n\nThe module = mini-project root: code, tests/, this registry and the machine instance\n(req-coverage.js, PREFIX=<MOD>) are self-contained: the folder is extractable into a\nseparate repo whole (`git subtree split --prefix=<path>`).\n\n- **ID prefix = module name**: `<MOD>-<GROUP>-NN`. The root machine (prefix <ROOT>)\n does not use this range and does not scan it — collision is structurally impossible;\n the folder<->prefix binding lives in req-machines.json, cross-checks — req-aggregate.\n- **Pipeline seams** (integration tested by the host) stay in the ROOT registry under the\n root prefix.\n- Groups: <GROUP1> — …; <GROUP2> — … (the middle slot is yours).\n\n- ✅ **<MOD>-<GROUP1>-01**: <formulation copied from the old row, ID renamed>. *(flow: <flow>; refs: …; tests: <module>/tests/…)*\n<module> (prefix <MOD>).<module>/REQUIREMENTS.md and were renamed from\n<ROOT>-<MOD>-NN to <MOD>-<GROUP>-NN (the group slot re-cut by concern);<module>/tests/ with their comment IDs rewritten; shorthand\ncomment clusters like <ROOT>-<MOD>-02/03/04 (one comment naming several IDs) needed an explicit\nmapping — a plain token regex misses bare-number shorthand;npm run req = root 375 rows + module 9 rows + req-aggregate OK (machines=2, ids=384).The real test of the split is not the migration commit but what happened next: the machine was the\nproject's only registry gate for ~6 days of active work, with npm run req (root && module &&\naggregator) on every commit.
npm test as everything else. \"Boring gate\" is the success mode here.experimental flag. The fractal's depth is proven; its breadth is not.req-coverage.js + idea process). From scratch: base first, then this dump. On top of an\nexisting base: start at step 1.<modules root>/<module>/ → <MOD>). Check no existing prefix collides.<module>/req-coverage.js; set the knobs (module dir as ROOT,\nPREFIX, TESTS_DIR=./tests; import your flow palette if the base validates flows). Do not edit the\nbase script.<module>/REQUIREMENTS.md: header contract (see above), the rows you are moving or minting\n(same status, new IDs), a summary table.<module>/tests/ and rewrite their ID comments (plan a token-rewrite\nscript; handle shorthand clusters by hand).<modules root>/*/tests/* or equivalent) — in the SAME commit\nas the move, or the gate silently loses the module.req-machines.json (one row per module) and scripts/req-aggregate.mjs (inlined above; add your\nscratch/output dirs to its skip set; adapt the test-file pattern).\"req\": \"node scripts/req-coverage.js && node scripts/<module>/req-coverage.js && node scripts/req-aggregate.mjs\"\n(extend per module).<MOD>-* ID in module tests; a foreign-group row in the\nmodule registry; a root row under a <MOD>- prefix; a REQUIREMENTS.md under the tree that is not\nin the manifest; a root test token mentioning a child prefix; one ID minted in two machines.docs/ideas/ and mint into the module registry only after their gate;\ndeleting a dead candidate = folder + manifest row, nothing else.Worked
\nDidn't / gotchas
\n\\,\ndiscovered dirs normalized back to /) → false \"unregistered machine\" failures. Normalize every path\ncomparison to forward slashes.tmp/ lab folder containing a stray REQUIREMENTS.md\ntripped the aggregator until tmp was skipped. List your scratch/output dirs before the first run.**ID** are invisible to the machine — the\nmanual summary table can silently drift from the machine's row count. Treat the machine's output as\nthe fact, not the table.<ROOT>-<MOD>-01 → new ID) silently misses comment shorthand like\n<ROOT>-<MOD>-02/03/04; enumerate shorthand clusters explicitly before rewriting.tests/ would silently skip module\ntests — extend discovery in the same commit as the move, and keep npm test running everything.req-machines.json,\nscripts/req-aggregate.mjs, the runner discovery pass, the npm chain, the module-registry header\ncontract.What it is. An extension of the requirements-machine dump that turns one project-wide requirements\nregistry into a composition: any module folder becomes a self-contained requirements machine — its own\nregistry, its own tests, its own copy of the coverage script — with the module name as the ID prefix.\nThe root stays aware through a small manifest and a cross-machine checker; a module can be lifted out of\nthe project together with its git history. Every added file is inlined in the raw body, and the base\nmachine is installed first.
\nWhy you would want it. If your project is growing side modules — experimental backends, candidate\nintegrations, a sub-project that may be extracted later — a flat registry forces a bad choice: mint\nrequirement IDs for experiments that die (dead IDs in your one-truth file), or keep obligations outside\nthe machine (drift comes back). With this setup a dying candidate costs one deleted folder and one\nmanifest row; a surviving module carries its contracts, tests and history out of the repo with it. ID\ncollisions between root and module are impossible by construction, not by convention.
\nWhat to watch out for. It layers on the base requirements machine — apply that dump first (or install\nboth together, base first). Experience so far: one pilot split (a module migration with a full ID rename,\nsuite green) followed by about a week of ordinary work, during which the module's registry grew from 9 to\n23 rows (including a speculative 7-row research track) and the root's ID space stayed clean; the coverage\nchain ran on every commit and stayed quiet. Read the honest limits before adopting: the \"seams stay in the\nroot\" rule is about ownership, not a frozen count — the root accrued more host-side rows too; and while the\nfractal's depth (root + child) is proven, its breadth is not — there is still exactly one child, and no\nmodule has actually been extracted into a second repository yet, which is why the dump stays experimental.\nThe rename path uses the base machine's own \"IDs never change — except one human-sanctioned synchronous\ncommit\" rule, so budget one careful commit with a rewrite script. Honesty labels: generated_by: hybrid\n(the human co-designed the rule, the agent implemented), human_review: minimal, trust_level: self-tested. The original project's specifics (its domain, framework and module names) were generalized\nto placeholders, and personal data and a third-party API token from the same session were removed — see\nREDACTIONS.md.
(This is the human door into the raw dump. The body stays machine-first.)
\n" }