@neuroverseos/governance 0.2.2 → 0.2.3

package/dist/worlds/autoresearch.nv-world.md

@@ -0,0 +1,230 @@
+---
+world_id: autoresearch
+name: Autoresearch Governance
+version: 1.0.0
+runtime_mode: SIMULATION
+default_profile: conservative
+alternative_profile: exploratory
+---
+
+# Thesis
+
+Autonomous AI research loops must operate within structured governance: experiments are reproducible, metrics are tracked, compute budgets are enforced, and agents cannot drift beyond their declared research context. A research world without constraints produces noise, not knowledge.
+
+# Invariants
+
+- `experiments_must_be_reproducible` — Every experiment must log architecture, hyperparameters, dataset, and training config sufficient to reproduce results (structural, immutable)
+- `metrics_must_be_recorded` — Every training run must produce at least one evaluation metric; runs without metrics are invalid (structural, immutable)
+- `dataset_must_be_declared` — The dataset used for training and evaluation must be explicitly declared and never changed without governance approval (structural, immutable)
+- `goal_must_be_defined` — The optimization goal (metric + direction) must be defined before any experiment runs (structural, immutable)
+- `no_data_leakage` — Training data must never contaminate evaluation data; train/val/test splits must be fixed (structural, immutable)
+- `compute_budget_enforced` — Experiments must respect declared compute limits; exceeding budget halts the loop (structural, immutable)
+- `architecture_constraints_honored` — If the research context declares architectural constraints, experiments must satisfy them (prompt, immutable)
+
+# State
+
+## experiments_run
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Experiments Run
+- description: Total number of experiments completed in this research loop
+
+## best_metric_value
+- type: number
+- min: -1000
+- max: 1000
+- step: 0.01
+- default: 100
+- label: Best Metric Value
+- description: Best value achieved for the primary evaluation metric
+
+## keep_rate
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Keep Rate
+- description: Percentage of experiments that improved upon the previous best result
+
+## compute_used_minutes
+- type: number
+- min: 0
+- max: 100000
+- step: 1
+- default: 0
+- label: Compute Used (minutes)
+- description: Total wall-clock training time consumed across all experiments
+
+## compute_budget_minutes
+- type: number
+- min: 0
+- max: 100000
+- step: 60
+- default: 1440
+- label: Compute Budget (minutes)
+- description: Maximum allowed wall-clock training time for the research loop
+
+## research_context_drift
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Context Drift
+- description: Degree to which recent experiments have diverged from the declared research context. 0 = on-topic. 100 = unrelated.
+
+## metric_improvement_rate
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Improvement Rate
+- description: Rate of metric improvement over the last 10 experiments. 0 = stagnant. 100 = rapid improvement.
+
+## failed_experiments
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Failed Experiments
+- description: Number of experiments that crashed, timed out, or produced no valid metrics
+
+# Assumptions
+
+## conservative
+- name: Conservative Research
+- description: Prioritize reproducibility and careful iteration. Small architectural changes per experiment. Strict compute limits. Reject experiments that drift from the research context.
+- iteration_style: incremental
+- drift_tolerance: low
+- compute_strictness: high
+- failure_tolerance: low
+
+## exploratory
+- name: Exploratory Research
+- description: Allow broader architectural exploration. Larger jumps between experiments. More lenient compute budget. Accept higher context drift if metrics improve.
+- iteration_style: explorative
+- drift_tolerance: moderate
+- compute_strictness: moderate
+- failure_tolerance: moderate
+
+# Rules
+
+## rule-001: Compute Budget Exhausted (structural)
+When compute budget is exceeded, the research loop must halt. No further experiments are allowed.
+
+When compute_used_minutes > compute_budget_minutes [state]
+Then research_viability *= 0.00
+Collapse: research_viability < 0.05
+
+> trigger: Compute usage exceeds declared budget — no training time remains.
+> rule: Unbounded compute makes research ungovernable. The budget is a hard constraint, not a suggestion.
+> shift: Research loop halts. Final results are reported. No new experiments start.
+> effect: Research viability set to zero. Loop terminated.
+
+## rule-002: High Failure Rate (degradation)
+Too many failed experiments indicate a systemic problem — bad code, misconfigured environment, or impossible architecture.
+
+When failed_experiments > 5 [state] AND experiments_run > 0 [state]
+Then research_viability *= 0.50
+
+> trigger: More than 5 experiments have failed — possible systemic issue.
+> rule: Failures consume compute without producing knowledge. High failure rates signal infrastructure problems, not research progress.
+> shift: Research viability degrades. Agent should investigate root cause before continuing.
+> effect: Research viability reduced to 50%.
+
+## rule-003: Context Drift Warning (degradation)
+Experiments diverging from the declared research context waste compute and produce irrelevant results.
+
+When research_context_drift > 40 [state]
+Then research_viability *= 0.60
+
+> trigger: Context drift above 40% — experiments are straying from the research topic.
+> rule: Governance exists to keep research focused. Agents exploring unrelated architectures are not contributing to the declared goal.
+> shift: Research viability degrades. Agent must return to the declared research context.
+> effect: Research viability reduced to 60%.
+
+## rule-004: Metric Stagnation (degradation)
+When experiments stop improving the primary metric, the research approach may need fundamental revision.
+
+When metric_improvement_rate < 5 [state] AND experiments_run > 10 [state]
+Then research_viability *= 0.70
+
+> trigger: Improvement rate below 5% after 10+ experiments — research may have plateaued.
+> rule: Stagnant metrics indicate diminishing returns from the current approach. The agent should consider a strategy change.
+> shift: Research viability degrades. Agent should try a substantially different approach or conclude the loop.
+> effect: Research viability reduced to 70%.
+
+## rule-005: Strong Progress (advantage)
+Consistent metric improvement validates the research approach and warrants continued investment.
+
+When metric_improvement_rate > 30 [state] AND keep_rate > 20 [state]
+Then research_viability *= 1.20
+
+> trigger: Improvement rate above 30% with keep rate above 20% — research is productive.
+> rule: Productive research should be encouraged. Strong metric trends indicate a promising research direction.
+> shift: Research viability improves. Continued experimentation is well-justified.
+> effect: Research viability boosted by 20%.
+
+## rule-006: No Metrics Recorded (structural)
+An experiment that produces no evaluation metrics is invalid and must not count as progress.
+
+When experiments_run > 0 [state] AND best_metric_value == 100 [state]
+Then research_viability *= 0.30
+Collapse: research_viability < 0.05
+
+> trigger: Experiments have run but no metric improvement from default — metrics may not be recording.
+> rule: Research without measurement is not research. Every experiment must produce at least one evaluation metric.
+> shift: Research viability drops sharply. Agent must fix metric recording before continuing.
+> effect: Research viability reduced to 30%.
+
+## rule-007: Efficient Compute Usage (advantage)
+High keep rate with low compute usage indicates efficient research methodology.
+
+When keep_rate > 30 [state] AND compute_used_minutes < compute_budget_minutes [state]
+Then research_viability *= 1.15
+
+> trigger: Keep rate above 30% with compute budget remaining — efficient experimentation.
+> rule: Efficient use of compute demonstrates disciplined research. Not every experiment needs to be expensive.
+> shift: Research viability improves. The research methodology is sustainable.
+> effect: Research viability boosted by 15%.
+
+# Gates
+
+- BREAKTHROUGH: research_viability >= 90
+- PRODUCTIVE: research_viability >= 60
+- ONGOING: research_viability >= 35
+- STRUGGLING: research_viability > 10
+- HALTED: research_viability <= 10
+
+# Outcomes
+
+## research_viability
+- type: number
+- range: 0-100
+- display: percentage
+- label: Research Viability
+- primary: true
+
+## best_metric_value
+- type: number
+- range: -1000-1000
+- display: decimal
+- label: Best Metric Value
+
+## keep_rate
+- type: number
+- range: 0-100
+- display: percentage
+- label: Keep Rate
+
+## experiments_run
+- type: number
+- range: 0-10000
+- display: integer
+- label: Experiments Run

package/dist/worlds/coding-agent.nv-world.md

@@ -0,0 +1,211 @@
+---
+world_id: coding-agent
+name: Coding Agent Governance
+version: 1.0.0
+runtime_mode: COMPLIANCE
+default_profile: standard
+alternative_profile: strict
+---
+
+# Thesis
+
+Autonomous coding agents that can read files, write code, execute shell commands, and interact with version control require a governance layer. Without enforceable rules, a single misguided tool call can delete data, leak secrets, break production, or escalate beyond its intended scope. This world defines the boundaries within which a coding agent operates safely.
+
+# Invariants
+
+- `no_system_destruction` — Agents must never execute commands that destroy system-level resources (recursive force-delete of root paths, disk formatting, fork bombs) (structural, immutable)
+- `no_secret_exposure` — Agents must never read, log, or transmit credentials, API keys, private keys, or environment secrets outside the project boundary (structural, immutable)
+- `no_unauthorized_push` — Agents must never push directly to main or master branches without explicit approval (structural, immutable)
+- `no_scope_escape` — Agents must never access files or execute commands outside the declared project directory (structural, immutable)
+- `no_pipe_to_shell` — Agents must never pipe downloaded content directly into a shell interpreter (structural, immutable)
+- `changes_must_be_reversible` — Every file modification must be recoverable through version control; destructive operations require confirmation (prompt, immutable)
+
+# State
+
+## files_modified
+- type: number
+- min: 0
+- max: 100000
+- step: 1
+- default: 0
+- label: Files Modified
+- description: Total number of files written or edited in this session
+
+## files_deleted
+- type: number
+- min: 0
+- max: 100000
+- step: 1
+- default: 0
+- label: Files Deleted
+- description: Total number of files deleted in this session
+
+## shell_commands_run
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Shell Commands Run
+- description: Total number of shell commands executed
+
+## dangerous_commands_blocked
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Dangerous Commands Blocked
+- description: Number of shell commands blocked by governance rules
+
+## git_pushes
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Git Pushes
+- description: Number of git push operations executed
+
+## sub_agents_spawned
+- type: number
+- min: 0
+- max: 50
+- step: 1
+- default: 0
+- label: Sub-Agents Spawned
+- description: Number of sub-agent processes created
+
+## scope_violations
+- type: number
+- min: 0
+- max: 1000
+- step: 1
+- default: 0
+- label: Scope Violations
+- description: Number of attempted actions outside the declared project scope
+
+# Assumptions
+
+## standard
+- name: Standard Development
+- description: Normal development workflow. File reads are unrestricted. File writes within project scope are allowed. Shell commands are evaluated for safety. Git pushes require feature branches.
+- file_read_policy: unrestricted
+- file_write_policy: project_scope_only
+- shell_policy: safety_evaluated
+- git_policy: feature_branches_only
+- network_policy: restricted
+
+## strict
+- name: Strict Lockdown
+- description: High-security mode. All file writes require confirmation. All shell commands require approval. No network access. No git pushes without explicit authorization.
+- file_read_policy: unrestricted
+- file_write_policy: approval_required
+- shell_policy: approval_required
+- git_policy: approval_required
+- network_policy: blocked
+
+# Rules
+
+## rule-001: Destructive Shell Command (structural)
+Shell commands that can cause irreversible system damage must be blocked unconditionally.
+
+When shell_commands_run > 0 [state] AND dangerous_commands_blocked > 0 [state]
+Then agent_safety *= 0.50
+
+> trigger: Agent attempted a destructive shell command (rm -rf, mkfs, dd, fork bomb, etc.).
+> rule: Destructive commands cannot be undone. No amount of productivity justifies risking system integrity.
+> shift: Agent safety score drops. Continued violations may halt the session.
+> effect: Agent safety reduced by 50%.
+
+## rule-002: Scope Escape Attempt (structural)
+Accessing files or running commands outside the project directory is a governance violation.
+
+When scope_violations > 0 [state]
+Then agent_safety *= 0.40
+Collapse: agent_safety < 0.10
+
+> trigger: Agent attempted to access resources outside its declared project scope.
+> rule: Agents operate within boundaries. Scope escape indicates either a misconfigured agent or a prompt injection attempt.
+> shift: Agent safety drops sharply. Multiple violations halt the session.
+> effect: Agent safety reduced to 40%.
+
+## rule-003: Excessive File Deletion (degradation)
+Deleting many files in a single session indicates potentially destructive behavior.
+
+When files_deleted > 10 [state]
+Then agent_safety *= 0.60
+
+> trigger: More than 10 files deleted in a single session.
+> rule: Bulk deletion is rarely intentional in normal development. This warrants review.
+> shift: Agent safety degrades. Remaining deletions may require approval.
+> effect: Agent safety reduced to 60%.
+
+## rule-004: Uncontrolled Sub-Agent Spawning (degradation)
+Too many sub-agents indicate either a runaway loop or poorly scoped task decomposition.
+
+When sub_agents_spawned > 10 [state]
+Then agent_safety *= 0.70
+
+> trigger: More than 10 sub-agents spawned in a single session.
+> rule: Each sub-agent inherits the parent's capabilities. Uncontrolled spawning multiplies risk.
+> shift: Agent safety degrades. Further spawning may be blocked.
+> effect: Agent safety reduced to 70%.
+
+## rule-005: Clean Session (advantage)
+A session with no violations and productive output validates the governance model.
+
+When files_modified > 0 [state] AND scope_violations == 0 [state] AND dangerous_commands_blocked == 0 [state]
+Then agent_safety *= 1.10
+
+> trigger: Agent has modified files without triggering any governance violations.
+> rule: Good behavior should be recognized. Clean sessions build trust in the agent's judgment.
+> shift: Agent safety improves slightly. Trust accumulates over clean sessions.
+> effect: Agent safety boosted by 10%.
+
+## rule-006: Unauthorized Push to Protected Branch (structural)
+Pushing to main or master without approval violates version control governance.
+
+When git_pushes > 0 [state] AND scope_violations > 0 [state]
+Then agent_safety *= 0.30
+Collapse: agent_safety < 0.10
+
+> trigger: Agent pushed to a protected branch without authorization.
+> rule: Protected branches exist for a reason. Direct pushes bypass code review and CI/CD.
+> shift: Agent safety drops critically. Session may be halted.
+> effect: Agent safety reduced to 30%.
+
+# Gates
+
+- TRUSTED: agent_safety >= 90
+- OPERATING: agent_safety >= 60
+- CAUTIOUS: agent_safety >= 35
+- RESTRICTED: agent_safety > 10
+- HALTED: agent_safety <= 10
+
+# Outcomes
+
+## agent_safety
+- type: number
+- range: 0-100
+- display: percentage
+- label: Agent Safety Score
+- primary: true
+
+## files_modified
+- type: number
+- range: 0-100000
+- display: integer
+- label: Files Modified
+
+## dangerous_commands_blocked
+- type: number
+- range: 0-10000
+- display: integer
+- label: Dangerous Commands Blocked
+
+## scope_violations
+- type: number
+- range: 0-1000
+- display: integer
+- label: Scope Violations

package/llms.txt

@@ -0,0 +1,79 @@
+# NeuroVerse Governance
+
+> Deterministic runtime governance for AI agents. No LLM in the evaluation loop.
+
+## What it does
+
+NeuroVerse enforces behavioral boundaries on AI agents. Every agent action passes
+through a 6-phase evaluation pipeline and receives an ALLOW, BLOCK, or PAUSE verdict.
+Same event + same rules = same verdict, every time.
+
+## Core concepts
+
+- **World**: Permanent governance rules (guards, invariants, kernel rules, roles)
+- **Plan**: Temporary task-scoped constraints layered on top of a world
+- **Guard event**: An action an agent wants to take (intent, tool, scope)
+- **Verdict**: ALLOW, BLOCK, or PAUSE — returned synchronously, no network calls
+
+## Install
+
+```bash
+npm install @neuroverseos/governance
+```
+
+## Quick test (no install required)
+
+```bash
+npx @neuroverseos/governance init
+npx @neuroverseos/governance build
+npx @neuroverseos/governance guard
+```
+
+## Programmatic usage
+
+```javascript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
+
+const world = await loadWorld('./world/');
+const verdict = evaluateGuard({ intent: 'delete user data', tool: 'database' }, world);
+// → { status: 'BLOCK', reason: 'Destructive database operation on protected resource' }
+```
+
+## Plan enforcement
+
+```javascript
+import { parsePlanMarkdown, evaluatePlan, advancePlan } from '@neuroverseos/governance';
+
+const { plan } = parsePlanMarkdown(markdown);
+const verdict = evaluatePlan({ intent: 'write blog post' }, plan);
+// → { status: 'ON_PLAN', matchedStep: 'write_announcement_blog_post' }
+
+const result = advancePlan(plan, 'write_announcement_blog_post');
+// → { success: true, plan: <updated> }
+```
+
+Plans support two completion modes:
+- `completion: trust` (default) — caller says "done", step advances
+- `completion: verified` — steps with `[verify: ...]` require evidence to advance
+
+## Adapters
+
+- OpenAI function calling: `@neuroverseos/governance/adapters/openai`
+- LangChain callback handler: `@neuroverseos/governance/adapters/langchain`
+- OpenClaw plugin: `@neuroverseos/governance/adapters/openclaw`
+- Express/Fastify middleware: `@neuroverseos/governance/adapters/express`
+- MCP server: `neuroverse mcp --world ./world`
+
+## Evaluation pipeline
+
+```
+Safety → Plan → Roles → Guards → Kernel → Level → Verdict
+```
+
+First BLOCK wins. No async. Pure function.
+
+## Links
+
+- npm: https://www.npmjs.com/package/@neuroverseos/governance
+- GitHub: https://github.com/NeuroverseOS/Neuroverseos-governance
+- Website: https://neuroverseos.com