qualia-framework 6.2.9 → 6.2.10

package/bin/state.js

@@ -4,6 +4,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const stateLedger = require("./state-ledger.js");
 
 const PLANNING = ".planning";
 const STATE_FILE = path.join(PLANNING, "STATE.md");
@@ -191,6 +192,22 @@ function readTracking() {
   }
 }
 
+function readTrackingRaw() {
+  try {
+    return fs.readFileSync(TRACKING_FILE, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function parseTrackingRaw(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
 function writeTracking(t) {
   atomicWrite(TRACKING_FILE, JSON.stringify(t, null, 2) + "\n");
 }
@@ -484,6 +501,18 @@ function fail(error, message) {
   return { ok: false, error, message };
 }
 
+function recordLedgerEvent(meta) {
+  try {
+    return stateLedger.append(process.cwd(), {
+      command: `state.js ${process.argv.slice(2).join(" ")}`.trim(),
+      ...meta,
+    });
+  } catch (err) {
+    try { _trace("state-ledger", "error", { action: meta && meta.action, error: err.message }); } catch {}
+    return { ok: false, error: err.message };
+  }
+}
+
 // ─── Next Command Logic ──────────────────────────────────
 function nextCommand(status, phase, totalPhases, verification) {
   switch (status) {
@@ -687,8 +716,10 @@ function cmdTransition(opts) {
   const target = opts.to;
   if (!target) return output(fail("MISSING_ARG", "--to is required"));
 
-  const t = readTracking();
-  const s = parseStateMd(readState());
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
+  const t = parseTrackingRaw(beforeTrackingRaw);
+  const s = parseStateMd(beforeStateRaw);
   if (!t || !s) {
     return output(fail("NO_PROJECT", "No .planning/ found. Run /qualia-new."));
   }
@@ -705,7 +736,31 @@ function cmdTransition(opts) {
 
   // Note/activity short-circuit (no status change, no precondition check)
   const noteResult = applyNoteOrActivity(target, s, t, opts);
-  if (noteResult) return output(noteResult);
+  if (noteResult) {
+    const ledger = recordLedgerEvent({
+      action: target,
+      phase_before: s.phase,
+      phase_after: s.phase,
+      status_before: s.status,
+      status_after: s.status,
+      state_before: s,
+      state_after: s,
+      tracking_before: parseTrackingRaw(beforeTrackingRaw),
+      tracking_after: t,
+      state_raw_before: beforeStateRaw,
+      state_raw_after: readState(),
+      tracking_raw_before: beforeTrackingRaw,
+      tracking_raw_after: readTrackingRaw(),
+      evidence_refs: opts.evidence ? [opts.evidence] : [],
+    });
+    if (ledger.ok) {
+      noteResult.ledger_event_id = ledger.event_id;
+      noteResult.ledger_event_hash = ledger.event_hash;
+    } else {
+      noteResult.ledger_error = ledger.error;
+    }
+    return output(noteResult);
+  }
 
   const phase = parseInt(opts.phase) || s.phase;
 
@@ -746,6 +801,23 @@ function cmdTransition(opts) {
   const writeError = commitTransitionAtomic(s, t);
   if (writeError) return output(writeError);
 
+  const ledger = recordLedgerEvent({
+    action: target,
+    phase_before: phase,
+    phase_after: s.phase,
+    status_before: prevStatus,
+    status_after: s.status,
+    state_before: parseStateMd(beforeStateRaw),
+    state_after: s,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+    evidence_refs: opts.evidence ? [opts.evidence] : [],
+  });
+
   // Trace transition for analytics
   _trace("state-transition", "allow", {
     phase: s.phase,
@@ -755,7 +827,7 @@ function cmdTransition(opts) {
     gap_closure: prevStatus === "verified" && target === "planned",
   });
 
-  output({
+  const result = {
     ok: true,
     phase: s.phase,
     phase_name: s.phase_name,
@@ -764,7 +836,14 @@ function cmdTransition(opts) {
     verification: t.verification,
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
     next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification),
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 function cmdInit(opts) {
@@ -825,6 +904,8 @@ function cmdInit(opts) {
   const date = now.split("T")[0];
 
   // Read existing tracking for lifetime data preservation across milestone resets
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const prev = readTracking();
   const prevLife = prev ? ensureLifetime(prev) : null;
 
@@ -906,7 +987,23 @@ function cmdInit(opts) {
   writeStateMd(s);
   writeTracking(t);
 
-  output({
+  const ledger = recordLedgerEvent({
+    action: "init",
+    phase_before: null,
+    phase_after: 1,
+    status_before: null,
+    status_after: "setup",
+    state_before: parseStateMd(beforeStateRaw),
+    state_after: s,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+  });
+
+  const result = {
     ok: true,
     action: "init",
     project: opts.project,
@@ -914,10 +1011,19 @@ function cmdInit(opts) {
     total_phases: totalPhases,
     status: "setup",
     next_command: "/qualia-plan 1",
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 function cmdFix(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const raw = readState();
   const t = readTracking();
   if (!raw && !t) {
@@ -980,17 +1086,41 @@ function cmdFix(opts) {
     return output(fail("WRITE_ERROR", e.message));
   }
 
-  output({
+  const ledger = recordLedgerEvent({
+    action: "fix",
+    phase_before: parsed.phase,
+    phase_after: s.phase,
+    status_before: parsed.status,
+    status_after: s.status,
+    state_before: parsed,
+    state_after: s,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+  });
+
+  const result = {
     ok: true,
     action: "fix",
     previous_errors: previousErrors,
     fixed: true,
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 function cmdValidatePlan(opts) {
   const phase = parseInt(opts.phase) || 1;
   const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
+  const contractFile = path.join(PLANNING, `phase-${phase}-contract.json`);
 
   if (!fs.existsSync(planFile)) {
     return output(fail("MISSING_FILE", `Plan file not found: ${planFile}`));
@@ -1036,6 +1166,47 @@ function cmdValidatePlan(opts) {
   const warnings = [];
   const VALID_CHECK_TYPES = ["file-exists", "grep-match", "command-exit", "behavioral"];
   let contractCount = 0;
+  let contractStatus = "missing";
+  let contractErrors = [];
+
+  // JSON contracts are the new machine-readable trust layer. Keep missing
+  // contracts as a warning by default for in-flight legacy projects; callers can
+  // opt into the hard gate with --require-contract.
+  try {
+    const pc = require("./plan-contract.js");
+    if (fs.existsSync(contractFile)) {
+      const loaded = pc.readContractFile(contractFile);
+      if (!loaded.ok) {
+        contractStatus = "invalid";
+        contractErrors = [loaded.message || loaded.error || "contract unreadable"];
+      } else {
+        contractErrors = pc.validate(loaded.contract);
+        const drift = pc.checkDrift(contractFile, planFile);
+        if (contractErrors.length > 0) {
+          contractStatus = "invalid";
+        } else if (drift.ok && drift.drift) {
+          contractStatus = "drifted";
+          contractErrors = [`source_plan_hash drift: stored ${drift.stored}, current ${drift.current}`];
+        } else {
+          contractStatus = "valid";
+          contractCount = Array.isArray(loaded.contract.tasks) ? loaded.contract.tasks.length : 0;
+        }
+      }
+    }
+  } catch (e) {
+    contractStatus = "unavailable";
+    contractErrors = [e.message];
+  }
+
+  if (contractStatus === "missing") {
+    const msg = `JSON contract missing: ${contractFile}`;
+    if (opts.require_contract) errors.push(msg);
+    else warnings.push(msg);
+  } else if (contractStatus !== "valid") {
+    const msg = `JSON contract ${contractStatus}: ${contractErrors.join("; ")}`;
+    if (opts.require_contract) errors.push(msg);
+    else warnings.push(msg);
+  }
 
   if (/^## Verification Contract/m.test(content)) {
     // Extract the contract section (from header to next ## or end of file)
@@ -1049,9 +1220,10 @@ function cmdValidatePlan(opts) {
       if (nextH2 !== -1) contractSection = contractSection.substring(0, nextH2);
       // Each contract starts with ### Contract for Task N
       const contractBlocks = contractSection.match(/^### Contract for Task \d+/gm);
-      contractCount = contractBlocks ? contractBlocks.length : 0;
+      const markdownContractCount = contractBlocks ? contractBlocks.length : 0;
+      if (contractStatus !== "valid") contractCount = markdownContractCount;
 
-      if (contractCount === 0) {
+      if (markdownContractCount === 0) {
         warnings.push("Verification Contract section exists but contains no contract blocks (expected '### Contract for Task N')");
       } else {
         // Split into individual contract blocks for validation
@@ -1092,9 +1264,9 @@ function cmdValidatePlan(opts) {
       }
 
       // Warn if contract count < task count
-      if (taskCount > 0 && contractCount > 0 && contractCount < taskCount) {
+      if (taskCount > 0 && markdownContractCount > 0 && markdownContractCount < taskCount) {
         warnings.push(
-          `Only ${contractCount} contract(s) for ${taskCount} task(s) — not all tasks have verification contracts`
+          `Only ${markdownContractCount} Markdown contract(s) for ${taskCount} task(s) — not all tasks have verification contracts`
         );
       }
     }
@@ -1119,6 +1291,9 @@ function cmdValidatePlan(opts) {
     done_when_count: doneWhenCount,
     ac_count: acCount,
     contract_count: contractCount,
+    contract_file: contractFile,
+    contract_status: contractStatus,
+    contract_errors: contractErrors.length > 0 ? contractErrors : undefined,
     warnings: warnings.length > 0 ? warnings : undefined,
   });
 }
@@ -1129,6 +1304,8 @@ function cmdValidatePlan(opts) {
 // hiccup) does NOT double-count. To re-close a milestone deliberately, pass
 // --force.
 function cmdCloseMilestone(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const t = readTracking();
   const s = parseStateMd(readState());
   if (!t || !s) {
@@ -1252,19 +1429,44 @@ function cmdCloseMilestone(opts) {
     lifetime: t.lifetime,
   });
 
-  output({
+  const ledger = recordLedgerEvent({
+    action: "close-milestone",
+    phase_before: s.phase,
+    phase_after: s.phase,
+    status_before: s.status,
+    status_after: s.status,
+    state_before: s,
+    state_after: s,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+  });
+
+  const result = {
     ok: true,
     action: "close-milestone",
     closed_milestone: closedMilestone,
     next_milestone: t.milestone,
     lifetime: t.lifetime,
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 // ─── Backfill Lifetime ───────────────────────────────────
 // Reconstructs lifetime counters from STATE.md roadmap + plan files.
 // Safe to run multiple times (idempotent — recalculates from source).
 function cmdBackfillLifetime(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const t = readTracking();
   const s = parseStateMd(readState());
   if (!t || !s) {
@@ -1327,7 +1529,23 @@ function cmdBackfillLifetime(opts) {
     phases_scanned: s.phases.length,
   });
 
-  output({
+  const ledger = recordLedgerEvent({
+    action: "backfill-lifetime",
+    phase_before: s.phase,
+    phase_after: s.phase,
+    status_before: s.status,
+    status_after: s.status,
+    state_before: s,
+    state_after: s,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+  });
+
+  const result = {
     ok: true,
     action: "backfill-lifetime",
     previous,
@@ -1335,7 +1553,14 @@ function cmdBackfillLifetime(opts) {
     phases_scanned: s.phases.length,
     phases_completed: phasesCompleted,
     tasks_completed: tasksCompleted,
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 // ─── Backfill Milestones from JOURNEY.md ─────────────────
@@ -1353,6 +1578,8 @@ function cmdBackfillLifetime(opts) {
 // Phase counting handles ranges (`1–13` → 13), comma lists (`14, 15, 16.1–16.6` → 8),
 // and "rolling" / "—" / "-" → 0.
 function cmdBackfillMilestones(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const t = readTracking();
   if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
   ensureLifetime(t);
@@ -1507,7 +1734,24 @@ function cmdBackfillMilestones(opts) {
     lifetime: t.lifetime,
   });
 
-  output({
+  const afterState = parseStateMd(readState());
+  const ledger = recordLedgerEvent({
+    action: "backfill-milestones",
+    phase_before: afterState ? afterState.phase : undefined,
+    phase_after: afterState ? afterState.phase : undefined,
+    status_before: afterState ? afterState.status : undefined,
+    status_after: afterState ? afterState.status : undefined,
+    state_before: parseStateMd(beforeStateRaw),
+    state_after: afterState,
+    tracking_before: parseTrackingRaw(beforeTrackingRaw),
+    tracking_after: t,
+    state_raw_before: beforeStateRaw,
+    state_raw_after: readState(),
+    tracking_raw_before: beforeTrackingRaw,
+    tracking_raw_after: readTrackingRaw(),
+  });
+
+  const result = {
     ok: true,
     action: "backfill-milestones",
     added,
@@ -1515,7 +1759,14 @@ function cmdBackfillMilestones(opts) {
     closed: closedSummaries,
     open_milestone: openRow ? { num: openRow.num, name: openRow.name } : null,
     lifetime: t.lifetime,
-  });
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
 }
 
 // ─── Next Report ID ──────────────────────────────────────
@@ -1525,6 +1776,8 @@ function cmdBackfillMilestones(opts) {
 // to the ERP. If --peek is passed, the next id is returned WITHOUT
 // incrementing — useful for --dry-run previews.
 function cmdNextReportId(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
   const t = readTracking();
   if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
   ensureLifetime(t);
@@ -1536,7 +1789,33 @@ function cmdNextReportId(opts) {
     t.last_updated = new Date().toISOString();
     writeTracking(t);
   }
-  output({ ok: true, action: "next-report-id", report_id: id, report_seq: next, peeked: peek });
+  const result = { ok: true, action: "next-report-id", report_id: id, report_seq: next, peeked: peek };
+  if (!peek) {
+    const afterState = parseStateMd(readState());
+    const beforeState = parseStateMd(beforeStateRaw);
+    const ledger = recordLedgerEvent({
+      action: "next-report-id",
+      phase_before: beforeState ? beforeState.phase : undefined,
+      phase_after: afterState ? afterState.phase : undefined,
+      status_before: beforeState ? beforeState.status : undefined,
+      status_after: afterState ? afterState.status : undefined,
+      state_before: beforeState,
+      state_after: afterState,
+      tracking_before: parseTrackingRaw(beforeTrackingRaw),
+      tracking_after: t,
+      state_raw_before: beforeStateRaw,
+      state_raw_after: readState(),
+      tracking_raw_before: beforeTrackingRaw,
+      tracking_raw_after: readTrackingRaw(),
+    });
+    if (ledger.ok) {
+      result.ledger_event_id = ledger.event_id;
+      result.ledger_event_hash = ledger.event_hash;
+    } else {
+      result.ledger_error = ledger.error;
+    }
+  }
+  output(result);
 }
 
 // ─── Output ──────────────────────────────────────────────