@cleocode/core 2.0.0

package/src/sessions/session-drift.ts

@@ -0,0 +1,162 @@
+/**
+ * Compute context drift score for a session.
+ *
+ * @task T4782
+ * @epic T4654
+ */
+
+import { getAccessor } from '../store/data-accessor.js';
+import { ExitCode } from '@cleocode/contracts';
+import type { Session, Task, TaskWorkState } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+
+export interface ContextDriftResult {
+  score: number;
+  factors: string[];
+  completedInScope: number;
+  totalInScope: number;
+  outOfScope: number;
+}
+
+/**
+ * Collect all descendant task IDs for a given parent task.
+ */
+function collectDescendantIds(
+  parentId: string,
+  tasks: Task[],
+): Set<string> {
+  const result = new Set<string>();
+
+  for (const task of tasks) {
+    if (task.parentId === parentId) {
+      result.add(task.id);
+      const grandchildren = collectDescendantIds(task.id, tasks);
+      for (const gc of grandchildren) {
+        result.add(gc);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Compute context drift score for the current session.
+ * Compares session progress against original scope by counting
+ * completed vs total tasks in scope, and detecting out-of-scope work.
+ */
+export async function getContextDrift(
+  projectRoot: string,
+  params?: { sessionId?: string },
+): Promise<ContextDriftResult> {
+  const accessor = await getAccessor(projectRoot);
+  const { tasks } = await accessor.queryTasks({});
+  const focus = await accessor.getMetaValue<TaskWorkState>('focus_state');
+  const current = {
+    tasks,
+    focus: focus ?? undefined,
+  };
+
+  // Find the active session (or specified session)
+  let session: Session | undefined;
+
+  if (params?.sessionId) {
+    const sessions = await accessor.loadSessions();
+    session = sessions.find((s) => s.id === params.sessionId);
+    if (!session) {
+      throw new CleoError(ExitCode.SESSION_NOT_FOUND, `Session '${params.sessionId}' not found`);
+    }
+  } else {
+    const activeSession = await accessor.getActiveSession();
+    session = activeSession ?? undefined;
+  }
+
+  const factors: string[] = [];
+
+  // If no session with scope, compute a basic drift from focus state
+  if (!session) {
+    const focusTask = current.focus?.currentTask;
+    if (!focusTask) {
+      return {
+        score: 0,
+        factors: ['No active session or focus'],
+        completedInScope: 0,
+        totalInScope: 0,
+        outOfScope: 0,
+      };
+    }
+
+    const rootTaskId = focusTask;
+    const inScopeIds = collectDescendantIds(rootTaskId, tasks);
+    inScopeIds.add(rootTaskId);
+
+    const inScopeTasks = tasks.filter((t) => inScopeIds.has(t.id));
+    const completedInScope = inScopeTasks.filter((t) => t.status === 'done').length;
+    const totalInScope = inScopeTasks.length;
+
+    const score = totalInScope > 0 ? Math.round((completedInScope / totalInScope) * 100) : 0;
+    factors.push('Single-session mode (focus-based scope)');
+    if (completedInScope === 0) factors.push('No tasks completed in scope yet');
+
+    return { score, factors, completedInScope, totalInScope, outOfScope: 0 };
+  }
+
+  // Multi-session: use session scope to determine in-scope tasks
+  const rootTaskId = session.scope.rootTaskId ?? session.scope.epicId ?? '';
+  const inScopeIds = new Set<string>();
+
+  if (session.scope.explicitTaskIds && session.scope.explicitTaskIds.length > 0) {
+    for (const id of session.scope.explicitTaskIds) {
+      inScopeIds.add(id);
+    }
+  } else {
+    inScopeIds.add(rootTaskId);
+    if (session.scope.includeDescendants !== false) {
+      const descendants = collectDescendantIds(rootTaskId, tasks);
+      for (const id of descendants) {
+        inScopeIds.add(id);
+      }
+    }
+  }
+
+  if (session.scope.excludeTaskIds) {
+    for (const id of session.scope.excludeTaskIds) {
+      inScopeIds.delete(id);
+    }
+  }
+
+  const inScopeTasks = tasks.filter((t) => inScopeIds.has(t.id));
+  const completedInScope = inScopeTasks.filter((t) => t.status === 'done').length;
+  const totalInScope = inScopeTasks.length;
+
+  // Detect out-of-scope work: tasks completed during session that are NOT in scope
+  let outOfScope = 0;
+  const sessionStartTime = new Date(session.startedAt).getTime();
+  for (const task of tasks) {
+    if (!inScopeIds.has(task.id) && task.status === 'done') {
+      const completedAt =
+        typeof task.completedAt === 'string' ? new Date(task.completedAt).getTime() : 0;
+      if (completedAt >= sessionStartTime) {
+        outOfScope++;
+      }
+    }
+  }
+
+  // Calculate drift score (0 = no progress, 100 = all done in scope)
+  let score = 0;
+  if (totalInScope > 0) {
+    const progressRatio = completedInScope / totalInScope;
+    const driftPenalty = outOfScope > 0 ? Math.min(outOfScope / totalInScope, 0.5) : 0;
+    score = Math.round(Math.max(0, Math.min(100, progressRatio * 100 - driftPenalty * 50)));
+  }
+
+  if (totalInScope === 0) factors.push('No tasks found in session scope');
+  if (completedInScope === 0 && totalInScope > 0) factors.push('No tasks completed in scope yet');
+  if (completedInScope === totalInScope && totalInScope > 0)
+    factors.push('All in-scope tasks completed');
+  if (outOfScope > 0) factors.push(`${outOfScope} task(s) completed outside of session scope`);
+  if (outOfScope === 0 && completedInScope > 0) factors.push('All completed work is within scope');
+  if (session.scope.type) factors.push(`Scope type: ${session.scope.type}`);
+
+  return { score, factors, completedInScope, totalInScope, outOfScope };
+}

package/src/sessions/session-enforcement.ts

@@ -0,0 +1,180 @@
+/**
+ * Session enforcement - require active sessions for write operations.
+ *
+ * Part of the Epic-Bound Session architecture. Enforces that write operations
+ * (add, update, complete) require an active session.
+ *
+ * @task T4454
+ * @epic T4454
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+import { getCleoDir } from '../paths.js';
+import { sessionStatus } from './index.js';
+
+/** Synchronous config value reader. */
+function readConfigValueSync(path: string, defaultValue: unknown, cwd?: string): unknown {
+  try {
+    const configPath = join(getCleoDir(cwd), 'config.json');
+    if (!existsSync(configPath)) return defaultValue;
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const keys = path.split('.');
+    let value: unknown = config;
+    for (const key of keys) {
+      if (value == null || typeof value !== 'object') return defaultValue;
+      value = (value as Record<string, unknown>)[key];
+    }
+    return value ?? defaultValue;
+  } catch {
+    return defaultValue;
+  }
+}
+
+/** Enforcement modes. */
+export type EnforcementMode = 'strict' | 'warn' | 'none';
+
+/** Get the current enforcement mode. */
+export function getEnforcementMode(cwd?: string): EnforcementMode {
+  try {
+    // Get enforcement mode from config
+    const mode = readConfigValueSync('session.enforcement', 'strict', cwd) as string;
+    if (mode === 'strict' || mode === 'warn' || mode === 'none') return mode;
+    return 'strict'; // Default
+  } catch {
+    return 'none';
+  }
+}
+
+/** Check if session enforcement is enabled. */
+export function isSessionEnforcementEnabled(cwd?: string): boolean {
+  return getEnforcementMode(cwd) !== 'none';
+}
+
+/** Session info for enforcement checks. */
+export interface ActiveSessionInfo {
+  id: string;
+  name: string;
+  scope: { type: string; epicId?: string };
+}
+
+/** Get active session info. Returns null if no active session. */
+export async function getActiveSessionInfo(cwd?: string): Promise<ActiveSessionInfo | null> {
+  const session = await sessionStatus(cwd);
+  if (!session) return null;
+
+  return {
+    id: session.id,
+    name: session.name,
+    scope: session.scope,
+  };
+}
+
+/** Enforcement result. */
+export interface EnforcementResult {
+  allowed: boolean;
+  mode: EnforcementMode;
+  session: ActiveSessionInfo | null;
+  warning?: string;
+}
+
+/**
+ * Require an active session for write operations.
+ * In strict mode, throws if no session is active.
+ * In warn mode, returns a warning but allows the operation.
+ * In none mode, always allows.
+ */
+export async function requireActiveSession(
+  operation: string,
+  cwd?: string,
+): Promise<EnforcementResult> {
+  const mode = getEnforcementMode(cwd);
+
+  if (mode === 'none') {
+    return { allowed: true, mode, session: null };
+  }
+
+  const session = await getActiveSessionInfo(cwd);
+
+  if (session) {
+    return { allowed: true, mode, session };
+  }
+
+  // No active session
+  if (mode === 'strict') {
+    throw new CleoError(
+      ExitCode.SESSION_REQUIRED,
+      `Operation '${operation}' requires an active session`,
+      {
+        fix: 'Start a session with \'cleo session start --scope epic:T### --auto-start --name "Work"\'',
+        alternatives: [
+          {
+            action: 'Start session',
+            command: 'cleo session start --scope epic:T001 --auto-start --name "Work"',
+          },
+          { action: 'List sessions', command: 'cleo session list' },
+        ],
+      },
+    );
+  }
+
+  // Warn mode
+  return {
+    allowed: true,
+    mode,
+    session: null,
+    warning: `No active session for operation '${operation}'. Consider starting one.`,
+  };
+}
+
+/**
+ * Validate that a task is within the current session's scope.
+ * Only enforced when a session is active.
+ */
+export async function validateTaskInScope(
+  taskId: string,
+  taskEpicId?: string,
+  cwd?: string,
+): Promise<{ inScope: boolean; warning?: string }> {
+  const mode = getEnforcementMode(cwd);
+  if (mode === 'none') return { inScope: true };
+
+  const session = await getActiveSessionInfo(cwd);
+  if (!session) return { inScope: true }; // No session = no scope enforcement
+
+  // Global scope allows everything
+  if (session.scope.type === 'global') return { inScope: true };
+
+  // Epic scope: task must be within the session's epic
+  if (session.scope.type === 'epic' && session.scope.epicId) {
+    const epicId = session.scope.epicId;
+
+    // Task is the epic itself or is a child
+    if (taskId === epicId || taskEpicId === epicId) {
+      return { inScope: true };
+    }
+
+    if (mode === 'strict') {
+      throw new CleoError(
+        ExitCode.TASK_NOT_IN_SCOPE,
+        `Task ${taskId} is not in scope of session ${session.id} (epic: ${epicId})`,
+        {
+          fix: `Focus on tasks within epic ${epicId} or start a new session`,
+          alternatives: [
+            { action: 'View session', command: `cleo session status` },
+            { action: 'End session', command: `cleo session end` },
+          ],
+        },
+      );
+    }
+
+    return {
+      inScope: false,
+      warning: `Task ${taskId} is outside session scope (epic: ${epicId})`,
+    };
+  }
+
+  return { inScope: true };
+}

package/src/sessions/session-grade.ts

@@ -0,0 +1,334 @@
+/**
+ * Session grading - rubric-based behavioral analysis of agent sessions.
+ *
+ * Reads audit log entries for a session and applies a 5-dimension rubric
+ * to score agent behavior:
+ *   - Session discipline (20pts)
+ *   - Discovery efficiency (20pts)
+ *   - Task hygiene (20pts)
+ *   - Error protocol (20pts)
+ *   - Progressive disclosure use (20pts)
+ *
+ * @task T4916
+ */
+
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { AuditEntry } from '../audit.js';
+import { queryAudit } from '../audit.js';
+import { getCleoDirAbsolute } from '../paths.js';
+
+export interface DimensionScore {
+  score: number;
+  max: number;
+  evidence: string[];
+}
+
+export interface GradeResult {
+  sessionId: string;
+  taskId?: string;
+  totalScore: number;
+  maxScore: number;
+  dimensions: {
+    sessionDiscipline: DimensionScore;
+    discoveryEfficiency: DimensionScore;
+    taskHygiene: DimensionScore;
+    errorProtocol: DimensionScore;
+    disclosureUse: DimensionScore;
+  };
+  flags: string[];
+  timestamp: string;
+  entryCount: number;
+}
+
+/**
+ * Grade a session by sessionId using the 5-dimension behavioral rubric.
+ */
+export async function gradeSession(sessionId: string, cwd?: string): Promise<GradeResult> {
+  const sessionEntries = await queryAudit({ sessionId });
+
+  const result: GradeResult = {
+    sessionId,
+    totalScore: 0,
+    maxScore: 100,
+    dimensions: {
+      sessionDiscipline: { score: 0, max: 20, evidence: [] },
+      discoveryEfficiency: { score: 0, max: 20, evidence: [] },
+      taskHygiene: { score: 0, max: 20, evidence: [] },
+      errorProtocol: { score: 0, max: 20, evidence: [] },
+      disclosureUse: { score: 0, max: 20, evidence: [] },
+    },
+    flags: [],
+    timestamp: new Date().toISOString(),
+    entryCount: sessionEntries.length,
+  };
+
+  if (sessionEntries.length === 0) {
+    result.flags.push(
+      'No audit entries found for session (use --grade flag when starting session)',
+    );
+    await appendGradeResult(result, cwd);
+    return result;
+  }
+
+  // -- Dimension 1: Session Discipline (20pts) --
+  const sessionListCalls = sessionEntries.filter(
+    (e) => e.domain === 'session' && e.operation === 'list',
+  );
+  const sessionEndCalls = sessionEntries.filter(
+    (e) => e.domain === 'session' && e.operation === 'end',
+  );
+  const taskOps = sessionEntries.filter((e) => e.domain === 'tasks');
+
+  let disciplineScore = 0;
+
+  if (sessionListCalls.length > 0) {
+    const firstListTime = new Date(sessionListCalls[0].timestamp).getTime();
+    const firstTaskTime = taskOps.length > 0 ? new Date(taskOps[0].timestamp).getTime() : Infinity;
+    if (firstListTime <= firstTaskTime) {
+      disciplineScore += 10;
+      result.dimensions.sessionDiscipline.evidence.push('session.list called before first task op');
+    } else {
+      result.flags.push('session.list called after task ops (should check sessions first)');
+    }
+  } else {
+    result.flags.push('session.list never called (check existing sessions before starting)');
+  }
+
+  if (sessionEndCalls.length > 0) {
+    disciplineScore += 10;
+    result.dimensions.sessionDiscipline.evidence.push('session.end called');
+  } else {
+    result.flags.push('session.end never called (always end sessions when done)');
+  }
+
+  result.dimensions.sessionDiscipline.score = disciplineScore;
+
+  // -- Dimension 2: Discovery Efficiency (20pts) --
+  const findCalls = sessionEntries.filter((e) => e.domain === 'tasks' && e.operation === 'find');
+  const listCalls = sessionEntries.filter((e) => e.domain === 'tasks' && e.operation === 'list');
+  const showCalls = sessionEntries.filter((e) => e.domain === 'tasks' && e.operation === 'show');
+
+  let discoveryScore = 0;
+  const totalDiscoveryCalls = findCalls.length + listCalls.length;
+
+  if (totalDiscoveryCalls > 0) {
+    const findRatio = findCalls.length / totalDiscoveryCalls;
+    if (findRatio >= 0.8) {
+      discoveryScore += 15;
+      result.dimensions.discoveryEfficiency.evidence.push(
+        `find:list ratio ${(findRatio * 100).toFixed(0)}% >= 80%`,
+      );
+    } else {
+      result.flags.push(`tasks.list used ${listCalls.length}x (prefer tasks.find for discovery)`);
+      discoveryScore += Math.round(15 * findRatio);
+    }
+  } else {
+    discoveryScore += 10;
+    result.dimensions.discoveryEfficiency.evidence.push('No discovery calls needed');
+  }
+
+  if (showCalls.length > 0) {
+    discoveryScore = Math.min(20, discoveryScore + 5);
+    result.dimensions.discoveryEfficiency.evidence.push(
+      `tasks.show used ${showCalls.length}x for detail`,
+    );
+  }
+
+  result.dimensions.discoveryEfficiency.score = Math.min(20, discoveryScore);
+
+  // -- Dimension 3: Task Hygiene (20pts) --
+  const addCalls = sessionEntries.filter(
+    (e) => e.domain === 'tasks' && e.operation === 'add' && e.result.success,
+  );
+  const existsCalls = sessionEntries.filter(
+    (e) => e.domain === 'tasks' && e.operation === 'exists',
+  );
+
+  let hygieneScore = 20;
+
+  for (const addCall of addCalls) {
+    const desc = addCall.params?.description as string | undefined;
+    if (!desc || desc.trim().length === 0) {
+      hygieneScore -= 5;
+      result.flags.push(
+        `tasks.add without description (taskId: ${addCall.metadata?.taskId ?? 'unknown'})`,
+      );
+    }
+  }
+
+  const subtaskAdds = addCalls.filter((e) => e.params?.parent);
+  if (subtaskAdds.length > 0 && existsCalls.length > 0) {
+    result.dimensions.taskHygiene.evidence.push(
+      'Parent existence verified before subtask creation',
+    );
+  } else if (subtaskAdds.length > 0) {
+    result.flags.push('Subtasks created without tasks.exists parent check');
+    hygieneScore -= 3;
+  }
+
+  if (addCalls.length > 0 && hygieneScore >= 20) {
+    result.dimensions.taskHygiene.evidence.push(
+      `All ${addCalls.length} tasks.add calls had descriptions`,
+    );
+  }
+
+  result.dimensions.taskHygiene.score = Math.max(0, hygieneScore);
+
+  // -- Dimension 4: Error Protocol (20pts) --
+  const notFoundErrors = sessionEntries.filter((e) => !e.result.success && e.result.exitCode === 4);
+
+  let errorScore = 20;
+
+  for (const errEntry of notFoundErrors) {
+    const errIdx = sessionEntries.indexOf(errEntry);
+    const nextEntries = sessionEntries.slice(errIdx + 1, errIdx + 5);
+    const hasRecovery = nextEntries.some(
+      (e) => e.domain === 'tasks' && (e.operation === 'find' || e.operation === 'exists'),
+    );
+    if (!hasRecovery) {
+      errorScore -= 5;
+      result.flags.push(
+        `E_NOT_FOUND (${errEntry.domain}.${errEntry.operation}) not followed by recovery lookup`,
+      );
+    } else {
+      result.dimensions.errorProtocol.evidence.push('E_NOT_FOUND followed by recovery lookup');
+    }
+  }
+
+  const duplicateCreates = detectDuplicateCreates(sessionEntries);
+  if (duplicateCreates > 0) {
+    errorScore -= 5;
+    result.flags.push(`${duplicateCreates} potentially duplicate task create(s) detected`);
+  }
+
+  if (notFoundErrors.length === 0 && duplicateCreates === 0) {
+    result.dimensions.errorProtocol.evidence.push('No error protocol violations');
+  }
+
+  result.dimensions.errorProtocol.score = Math.max(0, errorScore);
+
+  // -- Dimension 5: Progressive Disclosure Use (20pts) --
+  const helpCalls = sessionEntries.filter(
+    (e) =>
+      (e.domain === 'admin' && e.operation === 'help') ||
+      (e.domain === 'tools' && (e.operation === 'skill.show' || e.operation === 'skill.list')) ||
+      (e.domain === 'skills' && (e.operation === 'list' || e.operation === 'show')),
+  );
+  // gateway is stored as 'query'/'mutate' in the audit log
+  const mcpQueryCalls = sessionEntries.filter((e) => e.metadata?.gateway === 'query');
+
+  let disclosureScore = 0;
+
+  if (helpCalls.length > 0) {
+    disclosureScore += 10;
+    result.dimensions.disclosureUse.evidence.push(
+      `Progressive disclosure used (${helpCalls.length}x)`,
+    );
+  } else {
+    result.flags.push('No admin.help or skill lookup calls (load ct-cleo for guidance)');
+  }
+
+  if (mcpQueryCalls.length > 0) {
+    disclosureScore += 10;
+    result.dimensions.disclosureUse.evidence.push(`query (MCP) used ${mcpQueryCalls.length}x`);
+  } else {
+    result.flags.push('No MCP query calls (prefer query over CLI for programmatic access)');
+  }
+
+  result.dimensions.disclosureUse.score = disclosureScore;
+
+  // -- Total --
+  result.totalScore = Object.values(result.dimensions).reduce((sum, d) => sum + d.score, 0);
+
+  await feedGradeToBrain(result, cwd);
+  await appendGradeResult(result, cwd);
+  return result;
+}
+
+/** Detect potentially duplicate task creates (same title within session). */
+function detectDuplicateCreates(entries: AuditEntry[]): number {
+  const creates = entries.filter(
+    (e) => e.domain === 'tasks' && e.operation === 'add' && e.result.success,
+  );
+  const titles = creates
+    .map((e) => (e.params?.title as string)?.toLowerCase().trim())
+    .filter(Boolean);
+  const unique = new Set(titles);
+  return titles.length - unique.size;
+}
+
+/**
+ * Feed grade insights back into brain.db as learnings.
+ * Best-effort — errors are silently caught.
+ */
+async function feedGradeToBrain(result: GradeResult, projectRoot?: string): Promise<void> {
+  if (!projectRoot) return;
+
+  try {
+    const { storeLearning } = await import('../memory/learnings.js');
+
+    // Find dimensions scoring below 50% of max
+    const weakDimensions: string[] = [];
+    for (const [name, dim] of Object.entries(result.dimensions)) {
+      if (dim.score < dim.max * 0.5) {
+        weakDimensions.push(name);
+      }
+    }
+
+    if (weakDimensions.length > 0) {
+      await storeLearning(projectRoot, {
+        insight: `Session ${result.sessionId} scored ${result.totalScore}/${result.maxScore}. Weak dimensions: ${weakDimensions.join(', ')}`,
+        source: `grade:${result.sessionId}`,
+        confidence: 0.8,
+        actionable: true,
+        application: `Improve in next session: ${weakDimensions.join(', ')}`,
+      });
+    }
+
+    // Store protocol violations as separate learning
+    if (result.flags.length > 0) {
+      await storeLearning(projectRoot, {
+        insight: `Session ${result.sessionId} protocol violations: ${result.flags.join('; ')}`,
+        source: `grade:${result.sessionId}`,
+        confidence: 0.7,
+        actionable: true,
+        application: 'Address protocol violations in next session',
+      });
+    }
+  } catch {
+    // Best-effort — grade feedback should never block
+  }
+}
+
+/** Append a grade result to .cleo/metrics/GRADES.jsonl */
+async function appendGradeResult(result: GradeResult, cwd?: string): Promise<void> {
+  try {
+    const cleoDir = getCleoDirAbsolute(cwd);
+    const metricsDir = join(cleoDir, 'metrics');
+    await mkdir(metricsDir, { recursive: true });
+    const gradesPath = join(metricsDir, 'GRADES.jsonl');
+    const line = JSON.stringify({ ...result, evaluator: 'auto' }) + '\n';
+    await appendFile(gradesPath, line, 'utf8');
+  } catch {
+    // Best-effort
+  }
+}
+
+/** Read past grade results from .cleo/metrics/GRADES.jsonl */
+export async function readGrades(sessionId?: string, cwd?: string): Promise<GradeResult[]> {
+  try {
+    const cleoDir = getCleoDirAbsolute(cwd);
+    const gradesPath = join(cleoDir, 'metrics', 'GRADES.jsonl');
+    if (!existsSync(gradesPath)) return [];
+    const content = await readFile(gradesPath, 'utf8');
+    const results = content
+      .split('\n')
+      .filter((l) => l.trim())
+      .map((l) => JSON.parse(l) as GradeResult);
+    return sessionId ? results.filter((r) => r.sessionId === sessionId) : results;
+  } catch {
+    return [];
+  }
+}