@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/tasks/hooks/lib/task-store.mjs

@@ -1,159 +1,197 @@
-// The task store: the single source of truth for a project's tasks, on disk under
-// .ai/tasks/. Self-contained (Node built-ins only) so a hook can use it when the plugin is
-// installed on its own.
-//
-// justification: no existing tool covers this. Audited LOCAL deps (find-up, commander,
-// @clack/prompts, zod — none is a task store), CONTEXT7 (generic JSON-store libs), and WEB
-// (victor-software-house/task-tracker-plugin and Claude Code's native task manager both
-// persist tasks and survive compaction, but neither distills tasks from chat, none is a
-// zero-runtime-dependency library, and none fits the active/history + git-root shape here).
-// The generic persistence is a solved pattern; this store is the thin, dependency-free,
-// domain-specific piece the value layer (distil + remind + unlazy) sits on.
-//
-// Two files, mirroring the harness-sdd model:
-//   active.json   { tasks: [ {id, title, description, status, size, createdAt, messages[]} ] }
-//   history.json  { tasks: [ ...same shape + closedAt + closeReason ] }  — append-only
-// A task is never deleted: done and abandoned tasks MOVE from active to history, so the
-// record of what was decided (and dropped) is never lost.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-const TASKS_DIR = join('.ai', 'tasks');
-const ACTIVE_FILE = 'active.json';
-const HISTORY_FILE = 'history.json';
-const COUNTER_FILE = 'counter.json';
-const JSON_INDENT = 2;
-// A project root holds `.git` or `.ai/` — the same set the CLI and the gates config use, so
-// a repo-less project (no git yet) still resolves. Anchoring on `.git` alone drops it.
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-
-/** Statuses a task can hold. Active: open/blocked. Terminal (moved to history): done/abandoned. */
-export const STATUS = Object.freeze({
-  OPEN: 'open',
-  BLOCKED: 'blocked',
-  DONE: 'done',
-  ABANDONED: 'abandoned',
-});
-
-const TERMINAL_STATUSES = new Set([STATUS.DONE, STATUS.ABANDONED]);
-
-/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
-export 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;
-  }
-}
-
-function readCollection(path) {
-  if (!existsSync(path)) return { tasks: [] };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    return Array.isArray(parsed.tasks) ? parsed : { tasks: [] };
-  } catch {
-    return { tasks: [] };
-  }
-}
-
-function writeCollection(path, collection) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(
-    path,
-    `${JSON.stringify(collection, null, JSON_INDENT)}\n`,
-    'utf8',
-  );
-}
-
-/**
- * Opens the store rooted at a project. All paths derive from the project root's .ai/tasks/.
- * Returns a handle with read/mutate operations; each mutation persists immediately so a
- * crash between calls never loses a recorded task. Null when there is no project (no .git).
- */
-export function openTaskStore(startDirectory) {
-  const root = projectRootOf(startDirectory);
-  if (!root) return null;
-
-  const directory = join(root, TASKS_DIR);
-  const activePath = join(directory, ACTIVE_FILE);
-  const historyPath = join(directory, HISTORY_FILE);
-  const counterPath = join(directory, COUNTER_FILE);
-
-  return {
-    root,
-    /** Open (non-terminal) tasks. */
-    active() {
-      return readCollection(activePath).tasks;
-    },
-    /** Terminal (done/abandoned) tasks, newest last. */
-    history() {
-      return readCollection(historyPath).tasks;
-    },
-    /** Adds a task to active and returns it. `id` is caller-supplied (stable, human-readable). */
-    add(task) {
-      const collection = readCollection(activePath);
-      collection.tasks.push(task);
-      writeCollection(activePath, collection);
-      return task;
-    },
-    /** Merges fields into the active task with matching id. Null if not found. */
-    update(id, fields) {
-      const collection = readCollection(activePath);
-      const task = collection.tasks.find((entry) => entry.id === id);
-      if (!task) return null;
-      Object.assign(task, fields);
-      writeCollection(activePath, collection);
-      return task;
-    },
-    /**
-     * Closes an active task: sets a terminal status + closedAt + closeReason, then MOVES it
-     * from active to history (append-only). Nothing is deleted. Returns the closed task, or
-     * null when the id or status is invalid.
-     */
-    close(id, status, reason) {
-      if (!TERMINAL_STATUSES.has(status)) return null;
-      const activeCollection = readCollection(activePath);
-      const index = activeCollection.tasks.findIndex(
-        (entry) => entry.id === id,
-      );
-      if (index === -1) return null;
-
-      const [task] = activeCollection.tasks.splice(index, 1);
-      task.status = status;
-      task.closedAt = new Date().toISOString();
-      task.closeReason = reason ?? '';
-
-      const historyCollection = readCollection(historyPath);
-      historyCollection.tasks.push(task);
-
-      writeCollection(historyPath, historyCollection);
-      writeCollection(activePath, activeCollection);
-      return task;
-    },
-    /** The message counter since the last reminder (0 when unset or unreadable). */
-    counter() {
-      if (!existsSync(counterPath)) return 0;
-      try {
-        return JSON.parse(readFileSync(counterPath, 'utf8')).count ?? 0;
-      } catch {
-        return 0;
-      }
-    },
-    /** Sets the message counter. */
-    setCounter(count) {
-      mkdirSync(directory, { recursive: true });
-      writeFileSync(
-        counterPath,
-        `${JSON.stringify({ count }, null, JSON_INDENT)}\n`,
-        'utf8',
-      );
-    },
-  };
-}
+// The task store: the single source of truth for a project's tasks, on disk under
+// .ai/tasks/. Self-contained (Node built-ins only) so a hook can use it when the plugin is
+// installed on its own.
+//
+// justification: no existing tool covers this. Audited LOCAL deps (find-up, commander,
+// @clack/prompts, zod — none is a task store), CONTEXT7 (generic JSON-store libs), and WEB
+// (victor-software-house/task-tracker-plugin and Claude Code's native task manager both
+// persist tasks and survive compaction, but neither distills tasks from chat, none is a
+// zero-runtime-dependency library, and none fits the active/history + git-root shape here).
+// The generic persistence is a solved pattern; this store is the thin, dependency-free,
+// domain-specific piece the value layer (distil + remind + unlazy) sits on.
+//
+// Two files, mirroring the harness-sdd model:
+//   active.json   { tasks: [ {id, title, description, status, size, createdAt, messages[]} ] }
+//   history.json  { tasks: [ ...same shape + closedAt + closeReason ] }  — append-only
+// A task is never deleted: done and abandoned tasks MOVE from active to history, so the
+// record of what was decided (and dropped) is never lost.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const TASKS_DIR = join('.ai', 'tasks');
+const ACTIVE_FILE = 'active.json';
+const HISTORY_FILE = 'history.json';
+const COUNTER_FILE = 'counter.json';
+const JSON_INDENT = 2;
+// A project root holds `.git` or `.ai/` — the same set the CLI and the gates config use, so
+// a repo-less project (no git yet) still resolves. Anchoring on `.git` alone drops it.
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+
+/** Statuses a task can hold. Active: open/blocked/in_forge. Terminal (history): done/abandoned. */
+export const STATUS = Object.freeze({
+  OPEN: 'open',
+  BLOCKED: 'blocked',
+  IN_FORGE: 'in_forge', // promoted to a forge run for pipeline execution; still active
+  DONE: 'done',
+  ABANDONED: 'abandoned',
+});
+
+const TERMINAL_STATUSES = new Set([STATUS.DONE, STATUS.ABANDONED]);
+// A task closed as done must carry evidence it was actually attended and resolved — the
+// project rule "ningún pedido se marca hecho sin evidencia válida" made mechanical. Abandoned
+// needs only a reason (it is a deliberate drop, not a claim of completion), so it is exempt.
+const STATUS_REQUIRING_EVIDENCE = new Set([STATUS.DONE]);
+
+/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
+export 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;
+  }
+}
+
+// Node's readFileSync('utf8') does not strip a leading UTF-8 BOM (EF BB BF, decoded as
+// U+FEFF), and JSON.parse rejects a string starting with it. A file written by a BOM-adding
+// editor or `PowerShell Set-Content -Encoding utf8` would otherwise silently read back as
+// "corrupt" (caught below, treated as empty) — the same failure mode that made the gates'
+// own config.mjs treat a valid project config as absent. Stripping it here is the fix.
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function readCollection(path) {
+  if (!existsSync(path)) return { tasks: [] };
+  try {
+    const parsed = JSON.parse(stripBom(readFileSync(path, 'utf8')));
+    return Array.isArray(parsed.tasks) ? parsed : { tasks: [] };
+  } catch {
+    return { tasks: [] };
+  }
+}
+
+function writeCollection(path, collection) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    `${JSON.stringify(collection, null, JSON_INDENT)}\n`,
+    'utf8',
+  );
+}
+
+/**
+ * Opens the store rooted at a project. All paths derive from the project root's .ai/tasks/.
+ * Returns a handle with read/mutate operations; each mutation persists immediately so a
+ * crash between calls never loses a recorded task. Null when there is no project (no .git).
+ */
+export function openTaskStore(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  if (!root) return null;
+
+  const directory = join(root, TASKS_DIR);
+  const activePath = join(directory, ACTIVE_FILE);
+  const historyPath = join(directory, HISTORY_FILE);
+  const counterPath = join(directory, COUNTER_FILE);
+
+  return {
+    root,
+    /** Open (non-terminal) tasks. */
+    active() {
+      return readCollection(activePath).tasks;
+    },
+    /** Terminal (done/abandoned) tasks, newest last. */
+    history() {
+      return readCollection(historyPath).tasks;
+    },
+    /** Adds a task to active and returns it. `id` is caller-supplied (stable, human-readable). */
+    add(task) {
+      const collection = readCollection(activePath);
+      collection.tasks.push(task);
+      writeCollection(activePath, collection);
+      return task;
+    },
+    /** Merges fields into the active task with matching id. Null if not found. */
+    update(id, fields) {
+      const collection = readCollection(activePath);
+      const task = collection.tasks.find((entry) => entry.id === id);
+      if (!task) return null;
+      Object.assign(task, fields);
+      writeCollection(activePath, collection);
+      return task;
+    },
+    /**
+     * Closes an active task: sets a terminal status + closedAt + closeReason, then MOVES it
+     * from active to history (append-only). Nothing is deleted. Returns { task } on success,
+     * or { error } describing why it was refused — so a caller can tell "not found" from
+     * "done without evidence" and surface the right message.
+     *
+     * Closing as `done` REQUIRES non-empty `evidence` (a command output, a test result, a
+     * diff, a verification note): a request is never marked resolved on a claim alone.
+     * `abandoned` needs only a reason.
+     */
+    close(id, status, { reason, evidence } = {}) {
+      if (!TERMINAL_STATUSES.has(status)) {
+        return { error: `invalid terminal status: ${status}` };
+      }
+      if (STATUS_REQUIRING_EVIDENCE.has(status) && !String(evidence ?? '').trim()) {
+        return {
+          error:
+            'closing a task as done requires evidence that it was attended and resolved ' +
+            '(test output, a diff, a verification note). Provide --evidence, or close it as ' +
+            'abandoned with a reason if it will not be finished.',
+        };
+      }
+      const activeCollection = readCollection(activePath);
+      const index = activeCollection.tasks.findIndex(
+        (entry) => entry.id === id,
+      );
+      if (index === -1) return { error: `no active task with id ${id}` };
+
+      const [task] = activeCollection.tasks.splice(index, 1);
+      task.status = status;
+      task.closedAt = new Date().toISOString();
+      task.closeReason = reason ?? '';
+      if (STATUS_REQUIRING_EVIDENCE.has(status)) task.evidence = String(evidence).trim();
+
+      const historyCollection = readCollection(historyPath);
+      historyCollection.tasks.push(task);
+
+      writeCollection(historyPath, historyCollection);
+      writeCollection(activePath, activeCollection);
+      return { task };
+    },
+    /**
+     * Promotes an active task to a forge run: records the run id and flips status to in_forge
+     * (still active — it is being executed, not closed). Whether a task is promoted is the
+     * assistant's judgment, not a rule; this only records the link. Null if id not found.
+     */
+    promoteToForge(id, forgeRunId) {
+      return this.update(id, { status: STATUS.IN_FORGE, forgeRunId: String(forgeRunId) });
+    },
+    /** The message counter since the last reminder (0 when unset or unreadable). */
+    counter() {
+      if (!existsSync(counterPath)) return 0;
+      try {
+        return JSON.parse(stripBom(readFileSync(counterPath, 'utf8'))).count ?? 0;
+      } catch {
+        return 0;
+      }
+    },
+    /** Sets the message counter. */
+    setCounter(count) {
+      mkdirSync(directory, { recursive: true });
+      writeFileSync(
+        counterPath,
+        `${JSON.stringify({ count }, null, JSON_INDENT)}\n`,
+        'utf8',
+      );
+    },
+  };
+}

package/plugins/tasks/hooks/register-requests.mjs

@@ -1,108 +1,141 @@
-// register-requests — UserPromptSubmit hook. Runs on every user message, BEFORE the
-// assistant responds. It is the deterministic half of the task system: it never decides
-// what is a task (that judgment is the assistant's), it only makes sure open tasks are not
-// forgotten. Two jobs, both cheap and side-effect-light:
-//   1. Count messages. Every `remindEvery` messages, surface a stronger reminder.
-//   2. Inject the open tasks (title + status) into the assistant's context so a long or
-//      compacted conversation never loses the thread of what is still pending.
-//
-// A UserPromptSubmit hook's stdout is added to the assistant's context as plain text, so
-// the reminder is simply written to stdout. Self-contained: Node built-ins + the task-store
-// lib only, no npm at runtime.
-//
-// justification: no existing tool covers this. The task store and the audit were done when
-// task-store.mjs was written (see its header); this file is the hook wiring on top.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { openTaskStore } from './lib/task-store.mjs';
-
-const STDIN_FILE_DESCRIPTOR = 0;
-const CONFIG_KEY = 'runTaskReminders';
-const DEFAULT_REMIND_EVERY = 10;
-const MAX_TASKS_SHOWN = 12;
-
-// Config lookup mirrors the gates' config.mjs (project → global), kept local so this plugin
-// stays independent of the gates plugin.
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const PROJECT_CONFIG = join('.ai', 'config.json');
-const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
-
-function readJson(path) {
-  try {
-    return JSON.parse(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 tasks gate config entry (project overrides global), or null. */
-function taskConfig(startDirectory) {
-  const root = projectRootOf(startDirectory);
-  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : 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 formatReminder(tasks, forced) {
-  const shown = tasks.slice(0, MAX_TASKS_SHOWN);
-  const lines = shown.map(
-    (task) => `  - [${task.status}] ${task.id}: ${task.title}`,
-  );
-  const extra = tasks.length - shown.length;
-  if (extra > 0) lines.push(`  - …and ${extra} more`);
-  const header = forced
-    ? 'OPEN TASKS — recite these pending tasks to the user and confirm whether any should be dropped:'
-    : 'Open tasks (do not lose track of these):';
-  return `[tasks] ${header}\n${lines.join('\n')}`;
-}
-
-function main() {
-  const payload = readPayload();
-  const cwd = payload.cwd || process.cwd();
-
-  const config = taskConfig(cwd);
-  if (config && config.enabled === false) return; // gate turned off for this project
-
-  const store = openTaskStore(cwd);
-  if (!store) return; // no project: nowhere to track
-
-  const tasks = store.active();
-  if (tasks.length === 0) return; // nothing pending: stay silent
-
-  const remindEvery = Number(config?.remindEvery) || DEFAULT_REMIND_EVERY;
-  const next = store.counter() + 1;
-  const forced = next >= remindEvery;
-  store.setCounter(forced ? 0 : next);
-
-  process.stdout.write(`${formatReminder(tasks, forced)}\n`);
-}
-
-main();
+// register-requests — UserPromptSubmit hook. Runs on every user message, BEFORE the
+// assistant responds. It is the deterministic half of the task system: it never decides
+// what is a task (that judgment is the assistant's — the hook only asks it to judge), it
+// only makes sure the judgment is asked and open tasks are not forgotten. Two jobs:
+//   1. On every message, ask the assistant to classify: if this message is a new task,
+//      register it via `claude-gates task add` (persistence is deterministic — the store —
+//      but the classification itself is the model's judgment, never a regex here).
+//   2. Every `remindEveryMessages` messages (counted via the store's counter), also recite
+//      the currently active tasks so a long or compacted conversation never loses the
+//      thread of what is still pending.
+//
+// A UserPromptSubmit hook's stdout is added to the assistant's context as plain text, so
+// both are simply written to stdout. Self-contained: Node built-ins + the task-store lib
+// only, no npm at runtime.
+//
+// justification: no existing tool covers this. The task store and the audit were done when
+// task-store.mjs was written (see its header); this file is the hook wiring on top.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { openTaskStore } from './lib/task-store.mjs';
+
+const STDIN_FILE_DESCRIPTOR = 0;
+const CONFIG_KEY = 'remindOpenTasks';
+const DEFAULT_REMIND_EVERY_MESSAGES = 5;
+const MAX_TASKS_SHOWN = 12;
+const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
+
+// Config lookup mirrors the gates' config.mjs (project → global), kept local so this plugin
+// stays independent of the gates plugin.
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const PROJECT_CONFIG = join('.ai', 'config.json');
+const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
+
+function readJson(path) {
+  try {
+    return JSON.parse(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 tasks gate config entry (project overrides global), or null. */
+function taskConfig(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : 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 {};
+  }
+}
+
+// Asked on every message. The hook does not classify — it asks the model to, and the
+// model is the one that persists (via the CLI, which enforces the store's own rules,
+// e.g. evidence on close). This is legitimate: the hook is not depending on the model to
+// make something OCCUR deterministically; it is depending on the model's judgment for a
+// judgment call (whether this message describes a new task), same shape as ask-adoption.
+const CLASSIFY_PROMPT =
+  '[tasks] If the user just described a new actionable task (not a question, not small talk), ' +
+  'register it now: run `claude-gates task add "<title>" [--description <text>] [--size <size>]` ' +
+  'from the project root. Skip this for messages that are not a new task.';
+
+function formatReminder(tasks) {
+  const shown = tasks.slice(0, MAX_TASKS_SHOWN);
+  const lines = shown.map(
+    (task) => `  - [${task.status}] ${task.id}: ${task.title}`,
+  );
+  const extra = tasks.length - shown.length;
+  if (extra > 0) lines.push(`  - …and ${extra} more`);
+  return (
+    '[tasks] OPEN TASKS — recite these pending tasks to the user and confirm whether any ' +
+    `should be dropped:\n${lines.join('\n')}`
+  );
+}
+
+function main() {
+  // Same defaults-dump protocol as the gates plugin's runGate (see hook-io.mjs): the CLI's
+  // materialize.mjs spawns this script with the env var set to read its built-in params as
+  // the single source of truth, before touching stdin.
+  if (process.env[DUMP_ENV]) {
+    process.stdout.write(
+      JSON.stringify({
+        id: 'remind-open-tasks',
+        configKey: CONFIG_KEY,
+        enabledByDefault: true,
+        defaultParams: { remindEveryMessages: DEFAULT_REMIND_EVERY_MESSAGES },
+      }),
+    );
+    return;
+  }
+
+  const payload = readPayload();
+  const cwd = payload.cwd || process.cwd();
+
+  const config = taskConfig(cwd);
+  if (config && config.enabled === false) return; // gate turned off for this project
+
+  const store = openTaskStore(cwd);
+  if (!store) return; // no project: nowhere to track
+
+  const lines = [CLASSIFY_PROMPT];
+
+  const tasks = store.active();
+  if (tasks.length > 0) {
+    const remindEveryMessages =
+      Number(config?.remindEveryMessages) || DEFAULT_REMIND_EVERY_MESSAGES;
+    const next = store.counter() + 1;
+    const forced = next >= remindEveryMessages;
+    store.setCounter(forced ? 0 : next);
+    if (forced) lines.push(formatReminder(tasks));
+  }
+
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+main();