kld-sdd 2.4.13 → 2.4.15

package/README.md

@@ -1,12 +1,12 @@
 # kld-sdd
 
-KLD SDD OpenSpec 项目初始化工具 - 一键初始化 AI 编辑器命令与技能，支持完整的 SDD（规格驱动开发）研发工作流。
+KLD SDD OpenSpec 项目初始化工具 - 一键初始化 AI 编辑器技能，支持完整的 SDD（规格驱动开发）研发工作流。
 
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。
 
-`kld-sdd` 帮你在项目中一键配置好这套工作流所需的全部 AI 命令和技能，支持 **Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex** 等编辑器。
+`kld-sdd` 帮你在项目中一键配置好这套工作流所需的全部 AI 技能，支持 **Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex** 等编辑器。
 
 ## 快速开始
 
@@ -15,21 +15,21 @@ KLD SDD OpenSpec 项目初始化工具 - 一键初始化 AI 编辑器命令与
 npx kld-sdd
 ```
 
-初始化完成后，打开你的 AI 编辑器，就能用 `/opsx:*` 命令开始工作了。
+初始化完成后，打开你的 AI 编辑器，激活 `opsx-*` skills 开始工作。
 
 ---
 
-## 核心工作流：5 个命令
+## 核心工作流：5 个 skills
 
-初始化后，你会得到以下 6 个 `/opsx:*` 命令，按顺序使用：
+初始化后，你会得到以下 SDD skills，按顺序使用：
 
 ```
-propose → spec → design → task → check
-                                    ↓
-                              skill（独立使用）
+opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
+                                                          ↓
+                                                    opsx-knowledge（独立使用）
 ```
 
-### 第一步：`/opsx:propose <变更名称>`
+### 第一步：`opsx-propose <变更名称>`
 
 **做什么**：创建业务意图文档，明确"为什么要做这件事"。
 
@@ -44,7 +44,7 @@ propose → spec → design → task → check
 
 ---
 
-### 第二步：`/opsx:spec <变更名称>`
+### 第二步：`opsx-spec <变更名称>`
 
 **做什么**：创建技术契约文档，明确"要实现什么 API 和规范"。
 
@@ -64,7 +64,7 @@ propose → spec → design → task → check
 
 ---
 
-### 第三步：`/opsx:design <变更名称>`
+### 第三步：`opsx-design <变更名称>`
 
 **做什么**：创建技术实现方案，明确"怎么做"（聚焦本业务，不写全局架构）。
 
@@ -82,7 +82,7 @@ propose → spec → design → task → check
 
 ---
 
-### 第四步：`/opsx:task <变更名称>`
+### 第四步：`opsx-task <变更名称>`
 
 **做什么**：将 design.md 拆解为 AI 可执行的原子任务列表。
 
@@ -102,11 +102,11 @@ propose → spec → design → task → check
 
 ---
 
-### 第五步：`/opsx:check <变更名称>`
+### 第五步：`opsx-check <变更名称>`
 
 **做什么**：质量门禁检查，验证文档链的完整性、一致性和可执行性。
 
-**在让 AI 写代码之前，先运行这个命令。**
+**在让 AI 写代码之前，先激活这个 skill。**
 
 **检查内容**：
 | 检查项 | 说明 |
@@ -119,20 +119,9 @@ propose → spec → design → task → check
 
 ---
 
-### 独立使用：`/opsx:skill <文档路径>`
+### 独立使用：`opsx-knowledge`
 
-**做什么**：把你的团队规范文档（代码规范、API 设计规范等）转化为标准的 **Claude Skills 格式**技能文件，让 AI 每次都遵守你的团队规范。
-
-**适合场景**：
-- 把公司 Java 编码规范文档 → 生成 `java-code-style` 技能
-- 把 API 设计规范文档 → 生成 `api-design-rules` 技能
-- 把架构规范文档 → 生成 `arch-guidelines` 技能
-
-**AI 会做什么**：
-1. 读取你的规范文档，提炼四类规则（必须/禁止/推荐/例外）
-2. 识别规则模糊或冲突时，向你澄清
-3. 生成带 YAML frontmatter 的标准 SKILL.md
-4. 你确认输出路径后写入
+**做什么**：查询 MM/CO 业务知识库，辅助理解业务名词和领域规则。
 
 ---
 
@@ -192,16 +181,12 @@ your-project/
 │   ├── design.md
 │   └── task.md
 ├── .cursor/
-│   ├── commands/opsx/               # opsx 命令（9个）
 │   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .claude/
-│   ├── commands/opsx/               # opsx 命令（9个）
 │   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .codebuddy/
-│   ├── commands/opsx/               # opsx 命令（9个）
 │   └── skills/opsx-*/               # SDD skills（扁平一层）
 └── .agents/
-    ├── commands/opsx/               # Codex opsx 命令（9个）
     └── skills/opsx-*/               # Codex 项目级 skills
 ```
 
@@ -209,18 +194,18 @@ your-project/
 
 ## 支持的 AI 编辑器
 
-| 编辑器 | 命令格式 | 技能支持 | 自动创建目录 |
+| 编辑器 | 技能格式 | 技能支持 | 自动创建目录 |
 |-------|---------|---------|------------|
-| Cursor | `.md` | ✅ | 已存在时 |
-| Claude Code | `.md` | ✅ | 已存在时 |
-| CodeBuddy | `.md` | ✅ | 自动创建 |
-| Qoder | `.md` | ✅ | 自动创建 |
-| OpenCode | `.md` | ✅ | 自动创建 |
-| KunlunZhima | `.md` | ✅ | 自动创建 |
-| WorkBuddy | `.md` | ✅ | 自动创建 |
-| Codex | `.md`（`.agents/commands/opsx/`） | ✅（`.agents/skills/`） | 自动创建 |
+| Cursor | `SKILL.md` | ✅ | 已存在时 |
+| Claude Code | `SKILL.md` | ✅ | 已存在时 |
+| CodeBuddy | `SKILL.md` | ✅ | 自动创建 |
+| Qoder | `SKILL.md` | ✅ | 自动创建 |
+| OpenCode | `SKILL.md` | ✅ | 自动创建 |
+| KunlunZhima | `SKILL.md` | ✅ | 自动创建 |
+| WorkBuddy | `SKILL.md` | ✅ | 自动创建 |
+| Codex | `SKILL.md`（`.agents/skills/`） | ✅ | 自动创建 |
 
-> Codex 初始化会创建 `.agents/commands/opsx/` 和 `.agents/skills/opsx-*/`，用于项目级命令与技能。
+> Codex 初始化会创建 `.agents/skills/opsx-*/`，用于项目级技能。
 
 ---
 
@@ -230,7 +215,7 @@ your-project/
 
 1. 在项目中运行 `kld-sdd-init` 一次
 2. 将团队规范文档放入 `team-configs/` 目录
-3. 用 `/opsx:skill` 把规范转为技能，放入 `team-configs/skills/`
+3. 将自定义 skills 放入 `.*/skills/` 目录
 4. 提交到 Git
 
 ### 新成员 onboarding
@@ -241,7 +226,7 @@ npm install
 npx kld-sdd   # 一键配置好所有 AI 工具
 ```
 
-之后直接在编辑器中使用 `/opsx:propose` 开始工作。
+之后直接在编辑器中激活 `opsx-propose` 开始工作。
 
 ---
 
@@ -269,19 +254,19 @@ npx kld-sdd   # 一键配置好所有 AI 工具
 
 **Q：openspec 是什么，必须安装吗？**
 
-A：`openspec` 是管理 SDD 变更目录的 CLI 工具（负责创建变更目录和读取指导规则）。初始化时会自动安装，如果安装失败也可以跳过（`--skip-openspec`），手动创建 `openspec/changes/<name>/` 目录后命令仍然可用。
+A：`openspec` 是管理 SDD 变更目录的 CLI 工具（负责创建变更目录和读取指导规则）。初始化时会自动安装，如果安装失败也可以跳过（`--skip-openspec`），手动创建 `openspec/changes/<name>/` 目录后 skills 仍然可用。
 
 **Q：我用 CodeBuddy 或 Codex，目录不存在怎么办？**
 
-A：不用担心，`kld-sdd-init` 会自动创建 `.codebuddy/commands/opsx/`、`.codebuddy/skills/`、`.agents/commands/opsx/` 和 `.agents/skills/` 目录。
+A：不用担心，`kld-sdd-init` 会自动创建 `.codebuddy/skills/`、`.agents/skills/` 等目录。
 
-**Q：`/opsx:propose` 和直接让 AI 写代码有什么区别？**
+**Q：`opsx-propose` 和直接让 AI 写代码有什么区别？**
 
 A：直接让 AI 写代码，AI 会凭空假设很多细节，导致返工。SDD 流程强制先把"要做什么"写清楚，AI 按契约实现，减少歧义和返工。
 
 **Q：团队规范已经有了，怎么让 AI 每次都遵守？**
 
-A：用 `/opsx:skill <规范文档路径>` 把规范文档转成技能文件，部署到 `.*/skills/` 目录后，AI 编辑器激活该技能时会自动遵守这些规范。
+A：将规范文档转为 skill 文件，部署到 `.*/skills/` 目录后，AI 编辑器激活该 skill 时会自动遵守这些规范。
 
 ---
 

package/lib/init.js

@@ -4,10 +4,9 @@
  * 功能：
  * 1. 检测并自动安装 openspec
  * 2. 执行 openspec init 生成基础结构
- * 3. 覆盖 opsx 命令（9个独立命令）
- * 4. 部署 opsx skills
- * 5. 复制标准文档模版到项目
- * 6. 更新 .gitignore
+ * 3. 部署 opsx skills
+ * 4. 复制标准文档模版到项目
+ * 5. 更新 .gitignore
  */
 
 const fs = require('fs');
@@ -162,7 +161,7 @@ async function selectEditor() {
     console.log('  6. KunlunZhima');
     console.log('  7. WorkBuddy');
     console.log('  8. Codex');
-    console.log('  9. 全部（为所有编辑器生成命令）');
+    console.log('  9. 全部（为所有编辑器生成 skills）');
     
     const answer = await ask('请输入选项 (1-9): ');
     const selected = mapping[answer];
@@ -445,64 +444,6 @@ function cleanupNativeOpenspecCommands(selectedTools = Object.keys(TOOL_CONFIGS)
   return true;
 }
 
-/**
- * 覆盖 opsx 命令（9 个 SDD 工作流命令）
- * 所有编辑器统一使用 templates/opsx-commands/ 下的 SDD 命令模板
- * @param {string[]} selectedTools - 用户选择的编辑器列表
- */
-function overrideOpsxCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
-  console.log('🔧 正在覆盖 opsx 命令...');
-  
-  const pkgPath = getPackagePath();
-  const cwd = process.cwd();
-  
-  // 统一使用 opsx-commands 模板（9 个 SDD 命令，log 为内部自动触发）
-  const sddCommands = ['propose.md', 'spec.md', 'design.md', 'task.md', 'check.md', 'apply.md', 'test.md', 'archive.md', 'explore.md'];
-  const templatePath = path.join(pkgPath, 'templates', 'opsx-commands');
-  
-  if (!fs.existsSync(templatePath)) {
-    console.log(`⚠️  SDD 命令模板目录不存在: ${templatePath}`);
-    return false;
-  }
-  
-  // 为用户选择的每个编辑器部署命令
-  for (const toolKey of selectedTools) {
-    const config = TOOL_CONFIGS[toolKey];
-    if (!config) continue;
-    
-    const configDir = path.join(cwd, config.configDir);
-    const targetOpsxDir = path.join(cwd, config.opsxDir);
-    
-    // 自动创建配置目录
-    if (!fs.existsSync(configDir)) {
-      console.log(`   自动创建 ${config.name} 配置目录...`);
-      fs.mkdirSync(configDir, { recursive: true });
-    }
-    
-    // 确保 opsx 命令目录存在
-    if (!fs.existsSync(targetOpsxDir)) {
-      fs.mkdirSync(targetOpsxDir, { recursive: true });
-    }
-    
-    console.log(`   覆盖 ${config.name} 的 opsx 命令（9 个 SDD 命令）...`);
-    
-    // 复制所有 SDD 命令到 opsx 目录
-    for (const cmd of sddCommands) {
-      const sourceFile = path.join(templatePath, cmd);
-      const targetFile = path.join(targetOpsxDir, cmd);
-      
-      if (fs.existsSync(sourceFile)) {
-        const rendered = renderTemplate(fs.readFileSync(sourceFile, 'utf8'), config, toolKey);
-        fs.writeFileSync(targetFile, rendered, 'utf8');
-        console.log(`     ✓ ${cmd}`);
-      }
-    }
-  }
-  
-  console.log('✅ opsx 命令覆盖完成');
-  return true;
-}
-
 /**
  * 清理旧版嵌套 bundle（skills/kld-sdd/opsx-*）
  * Claude Code 只识别 skills/<skill-name>/SKILL.md 一层，嵌套 bundle 无法被 / 菜单发现
@@ -599,6 +540,36 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
  * 部署 Claude Code Hook Pack（可选增强）
  * Hook 只调用 skywalk-sdd/log.cjs，不写私有日志，不替代 OPSX 模板采集。
  */
+function hookCommandText(hook) {
+  const args = Array.isArray(hook.args) ? hook.args : [];
+  return [hook.command, ...args].filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function isSddClaudeHook(hook) {
+  const text = hookCommandText(hook);
+  return /(?:^|\s|["'])\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i.test(text) ||
+    /(?:^|\s|["'])\$\{CLAUDE_PROJECT_DIR\}[\\/]+\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i.test(text);
+}
+
+function sameHookCommand(left, right) {
+  return hookCommandText(left) === hookCommandText(right) &&
+    String(left.type || '') === String(right.type || '');
+}
+
+function removeManagedSddHooks(entries) {
+  return entries
+    .map(entry => {
+      if (!Array.isArray(entry.hooks)) {
+        return entry;
+      }
+      return {
+        ...entry,
+        hooks: entry.hooks.filter(hook => !isSddClaudeHook(hook)),
+      };
+    })
+    .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+}
+
 function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
   if (!selectedTools.includes('claude')) {
     return true;
@@ -642,11 +613,14 @@ function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
 
   existingSettings.hooks = existingSettings.hooks || {};
   for (const [eventName, entries] of Object.entries(templateSettings.hooks || {})) {
-    existingSettings.hooks[eventName] = existingSettings.hooks[eventName] || [];
+    existingSettings.hooks[eventName] = removeManagedSddHooks(existingSettings.hooks[eventName] || []);
     for (const entry of entries) {
-      const templateCommands = (entry.hooks || []).map(h => h.command).filter(Boolean);
+      const templateHooks = entry.hooks || [];
       const exists = existingSettings.hooks[eventName].some(existingEntry => {
-        return (existingEntry.hooks || []).some(h => templateCommands.includes(h.command));
+        const existingHooks = existingEntry.hooks || [];
+        return templateHooks.every(templateHook => {
+          return existingHooks.some(existingHook => sameHookCommand(existingHook, templateHook));
+        });
       });
       if (!exists) {
         existingSettings.hooks[eventName].push(entry);
@@ -656,7 +630,7 @@ function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
 
   fs.writeFileSync(targetSettingsPath, JSON.stringify(existingSettings, null, 2) + '\n', 'utf8');
   console.log('   ✓ 合并 .claude/settings.json hooks 配置');
-  console.log('✅ Claude Code SDD Hook Pack 已就绪（可选增强，核心采集仍由 OPSX 模板完成）');
+  console.log('✅ Claude Code SDD Hook Pack 已就绪（可选增强，核心采集仍由 OPSX skills 完成）');
   return true;
 }
 
@@ -783,7 +757,7 @@ function initGlobalOverview() {
   
   console.log(`✅ 全局架构约束已初始化: ${targetFile}`);
   console.log('   ℹ️  此文件定义了全局数据字典、接口规范、共享实体等约束');
-  console.log('   ℹ️  执行 /opsx:design 或 /opsx:task 时会自动读取此文件');
+  console.log('   ℹ️  执行 opsx-design 或 opsx-task 时会自动读取此文件');
   
   return true;
 }
@@ -994,7 +968,7 @@ KLD SDD 项目初始化工具
 
 示例:
   kld-sdd-init                 # 完整初始化流程
-  kld-sdd-init --skip-openspec # 跳过 openspec，直接部署命令
+  kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
   kld-sdd-init --tool codex    # 仅部署 Codex 配置
 `);
 }
@@ -1047,19 +1021,16 @@ async function main() {
     // 2. 清理原生 openspec 命令（删除 opsx-*.md，避免命名混淆）
     cleanupNativeOpenspecCommands(selectedTools);
 
-    // 3. 部署 SDD opsx 命令（根据编辑器类型使用不同模板）
-    overrideOpsxCommands(selectedTools);
-
-    // 4. 清理旧版嵌套 skills/kld-sdd/ bundle（Claude Code 无法识别二层目录）
+    // 3. 清理旧版嵌套 skills/kld-sdd/ bundle（Claude Code 无法识别二层目录）
     cleanupLegacyBundledOpsxSkills(selectedTools);
 
-    // 4.1 部署 SDD opsx skills（扁平到 .claude/skills/opsx-*/）
+    // 3.1 部署 SDD opsx skills（扁平到 .claude/skills/opsx-*/）
     deployOpsxSkills(selectedTools);
     
-    // 4.2 清理原生 openspec-* skills（防止残留）
+    // 3.2 清理原生 openspec-* skills（防止残留）
     cleanupNativeOpenspecSkills(selectedTools);
 
-    // 4.2 部署 Claude Code Hook Pack（可选增强）
+    // 3.3 部署 Claude Code Hook Pack（可选增强）
     deployClaudeHookPack(selectedTools);
 
     // 5. 部署 SDD Telemetry 数据目录
@@ -1090,7 +1061,7 @@ async function main() {
   console.log('已生成/覆盖:');
   console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
   console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
-  console.log('  🔧 .*/commands/opsx/             # 9 个 SDD 命令');
+  console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
   if (selectedTools.includes('claude')) {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
@@ -1099,26 +1070,27 @@ async function main() {
   console.log('  🧪 skywalk-sdd/ci/               # CI 兜底采集模板');
   console.log();
   
-  // 统一的命令格式说明
-  console.log('可用命令（/opsx:* 系列，9 个 SDD 命令）:');;
-  console.log('  /opsx:propose  - 创建业务意图文档（Why）');
-  console.log('  /opsx:spec     - 创建技术契约文档（What）');
-  console.log('  /opsx:design   - 创建技术实现方案（How）');
-  console.log('  /opsx:task     - 拆解AI编码任务（Do）');
-  console.log('  /opsx:check    - 质量门禁检查（Verify）');
-  console.log('  /opsx:apply    - 申请变更实施（Apply）');
-  console.log('  /opsx:test     - 执行单元测试（Test）');
-  console.log('  /opsx:archive  - 归档变更（Archive）');
-  console.log('  /opsx:explore  - 浏览变更状态（Explore）');
+  // 统一的 skill 格式说明
+  console.log('可用 skills（opsx-* 系列，10 个 SDD skills）:');
+  console.log('  opsx-propose   - 创建业务意图文档（Why）');
+  console.log('  opsx-spec      - 创建技术契约文档（What）');
+  console.log('  opsx-design    - 创建技术实现方案（How）');
+  console.log('  opsx-task      - 拆解AI编码任务（Do）');
+  console.log('  opsx-check     - 质量门禁检查（Verify）');
+  console.log('  opsx-apply     - 申请变更实施（Apply）');
+  console.log('  opsx-test      - 执行单元测试（Test）');
+  console.log('  opsx-archive   - 归档变更（Archive）');
+  console.log('  opsx-explore   - 浏览变更状态（Explore）');
+  console.log('  opsx-knowledge - 业务知识库检索（辅助）');
     
   console.log();
   console.log('后续步骤:');
-  console.log('  1. 运行 /opsx:propose <变更名称> 开始创建文档');
+  console.log('  1. 激活 opsx-propose skill，输入变更名称开始创建文档');
   console.log('  2. 按顺序执行 propose → spec → design → task');
-  console.log('  3. 运行 /opsx:check 验证文档质量');
-  console.log('  4. 运行 /opsx:apply 申请实施，/opsx:archive 归档完成');
+  console.log('  3. 激活 opsx-check 验证文档质量');
+  console.log('  4. 激活 opsx-apply 申请实施，opsx-archive 归档完成');
   console.log();
-  console.log('📊 SDD Telemetry（嵌入在命令流程中，自动执行，无需配置）：');
+  console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
   console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
   console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=. 查看四维度指标');
   console.log();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kld-sdd",
-  "version": "2.4.13",
-  "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
+  "version": "2.4.15",
+  "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
     "kld-sdd": "bin/kld-sdd-init.js",

package/templates/git-hooks/pre-push-sdd-check.cjs

@@ -39,11 +39,18 @@ function main() {
   });
 
   if (result.error) {
-    console.error(`SDD pre-push: failed to run doctor: ${result.error.message}`);
-    process.exit(1);
+    console.warn(`SDD pre-push: failed to run doctor: ${result.error.message}; push will continue.`);
+    return;
   }
 
-  process.exit(result.status || 0);
+  if (result.status && result.status !== 0) {
+    console.warn(`SDD pre-push: doctor reported issues with exit code ${result.status}; push will continue.`);
+    return;
+  }
+
+  if (result.signal) {
+    console.warn(`SDD pre-push: doctor stopped by signal ${result.signal}; push will continue.`);
+  }
 }
 
 main();

package/templates/hooks/claude/hooks/sdd-apply-gate.cjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * SDD Apply Gate Hook
+ *
+ * 在 apply 阶段执行前进行门禁检查：必须先完成 check 阶段，才能执行 apply。
+ * 拦截 PreToolUse(Write/Edit) 事件，阻断越界写入操作。
+ *
+ * 检查逻辑：
+ * 1. 检测当前是否存在活跃的 apply 阶段（state 文件）
+ * 2. 若存在，回溯 events 目录确认 check 阶段是否已完成
+ * 3. 若 check 未完成，阻断本次写入并提示用户先执行 /opsx:check
+ */
+const fs = require('fs');
+const path = require('path');
+
+// ── 工具函数 ──────────────────────────────────────────────
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function hasTelemetryCli(dir) {
+  return fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs')) ||
+    fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'));
+}
+
+function findProjectRoot(startDir) {
+  if (!startDir) return '';
+
+  let current = path.resolve(startDir);
+  while (true) {
+    if (hasTelemetryCli(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return '';
+    current = parent;
+  }
+}
+
+function getProjectRoot(input) {
+  const toolInput = input.tool_input || input.toolInput || {};
+  const candidates = [
+    toolInput.cwd,
+    input.cwd,
+    input.project_root,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    const root = findProjectRoot(dir);
+    if (root) return root;
+  }
+  return process.cwd();
+}
+
+/**
+ * 获取当前活跃的 apply 阶段事件（从 state 目录）
+ */
+function findActiveApplyStage(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+
+  const files = fs.readdirSync(stateDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8'));
+      const event = data.event || null;
+      if (event && event.command === 'apply') {
+        return event;
+      }
+    } catch {
+      // 跳过无法解析的 state 文件
+    }
+  }
+  return null;
+}
+
+/**
+ * 检查指定 change 是否已有完成的 check 阶段
+ * 在 events 目录中搜索 check 的 stage_end 事件
+ */
+function hasCompletedCheck(projectRoot, changeName) {
+  const safeName = safeChangeName(changeName);
+  const eventsChangeDir = path.join(projectRoot, 'skywalk-sdd', 'data', 'events', safeName);
+  if (!fs.existsSync(eventsChangeDir)) return false;
+
+  const jsonlFiles = fs.readdirSync(eventsChangeDir)
+    .filter(f => f.endsWith('.jsonl'))
+    .sort()
+    .reverse(); // 从最新文件开始搜索
+
+  for (const file of jsonlFiles) {
+    try {
+      const lines = fs.readFileSync(path.join(eventsChangeDir, file), 'utf-8')
+        .split('\n')
+        .filter(Boolean);
+      // 倒序遍历，优先命中最近的事件
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const event = JSON.parse(lines[i]);
+          if (event.type === 'stage_end' && event.command === 'check' && event.result === 'success') {
+            return true;
+          }
+        } catch {
+          // 跳过无法解析的行
+        }
+      }
+    } catch {
+      // 跳过无法读取的文件
+    }
+  }
+  return false;
+}
+
+/**
+ * 将 change 名称转为安全的目录名（与 log.cjs 中 safeChangeName 逻辑一致）
+ */
+function safeChangeName(name) {
+  if (!name) return 'general';
+  return String(name)
+    .replace(/[\\/:*?"<>|]/g, '-')
+    .replace(/[\s.]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase() || 'general';
+}
+
+// ── 主逻辑 ─────────────────────────────────────────────────
+
+const input = parseInput(readStdin());
+
+// 仅拦截 Write 和 Edit 工具
+const toolName = String(input.tool_name || input.toolName || '');
+if (toolName !== 'Write' && toolName !== 'Edit') {
+  process.exit(0);
+}
+
+const projectRoot = getProjectRoot(input);
+
+// 检查是否存在活跃的 apply 阶段
+const activeApply = findActiveApplyStage(projectRoot);
+if (!activeApply) {
+  // 没有活跃的 apply 阶段，无需门禁
+  process.exit(0);
+}
+
+// 检查 check 阶段是否已完成
+if (hasCompletedCheck(projectRoot, activeApply.change)) {
+  // check 已完成，放行
+  process.exit(0);
+}
+
+// check 未完成，阻断写入
+const changeName = activeApply.change || 'unknown';
+console.log(JSON.stringify({
+  decision: 'block',
+  reason: `[SDD Apply Gate] 检测到 apply 阶段正在执行（change: ${changeName}），但 check 阶段尚未完成。\n\n请先执行 /opsx:check 完成质量门禁检查，再执行 /opsx:apply 进行代码实施。\n\n操作顺序：/opsx:check → /opsx:apply`,
+}));