kld-sdd 2.4.7 → 2.4.9

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.js 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.js 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.js 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.js 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.js 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.js 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.js

@@ -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.js

@@ -0,0 +1,41 @@
+#!/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 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 = path.join(projectRoot, 'skywalk-sdd', 'log.js');
+
+  if (!fs.existsSync(logCli)) {
+    console.log('SDD pre-push: skywalk-sdd/log.js 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.error(`SDD pre-push: failed to run doctor: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  process.exit(result.status || 0);
+}
+
+main();

package/templates/hooks/claude/hooks/sdd-post-tool.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function findProjectRoot(input) {
+  const toolInput = input.tool_input || input.toolInput || {};
+  const candidates = [
+    toolInput.cwd,
+    input.cwd,
+    input.project_root,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  return candidates.find(dir => fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'))) || process.cwd();
+}
+
+function latestActiveStage(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+  return fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8'));
+        return data.event || null;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0] || null;
+}
+
+function inferResult(input) {
+  const response = input.tool_response || input.toolResponse || {};
+  if (typeof response.exit_code === 'number') return response.exit_code === 0 ? 'success' : 'failure';
+  if (typeof response.exitCode === 'number') return response.exitCode === 0 ? 'success' : 'failure';
+  if (typeof response.success === 'boolean') return response.success ? 'success' : 'failure';
+  return 'partial';
+}
+
+function inferRecord(command) {
+  if (/\b(npm|pnpm|yarn)\s+(test|run\s+test)\b|\bpytest\b|\bmvn\b.*\btest\b|\bgo\s+test\b|\bcargo\s+test\b/i.test(command)) {
+    return {
+      type: 'test_result',
+      detailsKey: 'test_results',
+      details: { command, passed: 0, failed: 0, skipped: 0, coverage: null, duration_ms: null },
+    };
+  }
+  if (/\b(npm|pnpm|yarn)\s+(run\s+build|build)\b|\btsc\b|\bmvn\b.*\bcompile\b|\bgradle\b.*\bcompile|\bgo\s+build\b|\bcargo\s+check\b/i.test(command)) {
+    return {
+      type: 'build_result',
+      detailsKey: 'build_results',
+      details: { command, success: null, duration_ms: null, error_count: null },
+    };
+  }
+  return null;
+}
+
+function recordTelemetry(projectRoot, activeStage, record, result) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.js');
+  const details = { [record.detailsKey]: { ...record.details } };
+  if (record.type === 'build_result') {
+    details.build_results.success = result === 'success';
+    details.build_results.error_count = result === 'success' ? 0 : null;
+  }
+
+  const args = [
+    logPath,
+    'record',
+    `--type=${record.type}`,
+    `--command=${activeStage.command || activeStage.stage || 'unknown'}`,
+    `--project=${projectRoot}`,
+    `--change=${activeStage.change || 'general'}`,
+    `--agent=${activeStage.agent_type || 'claude-code'}`,
+    '--source=claude-hook',
+    `--result=${result}`,
+    `--summary=Claude hook captured ${record.type}`,
+    `--details-json=${JSON.stringify(details)}`,
+  ];
+  if (activeStage.capability) args.push(`--capability=${activeStage.capability}`);
+  if (activeStage.task_id) args.push(`--task-id=${activeStage.task_id}`);
+  if (activeStage.session_id) args.push(`--session-id=${activeStage.session_id}`);
+  execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+}
+
+const input = parseInput(readStdin());
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || input.command || '');
+const record = inferRecord(command);
+if (!record) process.exit(0);
+
+const projectRoot = findProjectRoot(input);
+const activeStage = latestActiveStage(projectRoot);
+if (!activeStage || !activeStage.change || activeStage.change === 'general') {
+  process.exit(0);
+}
+
+try {
+  recordTelemetry(projectRoot, activeStage, record, inferResult(input));
+} catch {
+  process.exit(0);
+}

package/templates/hooks/claude/hooks/sdd-pre-tool.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+const fs = require('fs');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+const input = parseInput(readStdin());
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || input.command || '');
+
+const dangerousPatterns = [
+  /\brm\s+-rf\b/i,
+  /\brmdir\s+\/s\b/i,
+  /\bdel\s+\/[fsq]/i,
+  /\bgit\s+reset\s+--hard\b/i,
+  /\bgit\s+clean\s+-fdx\b/i,
+  /\bRemove-Item\b.*\b-Recurse\b.*\b-Force\b/i,
+];
+
+if (dangerousPatterns.some(pattern => pattern.test(command))) {
+  console.log(JSON.stringify({
+    decision: 'block',
+    reason: 'Blocked by SDD hook: destructive command requires explicit user approval.',
+  }));
+}

package/templates/hooks/claude/hooks/sdd-prompt.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+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 findProjectRoot(input) {
+  const candidates = [
+    input.cwd,
+    input.project_root,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  return candidates.find(dir => fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'))) || process.cwd();
+}
+
+function readActiveStages(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return [];
+  return fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8')).event;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+const input = parseInput(readStdin());
+const prompt = input.prompt || input.message || input.user_prompt || '';
+if (!/\/opsx:/.test(prompt)) process.exit(0);
+
+const projectRoot = findProjectRoot(input);
+const activeStages = readActiveStages(projectRoot)
+  .map(event => `${event.change || 'general'}:${event.command || event.stage || 'unknown'}`)
+  .join(', ');
+
+const lines = [
+  'SDD Telemetry reminder:',
+  '- Run skywalk-sdd/log.js start before the OPSX stage work begins.',
+  '- Run skywalk-sdd/log.js end before stopping the stage.',
+  '- Hooks are only an enhancement; OPSX command instructions remain authoritative.',
+];
+
+if (activeStages) {
+  lines.push(`- Active stage state: ${activeStages}`);
+}
+
+console.log(lines.join('\n'));

package/templates/hooks/claude/hooks/sdd-stop.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function findProjectRoot(input) {
+  const candidates = [
+    input.cwd,
+    input.project_root,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  return candidates.find(dir => fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'))) || process.cwd();
+}
+
+function readActiveStages(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return [];
+  return fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8')).event;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function writeWarning(projectRoot, event) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.js');
+  const args = [
+    logPath,
+    'record',
+    '--type=telemetry_warning',
+    `--command=${event.command || event.stage || 'unknown'}`,
+    `--project=${projectRoot}`,
+    `--change=${event.change || 'general'}`,
+    `--agent=${event.agent_type || 'claude-code'}`,
+    '--source=claude-hook',
+    '--result=partial',
+    '--summary=Claude hook detected an open SDD stage at stop',
+    `--details-json=${JSON.stringify({ warning: 'open_stage_at_stop', event_id: event.event_id })}`,
+  ];
+  if (event.capability) args.push(`--capability=${event.capability}`);
+  if (event.session_id) args.push(`--session-id=${event.session_id}`);
+  execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+}
+
+const input = parseInput(readStdin());
+const projectRoot = findProjectRoot(input);
+const activeStages = readActiveStages(projectRoot);
+if (activeStages.length === 0) process.exit(0);
+
+for (const event of activeStages) {
+  try {
+    writeWarning(projectRoot, event);
+  } catch {}
+}
+
+console.log([
+  'SDD Telemetry warning: open stage(s) detected.',
+  ...activeStages.map(event => `- ${event.change || 'general'}:${event.command || event.stage || 'unknown'} event_id=${event.event_id}`),
+  'Run skywalk-sdd/log.js end before closing the OPSX stage, or explicitly mark it partial/failure.',
+].join('\n'));

package/templates/hooks/claude/settings.json

@@ -0,0 +1,46 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/sdd-prompt.js"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/sdd-pre-tool.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/sdd-post-tool.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/sdd-stop.js"
+          }
+        ]
+      }
+    ]
+  }
+}