aitasks 1.3.1 → 1.3.3

package/README.md

@@ -174,14 +174,17 @@ aitasks init --with-review
 aitasks init --with-review  # safe to re-run; updates DB setting and rewrites agent file
 ```
 
+**A task is only complete when its status is `done`.** No other status — verified criteria, `review`, `in_progress` — counts as complete. Agents must reach `done` to consider a task finished.
+
 **How it works:**
 
-1. Agent completes work and checks all acceptance criteria
+1. Agent completes work and verifies all acceptance criteria with evidence
 2. Agent submits for review — task moves to `review` status:
    ```sh
    aitasks review TASK-001 --agent $AITASKS_AGENT_ID
    ```
-3. A separate review sub-agent inspects the implementation and either:
+   The command output explicitly instructs the agent to immediately spawn a review sub-agent. The task is **not complete** at this point.
+3. The agent **immediately spawns a review sub-agent** to inspect the implementation:
    - **Approves** — moves task to done:
      ```sh
      aitasks done TASK-001 --agent review-agent
@@ -190,11 +193,11 @@ aitasks init --with-review  # safe to re-run; updates DB setting and rewrites ag
      ```sh
      aitasks reject TASK-001 --reason "Missing error handling for 404 case" --agent review-agent
      ```
-4. If rejected, the agent addresses feedback, re-verifies criteria, and repeats from step 2.
+4. If rejected, the original agent addresses the feedback, re-verifies criteria, and repeats from step 2.
 
-**Enforcement:** When review is required, `aitasks done` and `aitasks update --status done` both block if the task is not already in `review` status. The gate cannot be bypassed.
+**Enforcement:** `aitasks done` and `aitasks update --status done` both block if the task isn't already in `review` status. The gate cannot be bypassed.
 
-**Board:** Tasks in `review` status appear in the **IN PROGRESS** section with a `◈` magenta indicator so they're visually distinct from actively worked tasks.
+**Board:** Tasks in `review` status appear in the **IN PROGRESS** section with a `◈` magenta indicator so they're visually distinct from actively-worked tasks.
 
 ---
 

package/dist/index.js

@@ -1890,7 +1890,7 @@ var require_commander = __commonJS((exports) => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "aitasks",
-    version: "1.3.1",
+    version: "1.3.3",
     description: "CLI task management tool built for AI agents",
     type: "module",
     bin: {
@@ -29290,7 +29290,12 @@ function getAgentInstructions(version, opts = {}) {
   return `${INSTRUCTIONS_START_MARKER}
 
 ## AITasks \u2014 Agent Task Protocol (v${version})
-
+${reviewRequired ? `
+> \u26A0\uFE0F  **REVIEW ENFORCEMENT IS ENABLED ON THIS PROJECT**
+> You cannot mark any task done directly. Every task requires a review step:
+> \`aitasks review\` \u2192 spawn review sub-agent \u2192 \`aitasks done\`
+> Tasks are only complete when their status is \`done\`. All other statuses mean work is still in progress.
+` : ""}
 You have access to the \`aitasks\` CLI. This is your single source of truth for
 all work in this project. Follow this protocol without exception.
 
@@ -29347,7 +29352,7 @@ This finds the best task, claims it, and starts it in one command.
    aitasks start TASK-001 --agent $AITASKS_AGENT_ID
    \`\`\`
 
-**Bulk operations:** You can claim, start, review, or complete multiple tasks at once:
+**Bulk operations:** You can claim, start, or complete multiple tasks at once:
 \`\`\`bash
 aitasks claim TASK-001 TASK-002 TASK-003 --agent $AITASKS_AGENT_ID
 aitasks start TASK-001 TASK-002 --agent $AITASKS_AGENT_ID
@@ -29395,6 +29400,8 @@ aitasks deps TASK-001    # Shows what this task is blocked by and what it blocks
 
 ### Completing a Task${reviewRequired ? " \u26A0\uFE0F  REVIEW REQUIRED" : ""}
 
+> **A task is only complete when its status is \`done\`. Verified criteria, implementation notes, and \`review\` status do NOT mean the task is done. You have not finished a task until \`aitasks done\` has succeeded.**
+
 You MUST verify every acceptance criterion before marking done.
 
 1. View all criteria:
@@ -29413,26 +29420,31 @@ ${reviewRequired ? `3. Submit for review \u2014 you CANNOT mark done directly:
    \`\`\`bash
    aitasks review TASK-001 --agent $AITASKS_AGENT_ID
    \`\`\`
+   **STOP HERE. Do not run \`aitasks done\` yourself.** The system will block self-approval.
 
-4. Spawn a review sub-agent to inspect the implementation and either:
-   - **Approve** (moves task to done):
-     \`\`\`bash
-     aitasks done TASK-001 --agent <review-agent-id>
-     \`\`\`
-   - **Reject** (sends task back to in_progress with feedback):
-     \`\`\`bash
-     aitasks reject TASK-001 --reason "<specific feedback>" --agent <review-agent-id>
-     \`\`\`
-
-5. If rejected: address the feedback, re-check criteria, and repeat from step 3.` : `3. Mark done (will FAIL if any criterion is unchecked):
+4. **IMMEDIATELY spawn a review sub-agent with a DIFFERENT agent ID** to inspect the implementation.
+   The review sub-agent must first register itself, then approve or reject:
    \`\`\`bash
-   aitasks done TASK-001 --agent $AITASKS_AGENT_ID
+   # Review sub-agent registers itself
+   aitasks heartbeat --agent <review-agent-id>
+
+   # Approve (moves task to done):
+   aitasks done TASK-001 --agent <review-agent-id>
+
+   # OR reject (sends task back to in_progress with feedback):
+   aitasks reject TASK-001 --reason "<specific feedback>" --agent <review-agent-id>
    \`\`\`
+   The task is still incomplete until the review agent approves it.
+   **The system will block approval from any agent that has not registered or that submitted the review itself.**
+
+5. If rejected: address the feedback, re-check criteria, and repeat from step 3.
 
-   If review is needed:
+> The task is only done when \`aitasks done\` completes successfully. \`review\` status means awaiting approval \u2014 it is not done.` : `3. Mark done (will FAIL if any criterion is unchecked):
    \`\`\`bash
-   aitasks review TASK-001 --agent $AITASKS_AGENT_ID
-   \`\`\``}
+   aitasks done TASK-001 --agent $AITASKS_AGENT_ID
+   \`\`\`
+
+> The task is only done when \`aitasks done\` completes successfully. Do not treat a task as finished until you see the done confirmation.`}
 
 ---
 
@@ -29446,8 +29458,8 @@ aitasks undo TASK-001    # Undoes the last action (claim, start, done, check, no
 Undoable actions:
 - claimed \u2192 unclaims the task
 - started \u2192 reverts to ready status
-- completed \u2192 reverts to in_progress
-- review_requested \u2192 reverts to in_progress
+- completed \u2192 reverts to in_progress${reviewRequired ? `
+- review_requested \u2192 reverts to in_progress` : ""}
 - criterion_checked \u2192 removes the verification
 - note_added \u2192 removes the implementation note
 
@@ -29464,14 +29476,15 @@ aitasks unclaim TASK-001 --agent $AITASKS_AGENT_ID --reason "Blocked on missing
 
 ### Rules
 
-1. Never mark a task done without checking EVERY acceptance criterion with evidence.
-2. Never start a task you haven't claimed.
-3. Never silently abandon a task \u2014 always unclaim with a reason.
-4. Add implementation notes continuously, not just at the end.
-5. If a task needs splitting, create subtasks BEFORE marking parent done.
-6. Your evidence strings must be concrete and verifiable \u2014 not vague affirmations.
-7. Always provide --desc and at least one --ac when creating a task. Both are required.${reviewRequired ? `
-8. NEVER move a task to done directly. Always submit for review first with \`aitasks review\`, then spawn a review sub-agent to approve or reject. Tasks cannot be marked done without a passing review.` : ""}
+1. **A task is only complete when its status is \`done\`.** No other status \u2014 not criteria-verified, not \`review\`, not \`in_progress\` \u2014 counts as complete. Your work on a task is not finished until \`aitasks done\` succeeds.
+2. Never mark a task done without checking EVERY acceptance criterion with evidence.
+3. Never start a task you haven't claimed.
+4. Never silently abandon a task \u2014 always unclaim with a reason.
+5. Add implementation notes continuously, not just at the end.
+6. If a task needs splitting, create subtasks BEFORE marking parent done.
+7. Your evidence strings must be concrete and verifiable \u2014 not vague affirmations.
+8. Always provide --desc and at least one --ac when creating a task. Both are required.${reviewRequired ? `
+9. NEVER move a task to done directly. Always submit for review first with \`aitasks review\`, then IMMEDIATELY spawn a review sub-agent with a DIFFERENT agent ID. Do NOT call \`aitasks done\` yourself after submitting for review \u2014 the system blocks self-approval.` : ""}
 
 ---
 
@@ -29488,8 +29501,9 @@ aitasks claim <id...> --agent <id>          Claim task(s) - supports patterns li
 aitasks start <id...> --agent <id>          Begin work on task(s)
 aitasks note <id> <text> --agent <id>       Add implementation note
 aitasks check <id> <n> --evidence <text>    Verify acceptance criterion n
-aitasks done <id...> --agent <id>           Mark task(s) complete
-aitasks review <id...> --agent <id>         Request human review
+aitasks done <id...> --agent <id>           Mark task(s) complete (only valid completion)${reviewRequired ? `
+aitasks review <id...> --agent <id>         Submit for review \u2014 then spawn review sub-agent immediately
+aitasks reject <id> --reason <r>            Reject review \u2014 sends back to in_progress` : ""}
 aitasks block <id> --on <id,...>            Mark as blocked
 aitasks unblock <id> --from <id>            Remove a blocker
 aitasks unclaim <id> --agent <id>           Release task
@@ -29583,7 +29597,19 @@ function appendToSpecificFile(filePath, version, reviewRequired = false) {
 }
 
 // src/commands/init.ts
-var initCommand = new Command("init").description("Initialize AITasks in the current project").option("--skip-agent-file", "Skip injecting agent instructions into CLAUDE.md/AGENTS.md/GEMINI.md").option("--with-review", "Enforce review gate: agents cannot mark tasks done without a passing review").action(async (opts) => {
+var initCommand = new Command("init").description("Initialize AITasks in the current project").option("--skip-agent-file", "Skip injecting agent instructions into CLAUDE.md/AGENTS.md/GEMINI.md").option("--with-review", "Enforce review gate: agents cannot mark tasks done without a passing review").addHelpText("after", `
+Examples:
+  $ aitasks init
+      Initialize in current directory, inject agent instructions into CLAUDE.md/AGENTS.md.
+
+  $ aitasks init --with-review
+      Same as above, but enable the review enforcement gate. Agents must run
+      \`aitasks review\` and spawn a review sub-agent before any task can be
+      marked done. Running this on an existing project also updates the agent
+      instructions file with the review workflow.
+
+  $ aitasks init --skip-agent-file
+      Initialize without touching any CLAUDE.md / AGENTS.md file.`).action(async (opts) => {
   const root = findProjectRoot();
   const taskieDir = join5(root, ".aitasks");
   if (existsSync5(join5(taskieDir, "db.sqlite"))) {
@@ -30427,16 +30453,43 @@ function completeTask(taskId, agentId) {
   if (unchecked.length > 0) {
     return { task: null, error: "Not all acceptance criteria are verified", unchecked };
   }
-  if (getReviewRequired() && task.status !== "review") {
-    return {
-      task: null,
-      error: `Review required: submit this task for review first.
+  if (getReviewRequired()) {
+    if (task.status !== "review") {
+      return {
+        task: null,
+        error: `Review required: submit this task for review first.
 ` + `  1. aitasks review <taskId> --agent $AITASKS_AGENT_ID
 ` + `  2. Spawn a review sub-agent to inspect the work
 ` + `  3. Review agent approves: aitasks done <taskId> --agent <review-agent-id>
 ` + `     Review agent rejects: aitasks reject <taskId> --reason "<feedback>"
 ` + "  Tasks cannot be moved to Done without a passing review."
-    };
+      };
+    }
+    if (task.assigned_to && task.assigned_to === agentId) {
+      return {
+        task: null,
+        error: `Self-approval blocked: ${agentId} is the implementing agent and cannot approve their own review.
+` + `  A separate review sub-agent must run: aitasks done ${taskId} --agent <review-agent-id>`
+      };
+    }
+    const events = getTaskEvents(taskId);
+    const reviewEvent = [...events].reverse().find((e2) => e2.event_type === "review_requested");
+    if (reviewEvent?.agent_id && reviewEvent.agent_id === agentId) {
+      return {
+        task: null,
+        error: `Self-approval blocked: ${agentId} submitted this task for review and cannot also approve it.
+` + `  A separate review sub-agent must run: aitasks done ${taskId} --agent <review-agent-id>`
+      };
+    }
+    const knownAgent = db.query(`SELECT id FROM agents WHERE id = ?`).get(agentId);
+    if (!knownAgent) {
+      return {
+        task: null,
+        error: `Unknown review agent: '${agentId}' has not registered with the system.
+` + `  A real review sub-agent must register first by running any aitasks command
+` + `  (e.g. aitasks heartbeat --agent ${agentId}) before it can approve a review.`
+      };
+    }
   }
   const updated = updateTask(taskId, { status: "done", completed_at: Date.now() });
   logEvent({ task_id: taskId, agent_id: agentId, event_type: "completed", payload: {} });
@@ -41082,6 +41135,7 @@ var startCommand = new Command("start").description("Start working on task(s) (t
     console.error("");
     process.exit(1);
   }
+  const reviewRequired = getReviewRequired();
   const results = [];
   let allSuccess = true;
   for (const taskId of resolvedIds) {
@@ -41095,18 +41149,21 @@ var startCommand = new Command("start").description("Start working on task(s) (t
       }
       continue;
     }
-    results.push({ id: taskId, success: true });
+    results.push({ id: taskId, success: true, review_required: reviewRequired });
     if (!json) {
       console.log("");
       console.log(source_default.green("  \u25B6") + `  Started ${source_default.bold(task.id)} \u2014 ${task.title}`);
       if (task.acceptance_criteria.length > 0) {
         console.log(source_default.dim(`     ${task.acceptance_criteria.length} acceptance criteria to verify before done`));
       }
+      if (reviewRequired) {
+        console.log(source_default.yellow("     \u26A0 ") + source_default.bold("Review required.") + source_default.dim(` When done: aitasks review ${task.id} \u2192 spawn review sub-agent \u2192 aitasks done ${task.id}`));
+      }
       console.log(source_default.dim(`     Add notes as you go: aitasks note ${task.id} "<your note>"`));
     }
   }
   if (json) {
-    return jsonOut(allSuccess, { results });
+    return jsonOut(allSuccess, { results, review_required: reviewRequired });
   }
   console.log("");
   if (!allSuccess) {
@@ -41278,6 +41335,7 @@ var reviewCommand = new Command("review").description("Request human review for
     console.error("");
     process.exit(1);
   }
+  const reviewRequired = getReviewRequired();
   const results = [];
   let allSuccess = true;
   for (const taskId of resolvedIds) {
@@ -41291,13 +41349,43 @@ var reviewCommand = new Command("review").description("Request human review for
       }
       continue;
     }
-    results.push({ id: taskId, success: true });
+    if (reviewRequired) {
+      results.push({
+        id: taskId,
+        success: true,
+        status: "review",
+        next_action: `REQUIRED: Spawn a review sub-agent immediately with a DIFFERENT agent ID (e.g. review-${taskId.toLowerCase()}). Do NOT call aitasks done yourself \u2014 the system will block self-approval.`,
+        review_commands: {
+          approve: `aitasks done ${taskId} --agent review-${taskId.toLowerCase()}`,
+          reject: `aitasks reject ${taskId} --reason "<specific feedback>" --agent review-${taskId.toLowerCase()}`
+        }
+      });
+    } else {
+      results.push({ id: taskId, success: true, status: "review" });
+    }
     if (!json) {
       console.log("");
       console.log(source_default.magenta("  \u25C8") + `  ${source_default.bold(task.id)} submitted for review`);
-      console.log(source_default.dim(`     Spawn a review sub-agent to inspect the implementation.`));
-      console.log(source_default.dim(`     Approve: aitasks done ${task.id} --agent <review-agent-id>`));
-      console.log(source_default.dim(`     Reject:  aitasks reject ${task.id} --reason "<feedback>"`));
+      if (reviewRequired) {
+        console.log(source_default.yellow("  \u26A0 ") + source_default.bold(" This task is NOT complete yet."));
+        console.log("");
+        console.log(`  You MUST ${source_default.bold("immediately spawn a review sub-agent")} to inspect the implementation.`);
+        console.log(source_default.dim("  The task remains incomplete until the review agent moves it to done."));
+        console.log("");
+        console.log(source_default.yellow("  \u2716 ") + source_default.bold("STOP \u2014 do NOT run `aitasks done` yourself."));
+        console.log(source_default.dim("  The system will block self-approval. A separate agent must do the review."));
+        console.log("");
+        console.log(source_default.dim("  Review sub-agent steps:"));
+        console.log(source_default.dim(`  1. Spawn a sub-agent with a unique agent ID, e.g. review-${task.id.toLowerCase()}`));
+        console.log(source_default.dim(`  2. Sub-agent registers:  aitasks heartbeat --agent review-${task.id.toLowerCase()}`));
+        console.log(source_default.dim(`  3. Sub-agent examines implementation and verifies all acceptance criteria`));
+        console.log(source_default.dim(`  4. Approve:  aitasks done ${task.id} --agent review-${task.id.toLowerCase()}`));
+        console.log(source_default.dim(`     Reject:   aitasks reject ${task.id} --reason "<feedback>" --agent review-${task.id.toLowerCase()}`));
+        console.log(source_default.dim(`  The system will reject approval from unregistered or self-approving agents.`));
+      } else {
+        console.log(source_default.dim(`     Approve: aitasks done ${task.id} --agent <review-agent-id>`));
+        console.log(source_default.dim(`     Reject:  aitasks reject ${task.id} --reason "<feedback>"`));
+      }
     }
   }
   if (json) {
@@ -41378,9 +41466,10 @@ var nextCommand = new Command("next").description("Show the next best task to wo
   }
   const aid = opts.claim ? requireAgentId(opts.agent, "next --claim") : agentId(opts.agent) ?? undefined;
   const task = getNextTask(aid);
+  const reviewRequired = getReviewRequired();
   if (!task) {
     if (json)
-      return jsonOut(true, null);
+      return jsonOut(true, { task: null, review_required: reviewRequired });
     console.log("");
     console.log(source_default.dim("  No ready tasks available. Check backlog with: aitasks list"));
     console.log("");
@@ -41403,17 +41492,24 @@ var nextCommand = new Command("next").description("Show the next best task to wo
     }
     const updatedTask = startResult.task;
     if (json)
-      return jsonOut(true, updatedTask);
+      return jsonOut(true, { ...updatedTask, review_required: reviewRequired });
     console.log("");
     console.log(source_default.green("  \u2713") + `  Claimed and started ${source_default.bold(updatedTask.id)}: ${updatedTask.title}`);
     console.log(source_default.dim(`     Priority: ${updatedTask.priority}  \xB7  Type: ${updatedTask.type}`));
     console.log(source_default.dim(`     Agent: ${aid}`));
+    if (reviewRequired) {
+      console.log("");
+      console.log(source_default.yellow("  \u26A0 ") + source_default.bold(" Review enforcement is ON.") + source_default.dim(" When done: aitasks review \u2192 spawn review sub-agent \u2192 aitasks done"));
+    }
     console.log("");
     return;
   }
   if (json)
-    return jsonOut(true, task);
+    return jsonOut(true, { ...task, review_required: reviewRequired });
   console.log(renderTaskDetail(task));
+  if (reviewRequired) {
+    console.log(source_default.yellow("  \u26A0 ") + source_default.bold(" Review enforcement is ON.") + source_default.dim(" When done: aitasks review \u2192 spawn review sub-agent \u2192 aitasks done"));
+  }
   console.log(source_default.dim(`  Claim it: aitasks claim ${task.id} --agent <your-id>`));
   console.log("");
 });
@@ -43222,4 +43318,4 @@ program2.parseAsync(process.argv).catch((err) => {
   process.exit(1);
 });
 
-//# debugId=B0EAB2DE4FE47CF564756E2164756E21
+//# debugId=62CCA2B3357C2C9A64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aitasks",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "CLI task management tool built for AI agents",
   "type": "module",
   "bin": {