@backlog-md/core 0.3.7 → 0.3.9

package/dist/core/Core.js

@@ -4,7 +4,9 @@
  * Provides a runtime-agnostic API for managing Backlog.md projects
  * by accepting adapter implementations for I/O operations.
  */
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
 import { extractMilestoneIdFromFilename, extractTaskIndexFromPath, getMilestoneFilename, parseMilestoneMarkdown, parseTaskMarkdown, serializeMilestoneMarkdown, serializeTaskMarkdown, } from "../markdown";
+import { getTracer } from "../telemetry";
 import { DEFAULT_TASK_STATUSES } from "../types";
 import { groupTasksByMilestone, groupTasksByStatus, milestoneKey, sortTasks, sortTasksBy, } from "../utils";
 import { parseBacklogConfig, serializeBacklogConfig } from "./config-parser";
@@ -26,6 +28,7 @@ import { parseBacklogConfig, serializeBacklogConfig } from "./config-parser";
 export class Core {
     projectRoot;
     fs;
+    tracer;
     config = null;
     tasks = new Map();
     initialized = false;
@@ -35,6 +38,9 @@ export class Core {
     constructor(options) {
         this.projectRoot = options.projectRoot;
         this.fs = options.adapters.fs;
+        // Get tracer from global provider (set up by the application)
+        // Returns no-op tracer if no provider is registered
+        this.tracer = getTracer();
     }
     /**
      * Check if projectRoot contains a valid Backlog.md project
@@ -106,25 +112,80 @@ export class Core {
     async initialize() {
         if (this.initialized)
             return;
-        // Load config
-        const configPath = this.fs.join(this.projectRoot, "backlog", "config.yml");
-        const configExists = await this.fs.exists(configPath);
-        if (!configExists) {
-            throw new Error(`Not a Backlog.md project: config.yml not found at ${configPath}`);
-        }
-        const configContent = await this.fs.readFile(configPath);
-        this.config = parseBacklogConfig(configContent);
-        // Load tasks from tasks/ directory
-        const tasksDir = this.fs.join(this.projectRoot, "backlog", "tasks");
-        if (await this.fs.exists(tasksDir)) {
-            await this.loadTasksFromDirectory(tasksDir, "local");
-        }
-        // Load tasks from completed/ directory
-        const completedDir = this.fs.join(this.projectRoot, "backlog", "completed");
-        if (await this.fs.exists(completedDir)) {
-            await this.loadTasksFromDirectory(completedDir, "completed");
-        }
-        this.initialized = true;
+        const span = this.tracer.startSpan("core.init", {
+            attributes: {
+                projectRoot: this.projectRoot,
+                mode: "full",
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            const startTime = Date.now();
+            try {
+                span.addEvent("core.init.started", {
+                    projectRoot: this.projectRoot,
+                    mode: "full",
+                });
+                // Load config
+                const configPath = this.fs.join(this.projectRoot, "backlog", "config.yml");
+                const configExists = await this.fs.exists(configPath);
+                if (!configExists) {
+                    const error = new Error(`Not a Backlog.md project: config.yml not found at ${configPath}`);
+                    span.addEvent("core.init.error", {
+                        "error.type": "ConfigNotFoundError",
+                        "error.message": error.message,
+                        stage: "config",
+                    });
+                    span.recordException(error);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+                    throw error;
+                }
+                const configContent = await this.fs.readFile(configPath);
+                this.config = parseBacklogConfig(configContent);
+                span.addEvent("core.init.config.loaded", {
+                    projectName: this.config.projectName,
+                    statusCount: this.config.statuses.length,
+                    labelCount: this.config.labels?.length ?? 0,
+                });
+                // Load tasks from tasks/ directory
+                let localTaskCount = 0;
+                const tasksDir = this.fs.join(this.projectRoot, "backlog", "tasks");
+                if (await this.fs.exists(tasksDir)) {
+                    await this.loadTasksFromDirectory(tasksDir, "local");
+                    localTaskCount = Array.from(this.tasks.values()).filter((t) => t.source === "local").length;
+                }
+                // Load tasks from completed/ directory
+                let completedTaskCount = 0;
+                const completedDir = this.fs.join(this.projectRoot, "backlog", "completed");
+                if (await this.fs.exists(completedDir)) {
+                    await this.loadTasksFromDirectory(completedDir, "completed");
+                    completedTaskCount = Array.from(this.tasks.values()).filter((t) => t.source === "completed").length;
+                }
+                const totalTaskCount = this.tasks.size;
+                span.addEvent("core.init.tasks.loaded", {
+                    localTaskCount,
+                    completedTaskCount,
+                    totalTaskCount,
+                });
+                this.initialized = true;
+                const duration = Date.now() - startTime;
+                span.addEvent("core.init.complete", {
+                    success: true,
+                    "duration.ms": duration,
+                    taskCount: totalTaskCount,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    span.recordException(error);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+                }
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /**
      * Initialize with lazy loading (no file content reads)
@@ -474,43 +535,76 @@ export class Core {
      * @returns Created milestone
      */
     async createMilestone(input) {
-        const milestonesDir = this.getMilestonesDir();
-        // Ensure milestones directory exists
-        await this.fs.createDir(milestonesDir, { recursive: true });
-        // Find next available milestone ID
-        const entries = await this.fs.readDir(milestonesDir).catch(() => []);
-        const existingIds = entries
-            .map((f) => {
-            const match = f.match(/^m-(\d+)/);
-            return match?.[1] ? parseInt(match[1], 10) : -1;
-        })
-            .filter((id) => id >= 0);
-        const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 0;
-        const id = `m-${nextId}`;
-        const description = input.description || `Milestone: ${input.title}`;
-        // Create a temporary milestone to generate content
-        const tempMilestone = {
-            id,
-            title: input.title,
-            description,
-            rawContent: "",
-            tasks: [],
-        };
-        // Generate content
-        const content = serializeMilestoneMarkdown(tempMilestone);
-        // Create the final milestone with correct rawContent
-        const milestone = {
-            id,
-            title: input.title,
-            description,
-            rawContent: content,
-            tasks: [],
-        };
-        // Write file
-        const filename = getMilestoneFilename(id, input.title);
-        const filepath = this.fs.join(milestonesDir, filename);
-        await this.fs.writeFile(filepath, content);
-        return milestone;
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("milestone.create", {
+            attributes: {
+                "input.title": input.title,
+                "input.hasDescription": input.description !== undefined,
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                span.addEvent("milestone.create.started", {
+                    "input.title": input.title,
+                    "input.hasDescription": input.description !== undefined,
+                });
+                const milestonesDir = this.getMilestonesDir();
+                // Ensure milestones directory exists
+                await this.fs.createDir(milestonesDir, { recursive: true });
+                // Find next available milestone ID
+                const entries = await this.fs.readDir(milestonesDir).catch(() => []);
+                const existingIds = entries
+                    .map((f) => {
+                    const match = f.match(/^m-(\d+)/);
+                    return match?.[1] ? parseInt(match[1], 10) : -1;
+                })
+                    .filter((id) => id >= 0);
+                const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 0;
+                const id = `m-${nextId}`;
+                const description = input.description || `Milestone: ${input.title}`;
+                // Create a temporary milestone to generate content
+                const tempMilestone = {
+                    id,
+                    title: input.title,
+                    description,
+                    rawContent: "",
+                    tasks: [],
+                };
+                // Generate content
+                const content = serializeMilestoneMarkdown(tempMilestone);
+                // Create the final milestone with correct rawContent
+                const milestone = {
+                    id,
+                    title: input.title,
+                    description,
+                    rawContent: content,
+                    tasks: [],
+                };
+                // Write file
+                const filename = getMilestoneFilename(id, input.title);
+                const filepath = this.fs.join(milestonesDir, filename);
+                await this.fs.writeFile(filepath, content);
+                span.addEvent("milestone.create.complete", {
+                    "output.milestoneId": id,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return milestone;
+            }
+            catch (error) {
+                span.addEvent("milestone.create.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
+            }
+        });
     }
     /**
      * Update an existing milestone
@@ -520,49 +614,101 @@ export class Core {
      * @returns Updated milestone or null if not found
      */
     async updateMilestone(id, input) {
-        const existing = await this.loadMilestone(id);
-        if (!existing) {
-            return null;
-        }
-        const milestonesDir = this.getMilestonesDir();
-        const entries = await this.fs.readDir(milestonesDir);
-        // Find the current file
-        const currentFile = entries.find((entry) => {
-            const fileId = extractMilestoneIdFromFilename(entry);
-            return fileId === id;
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("milestone.update", {
+            attributes: {
+                "input.milestoneId": id,
+                "input.hasTitle": input.title !== undefined,
+                "input.hasDescription": input.description !== undefined,
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                span.addEvent("milestone.update.started", {
+                    "input.milestoneId": id,
+                    "input.hasTitle": input.title !== undefined,
+                    "input.hasDescription": input.description !== undefined,
+                });
+                const existing = await this.loadMilestone(id);
+                if (!existing) {
+                    span.addEvent("milestone.update.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Milestone not found",
+                        "input.milestoneId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return null;
+                }
+                const milestonesDir = this.getMilestonesDir();
+                const entries = await this.fs.readDir(milestonesDir);
+                // Find the current file
+                const currentFile = entries.find((entry) => {
+                    const fileId = extractMilestoneIdFromFilename(entry);
+                    return fileId === id;
+                });
+                if (!currentFile) {
+                    span.addEvent("milestone.update.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Milestone file not found",
+                        "input.milestoneId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return null;
+                }
+                // Build updated values
+                const newTitle = input.title ?? existing.title;
+                const newDescription = input.description ?? existing.description;
+                const titleChanged = input.title !== undefined && input.title !== existing.title;
+                // Create a temporary milestone to generate content
+                const tempMilestone = {
+                    id: existing.id,
+                    title: newTitle,
+                    description: newDescription,
+                    rawContent: "",
+                    tasks: existing.tasks,
+                };
+                // Generate new content
+                const content = serializeMilestoneMarkdown(tempMilestone);
+                // Create the final updated milestone
+                const updated = {
+                    id: existing.id,
+                    title: newTitle,
+                    description: newDescription,
+                    rawContent: content,
+                    tasks: existing.tasks,
+                };
+                // Delete old file
+                const oldPath = this.fs.join(milestonesDir, currentFile);
+                await this.fs.deleteFile(oldPath);
+                // Write new file (with potentially new filename if title changed)
+                const newFilename = getMilestoneFilename(id, updated.title);
+                const newPath = this.fs.join(milestonesDir, newFilename);
+                await this.fs.writeFile(newPath, content);
+                span.addEvent("milestone.update.complete", {
+                    "output.milestoneId": id,
+                    "output.titleChanged": titleChanged,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return updated;
+            }
+            catch (error) {
+                span.addEvent("milestone.update.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.milestoneId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
+            }
         });
-        if (!currentFile) {
-            return null;
-        }
-        // Build updated values
-        const newTitle = input.title ?? existing.title;
-        const newDescription = input.description ?? existing.description;
-        // Create a temporary milestone to generate content
-        const tempMilestone = {
-            id: existing.id,
-            title: newTitle,
-            description: newDescription,
-            rawContent: "",
-            tasks: existing.tasks,
-        };
-        // Generate new content
-        const content = serializeMilestoneMarkdown(tempMilestone);
-        // Create the final updated milestone
-        const updated = {
-            id: existing.id,
-            title: newTitle,
-            description: newDescription,
-            rawContent: content,
-            tasks: existing.tasks,
-        };
-        // Delete old file
-        const oldPath = this.fs.join(milestonesDir, currentFile);
-        await this.fs.deleteFile(oldPath);
-        // Write new file (with potentially new filename if title changed)
-        const newFilename = getMilestoneFilename(id, updated.title);
-        const newPath = this.fs.join(milestonesDir, newFilename);
-        await this.fs.writeFile(newPath, content);
-        return updated;
     }
     /**
      * Delete a milestone
@@ -571,27 +717,69 @@ export class Core {
      * @returns true if deleted, false if not found
      */
     async deleteMilestone(id) {
-        const milestonesDir = this.getMilestonesDir();
-        if (!(await this.fs.exists(milestonesDir))) {
-            return false;
-        }
-        const entries = await this.fs.readDir(milestonesDir);
-        // Find file matching the ID
-        const milestoneFile = entries.find((entry) => {
-            const fileId = extractMilestoneIdFromFilename(entry);
-            return fileId === id;
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("milestone.delete", {
+            attributes: {
+                "input.milestoneId": id,
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                span.addEvent("milestone.delete.started", {
+                    "input.milestoneId": id,
+                });
+                const milestonesDir = this.getMilestonesDir();
+                if (!(await this.fs.exists(milestonesDir))) {
+                    span.addEvent("milestone.delete.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Milestones directory not found",
+                        "input.milestoneId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return false;
+                }
+                const entries = await this.fs.readDir(milestonesDir);
+                // Find file matching the ID
+                const milestoneFile = entries.find((entry) => {
+                    const fileId = extractMilestoneIdFromFilename(entry);
+                    return fileId === id;
+                });
+                if (!milestoneFile) {
+                    span.addEvent("milestone.delete.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Milestone not found",
+                        "input.milestoneId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return false;
+                }
+                const filepath = this.fs.join(milestonesDir, milestoneFile);
+                await this.fs.deleteFile(filepath);
+                span.addEvent("milestone.delete.complete", {
+                    "output.milestoneId": id,
+                    "output.deleted": true,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return true;
+            }
+            catch (error) {
+                span.addEvent("milestone.delete.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.milestoneId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
+            }
         });
-        if (!milestoneFile) {
-            return false;
-        }
-        const filepath = this.fs.join(milestonesDir, milestoneFile);
-        try {
-            await this.fs.deleteFile(filepath);
-            return true;
-        }
-        catch {
-            return false;
-        }
     }
     /**
      * Get a single task by ID
@@ -867,81 +1055,117 @@ export class Core {
      */
     async createTask(input) {
         this.ensureInitialized();
-        const tasksDir = this.getTasksDir();
-        // Ensure tasks directory exists
-        await this.fs.createDir(tasksDir, { recursive: true });
-        // Generate next task ID
-        // Use taskIndex as source of truth (works for both lazy and full initialization)
-        const existingIds = Array.from(this.lazyInitialized ? this.taskIndex.keys() : this.tasks.keys())
-            .map((id) => parseInt(id.replace(/\D/g, ""), 10))
-            .filter((n) => !Number.isNaN(n));
-        const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 1;
-        const taskId = String(nextId);
-        // Validate and normalize status
-        const configStatuses = this.config?.statuses || [
-            DEFAULT_TASK_STATUSES.TODO,
-            DEFAULT_TASK_STATUSES.IN_PROGRESS,
-            DEFAULT_TASK_STATUSES.DONE,
-        ];
-        let status = input.status || this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO;
-        // Validate status against configured statuses
-        if (!configStatuses.includes(status)) {
-            console.warn(`Warning: Status "${status}" is not in configured statuses [${configStatuses.join(", ")}]. ` +
-                `Using default status "${this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO}" instead.`);
-            status = this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO;
-        }
-        // Build task object
-        const now = new Date().toISOString().split("T")[0];
-        const task = {
-            id: taskId,
-            title: input.title,
-            status,
-            priority: input.priority,
-            assignee: input.assignee || [],
-            createdDate: now,
-            labels: input.labels || [],
-            milestone: input.milestone,
-            dependencies: input.dependencies || [],
-            references: input.references || [],
-            parentTaskId: input.parentTaskId,
-            description: input.description,
-            implementationPlan: input.implementationPlan,
-            implementationNotes: input.implementationNotes,
-            acceptanceCriteriaItems: input.acceptanceCriteria?.map((ac, i) => ({
-                index: i + 1,
-                text: ac.text,
-                checked: ac.checked || false,
-            })),
-            rawContent: input.rawContent,
-            source: "local",
-        };
-        // Serialize and write file
-        const content = serializeTaskMarkdown(task);
-        const safeTitle = input.title
-            .replace(/[<>:"/\\|?*]/g, "")
-            .replace(/\s+/g, " ")
-            .slice(0, 50);
-        const filename = `${taskId} - ${safeTitle}.md`;
-        const filepath = this.fs.join(tasksDir, filename);
-        await this.fs.writeFile(filepath, content);
-        // Update in-memory cache
-        task.filePath = filepath;
-        this.tasks.set(taskId, task);
-        // Also update taskIndex if in lazy mode
-        if (this.lazyInitialized) {
-            const relativePath = filepath.replace(this.projectRoot + "/", "");
-            this.taskIndex.set(taskId, {
-                id: taskId,
-                filePath: relativePath,
-                title: task.title,
-                source: "tasks",
-            });
-        }
-        // Sync milestone if specified
-        if (input.milestone) {
-            await this.addTaskToMilestone(taskId, input.milestone);
-        }
-        return task;
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("task.create", {
+            attributes: {
+                "input.title": input.title,
+                "input.status": input.status,
+                "input.milestoneId": input.milestone,
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                span.addEvent("task.create.started", {
+                    "input.title": input.title,
+                    "input.status": input.status,
+                    "input.milestoneId": input.milestone,
+                });
+                const tasksDir = this.getTasksDir();
+                // Ensure tasks directory exists
+                await this.fs.createDir(tasksDir, { recursive: true });
+                // Generate next task ID
+                // Use taskIndex as source of truth (works for both lazy and full initialization)
+                const existingIds = Array.from(this.lazyInitialized ? this.taskIndex.keys() : this.tasks.keys())
+                    .map((id) => parseInt(id.replace(/\D/g, ""), 10))
+                    .filter((n) => !Number.isNaN(n));
+                const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 1;
+                const taskId = String(nextId);
+                // Validate and normalize status
+                const configStatuses = this.config?.statuses || [
+                    DEFAULT_TASK_STATUSES.TODO,
+                    DEFAULT_TASK_STATUSES.IN_PROGRESS,
+                    DEFAULT_TASK_STATUSES.DONE,
+                ];
+                let status = input.status || this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO;
+                // Validate status against configured statuses
+                if (!configStatuses.includes(status)) {
+                    console.warn(`Warning: Status "${status}" is not in configured statuses [${configStatuses.join(", ")}]. ` +
+                        `Using default status "${this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO}" instead.`);
+                    status = this.config?.defaultStatus || DEFAULT_TASK_STATUSES.TODO;
+                }
+                // Build task object
+                const now = new Date().toISOString().split("T")[0];
+                const task = {
+                    id: taskId,
+                    title: input.title,
+                    status,
+                    priority: input.priority,
+                    assignee: input.assignee || [],
+                    createdDate: now,
+                    labels: input.labels || [],
+                    milestone: input.milestone,
+                    dependencies: input.dependencies || [],
+                    references: input.references || [],
+                    parentTaskId: input.parentTaskId,
+                    description: input.description,
+                    implementationPlan: input.implementationPlan,
+                    implementationNotes: input.implementationNotes,
+                    acceptanceCriteriaItems: input.acceptanceCriteria?.map((ac, i) => ({
+                        index: i + 1,
+                        text: ac.text,
+                        checked: ac.checked || false,
+                    })),
+                    rawContent: input.rawContent,
+                    source: "local",
+                };
+                // Serialize and write file
+                const content = serializeTaskMarkdown(task);
+                const safeTitle = input.title
+                    .replace(/[<>:"/\\|?*]/g, "")
+                    .replace(/\s+/g, " ")
+                    .slice(0, 50);
+                const filename = `${taskId} - ${safeTitle}.md`;
+                const filepath = this.fs.join(tasksDir, filename);
+                await this.fs.writeFile(filepath, content);
+                // Update in-memory cache
+                task.filePath = filepath;
+                this.tasks.set(taskId, task);
+                // Also update taskIndex if in lazy mode
+                if (this.lazyInitialized) {
+                    const relativePath = filepath.replace(`${this.projectRoot}/`, "");
+                    this.taskIndex.set(taskId, {
+                        id: taskId,
+                        filePath: relativePath,
+                        title: task.title,
+                        source: "tasks",
+                    });
+                }
+                // Sync milestone if specified
+                if (input.milestone) {
+                    await this.addTaskToMilestone(taskId, input.milestone);
+                }
+                span.addEvent("task.create.complete", {
+                    "output.taskId": taskId,
+                    "output.taskIndex": nextId,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return task;
+            }
+            catch (error) {
+                span.addEvent("task.create.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
+            }
+        });
     }
     /**
      * Update an existing task
@@ -952,105 +1176,153 @@ export class Core {
      */
     async updateTask(id, input) {
         this.ensureInitialized();
-        const existing = this.tasks.get(id);
-        if (!existing) {
-            return null;
-        }
-        const oldMilestone = existing.milestone;
-        const newMilestone = input.milestone === null
-            ? undefined
-            : input.milestone !== undefined
-                ? input.milestone
-                : oldMilestone;
-        // Build updated task
-        const now = new Date().toISOString().split("T")[0];
-        const updated = {
-            ...existing,
-            title: input.title ?? existing.title,
-            status: input.status ?? existing.status,
-            priority: input.priority ?? existing.priority,
-            milestone: newMilestone,
-            updatedDate: now,
-            description: input.description ?? existing.description,
-            implementationPlan: input.clearImplementationPlan
-                ? undefined
-                : (input.implementationPlan ?? existing.implementationPlan),
-            implementationNotes: input.clearImplementationNotes
-                ? undefined
-                : (input.implementationNotes ?? existing.implementationNotes),
-            ordinal: input.ordinal ?? existing.ordinal,
-            dependencies: input.dependencies ?? existing.dependencies,
-            references: input.references ?? existing.references ?? [],
-        };
-        // Handle label operations
-        if (input.labels) {
-            updated.labels = input.labels;
-        }
-        else {
-            if (input.addLabels) {
-                updated.labels = [...new Set([...updated.labels, ...input.addLabels])];
-            }
-            if (input.removeLabels) {
-                updated.labels = updated.labels.filter((l) => !input.removeLabels?.includes(l));
-            }
-        }
-        // Handle assignee
-        if (input.assignee) {
-            updated.assignee = input.assignee;
-        }
-        // Handle dependency operations
-        if (input.addDependencies) {
-            updated.dependencies = [...new Set([...updated.dependencies, ...input.addDependencies])];
-        }
-        if (input.removeDependencies) {
-            updated.dependencies = updated.dependencies.filter((d) => !input.removeDependencies?.includes(d));
-        }
-        // Handle references operations
-        if (input.addReferences) {
-            updated.references = [...new Set([...(updated.references || []), ...input.addReferences])];
-        }
-        if (input.removeReferences) {
-            updated.references = (updated.references || []).filter((r) => !input.removeReferences?.includes(r));
-        }
-        // Handle acceptance criteria
-        if (input.acceptanceCriteria) {
-            updated.acceptanceCriteriaItems = input.acceptanceCriteria.map((ac, i) => ({
-                index: i + 1,
-                text: ac.text,
-                checked: ac.checked || false,
-            }));
-        }
-        // Serialize and write file
-        const content = serializeTaskMarkdown(updated);
-        // Delete old file if exists
-        if (existing.filePath) {
-            await this.fs.deleteFile(existing.filePath).catch(() => { });
-        }
-        // Write new file
-        const tasksDir = this.getTasksDir();
-        const safeTitle = updated.title
-            .replace(/[<>:"/\\|?*]/g, "")
-            .replace(/\s+/g, " ")
-            .slice(0, 50);
-        const filename = `${id} - ${safeTitle}.md`;
-        const filepath = this.fs.join(tasksDir, filename);
-        await this.fs.writeFile(filepath, content);
-        // Update in-memory cache
-        updated.filePath = filepath;
-        this.tasks.set(id, updated);
-        // Handle milestone sync
-        const milestoneChanged = milestoneKey(oldMilestone) !== milestoneKey(newMilestone);
-        if (milestoneChanged) {
-            // Remove from old milestone
-            if (oldMilestone) {
-                await this.removeTaskFromMilestone(id, oldMilestone);
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("task.update", {
+            attributes: {
+                "input.taskId": id,
+                "input.hasTitle": input.title !== undefined,
+                "input.hasStatus": input.status !== undefined,
+                "input.hasMilestone": input.milestone !== undefined,
+            },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                span.addEvent("task.update.started", {
+                    "input.taskId": id,
+                    "input.hasTitle": input.title !== undefined,
+                    "input.hasStatus": input.status !== undefined,
+                    "input.hasMilestone": input.milestone !== undefined,
+                });
+                const existing = this.tasks.get(id);
+                if (!existing) {
+                    span.addEvent("task.update.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Task not found",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK }); // Not found is not an error
+                    span.end();
+                    return null;
+                }
+                const oldMilestone = existing.milestone;
+                const newMilestone = input.milestone === null
+                    ? undefined
+                    : input.milestone !== undefined
+                        ? input.milestone
+                        : oldMilestone;
+                // Build updated task
+                const now = new Date().toISOString().split("T")[0];
+                const updated = {
+                    ...existing,
+                    title: input.title ?? existing.title,
+                    status: input.status ?? existing.status,
+                    priority: input.priority ?? existing.priority,
+                    milestone: newMilestone,
+                    updatedDate: now,
+                    description: input.description ?? existing.description,
+                    implementationPlan: input.clearImplementationPlan
+                        ? undefined
+                        : (input.implementationPlan ?? existing.implementationPlan),
+                    implementationNotes: input.clearImplementationNotes
+                        ? undefined
+                        : (input.implementationNotes ?? existing.implementationNotes),
+                    ordinal: input.ordinal ?? existing.ordinal,
+                    dependencies: input.dependencies ?? existing.dependencies,
+                    references: input.references ?? existing.references ?? [],
+                };
+                // Handle label operations
+                if (input.labels) {
+                    updated.labels = input.labels;
+                }
+                else {
+                    if (input.addLabels) {
+                        updated.labels = [...new Set([...updated.labels, ...input.addLabels])];
+                    }
+                    if (input.removeLabels) {
+                        updated.labels = updated.labels.filter((l) => !input.removeLabels?.includes(l));
+                    }
+                }
+                // Handle assignee
+                if (input.assignee) {
+                    updated.assignee = input.assignee;
+                }
+                // Handle dependency operations
+                if (input.addDependencies) {
+                    updated.dependencies = [...new Set([...updated.dependencies, ...input.addDependencies])];
+                }
+                if (input.removeDependencies) {
+                    updated.dependencies = updated.dependencies.filter((d) => !input.removeDependencies?.includes(d));
+                }
+                // Handle references operations
+                if (input.addReferences) {
+                    updated.references = [
+                        ...new Set([...(updated.references || []), ...input.addReferences]),
+                    ];
+                }
+                if (input.removeReferences) {
+                    updated.references = (updated.references || []).filter((r) => !input.removeReferences?.includes(r));
+                }
+                // Handle acceptance criteria
+                if (input.acceptanceCriteria) {
+                    updated.acceptanceCriteriaItems = input.acceptanceCriteria.map((ac, i) => ({
+                        index: i + 1,
+                        text: ac.text,
+                        checked: ac.checked || false,
+                    }));
+                }
+                // Serialize and write file
+                const content = serializeTaskMarkdown(updated);
+                // Delete old file if exists
+                if (existing.filePath) {
+                    await this.fs.deleteFile(existing.filePath).catch(() => { });
+                }
+                // Write new file
+                const tasksDir = this.getTasksDir();
+                const safeTitle = updated.title
+                    .replace(/[<>:"/\\|?*]/g, "")
+                    .replace(/\s+/g, " ")
+                    .slice(0, 50);
+                const filename = `${id} - ${safeTitle}.md`;
+                const filepath = this.fs.join(tasksDir, filename);
+                await this.fs.writeFile(filepath, content);
+                // Update in-memory cache
+                updated.filePath = filepath;
+                this.tasks.set(id, updated);
+                // Handle milestone sync
+                const milestoneChanged = milestoneKey(oldMilestone) !== milestoneKey(newMilestone);
+                if (milestoneChanged) {
+                    // Remove from old milestone
+                    if (oldMilestone) {
+                        await this.removeTaskFromMilestone(id, oldMilestone);
+                    }
+                    // Add to new milestone
+                    if (newMilestone) {
+                        await this.addTaskToMilestone(id, newMilestone);
+                    }
+                }
+                span.addEvent("task.update.complete", {
+                    "output.taskId": id,
+                    "output.statusChanged": input.status !== undefined,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return updated;
             }
-            // Add to new milestone
-            if (newMilestone) {
-                await this.addTaskToMilestone(id, newMilestone);
+            catch (error) {
+                span.addEvent("task.update.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.taskId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
             }
-        }
-        return updated;
+        });
     }
     /**
      * Delete a task
@@ -1060,26 +1332,62 @@ export class Core {
      */
     async deleteTask(id) {
         this.ensureInitialized();
-        const task = this.tasks.get(id);
-        if (!task) {
-            return false;
-        }
-        // Remove from milestone if assigned
-        if (task.milestone) {
-            await this.removeTaskFromMilestone(id, task.milestone);
-        }
-        // Delete file
-        if (task.filePath) {
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("task.delete", {
+            attributes: { "input.taskId": id },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
             try {
-                await this.fs.deleteFile(task.filePath);
+                span.addEvent("task.delete.started", { "input.taskId": id });
+                const task = this.tasks.get(id);
+                if (!task) {
+                    span.addEvent("task.delete.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Task not found",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return false;
+                }
+                // Remove from milestone if assigned
+                if (task.milestone) {
+                    await this.removeTaskFromMilestone(id, task.milestone);
+                }
+                // Delete file
+                if (task.filePath) {
+                    try {
+                        await this.fs.deleteFile(task.filePath);
+                    }
+                    catch {
+                        // File may already be deleted
+                    }
+                }
+                // Remove from in-memory cache
+                this.tasks.delete(id);
+                span.addEvent("task.delete.complete", {
+                    "output.taskId": id,
+                    "output.deleted": true,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return true;
             }
-            catch {
-                // File may already be deleted
+            catch (error) {
+                span.addEvent("task.delete.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.taskId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
             }
-        }
-        // Remove from in-memory cache
-        this.tasks.delete(id);
-        return true;
+        });
     }
     /**
      * Archive a task (move from tasks/ to completed/)
@@ -1089,53 +1397,96 @@ export class Core {
      */
     async archiveTask(id) {
         this.ensureInitialized();
-        const task = this.tasks.get(id);
-        if (!task) {
-            return null;
-        }
-        // Check if already in completed
-        if (task.source === "completed") {
-            return null;
-        }
-        const completedDir = this.getCompletedDir();
-        // Ensure completed directory exists
-        await this.fs.createDir(completedDir, { recursive: true });
-        // Build new filepath in completed/
-        const safeTitle = task.title
-            .replace(/[<>:"/\\|?*]/g, "")
-            .replace(/\s+/g, " ")
-            .slice(0, 50);
-        const filename = `${id} - ${safeTitle}.md`;
-        const newFilepath = this.fs.join(completedDir, filename);
-        // Delete old file
-        if (task.filePath) {
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("task.archive", {
+            attributes: { "input.taskId": id },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
             try {
-                await this.fs.deleteFile(task.filePath);
-            }
-            catch {
-                // File may not exist
+                span.addEvent("task.archive.started", { "input.taskId": id });
+                const task = this.tasks.get(id);
+                if (!task) {
+                    span.addEvent("task.archive.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Task not found",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK }); // Not found is not an error
+                    span.end();
+                    return null;
+                }
+                // Check if already in completed
+                if (task.source === "completed") {
+                    span.addEvent("task.archive.error", {
+                        "error.type": "InvalidStateError",
+                        "error.message": "Task already archived",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return null;
+                }
+                const completedDir = this.getCompletedDir();
+                // Ensure completed directory exists
+                await this.fs.createDir(completedDir, { recursive: true });
+                // Build new filepath in completed/
+                const safeTitle = task.title
+                    .replace(/[<>:"/\\|?*]/g, "")
+                    .replace(/\s+/g, " ")
+                    .slice(0, 50);
+                const filename = `${id} - ${safeTitle}.md`;
+                const newFilepath = this.fs.join(completedDir, filename);
+                // Delete old file
+                if (task.filePath) {
+                    try {
+                        await this.fs.deleteFile(task.filePath);
+                    }
+                    catch {
+                        // File may not exist
+                    }
+                }
+                // Update task
+                const archived = {
+                    ...task,
+                    source: "completed",
+                    filePath: newFilepath,
+                };
+                // Write to new location
+                const content = serializeTaskMarkdown(archived);
+                await this.fs.writeFile(newFilepath, content);
+                // Update in-memory cache
+                this.tasks.set(id, archived);
+                // Update task index if lazy initialized
+                if (this.lazyInitialized) {
+                    const entry = this.taskIndex.get(id);
+                    if (entry) {
+                        entry.source = "completed";
+                        entry.filePath = newFilepath;
+                    }
+                }
+                span.addEvent("task.archive.complete", {
+                    "output.taskId": id,
+                    "output.newPath": newFilepath,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return archived;
             }
-        }
-        // Update task
-        const archived = {
-            ...task,
-            source: "completed",
-            filePath: newFilepath,
-        };
-        // Write to new location
-        const content = serializeTaskMarkdown(archived);
-        await this.fs.writeFile(newFilepath, content);
-        // Update in-memory cache
-        this.tasks.set(id, archived);
-        // Update task index if lazy initialized
-        if (this.lazyInitialized) {
-            const entry = this.taskIndex.get(id);
-            if (entry) {
-                entry.source = "completed";
-                entry.filePath = newFilepath;
+            catch (error) {
+                span.addEvent("task.archive.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.taskId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
             }
-        }
-        return archived;
+        });
     }
     /**
      * Restore a task (move from completed/ to tasks/)
@@ -1145,53 +1496,96 @@ export class Core {
      */
     async restoreTask(id) {
         this.ensureInitialized();
-        const task = this.tasks.get(id);
-        if (!task) {
-            return null;
-        }
-        // Check if in completed
-        if (task.source !== "completed") {
-            return null;
-        }
-        const tasksDir = this.getTasksDir();
-        // Ensure tasks directory exists
-        await this.fs.createDir(tasksDir, { recursive: true });
-        // Build new filepath in tasks/
-        const safeTitle = task.title
-            .replace(/[<>:"/\\|?*]/g, "")
-            .replace(/\s+/g, " ")
-            .slice(0, 50);
-        const filename = `${id} - ${safeTitle}.md`;
-        const newFilepath = this.fs.join(tasksDir, filename);
-        // Delete old file
-        if (task.filePath) {
+        const startTime = Date.now();
+        const span = this.tracer.startSpan("task.restore", {
+            attributes: { "input.taskId": id },
+        });
+        return await context.with(trace.setSpan(context.active(), span), async () => {
             try {
-                await this.fs.deleteFile(task.filePath);
-            }
-            catch {
-                // File may not exist
+                span.addEvent("task.restore.started", { "input.taskId": id });
+                const task = this.tasks.get(id);
+                if (!task) {
+                    span.addEvent("task.restore.error", {
+                        "error.type": "NotFoundError",
+                        "error.message": "Task not found",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK }); // Not found is not an error
+                    span.end();
+                    return null;
+                }
+                // Check if in completed
+                if (task.source !== "completed") {
+                    span.addEvent("task.restore.error", {
+                        "error.type": "InvalidStateError",
+                        "error.message": "Task not in completed",
+                        "input.taskId": id,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return null;
+                }
+                const tasksDir = this.getTasksDir();
+                // Ensure tasks directory exists
+                await this.fs.createDir(tasksDir, { recursive: true });
+                // Build new filepath in tasks/
+                const safeTitle = task.title
+                    .replace(/[<>:"/\\|?*]/g, "")
+                    .replace(/\s+/g, " ")
+                    .slice(0, 50);
+                const filename = `${id} - ${safeTitle}.md`;
+                const newFilepath = this.fs.join(tasksDir, filename);
+                // Delete old file
+                if (task.filePath) {
+                    try {
+                        await this.fs.deleteFile(task.filePath);
+                    }
+                    catch {
+                        // File may not exist
+                    }
+                }
+                // Update task
+                const restored = {
+                    ...task,
+                    source: "local",
+                    filePath: newFilepath,
+                };
+                // Write to new location
+                const content = serializeTaskMarkdown(restored);
+                await this.fs.writeFile(newFilepath, content);
+                // Update in-memory cache
+                this.tasks.set(id, restored);
+                // Update task index if lazy initialized
+                if (this.lazyInitialized) {
+                    const entry = this.taskIndex.get(id);
+                    if (entry) {
+                        entry.source = "tasks";
+                        entry.filePath = newFilepath;
+                    }
+                }
+                span.addEvent("task.restore.complete", {
+                    "output.taskId": id,
+                    "output.newPath": newFilepath,
+                    "duration.ms": Date.now() - startTime,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return restored;
             }
-        }
-        // Update task
-        const restored = {
-            ...task,
-            source: "local",
-            filePath: newFilepath,
-        };
-        // Write to new location
-        const content = serializeTaskMarkdown(restored);
-        await this.fs.writeFile(newFilepath, content);
-        // Update in-memory cache
-        this.tasks.set(id, restored);
-        // Update task index if lazy initialized
-        if (this.lazyInitialized) {
-            const entry = this.taskIndex.get(id);
-            if (entry) {
-                entry.source = "tasks";
-                entry.filePath = newFilepath;
+            catch (error) {
+                span.addEvent("task.restore.error", {
+                    "error.type": error instanceof Error ? error.name : "UnknownError",
+                    "error.message": error instanceof Error ? error.message : String(error),
+                    "input.taskId": id,
+                });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                throw error;
             }
-        }
-        return restored;
+        });
     }
     /**
      * Load specific tasks by their IDs (for lazy loading milestone tasks)