0xray 3.3.1 → 3.4.2

package/dist/AGENTS.md

@@ -1,87 +1,203 @@
 # xray Agents
 
-Quick reference for xray AI orchestration framework (v16 MCPs-centric three-subsystem).
+Quick reference for the xray AI orchestration framework (**v3.4.2**).
+
+**42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 
 ## What is xray?
 
-xray provides intelligent multi-agent orchestration with automatic delegation and Codex compliance validation under the pure v2 three-subsystem model (Inference + External Governance via Dynamo + Autonomous Engine via thinDispatch 7-flow in MCP orchestrator). Agents operate via `.opencode/agents/*.yml` YML surfaces and 3 dedicated MCP skill servers — no manual setup needed.
+xray provides intelligent multi-agent orchestration with automatic delegation and Codex compliance validation under the pure v2 three-subsystem model:
 
-## v16 MCPs-Centric Architecture
+- **Inference** — proposals, reflection, memory routing (optional)
+- **External Governance** — Dynamo Solar SSOT, 68-term Codex
+- **Autonomous Engine** — thinDispatch 7-flow, AsideContext, confidence gate
 
-The v2 release centers on **MCP (Model Context Protocol)** as the primary surface for agent skills. Three agent MCP servers handle governance deliberation:
+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).
 
-- `code-review` — Proposal quality, code analysis, best practices
-- `security-audit` — Vulnerability detection, threat modeling
-- `researcher` — Codebase exploration, pattern discovery, implementation lookup
+## Consumer MCP surface (7 servers)
 
-These MCP servers integrate with the three-subsystem pipeline for governance-gated execution.
+Registered in `.mcp.json`, invoked via `npx -y 0xray mcp <cmd>`:
 
-## xray Three-Subsystem Operation
+| Server | Role |
+|--------|------|
+| `xray-governance` | Proposal governance, codex snapshot, quality gates |
+| `xray-skills` | 45 knowledge skills + `invoke-skill` |
+| `xray-orchestrator` | thinDispatch, AsideContext, confidence gate |
+| `xray-enforcer` | Codex compliance, rule validation |
+| `xray-researcher` | Codebase exploration, memory-routing enrichment |
+| `xray-code-review` | Proposal quality, code review deliberation |
+| `xray-architect-tools` | System design, architecture decisions |
 
-xray operates under the pure three-subsystem model: Inference + External Governance (Dynamo Solar SSOT) + Autonomous Engine (thinDispatch 7-flow in MCP orchestrator). Agents are declared in `.opencode/agents/*.yml` YML surfaces with zero manual setup.
+Governance deliberation: **code-review**, **security-audit**, **researcher** within the 7-server set.
 
-### Core Tenets
-- YML declarations are the SSOT
-- Zero manual setup or registration
-- Governance precedes action via Dynamo
-- Automatic delegation via thinDispatch
-- MCP surfaces are the primary skill interface
-- fwLogger / frameworkLogger structured logging ONLY (never console.*) to logs/framework/activity.log + .opencode/logs/
+## Postinstall (v3.4.1)
 
-### File Organization Guidelines
+`postinstall.cjs` → `installAllBridges()`:
 
-**IMPORTANT**: Save all generated files to their proper directories. Do NOT save to root.
+1. `AGENTS-consumer.md` → `AGENTS.md`
+2. `SKILLS.md` + 46 skills → platform skill directories
+3. `.gitignore.default` → `.gitignore` (if absent)
+4. `.xray/` config (`codex.json`, `features.json`, `config.json`)
+5. `.mcp.json` (7 servers)
+6. Four bridges: OpenCode, Grok, Hermes, OpenClaw
+7. Optional git hooks
 
-| File Type | Save To | Example |
-|-----------|---------|---------|
-| **Reflections** | `docs/reflections/` | `docs/reflections/my-fix-reflection.md` |
-| **Logs** | `logs/` | `logs/framework/activity.log` |
-| **Scripts** | `scripts/` or `scripts/bash/` | `scripts/bash/my-script.sh` |
-| **Test Files** | `src/__tests__/` | `src/__tests__/unit/my-test.test.ts` |
-| **Source Code** | `src/` | `src/my-module.ts` |
-| **Config** | `config/` or `.xray/` | `.xray/config.json` |
+## Memory routing + Repertoire (v3.3+)
 
-**Never save to root** - Root directory is for essential files only:
-- `README.md`, `CHANGELOG.md`, `package.json`, `tsconfig.json`
+`xray/features.json` → `memory_routing` (schema: `features.schema.json`):
 
-## Available Agents
+```json
+"memory_routing": {
+  "enabled": true,
+  "provider": "repertoire",
+  "module_path": "../repertoire/dist/provider/memory-routing-provider.js",
+  "config": {
+    "dataDir": "../repertoire/data",
+    "signalsPath": "../repertoire/data/curated_signals.json",
+    "logDir": "../repertoire/logs/groover-inference"
+  }
+}
+```
 
-| Agent | Purpose | Invoke |
-|-------|---------|--------|
-| `@enforcer` | Codex compliance & error prevention | `@enforcer analyze this code` |
-| `@orchestrator` | Complex multi-step task coordination | `@orchestrator implement feature` |
-| `@architect` | System design & technical decisions | `@architect design API` |
-| `@security-auditor` | Vulnerability detection | `@security-auditor scan` |
-| `@code-reviewer` | Quality assessment | `@code-reviewer review PR` |
-| `@refactorer` | Technical debt elimination | `@refactorer optimize code` |
-| `@testing-lead` | Testing strategy | `@testing-lead plan tests` |
-| `@bug-triage-specialist` | Error investigation | `@bug-triage-specialist debug error` |
-| `@researcher` | Codebase exploration | `@researcher find implementation` |
+| Integration | Surface |
+|-------------|---------|
+| ExecutionPlanner | `enrichTasks`, `getTaskConfidence`, `selectAgent` |
+| thinDispatch | `resolveThinDispatch` |
+| Researcher | `researcher-confidence.ts`, `MEMORY_ROUTING:` block |
+| AsideContext | `buildInheritedContext` → `inheritedContext.memoryRouting` |
+| Feedback | Per-task `ingestFeedback` |
 
-## MCP Skill Servers
+**External MCP:** `npx @0xray/repertoire mcp` — `repertoire__get_task_confidence`, etc.
 
-xray ships dedicated MCP servers that provide agent skills:
+## AsideContext (v3.2+)
 
-| Server | Role |
-|--------|------|
-| `code-review` | Proposal quality analysis, code review |
-| `security-audit` | Vulnerability scanning, threat assessment |
-| `researcher` | Codebase exploration, implementation lookup |
-| `orchestrator` | thinDispatch 7-flow delegation routing |
-| `enforcer-tools` | Codex compliance enforcement |
-| `governance` | Proposal governance, codex snapshot |
+`src/mcps/orchestrator/aside-context.ts` — bounded subcontexts for orchestration:
+
+- `spawnAside` / `closeAside` on `orchestrate-task`, `analyze-complexity`, `govern-and-apply`
+- Observation extractors: governance, orchestration, complexity
+- Repertoire context flows via `ExecutionPlan.memoryContext`
+
+## Confidence gate (v3.3.1)
+
+`ExecutionPlanner.calculateTaskComplexity()` + `getTaskConfidence()` — complexity boost and ontological-trap routing.
+
+## Nucleus exports (v3.4.0)
 
-## thinDispatch Routing
+`0xray/nucleus` and `0xray/nucleus/*` — `handleGovernRequest`, plugin-registry, thinDispatch.
 
-The Autonomous Engine routes via complexity:
+## Changes since 3.1
+
+| Version | Change |
+|---------|--------|
+| **3.4.1** | `install-bridges.cjs`, 7 MCPs `npx`, release pipeline + docs sync |
+| **3.4.0** | Nucleus exports, governance closure, verify gate |
+| **3.3.1** | Confidence gate, repertoire researcher wiring |
+| **3.3.0** | Memory routing + Repertoire provider |
+| **3.2.0** | AsideContext wired, SelfProposalEngine, pre-tool-use hook |
+| **3.1.1** | 0xRay rename, marketplace, AGENTS/SKILLS consumer seeding |
+
+**Removed:** `hermes bridge`, `.opencode/xray/` fallback, `advanced-features/` on consumer boot.
+
+## Default operating mode: autonomy-command
+
+When the suit is worn, **autonomy-command** is ON by default (codex 67–68). Lead dev: phased todos, subagent dispatch, per-suite test triage, loop until green. Ships to consumers via `AGENTS-consumer.md`.
+
+Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Skill: `src/skills/autonomy-command/SKILL.md`
+
+## Core tenets
+
+- YML agents + SKILL.md are the SSOT
+- Zero manual registration
+- Governance precedes action (Dynamo)
+- MCP surfaces are the primary skill interface
+- frameworkLogger only (never `console.*`)
+
+## File organization
+
+| File Type | Save To |
+|-----------|---------|
+| Reflections | `docs/reflections/` |
+| Logs | `logs/` |
+| Scripts | `scripts/` or `scripts/bash/` |
+| Tests | `src/__tests__/` |
+| Source | `src/` |
+| Config | `.xray/` or `config/` |
+
+**Root essentials only:** `README.md`, `CHANGELOG.md`, `package.json`, `AGENTS.md`, `SKILLS.md`, `tsconfig.json`.
+
+## Available agents (42 YML surfaces)
+
+Invoke via `@agent-name` in OpenCode:
+
+| Agent | Purpose |
+|-------|---------|
+| `@enforcer` | Codex compliance & error prevention |
+| `@orchestrator` | Multi-step task coordination |
+| `@architect` | System design & technical decisions |
+| `@security-auditor` | Vulnerability detection |
+| `@code-reviewer` | Quality assessment |
+| `@refactorer` | Technical debt elimination |
+| `@testing-lead` | Testing strategy |
+| `@bug-triage-specialist` | Error investigation |
+| `@researcher` | Codebase exploration |
+| `@frontend-engineer` | React, Vue, Angular, responsive design |
+| `@backend-engineer` | REST/GraphQL APIs, microservices |
+| `@database-engineer` | Schema design, query optimization |
+| `@devops-engineer` | CI/CD, infrastructure, containers |
+| `@mobile-developer` | iOS, Android, React Native, Flutter |
+| `@storyteller` | Narrative reflections, technical stories |
+| `@strategist` | Architecture decisions, risk analysis |
+| `@performance-engineer` | Profiling, benchmarking |
+| `@frontend-ui-ux-engineer` | Visual design, accessibility |
+| `@multimodal-looker` | Media / screenshot analysis |
+| `@log-monitor` | Log diagnostics |
+| `@code-analyzer` | Code metrics, pattern detection |
+| `@content-creator` | SEO copy, technical content |
+| `@growth-strategist` | Marketing strategy |
+| `@seo-consultant` | Technical SEO |
+| `@tech-writer` | API docs, READMEs, changelogs |
+| `@hermes-agent` | Hermes bridge operations |
+| `@boot-orchestrator` | Framework boot orchestration |
+| `@processor-pipeline` | Data processing pipelines |
+| `@state-manager` | Session / state persistence |
+| `@session-management` | Session lifecycle |
+| `@inference-improve` | Autonomous inference improvement |
+| `@model-health-check` | Model health diagnostics |
+| `@framework-compliance-audit` | Framework compliance |
+| `@lint` | Code linting |
+| `@auto-format` | Automated formatting |
+| `@git-workflow` | Git workflow management |
+| `@api-design` | REST/GraphQL API design |
+| `@architecture-patterns` | Architecture patterns |
+| `@performance-analysis` | Performance analysis |
+| `@performance-optimization` | Performance optimization |
+| `@project-analysis` | Project health metrics |
+| `@security-scan` | Security vulnerability scanning |
+| `@testing-best-practices` | Testing QA |
+| `@ui-ux-design` | UI/UX design |
+
+Full skill mapping: [SKILLS.md](SKILLS.md).
+
+## thinDispatch routing
 
 - Simple (≤15): Single agent
 - Moderate (≤25): Single agent with tools
 - Complex (≤50): Multi-agent coordination
 - Enterprise (>50): Orchestrator-led team
 
-## Codex
+## Documentation
+
+| Topic | Path |
+|-------|------|
+| Features since 3.1 | `docs-site/docs/guides/features-since-3.1.md` |
+| features.json | `docs-site/docs/guides/features-json.md` |
+| Platform integrations | `docs-site/docs/guides/integrations.md` |
+| Memory routing | `docs-site/docs/guides/memory-routing.md` |
+| Repertoire | `docs-site/docs/guides/repertoire.md` |
+| AsideContext | `docs-site/docs/guides/aside-context.md` |
+| Consumer migration | `docs-site/docs/guides/consumer-migration.md` |
+| Docusaurus site | https://0xrayai.github.io/xray/ |
 
-xray enforces the Universal Development Codex (60 terms) via Dynamo governance. The codex lives in `.xray/codex.json`.
+## Release artifacts
 
-Pure v16 MCPs. Clean. Complete.
+`npm run release:patch` updates: `package.json`, `CHANGELOG.md`, `README.md`, `AGENTS.md`, `AGENTS-consumer.md`, `SKILLS.md`, Docusaurus guides.

package/dist/CHANGELOG.md

@@ -4,13 +4,85 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
-## [3.3.0] - 2026-06-18
+## [3.4.2] - 2026-06-18
 
-### 🔄 Changes
+### ✨ Features
+- **Ironclad Grok hooks** — PreToolUse stdin contract, codex pattern blocks, spawn_subagent gate, `activity.log` via `grok-hook-activity.js`
+- **SessionStart + UserPromptSubmit** — `session-start.js` writes `.xray/state/session-boot.json`
+- **Lead-dev plan persist** — `analyze-complexity` persists `.xray/state/lead-dev-plan.json` via `autonomy-kernel`
+- **Codex term 69** — No New Surface Without Consolidation (blocking)
+- **package.json `xray` field** — `dist` + `mcpServersPath` for consumer server-config-registry
+- Memory routing provider enabled with live feedback session
+- Blocking release docs freshness guard (`validate-release-docs.mjs`)
 
-### 🔎 Other Changes
-- Wire orchestrator confidence gate into execution planning (d7910b610)
-- tweet: v3.3.0 release tweet — Pluggable Memory Routing (7fb6c9f70)
+### 🐛 Bug Fixes
+- `server-config-registry` resolves `name === "0xray"` without requiring `xray` field
+- Ship `features.json` in npm package for `memory_routing`
+- Pre-publish guard: correct git porcelain parsing, ignore `.xray/inference` runtime state
+
+---
+
+## [3.4.1] - 2026-06-18
+
+### ✨ Features
+- Unified 4-platform bridge installer (`install-bridges.cjs`) runs on consumer `npm i 0xray` postinstall — OpenCode, Grok, Hermes, OpenClaw
+- All 7 MCP servers registered via `npx -y 0xray mcp <cmd>` (no brittle `dist/` paths)
+- `npx 0xray grok install` aligned with postinstall: 7 servers via npx, idempotent skill/MCP sync on re-run
+- Grok skills synced to both `~/.grok/plugins/0xray/skills/` and `~/.grok/skills/` (Grok Build / Cursor)
+- Canonical `release.mjs` pipeline: reconcile-version → release-gate → artifacts → tag → publish
+- Consumer smoke gate (`release-gate.mjs`) — pack, clean install, verify 7 MCP + 4 bridges
+
+### 🐛 Bug Fixes
+- `setup.cjs` consumer detection uses `isConsumerInstall()` — works for both `node_modules/0xray` and `node_modules/xray`
+- Hermes bridge honors `XRAY_ROOT` env and `xray-consumer-root.txt` marker for correct project root resolution
+
+### 📚 Documentation
+- README, AGENTS, AGENTS-consumer, and Docusaurus synced for v3.4.1 (42 agents, 45 skills, 7 MCP servers, 68 codex terms)
+- New guides: Repertoire integration, features.json reference, features since 3.1, memory routing, platform integrations
+- Repertoire: `features.json` `memory_routing` config, MCP tools, confidence gate, ExecutionPlanner/thinDispatch/researcher wiring
+- AsideContext guide: `spawnAside` lifecycle, observation extractors, Repertoire `inheritedContext.memoryRouting` link
+- `.grok-plugin/plugin.json` version and MCP description corrected
+
+---
+
+## [3.4.0] - 2026-06-17
+
+> Tagged locally; not published to npm. Superseded by 3.4.1 for consumer install.
+
+### ✨ Features
+- Governance default-on with Railway endpoint
+- 10-step E2E pipeline smoketest
+- Source-change governance detector with external Dynamo
+- Nucleus exports (`0xray/nucleus`, `0xray/nucleus/*`) for consumer plugin-registry access
+- Consumer path hygiene audit (postinstall/setup/prepare-consumer)
+- Compat shim scanner (term 78), orphan pre-PR check (term 73)
+
+### 🐛 Bug Fixes
+- Codex closure: processorRoadmap 7/74/75 done, validationCriteria 6/8 true
+- 2,880 tests pass, typecheck clean, 0 `console.*` in non-CLI source
+
+---
+
+## [3.3.1] - 2026-06-18
+
+### ✨ Features
+- Initial `install-bridges.cjs` scaffold and repertoire researcher wiring tests
+- Orchestrator **confidence gate** wired into execution planning (d7910b610)
+
+### 🐛 Bug Fixes
+- Postinstall consumer detection and bridge install hooks refined
+
+---
+
+## [3.3.0] - 2026-06-18
+
+### ✨ Features
+- **Pluggable Memory Routing** — `MemoryRoutingProvider` interface + `features.json` `memory_routing` block
+- `features.schema.json` runtime validation at load time
+- Repertoire as first plug-in provider (framework repo default)
+- Per-task `ingestFeedback` (not aggregate-only) for provider learning loop
+- Memory routing enriches orchestrator selection, thinDispatch scoring, researcher votes
+- 24 memory-routing integration tests; 3,221 tests passing (0 failures)
 
 ---
 
@@ -40,57 +112,24 @@ The format is based on [Conventional Commits](https://www.conventionalcommits.or
 
 ---
 
-## [3.1.1] - 2026-06-17
-
-### 🔄 Changes
-
-### ✨ Features
-- feat: AsideContext restoration + plugin module split + Hermes e2e 44/0/0 (3a917b7c3)
-- feat: config consolidation, MCP base class, test coverage, Hermes e2e fix (8b3f0500f)
-- feat: add root .mcp.json and .grok-plugin/plugin.json for marketplace discovery (f8d084cc0)
-- feat: ship .gitignore.default template + SKILLS.md to consumers via postinstall (44bba8c4c)
-
-### 🐛 Bug Fixes
-- fix: publish guard fixes - 4 test files, plugin build, ConfigLoader.clearConfigPaths() (5a5edfa42)
-- fix: restore .mcp.json (deleted by test writing to same path) (e22202cfc)
-- fix: support mcpServers format in ConfigLoader, fix tests for real .mcp.json (a930aa034)
-- fix: add missing fs imports, process.argv[1]! assertions, and vitest v4 config (0dffc5683)
-- fix: remove .opencode/xray/ fallback from auto-reflection-generator.mjs (de7633152)
-- fix: Railway deployment - MCP host, in-process skills, Hermes OAuth decode, OAuth daemon mode (a519338c3)
-- fix: pre-publish-guard handles missing features.json (855e3cfdb)
-
-### ♻️ Refactoring
-- refactor: complete StringRay→0xRay rename, archive cleanup, skill syncing, MCP tools (d78bc3763)
-
-### 🔎 Other Changes
-- v3.1.1 (825105795)
-- Revert "Add marketplace files: .grok-plugin/plugin.json and .mcp.json for xAI plugin catalog" (05feb6fba)
-- Add marketplace files: .grok-plugin/plugin.json and .mcp.json for xAI plugin catalog (5824d5776)
-
----
-
 ## [3.1.1] - 2026-06-16
 
-### 🔄 Changes
-
 ### ✨ Features
-- feat: add root .mcp.json and .grok-plugin/plugin.json for marketplace discovery (f8d084cc0)
-- feat: ship .gitignore.default template + SKILLS.md to consumers via postinstall (44bba8c4c)
+- Complete **StringRay → 0xRay** rename; archive cleanup, skill syncing, MCP tools
+- Root `.mcp.json` and `.grok-plugin/plugin.json` for xAI marketplace discovery
+- Postinstall ships `AGENTS-consumer.md` → `AGENTS.md`, `.gitignore.default`, `SKILLS.md`
+- AsideContext restoration + plugin module split; Hermes E2E 44/0/0
+- Config consolidation, MCP base class, expanded test coverage
 
 ### 🐛 Bug Fixes
-- fix: restore .mcp.json (deleted by test writing to same path) (e22202cfc)
-- fix: support mcpServers format in ConfigLoader, fix tests for real .mcp.json (a930aa034)
-- fix: add missing fs imports, process.argv[1]! assertions, and vitest v4 config (0dffc5683)
-- fix: remove .opencode/xray/ fallback from auto-reflection-generator.mjs (de7633152)
-- fix: Railway deployment - MCP host, in-process skills, Hermes OAuth decode, OAuth daemon mode (a519338c3)
-- fix: pre-publish-guard handles missing features.json (855e3cfdb)
-
-### ♻️ Refactoring
-- refactor: complete StringRay→0xRay rename, archive cleanup, skill syncing, MCP tools (d78bc3763)
-
-### 🔎 Other Changes
-- Revert "Add marketplace files: .grok-plugin/plugin.json and .mcp.json for xAI plugin catalog" (05feb6fba)
-- Add marketplace files: .grok-plugin/plugin.json and .mcp.json for xAI plugin catalog (5824d5776)
+- ConfigLoader supports `mcpServers` format in `.mcp.json`
+- Railway deployment: MCP host, in-process skills, Hermes OAuth decode, OAuth daemon mode
+- Publish guard fixes — 4 test files, plugin build, `ConfigLoader.clearConfigPaths()`
+- Remove `.opencode/xray/` fallback from auto-reflection-generator
+- Pre-publish-guard handles missing `features.json`
+
+### 🗑️ Removals
+- `hermes bridge` CLI — use `npx 0xray hermes install`
 
 ---