qualia-framework 6.1.0 → 6.2.7

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,20 @@ 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;
-
-  // Mirror branch-guard's stdin parse for refspec targets.
-  let pushCommand = "";
-  try {
-    const raw = fs.readFileSync(0, "utf8");
-    if (raw && raw.trim()) {
-      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;
-        }
-      }
-    }
-  }
+const QUALIA_HOME = qualiaHome();
+const TRACKING = path.join(".planning", "tracking.json");
+const SHELL = process.platform === "win32";
 
-  // 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 +50,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 +89,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.7",
+  "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/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-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.
 

package/skills/qualia-report/SKILL.md

@@ -126,7 +126,7 @@ fi
 ### Step 6 — Upload to ERP
 
 The full payload-builder + 3-attempt-retry logic lives unchanged from v4 — see the **ERP Upload** section below for the canonical implementation. Behavior summary:
-- ERP disabled in config → skip silently, note local commit
+- ERP disabled in config → skip upload with an info line, note local commit
 - API key missing → warn with self-service fix instructions, skip upload
 - 401/422 → permanent failure, no retry, tell employee to ask Fawzi
 - Transient (timeout/5xx) → 3 attempts with 1s/3s/9s backoff
@@ -149,7 +149,7 @@ node ~/.claude/bin/qualia-ui.js info "Shift report submitted. You can clock out
 | Symptom | Likely cause | Self-service fix |
 |---|---|---|
 | "Could not allocate report ID" | tracking.json missing/corrupt | `cat .planning/tracking.json` to inspect, or restore from `git checkout HEAD -- .planning/tracking.json` |
-| "ERP API key missing" | `~/.claude/.erp-api-key` empty | `qualia-framework set-erp-key <key>` (ask Fawzi for the key) |
+| "ERP API key missing" | `~/.claude/.erp-api-key` empty | `printf '%s' "$QUALIA_ERP_KEY" \| qualia-framework set-erp-key` (ask Fawzi for the key) |
 | "ERP auth failed (401)" | Key revoked or wrong | Ask Fawzi for a fresh key |
 | "ERP upload failed after 3 attempts" | ERP down or network issue | Local commit is safe. Re-run `/qualia-report` later. |
 | "git push failed" | Auth or network or upstream issue | `git push` manually, see the error, fix, re-run |
@@ -181,53 +181,16 @@ IDEMPOTENCY_KEY=$(node -e "
 
 # Guard: API key required for upload (otherwise curl posts an empty bearer)
 if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
-  node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: qualia-framework set-erp-key <key>"
+  node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: printf '%s' \"\$QUALIA_ERP_KEY\" | qualia-framework set-erp-key"
   ERP_ENABLED="false"
 fi
 
-# Build payload (env-var-passed user values to dodge shell escaping)
+# Build payload (env-var-passed user values to dodge shell escaping).
+# `report-payload.js` is the canonical, tested Framework -> ERP payload builder.
 PAYLOAD=$(
   SUBMITTED_BY="$SUBMITTED_BY" SUBMITTED_AT="$SUBMITTED_AT" \
   CLIENT_REPORT_ID="$CLIENT_REPORT_ID" REPORT_FILE="$REPORT_FILE" \
-  node -e "
-    const fs=require('fs'),path=require('path'),os=require('os');
-    const {spawnSync}=require('child_process');
-    const git=(a)=>{const r=spawnSync('git',a,{encoding:'utf8',timeout:3000});return r.status===0?r.stdout.trim():'';};
-    const repoSlug=(r)=>(r||'').replace(/^git@github\\.com:/,'github.com/').replace(/^https?:\\/\\//,'').replace(/\\.git$/,'').split('/').filter(Boolean).pop();
-    let config={};try{config=JSON.parse(fs.readFileSync(path.join(os.homedir(),'.claude/.qualia-config.json'),'utf8'));}catch{}
-    const t=JSON.parse(fs.readFileSync('.planning/tracking.json','utf8'));
-    const notes=fs.readFileSync(process.env.REPORT_FILE,'utf8').substring(0,60000);
-    const commits=[];try{const r=spawnSync('git',['log','--oneline','--since=8 hours ago','--format=%h'],{encoding:'utf8',timeout:3000});if(r.stdout)commits.push(...r.stdout.trim().split('\n').filter(Boolean));}catch{}
-    const gitRemote=t.git_remote||git(['config','--get','remote.origin.url']);
-    const projectKey=t.project_id||repoSlug(gitRemote)||require('path').basename(process.cwd());
-    // Session duration: minutes from session_started_at to submitted_at. The ERP's
-    // example payload (docs/erp-contract.md:93) includes this; without it the ERP
-    // can't compute shift-length analytics without parsing notes.
-    let sessionDurationMinutes=0;
-    if(t.session_started_at){
-      const startMs=Date.parse(t.session_started_at);
-      const endMs=Date.parse(process.env.SUBMITTED_AT)||Date.now();
-      if(!Number.isNaN(startMs)&&endMs>startMs){
-        sessionDurationMinutes=Math.round((endMs-startMs)/60000);
-      }
-    }
-    console.log(JSON.stringify({
-      project:t.project||require('path').basename(process.cwd()),
-      project_id:projectKey,team_id:t.team_id||'qualia-solutions',git_remote:gitRemote,
-      client:t.client||'',client_report_id:process.env.CLIENT_REPORT_ID,
-      framework_version:config.version||'',milestone:t.milestone||1,
-      milestone_name:t.milestone_name||'',milestones:Array.isArray(t.milestones)?t.milestones:[],
-      phase:t.phase,phase_name:t.phase_name,total_phases:t.total_phases,status:t.status,
-      tasks_done:t.tasks_done||0,tasks_total:t.tasks_total||0,verification:t.verification||'pending',
-      gap_cycles:(t.gap_cycles||{})[String(t.phase)]||0,build_count:t.build_count||0,
-      deploy_count:t.deploy_count||0,deployed_url:t.deployed_url||'',
-      ...(t.session_started_at?{session_started_at:t.session_started_at}:{}),
-      ...(t.last_pushed_at?{last_pushed_at:t.last_pushed_at}:{}),
-      session_duration_minutes:sessionDurationMinutes,
-      lifetime:t.lifetime||{},commits:commits,notes:notes,
-      submitted_by:process.env.SUBMITTED_BY||'unknown',submitted_at:process.env.SUBMITTED_AT
-    }));
-  "
+  node ~/.claude/bin/report-payload.js
 )
 
 # --dry-run: print and stop

package/skills/qualia-road/SKILL.md

@@ -117,7 +117,7 @@ No accumulated garbage. No context rot.
 - **Intent verification** — Confirm before modifying 3+ files (OWNER role: just do it)
 
 ## Tracking
-`.planning/tracking.json` is updated on every push. The ERP reads it via git.
+`.planning/tracking.json` is updated locally on every push. It feeds statusline, stop-session-log, and `/qualia-report`; the ERP receives explicit report uploads and does not read this file from git.
 Never edit tracking.json manually — hooks update it from STATE.md.
 
 ## Compaction — ALWAYS preserve

package/skills/qualia-verify/SKILL.md

@@ -106,7 +106,7 @@ Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIG
 
 ### 2d. INSUFFICIENT EVIDENCE downgrade (mandatory)
 
-The verifier marks criteria it could not check (budget exhaustion, missing context) as `INSUFFICIENT EVIDENCE`. The orchestrator treats those as silent PASS unless explicitly downgraded — that's the #1 false-pass vector. Grep the verification file before declaring PASS:
+The verifier marks criteria it could not check (budget exhaustion, missing context) as `INSUFFICIENT EVIDENCE`. The orchestrator must treat those as FAIL before declaring PASS. Grep the verification file and downgrade immediately:
 
 ```bash
 IE_COUNT=$(grep -c "INSUFFICIENT EVIDENCE" .planning/phase-{N}-verification.md 2>/dev/null || echo 0)

package/templates/help.html

@@ -437,7 +437,7 @@
         <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework version</span><span class="cmd-desc">Show installed version + check for updates.</span></div>
-        <div class="cmd"><span class="cmd-name">qualia-framework uninstall</span><span class="cmd-desc">Clean removal from ~/.claude/ while preserving user-owned settings.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework uninstall</span><span class="cmd-desc">Clean removal from installed Claude/Codex homes while preserving user-owned settings.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade legacy settings.json to the current hook layout.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework analytics</span><span class="cmd-desc">Hook telemetry, verification pass rates, gap cycles.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework set-erp-key</span><span class="cmd-desc">Save and enable the ERP API key.</span></div>

package/templates/knowledge/agents.md

@@ -6,11 +6,11 @@ once at session start.
 
 ## What's here
 
-`~/.claude/knowledge/` is the project-spanning memory tier. It holds three
+The installed `knowledge/` directory is the project-spanning memory tier. It holds three
 kinds of files, each with a clear purpose. Treat the structure as a contract.
 
 ```
-~/.claude/knowledge/
+knowledge/
 ├── agents.md              ← this file (system overview)
 ├── index.md               ← entry point — start here when answering questions
 ├── daily-log/
@@ -43,7 +43,7 @@ kinds of files, each with a clear purpose. Treat the structure as a contract.
 **Do not pretend something is in memory if it is not.** Better to say
 "INSUFFICIENT EVIDENCE: searched index.md and learned-patterns.md, no entry
 matches" than to hallucinate a recalled pattern. The grounding protocol
-(`~/.claude/rules/grounding.md`) applies here too.
+(`rules/grounding.md`) applies here too.
 
 ## Tiers
 

package/templates/knowledge/index.md

@@ -1,6 +1,6 @@
 # Knowledge Index
 
-Entry point for `~/.claude/knowledge/`. When answering a question, **read this
+Entry point for the installed `knowledge/` directory. When answering a question, **read this
 file first**, then jump to the specific file(s) that match.
 
 > Auto-maintained by `/qualia-learn`. Do not hand-edit unless the file is out

package/templates/tracking.json

@@ -5,6 +5,9 @@
   "assigned_to": "",
   "team_id": "",
   "project_id": "",
+  "erp_project_id": "",
+  "client_id": "",
+  "workspace_id": "",
   "git_remote": "",
   "milestone": 1,
   "milestone_name": "",