@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/hooks/hooks-codex.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-context",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-pre-tool-use",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__plugin_superharness_superharness-workflow-state__transition_state",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-post-transition",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-stop",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/superharness/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-context",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-pre-tool-use",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__plugin_superharness_superharness-workflow-state__transition_state",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-post-transition",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" workflow-stop",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/superharness/hooks/lib/free-mode-check.mjs

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Sync-ish check of free_mode flag without depending on state.js statically.
+ * Opens DB, reads free_mode, returns false on any error (fail-open).
+ */
+export async function isFreeMode({ pluginRoot, workspaceRoot }) {
+  const dbPath = process.env.SUPERHARNESS_WORKFLOW_STATE_DB
+    || path.join(path.resolve(workspaceRoot), '.superharness', 'workflow-state.db');
+  if (!fs.existsSync(dbPath)) return false;
+
+  try {
+    const { openWorkflowStateStore, readFreeMode } = await import(
+      pathToFileURL(path.join(pluginRoot, 'workflow-state-server', 'state.js')).href
+    );
+    const store = openWorkflowStateStore({ dbPath });
+    try {
+      return readFreeMode(store, workspaceRoot);
+    } finally {
+      store.close?.();
+    }
+  } catch {
+    return false;
+  }
+}

package/plugins/superharness/hooks/run-hook.cmd

@@ -0,0 +1,58 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+REM
+REM Usage: run-hook.cmd <script-name> [args...]
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH, but skip Windows' WSL shim because it cannot run
+REM Windows-style hook paths like C:\...\hooks\<script-name>.
+for /f "delims=" %%B in ('where bash 2^>nul') do (
+    echo %%B | findstr /I "\\Windows\\System32\\bash.exe \\WindowsApps\\bash.exe" >nul
+    if errorlevel 1 (
+        "%%B" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+        exit /b %ERRORLEVEL%
+    )
+)
+
+REM Try common MSYS2 locations.
+if exist "C:\msys64\usr\bin\bash.exe" (
+    "C:\msys64\usr\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\cygwin64\bin\bash.exe" (
+    "C:\cygwin64\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently rather than error
+REM (plugin still works, just without optional context injection)
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/plugins/superharness/hooks/workflow-context

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "${SCRIPT_DIR}/workflow-context.mjs"

package/plugins/superharness/hooks/workflow-context.mjs

@@ -0,0 +1,184 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const STATE_DIR_LABEL = '.' + 'superharness/';
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+function resolvePluginRoot() {
+  return path.resolve(
+    process.env.CLAUDE_PLUGIN_ROOT
+      || process.env.CODEX_PLUGIN_ROOT
+      || path.join(__dirname, '..'),
+  );
+}
+
+function workflowStateRoot(pluginRoot) {
+  return path.join(pluginRoot, 'workflow-state-server');
+}
+
+function hasWorkflowStateDeps(workflowStateDir) {
+  const nativeSqlite = path.join(
+    workflowStateDir,
+    'node_modules',
+    'better-sqlite3',
+    'build',
+    'Release',
+    'better_sqlite3.node',
+  );
+  return fs.existsSync(nativeSqlite)
+    && fs.existsSync(path.join(workflowStateDir, 'node_modules', 'yaml'))
+    && fs.existsSync(path.join(workflowStateDir, 'node_modules', '@modelcontextprotocol', 'sdk'));
+}
+
+function ensureWorkflowStateDeps(workflowStateDir) {
+  if (hasWorkflowStateDeps(workflowStateDir)) return { ok: true };
+
+  // Node 22+ on Windows refuses to spawn .cmd / .bat without shell: true
+  // (CVE-2024-27980 mitigation). To avoid DEP0190 warnings from
+  // shell: true + args[], pass the full command as a single string and
+  // omit the args array on Windows. Arguments here are hard-coded constants,
+  // so there is no injection surface.
+  const isWin = process.platform === 'win32';
+  const result = isWin
+    ? spawnSync('npm.cmd install --omit=dev --no-audit --no-fund', {
+      cwd: workflowStateDir,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      shell: true,
+    })
+    : spawnSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
+      cwd: workflowStateDir,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+
+  if (result.status === 0 && hasWorkflowStateDeps(workflowStateDir)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    error: result.error?.message
+      || result.stderr
+      || result.stdout
+      || `npm install exited with ${result.status}`,
+  };
+}
+
+function importFrom(workflowStateDir, file) {
+  return import(pathToFileURL(path.join(workflowStateDir, file)).href);
+}
+
+function loadInstalledSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  if (!fs.existsSync(skillsDir)) return new Set();
+  return new Set(
+    fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')))
+      .map((entry) => entry.name),
+  );
+}
+
+function hookOutput(additionalContext) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext,
+    },
+  };
+}
+
+const fallbackStopWorkContext = (reason) => [
+  '<SUPERHARNESS_WORKFLOW_STATE>',
+  'Runtime status: unavailable',
+  `Reason: ${reason || 'workflow state context could not be loaded'}`,
+  '',
+  'Rules:',
+  '- Stop business work.',
+  '- Report the workflow error to the user.',
+  '- Do not invent workflow state.',
+  `- Do not edit ${STATE_DIR_LABEL} directly.`,
+  '</SUPERHARNESS_WORKFLOW_STATE>',
+].join('\n');
+
+export async function main() {
+  let store;
+  const pluginRoot = resolvePluginRoot();
+  const workflowStateDir = workflowStateRoot(pluginRoot);
+
+  const deps = ensureWorkflowStateDeps(workflowStateDir);
+  if (!deps.ok) {
+    process.stdout.write(`${JSON.stringify(hookOutput(fallbackStopWorkContext(`workflow-state-server dependencies are unavailable: ${deps.error}`)))}\n`);
+    return;
+  }
+
+  try {
+    const input = await readStdinJson();
+    const workspaceRoot = path.resolve(input.cwd || process.cwd());
+
+    // Free-mode check: skip injection entirely
+    const { isFreeMode } = await import(pathToFileURL(path.join(pluginRoot, 'hooks', 'lib', 'free-mode-check.mjs')).href);
+    if (await isFreeMode({ pluginRoot, workspaceRoot })) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    const [
+      { loadWorkflowConfig, buildWorkflowGraph },
+      { openWorkflowStateStore, getWorkflowState, resolveWorkflowDbPath, createTurn },
+      { renderWorkflowContext },
+    ] = await Promise.all([
+      importFrom(workflowStateDir, 'validate-workflow.js'),
+      importFrom(workflowStateDir, 'state.js'),
+      importFrom(workflowStateDir, 'render-context.js'),
+    ]);
+    const config = loadWorkflowConfig({ pluginRoot, workspaceRoot });
+    const workflowGraph = buildWorkflowGraph(config, {
+      installedSkills: loadInstalledSkills(pluginRoot),
+    });
+    store = openWorkflowStateStore({
+      mode: process.env.SUPERHARNESS_WORKFLOW_STATE_MODE,
+      dbPath: process.env.SUPERHARNESS_WORKFLOW_STATE_DB
+        || resolveWorkflowDbPath({ workspaceRoot }),
+    });
+    const turnId = crypto.randomUUID();
+    createTurn(store, { workspaceRoot, turnId });
+    const stateInfo = getWorkflowState(store, {
+      workspaceRoot,
+      workflowGraph,
+    });
+    const context = renderWorkflowContext({
+      stateInfo,
+      workflowGraph,
+      skillsDir: path.join(pluginRoot, 'skills'),
+    });
+    process.stdout.write(`${JSON.stringify(hookOutput(context))}\n`);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    try {
+      const { renderStopWorkContext } = await importFrom(workflowStateDir, 'render-context.js');
+      process.stdout.write(`${JSON.stringify(hookOutput(renderStopWorkContext({ reason })))}\n`);
+    } catch {
+      process.stdout.write(`${JSON.stringify(hookOutput(fallbackStopWorkContext(reason)))}\n`);
+    }
+  } finally {
+    store?.close();
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/plugins/superharness/hooks/workflow-post-transition

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "${SCRIPT_DIR}/workflow-post-transition.mjs"

package/plugins/superharness/hooks/workflow-post-transition.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  return raw ? JSON.parse(raw) : {};
+}
+
+function resolvePluginRoot() {
+  return path.resolve(
+    process.env.CLAUDE_PLUGIN_ROOT
+      || process.env.CODEX_PLUGIN_ROOT
+      || process.env.PLUGIN_ROOT
+      || path.join(__dirname, '..'),
+  );
+}
+
+function hookOutput(additionalContext) {
+  return additionalContext
+    ? { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext } }
+    : {};
+}
+
+export async function main() {
+  try {
+    const input = await readStdinJson();
+    const toState = input?.tool_input?.to_state;
+    if (!toState) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+    const pluginRoot = resolvePluginRoot();
+    const workflowStateDir = path.join(pluginRoot, 'workflow-state-server');
+
+    // Free-mode check: skip skill injection entirely
+    const workspaceRoot = path.resolve(input.cwd || process.cwd());
+    const { isFreeMode } = await import(pathToFileURL(path.join(pluginRoot, 'hooks', 'lib', 'free-mode-check.mjs')).href);
+    if (await isFreeMode({ pluginRoot, workspaceRoot })) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+    const [{ renderActiveSkill }, { loadWorkflowConfig, buildWorkflowGraph }] = await Promise.all([
+      import(pathToFileURL(path.join(workflowStateDir, 'render-context.js')).href),
+      import(pathToFileURL(path.join(workflowStateDir, 'validate-workflow.js')).href),
+    ]);
+
+    const skillsDir = path.join(pluginRoot, 'skills');
+
+    // State 名 (e.g. serial_execution) → skill 目录名 (serial-execution) 由 YAML
+    // 的 state.skill 字段映射。从 graph 拿，不要直接用 stateName 当 skill name。
+    let skillName = toState;
+    try {
+      const config = loadWorkflowConfig({ pluginRoot });
+      const installedSkills = new Set();
+      if (fs.existsSync(skillsDir)) {
+        for (const e of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+          if (e.isDirectory() && fs.existsSync(path.join(skillsDir, e.name, 'SKILL.md'))) {
+            installedSkills.add(e.name);
+          }
+        }
+      }
+      const graph = buildWorkflowGraph(config, { installedSkills });
+      skillName = graph.states.get(toState)?.skill ?? toState;
+    } catch {
+      // graph 加载失败 → 回退用 stateName 当 skill name；renderActiveSkill 再 fail-open
+    }
+
+    try {
+      const skillContext = renderActiveSkill({ stateName: toState, skillsDir, skillName });
+      process.stdout.write(JSON.stringify(hookOutput(skillContext)) + '\n');
+    } catch {
+      // unknown state 或 SKILL 文件不存在 → fail-open
+      process.stdout.write(JSON.stringify({}) + '\n');
+    }
+  } catch {
+    // fail-open: hook 错误绝不阻塞 agent
+    process.stdout.write(JSON.stringify({}) + '\n');
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/plugins/superharness/hooks/workflow-pre-tool-use

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "${SCRIPT_DIR}/workflow-pre-tool-use.mjs"

package/plugins/superharness/hooks/workflow-pre-tool-use.mjs

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+function normalizePathText(value) {
+  return value.replaceAll('\\', '/').toLowerCase();
+}
+
+function pathTouchesWorkflowState(value) {
+  const normalized = normalizePathText(value);
+  return normalized.includes('/.superharness/')
+    || normalized.startsWith('.superharness/')
+    || normalized.includes('.superharness/');
+}
+
+function collectStrings(value, output = []) {
+  if (typeof value === 'string') {
+    output.push(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectStrings(item, output);
+  } else if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) collectStrings(item, output);
+  }
+  return output;
+}
+
+function isWriteCommand(command) {
+  return />>?|(^|\s)(rm|del|move|mv|copy|cp|set-content|add-content|out-file|sqlite3)(\s|$)/i
+    .test(command);
+}
+
+function firstString(...candidates) {
+  for (const value of candidates) {
+    if (typeof value === 'string') return value;
+  }
+  return '';
+}
+
+function shouldDeny(input) {
+  const toolName = String(input.tool_name || input.toolName || '');
+  const toolInput = input.tool_input || input.toolInput || {};
+  const lowered = toolName.toLowerCase();
+
+  if (lowered === 'bash' || lowered === 'shell') {
+    const command = firstString(toolInput.command, ...collectStrings(toolInput));
+    return pathTouchesWorkflowState(command) && isWriteCommand(command);
+  }
+
+  if (lowered === 'write' || lowered === 'edit' || lowered === 'multiedit') {
+    const filePath = firstString(toolInput.file_path, toolInput.filePath);
+    return pathTouchesWorkflowState(filePath);
+  }
+
+  if (lowered === 'notebookedit') {
+    const notebookPath = firstString(toolInput.notebook_path, toolInput.notebookPath);
+    return pathTouchesWorkflowState(notebookPath);
+  }
+
+  if (lowered === 'apply_patch') {
+    return collectStrings(toolInput).some(pathTouchesWorkflowState);
+  }
+
+  return collectStrings(toolInput).some(pathTouchesWorkflowState)
+    && /write|edit|patch/i.test(toolName);
+}
+
+function denyOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: 'Workflow state is managed by superharness workflow tools; do not edit .superharness/ directly.',
+    },
+  };
+}
+
+export async function main() {
+  const input = await readStdinJson();
+  if (shouldDeny(input)) {
+    process.stdout.write(`${JSON.stringify(denyOutput())}\n`);
+    return;
+  }
+  process.stdout.write('{}\n');
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/plugins/superharness/hooks/workflow-stop

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "${SCRIPT_DIR}/workflow-stop.mjs"