@kynetic-ai/spec 0.9.1 → 0.11.0

package/dist/cli/commands/task.js

@@ -1,6 +1,6 @@
 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 { checkSlugUniqueness, createNote, createTask, createTodo, deleteTask, getAuthor, initContext, loadAllItems, loadAllTasks, mutateTaskAtomically, ReferenceIndex, saveTask, scanTestCoverage, syncSpecImplementationStatus, } from "../../parser/index.js";
 import { commitIfShadow } from "../../parser/shadow.js";
 import { normalizeRefInput } from "../../schema/index.js";
 import { alignmentCheck, errors } from "../../strings/index.js";
@@ -13,6 +13,55 @@ import { parsePriority, validateEnumOption, validateSpecRef, } from "../validato
 import { addListOptions, listTasksAction } from "./tasks.js";
 import { findClosestCommand } from "../suggest.js";
 import { checkBudget, incrementBudget, isEndLoopRequested } from "../../sessions/store.js";
+import { PidFileManager } from "../pid-utils.js";
+/**
+ * Post a task state change event to the daemon dispatch engine.
+ * Fails silently — dispatch requires a running daemon; if absent, this is a no-op.
+ * AC: @daemon-agent-dispatch ac-2, ac-7
+ * AC: @agent-dispatch-engine ac-18
+ */
+async function postDispatchEvent(opts) {
+    // AC: @agent-dispatch-engine ac-18 - Suppress self-triggering when running
+    // inside a dispatched agent invocation. The file watcher will independently
+    // detect the change, so the CLI event would be redundant and causes stale
+    // queue entries to accumulate.
+    // NOTE: This relies on the daemon's file watcher being active. If the watcher
+    // is temporarily down, dispatched agents' task mutations won't produce dispatch
+    // events until the watcher recovers and diffs the changed state.
+    if (process.env.KSPEC_SESSION_ID)
+        return;
+    const pidManager = new PidFileManager();
+    if (!pidManager.isDaemonRunning())
+        return;
+    let port;
+    try {
+        port = pidManager.readPort();
+    }
+    catch {
+        return; // Daemon running but port unreadable — silent fail
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts.projectPath) {
+        headers['X-Kspec-Dir'] = opts.projectPath;
+    }
+    try {
+        await fetch(`http://localhost:${port}/api/agent/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                task_id: opts.taskId,
+                task_ref: opts.taskRef,
+                from_status: opts.fromStatus,
+                to_status: opts.toStatus,
+                timestamp: Date.now(),
+            }),
+            signal: AbortSignal.timeout(1000), // 1s timeout — fire-and-forget
+        });
+    }
+    catch {
+        // Silent fail — daemon unreachable or dispatch engine not running
+    }
+}
 /**
  * Find a task by reference with detailed error reporting.
  * Returns the task or exits with appropriate error.
@@ -97,20 +146,11 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                 };
             }
         }
-        // Build updated task with only provided options
-        const updatedTask = { ...foundTask };
         const changes = [];
-        if (options.title) {
-            updatedTask.title = options.title;
-            changes.push("title");
-        }
+        let noChangesMessage;
         if (options.specRef !== undefined) {
             // Handle 'null' string to clear spec_ref
-            if (options.specRef === "null") {
-                updatedTask.spec_ref = null;
-                changes.push("spec_ref: cleared");
-            }
-            else {
+            if (options.specRef !== "null") {
                 // Validate the spec ref exists and is a spec item
                 const specResult = index.resolve(options.specRef);
                 if (!specResult.ok) {
@@ -127,17 +167,11 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                         error: errors.reference.specRefIsTask(options.specRef),
                     };
                 }
-                updatedTask.spec_ref = normalizeRefInput(options.specRef);
-                changes.push("spec_ref");
             }
         }
         if (options.metaRef !== undefined) {
             // Handle 'null' string to clear meta_ref
-            if (options.metaRef === "null") {
-                updatedTask.meta_ref = null;
-                changes.push("meta_ref: cleared");
-            }
-            else {
+            if (options.metaRef !== "null") {
                 // Validate the meta ref exists and is a meta item
                 const metaRefResult = index.resolve(options.metaRef);
                 if (!metaRefResult.ok) {
@@ -155,17 +189,11 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                         error: errors.reference.metaRefPointsToSpec(options.metaRef),
                     };
                 }
-                updatedTask.meta_ref = normalizeRefInput(options.metaRef);
-                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 {
+            if (options.planRef !== "null") {
                 // First check if it's a task or spec item (wrong type)
                 const cleanRef = options.planRef.startsWith("@")
                     ? options.planRef.slice(1)
@@ -191,32 +219,26 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                         error: `Plan reference not found: ${options.planRef}`,
                     };
                 }
-                updatedTask.plan_ref = normalizeRefInput(options.planRef);
-                changes.push("plan_ref");
             }
         }
+        // Validate review URL if provided and not clearing
+        if (options.reviewUrl !== undefined && options.reviewUrl !== "null") {
+            try {
+                new URL(options.reviewUrl);
+            }
+            catch {
+                return { success: false, error: `Invalid review URL: ${options.reviewUrl}` };
+            }
+        }
+        let parsedPriority;
         if (options.priority) {
             const priorityResult = parsePriority(options.priority);
             if (!priorityResult.ok) {
                 return { success: false, error: priorityResult.error };
             }
-            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");
-            }
-        }
-        if (options.tag) {
-            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");
-            }
+            parsedPriority = priorityResult.value;
         }
+        const parsedTags = options.tag ? parseTagsArray(options.tag) : [];
         if (options.dependsOn) {
             // Validate all dependency refs
             for (const depRef of options.dependsOn) {
@@ -236,34 +258,12 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                     };
                 }
             }
-            updatedTask.depends_on = options.dependsOn.map(normalizeRefInput);
-            changes.push("depends_on");
-        }
-        // AC: @spec-task-clear-deps ac-1, ac-2 - Clear all dependencies
-        if (options.clearDeps) {
-            if (foundTask.depends_on.length === 0) {
-                // AC: @spec-task-clear-deps ac-2 - No changes needed
-                return {
-                    success: true,
-                    message: "No changes: task has no dependencies to clear",
-                };
-            }
-            updatedTask.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(ctx.config?.identity?.author));
-            updatedTask.notes = [...updatedTask.notes, note];
         }
         // AC: @task-automation-eligibility ac-5, ac-11, ac-12, ac-18
         // Handle automation status changes
         // Note: --no-automation sets options.automation to false, so check that first
-        if (options.automation === false) {
-            // --no-automation flag clears the automation status (AC: ac-12)
-            delete updatedTask.automation;
-            changes.push("automation");
-        }
-        else if (options.automation !== undefined) {
+        let validatedAutomation;
+        if (options.automation !== undefined && options.automation !== false) {
             const automationResult = validateEnumOption(options.automation, ["eligible", "needs_review", "manual_only"], "automation status");
             if (!automationResult.ok) {
                 return { success: false, error: automationResult.error };
@@ -275,15 +275,119 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                     error: "Setting automation to needs_review requires --reason flag explaining why",
                 };
             }
-            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 ${automationResult.value}: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
-                updatedTask.notes = [...updatedTask.notes, note];
-                changes.push("note");
+            validatedAutomation = automationResult.value;
+        }
+        let updatedTask = foundTask;
+        updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+            const nextTask = { ...latestTask };
+            const mutationChanges = [];
+            if (options.title) {
+                nextTask.title = options.title;
+                mutationChanges.push("title");
+            }
+            if (options.description !== undefined) {
+                if (options.description === "null" || options.description.trim() === "") {
+                    delete nextTask.description;
+                    mutationChanges.push("description: cleared");
+                }
+                else {
+                    nextTask.description = options.description;
+                    mutationChanges.push("description");
+                }
+            }
+            if (options.specRef !== undefined) {
+                if (options.specRef === "null") {
+                    nextTask.spec_ref = null;
+                    mutationChanges.push("spec_ref: cleared");
+                }
+                else {
+                    nextTask.spec_ref = normalizeRefInput(options.specRef);
+                    mutationChanges.push("spec_ref");
+                }
+            }
+            if (options.metaRef !== undefined) {
+                if (options.metaRef === "null") {
+                    nextTask.meta_ref = null;
+                    mutationChanges.push("meta_ref: cleared");
+                }
+                else {
+                    nextTask.meta_ref = normalizeRefInput(options.metaRef);
+                    mutationChanges.push("meta_ref");
+                }
+            }
+            if (options.planRef !== undefined) {
+                if (options.planRef === "null") {
+                    nextTask.plan_ref = null;
+                    mutationChanges.push("plan_ref: cleared");
+                }
+                else {
+                    nextTask.plan_ref = normalizeRefInput(options.planRef);
+                    mutationChanges.push("plan_ref");
+                }
             }
+            if (options.reviewUrl !== undefined) {
+                if (options.reviewUrl === "null") {
+                    delete nextTask.review_url;
+                    mutationChanges.push("review_url: cleared");
+                }
+                else {
+                    nextTask.review_url = options.reviewUrl;
+                    mutationChanges.push("review_url");
+                }
+            }
+            if (parsedPriority !== undefined) {
+                nextTask.priority = parsedPriority;
+                mutationChanges.push("priority");
+            }
+            if (options.slug && !nextTask.slugs.includes(options.slug)) {
+                nextTask.slugs = [...nextTask.slugs, options.slug];
+                mutationChanges.push("slug");
+            }
+            if (parsedTags.length > 0) {
+                const newTags = parsedTags.filter((tag) => !nextTask.tags.includes(tag));
+                if (newTags.length > 0) {
+                    nextTask.tags = [...nextTask.tags, ...newTags];
+                    mutationChanges.push("tags");
+                }
+            }
+            if (options.dependsOn) {
+                nextTask.depends_on = options.dependsOn.map(normalizeRefInput);
+                mutationChanges.push("depends_on");
+            }
+            if (options.clearDeps) {
+                if (latestTask.depends_on.length === 0) {
+                    // AC: @spec-task-clear-deps ac-2 - No changes needed
+                    noChangesMessage = "No changes: task has no dependencies to clear";
+                    return latestTask;
+                }
+                nextTask.depends_on = [];
+                mutationChanges.push("depends_on");
+                // AC: @task-set ac-author
+                const note = createNote(`Dependencies cleared (was: ${latestTask.depends_on.join(", ")})`, getAuthor(ctx.config?.identity?.author));
+                nextTask.notes = [...nextTask.notes, note];
+            }
+            if (options.automation === false) {
+                delete nextTask.automation;
+                mutationChanges.push("automation");
+            }
+            else if (validatedAutomation) {
+                nextTask.automation = validatedAutomation;
+                mutationChanges.push("automation");
+                if (options.reason) {
+                    const note = createNote(`Automation status set to ${validatedAutomation}: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
+                    nextTask.notes = [...nextTask.notes, note];
+                    mutationChanges.push("note");
+                }
+            }
+            changes.splice(0, changes.length, ...mutationChanges);
+            return nextTask;
+        });
+        if (noChangesMessage) {
+            return {
+                success: true,
+                message: noChangesMessage,
+                data: { task: updatedTask },
+            };
         }
         // AC: @spec-task-set-batch ac-4 - Warn on no changes, don't fail
         if (changes.length === 0) {
@@ -293,7 +397,6 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                 data: { task: updatedTask },
             };
         }
-        await saveTask(ctx, updatedTask);
         await commitIfShadow(ctx.shadow, "task-set", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(", "));
         return {
             success: true,
@@ -592,9 +695,11 @@ Examples:
         .description("Update task fields")
         .option("--refs <refs...>", "Update multiple tasks (AC: @spec-task-set-batch ac-1)")
         .option("--title <title>", "Update task title")
+        .option("--description <description>", "Update task description (use 'null' to clear)")
         .option("--spec-ref <ref>", "Link to spec item (use 'null' to clear)")
         .option("--meta-ref <ref>", "Link to meta item (use 'null' to clear)")
         .option("--plan-ref <ref>", "Link to plan (use 'null' to clear)")
+        .option("--review-url <url>", "Set review URL (use 'null' to clear)")
         .option("--priority <n>", "Set priority (1-5 or P1-P5)")
         .option("--slug <slug>", "Add a slug alias")
         .option("--tag <tag...>", "Add tags")
@@ -607,6 +712,7 @@ Examples:
         .addHelpText("after", `
 Examples:
   $ kspec task set @task-slug --priority 2
+  $ kspec task set @task-slug --description "Updated context"
   $ 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`)
@@ -771,20 +877,22 @@ Examples:
                     process.exit(EXIT_CODES.ERROR);
                 }
             }
-            // Build updated task
-            const updatedTask = { ...foundTask, ...validatedPatch };
             // Track changes for output
             const changes = Object.keys(validatedPatch);
             if (options.dryRun) {
+                const dryRunTask = { ...foundTask, ...validatedPatch };
                 info("Dry run - no changes will be written");
                 info(`Would update: ${changes.join(", ")}`);
-                output({ changes, updated: updatedTask }, () => {
+                output({ changes, updated: dryRunTask }, () => {
                     console.log(`\nChanges: ${changes.join(", ")}\n`);
-                    return formatTaskDetails(updatedTask, index);
+                    return formatTaskDetails(dryRunTask, index);
                 });
                 return;
             }
-            await saveTask(ctx, updatedTask);
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => ({
+                ...latestTask,
+                ...validatedPatch,
+            }));
             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 });
         }
@@ -830,30 +938,47 @@ Examples:
                     process.exit(EXIT_CODES.VALIDATION_FAILED);
                 }
             }
-            // AC: @task-budget-enforcement ac-block-start, ac-no-session, ac-no-budget
-            // Check budget before starting — only when session is set
-            const budgetCheck = await checkBudget(ctx.specDir, sessionId || undefined);
-            if (!budgetCheck.allowed) {
-                error(budgetCheck.reason);
-                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            // AC: @task-budget-enforcement ac-block-start, ac-no-session, ac-no-budget, ac-needs-work-no-increment
+            // Check budget before starting — only when session is set.
+            // Skip budget check for needs_work→in_progress (fix cycles): the task
+            // already consumed a budget slot when originally started; blocking it
+            // would prevent completing already-assigned work.
+            if (foundTask.status !== "needs_work") {
+                const budgetCheck = await checkBudget(ctx.specDir, sessionId || undefined);
+                if (!budgetCheck.allowed) {
+                    error(budgetCheck.reason);
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
             }
             // Update status
             // AC: @session-scoped-task-claiming ac-stamp, ac-no-env
-            const updatedTask = {
-                ...foundTask,
-                status: "in_progress",
-                started_at: new Date().toISOString(),
-                ...(sessionId ? { session_id: sessionId } : {}),
-            };
-            await saveTask(ctx, updatedTask);
+            let transitionFromStatus = foundTask.status;
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                transitionFromStatus = latestTask.status;
+                return {
+                    ...latestTask,
+                    status: "in_progress",
+                    started_at: new Date().toISOString(),
+                    ...(sessionId ? { session_id: sessionId } : {}),
+                };
+            });
             await commitIfShadow(ctx.shadow, "task-start", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
-            // AC: @task-budget-enforcement ac-increment, ac-resume-no-increment
-            // Increment budget counter after successful start.
-            // Resume case (already in_progress) returns early above, so this only
-            // runs for genuine pending→in_progress or needs_work→in_progress transitions.
-            if (sessionId) {
+            // AC: @task-budget-enforcement ac-increment, ac-resume-no-increment, ac-needs-work-no-increment
+            // Increment budget counter after successful start, but only for
+            // genuine pending→in_progress transitions. Resume case returns early
+            // above. needs_work→in_progress is a fix cycle (task already consumed
+            // a budget slot when originally started) — don't double-count it.
+            if (sessionId && transitionFromStatus === "pending") {
                 await incrementBudget(ctx.specDir, sessionId);
             }
+            // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+            postDispatchEvent({
+                taskId: updatedTask._ulid,
+                taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                fromStatus: transitionFromStatus,
+                toStatus: updatedTask.status,
+                projectPath: ctx.rootDir,
+            });
             success(`Started task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
             });
@@ -940,89 +1065,82 @@ Examples:
                 },
                 executeOperation: async (foundTask, { ctx, tasks, items, index, options }) => {
                     try {
-                        // AC: @spec-completion-enforcement ac-6
-                        if (foundTask.status === "completed") {
-                            return {
-                                success: false,
-                                error: errors.status.completeAlreadyCompleted,
-                            };
-                        }
-                        // AC: @task-commands ac-1 - Allow --force to bypass all state checks
                         const forcingCompletion = options.force;
-                        // AC: @spec-completion-enforcement ac-7 - Allow skip-review bypass
-                        if (!options.skipReview && !forcingCompletion) {
-                            // AC: @spec-completion-enforcement ac-2
-                            if (foundTask.status === "in_progress") {
-                                return {
-                                    success: false,
-                                    error: errors.status.completeRequiresReview,
-                                };
-                            }
-                            // AC: @spec-completion-enforcement ac-3
-                            if (foundTask.status === "pending") {
-                                return {
-                                    success: false,
-                                    error: errors.status.completeRequiresStart,
-                                };
-                            }
-                            // AC: @spec-completion-enforcement ac-4
-                            if (foundTask.status === "blocked") {
-                                return {
-                                    success: false,
-                                    error: errors.status.completeBlockedTask,
-                                };
-                            }
-                            // AC: @spec-completion-enforcement ac-5
-                            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") {
-                                return {
-                                    success: false,
-                                    error: errors.status.cannotComplete(foundTask.status),
-                                };
-                            }
-                        }
                         const now = new Date().toISOString();
-                        // AC: @spec-completion-enforcement ac-7 - Document skip-review reason
-                        // 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(ctx.config?.identity?.author));
-                            taskNotes = [...taskNotes, skipNote];
-                        }
-                        // AC: @task-commands ac-1 - Document force completion from non-standard state
-                        const forcedFromNonStandard = forcingCompletion &&
-                            foundTask.status !== "pending_review";
+                        let transitionFromStatus = foundTask.status;
+                        let forcedFromNonStandard = false;
                         let forceStateDetail;
-                        if (forcedFromNonStandard) {
-                            forceStateDetail = `from ${foundTask.status} state`;
-                            if (foundTask.status === "blocked") {
-                                const blockedBy = foundTask.blocked_by.join("; ");
-                                forceStateDetail += `. Was blocked by: ${blockedBy || "(dependency-blocked)"}`;
+                        const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                            transitionFromStatus = latestTask.status;
+                            // AC: @spec-completion-enforcement ac-6
+                            if (latestTask.status === "completed") {
+                                throw new Error(errors.status.completeAlreadyCompleted);
                             }
-                            let forceMessage = `Completed with --force ${forceStateDetail}`;
-                            if (options.reason) {
-                                forceMessage += `. Reason: ${options.reason}`;
+                            // AC: @spec-completion-enforcement ac-7 - Allow skip-review bypass
+                            if (!options.skipReview && !forcingCompletion) {
+                                // AC: @spec-completion-enforcement ac-2
+                                if (latestTask.status === "in_progress") {
+                                    throw new Error(errors.status.completeRequiresReview);
+                                }
+                                // AC: @spec-completion-enforcement ac-3
+                                if (latestTask.status === "pending") {
+                                    throw new Error(errors.status.completeRequiresStart);
+                                }
+                                // AC: @spec-completion-enforcement ac-4
+                                if (latestTask.status === "blocked") {
+                                    throw new Error(errors.status.completeBlockedTask);
+                                }
+                                // AC: @spec-completion-enforcement ac-5
+                                if (latestTask.status === "cancelled") {
+                                    throw new Error(errors.status.completeCancelledTask);
+                                }
+                                // AC: @spec-completion-enforcement ac-1 - Only pending_review allowed
+                                if (latestTask.status !== "pending_review") {
+                                    throw new Error(errors.status.cannotComplete(latestTask.status));
+                                }
                             }
-                            const forceNote = createNote(forceMessage, getAuthor(ctx.config?.identity?.author));
-                            taskNotes = [...taskNotes, forceNote];
-                        }
-                        // Update status
-                        const updatedTask = {
-                            ...foundTask,
-                            status: "completed",
-                            completed_at: now,
-                            closed_reason: options.reason || null,
-                            started_at: foundTask.started_at || now,
-                            notes: taskNotes,
-                        };
-                        await saveTask(ctx, updatedTask);
+                            // AC: @spec-completion-enforcement ac-7 - Document skip-review reason
+                            // AC: @spec-completion-enforcement ac-author
+                            let taskNotes = latestTask.notes;
+                            if (options.skipReview && options.reason) {
+                                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 from non-standard state
+                            forcedFromNonStandard =
+                                forcingCompletion &&
+                                    latestTask.status !== "pending_review";
+                            if (forcedFromNonStandard) {
+                                forceStateDetail = `from ${latestTask.status} state`;
+                                if (latestTask.status === "blocked") {
+                                    const blockedBy = latestTask.blocked_by.join("; ");
+                                    forceStateDetail += `. Was blocked by: ${blockedBy || "(dependency-blocked)"}`;
+                                }
+                                let forceMessage = `Completed with --force ${forceStateDetail}`;
+                                if (options.reason) {
+                                    forceMessage += `. Reason: ${options.reason}`;
+                                }
+                                const forceNote = createNote(forceMessage, getAuthor(ctx.config?.identity?.author));
+                                taskNotes = [...taskNotes, forceNote];
+                            }
+                            return {
+                                ...latestTask,
+                                status: "completed",
+                                completed_at: now,
+                                closed_reason: options.reason || null,
+                                started_at: latestTask.started_at || now,
+                                notes: taskNotes,
+                            };
+                        });
                         await commitIfShadow(ctx.shadow, "task-complete", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), options.reason);
+                        // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+                        postDispatchEvent({
+                            taskId: updatedTask._ulid,
+                            taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                            fromStatus: transitionFromStatus,
+                            toStatus: updatedTask.status,
+                            projectPath: ctx.rootDir,
+                        });
                         // 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);
@@ -1089,26 +1207,54 @@ Examples:
     });
     // kspec task submit <ref>
     // Transitions in_progress → pending_review (code done, awaiting merge)
+    // AC: @task-submit ac-submit-1, ac-submit-2, ac-submit-3
     markMutating(task.command("submit <ref>"))
         .description("Submit task for review (transitions to pending_review)")
-        .action(async (ref) => {
+        .option("--review-url <url>", "PR or review URL")
+        .action(async (ref, options) => {
         try {
+            // AC: @task-submit ac-submit-3 - Validate URL before any state change
+            if (options.reviewUrl !== undefined) {
+                try {
+                    new URL(options.reviewUrl);
+                }
+                catch {
+                    error(`Invalid review URL: ${options.reviewUrl}`);
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+            }
             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 !== "in_progress") {
-                error(`Cannot submit task with status: ${foundTask.status}. Task must be in_progress.`);
+            let transitionFromStatus = foundTask.status;
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                transitionFromStatus = latestTask.status;
+                if (latestTask.status !== "in_progress") {
+                    return latestTask;
+                }
+                return {
+                    ...latestTask,
+                    status: "pending_review",
+                    submitted_at: new Date().toISOString(),
+                    // AC: @task-submit ac-submit-2
+                    ...(options.reviewUrl !== undefined && { review_url: options.reviewUrl }),
+                };
+            });
+            if (transitionFromStatus !== "in_progress") {
+                error(`Cannot submit task with status: ${transitionFromStatus}. Task must be in_progress.`);
                 process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
-            const updatedTask = {
-                ...foundTask,
-                status: "pending_review",
-                submitted_at: new Date().toISOString(),
-            };
-            await saveTask(ctx, updatedTask);
             await commitIfShadow(ctx.shadow, "task-submit", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+            postDispatchEvent({
+                taskId: updatedTask._ulid,
+                taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                fromStatus: transitionFromStatus,
+                toStatus: updatedTask.status,
+                projectPath: ctx.rootDir,
+            });
             success(`Submitted task for review: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
         }
         catch (err) {
@@ -1128,23 +1274,38 @@ Examples:
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status !== "pending_review") {
-                error(errors.status.cannotNeedsWork(foundTask.status));
+            let transitionFromStatus = foundTask.status;
+            let cycleNumber = 0;
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                transitionFromStatus = latestTask.status;
+                if (latestTask.status !== "pending_review") {
+                    return latestTask;
+                }
+                // Track fix cycle count from existing kickback notes
+                const existingKickbacks = latestTask.notes.filter((note) => note.content.includes("[FIX_CYCLE:")).length;
+                cycleNumber = existingKickbacks + 1;
+                const note = createNote(`[FIX_CYCLE: ${cycleNumber}] Review findings: ${options.reason}`, getAuthor(ctx.config?.identity?.author));
+                // AC: @session-scoped-task-claiming ac-claim-clear
+                return {
+                    ...latestTask,
+                    status: "needs_work",
+                    session_id: null,
+                    notes: [...latestTask.notes, note],
+                };
+            });
+            if (transitionFromStatus !== "pending_review") {
+                error(errors.status.cannotNeedsWork(transitionFromStatus));
                 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));
-            // AC: @session-scoped-task-claiming ac-claim-clear
-            const updatedTask = {
-                ...foundTask,
-                status: "needs_work",
-                session_id: null,
-                notes: [...foundTask.notes, note],
-            };
-            await saveTask(ctx, updatedTask);
             await commitIfShadow(ctx.shadow, "task-needs-work", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), `cycle ${cycleNumber}`);
+            // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+            postDispatchEvent({
+                taskId: updatedTask._ulid,
+                taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                fromStatus: transitionFromStatus,
+                toStatus: updatedTask.status,
+                projectPath: ctx.rootDir,
+            });
             success(`Kicked back task: ${index.shortUlid(updatedTask._ulid)} (fix cycle ${cycleNumber})`, { task: updatedTask });
         }
         catch (err) {
@@ -1163,18 +1324,33 @@ Examples:
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status === "completed" ||
-                foundTask.status === "cancelled") {
-                error(errors.status.cannotBlock(foundTask.status));
+            let transitionFromStatus = foundTask.status;
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                transitionFromStatus = latestTask.status;
+                if (latestTask.status === "completed" ||
+                    latestTask.status === "cancelled") {
+                    return latestTask;
+                }
+                return {
+                    ...latestTask,
+                    status: "blocked",
+                    blocked_by: [...latestTask.blocked_by, options.reason],
+                };
+            });
+            if (transitionFromStatus === "completed" ||
+                transitionFromStatus === "cancelled") {
+                error(errors.status.cannotBlock(transitionFromStatus));
                 process.exit(EXIT_CODES.VALIDATION_FAILED);
             }
-            const updatedTask = {
-                ...foundTask,
-                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));
+            // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+            postDispatchEvent({
+                taskId: updatedTask._ulid,
+                taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                fromStatus: transitionFromStatus,
+                toStatus: updatedTask.status,
+                projectPath: ctx.rootDir,
+            });
             success(`Blocked task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
             });
@@ -1194,19 +1370,33 @@ Examples:
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
-            if (foundTask.status !== "blocked") {
+            let transitionFromStatus = foundTask.status;
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                transitionFromStatus = latestTask.status;
+                if (latestTask.status !== "blocked") {
+                    return latestTask;
+                }
+                // AC: @session-scoped-task-claiming ac-claim-clear
+                return {
+                    ...latestTask,
+                    status: "pending",
+                    blocked_by: [],
+                    session_id: null,
+                };
+            });
+            if (transitionFromStatus !== "blocked") {
                 warn("Task is not blocked");
                 return;
             }
-            // AC: @session-scoped-task-claiming ac-claim-clear
-            const updatedTask = {
-                ...foundTask,
-                status: "pending",
-                blocked_by: [],
-                session_id: null,
-            };
-            await saveTask(ctx, updatedTask);
             await commitIfShadow(ctx.shadow, "task-unblock", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+            // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
+            postDispatchEvent({
+                taskId: updatedTask._ulid,
+                taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
+                fromStatus: transitionFromStatus,
+                toStatus: updatedTask.status,
+                projectPath: ctx.rootDir,
+            });
             success(`Unblocked task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
             });
@@ -1291,54 +1481,60 @@ Examples:
             const items = await loadAllItems(ctx);
             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") {
+            let previousStatus = foundTask.status;
+            const clearedFields = [];
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                previousStatus = latestTask.status;
+                // AC: @spec-task-reset ac-2 - Error if already pending
+                if (latestTask.status === "pending") {
+                    return latestTask;
+                }
+                // AC: @spec-task-reset ac-1 - Reset to pending, clear completion-related fields
+                const nextTask = {
+                    ...latestTask,
+                    status: "pending",
+                };
+                clearedFields.splice(0, clearedFields.length);
+                // Clear timestamps and reasons based on previous status
+                if (latestTask.completed_at !== undefined &&
+                    latestTask.completed_at !== null) {
+                    nextTask.completed_at = null;
+                    clearedFields.push("completed_at");
+                }
+                if (latestTask.started_at !== undefined &&
+                    latestTask.started_at !== null) {
+                    nextTask.started_at = null;
+                    clearedFields.push("started_at");
+                }
+                if (latestTask.closed_reason !== undefined &&
+                    latestTask.closed_reason !== null) {
+                    nextTask.closed_reason = null;
+                    clearedFields.push("closed_reason");
+                }
+                if (latestTask.blocked_by.length > 0) {
+                    nextTask.blocked_by = [];
+                    clearedFields.push("blocked_by");
+                }
+                // AC: @session-scoped-task-claiming ac-claim-clear
+                if (latestTask.session_id) {
+                    nextTask.session_id = null;
+                    clearedFields.push("session_id");
+                }
+                // AC: @spec-task-reset ac-4 - Add note documenting the reset
+                // AC: @spec-task-reset ac-author
+                const hadCancelReason = latestTask.closed_reason && latestTask.status === "cancelled";
+                const cancelReasonText = hadCancelReason
+                    ? ` (was cancelled: ${latestTask.closed_reason})`
+                    : "";
+                const noteContent = `Reset from ${latestTask.status} to pending${cancelReasonText}`;
+                const note = createNote(noteContent, getAuthor(ctx.config?.identity?.author));
+                nextTask.notes = [...nextTask.notes, note];
+                return nextTask;
+            });
+            if (previousStatus === "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})`
-                : "";
-            // AC: @spec-task-reset ac-1 - Reset to pending, clear completion-related fields
-            const clearedFields = [];
-            const updatedTask = {
-                ...foundTask,
-                status: "pending",
-            };
-            // Clear timestamps and reasons based on previous status
-            if (foundTask.completed_at !== undefined &&
-                foundTask.completed_at !== null) {
-                updatedTask.completed_at = null;
-                clearedFields.push("completed_at");
-            }
-            if (foundTask.started_at !== undefined &&
-                foundTask.started_at !== null) {
-                updatedTask.started_at = null;
-                clearedFields.push("started_at");
-            }
-            if (foundTask.closed_reason !== undefined &&
-                foundTask.closed_reason !== null) {
-                updatedTask.closed_reason = null;
-                clearedFields.push("closed_reason");
-            }
-            if (foundTask.blocked_by.length > 0) {
-                updatedTask.blocked_by = [];
-                clearedFields.push("blocked_by");
-            }
-            // AC: @session-scoped-task-claiming ac-claim-clear
-            if (foundTask.session_id) {
-                updatedTask.session_id = null;
-                clearedFields.push("session_id");
-            }
-            // 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(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}`);
             // AC: @spec-task-reset ac-6 - JSON output includes previous_status, new_status, cleared_fields
@@ -1459,11 +1655,10 @@ Examples:
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
             const note = createNote(message, options.author, options.supersedes);
-            const updatedTask = {
-                ...foundTask,
-                notes: [...foundTask.notes, note],
-            };
-            await saveTask(ctx, updatedTask);
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => ({
+                ...latestTask,
+                notes: [...latestTask.notes, note],
+            }));
             await commitIfShadow(ctx.shadow, "task-note", foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
             success(`Added note to task: ${index.shortUlid(updatedTask._ulid)}`, {
                 note,
@@ -1561,8 +1756,11 @@ Examples:
                                 possibleRefs.push(`@${specItem.slugs[0]} ${ac.id}`);
                                 possibleRefs.push(`@${specItem.slugs[0]}`);
                             }
-                            possibleRefs.push(`@${specItem._ulid.slice(0, 8)} ${ac.id}`);
-                            possibleRefs.push(`@${specItem._ulid.slice(0, 8)}`);
+                            for (let prefixLength = 8; prefixLength <= specItem._ulid.length; prefixLength++) {
+                                const prefix = specItem._ulid.slice(0, prefixLength);
+                                possibleRefs.push(`@${prefix} ${ac.id}`);
+                                possibleRefs.push(`@${prefix}`);
+                            }
                             const isCovered = possibleRefs.some((ref) => coveredACs.has(ref));
                             if (isCovered) {
                                 covered.push(ac.id);
@@ -1701,16 +1899,18 @@ Examples:
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             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
-                : 1;
-            const todo = createTodo(nextId, text, options.author);
-            const updatedTask = {
-                ...foundTask,
-                todos: [...foundTask.todos, todo],
-            };
-            await saveTask(ctx, updatedTask);
+            let todo = createTodo(1, text, options.author);
+            const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                // Calculate next ID (max existing + 1, or 1 if none)
+                const nextId = latestTask.todos.length > 0
+                    ? Math.max(...latestTask.todos.map((entry) => entry.id)) + 1
+                    : 1;
+                todo = createTodo(nextId, text, options.author);
+                return {
+                    ...latestTask,
+                    todos: [...latestTask.todos, todo],
+                };
+            });
             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 });
         }
@@ -1734,29 +1934,42 @@ Examples:
                 error(errors.todo.invalidId(idStr));
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
-            const todoIndex = foundTask.todos.findIndex((t) => t.id === id);
-            if (todoIndex === -1) {
+            let todoState;
+            let updatedTodo;
+            await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                const todoIndex = latestTask.todos.findIndex((todo) => todo.id === id);
+                if (todoIndex === -1) {
+                    todoState = "not_found";
+                    return latestTask;
+                }
+                if (latestTask.todos[todoIndex].done) {
+                    todoState = "already_done";
+                    updatedTodo = latestTask.todos[todoIndex];
+                    return latestTask;
+                }
+                const updatedTodos = [...latestTask.todos];
+                updatedTodos[todoIndex] = {
+                    ...updatedTodos[todoIndex],
+                    done: true,
+                    done_at: new Date().toISOString(),
+                };
+                updatedTodo = updatedTodos[todoIndex];
+                return {
+                    ...latestTask,
+                    todos: updatedTodos,
+                };
+            });
+            if (todoState === "not_found") {
                 error(errors.todo.notFound(id));
                 process.exit(EXIT_CODES.NOT_FOUND);
             }
-            if (foundTask.todos[todoIndex].done) {
+            if (todoState === "already_done") {
                 warn(`Todo #${id} is already done`);
                 return;
             }
-            const updatedTodos = [...foundTask.todos];
-            updatedTodos[todoIndex] = {
-                ...updatedTodos[todoIndex],
-                done: true,
-                done_at: new Date().toISOString(),
-            };
-            const updatedTask = {
-                ...foundTask,
-                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],
+                todo: updatedTodo,
             });
         }
         catch (err) {
@@ -1779,29 +1992,42 @@ Examples:
                 error(errors.todo.invalidId(idStr));
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
-            const todoIndex = foundTask.todos.findIndex((t) => t.id === id);
-            if (todoIndex === -1) {
+            let todoState;
+            let updatedTodo;
+            await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
+                const todoIndex = latestTask.todos.findIndex((todo) => todo.id === id);
+                if (todoIndex === -1) {
+                    todoState = "not_found";
+                    return latestTask;
+                }
+                if (!latestTask.todos[todoIndex].done) {
+                    todoState = "already_not_done";
+                    updatedTodo = latestTask.todos[todoIndex];
+                    return latestTask;
+                }
+                const updatedTodos = [...latestTask.todos];
+                updatedTodos[todoIndex] = {
+                    ...updatedTodos[todoIndex],
+                    done: false,
+                    done_at: undefined,
+                };
+                updatedTodo = updatedTodos[todoIndex];
+                return {
+                    ...latestTask,
+                    todos: updatedTodos,
+                };
+            });
+            if (todoState === "not_found") {
                 error(errors.todo.notFound(id));
                 process.exit(EXIT_CODES.NOT_FOUND);
             }
-            if (!foundTask.todos[todoIndex].done) {
+            if (todoState === "already_not_done") {
                 warn(`Todo #${id} is not done`);
                 return;
             }
-            const updatedTodos = [...foundTask.todos];
-            updatedTodos[todoIndex] = {
-                ...updatedTodos[todoIndex],
-                done: false,
-                done_at: undefined,
-            };
-            const updatedTask = {
-                ...foundTask,
-                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],
+                todo: updatedTodo,
             });
         }
         catch (err) {