@cleocode/core 2026.3.43 → 2026.3.45

package/src/nexus/transfer.ts

@@ -0,0 +1,314 @@
+/**
+ * Cross-project task transfer engine for NEXUS.
+ *
+ * Provides executeTransfer() and previewTransfer() for moving/copying
+ * tasks between registered NEXUS projects with full provenance tracking.
+ *
+ * @task T046, T049, T050, T051, T052, T053
+ * @epic T4540
+ */
+
+import { randomUUID } from 'node:crypto';
+import { importFromPackage } from '../admin/import-tasks.js';
+import { getLogger } from '../logger.js';
+import { createLink } from '../reconciliation/link-store.js';
+import { BrainDataAccessor } from '../store/brain-accessor.js';
+import { getBrainDb } from '../store/brain-sqlite.js';
+import { getAccessor } from '../store/data-accessor.js';
+import { exportSingle, exportSubtree } from '../store/export.js';
+import { requirePermission } from './permissions.js';
+import { nexusGetProject } from './registry.js';
+import type {
+  TransferManifest,
+  TransferManifestEntry,
+  TransferParams,
+  TransferResult,
+} from './transfer-types.js';
+
+const log = getLogger('nexus:transfer');
+
+/**
+ * Preview a transfer without writing any data.
+ * Validates projects, permissions, and builds the manifest.
+ */
+export async function previewTransfer(params: TransferParams): Promise<TransferResult> {
+  return executeTransferInternal({ ...params, dryRun: true });
+}
+
+/**
+ * Execute a cross-project task transfer.
+ *
+ * Pipeline:
+ *   1. Validate source/target projects via nexusGetProject()
+ *   2. Check permissions: read on source, write on target
+ *   3. Read source tasks
+ *   4. Build ExportPackage via exportSubtree/exportSingle
+ *   5. Import into target via importFromPackage()
+ *   6. Create bidirectional external_task_links
+ *   7. Write nexus_audit_log entry
+ *   8. If move mode: archive source tasks
+ *   9. If transferBrain: copy brain observations
+ */
+export async function executeTransfer(params: TransferParams): Promise<TransferResult> {
+  return executeTransferInternal(params);
+}
+
+async function executeTransferInternal(params: TransferParams): Promise<TransferResult> {
+  const {
+    taskIds,
+    sourceProject: sourceProjectRef,
+    targetProject: targetProjectRef,
+    mode = 'copy',
+    scope = 'subtree',
+    onConflict = 'rename',
+    onMissingDep = 'strip',
+    provenance = true,
+    targetParent,
+    transferBrain = false,
+    dryRun = false,
+  } = params;
+
+  if (!taskIds.length) {
+    throw new Error('No task IDs specified for transfer');
+  }
+
+  // Step 1: Validate projects
+  const sourceProject = await nexusGetProject(sourceProjectRef);
+  if (!sourceProject) {
+    throw new Error(`Source project not found: ${sourceProjectRef}`);
+  }
+
+  const targetProject = await nexusGetProject(targetProjectRef);
+  if (!targetProject) {
+    throw new Error(`Target project not found: ${targetProjectRef}`);
+  }
+
+  if (sourceProject.hash === targetProject.hash) {
+    throw new Error('Source and target projects must be different');
+  }
+
+  // Step 2: Check permissions
+  await requirePermission(sourceProject.hash, 'read', 'nexus.transfer');
+  await requirePermission(targetProject.hash, 'write', 'nexus.transfer');
+
+  // Step 3: Read source tasks
+  const sourceAccessor = await getAccessor(sourceProject.path);
+  const { tasks: allSourceTasks } = await sourceAccessor.queryTasks({});
+
+  // Step 4: Build ExportPackage for each task
+  const exportPackages = [];
+  for (const taskId of taskIds) {
+    const pkg =
+      scope === 'subtree'
+        ? exportSubtree(taskId, allSourceTasks, sourceProject.name)
+        : exportSingle(taskId, allSourceTasks, sourceProject.name);
+
+    if (!pkg) {
+      throw new Error(`Task not found in source project: ${taskId}`);
+    }
+    exportPackages.push(pkg);
+  }
+
+  // Merge all packages into one (dedup by task ID)
+  const seenIds = new Set<string>();
+  const mergedTasks = [];
+  for (const pkg of exportPackages) {
+    for (const task of pkg.tasks) {
+      if (!seenIds.has(task.id)) {
+        seenIds.add(task.id);
+        mergedTasks.push(task);
+      }
+    }
+  }
+
+  // Use the first package as base and replace tasks
+  const mergedPkg = { ...exportPackages[0]! };
+  mergedPkg.tasks = mergedTasks;
+  mergedPkg._meta = { ...mergedPkg._meta, taskCount: mergedTasks.length };
+
+  // Step 5: Import into target
+  const importResult = await importFromPackage(mergedPkg, {
+    cwd: targetProject.path,
+    dryRun,
+    parent: targetParent,
+    provenance,
+    onConflict,
+    onMissingDep,
+  });
+
+  // Build manifest
+  const entries: TransferManifestEntry[] = mergedTasks.map((t) => ({
+    sourceId: t.id,
+    targetId: importResult.idRemap[t.id] ?? t.id,
+    title: t.title,
+    type: t.type ?? 'task',
+  }));
+
+  const manifest: TransferManifest = {
+    sourceProject: sourceProject.name,
+    targetProject: targetProject.name,
+    mode,
+    scope,
+    entries,
+    idRemap: importResult.idRemap,
+    brainObservationsTransferred: 0,
+  };
+
+  const result: TransferResult = {
+    dryRun,
+    transferred: importResult.imported,
+    skipped: importResult.skipped,
+    archived: 0,
+    linksCreated: 0,
+    brainObservationsTransferred: 0,
+    manifest,
+  };
+
+  if (dryRun) {
+    return result;
+  }
+
+  // Step 6: Create bidirectional external_task_links
+  // Only create links for tasks that were actually imported (verify they exist in target)
+  let linksCreated = 0;
+  const targetAccessor = await getAccessor(targetProject.path);
+  const { tasks: targetTasks } = await targetAccessor.queryTasks({});
+  const targetTaskIds = new Set(targetTasks.map((t) => t.id));
+
+  for (const entry of entries) {
+    if (importResult.idRemap[entry.sourceId] && targetTaskIds.has(entry.targetId)) {
+      // Link in target: points back to source
+      await createLink(
+        {
+          taskId: entry.targetId,
+          providerId: `nexus:${sourceProject.name}`,
+          externalId: entry.sourceId,
+          externalTitle: entry.title,
+          linkType: 'transferred',
+          syncDirection: 'inbound',
+          metadata: {
+            transferMode: mode,
+            transferScope: scope,
+            sourceProject: sourceProject.name,
+            transferredAt: new Date().toISOString(),
+          },
+        },
+        targetProject.path,
+      );
+      linksCreated++;
+
+      // Link in source: points to target
+      await createLink(
+        {
+          taskId: entry.sourceId,
+          providerId: `nexus:${targetProject.name}`,
+          externalId: entry.targetId,
+          externalTitle: entry.title,
+          linkType: 'transferred',
+          syncDirection: 'outbound',
+          metadata: {
+            transferMode: mode,
+            transferScope: scope,
+            targetProject: targetProject.name,
+            transferredAt: new Date().toISOString(),
+          },
+        },
+        sourceProject.path,
+      );
+      linksCreated++;
+    }
+  }
+  result.linksCreated = linksCreated;
+
+  // Step 7: Write audit log
+  try {
+    const { getNexusDb } = await import('../store/nexus-sqlite.js');
+    const { nexusAuditLog } = await import('../store/nexus-schema.js');
+    const db = await getNexusDb();
+    await db.insert(nexusAuditLog).values({
+      id: randomUUID(),
+      action: 'transfer',
+      projectHash: sourceProject.hash,
+      projectId: sourceProject.projectId,
+      domain: 'nexus',
+      operation: 'transfer',
+      success: 1,
+      detailsJson: JSON.stringify({
+        sourceProject: sourceProject.name,
+        targetProject: targetProject.name,
+        mode,
+        scope,
+        taskCount: result.transferred,
+        idRemap: importResult.idRemap,
+      }),
+    });
+  } catch (err) {
+    log.warn({ err }, 'nexus transfer audit write failed');
+  }
+
+  // Step 8: Move mode — archive source tasks
+  if (mode === 'move') {
+    let archived = 0;
+    for (const entry of entries) {
+      if (importResult.idRemap[entry.sourceId]) {
+        try {
+          await sourceAccessor.archiveSingleTask(entry.sourceId, {
+            archivedAt: new Date().toISOString(),
+            archiveReason: `Transferred to ${targetProject.name} as ${entry.targetId}`,
+          });
+          archived++;
+        } catch (err) {
+          log.warn({ err, taskId: entry.sourceId }, 'failed to archive source task after transfer');
+        }
+      }
+    }
+    result.archived = archived;
+  }
+
+  // Step 9: Brain observation transfer
+  if (transferBrain) {
+    let brainTransferred = 0;
+    try {
+      const sourceBrainDb = await getBrainDb(sourceProject.path);
+      const targetBrainDb = await getBrainDb(targetProject.path);
+      const sourceBrain = new BrainDataAccessor(sourceBrainDb);
+      const targetBrain = new BrainDataAccessor(targetBrainDb);
+
+      for (const entry of entries) {
+        if (!importResult.idRemap[entry.sourceId]) continue;
+
+        const links = await sourceBrain.getLinksForTask(entry.sourceId);
+        for (const link of links) {
+          if (link.memoryType !== 'observation') continue;
+
+          const observation = await sourceBrain.getObservation(link.memoryId);
+          if (!observation) continue;
+
+          const newObsId = `O-${randomUUID().slice(0, 8)}`;
+          await targetBrain.addObservation({
+            ...observation,
+            id: newObsId,
+            createdAt: observation.createdAt,
+            updatedAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+          });
+
+          await targetBrain.addLink({
+            memoryType: 'observation',
+            memoryId: newObsId,
+            taskId: entry.targetId,
+            linkType: 'applies_to',
+            createdAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+          });
+
+          brainTransferred++;
+        }
+      }
+    } catch (err) {
+      log.warn({ err }, 'brain observation transfer failed');
+    }
+    result.brainObservationsTransferred = brainTransferred;
+    result.manifest.brainObservationsTransferred = brainTransferred;
+  }
+
+  return result;
+}

package/src/orchestration/bootstrap.ts

@@ -7,7 +7,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { BrainState } from '@cleocode/contracts';
-import { getSessionsPath } from '../paths.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
@@ -26,29 +25,24 @@ export async function buildBrainState(
     },
   };
 
-  // --- Session (from sessions.json) ---
+  // --- Session (from SQLite, ADR-006/ADR-020) ---
+  const acc = accessor ?? (await getAccessor(projectRoot));
   try {
-    const sessionsPath = getSessionsPath(projectRoot);
-    if (existsSync(sessionsPath)) {
-      const sessionsData = JSON.parse(readFileSync(sessionsPath, 'utf-8'));
-      const activeSession = (sessionsData.sessions ?? []).find(
-        (s: { status: string }) => s.status === 'active',
-      );
-      if (activeSession) {
-        brain.session = {
-          id: activeSession.id,
-          name: activeSession.name || activeSession.id,
-          status: activeSession.status,
-          startedAt: activeSession.startedAt,
-        };
-      }
+    const sessions = await acc.loadSessions();
+    const activeSession = sessions.find((s) => s.status === 'active');
+    if (activeSession) {
+      brain.session = {
+        id: activeSession.id,
+        name: activeSession.name || activeSession.id,
+        status: activeSession.status,
+        startedAt: activeSession.startedAt,
+      };
     }
   } catch {
     // skip
   }
 
   // --- Tasks & Progress ---
-  const acc = accessor ?? (await getAccessor(projectRoot));
   const { tasks } = await acc.queryTasks({});
 
   brain.progress = {

package/src/orchestration/skill-ops.ts

@@ -25,52 +25,72 @@ export interface SkillContent {
   path: string;
 }
 
-/** List available skills. */
-export function listSkills(_projectRoot: string): { skills: SkillEntry[]; total: number } {
-  const skillsDir = getCanonicalSkillsDir();
+/** List available skills from canonical and project-local directories. */
+export function listSkills(projectRoot: string): { skills: SkillEntry[]; total: number } {
+  const seen = new Set<string>();
+  const allSkills: SkillEntry[] = [];
 
-  if (!existsSync(skillsDir)) {
-    return { skills: [], total: 0 };
-  }
+  // Scan a skills directory and collect entries
+  function scanSkillsDir(dir: string): void {
+    if (!existsSync(dir)) return;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const d of entries) {
+        if (!d.isDirectory() || d.name.startsWith('_') || seen.has(d.name)) continue;
+        seen.add(d.name);
+
+        const skillPath = join(dir, d.name, 'SKILL.md');
+        let description = '';
 
-  const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && !d.name.startsWith('_'))
-    .map((d) => {
-      const skillPath = join(skillsDir, d.name, 'SKILL.md');
-      let description = '';
-
-      if (existsSync(skillPath)) {
-        try {
-          const content = readFileSync(skillPath, 'utf-8');
-          const descMatch = content.match(/description:\s*[|>]?\s*\n?\s*(.+)/);
-          if (descMatch) {
-            description = descMatch[1]!.trim();
+        if (existsSync(skillPath)) {
+          try {
+            const content = readFileSync(skillPath, 'utf-8');
+            const descMatch = content.match(/description:\s*[|>]?\s*\n?\s*(.+)/);
+            if (descMatch) {
+              description = descMatch[1]!.trim();
+            }
+          } catch {
+            // ignore
           }
-        } catch {
-          // ignore
         }
+
+        allSkills.push({
+          name: d.name,
+          path: join(dir, d.name),
+          hasSkillFile: existsSync(skillPath),
+          description,
+        });
       }
+    } catch {
+      // ignore unreadable directories
+    }
+  }
 
-      return {
-        name: d.name,
-        path: join(skillsDir, d.name),
-        hasSkillFile: existsSync(skillPath),
-        description,
-      };
-    });
+  // 1. Scan project-local skills (higher priority, listed first)
+  scanSkillsDir(join(projectRoot, '.cleo', 'skills'));
 
-  return { skills: skillDirs, total: skillDirs.length };
+  // 2. Scan canonical (global) skills
+  scanSkillsDir(getCanonicalSkillsDir());
+
+  return { skills: allSkills, total: allSkills.length };
 }
 
-/** Read skill content for injection into agent context. */
-export function getSkillContent(skillName: string, _projectRoot: string): SkillContent {
+/** Read skill content for injection into agent context. Checks project-local skills first. */
+export function getSkillContent(skillName: string, projectRoot: string): SkillContent {
   if (!skillName) {
     throw new CleoError(ExitCode.INVALID_INPUT, 'skill name is required');
   }
 
-  const skillDir = join(getCanonicalSkillsDir(), skillName);
+  // Check project-local skills first, then canonical
+  const projectSkillDir = join(projectRoot, '.cleo', 'skills', skillName);
+  const canonicalSkillDir = join(getCanonicalSkillsDir(), skillName);
+  const skillDir = existsSync(projectSkillDir) ? projectSkillDir : canonicalSkillDir;
+
   if (!existsSync(skillDir)) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Skill '${skillName}' not found at ${skillDir}`);
+    throw new CleoError(
+      ExitCode.NOT_FOUND,
+      `Skill '${skillName}' not found at ${canonicalSkillDir} or ${projectSkillDir}`,
+    );
   }
 
   const skillFilePath = join(skillDir, 'SKILL.md');

package/src/otel/index.ts

@@ -125,14 +125,58 @@ export async function getOtelSpawns(opts: {
 }
 
 /** Get real token usage from Claude Code API. */
-export async function getRealTokenUsage(_opts: {
+export async function getRealTokenUsage(opts: {
   session?: string;
   since?: string;
 }): Promise<Record<string, unknown>> {
-  // Real token usage requires OTel integration - return placeholder
+  const otelEnabled = process.env.CLAUDE_CODE_ENABLE_TELEMETRY === '1';
+
+  // Read JSONL token data and filter by opts
+  const entries = readJsonlFile(getTokenFilePath());
+
+  if (entries.length === 0) {
+    return {
+      message: otelEnabled
+        ? 'OTel enabled but no token data recorded yet'
+        : 'Real token usage requires OpenTelemetry configuration',
+      otelEnabled,
+      totalEvents: 0,
+    };
+  }
+
+  let filtered = entries;
+
+  // Filter by session if provided
+  if (opts.session) {
+    filtered = filtered.filter((e) => {
+      const ctx = (e.context ?? {}) as Record<string, unknown>;
+      return ctx.session_id === opts.session || e.session_id === opts.session;
+    });
+  }
+
+  // Filter by since timestamp if provided
+  if (opts.since) {
+    const sinceDate = new Date(opts.since).getTime();
+    filtered = filtered.filter((e) => {
+      const ts = (e.timestamp ?? e.recorded_at) as string | undefined;
+      return ts ? new Date(ts).getTime() >= sinceDate : true;
+    });
+  }
+
+  const totalTokens = filtered.reduce((sum, e) => sum + ((e.estimated_tokens as number) ?? 0), 0);
+  const inputTokens = filtered.reduce((sum, e) => sum + ((e.input_tokens as number) ?? 0), 0);
+  const outputTokens = filtered.reduce((sum, e) => sum + ((e.output_tokens as number) ?? 0), 0);
+
   return {
-    message: 'Real token usage requires OpenTelemetry configuration',
-    otelEnabled: process.env.CLAUDE_CODE_ENABLE_TELEMETRY === '1',
+    otelEnabled,
+    totalEvents: filtered.length,
+    totalTokens,
+    inputTokens,
+    outputTokens,
+    filters: {
+      session: opts.session ?? null,
+      since: opts.since ?? null,
+    },
   };
 }
 

package/src/sessions/__tests__/briefing.test.ts

@@ -21,6 +21,12 @@ vi.mock('../handoff.js', () => ({
   getLastHandoff: vi.fn().mockResolvedValue(null),
 }));
 
+// Mock lifecycle pipeline — computePipelineStage dynamically imports this
+let mockPipeline: unknown = null;
+vi.mock('../../lifecycle/pipeline.js', () => ({
+  getPipeline: vi.fn().mockImplementation(() => Promise.resolve(mockPipeline)),
+}));
+
 import { getAccessor } from '../../store/data-accessor.js';
 import { computeBriefing } from '../briefing.js';
 
@@ -337,8 +343,28 @@ describe('computeBriefing scope filtering', () => {
     expect(briefing.currentTask!.title).toBe('Child 1');
   });
 
-  it('pipelineStage is included when metadata has lifecycle state', async () => {
-    setupMockAccessor(makeMockTasks(), { lifecycleState: 'implementation' });
+  it('pipelineStage is included when active lifecycle pipeline exists', async () => {
+    // Mock the lifecycle pipeline BEFORE calling computeBriefing
+    mockPipeline = { currentStage: 'implementation', status: 'active', isActive: true };
+
+    // Set up focus state pointing to a task that has a pipeline
+    const focus = { currentTask: 'T100', currentPhase: null };
+    const metaStore: Record<string, unknown> = { focus_state: focus };
+    const tasks = makeMockTasks();
+    const mockAccessor = {
+      loadSessions: vi.fn().mockResolvedValue([]),
+      queryTasks: vi.fn().mockResolvedValue({ tasks, total: tasks.length }),
+      getMetaValue: vi
+        .fn()
+        .mockImplementation((key: string) => Promise.resolve(metaStore[key] ?? null)),
+      setMetaValue: vi.fn().mockResolvedValue(undefined),
+      loadArchive: vi.fn().mockResolvedValue(null),
+      saveArchive: vi.fn().mockResolvedValue(undefined),
+      appendLog: vi.fn().mockResolvedValue(undefined),
+      close: vi.fn().mockResolvedValue(undefined),
+      engine: 'sqlite' as const,
+    };
+    (getAccessor as ReturnType<typeof vi.fn>).mockResolvedValue(mockAccessor);
 
     const briefing = await computeBriefing('/fake/project', {
       scope: 'global',
@@ -346,6 +372,9 @@ describe('computeBriefing scope filtering', () => {
 
     expect(briefing.pipelineStage).toBeDefined();
     expect(briefing.pipelineStage!.currentStage).toBe('implementation');
+
+    // Reset
+    mockPipeline = null;
   });
 
   it('blocked tasks include those with unresolved dependencies', async () => {