qualia-framework 6.2.7 → 6.2.10

package/bin/codex-goal.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// codex-goal — suggest a Codex /goal objective + token budget from current
+// .planning/STATE.md + ROADMAP.md state.
+//
+// Output is a single line meant to be pasted into a Codex session, or quoted
+// in an agent prompt that will then issue update_goal itself. The framework
+// does NOT write directly to ~/.codex/goals_1.sqlite — Codex owns the schema
+// and the thread_id; the /goal slash command (and the update_goal tool the
+// model can call) are the stable interfaces.
+//
+// Usage: node bin/codex-goal.js [phase|task|feature|quick]
+//        default scope = phase
+
+const fs = require("fs");
+const path = require("path");
+
+const SCOPE = (process.argv[2] || "phase").toLowerCase();
+
+// Token budgets are calibrated to Codex's per-thread context window and the
+// typical Qualia work-unit size. Phase = full builder loop with verification.
+// Task/feature = single fresh-context spawn. Quick = one-shot inline edit.
+const TOKEN_BUDGETS = {
+  phase: 80000,
+  task: 30000,
+  feature: 30000,
+  quick: 10000,
+};
+
+const PLANNING = path.join(process.cwd(), ".planning");
+const STATE_FILE = path.join(PLANNING, "STATE.md");
+const ROADMAP_FILE = path.join(PLANNING, "ROADMAP.md");
+
+function readSafe(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
+}
+
+function parseState(content) {
+  if (!content) return null;
+  const phaseMatch = content.match(/^Phase:\s*(\d+)\s+of\s+(\d+)\s*[—-]\s*(.+?)\r?$/m);
+  if (!phaseMatch) return null;
+  return {
+    phase: parseInt(phaseMatch[1], 10),
+    total: parseInt(phaseMatch[2], 10),
+    name: phaseMatch[3].trim(),
+  };
+}
+
+function readPhaseGoal(roadmap, phaseNum) {
+  if (!roadmap) return "";
+  // Match a heading like "## Phase 2 — Name" or "## Phase 2: Name", then
+  // grab the "Goal:" line that follows.
+  const heading = new RegExp(`##\\s*Phase\\s*${phaseNum}\\s*[—:\\-]\\s*[^\\n]+`, "i");
+  const idx = roadmap.search(heading);
+  if (idx === -1) return "";
+  const body = roadmap.slice(idx, idx + 2000);
+  const goalMatch = body.match(/^\s*\*?\*?Goal:?\*?\*?\s*(.+?)$/im);
+  return goalMatch ? goalMatch[1].trim() : "";
+}
+
+function clip(s, max) {
+  return s.length <= max ? s : s.slice(0, max - 1).trimEnd() + "…";
+}
+
+function main() {
+  const budget = TOKEN_BUDGETS[SCOPE];
+  if (budget == null) {
+    process.stderr.write(`unknown scope: ${SCOPE} (use phase|task|feature|quick)\n`);
+    process.exit(2);
+  }
+
+  const state = parseState(readSafe(STATE_FILE));
+  if (!state) {
+    // No .planning/STATE.md — fall back to a generic shape so the helper
+    // still emits something useful for ad-hoc invocations.
+    const objective = `${SCOPE[0].toUpperCase() + SCOPE.slice(1)} in ${path.basename(process.cwd())}`;
+    process.stdout.write(`/goal ${objective}\n`);
+    process.stdout.write(`# token_budget suggestion: ${budget}\n`);
+    return;
+  }
+
+  const phaseGoal = readPhaseGoal(readSafe(ROADMAP_FILE), state.phase);
+  const objectivePrefix = `Phase ${state.phase}/${state.total} — ${state.name}`;
+  const objective = clip(
+    phaseGoal ? `${objectivePrefix}: ${phaseGoal}` : objectivePrefix,
+    280
+  );
+
+  process.stdout.write(`/goal ${objective}\n`);
+  process.stdout.write(`# token_budget suggestion: ${budget}\n`);
+}
+
+main();

package/bin/contract-runner.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// Execute Qualia phase contract checks and write evidence.
+// No shell interpolation: command checks run through spawnSync(argv).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const pc = require("./plan-contract.js");
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--no-write") args.no_write = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice("--cwd=".length);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  contract-runner.js <contract.json> [--cwd DIR] [--json] [--no-write]",
+    "",
+    "Runs file-exists, grep-match, command-exit, and behavioral evidence checks.",
+  ].join("\n"));
+}
+
+function rel(root, p) {
+  return path.resolve(root, p);
+}
+
+function checkFileExists(root, check) {
+  const file = rel(root, check.path);
+  if (!fs.existsSync(file)) return { ok: false, detail: `missing file: ${check.path}` };
+  if (check.must_contain != null) {
+    const content = fs.readFileSync(file, "utf8");
+    if (!content.includes(check.must_contain)) {
+      return { ok: false, detail: `file does not contain required text: ${check.path}` };
+    }
+  }
+  return { ok: true };
+}
+
+function checkGrepMatch(root, check) {
+  const file = rel(root, check.path);
+  if (!fs.existsSync(file)) return { ok: false, detail: `missing file: ${check.path}` };
+  const content = fs.readFileSync(file, "utf8");
+  const re = new RegExp(check.pattern);
+  const present = re.test(content);
+  if (check.expect === "present" && !present) return { ok: false, detail: `pattern absent: ${check.pattern}` };
+  if (check.expect === "absent" && present) return { ok: false, detail: `pattern present: ${check.pattern}` };
+  return { ok: true };
+}
+
+function checkCommandExit(root, check) {
+  const started = Date.now();
+  const r = spawnSync(check.command, check.args || [], {
+    cwd: root,
+    encoding: "utf8",
+    timeout: check.timeout_ms || 30_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+  });
+  const status = typeof r.status === "number" ? r.status : 1;
+  if (status !== check.expected_exit) {
+    return {
+      ok: false,
+      detail: `exit ${status}, expected ${check.expected_exit}`,
+      duration_ms: Date.now() - started,
+      stdout: (r.stdout || "").slice(-1000),
+      stderr: (r.stderr || r.error?.message || "").slice(-1000),
+    };
+  }
+  if (check.expect_stdout_match != null) {
+    const re = new RegExp(check.expect_stdout_match);
+    if (!re.test(r.stdout || "")) {
+      return {
+        ok: false,
+        detail: `stdout did not match: ${check.expect_stdout_match}`,
+        duration_ms: Date.now() - started,
+        stdout: (r.stdout || "").slice(-1000),
+        stderr: (r.stderr || "").slice(-1000),
+      };
+    }
+  }
+  return {
+    ok: true,
+    duration_ms: Date.now() - started,
+    stdout: (r.stdout || "").slice(-1000),
+    stderr: (r.stderr || "").slice(-1000),
+  };
+}
+
+function checkBehavioral(root, check) {
+  for (const ev of check.evidence_required || []) {
+    const file = rel(root, ev.path);
+    if (!fs.existsSync(file)) {
+      return { ok: false, detail: `missing evidence file: ${ev.path}` };
+    }
+    if (ev.matcher != null) {
+      const content = fs.readFileSync(file, "utf8");
+      const re = new RegExp(ev.matcher);
+      if (!re.test(content)) {
+        return { ok: false, detail: `evidence matcher failed for ${ev.path}: ${ev.matcher}` };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+function runCheck(root, check) {
+  try {
+    if (check.type === "file-exists") return checkFileExists(root, check);
+    if (check.type === "grep-match") return checkGrepMatch(root, check);
+    if (check.type === "command-exit") return checkCommandExit(root, check);
+    if (check.type === "behavioral") return checkBehavioral(root, check);
+    return { ok: false, detail: `unknown check type: ${check.type}` };
+  } catch (e) {
+    return { ok: false, detail: e.message };
+  }
+}
+
+function writeEvidence(root, contract, result) {
+  const dir = path.join(root, ".planning", "evidence");
+  fs.mkdirSync(dir, { recursive: true });
+  const phase = Number(contract.phase || 0) || "unknown";
+  const file = path.join(dir, `phase-${phase}-contract-run.json`);
+  fs.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+  return path.relative(root, file);
+}
+
+function runContract(contract, opts = {}) {
+  const root = path.resolve(opts.cwd || process.cwd());
+  const errors = pc.validate(contract);
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      error: "CONTRACT_INVALID",
+      errors,
+      checked: 0,
+      failed: errors.length,
+      results: [],
+    };
+  }
+
+  const results = [];
+  for (const task of contract.tasks || []) {
+    for (let i = 0; i < (task.verification || []).length; i++) {
+      const check = task.verification[i];
+      const r = runCheck(root, check);
+      results.push({
+        task_id: task.id,
+        task_title: task.title,
+        index: i,
+        type: check.type,
+        ok: !!r.ok,
+        detail: r.detail || "",
+        duration_ms: r.duration_ms,
+        stdout: r.stdout,
+        stderr: r.stderr,
+      });
+    }
+  }
+  const failed = results.filter((r) => !r.ok).length;
+  const payload = {
+    ok: failed === 0,
+    phase: contract.phase,
+    goal: contract.goal,
+    checked: results.length,
+    failed,
+    generated_at: new Date().toISOString(),
+    results,
+  };
+  if (!opts.no_write) payload.evidence_file = writeEvidence(root, contract, payload);
+  return payload;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const contractPath = args._[0];
+  if (!contractPath || contractPath === "--help" || contractPath === "-h") {
+    usage();
+    return 2;
+  }
+  const loaded = pc.readContractFile(contractPath);
+  if (!loaded.ok) {
+    const payload = { ok: false, ...loaded, path: contractPath };
+    if (args.json) console.log(JSON.stringify(payload, null, 2));
+    else console.error(`${payload.error}: ${payload.message}`);
+    return 2;
+  }
+  const result = runContract(loaded.contract, {
+    cwd: args.cwd,
+    no_write: args.no_write,
+  });
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log(`PASS phase ${result.phase}: ${result.checked} check(s)`);
+    if (result.evidence_file) console.log(`Evidence: ${result.evidence_file}`);
+  } else {
+    console.error(`FAIL phase ${result.phase || "?"}: ${result.failed} of ${result.checked || result.failed} check(s) failed`);
+    for (const r of result.results || []) {
+      if (!r.ok) console.error(`- ${r.task_id} ${r.type}: ${r.detail}`);
+    }
+    if (result.error) for (const e of result.errors || []) console.error(`- ${e}`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+module.exports = { runContract, runCheck };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/host-adapters.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Host adapter rendering for installed Qualia text surfaces.
+
+const path = require("path");
+const os = require("os");
+
+const HOSTS = {
+  claude: {
+    name: "Claude Code",
+    home: path.join(os.homedir(), ".claude"),
+  },
+  codex: {
+    name: "OpenAI Codex",
+    home: path.join(os.homedir(), ".codex"),
+  },
+};
+
+function adapter(name) {
+  const host = HOSTS[name];
+  if (!host) throw new Error(`Unknown Qualia host adapter: ${name}`);
+  const home = host.home;
+  return {
+    ...host,
+    tokens: {
+      QUALIA_HOME: home,
+      QUALIA_BIN: `${home}/bin`,
+      QUALIA_AGENTS: `${home}/agents`,
+      QUALIA_SKILLS: `${home}/skills`,
+      QUALIA_RULES: `${home}/rules`,
+      QUALIA_TEMPLATES: `${home}/qualia-templates`,
+      QUALIA_KNOWLEDGE: `${home}/knowledge`,
+      QUALIA_REFERENCES: `${home}/qualia-references`,
+      QUALIA_DESIGN: `${home}/qualia-design`,
+    },
+  };
+}
+
+function renderText(content, hostName) {
+  const host = adapter(hostName);
+  let out = String(content);
+  for (const [token, value] of Object.entries(host.tokens)) {
+    out = out.replaceAll(`\${${token}}`, value);
+  }
+
+  // Backward-compatible rendering while source files migrate from hardcoded
+  // Claude paths to explicit ${QUALIA_*} tokens.
+  out = out
+    .replaceAll("~/.claude/", `${host.home}/`)
+    .replaceAll("$HOME/.claude/", `${host.home}/`)
+    .replaceAll("${HOME}/.claude/", `${host.home}/`)
+    .replaceAll("@~/.claude/", `@${host.home}/`)
+    .replaceAll(".claude/", `${path.basename(host.home)}/`);
+
+  if (hostName === "codex") {
+    out = out
+      .replaceAll("Claude Code", "Codex")
+      .replaceAll("Claude's", "Codex's");
+  }
+  return out;
+}
+
+module.exports = {
+  HOSTS,
+  adapter,
+  renderText,
+};