0xray 3.5.1 → 3.5.2

package/.gitignore.default

@@ -20,6 +20,13 @@ credentials.json
 *.pem
 *.key
 
+# 0xray suit artifacts (postinstall / bridge install)
+.grok/
+.mcp.json
+opencode.json
+AGENTS.md
+SKILLS.md
+
 # Runtime state (xray inference workflows, session state)
 .xray/
 .strray/
@@ -41,6 +48,7 @@ xray/inference/
 
 # Logs
 logs/
+logs/framework/
 *.log
 
 # OS files

package/.opencode/hooks/post-commit

@@ -20,39 +20,19 @@ BRANCH=$(git rev-parse --abbrev-ref HEAD)
   fi
 ) &
 
-# Load auto_reflection config from features.json
-CONFIG_FILE="$PROJECT_ROOT/.xray/features.json"
+# Load reflection config — synthesis.reflection SSOT, fallback auto_reflection
 MODE="minimal"
 COMMIT_THRESHOLD=25
 DAYS_THRESHOLD=14
 AUTO_GENERATE=true
 PROMPT_USER=true
 
-if [ -f "$CONFIG_FILE" ]; then
-  MODE=$(grep -o '"mode": *"[^"]*"' "$CONFIG_FILE" | cut -d'"' -f4)
-  MODE=${MODE:-minimal}
-  
-  # Get thresholds based on mode
-  case "$MODE" in
-    full)
-      COMMIT_THRESHOLD=10
-      DAYS_THRESHOLD=5
-      AUTO_GENERATE=true
-      PROMPT_USER=true
-      ;;
-    minimal)
-      COMMIT_THRESHOLD=25
-      DAYS_THRESHOLD=14
-      AUTO_GENERATE=true
-      PROMPT_USER=true
-      ;;
-    off)
-      COMMIT_THRESHOLD=999
-      DAYS_THRESHOLD=365
-      AUTO_GENERATE=false
-      PROMPT_USER=false
-      ;;
-  esac
+if command -v node >/dev/null 2>&1; then
+  LOAD_SCRIPT="$PROJECT_ROOT/scripts/node/load-reflection-config.mjs"
+  if [ -f "$LOAD_SCRIPT" ]; then
+    export PROJECT_ROOT="$PROJECT_ROOT"
+    eval "$(node "$LOAD_SCRIPT")"
+  fi
 fi
 
 # Check if this was a significant commit - prompt for reflection

package/.xray/features.json

@@ -141,6 +141,12 @@
     "module_path": "",
     "config": {}
   },
+  "synthesis": {
+    "enabled": false,
+    "every_n_gates": 12,
+    "every_n_turns": 0,
+    "every_n_todos_completed": 0
+  },
   "inference_governance": {
     "enabled": false,
     "request_timeout_ms": 10000,

package/.xray/features.schema.json

@@ -27,6 +27,23 @@
       "then": {
         "required": ["module_path"]
       }
+    },
+    "synthesis": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "every_n_gates": { "type": "integer", "minimum": 0 },
+        "every_n_turns": { "type": "integer", "minimum": 0 },
+        "every_n_todos_completed": { "type": "integer", "minimum": 0 },
+        "reflection": {
+          "type": "object",
+          "properties": {
+            "mode": { "type": "string", "enum": ["full", "minimal", "off"] },
+            "triggers": { "type": "object" },
+            "thresholds": { "type": "object" }
+          }
+        }
+      }
     }
   },
   "additionalProperties": true

package/AGENTS-consumer.md

@@ -4,7 +4,7 @@
 
 Quick reference for the 0xRay AI orchestration framework (shipped to your project on `npm install 0xray`).
 
-**v3.5.1** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
+**v3.5.2** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
 
 ## Postinstall (automatic)
 

package/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.5.1**).
+Quick reference for the xray AI orchestration framework (**v3.5.2**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.5.1** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.5.2** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 ## Your AI Power Suit
 

package/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.5.1** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.5.2** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/.gitignore.default

@@ -20,6 +20,13 @@ credentials.json
 *.pem
 *.key
 
+# 0xray suit artifacts (postinstall / bridge install)
+.grok/
+.mcp.json
+opencode.json
+AGENTS.md
+SKILLS.md
+
 # Runtime state (xray inference workflows, session state)
 .xray/
 .strray/
@@ -41,6 +48,7 @@ xray/inference/
 
 # Logs
 logs/
+logs/framework/
 *.log
 
 # OS files

package/dist/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.5.1**).
+Quick reference for the xray AI orchestration framework (**v3.5.2**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/dist/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [3.5.2] - 2026-06-19
+
+### 🐛 Bug Fixes
+- **Grok synthesis gate** — `pre-tool-use.js` wires `evaluatePreToolGate` SSOT (synthesis deny, gate slices, `govern-and-apply` block); fail-closed on hook errors
+- **Consumer bridge root** — `findProjectRoot` git-root + devDependency detection; `findGitRoot` applies `normalizePath`
+- **Consumer hooks** — stale xray pre-commit reinstall; post-commit hook installed; pre-commit fails closed when runner missing; non-xray hooks backed up before overwrite
+- **Consumer `.gitignore`** — idempotent suit block merge on postinstall; preserves orphan tail on incomplete marker
+- **`bridge.mjs`** — `handleGetConfig` fixes undeclared `envDir` ReferenceError
+- **Post-commit reflection** — `load-reflection-config.mjs` mode whitelist + `--json` output (no shell `eval`); macOS/BSD `stat` support
+
+### ✅ Tests
+- `verify-grok-synthesis-gate.mjs` (4/4 live Grok hook); chained in `verify:grok-delegation-gate` and `verify:delegation-gate`
+- `verify-consumer-gitignore` incomplete-marker fixture; `verify:find-project-root` 3/3
+
+---
+
 ## [3.5.1] - 2026-06-19
 
 ### ✨ Features

package/dist/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.5.1** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.5.2** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 ## Your AI Power Suit
 

package/dist/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.5.1** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.5.2** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/core/bridge.mjs

@@ -51,6 +51,7 @@ import { join, dirname, resolve, relative } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { createServer } from "http";
+import { findProjectRoot } from "../../scripts/helpers/find-project-root.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -63,35 +64,11 @@ let CodexFormatterModule = null;
 let frameworkReady = false;
 let frameworkLoadAttempted = false;
 
-// ============================================================================
-// Project Root Detection
-// ============================================================================
-
-function findProjectRoot() {
-  const envHome = process.env.XRAY_HOME;
-  if (envHome && existsSync(join(envHome, "package.json"))) return envHome;
-
-  const candidates = [
-    process.cwd(),
-    join(homedir(), "dev", "xray"),
-    join(dirname(__dirname), "..", ".."), // core/ -> project root
-    join(dirname(__dirname), "..", "..", ".."), // integrations/ -> project root
-  ];
-
-  for (const dir of candidates) {
-    try {
-      const pkgPath = join(dir, "package.json");
-      if (existsSync(pkgPath)) {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        if (pkg.name === "0xray" || pkg.dependencies?.["0xray"]) {
-          return dir;
-        }
-      }
-    } catch {
-      continue;
-    }
-  }
-  return process.cwd();
+function resolveBridgeProjectRoot() {
+  return findProjectRoot([
+    join(dirname(__dirname), "..", ".."),
+    join(dirname(__dirname), "..", "..", ".."),
+  ]);
 }
 
 // ============================================================================
@@ -184,7 +161,7 @@ const BRIDGE_CODEX_FALLBACK = {
 // ============================================================================
 
 async function handleHealth(input) {
-  const projectRoot = findProjectRoot();
+  const projectRoot = resolveBridgeProjectRoot();
   const loaded = await loadFramework(projectRoot);
 
   const pkgPath = join(projectRoot, "package.json");
@@ -313,6 +290,7 @@ async function handleGetCodexPrompt(input, projectRoot, logDir) {
 
 async function handleGetConfig(input, projectRoot, logDir) {
   logToActivity(logDir, "get-config");
+  const envDir = process.env.XRAY_CONFIG_DIR;
 
   const result = {
     status: "ok",
@@ -374,7 +352,7 @@ async function handleStats() {
     codexFormatterAvailable: !!CodexFormatterModule,
     qualityGateAvailable: !!QualityGateModule,
     nodeVersion: process.version,
-    projectRoot: findProjectRoot(),
+    projectRoot: resolveBridgeProjectRoot(),
   };
 }
 
@@ -893,7 +871,7 @@ async function main() {
     }
   }
 
-  const projectRoot = findProjectRoot();
+  const projectRoot = resolveBridgeProjectRoot();
   const logDir = ensureLogDir(projectRoot);
 
   // Lazy-load framework

package/dist/core/features-config.d.ts

@@ -66,6 +66,21 @@ export interface MultiAgentOrchestrationConfig {
     /** 3.5.0 — PreToolUse gate after delegate-deferred (default true when lead_dev_mode) */
     auto_chain_delegations?: boolean;
 }
+/** Reflection triggers merged from legacy auto_reflection when synthesis is configured */
+export interface SynthesisReflectionConfig {
+    mode?: AutoReflectionConfig['mode'];
+    triggers?: AutoReflectionConfig['triggers'];
+    thresholds?: AutoReflectionConfig['thresholds'];
+}
+/** 3.6.0 — periodic reflect & realign checkpoint (Synthesis PR1) */
+export interface SynthesisConfig {
+    enabled: boolean;
+    every_n_gates: number;
+    every_n_turns: number;
+    every_n_todos_completed: number;
+    /** SSOT for reflection triggers when synthesis enabled; seeded from auto_reflection */
+    reflection?: SynthesisReflectionConfig;
+}
 export interface AutonomousReportingConfig {
     enabled: boolean;
     interval_minutes: number;
@@ -369,6 +384,7 @@ export interface FeaturesConfig {
     auto_reflection?: AutoReflectionConfig;
     inference?: InferenceConfig;
     memory_routing?: MemoryRoutingConfig;
+    synthesis: SynthesisConfig;
     kernel?: KernelConfig;
     processors?: ProcessorsConfig;
     enforcement?: EnforcementConfig;

package/dist/core/features-config.js

@@ -278,6 +278,24 @@ export class FeaturesConfigLoader {
                 ...defaults.caching,
                 ...configData.caching,
             },
+            synthesis: (() => {
+                const merged = {
+                    ...defaults.synthesis,
+                    ...configData.synthesis,
+                };
+                const reflection = configData.synthesis?.reflection ??
+                    (configData.auto_reflection
+                        ? {
+                            mode: configData.auto_reflection.mode,
+                            triggers: configData.auto_reflection.triggers,
+                            thresholds: configData.auto_reflection.thresholds,
+                        }
+                        : undefined);
+                if (reflection) {
+                    merged.reflection = reflection;
+                }
+                return merged;
+            })(),
         };
     }
     /**
@@ -391,6 +409,12 @@ export class FeaturesConfigLoader {
                 cache_ttl_seconds: 300,
                 max_cache_size_mb: 50,
             },
+            synthesis: {
+                enabled: false,
+                every_n_gates: 12,
+                every_n_turns: 0,
+                every_n_todos_completed: 0,
+            },
         };
     }
     /**

package/dist/integrations/grok/hooks/grok-hook-utils.js

@@ -105,8 +105,8 @@ export function resolveCodexPath(root = workspaceRoot()) {
   return null;
 }
 
-export function loadFeatures() {
-  const featuresPath = resolveFeaturesPath();
+export function loadFeatures(root = workspaceRoot()) {
+  const featuresPath = resolveFeaturesPath(root);
   if (!featuresPath) return { lead_dev_mode: true, no_new_surface: true, per_suite_triage: true };
   try {
     const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));

package/dist/integrations/grok/hooks/post-tool-use.js

@@ -36,7 +36,7 @@ async function main() {
     if (isSubagentTool(toolName)) {
       const spawnCheck = validateSpawnMatchesTodo(toolInput, eventRoot);
       if (spawnCheck.valid && spawnCheck.expectedTodoId) {
-        updatePlanTodoStatusInPlace(spawnCheck.expectedTodoId, 'in_progress', eventRoot);
+        updatePlanTodoStatusInPlace(spawnCheck.expectedTodoId, 'completed', eventRoot);
       }
 
       const result = satisfyDelegationsFromToolInput(toolInput, eventRoot);

package/dist/integrations/grok/hooks/pre-tool-use.js

@@ -4,11 +4,13 @@
  * Contract: stdin JSON → stdout {"decision":"allow"} | {"decision":"deny","reason":"..."}
  */
 
+import {
+  evaluatePreToolGate,
+  loadDelegationGateFeatures,
+} from '../../hooks/delegation-gate-runtime.mjs';
 import {
   checkCodexPatterns,
   checkFullTestSuite,
-  checkPendingDelegationGate,
-  checkSubagentGate,
   checkSurfaceArea,
   ensureSessionBoot,
   isShellTool,
@@ -43,45 +45,27 @@ async function main() {
     const eventRoot = event.workspaceRoot || event.cwd || root;
     ensureSessionBoot(eventRoot, '0xray/grok-pre-tool-use-boot');
 
-    const features = loadFeatures();
+    const features = loadFeatures(eventRoot);
+    const gateFeatures = loadDelegationGateFeatures(eventRoot);
     const ctx = extractFromEvent(event);
     toolName = ctx.toolName;
     const { paths, content, cmd, toolInput } = ctx;
     const sessionId = resolveSessionId(event);
 
-    const delegationBlock = checkPendingDelegationGate(
-      toolName,
-      toolInput,
-      features,
-      eventRoot,
-      sessionId,
-    );
-    if (delegationBlock) {
-      finish(
-        eventRoot,
-        'deny',
-        delegationBlock.reason,
-        delegationBlock.hint,
-        toolName,
-        { gate: delegationBlock.gate },
-      );
-    }
-
-    const subagentBlock = checkSubagentGate(
-      toolName,
-      features,
-      eventRoot,
+    const gateBlock = evaluatePreToolGate(toolName, toolInput, {
+      projectRoot: eventRoot,
       sessionId,
-      toolInput,
-    );
-    if (subagentBlock) {
+      features: gateFeatures,
+      host: 'grok',
+    });
+    if (!gateBlock.allow) {
       finish(
         eventRoot,
         'deny',
-        subagentBlock.reason || subagentBlock,
-        subagentBlock.hint || null,
+        gateBlock.reason,
+        gateBlock.hint,
         toolName,
-        { gate: subagentBlock.gate || 'spawn-gate' },
+        { gate: gateBlock.gate },
       );
     }
 
@@ -110,7 +94,14 @@ async function main() {
       tool: toolName,
       error: err.message,
     });
-    finish(root, 'allow', null, null, toolName);
+    finish(
+      root,
+      'deny',
+      `PreToolUse hook error — blocked for safety: ${err.message}`,
+      null,
+      toolName,
+      { gate: 'hook-error' },
+    );
   }
 }
 

package/dist/integrations/grok/hooks/session-start.js

@@ -14,15 +14,34 @@ import {
   writeSessionBoot,
 } from './grok-hook-utils.js';
 import { appendHookActivity } from './grok-hook-activity.js';
+import { recordSynthesisTurnSlice } from '../../hooks/synthesis-hook-runtime.mjs';
 
-const HOOK_EVENT = process.env.GROK_HOOK_EVENT || 'session_start';
+function resolveHookEvent(event) {
+  if (process.env.GROK_HOOK_EVENT) return process.env.GROK_HOOK_EVENT;
+  const flag = process.argv.find((a) => a.startsWith('--hook-event='));
+  if (flag) return flag.slice('--hook-event='.length);
+  if (
+    event.prompt != null ||
+    event.userMessage != null ||
+    event.user_prompt != null ||
+    event.hook === 'UserPromptSubmit'
+  ) {
+    return 'user_prompt_submit';
+  }
+  return 'session_start';
+}
 
 async function main() {
   const root = workspaceRoot();
+  let HOOK_EVENT = 'session_start';
   try {
     const event = await readStdinJson();
+    HOOK_EVENT = resolveHookEvent(event);
     const eventRoot = event.workspaceRoot || event.cwd || root;
     const sessionId = resolveSessionId(event);
+    if (HOOK_EVENT === 'user_prompt_submit' && sessionId) {
+      recordSynthesisTurnSlice(eventRoot, sessionId);
+    }
     if (clearPendingDelegationsForSessionChange(sessionId, eventRoot)) {
       appendHookActivity(eventRoot, 'grok-session-start', 'stale-pending-cleared', 'info', {
         sessionId,

package/dist/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -36,7 +36,8 @@
             "type": "command",
             "command": "node",
             "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js",
+              "--hook-event=user_prompt_submit"
             ],
             "timeout": 15000
           }

package/dist/integrations/hermes-agent/bridge.mjs

@@ -39,6 +39,7 @@ import {
 import { join, dirname, relative } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
+import { findProjectRoot } from "../../../scripts/helpers/find-project-root.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -52,62 +53,19 @@ let frameworkReady = false;
 let frameworkLoadAttempted = false;
 
 // ── Project root detection ───────────────────────────────────
-function isConsumerWorkspace(dir) {
-  return (
-    existsSync(join(dir, ".xray", "features.json")) ||
-    existsSync(join(dir, "node_modules", "0xray", "package.json"))
-  );
-}
-
-function findProjectRoot() {
-  const envHome = process.env.XRAY_HOME || process.env.XRAY_ROOT;
-  if (envHome) {
-    const resolved = join(envHome);
-    if (existsSync(join(resolved, "package.json")) || isConsumerWorkspace(resolved)) {
-      return resolved;
-    }
-  }
-
+function resolveBridgeProjectRoot() {
   const consumerMarker = join(__dirname, "xray-consumer-root.txt");
   if (existsSync(consumerMarker)) {
     try {
       const marked = readFileSync(consumerMarker, "utf-8").trim();
-      if (marked && (existsSync(join(marked, "package.json")) || isConsumerWorkspace(marked))) {
+      if (marked && existsSync(join(marked, "package.json"))) {
         return marked;
       }
     } catch {
-      // fall through
+      // fall through to shared SSOT
     }
   }
-
-  // Prefer consumer workspace (--cwd / process.chdir) over framework package root
-  let dir = process.cwd();
-  for (let i = 0; i < 12; i++) {
-    if (isConsumerWorkspace(dir)) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-
-  const candidates = [
-    join(homedir(), "dev", "xray"),
-    join(dirname(__dirname), "..", "..", "..", ".."), // plugin dir -> package root
-  ];
-
-  for (const candidate of candidates) {
-    try {
-      const pkgPath = join(candidate, "package.json");
-      if (existsSync(pkgPath)) {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        if (pkg.name === "0xray" || pkg.dependencies?.["0xray"]) {
-          return candidate;
-        }
-      }
-    } catch {
-      continue;
-    }
-  }
-  return process.cwd();
+  return findProjectRoot([join(dirname(__dirname), "..", "..", "..", "..")]);
 }
 
 // ── Log directory ────────────────────────────────────────────
@@ -403,7 +361,7 @@ async function runProcessors(tool, args, phase, projectRoot, logDir) {
 // ── Command handlers ─────────────────────────────────────────
 
 async function handleHealth(input) {
-  const projectRoot = findProjectRoot();
+  const projectRoot = resolveBridgeProjectRoot();
   const loaded = await loadFramework(projectRoot);
 
   const components = {
@@ -760,7 +718,7 @@ function handleStats() {
     qualityGateAvailable: !!runQualityGateWithLogging,
     processorsAvailable: !!ProcessorManager,
     nodeVersion: process.version,
-    projectRoot: findProjectRoot(),
+    projectRoot: resolveBridgeProjectRoot(),
   };
 }
 
@@ -811,6 +769,16 @@ const KNOWN_COMMANDS = new Set([
   "skill-install", "skill-registry", "delegation-gate",
 ]);
 
+async function recordHermesSynthesisTurn(projectRoot, sessionId) {
+  if (!sessionId) return;
+  try {
+    const { recordSynthesisTurnSlice } = await import("../hooks/synthesis-hook-runtime.mjs");
+    recordSynthesisTurnSlice(projectRoot, sessionId);
+  } catch {
+    /* optional */
+  }
+}
+
 async function handleDelegationGate(command, projectRoot, logDir) {
   try {
     const gate = await import("../hooks/delegation-gate-runtime.mjs");
@@ -834,6 +802,10 @@ async function handleDelegationGate(command, projectRoot, logDir) {
       return { allow: true, phase: "post", ...result };
     }
 
+    if (command.recordTurn === true || command.event === 'user_prompt_submit') {
+      await recordHermesSynthesisTurn(projectRoot, sessionId);
+    }
+
     const features = gate.loadDelegationGateFeatures(projectRoot);
     const outcome = gate.evaluatePreToolGate(tool, args, {
       projectRoot,
@@ -935,7 +907,7 @@ async function main() {
     }
   }
 
-  const projectRoot = findProjectRoot();
+  const projectRoot = resolveBridgeProjectRoot();
   const logDir = ensureLogDir(projectRoot);
 
   // Log session start for test verification