cognitive-core 0.1.0 → 0.2.0

package/gaps.md

@@ -0,0 +1,204 @@
+# Team-Aware Trajectory Learning: Implementation Gap Analysis
+
+> Generated from comparison of RESEARCH-team-trajectory-learning.md, PROPOSAL-team-aware-learning.md,
+> DESIGN-team-extraction-pipeline.md against the current implementation.
+
+## Summary
+
+| Severity | Total | Fixed | Deferred |
+|----------|-------|-------|----------|
+| HIGH     | 3     | 3     | 0        |
+| MEDIUM   | 10    | 4     | 6        |
+| LOW      | 17    | 10    | 7        |
+
+---
+
+## HIGH Priority
+
+### Gap 1: Graph-based vs event-stream TeamTrajectory
+- **Source:** DESIGN doc specifies `members: MemberTrajectory[]` (full `Trajectory` objects per agent) + `interactions: AgentInteraction[]`. Implementation uses flat `events: TeamEvent[]` + `interactionGraph: InteractionEdge[]` (PROPOSAL model).
+- **Impact:** Loses per-agent step-level detail needed for compression, critical step identification, and fine-grained credit attribution.
+- **Status:** FIXED
+- **Fix:** Additive graph migration. Added `MemberTrajectory`, `AgentInteraction`, `GraphStructuralMetrics` types. Added optional graph fields (`members`, `interactions`, `graphMetrics`, `expectedPatterns`) to `TeamTrajectory`. Updated `buildTeamTrajectory()` to populate both graph and flat data. Updated ingester with graph-aware scoring (content-based step scoring, downstream success analysis). Migrated all consumers (pipeline, meta-learner, extraction, analysis template) to prefer graph data with flat fallback. 16 new tests added.
+
+### Gap 2: `TeamTrajectoryInput` entry point missing
+- **Source:** DESIGN specifies `TeamTrajectoryInput` with `memberTrajectories: { agentId, role, trajectory: Trajectory }[]` as the ingest entry point that gets converted to `TeamTrajectory`.
+- **Impact:** No way to ingest raw individual trajectories and automatically build the team trajectory graph.
+- **Status:** FIXED
+- **Fix:** Add `TeamTrajectoryInput` type and `buildTeamTrajectory()` conversion function.
+
+### Gap 3: `InteractionTag` runtime capture missing
+- **Source:** DESIGN specifies `InteractionTag` interface (`interactionId`, `interactionType`, `counterpartAgentId`, `stepRole`) as step metadata for automatic interaction graph construction.
+- **Impact:** No automatic way to tag agent interactions during execution. Users must manually construct `interactionGraph`.
+- **Status:** FIXED
+- **Fix:** Add `InteractionTag` and `InteractionType` types. Add `buildInteractionGraph()` utility that extracts edges from tagged steps.
+
+---
+
+## MEDIUM Priority
+
+### Gap 4: Trajectory compression not implemented
+- **Source:** DESIGN Phase 2 specifies per-agent trajectory compression: fold internal steps, strip verbose output, preserve interaction boundaries, target ~10x reduction.
+- **Impact:** Analysis operates on raw data, reducing quality and increasing cost for agentic analysis.
+- **Status:** DEFERRED - Requires graph-based TeamTrajectory (Gap 1). The ingester scores critical steps/interactions for prioritization, which partially addresses this.
+- **Fix:** N/A (depends on Gap 1)
+
+### Gap 5: Analysis output schema missing fields
+- **Source:** DESIGN specifies richer output types than implemented.
+- **Impact:** Lost detail in analysis results.
+- **Status:** FIXED
+- **Fix:** Add `stepAttributions` to `AgentCredit`, `type`/`contentQuality` to `InteractionCredit`, `patternComparison`/`emergentCoordination` to `CoordinationAssessment`, `interactionAssessment`/`evidence` to `RoleLessonEntry`.
+
+### Gap 6: `spawnTeamMember()` not implemented
+- **Source:** DESIGN specifies `Atlas.spawnTeamMember(config)` that injects both task playbooks and role playbooks into spawned team member agents.
+- **Impact:** No integrated way to spawn agents with full knowledge injection.
+- **Status:** DEFERRED - Runtime integration concern. Requires AgentManager + SkillLibrary coordination. The `formatRoleGuidance()` method provides the role playbook content for manual injection.
+- **Fix:** N/A (runtime integration)
+
+### Gap 7: `ExpectedInteractionPattern` type missing
+- **Source:** DESIGN specifies `ExpectedInteractionPattern` for comparing expected vs actual coordination patterns, and `AgentInteraction.wasExpected` flag.
+- **Impact:** Cannot compare observed coordination against expected patterns from team.yaml.
+- **Status:** FIXED
+- **Fix:** Add `ExpectedInteractionPattern` type to team-trajectory.ts.
+
+### Gap 8: Analysis agent meta-learning loop missing
+- **Source:** DESIGN specifies capturing the analysis agent's own trajectory and feeding it through the individual `LearningPipeline` with domain `"team-analysis"`.
+- **Impact:** System doesn't learn to be better at team analysis over time.
+- **Status:** DEFERRED - Requires AgentManager integration to capture analysis agent trajectories. The template infrastructure supports this but the pipeline doesn't wire it.
+- **Fix:** N/A (runtime integration)
+
+### Gap 9: Knowledge injection for analysis agents empty
+- **Source:** DESIGN specifies `getAnalysisKnowledge()` querying team playbooks, similar experiences, and individual memory. Templates return empty `getSkills()`/`getResources()`.
+- **Impact:** Analysis agents operate without prior knowledge context.
+- **Status:** DEFERRED - Templates are stateless and don't have access to memory at definition time. Would need a factory pattern or dependency injection to resolve.
+- **Fix:** N/A (architectural pattern needed)
+
+### Gap 10: Playbook updates/refinements not applied
+- **Source:** Batch extraction produces `TeamPlaybookUpdate`/`RolePlaybookUpdate` with refinement context/additions. Pipeline counts them but discards them (no `updatePlaybook()` method).
+- **Impact:** Existing playbooks never get refined from new experiences.
+- **Status:** FIXED
+- **Fix:** Add `updateTeamPlaybook()`/`updateRolePlaybook()` methods to `TeamExperienceMemory` and wire into pipeline's batch learning.
+
+### Gap 11: Cross-pollination references never populated
+- **Source:** DESIGN specifies `RolePlaybookReference` on TeamPlaybook and `RelatedTaskPlaybook` on RolePlaybook. Types exist but heuristic extraction never populates them.
+- **Impact:** No cross-linking between team playbooks and role/task playbooks.
+- **Status:** FIXED
+- **Fix:** Add cross-pollination logic to heuristic extraction.
+
+### Gap 12: Meta-learner fragile topology extraction
+- **Source:** `TeamMetaLearner.generateReflection()` extracts topology assessment from `trajectory.topologyType` but `analyzeTopologyEffectiveness()` uses regex on `obs.compositionEffectiveness.topologyAssessment` (a string like 'effective'/'neutral'/'hindering') to match topologies.
+- **Impact:** Topology analysis is unreliable and may produce incorrect meta-strategies.
+- **Status:** FIXED
+- **Fix:** Use the `teamTrajectoryId` to look up the actual trajectory's `topologyType` from meta-observations, or store topology directly on the observation.
+
+### Gap 13: Vector embeddings for team data missing
+- **Source:** DESIGN specifies extending `vectors.db` with team embeddings for semantic search. `TeamExperienceMemory` uses `JsonStore` with text-matching heuristics.
+- **Impact:** Team playbook/experience search relies on keyword matching instead of semantic similarity.
+- **Status:** DEFERRED - Requires EmbeddingManager integration. The current text-matching approach works for small datasets. Add as future enhancement when team data volume grows.
+- **Fix:** N/A (infrastructure enhancement)
+
+---
+
+## LOW Priority
+
+### Gap 14: `metricsWeight` config field missing
+- **Source:** PROPOSAL specifies `metricsWeight: z.number().min(0).max(1).default(0.3)` in `TeamLearningConfigSchema`.
+- **Impact:** No way to tune how much structural metrics influence analysis.
+- **Status:** FIXED
+- **Fix:** Add field to `TeamLearningConfigSchema`.
+
+### Gap 15: `CompressionConfig` not in `TeamLearningConfig`
+- **Source:** DESIGN specifies `compression: CompressionConfig` as a nested config field with 7 parameters.
+- **Impact:** Compression parameters not configurable through main config.
+- **Status:** FIXED
+- **Fix:** Add `CompressionConfig` schema to `TeamLearningConfigSchema`.
+
+### Gap 16: `InteractionType` union type not defined
+- **Source:** DESIGN specifies `InteractionType = 'delegation' | 'result_return' | 'message' | 'signal' | 'spawn' | 'escalation'` as a distinct type from `TeamEventType`.
+- **Impact:** `RoleInteractionGuidance.interactionType` uses `string` instead of a constrained union.
+- **Status:** FIXED (combined with Gap 3)
+- **Fix:** Add `InteractionType` to team-trajectory.ts and use in RoleInteractionGuidance.
+
+### Gap 17: `TeamPlaybook.complexity` missing 'epic'
+- **Source:** `TeamPlaybook.complexity` is `'simple' | 'moderate' | 'complex'` but `TeamPlaybookApplicability.complexityLevels` includes `'epic'`. Inconsistency.
+- **Impact:** Cannot create team playbooks tagged as epic complexity.
+- **Status:** FIXED
+- **Fix:** Add `'epic'` to `TeamPlaybook.complexity` union.
+
+### Gap 18: `AnalysisWorkspace` type not formalized
+- **Source:** DESIGN specifies `AnalysisWorkspace` interface with `path`, `teamTrajectory`, `compressionStats`, `criticalMoments`.
+- **Impact:** No formal type for the workspace state between ingestion and analysis.
+- **Status:** DEFERRED - The `IngestionResult` type serves this purpose. Adding a separate type would be redundant.
+- **Fix:** N/A
+
+### Gap 19: `TeamAnalysisCollector` not a separate class
+- **Source:** DESIGN specifies `TeamAnalysisCollector` as a distinct class for collecting analysis agent output.
+- **Impact:** Collection logic is embedded in the pipeline, reducing modularity.
+- **Status:** DEFERRED - Current approach works. Separate collector class would add complexity without clear benefit at current scale.
+- **Fix:** N/A
+
+### Gap 20: Assessment workspace filesystem layout differs
+- **Source:** DESIGN specifies specific `input/`/`workspace/`/`output/` directory structure. Templates use `WorkspaceHandle` abstraction.
+- **Impact:** Minor - templates use equivalent but different abstraction.
+- **Status:** DEFERRED - WorkspaceHandle provides the same capabilities through a cleaner API.
+- **Fix:** N/A
+
+### Gap 21: `RoleLessonEntry` missing detailed fields
+- **Source:** DESIGN specifies `interactionAssessment: { withRole, interactionType, quality, observation, recommendation }[]` and `evidence: { stepIndex, description }[]`.
+- **Impact:** Role lessons lack interaction-specific and evidence details.
+- **Status:** FIXED (combined with Gap 5)
+- **Fix:** Add fields to `RoleLessonEntry`.
+
+### Gap 22: `TeamLessonEntry` simplified vs design
+- **Source:** DESIGN has `compositionLessons` and `coordinationLessons` with structured categories (`'role-necessity' | 'team-size' | 'topology' | 'model-selection'` and `'delegation' | 'communication' | 'synchronization' | 'escalation'`).
+- **Impact:** Less structured lesson categorization.
+- **Status:** FIXED
+- **Fix:** Add specific subcategory types.
+
+### Gap 23: Deduplication threshold not wired from config
+- **Source:** Config has `deduplicationThreshold: 0.85` but heuristic extraction uses hardcoded `0.85`.
+- **Impact:** Config value is ignored.
+- **Status:** FIXED
+- **Fix:** Pass config value through to extraction.
+
+### Gap 24: `TeamMetaObservation` shape diverges from DESIGN
+- **Source:** PROPOSAL version (implemented) has `formation.confidence/reasoning`. DESIGN version has `formation.wasEffective`. Implementation lacks `lessons.roleSuggestions`.
+- **Impact:** Minor type mismatch.
+- **Status:** FIXED
+- **Fix:** Add `wasEffective` field to `FormationObservation` and `roleSuggestions` to `TeamLessonsLearned`.
+
+### Gap 25: Missing analysis domain tag
+- **Source:** DESIGN specifies analysis agent trajectory should be tagged with domain `"team-analysis"` for recursive learning.
+- **Impact:** If analysis agent trajectories are ever captured, they won't be domain-tagged.
+- **Status:** DEFERRED - Depends on Gap 8 (analysis agent meta-learning loop).
+- **Fix:** N/A
+
+### Gap 26: `CoordinationAssessment` missing `patternComparison`
+- **Source:** DESIGN specifies `patternComparison: { expected, observed, impact }[]`.
+- **Impact:** No structured comparison of expected vs actual coordination patterns.
+- **Status:** FIXED (combined with Gap 5)
+- **Fix:** Add field.
+
+### Gap 27: `CoordinationAssessment` missing `emergentCoordination`
+- **Source:** DESIGN specifies `emergentCoordination: { description, wasHelpful, shouldBeFormalized }[]`.
+- **Impact:** No tracking of emergent coordination patterns.
+- **Status:** FIXED (combined with Gap 5)
+- **Fix:** Add field.
+
+### Gap 28: `RoleInteractionGuidance.interactionType` uses `string`
+- **Source:** Should use `InteractionType` union from DESIGN.
+- **Impact:** No type safety on interaction types.
+- **Status:** FIXED (combined with Gap 16)
+- **Fix:** Update type to use `InteractionType`.
+
+### Gap 29: No `TeamBatchResult.ready` field
+- **Source:** DESIGN specifies `TeamBatchResult.ready: boolean` to indicate whether batch was actually run.
+- **Impact:** Caller can't distinguish "batch ran and produced nothing" from "batch not ready".
+- **Status:** FIXED
+- **Fix:** Add `ready` field.
+
+### Gap 30: `TeamProcessResult` type mismatch between Atlas and Pipeline
+- **Source:** Atlas defines its own `TeamProcessResult` (`{ teamTrajectoryId, stored }`) different from pipeline's (`{ teamTrajectoryId, stored, analyzed, analysis? }`).
+- **Impact:** Atlas method returns less information than pipeline produces.
+- **Status:** FIXED
+- **Fix:** Unify types; Atlas should re-export pipeline's type or extend it.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "cognitive-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript-native cognitive core for adaptive learning and abstraction",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "cognitive-core": "./dist/bin/cognitive-core.js"
+    "cognitive-core": "./dist/bin/cognitive-core.js",
+    "cogcore": "./dist/bin/cognitive-core.js"
   },
   "exports": {
     ".": {
@@ -28,6 +29,10 @@
     "./embeddings": {
       "import": "./dist/embeddings/index.js",
       "types": "./dist/embeddings/index.d.ts"
+    },
+    "./session-bank": {
+      "import": "./dist/session-bank/index.js",
+      "types": "./dist/session-bank/index.d.ts"
     }
   },
   "scripts": {
@@ -36,7 +41,11 @@
     "test": "vitest",
     "test:run": "vitest run",
     "lint": "eslint src --ext .ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "version:patch": "npm version patch && git push && git push --tags",
+    "version:minor": "npm version minor && git push && git push --tags",
+    "version:major": "npm version major && git push && git push --tags",
+    "publish:npm": "npm run build && npm publish"
   },
   "keywords": [
     "cognitive",
@@ -47,7 +56,7 @@
     "concept",
     "skill"
   ],
-  "author": "",
+  "author": "Alex Ngai",
   "license": "MIT",
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.8",
@@ -57,14 +66,25 @@
     "vitest": "^1.0.0"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "^0.13.1",
-    "@huggingface/transformers": "^3.0.0",
     "acp-factory": "^0.1.7",
+    "agent-workspace": "^0.1.3",
     "better-sqlite3": "^9.0.0",
+    "minimem": "^0.1.0",
+    "sessionlog": "^0.0.4",
+    "skill-tree": "^0.1.5",
     "sqlite-vec": "^0.1.6",
+    "yaml": "^2.8.2",
     "zod": "^3.22.0"
   },
+  "peerDependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   }
 }

package/references/agent-workspace/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+## Project overview
+
+`agent-workspace` is a TypeScript library for managing filesystem workspaces used by AI agents. It provides structured directory layouts, typed readers/writers (JSON, JSONL, Markdown with YAML frontmatter, raw text), and output validation with structured error collection.
+
+## Commands
+
+- `npm test` — run all tests (vitest)
+- `npm run test:watch` — run tests in watch mode
+- `npm run build` — build with tsup (outputs to `dist/`)
+- `npm run typecheck` — type-check without emitting
+
+## Architecture
+
+```
+src/
+  index.ts          ← public API, re-exports everything
+  types.ts          ← all shared types (Schema, OutputSpec, ValidationResult, etc.)
+  manager.ts        ← WorkspaceManager: create, list, cleanup, pruneStale
+  handle.ts         ← WorkspaceHandle: section-scoped I/O facade over readers/writers
+  validation.ts     ← validateOutput: non-throwing batch output checker
+  readers/
+    json.ts         ← readJson, readJsonl, readJsonDir
+    markdown.ts     ← readMarkdown (with YAML frontmatter parsing via `yaml` package)
+    raw.ts          ← readRaw, listFiles
+  writers/
+    json.ts         ← writeJson, writeJsonl
+    markdown.ts     ← writeMarkdown (with YAML frontmatter serialization)
+    raw.ts          ← writeRaw, copyDir, symlink
+
+tests/
+  readers.test.ts   ← standalone reader function tests
+  writers.test.ts   ← standalone writer function tests
+  handle.test.ts    ← WorkspaceHandle round-trip and section tests
+  manager.test.ts   ← WorkspaceManager lifecycle tests
+  validation.test.ts ← validateOutput tests
+  errors.test.ts    ← comprehensive parse/validation error behavior tests
+```
+
+## Key design decisions
+
+- **Two error strategies**: Reader functions **throw** on errors (for try/catch recovery). `validateOutput` **collects** errors into `{ valid, errors }` (for batch checking). Never mix these — readers always throw, validation never throws.
+- **Schema interface**: `{ parse(data: unknown): T }` — deliberately minimal so it works with Zod, Joi, or any custom implementation. `parse` must throw on invalid data.
+- **Section-scoped I/O**: `WorkspaceHandle` methods take a section name (`'input'`, `'output'`, `'resources'`, `'scratch'`, or custom) as the first argument. `handle.dir(section)` throws synchronously if the section is unknown.
+- **Default dirs**: `input`, `output`, `resources`, `scratch` are always created. Additional dirs are specified at `manager.create()` time.
+- **Workspace metadata**: Each workspace writes `.workspace.json` with `{ id, taskType, createdAt, dirs }`. The manager uses this to reconstruct handles when listing.
+
+## Conventions
+
+- ESM-first (`"type": "module"` in package.json), dual CJS/ESM output via tsup.
+- All file path parameters in readers/writers are relative to the `dir` argument. Writers auto-create parent directories via `fs.mkdir({ recursive: true })`.
+- Tests use temp directories (`os.tmpdir()` + `fs.mkdtemp`) and clean up in `afterEach`.
+- No external dependencies except `yaml` for YAML parsing/serialization.
+- TypeScript strict mode. Target ES2022.
+
+## Error message contracts
+
+Error messages are intentionally detailed to support agent re-prompting:
+
+- `readJson` on bad JSON: native `JSON.parse` SyntaxError
+- `readJson` schema failure: the schema's own error message (e.g., Zod's)
+- `readJsonl` schema failure: `"JSONL validation failed at line N: <schema error>"`
+- `handle.dir()` unknown section: `'Unknown section "X". Available: input, output, ...'`
+- `validateOutput` errors: `{ path: string, message: string }` — path identifies the file, message describes the issue
+
+## Testing
+
+The test suite has 101 tests across 6 files. When adding new functionality:
+
+- Add happy-path tests to the relevant existing test file (`readers.test.ts`, `handle.test.ts`, etc.)
+- Add error/throw behavior tests to `errors.test.ts`
+- All reader error paths must be tested: missing file, malformed content, schema rejection
+- Validation tests must verify that errors are **collected** (not thrown) and include both `path` and `message`