@smartmemory/compose 0.3.6-beta → 0.3.7

package/lib/dispatch-ledger.js

@@ -0,0 +1,301 @@
+/**
+ * dispatch-ledger.js — closed, append-only telemetry events for agent dispatch.
+ *
+ * Ledger rows are addressed by an explicit project root so callers running in a
+ * worktree cannot accidentally split telemetry away from the build project.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+import { normalizeSince } from './feature-events.js';
+
+export const DISPATCH_LEDGER_RELATIVE_PATH = '.compose/data/dispatch-ledger.jsonl';
+
+/**
+ * Resolve the project root a dispatch connector should address its ledger by.
+ *
+ * Two paths write telemetry into the live compose checkout during a test run:
+ * an unattributed dispatch with no project_cwd falls back to process.cwd(), and
+ * a test that explicitly roots a build at process.cwd() threads that same live
+ * path through. Under NODE_TEST_CONTEXT, any ledger write addressed at the
+ * process cwd (the live checkout) is redirected to a hermetic tmpdir so
+ * full-suite runs never accrete fixture rows in the real .compose/data ledger.
+ * A test that threads its own tmpdir project root is addressed there, unchanged.
+ * Production paths never set NODE_TEST_CONTEXT, so they are unaffected.
+ *
+ * @param {string} [explicitCwd] the caller's project_cwd, when known
+ * @returns {string}
+ */
+export function resolveDispatchLedgerCwd(explicitCwd) {
+  const cwd = isString(explicitCwd) ? explicitCwd : process.cwd();
+  if (process.env.NODE_TEST_CONTEXT && resolve(cwd) === resolve(process.cwd())) {
+    return join(tmpdir(), 'compose-test-worktrees', 'dispatch-ledger');
+  }
+  return cwd;
+}
+
+export const DISPATCH_SITES = Object.freeze([
+  'build-step', 'consumer', 'review', 'review-repair', 'gsd', 'gate-qa',
+  'escalation', 'preflight', 'judge', 'design-chat', 'import', 'validation',
+  'new-project', 'unattributed',
+]);
+export const DISPATCH_OUTCOMES = Object.freeze(['ok', 'error', 'blocked']);
+export const SETTLEMENT_FAILURE_CLASSES = Object.freeze([
+  'ownership', 'vocabulary', 'normalization', 'agent', 'ensure-retry',
+]);
+export const ESTIMATE_LANES = Object.freeze(['trivial', 'standard', 'complex']);
+export const ESTIMATE_SOURCES = Object.freeze(['fresh', 'cached', 'escalated']);
+export const TRIAGE_CONFIDENCES = Object.freeze(['high', 'medium', 'low']);
+export const BUILD_TERMINAL_STATUSES = Object.freeze(['complete', 'failed', 'aborted']);
+export const BUILD_FILES_SOURCES = Object.freeze(['ship', 'accumulated']);
+
+const EVENT_FIELDS = {
+  dispatch: {
+    required: ['dispatch_id', 'site', 'agent', 'outcome'],
+    optional: [
+      'build_id', 'feature_code', 'step_id', 'attempt', 'model',
+      'effort_intended', 'effort_executed', 'tokens_in', 'tokens_out',
+      'tokens_total', 'usd', 'duration_ms', 'note',
+    ],
+  },
+  settlement: {
+    required: ['dispatch_id', 'accepted'],
+    optional: ['build_id', 'step_id', 'failure_class'],
+  },
+  'triage-estimate': {
+    required: ['build_id', 'feature_code', 'tier', 'lane', 'profile', 'estimate_source'],
+    optional: ['confidence'],
+  },
+  'build-actuals': {
+    required: [
+      'build_id', 'feature_code', 'terminal_status', 'files_changed_count',
+      'files_source', 'review_iterations', 'escalations', 'tokens_total', 'usd',
+    ],
+    optional: ['test_count', 'pass_rate'],
+  },
+};
+
+const countersByPath = new Map();
+
+function ledgerPath(projectCwd) {
+  return resolve(projectCwd, DISPATCH_LEDGER_RELATIVE_PATH);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isNullableFiniteNumber(value) {
+  return value === null || isFiniteNumber(value);
+}
+
+function isNullableString(value) {
+  return value === null || isString(value);
+}
+
+function isEnum(value, values) {
+  return values.includes(value);
+}
+
+function invalid(message) {
+  throw new Error(`dispatch-ledger.appendEvent: ${message}`);
+}
+
+function validateEvent(event, { allowExtra = false } = {}) {
+  if (!isPlainObject(event)) invalid('event must be an object');
+  if (!isString(event.kind)) invalid('kind is required');
+  const shape = EVENT_FIELDS[event.kind];
+  if (!shape) invalid(`unknown kind "${event.kind}"`);
+
+  const allowed = new Set(['kind', ...shape.required, ...shape.optional]);
+  if (!allowExtra) {
+    for (const field of Object.keys(event)) {
+      if (!allowed.has(field)) invalid(`unknown field "${field}" for ${event.kind}`);
+    }
+  }
+  for (const field of shape.required) {
+    if (!Object.hasOwn(event, field) || event[field] === undefined) {
+      invalid(`required field "${field}" is missing for ${event.kind}`);
+    }
+  }
+
+  switch (event.kind) {
+    case 'dispatch':
+      requireString(event, 'dispatch_id');
+      requireEnum(event, 'site', DISPATCH_SITES);
+      requireString(event, 'agent');
+      requireEnum(event, 'outcome', DISPATCH_OUTCOMES);
+      optionalString(event, 'build_id');
+      optionalString(event, 'feature_code');
+      optionalString(event, 'step_id');
+      optionalNumber(event, 'attempt');
+      optionalNullableString(event, 'model');
+      optionalNullableString(event, 'effort_intended');
+      optionalNullableString(event, 'effort_executed');
+      for (const field of ['tokens_in', 'tokens_out', 'tokens_total', 'usd', 'duration_ms']) {
+        optionalNullableNumber(event, field);
+      }
+      optionalString(event, 'note');
+      break;
+    case 'settlement':
+      requireString(event, 'dispatch_id');
+      if (typeof event.accepted !== 'boolean') invalid('accepted must be a boolean');
+      optionalString(event, 'build_id');
+      optionalString(event, 'step_id');
+      optionalEnum(event, 'failure_class', SETTLEMENT_FAILURE_CLASSES);
+      break;
+    case 'triage-estimate':
+      requireString(event, 'build_id');
+      requireString(event, 'feature_code');
+      if (!Number.isInteger(event.tier) || event.tier < 0 || event.tier > 4) {
+        invalid('tier must be an integer 0-4');
+      }
+      requireEnum(event, 'lane', ESTIMATE_LANES);
+      if (!isPlainObject(event.profile)) invalid('profile must be a non-array object');
+      requireEnum(event, 'estimate_source', ESTIMATE_SOURCES);
+      if (Object.hasOwn(event, 'confidence') && event.confidence !== null && !isEnum(event.confidence, TRIAGE_CONFIDENCES)) {
+        invalid(`confidence must be one of ${TRIAGE_CONFIDENCES.join(', ')} or null`);
+      }
+      break;
+    case 'build-actuals':
+      requireString(event, 'build_id');
+      requireString(event, 'feature_code');
+      requireEnum(event, 'terminal_status', BUILD_TERMINAL_STATUSES);
+      requireNumber(event, 'files_changed_count');
+      requireEnum(event, 'files_source', BUILD_FILES_SOURCES);
+      requireNumber(event, 'review_iterations');
+      requireNumber(event, 'escalations');
+      requireNumber(event, 'tokens_total');
+      requireNumber(event, 'usd');
+      optionalNullableNumber(event, 'test_count');
+      optionalNullableNumber(event, 'pass_rate');
+      break;
+  }
+}
+
+function requireString(event, field) {
+  if (!isString(event[field])) invalid(`${field} must be a non-empty string`);
+}
+
+function requireNumber(event, field) {
+  if (!isFiniteNumber(event[field])) invalid(`${field} must be a number`);
+}
+
+function requireEnum(event, field, values) {
+  if (!isEnum(event[field], values)) invalid(`${field} must be one of ${values.join(', ')}`);
+}
+
+function optionalString(event, field) {
+  if (Object.hasOwn(event, field) && !isString(event[field])) invalid(`${field} must be a non-empty string`);
+}
+
+function optionalNullableString(event, field) {
+  if (Object.hasOwn(event, field) && !isNullableString(event[field])) invalid(`${field} must be a string or null`);
+}
+
+function optionalNumber(event, field) {
+  if (Object.hasOwn(event, field) && !isFiniteNumber(event[field])) invalid(`${field} must be a number`);
+}
+
+function optionalNullableNumber(event, field) {
+  if (Object.hasOwn(event, field) && !isNullableFiniteNumber(event[field])) invalid(`${field} must be a number or null`);
+}
+
+function optionalEnum(event, field, values) {
+  if (Object.hasOwn(event, field) && !isEnum(event[field], values)) {
+    invalid(`${field} must be one of ${values.join(', ')}`);
+  }
+}
+
+function isValidStoredRow(row) {
+  if (!isPlainObject(row) || row.v !== 1 || !isIsoTimestamp(row.ts) || !Number.isInteger(row._seq) || row._seq < 0) {
+    return false;
+  }
+  try {
+    validateEvent(row, { allowExtra: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isIsoTimestamp(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value) && !Number.isNaN(Date.parse(value));
+}
+
+function seedCounter(path) {
+  if (countersByPath.has(path)) return countersByPath.get(path);
+  let highest = 0;
+  if (existsSync(path)) {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (isValidStoredRow(row)) highest = Math.max(highest, row._seq);
+      } catch {
+        // A torn JSONL row must not prevent later rows from being read.
+      }
+    }
+  }
+  countersByPath.set(path, highest);
+  return highest;
+}
+
+/**
+ * Append one closed dispatch-ledger event, stamping its immutable envelope.
+ *
+ * @param {string} projectCwd
+ * @param {object} event caller-supplied kind and closed payload only
+ * @returns {object} the row written to disk
+ */
+export function appendEvent(projectCwd, event) {
+  validateEvent(event);
+  const path = ledgerPath(projectCwd);
+  const nextSeq = seedCounter(path) + 1;
+  countersByPath.set(path, nextSeq);
+  const row = { v: 1, ts: new Date().toISOString(), _seq: nextSeq, ...event };
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(row) + '\n');
+  return row;
+}
+
+/**
+ * Tolerantly read valid, known ledger rows. Future fields are preserved.
+ *
+ * @param {string} projectCwd
+ * @param {object} [opts]
+ * @param {string} [opts.kind]
+ * @param {string|number|Date} [opts.since]
+ * @param {string} [opts.feature]
+ * @returns {Array<object>}
+ */
+export function readEvents(projectCwd, { kind, since, feature } = {}) {
+  const path = ledgerPath(projectCwd);
+  if (!existsSync(path)) return [];
+  const sinceMs = normalizeSince(since);
+  const rows = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (!isValidStoredRow(row)) continue;
+      if (kind && row.kind !== kind) continue;
+      if (feature && row.feature_code !== feature) continue;
+      if (sinceMs !== null && Date.parse(row.ts) < sinceMs) continue;
+      rows.push(row);
+    } catch {
+      // Malformed rows are expected in an append-only JSONL file after a tear.
+    }
+  }
+  return rows;
+}

package/lib/dispatch-metrics.js

@@ -0,0 +1,236 @@
+/**
+ * dispatch-metrics.js — read-only aggregation over the dispatch ledger.
+ *
+ * This module deliberately keeps the ledger's append-only observations intact:
+ * settlements and terminal actuals are reduced at read time by their `_seq`.
+ */
+
+import { readEvents } from './dispatch-ledger.js';
+
+const RETRY_NOTE = 'known undercount: child flows';
+const GSD_NOTE = 'not instrumented';
+
+function isNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function upperMiddle(values) {
+  const sorted = values.filter(isNumber).sort((a, b) => a - b);
+  return sorted.length ? sorted[Math.floor(sorted.length / 2)] : null;
+}
+
+function rate(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : null;
+}
+
+function highestBy(rows, key) {
+  const result = new Map();
+  for (const row of rows) {
+    const current = result.get(row[key]);
+    if (!current || row._seq > current._seq) result.set(row[key], row);
+  }
+  return result;
+}
+
+function compareNullable(a, b) {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+  return String(a).localeCompare(String(b));
+}
+
+function collectRowStats(dispatches, settlements, { gsd = false } = {}) {
+  const tokenValues = dispatches.map((row) => row.tokens_total).filter(isNumber);
+  const durationValues = dispatches.map((row) => row.duration_ms).filter(isNumber);
+  const settled = dispatches
+    .map((row) => settlements.get(row.dispatch_id))
+    .filter(Boolean);
+  const accepted = settled.filter((row) => row.accepted).length;
+  const retryEligible = dispatches.filter((row) => isNumber(row.attempt));
+  const retries = retryEligible.filter((row) => row.attempt > 1).length;
+
+  return {
+    token_sample_count: tokenValues.length,
+    null_usage_count: dispatches.filter((row) => !isNumber(row.tokens_total)).length,
+    median_tokens: upperMiddle(tokenValues),
+    duration_sample_count: durationValues.length,
+    median_duration_ms: upperMiddle(durationValues),
+    completion: {
+      ok: dispatches.filter((row) => row.outcome === 'ok').length,
+      total: dispatches.length,
+      rate: rate(dispatches.filter((row) => row.outcome === 'ok').length, dispatches.length),
+    },
+    acceptance: {
+      accepted,
+      settled: settled.length,
+      rate: rate(accepted, settled.length),
+      note: gsd ? GSD_NOTE : null,
+    },
+    retry: {
+      retries,
+      eligible: retryEligible.length,
+      rate: rate(retries, retryEligible.length),
+      note: RETRY_NOTE,
+    },
+    usd_total: dispatches.reduce((total, row) => total + (isNumber(row.usd) ? row.usd : 0), 0),
+  };
+}
+
+function realizedLane(actual) {
+  if (actual.escalations >= 1 || actual.review_iterations >= 3 || actual.files_changed_count >= 6) return 'complex';
+  if (actual.files_changed_count <= 2 && actual.review_iterations <= 1 && actual.escalations === 0) return 'trivial';
+  return 'standard';
+}
+
+function acrrSummary(rows) {
+  const total = rows.length;
+  const matched = rows.filter((row) => row.matched).length;
+  return { matched, total, rate: rate(matched, total) };
+}
+
+/**
+ * Aggregate dispatch, settlement, estimate, and terminal actual rows without
+ * mutating the ledger.
+ *
+ * @param {string} projectCwd
+ * @param {{ since?: string|number|Date, feature?: string }} [opts]
+ * @returns {object}
+ */
+export function collectDispatchMetrics(projectCwd, { since, feature } = {}) {
+  // Settlements have no feature code. Read one since-filtered population first,
+  // then join them to the feature-filtered dispatches below.
+  const allRows = readEvents(projectCwd, { since });
+  const inFeature = (row) => !feature || row.feature_code === feature;
+  const dispatches = allRows.filter((row) => row.kind === 'dispatch' && inFeature(row));
+  const settlements = highestBy(allRows.filter((row) => row.kind === 'settlement'), 'dispatch_id');
+
+  const modelBuckets = new Map();
+  for (const row of dispatches) {
+    const executed = row.effort_executed ?? null;
+    const intendedWhenUnknown = executed === null ? (row.effort_intended ?? null) : null;
+    const values = [row.model ?? null, executed, intendedWhenUnknown];
+    const key = JSON.stringify(values);
+    if (!modelBuckets.has(key)) modelBuckets.set(key, { values, rows: [] });
+    modelBuckets.get(key).rows.push(row);
+  }
+  const model_effort = [...modelBuckets.values()]
+    .sort((a, b) => compareNullable(a.values[0], b.values[0]) || compareNullable(a.values[1], b.values[1]) || compareNullable(a.values[2], b.values[2]))
+    .map(({ values: [model, effort_executed, effort_intended_when_unknown], rows }) => {
+      const stats = collectRowStats(rows, settlements, { gsd: rows.every((row) => row.site === 'gsd') });
+      return {
+        model, effort_executed, effort_intended_when_unknown, dispatch_count: rows.length,
+        ...stats,
+      };
+    });
+
+  const siteBuckets = new Map();
+  for (const row of dispatches) {
+    if (!siteBuckets.has(row.site)) siteBuckets.set(row.site, []);
+    siteBuckets.get(row.site).push(row);
+  }
+  const sites = [...siteBuckets.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([site, rows]) => ({ site, dispatch_count: rows.length, ...collectRowStats(rows, settlements, { gsd: site === 'gsd' }) }));
+
+  const estimates = allRows.filter((row) => row.kind === 'triage-estimate' && inFeature(row));
+  const actualRows = allRows.filter((row) => row.kind === 'build-actuals' && inFeature(row));
+  const actuals = highestBy(actualRows, 'build_id');
+  const estimateBuildIds = new Set(estimates.map((row) => row.build_id));
+  const acrrRows = estimates
+    .map((estimate) => {
+      const actual = actuals.get(estimate.build_id) ?? null;
+      const eligible = actual?.terminal_status === 'complete';
+      const lane = eligible ? realizedLane(actual) : null;
+      return {
+        build_id: estimate.build_id,
+        feature_code: estimate.feature_code,
+        estimate_source: estimate.estimate_source,
+        confidence: estimate.confidence ?? null,
+        estimated_lane: estimate.lane,
+        terminal_status: actual?.terminal_status ?? null,
+        realized_lane: lane,
+        matched: eligible ? estimate.lane === lane : false,
+        files_changed_count: actual?.files_changed_count ?? null,
+        files_source: actual?.files_source ?? null,
+        review_iterations: actual?.review_iterations ?? null,
+        escalations: actual?.escalations ?? null,
+      };
+    })
+    .sort((a, b) => a.build_id.localeCompare(b.build_id));
+  const eligibleRows = acrrRows.filter((row) => row.terminal_status === 'complete' && row.estimate_source !== 'escalated');
+  const escalatedRows = acrrRows.filter((row) => row.terminal_status === 'complete' && row.estimate_source === 'escalated');
+  const failed_attempts = actualRows.filter((row) => row.terminal_status === 'failed').length;
+  const aborted_attempts = actualRows.filter((row) => row.terminal_status === 'aborted').length;
+
+  return {
+    v: 1,
+    filters: { since: since ?? null, feature: feature ?? null },
+    coverage: {
+      dispatch_count: dispatches.length,
+      unattributed_count: dispatches.filter((row) => row.site === 'unattributed').length,
+      null_usage_count: dispatches.filter((row) => !isNumber(row.tokens_total)).length,
+    },
+    model_effort,
+    sites,
+    acrr: {
+      eligible: acrrSummary(eligibleRows),
+      escalated: acrrSummary(escalatedRows),
+      attrition_count: failed_attempts + aborted_attempts,
+      failed_attempts,
+      aborted_attempts,
+      pending_count: acrrRows.filter((row) => row.terminal_status === null).length,
+      unpaired_count: [...actuals.keys()].filter((buildId) => !estimateBuildIds.has(buildId)).length,
+      rows: acrrRows,
+    },
+    known_limitations: { retry_rate: RETRY_NOTE, gsd_acceptance: GSD_NOTE },
+  };
+}
+
+function formatRate(value) {
+  return value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`;
+}
+
+function formatMedian(value) {
+  return value === null ? 'n/a' : String(value);
+}
+
+function formatAcceptance(acceptance) {
+  return acceptance.note === GSD_NOTE ? 'n/a (not instrumented)' : formatRate(acceptance.rate);
+}
+
+/** Render a compact, stable human report for `compose metrics`. */
+export function renderDispatchMetrics(report) {
+  const lines = [
+    'Model × executed effort',
+    'model | executed | intended when unknown | dispatches | median tokens | median ms | completion | acceptance | retry | usd',
+  ];
+  for (const row of report.model_effort) {
+    lines.push([
+      row.model === null ? '(model: unknown)' : row.model,
+      row.effort_executed ?? 'unknown',
+      row.effort_intended_when_unknown ?? '—',
+      row.dispatch_count,
+      formatMedian(row.median_tokens),
+      formatMedian(row.median_duration_ms),
+      formatRate(row.completion.rate),
+      formatAcceptance(row.acceptance),
+      formatRate(row.retry.rate),
+      row.usd_total,
+    ].join(' | '));
+  }
+  lines.push('', 'Sites', 'site | dispatches | median tokens | median ms | completion | acceptance | retry | usd');
+  for (const row of report.sites) {
+    lines.push([
+      row.site, row.dispatch_count, formatMedian(row.median_tokens), formatMedian(row.median_duration_ms),
+      formatRate(row.completion.rate), formatAcceptance(row.acceptance), formatRate(row.retry.rate), row.usd_total,
+    ].join(' | '));
+  }
+  lines.push('', 'ACRR');
+  lines.push(`eligible: ${report.acrr.eligible.matched}/${report.acrr.eligible.total} (${formatRate(report.acrr.eligible.rate)})`);
+  lines.push(`escalated: ${report.acrr.escalated.matched}/${report.acrr.escalated.total} (${formatRate(report.acrr.escalated.rate)})`);
+  lines.push(`attrition: ${report.acrr.attrition_count} (failed attempts: ${report.acrr.failed_attempts}, aborted attempts: ${report.acrr.aborted_attempts}, pending: ${report.acrr.pending_count}, unpaired: ${report.acrr.unpaired_count})`);
+  lines.push('', 'Known limitations');
+  lines.push(`retry rate: ${report.known_limitations.retry_rate}`);
+  lines.push(`GSD acceptance: ${report.known_limitations.gsd_acceptance}`);
+  return `${lines.join('\n')}\n`;
+}

package/lib/experiment-judge.js

@@ -121,6 +121,7 @@ export async function judge({ diff, goal, judgeModel, stratum, cwd }) {
   try {
     const prompt = buildJudgePrompt(diff, goal);
     const { provider, modelID, thinking, effort } = resolveAgentConfig(judgeModel);
+    const telemetry = { site: 'judge', project_cwd: cwd };
 
     let text;
     if (typeof stratum.agentRun === 'function') {
@@ -130,11 +131,15 @@ export async function judge({ diff, goal, judgeModel, stratum, cwd }) {
         thinking: thinking ?? undefined,
         effort:   effort   ?? undefined,
         cwd:      cwd      ?? undefined,
+        telemetry,
       });
       text = result?.text ?? '';
     } else {
       // Fallback: runAgentText (no model pinning — test harnesses may use this).
-      text = await stratum.runAgentText(provider, prompt, { cwd: cwd ?? undefined });
+      text = await stratum.runAgentText(provider, prompt, {
+        cwd: cwd ?? undefined,
+        telemetry,
+      });
     }
 
     return extractJudgeResult(text);

package/lib/feature-writer.js

@@ -68,6 +68,7 @@ const IMPACTS = new Set(['low', 'medium', 'high']);
 // front estimator, the doc-reading refinement, or an escalation bump.
 const LANES = new Set(['trivial', 'standard', 'complex']);
 const ESTIMATE_SOURCES = new Set(['front', 'refined', 'escalated']);
+const TRIAGE_CONFIDENCES = new Set(['high', 'medium', 'low']);
 
 // ---------------------------------------------------------------------------
 // validateFeatureFields — shared field-shape guard
@@ -90,6 +91,7 @@ const ESTIMATE_SOURCES = new Set(['front', 'refined', 'escalated']);
  * @param {number} [fields.triageTier]     integer 0-4
  * @param {string} [fields.lane]           one of trivial|standard|complex
  * @param {string} [fields.estimateSource] one of front|refined|escalated
+ * @param {string} [fields.triageConfidence] one of high|medium|low
  */
 export function validateFeatureFields(fields) {
   if (fields.complexity !== undefined && !COMPLEXITIES.has(fields.complexity)) {
@@ -107,6 +109,11 @@ export function validateFeatureFields(fields) {
       `feature-writer: invalid estimateSource "${fields.estimateSource}" — must be one of ${[...ESTIMATE_SOURCES].join(', ')}`
     );
   }
+  if (fields.triageConfidence !== undefined && !TRIAGE_CONFIDENCES.has(fields.triageConfidence)) {
+    throw new Error(
+      `feature-writer: invalid triageConfidence "${fields.triageConfidence}" — must be one of ${[...TRIAGE_CONFIDENCES].join(', ')}`
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -164,6 +171,7 @@ function maybeIdempotent(args, fn) {
  * @param {string} [args.lane]             COMP-TRIAGE-5: trivial | standard | complex
  * @param {number} [args.triageTier]       COMP-TRIAGE-5: integer 0-4
  * @param {string} [args.estimateSource]   COMP-TRIAGE-5: front | refined | escalated
+ * @param {string} [args.triageConfidence] COMP-TRIAGE-6: high | medium | low
  * @param {boolean} [args.force]
  * @param {string} [args.idempotency_key]
  */
@@ -235,6 +243,7 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.lane !== undefined) feature.lane = args.lane;
     if (args.triageTier !== undefined) feature.triageTier = args.triageTier;
     if (args.estimateSource !== undefined) feature.estimateSource = args.estimateSource;
+    if (args.triageConfidence !== undefined) feature.triageConfidence = args.triageConfidence;
 
     let roundtrip = null;
     if (isLocalProvider(provider)) {

package/lib/gsd.js

@@ -518,7 +518,7 @@ async function runOneStep(response, ctx) {
           // by definition a GSD task, so timing.json + diffs/<id>.diff are written
           // for the milestone report. The build consumer path omits it (no marker),
           // so build-mode fanout stays byte-identical.
-          context: { cwd, featureCode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage) => recordTsAgentUsage(ctx, usage), taskResultPath },
+          context: { cwd, projectCwd: cwd, featureCode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage) => recordTsAgentUsage(ctx, usage), taskResultPath },
           // runAndNormalize narrates via progress.debug/warn/info/toolUse — gsd
           // has no cockpit, so a COMPLETE no-op (not just stepStart/stepDone) is
           // required or the item throws "progress.debug is not a function".
@@ -565,7 +565,16 @@ async function runOneStep(response, ctx) {
 
     // D2(b): dispatch via agentRun (not runAgentText) so the TS complete
     // envelope's usage is captured and debited into the cumulative ledger.
-    const runOut = await stratum.agentRun(step.agent ?? 'claude', step.do ?? '', { cwd });
+    const runOut = await stratum.agentRun(step.agent ?? 'claude', step.do ?? '', {
+      cwd,
+      telemetry: {
+        site: 'gsd',
+        project_cwd: cwd,
+        feature_code: featureCode,
+        step_id: step.id,
+        ...(typeof step.attempt === 'number' ? { attempt: step.attempt } : {}),
+      },
+    });
     const text = runOut?.text ?? '';
     recordTsAgentUsage(ctx, runOut?.usage);
     // V1: also report usage in the step_done envelope so the ENGINE debits its