@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/cli/commands/task.js

@@ -1,12 +1,16 @@
-import chalk from 'chalk';
-import * as path from 'node:path';
-import { initContext, loadAllTasks, loadAllItems, saveTask, deleteTask, createTask, createNote, createTodo, syncSpecImplementationStatus, ReferenceIndex, checkSlugUniqueness, getAuthor, } from '../../parser/index.js';
-import { commitIfShadow } from '../../parser/shadow.js';
-import { output, formatTaskDetails, success, error, warn, info, isJsonMode, } from '../output.js';
-import { formatCommitGuidance, printCommitGuidance } from '../../utils/commit.js';
-import { alignmentCheck, errors } from '../../strings/index.js';
-import { executeBatchOperation, formatBatchOutput } from '../batch.js';
-import { EXIT_CODES } from '../exit-codes.js';
+import chalk from "chalk";
+import { markMutating } from "../command-annotations.js";
+import { checkSlugUniqueness, createNote, createTask, createTodo, deleteTask, getAuthor, initContext, loadAllItems, loadAllTasks, ReferenceIndex, saveTask, scanTestCoverage, syncSpecImplementationStatus, } from "../../parser/index.js";
+import { commitIfShadow } from "../../parser/shadow.js";
+import { alignmentCheck, errors } from "../../strings/index.js";
+import { formatCommitGuidance, printCommitGuidance, } from "../../utils/commit.js";
+import { executeBatchOperation, formatBatchOutput } from "../batch.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { parseTagsArray } from "../parse-utils.js";
+import { annotateNotesWithSuperseded, error, formatTaskDetails, info, isJsonMode, output, success, warn, } from "../output.js";
+import { parseIntOption, validateEnumOption, validateSpecRef, } from "../validators.js";
+import { addListOptions, listTasksAction } from "./tasks.js";
+import { findClosestCommand } from "../suggest.js";
 /**
  * Find a task by reference with detailed error reporting.
  * Returns the task or exits with appropriate error.
@@ -15,18 +19,18 @@ function resolveTaskRef(ref, tasks, index) {
     const result = index.resolve(ref);
     if (!result.ok) {
         switch (result.error) {
-            case 'not_found':
+            case "not_found":
                 error(errors.reference.taskNotFound(ref));
                 break;
-            case 'ambiguous':
+            case "ambiguous":
                 error(errors.reference.ambiguous(ref));
                 for (const candidate of result.candidates) {
-                    const task = tasks.find(t => t._ulid === candidate);
-                    const slug = task?.slugs[0] || '';
-                    console.error(`  - ${index.shortUlid(candidate)} ${slug ? `(${slug})` : ''}`);
+                    const task = tasks.find((t) => t._ulid === candidate);
+                    const slug = task?.slugs[0] || "";
+                    console.error(`  - ${index.shortUlid(candidate)} ${slug ? `(${slug})` : ""}`);
                 }
                 break;
-            case 'duplicate_slug':
+            case "duplicate_slug":
                 error(errors.reference.slugMapsToMultiple(ref));
                 for (const candidate of result.candidates) {
                     console.error(`  - ${index.shortUlid(candidate)}`);
@@ -37,7 +41,7 @@ function resolveTaskRef(ref, tasks, index) {
         process.exit(EXIT_CODES.NOT_FOUND);
     }
     // Check if it's actually a task
-    const task = tasks.find(t => t._ulid === result.ulid);
+    const task = tasks.find((t) => t._ulid === result.ulid);
     if (!task) {
         error(errors.reference.notTask(ref));
         // AC: @cli-exit-codes consistent-usage - NOT_FOUND for missing resources
@@ -55,20 +59,20 @@ function resolveTaskRefForBatch(ref, tasks, index) {
     if (!result.ok) {
         let errorMsg;
         switch (result.error) {
-            case 'not_found':
+            case "not_found":
                 errorMsg = `Reference "${ref}" not found`;
                 break;
-            case 'ambiguous':
+            case "ambiguous":
                 errorMsg = `Reference "${ref}" is ambiguous (matches ${result.candidates.length} items)`;
                 break;
-            case 'duplicate_slug':
+            case "duplicate_slug":
                 errorMsg = `Slug "${ref}" maps to multiple items`;
                 break;
         }
         return { task: null, error: errorMsg };
     }
     // Check if it's actually a task
-    const task = tasks.find(t => t._ulid === result.ulid);
+    const task = tasks.find((t) => t._ulid === result.ulid);
     if (!task) {
         return { task: null, error: `Reference "${ref}" is not a task` };
     }
@@ -79,7 +83,7 @@ function resolveTaskRefForBatch(ref, tasks, index) {
  * Used by both single-ref and batch modes of task set.
  * AC: @spec-task-set-batch ac-1, ac-2, ac-4, ac-5
  */
-async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index, options) {
+async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index, options) {
     try {
         // Check slug uniqueness if adding a new slug
         if (options.slug) {
@@ -96,7 +100,7 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
         const changes = [];
         if (options.title) {
             updatedTask.title = options.title;
-            changes.push('title');
+            changes.push("title");
         }
         if (options.specRef) {
             // Validate the spec ref exists and is a spec item
@@ -108,7 +112,7 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                 };
             }
             // Check it's not a task
-            const isTask = tasks.some(t => t._ulid === specResult.ulid);
+            const isTask = tasks.some((t) => t._ulid === specResult.ulid);
             if (isTask) {
                 return {
                     success: false,
@@ -116,7 +120,7 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                 };
             }
             updatedTask.spec_ref = options.specRef;
-            changes.push('spec_ref');
+            changes.push("spec_ref");
         }
         if (options.metaRef) {
             // Validate the meta ref exists and is a meta item
@@ -128,8 +132,8 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                 };
             }
             // Check if the resolved item is a meta item (not a spec item or task)
-            const isTask = tasks.some(t => t._ulid === metaRefResult.ulid);
-            const isSpecItem = items.some(i => i._ulid === metaRefResult.ulid);
+            const isTask = tasks.some((t) => t._ulid === metaRefResult.ulid);
+            const isSpecItem = items.some((i) => i._ulid === metaRefResult.ulid);
             if (isTask || isSpecItem) {
                 return {
                     success: false,
@@ -137,30 +141,68 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                 };
             }
             updatedTask.meta_ref = options.metaRef;
-            changes.push('meta_ref');
+            changes.push("meta_ref");
+        }
+        if (options.planRef !== undefined) {
+            // Handle 'null' string to clear plan_ref
+            if (options.planRef === "null") {
+                updatedTask.plan_ref = null;
+                changes.push("plan_ref: cleared");
+            }
+            else {
+                // First check if it's a task or spec item (wrong type)
+                const cleanRef = options.planRef.startsWith("@")
+                    ? options.planRef.slice(1)
+                    : options.planRef;
+                const isTask = tasks.some((t) => t.slugs.includes(cleanRef) ||
+                    t._ulid === cleanRef ||
+                    t._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+                const isSpecItem = items.some((i) => i.slugs.includes(cleanRef) ||
+                    i._ulid === cleanRef ||
+                    i._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+                if (isTask || isSpecItem) {
+                    return {
+                        success: false,
+                        error: `Reference "${options.planRef}" is not a plan`,
+                    };
+                }
+                // Now check if the plan exists
+                const { findPlanByRef } = await import("../../parser/plans.js");
+                const plan = await findPlanByRef(ctx, options.planRef);
+                if (!plan) {
+                    return {
+                        success: false,
+                        error: `Plan reference not found: ${options.planRef}`,
+                    };
+                }
+                updatedTask.plan_ref = options.planRef;
+                changes.push("plan_ref");
+            }
         }
         if (options.priority) {
-            const priority = parseInt(options.priority, 10);
-            if (isNaN(priority) || priority < 1 || priority > 5) {
-                return {
-                    success: false,
-                    error: 'Priority must be between 1 and 5',
-                };
+            const priorityResult = parseIntOption(options.priority, {
+                min: 1,
+                max: 5,
+                name: "Priority",
+            });
+            if (!priorityResult.ok) {
+                return { success: false, error: priorityResult.error };
             }
-            updatedTask.priority = priority;
-            changes.push('priority');
+            updatedTask.priority = priorityResult.value;
+            changes.push("priority");
         }
         if (options.slug) {
             if (!updatedTask.slugs.includes(options.slug)) {
                 updatedTask.slugs = [...updatedTask.slugs, options.slug];
-                changes.push('slug');
+                changes.push("slug");
             }
         }
         if (options.tag) {
-            const newTags = options.tag.filter((t) => !updatedTask.tags.includes(t));
+            const parsedTags = parseTagsArray(options.tag);
+            const newTags = parsedTags.filter((t) => !updatedTask.tags.includes(t));
             if (newTags.length > 0) {
                 updatedTask.tags = [...updatedTask.tags, ...newTags];
-                changes.push('tags');
+                changes.push("tags");
             }
         }
         if (options.dependsOn) {
@@ -173,9 +215,17 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                         error: errors.reference.depNotFound(depRef),
                     };
                 }
+                // Ensure the dependency is a task, not a spec item
+                const isTask = tasks.some((t) => t._ulid === depResult.ulid);
+                if (!isTask) {
+                    return {
+                        success: false,
+                        error: `Reference "${depRef}" is not a task`,
+                    };
+                }
             }
-            updatedTask.depends_on = options.dependsOn;
-            changes.push('depends_on');
+            updatedTask.depends_on = options.dependsOn.map((ref) => ref.startsWith("@") ? ref : `@${ref}`);
+            changes.push("depends_on");
         }
         // AC: @spec-task-clear-deps ac-1, ac-2 - Clear all dependencies
         if (options.clearDeps) {
@@ -183,14 +233,14 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
                 // AC: @spec-task-clear-deps ac-2 - No changes needed
                 return {
                     success: true,
-                    message: 'No changes: task has no dependencies to clear',
+                    message: "No changes: task has no dependencies to clear",
                 };
             }
             updatedTask.depends_on = [];
-            changes.push('depends_on');
+            changes.push("depends_on");
             // Add note documenting the change
             // AC: @task-set ac-author
-            const note = createNote(`Dependencies cleared (was: ${foundTask.depends_on.join(', ')})`, getAuthor());
+            const note = createNote(`Dependencies cleared (was: ${foundTask.depends_on.join(", ")})`, getAuthor(ctx.config?.identity?.author));
             updatedTask.notes = [...updatedTask.notes, note];
         }
         // AC: @task-automation-eligibility ac-5, ac-11, ac-12, ac-18
@@ -199,46 +249,43 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
         if (options.automation === false) {
             // --no-automation flag clears the automation status (AC: ac-12)
             delete updatedTask.automation;
-            changes.push('automation');
+            changes.push("automation");
         }
         else if (options.automation !== undefined) {
-            const validStatuses = ['eligible', 'needs_review', 'manual_only'];
-            if (!validStatuses.includes(options.automation)) {
-                return {
-                    success: false,
-                    error: `Invalid automation status: ${options.automation}. Must be one of: ${validStatuses.join(', ')}`,
-                };
+            const automationResult = validateEnumOption(options.automation, ["eligible", "needs_review", "manual_only"], "automation status");
+            if (!automationResult.ok) {
+                return { success: false, error: automationResult.error };
             }
             // AC: @task-automation-eligibility ac-18 - require reason for needs_review
-            if (options.automation === 'needs_review' && !options.reason) {
+            if (options.automation === "needs_review" && !options.reason) {
                 return {
                     success: false,
-                    error: 'Setting automation to needs_review requires --reason flag explaining why',
+                    error: "Setting automation to needs_review requires --reason flag explaining why",
                 };
             }
-            updatedTask.automation = options.automation;
-            changes.push('automation');
+            updatedTask.automation = automationResult.value;
+            changes.push("automation");
             // If reason provided, add a note documenting the change
             // AC: @task-set ac-author
             if (options.reason) {
-                const note = createNote(`Automation status set to ${options.automation}: ${options.reason}`, getAuthor());
+                const note = createNote(`Automation status set to ${automationResult.value}: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
                 updatedTask.notes = [...updatedTask.notes, note];
-                changes.push('note');
+                changes.push("note");
             }
         }
         // AC: @spec-task-set-batch ac-4 - Warn on no changes, don't fail
         if (changes.length === 0) {
             return {
                 success: true,
-                message: 'No changes specified',
+                message: "No changes specified",
                 data: { task: updatedTask },
             };
         }
         await saveTask(ctx, updatedTask);
-        await commitIfShadow(ctx.shadow, 'task-set', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(', '));
+        await commitIfShadow(ctx.shadow, "task-set", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(", "));
         return {
             success: true,
-            message: `Updated task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(', ')})`,
+            message: `Updated task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(", ")})`,
             data: { task: updatedTask },
         };
     }
@@ -254,20 +301,68 @@ async function setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index,
  */
 export function registerTaskCommands(program) {
     const task = program
-        .command('task')
-        .description('Operations on individual tasks');
+        .command("task")
+        .description("Operations on individual tasks")
+        .allowUnknownOption()
+        .allowExcessArguments();
+    // AC: @command-group-default-actions ac-bare-task, ac-unknown-subcommand
+    // Default action when no subcommand is given (e.g. `kspec task` or `kspec task --status pending`)
+    task.action(async (_options, cmd) => {
+        const { Command: Cmd } = await import("commander");
+        const listCmd = addListOptions(new Cmd("_list"));
+        listCmd.exitOverride();
+        try {
+            listCmd.parse(cmd.args, { from: "user" });
+        }
+        catch {
+            console.error(chalk.gray(`Run 'kspec task --help' to see available subcommands`));
+            process.exit(EXIT_CODES.ERROR);
+        }
+        // AC: @command-group-default-actions ac-unknown-subcommand
+        if (listCmd.args.length > 0) {
+            const unknownCmd = listCmd.args[0];
+            const subcommandNames = cmd.commands.map((c) => c.name());
+            const suggestion = findClosestCommand(unknownCmd, subcommandNames);
+            console.error(chalk.red(`error: unknown command 'task ${unknownCmd}'`));
+            if (suggestion) {
+                console.error(chalk.yellow(`Did you mean: kspec task ${suggestion}?`));
+            }
+            else {
+                console.error(chalk.gray(`Run 'kspec task --help' to see available subcommands`));
+            }
+            process.exit(EXIT_CODES.ERROR);
+        }
+        // AC: @command-group-default-actions ac-bare-with-options
+        await listTasksAction(listCmd.opts());
+    });
+    // kspec task list - alias for 'kspec tasks list'
+    task
+        .command("list")
+        .description("List all tasks (alias for 'kspec tasks list')")
+        .option("-s, --status <status>", "Filter by status")
+        .option("-t, --type <type>", "Filter by type")
+        .option("--tag <tag>", "Filter by tag")
+        .option("--meta-ref <ref>", "Filter by meta reference")
+        .option("-g, --grep <pattern>", "Search content with regex pattern")
+        .option("-v, --verbose", "Show more details")
+        .option("--full", "Show full details (notes, todos, timestamps)")
+        .option("--count", "Show only the count of matching tasks")
+        .action(async (options) => {
+        await listTasksAction(options);
+    });
     // kspec task get <ref>
     task
-        .command('get <ref>')
-        .description('Get task details')
-        .action(async (ref) => {
+        .command("get <ref>")
+        .description("Get task details")
+        .option("--all", "Show all notes including superseded ones")
+        .action(async (ref, options) => {
         try {
             const ctx = await initContext();
             const tasks = await loadAllTasks(ctx);
-            const items = await loadAllItems(ctx);
+            const _items = await loadAllItems(ctx);
             // Build all indexes including TraitIndex
             const { refIndex: index, traitIndex } = await (async () => {
-                const { buildIndexes } = await import('../../parser/index.js');
+                const { buildIndexes } = await import("../../parser/index.js");
                 return buildIndexes(ctx);
             })();
             const foundTask = resolveTaskRef(ref, tasks, index);
@@ -284,14 +379,16 @@ export function registerTaskCommands(program) {
                         if (!traitsByTrait.has(trait.ulid)) {
                             traitsByTrait.set(trait.ulid, { trait, acs: [] });
                         }
-                        traitsByTrait.get(trait.ulid).acs.push(ac);
+                        traitsByTrait.get(trait.ulid)?.acs.push(ac);
                     }
                     inheritedTraits = Array.from(traitsByTrait.values());
                 }
             }
             // Build JSON output with inherited traits (AC: @trait-display ac-2)
+            // Always include all notes in JSON output with superseded computed field
             const jsonOutput = {
                 ...foundTask,
+                notes: annotateNotesWithSuperseded(foundTask.notes),
                 ...(inheritedTraits.length > 0 && {
                     inherited_traits: inheritedTraits.map(({ trait, acs }) => ({
                         ref: `@${trait.slug}`,
@@ -301,13 +398,14 @@ export function registerTaskCommands(program) {
                 }),
             };
             output(jsonOutput, () => {
-                formatTaskDetails(foundTask, index);
+                formatTaskDetails(foundTask, index, { showAllNotes: options.all });
                 // AC: @trait-display ac-3, ac-4, ac-5 - Show inherited AC per trait in labeled sections
                 if (inheritedTraits.length > 0) {
                     for (const { trait, acs } of inheritedTraits) {
                         console.log(chalk.gray(`\n─── Inherited from @${trait.slug} ───`));
                         for (const ac of acs) {
-                            console.log(chalk.cyan(`  [${ac.id}]`) + chalk.gray(` (from @${trait.slug})`));
+                            console.log(chalk.cyan(`  [${ac.id}]`) +
+                                chalk.gray(` (from @${trait.slug})`));
                             if (ac.given)
                                 console.log(`    Given: ${ac.given}`);
                             if (ac.when)
@@ -325,25 +423,31 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task add
-    task
-        .command('add')
-        .description('Create a new task')
-        .requiredOption('--title <title>', 'Task title')
-        .option('--description <description>', 'Task description')
-        .option('--type <type>', 'Task type (task, epic, bug, spike, infra)', 'task')
-        .option('--spec-ref <ref>', 'Reference to spec item')
-        .option('--meta-ref <ref>', 'Reference to meta item (workflow, agent, or convention)')
-        .option('--priority <n>', 'Priority (1-5)', '3')
-        .option('--slug <slug>', 'Human-friendly slug')
-        .option('--tag <tag...>', 'Tags')
-        .option('--automation <status>', 'Automation eligibility (eligible, needs_review, manual_only)')
+    markMutating(task.command("add"))
+        .description("Create a new task")
+        .requiredOption("--title <title>", "Task title")
+        .option("--description <description>", "Task description")
+        .option("--type <type>", "Task type (task, epic, bug, spike, infra)", "task")
+        .option("--spec-ref <ref>", "Reference to spec item")
+        .option("--meta-ref <ref>", "Reference to meta item (workflow, agent, or convention)")
+        .option("--plan-ref <ref>", "Reference to plan this task is derived from")
+        .option("--priority <n>", "Priority (1-5)", "3")
+        .option("--slug <slug>", "Human-friendly slug")
+        .option("--tag <tag...>", "Tags")
+        .option("--depends-on <refs...>", "Set task dependencies")
+        .option("--automation <status>", "Automation eligibility (eligible, needs_review, manual_only)")
+        .addHelpText("after", `
+Examples:
+  $ kspec task add --title "Implement feature" --spec-ref @feature-spec
+  $ kspec task add --title "Fix bug" --type bug --priority 1
+  $ kspec task add --title "Multi-tag task" --tag cli urgent`)
         .action(async (options) => {
         try {
             const ctx = await initContext();
             const tasks = await loadAllTasks(ctx);
             const items = await loadAllItems(ctx);
             // Load meta items for validation
-            const { loadMetaContext } = await import('../../parser/meta.js');
+            const { loadMetaContext } = await import("../../parser/meta.js");
             const metaContext = await loadMetaContext(ctx);
             const allMetaItems = [
                 ...metaContext.agents,
@@ -369,25 +473,83 @@ export function registerTaskCommands(program) {
                     process.exit(EXIT_CODES.NOT_FOUND);
                 }
                 // Check if the resolved item is a meta item (not a spec item or task)
-                const isTask = tasks.some(t => t._ulid === metaRefResult.ulid);
-                const isSpecItem = items.some(i => i._ulid === metaRefResult.ulid);
+                const isTask = tasks.some((t) => t._ulid === metaRefResult.ulid);
+                const isSpecItem = items.some((i) => i._ulid === metaRefResult.ulid);
                 if (isTask || isSpecItem) {
                     error(errors.reference.metaRefPointsToSpec(options.metaRef));
                     process.exit(EXIT_CODES.NOT_FOUND);
                 }
             }
+            // Validate spec_ref if provided — must point to a spec item, not a task or meta item
+            if (options.specRef) {
+                const specRefResult = validateSpecRef(options.specRef, refIndex, tasks, items);
+                if (!specRefResult.ok) {
+                    error(specRefResult.error);
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+            }
             // AC: @task-automation-eligibility ac-13 - validate automation if provided
             let automationValue;
             if (options.automation) {
-                const validStatuses = ['eligible', 'needs_review', 'manual_only'];
-                if (!validStatuses.includes(options.automation)) {
-                    error(`Invalid automation status: ${options.automation}. Must be one of: ${validStatuses.join(', ')}`);
+                const automationResult = validateEnumOption(options.automation, ["eligible", "needs_review", "manual_only"], "automation status");
+                if (!automationResult.ok) {
+                    error(automationResult.error);
                     process.exit(EXIT_CODES.VALIDATION_FAILED);
                 }
-                automationValue = options.automation;
+                automationValue = automationResult.value;
+            }
+            // Validate plan_ref if provided (AC: @plan-derive ac-5, ac-6)
+            if (options.planRef) {
+                // First check if it's a task or spec item (wrong type)
+                const cleanRef = options.planRef.startsWith("@")
+                    ? options.planRef.slice(1)
+                    : options.planRef;
+                const isTask = tasks.some((t) => t.slugs.includes(cleanRef) ||
+                    t._ulid === cleanRef ||
+                    t._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+                const isSpecItem = items.some((i) => i.slugs.includes(cleanRef) ||
+                    i._ulid === cleanRef ||
+                    i._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+                if (isTask || isSpecItem) {
+                    error(`Reference "${options.planRef}" is not a plan`);
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+                // Now check if the plan exists
+                const { findPlanByRef } = await import("../../parser/plans.js");
+                const plan = await findPlanByRef(ctx, options.planRef);
+                if (!plan) {
+                    error(`Plan reference not found: ${options.planRef}`);
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+            }
+            // AC: @task-add-depends-on ac-2 - Validate dependency refs
+            if (options.dependsOn) {
+                for (const depRef of options.dependsOn) {
+                    const depResult = refIndex.resolve(depRef);
+                    if (!depResult.ok) {
+                        error(errors.reference.depNotFound(depRef));
+                        process.exit(EXIT_CODES.NOT_FOUND);
+                    }
+                    // Ensure the dependency is a task, not a spec item
+                    const isTask = tasks.some((t) => t._ulid === depResult.ulid);
+                    if (!isTask) {
+                        error(`Reference "${depRef}" is not a task`);
+                        process.exit(EXIT_CODES.NOT_FOUND);
+                    }
+                }
+            }
+            // Validate priority
+            const priorityResult = parseIntOption(options.priority, {
+                min: 1,
+                max: 5,
+                name: "Priority",
+            });
+            if (!priorityResult.ok) {
+                error(priorityResult.error);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
             // AC: @spec-task-add-description ac-6 - Omit description if empty string
-            const descriptionValue = options.description && options.description.trim() !== ''
+            const descriptionValue = options.description && options.description.trim() !== ""
                 ? options.description
                 : undefined;
             const input = {
@@ -396,17 +558,21 @@ export function registerTaskCommands(program) {
                 type: options.type,
                 spec_ref: options.specRef || null,
                 meta_ref: options.metaRef || null,
-                priority: parseInt(options.priority, 10),
+                plan_ref: options.planRef || null,
+                priority: priorityResult.value,
                 slugs: options.slug ? [options.slug] : [],
-                tags: options.tag || [],
+                tags: parseTagsArray(options.tag),
+                depends_on: (options.dependsOn || []).map((ref) => ref.startsWith("@") ? ref : `@${ref}`),
                 automation: automationValue,
             };
             const newTask = createTask(input);
             await saveTask(ctx, newTask);
-            await commitIfShadow(ctx.shadow, 'task-add', newTask.slugs[0] || newTask._ulid.slice(0, 8), newTask.title);
+            await commitIfShadow(ctx.shadow, "task-add", newTask.slugs[0] || newTask._ulid.slice(0, 8), newTask.title);
             // Build index including the new task for accurate short ULID
             const index = new ReferenceIndex([...tasks, newTask], items, allMetaItems);
-            success(`Created task: ${index.shortUlid(newTask._ulid)}`, { task: newTask });
+            success(`Created task: ${index.shortUlid(newTask._ulid)}`, {
+                task: newTask,
+            });
         }
         catch (err) {
             error(errors.failures.createTask, err);
@@ -414,39 +580,45 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task set <ref>
-    task
-        .command('set [ref]')
-        .description('Update task fields')
-        .option('--refs <refs...>', 'Update multiple tasks (AC: @spec-task-set-batch ac-1)')
-        .option('--title <title>', 'Update task title')
-        .option('--spec-ref <ref>', 'Link to spec item')
-        .option('--meta-ref <ref>', 'Link to meta item (workflow, agent, or convention)')
-        .option('--priority <n>', 'Set priority (1-5)')
-        .option('--slug <slug>', 'Add a slug alias')
-        .option('--tag <tag...>', 'Add tags')
-        .option('--depends-on <refs...>', 'Set dependencies (replaces existing)')
-        .option('--clear-deps', 'Clear all dependencies')
-        .option('--automation <status>', 'Set automation eligibility (eligible, needs_review, manual_only)')
-        .option('--no-automation', 'Clear automation status (return to unassessed)')
-        .option('--reason <reason>', 'Reason for status change (required when setting needs_review)')
-        .option('--status <status>', 'Reject with error - use state transition commands instead')
+    markMutating(task.command("set [ref]"))
+        .description("Update task fields")
+        .option("--refs <refs...>", "Update multiple tasks (AC: @spec-task-set-batch ac-1)")
+        .option("--title <title>", "Update task title")
+        .option("--spec-ref <ref>", "Link to spec item")
+        .option("--meta-ref <ref>", "Link to meta item (workflow, agent, or convention)")
+        .option("--plan-ref <ref>", "Link to plan (use 'null' to clear)")
+        .option("--priority <n>", "Set priority (1-5)")
+        .option("--slug <slug>", "Add a slug alias")
+        .option("--tag <tag...>", "Add tags")
+        .option("--depends-on <refs...>", "Set dependencies (replaces existing)")
+        .option("--clear-deps", "Clear all dependencies")
+        .option("--automation <status>", "Set automation eligibility (eligible, needs_review, manual_only)")
+        .option("--no-automation", "Clear automation status (return to unassessed)")
+        .option("--reason <reason>", "Reason for status change (required when setting needs_review)")
+        .option("--status <status>", "Reject with error - use state transition commands instead")
+        .addHelpText("after", `
+Examples:
+  $ kspec task set @task-slug --priority 2
+  $ kspec task set @task-slug --depends-on @dep1 @dep2
+  $ kspec task set @task-slug --tag cli urgent
+  $ kspec task set --refs @task1 @task2 --priority 3`)
         .action(async (ref, options) => {
         try {
             // AC: @spec-task-set-batch ac-3 - Reject --status flag
             if (options.status !== undefined) {
-                error('Use state transition commands (start, complete, block, etc.) to change status');
+                error("Use state transition commands (start, complete, block, etc.) to change status");
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
             // AC: @spec-task-clear-deps ac-3 - Mutual exclusivity check
             if (options.clearDeps && options.dependsOn) {
-                error('Cannot use --clear-deps and --depends-on together');
+                error("Cannot use --clear-deps and --depends-on together");
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
             const ctx = await initContext();
             const tasks = await loadAllTasks(ctx);
             const items = await loadAllItems(ctx);
             // Load meta items for validation
-            const { loadMetaContext } = await import('../../parser/meta.js');
+            const { loadMetaContext } = await import("../../parser/meta.js");
             const metaContext = await loadMetaContext(ctx);
             const allMetaItems = [
                 ...metaContext.agents,
@@ -456,7 +628,9 @@ export function registerTaskCommands(program) {
             ];
             const index = new ReferenceIndex(tasks, items, allMetaItems);
             // AC: @trait-multi-ref-batch ac-8 - Deduplicate refs
-            const refsFlag = options.refs ? [...new Set(options.refs)] : undefined;
+            const refsFlag = options.refs
+                ? [...new Set(options.refs)]
+                : undefined;
             // Batch mode or single mode?
             if (refsFlag && refsFlag.length > 0) {
                 // Batch mode - AC: @spec-task-set-batch ac-1, ac-2, ac-5
@@ -475,23 +649,23 @@ export function registerTaskCommands(program) {
                     },
                     getUlid: (task) => task._ulid,
                 });
-                formatBatchOutput(result, 'Set');
+                formatBatchOutput(result, "Set");
             }
             else {
                 // Single mode - existing behavior
                 if (!ref) {
-                    error('Either provide a positional ref or use --refs flag');
+                    error("Either provide a positional ref or use --refs flag");
                     process.exit(EXIT_CODES.USAGE_ERROR);
                 }
                 const foundTask = resolveTaskRef(ref, tasks, index);
                 const result = await setTaskFields(foundTask, ctx, tasks, items, allMetaItems, index, options);
                 if (!result.success) {
-                    error(result.error || 'Failed to update task');
+                    error(result.error || "Failed to update task");
                     process.exit(EXIT_CODES.ERROR);
                 }
                 if (result.message) {
                     // AC: @spec-task-set-batch ac-4 - Warn on no changes
-                    if (result.message.includes('No changes')) {
+                    if (result.message.includes("No changes")) {
                         if (isJsonMode()) {
                             output({ success: true, message: result.message });
                         }
@@ -511,19 +685,18 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task patch <ref>
-    task
-        .command('patch <ref>')
-        .description('Update task with JSON data')
-        .option('--data <json>', 'JSON object with fields to update')
-        .option('--dry-run', 'Show what would change without writing')
-        .option('--allow-unknown', 'Allow unknown fields (for extending format)')
+    markMutating(task.command("patch <ref>"))
+        .description("Update task with JSON data")
+        .option("--data <json>", "JSON object with fields to update")
+        .option("--dry-run", "Show what would change without writing")
+        .option("--allow-unknown", "Allow unknown fields (for extending format)")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
             const tasks = await loadAllTasks(ctx);
             const items = await loadAllItems(ctx);
             // Load meta items for validation
-            const { loadMetaContext } = await import('../../parser/meta.js');
+            const { loadMetaContext } = await import("../../parser/meta.js");
             const metaContext = await loadMetaContext(ctx);
             const allMetaItems = [
                 ...metaContext.agents,
@@ -544,7 +717,7 @@ export function registerTaskCommands(program) {
                 for await (const chunk of process.stdin) {
                     chunks.push(chunk);
                 }
-                jsonData = Buffer.concat(chunks).toString('utf-8');
+                jsonData = Buffer.concat(chunks).toString("utf-8");
             }
             // Parse JSON
             let patchData;
@@ -556,7 +729,7 @@ export function registerTaskCommands(program) {
                 process.exit(EXIT_CODES.ERROR);
             }
             // Validate against TaskInputSchema (partial)
-            const { TaskInputSchema } = await import('../../schema/index.js');
+            const { TaskInputSchema } = await import("../../schema/index.js");
             // Create a partial schema for validation
             const partialSchema = options.allowUnknown
                 ? TaskInputSchema.partial().passthrough()
@@ -573,7 +746,7 @@ export function registerTaskCommands(program) {
             if (!options.allowUnknown) {
                 const knownFields = Object.keys(TaskInputSchema.shape);
                 const providedFields = Object.keys(patchData);
-                const unknownFields = providedFields.filter(f => !knownFields.includes(f));
+                const unknownFields = providedFields.filter((f) => !knownFields.includes(f));
                 if (unknownFields.length > 0) {
                     error(errors.validation.unknownFields(unknownFields));
                     process.exit(EXIT_CODES.ERROR);
@@ -584,17 +757,17 @@ export function registerTaskCommands(program) {
             // Track changes for output
             const changes = Object.keys(validatedPatch);
             if (options.dryRun) {
-                info('Dry run - no changes will be written');
-                info(`Would update: ${changes.join(', ')}`);
+                info("Dry run - no changes will be written");
+                info(`Would update: ${changes.join(", ")}`);
                 output({ changes, updated: updatedTask }, () => {
-                    console.log(`\nChanges: ${changes.join(', ')}\n`);
+                    console.log(`\nChanges: ${changes.join(", ")}\n`);
                     return formatTaskDetails(updatedTask, index);
                 });
                 return;
             }
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-patch', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(', '));
-            success(`Patched task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(', ')})`, { task: updatedTask });
+            await commitIfShadow(ctx.shadow, "task-patch", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(", "));
+            success(`Patched task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(", ")})`, { task: updatedTask });
         }
         catch (err) {
             error(errors.failures.patchTask, err);
@@ -602,10 +775,9 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task start <ref>
-    task
-        .command('start <ref>')
-        .description('Start working on a task (pending -> in_progress)')
-        .option('--no-sync', 'Skip syncing spec implementation status')
+    markMutating(task.command("start <ref>"))
+        .description("Start working on a task (pending|needs_work -> in_progress)")
+        .option("--no-sync", "Skip syncing spec implementation status")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -613,37 +785,40 @@ export function registerTaskCommands(program) {
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status === 'in_progress') {
-                warn('Task is already in progress');
+            if (foundTask.status === "in_progress") {
+                warn("Task is already in progress");
                 output(foundTask, () => formatTaskDetails(foundTask));
                 return;
             }
-            if (foundTask.status !== 'pending') {
+            if (foundTask.status !== "pending" && foundTask.status !== "needs_work") {
                 error(errors.status.cannotStart(foundTask.status));
                 process.exit(EXIT_CODES.VALIDATION_FAILED); // Exit code 4 = invalid state
             }
             // Update status
             const updatedTask = {
                 ...foundTask,
-                status: 'in_progress',
+                status: "in_progress",
                 started_at: new Date().toISOString(),
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-start', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Started task: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
+            await commitIfShadow(ctx.shadow, "task-start", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Started task: ${index.shortUlid(updatedTask._ulid)}`, {
+                task: updatedTask,
+            });
             // Show spec context and AC guidance (suppressed in JSON mode)
             if (!isJsonMode() && foundTask.spec_ref) {
                 const specResult = index.resolve(foundTask.spec_ref);
                 if (specResult.ok) {
-                    const specItem = items.find(i => i._ulid === specResult.ulid);
+                    const specItem = items.find((i) => i._ulid === specResult.ulid);
                     if (specItem) {
-                        console.log('');
-                        console.log('--- Spec Context ---');
+                        console.log("");
+                        console.log("--- Spec Context ---");
                         console.log(`Implementing: ${specItem.title}`);
                         if (specItem.description) {
                             console.log(`\n${specItem.description}`);
                         }
-                        if (specItem.acceptance_criteria && specItem.acceptance_criteria.length > 0) {
+                        if (specItem.acceptance_criteria &&
+                            specItem.acceptance_criteria.length > 0) {
                             console.log(`\nAcceptance Criteria (${specItem.acceptance_criteria.length}):`);
                             for (const ac of specItem.acceptance_criteria) {
                                 console.log(`  [${ac.id}]`);
@@ -651,21 +826,21 @@ export function registerTaskCommands(program) {
                                 console.log(`    When: ${ac.when}`);
                                 console.log(`    Then: ${ac.then}`);
                             }
-                            console.log('');
-                            console.log('Remember: Add test coverage for each AC and mark tests with // AC: @spec-ref ac-N');
+                            console.log("");
+                            console.log("Remember: Add test coverage for each AC and mark tests with // AC: @spec-ref ac-N");
                         }
-                        console.log('');
+                        console.log("");
                     }
                 }
             }
             // Sync spec implementation status (unless --no-sync)
             if (options.sync !== false && foundTask.spec_ref) {
-                const updatedTasks = tasks.map(t => t._ulid === updatedTask._ulid ? { ...t, ...updatedTask } : t);
+                const updatedTasks = tasks.map((t) => t._ulid === updatedTask._ulid ? { ...t, ...updatedTask } : t);
                 const syncResult = await syncSpecImplementationStatus(ctx, updatedTask, updatedTasks, items, index);
                 if (syncResult) {
                     info(`Synced spec "${syncResult.specTitle}" implementation: ${syncResult.previousStatus} -> ${syncResult.newStatus}`);
                     // Commit the spec status change
-                    await commitIfShadow(ctx.shadow, 'spec-sync', syncResult.specUlid.slice(0, 8), `${syncResult.previousStatus} -> ${syncResult.newStatus}`);
+                    await commitIfShadow(ctx.shadow, "spec-sync", syncResult.specUlid.slice(0, 8), `${syncResult.previousStatus} -> ${syncResult.newStatus}`);
                 }
             }
         }
@@ -677,13 +852,17 @@ export function registerTaskCommands(program) {
     // kspec task complete <ref> | --refs <refs...>
     // AC: @multi-ref-batch ac-1 - Basic multi-ref syntax
     // AC: @multi-ref-batch ac-2 - Backward compatibility
-    task
-        .command('complete [ref]')
-        .description('Complete a task (pending_review -> completed)')
-        .option('--refs <refs...>', 'Complete multiple tasks by ref')
-        .option('--reason <reason>', 'Completion reason/notes')
-        .option('--skip-review', 'Skip review requirement (requires --reason)')
-        .option('--no-sync', 'Skip syncing spec implementation status')
+    markMutating(task.command("complete [ref]"))
+        .description("Complete a task (pending_review -> completed)")
+        .option("--refs <refs...>", "Complete multiple tasks by ref")
+        .option("--reason <reason>", "Completion reason/notes")
+        .option("--skip-review", "Skip review requirement (requires --reason)")
+        .option("--force", "Force completion even if blocked (AC: @task-commands ac-1)")
+        .option("--no-sync", "Skip syncing spec implementation status")
+        .addHelpText("after", `
+Examples:
+  $ kspec task complete @task-slug --reason "Merged in PR #123"
+  $ kspec task complete --refs @task1 @task2 --reason "Batch completion"`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -709,44 +888,47 @@ export function registerTaskCommands(program) {
                 executeOperation: async (foundTask, { ctx, tasks, items, index, options }) => {
                     try {
                         // AC: @spec-completion-enforcement ac-6
-                        if (foundTask.status === 'completed') {
+                        if (foundTask.status === "completed") {
                             return {
                                 success: false,
                                 error: errors.status.completeAlreadyCompleted,
                             };
                         }
+                        // AC: @task-commands ac-1 - Allow --force to bypass blocked state
+                        // Handle blocked task with --force before other checks
+                        const forcingBlockedTask = foundTask.status === "blocked" && options.force;
                         // AC: @spec-completion-enforcement ac-7 - Allow skip-review bypass
-                        if (!options.skipReview) {
+                        if (!options.skipReview && !forcingBlockedTask) {
                             // AC: @spec-completion-enforcement ac-2
-                            if (foundTask.status === 'in_progress') {
+                            if (foundTask.status === "in_progress") {
                                 return {
                                     success: false,
                                     error: errors.status.completeRequiresReview,
                                 };
                             }
                             // AC: @spec-completion-enforcement ac-3
-                            if (foundTask.status === 'pending') {
+                            if (foundTask.status === "pending") {
                                 return {
                                     success: false,
                                     error: errors.status.completeRequiresStart,
                                 };
                             }
                             // AC: @spec-completion-enforcement ac-4
-                            if (foundTask.status === 'blocked') {
+                            if (foundTask.status === "blocked") {
                                 return {
                                     success: false,
                                     error: errors.status.completeBlockedTask,
                                 };
                             }
                             // AC: @spec-completion-enforcement ac-5
-                            if (foundTask.status === 'cancelled') {
+                            if (foundTask.status === "cancelled") {
                                 return {
                                     success: false,
                                     error: errors.status.completeCancelledTask,
                                 };
                             }
                             // AC: @spec-completion-enforcement ac-1 - Only pending_review allowed
-                            if (foundTask.status !== 'pending_review') {
+                            if (foundTask.status !== "pending_review") {
                                 return {
                                     success: false,
                                     error: errors.status.cannotComplete(foundTask.status),
@@ -758,44 +940,61 @@ export function registerTaskCommands(program) {
                         // AC: @spec-completion-enforcement ac-author
                         let taskNotes = foundTask.notes;
                         if (options.skipReview && options.reason) {
-                            const skipNote = createNote(`Completed with --skip-review: ${options.reason}`, getAuthor());
+                            const skipNote = createNote(`Completed with --skip-review: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
                             taskNotes = [...taskNotes, skipNote];
                         }
+                        // AC: @task-commands ac-1 - Document force completion of blocked task
+                        if (forcingBlockedTask) {
+                            const blockedBy = foundTask.blocked_by.join("; ");
+                            const forceNote = createNote(`Completed with --force despite blocked state. Was blocked by: ${blockedBy || "(dependency-blocked)"}${options.reason ? `. Reason: ${options.reason}` : ""}`, getAuthor(ctx.config?.identity?.author));
+                            taskNotes = [...taskNotes, forceNote];
+                        }
                         // Update status
                         const updatedTask = {
                             ...foundTask,
-                            status: 'completed',
+                            status: "completed",
                             completed_at: now,
                             closed_reason: options.reason || null,
                             started_at: foundTask.started_at || now,
                             notes: taskNotes,
                         };
                         await saveTask(ctx, updatedTask);
-                        await commitIfShadow(ctx.shadow, 'task-complete', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), options.reason);
+                        await commitIfShadow(ctx.shadow, "task-complete", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), options.reason);
                         // Sync spec implementation status (unless --no-sync)
                         if (options.sync !== false && foundTask.spec_ref) {
-                            const updatedTasks = tasks.map(t => t._ulid === updatedTask._ulid ? { ...t, ...updatedTask } : t);
+                            const updatedTasks = tasks.map((t) => t._ulid === updatedTask._ulid ? { ...t, ...updatedTask } : t);
                             const syncResult = await syncSpecImplementationStatus(ctx, updatedTask, updatedTasks, items, index);
                             if (syncResult && !isJsonMode()) {
                                 info(`Synced spec "${syncResult.specTitle}" implementation: ${syncResult.previousStatus} -> ${syncResult.newStatus}`);
-                                await commitIfShadow(ctx.shadow, 'spec-sync', syncResult.specUlid.slice(0, 8), `${syncResult.previousStatus} -> ${syncResult.newStatus}`);
+                                await commitIfShadow(ctx.shadow, "spec-sync", syncResult.specUlid.slice(0, 8), `${syncResult.previousStatus} -> ${syncResult.newStatus}`);
                             }
                         }
                         // Show AC reminder for single-ref mode only (not in batch)
                         if (!options.refs && foundTask.spec_ref && !isJsonMode()) {
                             const specResult = index.resolve(foundTask.spec_ref);
                             if (specResult.ok && specResult.item) {
-                                const specItem = items.find(i => i._ulid === specResult.ulid);
-                                if (specItem && specItem.acceptance_criteria && specItem.acceptance_criteria.length > 0) {
+                                const specItem = items.find((i) => i._ulid === specResult.ulid);
+                                if (specItem?.acceptance_criteria &&
+                                    specItem.acceptance_criteria.length > 0) {
                                     const count = specItem.acceptance_criteria.length;
-                                    console.log(`\n⚠ Linked spec ${foundTask.spec_ref} has ${count} acceptance criteri${count === 1 ? 'on' : 'a'} - verify they are covered\n`);
+                                    console.log(`\n⚠ Linked spec ${foundTask.spec_ref} has ${count} acceptance criteri${count === 1 ? "on" : "a"} - verify they are covered\n`);
                                 }
                             }
                         }
+                        // AC: @task-commands ac-1 - Show warning when force-completing blocked task
+                        let warningMsg;
+                        if (forcingBlockedTask) {
+                            const blockedBy = foundTask.blocked_by.join("; ");
+                            warningMsg = `Task was blocked by: ${blockedBy || "(dependency-blocked)"}`;
+                            if (!isJsonMode()) {
+                                warn(warningMsg);
+                            }
+                        }
                         return {
                             success: true,
                             message: `Completed task: ${index.shortUlid(updatedTask._ulid)}`,
                             data: updatedTask,
+                            ...(forcingBlockedTask && { warning: warningMsg }),
                         };
                     }
                     catch (err) {
@@ -808,9 +1007,12 @@ export function registerTaskCommands(program) {
                 getUlid: (task) => task._ulid,
             });
             // AC: @multi-ref-batch ac-5, ac-6
-            formatBatchOutput(result, 'Complete');
+            formatBatchOutput(result, "Complete");
             // Show commit guidance for single-ref mode only
-            if (!options.refs && result.success && result.results.length === 1 && !isJsonMode()) {
+            if (!options.refs &&
+                result.success &&
+                result.results.length === 1 &&
+                !isJsonMode()) {
                 const taskData = result.results[0].data;
                 if (taskData) {
                     const guidance = formatCommitGuidance(taskData);
@@ -825,9 +1027,8 @@ export function registerTaskCommands(program) {
     });
     // kspec task submit <ref>
     // Transitions in_progress → pending_review (code done, awaiting merge)
-    task
-        .command('submit <ref>')
-        .description('Submit task for review (transitions to pending_review)')
+    markMutating(task.command("submit <ref>"))
+        .description("Submit task for review (transitions to pending_review)")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -835,16 +1036,16 @@ export function registerTaskCommands(program) {
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status !== 'in_progress') {
+            if (foundTask.status !== "in_progress") {
                 error(`Cannot submit task with status: ${foundTask.status}. Task must be in_progress.`);
                 process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
             const updatedTask = {
                 ...foundTask,
-                status: 'pending_review',
+                status: "pending_review",
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-submit', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            await commitIfShadow(ctx.shadow, "task-submit", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
             success(`Submitted task for review: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
         }
         catch (err) {
@@ -852,11 +1053,44 @@ export function registerTaskCommands(program) {
             process.exit(EXIT_CODES.ERROR);
         }
     });
+    // kspec task needs-work <ref>
+    // Reviewer kicks back a task for worker to fix
+    markMutating(task.command("needs-work <ref>"))
+        .description("Kick task back to worker for fixes (pending_review -> needs_work)")
+        .requiredOption("--reason <reason>", "Description of issues found")
+        .action(async (ref, options) => {
+        try {
+            const ctx = await initContext();
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            const index = new ReferenceIndex(tasks, items);
+            const foundTask = resolveTaskRef(ref, tasks, index);
+            if (foundTask.status !== "pending_review") {
+                error(`Cannot transition task to needs_work from status: ${foundTask.status}. Task must be pending_review.`);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            // Track fix cycle count from existing kickback notes
+            const existingKickbacks = foundTask.notes.filter((n) => n.content.includes("[FIX_CYCLE:")).length;
+            const cycleNumber = existingKickbacks + 1;
+            const note = createNote(`[FIX_CYCLE: ${cycleNumber}] Review findings: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
+            const updatedTask = {
+                ...foundTask,
+                status: "needs_work",
+                notes: [...foundTask.notes, note],
+            };
+            await saveTask(ctx, updatedTask);
+            await commitIfShadow(ctx.shadow, "task-needs-work", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), `cycle ${cycleNumber}`);
+            success(`Kicked back task: ${index.shortUlid(updatedTask._ulid)} (fix cycle ${cycleNumber})`, { task: updatedTask });
+        }
+        catch (err) {
+            error("Failed to transition task to needs_work", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
     // kspec task block <ref>
-    task
-        .command('block <ref>')
-        .description('Block a task')
-        .requiredOption('--reason <reason>', 'Reason for blocking')
+    markMutating(task.command("block <ref>"))
+        .description("Block a task")
+        .requiredOption("--reason <reason>", "Reason for blocking")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -864,18 +1098,21 @@ export function registerTaskCommands(program) {
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status === 'completed' || foundTask.status === 'cancelled') {
+            if (foundTask.status === "completed" ||
+                foundTask.status === "cancelled") {
                 error(errors.status.cannotBlock(foundTask.status));
                 process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
             const updatedTask = {
                 ...foundTask,
-                status: 'blocked',
+                status: "blocked",
                 blocked_by: [...foundTask.blocked_by, options.reason],
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-block', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Blocked task: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
+            await commitIfShadow(ctx.shadow, "task-block", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Blocked task: ${index.shortUlid(updatedTask._ulid)}`, {
+                task: updatedTask,
+            });
         }
         catch (err) {
             error(errors.failures.blockTask, err);
@@ -883,9 +1120,8 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task unblock <ref>
-    task
-        .command('unblock <ref>')
-        .description('Unblock a task')
+    markMutating(task.command("unblock <ref>"))
+        .description("Unblock a task")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -893,18 +1129,20 @@ export function registerTaskCommands(program) {
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status !== 'blocked') {
-                warn('Task is not blocked');
+            if (foundTask.status !== "blocked") {
+                warn("Task is not blocked");
                 return;
             }
             const updatedTask = {
                 ...foundTask,
-                status: 'pending',
+                status: "pending",
                 blocked_by: [],
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-unblock', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Unblocked task: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
+            await commitIfShadow(ctx.shadow, "task-unblock", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Unblocked task: ${index.shortUlid(updatedTask._ulid)}`, {
+                task: updatedTask,
+            });
         }
         catch (err) {
             error(errors.failures.unblockTask, err);
@@ -913,11 +1151,14 @@ export function registerTaskCommands(program) {
     });
     // kspec task cancel <ref> | --refs <refs...>
     // AC: @multi-ref-batch ac-1, ac-2
-    task
-        .command('cancel [ref]')
-        .description('Cancel a task')
-        .option('--refs <refs...>', 'Cancel multiple tasks by ref')
-        .option('--reason <reason>', 'Cancellation reason')
+    markMutating(task.command("cancel [ref]"))
+        .description("Cancel a task")
+        .option("--refs <refs...>", "Cancel multiple tasks by ref")
+        .option("--reason <reason>", "Cancellation reason")
+        .addHelpText("after", `
+Examples:
+  $ kspec task cancel @task-slug --reason "No longer needed"
+  $ kspec task cancel --refs @task1 @task2 --reason "Superseded by @new-task"`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -936,7 +1177,8 @@ export function registerTaskCommands(program) {
                 },
                 executeOperation: async (foundTask, { ctx, index, options }) => {
                     try {
-                        if (foundTask.status === 'completed' || foundTask.status === 'cancelled') {
+                        if (foundTask.status === "completed" ||
+                            foundTask.status === "cancelled") {
                             return {
                                 success: false,
                                 error: `Task is already ${foundTask.status}`,
@@ -944,11 +1186,11 @@ export function registerTaskCommands(program) {
                         }
                         const updatedTask = {
                             ...foundTask,
-                            status: 'cancelled',
+                            status: "cancelled",
                             closed_reason: options.reason || null,
                         };
                         await saveTask(ctx, updatedTask);
-                        await commitIfShadow(ctx.shadow, 'task-cancel', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+                        await commitIfShadow(ctx.shadow, "task-cancel", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
                         return {
                             success: true,
                             message: `Cancelled task: ${index.shortUlid(updatedTask._ulid)}`,
@@ -964,7 +1206,7 @@ export function registerTaskCommands(program) {
                 },
                 getUlid: (task) => task._ulid,
             });
-            formatBatchOutput(result, 'Cancel');
+            formatBatchOutput(result, "Cancel");
         }
         catch (err) {
             error(errors.failures.cancelTask, err);
@@ -973,9 +1215,8 @@ export function registerTaskCommands(program) {
     });
     // kspec task reset <ref>
     // AC: @spec-task-reset ac-1, ac-2, ac-3, ac-4, ac-5, ac-6
-    task
-        .command('reset <ref>')
-        .description('Reset a task to pending state')
+    markMutating(task.command("reset <ref>"))
+        .description("Reset a task to pending state")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -984,72 +1225,81 @@ export function registerTaskCommands(program) {
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
             // AC: @spec-task-reset ac-2 - Error if already pending
-            if (foundTask.status === 'pending') {
-                error('Task is already pending');
+            if (foundTask.status === "pending") {
+                error("Task is already pending");
                 process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
             // Track previous status and reason for note (AC-4)
             const previousStatus = foundTask.status;
-            const hadCancelReason = foundTask.closed_reason && foundTask.status === 'cancelled';
-            const cancelReasonText = hadCancelReason ? ` (was cancelled: ${foundTask.closed_reason})` : '';
+            const hadCancelReason = foundTask.closed_reason && foundTask.status === "cancelled";
+            const cancelReasonText = hadCancelReason
+                ? ` (was cancelled: ${foundTask.closed_reason})`
+                : "";
             // AC: @spec-task-reset ac-1 - Reset to pending, clear completion-related fields
             const clearedFields = [];
             const updatedTask = {
                 ...foundTask,
-                status: 'pending',
+                status: "pending",
             };
             // Clear timestamps and reasons based on previous status
-            if (foundTask.completed_at !== undefined && foundTask.completed_at !== null) {
+            if (foundTask.completed_at !== undefined &&
+                foundTask.completed_at !== null) {
                 updatedTask.completed_at = null;
-                clearedFields.push('completed_at');
+                clearedFields.push("completed_at");
             }
-            if (foundTask.started_at !== undefined && foundTask.started_at !== null) {
+            if (foundTask.started_at !== undefined &&
+                foundTask.started_at !== null) {
                 updatedTask.started_at = null;
-                clearedFields.push('started_at');
+                clearedFields.push("started_at");
             }
-            if (foundTask.closed_reason !== undefined && foundTask.closed_reason !== null) {
+            if (foundTask.closed_reason !== undefined &&
+                foundTask.closed_reason !== null) {
                 updatedTask.closed_reason = null;
-                clearedFields.push('closed_reason');
+                clearedFields.push("closed_reason");
             }
             if (foundTask.blocked_by.length > 0) {
                 updatedTask.blocked_by = [];
-                clearedFields.push('blocked_by');
+                clearedFields.push("blocked_by");
             }
             // AC: @spec-task-reset ac-4 - Add note documenting the reset
             // AC: @spec-task-reset ac-author
             const noteContent = `Reset from ${previousStatus} to pending${cancelReasonText}`;
-            const note = createNote(noteContent, getAuthor());
+            const note = createNote(noteContent, getAuthor(ctx.config?.identity?.author));
             updatedTask.notes = [...updatedTask.notes, note];
             await saveTask(ctx, updatedTask);
             // AC: @spec-task-reset ac-3 - Shadow commit with message task-reset
-            await commitIfShadow(ctx.shadow, 'task-reset', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), `from ${previousStatus}`);
+            await commitIfShadow(ctx.shadow, "task-reset", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), `from ${previousStatus}`);
             // AC: @spec-task-reset ac-6 - JSON output includes previous_status, new_status, cleared_fields
             const jsonOutput = {
                 task: updatedTask,
                 previous_status: previousStatus,
-                new_status: 'pending',
+                new_status: "pending",
                 cleared_fields: clearedFields,
             };
             output(jsonOutput, () => {
                 success(`Reset task: ${index.shortUlid(updatedTask._ulid)} (${previousStatus} → pending)`, undefined);
                 if (clearedFields.length > 0) {
-                    info(`Cleared fields: ${clearedFields.join(', ')}`);
+                    info(`Cleared fields: ${clearedFields.join(", ")}`);
                 }
             });
         }
         catch (err) {
-            error('Failed to reset task', err);
+            error("Failed to reset task", err);
             process.exit(EXIT_CODES.ERROR);
         }
     });
     // kspec task delete <ref> | --refs <refs...>
     // AC: @multi-ref-batch ac-1, ac-2
-    task
-        .command('delete [ref]')
-        .description('Delete a task permanently')
-        .option('--refs <refs...>', 'Delete multiple tasks by ref')
-        .option('--force', 'Skip confirmation (required for --refs)')
-        .option('--dry-run', 'Show what would be deleted without deleting')
+    markMutating(task.command("delete [ref]"))
+        .description("Delete a task permanently")
+        .option("--refs <refs...>", "Delete multiple tasks by ref")
+        .option("--force", "Skip confirmation (required for --refs)")
+        .option("--dry-run", "Show what would be deleted without deleting")
+        .addHelpText("after", `
+Examples:
+  $ kspec task delete @task-slug
+  $ kspec task delete --refs @task1 @task2 --force
+  $ kspec task delete --refs @task1 @task2 --dry-run`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -1057,8 +1307,11 @@ export function registerTaskCommands(program) {
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             // For batch mode (--refs), require --force
-            if (options.refs && options.refs.length > 0 && !options.force && !options.dryRun) {
-                error('Batch delete requires --force flag');
+            if (options.refs &&
+                options.refs.length > 0 &&
+                !options.force &&
+                !options.dryRun) {
+                error("Batch delete requires --force flag");
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
             const result = await executeBatchOperation({
@@ -1082,7 +1335,7 @@ export function registerTaskCommands(program) {
                         }
                         // For single-ref mode (not --refs), prompt for confirmation unless --force
                         if (!options.refs && !options.force) {
-                            const readline = await import('readline');
+                            const readline = await import("node:readline");
                             const rl = readline.createInterface({
                                 input: process.stdin,
                                 output: process.stdout,
@@ -1091,15 +1344,15 @@ export function registerTaskCommands(program) {
                                 rl.question(`Delete task "${taskDisplay}"? [y/N] `, resolve);
                             });
                             rl.close();
-                            if (answer.toLowerCase() !== 'y') {
+                            if (answer.toLowerCase() !== "y") {
                                 return {
                                     success: false,
-                                    error: 'Deletion cancelled by user',
+                                    error: "Deletion cancelled by user",
                                 };
                             }
                         }
                         await deleteTask(ctx, foundTask);
-                        await commitIfShadow(ctx.shadow, 'task-delete', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), foundTask.title);
+                        await commitIfShadow(ctx.shadow, "task-delete", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), foundTask.title);
                         return {
                             success: true,
                             message: `Deleted task: ${taskDisplay}`,
@@ -1114,7 +1367,7 @@ export function registerTaskCommands(program) {
                 },
                 getUlid: (task) => task._ulid,
             });
-            formatBatchOutput(result, 'Delete');
+            formatBatchOutput(result, "Delete");
         }
         catch (err) {
             error(errors.failures.deleteTask, err);
@@ -1122,11 +1375,10 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task note <ref> <message>
-    task
-        .command('note <ref> <message>')
-        .description('Add a note to a task')
-        .option('--author <author>', 'Note author')
-        .option('--supersedes <ulid>', 'ULID of note this supersedes')
+    markMutating(task.command("note <ref> <message>"))
+        .description("Add a note to a task")
+        .option("--author <author>", "Note author")
+        .option("--supersedes <ulid>", "ULID of note this supersedes")
         .action(async (ref, message, options) => {
         try {
             const ctx = await initContext();
@@ -1140,11 +1392,13 @@ export function registerTaskCommands(program) {
                 notes: [...foundTask.notes, note],
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-note', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Added note to task: ${index.shortUlid(updatedTask._ulid)}`, { note });
+            await commitIfShadow(ctx.shadow, "task-note", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Added note to task: ${index.shortUlid(updatedTask._ulid)}`, {
+                note,
+            });
             // Proactive alignment guidance for tasks with spec_ref
             if (foundTask.spec_ref) {
-                console.log('');
+                console.log("");
                 console.log(alignmentCheck.header);
                 console.log(alignmentCheck.beyondSpec);
                 console.log(alignmentCheck.updateSpec(foundTask.spec_ref));
@@ -1153,8 +1407,9 @@ export function registerTaskCommands(program) {
                 const specResult = index.resolve(foundTask.spec_ref);
                 if (specResult.ok && specResult.item) {
                     const specItem = specResult.item;
-                    if (specItem.acceptance_criteria && specItem.acceptance_criteria.length > 0) {
-                        console.log('');
+                    if (specItem.acceptance_criteria &&
+                        specItem.acceptance_criteria.length > 0) {
+                        console.log("");
                         console.log(alignmentCheck.testCoverage(specItem.acceptance_criteria.length));
                     }
                 }
@@ -1167,8 +1422,8 @@ export function registerTaskCommands(program) {
     });
     // kspec task notes <ref>
     task
-        .command('notes <ref>')
-        .description('Show notes for a task')
+        .command("notes <ref>")
+        .description("Show notes for a task")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -1178,14 +1433,14 @@ export function registerTaskCommands(program) {
             const foundTask = resolveTaskRef(ref, tasks, index);
             output(foundTask.notes, () => {
                 if (foundTask.notes.length === 0) {
-                    console.log('No notes');
+                    console.log("No notes");
                 }
                 else {
                     for (const note of foundTask.notes) {
-                        const author = note.author || 'unknown';
+                        const author = note.author || "unknown";
                         console.log(`[${note.created_at}] ${author}:`);
                         console.log(note.content);
-                        console.log('');
+                        console.log("");
                     }
                 }
             });
@@ -1197,8 +1452,8 @@ export function registerTaskCommands(program) {
     });
     // kspec task review <ref>
     task
-        .command('review <ref>')
-        .description('Get task context for review (task details, spec, ACs, git diff)')
+        .command("review <ref>")
+        .description("Get task context for review (task details, spec, ACs, git diff)")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -1207,42 +1462,7 @@ export function registerTaskCommands(program) {
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
             // Import getDiffSince from utils
-            const { getDiffSince } = await import('../../utils/index.js');
-            // Import scanTestCoverage (we'll need to export it from validate.ts)
-            // For now, duplicate the logic here
-            const scanTestCoverage = async (rootDir) => {
-                const coveredACs = new Set();
-                const testsDir = path.join(rootDir, 'tests');
-                const fs = await import('node:fs/promises');
-                try {
-                    await fs.access(testsDir);
-                    const files = await fs.readdir(testsDir);
-                    const testFiles = files.filter(f => f.endsWith('.test.ts') || f.endsWith('.test.js'));
-                    for (const file of testFiles) {
-                        const filePath = path.join(testsDir, file);
-                        const content = await fs.readFile(filePath, 'utf-8');
-                        const acPattern = /\/\/\s*AC:\s*(@[\w-]+)(?:\s+(ac-\d+(?:\s*,\s*ac-\d+)*))?/g;
-                        let match;
-                        while ((match = acPattern.exec(content)) !== null) {
-                            const specRef = match[1];
-                            const acList = match[2];
-                            if (acList) {
-                                const acs = acList.split(',').map(ac => ac.trim());
-                                for (const ac of acs) {
-                                    coveredACs.add(`${specRef} ${ac}`);
-                                }
-                            }
-                            else {
-                                coveredACs.add(specRef);
-                            }
-                        }
-                    }
-                }
-                catch (err) {
-                    // Tests directory doesn't exist or can't be read
-                }
-                return coveredACs;
-            };
+            const { getDiffSince } = await import("../../utils/index.js");
             // Gather review context
             const reviewContext = {
                 task: foundTask,
@@ -1254,10 +1474,11 @@ export function registerTaskCommands(program) {
             if (foundTask.spec_ref) {
                 const specResult = index.resolve(foundTask.spec_ref);
                 if (specResult.ok) {
-                    const specItem = items.find(i => i._ulid === specResult.ulid);
+                    const specItem = items.find((i) => i._ulid === specResult.ulid);
                     reviewContext.spec = specItem || null;
                     // Check test coverage for ACs if spec has them
-                    if (specItem && specItem.acceptance_criteria && specItem.acceptance_criteria.length > 0) {
+                    if (specItem?.acceptance_criteria &&
+                        specItem.acceptance_criteria.length > 0) {
                         const coveredACs = await scanTestCoverage(ctx.rootDir);
                         const covered = [];
                         const uncovered = [];
@@ -1270,7 +1491,7 @@ export function registerTaskCommands(program) {
                             }
                             possibleRefs.push(`@${specItem._ulid.slice(0, 8)} ${ac.id}`);
                             possibleRefs.push(`@${specItem._ulid.slice(0, 8)}`);
-                            const isCovered = possibleRefs.some(ref => coveredACs.has(ref));
+                            const isCovered = possibleRefs.some((ref) => coveredACs.has(ref));
                             if (isCovered) {
                                 covered.push(ac.id);
                             }
@@ -1288,29 +1509,32 @@ export function registerTaskCommands(program) {
                 reviewContext.diff = getDiffSince(startedDate, ctx.rootDir);
             }
             output(reviewContext, () => {
-                console.log('='.repeat(60));
-                console.log('Task Review Context');
-                console.log('='.repeat(60));
+                console.log("=".repeat(60));
+                console.log("Task Review Context");
+                console.log("=".repeat(60));
                 console.log();
                 // Task details
-                console.log('TASK DETAILS');
-                console.log('-'.repeat(60));
+                console.log("TASK DETAILS");
+                console.log("-".repeat(60));
                 console.log(formatTaskDetails(foundTask, index));
                 console.log();
                 // Spec details
                 if (reviewContext.spec) {
-                    console.log('LINKED SPEC');
-                    console.log('-'.repeat(60));
+                    console.log("LINKED SPEC");
+                    console.log("-".repeat(60));
                     console.log(`Title: ${reviewContext.spec.title}`);
                     console.log(`Type: ${reviewContext.spec.type}`);
                     if (reviewContext.spec.description) {
                         console.log(`\nDescription:\n${reviewContext.spec.description}`);
                     }
-                    if (reviewContext.spec.acceptance_criteria && reviewContext.spec.acceptance_criteria.length > 0) {
+                    if (reviewContext.spec.acceptance_criteria &&
+                        reviewContext.spec.acceptance_criteria.length > 0) {
                         console.log(`\nAcceptance Criteria (${reviewContext.spec.acceptance_criteria.length}):`);
                         for (const ac of reviewContext.spec.acceptance_criteria) {
                             const isCovered = reviewContext.testCoverage?.covered.includes(ac.id);
-                            const coverageMarker = isCovered ? chalk.green('✓') : chalk.yellow('○');
+                            const coverageMarker = isCovered
+                                ? chalk.green("✓")
+                                : chalk.yellow("○");
                             console.log(`  ${coverageMarker} [${ac.id}]`);
                             console.log(`    Given: ${ac.given}`);
                             console.log(`    When: ${ac.when}`);
@@ -1325,7 +1549,7 @@ export function registerTaskCommands(program) {
                             }
                             else {
                                 console.log(chalk.yellow(`  Test coverage: ${covered.length}/${covered.length + uncovered.length} ACs covered`));
-                                console.log(chalk.yellow(`  Missing coverage for: ${uncovered.join(', ')}`));
+                                console.log(chalk.yellow(`  Missing coverage for: ${uncovered.join(", ")}`));
                             }
                         }
                     }
@@ -1333,40 +1557,40 @@ export function registerTaskCommands(program) {
                 }
                 // Git diff
                 if (reviewContext.diff) {
-                    console.log('CHANGES SINCE TASK STARTED');
-                    console.log('-'.repeat(60));
+                    console.log("CHANGES SINCE TASK STARTED");
+                    console.log("-".repeat(60));
                     console.log(`Started at: ${foundTask.started_at}`);
                     console.log();
                     console.log(reviewContext.diff);
                     console.log();
                 }
                 else if (foundTask.started_at) {
-                    console.log('CHANGES SINCE TASK STARTED');
-                    console.log('-'.repeat(60));
+                    console.log("CHANGES SINCE TASK STARTED");
+                    console.log("-".repeat(60));
                     console.log(`Started at: ${foundTask.started_at}`);
-                    console.log('No changes detected');
+                    console.log("No changes detected");
                     console.log();
                 }
-                console.log('='.repeat(60));
-                console.log('Review Checklist:');
-                console.log('- Does the implementation match the task description?');
+                console.log("=".repeat(60));
+                console.log("Review Checklist:");
+                console.log("- Does the implementation match the task description?");
                 if (reviewContext.spec) {
-                    console.log('- Are all acceptance criteria covered?');
-                    console.log('- Is test coverage adequate?');
+                    console.log("- Are all acceptance criteria covered?");
+                    console.log("- Is test coverage adequate?");
                 }
-                console.log('- Are there any gaps or issues?');
-                console.log('='.repeat(60));
+                console.log("- Are there any gaps or issues?");
+                console.log("=".repeat(60));
             });
         }
         catch (err) {
-            error('Failed to generate review context', err);
+            error("Failed to generate review context", err);
             process.exit(EXIT_CODES.ERROR);
         }
     });
     // kspec task todos <ref>
     task
-        .command('todos <ref>')
-        .description('Show todos for a task')
+        .command("todos <ref>")
+        .description("Show todos for a task")
         .action(async (ref) => {
         try {
             const ctx = await initContext();
@@ -1376,12 +1600,12 @@ export function registerTaskCommands(program) {
             const foundTask = resolveTaskRef(ref, tasks, index);
             output(foundTask.todos, () => {
                 if (foundTask.todos.length === 0) {
-                    console.log('No todos');
+                    console.log("No todos");
                 }
                 else {
                     for (const todo of foundTask.todos) {
-                        const status = todo.done ? '[x]' : '[ ]';
-                        const doneInfo = todo.done && todo.done_at ? ` (done ${todo.done_at})` : '';
+                        const status = todo.done ? "[x]" : "[ ]";
+                        const doneInfo = todo.done && todo.done_at ? ` (done ${todo.done_at})` : "";
                         console.log(`${status} ${todo.id}. ${todo.text}${doneInfo}`);
                     }
                 }
@@ -1393,14 +1617,11 @@ export function registerTaskCommands(program) {
         }
     });
     // Create subcommand group for todo operations
-    const todoCmd = task
-        .command('todo')
-        .description('Manage task todos');
+    const todoCmd = task.command("todo").description("Manage task todos");
     // kspec task todo add <ref> <text>
-    todoCmd
-        .command('add <ref> <text>')
-        .description('Add a todo to a task')
-        .option('--author <author>', 'Todo author')
+    markMutating(todoCmd.command("add <ref> <text>"))
+        .description("Add a todo to a task")
+        .option("--author <author>", "Todo author")
         .action(async (ref, text, options) => {
         try {
             const ctx = await initContext();
@@ -1410,7 +1631,7 @@ export function registerTaskCommands(program) {
             const foundTask = resolveTaskRef(ref, tasks, index);
             // Calculate next ID (max existing + 1, or 1 if none)
             const nextId = foundTask.todos.length > 0
-                ? Math.max(...foundTask.todos.map(t => t.id)) + 1
+                ? Math.max(...foundTask.todos.map((t) => t.id)) + 1
                 : 1;
             const todo = createTodo(nextId, text, options.author);
             const updatedTask = {
@@ -1418,7 +1639,7 @@ export function registerTaskCommands(program) {
                 todos: [...foundTask.todos, todo],
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-note', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            await commitIfShadow(ctx.shadow, "task-note", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
             success(`Added todo #${todo.id} to task: ${index.shortUlid(updatedTask._ulid)}`, { todo });
         }
         catch (err) {
@@ -1427,9 +1648,8 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task todo done <ref> <id>
-    todoCmd
-        .command('done <ref> <id>')
-        .description('Mark a todo as done')
+    markMutating(todoCmd.command("done <ref> <id>"))
+        .description("Mark a todo as done")
         .action(async (ref, idStr) => {
         try {
             const ctx = await initContext();
@@ -1438,11 +1658,11 @@ export function registerTaskCommands(program) {
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
             const id = parseInt(idStr, 10);
-            if (isNaN(id)) {
+            if (Number.isNaN(id)) {
                 error(errors.todo.invalidId(idStr));
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
-            const todoIndex = foundTask.todos.findIndex(t => t.id === id);
+            const todoIndex = foundTask.todos.findIndex((t) => t.id === id);
             if (todoIndex === -1) {
                 error(errors.todo.notFound(id));
                 process.exit(EXIT_CODES.NOT_FOUND);
@@ -1462,8 +1682,10 @@ export function registerTaskCommands(program) {
                 todos: updatedTodos,
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-note', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Marked todo #${id} as done`, { todo: updatedTodos[todoIndex] });
+            await commitIfShadow(ctx.shadow, "task-note", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Marked todo #${id} as done`, {
+                todo: updatedTodos[todoIndex],
+            });
         }
         catch (err) {
             error(errors.failures.markTodoDone, err);
@@ -1471,9 +1693,8 @@ export function registerTaskCommands(program) {
         }
     });
     // kspec task todo undone <ref> <id>
-    todoCmd
-        .command('undone <ref> <id>')
-        .description('Mark a todo as not done')
+    markMutating(todoCmd.command("undone <ref> <id>"))
+        .description("Mark a todo as not done")
         .action(async (ref, idStr) => {
         try {
             const ctx = await initContext();
@@ -1482,11 +1703,11 @@ export function registerTaskCommands(program) {
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
             const id = parseInt(idStr, 10);
-            if (isNaN(id)) {
+            if (Number.isNaN(id)) {
                 error(errors.todo.invalidId(idStr));
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
-            const todoIndex = foundTask.todos.findIndex(t => t.id === id);
+            const todoIndex = foundTask.todos.findIndex((t) => t.id === id);
             if (todoIndex === -1) {
                 error(errors.todo.notFound(id));
                 process.exit(EXIT_CODES.NOT_FOUND);
@@ -1506,8 +1727,10 @@ export function registerTaskCommands(program) {
                 todos: updatedTodos,
             };
             await saveTask(ctx, updatedTask);
-            await commitIfShadow(ctx.shadow, 'task-note', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            success(`Marked todo #${id} as not done`, { todo: updatedTodos[todoIndex] });
+            await commitIfShadow(ctx.shadow, "task-note", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            success(`Marked todo #${id} as not done`, {
+                todo: updatedTodos[todoIndex],
+            });
         }
         catch (err) {
             error(errors.failures.markTodoNotDone, err);