qualia-framework 6.9.0 → 6.14.0

package/bin/state.js

@@ -706,6 +706,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;
 }
 
@@ -970,6 +973,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 +1016,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 +1085,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 +1103,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 +1241,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,
   });
@@ -1400,8 +1442,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 +1475,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 +1525,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 +1634,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 +1663,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 +1726,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();
@@ -2775,6 +2906,9 @@ try {
     case "transition":
       cmdTransition(opts);
       break;
+    case "launch":
+      cmdLaunch(opts);
+      break;
     case "init":
       cmdInit(opts);
       break;

package/docs/EMPLOYEE-QUICKSTART.md

@@ -2,6 +2,8 @@
 
 A five-minute path from a fresh machine to a shipped, reported day of work. This is the route for a **new employee who does not have a team install code yet**. You can install and do real work in employee mode today; the OWNER (Fawzi) issues the keys that unlock ERP reporting and any direct provider integrations.
 
+> Prefer a visual tour? Open **[`docs/qualia-manual.html`](./qualia-manual.html)** — the same path as an interactive Field Manual (command map, first-project walkthrough, copy-to-clipboard commands).
+
 Who issues credentials: **the OWNER (Fawzi) issues every key** — team install codes, the ERP API key, OpenRouter / Supabase / Vercel / Retell / ElevenLabs / Telnyx credentials. If a step says "ask Fawzi", that is who to ask. Never share or reuse another person's key.
 
 ---
@@ -27,7 +29,7 @@ Install code or "EMPLOYEE":
 ```
 
 - Have a team code (`QS-NAME-##`)? Enter it — you install as that team member.
-- **No code yet?** Type **`EMPLOYEE`**. You install at the least-privilege role: feature branches only, no pushes to `main` (enforced by the `branch-guard` hook). The full framework — skills, agents, hooks, knowledge — is installed exactly the same.
+- **No code yet?** Type **`EMPLOYEE`**. You install at the least-privilege role. Feature branches are the norm; pushing to `main` is **allowed but recorded** — the `branch-guard` hook counts each employee main-push locally and reports it to the ERP so the OWNER can see it. The full framework — skills, agents, hooks, knowledge — is installed exactly the same.
 
 What employee mode changes vs. a coded install:
 
@@ -35,7 +37,7 @@ What employee mode changes vs. a coded install:
 |---|---|---|
 | Role | OWNER or EMPLOYEE per code | EMPLOYEE |
 | Skills / agents / hooks | full | full |
-| Push to `main` | OWNER only | blocked |
+| Push to `main` | OWNER (silent) | allowed, recorded to ERP |
 | ERP reporting | on (with API key) | **off** until a code/key is set |
 | `/qualia-report` | uploads to ERP | saves a **local** report file |
 
@@ -118,7 +120,7 @@ Pull these into a project with `vercel env pull` once the project is linked. **A
 /qualia-ship
 ```
 
-Runs the quality gates, commits, deploys (Vercel via CLI), and verifies. As an employee you ship through a **feature branch and review** — `branch-guard` blocks direct pushes to `main`. Deploys happen only through the CLI; GitHub auto-deploy is intentionally disabled.
+Runs the quality gates, commits, deploys (Vercel via CLI), and verifies. As an employee, prefer shipping through a **feature branch and review**. Direct pushes to `main` are allowed but `branch-guard` records each one (framework + ERP) for the OWNER, so use them only for changes that are trivially safe. Deploys happen only through the CLI; GitHub auto-deploy is intentionally disabled.
 
 **Credentials this step needs:**
 - A Vercel login on the correct team (`vercel whoami`; `vercel link` if the project isn't linked). Ask Fawzi which Vercel team the project belongs to.

package/docs/erp-contract.md

@@ -54,6 +54,29 @@ employee's active session, such as proxy owner-approval claims ("Fawzi said OK")
 The ERP should increment or store by `(type, actor_code)` so Fawzi can see how
 many times each employee attempted to use proxy approval.
 
+**Event types posted to this endpoint:**
+
+| `type` | Posted by | Meaning |
+|---|---|---|
+| `proxy_owner_approval_claim` | `fawzi-approval-guard` | An EMPLOYEE used "Fawzi said OK"-style proxy approval. Has a `sample` field. |
+| `employee_main_push` | `branch-guard` (v6.10+) | An EMPLOYEE pushed to a protected branch (`main`/`master`). Pushing is **allowed**, not blocked — this event is the accountability record. Has a `branch` field instead of `sample`. |
+
+`employee_main_push` body (same envelope, `branch` replaces `sample`):
+```json
+{
+  "type": "employee_main_push",
+  "actor_code": "QS-HASAN-02",
+  "actor_name": "Hasan",
+  "actor_role": "EMPLOYEE",
+  "count": 4,
+  "branch": "main",
+  "project": "client-project",
+  "cwd": "/path/to/client-project",
+  "recorded_at": "2026-06-20T10:00:00.000Z"
+}
+```
+Store by `(type, actor_code)` the same way so Fawzi sees a per-employee main-push tally. `client_report_id` is `QS-MAINPUSH-<actor_code>-<count>` and each post carries an idempotency key.
+
 ### POST /api/v1/reports
 
 Upload a session report.
@@ -377,6 +400,8 @@ Snapshot shape:
 | last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |
 | build_count | number | optional (v3.6+) | Lifetime build counter. |
 | deploy_count | number | optional (v3.6+) | Lifetime deploy counter. |
+| command_usage | object | optional (v6.9+) | Per-session qualia slash-command histogram, e.g. `{ "qualia-build": 3, "qualia-fix": 1 }`. Captured by the `usage-capture` UserPromptSubmit hook into `.planning/.session-usage.json` and cleared at clock-out. Drives the ERP performance audit's command-usage signal. Defaults to `{}`. |
+| prompt_samples | string[] | optional (v6.9+) | Sampled real engineer prompts for the session (opt-in via `erp.capturePrompts`, default on; internal-only). Fed to the ERP prompt-quality judge. Capped at 60 entries / 8000 chars each. Defaults to `[]`. |
 | client_report_id | string | recommended (v4.0.4+) | Client-side sequential identifier: `QS-REPORT-01`, `QS-REPORT-02`, … per-project. Stable across retries. Preferred dedupe key over the ERP-generated `report_id`; safe to adopt as the ERP's primary report key. |
 | dry_run | boolean | optional (v4.0.4+) | `true` marks a synthetic ping (from `qualia-framework erp-ping`). Receivers should filter these out of production report views. |
 
@@ -393,4 +418,11 @@ All other fields are optional but recommended for complete reporting.
 - API keys are per-user, not per-project
 - Keys expire after 90 days (re-issue via Fawzi)
 - All traffic is HTTPS-only
-- No PII beyond team member names is transmitted
+- **Free-form content:** beyond team member names, the only free-form content
+  transmitted is `prompt_samples` — the engineer's real prompts — and only when
+  `erp.capturePrompts` is enabled (default on). This is disclosed to engineers
+  at install, in their own `.qualia-config.json`, and via a once-per-shift
+  runtime notice; they may opt out at any time. Treat `prompt_samples` as
+  data that **may contain PII**: store it access-controlled, keep it out of
+  third-party sub-processors that aren't covered by the team's data agreement,
+  and honor deletion requests. Every other field is non-PII project metadata.