aitasks 1.3.1 → 1.3.2

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.2",
     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:
@@ -29414,7 +29421,8 @@ ${reviewRequired ? `3. Submit for review \u2014 you CANNOT mark done directly:
    aitasks review TASK-001 --agent $AITASKS_AGENT_ID
    \`\`\`
 
-4. Spawn a review sub-agent to inspect the implementation and either:
+4. **IMMEDIATELY spawn a review sub-agent** \u2014 do NOT move to other tasks until review resolves.
+   The task is still incomplete. The review sub-agent must either:
    - **Approve** (moves task to done):
      \`\`\`bash
      aitasks done TASK-001 --agent <review-agent-id>
@@ -29424,15 +29432,14 @@ ${reviewRequired ? `3. Submit for review \u2014 you CANNOT mark done directly:
      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):
+5. If rejected: address the feedback, re-check criteria, and repeat from step 3.
+
+> 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 done TASK-001 --agent $AITASKS_AGENT_ID
    \`\`\`
 
-   If review is needed:
-   \`\`\`bash
-   aitasks review 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 +29453,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 +29471,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. Do NOT work on other tasks until the review resolves. A task is only complete when its status is \`done\`.` : ""}
 
 ---
 
@@ -29488,8 +29496,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 +29592,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"))) {
@@ -41082,6 +41103,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 +41117,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 +41303,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 +41317,37 @@ 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. This task is NOT complete until the review agent approves it.",
+        review_commands: {
+          approve: `aitasks done ${taskId} --agent <review-agent-id>`,
+          reject: `aitasks reject ${taskId} --reason "<specific feedback>" --agent <review-agent-id>`
+        }
+      });
+    } 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.dim("  Review sub-agent steps:"));
+        console.log(source_default.dim(`  1. Examine implementation and verify all acceptance criteria`));
+        console.log(source_default.dim(`  2. Approve:  aitasks done ${task.id} --agent <review-agent-id>`));
+        console.log(source_default.dim(`     Reject:   aitasks reject ${task.id} --reason "<feedback>" --agent <review-agent-id>`));
+      } 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 +41428,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 +41454,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 +43280,4 @@ program2.parseAsync(process.argv).catch((err) => {
   process.exit(1);
 });
 
-//# debugId=B0EAB2DE4FE47CF564756E2164756E21
+//# debugId=3AB57D11F115EBBB64756E2164756E21

package/package.json

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