@cleocode/core 2026.3.43 → 2026.3.45

package/src/skills/precedence-types.ts

@@ -1,6 +1,14 @@
 /**
  * Skills Precedence Types - Phase 3B of T5238
- * Re-exports CAAMP precedence types and adds CLEO-specific wrapper types.
+ *
+ * Re-exports CAAMP precedence types and adds CLEO-specific wrapper types
+ * for skill path resolution and installation context.
+ *
+ * These types complement the skill types in `./types.ts`:
+ * - `./types.ts` defines the CLEO skill domain model (Skill, SkillFrontmatter, etc.)
+ * - This file defines CAAMP precedence integration types used when resolving
+ *   which skill version takes priority across providers and scopes.
+ *
  * @task T5238
  */
 
@@ -21,23 +29,38 @@ export {
 
 import type { SkillsPrecedence } from '@cleocode/caamp';
 
+/** Configuration for skill precedence resolution across providers. */
 export interface SkillsPrecedenceConfig {
+  /** Default precedence mode when no provider-specific override exists. */
   defaultPrecedence?: SkillsPrecedence;
+  /** Per-provider precedence overrides (provider ID -> precedence). */
   providerOverrides?: Record<string, SkillsPrecedence>;
 }
 
+/** A resolved skill path with full provenance metadata. */
 export interface ResolvedSkillPath {
+  /** Absolute filesystem path to the skill directory. */
   path: string;
+  /** Where the skill was sourced from. */
   source: 'vendor' | 'agents' | 'marketplace';
+  /** Whether this is a global or project-scoped skill. */
   scope: 'global' | 'project';
+  /** The precedence mode that selected this path. */
   precedence: SkillsPrecedence;
+  /** The provider that owns this skill path. */
   providerId: string;
 }
 
+/** Context for a skill installation operation. */
 export interface SkillInstallationContext {
+  /** Name of the skill being installed. */
   skillName: string;
+  /** Source URL or path to install from. */
   source: string;
+  /** Provider IDs to install the skill for. */
   targetProviders: string[];
+  /** Precedence mode for the installation. */
   precedenceMode?: SkillsPrecedence;
+  /** Project root for project-scoped installations. */
   projectRoot?: string;
 }

package/src/skills/types.ts

@@ -1,13 +1,46 @@
 /**
  * Type definitions for the skills system.
- * Re-exports overlapping CAAMP types for downstream consumers.
+ *
+ * ## Dual Type System: CAAMP vs CLEO Skills
+ *
+ * The skill type system has two layers reflecting the CAAMP/CLEO split:
+ *
+ * ### CAAMP types (re-exported as `CaampSkillMetadata`, `CtSkillEntry`, etc.)
+ * - Defined in `@cleocode/caamp` -- the cross-agent skill standard.
+ * - **`CaampSkillMetadata`**: Minimal metadata parsed from SKILL.md YAML header
+ *   by CAAMP's `parseSkillFile()`. Contains: name, description, version, license,
+ *   compatibility, metadata, allowedTools.
+ * - **`CtSkillEntry`**: A discovered skill with location + metadata. Used by CAAMP's
+ *   discovery and install pipeline.
+ * - Use CAAMP types when interacting with CAAMP APIs (skill discovery, install,
+ *   provider lock files, skill precedence resolution).
+ *
+ * ### CLEO types (`Skill`, `SkillFrontmatter`, `SkillSummary`, `SkillManifest`)
+ * - Defined here -- CLEO's extended skill domain model.
+ * - **`SkillFrontmatter`**: Superset of CaampSkillMetadata. Adds CLEO-specific
+ *   fields: tags, triggers, dispatchPriority, model, invocable, command, protocol.
+ *   Parsed by CLEO's own SKILL.md reader with richer YAML support.
+ * - **`Skill`**: Full in-memory skill object with filesystem paths and parsed content.
+ * - **`SkillSummary`**: Lightweight projection for listings (cached in SkillManifest).
+ * - Use CLEO types for skill dispatch, orchestration, CLI display, and manifest caching.
+ *
+ * ### Relationship
+ * - `SkillFrontmatter` is a functional superset of `CaampSkillMetadata`:
+ *   every field in CaampSkillMetadata exists in SkillFrontmatter (name, description,
+ *   version, allowedTools). SkillFrontmatter adds CLEO-specific extension fields.
+ * - A `Skill` (CLEO) wraps a `SkillFrontmatter` with filesystem context, whereas
+ *   a `CtSkillEntry` (CAAMP) wraps a `CaampSkillMetadata` with install metadata.
+ * - When converting between layers, map `CaampSkillMetadata` -> `SkillFrontmatter`
+ *   (all CAAMP fields carry over; CLEO-specific fields default to undefined).
+ *
  * @epic T4454
  * @task T4516
  */
 
 import type { TaskRef, TaskRefPriority } from '@cleocode/contracts';
 
-// Re-export CAAMP types where they overlap with CLEO's domain
+// Re-export CAAMP types where they overlap with CLEO's domain.
+// See module JSDoc above for guidance on which type to use where.
 export type {
   CtDispatchMatrix,
   CtManifest,
@@ -25,23 +58,52 @@ export type {
 // Skill Types
 // ============================================================================
 
-/** Skill frontmatter parsed from SKILL.md YAML header. */
+/**
+ * Skill frontmatter parsed from SKILL.md YAML header.
+ *
+ * This is CLEO's extended skill metadata -- a functional superset of CAAMP's
+ * `SkillMetadata`. All fields from `CaampSkillMetadata` (name, description,
+ * version, allowedTools) are present here. CLEO adds: tags, triggers,
+ * dispatchPriority, model, invocable, command, protocol.
+ *
+ * Use this type when working with CLEO's skill loading, dispatch, and
+ * orchestration systems. Use `CaampSkillMetadata` when interfacing directly
+ * with CAAMP's discovery/install APIs.
+ */
 export interface SkillFrontmatter {
+  /** Skill name (lowercase, hyphens). Maps to CaampSkillMetadata.name. */
   name: string;
+  /** Human-readable description. Maps to CaampSkillMetadata.description. */
   description: string;
+  /** Semantic version string. Maps to CaampSkillMetadata.version. */
   version?: string;
+  /** Skill author (CLEO extension). */
   author?: string;
+  /** Classification tags for search/filter (CLEO extension). */
   tags?: string[];
+  /** Trigger patterns for auto-dispatch (CLEO extension). */
   triggers?: string[];
+  /** Priority for dispatch selection (CLEO extension). */
   dispatchPriority?: number;
+  /** Preferred LLM model (CLEO extension). */
   model?: string;
+  /** Allowed tool names. Maps to CaampSkillMetadata.allowedTools. */
   allowedTools?: string[];
+  /** Whether the skill can be invoked directly (CLEO extension). */
   invocable?: boolean;
+  /** CLI command for direct invocation (CLEO extension). */
   command?: string;
+  /** RCASD-IVTR+C protocol type (CLEO extension). */
   protocol?: SkillProtocolType;
 }
 
-/** Skill definition loaded from disk. */
+/**
+ * Skill definition loaded from disk.
+ *
+ * CLEO-specific type that wraps a {@link SkillFrontmatter} with filesystem
+ * context. For CAAMP's equivalent, see `CtSkillEntry` which wraps
+ * `CaampSkillMetadata` with install/discovery metadata instead.
+ */
 export interface Skill {
   name: string;
   dirName: string;
@@ -51,7 +113,12 @@ export interface Skill {
   content?: string;
 }
 
-/** Lightweight skill summary for manifest/listing. */
+/**
+ * Lightweight skill summary for manifest/listing.
+ *
+ * Projected from {@link Skill} for efficient caching in {@link SkillManifest}.
+ * Contains only the fields needed for CLI display and dispatch selection.
+ */
 export interface SkillSummary {
   name: string;
   dirName: string;

package/src/store/__tests__/test-db-helper.d.ts

@@ -7,7 +7,7 @@
  *
  * @task T5244
  */
-import type { Task, TaskFile } from '@cleocode/contracts';
+import type { Task } from '@cleocode/contracts';
 import type { DataAccessor } from '../data-accessor.js';
 /** Result of creating a test database environment. */
 export interface TestDbEnv {
@@ -32,16 +32,16 @@ export interface TestDbEnv {
  */
 export declare function createTestDb(): Promise<TestDbEnv>;
 /**
- * Build a TaskFile structure from a list of task partials.
+ * Build full Task objects from a list of task partials.
  * Useful for seeding test data via accessor.upsertSingleTask().
  */
-export declare function makeTaskFile(
+export declare function makeTasks(
   tasks: Array<
     Partial<Task> & {
       id: string;
     }
   >,
-): TaskFile;
+): Task[];
 /**
  * Seed tasks into the test database via the accessor.
  *

package/src/store/__tests__/test-db-helper.js

@@ -40,11 +40,11 @@ export async function createTestDb() {
     };
 }
 /**
- * Build a TaskFile structure from a list of task partials.
+ * Build full Task objects from a list of task partials.
  * Useful for seeding test data via accessor.upsertSingleTask().
  */
-export function makeTaskFile(tasks) {
-    const fullTasks = tasks.map((t) => ({
+export function makeTasks(tasks) {
+    return tasks.map((t) => ({
         title: t.title ?? `Task ${t.id}`,
         description: t.description ?? undefined,
         status: t.status ?? 'pending',
@@ -52,17 +52,6 @@ export function makeTaskFile(tasks) {
         createdAt: t.createdAt ?? new Date().toISOString(),
         ...t,
     }));
-    return {
-        version: '2.10.0',
-        project: { name: 'test', phases: {} },
-        lastUpdated: new Date().toISOString(),
-        _meta: {
-            schemaVersion: '2.10.0',
-            checksum: '0000000000000000',
-            configVersion: '1.0.0',
-        },
-        tasks: fullTasks,
-    };
 }
 /**
  * Seed tasks into the test database via the accessor.
@@ -79,8 +68,8 @@ export async function seedTasks(accessor, tasks) {
         return;
     }
     // Build full Task objects from partials
-    const tf = makeTaskFile(tasks);
-    const fullTasks = tf.tasks;
+    const fullTasks = makeTasks(tasks);
+    
     // Pass 1: Upsert all tasks without dependencies so FK targets exist
     for (const task of fullTasks) {
         await accessor.upsertSingleTask({ ...task, depends: undefined });

package/src/store/__tests__/test-db-helper.ts

@@ -11,7 +11,7 @@
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import type { Task, TaskFile } from '@cleocode/contracts';
+import type { Task } from '@cleocode/contracts';
 import type { DataAccessor } from '../data-accessor.js';
 import { resetDbState } from '../sqlite.js';
 import { createSqliteDataAccessor } from '../sqlite-data-accessor.js';
@@ -59,11 +59,11 @@ export async function createTestDb(): Promise<TestDbEnv> {
 }
 
 /**
- * Build a TaskFile structure from a list of task partials.
+ * Build full Task objects from a list of task partials.
  * Useful for seeding test data via accessor.upsertSingleTask().
  */
-export function makeTaskFile(tasks: Array<Partial<Task> & { id: string }>): TaskFile {
-  const fullTasks: Task[] = tasks.map(
+export function makeTasks(tasks: Array<Partial<Task> & { id: string }>): Task[] {
+  return tasks.map(
     (t) =>
       ({
         title: t.title ?? `Task ${t.id}`,
@@ -74,18 +74,6 @@ export function makeTaskFile(tasks: Array<Partial<Task> & { id: string }>): Task
         ...t,
       }) as Task,
   );
-
-  return {
-    version: '2.10.0',
-    project: { name: 'test', phases: {} },
-    lastUpdated: new Date().toISOString(),
-    _meta: {
-      schemaVersion: '2.10.0',
-      checksum: '0000000000000000',
-      configVersion: '1.0.0',
-    },
-    tasks: fullTasks,
-  };
 }
 
 /**
@@ -108,8 +96,7 @@ export async function seedTasks(
   }
 
   // Build full Task objects from partials
-  const tf = makeTaskFile(tasks);
-  const fullTasks = tf.tasks;
+  const fullTasks = makeTasks(tasks);
 
   // Pass 1: Upsert all tasks without dependencies so FK targets exist
   for (const task of fullTasks) {

package/src/store/brain-sqlite.ts

@@ -50,13 +50,17 @@ export function getBrainDbPath(cwd?: string): string {
 
 /**
  * Resolve the path to the drizzle-brain migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-brain
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-brain
  */
 export function resolveBrainMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-brain');
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-brain');
 }
 
 /**

package/src/store/chain-schema.ts

@@ -46,7 +46,7 @@ export const warpChainInstances = sqliteTable(
     id: text('id').primaryKey(),
     chainId: text('chain_id')
       .notNull()
-      .references(() => warpChains.id),
+      .references(() => warpChains.id, { onDelete: 'cascade' }),
     epicId: text('epic_id').notNull(),
     variables: text('variables'), // JSON
     stageToTask: text('stage_to_task'), // JSON

package/src/store/export.ts

@@ -7,7 +7,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import type { Task, TaskFile } from '@cleocode/contracts';
+import type { Task } from '@cleocode/contracts';
 
 /** Export format version. */
 const EXPORT_FORMAT_VERSION = '1.0.0';
@@ -137,17 +137,17 @@ export function buildRelationshipGraph(tasks: Task[]): RelationshipGraph {
  */
 export function buildExportPackage(
   tasks: Task[],
-  taskData: TaskFile,
   options: {
     mode: string;
     rootTaskIds: string[];
     includeChildren: boolean;
     cleoVersion?: string;
     filters?: unknown;
+    projectName?: string;
   },
 ): ExportPackage {
   const now = new Date().toISOString();
-  const projectName = taskData.project?.name ?? 'unknown';
+  const projectName = options.projectName ?? 'unknown';
   const maxId = tasks.reduce((max, t) => {
     const num = parseInt(t.id.replace('T', ''), 10);
     return num > max ? num : max;
@@ -188,41 +188,51 @@ export function buildExportPackage(
 /**
  * Export a single task.
  */
-export function exportSingle(taskId: string, taskData: TaskFile): ExportPackage | null {
-  const task = taskData.tasks.find((t) => t.id === taskId);
+export function exportSingle(
+  taskId: string,
+  allTasks: Task[],
+  projectName?: string,
+): ExportPackage | null {
+  const task = allTasks.find((t) => t.id === taskId);
   if (!task) return null;
 
-  return buildExportPackage([task], taskData, {
+  return buildExportPackage([task], {
     mode: 'single',
     rootTaskIds: [taskId],
     includeChildren: false,
+    projectName,
   });
 }
 
 /**
  * Export a subtree (task + all descendants).
  */
-export function exportSubtree(rootId: string, taskData: TaskFile): ExportPackage | null {
-  const root = taskData.tasks.find((t) => t.id === rootId);
+export function exportSubtree(
+  rootId: string,
+  allTasks: Task[],
+  projectName?: string,
+): ExportPackage | null {
+  const root = allTasks.find((t) => t.id === rootId);
   if (!root) return null;
 
-  // Collect all descendants
+  // Collect all descendants via BFS
   const collected = new Map<string, Task>();
   const queue = [rootId];
 
   while (queue.length > 0) {
     const id = queue.shift()!;
-    const task = taskData.tasks.find((t) => t.id === id);
+    const task = allTasks.find((t) => t.id === id);
     if (!task || collected.has(id)) continue;
     collected.set(id, task);
-    const children = taskData.tasks.filter((t) => t.parentId === id);
+    const children = allTasks.filter((t) => t.parentId === id);
     queue.push(...children.map((c) => c.id));
   }
 
   const tasks = [...collected.values()];
-  return buildExportPackage(tasks, taskData, {
+  return buildExportPackage(tasks, {
     mode: 'subtree',
     rootTaskIds: [rootId],
     includeChildren: true,
+    projectName,
   });
 }

package/src/store/nexus-sqlite.ts

@@ -46,13 +46,17 @@ export function getNexusDbPath(): string {
 
 /**
  * Resolve the path to the drizzle-nexus migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-nexus
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-nexus
  */
 export function resolveNexusMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-nexus');
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-nexus');
 }
 
 /**

package/src/store/sqlite.ts

@@ -357,13 +357,19 @@ export async function getDb(cwd?: string): Promise<NodeSQLiteDatabase<typeof sch
 
 /**
  * Resolve the path to the drizzle migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-tasks
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-tasks
  */
 export function resolveMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-tasks');
+  // When esbuild bundles into dist/index.js, __dirname is dist/ (1 level deep).
+  // When running from source via tsx, __dirname is src/store/ (2 levels deep).
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-tasks');
 }
 
 /**

package/src/store/tasks-schema.ts

@@ -16,6 +16,7 @@ import {
   primaryKey,
   sqliteTable,
   text,
+  unique,
 } from 'drizzle-orm/sqlite-core';
 import {
   ADR_STATUSES,
@@ -27,6 +28,22 @@ import {
   TASK_STATUSES,
 } from './status-registry.js';
 
+export type {
+  AgentErrorLogRow,
+  AgentErrorType,
+  AgentInstanceRow,
+  AgentInstanceStatus,
+  AgentType,
+  NewAgentErrorLogRow,
+  NewAgentInstanceRow,
+} from '../agents/agent-schema.js';
+// Re-export agent schema tables so drizzle-kit picks them up for migrations.
+export {
+  AGENT_INSTANCE_STATUSES,
+  AGENT_TYPES,
+  agentErrorLog,
+  agentInstances,
+} from '../agents/agent-schema.js';
 export type {
   NewWarpChainInstanceRow,
   NewWarpChainRow,
@@ -95,6 +112,26 @@ export const TOKEN_USAGE_CONFIDENCE = ['real', 'high', 'estimated', 'coarse'] as
 /** Transport types for token telemetry. */
 export const TOKEN_USAGE_TRANSPORTS = ['cli', 'mcp', 'api', 'agent', 'unknown'] as const;
 
+/** Task relation types matching DB CHECK constraint on task_relations.relation_type. */
+export const TASK_RELATION_TYPES = [
+  'related',
+  'blocks',
+  'duplicates',
+  'absorbs',
+  'fixes',
+  'extends',
+  'supersedes',
+] as const;
+
+/** Lifecycle transition types matching DB CHECK constraint on lifecycle_transitions.transition_type. */
+export const LIFECYCLE_TRANSITION_TYPES = ['automatic', 'manual', 'forced'] as const;
+
+/** External task link types matching DB constraint on external_task_links.link_type. */
+export const EXTERNAL_LINK_TYPES = ['created', 'matched', 'manual', 'transferred'] as const;
+
+/** Sync direction types matching DB constraint on external_task_links.sync_direction. */
+export const SYNC_DIRECTIONS = ['inbound', 'outbound', 'bidirectional'] as const;
+
 // === TASKS TABLE ===
 
 export const tasks = sqliteTable(
@@ -160,6 +197,7 @@ export const tasks = sqliteTable(
     index('idx_tasks_phase').on(table.phase),
     index('idx_tasks_type').on(table.type),
     index('idx_tasks_priority').on(table.priority),
+    index('idx_tasks_session_id').on(table.sessionId),
   ],
 );
 
@@ -193,13 +231,16 @@ export const taskRelations = sqliteTable(
       .notNull()
       .references(() => tasks.id, { onDelete: 'cascade' }),
     relationType: text('relation_type', {
-      enum: ['related', 'blocks', 'duplicates', 'absorbs', 'fixes', 'extends', 'supersedes'],
+      enum: TASK_RELATION_TYPES,
     })
       .notNull()
       .default('related'),
     reason: text('reason'),
   },
-  (table) => [primaryKey({ columns: [table.taskId, table.relatedTo] })],
+  (table) => [
+    primaryKey({ columns: [table.taskId, table.relatedTo] }),
+    index('idx_task_relations_related_to').on(table.relatedTo),
+  ],
 );
 
 // === SESSIONS ===
@@ -225,8 +266,12 @@ export const sessions = sqliteTable(
     startedAt: text('started_at').notNull().default(sql`(datetime('now'))`),
     endedAt: text('ended_at'),
     // Session chain columns (T4959)
-    previousSessionId: text('previous_session_id'),
-    nextSessionId: text('next_session_id'),
+    previousSessionId: text('previous_session_id').references((): AnySQLiteColumn => sessions.id, {
+      onDelete: 'set null',
+    }),
+    nextSessionId: text('next_session_id').references((): AnySQLiteColumn => sessions.id, {
+      onDelete: 'set null',
+    }),
     agentIdentifier: text('agent_identifier'),
     handoffConsumedAt: text('handoff_consumed_at'),
     handoffConsumedBy: text('handoff_consumed_by'),
@@ -242,6 +287,7 @@ export const sessions = sqliteTable(
     index('idx_sessions_status').on(table.status),
     index('idx_sessions_previous').on(table.previousSessionId),
     index('idx_sessions_agent_identifier').on(table.agentIdentifier),
+    index('idx_sessions_started_at').on(table.startedAt),
   ],
 );
 
@@ -325,6 +371,7 @@ export const lifecycleStages = sqliteTable(
     index('idx_lifecycle_stages_pipeline_id').on(table.pipelineId),
     index('idx_lifecycle_stages_stage_name').on(table.stageName),
     index('idx_lifecycle_stages_status').on(table.status),
+    index('idx_lifecycle_stages_validated_by').on(table.validatedBy),
   ],
 );
 
@@ -381,7 +428,7 @@ export const lifecycleTransitions = sqliteTable(
     fromStageId: text('from_stage_id').notNull(),
     toStageId: text('to_stage_id').notNull(),
     transitionType: text('transition_type', {
-      enum: ['automatic', 'manual', 'forced'],
+      enum: LIFECYCLE_TRANSITION_TYPES,
     })
       .notNull()
       .default('automatic'),
@@ -524,6 +571,7 @@ export const auditLog = sqliteTable(
     index('idx_audit_log_domain').on(table.domain),
     index('idx_audit_log_request_id').on(table.requestId),
     index('idx_audit_log_project_hash').on(table.projectHash),
+    index('idx_audit_log_actor').on(table.actor),
   ],
 );
 
@@ -567,6 +615,7 @@ export const tokenUsage = sqliteTable(
     index('idx_token_usage_transport').on(table.transport),
     index('idx_token_usage_domain_operation').on(table.domain, table.operation),
     index('idx_token_usage_method').on(table.method),
+    index('idx_token_usage_gateway').on(table.gateway),
   ],
 );
 
@@ -603,7 +652,10 @@ export const architectureDecisions = sqliteTable(
     keywords: text('keywords'),
     topics: text('topics'),
   },
-  (table) => [index('idx_arch_decisions_status').on(table.status)],
+  (table) => [
+    index('idx_arch_decisions_status').on(table.status),
+    index('idx_arch_decisions_amends_id').on(table.amendsId),
+  ],
 );
 
 // === ADR JUNCTION TABLES (ADR-017 §5.3) ===
@@ -673,11 +725,11 @@ export const externalTaskLinks = sqliteTable(
     externalTitle: text('external_title'),
     /** How this link was established. */
     linkType: text('link_type', {
-      enum: ['created', 'matched', 'manual'],
+      enum: EXTERNAL_LINK_TYPES,
     }).notNull(),
     /** Direction of the sync that created this link. */
     syncDirection: text('sync_direction', {
-      enum: ['inbound', 'outbound', 'bidirectional'],
+      enum: SYNC_DIRECTIONS,
     })
       .notNull()
       .default('inbound'),
@@ -692,6 +744,11 @@ export const externalTaskLinks = sqliteTable(
     index('idx_ext_links_task_id').on(table.taskId),
     index('idx_ext_links_provider_external').on(table.providerId, table.externalId),
     index('idx_ext_links_provider_id').on(table.providerId),
+    unique('uq_ext_links_task_provider_external').on(
+      table.taskId,
+      table.providerId,
+      table.externalId,
+    ),
   ],
 );
 

package/src/store/typed-query.ts

@@ -0,0 +1,17 @@
+import type { SQLInputValue, StatementSync } from 'node:sqlite';
+
+/**
+ * Type-safe wrapper for {@link StatementSync.all} — centralizes the
+ * `as unknown as` cast required by node:sqlite's untyped return type.
+ */
+export function typedAll<T>(stmt: StatementSync, ...params: SQLInputValue[]): T[] {
+  return stmt.all(...params) as unknown as T[];
+}
+
+/**
+ * Type-safe wrapper for {@link StatementSync.get} — centralizes the
+ * `as unknown as` cast required by node:sqlite's untyped return type.
+ */
+export function typedGet<T>(stmt: StatementSync, ...params: SQLInputValue[]): T | undefined {
+  return stmt.get(...params) as unknown as T | undefined;
+}