feat(trekresearch): emit and export the five STORM measurement fields

commands/trekresearch.md

@@ -648,6 +648,11 @@ Record format (one JSON line):
   "project_dir": "{project_dir or null}",
   "brief_path": "{brief_destination}",
   "dimensions": {N},
+  "dimensions_baseline": {N},
+  "effort": "{low|standard|high}",
+  "conv_turns": {N},
+  "empty_turns": {N},
+  "unique_sources": {N},
   "agents_local": {N},
   "agents_external": {N},
   "gemini_used": {true|false},
@@ -657,6 +662,17 @@ Record format (one JSON line):
 }
 ```
 
+**The five measurement fields (v5.10).** `effort` is the grouping key — the
+resolved `phase_signal_result.effort` for the `research` phase, a
+low-cardinality label (`low|standard|high`), and the only axis on which a
+high-effort run can be compared against a standard one. The other four are
+numeric: `unique_sources` (distinct sources cited across the brief),
+`dimensions_baseline` (the interview-derived dimension count, so the Phase 4.5
+delta against `dimensions` is machine-readable), `conv_turns` (Phase 5 loop
+turns actually spent), and `empty_turns` (loop turns that returned no findings
+or no citations). On a standard run the loop never arms, so
+`dimensions_baseline == dimensions` and both turn counters are `0`.
+
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
 
 ## Profile (v4.1)

lib/exporters/field-allowlist.mjs

@@ -30,11 +30,18 @@ const TREKBRIEF_ALLOWED = Object.freeze(new Set([
 // DENY BY OMISSION: question (free prose), project_dir + brief_path
 // (filesystem paths) are written into the jsonl but MUST NOT reach the
 // exporter.
+// The five v5.10 measurement fields are allowlisted too: `effort` is a
+// low-cardinality label (low|standard|high) and the grouping key the
+// measurement gate is computed on; `unique_sources`, `dimensions_baseline`,
+// `conv_turns` and `empty_turns` are plain counters. None of them carry prose
+// or paths.
 const TREKRESEARCH_ALLOWED = Object.freeze(new Set([
   'ts', 'slug', 'mode', 'scope', 'engine', 'dimensions', 'agents_local',
   'agents_external', 'gemini_used', 'confidence', 'contradictions',
   'open_questions', 'profile', 'parallel_agents',
   'external_research_enabled', 'profile_source',
+  'effort', 'unique_sources', 'dimensions_baseline', 'conv_turns',
+  'empty_turns',
 ]));
 
 // Source: tests/fixtures/jsonl-schemas.md row 3 (trekplan)

tests/fixtures/expected.prom

@@ -33,19 +33,31 @@ voyage_trekplan_deep_dives{_schema_id="trekplan",slug="add-auth",mode="default",
 voyage_trekplan_research_briefs_used{_schema_id="trekplan",slug="add-auth",mode="default",profile="premium",profile_source="flag"} 3
 # HELP voyage_trekresearch_agents_external voyage stats — trekresearch_agents_external
 # TYPE voyage_trekresearch_agents_external gauge
-voyage_trekresearch_agents_external{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",profile="premium",profile_source="default"} 3
+voyage_trekresearch_agents_external{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 3
 # HELP voyage_trekresearch_agents_local voyage stats — trekresearch_agents_local
 # TYPE voyage_trekresearch_agents_local gauge
-voyage_trekresearch_agents_local{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",profile="premium",profile_source="default"} 5
+voyage_trekresearch_agents_local{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 5
 # HELP voyage_trekresearch_contradictions voyage stats — trekresearch_contradictions
 # TYPE voyage_trekresearch_contradictions gauge
-voyage_trekresearch_contradictions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",profile="premium",profile_source="default"} 1
+voyage_trekresearch_contradictions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 1
+# HELP voyage_trekresearch_conv_turns voyage stats — trekresearch_conv_turns
+# TYPE voyage_trekresearch_conv_turns gauge
+voyage_trekresearch_conv_turns{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 5
 # HELP voyage_trekresearch_dimensions voyage stats — trekresearch_dimensions
 # TYPE voyage_trekresearch_dimensions gauge
-voyage_trekresearch_dimensions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",profile="premium",profile_source="default"} 4
+voyage_trekresearch_dimensions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 4
+# HELP voyage_trekresearch_dimensions_baseline voyage stats — trekresearch_dimensions_baseline
+# TYPE voyage_trekresearch_dimensions_baseline gauge
+voyage_trekresearch_dimensions_baseline{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 3
+# HELP voyage_trekresearch_empty_turns voyage stats — trekresearch_empty_turns
+# TYPE voyage_trekresearch_empty_turns gauge
+voyage_trekresearch_empty_turns{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 1
 # HELP voyage_trekresearch_open_questions voyage stats — trekresearch_open_questions
 # TYPE voyage_trekresearch_open_questions gauge
-voyage_trekresearch_open_questions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",profile="premium",profile_source="default"} 2
+voyage_trekresearch_open_questions{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 2
+# HELP voyage_trekresearch_unique_sources voyage stats — trekresearch_unique_sources
+# TYPE voyage_trekresearch_unique_sources gauge
+voyage_trekresearch_unique_sources{_schema_id="trekresearch",slug="add-auth",mode="default",scope="both",effort="high",profile="premium",profile_source="default"} 17
 # HELP voyage_trekreview_duration_ms voyage stats — trekreview_duration_ms
 # TYPE voyage_trekreview_duration_ms histogram
 voyage_trekreview_duration_ms{_schema_id="trekreview",slug="add-auth",verdict="ALLOW",mode="default",profile="balanced",profile_source="flag"} 4521

tests/fixtures/jsonl-schemas.md

@@ -20,7 +20,7 @@
 | schema_id | fields | writer_path | line_ref | v4.1 additive | PII |
 |-----------|--------|-------------|----------|---------------|-----|
 | trekbrief-stats | ts, task, slug, mode, interview_turns, review_iterations, brief_quality, research_topics, auto_research, auto_result, project_dir | commands/trekbrief.md (orchestrator-emit Phase 7) | trekbrief.md:657-672 | profile, phase_models, profile_source | none |
-| trekresearch-stats | ts, question, mode, scope, engine, slug, project_dir, brief_path, dimensions, agents_local, agents_external, gemini_used, confidence, contradictions, open_questions | commands/trekresearch.md (orchestrator-emit Stats tracking) | trekresearch.md:521-547 | profile, phase_models, parallel_agents, external_research_enabled, profile_source | none |
+| trekresearch-stats | ts, question, mode, scope, engine, slug, project_dir, brief_path, dimensions, dimensions_baseline, effort, conv_turns, empty_turns, unique_sources, agents_local, agents_external, gemini_used, confidence, contradictions, open_questions | commands/trekresearch.md (orchestrator-emit Stats tracking) | trekresearch.md:634-676 | profile, phase_models, parallel_agents, external_research_enabled, profile_source | none |
 | trekplan-stats | ts, task, mode, slug, brief_path, project_dir, codebase_size, codebase_files, agents_deployed, deep_dives, research_briefs_used, research_scout_used, critic_verdict, guardian_verdict, outcome | commands/trekplan.md (orchestrator-emit Phase 12) | trekplan.md:805-826 | profile, phase_models, parallel_agents, profile_source | none |
 | trekexecute-stats (Phase 9 record) | ts, plan, plan_type, mode, result, steps_total, steps_passed, steps_failed, steps_skipped, failed_at_step | commands/trekexecute.md (orchestrator-emit Phase 9) | trekexecute.md:1479-1494 | profile, phase_models, profile_source | none |
 | trekexecute-stats (autonomy events) | ts, event, known_event, payload | lib/stats/event-emit.mjs `emit()` | event-emit.mjs:64-86 | payload.profile, payload.phase_models, payload.profile_source | none |

tests/fixtures/stats-sample.jsonl

@@ -2,4 +2,4 @@
 {"_schema_id":"trekexecute","ts":"2026-05-09T08:30:00.000Z","plan":"trekplan-add-auth.md","plan_type":"plan","mode":"execute","result":"completed","steps_total":12,"steps_passed":12,"steps_failed":0,"steps_skipped":0,"profile":"premium","profile_source":"inheritance"}
 {"_schema_id":"trekreview","ts":"2026-05-09T09:00:00.000Z","slug":"add-auth","verdict":"ALLOW","reviewed_files_count":18,"mode":"default","duration_ms":4521,"profile":"balanced","profile_source":"flag"}
 {"_schema_id":"trekbrief","ts":"2026-05-09T07:00:00.000Z","slug":"add-auth","mode":"default","interview_turns":7,"review_iterations":2,"research_topics":3,"profile":"economy","profile_source":"env"}
-{"_schema_id":"trekresearch","ts":"2026-05-09T07:30:00.000Z","slug":"add-auth","mode":"default","scope":"both","dimensions":4,"agents_local":5,"agents_external":3,"contradictions":1,"open_questions":2,"profile":"premium","profile_source":"default"}
+{"_schema_id":"trekresearch","ts":"2026-05-09T07:30:00.000Z","slug":"add-auth","mode":"default","scope":"both","dimensions":4,"dimensions_baseline":3,"effort":"high","conv_turns":5,"empty_turns":1,"unique_sources":17,"agents_local":5,"agents_external":3,"contradictions":1,"open_questions":2,"profile":"premium","profile_source":"default"}

tests/hooks/otel-export-textfile.test.mjs

@@ -31,6 +31,25 @@ test('SC #12: stats-sample.jsonl → expected.prom snapshot byte-for-byte match'
     `  node scripts/gen-expected-prom.mjs > tests/fixtures/expected.prom`);
 });
 
+test('Step 9: the four numeric STORM fields are metric families and effort is a label', () => {
+  const expected = readFileSync(join(FIXTURES, 'expected.prom'), 'utf-8');
+  for (const field of ['unique_sources', 'dimensions_baseline', 'conv_turns', 'empty_turns']) {
+    assert.match(
+      expected,
+      new RegExp(`^# TYPE voyage_trekresearch_${field} `, 'm'),
+      `${field} must appear as its own metric family — a numeric that never becomes a metric cannot be measured`,
+    );
+  }
+  // effort is a low-cardinality string: it must ride along as a LABEL, never
+  // as a metric family (a label is what makes high-vs-standard groupable).
+  assert.match(expected, /effort="[a-z]+"/, 'effort must be emitted as a label');
+  assert.doesNotMatch(
+    expected,
+    /^# TYPE voyage_trekresearch_effort /m,
+    'effort must not become a metric family',
+  );
+});
+
 test('empty-input handling: [] returns empty string (no headers)', () => {
   assert.equal(transformToPrometheus([]), '');
   assert.equal(transformToPrometheus(null), '');

tests/lib/profile-stats-fields.test.mjs

@@ -94,6 +94,81 @@ test('SC #11(b): commands/trekplan.md prose mentions phase_models + parallel_age
     'trekplan.md prose must mention parallel_agents (additive stats field)');
 });
 
+// --- Step 9: the five STORM measurement fields -----------------------------
+// Four numerics + one low-cardinality label. Without `effort` there is no axis
+// to group high-vs-standard runs on, and the measurement gate cannot be
+// computed at all.
+
+const STORM_FIELDS = [
+  'effort',
+  'unique_sources',
+  'dimensions_baseline',
+  'conv_turns',
+  'empty_turns',
+];
+
+test('Step 9: a standard-run trekresearch record parses and survives applyFieldAllowlist', async () => {
+  const { applyFieldAllowlist } = await import('../../lib/exporters/field-allowlist.mjs');
+  // A standard run: loop never armed, so no discovered dimensions and no turns.
+  const raw = JSON.parse(JSON.stringify({
+    _schema_id: 'trekresearch',
+    ts: '2026-08-09T12:00:00.000Z',
+    slug: 'add-auth',
+    mode: 'default',
+    scope: 'both',
+    engine: 'swarm',
+    question: 'free prose that must never reach the exporter',
+    project_dir: '/Users/somebody/repos/x',
+    brief_path: '/Users/somebody/repos/x/brief.md',
+    dimensions: 4,
+    dimensions_baseline: 4,
+    conv_turns: 0,
+    empty_turns: 0,
+    unique_sources: 11,
+    effort: 'standard',
+    agents_local: 5,
+    agents_external: 4,
+    gemini_used: false,
+    confidence: 0.8,
+    contradictions: 1,
+    open_questions: 2,
+    profile: 'premium',
+    profile_source: 'default',
+  }));
+
+  assert.equal(raw.dimensions_baseline, raw.dimensions,
+    'a standard run discovers no dimensions — baseline must equal the final count');
+
+  const out = applyFieldAllowlist(raw, 'trekresearch');
+  for (const field of STORM_FIELDS) {
+    assert.ok(field in out, `${field} must survive the trekresearch allowlist`);
+  }
+  assert.equal(out.conv_turns, 0);
+  assert.equal(out.empty_turns, 0);
+  assert.equal(out.effort, 'standard');
+  // Deny-by-omission must still hold for the PII-ish fields.
+  for (const denied of ['question', 'project_dir', 'brief_path']) {
+    assert.equal(denied in out, false, `${denied} must NOT reach the exporter`);
+  }
+});
+
+test('Step 9: commands/trekresearch.md prose names all five measurement fields', () => {
+  const content = readFileSync(join(REPO_ROOT, 'commands', 'trekresearch.md'), 'utf-8');
+  for (const field of STORM_FIELDS) {
+    assert.ok(content.includes(field),
+      `trekresearch.md prose must name ${field} — an emitted-but-undocumented field is unauditable`);
+  }
+});
+
+test('Step 9: tests/fixtures/jsonl-schemas.md trekresearch row lists the five fields', () => {
+  const doc = readFileSync(join(REPO_ROOT, 'tests', 'fixtures', 'jsonl-schemas.md'), 'utf-8');
+  const row = doc.split('\n').find(l => l.startsWith('| trekresearch-stats '));
+  assert.ok(row, 'jsonl-schemas.md is missing the trekresearch-stats row');
+  for (const field of STORM_FIELDS) {
+    assert.ok(row.includes(field), `authoring reference must list ${field}`);
+  }
+});
+
 test('SC #11(b): commands/trekresearch.md prose mentions external_research_enabled', () => {
   const content = readFileSync(join(REPO_ROOT, 'commands', 'trekresearch.md'), 'utf-8');
   assert.match(content, /external_research_enabled/,