@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/scripts/hooks/gsd-t-in-session-usage-hook.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * GSD-T In-Session Usage Hook (M43 D1-T2)
+ *
+ * Installed into `~/.claude/settings.json` (Stop + SessionEnd) to capture
+ * per-turn token usage for the dialog channel. Reads the hook payload from
+ * stdin, resolves the project directory from `payload.cwd`, then delegates to
+ * `bin/gsd-t-in-session-usage.cjs::processHookPayload` which reads the
+ * transcript at `payload.transcript_path` and appends schema-v2 rows to
+ * `.gsd-t/metrics/token-usage.jsonl`.
+ *
+ * Silent on success (hooks run async in Claude Code — stdout is ignored).
+ * Swallows every error: a flaky capture must never break the user's session.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_SCRIPT_GUARD_MS = 5000;
+const started = Date.now();
+
+function _readStdin() {
+  return new Promise((resolve) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { buf += chunk; });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', () => resolve(buf));
+    setTimeout(() => resolve(buf), DEFAULT_SCRIPT_GUARD_MS).unref();
+  });
+}
+
+function _parsePayload(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch (_) {
+    return null;
+  }
+}
+
+function _resolveProjectDir(payload) {
+  if (payload && payload.cwd && fs.existsSync(payload.cwd)) return payload.cwd;
+  if (process.cwd) return process.cwd();
+  return '.';
+}
+
+function _resolveInSessionModule(projectDir) {
+  const candidates = [
+    path.join(projectDir, 'bin', 'gsd-t-in-session-usage.cjs'),
+    path.join(process.env.HOME || '', '.claude', 'gsd-t', 'bin', 'gsd-t-in-session-usage.cjs'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+async function main() {
+  try {
+    const raw = await _readStdin();
+    const payload = _parsePayload(raw);
+    if (!payload) return;
+    if (payload.hook_event_name !== 'Stop' && payload.hook_event_name !== 'SessionEnd') return;
+
+    const projectDir = _resolveProjectDir(payload);
+    const modulePath = _resolveInSessionModule(projectDir);
+    if (!modulePath) return;
+
+    const mod = require(modulePath);
+    mod.processHookPayload({ projectDir, payload });
+  } catch (_) {
+    // Intentionally swallow — hook must never interrupt the user session.
+  } finally {
+    const elapsed = Date.now() - started;
+    if (elapsed > DEFAULT_SCRIPT_GUARD_MS) process.exitCode = 0;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { _internal: { _parsePayload, _resolveProjectDir } };

package/scripts/spawn-plan-fmt-tokens.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * GSD-T Spawn Plan — token formatting + cumulative totals (M44 D8 T7)
+ *
+ * Pure helper module used by the transcript right-side spawn-plan panel.
+ * Extracted from the inline script in `scripts/gsd-t-transcript.html` so the
+ * same functions can be unit-tested under Node without loading a DOM.
+ *
+ * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
+ *   - Token cell format: `in=12.5k out=1.7k $0.42` (k-suffix above 1000,
+ *     2-decimal USD). Returns `—` when tokens are null/missing.
+ *   - Cumulative totals: sum `{in,out,cr,cc,cost_usd}` across done tasks.
+ *     Returns `null` when no done-task has tokens (panel renders `—`).
+ *
+ * Zero external deps. `.cjs` so it loads in both ESM-default and CJS projects.
+ */
+
+/**
+ * k-suffix number formatter. `1500` → `1.5k`, `999` → `999`, `null` → `0`.
+ * Used by `fmtTokens` to compact large counts.
+ *
+ * @param {number|string|null|undefined} n
+ * @returns {string}
+ */
+function fmtK(n) {
+  if (n == null || Number.isNaN(Number(n))) return '0';
+  const num = Number(n);
+  if (Math.abs(num) >= 1000) return (num / 1000).toFixed(1) + 'k';
+  return String(num);
+}
+
+/**
+ * Render a token-cell string from a `{in, out, cr, cc, cost_usd}` object.
+ * When `tokens` is null/undefined/non-object, returns the em-dash marker
+ * per the "zero is a measurement, dash is acknowledged gap" rule.
+ *
+ * @param {object|null|undefined} tokens
+ * @returns {string}
+ */
+function fmtTokens(tokens) {
+  if (!tokens || typeof tokens !== 'object') return '—';
+  const ins = fmtK(tokens.in);
+  const out = fmtK(tokens.out);
+  const cost = (typeof tokens.cost_usd === 'number')
+    ? '$' + tokens.cost_usd.toFixed(2)
+    : '';
+  return ['in=' + ins, 'out=' + out, cost].filter(Boolean).join(' ');
+}
+
+/**
+ * Sum the `tokens` field across every task whose `status === 'done'` and
+ * whose `tokens` is a populated object. Returns null when no done-task has
+ * a tokens object attached — the panel renders that state as `—`.
+ *
+ * @param {Array<{status?:string, tokens?:object}>|null|undefined} tasks
+ * @returns {{in:number,out:number,cr:number,cc:number,cost_usd:number}|null}
+ */
+function sumTokens(tasks) {
+  const acc = { in: 0, out: 0, cr: 0, cc: 0, cost_usd: 0 };
+  let hit = false;
+  for (const t of (tasks || [])) {
+    if (!t || t.status !== 'done' || !t.tokens) continue;
+    acc.in += Number(t.tokens.in || 0);
+    acc.out += Number(t.tokens.out || 0);
+    acc.cr += Number(t.tokens.cr || 0);
+    acc.cc += Number(t.tokens.cc || 0);
+    acc.cost_usd += Number(t.tokens.cost_usd || 0);
+    hit = true;
+  }
+  if (!hit) return null;
+  acc.cost_usd = Math.round(acc.cost_usd * 100) / 100;
+  return acc;
+}
+
+module.exports = {
+  fmtK,
+  fmtTokens,
+  sumTokens,
+};

package/templates/CLAUDE-global.md

@@ -322,10 +322,15 @@ No command file ships a bare `Task(...)` or `claude -p` line outside of a wrappe
 
 Rationale: the pre-M41 convention silently wrote `N/A` tokens because no caller parsed the `usage` envelope. The wrapper is the single place that parses it. Bypassing the wrapper re-introduces blind spots.
 
-## Headless-by-Default Spawn (M38, v3.12.10+)
+## Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation
 
-Long-running work (execute, wave, integrate, debug repair loops) spawns detached by default. Interactive session shows a banner, event-stream path, then exits — no mid-session `/compact` wall. `--watch` keeps a ScheduleWakeup-driven status block in the caller; events stream JSONL to `.gsd-t/events/YYYY-MM-DD.jsonl`. Router mode (`/gsd`) answers exploratory requests inline without a command spawn — see `commands/gsd.md` Step 2.5.
-Contract: `.gsd-t/contracts/headless-default-contract.md` (see also `unattended-event-stream-contract.md`, `unattended-supervisor-contract.md`).
+Every GSD-T command spawns detached, unconditionally. There is no `--watch`, no `--in-session`, no `--headless` opt-in, no context-meter threshold that reroutes, no low-water-mark bypass. The dialog channel is reserved for human↔Claude conversation; everything else is a detached headless child. Interactive session shows a launch banner + live-transcript URL + event-stream path, then exits. Results surface via the read-back banner on the user's next message.
+
+The only in-session surface is the `/gsd` router (`commands/gsd.md`), and only for dialog-only exploratory turns. The moment Step 2.5 classifies a turn as `workflow`, the router hands off to a detached spawn.
+
+Legacy `watch` / `inSession` params are accepted-and-ignored with a one-shot stderr deprecation warning (scheduled removal in v3.0.0 of the contract). `shouldSpawnHeadless` is a constant `() => true`.
+
+Contract: `.gsd-t/contracts/headless-default-contract.md` v2.0.0 (see also `unattended-event-stream-contract.md`, `unattended-supervisor-contract.md`).
 
 ## API Documentation Guard (Swagger/OpenAPI)
 

package/templates/CLAUDE-project.md

@@ -26,24 +26,27 @@
 <!-- Claude will verify the branch before every commit. -->
 **Expected branch**: {main | master | feature-branch-name}
 
-## Context Meter (M34/M38, v3.12.10+)
+## Context Meter (M34/M38/M43 D4, v3.16.x+) — Observational Only
 <!-- The Context Meter is a PostToolUse hook that uses local token estimation -->
 <!-- and writes the current context % to .gsd-t/.context-meter-state.json. -->
-<!-- bin/token-budget.cjs reads that file as the spawn-time routing signal. -->
-<!-- Single-band model (context-meter-contract v1.3.0): one threshold (default 85%), -->
-<!-- one action — hand off to a detached headless spawn via the unattended supervisor. -->
-<!-- No three-band routing, no silent model downgrades. The meter informs spawn-time -->
-<!-- decisions, not in-flight pauses. -->
-<!-- Config: .gsd-t/context-meter-config.json — modelWindowSize, thresholdPct, checkFrequency. -->
+<!-- Under M43 D4 (channel-separation inversion) the meter is OBSERVATIONAL ONLY: -->
+<!-- the pct is recorded into the token-log Ctx% column on the next spawn, -->
+<!-- but no threshold gates any routing decision. Every command spawns detached -->
+<!-- unconditionally (see Always-Headless section below). -->
+<!-- Config: .gsd-t/context-meter-config.json — modelWindowSize, checkFrequency. -->
 <!-- Verify: `npx @tekyzinc/gsd-t doctor`. -->
 
-## Headless-by-Default Spawn (M38, v3.12.10+)
-<!-- Long-running workflow commands (execute, wave, integrate, debug repair loops) -->
-<!-- route through the unattended supervisor from the start. Interactive session -->
-<!-- invokes, sees a launch banner and event-stream log location, and exits. -->
-<!-- Pass --watch to keep a live status block in the session (270s ScheduleWakeup ticks). -->
-<!-- Event stream: .gsd-t/events/YYYY-MM-DD.jsonl (JSONL, phase boundaries). -->
-<!-- Contracts: headless-default-contract.md v1.0.0, unattended-event-stream-contract.md v1.0.0, -->
+## Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation
+<!-- Every GSD-T command spawns detached, unconditionally. No --watch flag. -->
+<!-- No --in-session flag. No --headless opt-in. No context-meter threshold -->
+<!-- that reroutes. The dialog channel is reserved for human↔Claude conversation; -->
+<!-- every workflow turn is a detached headless child. Interactive session shows -->
+<!-- a launch banner + live-transcript URL + event-stream path, then exits. -->
+<!-- Results surface via the read-back banner on the user's next message. -->
+<!-- The only in-session surface is the /gsd router, and only for dialog-only -->
+<!-- exploratory turns (Step 2.5 classifier → `conversational`). -->
+<!-- Legacy watch/inSession params on autoSpawnHeadless() are accepted-and-ignored. -->
+<!-- Contracts: headless-default-contract.md v2.0.0, unattended-event-stream-contract.md v1.0.0, -->
 <!-- unattended-supervisor-contract.md v1.1.0. -->
 
 ## Model Selection

package/templates/hooks/post-commit-spawn-plan.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# GSD-T Post-Commit Spawn-Plan Hook — installed by `gsd-t init`
+#
+# This is a thin shim that delegates to the canonical hook script
+# shipped with GSD-T. If your project doesn't yet have the canonical
+# script, this template copy handles commits by itself; once the
+# framework script is in place, the framework wins.
+#
+# Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
+
+set +e  # silent-fail — never break the commit
+
+PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$PROJECT_DIR" ] || [ ! -d "$PROJECT_DIR/.gsd-t/spawns" ]; then
+  exit 0
+fi
+
+CANONICAL="$PROJECT_DIR/scripts/gsd-t-post-commit-spawn-plan.sh"
+if [ -x "$CANONICAL" ]; then
+  # Delegate to the framework-shipped hook.
+  "$CANONICAL"
+  exit 0
+fi
+
+UPDATER="$PROJECT_DIR/bin/spawn-plan-status-updater.cjs"
+if [ ! -f "$UPDATER" ]; then
+  exit 0
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "[spawn-plan-hook] node not found — skipping" 1>&2
+  exit 0
+fi
+
+COMMIT_SHA="$(git rev-parse --short HEAD 2>/dev/null)"
+COMMIT_MSG="$(git log -1 --format=%B 2>/dev/null)"
+if [ -z "$COMMIT_SHA" ] || [ -z "$COMMIT_MSG" ]; then
+  exit 0
+fi
+
+TASK_IDS="$(printf '%s' "$COMMIT_MSG" | grep -oE '\[M[0-9]+-D[0-9]+-T[0-9]+\]' | sed 's/[][]//g' | awk '!seen[$0]++')"
+if [ -z "$TASK_IDS" ]; then
+  exit 0
+fi
+
+printf '%s\n' "$TASK_IDS" | node -e '
+"use strict";
+try {
+  const path = require("path");
+  const fs = require("fs");
+  const projectDir = process.argv[1];
+  const commit = process.argv[2];
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { raw += c; });
+  process.stdin.on("end", () => {
+    try {
+      const taskIds = raw.split("\n").map((s) => s.trim()).filter(Boolean);
+      if (!taskIds.length) process.exit(0);
+      const updater = require(path.join(projectDir, "bin", "spawn-plan-status-updater.cjs"));
+      const activePaths = updater.listActivePlans(projectDir);
+      if (!activePaths.length) process.exit(0);
+      for (const fp of activePaths) {
+        let plan;
+        try { plan = JSON.parse(fs.readFileSync(fp, "utf8")); } catch (_) { continue; }
+        const spawnId = plan && plan.spawnId;
+        const spawnStartedAt = plan && plan.startedAt;
+        if (!spawnId) continue;
+        const planTaskIds = new Set((plan.tasks || []).map((t) => t && t.id).filter(Boolean));
+        for (const taskId of taskIds) {
+          if (!planTaskIds.has(taskId)) continue;
+          const tokens = updater.sumTokensForTask({ projectDir, taskId, spawnStartedAt });
+          updater.markTaskDone({ spawnId, taskId, commit, tokens, projectDir });
+        }
+      }
+    } catch (err) {
+      try { process.stderr.write("[spawn-plan-hook] " + String(err && err.message || err) + "\n"); } catch (_) { /* silent */ }
+    }
+  });
+} catch (err) {
+  try { process.stderr.write("[spawn-plan-hook] " + String(err && err.message || err) + "\n"); } catch (_) { /* silent */ }
+}
+' "$PROJECT_DIR" "$COMMIT_SHA" 2>/dev/null
+
+exit 0