@tekyzinc/gsd-t 3.10.11 → 3.10.12

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.10.12] - 2026-04-15
+
+### Fixed — P0 context meter regression (M36 /compact incidents)
+
+**Background**: During M36 execution the user hit Claude Code's native `/compact` prompt multiple times — the exact scenario M34's Context Meter was built to prevent. Audit of `.gsd-t/.context-meter-state.json` revealed `checkCount=2102` with `pct=0` and `lastError: missing_key` forever. Every one of 2102 PostToolUse hook calls had silently failed at the `ANTHROPIC_API_KEY` check and returned `{}` per the fail-open invariant. `token-budget.getSessionStatus()` read `pct: 0` and reported `threshold: "normal"` to the gate, so the gate was **blind since installation** with no user-visible alarm at any layer.
+
+### Added
+- **`bin/token-budget.js`** — fourth `stale` band in `getSessionStatus()`. When the state file exists but is dead (`lastError` set, `timestamp` null, state older than 5 min, or JSON corrupt), returns `{threshold: "stale", deadReason}` with one of `meter_error:missing_key`, `meter_error:api_error`, `meter_error:parse_failure`, `meter_error:no_transcript`, `meter_never_measured`, `meter_state_stale`, `state_file_corrupt`, `state_file_unreadable`. Previously fell through to the heuristic (which reported 0% and was indistinguishable from a healthy fresh session).
+- **`bin/token-budget.js`** — `buildBandResponse()` handles the `stale` band with a loud message pointing at `gsd-t doctor` and `ANTHROPIC_API_KEY`.
+- **`commands/gsd-t-resume.md`** — new Step 0.6 "Context Meter Health Check" runs after the headless read-back banner and before state loading. If the meter is stale, prints a prominent warning, runs `gsd-t doctor` inline, and refuses to auto-advance into gated commands (`execute`, `wave`, `integrate`, `quick`, `debug`) until fixed.
+- **`.gsd-t/contracts/context-meter-contract.md` v1.1.0** — new §"Stale Band and Resume Gating" documents the regression, the fix, and the mandatory resume-time health check. Also adds a "measurement only, never inference" rule to the configuration section clarifying that the API key named in `apiKeyEnvVar` must never be used for `/v1/messages` inference — inference always runs through the Claude Code subscription.
+- **`.gsd-t/contracts/token-budget-contract.md` v3.1.0** — fourth band added to the threshold table with explicit "gate treats stale as exit-10 stop but does NOT auto-spawn" semantics (a fresh session would have the same broken guardrail).
+
+### Changed
+- **`commands/gsd-t-execute.md`** — Step 3.5 gate snippet (Orchestrator Context Gate) and Step 7 per-domain context gate re-check now exit 10 on `s.threshold==='stop'||s.threshold==='stale'`. Both sites print different user-facing messages for each band: `stop` → "halt cleanly, hand off to runway estimator"; `stale` → "run `gsd-t doctor` and fix the cause".
+- **`commands/gsd-t-wave.md`** — Wave Orchestrator Context Gate snippet now exits 10 on `stale` in addition to `stop`. The `stale` path does NOT call `autoSpawnHeadless()` — a fresh session would have the same broken guardrail.
+- **`bin/gsd-t.js`** — `showStatusContextMeter()` promotes the dead-meter line from a dim ignorable whisper to a red `✗ CONTEXT METER DEAD` alarm with actionable fix instructions (explicitly calls out "measurement only — inference stays on Claude Code subscription" when the cause is `missing_key`). This is the line the user would have seen on every `gsd-t status` run during M36 if it had been loud enough to notice.
+
+### Root cause and the 6 hypotheses
+
+The continue-here file for this session listed 6 plausible failure modes. The audit disproved 5 of them and proved the sixth:
+1. ❌ Gate only fires at subagent-spawn boundaries — FALSE, coverage is broad (16 command files call `getSessionStatus`, `execute` alone has 13 call sites).
+2. ❌ Coverage holes in command files — FALSE, the 4 gated commands (`execute`, `wave`, `integrate`, `quick`, `debug`) all call the gate.
+3. ❌ `.gsd-t/.context-meter-state.json` stale due to silent hook failure — PARTIALLY; the state was not stale, it was **never fresh**. The file had `timestamp: null` after 2102 checks.
+4. ✅ **PostToolUse hook silent failure on missing `ANTHROPIC_API_KEY` — CONFIRMED root cause.** The hook's `runMeter()` step 5 checks the env var, writes `lastError: {code: "missing_key"}`, persists the state, and returns `{}`. This is correct per the hook's fail-open invariant. But nothing downstream was LOUD about it: `token-budget.js` fell through to the heuristic; the gate saw `threshold: "normal"`; `gsd-t status` printed a dim line.
+5. ❌ Session-tokens vs main-transcript measurement gap — MOOT, you can't have a measurement gap if you never measured.
+6. ❌ 85% stop band too thin — MOOT for the same reason.
+
+The v3.10.12 fix targets only the real root cause: **make the gate fail loud when the meter is dead**, and add a resume-time health check so future sessions can't silently run without the guardrail.
+
+### User-visible fix
+
+If you see `✗ CONTEXT METER DEAD` on `gsd-t status` or `⚠ Context meter is DEAD` from `gsd-t-resume`, set `ANTHROPIC_API_KEY` in your shell profile:
+
+```bash
+echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Important:** this key is used ONLY for `count_tokens` measurement via the PostToolUse hook and `gsd-t doctor` diagnostics. It is NEVER used for model inference — inference always runs through the Claude Code subscription. The contract `context-meter-contract.md` v1.1.0 Rule #3 enforces this.
+
 ## [3.10.11] - 2026-04-15
 
 ### Added

package/bin/gsd-t.js

@@ -1515,11 +1515,20 @@ function showStatusContextMeter() {
     return;
   }
 
-  // Error case: inputTokens === 0 AND lastError set
-  if (state.lastError && state.inputTokens === 0) {
+  // Error case: lastError set. Promoted from DIM to ERROR in v3.10.12.
+  // Before: a silent dim line nobody read. After: a red alarm so users see
+  // that the context-window guardrail is DEAD (M36 regression fix).
+  if (state.lastError) {
     const code = (state.lastError && state.lastError.code) || "unknown";
-    const rel = state.timestamp ? formatRelativeTime(state.timestamp) : "unknown";
-    log(`  ${DIM}Context: N/A (meter error: ${code}) — last check ${rel}${RESET}`);
+    const rel = state.timestamp ? formatRelativeTime(state.timestamp) : "never measured";
+    log(`  ${RED}${BOLD}✗ CONTEXT METER DEAD${RESET} ${RED}— error: ${code}, last check: ${rel}${RESET}`);
+    log(`    ${RED}The context-window guardrail is NOT working. Long sessions will hit /compact.${RESET}`);
+    if (code === "missing_key") {
+      log(`    ${YELLOW}Fix: export ANTHROPIC_API_KEY in your shell profile${RESET}`);
+      log(`    ${YELLOW}     (measurement only — inference stays on Claude Code subscription)${RESET}`);
+    } else {
+      log(`    ${YELLOW}Fix: run 'gsd-t doctor' for diagnostics${RESET}`);
+    }
     return;
   }
 

package/bin/token-budget.js

@@ -115,6 +115,21 @@ function getSessionStatus(projectDir) {
     const threshold = resolveThreshold(pct);
     return { consumed, estimated_remaining, pct, threshold };
   }
+  // Meter exists but is dead (file present, API key missing, parse/API error,
+  // or timestamp stale). Return a `stale` band so callers halt instead of
+  // silently running with a blind gate. This is the fix for the M36 /compact
+  // regression where checkCount=2102 but every hook call failed fail-open.
+  const dead = readContextMeterDead(dir);
+  if (dead) {
+    const window = dead.modelWindowSize > 0 ? dead.modelWindowSize : 200000;
+    return {
+      consumed: 0,
+      estimated_remaining: window,
+      pct: 0,
+      threshold: "stale",
+      deadReason: dead.reason,
+    };
+  }
   return getSessionStatusHeuristic(dir);
 }
 
@@ -127,12 +142,42 @@ function readContextMeterState(dir) {
     if (!s.timestamp) return null;
     const age = Date.now() - Date.parse(s.timestamp);
     if (isNaN(age) || age > STATE_STALE_MS || age < 0) return null;
+    if (s.lastError && typeof s.lastError === "object") return null;
     return s;
   } catch (_) {
     return null;
   }
 }
 
+// Return { reason, modelWindowSize } when the state file exists but the meter
+// is not producing a fresh, clean reading. Returns null when the file is
+// missing entirely (no meter installed — fall through to heuristic).
+function readContextMeterDead(dir) {
+  try {
+    const fp = path.join(dir, STATE_FILE_REL);
+    if (!fs.existsSync(fp)) return null;
+    const raw = fs.readFileSync(fp, "utf8");
+    const s = JSON.parse(raw);
+    if (!s || typeof s !== "object") {
+      return { reason: "state_file_corrupt", modelWindowSize: 0 };
+    }
+    const window = Number.isInteger(s.modelWindowSize) ? s.modelWindowSize : 0;
+    if (s.lastError && typeof s.lastError === "object" && typeof s.lastError.code === "string") {
+      return { reason: `meter_error:${s.lastError.code}`, modelWindowSize: window };
+    }
+    if (!s.timestamp) {
+      return { reason: "meter_never_measured", modelWindowSize: window };
+    }
+    const age = Date.now() - Date.parse(s.timestamp);
+    if (isNaN(age) || age < 0 || age > STATE_STALE_MS) {
+      return { reason: "meter_state_stale", modelWindowSize: window };
+    }
+    return null;
+  } catch (_) {
+    return { reason: "state_file_unreadable", modelWindowSize: 0 };
+  }
+}
+
 function getSessionStatusHeuristic(dir) {
   const window = 200000;
   const consumed = readSessionConsumed(dir);
@@ -218,6 +263,12 @@ function buildBandResponse(band, pct) {
         pct: safePct,
         message: `Context ${safePct.toFixed(1)}% — stop band (≥${STOP_THRESHOLD_PCT}%). Halt cleanly; hand off to runway estimator / headless auto-spawn.`,
       };
+    case "stale":
+      return {
+        band: "stale",
+        pct: safePct,
+        message: `Context meter is DEAD — no fresh measurements. Gate treats this as STOP. Run: gsd-t doctor. Fix the cause (usually missing ANTHROPIC_API_KEY) before running gated commands.`,
+      };
     case "normal":
     default:
       return {

package/commands/gsd-t-execute.md

@@ -529,7 +529,7 @@ Report back:
 
 6. **Per-domain Red Team** — invoke Step 5.5 (Red Team) NOW for this domain. This is the first place Red Team runs in v2.74.12 — there is no global post-execute Red Team anymore. If Red Team returns FAIL, fix bugs and re-run before proceeding to the next domain (max 2 fix-and-verify cycles); if bugs persist, log to `.gsd-t/deferred-items.md` and present to user.
 
-7. **Context gate re-check** — run `node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); if(s.threshold==='stop')process.exit(10); if(s.threshold==='warn')process.exit(13);"`. If exit code is `10`, follow the Step 3.5 STOP procedure now (do NOT spawn the next domain). If exit code is `13`, log the warning and proceed at full quality for the next domain (no model overrides, no phase skips — quality is never silently degraded).
+7. **Context gate re-check** — run `node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); if(s.threshold==='stop'||s.threshold==='stale')process.exit(10); if(s.threshold==='warn')process.exit(13);"`. If exit code is `10`, follow the Step 3.5 STOP procedure now (do NOT spawn the next domain). `stale` means the context meter is dead (usually missing `ANTHROPIC_API_KEY`) and is treated as STOP — print `⚠ Context meter DEAD — run 'gsd-t doctor' and fix before continuing` and halt. If exit code is `13`, log the warning and proceed at full quality for the next domain (no model overrides, no phase skips — quality is never silently degraded).
 
 ### Team Mode (when agent teams are enabled)
 Spawn teammates for domains within the same wave. Only domains in the same wave can run in parallel — do not spawn teammates for domains in different waves simultaneously. Each teammate uses the **domain task-dispatcher pattern** — one subagent per task within their domain (same as solo mode).
@@ -680,13 +680,13 @@ The orchestrator MUST check `getSessionStatus()` BEFORE every task subagent spaw
 **Before each task spawn — gate check:**
 
 ```bash
-node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s)); if(s.threshold==='stop')process.exit(10); if(s.threshold==='warn')process.exit(13);"
+node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s)); if(s.threshold==='stop'||s.threshold==='stale')process.exit(10); if(s.threshold==='warn')process.exit(13);"
 ```
 
-Exit code semantics (three-band model per `token-budget-contract.md` v3.0.0):
+Exit code semantics (three-band model per `token-budget-contract.md` v3.0.0, extended with a fourth `stale` guard in v3.10.12):
 - `0` → `normal` band (< 70% ctx). Proceed with standard model assignments.
 - `13` → `warn` band (70–85%). Log the warning to `.gsd-t/token-log.md` and proceed at full quality. **Never downgrade models or skip phases** — M35 removed that behavior intentionally. If the projected runway is insufficient, the runway estimator (m35-runway-estimator) will halt cleanly before reaching `stop`.
-- `10` → `stop` band (≥ 85%). STOP immediately. Do NOT spawn the next task. Jump straight to the STOP procedure below.
+- `10` → `stop` band (≥ 85%) **OR `stale` band (meter dead)**. STOP immediately. Do NOT spawn the next task. Jump straight to the STOP procedure below. For `stale`, also print `⚠ Context meter DEAD — run 'gsd-t doctor' and fix the cause (usually missing ANTHROPIC_API_KEY) before resuming` and halt the session — `stale` is not a resumable halt, it means the guardrail is BROKEN, not that the session is full.
 
 The JSON on stdout contains `{consumed, estimated_remaining, pct, threshold}` — capture `pct` as `{CTX_PCT}` for the token-log `Ctx%` column on the NEXT spawn.
 

package/commands/gsd-t-resume.md

@@ -72,6 +72,35 @@ This prints a `## Headless runs since you left` banner listing any completed ses
 
 Contract: `.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0
 
+## Step 0.6: Context Meter Health Check (MANDATORY, v3.10.12+)
+
+Before loading any other state, verify the Context Meter (M34) is actually alive. A dead meter was the root cause of the M36 `/compact` regression (2026-04-15) — `checkCount=2102` but every hook call failed fail-open because `ANTHROPIC_API_KEY` was unset, and the gate silently reported `pct=0` forever.
+
+Run via Bash:
+
+```bash
+node -e "
+const tb=require('./bin/token-budget.js');
+const s=tb.getSessionStatus('.');
+if (s.threshold === 'stale') {
+  console.error('⚠ Context meter is DEAD — reason: ' + (s.deadReason || 'unknown'));
+  console.error('  The context-window guardrail is BROKEN. Without it, long sessions will hit /compact silently.');
+  console.error('  Fix: set ANTHROPIC_API_KEY in your shell profile (measurement only, never inference).');
+  console.error('  Run: gsd-t doctor');
+  process.exit(1);
+}
+process.stdout.write('context-meter: ok (' + s.threshold + ', ' + s.pct + '%)\\n');
+" || true
+```
+
+If the meter is stale:
+1. **Print the warning** exactly as above (non-fatal — do not halt resume).
+2. **Run `node bin/gsd-t.js doctor`** inline and show the output so the user sees the actionable check list.
+3. **Continue with resume** — but add a prominent `⚠ CONTEXT METER DEAD — gate will treat future gate checks as STOP until fixed` line to your end-of-resume status block so the user cannot miss it.
+4. **Refuse to auto-advance into `execute` / `wave` / `integrate`** until the meter is healthy. If the continue-here file says the next action is one of those gated commands, stop at "meter dead — fix before continuing" instead.
+
+Contract: `context-meter-contract.md` v1.1.0 (v3.10.12) — §"Stale Band and Resume Gating"
+
 ## Step 1: Load Full State (cross-session only)
 
 Read in this exact order:

package/commands/gsd-t-wave.md

@@ -193,15 +193,16 @@ After phase agent returns — run via Bash:
 Run via Bash AFTER each phase agent returns:
 
 ```bash
-node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s)); if(s.threshold==='stop')process.exit(10); if(s.threshold==='warn')process.exit(13);"
+node -e "const tb=require('./bin/token-budget.js'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s)); if(s.threshold==='stop'||s.threshold==='stale')process.exit(10); if(s.threshold==='warn')process.exit(13);"
 ```
 
 The JSON on stdout contains `{consumed, estimated_remaining, pct, threshold}` — capture `pct` as `{CTX_PCT}` for the token-log row.
 
-Exit-code handling (three-band model per `token-budget-contract.md` v3.0.0):
+Exit-code handling (three-band model per `token-budget-contract.md` v3.0.0, extended with a fourth `stale` guard in v3.10.12):
 - `0` (normal, <70%) → proceed to the next phase at full quality.
 - `13` (warn, 70–85%) → log the warning to `.gsd-t/token-log.md` and proceed to the next phase at full quality. **Never downgrade models or skip phases** — the runway estimator (m35-runway-estimator) is responsible for halting cleanly before reaching `stop`.
 - `10` (stop, ≥85%) → STOP the wave loop. Save checkpoint to `.gsd-t/progress.md` — record which phases are complete, which remain. Call `autoSpawnHeadless({command: 'gsd-t-wave', args, projectDir})` — this spawns a fresh headless session that auto-resumes via `/gsd-t-resume` without any manual `/clear`. Output: `⏸️ Wave orchestrator context gate reached ({pct}% of model window) — handing off to a fresh headless session (ID: {id}). Progress saved.` Return cleanly. Do NOT spawn the next phase agent, do NOT exit with a special code — the handoff is the success path.
+- `10` (stale, meter dead) → **not resumable**. The context meter is dead (usually missing `ANTHROPIC_API_KEY`). Do NOT auto-spawn a fresh session — a fresh session would have the same broken guardrail. Instead, halt the wave and print `⚠ Context meter DEAD — run 'gsd-t doctor' and fix the cause before resuming`.
 
 As of v2.0.0 (M34), the wave orchestrator reads the SAME `bin/token-budget.js` real-source measurement as the execute orchestrator — both trace back to `.gsd-t/.context-meter-state.json` produced by the Context Meter PostToolUse hook. Each phase spawn (PARTITION, DISCUSS, PLAN, IMPACT, EXECUTE, TEST-SYNC, INTEGRATE, VERIFY+COMPLETE, DOC-RIPPLE) causes post-call updates to the state file, so each subsequent gate check reflects the real context consumption trajectory. When the state file is absent or stale, the call falls back to the historical heuristic.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.10.11",
+  "version": "3.10.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 61 slash commands with unattended supervisor relay, headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",