qualia-framework 6.2.9 → 6.2.10

package/bin/plan-contract.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // Plan contract validator + helpers. See docs/plan-contract.md.
 //
-// Pure library — no CLI dispatch. Required by state.js and by skills that
-// emit/consume `.planning/phase-{N}-contract.json`.
+// Library + tiny CLI. Required by state.js and by skills that emit/consume
+// `.planning/phase-{N}-contract.json`.
 //
 // Zero npm dependencies. Hand-rolled validator, ~100 LOC.
 
@@ -241,11 +241,108 @@ function checkDrift(contractPath, planMdPath) {
   return { ok: true, drift: stored !== current, stored, current };
 }
 
+function readContractFile(contractPath) {
+  if (!fs.existsSync(contractPath)) {
+    return { ok: false, error: "CONTRACT_MISSING", message: `Contract file not found: ${contractPath}` };
+  }
+  const parsed = parseSafely(fs.readFileSync(contractPath, "utf8"));
+  if (!parsed.ok) {
+    return { ok: false, error: "CONTRACT_UNPARSEABLE", message: parsed.error };
+  }
+  return { ok: true, contract: parsed.value };
+}
+
+function cliUsage() {
+  console.error([
+    "Usage:",
+    "  plan-contract.js validate <contract.json> [--json]",
+    "  plan-contract.js drift <contract.json> <plan.md> [--json]",
+    "  plan-contract.js hash <plan.md>",
+  ].join("\n"));
+}
+
+function printResult(payload, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (payload.ok) {
+    if (payload.action === "validate") console.log(`VALID ${payload.path}`);
+    else if (payload.action === "drift") console.log(payload.drift ? "DRIFT" : "NO_DRIFT");
+    else if (payload.action === "hash") console.log(payload.hash);
+    else console.log("OK");
+    return;
+  }
+  console.error(`${payload.error || "ERROR"}: ${payload.message || (payload.errors || []).join("; ")}`);
+}
+
+function main(argv) {
+  const cmd = argv[2];
+  const asJson = argv.includes("--json");
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    cliUsage();
+    return 2;
+  }
+
+  if (cmd === "validate") {
+    const contractPath = argv[3];
+    if (!contractPath || contractPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    const loaded = readContractFile(contractPath);
+    if (!loaded.ok) {
+      printResult({ ok: false, action: "validate", path: contractPath, ...loaded }, asJson);
+      return 2;
+    }
+    const errors = validate(loaded.contract);
+    const payload = { ok: errors.length === 0, action: "validate", path: contractPath, errors };
+    printResult(payload, asJson);
+    return payload.ok ? 0 : 1;
+  }
+
+  if (cmd === "drift") {
+    const contractPath = argv[3];
+    const planPath = argv[4];
+    if (!contractPath || !planPath || contractPath.startsWith("--") || planPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    const result = checkDrift(contractPath, planPath);
+    const payload = { ok: !!result.ok && !result.drift, action: "drift", path: contractPath, plan: planPath, ...result };
+    printResult(payload, asJson);
+    return payload.ok ? 0 : 1;
+  }
+
+  if (cmd === "hash") {
+    const planPath = argv[3];
+    if (!planPath || planPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    if (!fs.existsSync(planPath)) {
+      printResult({ ok: false, action: "hash", error: "PLAN_MISSING", message: `Plan file not found: ${planPath}` }, asJson);
+      return 2;
+    }
+    const hash = hashPlan(fs.readFileSync(planPath, "utf8"));
+    printResult({ ok: true, action: "hash", path: planPath, hash }, asJson);
+    return 0;
+  }
+
+  cliUsage();
+  return 2;
+}
+
 module.exports = {
   SCHEMA_VERSION,
   validate,
   parseSafely,
   hashPlan,
   checkDrift,
+  readContractFile,
   findScopeReductionPhrases,
 };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/planning-hygiene.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// Scan and organize `.planning/` so project state stays navigable.
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT_EXACT = new Set([
+  "PROJECT.md",
+  "PRODUCT.md",
+  "DESIGN.md",
+  "CONTEXT.md",
+  "JOURNEY.md",
+  "ROADMAP.md",
+  "REQUIREMENTS.md",
+  "STATE.md",
+  "tracking.json",
+  "project-discovery.md",
+  "agent-runs.jsonl",
+]);
+
+const ROOT_PATTERNS = [
+  /^phase-\d+(-gaps)?-plan\.md$/,
+  /^phase-\d+-contract\.json$/,
+  /^phase-\d+-verification\.md$/,
+  /^phase-\d+-context\.md$/,
+  /^phase-\d+-research\.md$/,
+  /^phase-\d+-postmortem\.md$/,
+  /^phase-\d+-deviations\.json$/,
+];
+
+const ALLOWED_DIRS = new Set([
+  "archive",
+  "assets",
+  "agent-runs",
+  "decisions",
+  "design",
+  "evidence",
+  "reports",
+  "research",
+  "snapshots",
+]);
+
+function usage() {
+  return `planning-hygiene.js — keep .planning organized
+
+Usage:
+  node planning-hygiene.js scan [--json] [--planning-dir .planning]
+  node planning-hygiene.js organize --write [--planning-dir .planning]
+
+scan is read-only. organize requires --write and only moves loose artifacts.`;
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    command: args.find((arg) => !arg.startsWith("-")) || "scan",
+    json: args.includes("--json"),
+    write: args.includes("--write"),
+    planningDir: ".planning",
+  };
+
+  const dirIndex = args.indexOf("--planning-dir");
+  if (dirIndex !== -1 && args[dirIndex + 1]) {
+    opts.planningDir = args[dirIndex + 1];
+  }
+
+  if (args.includes("-h") || args.includes("--help")) {
+    opts.help = true;
+  }
+
+  return opts;
+}
+
+function isAllowedRootFile(name) {
+  return ROOT_EXACT.has(name) || ROOT_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+function routeForLooseFile(name) {
+  if (/^DEBUG-\d{4}-\d{2}-\d{2}/.test(name)) return path.join("reports", "debug", name);
+  if (/^FIX-\d{4}-\d{2}-\d{2}/.test(name)) return path.join("reports", "fix", name);
+  if (name === "REVIEW.md" || /^REVIEW-/.test(name)) return path.join("reports", "review", name);
+  if (name === "OPTIMIZE.md" || /^OPTIMIZE-/.test(name)) return path.join("reports", "optimize", name);
+  if (/^REFACTOR-/.test(name)) return path.join("reports", "refactor", name);
+  if (/^polish-critique-/.test(name)) return path.join("reports", "polish", name);
+  if (/^vibe-after\./.test(name)) return path.join("assets", "vibe", name);
+  if (name === "DESIGN-extracted.md") return path.join("design", name);
+  return path.join("archive", "loose", name);
+}
+
+function listPlanningRoot(planningDir) {
+  if (!fs.existsSync(planningDir)) {
+    return { exists: false, entries: [] };
+  }
+  const entries = fs.readdirSync(planningDir, { withFileTypes: true })
+    .filter((entry) => entry.name !== ".DS_Store")
+    .map((entry) => ({
+      name: entry.name,
+      type: entry.isDirectory() ? "dir" : "file",
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return { exists: true, entries };
+}
+
+function scan(planningDir) {
+  const root = listPlanningRoot(planningDir);
+  if (!root.exists) {
+    return {
+      ok: false,
+      planning_dir: planningDir,
+      status: "missing",
+      loose: [],
+      unknown_dirs: [],
+      message: ".planning directory not found",
+    };
+  }
+
+  const loose = [];
+  const unknownDirs = [];
+
+  for (const entry of root.entries) {
+    if (entry.type === "dir") {
+      if (!ALLOWED_DIRS.has(entry.name)) {
+        unknownDirs.push({
+          path: entry.name,
+          suggested_path: path.join("archive", "loose", entry.name),
+        });
+      }
+      continue;
+    }
+
+    if (!isAllowedRootFile(entry.name)) {
+      loose.push({
+        path: entry.name,
+        suggested_path: routeForLooseFile(entry.name),
+      });
+    }
+  }
+
+  return {
+    ok: loose.length === 0 && unknownDirs.length === 0,
+    planning_dir: planningDir,
+    status: loose.length === 0 && unknownDirs.length === 0 ? "clean" : "needs_organizing",
+    loose,
+    unknown_dirs: unknownDirs,
+  };
+}
+
+function uniqueDestination(planningDir, relPath) {
+  const parsed = path.parse(relPath);
+  let candidate = relPath;
+  let index = 2;
+  while (fs.existsSync(path.join(planningDir, candidate))) {
+    candidate = path.join(parsed.dir, `${parsed.name}-${index}${parsed.ext}`);
+    index += 1;
+  }
+  return candidate;
+}
+
+function moveEntry(planningDir, fromRel, toRel) {
+  const from = path.join(planningDir, fromRel);
+  const safeToRel = uniqueDestination(planningDir, toRel);
+  const to = path.join(planningDir, safeToRel);
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+  return safeToRel;
+}
+
+function organize(planningDir, write) {
+  const result = scan(planningDir);
+  if (!result.ok && result.status === "missing") {
+    return result;
+  }
+
+  const moves = [];
+  for (const item of [...result.loose, ...result.unknown_dirs]) {
+    if (!write) {
+      moves.push({ from: item.path, to: item.suggested_path, moved: false });
+      continue;
+    }
+    const actual = moveEntry(planningDir, item.path, item.suggested_path);
+    moves.push({ from: item.path, to: actual, moved: true });
+  }
+
+  return {
+    ok: true,
+    planning_dir: planningDir,
+    status: write ? "organized" : "dry_run",
+    moves,
+  };
+}
+
+function printHuman(result) {
+  if (result.status === "missing") {
+    console.log(`planning hygiene: ${result.message}`);
+    return;
+  }
+
+  if (result.status === "clean") {
+    console.log(`planning hygiene: clean (${result.planning_dir})`);
+    return;
+  }
+
+  if (result.moves) {
+    console.log(`planning hygiene: ${result.status} (${result.moves.length} move${result.moves.length === 1 ? "" : "s"})`);
+    for (const move of result.moves) {
+      console.log(`  ${move.moved ? "moved" : "would move"} ${move.from} -> ${move.to}`);
+    }
+    return;
+  }
+
+  const count = result.loose.length + result.unknown_dirs.length;
+  console.log(`planning hygiene: needs organizing (${count} item${count === 1 ? "" : "s"})`);
+  for (const item of result.loose) {
+    console.log(`  loose file ${item.path} -> ${item.suggested_path}`);
+  }
+  for (const item of result.unknown_dirs) {
+    console.log(`  loose dir  ${item.path} -> ${item.suggested_path}`);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.help) {
+    console.log(usage());
+    return 0;
+  }
+
+  let result;
+  if (opts.command === "scan") {
+    result = scan(opts.planningDir);
+  } else if (opts.command === "organize" || opts.command === "fix") {
+    result = organize(opts.planningDir, opts.write);
+  } else {
+    console.error(usage());
+    return 2;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+
+  if (result.status === "missing") return 1;
+  if (opts.command === "scan" && !result.ok) return 1;
+  return 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main();
+}
+
+module.exports = {
+  ALLOWED_DIRS,
+  ROOT_EXACT,
+  ROOT_PATTERNS,
+  isAllowedRootFile,
+  routeForLooseFile,
+  scan,
+  organize,
+};

package/bin/runtime-manifest.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Shared runtime manifest for installed Qualia bin scripts.
+
+const RUNTIME_BIN_SCRIPTS = [
+  { file: "runtime-manifest.js", label: "runtime-manifest.js (shared install 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)" },
+  { file: "statusline.js", label: "statusline.js (status bar renderer)" },
+  { file: "knowledge.js", label: "knowledge.js (memory-layer loader)" },
+  { file: "knowledge-flush.js", label: "knowledge-flush.js (cron-runnable flush)" },
+  { file: "state-ledger.js", label: "state-ledger.js (hash-chained state event ledger)" },
+  { file: "plan-contract.js", label: "plan-contract.js (plan JSON validator)" },
+  { file: "contract-runner.js", label: "contract-runner.js (contract evidence runner)" },
+  { 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: "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: "codex-goal.js", label: "codex-goal.js (Codex /goal objective + token-budget suggester)" },
+  { file: "planning-hygiene.js", label: "planning-hygiene.js (.planning organization scanner)" },
+];
+
+function binFiles() {
+  return RUNTIME_BIN_SCRIPTS.map((script) => script.file);
+}
+
+module.exports = {
+  RUNTIME_BIN_SCRIPTS,
+  binFiles,
+};

package/bin/state-ledger.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// State ledger — append-only, hash-chained events for Qualia state mutations.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+
+function qualiaDir(cwd = process.cwd()) {
+  return path.join(cwd, ".planning", "qualia");
+}
+
+function ledgerPath(cwd = process.cwd()) {
+  return path.join(qualiaDir(cwd), "state.jsonl");
+}
+
+function ensureDir(p) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = stable(value[key]);
+    return out;
+  }
+  return value;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stable(value));
+}
+
+function hash(value) {
+  return `sha256:${crypto.createHash("sha256").update(String(value)).digest("hex")}`;
+}
+
+function hashContent(content) {
+  if (content == null) return null;
+  return hash(content);
+}
+
+function newEventId() {
+  const ts = Date.now().toString(36).toUpperCase().padStart(10, "0");
+  const rand = crypto.randomBytes(6).toString("hex").toUpperCase();
+  return `${ts}${rand}`;
+}
+
+function readEvents(cwd = process.cwd()) {
+  const file = ledgerPath(cwd);
+  if (!fs.existsSync(file)) return [];
+  const events = [];
+  for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean)) {
+    try { events.push(JSON.parse(line)); } catch {}
+  }
+  return events;
+}
+
+function lastEvent(cwd = process.cwd()) {
+  const events = readEvents(cwd);
+  return events.length ? events[events.length - 1] : null;
+}
+
+function actor() {
+  return process.env.QUALIA_ACTOR ||
+    process.env.CLAUDE_USER_NAME ||
+    process.env.USER ||
+    process.env.USERNAME ||
+    "unknown";
+}
+
+function compactState(state) {
+  if (!state) return null;
+  return {
+    phase: state.phase,
+    status: state.status,
+    phase_name: state.phase_name,
+    total_phases: state.total_phases,
+  };
+}
+
+function compactTracking(tracking) {
+  if (!tracking) return null;
+  return {
+    project: tracking.project,
+    phase: tracking.phase,
+    status: tracking.status,
+    milestone: tracking.milestone,
+    milestone_name: tracking.milestone_name,
+    tasks_done: tracking.tasks_done,
+    tasks_total: tracking.tasks_total,
+    verification: tracking.verification,
+    report_seq: tracking.report_seq,
+  };
+}
+
+function eventHash(event) {
+  const clean = { ...event };
+  delete clean.event_hash;
+  return hash(stableJson(clean));
+}
+
+function append(cwd, input) {
+  const previous = lastEvent(cwd);
+  const event = {
+    schema_version: SCHEMA_VERSION,
+    event_id: input.event_id || newEventId(),
+    timestamp: input.timestamp || new Date().toISOString(),
+    actor: input.actor || actor(),
+    command: input.command || "",
+    action: input.action,
+    result: input.result || "success",
+    phase_before: input.phase_before,
+    phase_after: input.phase_after,
+    status_before: input.status_before,
+    status_after: input.status_after,
+    state_before: compactState(input.state_before),
+    state_after: compactState(input.state_after),
+    tracking_before: compactTracking(input.tracking_before),
+    tracking_after: compactTracking(input.tracking_after),
+    state_hash_before: hashContent(input.state_raw_before),
+    state_hash_after: hashContent(input.state_raw_after),
+    tracking_hash_before: hashContent(input.tracking_raw_before),
+    tracking_hash_after: hashContent(input.tracking_raw_after),
+    evidence_refs: Array.isArray(input.evidence_refs) ? input.evidence_refs : [],
+    previous_event_hash: previous ? previous.event_hash : null,
+  };
+
+  for (const key of Object.keys(event)) {
+    if (event[key] === undefined) delete event[key];
+  }
+  event.event_hash = eventHash(event);
+
+  ensureDir(qualiaDir(cwd));
+  fs.appendFileSync(ledgerPath(cwd), JSON.stringify(event) + "\n");
+  return { ok: true, event_id: event.event_id, event_hash: event.event_hash };
+}
+
+function validate(cwd = process.cwd()) {
+  const events = readEvents(cwd);
+  const errors = [];
+  let previousHash = null;
+  events.forEach((event, index) => {
+    if (event.previous_event_hash !== previousHash) {
+      errors.push(`event ${index + 1}: previous_event_hash mismatch`);
+    }
+    const expected = eventHash(event);
+    if (event.event_hash !== expected) {
+      errors.push(`event ${index + 1}: event_hash mismatch`);
+    }
+    previousHash = event.event_hash || null;
+  });
+  return { ok: errors.length === 0, count: events.length, errors };
+}
+
+function main(argv) {
+  const cmd = argv[2] || "validate";
+  if (cmd === "validate") {
+    const result = validate(process.cwd());
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+  if (cmd === "tail") {
+    const limit = parseInt(argv[3] || "10", 10);
+    console.log(JSON.stringify(readEvents(process.cwd()).slice(-limit), null, 2));
+    return 0;
+  }
+  console.error("Usage: state-ledger.js <validate|tail> [limit]");
+  return 2;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  append,
+  validate,
+  readEvents,
+  ledgerPath,
+  hash,
+  stableJson,
+};
+
+if (require.main === module) process.exit(main(process.argv));