gsd-pi 2.26.0 → 2.27.0

package/dist/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: gsd-headless
+description: Orchestrate GSD (Get Shit Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute software development workflows, monitor task progress, check project status, or control GSD execution (pause/stop/skip/steer). Triggers on requests to "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or any programmatic interaction with the GSD project management system. Essential for building orchestrators that coordinate multiple GSD workers.
+---
+
+# GSD Headless Orchestration
+
+Run GSD commands without TUI via `gsd headless`. Spawns an RPC child process, auto-responds to UI prompts, streams progress.
+
+## Command Syntax
+
+```bash
+gsd headless [flags] [command] [args...]
+```
+
+**Flags:** `--timeout N` (ms, default 300000), `--json` (JSONL to stdout), `--model ID`, `--verbose`
+**Exit codes:** 0=complete, 1=error/timeout, 2=blocked
+
+## Core Workflows
+
+### 1. Create + Execute a Milestone (end-to-end)
+
+```bash
+gsd headless new-milestone --context spec.md --auto
+```
+
+Reads spec, bootstraps `.gsd/`, creates milestone, then chains into auto-mode executing all phases (discuss → research → plan → execute → summarize → complete).
+
+Extra flags for `new-milestone`: `--context <path>` (use `-` for stdin), `--context-text <text>`, `--auto`.
+
+### 2. Run All Queued Work
+
+```bash
+gsd headless auto
+```
+
+Default command. Loops through all pending units until milestone complete or blocked.
+
+### 3. Run One Unit
+
+```bash
+gsd headless next
+```
+
+Execute exactly one unit (task/slice/milestone step), then exit. Ideal for step-by-step orchestration with external decision logic between steps.
+
+### 4. Check Status
+
+```bash
+gsd headless --json status
+```
+
+Returns project state: active milestone/slice/task, phase, progress counts, blockers. Parse the JSONL output for machine-readable state.
+
+### 5. Dispatch Specific Phase
+
+```bash
+gsd headless dispatch research|plan|execute|complete|reassess|uat|replan
+```
+
+Force-route to a specific phase, bypassing normal state-machine routing.
+
+## Orchestrator Patterns
+
+### Poll-and-React Loop
+
+```bash
+# Check status, decide what to do
+STATUS=$(gsd headless --json status 2>/dev/null)
+EXIT=$?
+
+case $EXIT in
+  0) echo "Complete" ;;
+  2) echo "Blocked — needs intervention" ;;
+  *) echo "Error" ;;
+esac
+```
+
+### Step-by-Step with Monitoring
+
+```bash
+while true; do
+  gsd headless next
+  EXIT=$?
+  [ $EXIT -ne 0 ] && break
+  # Check progress, log, decide whether to continue
+  gsd headless --json status
+done
+```
+
+### Multi-Session Orchestration
+
+GSD tracks concurrent workers via file-based IPC in `.gsd/parallel/`. See [references/multi-session.md](references/multi-session.md) for the full architecture.
+
+**Quick overview:**
+
+Each worker spawns with `GSD_MILESTONE_LOCK=M00X` + its own git worktree. Workers write heartbeats to `.gsd/parallel/<milestoneId>.status.json`. The orchestrator enumerates all status files to get a dashboard of all workers, and sends commands via signal files.
+
+```bash
+# Spawn a worker for milestone M001 in its worktree
+GSD_MILESTONE_LOCK=M001 GSD_PARALLEL_WORKER=1 \
+  gsd headless --json auto \
+  --cwd .gsd/worktrees/M001 2>worker-M001.log &
+
+# Monitor all workers: read .gsd/parallel/*.status.json
+for f in .gsd/parallel/*.status.json; do
+  jq '{mid: .milestoneId, state: .state, unit: .currentUnit.id, cost: .cost}' "$f"
+done
+
+# Send pause signal to M001
+echo '{"signal":"pause","sentAt":'$(date +%s000)',"from":"coordinator"}' \
+  > .gsd/parallel/M001.signal.json
+```
+
+**Status file fields:** `milestoneId`, `pid`, `state` (running/paused/stopped/error), `currentUnit`, `completedUnits`, `cost`, `lastHeartbeat`, `startedAt`, `worktreePath`.
+
+**Signal commands:** `pause`, `resume`, `stop`, `rebase`.
+
+**Liveness detection:** PID alive check (`kill -0 $pid`) + heartbeat freshness (30s timeout). Stale sessions are auto-cleaned.
+
+**For multiple projects:** each project has its own `.gsd/` directory. The orchestrator must track `(projectPath, milestoneId)` tuples externally.
+
+### JSONL Event Stream
+
+Use `--json` to get real-time events on stdout for downstream processing:
+
+```bash
+gsd headless --json auto 2>/dev/null | while read -r line; do
+  TYPE=$(echo "$line" | jq -r '.type')
+  case "$TYPE" in
+    tool_execution_start) echo "Tool: $(echo "$line" | jq -r '.toolName')" ;;
+    extension_ui_request) echo "GSD: $(echo "$line" | jq -r '.message // .title // empty')" ;;
+    agent_end) echo "Session ended" ;;
+  esac
+done
+```
+
+Event types: `agent_start`, `agent_end`, `tool_execution_start`, `tool_execution_end`, `extension_ui_request`, `message_update`, `error`.
+
+## Answer Injection
+
+Pre-supply answers for non-interactive runs. See [references/answer-injection.md](references/answer-injection.md) for schema and usage.
+
+## GSD Project Structure
+
+All state lives in `.gsd/` as markdown files (version-controllable):
+
+```
+.gsd/
+  milestones/M001/
+    M001-CONTEXT.md      # Requirements, scope, decisions
+    M001-ROADMAP.md      # Slices with tasks, dependencies, checkboxes
+    M001-SUMMARY.md      # Completion summary
+    slices/S01/
+      S01-PLAN.md        # Task list
+      S01-SUMMARY.md     # Slice summary with frontmatter
+      tasks/T01-PLAN.md  # Individual task spec
+```
+
+State is derived from files on disk — checkboxes in ROADMAP.md are the source of truth for completion.
+
+## All Headless Commands
+
+Quick reference — see [references/commands.md](references/commands.md) for the complete list.
+
+| Command | Purpose |
+|---------|---------|
+| `auto` | Run all queued units (default) |
+| `next` | Run one unit |
+| `status` | Progress dashboard |
+| `new-milestone` | Create milestone from spec |
+| `queue` | Queue/reorder milestones |
+| `history` | View execution history |
+| `stop` / `pause` | Control auto-mode |
+| `dispatch <phase>` | Force specific phase |
+| `skip` / `undo` | Unit control |
+| `doctor` | Health check + auto-fix |
+| `steer <desc>` | Hard-steer plan mid-execution |

package/dist/resources/extensions/gsd/skills/gsd-headless/references/answer-injection.md

@@ -0,0 +1,54 @@
+# Answer Injection
+
+Pre-supply answers to eliminate interactive prompts during headless execution.
+
+## Answer File Schema
+
+```json
+{
+  "questions": {
+    "question_id": "selected_option_label",
+    "multi_select_question": ["option_a", "option_b"]
+  },
+  "secrets": {
+    "API_KEY": "sk-...",
+    "DATABASE_URL": "postgres://..."
+  },
+  "defaults": {
+    "strategy": "first_option"
+  }
+}
+```
+
+### Fields
+
+- **questions**: Map question ID → answer. String for single-select, string[] for multi-select.
+- **secrets**: Map env var name → value. Used for `secure_env_collect` tool calls. Values are never logged.
+- **defaults.strategy**: Fallback for unmatched questions.
+  - `"first_option"` — auto-select first available option
+  - `"cancel"` — cancel the request
+
+## How It Works
+
+Two-phase correlation:
+1. **Observe** `tool_execution_start` events for `ask_user_questions` — extracts question metadata (ID, options, allowMultiple)
+2. **Match** subsequent `extension_ui_request` events to metadata, respond with pre-supplied answer
+
+Handles out-of-order events (extension_ui_request can arrive before tool_execution_start in RPC mode) via deferred processing queue.
+
+## Without Answer Injection
+
+Headless mode has built-in auto-responders:
+- **select** → picks first option
+- **confirm** → auto-confirms
+- **input** → empty string
+- **editor** → returns prefill or empty
+
+Answer injection overrides these defaults with specific answers when precision matters.
+
+## Diagnostics
+
+The injector tracks stats:
+- `questionsAnswered` / `questionsDefaulted`
+- `secretsProvided` / `secretsMissing`
+- `fireAndForgetConsumed` / `confirmationsHandled`

package/dist/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -0,0 +1,59 @@
+# GSD Commands Reference
+
+All commands can be run via `gsd headless [command]`.
+
+## Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `auto` | Autonomous mode — loop until milestone complete (default) |
+| `next` | Step mode — execute one unit, then exit |
+| `stop` | Stop auto-mode gracefully |
+| `pause` | Pause auto-mode (preserves state, resumable) |
+| `new-milestone` | Create milestone from specification (requires `--context`) |
+| `dispatch <phase>` | Force-dispatch: research, plan, execute, complete, reassess, uat, replan |
+
+## Status & Monitoring
+
+| Command | Description |
+|---------|-------------|
+| `status` | Progress dashboard (active unit, phase, blockers) |
+| `visualize` | Workflow visualizer (deps, metrics, timeline) |
+| `history` | Execution history (supports --cost, --phase, --model, limit) |
+
+## Unit Control
+
+| Command | Description |
+|---------|-------------|
+| `skip` | Prevent a unit from auto-mode dispatch |
+| `undo` | Revert last completed unit (--force flag) |
+| `steer <desc>` | Hard-steer plan documents during execution |
+| `queue` | Queue and reorder future milestones |
+| `capture` | Fire-and-forget thought capture |
+| `triage` | Manually trigger triage of pending captures |
+
+## Configuration & Health
+
+| Command | Description |
+|---------|-------------|
+| `prefs` | Manage preferences (global/project/status/wizard/setup) |
+| `config` | Set API keys for external tools |
+| `doctor` | Runtime health checks with auto-fix |
+| `hooks` | Show configured post-unit and pre-dispatch hooks |
+| `knowledge <rule\|pattern\|lesson>` | Add persistent project knowledge |
+| `cleanup` | Remove merged branches or snapshots |
+| `export` | Export results (--json, --markdown) |
+| `migrate` | Migrate v1 .planning directory to .gsd format |
+
+## Phases
+
+GSD workflows progress through these phases:
+`pre-planning` → `needs-discussion` → `discussing` → `researching` → `planning` → `executing` → `verifying` → `summarizing` → `advancing` → `validating-milestone` → `completing-milestone` → `complete`
+
+Special phases: `paused`, `blocked`, `replanning-slice`
+
+## Hierarchy
+
+- **Milestone**: Shippable version (4-10 slices, 1-4 weeks)
+- **Slice**: One demoable vertical capability (1-7 tasks, 1-3 days)
+- **Task**: One context-window-sized unit of work (one session)

package/dist/resources/extensions/gsd/skills/gsd-headless/references/multi-session.md

@@ -0,0 +1,185 @@
+# Multi-Session Orchestration
+
+How to run and monitor multiple concurrent GSD sessions.
+
+## Architecture
+
+GSD uses **file-based IPC** — no sockets or ports. All coordination happens through JSON files in `.gsd/parallel/`.
+
+```
+.gsd/parallel/
+├── M001.status.json    # Worker heartbeat + state
+├── M001.signal.json    # Coordinator → worker commands (ephemeral)
+├── M002.status.json
+├── M003.status.json
+└── ...
+```
+
+## Worker Isolation
+
+Each worker gets:
+1. **`GSD_MILESTONE_LOCK=M00X`** — state derivation only sees this milestone
+2. **`GSD_PARALLEL_WORKER=1`** — prevents nested parallel spawns
+3. **Own git worktree** at `.gsd/worktrees/M00X/` — branch `milestone/M00X`
+
+Workers cannot interfere with each other. Each has its own filesystem and git branch.
+
+## Status File Schema
+
+Written atomically (`.tmp` + rename) by each worker at `.gsd/parallel/<milestoneId>.status.json`:
+
+```json
+{
+  "milestoneId": "M001",
+  "pid": 12345,
+  "state": "running",
+  "currentUnit": {
+    "type": "task",
+    "id": "T03",
+    "startedAt": 1710000000000
+  },
+  "completedUnits": 7,
+  "cost": 1.23,
+  "lastHeartbeat": 1710000015000,
+  "startedAt": 1710000000000,
+  "worktreePath": ".gsd/worktrees/M001"
+}
+```
+
+**States:** `running`, `paused`, `stopped`, `error`
+
+## Signal Files
+
+Coordinator writes to `.gsd/parallel/<milestoneId>.signal.json`. Worker consumes and deletes on next dispatch cycle.
+
+```json
+{
+  "signal": "pause",
+  "sentAt": 1710000020000,
+  "from": "coordinator"
+}
+```
+
+**Signals:** `pause`, `resume`, `stop`, `rebase`
+
+## Spawning Workers
+
+```bash
+# Spawn worker in its worktree
+GSD_MILESTONE_LOCK=M001 \
+GSD_PARALLEL_WORKER=1 \
+GSD_BIN_PATH=$(which gsd) \
+  gsd --mode json --print "/gsd auto" \
+  2>logs/M001.log &
+WORKER_PID=$!
+```
+
+Workers emit NDJSON on stdout. Parse `message_end` events for cost tracking:
+```bash
+# Extract cost from worker output
+gsd --mode json --print "/gsd auto" | while read -r line; do
+  COST=$(echo "$line" | jq -r 'select(.type=="message_end") | .message.usage.cost.total // empty')
+  [ -n "$COST" ] && echo "Cost update: $COST"
+done
+```
+
+## Monitoring All Workers
+
+```bash
+# Dashboard: enumerate all status files
+for f in .gsd/parallel/*.status.json; do
+  [ -f "$f" ] || continue
+  jq -r '[.milestoneId, .state, (.currentUnit.id // "idle"), "\(.cost | tostring)$"] | join("\t")' "$f"
+done
+
+# Liveness check
+for f in .gsd/parallel/*.status.json; do
+  PID=$(jq -r '.pid' "$f")
+  MID=$(jq -r '.milestoneId' "$f")
+  if kill -0 "$PID" 2>/dev/null; then
+    echo "$MID: alive (pid=$PID)"
+  else
+    echo "$MID: DEAD (pid=$PID) — cleanup needed"
+    rm "$f"
+  fi
+done
+```
+
+## Sending Commands
+
+```bash
+# Pause a worker
+send_signal() {
+  local MID=$1 SIGNAL=$2
+  echo "{\"signal\":\"$SIGNAL\",\"sentAt\":$(date +%s000),\"from\":\"coordinator\"}" \
+    > ".gsd/parallel/${MID}.signal.json"
+}
+
+send_signal M001 pause
+send_signal M002 stop
+send_signal M003 resume
+```
+
+## Budget Enforcement
+
+Track aggregate cost across all workers:
+```bash
+TOTAL=$(jq -s 'map(.cost) | add // 0' .gsd/parallel/*.status.json)
+CEILING=50.00
+if (( $(echo "$TOTAL > $CEILING" | bc -l) )); then
+  echo "Budget exceeded ($TOTAL > $CEILING) — stopping all"
+  for f in .gsd/parallel/*.status.json; do
+    MID=$(jq -r '.milestoneId' "$f")
+    send_signal "$MID" stop
+  done
+fi
+```
+
+## Stale Session Cleanup
+
+A session is stale when:
+- PID is dead (`kill -0 $pid` fails), OR
+- `lastHeartbeat` is older than 30 seconds
+
+```bash
+NOW=$(date +%s000)
+STALE_THRESHOLD=30000
+for f in .gsd/parallel/*.status.json; do
+  PID=$(jq -r '.pid' "$f")
+  HB=$(jq -r '.lastHeartbeat' "$f")
+  AGE=$((NOW - HB))
+  if ! kill -0 "$PID" 2>/dev/null || [ "$AGE" -gt "$STALE_THRESHOLD" ]; then
+    echo "Stale: $(jq -r '.milestoneId' "$f") — removing"
+    rm "$f"
+  fi
+done
+```
+
+## Multi-Project Orchestration
+
+Within one project, milestones are tracked automatically in `.gsd/parallel/`. For orchestrating across **multiple projects**, maintain an external registry:
+
+```json
+{
+  "sessions": [
+    { "project": "/path/to/project-a", "milestoneId": "M001" },
+    { "project": "/path/to/project-b", "milestoneId": "M001" },
+    { "project": "/path/to/project-b", "milestoneId": "M002" }
+  ]
+}
+```
+
+Then poll each project's `.gsd/parallel/` directory. GSD has no cross-project awareness — the orchestrator must bridge this gap.
+
+## Built-in Parallel Commands
+
+Inside an interactive GSD session, these commands manage the parallel orchestrator:
+
+| Command | Description |
+|---------|-------------|
+| `/gsd parallel start` | Analyze eligibility, spawn workers |
+| `/gsd parallel status` | Show all workers, costs, progress |
+| `/gsd parallel stop [MID]` | Stop one or all workers |
+| `/gsd parallel pause [MID]` | Pause without killing |
+| `/gsd parallel resume [MID]` | Resume paused worker |
+| `/gsd parallel merge [MID]` | Merge completed milestone branch |

package/dist/resources/extensions/gsd/state.ts

@@ -26,6 +26,7 @@ import {
   resolveSlicePath,
   resolveSliceFile,
   resolveTaskFile,
+  resolveTasksDir,
   resolveGsdRootFile,
   gsdRoot,
 } from './paths.js';
@@ -34,6 +35,7 @@ import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';
+import { existsSync, readdirSync } from 'node:fs';
 import { debugCount, debugTime } from './debug-logger.js';
 
 // ─── Query Functions ───────────────────────────────────────────────────────
@@ -573,6 +575,34 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
     title: activeTaskEntry.title,
   };
 
+  // ── Task plan file check (#909) ──────────────────────────────────────
+  // The slice plan may reference tasks but per-task plan files may be
+  // missing — e.g. when the slice plan was pre-created during roadmapping.
+  // If the tasks dir exists but has literally zero files (empty dir from
+  // mkdir), fall back to planning so plan-slice generates task plans.
+  const tasksDir = resolveTasksDir(basePath, activeMilestone.id, activeSlice.id);
+  if (tasksDir && existsSync(tasksDir) && slicePlan.tasks.length > 0) {
+    const allFiles = readdirSync(tasksDir).filter(f => f.endsWith(".md"));
+    if (allFiles.length === 0) {
+      return {
+        activeMilestone,
+        activeSlice,
+        activeTask: null,
+        phase: 'planning',
+        recentDecisions: [],
+        blockers: [],
+        nextAction: `Task plan files missing for ${activeSlice.id}. Run plan-slice to generate task plans.`,
+        registry,
+        requirements,
+        progress: {
+          milestones: milestoneProgress,
+          slices: sliceProgress,
+          tasks: taskProgress,
+        },
+      };
+    }
+  }
+
   // ── Blocker detection: scan completed task summaries ──────────────────
   // If any completed task has blocker_discovered: true and no REPLAN.md
   // exists yet, transition to replanning-slice instead of executing.

package/dist/resources/extensions/gsd/templates/task-summary.md

@@ -37,6 +37,15 @@ blocker_discovered: false
 
 {{whatWasVerifiedAndHow — commands run, tests passed, behavior confirmed}}
 
+## Verification Evidence
+
+<!-- Populated from verification gate output. If the gate ran, fill in the table below.
+     If no gate ran (e.g., no verification commands discovered), note that. -->
+
+| # | Command | Exit Code | Verdict | Duration |
+|---|---------|-----------|---------|----------|
+| {{row}} | {{command}} | {{exitCode}} | {{verdict}} | {{duration}} |
+
 ## Diagnostics
 
 {{howToInspectWhatThisTaskBuiltLater — status surfaces, logs, error shapes, failure artifacts, or none}}

package/dist/resources/extensions/gsd/tests/auto-dashboard.test.ts

@@ -7,6 +7,7 @@ import {
   describeNextUnit,
   formatAutoElapsed,
   formatWidgetTokens,
+  estimateTimeRemaining,
 } from "../auto-dashboard.ts";
 
 // ─── unitVerb ─────────────────────────────────────────────────────────────
@@ -151,3 +152,15 @@ test("formatWidgetTokens formats millions with M", () => {
   assert.equal(formatWidgetTokens(10_000_000), "10M");
   assert.equal(formatWidgetTokens(25_000_000), "25M");
 });
+
+// ─── estimateTimeRemaining ──────────────────────────────────────────────
+
+test("estimateTimeRemaining returns null when no ledger data", () => {
+  // With no active auto-mode session, ledger is empty
+  const result = estimateTimeRemaining();
+  assert.equal(result, null);
+});
+
+test("estimateTimeRemaining is exported and callable", () => {
+  assert.equal(typeof estimateTimeRemaining, "function");
+});

package/dist/resources/extensions/gsd/tests/continue-here.test.ts

@@ -201,4 +201,85 @@ describe("continue-here", () => {
       }
     });
   });
+
+  describe("context-pressure monitor integration", () => {
+    it("should fire wrap-up when context >= threshold and mark continueHereFired", async () => {
+      const { writeUnitRuntimeRecord, readUnitRuntimeRecord, clearUnitRuntimeRecord } = await import("../unit-runtime.js");
+      const fs = await import("node:fs");
+      const path = await import("node:path");
+      const os = await import("node:os");
+
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "continue-here-monitor-"));
+      try {
+        // Simulate the monitor's one-shot logic:
+        // 1. Write initial runtime record (continueHereFired=false)
+        const startedAt = Date.now();
+        writeUnitRuntimeRecord(tmpDir, "execute-task", "M001/S01/T01", startedAt, {
+          phase: "dispatched",
+          wrapupWarningSent: false,
+        });
+
+        const budget = computeBudgets(128_000);
+        const threshold = budget.continueThresholdPercent;
+
+        // Simulate the monitor poll: context at 75% (above threshold)
+        const contextPercent = 75;
+        const runtime = readUnitRuntimeRecord(tmpDir, "execute-task", "M001/S01/T01");
+        assert.ok(runtime, "runtime record should exist");
+        assert.equal(runtime!.continueHereFired, false, "initially false");
+
+        // Check: should fire
+        const shouldFire = !runtime!.continueHereFired
+          && contextPercent >= threshold;
+        assert.ok(shouldFire, "should fire when context >= threshold and not yet fired");
+
+        // Mark as fired (what the monitor does)
+        writeUnitRuntimeRecord(tmpDir, "execute-task", "M001/S01/T01", startedAt, {
+          continueHereFired: true,
+        });
+
+        // Verify one-shot: second poll should NOT fire
+        const runtime2 = readUnitRuntimeRecord(tmpDir, "execute-task", "M001/S01/T01");
+        assert.ok(runtime2, "runtime record should still exist");
+        assert.equal(runtime2!.continueHereFired, true, "should be marked as fired");
+
+        const shouldFireAgain = !runtime2!.continueHereFired
+          && contextPercent >= threshold;
+        assert.equal(shouldFireAgain, false, "must not fire again — one-shot guard");
+
+        // Clean up
+        clearUnitRuntimeRecord(tmpDir, "execute-task", "M001/S01/T01");
+      } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      }
+    });
+
+    it("should not fire when context is below threshold", () => {
+      const budget = computeBudgets(200_000);
+      const threshold = budget.continueThresholdPercent;
+
+      // Simulate monitor poll with context at 50%
+      const contextPercent = 50;
+      const continueHereFired = false;
+      const shouldFire = !continueHereFired && contextPercent >= threshold;
+      assert.equal(shouldFire, false, "50% should not trigger continue-here");
+    });
+
+    it("should not fire when contextUsage is null/undefined", () => {
+      const budget = computeBudgets(128_000);
+      const threshold = budget.continueThresholdPercent;
+
+      // Simulate the full guard chain from the monitor
+      const usageUndefined = undefined as { percent: number | null } | undefined;
+      const shouldFire1 = usageUndefined != null
+        && usageUndefined.percent != null
+        && usageUndefined.percent >= threshold;
+      assert.equal(shouldFire1, false, "undefined usage must not fire");
+
+      const usageNullPercent: { percent: number | null } = { percent: null };
+      const shouldFire2 = usageNullPercent.percent != null
+        && usageNullPercent.percent >= threshold;
+      assert.equal(shouldFire2, false, "null percent must not fire");
+    });
+  });
 });