@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/docs/architecture.md

@@ -70,6 +70,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **`scripts/gsd-t-dashboard.html`** (194 lines): React 17 + React Flow v11.11.4 + Dagre via CDN (no build step, no npm deps). Dark theme (`#0d1117`). Renders agent hierarchy as directed graph from `parent_agent_id` relationships. Live event feed (max 200, outcome color-coded). Auto-reconnects on SSE disconnect. Port configurable via `?port=` URL param.
 - **`commands/gsd-t-visualize.md`** (104 lines, 48th command): Starts server via `--detach`, polls `/ping` up to 5s, opens browser cross-platform (win32/darwin/linux). Accepts `stop` argument to shut down server. Step 0 self-spawn with OBSERVABILITY LOGGING.
 
+### Transcript Viewer as Primary Surface (M43 D6 — complete v3.16.13)
+- **Dashboard server additions** (`scripts/gsd-t-dashboard-server.js`): two new HTTP routes for the per-spawn viewer. `GET /transcript/:id/usage` → `{spawn_id, rows, truncated}` filtered from `.gsd-t/metrics/token-usage.jsonl` by `row.spawn_id === id` OR (no `spawn_id` column + `row.session_id === id` — the session-id branch covers M43 D1 Branch B in-session rows). `GET /transcript/:id/tool-cost` → proxies to `bin/gsd-t-tool-attribution.cjs::aggregateByTool` (M43 D2); returns 503 `{error: "tool-attribution library not yet available"}` when D2 isn't on disk so D6 could ship before D2 in Wave 2 without crashing callers.
+- **Transcript viewer panel** (`scripts/gsd-t-transcript.html`): collapsible "Tool Cost" sidebar panel that fetches `/transcript/:id/tool-cost` on viewer load and debounces a 2s refresh on each SSE `turn_complete` / `result` frame. Renders top-N tools sorted by attributed tokens with name, call count, tokens, and USD cost. Live badge green while SSE is open, muted otherwise. 503 → friendly "tool attribution not yet wired" row. `window.__gsdtRenderToolCostPanel` exposed for DOM tests.
+- **URL banner** (`bin/headless-auto-spawn.cjs`): every detached spawn prints `▶ Live transcript: http://127.0.0.1:{port}/transcript/{spawn-id}` on stdout. Port sourced from `ensureDashboardRunning().port` with `projectScopedDefaultPort(projectDir)` fallback. Best-effort — banner failure never crashes the spawn.
+- **Dashboard autostart** (`scripts/gsd-t-dashboard-autostart.cjs`, ~160 lines, zero deps): `ensureDashboardRunning({projectDir, port?})` probes the port synchronously via a short-lived subprocess (`_isPortBusySync` issues `net.createServer().listen(port)` host-less — matches the server's IPv6-wildcard bind on macOS dual-stack; specifying `127.0.0.1` would falsely report free). If free, fork-detaches the server with `spawn(…, {detached:true, stdio:'ignore'})` + `child.unref()` + writes `.gsd-t/.dashboard.pid` (hyphen → dot distinguishes this lifecycle from M38's `.gsd-t/dashboard.pid`). Idempotent on repeated invocation. Called at the top of `autoSpawnHeadless` so the banner printed immediately after resolves to a live listener.
+- **Contract**: `.gsd-t/contracts/dashboard-server-contract.md` v1.2.0 — new §HTTP Endpoints entries, §Banner Format, §Autostart sections.
+- **Tests**: `test/m43-dashboard-tool-cost-route.test.js` (9), `test/m43-transcript-panel.test.js` (12), `test/m43-dashboard-autostart.test.js` (6), `test/m43-url-banner.test.js` (3).
+
 ### Headless Mode (M23 — complete)
 - **doHeadless(args)**: Dispatch function for the `headless` CLI subcommand.
 - **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 `/gsd-t-X` — non-interactive mode rejects the `/` namespace prefix.)
@@ -433,22 +441,44 @@ Alert thresholds (inline display):
 
 `gsd-t-status` displays token breakdown by domain/task/phase. `gsd-t-visualize` consumes the same data for dashboard rendering.
 
-**Token Pipeline (M40 → M41 → M43 D3)**
+**Token Pipeline (M40 → M41 → M43 D3 → M43 D2)**
 
 Canonical store: `.gsd-t/metrics/token-usage.jsonl` (append-only JSONL; schema in `.gsd-t/contracts/metrics-schema-contract.md` — v1 M40, v2 M43 additive).
 
 ```
 producers ─┬─► .gsd-t/metrics/token-usage.jsonl ─┬─► gsd-t tokens                 (dashboard)
            │                                     ├─► gsd-t tokens --regenerate-log (→ token-log.md)
-           │                                     └─► M43 D2 tool-attribution (planned)
+           │                                     ├─► gsd-t tokens --show-tool-costs (adds D2 section)
+           │                                     └─► gsd-t tool-cost (M43 D2)
            ├── scripts/gsd-t-token-aggregator.js     (M40 worker stream-json)
            ├── bin/gsd-t-token-capture.cjs           (M41 recordSpawnRow / captureSpawn)
            ├── bin/gsd-t-token-backfill.cjs          (M41 D3 historical recovery)
-           └── M43 D1 in-session capture (hook or tee — branch pending)
+           └── bin/gsd-t-in-session-usage.cjs       (M43 D1 — Branch B: Stop-hook trigger + transcript-sourced)
 ```
 
 Under v2, `.gsd-t/token-log.md` is a **regenerated view** (`gsd-t tokens --regenerate-log`), not hand-maintained. Wrapper still appends in real time for live visibility; regeneration is an explicit operator step that requires the JSONL to be fully backfilled first. Regeneration is idempotent and deterministic (sort order: `startedAt` asc → `session_id` asc → `turn_id` asc, numeric when both turn IDs parse).
 
+**Per-Tool Attribution (M43 D2)**
+
+`bin/gsd-t-tool-attribution.cjs` + `bin/gsd-t-tool-cost.cjs` + `gsd-t tool-cost` CLI join per-turn usage rows with tool-call events and attribute each turn's tokens across the tools called in that turn. Contract: `.gsd-t/contracts/tool-attribution-contract.md` v1.0.0 defines the output-byte ratio algorithm with four tie-breakers (zero-byte turn → equal split, missing tool_result → zero weight flagged, no tool calls → no-tool bucket, null turn tokens → skipped).
+
+```
+.gsd-t/metrics/token-usage.jsonl ─┐
+                                  ├─► joinTurnsAndEvents (session_id + ts window)
+.gsd-t/events/YYYY-MM-DD.jsonl ───┘            │
+                                               ▼
+                                    attributeTurn → attributions[]
+                                               │
+                                               ▼
+                             aggregateByTool / aggregateByCommand / aggregateByDomain
+                                               │
+                                               ▼
+                                         gsd-t tool-cost CLI
+                                  (table / json, --group-by, --since, --milestone)
+```
+
+Zero-dep, sync filesystem I/O. Perf gate: 3k turns × 30k events join+aggregate in <3s (measured ~30ms on a dev laptop). The current event schema does not carry `tool_result` bytes, so the zero-byte tie-breaker fires and tools-in-turn split equally. A future event-schema extension that records bytes will activate the ratio with no library change.
+
 ### GSD 2 Tier 3 — Quality Culture & Design (M32 — complete v2.53.10)
 
 Three enhancements for project-level quality identity and design consistency.
@@ -558,6 +588,396 @@ Orchestrator Context Gate — v3.0.0 semantics:
 - `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)
 
+## Task-Graph Reader (M44 D1, v3.18.10+)
+
+`bin/gsd-t-task-graph.cjs` — a zero-external-dep CommonJS module that parses every `.gsd-t/domains/*/tasks.md` (and falls back to each domain's `scope.md` `## Files Owned` for missing touch lists) into a typed in-memory DAG. This is the **single shared input** for every M44 parallelism domain — D2 `gsd-t parallel`, D3 command-file integration, D4 dep-graph validation, D5 file-disjointness prover, D6 pre-spawn economics — none of which re-parse `tasks.md` themselves.
+
+```
+.gsd-t/domains/<domain>/tasks.md  ──┐
+.gsd-t/domains/<domain>/scope.md  ──┴──>  buildTaskGraph({projectDir})
+                                              │
+                                              ▼
+                                {nodes, edges, ready, byId, warnings}
+                                              │
+       ┌──────────────────────────────────────┼──────────────────────────────────────┐
+       ▼                                      ▼                                      ▼
+  D2 gsd-t parallel              D4 dep-validate (veto)                D5 disjoint-prove (veto)
+  D3 command-file integ.         D6 pre-spawn economics                 (touches[] overlap check)
+```
+
+**Public API** (`require('./bin/gsd-t-task-graph.cjs')`):
+- `buildTaskGraph({projectDir}) → { nodes, edges, ready, byId, warnings }` — synchronous
+- `getReadyTasks(graph) → TaskNode[]` — node objects whose deps are all DONE
+- `TaskGraphCycleError` — thrown on circular dependency, carries `.cycle: string[]`
+
+**Hard rules** (from `task-graph-contract.md` v1.0.0):
+- Zero external deps — Node built-ins only
+- Cycle detection mandatory (iterative three-color DFS) — never produces partial graph on cycle
+- Read-only — never writes to `tasks.md`, `scope.md`, or contracts
+- Mode-agnostic — knows nothing about in-session vs unattended; pure graph emitter
+- Performance budget < 200 ms for 100-domain / 1000-task project (measured 6 ms / 250 tasks)
+
+**CLI surface** (`bin/gsd-t.js doGraph` → `doGraphTaskOutput`):
+- `gsd-t graph --output json` — pretty-printed DAG to stdout
+- `gsd-t graph --output table` — column-aligned id/domain/wave/status/ready/deps table
+- `gsd-t graph tasks [json|table]` — explicit subcommand form
+- Pre-existing `graph index|status|query` (codebase entity graph via `graph-indexer`) unchanged
+
+**Contract**: `.gsd-t/contracts/task-graph-contract.md` v1.0.0
+
+## Dep-Graph Validation (M44 D4, v3.18.10+)
+
+`bin/gsd-t-depgraph-validate.cjs` — a zero-external-dep CommonJS module that runs as the **first pre-spawn gate** between D1's DAG emitter and the parallel dispatcher. Given `graph.ready` (the DAG's candidate set), it filters down to tasks whose declared `deps[]` are all in DONE status, emits one `dep_gate_veto` event per task it removes, and returns the reduced ready set plus the veto list. The caller (D2) decides whether to spawn the smaller batch or fall back to sequential — D4 itself is a pure filter with no spawn authority.
+
+```
+D1 graph (graph.ready, graph.byId)
+      │
+      ▼
+  D4 validateDepGraph              ← this module (filter-only; never throws on unmet deps)
+      │            │
+ ready[] (OK)   vetoed[] ──────>  .gsd-t/events/YYYY-MM-DD.jsonl  (one dep_gate_veto per task)
+      │
+      ▼
+  D5 disjointness check            ← next pre-spawn gate
+      │
+      ▼
+  D6 economics                     ← final pre-spawn gate
+      │
+      ▼
+  D2 parallel dispatch
+```
+
+**Public API** (`require('./bin/gsd-t-depgraph-validate.cjs')`):
+- `validateDepGraph({graph, projectDir}) → { ready: TaskNode[], vetoed: {task, unmet_deps[]}[] }` — synchronous
+
+**Veto rule** (locked in `depgraph-validation-contract.md` §3): a dep is satisfied iff `graph.byId[depId]` exists AND `status === 'done'`. Pending / skipped / failed / unknown all veto the dependent. Every vetoed task emits exactly one `dep_gate_veto` JSONL record on the event stream.
+
+**Event payload** (`dep_gate_veto`): base `event-schema-contract.md` fields (ts ISO 8601, event_type, command/phase/agent_id/parent_agent_id/trace_id/model set to null when D4 doesn't own them, reasoning="unmet deps: …", outcome="deferred") PLUS additive `task_id`, `domain`, `unmet_deps[]`.
+
+**Hard rules** (from `depgraph-validation-contract.md` v1.0.0):
+- Zero external deps — Node built-ins only
+- Never throws on unmet deps, unknown dep ids, or event-log I/O failure (only throws on malformed `opts`)
+- Read-only on `tasks.md` / `scope.md` / contracts — only write surface is appending JSONL lines (events dir created on demand)
+- Synchronous; < 50 ms on realistic 100-domain / 1000-task graphs
+- Mode-agnostic — same call shape in [in-session] and [unattended]; what to do with the reduced set is D2's call
+
+**Contract**: `.gsd-t/contracts/depgraph-validation-contract.md` v1.0.0
+
+## File-Disjointness Prover (M44 D5, v3.18.10+)
+
+`bin/gsd-t-file-disjointness.cjs` — the pre-spawn gate that, given a candidate parallel set of task nodes from D1's DAG, partitions them into `parallel` / `sequential` / `unprovable` groups based on declared write-target overlap. Mode-agnostic: same function used by the in-session D2 parallel CLI and the unattended D6 economics path.
+
+```
+D1 task-graph nodes (touches[])                    safe-default
+       │                                      (unprovable → sequential)
+       ▼                                                ▲
+ proveDisjointness({tasks, projectDir}) ────────────────┤
+       │                                                │
+       ├─→ resolveTouches()  (declared → git-history → none)
+       ├─→ groupByOverlap()  (union-find on touches[])
+       │
+       ▼
+ { parallel: TaskNode[][],  (singletons only in v1.0.0 — no multi-task "parallel clusters")
+   sequential: TaskNode[][], (overlap groups + unprovable singletons)
+   unprovable: TaskNode[] }
+       │
+       ▼
+ .gsd-t/events/YYYY-MM-DD.jsonl
+   { type: "disjointness_fallback", task_id, reason, ts }
+   reason ∈ { "unprovable", "write-target-overlap" }
+```
+
+**Public API** (`require('./bin/gsd-t-file-disjointness.cjs')`):
+- `proveDisjointness({tasks, projectDir}) → { parallel, sequential, unprovable }` — synchronous, never throws
+
+**Hard rules** (from `file-disjointness-contract.md` v1.0.0):
+- Unprovable is ALWAYS sequential — never assume disjointness
+- Zero external runtime deps; git invoked via `child_process.execSync` in a try/catch
+- Read-only on all domain artifacts; only write surface is the event JSONL append
+- Checks WRITE targets only — read-only file access is never a conflict
+- Git-history fallback bounded to 100 commits (`git log -n 100`)
+- Mode-agnostic — downstream (D2 / D6) decides what to do with sequential + unprovable groups
+
+**Contract**: `.gsd-t/contracts/file-disjointness-contract.md` v1.0.0
+
+## Per-CW Attribution (M44 D7, v3.18.10+)
+
+Per-Context-Window (CW) attribution lets the optimization report, the per-CW rollup in `gsd-t metrics`, and D6's pre-spawn estimator distinguish multiple CWs within one iter — necessary because Claude Code can compact mid-run, silently splitting one iter into two CWs that pre-D7 metrics treated as a single unit.
+
+```
+spawn site (orchestrator | supervisor | in-session driver)
+   │ supplies cw_id (= spawn_id for unattended; = session_id+":"+compaction_index for in-session)
+   ▼
+bin/gsd-t-token-capture.cjs::recordSpawnRow / captureSpawn
+   │ pass-through; serializes cw_id into the JSONL row when supplied
+   ▼
+.gsd-t/metrics/token-usage.jsonl   (schema v2.1.0 — cw_id optional)
+   │
+   ▼  consumers (D6 calibration, gsd-t metrics rollup, optimization report)
+
+Claude Code SessionStart  (source=compact)
+   ├──> scripts/gsd-t-compact-detector.js   (v1.0.0 — boundary row, unchanged)
+   └──> scripts/gsd-t-calibration-hook.js   (v1.1.0 — calibration row)
+              │ correlates with active spawn from .gsd-t/.unattended/state.json
+              │ derives actualCwPct from payload.input_tokens ÷ CW ceiling
+              ▼
+        .gsd-t/metrics/compactions.jsonl
+        ({type: "compaction_post_spawn", cw_id, task_id, spawn_id,
+          estimatedCwPct, actualCwPct, ts, schemaVersion: 1})
+```
+
+**`bin/gsd-t-token-capture.cjs` extension** — additive optional `cw_id` opt on `recordSpawnRow` and `captureSpawn`. The wrapper does not derive `cw_id`; it only forwards what the caller supplies. When absent (undefined / null / "") the field is omitted from the JSONL row entirely (NOT serialized as `null` or `""`). Pre-D7 callers produce byte-identical output. The serialization branch follows the existing `session_id` / `turn_id` pattern (`if (cw_id != null && cw_id !== '') rec.cw_id = String(cw_id);`).
+
+**`scripts/gsd-t-calibration-hook.js`** — zero-external-dep SessionStart hook handler that complements (does not replace) `scripts/gsd-t-compact-detector.js`. Both hooks fire on the same payload; both write to `.gsd-t/metrics/compactions.jsonl`; neither reads or writes the other's rows. The calibration hook silently no-ops when:
+- `payload.source !== "compact"`
+- `<cwd>/.gsd-t/` does not exist (off-switch)
+- `.gsd-t/.unattended/state.json` is missing / unparseable / `status !== "running"`
+- No `spawn_id` derivable from state
+- No `input_tokens` derivable from the compaction payload
+
+The hook ALWAYS exits 0 — throwing breaks Claude Code SessionStart. It includes a 1 MiB stdin cap, a path-traversal guard on the output sink, and a non-absolute-cwd guard mirroring the detector. Hard rules (from `compaction-events-contract.md` v1.1.0) specify the `compaction_post_spawn` row schema, the calibration sink coexistence rules, and the CW-ceiling override (`state.cwCeilingTokens` → defaults to `200000` input tokens).
+
+**Contracts**: `.gsd-t/contracts/metrics-schema-contract.md` v2.1.0 (`cw_id` field), `.gsd-t/contracts/compaction-events-contract.md` v1.1.0 (calibration event)
+
+**Tests**: `test/m44-cw-attribution.test.js` (19 tests covering pass-through with/without `cw_id`, calibration hook with/without active spawn, malformed state, non-compact sources, derivation fallback to `compactMetadata.preTokens`, ceiling overrides, coexistence with v1.0.0 detector rows, and zero-deps verification).
+
+## Pre-Spawn Economics Estimator (M44 D6, v3.18.10+)
+
+`bin/gsd-t-economics.cjs` — the pre-spawn gate component that predicts each candidate task's Context-Window (CW) footprint and feeds the D2 parallel-CLI gating math with a per-task recommendation. Zero external deps; loaded once per `projectDir` (sync cached corpus read); never returns `undefined` for numeric fields (global-median fallback is mandatory).
+
+**Core function**: `estimateTaskFootprint({taskNode, mode, projectDir})` → `{estimatedCwPct, parallelOk, split, workerCount, matchedRows, confidence}`.
+
+**Three-tier lookup** over the in-memory corpus index:
+
+1. **Exact** `command|step|domain` triplet — HIGH (≥5 rows) or MEDIUM (1–4 rows).
+2. **Fuzzy** — domain-only match, then command-only match → LOW confidence.
+3. **Global median** — `median(totals)` across every row → FALLBACK confidence. Mandatory floor; guarantees no undefined result.
+
+```
+     D1 task graph            ┌──────────────────────────────┐
+  ┌─ taskNode{cmd,step,dom} ──┤ bin/gsd-t-economics.cjs      │
+  │                           │  estimateTaskFootprint       │
+  │                           │  - corpus cache (per projDir)│
+  │                           │  - triplet lookup            │
+  │                           │  - fuzzy fallback            │
+  │                           │  - global median fallback    │
+  │                           │  - mode-specific gate math   │
+  │                           └───┬──────────────────────────┘
+  │                               │ {estimatedCwPct,
+  │                               │  parallelOk, split,
+  │                               │  workerCount, matchedRows,
+  │                               │  confidence}
+  │                               ↓
+  │                       D2 gating math (owns final decision)
+  │                               │
+  │                               └──→ appends economics_decision
+  │                                    event to .gsd-t/events/*.jsonl
+  │
+  └─ corpus sources: .gsd-t/metrics/token-usage.jsonl (v2.1.0)
+                     .gsd-t/metrics/compactions.jsonl (v1.1.0; calibration signal)
+```
+
+**Mode awareness**: `estimatedCwPct` is mode-agnostic (same tokens → same %). Gates differ:
+
+| Mode        | `parallelOk` threshold | `split` threshold | Rationale |
+|-------------|------------------------|-------------------|-----------|
+| in-session  | `≤ 85%`                | always `false`    | 85 % matches orchestrator-CW headroom check (D2); over-limit tasks still run with fewer workers. |
+| unattended  | `≤ 60%`                | `> 60%` → `true`  | Per-worker CW gate; heavy tasks are sliced into multiple `claude -p` iters by the caller (D6 recommends, does not slice). |
+
+**CW ceiling**: `200_000` input tokens — matches `bin/token-budget.cjs`, `bin/context-meter-config.cjs`, and `bin/runway-estimator.cjs`. Row totals = `inputTokens + outputTokens + cacheReadInputTokens + cacheCreationInputTokens` (a deliberately conservative upper bound; cache-read tokens are ~free in real CW accounting and inflate the estimate).
+
+**Calibration** (2026-04-22): run against the live 528-row `token-usage.jsonl` corpus. Per-tier MAE (% of CW ceiling): HIGH 12.89 %, MEDIUM 0.00 % (small-n tautology — 4 keys with 1–4 rows each), LOW 13.08 %, FALLBACK 15.06 %. Current corpus is skewed (523 rows on one triplet); `gsd-t-execute` and `gsd-t-wave` have no corpus signal yet and resolve to FALLBACK. Coverage grows as D7 `cw_id`-tagged rows accumulate from real-world spawns — the estimator's signal improves without code changes.
+
+**Hard invariants** (from `.gsd-t/contracts/economics-estimator-contract.md` v1.0.0):
+
+1. D6 is a HINT, not a veto — D2 retains gate authority.
+2. Corpus loaded ONCE per `projectDir` (cache via `Map`; `_resetCorpusCache()` exposed for tests).
+3. Never returns `undefined` for numeric fields — global-median fallback is mandatory.
+4. Mode-aware for gates; mode-agnostic for `estimatedCwPct`.
+5. Event emission is best-effort; FS failures never fail the estimate.
+6. Zero external npm runtime deps (Node built-ins only).
+
+**Contract**: `.gsd-t/contracts/economics-estimator-contract.md` v1.0.0.
+
+**Tests**: `test/m44-economics.test.js` (9 tests covering HIGH/MEDIUM/LOW/FALLBACK tiers, both mode thresholds under and over the boundary, economics_decision event shape, corpus cache identity, and empty-corpus behaviour).
+
+## Parallel CLI (M44 D2, v3.18.10+)
+
+`bin/gsd-t-parallel.cjs` — the `gsd-t parallel` subcommand dispatch. Wraps the M40 orchestrator with task-level (not just domain-level) parallelism and layers in mode-aware gating math. Extends, does not replace, `bin/gsd-t-orchestrator.js`; zero external runtime deps.
+
+**Surface**:
+- Module: `runParallel({projectDir, mode, milestone, domain, dryRun})` and `runCli(argv, env)`.
+- CLI: `gsd-t parallel [--mode in-session|unattended] [--milestone Mxx] [--domain <name>] [--dry-run] [--help]`.
+- Config extension in `bin/gsd-t-orchestrator-config.cjs`: `computeInSessionHeadroom`, `computeUnattendedGate`, and the exported constants `IN_SESSION_CW_CEILING_PCT=85`, `UNATTENDED_PER_WORKER_CW_PCT=60`, `DEFAULT_SUMMARY_SIZE_PCT=4`.
+
+**Dispatch flow**:
+
+```
+    gsd-t parallel --mode … [--dry-run]
+         │
+         ├──► D1 buildTaskGraph(projectDir) ─────────────┐
+         │    (bin/gsd-t-task-graph.cjs)                  │
+         │                                                │ ready tasks
+         ├──► D4 validateDepGraph(graph)  ◄───────────────┘
+         │    (bin/gsd-t-depgraph-validate.cjs)
+         │    → emits gate_veto on unmet deps
+         │
+         ├──► D5 proveDisjointness(readyTasks)
+         │    (bin/gsd-t-file-disjointness.cjs)
+         │    → emits gate_veto on overlap / unprovable
+         │
+         ├──► D6 estimateTaskFootprint(task, mode) × N
+         │    (bin/gsd-t-economics.cjs)
+         │    → per-task {estimatedCwPct, parallelOk, split, confidence}
+         │
+         ├──► Mode-aware gating math (config.cjs)
+         │    ├─ in-session: computeInSessionHeadroom
+         │    │  ctxPct from token-budget.getSessionStatus()
+         │    │  → reducedCount; emits parallelism_reduced on N < requested
+         │    └─ unattended: computeUnattendedGate(estimatedCwPct)
+         │       → emits task_split on > 60%
+         │
+         └──► plan{ workerCount, parallelTasks, plan[] }
+              → dry-run renders the 6-col table + mode/totals
+              → non-dry-run: hands off to M40 orchestrator machinery
+```
+
+**Mode contracts** (from `.gsd-t/contracts/wave-join-contract.md` v1.1.0):
+
+| Mode | Threshold | Math | On exceed |
+|------|-----------|------|-----------|
+| in-session | 85% orchestrator-CW | `ctxPct + N × summarySize ≤ 85` | Reduce N; floor=1 (never refuses) |
+| unattended | 60% per-worker CW | `estimatedCwPct ≤ 60` | `split=true`; caller slices |
+
+**Integration with the M40 path**: `runParallel` produces a plan object; it does **not** replace `bin/gsd-t-orchestrator.js`. The existing orchestrator machinery owns actual worker spawn, retry policy, wave barriers, merging, and the state-file lifecycle. D2 is the pre-spawn planning layer.
+
+**Event schemas** (all written best-effort to `.gsd-t/events/YYYY-MM-DD.jsonl`; failures never break control flow):
+- `gate_veto{type, task_id, gate, reason, ts}` — D4 or D5 rejection.
+- `parallelism_reduced{type, original_count, reduced_count, reason:'in_session_headroom', ts}` — in-session headroom forced a smaller N.
+- `task_split{type, task_id, estimatedCwPct, ts}` — unattended over-threshold.
+
+**Hard invariants** (from m44-d2 constraints.md):
+1. Zero external npm runtime deps.
+2. `bin/gsd-t-orchestrator.js` is never replaced; only extended via the config module.
+3. All three pre-existing invariants (disjointness, auto-merge, economics) apply to BOTH modes. No mode flag bypasses any gate.
+4. In-session mode NEVER throws pause/resume; N=1 is the irreducible floor.
+5. Adaptive `maxParallel` (`computeAdaptiveMaxParallel`) is untouched — D2 layers on top, not under.
+
+**Contract**: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+
+**Tests**: `test/m44-parallel-cli.test.js` (21 tests covering headroom ok/reduced/floor, unattended gate ok/split/boundary, plan-table format, runParallel in-session fan-out, disjointness gate-veto fallback, mode auto-detect, explicit-mode override, headroom reduction end-to-end with a 5-domain fixture at 70% ctxPct, and CLI arg parsing).
+
+## Command-File Integration (M44 D3, v3.18.10+)
+
+Wires the five primary GSD-T command files — `commands/gsd-t-execute.md`, `gsd-t-wave.md`, `gsd-t-integrate.md`, `gsd-t-quick.md`, `gsd-t-debug.md` — to the D2 `gsd-t parallel` CLI so task-level parallel dispatch becomes available from the standard workflow. Purely additive doc-ripple + conditional integration blocks; no new library code, no new spawns. Every existing sequential code path remains intact.
+
+**Dispatch decision flow**:
+
+```
+  command file                                 bin/gsd-t-parallel.cjs      bin/gsd-t-orchestrator.js
+  ────────────────                             ────────────────────       ────────────────────────
+  execute   ┐
+  wave      │   "Optional — Parallel               ┌─ D4 depgraph-validate ─┐
+  integrate ├─► Dispatch (M44)" block ───► runParallel │ (veto on unmet deps)  │
+  quick     │   (conditional: >1 pending       (D2)     ├─ D5 disjointness ──────┤──► validated plan
+  debug     ┘    task + D4/D5/D6 gates                  │ (veto on overlap)     │    ────► M40 orchestrator
+                 pass). Mode auto-detected              ├─ D6 economics (hint)  │          (spawns workers,
+                 from GSD_T_UNATTENDED.                 └─ mode-aware final     │          retries, wave
+                 Single-task or veto →                    gate (85% / 60%)      │          barriers, state
+                 silent sequential fallback.                                    │          lifecycle)
+                                                         emits gate_veto,
+                                                         parallelism_reduced,
+                                                         task_split events
+                                                         (best-effort JSONL)
+```
+
+**Per-file integration points**:
+
+| Command file | Step | Trigger | Behavior when no trigger |
+|-------------|------|---------|-------------------------|
+| `gsd-t-execute.md` | Step 3 (Choose Execution Mode) | >1 pending task + gates pass | Existing Wave Scheduling + Solo/Team Mode sequential path |
+| `gsd-t-wave.md` | Step 3 EXECUTE phase (#5) | Inherited from execute agent | Wave orchestrator does not configure mode |
+| `gsd-t-integrate.md` | Step 3 (Wire Integration Points) | Integrating >1 domain + gates pass | Sequential task-level dispatch |
+| `gsd-t-quick.md` | Step 3 (Execute) | >1 pending task + gates pass (uncommon for quick) | Sequential single-subagent (the common case) |
+| `gsd-t-debug.md` | Step 3 (Debug Solo or Team) | Multi-domain contract-boundary/gap debug | Sequential Solo Mode / Team Mode |
+
+**Invariants** (enforced by D2; documented in every D3 integration block):
+1. **Mode auto-detection** — mode comes from `GSD_T_UNATTENDED=1`; no command file hardcodes `--mode`.
+2. **Silent fallback** — gate vetoes, unprovable disjointness, and single-task scope ALL drop to sequential without a user prompt.
+3. **No opt-out flag** — no `--in-session`/`--headless` flag exists (consistent with M43 D4).
+4. **In-session: never interrupt** — headroom pressure reduces worker count to N=1 floor; never pauses.
+5. **Unattended: zero-compaction** — D2 enforces by splitting when D6 estimates > 60% per-worker CW.
+6. **Observability** — D2 owns spawn observability; D3 adds zero new spawns.
+
+**Contract**: `.gsd-t/contracts/wave-join-contract.md` v1.1.0 (surface referenced by every integration block).
+
+## Spawn Plan Visibility (M44 D8, v3.18.10+)
+
+Right-side two-layer task panel in the dashboard / transcript visualizer.
+Answers exactly one question: *"Of the tasks that were supposed to happen
+in this spawn, which are done, which are in flight, which are pending?"*
+Observability-only; zero added LLM token cost.
+
+**Writers (3 chokepoints; all wrapped in try/catch — plan-write failure NEVER blocks the spawn)**:
+- `bin/gsd-t-token-capture.cjs` — `captureSpawn()` calls `writeSpawnPlan`
+  before `await spawnFn()` and `markSpawnEnded` in both success/error paths.
+- `bin/headless-auto-spawn.cjs` — `autoSpawnHeadless()` calls
+  `writeSpawnPlan` before the detached child launches; `markSessionCompleted`
+  now also closes the plan.
+- `commands/gsd-t-resume.md` Step 0 — under `GSD_T_UNATTENDED_WORKER=1`,
+  every worker iteration writes a plan at iteration start.
+
+**Derivation**: `bin/spawn-plan-derive.cjs` reads `.gsd-t/partition.md` +
+`.gsd-t/domains/*/tasks.md` and emits `{milestone, wave, domains, tasks}`.
+Deterministic projection — no LLM calls, no prompts. Silent-fails to an
+empty slice when partition is absent.
+
+**Status updater**: `bin/spawn-plan-status-updater.cjs` — atomic JSON
+patches:
+- `markTaskDone({spawnId, taskId, commit, tokens?, projectDir})`
+- `markSpawnEnded({spawnId, endedReason, projectDir})`
+- `sumTokensForTask(...)` — parses `.gsd-t/token-log.md` rows where
+  `Task` column matches the id AND `Datetime-start >= spawn.startedAt`.
+
+**Post-commit hook**: `scripts/gsd-t-post-commit-spawn-plan.sh` (+ template
+at `templates/hooks/post-commit-spawn-plan.sh`). Greps commit message for
+all `[M\d+-D\d+-T\d+]` ids; for each active plan, calls `markTaskDone`
+with token attribution. Silent-fail: always `exit 0`.
+
+**Reader surface**:
+- `GET /api/spawn-plans` — active plans (where `endedAt === null`),
+  newest-first.
+- SSE channel `/api/spawn-plans/stream` — `fs.watch` on
+  `.gsd-t/spawns/*.json` emits `{spawnId, plan}` on every change.
+- `scripts/gsd-t-transcript.html` — right-side `<aside class="spawn-panel">`
+  with Layer 1 (project) + Layer 2 (active spawn). Status icons
+  `☐` pending / `◐` in_progress / `✓` done. Token cells render as
+  `in=12.5k out=1.7k $0.42` (k-suffix above 1000, 2-decimal USD); `—` when
+  attribution returned null.
+
+**Storage**: `.gsd-t/spawns/{spawnId}.json`. Schema v1. Atomic writes
+(temp file + rename). `spawnId` is filesystem-safe
+(`^[A-Za-z0-9._-]{1,200}$`). One ACTIVE plan per spawn; `endedAt === null`
+means in-flight.
+
+**Invariants** (from `.gsd-t/domains/m44-d8-spawn-plan-visibility/constraints.md`):
+1. Writer DERIVES, never decides.
+2. Spawn must launch even if writer fails.
+3. Atomic writes only.
+4. Post-commit hook silent-fail.
+5. Zero new LLM token cost.
+6. Additive edits to existing files only.
+7. No transcript-derivation fallback — missing plan file → *"no active
+   spawn plan"*, never reconstruct from transcript heuristics.
+
+**Contract**: `.gsd-t/contracts/spawn-plan-contract.md` v1.0.0.
+
+**Tests**: `test/m44-d8-spawn-plan-writer.test.js`,
+`test/m44-d8-spawn-plan-status-updater.test.js`,
+`test/m44-d8-post-commit-hook.test.js`,
+`test/m44-d8-dashboard-spawn-plans-endpoint.test.js`,
+`test/m44-d8-transcript-renderer-panel.test.js` — 36 tests total.
+
 ## Planned Architecture Changes (M23-M24)
 
 **M23: Headless Mode**