@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/cli/task.mjs

@@ -0,0 +1,140 @@
+// `claude-gates task` — the CLI half of the task system. The model registers, lists,
+// closes, abandons and promotes tasks through these subcommands; all persistence and the
+// evidence rule live in task-store.mjs (this file is thin wiring, no rules of its own).
+//
+// justification: no existing tool covers this. task-store.mjs was already audited when it
+// was written; this is the CLI surface on top of it, following the same pattern as
+// `registry` in cli/index.mjs.
+
+import { randomUUID } from 'node:crypto';
+import {
+  openTaskStore,
+  STATUS,
+} from '../plugins/tasks/hooks/lib/task-store.mjs';
+import { EXIT_CODE } from './constants.mjs';
+
+const DEFAULT_SIZE = 'unspecified';
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(EXIT_CODE.FAILURE);
+}
+
+function openStoreOrFail(cwd) {
+  const store = openTaskStore(cwd);
+  if (!store) {
+    fail(
+      'No project found here (no .git or .ai/ marker): tasks need a project root.',
+    );
+  }
+  return store;
+}
+
+function taskAdd(title, options, { cwd = process.cwd() } = {}) {
+  if (!title || !title.trim()) fail('task add requires a non-empty title.');
+  const store = openStoreOrFail(cwd);
+  const task = store.add({
+    id: options.id || randomUUID(),
+    title: title.trim(),
+    description: options.description ?? '',
+    status: STATUS.OPEN,
+    size: options.size ?? DEFAULT_SIZE,
+    createdAt: new Date().toISOString(),
+    messages: [],
+  });
+  process.stdout.write(`${JSON.stringify(task, null, 2)}\n`);
+}
+
+function taskList(options, { cwd = process.cwd() } = {}) {
+  const store = openStoreOrFail(cwd);
+  const tasks = options.all
+    ? [...store.active(), ...store.history()]
+    : store.active();
+  if (tasks.length === 0) {
+    process.stdout.write('No tasks.\n');
+    return;
+  }
+  for (const task of tasks) {
+    process.stdout.write(`[${task.status}] ${task.id}: ${task.title}\n`);
+  }
+}
+
+function reportCloseResult(result) {
+  if (result.error) fail(result.error);
+  process.stdout.write(`${JSON.stringify(result.task, null, 2)}\n`);
+}
+
+function taskClose(id, options, { cwd = process.cwd() } = {}) {
+  if (!options.evidence || !options.evidence.trim()) {
+    fail(
+      'closing a task as done requires evidence that it was attended and resolved ' +
+        '(test output, a diff, a verification note). Pass --evidence, or use ' +
+        '`task abandon` if it will not be finished.',
+    );
+  }
+  const store = openStoreOrFail(cwd);
+  reportCloseResult(
+    store.close(id, STATUS.DONE, {
+      reason: options.reason ?? '',
+      evidence: options.evidence,
+    }),
+  );
+}
+
+function taskAbandon(id, options, { cwd = process.cwd() } = {}) {
+  const store = openStoreOrFail(cwd);
+  reportCloseResult(
+    store.close(id, STATUS.ABANDONED, { reason: options.reason ?? '' }),
+  );
+}
+
+function taskPromote(id, runId, { cwd = process.cwd() } = {}) {
+  const store = openStoreOrFail(cwd);
+  const promoted = store.promoteToForge(id, runId);
+  if (!promoted) fail(`no active task with id ${id}`);
+  process.stdout.write(`${JSON.stringify(promoted, null, 2)}\n`);
+}
+
+/** Registers the `task` command and its subcommands on a commander program. */
+export function registerTaskCommand(program) {
+  const task = program
+    .command('task')
+    .description('Track project tasks (open/blocked/in_forge/done/abandoned).');
+
+  task
+    .command('add <title>')
+    .description('Register a new open task.')
+    .option('--id <id>', 'explicit task id (default: a generated uuid)')
+    .option('--description <text>', 'longer description of the task')
+    .option('--size <size>', 'rough size estimate (e.g. trivial, small, large)')
+    .action((title, options) => taskAdd(title, options));
+
+  task
+    .command('list')
+    .description('List active tasks (or all with --all).')
+    .option('--all', 'include closed (done/abandoned) tasks from history')
+    .action((options) => taskList(options));
+
+  task
+    .command('close <id>')
+    .description('Close a task as done. Requires --evidence.')
+    .option(
+      '--evidence <text>',
+      'proof the task was attended and resolved (required)',
+    )
+    .option('--reason <text>', 'closing note')
+    .action((id, options) => taskClose(id, options));
+
+  task
+    .command('abandon <id>')
+    .description('Close a task as abandoned (no evidence required).')
+    .option('--reason <text>', 'why the task was dropped')
+    .action((id, options) => taskAbandon(id, options));
+
+  task
+    .command('promote <id> <runId>')
+    .description('Link a task to a forge run and mark it in_forge.')
+    .action((id, runId) => taskPromote(id, runId));
+
+  return task;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Installable, deterministic gates (hooks) for Claude Code: block destructive commands, protected paths, and enforce delegation/spec/quality rules. Configurable per project.",
   "keywords": [
     "claude-code",
@@ -57,6 +57,7 @@
   "devDependencies": {
     "@cspell/eslint-plugin": "^10.1.1",
     "@eslint/js": "^10.0.1",
+    "@stryker-mutator/core": "^10.0.0",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-boundaries": "^7.2.0",

package/plugins/gates/.claude-plugin/plugin.json

@@ -1,9 +1,15 @@
 {
   "name": "gates",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic gates for Claude Code: destructive-command blocks, protected paths, delegation briefs, spec-driven flow and session-start validation. Selection lives in config, not in code.",
   "author": {
     "name": "Devrik"
   },
-  "keywords": ["hooks", "guards", "gates", "PreToolUse", "SessionStart"]
+  "keywords": [
+    "hooks",
+    "guards",
+    "gates",
+    "PreToolUse",
+    "SessionStart"
+  ]
 }

package/plugins/gates/hooks/__tests__/ask-adoption.test.mjs

@@ -0,0 +1,83 @@
+// ask-adoption — SessionStart hook. Spawned as a real child process with a JSON payload
+// on stdin, against a temp project (never this repo's own .ai/ state).
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'ask-adoption.mjs',
+);
+
+function makeProject() {
+  const project = mkdtempSync(join(tmpdir(), 'ask-adoption-'));
+  mkdirSync(join(project, '.git'));
+  return project;
+}
+
+function runHook(cwd) {
+  return execFileSync(process.execPath, [HOOK_PATH], {
+    input: JSON.stringify({ cwd }),
+    encoding: 'utf8',
+    env: { ...process.env, HOME: cwd, USERPROFILE: cwd },
+  });
+}
+
+test('a project that never answered gets asked, and the hook records that it asked', () => {
+  const project = makeProject();
+  const stdout = runHook(project);
+  assert.notEqual(stdout, '');
+  const payload = JSON.parse(stdout);
+  assert.equal(payload.hookSpecificOutput.hookEventName, 'SessionStart');
+  assert.match(payload.hookSpecificOutput.additionalContext, /adopt/i);
+  assert.ok(existsSync(join(project, '.ai', '.adoption-asked')));
+});
+
+test('a second session in the same never-answered project is not asked again', () => {
+  const project = makeProject();
+  runHook(project); // first session: asks, writes the marker
+  const stdout = runHook(project); // second session
+  assert.equal(stdout, '');
+});
+
+test('a project with an existing .ai/config.json is never asked', () => {
+  const project = makeProject();
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({ gates: {} }),
+  );
+  const stdout = runHook(project);
+  assert.equal(stdout, '');
+});
+
+test('askAdoptionInNewProject:false silences the hook even in a never-answered project', () => {
+  const project = makeProject();
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  // A config exists only to carry the disable flag; the adoption question itself would
+  // otherwise still be considered "answered" by this same file's presence — so assert the
+  // disable path directly against a config that ALSO sets the flag off, confirming this is
+  // the flag doing the work and not just "config.json exists" from the previous test.
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({ gates: { askAdoptionInNewProject: false } }),
+  );
+  const stdout = runHook(project);
+  assert.equal(stdout, '');
+});
+
+test('never throws even when stdin is not valid JSON', () => {
+  const project = makeProject();
+  const stdout = execFileSync(process.execPath, [HOOK_PATH], {
+    input: 'not json',
+    encoding: 'utf8',
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  assert.equal(typeof stdout, 'string');
+});

package/plugins/gates/hooks/__tests__/doctor.test.mjs

@@ -0,0 +1,85 @@
+// doctor — SessionStart hook. Spawned as a real child process with a JSON payload on
+// stdin, HOME isolated so the real global config is never read.
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'doctor.mjs',
+);
+
+function makeProject() {
+  const project = mkdtempSync(join(tmpdir(), 'doctor-'));
+  mkdirSync(join(project, '.git'));
+  return project;
+}
+
+function runHook(cwd, { env: environment = {} } = {}) {
+  return execFileSync(process.execPath, [HOOK_PATH], {
+    input: JSON.stringify({ cwd }),
+    encoding: 'utf8',
+    env: { ...process.env, HOME: cwd, USERPROFILE: cwd, ...environment },
+  });
+}
+
+test('stays silent when node satisfies the current engines.node and scripts are on disk', () => {
+  const project = makeProject();
+  const stdout = runHook(project);
+  assert.equal(stdout, '');
+});
+
+test('speaks when a minNodeVersion above the running node is configured', () => {
+  const project = makeProject();
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({
+      gates: {
+        validateEnvironmentOnStart: {
+          enabled: true,
+          minNodeVersion: '999.0.0',
+        },
+      },
+    }),
+  );
+  const stdout = runHook(project);
+  assert.notEqual(stdout, '');
+  const payload = JSON.parse(stdout);
+  assert.equal(payload.hookSpecificOutput.hookEventName, 'SessionStart');
+  assert.match(payload.hookSpecificOutput.additionalContext, /999\.0\.0/);
+});
+
+test('validateEnvironmentOnStart:false in project config silences the hook even with a bad minNodeVersion', () => {
+  const project = makeProject();
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({
+      gates: {
+        validateEnvironmentOnStart: {
+          enabled: false,
+          minNodeVersion: '999.0.0',
+        },
+      },
+    }),
+  );
+  const stdout = runHook(project);
+  assert.equal(stdout, '');
+});
+
+test('never throws even when stdin is not valid JSON', () => {
+  const project = makeProject();
+  const stdout = execFileSync(process.execPath, [HOOK_PATH], {
+    input: 'not json',
+    encoding: 'utf8',
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  assert.equal(typeof stdout, 'string');
+});

package/plugins/gates/hooks/__tests__/wiring-check.test.mjs

@@ -0,0 +1,65 @@
+// wiring-check — SessionStart hook. Runs against the REAL repo registry/hooks.json/disk
+// (it has no per-project state of its own — it inspects the install, not the project),
+// with HOME isolated only so config lookups do not read a real global config.
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'wiring-check.mjs',
+);
+const REPO_ROOT = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  '..',
+  '..',
+);
+
+function makeHomeOnly() {
+  // wiring-check reads the registry/hooks.json relative to ITS OWN location on disk, so the
+  // cwd it's given only matters for config lookup; it does not need to be a project root.
+  return mkdtempSync(join(tmpdir(), 'wiring-check-home-'));
+}
+
+function runHook(cwd, home) {
+  return execFileSync(process.execPath, [HOOK_PATH], {
+    input: JSON.stringify({ cwd }),
+    encoding: 'utf8',
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+}
+
+test('the real repo (registry, hooks.json, disk all in sync) produces no warning', () => {
+  const home = makeHomeOnly();
+  const stdout = runHook(REPO_ROOT, home);
+  assert.equal(stdout, '', `expected silence, got: ${stdout}`);
+});
+
+test('checkWiringOnStart:false silences the hook globally', () => {
+  const home = makeHomeOnly();
+  mkdirSync(join(home, '.claude', 'claude-gates'), { recursive: true });
+  writeFileSync(
+    join(home, '.claude', 'claude-gates', 'config.json'),
+    JSON.stringify({ gates: { checkWiringOnStart: false } }),
+  );
+  const stdout = runHook(REPO_ROOT, home);
+  assert.equal(stdout, '');
+});
+
+test('never throws even when stdin is not valid JSON', () => {
+  const home = makeHomeOnly();
+  const stdout = execFileSync(process.execPath, [HOOK_PATH], {
+    input: 'not json',
+    encoding: 'utf8',
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+  assert.equal(typeof stdout, 'string');
+});

package/plugins/gates/hooks/ask-adoption.mjs

@@ -0,0 +1,147 @@
+// ask-adoption — SessionStart hook. In a project that has never answered the adoption
+// question (no `.ai/config.json` and no recorded "asked" marker), asks the ASSISTANT to
+// ask the USER what to adopt — a SessionStart hook cannot itself pop a question (there is
+// no decision surface on this event), so the only legitimate move is to inject
+// additionalContext asking the model to raise it, exactly once.
+//
+// The hook does NOT depend on the model actually asking for its own correctness: the
+// deterministic half is the "have we already asked" marker, which THIS hook writes itself
+// (see markAsked below) the moment it speaks — not something it waits on the model to
+// report back. That guarantees the question is offered at most once per project even if
+// the model never follows up.
+//
+// "Already answered" is either of:
+//   - `.ai/config.json` exists (any content — the project already ran `init`, or has an
+//     explicit config; both count as "answered", including a deliberate `adopted: false`).
+//   - `.ai/.adoption-asked` exists (written by this hook after it spoke once, for the case
+//     where the assistant never ran `init` — so the question is not repeated every session).
+//
+// justification: no existing tool covers this. `ask-adoption` was declared in registry.json
+// (session family) with no script; this is that missing wiring, mirroring `session-tasks.mjs`
+// and `register-requests.mjs`'s "hook asks, model judges" pattern for the tasks plugin.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const STDIN_FILE_DESCRIPTOR = 0;
+const SESSION_START_EVENT = 'SessionStart';
+const CONFIG_KEY = 'askAdoptionInNewProject';
+const PROJECT_STATE_DIRECTORY = '.ai';
+const CONFIG_FILE = 'config.json';
+const ASKED_MARKER_FILE = '.adoption-asked';
+
+// Same config lookup as the other session hooks: kept local, dependency-free.
+const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
+const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
+
+const BOM_CHAR_CODE = 0xfeff;
+
+/** Strips a UTF-8 BOM a Windows editor/tool may have written before the JSON. */
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CHAR_CODE ? text.slice(1) : text;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(stripBom(readFileSync(path, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** The ask-adoption gate config entry (project overrides global), or null. */
+function adoptionConfig(startDirectory, projectRoot) {
+  const projectData = projectRoot
+    ? readJson(join(projectRoot, PROJECT_STATE_DIRECTORY, CONFIG_FILE))
+    : null;
+  const globalData = readJson(join(homedir(), GLOBAL_CONFIG));
+  const layer = projectData?.gates ?? globalData?.gates ?? {};
+  const entry = layer[CONFIG_KEY];
+  if (typeof entry === 'boolean') return { enabled: entry };
+  if (entry && typeof entry === 'object') return entry;
+  return null;
+}
+
+function readPayload() {
+  try {
+    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function speak(context) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: SESSION_START_EVENT,
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+/** Writes the "already asked" marker so this project is never asked again. */
+function markAsked(projectRoot) {
+  try {
+    mkdirSync(join(projectRoot, PROJECT_STATE_DIRECTORY), { recursive: true });
+    writeFileSync(
+      join(projectRoot, PROJECT_STATE_DIRECTORY, ASKED_MARKER_FILE),
+      `${new Date().toISOString()}\n`,
+    );
+  } catch {
+    // If the marker can't be written, worst case the question is offered again next
+    // session — not a correctness break, just a repeat.
+  }
+}
+
+const ADOPTION_PROMPT =
+  '[ask-adoption] This project has not adopted claude-gates yet (no .ai/config.json found). ' +
+  'Ask the user, once, whether they want to adopt it and with which mode: ' +
+  '"defaults" (recommended gates only), "all" (every gate in every family), or "none" ' +
+  '(record a no so this is not asked again). Record whatever they choose by running ' +
+  '`claude-gates init --<mode> --yes` (add --project or --global for scope) from the ' +
+  'project root — that CLI run is what actually persists the decision.';
+
+function main() {
+  const payload = readPayload();
+  const cwd = payload.cwd || process.cwd();
+  const projectRoot = projectRootOf(cwd) ?? cwd;
+
+  const config = adoptionConfig(cwd, projectRoot);
+  if (config && config.enabled === false) return; // gate turned off for this project
+
+  const configPath = join(projectRoot, PROJECT_STATE_DIRECTORY, CONFIG_FILE);
+  if (existsSync(configPath)) return; // already answered (init ran, or an explicit config)
+
+  const markerPath = join(
+    projectRoot,
+    PROJECT_STATE_DIRECTORY,
+    ASKED_MARKER_FILE,
+  );
+  if (existsSync(markerPath)) return; // already asked once; do not repeat
+
+  speak(ADOPTION_PROMPT);
+  markAsked(projectRoot);
+}
+
+try {
+  main();
+} catch {
+  // A broken ask-adoption hook must never block session start.
+}