oh-my-customcodex 0.5.1 → 0.5.2

package/README.md

@@ -228,7 +228,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (48)
+### Guides (50)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -288,7 +288,7 @@ your-project/
 │   └── ontology/               # Knowledge graph for RAG
 ├── .agents/
 │   └── skills/                 # 123 installed skill modules
-└── guides/                     # 48 reference documents
+└── guides/                     # 50 reference documents
 ```
 
 ### Source Repository And Compatibility Surfaces

package/dist/cli/index.js

@@ -3091,7 +3091,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.5.1",
+    version: "0.5.2",
     requiresCC: ">=2.1.121",
     claudeCode: {
       minimumVersion: "2.1.121",
@@ -26977,6 +26977,7 @@ init_lockfile();
 init_logger();
 import { execSync as execSync4 } from "node:child_process";
 import { platform as platform2 } from "node:os";
+var MINIMUM_OMX_VERSION = "0.18.0";
 var defaultDeps2 = {
   exec: execSync4,
   getPlatform: platform2
@@ -27000,11 +27001,116 @@ function getOmxVersion(deps = defaultDeps2) {
     return null;
   }
 }
+function parseOmxVersion(versionOutput) {
+  if (!versionOutput) {
+    return null;
+  }
+  const match = versionOutput.match(/\bv?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/);
+  return match ? match[1] : null;
+}
+function parseVersionParts(version) {
+  const [withoutBuild] = version.split("+");
+  const [coreText, prerelease = null] = withoutBuild.split("-", 2);
+  const coreParts = coreText.split(".").map((part) => Number.parseInt(part, 10));
+  return {
+    core: [coreParts[0] ?? 0, coreParts[1] ?? 0, coreParts[2] ?? 0],
+    prerelease
+  };
+}
+function compareOmxVersions(left, right) {
+  const a = parseVersionParts(left);
+  const b = parseVersionParts(right);
+  for (let index = 0;index < 3; index += 1) {
+    const diff = a.core[index] - b.core[index];
+    if (diff !== 0) {
+      return diff > 0 ? 1 : -1;
+    }
+  }
+  if (a.prerelease === b.prerelease) {
+    return 0;
+  }
+  if (a.prerelease === null) {
+    return 1;
+  }
+  if (b.prerelease === null) {
+    return -1;
+  }
+  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+}
+function hasOmxApiCommand(deps = defaultDeps2) {
+  try {
+    deps.exec("omx api --help", {
+      encoding: "utf-8",
+      stdio: "pipe",
+      timeout: 3000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assessOmxInstallation(deps = defaultDeps2) {
+  if (!isOmxInstalled(deps)) {
+    return {
+      status: "missing",
+      installed: false,
+      version: null,
+      parsedVersion: null,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  const version = getOmxVersion(deps);
+  const parsedVersion = parseOmxVersion(version);
+  if (parsedVersion && compareOmxVersions(parsedVersion, MINIMUM_OMX_VERSION) < 0) {
+    return {
+      status: "stale",
+      installed: true,
+      version,
+      parsedVersion,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  const hasApi = hasOmxApiCommand(deps);
+  if (parsedVersion && !hasApi) {
+    return {
+      status: "api-missing",
+      installed: true,
+      version,
+      parsedVersion,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  if (!parsedVersion && !hasApi) {
+    return {
+      status: "unknown-version",
+      installed: true,
+      version,
+      parsedVersion: null,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  return {
+    status: "ready",
+    installed: true,
+    version,
+    parsedVersion,
+    minimumVersion: MINIMUM_OMX_VERSION,
+    hasApiCommand: hasApi
+  };
+}
+function isOmxReady(deps = defaultDeps2) {
+  return assessOmxInstallation(deps).status === "ready";
+}
 function installOmx(deps = defaultDeps2) {
   if (process.env.CI || false || false) {
     return false;
   }
-  if (isOmxInstalled(deps)) {
+  const current = assessOmxInstallation(deps);
+  if (current.status === "ready") {
     info("install.omx_already");
     return true;
   }
@@ -27015,11 +27121,11 @@ function installOmx(deps = defaultDeps2) {
   }
   try {
     info("install.omx_installing");
-    deps.exec("npm install -g oh-my-codex", {
+    deps.exec("npm install -g oh-my-codex@latest", {
       stdio: "inherit",
       timeout: 120000
     });
-    return isOmxInstalled(deps);
+    return isOmxReady(deps);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     warn("install.omx_install_failed", { error: message });
@@ -27428,7 +27534,8 @@ async function checkCodex() {
   };
 }
 async function checkOmx() {
-  if (!isOmxInstalled()) {
+  const omx = assessOmxInstallation();
+  if (omx.status === "missing") {
     return {
       name: "OMX",
       status: "warn",
@@ -27436,11 +27543,34 @@ async function checkOmx() {
       fixable: true
     };
   }
-  const version = getOmxVersion();
+  if (omx.status === "stale") {
+    return {
+      name: "OMX",
+      status: "warn",
+      message: `OMX stale (${omx.version ?? "unknown version"}) — requires oh-my-codex v${MINIMUM_OMX_VERSION}+ with omx api`,
+      fixable: true
+    };
+  }
+  if (omx.status === "api-missing") {
+    return {
+      name: "OMX",
+      status: "warn",
+      message: `OMX missing required omx api command (${omx.version ?? "unknown version"}) — install oh-my-codex v${MINIMUM_OMX_VERSION}+`,
+      fixable: true
+    };
+  }
+  if (omx.status === "unknown-version") {
+    return {
+      name: "OMX",
+      status: "warn",
+      message: `OMX version could not be verified — requires oh-my-codex v${MINIMUM_OMX_VERSION}+ with omx api`,
+      fixable: true
+    };
+  }
   return {
     name: "OMX",
     status: "pass",
-    message: `OMX OK (${version ?? "unknown version"})`,
+    message: `OMX OK (${omx.version ?? "unknown version"}, omx api available)`,
     fixable: false
   };
 }
@@ -27557,7 +27687,7 @@ async function fixSingleIssue(check, targetDir, rootDir = ".codex") {
 async function fixIssues(checks, targetDir, rootDir = ".codex") {
   const fixedChecks = [];
   for (const check of checks) {
-    if (check.status !== "fail" || !check.fixable) {
+    if (check.status === "pass" || !check.fixable) {
       fixedChecks.push(check);
       continue;
     }
@@ -27717,7 +27847,7 @@ async function doctorCommand(options = {}) {
   const checksWithUpdate = await runAllChecks(targetDir, layout, packageVersion, options.updates ?? false);
   let checks = checksWithUpdate;
   if (options.fix) {
-    const hasFixableIssues = checksWithUpdate.some((c) => c.status === "fail" && c.fixable);
+    const hasFixableIssues = checksWithUpdate.some((c) => c.status !== "pass" && c.fixable);
     if (hasFixableIssues) {
       console.log(i18n.t("cli.doctor.applyingFixes"));
       console.log("");
@@ -28306,6 +28436,22 @@ async function installStatusline(targetDir, options, _result) {
   await fs2.chmod(destPath, 493);
   debug("install.statusline_installed", {});
 }
+async function installTestsConfig(targetDir, options, _result) {
+  const srcPath = resolveTemplatePath(join7("tests", "tsconfig.json"));
+  const destPath = join7(targetDir, "tests", "tsconfig.json");
+  if (!await fileExists(srcPath)) {
+    debug("install.tests_config_not_found", { path: srcPath });
+    return;
+  }
+  if (await fileExists(destPath)) {
+    if (!options.force && !options.backup) {
+      debug("install.tests_config_skipped", { reason: "exists" });
+      return;
+    }
+  }
+  await copyFile(srcPath, destPath);
+  debug("install.tests_config_installed", {});
+}
 async function installSettingsLocal(targetDir, result) {
   const layout = getProviderLayout();
   const settingsPath = join7(targetDir, layout.rootDir, "settings.local.json");
@@ -28382,13 +28528,15 @@ function installCodexIfNeeded(result) {
   }
 }
 function installOmxIfNeeded(result) {
-  if (!isOmxInstalled()) {
+  const omx = assessOmxInstallation();
+  if (omx.status !== "ready") {
     info("install.omx_installing");
     const omxInstalled = installOmx();
     if (omxInstalled) {
       info("install.omx_success");
     } else {
-      result.warnings.push("OMX installation failed — install manually: npm install -g oh-my-codex");
+      const versionDetail = omx.version ? ` (found ${omx.version})` : "";
+      result.warnings.push(`OMX installation/upgrade failed${versionDetail} — install oh-my-codex >= v${MINIMUM_OMX_VERSION} manually: npm install -g oh-my-codex@latest`);
     }
   } else {
     info("install.omx_already");
@@ -28404,6 +28552,7 @@ async function install(options) {
     await verifyTemplateDirectory();
     await installAllComponents(options.targetDir, options, result);
     await installStatusline(options.targetDir, options, result);
+    await installTestsConfig(options.targetDir, options, result);
     await installSettingsLocal(options.targetDir, result);
     await installEntryDocWithTracking(options.targetDir, options, result);
     if (preservation) {
@@ -31529,9 +31678,15 @@ function checkAndInstallCodexAfterUpdate() {
   }
 }
 function checkAndInstallOmxAfterUpdate() {
-  if (!isOmxInstalled()) {
+  const omx = assessOmxInstallation();
+  if (omx.status !== "ready") {
     warn("update.omx_missing");
-    console.log(i18n.t("cli.update.omxMissing"));
+    if (omx.status === "missing") {
+      console.log(i18n.t("cli.update.omxMissing"));
+    } else {
+      const versionDetail = omx.version ? ` (${omx.version})` : "";
+      console.log(`OMX${versionDetail} does not meet the oh-my-codex v${MINIMUM_OMX_VERSION} baseline. Attempting upgrade...`);
+    }
     const omxInstalled = installOmx();
     if (omxInstalled) {
       console.log(i18n.t("cli.update.omxInstalled"));

package/dist/index.js

@@ -1569,6 +1569,7 @@ init_lockfile();
 init_logger();
 import { execSync as execSync2 } from "node:child_process";
 import { platform as platform2 } from "node:os";
+var MINIMUM_OMX_VERSION = "0.18.0";
 var defaultDeps2 = {
   exec: execSync2,
   getPlatform: platform2
@@ -1581,11 +1582,127 @@ function isOmxInstalled(deps = defaultDeps2) {
     return false;
   }
 }
+function getOmxVersion(deps = defaultDeps2) {
+  try {
+    return deps.exec("omx --version", {
+      encoding: "utf-8",
+      stdio: "pipe",
+      timeout: 3000
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function parseOmxVersion(versionOutput) {
+  if (!versionOutput) {
+    return null;
+  }
+  const match = versionOutput.match(/\bv?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/);
+  return match ? match[1] : null;
+}
+function parseVersionParts(version) {
+  const [withoutBuild] = version.split("+");
+  const [coreText, prerelease = null] = withoutBuild.split("-", 2);
+  const coreParts = coreText.split(".").map((part) => Number.parseInt(part, 10));
+  return {
+    core: [coreParts[0] ?? 0, coreParts[1] ?? 0, coreParts[2] ?? 0],
+    prerelease
+  };
+}
+function compareOmxVersions(left, right) {
+  const a = parseVersionParts(left);
+  const b = parseVersionParts(right);
+  for (let index = 0;index < 3; index += 1) {
+    const diff = a.core[index] - b.core[index];
+    if (diff !== 0) {
+      return diff > 0 ? 1 : -1;
+    }
+  }
+  if (a.prerelease === b.prerelease) {
+    return 0;
+  }
+  if (a.prerelease === null) {
+    return 1;
+  }
+  if (b.prerelease === null) {
+    return -1;
+  }
+  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+}
+function hasOmxApiCommand(deps = defaultDeps2) {
+  try {
+    deps.exec("omx api --help", {
+      encoding: "utf-8",
+      stdio: "pipe",
+      timeout: 3000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assessOmxInstallation(deps = defaultDeps2) {
+  if (!isOmxInstalled(deps)) {
+    return {
+      status: "missing",
+      installed: false,
+      version: null,
+      parsedVersion: null,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  const version = getOmxVersion(deps);
+  const parsedVersion = parseOmxVersion(version);
+  if (parsedVersion && compareOmxVersions(parsedVersion, MINIMUM_OMX_VERSION) < 0) {
+    return {
+      status: "stale",
+      installed: true,
+      version,
+      parsedVersion,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  const hasApi = hasOmxApiCommand(deps);
+  if (parsedVersion && !hasApi) {
+    return {
+      status: "api-missing",
+      installed: true,
+      version,
+      parsedVersion,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  if (!parsedVersion && !hasApi) {
+    return {
+      status: "unknown-version",
+      installed: true,
+      version,
+      parsedVersion: null,
+      minimumVersion: MINIMUM_OMX_VERSION,
+      hasApiCommand: false
+    };
+  }
+  return {
+    status: "ready",
+    installed: true,
+    version,
+    parsedVersion,
+    minimumVersion: MINIMUM_OMX_VERSION,
+    hasApiCommand: hasApi
+  };
+}
+function isOmxReady(deps = defaultDeps2) {
+  return assessOmxInstallation(deps).status === "ready";
+}
 function installOmx(deps = defaultDeps2) {
   if (process.env.CI || false || false) {
     return false;
   }
-  if (isOmxInstalled(deps)) {
+  const current = assessOmxInstallation(deps);
+  if (current.status === "ready") {
     info("install.omx_already");
     return true;
   }
@@ -1596,11 +1713,11 @@ function installOmx(deps = defaultDeps2) {
   }
   try {
     info("install.omx_installing");
-    deps.exec("npm install -g oh-my-codex", {
+    deps.exec("npm install -g oh-my-codex@latest", {
       stdio: "inherit",
       timeout: 120000
     });
-    return isOmxInstalled(deps);
+    return isOmxReady(deps);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     warn("install.omx_install_failed", { error: message });
@@ -1796,6 +1913,22 @@ async function installStatusline(targetDir, options, _result) {
   await fs.chmod(destPath, 493);
   debug("install.statusline_installed", {});
 }
+async function installTestsConfig(targetDir, options, _result) {
+  const srcPath = resolveTemplatePath(join5("tests", "tsconfig.json"));
+  const destPath = join5(targetDir, "tests", "tsconfig.json");
+  if (!await fileExists(srcPath)) {
+    debug("install.tests_config_not_found", { path: srcPath });
+    return;
+  }
+  if (await fileExists(destPath)) {
+    if (!options.force && !options.backup) {
+      debug("install.tests_config_skipped", { reason: "exists" });
+      return;
+    }
+  }
+  await copyFile(srcPath, destPath);
+  debug("install.tests_config_installed", {});
+}
 async function installSettingsLocal(targetDir, result) {
   const layout = getProviderLayout();
   const settingsPath = join5(targetDir, layout.rootDir, "settings.local.json");
@@ -1872,13 +2005,15 @@ function installCodexIfNeeded(result) {
   }
 }
 function installOmxIfNeeded(result) {
-  if (!isOmxInstalled()) {
+  const omx = assessOmxInstallation();
+  if (omx.status !== "ready") {
     info("install.omx_installing");
     const omxInstalled = installOmx();
     if (omxInstalled) {
       info("install.omx_success");
     } else {
-      result.warnings.push("OMX installation failed — install manually: npm install -g oh-my-codex");
+      const versionDetail = omx.version ? ` (found ${omx.version})` : "";
+      result.warnings.push(`OMX installation/upgrade failed${versionDetail} — install oh-my-codex >= v${MINIMUM_OMX_VERSION} manually: npm install -g oh-my-codex@latest`);
     }
   } else {
     info("install.omx_already");
@@ -1894,6 +2029,7 @@ async function install(options) {
     await verifyTemplateDirectory();
     await installAllComponents(options.targetDir, options, result);
     await installStatusline(options.targetDir, options, result);
+    await installTestsConfig(options.targetDir, options, result);
     await installSettingsLocal(options.targetDir, result);
     await installEntryDocWithTracking(options.targetDir, options, result);
     if (preservation) {
@@ -2180,7 +2316,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.5.1",
+  version: "0.5.2",
   requiresCC: ">=2.1.121",
   claudeCode: {
     minimumVersion: "2.1.121",
@@ -5124,9 +5260,15 @@ function checkAndInstallCodexAfterUpdate() {
   }
 }
 function checkAndInstallOmxAfterUpdate() {
-  if (!isOmxInstalled()) {
+  const omx = assessOmxInstallation();
+  if (omx.status !== "ready") {
     warn("update.omx_missing");
-    console.log(i18n.t("cli.update.omxMissing"));
+    if (omx.status === "missing") {
+      console.log(i18n.t("cli.update.omxMissing"));
+    } else {
+      const versionDetail = omx.version ? ` (${omx.version})` : "";
+      console.log(`OMX${versionDetail} does not meet the oh-my-codex v${MINIMUM_OMX_VERSION} baseline. Attempting upgrade...`);
+    }
     const omxInstalled = installOmx();
     if (omxInstalled) {
       console.log(i18n.t("cli.update.omxInstalled"));

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.5.1",
+  "version": "0.5.2",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",

package/templates/.claude/agents/qa-engineer.md

@@ -31,6 +31,13 @@ You are a QA execution specialist that runs tests, identifies defects, and valid
 
 Jest, Vitest, pytest, go test, JUnit, Playwright, Cypress
 
+## Evidence Requirements
+
+- Before citing selectors, test IDs, CLI flags, mappings, function names, or config keys, read or grep the target code and quote the exact identifier.
+- Do not invent `data-testid`, route, mapping, or flag names from memory.
+- UI verification requires browser or screenshot evidence when a renderer is available; typecheck alone is not sufficient for visual completion.
+- If only indirect evidence is available, label it as indirect and state the missing direct check.
+
 ## Collaboration
 
 Receives from: qa-writer (test cases), qa-planner (priorities). Outputs to: dev-lead (defects), qa-writer (results).

package/templates/.claude/hooks/hooks.json

@@ -129,6 +129,10 @@
             "type": "command",
             "command": "bash .codex/hooks/scripts/agent-mode-guard.sh"
           },
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/agent-capability-precheck.sh"
+          },
           {
             "type": "command",
             "command": "#!/bin/bash\ninput=$(cat)\nagent_type=$(echo \"$input\" | jq -r '.tool_input.subagent_type // \"unknown\"')\nmodel=$(echo \"$input\" | jq -r '.tool_input.model // \"inherit\"')\ndesc=$(echo \"$input\" | jq -r '.tool_input.description // \"\"' | head -c 40)\nresume=$(echo \"$input\" | jq -r '.tool_input.resume // empty')\nif [ -n \"$resume\" ]; then\n  echo \"─── [Resume] ${agent_type}:${model} | ${desc} ───\" >&2\nelse\n  echo \"─── [Spawn] ${agent_type}:${model} | ${desc} ───\" >&2\nfi\necho \"$input\""
@@ -199,6 +203,16 @@
           }
         ],
         "description": "Auto-detect and fix previous session issues at start (#838)"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/plugin-cache-check.sh"
+          }
+        ],
+        "description": "Advisory check for plugin cache directories missing node_modules (#1366)"
       }
     ],
     "UserPromptSubmit": [
@@ -255,6 +269,10 @@
             "type": "command",
             "command": "bash .codex/hooks/scripts/auto-continue-guard.sh"
           },
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/session-reflection.sh"
+          },
           {
             "type": "prompt",
             "prompt": "A background subagent just completed. Check if there are pending workflow steps that depend on this result. If the previous subagent FAILED, do NOT auto-continue — report the failure and wait for user input. If the previous step succeeded and there are pending steps, proceed automatically. If no pending steps, report results and wait. Safety: The file /tmp/.codex-loop-count-$PPID tracks auto-continue count. After 3 consecutive auto-continues without user interaction, pause and ask the user before proceeding."
@@ -555,6 +573,16 @@
         ],
         "description": "Batch-save agent outcomes to eval-core DB on session end (advisory, exit 0)"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/session-reflection.sh"
+          }
+        ],
+        "description": "Capture session-end reflection from transcript, background_tasks, and session_crons (advisory, exit 0)"
+      },
       {
         "matcher": "*",
         "hooks": [