qualia-framework 6.9.2 → 6.22.0

package/bin/state.js

@@ -607,9 +607,28 @@ function cmdTransitionIncrement(opts, target) {
       const c = parseInt(opts.tasks_done) || 0;
       if (c > 0) t.lifetime.tasks_completed += c;
     }
+    // Scope tagging (anti-drift): /qualia-feature + /qualia-fix declare whether
+    // the work served the active milestone (--scope in --ref CORE-03) or was
+    // off-road (--scope off). Off-road work is COUNTED + ledgered so it can't
+    // drift invisibly — the OWNER + ERP see the tally, mirroring branch-guard.
+    const scope = String(opts.scope || "").toLowerCase();
+    if (scope === "off" || scope === "in") {
+      if (typeof t.lifetime.offroad_count !== "number") t.lifetime.offroad_count = 0;
+      if (scope === "off") {
+        t.lifetime.offroad_count += 1;
+        if (!Array.isArray(t.offroad)) t.offroad = [];
+        t.offroad.push({
+          at: new Date().toISOString(),
+          milestone: parseInt(t.milestone, 10) || null,
+          ref: opts.ref || null,
+          note: opts.notes || null,
+        });
+        if (t.offroad.length > 50) t.offroad = t.offroad.slice(-50); // keep recent
+      }
+    }
     writeTracking(t);
     regenerateViews(opts.notes || "Activity logged");
-    return output({ ok: true, action: target, layout: "increments" });
+    return output({ ok: true, action: target, layout: "increments", scope: scope || undefined, offroad_count: t.lifetime.offroad_count });
   }
 
   // Resolve the target increment: explicit --id, else --phase N (back-compat
@@ -706,6 +725,9 @@ function ensureLifetime(t) {
       total_phases: 0,
     };
   }
+  // v7 lifecycle (backward compat): pre-v7 tracking.json predates these fields.
+  if (t.lifecycle !== "operate" && t.lifecycle !== "build") t.lifecycle = "build";
+  if (typeof t.lifetime.updates_completed !== "number") t.lifetime.updates_completed = 0;
   return t;
 }
 
@@ -756,6 +778,31 @@ function normalizeMilestoneName(name) {
   return String(name == null ? "" : name).trim().toLowerCase();
 }
 
+// Parse the REQUIREMENTS.md traceability table for one milestone's REQ-IDs and
+// their status. Rows look like: `| CORE-01 | M2: Name | Phase 3 | Complete |`.
+// Returns { tracked: bool, total, incomplete: [{id, status}] }. tracked=false
+// when REQUIREMENTS.md is absent or has no rows for this milestone (→ gate
+// skips, like analyze-gate's no-scope-file: can't enforce what isn't declared).
+function readMilestoneRequirements(milestoneNum) {
+  let md;
+  try { md = fs.readFileSync(path.join(PLANNING, "REQUIREMENTS.md"), "utf8"); }
+  catch { return { tracked: false, total: 0, incomplete: [] }; }
+  const num = parseInt(milestoneNum, 10);
+  const rows = [];
+  for (const line of md.split(/\r?\n/)) {
+    if (!/^\s*\|/.test(line)) continue;
+    const cells = line.split("|").map((c) => c.trim()).filter((c, i, a) => !(i === 0 && c === "") && !(i === a.length - 1 && c === ""));
+    if (cells.length < 4) continue;
+    const [id, milestone, , status] = cells;
+    if (!/^[A-Z]+-\d+$/.test(id)) continue; // skip header + non-REQ rows
+    const m = milestone.match(/M(\d+)\b/);
+    if (!m || parseInt(m[1], 10) !== num) continue;
+    rows.push({ id, status: status || "" });
+  }
+  const incomplete = rows.filter((r) => r.status.trim().toLowerCase() !== "complete");
+  return { tracked: rows.length > 0, total: rows.length, incomplete };
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -970,6 +1017,25 @@ function checkPreconditions(current, target, opts) {
     const anchors = doneWhenCount + acCount;
     if (anchors < taskHeaders.length)
       return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${anchors} 'Done when:' or 'Acceptance Criteria:' anchors`);
+    // v7 kernel: a phase cannot reach `planned` without a machine contract.
+    // checkMachineEvidence() at the `verified` gate only engages when
+    // phase-N-contract.json exists; if a contract could be skipped here, the
+    // entire evidence requirement is bypassable by omission and the prose
+    // verifier (which can PASS on inaction) would govern. Requiring it here is
+    // what makes "I built it" insufficient and "the contract ran clean" required.
+    const contractFile = path.join(PLANNING, `phase-${phase}-contract.json`);
+    if (!fs.existsSync(contractFile))
+      return fail(
+        "MISSING_CONTRACT",
+        `Machine contract not found: ${contractFile}. /qualia-plan must compile the plan into a JSON contract before 'planned'. Regenerate with /qualia-plan, or build it via bin/plan-contract.js.`
+      );
+    try {
+      const c = JSON.parse(fs.readFileSync(contractFile, "utf8"));
+      if (!c || !Array.isArray(c.tasks) || c.tasks.length === 0)
+        return fail("INVALID_CONTRACT", `${contractFile} has no tasks[]; not a valid phase contract.`);
+    } catch (e) {
+      return fail("INVALID_CONTRACT", `Could not parse ${contractFile}: ${e.message}`);
+    }
   }
 
   if (target === "verified") {
@@ -994,9 +1060,17 @@ function checkPreconditions(current, target, opts) {
   }
 
   if (target === "handed_off") {
-    const hFile = path.join(PLANNING, "HANDOFF.md");
-    if (!fs.existsSync(hFile))
-      return fail("MISSING_FILE", `Handoff file not found: ${hFile}`);
+    // v7 lifecycle: the HANDOFF.md requirement is a BUILD-mode convention, not a
+    // universal law. An "operate" project (a launched, repeatedly-shipping
+    // product or retainer) has no single handoff moment, so it must not be
+    // forced to produce one. opts.lifecycle is threaded from tracking by the
+    // caller; absent/"build" keeps the original requirement.
+    const lifecycle = opts.lifecycle || "build";
+    if (lifecycle === "build") {
+      const hFile = path.join(PLANNING, "HANDOFF.md");
+      if (!fs.existsSync(hFile))
+        return fail("MISSING_FILE", `Handoff file not found: ${hFile}`);
+    }
   }
 
   // Gap-closure circuit breaker (configurable limit)
@@ -1055,7 +1129,14 @@ function recordLedgerEvent(meta) {
 }
 
 // ─── Next Command Logic ──────────────────────────────────
-function nextCommand(status, phase, totalPhases, verification) {
+// `lifecycle` (default "build") changes the route once a project has launched.
+// In "operate" the project is an UPDATE STREAM, not a milestone journey: there is
+// no polish → ship → handoff terminal chain. After the last phase verifies, the
+// next move is the next update (/qualia-update), and the project never gets
+// dragged to a handoff it has outgrown. This is the v7 thesis in miniature —
+// a behavior that was hard-coded in prose is now a branch on explicit state.
+function nextCommand(status, phase, totalPhases, verification, lifecycle) {
+  const operate = lifecycle === "operate";
   switch (status) {
     case "setup":
       return `/qualia-plan ${phase}`;
@@ -1066,15 +1147,17 @@ function nextCommand(status, phase, totalPhases, verification) {
     case "verified":
       if (verification === "fail") return `/qualia-plan ${phase} --gaps`;
       if (phase < totalPhases) return `/qualia-plan ${phase + 1}`;
-      return "/qualia-polish";
+      return operate ? "/qualia-update" : "/qualia-polish";
     case "polished":
       return "/qualia-ship";
     case "shipped":
-      return "/qualia-handoff";
+      // In build mode a shipped project hands off once. In operate it loops:
+      // the deploy was just another update.
+      return operate ? "/qualia-update" : "/qualia-handoff";
     case "handed_off":
       return "/qualia-report";
     case "done":
-      return "Done.";
+      return operate ? "/qualia-update" : "Done.";
     default:
       return `/qualia`;
   }
@@ -1202,11 +1285,14 @@ function cmdCheck(opts) {
     tasks_done: t.tasks_done || 0,
     tasks_total: t.tasks_total || 0,
     deployed_url: t.deployed_url || "",
+    lifecycle: t.lifecycle || "build",
+    launched_at: t.launched_at || "",
     next_command: nextCommand(
       s.status,
       s.phase,
       s.total_phases,
-      t.verification
+      t.verification,
+      t.lifecycle
     ),
     schema_errors: s.schema_errors && s.schema_errors.length ? s.schema_errors : undefined,
   });
@@ -1233,6 +1319,28 @@ function applyNoteOrActivity(target, s, t, opts) {
       t.lifetime.tasks_completed += count;
     }
   }
+  // Scope tagging (anti-drift): /qualia-feature + /qualia-fix declare whether the
+  // work served the active milestone (--scope in --ref CORE-03) or was off-road
+  // (--scope off). Off-road work is COUNTED + ledgered so it can't drift
+  // invisibly — the OWNER + ERP see the tally, mirroring branch-guard.
+  const scope = String(opts.scope || "").toLowerCase();
+  let offroadCount;
+  if (scope === "in" || scope === "off") {
+    ensureLifetime(t);
+    if (typeof t.lifetime.offroad_count !== "number") t.lifetime.offroad_count = 0;
+    if (scope === "off") {
+      t.lifetime.offroad_count += 1;
+      if (!Array.isArray(t.offroad)) t.offroad = [];
+      t.offroad.push({
+        at: new Date().toISOString(),
+        milestone: parseInt(t.milestone, 10) || null,
+        ref: opts.ref || null,
+        note: opts.notes || null,
+      });
+      if (t.offroad.length > 50) t.offroad = t.offroad.slice(-50);
+    }
+    offroadCount = t.lifetime.offroad_count;
+  }
   t.last_updated = new Date().toISOString();
   writeTracking(t);
   s.last_activity = opts.notes || "Activity logged";
@@ -1242,6 +1350,8 @@ function applyNoteOrActivity(target, s, t, opts) {
     phase: s.phase,
     status: s.status,
     action: target,
+    scope: scope || undefined,
+    offroad_count: offroadCount,
   };
 }
 
@@ -1400,8 +1510,8 @@ function cmdTransition(opts) {
 
   const phase = parseInt(opts.phase) || s.phase;
 
-  // Precondition check
-  const check = checkPreconditions({ ...s, phase }, target, { ...opts, phase });
+  // Precondition check (lifecycle threaded so the handoff gate can relax in operate)
+  const check = checkPreconditions({ ...s, phase }, target, { ...opts, phase, lifecycle: t.lifecycle });
   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
@@ -1433,6 +1543,18 @@ function cmdTransition(opts) {
   if (target === "polished") applyPolishedTransition(s);
   if (target === "shipped") applyShippedTransition(t, opts);
 
+  // v7: in operate mode, a verified(pass) on the final phase completes one UPDATE.
+  // This is the operate-mode analogue of closing a milestone in build mode.
+  if (
+    target === "verified" &&
+    opts.verification === "pass" &&
+    t.lifecycle === "operate" &&
+    phase >= (parseInt(s.total_phases) || phase)
+  ) {
+    ensureLifetime(t);
+    t.lifetime.updates_completed = (t.lifetime.updates_completed || 0) + 1;
+  }
+
   // Atomic commit
   const writeError = commitTransitionAtomic(s, t);
   if (writeError) return output(writeError);
@@ -1471,7 +1593,8 @@ function cmdTransition(opts) {
     previous_status: prevStatus,
     verification: t.verification,
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
-    next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification),
+    lifecycle: t.lifecycle || "build",
+    next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification, t.lifecycle),
   };
   if (ledger.ok) {
     result.ledger_event_id = ledger.event_id;
@@ -1579,6 +1702,7 @@ function cmdInit(opts) {
     milestones_completed: 0,
     total_phases: 0,
     last_closed_milestone: 0,
+    updates_completed: 0,
   };
   const lifetime = prevLife
     ? { ...defaultLifetime, ...(prevLife.lifetime || {}) }
@@ -1607,6 +1731,11 @@ function cmdInit(opts) {
     total_phases: totalPhases,
     status: "setup",
     profile,
+    // v7 lifecycle: a new project starts in "build" (milestone journey).
+    // `launch` flips it to "operate" (update stream). Preserved across re-init.
+    lifecycle: prevLife ? (prevLife.lifecycle || "build") : "build",
+    launched_at: prevLife ? (prevLife.launched_at || "") : "",
+    launch_source: prevLife ? (prevLife.launch_source || "") : "",
     wave: 0,
     tasks_done: 0,
     tasks_total: 0,
@@ -1665,6 +1794,76 @@ function cmdInit(opts) {
   output(result);
 }
 
+// v7: the one-time launch event. Flips the project from "build" (milestone
+// journey) to "operate" (update stream). This is the discrete transition the
+// ERP can drive when it detects a project is live (is_live / status:Launched),
+// so "the product is launched" becomes explicit state instead of a milestone the
+// team is forced to call "handoff". Idempotent: launching an operate project is
+// a no-op. lifecycle is canonical in tracking.json; cmdCheck surfaces it.
+function cmdLaunch(opts) {
+  const beforeStateRaw = readState();
+  const beforeTrackingRaw = readTrackingRaw();
+  const t = parseTrackingRaw(beforeTrackingRaw);
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found. Run /qualia-new."));
+  ensureLifetime(t);
+
+  if (t.lifecycle === "operate") {
+    return output({
+      ok: true,
+      action: "launch",
+      already_launched: true,
+      lifecycle: "operate",
+      launched_at: t.launched_at || "",
+      launch_source: t.launch_source || "",
+      next_command: "/qualia-update",
+      message: "Already launched (operate lifecycle). Nothing to do.",
+    });
+  }
+
+  t.lifecycle = "operate";
+  t.launched_at = new Date().toISOString();
+  t.launch_source = opts.source === "erp" ? "erp" : "manual";
+  if (opts.deployed_url) t.deployed_url = opts.deployed_url;
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+
+  const ledger = recordLedgerEvent({
+    action: "launch",
+    phase_before: t.phase || null,
+    phase_after: t.phase || null,
+    status_before: t.status || null,
+    status_after: t.status || null,
+    state_before: parseStateMd(beforeStateRaw),
+    state_after: parseStateMd(readState()),
+    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.deployed_url ? [opts.deployed_url] : [],
+  });
+
+  const result = {
+    ok: true,
+    action: "launch",
+    lifecycle: "operate",
+    launched_at: t.launched_at,
+    launch_source: t.launch_source,
+    deployed_url: t.deployed_url || "",
+    next_command: "/qualia-update",
+    message:
+      "Launched. The project is now an UPDATE STREAM (operate): no forced polish → ship → handoff. Ship updates with the build/verify/ship loop; the forced handoff is gone.",
+  };
+  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();
@@ -2183,6 +2382,27 @@ function cmdValidatePlan(opts) {
 // recently closed milestone so re-running close-milestone (e.g., after a
 // hiccup) does NOT double-count. To re-close a milestone deliberately, pass
 // --force.
+// Report REQ-ID completion for a milestone (defaults to the current one). The
+// same check close-milestone gates on — exposed so /qualia-milestone can show
+// coverage before closing, and so it's directly testable. Exit 0 = all complete
+// (or untracked), 1 = incomplete requirements remain.
+function cmdReqsCheck(opts) {
+  const t = readTracking();
+  const milestone = opts.milestone != null ? parseInt(opts.milestone, 10) : (t ? parseInt(t.milestone, 10) || 1 : 1);
+  const reqs = readMilestoneRequirements(milestone);
+  const ok = !reqs.tracked || reqs.incomplete.length === 0;
+  output({
+    ok,
+    action: "reqs-check",
+    milestone,
+    tracked: reqs.tracked,
+    total: reqs.total,
+    complete: reqs.total - reqs.incomplete.length,
+    incomplete: reqs.incomplete,
+  });
+  process.exitCode = ok ? 0 : 1;
+}
+
 function cmdCloseMilestone(opts) {
   const beforeStateRaw = readState();
   const beforeTrackingRaw = readTrackingRaw();
@@ -2192,6 +2412,7 @@ function cmdCloseMilestone(opts) {
     return output(fail("NO_PROJECT", "No .planning/ found."));
   }
   ensureLifetime(t);
+  const closeWarnings = [];
 
   // parseInt — legacy tracking.json files carry milestone as a string ("9"),
   // which would corrupt `closedMilestone + 1` ("91") and break num dedupe.
@@ -2236,6 +2457,23 @@ function cmdCloseMilestone(opts) {
         )
       );
     }
+    // REQ-ID coverage gate: a milestone isn't "done" just because its phases
+    // verified — its agreed requirements must actually be Complete. Stops
+    // "finishing a milestone with scope left open". strict blocks; standard warns.
+    const reqs = readMilestoneRequirements(closedMilestone);
+    if (reqs.tracked && reqs.incomplete.length > 0) {
+      const profile = resolveProfile(s, t);
+      const list = reqs.incomplete.map((r) => `${r.id}:${r.status || "Pending"}`).join(", ");
+      if (profile === "strict") {
+        return output(
+          fail(
+            "MILESTONE_REQS_INCOMPLETE",
+            `Milestone ${closedMilestone} has ${reqs.incomplete.length}/${reqs.total} requirement(s) not Complete in REQUIREMENTS.md: ${list}. Finish or explicitly defer them (move to Out of Scope), or use --force.`
+          )
+        );
+      }
+      closeWarnings.push(`${reqs.incomplete.length}/${reqs.total} requirement(s) not Complete: ${list} (standard profile — proceeding; record why in the report).`);
+    }
   }
 
   // ─── Append a summary to milestones[] so the ERP can render the tree ──
@@ -2354,6 +2592,7 @@ function cmdCloseMilestone(opts) {
   } else {
     result.ledger_error = ledger.error;
   }
+  if (closeWarnings.length) result.warnings = closeWarnings;
   output(result);
 }
 
@@ -2775,6 +3014,9 @@ try {
     case "transition":
       cmdTransition(opts);
       break;
+    case "launch":
+      cmdLaunch(opts);
+      break;
     case "init":
       cmdInit(opts);
       break;
@@ -2787,6 +3029,9 @@ try {
     case "close-milestone":
       cmdCloseMilestone(opts);
       break;
+    case "reqs-check":
+      cmdReqsCheck(opts);
+      break;
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;