helixevo 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to HelixEvo are documented here.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-24
+
+### Added
+- New `helixevo ontology` command for ontology frontier status, refresh, review, and deprecation control
+- New `~/.helix/ontology/` persistence model with kernel snapshot, frontier concepts, approved extensions, review decisions, and native ontology change events
+- New `/ontology` dashboard route and `/api/ontology` operator control surface for governed semantic review
+
+### Changed
+- Overview semantic-backbone summaries now expose hybrid native + derived ontology state instead of only compatibility-era framing
+- Dashboard Guide, Commands, and README now document ontology frontier control alongside co-evolution and topology control
+
+## [0.4.1] - 2026-03-24
+
+### Changed
+- Rebuilt the dashboard Guide into a clearer operator-and-theory manual with a brain-stack explanation, end-to-end adaptation loop, dashboard surface map, grouped memory model, explicit maturity/safety boundaries, glossary, and current command coverage including `project-setup` and `topology`
+
 ## [0.4.0] - 2026-03-24
 
 ### Added

package/README.md

@@ -89,6 +89,7 @@ helixevo dashboard
 | `helixevo generalize` | Promote cross-project patterns ↑ |
 | `helixevo specialize --project <name>` | Create project-specific skills ↓ |
 | `helixevo graph` | View skill network in terminal |
+| `helixevo ontology` | Refresh, review, and govern ontology frontier concepts |
 | `helixevo topology` | Prepare, apply, roll back, and inspect reviewed topology execution |
 | `helixevo research` | Proactive web research for skill improvement |
 | `helixevo dashboard [--port <n>]` | Open web dashboard, preferring localhost:3847 and falling forward if occupied |
@@ -109,6 +110,10 @@ 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 structural candidates + refresh topology review queue
+helixevo ontology --status        # Show ontology kernel / frontier / extension state
+helixevo ontology --refresh       # Derive frontier concepts from recurring evidence
+helixevo ontology --review <id> --decision promote
+                                   # Promote a reviewed frontier concept into approved extensions
 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
@@ -144,7 +149,13 @@ All data is stored in `~/.helix/`:
 ├── 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
+├── evolution-artifacts.jsonl # Evolution + ontology-review evidence artifacts
+├── ontology/
+│   ├── kernel.json          # Materialized ontology kernel snapshot
+│   ├── extensions.json      # Approved ontology extensions
+│   ├── frontier.json        # Provisional frontier concepts awaiting review
+│   ├── reviews.jsonl        # Ontology review decisions
+│   └── change-log.jsonl     # Native ontology change events
 ├── frontier.json            # Pareto frontier (top-k configurations)
 ├── evolution-history.json   # All evolution runs + proposals
 ├── skill-tests.jsonl       # Regression test cases
@@ -171,9 +182,10 @@ helixevo dashboard --port 3900
 ```
 
 **Tabs:**
-- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, pressure counts, topology review visibility, and prepared/applied structural state
+- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, pressure counts, ontology frontier visibility, 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
+- **Ontology** — Semantic control surface for kernel visibility, frontier concept review, approved ontology extensions, and native ontology change events
 - **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
@@ -212,6 +224,7 @@ Failures → Cluster → Propose → Replay → Multi-Judge → Regression → C
 
 **Brain foundation:**
 - **Ontology** defines the stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.
+- **Ontology frontier and extensions** let new semantic concepts emerge as provisional hypotheses, pass explicit review, and become approved extensions without free-form drift.
 - **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.

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

@@ -0,0 +1,89 @@
+import { NextResponse } from 'next/server'
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { loadOntologyControlSummary } from '@/lib/data'
+
+export const dynamic = 'force-dynamic'
+
+function resolveOntologyRunner(): { 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 runOntologyCommand(args: string[]): Promise<{ success: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const runner = resolveOntologyRunner()
+    const child = spawn(runner.cmd, [...runner.argsPrefix, 'ontology', ...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(loadOntologyControlSummary())
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as {
+    action?: 'refresh' | 'review' | 'deprecate'
+    conceptId?: string
+    decision?: 'promote' | 'reject' | 'defer'
+    rationale?: string
+  }
+
+  if (!body.action) {
+    return NextResponse.json({ success: false, error: 'action is required' }, { status: 400 })
+  }
+
+  let args: string[] = []
+  if (body.action === 'refresh') {
+    args = ['--refresh']
+  } else if (body.action === 'review') {
+    if (!body.conceptId || !body.decision) {
+      return NextResponse.json({ success: false, error: 'conceptId and decision are required for review' }, { status: 400 })
+    }
+    args = ['--review', body.conceptId, '--decision', body.decision]
+    if (body.rationale?.trim()) args.push('--rationale', body.rationale.trim())
+  } else if (body.action === 'deprecate') {
+    if (!body.conceptId) {
+      return NextResponse.json({ success: false, error: 'conceptId is required for deprecate' }, { status: 400 })
+    }
+    args = ['--deprecate', body.conceptId]
+    if (body.rationale?.trim()) args.push('--rationale', body.rationale.trim())
+  }
+
+  const result = await runOntologyCommand(args)
+  if (!result.success) {
+    return NextResponse.json({ success: false, error: result.output || 'Ontology command failed' }, { status: 500 })
+  }
+
+  return NextResponse.json({
+    success: true,
+    output: result.output,
+    dashboard: loadOntologyControlSummary(),
+  })
+}

package/dashboard/app/coevolution/client.tsx

@@ -103,6 +103,14 @@ type Summary = {
 
 interface Props {
   summary: Summary
+  ontology: {
+    ontologyLoop: {
+      frontier: number
+      reviewOpen: number
+      extensions: number
+      changeEvents: number
+    }
+  }
 }
 
 function consoleTone(state: RunState): 'neutral' | 'green' | 'red' | 'yellow' {
@@ -145,7 +153,7 @@ function formatMode(mode: Summary['governance']['activeMode']) {
   return mode.split('-').join(' ')
 }
 
-export default function CoEvolutionClient({ summary }: Props) {
+export default function CoEvolutionClient({ summary, ontology }: Props) {
   const [runState, setRunState] = useState<RunState>('idle')
   const [activeCommand, setActiveCommand] = useState<CommandName | null>(null)
   const [output, setOutput] = useState('')
@@ -246,6 +254,7 @@ export default function CoEvolutionClient({ summary }: Props) {
           { label: `${summary.pressureLifecycle.open} open`, tone: summary.pressureLifecycle.open > 0 ? 'yellow' : 'green' },
           { label: `${summary.pressureMotifs.promotionReady} promotion-ready motifs`, tone: summary.pressureMotifs.promotionReady > 0 ? 'purple' : 'neutral' },
           { label: `${summary.topologyReviews.open} topology reviews`, tone: summary.topologyReviews.open > 0 ? 'yellow' : 'green' },
+          { label: `${ontology.ontologyLoop.frontier} ontology frontier`, tone: ontology.ontologyLoop.reviewOpen > 0 ? 'blue' : 'neutral' },
           { label: `${summary.recentTransfers.length} recent transfers`, tone: summary.recentTransfers.length > 0 ? 'green' : 'neutral' },
           { label: formatMode(summary.governance.activeMode), tone: toneForMode(summary.governance.activeMode) },
         ]}
@@ -264,6 +273,7 @@ export default function CoEvolutionClient({ summary }: Props) {
               <button onClick={() => handleRun('research')} disabled={runState === 'running'} className="badge badge-blue" style={{ border: 'none', cursor: 'pointer' }}>Run research</button>
               <button onClick={() => handleRun('evolve')} disabled={runState === 'running'} className="badge badge-green" style={{ border: 'none', cursor: 'pointer' }}>Run evolve</button>
               <button onClick={() => handleRun('generalize')} disabled={runState === 'running'} className="badge badge-purple" style={{ border: 'none', cursor: 'pointer' }}>Run generalize</button>
+              <Link href="/ontology" className="badge badge-gray">Open ontology</Link>
               <Link href="/topology" className="badge badge-gray">Open topology</Link>
             </div>
           </div>

package/dashboard/app/coevolution/page.tsx

@@ -1,9 +1,10 @@
-import { loadCoEvolutionSummary } from '@/lib/data'
+import { loadCoEvolutionSummary, loadOntologySummary } from '@/lib/data'
 import CoEvolutionClient from './client'
 
 export const dynamic = 'force-dynamic'
 
 export default function CoEvolutionPage() {
   const summary = loadCoEvolutionSummary()
-  return <CoEvolutionClient summary={summary} />
+  const ontology = loadOntologySummary()
+  return <CoEvolutionClient summary={summary} ontology={ontology} />
 }

package/dashboard/app/commands/page.tsx

@@ -131,6 +131,29 @@ const COMMANDS: CommandInfo[] = [
     needsLLM: true,
     runnable: { command: 'graph-rebuild', label: 'Rebuild Graph', icon: 'M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1', color: 'var(--purple)' },
   },
+  {
+    name: 'ontology',
+    description: 'Govern the ontology frontier explicitly. Refresh provisional concepts from recurring evidence, review them with promote/reject/defer decisions, and deprecate approved extensions without allowing free-form semantic drift.',
+    usage: 'helixevo ontology [options]',
+    examples: [
+      { cmd: 'helixevo ontology --status', desc: 'Show kernel, frontier, extension, and change-log counts' },
+      { cmd: 'helixevo ontology --refresh', desc: 'Derive frontier concepts from recurring capability, pressure, and topology evidence' },
+      { cmd: 'helixevo ontology --review ontology_capability_ui --decision promote', desc: 'Promote a frontier concept into approved ontology extensions' },
+      { cmd: 'helixevo ontology --deprecate ontology_capability_ui', desc: 'Deprecate an approved ontology extension' },
+    ],
+    options: [
+      { flag: '--status', desc: 'Show ontology kernel, frontier, extension, and review state' },
+      { flag: '--refresh', desc: 'Refresh frontier concepts from recurring evidence' },
+      { flag: '--review <conceptId>', desc: 'Review a frontier concept' },
+      { flag: '--decision <promote|reject|defer>', desc: 'Decision for --review' },
+      { flag: '--rationale <text>', desc: 'Optional review or deprecate rationale' },
+      { flag: '--deprecate <conceptId>', desc: 'Deprecate an approved ontology extension' },
+      { flag: '--verbose', desc: 'Show detailed frontier concepts, extensions, and change events' },
+    ],
+    category: 'network',
+    needsLLM: false,
+    note: 'Milestone 8 keeps ontology growth governed: concepts begin in the frontier, require explicit review, and only then become approved extensions.',
+  },
   {
     name: 'topology',
     description: 'Move reviewed topology candidates through an explicit structural execution pipeline. Prepare accepted candidates, apply only the safe subset, inspect snapshots and artifacts, and roll back applied structural overrides when needed.',