kld-sdd 2.5.0 → 2.5.1

package/templates/hooks/codebuddy/settings.json

@@ -0,0 +1,72 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-prompt.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-skill-apply-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-pre-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-gate.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-post-tool.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-test-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-stop.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -29,7 +29,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
@@ -115,7 +115,7 @@ openspec list --json
 ### 1.2 【Check 门禁检查】验证质量门禁状态
 
 > **⛔ 强制门禁**：apply 阶段开始前，必须确认 check 阶段已完成。这是 SDD 流程的关键质量保障。
-> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 形成双重保障。
+> 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 
 ### 1.5 【本地并行】Worktree 与工作区（建议性策略）
 
@@ -230,7 +230,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 ### 6.0 【条件必做】单元测试真实执行（`test-strategy` 非 `none`）
 
-当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。Claude Code 的 `sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则阻断。
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时，在结束 apply 或执行 §6.1 收尾之前，必须真实运行单元测试并留 telemetry 证据。**详细执行要求与证据形式见 `./reference.md`「§6.0」+ `./checklist.md`「§6.0 单元测试真实执行自检」**。${HOOK_GATE_DESCRIPTION}
 
 ### 6.1 【条件必做】Worktree 收尾（仅当 §1.5 已创建 worktree）
 
@@ -247,11 +247,11 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
 
-- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 双重保障。
+- **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 - **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，禁止加载同级其他 Capability 的文档。
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
 - **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
-- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据。
+- **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}
 - **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行。
 - **⛔ Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告。

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -29,7 +29,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）

package/templates/skills/kld-sdd/opsx-design/SKILL.md

@@ -39,7 +39,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 

package/templates/skills/kld-sdd/opsx-explore/SKILL.md

@@ -20,7 +20,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -31,7 +31,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 

package/templates/skills/kld-sdd/opsx-rules/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: opsx-rules
+description: "规则生成技能 - 扫描项目生成 5 主题 Agent 规则，或对比现有规则输出更新建议"
+argument-hint: "[generate|review] [--agent <id>]"
+license: MIT
+compatibility: 无外部依赖；opencode 接线需项目存在或可创建 opencode.json。
+metadata:
+  author: sdd-team
+  version: "1.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - ${SHELL_GUIDANCE}
+> - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | 各 Agent 的规则文件在哪里、格式如何、是否与项目事实一致 |
+| 关键输出 | generate：按 Agent 落位的 5 主题规则文件；review：更新建议表 |
+| 操作类型 | generate 写入新规则；review 默认只读，确认后才写入 |
+
+---
+
+## 启动流程
+
+### 1. 检测已部署 Agent 与运行模式
+
+扫描以下目录，记录存在的 Agent（`--agent <id>` 可过滤为单个）：
+
+| Agent id | 检测路径 |
+|----------|----------|
+| cursor | `.cursor/` |
+| claude | `.claude/` |
+| codebuddy | `.codebuddy/` |
+| qoder | `.qoder/` |
+| opencode | `.opencode/` |
+| kunlunzhima | `.kunlunzhima/` |
+| workbuddy | `.workbuddy/` |
+| codex | `.agents/` |
+
+**模式判定**（参数优先，否则自动）：
+- 显式 `generate` → 生成模式
+- 显式 `review` → 审查模式
+- 未指定：任一已选 Agent 的规则目录已有文件 → **review**；否则 → **generate**
+
+规则目录与格式详见 `reference.md` 落位矩阵。**KunlunZhima 注意**：目录是 `.kunlunzhima/.rules/`（点前缀），不是 `rules/`。
+
+### 2. 轻量项目扫描（generate 与 review 共用，不落盘）
+
+借鉴 codebase-map 三视角，只读扫描：
+
+| 视角 | 探测目标 |
+|------|----------|
+| STACK | `package.json` / `pom.xml` / `pyproject.toml` / `go.mod` / `Cargo.toml`；构建命令 |
+| STRUCTURE | 顶层目录职责、入口文件（`bin/`、`src/`、`lib/`、`app/`） |
+| CONVENTIONS | ESLint/Prettier/Ruff 配置；`test/` 目录与框架；`git log --oneline -20` 提交风格 |
+
+扫描结果作为 5 主题规则的正文依据，禁止编造与仓库不符的内容。
+
+### 3a. generate 模式
+
+对 Step 1 检测到的每个 Agent：
+
+1. 读取 `reference.md` 中该 Agent 的 `rulesDir` / `rulesFormat` / `rulesWiring`
+2. 按 5 主题（architecture / coding-style / testing / database-safety / git-commit）生成内容
+3. 按格式模板写入规则文件（见 `reference.md`）
+4. **已有同名文件 → 跳过**，提示用户改用 review 模式
+5. **接线**（仅 wiring ≠ none 的 Agent）：
+   - `opencode-config`：保守合并 `opencode.json` 的 `instructions` 数组（只增不删）；优先指向已有 `.claude/rules/*.md`
+   - `agents-md`：在 `AGENTS.md` 用 `<!-- kld-sdd-rules:start/end -->` marker 追加/替换规则章节
+   - `context-file`：在 WorkBuddy 上下文文件加一行规则目录索引（见 reference.md）
+
+### 3b. review 模式
+
+1. 读取各 Agent 现有规则文件
+2. 与 Step 2 扫描事实对比，输出建议表：
+
+| 文件 | 主题 | 建议类型 | 依据 |
+|------|------|----------|------|
+| （路径） | architecture 等 | 新增 / 修订 / 过期 | 具体扫描证据 |
+
+3. 使用 **AskUserQuestion** 让用户确认要应用的项
+4. **未经确认不写文件**
+
+### 4. 输出报告
+
+```markdown
+## opsx-rules 执行报告
+
+| Agent | 模式 | 写入/建议文件数 | 接线 |
+|-------|------|----------------|------|
+| ... | generate/review | N | 无/opencode.json/AGENTS.md |
+
+### 详情
+- （列出路径与操作摘要）
+
+### 后续
+- 规则内容可手工微调；再次变更后运行 `/opsx-rules review`
+- OpenCode 用户：确认 `opencode.json` instructions 已包含规则路径
+```
+
+---
+
+## Guardrails
+
+- **review 模式未经用户确认不写文件**
+- **generate 模式不覆盖已有同名规则文件**（存在即跳过 + 提示 review）
+- **opencode.json 合并只增不删**；写前提示用户备份已有配置
+- **AGENTS.md 追加用 managed marker**，存在 marker 则整块替换（幂等）
+- **规则内容来自扫描证据**，禁止编造项目不存在的框架或命令
+
+---
+
+## 渐进披露
+
+- **Read `reference.md`** — 落位矩阵、格式模板、5 主题骨架、接线示例
+- **Read `checklist.md`** — generate/review 前后检查项

package/templates/skills/kld-sdd/opsx-rules/checklist.md

@@ -0,0 +1,27 @@
+# opsx-rules 检查清单
+
+## generate 前
+
+- [ ] 工作目录为项目根
+- [ ] 已检测存在的 Agent 目录
+- [ ] 已完成 Step 2 轻量扫描（STACK / STRUCTURE / CONVENTIONS）
+- [ ] 目标 Agent 规则目录无同名文件（有则改 review）
+
+## generate 写后
+
+- [ ] 5 主题文件均已写入（或按 Agent 格式合并）
+- [ ] frontmatter 符合 reference.md 模板
+- [ ] KunlunZhima 路径为 `.kunlunzhima/.rules/` 而非 `rules/`
+- [ ] opencode.json / AGENTS.md 接线已完成（若 wiring 非 none）
+- [ ] 未覆盖用户已有非受管文件
+
+## review 前
+
+- [ ] 已读取现有规则文件
+- [ ] 已完成 Step 2 扫描
+- [ ] 建议表已输出（文件 / 主题 / 类型 / 依据）
+
+## review 写后
+
+- [ ] 用户已通过 AskUserQuestion 确认
+- [ ] 仅写入确认项

package/templates/skills/kld-sdd/opsx-rules/reference.md

@@ -0,0 +1,124 @@
+# opsx-rules 参考 — 落位矩阵与格式模板
+
+> **权威源说明**：本文件是 skill **运行时**的落位矩阵真相源（部署到目标项目后无法 `require` kld-sdd 的 `lib/`）。`lib/tool-profiles.js` 中的 `rulesDir` / `rulesFormat` / `rulesWiring` 为 **init 契约与测试断言**；变更时须与本表同步，以本表为准写入规则文件。
+
+## 落位矩阵
+
+| Agent | rulesDir | 格式 | frontmatter | 原生加载 | 接线 |
+|-------|----------|------|-------------|----------|------|
+| cursor | `.cursor/rules/` | `.mdc` | description / globs / alwaysApply | ✅ | 无 |
+| claude | `.claude/rules/` | `.md` | 可选 paths（glob 列表） | ✅ | 无 |
+| codebuddy | `.codebuddy/rules/` | `.md` | 无 | ✅ | 无 |
+| qoder | `.qoder/rules/` | `.md` | 可选 trigger | ✅ | 无 |
+| kunlunzhima | **`.kunlunzhima/.rules/`** | `.mdc` | description / alwaysApply / enabled / updatedAt / provider | ✅ | 无 |
+| opencode | 无独立目录 | `.md` | 无 | ❌ | `opencode.json` instructions |
+| codex | 无独立目录 | — | — | ✅（读 AGENTS.md） | AGENTS.md managed marker |
+| workbuddy | `.workbuddy/rules/` | `.md` | 无 | ⚠️ 待验证 | 上下文文件索引行兜底 |
+
+> **KunlunZhima 证据**：样例目录 `.kunlunzhima/.rules/*.mdc`，frontmatter 含 IDE 管理字段 `enabled`、`updatedAt`、`provider`（无 `globs`）。
+
+## 格式模板
+
+### mdc（Cursor）
+
+```markdown
+---
+description: <一句话描述>
+globs:
+alwaysApply: true
+---
+
+<正文>
+```
+
+### mdc-kunlun（KunlunZhima）
+
+```markdown
+---
+description: <一句话描述>
+alwaysApply: true
+enabled: true
+updatedAt: <ISO8601 生成时间>
+provider:
+---
+
+<正文>
+```
+
+### md + paths（Claude Code，可选按路径触发）
+
+```markdown
+---
+paths:
+  - "src/**/*.ts"
+---
+
+<正文>
+```
+
+无 paths 时 Claude 会话启动即加载。
+
+### md + trigger（Qoder，可选）
+
+```markdown
+---
+trigger: always_on
+---
+
+<正文>
+```
+
+### 纯 md（CodeBuddy / WorkBuddy）
+
+```markdown
+<正文>
+```
+
+## 5 主题内容骨架
+
+| 主题 | 文件名 | 扫描依据 | 生成要点 |
+|------|--------|----------|----------|
+| 架构规范 | `architecture` | 目录分层、模块边界、入口 | 分层约定、禁止循环依赖、新代码落位 |
+| 编码规范 | `coding-style` | 语言、lint、缩进 | 命名、缩进、注释语言、CommonJS/ESM |
+| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望 |
+| 数据安全 | `database-safety` | ORM/迁移目录 | 无 DB 时降级为「禁止危险文件操作/敏感数据提交」 |
+| Git 提交 | `git-commit` | git log 风格、CI | 提交前确认、message 风格、禁止 force push |
+
+## OpenCode 接线
+
+优先复用已有 `.claude/rules/`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".claude/rules/*.md"]
+}
+```
+
+无 Claude 规则时，写入 `.opencode/rules/*.md` 并 instructions 指向该路径。合并：已有 `instructions` 数组去重追加，其他键不动。
+
+## Codex / AGENTS.md 接线
+
+```markdown
+<!-- kld-sdd-rules:start -->
+## 项目规则
+
+### 架构
+...
+
+### 编码
+...
+<!-- kld-sdd-rules:end -->
+```
+
+存在 marker 则整块替换，幂等。
+
+## WorkBuddy 兜底
+
+写入 `.workbuddy/rules/*.md`，并在项目上下文文件（若存在）追加：
+
+```markdown
+项目规则见 `.workbuddy/rules/` 目录。
+```
+
+验证：运行 CodeBuddy `/memory` 或查官方 docs。

package/templates/skills/kld-sdd/opsx-spec/SKILL.md

@@ -31,7 +31,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 

package/templates/skills/kld-sdd/opsx-task/SKILL.md

@@ -40,7 +40,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 

package/templates/skills/kld-sdd/opsx-test/SKILL.md

@@ -26,7 +26,7 @@ allowed-tools:
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）