qualia-framework 6.1.0 → 6.2.9

package/hooks/pre-deploy-gate.js

@@ -8,14 +8,51 @@
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
 const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+
+// Self-filter on the proposed bash command — only act when the user is
+// actually trying to deploy. Claude Code's `if: "Bash(vercel --prod*)"` does
+// substring matching (not glob), so commands that contain the literal text
+// "vercel --prod" inside a for-loop or grep argument trip the gate. Codex
+// ignores the `if` field entirely. Both runtimes therefore need this hook to
+// inspect tool_input.command itself before doing any work.
+//
+// Direct invocation (no stdin — `node pre-deploy-gate.js`) is treated as
+// "run the gate" so the test suite and manual `qualia-framework verify` flows
+// keep working. Only when stdin contains a parseable tool_input.command that
+// does NOT match a deploy pattern do we exit early.
+(function selfFilter() {
+  if (process.stdin.isTTY) return; // direct invocation — run full gate
+  let command = null; // null = no stdin payload, "" = empty command, "str" = parsed
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw) {
+      const payload = JSON.parse(raw);
+      command = (payload && payload.tool_input && payload.tool_input.command) || "";
+    }
+  } catch {}
+  if (command === null) return; // malformed or empty stdin — run full gate
+  if (!/^\s*(npx\s+)?vercel\s+(--prod|deploy\s+--prod)\b/.test(command)) {
+    process.exit(0);
+  }
+})();
+
 function _trace(hookName, result, extra) {
   try {
     const os = require("os");
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: hookName,

package/hooks/pre-push.js

@@ -1,16 +1,26 @@
 #!/usr/bin/env node
-// ~/.claude/hooks/pre-push.js — stamp tracking.json + commit it before push.
-// PreToolUse hook on `git push*` commands. The stamp is included in the push
-// via a small bot commit (no-verify, bot author) so the ERP — which reads
-// tracking.json straight from git — sees fresh data on every push.
+// ~/.claude/hooks/pre-push.js — stamp .planning/tracking.json on push.
 //
-// Cross-platform (Windows/macOS/Linux). No external dependencies.
+// Stamps last_commit + last_pushed_at locally on every `git push`. Does NOT
+// commit, stage, or push tracking.json. The file is consumed by local readers
+// only:
+//   - bin/statusline.js          (renders last-push time)
+//   - hooks/stop-session-log.js  (renders session-stop banner)
+//   - /qualia-report skill       (reads stamps for the report payload)
+//   - bin/state.js               (state machine)
+//
+// History rationale (v6.2 — 2026-05-20): pre-v6.2 versions of this hook wrote
+// the stamp, `git add`-ed it, then created a bot commit (`chore(track): ERP
+// sync …`) so a downstream consumer — the ERP at portal.qualiasolutions.net —
+// could read tracking.json straight from GitHub. That consumer was documented
+// (docs/erp-contract.md) but never actually implemented; the ERP repo had no
+// route, cron, or worker that reads tracking.json. The bot commits were
+// polluting every Qualia project's history (and on auto-deploy-enabled Vercel
+// projects, triggering useless redeploys) for no benefit. v6.2 strips the
+// commit entirely — the stamps still happen, just locally.
 //
-// History rationale: a previous version (≤v3.4.1) wrote the stamp to
-// tracking.json and then `git add`-ed it, but the actual `git push` ran on
-// the snapshot already prepared by Claude Code's tool dispatcher — so the
-// stamp never made it onto the wire. This rewrite creates a real commit so
-// the next `git push` it spawned by Claude Code includes it.
+// PreToolUse hook on `git push*` commands. Never blocks the push.
+// Cross-platform (Windows/macOS/Linux). No external dependencies.
 
 const fs = require("fs");
 const path = require("path");
@@ -18,67 +28,39 @@ const os = require("os");
 const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
-const HOME = os.homedir();
-const TRACKING = path.join(".planning", "tracking.json");
-const CONFIG = path.join(HOME, ".claude", ".qualia-config.json");
-const BOT_AUTHOR = "Qualia Framework <bot@qualia.solutions>";
-const SHELL = process.platform === "win32";
 
-function git(args, opts = {}) {
-  return spawnSync("git", args, {
-    encoding: "utf8",
-    timeout: 5000,
-    shell: SHELL,
-    ...opts,
-  });
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
 }
 
-// Self-gate against branch-guard: PreToolUse hooks run in parallel, so this
-// hook MUST mirror branch-guard's block logic before creating a side-effect
-// commit. Otherwise: branch-guard exits 2 (push blocked), we already wrote a
-// bot commit that's now orphaned in the local branch. Next push (to a feature
-// branch) silently ships the orphan. v5.9.2 fix.
-function wouldBeBlocked() {
-  let role = "";
-  try {
-    const cfg = JSON.parse(fs.readFileSync(CONFIG, "utf8"));
-    role = cfg.role || "";
-  } catch {
-    return false; // branch-guard will fail-closed on its own
-  }
-  if (role === "OWNER") return false;
+const QUALIA_HOME = qualiaHome();
+const TRACKING = path.join(".planning", "tracking.json");
+const SHELL = process.platform === "win32";
 
-  // Mirror branch-guard's stdin parse for refspec targets.
-  let pushCommand = "";
+// Self-filter — only stamp on actual `git push`. Claude's `if` matcher does
+// substring matching (so unrelated commands with "git push" as a literal
+// argument trip the hook) and Codex ignores the `if` field entirely. Direct
+// invocation (no stdin) falls through to the legacy behavior so tests and
+// manual runs still stamp tracking.json.
+(function selfFilter() {
+  if (process.stdin.isTTY) return;
+  let command = null;
   try {
     const raw = fs.readFileSync(0, "utf8");
-    if (raw && raw.trim()) {
+    if (raw) {
       const payload = JSON.parse(raw);
-      pushCommand = (payload && payload.tool_input && payload.tool_input.command) || "";
-    }
-  } catch { /* no stdin */ }
-
-  if (pushCommand) {
-    const tokens = pushCommand.split(/\s+/).filter(Boolean);
-    const pushIdx = tokens.indexOf("push");
-    if (pushIdx !== -1) {
-      for (let i = pushIdx + 1; i < tokens.length; i++) {
-        let tok = tokens[i];
-        if (tok.startsWith("-")) continue;
-        if (tok.startsWith("+")) tok = tok.slice(1);
-        tok = tok.replace(/^['"]|['"]$/g, "");
-        if (tok.includes(":")) {
-          const dst = tok.split(":").pop().replace(/^refs\/heads\//, "");
-          if (dst === "main" || dst === "master") return true;
-        }
-      }
+      command = (payload && payload.tool_input && payload.tool_input.command) || "";
     }
-  }
+  } catch {}
+  if (command === null) return;
+  if (!/^\s*git\s+push\b/.test(command)) process.exit(0);
+})();
 
-  // Current-branch fallback.
-  const r = git(["branch", "--show-current"], { stdio: ["ignore", "pipe", "ignore"] });
-  const branch = ((r.stdout || "").trim());
-  return branch === "main" || branch === "master";
+function git(args) {
+  return spawnSync("git", args, { encoding: "utf8", timeout: 5000, shell: SHELL });
 }
 
 function atomicWrite(file, content) {
@@ -87,91 +69,31 @@ function atomicWrite(file, content) {
   fs.renameSync(tmp, file);
 }
 
-function inGitRepo() {
-  const r = git(["rev-parse", "--is-inside-work-tree"], { stdio: ["ignore", "pipe", "ignore"] });
-  return r.status === 0 && (r.stdout || "").trim() === "true";
-}
-
-function commitStamp() {
+function stampLocal() {
   if (!fs.existsSync(TRACKING)) return { skipped: "no-tracking-file" };
-  if (!inGitRepo()) return { skipped: "not-a-git-repo" };
 
-  // Read current commit + stamp
-  const head = git(["log", "--oneline", "-1", "--format=%h"]);
-  const lastCommit = ((head.stdout || "").trim());
-  const now = new Date().toISOString().replace(/\.\d+Z$/, "Z");
-
-  // Mutate tracking.json (atomic). Tolerate CRLF on Windows-edited files.
-  let raw, parsed;
+  let parsed;
   try {
-    raw = fs.readFileSync(TRACKING, "utf8");
-    parsed = JSON.parse(raw);
+    parsed = JSON.parse(fs.readFileSync(TRACKING, "utf8"));
   } catch (err) {
     return { skipped: "tracking-unreadable", error: err.message };
   }
 
-  const before = JSON.stringify({ last_commit: parsed.last_commit, last_updated: parsed.last_updated });
+  const head = git(["log", "--oneline", "-1", "--format=%h"]);
+  const lastCommit = (head.stdout || "").trim();
+  const now = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
   if (lastCommit) parsed.last_commit = lastCommit;
   parsed.last_updated = now;
   parsed.last_pushed_at = now;
-  const after = JSON.stringify({ last_commit: parsed.last_commit, last_updated: parsed.last_updated });
-  if (before === after) return { skipped: "no-change" };
 
   atomicWrite(TRACKING, JSON.stringify(parsed, null, 2) + "\n");
-
-  // Commit so the stamp is part of the push that's about to happen.
-  // --no-verify: skip user pre-commit hooks (this is a bot commit).
-  // --no-gpg-sign: don't pop a signing prompt for a chore commit.
-  // --author: attribute to bot, not user.
-  // -c core.autocrlf=false: without this, Windows installs with autocrlf=true
-  // normalize the just-written LF-terminated JSON to CRLF in the index, so the
-  // diff against HEAD is empty, the commit fails, and we roll back the stamp.
-  // Forcing autocrlf=false for this one add/commit pair preserves the JSON as
-  // written and keeps the stamp consistent across platforms.
-  const add = git(["-c", "core.autocrlf=false", "add", TRACKING]);
-  if (add.status !== 0) return { skipped: "git-add-failed", error: add.stderr };
-
-  const commit = git([
-    "-c", "core.autocrlf=false",
-    "commit",
-    "--no-verify",
-    "--no-gpg-sign",
-    "--author", BOT_AUTHOR,
-    "-m", `chore(track): ERP sync ${now}`,
-  ]);
-  if (commit.status !== 0) {
-    // Commit failed (e.g., empty diff because git's auto-CRLF normalized the
-    // only change to nothing, or branch is in a detached/conflicted state).
-    // Unstage tracking.json and restore the working tree copy so the user's
-    // next manual commit isn't polluted by our aborted stamp.
-    try { git(["reset", "HEAD", "--", TRACKING]); } catch {}
-    try { if (raw != null) atomicWrite(TRACKING, raw); } catch {}
-    return { skipped: "git-commit-failed", error: (commit.stderr || commit.stdout || "").trim() };
-  }
-  return { committed: true, sha: lastCommit, ts: now };
-}
-
-function shouldBlock(result) {
-  // v5.0: tracking.json sync failures are now WARN not BLOCK. Rationale:
-  // tracking.json is ERP metadata, not load-bearing for the push itself. A
-  // corrupt tracking.json should NEVER prevent a production hotfix. The
-  // self-service fix is `git checkout HEAD -- .planning/tracking.json` and
-  // gets surfaced in the warning message below.
-  // To restore old fail-closed behavior set QUALIA_BLOCK_ON_TRACKING_FAIL=1.
-  if (process.env.QUALIA_BLOCK_ON_TRACKING_FAIL === "1") {
-    const hardSkips = new Set([
-      "tracking-unreadable",
-      "git-add-failed",
-      "git-commit-failed",
-    ]);
-    return result && hardSkips.has(result.skipped);
-  }
-  return false;
+  return { stamped: true, sha: lastCommit, ts: now };
 }
 
 function _trace(result, extra) {
   try {
-    const traceDir = path.join(HOME, ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: "pre-push",
@@ -186,34 +108,11 @@ function _trace(result, extra) {
 }
 
 try {
-  // Defer to branch-guard: if the push will be blocked, don't create the
-  // bot commit. branch-guard runs in parallel and will exit 2 with the
-  // user-facing block message.
-  if (wouldBeBlocked()) {
-    _trace("skip", { reason: "would-be-blocked-by-branch-guard" });
-    process.exit(0);
-  }
-
-  const result = commitStamp();
-  if (shouldBlock(result)) {
-    const detail = result.error ? ` ${String(result.error).slice(0, 500)}` : "";
-    const msg = `BLOCKED: tracking.json sync failed (${result.skipped}). Fix before pushing.${detail}\nSelf-service fix: git checkout HEAD -- .planning/tracking.json`;
-    console.error(msg);
-    console.log(msg);
-    _trace("block", result);
-    process.exit(2);
-  }
-  // v5.0: warn-not-block on tracking.json failures. The push proceeds; the user
-  // sees a clear message and a self-service fix path. Production hotfixes are
-  // never blocked by ERP-metadata corruption.
-  if (result && (result.skipped === "tracking-unreadable" || result.skipped === "git-add-failed" || result.skipped === "git-commit-failed")) {
-    const detail = result.error ? ` (${String(result.error).slice(0, 200)})` : "";
-    console.error(`⚠ tracking.json sync failed: ${result.skipped}${detail}. Push proceeding. Self-service fix: git checkout HEAD -- .planning/tracking.json`);
-  }
+  const result = stampLocal();
   _trace("allow", result);
 } catch (err) {
-  // Exception during commit stamping — warn, don't block (same v5.0 rationale).
-  console.error(`⚠ tracking.json sync threw: ${err.message}. Push proceeding. Self-service fix: git checkout HEAD -- .planning/tracking.json`);
+  // Never block a push on a stamp failure — tracking.json is local telemetry.
+  console.error(`⚠ tracking.json stamp failed: ${err.message}. Push proceeding.`);
   _trace("warn", { error: err.message });
 }
 

package/hooks/session-start.js

@@ -21,24 +21,32 @@ const DIM = "\x1b[38;2;80;90;100m";
 const RESET = "\x1b[0m";
 
 const HOME = os.homedir();
-const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(HOME, ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const UI = path.join(QUALIA_HOME, "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
-const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
-const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
-const ERP_RETRY = path.join(HOME, ".claude", "bin", "erp-retry.js");
-const ERP_QUEUE = path.join(HOME, ".claude", ".erp-retry-queue.json");
+const NOTIF_FILE = path.join(QUALIA_HOME, ".qualia-update-available.json");
+const HEALTH_FILE = path.join(QUALIA_HOME, ".qualia-install-health.json");
+const ERP_RETRY = path.join(QUALIA_HOME, "bin", "erp-retry.js");
+const ERP_QUEUE = path.join(QUALIA_HOME, ".erp-retry-queue.json");
 
 // Critical files referenced by skills via @-import. If any are missing, skills
 // silently get empty context and produce ungrounded output. We spot-check these
 // on session-start and write a cached result (1-per-day) to HEALTH_FILE so we
 // don't stat on every session.
 const CRITICAL_FILES = [
-  path.join(HOME, ".claude", "rules", "grounding.md"),
-  path.join(HOME, ".claude", "rules", "security.md"),
-  path.join(HOME, ".claude", "rules", "deployment.md"),
-  path.join(HOME, ".claude", "qualia-design", "frontend.md"),
-  path.join(HOME, ".claude", "bin", "state.js"),
+  path.join(QUALIA_HOME, "rules", "grounding.md"),
+  path.join(QUALIA_HOME, "rules", "security.md"),
+  path.join(QUALIA_HOME, "rules", "deployment.md"),
+  path.join(QUALIA_HOME, "qualia-design", "frontend.md"),
+  path.join(QUALIA_HOME, "bin", "state.js"),
 ];
 
 function checkInstallHealth() {
@@ -74,7 +82,7 @@ function runUi(...args) {
 }
 
 function getNextCommand() {
-  const stateJs = path.join(HOME, ".claude", "bin", "state.js");
+  const stateJs = path.join(QUALIA_HOME, "bin", "state.js");
   if (!fs.existsSync(stateJs)) return "";
   try {
     const r = spawnSync(process.execPath, [stateJs, "check"], {
@@ -91,7 +99,7 @@ function getNextCommand() {
 
 function readConfig() {
   try {
-    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+    return JSON.parse(fs.readFileSync(path.join(QUALIA_HOME, ".qualia-config.json"), "utf8"));
   } catch {
     return {};
   }
@@ -198,7 +206,7 @@ try {
   // Hook must never exit non-zero. Log to trace so silent crashes are visible
   // in analytics, but do not print to stderr (would clutter the banner).
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
     fs.appendFileSync(
@@ -215,7 +223,7 @@ try {
 
 function _trace(hookName, result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: hookName,

package/hooks/stop-session-log.js

@@ -31,14 +31,22 @@ const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
-const KNOWLEDGE_DIR = path.join(os.homedir(), ".claude", "knowledge");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const KNOWLEDGE_DIR = path.join(QUALIA_HOME, "knowledge");
 const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
-const LAST_WRITE_FILE = path.join(os.homedir(), ".claude", ".qualia-last-session-log");
+const LAST_WRITE_FILE = path.join(QUALIA_HOME, ".qualia-last-session-log");
 const MIN_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 
 function _trace(result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     fs.appendFileSync(
       path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`),

package/hooks/supabase-destructive-guard.js

@@ -11,9 +11,19 @@ const path = require("path");
 const os = require("os");
 
 const _traceStart = Date.now();
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+
 function _trace(result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: "supabase-destructive-guard", result,

package/hooks/vercel-account-guard.js

@@ -17,9 +17,18 @@ const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+
 function _trace(result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: "vercel-account-guard",
@@ -54,7 +63,7 @@ if (!/vercel\s+(--prod|deploy)/.test(command)) {
 }
 
 // Read allowed teams (one slug per line).
-const teamsFile = path.join(os.homedir(), ".claude", ".vercel-allowed-teams");
+const teamsFile = path.join(QUALIA_HOME, ".vercel-allowed-teams");
 let allowed;
 try {
   allowed = fs.readFileSync(teamsFile, "utf8").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
@@ -84,7 +93,7 @@ if (allowed.includes(actual)) {
 }
 
 // Block: wrong account.
-const msg = `BLOCKED: Wrong Vercel account/team. Active: '${actual}'. Allowed: ${allowed.join(", ")}. Run \`vercel switch ${allowed[0]}\` first, or add this team to ~/.claude/.vercel-allowed-teams.`;
+const msg = `BLOCKED: Wrong Vercel account/team. Active: '${actual}'. Allowed: ${allowed.join(", ")}. Run \`vercel switch ${allowed[0]}\` first, or add this team to ${path.join(QUALIA_HOME, ".vercel-allowed-teams")}.`;
 console.error(msg);
 console.log(msg);
 _trace("block", { actual, allowed_count: allowed.length, reason: "wrong-account" });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qualia-framework",
-  "version": "6.1.0",
-  "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
+  "version": "6.2.9",
+  "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
   },
@@ -32,6 +32,7 @@
     "test:slop-detect": "bash tests/slop-detect.test.sh",
     "test:statusline": "bash tests/statusline.test.sh",
     "test:refs": "bash tests/refs.test.sh",
+    "test:published-install": "bash tests/published-install-smoke.test.sh",
     "test:shell": "bash tests/run-all.sh"
   },
   "files": [

package/rules/codex-goal.md

@@ -0,0 +1,46 @@
+# Codex /goal integration
+
+When this skill spawns a unit of work on **Codex** (not Claude Code), set the thread goal at the start so Codex's native token-budget + status tracking takes over.
+
+## Runtime detection
+
+You are on Codex when `~/.codex/` exists and `~/.claude/` is absent or stale. The simplest probe:
+
+```bash
+test -f ~/.codex/AGENTS.md && echo codex || echo claude
+```
+
+If the answer is `claude`, **skip this entire rule** — Claude Code has no equivalent surface and emitting `/goal` text would just be noise.
+
+## How to set the goal
+
+1. Run the helper to produce the objective string + suggested token budget:
+
+   ```bash
+   node ~/.codex/bin/codex-goal.js {scope}
+   ```
+
+   `{scope}` is one of: `phase` · `task` · `feature` · `quick`. Use the scope of the current skill.
+
+2. The output is two lines:
+
+   ```
+   /goal {objective text from STATE.md + ROADMAP.md}
+   # token_budget suggestion: {N}
+   ```
+
+3. **If the `update_goal` tool is available** to you (Codex exposes it as a model-callable tool), call it directly with:
+   - `objective` = the text after `/goal ` on line 1
+   - `token_budget` = the integer suggestion on line 2
+
+4. **If `update_goal` is not available**, surface the `/goal` line to the user in your next message and let them paste it. Do not silently skip — the goal-set takes 1 second and is the only way Codex's budget telemetry knows what to track.
+
+## When NOT to set a goal
+
+- The user is on Claude Code (no `/goal` surface).
+- A goal is already active for this thread (Codex rejects `update_goal` when one exists — call `thread/goal/get` first if you're using the tool API directly).
+- The work is open-ended exploration with no clear objective (e.g. `/qualia-idk`, `/qualia-discuss`). Goals are for executing a defined scope.
+
+## Why
+
+Codex's `thread_goals` table tracks `objective`, `token_budget`, `tokens_used`, and a `status` enum (`active | paused | blocked | usage_limited | budget_limited | complete`). Setting the goal lets the user see burn-vs-budget in the TUI without the framework reinventing it. The token-budget number also makes the model self-aware of how much context it has left for the current unit of work.

package/skills/qualia-build/SKILL.md

@@ -24,6 +24,10 @@ Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal at phase start with scope `phase`.
+
 ### 1. Load Plan
 
 ```bash

package/skills/qualia-feature/SKILL.md

@@ -39,6 +39,10 @@ One command for everything between a typo and a phase. Auto-detects scope from t
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal with scope matching the auto-detected bucket (`quick` for inline, `feature` for spawn). Do this AFTER Step 2 (auto-detect scope) so the budget matches the actual work shape.
+
 ### 1. Capture description
 
 If invoked without args, ask: **"What do you want to build?"**

package/skills/qualia-map/SKILL.md

@@ -163,7 +163,7 @@ Read `.planning/codebase/onboarding.md`. Per detected dimension:
 - Domain docs at non-default path → `.planning/agents/domain.md`
 - CLAUDE.md/AGENTS.md found → APPEND `## Qualia substrate` (never overwrite)
 
-"none" → skip silently, defaults apply.
+"none" → report that no preference was provided; defaults apply.
 
 ### 6. Commit
 

package/skills/qualia-milestone/SKILL.md

@@ -276,6 +276,6 @@ node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1
 2. **JOURNEY.md is the source of truth for next milestone.** Don't ask the user to name it unless JOURNEY.md is missing (legacy project).
 3. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
 4. **New milestone = fresh phase numbering.** First phase of the new milestone is Phase 1, not Phase {N+1}.
-5. **ERP sync aware.** tracking.json milestones[] gets a summary entry on close — the ERP reads this to render the tree.
+5. **Report aware.** `tracking.json.milestones[]` gets a summary entry on close so local status and `/qualia-report` have milestone context.
 6. **Handoff is the final milestone (full projects).** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
 7. **Demo closes via the demo-extension branch (Step 1b).** A demo's single milestone closing triggers the "client signed?" question. The framework never silently auto-extends a demo without asking — the conversion is a real business decision.

package/skills/qualia-optimize/SKILL.md

@@ -41,7 +41,7 @@ Modes: `full`, `perf`, `ui`, `backend`, `alignment`, `deepen`, `fix`.
 
 ### Step 2: Load Planning Context (MANDATORY)
 
-Read all (skip silently if missing):
+Read all (use the shown NO_* marker when missing):
 
 ```bash
 cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"

package/skills/qualia-plan/SKILL.md

@@ -27,6 +27,10 @@ Spawn planner to break phase into tasks, validate with checker (max 2 revision c
 
 ## Process
 
+### 0. Codex goal (Codex runtime only)
+
+Per `rules/codex-goal.md` — set the thread goal at plan start with scope `phase`. The objective covers both planning and the subsequent build, so a single goal-set at this stage is enough.
+
 ### 1. Determine Phase & Load Context
 
 ```bash

package/skills/qualia-polish/SKILL.md

@@ -97,7 +97,7 @@ node bin/slop-detect.mjs {target_paths}
 npx tsc --noEmit 2>&1 | head -20
 
 # Token enforcement (if Stylelint configured)
-npx stylelint "src/**/*.css" 2>&1 | head -20  # optional, skip silently if not configured
+npx stylelint "src/**/*.css" 2>&1 | head -20  # optional, report if not configured
 ```
 
 ANY critical-severity slop hit = mandatory fix before proceeding. Don't stage anything until critical findings are zero.
@@ -150,7 +150,7 @@ npx lhci autorun \
 npx @axe-core/cli http://localhost:3000{route} --exit 2>&1 | tail -30
 ```
 
-If Lighthouse/axe not installed, skip silently and note in the report. Don't fail the polish over missing tooling.
+If Lighthouse/axe are not installed, continue but note the missing tooling in the report. Don't fail the polish over optional local tooling, and don't hide the skipped gate.
 
 If a11y < 90 OR axe critical/serious violations: **fix programmatically** (these are deterministic — no vision needed). Re-run to confirm.