@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/docs/requirements.md

@@ -461,3 +461,206 @@ Supporting contracts (no direct REQ mapping — shared infrastructure):
 - `stream-json-sink-contract.md` (d1↔d4 joint) — enables REQ-M40-03
 
 All 5 REQs map to at least one task; no orphaned requirements. All 25 tasks across 7 domains trace to at least one REQ (task-brief/completion tasks support via contract infra).
+
+## M43 Universal Token Attribution (partition phase — 2026-04-21)
+
+Milestone 43 (Token Attribution & Always-Headless Inversion — target v3.17.10) decomposes into 6 measurable requirements across two themes. Task numbers reference `.gsd-t/domains/m43-*/tasks.md`.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M43-01 | Per-turn in-session token usage captured on every dialog turn; rows land in `.gsd-t/metrics/token-usage.jsonl` with `turn_id`, `session_id`, `sessionType: "in-session"` | D1 in-session-usage-capture | **Wave 1 complete (2026-04-21)** — Branch B locked (transcript-sourced, Stop-hook-triggered). Live end-to-end validated: 523 rows in sink from real transcript. |
+| REQ-M43-02 | Per-tool attribution via output-byte ratio — `gsd-t tool-cost --group-by tool\|command\|domain` shows non-zero attribution across Bash/Read/Edit/Grep/Task | D2 per-tool-attribution | pending (Wave 2) |
+| REQ-M43-03 | One canonical sink + schema v2 for all token rows; `.gsd-t/token-log.md` regeneratable view | D3 sink-unification-backfill | **complete (2026-04-21)** minus D3-T4.1 backfill parser follow-up |
+| REQ-M43-04 | Every command spawns; zero `--in-session` / `--headless` flag matches in `commands/*.md` after D4 | D4 default-headless-inversion | pending (Wave 3) |
+| REQ-M43-05 | Router dialog-growth meter warns when `/compact` predicted within N turns; pure read/warn, never refuses | D5 dialog-channel-meter | pending (Wave 2) |
+| REQ-M43-06 | Dashboard URL printed at every spawn; transcript viewer auto-launches on first spawn if not running; tool-cost panel renders against any spawn | D6 transcript-viewer-primary-surface | pending (Wave 2) |
+
+### D1 Branch Lock (2026-04-21)
+
+Branch B chosen. Evidence from `.gsd-t/.hook-probe/` payloads (captured during supervisor-2026-04-21-2320 session):
+
+- Stop / SessionEnd / PostToolUse hook payloads carry `session_id`, `transcript_path`, `cwd`, `hook_event_name` — **but no `usage`**.
+- `transcript_path` JSONL rows contain `message.usage` with `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`, `total_cost_usd` — same shape the M40 D4 aggregator already parses.
+
+**Hybrid chosen**: Stop hook = trigger, transcript = data source. `bin/gsd-t-in-session-usage.cjs::processHookPayload` reads the transcript since the last cursor, emits one v2-schema JSONL row per assistant turn with `sessionType: "in-session"`, `turn_id` (Claude `message.id`), `session_id` (hook `session_id`). Idempotent across replays via per-session transcript-line cursor.
+
+**Install path**: hook entry goes in user's `~/.claude/settings.json` (or project `.claude/settings.json`) — not written by the installer. The user wires it once:
+
+```json
+{ "matcher": "", "hooks": [
+    { "type": "command",
+      "command": "node \"$HOME/.claude/scripts/gsd-t-in-session-usage-hook.js\"",
+      "async": true } ] }
+```
+
+Supporting contracts:
+- `metrics-schema-contract.md` v2 — owns `turn_id`, `session_id`, `sessionType`, `tool_attribution[]`
+- `stream-json-sink-contract.md` v1.2.0 — formalizes dialog-channel entry-point (D1)
+- `tool-attribution-contract.md` v1.0.0 — output-byte ratio algorithm (D2, new contract)
+- `headless-default-contract.md` v2.0.0 — always-headless rule (D4, bump pending)
+
+## M44 Task-Graph Reader (D1 — execute phase 2026-04-22)
+
+Milestone 44 D1 ships the shared DAG that all downstream M44 domains (D2 parallel CLI, D3 command-file integration, D4 dep-graph validation, D5 file-disjointness prover, D6 pre-spawn economics) consume. Mode-agnostic: produces only a graph, owns no in-session vs unattended branching.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D1-01 | `bin/gsd-t-task-graph.cjs` parses every `.gsd-t/domains/*/tasks.md` into a typed in-memory DAG: nodes `{id, domain, wave, title, status, deps, touches}`, edges `{from, to}`, `ready` mask, `byId` index, `warnings[]` | m44-d1-task-graph-reader | **complete (2026-04-22)** — 22/22 unit tests pass |
+| REQ-M44-D1-02 | Cycle detection mandatory: throws `TaskGraphCycleError` with `.cycle: string[]` path on any circular dep — 3-task ring AND self-loop covered | m44-d1-task-graph-reader | **complete (2026-04-22)** — iterative three-color DFS; tests 3 + 4 |
+| REQ-M44-D1-03 | Touch-list resolution: prefer task `**Touches**` / `**Files touched**`, fall back to domain `scope.md` `## Files Owned`, fall back to `[]` + warning | m44-d1-task-graph-reader | **complete (2026-04-22)** — both fallback paths tested |
+| REQ-M44-D1-04 | Status markers: `[ ]` pending / `[x]` done / `[-]` skipped / `[!]` failed; unknown markers → pending + warning. Only `done` deps satisfy dependents (skipped/failed do NOT) | m44-d1-task-graph-reader | **complete (2026-04-22)** — covered by ready-mask tests |
+| REQ-M44-D1-05 | Read-only invariant: never writes to `tasks.md`, `scope.md`, or any contract file during build/query | m44-d1-task-graph-reader | **complete (2026-04-22)** — sync `readFileSync` only, no `writeFileSync` calls |
+| REQ-M44-D1-06 | Performance: parse + cycle-check + ready-mask in < 200 ms for 100-domain / 1000-task project | m44-d1-task-graph-reader | **complete (2026-04-22)** — measured 6 ms on 50-domain/250-task synthetic; 3 ms on this repo |
+| REQ-M44-D1-07 | CLI debugging surface: `gsd-t graph --output json` (pretty JSON) and `--output table` (id/domain/wave/status/ready/deps), backward-compat with existing `graph index/status/query` | m44-d1-task-graph-reader | **complete (2026-04-22)** — verified live: 33 tasks · 36 edges · 2 ready |
+
+Supporting contract:
+- `task-graph-contract.md` v1.0.0 — locks DAG schema; downstream M44 domains may begin implementation against this contract.
+
+## M44 Dep-Graph Validation (D4 — Wave 2 gate, 2026-04-22)
+
+Milestone 44 D4 ships the pre-spawn dependency gate. Given the DAG from D1 (`buildTaskGraph`), it filters the candidate-ready set to tasks whose declared `deps[]` are **all** in DONE status, and emits a `dep_gate_veto` event for every task it removes. The consumer (D2) decides whether to spawn a smaller batch or fall back to sequential — D4 itself is a pure filter. Mode-agnostic: same call shape in-session and unattended.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D4-01 | `bin/gsd-t-depgraph-validate.cjs` exports `validateDepGraph({graph, projectDir}) → {ready: TaskNode[], vetoed: {task, unmet_deps[]}[]}`. Synchronous. Never throws on unmet deps. | m44-d4-depgraph-validation | **complete (2026-04-22)** — 13/13 unit tests pass |
+| REQ-M44-D4-02 | Veto rule: a dep is satisfied iff `graph.byId[depId]` exists AND `status === 'done'`. Pending / skipped / failed / unknown all veto. (Matches `task-graph-contract.md` §5.) | m44-d4-depgraph-validation | **complete (2026-04-22)** — covered by skipped-dep, failed-dep, and unknown-dep tests |
+| REQ-M44-D4-03 | For every vetoed task, append one `dep_gate_veto` event to `.gsd-t/events/YYYY-MM-DD.jsonl` carrying the full base event schema (ts ISO 8601, event_type, command/phase/agent_id/parent_agent_id/trace_id/model null, reasoning="unmet deps: …", outcome="deferred") PLUS D4-additive fields `task_id`, `domain`, `unmet_deps[]` | m44-d4-depgraph-validation | **complete (2026-04-22)** — event-schema assertion test covers all fields |
+| REQ-M44-D4-04 | Non-throwing guarantee: unmet deps, unknown dep ids, and event-log I/O failures NEVER throw. Only malformed `opts` (missing `graph`) throws — programming error only. | m44-d4-depgraph-validation | **complete (2026-04-22)** — 20-task stress test + 3 throw-guard tests |
+| REQ-M44-D4-05 | Read-only on all domain artifacts. Only write surface is appending JSONL lines to `.gsd-t/events/YYYY-MM-DD.jsonl` (events directory created on demand). Zero external runtime deps. | m44-d4-depgraph-validation | **complete (2026-04-22)** — only `appendFileSync`/`mkdirSync` on events dir |
+| REQ-M44-D4-06 | Performance: adds < 50 ms to the pre-spawn path on a realistic 100-domain / 1000-task graph. O(R · D) where R = |candidate set|, D = avg deps/task. | m44-d4-depgraph-validation | **complete (2026-04-22)** — test suite runs in < 50 ms total |
+| REQ-M44-D4-07 | Synthetic gate fixture: a task with one unmet dep (unknown id) is vetoed; an independent task in the same ready set passes through. | m44-d4-depgraph-validation | **complete (2026-04-22)** — `M44-D4 gate fixture` test |
+
+Supporting contract:
+- `depgraph-validation-contract.md` v1.0.0 — locks veto semantics, dep_gate_veto event payload, non-throw guarantee, read-only invariant, and the D4 → D5 → D6 pre-spawn pipeline ordering. Downstream D2/D3 may wire in.
+
+## M44 File-Disjointness Prover (D5 — Wave 2 gate, 2026-04-22)
+
+Milestone 44 D5 ships the pre-spawn gate that proves every candidate parallel-spawn set writes disjoint files. If two tasks would both write the same file, D5 removes them from the parallel set and routes them to a sequential queue. Unprovable tasks (no touch-list source) are always routed sequential as singletons — safe-default, never assume disjoint. Mode-agnostic: same function used by in-session (D2) and unattended (D6) consumers.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D5-01 | `bin/gsd-t-file-disjointness.cjs` exports `proveDisjointness({tasks, projectDir})` → `{parallel: TaskNode[][], sequential: TaskNode[][], unprovable: TaskNode[]}`. Synchronous. Never throws. | m44-d5-file-disjointness-prover | **complete (2026-04-22)** — 11/11 unit tests pass |
+| REQ-M44-D5-02 | Touch-list source priority: (1) explicit `touches` populated by D1, (2) git-history heuristic bounded to 100 commits via `git log --name-only -n 100 -- .gsd-t/domains/<domain>/` intersecting with commit subjects containing the task id, (3) unprovable → always sequential | m44-d5-file-disjointness-prover | **complete (2026-04-22)** — fallback chain covered by `_resolveTouches` tests |
+| REQ-M44-D5-03 | Union-find grouping over the pairwise write-target overlap relation: component size 1 → parallel; component size ≥ 2 → sequential (transitive closure) | m44-d5-file-disjointness-prover | **complete (2026-04-22)** — 3-task transitive-closure test verified |
+| REQ-M44-D5-04 | For every task routed sequential (including unprovable singletons), append `{type:'disjointness_fallback', task_id, reason, ts}` to `.gsd-t/events/YYYY-MM-DD.jsonl`. Reasons: `unprovable` or `write-target-overlap`. Best-effort (silent on FS failure). | m44-d5-file-disjointness-prover | **complete (2026-04-22)** — event shape asserted in 3 tests |
+| REQ-M44-D5-05 | Read-only on all domain artifacts. Only write surface is the event stream. Git subprocess wrapped in try/catch. Zero external runtime deps. | m44-d5-file-disjointness-prover | **complete (2026-04-22)** |
+| REQ-M44-D5-06 | Robust input handling: `opts.tasks` missing/null, task missing `touches` field, empty candidate set — all return a valid partition without throwing | m44-d5-file-disjointness-prover | **complete (2026-04-22)** — robustness tests cover all four paths |
+
+Supporting contract:
+- `file-disjointness-contract.md` v1.0.0 — locks prover interface, fallback chain, and event format. Downstream D2/D6 may wire in.
+
+## M44 Per-CW Attribution (D7 — Wave 1 foundation, 2026-04-22)
+
+Milestone 44 D7 ships the per-Context-Window attribution surface that downstream consumers (D6 estimator calibration, the per-CW rollup in `gsd-t metrics`, the optimization report) need to keep working post-M44. Without `cw_id` on token-usage rows, every iter looks like a single CW even when Claude Code compacted mid-run; the calibration loop also needs a post-spawn signal so D6 can self-correct from the delta between predicted and observed CW utilization.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D7-01 | `bin/gsd-t-token-capture.cjs` accepts an optional `cw_id` field on `recordSpawnRow` / `captureSpawn`. When supplied, written to the JSONL row; when absent, omitted (NOT null, NOT ""). Pass-through only — wrapper does not derive `cw_id`. | m44-d7-per-cw-attribution | **complete (2026-04-22)** — 15/15 existing m41-token-capture tests still pass unchanged |
+| REQ-M44-D7-02 | `metrics-schema-contract.md` bumped v2 → v2.1.0 documenting `cw_id` field + derivation rules (unattended: `cw_id == spawn_id`; in-session: `session_id + ":" + compaction_index`) | m44-d7-per-cw-attribution | **complete (2026-04-22)** |
+| REQ-M44-D7-03 | `compaction-events-contract.md` bumped v1.0.0 → v1.1.0 adding `compaction_post_spawn` calibration event type appended to the same sink (`compactions.jsonl`); pairs `estimatedCwPct` with `actualCwPct` | m44-d7-per-cw-attribution | **complete (2026-04-22)** |
+| REQ-M44-D7-04 | `scripts/gsd-t-calibration-hook.js` SessionStart hook: on `source=compact`, correlates with active spawn from `.gsd-t/.unattended/state.json`, derives `actualCwPct` from `payload.input_tokens` ÷ CW ceiling, appends one calibration row. Silent no-op when no active spawn (supervisor not running). | m44-d7-per-cw-attribution | **complete (2026-04-22)** — 19/19 unit tests in `test/m44-cw-attribution.test.js` |
+| REQ-M44-D7-05 | Calibration hook safe to register alongside `scripts/gsd-t-compact-detector.js` — both fire on SessionStart, both write to the same sink, neither reads/writes the other's rows. Hook always exits 0 (throwing breaks Claude Code session start). | m44-d7-per-cw-attribution | **complete (2026-04-22)** — coexistence test verifies v1.0.0 detector rows remain intact when calibration row appended |
+| REQ-M44-D7-06 | Backward compatibility: every pre-D7 v2 row remains a valid v2.1.0 row. Pre-D7 callers (no `cw_id` supplied) produce byte-identical output. Historical `token-usage.jsonl` rows are NOT backfilled with `cw_id`. | m44-d7-per-cw-attribution | **complete (2026-04-22)** |
+
+Supporting contracts:
+- `metrics-schema-contract.md` v2.1.0 — adds optional `cw_id` field; documents producer ownership (M44 D7) and derivation rules
+- `compaction-events-contract.md` v1.1.0 — adds `compaction_post_spawn` calibration event; documents the calibration hook's lifecycle and guardrails
+
+Out of scope for D7:
+- Backfilling historical `token-usage.jsonl` rows with `cw_id` (consumers fall back to per-iter median for pre-D7 rows)
+- Modifying `scripts/gsd-t-compact-detector.js` (D7 adds a companion hook only)
+- Any economics logic (D6) or parallel dispatch logic (D2)
+
+## M44 Pre-Spawn Economics Estimator (D6 — Wave 2 gate, 2026-04-22)
+
+Milestone 44 D6 ships the pre-spawn economics estimator — a per-task CW-footprint predictor that feeds the D2 parallel-CLI's gating math with a `{estimatedCwPct, parallelOk, split, workerCount, matchedRows, confidence}` decision. D6 is a **HINT**, never a veto: it produces a mode-specific recommendation; D2 owns the final gate. Mode-aware: `estimatedCwPct` is mode-agnostic, but `parallelOk` uses 85 % CW for in-session (orchestrator-CW headroom) and 60 % for unattended (per-worker CW); unattended-only `split=true` when `estimatedCwPct > 60`.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D6-01 | `bin/gsd-t-economics.cjs` exports `estimateTaskFootprint({taskNode, mode, projectDir})` → `{estimatedCwPct, parallelOk, split, workerCount, matchedRows, confidence}`. Synchronous. Never returns `undefined` (global-median fallback guarantees a number). | m44-d6-pre-spawn-economics | **complete (2026-04-22)** — 9/9 unit tests pass |
+| REQ-M44-D6-02 | Three-tier corpus lookup: exact `command+step+domain` triplet (HIGH ≥5 rows, MEDIUM 1–4 rows), fuzzy (domain-only, then command-only) → LOW, global median → FALLBACK. Corpus loaded ONCE per `projectDir` (sync cached read), never re-read per call. | m44-d6-pre-spawn-economics | **complete (2026-04-22)** — all four tiers covered by tmpdir-fixture tests |
+| REQ-M44-D6-03 | Mode-specific gates: in-session `parallelOk = estimatedCwPct ≤ 85`, unattended `parallelOk = estimatedCwPct ≤ 60` + `split = estimatedCwPct > 60`. `split` is always `false` for in-session. CW ceiling = 200 K tokens (matches `token-budget.cjs` / `context-meter-config.cjs` / `runway-estimator.cjs`). | m44-d6-pre-spawn-economics | **complete (2026-04-22)** — both mode thresholds asserted under and over the boundary |
+| REQ-M44-D6-04 | Every call appends `{type:'economics_decision', ts, task_id, mode, estimatedCwPct, parallelOk, split, confidence, matchedRows}` to `.gsd-t/events/YYYY-MM-DD.jsonl`. Best-effort (silent on FS failure — never fails the estimate). | m44-d6-pre-spawn-economics | **complete (2026-04-22)** — event shape asserted in tests |
+| REQ-M44-D6-05 | Calibrated against the live 528-row `token-usage.jsonl` corpus. Per-tier MAE (% of CW ceiling): HIGH 12.89 %, MEDIUM 0.00 % (small-n tautology), LOW 13.08 %, FALLBACK 15.06 %. Known-failure modes documented in the contract (§10). | m44-d6-pre-spawn-economics | **complete (2026-04-22)** — contract v1.0.0 documents measured numbers |
+| REQ-M44-D6-06 | Zero external runtime deps (Node built-ins only). D6 is a HINT — D2 owns the final gate decision. | m44-d6-pre-spawn-economics | **complete (2026-04-22)** |
+
+Supporting contract:
+- `economics-estimator-contract.md` v1.0.0 — locks estimator interface, confidence tiers, mode-specific thresholds, event schema, known-failure modes, and calibration numbers. Downstream D2 may wire in.
+
+Out of scope for D6:
+- CW headroom arithmetic (D2 owns `computeInSessionHeadroom` / `computeUnattendedGate`)
+- Dep-graph validation (D4) and file disjointness (D5)
+- Writing back to `token-usage.jsonl` (read-only)
+- Multi-iter task slicing (D6 recommends `split=true`; the caller plans the iter breakdown)
+
+## M44 Parallel CLI (D2 — Wave 3 integration, 2026-04-23)
+
+Milestone 44 D2 ships the `gsd-t parallel` subcommand: a CLI wrapping the M40 orchestrator with task-level (not just domain-level) parallelism and mode-aware gating math. D2 consumes D1 (DAG), D4 (depgraph validation), D5 (disjointness prover), and D6 (economics estimator) and produces a validated worker plan. Extends — does not replace — the M40 orchestrator.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D2-01 | `bin/gsd-t-parallel.cjs` exports `runParallel({projectDir, mode, milestone, domain, dryRun})` and `runCli(argv, env)`. Node built-ins only; zero external runtime deps. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-02 | `gsd-t parallel --help` prints usage (flags + gates + modes + contract reference) and exits 0 without side effects. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-03 | `--mode in-session\|unattended` flag; auto-detect fallback: `GSD_T_UNATTENDED=1` → `unattended`, else `in-session`. Explicit `--mode` overrides env. Additional flags: `--milestone Mxx`, `--domain <name>`, `--dry-run`. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-04 | `bin/gsd-t-orchestrator-config.cjs` exports `computeInSessionHeadroom({ctxPct, workerCount, summarySize})` → `{ok, reducedCount}`. `ok=true` iff `ctxPct + workerCount × summarySize ≤ 85`; otherwise reduce N until it fits. Final floor is N=1 — NEVER returns `ok=false` (in-session must never throw pause/resume). | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-05 | `bin/gsd-t-orchestrator-config.cjs` exports `computeUnattendedGate({estimatedCwPct, threshold=60})` → `{ok, split}`. `split=true` when `estimatedCwPct > threshold`; caller MUST slice into multiple iters. Actual slicing is orchestrator responsibility. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-06 | `runParallel` wires three gates in sequence BEFORE any fan-out: D4 depgraph → D5 disjointness → D6 economics. Any veto emits `gate_veto` event `{type, task_id, gate, reason, ts}` and the task drops from the parallel batch (decision="sequential" or "veto-deps"). | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-07 | In-session mode reads `ctxPct` from `bin/token-budget.cjs::getSessionStatus()`. On reduction (`reducedCount < workerCount`), emits `parallelism_reduced` event `{type, original_count, reduced_count, reason:'in_session_headroom', ts}`. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-08 | Unattended mode calls D6 `estimateTaskFootprint` per task + `computeUnattendedGate`. On split, emits `task_split` event `{type, task_id, estimatedCwPct, ts}`. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-09 | `--dry-run` prints a fixed-width 6-column plan table (`task_id`, `domain`, `estimated CW%`, `disjoint?`, `deps ok?`, `decision`) followed by total worker count and mode; exits without spawning any workers. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+| REQ-M44-D2-10 | `.gsd-t/contracts/wave-join-contract.md` bumped v1.0.0 → v1.1.0 with §Mode-Aware Gating Math documenting both thresholds, `reducedCount` fallback behavior, the three event schemas, and invariant preservation. | m44-d2-parallel-cli | **complete (2026-04-23)** |
+
+Supporting contract:
+- `wave-join-contract.md` v1.1.0 — M44 D2 addendum locks the gating math surface, thresholds, and event schemas.
+
+Out of scope for D2:
+- Command file wiring (`commands/gsd-t-execute.md`, `gsd-t-wave.md`, etc.) — that is D3
+- Actual task slicing implementation (D2 only emits `task_split`; orchestrator executes)
+- Replacing or rewriting `bin/gsd-t-orchestrator.js` — M44 builds on M40
+
+## M44 Command-File Integration (D3 — Wave 3, 2026-04-23)
+
+Milestone 44 D3 wires the five primary GSD-T command files to the D2 `gsd-t parallel` CLI so task-level parallel dispatch becomes available from the standard workflow. D3 is purely additive doc-ripple + integration blocks — no new library code, no new spawns. Existing sequential code paths remain intact; the parallel path is a conditional that falls back silently when any gate vetoes or when only a single task is pending.
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D3-01 | `commands/gsd-t-execute.md` Step 3 gains an "Optional — Parallel Dispatch (M44)" block documenting the >1-pending-task + D4/D5/D6 gate conditional, `GSD_T_UNATTENDED` mode auto-detection (no hardcoded `--mode`), silent fallback to sequential, D2-owned observability, unattended zero-compaction invariant, and in-session never-interrupt invariant. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-02 | `commands/gsd-t-wave.md` EXECUTE phase (Step 3 Phase Orchestration Loop) documents that the spawned execute agent owns the parallel-vs-sequential decision internally; wave orchestrator inherits `GSD_T_UNATTENDED` and does not configure mode. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-03 | `commands/gsd-t-integrate.md` Step 3 (Wire Integration Points) gains a conditional block triggering only when integrating >1 domain simultaneously; single-domain wiring is unchanged. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-04 | `commands/gsd-t-quick.md` Step 3 (Execute) gains a lightweight conditional block — no-op for single-task quick invocations (the common case); triggers only when >1 pending task AND all gates pass. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-05 | `commands/gsd-t-debug.md` Step 3 (Debug Solo or Team) gains a conditional block triggering only for multi-domain contract-boundary/gap debug sessions; single-domain debug runs unchanged. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-06 | `commands/gsd-t-help.md` documents the `gsd-t parallel` CLI entry and detailed command block mirroring the style of adjacent entries (flags, reads/writes, contract reference). | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-07 | `docs/GSD-T-README.md` commands table reflects M44 D3 parallel-dispatch behavior in the rows for execute, wave, quick, debug, and integrate (1-line note per command). | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-08 | `README.md` Workflow Phases table mentions task-level parallelism via `gsd-t parallel --help` in the Execute row. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-09 | No command file hardcodes `--mode` — every integration block explicitly states that mode is auto-detected from `GSD_T_UNATTENDED=1`. No `--in-session` opt-out flag exists in any of the 5 command files. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+| REQ-M44-D3-10 | `docs/architecture.md` documents the parallel dispatch decision flow (command file → D2 `gsd-t parallel` → D4/D5/D6 gates → M40 orchestrator → workers) as a single authoritative diagram. | m44-d3-command-file-integration | **complete (2026-04-23)** |
+
+Supporting contract:
+- `wave-join-contract.md` v1.1.0 — the D2 CLI surface referenced by every D3 integration block.
+
+Out of scope for D3:
+- The parallel execution logic (D2 owns it)
+- Any gate logic (D4 depgraph, D5 file-disjointness, D6 economics)
+- Modifying `bin/gsd-t.js` or any other CLI router (D2-owned)
+- Creating new test files — command files are validated by use per project CLAUDE.md conventions
+- Modifying the commands' non-parallel code paths — integration blocks are ADDITIVE only
+
+## M44 Spawn Plan Visibility (D8 — Wave 3 observability, 2026-04-23)
+
+Milestone 44 D8 delivers a right-side two-layer task panel in the dashboard and transcript visualizer. Layer 1 surfaces the full project/milestone task plan; Layer 2 scopes down to the currently-active spawn. Done tasks display a compact token cell (`in=Nk out=Nk $X.XX`). A post-commit git hook flips task status to `done` and performs token attribution by scanning `.gsd-t/token-log.md` rows within the spawn's time window. One protocol, three writers (`captureSpawn`, `autoSpawnHeadless`, unattended worker resume Step 0), one reader (dashboard SSE + transcript HTML panel).
+
+| REQ-ID | Requirement Summary | Domain | Status |
+|--------|---------------------|--------|--------|
+| REQ-M44-D8-01 | `bin/spawn-plan-writer.cjs` exports `writeSpawnPlan({spawnId, kind, milestone, wave, domains, tasks, projectDir})` with atomic temp+rename writes into `.gsd-t/spawns/{spawnId}.json`. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-02 | `bin/spawn-plan-status-updater.cjs` exports `markTaskDone({spawnId, taskId, commit, tokens?, projectDir})` and `markSpawnEnded({spawnId, endedReason, projectDir})` with atomic rewrites. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-03 | Post-commit hook (`scripts/gsd-t-post-commit-spawn-plan.sh` + template `templates/hooks/post-commit-spawn-plan.sh`) greps commit messages for `[M\d+-D\d+-T\d+]` matches and flips matching tasks in every active spawn plan (where `endedAt === null`). Silent-fail (exit 0) on any error. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-04 | Token attribution: hook parses `.gsd-t/token-log.md` rows where `Task` column matches the task id AND `Datetime-start >= spawn.startedAt`, sums `in/out/cr/cc/cost_usd`, writes to the task's `tokens` field. Null renders as `—` per the "zero is a measurement, dash is a gap" rule. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-05 | Writer integration at 3 chokepoints — `bin/gsd-t-token-capture.cjs` `captureSpawn` calls `writeSpawnPlan` before `spawnFn()` and `markSpawnEnded` after (success + error both); `bin/headless-auto-spawn.cjs` before child launch; `commands/gsd-t-resume.md` Step 0 under `GSD_T_UNATTENDED_WORKER=1`. All try/catch-wrapped — writer failure never blocks the spawn. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-06 | `bin/spawn-plan-derive.cjs` exports `derivePlanFromPartition({projectDir, milestone, currentIter})` that reads `.gsd-t/partition.md` + `.gsd-t/domains/*/tasks.md` and returns the `{wave, domains, tasks}` slice for the current incomplete-tasks wave. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-07 | Dashboard server gains `GET /api/spawn-plans` (returns array of plan files where `endedAt === null`) and a `spawn-plan-update` SSE channel (fs.watch on `.gsd-t/spawns/*.json` with mtime-deduplicated emits). Additive — existing endpoints and SSE channels unchanged. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-08 | `scripts/gsd-t-transcript.html` gains a right-side `<aside class="spawn-panel">` with two `<section>` layers, status icons `☐ ◐ ✓` (only one `◐` per spawn at a time), and the `fmtTokens({in,out,cr,cc,cost_usd})` renderer producing `in=12.5k out=1.7k $0.42` with k-suffix above 1000 and 2-decimal USD. Cumulative totals computed at milestone and spawn scope. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-09 | No new LLM token cost — all writers derive plans deterministically from partition.md + tasks.md; reader is browser-only; status updater is shell + node. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+| REQ-M44-D8-10 | 5 test suites covering writer, status updater, post-commit hook (including token-log attribution), dashboard endpoint + SSE, and transcript renderer panel — 36 tests, all passing. | m44-d8-spawn-plan-visibility | **complete (2026-04-23)** |
+
+Supporting contract:
+- `.gsd-t/contracts/spawn-plan-contract.md` v1.0.0 — schema + writer/reader/updater protocol + silent-fail rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.16.12",
+  "version": "3.18.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-calibration-hook.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-calibration-hook.js
+ *
+ * SessionStart hook that records a calibration event whenever Claude Code
+ * fires `source=compact` AND we can correlate the compaction with an
+ * active unattended spawn.
+ *
+ * The output is one NDJSON row appended to
+ * `<cwd>/.gsd-t/metrics/compactions.jsonl`, alongside the rows produced by
+ * the v1.0.0 detector (`scripts/gsd-t-compact-detector.js`). The two hooks
+ * are independent listeners on the same stdin payload and do not interact.
+ *
+ *   { "type": "compaction_post_spawn", "schemaVersion": 1,
+ *     "ts": ..., "cw_id": ..., "task_id": ..., "spawn_id": ...,
+ *     "estimatedCwPct": ..., "actualCwPct": ... }
+ *
+ * The pairing of `estimatedCwPct` (D6's pre-spawn prediction) with
+ * `actualCwPct` (derived from the live compaction event) is what makes
+ * the calibration loop actionable — D6's estimator can self-correct from
+ * the delta.
+ *
+ * Behavior:
+ * - Zero-dep. Reads stdin JSON, silently fails on any error. Always exits
+ *   0 — throwing here would break Claude Code session startup.
+ * - Only acts when `payload.source === "compact"`.
+ * - Silently no-ops when `<cwd>/.gsd-t/.unattended/state.json` is missing,
+ *   unparseable, not running, or carries no spawn correlation. The
+ *   supervisor may not be running when a manual session compacts —
+ *   accepted.
+ * - Safe to register alongside `gsd-t-compact-detector.js`. Both fire on
+ *   SessionStart, both read the same payload, both write to the same
+ *   sink, and neither reads or writes the other's rows.
+ *
+ * Contract: .gsd-t/contracts/compaction-events-contract.md (v1.1.0)
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const MAX_STDIN = 1024 * 1024; // 1 MiB
+const SCHEMA_VERSION = 1;
+const DEFAULT_CW_CEILING_TOKENS = 200000; // input-token budget per CW
+
+if (require.main === module) {
+  let input = "";
+  let aborted = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    input += chunk;
+    if (input.length > MAX_STDIN) {
+      aborted = true;
+      try { process.stdin.destroy(); } catch { /* noop */ }
+    }
+  });
+  process.stdin.on("error", () => { /* silent */ });
+  process.stdin.on("end", () => {
+    if (aborted) { exitClean(); return; }
+    try {
+      handle(input);
+    } catch {
+      // silent — never throw from a SessionStart hook
+    }
+    exitClean();
+  });
+}
+
+/**
+ * Handle a single SessionStart payload. Pure-ish: I/O is via fs but no
+ * argument is mutated. Exported for testing.
+ *
+ * @param {string} rawInput  raw stdin contents (UTF-8 JSON or empty)
+ * @param {object} [overrides] test injection: { cwd, now }
+ * @returns {object|null}    the row that was written, or null if no-op
+ */
+function handle(rawInput, overrides = {}) {
+  let payload;
+  try {
+    payload = JSON.parse(rawInput);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object") return null;
+  if (payload.source !== "compact") return null;
+
+  const cwd = resolveCwd(payload, overrides);
+  if (!cwd) return null;
+
+  const gsdDir = path.join(cwd, ".gsd-t");
+  if (!fs.existsSync(gsdDir)) return null;
+
+  const correlation = readActiveSpawn(cwd);
+  if (!correlation) return null; // silent no-op when no active spawn
+
+  const actualCwPct = deriveActualCwPct(payload, correlation.cwCeilingTokens);
+  if (actualCwPct == null) return null;
+
+  const metricsDir = path.join(gsdDir, "metrics");
+  const outPath = path.join(metricsDir, "compactions.jsonl");
+
+  const resolvedOut = path.resolve(outPath);
+  const resolvedMetrics = path.resolve(metricsDir) + path.sep;
+  if (!resolvedOut.startsWith(resolvedMetrics)) return null;
+
+  try {
+    fs.mkdirSync(metricsDir, { recursive: true });
+  } catch {
+    return null;
+  }
+
+  const now = (overrides.now instanceof Date) ? overrides.now : new Date();
+  const row = {
+    type: "compaction_post_spawn",
+    schemaVersion: SCHEMA_VERSION,
+    ts: now.toISOString(),
+    cw_id: correlation.cw_id,
+    task_id: correlation.task_id,
+    spawn_id: correlation.spawn_id,
+    estimatedCwPct: correlation.estimatedCwPct,
+    actualCwPct,
+  };
+
+  fs.appendFileSync(outPath, JSON.stringify(row) + "\n", "utf8");
+  return row;
+}
+
+/**
+ * Resolve a usable cwd from the payload, mirroring detector semantics:
+ * absolute string → use as-is; missing/null → fall back to process.cwd();
+ * any other shape → no-op (return null).
+ */
+function resolveCwd(payload, overrides) {
+  if (overrides && typeof overrides.cwd === "string") return overrides.cwd;
+  if (typeof payload.cwd === "string") {
+    if (!path.isAbsolute(payload.cwd)) return null;
+    return payload.cwd;
+  }
+  if (payload.cwd === undefined || payload.cwd === null) return process.cwd();
+  return null;
+}
+
+/**
+ * Read the supervisor's view of the currently-active spawn from
+ * `.gsd-t/.unattended/state.json`. Returns null when:
+ *   - the file is missing / unreadable / not JSON
+ *   - state.status is not "running"
+ *   - we cannot derive a spawn_id (no sessionId)
+ *
+ * The fields we expose:
+ *   - cw_id   : per-CW attribution key (== spawn_id for unattended workers)
+ *   - task_id : active task identifier, if the supervisor recorded one
+ *   - spawn_id: stable spawn identifier (sessionId for unattended)
+ *   - estimatedCwPct: D6's pre-spawn prediction (if supervisor recorded it)
+ *   - cwCeilingTokens: optional override of the default ceiling
+ */
+function readActiveSpawn(cwd) {
+  const statePath = path.join(cwd, ".gsd-t", ".unattended", "state.json");
+  let raw;
+  try {
+    raw = fs.readFileSync(statePath, "utf8");
+  } catch {
+    return null;
+  }
+  let state;
+  try {
+    state = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!state || typeof state !== "object") return null;
+  if (state.status !== "running") return null;
+
+  const spawn_id =
+    (typeof state.activeSpawnId === "string" && state.activeSpawnId) ||
+    (typeof state.spawn_id === "string" && state.spawn_id) ||
+    (typeof state.sessionId === "string" && state.sessionId) ||
+    null;
+  if (!spawn_id) return null;
+
+  const cw_id =
+    (typeof state.cw_id === "string" && state.cw_id) ||
+    (typeof state.activeCwId === "string" && state.activeCwId) ||
+    spawn_id; // unattended: one spawn = one CW
+
+  const task_id =
+    (typeof state.activeTask === "string" && state.activeTask) ||
+    (typeof state.task_id === "string" && state.task_id) ||
+    (typeof state.currentTask === "string" && state.currentTask) ||
+    null;
+
+  let estimatedCwPct = null;
+  for (const key of ["estimatedCwPct", "estimated_cw_pct", "predictedCwPct"]) {
+    if (typeof state[key] === "number" && Number.isFinite(state[key])) {
+      estimatedCwPct = state[key];
+      break;
+    }
+  }
+
+  let cwCeilingTokens = DEFAULT_CW_CEILING_TOKENS;
+  for (const key of ["cwCeilingTokens", "cw_ceiling_tokens", "cwCeiling"]) {
+    if (typeof state[key] === "number" && state[key] > 0) {
+      cwCeilingTokens = state[key];
+      break;
+    }
+  }
+
+  return { cw_id, task_id, spawn_id, estimatedCwPct, cwCeilingTokens };
+}
+
+/**
+ * Derive actualCwPct (0.0–2.0) from the compaction payload. Looks at
+ * `payload.input_tokens`, then falls back to nested fields used by the
+ * scanner's compactMetadata shape. Returns null when nothing usable.
+ */
+function deriveActualCwPct(payload, cwCeilingTokens) {
+  const ceiling = (typeof cwCeilingTokens === "number" && cwCeilingTokens > 0)
+    ? cwCeilingTokens
+    : DEFAULT_CW_CEILING_TOKENS;
+
+  let inputTokens = null;
+  if (typeof payload.input_tokens === "number" && payload.input_tokens >= 0) {
+    inputTokens = payload.input_tokens;
+  } else if (typeof payload.preTokens === "number" && payload.preTokens >= 0) {
+    inputTokens = payload.preTokens;
+  } else if (payload.compactMetadata && typeof payload.compactMetadata === "object") {
+    const m = payload.compactMetadata;
+    if (typeof m.preTokens === "number" && m.preTokens >= 0) {
+      inputTokens = m.preTokens;
+    }
+  }
+  if (inputTokens == null) return null;
+
+  const pct = inputTokens / ceiling;
+  // Clamp: keep within a sane band. We allow >1.0 (ceiling can be lower
+  // than the actual hard limit) but cap at 2.0 to avoid runaway values.
+  if (!Number.isFinite(pct) || pct < 0) return 0;
+  if (pct > 2) return 2;
+  return pct;
+}
+
+function exitClean() {
+  try { process.stdout.write(""); } catch { /* noop */ }
+  process.exit(0);
+}
+
+module.exports = {
+  handle,
+  // Exported for white-box testing only:
+  _readActiveSpawn: readActiveSpawn,
+  _deriveActualCwPct: deriveActualCwPct,
+  _resolveCwd: resolveCwd,
+  SCHEMA_VERSION,
+  DEFAULT_CW_CEILING_TOKENS,
+};