@tekyzinc/gsd-t 2.74.12 → 2.76.10

package/bin/headless-auto-spawn.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Headless Auto-Spawn — Detached headless continuation
+ *
+ * When the runway estimator refuses a run (projected context ≥ stop band),
+ * the caller invokes `autoSpawnHeadless()` to hand off to a detached child
+ * process running `gsd-t headless {command} --log`. The interactive session
+ * never blocks on the child (`child.unref()`), so the user retains their
+ * terminal and can work on unrelated tasks. On child completion, a macOS
+ * notification fires (T2). The interactive session surfaces the result via
+ * a read-back banner on the next `gsd-t-resume` or `gsd-t-status` call (T4).
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
+ * Consumers: commands/gsd-t-execute|wave|integrate|quick|debug.md (via runway
+ *            estimator handoff), bin/runway-estimator.js (conceptual target).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
+const LOG_DIR_REL = ".gsd-t"; // headless-{id}.log lives directly in .gsd-t
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  autoSpawnHeadless,
+  makeSessionId,
+  writeSessionFile,
+  writeContinueHereFile,
+  markSessionCompleted,
+};
+
+// ── autoSpawnHeadless ────────────────────────────────────────────────────────
+
+/**
+ * @param {{
+ *   command: string,
+ *   args?: string[],
+ *   continue_from?: string,
+ *   projectDir?: string,
+ *   context?: object
+ * }} opts
+ * @returns {{ id: string, pid: number, logPath: string, timestamp: string }}
+ */
+function autoSpawnHeadless(opts) {
+  const command = opts.command;
+  const args = opts.args || [];
+  const continue_from = opts.continue_from || ".";
+  const projectDir = opts.projectDir || process.cwd();
+  const context = opts.context || null;
+
+  if (!command || typeof command !== "string") {
+    throw new Error("autoSpawnHeadless: `command` is required");
+  }
+
+  const timestamp = new Date().toISOString();
+  const id = makeSessionId(command, new Date());
+  const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
+
+  ensureDir(path.join(projectDir, LOG_DIR_REL));
+  ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
+
+  // Open log file descriptor before spawning — child writes directly.
+  const logFd = fs.openSync(logPath, "a");
+
+  // Headless invocation: `node bin/gsd-t.js headless <command> [args] --log`
+  // The `gsd-t` CLI entry point is bin/gsd-t.js relative to projectDir.
+  const gsdtCli = path.join(projectDir, "bin", "gsd-t.js");
+  const childArgs = [gsdtCli, "headless", stripGsdtPrefix(command), ...args, "--log"];
+
+  const child = spawn("node", childArgs, {
+    cwd: projectDir,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: process.env,
+  });
+
+  child.unref();
+  fs.closeSync(logFd);
+
+  const pid = child.pid || 0;
+
+  writeSessionFile(projectDir, {
+    id,
+    pid,
+    logPath: path.relative(projectDir, logPath),
+    startTimestamp: timestamp,
+    command,
+    args,
+    status: "running",
+    continueFromPath: continue_from,
+    surfaced: false,
+  });
+
+  writeContinueHereFile(projectDir, id, context);
+
+  // T2 — install completion watcher. Non-blocking (setImmediate) so the
+  // caller's return is not delayed. The watcher uses `child.on('exit')` on
+  // a separately-spawned bridge process; here we defer to fs.watchFile for
+  // a detached approach that survives even after the parent's `unref()`.
+  installCompletionWatcher({ projectDir, id, logPath, pid, startTimestamp: timestamp });
+
+  return { id, pid, logPath: path.relative(projectDir, logPath), timestamp };
+}
+
+// ── makeSessionId ────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} command
+ * @param {Date} [now]
+ * @returns {string} e.g., "gsd-t-execute-2026-04-15-01-23-45"
+ */
+function makeSessionId(command, now) {
+  const d = now || new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+  const time = `${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
+  const base = stripGsdtPrefix(command) || command;
+  return `gsd-t-${base}-${date}-${time}`;
+}
+
+// ── writeSessionFile ─────────────────────────────────────────────────────────
+
+function writeSessionFile(projectDir, session) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${session.id}.json`);
+  ensureDir(path.dirname(fp));
+  fs.writeFileSync(fp, JSON.stringify(session, null, 2) + "\n");
+  return fp;
+}
+
+// ── writeContinueHereFile ────────────────────────────────────────────────────
+
+function writeContinueHereFile(projectDir, id, context) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}-context.json`);
+  const payload = context || buildContextSnapshot(projectDir);
+  fs.writeFileSync(fp, JSON.stringify(payload, null, 2) + "\n");
+  return fp;
+}
+
+function buildContextSnapshot(projectDir) {
+  // Best-effort snapshot of current GSD-T state at handoff time.
+  const snap = {
+    capturedAt: new Date().toISOString(),
+    progress: null,
+    currentDomain: null,
+    pendingTasks: [],
+    lastDecisionLogEntry: null,
+    currentWave: null,
+  };
+  try {
+    const progressFp = path.join(projectDir, ".gsd-t", "progress.md");
+    if (fs.existsSync(progressFp)) {
+      const raw = fs.readFileSync(progressFp, "utf8");
+      snap.progress = firstNLines(raw, 20);
+      // Pull the last Decision Log entry (last non-empty bullet line).
+      const lines = raw.split("\n");
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const ln = lines[i].trim();
+        if (ln.startsWith("- ")) {
+          snap.lastDecisionLogEntry = ln;
+          break;
+        }
+      }
+    }
+  } catch (_) {
+    /* best-effort */
+  }
+  return snap;
+}
+
+function firstNLines(s, n) {
+  return s.split("\n").slice(0, n).join("\n");
+}
+
+// ── markSessionCompleted ─────────────────────────────────────────────────────
+
+/**
+ * T2 completion hook — updates the session file in place.
+ * @param {string} projectDir
+ * @param {string} id
+ * @param {{ exitCode: number, endTimestamp?: string }} result
+ */
+function markSessionCompleted(projectDir, id, result) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}.json`);
+  if (!fs.existsSync(fp)) return;
+  try {
+    const s = JSON.parse(fs.readFileSync(fp, "utf8"));
+    s.status = "completed";
+    s.exitCode = result.exitCode;
+    s.endTimestamp = result.endTimestamp || new Date().toISOString();
+    fs.writeFileSync(fp, JSON.stringify(s, null, 2) + "\n");
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+// ── Completion watcher (T2) — macOS notification on exit ─────────────────────
+
+function installCompletionWatcher(opts) {
+  const { projectDir, id, pid, startTimestamp } = opts;
+  if (!pid || pid <= 0) return;
+
+  // Poll-based watcher. We can't hold a reference to the child (it's unref'd
+  // and detached), so we poll `process.kill(pid, 0)` which throws if the
+  // process is gone. This is cheap and survives across detachment.
+  const POLL_MS = 2000;
+  const MAX_WAIT_MS = 60 * 60 * 1000; // 1 hour safety cap
+  const startMs = Date.now();
+
+  const timer = setInterval(() => {
+    let alive = false;
+    try {
+      process.kill(pid, 0);
+      alive = true;
+    } catch (_) {
+      alive = false;
+    }
+    if (!alive) {
+      clearInterval(timer);
+      // Exit code is unknown from a signal-based probe. Best-effort: read
+      // the log's last lines to guess, otherwise default to 0.
+      const exitCode = guessExitCodeFromLog(projectDir, id);
+      markSessionCompleted(projectDir, id, {
+        exitCode,
+        endTimestamp: new Date().toISOString(),
+      });
+      fireMacNotification({ id, command: extractCommand(id), startTimestamp });
+    } else if (Date.now() - startMs > MAX_WAIT_MS) {
+      clearInterval(timer);
+    }
+  }, POLL_MS);
+
+  // Let the timer not block the parent's exit.
+  if (typeof timer.unref === "function") timer.unref();
+}
+
+function guessExitCodeFromLog(projectDir, id) {
+  try {
+    const fp = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
+    if (!fs.existsSync(fp)) return 0;
+    const raw = fs.readFileSync(fp, "utf8");
+    if (/exit code[: ]+(\d+)/i.test(raw)) {
+      const m = raw.match(/exit code[: ]+(\d+)/i);
+      return parseInt(m[1], 10);
+    }
+    return 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
+function extractCommand(id) {
+  // id format: gsd-t-{command}-{date}-{time}
+  const m = id.match(/^gsd-t-(.+?)-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}$/);
+  return m ? m[1] : id;
+}
+
+function fireMacNotification({ id, command }) {
+  if (process.platform !== "darwin") return;
+  try {
+    const { spawn } = require("child_process");
+    const msg = `GSD-T headless run complete: ${id}`;
+    const script = `display notification "${msg}" with title "GSD-T" subtitle "${command}"`;
+    const child = spawn("osascript", ["-e", script], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch (_) {
+    /* graceful degradation */
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+function stripGsdtPrefix(command) {
+  if (typeof command !== "string") return "";
+  return command.replace(/^gsd-t-/, "");
+}

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