@kynetic-ai/spec 0.11.0 → 0.12.0

package/dist/cli/commands/task.js

@@ -1,14 +1,16 @@
+import { execSync } from "node:child_process";
 import chalk from "chalk";
 import { markMutating } from "../command-annotations.js";
-import { checkSlugUniqueness, createNote, createTask, createTodo, deleteTask, getAuthor, initContext, loadAllItems, loadAllTasks, mutateTaskAtomically, ReferenceIndex, saveTask, scanTestCoverage, syncSpecImplementationStatus, } from "../../parser/index.js";
+import { checkSlugUniqueness, createNote, createTask, createTodo, deleteTask, findReviewByRef, getAuthor, initContext, loadAllItems, loadAllTasks, loadReviewRecords, 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";
 import { formatCommitGuidance, printCommitGuidance, } from "../../utils/commit.js";
+import { captureSubmissionLinkage, getCurrentBranch, isGitRepo } from "../../utils/git.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 { annotateNotesWithSuperseded, error, formatTaskDetails, info, isJsonMode, output, showChangeDiff, success, warn, } from "../output.js";
 import { parsePriority, validateEnumOption, validateSpecRef, } from "../validators.js";
 import { addListOptions, listTasksAction } from "./tasks.js";
 import { findClosestCommand } from "../suggest.js";
@@ -129,6 +131,120 @@ function resolveTaskRefForBatch(ref, tasks, index) {
     }
     return { task };
 }
+/**
+ * Compute the deterministic dispatch-compatible branch name for a task.
+ * Uses the exact `dispatch/task/<normalized-task-slug>/<short-task-ref>` naming contract.
+ * AC: @deterministic-task-branch-helper ac-1
+ */
+function computeDispatchBranchName(taskRef, task) {
+    const preferred = task?.slugs?.[0] ?? task?.title ?? taskRef.replace(/^@/, "task");
+    const slug = preferred
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/--+/g, "-") || "task";
+    const shortId = taskRef.replace(/^@/, "").slice(0, 8).toLowerCase();
+    return `dispatch/task/${slug}/${shortId}`;
+}
+/**
+ * Check if a git ref exists locally.
+ */
+function gitRefExists(ref) {
+    try {
+        execSync(`git show-ref --verify --quiet ${ref}`, { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List git remotes, with "origin" sorted first.
+ */
+function listRemotes() {
+    try {
+        const output = execSync("git remote", { encoding: "utf-8", stdio: "pipe" }).trim();
+        if (!output)
+            return [];
+        const remotes = output.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+        return [
+            ...remotes.filter((r) => r === "origin"),
+            ...remotes.filter((r) => r !== "origin"),
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find a branch on any configured remote. Returns the remote ref (e.g. "origin/branch")
+ * if found, null otherwise. Fetches from the remote to ensure refs are up to date.
+ */
+function findBranchOnRemote(branch) {
+    for (const remote of listRemotes()) {
+        // Fetch the branch from the remote (it may exist remotely but not be tracked locally)
+        try {
+            execSync(`git fetch ${remote} ${branch}`, { stdio: "pipe" });
+        }
+        catch {
+            // Fetch failed — branch may not exist on this remote
+        }
+        if (gitRefExists(`refs/remotes/${remote}/${branch}`)) {
+            return `${remote}/${branch}`;
+        }
+    }
+    return null;
+}
+/**
+ * Create a local branch from a remote tracking ref.
+ */
+function gitCreateBranchFrom(branch, startPoint) {
+    execSync(`git branch ${branch} ${startPoint}`, { stdio: "pipe" });
+}
+/**
+ * Switch to an existing branch.
+ */
+function gitCheckout(branch) {
+    execSync(`git checkout ${branch}`, { stdio: "pipe" });
+}
+/**
+ * Create and switch to a new branch.
+ */
+function gitCheckoutNew(branch) {
+    execSync(`git checkout -b ${branch}`, { stdio: "pipe" });
+}
+/**
+ * Report the result of the branch helper operation.
+ * AC: @deterministic-task-branch-helper ac-3
+ * AC: @trait-json-output ac-1, ac-2, ac-4
+ */
+function reportBranchResult(result) {
+    const actionLabels = {
+        created: "Created new branch",
+        switched: "Switched to existing branch",
+        rehydrated: "Rehydrated branch from remote",
+        already_on_branch: "Already on branch",
+    };
+    const label = actionLabels[result.action];
+    const guidance = "Using this dispatch-compatible branch preserves reviewer and fix-cycle continuity for manual work.";
+    if (isJsonMode()) {
+        output({
+            branch: result.branch,
+            action: result.action,
+            task_ref: result.taskRef,
+            source: result.source ?? null,
+            guidance,
+        });
+    }
+    else {
+        success(`${label}: ${result.branch}`);
+        info(`Task: ${result.taskRef}`);
+        if (result.source) {
+            info(`Source: ${result.source}`);
+        }
+        info(guidance);
+    }
+}
 /**
  * Helper function to update task fields.
  * Used by both single-ref and batch modes of task set.
@@ -281,78 +397,101 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
         updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
             const nextTask = { ...latestTask };
             const mutationChanges = [];
-            if (options.title) {
+            if (options.title && options.title !== latestTask.title) {
                 nextTask.title = options.title;
-                mutationChanges.push("title");
+                mutationChanges.push({ field: "title", before: latestTask.title, after: options.title });
             }
             if (options.description !== undefined) {
                 if (options.description === "null" || options.description.trim() === "") {
-                    delete nextTask.description;
-                    mutationChanges.push("description: cleared");
+                    if (latestTask.description !== undefined) {
+                        const before = latestTask.description;
+                        delete nextTask.description;
+                        mutationChanges.push({ field: "description", before, after: null });
+                    }
                 }
-                else {
+                else if (options.description !== latestTask.description) {
+                    mutationChanges.push({ field: "description", before: latestTask.description, after: options.description });
                     nextTask.description = options.description;
-                    mutationChanges.push("description");
                 }
             }
             if (options.specRef !== undefined) {
                 if (options.specRef === "null") {
-                    nextTask.spec_ref = null;
-                    mutationChanges.push("spec_ref: cleared");
+                    if (latestTask.spec_ref != null) {
+                        mutationChanges.push({ field: "spec_ref", before: latestTask.spec_ref, after: null });
+                        nextTask.spec_ref = null;
+                    }
                 }
                 else {
-                    nextTask.spec_ref = normalizeRefInput(options.specRef);
-                    mutationChanges.push("spec_ref");
+                    const newVal = normalizeRefInput(options.specRef);
+                    if (newVal !== latestTask.spec_ref) {
+                        mutationChanges.push({ field: "spec_ref", before: latestTask.spec_ref, after: newVal });
+                        nextTask.spec_ref = newVal;
+                    }
                 }
             }
             if (options.metaRef !== undefined) {
                 if (options.metaRef === "null") {
-                    nextTask.meta_ref = null;
-                    mutationChanges.push("meta_ref: cleared");
+                    if (latestTask.meta_ref != null) {
+                        mutationChanges.push({ field: "meta_ref", before: latestTask.meta_ref, after: null });
+                        nextTask.meta_ref = null;
+                    }
                 }
                 else {
-                    nextTask.meta_ref = normalizeRefInput(options.metaRef);
-                    mutationChanges.push("meta_ref");
+                    const newVal = normalizeRefInput(options.metaRef);
+                    if (newVal !== latestTask.meta_ref) {
+                        mutationChanges.push({ field: "meta_ref", before: latestTask.meta_ref, after: newVal });
+                        nextTask.meta_ref = newVal;
+                    }
                 }
             }
             if (options.planRef !== undefined) {
                 if (options.planRef === "null") {
-                    nextTask.plan_ref = null;
-                    mutationChanges.push("plan_ref: cleared");
+                    if (latestTask.plan_ref != null) {
+                        mutationChanges.push({ field: "plan_ref", before: latestTask.plan_ref, after: null });
+                        nextTask.plan_ref = null;
+                    }
                 }
                 else {
-                    nextTask.plan_ref = normalizeRefInput(options.planRef);
-                    mutationChanges.push("plan_ref");
+                    const newVal = normalizeRefInput(options.planRef);
+                    if (newVal !== latestTask.plan_ref) {
+                        mutationChanges.push({ field: "plan_ref", before: latestTask.plan_ref, after: newVal });
+                        nextTask.plan_ref = newVal;
+                    }
                 }
             }
             if (options.reviewUrl !== undefined) {
                 if (options.reviewUrl === "null") {
-                    delete nextTask.review_url;
-                    mutationChanges.push("review_url: cleared");
+                    if (latestTask.review_url != null) {
+                        mutationChanges.push({ field: "review_url", before: latestTask.review_url, after: null });
+                        delete nextTask.review_url;
+                    }
                 }
-                else {
+                else if (options.reviewUrl !== latestTask.review_url) {
+                    mutationChanges.push({ field: "review_url", before: latestTask.review_url, after: options.reviewUrl });
                     nextTask.review_url = options.reviewUrl;
-                    mutationChanges.push("review_url");
                 }
             }
-            if (parsedPriority !== undefined) {
+            if (parsedPriority !== undefined && parsedPriority !== latestTask.priority) {
+                mutationChanges.push({ field: "priority", before: latestTask.priority, after: parsedPriority });
                 nextTask.priority = parsedPriority;
-                mutationChanges.push("priority");
             }
             if (options.slug && !nextTask.slugs.includes(options.slug)) {
+                const before = [...latestTask.slugs];
                 nextTask.slugs = [...nextTask.slugs, options.slug];
-                mutationChanges.push("slug");
+                mutationChanges.push({ field: "slugs", before, after: nextTask.slugs });
             }
             if (parsedTags.length > 0) {
                 const newTags = parsedTags.filter((tag) => !nextTask.tags.includes(tag));
                 if (newTags.length > 0) {
+                    const before = [...latestTask.tags];
                     nextTask.tags = [...nextTask.tags, ...newTags];
-                    mutationChanges.push("tags");
+                    mutationChanges.push({ field: "tags", before, after: nextTask.tags });
                 }
             }
             if (options.dependsOn) {
+                const before = [...latestTask.depends_on];
                 nextTask.depends_on = options.dependsOn.map(normalizeRefInput);
-                mutationChanges.push("depends_on");
+                mutationChanges.push({ field: "depends_on", before, after: nextTask.depends_on });
             }
             if (options.clearDeps) {
                 if (latestTask.depends_on.length === 0) {
@@ -360,23 +499,41 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                     noChangesMessage = "No changes: task has no dependencies to clear";
                     return latestTask;
                 }
+                const before = [...latestTask.depends_on];
                 nextTask.depends_on = [];
-                mutationChanges.push("depends_on");
+                mutationChanges.push({ field: "depends_on", before, after: [] });
                 // 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");
+                if (latestTask.automation != null) {
+                    mutationChanges.push({ field: "automation", before: latestTask.automation, after: null });
+                    delete nextTask.automation;
+                }
             }
-            else if (validatedAutomation) {
+            else if (validatedAutomation && validatedAutomation !== latestTask.automation) {
+                mutationChanges.push({ field: "automation", before: latestTask.automation, after: 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");
+                }
+            }
+            // AC: @portable-task-submission-linkage ac-4 — repair/backfill or clear submission linkage
+            if (options.clearSubmissionLinkage) {
+                if (latestTask.submission_linkage != null) {
+                    mutationChanges.push({ field: "submission_linkage", before: latestTask.submission_linkage, after: null });
+                    nextTask.submission_linkage = null;
+                }
+            }
+            else if (options.submissionLinkage) {
+                const linkage = isGitRepo(ctx.projectRoot)
+                    ? captureSubmissionLinkage(ctx.projectRoot, latestTask.review_url, ctx.config?.dispatch?.base_branch)
+                    : null;
+                if (linkage) {
+                    mutationChanges.push({ field: "submission_linkage", before: latestTask.submission_linkage, after: linkage });
+                    nextTask.submission_linkage = linkage;
                 }
             }
             changes.splice(0, changes.length, ...mutationChanges);
@@ -397,11 +554,12 @@ async function setTaskFields(foundTask, ctx, tasks, items, _allMetaItems, index,
                 data: { task: updatedTask },
             };
         }
-        await commitIfShadow(ctx.shadow, "task-set", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changes.join(", "));
+        const changedFields = changes.map((c) => c.field).join(", ");
+        await commitIfShadow(ctx.shadow, "task-set", foundTask.slugs[0] || index.shortUlid(foundTask._ulid), changedFields);
         return {
             success: true,
-            message: `Updated task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(", ")})`,
-            data: { task: updatedTask },
+            message: `Updated task: ${index.shortUlid(updatedTask._ulid)} (${changedFields})`,
+            data: { task: updatedTask, changes },
         };
     }
     catch (err) {
@@ -470,6 +628,7 @@ export function registerTaskCommands(program) {
         .command("get <ref>")
         .description("Get task details")
         .option("--all", "Show all notes including superseded ones")
+        .option("--activity", "Show full activity timeline")
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -499,11 +658,66 @@ export function registerTaskCommands(program) {
                     inheritedTraits = Array.from(traitsByTrait.values());
                 }
             }
+            // Load review records once — used for both active review display and activity timeline
+            const allReviews = await loadReviewRecords(ctx);
+            // AC: @review-cli-task-linkage ac-1 — resolve active review for task
+            let activeReview = null;
+            if (foundTask.review_ref) {
+                const { computeDisposition } = await import("../../parser/index.js");
+                const found = findReviewByRef(allReviews, foundTask.review_ref);
+                if (found) {
+                    activeReview = {
+                        ref: `@${found.slugs[0] || found._ulid}`,
+                        title: found.title,
+                        lifecycle_state: found.lifecycle_state,
+                        disposition: computeDisposition(found),
+                    };
+                }
+            }
+            // AC: @task-activity-timeline ac-1, ac-2, ac-3 — load activity timeline
+            let activity = [];
+            try {
+                const { getRawTaskCommits, normalizeTaskActivity } = await import("../../utils/activity.js");
+                const rawCommits = getRawTaskCommits(ctx.specDir, foundTask._ulid);
+                activity = normalizeTaskActivity(rawCommits);
+                // AC: @task-activity-timeline ac-3 — merge review events into timeline
+                const taskRef = `@${foundTask.slugs[0] || foundTask._ulid}`;
+                const linkedReviews = allReviews.filter((r) => r.related_refs.includes(taskRef) ||
+                    (r.subject.type === "task" && r.subject.ref === taskRef) ||
+                    r._ulid === (foundTask.review_ref?.startsWith("@")
+                        ? foundTask.review_ref.slice(1)
+                        : foundTask.review_ref));
+                for (const review of linkedReviews) {
+                    const reviewRef = `@${review.slugs[0] || review._ulid}`;
+                    for (const event of review.events) {
+                        activity.push({
+                            type: event.event_type === "verdict_submitted"
+                                ? "submitted"
+                                : event.event_type === "lifecycle_change"
+                                    ? "state_change"
+                                    : "review_linked",
+                            timestamp: event.timestamp,
+                            author: event.actor,
+                            summary: `Review ${reviewRef}: ${event.event_type.replace(/_/g, " ")}`,
+                            commitHash: "",
+                        });
+                    }
+                }
+                // Re-sort chronologically (oldest first) after merging
+                activity.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+            }
+            catch {
+                // Activity is best-effort — don't fail task get if git query fails
+            }
             // Build JSON output with inherited traits (AC: @trait-display ac-2)
             // Always include all notes in JSON output with superseded computed field
+            // AC: @review-cli-task-linkage ac-1 — include resolved review summary in JSON
+            // AC: @task-activity-timeline ac-4 — include activity in JSON output
             const jsonOutput = {
                 ...foundTask,
                 notes: annotateNotesWithSuperseded(foundTask.notes),
+                ...(activeReview && { active_review: activeReview }),
+                ...(activity.length > 0 && { activity }),
                 ...(inheritedTraits.length > 0 && {
                     inherited_traits: inheritedTraits.map(({ trait, acs }) => ({
                         ref: `@${trait.slug}`,
@@ -513,7 +727,12 @@ export function registerTaskCommands(program) {
                 }),
             };
             output(jsonOutput, () => {
-                formatTaskDetails(foundTask, index, { showAllNotes: options.all });
+                formatTaskDetails(foundTask, index, {
+                    showAllNotes: options.all,
+                    activeReview,
+                    activity,
+                    showFullActivity: options.activity,
+                });
                 // 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) {
@@ -613,7 +832,7 @@ Examples:
                 }
                 automationValue = automationResult.value;
             }
-            // Validate plan_ref if provided (AC: @plan-derive ac-5, ac-6)
+            // Validate plan_ref if provided (AC: @plan-derive-enhanced ac-task-refs, ac-bidirectional-links)
             if (options.planRef) {
                 // First check if it's a task or spec item (wrong type)
                 const cleanRef = options.planRef.startsWith("@")
@@ -709,12 +928,15 @@ Examples:
         .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")
+        .option("--submission-linkage", "Repair/backfill submission linkage from current git context (AC: @portable-task-submission-linkage ac-4)")
+        .option("--clear-submission-linkage", "Clear submission linkage (AC: @portable-task-submission-linkage ac-4)")
         .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 @task-slug --submission-linkage  # capture current git context
   $ kspec task set --refs @task1 @task2 --priority 3`)
         .action(async (ref, options) => {
         try {
@@ -789,6 +1011,11 @@ Examples:
                     }
                     else {
                         success(result.message, result.data);
+                        // Show before→after diff in text mode
+                        const data = result.data;
+                        if (data?.changes) {
+                            showChangeDiff(data.changes);
+                        }
                     }
                 }
             }
@@ -930,7 +1157,7 @@ Examples:
             }
             // AC: @session-end-loop-signal ac-block-task - Block if end-loop requested
             if (sessionId) {
-                const endLoopState = await isEndLoopRequested(ctx.specDir, sessionId);
+                const endLoopState = await isEndLoopRequested(ctx.sessionsDir, sessionId);
                 if (endLoopState?.requested) {
                     error(`Cannot start task: loop is ending for session ${sessionId.slice(0, 8)}...` +
                         (endLoopState.reason ? ` Reason: ${endLoopState.reason}` : ""));
@@ -944,7 +1171,7 @@ Examples:
             // 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);
+                const budgetCheck = await checkBudget(ctx.sessionsDir, sessionId || undefined);
                 if (!budgetCheck.allowed) {
                     error(budgetCheck.reason);
                     process.exit(EXIT_CODES.VALIDATION_FAILED);
@@ -969,7 +1196,7 @@ Examples:
             // 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);
+                await incrementBudget(ctx.sessionsDir, sessionId);
             }
             // AC: @daemon-agent-dispatch ac-2, ac-7 - Notify daemon of state change (fire-and-forget)
             postDispatchEvent({
@@ -977,7 +1204,7 @@ Examples:
                 taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                 fromStatus: transitionFromStatus,
                 toStatus: updatedTask.status,
-                projectPath: ctx.rootDir,
+                projectPath: ctx.projectRoot,
             });
             success(`Started task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
@@ -1139,7 +1366,7 @@ Examples:
                             taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                             fromStatus: transitionFromStatus,
                             toStatus: updatedTask.status,
-                            projectPath: ctx.rootDir,
+                            projectPath: ctx.projectRoot,
                         });
                         // Sync spec implementation status (unless --no-sync)
                         if (options.sync !== false && foundTask.spec_ref) {
@@ -1228,6 +1455,10 @@ Examples:
             const items = await loadAllItems(ctx);
             const index = new ReferenceIndex(tasks, items);
             const foundTask = resolveTaskRef(ref, tasks, index);
+            // AC: @portable-task-submission-linkage ac-1, ac-3, ac-5 — capture git context
+            const linkage = isGitRepo(ctx.projectRoot)
+                ? captureSubmissionLinkage(ctx.projectRoot, options.reviewUrl, ctx.config?.dispatch?.base_branch)
+                : null;
             let transitionFromStatus = foundTask.status;
             const updatedTask = await mutateTaskAtomically(ctx, foundTask, (latestTask) => {
                 transitionFromStatus = latestTask.status;
@@ -1240,6 +1471,8 @@ Examples:
                     submitted_at: new Date().toISOString(),
                     // AC: @task-submit ac-submit-2
                     ...(options.reviewUrl !== undefined && { review_url: options.reviewUrl }),
+                    // AC: @portable-task-submission-linkage ac-1
+                    ...(linkage && { submission_linkage: linkage }),
                 };
             });
             if (transitionFromStatus !== "in_progress") {
@@ -1253,9 +1486,15 @@ Examples:
                 taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                 fromStatus: transitionFromStatus,
                 toStatus: updatedTask.status,
-                projectPath: ctx.rootDir,
+                projectPath: ctx.projectRoot,
             });
             success(`Submitted task for review: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
+            // AC: @portable-task-submission-linkage ac-3 — warn on detached HEAD
+            if (linkage && !linkage.branch) {
+                warn("Submitted from detached HEAD — submission linkage has no branch name. " +
+                    "Dispatch review continuity may require an explicit branch. " +
+                    "Use `kspec task set @ref --submission-linkage` to repair.");
+            }
         }
         catch (err) {
             error(errors.failures.updateTask, err);
@@ -1304,7 +1543,7 @@ Examples:
                 taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                 fromStatus: transitionFromStatus,
                 toStatus: updatedTask.status,
-                projectPath: ctx.rootDir,
+                projectPath: ctx.projectRoot,
             });
             success(`Kicked back task: ${index.shortUlid(updatedTask._ulid)} (fix cycle ${cycleNumber})`, { task: updatedTask });
         }
@@ -1349,7 +1588,7 @@ Examples:
                 taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                 fromStatus: transitionFromStatus,
                 toStatus: updatedTask.status,
-                projectPath: ctx.rootDir,
+                projectPath: ctx.projectRoot,
             });
             success(`Blocked task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
@@ -1395,7 +1634,7 @@ Examples:
                 taskRef: `@${updatedTask.slugs[0] || updatedTask._ulid}`,
                 fromStatus: transitionFromStatus,
                 toStatus: updatedTask.status,
-                projectPath: ctx.rootDir,
+                projectPath: ctx.projectRoot,
             });
             success(`Unblocked task: ${index.shortUlid(updatedTask._ulid)}`, {
                 task: updatedTask,
@@ -2035,5 +2274,76 @@ Examples:
             process.exit(EXIT_CODES.ERROR);
         }
     });
+    // kspec task branch <ref>
+    // AC: @deterministic-task-branch-helper ac-1, ac-2, ac-3
+    task
+        .command("branch <ref>")
+        .description("Create or resume the deterministic dispatch-compatible branch for a task")
+        .action(async (ref) => {
+        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);
+            // AC: @trait-error-guidance ac-1, ac-2
+            if (!isGitRepo()) {
+                error("Not a git repository. Run this command from inside a git repo.");
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            // AC: @deterministic-task-branch-helper ac-1
+            // Compute the deterministic branch name using the dispatch naming contract
+            const branchName = computeDispatchBranchName(foundTask._ulid, foundTask);
+            // AC: @deterministic-task-branch-helper ac-2
+            // Check if the branch already exists locally
+            const localExists = gitRefExists(`refs/heads/${branchName}`);
+            if (localExists) {
+                // Branch exists locally — switch to it
+                const currentBranch = getCurrentBranch();
+                if (currentBranch === branchName) {
+                    // Already on the branch
+                    reportBranchResult({
+                        branch: branchName,
+                        action: "already_on_branch",
+                        taskRef: `@${foundTask.slugs[0] || foundTask._ulid}`,
+                    });
+                }
+                else {
+                    gitCheckout(branchName);
+                    reportBranchResult({
+                        branch: branchName,
+                        action: "switched",
+                        taskRef: `@${foundTask.slugs[0] || foundTask._ulid}`,
+                    });
+                }
+                return;
+            }
+            // AC: @deterministic-task-branch-helper ac-2
+            // Check remotes for the branch and rehydrate if found
+            const remoteSource = findBranchOnRemote(branchName);
+            if (remoteSource) {
+                gitCreateBranchFrom(branchName, remoteSource);
+                gitCheckout(branchName);
+                reportBranchResult({
+                    branch: branchName,
+                    action: "rehydrated",
+                    source: remoteSource,
+                    taskRef: `@${foundTask.slugs[0] || foundTask._ulid}`,
+                });
+                return;
+            }
+            // Branch does not exist anywhere — create it
+            gitCheckoutNew(branchName);
+            reportBranchResult({
+                branch: branchName,
+                action: "created",
+                taskRef: `@${foundTask.slugs[0] || foundTask._ulid}`,
+            });
+        }
+        catch (err) {
+            error(errors.failures.taskBranch, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
 }
 //# sourceMappingURL=task.js.map