qualia-framework 6.2.10 → 6.3.0

package/AGENTS.md

@@ -11,6 +11,7 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 - Feature branches only — never push to main/master
 - MVP first — build only what's asked
 - Root cause on failures — no band-aids
+- No proxy approval — employees cannot claim Fawzi approved; OWNER-only overrides require OWNER config
 
 ## Discoverable substrate (load on demand, not always)
 - `/qualia-road` — workflow map, every command, when to use it

package/CLAUDE.md

@@ -11,6 +11,7 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 - Feature branches only — never push to main/master
 - MVP first — build only what's asked
 - Root cause on failures — no band-aids
+- No proxy approval — employees cannot claim Fawzi approved; OWNER-only overrides require OWNER config
 
 ## Discoverable substrate (load on demand, not always)
 - `/qualia-road` — workflow map, every command, when to use it

package/README.md

@@ -1,9 +1,11 @@
-# Qualia Framework v6.2.10
+# Qualia Framework v6.3.0
 
 A harness engineering framework for Claude Code and OpenAI Codex. It installs into `~/.claude/` and/or `~/.codex/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
 It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
+**v6.3.0** — Harness hardening pass. Default install surface drops to 23 active skills, retired helper command sources are removed and pruned from older installs, `/qualia-polish --vibe` absorbs the separate vibe command, `harness-eval.js` writes scored eval artifacts, ERP reports/snapshots carry the latest eval score, and `state.js` refuses PASS when machine contract evidence is missing/failing or the verification report contains `INSUFFICIENT EVIDENCE`.
+**v6.2.11** — Owner approval integrity. Fawzi's install code is now `QS-FAWZI-11`; employees cannot use `QUALIA_SHIP_FORCE=1`; deploy refusals say why and what to run next; and employee "Fawzi said OK" proxy-approval claims are silently counted for ERP policy review.
 **v6.2.10** — Codex status line is now a publish-blocking install contract. Installer guarantees `[tui].status_line` in `~/.codex/config.toml`, `/qualia-doctor` verifies the native bottom line, and package smoke tests assert the Codex TUI segments are present.
 **v6.2.9** — Codex hook noise + status line. Conditional PreToolUse hooks no longer status-message on every Bash call (Codex was printing 8 "Running hook…" lines on every command). Self-filtering added to `pre-deploy-gate.js` and `pre-push.js` so they never trip on unrelated commands (Claude's substring matcher was firing them on for-loop arguments). Installer now writes `[tui] status_line = [...]` to Codex's `config.toml` for the rich native bottom status line.
 
@@ -12,10 +14,10 @@ It is not an application framework like Rails or Next.js. It doesn't generate co
 **v6.2.7** — Codex runtime compatibility. The installer now writes Codex-native hooks, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config under `~/.codex/`, not just `AGENTS.md`.
 
 **The v5 line (preserved):**
-- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
+- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, zoom/queue helper experiments, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
 - **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
 - **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
-- **v5.3**, Matt Pocock gaps closed. `/qualia-hook-gen` (CLAUDE.md instruction to deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+- **v5.3**, Matt Pocock gaps closed. hook-generation utility experiment, `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
 - **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
 - **v5.6**, Demo vs Full Project gate at kickoff. Mandatory discovery interview via `/qualia-discuss` in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in `/qualia-milestone` for client-signs-after-demo conversion.
 - **v5.7**, `/qualia-feature` consolidates `/qualia-quick` + `/qualia-task` into one auto-scoped command.
@@ -24,7 +26,7 @@ It is not an application framework like Rails or Next.js. It doesn't generate co
 - **v5.9.1**, kickoff UX fix. `/qualia-new` now opens with the Demo/Full/Quick gate as Step 1 (`AskUserQuestion`), then exactly one free-text pitch question, then mandatory hand-off to `/qualia-discuss` — no ad-hoc clarification questioning between them. The shape gate drives the whole downstream interview, so it must come first.
 - **v5.9.2**, hook ordering + ERP payload fixes. `pre-push.js` self-gates against `branch-guard.js` so a blocked-push no longer leaves an orphan bot commit in local history. `qualia-report` ERP payload omits empty ISO datetime fields (`session_started_at`, `last_pushed_at`) instead of sending `''`, which the ERP validator rejected as 422.
 - **v6.0.0**, audit + cleanup pass. See CHANGELOG for the full list. Highlights: uninstall/migrate manifests fixed, silent hook `catch{}` blocks now traced, phantom `rules/frontend.md` references replaced, `/qualia-learn` and `/qualia-map` declare their actually-used tools, `/qualia-plan` revision-cycle contradiction reconciled (max 2), `agents/planner.md` and `agents/qa-browser.md` MCP tools declared in frontmatter, `rules/trust-boundary.md` extracted, hardcoded `/tmp` paths replaced with `mktemp`, fail-collect test runner, pre-v4 CHANGELOG archived.
-- **v6.1.0**, `/qualia-vibe` adds a fast layout-preserving design pivot path and strengthens design-surface guards.
+- **v6.1.0**, `/qualia-polish --vibe` adds a fast layout-preserving design pivot path and strengthens design-surface guards.
 - **v6.2.0**, removes hook-created bot commits. The ERP/report contract is `/qualia-report` POSTs, not passive git scraping of `tracking.json`.
 - **v6.2.1**, active-surface drift guard. README, guide, onboarding, ERP contract, road, milestone, polish, verify, and roadmapper wording now align with v6.2 behavior; refs tests fail on the stale claims.
 - **v6.2.2**, Framework/Memory/ERP clarity. ERP can hand a work packet into Framework sessions, reports can carry ERP-native IDs, and public npm install proof is a first-class release smoke.
@@ -104,37 +106,27 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 
 ```
 /qualia           # Mechanical state router — "what's my next command?"
-/qualia-idk       # Diagnostic — "what's actually going on?" Two isolated scans (planning / codebase), then a plain-language explanation
-/qualia-pause     # Save session, continue later
-/qualia-resume    # Pick up where you left off
+/qualia           # Also handles "resume", "pause", and "I don't know what's going on" diagnostics
+/qualia-road      # View and navigate the project road (journey/milestone/phase status)
 ```
 
 ### Quality & shortcuts
 
 ```
-/qualia-debug         # Structured debugging
 /qualia-fix           # Repair broken existing behavior (root cause -> patch -> verify -> report)
 /qualia-review        # Production audit (scored diagnostics)
 /qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
 /qualia-feature       # Auto-scoped new feature build (inline for trivia, fresh spawn for 1-5 files)
 /qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
-/qualia-zoom          # Focus on a single file or function with full context
-/qualia-issues        # Break a phase plan into vertical-slice GitHub issues
-/qualia-triage        # Triage open issues through the ready-for-agent state machine
-/qualia-road          # View and navigate the project road (journey/milestone/phase status)
 /qualia-polish --loop # Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat
-/qualia-vibe          # Fast aesthetic pivot (~3 min): swap design tokens, keep layout. Supports --extract URL (reverse-engineer DESIGN.md) and --sync (code → DESIGN.md back-sync)
-/qualia-hook-gen      # Convert a CLAUDE.md/rules instruction into a deterministic hook
+/qualia-polish --vibe          # Fast aesthetic pivot (~3 min): swap design tokens, keep layout. Supports --extract URL (reverse-engineer DESIGN.md) and --sync (code → DESIGN.md back-sync)
 ```
 
 ### Knowledge & meta
 
 ```
 /qualia-learn      # Save a pattern, fix, or client pref to the active install home's knowledge/
-/qualia-flush      # Promote daily-log raw entries into curated knowledge concepts
 /qualia-postmortem # Self-heal — when verification fails, propose rule/skill deltas
-/qualia-skill-new  # Author a new Qualia skill or agent
-/qualia-help       # Open the framework reference in your browser
 ```
 
 ### Team-specific
@@ -165,11 +157,11 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.
 
-## What's Inside (v6.2.10)
+## What's Inside (v6.3.0)
 
-- **35 installed skills**, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (fix, debug, review, optimize with `--deepen` parallel-interface design, feature, test, zoom, issues, triage), design (`qualia-polish --loop`, `qualia-vibe` for fast aesthetic pivots), deterministic enforcement (`qualia-hook-gen`), meta (learn, skill-new, flush, postmortem), and Zoho workflow support
+- **23 installed skills**, focused into Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router + road), quality (fix, review, optimize with `--deepen` parallel-interface design, feature, test), design (`qualia-polish --loop` and `--vibe`), health/reporting (doctor, learn, postmortem), and Zoho workflow support. Retired helper commands are pruned on install rather than exposed as default slash commands.
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
-- **11 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
+- **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **10 installed rules** (`rules/`): grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, and always-on command-output transparency.
 - **7 lazy-loaded design files** (`qualia-design/`): design-laws, design-brand, design-product, design-rubric, design-reference, frontend, graphics — `Read` on demand by design-aware skills/agents only.
 - **25 template files**: project.md, journey.md, plan.md (story-file format), state.md, DESIGN.md, CONTEXT.md (domain glossary), work-packet.md (ERP-approved session context), decisions/ADR-template.md, tracking.json (with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
@@ -210,9 +202,10 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-All 11 hooks are real ops engineering, not theoretical:
+All 12 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
+- **Fawzi approval guard** — Silently counts employee proxy-approval claims for ERP review
 - **Session start** — Shows project state, next command, update notices, and health warnings at session start
 - **Auto-update** — Daily update check with cached failures so offline/npm issues do not slow every command
 - **Git guardrails** — Blocks destructive git operations like force-push to main/master, `git clean -fd`, and `rm -rf .git`
@@ -234,7 +227,7 @@ Plans are grouped into waves for parallel execution. No fancy DAG solver — the
 
 ### Diagnostic Intelligence
 
-`/qualia-idk` is a real diagnostician (not a router alias). When the user's confusion is about *understanding the situation*, it spawns two isolated scans in parallel — one reads only `.planning/`, the other reads only source code — then synthesizes a plain-language "What I see / What I think is happening / What to do next" diagnosis. Catches plan↔code drift that a state-only router can't see.
+`/qualia` is a real diagnostician (not a router alias). When the user's confusion is about *understanding the situation*, it spawns two isolated scans in parallel — one reads only `.planning/`, the other reads only source code — then synthesizes a plain-language "What I see / What I think is happening / What to do next" diagnosis. Catches plan↔code drift that a state-only router can't see.
 
 ## Architecture
 
@@ -243,7 +236,7 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/ and/or ~/.codex/
-  ├── skills/             35 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
+  ├── skills/             23 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
   ├── agents/             9 agent definitions (Claude .md, Codex .toml)
   ├── hooks/              11 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + planning-hygiene.js + plan-contract.js + agent-runs.js + ERP/report helpers

package/bin/cli.js

@@ -205,6 +205,7 @@ const QUALIA_HOOK_FILES = [
   "pre-deploy-gate.js",
   "git-guardrails.js",
   "stop-session-log.js",
+  "fawzi-approval-guard.js",
   "env-empty-guard.js",
   "supabase-destructive-guard.js",
   "vercel-account-guard.js",
@@ -499,7 +500,7 @@ async function cmdUninstall() {
 
 function getDefaultTeam() {
   return {
-    "QS-FAWZI-01": { name: "Fawzi Goussous", role: "OWNER", description: "Company owner. Full access. Can push to main, approve deploys, edit secrets." },
+    "QS-FAWZI-11": { name: "Fawzi Goussous", role: "OWNER", description: "Company owner. Full access. Can push to main, approve deploys, edit secrets." },
     "QS-HASAN-02": { name: "Hasan", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
     "QS-MOAYAD-03": { name: "Moayad", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
     "QS-RAMA-04": { name: "Rama", role: "EMPLOYEE", description: "Developer. Feature branches only. Cannot push to main or edit .env files." },
@@ -1206,6 +1207,23 @@ function cmdProjectSnapshot() {
   process.exit(typeof r.status === "number" ? r.status : 1);
 }
 
+function cmdWorkPacket() {
+  const installedScript = path.join(primaryInstallHome(), "bin", "work-packet.js");
+  const localScript = path.join(__dirname, "work-packet.js");
+  const script = fs.existsSync(installedScript) ? installedScript : localScript;
+  if (!fs.existsSync(script)) {
+    console.log(`  ${RED}✗${RESET} work-packet.js not available`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [script, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
 function cmdPlanningHygiene() {
   const installedScript = path.join(primaryInstallHome(), "bin", "planning-hygiene.js");
   const localScript = path.join(__dirname, "planning-hygiene.js");
@@ -1240,6 +1258,23 @@ function cmdTrust() {
   process.exit(typeof r.status === "number" ? r.status : 1);
 }
 
+function cmdHarnessEval() {
+  const installedScript = path.join(primaryInstallHome(), "bin", "harness-eval.js");
+  const localScript = path.join(__dirname, "harness-eval.js");
+  const script = fs.existsSync(installedScript) ? installedScript : localScript;
+  if (!fs.existsSync(script)) {
+    console.log(`  ${RED}✗${RESET} harness-eval.js not available`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [script, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
 function cmdFlush() {
   const flushScript = path.join(primaryInstallHome(), "bin", "knowledge-flush.js");
   if (!fs.existsSync(flushScript)) {
@@ -1282,12 +1317,14 @@ function cmdDoctor() {
       "bin/state.js",
       "bin/qualia-ui.js",
       "bin/statusline.js",
+      "bin/command-surface.js",
       "bin/knowledge.js",
       "bin/knowledge-flush.js",
       "bin/state-ledger.js",
       "bin/plan-contract.js",
       "bin/contract-runner.js",
       "bin/trust-score.js",
+      "bin/harness-eval.js",
       "bin/erp-retry.js",
       "bin/report-payload.js",
       "bin/project-snapshot.js",
@@ -1518,10 +1555,12 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}set-erp-key${RESET}  Save/enable the ERP API key`);
   console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
   console.log(`    qualia-framework ${TEAL}erp-flush${RESET}    Retry queued ERP report uploads (${DIM}show|clear${RESET})`);
+  console.log(`    qualia-framework ${TEAL}work-packet${RESET}  Pull/read ERP mission packet (${DIM}pull --project UUID${RESET})`);
   console.log(`    qualia-framework ${TEAL}project-snapshot${RESET} Export/upload ERP admin project progress snapshot (${DIM}--write|--upload${RESET})`);
   console.log(`    qualia-framework ${TEAL}planning-hygiene${RESET} Scan/organize .planning artifacts (${DIM}scan|organize --write${RESET})`);
   console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
   console.log(`    qualia-framework ${TEAL}trust${RESET}        Score install, state, contracts, memory, ERP (${DIM}--json${RESET})`);
+  console.log(`    qualia-framework ${TEAL}eval${RESET}         Write/run project harness eval scoring (${DIM}--run --write --json${RESET})`);
   console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
@@ -1532,7 +1571,7 @@ function cmdHelp() {
   console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
   console.log(`    ${TG}/qualia-verify${RESET}   Verify it works`);
   console.log(`    ${TG}/qualia-polish${RESET}   Design pass — any scope (component, route, app, redesign)`);
-  console.log(`    ${TG}/qualia-debug${RESET}    Structured debugging`);
+  console.log(`    ${TG}/qualia-fix${RESET}      Root-cause broken behavior, patch, verify`);
   console.log(`    ${TG}/qualia-review${RESET}   Production audit`);
   console.log(`    ${TG}/qualia-ship${RESET}     Deploy to production`);
   console.log(`    ${TG}/qualia-report${RESET}   Log your work`);
@@ -1595,6 +1634,10 @@ switch (cmd) {
   case "snapshot":
     cmdProjectSnapshot();
     break;
+  case "work-packet":
+  case "packet":
+    cmdWorkPacket();
+    break;
   case "planning-hygiene":
   case "planning":
     cmdPlanningHygiene();
@@ -1608,6 +1651,10 @@ switch (cmd) {
   case "score":
     cmdTrust();
     break;
+  case "eval":
+  case "harness-eval":
+    cmdHarnessEval();
+    break;
   case "flush":
   case "knowledge-flush":
     cmdFlush();

package/bin/command-surface.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Canonical Qualia command surface.
+//
+// The repo may keep retired skills for migration/history, but installs should
+// expose the small active surface below. This gives users fewer commands while
+// preserving compatibility cleanup for older installs.
+
+const ACTIVE_SKILLS = [
+  "qualia",
+  "qualia-new",
+  "qualia-discuss",
+  "qualia-map",
+  "qualia-research",
+  "qualia-plan",
+  "qualia-build",
+  "qualia-verify",
+  "qualia-fix",
+  "qualia-feature",
+  "qualia-review",
+  "qualia-optimize",
+  "qualia-polish",
+  "qualia-test",
+  "qualia-milestone",
+  "qualia-ship",
+  "qualia-handoff",
+  "qualia-report",
+  "qualia-doctor",
+  "qualia-road",
+  "qualia-learn",
+  "qualia-postmortem",
+  "zoho-workflow",
+];
+
+const RETIRED_SKILLS = [
+  // Historical folds.
+  "qualia-task",
+  "qualia-quick",
+  "qualia-polish-loop",
+  "qualia-design",
+  "qualia-prd",
+
+  // v6.3 surface reduction: keep the behavior under sharper active commands.
+  "qualia-debug",      // folded into qualia-fix for actionable repairs
+  "qualia-vibe",       // folded into qualia-polish modes/documentation
+  "qualia-help",       // guide/help files remain installed; no slash command
+  "qualia-idk",        // folded into qualia router diagnostic branch
+  "qualia-pause",      // folded into qualia router handoff branch
+  "qualia-resume",     // folded into qualia router handoff branch
+  "qualia-zoom",       // folded into qualia-map/qualia-review as an analysis mode
+  "qualia-issues",     // GitHub queue externalization is not default workflow
+  "qualia-triage",     // GitHub queue routing is not default workflow
+  "qualia-hook-gen",   // framework-authoring utility, not employee default
+  "qualia-skill-new",  // framework-authoring utility, not employee default
+  "qualia-flush",      // available as qualia-framework flush / automation
+];
+
+function activeSkills() {
+  return [...ACTIVE_SKILLS];
+}
+
+function retiredSkills() {
+  return [...RETIRED_SKILLS];
+}
+
+module.exports = {
+  ACTIVE_SKILLS,
+  RETIRED_SKILLS,
+  activeSkills,
+  retiredSkills,
+};
+

package/bin/harness-eval.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// Qualia harness eval — deterministic project scoring + evidence artifact.
+//
+// This is the mechanical layer above trust-score and contract-runner. It writes
+// one JSON/Markdown artifact that can be attached to reports, snapshots, and
+// state transitions instead of relying on a prose "looks good" verdict.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const pc = require("./plan-contract.js");
+const contractRunner = require("./contract-runner.js");
+const trust = require("./trust-score.js");
+
+function parseArgs(argv) {
+  const args = { cwd: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--run") args.run = true;
+    else if (a === "--write") args.write = true;
+    else if (a === "--no-write") args.no_write = true;
+    else if (a === "--phase") args.phase = Number(argv[++i]);
+    else if (a.startsWith("--phase=")) args.phase = Number(a.slice("--phase=".length));
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice("--cwd=".length);
+  }
+  return args;
+}
+
+function readJson(file, fallback = null) {
+  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 rel(root, file) {
+  return path.relative(root, file).replace(/\\/g, "/");
+}
+
+function stateCheck(cwd) {
+  const r = spawnSync(process.execPath, [path.join(__dirname, "state.js"), "check"], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 5000,
+  });
+  const parsed = readJsonFromString(r.stdout);
+  return {
+    ok: r.status === 0 && parsed && parsed.ok === true,
+    status: r.status,
+    stdout: r.stdout,
+    stderr: r.stderr,
+    parsed,
+  };
+}
+
+function readJsonFromString(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+function latestEval(cwd) {
+  const dir = path.join(cwd, ".planning", "evals");
+  try {
+    const files = fs.readdirSync(dir)
+      .filter((f) => /^harness-eval-.*\.json$/.test(f))
+      .map((f) => path.join(dir, f))
+      .sort();
+    if (!files.length) return null;
+    return readJson(files[files.length - 1], null);
+  } catch {
+    return null;
+  }
+}
+
+function addCheck(checks, name, weight, status, evidence, data) {
+  checks.push({
+    name,
+    weight,
+    status,
+    score: status === "pass" || status === "not_applicable" ? weight : status === "warn" ? Math.floor(weight / 2) : 0,
+    evidence,
+    ...(data && typeof data === "object" ? data : {}),
+  });
+}
+
+function verificationVerdict(text) {
+  if (!text) return "";
+  const explicit = text.match(/^result:\s*(PASS|FAIL)$/im);
+  if (explicit) return explicit[1].toLowerCase();
+  const md = text.match(/\bVerdict\b.*\b(PASS|FAIL)\b/i);
+  if (md) return md[1].toLowerCase();
+  if (/PHASE\s+PASS|ALL\s+CRITERIA\s+PASSED/i.test(text)) return "pass";
+  if (/PHASE\s+FAIL|FAILED\s+CRITERIA|GAPS\s+FOUND/i.test(text)) return "fail";
+  return "";
+}
+
+function writeArtifacts(cwd, result) {
+  const dir = path.join(cwd, ".planning", "evals");
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = result.generated_at.replace(/[:.]/g, "-");
+  const jsonPath = path.join(dir, `harness-eval-${stamp}.json`);
+  const mdPath = path.join(dir, `harness-eval-${stamp}.md`);
+  fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2) + "\n");
+  const lines = [
+    `# Harness Eval`,
+    ``,
+    `**Generated:** ${result.generated_at}`,
+    `**Phase:** ${result.phase || "n/a"}`,
+    `**Status:** ${result.status}`,
+    `**Score:** ${result.score}/100`,
+    ``,
+    `## Checks`,
+    ``,
+    `| Check | Status | Score | Evidence |`,
+    `|---|---:|---:|---|`,
+    ...result.checks.map((c) => `| ${c.name} | ${c.status} | ${c.score}/${c.weight} | ${String(c.evidence || "").replace(/\|/g, "\\|")} |`),
+    ``,
+  ];
+  fs.writeFileSync(mdPath, lines.join("\n"));
+  result.artifacts = {
+    json: rel(cwd, jsonPath),
+    markdown: rel(cwd, mdPath),
+  };
+  fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2) + "\n");
+  return result.artifacts;
+}
+
+function buildHarnessEval(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const planning = path.join(cwd, ".planning");
+  const generatedAt = options.now || new Date().toISOString();
+  const checks = [];
+
+  const state = stateCheck(cwd);
+  if (!fs.existsSync(planning)) {
+    addCheck(checks, "planning_state", 15, "fail", "No .planning directory; run /qualia-new");
+    return finalize({ cwd, generatedAt, phase: options.phase || 0, checks, statusOverride: "FAIL" }, options);
+  }
+
+  const tracking = readJson(path.join(planning, "tracking.json"), {});
+  const phase = Number(options.phase || state.parsed?.phase || tracking.phase || 0);
+  addCheck(
+    checks,
+    "planning_state",
+    15,
+    state.ok ? "pass" : "fail",
+    state.ok ? "state.js check returned ok" : "state.js check failed",
+    { state: state.parsed || null }
+  );
+
+  const ledgerResult = (() => {
+    try {
+      const stateLedger = require("./state-ledger.js");
+      return stateLedger.validate(cwd);
+    } catch (e) {
+      return { ok: false, errors: [e.message] };
+    }
+  })();
+  addCheck(
+    checks,
+    "state_ledger",
+    10,
+    ledgerResult.ok ? "pass" : "fail",
+    ledgerResult.ok ? `${ledgerResult.count || 0} hash-chained event(s)` : (ledgerResult.errors || []).join("; ")
+  );
+
+  const planPath = path.join(planning, `phase-${phase}-plan.md`);
+  const contractPath = path.join(planning, `phase-${phase}-contract.json`);
+  const hasPlan = fs.existsSync(planPath);
+  const hasContract = fs.existsSync(contractPath);
+  let loadedContract = null;
+
+  if (!hasPlan && !hasContract) {
+    addCheck(checks, "plan_contract", 20, "not_applicable", `No current phase plan/contract for phase ${phase}`);
+  } else if (!hasContract) {
+    addCheck(checks, "plan_contract", 20, "fail", `Missing ${rel(cwd, contractPath)}`);
+  } else {
+    const loaded = pc.readContractFile(contractPath);
+    loadedContract = loaded.ok ? loaded.contract : null;
+    const errors = loaded.ok ? pc.validate(loaded.contract) : [loaded.message || loaded.error];
+    const drift = hasPlan ? pc.checkDrift(contractPath, planPath) : { ok: true, drift: false };
+    const ok = loaded.ok && errors.length === 0 && !(drift.ok && drift.drift);
+    addCheck(
+      checks,
+      "plan_contract",
+      20,
+      ok ? "pass" : "fail",
+      ok ? `${rel(cwd, contractPath)} valid and in sync` : [...errors, drift.drift ? "contract drifted from plan" : ""].filter(Boolean).join("; "),
+      { contract: rel(cwd, contractPath) }
+    );
+  }
+
+  const evidencePath = path.join(planning, "evidence", `phase-${phase}-contract-run.json`);
+  let evidence = readJson(evidencePath, null);
+  if (loadedContract && options.run) {
+    evidence = contractRunner.runContract(loadedContract, { cwd });
+  }
+  if (!loadedContract) {
+    addCheck(checks, "machine_evidence", 20, "not_applicable", "No contract to execute");
+  } else if (evidence && evidence.ok === true) {
+    addCheck(checks, "machine_evidence", 20, "pass", `${rel(cwd, evidencePath)} passed ${evidence.checked || 0} check(s)`);
+  } else {
+    addCheck(
+      checks,
+      "machine_evidence",
+      20,
+      "fail",
+      evidence ? `${evidence.failed || "unknown"} failing machine check(s)` : `Missing ${rel(cwd, evidencePath)}`
+    );
+  }
+
+  const verificationPath = path.join(planning, `phase-${phase}-verification.md`);
+  const verification = readText(verificationPath, "");
+  const ieCount = (verification.match(/INSUFFICIENT EVIDENCE/g) || []).length;
+  const verdict = verificationVerdict(verification);
+  if (!verification) {
+    addCheck(checks, "verification_report", 15, "fail", `Missing ${rel(cwd, verificationPath)}`);
+  } else if (ieCount > 0) {
+    addCheck(checks, "verification_report", 15, "fail", `${ieCount} insufficient-evidence marker(s)`);
+  } else if (verdict === "pass" || verdict === "fail") {
+    addCheck(checks, "verification_report", 15, verdict === "pass" ? "pass" : "warn", `${rel(cwd, verificationPath)} verdict=${verdict}`);
+  } else {
+    addCheck(checks, "verification_report", 15, "warn", `${rel(cwd, verificationPath)} has no machine-readable verdict`);
+  }
+
+  const trustScore = trust.buildTrustScore(cwd);
+  addCheck(
+    checks,
+    "framework_trust_score",
+    10,
+    trustScore.status === "FAIL" ? "fail" : trustScore.status === "DEGRADED" ? "warn" : "pass",
+    `trust-score=${trustScore.score}/100 status=${trustScore.status}`,
+    { trust_score: trustScore.score }
+  );
+
+  const hasErpId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tracking.erp_project_id || "");
+  const hasProjectKey = !!(tracking.project_id || tracking.project);
+  addCheck(
+    checks,
+    "erp_linkage",
+    10,
+    hasErpId ? "pass" : hasProjectKey ? "warn" : "fail",
+    hasErpId ? "tracking.json has erp_project_id UUID" : hasProjectKey ? "project key exists, ERP UUID missing" : "missing project/project_id for ERP correlation"
+  );
+
+  return finalize({ cwd, generatedAt, phase, checks }, options);
+}
+
+function finalize(base, options) {
+  const score = Math.max(0, Math.min(100, base.checks.reduce((n, c) => n + (c.score || 0), 0)));
+  const failed = base.checks.filter((c) => c.status === "fail").length;
+  const warned = base.checks.filter((c) => c.status === "warn").length;
+  const status = base.statusOverride || (failed ? "FAIL" : score >= 85 ? "PASS" : warned ? "WARN" : "PASS");
+  const result = {
+    ok: status !== "FAIL",
+    status,
+    score,
+    phase: base.phase,
+    generated_at: base.generatedAt,
+    checks: base.checks,
+  };
+  if (options.write && !options.no_write && fs.existsSync(path.join(base.cwd, ".planning"))) {
+    writeArtifacts(base.cwd, result);
+  }
+  return result;
+}
+
+function printHuman(result) {
+  console.log(`Harness eval: ${result.score}/100 (${result.status})`);
+  for (const c of result.checks) {
+    console.log(`${c.name}: ${c.status} (${c.score}/${c.weight}) — ${c.evidence}`);
+  }
+  if (result.artifacts) {
+    console.log(`Artifacts: ${result.artifacts.json}, ${result.artifacts.markdown}`);
+  }
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const result = buildHarnessEval(args);
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else printHuman(result);
+  return result.ok ? 0 : 1;
+}
+
+module.exports = {
+  buildHarnessEval,
+  latestEval,
+  verificationVerdict,
+};
+
+if (require.main === module) process.exit(main(process.argv));
+