@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/commands/gsd-t-verify.md

@@ -2,6 +2,13 @@
 
 You are the lead agent coordinating verification of the completed work. Each verification dimension should be thorough and independent.
 
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `opus` (`selectModel({phase: "verify"})`) — milestone verification is the final quality gate before completion. High stakes.
+- **Escalation**: already at opus; there is no stronger tier. Verify judgments are always made at full quality.
+
 ## Step 1: Load State
 
 Read:
@@ -161,9 +168,9 @@ Before spawning — run via Bash:
 `T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
 Spawn a Task subagent to run the full test suite and contract audit.
 After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-verify | Step 4 | haiku | {DURATION}s | test audit + contract review | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-verify | Step 4 | haiku | {DURATION}s | test audit + contract review | {CTX_PCT} |`
 Collect all reports, synthesize, create remediation plan.
 ```
 
@@ -367,9 +374,9 @@ Report back: one-line status summary."
 ```
 
 After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
 Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-verify | Step 8 | sonnet | {DURATION}s | auto-complete-milestone | | | {COUNTER} |`
+`| {DT_START} | {DT_END} | gsd-t-verify | Step 8 | sonnet | {DURATION}s | auto-complete-milestone | | | {CTX_PCT} |`
 
 3. Verify subagent result: Read `.gsd-t/progress.md` — confirm status is COMPLETED. If not, report the failure.
 

package/commands/gsd-t-visualize.md

@@ -21,14 +21,10 @@ Skip Step 0 — you are already the subagent."
 **OBSERVABILITY LOGGING — after subagent returns:**
 
 Run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
 
-Compute tokens:
-- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
-- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
-
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-visualize | Step 0 | sonnet | {DURATION}s | dashboard launched | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-visualize | Step 0 | sonnet | {DURATION}s | dashboard launched | {CTX_PCT} |`
 
 Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
 

package/commands/gsd-t-wave.md

@@ -2,15 +2,77 @@
 
 You are the wave orchestrator. You do NOT execute phases yourself. Instead, you spawn an **independent agent for each phase**, giving each a fresh context window. This eliminates context accumulation across phases and prevents mid-wave compaction.
 
-## Step 0: Reset Phase-Count Gate (MANDATORY — first thing in a fresh session)
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0. Each phase spawn picks its tier from `bin/model-selector.js` — the wave orchestrator itself is routine coordination work.
+
+- **Wave orchestrator (this agent)**: `sonnet` (`selectModel({phase: "wave"})`).
+- **Per-phase spawns**: each phase agent selects its own tier — `partition` → opus, `discuss` → opus, `plan` → sonnet, `execute` → sonnet (with mechanical haiku subroutines and opus Red Team), `test-sync` → sonnet, `integrate` → sonnet, `verify` → opus, `doc-ripple` → sonnet. The phase command files carry their own Model Assignment blocks.
+- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` at declared high-stakes sub-decisions (see `.gsd-t/M35-advisor-findings.md`). Never silently downgrade the model or skip phases under context pressure — M35 removed that behavior.
+
+## Per-Spawn Token Bracket (MANDATORY — wrap EVERY phase agent spawn)
+
+Per `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0. Every phase agent spawn in the Phase Agent Spawn Pattern below **MUST** be wrapped in this token bracket so `.gsd-t/token-metrics.jsonl` gets one record per spawn. This is additive — the existing OBSERVABILITY LOGGING blocks in each spawn site are preserved unmodified alongside this bracket.
+
+**Before each phase spawn — read starting context tokens:**
+
+```bash
+T0_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
+T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+```
+
+**After each phase spawn — record the bracket:**
+
+```bash
+T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
+T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-wave',phase:'${PHASE:-}',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+```
+
+The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist — token-log.md is human-readable with context percentage, token-metrics.jsonl is machine-readable with the full 18-field schema for `gsd-t metrics --tokens/--halts/--context-window` aggregation.
+
+## Step 0: Runway Check (MANDATORY — before any other work in a fresh session)
+
+Count the wave's total task count (sum of atomic tasks across domains in the current wave). Then run via Bash:
+
+```bash
+node -e "
+const r = require('./bin/runway-estimator.js').estimateRunway({
+  command: 'gsd-t-wave',
+  domain_type: '',
+  remaining_tasks: {N},
+  projectDir: '.'
+});
+console.log(JSON.stringify(r, null, 2));
+if (!r.can_start) {
+  console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
+  console.log('Auto-spawning headless to continue in a fresh context.');
+  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+    command: 'gsd-t-wave', args: [], continue_from: '.'
+  });
+  console.log('Session ID: ' + s.id);
+  console.log('Status: tail ' + s.logPath);
+  console.log('');
+  console.log('Your interactive session remains idle — you can use it for other work.');
+  console.log('You will be notified when the headless run completes.');
+  process.exit(0);
+}
+"
+```
+
+If `can_start === false`, the headless continuation has already been spawned and the interactive session must stop here. Do NOT proceed to Step 0.1.
+
+**Contract**: `.gsd-t/contracts/runway-estimator-contract.md` v1.0.0; stop threshold (85%) mirrors `.gsd-t/contracts/token-budget-contract.md` v3.0.0.
+
+## Step 0.1: Verify Context Gate Readiness (MANDATORY — first thing in a fresh session)
 
 Run via Bash:
 
 ```bash
-node bin/task-counter.cjs reset
+node -e "const tb = require('./bin/token-budget.js'); const s = tb.getSessionStatus('.'); console.log(JSON.stringify(s));"
 ```
 
-This clears `.gsd-t/.task-counter` so the new wave session starts at 0. The gate logic is in the Phase Agent Spawn Pattern below — it forces a /clear-and-resume after N phase spawns to prevent the wave orchestrator from itself running out of context. Default N=5, override per-project via `.gsd-t/task-counter-config.json` (`{"limit":8}`) or env `GSD_T_TASK_LIMIT=8`.
+This calls `getSessionStatus()` (v2.0.0) which reads `.gsd-t/.context-meter-state.json` produced by the Context Meter PostToolUse hook. The returned `threshold` drives the gate logic in the Phase Agent Spawn Pattern below — it enforces the three-band stop boundary (85%) so the wave orchestrator itself never runs out of context mid-wave. When the state file is absent or stale, the call falls back to a historical heuristic from `.gsd-t/token-log.md`. Band boundaries and `modelWindowSize` are configured in `.gsd-t/context-meter-config.json` and `bin/token-budget.js` (THRESHOLDS constant).
 
 ## Step 1: Load State (Lightweight)
 
@@ -96,10 +158,10 @@ If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 Run via Bash:
 `node -e "const tb = require('./bin/token-budget.js'); const s = tb.getSessionStatus('.'); process.stdout.write(s.threshold);" 2>/dev/null`
 
+Three-band model per `token-budget-contract.md` v3.0.0 (never silently degrade quality):
 - `normal` or file missing → proceed normally
-- `downgrade` → apply model overrides from `getDegradationActions()` in the phase agent prompt
-- `conserve` → checkpoint progress, skip non-essential phases (test-sync if code unchanged, discuss if already done)
-- `stop` → checkpoint all progress and output: "Token budget exhausted — wave paused. Resume after session reset." then halt
+- `warn` (≥70%) → log the warning to `.gsd-t/token-log.md` and proceed at full quality; **do NOT downgrade models or skip phases** — M35 removed that behavior intentionally
+- `stop` (≥85%) → checkpoint all progress and output: "Wave orchestrator context gate reached ({pct}%). Progress saved. Resume after session reset." then halt
 
 **OBSERVABILITY LOGGING (MANDATORY) — repeat for every phase spawn:**
 Before spawning — run via Bash:
@@ -126,29 +188,31 @@ Task agent (subagent_type: "general-purpose", mode: "bypassPermissions"):
 After phase agent returns — run via Bash:
 `T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
 
-**Wave Orchestrator Phase-Count Gate (MANDATORY) — replaces the broken context-percent check from v2.74.x:**
+**Wave Orchestrator Context Gate (MANDATORY) — real-count measurement via Context Meter state file:**
 
 Run via Bash AFTER each phase agent returns:
 
 ```bash
-node bin/task-counter.cjs increment phase
+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);"
 ```
 
-Read the JSON status the command prints. If `should_stop` is `true` (or the command's exit code is `10`):
-1. Save checkpoint to `.gsd-t/progress.md` — record which phases are complete, which remain.
-2. Output exactly: `⏸️ Wave orchestrator phase-count gate reached ({count}/{limit} phases in this session). Progress saved. Run /clear then /user:gsd-t-wave to continue from the next phase.`
-3. **STOP the wave loop.** Do NOT spawn the next phase agent. The next session resumes from saved state.
+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):
+- `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.
 
-The wave orchestrator shares the same `bin/task-counter.cjs` counter as the execute orchestrator. Each phase spawn (PARTITION, DISCUSS, PLAN, IMPACT, EXECUTE, TEST-SYNC, INTEGRATE, VERIFY+COMPLETE, DOC-RIPPLE) increments the counter by 1. With the default limit of 5, a wave will run at most 5 phase agents per session before forcing a /clear-and-resume — typically two sessions per full wave. Override via `.gsd-t/task-counter-config.json` (`{"limit":8}`) or `GSD_T_TASK_LIMIT=8`.
+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.
 
-The previous version of this gate relied on `CLAUDE_CONTEXT_TOKENS_USED`/`_MAX` env vars which Claude Code does not export — that check was inert and let the orchestrator drain context until forced compaction. The deterministic on-disk counter has the same intent (force a /clear before context runs out) but actually works.
+The previous v1.x version relied on an environment-variable-based context check which Claude Code never populated; v2.74.12 stood in a proxy task counter; v2.0.0 (M34) retires both and uses the real count_tokens measurement.
 
-**On wave entry**, the wave orchestrator runs `node bin/task-counter.cjs reset` exactly once (see Step 0 — it is the very first thing the wave does in a fresh session). The reset is the SIGNAL that this is a clean post-/clear session.
+**On wave entry**, Step 0 runs `getSessionStatus()` once for a readiness confirmation. No counter reset is needed — `/clear` plus the next tool call will cause the Context Meter hook to refresh the state file with the new session's starting `input_tokens`.
 
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-wave | {PHASE} | sonnet | {DURATION}s | phase: {PHASE} | | | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-wave | {PHASE} | sonnet | {DURATION}s | phase: {PHASE} | | | {CTX_PCT} |`
 
-Where `{COUNTER}` is the `count` field from the JSON the increment command just printed.
+Where `{CTX_PCT}` is the `pct` field from the JSON the getSessionStatus command just printed.
 
 ### Phase Sequence
 

package/docs/GSD-T-README.md

@@ -114,6 +114,9 @@ GSD-T reads all state files and tells you exactly where you left off.
 
 | Command | Purpose | Auto |
 |---------|---------|------|
+| `/user:gsd-t-unattended` | Launch detached supervisor — runs active milestone to completion with zero human intervention | Manual |
+| `/user:gsd-t-unattended-watch` | Watch tick — fires every 270s via ScheduleWakeup, reports supervisor status | Auto |
+| `/user:gsd-t-unattended-stop` | Touch stop sentinel — supervisor halts after current worker finishes | Manual |
 | `/user:gsd-t-wave` | Full cycle, auto-advances all phases | Manual |
 | `/user:gsd-t-status` | Cross-domain progress view with token breakdown, global ELO and cross-project rankings | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
@@ -286,6 +289,20 @@ Drop a `.md` file into `templates/stacks/` to add a new stack. Files prefixed wi
 
 ---
 
+## Unattended Execution (M36)
+
+Run the active milestone to completion over hours or days with zero human intervention. The unattended supervisor is an OS-level process that spawns `claude -p` workers in a relay — each worker runs in a fresh context window, completing one round of wave tasks before handing off to the next. The supervisor survives `/clear`, terminal close, and sleep/wake cycles (macOS/Linux; see `docs/unattended-windows-caveats.md` for Windows).
+
+**Relay model**: Each iteration spawns a fresh `claude -p` session with a compact prompt derived from `.gsd-t/progress.md` state. The supervisor waits for the worker to exit, records the exit code in `state.json`, runs safety checks (gutter detection, blocker sentinel scan), and spawns the next worker. Workers never overlap. Context rot is impossible — each worker starts clean.
+
+**Watch loop**: `/user:gsd-t-unattended` starts an in-session ScheduleWakeup loop that ticks every 270 seconds. Each tick reads `state.json` and `supervisor.pid` to render a live progress block. When the supervisor reaches a terminal state (`done`, `failed`, `stopped`), the watch loop stops rescheduling and prints a final summary. A `/clear` + `/user:gsd-t-resume` transparently re-attaches: the resume command checks for a live `supervisor.pid` and re-starts the watch loop automatically.
+
+**Safety rails**: Branch protection (refuses to run on `main`/`master`/`release/*` by default), dirty-tree check (whitelists GSD-T runtime files), per-iteration gutter detection (repeated error patterns, file thrash, no-progress stall), wall-clock and iteration caps, and a blocker sentinel that halts on unrecoverable worker errors.
+
+**Contract**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 is the authoritative reference for the state file schema, exit codes, CLI surface, and platform matrix.
+
+---
+
 ## Headless Mode
 
 Run GSD-T non-interactively in CI/CD pipelines or automated workflows.
@@ -423,6 +440,58 @@ Recommended `.gsd-t/config.json`:
 }
 ```
 
+### Context Meter (M34)
+
+The Context Meter is a PostToolUse hook that runs after every tool call, streams the current Claude Code transcript to the Anthropic `count_tokens` API, and writes the exact input-token count and threshold band to `.gsd-t/.context-meter-state.json`. The GSD-T orchestrator (`gsd-t-execute`, `gsd-t-wave`, `gsd-t-quick`, `gsd-t-integrate`, `gsd-t-debug`) reads this state file via `token-budget.getSessionStatus()` as the authoritative context-burn signal — replacing the v2.74.12 task-counter proxy.
+
+Setup:
+
+1. **Export an API key** — `export ANTHROPIC_API_KEY="sk-ant-..."` (free-tier key is sufficient; `count_tokens` is inexpensive).
+2. **Install the hook** — `npx @tekyzinc/gsd-t install` (registers the PostToolUse hook globally) then `npx @tekyzinc/gsd-t init` in each project (copies the hook runtime and config template).
+3. **Verify with doctor** — `npx @tekyzinc/gsd-t doctor` hard-gates on API key presence, hook registration, script existence, config validity, and a live `count_tokens` dry-run.
+4. **Check status** — `npx @tekyzinc/gsd-t status` shows a Context line with `{pct}% of {window} tokens ({band}) — last check {time ago}`.
+
+`.gsd-t/context-meter-config.json` controls the meter:
+
+```json
+{
+  "enabled": true,
+  "apiKeyEnvVar": "ANTHROPIC_API_KEY",
+  "modelWindowSize": 200000,
+  "thresholdPct": 85,
+  "checkFrequency": 1
+}
+```
+
+Threshold bands used by the orchestrator gate (v3.0.0 three-band model as of M35 / v2.76.10):
+
+| Band      | Range       | Orchestrator action                                             |
+|-----------|-------------|-----------------------------------------------------------------|
+| normal    | 0–69%       | Proceed as normal                                               |
+| warn      | 70–84%      | Surface warning; runway estimator refuses if projection crosses |
+| stop      | ≥85%        | Halt cleanly; headless auto-spawn continues in a fresh context  |
+
+**Zero silent quality degradation.** There is no `downgrade` or `conserve` band anymore. When the runway estimator (`bin/runway-estimator.js`) projects a run will cross the 85% stop threshold, the command refuses to start. Instead of printing "please `/clear` and resume," it calls `bin/headless-auto-spawn.js` which detaches a child process to continue the work. The interactive session receives a single ⛔ banner and exits cleanly; the user is never blocked.
+
+**Per-phase model selection** — see `bin/model-selector.js` for the declarative rules table (≥13 phase mappings). Each command file carries a `## Model Assignment` block documenting which phases run on haiku / sonnet / opus. Complexity signals (`cross_module_refactor`, `security_boundary`, `data_loss_risk`, `contract_design`) escalate sonnet→opus at plan time.
+
+**`/advisor` escalation** — mid-phase escalation channel. If `/advisor` is programmable in the runtime, subagents invoke it directly; otherwise, the convention-based fallback (`bin/advisor-integration.js`) appends a `missed_escalation` marker to `.gsd-t/token-log.md` that surfaces at `gsd-t-reflect`. See `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+**`gsd-t metrics` CLI** — `gsd-t metrics --tokens [--by model,command,phase,milestone,domain,domain_type]` aggregates `.gsd-t/token-metrics.jsonl` into a count/total/mean/median/p95 table. `gsd-t metrics --halts` breaks halts down by type (`clean`, `runway-refusal`, `headless-handoff`, `native-compact`). `gsd-t metrics --tokens --context-window` buckets spawns by `context_window_pct_before` in 10% increments. See `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0.
+
+**Optimization apply/reject** — `/user:gsd-t-optimization-apply {ID}` promotes a pending recommendation; `/user:gsd-t-optimization-reject {ID} [--reason "text"]` dismisses it with a 5-milestone cooldown. Both are idempotent. See `commands/gsd-t-optimization-apply.md` and `commands/gsd-t-optimization-reject.md`.
+
+**Observability logging columns** — as of M34, the `.gsd-t/token-log.md` header includes `Ctx%` (the real session-wide context percentage at the time of the subagent spawn) replacing the earlier `Tasks-Since-Reset` column. The old column was a proxy count of how many tasks had run since the last `/clear`; the new column is the actual measurement.
+
+**Upgrading from pre-M34** — `gsd-t update-all` handles the migration automatically:
+- Copies the hook script, runtime files, and config template into every registered project
+- Runs a one-time task-counter retirement (`bin/task-counter.cjs` + `.task-counter*` files deleted, `.gsd-t/.task-counter-retired-v1` marker written)
+- Idempotent on second run
+
+After upgrading, you **must** set `ANTHROPIC_API_KEY` or `gsd-t doctor` will fail.
+
+**Historical note on v2.74.12–13**: between 2026-03 and 2026-04, the orchestrator used `bin/task-counter.cjs` as a proxy — it assumed N tasks ≈ M% context used. That was itself a replacement for an earlier env-var-based check (`CLAUDE_CONTEXT_TOKENS_USED` / `CLAUDE_CONTEXT_TOKENS_MAX`) that never worked because Claude Code does not export those vars. The Context Meter (v2.75.10, M34) is the first version that measures context burn from the authoritative source: the Anthropic API itself.
+
 ---
 
 ## License

package/docs/architecture.md

@@ -68,14 +68,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 
 ### Headless Mode (M23 — complete)
 - **doHeadless(args)**: Dispatch function for the `headless` CLI subcommand.
-- **doHeadlessExec(command, cmdArgs, flags)**: Wraps `claude -p "/user:gsd-t-{command}"` via `execFileSync`. Verifies claude CLI availability, enforces timeout, writes log file if `--log` requested. Returns structured JSON if `--json` flag set.
+- **doHeadlessExec(command, cmdArgs, flags)**: Wraps `claude -p "/gsd-t-{command}"` via `execFileSync`. Verifies claude CLI availability, enforces timeout, writes log file if `--log` requested. Returns structured JSON if `--json` flag set. (M36 Phase 0: prompt form is `/gsd-t-X`, NOT `/user:gsd-t-X` — non-interactive mode rejects the `/user:` namespace prefix.)
 - **parseHeadlessFlags(args)**: Extracts `--json`, `--timeout=N`, `--log` from raw args. Returns `{ flags, positional }`.
-- **buildHeadlessCmd(command, cmdArgs)**: Builds the `/user:gsd-t-{command}` prompt string.
-- **mapHeadlessExitCode(processExitCode, output)**: Maps process exit code + output text patterns to GSD-T exit codes (0–4).
+- **buildHeadlessCmd(command, cmdArgs)**: Builds the bare `/gsd-t-{command}` prompt string. Interactive-mode `/user:` prefix deliberately omitted — see `.gsd-t/M36-spike-findings.md` Spike A.
+- **mapHeadlessExitCode(processExitCode, output)**: Maps process exit code + output text patterns to GSD-T exit codes (0–5).
 - **headlessLogPath(projectDir, timestamp)**: Generates `.gsd-t/headless-{timestamp}.log` path.
 - **doHeadlessQuery(type)**: Dispatches to one of 7 query functions. All pure Node.js file reads, no LLM calls, <100ms.
 - **Query functions** (7): `queryStatus`, `queryDomains`, `queryContracts`, `queryDebt`, `queryContext`, `queryBacklog`, `queryGraph` — each reads corresponding `.gsd-t/` file and returns typed JSON result.
-- **Exit codes**: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error, 4=blocked-needs-human
+- **Exit codes**: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error, 4=blocked-needs-human, 5=command-dispatch-failed (M36 Phase 0 — `claude -p` returned `Unknown command:` for the slash command; caller should treat as a bug not a transient failure)
 - **CI/CD examples**: `docs/ci-examples/github-actions.yml` (GitHub Actions), `docs/ci-examples/gitlab-ci.yml` (GitLab CI)
 
 ### Compaction-Proof Debug Loop (M29 — complete)
@@ -272,6 +272,83 @@ QA runs inline or as Task subagent depending on phase (M10 refactor). Removed fr
 - **Resource limits**: Heartbeat stdin capped at 1MB, HTTP responses capped at 1MB (M5), 5s/8s timeouts, 7-day file cleanup
 - **Wave security**: `bypassPermissions` mode documented with attack surface analysis and mitigations (M5)
 
+## Unattended Supervisor (M36)
+
+The unattended supervisor is a cross-session relay engine that runs an active GSD-T milestone to completion over hours or days without human intervention. It spans the boundary between the interactive Claude session and the OS process layer.
+
+### Component Diagram
+
+```
+Interactive Claude session
+  └── /user:gsd-t-unattended (launch command)
+        ├── Pre-flight safety checks (branch, dirty tree)
+        └── spawn(detached) → Supervisor process (bin/gsd-t-unattended.js)
+                               ├── writes .gsd-t/.unattended/supervisor.pid
+                               ├── writes .gsd-t/.unattended/state.json  (atomic rewrite each iter)
+                               ├── appends .gsd-t/.unattended/run.log    (worker stdout+stderr)
+                               ├── checks .gsd-t/.unattended/stop        (sentinel — presence = halt)
+                               └── relay loop:
+                                    spawnSync('claude -p "/gsd-t-resume"')
+                                      → worker exits → post-worker safety check → next iter
+
+In-session watch loop (every 270s via ScheduleWakeup)
+  └── /user:gsd-t-unattended-watch
+        ├── reads supervisor.pid  (kill -0 liveness)
+        ├── reads state.json      (status, iter, lastTick)
+        └── reschedules or reports final status
+```
+
+### State Directory Layout
+
+```
+.gsd-t/.unattended/
+├── supervisor.pid   — Integer PID. Exists ONLY while supervisor is alive.
+├── state.json       — Live state snapshot. Atomically rewritten between iterations.
+├── run.log          — Append-only worker stdout+stderr. Never truncated during a run.
+├── stop             — Sentinel file. Absence = run. Presence = user-requested stop.
+└── config.json      — Optional per-project config overrides (maxIterations, hours, etc.)
+```
+
+Sibling: `.gsd-t/.handoff/` — owned by M35-gap-fixes for single-shot handoff locks (see below).
+
+### Contract
+
+`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative source for: state schema, status enum, exit-code table, launch handshake, watch tick decision tree, resume auto-reattach handshake, stop mechanism, safety-rails hook points, and CLI surface.
+
+### Platform Abstraction Layer (`bin/gsd-t-unattended-platform.js`)
+
+Exports four cross-platform functions:
+
+| Export | macOS | Linux | Windows |
+|--------|-------|-------|---------|
+| `spawnSupervisor(args)` | `spawn(node, ...)` detached | same | same (`windowsHide:true`) |
+| `preventSleep()` | `caffeinate -i` subprocess | `systemd-inhibit` or no-op | no-op (not supported — see docs/unattended-windows-caveats.md) |
+| `releaseSleep(handle)` | kill caffeinate PID | release inhibit or no-op | no-op |
+| `notify(title, msg, level)` | `osascript` | `notify-send` | no-op |
+| `resolveClaudePath()` | PATH lookup | PATH lookup | `claude.cmd` via PATH |
+
+### Safety Rails (`bin/gsd-t-unattended-safety.js`)
+
+Called at four supervisor hook points (pre-launch, supervisor-init, pre-worker, post-worker):
+
+- **Gutter detection**: stall pattern — repeated identical errors or no file changes for N iterations
+- **Blocker sentinels**: scan worker stdout for unrecoverable-error markers (`BLOCKED_NEEDS_HUMAN`, `DISPATCH_FAILED`)
+- **Iteration cap**: `maxIterations` guard (default 200)
+- **Wall-clock cap**: `hours` guard (default 24h)
+- **Branch/dirty-tree pre-flight**: refuses to start on protected branches or uncleaned worktrees
+
+Each check returns `{ ok, reason?, code? }`. A `false` result halts with `status = 'failed'` and the corresponding exit code (6=gutter, 7=protected-branch, 8=dirty-tree).
+
+### Handoff-Lock Primitive (`bin/handoff-lock.js`)
+
+Closes the M35 parent/child race in `bin/headless-auto-spawn.js`. When the runway estimator fires `autoSpawnHeadless()`, the parent session writes a lock file in `.gsd-t/.handoff/` before spawning the child and removes it only after the child has confirmed PID + state-ready. Prevents the child from beginning execution before the parent has cleanly exited — eliminating the race where both sessions wrote to the same `.gsd-t/` files simultaneously.
+
+### Resume Auto-Reattach
+
+`/user:gsd-t-resume` Step 0 checks for a live supervisor before any other resume logic. If `supervisor.pid` exists and `kill -0` succeeds and `state.json.status` is non-terminal, the resume command skips normal resume flow entirely, prints the current watch block, and calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch', ...)`. The user transparently re-enters the watch loop without any manual step.
+
+---
+
 ## Design Decisions
 
 | Date | Decision | Rationale | Alternatives Considered |
@@ -368,6 +445,101 @@ During partition, UI/frontend projects automatically receive `.gsd-t/contracts/d
 
 When Playwright MCP is registered in Claude Code settings, QA agents get 3 minutes of interactive exploration and Red Team gets 5 minutes after all scripted tests pass. Findings are tagged `[EXPLORATORY]` in qa-issues.md and red-team-report.md, and tracked separately in QA calibration (category key: `exploratory` — does NOT count against scripted pass/fail ratio). Silent skip when Playwright MCP absent. Wired into: execute, quick, integrate, debug.
 
+## Context Meter Architecture (M34, v2.75.10+)
+
+The Context Meter is the authoritative source for session context-burn measurement in GSD-T. It replaces the v2.74.12 `bin/task-counter.cjs` proxy (and the pre-v2.74.12 `CLAUDE_CONTEXT_TOKENS_USED` env-var approach, which never worked because Claude Code does not export those vars).
+
+**Data flow:**
+
+```
+Claude Code tool call finishes
+  │
+  ▼
+PostToolUse hook (~/.claude/settings.json registered)
+  │
+  ▼
+scripts/gsd-t-context-meter.js (runMeter)
+  │
+  ├── 1. loadConfig(.gsd-t/context-meter-config.json)
+  ├── 2. check-frequency gate — short-circuits if tool-call % freq != 0
+  ├── 3. parseTranscript(hook.transcript_path)
+  │         → { system, messages } shaped for count_tokens
+  ├── 4. countTokens({apiKey, model, system, messages, timeoutMs:200})
+  │         → POST https://api.anthropic.com/v1/messages/count_tokens
+  │         → 200 { input_tokens }  |  failure → null
+  ├── 5. computePct(inputTokens, modelWindowSize)
+  ├── 6. bandFor(pct) → "normal" | "warn" | "stop"   (v3.0.0 three-band model)
+  └── 7. atomic write .gsd-t/.context-meter-state.json
+           { version, timestamp, inputTokens, modelWindowSize, pct, threshold, checkCount, lastError? }
+  │
+  ▼
+bin/token-budget.js getSessionStatus(projectDir)      ── v3.0.0: normal/warn/stop only
+  │
+  ├── readContextMeterState(dir)
+  │      if fresh (timestamp within 5 min):
+  │        return { consumed, estimated_remaining, pct, threshold }
+  │      else: null
+  │
+  └── fallback: readSessionConsumed(dir) from .gsd-t/token-log.md (heuristic)
+  │
+  ▼
+bin/runway-estimator.js estimateRunway({command, domain_type, remaining_tasks})
+  │        reads current_pct from .context-meter-state.json
+  │        queries .gsd-t/token-metrics.jsonl for historical pct-delta per spawn
+  │        projects current_pct + pct_per_task × remaining_tasks × skew
+  │        confidence: high ≥50 records, medium ≥10, low <10 (+1.25× skew)
+  │        returns {can_start, projected_end_pct, confidence, recommendation}
+  ▼
+Command file Step 0 — runway gate (execute/wave/quick/integrate/debug):
+  if (!decision.can_start) {
+    print ⛔ banner
+    autoSpawnHeadless({command, continue_from: '.'})    ── bin/headless-auto-spawn.js
+    process.exit(0)                                      ── never prompts user
+  } else {
+    proceed to Step 0.1 (Verify Context Gate Readiness) and Step 1
+  }
+  │
+  ▼
+bin/headless-auto-spawn.js (when refused)
+  │        detached child: node bin/gsd-t.js headless {command} --log
+  │        child.unref(); interactive session returns immediately
+  │        writes .gsd-t/headless-sessions/{id}.json (status: "running")
+  │        2s poll watcher: process.kill(pid, 0) → mac osascript notification on exit
+  │
+  ▼
+Orchestrator Context Gate — v3.0.0 semantics:
+  normal → proceed
+  warn   → log to .gsd-t/token-log.md, proceed at full quality (informational only)
+  stop   → halt cleanly, runway estimator hands off to headless-auto-spawn
+```
+
+**Key constraints:**
+- **Fail-open**: every stage catches errors and writes a partial state file. Never crashes Claude Code.
+- **No message content in state or log files** — only token counts, band names, error codes.
+- **Never logs or writes the API key** anywhere.
+- **State staleness window**: 5 minutes — after that, heuristic fallback takes over.
+- **Hook latency budget**: 200ms (timeoutMs on the HTTP call), enforced by `req.setTimeout` + `req.destroy()`.
+
+**Contracts:**
+- `.gsd-t/contracts/context-meter-contract.md` — schema, state file format, hook I/O
+- `.gsd-t/contracts/context-observability-contract.md` v2.0.0 — Ctx% as the real session-wide signal (replaces Tasks-Since-Reset)
+- `.gsd-t/contracts/token-budget-contract.md` v3.0.0 — three-band stop-at-85 (M35 clean break from v2.0.0)
+- `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0 — per-spawn 18-field JSONL at `.gsd-t/token-metrics.jsonl`
+- `.gsd-t/contracts/runway-estimator-contract.md` v1.0.0 — pre-flight projection, confidence grading, refusal/headless handoff
+- `.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0 — detached continuation, session schema, macOS notification channel
+- `.gsd-t/contracts/model-selection-contract.md` v1.0.0 — per-phase tier mapping + complexity-signal escalation, consumed by `bin/model-selector.js`
+
+**M35 supporting components** (outside the context-meter dataflow):
+- `bin/model-selector.js` — declarative rules table mapping phases to haiku/sonnet/opus; consulted at plan time, never at runtime under pressure
+- `bin/token-optimizer.js` — at `complete-milestone`, scans the last 3 milestones of `.gsd-t/token-metrics.jsonl` and appends recalibration recommendations to `.gsd-t/optimization-backlog.md` (never auto-applied; user promotes via `/user:gsd-t-optimization-apply` or rejects via `/user:gsd-t-optimization-reject` with 5-milestone cooldown)
+- `bin/check-headless-sessions.js` — renders the read-back banner on `/user:gsd-t-resume` and `/user:gsd-t-status` for completed-but-not-yet-surfaced headless sessions
+
+**Installer integration** (`bin/gsd-t.js`):
+- `install` / `init` — copy hook runtime, merge PostToolUse entry into `~/.claude/settings.json`, copy config template, prompt for API key (skippable, TTY-only)
+- `doctor` — RED on missing API key, missing hook, missing script, invalid config, failed count_tokens dry-run
+- `status` — displays `Context: {pct}% of {window} tokens ({band}) — last check {rel}` line
+- `update-all` — one-shot task-counter retirement migration (deletes legacy files, writes `.gsd-t/.task-counter-retired-v1` marker)
+
 ## Planned Architecture Changes (M23-M24)
 
 **M23: Headless Mode**