@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/bin/model-selector.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Model Selector — surgical per-phase model tier assignment
+ *
+ * Replaces the v2.x "silent downgrade under context pressure" behavior with
+ * declarative per-phase tier assignments. Callers ask `selectModel({phase, ...})`
+ * and get back `{model, reason, escalation_hook}` — the tier decision is
+ * deterministic, driven by the rules table below, and does NOT depend on
+ * session context percentage.
+ *
+ * Contract: .gsd-t/contracts/model-selection-contract.md v1.0.0 (M35 T4)
+ * Findings: .gsd-t/M35-advisor-findings.md (convention-based /advisor fallback)
+ *
+ * Zero external dependencies.
+ */
+
+// ── Tiers ───────────────────────────────────────────────────────────────────
+
+const TIERS = Object.freeze({
+  HAIKU: "haiku",
+  SONNET: "sonnet",
+  OPUS: "opus",
+});
+
+const DEFAULT_TIER = TIERS.SONNET;
+
+// ── Escalation hook block (convention-based /advisor fallback) ──────────────
+//
+// Per `.gsd-t/M35-advisor-findings.md`, Claude Code's native /advisor has no
+// programmable API at subagent scope. This block is injected into the subagent
+// prompt at declared escalation points on sonnet-tier phases where the
+// orchestrator has flagged a high-stakes sub-decision.
+//
+// Kept as a constant so all consumers (command files, advisor-integration.js,
+// M35-advisor-findings.md) reference the same canonical text.
+
+const ESCALATION_HOOK = [
+  "## Escalation Hook — /advisor convention-based fallback",
+  "",
+  "Before finalizing your answer for this phase, stop and consider:",
+  "1. Is this decision high-stakes? (architecture, contract design, security boundary,",
+  "   data-loss risk, cross-module refactor, adversarial QA verdict)",
+  "2. Would a more capable model produce a materially better answer?",
+  "3. Are you confident in the assumptions you're making?",
+  "",
+  "If YES to any of the above, do ONE of the following:",
+  "- Escalate internally: spend an extra reasoning pass re-examining the decision",
+  "  from first principles. Document the re-examination in your output.",
+  "- Spawn a nested opus subagent: use the Task tool with",
+  "  `subagent_type: \"general-purpose\"` and include `model: opus` in the spawn.",
+  "",
+  "Record in your output whether you escalated: set `ESCALATED_VIA_ADVISOR=true` or",
+  "`ESCALATED_VIA_ADVISOR=false` on a line by itself near the end of your report.",
+].join("\n");
+
+// ── Declarative phase rules table ───────────────────────────────────────────
+//
+// Each rule maps (phase, task_type) → tier. The first matching rule wins.
+// `task_type` is optional — when absent, the rule matches any task within
+// that phase. Order the rules from most-specific to least-specific.
+//
+// Tier assignments mirror `.gsd-t/M35-definition.md` Part B and the Model
+// Assignments section of the GSD-T global CLAUDE template:
+//   - haiku:  strictly mechanical — test runners, branch guards, file checks,
+//             JSON validation, no judgment
+//   - sonnet: routine code work — execute step 2, test-sync, doc-ripple wiring,
+//             quick fixes, integration wiring, debug fix-apply
+//   - opus:   high-stakes reasoning — partition, discuss, Red Team, verify
+//             judgment, debug root-cause, contract/architecture design
+
+const PHASE_RULES = Object.freeze([
+  // Phase: execute
+  { phase: "execute", task_type: "test_runner",    model: TIERS.HAIKU,  reason: "Mechanical test-suite runner — zero judgment" },
+  { phase: "execute", task_type: "branch_guard",   model: TIERS.HAIKU,  reason: "Mechanical branch-name check — zero judgment" },
+  { phase: "execute", task_type: "file_check",     model: TIERS.HAIKU,  reason: "Mechanical file-existence check — zero judgment" },
+  { phase: "execute", task_type: "qa",             model: TIERS.SONNET, reason: "QA evaluation needs judgment per M31 tier refinement" },
+  { phase: "execute", task_type: "red_team",       model: TIERS.OPUS,   reason: "Adversarial QA benefits most from top tier" },
+  { phase: "execute",                              model: TIERS.SONNET, reason: "Routine task execution — sonnet is the M35 default for routine work", hasEscalation: true },
+
+  // Phase: wave (the wave orchestrator itself)
+  { phase: "wave",                                 model: TIERS.SONNET, reason: "Wave orchestration dispatches per-phase subagents; the orchestrator itself is routine coordination", hasEscalation: true },
+
+  // Phase: quick
+  { phase: "quick", task_type: "test_runner",      model: TIERS.HAIKU,  reason: "Mechanical test-suite runner — zero judgment" },
+  { phase: "quick",                                model: TIERS.SONNET, reason: "Routine one-off task — sonnet default" },
+
+  // Phase: integrate
+  { phase: "integrate", task_type: "test_runner",  model: TIERS.HAIKU,  reason: "Mechanical integration test runner — zero judgment" },
+  { phase: "integrate",                            model: TIERS.SONNET, reason: "Integration wiring is routine coordination work" },
+
+  // Phase: debug
+  { phase: "debug", task_type: "fix_apply",        model: TIERS.SONNET, reason: "Applying a known fix is routine code work" },
+  { phase: "debug", task_type: "root_cause",       model: TIERS.OPUS,   reason: "Root-cause analysis is high-stakes reasoning" },
+  { phase: "debug",                                model: TIERS.OPUS,   reason: "Debug default is high-stakes — prefer opus unless the task_type says otherwise" },
+
+  // Phase: partition — high-stakes architectural decomposition
+  { phase: "partition",                            model: TIERS.OPUS,   reason: "Domain partitioning is architectural reasoning — high stakes" },
+
+  // Phase: discuss — multi-perspective design exploration
+  { phase: "discuss",                              model: TIERS.OPUS,   reason: "Design exploration benefits from top-tier reasoning" },
+
+  // Phase: plan — task-list authoring
+  { phase: "plan",                                 model: TIERS.SONNET, reason: "Task decomposition is structured work — sonnet with escalation hook", hasEscalation: true },
+
+  // Phase: verify — final quality judgment before milestone complete
+  { phase: "verify",                               model: TIERS.OPUS,   reason: "Milestone verification is the final quality gate — high stakes" },
+
+  // Phase: test-sync — keeping tests aligned with code
+  { phase: "test-sync",                            model: TIERS.SONNET, reason: "Test alignment is routine refactoring work" },
+
+  // Phase: doc-ripple — downstream document updates
+  { phase: "doc-ripple",                           model: TIERS.SONNET, reason: "Documentation updates are routine prose editing" },
+
+  // Phase: red_team — explicit adversarial QA phase (separate from execute task_type)
+  { phase: "red_team",                             model: TIERS.OPUS,   reason: "Adversarial QA — always opus, the incentive is to find bugs" },
+
+  // Phase: qa — explicit standalone QA phase
+  { phase: "qa",                                   model: TIERS.SONNET, reason: "QA per M31 refinement — sonnet produces fewer false negatives than haiku" },
+]);
+
+// Complexity-signal overrides. If the caller provides `complexity_signals`,
+// these can bump a sonnet decision to opus regardless of phase rule.
+const COMPLEXITY_OVERRIDES = Object.freeze({
+  cross_module_refactor: TIERS.OPUS,
+  security_boundary:     TIERS.OPUS,
+  data_loss_risk:        TIERS.OPUS,
+  contract_design:       TIERS.OPUS,
+});
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Select the model tier for a subagent spawn.
+ *
+ * @param {object} args
+ * @param {string} args.phase           — required; one of the phase names above
+ * @param {string} [args.task_type]     — optional task_type for finer-grained rules
+ * @param {string} [args.domain_type]   — optional, currently unused (reserved for future per-domain rules)
+ * @param {object} [args.complexity_signals] — optional object, keys matching COMPLEXITY_OVERRIDES escalate sonnet→opus
+ * @returns {{model: string, reason: string, escalation_hook: string|null}}
+ */
+function selectModel(args) {
+  if (!args || typeof args !== "object") {
+    return {
+      model: DEFAULT_TIER,
+      reason: "No args provided — default to routine tier (sonnet)",
+      escalation_hook: null,
+    };
+  }
+
+  const { phase, task_type, complexity_signals } = args;
+
+  if (!phase || typeof phase !== "string") {
+    return {
+      model: DEFAULT_TIER,
+      reason: "No phase provided — default to routine tier (sonnet)",
+      escalation_hook: null,
+    };
+  }
+
+  // First pass: find the most-specific matching rule.
+  let matched = null;
+  for (const rule of PHASE_RULES) {
+    if (rule.phase !== phase) continue;
+    if (rule.task_type && rule.task_type !== task_type) continue;
+    matched = rule;
+    break;
+  }
+
+  if (!matched) {
+    return {
+      model: DEFAULT_TIER,
+      reason: `Unknown phase "${phase}" — fallback to routine tier (sonnet)`,
+      escalation_hook: null,
+    };
+  }
+
+  let model = matched.model;
+  let reason = matched.reason;
+
+  // Complexity-signal overrides: bump sonnet → opus if any flagged signal is truthy.
+  if (model === TIERS.SONNET && complexity_signals && typeof complexity_signals === "object") {
+    for (const key of Object.keys(complexity_signals)) {
+      if (!complexity_signals[key]) continue;
+      const override = COMPLEXITY_OVERRIDES[key];
+      if (override && override !== model) {
+        model = override;
+        reason = `${reason} (escalated to ${override} by complexity signal: ${key})`;
+        break;
+      }
+    }
+  }
+
+  // Escalation hook is only injected on sonnet phases flagged as high-stakes-adjacent.
+  // Haiku phases have no hook (mechanical, no judgment). Opus phases have no hook
+  // (already at top tier — nowhere to escalate).
+  let escalation_hook = null;
+  if (model === TIERS.SONNET && matched.hasEscalation) {
+    escalation_hook = ESCALATION_HOOK;
+  }
+
+  return { model, reason, escalation_hook };
+}
+
+/**
+ * Return the canonical list of phase names the selector knows about.
+ * Used by tests and documentation tooling to assert coverage.
+ */
+function listPhases() {
+  const seen = new Set();
+  for (const rule of PHASE_RULES) seen.add(rule.phase);
+  return [...seen].sort();
+}
+
+module.exports = {
+  selectModel,
+  listPhases,
+  TIERS,
+  DEFAULT_TIER,
+  ESCALATION_HOOK,
+  PHASE_RULES,
+  COMPLEXITY_OVERRIDES,
+};

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;
+}