@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.18.11] - 2026-04-23
+
+### Fixed
+
+- **Flaky `m43-dashboard-autostart` test under load** — bumped `_isPortBusySync` spawnSync timeout from 2s → 10s. Under saturated full-suite execution the 2s budget could expire before the probe child even reported back, causing a falsely-free port reading and intermittent assertion failures. The 10s budget is comfortably above any observed real-world probe latency while still bounding hung-child cases.
+- **Stale snapshot test in `m43-milestone-complete-detection`** — replaced the live-state assertion that hard-coded `M43=PARTITIONED` (true at the time the test was written, false ever since M43 completed) with an M42-only sanity check. M42 is the oldest stable terminal milestone and serves as a fixed anchor that won't go stale every release. The other 7 tests in the file already cover the actual `isMilestoneComplete` matcher logic via `withTmpProgress` fixtures.
+
+## [3.18.10] - 2026-04-23
+
+### Added — Cross-Domain & Cross-Task Parallelism (M44)
+
+Task-level parallelism shipped to **both** execution modes (in-session and unattended) on equal footing, with mode-aware gating math. 8 of 9 domains landed (D1–D8 DONE; D9 parallelism-observability grafted as backlog #16 follow-up). 3 waves, 1903/1907 tests pass (4 pre-existing unrelated fails).
+
+**Wave 1 foundation:**
+- **D1 — Generic task-graph reader**: typed DAG + cycle detection + `gsd-t graph` CLI. 22/22 tests, contract v1.0.0.
+- **D7 — Per-CW token attribution**: `cw_id` pass-through + post-spawn calibration hook. 19/19 tests; contracts metrics-schema v2.1.0 + compaction-events v1.1.0.
+
+**Wave 2 parallel:**
+- **D4 — Dep-graph veto gate**: refuses fan-out when deps unmet. 4/4 tasks, 13/13 tests.
+- **D5 — File-disjointness prover**: union-find + git-history fallback. 4/4 tasks, 11/11 tests.
+- **D6 — Pre-spawn economics estimator**: 3-tier corpus lookup (mode-aware 85%/60% thresholds) calibrated against 528-row corpus. 5/5 tasks, 9/9 tests, contract v1.0.0.
+
+**Wave 3:**
+- **D2 — `gsd-t parallel` CLI**: mode-aware gating math (in-session 85% + N=1 floor; unattended 60% + task_split signal). 5/5 tasks, 21/21 tests; wave-join-contract v1.0.0 → v1.1.0.
+- **D8 — Spawn-plan-visibility**: right-side two-layer panel + `/api/spawn-plans` endpoint + SSE + post-commit token attribution hook. 7/7 tasks, 36/36 tests, contract v1.0.0.
+- **D3 — Command-file integration**: additive "Optional — Parallel Dispatch (M44)" blocks in `execute`/`wave`/`quick`/`debug`/`integrate`. No hardcoded `--mode`; silent fallback to sequential. 5/5 tasks; smoke-test fixtures deferred to backlog #15.
+
+**Mode contracts (NON-NEGOTIABLE):**
+- **[in-session]** Speed + reduce compaction as much as possible. Hard rule: NEVER throw an interactive pause/resume prompt.
+- **[unattended]** Run M1 → M10 end-to-end with zero human involvement and zero compaction. Per-worker CW headroom is the binding gate.
+
+## [3.17.10] - 2026-04-21
+
+### Added — Token Attribution & Always-Headless Inversion (M43)
+
+Every token is now attributable to a specific tool / command / domain, and the framework is locked to a single rule: **the in-session channel is reserved for human↔Claude dialog. All tool-using work spawns. The visualizer is the watching surface.** No flags, no thresholds, no opt-outs — there is no "in-session mode" for commands to enter.
+
+**Part A — Universal Token Attribution**
+
+**In-session usage capture (D1)**: `bin/gsd-t-in-session-usage.cjs` exports `captureInSessionUsage({projectDir, sessionId, turnId, usage, model})` and `processHookPayload({projectDir, payload})`. Branch B locked: Stop hook triggers, Claude Code transcript (`~/.claude/projects/-.../{sessionId}.jsonl`) is the data source. Writes v2-schema JSONL rows with `sessionType: "in-session"` + distinct `turn_id` + parsed `input_tokens`/`output_tokens`/`cache_read_input_tokens`. Idempotent via transcript-line cursor. Live-validated: 523 rows from one 23-min session (`.gsd-t/.hook-probe/` evidence retained).
+
+**Per-tool attribution (D2)**: `.gsd-t/contracts/tool-attribution-contract.md` v1.0.0 + `bin/gsd-t-tool-attribution.cjs` exports `joinTurnsAndEvents` / `attributeTurn` / `aggregateByTool|Command|Domain`. Output-byte ratio algorithm, 4 tie-breakers (zero-byte turn, missing tool_result, no tool calls, null usage). New CLI: `gsd-t tool-cost [--group-by tool|command|domain] [--since YYYY-MM-DD] [--milestone Mxx] [--format table|json]`. Perf gate: 30ms on 3k turns × 30k events fixture (budget 3s). `gsd-t tokens --show-tool-costs` optional integration adds "Top 10 tools by cost" section.
+
+**Sink unification + schema v2 (D3)**: `.gsd-t/contracts/metrics-schema-contract.md` bumped v1 → v2 — adds optional `turn_id`, `session_id`, `sessionType`, `tool_attribution[]`, `compaction_pressure{}`. `recordSpawnRow` / `captureSpawn` pass-through preserves backward compat. `bin/gsd-t-token-regenerate-log.cjs` + `gsd-t tokens --regenerate-log` makes `.gsd-t/token-log.md` a regenerated view (streaming read + deterministic sort).
+
+**Part B — Always-Headless Inversion (Channel Separation)**
+
+**Default headless spawn (D4)**: `bin/headless-auto-spawn.cjs::shouldSpawnHeadless` collapsed to `() => true`. Removed low-water branch, context-meter-driven branching, `--in-session` opt-out parsing. Legacy `watch`/`inSession` params accepted-and-ignored with one-shot stderr deprecation warning. 7 command files stripped of spawn-mode branching (`execute`, `wave`, `integrate`, `quick`, `debug`, `verify`, `scan`). `/gsd` router preserves in-session classification only for dialog-only exploratory turns — all action turns spawn detached. `.gsd-t/contracts/headless-default-contract.md` bumped v1.0.0 → **v2.0.0** (breaking: flag removal). 40 matrix tests.
+
+**Dialog-channel growth meter (D5)**: `bin/runway-estimator.cjs::estimateDialogGrowth({projectDir, sessionId, k = 5, modelContextCap = 200000})` returns `{slope, median_delta, latest_input_tokens, predicted_turns_to_compact, shouldWarn}`. Outlier-resistant median-of-deltas. When `shouldWarn=true`, `/gsd` router appends a one-line blockquote footer suggesting `/compact` or detached spawn. Pure read/warn — never refuses, never reroutes (there's nothing to reroute to under channel separation). Scope collapsed from originally-sketched circuit breaker; `.gsd-t/contracts/context-meter-contract.md` bumped v1.3.0 → v1.4.0 (additive subsection).
+
+**Transcript viewer as primary surface (D6)**: `scripts/gsd-t-dashboard-server.js` gains `GET /transcript/:id/tool-cost` (D2-backed, 503 graceful fallback) + `GET /transcript/:id/usage` (per-turn JSONL rows). `scripts/gsd-t-transcript.html` gains collapsible Tool Cost sidebar panel with live SSE updates. `bin/headless-auto-spawn.cjs` prints `▶ Live transcript: http://127.0.0.1:{port}/transcript/{spawn-id}` on every spawn. New `scripts/gsd-t-dashboard-autostart.cjs` — `ensureDashboardRunning({projectDir})` port-probe + fork-detach + pid file, hooked into spawn start path (idempotent). `.gsd-t/contracts/dashboard-server-contract.md` bumped (routes + banner format + autostart sections).
+
+**Tests**: 1708/1710 pass (2 pre-existing unrelated fails). Net additions across D1–D6: ~90 new test cases.
+
+## [3.16.10] - 2026-04-20
+
+### Added — Live Spawn Transcript Viewer (M42)
+
+Per-spawn live transcript UI on `:7433`: stream-json tee (`bin/gsd-t-transcript-tee.cjs`), SSE route (`/transcript/:id/stream`), Claude-Code-style ndjson renderer (`scripts/gsd-t-transcript.html`), sidebar tree with parent-indent + status dots, per-spawn kill button (POST `/transcript/:id/kill`). 29 M42-specific tests; 1522/1522 suite. Intervene/SIGSTOP deferred to follow-up milestone.
+
 ## [3.15.10] - 2026-04-20
 
 ### Added — Universal Token Capture Across GSD-T (M41)

package/README.md

@@ -14,10 +14,11 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 **Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
 **External Task Orchestrator + Streaming Watcher UI (M40, v3.14.10)** — JS orchestrator drives `claude -p` one task per spawn: short-lived, fresh context, architecturally compaction-free. Benchmarks 0.72× wall-clock vs in-session on 20-task/3-wave workloads. Paired with a zero-Claude-cost local streaming UI at `127.0.0.1:7842` that renders all workers' stream-json output as a continuous claude.ai-style feed — task/wave banners, duration + usage chips, token corner bar, localStorage filters, replay via `WS /feed?from=N`. Recovery: `--resume` reconciles interrupted runs using commit + progress.md evidence; ambiguous tasks (commit without progress entry) are flagged for operator triage, never silently claimed done. CLI: `gsd-t orchestrate`, `gsd-t benchmark-orchestrator`, `gsd-t stream-feed`. Contracts: `stream-json-sink-contract.md` v1.1.0, `wave-join-contract.md`, `completion-signal-contract.md`, `metrics-schema-contract.md`.
-**Headless-by-Default Spawn (M38, v3.12.10)** — long-running workflow commands (execute, wave, integrate, debug repair loops) spawn detached by default. The interactive session prints a launch banner, logs the event-stream path, and exits. Pass `--watch` to keep a live status block in the session (270s `ScheduleWakeup` ticks, cache-window-safe). Detached workers emit JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by watch command and dashboard. See `.gsd-t/contracts/headless-default-contract.md` v1.0.0 and `unattended-event-stream-contract.md` v1.0.0.
+**Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation** — every GSD-T command spawns detached, unconditionally. No `--watch`, no `--in-session`, no `--headless` opt-in, no context-meter threshold that reroutes. The dialog channel is reserved for human↔Claude conversation; every workflow turn is a detached headless child. Interactive session shows a launch banner + live-transcript URL + event-stream path, then exits — results surface via the read-back banner on the user's next message. Detached workers emit JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by dashboard and (historically) the watch command. The only in-session surface is the `/gsd` router (for dialog-only exploratory turns). See `.gsd-t/contracts/headless-default-contract.md` v2.0.0 and `unattended-event-stream-contract.md` v1.0.0.
+**Live Transcript as Primary Surface (M43 D6, v3.16.13)** — every detached spawn prints a one-line banner (`▶ Live transcript: http://127.0.0.1:{port}/transcript/{id}`) pointing at a browser viewer that SSE-streams the child's stdout and renders a collapsible "Tool Cost" sidebar panel showing per-tool attributed tokens and cost (sourced from `/transcript/:id/tool-cost`, which proxies to the M43 D2 tool-attribution library). The dashboard server auto-starts (`scripts/gsd-t-dashboard-autostart.cjs`) idempotently on each spawn — a port probe backs off when a server is already running, otherwise a fork-detach writes `.gsd-t/.dashboard.pid`. Port is project-scoped via `projectScopedDefaultPort(projectDir)` so multi-project workflows don't clobber each other. Contract: `dashboard-server-contract.md` v1.2.0.
 - **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
 - **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn.
-**Context Meter (M34/M38)** — PostToolUse hook writes `.gsd-t/.context-meter-state.json` via local token estimation. Single-band model (`context-meter-contract.md` v1.3.0): one threshold (default 85%), one action — hand off to a detached headless spawn. The meter informs spawn-time routing, not in-flight pauses.
+**Context Meter (M34/M38/M43 D4) — Observational Only** — PostToolUse hook writes `.gsd-t/.context-meter-state.json` via local token estimation. Under M43 D4 (channel-separation inversion, `headless-default-contract.md` v2.0.0) the meter is OBSERVATIONAL ONLY: the pct is recorded into the token-log `Ctx%` column on the next spawn, but no threshold gates any routing decision — every command spawns detached regardless. The `context-meter-contract.md` single-band model is preserved for the value itself; it no longer drives in-flight pauses or spawn-time rerouting.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
 **Design Verification Agent** — after QA passes on design-to-code projects, a dedicated verification agent opens a browser with both the built frontend AND the original design (Figma page, design image, or MCP screenshot) side-by-side for direct visual comparison. Produces a structured element-by-element comparison table (30+ rows) with specific design values vs. implementation values and MATCH/DEVIATION verdicts. An artifact gate enforces that the comparison table exists — missing it blocks completion. Separation of concerns: coding agents code, verification agents verify. Wired into execute (Step 5.25) and quick (Step 5.25). Only fires when `.gsd-t/contracts/design-contract.md` exists — non-design projects are unaffected.
@@ -101,8 +102,17 @@ gsd-t headless --debug-loop --max-iterations=10         # Cap at 10 iterations
 gsd-t headless --debug-loop --test-cmd="npm test"       # Override test command
 gsd-t headless --debug-loop --fix-scope="src/auth/**"   # Limit fix scope
 gsd-t headless --debug-loop --json --log                # Structured output + per-iteration logs
+
+# Parallel CLI (M44 D2 — task-level parallelism, mode-aware gating)
+gsd-t parallel --help                                   # Usage, flags, gates, contract ref
+gsd-t parallel --dry-run                                # Print worker plan table + exit (no spawn)
+gsd-t parallel --mode in-session --dry-run              # 85% orchestrator-CW ceiling; N=1 floor
+gsd-t parallel --mode unattended --dry-run              # 60% per-worker ceiling; > 60% → task_split
+gsd-t parallel --milestone M44 --domain m44-d2-parallel-cli --dry-run
 ```
 
+`gsd-t parallel` consumes the M44 task-graph (D1) and applies three pre-spawn gates (D4 depgraph validation → D5 file-disjointness → D6 economics) followed by mode-aware headroom/split math. Extends — does not replace — the M40 orchestrator. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+
 Each iteration runs as a fresh `claude -p` session. A cumulative debug ledger (`.gsd-t/debug-state.jsonl`) preserves hypothesis/fix/learning history across sessions. An anti-repetition preamble prevents retrying failed approaches.
 
 **Escalation tiers**: sonnet (iterations 1–5) → opus (6–15) → STOP with diagnostic summary (16–20)
@@ -235,7 +245,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | **Discuss** | Explore design decisions | Both |
 | **Plan** | Create atomic task lists | Solo (always) |
 | **Impact** | Downstream effect analysis | Solo |
-| **Execute** | Build it | Both |
+| **Execute** | Build it — task-level parallelism via `gsd-t parallel --help` (M44 D2/D3); conditional on >1 gate-passing task, falls back to sequential silently | Both |
 | **Test-Sync** | Maintain test coverage | Solo |
 | **Integrate** | Wire domains together | Solo (always) |
 | **Verify** | Quality gates | Both |

package/bin/gsd-t-depgraph-validate.cjs

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * gsd-t-depgraph-validate — M44 D4
+ *
+ * Pre-spawn dependency gate. Consumes the DAG from `bin/gsd-t-task-graph.cjs`
+ * and filters candidate-ready tasks down to those whose declared `deps[]`
+ * are all in DONE status. Vetoed tasks (any unmet dep, or any dep
+ * referencing an unknown task id) are removed from the returned ready set
+ * AND appended to the event stream as `dep_gate_veto` records so that
+ * "why wasn't this task spawned?" is observable.
+ *
+ * Contract: .gsd-t/contracts/depgraph-validation-contract.md (v1.0.0)
+ *
+ * Hard rules (from constraints.md):
+ *   - Zero external runtime deps (Node built-ins only)
+ *   - Never throws on unmet deps; only throws on programming errors
+ *   - Read-only on tasks.md / scope.md / contracts; only writes appended
+ *     JSONL lines to .gsd-t/events/YYYY-MM-DD.jsonl
+ *   - Synchronous; < 50 ms on realistic graphs
+ *   - Mode-agnostic (no in-session vs unattended branching)
+ *   - A task's dep is satisfied iff graph.byId[depId] exists AND
+ *     byId[depId].status === 'done' (skipped/failed/pending all veto)
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// ─── event stream writer (self-contained; no external deps) ───────────────
+
+/**
+ * Append one JSON-line event to `.gsd-t/events/YYYY-MM-DD.jsonl`.
+ * Creates the events directory on demand. Never throws on I/O failure —
+ * event logging must never break the caller's control flow.
+ */
+function appendEvent(projectDir, event) {
+  try {
+    const eventsDir = path.join(projectDir, ".gsd-t", "events");
+    fs.mkdirSync(eventsDir, { recursive: true });
+    const day = event.ts.slice(0, 10); // YYYY-MM-DD from ISO string
+    const file = path.join(eventsDir, `${day}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(event) + "\n");
+  } catch {
+    // Intentionally swallowed — D4 must not throw on event-log failure.
+  }
+}
+
+/**
+ * Build a `dep_gate_veto` event with the base event-schema fields filled in
+ * (null for optional context the gate doesn't own) plus the D4-specific
+ * extras documented in depgraph-validation-contract.md §4.
+ */
+function buildVetoEvent(task, unmetDeps) {
+  return {
+    ts: new Date().toISOString(),
+    event_type: "dep_gate_veto",
+    command: null,
+    phase: null,
+    agent_id: null,
+    parent_agent_id: null,
+    trace_id: null,
+    reasoning: `unmet deps: ${unmetDeps.join(", ")}`,
+    outcome: "deferred",
+    model: null,
+    // D4-specific additive fields:
+    task_id: task.id,
+    domain: task.domain,
+    unmet_deps: unmetDeps.slice(),
+  };
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Validate that each candidate-ready task has all of its deps satisfied.
+ * Returns the reduced ready set (node objects, ordered as in graph.ready)
+ * and the list of vetoes (one per task, carrying the full node + the
+ * unmet-dep ids).
+ *
+ * Never throws on unmet deps; only throws on malformed input.
+ *
+ * @param {{graph: object, projectDir: string}} opts
+ * @returns {{ready: object[], vetoed: {task: object, unmet_deps: string[]}[]}}
+ */
+function validateDepGraph(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("validateDepGraph: opts must be an object");
+  }
+  const { graph, projectDir } = opts;
+  if (!graph || typeof graph !== "object") {
+    throw new TypeError("validateDepGraph: opts.graph must be the DAG object from buildTaskGraph");
+  }
+  const byId = graph.byId || Object.create(null);
+  const pd = projectDir || process.cwd();
+
+  // Candidate set: if graph.ready exists use it, else fall back to every
+  // pending node (defensive — keeps the function useful when the caller
+  // passes a hand-built fixture graph without a pre-computed ready mask).
+  let candidateIds;
+  if (Array.isArray(graph.ready) && graph.ready.length) {
+    candidateIds = graph.ready.slice();
+  } else if (Array.isArray(graph.nodes)) {
+    candidateIds = graph.nodes
+      .filter((n) => n && n.status === "pending")
+      .map((n) => n.id);
+  } else {
+    candidateIds = [];
+  }
+
+  const ready = [];
+  const vetoed = [];
+
+  for (const id of candidateIds) {
+    const task = byId[id];
+    if (!task) continue; // stale id in ready mask — skip silently
+    const deps = Array.isArray(task.deps) ? task.deps : [];
+    const unmet = [];
+    for (const d of deps) {
+      const dep = byId[d];
+      if (!dep || dep.status !== "done") {
+        unmet.push(d);
+      }
+    }
+    if (unmet.length === 0) {
+      ready.push(task);
+    } else {
+      vetoed.push({ task, unmet_deps: unmet });
+      appendEvent(pd, buildVetoEvent(task, unmet));
+    }
+  }
+
+  return { ready, vetoed };
+}
+
+module.exports = {
+  validateDepGraph,
+  // Exposed for unit tests only; not a stable public surface.
+  _buildVetoEvent: buildVetoEvent,
+  _appendEvent: appendEvent,
+};

package/bin/gsd-t-economics.cjs

@@ -0,0 +1,287 @@
+"use strict";
+
+/**
+ * gsd-t-economics — M44 D6 (pre-spawn economics estimator)
+ *
+ * Contract: .gsd-t/contracts/economics-estimator-contract.md
+ *
+ * Hard invariants:
+ *   - Zero external runtime deps (Node built-ins only).
+ *   - Corpus loaded ONCE per projectDir at module init (sync read, cached).
+ *   - NEVER returns undefined — global median fallback guarantees a number.
+ *   - D6 is a HINT only; D2 owns the final gate decision.
+ *   - Event emission is best-effort; failures never fail the estimate.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+/**
+ * Effective CW ceiling in tokens. Matches:
+ *   - bin/token-budget.cjs (200000)
+ *   - bin/context-meter-config.cjs (modelWindowSize: 200000)
+ *   - bin/runway-estimator.cjs (DEFAULT_MODEL_CONTEXT_CAP = 200000)
+ */
+const CW_CEILING_TOKENS = 200000;
+
+/** Confidence tier cutoffs (exact-match row counts). */
+const HIGH_CONFIDENCE_MIN = 5; // ≥5 exact matches
+// MEDIUM: 1-4 exact matches.
+// LOW: fuzzy match (domain-only or command-only).
+// FALLBACK: global median.
+
+/** Mode-specific gate thresholds (percent of CW ceiling). */
+const IN_SESSION_PARALLEL_OK_PCT = 85;
+const UNATTENDED_PARALLEL_OK_PCT = 60;
+const UNATTENDED_SPLIT_PCT = 60;
+
+// ─── Corpus loading (ONCE per projectDir) ─────────────────────────────────
+
+const _corpusCache = new Map(); // projectDir → loaded corpus index
+
+/**
+ * Synchronously load the token-usage corpus for a given projectDir.
+ * Cached indefinitely per process per projectDir.
+ *
+ * @param {string} projectDir
+ * @returns {{
+ *   rows: object[],
+ *   exact:   Map<string, number[]>,  // "cmd|step|dom" → [totals]
+ *   byDomain: Map<string, number[]>, // dom → [totals]
+ *   byCommand: Map<string, number[]>, // cmd → [totals]
+ *   globalMedian: number,
+ *   globalPct: number,
+ * }}
+ */
+function loadCorpus(projectDir) {
+  if (_corpusCache.has(projectDir)) return _corpusCache.get(projectDir);
+
+  const corpusPath = path.join(projectDir, ".gsd-t", "metrics", "token-usage.jsonl");
+  let raw = "";
+  try {
+    raw = fs.readFileSync(corpusPath, "utf8");
+  } catch {
+    raw = "";
+  }
+
+  const rows = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r === "object") rows.push(r);
+    } catch {
+      /* skip malformed */
+    }
+  }
+
+  const exact = new Map();
+  const byDomain = new Map();
+  const byCommand = new Map();
+  const allTotals = [];
+
+  for (const r of rows) {
+    const total = rowTotalTokens(r);
+    const cmd = r.command || "-";
+    const step = r.step || "-";
+    const dom = r.domain || "-";
+    const key = `${cmd}|${step}|${dom}`;
+    pushMap(exact, key, total);
+    pushMap(byDomain, dom, total);
+    pushMap(byCommand, cmd, total);
+    allTotals.push(total);
+  }
+
+  const globalMedian = median(allTotals);
+  const globalPct = tokensToCwPct(globalMedian);
+
+  const idx = { rows, exact, byDomain, byCommand, globalMedian, globalPct };
+  _corpusCache.set(projectDir, idx);
+  return idx;
+}
+
+/** Row-level total = input + output + cacheRead + cacheCreation. */
+function rowTotalTokens(r) {
+  return (r.inputTokens || 0)
+    + (r.outputTokens || 0)
+    + (r.cacheReadInputTokens || 0)
+    + (r.cacheCreationInputTokens || 0);
+}
+
+function pushMap(m, k, v) {
+  if (!m.has(k)) m.set(k, []);
+  m.get(k).push(v);
+}
+
+function median(arr) {
+  if (!arr || arr.length === 0) return 0;
+  const a = arr.slice().sort((x, y) => x - y);
+  const mid = Math.floor(a.length / 2);
+  return a.length % 2 === 1 ? a[mid] : (a[mid - 1] + a[mid]) / 2;
+}
+
+function tokensToCwPct(tokens) {
+  if (!Number.isFinite(tokens) || tokens <= 0) return 0;
+  return (tokens / CW_CEILING_TOKENS) * 100;
+}
+
+// ─── Event emission (best-effort) ─────────────────────────────────────────
+
+function writeEconomicsEvent(projectDir, ev) {
+  try {
+    const dir = path.join(projectDir, ".gsd-t", "events");
+    fs.mkdirSync(dir, { recursive: true });
+    const now = new Date(ev.ts || Date.now());
+    const y = now.getUTCFullYear();
+    const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(now.getUTCDate()).padStart(2, "0");
+    const file = path.join(dir, `${y}-${m}-${d}.jsonl`);
+    const line = JSON.stringify(ev) + "\n";
+    fs.appendFileSync(file, line, "utf8");
+    return true;
+  } catch {
+    return false; // best-effort — never fails the estimate
+  }
+}
+
+// ─── Lookup algorithm ─────────────────────────────────────────────────────
+
+/**
+ * Three-tier lookup against the corpus:
+ *   1. Exact `command|step|domain` match → HIGH (≥5) or MEDIUM (1–4).
+ *   2. Fuzzy match (domain-only, then command-only) → LOW.
+ *   3. Global median → FALLBACK.
+ *
+ * Returns { estimatedTokens, matchedRows, confidence }.
+ */
+function lookupInCorpus(taskNode, corpus) {
+  const cmd = (taskNode && taskNode.command) || "-";
+  const step = (taskNode && taskNode.step) || "-";
+  const dom = (taskNode && taskNode.domain) || "-";
+
+  // Tier 1: exact triplet.
+  const exactKey = `${cmd}|${step}|${dom}`;
+  const exactRows = corpus.exact.get(exactKey);
+  if (exactRows && exactRows.length > 0) {
+    const n = exactRows.length;
+    return {
+      estimatedTokens: median(exactRows),
+      matchedRows: n,
+      confidence: n >= HIGH_CONFIDENCE_MIN ? "HIGH" : "MEDIUM",
+    };
+  }
+
+  // Tier 2a: domain-only fuzzy match.
+  if (dom && dom !== "-") {
+    const domRows = corpus.byDomain.get(dom);
+    if (domRows && domRows.length > 0) {
+      return {
+        estimatedTokens: median(domRows),
+        matchedRows: domRows.length,
+        confidence: "LOW",
+      };
+    }
+  }
+
+  // Tier 2b: command-only fuzzy match.
+  if (cmd && cmd !== "-") {
+    const cmdRows = corpus.byCommand.get(cmd);
+    if (cmdRows && cmdRows.length > 0) {
+      return {
+        estimatedTokens: median(cmdRows),
+        matchedRows: cmdRows.length,
+        confidence: "LOW",
+      };
+    }
+  }
+
+  // Tier 3: global median fallback.
+  return {
+    estimatedTokens: corpus.globalMedian,
+    matchedRows: 0,
+    confidence: "FALLBACK",
+  };
+}
+
+// ─── Gate arithmetic ──────────────────────────────────────────────────────
+
+function decideGates(mode, estimatedCwPct, confidence) {
+  let parallelOk;
+  let split;
+
+  if (mode === "unattended") {
+    parallelOk = estimatedCwPct <= UNATTENDED_PARALLEL_OK_PCT;
+    split = estimatedCwPct > UNATTENDED_SPLIT_PCT;
+  } else {
+    // 'in-session' (default)
+    parallelOk = estimatedCwPct <= IN_SESSION_PARALLEL_OK_PCT;
+    split = false;
+  }
+
+  // Worker-count recommendation: 1 by default; halve (floor 1) for FALLBACK
+  // confidence per §5 guidance. LOW confidence keeps 1 worker at this level —
+  // D2 applies the "reduce by 1–2" heuristic itself (it owns pool sizing).
+  let workerCount = 1;
+  if (confidence === "FALLBACK") workerCount = 1; // already 1; documented for clarity
+  return { parallelOk, split, workerCount };
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Estimate a task's CW footprint and produce a mode-specific recommendation.
+ *
+ * @param {object} opts
+ * @param {{id?:string, command?:string, step?:string, domain?:string}} opts.taskNode
+ * @param {'in-session'|'unattended'} opts.mode
+ * @param {string} [opts.projectDir]
+ * @returns {{estimatedCwPct:number, parallelOk:boolean, split:boolean, workerCount:number, matchedRows:number, confidence:'HIGH'|'MEDIUM'|'LOW'|'FALLBACK'}}
+ */
+function estimateTaskFootprint(opts) {
+  const taskNode = (opts && opts.taskNode) || {};
+  const mode = (opts && opts.mode) || "in-session";
+  const projectDir = (opts && opts.projectDir) || process.cwd();
+
+  const corpus = loadCorpus(projectDir);
+
+  const { estimatedTokens, matchedRows, confidence } = lookupInCorpus(taskNode, corpus);
+  const estimatedCwPct = tokensToCwPct(estimatedTokens);
+
+  const { parallelOk, split, workerCount } = decideGates(mode, estimatedCwPct, confidence);
+
+  // Best-effort event emission.
+  writeEconomicsEvent(projectDir, {
+    type: "economics_decision",
+    ts: new Date().toISOString(),
+    task_id: taskNode.id || null,
+    mode,
+    estimatedCwPct,
+    parallelOk,
+    split,
+    confidence,
+    matchedRows,
+  });
+
+  return {
+    estimatedCwPct,
+    parallelOk,
+    split,
+    workerCount,
+    matchedRows,
+    confidence,
+  };
+}
+
+module.exports = {
+  estimateTaskFootprint,
+  // Internals exposed for unit tests + calibration tooling:
+  _CW_CEILING_TOKENS: CW_CEILING_TOKENS,
+  _loadCorpus: loadCorpus,
+  _lookupInCorpus: lookupInCorpus,
+  _rowTotalTokens: rowTotalTokens,
+  _median: median,
+  _tokensToCwPct: tokensToCwPct,
+  _resetCorpusCache: function resetCorpusCache() { _corpusCache.clear(); },
+};