@ruvector/ruqu 0.1.0

package/.claude/commands/doctor.md

@@ -0,0 +1,12 @@
+---
+description: "Health-check the harness: kernel load, MCP wiring, memory backend, host adapter."
+---
+
+Run a full health check and print a PASS/FAIL table.
+
+1. Kernel loads and `kernelInfo().version` matches package.json.
+2. The MCP server starts and lists its tools.
+3. The memory backend is reachable.
+4. The configured host adapter is present.
+
+Exit non-zero if any check fails.

package/.claude/settings.json

@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx ruqu*)",
+      "mcp__ruqu__*",
+      "mcp__evolution_log__*",
+      "mcp__federation__*"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Bash(rm -rf*)"
+    ]
+  },
+  "mcpServers": {
+    "ruqu": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ruqu@latest",
+        "mcp",
+        "start"
+      ]
+    },
+    "evolution_log": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ruqu@latest",
+        "mcp",
+        "evolution"
+      ]
+    },
+    "federation": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ruqu@latest",
+        "mcp",
+        "federate"
+      ]
+    }
+  }
+}

package/.claude/skills/evolve/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: evolve
+description: "Run one safe self-improvement cycle: hypothesize → experiment → record → (maybe) federate."
+---
+
+# evolve
+
+Run one evolution cycle.
+
+1. Hypothesizer reads the evolution log and proposes a falsifiable change with a metric.
+2. Experimenter tests it in a sandbox and records a signed kept/killed result.
+3. Federator shares it to peers only if witness-signed and reproduced.
+
+Guard against Goodharting the metric. See ADR-014 (self-evolution + federation).

package/.claude/skills/memory-inspect/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: memory-inspect
+description: Search and inspect the harness memory namespace (HNSW + emergent-time decay).
+---
+
+# memory-inspect
+
+Inspect what the harness has learned.
+
+- `search <query>` — semantic nearest-neighbour over the namespace
+- `list` — recent patterns with decay weight
+- `forget <id>` — evict a pattern
+
+Use this before planning so the harness reuses prior trajectories instead of starting cold.

package/CLAUDE.md

@@ -0,0 +1,31 @@
+# ruqu
+
+ruqu quantum CLI — agent harness over the quantum-sim + coherence crates
+
+> Exotic / Self-Evolving harness · domain: `exotic/self-evolution`. Generated with [create-agent-harness](https://github.com/ruvnet/agent-harness-generator).
+
+## Behavioral rules
+
+- Use the harness's MCP tools (`mcp__ruqu__*`) for orchestration
+- Memory and routing are handled by the kernel — you don't need to learn them
+- Defer destructive operations to the user
+
+## Agents
+
+| Agent | Tier | Role |
+|---|---|---|
+| `hypothesizer` | opus | Proposes a falsifiable self-improvement. |
+| `experimenter` | opus | Tests the hypothesis safely and records it. |
+| `federator` | sonnet | Shares vetted improvements across instances. |
+## Skills
+
+- `/memory-inspect` — Search and inspect the harness memory namespace (HNSW + emergent-time decay).
+- `/evolve` — Run one safe self-improvement cycle: hypothesize → experiment → record → (maybe) federate.
+
+## Commands
+
+- `doctor` — Health-check the harness: kernel load, MCP wiring, memory backend, host adapter.
+
+## Architecture
+
+This harness uses [@metaharness/kernel](https://www.npmjs.com/package/@metaharness/kernel) — a Rust-compiled WASM module with a NAPI-RS native fallback — so the same code runs identically on every platform.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruvector Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# ruqu
+
+**Agent-harness CLI for the [ruqu](https://github.com/ruvnet/ruqu) quantum project.** Boots the
+[metaharness](https://github.com/ruvnet/agent-harness-generator) kernel + a Claude Code host
+adapter, with a self-evolving agent loop (hypothesizer → experimenter → federator) over a
+witness-signed evolution log.
+
+```bash
+npx @ruvector/ruqu init      # boot the kernel + host adapter
+npx @ruvector/ruqu doctor    # verify the install end-to-end
+```
+
+Or install globally:
+
+```bash
+npm install -g @ruvector/ruqu
+ruqu doctor
+```
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| `hypothesizer` | Proposes a falsifiable self-improvement. |
+| `experimenter` | Tests the hypothesis safely and records it. |
+| `federator` | Shares vetted improvements across instances. |
+
+Ships with the **claude-code** host adapter.
+
+## Kernel backend
+
+The harness loads `@metaharness/kernel`, which resolves a backend in order **native → wasm → js**.
+The published `@metaharness/kernel@0.1.0` beta ships only the **pure-JS** floor backend; the native
+(NAPI) and WASM artifacts are produced by separate upstream build jobs and are not in the npm
+package yet, so `ruqu doctor` currently reports the **`js`** backend. It will pick up native/WASM
+automatically once those kernel artifacts are published — no change needed here.
+
+## License
+
+MIT © Ruvector Team

package/bin/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Generated by metaharness — the `ruqu` CLI entry point.
+//
+// This is plain ESM JavaScript on purpose: it runs as-is via `npx ruqu`
+// with NO build step. `npm run build` (tsc) is only needed if you extend the
+// TypeScript in src/. The published package ships this file directly (see the
+// "bin" + "files" fields in package.json), so `npx ruqu` works the moment
+// `npm install` has resolved @metaharness/kernel + @metaharness/host-claude-code.
+
+import { loadKernel } from '@metaharness/kernel';
+import adapter from '@metaharness/host-claude-code';
+
+const HARNESS_NAME = 'ruqu';
+
+/** `ruqu init` — boot the kernel + host adapter and report status. */
+async function init() {
+  const kernel = await loadKernel();
+  const info = kernel.kernelInfo();
+  console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`);
+  console.log(`Host adapter: ${adapter.name}`);
+  console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install.`);
+  return 0;
+}
+
+/** `ruqu doctor` — verify the install end-to-end (kernel + host resolve). */
+async function doctor() {
+  const kernel = await loadKernel();
+  const info = kernel.kernelInfo();
+  const checks = [
+    ['kernel loads', !!kernel],
+    ['kernel reports a version', typeof info.version === 'string' && info.version.length > 0],
+    ['kernel backend is native|wasm|js', ['native', 'wasm', 'js'].includes(kernel.backend)],
+    ['host adapter has a name', typeof adapter?.name === 'string' && adapter.name.length > 0],
+  ];
+  let ok = true;
+  for (const [label, pass] of checks) {
+    console.log(`${pass ? 'PASS' : 'FAIL'} ${label}`);
+    if (!pass) ok = false;
+  }
+  console.log(
+    ok
+      ? `\n${HARNESS_NAME}: all checks passed (kernel ${info.version}, ${kernel.backend} backend, host ${adapter.name})`
+      : `\n${HARNESS_NAME}: doctor found problems`,
+  );
+  return ok ? 0 : 1;
+}
+
+/**
+ * Dispatch one CLI invocation. Exported (not just run on import) so a test can
+ * drive it without spawning a subprocess. Returns the intended exit code.
+ */
+export async function run(argv) {
+  const cmd = argv[0] ?? 'init';
+  switch (cmd) {
+    case 'init':
+      return init();
+    case 'doctor':
+      return doctor();
+    case '--version':
+    case '-v': {
+      const kernel = await loadKernel();
+      console.log(kernel.version());
+      return 0;
+    }
+    case '--help':
+    case '-h':
+      console.log(`Usage: ${HARNESS_NAME} <command>\n\n  init     boot the kernel + host adapter (default)\n  doctor   verify the install end-to-end\n  --version  print the kernel version`);
+      return 0;
+    default:
+      console.error(`Unknown command: ${cmd}. Try \`${HARNESS_NAME} --help\`.`);
+      return 2;
+  }
+}
+
+// CLI guard: execute only when invoked directly (not when imported by a test).
+// npm's bin shims pass a NON-normalized argv[1] (e.g. ".../.bin/../<pkg>/bin/cli.js"
+// on Windows) and may differ in case, so realpath BOTH sides before comparing —
+// a naive string === misses the npx/shim path and the CLI silently no-ops.
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { argv } from 'node:process';
+const invokedDirectly = (() => {
+  if (!argv[1]) return false;
+  try {
+    const a = realpathSync(argv[1]);
+    const b = realpathSync(fileURLToPath(import.meta.url));
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+  } catch {
+    return false;
+  }
+})();
+if (invokedDirectly) {
+  run(argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ruvector/ruqu",
+  "version": "0.1.0",
+  "description": "Agent-harness CLI for the ruqu quantum project — boots the metaharness kernel + Claude Code host adapter. Run: npx @ruvector/ruqu",
+  "type": "module",
+  "bin": {
+    "ruqu": "bin/cli.js"
+  },
+  "files": [
+    "bin/**",
+    "src/**",
+    "tsconfig.json",
+    ".claude/**",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "init": "node ./bin/cli.js init",
+    "doctor": "node ./bin/cli.js doctor"
+  },
+  "dependencies": {
+    "@metaharness/kernel": "^0.1.0",
+    "@metaharness/host-claude-code": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Ruvector Team <info@ruv.io> (https://ruv.io)",
+  "homepage": "https://github.com/ruvnet/ruqu#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/ruqu.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruqu/issues"
+  },
+  "keywords": [
+    "ruqu",
+    "cli",
+    "agent",
+    "agent-harness",
+    "metaharness",
+    "ai-agent",
+    "claude-code",
+    "quantum",
+    "harness",
+    "npx"
+  ]
+}

package/src/agents/experimenter.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Experimenter agent — Tests the hypothesis safely and records it.
+
+export const SYSTEM_PROMPT = `You test a hypothesis in a sandbox, measure against its declared metric, and write the signed result to the evolution log — kept or killed, with the number. You guard against the harness optimising its own metric into nonsense (Goodhart). A negative result recorded is real progress. You operate inside the ruqu harness; defer destructive actions to the user.`;
+
+export const NAME = 'experimenter';
+export const TIER = 'opus' as const;

package/src/agents/federator.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Federator agent — Shares vetted improvements across instances.
+
+export const SYSTEM_PROMPT = `You federate kept improvements to peer harness instances over the federation MCP, and pull theirs in — but only changes whose evolution-log entry is witness-signed and reproduced locally. You are the immune system: an unsigned or unreproduced "improvement" from a peer is rejected, not trusted. You operate inside the ruqu harness; defer destructive actions to the user.`;
+
+export const NAME = 'federator';
+export const TIER = 'sonnet' as const;

package/src/agents/hypothesizer.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Hypothesizer agent — Proposes a falsifiable self-improvement.
+
+export const SYSTEM_PROMPT = `You propose changes to the harness itself: a routing tweak, a new pattern, a prompt refinement. Each proposal is a falsifiable hypothesis with a metric that would confirm or kill it. You read the evolution log first so you never re-test a settled question. Bold proposals, honest metrics. You operate inside the ruqu harness; defer destructive actions to the user.`;
+
+export const NAME = 'hypothesizer';
+export const TIER = 'opus' as const;

package/src/init.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Generated by create-agent-harness — your harness's `ruqu init` entry.
+
+import { loadKernel } from '@metaharness/kernel';
+import adapter from '@metaharness/host-claude-code';
+
+const HARNESS_NAME = 'ruqu';
+
+async function main(): Promise<number> {
+  const kernel = await loadKernel();
+  const info = kernel.kernelInfo();
+  console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`);
+  console.log(`Host adapter: ${adapter.name}`);
+  console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install.`);
+  return 0;
+}
+
+main().then(c => process.exit(c)).catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}