cognitive-core 0.2.4 → 0.3.1

package/docs/DESIGN-session-bank.md

@@ -1,1134 +0,0 @@
-# Design: Session Bank (Entire-backed)
-
-> **Status**: Proposed
-> **Authors**: Alex Ngai, Claude
-> **Date**: 2026-02-24
-> **Related**: [Entire CLI](https://github.com/entireio/cli), [ReMem](https://arxiv.org/abs/2501.00662)
-
-## 1. Motivation
-
-cognitive-core's learning pipeline operates on **Trajectory** objects — structured sequences of thought/action/observation steps with an outcome. Today, trajectories are constructed synthetically (tests, manual creation) or extracted in-memory from `AgentSession` objects that are discarded after execution.
-
-This creates three problems:
-
-1. **No durable session capture** — When an agent runs outside cognitive-core (e.g. Claude Code sessions, standalone CLI agents), there is no mechanism to ingest those sessions as trajectories. The richest source of learning data — real developer interactions — is lost.
-
-2. **No raw transcript preservation** — The `Trajectory` type is a lossy abstraction. It discards conversational context, partial reasoning, tool call timing, and multi-turn structure. Once converted, the original session is gone.
-
-3. **No session-level queries** — The existing `ExperienceMemory` stores compressed experience tuples. There is no way to ask "show me all sessions where the agent debugged a TypeScript error" at the raw session level, before lossy compression.
-
-### The Entire Opportunity
-
-[Entire](https://github.com/entireio/cli) is a Go CLI tool that captures full agent session transcripts via Claude Code (and Gemini CLI) hooks. It stores data on an orphan git branch (`entire/checkpoints/v1`), providing:
-
-- **Automatic capture** — 7 hook events: session-start, session-end, stop, user-prompt-submit, pre-task, post-task, post-todo
-- **Full fidelity** — JSONL transcripts preserve every message, tool call, and observation in the agent's native format
-- **Rich metadata** — token usage, file attribution, AI-generated summaries (intent, outcome, learnings, friction points)
-- **Git-native storage** — checkpoint-sharded orphan branch, pushed alongside your code
-- **Commit linking** — git trailers (`Entire-Checkpoint`, `Entire-Session`) bidirectionally link code commits to session data
-
-By using Entire as the capture and storage layer, cognitive-core gains a durable session archive without building its own capture infrastructure.
-
-### Standalone Package Philosophy
-
-The session bank is designed as a **standalone TypeScript package** (`@entire-sessions/reader` or similar) that can be used independently of cognitive-core. It reads from Entire's orphan branch and exposes a generic session query API. cognitive-core then adapts it via a thin `EntireTrajectorySource` implementing the existing `TrajectorySource` interface.
-
-This keeps the boundary clean:
-- **session-bank** knows about Entire's data format, not about Trajectories
-- **cognitive-core** knows about Trajectories, not about Entire's internals
-- The adapter is the only code that bridges the two
-
-## 2. Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     cognitive-core                               │
-│                                                                 │
-│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐       │
-│  │  Playbook    │  │  Experience  │  │  Knowledge Bank   │       │
-│  │  Library     │  │  Memory      │  │  (semantic)       │       │
-│  └──────┬──────┘  └──────┬───────┘  └───────┬───────────┘       │
-│         │                │                   │                   │
-│         │     ┌──────────┴──────────┐        │                   │
-│         └─────┤   Learning Pipeline ├────────┘                   │
-│               └─────────┬───────────┘                            │
-│                         │                                        │
-│               ┌─────────┴───────────┐                            │
-│               │ EntireTrajectory    │  ← adapter (in cognitive-  │
-│               │ Source              │     core, implements        │
-│               │                     │     TrajectorySource)       │
-│               └─────────┬───────────┘                            │
-│                         │                                        │
-└─────────────────────────┼────────────────────────────────────────┘
-                          │ uses
-┌─────────────────────────▼────────────────────────────────────────┐
-│               session-bank (standalone package)                   │
-│                                                                   │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
-│  │ EntireGit    │  │ Transcript   │  │ SessionBank           │   │
-│  │ Reader       │  │ Parser       │  │ (facade: discover,    │   │
-│  │ (git plumb)  │  │ (JSONL→types)│  │  query, get, count)   │   │
-│  └──────┬───────┘  └──────┬───────┘  └──────────┬────────────┘   │
-│         │                 │                      │               │
-│         └────────┬────────┘                      │               │
-│                  │ reads                          │ exposes       │
-│                  ▼                                ▼               │
-│         git show / ls-tree              SessionRecord[]          │
-└──────────────────┬───────────────────────────────────────────────┘
-                   │
-              reads from
-                   │
-       ┌───────────▼─────────────┐
-       │ entire/checkpoints/v1   │  (orphan branch)
-       │                         │
-       │ <id[:2]>/<id[2:]>/      │  checkpoint-sharded
-       │ ├── metadata.json       │  root summary
-       │ ├── 0/                  │  session subdirectory
-       │ │   ├── metadata.json   │  committed metadata
-       │ │   ├── full.jsonl      │  raw transcript
-       │ │   ├── prompt.txt      │  user prompts
-       │ │   └── context.md      │  generated context
-       │ └── tasks/              │  subagent checkpoints
-       └─────────────────────────┘
-```
-
-### Data Flow
-
-```
-1. Developer uses Claude Code (Entire hooks installed)
-         │
-         ▼
-2. Entire hooks fire on session events → capture to shadow branch
-         │
-         ▼
-3. Developer commits → post-commit hook condenses to entire/checkpoints/v1
-         │
-         ▼
-4. session-bank: SessionBank.discover() reads orphan branch via git plumbing
-         │
-         ▼
-5. session-bank: Parser converts JSONL → SessionRecord (with metadata, events, summary)
-         │
-         ▼
-6. cognitive-core: EntireTrajectorySource.load() calls SessionBank, synthesizes Trajectories
-         │
-         ▼
-7. cognitive-core: LearningPipeline.processTrajectory() → playbooks, experiences, knowledge
-```
-
-## 3. Entire's Real Storage Format
-
-Based on analysis of [`entireio/cli`](https://github.com/entireio/cli) source code.
-
-### Branch Structure
-
-Entire uses the `entire/checkpoints/v1` orphan branch. Checkpoints are **sharded by the first 2 hex chars** of the checkpoint ID (256 possible buckets):
-
-```
-entire/checkpoints/v1 branch tree:
-<checkpointId[:2]>/<checkpointId[2:]>/
-├── metadata.json              # CheckpointSummary (root-level, aggregated)
-├── 0/                         # First session subdirectory
-│   ├── metadata.json          # CommittedMetadata for this session
-│   ├── full.jsonl             # Complete transcript (Claude native JSONL)
-│   ├── prompt.txt             # Concatenated user prompts
-│   ├── context.md             # Generated context document
-│   └── content_hash.txt       # Deduplication hash
-├── 1/                         # Second session (if concurrent)
-│   └── ...
-└── tasks/                     # Task/subagent checkpoints (optional)
-    └── <tool-use-id>/
-        ├── checkpoint.json    # Task checkpoint metadata
-        ├── agent-<id>.jsonl   # Subagent transcript
-        └── checkpoints/
-            └── NNN-<id>.json  # Incremental checkpoints
-```
-
-### ID Formats
-
-- **Checkpoint ID**: 12 lowercase hex chars (e.g. `a3b2c4d5e6f7`), generated from 6 random bytes
-- **Session ID**: `YYYY-MM-DD-<UUID>` (e.g. `2026-01-08-abc123de-f456-7890-abcd-ef1234567890`)
-
-### Transcript Format (full.jsonl)
-
-Each line is Claude's native JSONL format:
-
-```jsonl
-{"type":"user","uuid":"abc123","message":{"content":"Fix the bug in auth.ts"}}
-{"type":"assistant","uuid":"def456","message":{"content":[{"type":"text","text":"I'll fix that..."},{"type":"tool_use","name":"Edit","input":{"file_path":"/src/auth.ts","old_string":"...","new_string":"..."}}]}}
-{"type":"user","uuid":"ghi789","message":{"content":[{"type":"tool_result","tool_use_id":"...","content":"File edited successfully"}]}}
-```
-
-The `message.content` is either:
-- A string (user text messages)
-- An array of `ContentBlock` objects (assistant responses with text + tool_use, or user messages with tool_results)
-
-Transcripts exceeding 50MB are chunked: `full.jsonl.001`, `full.jsonl.002`, etc.
-
-### Session Metadata (per-session metadata.json)
-
-```typescript
-// Entire's CommittedMetadata (Go struct → TypeScript equivalent)
-interface EntireCommittedMetadata {
-  cli_version: string;
-  checkpoint_id: string;              // 12-hex-char
-  session_id: string;                 // YYYY-MM-DD-<UUID>
-  strategy: 'manual-commit' | 'auto-commit';
-  created_at: string;                 // RFC3339
-  branch: string;                     // source code branch
-  files_touched: string[];            // files modified during session
-  agent: string;                      // "Claude Code", "Gemini CLI", etc.
-  is_task: boolean;
-  tool_use_id?: string;               // for task checkpoints
-  checkpoint_transcript_start: number; // line offset into JSONL
-  token_usage: EntireTokenUsage;
-  summary?: EntireSummary;            // AI-generated (optional)
-  initial_attribution?: EntireAttribution;
-}
-
-interface EntireTokenUsage {
-  input_tokens: number;
-  cache_creation_tokens: number;
-  cache_read_tokens: number;
-  output_tokens: number;
-  api_call_count: number;
-  subagent_usage?: EntireTokenUsage[];
-}
-
-interface EntireSummary {
-  intent: string;                     // What the user was trying to do
-  outcome: string;                    // What happened
-  learnings: {
-    repo_patterns: string[];          // Repository-specific patterns
-    code_findings: string[];          // Code-specific findings
-    workflow_practices: string[];     // Workflow learnings
-  };
-  friction_points: string[];          // Where things went wrong
-  open_items: string[];               // Unfinished work
-}
-
-interface EntireAttribution {
-  agent_lines_added: number;
-  human_additions: number;
-  human_modifications: number;
-  human_removals: number;
-  total_committed_lines: number;
-  agent_contribution: number;         // 0-1 percentage
-}
-```
-
-### Root Checkpoint Summary (root metadata.json)
-
-```typescript
-interface EntireCheckpointSummary {
-  sessions: Array<{
-    metadata: string;      // path: "0/metadata.json"
-    transcript: string;    // path: "0/full.jsonl"
-    context: string;       // path: "0/context.md"
-    content_hash: string;  // path: "0/content_hash.txt"
-    prompt: string;        // path: "0/prompt.txt"
-  }>;
-}
-```
-
-### Commit Trailers
-
-Entire writes trailers into user git commits for bidirectional linking:
-
-```
-Entire-Checkpoint: a3b2c4d5e6f7
-Entire-Session: 2026-01-08-abc123de-f456-7890-abcd-ef1234567890
-Entire-Strategy: manual-commit
-```
-
-## 4. Standalone Package: Type Definitions
-
-These types are defined by the session-bank package — they represent parsed, normalized Entire data. They are deliberately **not** cognitive-core types.
-
-### SessionRecord — The Core Type
-
-```typescript
-/**
- * A parsed Entire checkpoint session — the primary data type exposed
- * by the session bank. Contains the full transcript, metadata, and
- * Entire's AI-generated summary.
- *
- * This is the intermediate representation between Entire's raw files
- * on the orphan branch and any downstream consumer (cognitive-core,
- * analytics, UI, etc.).
- */
-export interface SessionRecord {
-  /** Entire session ID (YYYY-MM-DD-<UUID>) */
-  sessionId: string;
-
-  /** Entire checkpoint ID (12-hex-char) */
-  checkpointId: string;
-
-  /** Parsed metadata from per-session metadata.json */
-  metadata: SessionMetadata;
-
-  /** Parsed transcript events from full.jsonl */
-  transcript: TranscriptMessage[];
-
-  /** AI-generated summary (from Entire's summarize feature, if enabled) */
-  summary?: SessionSummary;
-
-  /** Token usage statistics */
-  tokenUsage: TokenUsage;
-
-  /** Line-level code attribution */
-  attribution?: Attribution;
-
-  /** Provenance: where this data came from on the orphan branch */
-  source: SessionSource;
-}
-
-export interface SessionMetadata {
-  /** Entire CLI version that captured this */
-  cliVersion: string;
-  /** Checkpoint strategy used */
-  strategy: 'manual-commit' | 'auto-commit';
-  /** When the checkpoint was created */
-  createdAt: Date;
-  /** Source code branch the session was on */
-  branch: string;
-  /** Agent that ran the session */
-  agent: string;
-  /** Working directory (if available from context) */
-  cwd?: string;
-  /** Files modified during the session */
-  filesTouched: string[];
-  /** Whether this is a task (subagent) checkpoint */
-  isTask: boolean;
-  /** Tool use ID (for task checkpoints) */
-  toolUseId?: string;
-}
-
-export interface TranscriptMessage {
-  /** Message role */
-  role: 'user' | 'assistant';
-  /** Unique message identifier */
-  uuid: string;
-  /** Content blocks */
-  content: ContentBlock[];
-  /** Computed: index in original JSONL */
-  lineIndex: number;
-}
-
-export type ContentBlock =
-  | TextBlock
-  | ToolUseBlock
-  | ToolResultBlock;
-
-export interface TextBlock {
-  type: 'text';
-  text: string;
-}
-
-export interface ToolUseBlock {
-  type: 'tool_use';
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-
-export interface ToolResultBlock {
-  type: 'tool_result';
-  toolUseId: string;
-  content: string;
-  isError?: boolean;
-}
-
-export interface SessionSummary {
-  /** What the user was trying to accomplish */
-  intent: string;
-  /** What actually happened */
-  outcome: string;
-  /** Learnings from the session */
-  learnings: {
-    repoPatterns: string[];
-    codeFindings: string[];
-    workflowPractices: string[];
-  };
-  /** Where things went wrong or caused friction */
-  frictionPoints: string[];
-  /** Unfinished work or follow-ups */
-  openItems: string[];
-}
-
-export interface TokenUsage {
-  inputTokens: number;
-  cacheCreationTokens: number;
-  cacheReadTokens: number;
-  outputTokens: number;
-  apiCallCount: number;
-  subagentUsage?: TokenUsage[];
-  /** Computed: total tokens across all categories */
-  total: number;
-}
-
-export interface Attribution {
-  agentLinesAdded: number;
-  humanAdditions: number;
-  humanModifications: number;
-  humanRemovals: number;
-  totalCommittedLines: number;
-  /** 0-1 percentage of agent contribution */
-  agentContribution: number;
-}
-
-export interface SessionSource {
-  /** Orphan branch name */
-  branch: string;
-  /** Path on branch: "<id[:2]>/<id[2:]>" */
-  checkpointPath: string;
-  /** Session subdirectory index: "0", "1", etc. */
-  sessionIndex: string;
-  /** Git commit SHA on the orphan branch containing this data */
-  commitSha?: string;
-  /** Git commit SHA on the source branch linked via Entire-Checkpoint trailer */
-  linkedCommitSha?: string;
-}
-```
-
-### SessionQuery — Query Interface
-
-```typescript
-/**
- * Query options for filtering sessions in the bank.
- */
-export interface SessionQuery {
-  /** Only checkpoints created after this date */
-  since?: Date;
-  /** Only checkpoints created before this date */
-  before?: Date;
-  /** Filter by source code branch (exact match) */
-  branch?: string;
-  /** Filter by agent type (e.g. "Claude Code") */
-  agent?: string;
-  /** Full-text search across user messages */
-  search?: string;
-  /** Filter by checkpoint strategy */
-  strategy?: 'manual-commit' | 'auto-commit';
-  /** Only include sessions with/without summaries */
-  hasSummary?: boolean;
-  /** Maximum number of sessions to return */
-  limit?: number;
-  /** Sort order (default: newest first) */
-  sort?: 'newest' | 'oldest';
-  /** Only sessions not yet marked as processed */
-  unprocessedOnly?: boolean;
-}
-
-export interface SessionQueryResult {
-  sessions: SessionRecord[];
-  total: number;
-}
-```
-
-### CheckpointRef — Lightweight Reference
-
-```typescript
-/**
- * Lightweight reference to a checkpoint, for enumeration without
- * loading full transcripts.
- */
-export interface CheckpointRef {
-  checkpointId: string;
-  sessionIds: string[];
-  path: string;
-  /** Available without loading full metadata */
-  sessionCount: number;
-}
-```
-
-## 5. Standalone Package: Core Components
-
-### 5.1 EntireGitReader
-
-Low-level git plumbing for reading from the orphan branch without checkout.
-
-```typescript
-export class EntireGitReader {
-  constructor(options: { repoPath: string; branch?: string });
-
-  /** Check if the orphan branch exists in this repo */
-  async branchExists(): Promise<boolean>;
-
-  /**
-   * List all checkpoint directories (top-level shard + inner dirs).
-   * Returns paths like ["a3/b2c4d5e6f7", "f1/0a9b8c7d6e5f", ...]
-   */
-  async listCheckpoints(): Promise<string[]>;
-
-  /**
-   * List session subdirectories within a checkpoint.
-   * Returns ["0", "1", ...] (numeric session indices)
-   */
-  async listSessions(checkpointPath: string): Promise<string[]>;
-
-  /** Read a single file from the orphan branch */
-  async readFile(path: string): Promise<string>;
-
-  /**
-   * Read multiple files in batch (minimizes git process spawns).
-   * Returns Map<path, content>. Missing files are omitted.
-   */
-  async readFiles(paths: string[]): Promise<Map<string, string>>;
-
-  /**
-   * Read a file, returning null if it doesn't exist (no throw).
-   */
-  async readFileOrNull(path: string): Promise<string | null>;
-
-  /**
-   * Get the HEAD commit SHA of the orphan branch.
-   * Useful for cache invalidation.
-   */
-  async getBranchHead(): Promise<string | null>;
-}
-```
-
-**Implementation:**
-
-```bash
-# Branch existence
-git rev-parse --verify entire/checkpoints/v1
-
-# List shard directories (top-level: "a3", "f1", etc.)
-git ls-tree --name-only entire/checkpoints/v1
-
-# List checkpoints within a shard
-git ls-tree --name-only entire/checkpoints/v1 a3/
-
-# List session subdirs within a checkpoint
-git ls-tree --name-only entire/checkpoints/v1 a3/b2c4d5e6f7/
-
-# Read a file
-git show entire/checkpoints/v1:a3/b2c4d5e6f7/0/metadata.json
-
-# Batch read (single git process via cat-file --batch)
-echo "entire/checkpoints/v1:a3/b2c4d5e6f7/0/metadata.json" | git cat-file --batch
-```
-
-### 5.2 EntireTranscriptParser
-
-Parses Entire's raw files into `SessionRecord` objects.
-
-```typescript
-export class EntireTranscriptParser {
-  /**
-   * Parse a full session from its component files.
-   */
-  parseSession(
-    metadataJson: string,
-    transcriptJsonl: string,
-    checkpointPath: string,
-    sessionIndex: string
-  ): SessionRecord;
-
-  /**
-   * Parse just the per-session metadata (fast path for listing).
-   */
-  parseMetadata(metadataJson: string): SessionMetadata & {
-    sessionId: string;
-    checkpointId: string;
-    summary?: SessionSummary;
-    tokenUsage: TokenUsage;
-    attribution?: Attribution;
-  };
-
-  /**
-   * Parse a JSONL transcript into structured messages.
-   * Handles Claude's native JSONL format:
-   *   {"type":"user"|"assistant", "uuid":"...", "message":{...}}
-   *
-   * Tolerant of malformed lines (skips with warning).
-   */
-  parseTranscript(jsonlContent: string): TranscriptMessage[];
-
-  /**
-   * Parse chunked transcripts (full.jsonl.001, .002, etc.)
-   * by concatenating chunks before parsing.
-   */
-  parseChunkedTranscript(chunks: string[]): TranscriptMessage[];
-
-  /**
-   * Parse the root checkpoint summary to discover session subdirectories.
-   */
-  parseCheckpointSummary(metadataJson: string): CheckpointRef;
-}
-```
-
-**JSONL parsing details:**
-
-Each line in Entire's transcript follows Claude's format:
-
-```typescript
-// Raw JSONL line shape
-interface RawTranscriptLine {
-  type: 'user' | 'assistant';
-  uuid: string;
-  message: {
-    content: string | RawContentBlock[];
-  };
-}
-
-interface RawContentBlock {
-  type: 'text' | 'tool_use' | 'tool_result';
-  text?: string;          // for type === 'text'
-  name?: string;          // for type === 'tool_use'
-  input?: Record<string, unknown>; // for type === 'tool_use'
-  tool_use_id?: string;   // for type === 'tool_result'
-  content?: string;       // for type === 'tool_result'
-}
-```
-
-The parser normalizes this into `TranscriptMessage` with typed `ContentBlock` discriminated union. String content is wrapped into `[{ type: 'text', text: content }]` for consistency.
-
-### 5.3 SessionBank — Main Facade
-
-```typescript
-export class SessionBank {
-  constructor(options?: SessionBankOptions);
-
-  /**
-   * Initialize: verify orphan branch exists, optionally build index.
-   * @throws if repoPath is not a git repository
-   */
-  async init(): Promise<void>;
-
-  /** Whether the Entire orphan branch exists in this repo */
-  isAvailable(): boolean;
-
-  // ── Discovery ──────────────────────────────────────────────
-
-  /**
-   * List all checkpoint references without loading transcripts.
-   * Fast: only reads directory listings and root metadata.json files.
-   */
-  async listCheckpoints(): Promise<CheckpointRef[]>;
-
-  /**
-   * Discover all sessions across all checkpoints.
-   * Loads metadata but NOT transcripts (lazy loading).
-   */
-  async discover(): Promise<SessionRecord[]>;
-
-  /**
-   * Count sessions matching a query.
-   */
-  async count(query?: SessionQuery): Promise<number>;
-
-  // ── Querying ───────────────────────────────────────────────
-
-  /**
-   * Query sessions with filtering and sorting.
-   * Loads full transcripts only for matching sessions.
-   */
-  async query(query?: SessionQuery): Promise<SessionQueryResult>;
-
-  /**
-   * Get a single session by session ID.
-   * Searches across all checkpoints.
-   */
-  async getBySessionId(sessionId: string): Promise<SessionRecord | undefined>;
-
-  /**
-   * Get all sessions within a specific checkpoint.
-   */
-  async getByCheckpointId(checkpointId: string): Promise<SessionRecord[]>;
-
-  /**
-   * Find the session(s) linked to a specific git commit.
-   * Uses git log to find Entire-Checkpoint trailers.
-   */
-  async getByCommit(commitSha: string): Promise<SessionRecord[]>;
-
-  // ── Processing Tracking ────────────────────────────────────
-
-  /**
-   * Mark a session as processed by an external consumer.
-   * Tracked in a local state file to avoid re-processing.
-   */
-  async markProcessed(
-    sessionId: string,
-    metadata?: Record<string, unknown>
-  ): Promise<void>;
-
-  /** Check if a session has been marked as processed */
-  isProcessed(sessionId: string): boolean;
-
-  /** Get all processing log entries */
-  getProcessingLog(): ProcessingLogEntry[];
-
-  // ── Cache Management ───────────────────────────────────────
-
-  /**
-   * Invalidate cached data (forces re-read from git on next query).
-   * Called automatically when orphan branch HEAD changes.
-   */
-  invalidateCache(): void;
-
-  // ── Lifecycle ──────────────────────────────────────────────
-
-  async close(): Promise<void>;
-}
-
-export interface SessionBankOptions {
-  /** Git repository path (default: process.cwd()) */
-  repoPath?: string;
-  /** Orphan branch name (default: 'entire/checkpoints/v1') */
-  branch?: string;
-  /** Directory to store processing state (default: '.atlas/session-bank') */
-  stateDir?: string;
-  /** Enable in-memory caching of parsed sessions */
-  cache?: boolean;
-}
-
-export interface ProcessingLogEntry {
-  sessionId: string;
-  processedAt: Date;
-  metadata?: Record<string, unknown>;
-}
-```
-
-### Lazy Loading Strategy
-
-The session bank uses a two-tier loading approach:
-
-1. **Metadata-only (fast)**: `listCheckpoints()` and `discover()` read only `metadata.json` files. This is fast because it avoids parsing potentially large JSONL transcripts.
-
-2. **Full load (on demand)**: `query()`, `getBySessionId()`, `getByCheckpointId()` load the full `full.jsonl` transcript. The transcript is parsed lazily — only when a query actually matches.
-
-This matters because JSONL transcripts can be large (Entire chunks at 50MB).
-
-## 6. cognitive-core Adapter: EntireTrajectorySource
-
-This lives in cognitive-core, not in the standalone package. It adapts `SessionRecord` into `Trajectory`.
-
-```typescript
-// src/learning/trajectory-sources/entire.ts
-
-import type { SessionRecord, SessionBank } from '@entire-sessions/reader';
-import type {
-  TrajectorySource,
-  TrajectoryWithAnalysis,
-  TrajectoryLoadOptions,
-} from '../../types/trajectory-source.js';
-import type { Trajectory, Step, Task, Outcome } from '../../types/index.js';
-
-export interface EntireSynthesisOptions {
-  /** Domain to assign (default: inferred from branch/files) */
-  domain?: string;
-  /** How to determine success/failure (default: 'summary') */
-  outcomeStrategy?: 'summary' | 'heuristic' | 'llm';
-}
-
-export class EntireTrajectorySource implements TrajectorySource {
-  readonly name = 'entire';
-
-  constructor(
-    private sessionBank: SessionBank,
-    private options?: EntireSynthesisOptions
-  ) {}
-
-  async load(options?: TrajectoryLoadOptions): Promise<TrajectoryWithAnalysis[]> {
-    const result = await this.sessionBank.query({
-      since: options?.since,
-      limit: options?.limit,
-      unprocessedOnly: false,
-    });
-
-    return result.sessions
-      .map(session => {
-        try {
-          return {
-            trajectory: this.synthesize(session),
-            analysis: undefined, // consumer computes this
-          };
-        } catch {
-          return null;
-        }
-      })
-      .filter((t): t is TrajectoryWithAnalysis => t !== null)
-      .filter(t => {
-        if (options?.domain && t.trajectory.task.domain !== options.domain) return false;
-        if (options?.successOnly && !t.trajectory.outcome.success) return false;
-        return true;
-      });
-  }
-
-  async count(options?: TrajectoryLoadOptions): Promise<number> {
-    return this.sessionBank.count({
-      since: options?.since,
-      limit: options?.limit,
-    });
-  }
-
-  /**
-   * Convert an Entire SessionRecord into a cognitive-core Trajectory.
-   */
-  synthesize(session: SessionRecord): Trajectory {
-    return {
-      id: `entire-${session.checkpointId}-${session.sessionId}`,
-      task: this.extractTask(session),
-      steps: this.extractSteps(session),
-      outcome: this.inferOutcome(session),
-      agentId: session.metadata.agent,
-      timestamp: session.metadata.createdAt,
-      llmCalls: session.tokenUsage.apiCallCount,
-      totalTokens: session.tokenUsage.total,
-      wallTimeSeconds: 0, // not available from metadata alone
-      metadata: {
-        source: 'entire',
-        checkpointId: session.checkpointId,
-        sessionId: session.sessionId,
-        branch: session.metadata.branch,
-        filesTouched: session.metadata.filesTouched,
-        strategy: session.metadata.strategy,
-        attribution: session.attribution,
-      },
-    };
-  }
-
-  // ── Private helpers ──────────────────────────────────────
-
-  private extractTask(session: SessionRecord): Task {
-    // Prefer Entire's summary intent over raw first message
-    const description = session.summary?.intent
-      ?? this.getFirstUserMessage(session)
-      ?? 'Unknown task';
-
-    return {
-      id: `task-${session.sessionId}`,
-      domain: this.options?.domain ?? this.inferDomain(session),
-      description,
-      context: {
-        filesTouched: session.metadata.filesTouched,
-        branch: session.metadata.branch,
-      },
-      metadata: {},
-      createdAt: session.metadata.createdAt,
-    };
-  }
-
-  private extractSteps(session: SessionRecord): Step[] {
-    const steps: Step[] = [];
-
-    for (const msg of session.transcript) {
-      if (msg.role !== 'assistant') continue;
-
-      // Extract text blocks as thought
-      const textBlocks = msg.content.filter(b => b.type === 'text');
-      const thought = textBlocks.map(b => (b as { text: string }).text).join('\n');
-
-      // Extract tool_use blocks as actions
-      const toolBlocks = msg.content.filter(b => b.type === 'tool_use');
-
-      if (toolBlocks.length === 0) {
-        // Pure reasoning step (no tool calls)
-        if (thought) {
-          steps.push({
-            thought,
-            action: '',
-            observation: '',
-            timestamp: session.metadata.createdAt, // approximation
-            metadata: { messageUuid: msg.uuid },
-          });
-        }
-      } else {
-        // One step per tool call, sharing the thought
-        for (const tool of toolBlocks) {
-          const t = tool as { name: string; id: string; input: Record<string, unknown> };
-          const observation = this.findToolResult(session.transcript, t.id);
-
-          steps.push({
-            thought: steps.length === 0 || thought ? thought : undefined,
-            action: `${t.name}(${JSON.stringify(t.input)})`,
-            observation: observation ?? '',
-            timestamp: session.metadata.createdAt,
-            metadata: {
-              messageUuid: msg.uuid,
-              toolName: t.name,
-              toolUseId: t.id,
-            },
-          });
-        }
-      }
-    }
-
-    return steps;
-  }
-
-  private inferOutcome(session: SessionRecord): Outcome {
-    const strategy = this.options?.outcomeStrategy ?? 'summary';
-
-    if (strategy === 'summary' && session.summary) {
-      // Use Entire's AI-generated outcome
-      const outcome = session.summary.outcome.toLowerCase();
-      const success = !outcome.includes('fail') &&
-                      !outcome.includes('error') &&
-                      !outcome.includes('unable') &&
-                      !outcome.includes('could not');
-      return {
-        success,
-        partialScore: success ? 1.0 : 0.0,
-        verificationDetails: {
-          entireOutcome: session.summary.outcome,
-          frictionPoints: session.summary.frictionPoints,
-          openItems: session.summary.openItems,
-        },
-      };
-    }
-
-    // Heuristic fallback
-    const hasFiles = session.metadata.filesTouched.length > 0;
-    return {
-      success: hasFiles, // if files were touched, something was accomplished
-      partialScore: hasFiles ? 0.7 : 0.3,
-      verificationDetails: { strategy: 'heuristic' },
-    };
-  }
-
-  private inferDomain(session: SessionRecord): string {
-    const files = session.metadata.filesTouched;
-    if (files.some(f => f.match(/\.(test|spec)\.(ts|js|tsx|jsx)$/))) return 'testing';
-    if (files.some(f => f.match(/\.(ts|tsx)$/))) return 'typescript';
-    if (files.some(f => f.match(/\.(py)$/))) return 'python';
-    if (files.some(f => f.match(/\.(go)$/))) return 'go';
-    if (files.some(f => f.match(/\.(rs)$/))) return 'rust';
-    return 'code';
-  }
-
-  private getFirstUserMessage(session: SessionRecord): string | undefined {
-    const firstUser = session.transcript.find(m => m.role === 'user');
-    if (!firstUser) return undefined;
-    const textBlock = firstUser.content.find(b => b.type === 'text');
-    return textBlock ? (textBlock as { text: string }).text : undefined;
-  }
-
-  private findToolResult(
-    messages: SessionRecord['transcript'],
-    toolUseId: string
-  ): string | undefined {
-    for (const msg of messages) {
-      if (msg.role !== 'user') continue;
-      for (const block of msg.content) {
-        if (block.type === 'tool_result' && (block as { toolUseId: string }).toolUseId === toolUseId) {
-          return (block as { content: string }).content;
-        }
-      }
-    }
-    return undefined;
-  }
-}
-```
-
-### Key Synthesis Decisions
-
-| Decision | Approach | Rationale |
-|----------|----------|-----------|
-| Task description | Use `summary.intent` (prefer) or first user message | Entire's AI summary produces cleaner task descriptions than raw prompts |
-| Outcome | Use `summary.outcome` keywords | Entire already runs outcome analysis; avoids duplicate LLM call |
-| Domain | Infer from `filesTouched` extensions | Simple heuristic; can be overridden via options |
-| Step grouping | One step per tool_use, shared thought | Matches ReAct format; preserves tool-level granularity |
-| Token count | Use `tokenUsage.total` directly | Entire captures real API usage, no need to estimate |
-| Trajectory ID | `entire-{checkpointId}-{sessionId}` | Globally unique, traceable back to source |
-
-## 7. cognitive-core Integration
-
-### Config Addition
-
-```typescript
-// Add to AtlasConfigSchema
-const SessionBankConfigSchema = z.object({
-  /** Enable session bank integration */
-  enabled: z.boolean().default(false),
-  /** Orphan branch name */
-  branch: z.string().default('entire/checkpoints/v1'),
-  /** State directory (relative to storage.baseDir) */
-  stateDir: z.string().default('session-bank'),
-  /** Default outcome strategy for synthesis */
-  outcomeStrategy: z.enum(['summary', 'heuristic', 'llm']).default('summary'),
-  /** Auto-ingest unprocessed sessions on init */
-  autoIngest: z.boolean().default(false),
-  /** Maximum sessions per auto-ingest batch */
-  maxIngestBatch: z.number().default(20),
-});
-```
-
-### Atlas Integration
-
-```typescript
-class Atlas {
-  // Existing...
-
-  getSessionBank(): SessionBank | null;
-
-  /**
-   * Ingest unprocessed Entire sessions into the learning pipeline.
-   * Each session is: parsed → synthesized to Trajectory → processTrajectory()
-   */
-  async ingestEntireSessions(options?: {
-    limit?: number;
-    domain?: string;
-    outcomeStrategy?: 'summary' | 'heuristic' | 'llm';
-  }): Promise<IngestResult>;
-}
-```
-
-### Ingestion Flow (inside Atlas)
-
-```typescript
-async ingestEntireSessions(options) {
-  const bank = this.getSessionBank();
-  if (!bank) throw new Error('Session bank not enabled');
-
-  const source = new EntireTrajectorySource(bank, {
-    domain: options?.domain,
-    outcomeStrategy: options?.outcomeStrategy,
-  });
-
-  const sessions = await bank.query({
-    unprocessedOnly: true,
-    limit: options?.limit ?? this.config.sessionBank.maxIngestBatch,
-  });
-
-  const results = [];
-  for (const session of sessions.sessions) {
-    try {
-      const trajectory = source.synthesize(session);
-      const processResult = await this.processTrajectory(trajectory);
-      await bank.markProcessed(session.sessionId, {
-        trajectoryId: trajectory.id,
-      });
-      results.push({ sessionId: session.sessionId, trajectoryId: trajectory.id, success: true });
-    } catch (error) {
-      results.push({ sessionId: session.sessionId, success: false, error: String(error) });
-    }
-  }
-
-  return { discovered: sessions.total, ingested: results.filter(r => r.success).length, ... };
-}
-```
-
-## 8. Package Structure
-
-### Standalone Package
-
-```
-session-bank/                          # standalone npm package
-├── package.json                       # @entire-sessions/reader (or similar)
-├── tsconfig.json
-├── src/
-│   ├── index.ts                       # Barrel: SessionBank, types, parser
-│   ├── session-bank.ts                # SessionBank class
-│   ├── git-reader.ts                  # EntireGitReader
-│   ├── parser.ts                      # EntireTranscriptParser
-│   └── types.ts                       # SessionRecord, SessionQuery, etc.
-└── tests/
-    ├── fixtures/                       # Sample JSONL + metadata files
-    │   ├── simple-session/
-    │   │   ├── metadata.json
-    │   │   └── full.jsonl
-    │   └── multi-tool-session/
-    │       ├── metadata.json
-    │       └── full.jsonl
-    ├── parser.test.ts
-    ├── git-reader.test.ts
-    └── session-bank.test.ts
-```
-
-### cognitive-core Additions
-
-```
-src/
-├── learning/
-│   └── trajectory-sources/
-│       ├── entire.ts                  # EntireTrajectorySource (NEW)
-│       └── index.ts                   # Updated barrel
-└── types/
-    └── config.ts                      # SessionBankConfigSchema addition
-```
-
-## 9. Implementation Plan
-
-### Phase 1: Standalone Reader (session-bank package)
-- `EntireGitReader` — git plumbing, branch existence, file reading
-- `EntireTranscriptParser` — JSONL parsing, metadata parsing, chunked transcripts
-- Types (`SessionRecord`, `TranscriptMessage`, `ContentBlock`, etc.)
-- Unit tests with real Entire fixture data
-
-### Phase 2: Session Bank Facade
-- `SessionBank` class — discover, query, get, count
-- Lazy loading (metadata-first, transcript-on-demand)
-- Processing log persistence
-- Cache invalidation via orphan branch HEAD comparison
-
-### Phase 3: cognitive-core Adapter
-- `EntireTrajectorySource` implementing `TrajectorySource`
-- `synthesize()` — SessionRecord → Trajectory conversion
-- ReAct step grouping, outcome inference (summary-based + heuristic)
-- `SessionBankConfigSchema` addition to `AtlasConfig`
-- `Atlas.ingestEntireSessions()` integration
-
-### Phase 4: Polish
-- Commit-linked queries (`getByCommit()` via trailer parsing)
-- `search` filter (full-text across user messages)
-- Task/subagent checkpoint support
-- Error tolerance for corrupt/partial data
-- Integration test against a real Entire-enabled repo
-
-## 10. Design Decisions
-
-### Why a standalone package?
-
-The session bank reads Entire's data format — it doesn't need cognitive-core's Trajectory type, learning pipeline, or memory system. Keeping it standalone means:
-- Entire's data can be consumed by other tools (analytics, dashboards, review UIs)
-- The package has zero dependencies beyond Node.js built-ins
-- Testing is simpler (no cognitive-core setup needed)
-- cognitive-core's `EntireTrajectorySource` adapter is a thin 100-line bridge
-
-### Why `summary.intent` over first user message for task description?
-
-Entire's AI-generated summaries distill multi-turn sessions into coherent task descriptions. The first user message might be "fix this" with no context. The summary's `intent` field is "Fix the authentication token refresh bug in the middleware" — much better for learning.
-
-### Why `summary`-based outcome inference by default?
-
-Entire already runs an LLM to generate session summaries with an `outcome` field. Using this avoids a duplicate LLM call during ingestion. The summary-based strategy examines the outcome text for failure indicators — this is nearly as accurate as a dedicated outcome classifier, at zero additional cost.
-
-### Why checkpoint-indexed, not session-indexed?
-
-Entire's storage is organized by checkpoint ID, not session ID. A single checkpoint can contain multiple concurrent sessions. The session bank follows this structure rather than fighting it — `getByCheckpointId()` returns all sessions in a checkpoint, while `getBySessionId()` searches across checkpoints.
-
-### Why processing log rather than modifying Entire's data?
-
-The session bank never writes to the orphan branch. Processing state is kept in a local file (`.atlas/session-bank/processed.json`). This means:
-- Multiple consumers can independently track their own processing state
-- Entire's data stays immutable and authoritative
-- No risk of corrupting the orphan branch
-
-## 11. Entire Features We Leverage
-
-| Entire Feature | How We Use It |
-|---|---|
-| `summary.intent` | Task description for Trajectory |
-| `summary.outcome` | Outcome inference (success/failure) |
-| `summary.learnings` | Candidate knowledge notes for KnowledgeBank |
-| `summary.friction_points` | Anti-pattern identification for playbooks |
-| `files_touched` | Domain inference, file-level context |
-| `token_usage` | Direct `totalTokens` on Trajectory (no estimation) |
-| `initial_attribution` | Code contribution metrics for meta-learning |
-| `Entire-Checkpoint` trailers | Commit↔session linking |
-| Checkpoint sharding | Efficient git tree enumeration |
-| Transcript chunking | Handle large sessions (>50MB) gracefully |
-
-## 12. Future Extensions
-
-- **Learnings → KnowledgeBank pipeline** — `summary.learnings` maps directly to KnowledgeBank observations; auto-extract without re-analyzing the transcript
-- **Friction → anti-pattern extraction** — `summary.friction_points` can seed `playbook.applicability.antiPatterns`
-- **Attribution-weighted learning** — weight trajectory importance by `agentContribution` score; sessions where the human did most of the work may be less useful for agent learning
-- **Cross-repo federation** — aggregate session banks from multiple repos into a shared learning corpus
-- **Incremental sync** — track orphan branch commit SHA; only re-scan checkpoints added since last sync
-- **Gemini CLI support** — Entire captures Gemini sessions too; parser can be extended to handle Gemini's JSON format alongside Claude's JSONL