@kynetic-ai/spec 0.1.0

package/dist/parser/alignment.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Alignment tracking between specs and tasks.
+ *
+ * Provides bidirectional mapping from spec items to implementing tasks,
+ * and detects alignment issues like orphaned specs or stale implementation status.
+ */
+import type { LoadedSpecItem, LoadedTask, KspecContext } from './yaml.js';
+import type { ReferenceIndex } from './refs.js';
+import type { ImplementationStatus } from '../schema/index.js';
+/**
+ * Summary of a spec item's implementation status based on linked tasks
+ */
+export interface SpecImplementationSummary {
+    specUlid: string;
+    specTitle: string;
+    currentStatus: ImplementationStatus;
+    expectedStatus: ImplementationStatus;
+    linkedTasks: LinkedTaskSummary[];
+    isAligned: boolean;
+}
+/**
+ * Summary of a task linked to a spec item
+ */
+export interface LinkedTaskSummary {
+    taskUlid: string;
+    taskTitle: string;
+    taskStatus: string;
+    hasNotes: boolean;
+}
+/**
+ * Alignment warning
+ */
+export interface AlignmentWarning {
+    type: 'orphaned_spec' | 'status_mismatch' | 'stale_implementation';
+    specUlid?: string;
+    specTitle?: string;
+    taskUlid?: string;
+    message: string;
+}
+/**
+ * Index for tracking spec-task alignment.
+ * Build once when loading, then query for alignment issues.
+ */
+export declare class AlignmentIndex {
+    /** spec ULID → task ULIDs that reference it */
+    private specToTasks;
+    /** task ULID → spec ULID it references */
+    private taskToSpec;
+    /** All spec items by ULID */
+    private specItems;
+    /** All tasks by ULID */
+    private tasks;
+    /**
+     * Build index from loaded items
+     */
+    constructor(tasks: LoadedTask[], items: LoadedSpecItem[]);
+    /**
+     * Resolve task spec_refs and build the bidirectional index.
+     * Must be called with a ReferenceIndex to resolve @refs.
+     */
+    buildLinks(refIndex: ReferenceIndex): void;
+    /**
+     * Get tasks that implement a spec item
+     */
+    getTasksForSpec(specUlid: string): LoadedTask[];
+    /**
+     * Get the spec item a task implements
+     */
+    getSpecForTask(taskUlid: string, refIndex: ReferenceIndex): LoadedSpecItem | undefined;
+    /**
+     * Calculate expected implementation status based on linked task statuses
+     */
+    calculateExpectedStatus(specUlid: string): ImplementationStatus;
+    /**
+     * Get implementation summary for a spec item
+     */
+    getImplementationSummary(specUlid: string): SpecImplementationSummary | undefined;
+    /**
+     * Find all alignment issues
+     */
+    findAlignmentWarnings(): AlignmentWarning[];
+    /**
+     * Get all spec items with their implementation summary
+     */
+    getAllImplementationSummaries(): SpecImplementationSummary[];
+    /**
+     * Get stats about alignment
+     */
+    getStats(): {
+        totalSpecs: number;
+        specsWithTasks: number;
+        alignedSpecs: number;
+        orphanedSpecs: number;
+    };
+}
+/**
+ * Result of syncing spec implementation status
+ */
+export interface SyncResult {
+    synced: boolean;
+    specUlid: string;
+    specTitle: string;
+    previousStatus: ImplementationStatus;
+    newStatus: ImplementationStatus;
+}
+/**
+ * Sync a spec item's implementation status based on its linked tasks.
+ * Called after task state changes (start, complete, etc.).
+ *
+ * @returns SyncResult if status changed, null if no change needed or no spec_ref
+ */
+export declare function syncSpecImplementationStatus(ctx: KspecContext, task: LoadedTask, allTasks: LoadedTask[], allItems: LoadedSpecItem[], refIndex: ReferenceIndex): Promise<SyncResult | null>;
+//# sourceMappingURL=alignment.d.ts.map

package/dist/parser/alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../src/parser/alignment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAM/D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,oBAAoB,CAAC;IACpC,cAAc,EAAE,oBAAoB,CAAC;IACrC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,qBAAa,cAAc;IACzB,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAA+B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,UAAU,CAA6B;IAE/C,6BAA6B;IAC7B,OAAO,CAAC,SAAS,CAAqC;IAEtD,wBAAwB;IACxB,OAAO,CAAC,KAAK,CAAiC;IAE9C;;OAEG;gBACS,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;IAkBxD;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAa1C;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IAO/C;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS;IAWtF;;OAEG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB;IA4B/D;;OAEG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IA4BjF;;OAEG;IACH,qBAAqB,IAAI,gBAAgB,EAAE;IA4C3C;;OAEG;IACH,6BAA6B,IAAI,yBAAyB,EAAE;IAW5D;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB;CAyBF;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6C5B"}

package/dist/parser/alignment.js

@@ -0,0 +1,261 @@
+/**
+ * Alignment tracking between specs and tasks.
+ *
+ * Provides bidirectional mapping from spec items to implementing tasks,
+ * and detects alignment issues like orphaned specs or stale implementation status.
+ */
+import { updateSpecItem } from './yaml.js';
+// ============================================================
+// ALIGNMENT INDEX
+// ============================================================
+/**
+ * Index for tracking spec-task alignment.
+ * Build once when loading, then query for alignment issues.
+ */
+export class AlignmentIndex {
+    /** spec ULID → task ULIDs that reference it */
+    specToTasks = new Map();
+    /** task ULID → spec ULID it references */
+    taskToSpec = new Map();
+    /** All spec items by ULID */
+    specItems = new Map();
+    /** All tasks by ULID */
+    tasks = new Map();
+    /**
+     * Build index from loaded items
+     */
+    constructor(tasks, items) {
+        // Index spec items
+        for (const item of items) {
+            this.specItems.set(item._ulid, item);
+            this.specToTasks.set(item._ulid, []);
+        }
+        // Index tasks and build reverse mapping
+        for (const task of tasks) {
+            this.tasks.set(task._ulid, task);
+            if (task.spec_ref) {
+                // Store the raw ref - we'll resolve it when needed
+                this.taskToSpec.set(task._ulid, task.spec_ref);
+            }
+        }
+    }
+    /**
+     * Resolve task spec_refs and build the bidirectional index.
+     * Must be called with a ReferenceIndex to resolve @refs.
+     */
+    buildLinks(refIndex) {
+        for (const [taskUlid, specRef] of this.taskToSpec) {
+            const result = refIndex.resolve(specRef);
+            if (result.ok) {
+                const specUlid = result.ulid;
+                const existing = this.specToTasks.get(specUlid);
+                if (existing) {
+                    existing.push(taskUlid);
+                }
+            }
+        }
+    }
+    /**
+     * Get tasks that implement a spec item
+     */
+    getTasksForSpec(specUlid) {
+        const taskUlids = this.specToTasks.get(specUlid) || [];
+        return taskUlids
+            .map(ulid => this.tasks.get(ulid))
+            .filter((t) => t !== undefined);
+    }
+    /**
+     * Get the spec item a task implements
+     */
+    getSpecForTask(taskUlid, refIndex) {
+        const specRef = this.taskToSpec.get(taskUlid);
+        if (!specRef)
+            return undefined;
+        const result = refIndex.resolve(specRef);
+        if (result.ok) {
+            return this.specItems.get(result.ulid);
+        }
+        return undefined;
+    }
+    /**
+     * Calculate expected implementation status based on linked task statuses
+     */
+    calculateExpectedStatus(specUlid) {
+        const taskUlids = this.specToTasks.get(specUlid) || [];
+        if (taskUlids.length === 0) {
+            return 'not_started';
+        }
+        const tasks = taskUlids
+            .map(ulid => this.tasks.get(ulid))
+            .filter((t) => t !== undefined);
+        if (tasks.length === 0) {
+            return 'not_started';
+        }
+        // Check task statuses
+        const hasInProgress = tasks.some(t => t.status === 'in_progress');
+        const allCompleted = tasks.every(t => t.status === 'completed');
+        const someCompleted = tasks.some(t => t.status === 'completed');
+        if (allCompleted) {
+            return 'implemented';
+        }
+        if (hasInProgress || someCompleted) {
+            return 'in_progress';
+        }
+        return 'not_started';
+    }
+    /**
+     * Get implementation summary for a spec item
+     */
+    getImplementationSummary(specUlid) {
+        const spec = this.specItems.get(specUlid);
+        if (!spec)
+            return undefined;
+        const taskUlids = this.specToTasks.get(specUlid) || [];
+        const linkedTasks = taskUlids
+            .map(ulid => this.tasks.get(ulid))
+            .filter((t) => t !== undefined)
+            .map(t => ({
+            taskUlid: t._ulid,
+            taskTitle: t.title,
+            taskStatus: t.status,
+            hasNotes: t.notes.length > 0,
+        }));
+        const currentStatus = spec.status?.implementation || 'not_started';
+        const expectedStatus = this.calculateExpectedStatus(specUlid);
+        return {
+            specUlid,
+            specTitle: spec.title,
+            currentStatus,
+            expectedStatus,
+            linkedTasks,
+            isAligned: currentStatus === expectedStatus,
+        };
+    }
+    /**
+     * Find all alignment issues
+     */
+    findAlignmentWarnings() {
+        const warnings = [];
+        // Check each spec item
+        for (const [specUlid, spec] of this.specItems) {
+            const taskUlids = this.specToTasks.get(specUlid) || [];
+            const currentStatus = spec.status?.implementation || 'not_started';
+            const expectedStatus = this.calculateExpectedStatus(specUlid);
+            // Orphaned spec (no tasks)
+            if (taskUlids.length === 0 && currentStatus === 'not_started') {
+                warnings.push({
+                    type: 'orphaned_spec',
+                    specUlid,
+                    specTitle: spec.title,
+                    message: `Spec item "${spec.title}" has no implementing tasks`,
+                });
+            }
+            // Status mismatch
+            if (currentStatus !== expectedStatus) {
+                warnings.push({
+                    type: 'status_mismatch',
+                    specUlid,
+                    specTitle: spec.title,
+                    message: `Spec "${spec.title}" status is "${currentStatus}" but should be "${expectedStatus}" based on task progress`,
+                });
+            }
+        }
+        // Check completed tasks with stale spec status
+        for (const [taskUlid, task] of this.tasks) {
+            if (task.status === 'completed' && task.spec_ref) {
+                const specRef = this.taskToSpec.get(taskUlid);
+                if (specRef) {
+                    // Note: We already checked this via spec iteration above
+                    // But this provides task-centric context
+                }
+            }
+        }
+        return warnings;
+    }
+    /**
+     * Get all spec items with their implementation summary
+     */
+    getAllImplementationSummaries() {
+        const summaries = [];
+        for (const specUlid of this.specItems.keys()) {
+            const summary = this.getImplementationSummary(specUlid);
+            if (summary) {
+                summaries.push(summary);
+            }
+        }
+        return summaries;
+    }
+    /**
+     * Get stats about alignment
+     */
+    getStats() {
+        let specsWithTasks = 0;
+        let alignedSpecs = 0;
+        let orphanedSpecs = 0;
+        for (const specUlid of this.specItems.keys()) {
+            const taskUlids = this.specToTasks.get(specUlid) || [];
+            if (taskUlids.length > 0) {
+                specsWithTasks++;
+                const summary = this.getImplementationSummary(specUlid);
+                if (summary?.isAligned) {
+                    alignedSpecs++;
+                }
+            }
+            else {
+                orphanedSpecs++;
+            }
+        }
+        return {
+            totalSpecs: this.specItems.size,
+            specsWithTasks,
+            alignedSpecs,
+            orphanedSpecs,
+        };
+    }
+}
+/**
+ * Sync a spec item's implementation status based on its linked tasks.
+ * Called after task state changes (start, complete, etc.).
+ *
+ * @returns SyncResult if status changed, null if no change needed or no spec_ref
+ */
+export async function syncSpecImplementationStatus(ctx, task, allTasks, allItems, refIndex) {
+    // Skip if task has no spec_ref
+    if (!task.spec_ref) {
+        return null;
+    }
+    // Resolve the spec reference
+    const result = refIndex.resolve(task.spec_ref);
+    if (!result.ok) {
+        return null;
+    }
+    // Find the spec item
+    const specItem = allItems.find(item => item._ulid === result.ulid);
+    if (!specItem) {
+        return null;
+    }
+    // Build alignment index to calculate expected status
+    const alignmentIndex = new AlignmentIndex(allTasks, allItems);
+    alignmentIndex.buildLinks(refIndex);
+    const expectedStatus = alignmentIndex.calculateExpectedStatus(specItem._ulid);
+    const currentStatus = specItem.status?.implementation || 'not_started';
+    // No change needed
+    if (currentStatus === expectedStatus) {
+        return null;
+    }
+    // Update the spec item
+    await updateSpecItem(ctx, specItem, {
+        status: {
+            maturity: specItem.status?.maturity || 'draft',
+            implementation: expectedStatus,
+        },
+    });
+    return {
+        synced: true,
+        specUlid: specItem._ulid,
+        specTitle: specItem.title,
+        previousStatus: currentStatus,
+        newStatus: expectedStatus,
+    };
+}
+//# sourceMappingURL=alignment.js.map

package/dist/parser/alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.js","sourceRoot":"","sources":["../../src/parser/alignment.ts"],"names":[],"mappings":"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"}

package/dist/parser/assess.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Task automation assessment logic.
+ *
+ * Provides criteria checking for task automation eligibility.
+ * AC: @tasks-assess-automation
+ */
+import type { LoadedTask, LoadedSpecItem } from './yaml.js';
+import type { ReferenceIndex } from './refs.js';
+/**
+ * Criterion check result
+ */
+export interface CriterionResult {
+    pass: boolean;
+    /** For skipped criteria (neutral) */
+    skipped?: boolean;
+    /** Additional context */
+    detail?: string;
+}
+/**
+ * Full assessment result for a task
+ * AC: @tasks-assess-automation ac-3, ac-4
+ */
+export interface TaskAssessment {
+    taskRef: string;
+    taskUlid: string;
+    taskTitle: string;
+    taskType: string;
+    criteria: {
+        has_spec_ref: CriterionResult & {
+            spec_ref?: string;
+        };
+        spec_has_acs: CriterionResult & {
+            ac_count?: number;
+        };
+        not_spike: CriterionResult;
+    };
+    recommendation: 'review_for_eligible' | 'needs_review' | 'manual_only';
+    reason: string;
+}
+/**
+ * Assessment summary counts
+ * AC: @tasks-assess-automation ac-5, ac-25
+ */
+export interface AssessmentSummary {
+    review_for_eligible: number;
+    needs_review: number;
+    manual_only: number;
+    total: number;
+}
+/**
+ * Assess a single task's automation eligibility
+ * AC: @tasks-assess-automation ac-8 through ac-16
+ */
+export declare function assessTask(task: LoadedTask, index: ReferenceIndex, items: LoadedSpecItem[]): TaskAssessment;
+/**
+ * Filter tasks for assessment
+ * AC: @tasks-assess-automation ac-1, ac-2, ac-27, ac-28
+ */
+export declare function filterTasksForAssessment(tasks: LoadedTask[], options: {
+    all?: boolean;
+    taskRef?: string;
+}, index: ReferenceIndex): LoadedTask[];
+/**
+ * Compute summary counts from assessments
+ * AC: @tasks-assess-automation ac-5, ac-25
+ */
+export declare function computeSummary(assessments: TaskAssessment[]): AssessmentSummary;
+/**
+ * Determine what changes auto mode would make
+ * AC: @tasks-assess-automation ac-17, ac-18, ac-21
+ */
+export interface AutoModeChange {
+    taskRef: string;
+    taskUlid: string;
+    taskTitle: string;
+    action: 'set_manual_only' | 'set_needs_review' | 'no_change';
+    newStatus?: 'manual_only' | 'needs_review';
+    reason: string;
+}
+export declare function computeAutoModeChanges(assessments: TaskAssessment[]): AutoModeChange[];
+//# sourceMappingURL=assess.d.ts.map

package/dist/parser/assess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assess.d.ts","sourceRoot":"","sources":["../../src/parser/assess.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE;QACR,YAAY,EAAE,eAAe,GAAG;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACtD,YAAY,EAAE,eAAe,GAAG;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACtD,SAAS,EAAE,eAAe,CAAC;KAC5B,CAAC;IACF,cAAc,EAAE,qBAAqB,GAAG,cAAc,GAAG,aAAa,CAAC;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,cAAc,EAAE,GACtB,cAAc,CAmChB;AA8GD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5C,KAAK,EAAE,cAAc,GACpB,UAAU,EAAE,CAsBd;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,cAAc,EAAE,GAAG,iBAAiB,CAa/E;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,WAAW,CAAC;IAC7D,SAAS,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAmCtF"}

package/dist/parser/assess.js

@@ -0,0 +1,197 @@
+/**
+ * Task automation assessment logic.
+ *
+ * Provides criteria checking for task automation eligibility.
+ * AC: @tasks-assess-automation
+ */
+// ============================================================
+// ASSESSMENT LOGIC
+// ============================================================
+/**
+ * Assess a single task's automation eligibility
+ * AC: @tasks-assess-automation ac-8 through ac-16
+ */
+export function assessTask(task, index, items) {
+    const taskRef = task.slugs.length > 0 ? `@${task.slugs[0]}` : `@${task._ulid.slice(0, 8)}`;
+    const taskType = task.type || 'task';
+    // AC: @tasks-assess-automation ac-8, ac-9 - Check has_spec_ref
+    const hasSpecRefResult = checkHasSpecRef(task, index);
+    // AC: @tasks-assess-automation ac-10, ac-11 - Check spec_has_acs
+    const specHasAcsResult = checkSpecHasAcs(task, index, items);
+    // AC: @tasks-assess-automation ac-12, ac-13 - Check not_spike
+    const notSpikeResult = checkNotSpike(task);
+    // Compute recommendation
+    // AC: @tasks-assess-automation ac-14, ac-15, ac-16
+    const { recommendation, reason } = computeRecommendation(hasSpecRefResult, specHasAcsResult, notSpikeResult, taskType);
+    return {
+        taskRef,
+        taskUlid: task._ulid,
+        taskTitle: task.title,
+        taskType,
+        criteria: {
+            has_spec_ref: hasSpecRefResult,
+            spec_has_acs: specHasAcsResult,
+            not_spike: notSpikeResult,
+        },
+        recommendation,
+        reason,
+    };
+}
+/**
+ * Check if task has spec_ref pointing to resolvable spec
+ * AC: @tasks-assess-automation ac-8, ac-9
+ */
+function checkHasSpecRef(task, index) {
+    if (!task.spec_ref) {
+        return { pass: false, detail: 'missing' };
+    }
+    const resolved = index.resolve(task.spec_ref);
+    if (!resolved.ok) {
+        return { pass: false, detail: 'unresolvable', spec_ref: task.spec_ref };
+    }
+    return { pass: true, spec_ref: task.spec_ref };
+}
+/**
+ * Check if linked spec has acceptance criteria
+ * AC: @tasks-assess-automation ac-10, ac-11
+ */
+function checkSpecHasAcs(task, index, items) {
+    // AC: @tasks-assess-automation ac-11 - skipped if no spec_ref
+    if (!task.spec_ref) {
+        return { pass: false, skipped: true, detail: 'no spec to check' };
+    }
+    const resolved = index.resolve(task.spec_ref);
+    if (!resolved.ok) {
+        return { pass: false, skipped: true, detail: 'spec not resolvable' };
+    }
+    // Find the spec item
+    const specItem = items.find(i => i._ulid === resolved.ulid);
+    if (!specItem) {
+        return { pass: false, skipped: true, detail: 'spec not found in items' };
+    }
+    const acCount = specItem.acceptance_criteria?.length || 0;
+    if (acCount === 0) {
+        return { pass: false, ac_count: 0, detail: 'spec has no acceptance criteria' };
+    }
+    return { pass: true, ac_count: acCount };
+}
+/**
+ * Check if task type is not spike
+ * AC: @tasks-assess-automation ac-12, ac-13
+ */
+function checkNotSpike(task) {
+    const taskType = task.type || 'task';
+    if (taskType === 'spike') {
+        return { pass: false, detail: 'type: spike' };
+    }
+    return { pass: true, detail: `type: ${taskType}` };
+}
+/**
+ * Compute recommendation based on criteria results
+ * AC: @tasks-assess-automation ac-14, ac-15, ac-16
+ */
+function computeRecommendation(hasSpecRef, specHasAcs, notSpike, taskType) {
+    // AC: @tasks-assess-automation ac-14 - Spikes are always manual_only
+    if (!notSpike.pass) {
+        return {
+            recommendation: 'manual_only',
+            reason: 'Spikes output knowledge, not automatable code',
+        };
+    }
+    // AC: @tasks-assess-automation ac-15 - Missing spec or no ACs → needs_review
+    const reasons = [];
+    if (!hasSpecRef.pass) {
+        reasons.push('missing spec_ref');
+    }
+    if (!specHasAcs.pass && !specHasAcs.skipped) {
+        reasons.push('spec has no acceptance criteria');
+    }
+    else if (specHasAcs.skipped && !hasSpecRef.pass) {
+        // Only add this if spec is missing (not if spec is unresolvable)
+    }
+    if (reasons.length > 0) {
+        return {
+            recommendation: 'needs_review',
+            reason: reasons.join(', '),
+        };
+    }
+    // AC: @tasks-assess-automation ac-16 - All criteria pass → review_for_eligible
+    return {
+        recommendation: 'review_for_eligible',
+        reason: 'Criteria pass - verify spec is appropriate and ACs are adequate',
+    };
+}
+/**
+ * Filter tasks for assessment
+ * AC: @tasks-assess-automation ac-1, ac-2, ac-27, ac-28
+ */
+export function filterTasksForAssessment(tasks, options, index) {
+    let filtered = tasks;
+    // AC: @tasks-assess-automation ac-28 - Exclude non-pending tasks
+    filtered = filtered.filter(t => t.status === 'pending');
+    // AC: @tasks-assess-automation ac-6 - Single task assessment
+    if (options.taskRef) {
+        const resolved = index.resolve(options.taskRef);
+        if (!resolved.ok) {
+            return []; // Will be handled by caller
+        }
+        filtered = filtered.filter(t => t._ulid === resolved.ulid);
+        return filtered;
+    }
+    // AC: @tasks-assess-automation ac-1, ac-27 - Filter by unassessed unless --all
+    if (!options.all) {
+        filtered = filtered.filter(t => !t.automation);
+    }
+    return filtered;
+}
+/**
+ * Compute summary counts from assessments
+ * AC: @tasks-assess-automation ac-5, ac-25
+ */
+export function computeSummary(assessments) {
+    const summary = {
+        review_for_eligible: 0,
+        needs_review: 0,
+        manual_only: 0,
+        total: assessments.length,
+    };
+    for (const assessment of assessments) {
+        summary[assessment.recommendation]++;
+    }
+    return summary;
+}
+export function computeAutoModeChanges(assessments) {
+    return assessments.map(assessment => {
+        // AC: @tasks-assess-automation ac-17 - Spikes → manual_only
+        if (assessment.recommendation === 'manual_only') {
+            return {
+                taskRef: assessment.taskRef,
+                taskUlid: assessment.taskUlid,
+                taskTitle: assessment.taskTitle,
+                action: 'set_manual_only',
+                newStatus: 'manual_only',
+                reason: assessment.reason,
+            };
+        }
+        // AC: @tasks-assess-automation ac-17 - Missing criteria → needs_review
+        if (assessment.recommendation === 'needs_review') {
+            return {
+                taskRef: assessment.taskRef,
+                taskUlid: assessment.taskUlid,
+                taskTitle: assessment.taskTitle,
+                action: 'set_needs_review',
+                newStatus: 'needs_review',
+                reason: assessment.reason,
+            };
+        }
+        // AC: @tasks-assess-automation ac-18, ac-21 - review_for_eligible → no change
+        return {
+            taskRef: assessment.taskRef,
+            taskUlid: assessment.taskUlid,
+            taskTitle: assessment.taskTitle,
+            action: 'no_change',
+            reason: 'Passes criteria - requires agent/human review to mark eligible',
+        };
+    });
+}
+//# sourceMappingURL=assess.js.map