@boyingliu01/xp-gate 0.32.1 → 0.32.3

package/plugins/dsh/skills/sprint-flow/references/phase-3-build.md

@@ -236,6 +236,27 @@ Without these events, the Harness can only infer changes from file diffs and has
 
 ---
 
+## 工具调用效率自检（P2 硬性 — 2026-10-30 诊断）
+
+> BUILD 阶段是工具调用最密集的阶段，也是"等待时间长"的主要来源。依据
+> `docs/plans/2026-10-30-dev-speed-diagnosis.md`：工具延迟占总耗时 58%，其中 32.7% 的
+> shell 调用是纯读取/搜索、calls/step 仅 1.03、`job_output` 阻塞 66.5 h。以下四条在 BUILD
+> 期间是硬性自检项，不满足不得宣称 REQ 完成。
+
+| ❌ 低效做法 | ✅ 正确做法 |
+|------------|------------|
+| `cat` / `Get-Content` / `sed -n` / `head` 读文件 | 用 `read` 原生工具（毫秒级，可并发） |
+| `grep` / `rg` / `Select-String` / `findstr` 搜内容 | 用 `grep` 原生工具 |
+| `find` / `ls` / `Get-ChildItem` 找文件 | 用 `glob` 原生工具 |
+| 一个一个发独立调用（改完再想下一个） | 多个互不依赖的调用放进**同一步**并发发出 |
+| 用 `job_output wait:true` / `sleep` 反复阻塞等长任务 | `run_in_background` + 完成通知，需要时短超时取一次 |
+| 打包/发布/插件改动只靠 CI 发现契约破坏 | 先写契约测试（`plugins/dsh/src/contract.test.ts` 范式），本地先红 |
+
+**验收目标**：纯读取 shell 占比 <5%（现 32.7%）；calls/step ≥2.0（现 1.03）；`job_output`
+调用数下降 ≥50%。这三项在 `xp-gate retro` 的 activity 统计里可复查。
+
+---
+
 ## Blind Review — Read-Only Subagent Convention (v0.18.0+, 证据型标准步骤)
 
 **Purpose**: Code review by an isolated subagent with read-only tool access. Replaces the former `freeze/unfreeze` mechanism.

package/plugins/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-29
-**Commit:** 101a0ff3
+**Generated:** 2026-10-30
+**Commit:** e5ca7d9d
 **Branch:** main
-**Version:** 0.32.1.0
+**Version:** 0.32.3.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/src/client.test.ts

@@ -0,0 +1,231 @@
+/**
+ * @test REQ-DSH-018 The Delphi model configuration page registers and saves correctly
+ * @intent Verify the browser half of the plugin against the contracts DSH actually
+ *         enforces: the `window.__ModuleLoader__` bundle shape, the `plugins.row.config`
+ *         key, and — most importantly — the settings write op format
+ *         `{ op: 'set', path: [...], value }`, which a shipped third-party plugin got
+ *         wrong (it sent `{ type, key, value }`, so every save failed silently).
+ * @covers AC-DSH-018-01 AC-DSH-018-02 AC-DSH-018-03
+ *
+ * The bundle is plain CommonJS executed by DSH's own module loader, not by Node, so
+ * these tests evaluate it with a minimal `window.__ModuleLoader__` and a stub
+ * `require` that stands in for the shared platform modules.
+ */
+
+import { readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+
+const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)))
+
+/** The package name and loader row id the page must key itself by. */
+const PKG = "@boyingliu01/dsh-plugin-xp-gate"
+const ROW_ID = "tool-xp-gate"
+
+/** What a module loader hands the bundle: the React surface it may rely on. */
+function stubRequire(id: string): unknown {
+  if (id === "react") {
+    return {
+      createElement: () => null,
+      useState: () => [undefined, () => undefined],
+      useEffect: () => undefined,
+      useMemo: (fn: () => unknown) => fn(),
+      useId: () => "id",
+      useRef: (v: unknown) => ({ current: v }),
+    }
+  }
+  if (id === "react/jsx-runtime") return {}
+  // Any primitives the page imports must degrade rather than throw.
+  return new Proxy({}, { get: () => undefined })
+}
+
+/** Evaluate the client bundle and return its exports plus what it registered. */
+function loadClient(): {
+  exports: Record<string, unknown>
+  registrations: Array<{ name: string; options: Record<string, unknown> }>
+} {
+  const source = readFileSync(join(PKG_ROOT, "lib", "client.js"), "utf8")
+  const registrations: Array<{ name: string; options: Record<string, unknown> }> = []
+  let loaded: Record<string, unknown> | undefined
+
+  const window = {
+    __ModuleLoader__: {
+      load: (def: { id: string; factory: (require: typeof stubRequire) => Record<string, unknown> }) => {
+        expect(def.id).toBe(PKG)
+        loaded = def.factory(stubRequire)
+      },
+    },
+  }
+
+  // The bundle is CommonJS for DSH's own loader, so it cannot be imported; it has
+  // to be evaluated. `new Function` is the sandbox here, not a hazard.
+  const run = new Function("window", "document", "console", source)
+  run(window, { querySelector: () => null, head: { appendChild: () => undefined }, createElement: () => ({ dataset: {}, style: {} }) }, console)
+
+  expect(loaded, "bundle must register through window.__ModuleLoader__.load").toBeDefined()
+  return { exports: loaded as Record<string, unknown>, registrations }
+}
+
+/** The slot service: records each registration and runs each injected body once. */
+function recordingSlots(registrations: Array<{ name: string; options: Record<string, unknown> }>) {
+  return {
+    register: (options: Record<string, unknown>) => {
+      registrations.push({ name: String(options.name), options })
+      return () => undefined
+    },
+    inject: (_name: string, register: () => unknown) => {
+      register()
+      return () => undefined
+    },
+    entries: () => [],
+    getVersion: () => 0,
+    subscribe: () => () => undefined,
+  }
+}
+
+/** The locale service, answering in English so the assertions can read the text. */
+function stubLocale() {
+  return {
+    register: () => () => undefined,
+    bind: () => (key: string) => key,
+    getSnapshot: () => ({ active: "en", revision: 0 }),
+    subscribe: () => () => undefined,
+  }
+}
+
+/** The config-forms service: a writable scope that accepts every mutation. */
+function stubConfigForms() {
+  return {
+    get: () => ({ getSnapshot: () => ({}), subscribe: () => () => undefined, mutate: async () => true }),
+  }
+}
+
+/** A client context recording every slot registration the page makes. */
+function makeCtx(registrations: Array<{ name: string; options: Record<string, unknown> }>) {
+  return {
+    slots: recordingSlots(registrations),
+    locale: stubLocale(),
+    configForms: stubConfigForms(),
+    effect: (fn: () => unknown) => {
+      const result = fn()
+      if (typeof result === "function") (result as () => void)()
+    },
+    inject: [] as string[],
+  }
+}
+
+describe("delphi config client bundle", () => {
+  it("declares the services the page needs", () => {
+    const { exports } = loadClient()
+    expect(exports.apply).toBeTypeOf("function")
+    const inject = exports.inject
+    expect(Array.isArray(inject), "inject must be an array of service names").toBe(true)
+    expect(inject).toContain("slots")
+    expect(inject).toContain("configForms")
+  })
+
+  it("registers a configuration page under the row the bundle patch declares", () => {
+    const { exports, registrations } = loadClient()
+    const ctx = makeCtx(registrations)
+    ;(exports.apply as (ctx: unknown) => void)(ctx)
+
+    const page = registrations.find((r) => r.name === "plugins.row.config")
+    expect(page, "the page must land on plugins.row.config so the row shows Configure").toBeDefined()
+    // DSH's config ledger keys a row page by `<package name>#<row id>`.
+    expect(page?.options.key).toBe(`${PKG}#${ROW_ID}`)
+  })
+
+  it("does not claim plugins.item, which the official settings pages own", () => {
+    // A third-party plugin that registered plugins.item displaced nothing but could
+    // collide with an official page id; row.config is the supported seat.
+    const { exports, registrations } = loadClient()
+    ;(exports.apply as (ctx: unknown) => void)(makeCtx(registrations))
+    expect(registrations.some((r) => r.name === "plugins.item")).toBe(false)
+  })
+})
+
+/**
+ * The operation shape is the one contract a settings page cannot get wrong
+ * silently: DSH's `SettingsPathOpView` is `{ op, path, value }`. The shipped
+ * third-party plugin in this very profile sends `{ type, key, value }`, which the
+ * Host rejects, so its Save button does nothing. Pin ours.
+ */
+describe("delphi config save operations", () => {
+  /** A filled draft, shaped like the page's internal state. */
+  function draft() {
+    return {
+      seats: [
+        { role: "architecture", model: " g-glm-5.3-flash " },
+        { role: "technical", model: "g-qwen3.8-flash" },
+        { role: "feasibility", model: "g-deepseek-flash" },
+      ],
+      baseUrl: " https://gw.example/gpt-proxy ",
+      apiKey: "${WHALECLOUD_API_KEY}",
+      thresholdPercent: "90",
+      maxRounds: "5",
+    }
+  }
+
+  it("emits path-addressed ops, not the {type,key} shape", () => {
+    const { exports } = loadClient()
+    const ops = (exports.saveOperations as (d: unknown) => Array<Record<string, unknown>>)(draft())
+    expect(ops).toHaveLength(1)
+    expect(ops[0].op).toBe("set")
+    expect(Array.isArray(ops[0].path)).toBe(true)
+    expect(ops[0].path).toEqual(["delphi"])
+    // Guards against a regression to the broken third-party shape.
+    expect(ops[0]).not.toHaveProperty("type")
+    expect(ops[0]).not.toHaveProperty("key")
+  })
+
+  it("trims model ids and the gateway before writing them", () => {
+    const { exports } = loadClient()
+    const ops = (exports.saveOperations as (d: unknown) => Array<Record<string, unknown>>)(draft())
+    const delphi = ops[0].value as { baseUrl: string; seats: Array<{ model: string }> }
+    expect(delphi.baseUrl).toBe("https://gw.example/gpt-proxy")
+    expect(delphi.seats.map((s) => s.model)).toEqual([
+      "g-glm-5.3-flash",
+      "g-qwen3.8-flash",
+      "g-deepseek-flash",
+    ])
+  })
+
+  it("rejects a draft whose seats share a model, matching the host rule", () => {
+    const { exports } = loadClient()
+    const validate = exports.validationError as (s: unknown, b: string) => string
+    const d = draft()
+    d.seats[2].model = d.seats[0].model
+    expect(validate(d.seats, d.baseUrl)).toBe("duplicate")
+  })
+
+  it("rejects a draft with a blank seat or no gateway", () => {
+    const { exports } = loadClient()
+    const validate = exports.validationError as (s: unknown, b: string) => string
+    const blank = draft()
+    blank.seats[1].model = "   "
+    expect(validate(blank.seats, blank.baseUrl)).toBe("empty")
+    const noGateway = draft()
+    expect(validate(noGateway.seats, "  ")).toBe("gateway")
+  })
+
+  it("accepts a fully specified draft", () => {
+    const { exports } = loadClient()
+    const validate = exports.validationError as (s: unknown, b: string) => string
+    const d = draft()
+    expect(validate(d.seats, d.baseUrl)).toBe("")
+  })
+
+  it("pads a short stored seat list to the three seats the page edits", () => {
+    // A profile that stored one seat must still render three editors, or the user
+    // can never reach a valid panel from the page.
+    const { exports } = loadClient()
+    const seats = (exports.seatsOf as (v: unknown) => Array<{ role: string; model: string }>)({
+      seats: [{ role: "architecture", model: "only-one" }],
+    })
+    expect(seats).toHaveLength(3)
+    expect(seats[1].role).toBe("technical")
+    expect(seats[2].role).toBe("feasibility")
+    expect(seats[1].model).toBe("")
+  })
+})

package/plugins/dsh/src/contract.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { readFileSync } from "node:fs"
+import { readFileSync, readdirSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
@@ -95,4 +95,28 @@ describe("packaging contract", () => {
     // A report with no explicit verdict must not be counted toward consensus.
     expect(core).toContain("INVALID_NO_VERDICT")
   })
+
+  /**
+   * @test REQ-DSH-019 prepack scripts keep stdout clean for `npm pack --json`
+   * @intent 发布流水线用 `npm pack --dry-run --json | jq ...` 量 tarball 大小。
+   *         `prepack` 里任何一句 console.log 都会混进那个 JSON 流，jq 报
+   *         "Invalid numeric literal" 并以 exit 5 结束——0.32.2 的 dsh 插件正是
+   *         因此没发出去，而 create-release 依赖三个 publish job，于是 tag 与
+   *         release 一起被跳过。日志一律走 stderr。
+   * @covers AC-DSH-019-01
+   */
+  it("prepack-time scripts log to stderr, never stdout", () => {
+    const scriptsDir = join(PKG_ROOT, "scripts")
+    const files = readdirSync(scriptsDir).filter((f) => f.endsWith(".cjs"))
+    expect(files.length, "no prepack scripts found").toBeGreaterThan(0)
+
+    for (const f of files) {
+      const source = readFileSync(join(scriptsDir, f), "utf8")
+      // Strip comments so an explanatory "console.log" in prose does not fail it.
+      const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "")
+      expect(code, `${f} writes to stdout and would corrupt npm pack --json`).not.toMatch(
+        /console\.log\s*\(/,
+      )
+    }
+  })
 })

package/plugins/dsh/src/delphi-settings.test.ts

@@ -0,0 +1,101 @@
+/**
+ * @test REQ-DSH-017 Delphi seats are configurable from the DSH settings document
+ * @intent Verify the plugin's own `delphi` configuration layer, when present, wins
+ *         over `.delphi-config.json` AND is held to the same three-seat invariants —
+ *         three distinct models, no unexpanded placeholder — so a settings page
+ *         cannot introduce a panel the skill would have rejected.
+ * @covers AC-DSH-017-01 AC-DSH-017-02 AC-DSH-017-03
+ *
+ * Why this exists: the settings page is a new, user-editable surface for the one
+ * setting that costs money per run. The invariants were previously enforced only
+ * inside `loadDelphiConfig`'s validation of a JSON file; a value arriving through
+ * DSH's settings document bypasses that file entirely, so the same checks have to
+ * run on this path too. Enforcing them host-side (not only in the page) is the
+ * point: the page is a convenience, the host is the authority.
+ */
+
+import { describe, expect, it } from "vitest"
+import { seatsFromSettings, type DelphiSettingsLayer } from "./delphi-settings.js"
+import { DelphiConfigError } from "./delphi.js"
+import { DelphiSetupError } from "./delphi-config.js"
+
+/** A settings layer whose seats are present, so tests may index them. */
+interface SeatedLayer extends DelphiSettingsLayer {
+  seats: NonNullable<DelphiSettingsLayer["seats"]>
+}
+
+/** A complete, valid three-seat settings layer. */
+function valid(): SeatedLayer {
+  return {
+    baseUrl: "https://gw.example/v1",
+    apiKey: "${WHALECLOUD_API_KEY}",
+    seats: [
+      { role: "architecture", model: "g-glm-5.3-flash" },
+      { role: "technical", model: "g-qwen3.8-flash" },
+      { role: "feasibility", model: "g-deepseek-flash" },
+    ],
+    thresholdPercent: 90,
+    maxRounds: 5,
+  }
+}
+
+describe("seatsFromSettings", () => {
+  it("returns undefined when the settings layer is absent, so the JSON file still applies", () => {
+    // The migration path: an existing .delphi-config.json user keeps working
+    // untouched until they open the page and save something.
+    expect(seatsFromSettings(undefined)).toBeUndefined()
+  })
+
+  it("carries three distinct seats and the gateway through", () => {
+    const resolved = seatsFromSettings(valid())
+    expect(resolved?.seats.map((s) => s.model)).toEqual([
+      "g-glm-5.3-flash",
+      "g-qwen3.8-flash",
+      "g-deepseek-flash",
+    ])
+    expect(resolved?.baseUrl).toBe("https://gw.example/v1")
+    expect(resolved?.thresholdPercent).toBe(90)
+    expect(resolved?.maxRounds).toBe(5)
+  })
+
+  it("keeps a configured api key expression for the caller to resolve", () => {
+    // Resolution belongs to the caller: only it can reach the credential store.
+    expect(seatsFromSettings(valid())?.apiKeyExpression).toBe("${WHALECLOUD_API_KEY}")
+  })
+
+  it("rejects a panel whose models are not all distinct", () => {
+    const layer = valid()
+    layer.seats[2].model = layer.seats[0].model
+    expect(() => seatsFromSettings(layer)).toThrow(DelphiConfigError)
+  })
+
+  it("rejects a panel that does not have exactly three seats", () => {
+    const layer = valid()
+    layer.seats = layer.seats.slice(0, 2)
+    expect(() => seatsFromSettings(layer)).toThrow(DelphiConfigError)
+  })
+
+  it("rejects a blank model rather than treating it as an unpinned seat", () => {
+    const layer = valid()
+    layer.seats[1].model = "   "
+    expect(() => seatsFromSettings(layer)).toThrow(DelphiConfigError)
+  })
+
+  it("rejects an unexpanded placeholder in a model id", () => {
+    const layer = valid()
+    layer.seats[0].model = "${MODEL_VAR}"
+    expect(() => seatsFromSettings(layer)).toThrow(DelphiConfigError)
+  })
+
+  it("refuses a layer with no gateway instead of silently using a default", () => {
+    const layer = valid()
+    layer.baseUrl = ""
+    expect(() => seatsFromSettings(layer)).toThrow(DelphiSetupError)
+  })
+
+  it("applies documented defaults for the consensus settings", () => {
+    const resolved = seatsFromSettings({ ...valid(), thresholdPercent: undefined, maxRounds: undefined })
+    expect(resolved?.thresholdPercent).toBe(90)
+    expect(resolved?.maxRounds).toBe(5)
+  })
+})

package/plugins/dsh/src/delphi-settings.ts

@@ -0,0 +1,111 @@
+/**
+ * Delphi seats supplied through DSH's own settings document.
+ *
+ * `.delphi-config.json` remains the portable, cross-platform source that the skill,
+ * the CI validator, and the other plugins share. This module adds a SECOND source —
+ * the `delphi` section of the plugin's Config, editable from the Plugins page — and
+ * the rules that keep the two from disagreeing in a way that costs money:
+ *
+ *  - the settings layer, when it has any seats, WINS (it is the more recent edit)
+ *  - it must still satisfy every Delphi invariant (`validateSeats`) before a single
+ *    request is made, because a form is a convenience and the host is the authority
+ *  - an absent settings layer resolves to `undefined`, so an existing JSON user is
+ *    never silently migrated to an empty panel
+ *
+ * @test REQ-DSH-017 Delphi seats are configurable from the DSH settings document
+ * @intent 把 DSH settings 里的 delphi 段解析成与 JSON 同构的席位，并在这条新路径上
+ *         重新执行三席/三模型互异/非占位符等不变量，避免表单绕过校验。
+ * @covers AC-DSH-017-01 AC-DSH-017-02 AC-DSH-017-03
+ */
+
+import type { ExpertSeat } from "./delphi.js"
+import { validateSeats } from "./delphi.js"
+import { DelphiSetupError } from "./delphi-config.js"
+
+/** One seat as the settings document stores it. */
+export interface DelphiSettingsSeat {
+  role: string
+  model: string
+  maxTokens?: number
+}
+
+/** The `delphi` section of the plugin Config. */
+export interface DelphiSettingsLayer {
+  baseUrl?: string
+  apiKey?: string
+  seats?: DelphiSettingsSeat[]
+  thresholdPercent?: number
+  maxRounds?: number
+}
+
+/** What {@link seatsFromSettings} produces: seats plus the transport they need. */
+export interface SettingsReviewSetup {
+  readonly seats: readonly ExpertSeat[]
+  readonly baseUrl: string
+  /** The still-unexpanded `api_key` expression; the caller resolves it. */
+  readonly apiKeyExpression: string
+  readonly thresholdPercent: number
+  readonly maxRounds: number
+}
+
+/** Delphi's documented defaults, applied when the settings omit a consensus value. */
+const DEFAULT_THRESHOLD_PERCENT = 90
+const DEFAULT_MAX_ROUNDS = 5
+
+/**
+ * Is the settings layer actually configured?
+ *
+ * Judged by seats alone: a half-filled form (a gateway typed but no seats yet) must
+ * not pre-empt the JSON file, or opening the page would quietly disable every
+ * existing `.delphi-config.json` review.
+ */
+function isConfigured(layer: DelphiSettingsLayer | undefined): boolean {
+  return Array.isArray(layer?.seats) && layer.seats.length > 0
+}
+
+/** Reject a layer that names no gateway, rather than dialling a guess. */
+function requireBaseUrl(layer: DelphiSettingsLayer): string {
+  const baseUrl = (layer.baseUrl ?? "").trim()
+  if (baseUrl === "") {
+    throw new DelphiSetupError(
+      "The Delphi settings have seats but no base_url. Set the gateway URL, " +
+        "or clear the seats to fall back to .delphi-config.json.",
+    )
+  }
+  return baseUrl
+}
+
+/**
+ * Turn the settings layer into a review setup, or `undefined` when it holds no seats.
+ *
+ * Throws the same errors the JSON path throws, so a caller can report either source
+ * through one handler. `validateSeats` runs before any network call, which is what
+ * makes a misconfigured panel a configuration error rather than a provider failure.
+ */
+export function seatsFromSettings(layer: DelphiSettingsLayer | undefined): SettingsReviewSetup | undefined {
+  if (!isConfigured(layer)) return undefined
+  // Narrowed by isConfigured; non-null assertions are avoided to keep strict TS honest.
+  const configured = layer as DelphiSettingsLayer
+  const rawSeats = configured.seats ?? []
+
+  const seats: ExpertSeat[] = rawSeats.map((seat, index) => ({
+    id: seat.role || `Expert ${String.fromCharCode(65 + index)}`,
+    role: seat.role || `expert${index}`,
+    // Trim: a model id pasted from a catalog picker can carry padding, and
+    // `" model-a"` is not the model that was intended.
+    model: (seat.model ?? "").trim(),
+    maxTokens: seat.maxTokens,
+  }))
+
+  // The invariants are the reason this module exists; they run before the
+  // transport is even built.
+  validateSeats(seats)
+
+  return {
+    seats,
+    baseUrl: requireBaseUrl(configured),
+    apiKeyExpression: configured.apiKey ?? "",
+    thresholdPercent: configured.thresholdPercent ?? DEFAULT_THRESHOLD_PERCENT,
+    maxRounds: configured.maxRounds ?? DEFAULT_MAX_ROUNDS,
+  }
+}

package/plugins/dsh/src/hooks.test.ts

@@ -85,3 +85,51 @@ describe("delphiGuardDecision", () => {
     expect(delphiGuardDecision(root, "edit")).toBeDefined()
   })
 })
+
+/**
+ * @test REQ-DSH-015 sprint-phase writes are gated the way the IDE plugin gates them
+ * @intent 验证守卫用「只读工具白名单」判定，而不是「已知写工具黑名单」：
+ *         黑名单漏掉了 bash，而 shell 一条命令就能改文件，等于这道 HARD-GATE 可绕过。
+ * @covers AC-DSH-015-01
+ *
+ * The listed names are the tools a DSH session actually exposes; `bash` is the
+ * one that made the old blacklist bypassable, and the unlisted future tool is
+ * the case a blacklist loses by construction.
+ */
+describe("delphiGuardDecision tool classification", () => {
+  /** Read-only: none of these can modify a file, so none may be gated. */
+  const READ_ONLY = ["read", "grep", "glob", "read_image", "list_agents"]
+
+  /** Anything that can reach a shell or a file write, plus an unknown future tool. */
+  const CAN_WRITE = ["write", "edit", "bash", "pwsh", "str_replace_editor", "some_future_tool"]
+
+  it("never gates the read-only tools", () => {
+    const root = project("rejected")
+    for (const tool of READ_ONLY) {
+      expect(delphiGuardDecision(root, tool), `${tool} must not be gated`).toBeUndefined()
+    }
+  })
+
+  it("gates every tool that can modify code, including bash", () => {
+    const root = project("rejected")
+    for (const tool of CAN_WRITE) {
+      expect(delphiGuardDecision(root, tool), `${tool} must be gated`).toBeDefined()
+    }
+  })
+
+  it("still allows everything once the review is APPROVED", () => {
+    const root = project("approved")
+    for (const tool of CAN_WRITE) {
+      expect(delphiGuardDecision(root, tool), `${tool} must pass`).toBeUndefined()
+    }
+  })
+
+  it("still allows an ordinary repository that has no sprint state", () => {
+    const root = project("none")
+    // Unknown tools stay ungated outside a sprint: the guard protects the sprint
+    // phase, not every repository that installed the plugin.
+    for (const tool of [...CAN_WRITE, "some_future_tool"]) {
+      expect(delphiGuardDecision(root, tool), `${tool} must pass`).toBeUndefined()
+    }
+  })
+})

package/plugins/dsh/src/hooks.ts

@@ -22,8 +22,32 @@
 import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 
-/** Tools that modify files. Read-only tools are never gated. */
-const EDIT_TOOLS: ReadonlySet<string> = new Set(["write", "edit", "str_replace_editor"])
+/**
+ * Tools that provably cannot modify a file. Everything else is gated.
+ *
+ * This is an ALLOWLIST on purpose. The guard used to name the write tools
+ * instead (`write`, `edit`, `str_replace_editor`), which let `bash` through —
+ * one shell command writes a file, so the guard was bypassable by the very tool
+ * a model reaches for first. A write-blacklist loses again on every new
+ * file-touching tool; a read-only allowlist loses only by being too strict,
+ * which surfaces as an over-eager denial rather than a silent hole.
+ */
+const READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "read_image",
+  "grep",
+  "glob",
+  "todo_write",
+  "ask_user_question",
+  "list_agents",
+  "present",
+  // XP-Gate's report tools only read: `xp-gate check/principles/arch` report to
+  // stdout, and the one file they ever write is a temp file list under the OS
+  // temp directory (gate-runner's --all path), never the workspace.
+  "gate-check",
+  "gate-principles",
+  "gate-arch",
+])
 
 /** Where Sprint Flow records the review verdict. */
 const SPRINT_STATE_DIR = ".sprint-state"
@@ -55,9 +79,25 @@ const CHECKABLE_EXTENSIONS: ReadonlySet<string> = new Set([
   ".ps1",
 ])
 
-/** Does this tool modify files? */
+/**
+ * Can this tool modify the workspace? Anything not proven read-only can.
+ *
+ * Used by the save-time principles check, which must fire only for the tools that
+ * actually write a source file — `bash` is excluded here even though the guard
+ * gates it, because the check needs a `file_path` argument to inspect.
+ */
 export function isEditTool(name: string): boolean {
-  return EDIT_TOOLS.has(name)
+  return name === "write" || name === "edit" || name === "str_replace_editor"
+}
+
+/**
+ * Must this tool be gated by the sprint review guard?
+ *
+ * The inverse of {@link READ_ONLY_TOOLS}: an unrecognised tool is treated as
+ * capable of writing, which is what closes the `bash` hole.
+ */
+export function mayModifyFiles(name: string): boolean {
+  return !READ_ONLY_TOOLS.has(name)
 }
 
 /**
@@ -94,7 +134,7 @@ function readVerdict(root: string): { verdict?: string; unreadable?: string } {
  * Returns undefined to mean "allow" so the caller can `if (denial) return denial`.
  */
 export function delphiGuardDecision(root: string, toolName: string): GuardDenial | undefined {
-  if (!isEditTool(toolName)) return undefined
+  if (!mayModifyFiles(toolName)) return undefined
   if (!existsSync(join(root, SPRINT_STATE_DIR))) return undefined
 
   const verdictFile = join(root, SPRINT_STATE_DIR, VERDICT_FILE)

package/plugins/dsh/src/index.test.ts

@@ -95,11 +95,12 @@ describe("apply", () => {
     expect(create).toBeDefined()
     if (!create) return
     // Recording invalidations rather than no-oping: listing must not invalidate, and
-    // an empty stub would hide it if it started to.
+    // an empty stub would hide it if it started to. DSH's `invalidate` takes no
+    // arguments, so the count is the whole signal.
     const invalidations: string[] = []
     const provider = create({
       signal: new AbortController().signal,
-      invalidate: (name: string) => void invalidations.push(name),
+      invalidate: () => void invalidations.push("invalidated"),
     })
     expect(provider.name).toBe("xp-gate")