@hasna/todos 0.9.6 → 0.9.7

package/dist/cli/index.js

@@ -2379,7 +2379,7 @@ var init_database = __esm(() => {
 });
 
 // src/types/index.ts
-var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, TaskListNotFoundError, DependencyCycleError;
+var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError;
 var init_types = __esm(() => {
   VersionConflictError = class VersionConflictError extends Error {
     taskId;
@@ -2445,6 +2445,16 @@ var init_types = __esm(() => {
       this.name = "DependencyCycleError";
     }
   };
+  CompletionGuardError = class CompletionGuardError extends Error {
+    reason;
+    retryAfterSeconds;
+    constructor(reason, retryAfterSeconds) {
+      super(reason);
+      this.reason = reason;
+      this.retryAfterSeconds = retryAfterSeconds;
+      this.name = "CompletionGuardError";
+    }
+  };
 });
 
 // src/db/projects.ts
@@ -2546,6 +2556,173 @@ var init_projects = __esm(() => {
   init_database();
 });
 
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+var HOME;
+var init_sync_utils = __esm(() => {
+  HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+});
+
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTaskListId(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+var CONFIG_PATH, cached = null, GUARD_DEFAULTS;
+var init_config = __esm(() => {
+  init_sync_utils();
+  CONFIG_PATH = join3(HOME, ".todos", "config.json");
+  GUARD_DEFAULTS = {
+    enabled: false,
+    min_work_seconds: 30,
+    max_completions_per_window: 5,
+    window_minutes: 10,
+    cooldown_seconds: 60
+  };
+});
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+var init_completion_guard = __esm(() => {
+  init_types();
+  init_config();
+  init_projects();
+});
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -2723,6 +2900,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -2794,6 +2974,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   d.run(`UPDATE tasks SET status = 'completed', locked_by = NULL, locked_at = NULL, completed_at = ?, version = version + 1, updated_at = ?
      WHERE id = ?`, [timestamp, timestamp, id]);
@@ -2876,6 +3057,7 @@ var init_tasks = __esm(() => {
   init_types();
   init_database();
   init_projects();
+  init_completion_guard();
 });
 
 // src/db/agents.ts
@@ -3111,109 +3293,6 @@ var init_search = __esm(() => {
   init_database();
 });
 
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-var HOME;
-var init_sync_utils = __esm(() => {
-  HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-});
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTaskListId(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-var CONFIG_PATH, cached = null;
-var init_config = __esm(() => {
-  init_sync_utils();
-  CONFIG_PATH = join3(HOME, ".todos", "config.json");
-});
-
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
@@ -7729,6 +7808,10 @@ function formatError(error) {
     return `Lock error: ${error.message}`;
   if (error instanceof DependencyCycleError)
     return `Dependency cycle: ${error.message}`;
+  if (error instanceof CompletionGuardError) {
+    const retry = error.retryAfterSeconds ? ` (retry after ${error.retryAfterSeconds}s)` : "";
+    return `Completion blocked: ${error.reason}${retry}`;
+  }
   if (error instanceof Error)
     return error.message;
   return String(error);

package/dist/index.js

@@ -417,6 +417,17 @@ class DependencyCycleError extends Error {
   }
 }
 
+class CompletionGuardError extends Error {
+  reason;
+  retryAfterSeconds;
+  constructor(reason, retryAfterSeconds) {
+    super(reason);
+    this.reason = reason;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "CompletionGuardError";
+  }
+}
+
 // src/db/projects.ts
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
@@ -517,6 +528,159 @@ function ensureProject(name, path, db) {
   return createProject({ name, path }, d);
 }
 
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+
+// src/lib/config.ts
+var CONFIG_PATH = join3(HOME, ".todos", "config.json");
+var cached = null;
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+var GUARD_DEFAULTS = {
+  enabled: false,
+  min_work_seconds: 30,
+  max_completions_per_window: 5,
+  window_minutes: 10,
+  cooldown_seconds: 60
+};
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -694,6 +858,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -765,6 +932,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   d.run(`UPDATE tasks SET status = 'completed', locked_by = NULL, locked_at = NULL, completed_at = ?, version = version + 1, updated_at = ?
      WHERE id = ?`, [timestamp, timestamp, id]);
@@ -1140,102 +1308,6 @@ function searchTasks(query, projectId, taskListId, db) {
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-
-// src/lib/config.ts
-var CONFIG_PATH = join3(HOME, ".todos", "config.json");
-var cached = null;
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-
-// src/lib/claude-tasks.ts
 function getTaskListDir(taskListId) {
   return join4(HOME, ".claude", "tasks", taskListId);
 }
@@ -1789,6 +1861,7 @@ export {
   getProject,
   getPlan,
   getDatabase,
+  getCompletionGuardConfig,
   getComment,
   getAgentByName,
   getAgent,
@@ -1809,6 +1882,7 @@ export {
   createPlan,
   completeTask,
   closeDatabase,
+  checkCompletionGuard,
   addDependency,
   addComment,
   VersionConflictError,
@@ -1821,5 +1895,6 @@ export {
   PLAN_STATUSES,
   LockError,
   DependencyCycleError,
+  CompletionGuardError,
   AgentNotFoundError
 };

package/dist/mcp/index.js

@@ -4049,6 +4049,17 @@ class DependencyCycleError extends Error {
   }
 }
 
+class CompletionGuardError extends Error {
+  reason;
+  retryAfterSeconds;
+  constructor(reason, retryAfterSeconds) {
+    super(reason);
+    this.reason = reason;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "CompletionGuardError";
+  }
+}
+
 // src/db/database.ts
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "fs";
@@ -4417,6 +4428,164 @@ function nextTaskShortId(projectId, db) {
   return `${updated.task_prefix}-${padded}`;
 }
 
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+
+// src/lib/config.ts
+var CONFIG_PATH = join3(HOME, ".todos", "config.json");
+var cached = null;
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTaskListId(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+var GUARD_DEFAULTS = {
+  enabled: false,
+  min_work_seconds: 30,
+  max_completions_per_window: 5,
+  window_minutes: 10,
+  cooldown_seconds: 60
+};
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -4594,6 +4763,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -4665,6 +4837,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   d.run(`UPDATE tasks SET status = 'completed', locked_by = NULL, locked_at = NULL, completed_at = ?, version = version + 1, updated_at = ?
      WHERE id = ?`, [timestamp, timestamp, id]);
@@ -4960,107 +5133,6 @@ function searchTasks(query, projectId, taskListId, db) {
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-
-// src/lib/config.ts
-var CONFIG_PATH = join3(HOME, ".todos", "config.json");
-var cached = null;
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTaskListId(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-
-// src/lib/claude-tasks.ts
 function getTaskListDir(taskListId) {
   return join4(HOME, ".claude", "tasks", taskListId);
 }
@@ -5593,6 +5665,10 @@ function formatError(error) {
     return `Lock error: ${error.message}`;
   if (error instanceof DependencyCycleError)
     return `Dependency cycle: ${error.message}`;
+  if (error instanceof CompletionGuardError) {
+    const retry = error.retryAfterSeconds ? ` (retry after ${error.retryAfterSeconds}s)` : "";
+    return `Completion blocked: ${error.reason}${retry}`;
+  }
   if (error instanceof Error)
     return error.message;
   return String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/todos",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   "type": "module",
   "main": "dist/index.js",