cognitive-core 0.2.1 → 0.2.3

package/src/atlas.ts

@@ -9,6 +9,15 @@ import type {
 import type { KnowledgeMatch } from './types/knowledge.js';
 import { createDefaultConfig } from './types/index.js';
 import { MemorySystem, createMemorySystem, type TeamExperience } from './memory/index.js';
+import {
+  loadCuratedPlaybooks as loadCuratedPlaybooksFn,
+  BUNDLED_SEED_PACK_DIR,
+} from './memory/curated-loader.js';
+import {
+  resolvePlaybookSource,
+  sourceStateKey,
+  type SourceState,
+} from './memory/source-resolver.js';
 import {
   UnifiedLearningPipeline,
   createUnifiedPipeline,
@@ -271,6 +280,9 @@ export class Atlas {
 
     // Initialize playbook-based components if playbooks are available
     if (this.memory.playbooks) {
+      // Load curated playbooks (bundled seed pack + additional dirs)
+      await this.loadCuratedPlaybooks();
+
       this.skillLibrary = createSkillLibrary(
         this.memory.playbooks,
         this.config.skillLibrary
@@ -290,6 +302,90 @@ export class Atlas {
     }
   }
 
+  /**
+   * Load curated playbooks from bundled seed pack, additional directories,
+   * and resolved sources (local paths or git repos).
+   * Called during init() when curatedPlaybooks config is enabled.
+   */
+  private async loadCuratedPlaybooks(): Promise<void> {
+    const cfg = this.config.curatedPlaybooks;
+    const recreate = cfg.recreateOnInit;
+
+    // Load bundled seed pack (shipped with cognitive-core)
+    if (cfg.loadBundledSeedPack) {
+      const loadOpts = recreate
+        ? { recreate: true, sourceId: 'bundled' }
+        : { sourceId: 'bundled' };
+      await loadCuratedPlaybooksFn(
+        BUNDLED_SEED_PACK_DIR,
+        this.memory.playbooks,
+        loadOpts,
+      );
+    }
+
+    // Load from additional directories (backward compat)
+    for (const dir of cfg.additionalDirs) {
+      const loadOpts = recreate
+        ? { recreate: true, sourceId: dir }
+        : { sourceId: dir };
+      await loadCuratedPlaybooksFn(dir, this.memory.playbooks, loadOpts);
+    }
+
+    // Resolve and load from sources (local paths + git repos)
+    if (cfg.sources.length > 0) {
+      const cacheDir = join(this.config.storage.baseDir, cfg.cache.dir);
+      for (const source of cfg.sources) {
+        await this.loadFromSource(source, cacheDir, recreate);
+      }
+    }
+  }
+
+  /**
+   * Resolve a single source (local or git) and load its playbooks.
+   */
+  private async loadFromSource(
+    source: string,
+    cacheDir: string,
+    recreate: boolean,
+  ): Promise<void> {
+    const cfg = this.config.curatedPlaybooks;
+
+    const resolved = await resolvePlaybookSource(source, {
+      cacheDir,
+      maxAgeMs: cfg.cache.maxAgeMs,
+      forceUpdate: recreate,
+      getSourceState: (s) =>
+        this.persistence.getSystemState<SourceState>(sourceStateKey(s)),
+      setSourceState: (s, state) =>
+        this.persistence.setSystemState(sourceStateKey(s), state),
+    });
+
+    if (!resolved) return;
+
+    // For git sources: skip loading if SHA hasn't changed and we're not recreating
+    // (playbooks are already in the library from a previous init).
+    // For local paths: always load (the loader handles dedup via getByName).
+    if (resolved.isGit && !resolved.updated && !recreate) return;
+
+    const loadOpts = recreate
+      ? { recreate: true, sourceId: resolved.sourceId }
+      : { sourceId: resolved.sourceId };
+
+    const result = await loadCuratedPlaybooksFn(
+      resolved.playbookDir,
+      this.memory.playbooks,
+      loadOpts,
+    );
+
+    // Update source state with playbook count
+    const stateKey = sourceStateKey(source);
+    const prevState = this.persistence.getSystemState<SourceState>(stateKey);
+    if (prevState) {
+      prevState.playbookCount = result.loaded;
+      this.persistence.setSystemState(stateKey, prevState);
+    }
+  }
+
   /**
    * Set the LLM provider for solving (deprecated)
    * @deprecated Use setAgentManager() with backends for real execution

package/src/memory/curated-loader.ts

@@ -6,17 +6,30 @@
  * drop all curated playbooks and reload from source files without
  * losing extracted or imported playbooks.
  *
+ * Supports recursive directory scanning and source-prefix-based
+ * deletion for per-source recreate (multiple sources don't clobber
+ * each other).
+ *
  * Inspired by Dash's separation of curated knowledge (file-loaded)
  * vs learnings (runtime-discovered).
  */
 
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import type { PlaybookProvenance } from '../types/index.js';
 import { createPlaybook } from '../types/index.js';
 import type { PlaybookLibrary } from './playbook.js';
 
+/**
+ * Path to the bundled compound-engineering seed pack shipped with cognitive-core.
+ * Resolves relative to this file's location in the package.
+ */
+const __filename_curated = fileURLToPath(import.meta.url);
+const __dirname_curated = dirname(__filename_curated);
+export const BUNDLED_SEED_PACK_DIR = join(__dirname_curated, '../../playbooks/compound-engineering');
+
 /**
  * Schema for a curated playbook JSON file
  */
@@ -55,17 +68,49 @@ export interface CuratedLoadResult {
   recreated: boolean;
 }
 
+/**
+ * Options for loadCuratedPlaybooks
+ */
+export interface CuratedLoadOptions {
+  /** If true, delete existing curated playbooks before loading */
+  recreate?: boolean;
+  /**
+   * Source identifier for provenance tracking.
+   * Used as prefix in provenance.sourceFile for per-source recreate.
+   * If provided and recreate is true, only playbooks from this source are deleted.
+   */
+  sourceId?: string;
+}
+
+/**
+ * Recursively find all JSON files in a directory tree.
+ */
+async function findJsonFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await findJsonFiles(fullPath));
+    } else if (entry.name.endsWith('.json')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
 /**
  * Load curated playbooks from a directory of JSON files into the library.
+ * Supports recursive directory scanning.
  *
  * @param curatedDir - Directory containing curated playbook JSON files
  * @param library - PlaybookLibrary to load into
- * @param options.recreate - If true, delete existing curated playbooks before loading
+ * @param options - Load options (recreate, sourceId)
  */
 export async function loadCuratedPlaybooks(
   curatedDir: string,
   library: PlaybookLibrary,
-  options?: { recreate?: boolean }
+  options?: CuratedLoadOptions
 ): Promise<CuratedLoadResult> {
   const result: CuratedLoadResult = {
     loaded: 0,
@@ -78,20 +123,23 @@ export async function loadCuratedPlaybooks(
     return result;
   }
 
-  // Recreate: drop all curated playbooks first
+  // Recreate: drop curated playbooks before loading
   if (options?.recreate) {
-    await library.deleteByOrigin('curated');
+    if (options.sourceId) {
+      // Per-source recreate: only delete playbooks from this source
+      await library.deleteByCuratedSource(options.sourceId);
+    } else {
+      // Global recreate: delete all curated playbooks
+      await library.deleteByOrigin('curated');
+    }
     result.recreated = true;
   }
 
-  // Find all JSON files in the directory (non-recursive)
-  const files = await readdir(curatedDir);
-  const jsonFiles = files.filter((f) => f.endsWith('.json'));
+  // Find all JSON files recursively
+  const jsonFiles = await findJsonFiles(curatedDir);
 
-  for (const file of jsonFiles) {
-    const filePath = join(curatedDir, file);
-    const fileStat = await stat(filePath);
-    if (!fileStat.isFile()) continue;
+  for (const filePath of jsonFiles) {
+    const relativeToDir = relative(curatedDir, filePath);
 
     try {
       const content = await readFile(filePath, 'utf-8');
@@ -100,7 +148,7 @@ export async function loadCuratedPlaybooks(
       // Validate required fields
       if (!parsed.name || !parsed.applicability || !parsed.guidance) {
         result.errors.push({
-          file,
+          file: relativeToDir,
           error: 'Missing required fields: name, applicability, guidance',
         });
         continue;
@@ -113,10 +161,15 @@ export async function loadCuratedPlaybooks(
         continue;
       }
 
+      // Build sourceFile with optional source prefix
       const relativePath = relative(process.cwd(), filePath);
+      const sourceFile = options?.sourceId
+        ? `${options.sourceId}:${relativeToDir}`
+        : relativePath;
+
       const provenance: PlaybookProvenance = {
         origin: 'curated',
-        sourceFile: relativePath,
+        sourceFile,
         curatedBy: parsed.curatedBy,
         recordedAt: new Date(),
       };
@@ -150,7 +203,7 @@ export async function loadCuratedPlaybooks(
       result.loaded++;
     } catch (error) {
       result.errors.push({
-        file,
+        file: relativeToDir,
         error: error instanceof Error ? error.message : String(error),
       });
     }

package/src/memory/index.ts

@@ -99,10 +99,26 @@ export type { SqlitePersistenceConfig } from '../persistence/index.js';
 // Curated playbook loading
 export {
   loadCuratedPlaybooks,
+  BUNDLED_SEED_PACK_DIR,
   type CuratedPlaybookFile,
   type CuratedLoadResult,
+  type CuratedLoadOptions,
 } from './curated-loader.js';
 
+// Source resolver (git + local path resolution for curated sources)
+export {
+  resolvePlaybookSource,
+  isGitSource,
+  parseGitSource,
+  discoverPlaybookDir,
+  sourceStateKey,
+  type ParsedGitSource,
+  type PlaybookManifest,
+  type SourceState,
+  type ResolveResult,
+  type ResolveOptions,
+} from './source-resolver.js';
+
 // Skill export (compile playbooks → Open Agent Skills format)
 export {
   compilePlaybookToSkill,

package/src/memory/playbook.ts

@@ -616,6 +616,25 @@ export class PlaybookLibrary {
     return toDelete.length;
   }
 
+  /**
+   * Delete curated playbooks whose provenance.sourceFile starts with the given prefix.
+   * Used by the source resolver to recreate playbooks from a specific source
+   * without affecting other curated sources.
+   */
+  async deleteByCuratedSource(sourcePrefix: string): Promise<number> {
+    await this.init();
+    const toDelete = this.getAllSync().filter(
+      (p) =>
+        p.provenance?.origin === 'curated' &&
+        p.provenance.sourceFile?.startsWith(sourcePrefix),
+    );
+    for (const playbook of toDelete) {
+      this.persistence.deletePlaybook(playbook.id);
+      this._index.remove(playbook.id);
+    }
+    return toDelete.length;
+  }
+
   /**
    * Get provenance summary across all playbooks
    */