trekoon 0.1.2 → 0.1.4

package/.agents/skills/trekoon/SKILL.md

@@ -7,9 +7,154 @@ description: Use Trekoon to create issues/tasks, plan backlog and sprints, creat
 
 Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
 
-Use long flags (`--status`, `--description`, etc.) and ALWAYS prefer `--toon` for machine-readable output.
+## CRITICAL: Always Use --toon Flag
+
+**Every trekoon command MUST include `--toon` for machine-readable output.**
+
+The `--toon` flag outputs structured YAML-like data that is easy to parse. Never run trekoon commands without it.
+
+### TOON Output Format
+
+All `--toon` output follows this structure:
+
+```yaml
+ok: true
+command: task.list
+data:
+  tasks[0]:
+    id: abc-123
+    epicId: epic-456
+    title: Implement feature X
+    status: todo
+    createdAt: 1700000000000
+    updatedAt: 1700000000000
+  tasks[1]:
+    id: def-789
+    epicId: epic-456
+    title: Write tests
+    status: in_progress
+    createdAt: 1700000001000
+    updatedAt: 1700000001000
+```
+
+On error:
+
+```yaml
+ok: false
+command: task.show
+data: {}
+error:
+  code: not_found
+  message: task not found: invalid-id
+```
+
+### Key Fields
+
+| Field | Meaning |
+|-------|---------|
+| `ok` | `true` if command succeeded, `false` on error |
+| `command` | The command that was executed (e.g., `task.list`, `epic.create`) |
+| `data` | The response payload (tasks, epics, dependencies, etc.) |
+| `error` | Present only on failure, contains `code` and `message` |
+
+Use long flags (`--status`, `--description`, etc.) and ALWAYS append `--toon` to every command.
+
+## 1) Status Management
+
+### Valid Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `todo` | Work not started (default for new items) |
+| `in_progress` | Actively being worked on |
+| `done` | Completed successfully |
+
+Note: `in-progress` (hyphenated) is equivalent to `in_progress`.
+
+### When to Change Status
+
+| Transition | When to apply |
+|------------|---------------|
+| `todo → in_progress` | When you START working on a task/subtask/epic |
+| `in_progress → done` | When you COMPLETE the work and it is ready |
+
+### Status Change Commands
+
+```bash
+trekoon task update <task-id> --status in_progress --toon
+trekoon task update <task-id> --status done --toon
+trekoon subtask update <subtask-id> --status done --toon
+trekoon epic update <epic-id> --status done --toon
+```
+
+## 2) Dependency Management
+
+Dependencies define what must be completed before a task can start. A task/subtask can depend on other tasks/subtasks.
+
+### Commands
+
+```bash
+trekoon dep add <source-id> <depends-on-id> --toon
+trekoon dep list <source-id> --toon
+trekoon dep remove <source-id> <depends-on-id> --toon
+```
+
+- `<source-id>`: The task/subtask that has the dependency
+- `<depends-on-id>`: The task/subtask that must be completed first
 
-## 1) Load existing work first
+### Checking Dependencies
+
+Before starting any task, always check its dependencies:
+
+```bash
+trekoon dep list <task-id> --toon
+```
+
+The response `data.dependencies` array contains entries with:
+- `sourceId`: the task you're checking
+- `dependsOnId`: what must be done first
+- `dependsOnKind`: "task" or "subtask"
+
+### Dependency Rules
+
+1. A task with dependencies should only be marked `in_progress` when ALL dependencies have status `done`
+2. Dependencies can only exist between tasks and subtasks (not epics)
+3. Cycles are automatically detected and rejected
+
+## 3) Task Completion Flow
+
+### Before Starting a Task
+
+1. Check if task has unmet dependencies:
+   ```bash
+   trekoon dep list <task-id> --toon
+   ```
+
+2. If dependencies exist and are not `done`, complete those first
+
+3. Only mark `in_progress` when all dependencies are `done`
+
+### When Completing a Task
+
+1. Mark the task as done:
+   ```bash
+   trekoon task update <task-id> --status done --toon
+   ```
+
+2. To find the next task that was blocked by this one:
+   - List all tasks: `trekoon task list --all --toon`
+   - Check which tasks have dependencies on the completed task
+   - The task(s) with all dependencies now satisfied are ready to start
+
+### Finding Next Work
+
+```bash
+trekoon task list --status todo --limit 20 --toon
+```
+
+Tasks are sorted with `in_progress` first, then `todo`. Look for tasks with no dependencies or all dependencies satisfied.
+
+## 4) Load existing work first
 
 Before creating or changing anything, inspect current context:
 
@@ -36,7 +181,14 @@ trekoon task list --all --toon
 - `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
 - `task show <id> --all --toon`: task plus its subtasks
 
-## 2) Create work (epic/task/subtask)
+### View Options
+
+| Command | `--view` options |
+|---------|------------------|
+| `list` | `table` (default), `compact` |
+| `show` | `table` (default), `compact`, `tree`, `detail` |
+
+## 5) Create work (epic/task/subtask)
 
 ```bash
 trekoon epic create --title "..." --description "..." --status todo --toon
@@ -47,8 +199,9 @@ trekoon subtask create --task <task-id> --title "..." --description "..." --stat
 Notes:
 - `description` is required for epic/task create and it must be well written.
 - `status` defaults to `todo` if omitted.
+- `description` is optional for subtask create.
 
-## 3) Update work
+## 6) Update work
 
 ### Single-item update
 
@@ -73,7 +226,7 @@ Rules:
 - In bulk mode, do not pass a positional ID.
 - Bulk update supports `--append` and/or `--status`.
 
-## 4) Setup/install/init (if `trekoon` is unavailable)
+## 7) Setup/install/init (if `trekoon` is unavailable)
 
 1. Install Trekoon (or make sure it is on `PATH`).
 2. In the target repository/worktree, initialize tracker state:
@@ -81,11 +234,12 @@ Rules:
 ```bash
 trekoon init
 ```
+
 3. You can always run `trekoon quickstart` or `trekoon --help` to get more information.
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
-## 5) Safety
+## 8) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
 - `trekoon wipe --yes` is prohibited unless the user explicitly confirms they want a destructive wipe.

package/README.md

@@ -89,7 +89,7 @@ List defaults and filters (`epic list`, `task list`):
 - All rows and statuses: `--all`
 - `--all` is mutually exclusive with `--status` and `--limit`
 
-Bulk updates (`epic update`, `task update`):
+Bulk updates (`epic update`, `task update`, `subtask update`):
 
 - Target all rows: `--all`
 - Target specific rows: `--ids <id1,id2,...>`
@@ -103,6 +103,8 @@ Examples:
 ```bash
 trekoon task update --all --status in_progress
 trekoon task update --ids <task-1>,<task-2> --append "\nFollow-up note"
+trekoon subtask update --all --status done
+trekoon subtask update --ids <subtask-1>,<subtask-2> --append "\nFollow-up note"
 trekoon epic update --ids <epic-1>,<epic-2> --status done
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,8 @@
   "scripts": {
     "run": "bun run ./src/index.ts",
     "build": "bun build ./src/index.ts --outdir ./dist --target bun",
-    "test": "bun test ./tests"
+    "test": "bun test ./tests",
+    "lint": "bunx tsc --noEmit"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",

package/src/commands/events.ts

@@ -0,0 +1,88 @@
+import { hasFlag, parseArgs, parseStrictPositiveInt, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { DEFAULT_EVENT_RETENTION_DAYS, pruneEvents } from "../storage/events-retention";
+
+const EVENTS_USAGE = "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "events",
+    human: `${message}\n${EVENTS_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function invalidInput(command: string, message: string, option: string): CliResult {
+  return failResult({
+    command,
+    human: message,
+    data: {
+      option,
+    },
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+export async function runEvents(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing events subcommand.");
+  }
+
+  if (subcommand !== "prune") {
+    return usage(`Unknown events subcommand '${subcommand}'.`);
+  }
+
+  if (parsed.positional.length > 1) {
+    return usage("Unexpected positional arguments for events prune.");
+  }
+
+  const missingOption: string | undefined = readMissingOptionValue(parsed.missingOptionValues, "retention-days");
+  if (missingOption !== undefined) {
+    return invalidInput("events.prune", `Option --${missingOption} requires a value.`, missingOption);
+  }
+
+  const parsedRetentionDays: number | undefined = parseStrictPositiveInt(readOption(parsed.options, "retention-days"));
+  if (Number.isNaN(parsedRetentionDays)) {
+    return invalidInput("events.prune", "--retention-days must be a positive integer.", "retention-days");
+  }
+
+  const retentionDays: number = parsedRetentionDays ?? DEFAULT_EVENT_RETENTION_DAYS;
+  const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
+  const archive: boolean = hasFlag(parsed.flags, "archive");
+  const storage = openTrekoonDatabase(context.cwd);
+
+  try {
+    const summary = pruneEvents(storage.db, {
+      retentionDays,
+      dryRun,
+      archive,
+    });
+
+    return okResult({
+      command: "events.prune",
+      human: [
+        dryRun ? "Dry run complete." : "Prune complete.",
+        `Retention days: ${summary.retentionDays}`,
+        `Candidates: ${summary.candidateCount}`,
+        `Archived: ${summary.archivedCount}`,
+        `Deleted: ${summary.deletedCount}`,
+      ].join("\n"),
+      data: summary,
+    });
+  } finally {
+    storage.close();
+  }
+}

package/src/commands/help.ts

@@ -21,6 +21,8 @@ const ROOT_HELP = [
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
+  "  events       Event retention and cleanup commands",
+  "  migrate      Migration status and rollback commands",
   "  sync         Cross-branch sync commands",
   "  skills       Project-local skill install/link commands",
 ].join("\n");
@@ -33,8 +35,11 @@ const COMMAND_HELP: Record<string, string> = {
     "Usage: trekoon epic <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=epic summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   task:
     "Usage: trekoon task <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=task summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  subtask: "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact)",
+  subtask:
+    "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   dep: "Usage: trekoon dep <subcommand> [options]",
+  events: "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
+  migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   sync: "Usage: trekoon sync <subcommand> [options]",
   skills:
     "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>] (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md)",

package/src/commands/migrate.ts

@@ -0,0 +1,123 @@
+import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { describeMigrations, rollbackDatabase } from "../storage/migrations";
+
+const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "migrate",
+    human: `${message}\n${MIGRATE_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function parseVersion(rawValue: string | undefined): number | null {
+  if (rawValue === undefined) {
+    return null;
+  }
+
+  if (!/^\d+$/.test(rawValue)) {
+    return Number.NaN;
+  }
+
+  return Number.parseInt(rawValue, 10);
+}
+
+export async function runMigrate(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing migrate subcommand.");
+  }
+
+  const missingOption = readMissingOptionValue(parsed.missingOptionValues, "to-version");
+  if (missingOption !== undefined) {
+    return failResult({
+      command: "migrate",
+      human: `Option --${missingOption} requires a value.`,
+      data: {
+        option: missingOption,
+      },
+      error: {
+        code: "invalid_input",
+        message: `Option --${missingOption} requires a value.`,
+      },
+    });
+  }
+
+  const storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
+
+  try {
+    if (subcommand === "status") {
+      const status = describeMigrations(storage.db);
+
+      return okResult({
+        command: "migrate.status",
+        human: [
+          `Current version: ${status.currentVersion}`,
+          `Latest version: ${status.latestVersion}`,
+          `Pending migrations: ${status.pending.length}`,
+        ].join("\n"),
+        data: status,
+      });
+    }
+
+    if (subcommand === "rollback") {
+      const status = describeMigrations(storage.db);
+      const parsedVersion: number | null = parseVersion(readOption(parsed.options, "to-version"));
+
+      if (Number.isNaN(parsedVersion)) {
+        return failResult({
+          command: "migrate.rollback",
+          human: "--to-version must be a non-negative integer.",
+          data: {
+            option: "to-version",
+          },
+          error: {
+            code: "invalid_input",
+            message: "--to-version must be a non-negative integer.",
+          },
+        });
+      }
+
+      const targetVersion: number = parsedVersion ?? Math.max(0, status.currentVersion - 1);
+      const summary = rollbackDatabase(storage.db, targetVersion);
+
+      return okResult({
+        command: "migrate.rollback",
+        human: [
+          `Rolled back ${summary.rolledBack} migration(s).`,
+          `From version ${summary.fromVersion} to ${summary.toVersion}.`,
+        ].join("\n"),
+        data: summary,
+      });
+    }
+
+    return usage(`Unknown migrate subcommand '${subcommand}'.`);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown migration failure.";
+
+    return failResult({
+      command: "migrate",
+      human: message,
+      data: {
+        reason: "migrate_failed",
+      },
+      error: {
+        code: "migrate_failed",
+        message,
+      },
+    });
+  } finally {
+    storage.close();
+  }
+}

package/src/commands/subtask.ts

@@ -1,4 +1,4 @@
-import { parseArgs, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import { hasFlag, parseArgs, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
 
 import { DomainError, type SubtaskRecord } from "../domain/types";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -13,6 +13,21 @@ function formatSubtask(subtask: SubtaskRecord): string {
 
 const VIEW_MODES = ["table", "compact"] as const;
 
+function parseIdsOption(rawIds: string | undefined): string[] {
+  if (rawIds === undefined) {
+    return [];
+  }
+
+  return rawIds
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+function appendLine(existing: string, line: string): string {
+  return existing.length > 0 ? `${existing}\n${line}` : line;
+}
+
 function formatSubtaskListTable(subtasks: readonly SubtaskRecord[]): string {
   return formatHumanTable(
     ["ID", "TASK", "TITLE", "STATUS"],
@@ -138,6 +153,8 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       }
       case "update": {
         const missingUpdateOption =
+          readMissingOptionValue(parsed.missingOptionValues, "ids") ??
+          readMissingOptionValue(parsed.missingOptionValues, "append") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s");
         if (missingUpdateOption !== undefined) {
@@ -145,10 +162,112 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         }
 
         const subtaskId: string = parsed.positional[1] ?? "";
+        const updateAll: boolean = hasFlag(parsed.flags, "all");
+        const rawIds: string | undefined = readOption(parsed.options, "ids");
+        const ids = parseIdsOption(rawIds);
         const title: string | undefined = readOption(parsed.options, "title");
         const description: string | undefined = readOption(parsed.options, "description", "d");
+        const append: string | undefined = readOption(parsed.options, "append");
         const status: string | undefined = readOption(parsed.options, "status", "s");
-        const subtask = domain.updateSubtask(subtaskId, { title, description, status });
+
+        if (updateAll && ids.length > 0) {
+          return failResult({
+            command: "subtask.update",
+            human: "Use either --all or --ids, not both.",
+            data: { code: "invalid_input", target: ["all", "ids"] },
+            error: {
+              code: "invalid_input",
+              message: "--all and --ids are mutually exclusive",
+            },
+          });
+        }
+
+        if (append !== undefined && description !== undefined) {
+          return failResult({
+            command: "subtask.update",
+            human: "Use either --append or --description, not both.",
+            data: { code: "invalid_input", fields: ["append", "description"] },
+            error: {
+              code: "invalid_input",
+              message: "--append and --description are mutually exclusive",
+            },
+          });
+        }
+
+        const hasBulkTarget = updateAll || ids.length > 0;
+        if (hasBulkTarget) {
+          if (subtaskId.length > 0) {
+            return failResult({
+              command: "subtask.update",
+              human: "Do not pass a subtask id when using --all or --ids.",
+              data: { code: "invalid_input", id: subtaskId },
+              error: {
+                code: "invalid_input",
+                message: "Positional id is not allowed with --all/--ids",
+              },
+            });
+          }
+
+          if (title !== undefined || description !== undefined) {
+            return failResult({
+              command: "subtask.update",
+              human: "Bulk update supports only --append and/or --status.",
+              data: { code: "invalid_input" },
+              error: {
+                code: "invalid_input",
+                message: "Bulk update supports only --append and --status",
+              },
+            });
+          }
+
+          if (append === undefined && status === undefined) {
+            return failResult({
+              command: "subtask.update",
+              human: "Bulk update requires --append and/or --status.",
+              data: { code: "invalid_input" },
+              error: {
+                code: "invalid_input",
+                message: "Missing bulk update fields",
+              },
+            });
+          }
+
+          const targets = updateAll ? [...domain.listSubtasks()] : ids.map((id) => domain.getSubtaskOrThrow(id));
+          const subtasks = targets.map((target) =>
+            domain.updateSubtask(target.id, {
+              status,
+              description: append === undefined ? undefined : appendLine(target.description, append),
+            }),
+          );
+
+          return okResult({
+            command: "subtask.update",
+            human: `Updated ${subtasks.length} subtask(s)`,
+            data: {
+              subtasks,
+              target: updateAll ? "all" : "ids",
+              ids: subtasks.map((subtask) => subtask.id),
+            },
+          });
+        }
+
+        if (subtaskId.length === 0) {
+          return failResult({
+            command: "subtask.update",
+            human: "Provide a subtask id, or use --all/--ids for bulk update.",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing subtask id",
+            },
+          });
+        }
+
+        const nextDescription =
+          append === undefined
+            ? description
+            : appendLine(domain.getSubtaskOrThrow(subtaskId).description, append);
+        const subtask = domain.updateSubtask(subtaskId, { title, description: nextDescription, status });
 
         return okResult({
           command: "subtask.update",

package/src/domain/tracker-domain.ts

@@ -522,44 +522,25 @@ export class TrackerDomain {
   }
 
   private wouldCreateCycle(sourceId: string, dependsOnId: string): boolean {
-    const adjacency = new Map<string, string[]>();
-    const rows = this.#db.query("SELECT source_id, depends_on_id FROM dependencies;").all() as Array<{
-      source_id: string;
-      depends_on_id: string;
-    }>;
-
-    for (const row of rows) {
-      const existing = adjacency.get(row.source_id) ?? [];
-      existing.push(row.depends_on_id);
-      adjacency.set(row.source_id, existing);
-    }
-
-    const newEdges = adjacency.get(sourceId) ?? [];
-    newEdges.push(dependsOnId);
-    adjacency.set(sourceId, newEdges);
-
-    const visited = new Set<string>();
-    const queue: string[] = [dependsOnId];
-
-    while (queue.length > 0) {
-      const next = queue.shift();
-      if (!next) {
-        continue;
-      }
-      if (next === sourceId) {
-        return true;
-      }
-      if (visited.has(next)) {
-        continue;
-      }
-      visited.add(next);
-      const outgoing = adjacency.get(next) ?? [];
-      for (const neighbor of outgoing) {
-        queue.push(neighbor);
-      }
-    }
+    const row = this.#db
+      .query(
+        `
+        WITH RECURSIVE reachable(id) AS (
+          SELECT ?
+          UNION
+          SELECT d.depends_on_id
+          FROM dependencies d
+          INNER JOIN reachable r ON d.source_id = r.id
+        )
+        SELECT 1 AS has_cycle
+        FROM reachable
+        WHERE id = ?
+        LIMIT 1;
+        `,
+      )
+      .get(dependsOnId, sourceId) as { has_cycle: number } | null;
 
-    return false;
+    return row !== null;
   }
 }
 

package/src/runtime/cli-shell.ts

@@ -1,7 +1,9 @@
 import { runHelp } from "../commands/help";
 import { runDep } from "../commands/dep";
 import { runEpic } from "../commands/epic";
+import { runEvents } from "../commands/events";
 import { runInit } from "../commands/init";
+import { runMigrate } from "../commands/migrate";
 import { runQuickstart } from "../commands/quickstart";
 import { runSkills } from "../commands/skills";
 import { runSubtask } from "../commands/subtask";
@@ -21,6 +23,8 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "task",
   "subtask",
   "dep",
+  "events",
+  "migrate",
   "sync",
   "skills",
   "wipe",
@@ -147,6 +151,10 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
       return runSubtask(context);
     case "dep":
       return runDep(context);
+    case "events":
+      return runEvents(context);
+    case "migrate":
+      return runMigrate(context);
     case "sync":
       return runSync(context);
     case "skills":

package/src/storage/database.ts

@@ -11,7 +11,14 @@ export interface TrekoonDatabase {
   close(): void;
 }
 
-export function openTrekoonDatabase(workingDirectory: string = process.cwd()): TrekoonDatabase {
+export interface OpenTrekoonDatabaseOptions {
+  readonly autoMigrate?: boolean;
+}
+
+export function openTrekoonDatabase(
+  workingDirectory: string = process.cwd(),
+  options: OpenTrekoonDatabaseOptions = {},
+): TrekoonDatabase {
   const paths: StoragePaths = resolveStoragePaths(workingDirectory);
 
   mkdirSync(paths.storageDir, { recursive: true });
@@ -22,7 +29,9 @@ export function openTrekoonDatabase(workingDirectory: string = process.cwd()): T
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
 
-  migrateDatabase(db);
+  if (options.autoMigrate ?? true) {
+    migrateDatabase(db);
+  }
 
   return {
     db,

package/src/storage/events-retention.ts

@@ -0,0 +1,138 @@
+import { type Database } from "bun:sqlite";
+
+export const DEFAULT_EVENT_RETENTION_DAYS = 90;
+const DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+
+export interface EventPruneOptions {
+  readonly retentionDays?: number;
+  readonly dryRun?: boolean;
+  readonly archive?: boolean;
+  readonly now?: number;
+}
+
+export interface EventPruneSummary {
+  readonly retentionDays: number;
+  readonly cutoffTimestamp: number;
+  readonly dryRun: boolean;
+  readonly archive: boolean;
+  readonly candidateCount: number;
+  readonly archivedCount: number;
+  readonly deletedCount: number;
+}
+
+function ensureArchiveTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS event_archive (
+      id TEXT PRIMARY KEY,
+      entity_kind TEXT NOT NULL,
+      entity_id TEXT NOT NULL,
+      operation TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      git_branch TEXT,
+      git_head TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1
+    );
+  `);
+}
+
+function assertRetentionDays(value: number): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("retentionDays must be a positive integer.");
+  }
+
+  return value;
+}
+
+function countCandidates(db: Database, cutoffTimestamp: number): number {
+  const row = db.query("SELECT COUNT(*) AS count FROM events WHERE created_at < ?;").get(cutoffTimestamp) as
+    | { count: number }
+    | null;
+
+  return row?.count ?? 0;
+}
+
+export function pruneEvents(db: Database, options: EventPruneOptions = {}): EventPruneSummary {
+  const retentionDays: number = assertRetentionDays(options.retentionDays ?? DEFAULT_EVENT_RETENTION_DAYS);
+  const dryRun: boolean = options.dryRun ?? false;
+  const archive: boolean = options.archive ?? false;
+  const now: number = options.now ?? Date.now();
+  const cutoffTimestamp: number = now - retentionDays * DAY_IN_MILLISECONDS;
+  const candidateCount: number = countCandidates(db, cutoffTimestamp);
+
+  if (dryRun || candidateCount === 0) {
+    return {
+      retentionDays,
+      cutoffTimestamp,
+      dryRun,
+      archive,
+      candidateCount,
+      archivedCount: 0,
+      deletedCount: 0,
+    };
+  }
+
+  return db.transaction((): EventPruneSummary => {
+    let archivedCount = 0;
+
+    if (archive) {
+      ensureArchiveTable(db);
+      const archived = db
+        .query(
+          `
+          INSERT INTO event_archive (
+            id,
+            entity_kind,
+            entity_id,
+            operation,
+            payload,
+            git_branch,
+            git_head,
+            created_at,
+            updated_at,
+            version
+          )
+          SELECT
+            id,
+            entity_kind,
+            entity_id,
+            operation,
+            payload,
+            git_branch,
+            git_head,
+            created_at,
+            updated_at,
+            version
+          FROM events
+          WHERE created_at < ?
+          ON CONFLICT(id) DO UPDATE SET
+            entity_kind = excluded.entity_kind,
+            entity_id = excluded.entity_id,
+            operation = excluded.operation,
+            payload = excluded.payload,
+            git_branch = excluded.git_branch,
+            git_head = excluded.git_head,
+            created_at = excluded.created_at,
+            updated_at = excluded.updated_at,
+            version = excluded.version;
+          `,
+        )
+        .run(cutoffTimestamp);
+
+      archivedCount = archived.changes;
+    }
+
+    const deleted = db.query("DELETE FROM events WHERE created_at < ?;").run(cutoffTimestamp);
+
+    return {
+      retentionDays,
+      cutoffTimestamp,
+      dryRun,
+      archive,
+      candidateCount,
+      archivedCount,
+      deletedCount: deleted.changes,
+    };
+  })();
+}

package/src/storage/migrations.ts

@@ -2,10 +2,142 @@ import { Database } from "bun:sqlite";
 
 import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
 
+const BASE_MIGRATION_VERSION = 1;
 const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
+const LEGACY_BASE_MIGRATION_NAME_PATTERNS: readonly string[] = [
+  "0001_base_schema_v*",
+];
 
-function hasMigration(db: Database, name: string): boolean {
-  const migrationTableExists: { count: number } | null = db
+const BASE_ROLLBACK_STATEMENTS: readonly string[] = [
+  "DROP TABLE IF EXISTS sync_conflicts;",
+  "DROP TABLE IF EXISTS sync_cursors;",
+  "DROP TABLE IF EXISTS git_context;",
+  "DROP TABLE IF EXISTS events;",
+  "DROP TABLE IF EXISTS dependencies;",
+  "DROP TABLE IF EXISTS subtasks;",
+  "DROP TABLE IF EXISTS tasks;",
+  "DROP TABLE IF EXISTS epics;",
+];
+
+const INDEX_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at ON events(created_at);",
+  "CREATE INDEX IF NOT EXISTS idx_events_git_branch ON events(git_branch);",
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at_id ON events(created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_depends_on ON dependencies(depends_on_id);",
+];
+
+const INDEX_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_events_created_at;",
+  "DROP INDEX IF EXISTS idx_events_git_branch;",
+  "DROP INDEX IF EXISTS idx_events_created_at_id;",
+  "DROP INDEX IF EXISTS idx_dependencies_source;",
+  "DROP INDEX IF EXISTS idx_dependencies_depends_on;",
+];
+
+const EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  `
+  CREATE TABLE IF NOT EXISTS event_archive (
+    id TEXT PRIMARY KEY,
+    entity_kind TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    git_branch TEXT,
+    git_head TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  "CREATE INDEX IF NOT EXISTS idx_event_archive_created_at ON event_archive(created_at);",
+];
+
+const EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_event_archive_created_at;",
+  "DROP TABLE IF EXISTS event_archive;",
+];
+
+interface Migration {
+  readonly version: number;
+  readonly name: string;
+  up(db: Database): void;
+  down(db: Database): void;
+}
+
+interface AppliedMigrationRow {
+  readonly version: number;
+  readonly name: string;
+  readonly applied_at: number;
+}
+
+export interface AppliedMigration {
+  readonly version: number;
+  readonly name: string;
+  readonly appliedAt: number;
+}
+
+export interface MigrationStatus {
+  readonly currentVersion: number;
+  readonly latestVersion: number;
+  readonly applied: readonly AppliedMigration[];
+  readonly pending: ReadonlyArray<{ version: number; name: string }>;
+}
+
+export interface RollbackSummary {
+  readonly fromVersion: number;
+  readonly toVersion: number;
+  readonly rolledBack: number;
+  readonly rolledBackMigrations: readonly string[];
+}
+
+const MIGRATIONS: readonly Migration[] = [
+  {
+    version: BASE_MIGRATION_VERSION,
+    name: BASE_MIGRATION_NAME,
+    up(db: Database): void {
+      for (const statement of BASE_SCHEMA_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BASE_ROLLBACK_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 2,
+    name: "0002_sync_dependency_indexes",
+    up(db: Database): void {
+      for (const statement of INDEX_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of INDEX_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 3,
+    name: "0003_event_archive_retention",
+    up(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+];
+
+function migrationTableExists(db: Database): boolean {
+  const row = db
     .query(
       `
       SELECT COUNT(*) AS count
@@ -15,32 +147,221 @@ function hasMigration(db: Database, name: string): boolean {
     )
     .get() as { count: number } | null;
 
-  if (!migrationTableExists || migrationTableExists.count === 0) {
-    return false;
+  return (row?.count ?? 0) > 0;
+}
+
+function hasMigrationVersionColumn(db: Database): boolean {
+  const columns = db.query("PRAGMA table_info(schema_migrations);").all() as Array<{ name: string }>;
+  return columns.some((column) => column.name === "version");
+}
+
+function ensureMigrationTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      version INTEGER NOT NULL UNIQUE,
+      name TEXT NOT NULL UNIQUE,
+      applied_at INTEGER NOT NULL
+    );
+  `);
+}
+
+function ensureMigrationVersionColumn(db: Database): void {
+  if (!migrationTableExists(db) || hasMigrationVersionColumn(db)) {
+    return;
+  }
+
+  db.exec("ALTER TABLE schema_migrations ADD COLUMN version INTEGER;");
+  db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name = ?;").run(BASE_MIGRATION_VERSION, BASE_MIGRATION_NAME);
+
+  for (const legacyPattern of LEGACY_BASE_MIGRATION_NAME_PATTERNS) {
+    db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name GLOB ?;").run(
+      BASE_MIGRATION_VERSION,
+      legacyPattern,
+    );
+  }
+
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_schema_migrations_version ON schema_migrations(version);");
+
+  const unresolvedRow = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM schema_migrations
+      WHERE version IS NULL;
+      `,
+    )
+    .get() as { count: number } | null;
+
+  if ((unresolvedRow?.count ?? 0) > 0) {
+    throw new Error(
+      "Unable to infer one or more schema_migrations.version values during legacy upgrade. Repair schema_migrations entries manually so every row has a valid version, then rerun migrations.",
+    );
+  }
+}
+
+function validateMigrationPlan(): void {
+  const seen = new Set<number>();
+
+  for (let index = 0; index < MIGRATIONS.length; index += 1) {
+    const migration: Migration = MIGRATIONS[index]!;
+
+    if (migration.version !== index + 1) {
+      throw new Error(`Migration versions must be contiguous from 1 (found ${migration.version} at index ${index}).`);
+    }
+
+    if (seen.has(migration.version)) {
+      throw new Error(`Duplicate migration version ${migration.version}.`);
+    }
+
+    seen.add(migration.version);
+  }
+}
+
+function runExclusive<T>(db: Database, operation: () => T): T {
+  db.exec("BEGIN EXCLUSIVE TRANSACTION;");
+
+  try {
+    const result: T = operation();
+    db.exec("COMMIT;");
+    return result;
+  } catch (error: unknown) {
+    db.exec("ROLLBACK;");
+    throw error;
+  }
+}
+
+function currentVersion(db: Database): number {
+  if (!migrationTableExists(db)) {
+    return 0;
   }
 
-  const row: { count: number } | null = db
-    .query("SELECT COUNT(*) AS count FROM schema_migrations WHERE name = ?;")
-    .get(name) as { count: number } | null;
+  const row = db
+    .query("SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations;")
+    .get() as { version: number } | null;
 
-  return Boolean(row && row.count > 0);
+  return row?.version ?? 0;
+}
+
+function listAppliedMigrations(db: Database): AppliedMigrationRow[] {
+  if (!migrationTableExists(db)) {
+    return [];
+  }
+
+  return db
+    .query(
+      `
+      SELECT version, name, applied_at
+      FROM schema_migrations
+      WHERE version IS NOT NULL
+      ORDER BY version ASC;
+      `,
+    )
+    .all() as AppliedMigrationRow[];
+}
+
+function migrationForVersion(version: number): Migration {
+  const found = MIGRATIONS.find((migration) => migration.version === version);
+
+  if (!found) {
+    throw new Error(`No migration definition found for version ${version}.`);
+  }
+
+  return found;
+}
+
+function recordMigration(db: Database, migration: Migration): void {
+  db.query("INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?);").run(
+    migration.version,
+    migration.name,
+    Date.now(),
+  );
 }
 
 export function migrateDatabase(db: Database): void {
-  if (hasMigration(db, BASE_MIGRATION_NAME)) {
-    return;
+  runExclusive(db, (): void => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
+
+    const version: number = currentVersion(db);
+
+    for (const migration of MIGRATIONS) {
+      if (migration.version <= version) {
+        continue;
+      }
+
+      migration.up(db);
+      recordMigration(db, migration);
+    }
+  });
+}
+
+export function describeMigrations(db: Database): MigrationStatus {
+  ensureMigrationTable(db);
+  ensureMigrationVersionColumn(db);
+  validateMigrationPlan();
+
+  const appliedRows: AppliedMigrationRow[] = listAppliedMigrations(db);
+  const latestVersion: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+  const activeVersion: number = appliedRows[appliedRows.length - 1]?.version ?? 0;
+  const appliedVersions = new Set(appliedRows.map((row) => row.version));
+
+  return {
+    currentVersion: activeVersion,
+    latestVersion,
+    applied: appliedRows.map((row) => ({
+      version: row.version,
+      name: row.name,
+      appliedAt: row.applied_at,
+    })),
+    pending: MIGRATIONS.filter((migration) => !appliedVersions.has(migration.version)).map((migration) => ({
+      version: migration.version,
+      name: migration.name,
+    })),
+  };
+}
+
+export function rollbackDatabase(db: Database, targetVersion: number): RollbackSummary {
+  if (!Number.isInteger(targetVersion) || targetVersion < 0) {
+    throw new Error("Rollback target version must be a non-negative integer.");
   }
 
-  const now: number = Date.now();
+  return runExclusive(db, (): RollbackSummary => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
 
-  db.transaction((): void => {
-    for (const statement of BASE_SCHEMA_STATEMENTS) {
-      db.exec(statement);
+    const fromVersion: number = currentVersion(db);
+    if (targetVersion > fromVersion) {
+      throw new Error(`Cannot roll back to version ${targetVersion}; current version is ${fromVersion}.`);
     }
 
-    db.query("INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?);").run(
-      BASE_MIGRATION_NAME,
-      now,
-    );
-  })();
+    const appliedDescending = db
+      .query(
+        `
+        SELECT version, name, applied_at
+        FROM schema_migrations
+        WHERE version IS NOT NULL AND version > ?
+        ORDER BY version DESC;
+        `,
+      )
+      .all(targetVersion) as AppliedMigrationRow[];
+
+    const rolledBackMigrations: string[] = [];
+
+    for (const row of appliedDescending) {
+      const migration: Migration = migrationForVersion(row.version);
+      migration.down(db);
+      db.query("DELETE FROM schema_migrations WHERE version = ?;").run(row.version);
+      rolledBackMigrations.push(migration.name);
+    }
+
+    return {
+      fromVersion,
+      toVersion: targetVersion,
+      rolledBack: appliedDescending.length,
+      rolledBackMigrations,
+    };
+  });
 }

package/src/storage/schema.ts

@@ -5,6 +5,7 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `
   CREATE TABLE IF NOT EXISTS schema_migrations (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
+    version INTEGER NOT NULL UNIQUE,
     name TEXT NOT NULL UNIQUE,
     applied_at INTEGER NOT NULL
   );

package/src/storage/types.ts

@@ -6,6 +6,7 @@ export interface MutableRow {
 
 export interface MigrationRecord {
   readonly id: number;
+  readonly version: number;
   readonly name: string;
   readonly applied_at: number;
 }

package/src/sync/service.ts

@@ -41,11 +41,19 @@ interface EventPayload {
   readonly fields?: Record<string, unknown>;
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function parsePayload(rawPayload: string): EventPayload {
   try {
     const parsed: unknown = JSON.parse(rawPayload);
 
-    if (typeof parsed === "object" && parsed !== null) {
+    if (isObjectRecord(parsed)) {
+      if ("fields" in parsed && !isObjectRecord(parsed.fields)) {
+        return {};
+      }
+
       return parsed as EventPayload;
     }
   } catch {