qualia-framework 4.1.1 → 4.4.0

package/bin/plan-contract.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// Plan contract validator + helpers. See docs/plan-contract.md.
+//
+// Pure library — no CLI dispatch. Required by state.js and by skills that
+// emit/consume `.planning/phase-{N}-contract.json`.
+//
+// Zero npm dependencies. Hand-rolled validator, ~100 LOC.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+
+const PERSONAS = new Set([
+  "security", "architect", "ux", "frontend",
+  "backend", "data", "performance", "none",
+]);
+
+const CHECK_TYPES = new Set([
+  "file-exists", "grep-match", "command-exit", "behavioral",
+]);
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function isPlainObject(v) {
+  return v && typeof v === "object" && !Array.isArray(v);
+}
+
+function validateCheck(check, taskId, idx) {
+  const errs = [];
+  const where = `tasks[id=${taskId}].verification[${idx}]`;
+  if (!isPlainObject(check)) return [`${where}: not an object`];
+  if (!CHECK_TYPES.has(check.type)) {
+    errs.push(`${where}.type: must be one of ${[...CHECK_TYPES].join("|")}`);
+    return errs;
+  }
+  switch (check.type) {
+    case "file-exists":
+      if (typeof check.path !== "string" || !check.path) errs.push(`${where}.path: required string`);
+      if (check.must_contain != null && typeof check.must_contain !== "string") errs.push(`${where}.must_contain: must be string`);
+      break;
+    case "grep-match":
+      if (typeof check.path !== "string" || !check.path) errs.push(`${where}.path: required string`);
+      if (typeof check.pattern !== "string" || !check.pattern) errs.push(`${where}.pattern: required string`);
+      else { try { new RegExp(check.pattern); } catch { errs.push(`${where}.pattern: invalid regex`); } }
+      if (check.expect !== "present" && check.expect !== "absent") errs.push(`${where}.expect: must be "present" or "absent"`);
+      break;
+    case "command-exit":
+      if (typeof check.command !== "string" || !check.command) errs.push(`${where}.command: required string`);
+      else if (/[;&|`$<>(){}\\]/.test(check.command)) errs.push(`${where}.command: shell metacharacters not allowed (use args[])`);
+      if (!isStringArray(check.args || [])) errs.push(`${where}.args: must be string[]`);
+      if (typeof check.expected_exit !== "number") errs.push(`${where}.expected_exit: required number`);
+      if (check.timeout_ms != null && (typeof check.timeout_ms !== "number" || check.timeout_ms <= 0)) {
+        errs.push(`${where}.timeout_ms: must be positive number`);
+      }
+      if (check.expect_stdout_match != null) {
+        if (typeof check.expect_stdout_match !== "string") errs.push(`${where}.expect_stdout_match: must be string`);
+        else { try { new RegExp(check.expect_stdout_match); } catch { errs.push(`${where}.expect_stdout_match: invalid regex`); } }
+      }
+      break;
+    case "behavioral":
+      if (typeof check.description !== "string" || !check.description) errs.push(`${where}.description: required string`);
+      if (!Array.isArray(check.evidence_required) || check.evidence_required.length === 0) {
+        errs.push(`${where}.evidence_required: must be a non-empty array`);
+      } else {
+        check.evidence_required.forEach((ev, i) => {
+          const w = `${where}.evidence_required[${i}]`;
+          if (!isPlainObject(ev)) { errs.push(`${w}: not an object`); return; }
+          if (typeof ev.path !== "string" || !ev.path) errs.push(`${w}.path: required string`);
+          if (typeof ev.description !== "string" || !ev.description) errs.push(`${w}.description: required string`);
+          if (ev.matcher != null) {
+            if (typeof ev.matcher !== "string") errs.push(`${w}.matcher: must be string`);
+            else { try { new RegExp(ev.matcher); } catch { errs.push(`${w}.matcher: invalid regex`); } }
+          }
+        });
+      }
+      break;
+  }
+  return errs;
+}
+
+function validateTask(task, idx, allIds) {
+  const errs = [];
+  const where = `tasks[${idx}]`;
+  if (!isPlainObject(task)) return [`${where}: not an object`];
+  if (typeof task.id !== "string" || !/^T\d+$/.test(task.id)) errs.push(`${where}.id: must match ^T\\d+$`);
+  if (typeof task.title !== "string" || !task.title) errs.push(`${where}.title: required string`);
+  if (typeof task.wave !== "number" || task.wave < 1) errs.push(`${where}.wave: must be positive number`);
+  if (!isStringArray(task.depends_on || [])) errs.push(`${where}.depends_on: must be string[]`);
+  if (task.persona != null && !PERSONAS.has(task.persona)) errs.push(`${where}.persona: invalid value`);
+  if (!isStringArray(task.files_modify || [])) errs.push(`${where}.files_modify: must be string[]`);
+  if (!isStringArray(task.files_create || [])) errs.push(`${where}.files_create: must be string[]`);
+  if (!isStringArray(task.files_delete || [])) errs.push(`${where}.files_delete: must be string[]`);
+  if (!isStringArray(task.acceptance_criteria || []) || (task.acceptance_criteria || []).length === 0) {
+    errs.push(`${where}.acceptance_criteria: must be a non-empty string[]`);
+  }
+  if (typeof task.action !== "string") errs.push(`${where}.action: required string`);
+  else if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+  if (!isStringArray(task.context_files || [])) errs.push(`${where}.context_files: must be string[]`);
+  if (!Array.isArray(task.verification) || task.verification.length === 0) {
+    errs.push(`${where}.verification: must be a non-empty array`);
+  } else {
+    task.verification.forEach((c, i) => errs.push(...validateCheck(c, task.id, i)));
+  }
+
+  // disjointness across files_modify/create/delete
+  const m = new Set(task.files_modify || []);
+  const c = new Set(task.files_create || []);
+  const d = new Set(task.files_delete || []);
+  for (const p of m) if (c.has(p) || d.has(p)) errs.push(`${where}: ${p} appears in multiple file lists`);
+  for (const p of c) if (d.has(p)) errs.push(`${where}: ${p} appears in multiple file lists`);
+
+  // depends_on references must exist
+  for (const dep of task.depends_on || []) {
+    if (!allIds.has(dep)) errs.push(`${where}.depends_on: references unknown id "${dep}"`);
+  }
+  return errs;
+}
+
+function detectCycles(tasks) {
+  const graph = new Map(tasks.map((t) => [t.id, t.depends_on || []]));
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map([...graph.keys()].map((k) => [k, WHITE]));
+  const cycles = [];
+  function dfs(u, stack) {
+    color.set(u, GRAY);
+    stack.push(u);
+    for (const v of graph.get(u) || []) {
+      if (!graph.has(v)) continue;
+      const cv = color.get(v);
+      if (cv === GRAY) { cycles.push([...stack, v].join(" → ")); return; }
+      if (cv === WHITE) dfs(v, stack);
+    }
+    color.set(u, BLACK);
+    stack.pop();
+  }
+  for (const k of graph.keys()) if (color.get(k) === WHITE) dfs(k, []);
+  return cycles;
+}
+
+function validate(contract) {
+  const errs = [];
+  if (!isPlainObject(contract)) return ["contract: not an object"];
+  if (contract.version !== SCHEMA_VERSION) errs.push(`version: must be ${SCHEMA_VERSION}, got ${contract.version}`);
+  if (typeof contract.phase !== "number" || contract.phase < 1) errs.push("phase: must be positive number");
+  if (typeof contract.goal !== "string" || !contract.goal) errs.push("goal: required string");
+  if (typeof contract.why !== "string" || !contract.why) errs.push("why: required string");
+  if (typeof contract.generated_at !== "string") errs.push("generated_at: required ISO 8601 string");
+  if (!["planner", "compile-plan", "manual"].includes(contract.generated_by)) {
+    errs.push('generated_by: must be "planner" | "compile-plan" | "manual"');
+  }
+  if (typeof contract.source_plan_hash !== "string") errs.push("source_plan_hash: required string (empty for manual)");
+  if (!isStringArray(contract.success_criteria || []) || (contract.success_criteria || []).length === 0) {
+    errs.push("success_criteria: must be a non-empty string[]");
+  }
+  if (!Array.isArray(contract.tasks) || contract.tasks.length === 0) {
+    errs.push("tasks: must be a non-empty array");
+    return errs;
+  }
+
+  const ids = new Set();
+  for (const t of contract.tasks) {
+    if (t && typeof t.id === "string") {
+      if (ids.has(t.id)) errs.push(`tasks: duplicate id "${t.id}"`);
+      ids.add(t.id);
+    }
+  }
+
+  contract.tasks.forEach((t, i) => errs.push(...validateTask(t, i, ids)));
+
+  const cycles = detectCycles(contract.tasks);
+  if (cycles.length) errs.push(`tasks: cycle detected: ${cycles[0]}`);
+
+  // wave > max(deps wave)
+  const byId = new Map(contract.tasks.map((t) => [t.id, t]));
+  for (const t of contract.tasks) {
+    const deps = (t.depends_on || []).map((id) => byId.get(id)).filter(Boolean);
+    if (deps.length === 0) continue;
+    const maxDepWave = Math.max(...deps.map((d) => d.wave || 0));
+    if ((t.wave || 0) <= maxDepWave) {
+      errs.push(`tasks[id=${t.id}].wave: must be > ${maxDepWave} (max wave of its dependencies)`);
+    }
+  }
+
+  return errs;
+}
+
+function parseSafely(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function hashPlan(text) {
+  return "sha256:" + crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function checkDrift(contractPath, planMdPath) {
+  if (!fs.existsSync(contractPath)) return { ok: false, reason: "contract-missing" };
+  if (!fs.existsSync(planMdPath)) return { ok: false, reason: "plan-md-missing" };
+  const parsed = parseSafely(fs.readFileSync(contractPath, "utf8"));
+  if (!parsed.ok) return { ok: false, reason: "contract-unparseable", detail: parsed.error };
+  const stored = parsed.value.source_plan_hash;
+  if (!stored) return { ok: true, drift: false, reason: "no-hash-stored" };
+  const current = hashPlan(fs.readFileSync(planMdPath, "utf8"));
+  return { ok: true, drift: stored !== current, stored, current };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  validate,
+  parseSafely,
+  hashPlan,
+  checkDrift,
+};

package/bin/state.js

@@ -104,11 +104,14 @@ function acquireLock(timeoutMs = 5000) {
       sleepSync(50);
     }
   }
-  // Couldn't acquire inside the budget — proceed unlocked rather than
-  // hard-block the user. Surface this in analytics so repeated contention
-  // is visible instead of silent.
-  try { _trace("state-lock", "fallthrough", { waited_ms: Date.now() - start }); } catch {}
-  return null;
+  const waited = Date.now() - start;
+  try { _trace("state-lock", "timeout", { waited_ms: waited }); } catch {}
+  const err = new Error(
+    `Could not acquire ${LOCK_FILE} after ${waited}ms. Another state mutation may still be running.`
+  );
+  err.code = "STATE_LOCK_TIMEOUT";
+  err.waited_ms = waited;
+  throw err;
 }
 
 function releaseLock(lock) {
@@ -1297,9 +1300,8 @@ const opts = parseArgs(rest);
 
 // Mutators must hold the .planning/.state.lock for the duration of their
 // dual STATE.md + tracking.json writes. Read commands (check, validate-plan)
-// don't need the lock. The lock is best-effort: if it can't be acquired
-// inside acquireLock's timeout, the command proceeds anyway — we'd rather
-// risk a rare race than hard-block the user.
+// don't need the lock. A lock timeout is a hard failure for mutators; racing
+// state writes are worse than asking the user to retry.
 const READ_ONLY = new Set(["check", "validate-plan"]);
 let __lock = null;
 if (!READ_ONLY.has(cmd)) {
@@ -1307,7 +1309,11 @@ if (!READ_ONLY.has(cmd)) {
   // previous mutator. Runs for mutators only; read commands should still
   // return the actual on-disk state even if it's mid-recovery.
   try { recoverFromJournal(); } catch {}
-  __lock = acquireLock();
+  try {
+    __lock = acquireLock();
+  } catch (err) {
+    output(fail(err.code || "STATE_LOCK_ERROR", err.message));
+  }
   process.on("exit", () => releaseLock(__lock));
   process.on("SIGINT", () => { releaseLock(__lock); process.exit(130); });
   process.on("SIGTERM", () => { releaseLock(__lock); process.exit(143); });

package/docs/agent-runs.md

@@ -0,0 +1,273 @@
+# Agent Runs Telemetry
+
+Append-only JSONL ledger of every subagent spawn, recorded per project. Substrate for `qualia-framework agents`, postmortem analysis, and ERP enrichment.
+
+Status: **draft, v1.** Pressure-test the shape against real spawns before locking.
+
+## Why this exists
+
+Today, `traces.jsonl` records hook-level events only. There is zero per-agent telemetry: no record of which builder ran for how long on which task, which verifier failed and why, which researcher hit a rate limit. The data needed to answer "which task failed twice and required a postmortem" doesn't exist.
+
+This file specifies a per-spawn record that lives next to the project (not in `~/.claude/`) so it travels with the repo, is committed alongside other planning artifacts, and stays attributable to a specific phase.
+
+## File layout
+
+```
+.planning/
+  agent-runs.jsonl          # all-time, append-only
+  agent-runs/
+    2026-04-28.jsonl        # daily rotation (optional, see below)
+```
+
+**Rotation:** start with single-file. If `agent-runs.jsonl` exceeds 5MB, rotate to dated subfile. Cheap, no dependency.
+
+**Privacy:** records contain file paths, task ids, durations, token counts, error strings — never command output, never file contents, never user prompts. The schema below is the upper bound of what we capture. `QUALIA_TELEMETRY=off` env var disables writes.
+
+## Schema (v1)
+
+OpenTelemetry GenAI semantic conventions where they fit; framework-specific fields where they don't.
+
+```ts
+interface AgentRunRecord {
+  // Identity
+  schema_version: 1;
+  run_id: string;                    // ULID — sortable, monotonic
+  parent_run_id?: string;            // ONLY for true nesting (an agent spawned this one); null otherwise
+  skill_invocation_id: string;       // groups runs from one skill call (sequential or parallel siblings)
+  session_id?: string;                // Claude Code session id when reachable; per-process UUID fallback
+
+  // What ran
+  agent_type: AgentType;
+  agent_name?: string;               // for custom agents (e.g. "frontend-agent")
+  model: string;                     // "claude-opus-4-7", "claude-sonnet-4-6", etc.
+  effort?: "low" | "medium" | "high" | "max";
+
+  // Where in the road
+  project: string;                   // tracking.json.project
+  phase?: number;                    // current phase if applicable
+  milestone?: number;
+  task_id?: string;                  // contract task id ("T1", "T2") for builders
+  wave?: number;
+  retry_of?: string;                 // run_id of the prior failed attempt this one is retrying
+
+  // Lifecycle
+  status: AgentStatus;
+  started_at: string;                // ISO 8601 UTC
+  finished_at: string;               // ISO 8601 UTC
+  duration_ms: number;
+
+  // Cost (OTel-aligned, optional — only if obtainable from spawn shape)
+  input_tokens?: number;             // gen_ai.usage.input_tokens
+  output_tokens?: number;            // gen_ai.usage.output_tokens
+  cache_read_tokens?: number;        // gen_ai.usage.cache_read.input_tokens
+  cache_creation_tokens?: number;    // gen_ai.usage.cache_creation.input_tokens
+
+  // Activity
+  tool_calls_count?: number;
+  files_changed?: string[];          // repo-relative, deduped
+  commit_sha?: string;               // if the run produced a commit
+
+  // Outcome detail
+  // status = did the agent process complete cleanly (success/failure/timeout/...)
+  // verification_result = did the code under test pass (only on agent_type="verifier")
+  // a verifier with status="success" + verification_result="fail" = the verifier ran fine and the code failed.
+  // a verifier with status="failure" = the verifier itself errored (timeout, infra, etc.)
+  verifier_score?: number;           // 1-5 if agent_type=verifier
+  verification_result?: "pass" | "fail" | "partial";
+  failure_reason?: string;           // short, machine-classifiable; see "Failure taxonomy" below
+  failure_detail?: string;           // last 500 chars of stderr/error — keep the tail (newest content), drop the head
+
+  // Self-link — only set on failure
+  log_file?: string;                 // .planning/agent-runs/<run_id>.log if status != success
+}
+
+type AgentType =
+  | "planner"
+  | "plan-checker"
+  | "builder"
+  | "verifier"
+  | "qa-browser"
+  | "researcher"
+  | "research-synthesizer"
+  | "roadmapper"
+  | "team-orchestrator"
+  | "custom";                        // user-defined agents
+
+type AgentStatus =
+  | "success"                        // completed, no failure_reason
+  | "partial"                        // completed but flagged issues (e.g. builder PARTIAL)
+  | "blocked"                        // builder hit a precondition gate (e.g. file lock)
+  | "failure"                        // explicit failure (verifier fail, builder error)
+  | "timeout"                        // exceeded budget
+  | "interrupted";                   // user cancelled / parent killed
+```
+
+### Failure taxonomy
+
+`failure_reason` is a closed enum so analytics can classify without parsing free text. Add new values via PR — don't free-text.
+
+| Code | Meaning |
+|---|---|
+| `tsc-failed` | TypeScript compilation errors |
+| `lint-failed` | ESLint violations |
+| `tests-failed` | Test runner non-zero exit |
+| `build-failed` | Production build broke |
+| `verification-criteria-unmet` | Verifier ran cleanly but criteria failed |
+| `verification-evidence-missing` | Behavioral check lacked required citations |
+| `verification-execution-error` | Check itself errored (binary missing, timeout, cwd missing) — distinct from criteria failure |
+| `file-not-found` | Referenced file absent |
+| `dependency-missing` | Referenced npm/pip/etc package absent |
+| `lock-timeout` | `.planning/.state.lock` not acquired |
+| `network-error` | Outbound HTTP failed (research, ERP) |
+| `rate-limited` | LLM API 429 |
+| `context-overflow` | Prompt exceeded model context |
+| `tool-misuse` | Builder called a forbidden tool |
+| `precondition-unmet` | Required state/file missing before run |
+| `unknown` | Catch-all; should be rare and trigger triage |
+
+## Example records
+
+**Successful builder run** (sequential under `/qualia-build` skill invocation `sk_42`):
+```json
+{"schema_version":1,"run_id":"01HXY8N3W2K7Q5MZP9V4F8R6T1","skill_invocation_id":"sk_42","session_id":"sess_abc123","agent_type":"builder","model":"claude-sonnet-4-6","effort":"medium","project":"acme-portal","phase":2,"milestone":1,"task_id":"T1","wave":1,"status":"success","started_at":"2026-04-28T14:32:11Z","finished_at":"2026-04-28T14:34:02Z","duration_ms":111000,"input_tokens":12450,"output_tokens":1820,"cache_read_tokens":11200,"tool_calls_count":7,"files_changed":["src/lib/auth.ts","src/lib/auth-schema.ts"],"commit_sha":"a3f5e1c"}
+```
+
+**Failed verifier run** (same skill invocation, no parent — it's a sibling of the builder, not nested):
+```json
+{"schema_version":1,"run_id":"01HXY8P5R8K7Q5MZP9V4F8R6T2","skill_invocation_id":"sk_42","session_id":"sess_abc123","agent_type":"verifier","model":"claude-opus-4-7","project":"acme-portal","phase":2,"milestone":1,"status":"failure","started_at":"2026-04-28T14:38:10Z","finished_at":"2026-04-28T14:39:55Z","duration_ms":105000,"input_tokens":18200,"output_tokens":2100,"tool_calls_count":12,"verifier_score":2,"verification_result":"fail","failure_reason":"verification-criteria-unmet","failure_detail":"Task T2 acceptance criterion 'Redirect to /dashboard on 200' could not be verified — page.tsx contains no redirect() call","log_file":".planning/agent-runs/01HXY8P5R8K7Q5MZP9V4F8R6T2.log"}
+```
+
+**Researcher spawned by team-orchestrator** (true nesting — parent_run_id is set):
+```json
+{"schema_version":1,"run_id":"01HXY8QF1ZK7Q5MZP9V4F8R6T3","parent_run_id":"01HXY8QE9V2K7Q5MZP9V4F8R6T0","skill_invocation_id":"sk_43","session_id":"sess_abc123","agent_type":"researcher","model":"claude-sonnet-4-6","project":"acme-portal","status":"failure","started_at":"2026-04-28T14:42:00Z","finished_at":"2026-04-28T14:42:12Z","duration_ms":12000,"tool_calls_count":1,"failure_reason":"rate-limited","failure_detail":"WebFetch returned 429 from context7.com after 1 attempt","log_file":".planning/agent-runs/01HXY8QF1ZK7Q5MZP9V4F8R6T3.log"}
+```
+
+### `parent_run_id` vs `skill_invocation_id` — when to use which
+
+- **`skill_invocation_id`:** every record carries one. Groups all agents that ran under a single user-triggered skill (`/qualia-build phase 2` → planner, all builders, verifier all share an id).
+- **`parent_run_id`:** rare. Set only when one agent literally spawned another via the `Agent` tool — for example, `team-orchestrator` fanning out to `frontend-agent` + `backend-agent`. Sequential planner→builder→verifier under one skill is *not* nesting; those are siblings.
+
+## How records get written
+
+A small helper at `bin/lib/agent-runs.js`:
+
+```js
+// pseudocode
+const ar = require('./lib/agent-runs');
+
+const run = ar.start({
+  agent_type: 'builder',
+  task_id: 'T1',
+  phase: 2,
+  model: process.env.QUALIA_MODEL || 'claude-sonnet-4-6',
+});
+
+// ... spawn agent, capture result ...
+
+ar.finish(run, {
+  status: 'success',
+  files_changed: ['src/lib/auth.ts'],
+  commit_sha: getHeadSha(),
+  input_tokens: 12450,
+  output_tokens: 1820,
+});
+```
+
+`start()` returns a token; `finish()` writes the full record via a single `fs.appendFileSync` call. Crash between start and finish leaves no partial record on disk — the in-memory record is lost, which is fine.
+
+**Concurrency:** `qualia-build` spawns multiple builders in the same wave, each calling `finish()` concurrently. Atomicity guarantee: `fs.appendFileSync` opens with `O_APPEND` and issues a single `write()` syscall per call. On Linux ext4/btrfs/xfs and macOS APFS, `write()` to a regular file with `O_APPEND` is atomic for sizes up to the filesystem block size (typically 4096 bytes). Records run ~600–800 bytes — well under. On Windows NTFS, `O_APPEND` semantics are implemented by Node's libuv via an internal seek+write under a file lock; effectively atomic for our sizes. This is *not* the POSIX pipe `PIPE_BUF` guarantee — that applies to pipes, not regular files. The protection here is the kernel's regular-file `O_APPEND` + single-`write()` behavior. If records ever exceed ~3.5KB, switch to a per-write lock (`proper-lockfile` or a `.planning/.agent-runs.lock` flock).
+
+On `status != "success"`, `finish()` also writes `.planning/agent-runs/<run_id>.log` with the full stderr/error output. JSONL stays lean for analytics; debugging context lives in the side files. Successful runs leave no log file.
+
+**Where called from:**
+- The skills that orchestrate spawns (`/qualia-build`, `/qualia-verify`, `/qualia-plan`, etc.) wrap each Agent invocation in `ar.start` / `ar.finish`.
+- Skills can't easily measure tokens — those fields are populated when the harness exposes them via `Task` tool result metadata and left undefined otherwise. Don't gate the design on data we may or may not have.
+
+## How records get read
+
+`qualia-framework agents` — summary table:
+```
+$ qualia-framework agents
+Agent runs (last 50, project: acme-portal)
+
+  TIME    AGENT     PHASE  TASK  STATUS    DURATION  TOKENS    NOTE
+  14:34   builder   2      T1    success      111s   14k in    src/lib/auth.ts
+  14:38   verifier  2      —     failure      105s   20k in    verification-criteria-unmet
+  14:42   builder   2      T1    success       89s   13k in    fix: redirect after signin
+  14:45   verifier  2      —     success       97s   19k in    pass
+```
+
+`qualia-framework agents --failed` — only failure/partial/timeout/blocked:
+```
+$ qualia-framework agents --failed
+2 failures in last 7 days
+
+  2026-04-28 14:38  verifier   phase 2  verification-criteria-unmet
+  2026-04-26 09:22  builder    phase 1  tsc-failed
+```
+
+`qualia-framework agents --task T1` — all runs for one task (gap cycles visible):
+```
+$ qualia-framework agents --task T1
+T1 — Add email/password sign-in handler  (3 runs)
+
+  2026-04-28 14:32  builder   success      111s
+  2026-04-28 14:38  verifier  failure      105s   verification-criteria-unmet
+  2026-04-28 14:42  builder   success       89s   ← retry after gap
+```
+
+`qualia-framework analytics` extends with: agent failure rate, slowest agents (p50/p95), verifier fail rate by phase, repeated gap-cycles by task.
+
+## ERP integration (additive, non-breaking)
+
+Report payload v2 (in `docs/erp-contract.md`) gains:
+```json
+"agent_runs": {
+  "count": 14,
+  "failures": 2,
+  "verifier_fail_rate": 0.14,
+  "slowest_agent_ms": 312000,
+  "by_type": { "builder": 9, "verifier": 4, "planner": 1 }
+}
+```
+
+Aggregated counts only — never raw records. ERP backend treats the field as optional; old reports without it still parse. The full JSONL stays local.
+
+## Privacy and opt-out
+
+| Captured | Not captured |
+|---|---|
+| Agent type, model | User prompts |
+| Phase, task id | LLM responses |
+| File paths (repo-relative) | File contents |
+| Token counts | Command output |
+| Duration, status | Stderr/stdout beyond `failure_detail` last 500 chars |
+| Failure code | Network response bodies |
+| Commit SHA | Git diffs |
+
+Disable new writes: `export QUALIA_TELEMETRY=off`. The helper short-circuits *writes* — reads (`qualia-framework agents`) still surface previously recorded data. Opting out doesn't erase history.
+
+## Design decisions (locked v1)
+
+These were called out as open questions during draft; resolved here so implementation can proceed.
+
+1. **Token counts:** all token fields are optional. Populate when the harness exposes them via `Task` tool metadata; leave undefined otherwise. The schema doesn't depend on always having them.
+2. **`session_id`:** optional. If Claude Code exposes a stable id to skills/hooks, use it. Otherwise the `bin/lib/agent-runs.js` writer generates a per-process UUID on first call and reuses it for the lifetime of that process.
+3. **Tool-call telemetry:** aggregate `tool_calls_count` only. No per-call spans. If a future analytics need demands per-call detail, add a separate `agent-tool-calls.jsonl` — don't bloat the main ledger.
+4. **`parent_run_id` vs `skill_invocation_id`:** added `skill_invocation_id` as the common grouping key (every record has one). `parent_run_id` is reserved strictly for true agent-spawned-agent nesting (team-orchestrator → fan-out children). Documented inline above.
+5. **`failure_detail`:** capped at 500 chars; keep the tail (most recent stderr), drop the head. The newest content is usually the most useful for classification.
+6. **Side log files:** on `status != success`, `finish()` writes `.planning/agent-runs/<run_id>.log` with full stderr. Lean JSONL stays grep-friendly; debugging context survives.
+7. **Cross-project rollup:** rejected. ERP does fleet-wide aggregation. A `~/.claude/agent-runs.jsonl` mirror would add a sync surface for marginal benefit.
+8. **Append atomicity:** relies on `O_APPEND` + single-`write()` syscall behavior for regular files (Linux/macOS/Windows). Atomic up to filesystem block size; our records are well under. Detailed in the "Concurrency" note above.
+9. **Cleanup:** `qualia-framework agents prune --before YYYY-MM-DD` removes records and matching log files older than the cutoff. Never auto-prunes — operator-driven only.
+10. **`QUALIA_TELEMETRY=off` semantics:** disables *writes* only. Reads (`qualia-framework agents`) still surface existing records — opting out of new collection does not retroactively hide history. Set before a session to silence that session's spawns.
+
+## Migration plan
+
+1. Add `bin/lib/agent-runs.js` (writer) + `bin/cli.js agents` (reader). Helper is a no-op if `.planning/` doesn't exist.
+2. Wire `ar.start`/`ar.finish` calls into the orchestrating skills (`/qualia-build`, `/qualia-verify`, `/qualia-plan`, `/qualia-research`, `/qualia-postmortem`).
+3. Add `agents` table to `qualia-framework analytics`.
+4. After two milestones produce real data, extend ERP payload (v2) with aggregated metrics. Coordinate with ERP backend.
+5. Defer postmortem feedback loop and ERP feedback analyzer until ≥4 weeks of real data exist.
+
+No hard cutover. Pre-existing projects acquire the JSONL on first spawn after upgrade — older runs are simply absent.