@boyingliu01/xp-gate 0.31.4 → 0.32.1

package/plugins/dsh/src/evidence.ts

@@ -0,0 +1,141 @@
+/**
+ * Gate MW walkthrough evidence.
+ *
+ * @test REQ-DSH-012 delphi-review can produce Gate MW evidence
+ * @intent Build the .code-walkthrough-result.json document that the pre-push
+ *         validator accepts, from a review the plugin actually ran.
+ * @covers AC-DSH-012-01
+ *
+ * Every field here mirrors a check in githooks/lib/validate-code-walkthrough.cjs.
+ * Two of those checks are easy to misread and are pinned by test:
+ *
+ *  - result_type belongs to each EXPERT record. Putting it at the top level looks
+ *    right, passes no check, and fails with a message that never mentions placement.
+ *  - requested_model comes from the configured seat, never from the gateway's
+ *    response. The gateway answers with its own naming (Qwen3_8-flash-next for a seat
+ *    configured as local-qwen3.8-flash), so using the response tripped #574.
+ */
+
+/** The document Gate MW reads. Field names are the validator's, not ours. */
+export interface WalkthroughEvidence {
+  readonly commit: string
+  readonly branch: string
+  readonly timestamp: string
+  readonly expires: string
+  readonly consensus_ratio: number
+  readonly verdict: "APPROVED"
+  readonly experts: readonly EvidenceExpert[]
+}
+
+export interface EvidenceExpert {
+  readonly role: string
+  readonly requested_model: string
+  readonly resolved_model: string
+  /** Per-expert, not top-level. The validator reads it here. */
+  readonly result_type: "delphi_expert_result"
+  readonly channel: "external" | "local"
+  readonly verdict: "APPROVED"
+}
+
+/** One seat as observed by the review: what we asked for, and what answered. */
+export interface SeatOutcome {
+  readonly role: string
+  /** The model configured for this role. Becomes requested_model. */
+  readonly model: string
+  /** The model the gateway reported. Becomes resolved_model. */
+  readonly resolved: string
+}
+
+export interface BuildEvidenceInput {
+  readonly head: string
+  readonly branch: string
+  readonly seats: readonly SeatOutcome[]
+  readonly verdict: string
+  readonly now: Date
+  /** Gateway URL, used to label provenance. */
+  readonly baseUrl?: string
+  /** Observed agreement. Defaults to unanimous, which is what a 3-seat APPROVED run is. */
+  readonly consensusRatio?: number
+}
+
+/** The validator requires exactly three seats. */
+const REQUIRED_SEATS = 3;
+
+/** Evidence is valid for exactly this long; the validator checks the delta. */
+const VALIDITY_MS = 3_600_000;
+
+/** The validator rejects anything below this. */
+const MIN_CONSENSUS = 0.9;
+
+/**
+ * Label a gateway as local or external.
+ *
+ * Only loopback counts as local: the validator uses this field as provenance, so a
+ * private-network host is still external — nothing about it is verifiable from here.
+ */
+export function evidenceChannel(baseUrl: string): "local" | "external" {
+  const lowered = baseUrl.toLowerCase()
+  return lowered.includes("localhost") || lowered.includes("127.0.0.1") || lowered.includes("[::1]")
+    ? "local"
+    : "external"
+}
+
+/** Refuse to emit a document the validator would reject, and say which field. */
+function assertSeatsUsable(seats: readonly SeatOutcome[]): void {
+  if (seats.length !== REQUIRED_SEATS) {
+    throw new Error(`evidence needs exactly ${REQUIRED_SEATS} seats; got ${seats.length}`)
+  }
+  const requested = new Set<string>()
+  const resolved = new Set<string>()
+  for (const seat of seats) {
+    if (seat.resolved.trim() === "") {
+      throw new Error(`seat "${seat.role}" has no resolved_model; a failed seat cannot produce evidence`)
+    }
+    // Both are checked case-insensitively by some validator paths, so assert on the
+    // stricter reading: duplicated IDs mean one model answered twice.
+    if (requested.has(seat.model.trim())) throw new Error(`duplicate requested_model "${seat.model}"`)
+    if (resolved.has(seat.resolved.trim().toLowerCase())) {
+      throw new Error(`duplicate resolved_model "${seat.resolved}"`)
+    }
+    requested.add(seat.model.trim())
+    resolved.add(seat.resolved.trim().toLowerCase())
+  }
+}
+
+/**
+ * Build the evidence document.
+ *
+ * Refuses on anything the validator would reject rather than emitting a document
+ * that fails at push time, where the cause is much harder to see.
+ */
+export function buildEvidence(input: BuildEvidenceInput): WalkthroughEvidence {
+  if (input.verdict !== "APPROVED") {
+    throw new Error(`evidence requires an APPROVED review; got ${input.verdict}`)
+  }
+  assertSeatsUsable(input.seats)
+
+  const ratio = input.consensusRatio ?? 1
+  if (ratio < MIN_CONSENSUS || ratio > 1) {
+    throw new Error(`consensus_ratio must be ${MIN_CONSENSUS} through 1; got ${ratio}`)
+  }
+
+  const channel = evidenceChannel(input.baseUrl ?? "")
+  const expires = new Date(input.now.getTime() + VALIDITY_MS)
+
+  return {
+    commit: input.head,
+    branch: input.branch,
+    timestamp: input.now.toISOString(),
+    expires: expires.toISOString(),
+    consensus_ratio: ratio,
+    verdict: "APPROVED",
+    experts: input.seats.map((seat) => ({
+      role: seat.role,
+      requested_model: seat.model,
+      resolved_model: seat.resolved,
+      result_type: "delphi_expert_result",
+      channel,
+      verdict: "APPROVED",
+    })),
+  }
+}

package/plugins/dsh/src/gate-runner.test.ts

@@ -2,6 +2,9 @@ import { describe, it, expect } from "vitest"
 import type { ShellExecRequest, ShellRunResult } from "@deepseek-ai/dsh-shell"
 import { renderGateResult, runXpGate, type XpGateShell } from "./gate-runner.js"
 
+/** A timeout distinct from the fixture default, so a passing assertion proves it was forwarded. */
+const FORWARDED_TIMEOUT_MS = 5000;
+
 function result(over: Partial<ShellRunResult> = {}): ShellRunResult {
   return {
     exitCode: 0,
@@ -24,21 +27,26 @@ function makeShell(finalResult: ShellRunResult): { shell: XpGateShell; requests:
         command: req.command,
         workdir: req.workdir ?? "/workspace",
         timeoutMs: req.timeoutMs ?? 1000,
+        // 0.2.0-rc.2 requires the resolved expiry policy even though the request
+        // leaves it optional ("kill" is the executor default).
+        onExpiry: "kill",
         stdoutMaxBytes: 1_000_000,
         signal: req.signal,
         sandboxPolicy: undefined,
       }
     },
-    run() {
-      return Promise.resolve(finalResult)
+    execute() {
+      return Promise.resolve({ result: () => Promise.resolve(finalResult) })
     },
   }
   return { shell, requests }
 }
 
 describe("renderGateResult", () => {
-  it("renders stdout text", () => {
-    expect(renderGateResult(result())).toBe("ok")
+  it("renders stdout text under an explicit PASS verdict", () => {
+    // A bare body would let the model mistake silence for success, so every
+    // render now leads with one of the three verdicts.
+    expect(renderGateResult(result())).toBe("[XP-Gate] PASS\nok")
   })
 
   it("appends [exit code: N] on non-zero exit", () => {
@@ -73,10 +81,10 @@ describe("runXpGate", () => {
   it("passes command/workdir/timeoutMs/signal to the shell", async () => {
     const signal = new AbortController().signal
     const { shell, requests } = makeShell(result())
-    await runXpGate(shell, signal, "xp-gate check 'src'", "/workspace", 5000)
+    await runXpGate(shell, signal, "xp-gate check 'src'", "/workspace", FORWARDED_TIMEOUT_MS)
     expect(requests[0]?.command).toBe("xp-gate check 'src'")
     expect(requests[0]?.workdir).toBe("/workspace")
-    expect(requests[0]?.timeoutMs).toBe(5000)
+    expect(requests[0]?.timeoutMs).toBe(FORWARDED_TIMEOUT_MS)
     expect(requests[0]?.signal).toBe(signal)
   })
 

package/plugins/dsh/src/gate-runner.ts

@@ -5,14 +5,49 @@ import type { ShellExecRequest, ShellExecSpec, ShellRunResult } from "@deepseek-
 /**
  * Structural view of `ctx.shell` so the runner is testable with a fake shell
  * without importing the abstract `ShellExecutor` service.
+ *
+ * The shape tracks the 0.2.0-rc.2 seam: `execute()` returns a handle whose
+ * `result()` settles into the run result. Earlier 0.1.x exposed a single `run()`,
+ * which is why a stale devDependency made this compile while the real runtime
+ * had already moved on.
  */
 export interface XpGateShell {
   resolve(request: ShellExecRequest): ShellExecSpec
-  run(spec: ShellExecSpec): Promise<ShellRunResult>
+  execute(spec: ShellExecSpec): Promise<{ result(): Promise<ShellRunResult> }>
 }
 
-/** Render a completed shell run as a single model-facing text block. */
-export function renderGateResult(result: ShellRunResult): string {
+/** The three verdicts a gate run can produce. There is deliberately no fourth. */
+export type GateVerdict = "PASS" | "GATE FAILED" | "INDETERMINATE"
+
+/**
+ * Classify a completed shell run.
+ *
+ * The order below is load-bearing and must not be rearranged:
+ *
+ *   1. timeout / truncation  -> INDETERMINATE (a killed or clipped run yields no verdict)
+ *   2. exit 0 with no stdout -> INDETERMINATE (the command succeeded but said nothing)
+ *   3. exit 0 with stdout    -> PASS
+ *   4. otherwise             -> GATE FAILED  (nonzero with output) or INDETERMINATE (silent)
+ *
+ * Step 1 must precede step 3: a timed-out process can still report exit 0 from
+ * the state it held when the deadline killed it, so testing `exitCode === 0`
+ * first would render a timeout as a pass. That is the exact defect this project
+ * fixed in Gate 8 and Gate 10, and the plugin must not reintroduce it.
+ */
+export function classifyGateRun(result: ShellRunResult): GateVerdict {
+  const stdout = result.stdout.text.trim()
+
+  if (result.timedOut) return "INDETERMINATE"
+  if (result.stdout.truncated) return "INDETERMINATE"
+  if (result.exitCode === 0) return stdout.length > 0 ? "PASS" : "INDETERMINATE"
+
+  // Nonzero: a verdict exists only when the run produced something to show.
+  const stderr = result.stderr.text.trim()
+  return stdout.length > 0 || stderr.length > 0 ? "GATE FAILED" : "INDETERMINATE"
+}
+
+/** Detailed diagnostics appended after the verdict line, when present. */
+function renderDetails(result: ShellRunResult): string[] {
   const lines: string[] = []
   const stdout = result.stdout.text.trim()
   if (stdout.length > 0) lines.push(stdout)
@@ -32,7 +67,34 @@ export function renderGateResult(result: ShellRunResult): string {
     const spill = result.stderr.spillPath !== undefined ? `, full output: ${result.stderr.spillPath}` : ""
     lines.push(`[stderr truncated${spill}]`)
   }
-  return lines.length > 0 ? lines.join("\n") : "[XP-Gate] command completed (no output)."
+  return lines
+}
+
+/** Install hint appended whenever no verdict could be reached. */
+const INDETERMINATE_HINT =
+  "The gate produced no usable verdict. Check that the xp-gate CLI is installed " +
+  "and runnable (npm i -g @boyingliu01/xp-gate), then retry."
+
+/**
+ * Render a completed shell run as model-facing text.
+ *
+ * Every run resolves to exactly one of three verdicts. A run that could not
+ * establish a verdict says INDETERMINATE and states explicitly that it is not a
+ * pass, because an empty output read as a green check is worse than no output.
+ */
+export function renderGateResult(result: ShellRunResult): string {
+  const verdict = classifyGateRun(result)
+  const lines = renderDetails(result)
+
+  if (verdict === "PASS") {
+    return `[XP-Gate] PASS\n${lines.join("\n")}`
+  }
+  if (verdict === "GATE FAILED") {
+    return `[XP-Gate] GATE FAILED\n${lines.join("\n")}`
+  }
+  return [`[XP-Gate] INDETERMINATE — gate produced no output; NOT a pass`, ...lines, INDETERMINATE_HINT].join(
+    "\n",
+  )
 }
 
 /**
@@ -48,7 +110,8 @@ export async function runXpGate(
   timeoutMs: number,
 ): Promise<string> {
   const spec = shell.resolve({ command, workdir, timeoutMs, signal })
-  const result = await shell.run(spec)
+  const execution = await shell.execute(spec)
+  const result = await execution.result()
   if (result.aborted) {
     const error = new HarnessError("tool call aborted", TOOL_ABORTED)
     error.name = "AbortError"

package/plugins/dsh/src/git-context.test.ts

@@ -0,0 +1,39 @@
+/**
+ * @test REQ-DSH-012 delphi-review can produce Gate MW evidence
+ * @intent Verify HEAD and branch are read from the repository the review ran in, so
+ *         the evidence names the commit the validator will compare against.
+ * @covers AC-DSH-012-02
+ *
+ * Runs against this repository rather than a scratch one: the point is that the
+ * values agree with what git itself reports here, which is exactly what the
+ * pre-push validator does with them.
+ */
+
+import { execFileSync } from "node:child_process"
+import { describe, expect, it } from "vitest"
+import { readGitContext } from "./git-context.js"
+
+/** Ask git directly, the way the validator does. */
+function git(args: readonly string[]): string {
+  return execFileSync("git", args, { encoding: "utf8" }).trim()
+}
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim()
+
+describe("readGitContext", () => {
+  it("reports the same HEAD and branch git reports", () => {
+    const context = readGitContext(repoRoot)
+    expect(context.head).toBe(git(["rev-parse", "HEAD"]))
+    expect(context.branch).toBe(git(["rev-parse", "--abbrev-ref", "HEAD"]))
+  })
+
+  it("returns a full 40-character commit id, not an abbreviation", () => {
+    // The validator compares commit exactly; an abbreviation would never match.
+    expect(readGitContext(repoRoot).head).toMatch(/^[0-9a-f]{40}$/)
+  })
+
+  it("fails loudly outside a repository rather than returning blanks", () => {
+    // Blank values would produce evidence rejected at push time with no clue why.
+    expect(() => readGitContext("/")).toThrow()
+  })
+})

package/plugins/dsh/src/git-context.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal git context for evidence.
+ *
+ * @test REQ-DSH-012 delphi-review can produce Gate MW evidence
+ * @intent Read HEAD and the current branch name, which the walkthrough evidence must
+ *         name exactly, without adding a git library dependency.
+ * @covers AC-DSH-012-02
+ *
+ * Spawned git, not a parsed .git directory: worktrees and detached HEAD have
+ * layouts that are easy to misread, and getting either wrong produces evidence the
+ * validator rejects at push time with no hint about why.
+ */
+
+import { execFileSync } from "node:child_process"
+
+/** The two facts the validator compares against. */
+export interface GitContext {
+  readonly head: string
+  readonly branch: string
+}
+
+/**
+ * Read HEAD and the branch.
+ *
+ * The validator compares `branch` to the name the push reports; a detached HEAD
+ * reports "HEAD", which is what git itself would say, so it is passed through
+ * rather than guessed at.
+ */
+export function readGitContext(cwd: string): GitContext {
+  const run = (args: readonly string[]): string =>
+    execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+
+  try {
+    return { head: run(["rev-parse", "HEAD"]), branch: run(["rev-parse", "--abbrev-ref", "HEAD"]) }
+  } catch (error) {
+    throw new Error(`cannot read git context in ${cwd}: ${(error as Error).message}`)
+  }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * @test REQ-DSH-015 sprint-phase writes are gated the way the IDE plugin gates them
+ * @intent Verify the pre-execute guard allows non-sprint projects, denies a sprint
+ *         that has no APPROVED review, and never throws into the tool path.
+ * @covers AC-DSH-015-01 AC-DSH-015-02
+ *
+ * Mirrors plugins/claude-code/bin/delphi-review-guard.sh, whose degrade rules are
+ * already proven: an absent .sprint-state means "not a sprint project", so gating it
+ * would punish every ordinary repository that installed the plugin.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { delphiGuardDecision } from "./hooks.js"
+
+let dir: string
+
+/** Build a scratch project, optionally with sprint state and a verdict. */
+function project(state: "none" | "no-verdict" | "approved" | "rejected"): string {
+  const root = mkdtempSync(join(dir, "proj-"))
+  if (state === "none") return root
+  try {
+    mkdirSync(join(root, ".sprint-state"), { recursive: true })
+    if (state !== "no-verdict") {
+      const verdict = state === "approved" ? "APPROVED" : "REQUEST_CHANGES"
+      writeFileSync(
+        join(root, ".sprint-state", "delphi-reviewed.json"),
+        JSON.stringify({ verdict, timestamp: "2026-10-27T10:00:00.000Z" }),
+        "utf8",
+      )
+    }
+  } catch (error) {
+    throw new Error(`cannot build scratch project: ${(error as Error).message}`)
+  }
+  return root
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "xp-gate-hooks-"))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+describe("delphiGuardDecision", () => {
+  it("allows a project with no sprint state at all", () => {
+    // The plugin is installed repo-wide; gating a non-sprint repo would break it.
+    expect(delphiGuardDecision(project("none"), "edit")).toBeUndefined()
+  })
+
+  it("denies a sprint whose review has not been recorded", () => {
+    expect(delphiGuardDecision(project("no-verdict"), "write")).toBeDefined()
+  })
+
+  it("denies a sprint whose review was rejected", () => {
+    const decision = delphiGuardDecision(project("rejected"), "edit")
+    expect(decision).toBeDefined()
+    // The reason has to name the current verdict, or the model cannot act on it.
+    expect(decision?.reason).toContain("REQUEST_CHANGES")
+  })
+
+  it("allows a sprint once the review is APPROVED", () => {
+    expect(delphiGuardDecision(project("approved"), "edit")).toBeUndefined()
+  })
+
+  it("ignores read-only tools", () => {
+    // Reading is never what the guard protects against.
+    expect(delphiGuardDecision(project("rejected"), "read")).toBeUndefined()
+    expect(delphiGuardDecision(project("rejected"), "gate-check")).toBeUndefined()
+  })
+
+  it("treats a corrupt verdict file as unreviewed rather than crashing", () => {
+    const root = project("none")
+    try {
+      mkdirSync(join(root, ".sprint-state"), { recursive: true })
+      writeFileSync(join(root, ".sprint-state", "delphi-reviewed.json"), "{not json", "utf8")
+    } catch (error) {
+      throw new Error(`cannot corrupt verdict: ${(error as Error).message}`)
+    }
+    // A parse failure must not surface as a thrown error inside the tool pipeline.
+    expect(() => delphiGuardDecision(root, "edit")).not.toThrow()
+    expect(delphiGuardDecision(root, "edit")).toBeDefined()
+  })
+})

package/plugins/dsh/src/hooks.ts

@@ -0,0 +1,126 @@
+/**
+ * DSH-native hooks: the delphi-review guard and the save-time principles check.
+ *
+ * @test REQ-DSH-015 sprint-phase writes are gated the way the IDE plugin gates them
+ * @intent Port the Claude Code guard and save-check to DSH's own pre/post-execute
+ *         seams, keeping the degrade rules that made them safe there.
+ * @covers AC-DSH-015-01
+ *
+ * Degrade semantics are copied from plugins/claude-code/bin/delphi-review-guard.sh,
+ * which has been in use long enough to have settled them:
+ *
+ *   no .sprint-state   -> ALLOW  (not a sprint project; gating it would punish every
+ *                                 ordinary repo that installed the plugin)
+ *   state, no verdict  -> DENY   (sprint is open, review not done)
+ *   verdict != APPROVED-> DENY   (reason names the actual verdict)
+ *   APPROVED           -> ALLOW
+ *
+ * The guard only ever inspects state. It must not throw: a throw inside pre-execute
+ * aborts the tool call, which is a worse failure than letting an edit through.
+ */
+
+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"])
+
+/** Where Sprint Flow records the review verdict. */
+const SPRINT_STATE_DIR = ".sprint-state"
+const VERDICT_FILE = "delphi-reviewed.json"
+
+/** Denial the guard returns; shape matches DSH's PreToolDecision deny variant. */
+export interface GuardDenial {
+  readonly kind: "deny"
+  readonly reason: string
+}
+
+/** The file extensions the principles engine actually covers. */
+const CHECKABLE_EXTENSIONS: ReadonlySet<string> = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".go",
+  ".java",
+  ".kt",
+  ".c",
+  ".cpp",
+  ".h",
+  ".swift",
+  ".m",
+  ".dart",
+  ".sh",
+  ".ps1",
+])
+
+/** Does this tool modify files? */
+export function isEditTool(name: string): boolean {
+  return EDIT_TOOLS.has(name)
+}
+
+/**
+ * Should a save-time check run for this path?
+ *
+ * Documents and data files are excluded on purpose: they are a large share of the
+ * commits in repositories using xp-gate, and the engine has nothing to say about
+ * them. Skipping them removes most of the hook's cost.
+ */
+export function isCheckablePath(path: string): boolean {
+  const lowered = path.toLowerCase()
+  const dot = lowered.lastIndexOf(".")
+  if (dot < 0) return false
+  return CHECKABLE_EXTENSIONS.has(lowered.slice(dot))
+}
+
+/** Read the recorded verdict, or a reason it cannot be read. */
+function readVerdict(root: string): { verdict?: string; unreadable?: string } {
+  const file = join(root, SPRINT_STATE_DIR, VERDICT_FILE)
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as { verdict?: unknown }
+    const verdict = typeof parsed.verdict === "string" ? parsed.verdict : ""
+    return { verdict }
+  } catch (error) {
+    // Corrupt JSON is a real state (a half-written file, a merge conflict). Treat it
+    // as "not reviewed" and say why, rather than throwing into the tool pipeline.
+    return { unreadable: (error as Error).message }
+  }
+}
+
+/**
+ * Decide whether an edit may proceed.
+ *
+ * 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 (!existsSync(join(root, SPRINT_STATE_DIR))) return undefined
+
+  const verdictFile = join(root, SPRINT_STATE_DIR, VERDICT_FILE)
+  if (!existsSync(verdictFile)) {
+    return {
+      kind: "deny",
+      reason:
+        "delphi-review has not run for this sprint. Complete the Phase 2 delphi-review " +
+        "before modifying code, then retry.",
+    }
+  }
+
+  const { verdict, unreadable } = readVerdict(root)
+  if (unreadable !== undefined) {
+    return {
+      kind: "deny",
+      reason: `${VERDICT_FILE} is not readable as JSON (${unreadable}). Re-run delphi-review.`,
+    }
+  }
+  if (verdict !== "APPROVED") {
+    return {
+      kind: "deny",
+      reason:
+        `delphi-review verdict is "${verdict || "(missing)"}", not APPROVED. ` +
+        "Address the findings and re-run delphi-review, then retry.",
+    }
+  }
+  return undefined
+}