@kynetic-ai/spec 0.1.0

package/dist/cli/commands/task.js

@@ -0,0 +1,1514 @@
+import chalk from 'chalk';
+import * as path from 'node:path';
+import { initContext, loadAllTasks, loadAllItems, saveTask, deleteTask, createTask, createNote, createTodo, syncSpecImplementationStatus, ReferenceIndex, checkSlugUniqueness, } 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';
+/**
+ * Find a task by reference with detailed error reporting.
+ * Returns the task or exits with appropriate error.
+ */
+function resolveTaskRef(ref, tasks, index) {
+    const result = index.resolve(ref);
+    if (!result.ok) {
+        switch (result.error) {
+            case 'not_found':
+                error(errors.reference.taskNotFound(ref));
+                break;
+            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})` : ''}`);
+                }
+                break;
+            case 'duplicate_slug':
+                error(errors.reference.slugMapsToMultiple(ref));
+                for (const candidate of result.candidates) {
+                    console.error(`  - ${index.shortUlid(candidate)}`);
+                }
+                break;
+        }
+        // AC: @cli-exit-codes consistent-usage - NOT_FOUND for missing resources
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Check if it's actually a task
+    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
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    return task;
+}
+/**
+ * Batch-compatible resolver that returns null instead of calling process.exit().
+ * Used by executeBatchOperation to handle errors without terminating the process.
+ * AC: @multi-ref-batch ac-4, ac-8 - Partial failure handling and ref resolution
+ */
+function resolveTaskRefForBatch(ref, tasks, index) {
+    const result = index.resolve(ref);
+    if (!result.ok) {
+        let errorMsg;
+        switch (result.error) {
+            case 'not_found':
+                errorMsg = `Reference "${ref}" not found`;
+                break;
+            case 'ambiguous':
+                errorMsg = `Reference "${ref}" is ambiguous (matches ${result.candidates.length} items)`;
+                break;
+            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);
+    if (!task) {
+        return { task: null, error: `Reference "${ref}" is not a task` };
+    }
+    return { task };
+}
+/**
+ * Helper function to update task fields.
+ * 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) {
+    try {
+        // Check slug uniqueness if adding a new slug
+        if (options.slug) {
+            const slugCheck = checkSlugUniqueness(index, [options.slug], foundTask._ulid);
+            if (!slugCheck.ok) {
+                return {
+                    success: false,
+                    error: `Slug "${slugCheck.slug}" already exists on ${slugCheck.existingUlid}`,
+                };
+            }
+        }
+        // Build updated task with only provided options
+        const updatedTask = { ...foundTask };
+        const changes = [];
+        if (options.title) {
+            updatedTask.title = options.title;
+            changes.push('title');
+        }
+        if (options.specRef) {
+            // Validate the spec ref exists and is a spec item
+            const specResult = index.resolve(options.specRef);
+            if (!specResult.ok) {
+                return {
+                    success: false,
+                    error: errors.reference.specRefNotFound(options.specRef),
+                };
+            }
+            // Check it's not a task
+            const isTask = tasks.some(t => t._ulid === specResult.ulid);
+            if (isTask) {
+                return {
+                    success: false,
+                    error: errors.reference.specRefIsTask(options.specRef),
+                };
+            }
+            updatedTask.spec_ref = options.specRef;
+            changes.push('spec_ref');
+        }
+        if (options.metaRef) {
+            // Validate the meta ref exists and is a meta item
+            const metaRefResult = index.resolve(options.metaRef);
+            if (!metaRefResult.ok) {
+                return {
+                    success: false,
+                    error: errors.reference.metaRefNotFound(options.metaRef),
+                };
+            }
+            // 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);
+            if (isTask || isSpecItem) {
+                return {
+                    success: false,
+                    error: errors.reference.metaRefPointsToSpec(options.metaRef),
+                };
+            }
+            updatedTask.meta_ref = options.metaRef;
+            changes.push('meta_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',
+                };
+            }
+            updatedTask.priority = priority;
+            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 newTags = options.tag.filter((t) => !updatedTask.tags.includes(t));
+            if (newTags.length > 0) {
+                updatedTask.tags = [...updatedTask.tags, ...newTags];
+                changes.push('tags');
+            }
+        }
+        if (options.dependsOn) {
+            // Validate all dependency refs
+            for (const depRef of options.dependsOn) {
+                const depResult = index.resolve(depRef);
+                if (!depResult.ok) {
+                    return {
+                        success: false,
+                        error: errors.reference.depNotFound(depRef),
+                    };
+                }
+            }
+            updatedTask.depends_on = options.dependsOn;
+            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
+            const note = createNote(`Dependencies cleared (was: ${foundTask.depends_on.join(', ')})`, '@human');
+            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) {
+            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(', ')}`,
+                };
+            }
+            // AC: @task-automation-eligibility ac-18 - require reason for needs_review
+            if (options.automation === 'needs_review' && !options.reason) {
+                return {
+                    success: false,
+                    error: 'Setting automation to needs_review requires --reason flag explaining why',
+                };
+            }
+            updatedTask.automation = options.automation;
+            changes.push('automation');
+            // If reason provided, add a note documenting the change
+            if (options.reason) {
+                const note = createNote(`Automation status set to ${options.automation}: ${options.reason}`, '@human');
+                updatedTask.notes = [...updatedTask.notes, 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',
+                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,
+            message: `Updated task: ${index.shortUlid(updatedTask._ulid)} (${changes.join(', ')})`,
+            data: { task: updatedTask },
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Register the 'task' command group (singular - operations on individual tasks)
+ */
+export function registerTaskCommands(program) {
+    const task = program
+        .command('task')
+        .description('Operations on individual tasks');
+    // kspec task get <ref>
+    task
+        .command('get <ref>')
+        .description('Get task details')
+        .action(async (ref) => {
+        try {
+            const ctx = await initContext();
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            // Build all indexes including TraitIndex
+            const { refIndex: index, traitIndex } = await (async () => {
+                const { buildIndexes } = await import('../../parser/index.js');
+                return buildIndexes(ctx);
+            })();
+            const foundTask = resolveTaskRef(ref, tasks, index);
+            // AC: @trait-display ac-3 - task get shows inherited AC sections
+            // Get inherited traits if task has spec_ref
+            let inheritedTraits = [];
+            if (foundTask.spec_ref) {
+                const specResult = index.resolve(foundTask.spec_ref);
+                if (specResult.ok) {
+                    const specUlid = specResult.ulid;
+                    const inheritedAC = traitIndex.getInheritedAC(specUlid);
+                    const traitsByTrait = new Map();
+                    for (const { trait, ac } of inheritedAC) {
+                        if (!traitsByTrait.has(trait.ulid)) {
+                            traitsByTrait.set(trait.ulid, { trait, acs: [] });
+                        }
+                        traitsByTrait.get(trait.ulid).acs.push(ac);
+                    }
+                    inheritedTraits = Array.from(traitsByTrait.values());
+                }
+            }
+            // Build JSON output with inherited traits (AC: @trait-display ac-2)
+            const jsonOutput = {
+                ...foundTask,
+                ...(inheritedTraits.length > 0 && {
+                    inherited_traits: inheritedTraits.map(({ trait, acs }) => ({
+                        ref: `@${trait.slug}`,
+                        title: trait.title,
+                        acceptance_criteria: acs,
+                    })),
+                }),
+            };
+            output(jsonOutput, () => {
+                formatTaskDetails(foundTask, index);
+                // 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})`));
+                            if (ac.given)
+                                console.log(`    Given: ${ac.given}`);
+                            if (ac.when)
+                                console.log(`    When: ${ac.when}`);
+                            if (ac.then)
+                                console.log(`    Then: ${ac.then}`);
+                        }
+                    }
+                }
+            });
+        }
+        catch (err) {
+            error(errors.failures.getTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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)')
+        .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 metaContext = await loadMetaContext(ctx);
+            const allMetaItems = [
+                ...metaContext.agents,
+                ...metaContext.workflows,
+                ...metaContext.conventions,
+                ...metaContext.observations,
+            ];
+            // Build index for reference validation
+            const refIndex = new ReferenceIndex(tasks, items, allMetaItems);
+            // Check slug uniqueness if provided
+            if (options.slug) {
+                const slugCheck = checkSlugUniqueness(refIndex, [options.slug]);
+                if (!slugCheck.ok) {
+                    error(errors.slug.alreadyExists(slugCheck.slug, slugCheck.existingUlid));
+                    process.exit(EXIT_CODES.CONFLICT);
+                }
+            }
+            // Validate meta_ref if provided (AC-meta-ref-3, AC-meta-ref-4)
+            if (options.metaRef) {
+                const metaRefResult = refIndex.resolve(options.metaRef);
+                if (!metaRefResult.ok) {
+                    error(errors.reference.metaRefNotFound(options.metaRef));
+                    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);
+                if (isTask || isSpecItem) {
+                    error(errors.reference.metaRefPointsToSpec(options.metaRef));
+                    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(', ')}`);
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                automationValue = options.automation;
+            }
+            // AC: @spec-task-add-description ac-6 - Omit description if empty string
+            const descriptionValue = options.description && options.description.trim() !== ''
+                ? options.description
+                : undefined;
+            const input = {
+                title: options.title,
+                description: descriptionValue,
+                type: options.type,
+                spec_ref: options.specRef || null,
+                meta_ref: options.metaRef || null,
+                priority: parseInt(options.priority, 10),
+                slugs: options.slug ? [options.slug] : [],
+                tags: options.tag || [],
+                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);
+            // 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 });
+        }
+        catch (err) {
+            error(errors.failures.createTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .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');
+                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');
+                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 metaContext = await loadMetaContext(ctx);
+            const allMetaItems = [
+                ...metaContext.agents,
+                ...metaContext.workflows,
+                ...metaContext.conventions,
+                ...metaContext.observations,
+            ];
+            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;
+            // Batch mode or single mode?
+            if (refsFlag && refsFlag.length > 0) {
+                // Batch mode - AC: @spec-task-set-batch ac-1, ac-2, ac-5
+                const result = await executeBatchOperation({
+                    positionalRef: ref,
+                    refsFlag,
+                    context: { ctx, tasks, items, allMetaItems, index, options },
+                    items: tasks,
+                    index,
+                    resolveRef: (refStr, taskList, idx) => {
+                        const result = resolveTaskRefForBatch(refStr, taskList, idx);
+                        return { item: result.task, error: result.error };
+                    },
+                    executeOperation: async (task, context) => {
+                        return await setTaskFields(task, context.ctx, context.tasks, context.items, context.allMetaItems, context.index, context.options);
+                    },
+                    getUlid: (task) => task._ulid,
+                });
+                formatBatchOutput(result, 'Set');
+            }
+            else {
+                // Single mode - existing behavior
+                if (!ref) {
+                    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');
+                    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 (isJsonMode()) {
+                            output({ success: true, message: result.message });
+                        }
+                        else {
+                            warn(result.message);
+                        }
+                    }
+                    else {
+                        success(result.message, result.data);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            error(errors.failures.updateTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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)')
+        .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 metaContext = await loadMetaContext(ctx);
+            const allMetaItems = [
+                ...metaContext.agents,
+                ...metaContext.workflows,
+                ...metaContext.conventions,
+                ...metaContext.observations,
+            ];
+            const index = new ReferenceIndex(tasks, items, allMetaItems);
+            const foundTask = resolveTaskRef(ref, tasks, index);
+            // Get JSON data from --data flag or stdin
+            let jsonData;
+            if (options.data) {
+                jsonData = options.data;
+            }
+            else {
+                // Read from stdin
+                const chunks = [];
+                for await (const chunk of process.stdin) {
+                    chunks.push(chunk);
+                }
+                jsonData = Buffer.concat(chunks).toString('utf-8');
+            }
+            // Parse JSON
+            let patchData;
+            try {
+                patchData = JSON.parse(jsonData);
+            }
+            catch (parseErr) {
+                error(errors.validation.invalidJson, parseErr);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // Validate against TaskInputSchema (partial)
+            const { TaskInputSchema } = await import('../../schema/index.js');
+            // Create a partial schema for validation
+            const partialSchema = options.allowUnknown
+                ? TaskInputSchema.partial().passthrough()
+                : TaskInputSchema.partial().strict();
+            let validatedPatch;
+            try {
+                validatedPatch = partialSchema.parse(patchData);
+            }
+            catch (validationErr) {
+                error(errors.validation.invalidPatchData(String(validationErr)), validationErr);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // Check for unknown fields if strict mode
+            if (!options.allowUnknown) {
+                const knownFields = Object.keys(TaskInputSchema.shape);
+                const providedFields = Object.keys(patchData);
+                const unknownFields = providedFields.filter(f => !knownFields.includes(f));
+                if (unknownFields.length > 0) {
+                    error(errors.validation.unknownFields(unknownFields));
+                    process.exit(EXIT_CODES.ERROR);
+                }
+            }
+            // Build updated task
+            const updatedTask = { ...foundTask, ...validatedPatch };
+            // 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(', ')}`);
+                output({ changes, updated: updatedTask }, () => {
+                    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 });
+        }
+        catch (err) {
+            error(errors.failures.patchTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .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 === 'in_progress') {
+                warn('Task is already in progress');
+                output(foundTask, () => formatTaskDetails(foundTask));
+                return;
+            }
+            if (foundTask.status !== 'pending') {
+                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',
+                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 });
+            // 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);
+                    if (specItem) {
+                        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) {
+                            console.log(`\nAcceptance Criteria (${specItem.acceptance_criteria.length}):`);
+                            for (const ac of specItem.acceptance_criteria) {
+                                console.log(`  [${ac.id}]`);
+                                console.log(`    Given: ${ac.given}`);
+                                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('');
+                    }
+                }
+            }
+            // 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 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}`);
+                }
+            }
+        }
+        catch (err) {
+            error(errors.failures.startTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .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);
+            // AC: @spec-completion-enforcement ac-8
+            if (options.skipReview && !options.reason) {
+                error(errors.status.skipReviewRequiresReason);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // AC: @multi-ref-batch ac-1, ac-2, ac-3, ac-4
+            const result = await executeBatchOperation({
+                positionalRef: ref,
+                refsFlag: options.refs,
+                context: { ctx, tasks, items, index, options },
+                items: tasks,
+                index,
+                resolveRef: (refStr, taskList, idx) => {
+                    const resolved = resolveTaskRefForBatch(refStr, taskList, idx);
+                    return { item: resolved.task, error: resolved.error };
+                },
+                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: @spec-completion-enforcement ac-7 - Allow skip-review bypass
+                        if (!options.skipReview) {
+                            // 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
+                        let taskNotes = foundTask.notes;
+                        if (options.skipReview && options.reason) {
+                            const skipNote = createNote(`Completed with --skip-review: ${options.reason}`, '@human');
+                            taskNotes = [...taskNotes, skipNote];
+                        }
+                        // 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);
+                        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 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}`);
+                            }
+                        }
+                        // 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 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`);
+                                }
+                            }
+                        }
+                        return {
+                            success: true,
+                            message: `Completed task: ${index.shortUlid(updatedTask._ulid)}`,
+                            data: updatedTask,
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                },
+                getUlid: (task) => task._ulid,
+            });
+            // AC: @multi-ref-batch ac-5, ac-6
+            formatBatchOutput(result, 'Complete');
+            // Show commit guidance for single-ref mode only
+            if (!options.refs && result.success && result.results.length === 1 && !isJsonMode()) {
+                const taskData = result.results[0].data;
+                if (taskData) {
+                    const guidance = formatCommitGuidance(taskData);
+                    printCommitGuidance(guidance);
+                }
+            }
+        }
+        catch (err) {
+            error(errors.failures.completeTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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)')
+        .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);
+            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',
+            };
+            await saveTask(ctx, updatedTask);
+            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) {
+            error(errors.failures.updateTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task block <ref>
+    task
+        .command('block <ref>')
+        .description('Block a task')
+        .requiredOption('--reason <reason>', 'Reason for blocking')
+        .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 === 'completed' || foundTask.status === 'cancelled') {
+                error(errors.status.cannotBlock(foundTask.status));
+                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));
+            success(`Blocked task: ${index.shortUlid(updatedTask._ulid)}`, { task: updatedTask });
+        }
+        catch (err) {
+            error(errors.failures.blockTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task unblock <ref>
+    task
+        .command('unblock <ref>')
+        .description('Unblock 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);
+            if (foundTask.status !== 'blocked') {
+                warn('Task is not blocked');
+                return;
+            }
+            const updatedTask = {
+                ...foundTask,
+                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 });
+        }
+        catch (err) {
+            error(errors.failures.unblockTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .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 result = await executeBatchOperation({
+                positionalRef: ref,
+                refsFlag: options.refs,
+                context: { ctx, tasks, items, index, options },
+                items: tasks,
+                index,
+                resolveRef: (refStr, taskList, idx) => {
+                    const resolved = resolveTaskRefForBatch(refStr, taskList, idx);
+                    return { item: resolved.task, error: resolved.error };
+                },
+                executeOperation: async (foundTask, { ctx, index, options }) => {
+                    try {
+                        if (foundTask.status === 'completed' || foundTask.status === 'cancelled') {
+                            return {
+                                success: false,
+                                error: `Task is already ${foundTask.status}`,
+                            };
+                        }
+                        const updatedTask = {
+                            ...foundTask,
+                            status: 'cancelled',
+                            closed_reason: options.reason || null,
+                        };
+                        await saveTask(ctx, updatedTask);
+                        await commitIfShadow(ctx.shadow, 'task-cancel', foundTask.slugs[0] || index.shortUlid(foundTask._ulid));
+                        return {
+                            success: true,
+                            message: `Cancelled task: ${index.shortUlid(updatedTask._ulid)}`,
+                            data: updatedTask,
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                },
+                getUlid: (task) => task._ulid,
+            });
+            formatBatchOutput(result, 'Cancel');
+        }
+        catch (err) {
+            error(errors.failures.cancelTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .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: @spec-task-reset ac-2 - Error if 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})` : '';
+            // 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: @spec-task-reset ac-4 - Add note documenting the reset
+            const noteContent = `Reset from ${previousStatus} to pending${cancelReasonText}`;
+            const note = createNote(noteContent, '@human');
+            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
+            const jsonOutput = {
+                task: updatedTask,
+                previous_status: previousStatus,
+                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(', ')}`);
+                }
+            });
+        }
+        catch (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')
+        .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);
+            // For batch mode (--refs), require --force
+            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({
+                positionalRef: ref,
+                refsFlag: options.refs,
+                context: { ctx, tasks, items, index, options },
+                items: tasks,
+                index,
+                resolveRef: (refStr, taskList, idx) => {
+                    const resolved = resolveTaskRefForBatch(refStr, taskList, idx);
+                    return { item: resolved.task, error: resolved.error };
+                },
+                executeOperation: async (foundTask, { ctx, index, options }) => {
+                    try {
+                        const taskDisplay = `${foundTask.title} (${index.shortUlid(foundTask._ulid)})`;
+                        if (options.dryRun) {
+                            return {
+                                success: true,
+                                message: `Would delete: ${taskDisplay}`,
+                            };
+                        }
+                        // For single-ref mode (not --refs), prompt for confirmation unless --force
+                        if (!options.refs && !options.force) {
+                            const readline = await import('readline');
+                            const rl = readline.createInterface({
+                                input: process.stdin,
+                                output: process.stdout,
+                            });
+                            const answer = await new Promise((resolve) => {
+                                rl.question(`Delete task "${taskDisplay}"? [y/N] `, resolve);
+                            });
+                            rl.close();
+                            if (answer.toLowerCase() !== 'y') {
+                                return {
+                                    success: false,
+                                    error: 'Deletion cancelled by user',
+                                };
+                            }
+                        }
+                        await deleteTask(ctx, foundTask);
+                        await commitIfShadow(ctx.shadow, 'task-delete', foundTask.slugs[0] || index.shortUlid(foundTask._ulid), foundTask.title);
+                        return {
+                            success: true,
+                            message: `Deleted task: ${taskDisplay}`,
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                },
+                getUlid: (task) => task._ulid,
+            });
+            formatBatchOutput(result, 'Delete');
+        }
+        catch (err) {
+            error(errors.failures.deleteTask, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // 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')
+        .action(async (ref, message, 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);
+            const note = createNote(message, options.author, options.supersedes);
+            const updatedTask = {
+                ...foundTask,
+                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 });
+            // Proactive alignment guidance for tasks with spec_ref
+            if (foundTask.spec_ref) {
+                console.log('');
+                console.log(alignmentCheck.header);
+                console.log(alignmentCheck.beyondSpec);
+                console.log(alignmentCheck.updateSpec(foundTask.spec_ref));
+                console.log(alignmentCheck.addAC);
+                // Check if linked spec has acceptance criteria and remind about test coverage
+                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('');
+                        console.log(alignmentCheck.testCoverage(specItem.acceptance_criteria.length));
+                    }
+                }
+            }
+        }
+        catch (err) {
+            error(errors.failures.addNote, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task notes <ref>
+    task
+        .command('notes <ref>')
+        .description('Show notes 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);
+            output(foundTask.notes, () => {
+                if (foundTask.notes.length === 0) {
+                    console.log('No notes');
+                }
+                else {
+                    for (const note of foundTask.notes) {
+                        const author = note.author || 'unknown';
+                        console.log(`[${note.created_at}] ${author}:`);
+                        console.log(note.content);
+                        console.log('');
+                    }
+                }
+            });
+        }
+        catch (err) {
+            error(errors.failures.getNotes, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task review <ref>
+    task
+        .command('review <ref>')
+        .description('Get task context for review (task details, spec, ACs, git diff)')
+        .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);
+            // 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;
+            };
+            // Gather review context
+            const reviewContext = {
+                task: foundTask,
+                spec: null,
+                diff: null,
+                started_at: foundTask.started_at || null,
+            };
+            // Get spec item if task has spec_ref
+            if (foundTask.spec_ref) {
+                const specResult = index.resolve(foundTask.spec_ref);
+                if (specResult.ok) {
+                    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) {
+                        const coveredACs = await scanTestCoverage(ctx.rootDir);
+                        const covered = [];
+                        const uncovered = [];
+                        for (const ac of specItem.acceptance_criteria) {
+                            // Build possible references
+                            const possibleRefs = [];
+                            if (specItem.slugs && specItem.slugs.length > 0) {
+                                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)}`);
+                            const isCovered = possibleRefs.some(ref => coveredACs.has(ref));
+                            if (isCovered) {
+                                covered.push(ac.id);
+                            }
+                            else {
+                                uncovered.push(ac.id);
+                            }
+                        }
+                        reviewContext.testCoverage = { covered, uncovered };
+                    }
+                }
+            }
+            // Get git diff since task started
+            if (foundTask.started_at) {
+                const startedDate = new Date(foundTask.started_at);
+                reviewContext.diff = getDiffSince(startedDate, ctx.rootDir);
+            }
+            output(reviewContext, () => {
+                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(formatTaskDetails(foundTask, index));
+                console.log();
+                // Spec details
+                if (reviewContext.spec) {
+                    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) {
+                        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('○');
+                            console.log(`  ${coverageMarker} [${ac.id}]`);
+                            console.log(`    Given: ${ac.given}`);
+                            console.log(`    When: ${ac.when}`);
+                            console.log(`    Then: ${ac.then}`);
+                        }
+                        // Test coverage summary
+                        if (reviewContext.testCoverage) {
+                            const { covered, uncovered } = reviewContext.testCoverage;
+                            console.log();
+                            if (uncovered.length === 0) {
+                                console.log(chalk.green(`  ✓ All ${covered.length} AC(s) have test coverage`));
+                            }
+                            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();
+                }
+                // Git diff
+                if (reviewContext.diff) {
+                    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(`Started at: ${foundTask.started_at}`);
+                    console.log('No changes detected');
+                    console.log();
+                }
+                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 there any gaps or issues?');
+                console.log('='.repeat(60));
+            });
+        }
+        catch (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')
+        .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);
+            output(foundTask.todos, () => {
+                if (foundTask.todos.length === 0) {
+                    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})` : '';
+                        console.log(`${status} ${todo.id}. ${todo.text}${doneInfo}`);
+                    }
+                }
+            });
+        }
+        catch (err) {
+            error(errors.failures.getTodos, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // Create subcommand group for todo operations
+    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')
+        .action(async (ref, text, 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);
+            // 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);
+            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) {
+            error(errors.failures.addTodo, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task todo done <ref> <id>
+    todoCmd
+        .command('done <ref> <id>')
+        .description('Mark a todo as done')
+        .action(async (ref, idStr) => {
+        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);
+            const id = parseInt(idStr, 10);
+            if (isNaN(id)) {
+                error(errors.todo.invalidId(idStr));
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            const todoIndex = foundTask.todos.findIndex(t => t.id === id);
+            if (todoIndex === -1) {
+                error(errors.todo.notFound(id));
+                process.exit(EXIT_CODES.NOT_FOUND);
+            }
+            if (foundTask.todos[todoIndex].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] });
+        }
+        catch (err) {
+            error(errors.failures.markTodoDone, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+    // kspec task todo undone <ref> <id>
+    todoCmd
+        .command('undone <ref> <id>')
+        .description('Mark a todo as not done')
+        .action(async (ref, idStr) => {
+        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);
+            const id = parseInt(idStr, 10);
+            if (isNaN(id)) {
+                error(errors.todo.invalidId(idStr));
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            const todoIndex = foundTask.todos.findIndex(t => t.id === id);
+            if (todoIndex === -1) {
+                error(errors.todo.notFound(id));
+                process.exit(EXIT_CODES.NOT_FOUND);
+            }
+            if (!foundTask.todos[todoIndex].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] });
+        }
+        catch (err) {
+            error(errors.failures.markTodoNotDone, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+//# sourceMappingURL=task.js.map