qualia-framework 6.14.0 → 6.22.0

package/bin/verify-panel.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// verify-panel.js — deterministic aggregator for the verifier panel + skeptics.
+//
+// WHY: a single LLM judge is adversarially fragile — a lone stray token can
+// swing it (~35% false positives in the lit). R8 replaces single-pass verify
+// with (a) a PANEL of verifiers each scoring one lens (correctness / security /
+// performance / design) and (b) per-finding adversarial SKEPTICS that vote on
+// whether each finding is real. This module is the part that must NOT be a vibe:
+// it dedupes the panel's findings, applies majority-survives over the skeptic
+// votes, and computes the verdict + scores with the rules/grounding.md formula.
+// Same inputs → same verdict.
+//
+// Input (panel JSON the skill assembles from agent outputs):
+//   {
+//     "phase": 2,
+//     "lenses": ["correctness","security","performance","design"],
+//     "findings": [
+//       { "lens":"security", "file":"lib/auth.ts", "line":42,
+//         "severity":"CRITICAL", "title":"service_role reachable client-side",
+//         "votes": { "real": 2, "notReal": 1 } }
+//     ]
+//   }
+//
+// Exit 0 = PASS, 1 = FAIL, 2 = invocation error.
+// Zero npm dependencies. Library + CLI.
+
+const fs = require("fs");
+const path = require("path");
+
+const SEVERITY_WEIGHT = { CRITICAL: 8, HIGH: 4, MEDIUM: 2, LOW: 1 };
+const SEVERITY_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+
+function normSeverity(s) {
+  const up = String(s || "").toUpperCase();
+  return SEVERITY_WEIGHT[up] != null ? up : "LOW";
+}
+
+function slug(title) {
+  return String(title || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().slice(0, 48);
+}
+
+function findingKey(f) {
+  const file = String(f.file || "").replace(/\\/g, "/");
+  const line = f.line != null ? f.line : "";
+  return `${file}:${line}:${slug(f.title)}`;
+}
+
+// Merge findings that point at the same file:line:title (e.g. the correctness
+// AND security lens both flagged it). Keep the highest severity, union the
+// lenses, and sum the skeptic votes so the merged finding is judged once.
+function dedupeFindings(findings) {
+  const byKey = new Map();
+  for (const raw of findings || []) {
+    const f = {
+      file: raw.file || null,
+      line: raw.line != null ? raw.line : null,
+      title: raw.title || "",
+      severity: normSeverity(raw.severity),
+      lenses: raw.lens ? [raw.lens] : (Array.isArray(raw.lenses) ? raw.lenses.slice() : []),
+      votes: {
+        real: Number((raw.votes && raw.votes.real) || 0),
+        notReal: Number((raw.votes && raw.votes.notReal) || 0),
+      },
+    };
+    const key = findingKey(f);
+    const prev = byKey.get(key);
+    if (!prev) { byKey.set(key, f); continue; }
+    if (SEVERITY_RANK[f.severity] > SEVERITY_RANK[prev.severity]) prev.severity = f.severity;
+    for (const l of f.lenses) if (!prev.lenses.includes(l)) prev.lenses.push(l);
+    prev.votes.real += f.votes.real;
+    prev.votes.notReal += f.votes.notReal;
+  }
+  return [...byKey.values()];
+}
+
+// Majority-survives: a finding is KILLED only when the skeptics who voted are a
+// strict majority calling it not-real. With no votes recorded it survives
+// (unverified ≠ disproven — verification stays conservative).
+function survives(finding) {
+  const r = finding.votes.real;
+  const n = finding.votes.notReal;
+  if (r + n === 0) return true;
+  return !(n > r);
+}
+
+function scoreFromCounts(counts) {
+  const ws =
+    counts.CRITICAL * SEVERITY_WEIGHT.CRITICAL +
+    counts.HIGH * SEVERITY_WEIGHT.HIGH +
+    counts.MEDIUM * SEVERITY_WEIGHT.MEDIUM +
+    counts.LOW * SEVERITY_WEIGHT.LOW;
+  return Math.max(1, 5 - Math.floor(ws / 8));
+}
+
+function emptyCounts() {
+  return { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+}
+
+function aggregate(panel) {
+  const deduped = dedupeFindings(panel.findings || []);
+  const surviving = [];
+  const killed = [];
+  for (const f of deduped) {
+    (survives(f) ? surviving : killed).push({ ...f, verified: f.votes.real + f.votes.notReal > 0 });
+  }
+
+  const counts = emptyCounts();
+  const perLens = {};
+  for (const lens of panel.lenses || []) perLens[lens] = emptyCounts();
+  for (const f of surviving) {
+    counts[f.severity]++;
+    for (const lens of f.lenses) {
+      if (!perLens[lens]) perLens[lens] = emptyCounts();
+      perLens[lens][f.severity]++;
+    }
+  }
+
+  // A surviving CRITICAL or HIGH fails the phase (rules/grounding.md severity).
+  const verdict = counts.CRITICAL === 0 && counts.HIGH === 0 ? "PASS" : "FAIL";
+  const perLensScores = {};
+  for (const [lens, c] of Object.entries(perLens)) perLensScores[lens] = scoreFromCounts(c);
+
+  return {
+    ok: verdict === "PASS",
+    verdict,
+    phase: panel.phase != null ? panel.phase : null,
+    counts,
+    score: scoreFromCounts(counts),
+    per_lens_scores: perLensScores,
+    surviving,
+    killed,
+    totals: { findings: deduped.length, surviving: surviving.length, killed: killed.length },
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+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 === "--write") args.write = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  verify-panel.js <panel.json> [--json] [--write] [--cwd DIR]",
+    "",
+    "Aggregates panel findings + skeptic votes → deterministic verdict.",
+    "Exit 0 = PASS, 1 = FAIL, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function toMarkdown(r) {
+  const lines = [];
+  lines.push(`# Verifier Panel — phase ${r.phase}`);
+  lines.push("");
+  lines.push(`result: ${r.verdict}`);
+  lines.push(`score: ${r.score}/5`);
+  lines.push(`findings: ${r.totals.surviving} surviving / ${r.totals.killed} killed by skeptics`);
+  lines.push("");
+  lines.push(`Severity (surviving): CRITICAL ${r.counts.CRITICAL} · HIGH ${r.counts.HIGH} · MEDIUM ${r.counts.MEDIUM} · LOW ${r.counts.LOW}`);
+  lines.push("");
+  if (r.surviving.length) {
+    lines.push("## Surviving findings");
+    for (const f of r.surviving) {
+      const where = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "(no location)";
+      lines.push(`- **[${f.severity}]** ${f.title} — ${where} _(lens: ${f.lenses.join(", ") || "?"}; votes ${f.votes.real}✓/${f.votes.notReal}✗)_`);
+    }
+    lines.push("");
+  }
+  if (r.killed.length) {
+    lines.push("## Killed by skeptics (majority not-real)");
+    for (const f of r.killed) {
+      const where = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "(no location)";
+      lines.push(`- ~~[${f.severity}] ${f.title}~~ — ${where} _(votes ${f.votes.real}✓/${f.votes.notReal}✗)_`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+// Assemble per-lens finding files (.planning/phase-{N}-panel-{lens}.json, each
+// an array of {file,line,severity,title}) into one panel.json — findings tagged
+// with their lens, votes zeroed for the skeptic pass to fill. Deterministic so
+// the orchestrator never hand-builds the panel skeleton.
+function assemble(root, phase) {
+  const dir = path.join(root, ".planning");
+  const re = new RegExp(`^phase-${phase}-panel-([a-z]+)\\.json$`);
+  const lenses = [];
+  const findings = [];
+  let files = [];
+  try { files = fs.readdirSync(dir); } catch { files = []; }
+  for (const f of files.sort()) {
+    const m = f.match(re);
+    if (!m) continue;
+    const lens = m[1];
+    let arr;
+    try { arr = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); } catch { continue; }
+    if (!Array.isArray(arr)) continue;
+    lenses.push(lens);
+    for (const item of arr) {
+      findings.push({
+        lens,
+        file: item.file || null,
+        line: item.line != null ? item.line : null,
+        severity: item.severity || "LOW",
+        title: item.title || "",
+        votes: { real: 0, notReal: 0 },
+      });
+    }
+  }
+  return { phase: Number(phase), lenses, findings };
+}
+
+function main(argv) {
+  // assemble subcommand: verify-panel.js assemble <phase> [--cwd DIR]
+  if (argv[2] === "assemble") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    if (phase == null) { usage(); return 2; }
+    const root = path.resolve(sub.cwd || process.cwd());
+    const panel = assemble(root, phase);
+    const out = path.join(root, ".planning", `phase-${phase}-panel.json`);
+    try {
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, JSON.stringify(panel, null, 2) + "\n");
+    } catch (e) {
+      console.error(`ERROR: could not write ${out}: ${e.message}`);
+      return 2;
+    }
+    console.log(`assembled ${panel.findings.length} finding(s) from ${panel.lenses.length} lens file(s) → ${path.relative(root, out)}`);
+    return 0;
+  }
+
+  const args = parseArgs(argv);
+  const panelPath = args._[0];
+  if (!panelPath || panelPath === "-h" || panelPath === "--help") { usage(); return 2; }
+  const root = path.resolve(args.cwd || process.cwd());
+
+  let panel;
+  try {
+    panel = JSON.parse(fs.readFileSync(path.resolve(root, panelPath), "utf8"));
+  } catch (e) {
+    console.error(`ERROR: cannot read panel JSON: ${e.message}`);
+    return 2;
+  }
+
+  const result = aggregate(panel);
+
+  if (args.write && result.phase != null) {
+    const dir = path.join(root, ".planning");
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, `phase-${result.phase}-verification-panel.json`), JSON.stringify(result, null, 2) + "\n");
+      fs.writeFileSync(path.join(dir, `phase-${result.phase}-verification-panel.md`), toMarkdown(result));
+    } catch (e) {
+      console.error(`WARN: could not write panel artifacts: ${e.message}`);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`PANEL ${result.verdict} phase ${result.phase}: ` +
+      `${result.totals.surviving} surviving (${result.counts.CRITICAL}C/${result.counts.HIGH}H/${result.counts.MEDIUM}M/${result.counts.LOW}L), ` +
+      `${result.totals.killed} killed by skeptics, score ${result.score}/5`);
+    if (!result.ok) for (const f of result.surviving) {
+      if (f.severity === "CRITICAL" || f.severity === "HIGH") {
+        console.log(`  [${f.severity}] ${f.title} — ${f.file || "?"}${f.line != null ? `:${f.line}` : ""}`);
+      }
+    }
+  }
+  return result.ok ? 0 : 1;
+}
+
+module.exports = {
+  dedupeFindings,
+  survives,
+  scoreFromCounts,
+  aggregate,
+  assemble,
+  SEVERITY_WEIGHT,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/wave-plan.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// wave-plan.js — derive a deterministic build schedule from the task DAG.
+//
+// WHY: /qualia-build spawned EVERY task in a contract "wave" concurrently, with
+// no cap. That's two failure modes at once:
+//   1. Over-serialization — the planner's hand-numbered waves can be deeper than
+//      the dependency graph requires (tasks that COULD run together placed in
+//      separate waves), so the build is slower than necessary.
+//   2. Over-parallelization — a wide wave (say 9 independent tasks) spawns 9
+//      concurrent builders, past the 3–5 sweet spot where coordination +
+//      context cost overwhelms the gain (the LangGraph max_concurrency lesson).
+//
+// This recomputes waves from `depends_on` (minimal-depth topological levels —
+// maximal safe parallelism) and splits each level into batches capped at
+// max_concurrency. Output is an ordered list of batches the orchestrator spawns
+// one at a time. Deterministic: same contract + same cap → same schedule.
+//
+// max_concurrency:
+//   --parallel N  → exactly N (N ≥ 1)
+//   auto (default)→ 1 if < 3 total tasks ("don't parallelize tiny phases"),
+//                   else SWEET (5).
+//
+// Zero npm dependencies. Library + CLI. Exit 0 ok, 1 cycle, 2 invocation error.
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("./plan-contract.js");
+
+const SWEET = 5;
+
+function numericId(id) {
+  const m = String(id).match(/\d+/);
+  return m ? Number(m[0]) : 0;
+}
+
+// Minimal-depth level for each task: level = 1 + max(level(deps)); roots = 1.
+// Returns { levels: Map<id,level>, cycle: [...] | null }.
+function deriveLevels(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const levels = new Map();
+  const visiting = new Set();
+
+  function depth(id, trail) {
+    if (levels.has(id)) return levels.get(id);
+    if (visiting.has(id)) {
+      const err = new Error("cycle");
+      err.cycle = [...trail, id];
+      throw err;
+    }
+    const t = byId.get(id);
+    const deps = (t && t.depends_on) || [];
+    visiting.add(id);
+    let max = 0;
+    for (const d of deps) {
+      if (!byId.has(d)) continue; // unknown dep — plan-contract validates this separately
+      max = Math.max(max, depth(d, [...trail, id]));
+    }
+    visiting.delete(id);
+    const lvl = max + 1;
+    levels.set(id, lvl);
+    return lvl;
+  }
+
+  try {
+    for (const t of tasks) depth(t.id, []);
+  } catch (e) {
+    if (e.cycle) return { levels: null, cycle: e.cycle };
+    throw e;
+  }
+  return { levels, cycle: null };
+}
+
+function resolveConcurrency(taskCount, parallel) {
+  if (parallel != null) {
+    const n = Number(parallel);
+    if (!Number.isFinite(n) || n < 1) throw new Error(`--parallel must be an integer ≥ 1 (got ${parallel})`);
+    return Math.floor(n);
+  }
+  return taskCount < 3 ? 1 : SWEET;
+}
+
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+function plan(contract, opts = {}) {
+  const tasks = (contract.tasks || []).slice();
+  const { levels, cycle } = deriveLevels(tasks);
+  if (cycle) return { ok: false, error: "CYCLE", cycle: cycle.join(" → ") };
+
+  const maxConcurrency = resolveConcurrency(tasks.length, opts.parallel);
+
+  // Group task ids by derived level, ordered numerically within a level.
+  const byLevel = new Map();
+  for (const t of tasks) {
+    const lvl = levels.get(t.id);
+    if (!byLevel.has(lvl)) byLevel.set(lvl, []);
+    byLevel.get(lvl).push(t.id);
+  }
+  const sortedLevels = [...byLevel.keys()].sort((a, b) => a - b);
+
+  // Emit batches: each derived level split into ≤ maxConcurrency chunks.
+  const batches = [];
+  for (const lvl of sortedLevels) {
+    const ids = byLevel.get(lvl).sort((a, b) => numericId(a) - numericId(b));
+    for (const group of chunk(ids, maxConcurrency)) {
+      batches.push({ wave: lvl, batch: batches.length + 1, tasks: group });
+    }
+  }
+
+  // Note where the planner's declared wave is deeper than necessary (the DAG
+  // permits more parallelism than the contract used).
+  const notes = [];
+  const declared = new Map(tasks.map((t) => [t.id, t.wave]));
+  let overSerialized = 0;
+  for (const t of tasks) {
+    const d = declared.get(t.id);
+    const derived = levels.get(t.id);
+    if (typeof d === "number" && d > derived) overSerialized++;
+  }
+  if (overSerialized > 0) {
+    notes.push(`${overSerialized} task(s) declared a deeper wave than the dependency graph requires — the schedule below runs them earlier (more parallel).`);
+  }
+  const widest = Math.max(0, ...sortedLevels.map((l) => byLevel.get(l).length));
+  if (widest > maxConcurrency) {
+    notes.push(`widest level has ${widest} independent tasks; capped to batches of ${maxConcurrency}.`);
+  }
+
+  return {
+    ok: true,
+    phase: contract.phase != null ? contract.phase : null,
+    task_count: tasks.length,
+    max_concurrency: maxConcurrency,
+    derived_levels: sortedLevels.length,
+    batch_count: batches.length,
+    batches,
+    notes,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+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 === "--parallel") args.parallel = argv[++i];
+    else if (a.startsWith("--parallel=")) args.parallel = a.slice(11);
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  wave-plan.js <contract.json> [--parallel N] [--json] [--cwd DIR]",
+    "",
+    "Derives a dependency-ordered, concurrency-capped build schedule.",
+    "Exit 0 = ok, 1 = cycle in DAG, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const contractPath = args._[0];
+  if (!contractPath || contractPath === "-h" || contractPath === "--help") { usage(); return 2; }
+  const root = path.resolve(args.cwd || process.cwd());
+
+  const loaded = pc.readContractFile(path.resolve(root, contractPath));
+  if (!loaded.ok) {
+    if (args.json) console.log(JSON.stringify({ ok: false, ...loaded }));
+    else console.error(`${loaded.error}: ${loaded.message}`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = plan(loaded.contract, { parallel: args.parallel });
+  } catch (e) {
+    if (args.json) console.log(JSON.stringify({ ok: false, error: "BAD_ARG", message: e.message }));
+    else console.error(`ERROR: ${e.message}`);
+    return 2;
+  }
+
+  if (!result.ok) {
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else console.error(`${result.error}: ${result.cycle || ""}`);
+    return result.error === "CYCLE" ? 1 : 2;
+  }
+
+  if (args.json) { console.log(JSON.stringify(result, null, 2)); return 0; }
+
+  console.log(`Build schedule — phase ${result.phase}: ${result.task_count} task(s), ` +
+    `${result.batch_count} batch(es), max ${result.max_concurrency} concurrent`);
+  for (const b of result.batches) {
+    console.log(`  wave ${b.wave} · batch ${b.batch}: ${b.tasks.join(", ")}`);
+  }
+  for (const n of result.notes) console.log(`  note: ${n}`);
+  return 0;
+}
+
+module.exports = { deriveLevels, resolveConcurrency, plan, SWEET };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/docs/erp-contract.md

@@ -346,6 +346,151 @@ Snapshot shape:
 }
 ```
 
+## Project Sync Payload (reconciliation)
+
+`qualia-framework project-sync` builds the **single complete project-sync snapshot** — the one payload the ERP reads to RECONCILE a project's milestones, phases, tasks, and reports in one pass, and to understand the PR/merge model that maps a feature branch to deployed `main`.
+
+It is distinct from the two existing emitters:
+- `POST /api/v1/reports` (report-payload.js) = ONE work session.
+- `POST /api/v1/project-snapshots` (project-snapshot.js) = lean progress rollup for dashboards (`progress_percent`).
+- **project-sync** = the FULL reconciliation surface: every milestone with REQ-ID completion, current position, task rollup, accountability counters, and the trunk/merge model. project-sync **composes** project-snapshot's identity/current/journey/lifetime/quality blocks (no duplication) and enriches them.
+
+```text
+qualia-framework project-sync            # print JSON (compact) to stdout
+qualia-framework project-sync --json     # print JSON (pretty)
+qualia-framework project-sync --write    # persist .planning/snapshots/project-sync-<ts>.json
+```
+
+Exit 0 = built; exit 2 = no `.planning/` (run `/qualia-new`). Read-only, zero dependencies. Graceful when JOURNEY.md / REQUIREMENTS.md / fields are absent (milestones still emit, REQ blocks report `tracked: false`).
+
+### Payload shape
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-06-21T00:00:00.000Z",
+  "source": "qualia-framework",
+  "payload": "project-sync",
+  "framework_version": "6.14.0",
+  "identifiers": {
+    "project_id": "qs-acme-portal",
+    "team_id": "qualia-solutions",
+    "git_remote": "github.com/QualiasolutionsCY/acme-portal",
+    "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef"
+  },
+  "project": {
+    "name": "acme-portal",
+    "client": "Acme",
+    "status": "built",
+    "deployed_url": "https://client.vercel.app",
+    "progress_percent": 42,
+    "lifecycle": "build",
+    "launched_at": "2026-05-01T00:00:00Z"
+  },
+  "current": {
+    "milestone": 2, "milestone_name": "Product",
+    "phase": 2, "phase_name": "Dashboard", "total_phases": 4,
+    "tasks_done": 3, "tasks_total": 5,
+    "verification": "pending", "gap_cycles": 1
+  },
+  "quality": { "harness_eval": { "status": "PASS", "score": 92, "phase": 2, "generated_at": "…", "artifact": "…" } },
+  "total_milestones": 3,
+  "milestones": [
+    {
+      "num": 1, "name": "Foundation", "status": "closed",
+      "phases": 3, "tasks_completed": 12,
+      "requirements": { "tracked": true, "total": 4, "complete": 4, "incomplete": [] },
+      "closed_at": "2026-04-10T18:00:00Z",
+      "deployed_url": "https://m1.vercel.app"
+    },
+    {
+      "num": 2, "name": "Product", "status": "current",
+      "phases": 4, "tasks_completed": 0,
+      "requirements": { "tracked": true, "total": 5, "complete": 3,
+        "incomplete": [ { "id": "CORE-03", "status": "Incomplete" } ] }
+    },
+    {
+      "num": 3, "name": "Handoff", "status": "future",
+      "phases": 0, "tasks_completed": 0,
+      "requirements": { "tracked": false, "total": 0, "complete": 0, "incomplete": [] }
+    }
+  ],
+  "task_rollup": {
+    "tasks_completed": 15, "phases_completed": 4, "milestones_completed": 1,
+    "total_phases_all_milestones": 7, "build_count": 4, "deploy_count": 1,
+    "current_phase_gap_cycles": 1
+  },
+  "accountability": {
+    "offroad_count": 2,
+    "offroad": [ { "at": "2026-06-01T10:00:00Z", "milestone": 2, "ref": "BUG-7", "note": "hotfix login" } ]
+  },
+  "integration": {
+    "model": "trunk",
+    "integrates_at": "/qualia-ship",
+    "protected_branches": ["main", "master"],
+    "main_push_event_type": "employee_main_push",
+    "main_push_events_path": "~/.claude/.main-push-events.json",
+    "note": "Feature branches integrate to main at /qualia-ship (then deploy). Direct pushes to a protected branch are allowed but recorded as employee_main_push policy events for per-employee accountability."
+  },
+  "timestamps": { "session_started_at": "", "last_pushed_at": "", "last_updated": "" }
+}
+```
+
+### Field meanings
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | project-sync contract version. The ERP branches on this to evolve the shape safely. **Distinct** from `snapshot_version` (project-snapshot). |
+| `payload` | Always `"project-sync"` — discriminates this from the report / snapshot payloads when they share an endpoint or queue. |
+| `identifiers` | Same resolution block as project-snapshot — `erp_project_id` is the strongest link, then `git_remote`, then `(team_id, project_id)`. |
+| `project.lifecycle` | `build` (milestone journey) or `operate` (post-launch update stream). The ERP stops expecting a handoff for an `operate` project. |
+| `project.launched_at` / `launch_source` | Present once launched; lets the ERP date the build→operate transition. |
+| `current.*` | The active milestone/phase position + verification + flattened `gap_cycles` (number, current phase). |
+| `total_milestones` | Denominator for milestone-completion (from JOURNEY.md, else max known). |
+| `milestones[]` | The reconciliation spine — every known milestone (journey ∪ closed ∪ current), ordered by num. |
+| `milestones[].status` | `closed` \| `current` \| `future`. The ERP marks done / in-progress / pending from this. |
+| `milestones[].phases` | Phase count: `phases_completed` for closed milestones; the current roadmap phase count for the active one; 0 for future. |
+| `milestones[].tasks_completed` | Tasks completed within that milestone (closed summaries carry this; 0 for current/future — use `task_rollup` for cumulative). |
+| `milestones[].requirements` | REQ-ID completion from REQUIREMENTS.md: `tracked` (false ⇒ no REQ rows declared for this milestone, ERP skips the REQ gate), `total`, `complete`, `incomplete[]` (`{id, status}`). |
+| `milestones[].closed_at` / `deployed_url` | Present when the closed-milestone summary carries them. |
+| `task_rollup` | Cumulative counters so the ERP rolls tasks up without replaying every report: lifetime tasks/phases/milestones, `total_phases_all_milestones`, build/deploy counts, current-phase gap cycles. |
+| `accountability.offroad_count` | Count of off-milestone work units (mirrors the branch-guard main-push tally — drift is counted, not hidden). |
+| `accountability.offroad[]` | Last 10 off-road entries: `{at, milestone, ref, note}`. |
+| `integration` | The PR/merge model (see below). |
+
+### How the ERP reconciles from this payload
+
+1. **Resolve the project** via `identifiers` (same precedence as reports/snapshots).
+2. **Milestones** — upsert each `milestones[]` entry by `num`. Set the ERP milestone state from `status` (`closed`→done, `current`→in-progress, `future`→pending). When `requirements.tracked` is true, the milestone is **complete only if** `complete === total`; surface `incomplete[]` REQ-IDs as the remaining work. When `tracked` is false, fall back to `status` alone (no REQ table was declared).
+3. **Phases** — `milestones[].phases` + `current.total_phases` give per-milestone phase counts; `task_rollup.total_phases_all_milestones` is the grand total across the whole journey.
+4. **Tasks** — use `task_rollup.tasks_completed` for the cumulative figure and `milestones[].tasks_completed` for per-closed-milestone attribution. Do **not** sum reports to get this — the rollup is authoritative.
+5. **Reports** — project-sync does not carry session notes; it reconciles *state*, while `/api/v1/reports` carries each *session*. Reconcile both against the same resolved project: reports for the activity feed, project-sync for the milestone/phase/task tree.
+6. **Accountability** — store `offroad_count` per project so off-milestone drift is visible alongside the per-employee `employee_main_push` tally from `/api/v1/policy-events`.
+
+### PR / merge model (what the ERP must understand)
+
+The framework uses **trunk integration**, surfaced in `integration`:
+
+- Work happens on a **feature branch** (`branch-guard` enforces feature-branch-only; `main`/`master` are protected).
+- `/qualia-ship` **integrates the feature branch into `main`** and then deploys (`integrates_at: "/qualia-ship"`). There is no long-lived release branch; `main` is always the deployable trunk.
+- A direct push to a protected branch is **allowed, not blocked** — but `branch-guard` records an `employee_main_push` policy event (`POST /api/v1/policy-events`, keyed by `(type, actor_code)`) for per-employee accountability. The local journal lives at `main_push_events_path` (`~/.claude/.main-push-events.json`) in the install home; project-sync **references** it, it does not read across the home boundary.
+
+So the branch→main→deploy mapping the ERP should encode: **a milestone's `deployed_url` + `status: closed` means its feature work was integrated to `main` and shipped via `/qualia-ship`.** Main-push events are the exception trail, not the normal integration path.
+
+---
+
+## Framework emits (this repo) vs ERP ingests (backend — out of scope here)
+
+**Framework emits (delivered in this repo):**
+- `qualia-framework project-sync [--json|--write]` builds and (optionally) persists the payload above.
+- Deterministic, read-only, zero-dependency; composes project-snapshot; graceful on missing fields.
+- The payload SHAPE and field semantics documented in this section are the contract.
+
+**ERP ingests (backend work — NOT in this repo):**
+- A `POST /api/v1/project-sync` endpoint (or extend project-snapshots to accept `payload: "project-sync"`) that authenticates the Bearer key and validates `schema_version`.
+- Project resolution + the reconciliation logic in "How the ERP reconciles" above — upserting milestones/phases/tasks, marking completion from REQ counts, and storing `offroad_count`.
+- Wiring an upload path (the framework's `project-snapshot.js` already has `uploadSnapshot()`/retry plumbing the ERP team can mirror for project-sync once the endpoint exists). project-sync itself ships **emit + document** only; the HTTP upload + server-side ingest are the backend's to build.
+
 ## Behavior
 
 - When `erp.enabled` is `false`, `/qualia-report` skips the upload and prints an info line so the employee knows the report stayed local.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.14.0",
+  "version": "6.22.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -33,7 +33,8 @@
     "test:statusline": "bash tests/statusline.test.sh",
     "test:refs": "bash tests/refs.test.sh",
     "test:published-install": "bash tests/published-install-smoke.test.sh",
-    "test:shell": "bash tests/run-all.sh"
+    "test:shell": "bash tests/run-all.sh",
+    "compile:instructions": "node bin/compile-instructions.js"
   },
   "files": [
     "bin/",