@evomap/evolver 1.89.3 → 1.89.4

package/.cursor/BUGBOT.md

@@ -0,0 +1,182 @@
+# Bugbot Review Rules — evolver-private-dev
+
+This file gives Cursor Bugbot project-specific context. The repository is the
+**private source of truth** for `@evomap/evolver`; the public mirror is
+`EvoMap/evolver`, built via `scripts/build_public.js` driven by
+`public.manifest.json`. Treat anything that could leak from private to public,
+or that could break GEP asset integrity, as high severity.
+
+## Project shape
+
+- Pure Node.js (no TypeScript). Public surface is the npm package
+  `@evomap/evolver`; entry point is `index.js`.
+- Runtime dependencies are intentionally minimal — only `dotenv`. Do not
+  approve PRs that add new runtime dependencies without a clear justification
+  in the PR description.
+- Tests run via `node --test`. There is no ESLint/Prettier in CI; rely on
+  Bugbot to catch style and correctness regressions.
+
+## High-severity rules (block the PR)
+
+### 1. Secrets must round-trip through `src/gep/sanitize.js`
+
+Any code path that writes capsule payloads, agent logs, prompts, or hub
+broadcasts must call `sanitizePayload` (or an equivalent redactor) **before**
+the data leaves the process. Flag as a blocking Bug if a PR:
+
+- Logs raw `process.env.*`, request headers, or `Authorization` values.
+- Sends capsule/event/log objects to `src/gep/bridge.js`,
+  `src/gep/a2aProtocol.js`, `src/gep/issueReporter.js`, `src/proxy/sync/**`,
+  or any HTTP/IPC sink without first running `sanitizePayload`.
+- Adds a new secret pattern (API key, token, private key) that is not also
+  added to `REDACT_PATTERNS` in `sanitize.js`.
+
+### 2. Public/private leak prevention
+
+`scripts/build_public.js` + `public.manifest.json` decide what ships to the
+public repo and to npm. Block PRs that:
+
+- Add a new top-level path that is **not** covered by either `include` or
+  `exclude` in `public.manifest.json`. New private-only paths (docs/,
+  memory/, internal scripts) must be added to `exclude`.
+- Add `console.log` / TODO / FIXME / internal URLs / employee emails inside
+  files listed in the `obfuscate` array — those files are shipped after
+  obfuscation and any plaintext secret/comment leaks past obfuscation.
+- Reference `EvoMap/evolver-private-dev` (this repo's URL) inside any file
+  that is part of the public include set.
+- **Add a new file under `src/gep/**` or `src/evolve/**` (or any directory
+  whose siblings are already in the `obfuscate` array) without also adding
+  the new file to `obfuscate`.** Sibling consistency is the rule: if every
+  other `*.js` in the same directory is obfuscated, the new one must be
+  too. Exception: the PR description must explicitly state why obfuscation
+  is unnecessary (e.g. "trivial public algorithm reused from MIT-licensed
+  source") AND the file must contain no business logic, no env-var reads,
+  and no path/URL constants. Historical regressions: PR #20 (hub.js,
+  enrich.js, utils.js missed obfuscate, fixed in 79821fc and 3da07e3),
+  PR #34 (hash.js missed obfuscate).
+
+**This file is private-only.** `.cursor/BUGBOT.md` is private to this repo
+and is pruned from the public build via `public.manifest.json`'s
+`exclude: [".cursor/**"]`. Project-specific rules for the public mirror
+`EvoMap/evolver` (if any are needed) live in the Cursor dashboard's
+repository manual rules, not in the source tree, so the published npm
+package and the public GitHub repo do not carry editor-tool config files.
+
+### 3. GEP asset integrity
+
+The GEP protocol depends on stable hashing and signatures
+(`src/gep/contentHash.js`, `src/gep/crypto.js`, `src/gep/integrityCheck.js`).
+Block PRs that:
+
+- Change `contentHash` / `crypto.sign` / `crypto.verify` behaviour without an
+  explicit version bump and a migration path for existing
+  `assets/gep/*.jsonl` records.
+- Mutate gene/capsule/event objects in-place after they have been hashed or
+  signed.
+- Introduce non-deterministic ordering (e.g. `Object.keys` without sort, or
+  `for ... in`) inside any code that participates in hashing.
+- **Ship a schema factory (e.g. `createGene` / `createCapsule` / `createTask`,
+  or any new `src/gep/schemas/<X>.js`) without proving the matching
+  `validate<X>` is actually called on every write/publish path.** A schema
+  that no one calls is dead code that masks LLM/Hub-supplied garbage.
+  Require the PR description to include a `grep -rn 'validate<X>' src/`
+  output covering at least: every `upsert<X>` / `append<X>` in
+  `src/gep/assetStore.js`, every `buildPublish<X>*` in
+  `src/gep/a2aProtocol.js`, and every direct disk-write site. Historical
+  regression: PR #25 / #27 shipped `validateGene` / `validateCapsule` that
+  no caller invoked, fixed retroactively as audit issue #30 H1 (commit
+  902a256). Track the same expectation for any future `validate<Y>`.
+- **Spread `DEFAULTS` into a partial without slicing every reference-typed
+  field afterwards.** `Object.assign({}, X_DEFAULTS, partial)` is a shallow
+  copy: arrays and sub-objects on the result still point to either
+  `X_DEFAULTS`'s shared instance or to `partial`'s caller-owned
+  instance. Downstream `.push(...)` then contaminates every other consumer.
+  Every array field needs `Array.isArray(x) ? x.slice() : []`; every
+  sub-object needs `Object.assign({}, FIELD_DEFAULTS, x)`. Historical
+  regression: PR #25 createGene leaked `epigenetic_marks` /
+  `learning_history` / `anti_patterns` / `constraints.forbidden_paths`
+  across all genes (commit 549f1bd).
+
+### 4. Filesystem and network safety
+
+- Reject `child_process.exec*` / `spawn*` calls that interpolate untrusted
+  strings into the command. Use the array form with explicit args.
+- Reject `fs.writeFileSync` / `fs.rmSync({recursive:true})` calls that
+  resolve paths from user/LLM input without going through `src/gep/paths.js`
+  or an equivalent allowlist.
+- Reject HTTP fetches that disable TLS verification
+  (`rejectUnauthorized: false`, `NODE_TLS_REJECT_UNAUTHORIZED=0`) outside
+  isolated test fixtures.
+
+## Medium-severity rules (request changes)
+
+### Async correctness
+
+- Every Promise must either be `await`ed or have a `.catch` handler. Flag
+  unhandled-rejection risks.
+- Do not mix `await` with `.then(...)` chains inside the same logical block.
+- Long-running loops in `src/proxy/**` must respect the existing cancellation
+  / shutdown signals (look for `idleScheduler.js`, `lifecycle/**`).
+
+### Module-load ordering vs. dotenv
+
+`src/evolve.js` calls `require('dotenv').config(...)` mid-file (around
+the comment block "Load environment variables from repo root"). Any module
+that reads `process.env.X` at module-load time (e.g.
+`const FOO = process.env.FOO || default` at the top of the file) MUST be
+required AFTER the `dotenv.config()` call, otherwise `process.env.X` is
+empty and the constant freezes to the default for the rest of the process
+lifetime. Block PRs that:
+
+- Add a new module-level `const`/`let` initialized from `process.env.*` and
+  hoist its `require(...)` above the `dotenv.config()` call in `evolve.js`,
+  `index.js`, or any new top-level entry point.
+- Re-introduce eager `require('./evolve/pipeline/<X>')` at the top of
+  `src/evolve.js`. The current pattern requires those modules AFTER dotenv;
+  see commit 3da07e3 for context.
+
+A safe pattern when a module truly needs env at module-load time: read the
+env via `src/config.js`'s `envInt()` / `envStr()` helpers, which are
+re-evaluated lazily on each call instead of frozen at module load.
+
+### CLI compatibility
+
+`index.js` is the public CLI binary. Any change to CLI flags, default
+behaviour, exit codes, or stdout/stderr format is a breaking change for
+downstream users. Require:
+
+- A note in `CHANGELOG.md` describing the user-visible change.
+- Backwards-compatible behaviour behind a feature flag in
+  `src/gep/featureFlags.js` whenever possible.
+
+### Node version
+
+`package.json` does not currently pin an `engines` field. The package is
+distributed as a CLI to end users on a wide range of Node versions. Treat
+Node.js >= 18 as the de-facto floor and flag use of APIs that require Node
+20+ (e.g. `fs.glob`, top-level `using`, `--experimental-strip-types`) unless
+the PR also adds an `engines.node` constraint to `package.json` and notes
+the bump in `CHANGELOG.md`.
+
+## Low-severity rules (nit / suggestion)
+
+- Use `node:` prefix for built-in module imports (`require('node:fs')`).
+- Prefer named functions over anonymous arrow functions when registering
+  event listeners — eases stack traces.
+- Avoid `JSON.stringify(...)` of large objects in hot paths inside
+  `src/proxy/server/**`; prefer streaming or pagination.
+
+## Context Bugbot should NOT flag
+
+- The lack of TypeScript or ESLint config — intentional.
+- Single-dependency `package.json` — intentional minimal supply chain.
+- Files under `assets/gep/*.jsonl` are gitignored; if a PR appears to add
+  them, that is a **block**, not a nit (see rule 2).
+- The `dist-public/` and `dist-binaries/` directories are build artifacts —
+  do not review them.
+
+## Style
+
+This repository forbids emoji in code, comments, commit messages, and
+documentation, with a single allowed exception: the DNA glyph used in
+public-facing docs. Flag any PR that adds other emoji.

package/.env.example

@@ -0,0 +1,68 @@
+# EvoMap Hub connection (optional -- all core features work offline without these)
+# A2A_HUB_URL=https://evomap.ai
+# A2A_NODE_ID=your_node_id_here
+
+# Evolution strategy: balanced (default) | innovate | harden | repair-only
+# EVOLVE_STRATEGY=balanced
+
+# Bridge mode: controls sessions_spawn() output for host runtimes like OpenClaw.
+# Defaults to off unless OPENCLAW_WORKSPACE is set.
+# EVOLVE_BRIDGE=false
+
+# Heartbeat interval in milliseconds (default: 360000 = 6 minutes)
+# HEARTBEAT_INTERVAL_MS=360000
+
+# Worker pool: set to 1 to participate as a worker in the EvoMap network
+# WORKER_ENABLED=1
+# WORKER_DOMAINS=repair,harden
+# WORKER_MAX_LOAD=5
+
+# Path overrides (usually auto-detected)
+# MEMORY_DIR=./memory
+# EVOLVER_REPO_ROOT=.
+# OPENCLAW_WORKSPACE=
+# When evolver runs as an npm dependency or a skill under a host repo,
+# it auto-detects the host's .git so it can see Hand Agent edits.
+# Set this to 'true' only if you deliberately want evolver to ignore the
+# host repo and treat its own package directory as the work area.
+# EVOLVER_NO_PARENT_GIT=false
+
+# Auto GitHub issue reporting (enabled by default)
+# EVOLVER_AUTO_ISSUE=true
+# GITHUB_TOKEN=your_github_token_here
+
+# Pre-publish leak check mode: strict (default since v1.69.7) | warn | off
+# - strict: block publish when sensitive data is detected in the capsule/gene payload
+# - warn: log a warning and continue publishing (relies on sanitizePayload redaction)
+# - off: skip the leak scan entirely (not recommended)
+# Set to 'warn' to restore v1.69.6 and earlier behavior.
+# EVOLVER_LEAK_CHECK=strict
+
+# Hub URL resolution (v1.69.7+):
+# - A2A_HUB_URL is the primary override (used at runtime by most modules)
+# - EVOMAP_HUB_URL is a secondary override kept for backward compatibility
+# - EVOLVER_DEFAULT_HUB_URL overrides the compile-time default when neither of
+#   the above is set. Use this for fully air-gapped deployments that still want
+#   to point validator/directory/privacy clients at a private hub endpoint.
+# EVOLVER_DEFAULT_HUB_URL=https://evomap.ai
+
+# Verbose logging
+# EVOLVER_VERBOSE=true
+
+# Memory graph rotation (issue #519). memory_graph.jsonl accumulates
+# every evolution event and grows unboundedly on long-running nodes.
+# When the active file crosses EVOLVER_MEMORY_GRAPH_MAX_SIZE_MB it is
+# renamed to memory_graph.jsonl.<timestamp>.gz and a fresh file is
+# started. Only the most recent EVOLVER_MEMORY_GRAPH_RETENTION_COUNT
+# archives are kept; older ones are deleted.
+# EVOLVER_MEMORY_GRAPH_AUTO_ROTATE=true
+# EVOLVER_MEMORY_GRAPH_MAX_SIZE_MB=100
+# EVOLVER_MEMORY_GRAPH_RETENTION_COUNT=7
+
+# Rollback strategy when a solidify cycle's validation fails.
+#   stash (default): git stash push --include-untracked. Recover via 'git stash pop'.
+#   hard:            git reset --hard. WARNING: discards uncommitted changes irrecoverably.
+#   none:            do nothing. Leaves the failed cycle's edits in place.
+# Default flipped from 'hard' to 'stash' in 1.80.8 to prevent silent data loss
+# when evolver runs in third-party host repos.
+# EVOLVER_ROLLBACK_MODE=stash

package/.git-commit-guard-token

@@ -0,0 +1 @@
+SKILL_COMMIT

package/.github/CODEOWNERS

@@ -0,0 +1,63 @@
+# Code owners for this repository
+# Format: each rule grants automatic review-request to the listed owner(s)
+# when a matching path is touched in a PR. Combined with branch protection's
+# "Require review from Code Owners" rule on main, these owners must approve
+# the PR before it can merge.
+#
+# Multiple owners on each line means GitHub will auto-request a review from
+# all listed owners on a matching PR; ANY one of them approving is sufficient
+# to satisfy the branch-protection 'require code owner review' gate. This is
+# the agreed fallback order: autogame-17 primary, forrestlinfeng + cloudcarver
+# as backups when the primary is unavailable.
+#
+# Why we need this: PR #34 (2026-05-10) was self-merged by the author 2 minutes
+# before a maintainer review comment landed, shipping a missing obfuscate
+# registration into main. CODEOWNERS + branch protection make that pattern
+# physically impossible.
+
+# Default: every file is owned by autogame-17 unless a more specific rule below
+# overrides it. Keeps coverage complete even for files we forget to call out.
+*                              @autogame-17 @forrestlinfeng @cloudcarver
+
+# High-risk paths -- listed explicitly so GitHub UI surfaces "Owner review
+# required" prominently when these are touched, even if the catch-all above
+# would already cover them. New contributors should treat any change here
+# as a multi-day review cycle.
+
+# GEP schemas (Gene / Capsule / Task / future). Validators and defaults must
+# stay in sync with hub-side expectations; shallow-copy bugs and validator-
+# wiring gaps in this directory have a track record (PR #25 / #27 / audit #30).
+/src/gep/schemas/              @autogame-17 @forrestlinfeng @cloudcarver
+
+# Pipeline modules. Module-load order vs dotenv is fragile here; refactors
+# in PR #20-#24 introduced multiple dotenv-ordering and missing-import
+# regressions before merge.
+/src/evolve/                   @autogame-17 @forrestlinfeng @cloudcarver
+
+# Content-addressable storage and integrity primitives. Any change here
+# changes asset_id semantics across all stored capsules.
+/src/gep/contentHash.js        @autogame-17 @forrestlinfeng @cloudcarver
+/src/gep/crypto.js             @autogame-17 @forrestlinfeng @cloudcarver
+/src/gep/integrityCheck.js     @autogame-17 @forrestlinfeng @cloudcarver
+/src/gep/shield.js             @autogame-17 @forrestlinfeng @cloudcarver
+/src/gep/hubVerify.js          @autogame-17 @forrestlinfeng @cloudcarver
+
+# Anything that touches secrets, sanitization, or proxy auth.
+/src/gep/sanitize.js           @autogame-17 @forrestlinfeng @cloudcarver
+/src/proxy/                    @autogame-17 @forrestlinfeng @cloudcarver
+
+# Public-mirror surface. Manifest mistakes leak source / runtime assets to
+# npm; build/publish scripts directly drive npm + GitHub Release.
+/public.manifest.json          @autogame-17 @forrestlinfeng @cloudcarver
+/scripts/build_public.js       @autogame-17 @forrestlinfeng @cloudcarver
+/scripts/publish_public.js     @autogame-17 @forrestlinfeng @cloudcarver
+/scripts/pre_publish_check.js  @autogame-17 @forrestlinfeng @cloudcarver
+/scripts/build_binaries.js     @autogame-17 @forrestlinfeng @cloudcarver
+/scripts/deploy.sh             @autogame-17 @forrestlinfeng @cloudcarver
+
+# Repo metadata that gates everything else.
+/.github/                      @autogame-17 @forrestlinfeng @cloudcarver
+/.cursor/                      @autogame-17 @forrestlinfeng @cloudcarver
+/CODEOWNERS                    @autogame-17 @forrestlinfeng @cloudcarver
+/package.json                  @autogame-17 @forrestlinfeng @cloudcarver
+/package-lock.json             @autogame-17 @forrestlinfeng @cloudcarver

package/.github/ISSUE_TEMPLATE/good_first_issue.md

@@ -0,0 +1,23 @@
+---
+name: Good first issue
+about: Help newcomers get started with a small, self-contained task
+labels: good first issue, help wanted, docs
+
+---
+
+## Summary
+
+Short description of the task to complete.
+
+## Steps to reproduce / task
+
+1. Steps to reproduce (if a bug) or steps to implement (if feature)
+2. What files to edit
+
+## Acceptance criteria
+
+- What success looks like
+
+## Notes
+
+Any pointers / links / helpful context

package/.github/pull_request_template.md

@@ -0,0 +1,45 @@
+## Summary
+
+Short 1-2 sentence summary of the change.
+
+## What changed
+
+- Bullet list of changes
+
+## How to test
+
+1. Copy commands
+2. Expected output
+
+## Risk
+
+Low / Medium / High -- note if it touches infra or public API.
+
+## Self-check
+
+Tick only the boxes that apply, but every applicable box must be ticked. Bugbot
+reads the project rules and will request changes if anything below is missing.
+
+- [ ] If this PR adds a new source file under `src/`, it is registered in
+      `public.manifest.json` consistently with its sibling files (e.g. listed
+      in `obfuscate` when the rest of the directory is). Build verification
+      passed: `node scripts/build_public.js` succeeded and the new file shows
+      up in `dist-public/` in the expected (obfuscated or plain) form.
+- [ ] If this PR adds or modifies a schema factory under `src/gep/schemas/`,
+      the corresponding `validate*` function is invoked at every write and
+      every publish call site (not just defined).
+- [ ] If this PR uses `Object.assign({}, DEFAULTS, partial)` to build an
+      object, every reference-typed field (arrays, sub-objects) on the result
+      is sliced or cloned -- not held by reference to either source.
+- [ ] If this PR introduces a new module-level constant initialized from
+      `process.env.X`, the owning module is loaded after the entry point's
+      dotenv configuration step (or the constant is migrated to the lazy
+      env helpers in `src/config.js`).
+- [ ] No new runtime dependencies added without a clear justification in the
+      "What changed" section above.
+- [ ] Tests added or updated to cover the new behavior; full suite passes
+      locally (`node --test test/*.test.js`).
+
+## Related
+
+Closes #NN

package/.github/workflows/test.yml

@@ -0,0 +1,75 @@
+name: test
+
+# Runs the Node test suite on every PR and on pushes to main. Originally
+# Ubuntu-only (#198): PR checks were Cursor Bugbot + Security, neither of
+# which runs `npm test`, so a green PR did NOT mean the tests passed.
+#
+# This workflow now also runs the suite on Windows + macOS via a second job
+# (test-cross). #198 explicitly flagged Windows / macOS as a follow-up: the
+# suite still has Linux-specific assumptions (symlink reliance, hard-coded
+# ~/.volta layout, POSIX-style path equality) that would fail on those
+# hosts. test-cross runs on PRs in **advisory** mode (continue-on-error)
+# so those red signals are visible to reviewers without blocking merge
+# while the suite is being made hermetic. Each fix can flip its tests
+# from "red on Win/Mac" to "green on Win/Mac" incrementally. Once the
+# remaining failures are cleaned up, drop `continue-on-error: true` and
+# add `test-cross` to required checks to make cross-platform green a
+# hard merge gate.
+#
+# main pushes skip test-cross to keep private-repo billing predictable
+# (macos-latest is 10x and windows-latest is 2x the ubuntu rate).
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22' # engines: node >=22.12
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests (node --test)
+        run: npm test
+
+  test-cross:
+    # Advisory cross-platform run: PR-only (skips main push to save billing),
+    # continue-on-error so a known Win/Mac regression does not block merge
+    # while the suite is being hardened. Reviewers still see the result and
+    # can opt-in to wait for a fix on a per-PR basis.
+    if: github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests (node --test)
+        run: npm test