@tekyzinc/gsd-t 2.74.12 → 2.76.10

package/bin/runway-estimator.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Runway Estimator — Pre-flight context runway projection
+ *
+ * Reads current context percentage from the M34 context meter state file and
+ * historical token-telemetry records (token-metrics.jsonl) to project whether
+ * a command about to run will complete before the v3.0.0 stop band (85%).
+ *
+ * Confidence-weighted: high ≥50 records, medium ≥10, low <10. Low confidence
+ * applies a 1.25x conservative skew. On missing history a constant fallback
+ * is used (4%/task sonnet-default, 8%/task opus-default). On refusal the
+ * estimator never prompts the user — callers hand off to headless-auto-spawn.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/runway-estimator-contract.md v1.0.0
+ * Consumers: bin/gsd-t.js, commands/gsd-t-execute|wave|integrate|quick|debug.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+// Mirrors token-budget-contract v3.0.0 — must stay in sync.
+const STOP_THRESHOLD_PCT = 85;
+
+// Confidence grading thresholds (frozen in runway-estimator-contract v1.0.0).
+const CONFIDENCE_HIGH_MIN = 50;
+const CONFIDENCE_MEDIUM_MIN = 10;
+
+// Conservative skew multiplier applied to low-confidence projections.
+const LOW_CONFIDENCE_SKEW = 1.25;
+
+// Conservative constant fallback when no history exists at all.
+const FALLBACK_PCT_PER_TASK_SONNET = 4;
+const FALLBACK_PCT_PER_TASK_OPUS = 8;
+
+// Opus-default phases — used when picking a constant fallback for a command
+// with no historical telemetry. Commands not listed default to sonnet.
+const OPUS_DEFAULT_COMMANDS = new Set([
+  "gsd-t-debug",
+  "gsd-t-integrate",
+]);
+
+const STATE_FILE_REL = path.join(".gsd-t", ".context-meter-state.json");
+const METRICS_FILE_REL = path.join(".gsd-t", "token-metrics.jsonl");
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  estimateRunway,
+  STOP_THRESHOLD_PCT,
+  CONFIDENCE_HIGH_MIN,
+  CONFIDENCE_MEDIUM_MIN,
+  LOW_CONFIDENCE_SKEW,
+};
+
+// ── estimateRunway ───────────────────────────────────────────────────────────
+
+/**
+ * @param {{
+ *   command: string,
+ *   domain_type?: string,
+ *   remaining_tasks: number,
+ *   projectDir?: string,
+ *   headlessAvailable?: boolean
+ * }} opts
+ * @returns {{
+ *   can_start: boolean,
+ *   current_pct: number,
+ *   projected_end_pct: number,
+ *   confidence: 'low'|'medium'|'high',
+ *   confidence_basis: number,
+ *   pct_per_task: number,
+ *   recommendation: 'proceed'|'headless'|'clear-and-resume',
+ *   reason: string
+ * }}
+ */
+function estimateRunway(opts) {
+  const command = opts.command;
+  const domain_type = opts.domain_type || "";
+  const remaining_tasks = Math.max(0, Number(opts.remaining_tasks) || 0);
+  const projectDir = opts.projectDir || process.cwd();
+  const headlessAvailable = opts.headlessAvailable !== false;
+
+  const current_pct = readCurrentPct(projectDir);
+  const records = readMetrics(projectDir);
+  const { pct_per_task, confidence, confidence_basis } = computePctPerTask(
+    records,
+    command,
+    domain_type,
+  );
+
+  const skew = confidence === "low" ? LOW_CONFIDENCE_SKEW : 1.0;
+  const projected_end_pct = round1(
+    current_pct + pct_per_task * remaining_tasks * skew,
+  );
+  const can_start = projected_end_pct < STOP_THRESHOLD_PCT;
+
+  let recommendation;
+  let reason;
+  if (can_start) {
+    recommendation = "proceed";
+    reason = `Projected end ${projected_end_pct}% < ${STOP_THRESHOLD_PCT}% stop threshold`;
+  } else if (headlessAvailable) {
+    recommendation = "headless";
+    reason = `Projected end ${projected_end_pct}% ≥ ${STOP_THRESHOLD_PCT}% — auto-spawn headless`;
+  } else {
+    recommendation = "clear-and-resume";
+    reason = `Projected end ${projected_end_pct}% ≥ ${STOP_THRESHOLD_PCT}% — headless unavailable, clear-and-resume`;
+  }
+
+  return {
+    can_start,
+    current_pct,
+    projected_end_pct,
+    confidence,
+    confidence_basis,
+    pct_per_task: round2(pct_per_task),
+    recommendation,
+    reason,
+  };
+}
+
+// ── Internal: read current pct from M34 state file ──────────────────────────
+
+function readCurrentPct(projectDir) {
+  try {
+    const fp = path.join(projectDir, STATE_FILE_REL);
+    const raw = fs.readFileSync(fp, "utf8");
+    const s = JSON.parse(raw);
+    if (typeof s.pct === "number" && Number.isFinite(s.pct)) {
+      return round1(s.pct);
+    }
+  } catch (_) {
+    // Missing or unreadable — warn and fall through.
+    try {
+      process.stderr.write(
+        `runway-estimator: ${STATE_FILE_REL} missing or unreadable — assuming current_pct=0\n`,
+      );
+    } catch (_) {
+      /* ignore */
+    }
+  }
+  return 0;
+}
+
+// ── Internal: read token-metrics.jsonl ──────────────────────────────────────
+
+function readMetrics(projectDir) {
+  try {
+    const fp = path.join(projectDir, METRICS_FILE_REL);
+    const raw = fs.readFileSync(fp, "utf8");
+    const out = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch (_) {
+        /* skip malformed */
+      }
+    }
+    return out;
+  } catch (_) {
+    return [];
+  }
+}
+
+// ── Internal: compute pct-per-task with confidence grading ──────────────────
+
+function computePctPerTask(records, command, domain_type) {
+  // Tier 1: {command, domain_type} pair — sharpest match.
+  if (domain_type) {
+    const pair = records.filter(
+      (r) => r.command === command && r.domain_type === domain_type,
+    );
+    if (pair.length >= CONFIDENCE_MEDIUM_MIN) {
+      return {
+        pct_per_task: meanPctDelta(pair),
+        confidence: gradeConfidence(pair.length),
+        confidence_basis: pair.length,
+      };
+    }
+  }
+
+  // Tier 2: {command} aggregate.
+  const cmd = records.filter((r) => r.command === command);
+  if (cmd.length >= CONFIDENCE_MEDIUM_MIN) {
+    return {
+      pct_per_task: meanPctDelta(cmd),
+      confidence: gradeConfidence(cmd.length),
+      confidence_basis: cmd.length,
+    };
+  }
+
+  // Tier 3: constant fallback — confidence=low, basis=cmd.length (0 or few).
+  return {
+    pct_per_task: fallbackPctPerTask(command),
+    confidence: "low",
+    confidence_basis: cmd.length,
+  };
+}
+
+function meanPctDelta(records) {
+  if (!records.length) return 0;
+  let sum = 0;
+  let n = 0;
+  for (const r of records) {
+    const before = Number(r.context_window_pct_before);
+    const after = Number(r.context_window_pct_after);
+    if (!Number.isFinite(before) || !Number.isFinite(after)) continue;
+    const delta = after - before;
+    if (delta < 0) continue; // pathological — treat as 0
+    sum += delta;
+    n += 1;
+  }
+  if (n === 0) return 0;
+  return sum / n;
+}
+
+function gradeConfidence(n) {
+  if (n >= CONFIDENCE_HIGH_MIN) return "high";
+  if (n >= CONFIDENCE_MEDIUM_MIN) return "medium";
+  return "low";
+}
+
+function fallbackPctPerTask(command) {
+  if (OPUS_DEFAULT_COMMANDS.has(command)) return FALLBACK_PCT_PER_TASK_OPUS;
+  return FALLBACK_PCT_PER_TASK_SONNET;
+}
+
+// ── Internal: rounding helpers ──────────────────────────────────────────────
+
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}

package/bin/token-budget.js

@@ -1,10 +1,22 @@
 #!/usr/bin/env node
 
 /**
- * GSD-T Token Budget — Session-level token tracking and graduated degradation
+ * GSD-T Token Budget — Session-level token tracking (three-band model)
  *
- * Reads .gsd-t/token-log.md for historical averages, tracks session usage,
- * and returns model override recommendations at degradation thresholds.
+ * Reads .gsd-t/.context-meter-state.json (M34) for real context-window
+ * readings, tracks session usage, and returns a three-band status signal
+ * (normal / warn / stop) that callers use to decide whether to proceed,
+ * log a warning, or halt cleanly.
+ *
+ * v3.0.0 (M35 — clean break from v2.0.0):
+ *   - The `downgrade` and `conserve` bands were REMOVED. Silent model
+ *     degradation and silent phase-skipping are anti-features — they
+ *     violate GSD-T's "quality is non-negotiable" principle.
+ *   - `getDegradationActions()` now returns `{band, pct, message}` instead
+ *     of `{threshold, actions, modelOverrides}`. No `modelOverride`, no
+ *     `skipPhases`, no `checkpoint` side-channel.
+ *   - `warn` threshold tightened from 60% → 70%. `stop` tightened from
+ *     95% → 85% — keeps us clear of the runtime's native ~95% compact.
  *
  * Zero external dependencies (Node.js built-ins only).
  */
@@ -28,11 +40,16 @@ const BASE_ESTIMATES = {
   default: 6000,
 };
 
+// v3.0.0 three-band thresholds. Lower-bound inclusive.
+//   pct <  70 → normal
+//   70 ≤ pct <  85 → warn (informational — log, proceed)
+//   pct ≥ 85 → stop  (halt cleanly, hand off to runway estimator)
+const WARN_THRESHOLD_PCT = 70;
+const STOP_THRESHOLD_PCT = 85;
+
 const THRESHOLDS = {
-  warn: 60,
-  downgrade: 70,
-  conserve: 85,
-  stop: 95,
+  warn: WARN_THRESHOLD_PCT,
+  stop: STOP_THRESHOLD_PCT,
 };
 
 // ── Exports ──────────────────────────────────────────────────────────────────
@@ -74,50 +91,57 @@ function estimateCost(model, taskType, options) {
 
 // ── getSessionStatus ─────────────────────────────────────────────────────────
 
+const STATE_FILE_REL = path.join(".gsd-t", ".context-meter-state.json");
+const STATE_STALE_MS = 5 * 60 * 1000;
+
 /**
  * @param {string} [projectDir]
  * @returns {{ consumed: number, estimated_remaining: number, pct: number, threshold: string }}
  *
- * v2.74.12: previously this read process.env.CLAUDE_CONTEXT_TOKENS_USED /
- * CLAUDE_CONTEXT_TOKENS_MAX, which Claude Code does not export — so consumed
- * was always 0 and threshold was always 'normal'. The graduated-degradation
- * machinery downstream was inert. Now we synthesise a percent from the real
- * task counter at .gsd-t/.task-counter, mapping 0..limit linearly to
- * 0..100%. This keeps the API stable so commands that ask for thresholds
- * (downgrade/conserve/stop) get a real signal.
+ * v2.0.0 (M34): reads `.gsd-t/.context-meter-state.json` produced by the
+ * Context Meter PostToolUse hook. When that file is fresh (timestamp within
+ * the last 5 minutes), real `input_tokens` drive the response. Otherwise we
+ * fall back to a historical heuristic from `.gsd-t/token-log.md`, preserving
+ * graceful degradation for projects without the hook installed.
  */
 function getSessionStatus(projectDir) {
   const dir = projectDir || process.cwd();
-  const counter = readTaskCounter(dir);
-  const limit = counter.limit > 0 ? counter.limit : 5;
-  const consumed = counter.count;
-  const pct = Math.min(100, Math.round((consumed / limit) * 100 * 10) / 10);
-  const threshold = resolveThreshold(pct);
-  const estimated_remaining = Math.max(0, limit - consumed);
-  return { consumed, estimated_remaining, pct, threshold };
+  const real = readContextMeterState(dir);
+  if (real) {
+    const consumed = real.inputTokens;
+    const window = real.modelWindowSize > 0 ? real.modelWindowSize : 200000;
+    const estimated_remaining = Math.max(0, window - consumed);
+    const pct = Math.round(real.pct * 10) / 10;
+    const threshold = resolveThreshold(pct);
+    return { consumed, estimated_remaining, pct, threshold };
+  }
+  return getSessionStatusHeuristic(dir);
 }
 
-function readTaskCounter(dir) {
+function readContextMeterState(dir) {
   try {
-    const fp = path.join(dir, ".gsd-t", ".task-counter");
+    const fp = path.join(dir, STATE_FILE_REL);
     const raw = fs.readFileSync(fp, "utf8");
     const s = JSON.parse(raw);
-    let limit = 5;
-    try {
-      const cfgRaw = fs.readFileSync(path.join(dir, ".gsd-t", "task-counter-config.json"), "utf8");
-      const cfg = JSON.parse(cfgRaw);
-      if (cfg && typeof cfg.limit === "number" && cfg.limit > 0) limit = cfg.limit;
-    } catch (_) {}
-    if (process.env.GSD_T_TASK_LIMIT) {
-      const n = parseInt(process.env.GSD_T_TASK_LIMIT, 10);
-      if (!isNaN(n) && n > 0) limit = n;
-    }
-    return { count: typeof s.count === "number" ? s.count : 0, limit };
+    if (!s || typeof s.inputTokens !== "number" || typeof s.pct !== "number") return null;
+    if (!s.timestamp) return null;
+    const age = Date.now() - Date.parse(s.timestamp);
+    if (isNaN(age) || age > STATE_STALE_MS || age < 0) return null;
+    return s;
   } catch (_) {
-    return { count: 0, limit: 5 };
+    return null;
   }
 }
 
+function getSessionStatusHeuristic(dir) {
+  const window = 200000;
+  const consumed = readSessionConsumed(dir);
+  const estimated_remaining = Math.max(0, window - consumed);
+  const pct = window > 0 ? Math.round((consumed / window) * 100 * 10) / 10 : 0;
+  const threshold = resolveThreshold(pct);
+  return { consumed, estimated_remaining, pct, threshold };
+}
+
 // ── recordUsage ──────────────────────────────────────────────────────────────
 
 /**
@@ -136,15 +160,20 @@ function recordUsage(usage) {
   fs.appendFileSync(fp, line);
 }
 
-// ── getDegradationActions ─────────────────────────────────────────────────────
+// ── getDegradationActions (v3.0.0 — three-band) ─────────────────────────────
 
 /**
+ * v3.0.0 three-band response. The name is preserved for caller-identification
+ * convenience; the return shape is a CLEAN BREAK from v2.0.0 — no
+ * `modelOverrides`, no `actions` list, no `skipPhases`, no `checkpoint`
+ * side-channel. Callers that relied on those fields MUST be updated.
+ *
  * @param {string} [projectDir]
- * @returns {{ threshold: string, actions: string[], modelOverrides: object }}
+ * @returns {{ band: 'normal'|'warn'|'stop', pct: number, message: string }}
  */
 function getDegradationActions(projectDir) {
-  const { threshold } = getSessionStatus(projectDir);
-  return buildDegradationResponse(threshold);
+  const { threshold, pct } = getSessionStatus(projectDir);
+  return buildBandResponse(threshold, pct);
 }
 
 // ── estimateMilestoneCost ─────────────────────────────────────────────────────
@@ -156,69 +185,47 @@ function getDegradationActions(projectDir) {
  */
 function estimateMilestoneCost(remainingTasks, projectDir) {
   const status = getSessionStatus(projectDir);
-  const limit = status.consumed + status.estimated_remaining || 5;
+  const window = status.consumed + status.estimated_remaining || 200000;
   const estimatedTokens = remainingTasks.reduce((sum, t) => {
     return sum + estimateCost(t.model, t.taskType, { complexity: t.complexity, projectDir });
   }, 0);
-  // Estimate task-equivalents needed for the remaining work: cost-weighted
-  // approximation against historical avg, capped at the configured task limit.
-  const taskEquivalents = remainingTasks.length;
-  const estimatedPct = limit > 0 ? Math.min(100, Math.round((taskEquivalents / limit) * 100 * 10) / 10) : 0;
-  const feasible = taskEquivalents <= status.estimated_remaining;
+  const estimatedPct = window > 0 ? Math.min(100, Math.round((estimatedTokens / window) * 100 * 10) / 10) : 0;
+  const feasible = estimatedTokens <= status.estimated_remaining;
   return { estimatedTokens, estimatedPct, feasible };
 }
 
-// ── Internal: threshold resolution ───────────────────────────────────────────
+// ── Internal: threshold resolution (v3.0.0 — three-band) ─────────────────────
 
 function resolveThreshold(pct) {
+  if (!Number.isFinite(pct)) return "normal";
   if (pct >= THRESHOLDS.stop) return "stop";
-  if (pct >= THRESHOLDS.conserve) return "conserve";
-  if (pct >= THRESHOLDS.downgrade) return "downgrade";
   if (pct >= THRESHOLDS.warn) return "warn";
   return "normal";
 }
 
-function buildDegradationResponse(threshold) {
-  const responses = {
-    normal: {
-      threshold: "normal",
-      actions: [],
-      modelOverrides: {},
-    },
-    warn: {
-      threshold: "warn",
-      actions: ["Display budget alert", "Reduce iteration budgets to minimum (2)"],
-      modelOverrides: {},
-    },
-    downgrade: {
-      threshold: "downgrade",
-      actions: ["Downgrade non-critical Sonnet to Haiku", "Skip exploratory testing", "Disable shadow-mode audit"],
-      modelOverrides: {
-        "sonnet:qa": "sonnet",
-        "sonnet:execute": "haiku",
-        "sonnet:doc-ripple": "skip",
-        "opus:red-team": "sonnet",
-        "haiku:*": "haiku",
-      },
-    },
-    conserve: {
-      threshold: "conserve",
-      actions: ["Pause doc-ripple", "Pause design brief generation", "Checkpoint all progress"],
-      modelOverrides: {
-        "sonnet:qa": "sonnet",
-        "sonnet:execute": "haiku",
-        "sonnet:doc-ripple": "skip",
-        "opus:red-team": "sonnet",
-        "haiku:*": "haiku",
-      },
-    },
-    stop: {
-      threshold: "stop",
-      actions: ["Hard stop", "Save all progress", "Display resume instruction"],
-      modelOverrides: {},
-    },
-  };
-  return responses[threshold] || responses.normal;
+function buildBandResponse(band, pct) {
+  const safePct = Number.isFinite(pct) ? pct : 0;
+  switch (band) {
+    case "warn":
+      return {
+        band: "warn",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — warn band (≥${WARN_THRESHOLD_PCT}%). Informational only; proceed.`,
+      };
+    case "stop":
+      return {
+        band: "stop",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — stop band (≥${STOP_THRESHOLD_PCT}%). Halt cleanly; hand off to runway estimator / headless auto-spawn.`,
+      };
+    case "normal":
+    default:
+      return {
+        band: "normal",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — normal band. Proceed.`,
+      };
+  }
 }
 
 // ── Internal: token-log parsing ───────────────────────────────────────────────