@tekyzinc/gsd-t 3.10.13 → 3.10.15

package/bin/token-telemetry.cjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Token Telemetry — per-subagent-spawn granular telemetry recorder
+ *
+ * Records one JSON object per line to .gsd-t/token-metrics.jsonl for every
+ * subagent spawn across every command file. Feeds:
+ *   - bin/runway-estimator.js (M35 Wave 3) — pre-flight runway projection
+ *   - bin/token-optimizer.js  (M35 Wave 4) — optimization backlog detector
+ *   - gsd-t metrics --tokens / --halts / --tokens --context-window CLI
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ * Zero API calls (reads .gsd-t/.context-meter-state.json written by M34 hook).
+ * Single-writer assumption — no lockfile; fs.appendFileSync is atomic for
+ * writes under PIPE_BUF (4096 bytes on POSIX), and a single record is well
+ * under that limit.
+ *
+ * Contract: .gsd-t/contracts/token-telemetry-contract.md v1.0.0
+ * Schema is frozen for v1.x — fields can be added in minor bumps but never
+ * removed or renamed.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Frozen schema (matches token-telemetry-contract.md v1.0.0) ──────────────
+
+/**
+ * The 18 required fields. Order is not significant on disk (parsers use keys),
+ * but this array is the canonical list for validation error messages and
+ * downstream tooling that needs a stable field enumeration.
+ */
+const REQUIRED_FIELDS = Object.freeze([
+  "timestamp",
+  "milestone",
+  "command",
+  "phase",
+  "step",
+  "domain",
+  "domain_type",
+  "task",
+  "model",
+  "duration_s",
+  "input_tokens_before",
+  "input_tokens_after",
+  "tokens_consumed",
+  "context_window_pct_before",
+  "context_window_pct_after",
+  "outcome",
+  "halt_type",
+  "escalated_via_advisor",
+]);
+
+/**
+ * Type enforcement map. Keys are field names; values are either "string",
+ * "number", "boolean", "nullable-string", or a Set of valid string enum values.
+ * halt_type is the only nullable field in v1.0.0 per the contract.
+ */
+const FIELD_TYPES = Object.freeze({
+  timestamp: "string",
+  milestone: "string",
+  command: "string",
+  phase: "string",
+  step: "string",
+  domain: "string",
+  domain_type: "string",
+  task: "string",
+  model: new Set(["haiku", "sonnet", "opus"]),
+  duration_s: "number",
+  input_tokens_before: "number",
+  input_tokens_after: "number",
+  tokens_consumed: "number",
+  context_window_pct_before: "number",
+  context_window_pct_after: "number",
+  outcome: new Set(["success", "failure", "blocked", "escalated"]),
+  halt_type: "nullable-string", // null OR one of the halt_type enum values
+  escalated_via_advisor: "boolean",
+});
+
+const HALT_TYPE_ENUM = Object.freeze(
+  new Set(["clean", "runway-refusal", "headless-handoff", "native-compact"]),
+);
+
+// ── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  recordSpawn,
+  readAll,
+  aggregate,
+  REQUIRED_FIELDS,
+};
+
+// ── recordSpawn ─────────────────────────────────────────────────────────────
+
+/**
+ * Append one telemetry record to .gsd-t/token-metrics.jsonl.
+ *
+ * @param {object} record - A record matching the v1.0.0 schema. All 18
+ *   required fields must be present and of the correct type.
+ * @param {string} [projectDir] - Optional project root. Defaults to cwd.
+ * @throws {Error} on missing required field, wrong type, or I/O failure.
+ * @returns {void}
+ */
+function recordSpawn(record, projectDir) {
+  validateRecord(record);
+  const dir = projectDir || process.cwd();
+  const gsdDir = path.join(dir, ".gsd-t");
+  ensureDir(gsdDir);
+  const fp = path.join(gsdDir, "token-metrics.jsonl");
+  const line = JSON.stringify(record) + "\n";
+  fs.appendFileSync(fp, line);
+}
+
+// ── readAll ─────────────────────────────────────────────────────────────────
+
+/**
+ * Read and parse every record from .gsd-t/token-metrics.jsonl.
+ *
+ * @param {string} [projectDir] - Optional project root. Defaults to cwd.
+ * @returns {Array<object>} - Array of parsed records. Returns [] if the file
+ *   does not exist. Malformed lines are skipped with a console.warn (does
+ *   not abort the read).
+ */
+function readAll(projectDir) {
+  const dir = projectDir || process.cwd();
+  const fp = path.join(dir, ".gsd-t", "token-metrics.jsonl");
+  if (!fs.existsSync(fp)) return [];
+  const raw = fs.readFileSync(fp, "utf8");
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  const records = [];
+  for (const line of lines) {
+    try {
+      records.push(JSON.parse(line));
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn(`token-telemetry.readAll: skipping malformed line: ${e.message}`);
+    }
+  }
+  return records;
+}
+
+// ── aggregate ───────────────────────────────────────────────────────────────
+
+/**
+ * Group records by one or more fields and compute per-group statistics.
+ *
+ * @param {Array<object>} records
+ * @param {{ by: Array<string> }} options - Array of field names to group by.
+ *   Unknown fields yield empty-string values in the group key.
+ * @returns {Array<{ key: object, count: number, total_tokens: number,
+ *                   mean: number, median: number, p95: number }>}
+ */
+function aggregate(records, options) {
+  const by = (options && Array.isArray(options.by)) ? options.by : [];
+  if (!Array.isArray(records) || records.length === 0) return [];
+
+  // Build groups keyed on a stable string (JSON of the key object).
+  const groups = new Map();
+  for (const r of records) {
+    const key = {};
+    for (const field of by) key[field] = r[field] != null ? r[field] : "";
+    const keyStr = JSON.stringify(key);
+    if (!groups.has(keyStr)) groups.set(keyStr, { key, tokens: [] });
+    const tokens = typeof r.tokens_consumed === "number" ? r.tokens_consumed : 0;
+    groups.get(keyStr).tokens.push(tokens);
+  }
+
+  const result = [];
+  for (const { key, tokens } of groups.values()) {
+    const count = tokens.length;
+    const total_tokens = tokens.reduce((s, v) => s + v, 0);
+    const mean = count > 0 ? total_tokens / count : 0;
+    const sorted = tokens.slice().sort((a, b) => a - b);
+    const median = count > 0 ? sorted[Math.floor(count / 2)] : 0;
+    const p95idx = count > 0 ? Math.min(count - 1, Math.floor(count * 0.95)) : 0;
+    const p95 = count > 0 ? sorted[p95idx] : 0;
+    result.push({ key, count, total_tokens, mean, median, p95 });
+  }
+  return result;
+}
+
+// ── Internal: schema validation ─────────────────────────────────────────────
+
+function validateRecord(record) {
+  if (record == null || typeof record !== "object" || Array.isArray(record)) {
+    throw new Error(
+      `recordSpawn: record must be a plain object, got ${Array.isArray(record) ? "array" : typeof record}`,
+    );
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in record)) {
+      throw new Error(`recordSpawn: missing required field: ${field}`);
+    }
+  }
+  for (const field of REQUIRED_FIELDS) {
+    const expected = FIELD_TYPES[field];
+    const value = record[field];
+    if (expected === "string") {
+      if (typeof value !== "string") {
+        throw new Error(
+          `recordSpawn: field ${field} has wrong type: expected string, got ${typeName(value)}`,
+        );
+      }
+    } else if (expected === "number") {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(
+          `recordSpawn: field ${field} has wrong type: expected finite number, got ${typeName(value)}`,
+        );
+      }
+    } else if (expected === "boolean") {
+      if (typeof value !== "boolean") {
+        throw new Error(
+          `recordSpawn: field ${field} has wrong type: expected boolean, got ${typeName(value)}`,
+        );
+      }
+    } else if (expected === "nullable-string") {
+      // halt_type: null OR one of the halt_type enum values
+      if (value !== null) {
+        if (typeof value !== "string" || !HALT_TYPE_ENUM.has(value)) {
+          throw new Error(
+            `recordSpawn: field ${field} has wrong value: expected null or one of ${Array.from(HALT_TYPE_ENUM).join("|")}, got ${JSON.stringify(value)}`,
+          );
+        }
+      }
+    } else if (expected instanceof Set) {
+      // string enum
+      if (typeof value !== "string" || !expected.has(value)) {
+        throw new Error(
+          `recordSpawn: field ${field} has wrong value: expected one of ${Array.from(expected).join("|")}, got ${JSON.stringify(value)}`,
+        );
+      }
+    }
+  }
+}
+
+function typeName(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}
+
+// ── Internal: fs helpers ────────────────────────────────────────────────────
+
+function ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}

package/commands/gsd-t-backlog-list.md

@@ -13,11 +13,11 @@ If `$ARGUMENTS` contains `--file {path}`, read from `.gsd-t/{path}` instead of t
 
 Also support `--status {pending|promoted|rejected}` when listing the optimization backlog — filters by the `**Status**:` field inside each H2 block.
 
-If `--file optimization-backlog.md` is supplied, use `bin/token-optimizer.js` parseBacklog() to parse entries, then render a simplified table with columns: ID, Type, Status, Evidence (truncated to 80 chars). Example:
+If `--file optimization-backlog.md` is supplied, use `bin/token-optimizer.cjs` parseBacklog() to parse entries, then render a simplified table with columns: ID, Type, Status, Evidence (truncated to 80 chars). Example:
 
 ```bash
 node -e "
-const opt = require('./bin/token-optimizer.js');
+const opt = require('./bin/token-optimizer.cjs');
 const entries = opt.parseBacklog(opt.readBacklog('.'));
 const statusFilter = process.argv[1] || '';
 const filtered = statusFilter

package/commands/gsd-t-complete-milestone.md

@@ -515,7 +515,7 @@ After all quality gates pass and the milestone is archived, run the token optimi
 ```bash
 node -e "
 try {
-  const opt = require('./bin/token-optimizer.js');
+  const opt = require('./bin/token-optimizer.cjs');
   const recs = opt.detectRecommendations({projectDir: '.', lookbackMilestones: 3});
   opt.appendToBacklog(recs, '.');
   if (recs.length === 0) {

package/commands/gsd-t-debug.md

@@ -27,7 +27,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-debug',phase:'debug',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-opus}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-debug',phase:'debug',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-opus}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist.
@@ -38,7 +38,7 @@ Debug uses conservative per-iteration cost (opus-default fallback = 8%/task). Ru
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-debug',
   domain_type: '',
   remaining_tasks: 1,
@@ -48,7 +48,7 @@ console.log(JSON.stringify(r, null, 2));
 if (!r.can_start) {
   console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
   console.log('Auto-spawning headless to continue in a fresh context.');
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-debug', args: [], continue_from: '.'
   });
   console.log('Session ID: ' + s.id);
@@ -353,7 +353,7 @@ Run via Bash before each iteration:
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-debug',
   domain_type: '',
   remaining_tasks: 1,
@@ -381,7 +381,7 @@ if (!r.can_start) {
   console.log('⛔ Runway exceeded mid-loop — projected ' + r.projected_end_pct + '% at iteration ' + snapshot.iteration_n_plus_1);
   console.log('Persisted hypothesis + last fix + test output to ' + ledgerPath);
 
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-debug',
     args: ['--resume', 'iteration-' + snapshot.iteration_n_plus_1],
     continue_from: ledgerPath

package/commands/gsd-t-doc-ripple.md

@@ -25,7 +25,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-doc-ripple',phase:'doc-ripple',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-doc-ripple',phase:'doc-ripple',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist.

package/commands/gsd-t-execute.md

@@ -31,7 +31,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-execute',phase:'${PHASE:-execute}',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-execute',phase:'${PHASE:-execute}',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist — token-log.md is human-readable with context percentage, token-metrics.jsonl is machine-readable with the full 18-field schema for `gsd-t metrics --tokens/--halts/--context-window` aggregation.
@@ -42,7 +42,7 @@ Run via Bash. Count the `remaining_tasks` from the unblocked task list (Step 1 r
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-execute',
   domain_type: '{DOMAIN_TYPE}',
   remaining_tasks: {N},
@@ -52,7 +52,7 @@ console.log(JSON.stringify(r, null, 2));
 if (!r.can_start) {
   console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
   console.log('Auto-spawning headless to continue in a fresh context.');
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-execute', args: [], continue_from: '.'
   });
   console.log('Session ID: ' + s.id);

package/commands/gsd-t-integrate.md

@@ -27,7 +27,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-integrate',phase:'integrate',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-integrate',phase:'integrate',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist.
@@ -38,7 +38,7 @@ Count the integration wiring seams in `.gsd-t/contracts/integration-points.md` a
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-integrate',
   domain_type: '',
   remaining_tasks: {N},
@@ -48,7 +48,7 @@ console.log(JSON.stringify(r, null, 2));
 if (!r.can_start) {
   console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
   console.log('Auto-spawning headless to continue in a fresh context.');
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-integrate', args: [], continue_from: '.'
   });
   console.log('Session ID: ' + s.id);

package/commands/gsd-t-optimization-apply.md

@@ -2,7 +2,7 @@
 
 Apply (promote) a pending recommendation from `.gsd-t/optimization-backlog.md`. Takes `$ARGUMENTS` as the recommendation ID (e.g., `M35-OPT-001`).
 
-Recommendations are produced by `bin/token-optimizer.js` at `complete-milestone` and are **never auto-applied**. This command is the user's deliberate promotion step.
+Recommendations are produced by `bin/token-optimizer.cjs` at `complete-milestone` and are **never auto-applied**. This command is the user's deliberate promotion step.
 
 ## Usage
 
@@ -25,7 +25,7 @@ Then exit.
 
 ```bash
 node -e "
-const opt = require('./bin/token-optimizer.js');
+const opt = require('./bin/token-optimizer.cjs');
 const content = opt.readBacklog('.');
 const entries = opt.parseBacklog(content);
 const id = process.argv[1];
@@ -58,7 +58,7 @@ At Autonomy Level 3: automatically choose option 1 (quick task) unless the recom
 
 ```bash
 node -e "
-const opt = require('./bin/token-optimizer.js');
+const opt = require('./bin/token-optimizer.cjs');
 let content = opt.readBacklog('.');
 content = opt.setRecommendationStatus(content, process.argv[1], {
   status: 'promoted'

package/commands/gsd-t-optimization-reject.md

@@ -28,7 +28,7 @@ Run `/user:gsd-t-backlog-list --file optimization-backlog.md` to see pending rec
 
 ```bash
 node -e "
-const opt = require('./bin/token-optimizer.js');
+const opt = require('./bin/token-optimizer.cjs');
 const content = opt.readBacklog('.');
 const entries = opt.parseBacklog(content);
 const id = process.argv[1];
@@ -54,7 +54,7 @@ The reason text defaults to "no reason given" when `--reason` is absent.
 ```bash
 REASON="${REASON:-no reason given}"
 node -e "
-const opt = require('./bin/token-optimizer.js');
+const opt = require('./bin/token-optimizer.cjs');
 let content = opt.readBacklog('.');
 content = opt.setRecommendationStatus(content, process.argv[1], {
   status: 'rejected',
@@ -87,7 +87,7 @@ Add a Decision Log entry to `.gsd-t/progress.md`:
 
 ## Cooldown Behavior
 
-After rejection, `bin/token-optimizer.js` will skip any fingerprint-matching recommendation for 5 subsequent `complete-milestone` invocations. The cooldown counter is stored in the entry's `Rejection cooldown` field and decrements at each `complete-milestone` run (decrement logic lives in `bin/token-optimizer.js` — Wave 5 docs task DAT-T? covers the decrement step if missing).
+After rejection, `bin/token-optimizer.cjs` will skip any fingerprint-matching recommendation for 5 subsequent `complete-milestone` invocations. The cooldown counter is stored in the entry's `Rejection cooldown` field and decrements at each `complete-milestone` run (decrement logic lives in `bin/token-optimizer.cjs` — Wave 5 docs task DAT-T? covers the decrement step if missing).
 
 ## Contract References
 

package/commands/gsd-t-quick.md

@@ -27,7 +27,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-quick',phase:'quick',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-quick',phase:'quick',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist — token-log.md is human-readable, token-metrics.jsonl is machine-readable for `gsd-t metrics` aggregation.
@@ -38,7 +38,7 @@ Quick tasks are always single-task, so `remaining_tasks=1`. Run via Bash:
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-quick',
   domain_type: '',
   remaining_tasks: 1,
@@ -48,7 +48,7 @@ console.log(JSON.stringify(r, null, 2));
 if (!r.can_start) {
   console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
   console.log('Auto-spawning headless to continue in a fresh context.');
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-quick', args: [], continue_from: '.'
   });
   console.log('Session ID: ' + s.id);

package/commands/gsd-t-resume.md

@@ -46,7 +46,7 @@ Before reading any continue-here file or state file, check if a parent process w
 node -e "
 const sessionId = process.env.CLAUDE_HEADLESS_SESSION_ID;
 if (!sessionId) { process.exit(0); }
-const hl = require('./bin/handoff-lock.js');
+const hl = require('./bin/handoff-lock.cjs');
 hl.waitForLockRelease('.', sessionId, 5000)
   .then(() => process.exit(0))
   .catch(e => { console.error('[resume] handoff lock wait timed out:', e.message); process.exit(0); });

package/commands/gsd-t-status.md

@@ -38,7 +38,7 @@ Immediately after the headless banner, surface the count of pending token-optimi
 ```bash
 node -e "
 try {
-  const opt = require('./bin/token-optimizer.js');
+  const opt = require('./bin/token-optimizer.cjs');
   const entries = opt.parseBacklog(opt.readBacklog('.'));
   const pending = entries.filter(e => e.status === 'pending').length;
   if (pending > 0) {

package/commands/gsd-t-unattended.md

@@ -243,7 +243,7 @@ Otherwise, run the actual spawn:
 ```bash
 node -e "
 const path = require('path');
-const { spawnSupervisor } = require('./bin/gsd-t-unattended-platform.js');
+const { spawnSupervisor } = require('./bin/gsd-t-unattended-platform.cjs');
 
 // Parse CLI args forwarded from the launch command
 const hours = parseInt(process.env.GSD_T_HOURS || '24', 10) || 24;
@@ -412,7 +412,7 @@ After the tool call, end the turn. The in-session watch loop takes over from her
 
 - **Singleton**: only one supervisor per project at a time. PID collision → refuse with "already running" message.
 - **Stale stop sentinel**: if `.gsd-t/.unattended/stop` exists from a prior run, Step 1d removes it before spawning.
-- **Platform helper**: uses `spawnSupervisor` from `bin/gsd-t-unattended-platform.js` — never hand-rolls `child_process.spawn` directly. This handles macOS/Linux/Windows differences.
+- **Platform helper**: uses `spawnSupervisor` from `bin/gsd-t-unattended-platform.cjs` — never hand-rolls `child_process.spawn` directly. This handles macOS/Linux/Windows differences.
 - **Dry-run**: `--dry-run` prints the would-be invocation without spawning. Useful for validating flags before a long overnight run.
 - **No doc ripple, no pre-commit gate**: this command spawns a background process; it does not modify any source files or contracts.
 - **watch command is stateless**: after this command returns, every `/user:gsd-t-unattended-watch` tick re-reads state from disk. There is no in-memory state to preserve.

package/commands/gsd-t-wave.md

@@ -26,7 +26,7 @@ T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.
 ```bash
 T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
 T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-wave',phase:'${PHASE:-}',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+node -e "require('./bin/token-telemetry.cjs').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-wave',phase:'${PHASE:-}',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
 ```
 
 The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist — token-log.md is human-readable with context percentage, token-metrics.jsonl is machine-readable with the full 18-field schema for `gsd-t metrics --tokens/--halts/--context-window` aggregation.
@@ -37,7 +37,7 @@ Count the wave's total task count (sum of atomic tasks across domains in the cur
 
 ```bash
 node -e "
-const r = require('./bin/runway-estimator.js').estimateRunway({
+const r = require('./bin/runway-estimator.cjs').estimateRunway({
   command: 'gsd-t-wave',
   domain_type: '',
   remaining_tasks: {N},
@@ -47,7 +47,7 @@ console.log(JSON.stringify(r, null, 2));
 if (!r.can_start) {
   console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
   console.log('Auto-spawning headless to continue in a fresh context.');
-  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+  const s = require('./bin/headless-auto-spawn.cjs').autoSpawnHeadless({
     command: 'gsd-t-wave', args: [], continue_from: '.'
   });
   console.log('Session ID: ' + s.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.10.13",
+  "version": "3.10.15",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 61 slash commands with unattended supervisor relay, headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/context-meter/transcript-parser.js

@@ -152,7 +152,69 @@ async function parseTranscript(transcriptPath) {
     return null;
   }
 
-  return { system, messages };
+  return { system, messages: sanitizeToolPairs(messages) };
+}
+
+/**
+ * Enforce the count_tokens adjacency constraint: every assistant tool_use
+ * must be immediately followed by a user message whose tool_result ids match
+ * ALL tool_use ids from the preceding assistant message.  Walk the message
+ * list and strip tool_use / tool_result blocks from any pair that violates
+ * this rule. Drop messages that become empty after stripping.
+ */
+function sanitizeToolPairs(messages) {
+  const out = [];
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!Array.isArray(m.content)) { out.push(m); continue; }
+
+    if (m.role === "assistant") {
+      const toolUseIds = new Set();
+      for (const b of m.content) {
+        if (b.type === "tool_use" && typeof b.id === "string") toolUseIds.add(b.id);
+      }
+
+      if (toolUseIds.size === 0) { out.push(m); continue; }
+
+      const next = messages[i + 1];
+      const nextResultIds = new Set();
+      if (next && next.role === "user" && Array.isArray(next.content)) {
+        for (const b of next.content) {
+          if (b.type === "tool_result" && typeof b.tool_use_id === "string") {
+            nextResultIds.add(b.tool_use_id);
+          }
+        }
+      }
+
+      const validIds = new Set([...toolUseIds].filter((id) => nextResultIds.has(id)));
+      const filtered = m.content.filter((b) => {
+        if (b.type === "tool_use") return validIds.has(b.id);
+        return true;
+      });
+      if (filtered.length > 0) out.push({ role: m.role, content: filtered });
+      continue;
+    }
+
+    if (m.role === "user") {
+      const prev = out[out.length - 1];
+      const prevUseIds = new Set();
+      if (prev && prev.role === "assistant" && Array.isArray(prev.content)) {
+        for (const b of prev.content) {
+          if (b.type === "tool_use" && typeof b.id === "string") prevUseIds.add(b.id);
+        }
+      }
+
+      const filtered = m.content.filter((b) => {
+        if (b.type === "tool_result") return prevUseIds.has(b.tool_use_id);
+        return true;
+      });
+      if (filtered.length > 0) out.push({ role: m.role, content: filtered });
+      continue;
+    }
+
+    out.push(m);
+  }
+  return out;
 }
 
 /**