0xray 3.5.5 → 4.0.0

package/.opencode/skills/researcher/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: researcher
 description: Multi-repo analysis, documentation lookup, and implementation examples
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [research, researcher]
@@ -28,10 +28,23 @@ Multi-repo analysis, documentation lookup, and implementation examples.
 - **find_implementations**: Find implementations
 - **analyze_documentation**: Analyze documentation
 
-## Usage
+## When to invoke (autonomy-command)
 
-This skill provides research capabilities for researcher functionality.
+Lead dev dispatches researcher **before** major planning, refactors, or cross-repo work — not only when user says "research."
 
-## Integration
+| Trigger | Action |
+|---------|--------|
+| Major refactor / new phase | `search_codebase`, `get_documentation`, `find_implementation` |
+| Prior art / patterns | Search sibling repos (xray, groover, repertoire) |
+| Proposal analysis | `analyze_proposal` via xray-researcher MCP |
 
-Activated when research capabilities are requested through the skills system.
+## MCP tools (xray-researcher)
+
+- `get_documentation` — module/class docs (`target` required)
+- `search_codebase` — text search in workspace
+- `find_implementation` — locate implementations
+- `analyze_proposal` — governance-aware proposal review
+
+## Return shape for lead
+
+Summarize: findings (3–5 bullets), file paths, recommended next todos. Do not defer work back to lead without concrete patches or todos.

package/.opencode/skills/security-audit/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: security-audit
 description: Security auditing and compliance validation
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [security, security, audit]

package/.opencode/skills/security-scan/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: security-scan
 description: Security vulnerability scanning and assessment
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [security, security, scan]

package/.opencode/skills/session-management/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: session-management
 description: Manage user sessions and persistent state
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [infrastructure, session, management]

package/.opencode/skills/state-manager/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: state-manager
 description: Application state management and persistence
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [infrastructure, state, manager]

package/.opencode/skills/storyteller/SKILL.md

@@ -96,7 +96,7 @@ codex_terms: [5, 7, 32]  # Related Codex term numbers
 ```markdown
 ## What Next?
 
-- Related Codex terms: [codex.json](../../.opencode/xray/codex.json)
+- Related Codex terms: [codex.json](../../../../.xray/codex.json)
 - Next story to write: [suggestion]
 ```
 

package/.opencode/skills/strategist/SKILL.md

@@ -30,3 +30,15 @@ Think deeply before recommending. Consider trade-offs and long-term implications
 - Risk analysis and mitigation planning
 - High-level system design and framework evolution
 - Technical debt identification and prioritization
+
+## When to invoke (autonomy-command)
+
+Lead dev dispatches strategist when `analyze-complexity` score **>25** or work spans multiple repos/phases.
+
+| Output required | Format |
+|-----------------|--------|
+| Phased plan | Phase N + goal + definition of done |
+| Todo breakdown | ID, task, subagent assignment |
+| Risks | Top 3 with mitigations |
+
+Use `orchestrate-task` or Task subagent. Return actionable todos — not essays.

package/.opencode/skills/testing-best-practices/SKILL.md

@@ -0,0 +1,37 @@
+---
+source: framework
+name: testing-best-practices
+description: Testing best practices and quality assurance
+author: Xray Framework
+version: 1.0.0
+schema_version: "1.0"
+tags: [testing, testing, best, practices]
+capabilities:
+  - write_unit_tests
+  - write_integration_tests
+  - analyze_coverage
+dependencies: []
+
+mcp:
+  testing-best-practices:
+    command: node
+    args: [node_modules/0xray/dist/mcps/knowledge-skills/testing-best-practices.server.js]
+---
+
+# Testing Best Practices Skill
+
+Testing best practices and quality assurance.
+
+## Tools Available
+
+- **testing_practices**: Testing practices
+- **quality_assurance**: Quality assurance
+- **best_practices**: Best practices
+
+## Usage
+
+This skill provides testing capabilities for testing best practices functionality.
+
+## Integration
+
+Activated when testing capabilities are requested through the skills system.

package/.opencode/skills/testing-strategy/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: testing-strategy
 description: Design comprehensive testing strategies and optimize test coverage
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [testing, strategy, coverage, quality]
@@ -38,6 +38,17 @@ This skill helps design and optimize testing strategies for:
 - Test coverage optimization
 - Testing best practices implementation
 
-## Integration
+## Per-suite triage (autonomy-command rule 3)
 
-Provides testing expertise and coverage analysis when requested through the skills system.
+After major changes, **do not** run the full test suite first.
+
+```text
+1. Identify affected test file(s) from the diff
+2. Run ONE suite: npm test -- path/to/focused.test.ts
+3. Read ALL failure output — triage root cause
+4. Fix → rerun that suite until green
+5. Repeat for each affected suite
+6. Only then: npm test (full suite gate)
+```
+
+Lead dev owns every failure. No "pre-existing" deferrals.

package/.opencode/skills/ui-ux-design/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: ui-ux-design
 description: User interface and user experience design with mobile-first approach, cognitive simplicity, and accessibility-first principles
-author: StrRay Framework
+author: Xray Framework
 version: 2.1.0
 schema_version: "1.0"
 tags: [design, ui, ux, accessibility, mobile-first, visual-hierarchy, wcag, contrast, color-theory, dont-make-me-think]

package/.opencode/skills/xray-orchestrator/index.ts

@@ -0,0 +1,267 @@
+/**
+ * xray Orchestrator Skill
+ *
+ * OpenClaw skill that provides xray orchestration commands.
+ *
+ * @since 2026-03-14
+ */
+
+const API_BASE = process.env.XRAY_API_URL || 'http://localhost:18431';
+const API_KEY = process.env.XRAY_API_KEY;
+
+interface ParsedArgs extends Record<string, unknown> {
+  _?: string[];
+}
+
+function parseArgs(input: string): { command: string; args: ParsedArgs } {
+  const parts = input.trim().split(/\s+/);
+  const command = parts[0] || '';
+  const args: ParsedArgs = {};
+
+  for (const part of parts.slice(1)) {
+    if (part.startsWith('--')) {
+      const key = part.slice(2);
+      args[key] = true;
+    } else if (part.includes(':')) {
+      const colonIdx = part.indexOf(':');
+      const key = part.slice(0, colonIdx);
+      const value = part.slice(colonIdx + 1);
+      if (key && value) args[key] = value;
+    } else if (!args._) {
+      args._ = [];
+      args._.push(part);
+    } else {
+      args._.push(part);
+    }
+  }
+
+  return { command, args };
+}
+
+async function callAPI(endpoint: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (API_KEY) {
+    headers['Authorization'] = `Bearer ${API_KEY}`;
+  }
+
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method: data ? 'POST' : 'GET',
+    headers,
+    body: data ? JSON.stringify(data) : null,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+export async function handleSkill(input: string): Promise<string> {
+  const { command, args } = parseArgs(input);
+
+  try {
+    switch (command.toLowerCase()) {
+      // xray primary
+      case 'xray':
+      case 'xray-status':
+        return await handleStatus();
+
+      case 'xray-analyze':
+        return await handleAnalyze(args);
+
+      case 'xray-code':
+        return await handleCodeReview(args);
+
+      case 'xray-file':
+        return await handleFileRead(args);
+
+      case 'xray-exec':
+        return await handleExec(args);
+
+      case 'xray-help':
+        return handleHelp(args._ as string | undefined);
+
+      default:
+        return formatHelp();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `❌ Error: ${message}`;
+  }
+}
+
+async function handleStatus(): Promise<string> {
+  const health = await callAPI('/health') as { status: string; version: string; uptime: number };
+
+  return `🤖 xray Status
+
+• Status: ${health.status}
+• Version: ${health.version}
+• Uptime: ${formatUptime(health.uptime)}
+
+Use /xray-help for available commands.`;
+}
+
+async function handleAnalyze(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-analyze <file-path>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'analyze',
+    args: { filePath },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Analysis failed: ${result.error}`;
+  }
+
+  return `✅ Analysis complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleCodeReview(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+  const fix = args.fix === true;
+
+  if (!filePath) {
+    return '❌ Usage: /xray-code <file-path> [--fix]';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'code-review',
+    args: { filePath, fix },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Code review failed: ${result.error}`;
+  }
+
+  return `✅ Code review complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleFileRead(args: Record<string, unknown>): Promise<string> {
+  const rest = args._ as string[] | undefined;
+  const filePath = rest?.[0];
+  const range = rest?.[1];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-file <file-path> [line-start:line-end]';
+  }
+
+  let lineRange: { start?: number; end?: number } | undefined;
+  if (range?.includes(':')) {
+    const [rawStart, rawEnd] = range.split(':');
+    lineRange = {};
+    if (rawStart) lineRange.start = Number(rawStart);
+    if (rawEnd) lineRange.end = Number(rawEnd);
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'read',
+    args: { filePath, ...lineRange },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ File read failed: ${result.error}`;
+  }
+
+  return `📄 ${filePath}\n\`\`\`\n${result.result}\n\`\`\``;
+}
+
+async function handleExec(args: Record<string, unknown>): Promise<string> {
+  const command = (args._ as string[])?.[0];
+
+  if (!command) {
+    return '❌ Usage: /xray-exec <command>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'exec',
+    args: { command },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Execution failed: ${result.error}`;
+  }
+
+  return `✅ Command executed\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+function handleHelp(command?: string): string {
+  if (command) {
+    switch (command) {
+      case 'xray-analyze':
+        return `📖 /xray-analyze <file-path>
+
+Analyze code in a file.
+
+Example: /xray-analyze src/index.ts`;
+
+      case 'xray-code':
+        return `📖 /xray-code <file-path> [--fix]
+
+Perform code review on a file.
+Use --fix to attempt automatic fixes.
+
+Example: /xray-code src/utils/helper.ts
+Example: /xray-code src/utils/helper.ts --fix`;
+
+      case 'xray-file':
+        return `📖 /xray-file <file-path> [line-start:line-end]
+
+Read a file.
+Optionally specify line range.
+
+Example: /xray-file src/index.ts
+Example: /xray-file src/index.ts 1:50`;
+
+      case 'xray-exec':
+        return `📖 /xray-exec <command>
+
+Execute an arbitrary command.
+
+Example: /xray-exec list files src/`;
+
+      default:
+        return `Unknown command: ${command}`;
+    }
+  }
+
+  return formatHelp();
+}
+
+function formatHelp(): string {
+  return `🤖 xray Orchestrator
+
+Available Commands:
+• /xray - Show status
+• /xray-analyze <file> - Analyze code
+• /xray-code <file> [--fix] - Code review
+• /xray-file <file> [lines] - Read file
+• /xray-exec <command> - Execute command
+• /xray-help [command] - Show help
+
+Use /xray-help <command> for detailed usage.`;
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${seconds}s`;
+}
+
+// Export for OpenClaw
+export default { handleSkill };

package/.xray/codex.json

@@ -1,6 +1,6 @@
 {
   "version": "3.1.0",
-  "lastUpdated": "2026-06-05",
+  "lastUpdated": "2026-08-24",
   "errorPreventionTarget": 0.998,
   "terms": {
     "1": {
@@ -546,6 +546,14 @@
       "category": "process",
       "zeroTolerance": false,
       "enforcementLevel": "high"
+    },
+    "69": {
+      "number": 69,
+      "title": "No New MCP, Skill, or Handler Surface",
+      "description": "Do not add parallel APIs. Rewire existing MCP servers, skills, and orchestrator handlers. PreToolUse denies creating new src/mcps/*.server.ts, src/skills/*/SKILL.md, or orchestrator *-handler files. Existing files may be rewritten.",
+      "category": "process",
+      "zeroTolerance": true,
+      "enforcementLevel": "blocking"
     }
   },
   "interweaves": [
@@ -589,10 +597,11 @@
     "No type errors or any usage": true,
     "Agent spawns go through governor": true,
     "Subagent spawning prevented": true,
-    "PostProcessor validation passes": true
+    "PostProcessor validation passes": true,
+    "No new MCP/skill/handler surface": true
   },
   "frameworkAlignment": {
     "OpenCode": "v1.1.1",
-    "0xRay": "v2.0.0"
+    "0xRay": "v4.0.0"
   }
 }

package/.xray/features.json

@@ -1,7 +1,17 @@
 {
   "$schema": "./features.schema.json",
-  "version": "3.4.3",
+  "version": "4.0.0",
   "description": "0xRay Framework - Unified Feature Configuration",
+  "suit_temperament": {
+    "profile": "auto",
+    "host_defaults": {
+      "grok": "frontier",
+      "hermes": "guided",
+      "opencode": "guided",
+      "openclaw": "guided",
+      "generic": "guided"
+    }
+  },
   "token_optimization": {
     "enabled": true,
     "max_context_tokens": 20000,
@@ -37,11 +47,19 @@
     "auto_consult_major_work": true,
     "no_new_surface": true,
     "auto_chain_delegations": true,
+    "plan_stale_hours": 8,
+    "plan_archive_marker_hours": 24,
     "user_asides": {
       "enabled": true,
       "auto_provision_worktree": false
     }
   },
+  "grok_postprocessor_light": true,
+  "inference_session_capture": {
+    "enabled": true,
+    "min_commits": 3,
+    "lookback_commits": 20
+  },
   "autonomous_reporting": {
     "enabled": true,
     "interval_minutes": 60,
@@ -140,10 +158,14 @@
     "min_success_rate": 0.7
   },
   "memory_routing": {
-    "enabled": false,
-    "provider": "null",
-    "module_path": "",
-    "config": {}
+    "enabled": true,
+    "provider": "repertoire",
+    "module_path": "node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js",
+    "config": {
+      "signalsPath": "node_modules/@0xray/repertoire/data/curated_signals.json",
+      "statePath": ".xray/state/repertoire/inference-state.json",
+      "feedbackDir": ".xray/state/repertoire/feedback"
+    }
   },
   "synthesis": {
     "enabled": false,

package/.xray/features.schema.json

@@ -84,6 +84,37 @@
         }
       }
     },
+    "grok_postprocessor_light": {
+      "type": "boolean",
+      "description": "Opt-in lightweight postprocessor marker + activity.log on Grok write tools"
+    },
+    "inference_session_capture": {
+      "type": "object",
+      "description": "git post-commit → captureSessionInference when commit threshold is met",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "min_commits": { "type": "integer", "minimum": 1 },
+        "lookback_commits": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "suit_temperament": {
+      "type": "object",
+      "description": "0xRay 4.0 — constitution always on; ceremony scales by host. Missing key = guided (existing consumers unchanged).",
+      "properties": {
+        "profile": {
+          "type": "string",
+          "enum": ["auto", "frontier", "guided", "strict"],
+          "description": "auto = host_defaults (grok→frontier, hermes/opencode/openclaw→guided)"
+        },
+        "host_defaults": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["frontier", "guided", "strict"]
+          }
+        }
+      }
+    },
     "synthesis": {
       "type": "object",
       "properties": {

package/AGENTS-consumer.md

@@ -4,7 +4,15 @@
 
 Quick reference for the 0xRay AI orchestration framework (shipped to your project on `npm install 0xray`).
 
-**v3.5.5** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
+**v4.0.0** — a suit that survives the context window.
+
+**v4.0.0** — same **three-subsystem OS** as v2 (Inference · External Governance · Autonomous Engine). Constitution always on. Temperament scales ceremony. Four platform bridges. Repertoire auto-enables when the module is present; otherwise `memory_routing` stays off. Trim fat, do not gut the design.
+
+**Governance always on** (Codex PreToolUse, no new surface, no `eval`). **Engine ceremony** (analyze-complexity before spawn, confer) is **guided** by default so free-model OpenCode/Hermes stay in check. Frontier hosts (Grok 4.6 class) with `suit_temperament.profile: auto` **warn** on spawn-without-plan instead of deny — the engine is still there. Existing `.xray/features.json` without `suit_temperament` stays **guided**. Docs: v3 from v2 · Suit temperament.
+
+## Hot-swap
+
+Before other work, Read `.xray/state/STATION.md`. Compaction and host change are the same cut. Continue the card. Do not restart the job. Grok does not inject the card (OpenCode does) — this Read is the Grok contract. Do not thicken the Grok exo.
 
 ## Postinstall (automatic)
 
@@ -76,14 +84,16 @@ Configure in `.xray/features.json`:
 "memory_routing": {
   "enabled": true,
   "provider": "repertoire",
-  "module_path": "../repertoire/dist/provider/memory-routing-provider.js",
+  "module_path": "node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js",
   "config": {
-    "signalsPath": "../repertoire/data/curated_signals.json"
+    "signalsPath": "node_modules/@0xray/repertoire/data/curated_signals.json",
+    "statePath": ".xray/state/repertoire/inference-state.json",
+    "feedbackDir": ".xray/state/repertoire/feedback"
   }
 }
 ```
 
-Without Repertoire: `{ "enabled": false, "provider": "null" }`.
+Opt out: `{ "enabled": false, "provider": "repertoire" }`.
 
 **External MCP** (Hermes/Grok): add Repertoire alongside 0xRay servers:
 
@@ -104,7 +114,7 @@ The Universal Development Codex (`.xray/codex.json`, **69 terms**) is enforced b
 |------|------|-------------|
 | 11 | No `any`, `@ts-ignore`, `@ts-expect-error` | PreToolUse deny on edits |
 | 29 | Security by design — no `eval()` | PreToolUse deny |
-| 59 | Complex work → orchestrator intake | PreToolUse deny `spawn_subagent` without plan |
+| 59 | Complex work → orchestrator intake | **guided/strict:** PreToolUse **deny** spawn without plan. **frontier:** **warn** (allow) — engine still available; leftover-plan todo mismatch also warns. Codex 11/29/69 still **deny**. |
 | 67–68 | Best subagents + lead dev ownership | `analyze-complexity` + orchestrator skill |
 | **69** | **No new MCP/skill/handler surface** | PreToolUse deny new `*.server.ts`, `SKILL.md` |
 
@@ -123,7 +133,7 @@ When the suit is worn, **lead dev mode** is ON via existing config + hooks:
 | Test triage | PreToolUse hook | Per-suite hint on full `npm test` |
 | Playbook | **`orchestrator`** skill | Codex 59, 67–69 rules |
 
-**First substantive task:** `analyze-complexity` with `tasks` array — **required before** `spawn_subagent`. You are the **lead developer**. Users speak in goals, not keywords.
+**First substantive task (guided/strict):** `analyze-complexity` with `tasks` array — **required before** `spawn_subagent`. **Frontier:** intake is optional; spawn without a plan **warns**. You are the **lead developer**. Users speak in goals, not keywords.
 
 | # | Rule |
 |---|------|

package/AGENTS.md

@@ -1,15 +1,23 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.5.5**).
+Quick reference for the xray AI orchestration framework (**v4.0.0**).
 
-**42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
+**v4.0.0** — a suit that survives the context window.
+
+**Exo, not catalog.** Three-subsystem OS (Inference · External Governance · Autonomous Engine) · constitution always on · temperament by host · 4 floors · Repertoire when it resolves.
+
+**Temperament:** ceremony (analyze-complexity before spawn, confer) is **guided** by default so free-model OpenCode/Hermes stay in check. Frontier hosts (Grok 4.6 class) with `suit_temperament.profile: auto` **warn** on spawn-without-plan; Codex 11/29/69 still **deny**. Missing `suit_temperament` stays guided. See `docs-site/docs/architecture/v3-from-v2.md`.
+
+## Hot-swap
+
+Before other work, Read `.xray/state/STATION.md`. Compaction and host change are the same cut. Continue the card. Do not restart the job. Grok does not inject the card (OpenCode does) — this Read is the Grok contract. Do not thicken the Grok exo.
 
 ## What is xray?
 
 xray provides intelligent multi-agent orchestration with automatic delegation and Codex compliance validation under the pure v2 three-subsystem model:
 
 - **Inference** — proposals, reflection, memory routing (optional)
-- **External Governance** — Dynamo Solar SSOT, 68-term Codex
+- **External Governance** — Dynamo Solar SSOT, 69-term Codex
 - **Autonomous Engine** — thinDispatch 7-flow, AsideContext, confidence gate
 
 Agents are declared in `src/opencode/agents/*.yml` — the YML SSOT. Skills live in `src/skills/*/SKILL.md` — see [SKILLS.md](SKILLS.md). Consumer projects receive slimmed copies via postinstall (`AGENTS-consumer.md` → `AGENTS.md`, skills synced to platform dirs).