qualia-framework 6.9.0 → 6.14.0

package/bin/analyze-gate.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// analyze-gate.js — cross-artifact consistency + coverage gate (Spec-Kit's
+// most-copied feature). Runs BETWEEN plan and build: diffs the plan contract
+// against the scope's acceptance criteria and the CONTEXT.md glossary, and
+// flags requirements the plan under-covers plus contradictions it introduces.
+//
+// WHY: Qualia validates each artifact in isolation — plan-contract.js proves the
+// contract is internally well-formed, harness-eval scores the built phase — but
+// nothing diffs scope ↔ plan. That's exactly where a junior's idea silently
+// loses intent: the scope asks for X, the plan quietly drops it, and no
+// deterministic check notices. This is that check.
+//
+// DETERMINISTIC: keyword/token coverage, not an LLM. Same inputs → same output.
+// Heuristic by nature (token overlap), so it is a *flag-for-review* gate: the
+// caller decides hard-block (strict profile) vs advisory (standard). Exit 0 =
+// clean, 1 = findings, 2 = invocation error.
+//
+// Inputs (auto-discovered from --phase, or passed explicitly):
+//   contract  .planning/phase-{N}-contract.json   (required)
+//   scope     .planning/phase-{N}-context.md       (optional)
+//   context   .planning/CONTEXT.md                 (optional, glossary)
+//
+// Zero npm dependencies. Library + CLI.
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("./plan-contract.js");
+
+// Tokens shorter than this, or in the stop list, carry no coverage signal.
+const MIN_TOKEN_LEN = 4;
+const STOPWORDS = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "into", "your", "you",
+  "are", "was", "were", "will", "shall", "should", "must", "when", "then",
+  "each", "every", "any", "all", "not", "but", "via", "per", "page", "user",
+  "users", "data", "system", "feature", "support", "able", "ensure", "show",
+  "display", "have", "has", "can", "its", "their", "they", "them", "which",
+  "where", "what", "who", "how", "use", "uses", "used", "using", "new",
+]);
+
+// A requirement is "covered" when at least this fraction of its significant
+// tokens appear somewhere in the plan corpus, OR ABS_OVERLAP distinct tokens do.
+const COVERAGE_RATIO = 0.5;
+const ABS_OVERLAP = 3;
+
+function tokenize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= MIN_TOKEN_LEN && !STOPWORDS.has(t));
+}
+
+function significantTokens(text) {
+  return new Set(tokenize(text));
+}
+
+// covered ⇔ ≥COVERAGE_RATIO of the requirement's tokens are in the corpus, or
+// ≥ABS_OVERLAP of them are. Requirements with no significant tokens are treated
+// as covered (nothing to match — e.g. a one-word "Works.").
+function coverage(reqText, corpusTokenSet) {
+  const reqTokens = [...significantTokens(reqText)];
+  if (reqTokens.length === 0) return { covered: true, overlap: 0, total: 0, ratio: 1 };
+  const overlap = reqTokens.filter((t) => corpusTokenSet.has(t)).length;
+  const ratio = overlap / reqTokens.length;
+  return {
+    covered: ratio >= COVERAGE_RATIO || overlap >= ABS_OVERLAP,
+    overlap,
+    total: reqTokens.length,
+    ratio,
+  };
+}
+
+// ── Scope parsing ───────────────────────────────────────────────────────
+// Pull the bullets under "## Acceptance Criteria" (testable observables) from a
+// phase-context / scope markdown file. Bullets look like "- AC1 — {criterion}"
+// or plain "- {criterion}". Stops at the next "## " heading.
+function parseScopeAcceptanceCriteria(md) {
+  if (!md) return [];
+  const lines = md.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = /^##\s+Acceptance Criteria/i.test(line);
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    // Strip a leading "AC12 —"/"AC12:"/"AC12 -" label so it isn't matched as a token.
+    const text = m[1].replace(/^AC\d+\s*[—:\-]\s*/i, "").trim();
+    if (text) out.push(text);
+  }
+  return out;
+}
+
+// Pull "Avoid:" aliases from CONTEXT.md glossary lines. The glossary bans
+// alternative terms ("**Avoid:** AuthUser vs Customer"); using a banned alias in
+// the plan is a genuine, deterministic cross-artifact contradiction.
+function parseGlossaryBannedTerms(md) {
+  if (!md) return [];
+  const banned = new Set();
+  const lines = md.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/\*{0,2}Avoid:?\*{0,2}\s*(.+)$/i);
+    if (!m) continue;
+    // "AuthUser vs Customer (unless disambiguated)" → ["AuthUser", "Customer"]
+    const body = m[1].replace(/\([^)]*\)/g, " ");
+    for (const part of body.split(/\bvs\b|,|\/|;/i)) {
+      const term = part.trim().replace(/[.*_`]/g, "");
+      // Only meaningful identifier-like aliases (skip prose).
+      if (/^[A-Za-z][A-Za-z0-9 _-]{2,}$/.test(term) && !STOPWORDS.has(term.toLowerCase())) {
+        banned.add(term.trim());
+      }
+    }
+  }
+  return [...banned];
+}
+
+// ── Core analysis ─────────────────────────────────────────────────────────
+function analyze({ contract, scopeMd, contextMd }) {
+  const findings = [];
+
+  const tasks = (contract && contract.tasks) || [];
+  const successCriteria = (contract && contract.success_criteria) || [];
+
+  // The plan corpus = everything the plan promises to do.
+  const planText = [
+    contract.goal,
+    contract.why,
+    ...successCriteria,
+    ...tasks.map((t) => t.title),
+    ...tasks.map((t) => t.action),
+    ...tasks.flatMap((t) => t.acceptance_criteria || []),
+  ].filter(Boolean).join("\n");
+  const planTokens = significantTokens(planText);
+
+  // Per-task corpora for success-criterion → task mapping.
+  const taskCorpora = tasks.map((t) => ({
+    id: t.id,
+    tokens: significantTokens([t.title, t.action, ...(t.acceptance_criteria || [])].filter(Boolean).join("\n")),
+  }));
+
+  // 1. Scope acceptance criteria under-covered by the plan (the core check).
+  const scopeACs = parseScopeAcceptanceCriteria(scopeMd);
+  for (const ac of scopeACs) {
+    const cov = coverage(ac, planTokens);
+    if (!cov.covered) {
+      findings.push({
+        type: "uncovered-scope-ac",
+        severity: "HIGH",
+        message: `Scope acceptance criterion under-covered by the plan: "${ac}"`,
+        detail: `${cov.overlap}/${cov.total} key terms found in the contract (need ≥${Math.ceil(cov.total * COVERAGE_RATIO)} or ${ABS_OVERLAP}). The plan may have dropped this requirement.`,
+      });
+    }
+  }
+
+  // 2. Contract success criteria with no task home (orphan requirement).
+  for (const sc of successCriteria) {
+    const best = taskCorpora
+      .map((tc) => ({ id: tc.id, cov: coverage(sc, tc.tokens) }))
+      .sort((a, b) => b.cov.ratio - a.cov.ratio)[0];
+    if (!best || !best.cov.covered) {
+      findings.push({
+        type: "uncovered-success-criterion",
+        severity: "MEDIUM",
+        message: `Success criterion maps to no task: "${sc}"`,
+        detail: "No task's title/action/acceptance-criteria covers this success criterion. Either a task is missing or the criterion is unowned.",
+      });
+    }
+  }
+
+  // 3. Glossary contradictions — a banned alias used in the plan text.
+  const banned = parseGlossaryBannedTerms(contextMd);
+  for (const term of banned) {
+    const re = new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+    if (re.test(planText)) {
+      findings.push({
+        type: "glossary-violation",
+        severity: "MEDIUM",
+        message: `Plan uses a term CONTEXT.md bans: "${term}"`,
+        detail: "The glossary lists this under Avoid:. Use the canonical term so spec, plan, and code agree.",
+      });
+    }
+  }
+
+  // 4. Scope-reduction phrases anywhere in the plan's free text (reuse the
+  //    plan-contract scanner — surfaced here as part of the cross-artifact gate).
+  for (const t of tasks) {
+    const fields = [["action", t.action], ...(t.acceptance_criteria || []).map((a, i) => [`acceptance_criteria[${i}]`, a])];
+    for (const [field, val] of fields) {
+      const hits = pc.findScopeReductionPhrases(val);
+      if (hits.length) {
+        findings.push({
+          type: "scope-reduction",
+          severity: "HIGH",
+          message: `Task ${t.id} ${field} contains scope-reduction language: ${hits.join(", ")}`,
+          detail: "The plan waters down the spec. Deliver the actual requirement or split it via the locked-decision channel.",
+        });
+      }
+    }
+  }
+
+  const bySeverity = (s) => findings.filter((f) => f.severity === s).length;
+  return {
+    ok: findings.length === 0,
+    phase: contract.phase,
+    counts: {
+      total: findings.length,
+      high: bySeverity("HIGH"),
+      medium: bySeverity("MEDIUM"),
+      scope_acs_checked: scopeACs.length,
+      success_criteria_checked: successCriteria.length,
+      glossary_terms_checked: banned.length,
+    },
+    scope_present: scopeMd != null,
+    context_present: contextMd != null,
+    findings,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+function readMaybe(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return null; }
+}
+
+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 === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--contract") args.contract = argv[++i];
+    else if (a.startsWith("--contract=")) args.contract = a.slice(11);
+    else if (a === "--scope") args.scope = argv[++i];
+    else if (a.startsWith("--scope=")) args.scope = a.slice(8);
+    else if (a === "--context") args.context = argv[++i];
+    else if (a.startsWith("--context=")) args.context = a.slice(10);
+    else if (a === "--phase") args.phase = argv[++i];
+    else if (a.startsWith("--phase=")) args.phase = a.slice(8);
+    else args._.push(a);
+  }
+  if (args.phase == null && args._.length && /^\d+$/.test(args._[0])) args.phase = args._[0];
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  analyze-gate.js <phase> [--cwd DIR] [--json]",
+    "  analyze-gate.js --contract <c.json> [--scope <s.md>] [--context <ctx.md>] [--json]",
+    "",
+    "Cross-artifact coverage gate between plan and build.",
+    "Exit 0 = clean, 1 = findings, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const root = path.resolve(args.cwd || process.cwd());
+  const planning = path.join(root, ".planning");
+
+  let contractPath = args.contract;
+  let scopePath = args.scope;
+  let contextPath = args.context;
+  if (!contractPath && args.phase != null) {
+    contractPath = path.join(planning, `phase-${args.phase}-contract.json`);
+    if (scopePath == null) scopePath = path.join(planning, `phase-${args.phase}-context.md`);
+    if (contextPath == null) contextPath = path.join(planning, "CONTEXT.md");
+  }
+  if (!contractPath) { usage(); return 2; }
+
+  const loaded = pc.readContractFile(contractPath);
+  if (!loaded.ok) {
+    if (args.json) console.log(JSON.stringify({ ok: false, ...loaded }, null, 2));
+    else console.error(`${loaded.error}: ${loaded.message}`);
+    return 2;
+  }
+
+  const result = analyze({
+    contract: loaded.contract,
+    scopeMd: scopePath ? readMaybe(scopePath) : null,
+    contextMd: contextPath ? readMaybe(contextPath) : null,
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+
+  const c = result.counts;
+  if (result.ok) {
+    console.log(`ANALYZE PASS phase ${result.phase}: scope↔plan consistent ` +
+      `(${c.scope_acs_checked} scope AC, ${c.success_criteria_checked} success criteria, ${c.glossary_terms_checked} glossary terms checked)`);
+    if (!result.scope_present) console.log("  note: no scope file (phase-N-context.md) — scope-coverage check skipped");
+    return 0;
+  }
+
+  console.error(`ANALYZE FINDINGS phase ${result.phase}: ${c.total} (${c.high} HIGH, ${c.medium} MEDIUM)`);
+  if (!result.scope_present) console.error("  note: no scope file — scope-coverage check was skipped");
+  for (const f of result.findings) {
+    console.error(`  [${f.severity}] ${f.message}`);
+    console.error(`         ${f.detail}`);
+  }
+  return 1;
+}
+
+module.exports = {
+  analyze,
+  coverage,
+  tokenize,
+  parseScopeAcceptanceCriteria,
+  parseGlossaryBannedTerms,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/command-surface.js

@@ -21,6 +21,7 @@ const ACTIVE_SKILLS = [
   "qualia-polish",
   "qualia-test",
   "qualia-milestone",
+  "qualia-update",
   "qualia-ship",
   "qualia-handoff",
   "qualia-report",

package/bin/install.js

@@ -555,8 +555,9 @@ function askCode() {
 // ─── Employee mode (no team code) ────────────────────────
 // A new employee may not have a QS-NAME-## code yet. Typing "EMPLOYEE" at the
 // install-code prompt installs the full framework at the least-privilege role:
-// feature branches only, no main pushes (enforced by branch-guard, which trusts
-// the role bit in the 0o600 config). ERP reporting stays OFF until a real team
+// feature branches by default; main pushes are allowed but recorded by
+// branch-guard (counted locally + reported to the ERP, which trusts the role bit
+// in the 0o600 config). ERP reporting stays OFF until a real team
 // code is set, so /qualia-report degrades to a local-only report.
 //
 // Defaulting to EMPLOYEE (not OWNER) on a missing/keyword code is the secure
@@ -1140,6 +1141,10 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       enabled: !employeeMode,
       url: "https://portal.qualiasolutions.net",
       api_key_file: ".erp-api-key",
+      // Performance-audit telemetry. command_usage (counts) is always on.
+      // capturePrompts records real prompt text for the prompt-quality judge —
+      // written explicitly (not implied) so engineers can see and flip it.
+      capturePrompts: true,
     },
   };
   // mode 0o600: this file holds the role bit (OWNER vs EMPLOYEE) which the
@@ -1272,9 +1277,11 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
     "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
     "git-guardrails.js", "stop-session-log.js",
-    "fawzi-approval-guard.js",
+    "fawzi-approval-guard.js", "task-write-guard.js",
     // v5.0 — insights-driven destructive-op + wrong-account guards
     "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
+    // performance-audit telemetry capture (UserPromptSubmit)
+    "usage-capture.js",
   ]);
   const isQualiaHookCmd = (cmd) => {
     if (typeof cmd !== "string") return false;
@@ -1299,7 +1306,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
           { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "⬢ Checking git safety..." },
           { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
-          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Recording branch activity..." },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
           { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 600, statusMessage: "⬢ Running quality gates..." },
           // v5.0 hooks — insights-driven friction prevention
@@ -1312,6 +1319,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         matcher: "Edit|Write",
         hooks: [
           { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
+          { type: "command", command: nodeCmd("task-write-guard.js"), timeout: 5, statusMessage: "⬢ Checking plan-contract file scope..." },
           { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
@@ -1338,6 +1346,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         ],
       },
     ],
+    // Performance-audit telemetry — record qualia-command usage + (opt-in)
+    // prompt samples per session for the ERP clock-out payload.
+    UserPromptSubmit: [
+      {
+        matcher: ".*",
+        hooks: [
+          { type: "command", command: nodeCmd("usage-capture.js"), timeout: 5 },
+        ],
+      },
+    ],
   };
 
   // Merge user hooks: strip Qualia-owned commands, preserve everything else.
@@ -1519,6 +1537,13 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");
+  console.log(
+    `  ${DIM}Telemetry${RESET}      ${DIM}your /qualia command usage + prompt samples feed the team${RESET}`
+  );
+  console.log(
+    `  ${DIM}              performance audit. Opt out:${RESET} ${TEAL}erp.capturePrompts=false${RESET} ${DIM}in ~/.claude/.qualia-config.json${RESET}`
+  );
+  console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
   console.log(`  ${DIM2}${RULE}${RESET}`);
@@ -1626,6 +1651,8 @@ async function installCodex(member, target, employeeMode = false) {
         enabled: !employeeMode,
         url: "https://portal.qualiasolutions.net",
         api_key_file: ".erp-api-key",
+        // See ~/.claude config above — explicit so engineers can see/flip it.
+        capturePrompts: true,
       },
     };
     atomicWrite(path.join(CODEX_DIR, ".qualia-config.json"), JSON.stringify(codexConfig, null, 2) + "\n", 0o600);

package/bin/report-payload.js

@@ -89,6 +89,16 @@ function buildPayload(options = {}) {
   const latestHarnessEval = harnessEval.latestEval(cwd);
   const workPacket = readLocalWorkPacket(cwd);
 
+  // Performance-audit telemetry captured during the session by the
+  // usage-capture UserPromptSubmit hook. Cleared by /qualia-report after upload.
+  const usagePath = options.usagePath || path.join(cwd, ".planning", ".session-usage.json");
+  const usage = readJson(usagePath, {});
+  const commandUsage =
+    usage && typeof usage.command_usage === "object" && usage.command_usage
+      ? usage.command_usage
+      : {};
+  const promptSamples = Array.isArray(usage.prompt_samples) ? usage.prompt_samples : [];
+
   return {
     project: tracking.project || path.basename(cwd),
     project_id: projectKey,
@@ -112,12 +122,21 @@ function buildPayload(options = {}) {
     phase_name: tracking.phase_name,
     total_phases: tracking.total_phases,
     status: tracking.status,
+    // v7 lifecycle: "build" (milestone journey) or "operate" (post-launch update
+    // stream). The ERP uses this to count updates vs milestones and to stop
+    // expecting a "handoff" for a launched product. lifetime.updates_completed
+    // rides along in `lifetime` below.
+    lifecycle: tracking.lifecycle || "build",
+    ...(tracking.launched_at ? { launched_at: tracking.launched_at } : {}),
+    ...(tracking.launch_source ? { launch_source: tracking.launch_source } : {}),
     tasks_done: tracking.tasks_done || 0,
     tasks_total: tracking.tasks_total || 0,
     verification: tracking.verification || "pending",
     gap_cycles: (tracking.gap_cycles || {})[String(phase)] || 0,
     build_count: tracking.build_count || 0,
     deploy_count: tracking.deploy_count || 0,
+    command_usage: commandUsage,
+    prompt_samples: promptSamples,
     deployed_url: tracking.deployed_url || "",
     ...(tracking.session_started_at ? { session_started_at: tracking.session_started_at } : {}),
     ...(tracking.last_pushed_at ? { last_pushed_at: tracking.last_pushed_at } : {}),

package/bin/runtime-manifest.js

@@ -13,6 +13,8 @@ const RUNTIME_BIN_SCRIPTS = [
   { 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-status.js", label: "agent-status.js (per-task build status + wave fan-in barrier)" },
+  { file: "analyze-gate.js", label: "analyze-gate.js (cross-artifact scope↔plan coverage gate)" },
   { 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)" },