@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/commands/gsd-t-debug.md

@@ -4,16 +4,16 @@ You are debugging an issue in a contract-driven project. Your approach should id
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS`. The issue description is `$ISSUE`. Detect `--watch` (sets `WATCH_FLAG=true`; default `false`). Per `.gsd-t/contracts/headless-default-contract.md` §2, `--watch` propagates only to the **primary** inner fix-loop subagent (Step 0.1). Validation spawns (Deep Research Step 1.5, Red Team Step 5.3, doc-ripple Step 6) always go headless regardless of the flag.
+Parse `$ARGUMENTS`. The issue description is `$ISSUE`. M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** the inner fix-loop subagent (Step 0.1) and all validation spawns (Deep Research Step 1.5, Red Team Step 5.3, doc-ripple Step 6) go headless unconditionally. A legacy `--watch` token is accepted but ignored (stderr deprecation line).
 
-## Spawn Primitive — Default Headless (M38 Domain 1)
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Spawn classifications used below:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Spawn classifications used below (both always headless):
 
 - `spawnType: 'primary'` — Step 0.1 fresh-dispatch subagent running the debug session
 - `spawnType: 'validation'` — Step 1.5 Deep Research teammates, Step 5.3 Red Team, Step 6 doc-ripple
 
-Default path is `autoSpawnHeadless({command, spawnType, watch: WATCH_FLAG, projectDir, sessionContext})`. Outer orchestrator stays interactive; inner subagent goes headless by default and streams in-context only when `WATCH_FLAG=true`.
+Spawn path is `autoSpawnHeadless({command, spawnType, projectDir, sessionContext})`. The outer `gsd-t-debug` command body is itself the interactive spawn target when invoked by `/gsd` or `gsd-t-wave`; nested spawns always go headless.
 
 ## Model Assignment
 
@@ -96,7 +96,7 @@ Violations are task failures, not warnings.
 
 If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 
-Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (always headless per headless-default-contract v2.0.0):
 
 **OBSERVABILITY LOGGING (MANDATORY) — wrap the primary subagent spawn with `captureSpawn`:**
 
@@ -316,6 +316,25 @@ Before touching any code:
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 3 --step-label "Debug (Solo or Team)" 2>/dev/null || true
 ```
 
+### Optional — Parallel Dispatch (M44, lightweight · conditional-only)
+
+**This block is a no-op for single-domain debug sessions.** Most debug sessions touch one domain (within-domain bug, Category A in Step 2); for those, the sequential Solo Mode path below runs unchanged.
+
+**Trigger conditions (BOTH must hold)**:
+1. This is a multi-domain debug session (Category B contract boundary bug OR Category C contract gap that spans more than one domain), AND
+2. The fix is decomposable into independent tasks across domains that pass D4 depgraph + D5 file-disjointness + D6 economics gates.
+
+**If either condition fails** — single-domain debug, or a fix that cannot be decomposed cleanly — skip this block entirely. The sequential Solo Mode / Team Mode flow below remains unchanged.
+
+**If BOTH conditions hold** — dispatch the independent fix tasks via `gsd-t parallel` (mode auto-detected from `GSD_T_UNATTENDED=1`; do not hardcode `--mode`):
+
+- Fallback is silent — any gate veto drops the affected tasks back to the sequential debug path.
+- D2 owns the spawn observability; the parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records and `.gsd-t/token-log.md` rows as the sequential path via `captureSpawn`. D3 adds no new spawn machinery.
+- `[unattended]` — D2 enforces the zero-compaction contract by splitting tasks when D6 estimates > 60% per-worker CW.
+- `[in-session]` — NEVER interrupts the user with a pause/resume prompt. If headroom is tight, D2 reduces the worker count (floor N=1). No opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
+
+Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+
 ### Deviation Rules
 
 When you encounter unexpected situations during the fix:
@@ -460,7 +479,7 @@ const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
     description: 'adversarial validation of debug fix',
     projectDir: '.',
     notes: '{VERDICT} — {N} bugs found',
-    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, --watch ignored:
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless per headless-default-contract v2.0.0:
       'Read \$RT_PROMPT and follow it. Context: post-fix validation for a debug session.
       Additional categories for this run:
       (a) Regression Around the Fix — test every code path adjacent to the changed lines; fixes frequently break neighboring functionality.
@@ -500,7 +519,7 @@ After all work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
 2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
-3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless, `--watch` ignored):
+3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
 

package/commands/gsd-t-execute.md

@@ -4,20 +4,16 @@ You are the lead agent coordinating task execution across domains. Choose solo o
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS` before doing any work. Detect these flags:
+Parse `$ARGUMENTS` before doing any work. M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** every command spawns — the dialog channel is reserved for the `/gsd` router's exploratory turns and is upstream of this command. Any legacy `--watch` token in `$ARGUMENTS` is accepted but ignored (printed as a single stderr deprecation line by the spawn primitive).
 
-- `--watch` — opt-in to **in-context streaming** for primary work subagents. If present, set `WATCH_FLAG=true`; otherwise `WATCH_FLAG=false` (default).
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Validation spawns (QA, Red Team, Design Verification, doc-ripple) ignore `--watch` per `.gsd-t/contracts/headless-default-contract.md` §2 — they always go headless.
-
-## Spawn Primitive — Default Headless (M38 Domain 1)
-
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Every Task-subagent spawn below is classified as one of:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Every Task-subagent spawn below goes headless unconditionally. Classification is kept only for downstream logging:
 
 - `spawnType: 'primary'` — domain task-dispatcher (Step 3 fresh-dispatch)
 - `spawnType: 'validation'` — Step 2 QA, Step 5.25 Design Verification, Step 5.5 Red Team, Step 7 doc-ripple
 
-**Default spawn path** (when `WATCH_FLAG=false`):
+**Spawn path** (unconditional):
 
 ```bash
 SESSION=$(node -e "
@@ -27,7 +23,6 @@ const r = has.autoSpawnHeadless({
   args: [], // optional per-spawn args
   projectDir: process.cwd(),
   spawnType: '{primary|validation}',
-  watch: false,
   sessionContext: { step: '{step-id}', domain: '{domain-name}', task: '{task-id}' }
 });
 process.stdout.write(JSON.stringify(r));
@@ -37,10 +32,6 @@ echo "⚙ [${MODEL:-sonnet}] gsd-t-execute → ${DESC:-subagent} (headless)"
 
 Then `bin/check-headless-sessions.js printBannerIfAny()` surfaces the completion on the next user message.
 
-**`--watch` path** (only when `WATCH_FLAG=true` AND `spawnType: 'primary'`): `autoSpawnHeadless()` returns `{mode: 'in-context'}` sentinel — fall back to the in-context Task subagent pattern documented in each Step below. The OBSERVABILITY LOGGING block runs unchanged.
-
-**Validation spawns** always run headless regardless of `--watch`.
-
 ## Model Assignment
 
 Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0. Selection is deterministic via `bin/model-selector.js` — never runtime-overridden by context pressure.
@@ -116,7 +107,7 @@ node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-
 
 In solo mode, QA runs inside each domain subagent (see Step 3). In team mode, the lead spawns QA subagents at each domain checkpoint using the pattern below.
 
-**QA subagent prompt** — `spawnType: 'validation'` (always headless, `--watch` ignored per headless-default-contract §2):
+**QA subagent prompt** — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 ```
 Task subagent (spawnType: validation, general-purpose, model: sonnet):
 "Run the full test suite for this project and report pass/fail counts.
@@ -134,6 +125,28 @@ If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `|
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 3 --step-label "Choose Execution Mode" 2>/dev/null || true
 ```
 
+### Optional — Parallel Dispatch (M44)
+
+**Conditional check** — if `.gsd-t/domains/` contains more than one pending task that passes the D4 depgraph, D5 file-disjointness, and D6 economics gates, dispatch the ready batch via `gsd-t parallel` instead of the sequential task-dispatcher below. If the conditional fails (single pending task, or any gate vetoes, or disjointness is unprovable), fall through silently to the existing sequential path — there is no user prompt, no pause, no opt-out flag.
+
+- **Mode auto-detection** — mode is auto-detected by `bin/gsd-t-parallel.cjs` from `GSD_T_UNATTENDED=1`. Do not hardcode `--mode` in this command file. Explicit `--mode` overrides env; omitted flag falls back to env; missing env defaults to in-session.
+- **Fallback** — every gate veto (D4 `dep_gate_veto`, D5 `disjointness_fallback`, D6 estimated > threshold) removes the affected task(s) from the parallel batch. Tasks fall back to the sequential task-dispatcher silently; the dry-run plan table still lists them with decision `sequential` or `veto-deps` so the operator can see why.
+- **Observability** — D2 owns the spawn observability. The parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` event stream (`gate_veto`, `parallelism_reduced`, `task_split`) and the same `.gsd-t/token-log.md` rows that sequential spawns produce via `captureSpawn`. D3 adds no new spawn machinery — integration is purely a dispatch decision.
+- **Zero-compaction invariant (unattended)** — for `[unattended]` runs, D2 enforces the zero-compaction contract by splitting tasks when D6 estimates per-worker CW > 60%. Mid-run compaction is not tolerated; the splitter slices before fan-out.
+- **In-session invariant** — the parallel path NEVER interrupts the user with a pause/resume prompt. If the in-session headroom check reduces the worker count below the requested N, D2 emits `parallelism_reduced` and proceeds at the reduced count. The final floor is N=1 (sequential). If all gates fail, D2 falls back to sequential silently — no opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
+
+**Dispatch call** (example; resolve `--mode` via env):
+
+```bash
+# Dry-run first if you want to see the plan table without spawning:
+gsd-t parallel --milestone {milestone} --dry-run
+
+# Live dispatch (mode auto-detected from GSD_T_UNATTENDED):
+gsd-t parallel --milestone {milestone}
+```
+
+`runParallel` produces the validated worker plan; the existing M40 orchestrator machinery owns the actual worker spawn, retry policy, wave barriers, and state-file lifecycle. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0. When the conditional is not met — or when every candidate task falls back via veto — proceed to the existing Wave Scheduling + Solo/Team Mode flow below.
+
 ### Wave Scheduling (read first)
 
 Before choosing solo or team mode, read the `## Wave Execution Groups` section in `.gsd-t/contracts/integration-points.md` (added by the plan phase).
@@ -202,9 +215,7 @@ const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
 Run via Bash:
 `node -e "const tb = require('./bin/token-budget.cjs'); const s = tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s));" 2>/dev/null`
 
-Apply the single-band result per `context-meter-contract.md` v1.3.0:
-- `threshold: 'normal'` (or file missing) → proceed with standard model assignments.
-- `threshold: 'threshold'` → the Context Meter's PostToolUse hook has already emitted the `next-spawn-headless:true` marker; subsequent task-dispatcher spawns route through `autoSpawnHeadless()` automatically. No manual halt.
+Capture `pct` as `{CTX_PCT}` for the token-log `Ctx%` column on the next spawn. The reading is observational only — under headless-default-contract v2.0.0 the spawn decision is no longer gated on `threshold`; every task-dispatcher spawn goes through `autoSpawnHeadless()` regardless of band.
 
 **Pre-dispatch experience retrieval (before dispatching each domain's tasks):**
 Run via Bash:
@@ -309,7 +320,7 @@ For each task in `.gsd-t/domains/{domain-name}/tasks.md` (in order, skip complet
 2. Load graph context (if `.gsd-t/graph/meta.json` exists): query task's files for relevant graph context
 3. Display: `⚙ [sonnet] gsd-t-execute → domain: {domain-name}, task-{task-id}`
 4. Run observability Bash (T_START / DT_START)
-5. Spawn task subagent — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+5. Spawn task subagent — `spawnType: 'primary'` (always headless per headless-default-contract v2.0.0):
 
 ```
 Task subagent (spawnType: primary, general-purpose, model: sonnet, mode: bypassPermissions):
@@ -537,7 +548,7 @@ Report back:
 
 6. **Per-domain Red Team** — invoke Step 5.5 (Red Team) NOW for this domain. This is the first place Red Team runs in v2.74.12 — there is no global post-execute Red Team anymore. If Red Team returns FAIL, fix bugs and re-run before proceeding to the next domain (max 2 fix-and-verify cycles); if bugs persist, log to `.gsd-t/deferred-items.md` and present to user.
 
-7. **Context gate re-check** — run `node -e "const tb=require('./bin/token-budget.cjs'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s));"`. If `threshold === 'threshold'`, the Context Meter hook has already emitted the `next-spawn-headless:true` marker — the next domain dispatcher must be routed through `autoSpawnHeadless()` so it runs in a fresh headless context. `threshold === 'normal'` → proceed in-context.
+7. **Context observation** — run `node -e "const tb=require('./bin/token-budget.cjs'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s));"` and capture `pct` for the NEXT spawn's token-log row. No gating: the next domain dispatcher runs through `autoSpawnHeadless()` either way under headless-default-contract v2.0.0.
 
 ### Team Mode (when agent teams are enabled)
 Spawn teammates for domains within the same wave. Only domains in the same wave can run in parallel — do not spawn teammates for domains in different waves simultaneously. Each teammate uses the **domain task-dispatcher pattern** — one subagent per task within their domain (same as solo mode).
@@ -687,18 +698,15 @@ Cleanup is not optional — orphaned worktrees waste disk space and can confuse
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 3 --step-label ".5: Orchestrator Context Gate (MANDATORY)" 2>/dev/null || true
 ```
 
-Single-band context gate per `.gsd-t/contracts/context-meter-contract.md` v1.3.0. The orchestrator checks `getSessionStatus()` BEFORE every task subagent spawn. `bin/token-budget.cjs` reads `.gsd-t/.context-meter-state.json` — the token estimate produced by the Context Meter PostToolUse hook.
+Context observation — the orchestrator captures `getSessionStatus()` BEFORE every spawn for the Ctx% column only. Under headless-default-contract v2.0.0 the band does NOT gate the spawn decision; every task-dispatcher spawn goes through `autoSpawnHeadless()`.
 
-**Before each task spawn — gate check:**
+**Before each task spawn — capture ctx reading:**
 
 ```bash
 node -e "const tb=require('./bin/token-budget.cjs'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s));"
 ```
 
-The JSON on stdout contains `{pct, threshold}` where `threshold` is `normal` or `threshold`. Capture `pct` as `{CTX_PCT}` for the token-log `Ctx%` column on the NEXT spawn.
-
-- `threshold: 'normal'` → proceed with the standard in-context spawn path for `primary` spawns (headless for `validation` spawns per headless-default-contract).
-- `threshold: 'threshold'` → the Context Meter's PostToolUse hook has already emitted the `next-spawn-headless:true` marker. Route subsequent `primary` task-dispatcher spawns through `autoSpawnHeadless()` as well — the next spawn runs in a fresh headless context, the current orchestrator finishes its bookkeeping and returns cleanly. No manual checkpoint/halt.
+The JSON on stdout contains `{pct, threshold}`. Capture `pct` as `{CTX_PCT}` for the token-log `Ctx%` column on the NEXT spawn. The `threshold` field is observational — no longer used for branching.
 
 **Configuring the threshold:**
 
@@ -774,7 +782,7 @@ DV_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/design-v
 [ -f "$DV_PROMPT" ] || DV_PROMPT="templates/prompts/design-verify-subagent.md"
 ```
 
-Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ```
 node -e "
@@ -840,7 +848,7 @@ RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
 ```
 
-Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ```
 node -e "
@@ -905,7 +913,7 @@ After all work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
 2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
-3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless, `--watch` ignored):
+3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
 

package/commands/gsd-t-help.md

@@ -72,6 +72,7 @@ HEADLESS (CI/CD)                                                       CLI
   headless exec       Run any GSD-T command non-interactively via claude -p
   headless query      Read project state without LLM (<100ms)
   headless --debug-loop  Compaction-proof test-fix-retest loop (fresh sessions)
+  parallel            Task-level parallel dispatch with mode-aware gating (M44)
 
 BACKLOG                                                                Manual
 ───────────────────────────────────────────────────────────────────────────────
@@ -317,6 +318,7 @@ Use these when user asks for help on a specific command:
 - **Reads**: `.gsd-t/dashboard.pid`, `.gsd-t/events/*.jsonl` (via server)
 - **Creates**: `.gsd-t/dashboard.pid` (when starting server)
 - **Use when**: Monitoring live agent activity during execute/wave phases; run `gsd-t-visualize stop` to stop the server
+- **Spawn-plan panel (M44 D8, v3.18.10+)**: the transcript viewer at `/transcript/{spawnId}` now includes a right-side two-layer task panel (Layer 1 project · Layer 2 active spawn). Status icons `☐` pending, `◐` in_progress, `✓` done. Done tasks show a right-aligned token cell `in=12.5k out=1.7k $0.42` (or `—` when attribution unavailable). Token attribution is sourced from `.gsd-t/token-log.md` via the post-commit hook `scripts/gsd-t-post-commit-spawn-plan.sh`. Endpoints: `GET /api/spawn-plans` + SSE `/api/spawn-plans/stream`. Contract: `.gsd-t/contracts/spawn-plan-contract.md` v1.0.0.
 
 ### metrics
 - **Summary**: View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (with `--cross-project` flag)
@@ -339,6 +341,15 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/debug-state.jsonl`, optional `.gsd-t/headless-{ts}.log`
 - **Use when**: Running automated fix loops in CI, or delegated from in-context commands that exhausted fix attempts
 
+### parallel
+- **Summary**: Task-level parallel dispatch with mode-aware gating math (M44 D2) — wraps the M40 orchestrator with D4 depgraph + D5 file-disjointness + D6 economics gates and in-session headroom / unattended task-split decisions
+- **Auto-invoked**: Conditionally — from `execute`, `wave`, `integrate`, `quick`, and `debug` integration blocks when >1 pending task passes all three gates. Single-task or veto paths fall back to sequential silently.
+- **Flags**: `--mode in-session|unattended` (auto-detects from `GSD_T_UNATTENDED=1` when omitted), `--milestone Mxx`, `--domain <name>`, `--dry-run`, `--help/-h`
+- **Reads**: `.gsd-t/domains/*/tasks.md` (via D1 task-graph), `.gsd-t/token-log.md` / `.gsd-t/metrics/token-usage.jsonl` (D6 corpus), `.gsd-t/.context-meter-state.json` (in-session ctxPct)
+- **Writes**: `.gsd-t/events/YYYY-MM-DD.jsonl` — `gate_veto`, `parallelism_reduced`, `task_split` events (best-effort). Never writes to tasks.md.
+- **Use when**: Usually auto-invoked by the integration blocks. Standalone use: preview a plan with `gsd-t parallel --dry-run`, or force a specific milestone/domain filter.
+- **Contract**: `.gsd-t/contracts/wave-join-contract.md` v1.1.0 (§Mode-Aware Gating Math)
+
 ### promote-debt
 - **Summary**: Convert techdebt.md items into milestones
 - **Auto-invoked**: No

package/commands/gsd-t-integrate.md

@@ -4,15 +4,15 @@ You are the lead agent performing integration work. This phase is ALWAYS single-
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS`. Detect `--watch` (sets `WATCH_FLAG=true`; default `false`). Per `.gsd-t/contracts/headless-default-contract.md` §2, integrate's own agent work is interactive; all **validation** spawns below (QA in Step 5, Red Team in Step 7.5, doc-ripple in Step 9) always go headless regardless of `--watch`.
+Parse `$ARGUMENTS`. M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** every spawn below goes headless unconditionally — QA (Step 5), Red Team (Step 7.5), doc-ripple (Step 9). Integrate's own lead-agent body remains the interactive entry point for this command (it is itself the spawn target when invoked from `/gsd` or `gsd-t-wave`). A legacy `--watch` token is accepted but ignored (stderr deprecation line).
 
-## Spawn Primitive — Default Headless (M38 Domain 1)
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Spawn classifications used below:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Spawn classifications used below:
 
 - `spawnType: 'validation'` — QA subagent (Step 5 contract compliance), Red Team (Step 7.5 adversarial), doc-ripple (Step 9)
 
-Default path is `autoSpawnHeadless({command, spawnType: 'validation', watch: false, projectDir, sessionContext})` — validation spawns ignore `--watch`. Read-back banner surfaces each completion.
+Spawn path is `autoSpawnHeadless({command, spawnType: 'validation', projectDir, sessionContext})`. Read-back banner surfaces each completion.
 
 ## Model Assignment
 
@@ -103,6 +103,26 @@ If rolled-back domains exist, report them to the user (or if Level 3: log to `.g
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-integrate --step 3 --step-label "Wire Integration Points" 2>/dev/null || true
 ```
 
+### Optional — Parallel Dispatch (M44)
+
+When integration work spans **more than one domain simultaneously** (i.e., the integration-points.md list contains independent integration tasks across multiple domains), the ready batch may be dispatched via `gsd-t parallel` instead of the sequential task-level dispatch below. When integration touches only one domain (single-domain wiring), the conditional is a no-op and the existing sequential path runs unchanged.
+
+- **Conditional check** — only triggers when integrating > 1 domain AND the integration tasks pass D4 depgraph + D5 file-disjointness + D6 economics gates. Otherwise the block is a no-op.
+- **Mode auto-detection** — mode is auto-detected from `GSD_T_UNATTENDED=1` by `bin/gsd-t-parallel.cjs`. Do not hardcode `--mode` in this command file.
+- **Fallback** — any gate veto (unmet deps, overlapping write targets, unprovable disjointness) removes the affected tasks from the parallel batch; they fall back to the sequential task-dispatcher silently. No user prompt.
+- **Observability** — D2 owns the spawn observability. The parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records (`gate_veto`, `parallelism_reduced`, `task_split`) and `.gsd-t/token-log.md` rows as the sequential path via `captureSpawn`. D3 adds no new spawn machinery.
+- **Zero-compaction invariant (unattended)** — for `[unattended]` runs, D2 enforces zero-compaction by splitting integration tasks when D6 estimates > 60% per-worker CW.
+- **In-session invariant** — NEVER interrupts the user with a pause/resume prompt. If headroom is tight, D2 reduces the worker count (floor N=1) and emits `parallelism_reduced`. If all gates fail, falls back to sequential silently. No opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
+
+Example (mode auto-detected from env):
+
+```bash
+gsd-t parallel --milestone {milestone} --dry-run   # preview plan, no spawn
+gsd-t parallel --milestone {milestone}             # live dispatch
+```
+
+Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:
 `GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
@@ -181,7 +201,7 @@ Result: PARTIAL — needs pagination contract addition
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-integrate --step 5 --step-label "Contract Compliance Testing" 2>/dev/null || true
 ```
 
-Spawn a QA subagent via the Task tool to verify contract compliance at all domain boundaries — `spawnType: 'validation'` (always headless, `--watch` ignored):
+Spawn a QA subagent via the Task tool to verify contract compliance at all domain boundaries — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ```
 Task subagent (spawnType: validation, general-purpose, model: sonnet):
@@ -288,7 +308,7 @@ RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
 ```
 
-Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ```
 node -e "
@@ -327,7 +347,7 @@ After all integration work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
 2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
-3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless, `--watch` ignored):
+3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
 

package/commands/gsd-t-quick.md

@@ -4,16 +4,16 @@ You are executing a small, focused task that doesn't need full phase planning. T
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS`. The first positional arg is the quick task description (`$TASK`). Detect `--watch` (sets `WATCH_FLAG=true`; default `false`). Per `.gsd-t/contracts/headless-default-contract.md` §2, `--watch` propagates only to the **primary** inner subagent (Step 0.1 fresh-dispatch). Validation spawns (Design Verification Step 5.25, Red Team Step 5.5, doc-ripple Step 6) always go headless regardless of `--watch`.
+Parse `$ARGUMENTS`. The first positional arg is the quick task description (`$TASK`). M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** the inner subagent spawn (Step 0.1 fresh-dispatch) and all validation spawns (Design Verification Step 5.25, Red Team Step 5.5, doc-ripple Step 6) go headless unconditionally. A legacy `--watch` token is accepted but ignored (stderr deprecation line).
 
-## Spawn Primitive — Default Headless (M38 Domain 1)
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Spawn classifications used below:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Spawn classifications used below (both always headless):
 
 - `spawnType: 'primary'` — Step 0.1 fresh-dispatch subagent running the quick task
 - `spawnType: 'validation'` — Design Verification (Step 5.25), Red Team (Step 5.5), doc-ripple (Step 6)
 
-Default path is `autoSpawnHeadless({command, spawnType, watch: WATCH_FLAG, projectDir, sessionContext})`. Outer `gsd-t-quick` orchestrator stays interactive; the inner subagent goes headless by default and streams in-context only when `WATCH_FLAG=true`.
+Spawn path is `autoSpawnHeadless({command, spawnType, projectDir, sessionContext})`. The outer `gsd-t-quick` command body is itself the interactive spawn target for the parent `/gsd` router — nested spawns from this body always go headless.
 
 ## Model Assignment
 
@@ -34,14 +34,12 @@ To give this task a fresh context window and prevent compaction during consecuti
 
 **If you are the orchestrating agent** (you received the slash command directly):
 
-**Token Budget Check (before spawning subagent):**
+**Context observation (before spawning subagent):**
 
-Run via Bash:
-`node -e "const tb = require('./bin/token-budget.cjs'); const s = tb.getSessionStatus('.'); process.stdout.write(s.threshold);" 2>/dev/null`
+Run via Bash to capture `pct` for the NEXT spawn's token-log Ctx% column:
+`node -e "const tb = require('./bin/token-budget.cjs'); const s = tb.getSessionStatus('.'); process.stdout.write(String(s.pct));" 2>/dev/null`
 
-Apply the single-band result per `context-meter-contract.md` v1.3.0:
-- `normal` (or file missing) → proceed with default model (sonnet).
-- `threshold` → the Context Meter's PostToolUse hook has already emitted the `next-spawn-headless:true` marker; route the subagent spawn through `autoSpawnHeadless()` so the work runs in a fresh headless context.
+No gating — under headless-default-contract v2.0.0 every spawn goes through `autoSpawnHeadless()` regardless of band. The capture is observational only.
 
 **Stack Rules Detection (before spawning subagent):**
 
@@ -105,7 +103,7 @@ Violations are task failures, not warnings.
 
 If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 
-Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (always headless per headless-default-contract v2.0.0):
 
 **OBSERVABILITY LOGGING (MANDATORY) — wrap the primary subagent spawn with `captureSpawn`:**
 
@@ -186,6 +184,25 @@ Proceed.
 node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-quick --step 3 --step-label "Execute" 2>/dev/null || true
 ```
 
+### Optional — Parallel Dispatch (M44, lightweight · conditional-only)
+
+**This block is a no-op for the typical quick invocation.** `gsd-t-quick` is designed for single-focus work; forcing parallel on every quick invocation would add gate overhead without benefit.
+
+**Trigger conditions (BOTH must hold)**:
+1. `.gsd-t/domains/` contains more than one pending task, AND
+2. All three gates (D4 depgraph + D5 file-disjointness + D6 economics) pass for the candidate batch.
+
+**If either condition fails** — and that includes the common case of a single-task quick invocation — skip this block entirely. The sequential single-subagent path in Step 0.1 remains unchanged.
+
+**If BOTH conditions hold** — dispatch the ready batch via `gsd-t parallel` (mode auto-detected from `GSD_T_UNATTENDED=1`; do not hardcode `--mode`):
+
+- Fallback is silent — any gate veto drops the affected tasks back to the sequential quick path.
+- D2 owns the spawn observability; the parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records and `.gsd-t/token-log.md` rows via `captureSpawn`. D3 adds no new spawn machinery.
+- `[unattended]` — D2 enforces the zero-compaction contract by splitting tasks when D6 estimates > 60% per-worker CW.
+- `[in-session]` — NEVER interrupts the user with a pause/resume prompt. If headroom is tight, D2 reduces the worker count (floor N=1). No opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
+
+Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+
 ### Deviation Rules
 
 When you encounter unexpected situations:
@@ -426,7 +443,7 @@ const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
     description: 'adversarial validation of quick task',
     projectDir: '.',
     notes: '{VERDICT} — {N} bugs found',
-    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, --watch ignored:
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless per headless-default-contract v2.0.0:
       'Read \$RT_PROMPT and follow it. Context for this run: quick task — adversarial validation of the code just changed. Write findings to .gsd-t/red-team-report.md.' */ },
   });
 })();
@@ -452,7 +469,7 @@ After all work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
 2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
-3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless, `--watch` ignored):
+3. If FIRE: spawn doc-ripple agent — `spawnType: 'validation'` (always headless per headless-default-contract v2.0.0):
 
 ⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
 

package/commands/gsd-t-scan.md

@@ -4,16 +4,16 @@ You are the lead agent performing a comprehensive analysis of an existing codeba
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS`. Detect `--watch` (sets `WATCH_FLAG=true`; default `false`). Per `.gsd-t/contracts/headless-default-contract.md` §2, `--watch` propagates to the **primary** scan spawns (Step 0 outer subagent, Step 2 dimension agents). Step 5 living-document updates and Step 8 HTML report are validation-style — they always go headless.
+Parse `$ARGUMENTS`. M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** every scan spawn goes headless unconditionally (Step 0 outer subagent, Step 2 dimension agents, Step 3 synthesis agent, Step 5 living-document updater, Step 8 HTML report generator). A legacy `--watch` token is accepted but ignored (stderr deprecation line).
 
-## Spawn Primitive — Default Headless (M38 Domain 1)
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Spawn classifications used below:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Spawn classifications used below (both always headless):
 
 - `spawnType: 'primary'` — Step 0 outer fresh-dispatch subagent, Step 2 dimension agents, Step 3 synthesis agent
 - `spawnType: 'validation'` — Step 5 living-document updater, Step 8 HTML report generator
 
-Default path is `autoSpawnHeadless({command, spawnType, watch: WATCH_FLAG, projectDir, sessionContext})`.
+Spawn path is `autoSpawnHeadless({command, spawnType, projectDir, sessionContext})`.
 
 ## Step 0: Launch via Subagent
 
@@ -24,7 +24,7 @@ node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-
 Scans are long-running and context-heavy. Always execute via a Task subagent for a fresh context window.
 
 **If you are the orchestrating agent** (you received the slash command directly):
-Spawn a fresh subagent using the Task tool — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+Spawn a fresh subagent using the Task tool — `spawnType: 'primary'` (always headless per headless-default-contract v2.0.0):
 ```
 subagent_type: general-purpose
 spawnType: primary

package/commands/gsd-t-unattended-watch.md

@@ -54,13 +54,14 @@ const LOG_FILE = path.join(UDIR, 'run.log');
 
 function out(k, v) { console.log(k + '=' + JSON.stringify(v ?? null)); }
 
-// --- PID file ---
+// --- PID file (JSON or legacy bare-integer; canonical reader handles both) ---
 let pid = null;
 let pidFileExists = fs.existsSync(PID_FILE);
 if (pidFileExists) {
   try {
-    pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
-    if (!Number.isFinite(pid)) pid = null;
+    const { readPidFile } = require('./bin/supervisor-pid-fingerprint.cjs');
+    const entry = readPidFile(process.cwd());
+    pid = entry && Number.isInteger(entry.pid) ? entry.pid : null;
   } catch (_) { pid = null; }
 }
 out('PID_FILE_EXISTS', pidFileExists);

package/commands/gsd-t-unattended.md

@@ -43,7 +43,9 @@ if (!fs.existsSync(PID_FILE)) {
 
 let pid = null;
 try {
-  pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+  const { readPidFile } = require('./bin/supervisor-pid-fingerprint.cjs');
+  const entry = readPidFile(process.cwd());
+  pid = entry && Number.isInteger(entry.pid) ? entry.pid : null;
 } catch (_) {}
 
 if (!pid || !Number.isFinite(pid)) {
@@ -361,9 +363,13 @@ while (Date.now() < deadline) {
       alive = e.code === 'EPERM';
     }
   }
-  // Also try reading the PID file the supervisor writes
+  // Also try reading the PID file the supervisor writes (JSON or legacy bare-integer)
   if (fs.existsSync(PID_FILE)) {
-    try { pidFromFile = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10); } catch (_) {}
+    try {
+      const { readPidFile } = require('./bin/supervisor-pid-fingerprint.cjs');
+      const entry = readPidFile(process.cwd());
+      pidFromFile = entry && Number.isInteger(entry.pid) ? entry.pid : null;
+    } catch (_) {}
   }
   if (alive || pidFromFile) break;
   sleep(POLL_MS);

package/commands/gsd-t-verify.md

@@ -4,15 +4,15 @@ You are the lead agent coordinating verification of the completed work. Each ver
 
 ## Argument Parsing
 
-Parse `$ARGUMENTS`. Detect `--watch` (sets `WATCH_FLAG=true`; default `false`). Per `.gsd-t/contracts/headless-default-contract.md` §2, verify spawns are ALL classified as **validation** (the work product is a verdict, not a code change) — they always go headless regardless of `--watch`.
+Parse `$ARGUMENTS`. M43 D4 removed the `--watch` opt-out; `--in-session`/`--headless` were never shipped. Under `.gsd-t/contracts/headless-default-contract.md` **v2.0.0** every verify spawn goes headless unconditionally. A legacy `--watch` token is accepted but ignored (stderr deprecation line).
 
-## Spawn Primitive — Default Headless (M38 Domain 1)
+## Spawn Primitive — Always Headless (M43 D4, v2.0.0)
 
-Per `.gsd-t/contracts/headless-default-contract.md` v1.0.0. Spawn classifications used below:
+Per `.gsd-t/contracts/headless-default-contract.md` v2.0.0. Spawn classifications used below:
 
 - `spawnType: 'validation'` — Step 4 test-audit subagent, Step 8 auto-invoke complete-milestone
 
-Default path is `autoSpawnHeadless({command, spawnType: 'validation', watch: false, projectDir, sessionContext})`. Auto-invoke of complete-milestone (Step 8) is preserved — it is spawned headless via the same primitive and surfaces via the read-back banner.
+Spawn path is `autoSpawnHeadless({command, spawnType: 'validation', projectDir, sessionContext})`. Auto-invoke of complete-milestone (Step 8) is preserved — spawned headless via the same primitive and surfaced via the read-back banner.
 
 ## Model Assignment
 
@@ -421,7 +421,7 @@ If status is VERIFIED or VERIFIED-WITH-WARNINGS:
 
 **OBSERVABILITY LOGGING (MANDATORY) — wrap the complete-milestone auto-invoke with `captureSpawn`:**
 
-2. Spawn through `captureSpawn` — `spawnType: 'validation'`, model: sonnet, mode: bypassPermissions (always headless, `--watch` ignored):
+2. Spawn through `captureSpawn` — `spawnType: 'validation'`, model: sonnet, mode: bypassPermissions (always headless per headless-default-contract v2.0.0):
 
 ```
 node -e "