@boyingliu01/xp-gate 0.31.1 → 0.31.3

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

@@ -58,14 +58,67 @@ export interface ResolvedDelphiConfig {
 /** Raised when config on disk cannot be turned into a usable review setup. */
 export class DelphiSetupError extends Error {}
 
+/** Placeholder spellings xp-gate configs already use. Named so the error text can
+ *  quote the exact form the user wrote — a typo in the spelling is
+ *  indistinguishable from an unset variable otherwise (#576). */
+const PLACEHOLDER_PATTERNS = [
+  { form: "shell", re: /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g },
+  { form: "env", re: /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g },
+] as const
+
+/**
+ * The result of expanding a config value: the expanded text plus what could not
+ * be resolved, kept apart by REASON.
+ *
+ * `missing` and `empty` are different problems with different remedies, so they
+ * are separate lists rather than one "did not expand" bucket (#576):
+ *   missing — nobody set it: fix the environment (and, on a long-lived host,
+ *             restart the process that needs to inherit it)
+ *   empty   — someone set it to "": fix the configuration
+ */
+export interface ExpandedEnv {
+  readonly value: string
+  readonly missing: readonly string[]
+  readonly empty: readonly string[]
+}
+
+/**
+ * Expand `${VAR}` / `{env:VAR}` without collapsing "unset" into "empty".
+ * Supports the two spellings already present in xp-gate config files.
+ */
+export function expandEnvDetailed(
+  value: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ExpandedEnv {
+  const missing: string[] = []
+  const empty: string[] = []
+  let out = value
+  for (const { re } of PLACEHOLDER_PATTERNS) {
+    out = out.replace(re, (_m, name: string) => {
+      const found = env[name]
+      if (found === undefined) {
+        if (!missing.includes(name)) missing.push(name)
+        return ""
+      }
+      if (found === "") {
+        if (!empty.includes(name)) empty.push(name)
+        return ""
+      }
+      return found
+    })
+  }
+  return { value: out, missing, empty }
+}
+
 /**
  * Expand `${VAR}` and `{env:VAR}` placeholders from the environment.
  * Supports the two spellings already present in xp-gate config files.
+ *
+ * Kept for callers that only need the text; use {@link expandEnvDetailed} when
+ * the difference between "unset" and "set to empty" matters.
  */
 export function expandEnv(value: string, env: NodeJS.ProcessEnv = process.env): string {
-  return value
-    .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => env[name] ?? "")
-    .replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => env[name] ?? "")
+  return expandEnvDetailed(value, env).value
 }
 
 /** Pick the active profile, falling back to the top level. */
@@ -123,15 +176,25 @@ function resolveProviders(
     if (!baseUrl) throw new DelphiSetupError(`Provider "${name}" has no base_url.`)
 
     const rawKey = entry.api_key ?? entry.apiKey ?? ""
-    const apiKey = expandEnv(rawKey, env)
+    // Find the placeholder BEFORE touching `env`: the spelling lives in the
+    // config, not the environment, so a broken `env` must not hide it.
+    const placeholder = findPlaceholder(rawKey)
+    // Every read of `env` may fail — a caller can pass a proxy, a frozen object,
+    // or an environment that throws on access. Diagnostics must never become the
+    // reason the run dies: on any error fall back to the plainest possible
+    // message, which is still a DelphiSetupError (#576).
+    let expanded: ExpandedEnv
+    try {
+      expanded = expandEnvDetailed(rawKey, env)
+    } catch {
+      expanded = { value: "", missing: placeholder ? [placeholder.name] : [], empty: [] }
+    }
+    const apiKey = expanded.value
     if (!apiKey) {
       // Name the variable rather than echoing config, which may hold a literal key.
-      const varName =
-        /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(rawKey)?.[1] ??
-        /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/.exec(rawKey)?.[1]
       throw new DelphiSetupError(
-        varName
-          ? `API key variable ${varName} is not set in the environment.`
+        placeholder
+          ? describeUnusableKey(name, rawKey, placeholder, expanded, env)
           : `Provider "${name}" has no api_key.`,
       )
     }
@@ -140,6 +203,85 @@ function resolveProviders(
   return resolved
 }
 
+/** Locate the first placeholder in a config value, keeping both name and spelling. */
+function findPlaceholder(rawKey: string): { name: string; spelling: string } | null {
+  for (const { re } of PLACEHOLDER_PATTERNS) {
+    // Fresh lastIndex each call: the shared regexes are global.
+    re.lastIndex = 0
+    const match = re.exec(rawKey)
+    if (match) return { name: match[1], spelling: match[0] }
+  }
+  return null
+}
+
+/** Env keys whose name matches case-insensitively. Never throws: a hostile or
+ *  partially-broken `env` must not turn diagnostics into the failure (#576). */
+function caseVariantsOf(name: string, env: NodeJS.ProcessEnv): string[] {
+  try {
+    const lower = name.toLowerCase()
+    return Object.keys(env).filter((k) => k !== name && k.toLowerCase() === lower)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Build the message for a provider whose api_key did not expand to anything.
+ *
+ * The old text asserted "is not set in the environment" for every failure. That
+ * is a factual claim the caller cannot make from an expanded string alone: an
+ * empty result also happens when the variable IS set — to "", or set in a
+ * place this process never inherited (a long-lived host whose parent started
+ * before the variable was written; a shell that never reloaded; a systemd unit
+ * without restart; a container created without `-e`). The reader was sent to
+ * check the key, the config, and the gateway — everything except the parent
+ * process environment (#576).
+ */
+function describeUnusableKey(
+  providerName: string,
+  rawKey: string,
+  placeholder: { name: string; spelling: string },
+  expanded: ExpandedEnv,
+  env: NodeJS.ProcessEnv,
+): string {
+  const { name, spelling } = placeholder
+  const lines: string[] = []
+
+  if (expanded.empty.includes(name)) {
+    lines.push(
+      `API key variable ${name} is empty in the environment.`,
+      `Provider "${providerName}" uses ${spelling} in its api_key.`,
+      "The variable is defined but has no value — this is usually a configuration error.",
+      `Set ${name} to a non-empty value.`,
+    )
+  } else {
+    lines.push(
+      `API key variable ${name} is not set in the environment.`,
+      `Provider "${providerName}" uses ${spelling} in its api_key.`,
+    )
+    const variants = caseVariantsOf(name, env)
+    if (variants.length > 0) {
+      lines.push(
+        `Note: the environment has a variable whose name differs only in case: ` +
+          `${variants.join(", ")}. Environment variable names are case-sensitive on ` +
+          "POSIX systems, so ${name} does not match it.",
+      )
+    }
+    lines.push(
+      `Set ${name} and restart the process that reads it. If you already set it, ` +
+        "a long-running parent may still be holding the environment it started " +
+        "with — the variable is inherited once at process start and not refreshed.",
+    )
+  }
+
+  if (!rawKey.includes("${") && !rawKey.includes("{env:")) {
+    // Reached only when the value expanded to "" from a literal; say so instead
+    // of naming a variable that is not referenced.
+    lines.push(`The configured api_key is a literal value and expands to an empty string.`)
+  }
+  return lines.join(" ")
+}
+
 /**
  * Turn raw config into a ready-to-run review setup.
  * Fails loudly and specifically: a missing key or an unexpanded placeholder is

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.31.1",
+  "version": "0.31.3",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/opencode/skills/delphi-review/SKILL.md

@@ -392,6 +392,11 @@ delphi-review(
 )
 ```
 
+> **先确认该工具真的存在（#574）**：不是所有 DSH profile 都装了它。若当前会话的工具列表里
+> 没有 `delphi-review`，说明插件未安装 —— 此时**不要**推断"那就用 subagent / workflow 吧"。
+> 按下方【通道白名单】处理：要么装插件（`dsh plugin add @boyingliu01/dsh-plugin-xp-gate`），
+> 要么走 external 脚本路径，要么 BLOCK。
+
 该工具**直连外部 OpenAI 兼容网关**，每个席位绑定一个不同模型，因此不依赖宿主配置即可
 满足不变量。它复用**同一份** `.delphi-config.json`，无需额外配置。
 
@@ -431,6 +436,51 @@ delphi-review(
 - 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
 - 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
 - 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
+
+##### 通道白名单（default-deny，#574）
+
+上面的双通道契约是**允许清单**，不是"除 subagent 外都能用"。**只有这两条通道合法**：
+`subagent`（native，需通过 ①②③）与 external（插件工具 / `delphi-external-review.cjs`）。
+
+**其余一切扇出机制一律禁止**，包括但不限于：
+
+| 禁止的通道 | 为什么禁止 |
+|---|---|
+| `workflow` 工具的 `agent()` 扇出 | `agent()` 的 `provider`/`model` **不受** `allowedModels` 约束（`dsh-workflow-ptc` 里没有任何白名单校验，直达 `subagents.start`）。脚本里写什么模型就真的跑什么模型。 |
+| 手写脚本 / 循环里逐个调 `subagent` 但省略 `model` | 缺 `model` 时子代理**静默继承宿主会话模型**，三席变一席。 |
+| Agent Teams / `spawn_teammate` | 团队成员模型不可逐条指定，且 `TeamMemberView.model` 是输出字段、可能是继承值。 |
+| 任何"从网关模型清单里挑三个"的做法 | 网关可能注册上百个模型，任意三个互异都满足旧不变量 —— 这正是 #574 的事故形态。 |
+
+**推荐通道不可用时，必须 BLOCK 并如实报告，不得自行选一条"看起来能跑"的路径。**
+判定句：*如果我正在用的派发机制不在上面两条之内，立即停止，输出 BLOCK 并说明缺什么。*
+
+##### 席位解析（派发前强制步骤，#574）
+
+模型 ID **只能来自 `.delphi-config.json`**，不得来自会话默认模型、网关模型清单、
+记忆、或上一次评审的残留。派发前依次执行：
+
+1. 读取 `<项目根>/.delphi-config.json`，取 `active_profile` 指向的 profile。
+   （查找顺序：项目根 → `~/.config/xp-gate/.delphi-config.json`；多份存在时以项目根为准。）
+2. 解出 `architecture` / `technical` / `feasibility` 三个席位的 `model`，**去空白**。
+3. **原样打印**这三个 ID 与 `active_profile`，作为本轮派发的凭据。
+4. 只用这三个字面量派发；脚本里**不得出现配置中不存在的模型 ID**。
+5. 三席位必须互异 —— 若配置本身有重复，这是配置错误，BLOCK，不要去"挑一个换掉"。
+
+> 反例（2026-10-22 实测事故）：某次 code-walkthrough 的 workflow 脚本硬编码了
+> `s-deepseek-v4.1-flash` / `g-deepseek-v4-pro` / `doubao-seed-2.0-pro`，
+> 而配置写的是三个 `local-*` 免费席位。三者互异、评审"成功"、Gate MW 判 APPROVED，
+> 但付费模型被真实调用，而 `local-*` 只落了 1/3。16 次 workflow 运行中读取配置的次数为 **0**。
+
+##### 执行后核验（#574）
+
+评审结束后必须逐席位核对**实际解析到的模型**，不能只看请求值：
+
+- 证据来源：子会话的 `request/header`（平台日志）或 external 脚本的回执 `resolved_model`。
+- 三席 `requested_model` 必须**逐一等于**配置中同角色的席位（按角色对应，不是"三者在集合里"）。
+- 任一不匹配 → 本次评审**作废**，不得写入 `.code-walkthrough-result.json`，按 BLOCK 处理。
+- Gate MW 会独立复核这一点（#574）：存在 `.delphi-config.json` 时，
+  证据里每个 `requested_model` 必须等于该角色的配置席位，否则 pre-push 直接 BLOCK。
+
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

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

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.31.1",
+  "version": "0.31.3",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/qoder/skills/delphi-review/SKILL.md

@@ -392,6 +392,11 @@ delphi-review(
 )
 ```
 
+> **先确认该工具真的存在（#574）**：不是所有 DSH profile 都装了它。若当前会话的工具列表里
+> 没有 `delphi-review`，说明插件未安装 —— 此时**不要**推断"那就用 subagent / workflow 吧"。
+> 按下方【通道白名单】处理：要么装插件（`dsh plugin add @boyingliu01/dsh-plugin-xp-gate`），
+> 要么走 external 脚本路径，要么 BLOCK。
+
 该工具**直连外部 OpenAI 兼容网关**，每个席位绑定一个不同模型，因此不依赖宿主配置即可
 满足不变量。它复用**同一份** `.delphi-config.json`，无需额外配置。
 
@@ -431,6 +436,51 @@ delphi-review(
 - 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
 - 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
 - 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
+
+##### 通道白名单（default-deny，#574）
+
+上面的双通道契约是**允许清单**，不是"除 subagent 外都能用"。**只有这两条通道合法**：
+`subagent`（native，需通过 ①②③）与 external（插件工具 / `delphi-external-review.cjs`）。
+
+**其余一切扇出机制一律禁止**，包括但不限于：
+
+| 禁止的通道 | 为什么禁止 |
+|---|---|
+| `workflow` 工具的 `agent()` 扇出 | `agent()` 的 `provider`/`model` **不受** `allowedModels` 约束（`dsh-workflow-ptc` 里没有任何白名单校验，直达 `subagents.start`）。脚本里写什么模型就真的跑什么模型。 |
+| 手写脚本 / 循环里逐个调 `subagent` 但省略 `model` | 缺 `model` 时子代理**静默继承宿主会话模型**，三席变一席。 |
+| Agent Teams / `spawn_teammate` | 团队成员模型不可逐条指定，且 `TeamMemberView.model` 是输出字段、可能是继承值。 |
+| 任何"从网关模型清单里挑三个"的做法 | 网关可能注册上百个模型，任意三个互异都满足旧不变量 —— 这正是 #574 的事故形态。 |
+
+**推荐通道不可用时，必须 BLOCK 并如实报告，不得自行选一条"看起来能跑"的路径。**
+判定句：*如果我正在用的派发机制不在上面两条之内，立即停止，输出 BLOCK 并说明缺什么。*
+
+##### 席位解析（派发前强制步骤，#574）
+
+模型 ID **只能来自 `.delphi-config.json`**，不得来自会话默认模型、网关模型清单、
+记忆、或上一次评审的残留。派发前依次执行：
+
+1. 读取 `<项目根>/.delphi-config.json`，取 `active_profile` 指向的 profile。
+   （查找顺序：项目根 → `~/.config/xp-gate/.delphi-config.json`；多份存在时以项目根为准。）
+2. 解出 `architecture` / `technical` / `feasibility` 三个席位的 `model`，**去空白**。
+3. **原样打印**这三个 ID 与 `active_profile`，作为本轮派发的凭据。
+4. 只用这三个字面量派发；脚本里**不得出现配置中不存在的模型 ID**。
+5. 三席位必须互异 —— 若配置本身有重复，这是配置错误，BLOCK，不要去"挑一个换掉"。
+
+> 反例（2026-10-22 实测事故）：某次 code-walkthrough 的 workflow 脚本硬编码了
+> `s-deepseek-v4.1-flash` / `g-deepseek-v4-pro` / `doubao-seed-2.0-pro`，
+> 而配置写的是三个 `local-*` 免费席位。三者互异、评审"成功"、Gate MW 判 APPROVED，
+> 但付费模型被真实调用，而 `local-*` 只落了 1/3。16 次 workflow 运行中读取配置的次数为 **0**。
+
+##### 执行后核验（#574）
+
+评审结束后必须逐席位核对**实际解析到的模型**，不能只看请求值：
+
+- 证据来源：子会话的 `request/header`（平台日志）或 external 脚本的回执 `resolved_model`。
+- 三席 `requested_model` 必须**逐一等于**配置中同角色的席位（按角色对应，不是"三者在集合里"）。
+- 任一不匹配 → 本次评审**作废**，不得写入 `.code-walkthrough-result.json`，按 BLOCK 处理。
+- Gate MW 会独立复核这一点（#574）：存在 `.delphi-config.json` 时，
+  证据里每个 `requested_model` 必须等于该角色的配置席位，否则 pre-push 直接 BLOCK。
+
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

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

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-22
-**Commit:** 0678b903
+**Generated:** 2026-10-26
+**Commit:** 7a6d9971
 **Branch:** main
-**Version:** 0.31.1.0
+**Version:** 0.31.3.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.