qualia-framework 6.2.10 → 6.3.0

package/bin/install.js

@@ -5,6 +5,7 @@ const path = require("path");
 const fs = require("fs");
 const ui = require("./qualia-ui.js");
 const { RUNTIME_BIN_SCRIPTS, binFiles } = require("./runtime-manifest.js");
+const { ACTIVE_SKILLS, RETIRED_SKILLS } = require("./command-surface.js");
 const { renderText } = require("./host-adapters.js");
 
 // ─── Colors (kept for legacy log lines; new sections route through qualia-ui) ─
@@ -49,7 +50,7 @@ const installStart = Date.now();
 
 // ─── Team codes ──────────────────────────────────────────
 const DEFAULT_TEAM = {
-  "QS-FAWZI-01": {
+  "QS-FAWZI-11": {
     name: "Fawzi Goussous",
     role: "OWNER",
     description: "Company owner. Full access. Can push to main, approve deploys, edit secrets.",
@@ -275,11 +276,7 @@ function renderCodexAgentToml(markdown, filenameFallback) {
 // Pruned from BOTH ~/.claude/skills/ and ~/.codex/skills/ on every install run
 // so the active surface matches what the framework currently ships.
 const DEPRECATED_SKILLS = [
-  "qualia-task",         // v5.7.0 — folded into qualia-feature
-  "qualia-quick",        // v5.7.0 — folded into qualia-feature
-  "qualia-polish-loop",  // v5.8.0 — folded into qualia-polish --loop
-  "qualia-design",       // v4 wave 2 — folded into scope-adaptive qualia-polish
-  "qualia-prd",          // v5.8.0 — surface cleanup
+  ...RETIRED_SKILLS,
 ];
 
 function pruneDeprecatedSkills(baseDir) {
@@ -491,8 +488,8 @@ function targetLabel(t) {
 }
 
 // ─── Resolve team code (tolerates case + O/0 typo in suffix) ─
-// Accepts "qs-fawzi-01", "QS-FAWZI-01", "QS-FAWZI-O1" (letter O in the
-// numeric suffix), and returns the canonical key if found, else null.
+// Accepts lowercase codes and common letter-O typos in numeric suffixes,
+// then returns the canonical key if found, else null.
 // Only normalizes O→0 in the segment AFTER the last dash — "QS-MOAYAD-03"
 // contains a real "O" in the name and must not be mangled.
 function resolveTeamCode(input) {
@@ -521,7 +518,7 @@ async function main() {
   if (!member) {
     console.log("");
     log(`${RED}✗${RESET} Invalid code: "${rawCode}". Get your install code from Fawzi.`);
-    log(`${DIM}  Tip: codes use digit zero, not letter O. Format: QS-NAME-01${RESET}`);
+    log(`${DIM}  Tip: codes use digit zero, not letter O. Format: QS-NAME-##${RESET}`);
     console.log("");
     process.exit(1);
   }
@@ -549,9 +546,7 @@ async function main() {
 
   // ─── Skills ──────────────────────────────────────────
   const skillsDir = path.join(FRAMEWORK_DIR, "skills");
-  const skills = fs
-    .readdirSync(skillsDir)
-    .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
+  const skills = ACTIVE_SKILLS.filter((d) => fs.existsSync(path.join(skillsDir, d, "SKILL.md")));
 
   printSection("Skills");
   const claudePruned = pruneDeprecatedSkills(CLAUDE_DIR);
@@ -868,7 +863,7 @@ Recurring issues and their solutions.
 ## Install code "Invalid" — user typed letter O instead of digit 0
 **Symptom:** \`npx qualia-framework install\` rejects \`QS-NAME-O1\` (letter O in suffix).
 **Cause:** Team codes use digit zero (\`-01\`, \`-02\`, etc.), not letter O.
-**Fix:** Since v2.8.1, install.js auto-normalizes: \`QS-FAWZI-O1\` → \`QS-FAWZI-01\`. The normalization only touches the segment after the last dash, so \`QS-MOAYAD-03\` (real O in name) is preserved.
+**Fix:** Since v2.8.1, install.js auto-normalizes: \`QS-HASAN-O2\` → \`QS-HASAN-02\`. The normalization only touches the segment after the last dash, so \`QS-MOAYAD-03\` (real O in name) is preserved.
 **Framework version:** Fixed in v2.8.1.
 
 ---
@@ -1061,6 +1056,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
     "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
     "git-guardrails.js", "stop-session-log.js",
+    "fawzi-approval-guard.js",
     // v5.0 — insights-driven destructive-op + wrong-account guards
     "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
   ]);
@@ -1086,6 +1082,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         hooks: [
           { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
           { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "⬢ Checking git safety..." },
+          { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
           { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
@@ -1098,6 +1095,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "Edit|Write",
         hooks: [
+          { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
           { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
@@ -1171,7 +1169,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   fs.writeFileSync(settingsTmp, JSON.stringify(settings, null, 2));
   fs.renameSync(settingsTmp, settingsPath);
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, git-guardrails, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, git-guardrails, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
@@ -1208,10 +1206,7 @@ function printSummary({ member, target, claudeInstalled }) {
     const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
     const rulesDir = path.join(FRAMEWORK_DIR, "rules");
     const tmplDir = path.join(FRAMEWORK_DIR, "templates");
-    const skillsDir = path.join(FRAMEWORK_DIR, "skills");
-    const skillCount = fs
-      .readdirSync(skillsDir)
-      .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory()).length;
+    const skillCount = ACTIVE_SKILLS.length;
     const agentCount = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md")).length;
     const hookCount = fs.readdirSync(hooksSource).length;
     const ruleCount = fs.readdirSync(rulesDir).length;
@@ -1450,9 +1445,9 @@ async function installCodex(member, target) {
     const skillsDest = path.join(CODEX_DIR, "skills");
     const codexPruned = pruneDeprecatedSkills(CODEX_DIR);
     for (const name of codexPruned) ok(`pruned deprecated: ${name}`);
-    for (const skill of fs.readdirSync(skillsSrc)) {
+    for (const skill of ACTIVE_SKILLS) {
       const src = path.join(skillsSrc, skill);
-      if (!fs.statSync(src).isDirectory()) continue;
+      if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) continue;
       copyTreeTransform(src, path.join(skillsDest, skill), codexText);
     }
     ok("skills/");
@@ -1529,6 +1524,7 @@ async function installCodex(member, target) {
             hooks: [
               { type: "command", command: nodeCmd("auto-update.js"), timeout: 5, statusMessage: "Qualia update check..." },
               { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "Qualia git safety..." },
+              { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
               { type: "command", command: nodeCmd("branch-guard.js"), timeout: 5 },
               { type: "command", command: nodeCmd("pre-push.js"), timeout: 15 },
               { type: "command", command: nodeCmd("pre-deploy-gate.js"), timeout: 180 },
@@ -1540,6 +1536,7 @@ async function installCodex(member, target) {
           {
             matcher: "Edit|Write",
             hooks: [
+              { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
               { type: "command", command: nodeCmd("migration-guard.js"), timeout: 10 },
             ],
           },

package/bin/knowledge-flush.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // ~/.claude/bin/knowledge-flush.js — non-interactive memory-layer flush.
 //
-// Wraps `/qualia-flush` so it can run from cron (or systemd timer, or any
-// CI/scheduled job) without an interactive Claude Code session. Closes the
+// Runs the Qualia memory flush prompt from cron (or systemd timer, or any
+// CI/scheduled job) without installing a separate slash command. Closes the
 // memory loop end-to-end:
 //
 //   Stop hook (auto, every turn) → <install-home>/knowledge/daily-log/{date}.md
 //   THIS SCRIPT (weekly cron)    → spawns the installed agent CLI
-//   /qualia-flush                 → promotes raw → curated tier
+//   flush prompt                 → promotes raw → curated tier
 //   bin/knowledge.js (every spawn) → reads index.md → reaches the right file
 //
 // Usage:
@@ -86,10 +86,9 @@ function which(cmd) {
   return null;
 }
 
-// Pass-through args (so `--days 14`, `--dry-run`, `--project X` all reach the
-// skill). We don't parse them ourselves — the skill is the source of truth
-// for argument semantics. We only use `--days` locally to short-circuit when
-// the daily-log is genuinely empty.
+// Pass-through args (so `--days 14`, `--dry-run`, `--project X` are visible to
+// the agent prompt). We only parse `--days` locally to short-circuit when the
+// daily-log is genuinely empty.
 const argv = process.argv.slice(2);
 const flagIdx = argv.indexOf("--days");
 const days = flagIdx >= 0 ? parseInt(argv[flagIdx + 1], 10) || 7 : 7;
@@ -128,9 +127,21 @@ if (!dailyLogHasRecentEntries(days)) {
 
 // ── Run ──────────────────────────────────────────────────
 // `claude -p "<prompt>"` and `codex exec "<prompt>"` run a single
-// non-interactive turn. The skill body invocation matches what the user would
-// type at the prompt.
-const prompt = `/qualia-flush ${argv.join(" ")}`.trim();
+// non-interactive turn. Keep the prompt self-contained so no separate flush
+// slash command needs to be installed.
+const argsText = argv.join(" ").trim() || "(none)";
+const prompt = [
+  "Run the Qualia memory flush.",
+  "",
+  `Arguments: ${argsText}`,
+  `Install home: ${QUALIA_HOME}`,
+  "",
+  "Read recent markdown files from knowledge/daily-log under the install home.",
+  "Promote recurring patterns, decisions, fixes, and client preferences into the curated knowledge tier using bin/knowledge.js append.",
+  "Do not promote one-off noise. If --dry-run is present, report planned promotions without writing.",
+  "If --project NAME is present, limit promotions to that project.",
+  "Finish with one line starting exactly: ⬢ Flushed daily-log",
+].join("\n");
 
 const cliArgs = IS_CODEX_INSTALL ? ["exec", prompt] : ["-p", prompt];
 const result = spawnSync(agentBin, cliArgs, {

package/bin/knowledge.js

@@ -79,7 +79,7 @@ function readSafe(p) {
 //   3. Path with "/" → treat as relative to knowledge dir (concepts/foo)
 //   4. Bare name → look in top-level first; if missing, search known
 //      subdirectories (concepts/, daily-log/) for an exact match. This
-//      means /qualia-flush can write to concepts/voice-agent-call-state.md
+//      means the memory flush can write to concepts/voice-agent-call-state.md
 //      and skills can later run `knowledge.js load voice-agent-call-state`
 //      without knowing it lives in a subdirectory.
 function resolveFile(name) {

package/bin/project-snapshot.js

@@ -5,6 +5,8 @@ const https = require("https");
 const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const harnessEval = require("./harness-eval.js");
+const { readLocalWorkPacket } = require("./work-packet.js");
 
 function readJson(file, fallback = {}) {
   try {
@@ -90,6 +92,8 @@ function buildSnapshot(options = {}) {
   const projectId = tracking.project_id || repoSlug(gitRemote) || path.basename(cwd);
   const currentMilestone = Number(tracking.milestone || 1);
   const currentPhase = Number(tracking.phase || 0);
+  const latestHarnessEval = harnessEval.latestEval(cwd);
+  const workPacket = readLocalWorkPacket(cwd);
   const totalPhases = Number(tracking.total_phases || 0);
   const lifetime = tracking.lifetime && typeof tracking.lifetime === "object" ? tracking.lifetime : {};
   const closedMilestones = Array.isArray(tracking.milestones) ? tracking.milestones : [];
@@ -118,6 +122,11 @@ function buildSnapshot(options = {}) {
       ...(uuid(tracking.erp_project_id) ? { erp_project_id: uuid(tracking.erp_project_id) } : {}),
       ...(uuid(tracking.client_id) ? { client_id: uuid(tracking.client_id) } : {}),
       ...(uuid(tracking.workspace_id) ? { workspace_id: uuid(tracking.workspace_id) } : {}),
+      ...(workPacket ? { work_packet_id: workPacket.id } : {}),
+      ...(workPacket && workPacket.assignment_id ? { assignment_id: workPacket.assignment_id } : {}),
+      ...(workPacket && workPacket.deadline_date
+        ? { assignment_deadline: workPacket.deadline_date }
+        : {}),
     },
     project: {
       name: tracking.project || path.basename(cwd),
@@ -137,6 +146,17 @@ function buildSnapshot(options = {}) {
       verification: tracking.verification || "pending",
       gap_cycles: (tracking.gap_cycles || {})[String(currentPhase)] || 0,
     },
+    quality: {
+      harness_eval: latestHarnessEval
+        ? {
+            status: latestHarnessEval.status,
+            score: latestHarnessEval.score,
+            phase: latestHarnessEval.phase,
+            generated_at: latestHarnessEval.generated_at,
+            artifact: latestHarnessEval.artifacts && latestHarnessEval.artifacts.json,
+          }
+        : null,
+    },
     journey: {
       total_milestones: journeyTotal,
       milestones: journey.map((milestone) => ({

package/bin/report-payload.js

@@ -3,6 +3,8 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const harnessEval = require("./harness-eval.js");
+const { readLocalWorkPacket } = require("./work-packet.js");
 
 function readJson(file, fallback = {}) {
   try {
@@ -84,6 +86,8 @@ function buildPayload(options = {}) {
   const gitRemote = tracking.git_remote || git(["config", "--get", "remote.origin.url"], cwd);
   const projectKey = tracking.project_id || repoSlug(gitRemote) || path.basename(cwd);
   const phase = tracking.phase;
+  const latestHarnessEval = harnessEval.latestEval(cwd);
+  const workPacket = readLocalWorkPacket(cwd);
 
   return {
     project: tracking.project || path.basename(cwd),
@@ -93,6 +97,11 @@ function buildPayload(options = {}) {
     ...(uuid(tracking.erp_project_id) ? { erp_project_id: uuid(tracking.erp_project_id) } : {}),
     ...(uuid(tracking.client_id) ? { client_id: uuid(tracking.client_id) } : {}),
     ...(uuid(tracking.workspace_id) ? { workspace_id: uuid(tracking.workspace_id) } : {}),
+    ...(workPacket ? { work_packet_id: workPacket.id } : {}),
+    ...(workPacket && workPacket.assignment_id ? { assignment_id: workPacket.assignment_id } : {}),
+    ...(workPacket && workPacket.deadline_date
+      ? { assignment_deadline: workPacket.deadline_date }
+      : {}),
     client: tracking.client || "",
     client_report_id: env.CLIENT_REPORT_ID || "",
     framework_version: config.version || "",
@@ -114,6 +123,15 @@ function buildPayload(options = {}) {
     ...(tracking.last_pushed_at ? { last_pushed_at: tracking.last_pushed_at } : {}),
     session_duration_minutes: sessionDurationMinutes(tracking.session_started_at, submittedAt),
     lifetime: tracking.lifetime || {},
+    ...(latestHarnessEval ? {
+      harness_eval: {
+        status: latestHarnessEval.status,
+        score: latestHarnessEval.score,
+        phase: latestHarnessEval.phase,
+        generated_at: latestHarnessEval.generated_at,
+        artifact: latestHarnessEval.artifacts && latestHarnessEval.artifacts.json,
+      },
+    } : {}),
     commits: recentCommitHashes(cwd),
     notes,
     submitted_by: env.SUBMITTED_BY || "unknown",

package/bin/runtime-manifest.js

@@ -3,6 +3,7 @@
 
 const RUNTIME_BIN_SCRIPTS = [
   { file: "runtime-manifest.js", label: "runtime-manifest.js (shared install manifest)" },
+  { file: "command-surface.js", label: "command-surface.js (active/deprecated skill manifest)" },
   { file: "host-adapters.js", label: "host-adapters.js (Claude/Codex path renderer)" },
   { file: "state.js", label: "state.js (state machine)" },
   { file: "qualia-ui.js", label: "qualia-ui.js (cosmetics library)" },
@@ -15,9 +16,11 @@ const RUNTIME_BIN_SCRIPTS = [
   { file: "agent-runs.js", label: "agent-runs.js (agent telemetry writer)" },
   { file: "slop-detect.mjs", label: "slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)" },
   { file: "erp-retry.js", label: "erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)" },
+  { file: "work-packet.js", label: "work-packet.js (ERP mission/work packet pull + local reader)" },
   { file: "report-payload.js", label: "report-payload.js (Framework -> ERP report payload builder)" },
   { file: "project-snapshot.js", label: "project-snapshot.js (ERP/admin project progress snapshot)" },
   { file: "trust-score.js", label: "trust-score.js (harness health scoring)" },
+  { file: "harness-eval.js", label: "harness-eval.js (project eval scoring + evidence artifact)" },
   { file: "codex-goal.js", label: "codex-goal.js (Codex /goal objective + token-budget suggester)" },
   { file: "planning-hygiene.js", label: "planning-hygiene.js (.planning organization scanner)" },
 ];

package/bin/state.js

@@ -468,6 +468,14 @@ function checkPreconditions(current, target, opts) {
       return fail("MISSING_FILE", `Verification file not found: ${vFile}`);
     if (!opts.verification || !["pass", "fail"].includes(opts.verification))
       return fail("MISSING_ARG", "--verification must be 'pass' or 'fail'");
+    if (opts.verification === "pass") {
+      const vContent = fs.readFileSync(vFile, "utf8");
+      if (/\bINSUFFICIENT EVIDENCE\b/.test(vContent)) {
+        return fail("INSUFFICIENT_EVIDENCE", `${vFile} contains INSUFFICIENT EVIDENCE; PASS is not allowed`);
+      }
+      const evidenceCheck = checkMachineEvidence(phase);
+      if (!evidenceCheck.ok) return evidenceCheck;
+    }
   }
 
   if (target === "shipped") {
@@ -501,6 +509,29 @@ function fail(error, message) {
   return { ok: false, error, message };
 }
 
+function checkMachineEvidence(phase) {
+  const contractFile = path.join(PLANNING, `phase-${phase}-contract.json`);
+  if (!fs.existsSync(contractFile)) return { ok: true };
+
+  const evidenceFile = path.join(PLANNING, "evidence", `phase-${phase}-contract-run.json`);
+  if (!fs.existsSync(evidenceFile)) {
+    return fail(
+      "MISSING_EVIDENCE",
+      `Contract exists for phase ${phase}, but machine evidence is missing: ${evidenceFile}. Run contract-runner.js or qualia-framework eval --run --write.`
+    );
+  }
+  let evidence;
+  try {
+    evidence = JSON.parse(fs.readFileSync(evidenceFile, "utf8"));
+  } catch (e) {
+    return fail("INVALID_EVIDENCE", `Could not parse ${evidenceFile}: ${e.message}`);
+  }
+  if (!evidence || evidence.ok !== true) {
+    return fail("FAILING_EVIDENCE", `${evidenceFile} does not prove the contract passed`);
+  }
+  return { ok: true };
+}
+
 function recordLedgerEvent(meta) {
   try {
     return stateLedger.append(process.cwd(), {

package/bin/trust-score.js

@@ -7,6 +7,7 @@ const os = require("os");
 const pc = require("./plan-contract.js");
 const ledger = require("./state-ledger.js");
 const { binFiles } = require("./runtime-manifest.js");
+const { ACTIVE_SKILLS } = require("./command-surface.js");
 
 const HOMES = [
   { name: "Claude", dir: path.join(os.homedir(), ".claude") },
@@ -18,7 +19,7 @@ const REQUIRED_BIN = binFiles();
 const REQUIRED_HOOKS = [
   "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
   "pre-deploy-gate.js", "migration-guard.js", "git-guardrails.js",
-  "stop-session-log.js", "vercel-account-guard.js", "env-empty-guard.js",
+  "stop-session-log.js", "fawzi-approval-guard.js", "vercel-account-guard.js", "env-empty-guard.js",
   "supabase-destructive-guard.js",
 ];
 
@@ -32,13 +33,7 @@ const REQUIRED_DESIGN_FILES = [
   "graphics.md",
 ];
 
-const REQUIRED_EMPLOYEE_SKILLS = [
-  "qualia-doctor",
-  "qualia-road",
-  "qualia-resume",
-  "qualia-pause",
-  "qualia-report",
-];
+const REQUIRED_EMPLOYEE_SKILLS = ACTIVE_SKILLS;
 
 function exists(p) {
   try { return fs.existsSync(p); } catch { return false; }
@@ -169,9 +164,6 @@ function inspectDesign(homes) {
     if (!exists(path.join(home.dir, "skills", "qualia-polish", "SKILL.md"))) {
       issues.push(`${home.name}: missing qualia-polish skill`);
     }
-    if (!exists(path.join(home.dir, "skills", "qualia-vibe", "SKILL.md"))) {
-      issues.push(`${home.name}: missing qualia-vibe skill`);
-    }
     if (!exists(path.join(home.dir, "agents", home.name === "Codex" ? "visual-evaluator.toml" : "visual-evaluator.md"))) {
       issues.push(`${home.name}: missing visual-evaluator agent`);
     }

package/bin/work-packet.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+
+const WORK_PACKET_FILE = path.join(".planning", "work-packet.json");
+
+function readJson(file, fallback = {}) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function readText(file, fallback = "") {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+function qualiaHome(home = os.homedir()) {
+  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);
+  const claude = path.join(home, ".claude");
+  if (fs.existsSync(path.join(claude, ".qualia-config.json"))) return claude;
+  return claude;
+}
+
+function uuid(value) {
+  if (typeof value !== "string") return "";
+  const trimmed = value.trim();
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmed)
+    ? trimmed
+    : "";
+}
+
+function localWorkPacketPath(cwd = process.cwd()) {
+  return path.join(cwd, WORK_PACKET_FILE);
+}
+
+function normalizePacket(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const packet = raw.work_packet && typeof raw.work_packet === "object" ? raw.work_packet : raw;
+  if (!packet || typeof packet !== "object" || Array.isArray(packet)) return null;
+  const id = uuid(packet.id || packet.work_packet_id);
+  const projectId = uuid(packet.project_id || packet.erp_project_id);
+  if (!id || !projectId) return null;
+  return {
+    id,
+    project_id: projectId,
+    assignment_id: uuid(packet.assignment_id) || null,
+    employee_id: uuid(packet.employee_id) || null,
+    deadline_date: typeof packet.deadline_date === "string" ? packet.deadline_date : null,
+    current_milestone: Number.isFinite(packet.current_milestone) ? packet.current_milestone : null,
+    current_milestone_name:
+      typeof packet.current_milestone_name === "string" ? packet.current_milestone_name : null,
+    current_phase: Number.isFinite(packet.current_phase) ? packet.current_phase : null,
+    current_phase_name: typeof packet.current_phase_name === "string" ? packet.current_phase_name : null,
+    next_command: typeof packet.next_command === "string" ? packet.next_command : "/qualia",
+    definition_of_done:
+      typeof packet.definition_of_done === "string" ? packet.definition_of_done : null,
+    blockers: Array.isArray(packet.blockers) ? packet.blockers.filter((b) => typeof b === "string") : [],
+    repo_url: typeof packet.repo_url === "string" ? packet.repo_url : null,
+    vercel_url: typeof packet.vercel_url === "string" ? packet.vercel_url : null,
+    framework_status:
+      typeof packet.framework_status === "string" ? packet.framework_status : null,
+    verification: typeof packet.verification === "string" ? packet.verification : null,
+    snapshot_generated_at:
+      typeof packet.snapshot_generated_at === "string" ? packet.snapshot_generated_at : null,
+    last_report_at: typeof packet.last_report_at === "string" ? packet.last_report_at : null,
+    status: typeof packet.status === "string" ? packet.status : "active",
+    updated_at: typeof packet.updated_at === "string" ? packet.updated_at : null,
+    employee: packet.employee && typeof packet.employee === "object" ? packet.employee : null,
+    project: packet.project && typeof packet.project === "object" ? packet.project : null,
+    mission_url: typeof packet.mission_url === "string" ? packet.mission_url : null,
+  };
+}
+
+function readLocalWorkPacket(cwd = process.cwd()) {
+  return normalizePacket(readJson(localWorkPacketPath(cwd), null));
+}
+
+function writeLocalWorkPacket(packet, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const file = options.file || localWorkPacketPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
+  return file;
+}
+
+function erpConfig(options = {}) {
+  const home = options.home || os.homedir();
+  const installHome = options.qualiaHome || qualiaHome(home);
+  const config = readJson(path.join(installHome, ".qualia-config.json"), {});
+  const erp = config.erp || {};
+  const url = (erp.url || "https://portal.qualiasolutions.net").replace(/\/+$/, "");
+  const keyFile = path.join(installHome, erp.api_key_file || ".erp-api-key");
+  const key = readText(keyFile, "").trim();
+  return {
+    enabled: erp.enabled !== false,
+    url,
+    key,
+  };
+}
+
+function trackingProjectId(cwd = process.cwd()) {
+  const tracking = readJson(path.join(cwd, ".planning", "tracking.json"), {});
+  return uuid(tracking.erp_project_id);
+}
+
+function fetchJson(url, key, options = {}) {
+  const endpoint = new URL(url);
+  const transport = endpoint.protocol === "http:" ? http : https;
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      endpoint,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${key}`,
+          Accept: "application/json",
+          "User-Agent": "qualia-framework-work-packet",
+        },
+        timeout: options.timeout || 15000,
+      },
+      (res) => {
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          body += chunk;
+        });
+        res.on("end", () => {
+          let parsed = null;
+          try {
+            parsed = body ? JSON.parse(body) : null;
+          } catch {
+            parsed = body;
+          }
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(parsed);
+          } else {
+            const message =
+              parsed && typeof parsed === "object" && parsed.message
+                ? parsed.message
+                : body || `HTTP ${res.statusCode}`;
+            reject(new Error(`ERP work packet pull failed (${res.statusCode}): ${message}`));
+          }
+        });
+      }
+    );
+    req.on("timeout", () => req.destroy(new Error("ERP work packet pull timed out")));
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+async function pullWorkPacket(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const cfg = options.erp || erpConfig(options);
+  if (!cfg.enabled) throw new Error("ERP disabled in Qualia config");
+  if (!cfg.key) throw new Error("ERP API key missing in Qualia install");
+  const projectId = uuid(options.projectId) || trackingProjectId(cwd);
+  if (!projectId) {
+    throw new Error("ERP project UUID required. Pass --project <uuid> or set tracking.erp_project_id");
+  }
+  const endpoint = new URL("/api/v1/work-packets", cfg.url);
+  endpoint.searchParams.set("project_id", projectId);
+  const response = await fetchJson(endpoint.toString(), cfg.key, options);
+  const packet = normalizePacket(response);
+  if (!packet) throw new Error("ERP returned an invalid work packet");
+  return packet;
+}
+
+function parseArgs(argv) {
+  const args = {
+    action: "show",
+    projectId: "",
+    write: false,
+    pretty: false,
+    output: "",
+  };
+  const rest = [...argv];
+  if (rest[0] && !rest[0].startsWith("-")) args.action = rest.shift();
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--project" || arg === "-p") args.projectId = rest[++i] || "";
+    else if (arg === "--write") args.write = true;
+    else if (arg === "--pretty") args.pretty = true;
+    else if (arg === "--output" || arg === "-o") args.output = rest[++i] || "";
+  }
+  return args;
+}
+
+if (require.main === module) {
+  (async () => {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.action === "pull") {
+      const packet = await pullWorkPacket({ projectId: args.projectId });
+      const file = writeLocalWorkPacket(packet, { file: args.output || undefined });
+      process.stdout.write(args.pretty ? `${JSON.stringify(packet, null, 2)}\n` : `${file}\n`);
+      return;
+    }
+    const packet = readLocalWorkPacket();
+    if (!packet) throw new Error("No local .planning/work-packet.json found");
+    process.stdout.write(`${JSON.stringify(packet, null, args.pretty ? 2 : 0)}\n`);
+  })().catch((error) => {
+    console.error(`work-packet failed: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  WORK_PACKET_FILE,
+  erpConfig,
+  localWorkPacketPath,
+  normalizePacket,
+  pullWorkPacket,
+  readLocalWorkPacket,
+  trackingProjectId,
+  uuid,
+  writeLocalWorkPacket,
+};