253ac93896
Establish CONTRACTS.md at the EVOLV root as the canonical map of where every contract, rule, and standard lives. Surface it from CLAUDE.md so every fresh agent or colleague lands there first. Reshape .claude/refactor/ to reflect that the platform refactor is done: live standards stay at the top level; the plan artifacts (CONTINUE_HERE.md, TASKS.md) move into Archive/ with WARNING banners. Drop content that drifted out of date or duplicated the new standards stack: - docs/DEVELOPER_GUIDE.md (pre-refactor walkthrough; superseded by wiki/Architecture, wiki/Getting-Started, .claude/rules/node-architecture, .claude/refactor/MODULE_SPLIT + per-node CONTRACT.md + src/commands/). - .agents/decisions/ (15 DECISION files): load-bearing decisions belong in commit messages and PR descriptions; live open items in OPEN_QUESTIONS.md. - .agents/improvements/TOP10_*.md: moved to Archive/. Bump generalFunctions to 49c77f2 — adds CONTRACT.md inside the library: different shape from per-node CONTRACT.md files (library API, not msg.topic), with stability tags and pointers to .claude/refactor/CONTRACTS.md §N. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# 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.
|