qualia-framework 6.9.2 → 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
@@ -1276,7 +1277,7 @@ 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)
@@ -1305,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
@@ -1318,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..." },
         ],
       },

package/bin/report-payload.js

@@ -122,6 +122,13 @@ 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",

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)" },

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

@@ -29,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:
 
@@ -37,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 |
 
@@ -120,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.