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>
This commit is contained in:
Rene De Ren
@@ -1,7 +1,13 @@
|
||||
# Continue here (fresh-context entry point)
|
||||
# Continue here (fresh-context entry point) — ARCHIVED
|
||||
|
||||
**Read this file first** if you're picking up the EVOLV refactor in a fresh
|
||||
session. It points at the durable plan and lists what's left.
|
||||
> [!WARNING]
|
||||
> **ARCHIVED — the refactor described here landed on `development` in May 2026.**
|
||||
> This file describes the *plan* and the *deferred work as of 2026-05-11*. It is
|
||||
> retained for history. For current work, start at [`../../../CONTRACTS.md`](../../../CONTRACTS.md)
|
||||
> (EVOLV root) and the live standards in [`../`](../).
|
||||
|
||||
Original intro: read this file first if you're picking up the EVOLV refactor
|
||||
in a fresh session. It points at the durable plan and lists what's left.
|
||||
|
||||
## Read in order
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
# Task list
|
||||
# Task list — ARCHIVED
|
||||
|
||||
> [!WARNING]
|
||||
> **ARCHIVED — Phases 1–11 landed on `development` in May 2026.**
|
||||
> This file is the original phased plan and is retained for history. For
|
||||
> deferred / open work, see [`../OPEN_QUESTIONS.md`](../OPEN_QUESTIONS.md).
|
||||
> For current standards, start at [`../../../CONTRACTS.md`](../../../CONTRACTS.md) (EVOLV root).
|
||||
|
||||
Phased and ordered. The TaskCreate tracker mirrors this list and is the
|
||||
active, mutable view; this file is the durable plan.
|
||||
@@ -1,82 +1,42 @@
|
||||
# EVOLV Platform Refactor — Guidelines
|
||||
# Platform Standards (post-refactor)
|
||||
|
||||
This directory holds the durable plan and conventions for the platform-wide
|
||||
refactor of the EVOLV Node-RED nodes. Anyone (human or agent) working on
|
||||
this refactor reads these files first.
|
||||
> **Front door:** start at [`CONTRACTS.md`](../../CONTRACTS.md) at the EVOLV root. It maps every contract, rule, and standard in the stack.
|
||||
|
||||
> **Fresh context? Start here:** read **[`CONTINUE_HERE.md`](./CONTINUE_HERE.md)** first.
|
||||
> It explains the current state (Phases 1–11 done, 823 platform tests green),
|
||||
> lists the deferred work in priority order, and points at the specific
|
||||
> `OPEN_QUESTIONS.md` entries that still need action.
|
||||
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.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Eliminate boilerplate** — every nodeClass today is ~80% identical.
|
||||
Move the shared parts into `generalFunctions/`. Each node keeps only
|
||||
what is genuinely node-specific.
|
||||
2. **Split big domain classes** — `pumpingStation`, `machineGroupControl`,
|
||||
and `rotatingMachine` each have ~1000–1800 line monolithic
|
||||
`specificClass.js` files mixing 6+ concerns. Split each into focused
|
||||
concern-based modules under `src/`.
|
||||
3. **Document the contract** — every msg.topic the node accepts and every
|
||||
message it emits is declared in code (a `commands/` module) and
|
||||
surfaced in a per-node `CONTRACT.md`.
|
||||
4. **Standardise naming** — consistent topic names across the platform
|
||||
(`set.<noun>`, `cmd.<verb>`, `evt.<noun>`).
|
||||
5. **Keep it readable** — small files, small functions, comments that say
|
||||
*why* and skip *what*.
|
||||
|
||||
## Constraint: this is the development branch
|
||||
|
||||
All 12 submodules + the parent EVOLV repo are on a `development` branch.
|
||||
`main` is untouched. We can change anything without breaking deployments
|
||||
that track `main`.
|
||||
|
||||
The refactor lands on `development`. Promotion to `main` happens once the
|
||||
whole platform passes its 3-tier tests + Docker E2E.
|
||||
|
||||
## Layered approach
|
||||
|
||||
The refactor is sequenced as **tiers**, not a big bang.
|
||||
|
||||
| Tier | What | Risk | Reversible? |
|
||||
|---|---|---|---|
|
||||
| 1 | Add infra in `generalFunctions` (additive only — no breaking changes) | Low | Yes |
|
||||
| 2 | Pilot one node (pumpingStation) end-to-end on the new infra | Med | Yes |
|
||||
| 3 | Convert remaining core nodes (measurement, MGC, rotatingMachine) | Med | Yes |
|
||||
| 4 | Convert remaining nodes (valve, VGC, reactor, settler, monster, diffuser, dashboardAPI) | Low | Yes |
|
||||
| 5 | Standardise input topic names + deprecation map | Med | Behind feature flag |
|
||||
| 6 | Promote `development` → `main` once Docker E2E green platform-wide | Low | Yes |
|
||||
| 7 | Wiki cleanup — visual-first template + Mermaid diagrams per node (post-refactor) | Low | Yes |
|
||||
|
||||
Each tier is a sequence of small PRs on `development`, each with its
|
||||
existing tests green.
|
||||
|
||||
## Files in this directory
|
||||
## Live standards (read these before changing code)
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `README.md` | This file. |
|
||||
| `CONVENTIONS.md` | Code style, file size, comments, naming, imports, tests. |
|
||||
| `CONTRACTS.md` | The exact shapes — `BaseNodeAdapter`, `BaseDomain`, commands registry, child router, unit policy, status badge, output ports. |
|
||||
| `MODULE_SPLIT.md` | Per-node `src/` layout for the 4 core nodes + a generic template. |
|
||||
| `TASKS.md` | Phased task list. The `TaskCreate` task tree mirrors this and is the active tracker. |
|
||||
| `OPEN_QUESTIONS.md` | Decisions deferred to later — collected here so we don't lose them. |
|
||||
| [`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. |
|
||||
|
||||
## Workflow rules for spawned agents
|
||||
## How to use them
|
||||
|
||||
If you are an agent working on a refactor task:
|
||||
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.
|
||||
|
||||
1. Read this file, `CONVENTIONS.md`, `CONTRACTS.md`, and the relevant
|
||||
section of `MODULE_SPLIT.md` before changing code.
|
||||
2. Stay within the scope of one task. Don't expand scope without flagging.
|
||||
3. Run the affected node's tests after every meaningful change. Commands:
|
||||
```
|
||||
cd nodes/<nodeName> && node --test test/basic test/integration test/edge
|
||||
```
|
||||
4. Don't change `generalFunctions` exports unless your task is in tier 1.
|
||||
5. If you discover something unclear, append it to `OPEN_QUESTIONS.md`
|
||||
with a short note. Do **not** invent a decision.
|
||||
6. Comments: small, function-level, *why* not *what*. See `CONVENTIONS.md`.
|
||||
7. When done, summarise: files changed, tests run, anything deferred to
|
||||
`OPEN_QUESTIONS.md`.
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user