0xray 3.4.5 → 3.4.7

package/.xray/config.json

@@ -1,6 +1,5 @@
 {
   "$schema": "./config.schema.json",
-  "version": "3.1.0",
   "description": "0xRay Framework - Token Management & Performance Configuration",
   "token_management": {
     "maxPromptTokens": 20000,

package/AGENTS-consumer.md

@@ -1,8 +1,10 @@
 # 0xRay AI Agents
 
+<!-- 0xray-managed -->
+
 Quick reference for the 0xRay AI orchestration framework (shipped to your project on `npm install 0xray`).
 
-**v3.4.5** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
+**v3.4.7** — 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.4.5**).
+Quick reference for the xray AI orchestration framework (**v3.4.7**).
 
 **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.4.5** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.4.7** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 xray is the pure v2 three-subsystem AI orchestration framework — **MCP-centric**, governed by Dynamo, and autonomous via thinDispatch. Consumer `npm install 0xray` auto-wires all four platform bridges and seven MCP servers with zero manual config.
 

package/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.4.5** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.4.7** — **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/AGENTS.md

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

package/dist/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [3.4.7] - 2026-06-18
+
+### 🐛 Bug Fixes
+- **Release gate upgrade smoke** — `consumer-install-smoke` simulates consumer opt-in merge on every publish
+- **Release pipeline** — artifacts sync before gate; idempotent `npm publish`; tag after publish
+- **Postinstall** — skip customized `AGENTS.md`; hard-fail on bridge wiring errors
+- **pre-publish-guard** — allow `.xray/config.json` and `.xray/state/` runtime dirt between gate steps
+
+---
+
+## [3.4.6] - 2026-06-18
+
+### 🐛 Bug Fixes
+- **Postinstall config merge** — `deployXrayConfig` deep-merges existing consumer `features.json`, `codex.json`, and `config.json` instead of overwriting on mtime; consumer opt-ins (e.g. `memory_routing`) are preserved and `features.version` bumps to the installed package
+
+---
+
 ## [3.4.5] - 2026-06-18
 
 ### ✨ Features

package/dist/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.4.5** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.4.7** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 xray is the pure v2 three-subsystem AI orchestration framework — **MCP-centric**, governed by Dynamo, and autonomous via thinDispatch. Consumer `npm install 0xray` auto-wires all four platform bridges and seven MCP servers with zero manual config.
 

package/dist/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.4.5** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.4.7** — **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.4.5",
+  "version": "3.4.7",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",

package/scripts/node/consumer-install-smoke.mjs

@@ -3,6 +3,7 @@
  * consumer-install-smoke.mjs — Clean-room pack + install verification.
  *
  * Simulates what consumers receive from npm without publishing.
+ * Runs fresh install checks + upgrade merge simulation.
  *
  * Usage:
  *   node scripts/node/consumer-install-smoke.mjs
@@ -38,6 +39,85 @@ function run(cmd, cwd, { inherit = false } = {}) {
   return inherit ? "" : String(result).trim();
 }
 
+function assertFreshInstallDefaults(tmpRoot, version) {
+  const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
+  if (!fs.existsSync(consumerFeaturesPath)) {
+    throw new Error(".xray/features.json not deployed to consumer project by postinstall");
+  }
+  const features = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
+  if (!features.memory_routing) {
+    throw new Error("Deployed features.json missing memory_routing block");
+  }
+  if (features.memory_routing.enabled !== false) {
+    throw new Error(
+      `Fresh install must default memory_routing.enabled=false (got ${features.memory_routing.enabled})`,
+    );
+  }
+  if (!features.inference_governance) {
+    throw new Error("Deployed features.json missing inference_governance block");
+  }
+  if (features.inference_governance.enabled !== false) {
+    throw new Error("Fresh install must default inference_governance.enabled=false");
+  }
+  console.log("  ✅ .xray/features.json fresh-install defaults (opt-in off)");
+  return { consumerFeaturesPath, features };
+}
+
+function runUpgradeMergeSmoke(tmpRoot, nmRoot, version) {
+  console.log("\n📋 Upgrade merge smoke (consumer opt-ins preserved)...");
+
+  const { deployXrayConfig } = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
+  const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
+
+  fs.writeFileSync(
+    consumerFeaturesPath,
+    `${JSON.stringify(
+      {
+        version: "3.4.0",
+        memory_routing: {
+          enabled: true,
+          provider: "repertoire",
+          module_path: "dist/provider/memory-routing-provider.js",
+        },
+        inference_governance: { enabled: true },
+        consumer_custom_block: { kept: true },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  const shippedTemplate = JSON.parse(
+    fs.readFileSync(path.join(nmRoot, "xray/features.json"), "utf-8"),
+  );
+  const shippedMarker = shippedTemplate.token_optimization ? "token_optimization" : null;
+
+  deployXrayConfig(tmpRoot, nmRoot, () => {});
+
+  const merged = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
+
+  if (merged.memory_routing?.enabled !== true) {
+    throw new Error(`Upgrade merge lost memory_routing.enabled (got ${merged.memory_routing?.enabled})`);
+  }
+  if (merged.memory_routing?.provider !== "repertoire") {
+    throw new Error(`Upgrade merge lost memory_routing.provider (got ${merged.memory_routing?.provider})`);
+  }
+  if (merged.inference_governance?.enabled !== true) {
+    throw new Error("Upgrade merge lost inference_governance.enabled");
+  }
+  if (merged.consumer_custom_block?.kept !== true) {
+    throw new Error("Upgrade merge dropped consumer-only keys");
+  }
+  if (merged.version !== version) {
+    throw new Error(`Upgrade merge version: expected ${version}, got ${merged.version}`);
+  }
+  if (shippedMarker && !merged[shippedMarker]) {
+    throw new Error(`Upgrade merge missing shipped template key: ${shippedMarker}`);
+  }
+
+  console.log("  ✅ upgrade merge preserves opt-ins + bumps features.version");
+}
+
 function main() {
   console.log("\n=== Consumer Install Smoke ===\n");
 
@@ -94,7 +174,7 @@ function main() {
     }
 
     const bridges = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
-    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall"]) {
+    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall", "deployXrayConfig"]) {
       if (typeof bridges[exp] !== "function") {
         throw new Error(`install-bridges missing export: ${exp}`);
       }
@@ -106,7 +186,6 @@ function main() {
     }
     console.log("  ✅ consumer target resolution");
 
-    // Postinstall should have run; verify .mcp.json merge
     const mcpPath = path.join(tmpRoot, ".mcp.json");
     if (!fs.existsSync(mcpPath)) {
       throw new Error(".mcp.json not created by postinstall");
@@ -124,26 +203,7 @@ function main() {
     }
     console.log(`  ✅ .mcp.json has ${XRAY_MCP_NAMES.length} npx MCP servers`);
 
-    const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
-    if (!fs.existsSync(consumerFeaturesPath)) {
-      throw new Error(".xray/features.json not deployed to consumer project by postinstall");
-    }
-    const features = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
-    if (!features.memory_routing) {
-      throw new Error("Deployed features.json missing memory_routing block");
-    }
-    if (features.memory_routing.enabled !== false) {
-      throw new Error(
-        `Shipped template must default memory_routing.enabled=false (got ${features.memory_routing.enabled})`,
-      );
-    }
-    if (!features.inference_governance) {
-      throw new Error("Deployed features.json missing inference_governance block");
-    }
-    if (features.inference_governance.enabled !== false) {
-      throw new Error("Shipped template must default inference_governance.enabled=false");
-    }
-    console.log("  ✅ .xray/features.json deployed (memory_routing + inference_governance opt-in defaults)");
+    assertFreshInstallDefaults(tmpRoot, version);
 
     const schemaInPackage = path.join(nmRoot, "xray", "features.schema.json");
     if (!fs.existsSync(schemaInPackage)) {
@@ -151,6 +211,8 @@ function main() {
     }
     console.log("  ✅ xray/features.schema.json in package");
 
+    runUpgradeMergeSmoke(tmpRoot, nmRoot, version);
+
     console.log("\n✅ Consumer install smoke passed\n");
   } catch (err) {
     console.error(`\n❌ Consumer smoke failed: ${err.message}\n`);

package/scripts/node/install-bridges.cjs

@@ -403,6 +403,64 @@ function installOpenclawBridge(targetDir, packageRoot, log) {
 
 const XRAY_CONFIG_FILES = ["codex.json", "features.json", "features.schema.json", "config.json"];
 
+/** Consumer JSON configs merge on upgrade — consumer values win; shipped fills new keys. */
+const MERGE_CONFIG_FILES = new Set(["features.json", "config.json", "codex.json"]);
+
+function readPackageVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(filePath, data) {
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function deployXrayConfigFile(file, src, dst, packageRoot) {
+  if (!fs.existsSync(dst)) {
+    fs.copyFileSync(src, dst);
+    return true;
+  }
+
+  if (file === "features.schema.json") {
+    if (fs.statSync(src).mtime > fs.statSync(dst).mtime) {
+      fs.copyFileSync(src, dst);
+      return true;
+    }
+    return false;
+  }
+
+  if (MERGE_CONFIG_FILES.has(file)) {
+    try {
+      const shipped = JSON.parse(fs.readFileSync(src, "utf8"));
+      const consumer = JSON.parse(fs.readFileSync(dst, "utf8"));
+      const merged = deepMerge(shipped, consumer);
+      if (file === "features.json") {
+        const pkgVersion = readPackageVersion(packageRoot);
+        if (pkgVersion) merged.version = pkgVersion;
+        else if (shipped.version) merged.version = shipped.version;
+      }
+      writeJsonFile(dst, merged);
+      return true;
+    } catch {
+      if (fs.statSync(src).mtime > fs.statSync(dst).mtime) {
+        fs.copyFileSync(src, dst);
+        return true;
+      }
+      return false;
+    }
+  }
+
+  if (fs.statSync(src).mtime > fs.statSync(dst).mtime) {
+    fs.copyFileSync(src, dst);
+    return true;
+  }
+  return false;
+}
+
 function resolveXrayConfigSource(packageRoot, file) {
   // Shipped SSOT: xray/ template wins over dev .xray/ runtime copy (P0.2)
   const xrayDir = path.join(packageRoot, "xray", file);
@@ -423,9 +481,7 @@ function deployXrayConfig(targetDir, packageRoot, log) {
     const src = resolveXrayConfigSource(packageRoot, file);
     const dst = path.join(xrayTargetDir, file);
     if (!src) continue;
-    const shouldCopy = !fs.existsSync(dst) || fs.statSync(src).mtime > fs.statSync(dst).mtime;
-    if (shouldCopy) {
-      fs.copyFileSync(src, dst);
+    if (deployXrayConfigFile(file, src, dst, packageRoot)) {
       copied++;
     }
   }
@@ -479,6 +535,8 @@ module.exports = {
   syncBuiltinSkills,
   isConsumerInstall,
   deployXrayConfig,
+  deployXrayConfigFile,
   resolveXrayConfigSource,
   XRAY_CONFIG_FILES,
+  MERGE_CONFIG_FILES,
 };

package/scripts/node/postinstall.cjs

@@ -19,11 +19,24 @@ const targetDir = resolveConsumerTargetDir(packageRoot, process.env.PWD || proce
 const resolvedPackage = path.resolve(packageRoot);
 const resolvedTarget = path.resolve(targetDir);
 
-// Copy AGENTS-consumer.md → AGENTS.md
+const XRAY_MANAGED_AGENTS_MARKER = "<!-- 0xray-managed -->";
+
+// Copy AGENTS-consumer.md → AGENTS.md (only if absent or still 0xray-managed)
 const agentsConsumer = path.join(packageRoot, "AGENTS-consumer.md");
 const agentsDest = path.join(targetDir, "AGENTS.md");
 if (fs.existsSync(agentsConsumer) && isConsumerInstall(resolvedPackage, resolvedTarget)) {
-  fs.copyFileSync(agentsConsumer, agentsDest);
+  const shouldDeployAgents =
+    !fs.existsSync(agentsDest) ||
+    fs.readFileSync(agentsDest, "utf8").includes(XRAY_MANAGED_AGENTS_MARKER);
+  if (shouldDeployAgents) {
+    let content = fs.readFileSync(agentsConsumer, "utf8");
+    if (!content.includes(XRAY_MANAGED_AGENTS_MARKER)) {
+      content = `${content.trimEnd()}\n\n${XRAY_MANAGED_AGENTS_MARKER}\n`;
+    }
+    fs.writeFileSync(agentsDest, content);
+  } else {
+    structuredLog("postinstall", "Skipped AGENTS.md (consumer-customized)", "info");
+  }
 }
 
 // Copy .gitignore.default → .gitignore (never overwrite existing)
@@ -43,7 +56,9 @@ if (isConsumerInstall(resolvedPackage, resolvedTarget)) {
       log: structuredLog,
     });
   } catch (e) {
-    structuredLog("postinstall", "Bridge install failed", "warn", { error: e.message });
+    structuredLog("postinstall", "Bridge install failed", "error", { error: e.message });
+    console.error("\n❌ 0xRay postinstall failed — bridge wiring did not complete.\n");
+    process.exit(1);
   }
 
   structuredLog(

package/scripts/node/pre-publish-guard.js

@@ -67,6 +67,8 @@ const ARTIFACT_PREFIXES = [
   '.opencode/activity-report.json',
   '.opencode/init.sh',
   '.xray/inference/',
+  '.xray/config.json',
+  '.xray/state/',
   'logs/',
   'backups/',
   '.ci-reports/',

package/scripts/node/release-gate.mjs

@@ -3,8 +3,8 @@
  * release-gate.mjs — Single release checkpoint.
  *
  * Modes:
- *   (default)     build + test + consumer smoke — run once before commit
- *   --verify-only git + reconcile + release docs + consumer smoke — after push, before tag
+ *   (default)     build + test + consumer smoke (fresh + upgrade merge)
+ *   --verify-only git + reconcile + release docs + consumer smoke — after push, before publish
  *   --skip-smoke  skip consumer install smoke
  *   --skip-docs   skip release docs validation (not recommended for publish)
  *
@@ -47,10 +47,7 @@ function main() {
       step("1/4 Build", "npm run build");
       step("2/4 Tests", "npm test");
       if (!skipSmoke) {
-        step("3/4 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
-      }
-      if (!skipDocs && process.argv.includes("--with-docs")) {
-        step("4/4 Release docs", "node scripts/node/validate-release-docs.mjs");
+        step("3/4 Consumer install smoke (fresh + upgrade)", "node scripts/node/consumer-install-smoke.mjs");
       }
     }
 

package/scripts/node/release.mjs

@@ -4,16 +4,15 @@
  * Canonical 0xRay release script.
  *
  * 1. Bump version from npm registry baseline (reconcile-version)
- * 2. Release gate once (build + test + consumer smoke)
- * 3. Update CHANGELOG / README / AGENTS / docs (version-manager --artifacts-only)
+ * 2. Release artifacts (CHANGELOG / README / AGENTS / docs) — before gate so docs tests pass
+ * 3. Release gate (build + test + consumer smoke)
  * 4. Commit release artifacts → push
  * 5. Verify gate (reconcile + git + release docs + smoke)
- * 6. Tag → push tag → npm publish
+ * 6. npm publish (idempotent — skip if version already on registry)
+ * 7. Tag → push tag (only after successful publish)
  *
  * Usage:
  *   npm run release:patch
- *   npm run release:minor
- *   npm run release:major
  *   node scripts/node/release.mjs patch --dry-run
  */
 
@@ -44,6 +43,32 @@ function currentBranch() {
   return execSync("git rev-parse --abbrev-ref HEAD", { cwd: rootDir, encoding: "utf-8" }).trim();
 }
 
+function npmVersionPublished(version) {
+  try {
+    const out = execSync(`npm view 0xray@${version} version`, {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out === version;
+  } catch {
+    return false;
+  }
+}
+
+function publishIdempotent(version) {
+  if (dryRun) {
+    console.log(`  would: npm publish --access public (check 0xray@${version} first)`);
+    return;
+  }
+  if (npmVersionPublished(version)) {
+    console.log(`ℹ️  0xray@${version} already on npm — skipping publish`);
+    return;
+  }
+  execSync("npm publish --access public", { cwd: rootDir, stdio: "inherit", encoding: "utf-8" });
+  console.log(`✅ Published 0xray@${version}`);
+}
+
 async function main() {
   if (!["major", "minor", "patch"].includes(releaseType)) {
     console.error("Usage: node scripts/node/release.mjs [patch|minor|major] [--dry-run]");
@@ -70,14 +95,14 @@ async function main() {
     : readVersion();
   console.log(`📌 Release version: ${newVersion}`);
 
-  // 2. Single gate before commit
-  console.log("\n📦 Step 2: Release gate (build + test + smoke)");
-  run("node scripts/node/release-gate.mjs", "release gate");
-
-  // 3. Changelog + doc artifacts
-  console.log("\n📦 Step 3: Release artifacts (CHANGELOG, README, AGENTS, docs)");
+  // 2. Artifacts BEFORE gate (docs vitest matches package.json version)
+  console.log("\n📦 Step 2: Release artifacts (CHANGELOG, README, AGENTS, docs)");
   run("node scripts/node/version-manager.mjs --artifacts-only", "release artifacts");
 
+  // 3. Gate
+  console.log("\n📦 Step 3: Release gate (build + test + smoke)");
+  run("node scripts/node/release-gate.mjs", "release gate");
+
   // 4. Commit + push
   console.log("\n📦 Step 4: Commit & push");
   const releaseFiles = getReleaseArtifactPaths();
@@ -97,24 +122,33 @@ async function main() {
   const branch = currentBranch();
   run(`git push origin ${branch}`, "git push");
 
-  // 5. Post-push verify before tag
-  console.log("\n📦 Step 5: Verify gate (reconcile + git + smoke)");
+  // 5. Post-push verify before publish
+  console.log("\n📦 Step 5: Verify gate (reconcile + git + docs + smoke)");
   run("node scripts/node/release-gate.mjs --verify-only", "verify gate");
 
-  // 6. Tag
-  console.log("\n📦 Step 6: Tag");
+  // 6. Publish (idempotent)
+  console.log("\n📦 Step 6: npm publish");
+  publishIdempotent(newVersion);
+
+  // 7. Tag after publish
+  console.log("\n📦 Step 7: Tag");
   if (!dryRun) {
-    execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
-    console.log(`✅ Created tag v${newVersion}`);
+    try {
+      execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+      console.log(`✅ Created tag v${newVersion}`);
+    } catch (e) {
+      const msg = String(e.stderr || e.message || "");
+      if (msg.includes("already exists")) {
+        console.log(`ℹ️  Tag v${newVersion} already exists`);
+      } else {
+        throw e;
+      }
+    }
   } else {
     console.log(`  would: git tag -a v${newVersion}`);
   }
   run(`git push origin v${newVersion}`, "push tag");
 
-  // 7. Publish
-  console.log("\n📦 Step 7: npm publish");
-  run("npm publish --access public", "npm publish");
-
   console.log("\n╔════════════════════════════════════════════════════════╗");
   console.log("║        ✅ Release Complete!                            ║");
   console.log("╚════════════════════════════════════════════════════════╝");
@@ -125,7 +159,7 @@ async function main() {
       fs.mkdirSync(path.join(rootDir, "tweets"), { recursive: true });
       fs.writeFileSync(
         tweetPath,
-        `🎉 0xRay v${newVersion} is LIVE - {THEME}!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
+        `🎉 0xRay v${newVersion} is LIVE - consumer-safe upgrades!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
       );
       console.log(`📝 Tweet template: tweets/v${newVersion}.md`);
     }