cognitive-core 0.0.2 → 0.1.2

package/docs/PLAN-graph-migration.md

@@ -0,0 +1,299 @@
+# Plan: Migrate TeamTrajectory to Graph-Based Model
+
+## Strategy: Additive Migration
+
+Rather than a breaking rewrite, we add graph fields alongside the existing flat fields,
+then migrate consumers one at a time. This keeps all 726 tests passing at each step.
+
+```
+Phase 1: Add graph types + optional fields on TeamTrajectory
+Phase 2: Update builder + ingester to populate graph data
+Phase 3: Migrate consumers to prefer graph data when available
+Phase 4: Update analysis template to leverage per-step data
+Phase 5: Update tests + cleanup
+```
+
+---
+
+## Current vs Target Shape
+
+```
+CURRENT (flat)                          TARGET (graph)
+─────────────────────────              ─────────────────────────
+events: TeamEvent[]                    members: MemberTrajectory[]
+interactionGraph: InteractionEdge[]    interactions: AgentInteraction[]
+memberOutcomes: MemberOutcome[]        structuralMetrics: StructuralMetrics
+metrics: CoordinationMetrics           expectedPatterns: ExpectedInteractionPattern[]
+```
+
+After migration, TeamTrajectory will have BOTH sets of fields:
+- Graph fields (`members`, `interactions`, `structuralMetrics`) — primary, always populated
+- Flat fields (`events`, `interactionGraph`, `memberOutcomes`, `metrics`) — derived, kept for backward compat
+
+---
+
+## Phase 1: Add Graph Types to TeamTrajectory
+
+**File: `src/types/team-trajectory.ts`**
+
+Add new interfaces:
+```typescript
+interface MemberTrajectory {
+  agentId: string;
+  role: string;
+  trajectory: Trajectory;  // existing type, unchanged
+}
+
+interface AgentInteraction {
+  id: string;
+  type: InteractionType;
+  from: { agentId: string; role: string; stepIndex: number };
+  to:   { agentId: string; role: string; stepIndex: number };
+  content: string;
+  channel?: string;
+  signal?: string;
+  timestamp: Date;
+  latencyMs?: number;
+  wasExpected: boolean;
+}
+
+interface StructuralMetrics {
+  teamSize: number;
+  totalSteps: number;
+  totalInteractions: number;
+  interactionDensity: number;
+  maxInDegree: { agentId: string; count: number };
+  maxOutDegree: { agentId: string; count: number };
+  parallelismRatio: number;
+  totalWallTimeSeconds: number;
+  totalTokens: number;
+}
+```
+
+Add optional graph fields to `TeamTrajectory`:
+```typescript
+interface TeamTrajectory {
+  // ... existing fields stay ...
+
+  // === GRAPH DATA (new, primary) ===
+  /** Full per-agent trajectories (graph nodes) */
+  members?: MemberTrajectory[];
+  /** Step-level interactions between agents (graph edges) */
+  interactions?: AgentInteraction[];
+  /** Graph-level structural metrics */
+  structuralMetrics?: StructuralMetrics;
+}
+```
+
+**File: `src/types/index.ts`** — export new types
+
+No consumer changes. All tests pass unchanged.
+
+---
+
+## Phase 2: Update Builder + Ingester
+
+### 2a: Update `buildTeamTrajectory()`
+
+**File: `src/types/team-trajectory.ts`**
+
+The existing `buildTeamTrajectory(input: TeamTrajectoryInput)` already receives
+`memberTrajectories` with full `Trajectory` objects. Currently it discards them
+after extracting events/outcomes. Update to preserve them:
+
+- Store `input.memberTrajectories` as `members` on the output
+- Build `AgentInteraction[]` from `InteractionTag` step metadata (alongside existing `InteractionEdge[]`)
+- Compute `StructuralMetrics` from the graph data
+
+### 2b: Update `TeamTrajectoryIngester`
+
+**File: `src/learning/team-ingester.ts`**
+
+Currently the ingester only works with `events[]` and `interactionGraph[]`.
+Update to use `members[]` and `interactions[]` when available:
+
+- `computeStructuralMetrics()`: use `members` for per-agent step counts, `interactions` for degree analysis
+- `scoreSteps()`: score actual trajectory steps (not just events). Use step content for richer scoring
+- `scoreInteractions()`: score `AgentInteraction` objects with downstream success, latency penalty, etc.
+- New: `compressTrajectories()`: fold internal steps between interaction boundaries
+
+Add `CriticalStep` type (scores on actual `Step` objects, not events):
+```typescript
+interface CriticalStep {
+  agentId: string;
+  role: string;
+  stepIndex: number;
+  step: Step;
+  scores: { promise: number; progress: number; interactionBonus: number; total: number };
+}
+
+interface CriticalInteraction {
+  interaction: AgentInteraction;
+  scores: { downstreamSuccess: number; latencyPenalty: number; expectedBonus: number; informationDensity: number; total: number };
+}
+```
+
+Update `IngestionResult` to include these:
+```typescript
+interface IngestionResult {
+  teamTrajectory: TeamTrajectory;
+  structuralMetrics: StructuralMetrics;  // now from graph data when available
+  criticalSteps: CriticalStep[];          // updated type
+  criticalInteractions: CriticalInteraction[];  // updated type
+  compressionStats: { ... };
+}
+```
+
+**Backward compat**: When `members` is not present, fall back to existing event-based scoring.
+
+---
+
+## Phase 3: Migrate Consumers to Prefer Graph Data
+
+Each consumer is updated to check `trajectory.members` and use graph data when available,
+falling back to flat fields otherwise. This is done one file at a time.
+
+### 3a: `team-pipeline.ts`
+
+Meta-observation building currently uses `memberOutcomes` for role utilization.
+Update to compute from `members[].trajectory.outcome` when available, providing
+richer data (actual completion rate from step outcomes vs aggregate task counts).
+
+### 3b: `team-meta-learner.ts`
+
+`generateReflection()` uses `memberOutcomes` for redundancy detection and
+`metrics` for parallelism/overhead. Update to:
+- Compute role utilization from `members[].trajectory` step completion
+- Detect redundancy from token usage across actual steps
+- Use `structuralMetrics` when available
+
+### 3c: `team-playbook-extraction.ts`
+
+Heuristic extraction groups by topology and extracts common roles.
+Update to also extract interaction patterns from `interactions[]`:
+- Identify common interaction sequences across successful executions
+- Populate `interactionPatterns` on extracted TeamPlaybooks with actual observed patterns
+
+### 3d: `team-experience.ts` (memory)
+
+No code changes needed — it stores whatever TeamTrajectory has.
+The graph data will be persisted automatically.
+
+---
+
+## Phase 4: Update Analysis Template
+
+**File: `src/workspace/templates/team-trajectory-analysis.ts`**
+
+This is the biggest consumer and benefits most from graph data.
+
+### 4a: `assessComplexity()`
+
+Currently checks `events.length` and `teamSize`. Update to also consider:
+- Total step count across all members
+- Interaction density
+- Whether trajectories are compressed
+
+### 4b: `heuristicFallback()`
+
+Currently derives agent credits from `memberOutcomes` aggregate counts.
+Update to analyze actual trajectory steps when available:
+- Per-step credit based on action type and outcome
+- Interaction credit from `AgentInteraction` with content quality analysis
+- Role lessons from actual step patterns (not just task count)
+
+### 4c: `prepareWorkspace()`
+
+Currently writes MemberOutcome summaries to `trajectories/{role}.json`.
+Update to write compressed trajectory steps:
+```
+trajectories/
+  planner.json      ← Full (or compressed) step sequence
+  executor-1.json   ← Full (or compressed) step sequence
+```
+
+Each file includes:
+```json
+{
+  "agentId": "agent-1",
+  "role": "planner",
+  "steps": [
+    { "thought": "...", "action": "...", "observation": "...", "isCritical": true },
+    ...
+  ],
+  "outcome": { "success": true, ... },
+  "stepCount": 25,
+  "criticalStepCount": 4
+}
+```
+
+### 4d: `buildTaskPrompt()`
+
+Update the analysis prompt to guide the agent to:
+- Read per-agent trajectory files (not just outcome summaries)
+- Focus on critical steps flagged in `critical-moments.json`
+- Trace causal chains across agents via `interactions/graph.json`
+- Produce per-step attributions in `AgentCredit.stepAttributions`
+
+### 4e: `collectOutput()`
+
+Update output parsing to handle richer agent output:
+- Parse `stepAttributions` from agent credits
+- Parse `type` and `contentQuality` from interaction credits
+- Parse `patternComparison` and `emergentCoordination` from coordination assessment
+- Parse `interactionAssessment` and `evidence` from role lessons
+
+---
+
+## Phase 5: Update Tests + Cleanup
+
+### 5a: Update test helpers
+
+Every test file has a `makeSampleTrajectory()` helper that creates a TeamTrajectory
+with flat fields. Update each to optionally include graph data:
+
+- `tests/types/team-trajectory.test.ts` — add graph construction tests
+- `tests/learning/team-ingester.test.ts` — test graph-aware ingestion + compression
+- `tests/workspace/templates/team-trajectory-analysis.test.ts` — test graph-aware analysis
+- `tests/workspace/templates/team-playbook-extraction.test.ts` — test interaction pattern extraction
+- `tests/learning/team-pipeline.test.ts` — test pipeline with graph data
+- `tests/learning/team-meta-learner.test.ts` — test meta-learner with graph data
+
+### 5b: New test file
+
+`tests/types/team-trajectory-graph.test.ts`:
+- Test `buildTeamTrajectory()` produces graph + flat data
+- Test `buildInteractionGraph()` with InteractionTags
+- Test `AgentInteraction` construction from tagged steps
+- Test `StructuralMetrics` computation
+- Test backward compat (trajectory without graph data still works everywhere)
+
+### 5c: Update gaps.md
+
+Mark Gap 1 as FIXED. Update Gap 4 (compression) status since it's now addressable.
+
+---
+
+## Files Changed Per Phase
+
+| Phase | Files Modified | Files Created | Risk |
+|-------|---------------|---------------|------|
+| 1     | team-trajectory.ts, types/index.ts | — | None (additive) |
+| 2     | team-trajectory.ts, team-ingester.ts | — | Low (backward compat) |
+| 3     | team-pipeline.ts, team-meta-learner.ts, team-playbook-extraction.ts | — | Low (prefer-when-available) |
+| 4     | team-trajectory-analysis.ts | — | Medium (template changes) |
+| 5     | 6 test files | team-trajectory-graph.test.ts | Low (tests only) |
+
+---
+
+## Key Design Decisions
+
+1. **Graph fields are optional on TeamTrajectory** — consumers check `trajectory.members` and fall back to flat fields. This avoids breaking any existing code paths or test data.
+
+2. **Flat fields remain derived** — `buildTeamTrajectory()` always populates both flat and graph fields. Existing code that only uses flat fields continues to work unchanged.
+
+3. **Compression happens in the ingester** — the ingester's `ingest()` method is where we fold internal steps and strip waste. The compressed trajectories are what get written to the workspace.
+
+4. **No new classes** — the existing `TeamTrajectoryIngester` gets updated in place. No need for a separate `TeamTrajectoryGraphBuilder` class.
+
+5. **Step metadata carries InteractionTags** — `Step.metadata.interactionTag` is the existing mechanism (already implemented in Gap 3). `AgentInteraction` objects are built from these tags by `buildTeamTrajectory()`.