qualia-framework 6.5.0 → 6.7.0

package/README.md

@@ -75,7 +75,7 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 ### Phase-specific depth (optional)
 
 ```
-/qualia-discuss N   # Capture decisions before planning a complex phase (locks constraints for the planner)
+/qualia-scope N   # Capture decisions before planning a complex phase (locks constraints for the planner)
 /qualia-research N  # Deep-research a niche phase (Context7/WebFetch/WebSearch)
 /qualia-map         # Map existing codebase (brownfield projects — run before /qualia-new)
 ```
@@ -137,7 +137,7 @@ Project
 
 ## What's Inside (v6.3.0)
 
-- **23 installed skills**, focused into Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router + road), quality (fix, review, optimize with `--deepen` parallel-interface design, feature, test), design (`qualia-polish --loop` and `--vibe`), health/reporting (doctor, learn, postmortem), and Zoho workflow support. Retired helper commands are pruned on install rather than exposed as default slash commands.
+- **25 installed skills**, focused into Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (scope, research, map), navigation (qualia router + road), quality (fix, review, optimize with `--deepen` parallel-interface design, feature, test), design (`qualia-polish --loop` and `--vibe`), health/reporting (doctor, learn, postmortem), and Zoho workflow support. Retired helper commands are pruned on install rather than exposed as default slash commands.
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
 - **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **10 installed rules** (`rules/`): grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, and always-on command-output transparency.
@@ -214,7 +214,7 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/ and/or ~/.codex/
-  ├── skills/             23 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
+  ├── skills/             25 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
   ├── agents/             9 agent definitions (Claude .md, Codex .toml)
   ├── hooks/              11 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + planning-hygiene.js + plan-contract.js + agent-runs.js + ERP/report helpers

package/agents/roadmapper.md

@@ -23,7 +23,7 @@ You do NOT run research — that's already done upstream.
 Per `rules/grounding.md`. JOURNEY.md / REQUIREMENTS.md / ROADMAP.md become canon for every downstream agent. Anything you write becomes the source of truth — fabrications calcify into requirements:
 
 1. **Every milestone scope ties back to PROJECT.md or research.** Format inline: `{milestone scope sentence} — [PROJECT.md §Goals]` or `[research/SUMMARY.md §Architecture]`. Sections without attribution will be rejected by the user during the journey-approval gate.
-2. **Every REQ-ID has a source line.** REQ-001 cites the line in PROJECT.md or research where the requirement originated. No `/qualia-discuss` loop should be needed to ask "where did REQ-007 come from?" later.
+2. **Every REQ-ID has a source line.** REQ-001 cites the line in PROJECT.md or research where the requirement originated. No `/qualia-scope` loop should be needed to ask "where did REQ-007 come from?" later.
 3. **Don't invent features that weren't asked for.** If PROJECT.md mentions "user dashboard" and you derive 8 dashboard sub-requirements, cite which user need each one addresses. If you can't, drop it.
 4. **No hedging in milestone names or success criteria.** "M2 might include payments" → either it does (commit to it with citation) or it goes in `Out of Scope`. Roadmaps with hedge language produce hedge plans.
 5. **Tool-use is mandatory before challenging an assumption.** Before saying "the tech stack should be Next.js," `Read` PROJECT.md to confirm whether the user already chose. The user's preferences override your taste.

package/bin/auto-report.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// ~/.claude/bin/auto-report.js — B1 auto-capture (framework side).
+//
+// Fires at SHIP TIME: when a Qualia project's tracking.json reaches
+// status `shipped`, POST a session report to the ERP tagged `source: "auto"`,
+// so the ERP reflects real shipped work without anyone running /qualia-report.
+//
+// Design (mirrors the constraints learned the hard way):
+//   • Ship-time, NOT per-turn. The Stop hook fires every turn; this guards on
+//     status===shipped + a per-shipped-unit dedupe marker, so it POSTs exactly
+//     ONCE per shipped (milestone, phase) — never a per-turn spam stream.
+//   • Fail-soft. Never throws, never blocks. On any upload failure it enqueues
+//     to the existing erp-retry queue (drained by session-start) and exits 0.
+//   • One ERP-upload seam. Reuses erp-retry's postOnce/enqueue/config/key
+//     readers and report-payload's buildPayload — no duplicated contract.
+//   • No double-posting. The dedupe marker means re-running on the same shipped
+//     unit is a no-op; the ERP also UPSERTs on (project_id, client_report_id).
+//
+// Invoked fire-and-forget (detached) by hooks/stop-session-log.js, or directly:
+//   node auto-report.js            # run the guarded auto-report for cwd
+//   SOURCE handled internally as "auto"; set DRY_RUN=1 to mark the report dry.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { spawnSync } = require("child_process");
+const { buildPayload } = require("./report-payload.js");
+const { enqueue, postOnce, readApiKey, readConfig } = require("./erp-retry.js");
+
+function qualiaHome(home = os.homedir()) {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(home, ".claude");
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function markerFile(home, projectKey) {
+  const safe = String(projectKey || "project").replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
+  return path.join(qualiaHome(home), `.qualia-auto-report-${safe}.json`);
+}
+
+function erpUrl(cfg) {
+  const base = (cfg && cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
+  return base.replace(/\/+$/, "") + "/api/v1/reports";
+}
+
+function allocateReportId(cwd) {
+  // Sequential QS-REPORT-NN via state.js (the same allocator /qualia-report uses).
+  try {
+    const r = spawnSync("node", [path.join(__dirname, "state.js"), "next-report-id"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 4000,
+    });
+    if (r.status === 0 && r.stdout) {
+      const parsed = JSON.parse(r.stdout);
+      if (parsed && parsed.report_id) return parsed.report_id;
+    }
+  } catch {}
+  return "";
+}
+
+// The single decision + action. Returns a small status object; never throws.
+async function maybeAutoReport({ cwd = process.cwd(), home = os.homedir(), env = process.env } = {}) {
+  try {
+    // Guard 1 — ERP configured. No key / disabled → silent no-op.
+    const cfg = readConfig();
+    if (cfg && cfg.erp && cfg.erp.enabled === false) return { skipped: "erp-disabled" };
+    const apiKey = readApiKey();
+    if (!apiKey) return { skipped: "no-key" };
+
+    // Guard 2 — Qualia project at SHIP time only.
+    const tracking = readJson(path.join(cwd, ".planning", "tracking.json"));
+    if (!tracking) return { skipped: "no-project" };
+    if (String(tracking.status) !== "shipped") return { skipped: "not-shipped" };
+
+    // Guard 3 — dedupe: one report per shipped (milestone, phase).
+    const projectKey =
+      tracking.project_id ||
+      tracking.project ||
+      path.basename(cwd);
+    const unit = `${tracking.milestone || 1}:${tracking.phase || 0}:shipped`;
+    const mFile = markerFile(home, projectKey);
+    const marker = readJson(mFile) || {};
+    if (marker.last === unit) return { skipped: "already-reported", unit };
+
+    // Allocate a sequential client_report_id (the ERP dedupe key).
+    const clientReportId = allocateReportId(cwd);
+    const idempotencyKey = crypto.randomUUID();
+    const payload = buildPayload({
+      cwd,
+      home,
+      env: { ...env, SOURCE: "auto", CLIENT_REPORT_ID: clientReportId },
+    });
+    const body = JSON.stringify(payload);
+    const url = erpUrl(cfg);
+
+    const result = await postOnce(
+      { url, payload: body, idempotency_key: idempotencyKey },
+      apiKey,
+    );
+
+    const writeMarker = (extra) => {
+      try {
+        fs.writeFileSync(
+          mFile,
+          JSON.stringify({ last: unit, client_report_id: clientReportId, at: new Date().toISOString(), ...extra }, null, 2),
+          { mode: 0o600 },
+        );
+      } catch {}
+    };
+
+    if (result.code === "200") {
+      writeMarker({ posted: true });
+      return { posted: clientReportId, unit };
+    }
+
+    // Any non-200 → enqueue for the retry queue (session-start drains it).
+    // Mark the unit so we don't re-allocate a new id on the next turn; the
+    // queued item carries this client_report_id and the ERP dedupes on it.
+    try {
+      enqueue({
+        client_report_id: clientReportId,
+        idempotency_key: idempotencyKey,
+        url,
+        payload: body,
+        last_error: result.error ? `network: ${result.error}` : `HTTP ${result.code}`,
+      });
+    } catch {}
+    writeMarker({ queued: true, last_error: result.error || `HTTP ${result.code}` });
+    return { queued: clientReportId, unit, error: result.error || `HTTP ${result.code}` };
+  } catch (e) {
+    // Auto-capture must never break a session.
+    return { skipped: "error", error: e && e.message ? e.message : String(e) };
+  }
+}
+
+module.exports = { maybeAutoReport };
+
+if (require.main === module) {
+  maybeAutoReport()
+    .then((r) => {
+      if (process.env.QUALIA_DEBUG) process.stdout.write(JSON.stringify(r) + "\n");
+      process.exit(0);
+    })
+    .catch(() => process.exit(0));
+}

package/bin/command-surface.js

@@ -9,7 +9,6 @@ const ACTIVE_SKILLS = [
   "qualia",
   "qualia-new",
   "qualia-scope",
-  "qualia-discuss",
   "qualia-map",
   "qualia-research",
   "qualia-plan",
@@ -57,6 +56,9 @@ const RETIRED_SKILLS = [
   "qualia-hook-gen",   // framework-authoring utility, not employee default
   "qualia-skill-new",  // framework-authoring utility, not employee default
   "qualia-flush",      // available as qualia-framework flush / automation
+
+  // A4 surface collapse (v6.7): folded where a surviving skill genuinely covers it.
+  "qualia-discuss",    // folded into qualia-scope — PROJECT MODE (kickoff → project-discovery.md) + PHASE MODE (grill → phase-N-context.md) now live there via its mode router
 ];
 
 function activeSkills() {

package/bin/erp-retry.js

@@ -274,8 +274,10 @@ function actionClear() {
   log(`queue cleared (backup at ${bak})`);
 }
 
-// ─── Export for in-process use (qualia-report skill enqueues directly) ──
-module.exports = { enqueue, readQueue, writeQueue };
+// ─── Export for in-process use (qualia-report skill enqueues directly;
+//     auto-report.js reuses the POST + config/key readers so there is ONE
+//     ERP-upload seam, not two). ──
+module.exports = { enqueue, readQueue, writeQueue, postOnce, readApiKey, readConfig };
 
 // ─── CLI entrypoint ─────────────────────────────────────
 if (require.main === module) {

package/bin/report-payload.js

@@ -136,6 +136,11 @@ function buildPayload(options = {}) {
     notes,
     submitted_by: env.SUBMITTED_BY || "unknown",
     submitted_at: submittedAt,
+    // B1 — provenance. 'auto' = captured automatically at ship-time (auto-report.js);
+    // 'manual' = a deliberate /qualia-report. Defaults to 'manual' so the manual
+    // flow is unchanged; auto-report passes SOURCE=auto.
+    source: env.SOURCE === "auto" ? "auto" : "manual",
+    ...(env.DRY_RUN === "1" ? { dry_run: true } : {}),
   };
 }