Which data/ files you author, which are produced for you — and the CLIs that run the build. Generated from contract/pipelines.mjs, the same source Claude reads.
Every file in an engagement’s data/ is one of two kinds, and the distinction is the
whole game:
requirements.json,
architectures.json, decisions.json, fillers.json, config.json._site/), and never hand-edited.The danger is editing a build output: your change is silently discarded the next time
the producer runs. So before you touch a data/ file, know which kind it is.
The machine-readable index of every producer is contract/pipelines.mjs (pinned, in
the contract layer). The docs site and this page are both reflections of it — the
solutions/research-index entries are derived from assemble.mjs’s own paths, so they
can’t drift. When in doubt, read that file.
| Output | Built from | Producer |
|---|---|---|
data/solutions.json |
data/solutions/<key>.yaml (one per solution) + _index.yaml |
assemble.mjs |
data/research-index.json |
data/rounds/<id>.yaml (one per round) + data/research-index.yaml |
assemble.mjs |
requirements.md |
requirements.json (regenerates the Gate/Fit/Risk tables from criteria[]) |
generate-requirements-md.mjs |
data/landscape.json |
research/landscape-results.json (the raw survey) |
build-landscape.mjs (per-engagement) |
The first two are the sharding projection (Plan 24): once solutions.json /
research-index.json outgrow hand-editing, they become generated artifacts assembled
from per-record YAML shards — the shards are the source of truth. The assembler is
additive: a no-op on an instance that still ships monolithic JSON.
author shards / JSON → assemble + generate → validate → 11ty build → served _site/
(code time) (build outputs) (gate) (cockpit)
data-edit.mjs (it auto-assembles after each change).assemble.mjs assemble data rebuilds the served monoliths from shards.validate.mjs data: shape (Ajv 2020) + semantics (cross-refs) + the
MR-5 doc-lint (every field carries a description — that’s what makes the field
reference generatable)._site/.All run from the engagement root; the contract CLIs live in the pinned _methodology
submodule.
validate.mjs <data> — full validation. --lint-only runs just the schema
doc-lint.assemble.mjs <assemble|explode|verify> [dataDir] — assemble (shards → JSON,
the build step), explode (JSON → shards, one-shot migration), verify (round-trip
check that the live shards assemble losslessly).data-edit.mjs <show|set-score|set-coverage|set-knowledge|add-fact> … — the
surgical editor over the shards, for the fiddly-shape edits, auto-assembling after each.Adding a new producer? Declare it in contract/pipelines.mjs (or, if its paths come from
code, derive them there) — the reference and this page pick it up automatically.
Every build-time output, its sources, and the command that produces it. derived entries are read straight from assemble.mjs's own paths; declared ones live in the manifest.
data/solutions.json
derived
The Phase-4 candidate compositions. Authored as one YAML shard per solution; assembled into the served JSON at build time.
data/solutions/<key>.yamlOne file per solution — a single system[] record. This is where an individual solution is authored.data/solutions/_index.yamlManifest — the wrapper keys (e.g. _comment) plus the solution order, for deterministic reassembly.run node _methodology/contract/assemble.mjs assemble data
data/research-index.json
derived
The append-only research ledger. Authored as one YAML shard per research round; assembled into the served JSON at build time.
data/rounds/<id>.yamlOne file per research round — that round's narrative plus just the facts bucketed to it.data/research-index.yamlBase — everything except research + facts, plus a _researchOrder manifest.run node _methodology/contract/assemble.mjs assemble data
requirements.md
declared
The human-readable requirements.md — its Gate / Fit-by-area / Risk tables are regenerated from criteria[] so they can't drift. Never hand-edit the .md.
requirements.jsonThe single authored input — mission, narrative, values, criteria[].run node scripts/generate-requirements-md.mjs
data/landscape.json
declaredper-engagement
The neutral landscape.json the Tools view reads — a deterministic transform of the raw survey. Per-engagement (ehimare ships it; not yet generic in template/).
research/landscape-results.jsonThe raw, un-scored tool survey (profiles + gate verdicts).run node scripts/build-landscape.mjs
Run from the engagement root; the contract CLIs live in the pinned _methodology submodule.
validate.mjsValidate an engagement's data: shape (JSON Schema 2020-12 via Ajv) + semantics (cross-refs) + an MR-5 doc-lint (every field carries a description).
| Command | What it does |
|---|---|
node _methodology/contract/validate.mjs <data> |
Full validation of the <data> directory. |
node _methodology/contract/validate.mjs --lint-only |
Schema doc-lint only — assert every field has a description. |
assemble.mjsThe shard ⇄ monolith projection (Plan 24). Additive: a no-op on an instance that ships no shards.
| Command | What it does |
|---|---|
… assemble [dataDir] |
YAML shards → data/*.json. The build step; run before validate + 11ty. |
… explode [dataDir] |
data/*.json → YAML shards. One-shot migration to sharded authoring. |
… verify [dataDir] |
Round-trip check — the live shards assemble losslessly. |
data-edit.mjsSurgical editor over the YAML shards — the fiddly-shape edits (score/coverage/knowledge cells, cross-file fact links), auto-assembling after each change.
| Command | What it does |
|---|---|
data-edit.mjs show <solKey> |
Print one solution shard. |
data-edit.mjs set-score <solKey> <crit> <val> [--note --confidence --facts] |
Set a criterion score. |
data-edit.mjs set-coverage <solKey> <crit> <cov> […] |
Set a coverage cell. |
data-edit.mjs set-knowledge <solKey> <facet> <lvl> […] |
Set a knowledge facet. |
data-edit.mjs add-fact <factId> --research <round> --claim … […] |
Add a fact to a round shard. |