EVOLV/.claude/refactor/README.md

# Platform Standards (post-refactor)

> **Front door:** start at [`CONTRACTS.md`](../../CONTRACTS.md) at the EVOLV root. It maps every contract, rule, and standard in the stack.

This directory holds the **live standards** that govern how every EVOLV node
is shaped. They are the source of truth for any human or agent making a
change. The platform refactor that produced them landed on `development` in
May 2026; the plan artifacts that drove it are in [`Archive/`](./Archive/)
for historical reference only.

## Live standards (read these before changing code)

| File | Purpose |
|---|---|
| [`CONTRACTS.md`](./CONTRACTS.md) | The exact API shapes — `BaseNodeAdapter`, `BaseDomain`, commands registry, `ChildRouter`, `UnitPolicy`, `statusBadge`, `HealthStatus`, `LatestWinsGate`, output ports, topic naming. |
| [`CONVENTIONS.md`](./CONVENTIONS.md) | Code style, file/function size, comments, naming, imports, tests. |
| [`MODULE_SPLIT.md`](./MODULE_SPLIT.md) | Per-node `src/` concern layout + the generic node template. |
| [`WIKI_TEMPLATE.md`](./WIKI_TEMPLATE.md) | The 14-section visual-first template every per-node wiki uses. |
| [`WIKI_HOME_TEMPLATE.md`](./WIKI_HOME_TEMPLATE.md) | The shape of each per-node `wiki/Home.md`. |
| [`OPEN_QUESTIONS.md`](./OPEN_QUESTIONS.md) | Live decisions log — append-only. Most entries are resolved; unresolved entries are what's actually in play. |

## How to use them

1. **Reading code in a node.** The node's `CONTRACT.md` and `src/commands/index.js`
   are the per-node contract; the files above are the platform contract those
   per-node files implement.
2. **Writing new code in a node.** Match `MODULE_SPLIT.md` for layout, `CONVENTIONS.md`
   for style, `CONTRACTS.md` for the base-class API surface, and add to
   `OPEN_QUESTIONS.md` if you discover something unclear rather than inventing
   a decision.
3. **Touching `generalFunctions`.** Any new export needs a `CONTRACT.md` entry
   in `nodes/generalFunctions/CONTRACT.md` and, if it introduces a new platform
   shape, a section in `CONTRACTS.md` here.
4. **Updating a wiki page.** Generated sections (topic-contract, data-model)
   are produced by `npm run wiki:all` per submodule — never hand-edit between
   the `BEGIN AUTOGEN` / `END AUTOGEN` markers.

## Archive

[`Archive/`](./Archive/) holds the refactor *plan* (now done): `CONTINUE_HERE.md`,
`TASKS.md`. They describe how the platform got from pre-refactor to the
current shape. They are **not** authoritative for new work — the files above are.