@tekyzinc/gsd-t 2.74.12 → 2.76.10

package/CHANGELOG.md

@@ -2,6 +2,136 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.76.10] - 2026-04-15
+
+### M35: Runway-Protected Execution — Aggressive Pause-Resume Replaces Graduated Degradation
+
+**Background**: Between v2.74 and v2.75, GSD-T coped with context pressure via graduated degradation — `downgrade` and `conserve` bands that silently demoted opus→sonnet→haiku and skipped Red Team / doc-ripple / Design Verify phases. This made quality **conditional on context pressure**, a load-bearing invariant the user could neither see nor control. M35 removes graduated degradation entirely and replaces it with: surgical per-phase model selection (plan-time, never runtime), a pre-flight runway estimator that refuses runs projected to cross 85% and auto-spawns a detached headless continuation, frozen 18-field per-spawn token telemetry, and a detect-only optimization backlog the user explicitly promotes or rejects. The user never types `/clear` under normal operation.
+
+### Added
+
+- **`bin/model-selector.js`** — declarative phase→tier mapping (≥13 phase mappings) with complexity-signal escalation (`cross_module_refactor`, `security_boundary`, `data_loss_risk`, `contract_design`) that escalates sonnet→opus at plan time. Each command file carries a `## Model Assignment` block.
+- **`bin/runway-estimator.js`** — `estimateRunway({command, domain_type, remaining_tasks})` reads `.gsd-t/token-metrics.jsonl` via a three-tier query fallback (exact → command+phase → command) and returns `{can_start, projected_end_pct, confidence, recommendation}`. Confidence grading: high ≥50 records, medium ≥10, low <10 (+1.25× skew).
+- **`bin/headless-auto-spawn.js`** — detached `child_process.spawn({detached:true, stdio:['ignore', fd, fd]}) + child.unref()`. Writes `.gsd-t/headless-sessions/{session-id}.json`, polls with `process.kill(pid, 0)` (timer `.unref()`-ed), marks `status: completed`, posts a macOS `osascript` notification on exit (graceful no-op on non-darwin).
+- **`bin/check-headless-sessions.js`** — scans `.gsd-t/headless-sessions/` for `status === 'completed' && surfaced !== true` and renders the read-back banner on `/user:gsd-t-resume` and `/user:gsd-t-status`. Exports `checkCompletedSessions`, `markSurfaced`, `formatBanner`, `printBannerIfAny`, `computeDurationLabel`.
+- **`bin/token-telemetry.js`** — per-spawn token bracket writes one frozen 18-field JSONL record per subagent spawn to `.gsd-t/token-metrics.jsonl`. Fields: `timestamp, session_id, command, phase, domain, task_id, model, complexity_signals[], input_tokens, output_tokens, duration_seconds, start_pct, end_pct, halt_type, halt_reason, exit_code, run_type, projection_variance`. `halt_type` values: `clean`, `stop-band`, `runway-refuse`, `native-compact` (defect), `crash`.
+- **`bin/token-optimizer.js`** — at `complete-milestone`, scans the last 3 milestones and appends recalibration recommendations to `.gsd-t/optimization-backlog.md`. Four detection rules: `demote` (opus phase ≥90% success, ≥3 volume), `escalate` (sonnet phase ≥30% failure rate, ≥5 volume), `runway-tune` (projection vs. actual divergence >15%), `investigate` (per-phase p95 > 2× median, ≥10 volume). Fingerprint-based 5-milestone cooldown on rejected items. Exports `detectRecommendations`, `appendToBacklog`, `readBacklog`, `writeBacklog`, `parseBacklog`, `setRecommendationStatus`, `DETECTION_RULES`, `REJECTION_COOLDOWN_MILESTONES`.
+- **`bin/advisor-integration.js`** — `/advisor` escalation hook; convention-based fallback if no programmable API.
+- **`.gsd-t/contracts/token-budget-contract.md` v3.0.0 ACTIVE** — clean-break rewrite. Three bands only: `normal` <70%, `warn` 70–85%, `stop` ≥85%. Response shape `{band, pct, message}`. `downgrade`, `conserve`, `modelOverrides`, `skipPhases` all deleted — no compat shim.
+- **`.gsd-t/contracts/model-selection-contract.md` v1.0.0 ACTIVE** — declarative phase→tier rules, complexity-signal escalation semantics, `/advisor` hook schema.
+- **`.gsd-t/contracts/token-telemetry-contract.md` v1.0.0 ACTIVE** — frozen 18-field per-spawn JSONL schema, `halt_type` enum, `run_type` enum.
+- **`.gsd-t/contracts/runway-estimator-contract.md` v1.0.0 ACTIVE** — pre-flight projection, three-tier query fallback, confidence grading, refusal + headless handoff contract.
+- **`.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0 ACTIVE** — detached continuation, session file schema, macOS notification channel, read-back banner.
+- **`commands/gsd-t-optimization-apply.md`** — promotes a backlog recommendation by ID, auto-routes to `/user:gsd-t-quick` or `/user:gsd-t-backlog-promote` based on recommendation type.
+- **`commands/gsd-t-optimization-reject.md`** — rejects a recommendation with optional `--reason`, sets 5-milestone cooldown. Reason captured in token-log.md + Decision Log.
+- **`gsd-t metrics` flags** — `--tokens` (per-command/phase token summary), `--halts` (halt-type breakdown; flags any `native-compact` as defect), `--context-window` (trailing 20-run `end_pct` with runway headroom).
+- **Test coverage**: `test/headless-auto-spawn.test.js` (16 tests — session file schema, completion watcher, read-back banner, non-darwin degradation, E2E shim smoke), `test/token-optimizer.test.js` (19 tests — each rule triggers/skips, parseBacklog round-trip, cooldown filter, OB-T1+OB-T4 integration roundtrip), plus rewrites of `test/token-budget.test.js` around v3.0.0. **~1011/1011 total tests green through Wave 4**.
+
+### Changed
+
+- **`bin/token-budget.js`** — `getSessionStatus()` now returns `{band, pct, message}` with only three bands. `applyModelOverride`, `skipPhases`, `getDegradationActions` band-branching for `downgrade`/`conserve` — all deleted.
+- **`bin/orchestrator.js`** — gate semantics: `normal` proceed, `warn` log + proceed at **full quality**, `stop` halt cleanly and hand off to runway estimator → headless-auto-spawn. No model swaps. No phase skips.
+- **Command files** (`gsd-t-execute.md`, `gsd-t-wave.md`, `gsd-t-quick.md`, `gsd-t-integrate.md`, `gsd-t-debug.md`, `gsd-t-doc-ripple.md`) — Step 0 runway gate; `## Model Assignment` blocks documenting per-phase tier choices; per-spawn token telemetry brackets around every subagent spawn.
+- **`commands/gsd-t-resume.md`** — Step 0.5 Headless Read-Back Banner (MANDATORY) invokes `node bin/check-headless-sessions.js . 2>/dev/null || true`.
+- **`commands/gsd-t-status.md`** — Step 0 Headless Read-Back Banner + Step 0.5 Optimization Backlog Pending Count (one-liner, suppressed when N=0).
+- **`commands/gsd-t-complete-milestone.md`** — Step 14 non-blocking optimizer invocation: `detectRecommendations({lookbackMilestones: 3})` → `appendToBacklog`. Wrapped in try/catch; optimizer failure logged but not re-thrown.
+- **`commands/gsd-t-backlog-list.md`** — `--file` flag supports rendering `optimization-backlog.md` via `bin/token-optimizer.js` parseBacklog, with optional `--status {pending|promoted|rejected}` filter.
+- **`commands/gsd-t-help.md`** — new OPTIMIZATION section in summary table; detailed entries for `optimization-apply` and `optimization-reject`.
+- **Documentation ripple**:
+  - `README.md` — "Runway-Protected Execution (M35, v2.76.10)" section replacing "Token-Aware Orchestration"; threshold description updated to "85% = stop band; 70% = warn band — cue for explicit pause/resume; no silent degradation".
+  - `docs/GSD-T-README.md` — 3-band table replacing 5-band table, "Zero silent quality degradation" explanation, per-phase model selection, `/advisor` escalation, `gsd-t metrics` flags, optimization apply/reject.
+  - `docs/methodology.md` — new "From Silent Degradation to Aggressive Pause-Resume (M35)" section with five principles (quality non-negotiable, explicit per-phase model selection, user never types `/clear`, data before optimization, clean break no compat shim) + "Structural guarantee" closing paragraph.
+  - `docs/architecture.md` — dataflow updated for runway estimator + headless auto-spawn + v3.0.0 band semantics; M35 supporting components section (model-selector, token-optimizer, check-headless-sessions).
+  - `docs/infrastructure.md` — 3-band threshold table replacing 5-band; new Runway-Protected Execution section covering all 5 components; `gsd-t metrics` CLI table; `/advisor` convention.
+  - `docs/requirements.md` — REQ-069 through REQ-078 M35 traceability; REQ-076/077 marked complete.
+  - `docs/prd-harness-evolution.md` — §3.7 rewritten as "Context Gate + Surgical Model Escalation"; risk-table + session-cost mitigations updated to reference runway estimator + headless handoff (no graduated degradation).
+  - `templates/CLAUDE-global.md` + `templates/CLAUDE-project.md` — Token-Aware Orchestration section rewritten around M35 semantics.
+
+### Removed
+
+- **Graduated degradation** — `downgrade` and `conserve` bands are deleted from `bin/token-budget.js`, the v3.0.0 `token-budget-contract.md`, and every command file. `applyModelOverride`, `skipPhases`, and all related runtime machinery are gone.
+- **Runtime model downgrade** — there is no code path that swaps opus→sonnet or sonnet→haiku under context pressure. Model choice is a plan-time decision made by `bin/model-selector.js`, full stop.
+- **Phase-skipping under pressure** — Red Team, doc-ripple, and Design Verify always run at their designated tier regardless of context %. No "non-essential" phase exists.
+- **Manual `/clear` prompts** under normal operation — the user only sees a `/clear` prompt when the headless handoff itself fails, which is an explicit degradation path, not a silent one.
+
+### Migration
+
+- **No user migration required** for v2.75.10 → v2.76.10 — `gsd-t update-all` rewrites command files in place and the new contracts ship with the package. Existing projects inherit the three-band gate automatically.
+- **Projects with custom wrappers calling `getSessionStatus()`** — the return shape changed from `{band, pct, modelOverrides, skipPhases, message}` to `{band, pct, message}`. `modelOverrides` and `skipPhases` consumers must delete their handling code (they never had a quality-reducing role in v3.0.0 anyway).
+- **Historical note**: `halt_type: native-compact` entries in `.gsd-t/token-metrics.jsonl` are defect signals — if they appear after upgrade, the runway estimator thresholds need re-tuning. The structural guarantee is that with `STOP_THRESHOLD_PCT = 85` and pre-flight refusal, the runtime's 95% native compact is unreachable under healthy operation.
+
+### Propagation
+
+Run `/user:gsd-t-version-update-all` from any registered GSD-T project to propagate v2.76.10 to all projects. The command files, templates, and `bin/` scripts are rewritten in place; project state in `.gsd-t/` is preserved.
+
+---
+
+## [2.75.10] - 2026-04-14
+
+### M34: Context Meter — Real Context-Window Measurement Replaces Task-Counter Proxy
+
+**Background**: v2.74.12/v2.74.13 introduced `bin/task-counter.cjs` as a deterministic session-burn gate after the env-var-based context self-check (`CLAUDE_CONTEXT_TOKENS_USED`) was found to be permanently inert. The task counter fixed the immediate bleeding, but it was always a proxy — 5 tasks ≠ N tokens, and Opus-primary sessions burn context faster than Sonnet-primary sessions for the same task count. M34 replaces the proxy with real measurement via the Anthropic `count_tokens` API, re-exposed through a PostToolUse hook.
+
+### Added
+
+- **`scripts/gsd-t-context-meter.js`** — PostToolUse hook that measures the active Claude Code session's context window after every tool call. Writes a snapshot to `.gsd-t/.context-meter-state.json` (`{pct, consumed, limit, timestamp, model}`) and, when `pct >= warn_threshold`, injects `additionalContext` into the Claude Code response so the orchestrator sees real burn in real time. Fails open (silent no-op) when `ANTHROPIC_API_KEY` is missing or the API is unreachable — never blocks the user's session.
+- **`scripts/context-meter/`** — helper modules: `parser.js` (extract recent turns from transcript), `client.js` (count_tokens API wrapper with retry), `threshold.js` (warn/degrade/conserve/stop bands), `test-injector.js` (deterministic fixtures for unit tests).
+- **`bin/context-meter-config.cjs`** — config loader with defaults and schema validation.
+- **`templates/context-meter-config.json`** — default config (thresholds: warn 0.65, degrade 0.75, conserve 0.85, stop 0.92; staleness window 5 min).
+- **`.gsd-t/contracts/context-meter-contract.md`** v1.0.0 ACTIVE — hook I/O contract, state file schema, threshold semantics, fail-open guarantees.
+- **`.gsd-t/contracts/token-budget-contract.md`** v2.0.0 ACTIVE — rewritten around real measurement; public `getSessionStatus()` API surface preserved but semantics now reflect actual context % instead of task count.
+- **Installer extensions (`bin/gsd-t.js`)**:
+  - `install`/`update` registers `scripts/gsd-t-context-meter.js` as a PostToolUse hook in `~/.claude/settings.json` (idempotent).
+  - First-run prompt for `ANTHROPIC_API_KEY` (skippable — doctor will later fail-red if unset).
+  - `doctor` adds hard-gate checks for API key presence, hook registration, config file, and a dry-run smoke test of the hook entry point.
+  - `status` displays real context % read from `.gsd-t/.context-meter-state.json` (falls back to heuristic when state is missing/stale).
+- **Test coverage**: `scripts/gsd-t-context-meter.e2e.test.js` (90 tests — parser, client, threshold, hook entry, injection); `test/token-budget.test.js` fully rewritten around real measurement; `test/installer-m34.test.js` covers hook install, API key prompt, doctor gate, status line; **941/941 total tests green**.
+
+### Changed
+
+- **`bin/token-budget.js`** — `getSessionStatus()` now reads `.gsd-t/.context-meter-state.json` (with a 5-minute staleness window) and falls back to a heuristic based on `.gsd-t/token-log.md` row count when state is unavailable. Graduated degradation (`warn`/`downgrade`/`conserve`/`stop`) fires on real context % instead of task count. Public API unchanged so `bin/orchestrator.js` and every command that calls it keeps working.
+- **`bin/orchestrator.js`** — task-budget gate now calls `token-budget.getSessionStatus()` for the real signal; checkpoint-and-stop behavior preserved.
+- **Command files** (`gsd-t-execute.md`, `gsd-t-wave.md`, `gsd-t-quick.md`, `gsd-t-integrate.md`, `gsd-t-debug.md`) — every `node bin/task-counter.cjs …` invocation replaced with a `CTX_PCT` bash shim that sources the context meter state file. Observability logging updated.
+- **Token log schema** — `Tasks-Since-Reset` column renamed to `Ctx%`. All command files and templates updated.
+- **Documentation ripple**:
+  - `README.md` — Context Meter feature bullet + full "Context Meter Setup" section.
+  - `docs/GSD-T-README.md` — Configuration → Context Meter subsection with data-flow, threshold bands, upgrade notes.
+  - `docs/architecture.md` — Context Meter Architecture with full data-flow diagram.
+  - `docs/infrastructure.md` — Context Meter Setup section with API key instructions, doctor verification, threshold table, upgrade migration.
+  - `docs/methodology.md` — "Context Awareness: From Proxy to Real Measurement" narrative explaining why proxies failed and how real measurement restores gate integrity.
+  - `docs/requirements.md` — M34 REQ-063 through REQ-068 traceability table with functional and non-functional requirements.
+  - `templates/CLAUDE-global.md` — Context Meter Gate subsection + historical note about the task-counter era.
+  - `templates/CLAUDE-project.md` — new Context Meter section for per-project setup.
+
+### Removed
+
+- **`bin/task-counter.cjs`** — deleted. The entire proxy gate retires. `.gsd-t/.task-counter`, `.gsd-t/task-counter-config.json`, and the `Tasks-Since-Reset` column are no longer read by any code.
+- All `CLAUDE_CONTEXT_TOKENS_USED` / `CLAUDE_CONTEXT_TOKENS_MAX` references across `commands/`, `bin/`, `scripts/`, and `templates/` — the last vestiges of the original broken env-var self-check.
+
+### Migration
+
+- **`gsd-t update-all`** runs a one-shot task-counter retirement migration: deletes `bin/task-counter.cjs`, `.gsd-t/.task-counter`, `.gsd-t/task-counter-config.json` from each registered project; writes `.gsd-t/.task-counter-retired-v1` marker so the migration is idempotent. Projects that had the proxy gate wired in come out the other side on the real context meter with zero manual intervention.
+- **Users MUST set `ANTHROPIC_API_KEY`** in their shell environment (or accept the install-time prompt) for the context meter to produce real readings. Without the key, the hook fails open and `doctor` reports RED on the API key check — the gate falls back to the `token-log.md` row-count heuristic, which is safer than the old env-var vaporware but less accurate than real measurement.
+- Both `install` and `update-all` register the hook in `~/.claude/settings.json` and copy the default config template. Existing `.claude/settings.json` is preserved; only the hook entry is appended.
+
+### Propagation
+
+After publishing, run `/user:gsd-t-version-update-all` to propagate M34 (hook, config, installer, rewritten token-budget, command file updates, retirement migration) to every registered GSD-T project in a single sweep.
+
+## [2.74.13] - 2026-04-14
+
+### Fixed — v2.74.12 task-counter distribution gap (P0)
+
+**Root cause**: v2.74.12 added `bin/task-counter.cjs` as the deterministic context-burn gate and wired every command file to call `node bin/task-counter.cjs …`, but the installer's `PROJECT_BIN_TOOLS` list (`bin/gsd-t.js:1562`) was never updated to include it. Every downstream project ran command files that referenced a file the installer never copied. In every GSD-T project, `node bin/task-counter.cjs status|should-stop|reset|increment` threw "Cannot find module" — swallowed by `2>/dev/null` — and the orchestrator silently continued with no gate. Confirmed in bee-poc: `reassign-display` 6/6 + `reassign-candidates` 2/9 executed across ~30 min while `task-counter status` stayed `{"count":0}` the entire run and `token-log.md` got zero new rows.
+
+**Additionally**: `doInit()` (`bin/gsd-t.js:1095`) never called `copyBinToolsToProject` at all, so brand-new projects created with `gsd-t init` were born with no bin tools until the user manually ran `update`.
+
+**Fix**:
+- **`bin/gsd-t.js`** — `PROJECT_BIN_TOOLS` now includes `task-counter.cjs`. One-line change at `bin/gsd-t.js:1562`.
+- **`bin/gsd-t.js`** — `doInit()` now calls `copyBinToolsToProject(projectDir, projectName)` after `initGsdtDir`, so newly-initialized projects ship bin tools immediately.
+
+v2.74.12's entire two-layer fix (task-count gate + extracted prompts) is correct — it just needed one line to actually distribute the counter script. Running `/user:gsd-t-version-update-all` after publishing this version will propagate `task-counter.cjs` to every registered project.
+
 ## [2.74.12] - 2026-04-14
 
 ### Fixed — Context-Burn Regression (P0, affects every GSD-T project)

package/README.md

@@ -14,7 +14,13 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 **Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
 **Self-Calibrating QA** — `qa-calibrator.js` tracks QA miss-rates across milestones, detects weak-spot categories (error paths, boundaries, state transitions), and automatically injects targeted guidance into QA subagent prompts. Projects on the same stack share miss-rate data for faster calibration.
-**Token-Aware Orchestration** — `token-budget.js` tracks session token consumption and applies graduated degradation: downgrade model assignments when approaching limits, checkpoint and skip non-essential operations to conserve budget, and halt cleanly with a resume instruction at the ceiling. Wave and execute phases check budget before each subagent spawn.
+**Runway-Protected Execution (M35, v2.76.10)** — three-band token budget (`normal` < 70%, `warn` 70–85%, `stop` ≥ 85%) with **zero silent quality degradation**. No model downgrades, no phase skips under pressure. Instead:
+- **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
+- **Pre-flight runway estimator** — `bin/runway-estimator.js` reads per-spawn token telemetry and projects whether a long-running command would cross 85%. If yes, the run is refused *before burning any tokens*.
+- **Headless auto-spawn on refusal** — `bin/headless-auto-spawn.js` detaches a child process to continue the work in a fresh context. The interactive session never sees a `/clear` prompt.
+- **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn. Feeds the runway estimator and the retrospective optimization backlog.
+- **Optimization backlog** — `bin/token-optimizer.js` runs at `complete-milestone` and appends model-tier recalibration recommendations (`demote`, `escalate`, `runway-tune`, `investigate`) to `.gsd-t/optimization-backlog.md`. **Never auto-applies.** User promotes via `/user:gsd-t-optimization-apply {ID}` or dismisses via `/user:gsd-t-optimization-reject {ID} [--reason "..."]` with a 5-milestone cooldown.
+**Context Meter (M34)** — real-time context window measurement via the Anthropic `count_tokens` API. A PostToolUse hook streams the current transcript to `count_tokens`, writes the exact input-token count and threshold band to `.gsd-t/.context-meter-state.json`, and `token-budget.getSessionStatus()` reads that state file as the authoritative context-burn signal. Replaces the v2.74.12 task-counter proxy. Requires an `ANTHROPIC_API_KEY` — `gsd-t doctor` hard-gates on it. See the Context Meter Setup section below.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
 **Design Verification Agent** — after QA passes on design-to-code projects, a dedicated verification agent opens a browser with both the built frontend AND the original design (Figma page, design image, or MCP screenshot) side-by-side for direct visual comparison. Produces a structured element-by-element comparison table (30+ rows) with specific design values vs. implementation values and MATCH/DEVIATION verdicts. An artifact gate enforces that the comparison table exists — missing it blocks completion. Separation of concerns: coding agents code, verification agents verify. Wired into execute (Step 5.25) and quick (Step 5.25). Only fires when `.gsd-t/contracts/design-contract.md` exists — non-design projects are unaffected.
@@ -305,6 +311,70 @@ your-project/
 
 ---
 
+## Context Meter Setup (M34 — v2.75.10+)
+
+The Context Meter replaces the v2.74.12 task-counter proxy with real context-window measurement via the Anthropic `count_tokens` API. This is the authoritative signal for session-stop gates in `gsd-t-execute`, `gsd-t-wave`, `gsd-t-quick`, `gsd-t-integrate`, and `gsd-t-debug`.
+
+### 1. Set your API key
+
+Create a key at [console.anthropic.com](https://console.anthropic.com) (free tier is sufficient — `count_tokens` calls are inexpensive) and export it in your shell profile:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+The env var name is configurable in `.gsd-t/context-meter-config.json` (default: `ANTHROPIC_API_KEY`).
+
+### 2. Verify with `gsd-t doctor`
+
+```bash
+npx @tekyzinc/gsd-t doctor
+```
+
+Doctor checks:
+- `ANTHROPIC_API_KEY` is set (RED if missing)
+- PostToolUse hook is registered in `~/.claude/settings.json`
+- `scripts/gsd-t-context-meter.js` exists in the project
+- `.gsd-t/context-meter-config.json` parses cleanly
+- A live `count_tokens` dry-run succeeds (RED on 401/403/network failure)
+
+### 3. Adjust thresholds (optional)
+
+Edit `.gsd-t/context-meter-config.json`:
+
+```json
+{
+  "enabled": true,
+  "apiKeyEnvVar": "ANTHROPIC_API_KEY",
+  "modelWindowSize": 200000,
+  "thresholdPct": 85,
+  "checkFrequency": 1
+}
+```
+
+- `modelWindowSize` — total context window (200K for Opus/Sonnet)
+- `thresholdPct` — percentage at which the orchestrator halts (85% = stop band; 70% = warn band — cue for explicit pause/resume; no silent degradation)
+- `checkFrequency` — run `count_tokens` every N tool calls (1 = every call; higher = cheaper + slightly delayed signal)
+
+### 4. Live status
+
+```bash
+npx @tekyzinc/gsd-t status
+```
+
+Displays a Context line with `{pct}% of {window} tokens ({band}) — last check {time ago}`. Missing state file shows `N/A (meter hook not run this session)`.
+
+### Upgrading from pre-M34
+
+Running `gsd-t update-all` handles the migration automatically:
+- Copies the new hook script, runtime files, config template, and `context-meter-config.cjs` loader into every registered project
+- Runs a one-time task-counter retirement — deletes `bin/task-counter.cjs`, `.gsd-t/task-counter-config.json`, `.gsd-t/.task-counter-state.json`, and the `.gsd-t/.task-counter` state file
+- Writes `.gsd-t/.task-counter-retired-v1` marker (subsequent runs are no-op)
+
+After upgrading, **you must set `ANTHROPIC_API_KEY`** — `gsd-t doctor` will fail otherwise.
+
+---
+
 ## Enabling Agent Teams
 
 ```json

package/bin/advisor-integration.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Advisor Integration — convention-based /advisor escalation fallback
+ *
+ * Per `.gsd-t/M35-advisor-findings.md`: Claude Code's native /advisor tool has
+ * NO programmable API at subagent scope. This module exists as a seam so that
+ * when Anthropic ships a programmable advisor endpoint, the function body can
+ * be rewritten without touching callers.
+ *
+ * Current (M35 v1.0.0) behavior:
+ *   - invokeAdvisor() always returns {available: false, guidance: null, loggedMiss: true}
+ *   - The call appends a single `missed_escalation` record to
+ *     `.gsd-t/token-log.md` so that token-telemetry's aggregate view can
+ *     report how many escalation points occurred without a programmable path
+ *   - Graceful degradation: if the log write fails, return loggedMiss: false
+ *     but never throw — callers proceed at their assigned model either way
+ *
+ * Contract: `.gsd-t/contracts/model-selection-contract.md` v1.0.0 (M35 T4)
+ * Zero external dependencies.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const TOKEN_LOG_RELATIVE = ".gsd-t/token-log.md";
+
+/**
+ * Invoke the /advisor escalation hook.
+ *
+ * @param {object} args
+ * @param {string} args.question    — the escalation question being asked
+ * @param {object} [args.context]   — optional structured context (phase, domain, task)
+ * @param {string} [args.projectDir] — project root; defaults to cwd
+ * @returns {{available: boolean, guidance: string|null, loggedMiss: boolean}}
+ */
+function invokeAdvisor(args) {
+  const { question, context, projectDir } = args || {};
+  const dir = projectDir || process.cwd();
+
+  // There is no programmable path to try. Record the miss and return.
+  const loggedMiss = logMissedEscalation(dir, question, context);
+
+  return {
+    available: false,
+    guidance: null,
+    loggedMiss,
+  };
+}
+
+/**
+ * Append a single missed-escalation record to `.gsd-t/token-log.md`.
+ * Returns true on successful append, false on any filesystem error
+ * (non-throwing — this is a best-effort audit trail).
+ *
+ * @param {string} projectDir
+ * @param {string} [question]
+ * @param {object} [context]
+ * @returns {boolean}
+ */
+function logMissedEscalation(projectDir, question, context) {
+  try {
+    const logPath = path.join(projectDir, TOKEN_LOG_RELATIVE);
+    const logDir = path.dirname(logPath);
+    if (!fs.existsSync(logDir)) return false;
+
+    const ts = new Date().toISOString();
+    const q = sanitizeOneLine(question || "(no question provided)");
+    const ctxPhase = (context && context.phase) ? sanitizeOneLine(String(context.phase)) : "";
+    const ctxDomain = (context && context.domain) ? sanitizeOneLine(String(context.domain)) : "";
+    const ctxTask = (context && context.task) ? sanitizeOneLine(String(context.task)) : "";
+
+    const line = `<!-- missed_escalation ${ts} phase=${ctxPhase} domain=${ctxDomain} task=${ctxTask} q="${q}" -->\n`;
+
+    fs.appendFileSync(logPath, line, "utf8");
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Strip newlines and trim whitespace so the record stays on one line.
+ */
+function sanitizeOneLine(s) {
+  return String(s).replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+module.exports = {
+  invokeAdvisor,
+  logMissedEscalation,
+  TOKEN_LOG_RELATIVE,
+};

package/bin/check-headless-sessions.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Check Headless Sessions — Read-back banner helper
+ *
+ * Scans .gsd-t/headless-sessions/ for completed sessions that have not yet
+ * been surfaced to the user. Consumed by `gsd-t-resume` and `gsd-t-status`
+ * to print a "Headless runs since you left" banner at the start of their
+ * output. After surfacing, marks the session file with `surfaced: true`
+ * so the banner never re-appears for the same session.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
+ * Consumers: commands/gsd-t-resume.md, commands/gsd-t-status.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
+
+module.exports = {
+  checkCompletedSessions,
+  markSurfaced,
+  formatBanner,
+  printBannerIfAny,
+};
+
+/**
+ * @param {string} [projectDir]
+ * @returns {Array<object>} unsurfaced completed sessions, oldest first
+ */
+function checkCompletedSessions(projectDir) {
+  const dir = path.join(projectDir || process.cwd(), SESSIONS_DIR_REL);
+  if (!fs.existsSync(dir)) return [];
+
+  const entries = [];
+  let files;
+  try {
+    files = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    if (f.endsWith("-context.json")) continue;
+    const fp = path.join(dir, f);
+    try {
+      const s = JSON.parse(fs.readFileSync(fp, "utf8"));
+      if (s && s.status === "completed" && s.surfaced !== true) {
+        entries.push(s);
+      }
+    } catch (_) {
+      // skip malformed session files silently
+    }
+  }
+
+  entries.sort((a, b) => {
+    const ta = a.endTimestamp || a.startTimestamp || "";
+    const tb = b.endTimestamp || b.startTimestamp || "";
+    return ta.localeCompare(tb);
+  });
+
+  return entries;
+}
+
+/**
+ * Mark a session as surfaced so the banner won't re-appear for it.
+ * @param {string} projectDir
+ * @param {string} id
+ */
+function markSurfaced(projectDir, id) {
+  const fp = path.join(projectDir || process.cwd(), SESSIONS_DIR_REL, `${id}.json`);
+  if (!fs.existsSync(fp)) return;
+  try {
+    const s = JSON.parse(fs.readFileSync(fp, "utf8"));
+    s.surfaced = true;
+    fs.writeFileSync(fp, JSON.stringify(s, null, 2) + "\n");
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+/**
+ * Format a human-readable banner for the given sessions. Does not print.
+ * @param {Array<object>} sessions
+ * @returns {string}
+ */
+function formatBanner(sessions) {
+  if (!sessions || sessions.length === 0) return "";
+  const lines = [];
+  lines.push("## Headless runs since you left");
+  lines.push("");
+  for (const s of sessions) {
+    const duration = computeDurationLabel(s.startTimestamp, s.endTimestamp);
+    const outcome = s.exitCode === 0 ? "success" : `exit ${s.exitCode}`;
+    const cmd = s.command || "(unknown)";
+    lines.push(`- **${s.id}** — ${cmd} — ${duration} — ${outcome}`);
+    if (s.logPath) lines.push(`  Log: \`${s.logPath}\``);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Convenience wrapper: check, print to stdout if any, mark surfaced.
+ * Returns number of sessions surfaced.
+ */
+function printBannerIfAny(projectDir) {
+  const sessions = checkCompletedSessions(projectDir);
+  if (sessions.length === 0) return 0;
+  process.stdout.write(formatBanner(sessions) + "\n");
+  for (const s of sessions) markSurfaced(projectDir, s.id);
+  return sessions.length;
+}
+
+function computeDurationLabel(startIso, endIso) {
+  if (!startIso || !endIso) return "unknown duration";
+  const start = Date.parse(startIso);
+  const end = Date.parse(endIso);
+  if (!isFinite(start) || !isFinite(end) || end < start) return "unknown duration";
+  const secs = Math.round((end - start) / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  const rem = secs % 60;
+  if (mins < 60) return `${mins}m ${rem}s`;
+  const hrs = Math.floor(mins / 60);
+  const remMins = mins % 60;
+  return `${hrs}h ${remMins}m`;
+}
+
+// ── CLI entry point ─────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const projectDir = process.argv[2] || process.cwd();
+  const n = printBannerIfAny(projectDir);
+  process.exit(n > 0 ? 0 : 0);
+}

package/bin/context-meter-config.cjs

@@ -0,0 +1,101 @@
+/**
+ * Context Meter config loader (M34).
+ *
+ * Reads .gsd-t/context-meter-config.json, merges over defaults, validates,
+ * and returns the resolved config. Missing file → defaults. Unknown schema
+ * version or API-key leak → throws with a clear message.
+ *
+ * See .gsd-t/contracts/context-meter-contract.md for the schema, validation
+ * rules, and the API-key-never-stored invariant.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULTS = Object.freeze({
+  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,
+});
+
+const SUPPORTED_VERSION = 1;
+const API_KEY_FIELD_RE = /api.?key/i;
+const HEX_LOOKALIKE_RE = /^[a-zA-Z0-9_-]{64,}$/;
+
+function loadConfig(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const configPath = path.join(root, ".gsd-t", "context-meter-config.json");
+
+  let userConfig = {};
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, "utf8");
+    try {
+      userConfig = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(
+        `context-meter-config: invalid JSON in ${configPath}: ${e.message}`
+      );
+    }
+    if (!userConfig || typeof userConfig !== "object" || Array.isArray(userConfig)) {
+      throw new Error(`context-meter-config: ${configPath} must contain a JSON object`);
+    }
+  }
+
+  validateNoKeyLeak(userConfig);
+
+  if (userConfig.version !== undefined && userConfig.version !== SUPPORTED_VERSION) {
+    throw new Error(
+      `context-meter-config: unsupported schema version ${userConfig.version} ` +
+        `(expected ${SUPPORTED_VERSION}). See .gsd-t/contracts/context-meter-contract.md#breaking-changes for migration.`
+    );
+  }
+
+  const merged = { ...DEFAULTS, ...userConfig, version: SUPPORTED_VERSION };
+  validateRanges(merged);
+  return merged;
+}
+
+function validateNoKeyLeak(obj) {
+  for (const key of Object.keys(obj)) {
+    if (key === "apiKeyEnvVar") continue;
+    if (API_KEY_FIELD_RE.test(key)) {
+      throw new Error(
+        `context-meter-config: field "${key}" looks like an API key storage field. ` +
+          `API keys must only be read from the env var named in apiKeyEnvVar.`
+      );
+    }
+    const val = obj[key];
+    if (typeof val === "string" && val.length > 100 && HEX_LOOKALIKE_RE.test(val)) {
+      throw new Error(
+        `context-meter-config: field "${key}" contains a long token-like string. ` +
+          `Do not store API keys in config — use apiKeyEnvVar to name the env var.`
+      );
+    }
+  }
+}
+
+function validateRanges(c) {
+  const assert = (cond, msg) => { if (!cond) throw new Error(`context-meter-config: ${msg}`); };
+
+  assert(Number.isFinite(c.thresholdPct) && c.thresholdPct > 0 && c.thresholdPct < 100,
+    `thresholdPct must be a number in (0, 100), got ${c.thresholdPct}`);
+  assert(Number.isInteger(c.modelWindowSize) && c.modelWindowSize > 0,
+    `modelWindowSize must be a positive integer, got ${c.modelWindowSize}`);
+  assert(Number.isInteger(c.checkFrequency) && c.checkFrequency >= 1,
+    `checkFrequency must be an integer >= 1, got ${c.checkFrequency}`);
+  assert(typeof c.apiKeyEnvVar === "string" && c.apiKeyEnvVar.length > 0,
+    `apiKeyEnvVar must be a non-empty string, got ${JSON.stringify(c.apiKeyEnvVar)}`);
+  assert(typeof c.statePath === "string" && c.statePath.length > 0,
+    `statePath must be a non-empty string`);
+  assert(typeof c.logPath === "string" && c.logPath.length > 0,
+    `logPath must be a non-empty string`);
+  assert(Number.isInteger(c.timeoutMs) && c.timeoutMs > 0,
+    `timeoutMs must be a positive integer, got ${c.timeoutMs}`);
+}
+
+module.exports = { loadConfig, DEFAULTS };