docs: retire repo-mem MCP, migrate skills to .claude/skills, audit fixes
- Delete .mcp.json + .claude/rules/repo-mem.md; drop .repo-mem from .gitignore - Remove repo-mem / substrate_score / repo_search references from all .md - Move 15 EVOLV skills from .agents/skills/ to .claude/skills/ so they are auto-discovered by the Claude Code harness and invokable via the Skill tool - Retire .agents/skills/evolv-orchestrator (duplicate of the subagent at .claude/agents/evolv-orchestrator.md); orchestrator lives as a subagent only - Drop OpenAI-format agent yaml metadata from each skill (not needed for CC) - Update CLAUDE.md, CONTRACTS.md, AGENTS.md to point at the new locations and disambiguate skills (.claude/skills/) vs subagents (.claude/agents/) - Fix CLAUDE.md tick-loop wording (opt-in per-node, not a fixed 1000ms) - Widen .claude/rules/ paths frontmatter so node-architecture and telemetry rules trigger on more relevant files; add frontmatter to flow-layout rule - Bump CONTRACTS.md review date to 2026-05-19; add step 7 to the contract- change workflow (review example flows when topic usage changes) - Bump nodes/generalFunctions pin (Home.md substrate_score reference removed) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
@@ -41,8 +41,8 @@ You are a biological process engineer specializing in wastewater treatment model
|
||||
- `.agents/function-anchors/monster/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-biological-process-engineering/SKILL.md`
|
||||
- `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.claude/skills/evolv-biological-process-engineering/SKILL.md`
|
||||
- `.claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Kinetic rates have correct temperature compensation
|
||||
@@ -53,4 +53,4 @@ You are a biological process engineer specializing in wastewater treatment model
|
||||
- [ ] Retention times consistent with reactor geometry and flow
|
||||
|
||||
## Reasoning Difficulty: Very High
|
||||
This agent handles ASM kinetics, mass balance calculations, temperature compensation, and sludge settling models — some of the most complex scientific reasoning in the platform. Incorrect stoichiometric coefficients, missed temperature corrections, or flawed mass balance closures can propagate silently through reactor simulations. When uncertain, consult `third_party/docs/asm-models.md`, `third_party/docs/settling-models.md`, and `.agents/skills/evolv-biological-process-engineering/SKILL.md` before making claims about biological process behavior.
|
||||
This agent handles ASM kinetics, mass balance calculations, temperature compensation, and sludge settling models — some of the most complex scientific reasoning in the platform. Incorrect stoichiometric coefficients, missed temperature corrections, or flawed mass balance closures can propagate silently through reactor simulations. When uncertain, consult `third_party/docs/asm-models.md`, `third_party/docs/settling-models.md`, and `.claude/skills/evolv-biological-process-engineering/SKILL.md` before making claims about biological process behavior.
|
||||
|
||||
@@ -43,9 +43,9 @@ You are a commissioning and compliance specialist for the EVOLV wastewater treat
|
||||
- Mode changes (auto→manual, simulation→physical) are compliance-relevant events
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
|
||||
- `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
- `.claude/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.claude/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
|
||||
- `.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Compliance-relevant output fields unchanged (or migration documented)
|
||||
@@ -56,4 +56,4 @@ You are a commissioning and compliance specialist for the EVOLV wastewater treat
|
||||
- [ ] Control-action traceability maintained through the change
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles regulatory compliance context, audit trail requirements, and simulation-to-field validation gaps. Dutch wastewater regulations (Waterschapswet, EU UWWTD) have specific monitoring and reporting obligations that code changes can inadvertently violate. When uncertain, consult `third_party/docs/wastewater-compliance-nl.md` and `.agents/skills/evolv-commissioning-validation/SKILL.md` before making claims about compliance requirements.
|
||||
This agent handles regulatory compliance context, audit trail requirements, and simulation-to-field validation gaps. Dutch wastewater regulations (Waterschapswet, EU UWWTD) have specific monitoring and reporting obligations that code changes can inadvertently violate. When uncertain, consult `third_party/docs/wastewater-compliance-nl.md` and `.claude/skills/evolv-commissioning-validation/SKILL.md` before making claims about compliance requirements.
|
||||
|
||||
@@ -29,7 +29,7 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- Canonical internal units: Pa, m³/s, W, K
|
||||
|
||||
## Workflow
|
||||
1. Read `.agents/skills/evolv-orchestrator/SKILL.md` for full orchestration protocol
|
||||
1. Read `.claude/skills/evolv-orchestrator/SKILL.md` for full orchestration protocol
|
||||
2. Build an impact map: which nodes, contracts, and shared modules are affected?
|
||||
3. Identify the minimum set of specialist agents needed
|
||||
4. Decompose into sequenced subtasks with clear acceptance criteria
|
||||
@@ -44,7 +44,7 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- `CONTRACTS.md` (EVOLV root) — front-door map: where every contract, rule, and standard lives
|
||||
- `.claude/refactor/CONTRACTS.md` — platform API shapes (BaseDomain, BaseNodeAdapter, commands registry, …)
|
||||
- `.claude/refactor/OPEN_QUESTIONS.md` — live decisions log
|
||||
- `.agents/skills/evolv-orchestrator/SKILL.md` — Full orchestration protocol
|
||||
- `.claude/skills/evolv-orchestrator/SKILL.md` — Full orchestration protocol
|
||||
- `.agents/AGENTS.md` — Agent invocation policy and routing table
|
||||
- `.agents/improvements/IMPROVEMENTS_BACKLOG.md` — Deferred improvements
|
||||
|
||||
@@ -55,4 +55,4 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- Owner-approved defaults: compatibility=controlled, safety=availability-first
|
||||
|
||||
## Reasoning Difficulty: Medium-High
|
||||
This agent handles multi-domain task decomposition, cross-cutting impact analysis, and decision governance enforcement. The primary challenge is correctly mapping changes across node boundaries — a single modification can cascade through parent-child relationships, shared contracts, and InfluxDB semantics. When uncertain about cross-domain impact, consult `.agents/skills/evolv-orchestrator/SKILL.md` and `.agents/AGENTS.md` before routing to specialist agents.
|
||||
This agent handles multi-domain task decomposition, cross-cutting impact analysis, and decision governance enforcement. The primary challenge is correctly mapping changes across node boundaries — a single modification can cascade through parent-child relationships, shared contracts, and InfluxDB semantics. When uncertain about cross-domain impact, consult `.claude/skills/evolv-orchestrator/SKILL.md` and `.agents/AGENTS.md` before routing to specialist agents.
|
||||
|
||||
@@ -45,7 +45,7 @@ dashboardAPI, diffuser, machineGroupControl, measurement, monster, pumpingStatio
|
||||
- `nodes/generalFunctions/src/*/` — Individual module directories
|
||||
|
||||
## Reference Skills
|
||||
- All `.agents/skills/` depending on which module is being changed:
|
||||
- All `.claude/skills/` depending on which module is being changed:
|
||||
- predict/interpolation/loadCurve → `evolv-mechanical-rotating-equipment`
|
||||
- MeasurementContainer/nrmse/convert → `evolv-instrumentation-assets`
|
||||
- outputUtils → `evolv-database-influx-architecture`
|
||||
@@ -59,4 +59,4 @@ dashboardAPI, diffuser, machineGroupControl, measurement, monster, pumpingStatio
|
||||
- Prefer additive changes (new exports) over breaking changes (renamed/removed exports)
|
||||
|
||||
## Reasoning Difficulty: Medium-High
|
||||
This agent manages a shared library consumed by all 13 nodes. Individual module changes are often straightforward, but the cross-node impact analysis is challenging — a subtle behavior change in interpolation or predict can cascade through rotatingMachine, pumpingStation, and machineGroupControl simultaneously. When uncertain about impact scope, grep for imports across `nodes/*/src/` and consult the relevant `.agents/skills/` for the module being changed.
|
||||
This agent manages a shared library consumed by all 13 nodes. Individual module changes are often straightforward, but the cross-node impact analysis is challenging — a subtle behavior change in interpolation or predict can cascade through rotatingMachine, pumpingStation, and machineGroupControl simultaneously. When uncertain about impact scope, grep for imports across `nodes/*/src/` and consult the relevant `.claude/skills/` for the module being changed.
|
||||
|
||||
@@ -43,8 +43,8 @@ You are an instrumentation engineer specializing in sensor measurement, signal c
|
||||
- `.agents/function-anchors/measurement/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-instrumentation-assets/SKILL.md`
|
||||
- `.agents/skills/evolv-measurement-product-specialist/SKILL.md`
|
||||
- `.claude/skills/evolv-instrumentation-assets/SKILL.md`
|
||||
- `.claude/skills/evolv-measurement-product-specialist/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Unit conversions chain correctly (no double-conversion)
|
||||
@@ -55,4 +55,4 @@ You are an instrumentation engineer specializing in sensor measurement, signal c
|
||||
- [ ] MeasurementContainer fields populated consistently
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles signal processing, NRMSE-based drift detection, sensor behavior modeling, and data quality propagation. Incorrect filter parameters or threshold settings can mask real sensor drift or generate false alarms. When uncertain, consult `third_party/docs/signal-processing-sensors.md` and `.agents/skills/evolv-instrumentation-assets/SKILL.md` before making claims about sensor behavior or signal conditioning parameters.
|
||||
This agent handles signal processing, NRMSE-based drift detection, sensor behavior modeling, and data quality propagation. Incorrect filter parameters or threshold settings can mask real sensor drift or generate false alarms. When uncertain, consult `third_party/docs/signal-processing-sensors.md` and `.claude/skills/evolv-instrumentation-assets/SKILL.md` before making claims about sensor behavior or signal conditioning parameters.
|
||||
|
||||
@@ -50,9 +50,9 @@ You are a mechanical and process engineer specializing in rotating equipment, hy
|
||||
- `.agents/function-anchors/valve/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md`
|
||||
- `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
- `.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md`
|
||||
- `.claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Unit conversions use canonical system (Pa, m³/s, W, K internally)
|
||||
@@ -63,4 +63,4 @@ You are a mechanical and process engineer specializing in rotating equipment, hy
|
||||
- [ ] System curve intersection validated for duty point calculations
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles physics validation involving affinity laws, pump curve theory, system curve intersections, and unit system rigor. Errors in hydraulic calculations or VFD scaling can produce physically impossible results that look numerically plausible. When uncertain, consult `third_party/docs/pump-affinity-laws.md`, `third_party/docs/pid-control-theory.md`, and `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md` before making claims about mechanical behavior.
|
||||
This agent handles physics validation involving affinity laws, pump curve theory, system curve intersections, and unit system rigor. Errors in hydraulic calculations or VFD scaling can produce physically impossible results that look numerically plausible. When uncertain, consult `third_party/docs/pump-affinity-laws.md`, `third_party/docs/pid-control-theory.md`, and `.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md` before making claims about mechanical behavior.
|
||||
|
||||
@@ -38,8 +38,8 @@ You are a Node-RED runtime and editor specialist for the EVOLV platform. You und
|
||||
- `nodes/generalFunctions/` — Shared utilities (MenuManager, configManager, logger, etc.)
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-frontend-node-red/SKILL.md` — Detailed Node-RED frontend patterns
|
||||
- `.agents/skills/evolv-process-systems-control/SKILL.md` — Control architecture and topic contracts
|
||||
- `.claude/skills/evolv-frontend-node-red/SKILL.md` — Detailed Node-RED frontend patterns
|
||||
- `.claude/skills/evolv-process-systems-control/SKILL.md` — Control architecture and topic contracts
|
||||
|
||||
## Rules
|
||||
- Never put `RED.*` calls in specificClass — that's nodeClass territory
|
||||
@@ -48,4 +48,4 @@ You are a Node-RED runtime and editor specialist for the EVOLV platform. You und
|
||||
- Always check `generalFunctions` MenuManager/configManager when modifying config flows
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
Node-RED patterns are well-documented with clear conventions. The main risk is editor/runtime synchronization — changes to admin endpoints, HTML forms, or registration patterns can silently break the editor without runtime errors. When uncertain, consult `.agents/skills/evolv-frontend-node-red/SKILL.md` and the Node-RED documentation before making structural changes.
|
||||
Node-RED patterns are well-documented with clear conventions. The main risk is editor/runtime synchronization — changes to admin endpoints, HTML forms, or registration patterns can silently break the editor without runtime errors. When uncertain, consult `.claude/skills/evolv-frontend-node-red/SKILL.md` and the Node-RED documentation before making structural changes.
|
||||
|
||||
@@ -35,8 +35,8 @@ You are an OT/IT security and edge integration specialist for the EVOLV industri
|
||||
- Watchdog timers for connection health monitoring
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-ot-it-security/SKILL.md`
|
||||
- `.agents/skills/evolv-ot-edge-plc-integration/SKILL.md`
|
||||
- `.claude/skills/evolv-ot-it-security/SKILL.md`
|
||||
- `.claude/skills/evolv-ot-edge-plc-integration/SKILL.md`
|
||||
|
||||
## Scope
|
||||
- Admin endpoints (`GET /<nodeName>/menu.js`, `GET /<nodeName>/configData.js`)
|
||||
@@ -55,4 +55,4 @@ You are an OT/IT security and edge integration specialist for the EVOLV industri
|
||||
- [ ] Control messages validated before actuator commands are issued
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles industrial threat modeling, OT protocol security, and fail-safe analysis. Security in industrial systems has physical safety implications — a missed input validation on a control message could lead to unsafe actuator commands. When uncertain, consult `third_party/docs/ot-security-iec62443.md` and `.agents/skills/evolv-ot-it-security/SKILL.md` before making claims about security boundaries or protocol safety.
|
||||
This agent handles industrial threat modeling, OT protocol security, and fail-safe analysis. Security in industrial systems has physical safety implications — a missed input validation on a control message could lead to unsafe actuator commands. When uncertain, consult `third_party/docs/ot-security-iec62443.md` and `.claude/skills/evolv-ot-it-security/SKILL.md` before making claims about security boundaries or protocol safety.
|
||||
|
||||
@@ -49,8 +49,8 @@ node --test nodes/<nodeName>/test/edge/*.test.js
|
||||
- `nodes/*/examples/` — Example flows
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-quality-technical-debt/SKILL.md`
|
||||
- `.agents/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.claude/skills/evolv-quality-technical-debt/SKILL.md`
|
||||
- `.claude/skills/evolv-commissioning-validation/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] All 3 test tiers present (basic/integration/edge)
|
||||
@@ -62,4 +62,4 @@ node --test nodes/<nodeName>/test/edge/*.test.js
|
||||
- [ ] Code complexity reasonable (no god functions, clear naming)
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
Test patterns are straightforward and the 3-tier structure provides clear guidance. The harder challenge is cross-node regression detection — a change in generalFunctions can silently break downstream nodes whose tests still pass in isolation. When uncertain, consult `.agents/skills/evolv-quality-technical-debt/SKILL.md` and `.agents/function-anchors/` for behavioral contracts before writing or modifying tests.
|
||||
Test patterns are straightforward and the 3-tier structure provides clear guidance. The harder challenge is cross-node regression detection — a change in generalFunctions can silently break downstream nodes whose tests still pass in isolation. When uncertain, consult `.claude/skills/evolv-quality-technical-debt/SKILL.md` and `.agents/function-anchors/` for behavioral contracts before writing or modifying tests.
|
||||
|
||||
@@ -45,8 +45,8 @@ You are a telemetry and database specialist for the EVOLV platform, focusing on
|
||||
- `.agents/function-anchors/dashboardAPI/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-database-influx-architecture/SKILL.md`
|
||||
- `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
|
||||
- `.claude/skills/evolv-database-influx-architecture/SKILL.md`
|
||||
- `.claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Tags are low-cardinality only (no timestamps, UUIDs, free-text)
|
||||
@@ -57,4 +57,4 @@ You are a telemetry and database specialist for the EVOLV platform, focusing on
|
||||
- [ ] Retention policy matches data criticality and storage constraints
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
InfluxDB schema design is well-understood, and the Port 1 telemetry contract is consistent across nodes. The main risk area is cardinality management — adding a high-cardinality tag can silently degrade query performance until it becomes critical. When uncertain, consult `third_party/docs/influxdb-schema-design.md` and `.agents/skills/evolv-database-influx-architecture/SKILL.md` before making schema changes.
|
||||
InfluxDB schema design is well-understood, and the Port 1 telemetry contract is consistent across nodes. The main risk area is cardinality management — adding a high-cardinality tag can silently degrade query performance until it becomes critical. When uncertain, consult `third_party/docs/influxdb-schema-design.md` and `.claude/skills/evolv-database-influx-architecture/SKILL.md` before making schema changes.
|
||||
|
||||
@@ -211,7 +211,7 @@ post-refactor shape, not the in-flight transition).
|
||||
|
||||
| # | Task | Notes |
|
||||
|---|---|---|
|
||||
| 9.1 | Author the canonical wiki template at `.claude/refactor/WIKI_TEMPLATE.md` (or the repo-mem rule path) | Source of truth. |
|
||||
| 9.1 | Author the canonical wiki template at `.claude/refactor/WIKI_TEMPLATE.md` | Source of truth. |
|
||||
| 9.2 | Build the auto-generator: `commands/index.js` → "Topic contract" markdown section | Run via a small `npm run wiki:contract` script per node. |
|
||||
| 9.3 | Pilot on `pumpingStation` wiki: replace existing pages with the new template | Visual-first, prune prose. |
|
||||
| 9.4 | Apply to other 3 core nodes (`measurement`, `MGC`, `rotatingMachine`) | |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/*.js"
|
||||
- "nodes/*/*.html"
|
||||
- "nodes/*/src/**"
|
||||
---
|
||||
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/examples/**"
|
||||
- "examples/**"
|
||||
---
|
||||
|
||||
# Node-RED Flow Layout Rules
|
||||
|
||||
How to lay out a multi-tab Node-RED demo or production flow so it is readable, debuggable, and trivially extendable. These rules apply to anything you build with `examples/` flows, dashboards, or production deployments.
|
||||
|
||||
@@ -1,80 +0,0 @@
|
||||
# repo-mem MCP Tools
|
||||
|
||||
This repo has a per-repo memory MCP server (`repo-mem`) wired via `.mcp.json`. It exposes 5 tools backed by a Hopfield substrate trained on EVOLV's source plus a BM25 index over file chunks. **Use them. They are faster and better-targeted than `grep` for concept queries, and they accumulate institutional memory of repairs.**
|
||||
|
||||
If `/mcp` does not list `repo-mem` as Connected, the rest of this file does not apply for this session — fall back to `grep` / `Read`.
|
||||
|
||||
## When to call which tool
|
||||
|
||||
### `repo_search(query, k=8)` — primary lookup tool
|
||||
Use **before** `grep` / `find` / `Explore` agent for any natural-language "where is X handled / find all places that do Y / what code implements Z" question.
|
||||
|
||||
- ✅ "where is the predicted volume integrator?" → `repo_search`
|
||||
- ✅ "find places that emit InfluxDB line protocol" → `repo_search`
|
||||
- ❌ "find every occurrence of `_updatePredictedVolume`" → `grep` (exact symbol — BM25 doesn't beat grep at exact-string lookup)
|
||||
- ❌ "list all `.test.js` files" → `find` / `ls` (no concept query)
|
||||
|
||||
Returns top-K files with `file:line` ranges and snippets. Read the snippet first; only open the file if the snippet doesn't answer the question.
|
||||
|
||||
### `repo_similar_fixes(query, failure?, files?, tags?, k=5)` — start-of-task context
|
||||
Call at the **start** of any non-trivial bug fix or behavioral change. Cheap (BM25 + file overlap + atom cosine), zero downside if it returns nothing useful.
|
||||
|
||||
- Pass the user's task description as `query`.
|
||||
- If there's a failing test or stack trace, pass it as `failure`.
|
||||
- If you already know which files are involved, pass them as `files`.
|
||||
- Skim the returned traces; surface any near-match to the user before starting.
|
||||
|
||||
### `repo_record_fix({task, failure, files, diff_summary, patch, tests, outcome, tags})` — end-of-task persist
|
||||
Call at the **end** of a landed fix or behavioral change, **before** reporting completion to the user. Skip for trivial typo/comment commits. Required fields: `task` and `outcome`. Recommended:
|
||||
- `failure`: the symptom that prompted the work (test output, user description, stack trace).
|
||||
- `files`: the files actually changed.
|
||||
- `diff_summary`: 1–3 sentences on *what* changed and *why*.
|
||||
- `patch`: the unified diff (truncate to the load-bearing hunks if huge).
|
||||
- `tests`: the verification command(s) you ran.
|
||||
- `outcome`: `passed` / `failed` / `partial` / `reverted`.
|
||||
- `tags`: short labels (`overflow-clamp`, `tokenizer`, `migration`, etc.) for retrieval bias.
|
||||
|
||||
Rule of thumb: if the change took more than one read+edit pair, record it.
|
||||
|
||||
### `substrate_score(text, worst_k=5)` — OOD-token check
|
||||
Use **sparingly**. After generating a non-trivial code block (≥ ~30 lines of new logic, not test scaffolding), pass it through `substrate_score` and inspect the worst-confidence positions for typos, wrong identifiers, or out-of-house style. Noisy on small additions — don't use it for one-line tweaks.
|
||||
|
||||
### `substrate_top_next(context, k=10)` — rarely
|
||||
Predicts next BPE-subword tokens in the local style. Mostly useful for autonomous solver loops; in interactive review it's diagnostic only. If you find yourself wanting it, you probably want `repo_search` instead.
|
||||
|
||||
## Workflow shape
|
||||
|
||||
```
|
||||
new task arrives
|
||||
↓
|
||||
repo_similar_fixes(query=user_task) ← cheap, always do this for non-trivial tasks
|
||||
↓
|
||||
repo_search(query=concept) ← when scoping
|
||||
↓
|
||||
[normal Read / Edit / Bash work]
|
||||
↓
|
||||
[after generating non-trivial new code]
|
||||
substrate_score(text=new_block) ← optional, only if block is big
|
||||
↓
|
||||
[verify: tests / build / smoke]
|
||||
↓
|
||||
repo_record_fix({...}) ← before final user-facing summary
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- ❌ Calling `repo_search` when you already know the file path. Just `Read` it.
|
||||
- ❌ Calling `repo_record_fix` after every micro-edit. Only at meaningful task boundaries.
|
||||
- ❌ Treating `substrate_top_next` results as authoritative — they reflect repo style, not correctness.
|
||||
- ❌ Passing the full conversation to `substrate_score` — it's per-snippet, not per-session.
|
||||
|
||||
## Refresh model
|
||||
|
||||
The post-commit hook auto-runs `--quick --lock` (re-ingest + BM25 + chunk re-embed; substrate retrain skipped) so retrieval stays current within ~2 s of any commit. The substrate itself is only retrained when you (or a maintainer) run `--full` manually:
|
||||
|
||||
```bash
|
||||
node ~/anchor-net-master/tools/repo-mem/refresh.mjs \
|
||||
--repo . --in .repo-mem --full
|
||||
```
|
||||
|
||||
Re-train when the repo gains substantially new vocabulary (new node, new domain, new dependency surface). Otherwise BM25 + existing atoms keep up.
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/src/nodeClass.js"
|
||||
- "nodes/*/src/specificClass.js"
|
||||
- "nodes/*/src/output/**"
|
||||
- "nodes/generalFunctions/src/outputUtils/**"
|
||||
---
|
||||
|
||||
# Telemetry Rules
|
||||
|
||||
54
.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md
Normal file
54
.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-alarms-interlocks-permissives
|
||||
description: Design and review alarms, interlocks, and permissive logic for EVOLV control nodes. Use when implementing trip conditions, permissive checks, startup/shutdown guards, alarm priorities, latching/reset behavior, and operator-facing fault handling.
|
||||
---
|
||||
|
||||
# EVOLV Alarms Interlocks Permissives
|
||||
|
||||
## Mission
|
||||
Make alarm and interlock behavior explicit, testable, and operationally safe while preserving availability-first policy bounds.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build alarm/interlock map from current node contracts and state logic.
|
||||
- Define invariants before edits:
|
||||
- trips/permissives are deterministic
|
||||
- latching/reset behavior is explicit
|
||||
- operator-visible diagnostics are preserved
|
||||
- Validate with sequence and fail-state tests.
|
||||
|
||||
## Scope
|
||||
- `nodes/pumpingStation/`
|
||||
- `nodes/machineGroupControl/`
|
||||
- `nodes/rotatingMachine/`
|
||||
- Any node with mode/state transitions and protective actions
|
||||
|
||||
## Workflow
|
||||
1. Enumerate alarm conditions and priority/severity.
|
||||
2. Define interlock and permissive truth tables.
|
||||
3. Verify startup/shutdown/emergency sequences.
|
||||
4. Confirm reset, auto-recovery, and manual acknowledgement behavior.
|
||||
5. Ensure outputs expose actionable fault context.
|
||||
|
||||
## Standards
|
||||
- Avoid hidden permissives; every gate should be observable.
|
||||
- Keep alarm naming stable and semantically clear.
|
||||
- Separate advisory warnings from trip-level protection.
|
||||
- Preserve controlled compatibility for released fault topics.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- trip activation and reset/latch behavior
|
||||
- permissive-denied and permissive-restored transitions
|
||||
- out-of-order signal handling in sequence transitions
|
||||
- degraded sensor quality paths and alarm escalation
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- alarm/interlock/permissive matrix
|
||||
- changed files/tests and evidence
|
||||
- unresolved protection-vs-availability tradeoffs
|
||||
|
||||
Decision interview triggers:
|
||||
- changed trip thresholds or permissive logic with operational impact
|
||||
- altered reset authority (auto vs manual)
|
||||
- alarm contract changes affecting external consumers
|
||||
54
.claude/skills/evolv-biological-process-engineering/SKILL.md
Normal file
54
.claude/skills/evolv-biological-process-engineering/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-biological-process-engineering
|
||||
description: Engineer biological wastewater process behavior for EVOLV nodes. Use when implementing or reviewing reactor/settler biology, ASM-style kinetics, oxygen demand, nitrification/denitrification, sludge behavior, calibration assumptions, and biologically plausible constraints.
|
||||
---
|
||||
|
||||
# EVOLV Biological Process Engineering
|
||||
|
||||
## Mission
|
||||
Keep EVOLV biological process models physically plausible, calibratable, and operationally useful.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Ground changes in current biology/state variables and connected control topics.
|
||||
- Define invariants before edits:
|
||||
- biological mass-balance intent is preserved
|
||||
- model assumptions remain explicit and traceable
|
||||
- degraded behavior remains availability-first and bounded
|
||||
- Validate with deterministic tests and representative operating scenarios.
|
||||
|
||||
## Scope
|
||||
- `nodes/reactor/`
|
||||
- `nodes/settler/`
|
||||
- `nodes/pumpingStation/` (where biology interacts with flow/retention assumptions)
|
||||
- Related reaction modules and utilities under `nodes/*/src/`
|
||||
|
||||
## Workflow
|
||||
1. Identify biological state variables, units, and expected ranges.
|
||||
2. Map kinetic pathways (growth, decay, transfer, conversion) and rate constraints.
|
||||
3. Verify oxygen/temperature dependencies and fallback behavior.
|
||||
4. Check integration stability for configured time-step and resolution choices.
|
||||
5. Confirm outputs remain interpretable for control and dashboard consumers.
|
||||
|
||||
## Standards
|
||||
- Keep state vectors explicit and index mappings documented.
|
||||
- Avoid silent clipping/coercion without test coverage and rationale.
|
||||
- Preserve topic/payload compatibility unless migration is defined.
|
||||
- Record calibration assumptions and required field data.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- kinetic branch behavior under representative and boundary conditions
|
||||
- non-negativity and boundedness safeguards
|
||||
- temperature and oxygen transfer sensitivity
|
||||
- time-step/resolution edge behavior and stability warnings
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- biological assumptions and constraints used
|
||||
- changed files/tests and evidence
|
||||
- calibration notes and unresolved biological uncertainties
|
||||
|
||||
Decision interview triggers:
|
||||
- altered biology assumptions that can change plant behavior
|
||||
- parameter/default changes with startup or compliance impact
|
||||
- compatibility breaks in biological outputs or topic contracts
|
||||
54
.claude/skills/evolv-commissioning-validation/SKILL.md
Normal file
54
.claude/skills/evolv-commissioning-validation/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-commissioning-validation
|
||||
description: Plan and verify EVOLV commissioning readiness. Use when defining FAT/SAT test plans, acceptance criteria, loop checks, simulation-to-field validation, startup sequencing evidence, and rollout gates for operational deployment.
|
||||
---
|
||||
|
||||
# EVOLV Commissioning Validation
|
||||
|
||||
## Mission
|
||||
Convert implementation changes into deployment-ready evidence with clear acceptance gates.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from impacted contracts, modes, and site-operational constraints.
|
||||
- Define invariants before edits:
|
||||
- validation criteria are measurable and reproducible
|
||||
- startup and failover behavior is proven, not assumed
|
||||
- rollback path is explicit
|
||||
- Produce evidence artifacts tied to concrete tests/checks.
|
||||
|
||||
## Scope
|
||||
- Cross-node behavior spanning control, measurement, and integrations
|
||||
- Test plans and validation docs under repository documentation paths
|
||||
- Node-level suites where commissioning evidence is derived
|
||||
|
||||
## Workflow
|
||||
1. Build FAT/SAT matrix from impacted contracts and risk areas.
|
||||
2. Define pass/fail criteria and required instrumentation visibility.
|
||||
3. Execute or script reproducible validation checks.
|
||||
4. Capture evidence with timestamps, commands, and outcomes.
|
||||
5. Define rollout gates and rollback triggers.
|
||||
|
||||
## Standards
|
||||
- Prefer deterministic replayable checks over ad-hoc validation.
|
||||
- Include negative-path and recovery-path tests.
|
||||
- Tie each acceptance criterion to a concrete artifact.
|
||||
- Keep operator handoff notes concise and actionable.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- startup/shutdown commissioning sequences
|
||||
- failover and reconnect scenarios
|
||||
- alarm/interlock behavior under commissioning cases
|
||||
- post-deploy smoke checks and regression shortlist
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- FAT/SAT-style validation matrix
|
||||
- executed evidence summary
|
||||
- go/no-go risks and mitigations
|
||||
- rollback plan and monitoring checklist
|
||||
|
||||
Decision interview triggers:
|
||||
- reduced commissioning scope under schedule pressure
|
||||
- acceptance of unresolved high-severity risks
|
||||
- rollout sequencing choices with operational impact
|
||||
58
.claude/skills/evolv-database-influx-architecture/SKILL.md
Normal file
58
.claude/skills/evolv-database-influx-architecture/SKILL.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: evolv-database-influx-architecture
|
||||
description: Design and review EVOLV data modeling and storage architecture for telemetry and dashboard consumption. Use when deciding InfluxDB measurement/tag/field schemas, retention/downsampling strategy, write/read payload structures, and Grafana query compatibility for Node-RED outputs.
|
||||
---
|
||||
|
||||
# EVOLV Database Influx Architecture
|
||||
|
||||
## Mission
|
||||
Shape telemetry data so it is queryable, performant, and maintainable for operations dashboards and analytics.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current measurement/tag/field usage and dashboard queries.
|
||||
- Define invariants before edits:
|
||||
- query compatibility for existing Grafana/consumer flows
|
||||
- bounded tag cardinality
|
||||
- explicit units and timestamp policy
|
||||
- Provide validation evidence using representative payloads and queries.
|
||||
|
||||
## Scope
|
||||
- Output payload structure from EVOLV nodes
|
||||
- InfluxDB write model: measurement, tags, fields, timestamp policy
|
||||
- Retention/downsampling implications for Grafana visualization
|
||||
|
||||
## Workflow
|
||||
1. Classify data by usage:
|
||||
- real-time control
|
||||
- operator dashboarding
|
||||
- long-term analytics
|
||||
2. Define stable schema conventions:
|
||||
- measurement naming
|
||||
- tag cardinality controls
|
||||
- numeric fields and units
|
||||
3. Validate that node outputs map cleanly to write model.
|
||||
4. Check query ergonomics for expected Grafana panels.
|
||||
5. Specify retention/downsampling and backfill behavior.
|
||||
|
||||
## Design Rules
|
||||
- Avoid high-cardinality tags for volatile identifiers.
|
||||
- Keep units explicit and consistent over time.
|
||||
- Prefer additive schema evolution; document breaking changes.
|
||||
- Include timestamps that are consistent across nodes.
|
||||
|
||||
## Test/Validation Expectations
|
||||
- Verify sample payloads produce intended point shape.
|
||||
- Check representative queries for latency and result correctness.
|
||||
- Include migration strategy when schema changes are unavoidable.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- proposed schema (measurement/tags/fields)
|
||||
- rationale tied to dashboard and analytics use
|
||||
- changed files/tests
|
||||
- migration and retention plan
|
||||
|
||||
Decision interview triggers:
|
||||
- schema changes that break existing queries/panels
|
||||
- retention/downsampling policies with data-loss tradeoffs
|
||||
- backfill rules that alter historical comparability
|
||||
67
.claude/skills/evolv-frontend-node-red/SKILL.md
Normal file
67
.claude/skills/evolv-frontend-node-red/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: evolv-frontend-node-red
|
||||
description: Design and implement Node-RED node editor UI and runtime-facing configuration for EVOLV. Use when editing node HTML editor files, `RED.nodes.registerType(...)` defaults, admin endpoint-driven menus/config scripts, and config mapping into `src/nodeClass.js` in JavaScript/CommonJS nodes.
|
||||
---
|
||||
|
||||
# EVOLV Frontend Node-RED
|
||||
|
||||
## Mission
|
||||
Implement robust Node-RED editor experiences that keep UI defaults, runtime config parsing, and behavior in lockstep.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from impacted files and active runtime/editor contracts.
|
||||
- Define invariants before editing:
|
||||
- `.html` defaults and runtime parsing parity
|
||||
- endpoint path stability (`/<nodeName>/menu.js`, `/<nodeName>/configData.js`)
|
||||
- released topic/output compatibility unless migration is declared
|
||||
- Provide evidence for changed behavior (tests or smoke checks).
|
||||
|
||||
## Repo-Specific Rules
|
||||
- Use CommonJS patterns in runtime files.
|
||||
- Keep node names aligned across `RED.nodes.registerType('<nodeName>', ...)`, runtime registration in `<nodeName>.js`, and package/node mapping.
|
||||
- Keep admin endpoint paths stable unless editor consumers are updated: `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
|
||||
- Prefer placeholder-driven UI composition when matching EVOLV patterns.
|
||||
|
||||
## Node Layout Standard
|
||||
Use `nodes/machineGroupControl/` as the template baseline for new nodes.
|
||||
|
||||
- `nodes/<nodeName>/<nodeName>.js`
|
||||
- Keep runtime entry small.
|
||||
- Create Node-RED instance and attach `this.nodeClass = new nodeClass(...)`.
|
||||
- Register admin endpoints via shared managers.
|
||||
- `nodes/<nodeName>/<nodeName>.html`
|
||||
- Register defaults in `RED.nodes.registerType(...)`.
|
||||
- Load `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
|
||||
- Use `oneditprepare` to call `window.EVOLV.nodes.<nodeName>.initEditor(this)`.
|
||||
- `nodes/<nodeName>/src/nodeClass.js`
|
||||
- Normalize `uiConfig` into runtime config.
|
||||
- Keep Node-RED concerns here: input routing, tick loop, output formatting, status.
|
||||
- `nodes/<nodeName>/src/specificClass.js`
|
||||
- Keep domain logic here with minimal/no direct Node-RED coupling.
|
||||
|
||||
## Implementation Workflow
|
||||
1. Inspect current node trio: `.html`, `.js`, `src/nodeClass.js`.
|
||||
2. Define required config properties and defaults.
|
||||
3. Update `.html` defaults and form controls.
|
||||
4. Update runtime config normalization in `src/nodeClass.js`.
|
||||
5. Confirm `msg.topic` command handling is still coherent.
|
||||
6. Add tests under `nodes/<nodeName>/test/` with focus on config defaults/overrides and topic routing.
|
||||
7. If creating a new node, add entry under root `package.json` `node-red.nodes` map.
|
||||
|
||||
## Quality Gates
|
||||
- Every UI property has corresponding runtime handling.
|
||||
- Numeric inputs are validated/coerced consistently.
|
||||
- Node status and output shape remain predictable.
|
||||
- No Node-RED runtime dependency required for domain tests.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- changed config fields and mapping table
|
||||
- changed files
|
||||
- tests added and what they prove
|
||||
- migration notes if backward compatibility changed
|
||||
|
||||
Decision interview triggers:
|
||||
- form or default changes that alter existing deployed behavior
|
||||
- endpoint contract/path changes
|
||||
- UI/runtime migration that could break saved Node-RED flows
|
||||
55
.claude/skills/evolv-instrumentation-assets/SKILL.md
Normal file
55
.claude/skills/evolv-instrumentation-assets/SKILL.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: evolv-instrumentation-assets
|
||||
description: Engineer measurement and instrumentation behavior for EVOLV assets. Use when defining sensor mappings, tag semantics, data quality checks, measurement container behavior, calibration assumptions, and measurement-driven node logic in `measurement` and related assets.
|
||||
---
|
||||
|
||||
# EVOLV Instrumentation Assets
|
||||
|
||||
## Mission
|
||||
Ensure measurements are trustworthy, well-modeled, and usable by control and analytics logic.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Ground changes in current measurement definitions and downstream consumers.
|
||||
- Define invariants before edits:
|
||||
- unit consistency and conversion transparency
|
||||
- explicit quality-state handling
|
||||
- no silent coercion that hides sensor faults
|
||||
- Provide evidence for data-quality transitions and fallback behavior.
|
||||
|
||||
## Scope
|
||||
- `nodes/measurement/`
|
||||
- `nodes/generalFunctions/src/helper/measurement*`
|
||||
- `nodes/generalFunctions/datasets/assetData/measurement.json`
|
||||
- Any node consuming measurement topics or quality flags
|
||||
|
||||
## Workflow
|
||||
1. Inventory required measurements by asset/function.
|
||||
2. Define tag semantics and expected units.
|
||||
3. Add validation rules for bounds, type, and missing values.
|
||||
4. Specify handling for stale/noisy/bad-quality signals.
|
||||
5. Ensure downstream nodes receive consistent payload structure.
|
||||
|
||||
## Standards
|
||||
- Prefer explicit unit naming and conversion points.
|
||||
- Separate raw sensor value from engineered value when possible.
|
||||
- Avoid hidden coercions that mask instrumentation faults.
|
||||
- Record assumptions around calibration and sensor placement.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- missing/invalid payloads
|
||||
- unit conversion correctness
|
||||
- quality/state transitions (good/suspect/bad)
|
||||
- behavior when critical measurements drop out
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- measurement dictionary (name, unit, validity range, source)
|
||||
- validation and fallback rules
|
||||
- file/test changes
|
||||
- open instrumentation risks for commissioning
|
||||
|
||||
Decision interview triggers:
|
||||
- changed units or semantics for released measurements
|
||||
- new fallback logic that may mask real field failures
|
||||
- altered quality thresholds affecting control decisions
|
||||
54
.claude/skills/evolv-measurement-product-specialist/SKILL.md
Normal file
54
.claude/skills/evolv-measurement-product-specialist/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-measurement-product-specialist
|
||||
description: Apply measurement product and device expertise for EVOLV. Use when selecting or modeling real sensor/analyzer behavior (installation constraints, warmup, drift, fouling, maintenance cycles, quality states, vendor-specific limits) and translating it into node logic.
|
||||
---
|
||||
|
||||
# EVOLV Measurement Product Specialist
|
||||
|
||||
## Mission
|
||||
Model real-world measurement device behavior so EVOLV control logic receives realistic, diagnosable signals.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from concrete device classes and current measurement payload contracts.
|
||||
- Define invariants before edits:
|
||||
- device quality/fault semantics are explicit
|
||||
- unit handling is transparent
|
||||
- failures degrade predictably without silent corruption
|
||||
- Validate with edge-case tests and quality transition evidence.
|
||||
|
||||
## Scope
|
||||
- `nodes/measurement/`
|
||||
- Measurement consumption paths in `nodes/*/src/`
|
||||
- Shared measurement utilities in `nodes/generalFunctions/src/measurements/`
|
||||
|
||||
## Workflow
|
||||
1. Define device class behavior (transmitter, analyzer, meter, switch).
|
||||
2. Capture startup/warmup/maintenance/fault states.
|
||||
3. Map quality codes and stale/noisy behavior into payload semantics.
|
||||
4. Verify conversion and plausibility bounds.
|
||||
5. Confirm downstream control impact under bad/suspect states.
|
||||
|
||||
## Standards
|
||||
- Separate raw, filtered, and engineered values where needed.
|
||||
- Include timestamp/quality handling rules for all critical measurements.
|
||||
- Avoid masking device faults with silent defaults.
|
||||
- Document maintenance and recalibration assumptions.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- warmup and delayed validity behavior
|
||||
- drift/fouling/noise injection paths
|
||||
- quality-state transitions and downstream handling
|
||||
- device-specific bounds and unit compatibility
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- device behavior model and assumptions
|
||||
- payload/quality mapping
|
||||
- changed files/tests with evidence
|
||||
- commissioning checks required in field
|
||||
|
||||
Decision interview triggers:
|
||||
- changed quality semantics used by control decisions
|
||||
- new fallback paths that could hide instrumentation failure
|
||||
- device defaults likely to alter operator behavior
|
||||
58
.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md
Normal file
58
.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: evolv-mechanical-rotating-equipment
|
||||
description: Provide rotating equipment engineering guidance for EVOLV machine and pumping logic. Use when implementing or reviewing `rotatingMachine`, `machineGroupControl`, pump/motor behavior, operating envelopes, efficiency/power curves, surge/choke limits, and physically plausible constraints in node domain logic.
|
||||
---
|
||||
|
||||
# EVOLV Mechanical Rotating Equipment
|
||||
|
||||
## Mission
|
||||
Keep rotating equipment behavior physically plausible, safe, and diagnosable in EVOLV JavaScript domain classes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from equipment assumptions and current curve/sensor sources in repo.
|
||||
- Define invariants before edits:
|
||||
- physical plausibility constraints remain enforced
|
||||
- degraded/fail-safe behavior remains explicit
|
||||
- outputs remain diagnosable for operations teams
|
||||
- Validate with boundary-condition evidence and deterministic test outcomes.
|
||||
|
||||
## Scope
|
||||
- `nodes/rotatingMachine/`
|
||||
- `nodes/machineGroupControl/`
|
||||
- `nodes/pumpingStation/`
|
||||
- Related shared curve/model datasets in `nodes/generalFunctions/datasets/assetData/`
|
||||
|
||||
## Engineering Checklist
|
||||
1. Validate units and conversions before algorithm changes.
|
||||
2. Enforce operating envelope constraints:
|
||||
- min/max speed
|
||||
- flow/head boundaries
|
||||
- power/torque limits
|
||||
- efficiency range sanity
|
||||
3. Prevent impossible states (negative flow where not allowed, non-physical efficiencies, unstable mode transitions).
|
||||
4. Define clear degraded behavior for out-of-range inputs.
|
||||
5. Preserve interpretability: outputs should map to recognizable mechanical concepts.
|
||||
|
||||
## Implementation Pattern
|
||||
- Keep mechanics in `src/specificClass.js`.
|
||||
- Keep Node-RED concerns in `src/nodeClass.js`.
|
||||
- Use shared helpers from `generalFunctions` for logging/config assertions.
|
||||
|
||||
## Test Expectations
|
||||
Add/adjust tests under node-specific `test/` for:
|
||||
- boundary conditions
|
||||
- invalid sensor/input combinations
|
||||
- regression of known machine edge cases
|
||||
- deterministic output under repeated ticks
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- assumptions about equipment type and curve source
|
||||
- implemented constraints and rationale
|
||||
- test coverage for boundary cases
|
||||
- remaining mechanical uncertainties requiring field data
|
||||
|
||||
Decision interview triggers:
|
||||
- safety envelope changes (speed, power, flow/head boundaries)
|
||||
- curve-source replacement with uncertain field alignment
|
||||
- degraded-mode changes that affect availability vs protection tradeoffs
|
||||
54
.claude/skills/evolv-ot-edge-plc-integration/SKILL.md
Normal file
54
.claude/skills/evolv-ot-edge-plc-integration/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-ot-edge-plc-integration
|
||||
description: Engineer OT edge connectivity and PLC interoperability for EVOLV. Use when implementing or reviewing OPC UA/Modbus and similar integrations, namespace/tag mapping, quality/timestamp semantics, retry/reconnect behavior, and deterministic command/feedback contracts at the edge.
|
||||
---
|
||||
|
||||
# EVOLV OT Edge PLC Integration
|
||||
|
||||
## Mission
|
||||
Deliver reliable, deterministic edge protocol integration between EVOLV Node-RED nodes and PLC/SCADA systems.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current integration topology, topic contracts, and protocol endpoints.
|
||||
- Define invariants before edits:
|
||||
- command/feedback contracts remain deterministic
|
||||
- reconnect/retry behavior is bounded and observable
|
||||
- quality/timestamp semantics are preserved end-to-end
|
||||
- Validate with connection-loss and recovery evidence.
|
||||
|
||||
## Scope
|
||||
- Edge/connector nodes (existing and new)
|
||||
- Topic mapping code in `nodes/*/src/`
|
||||
- Admin endpoints/config for connector behavior and credentials
|
||||
|
||||
## Workflow
|
||||
1. Map PLC tags/NodeIds/registers to EVOLV message contracts.
|
||||
2. Define write acknowledgement and feedback confirmation rules.
|
||||
3. Implement reconnect/backoff/session handling.
|
||||
4. Enforce quality, timestamp, and stale-value semantics.
|
||||
5. Verify failover behavior and command idempotency.
|
||||
|
||||
## Standards
|
||||
- Never assume connection continuity; model transient faults explicitly.
|
||||
- Keep protocol mappings versioned and auditable.
|
||||
- Separate transport errors from process-state errors.
|
||||
- Ensure secure defaults align with OT/IT security skill.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- disconnect/reconnect and session re-establish paths
|
||||
- duplicate/late/out-of-order message handling
|
||||
- read/write mapping correctness and unit conversion
|
||||
- safe behavior under degraded quality or timeout
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- integration contract map (protocol <-> topic/payload)
|
||||
- retry/recovery strategy and limits
|
||||
- changed files/tests with failure-injection evidence
|
||||
- operational rollout risks and mitigations
|
||||
|
||||
Decision interview triggers:
|
||||
- command authority or handshake behavior changes
|
||||
- protocol mapping breaks requiring migration
|
||||
- timeout/retry strategy changes affecting availability/safety
|
||||
56
.claude/skills/evolv-ot-it-security/SKILL.md
Normal file
56
.claude/skills/evolv-ot-it-security/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: evolv-ot-it-security
|
||||
description: Perform OT/IT security analysis for EVOLV Node-RED automation systems. Use when reviewing admin endpoints, node input handling, configuration exposure, dependency risk, network/data flow boundaries, and secure-by-default behavior for operational technology integrations.
|
||||
---
|
||||
|
||||
# EVOLV OT/IT Security
|
||||
|
||||
## Mission
|
||||
Identify and reduce security risk while preserving operational reliability for process automation workloads.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Model trust boundaries first (admin HTTP, message ingress, external integrations).
|
||||
- Define security invariants before edits:
|
||||
- secure defaults stay secure unless explicitly approved
|
||||
- no sensitive leakage in logs/UI/errors
|
||||
- malformed control inputs are rejected predictably
|
||||
- Support findings with reproducible evidence and concrete remediation steps.
|
||||
|
||||
## Scope
|
||||
- Node-RED admin endpoints in node entry files
|
||||
- Input validation across `msg.topic` and payload paths
|
||||
- Exposure of sensitive config/secrets in code, logs, or UI
|
||||
- Dependency and supply-chain concerns in node packages
|
||||
|
||||
## Security Workflow
|
||||
1. Enumerate attack surface:
|
||||
- HTTP admin routes
|
||||
- message ingress topics/payloads
|
||||
- external service interfaces
|
||||
2. Validate input sanitization and type checks.
|
||||
3. Check least-privilege assumptions and secret handling.
|
||||
4. Evaluate failure modes for denial-of-service or unsafe operation.
|
||||
5. Recommend pragmatic controls with minimal operational friction.
|
||||
|
||||
## Control Priorities
|
||||
- Reject malformed or unauthorized control messages.
|
||||
- Avoid leaking credentials, asset identifiers, or internal topology.
|
||||
- Keep defaults safe; require explicit opt-in for risky behavior.
|
||||
- Preserve auditability of critical control actions.
|
||||
|
||||
## Validation Expectations
|
||||
- Add negative tests for malformed inputs and unauthorized paths.
|
||||
- Confirm error paths are explicit and non-sensitive.
|
||||
- Document residual risk when controls are deferred.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- findings sorted by severity
|
||||
- concrete remediation plan by file
|
||||
- tests added for security regressions
|
||||
- residual risks and compensating controls
|
||||
|
||||
Decision interview triggers:
|
||||
- any change that relaxes authentication/authorization checks
|
||||
- exposure of new admin routes or integration interfaces
|
||||
- security control deferrals that require compensating controls
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: evolv-process-hydraulics-mass-balance
|
||||
description: Engineer process hydraulics and mass-balance consistency across EVOLV nodes. Use when validating flow/volume/level relationships, retention-time assumptions, split/merge behavior, and physically plausible cross-node transport dynamics.
|
||||
---
|
||||
|
||||
# EVOLV Process Hydraulics Mass Balance
|
||||
|
||||
## Mission
|
||||
Preserve physically coherent hydraulics and conservation behavior across interacting EVOLV process nodes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build a flow and accumulation map from current node contracts.
|
||||
- Define invariants before edits:
|
||||
- no unplanned conservation breaks
|
||||
- split/merge behavior remains deterministic
|
||||
- retention/transport assumptions are explicit
|
||||
- Validate with scenario-based balance checks.
|
||||
|
||||
## Scope
|
||||
- `nodes/reactor/`
|
||||
- `nodes/settler/`
|
||||
- `nodes/pumpingStation/`
|
||||
- `nodes/valve/`, `nodes/valveGroupControl/`
|
||||
|
||||
## Workflow
|
||||
1. Identify control volumes and interfaces.
|
||||
2. Map inflow/outflow/storage terms and units.
|
||||
3. Validate steady-state and transient behavior under typical scenarios.
|
||||
4. Check edge cases: zero flow, reverse flow, surge, overflow.
|
||||
5. Confirm output contracts preserve balance observability.
|
||||
|
||||
## Standards
|
||||
- Keep units and sign conventions explicit.
|
||||
- Avoid hidden source/sink terms.
|
||||
- Document retention-time and mixing assumptions.
|
||||
- Preserve existing contracts unless migration is defined.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- mass/volume conservation under nominal operation
|
||||
- split/merge and bypass edge cases
|
||||
- boundary condition behavior at zero/low/high flow
|
||||
- numeric stability under long-run ticks
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- balance model and assumptions
|
||||
- changed files/tests with scenario evidence
|
||||
- unresolved hydraulic risks and required field checks
|
||||
|
||||
Decision interview triggers:
|
||||
- changes to balance assumptions affecting KPI/compliance outputs
|
||||
- compatibility-breaking payload/topic changes for flow/volume data
|
||||
- startup behavior changes with overflow/dry-run implications
|
||||
62
.claude/skills/evolv-process-systems-control/SKILL.md
Normal file
62
.claude/skills/evolv-process-systems-control/SKILL.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: evolv-process-systems-control
|
||||
description: Design and review system-level control behavior across EVOLV process nodes. Use when coordinating multi-node interactions, mode/state transitions, parent-child registration flows, control loops, and complex process sequencing spanning reactors, valves, pumps, settlers, and machine groups.
|
||||
---
|
||||
|
||||
# EVOLV Process Systems Control
|
||||
|
||||
## Mission
|
||||
Preserve stable system-wide behavior across interacting Node-RED nodes and process assets.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build a topic and ownership map from the current repo before changing behavior.
|
||||
- Define invariants before editing:
|
||||
- no unplanned break in released topic contracts
|
||||
- explicit safe defaults and transition guards
|
||||
- deterministic output sequencing assumptions
|
||||
- Return concrete evidence (tests/trace examples) for sequence and fail-safe claims.
|
||||
|
||||
## Scope
|
||||
- Cross-node interactions via `msg.topic`
|
||||
- Parent-child registration contracts (`registerChild` and related topics)
|
||||
- Mode management and sequencing in node wrappers/domain classes
|
||||
|
||||
## Message/Port Convention Baseline
|
||||
Many EVOLV nodes use this output convention:
|
||||
- output 0: process message
|
||||
- output 1: database/influx message
|
||||
- output 2: parent/registration/control plumbing
|
||||
|
||||
Preserve topic stability once released (`registerChild`, `setMode`, `setScaling`, etc). If a topic contract changes, define a migration path.
|
||||
|
||||
## Control Workflow
|
||||
1. Map control boundaries and authority (who commands whom).
|
||||
2. List topic contracts and payload schemas.
|
||||
3. Verify state/mode transition logic for race/conflict conditions.
|
||||
4. Define safe startup, shutdown, and failover behavior.
|
||||
5. Confirm tick timing and output ordering assumptions.
|
||||
|
||||
## Design Rules
|
||||
- Keep topic names stable once released.
|
||||
- Use explicit transition guards and default-safe modes.
|
||||
- Avoid hidden cross-coupling between unrelated assets.
|
||||
- Make control intent observable in outputs/status.
|
||||
|
||||
## Test Expectations
|
||||
Add tests for:
|
||||
- normal sequence transitions
|
||||
- out-of-order messages
|
||||
- duplicate child registration and dedupe behavior
|
||||
- fail-safe behavior under missing dependencies
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- system interaction map (topics + ownership)
|
||||
- transition table and safety guards
|
||||
- changed files/tests
|
||||
- unresolved control hazards with mitigation suggestions
|
||||
|
||||
Decision interview triggers:
|
||||
- any topic rename/removal or payload schema break
|
||||
- authority changes across parent/child nodes
|
||||
- startup/shutdown sequencing changes with operational impact
|
||||
63
.claude/skills/evolv-quality-technical-debt/SKILL.md
Normal file
63
.claude/skills/evolv-quality-technical-debt/SKILL.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: evolv-quality-technical-debt
|
||||
description: Drive code quality, regression prevention, and technical debt management for EVOLV nodes. Use when reviewing changes for bugs, maintainability, test completeness, architectural drift, and when creating prioritized remediation plans for JavaScript/CommonJS Node-RED modules.
|
||||
---
|
||||
|
||||
# EVOLV Quality Technical Debt
|
||||
|
||||
## Mission
|
||||
Raise delivery reliability by detecting defects early and systematically reducing technical debt in EVOLV nodes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Anchor findings to concrete file/line evidence.
|
||||
- Separate correctness risk from style preferences.
|
||||
- Require regression-proof evidence for fixes (tests that fail-before/pass-after when feasible).
|
||||
- Feed recurring failure patterns back into the relevant skill guidance.
|
||||
|
||||
## Scope
|
||||
- Node implementation quality in `nodes/<nodeName>/src/`
|
||||
- Editor/runtime contract consistency in `.html` + runtime wrappers
|
||||
- Shared utility hygiene in `nodes/generalFunctions/`
|
||||
- Test depth in `nodes/<nodeName>/test/`
|
||||
|
||||
## Test Policy Baseline
|
||||
All code changes require tests under `nodes/<nodeName>/test/`.
|
||||
|
||||
Cover at minimum:
|
||||
- config default/override behavior and numeric coercion
|
||||
- each supported `msg.topic` handler with edge cases
|
||||
- child registration and dedupe side effects
|
||||
- tick/output boundaries and error paths
|
||||
- regression tests for fixed bugs
|
||||
|
||||
Execution:
|
||||
- preferred: `node --test nodes/<nodeName>/test/*.test.js`
|
||||
- fallback: `node nodes/<nodeName>/test/<file>.test.js`
|
||||
|
||||
## Review Workflow
|
||||
1. Assess correctness risks first (runtime errors, logic regressions, broken topic contracts).
|
||||
2. Assess maintainability (duplication, unclear ownership, implicit behavior).
|
||||
3. Assess test adequacy against EVOLV policy:
|
||||
- config defaults/overrides
|
||||
- topic handlers and edge cases
|
||||
- tick/output boundaries
|
||||
- regressions for fixed bugs
|
||||
4. Create a prioritized debt backlog with effort and impact.
|
||||
|
||||
## Quality Criteria
|
||||
- Domain logic remains testable without full Node-RED runtime.
|
||||
- Complex logic is explicit and minimally coupled.
|
||||
- Backward compatibility is deliberate and documented.
|
||||
- New behavior includes tests that fail before and pass after.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- findings by severity
|
||||
- test gaps and specific cases to add
|
||||
- debt backlog (now/next/later)
|
||||
- recommended refactors with expected payoff
|
||||
|
||||
Decision interview triggers:
|
||||
- tradeoff between delivery speed and known high-severity risk
|
||||
- acceptance of temporary risk with deferred remediation
|
||||
- testing scope reductions that materially raise regression risk
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: evolv-regulatory-compliance-wastewater
|
||||
description: Apply wastewater regulatory and compliance constraints to EVOLV control and telemetry design. Use when reviewing effluent-quality KPIs, reporting semantics, auditability, traceability of control actions, and compliance-impacting alarm/control decisions.
|
||||
---
|
||||
|
||||
# EVOLV Regulatory Compliance Wastewater
|
||||
|
||||
## Mission
|
||||
Ensure EVOLV changes remain auditable and aligned with wastewater compliance/reporting obligations.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Map compliance-relevant outputs and control decisions from current repo contracts.
|
||||
- Define invariants before edits:
|
||||
- compliance KPIs remain traceable
|
||||
- auditability of major control actions is preserved
|
||||
- reporting semantics are stable or explicitly migrated
|
||||
- Validate with evidence that supports audit/review workflows.
|
||||
|
||||
## Scope
|
||||
- Effluent-related outputs and quality calculations in process nodes
|
||||
- Alarm and control behaviors that affect permit-critical operation
|
||||
- Telemetry/reporting contracts consumed by dashboards/reports
|
||||
|
||||
## Workflow
|
||||
1. Identify compliance-relevant metrics and events.
|
||||
2. Trace data lineage from sensor/input to reported output.
|
||||
3. Verify timestamp/quality metadata sufficiency for audits.
|
||||
4. Review alarm/control actions that can affect permit outcomes.
|
||||
5. Define documentation and test evidence for compliance-critical paths.
|
||||
|
||||
## Standards
|
||||
- Prefer explicit semantics over inferred compliance logic.
|
||||
- Preserve historical comparability of compliance KPIs.
|
||||
- Ensure traceability of overrides, trips, and degraded operation.
|
||||
- Keep evidence artifacts reproducible and review-friendly.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- compliance KPI payload consistency
|
||||
- traceability fields presence (timestamp/source/quality where applicable)
|
||||
- alarm/control transitions relevant to permit risk
|
||||
- behavior under missing or suspect compliance measurements
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- compliance impact map and assumptions
|
||||
- changed files/tests with audit-focused evidence
|
||||
- unresolved compliance risks and mitigation recommendations
|
||||
|
||||
Decision interview triggers:
|
||||
- any change that can alter reported compliance values
|
||||
- changed retention/backfill semantics for compliance reporting
|
||||
- reduced auditability or traceability in control/telemetry paths
|
||||
53
.claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md
Normal file
53
.claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: evolv-telemetry-analytics-dashboards
|
||||
description: Design telemetry-to-dashboard contracts for EVOLV operations analytics. Use when defining KPI semantics, chart/topic contracts, aggregation windows, operator diagnostics, and compatibility between node outputs, Influx schema, and dashboard consumers.
|
||||
---
|
||||
|
||||
# EVOLV Telemetry Analytics Dashboards
|
||||
|
||||
## Mission
|
||||
Keep EVOLV telemetry contracts stable, queryable, and useful for operators and performance analysis.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current output payloads, Influx schema assumptions, and dashboard queries.
|
||||
- Define invariants before edits:
|
||||
- KPI semantics remain explicit and comparable over time
|
||||
- topic/field naming stability is preserved or migrated
|
||||
- dashboard failure modes are diagnosable
|
||||
- Validate with query-level and chart-level evidence.
|
||||
|
||||
## Scope
|
||||
- Node outputs in `nodes/*/src/nodeClass.js`
|
||||
- Influx-related contract points and dashboard config/manuals
|
||||
- FlowFuse chart usage and topic/category consistency
|
||||
|
||||
## Workflow
|
||||
1. Inventory KPI producers and consumers.
|
||||
2. Define measurement/tag/field/topic contracts.
|
||||
3. Validate aggregation/downsampling assumptions.
|
||||
4. Ensure chart wiring remains consistent (`msg.topic` category baseline).
|
||||
5. Verify operator readability and anomaly visibility.
|
||||
|
||||
## Standards
|
||||
- Keep KPI definitions versioned and unambiguous.
|
||||
- Preserve backward compatibility for released dashboards.
|
||||
- Avoid overloading fields with mixed semantics.
|
||||
- Pair every contract change with migration notes.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- payload field presence/types for key KPIs
|
||||
- topic/category compatibility for charts
|
||||
- query compatibility for existing dashboards
|
||||
- behavior under missing/null data windows
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- KPI and telemetry contract map
|
||||
- changed files/tests and dashboard impact notes
|
||||
- migration/deprecation notes if compatibility changed
|
||||
|
||||
Decision interview triggers:
|
||||
- KPI definition changes affecting reporting decisions
|
||||
- dashboard contract breaks requiring migration
|
||||
- retention/aggregation changes impacting trend interpretation
|
||||
Reference in New Issue
Block a user