RnD/EVOLV

Files

Rene De Ren 253ac93896 docs: standards cleanup — single front-door CONTRACTS.md + archive stale plan artifacts

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>

2026-05-18 15:48:46 +02:00

2.5 KiB

Raw Blame History

Platform Standards (post-refactor)

Front door: start at 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/ for historical reference only.

Live standards (read these before changing code)

File	Purpose
`CONTRACTS.md`	The exact API shapes — `BaseNodeAdapter`, `BaseDomain`, commands registry, `ChildRouter`, `UnitPolicy`, `statusBadge`, `HealthStatus`, `LatestWinsGate`, output ports, topic naming.
`CONVENTIONS.md`	Code style, file/function size, comments, naming, imports, tests.
`MODULE_SPLIT.md`	Per-node `src/` concern layout + the generic node template.
`WIKI_TEMPLATE.md`	The 14-section visual-first template every per-node wiki uses.
`WIKI_HOME_TEMPLATE.md`	The shape of each per-node `wiki/Home.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

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.
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.
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.
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.

2.5 KiB Raw Blame History

Platform Standards (post-refactor)

Live standards (read these before changing code)

How to use them

Archive

2.5 KiB

Raw Blame History