@boyingliu01/xp-gate 0.35.17 → 0.35.18

package/lib/__tests__/gate-numbering.test.js

@@ -0,0 +1,52 @@
+/**
+ * @test REQ-686
+ * @intent 验证 CLI 的门禁编号与钩子一致——钩子把 9 号门叫 Build integrity、
+ *         10 号门叫 SAST，而 CLI 注册表把两者对调了；用户按报错提示单跑对应门
+ *         会跑到另一道门上去（#677）
+ * @covers AC-686-01, AC-686-02, AC-686-03
+ *
+ * 为什么必须直接断言注册表：这个错误的表现是「跑起来了、报告绿了」。
+ * `xp-gate check --gates 9` 在编号错位时不会报错，它跑的是 semgrep 并如实报告
+ * semgrep 的结果——只有拿它和钩子里的门名对照才能看出跑错了门。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { GATE_REGISTRY, resolveAlias } = require('../gate-runner');
+
+const REPO_ROOT = path.join(__dirname, '../../../..');
+
+describe('gate numbering matches the hook (#677)', () => {
+  it('AC-686-01: gate 9 is Build Integrity and gate 10 is SAST Security', () => {
+    expect(GATE_REGISTRY['9'].name).toBe('Build Integrity');
+    expect(GATE_REGISTRY['10'].name).toBe('SAST Security');
+  });
+
+  it('AC-686-02: the hook agrees — its own output names 9 as Build integrity', () => {
+    // Reads the hook rather than restating the constant: if the hook ever
+    // renumbers again, this fails and points at which side moved.
+    const hook = fs.readFileSync(path.join(REPO_ROOT, 'githooks/pre-commit'), 'utf8');
+    expect(hook).toMatch(/→ Gate 9: Build integrity/);
+    expect(hook).toMatch(/GATE 10: Semgrep SAST/);
+  });
+
+  it('AC-686-03: aliases resolve to the gate the user meant', () => {
+    expect(resolveAlias('sast')).toBe('10');
+    expect(resolveAlias('semgrep')).toBe('10');
+    expect(resolveAlias('build')).toBe('9');
+  });
+
+  it('AC-686-03: gates 12 and 13 are registered instead of "Unknown gate(s)"', () => {
+    // Both block commits in the hook. Answering "Unknown gate" for a gate that just
+    // blocked the user is the same category of wrong as running the wrong one.
+    expect(GATE_REGISTRY['12'].name).toBe('File Hygiene');
+    expect(GATE_REGISTRY['13'].name).toBe('Compiler Strictness');
+    // They are registered as hook-only, with a stated reason -- not as runnable
+    // stubs that would answer PASS without doing the work.
+    expect(GATE_REGISTRY['12'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['13'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['12'].reason).toBeTruthy();
+    expect(GATE_REGISTRY['13'].reason).toBeTruthy();
+  });
+});

package/lib/__tests__/gate-runner.test.js

@@ -9,6 +9,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { execFileSync, spawnSync } = require('node:child_process');
+const { findConsumerGateVariant } = require('../gate-runner');
 
 let tmpProject;
 let tmpAdapters;
@@ -25,15 +26,26 @@ afterEach(() => {
   }
 });
 
+// Fixture writers run in every `beforeAll`; swallowing their failure would turn a
+// broken fixture into "the gate under test misbehaved", which is the opposite of
+// what the assertion is checking. Report which file could not be written.
+function writeFixture(filePath, content) {
+  try {
+    fs.writeFileSync(filePath, content);
+  } catch (err) {
+    throw new Error(`Cannot write test fixture ${filePath}: ${err.message}`);
+  }
+}
+
 function writeAdapterCommon() {
-  fs.writeFileSync(
+  writeFixture(
     path.join(tmpAdapters, 'adapter-common.sh'),
     'detect_project_lang() { echo "typescript"; }'
   );
 }
 
 function writeGateFragment(fragmentLines) {
-  fs.writeFileSync(
+  writeFixture(
     path.join(tmpAdapters, 'gate-9.sh'),
     ['# gate-9 fragment', ...fragmentLines, 'exit 0'].join('\n')
   );
@@ -55,14 +67,21 @@ function hostilePathSegment() {
 }
 
 function initializeGitProject() {
-  execFileSync('git', ['init', '-q'], { cwd: tmpProject });
-  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: tmpProject });
-  execFileSync('git', ['config', 'user.name', 'XP-Gate Test'], { cwd: tmpProject });
-  fs.writeFileSync(path.join(tmpProject, 'tracked.ts'), 'const value = 1;\n');
-  execFileSync('git', ['add', 'tracked.ts'], { cwd: tmpProject });
-  execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'initial'], {
-    cwd: tmpProject,
-  });
+  try {
+    execFileSync('git', ['init', '-q'], { cwd: tmpProject });
+    execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: tmpProject });
+    execFileSync('git', ['config', 'user.name', 'XP-Gate Test'], { cwd: tmpProject });
+    writeFixture(path.join(tmpProject, 'tracked.ts'), 'const value = 1;\n');
+    execFileSync('git', ['add', 'tracked.ts'], { cwd: tmpProject });
+    execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'initial'], {
+      cwd: tmpProject,
+    });
+  } catch (err) {
+    // Without this the failure surfaces as a downstream assertion on the gate's
+    // output. Name the setup step instead: a repo fixture that never initialised
+    // is not a gate defect.
+    throw new Error(`Cannot initialise the fixture git repo at ${tmpProject}: ${err.message}`);
+  }
 }
 
 // Runs runGateAdapter in a child node process (worker threads forbid process
@@ -188,7 +207,7 @@ describe('gate-runner.js — runGateAdapter', () => {
       ].join('\n')
     );
 
-    const result = spawnSync(process.execPath, [cliPath, 'check', '9'], {
+    const result = spawnSync(process.execPath, [cliPath, 'check', '10'], {
       cwd: tmpProject,
       encoding: 'utf8',
       timeout: 30000,
@@ -225,7 +244,7 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10', targetProject],
       {
         cwd: callerProject,
         encoding: 'utf8',
@@ -283,7 +302,7 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9'],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10'],
       { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
     );
 
@@ -301,10 +320,36 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10', targetProject],
       { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
     );
 
     expect(result.status).toBe(1);
   }, 30000);
+
+  // The mirror image of the tests above, asserted on the resolver rather than on
+  // CLI output. A project that declares no variant must resolve to nothing, so
+  // the built-in implementation still runs.
+  //
+  // Asserted here, not through `check 9`: BOTH implementations print "Semgrep"
+  // (githooks/gate-9.sh says it five times too), and a bash fallback that finds
+  // no script prints neither banner, so every stdout-based assertion passed even
+  // with the TypeScript module hard-disabled -- the guard proved nothing.
+  it('resolves no variant when the project declares none (REQ-standalone-gates-05)', () => {
+    const plainProject = path.join(tmpProject, 'plain-target');
+    fs.mkdirSync(plainProject, { recursive: true });
+
+    expect(findConsumerGateVariant('gate-9', plainProject)).toBe(null);
+  });
+
+  it('resolves the declared variant when the project has one (REQ-standalone-gates-05)', () => {
+    const variantProject = path.join(tmpProject, 'variant-target');
+    const gatesDir = path.join(variantProject, 'githooks', 'gates');
+    fs.mkdirSync(gatesDir, { recursive: true });
+    const variantPath = path.join(gatesDir, 'gate-9-project-choice.sh');
+    fs.writeFileSync(variantPath, 'exit 0\n');
+
+    const resolved = findConsumerGateVariant('gate-9', variantProject);
+    expect(resolved).toBe(variantPath);
+  });
 });

package/lib/__tests__/shared-utils.test.js

@@ -130,4 +130,51 @@ describe('shared-utils', () => {
     });
   });
 
+  describe('copyDirRecursive (#640 concurrency)', () => {
+    // The mirrored trees this walks are rewritten in place by
+    // scripts/sync-package-content.js. A concurrent init enumerates the
+    // directory, then finds an entry gone -- ENOENT on a file that reappears
+    // microseconds later. That must not abort the install.
+    it('skips a file that disappears between enumeration and copy', () => {
+      const src = path.join(tmpRoot, 'src');
+      const dest = path.join(tmpRoot, 'dest');
+      fs.mkdirSync(src, { recursive: true });
+      fs.writeFileSync(path.join(src, 'stable.sh'), 'stable');
+      fs.writeFileSync(path.join(src, 'vanishing.sh'), 'vanishing');
+
+      const realReadFileSync = fs.readFileSync;
+      vi.spyOn(fs, 'readFileSync').mockImplementation((p, ...rest) => {
+        if (String(p).endsWith('vanishing.sh')) {
+          const err = new Error('ENOENT: no such file or directory');
+          err.code = 'ENOENT';
+          throw err;
+        }
+        return realReadFileSync(p, ...rest);
+      });
+
+      const { copyDirRecursive } = require('../shared-utils');
+      expect(() => copyDirRecursive(src, dest)).not.toThrow();
+      expect(fs.existsSync(path.join(dest, 'stable.sh'))).toBe(true);
+      expect(fs.existsSync(path.join(dest, 'vanishing.sh'))).toBe(false);
+    });
+
+    it('still surfaces a real read error instead of silently skipping', () => {
+      // Only ENOENT means "being replaced". A permission or disk error is a real
+      // failure, and swallowing it would ship a half-installed hook set.
+      const src = path.join(tmpRoot, 'src2');
+      const dest = path.join(tmpRoot, 'dest2');
+      fs.mkdirSync(src, { recursive: true });
+      fs.writeFileSync(path.join(src, 'locked.sh'), 'locked');
+
+      vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+        const err = new Error('EACCES: permission denied');
+        err.code = 'EACCES';
+        throw err;
+      });
+
+      const { copyDirRecursive } = require('../shared-utils');
+      expect(() => copyDirRecursive(src, dest)).toThrow(/EACCES/);
+    });
+  });
+
 });

package/lib/gate-runner.js

@@ -361,16 +361,69 @@ function resolveNpxInvocation(args) {
   return ['npx', args];
 }
 
+/**
+ * A project-local gate variant, if the project declares one.
+ *
+ * `<consumer cwd>/githooks/gates/gate-<n>-<name>.sh` is where a PROJECT puts its
+ * own variant of a gate: the hyphenated name is the point, because it lets one
+ * project keep several variants where a flat `gate-<n>.sh` cannot express the
+ * choice (#672, restored by 7b43666a). `xp-gate init` never creates that
+ * directory, so a stock project simply falls through to the built-in
+ * implementation and nothing changes for it.
+ *
+ * This is deliberately NOT the same as `<project>/src/gates/<gate>.ts`, which
+ * `findTsGateEntry` refuses to read (#672): that path let the party being
+ * checked supply the implementation, so `process.exit(0)` passed every gate.
+ * Declaring a variant under `githooks/gates/` is an explicit, named opt-in;
+ * dropping a file into `src/gates/` is not.
+ *
+ * @param {string} gateModule e.g. 'gate-9'
+ * @param {string} cwd project root to search
+ * @returns {string|null}
+ */
+function findConsumerGateVariant(gateModule, cwd) {
+  const gateNum = gateModule.replace('gate-', '');
+  // Strictly the project's own declaration. `resolveGateScript` additionally
+  // probes the flat `githooks/gate-<n>.sh` and the global install
+  // (~/.config/xp-gate/adapters/); treating either as "the project declared a
+  // variant" would hand every gate to whichever bash copy happens to be
+  // installed -- on a machine with a global install that is *always*. A variant
+  // is a file the project deliberately named, so only `githooks/gates/` counts.
+  const gatesDir = path.join(cwd, 'githooks', 'gates');
+  const declared = matchGateFileIn(gatesDir, gateNum);
+  return declared ? path.join(gatesDir, declared) : null;
+}
+
+/**
+ * Which implementation runs this gate: a project-declared variant, the built-in
+ * TypeScript module, or a bash fallback.
+ *
+ * Split out of `runTsGate` so that function stays about running the gate. The
+ * precedence is a contract with two sides -- `githooks/gates/` is the project's
+ * opt-in, and the built-in module must remain reachable when nobody opted in --
+ * so it is named here rather than inlined in the runner.
+ *
+ * @returns {{kind: 'variant', script: string} | {kind: 'module', entry: string} | {kind: 'fallback', script: string} | {kind: 'none'}}
+ */
+function resolveGateImplementation(gateModule, targetCwd) {
+  const variant = findConsumerGateVariant(gateModule, targetCwd);
+  if (variant) return { kind: 'variant', script: variant };
+
+  const entry = findTsGateEntry(gateModule);
+  if (entry) return { kind: 'module', entry };
+
+  const script = resolveGateScript(gateModule.replace('gate-', ''), targetCwd);
+  return script ? { kind: 'fallback', script } : { kind: 'none' };
+}
+
 function runTsGate(gateModule, targetPath, opts = {}) {
   const targetCwd = resolveGateCwd(targetPath);
-  const entry = findTsGateEntry(gateModule);
-  if (!entry) {
-    // Fallback to bash script
-    const gateNum = gateModule.replace('gate-', '');
-    const script = resolveGateScript(gateNum, targetCwd);
-    if (script) {
-      return runGateAdapter(script, targetCwd, opts);
-    }
+  const impl = resolveGateImplementation(gateModule, targetCwd);
+
+  if (impl.kind === 'variant' || impl.kind === 'fallback') {
+    return runGateAdapter(impl.script, targetCwd, opts);
+  }
+  if (impl.kind === 'none') {
     // #618: nothing ran. Before this, the function fell through to `return 0`
     // and the --all summary counted the gate as passed.
     console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
@@ -378,7 +431,7 @@ function runTsGate(gateModule, targetPath, opts = {}) {
     return GATE_NOT_RUN;
   }
 
-  const args = ['-y', 'tsx', entry, '--run'];
+  const args = ['-y', 'tsx', impl.entry, '--run'];
   if (targetPath) args.push('--cwd', targetPath);
 
   // spawnSync reports a spawn failure (npx missing) on `error`, throws only on a
@@ -508,21 +561,28 @@ const GATE_REGISTRY = {
       return runTsGate('gate-8', targetPath);
     },
   },
+  // Numbering follows the HOOK, which is where gates actually execute (#677).
+  // These two were swapped here: the CLI called 9 "SAST" and 10 "Build Integrity"
+  // while the hook runs 9=Build integrity and 10=Semgrep SAST. A user reading
+  // "❌ BLOCKED - Gate 9: Build integrity check failed" in their commit output and
+  // then running `xp-gate check --gates 9` got semgrep -- a different gate, reported
+  // green. The hook is the majority implementation and the one the error message
+  // names, so its numbering wins.
   '9': {
+    name: 'Build Integrity',
+    description: 'TypeScript compilation, npm pack, and import validation',
+    aliases: ['build', '9'],
+    preCommitOnly: true,
+    reason: 'Build integrity checks require language detection and build tool context',
+  },
+  '10': {
     name: 'SAST Security',
     description: 'semgrep static application security testing',
-    aliases: ['sast', 'semgrep', '9'],
+    aliases: ['sast', 'semgrep', '10'],
     run: (targetPath) => {
       return runTsGate('gate-9', targetPath);
     },
   },
-  '10': {
-    name: 'Build Integrity',
-    description: 'TypeScript compilation, npm pack, and import validation',
-    aliases: ['build', '10'],
-    preCommitOnly: true,
-    reason: 'Build integrity checks require language detection and build tool context',
-  },
   '11': {
     name: 'Sprint Flow Enforcement',
     description: 'Sprint state and delphi-review validation',
@@ -530,6 +590,26 @@ const GATE_REGISTRY = {
     preCommitOnly: true,
     reason: 'Requires sprint state (.sprint-state/) and git branch context',
   },
+  // Gates 12 and 13 block commits in the hook but were absent here entirely, so
+  // `xp-gate check --gates 12` answered "Unknown gate(s)" for a gate that had just
+  // blocked the user (#677). Registered with an explicit reason rather than
+  // pretending to re-implement them: both need the staged-diff and per-language
+  // build context the hook assembles, and a half-correct reimplementation that
+  // answered PASS would be worse than saying so.
+  '12': {
+    name: 'File Hygiene',
+    description: 'conflict markers (blocking) + YAML/JSON syntax (blocking) + whitespace warnings',
+    aliases: ['hygiene', 'file-hygiene', '12'],
+    preCommitOnly: true,
+    reason: 'File hygiene inspects the staged diff, which only exists inside the hook',
+  },
+  '13': {
+    name: 'Compiler Strictness',
+    description: 'gcc/g++ -Wall -Wextra, javac -Xlint, Maven/Gradle warnings on changed files',
+    aliases: ['compiler', 'strictness', '13'],
+    preCommitOnly: true,
+    reason: 'Compiler strictness needs the changed-file set and a discovered toolchain',
+  },
   'python-health': {
     name: 'Python Environment Health',
     description: 'Comprehensive Python environment diagnostics',
@@ -718,4 +798,4 @@ async function runGate(gateId, targetPath, opts = {}) {
   return 1;
 }
 
-module.exports = { GATE_REGISTRY, GATE_NOT_RUN, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };
+module.exports = { findConsumerGateVariant, GATE_REGISTRY, GATE_NOT_RUN, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-31T07:40:57.523Z",
+  "checked_at": "2026-10-31T16:53:19.066Z",
   "source": "network"
 }

package/lib/shared-utils.js

@@ -8,6 +8,19 @@ const path = require('path');
 /**
  * Recursively copy a directory.
  * Pure function: only uses fs/path params, no global config.
+ *
+ * A file that disappears between `readdirSync` and `copyFileSync` is skipped
+ * rather than crashing the whole copy. That is not defensive padding: the
+ * mirrored trees this walks (`hooks/`, `adapters/`) are rewritten in place by
+ * `scripts/sync-package-content.js`, which unlinks and recreates each entry. A
+ * concurrent `xp-gate init` (or a test suite that runs init while another test
+ * invokes the sync) enumerates the directory, then finds the entry gone --
+ * `ENOENT` on a file that will exist again microseconds later. Aborting the
+ * install there would report a broken package for a transient race.
+ *
+ * Copies the CONTENT instead of `copyFileSync` so the read and the write both
+ * see a consistent snapshot, and only ENOENT is tolerated -- permission and
+ * disk errors still surface, because those are real failures.
  */
 function copyDirRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -18,11 +31,24 @@ function copyDirRecursive(src, dest) {
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      copyFileContents(srcPath, destPath);
     }
   }
 }
 
+/** Copy one file, treating "vanished mid-copy" as a skip. @returns {boolean} whether it was copied */
+function copyFileContents(srcPath, destPath) {
+  let data;
+  try {
+    data = fs.readFileSync(srcPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+  fs.writeFileSync(destPath, data);
+  return true;
+}
+
 function readXpGateConfig() {
   const cfgPath = path.join(require('os').homedir(), '.xp-gate', 'config.json');
   try {

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 26a741de
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 26a741de
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.35.17",
+  "version": "0.35.18",
   "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.35.17",
+  "version": "0.35.18",
   "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/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 26a741de
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.18.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/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 26a741de
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.18.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/sprint-flow/__tests__/verify-sprint-state.test.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+# @test REQ-688
+# @intent 验证 sprint-flow 的校验脚本能接受 `xp-gate sprint-init` 自己写出的状态文件
+#         ——脚本曾要求 sprint_id/current_phase/phases 这套从未被写入过的键，
+#         对 CLI 刚创建的 sprint 恒判失败（#679）
+# @covers AC-688-01, AC-688-02
+#
+# 为什么用真 sprint-init 而不是手写一个 fixture：缺陷的本质是「校验方与生产方对
+# schema 的认知不一致」。手写 fixture 会把「我认为 CLI 写什么」固化下来，双方一起
+# 错就一起绿。只有让生产方真的产出、校验方真的读，才能发现这类偏差。
+
+setup() {
+  REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../.." && pwd)"
+  VERIFY="$REPO_ROOT/skills/sprint-flow/scripts/verify-sprint-state.sh"
+  CLI="$REPO_ROOT/src/npm-package/bin/xp-gate.js"
+  WORK="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$WORK"
+}
+
+@test "AC-688-01: accepts state written by xp-gate sprint-init" {
+  cd "$WORK"
+  git init -q .
+  echo '{}' > package.json
+  git add -A
+  git -c user.email=t@t -c user.name=t commit -q -m init
+
+  run node "$CLI" sprint-init "probe task"
+  [ -f ".sprint-state/sprint-state.json" ]
+
+  run bash "$VERIFY"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"OK:"* ]]
+}
+
+@test "AC-688-02: still rejects a state file missing real keys" {
+  # The fix must not become "accept anything": a file that lost its task or its
+  # phase is genuinely broken and the verifier should say so.
+  mkdir -p "$WORK/.sprint-state"
+  printf '{"id":"s-1","phase":"BUILD"}\n' > "$WORK/.sprint-state/sprint-state.json"
+
+  cd "$WORK"
+  run bash "$VERIFY"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"task_description"* ]]
+}

package/plugins/claude-code/skills/sprint-flow/references/definition-of-done.md

@@ -0,0 +1,47 @@
+# Definition of Done（统一完成定义）
+
+一个 REQ 只有在**全部 10 项**都可指向证据时才算完成。这份清单是 #607 的落地，
+对应指南 §12；它存在的理由是本仓库历史上反复出现「以为完成了，其实没有」：
+
+- **#561** 覆盖率阈值形状写错（`Path` 而非 `Partial<Record>`），声明 80% 但整个门禁是空转
+- **#570** 覆盖率检查 fail-open，跑不起来时报告通过
+- **#585** Gate 5c 静默通过
+- **.xp-gate/modules 陈旧副本**（2026-10-19）劫持 Gate 6 数周，hook 报的警告数和独立扫描永远对不上
+
+共同点全部是：**某一步从未真正执行，而没有任何东西把这件事说出来。**
+所以这份清单里每一项的判据都是「证据在哪儿」，不是「做没做」。
+
+---
+
+## 10 项完成定义
+
+| # | 条目 | 判据（必须能指出位置） |
+|---|------|------------------------|
+| 1 | **需求可追溯** | `specification.yaml` 有 REQ + AC；测试文件带 `@covers AC-xxx`；`scripts/__tests__/ac-reference-guard.test.cjs` 通过 |
+| 2 | **测试先行** | 实现前存在失败的测试；或说明为何不适用（纯文档/配置） |
+| 3 | **测试真的能失败** | 至少一个变异体/破坏被测试抓住。「测试通过」在从未运行时和「功能正确」无法区分 |
+| 4 | **验证命令已运行** | 记录实际命令与输出，不是「应该是绿的」。CI 命令与本地命令一致 |
+| 5 | **门禁未降级** | 无 `--no-verify`；无新增基线额度来吸收本次改动自身的告警 |
+| 6 | **镜像已同步** | 改了 `githooks/`/`skills/`/`plugins/` → `bash scripts/check-hook-mirror.sh` 输出 PASS |
+| 7 | **不做未经要求的相邻改动** | 每行改动可追溯到本 REQ；顺手发现的无关死代码只提及不删除 |
+| 8 | **已知限制已写明** | 没做的部分、以及为什么没做，写进 issue/提交，而不是留空 |
+| 9 | **文档与实现一致** | 门禁数量、CLI 表、阈值等出现在多处的事实同步更新（见 `AGENTS.md` "Known Drift"） |
+| 10 | **可回滚** | 提交粒度单一；出问题时能单独 revert 而不牵连其他改动 |
+
+---
+
+## 相位落点
+
+- **Phase 4 VERIFY**：逐项过 1/2/3/4/5/6，任何一项拿不出证据 → 不得进入 SHIP。
+- **Phase 5 SHIP**：逐项过 7/8/9/10，然后才推送。
+- **Phase 6 CLOSE**：把第 8 项「已知限制」回填到 issue 并关闭。
+
+## 常见误判
+
+| 看起来完成了 | 实际没有 |
+|---|---|
+| 「测试通过」 | 没跑过会失败的版本，不知道它能不能失败 |
+| 「门禁有配置」 | 配置形状错/键名不对时被静默丢弃，等于没有（#561） |
+| 「工具缺失时跳过」 | 跳过被当成通过；只有 Gate 8 是 fail-closed |
+| 「CI 绿了」 | CI 可能没跑到那一步（`if:` 条件不满足），或跑的是旧副本（#451） |
+| 「注释写了这么做」 | 注释与代码漂移；只有测试能固定行为 |

package/plugins/claude-code/skills/sprint-flow/references/phase-4-verify.md

@@ -142,6 +142,22 @@ ELSE:
 - Web 前端附加: ui-review report + OPTIONAL QA/design-review/benchmark reports
 - 验证通过的 MVP
 
+### 完成定义（DoD 第 1–6 项）
+
+离开 VERIFY 前逐项过一遍 [`definition-of-done.md`](./definition-of-done.md)。**任何一项拿不出证据 → 不得进入 SHIP。**
+
+| # | 条目 | 在 VERIFY 的检查方式 |
+|---|------|----------------------|
+| 1 | 需求可追溯 | `npx vitest run scripts/__tests__/ac-reference-guard.test.cjs` 通过（测试引用的 AC 都在 spec 里） |
+| 2 | 测试先行 | 有 RED 证据（提交历史或记录），或说明为何不适用 |
+| 3 | **测试真的能失败** | 至少证明过一个变异体会被抓住——「测试通过」在从未运行时与「功能正确」无法区分 |
+| 4 | 验证命令已运行 | 记录实际命令 + 输出，不是「应该是绿的」 |
+| 5 | 门禁未降级 | 无 `--no-verify`；无为了本次改动新增的基线额度 |
+| 6 | 镜像已同步 | `bash scripts/check-hook-mirror.sh` → PASS |
+
+第 5 项值得单独说明：**加基线额度来吸收自己刚产生的告警，等于把门禁关掉一次。**
+`.warnings-baseline.json` 只应记录「改动之前就存在」的告警。
+
 ---
 
 ## Part B: FEEDBACK CAPTURE（反馈获取）