@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.2

package/packages/shared/src/dashboard-plugin/plugin-status.ts

@@ -0,0 +1,26 @@
+/**
+ * Plugin status types used in /api/health.plugins[] and WebSocket broadcasts.
+ */
+
+/** Status of a single discovered plugin, reported by /api/health. */
+export interface PluginStatus {
+  id: string;
+  enabled: boolean;
+  loaded: boolean;
+  /** Error message if the plugin failed to load or has a conflict. */
+  error?: string;
+  /** Number of slot claims declared in the plugin's manifest. */
+  claims: number;
+}
+
+/** WebSocket broadcast sent to all browsers when a plugin's config changes. */
+export interface PluginConfigUpdate {
+  type: "plugin_config_update";
+  /** Plugin id that was updated. */
+  id: string;
+  /**
+   * Only this plugin's namespace config (plugins.<id>.*).
+   * Never contains other plugins' config.
+   */
+  config: unknown;
+}

package/packages/shared/src/dashboard-plugin/slot-props.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed prop contracts for each slot id.
+ *
+ * Every slot consumer passes exactly the props defined here to each contribution
+ * component. Plugins receive only the props for the slot they claim.
+ *
+ * NOTE: PluginContext is imported as a type-only forward reference so this
+ * shared package doesn't depend on the runtime package. The runtime package
+ * will re-export this map with the concrete PluginContext type filled in.
+ */
+import type { DashboardSession } from "../types.js";
+import type { SlotId } from "./slot-types.js";
+
+/**
+ * Opaque marker type for PluginContext.
+ * The concrete type is defined in @blackbelt-technology/dashboard-plugin-runtime/context.
+ * Using `unknown` here keeps this shared types-only package free of runtime deps.
+ */
+export type AnyPluginContext = unknown;
+
+/** Folder descriptor passed to sidebar-folder-section slot. */
+export interface FolderDescriptor {
+  cwd: string;
+  label?: string;
+}
+
+/** Map of slot id → props type for that slot's contributions. */
+export interface SlotPropsMap {
+  "sidebar-folder-section": {
+    folder: FolderDescriptor;
+    pluginContext: AnyPluginContext;
+  };
+  "session-card-badge": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "session-card-action-bar": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "content-view": {
+    session: DashboardSession;
+    routeParams: Record<string, string>;
+    onClose: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "content-header-sticky": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "content-inline-footer": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "anchored-popover": {
+    anchorEl: HTMLElement;
+    onDismiss: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "command-route": {
+    session: DashboardSession;
+    routeParams: Record<string, string>;
+    onClose: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "settings-section": {
+    pluginContext: AnyPluginContext;
+  };
+  "tool-renderer": {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    sessionId: string;
+    pluginContext: AnyPluginContext;
+  };
+  // Descriptor-only slots don't have React props (consumed by extension-ui-system)
+  "management-modal": Record<string, unknown>;
+  "footer-segment": Record<string, unknown>;
+  "agent-metric": Record<string, unknown>;
+  "breadcrumb": Record<string, unknown>;
+  "gate": Record<string, unknown>;
+  "toast": Record<string, unknown>;
+  "rjsf-form": Record<string, unknown>;
+}
+
+/** Get the props type for a specific slot id. */
+export type SlotProps<S extends SlotId> = SlotPropsMap[S];
+
+// Type-level test: assert SlotPropsMap covers every SlotId.
+// This will produce a TS error if any SlotId is not in SlotPropsMap.
+type _AssertAllSlotsCovered = {
+  [K in SlotId]: SlotPropsMap[K];
+};

package/packages/shared/src/dashboard-plugin/slot-types.ts

@@ -0,0 +1,151 @@
+/**
+ * Frozen slot taxonomy for the dashboard plugin system.
+ * These ids and their payload contracts are versioned via
+ * @blackbelt-technology/pi-dashboard-shared.
+ *
+ * Adding a slot: minor (non-breaking).
+ * Removing or renaming a slot: major (breaking).
+ */
+
+/** All valid slot ids (frozen for v0.x). */
+export type SlotId =
+  // React-only slots
+  | "sidebar-folder-section"
+  | "session-card-action-bar"
+  | "content-inline-footer"
+  | "anchored-popover"
+  | "command-route"
+  | "tool-renderer"
+  // React-or-descriptor slots
+  | "session-card-badge"
+  | "content-view"
+  | "content-header-sticky"
+  | "settings-section"
+  // Descriptor-only slots (from extension-ui-system)
+  | "management-modal"
+  | "footer-segment"
+  | "agent-metric"
+  | "breadcrumb"
+  | "gate"
+  | "toast"
+  | "rjsf-form";
+
+/** How many contributions a slot allows. */
+export type Multiplicity = "one" | "many" | "one-active";
+
+/** Which payload types the slot accepts. */
+export type PayloadTier = "react-only" | "descriptor-only" | "react-or-descriptor";
+
+export interface SlotDefinition {
+  multiplicity: Multiplicity;
+  payloadTier: PayloadTier;
+  description: string;
+}
+
+/** Frozen slot definitions map for v0.x. */
+export const SLOT_DEFINITIONS: Record<SlotId, SlotDefinition> = {
+  "sidebar-folder-section": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Collapsible block above session list per workspace folder",
+  },
+  "session-card-badge": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "Compact info chip on a session card",
+  },
+  "session-card-action-bar": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Action buttons on a session card",
+  },
+  "content-view": {
+    multiplicity: "one-active",
+    payloadTier: "react-or-descriptor",
+    description: "Full-screen content area view for a session",
+  },
+  "content-header-sticky": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "Sticky header above the content view",
+  },
+  "content-inline-footer": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Inline footer below the content view (React-only)",
+  },
+  "anchored-popover": {
+    multiplicity: "one",
+    payloadTier: "react-only",
+    description: "Popover anchored to a UI trigger element",
+  },
+  "command-route": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Maps a slash command or URL route to a content view",
+  },
+  "settings-section": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "A section in the Settings page",
+  },
+  "tool-renderer": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Custom React renderer for a specific tool call by toolName",
+  },
+  // Descriptor-only (extension-ui-system)
+  "management-modal": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Full-screen management modal (extension-ui-system)",
+  },
+  "footer-segment": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Segment in the session footer bar (extension-ui-system)",
+  },
+  "agent-metric": {
+    multiplicity: "one",
+    payloadTier: "descriptor-only",
+    description: "Metric chip on an agent card (extension-ui-system)",
+  },
+  "breadcrumb": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Breadcrumb item in the content header (extension-ui-system)",
+  },
+  "gate": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Flow gate/checkpoint UI (extension-ui-system)",
+  },
+  "toast": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Transient notification toast (extension-ui-system)",
+  },
+  "rjsf-form": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "JSON-Schema-driven form (extension-ui-system Phase 4)",
+  },
+};
+
+/** Valid settings tab ids in SettingsPanel. */
+export type SettingsTab =
+  | "general"
+  | "servers"
+  | "packages"
+  | "providers"
+  | "security"
+  | "advanced";
+
+export const VALID_SETTINGS_TABS: SettingsTab[] = [
+  "general",
+  "servers",
+  "packages",
+  "providers",
+  "security",
+  "advanced",
+];

package/packages/shared/src/openspec-activity-detector.ts

@@ -83,29 +83,25 @@ export function detectOpenSpecActivity(
   }
 
   if (tool === "bash") {
-    const command = args.command as string | undefined;
-    if (!command || !command.includes("openspec")) return null;
-
-    // Check for --change flag
-    const flagMatch = command.match(CLI_CHANGE_FLAG_RE);
-    if (flagMatch) {
-      return { changeName: flagMatch[1], isActive: true };
-    }
-
-    // Check for openspec archive <name>
-    const archiveMatch = command.match(CLI_ARCHIVE_RE);
-    if (archiveMatch) {
-      return { changeName: archiveMatch[1], isActive: true };
-    }
-
-    // Check for openspec new change "name"
-    const newChangeMatch = command.match(CLI_NEW_CHANGE_RE);
-    if (newChangeMatch) {
-      return { changeName: newChangeMatch[1], isActive: true };
+      const command = args.command as string | undefined;
+      if (!command || !command.includes("openspec")) return null;
+
+      // Try each CLI regex in order; first match wins.
+      const match =
+        command.match(CLI_CHANGE_FLAG_RE) ??
+        command.match(CLI_ARCHIVE_RE) ??
+        command.match(CLI_NEW_CHANGE_RE);
+      if (!match) return null;
+
+      const name = match[1];
+      // Reject flag-shaped tokens (e.g. `--help`, `-h`). The CLI regex capture
+      // groups use `[^\s"']+` which would otherwise treat `--help` as a change
+      // name and trigger downstream auto-attach + auto-rename.
+      // See change: fix-openspec-flag-rename-bug.
+      if (name.startsWith("-")) return null;
+
+      return { changeName: name, isActive: true };
     }
 
-    return null;
-  }
-
   return null;
 }

package/packages/shared/src/openspec-design-evidence.ts

@@ -0,0 +1,109 @@
+/**
+ * Local-evidence override for the OpenSpec `design` artifact.
+ *
+ * The upstream `spec-driven` schema requires `design.md` as a hard,
+ * single-file dependency of `tasks`. Two real-world workflows fight that:
+ *
+ *   • **Split design** — users put design content in `design-rendering.md`
+ *     + `design-state.md`. The CLI doesn't see them; status reports
+ *     `design: ready` forever; dashboard shows `[Continue] [FF]` instead of
+ *     `[Apply]`.
+ *   • **No-design changes** — trivial fixes that don't need a design doc.
+ *     User writes `tasks.md`, starts implementing; CLI still says
+ *     `design: ready`; dashboard buttons are wrong.
+ *
+ * This module computes a boolean "is design satisfied locally?" from
+ * file-system evidence the CLI ignores. It is consumed by:
+ *
+ *   1. `buildOpenSpecData` in `openspec-poller.ts` — promotes
+ *      `artifacts[design].status` from "ready" to "done" when the rules fire.
+ *      Promote-only; design-only; never demotes; never touches other artifacts.
+ *
+ *   2. `.pi/skills/openspec-shared/scripts/effective-status.sh` — the
+ *      OpenSpec workflow skills invoke this wrapper instead of
+ *      `openspec status --json` so skill-driven prompts and dashboard buttons
+ *      cannot disagree.
+ *
+ * Three rules, evaluated in order with short-circuit:
+ *
+ *   R1  any file matching ^design.*\.md$ exists in the change folder
+ *   R2  a design/ subdirectory exists with at least one *.md inside
+ *   R3  tasks.md exists AND contains at least one Markdown checkbox
+ *       (^\s*-\s+\[[ xX]\]\s)
+ *
+ * R3 is heuristic but defensible: a user who wrote actionable tasks has
+ * already made the design decisions. The schema's hard dependency is
+ * paperwork we don't believe in for trivial changes.
+ *
+ * See change: fix-openspec-design-detection.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+/** Probe surface — kept tiny so unit tests can pass an in-memory stub. */
+export interface DesignEvidenceProbe {
+  /** R1: any file matching `^design.*\.md$` in `changeDir`. */
+  hasDesignFile(changeDir: string): boolean;
+  /** R2: `<changeDir>/design/` exists and contains at least one `*.md`. */
+  hasDesignDirWithMd(changeDir: string): boolean;
+  /** R3: `<changeDir>/tasks.md` contains at least one Markdown checkbox. */
+  tasksHasCheckboxes(changeDir: string): boolean;
+}
+
+/** Pure rule evaluator. R1 → R2 → R3, short-circuits on first match. */
+export function evaluateLocalDesignSatisfaction(
+  changeDir: string,
+  probe: DesignEvidenceProbe,
+): boolean {
+  if (probe.hasDesignFile(changeDir)) return true;
+  if (probe.hasDesignDirWithMd(changeDir)) return true;
+  if (probe.tasksHasCheckboxes(changeDir)) return true;
+  return false;
+}
+
+const DESIGN_FILE_RE = /^design.*\.md$/;
+const CHECKBOX_RE = /^\s*-\s+\[[ xX]\]\s/m;
+
+/** Production probe — backed by the real filesystem. Sync, defensive. */
+export function createFsDesignEvidenceProbe(): DesignEvidenceProbe {
+  return {
+    hasDesignFile(changeDir) {
+      try {
+        const entries = readdirSync(changeDir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isFile() && DESIGN_FILE_RE.test(e.name)) return true;
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    },
+
+    hasDesignDirWithMd(changeDir) {
+      const dir = path.join(changeDir, "design");
+      try {
+        const st = statSync(dir);
+        if (!st.isDirectory()) return false;
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isFile() && e.name.endsWith(".md")) return true;
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    },
+
+    tasksHasCheckboxes(changeDir) {
+      const tasks = path.join(changeDir, "tasks.md");
+      if (!existsSync(tasks)) return false;
+      try {
+        const text = readFileSync(tasks, "utf8");
+        return CHECKBOX_RE.test(text);
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/packages/shared/src/openspec-poller.ts

@@ -23,12 +23,47 @@
 import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
 import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
+import {
+  evaluateLocalDesignSatisfaction,
+  createFsDesignEvidenceProbe,
+  type DesignEvidenceProbe,
+} from "./openspec-design-evidence.js";
+import {
+  evaluateLocalSpecsSatisfaction,
+  createFsSpecsEvidenceProbe,
+  type SpecsEvidenceProbe,
+} from "./openspec-specs-evidence.js";
+import path from "node:path";
 
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
+/**
+ * Factory that returns a probe for a given change name. Production callers
+ * pass a closure rooted at `<cwd>/openspec/changes/<name>`. Tests pass an
+ * in-memory factory. When omitted, the design override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim.
+ *
+ * See change: fix-openspec-design-detection.
+ */
+export type DesignProbeFactory = (changeName: string) => DesignEvidenceProbe;
+
+/**
+ * Factory that returns a specs-evidence probe for a given change name.
+ * Parallel to `DesignProbeFactory` — production callers pass a closure
+ * rooted at `<cwd>/openspec/changes/<name>`; tests pass an in-memory
+ * factory. When omitted, the specs override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim for the specs
+ * artifact.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export type SpecsProbeFactory = (changeName: string) => SpecsEvidenceProbe;
+
 export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
   statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
+  probeFactory?: DesignProbeFactory,
+  specsProbeFactory?: SpecsProbeFactory,
 ): OpenSpecData {
   if (!listResult || !Array.isArray(listResult.changes)) {
     return EMPTY_DATA;
@@ -41,9 +76,40 @@ export function buildOpenSpecData(
       status: (a.status === "done" ? "done" : a.status === "ready" ? "ready" : "blocked") as OpenSpecArtifact["status"],
     }));
 
-    const isComplete =
+    // Design-artifact override: promote-only, design-only. See change:
+    // fix-openspec-design-detection.
+    if (probeFactory) {
+      const designIdx = artifacts.findIndex((a) => a.id === "design");
+      if (designIdx !== -1 && artifacts[designIdx].status === "ready") {
+        const probe = probeFactory(c.name);
+        if (evaluateLocalDesignSatisfaction("", probe)) {
+          artifacts[designIdx] = { ...artifacts[designIdx], status: "done" };
+        }
+      }
+    }
+
+    // Specs-artifact override: promote-only, specs-only. See change:
+    // fix-openspec-specs-mtime-gate-blind-spot.
+    if (specsProbeFactory) {
+      const specsIdx = artifacts.findIndex((a) => a.id === "specs");
+      if (specsIdx !== -1 && artifacts[specsIdx].status === "ready") {
+        const probe = specsProbeFactory(c.name);
+        if (evaluateLocalSpecsSatisfaction("", probe)) {
+          artifacts[specsIdx] = { ...artifacts[specsIdx], status: "done" };
+        }
+      }
+    }
+
+    const cliIsComplete =
       typeof statusResult?.isComplete === "boolean" ? statusResult.isComplete : undefined;
 
+    // Re-derive isComplete from post-override artifacts. Promote false→true
+    // only when every artifact is done; never demote CLI true.
+    let isComplete = cliIsComplete;
+    if (artifacts.length > 0 && artifacts.every((a) => a.status === "done")) {
+      isComplete = true;
+    }
+
     const change: OpenSpecChange = {
       name: c.name,
       status: (c.status === "complete" ? "complete" : c.status === "in-progress" ? "in-progress" : "no-tasks") as OpenSpecChange["status"],
@@ -58,6 +124,44 @@ export function buildOpenSpecData(
   return { initialized: true, changes };
 }
 
+/**
+ * Build a real-fs probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Production callers (`pollOpenSpec`, `pollOpenSpecAsync`,
+ * `directory-service.ts`) use this to wire the override. Tests inject
+ * their own factory.
+ */
+export function createFsProbeFactory(cwd: string): DesignProbeFactory {
+  const probe = createFsDesignEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasDesignFile: () => probe.hasDesignFile(changeDir),
+      hasDesignDirWithMd: () => probe.hasDesignDirWithMd(changeDir),
+      tasksHasCheckboxes: () => probe.tasksHasCheckboxes(changeDir),
+    };
+  };
+}
+
+/**
+ * Build a real-fs specs-probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Parallel to `createFsProbeFactory` — production callers (`pollOpenSpec`,
+ * `pollOpenSpecAsync`, `directory-service.ts`) use this to wire the specs
+ * override. Tests inject their own factory.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export function createFsSpecsProbeFactory(cwd: string): SpecsProbeFactory {
+  const probe = createFsSpecsEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasAnySpecFile: () => probe.hasAnySpecFile(changeDir),
+    };
+  };
+}
+
 /**
  * Synchronous poll — blocks the event loop. Used by the bridge extension
  * where async isn't practical (some pi extension hooks are sync).
@@ -70,7 +174,12 @@ export function pollOpenSpec(cwd: string): OpenSpecData {
   for (const c of listResult.changes) {
     statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }
 
 /**
@@ -114,5 +223,10 @@ export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
     }),
   );
   const statusResults = new Map<string, any>(statusEntries);
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }

package/packages/shared/src/openspec-specs-evidence.ts

@@ -0,0 +1,79 @@
+/**
+ * Local-evidence override for the OpenSpec `specs` artifact.
+ *
+ * The `spec-driven` schema declares `specs/**\/*.md` as the `generates`
+ * pattern for the `specs` artifact, and the openspec CLI marks the
+ * artifact `done` whenever that glob matches anything. The dashboard's
+ * mtime-gated cache, however, can momentarily stale on `specs: ready`
+ * for multi-spec changes (see change:
+ * fix-openspec-specs-mtime-gate-blind-spot — the watch set is now
+ * extended to cover `specs/**`, but this override is the second line
+ * of defence).
+ *
+ * This module computes a boolean "is specs satisfied locally?" from
+ * file-system evidence the dashboard's cache might miss between polls.
+ * It is consumed by:
+ *
+ *   1. `buildOpenSpecData` in `openspec-poller.ts` — promotes
+ *      `artifacts[specs].status` from "ready" to "done" when at least
+ *      one `specs/**\/*.md` file exists. Promote-only; specs-only;
+ *      never demotes; never touches other artifacts.
+ *
+ * One rule:
+ *
+ *   any file matching `specs/**\/*.md` exists in the change folder
+ *
+ * The probe walks the `specs/` subtree once and short-circuits on the
+ * first `*.md` it finds. Defensive: every fs call is wrapped in
+ * try/catch and treated as "no match" on error.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+/** Probe surface — kept tiny so unit tests can pass an in-memory stub. */
+export interface SpecsEvidenceProbe {
+  /** Returns true iff at least one `*.md` file exists under `<changeDir>/specs/`. */
+  hasAnySpecFile(changeDir: string): boolean;
+}
+
+/** Pure rule evaluator. Single rule; short-circuits on first match. */
+export function evaluateLocalSpecsSatisfaction(
+  changeDir: string,
+  probe: SpecsEvidenceProbe,
+): boolean {
+  return probe.hasAnySpecFile(changeDir);
+}
+
+/**
+ * Production probe — backed by the real filesystem. Walks `<changeDir>/specs/`
+ * iteratively, short-circuits on the first `*.md` file encountered. Every
+ * `readdirSync` is wrapped in try/catch (handles ENOENT, permission errors,
+ * symlink loops, and any unexpected fs error) and treated as "no match".
+ */
+export function createFsSpecsEvidenceProbe(): SpecsEvidenceProbe {
+  return {
+    hasAnySpecFile(changeDir: string): boolean {
+      const root = path.join(changeDir, "specs");
+      // Iterative DFS — no recursion to avoid stack overflow on pathological trees.
+      const stack: string[] = [root];
+      while (stack.length > 0) {
+        const dir = stack.pop()!;
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+          // Missing dir, permission denied, or any other fs error — skip.
+          continue;
+        }
+        for (const e of entries) {
+          if (e.isFile() && e.name.endsWith(".md")) return true;
+          if (e.isDirectory()) stack.push(path.join(dir, e.name));
+        }
+      }
+      return false;
+    },
+  };
+}