0xray 3.5.1 → 3.5.3

package/scripts/hooks/install-hooks.cjs

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 /**
- * install-hooks.cjs — Installs xray pre-commit hook into the consumer project's .git/hooks/.
+ * install-hooks.cjs — Installs xray pre-commit + post-commit hooks into consumer .git/hooks/.
  *
- * Called from setup.cjs or standalone via:
+ * Called from postinstall.cjs or standalone via:
  *   node scripts/hooks/install-hooks.cjs
- *
- * Creates a consumer-aware pre-commit hook that references the installed
- * package's run-hook.js and LightweightValidator via node_modules/ paths.
  */
 
 const fs = require("fs");
@@ -15,7 +12,6 @@ const { execSync } = require("child_process");
 
 const packageRoot = path.resolve(path.join(__dirname, "..", ".."));
 
-// Determine the target project root (where .git/ lives)
 let targetDir;
 try {
   targetDir = execSync("git rev-parse --show-toplevel 2>/dev/null", {
@@ -33,34 +29,49 @@ if (!fs.existsSync(gitHooksDir)) {
   process.exit(0);
 }
 
-// Check if we're in a consumer install (via node_modules) or dev
 const isConsumer = packageRoot.includes("node_modules");
-
-// Resolve run-hook.js path
-// In dev: scripts/hooks/run-hook.js (relative to project root)
-// In consumer: node_modules/0xray/scripts/hooks/run-hook.js (relative to project root)
 const runHookRelativePath = isConsumer
   ? "node_modules/0xray/scripts/hooks/run-hook.js"
   : "scripts/hooks/run-hook.js";
+const loadReflectionRelativePath = isConsumer
+  ? "node_modules/0xray/scripts/node/load-reflection-config.mjs"
+  : "scripts/node/load-reflection-config.mjs";
+const autoReflectionRelativePath = isConsumer
+  ? "node_modules/0xray/scripts/node/auto-reflection-generator.mjs"
+  : "scripts/node/auto-reflection-generator.mjs";
 
-const hookContent = `#!/bin/bash
+function hookRunnerExists(projectRoot) {
+  return (
+    fs.existsSync(path.join(projectRoot, "node_modules/0xray/scripts/hooks/run-hook.js")) ||
+    fs.existsSync(path.join(projectRoot, "scripts/hooks/run-hook.js"))
+  );
+}
+
+function isXrayHookContent(content) {
+  return content.includes("0xRay") || content.includes("xray");
+}
+
+function backupExistingHook(hookPath) {
+  const backupPath = `${hookPath}.backup-${Date.now()}`;
+  fs.copyFileSync(hookPath, backupPath);
+  console.log(`ℹ️  Backed up existing hook to ${path.basename(backupPath)}`);
+}
+
+const preCommitContent = `#!/bin/bash
 # 0xRay Pre-Commit Hook — Consumer Install
-# Installed by xray setup on $(new Date().toISOString().split('T')[0])
-# Runs TypeScript check, linting, and Codex validation before commit
+# Installed by xray setup on ${new Date().toISOString().split("T")[0]}
 # BLOCKS the commit if validation fails
 
 set -e
 
 PROJECT_ROOT=$(git rev-parse --show-toplevel)
 
-# Get staged files (only source files)
 STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(ts|tsx|js|jsx|mjs)$' || true)
 
 if [ -z "$STAGED_FILES" ]; then
   exit 0
 fi
 
-# Run the Node.js hook runner
 if command -v node >/dev/null 2>&1; then
   export HOOK_TYPE="pre-commit"
   export STAGED_FILES="$STAGED_FILES"
@@ -69,32 +80,121 @@ if command -v node >/dev/null 2>&1; then
     node "$PROJECT_ROOT/${runHookRelativePath}" pre-commit
     exit $?
   else
-    echo "Warning: xray hook runner not found — install may be incomplete"
-    exit 0
+    echo "Error: xray hook runner not found at ${runHookRelativePath} — run npm install 0xray"
+    exit 1
   fi
 else
-  echo "Warning: Node.js not found, skipping xray pre-commit validation"
-  exit 0
+  echo "Error: Node.js not found — xray pre-commit validation requires node"
+  exit 1
 fi
 `;
 
-const hookPath = path.join(gitHooksDir, "pre-commit");
-const existing = fs.existsSync(hookPath);
-if (existing) {
-  const existingContent = fs.readFileSync(hookPath, "utf-8");
-  if (existingContent.includes("0xRay") || existingContent.includes("xray")) {
-    console.log("ℹ️  Pre-commit hook already installed by xray — skipping");
-    process.exit(0);
-  }
-}
+const postCommitContent = `#!/bin/bash
+# 0xRay Post-Commit Hook — Consumer Install
+# Runs activity logging and auto-reflection after commit (non-blocking)
 
-try {
-  fs.writeFileSync(hookPath, hookContent, { mode: 0o755 });
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+COMMIT_SHA=$(git rev-parse HEAD)
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+(
+  if command -v node >/dev/null 2>&1 && [ -f "$PROJECT_ROOT/${runHookRelativePath}" ]; then
+    export HOOK_TYPE="post-commit"
+    export COMMIT_SHA="$COMMIT_SHA"
+    export BRANCH="$BRANCH"
+    export PROJECT_ROOT="$PROJECT_ROOT"
+    node "$PROJECT_ROOT/${runHookRelativePath}" post-commit 2>/dev/null || true
+  fi
+) &
+
+MODE="minimal"
+COMMIT_THRESHOLD=25
+DAYS_THRESHOLD=14
+AUTO_GENERATE=true
+PROMPT_USER=true
+
+if command -v node >/dev/null 2>&1; then
+  LOAD_SCRIPT="$PROJECT_ROOT/${loadReflectionRelativePath}"
+  if [ -f "$LOAD_SCRIPT" ]; then
+    export PROJECT_ROOT="$PROJECT_ROOT"
+    REFLECTION_JSON=$(node "$LOAD_SCRIPT" --json 2>/dev/null || echo '{}')
+    MODE=$(node -e 'const c=JSON.parse(process.argv[1]);process.stdout.write(String(c.mode||"minimal"))' "$REFLECTION_JSON")
+    COMMIT_THRESHOLD=$(node -e 'const c=JSON.parse(process.argv[1]);process.stdout.write(String(c.commitThreshold??25))' "$REFLECTION_JSON")
+    DAYS_THRESHOLD=$(node -e 'const c=JSON.parse(process.argv[1]);process.stdout.write(String(c.daysThreshold??14))' "$REFLECTION_JSON")
+    AUTO_GENERATE=$(node -e 'const c=JSON.parse(process.argv[1]);process.stdout.write(c.autoGenerate===false?"false":"true")' "$REFLECTION_JSON")
+    PROMPT_USER=$(node -e 'const c=JSON.parse(process.argv[1]);process.stdout.write(c.promptUser===false?"false":"true")' "$REFLECTION_JSON")
+  fi
+fi
+
+COMMIT_MSG=$(git log -1 --pretty=%B)
+SIGNIFICANT_KEYWORDS="fix|bug|debug|deploy|release|feature|refactor|kernel|learning|pattern|wire|connect|integrate"
+
+if echo "$COMMIT_MSG" | grep -qiE "$SIGNIFICANT_KEYWORDS" && [ "$PROMPT_USER" = true ]; then
+  echo ""
+  echo "📝 REFLECTION SUGGESTION: This commit appears to involve significant changes."
+  echo "   Consider writing a reflection using the v3.0 template:"
+  echo "   → cat docs/reflections/TEMPLATE_v3.md"
+  echo ""
+fi
+
+if [ "$AUTO_GENERATE" = true ] && [ -d "$PROJECT_ROOT/docs/reflections" ]; then
+  if stat --version >/dev/null 2>&1; then
+    LAST_REFLECTION=$(find "$PROJECT_ROOT/docs/reflections" -name "*.md" -type f -exec stat --format="%Y" {} \\; 2>/dev/null | sort -rn | head -1)
+  else
+    LAST_REFLECTION=$(find "$PROJECT_ROOT/docs/reflections" -name "*.md" -type f -exec stat -f "%m" {} \\; 2>/dev/null | sort -rn | head -1)
+  fi
+
+  if [ -n "$LAST_REFLECTION" ]; then
+    REFLECTION_EPOCH=$(date -r "$LAST_REFLECTION" +%s 2>/dev/null || echo "0")
+    NOW_EPOCH=$(date +%s)
+    DAYS_SINCE=$(( (NOW_EPOCH - REFLECTION_EPOCH) / 86400 ))
+    COMMITS_SINCE=$(git log --since="$LAST_REFLECTION" --oneline 2>/dev/null | wc -l | tr -d ' ')
+  else
+    DAYS_SINCE=999
+    COMMITS_SINCE=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+  fi
+
+  if [ "$COMMITS_SINCE" -gt "$COMMIT_THRESHOLD" ] || [ "$DAYS_SINCE" -gt "$DAYS_THRESHOLD" ]; then
+    echo ""
+    echo "⚠️  AUTO-REFLECTION TRIGGERED (mode: $MODE)"
+    echo "   $COMMITS_SINCE commits since last reflection ($DAYS_SINCE days)"
+    if [ "$MODE" != "off" ]; then
+      cd "$PROJECT_ROOT"
+      if [ -f "$PROJECT_ROOT/${autoReflectionRelativePath}" ]; then
+        node "$PROJECT_ROOT/${autoReflectionRelativePath}" --trigger commit-threshold \\
+          --title "Multiple commits since last reflection" 2>/dev/null || true
+      fi
+    fi
+  fi
+fi
+
+exit 0
+`;
+
+function installHook(name, content, { forceReinstall = false } = {}) {
+  const hookPath = path.join(gitHooksDir, name);
+  const existing = fs.existsSync(hookPath);
   if (existing) {
-    console.log("✅ Pre-commit hook updated for xray validation");
-  } else {
-    console.log("✅ Pre-commit hook installed — runs Codex validation on every commit");
+    const existingContent = fs.readFileSync(hookPath, "utf-8");
+    const isXray = isXrayHookContent(existingContent);
+    if (isXray && hookRunnerExists(targetDir) && !forceReinstall) {
+      console.log(`ℹ️  ${name} hook already installed by xray — skipping`);
+      return false;
+    }
+    if (isXray && !hookRunnerExists(targetDir)) {
+      console.log(`⚠️  Stale xray ${name} hook detected — reinstalling`);
+    } else if (!isXray) {
+      backupExistingHook(hookPath);
+    }
   }
-} catch (e) {
-  console.warn(`⚠️ Failed to install pre-commit hook: ${e.message}`);
+  fs.writeFileSync(hookPath, content, { mode: 0o755 });
+  console.log(
+    existing
+      ? `✅ ${name} hook updated for xray`
+      : `✅ ${name} hook installed`,
+  );
+  return true;
 }
+
+installHook("pre-commit", preCommitContent);
+installHook("post-commit", postCommitContent);

package/scripts/hooks/run-hook.js

@@ -21,7 +21,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from "fs";
 import { join, dirname } from "path";
-import { execSync, exec } from "child_process";
+import { execSync, exec, execFileSync } from "child_process";
 
 // ── Parse arguments ──────────────────────────────────────────
 
@@ -92,14 +92,47 @@ function recordMetrics(duration, exitCode) {
 
 // ── TypeScript checking ──────────────────────────────────────
 
+function packageHasTypecheckScript() {
+  try {
+    const pkgPath = join(projectRoot, "package.json");
+    if (!existsSync(pkgPath)) return false;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return typeof pkg.scripts?.typecheck === "string" && pkg.scripts.typecheck.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 function runTypeScriptCheck(files) {
   /**
-   * Run tsc --noEmit on a subset of files.
-   * Falls back to full project check if per-file fails.
+   * Prefer npm run typecheck when defined (matches CI).
+   * Otherwise tsc --noEmit on staged files or full project.
    */
   log("Running TypeScript validation...");
 
   try {
+    if (packageHasTypecheckScript()) {
+      try {
+        execSync("npm run typecheck", {
+          cwd: projectRoot,
+          encoding: "utf-8",
+          timeout: 120000,
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        log("npm run typecheck passed");
+        return { passed: true, errors: [] };
+      } catch (err) {
+        const stderr = (err.stderr || err.stdout || "").toString();
+        const errorLines = stderr
+          .split("\n")
+          .filter((l) => /error TS\d+/.test(l))
+          .map((l) => l.trim())
+          .slice(0, 20);
+        log(`npm run typecheck failed: ${errorLines.length} errors`);
+        return { passed: false, errors: errorLines };
+      }
+    }
+
     // Check if tsconfig.json exists
     const tsconfigPath = join(projectRoot, "tsconfig.json");
     if (!existsSync(tsconfigPath)) {
@@ -115,12 +148,16 @@ function runTypeScriptCheck(files) {
     const tsFiles = files.filter((f) => /\.(ts|tsx)$/.test(f));
     if (tsFiles.length > 0 && tsFiles.length <= 20) {
       try {
-        execSync(`${tscCmd} --noEmit ${tsFiles.map((f) => `"${f}"`).join(" ")}`, {
-          cwd: projectRoot,
-          encoding: "utf-8",
-          timeout: 30000,
-          stdio: ["pipe", "pipe", "pipe"],
-        });
+        execFileSync(
+          tscCmd,
+          ["--noEmit", ...tsFiles],
+          {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            timeout: 30000,
+            stdio: ["pipe", "pipe", "pipe"],
+          },
+        );
         log(`TypeScript check passed: ${tsFiles.length} files`);
         return { passed: true, errors: [] };
       } catch (err) {

package/scripts/mjs/delegation-gate-fixture.mjs

@@ -60,6 +60,43 @@ export function seedDelegationGateFixture(tmp) {
   );
 }
 
+export const SYNTHESIS_FIXTURE_SESSION_ID = 'verify-synthesis';
+
+export function seedSynthesisDueFixture(tmp, sessionId = SYNTHESIS_FIXTURE_SESSION_ID) {
+  mkdirSync(join(tmp, '.xray', 'state'), { recursive: true });
+  const now = new Date().toISOString();
+  writeFileSync(
+    join(tmp, '.xray', 'features.json'),
+    JSON.stringify({
+      synthesis: {
+        enabled: true,
+        every_n_gates: 12,
+        every_n_turns: 0,
+        every_n_todos_completed: 0,
+      },
+      multi_agent_orchestration: {
+        enabled: true,
+        lead_dev_mode: true,
+        auto_chain_delegations: true,
+      },
+    }),
+  );
+  writeFileSync(
+    join(tmp, '.xray', 'state', 'synthesis-checkpoint.json'),
+    JSON.stringify({
+      version: 1,
+      sessionId,
+      slicesSinceLastSynthesis: { gates: 12, turns: 0, todosCompleted: 0 },
+      lifetimeSlices: { gates: 12, turns: 0, todosCompleted: 0 },
+      synthesisDue: true,
+      dueReason: 'gate_threshold',
+      lastSynthesisAt: null,
+      lastSliceAt: now,
+      synthesisCount: 0,
+    }),
+  );
+}
+
 export function seedSpawnTodoPlan(tmp) {
   writeFileSync(
     join(tmp, '.xray', 'state', 'lead-dev-plan.json'),

package/scripts/mjs/verify-grok-synthesis-gate.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Hook fixture verify — PreToolUse synthesis gate via live Grok hook path.
+ * Run: node scripts/mjs/verify-grok-synthesis-gate.mjs
+ */
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  SYNTHESIS_FIXTURE_SESSION_ID,
+  seedSynthesisDueFixture,
+} from './delegation-gate-fixture.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '../..');
+const preToolHook = join(packageRoot, 'dist/integrations/grok/hooks/pre-tool-use.js');
+
+let failed = 0;
+function pass(n) {
+  console.log(`✅ ${n}`);
+}
+function fail(n, d = '') {
+  failed++;
+  console.error(`❌ ${n}${d ? ` — ${d}` : ''}`);
+}
+
+function runHook(fixture, env = {}) {
+  const payload = JSON.stringify(fixture);
+  const out = execSync(`printf '%s' '${payload.replace(/'/g, "'\\''")}' | node "${preToolHook}"`, {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(out.trim());
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'xray-synth-grok-'));
+seedSynthesisDueFixture(tmp);
+
+const baseEnv = {
+  GROK_WORKSPACE_ROOT: tmp,
+  GROK_SESSION_ID: SYNTHESIS_FIXTURE_SESSION_ID,
+};
+
+try {
+  const denyWrite = runHook(
+    {
+      toolName: 'search_replace',
+      workspaceRoot: tmp,
+      sessionId: SYNTHESIS_FIXTURE_SESSION_ID,
+      toolInput: { path: 'src/a.ts', new_string: 'x' },
+    },
+    baseEnv,
+  );
+  if (denyWrite.decision === 'deny' && denyWrite.gate === 'synthesis-checkpoint') {
+    pass('PreToolUse denies write when synthesis due');
+  } else {
+    fail('synthesis write deny', JSON.stringify(denyWrite));
+  }
+
+  const allowRead = runHook(
+    {
+      toolName: 'read_file',
+      workspaceRoot: tmp,
+      sessionId: SYNTHESIS_FIXTURE_SESSION_ID,
+      toolInput: { path: 'src/a.ts' },
+    },
+    baseEnv,
+  );
+  if (allowRead.decision === 'allow') pass('PreToolUse allows read when synthesis due');
+  else fail('synthesis read allow', JSON.stringify(allowRead));
+
+  const allowConsult = runHook(
+    {
+      toolName: 'CallMcpTool',
+      workspaceRoot: tmp,
+      sessionId: SYNTHESIS_FIXTURE_SESSION_ID,
+      toolInput: {
+        server: 'xray-orchestrator',
+        toolName: 'analyze-complexity',
+        arguments: { tasks: [{ description: 'synthesis reflect', type: 'plan' }] },
+      },
+    },
+    baseEnv,
+  );
+  if (allowConsult.decision === 'allow') {
+    pass('PreToolUse allows analyze-complexity consult when synthesis due');
+  } else {
+    fail('synthesis consult allow', JSON.stringify(allowConsult));
+  }
+
+  const denyGovern = runHook(
+    {
+      toolName: 'CallMcpTool',
+      workspaceRoot: tmp,
+      sessionId: SYNTHESIS_FIXTURE_SESSION_ID,
+      toolInput: {
+        server: 'xray-orchestrator',
+        toolName: 'govern-and-apply',
+        arguments: { proposal: 'test' },
+      },
+    },
+    baseEnv,
+  );
+  if (denyGovern.decision === 'deny' && denyGovern.gate === 'synthesis-checkpoint') {
+    pass('PreToolUse denies govern-and-apply when synthesis due');
+  } else {
+    fail('synthesis govern deny', JSON.stringify(denyGovern));
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(
+  '\n' +
+    (failed === 0
+      ? '🎉 Grok synthesis gate verify passed (4/4).'
+      : `⚠️  ${failed} synthesis gate check(s) failed.`),
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/node/auto-reflection-generator.mjs

@@ -113,6 +113,13 @@ function loadConfig() {
     try {
       const content = readFileSync(configPath, "utf-8");
       const parsed = JSON.parse(content);
+      if (parsed.synthesis?.reflection) {
+        return {
+          mode: parsed.synthesis.reflection.mode ?? "minimal",
+          triggers: parsed.synthesis.reflection.triggers,
+          thresholds: parsed.synthesis.reflection.thresholds,
+        };
+      }
       if (parsed.auto_reflection) {
         return parsed.auto_reflection;
       }

package/scripts/node/consumer-gitignore.cjs

@@ -0,0 +1,101 @@
+/**
+ * Consumer .gitignore — template + idempotent merge into existing .gitignore.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const MARKER_START = "# --- 0xray suit (postinstall) ---";
+const MARKER_END = "# --- end 0xray suit ---";
+
+/** Suit artifacts dropped by postinstall / install-bridges — keep out of product repos */
+const SUIT_IGNORE_LINES = [
+  ".grok/",
+  ".mcp.json",
+  "opencode.json",
+  "AGENTS.md",
+  "SKILLS.md",
+  ".xray/",
+  ".strray/",
+  "strray/",
+  ".hermes/",
+  ".opencode/agents/",
+  ".opencode/commands/",
+  ".opencode/workflows/",
+  ".opencode/codex.codex",
+  ".opencode/enforcer-config.json",
+  ".opencode/skills/",
+  ".opencode/scripts/",
+  ".opencode/logs/",
+  ".opencode/validation/",
+  ".opencode/triage/",
+  "logs/framework/",
+];
+
+function buildMarkerBlock(lines = SUIT_IGNORE_LINES) {
+  return [MARKER_START, ...lines, MARKER_END].join("\n");
+}
+
+function stripMarkerBlock(content) {
+  const start = content.indexOf(MARKER_START);
+  if (start === -1) return content;
+  const end = content.indexOf(MARKER_END);
+  if (end === -1) {
+    // Incomplete marker — preserve content before START; orphan tail handled in merge
+    return content.slice(0, start).trimEnd();
+  }
+  const tail = content.slice(end + MARKER_END.length);
+  return `${content.slice(0, start).trimEnd()}${tail}`.trimEnd();
+}
+
+function markerBlockIsCurrent(raw) {
+  if (!raw.includes(MARKER_START) || !raw.includes(MARKER_END)) {
+    return false;
+  }
+  const start = raw.indexOf(MARKER_START);
+  const end = raw.indexOf(MARKER_END) + MARKER_END.length;
+  const blockSection = raw.slice(start, end);
+  return SUIT_IGNORE_LINES.every((line) => blockSection.includes(line));
+}
+
+/**
+ * @returns {'created' | 'merged' | 'unchanged'}
+ */
+function applyConsumerGitignore(targetDir, packageRoot) {
+  const gitignoreSource = path.join(packageRoot, ".gitignore.default");
+  const gitignoreDest = path.join(targetDir, ".gitignore");
+
+  if (!fs.existsSync(gitignoreSource)) {
+    return "unchanged";
+  }
+
+  if (!fs.existsSync(gitignoreDest)) {
+    fs.copyFileSync(gitignoreSource, gitignoreDest);
+    return "created";
+  }
+
+  const raw = fs.readFileSync(gitignoreDest, "utf8");
+  if (markerBlockIsCurrent(raw)) {
+    return "unchanged";
+  }
+
+  const hasIncompleteMarker =
+    raw.includes(MARKER_START) && !raw.includes(MARKER_END);
+  const orphanTail = hasIncompleteMarker
+    ? raw.slice(raw.indexOf(MARKER_START)).trimEnd()
+    : "";
+  const content = stripMarkerBlock(raw);
+  const next = orphanTail
+    ? `${content.trimEnd()}\n\n${buildMarkerBlock()}\n\n${orphanTail}\n`
+    : `${content.trimEnd()}\n\n${buildMarkerBlock()}\n`;
+  fs.writeFileSync(gitignoreDest, next);
+  return "merged";
+}
+
+module.exports = {
+  MARKER_START,
+  MARKER_END,
+  SUIT_IGNORE_LINES,
+  buildMarkerBlock,
+  stripMarkerBlock,
+  applyConsumerGitignore,
+};

package/scripts/node/load-reflection-config.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Emit reflection config for post-commit hook.
+ * SSOT: synthesis.reflection, fallback auto_reflection.
+ *
+ * Usage:
+ *   node load-reflection-config.mjs          # shell-safe export lines
+ *   node load-reflection-config.mjs --json   # JSON for hook parsers
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ALLOWED_MODES = new Set(['minimal', 'full', 'off']);
+
+const root = process.env.PROJECT_ROOT || process.cwd();
+const configPath = join(root, '.xray', 'features.json');
+
+let mode = 'minimal';
+let commitThreshold = 25;
+let daysThreshold = 14;
+let autoGenerate = true;
+let promptUser = true;
+
+if (existsSync(configPath)) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    const reflection = parsed.synthesis?.reflection ?? parsed.auto_reflection;
+    if (reflection) {
+      const rawMode = reflection.mode ?? 'minimal';
+      mode = ALLOWED_MODES.has(rawMode) ? rawMode : 'minimal';
+      const thresholds = reflection.thresholds?.[mode];
+      if (thresholds) {
+        if (typeof thresholds.commit_threshold === 'number') {
+          commitThreshold = thresholds.commit_threshold;
+        }
+        if (typeof thresholds.days_threshold === 'number') {
+          daysThreshold = thresholds.days_threshold;
+        }
+        if (typeof thresholds.auto_generate === 'boolean') {
+          autoGenerate = thresholds.auto_generate;
+        }
+        if (typeof thresholds.prompt_user === 'boolean') {
+          promptUser = thresholds.prompt_user;
+        }
+      } else if (mode === 'full') {
+        commitThreshold = 10;
+        daysThreshold = 5;
+      }
+    }
+  } catch {
+    /* keep defaults */
+  }
+}
+
+if (mode === 'off') {
+  autoGenerate = false;
+  promptUser = false;
+}
+
+const config = {
+  mode,
+  commitThreshold,
+  daysThreshold,
+  autoGenerate,
+  promptUser,
+};
+
+if (process.argv.includes('--json')) {
+  console.log(JSON.stringify(config));
+  process.exit(0);
+}
+
+console.log(`MODE=${mode}`);
+console.log(`COMMIT_THRESHOLD=${commitThreshold}`);
+console.log(`DAYS_THRESHOLD=${daysThreshold}`);
+console.log(`AUTO_GENERATE=${autoGenerate}`);
+console.log(`PROMPT_USER=${promptUser}`);