@boyingliu01/xp-gate 0.23.0 → 0.25.0

package/mutation/runners/gremlins-runner.ts

@@ -0,0 +1,238 @@
+// @no-test-required: gremlins wrapper — tested via gremlins-runner.test.ts + pre-push Gate M
+import { spawn, execSync, type ChildProcess } from 'child_process';
+import { dirname } from 'path';
+import type {
+  MutationRunner,
+  RunMutationOptions,
+  MutationRunOutcome,
+  MutationRunResult,
+} from './types';
+
+/**
+ * pytest-gremlins mutation runner for Python files (#410).
+ *
+ * Why a second Python engine exists: mutmut 3.x is built on fork(), so on
+ * Windows it can only run under WSL — a native Windows user had a structural
+ * deadlock (installed => `mutmut run` exits 1 => push blocked; uninstalled =>
+ * Gate M skips). pytest-gremlins uses mutation *switching* (instrument once,
+ * flip an env var per mutant) with no fork and no per-mutant file I/O, making
+ * it natively cross-platform. It also matches Gate M's needs: coverage-guided
+ * test selection, an incremental content-hash cache, parallel workers and
+ * console/HTML/JSON reports.
+ *
+ * Constraint: pytest-gremlins requires Python >= 3.11. On older interpreters
+ * the import probe simply fails and the caller keeps the mutmut path (or
+ * SKIPs) — no new hard dependency.
+ */
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL. pytest-gremlins
+ * runs a whole pytest session per invocation, so a child that ignores SIGTERM
+ * (stuck in a C extension) still needs a hard backstop.
+ */
+const SIGKILL_ESCALATION_MS = 5000;
+
+/** Bound on the one-shot import probe; a hung interpreter must not stall Gate M. */
+const PROBE_TIMEOUT_MS = 10000;
+
+/**
+ * Exactly-once resolve bookkeeping for a spawned mutation run.
+ *
+ * A child can report `close`, `error`, a timeout, and the SIGKILL escalation in
+ * any interleaving; without a single latched gate the Promise resolves twice
+ * (subsequent resolves are silent no-ops, but the *first* one wins, which can
+ * be the wrong verdict). `settled` makes the ordering irrelevant. Extracted
+ * from `spawnGremlins` so that function stays under the long-function budget.
+ *
+ * A factory rather than a class: it holds no collaborators to inject, and the
+ * SOLID analyzer flags `new X()` as a dependency-inversion smell regardless of
+ * whether the type is injectable.
+ */
+function createSettleGuard(resolve: (o: MutationRunOutcome) => void) {
+  let settled = false;
+  let escalationId: NodeJS.Timeout | undefined;
+  let timeoutId: NodeJS.Timeout | undefined;
+
+  const escalateToKill = (child: ChildProcess): void => {
+    if (!settled) child.kill('SIGKILL');
+  };
+
+  const guard = {
+    timedOut: false,
+    /** SIGTERM at `timeoutMs`, escalating to SIGKILL if the child ignores it. */
+    armTimeout(child: ChildProcess, timeoutMs: number): void {
+      timeoutId = setTimeout(() => {
+        guard.timedOut = true;
+        child.kill('SIGTERM');
+        if (settled) return;
+        escalationId = setTimeout(() => escalateToKill(child), SIGKILL_ESCALATION_MS);
+      }, timeoutMs);
+    },
+    settle(outcome: MutationRunOutcome): void {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      if (escalationId) clearTimeout(escalationId);
+      resolve(outcome);
+    },
+  };
+  return guard;
+}
+
+export class GremlinsRunner implements MutationRunner {
+  readonly name = 'pytest-gremlins';
+  readonly extensions = ['py'];
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      execSync('python -c "import pytest_gremlins"', {
+        stdio: 'pipe',
+        timeout: PROBE_TIMEOUT_MS,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async run(options: RunMutationOptions): Promise<MutationRunOutcome> {
+    if (!(await this.isAvailable())) {
+      return { report: null, timedOut: false };
+    }
+
+    // Spawning can throw synchronously (e.g. ENOENT on a broken interpreter
+    // shim); that must surface as a null report, never as an unhandled
+    // rejection that aborts the whole Gate M orchestration.
+    try {
+      return await this.spawnGremlins(options);
+    } catch (err) {
+      return {
+        report: null,
+        timedOut: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /**
+   * Build the argv for `python -m pytest`.
+   *
+   * `-m pytest` rather than a bare `pytest`: the import probe in
+   * `isAvailable()` already proved *this* interpreter carries the plugin, so
+   * running through the same interpreter is the only way to be sure the plugin
+   * is actually loaded.
+   */
+  private gremlinsArgs(options: RunMutationOptions): string[] {
+    return [
+      '-m',
+      'pytest',
+      '--gremlins',
+      `--gremlin-targets=${buildTargets(options.files)}`,
+      '--gremlin-report=console',
+      '--gremlin-parallel',
+      '--gremlin-cache',
+    ];
+  }
+
+  /** Spawn the child and settle exactly once, on close or on error. */
+  private spawnGremlins(options: RunMutationOptions): Promise<MutationRunOutcome> {
+    return new Promise((resolve) => {
+      const guard = createSettleGuard(resolve);
+      let child: ChildProcess;
+      try {
+        child = spawn('python', this.gremlinsArgs(options), {
+          stdio: 'pipe',
+          cwd: options.cwd,
+        });
+      } catch (err) {
+        guard.settle({
+          report: null,
+          timedOut: false,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+      }
+
+      let stdout = '';
+      let stderr = '';
+      guard.armTimeout(child, options.timeoutMs);
+
+      child.stdout?.on('data', (data: Buffer) => {
+        stdout += data.toString();
+      });
+      child.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      child.on('close', (code) => {
+        // A missing report is NOT a failure verdict: parse returns null and the
+        // orchestrator keeps its non-blocking semantics (same contract as the
+        // mutmut runner's null report).
+        guard.settle({
+          report: parseConsoleReport(stdout),
+          timedOut: guard.timedOut,
+          error: code !== 0 ? stderr || stdout : undefined,
+        });
+      });
+
+      child.on('error', (err) => {
+        guard.settle({ report: null, timedOut: guard.timedOut, error: err.message });
+      });
+    });
+  }
+}
+
+/**
+ * Comma-separated mutate targets, deduplicated, derived from the changed
+ * files' directories — `--gremlin-targets` accepts files OR directories, and
+ * the directories keep the mutant count bounded to the touched area.
+ *
+ * Module-level and pure so it is directly testable without instantiating the
+ * runner.
+ */
+function buildTargets(files: string[]): string {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    const dir = dirname(file);
+    dirs.add(dir && dir !== '.' ? dir : file);
+  }
+  return Array.from(dirs).join(',');
+}
+
+/**
+ * Parse pytest-gremlins' console report.
+ *
+ * The report prints two lines (plus a banner):
+ *   Zapped: 142 gremlins (89%)
+ *   Survived: 18 gremlins (11%)
+ *
+ * Returns null when neither line is present — a run that never got to the
+ * report (import failure, collection error, timeout) must not be reported as
+ * a 0% score, which would be a fabricated verdict. `Zapped` maps to killed,
+ * `Survived` to survived; the totals are their sum, matching the mutmut
+ * runner's normalization exactly.
+ */
+export function parseConsoleReport(stdout: string): MutationRunResult | null {
+  const zapped = extractCount(stdout, /Zapped:\s*(\d+)\s*gremlins?/i);
+  const survived = extractCount(stdout, /Survived:\s*(\d+)\s*gremlins?/i);
+
+  if (zapped === null && survived === null) return null;
+
+  const nrOfKilledMutants = zapped ?? 0;
+  const nrOfSurvivedMutants = survived ?? 0;
+  const nrOfMutants = nrOfKilledMutants + nrOfSurvivedMutants;
+  if (nrOfMutants === 0) return null;
+
+  return {
+    mutationScore: (nrOfKilledMutants / nrOfMutants) * 100,
+    nrOfMutants,
+    nrOfKilledMutants,
+    nrOfSurvivedMutants,
+  };
+}
+
+function extractCount(text: string, pattern: RegExp): number | null {
+  const match = text.match(pattern);
+  if (!match?.[1]) return null;
+  const value = parseInt(match[1], 10);
+  return Number.isNaN(value) ? null : value;
+}

package/mutation/runners/index.ts

@@ -7,15 +7,17 @@ export type {
   MutationRunner,
 } from './types';
 
-export { registerRunner, resolveRunner, runnerRegistry } from './types';
+export { registerRunner, resolveRunner, resolveRunners, runnerRegistry } from './types';
 
 export { StrykerRunner } from './stryker-runner';
 export { MutmutRunner } from './mutmut-runner';
+export { GremlinsRunner } from './gremlins-runner';
 export { GoMutantRunner } from './go-mutant-runner';
 export { PitestRunner } from './pitest-runner';
 
 import { StrykerRunner } from './stryker-runner';
 import { MutmutRunner } from './mutmut-runner';
+import { GremlinsRunner } from './gremlins-runner';
 import { GoMutantRunner } from './go-mutant-runner';
 import { PitestRunner } from './pitest-runner';
 import { registerRunner } from './types';
@@ -23,6 +25,12 @@ import { registerRunner } from './types';
 /** Auto-register all known runners. */
 export function registerAllRunners(): void {
   registerRunner(new StrykerRunner());
+  // Registration order decides the `py` winner (resolveRunner returns the
+  // FIRST runner whose extensions include the ext). pytest-gremlins is
+  // registered before mutmut deliberately (#410): it is natively
+  // cross-platform, so when both are installed it is the better default —
+  // mutmut stays reachable via its own runner on Unix-only setups.
+  registerRunner(new GremlinsRunner());
   registerRunner(new MutmutRunner());
   registerRunner(new GoMutantRunner());
   registerRunner(new PitestRunner());

package/mutation/runners/mutmut-runner.ts

@@ -33,25 +33,31 @@ export class MutmutRunner implements MutationRunner {
   constructor(private readonly platform: Platform = process.platform) {}
 
   async isAvailable(): Promise<boolean> {
-    try {
-      execSync('mutmut --version', { stdio: 'pipe', timeout: 5000 });
-      this.route = 'native';
-      return true;
-    } catch {
-      if (this.platform !== 'win32') {
-        this.route = 'unavailable';
-        return false;
-      }
-
+    if (this.platform !== 'win32') {
       try {
-        execSync('wsl mutmut --version', { stdio: 'pipe', timeout: 5000 });
-        this.route = 'wsl';
+        execSync('mutmut --version', { stdio: 'pipe', timeout: 5000 });
+        this.route = 'native';
         return true;
       } catch {
         this.route = 'unavailable';
         return false;
       }
     }
+
+    // Windows: mutmut 3.x is fork()-based and can ONLY run under WSL. A native
+    // `mutmut --version` succeeding therefore proves nothing about `mutmut run`
+    // — reporting route='native' here is exactly the #410 deadlock: every push
+    // reached `mutmut run`, which exits 1 with "please use the WSL", and the
+    // gate blocked on a structurally unachievable check. The route is decided
+    // by the WSL probe alone so an unavailable WSL yields a clean SKIP.
+    try {
+      execSync('wsl mutmut --version', { stdio: 'pipe', timeout: 10000 });
+      this.route = 'wsl';
+      return true;
+    } catch {
+      this.route = 'unavailable';
+      return false;
+    }
   }
 
   async run(options: RunMutationOptions): Promise<MutationRunOutcome> {

package/mutation/runners/types.ts

@@ -90,6 +90,11 @@ export function registerRunner(runner: MutationRunner): void {
 /**
  * Resolve the correct runner for a given file extension.
  * Returns undefined if no runner supports this extension.
+ *
+ * Registration order decides the winner when several runners share an
+ * extension. This is a synchronous fast-path (used by file filtering); the
+ * availability-aware fallback that honors "first AVAILABLE runner" lives in
+ * {@link resolveRunners}.
  */
 export function resolveRunner(ext: string): MutationRunner | undefined {
   const normalized = ext.replace(/^\./, '');
@@ -98,3 +103,18 @@ export function resolveRunner(ext: string): MutationRunner | undefined {
   }
   return undefined;
 }
+
+/**
+ * Resolve ALL runners supporting an extension, in registration (priority)
+ * order — e.g. for `.py` that is [pytest-gremlins, mutmut] (#410).
+ *
+ * The gate walks this list and uses the first runner whose `isAvailable()`
+ * returns true, so a pure-mutmut environment (no gremlins installed) still
+ * gets mutation testing instead of a silent SKIP. This is the actual
+ * implementation of the design contract "gremlins 可用 → GremlinsRunner，
+ * 否则 MutmutRunner".
+ */
+export function resolveRunners(ext: string): MutationRunner[] {
+  const normalized = ext.replace(/^\./, '');
+  return Array.from(runnerRegistry.values()).filter(r => r.extensions.includes(normalized));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.21.0",
+  "version": "0.25.0",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. 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/claude-code/skills/delphi-review/.delphi-config.json.example

@@ -66,5 +66,28 @@
     "max_review_rounds": 5,
     "distinct_models_required": true,
     "cross_provider_required": true
-  }
+  },
+
+  "$comment_seat_fields": [
+    "Optional per-seat fields (#481). The prompt ceiling is a seat x model route",
+    "property, not a global constant: max_prompt_bytes (UTF-8 bytes, default 40000)",
+    "is the hard pre-send gate; prompt_calibration carries the measured bounds used",
+    "to classify a pre-response drop as SIZE_EXCEEDED instead of a network fault.",
+    "Recalibrate (binary search 3-5 probes in [last_pass, last_fail]) whenever the",
+    "model or gateway changes. See docs/plans/2026-10-14-sprint-c-design.md section 2.",
+    "Example expert entry:",
+    "  \"architecture\": {",
+    "    \"provider\": \"bailian-tp\",",
+    "    \"model\": \"qwen-plus\",",
+    "    \"seat_id\": \"architecture\",",
+    "    \"max_prompt_bytes\": 26624,",
+    "    \"prompt_calibration\": {",
+    "      \"measured_at\": \"2026-10-05\",",
+    "      \"model_id\": \"qwen-plus\",",
+    "      \"gateway\": \"bailian\",",
+    "      \"last_pass_bytes\": 26624,",
+    "      \"last_fail_bytes\": 36897",
+    "    }",
+    "  }"
+  ]
 }

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.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/claude-code/skills/delphi-review/SKILL.md

@@ -329,6 +329,15 @@ Each round MUST output a structured round marker:
 
 #### Qoder 平台（Custom Agent 模式 — 只能做到同模型三角色）
 
+**通道契约（native-first + external fallback，#414）**：每轮评审开始先探测 native 通道——三个 Custom Agent（`delphi-architecture/technical/feasibility`）是否存在且绑定互异（`xp-gate doctor delphi` 一条命令给出全部判定）。但 **native 通道已被实测证伪**（见下）：subagent 派发采纳 agent 提示词、丢弃 model 绑定，三席永远是会话模型。因此 Qoder 的通道决策表实际收敛为：
+
+| 探测结果 | 通道 | 处置 |
+|---|---|---|
+| 需要 distinct-models 证据的评审 | **external** | `.delphi-config.json` + `scripts/delphi-external-review.cjs`（外部 provider 三模型） |
+| 仅需同模型三角色自查（不计入共识证据） | native | 三 Custom Agent 并行，报告中注明「同模型自查，不构成多模型凭据」 |
+
+降级证据落盘 `delphi-reviewed.json`：`channel`（native/external）、`fallback_reason`（如 `qoder_native_drops_model_binding`）、`probe_evidence`（doctor/日志摘录）。两通道同不变量：三专家齐全、`requested_model` 互异（external）、consensus ≥90%、**无单专家路径**。
+
 Qoder 的内置模型**没有本地推理端点**：推理请求由 Qoder 客户端经服务端代理发出，凭证是一次性 job token。所以不能照搬 OpenCode 的 `base_url + api_key` 直连方式；Qoder 侧内置模型的唯一入口是 **Custom Agent** —— 每个专家一个独立 agent 文件，frontmatter 用 `model` 字段声明模型。
 
 **契约结论（先说结论）**：这条路径**不满足**"三个不同可执行模型 ID"契约。2026-09-23 做过一次排除混杂因素的复测：先把 `~/.qoder/agents/delphi-*.md` 三份文件绑成三个不同的 0.1× 内置模型（`qfmodel` / `dfmodel` / `gfmodel`；架构角与会话模型同名，所以真正有判别力的是技术角与可行性角），**再**新开会话——新 CLI 进程，`session.config.loaded` 记录 `model: "qfmodel"`，注册表加载的必然是已修好的绑定——然后只派发三个 subagent，各回一句话、不调工具。结果：三个独立的 `is_subagent: true` turn，`turn.started` / `model.request.started` / `model.response.completed` 三处的 `model` 全为会话模型 `qfmodel`，`dfmodel` / `gfmodel` 出现 0 次；同时三份回复分别命中架构 / 技术 / 可行性视角，说明角色提示词确实生效、agent 也确实被加载。即 `subagent_type` 派发路径采纳 Custom Agent 的提示词，但**丢弃**它的 `model` 绑定。
@@ -408,6 +417,20 @@ delphi-review(
 > (1) `dsh-tool-subagent` 的 `modelSelectionSettings: true`（仅能力开关），
 > (2) 宿主设置 `SubagentModelSelectionConfig.enabled = true` 且 `allowedModels` ≥3 个不同模型。
 > 该路线依赖宿主配置，CI / 一次性会话不可靠，故不作为默认路径。
+
+**DSH 双通道契约（native-first + external fallback，#443）**：评审开始先探测 native 通道，两层开关缺一不可——
+
+| 探测步骤 | 方法 | 判定 |
+|---|---|---|
+| ① 工具 schema | 当前会话 `subagent` 工具的参数里是否暴露 `provider` / `model` 字段 | 无 → native 不可用（`enabled` 默认 `false`） |
+| ② 模型清单 | `list_subagent_models` 工具是否注册；可用时返回条数是否 ≥3 且互异 | 未注册或 <3 条 → native 不可用 |
+| ③ 运行时兜底 | 上述任一不满足时调用 subagent 会抛 `child model selection is disabled` | 直接判定，不试错 |
+
+- **native 可用**：三个专家并行派发，每个显式传 `model`（取自 `allowedModels` 三个互异条目）；`resolved_model` 以平台日志/回执为准，无日志时按 #437 过渡标准注明「执行层验证待平台支持」。
+- **native 不可用**：降级 **external**（本 skill 的 `delphi-review` 插件工具，或 `.delphi-config.json` + `scripts/delphi-external-review.cjs`）。缺 API key 时必须给出明确指引（导出环境变量），不得静默失败。
+- 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
+- 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
+- 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：
@@ -432,6 +455,26 @@ WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `
 
 **成本**：3 专家合计 x0.17/轮；主理人选 local 会话模型则零 credits。
 
+### 席位 prompt 上限与降序裁剪（强制 — #481）
+
+prompt 字节上限是 **席位×模型路由 属性**，不是全局安全值（2026-10-05 实测：同一网关下
+`g-glm-5.3-flash` 席 32-39KB 连续 6 次断连，他席 36KB 一次通过）。编排规则：
+
+1. **发送前硬闸**：runner 按 expert 条目的 `max_prompt_bytes`（默认 40000 字节，UTF-8 计）
+   拒发超限请求，输出 `error_type: "prompt_budget_exceeded"`。
+2. **失败分类**：响应前断连且字节数超过该席位标定的 `last_pass_bytes` →
+   `error_type: "SIZE_EXCEEDED"`（不是网络故障，重试同一 payload 无意义）；
+   其余失败输出 `network_error` / `retryable_error`，编排层按 `error_type` 字段断言，不解析散文。
+3. **超限时按降序裁剪，每步只做一步**：
+   ① 去附录（探针填充、日志附录、非必需长引用）→ ② 去非本轮 AC 原文 →
+   ③ 去测试清单（枚举 → 计数）→ ④ 拆分两次调用（按 diff 对半，同报告合并）→
+   ⑤ 仍失败 → `PROCESS_BLOCK` 交人裁定。**不得以两席结果冒充 3/3 共识。**
+4. **标定**：上限按「固定语义核心 + 确定性填充附录」构造探针，在
+   `[last_pass, last_fail]` 区间二分 3-5 次测得；记录行含
+   `seat_id × model_id × gateway × max_passing_bytes × measured_at`；
+   模型或网关变更即重标。协议全文与种子标定表见
+   [docs/plans/2026-10-14-sprint-c-design.md](../../docs/plans/2026-10-14-sprint-c-design.md) §2。
+
 ### 共识阈值
 
 | 阈值 | 说明 |

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.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/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.21.0",
+  "version": "0.25.0",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/.delphi-config.json.example

@@ -66,5 +66,28 @@
     "max_review_rounds": 5,
     "distinct_models_required": true,
     "cross_provider_required": true
-  }
+  },
+
+  "$comment_seat_fields": [
+    "Optional per-seat fields (#481). The prompt ceiling is a seat x model route",
+    "property, not a global constant: max_prompt_bytes (UTF-8 bytes, default 40000)",
+    "is the hard pre-send gate; prompt_calibration carries the measured bounds used",
+    "to classify a pre-response drop as SIZE_EXCEEDED instead of a network fault.",
+    "Recalibrate (binary search 3-5 probes in [last_pass, last_fail]) whenever the",
+    "model or gateway changes. See docs/plans/2026-10-14-sprint-c-design.md section 2.",
+    "Example expert entry:",
+    "  \"architecture\": {",
+    "    \"provider\": \"bailian-tp\",",
+    "    \"model\": \"qwen-plus\",",
+    "    \"seat_id\": \"architecture\",",
+    "    \"max_prompt_bytes\": 26624,",
+    "    \"prompt_calibration\": {",
+    "      \"measured_at\": \"2026-10-05\",",
+    "      \"model_id\": \"qwen-plus\",",
+    "      \"gateway\": \"bailian\",",
+    "      \"last_pass_bytes\": 26624,",
+    "      \"last_fail_bytes\": 36897",
+    "    }",
+    "  }"
+  ]
 }

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

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.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/dsh/skills/delphi-review/SKILL.md

@@ -329,6 +329,15 @@ Each round MUST output a structured round marker:
 
 #### Qoder 平台（Custom Agent 模式 — 只能做到同模型三角色）
 
+**通道契约（native-first + external fallback，#414）**：每轮评审开始先探测 native 通道——三个 Custom Agent（`delphi-architecture/technical/feasibility`）是否存在且绑定互异（`xp-gate doctor delphi` 一条命令给出全部判定）。但 **native 通道已被实测证伪**（见下）：subagent 派发采纳 agent 提示词、丢弃 model 绑定，三席永远是会话模型。因此 Qoder 的通道决策表实际收敛为：
+
+| 探测结果 | 通道 | 处置 |
+|---|---|---|
+| 需要 distinct-models 证据的评审 | **external** | `.delphi-config.json` + `scripts/delphi-external-review.cjs`（外部 provider 三模型） |
+| 仅需同模型三角色自查（不计入共识证据） | native | 三 Custom Agent 并行，报告中注明「同模型自查，不构成多模型凭据」 |
+
+降级证据落盘 `delphi-reviewed.json`：`channel`（native/external）、`fallback_reason`（如 `qoder_native_drops_model_binding`）、`probe_evidence`（doctor/日志摘录）。两通道同不变量：三专家齐全、`requested_model` 互异（external）、consensus ≥90%、**无单专家路径**。
+
 Qoder 的内置模型**没有本地推理端点**：推理请求由 Qoder 客户端经服务端代理发出，凭证是一次性 job token。所以不能照搬 OpenCode 的 `base_url + api_key` 直连方式；Qoder 侧内置模型的唯一入口是 **Custom Agent** —— 每个专家一个独立 agent 文件，frontmatter 用 `model` 字段声明模型。
 
 **契约结论（先说结论）**：这条路径**不满足**"三个不同可执行模型 ID"契约。2026-09-23 做过一次排除混杂因素的复测：先把 `~/.qoder/agents/delphi-*.md` 三份文件绑成三个不同的 0.1× 内置模型（`qfmodel` / `dfmodel` / `gfmodel`；架构角与会话模型同名，所以真正有判别力的是技术角与可行性角），**再**新开会话——新 CLI 进程，`session.config.loaded` 记录 `model: "qfmodel"`，注册表加载的必然是已修好的绑定——然后只派发三个 subagent，各回一句话、不调工具。结果：三个独立的 `is_subagent: true` turn，`turn.started` / `model.request.started` / `model.response.completed` 三处的 `model` 全为会话模型 `qfmodel`，`dfmodel` / `gfmodel` 出现 0 次；同时三份回复分别命中架构 / 技术 / 可行性视角，说明角色提示词确实生效、agent 也确实被加载。即 `subagent_type` 派发路径采纳 Custom Agent 的提示词，但**丢弃**它的 `model` 绑定。
@@ -408,6 +417,20 @@ delphi-review(
 > (1) `dsh-tool-subagent` 的 `modelSelectionSettings: true`（仅能力开关），
 > (2) 宿主设置 `SubagentModelSelectionConfig.enabled = true` 且 `allowedModels` ≥3 个不同模型。
 > 该路线依赖宿主配置，CI / 一次性会话不可靠，故不作为默认路径。
+
+**DSH 双通道契约（native-first + external fallback，#443）**：评审开始先探测 native 通道，两层开关缺一不可——
+
+| 探测步骤 | 方法 | 判定 |
+|---|---|---|
+| ① 工具 schema | 当前会话 `subagent` 工具的参数里是否暴露 `provider` / `model` 字段 | 无 → native 不可用（`enabled` 默认 `false`） |
+| ② 模型清单 | `list_subagent_models` 工具是否注册；可用时返回条数是否 ≥3 且互异 | 未注册或 <3 条 → native 不可用 |
+| ③ 运行时兜底 | 上述任一不满足时调用 subagent 会抛 `child model selection is disabled` | 直接判定，不试错 |
+
+- **native 可用**：三个专家并行派发，每个显式传 `model`（取自 `allowedModels` 三个互异条目）；`resolved_model` 以平台日志/回执为准，无日志时按 #437 过渡标准注明「执行层验证待平台支持」。
+- **native 不可用**：降级 **external**（本 skill 的 `delphi-review` 插件工具，或 `.delphi-config.json` + `scripts/delphi-external-review.cjs`）。缺 API key 时必须给出明确指引（导出环境变量），不得静默失败。
+- 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
+- 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
+- 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：
@@ -432,6 +455,26 @@ WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `
 
 **成本**：3 专家合计 x0.17/轮；主理人选 local 会话模型则零 credits。
 
+### 席位 prompt 上限与降序裁剪（强制 — #481）
+
+prompt 字节上限是 **席位×模型路由 属性**，不是全局安全值（2026-10-05 实测：同一网关下
+`g-glm-5.3-flash` 席 32-39KB 连续 6 次断连，他席 36KB 一次通过）。编排规则：
+
+1. **发送前硬闸**：runner 按 expert 条目的 `max_prompt_bytes`（默认 40000 字节，UTF-8 计）
+   拒发超限请求，输出 `error_type: "prompt_budget_exceeded"`。
+2. **失败分类**：响应前断连且字节数超过该席位标定的 `last_pass_bytes` →
+   `error_type: "SIZE_EXCEEDED"`（不是网络故障，重试同一 payload 无意义）；
+   其余失败输出 `network_error` / `retryable_error`，编排层按 `error_type` 字段断言，不解析散文。
+3. **超限时按降序裁剪，每步只做一步**：
+   ① 去附录（探针填充、日志附录、非必需长引用）→ ② 去非本轮 AC 原文 →
+   ③ 去测试清单（枚举 → 计数）→ ④ 拆分两次调用（按 diff 对半，同报告合并）→
+   ⑤ 仍失败 → `PROCESS_BLOCK` 交人裁定。**不得以两席结果冒充 3/3 共识。**
+4. **标定**：上限按「固定语义核心 + 确定性填充附录」构造探针，在
+   `[last_pass, last_fail]` 区间二分 3-5 次测得；记录行含
+   `seat_id × model_id × gateway × max_passing_bytes × measured_at`；
+   模型或网关变更即重标。协议全文与种子标定表见
+   [docs/plans/2026-10-14-sprint-c-design.md](../../docs/plans/2026-10-14-sprint-c-design.md) §2。
+
 ### 共识阈值
 
 | 阈值 | 说明 |

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

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.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/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.