@tekyzinc/gsd-t 2.76.10 → 3.10.10

package/commands/gsd-t-wave.md

@@ -201,7 +201,7 @@ The JSON on stdout contains `{consumed, estimated_remaining, pct, threshold}`
 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. Output exactly: `⏸️ Wave orchestrator context gate reached ({pct}% of model window). Progress saved. Run /clear then /user:gsd-t-wave to continue from the next phase.` Do NOT spawn the next phase agent.
+- `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.
 
 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/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.

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 |

package/docs/infrastructure.md

@@ -312,6 +312,110 @@ Read-only surface onto the token telemetry stream. Backward-compatible with pre-
 
 When a sonnet-default phase hits a complexity signal that warrants opus (e.g., cross-module refactor detected mid-execution), the command may emit an `/advisor` hook line in its output — a structured suggestion for the orchestrator to escalate the **next** spawn of that phase to opus. This is a plan-time signal, not a runtime swap: the current spawn completes at its assigned tier, and the escalation applies to subsequent work. See `.gsd-t/contracts/model-selection-contract.md` for the hook schema.
 
+## Unattended Supervisor Setup (M36)
+
+The unattended supervisor runs an active GSD-T milestone to completion in a detached OS process — no terminal needed, no human intervention required.
+
+### Quick Start
+
+```bash
+# From within an interactive Claude session:
+/user:gsd-t-unattended
+
+# From the terminal (detached — returns immediately):
+gsd-t unattended --hours=24 --milestone=M36
+
+# Watch current run status (in-session, 270s tick):
+/user:gsd-t-unattended-watch
+
+# Request a graceful stop:
+/user:gsd-t-unattended-stop
+```
+
+### CLI Flags
+
+```
+gsd-t unattended [OPTIONS]
+  --hours=24              Wall-clock cap in hours (default: 24)
+  --max-iterations=200    Worker iteration cap (default: 200)
+  --project=.             Project directory (default: cwd)
+  --branch=AUTO           Branch to run on; AUTO = current non-protected branch
+  --on-done=print         Terminal action: print | merge-commit (merge-commit is v2)
+  --dry-run               Preflight only; no spawn
+  --verbose               Extra log detail
+  --test-mode             Uses stub worker; for CI and smoke tests
+```
+
+### Config File (optional)
+
+`.gsd-t/unattended-config.json` — per-project overrides. Absence = hardcoded defaults.
+
+```json
+{
+  "hours": 24,
+  "maxIterations": 200,
+  "gutterNoProgressIters": 5,
+  "workerTimeoutMs": 3600000,
+  "protectedBranches": ["main", "master", "develop", "trunk"],
+  "dirtyTreeWhitelist": [".gsd-t/.unattended/*", ".gsd-t/events/*.jsonl"]
+}
+```
+
+### State Files
+
+| File | Purpose |
+|------|---------|
+| `.gsd-t/.unattended/supervisor.pid` | Integer PID. Exists only while supervisor is alive. |
+| `.gsd-t/.unattended/state.json` | Live state snapshot — status, iter, milestone, lastTick, etc. Full schema in `unattended-supervisor-contract.md`. |
+| `.gsd-t/.unattended/run.log` | Append-only worker stdout+stderr. Never truncated during a run. |
+| `.gsd-t/.unattended/stop` | Sentinel — touching this file requests a graceful stop. |
+| `.gsd-t/.unattended/config.json` | Optional per-project config overrides (same keys as CLI flags). |
+
+### Required Platform Helpers
+
+| Platform | Sleep Prevention | Notifications |
+|----------|-----------------|---------------|
+| macOS | `caffeinate` (built-in) | `osascript` (built-in) |
+| Linux | `systemd-inhibit` or no-op | `notify-send` (install via `apt`/`dnf`) |
+| Windows | NOT supported — see `docs/unattended-windows-caveats.md` | no-op |
+
+macOS and Linux work out of the box on standard installs. Windows can run the supervisor but the machine may sleep mid-run.
+
+### Contract
+
+`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative state schema, exit-code table, status enum, launch/resume handshakes.
+
+### Troubleshooting
+
+**Supervisor won't start**
+- Check `.gsd-t/.unattended/run.log` for error output
+- Run `gsd-t unattended --dry-run` to run pre-flight checks without spawning
+- Verify no protected branch: `git branch --show-current`
+
+**"Already running" error**
+```bash
+# Verify supervisor is actually alive:
+kill -0 $(cat .gsd-t/.unattended/supervisor.pid) && echo "alive" || echo "stale PID"
+
+# If stale, remove PID file:
+rm .gsd-t/.unattended/supervisor.pid
+
+# Or request a graceful stop:
+/user:gsd-t-unattended-stop
+# (or) touch .gsd-t/.unattended/stop
+```
+
+**Watch loop stopped firing**
+- Re-invoke `/user:gsd-t-resume` from a fresh session
+- Step 0 auto-reattach reads `supervisor.pid` — if the supervisor is still alive, it re-enters the watch loop automatically (no manual steps needed)
+
+**Supervisor crashed mid-run**
+- The watch loop detects crash via `kill -0` failure
+- Check `.gsd-t/.unattended/run.log` and final `state.json` for diagnostics
+- Resume normally with `/user:gsd-t-resume` — the milestone continues from its last checkpoint
+
+---
+
 ## Security Notes
 
 - Zero npm dependencies — no supply chain risk

package/docs/methodology.md

@@ -119,3 +119,11 @@ Between v2.74 and v2.75, GSD-T attempted to cope with context pressure through *
 **Structural guarantee.** Because `STOP_THRESHOLD_PCT = 85` and the runway estimator refuses runs that would project past 85%, the runtime's 95% native compact is now structurally unreachable under healthy operation. `halt_type: native-compact` in `.gsd-t/token-metrics.jsonl` is a defect signal — if it appears, the estimator needs re-tuning.
 
 **Message content is never logged**: the meter writes only token counts, band names, and error category codes. Never transcript text, never API response bodies, never the API key itself. See `docs/architecture.md` for the full data-flow diagram and `.gsd-t/contracts/context-meter-contract.md` for the schema.
+
+## From Runway-Protected Execution to Cross-Session Relay (M36)
+
+M34 gave GSD-T a real measurement of how much context window each session had consumed. M35 used that signal to refuse starting new work that would exceed the 85% threshold, auto-spawning a detached headless process instead so the user never had to manually run `/clear`. Both milestones still had a ceiling: the headless continuation was a single shot — it ran one Claude session, and if the milestone wasn't complete when that session exhausted its context, a human had to intervene again to trigger the next continuation. Long-running milestones (multi-day builds, large waves) still required periodic human attention to keep the relay going.
+
+M36 (v2.77.10) makes the relay automatic and indefinite. The unattended supervisor (`bin/gsd-t-unattended.js`) is a long-lived OS process, fully detached from any Claude Code terminal session, that drives the relay itself: it spawns a fresh `claude -p "/gsd-t-resume"` worker, waits for it to exit, reads the outcome, and immediately spawns the next worker — repeating until the milestone reaches COMPLETED status or a wall-clock cap is hit. Each worker gets a pristine context window. The `/compact` that inevitably fires in a long session is irrelevant because the *next* session has already started fresh. The supervisor IS the orchestrator of runway handoffs. Safety rails (`bin/gsd-t-unattended-safety.js`) prevent infinite-loop scenarios: gutter detection catches stall patterns, blocker sentinels catch unrecoverable errors, and iteration/hour caps ensure the machine doesn't run forever on a broken state. A cross-platform abstraction layer handles macOS sleep-prevention (`caffeinate`), Linux equivalents, and Windows limitations. From the user's perspective: invoke `/user:gsd-t-unattended`, walk away, and receive a native OS notification when the milestone is done — hours or days later.
+
+The in-session watch loop (270-second `ScheduleWakeup` ticks, chosen to stay inside the 5-minute prompt-cache TTL) closes the feedback loop for users who keep a Claude session open. And the `gsd-t-resume` Step 0 auto-reattach means that even a `/clear` or accidental session close is transparent: the next resume detects the live supervisor and silently re-enters the watch loop without any manual step. Taken together, M34 + M35 + M36 form a complete three-layer system: measure the context accurately, refuse to degrade when it runs low, and relay execution automatically across as many fresh sessions as the work requires.

package/docs/requirements.md

@@ -254,6 +254,15 @@
 | REQ-076 | Optimization backlog — detect only, never auto-apply, user promotes or rejects | optimization-backlog | T1–T4 | complete (Wave 4) |
 | REQ-077 | Headless auto-spawn on runway refusal — user never sees a `/clear` prompt | headless-auto-spawn | T1–T5 | complete (Waves 3–4) |
 | REQ-078 | Structural elimination of native compact messages — `halt_type: native-compact` count is 0 during M35 execution | runway-estimator + headless-auto-spawn | T1–T5 (RE), T1–T5 (HAS) | complete (Wave 5) |
+| REQ-079 | `gsd-t unattended` CLI subcommand runs an active milestone to completion unattended on macOS and Linux (24h+ multi-worker relay, detached OS process) | m36-supervisor-core | T1–T5 | complete (M36 Wave 1–2) |
+| REQ-080 | `/user:gsd-t-unattended` slash command launches the supervisor from within a Claude session without blocking the terminal | m36-supervisor-core + m36-watch-loop | T1, T3 | complete (M36 Wave 1–3) |
+| REQ-081 | In-session watch loop ticks every 270s via `ScheduleWakeup` (inside 5-min prompt-cache TTL) to report live supervisor state | m36-watch-loop | T1–T2 | complete (M36 Wave 3) |
+| REQ-082 | `/clear` + `/user:gsd-t-resume` during a live unattended run transparently re-attaches to the watch loop (Step 0 auto-reattach, no user-visible disruption) | m36-watch-loop | T4 | complete (M36 Wave 3) |
+| REQ-083 | Supervisor survives `/compact` and context resets — each worker is a fresh `claude -p` session; context exhaustion is structurally irrelevant | m36-supervisor-core | T1–T5 | complete (M36 Wave 1–2) |
+| REQ-084 | Safety rails prevent infinite loops: gutter detection, blocker sentinels (`BLOCKED_NEEDS_HUMAN`, `DISPATCH_FAILED`), max-hours and max-iterations timeouts | m36-safety-rails | T1–T5 | complete (M36 Wave 2) |
+| REQ-085 | Cross-platform support — macOS (caffeinate sleep-prevention) + Linux (systemd-inhibit or no-op) + Windows (claude.cmd via PATH; sleep-prevention not supported — see docs/unattended-windows-caveats.md) | m36-cross-platform | T1–T5 | complete (M36 Wave 2) |
+| REQ-086 | Handoff-lock primitive (`bin/handoff-lock.js`) eliminates parent/child race in `headless-auto-spawn.js` runway handoffs (M35 gap fix) | m36-m35-gap-fixes | T1–T3 | complete (M36 Wave 2) |
+| REQ-087 | 5 command files no longer emit "Run /clear" STOP — runway-exceeded handoff auto-invokes `autoSpawnHeadless()` seamlessly (M35 gap fix) | m36-m35-gap-fixes | T3 | complete (M36 Wave 3) |
 
 **M35 Functional Requirements:**
 - **REQ-069**: `bin/token-budget.js` `getDegradationActions()` must return `{band: 'normal'|'warn'|'stop', pct: number, message: string}` only. No `modelOverride`, no `skipPhases`, no `checkpoint` side-channel.
@@ -276,6 +285,26 @@
 **Orphaned requirements**: None — all M35 REQs mapped to tasks.
 **Unanchored tasks**: None — all 38 M35 tasks trace to REQ-069–REQ-078 or REQ-063–068 (existing requirements that M35 code continues to satisfy).
 
+**M36 Functional Requirements:**
+- **REQ-079**: `bin/gsd-t-unattended.js` implements the supervisor relay loop: spawn worker → await exit → post-worker safety check → next iter. State written atomically to `.gsd-t/.unattended/state.json`. Contract: `unattended-supervisor-contract.md` v1.0.0.
+- **REQ-080**: `commands/gsd-t-unattended.md` pre-flights branch + dirty tree, spawns supervisor detached, polls for PID readiness, displays initial watch block, and calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')`.
+- **REQ-081**: `commands/gsd-t-unattended-watch.md` implements the watch tick decision tree (§8 of contract): reads PID → liveness probe → reads state.json → reschedule or terminal report.
+- **REQ-082**: `commands/gsd-t-resume.md` Step 0 checks `supervisor.pid` before any other resume logic. If live + non-terminal: skip normal resume, print watch block, call `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')`.
+- **REQ-083**: Supervisor relay architecture ensures each worker gets a fresh context window. No compaction state carries over between workers — only `.gsd-t/` milestone state files.
+- **REQ-084**: `bin/gsd-t-unattended-safety.js` exports: `checkGitBranch`, `checkWorktreeCleanliness`, `validateState`, `checkIterationCap`, `checkWallClockCap`, `detectBlockerSentinel`, `detectGutter`. Called at all 4 supervisor hook points.
+- **REQ-085**: `bin/gsd-t-unattended-platform.js` exports: `spawnSupervisor`, `preventSleep`, `releaseSleep`, `notify`, `resolveClaudePath`. Windows: `preventSleep` is a documented no-op. Windows caveats documented in `docs/unattended-windows-caveats.md`.
+- **REQ-086**: `bin/handoff-lock.js` exports: `acquireLock(dir)`, `releaseLock(dir)`, `isLocked(dir)`. Used in `bin/headless-auto-spawn.js` `autoSpawnHeadless()` to guard the parent-exits-before-child-starts window.
+- **REQ-087**: `commands/gsd-t-execute.md`, `gsd-t-wave.md`, `gsd-t-integrate.md`, `gsd-t-quick.md`, `gsd-t-debug.md` — runway-exceeded path calls `autoSpawnHeadless()` and exits cleanly. No "Run /clear" instruction emitted.
+
+**M36 Non-Functional Requirements:**
+- Zero external npm dependencies (all M36 bin/ modules use Node.js built-ins only)
+- Supervisor launch → PID-ready in < 5 seconds (poll timeout in launch command)
+- Worker spawn overhead: < 500ms before `claude -p` subprocess starts
+- Test count: 1146 → 1226 (+80 net new tests across 6 M36 domain test files)
+
+**Orphaned requirements**: None — all M36 REQs mapped to tasks.
+**Unanchored tasks**: None — all M36 tasks trace to REQ-079–REQ-087.
+
 ---
 
 ## M17: Scan Visual Output — Feature Specification

package/docs/unattended-windows-caveats.md

@@ -0,0 +1,245 @@
+# Unattended Supervisor — Windows Caveats (v1.0.0)
+
+**Status**: Windows support is **shipping but caveated** in v1.0.0.
+
+**Contract reference**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0
+**Platform module**: `bin/gsd-t-unattended-platform.js`
+
+---
+
+## 0. Required Software (All Platforms)
+
+The launch command (`/user:gsd-t-unattended`) pre-flights required software in
+Step 1e and refuses to spawn if anything is missing. Install these before
+launching:
+
+**Required everywhere (hard-fail):**
+
+| Tool    | Install                                                       |
+|---------|---------------------------------------------------------------|
+| node    | https://nodejs.org (>= 16)                                    |
+| claude  | `npm install -g @anthropic-ai/claude-code`                    |
+| git     | https://git-scm.com/downloads                                 |
+
+**macOS — soft warnings (install for best reliability):**
+
+| Tool        | Purpose                  | Install             |
+|-------------|--------------------------|---------------------|
+| caffeinate  | sleep prevention          | built-in (Apple)    |
+
+**Linux — soft warnings:**
+
+| Tool                      | Purpose                     | Install                                    |
+|---------------------------|-----------------------------|--------------------------------------------|
+| systemd-inhibit OR caffeine | sleep/screen-lock prevention | usually preinstalled; else `sudo apt install caffeine` |
+| notify-send               | desktop notifications        | `sudo apt install libnotify-bin`           |
+
+**Windows — soft warnings:**
+
+| Tool               | Purpose                      | Install                                |
+|--------------------|------------------------------|----------------------------------------|
+| PowerShell         | sleep prevention (built-in)  | ships with Windows                     |
+| BurntToast         | real toast notifications     | `Install-Module BurntToast` (PowerShell) |
+
+If the pre-flight fails, the launcher prints each missing tool with its
+install instructions and refuses to spawn. Soft warnings are advisory only —
+the supervisor still launches without them, but with degraded resilience.
+
+---
+
+## 1. Overview
+
+The GSD-T unattended supervisor (M36) ships cross-platform. All core supervisor
+mechanics — the watch loop, state-file lifecycle, worker spawning, stop
+sentinel, and safety rails — run unchanged on Windows. The darwin and linux
+code paths are runtime-tested; the win32 code paths are
+**implementation-complete but not runtime-tested on the dev host (macOS)**.
+
+Three OS-integration surfaces have known limitations on Windows:
+
+1. **Sleep prevention** — no stock `caffeinate` equivalent ships with Windows.
+2. **Notifications** — `msg.exe` is a minimal fire-and-forget shim with real
+   delivery restrictions.
+3. **Process detach** — `spawn(..., { detached: true })` behaves differently
+   from POSIX and is not a true daemonization primitive.
+
+This document covers what works, what doesn't, the Spike C disposition, and
+the recommended usage pattern. Everything below applies to `win32` only;
+darwin and linux are unaffected.
+
+---
+
+## 2. Known Gaps
+
+### 2.1 Sleep prevention (no-op on win32)
+
+`preventSleep(reason)` in `bin/gsd-t-unattended-platform.js` explicitly
+**returns `null` on win32** and writes a one-line notice to stderr:
+
+```
+[platform] sleep prevention not implemented on win32 (see docs/unattended-windows-caveats.md)
+```
+
+Windows has no stock command-line equivalent of macOS `caffeinate`. The
+native API (`SetThreadExecutionState`) requires a C binding, which violates
+the GSD-T zero-external-dependency constraint for `bin/`. `releaseSleep(null)`
+is a safe no-op, so the supervisor still shuts down cleanly.
+
+**Consequence**: if a Windows machine is configured to sleep on its default
+power schedule, a long unattended run will pause (or outright fail) when the
+machine sleeps. The supervisor has no way to prevent this.
+
+**Workaround (v1)**: the user must configure Windows power settings manually
+to keep the machine awake for the duration of the run. Microsoft's official
+guidance covers both GUI and command-line approaches:
+
+- [powercfg command-line options](https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/powercfg-command-line-options)
+- [Change power plan settings](https://support.microsoft.com/en-us/windows/change-power-mode-for-your-windows-pc-c2aff038-22f9-f46a-8ca1-ba5be2b6a7b9)
+
+Useful examples:
+
+```powershell
+# Disable sleep while on AC power (requires admin)
+powercfg /change standby-timeout-ac 0
+
+# Disable sleep while on battery (requires admin)
+powercfg /change standby-timeout-dc 0
+```
+
+### 2.2 Notifications (`msg.exe`, interactive-session only)
+
+`notify(title, message, level)` in `bin/gsd-t-unattended-platform.js` uses
+`msg.exe * "title: message"` on win32 with `windowsHide: true`. This is a
+deliberate minimal fire-and-forget dependency: `msg.exe` ships with Windows
+and has zero install cost.
+
+**Restrictions**:
+
+- `msg.exe` only delivers to **interactive Windows sessions**. If the
+  supervisor is launched under a Windows Service, a non-interactive ssh
+  session, or any other session without a desktop attached, `msg.exe` will
+  silently drop the notification (or fail with an access error). The
+  supervisor core is unaffected — the `child.on('error', ...)` handler logs
+  the failure to stderr and the relay loop continues.
+- `msg.exe` is not a true toast / Action Center notification. It pops a
+  blocking message-box dialog into the active session. This is visible and
+  audible but is not the modern Windows notification experience.
+
+**Recommended v2 enhancement**: integrate a real toast API such as
+[`BurntToast`](https://github.com/Windos/BurntToast) (a PowerShell module).
+`BurntToast` requires an opt-in install, so it will remain behind a capability
+check; stock installs will fall back to `msg.exe`.
+
+### 2.3 Process detach (`detached: true` is not full daemonization)
+
+`spawnSupervisor({ binPath, args, cwd })` uses
+`spawn('node', [...], { detached: true, stdio: 'ignore', windowsHide: true })`
+followed by `child.unref()`. On **POSIX** (darwin / linux) this makes the
+child a new process-group leader and the supervisor survives the parent
+terminal closing. On **win32** the same options produce a separate process
+tree but do **not** fully detach the child from the launching console:
+
+- Closing the launching terminal window may still deliver a console
+  `CTRL_CLOSE_EVENT` to the child and terminate the supervisor.
+- Signing out of the user session will terminate the child along with every
+  other user process.
+- There is no equivalent of POSIX `setsid()` purely from Node's `spawn`
+  options.
+
+**Workarounds**:
+
+- Use `start /B` via a shell wrapper to launch the supervisor in a fully
+  background-detached process on the current session.
+- For truly-outlive-the-session runs, register the supervisor as a **Windows
+  Task Scheduler** task. Task Scheduler manages its own process lifetime
+  independent of the interactive session.
+- Run inside **WSL2** (see §5) to get POSIX detach semantics end-to-end.
+
+---
+
+## 3. Spike C Disposition — Sleep Prevention Alternatives
+
+Spike C was an exploratory investigation of Windows-native alternatives to
+`caffeinate`. The question: can we keep the zero-dependency constraint and
+still prevent sleep?
+
+Three candidates were evaluated:
+
+| Option | Mechanism | Verdict |
+|--------|-----------|---------|
+| `SetThreadExecutionState` Win32 API via `ffi` | Native API, exactly what caffeinate maps to. | **Reject.** Requires `ffi-napi` or equivalent — a C binding and a compiled native dep. Violates the zero-external-dependency constraint for `bin/`. |
+| `powercfg` toggle | CLI that ships with Windows. `powercfg /change standby-timeout-ac 0` before run, restore after. | **Reject.** Requires administrator privileges. Persists across runs if the supervisor crashes mid-run, leaving the machine in a modified power state. Hard to guarantee restoration. |
+| Task Scheduler "wake to run" / wake events | Scheduled task can force the machine to wake at interval. | **Defer.** Best user-space path but adds non-trivial scheduler management code (create task, tear down on exit, handle orphaned tasks). |
+
+**Verdict**: **defer to v2.** v1.0.0 ships with the `null`-handle + documentation
+approach described in §2.1. v2 will consider Task Scheduler integration as the
+primary path, since it is the only candidate that is both user-space and
+compatible with the zero-dependency constraint.
+
+---
+
+## 4. What Works Today on Windows
+
+All of the following run on Windows with no caveats (pending runtime testing
+on a real Windows host; implementation is complete):
+
+- **Core supervisor process** — runs to completion, observes the state file,
+  dispatches workers, honours the watch-loop cadence, and exits cleanly.
+- **State file lifecycle** — atomic write, lockfile, heartbeat updates, and
+  teardown all use Node built-ins and behave identically on win32.
+- **Worker spawning** — `spawnWorker(projectDir, timeoutMs)` uses `claude.cmd`
+  via `resolveClaudePath()` with `shell: false` and `windowsHide: true`, which
+  avoids the Spike C PowerShell quoting hazard.
+- **Stop sentinel** — sentinel-file detection is filesystem-based and is
+  cross-platform by construction.
+- **Safety rails** — `isAlive(pid)` uses Node's `process.kill(pid, 0)`, which
+  implements POSIX signal-0 semantics on Windows. Liveness checks, watchdog
+  timers, and stuck-worker detection all work unchanged.
+
+Exit code table (contract §5), heartbeat contract, and the launch-handshake
+file contract are all platform-agnostic and fully honoured on win32.
+
+---
+
+## 5. Recommended Usage Pattern on Windows
+
+Given the gaps above, the recommended way to run the unattended supervisor on
+Windows for v1.0.0 is:
+
+1. **Run on a desktop that never sleeps.** Configure Windows power settings so
+   the machine will not sleep, hibernate, or turn off the display for the
+   expected duration of the run. Use `powercfg` or the Settings UI (see §2.1).
+2. **Launch from an interactive PowerShell session** (not a Windows Service,
+   not a non-interactive ssh session). This ensures `msg.exe` notifications
+   can be delivered and that the supervisor's stderr diagnostics are visible.
+3. **Monitor via the watch-tick command from the same interactive session.**
+   Do not close the launching terminal until the supervisor exits — see §2.3
+   for why.
+4. **Consider running inside WSL2** instead of native Windows. WSL2 provides a
+   full Linux userland where `bin/gsd-t-unattended-platform.js` takes the
+   `linux` branch everywhere: `isAlive`, `spawnWorker`, `spawnSupervisor`, and
+   `notify` all behave with POSIX semantics end-to-end. The only remaining gap
+   in WSL2 is sleep prevention (linux also returns `null` from `preventSleep`
+   in v1.0.0), which is still governed by the host Windows machine's power
+   settings. WSL2 is currently the closest thing to the full darwin / linux
+   feature set on a Windows box.
+
+---
+
+## 6. Summary Matrix
+
+| Feature                  | darwin    | linux     | win32                                          |
+|--------------------------|-----------|-----------|------------------------------------------------|
+| `resolveClaudePath`      | `claude`  | `claude`  | `claude.cmd`                                   |
+| `isAlive(pid)`           | works     | works     | works (POSIX signal-0 semantics)               |
+| `spawnWorker`            | works     | works     | implementation-complete, untested on real host |
+| `spawnSupervisor` detach | full      | full      | partial — console-close may kill child         |
+| `preventSleep`           | works     | null (v1) | null (v1) — see §2.1 and §3                    |
+| `releaseSleep`           | works     | no-op     | no-op                                          |
+| `notify`                 | works     | works     | works only in interactive sessions (§2.2)      |
+
+**v2 roadmap (non-binding)**:
+- Linux: opt-in `systemd-inhibit` for sleep prevention.
+- Windows: Task Scheduler integration for sleep prevention; `BurntToast`
+  capability check for real toast notifications; optional Task-Scheduler-based
+  daemonization path for true detachment.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.76.10",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 56 slash commands with 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",
+  "version": "3.10.10",
+  "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",
   "repository": {

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

@@ -44,7 +44,7 @@ const os = require("node:os");
 
 const HOOK_SCRIPT = path.resolve(__dirname, "gsd-t-context-meter.js");
 const INJECTOR = path.resolve(__dirname, "context-meter", "test-injector.js");
-const HARD_TIMEOUT_MS = 6000;
+const HARD_TIMEOUT_MS = 12000;
 
 /* ──────────────────────────── test fixtures ──────────────────────────── */
 

package/templates/CLAUDE-global.md

@@ -68,6 +68,9 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-resume` | Restore context, continue |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects |
+| `/user:gsd-t-unattended` | Launch detached supervisor — runs active milestone to completion with zero human intervention |
+| `/user:gsd-t-unattended-watch` | Watch tick — fires every 270s via ScheduleWakeup, reports supervisor status |
+| `/user:gsd-t-unattended-stop` | Touch stop sentinel — supervisor halts after current worker finishes |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches |
 | `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components |
 | `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report |
@@ -398,6 +401,15 @@ KEEP GOING. Only stop for:
 3. Milestone completion (checkpoint for user review)
 4. Destructive actions (see Destructive Action Guard above — ALWAYS stop)
 
+## Unattended Execution (M36, v3.10.10+)
+
+`/user:gsd-t-unattended` launches a detached OS-process supervisor that drives the active milestone to completion over hours or days via a `claude -p` worker relay — each worker in a fresh context window. The interactive Claude session receives a 270-second ScheduleWakeup watch loop (`/user:gsd-t-unattended-watch`) that ticks and prints progress until the supervisor reaches a terminal state.
+
+- **Resume re-attach**: `/user:gsd-t-resume` checks for a live `supervisor.pid`; if the supervisor is still running, it skips normal resume and re-starts the watch loop automatically.
+- **Stop**: `/user:gsd-t-unattended-stop` touches `.gsd-t/.unattended/stop`; supervisor halts after the current worker finishes.
+- **Contract**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative for state schema, exit codes, CLI flags, and platform matrix.
+- **Platform**: macOS and Linux fully supported. Windows supported except sleep-prevention (see `docs/unattended-windows-caveats.md`).
+
 ## Pre-Commit Gate (MANDATORY)
 
 NEVER commit code without running this checklist. This is not optional.