kenaz 0.0.0-stage → 0.3.2

package/core/dev/scripts/dispatch-stats.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+/**
+ * dispatch-stats.js — TASK_1998 R1b
+ *
+ * Reads the sub-agent dispatch telemetry written by
+ * .formation/tools/dispatch.js (dispatch_prompt_stats.jsonl, one line per
+ * --dispatch-mode=subagent dispatch: { ts, task_id, rigor, complexity,
+ * formation, prompt_bytes, sections, model }) and, when it exists, correlates
+ * it with .formation/tools/post-complete.js's phase9_dispatch_outcomes.jsonl
+ * (one line per completed dispatch; a subset optionally carry duration_ms /
+ * tool_uses / turns from Ansuz's agent_result_<TASK_ID>.json — see R1c).
+ *
+ * Prints p50/p90 of prompt_bytes per (rigor, complexity) pair, and — for
+ * whichever outcome records actually carry the field — p50/p90 of turns /
+ * duration_ms / tool_uses, grouped the same way via the task_id -> (rigor,
+ * complexity) mapping learned from dispatch_prompt_stats.jsonl. Records
+ * written before the two-axis policy landed have no `complexity` field —
+ * those default to 'medium'.
+ *
+ * TASK_2109 R1 (grouping bug, TASK_2097 red flag): outcome records whose
+ * task_id was never seen in dispatch_prompt_stats.jsonl used to fall into a
+ * bucket literally named 'unknown/unknown' — a string shaped exactly like a
+ * real "rigor/complexity" key — and were sorted and printed inline, as an
+ * ordinary row, alongside real buckets in the SAME comparison tables. On the
+ * live data this bucket (TASK_1943-1997, all dispatched before
+ * dispatch_prompt_stats.jsonl existed — the earliest entry in that file is
+ * TASK_1993) happened to land on the exact same n/first-round-rate/mean as
+ * the real 'medium/simple' bucket, which read as duplication. Traced
+ * end-to-end (task_id sets are fully disjoint, 0 overlap; each task's own
+ * derived corrections count differs; the aggregate equality was a verified
+ * coincidence in small-integer count data — see dispatch-stats.test.js). The
+ * actual bug is a REPORTING one, not a data-leak one: nothing marked that
+ * bucket as a structurally different population (no rigor/complexity signal
+ * at all, not "this specific combination"), so it could be visually mistaken
+ * for a peer row. Fix: it is now a distinct sentinel (UNTRACKED_KEY, shaped
+ * so it can never collide with or be sorted into a real "rigor/complexity"
+ * key) and is always reported in its own section, never inside the sorted
+ * per-bucket comparison tables.
+ *
+ * TASK_2078: outcome records with no duration_ms/tool_uses (pre-dating the
+ * agent_result_<TASK_ID>.json convention, or dispatches where Ansuz never
+ * wrote it) get a report-time fallback to deriveSubagentStats, which reads
+ * the subagent's own Claude Code transcript straight off disk. This never
+ * rewrites phase9_dispatch_outcomes.jsonl — it only affects what THIS report
+ * prints. Pass --no-transcripts to disable it and see the raw stored data.
+ *
+ * TASK_2109 R2: `corrections` (used by the landing-rate metric below) now
+ * excludes coordinator messages classified 'information' (FYI/context, no
+ * rework demanded) — see subagent-transcript-stats.js
+ * classifyCoordinatorMessage. The landing-rate metric has always read only
+ * the `corrections` field; this file needed no logic change for R2, only the
+ * upstream field's meaning got more accurate.
+ *
+ * Usage:
+ *   node dev/scripts/dispatch-stats.js [--project-path <path>] [--no-transcripts]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { deriveSubagentStats } = require('../../.formation/tools/post-complete/subagent-transcript-stats');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+function getArg(flag) {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith(`${flag}=`)) return args[i].split('=').slice(1).join('=');
+    if (args[i] === flag && args[i + 1]) return args[i + 1];
+  }
+  return null;
+}
+
+function hasFlag(flag) {
+  return process.argv.slice(2).includes(flag);
+}
+
+/**
+ * Classify one outcome record's timing source and, when the record lacks
+ * duration_ms/tool_uses, fill them in (report-time only) from the subagent
+ * transcript on disk. Never mutates the input record.
+ *
+ * TASK_2097: also fills `corrections` (report-time only) when the stored
+ * record lacks it, independently of the duration_ms/tool_uses timing bucket
+ * above — corrections has no agent_result counterpart, so a record that
+ * already carries agent_result timing can still be missing it (either it
+ * predates TASK_2097, or post-complete's own transcript read found none).
+ *
+ * @returns {{effective: object, bucket: 'agent_result'|'mixed'|'transcript'|'none'}}
+ */
+function classifyAndFillTiming(outcome, root, transcriptsEnabled, cache) {
+  const hasDuration = typeof outcome.duration_ms === 'number';
+  const hasToolUses = typeof outcome.tool_uses === 'number';
+  const hasCorrections = typeof outcome.corrections === 'number';
+
+  let effective = outcome;
+  let bucket;
+
+  if (hasDuration || hasToolUses) {
+    // Already carries stored timing — trust its own timing_source (TASK_2078
+    // post-complete.js field) when present; older records predate that field
+    // and were always agent_result-sourced.
+    bucket = outcome.timing_source || 'agent_result';
+  } else if (!transcriptsEnabled || !outcome.task_id) {
+    bucket = 'none';
+  } else {
+    if (!cache.has(outcome.task_id)) {
+      cache.set(outcome.task_id, deriveSubagentStats(outcome.task_id, root));
+    }
+    const derived = cache.get(outcome.task_id);
+    if (derived) {
+      const copy = { ...outcome };
+      let filled = false;
+      if (typeof derived.duration_ms === 'number') { copy.duration_ms = derived.duration_ms; filled = true; }
+      if (typeof derived.tool_uses === 'number') { copy.tool_uses = derived.tool_uses; filled = true; }
+      effective = copy;
+      bucket = filled ? 'transcript' : 'none';
+    } else {
+      bucket = 'none';
+    }
+  }
+
+  if (!hasCorrections && transcriptsEnabled && outcome.task_id) {
+    if (!cache.has(outcome.task_id)) {
+      cache.set(outcome.task_id, deriveSubagentStats(outcome.task_id, root));
+    }
+    const derived = cache.get(outcome.task_id);
+    if (derived && typeof derived.corrections === 'number') {
+      if (effective === outcome) effective = { ...outcome };
+      effective.corrections = derived.corrections;
+    }
+  }
+
+  return { effective, bucket };
+}
+
+function readJsonl(file) {
+  if (!fs.existsSync(file)) return [];
+  const lines = fs.readFileSync(file, 'utf8').split('\n').filter(l => l.trim());
+  const out = [];
+  for (const line of lines) {
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+/** Nearest-rank percentile (p in [0,100]) over a numeric array. */
+function percentile(values, p) {
+  if (!values || values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[idx];
+}
+
+function fmt(n, digits = 0) {
+  return n == null ? 'n/a' : Number(n).toFixed(digits);
+}
+
+// TASK_2109 R1: sentinel for outcomes whose task_id has no
+// dispatch_prompt_stats.jsonl entry at all. Deliberately NOT shaped like a
+// real "rigor/complexity" key (parens + spaces, no bare "/") so it can never
+// collide with, or be mistaken for, a real bucket when sorted or printed —
+// see REAL_GROUP_KEY_RE below and the header comment for the bug this fixes.
+const UNTRACKED_KEY = '(untracked: no dispatch_prompt_stats.jsonl entry)';
+const REAL_GROUP_KEY_RE = /^[a-z]+\/[a-z]+$/;
+
+/**
+ * Build the (rigor, complexity) grouping tables from dispatch_prompt_stats.jsonl.
+ * `byKey`: "rigor/complexity" -> prompt_bytes[]. `taskKey`: task_id ->
+ * "rigor/complexity" (last record for that task_id in file order wins).
+ * @param {object[]} promptStats
+ * @returns {{byKey: Map<string, number[]>, taskKey: Map<string, string>}}
+ */
+function buildTaskKeyMap(promptStats) {
+  const byKey = new Map();
+  const taskKey = new Map();
+  for (const r of promptStats) {
+    const rigor = r.rigor || 'medium';
+    const complexity = r.complexity || 'medium'; // pre-two-axis records have no field
+    const key = `${rigor}/${complexity}`;
+    if (!byKey.has(key)) byKey.set(key, []);
+    if (typeof r.prompt_bytes === 'number') byKey.get(key).push(r.prompt_bytes);
+    if (r.task_id) taskKey.set(r.task_id, key);
+  }
+  return { byKey, taskKey };
+}
+
+/**
+ * Resolve one outcome's group key. Returns UNTRACKED_KEY — never a value
+ * that looks like a real "rigor/complexity" pair — when taskId is falsy or
+ * has no dispatch_prompt_stats.jsonl entry.
+ * @param {string|undefined} taskId
+ * @param {Map<string, string>} taskKey
+ * @returns {string}
+ */
+function resolveGroupKey(taskId, taskKey) {
+  if (taskId && taskKey.has(taskId)) return taskKey.get(taskId);
+  return UNTRACKED_KEY;
+}
+
+/**
+ * Core grouping/aggregation loop (TASK_2109: extracted so R1's fix — real
+ * buckets and UNTRACKED_KEY can never be silently merged or visually
+ * confused — is unit-testable without touching disk). Mutates nothing;
+ * returns the same shape main() used to build inline.
+ * @param {object[]} outcomes
+ * @param {Map<string, string>} taskKey
+ * @param {{root: string, transcriptsEnabled: boolean, cache: Map}} opts
+ */
+function aggregateOutcomes(outcomes, taskKey, opts) {
+  const { root, transcriptsEnabled, cache } = opts;
+  const fields = ['turns', 'duration_ms', 'tool_uses'];
+  const byKeyField = new Map(); // key -> field -> values[]
+  const landingByKey = new Map(); // key -> { landedWithCorrections, landedFirstRound, correctionsSum }
+  const sourceCounts = { agent_result: 0, mixed: 0, transcript: 0, none: 0 };
+  let carriedAny = false;
+
+  function bumpLanding(key, corrections) {
+    if (!landingByKey.has(key)) landingByKey.set(key, { landedWithCorrections: 0, landedFirstRound: 0, correctionsSum: 0 });
+    const b = landingByKey.get(key);
+    b.landedWithCorrections += 1;
+    b.correctionsSum += corrections;
+    if (corrections === 0) b.landedFirstRound += 1;
+  }
+
+  for (const o of outcomes) {
+    const { effective, bucket: source } = classifyAndFillTiming(o, root, transcriptsEnabled, cache);
+    sourceCounts[source] = (sourceCounts[source] || 0) + 1;
+
+    const key = resolveGroupKey(effective.task_id, taskKey);
+    for (const field of fields) {
+      if (typeof effective[field] !== 'number') continue;
+      carriedAny = true;
+      if (!byKeyField.has(key)) byKeyField.set(key, {});
+      const values = byKeyField.get(key);
+      if (!values[field]) values[field] = [];
+      values[field].push(effective[field]);
+    }
+
+    if (effective.verify_merge_landed === true && typeof effective.corrections === 'number') {
+      bumpLanding(key, effective.corrections);
+      bumpLanding('overall', effective.corrections);
+    }
+  }
+
+  return { byKeyField, landingByKey, sourceCounts, carriedAny, fields };
+}
+
+function main() {
+  const projectPath = getArg('--project-path');
+  const root = projectPath || ROOT;
+  const specialistDir = path.join(root, '.kenaz', 'specialist');
+  const promptStatsFile = path.join(specialistDir, 'dispatch_prompt_stats.jsonl');
+  const outcomesFile = path.join(specialistDir, 'phase9_dispatch_outcomes.jsonl');
+
+  const promptStats = readJsonl(promptStatsFile);
+  const outcomes = readJsonl(outcomesFile);
+
+  console.log(`Formation dispatch stats — ${root}`);
+  console.log(`  ${promptStatsFile}: ${promptStats.length} record(s)`);
+  console.log(`  ${outcomesFile}: ${outcomes.length} record(s)`);
+  console.log('');
+
+  // ── prompt_bytes p50/p90 per rigor ──────────────────────────────────
+  if (promptStats.length === 0) {
+    console.log('No dispatch_prompt_stats.jsonl records yet — dispatch via');
+    console.log('  node .formation/tools/dispatch.js --skill=<s> --task=<TASK_ID> --dispatch-mode=subagent');
+    console.log('to generate telemetry.');
+  } else {
+    // TASK_1998 two-axis policy: group by (rigor, complexity) pair, not rigor
+    // alone — prompt shape now depends on both.
+    const { byKey, taskKey } = buildTaskKeyMap(promptStats);
+
+    console.log('Prompt bytes (p50/p90) per rigor/complexity:');
+    for (const [key, bytesArr] of [...byKey.entries()].sort()) {
+      const p50 = percentile(bytesArr, 50);
+      const p90 = percentile(bytesArr, 90);
+      console.log(`  ${key.padEnd(16)} n=${bytesArr.length.toString().padEnd(4)} p50=${fmt(p50)}B (${fmt(p50 / 1024, 1)}KB)  p90=${fmt(p90)}B (${fmt(p90 / 1024, 1)}KB)`);
+    }
+    console.log('');
+
+    // ── turns / duration_ms / tool_uses p50/p90, when present ──────────
+    // TASK_2078: records missing duration_ms/tool_uses get a report-time
+    // fallback to deriveSubagentStats (subagent transcript on disk).
+    const transcriptsEnabled = !hasFlag('--no-transcripts');
+    const transcriptCache = new Map();
+
+    // TASK_2097: first-round landing rate (landed with corrections == 0) and
+    // mean corrections per landed card, per rigor/complexity and overall.
+    // Only outcomes with a KNOWN corrections value (stored, or filled above
+    // from the transcript) count toward these — an outcome with no
+    // transcript match at all contributes to neither the numerator nor the
+    // denominator, so a thin transcript archive undercounts rather than
+    // silently overstating the landing rate.
+    //
+    // TASK_2109 R1: grouping now goes through aggregateOutcomes/resolveGroupKey
+    // — outcomes with no dispatch_prompt_stats.jsonl entry land in
+    // UNTRACKED_KEY, always reported separately below, never inline with a
+    // real rigor/complexity bucket (see file header for the bug this fixes).
+    const { byKeyField, landingByKey, sourceCounts, carriedAny, fields } =
+      aggregateOutcomes(outcomes, taskKey, { root, transcriptsEnabled, cache: transcriptCache });
+
+    console.log(`Timing source (${outcomes.length} outcome record(s)${transcriptsEnabled ? '' : ', transcript fallback disabled'}):`);
+    for (const src of ['agent_result', 'mixed', 'transcript', 'none']) {
+      console.log(`  ${src.padEnd(14)} n=${sourceCounts[src]}`);
+    }
+    console.log('');
+
+    if (!carriedAny) {
+      console.log('No phase9_dispatch_outcomes.jsonl records carry turns/duration_ms/tool_uses yet');
+      console.log('(optional fields — see post-complete.js appendPhase9OutcomeLog, TASK_1998 R1c).');
+    } else {
+      console.log('turns / duration_ms / tool_uses (p50/p90) per rigor/complexity, from outcomes correlated by task_id:');
+      // TASK_2109 R1: real buckets only — UNTRACKED_KEY is reported in its
+      // own paragraph below, never sorted into this comparison list, so it
+      // can never be read as a peer of a real rigor/complexity combination.
+      const realTimingRows = [...byKeyField.entries()].filter(([key]) => key !== UNTRACKED_KEY).sort();
+      for (const [key, bucket] of realTimingRows) {
+        console.log(`  ${key}:`);
+        for (const field of fields) {
+          const values = bucket[field];
+          if (!values || values.length === 0) continue;
+          const p50 = percentile(values, 50);
+          const p90 = percentile(values, 90);
+          console.log(`    ${field.padEnd(12)} n=${values.length.toString().padEnd(4)} p50=${fmt(p50, 1)}  p90=${fmt(p90, 1)}`);
+        }
+      }
+      const untrackedTiming = byKeyField.get(UNTRACKED_KEY);
+      if (untrackedTiming) {
+        console.log(`  ${UNTRACKED_KEY} — NOT a rigor/complexity bucket, do not compare to the rows above:`);
+        for (const field of fields) {
+          const values = untrackedTiming[field];
+          if (!values || values.length === 0) continue;
+          const p50 = percentile(values, 50);
+          const p90 = percentile(values, 90);
+          console.log(`    ${field.padEnd(12)} n=${values.length.toString().padEnd(4)} p50=${fmt(p50, 1)}  p90=${fmt(p90, 1)}`);
+        }
+      }
+    }
+    console.log('');
+
+    // TASK_2097: first-round landing rate + mean corrections per landed card.
+    if (landingByKey.size === 0) {
+      console.log('No landed outcome records carry a known corrections value yet');
+      console.log('(see subagent-transcript-stats.js deriveSubagentStats / post-complete.js appendPhase9OutcomeLog, TASK_2097).');
+    } else {
+      console.log('First-round landing rate (landed with corrections == 0) and mean corrections per landed card:');
+      // TASK_2109 R1: same separation as the timing table above.
+      const rows = [...landingByKey.entries()].filter(([key]) => key !== 'overall' && key !== UNTRACKED_KEY).sort();
+      const overall = landingByKey.get('overall');
+      const untracked = landingByKey.get(UNTRACKED_KEY);
+      for (const [key, b] of rows) {
+        const rate = b.landedWithCorrections > 0 ? (b.landedFirstRound / b.landedWithCorrections) * 100 : null;
+        const mean = b.landedWithCorrections > 0 ? b.correctionsSum / b.landedWithCorrections : null;
+        console.log(`  ${key.padEnd(16)} n=${b.landedWithCorrections.toString().padEnd(4)} first_round=${fmt(rate, 1)}%  mean_corrections=${fmt(mean, 2)}`);
+      }
+      if (overall) {
+        const rate = overall.landedWithCorrections > 0 ? (overall.landedFirstRound / overall.landedWithCorrections) * 100 : null;
+        const mean = overall.landedWithCorrections > 0 ? overall.correctionsSum / overall.landedWithCorrections : null;
+        console.log(`  ${'overall'.padEnd(16)} n=${overall.landedWithCorrections.toString().padEnd(4)} first_round=${fmt(rate, 1)}%  mean_corrections=${fmt(mean, 2)}`);
+      }
+      if (untracked) {
+        const rate = untracked.landedWithCorrections > 0 ? (untracked.landedFirstRound / untracked.landedWithCorrections) * 100 : null;
+        const mean = untracked.landedWithCorrections > 0 ? untracked.correctionsSum / untracked.landedWithCorrections : null;
+        console.log(`  ${UNTRACKED_KEY} — NOT a rigor/complexity bucket, do not compare to the rows above:`);
+        console.log(`    n=${untracked.landedWithCorrections} first_round=${fmt(rate, 1)}%  mean_corrections=${fmt(mean, 2)}`);
+      }
+    }
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  readJsonl,
+  percentile,
+  buildTaskKeyMap,
+  resolveGroupKey,
+  aggregateOutcomes,
+  classifyAndFillTiming,
+  UNTRACKED_KEY,
+  REAL_GROUP_KEY_RE,
+};

package/core/dev/scripts/dispatch-stats.test.js

@@ -0,0 +1,162 @@
+'use strict';
+/**
+ * dispatch-stats.test.js — TASK_2109 R1/A1
+ *
+ * Covers the grouping-bug fix: outcomes whose task_id has no
+ * dispatch_prompt_stats.jsonl entry must never be silently merged into, or
+ * visually confused with, a real "rigor/complexity" bucket. TASK_2097's red
+ * flag ("the 'unknown/unknown' row is identical to 'medium/simple'") turned
+ * out, on live-data tracing, to be a verified coincidence in small-integer
+ * count data (fully disjoint task_id sets — see dispatch-stats.js header
+ * comment) rather than a data leak; the real bug was that the fallback
+ * bucket was reported as an ordinary sortable row shaped exactly like a real
+ * bucket key, with nothing marking it as a structurally different
+ * population. These tests reproduce that exact coincidence scenario
+ * synthetically and assert the two groups stay distinct and correctly
+ * labeled regardless.
+ *
+ * Run: node --test dev/scripts/dispatch-stats.test.js
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildTaskKeyMap,
+  resolveGroupKey,
+  aggregateOutcomes,
+  UNTRACKED_KEY,
+  REAL_GROUP_KEY_RE,
+} = require('./dispatch-stats');
+
+test('UNTRACKED_KEY can never collide with a real "rigor/complexity" key shape', () => {
+  assert.equal(REAL_GROUP_KEY_RE.test(UNTRACKED_KEY), false);
+  assert.equal(REAL_GROUP_KEY_RE.test('medium/simple'), true);
+  assert.equal(REAL_GROUP_KEY_RE.test('unknown/unknown'), true, 'sanity: the OLD sentinel string DID look like a real key — that was the bug');
+});
+
+test('buildTaskKeyMap: groups task_id by (rigor, complexity), defaulting missing fields to medium', () => {
+  const promptStats = [
+    { task_id: 'TASK_1', rigor: 'high', complexity: 'complex', prompt_bytes: 100 },
+    { task_id: 'TASK_2', rigor: 'medium', complexity: 'simple', prompt_bytes: 200 },
+    { task_id: 'TASK_3', prompt_bytes: 300 }, // pre-two-axis record: no rigor/complexity at all
+  ];
+  const { byKey, taskKey } = buildTaskKeyMap(promptStats);
+  assert.equal(taskKey.get('TASK_1'), 'high/complex');
+  assert.equal(taskKey.get('TASK_2'), 'medium/simple');
+  assert.equal(taskKey.get('TASK_3'), 'medium/medium');
+  assert.deepEqual(byKey.get('medium/medium'), [300]);
+});
+
+test('resolveGroupKey: untracked task_id (or none at all) resolves to UNTRACKED_KEY, never a real bucket', () => {
+  const { taskKey } = buildTaskKeyMap([{ task_id: 'TASK_1', rigor: 'high', complexity: 'complex' }]);
+  assert.equal(resolveGroupKey('TASK_1', taskKey), 'high/complex');
+  assert.equal(resolveGroupKey('TASK_999_NEVER_DISPATCHED', taskKey), UNTRACKED_KEY);
+  assert.equal(resolveGroupKey(undefined, taskKey), UNTRACKED_KEY);
+  assert.equal(resolveGroupKey('', taskKey), UNTRACKED_KEY);
+});
+
+// ── A1: reproduce the exact TASK_2097 red-flag scenario ─────────────────────
+// Two fully disjoint sets of task_ids — one tracked (real "medium/simple"
+// bucket), one untracked (pre-dates dispatch_prompt_stats.jsonl) — engineered
+// so their aggregate corrections sum and landed count coincidentally match,
+// exactly like the real TASK_1943-1997 vs TASK_2032+ data did (n=23, sum=6
+// in both, verified on live data). The fix must keep them as two distinct
+// map entries, not merge them into one row.
+function buildCoincidenceFixture() {
+  const promptStats = [];
+  const outcomes = [];
+
+  // Tracked set: 3 tasks, all real "medium/simple", corrections sum to 2.
+  const trackedCorrections = [0, 1, 1];
+  trackedCorrections.forEach((corrections, i) => {
+    const taskId = `TASK_TRACKED_${i}`;
+    promptStats.push({ task_id: taskId, rigor: 'medium', complexity: 'simple', prompt_bytes: 1000 });
+    outcomes.push({ task_id: taskId, verify_merge_landed: true, corrections, ts: new Date().toISOString() });
+  });
+
+  // Untracked set: different task_ids, NEVER appear in promptStats, but
+  // corrections also sum to 2 over the same count (3) — same n, same sum,
+  // same mean, same first-round rate as the tracked set above.
+  const untrackedCorrections = [0, 0, 2];
+  untrackedCorrections.forEach((corrections, i) => {
+    const taskId = `TASK_UNTRACKED_${i}`;
+    outcomes.push({ task_id: taskId, verify_merge_landed: true, corrections, ts: new Date().toISOString() });
+  });
+
+  return { promptStats, outcomes };
+}
+
+test('aggregateOutcomes: coincidentally-identical aggregate stats stay in two DISTINCT groups, not merged', () => {
+  const { promptStats, outcomes } = buildCoincidenceFixture();
+  const { taskKey } = buildTaskKeyMap(promptStats);
+  const cache = new Map();
+  const { landingByKey } = aggregateOutcomes(outcomes, taskKey, { root: __dirname, transcriptsEnabled: false, cache });
+
+  assert.ok(landingByKey.has('medium/simple'), 'tracked set must land in its real bucket');
+  assert.ok(landingByKey.has(UNTRACKED_KEY), 'untracked set must land in the untracked sentinel, not merge into medium/simple');
+  assert.notEqual(landingByKey.get('medium/simple'), landingByKey.get(UNTRACKED_KEY), 'must be two distinct accumulator objects, not one shared reference');
+
+  const tracked = landingByKey.get('medium/simple');
+  const untracked = landingByKey.get(UNTRACKED_KEY);
+  // Sanity: the fixture really does produce equal aggregates (that's the point).
+  assert.equal(tracked.landedWithCorrections, 3);
+  assert.equal(untracked.landedWithCorrections, 3);
+  assert.equal(tracked.correctionsSum, 2);
+  assert.equal(untracked.correctionsSum, 2);
+
+  // 'overall' must count BOTH sets (6 landed total, sum 4) — the untracked
+  // set is excluded only from the per-bucket comparison rows, never from the
+  // true overall total.
+  const overall = landingByKey.get('overall');
+  assert.equal(overall.landedWithCorrections, 6);
+  assert.equal(overall.correctionsSum, 4);
+});
+
+test('aggregateOutcomes: a task_id dispatched under two different rigor/complexity keys does not split its outcome across two buckets (last-write-wins is applied once, consistently)', () => {
+  // TASK_2109: defensive regression — taskKey is built with "last write in
+  // file order wins" per task_id. If dispatch_prompt_stats.jsonl ever logs
+  // the SAME task_id under two different keys (re-dispatch at escalated
+  // rigor), a single outcome for that task must resolve to exactly one key,
+  // not be double-counted or split.
+  const promptStats = [
+    { task_id: 'TASK_X', rigor: 'low', complexity: 'simple', prompt_bytes: 10 },
+    { task_id: 'TASK_X', rigor: 'high', complexity: 'complex', prompt_bytes: 20 }, // later record wins
+  ];
+  const outcomes = [{ task_id: 'TASK_X', verify_merge_landed: true, corrections: 0, ts: new Date().toISOString() }];
+  const { taskKey } = buildTaskKeyMap(promptStats);
+  const cache = new Map();
+  const { landingByKey } = aggregateOutcomes(outcomes, taskKey, { root: __dirname, transcriptsEnabled: false, cache });
+
+  assert.equal(landingByKey.has('low/simple'), false, 'must not also appear under the superseded key');
+  assert.ok(landingByKey.has('high/complex'));
+  assert.equal(landingByKey.get('high/complex').landedWithCorrections, 1);
+});
+
+// ── negative control ─────────────────────────────────────────────────────
+test('negative control: a grouping key that ignores UNTRACKED_KEY entirely (merges untracked into whatever bucket happens to sort adjacent) fails the distinctness assertion', () => {
+  const { promptStats, outcomes } = buildCoincidenceFixture();
+  const { taskKey } = buildTaskKeyMap(promptStats);
+
+  // Simulate the OLD behavior: untracked outcomes silently keyed into the
+  // SAME bucket as a real one (here, forced onto 'medium/simple' — the
+  // real-world equivalent of the pre-fix 'unknown/unknown' string coinciding
+  // with a real bucket in the sorted, undifferentiated table).
+  const landingByKey = new Map();
+  function bump(key, corrections) {
+    if (!landingByKey.has(key)) landingByKey.set(key, { landedWithCorrections: 0, correctionsSum: 0 });
+    const b = landingByKey.get(key);
+    b.landedWithCorrections += 1;
+    b.correctionsSum += corrections;
+  }
+  for (const o of outcomes) {
+    const realKey = taskKey.get(o.task_id) || 'medium/simple'; // BUG: merges untracked into a real bucket
+    bump(realKey, o.corrections);
+  }
+
+  // This is the failure the fix prevents: only ONE bucket exists, holding
+  // both the tracked and untracked task_ids' outcomes combined (n=6, not the
+  // correct n=3/n=3 split asserted in the fixed-behavior test above).
+  assert.equal(landingByKey.size, 1, 'negative control: the broken merge collapses two distinct populations into one bucket');
+  assert.equal(landingByKey.get('medium/simple').landedWithCorrections, 6, 'negative control: n=6 conflates tracked (3) and untracked (3) — this is the bug the fix removes');
+});