qualia-framework 7.2.1 → 7.3.0

package/bin/qualia-doctor.js

@@ -17,6 +17,7 @@
 //   3. wiki/_export rebuilt    ≤ 2 days  (export is scheduled & running)
 //   4. export concept count    == allowed source set (export covers all concepts)
 //   5. tags:deprecated         == 0 in _export (no deprecated rows leaked out)
+//   6. doc/code coherence      docs only reference real cli.js commands + skills
 //
 // Zero-dependency. Resolves the vault from $QUALIA_MEMORY else ~/qualia-memory,
 // and the install home from $QUALIA_HOME else ~/.claude. Missing dirs surface
@@ -209,6 +210,118 @@ function gateNoDeprecated(VAULT) {
   };
 }
 
+// ── Doc/code coherence ──────────────────────────────────────────────────
+// Docs that promise a `qualia-framework <cmd>` CLI command or a `/qualia-*`
+// skill must point at one that actually exists, else a new hire follows a
+// dead reference. This gate resolves the real surface from code (cli.js switch
+// cases + command-surface.js ACTIVE_SKILLS) and flags any doc token that
+// doesn't resolve. Deterministic, filesystem-only, fail-soft if sources are
+// absent (e.g. a partial install) — it WARNs rather than crashing.
+
+const COHERENCE_DOCS = [
+  "TROUBLESHOOTING.md",
+  "README.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "docs/EMPLOYEE-QUICKSTART.md",
+  "docs/onboarding.html",
+];
+
+// Real CLI commands = the quoted labels of the top-level `switch (cmd)` cases
+// in bin/cli.js. We read the dispatch verbatim so the gate can never drift
+// from the code.
+function cliCommandSet(REPO) {
+  const file = path.join(REPO, "bin", "cli.js");
+  if (!fs.existsSync(file)) return null;
+  let txt;
+  try { txt = fs.readFileSync(file, "utf8"); } catch { return null; }
+  // Only the dispatch switch matters; bound the scan to after `switch (cmd)`.
+  const sw = txt.indexOf("switch (cmd)");
+  const body = sw >= 0 ? txt.slice(sw) : txt;
+  const set = new Set();
+  for (const m of body.matchAll(/^\s*case\s+"([a-z][a-z0-9-]*)":/gim)) {
+    set.add(m[1]);
+  }
+  return set.size ? set : null;
+}
+
+function activeSkillSet(REPO) {
+  // Prefer the canonical module; fall back to the installed copy beside us.
+  for (const candidate of [
+    path.join(REPO, "bin", "command-surface.js"),
+    path.join(__dirname, "command-surface.js"),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const mod = require(candidate);
+      const list = mod.activeSkills ? mod.activeSkills() : mod.ACTIVE_SKILLS;
+      if (Array.isArray(list) && list.length) return new Set(list);
+    } catch {}
+  }
+  return null;
+}
+
+function gateDocCoherence(REPO) {
+  const cliCmds = cliCommandSet(REPO);
+  const skills = activeSkillSet(REPO);
+  if (!cliCmds || !skills) {
+    return {
+      gate: "doc/code coherence",
+      status: "WARN",
+      detail: "cli.js or command-surface.js not found — coherence not checked",
+    };
+  }
+  const offenders = [];
+  let docsScanned = 0;
+  for (const rel of COHERENCE_DOCS) {
+    const p = path.join(REPO, rel);
+    if (!fs.existsSync(p)) continue;
+    let txt;
+    try { txt = fs.readFileSync(p, "utf8"); } catch { continue; }
+    docsScanned++;
+    // (a) `qualia-framework <cmd>` — first word after the binary name.
+    for (const m of txt.matchAll(/qualia-framework\s+([a-z][a-z0-9-]*)/g)) {
+      const cmd = m[1];
+      if (!cliCmds.has(cmd)) offenders.push(`${rel}:qualia-framework ${cmd}`);
+    }
+    // (b) `/qualia-<skill>` slash-command invocations. The leading slash must
+    // be a real command slash (boundary before it — whitespace, `(`, backtick,
+    // quote, or line start), NOT a path separator. And the token must not be a
+    // file/repo path (followed by `.`, `/`, or `:` → e.g. ./qualia-manual.html,
+    // qualia-memory.git, to/qualia-memory). This avoids false positives on the
+    // HTML file link and the knowledge-repo path in the quickstart.
+    for (const m of txt.matchAll(/(^|[\s(`'">])\/(qualia-[a-z]+)(?![a-z./:-])/gim)) {
+      const skill = m[2];
+      // `qualia` (the router) and `qualia-framework` (the CLI) are valid; the
+      // CLI binary is matched without a slash, so a bare `/qualia-framework`
+      // would be wrong — but the negative lookahead already excludes `-`.
+      if (skill === "qualia") continue;
+      if (!skills.has(skill)) offenders.push(`${rel}:/${skill}`);
+    }
+  }
+  if (docsScanned === 0) {
+    return { gate: "doc/code coherence", status: "WARN", detail: "no coherence docs present to scan" };
+  }
+  if (offenders.length === 0) {
+    return {
+      gate: "doc/code coherence",
+      status: "PASS",
+      detail: `${docsScanned} doc(s): all command/skill refs resolve`,
+    };
+  }
+  const uniq = [...new Set(offenders)];
+  return {
+    gate: "doc/code coherence",
+    status: "FAIL",
+    detail: `${uniq.length} dead ref(s): ${uniq.slice(0, 4).join(", ")}${uniq.length > 4 ? "…" : ""}`,
+  };
+}
+
+function repoRoot() {
+  // The doctor lives in <root>/bin; the docs/cli/surface sit one level up.
+  return path.dirname(__dirname);
+}
+
 function runGates() {
   const QUALIA_HOME = qualiaHome();
   const VAULT = vaultRoot();
@@ -218,6 +331,7 @@ function runGates() {
     gateExportFresh(VAULT),
     gateExportCoverage(VAULT),
     gateNoDeprecated(VAULT),
+    gateDocCoherence(repoRoot()),
   ];
 }
 
@@ -245,5 +359,5 @@ function main() {
 if (require.main === module) {
   main();
 } else {
-  module.exports = { runGates, gateDailyLog, gateFlushLog, gateExportFresh, gateExportCoverage, gateNoDeprecated, qualiaHome, vaultRoot };
+  module.exports = { runGates, gateDailyLog, gateFlushLog, gateExportFresh, gateExportCoverage, gateNoDeprecated, gateDocCoherence, repoRoot, qualiaHome, vaultRoot };
 }

package/bin/state.js

@@ -5,6 +5,9 @@
 const fs = require("fs");
 const path = require("path");
 const stateLedger = require("./state-ledger.js");
+// analyze-gate.js is loaded lazily inside checkScopeDrift() (require-in-function)
+// so a missing/broken gate file can never crash state.js at load time — the
+// scope-drift gate fails SOFT (advisory), never fail-closed on its own error.
 
 const PLANNING = ".planning";
 const STATE_FILE = path.join(PLANNING, "STATE.md");
@@ -529,7 +532,7 @@ function regenerateViews(activity) {
   }));
   t.releases = listReleases().map((r) => ({ id: r.id, type: r.type, status: r.status, increments: r.increments }));
   t.next_command = active
-    ? nextCommand(active.status, active.num, increments.length, active.verification)
+    ? nextCommand(active.status, active.num, increments.length, active.verification, t.lifecycle)
     : "/qualia";
   t.last_updated = new Date().toISOString();
   writeTracking(t);
@@ -560,10 +563,10 @@ function cmdCheckIncrement(opts) {
   const totalPhases = increments.length;
   const allDone = increments.every(isDone);
   const next_command = mine
-    ? nextCommand(mine.status, mine.num, totalPhases, mine.verification)
+    ? nextCommand(mine.status, mine.num, totalPhases, mine.verification, t.lifecycle)
     : next_unclaimed
-      ? nextCommand(next_unclaimed.status, next_unclaimed.num, totalPhases, next_unclaimed.verification)
-      : (allDone ? "/qualia-polish" : "/qualia");
+      ? nextCommand(next_unclaimed.status, next_unclaimed.num, totalPhases, next_unclaimed.verification, t.lifecycle)
+      : (allDone ? (t.lifecycle === "operate" ? "/qualia-update" : "/qualia-polish") : "/qualia");
 
   output({
     ok: true,
@@ -642,9 +645,10 @@ function cmdTransitionIncrement(opts, target) {
 
   const phase = inc.num;
   const prevStatus = inc.status;
-  const check = checkPreconditions({ phase, status: inc.status, total_phases: increments.length }, target, { ...opts, phase });
+  const t0 = ensureLifetime(readTracking() || {});
+  const check = checkPreconditions({ phase, status: inc.status, total_phases: increments.length }, target, { ...opts, phase, lifecycle: t0.lifecycle, profile: resolveProfile(null, t0) });
   if (!check.ok) {
-    const forceable = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN"];
+    const forceable = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN", "SCOPE_DRIFT"];
     if (opts.force && forceable.includes(check.error)) {
       console.error(`WARNING: Forcing transition despite: ${check.message}`);
     } else {
@@ -698,7 +702,7 @@ function cmdTransitionIncrement(opts, target) {
     previous_status: prevStatus,
     verification: inc.verification,
     gap_cycles: inc.gap_cycles || 0,
-    next_command: nextCommand(inc.status, inc.num, increments.length, inc.verification),
+    next_command: nextCommand(inc.status, inc.num, increments.length, inc.verification, t.lifecycle),
   };
   if (ledger.ok) {
     result.ledger_event_id = ledger.event_id;
@@ -1040,6 +1044,14 @@ function checkPreconditions(current, target, opts) {
     }
   }
 
+  if (target === "built") {
+    // Scope-drift gate (ITEM #5): the planned→built seam is where /qualia-build
+    // used to ASK the agent to run analyze-gate. Now it's enforced. strict +
+    // HIGH finding refuses; standard is advisory; the gate's own failure is soft.
+    const driftCheck = checkScopeDrift(phase, opts.profile);
+    if (!driftCheck.ok) return driftCheck;
+  }
+
   if (target === "verified") {
     const vFile = path.join(PLANNING, `phase-${phase}-verification.md`);
     if (!fs.existsSync(vFile))
@@ -1119,6 +1131,78 @@ function checkMachineEvidence(phase) {
   return { ok: true };
 }
 
+// Scope-drift gate (ITEM #5): enforce analyze-gate.js at the planned→built seam
+// instead of leaving it to the qualia-build SKILL prose ("please run analyze-gate").
+// "A rule worth enforcing is worth a hook" — so the highest-value catch (a plan
+// silently dropping a scope acceptance criterion) is now deterministic state.
+//
+// Fail-SOFT discipline: this gate must never crash a build on its OWN error. A
+// missing contract, missing analyze-gate.js, a thrown analyze(), or a parse
+// failure all return { ok: true } (advisory, build proceeds). It fail-CLOSES
+// only on a genuine finding: a strict-profile project with a HIGH analyze
+// finding (an under-covered scope AC or scope-reduction language). In
+// `standard` profile every finding stays advisory, mirroring the SKILL contract.
+function checkScopeDrift(phase, profile) {
+  const contractFile = path.join(PLANNING, `phase-${phase}-contract.json`);
+  // No contract → nothing to diff against. (planned→built already required a
+  // contract at the `planned` gate, but a forced/legacy build may lack one.)
+  if (!fs.existsSync(contractFile)) return { ok: true };
+
+  let analyzeGate;
+  try {
+    analyzeGate = require("./analyze-gate.js");
+  } catch (e) {
+    try { _trace("scope-drift", "skip", { phase, reason: "gate-unavailable", error: e.message }); } catch {}
+    return { ok: true };
+  }
+
+  // Reuse plan-contract's reader so a malformed contract is a soft skip, not a throw.
+  let result;
+  try {
+    const pc = require("./plan-contract.js");
+    const loaded = pc.readContractFile(contractFile);
+    if (!loaded.ok) {
+      try { _trace("scope-drift", "skip", { phase, reason: "contract-unreadable", error: loaded.error }); } catch {}
+      return { ok: true };
+    }
+    const scopePath = path.join(PLANNING, `phase-${phase}-context.md`);
+    const contextPath = path.join(PLANNING, "CONTEXT.md");
+    const readMaybe = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return null; } };
+    result = analyzeGate.analyze({
+      contract: loaded.contract,
+      scopeMd: readMaybe(scopePath),
+      contextMd: readMaybe(contextPath),
+    });
+  } catch (e) {
+    // The gate's own failure must not block the build — fail soft.
+    try { _trace("scope-drift", "error", { phase, error: e.message }); } catch {}
+    return { ok: true };
+  }
+
+  const highs = (result.findings || []).filter((f) => f.severity === "HIGH");
+  if (highs.length === 0) {
+    try { _trace("scope-drift", "allow", { phase, findings: (result.findings || []).length }); } catch {}
+    return { ok: true };
+  }
+
+  // standard profile: a senior may proceed past findings (advisory). The build
+  // SKILL logs the waiver; state.js only records the trace and lets it through.
+  if (profile === "standard") {
+    try { _trace("scope-drift", "advisory", { phase, profile, high: highs.length }); } catch {}
+    return { ok: true };
+  }
+
+  // strict profile + HIGH finding → REFUSE the advance.
+  const dropped = highs.map((f) => f.message).join("; ");
+  try { _trace("scope-drift", "block", { phase, profile, high: highs.length, findings: highs.map((f) => f.type) }); } catch {}
+  return fail(
+    "SCOPE_DRIFT",
+    `Phase ${phase} plan drifts from scope (${highs.length} HIGH): ${dropped}. ` +
+      `Route to /qualia-plan ${phase} --gaps (plan dropped a requirement) or /qualia-scope ${phase} (scope is wrong). ` +
+      `Override (standard profile / senior waiver) with --force.`
+  );
+}
+
 function recordLedgerEvent(meta) {
   try {
     return stateLedger.append(process.cwd(), {
@@ -1166,7 +1250,10 @@ function nextCommand(status, phase, totalPhases, verification, lifecycle) {
     case "done":
       return operate ? "/qualia-update" : "Done.";
     default:
-      return `/qualia`;
+      // UNRECOGNIZED_STATUS — an unknown status must never recommend /qualia
+      // itself (that's a self-recommending loop: /qualia reads state, state
+      // points back at /qualia). Emit a diagnostic the caller can surface.
+      return `UNRECOGNIZED_STATUS '${status}' — run /qualia-doctor`;
   }
 }
 
@@ -1517,15 +1604,16 @@ function cmdTransition(opts) {
 
   const phase = parseInt(opts.phase) || s.phase;
 
-  // Precondition check (lifecycle threaded so the handoff gate can relax in operate)
-  const check = checkPreconditions({ ...s, phase }, target, { ...opts, phase, lifecycle: t.lifecycle });
+  // Precondition check (lifecycle threaded so the handoff gate can relax in
+  // operate; profile threaded so the scope-drift gate knows strict vs standard)
+  const check = checkPreconditions({ ...s, phase }, target, { ...opts, phase, lifecycle: t.lifecycle, profile: resolveProfile(s, t) });
   if (!check.ok) {
     // --force bypasses status-ordering and plan-content errors. The use case
     // is retroactive bookkeeping: a phase was built without /qualia-plan and
     // the user is catching STATE.md up to reality. --force never bypasses
     // MISSING_FILE or MISSING_ARG — those would leave the state machine
     // pointing at nothing.
-    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN"];
+    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN", "SCOPE_DRIFT"];
     if (opts.force && forceableErrors.includes(check.error)) {
       console.error(`WARNING: Forcing transition despite: ${check.message}`);
     } else {
@@ -2102,7 +2190,7 @@ function cmdMigrate(opts) {
     increment_ids: ids,
     cursor: ids[(Number(t.phase || s.phase) || s.phase) - 1] || ids[0],
     note: "STATE.md + tracking.json are now gitignored generated views. If they were previously committed, run `git rm --cached .planning/STATE.md .planning/tracking.json` to stop tracking them. Revert anytime with `state.js migrate --revert`.",
-    next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification),
+    next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification, t.lifecycle),
   });
 }
 
@@ -2158,7 +2246,8 @@ function cmdClaim(opts) {
   writeCursor({ current_increment: id });
   regenerateViews(`Claimed ${id} (${me})`);
   recordLedgerEvent({ action: "claim", phase_before: inc.num, phase_after: inc.num, status_before: inc.status, status_after: inc.status });
-  output({ ok: true, action: "claim", id, claimed_by: me, branch: inc.branch, status: inc.status, next_command: nextCommand(inc.status, inc.num, listIncrements().length, inc.verification) });
+  const lifecycle = (readTracking() || {}).lifecycle;
+  output({ ok: true, action: "claim", id, claimed_by: me, branch: inc.branch, status: inc.status, next_command: nextCommand(inc.status, inc.num, listIncrements().length, inc.verification, lifecycle) });
 }
 
 // ─── A5: release (ship) an increment + clear its claim ──