helixevo 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to HelixEvo are documented here.
 
+## [Unreleased]
+
+## [0.4.0] - 2026-03-24
+
+### Added
+- Dedicated **Co-Evolution** dashboard route and pressure-response control surface for routed interventions, lifecycle visibility, and operator control
+- Persistent pressure intervention history in `~/.helix/pressure-interventions.jsonl` so research, specialize, evolve, generalize, and manual review responses become part of the brain ledger
+- Governed route recommendations, pressure motif aggregation, and transfer-event persistence in `~/.helix/transfer-events.jsonl` for reusable cross-project promotion evidence
+- Dedicated **Topology** dashboard route for governed structural review, including persistent open/deferred/accepted/rejected queue visibility
+- Operator governance steering persisted in `~/.helix/governance-state.json` and surfaced across runtime summaries plus the dashboard
+- Persistent topology review candidate queue in `~/.helix/topology-review-candidates.json` with decision ledger in `~/.helix/topology-review-decisions.jsonl`
+- `graph --optimize` now refreshes topology review candidates for merge, split, promote, consolidate, and rewire review
+- New reviewed topology execution state in:
+  - `~/.helix/topology-overrides.json`
+  - `~/.helix/topology-snapshots.json`
+  - `~/.helix/topology-apply-plans.json`
+  - `~/.helix/topology-executions.jsonl`
+  - `~/.helix/topology-artifacts.jsonl`
+- New `helixevo topology` command for status, prepare, apply, and rollback control
+- New `/api/topology-apply` dashboard route for reviewed execution actions via the local CLI runner
+
+### Changed
+- HelixEvo now closes more of the brain loop from pressure sensing to governed response, transfer promotion, topology review, and safe reviewed structural execution
+- Overview, Co-Evolution, Research, Projects, and Skill Network now surface pressure, governance, transfer, topology review, and topology execution state in parallel
+- `generalize` now acts as a governed network-level intervention lane that can address recurring motifs via transfer evidence without falsely closing local signal lifecycle
+- `manual-review` is now a real operator workflow backed by persisted review candidates and explicit decisions rather than only a routing label
+- Accepted topology review candidates can now progress into prepared plans, safe structural apply, snapshot-backed rollback, and visible execution history on `/topology`
+
+## [0.3.1] - 2026-03-23
+
+### Fixed
+- `helixevo dashboard` now recovers cleanly when the preferred port is occupied: it reuses a known managed dashboard if one is already running there, otherwise it falls forward to the next open port instead of failing with `EADDRINUSE`
+- Added `helixevo dashboard --port <port>` so operators can choose a preferred starting port while preserving automatic fallback behavior
+- Background dashboard stop/reuse logic now tracks the actual assigned port, so `helixevo dashboard --stop` works correctly even after fallback to a non-default port
+
 ## [0.3.0] - 2026-03-23
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # HelixEvo
 
-Co-evolving skill and project brain for AI agents. HelixEvo captures failures, traces activations, models pressure, evolves skills through multi-judge evaluation, and maintains a Pareto frontier of optimal skill configurations.
+Co-evolving skill and project brain for AI agents. HelixEvo captures failures, traces activations, models pressure, routes governed responses, promotes cross-project transfer, reviews structural topology changes, safely executes accepted topology transitions with rollback, and maintains a Pareto frontier of optimal skill configurations.
 
 ## How it works
 
@@ -89,8 +89,9 @@ helixevo dashboard
 | `helixevo generalize` | Promote cross-project patterns ↑ |
 | `helixevo specialize --project <name>` | Create project-specific skills ↓ |
 | `helixevo graph` | View skill network in terminal |
+| `helixevo topology` | Prepare, apply, roll back, and inspect reviewed topology execution |
 | `helixevo research` | Proactive web research for skill improvement |
-| `helixevo dashboard` | Open web dashboard at localhost:3847 |
+| `helixevo dashboard [--port <n>]` | Open web dashboard, preferring localhost:3847 and falling forward if occupied |
 | `helixevo status` | Show system health |
 | `helixevo report` | Generate evolution report |
 
@@ -107,7 +108,11 @@ helixevo graph                    # TUI view (instant, cached)
 helixevo graph --mermaid          # Open in browser as Mermaid diagram
 helixevo graph --obsidian ~/vault # Sync to Obsidian vault
 helixevo graph --rebuild          # Re-infer relationships (LLM call)
-helixevo graph --optimize         # Detect merge/split/conflict opportunities
+helixevo graph --optimize         # Detect structural candidates + refresh topology review queue
+helixevo topology --status        # Show reviewed topology execution state
+helixevo topology --prepare <id>  # Prepare an accepted topology candidate
+helixevo topology --apply <id>    # Apply a safe prepared topology plan
+helixevo topology --rollback <id> # Roll back an applied topology plan
 ```
 
 ### Research options
@@ -129,6 +134,16 @@ All data is stored in `~/.helix/`:
 ├── failures.jsonl           # Captured failures
 ├── activation-traces.jsonl  # Native + derived activation traces
 ├── pressure-signals.jsonl   # Native + derived adaptation pressure
+├── pressure-interventions.jsonl # Routed intervention ledger across response lanes
+├── transfer-events.jsonl    # Promotion / transfer evidence across motifs and projects
+├── governance-state.json    # Operator steering for active governance mode
+├── topology-review-candidates.json # Persisted structural review queue
+├── topology-review-decisions.jsonl # Operator accept/reject/defer decision ledger
+├── topology-overrides.json   # Applied safe structural topology overrides
+├── topology-snapshots.json   # Snapshot refs for reviewed execution and rollback
+├── topology-apply-plans.json # Prepared reviewed topology plans
+├── topology-executions.jsonl # Prepared/applied/rolled-back execution ledger
+├── topology-artifacts.jsonl  # Evidence artifacts for reviewed structural execution
 ├── evolution-artifacts.jsonl # Evolution evidence artifacts per proposal/iteration
 ├── frontier.json            # Pareto frontier (top-k configurations)
 ├── evolution-history.json   # All evolution runs + proposals
@@ -149,15 +164,20 @@ The dashboard provides an interactive view of your skill ecosystem:
 
 ```bash
 helixevo dashboard
-# Opens http://localhost:3847
+# Prefers http://localhost:3847 and falls forward if that port is occupied
+
+helixevo dashboard --port 3900
+# Prefer port 3900 first
 ```
 
 **Tabs:**
-- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, and pressure counts
-- **Skill Network** — Interactive graph, premium inspector, and co-evolution pressure routing signals
-- **Projects** — Project intake studio, live project analysis, gap routing, and per-project pressure hotspots
+- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, pressure counts, topology review visibility, and prepared/applied structural state
+- **Skill Network** — Interactive graph, premium inspector, co-evolution routing signals, and topology review/execution handoff links
+- **Co-Evolution** — Operator cockpit for routed pressure response, governance mode visibility, promotion queues, transfer evidence, and topology handoff
+- **Topology** — Governance steering plus a persistent operator pipeline for review → prepare → apply → rollback across merge / split / promote / rewire / consolidate candidates
+- **Projects** — Project intake studio, live project analysis, gap routing, per-project pressure hotspots, and promotion feeders
 - **Evolution** — Timeline of evolution runs with judge scores, artifact provenance, and activation-aware context
-- **Research** — Knowledge buffer plus a live “why research now” handoff from current pressure and recurring gaps
+- **Research** — Knowledge buffer plus a live “why research now” handoff from current pressure, governed routing, and recurring gaps
 - **Frontier** — Pareto frontier with 4-dimension scores + canary status
 
 The dashboard requires Next.js dependencies. On first run:
@@ -194,6 +214,11 @@ Failures → Cluster → Propose → Replay → Multi-Judge → Regression → C
 - **Ontology** defines the stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.
 - **Activation traces** record which skills and gaps were active during capture and project analysis.
 - **Pressure signals** turn failures and project gaps into explicit adaptation demand.
+- **Pressure interventions** record how HelixEvo responded across research, specialize, evolve, generalize, and manual-review lanes.
+- **Governed routing and transfer evidence** let recurring multi-project motifs bias toward promotion and show when reusable knowledge was actually realized.
+- **Governance steering** lets the operator pin or release the active adaptation mode rather than relying only on derived routing.
+- **Topology review** persists merge / split / promote / rewire / consolidate candidates so manual review is a real workflow.
+- **Reviewed topology execution** turns accepted safe candidates into prepared plans, snapshot-backed applies, and rollbackable structural transitions.
 - **Evolution artifacts** preserve proposal-level evidence so the dashboard can show what changed, why, and with what provenance.
 
 **Three-layer hierarchy:**

package/dashboard/app/api/governance/route.ts

@@ -0,0 +1,49 @@
+import { mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+import { NextResponse } from 'next/server'
+import { getActiveGovernanceSummary, loadGovernanceState } from '@/lib/data'
+
+export const dynamic = 'force-dynamic'
+
+const HELIX_DIR = join(homedir(), '.helix')
+const STATE_PATH = join(HELIX_DIR, 'governance-state.json')
+const MODES = new Set(['conservative', 'balanced', 'exploration', 'project-critical', 'consolidation-focused', 'transfer-focused'])
+
+function ensureHelixDir() {
+  mkdirSync(HELIX_DIR, { recursive: true })
+}
+
+export async function GET() {
+  return NextResponse.json({
+    state: loadGovernanceState(),
+    summary: getActiveGovernanceSummary(),
+  })
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as { selectionMode?: 'auto' | 'manual'; manualMode?: string; note?: string }
+  const selectionMode = body.selectionMode === 'manual' && body.manualMode && MODES.has(body.manualMode)
+    ? 'manual'
+    : 'auto'
+
+  if (selectionMode === 'manual' && (!body.manualMode || !MODES.has(body.manualMode))) {
+    return NextResponse.json({ success: false, error: 'Invalid manual governance mode' }, { status: 400 })
+  }
+
+  ensureHelixDir()
+  const nextState = {
+    selectionMode,
+    manualMode: selectionMode === 'manual' ? body.manualMode : undefined,
+    updatedAt: new Date().toISOString(),
+    note: body.note?.trim() || undefined,
+  }
+
+  writeFileSync(STATE_PATH, JSON.stringify(nextState, null, 2))
+
+  return NextResponse.json({
+    success: true,
+    state: loadGovernanceState(),
+    summary: getActiveGovernanceSummary(),
+  })
+}

package/dashboard/app/api/run/route.ts

@@ -18,17 +18,44 @@ const ALLOWED_COMMANDS: Record<string, { cmd: string; args: string[]; timeout: n
   'report':         { cmd: 'helixevo', args: ['report', '--days', '7'],            timeout: 30000 },
 }
 
+function buildCommandEntry(body: { command: string; project?: string; path?: string }) {
+  const entry = ALLOWED_COMMANDS[body.command]
+  if (entry) return entry
+
+  if (body.command === 'specialize') {
+    if (!body.project) return null
+    return { cmd: 'helixevo', args: ['specialize', '--project', body.project, '--verbose'], timeout: 300000 }
+  }
+
+  if (body.command === 'specialize-dry') {
+    if (!body.project) return null
+    return { cmd: 'helixevo', args: ['specialize', '--project', body.project, '--dry-run', '--verbose'], timeout: 300000 }
+  }
+
+  if (body.command === 'research-project') {
+    if (!body.path) return null
+    return { cmd: 'helixevo', args: ['research', '--project', body.path, '--verbose'], timeout: 300000 }
+  }
+
+  if (body.command === 'research-project-dry') {
+    if (!body.path) return null
+    return { cmd: 'helixevo', args: ['research', '--project', body.path, '--dry-run', '--verbose'], timeout: 300000 }
+  }
+
+  return null
+}
+
 let activeProcess: ChildProcess | null = null
 let activeCommand: string | null = null
 
 // POST — stream output via SSE
 export async function POST(request: Request) {
-  const body = await request.json()
-  const { command } = body as { command: string }
+  const body = await request.json() as { command: string; project?: string; path?: string }
+  const { command } = body
 
-  const entry = ALLOWED_COMMANDS[command]
+  const entry = buildCommandEntry(body)
   if (!entry) {
-    return NextResponse.json({ success: false, error: `Unknown command: ${command}` }, { status: 400 })
+    return NextResponse.json({ success: false, error: `Unknown or incomplete command: ${command}` }, { status: 400 })
   }
 
   // Kill any existing process

package/dashboard/app/api/topology-apply/route.ts

@@ -0,0 +1,80 @@
+import { NextResponse } from 'next/server'
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { loadTopologyDashboardSummary } from '@/lib/data'
+
+export const dynamic = 'force-dynamic'
+
+function resolveTopologyRunner(): { cmd: string; argsPrefix: string[] } {
+  const candidates = [
+    join(process.cwd(), '..', 'dist', 'cli.js'),
+    join(process.cwd(), 'dist', 'cli.js'),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return { cmd: process.execPath, argsPrefix: [candidate] }
+    }
+  }
+
+  return { cmd: 'helixevo', argsPrefix: [] }
+}
+
+function runTopologyCommand(args: string[]): Promise<{ success: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const runner = resolveTopologyRunner()
+    const child = spawn(runner.cmd, [...runner.argsPrefix, 'topology', ...args], {
+      env: { ...process.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let output = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.on('close', (code) => {
+      resolve({ success: code === 0, output })
+    })
+    child.on('error', (err) => {
+      resolve({ success: false, output: `Error: ${err.message}` })
+    })
+  })
+}
+
+export async function GET() {
+  return NextResponse.json(loadTopologyDashboardSummary())
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as { action?: 'prepare' | 'apply' | 'rollback'; candidateId?: string; planId?: string }
+  if (!body.action) {
+    return NextResponse.json({ success: false, error: 'action is required' }, { status: 400 })
+  }
+
+  let args: string[] = []
+  if (body.action === 'prepare') {
+    if (!body.candidateId) return NextResponse.json({ success: false, error: 'candidateId is required for prepare' }, { status: 400 })
+    args = ['--prepare', body.candidateId]
+  } else if (body.action === 'apply') {
+    if (!body.planId) return NextResponse.json({ success: false, error: 'planId is required for apply' }, { status: 400 })
+    args = ['--apply', body.planId]
+  } else if (body.action === 'rollback') {
+    if (!body.planId) return NextResponse.json({ success: false, error: 'planId is required for rollback' }, { status: 400 })
+    args = ['--rollback', body.planId]
+  }
+
+  const result = await runTopologyCommand(args)
+  if (!result.success) {
+    return NextResponse.json({ success: false, error: result.output || 'Topology command failed' }, { status: 500 })
+  }
+
+  return NextResponse.json({
+    success: true,
+    output: result.output,
+    dashboard: loadTopologyDashboardSummary(),
+  })
+}

package/dashboard/app/api/topology-review/route.ts

@@ -0,0 +1,51 @@
+import { mkdirSync, appendFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+import { NextResponse } from 'next/server'
+import { getActiveGovernanceSummary, loadResolvedTopologyReviewCandidates, loadTopologyDashboardSummary } from '@/lib/data'
+
+export const dynamic = 'force-dynamic'
+
+const HELIX_DIR = join(homedir(), '.helix')
+const DECISIONS_PATH = join(HELIX_DIR, 'topology-review-decisions.jsonl')
+const DECISIONS = new Set(['accepted', 'rejected', 'deferred'])
+
+function ensureHelixDir() {
+  mkdirSync(HELIX_DIR, { recursive: true })
+}
+
+export async function GET() {
+  return NextResponse.json(loadTopologyDashboardSummary())
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as { candidateId?: string; decision?: 'accepted' | 'rejected' | 'deferred'; rationale?: string }
+  if (!body.candidateId || !body.decision || !DECISIONS.has(body.decision)) {
+    return NextResponse.json({ success: false, error: 'candidateId and a valid decision are required' }, { status: 400 })
+  }
+
+  const candidate = loadResolvedTopologyReviewCandidates().find((entry) => entry.id === body.candidateId)
+  if (!candidate) {
+    return NextResponse.json({ success: false, error: 'Unknown topology review candidate' }, { status: 404 })
+  }
+
+  const governance = getActiveGovernanceSummary()
+  const record = {
+    id: `topology_decision_${body.decision}_${body.candidateId}_${Date.now()}`.replace(/[^a-zA-Z0-9_-]/g, '-'),
+    candidateId: body.candidateId,
+    decision: body.decision,
+    decidedAt: new Date().toISOString(),
+    governanceMode: governance.activeMode,
+    rationale: body.rationale?.trim() || `${body.decision} via operator review`,
+    decidedBy: 'operator',
+  }
+
+  ensureHelixDir()
+  appendFileSync(DECISIONS_PATH, JSON.stringify(record) + '\n')
+
+  return NextResponse.json({
+    success: true,
+    candidate: loadResolvedTopologyReviewCandidates().find((entry) => entry.id === body.candidateId) ?? null,
+    dashboard: loadTopologyDashboardSummary(),
+  })
+}