@tekyzinc/gsd-t 2.74.12 → 2.76.10

package/scripts/gsd-t-context-meter.test.js

@@ -0,0 +1,417 @@
+"use strict";
+
+/**
+ * Unit tests for scripts/gsd-t-context-meter.js (M34 Task 4 — CP2 satisfaction).
+ *
+ * Covers 10 scenarios from the task spec:
+ *   1. check-frequency skip
+ *   2. check-frequency hit — under threshold
+ *   3. check-frequency hit — over threshold
+ *   4. missing API key
+ *   5. transcript parse failure
+ *   6. API timeout / failure
+ *   7. state file corruption
+ *   8. missing transcript_path in payload
+ *   9. atomic write — no stale .tmp file after success
+ *  10. fail-open on unexpected throw (loadConfig throws)
+ *
+ * All dependencies are injected via runMeter's test seams so no real network
+ * calls, no real Anthropic API, and no real config-file reads are needed.
+ */
+
+const { test, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const { runMeter, defaultState } = require("./gsd-t-context-meter");
+
+/* ─────────────────────────── test harness ─────────────────────────── */
+
+let tmpRoot;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-t-cm-hook-"));
+});
+
+afterEach(() => {
+  try {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  } catch (_) {
+    /* ignore */
+  }
+});
+
+function makeConfig(overrides = {}) {
+  return {
+    version: 1,
+    thresholdPct: 75,
+    modelWindowSize: 200000,
+    checkFrequency: 5,
+    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+    statePath: ".gsd-t/.context-meter-state.json",
+    logPath: ".gsd-t/context-meter.log",
+    timeoutMs: 2000,
+    ...overrides,
+  };
+}
+
+function stateFile(root) {
+  return path.join(root, ".gsd-t", ".context-meter-state.json");
+}
+
+function logFile(root) {
+  return path.join(root, ".gsd-t", "context-meter.log");
+}
+
+function seedState(root, partial) {
+  const statePath = stateFile(root);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(
+    statePath,
+    JSON.stringify({ ...defaultState(), ...partial }, null, 2)
+  );
+}
+
+function makePayload() {
+  // A phony transcript path — tests inject a fake parseTranscript, so the path
+  // doesn't actually need to exist.
+  return {
+    session_id: "test-session",
+    transcript_path: path.join(tmpRoot, "fake-transcript.jsonl"),
+    tool_name: "Bash",
+    tool_input: {},
+    tool_response: {},
+  };
+}
+
+const FAKE_PARSED = {
+  system: "",
+  messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+};
+
+/* ───────────────────────────── tests ───────────────────────────── */
+
+test("1. check-frequency skip — API NOT called, counter incremented, stdout {}", async () => {
+  seedState(tmpRoot, { checkCount: 3 });
+
+  const apiCalls = [];
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig({ checkFrequency: 5 }),
+    _parseTranscript: async () => {
+      throw new Error("parseTranscript should not be called on skip");
+    },
+    _countTokens: async () => {
+      apiCalls.push("called");
+      throw new Error("countTokens should not be called on skip");
+    },
+  });
+
+  assert.deepEqual(out, {});
+  assert.equal(apiCalls.length, 0);
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 4);
+  assert.equal(state.lastError, null);
+});
+
+test("2. check-frequency hit — under threshold → {} + state updated", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 10000 }),
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 5);
+  assert.equal(state.inputTokens, 10000);
+  assert.equal(state.pct, 5);
+  assert.equal(state.threshold, "normal");
+  assert.equal(state.lastError, null);
+  assert.equal(state.modelWindowSize, 200000);
+});
+
+test("3. check-frequency hit — over threshold → additionalContext emitted", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 160000 }),
+  });
+
+  assert.equal(typeof out.additionalContext, "string");
+  assert.match(out.additionalContext, /80\.0%/);
+  assert.match(out.additionalContext, /200000/);
+  assert.match(out.additionalContext, /\/user:gsd-t-pause/);
+
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 5);
+  assert.equal(state.pct, 80);
+  // v3.0.0 three-band (M35): 80% ∈ [70, 85) → warn
+  assert.equal(state.threshold, "warn");
+  assert.equal(state.inputTokens, 160000);
+});
+
+test("4. missing API key — stdout {}, lastError.code='missing_key', no API call", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  const apiCalls = [];
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: {}, // no ANTHROPIC_API_KEY
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => {
+      apiCalls.push("x");
+      return { inputTokens: 1 };
+    },
+  });
+
+  assert.deepEqual(out, {});
+  assert.equal(apiCalls.length, 0);
+
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 5);
+  assert.ok(state.lastError, "lastError populated");
+  assert.equal(state.lastError.code, "missing_key");
+
+  // Log file exists and contains the missing_key diagnostic
+  assert.ok(fs.existsSync(logFile(tmpRoot)));
+  const log = fs.readFileSync(logFile(tmpRoot), "utf8");
+  assert.match(log, /missing_key/);
+  // And NEVER the API key itself
+  assert.ok(!log.includes("sk-test"));
+});
+
+test("5. transcript parse failure — returns null → lastError 'parse_failure'", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => null,
+    _countTokens: async () => {
+      throw new Error("should not call API when parse fails");
+    },
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 5);
+  assert.equal(state.lastError.code, "parse_failure");
+});
+
+test("6. API timeout / failure — countTokens null → lastError 'api_error', inputTokens reset", async () => {
+  seedState(tmpRoot, { checkCount: 4, inputTokens: 99999 });
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig({ timeoutMs: 50 }),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => null,
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.lastError.code, "api_error");
+  // Choice documented in hook: reset inputTokens to 0 on failure to avoid stale
+  // readings tripping threshold false-positives.
+  assert.equal(state.inputTokens, 0);
+  assert.equal(state.pct, 0);
+  assert.equal(state.threshold, "normal");
+});
+
+test("7. state file corruption — overwritten with valid defaults + fresh count", async () => {
+  const sp = stateFile(tmpRoot);
+  fs.mkdirSync(path.dirname(sp), { recursive: true });
+  fs.writeFileSync(sp, "not json{");
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig({ checkFrequency: 5 }),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 100 }),
+  });
+
+  assert.deepEqual(out, {});
+  // Post-write must be valid JSON with defaults + checkCount == 1
+  const state = JSON.parse(fs.readFileSync(sp, "utf8"));
+  assert.equal(state.version, 1);
+  assert.equal(state.checkCount, 1);
+  // checkCount=1 % checkFrequency=5 !== 0, so this was a skip path; API not called.
+  // Verify API was NOT called on this path by re-running with a throwing stub.
+});
+
+test("7b. state file corruption + frequency hit — API called once, state valid", async () => {
+  const sp = stateFile(tmpRoot);
+  fs.mkdirSync(path.dirname(sp), { recursive: true });
+  fs.writeFileSync(sp, "not json{");
+
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig({ checkFrequency: 1 }),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 500 }),
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(sp, "utf8"));
+  assert.equal(state.version, 1);
+  assert.equal(state.checkCount, 1);
+  assert.equal(state.inputTokens, 500);
+  assert.equal(state.lastError, null);
+});
+
+test("8. missing transcript_path in payload — lastError 'no_transcript', counter increments", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  const out = await runMeter({
+    payload: { session_id: "x" }, // no transcript_path
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => {
+      throw new Error("should not parse when transcript_path missing");
+    },
+    _countTokens: async () => {
+      throw new Error("should not call API when transcript_path missing");
+    },
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.checkCount, 5);
+  assert.equal(state.lastError.code, "no_transcript");
+});
+
+test("9. atomic write — no .tmp file on disk after successful run", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+
+  await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 1000 }),
+  });
+
+  const tmp = stateFile(tmpRoot) + ".tmp";
+  assert.equal(fs.existsSync(tmp), false, ".tmp file should not exist after rename");
+  assert.equal(fs.existsSync(stateFile(tmpRoot)), true, "state file should exist");
+});
+
+test("10. fail-open on unexpected throw — loadConfig throws → runMeter returns {}", async () => {
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => {
+      throw new Error("boom");
+    },
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 1 }),
+  });
+
+  assert.deepEqual(out, {});
+});
+
+test("10b. fail-open — parseTranscript throws synchronously → {}", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: () => {
+      throw new Error("sync boom");
+    },
+    _countTokens: async () => ({ inputTokens: 1 }),
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.lastError.code, "parse_failure");
+});
+
+test("10c. fail-open — countTokens throws → {}", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+  const out = await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: () => {
+      throw new Error("sync boom");
+    },
+  });
+
+  assert.deepEqual(out, {});
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.lastError.code, "api_error");
+});
+
+test("11. log never contains message content — only categories/counts", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+  const secretText = "SECRET_MESSAGE_CONTENT_XYZ";
+
+  await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => ({
+      system: "",
+      messages: [
+        { role: "user", content: [{ type: "text", text: secretText }] },
+      ],
+    }),
+    _countTokens: async () => ({ inputTokens: 42 }),
+  });
+
+  const log = fs.readFileSync(logFile(tmpRoot), "utf8");
+  assert.ok(!log.includes(secretText), "log must not contain message content");
+  assert.match(log, /measure/);
+  assert.match(log, /tokens=42/);
+});
+
+test("12. clock injection — timestamp uses injected clock", async () => {
+  seedState(tmpRoot, { checkCount: 4 });
+  const fixed = new Date("2026-04-14T18:00:00.000Z");
+
+  await runMeter({
+    payload: makePayload(),
+    projectRoot: tmpRoot,
+    env: { ANTHROPIC_API_KEY: "sk-test" },
+    clock: () => fixed,
+    _loadConfig: () => makeConfig(),
+    _parseTranscript: async () => FAKE_PARSED,
+    _countTokens: async () => ({ inputTokens: 1000 }),
+  });
+
+  const state = JSON.parse(fs.readFileSync(stateFile(tmpRoot), "utf8"));
+  assert.equal(state.timestamp, fixed.toISOString());
+});

package/scripts/gsd-t-heartbeat.js

@@ -97,8 +97,8 @@ function cleanupOldHeartbeats(gsdtDir) {
 const EVENT_HANDLERS = {
   SessionStart: (h) => ({ evt: "session_start", data: { source: h.source, model: h.model } }),
   PostToolUse: (h) => ({ evt: "tool", tool: h.tool_name, agent_id: h.agent_id || null, data: summarize(h.tool_name, h.tool_input) }),
-  SubagentStart: (h) => ({ evt: "agent_spawn", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id, tokens: process.env.CLAUDE_CONTEXT_TOKENS_USED ? parseInt(process.env.CLAUDE_CONTEXT_TOKENS_USED, 10) : null } }),
-  SubagentStop: (h) => ({ evt: "agent_stop", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id, tokens: process.env.CLAUDE_CONTEXT_TOKENS_USED ? parseInt(process.env.CLAUDE_CONTEXT_TOKENS_USED, 10) : null } }),
+  SubagentStart: (h) => ({ evt: "agent_spawn", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id, tokens: null } }),
+  SubagentStop: (h) => ({ evt: "agent_stop", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id, tokens: null } }),
   TaskCompleted: (h) => ({ evt: "task_done", data: { task: h.task_subject, agent: h.teammate_name } }),
   TeammateIdle: (h) => ({ evt: "agent_idle", data: { agent: h.teammate_name, team: h.team_name } }),
   Notification: (h) => ({ evt: "notification", data: { message: scrubSecrets(h.message), title: scrubSecrets(h.title) } }),

package/scripts/gsd-t-statusline.js

@@ -6,9 +6,11 @@
 // Configure in ~/.claude/settings.json:
 //   "statusLine": "node ~/.claude/scripts/gsd-t-statusline.js"
 //
-// Context usage is read from CLAUDE_CONTEXT_TOKENS_USED and
-// CLAUDE_CONTEXT_TOKENS_MAX environment variables if available.
-// Falls back to GSD-T project state only.
+// Context usage is read from .gsd-t/.context-meter-state.json (produced by
+// the Context Meter PostToolUse hook). v2.0.0 (M34) — the legacy
+// environment-variable-based context check is retired because Claude Code
+// never populated those env vars. When the state file is absent or stale
+// (>5min), the context segment is omitted.
 //
 // Zero external dependencies.
 
@@ -63,11 +65,24 @@ function contextBar(pct) {
 
 const root = findProjectRoot();
 
-// Context usage from env vars (provided by Claude Code if available)
-const tokensUsed = parseInt(process.env.CLAUDE_CONTEXT_TOKENS_USED || '0', 10);
-const tokensMax  = parseInt(process.env.CLAUDE_CONTEXT_TOKENS_MAX  || '0', 10);
-const hasContext = tokensMax > 0;
-const ctxPct     = hasContext ? Math.min(100, Math.round((tokensUsed / tokensMax) * 100)) : null;
+// Context usage from the Context Meter state file.
+// Stale-window check mirrors bin/token-budget.js (5 minutes).
+function readContextPct(projectRoot) {
+  if (!projectRoot) return null;
+  try {
+    const fp = path.join(projectRoot, '.gsd-t', '.context-meter-state.json');
+    const raw = fs.readFileSync(fp, 'utf8');
+    const s = JSON.parse(raw);
+    if (!s || typeof s.pct !== 'number' || !s.timestamp) return null;
+    const age = Date.now() - Date.parse(s.timestamp);
+    if (isNaN(age) || age > 5 * 60 * 1000 || age < 0) return null;
+    return Math.min(100, Math.round(s.pct));
+  } catch {
+    return null;
+  }
+}
+
+const ctxPct = readContextPct(root);
 
 // GSD-T project state
 let projectPart = '';

package/templates/CLAUDE-global.md

@@ -366,7 +366,11 @@ This gives the user real-time visibility into which model is handling each opera
 - `model: sonnet` — mid-tier reasoning: routine code changes, standard refactors, test writing, QA evaluation, straightforward synthesis
 - `model: opus` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, Red Team adversarial QA, quality judgment on critical paths
 
-**Token-Aware Orchestration** — If `bin/token-budget.js` exists, the system checks session token consumption before each subagent spawn in `execute`, `wave`, and `quick`. Graduated degradation: `downgrade` applies model overrides (opus→sonnet, sonnet→haiku), `conserve` checkpoints progress and skips non-essential phases, `stop` halts cleanly with a resume instruction. Projects without `token-budget.js` behave identically to baseline — token awareness is fully backward compatible.
+**Context Gate — No Silent Degradation (M35, v2.76.10+)** — The orchestrator reads session context consumption via `bin/token-budget.js` `getSessionStatus()` before each subagent spawn and applies a **three-band model** (`token-budget-contract.md` v3.0.0): `normal` (< 70%, proceed at full quality), `warn` (70–85%, log and proceed at **full quality** — never downgrade models, never skip Red Team / doc-ripple / Design Verification), `stop` (≥ 85%, halt cleanly and hand off to the runway estimator). The older v2.x `downgrade` / `conserve` bands are deleted. Model choice is made surgically per-phase via `bin/model-selector.js` (`model-selection-contract.md` v1.0.0) — sonnet for routine work, opus at declared escalation points, haiku strictly for mechanical tasks — not as a fallback for context pressure. Per-spawn telemetry is captured to `.gsd-t/token-metrics.jsonl` via `bin/token-telemetry.js` (`token-telemetry-contract.md` v1.0.0) and surfaced via `gsd-t metrics --tokens|--halts|--context-window`.
+
+**Context Meter (M34, v2.75.10+)** — The real context-window measurement feeding the context gate above. A PostToolUse hook (`scripts/gsd-t-context-meter.js`) runs after every tool call, streams the current Claude Code transcript to the Anthropic `count_tokens` API, and writes the real input-token count plus the resolved threshold band into `.gsd-t/.context-meter-state.json`. `getSessionStatus()` reads that state file (fresh window = 5 minutes) with a historical heuristic fallback when the file is missing or stale. Command files consume the signal via a small bash shim (`CTX_PCT=$(node -e "…tb.getSessionStatus('.').pct")`). Threshold bands (lower-bound inclusive) as of M35: `normal` < 70, `warn` ≥ 70, `stop` ≥ 85. Requires `ANTHROPIC_API_KEY` — `gsd-t doctor` hard-gates on its presence.
+
+*Historical note (v2.74.12–v2.74.13)*: between 2026-03 and 2026-04 the orchestrator used `bin/task-counter.cjs` — a proxy that assumed N tasks ≈ M% context used. That itself replaced an earlier env-var-based check (`CLAUDE_CONTEXT_TOKENS_USED` / `CLAUDE_CONTEXT_TOKENS_MAX`) that never worked because Claude Code does not export those variables. Both approaches are retired: the env-var path is removed entirely; `task-counter.cjs` is deleted from the package and from downstream projects via a one-shot migration in `gsd-t update-all`. Do not reintroduce either check.
 
 ## API Documentation Guard (Swagger/OpenAPI)
 

package/templates/CLAUDE-project.md

@@ -26,12 +26,32 @@
 <!-- Claude will verify the branch before every commit. -->
 **Expected branch**: {main | master | feature-branch-name}
 
-## Daily Token Budget (optional)
-<!-- Set a session token ceiling for token-aware orchestration (bin/token-budget.js). -->
-<!-- When the session approaches this ceiling, model assignments are downgraded and -->
-<!-- non-essential operations are skipped to stay within budget. -->
-<!-- Example: 1500000 (1.5M tokens) — omit this field to disable token-aware orchestration. -->
-<!-- **Daily token budget**: {ceiling in tokens} -->
+## Context Gate — No Silent Degradation (M35, v2.76.10+)
+<!-- Three-band context gate per .gsd-t/contracts/token-budget-contract.md v3.0.0: -->
+<!--   - normal (<70%):  proceed at full quality -->
+<!--   - warn   (70–85%): log to .gsd-t/token-log.md and proceed at FULL quality -->
+<!--                      (never downgrade models, never skip Red Team / doc-ripple / Design Verification) -->
+<!--   - stop   (≥85%):  halt cleanly, runway estimator / headless auto-spawn handles the handoff -->
+<!-- Model choice is made surgically per-phase via bin/model-selector.js (model-selection-contract.md v1.0.0): -->
+<!--   - haiku  — mechanical: test runners, file-existence checks, JSON validation, branch guards -->
+<!--   - sonnet — routine: execute, test-sync, doc-ripple wiring, quick, integrate, debug fix-apply -->
+<!--   - opus   — high-stakes: partition, discuss, Red Team, verify judgment, debug root-cause, contracts -->
+<!-- Per-spawn telemetry is captured to .gsd-t/token-metrics.jsonl via bin/token-telemetry.js -->
+<!-- (token-telemetry-contract.md v1.0.0) and surfaced via: -->
+<!--   - gsd-t metrics --tokens [--by model,command,phase,milestone] -->
+<!--   - gsd-t metrics --halts -->
+<!--   - gsd-t metrics --context-window -->
+
+## Context Meter (M34, v2.75.10+)
+<!-- The Context Meter is a PostToolUse hook that streams the current transcript -->
+<!-- to Anthropic count_tokens and writes the real context % to -->
+<!-- .gsd-t/.context-meter-state.json. bin/token-budget.js reads that file as the -->
+<!-- authoritative session-stop signal, feeding the three-band context gate above. -->
+<!-- Requires ANTHROPIC_API_KEY in the shell environment. -->
+<!-- Threshold bands (lower-bound inclusive) as of M35: normal<70, warn≥70, stop≥85. -->
+<!-- Config: .gsd-t/context-meter-config.json — apiKeyEnvVar, modelWindowSize, thresholdPct, checkFrequency. -->
+<!-- Verify: `npx @tekyzinc/gsd-t doctor` hard-gates on API key + hook + live count_tokens dry-run. -->
+<!-- Historical: v2.74.12 used bin/task-counter.cjs (proxy); v2.74.11 and earlier used CLAUDE_CONTEXT_TOKENS_* env vars (never worked). Both retired in v2.75.10. M35 removed the v2.x downgrade/conserve bands that silently degraded quality. -->
 
 <!-- For multi-branch parallel work (e.g., web + mobile in separate terminals), -->
 <!-- each terminal's CLAUDE.md should declare its own expected branch. -->

package/templates/context-meter-config.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "thresholdPct": 75,
+  "modelWindowSize": 200000,
+  "checkFrequency": 5,
+  "apiKeyEnvVar": "ANTHROPIC_API_KEY",
+  "statePath": ".gsd-t/.context-meter-state.json",
+  "logPath": ".gsd-t/context-meter.log",
+  "timeoutMs": 2000
+}

package/templates/prompts/README.md

@@ -14,7 +14,7 @@ Now command files reference these by path. The orchestrator passes the file path
 
 ## Why per-domain instead of per-task
 
-Red Team and Design Verification were originally per-domain. They were promoted to per-task by commits `da6d3ae` and `b68353e`, on the assumption that the orchestrator's `CLAUDE_CONTEXT_TOKENS_USED` self-check would catch context drain before it got bad. That env var is never set by Claude Code — the self-check was vaporware. With it inert, per-task spawning of ~10k-token Red Team subagents drained sessions in 5-10 tasks. Reverting them to per-domain raises the safe task count from ~5 to ~15+.
+Red Team and Design Verification were originally per-domain. They were promoted to per-task by commits `da6d3ae` and `b68353e`, on the assumption that the orchestrator's environment-variable-based context self-check would catch context drain before it got bad. That env-var path was never populated by Claude Code — the self-check was vaporware. With it inert, per-task spawning of ~10k-token Red Team subagents drained sessions in 5-10 tasks. Reverting them to per-domain raises the safe task count from ~5 to ~15+. v2.0.0 (M34) replaced the broken check with real `count_tokens` measurements via the Context Meter PostToolUse hook.
 
 QA stays per-task because (a) it's much smaller, (b) it grounds against contracts which can drift task by task.