@tekyzinc/gsd-t 3.13.16 → 3.16.11

package/commands/gsd-t-unattended.md

@@ -257,14 +257,14 @@ node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-
 
 ⚙ [sonnet] gsd-t-unattended → spawning detached supervisor
 
-**Before spawn — read starting context tokens (observability bracket):**
+**Before spawn — capture start timestamp (observability bracket):**
 
 ```bash
-T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")
-T0_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
-T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+DT_START=$(date +"%Y-%m-%d %H:%M")
 ```
 
+The detached supervisor is a `node -e spawnSupervisor` fire-and-forget (no Claude result envelope). Timing is recorded via `recordSpawnRow` (Pattern B) after spawn returns.
+
 If `--dry-run` was specified, print:
 
 ```
@@ -307,28 +307,27 @@ console.log('SPAWNED_PID=' + result.pid);
 
 Capture `SPAWNED_PID` from the output.
 
-**After spawn — record observability bracket:**
-
-```bash
-T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
-T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
-COUNTER=$(node bin/task-counter.cjs status 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(String(JSON.parse(s).count||''))}catch(_){process.stdout.write('')}})")
-```
-
-Append to `.gsd-t/token-log.md` (create with header if missing):
+**After spawn — record row via `recordSpawnRow` (Pattern B, no usage envelope):**
 
 ```bash
+DT_END=$(date +"%Y-%m-%d %H:%M")
 node -e "
-const fs = require('fs');
-const LOG = '.gsd-t/token-log.md';
-const header = '| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Tasks-Since-Reset |\n|---|---|---|---|---|---|---|---|---|---|\n';
-const row = '| ${DT_START} | ${DT_END} | gsd-t-unattended | Step 2 | sonnet | ${DURATION}s | supervisor spawned PID ${SPAWNED_PID} | | | ${COUNTER} |\n';
-if (!fs.existsSync(LOG)) fs.writeFileSync(LOG, header);
-fs.appendFileSync(LOG, row);
+const { recordSpawnRow } = require('./bin/gsd-t-token-capture.cjs');
+recordSpawnRow({
+  projectDir: '.',
+  command: 'gsd-t-unattended',
+  step: 'Step 2',
+  model: 'sonnet',
+  startedAt: process.env.DT_START,
+  endedAt: process.env.DT_END,
+  // usage omitted → Tokens cell renders as '—' (no envelope from a fire-and-forget node spawn)
+  notes: 'supervisor spawned PID ' + (process.env.SPAWNED_PID || '?'),
+});
 "
 ```
 
+The row lands under the canonical `.gsd-t/token-log.md` header with Tokens = `—`, Ctx% pulled via `getSessionStatus()`. No usage envelope is available because the supervisor is a fire-and-forget `node -e spawnSupervisor` child, not a `claude -p` or Task subagent.
+
 ## Step 3: Verify Supervisor Liveness
 
 ```bash

package/commands/gsd-t-verify.md

@@ -199,15 +199,24 @@ Teammate assignments:
   Report: severity-ranked findings.
 
 Lead: After receiving teammate reports:
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
-Spawn a Task subagent (spawnType: validation) to run the full test suite and contract audit — always headless.
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-verify | Step 4 | haiku | {DURATION}s | test audit + contract review | {CTX_PCT} |`
-Collect all reports, synthesize, create remediation plan.
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the validation spawn with `captureSpawn`:**
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-verify',
+    step: 'Step 4',
+    model: 'haiku',
+    description: 'test audit + contract review',
+    projectDir: '.',
+    notes: 'test audit + contract review',
+    spawnFn: async () => { /* Task subagent (spawnType: validation) runs the full test suite and contract audit — always headless */ },
+  });
+})();
+"
+```
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`. Collect all reports, synthesize, create remediation plan.
 ```
 
 ## Step 5: Compile Verification Report
@@ -410,33 +419,40 @@ If status is VERIFY-FAILED:
 If status is VERIFIED or VERIFIED-WITH-WARNINGS:
 1. Log: "✅ Verify complete — spawning complete-milestone agent..."
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
-
-2. Spawn a Task subagent (spawnType: validation, model: sonnet, mode: bypassPermissions) — always headless, `--watch` ignored:
-```
-"Execute the complete-milestone phase of the current GSD-T milestone.
-
-Read and follow the full instructions in commands/gsd-t-complete-milestone.md
-(resolve from ~/.claude/commands/ if not in project).
-Read .gsd-t/progress.md for current milestone and state.
-Read CLAUDE.md for project conventions.
-Read .gsd-t/contracts/ for domain interfaces.
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the complete-milestone auto-invoke with `captureSpawn`:**
 
-Complete the phase fully:
-- Follow every step in the command file
-- Update .gsd-t/progress.md status when done
-- Run document ripple as specified
-- Commit your work
+2. Spawn through `captureSpawn` — `spawnType: 'validation'`, model: sonnet, mode: bypassPermissions (always headless, `--watch` ignored):
 
-Report back: one-line status summary."
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-verify',
+    step: 'Step 8',
+    model: 'sonnet',
+    description: 'auto-complete-milestone',
+    projectDir: '.',
+    notes: 'auto-complete-milestone',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, model: sonnet, mode: bypassPermissions):
+      'Execute the complete-milestone phase of the current GSD-T milestone.
+       Read and follow the full instructions in commands/gsd-t-complete-milestone.md
+       (resolve from ~/.claude/commands/ if not in project).
+       Read .gsd-t/progress.md for current milestone and state.
+       Read CLAUDE.md for project conventions.
+       Read .gsd-t/contracts/ for domain interfaces.
+       Complete the phase fully:
+       - Follow every step in the command file
+       - Update .gsd-t/progress.md status when done
+       - Run document ripple as specified
+       - Commit your work
+       Report back: one-line status summary.' */ },
+  });
+})();
+"
 ```
 
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
-Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-verify | Step 8 | sonnet | {DURATION}s | auto-complete-milestone | | | {CTX_PCT} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 3. Verify subagent result: Read `.gsd-t/progress.md` — confirm status is COMPLETED. If not, report the failure.
 

package/commands/gsd-t-visualize.md

@@ -6,27 +6,29 @@ You are launching the GSD-T real-time agent dashboard — an SSE-backed browser
 
 When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window.
 
-**OBSERVABILITY LOGGING — before spawning:**
-
-Run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the visualize subagent spawn with `captureSpawn`:**
 
 ```
-Task subagent (general-purpose, model: sonnet):
-"Run the GSD-T visualize command. Read commands/gsd-t-visualize.md for your full instructions.
-Arguments: {$ARGUMENTS}
-Skip Step 0 — you are already the subagent."
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-visualize',
+    step: 'Step 0',
+    model: 'sonnet',
+    description: 'dashboard launched',
+    projectDir: '.',
+    notes: 'dashboard launched',
+    spawnFn: async () => { /* Task subagent (general-purpose, model: sonnet):
+      'Run the GSD-T visualize command. Read commands/gsd-t-visualize.md for your full instructions.
+      Arguments: {\$ARGUMENTS}
+      Skip Step 0 — you are already the subagent.' */ },
+  });
+})();
+"
 ```
 
-**OBSERVABILITY LOGGING — after subagent returns:**
-
-Run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
-
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-visualize | Step 0 | sonnet | {DURATION}s | dashboard launched | {CTX_PCT} |`
-
-Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`. Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
 
 ## Step 1: Write command_invoked Event
 

package/commands/gsd-t-wave.md

@@ -132,50 +132,52 @@ Violations are task failures, not warnings.
 
 If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 
-**OBSERVABILITY LOGGING (MANDATORY) — repeat for every phase spawn:**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap every phase spawn with `captureSpawn`:**
 
 ```
-Task agent (spawnType: primary, subagent_type: "general-purpose", mode: "bypassPermissions"):
-  "Execute the {PHASE} phase of the current GSD-T milestone.
-
-   Read and follow the full instructions in commands/gsd-t-{phase}.md
-   Read .gsd-t/progress.md for current milestone and state.
-   Read CLAUDE.md for project conventions.
-   Read .gsd-t/contracts/ for domain interfaces.
-
-   Complete the phase fully:
-   - Follow every step in the command file
-   - Update .gsd-t/progress.md status when done
-   - Run document ripple as specified
-   - Commit your work
-
-   Report back: one-line status summary."
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-wave',
+    step: '{PHASE}',
+    model: 'sonnet',
+    description: 'phase: {PHASE}',
+    projectDir: '.',
+    notes: 'phase: {PHASE}',
+    spawnFn: async () => { /* Task agent (spawnType: primary, subagent_type: 'general-purpose', mode: 'bypassPermissions'):
+      'Execute the {PHASE} phase of the current GSD-T milestone.
+       Read and follow the full instructions in commands/gsd-t-{phase}.md
+       Read .gsd-t/progress.md for current milestone and state.
+       Read CLAUDE.md for project conventions.
+       Read .gsd-t/contracts/ for domain interfaces.
+       Complete the phase fully:
+       - Follow every step in the command file
+       - Update .gsd-t/progress.md status when done
+       - Run document ripple as specified
+       - Commit your work
+       Report back: one-line status summary.' */ },
+  });
+})();
+"
 ```
 
-After phase agent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`. Ctx% is pulled from `getSessionStatus()` automatically.
 
 **Wave Orchestrator Context Gate (MANDATORY) — single-band measurement via Context Meter state file:**
 
-Run via Bash AFTER each phase agent returns:
+After each phase agent returns, run via Bash:
 
 ```bash
 node -e "const tb=require('./bin/token-budget.cjs'); const s=tb.getSessionStatus('.'); process.stdout.write(JSON.stringify(s));"
 ```
 
-The JSON on stdout contains `{pct, threshold}` where `threshold` is `normal` or `threshold` (single-band model per `context-meter-contract.md` v1.3.0). Capture `pct` as `{CTX_PCT}` for the token-log row.
+The JSON on stdout contains `{pct, threshold}` where `threshold` is `normal` or `threshold` (single-band model per `context-meter-contract.md` v1.3.0).
 
 Handling:
 - `threshold === 'normal'` → proceed to the next phase.
 - `threshold === 'threshold'` → the Context Meter's PostToolUse hook has already emitted the `next-spawn-headless:true` marker; the orchestrator routes subsequent subagent spawns through `autoSpawnHeadless()`. No manual checkpoint/halt — the meter + spawn primitive together handle handoff.
 
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-wave | {PHASE} | sonnet | {DURATION}s | phase: {PHASE} | | | {CTX_PCT} |`
-
-Where `{CTX_PCT}` is the `pct` field from the JSON the getSessionStatus command just printed.
-
 ### Phase Sequence
 
 Execute phases in this order, spawning one agent per phase:

package/docs/architecture.md

@@ -433,6 +433,22 @@ 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)**
+
+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)
+           ├── 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)
+```
+
+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).
+
 ### GSD 2 Tier 3 — Quality Culture & Design (M32 — complete v2.53.10)
 
 Three enhancements for project-level quality identity and design consistency.

package/docs/m40-benchmark-report.md

@@ -0,0 +1,35 @@
+# M40 Speed Benchmark — Gate Verdict
+
+- **Generated**: 2026-04-20T20:25:33.610Z
+- **Runs per side**: 1
+- **Fixture**: /Users/david/projects/GSD-T/test/fixtures/m40-benchmark-workload
+- **Verdict**: **PASS** — orchestrator 226451ms ≤ in-session 315567ms × 1.05 (331345ms) — Waves 2+3+4 unlocked
+
+## Environment
+
+- Node: v24.14.1
+- Platform: darwin-25.4.0 (arm64)
+- CPUs: 18
+- RAM: 2849 MB free / 49152 MB total
+
+## Per-run timings (ms) and commit-discipline audit
+
+| # | Orchestrator (ms / exit / commits) | In-session (ms / exit / commits) |
+|---|------------------------------------|----------------------------------|
+| 1 | 226451 / 0 / 20/20 | 315567 / 0 / 20/20 |
+
+- **Median orchestrator**: 226451 ms
+- **Median in-session**:  315567 ms
+- **Threshold** (insession × 1.05): 331345 ms
+
+## Methodology
+
+- Same fixture (`test/fixtures/m40-benchmark-workload/`) copied to a fresh
+  tmp dir per run; git initialized; no cross-run state.
+- Orchestrator path: `bin/gsd-t-orchestrator.js` drives waves via the
+  D1 spawn loop + D2 brief builder.
+- In-session path: a single `claude -p` session handed the tasks
+  sequentially — no subagents.
+- `Date.now()` wall-clock, millisecond precision. Both sides include
+  their full lifecycle (startup + work + teardown).
+- PASS when `median(orchestrator_ms) ≤ median(in-session_ms) × 1.05`.

package/docs/requirements.md

@@ -441,3 +441,23 @@ A reference implementation of the HTML report output is at `scan-report-mock.htm
 - ~~Backlog file format drift (TD-014)~~ — RESOLVED
 - ~~Progress.md format drift (TD-015)~~ — RESOLVED
 - ~~7 backlog commands missing from GSD-T-README (TD-016)~~ — RESOLVED
+
+## M40 Requirements Traceability (plan phase — 2026-04-19)
+
+Milestone 40 (External Task Orchestrator + Streaming Watcher UI) decomposes into 5 measurable requirements drawn directly from `progress.md` Current Milestone § Success criteria. Task numbers reference `.gsd-t/domains/*/tasks.md`.
+
+| REQ-ID | Requirement Summary | Domain | Task(s) | Status |
+|--------|---------------------|--------|---------|--------|
+| REQ-M40-01 | Speed parity or better vs in-session (D0 kill-switch gate) | d0-speed-benchmark | Tasks 1, 2, 3 | pending |
+| REQ-M40-02 | No compaction — one task per spawn, fresh context each time | d1-orchestrator-core | Tasks 3, 4, 6 | pending |
+| REQ-M40-03 | Live streaming UI on localhost:7842 at zero Claude token cost | d4-stream-feed-server, d5-stream-feed-ui | D4 Tasks 1–5, D5 Tasks 1–5 | pending |
+| REQ-M40-04 | Per-wave Promise.all parallelism with Team Mode §15 ceiling (15 max) | d1-orchestrator-core | Tasks 1, 4, 6 | pending |
+| REQ-M40-05 | Recovery from durable JSONL + progress.md on orchestrator crash | d6-recovery-and-resume | Tasks 1, 2, 3, 4 | pending |
+
+Supporting contracts (no direct REQ mapping — shared infrastructure):
+- `task-brief-contract.md` (d2-task-brief-builder Tasks 1–3) — enables REQ-M40-02 via self-contained briefs
+- `completion-signal-contract.md` (d3-completion-protocol Tasks 1–3) — enables REQ-M40-02 and REQ-M40-05 via deterministic done-signal
+- `wave-join-contract.md` (d1-orchestrator-core) — enables REQ-M40-04
+- `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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.13.16",
+  "version": "3.16.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",