@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/bin/token-telemetry.js

@@ -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-audit.md

@@ -22,9 +22,9 @@ Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-au
 ```
 
 After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header if missing):
-`| {DT_START} | {DT_END} | gsd-t-audit | Step 0 | sonnet | {DURATION}s | audit: {args summary} | | | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-audit | Step 0 | sonnet | {DURATION}s | audit: {args summary} | | | {CTX_PCT} |`
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
 

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

@@ -2,6 +2,44 @@
 
 You are displaying the project backlog with optional filtering and limiting.
 
+## Step 0: Parse --file flag
+
+If `$ARGUMENTS` contains `--file {path}`, read from `.gsd-t/{path}` instead of the default `.gsd-t/backlog.md`. This enables listing alternate backlog files such as `.gsd-t/optimization-backlog.md` (produced by the token optimizer at complete-milestone):
+
+```
+/user:gsd-t-backlog-list --file optimization-backlog.md
+/user:gsd-t-backlog-list --file optimization-backlog.md --status pending
+```
+
+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:
+
+```bash
+node -e "
+const opt = require('./bin/token-optimizer.js');
+const entries = opt.parseBacklog(opt.readBacklog('.'));
+const statusFilter = process.argv[1] || '';
+const filtered = statusFilter
+  ? entries.filter(e => e.status === statusFilter)
+  : entries;
+if (filtered.length === 0) {
+  console.log('No recommendations' + (statusFilter ? ' with status=' + statusFilter : '') + '.');
+  process.exit(0);
+}
+console.log('# Optimization Backlog (' + filtered.length + ' entries' + (statusFilter ? ', status=' + statusFilter : '') + ')');
+console.log('');
+console.log('| ID | Type | Status | Evidence |');
+console.log('|---|---|---|---|');
+for (const e of filtered) {
+  const ev = (e.evidence || '').slice(0, 80);
+  console.log('| ' + e.id + ' | ' + (e.type || '') + ' | ' + (e.status || '') + ' | ' + ev + ' |');
+}
+" "$STATUS_FILTER"
+```
+
+Exit after rendering when `--file` is present — skip the default steps below.
+
 ## Step 1: Read Backlog
 
 Read `.gsd-t/backlog.md` and parse all entries.

package/commands/gsd-t-brainstorm.md

@@ -123,9 +123,9 @@ Do NOT proceed to Step 5 until this synthesis is complete.
 ```
 
 After team completes — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-brainstorm | Step 3 | sonnet | {DURATION}s | deep research: {topic summary} | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-brainstorm | Step 3 | sonnet | {DURATION}s | deep research: {topic summary} | {CTX_PCT} |`
 
 ## Step 4: Capture the Sparks
 

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

@@ -508,6 +508,30 @@ If `.gsd-t/roadmap.md` exists:
 - Update any dependent milestones
 - Highlight next recommended milestone
 
+## Step 14: Token Optimization Recommendations (non-blocking)
+
+After all quality gates pass and the milestone is archived, run the token optimizer to detect model-tier miscalibration signals from the milestone's telemetry. This appends recommendations to `.gsd-t/optimization-backlog.md`. **Never blocks, never prompts, never auto-applies.** Optimizer failure is caught and logged, not re-thrown.
+
+```bash
+node -e "
+try {
+  const opt = require('./bin/token-optimizer.js');
+  const recs = opt.detectRecommendations({projectDir: '.', lookbackMilestones: 3});
+  opt.appendToBacklog(recs, '.');
+  if (recs.length === 0) {
+    console.log('Token optimizer: no new recommendations.');
+  } else {
+    console.log('Token optimizer: ' + recs.length + ' new recommendation(s) → .gsd-t/optimization-backlog.md');
+    console.log('Review with: /user:gsd-t-backlog-list --file optimization-backlog.md');
+  }
+} catch (e) {
+  console.error('Token optimizer error (non-blocking): ' + e.message);
+}
+"
+```
+
+Contract: `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0
+
 ## Error Handling
 
 ### If verify failed:

package/commands/gsd-t-debug.md

@@ -2,7 +2,70 @@
 
 You are debugging an issue in a contract-driven project. Your approach should identify whether the bug is within a domain or at a contract boundary.
 
-## Step 0: Launch via Subagent
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `opus` (`selectModel({phase: "debug"})`) — debugging is high-stakes reasoning by default.
+- **Root-cause analysis**: `opus` (`selectModel({phase: "debug", task_type: "root_cause"})`).
+- **Fix-apply**: `sonnet` (`selectModel({phase: "debug", task_type: "fix_apply"})`) — applying a known fix is routine code work.
+- **Escalation**: already at opus for judgment work; `/advisor` fallback applies if a fix crosses a contract boundary or schema. Never silently downgrade the model under context pressure — M35 removed that behavior.
+
+## Per-Spawn Token Bracket (MANDATORY — wrap EVERY Task subagent spawn)
+
+Per `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0. Every Task subagent spawn below **MUST** be wrapped in this token bracket so `.gsd-t/token-metrics.jsonl` gets one record per spawn. This is additive — the existing OBSERVABILITY LOGGING blocks in each spawn site are preserved unmodified alongside this bracket.
+
+**Before each spawn — read starting context tokens:**
+
+```bash
+T0_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')}")
+T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+```
+
+**After each spawn — record the bracket:**
+
+```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.js');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
+```
+
+The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist.
+
+## Step 0: Runway Check (MANDATORY — before any other work in a fresh session)
+
+Debug uses conservative per-iteration cost (opus-default fallback = 8%/task). Run with `remaining_tasks=1` for a single pass; the mid-loop check (below, added by HAS-T3) re-runs this gate between iterations. Run via Bash:
+
+```bash
+node -e "
+const r = require('./bin/runway-estimator.js').estimateRunway({
+  command: 'gsd-t-debug',
+  domain_type: '',
+  remaining_tasks: 1,
+  projectDir: '.'
+});
+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({
+    command: 'gsd-t-debug', args: [], continue_from: '.'
+  });
+  console.log('Session ID: ' + s.id);
+  console.log('Status: tail ' + s.logPath);
+  console.log('');
+  console.log('Your interactive session remains idle — you can use it for other work.');
+  console.log('You will be notified when the headless run completes.');
+  process.exit(0);
+}
+"
+```
+
+If `can_start === false`, the headless continuation has been spawned and the interactive session must stop here. Do NOT proceed to Step 0.1.
+
+**Contract**: `.gsd-t/contracts/runway-estimator-contract.md` v1.0.0; stop threshold (85%) mirrors `.gsd-t/contracts/token-budget-contract.md` v3.0.0.
+
+## Step 0.1: Launch via Subagent
 
 To give this debug session a fresh context window and prevent compaction, always execute via a Task subagent.
 
@@ -84,8 +147,8 @@ Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-de
 
 After subagent returns — run via Bash:
 `T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-debug | Step 0 | sonnet | {DURATION}s | debug: {issue summary} | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-debug | Step 0 | sonnet | {DURATION}s | debug: {issue summary} | {CTX_PCT} |`
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
 
@@ -150,9 +213,9 @@ Lead: Wait for all three researchers to complete. Then synthesize:
 ```
 
 After team completes — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
 Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-debug | Step 1.5 | sonnet | {DURATION}s | deep research loop break: {issue summary} | {COUNTER} |`
+`| {DT_START} | {DT_END} | gsd-t-debug | Step 1.5 | sonnet | {DURATION}s | deep research loop break: {issue summary} | {CTX_PCT} |`
 
 **STOP. Present findings to the user before making any changes:**
 
@@ -282,6 +345,60 @@ When you encounter unexpected situations during the fix:
 
 If the debug-loop also fails (exit 1/4), log the attempt to `.gsd-t/progress.md` Decision Log with a `[failure]` prefix, return to Step 1.5 and run Deep Research Mode before any further attempts. Present findings and options to the user before proceeding.
 
+### Between-Iteration Runway Check (MANDATORY — every iteration)
+
+Before starting each new fix attempt (iteration N+1), re-run the runway estimator with `remaining_tasks=1`. Debug loops are the single highest-variance consumer of context, and a mid-loop halt is worse than a pre-flight halt — the user loses the current hypothesis and partial work unless we persist them first.
+
+Run via Bash before each iteration:
+
+```bash
+node -e "
+const r = require('./bin/runway-estimator.js').estimateRunway({
+  command: 'gsd-t-debug',
+  domain_type: '',
+  remaining_tasks: 1,
+  projectDir: '.'
+});
+if (!r.can_start) {
+  // ── HAS-T3 state persistence: capture current hypothesis + fix + test output ──
+  const fs = require('fs');
+  const path = require('path');
+  const ledgerPath = '.gsd-t/debug-ledger.jsonl';
+  const snapshot = {
+    type: 'runway-handoff-snapshot',
+    timestamp: new Date().toISOString(),
+    hypothesis: process.env.GSD_T_DEBUG_HYPOTHESIS || '',
+    last_fix_diff: process.env.GSD_T_DEBUG_LAST_FIX || '',
+    last_test_output: process.env.GSD_T_DEBUG_LAST_TEST_OUTPUT || '',
+    iteration_n_plus_1: Number(process.env.GSD_T_DEBUG_NEXT_ITERATION || 0),
+    current_pct: r.current_pct,
+    projected_end_pct: r.projected_end_pct,
+    confidence: r.confidence
+  };
+  try { fs.mkdirSync(path.dirname(ledgerPath), { recursive: true }); } catch (_) {}
+  fs.appendFileSync(ledgerPath, JSON.stringify(snapshot) + '\n');
+
+  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({
+    command: 'gsd-t-debug',
+    args: ['--resume', 'iteration-' + snapshot.iteration_n_plus_1],
+    continue_from: ledgerPath
+  });
+  console.log('Runway exceeded mid-loop — headless debug picking up at iteration ' + snapshot.iteration_n_plus_1 + '. Session: ' + s.id + '. Log: ' + s.logPath);
+  process.exit(0);
+}
+"
+```
+
+- On refusal: the block persists `{hypothesis, last_fix_diff, last_test_output}` as a `runway-handoff-snapshot` entry in `.gsd-t/debug-ledger.jsonl`, calls `autoSpawnHeadless` with `--resume iteration-N+1`, prints the handoff message, and exits the loop cleanly (no `/clear` prompt).
+- On proceed: the block exits silently and the next iteration begins.
+
+**Environment variables**: the calling iteration sets `GSD_T_DEBUG_HYPOTHESIS`, `GSD_T_DEBUG_LAST_FIX`, `GSD_T_DEBUG_LAST_TEST_OUTPUT`, `GSD_T_DEBUG_NEXT_ITERATION` before running the Bash block. If unset, empty strings are persisted (the ledger entry is still useful for the headless continuation).
+
+**Contracts**: `.gsd-t/contracts/runway-estimator-contract.md` v1.0.0, `.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0.
+
 ### Solo Mode
 1. Reproduce the issue — **reproduction script must exist before step 2** (see Step 2.5)
 2. Trace through the relevant domain(s)
@@ -389,10 +506,10 @@ Spawn Task subagent (general-purpose, model: opus):
 After subagent returns — run via Bash:
 ```
 T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-COUNTER=$(node bin/task-counter.cjs status 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(String(JSON.parse(s).count||''))}catch(_){process.stdout.write('')}})")
+CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")
 ```
 Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-debug | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {COUNTER} |`
+`| {DT_START} | {DT_END} | gsd-t-debug | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {CTX_PCT} |`
 
 **If FAIL:** fix CRITICAL/HIGH bugs (≤2 cycles) → re-run. Persistent bugs → `.gsd-t/deferred-items.md`.
 **If GRUDGING PASS:** proceed to metrics and doc-ripple.

package/commands/gsd-t-discuss.md

@@ -2,6 +2,13 @@
 
 You are the lead agent exploring design decisions before committing to a plan. The goal of this phase is to produce or refine **contracts** — not just recommendations.
 
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `opus` (`selectModel({phase: "discuss"})`) — design exploration benefits most from top-tier reasoning.
+- **Escalation**: already at opus; there is no stronger tier.
+
 ## IMPORTANT: Manual vs Auto-Invoked Behavior
 
 **When manually invoked** (user typed `/user:gsd-t-discuss`):
@@ -72,9 +79,9 @@ Lead: Synthesize into decisions and update contracts.
 ```
 
 After team completes — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-discuss | Step 3 | sonnet | {DURATION}s | team discuss: {topic summary} | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-discuss | Step 3 | sonnet | {DURATION}s | team discuss: {topic summary} | {CTX_PCT} |`
 
 Assign teammates based on the nature of the questions:
 - **Technical choice** (e.g., which database): one advocate per option + critic

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

@@ -2,6 +2,34 @@
 
 You are the doc-ripple agent. You identify and update all downstream documents after code changes. You are spawned by execute, integrate, quick, debug, and wave after primary work is committed.
 
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `sonnet` (`selectModel({phase: "doc-ripple"})`) — downstream documentation updates are routine prose editing.
+- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` when a doc change involves rewriting an architectural invariant or a contract. Never silently skip doc-ripple under context pressure — M35 removed that behavior.
+
+## Per-Spawn Token Bracket (MANDATORY — wrap EVERY Task subagent spawn)
+
+Per `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0. Every Task subagent spawn below **MUST** be wrapped in this token bracket so `.gsd-t/token-metrics.jsonl` gets one record per spawn. This is additive — the existing OBSERVABILITY LOGGING blocks in each spawn site are preserved unmodified alongside this bracket.
+
+**Before each spawn — read starting context tokens:**
+
+```bash
+T0_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')}")
+T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+```
+
+**After each spawn — record the bracket:**
+
+```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.js');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
+```
+
+The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist.
+
 ## Step 1: Load Context
 
 Read:
@@ -98,11 +126,11 @@ Before spawning — run via Bash:
 After subagent returns — run via Bash:
 `T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
 
-Read the task counter (deterministic context-burn signal):
-`COUNTER=$(node bin/task-counter.cjs status 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(String(JSON.parse(s).count||''))}catch(_){process.stdout.write('')}})")`
+Read the real context% from the Context Meter state file:
+`CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")`
 
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-doc-ripple | Step 5 | {model} | {DURATION}s | update:{document} | doc-ripple | — | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-doc-ripple | Step 5 | {model} | {DURATION}s | update:{document} | doc-ripple | — | {CTX_PCT} |`
 
 **Each document-update subagent prompt:**
 ```