@hunterzheng/kld-sdd 2.4.19

package/templates/ci/github-actions-sdd.yml

@@ -0,0 +1,67 @@
+name: SDD Quality Gate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  sdd-quality-gate:
+    runs-on: ubuntu-latest
+    env:
+      SDD_PROJECT: ${{ github.workspace }}
+      SDD_CHANGE: ${{ github.head_ref || github.ref_name }}
+      SDD_AGENT: github-actions
+      SDD_SESSION: github-${{ github.run_id }}
+      SDD_BUILD_COMMAND: npm run build --if-present
+      SDD_TEST_COMMAND: npm test --if-present
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: SDD doctor
+        run: node skywalk-sdd/log.cjs doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
+
+      - name: Build and record SDD result
+        shell: bash
+        run: |
+          set +e
+          start_ms=$(date +%s%3N)
+          bash -lc "$SDD_BUILD_COMMAND"
+          status=$?
+          end_ms=$(date +%s%3N)
+          duration=$((end_ms - start_ms))
+          result="success"
+          success="true"
+          if [ "$status" -ne 0 ]; then
+            result="failure"
+            success="false"
+          fi
+          node skywalk-sdd/log.cjs record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
+          exit "$status"
+
+      - name: Test and record SDD result
+        shell: bash
+        run: |
+          set +e
+          start_ms=$(date +%s%3N)
+          bash -lc "$SDD_TEST_COMMAND"
+          status=$?
+          end_ms=$(date +%s%3N)
+          duration=$((end_ms - start_ms))
+          result="success"
+          failed=0
+          if [ "$status" -ne 0 ]; then
+            result="failure"
+            failed=1
+          fi
+          node skywalk-sdd/log.cjs record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
+          exit "$status"

package/templates/ci/gitlab-ci-sdd.yml

@@ -0,0 +1,44 @@
+sdd_quality_gate:
+  image: node:20
+  stage: test
+  variables:
+    SDD_PROJECT: "$CI_PROJECT_DIR"
+    SDD_CHANGE: "$CI_COMMIT_REF_NAME"
+    SDD_AGENT: "gitlab-ci"
+    SDD_SESSION: "gitlab-$CI_PIPELINE_ID"
+    SDD_BUILD_COMMAND: "npm run build --if-present"
+    SDD_TEST_COMMAND: "npm test --if-present"
+  before_script:
+    - npm install
+  script:
+    - node skywalk-sdd/log.cjs doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
+    - |
+      set +e
+      start_ms=$(date +%s%3N)
+      sh -lc "$SDD_BUILD_COMMAND"
+      status=$?
+      end_ms=$(date +%s%3N)
+      duration=$((end_ms - start_ms))
+      result="success"
+      success="true"
+      if [ "$status" -ne 0 ]; then
+        result="failure"
+        success="false"
+      fi
+      node skywalk-sdd/log.cjs record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
+      if [ "$status" -ne 0 ]; then exit "$status"; fi
+    - |
+      set +e
+      start_ms=$(date +%s%3N)
+      sh -lc "$SDD_TEST_COMMAND"
+      status=$?
+      end_ms=$(date +%s%3N)
+      duration=$((end_ms - start_ms))
+      result="success"
+      failed=0
+      if [ "$status" -ne 0 ]; then
+        result="failure"
+        failed=1
+      fi
+      node skywalk-sdd/log.cjs record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
+      if [ "$status" -ne 0 ]; then exit "$status"; fi

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(arg => arg.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+function getStagedFiles(projectRoot) {
+  try {
+    return execFileSync('git', ['diff', '--cached', '--name-only'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+function getChangeNameFromPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const match = normalized.match(/^openspec\/changes\/([^/]+)\//);
+  return match ? match[1] : '';
+}
+
+function hasArchiveIntent(files) {
+  return files.some(file => {
+    const normalized = normalizePath(file);
+    return /^openspec\/changes\/[^/]+\/archive/i.test(normalized) ||
+      /^openspec\/archive\//i.test(normalized);
+  });
+}
+
+function discoverChanges(projectRoot, explicitChange, archiveMode) {
+  if (explicitChange) {
+    return [explicitChange];
+  }
+
+  const stagedFiles = getStagedFiles(projectRoot);
+  if (!archiveMode && !hasArchiveIntent(stagedFiles)) {
+    return [];
+  }
+
+  const changes = new Set();
+  for (const file of stagedFiles) {
+    const changeName = getChangeNameFromPath(file);
+    if (changeName) {
+      changes.add(changeName);
+    }
+  }
+
+  if (changes.size > 0) {
+    return Array.from(changes);
+  }
+
+  const changesDir = path.join(projectRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(changesDir)
+    .filter(name => fs.statSync(path.join(changesDir, name)).isDirectory());
+}
+
+function walkFiles(dirPath, predicate, files = []) {
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(fullPath, predicate, files);
+    } else if (!predicate || predicate(fullPath)) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function findIncompleteTasks(projectRoot, changeName) {
+  const changePath = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const taskFiles = walkFiles(changePath, filePath => {
+    const fileName = path.basename(filePath).toLowerCase();
+    return fileName === 'tasks.md' || fileName === 'task.md';
+  });
+
+  const incomplete = [];
+  for (const tasksPath of taskFiles) {
+    const relPath = path.relative(projectRoot, tasksPath).replace(/\\/g, '/');
+    const items = fs.readFileSync(tasksPath, 'utf8')
+      .split(/\r?\n/)
+      .map((line, index) => ({ file: relPath, line, lineNumber: index + 1 }))
+      .filter(item => /\[\s\]/.test(item.line));
+    incomplete.push(...items);
+  }
+
+  return incomplete;
+}
+
+function main() {
+  const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
+  const explicitChange = readArg('change') || process.env.SDD_CHANGE || process.env.OPENSPEC_CHANGE || '';
+  const archiveMode = hasFlag('archive') || process.env.SDD_ARCHIVE_CHECK === '1';
+  const changes = discoverChanges(projectRoot, explicitChange, archiveMode);
+
+  if (changes.length === 0) {
+    console.log('SDD pre-commit: no archive intent detected; tasks gate skipped.');
+    return;
+  }
+
+  const failures = [];
+  for (const changeName of changes) {
+    const incomplete = findIncompleteTasks(projectRoot, changeName);
+    if (incomplete.length > 0) {
+      failures.push({ changeName, incomplete });
+    }
+  }
+
+  if (failures.length === 0) {
+    console.log(`SDD pre-commit: tasks gate passed for ${changes.length} change(s).`);
+    return;
+  }
+
+  console.warn('SDD pre-commit: tasks.md still has incomplete items. Archive is allowed, but these items must be shown as unfinished/unchecked in telemetry and reports.');
+  for (const failure of failures) {
+    console.warn(`- ${failure.changeName}`);
+    for (const item of failure.incomplete.slice(0, 10)) {
+      console.warn(`  ${item.file}:${item.lineNumber}: ${item.line.trim()}`);
+    }
+    if (failure.incomplete.length > 10) {
+      console.warn(`  ... ${failure.incomplete.length - 10} more`);
+    }
+  }
+  if (hasFlag('strict-tasks') || process.env.SDD_STRICT_TASKS === '1') {
+    console.error('SDD pre-commit: strict task mode enabled; blocking archive commit.');
+    process.exit(1);
+  }
+}
+
+main();

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(arg => arg.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+function resolveLogCli(projectRoot) {
+  const logCjs = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  if (fs.existsSync(logCjs)) {
+    return logCjs;
+  }
+  return null;
+}
+
+function main() {
+  const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
+  const changeName = readArg('change') || process.env.SDD_CHANGE || process.env.OPENSPEC_CHANGE || '';
+  const logCli = resolveLogCli(projectRoot);
+
+  if (!logCli) {
+    console.log('SDD pre-push: skywalk-sdd/log.cjs not found; doctor gate skipped.');
+    return;
+  }
+
+  const args = [logCli, 'doctor', `--project=${projectRoot}`];
+  if (changeName) {
+    args.push(`--change=${changeName}`);
+  }
+
+  const result = spawnSync(process.execPath, args, {
+    cwd: projectRoot,
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    console.warn(`SDD pre-push: failed to run doctor: ${result.error.message}; push will continue.`);
+    return;
+  }
+
+  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,173 @@
+#!/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', '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' || event.result === 'partial')) {
+            return true;
+          }
+        } catch {
+          // 跳过无法解析的行
+        }
+      }
+    } catch {
+      // 跳过无法读取的文件
+    }
+  }
+  return false;
+}
+
+/**
+ * 将 change 名称转为安全的目录名（与 L1 门禁 && log.cjs 中 safeChangeName 逻辑一致）
+ *
+ * 规则：转小写 → 空格/下划线转连字符 → 剔除非法字符 → 压缩连字符 → 去头尾连字符
+ */
+function safeChangeName(name) {
+  if (!name) return '';
+  return String(name)
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9一-鿿\-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+// ── 主逻辑 ─────────────────────────────────────────────────
+
+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`,
+}));
+process.exit(2);