This is a self-contained setup guide for the requirements-management half of a\nlong-session OpenCode configuration: a single registry of obligations with stable IDs\nand a test per requirement, a coverage check that reconciles every test with the\nregistry, and an idea process that turns a raw brainstorm into grounded, testable\nrequirements. It is one of two companion dumps. The other, The agent-control loop —\nhttps://kodavr.xyz/dumps/2026-09-18-opencode-agent-control/ — installs the global OpenCode\nloop, the root AGENTS.md digest that points at this registry, and the STATE.md\ncheckpoint; applied together, the two reproduce the combined context-machine-setup guide.
Inspiration: the requirements-management machine was inspired by the Telegram channel\nLLM Under the Hood — https://t.me/llm_under_hood.
\nAll files are stripped of the original project's specifics and given in an initial\nempty state — the mechanisms work, domain data is empty. Paths: ~ = the user's home\ndirectory (C:\\Users\\<name> on Windows), <project> = the root of your repository.
Long agent sessions fail a fifth way: knowledge drifts. An obligation agreed in one\nsession is forgotten or re-litigated in the next; an idea is mistaken for design; the\nsame requirement gets two homes and the two homes diverge. The machine binds the\nobligations to one place:
\nREQUIREMENTS.md registry — stable IDs plus a test per requirement. npm run req reconciles test IDs with the registry before every commit.STATE.md — a checkpoint, not a chronicle. STATE.md itself is installed by the agent-control companion dump; this dump only relies on it.docs/ideas/ — raw brainstorms are hypothesis generators, never design; only grounded branches are minted into registry rows.Everything read at startup stays a pointer and does not grow.
\nCore principles (the requirements side): TDD is mandatory (the contract is fixed\nby a test before implementation); declarativity (an extension point is a file or a\nregistry row, not code); one truth per entity (after minting, the registry owns the\ncontract, not the idea doc); fail-visible (a typo'd ID or a ✅ row without a test fails\nthe coverage check); mechanism not a request (the coverage script holds the contract,\nnot a note in the prompt).
\n<project>/\n ├── REQUIREMENTS.md # single registry: stable IDs + statuses + test links\n ├── package.json # adds the `req` script (base installed by the agent-control dump)\n ├── AGENTS.md # digest: the registry pointer + TDD cycle live here (base)\n ├── AGENTS/\n │ └── requirements.md # registry maintenance protocol (this dump)\n ├── scripts/\n │ └── req-coverage.js # reconcile test IDs with the registry (this dump)\n └── docs/\n └── ideas/ # raw brainstorms and their verdicts\n ├── README.md # idea lifecycle (this dump)\n └── idea-TEMPLATE.md # brainstorm dump template (this dump)\npackage.json, AGENTS.md and .gitignore come from the base agent-control dump; this\ndump adds the registry, its maintenance protocol, the coverage tool and the idea process.
AGENTS.md digest, STATE.md and package.json.REQUIREMENTS.md (§4.5).scripts/req-coverage.js (§4.3) and the req npm script (\"req\": \"node scripts/req-coverage.js\").AGENTS/requirements.md (§4.9) and keep the registry pointer plus the TDD cycle in AGENTS.md (the two sections reproduced under §4.7 below).docs/ideas/README.md and docs/ideas/idea-TEMPLATE.md (§4.15, §4.16).npm run req exits 0 on the empty registry.If you are applying only this dump, make sure steps 1 and 4 hold: AGENTS.md must carry\nthe two sections in §4.7, and package.json must have the req script.
<project>/AGENTS.md — the two sections this dump relies onThe base digest (AGENTS.md) carries the registry pointer and the TDD cycle. They are\nreproduced here because every requirement change depends on them; the full file is\ninstalled by the companion agent-control dump.
REQUIREMENTS.md is the single registry (stable <PREFIX>-<GROUP>-NN + tests;\ndocs/ideas/ — raw material and verdicts). The file can grow large — do not read it entirely:\nsearch with Grep by requirement strings, read the region with Read, coverage — npm run req\nbefore every commit. Maintenance protocol — AGENTS/requirements.md.
npm run req; fix the summary table if statuses changed.<project>/REQUIREMENTS.md (empty registry)# <project> — Requirements\n\nSource: [docs/design.md](docs/design.md). Every requirement has a **stable ID**.\n\n> **Maintenance protocol, structure, tools, and recipes — [AGENTS/requirements.md](AGENTS/requirements.md).**\n> This is the base (registry body). The file can grow large — do not read it entirely without need;\n> search with `Grep` by requirement strings, read the region with `Read`, coverage — `npm run req`.\n\n---\n\n## <Group 1> (§…)\n- ⬜ **<PREFIX>-<GROUP1>-01**: <formulation — one testable line>. *(tests will appear during implementation)*\n\n## <Group 2> (§…)\n- ⬜ **<PREFIX>-<GROUP2>-01**: <formulation>.\n\n---\n\n## Summary\n| Group | Total | ✅ | 🟧 | ⬜ | ⛔ |\n|---|---|---|---|---|---|\n| <Group 1> | 1 | 0 | 0 | 1 | 0 |\n| <Group 2> | 1 | 0 | 0 | 1 | 0 |\n| **Total** | **2** | **0** | **0** | **2** | **0** |\nFormat rules: requirement = exactly one line - <status> **ID**: formulation. *(links/tests)*; statuses ✅ has test · 🟧 partial · ⬜ none · ❓ concept; canceled — DEPRECATED (ID preserved); summary updated in the same commit.
<project>/AGENTS/requirements.md# requirements — requirements registry protocol\n\n> **Base (body): `REQUIREMENTS.md`**. The file can grow large (~tens of KB and above).\n> Do not read it entirely without need. Here is how the base is structured, how to read and edit it.\n\n## How the base is structured\n- **Groups** — `## ` headers.\n- **Requirement** — exactly **one line**: `- <status> **<PREFIX>-<GROUP>-NN**: formulation. *(links/tests)*`.\n- **ID** — `<PREFIX>-<GROUP>-NN`, stable (see \"Maintenance rules\").\n- **Statuses**: ✅ has test · 🟧 partial · ⬜ none · ❓ concept (not directly testable); `DEPRECATED` — canceled.\n- **\"Summary\"** at the end — table of groups × statuses (maintained manually: number of lines = fact).\n- **Ideas** — `docs/ideas/` (raw material + verdicts).\n\nThe format is line-based and greps perfectly: every requirement line starts with `-`. Search with `Grep`.\n\n## Size — warning\nIt is justified to read it entirely only for complex tasks (full analysis of a new idea). Otherwise —\npointedly: `Grep` by keys/IDs → `Read` of the needed region (`offset/limit`).\n\n## Tools\n- `npm run req` (`scripts/req-coverage.js`) — reconcile IDs from tests with the registry; exit 1 on\n typos/unknown IDs. **Before every commit.**\n- `Grep` over `REQUIREMENTS.md` — candidate lines (ID + status + text), without reading the file.\n- `Read` (`offset/limit`) — one region / group / line entirely.\n\n## Recipes\n\n### Bug → reconcile with registry\n1. Symptom → keywords (entity, command, area).\n2. `Grep` the registry → candidates.\n3. `Read` narrow region — full text of the requirement.\n4. `npm run req` + `Grep` over tests — coverage and where the regression lives.\n5. Solution: regression (same ID + new test) / coverage gap (`✅` without test — anomaly) /\n not yet implemented (`⬜`/`🟧`) / **new requirement**.\n\n### New idea (`idea-*.md`) → flat requirements\n1. Read the idea itself (this is the human's input).\n2. For each point — `Grep` related/conflicting requirements (candidates).\n3. Conflict (idea X ↔ requirement ¬X) — **agent's judgment**, not the tool's.\n4. New points → **flatly**: one requirement = one testable formulation; status ⬜;\n ID — next `NN` of the group.\n5. Idea verdict — by `docs/ideas/README.md`.\n\n## Maintenance rules\n1. **IDs never change**: we do not rename, renumber, or delete them.\n Exception — a conscious human decision: registry, tests, and docs are renamed in ONE\n synchronous commit.\n2. `REQUIREMENTS.md` is the **single registry**: stable ID + formulation + status + links to tests.\n3. New requirement → new ID at the end of its group; line with status ⬜ (or ✅ immediately,\n if the test is written in this same change).\n4. Canceled requirement → marked `DEPRECATED`, ID preserved.\n5. **Every test must reference the requirement ID as the first word of the title**:\n `it('<PREFIX>-LLM-04: keys never reach the browser')`. A test without an ID is an overview error;\n an ID without a test — the requirement must not be ✅.\n6. One test can cover multiple requirements: `it('<PREFIX>-LLM-04 + <PREFIX>-SEC-01: ...')`.\n7. Status in the file is updated in the same commit as the test.\n8. When adding — update the summary table at the end of the base.\n9. Refactoring that changes behavior covers existing IDs; new requirements — new IDs.\n<project>/scripts/req-coverage.jsReconciling test IDs with the registry (run before every commit): exit 1 on typos, unknown IDs, and \"✅ without a test\".
\n#!/usr/bin/env node\n// scripts/req-coverage.js — reconcile requirement IDs between REQUIREMENTS.md and tests.\n// Exit 1 on: an ID used in a test but absent from the registry; a ✅ row with no test.\n// Prefix/suffix are project-specific: set PREFIX and TESTS_DIR below.\n\nimport { readFileSync, readdirSync, statSync } from \"node:fs\"\nimport { join } from \"node:path\"\n\nconst ROOT = new URL(\"..\", import.meta.url).pathname\nconst PREFIX = \"WF\" // ← your registry prefix\nconst TESTS_DIR = join(ROOT, \"tests\")\n\nconst registry = readFileSync(join(ROOT, \"REQUIREMENTS.md\"), \"utf8\")\nconst rows = [...registry.matchAll(new RegExp(`^-\\\\s*(✅|🟧|⬜|❓)\\\\s*\\\\*\\\\*(${PREFIX}-[A-Z]+-\\\\d+)\\\\*\\\\*`, \"gm\"))]\n .map((m) => ({ status: m[1], id: m[2] }))\n\nconst files = []\n;(function walk(dir) {\n for (const name of readdirSync(dir)) {\n const p = join(dir, name)\n if (statSync(p).isDirectory()) walk(p)\n else if (/\\.(test|spec)\\.[cm]?[jt]s$/.test(name)) files.push(p)\n }\n})(TESTS_DIR)\n\nconst tested = new Set()\nfor (const f of files) {\n for (const m of readFileSync(f, \"utf8\").matchAll(new RegExp(`${PREFIX}-[A-Z]+-\\\\d+`, \"g\"))) tested.add(m[0])\n}\n\nconst known = new Set(rows.map((r) => r.id))\nconst problems = []\nfor (const id of [...tested].sort()) if (!known.has(id)) problems.push(`test uses unknown ID: ${id}`)\nfor (const r of rows) if (r.status === \"✅\" && !tested.has(r.id)) problems.push(`✅ without a test: ${r.id}`)\n\nif (problems.length) {\n console.error(\"req-coverage FAILED:\\n \" + problems.join(\"\\n \"))\n process.exit(1)\n}\nconsole.log(`req-coverage OK (${rows.length} rows, ${tested.size} IDs tested)`)\n<project>/docs/ideas/README.md# docs/ideas/ — raw brainstorm dumps and their verdicts\n\n## What these files are\nEach file here is an unloading of a wide discussion (a \"mindmap\"): the human brings a seed\n(\"what if...\"), the discussion spreads it across pains, cases, value and candidate\ncontracts, and everything is dumped into an `idea-*.md` file. These documents are\n**hypothesis generators, not design** — their facts about the real system are unverified\nand often wrong. Their value is coverage, not accuracy.\n\n**Start every new dump from [idea-TEMPLATE.md](idea-TEMPLATE.md)** — the skeleton with the\nhard-won rules baked in (append-only branches, the «Ground» section, per-branch verdicts in\nthe Status tail, anti-patterns).\n\n## Active\n<empty for now — list of active ideas with their status>\n\n## The lifecycle (mindmap → code → registry)\n1. **Raw dump.** A new `idea-*.md` lands here with a status header saying it is raw and\n unverified. No requirement exists yet.\n2. **Grounding.** Any branch taken into work must be checked against the REAL code first —\n what exists, what the pipeline actually does, which invariants would block it. Expect to\n reject items as factually wrong.\n3. **Minting.** A grounded idea becomes an **ID row in the registry** (`REQUIREMENTS.md`)\n with a red test written first (TDD) — the working protocol lives in\n [AGENTS/requirements.md](../../AGENTS/requirements.md). After minting, the idea doc is\n no longer the source of truth for that branch — one truth per entity; the registry row +\n its test carry the contract.\n4. **Verdicts stay in the doc.** Every branch that is NOT minted gets an explicit verdict in\n the doc's `Status`/disposition tail:\n - **rejected** — with the reason (false premise, conflicts with a value or invariant,\n costs more than it returns);\n - **deferred** — with the return condition (which brick/blocking must land first).\n Rejected \"chaff\" is NEVER pulled into the registry: no ID, no status churn — the doc\n keeps the reasoning so nobody (human or agent) re-litigates the same idea from scratch.\n5. **Re-taking is fine.** A deferred or partially-minted doc may feed new IDs later; the\n Status tail honestly shows what was taken, when, and as what.\n\n## Rules of thumb\n- The registry holds obligations only; this folder holds exploration and verdicts. Don't\n mirror registry rows here beyond pointers.\n- A mindmap's internal numbering (5.1, 7.3 …) is local to the doc — quote it as\n \"contract 5.2 review\", never as a registry ID.\n- The verdict language: a short, honest sentence beats a taxonomy. When in doubt —\n rejected-with-reason is the safer default; a minted row is a promise to keep a test green\n forever.\n<project>/docs/ideas/idea-TEMPLATE.md# <topic>-idea\n\n**Status:** raw dump — facts about the system are NOT verified\n**Origin:** dump from discussion, <date>; seed: \"<initial human formulation>\"\n\n> **File rule: APPENDED, NOT EDITED.** Branch addresses are eternal anchors\n> (2.4.3 lives forever). Source errors are not erased — the discrepancy \"mindmap vs ground\"\n> is valuable in itself; the history of decisions is read as a protocol, not as a\n> retroactively rewritten plan.\n\n## Mindmap\n\n### 0. Ground (filled on the FIRST analysis — before hypotheses)\n- 0.1 Code mechanics the idea touches (files/modules/invariants — by fact, with paths;\n \"seems\" does not live here).\n- 0.2 Existing requirements (with IDs) that block or help.\n- 0.3 Connections with other ideas in this folder.\n- 0.4 Target slicing group.\n\n### 1. Pain\nEvery statement about the current system is a hypothesis, mark it `[needs ground]` if not verified.\nPain is formulated by the HUMAN, not the model.\n\n### 2. Dependencies (blockers — verify on the ground!)\n\n### 3. Cases (1–3 real user scenarios)\nCases are the main tool for convergence: a real scenario closes forks that\nabstract branches chew on endlessly.\n\n### 4. Value\n\n### 5. Resolved (contracts, do not re-resolve)\nFormulations-obligations. When slicing, they are cut into IDs with a test; after minting, the source\nof truth is the registry, not this file.\n\n### 6. Open questions (closing — by a new branch with a link)\nClosed question = new branch linking to the old one; do not edit the old one.\n\n### 7+. Hypotheses (candidates for moving to a separate idea — mark immediately)\n\n## Entry point for the agent (take into work only by explicit command)\n1. Read the doc entirely; \"Resolved\" branches — contracts, do not re-resolve.\n2. Fill/verify the \"Ground\" against the real code and registry.\n3. The agent proposes requirement and test variants; the word \"we take it\" — the human's.\n4. Verdicts — in the Status tail; code — only after explicit command.\n\n## Status (verdicts by branches — tail, appended, never rewritten)\n- **Accepted:** <branch> → <ID> (<date>)\n- **Rejected:** <branch> → <why, in one honest sentence>\n- **Deferred:** <branch> → <return condition: what brick/blocking is needed>\n\n---\n\n## Anti-patterns (what killed past runs — do not repeat)\n- Fact about code without path/ID → eternal false branch (\"raw material without ground gives false anchors\").\n- Retelling a closed branch instead of linking → duplication of meaning, registry swells.\n- Duplicate ID when throwing in — check the registry, not memory.\n- File rules are stricter than the owner's will — human changes the process, file follows.\n- Hypotheses not marked \"candidate for moving out\" are eaten into the slice and generate garbage requirements.\nnpm run req — exit 0 on the empty registry (no tests yet).npm run req must exit 1 with the offending IDs named.Grep the registry → candidates; Read the narrow region; npm run req + Grep over tests; then decide — regression (same ID + new test), coverage gap (✅ without test — anomaly), not yet implemented (⬜/🟧), or a new requirement.Grep related/conflicting requirements; make the conflict call as an agent, not the tool; mint every new point as one testable row with the next NN of its group and status ⬜; record the verdict per docs/ideas/README.md.REQUIREMENTS.md (requirement lines) and docs/ideas/ (ideas and verdicts).This dump works in tandem with The agent-control loop —\nhttps://kodavr.xyz/dumps/2026-09-18-opencode-agent-control/ — the companion dump that\ninstalls the global OpenCode loop, the compaction sentinel and the lazy layers. Applied\ntogether, the two reproduce the combined context-machine-setup guide in full.
What it is. A reproduction-ready way to keep an agent-driven repository honest about\nwhat it owes: a single REQUIREMENTS.md registry with stable IDs and a test per\nrequirement, an npm run req coverage check that reconciles tests with the registry, a\nmaintenance protocol (AGENTS/requirements.md), and an idea process that turns raw\nbrainstorms into grounded requirements. Every file is inlined. The requirements-management\nmachine was inspired by the Telegram channel LLM Under the Hood\n(https://t.me/llm_under_hood).
Why you would want it. Across long sessions, obligations quietly drift — a rule gets\nforgotten, an idea is mistaken for a design decision, the same requirement appears in\ntwo places and they disagree. This machine gives each obligation exactly one home with a\nstable ID and a green test, fails loudly on a typo'd ID or a ✅ row with no test, and\nforces every brainstorm branch to get an explicit verdict (minted, rejected with a\nreason, or deferred). The registry grows with the project; what is read at startup stays\na pointer.
\nWhat to watch out for. This is the requirements half of a two-dump setup. It works in\ntandem with The agent-control loop (https://kodavr.xyz/dumps/2026-09-18-opencode-agent-control/):\nthe agent-control machinery and the root AGENTS.md digest come from there — apply it first. It is self-tested on one account, not\ncommunity-tested, and the ID prefix, registry groups and test runner are placeholders\nyou set for your project; npm run req must be wired to your test directory. Honesty\nlabels: generated_by: agent, human_review: minimal, trust_level: self-tested.\nPersonal data was removed — see REDACTIONS.md.
(This is the human door into the raw dump. The body stays machine-first.)
\n" }