aitasks 1.3.0 → 1.3.2

package/README.md

@@ -72,6 +72,7 @@ export AITASKS_JSON=true
 | Command | Description |
 |---|---|
 | `aitasks init` | Initialize a task database in the current project |
+| `aitasks init --with-review` | Initialize with review enforcement (agents cannot mark done without a passing review) |
 | `aitasks onboard` | Print or inject agent protocol instructions into CLAUDE.md / AGENTS.md |
 
 ### Task Discovery
@@ -79,7 +80,7 @@ export AITASKS_JSON=true
 | Command | Description |
 |---|---|
 | `aitasks list` | List all tasks, sorted by priority |
-| `aitasks list --status ready` | Filter by status (`ready`, `in_progress`, `done`, `blocked`, `needs_review`) |
+| `aitasks list --status ready` | Filter by status (`ready`, `in_progress`, `blocked`, `review`, `done`) |
 | `aitasks next` | Show the highest-priority unblocked ready task |
 | `aitasks next --claim --agent <id>` | Auto-claim and start the best task |
 | `aitasks show <id>` | Full detail on a specific task (includes time tracking) |
@@ -96,9 +97,9 @@ export AITASKS_JSON=true
 | `aitasks start <id...> --agent <id>` | Begin active work on task(s) |
 | `aitasks note <id> <text>` | Add an implementation note |
 | `aitasks check <id> <n> --evidence <text>` | Verify acceptance criterion n |
-| `aitasks done <id...> --agent <id>` | Mark task(s) complete (all criteria must be verified) |
-| `aitasks review <id...> --agent <id>` | Submit for human review |
-| `aitasks reject <id> --reason <text>` | Reject and send back to in_progress |
+| `aitasks done <id...> --agent <id>` | Mark task(s) complete (all criteria must be verified; must be in `review` status if enforcement is on) |
+| `aitasks review <id...> --agent <id>` | Submit task(s) for review (moves to `review` status) |
+| `aitasks reject <id> --reason <text>` | Reject a task in review, send it back to `in_progress` with feedback |
 | `aitasks unclaim <id> --agent <id>` | Release a task back to the pool |
 | `aitasks undo <id>` | Undo the last action on a task |
 | `aitasks delete <id...>` | Delete task(s) - does not require claiming first |
@@ -151,12 +152,53 @@ When you run `aitasks init`, it automatically injects a full agent protocol into
 You can also inject/view it manually:
 
 ```sh
-aitasks onboard               # print to stdout
+aitasks onboard               # print to stdout (reflects current review_required setting)
 aitasks onboard --append      # append to detected agent file
 aitasks onboard --file MY.md  # append to a specific file
 aitasks onboard --json        # output as JSON string
 ```
 
+The injected instructions automatically adapt to the project's review enforcement setting — if `--with-review` is enabled, agents receive the full review workflow (with `aitasks review`, sub-agent approval, and `aitasks reject`) instead of the standard completion flow.
+
+---
+
+## Review Enforcement
+
+Enable a mandatory review gate so agents cannot mark tasks done without an explicit approval step:
+
+```sh
+# Enable at init time
+aitasks init --with-review
+
+# Enable on an existing project (also replaces the agent instructions file with review-aware version)
+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 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
+   ```
+   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
+     ```
+   - **Rejects** — sends it back to `in_progress` with feedback:
+     ```sh
+     aitasks reject TASK-001 --reason "Missing error handling for 404 case" --agent review-agent
+     ```
+4. If rejected, the original agent addresses the feedback, re-verifies criteria, and repeats from step 2.
+
+**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.
+
 ---
 
 ## Data Storage

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.0",
+    version: "1.3.2",
     description: "CLI task management tool built for AI agents",
     type: "module",
     bin: {
@@ -29071,7 +29071,16 @@ import { join as join3 } from "path";
 import { existsSync as existsSync3 } from "fs";
 
 // src/db/schema.ts
-var SCHEMA_VERSION = 1;
+var SCHEMA_VERSION = 2;
+function runMigrations(db) {
+  const row = db.query(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
+  const current = row ? parseInt(row.value, 10) : 1;
+  if (current < 2) {
+    db.exec(`UPDATE tasks SET status = 'review' WHERE status = 'needs_review'`);
+    db.exec(`INSERT OR IGNORE INTO meta (key, value) VALUES ('review_required', 'false')`);
+    db.exec(`UPDATE meta SET value = '2' WHERE key = 'schema_version'`);
+  }
+}
 function initializeSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS meta (
@@ -29126,6 +29135,7 @@ function initializeSchema(db) {
   insert.run("last_task_number", "0");
   insert.run("schema_version", String(SCHEMA_VERSION));
   insert.run("initialized_at", String(Date.now()));
+  insert.run("review_required", "false");
 }
 
 // src/db/backup.ts
@@ -29240,10 +29250,20 @@ function getDb() {
   const db = new Database(dbPath);
   applyPragmas(db);
   checkIntegrity(db, taskieDir);
+  runMigrations(db);
   registerCleanup();
   _db = db;
   return db;
 }
+function getReviewRequired() {
+  const db = getDb();
+  const row = db.query(`SELECT value FROM meta WHERE key = 'review_required'`).get();
+  return row?.value === "true";
+}
+function setReviewRequired(enabled) {
+  const db = getDb();
+  db.run(`INSERT OR REPLACE INTO meta (key, value) VALUES ('review_required', ?)`, [enabled ? "true" : "false"]);
+}
 function createFreshDb(taskieDir) {
   const dbPath = join3(taskieDir, "db.sqlite");
   const db = new Database(dbPath);
@@ -29265,11 +29285,17 @@ import { join as join4 } from "path";
 // src/utils/instructions.ts
 var INSTRUCTIONS_START_MARKER = "<!-- aitasks:instructions -->";
 var INSTRUCTIONS_END_MARKER = "<!-- aitasks:instructions:end -->";
-function getAgentInstructions(version) {
+function getAgentInstructions(version, opts = {}) {
+  const reviewRequired = opts.reviewRequired ?? false;
   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.
 
@@ -29326,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
@@ -29372,7 +29398,9 @@ aitasks deps TASK-001    # Shows what this task is blocked by and what it blocks
 
 ---
 
-### Completing a Task
+### 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.
 
@@ -29388,16 +29416,31 @@ You MUST verify every acceptance criterion before marking done.
    aitasks check TASK-001 2 --evidence "integration test suite passes: 12/12 green"
    \`\`\`
 
-3. Mark done (will FAIL if any criterion is unchecked):
+${reviewRequired ? `3. Submit for review \u2014 you CANNOT mark done directly:
    \`\`\`bash
-   aitasks done TASK-001 --agent $AITASKS_AGENT_ID
+   aitasks review TASK-001 --agent $AITASKS_AGENT_ID
    \`\`\`
 
-   If human review is needed instead:
+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>
+     \`\`\`
+   - **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.
+
+> 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.`}
+
 ---
 
 ### Undoing Mistakes
@@ -29410,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
 
@@ -29428,13 +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.
+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\`.` : ""}
 
 ---
 
@@ -29451,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
@@ -29481,13 +29527,17 @@ function findExistingAgentFile(projectRoot) {
   }
   return null;
 }
-function injectOrCreateAgentFile(projectRoot, version) {
-  const instructions = getAgentInstructions(version);
+function injectOrCreateAgentFile(projectRoot, version, reviewRequired = false, force = false) {
+  const instructions = getAgentInstructions(version, { reviewRequired });
   const existing = findExistingAgentFile(projectRoot);
   if (existing) {
     const content = readFileSync2(existing, "utf8");
     if (instructionsAlreadyPresent(content)) {
-      return { filePath: existing, action: "skipped" };
+      if (!force)
+        return { filePath: existing, action: "skipped" };
+      const replaced = replaceInstructionsBlock(content, instructions);
+      writeFileSync2(existing, replaced, "utf8");
+      return { filePath: existing, action: "appended" };
     }
     const separator = content.endsWith(`
 `) ? `
@@ -29503,8 +29553,25 @@ function injectOrCreateAgentFile(projectRoot, version) {
 `, "utf8");
   return { filePath: newPath, action: "created" };
 }
-function appendToSpecificFile(filePath, version) {
-  const instructions = getAgentInstructions(version);
+function replaceInstructionsBlock(content, newInstructions) {
+  const start = content.indexOf(INSTRUCTIONS_START_MARKER);
+  const end = content.indexOf(INSTRUCTIONS_END_MARKER);
+  if (start === -1 || end === -1)
+    return content;
+  const before = content.slice(0, start).replace(/\n+$/, "");
+  const after = content.slice(end + INSTRUCTIONS_END_MARKER.length).replace(/^\n+/, "");
+  const sep = before.length > 0 ? `
+
+` : "";
+  const tail = after.length > 0 ? `
+
+` + after : `
+`;
+  return before + sep + newInstructions + `
+` + tail;
+}
+function appendToSpecificFile(filePath, version, reviewRequired = false) {
+  const instructions = getAgentInstructions(version, { reviewRequired });
   if (!existsSync4(filePath)) {
     writeFileSync2(filePath, instructions + `
 `, "utf8");
@@ -29525,27 +29592,51 @@ function appendToSpecificFile(filePath, version) {
 }
 
 // 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").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"))) {
     console.log(source_default.yellow("  AITasks is already initialized in this project."));
     console.log(source_default.dim(`  DB: ${join5(taskieDir, "db.sqlite")}`));
+    if (opts.withReview) {
+      setReviewRequired(true);
+      console.log(source_default.green("  \u2713") + "  Review enforcement enabled.");
+    }
     if (!opts.skipAgentFile) {
-      const result = injectOrCreateAgentFile(root, getVersion());
+      const result = injectOrCreateAgentFile(root, getVersion(), !!opts.withReview, !!opts.withReview);
       printAgentFileResult(result);
     }
     return;
   }
   mkdirSync(taskieDir, { recursive: true });
   createFreshDb(taskieDir);
+  if (opts.withReview) {
+    setReviewRequired(true);
+  }
   console.log("");
   console.log(source_default.green("  \u2713") + source_default.bold("  AITasks initialized"));
   console.log(source_default.dim(`     Project root : ${root}`));
   console.log(source_default.dim(`     Database      : ${join5(taskieDir, "db.sqlite")}`));
+  if (opts.withReview) {
+    console.log(source_default.magenta("  \u25C8") + source_default.bold("  Review enforcement enabled"));
+    console.log(source_default.dim("     Agents must submit tasks for review before marking done."));
+    console.log(source_default.dim("     Use: aitasks review <id>  \u2192  review sub-agent  \u2192  aitasks done <id>"));
+  }
   console.log("");
   if (!opts.skipAgentFile) {
-    const result = injectOrCreateAgentFile(root, getVersion());
+    const result = injectOrCreateAgentFile(root, getVersion(), !!opts.withReview);
     printAgentFileResult(result);
   }
   console.log(source_default.dim("  Run `aitasks create` to add your first task."));
@@ -30156,7 +30247,7 @@ var PRIORITY_ORDER = `CASE priority
   WHEN 'low'      THEN 3 END`;
 var STATUS_ORDER = `CASE status
   WHEN 'in_progress'  THEN 0
-  WHEN 'needs_review' THEN 1
+  WHEN 'review'       THEN 1
   WHEN 'blocked'      THEN 2
   WHEN 'ready'        THEN 3
   WHEN 'backlog'      THEN 4
@@ -30357,6 +30448,17 @@ 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.
+` + `  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."
+    };
+  }
   const updated = updateTask(taskId, { status: "done", completed_at: Date.now() });
   logEvent({ task_id: taskId, agent_id: agentId, event_type: "completed", payload: {} });
   const pendingRows = db.query(`SELECT id, blocked_by FROM tasks WHERE status != 'done'`).all();
@@ -30442,7 +30544,7 @@ function reviewTask(taskId, agentId) {
   if (task.status !== "in_progress") {
     return { task: null, error: "Task must be in_progress to request review" };
   }
-  const updated = updateTask(taskId, { status: "needs_review" });
+  const updated = updateTask(taskId, { status: "review" });
   logEvent({ task_id: taskId, agent_id: agentId, event_type: "review_requested", payload: {} });
   return { task: updated };
 }
@@ -30450,8 +30552,8 @@ function rejectTask(taskId, reason, agentId) {
   const task = getTask(taskId);
   if (!task)
     return { task: null, error: "Task not found" };
-  if (task.status !== "needs_review") {
-    return { task: null, error: "Task must be in needs_review status to reject" };
+  if (task.status !== "review") {
+    return { task: null, error: "Task must be in review status to reject" };
   }
   updateTask(taskId, { status: "in_progress" });
   addImplementationNote(taskId, `REVIEW REJECTED: ${reason}`, agentId ?? "human");
@@ -38533,7 +38635,7 @@ var STATUS_ICON = {
   ready: "\u25CE",
   in_progress: "\u25B6",
   blocked: "\u2298",
-  needs_review: "\u25C8",
+  review: "\u25C8",
   done: "\u2713"
 };
 
@@ -40114,7 +40216,7 @@ var STATUS_COLORS = {
   ready: "blue",
   in_progress: "yellow",
   blocked: "#FF5C5C",
-  needs_review: "magenta",
+  review: "magenta",
   done: "green"
 };
 var PRIORITY_COLORS = {
@@ -40526,7 +40628,7 @@ var STATUS_COLORS2 = {
   ready: "blue",
   in_progress: "yellow",
   blocked: "#FF5C5C",
-  needs_review: "magenta",
+  review: "magenta",
   done: "green"
 };
 var PRIORITY_COLORS2 = {
@@ -41001,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) {
@@ -41014,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) {
@@ -41197,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) {
@@ -41210,12 +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(`     A human can approve with: aitasks done ${task.id}`));
-      console.log(source_default.dim(`     Or reject with: aitasks reject ${task.id} --reason "<reason>"`));
+      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) {
@@ -41296,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("");
@@ -41321,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("");
 });
@@ -41364,6 +41504,9 @@ var updateCommand = new Command("update").description("Update task fields").argu
   if (Object.keys(changes).length === 0) {
     exitError("No changes specified. Use --help to see available options.", json);
   }
+  if (opts.status === "done" && getReviewRequired() && task.status !== "review") {
+    exitError("Review required: use `aitasks done` which enforces the review gate.\n" + "  Submit for review first: aitasks review <taskId> --agent $AITASKS_AGENT_ID", json);
+  }
   const updated = updateTask(id, changes);
   if (json)
     return jsonOut(true, updated);
@@ -41387,7 +41530,7 @@ var STATUS_COLORS3 = {
   ready: "blue",
   in_progress: "yellow",
   blocked: "#FF5C5C",
-  needs_review: "magenta",
+  review: "magenta",
   done: "green"
 };
 var PRIORITY_COLORS3 = {
@@ -41398,11 +41541,11 @@ var PRIORITY_COLORS3 = {
 };
 function buildTree(tasks) {
   const sorted = [...tasks].sort((a2, b2) => a2.id.localeCompare(b2.id));
-  const inProgressIds = new Set(sorted.filter((t) => t.status === "in_progress").map((t) => t.id));
+  const inProgressIds = new Set(sorted.filter((t) => t.status === "in_progress" || t.status === "review").map((t) => t.id));
   const doneIds = new Set(sorted.filter((t) => t.status === "done").map((t) => t.id));
   const shownIds = new Set;
   const items = [];
-  const ipCount = sorted.filter((t) => t.status === "in_progress").length;
+  const ipCount = sorted.filter((t) => t.status === "in_progress" || t.status === "review").length;
   const doneCount = sorted.filter((t) => t.status === "done").length;
   function push(task, indent, isLastSibling, section, showHeader) {
     items.push({
@@ -41416,13 +41559,13 @@ function buildTree(tasks) {
     shownIds.add(task.id);
   }
   let firstIp = true;
-  for (const task of sorted.filter((t) => t.status === "in_progress" && !t.parent_id)) {
+  for (const task of sorted.filter((t) => (t.status === "in_progress" || t.status === "review") && !t.parent_id)) {
     push(task, 0, false, "in_progress", firstIp);
     firstIp = false;
     const subs = sorted.filter((t) => t.parent_id === task.id);
     subs.forEach((sub, i) => push(sub, 1, i === subs.length - 1, "in_progress", false));
   }
-  for (const task of sorted.filter((t) => t.status === "in_progress" && !!t.parent_id)) {
+  for (const task of sorted.filter((t) => (t.status === "in_progress" || t.status === "review") && !!t.parent_id)) {
     if (!shownIds.has(task.id)) {
       push(task, 0, false, "in_progress", firstIp);
       firstIp = false;
@@ -41666,7 +41809,7 @@ var RightPane = ({ task, width, height, scrollOffset, metricsRef }) => {
     }, i, true, undefined, this))
   }, undefined, false, undefined, this);
 };
-var PICKER_STATUSES = ["backlog", "ready", "in_progress", "blocked", "needs_review", "done"];
+var PICKER_STATUSES = ["backlog", "ready", "in_progress", "blocked", "review", "done"];
 var StatusPicker = ({ task }) => /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
   flexDirection: "column",
   paddingLeft: 2,
@@ -41877,7 +42020,7 @@ var TreeBoardComponent = ({ getTasks }) => {
         "2": "ready",
         "3": "in_progress",
         "4": "blocked",
-        "5": "needs_review",
+        "5": "review",
         "6": "done"
       };
       const newStatus = statusMap[input];
@@ -42274,10 +42417,10 @@ var STATUS_LABELS = {
   ready: "READY",
   in_progress: "IN PROGRESS",
   blocked: "BLOCKED",
-  needs_review: "NEEDS REVIEW",
+  review: "REVIEW",
   done: "DONE"
 };
-var ALL_STATUSES = ["in_progress", "needs_review", "ready", "blocked", "backlog", "done"];
+var ALL_STATUSES = ["in_progress", "review", "ready", "blocked", "backlog", "done"];
 var StaticCard = ({ task }) => {
   const priColor = PRIORITY_COLORS3[task.priority] ?? "gray";
   return /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
@@ -42544,13 +42687,14 @@ var exportCommand = new Command("export").description("Export all task data").op
 // src/commands/onboard.ts
 var VERSION = "1.0.0";
 var onboardCommand = new Command("onboard").description("Print or inject agent protocol instructions").option("--append", "Auto-detect and append to CLAUDE.md/AGENTS.md/GEMINI.md").option("--file <path>", "Append to a specific file").option("--json", "Output the instructions as a JSON string").action((opts) => {
-  const instructions = getAgentInstructions(VERSION);
+  const reviewRequired = isInitialized() ? getReviewRequired() : false;
+  const instructions = getAgentInstructions(VERSION, { reviewRequired });
   if (opts.json) {
     console.log(JSON.stringify({ instructions }, null, 2));
     return;
   }
   if (opts.file) {
-    const result2 = appendToSpecificFile(opts.file, VERSION);
+    const result2 = appendToSpecificFile(opts.file, VERSION, reviewRequired);
     const rel = opts.file.replace(process.cwd() + "/", "");
     switch (result2.action) {
       case "created":
@@ -42567,7 +42711,7 @@ var onboardCommand = new Command("onboard").description("Print or inject agent p
   }
   if (opts.append) {
     const root = findProjectRoot();
-    const result2 = injectOrCreateAgentFile(root, VERSION);
+    const result2 = injectOrCreateAgentFile(root, VERSION, reviewRequired);
     const rel = result2.filePath.replace(process.cwd() + "/", "");
     switch (result2.action) {
       case "created":
@@ -42738,7 +42882,7 @@ function getStatusIcon(status) {
     ready: "\u25D0",
     in_progress: "\u25B6",
     blocked: "\u2298",
-    needs_review: "\u25C8",
+    review: "\u25C8",
     done: "\u2713"
   };
   return icons[status] || "\u25CB";
@@ -42778,7 +42922,7 @@ var searchCommand = new Command("search").description("Full-text search across t
     const statusIcon = getStatusIcon2(task.status);
     const priColor = getPriorityColor(task.priority);
     console.log("");
-    console.log(`${source_default.bold.white(task.id)}  ` + `${priColor(task.priority[0].toUpperCase())}  ` + `${statusIcon} ` + highlightMatches(task.title, searchTerms));
+    console.log(`${source_default.bold.white(task.id)}  ` + `${priColor((task.priority[0] ?? "?").toUpperCase())}  ` + `${statusIcon} ` + highlightMatches(task.title, searchTerms));
     const context = getSearchContext(task, searchTerms);
     if (context) {
       console.log(source_default.dim(`  ${context}`));
@@ -42837,7 +42981,7 @@ function getStatusIcon2(status) {
     ready: source_default.blue("\u25D0"),
     in_progress: source_default.yellow("\u25B6"),
     blocked: source_default.hex("#FF5C5C")("\u2298"),
-    needs_review: source_default.magenta("\u25C8"),
+    review: source_default.magenta("\u25C8"),
     done: source_default.green("\u2713")
   };
   return icons[status] || "\u25CB";
@@ -42927,25 +43071,26 @@ var undoCommand = new Command("undo").description("Undo the last action on a tas
   }
 });
 function undoComplete(task) {
+  const newStatus = getReviewRequired() ? "review" : "in_progress";
   updateTask(task.id, {
-    status: "in_progress",
+    status: newStatus,
     completed_at: null
   });
   return {
     success: true,
-    message: `${task.id} reverted from done to in_progress`,
-    data: { task: task.id, previousStatus: "done", newStatus: "in_progress" }
+    message: `${task.id} reverted from done to ${newStatus}`,
+    data: { task: task.id, previousStatus: "done", newStatus }
   };
 }
 function undoReviewRequested(task) {
-  if (task.status !== "needs_review") {
-    return { success: false, message: `${task.id} is not in needs_review status` };
+  if (task.status !== "review") {
+    return { success: false, message: `${task.id} is not in review status` };
   }
   updateTask(task.id, { status: "in_progress" });
   return {
     success: true,
-    message: `${task.id} reverted from needs_review to in_progress`,
-    data: { task: task.id, previousStatus: "needs_review", newStatus: "in_progress" }
+    message: `${task.id} reverted from review to in_progress`,
+    data: { task: task.id, previousStatus: "review", newStatus: "in_progress" }
   };
 }
 function undoStarted(task) {
@@ -43135,4 +43280,4 @@ program2.parseAsync(process.argv).catch((err) => {
   process.exit(1);
 });
 
-//# debugId=26C003F11D02306964756E2164756E21
+//# debugId=3AB57D11F115EBBB64756E2164756E21

package/package.json

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