cognitive-core 0.2.5 → 0.3.1

package/dist/memory/system.js

@@ -1,12 +1,17 @@
 import { createExperience } from '../types/index.js';
+import { logger } from '../utils/logger.js';
 import { ExperienceMemory } from './experience.js';
 import { PlaybookLibrary } from './playbook.js';
 import { MetaMemory } from './meta.js';
-import { TeamExperienceMemory, } from './team-experience.js';
 import { LearningEffectivenessTracker, } from '../learning/effectiveness.js';
 import { KnowledgeBank } from './knowledge-bank.js';
 import { ReflexionMemory } from './reflexion.js';
-import { CausalStore } from './causal-store.js';
+import { MetaPlaybookBank } from './meta-playbook-bank.js';
+import { seedMetaPlaybookBank, seedMetaStrategies } from './seeds/seed-loader.js';
+import { ProceduralMemoryFileStore, pruneSqliteOnlyPlaybooks, readAtlasMemoryManifest, reindexCanonicalPlaybookFile, reindexCanonicalPlaybookFiles, resolveScopedProceduralPlaybookDir, } from './procedural-skill.js';
+import { createFilesystemCascade, createPlaybookCascadeTarget, } from './filesystem-cascade.js';
+import { assessPlaybookApplicability } from './playbook-applicability.js';
+import { sectionGuidanceForTask } from './playbook-incorporation.js';
 import { join } from 'node:path';
 /**
  * Default capacity configuration
@@ -29,16 +34,22 @@ export class MemorySystem {
     playbooks;
     meta;
     effectiveness;
-    teamExperiences;
     reflexion;
-    causal;
     knowledgeBank;
+    metaPlaybooks;
+    persistence;
+    baseDir;
     config;
     capacityConfig;
+    validationControls = null;
     initialized = false;
+    /** Reindex-on-edit watcher; null unless procedural memory runs in filesystem+watch mode. */
+    cascade = null;
     lastCapacityCheck = 0;
     capacityCheckInterval = 60000; // Check every minute
     constructor(persistence, baseDir, config, knowledgeBankConfig) {
+        this.persistence = persistence;
+        this.baseDir = baseDir;
         this.config = {
             maxExperiences: config?.maxExperiences ?? 4,
             maxStrategies: config?.maxStrategies ?? 3,
@@ -46,17 +57,57 @@ export class MemorySystem {
             maxSkills: config?.maxSkills ?? 3,
             maxContextTokens: config?.maxContextTokens ?? 4000,
             capacity: config?.capacity ?? DEFAULT_CAPACITY,
+            // G6: default ON, matching MemoryConfigSchema. Headless-safe — a cold
+            // store falls back to text-similarity matching in
+            // `findMatchingFrontierAware`, so enabling it never throws/deadlocks.
+            frontierRouting: config?.frontierRouting ?? true,
+            injectFailedExperiences: config?.injectFailedExperiences ?? true,
+            seedMetaPlaybooks: config?.seedMetaPlaybooks ?? true,
+            seedMetaStrategies: config?.seedMetaStrategies ?? true,
+            playbookRetrieval: {
+                mode: config?.playbookRetrieval?.mode ?? 'legacy',
+                minScore: config?.playbookRetrieval?.minScore ?? 0.1,
+                minScoreSemantic: config?.playbookRetrieval?.minScoreSemantic ?? 0.35,
+                crossDomainFloorMultiplier: config?.playbookRetrieval?.crossDomainFloorMultiplier ?? 1.5,
+                fusion: config?.playbookRetrieval?.fusion ?? 'rrf',
+                incorporation: config?.playbookRetrieval?.incorporation ?? 'full',
+            },
+            playbookApplicability: {
+                enabled: config?.playbookApplicability?.enabled ?? false,
+                minSpecificityScore: config?.playbookApplicability?.minSpecificityScore ?? 0.45,
+                crossDomainMinScore: config?.playbookApplicability?.crossDomainMinScore ?? 0.55,
+            },
+            proceduralMemory: {
+                source: config?.proceduralMemory?.source ?? 'filesystem',
+                dir: config?.proceduralMemory?.dir ?? 'playbooks',
+                strictStartup: config?.proceduralMemory?.strictStartup ?? false,
+                pruneSqliteOnly: config?.proceduralMemory?.pruneSqliteOnly ?? false,
+                watch: config?.proceduralMemory?.watch ?? false,
+                watchDebounceMs: config?.proceduralMemory?.watchDebounceMs ?? 150,
+                watchUsePolling: config?.proceduralMemory?.watchUsePolling ?? false,
+                watchPollIntervalMs: config?.proceduralMemory?.watchPollIntervalMs ?? 100,
+                structuralDualWrite: {
+                    enabled: config?.proceduralMemory?.structuralDualWrite?.enabled ?? false,
+                    dir: config?.proceduralMemory?.structuralDualWrite?.dir ?? 'playbooks',
+                },
+            },
         };
         this.capacityConfig = { ...DEFAULT_CAPACITY, ...config?.capacity };
         // Core stores backed by SqlitePersistence
         this.experiences = new ExperienceMemory(persistence);
         this.playbooks = new PlaybookLibrary(persistence);
+        if (this.config.proceduralMemory.source === 'filesystem' ||
+            this.config.proceduralMemory.structuralDualWrite.enabled) {
+            const proceduralDir = this.config.proceduralMemory.source === 'filesystem'
+                ? this.config.proceduralMemory.dir
+                : this.config.proceduralMemory.structuralDualWrite.dir;
+            this.playbooks.setStructuralWriter(new ProceduralMemoryFileStore(resolveScopedProceduralPlaybookDir(baseDir, proceduralDir)));
+        }
         this.meta = new MetaMemory(persistence);
         this.reflexion = new ReflexionMemory(persistence);
-        this.causal = new CausalStore(persistence);
+        this.metaPlaybooks = new MetaPlaybookBank(join(baseDir, 'meta-playbooks'));
         // File-backed stores (not yet migrated to SqlitePersistence)
         this.effectiveness = new LearningEffectivenessTracker(baseDir);
-        this.teamExperiences = new TeamExperienceMemory(baseDir);
         // Initialize knowledge bank if enabled (stays as Markdown files)
         if (knowledgeBankConfig?.enabled) {
             const memoryDir = join(baseDir, knowledgeBankConfig.memoryDir ?? 'memory');
@@ -77,16 +128,116 @@ export class MemorySystem {
             this.playbooks.init(),
             this.meta.init(),
             this.effectiveness.init(),
-            this.teamExperiences.init(),
             this.reflexion.init(),
-            this.causal.init(),
+            this.metaPlaybooks.init(),
         ];
         if (this.knowledgeBank) {
             initPromises.push(this.knowledgeBank.init());
         }
         await Promise.all(initPromises);
+        await this.initProceduralFilesystem();
+        // Seed the meta-playbook bank with committed extraction/maintenance
+        // guidance. Idempotent — only seeds an empty bank, so learned refinements
+        // survive (default on; set memory.seedMetaPlaybooks=false to ablate).
+        if (this.config.seedMetaPlaybooks) {
+            await seedMetaPlaybookBank(this.metaPlaybooks);
+        }
+        // Seed MetaMemory routing priors so the router's meta-adjustment path is
+        // not inert on a cold store. Same idempotency contract: only seeds when
+        // no strategies exist, so learned strategies and accumulated application
+        // evidence are never clobbered.
+        if (this.config.seedMetaStrategies) {
+            await seedMetaStrategies(this.meta);
+        }
         this.initialized = true;
     }
+    async initProceduralFilesystem() {
+        let manifest;
+        try {
+            manifest = await readAtlasMemoryManifest(this.baseDir);
+        }
+        catch (error) {
+            const message = `Procedural memory manifest ignored: ${error instanceof Error ? error.message : String(error)}`;
+            if (this.config.proceduralMemory.strictStartup) {
+                throw new Error(message);
+            }
+            logger.warn(message);
+            manifest = null;
+        }
+        const manifestFileFirst = manifest?.canonicalStores?.procedural === 'filesystem';
+        const configFileFirst = this.config.proceduralMemory.source === 'filesystem';
+        if (!manifestFileFirst && !configFileFirst)
+            return;
+        const dir = manifest?.procedural?.dir ?? this.config.proceduralMemory.dir;
+        const strict = manifest?.procedural?.strictStartup ?? this.config.proceduralMemory.strictStartup;
+        const rootDir = resolveScopedProceduralPlaybookDir(this.baseDir, dir);
+        this.playbooks.setStructuralWriter(new ProceduralMemoryFileStore(rootDir));
+        const result = await reindexCanonicalPlaybookFiles(this.playbooks, rootDir);
+        if (result.rootMissing) {
+            // Expected on a fresh filesystem-mode boot: the playbook dir is created on
+            // first write. Debug, not warn — this used to spam a warning per cold Atlas.
+            logger.debug(`Procedural memory: canonical playbook directory not created yet at ${rootDir} (cold store; nothing to reindex).`);
+        }
+        const fileIds = new Set(result.playbooks.map((playbook) => playbook.id));
+        const sqliteOnly = (await this.playbooks.getAll()).filter((playbook) => !fileIds.has(playbook.id));
+        const warningCount = result.skipped.length + result.duplicateIds.length + sqliteOnly.length;
+        const pruneSqliteOnly = manifest?.procedural?.pruneSqliteOnly ?? this.config.proceduralMemory.pruneSqliteOnly;
+        // A missing canonical dir means no file-backed playbooks — never prune then,
+        // or every sqlite-only row (i.e. all of them) would be deleted.
+        const canPrune = !result.rootMissing && result.skipped.length === 0 && result.duplicateIds.length === 0;
+        const willPrune = !strict && pruneSqliteOnly && canPrune && sqliteOnly.length > 0;
+        if (warningCount === 0) {
+            await this.maybeStartCascade(rootDir);
+            return;
+        }
+        const message = [
+            `Procedural memory filesystem startup indexed ${result.indexed} file(s) with ${warningCount} warning(s).`,
+            ...result.skipped.map((issue) => {
+                const id = issue.id ? ` (${issue.id})` : '';
+                return `  ${issue.path}${id}: ${issue.message}`;
+            }),
+            ...result.duplicateIds.map((duplicate) => `  duplicate ${duplicate.id}: ${duplicate.paths.join(', ')}`),
+            ...sqliteOnly.map((playbook) => `  sqlite-only ${playbook.id}: no valid canonical SKILL.md file found${willPrune ? ' (pruned)' : ''}`),
+        ].join('\n');
+        if (strict) {
+            throw new Error(message);
+        }
+        if (willPrune) {
+            await pruneSqliteOnlyPlaybooks(this.playbooks, fileIds);
+        }
+        logger.warn(message);
+        await this.maybeStartCascade(rootDir);
+    }
+    /**
+     * Start the reindex-on-edit cascade over the canonical playbook tree, when
+     * enabled (`proceduralMemory.watch`). Idempotent and lazy — the watcher only
+     * runs for long-lived filesystem-mode processes; short-lived runs rely on the
+     * startup reindex above. The cascade drives derived rows through the
+     * structural-write-free `upsertCanonical`/`removeCanonical` so its own indexing
+     * never triggers another file event.
+     */
+    async maybeStartCascade(rootDir) {
+        if (this.cascade || !this.config.proceduralMemory.watch)
+            return;
+        const target = createPlaybookCascadeTarget({
+            root: rootDir,
+            reindexFile: async (path) => (await reindexCanonicalPlaybookFile(this.playbooks, path)).id,
+            removeEntity: async (id) => {
+                await this.playbooks.removeCanonical(id);
+            },
+        });
+        this.cascade = createFilesystemCascade(this.persistence, [target], {
+            debounceMs: this.config.proceduralMemory.watchDebounceMs,
+            usePolling: this.config.proceduralMemory.watchUsePolling,
+            pollIntervalMs: this.config.proceduralMemory.watchPollIntervalMs,
+            onError: (path, error) => logger.warn(`Procedural cascade error for ${path}: ${error instanceof Error ? error.message : String(error)}`),
+        });
+        await this.cascade.start();
+    }
+    /** The reindex-on-edit cascade, when running (filesystem + watch mode). */
+    get filesystemCascade() {
+        return this.cascade;
+    }
     /**
      * Query memory (legacy format)
      * @deprecated Use queryV2 for new code - this method returns empty arrays for deprecated fields
@@ -115,7 +266,7 @@ export class MemorySystem {
         // Handle undefined solution (e.g., from failed trajectories)
         const solutionOutput = trajectory.outcome.solution !== undefined
             ? JSON.stringify(trajectory.outcome.solution)
-            : trajectory.outcome.errorInfo ?? 'No solution (task failed)';
+            : (trajectory.outcome.errorInfo ?? 'No solution (task failed)');
         // Preserve trajectory structure in metadata for learning from intermediate steps
         const trajectoryMetadata = {
             // Preserve steps with key information (limited to prevent bloat)
@@ -144,9 +295,7 @@ export class MemorySystem {
         const experience = createExperience({
             taskInput: trajectory.task.description,
             solutionOutput,
-            feedback: trajectory.outcome.success
-                ? 'Success'
-                : trajectory.outcome.errorInfo ?? 'Failed',
+            feedback: trajectory.outcome.success ? 'Success' : (trajectory.outcome.errorInfo ?? 'Failed'),
             success: trajectory.outcome.success,
             domain: trajectory.task.domain,
             trajectoryId: trajectory.id,
@@ -167,28 +316,230 @@ export class MemorySystem {
     /**
      * Query memory with new playbook-based format
      */
+    /**
+     * Attach a pluggable embedding provider to experience retrieval, playbook
+     * matching, AND knowledge-note search. When set, retrieval scores by vector
+     * cosine (semantic) instead of lexical similarity. Providers: hash / local /
+     * openai / voyage.
+     *
+     * Options:
+     *   - `embedOnStore` (default true): embed items at write time so vectors are
+     *     persisted immediately. Set false for async-heavy providers (e.g. local
+     *     transformer) to avoid blocking the InstantLoop hot path — embeddings
+     *     will be computed lazily on first retrieval instead.
+     *   - `lexicalRetrieval` (default false): force Jaccard+trigram scoring even
+     *     when a provider is attached (ablation: `features.lexicalRetrieval`).
+     *     Applies uniformly across all three stores so A/B stays clean.
+     */
+    setEmbeddingProvider(provider, options) {
+        const embedOnStore = options?.embedOnStore ?? true;
+        const forceLexical = options?.lexicalRetrieval ?? false;
+        this.experiences.setEmbeddingProvider(provider, { embedOnStore });
+        this.playbooks.setEmbeddingProvider(provider);
+        this.playbooks.setForceLexical(forceLexical);
+        // KnowledgeBank: embedding wins over minimem auto-detect, unless the
+        // ablation forces lexical — then keep the TextSimilarity floor.
+        this.knowledgeBank?.setEmbeddingProvider(forceLexical ? null : provider);
+    }
+    setValidationControls(validation) {
+        this.validationControls = validation;
+    }
+    canRetrieve(channel) {
+        if (!this.validationControls?.enabled)
+            return true;
+        return this.validationControls.channelMasks.retrieval.includes(channel);
+    }
+    canServe(channel) {
+        if (!this.validationControls?.enabled)
+            return true;
+        return this.validationControls.channelMasks.serving.includes(channel);
+    }
     async queryV2(input, options) {
         await this.init();
         const includeAll = !options ||
-            (options.includeExperiences === undefined &&
-                options.includePlaybooks === undefined);
-        const [experiences, playbooks] = await Promise.all([
-            includeAll || options?.includeExperiences
+            (options.includeExperiences === undefined && options.includePlaybooks === undefined);
+        const playbookK = this.config.maxStrategies + this.config.maxSkills;
+        const useFrontier = this.config.frontierRouting &&
+            options?.taskSignature !== undefined &&
+            options.taskSignature.length > 0;
+        // Surface knowledge notes when the bank is enabled (opt-out via includeKnowledge=false).
+        const includeKnowledge = this.knowledgeBank !== null && (options?.includeKnowledge ?? true);
+        let retrievalDiagnostics;
+        const findPlaybooks = async () => {
+            if (!this.canRetrieve('playbooks') || !(includeAll || options?.includePlaybooks))
+                return [];
+            // Mode-aware relevance floor: embedding-cosine scores are denser than
+            // lexical, so semantic mode tolerates (and needs) a higher floor. The
+            // cross-domain fallback (below) multiplies this floor so out-of-family
+            // playbooks need a strong match — preventing the negative transfer seen
+            // when DCA playbooks were injected onto Embedded-Data-Repair tasks.
+            const semantic = this.playbooks.isSemanticScoring();
+            const baseFloor = options?.minPlaybookScore ??
+                (semantic
+                    ? this.config.playbookRetrieval.minScoreSemantic
+                    : this.config.playbookRetrieval.minScore);
+            const crossDomainFloor = Math.min(1, baseFloor * this.config.playbookRetrieval.crossDomainFloorMultiplier);
+            const retrievalMode = this.config.playbookRetrieval.mode;
+            const baseRetriever = retrievalMode === 'skill-tree-hybrid'
+                ? 'skill-tree-hybrid'
+                : useFrontier
+                    ? 'frontier'
+                    : 'legacy';
+            let rawCount = 0;
+            let filteredCount = 0;
+            let applicabilityExcludedCount = 0;
+            let domainFallbackUsed = false;
+            const candidateDecisions = [];
+            const normalizeDomain = (d) => d.toLowerCase().trim();
+            // Phase-0 instrumentation: record a decision row for every RAW candidate
+            // (before the score floor or applicability gate drop any), so rejected
+            // candidates keep their id/decision/reason. The gate is assessed here for
+            // the audit regardless of whether it is enforcing — gateEnforced records
+            // which. Ranking is per retrieval pass, by score descending.
+            const recordCandidates = (matches, floor, fallback) => {
+                const ranked = [...matches].sort((a, b) => b.score - a.score);
+                ranked.forEach((match, rank) => {
+                    const decision = assessPlaybookApplicability(match, {
+                        query: input,
+                        domains: options?.domains,
+                        config: this.config.playbookApplicability,
+                    });
+                    candidateDecisions.push({
+                        playbookId: match.playbook.id,
+                        playbookName: match.playbook.name,
+                        skillLevel: match.playbook.skillLevel,
+                        retrievalMethod: match.retrievalMethod,
+                        score: match.score,
+                        candidateRank: rank,
+                        domainFallbackUsed: fallback,
+                        scoreFloorPassed: match.score >= floor,
+                        rawDomains: match.playbook.applicability.domains,
+                        normalizedDomains: match.playbook.applicability.domains.map(normalizeDomain),
+                        taskDomains: (options?.domains ?? []).map(normalizeDomain),
+                        domainAliasOverlap: decision.domainAliasOverlap,
+                        cueHits: decision.cueHits,
+                        antiPatternHits: decision.antiPatternHits,
+                        decision: decision.decision,
+                        reason: decision.reason,
+                        gateEnforced: this.config.playbookApplicability.enabled,
+                    });
+                });
+            };
+            const applyScoreFloor = (matches, floor) => {
+                rawCount += matches.length;
+                const filtered = matches.filter((m) => m.score >= floor);
+                filteredCount += filtered.length;
+                return filtered;
+            };
+            const applyApplicabilityGate = (matches) => {
+                if (!this.config.playbookApplicability.enabled)
+                    return matches;
+                const kept = [];
+                for (const match of matches) {
+                    const decision = assessPlaybookApplicability(match, {
+                        query: input,
+                        domains: options?.domains,
+                        config: this.config.playbookApplicability,
+                    });
+                    const annotated = { ...match, applicabilityDecision: decision };
+                    if (decision.decision === 'use' || decision.decision === 'refine') {
+                        kept.push(annotated);
+                    }
+                    else {
+                        applicabilityExcludedCount++;
+                    }
+                }
+                return kept;
+            };
+            const buildDiagnostics = (floor) => ({
+                playbookRetriever: baseRetriever,
+                playbookMinScore: floor,
+                playbookRawCount: rawCount,
+                playbookFilteredCount: filteredCount,
+                playbookExcludedByScoreFloor: rawCount - filteredCount,
+                playbookExcludedByApplicability: applicabilityExcludedCount,
+                playbookDomainFallbackUsed: domainFallbackUsed,
+                playbookApplicabilityGateEnabled: this.config.playbookApplicability.enabled,
+                candidateDecisions: [...candidateDecisions],
+            });
+            const retrieve = async (domains) => {
+                const commonOptions = {
+                    k: playbookK,
+                    domains,
+                    minConfidence: options?.minPlaybookConfidence,
+                    excludeAntiPatterns: true,
+                };
+                if (retrievalMode === 'skill-tree-hybrid') {
+                    return this.playbooks.findMatchingSkillTreeHybrid(input, {
+                        ...commonOptions,
+                        fusion: this.config.playbookRetrieval.fusion,
+                    });
+                }
+                return useFrontier
+                    ? this.playbooks.findMatchingFrontierAware(input, options.taskSignature, {
+                        ...commonOptions,
+                        prefer: options?.prefer,
+                    })
+                    : this.playbooks.findMatching(input, commonOptions);
+            };
+            const commonOptions = {
+                k: playbookK,
+                domains: options?.domains,
+                minConfidence: options?.minPlaybookConfidence,
+                excludeAntiPatterns: true,
+            };
+            const rawInDomain = await retrieve(commonOptions.domains);
+            recordCandidates(rawInDomain, baseFloor, false);
+            const playbooks = applyApplicabilityGate(applyScoreFloor(rawInDomain, baseFloor));
+            // Only fall back to a global (cross-domain) scan when the in-domain query
+            // found NOTHING. If in-domain candidates existed but were dropped by the
+            // floor/gate, that was a real decision — a global fallback would re-surface
+            // cross-family playbooks the gate just rejected. Keying the fallback on
+            // post-gate emptiness produced a gate-induced fallback (observed live: a
+            // 50% EDR fallback rate caused purely by the gate emptying in-domain hits).
+            if (playbooks.length > 0 ||
+                rawInDomain.length > 0 ||
+                !options?.domains ||
+                options.domains.length === 0) {
+                retrievalDiagnostics = buildDiagnostics(baseFloor);
+                return playbooks;
+            }
+            // Extracted playbooks often carry semantic domains (e.g. logistics or
+            // compliance) while benchmark tasks use coarse routing domains (e.g.
+            // spreadsheet-audit). If exact-domain matching goes cold, retry globally
+            // and let the text/embedding score decide whether a playbook applies.
+            const fallbackOptions = {
+                ...commonOptions,
+                domains: undefined,
+            };
+            domainFallbackUsed = true;
+            const rawFallback = await retrieve(fallbackOptions.domains);
+            recordCandidates(rawFallback, crossDomainFloor, true);
+            const fallback = applyApplicabilityGate(applyScoreFloor(rawFallback, crossDomainFloor));
+            retrievalDiagnostics = buildDiagnostics(crossDomainFloor);
+            return fallback;
+        };
+        const [experiences, playbooks, knowledge] = await Promise.all([
+            this.canRetrieve('experiences') && (includeAll || options?.includeExperiences)
                 ? this.experiences.findSimilar(input, {
                     k: this.config.maxExperiences,
                     domain: options?.domains?.[0],
+                    // Success-biased exemplars: when failures are excluded from the
+                    // imitation channel, the agent only sees trajectories that worked.
+                    // Failures are still learned from elsewhere (reflexion / anti-
+                    // patterns / causal). See MemoryConfig.injectFailedExperiences.
+                    successOnly: this.config.injectFailedExperiences === false,
                 })
                 : Promise.resolve([]),
-            includeAll || options?.includePlaybooks
-                ? this.playbooks.findMatching(input, {
-                    k: this.config.maxStrategies + this.config.maxSkills, // Combined count
+            findPlaybooks(),
+            this.canRetrieve('knowledge') && includeKnowledge
+                ? this.knowledgeBank.search(input, {
                     domains: options?.domains,
-                    minConfidence: options?.minPlaybookConfidence,
-                    excludeAntiPatterns: true,
-                })
+                    maxResults: this.config.maxExperiences,
+                }).catch(() => [])
                 : Promise.resolve([]),
         ]);
-        return { experiences, playbooks };
+        return { experiences, playbooks, knowledge, retrievalDiagnostics };
     }
     /**
      * Format memory for context injection (new playbook format)
@@ -196,8 +547,9 @@ export class MemorySystem {
     formatForPromptV2(result, options) {
         const sections = [];
         const includeRefinements = options?.includeRefinements ?? true;
+        const incorporation = options?.incorporation ?? this.config.playbookRetrieval.incorporation;
         // Format experiences
-        if (result.experiences.length > 0) {
+        if (this.canServe('experiences') && result.experiences.length > 0) {
             sections.push('## Similar Experiences\n');
             for (const { experience, score } of result.experiences) {
                 sections.push(`### Task (${Math.round(score * 100)}% match)`);
@@ -208,21 +560,30 @@ export class MemorySystem {
             }
         }
         // Format playbooks
-        if (result.playbooks.length > 0) {
+        if (this.canServe('playbooks') && result.playbooks.length > 0) {
             sections.push('## Applicable Playbooks\n');
             for (const { playbook, score: _score, matchType } of result.playbooks) {
                 sections.push(`### ${playbook.name} (${Math.round(playbook.confidence * 100)}% confidence, matched on ${matchType})`);
-                sections.push(`**Strategy**: ${playbook.guidance.strategy}`);
-                if (playbook.guidance.tactics.length > 0) {
+                // Section-level incorporation: render only the task-relevant tactics/steps
+                // when configured (and a query is available). No-op for atomic playbooks.
+                const guidance = incorporation === 'sectioned' && options?.query
+                    ? sectionGuidanceForTask(playbook, options.query)
+                    : {
+                        strategy: playbook.guidance.strategy,
+                        tactics: playbook.guidance.tactics,
+                        steps: playbook.guidance.steps ?? [],
+                    };
+                sections.push(`**Strategy**: ${guidance.strategy}`);
+                if (guidance.tactics.length > 0) {
                     sections.push('**Tactics**:');
-                    for (const tactic of playbook.guidance.tactics) {
+                    for (const tactic of guidance.tactics) {
                         sections.push(`  - ${tactic}`);
                     }
                 }
-                if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+                if (guidance.steps.length > 0) {
                     sections.push('**Steps**:');
-                    for (let i = 0; i < playbook.guidance.steps.length; i++) {
-                        sections.push(`  ${i + 1}. ${playbook.guidance.steps[i]}`);
+                    for (let i = 0; i < guidance.steps.length; i++) {
+                        sections.push(`  ${i + 1}. ${guidance.steps[i]}`);
                     }
                 }
                 if (playbook.verification.successIndicators.length > 0) {
@@ -279,22 +640,17 @@ export class MemorySystem {
      */
     async getStats() {
         await this.init();
-        const [experienceCount, playbookCount, metaStats, annotationCount, teamStats] = await Promise.all([
+        const [experienceCount, playbookCount, metaStats, annotationCount] = await Promise.all([
             this.experiences.count(),
             this.playbooks.count(),
             this.meta.getStats(),
             this.effectiveness.count(),
-            this.teamExperiences.getStats(),
         ]);
         return {
             experienceCount,
             playbookCount,
             metaObservationCount: metaStats.totalObservations,
             annotationCount,
-            teamExperienceCount: teamStats.teamExperienceCount,
-            teamPlaybookCount: teamStats.teamPlaybookCount,
-            rolePlaybookCount: teamStats.rolePlaybookCount,
-            teamMetaObservationCount: teamStats.metaObservationCount,
         };
     }
     /**
@@ -325,12 +681,8 @@ export class MemorySystem {
             result.experiencesPruned = await this.experiences.prune({
                 maxCount: capacity.maxExperiences > 0 ? capacity.maxExperiences : undefined,
                 maxAgeDays: capacity.maxExperienceAgeDays > 0 ? capacity.maxExperienceAgeDays : undefined,
-                removeFailedOlderThanDays: capacity.maxFailedExperienceAgeDays > 0
-                    ? capacity.maxFailedExperienceAgeDays
-                    : undefined,
-                similarityThreshold: capacity.deduplicationThreshold > 0
-                    ? capacity.deduplicationThreshold
-                    : undefined,
+                removeFailedOlderThanDays: capacity.maxFailedExperienceAgeDays > 0 ? capacity.maxFailedExperienceAgeDays : undefined,
+                similarityThreshold: capacity.deduplicationThreshold > 0 ? capacity.deduplicationThreshold : undefined,
                 preserveDomainCoverage: capacity.preserveDomainCoverage,
             });
         }
@@ -338,11 +690,21 @@ export class MemorySystem {
         if (capacity.maxPlaybooks > 0) {
             const playbookCount = await this.playbooks.count();
             if (playbookCount > capacity.maxPlaybooks) {
-                // Prune lowest confidence playbooks
+                // Prune lowest confidence playbooks, but veto deletion of
+                // specialists — playbooks with uniqueWins on the Pareto frontier.
+                // Those playbooks are the only ones that beat their peers on
+                // some subset of work; killing them by global confidence ranking
+                // is exactly the specialist erasure GEPA's frontier prevents.
                 const allPlaybooks = await this.playbooks.getAll();
                 const sorted = allPlaybooks.sort((a, b) => b.confidence - a.confidence);
-                const toRemove = sorted.slice(capacity.maxPlaybooks);
-                for (const playbook of toRemove) {
+                const overflow = sorted.slice(capacity.maxPlaybooks);
+                for (const playbook of overflow) {
+                    const contribution = await this.playbooks.getFrontierContribution(playbook.id);
+                    if (contribution.uniqueWins > 0) {
+                        // Specialist: skip. It would take a replay-replacement step
+                        // (future Phase 2 work) to safely retire this playbook.
+                        continue;
+                    }
                     await this.playbooks.delete(playbook.id);
                     result.playbooksPruned++;
                 }
@@ -382,9 +744,7 @@ export class MemorySystem {
             playbooks: {
                 current: playbookCount,
                 limit: capacity.maxPlaybooks,
-                utilizationPercent: capacity.maxPlaybooks > 0
-                    ? Math.round((playbookCount / capacity.maxPlaybooks) * 100)
-                    : 0,
+                utilizationPercent: capacity.maxPlaybooks > 0 ? Math.round((playbookCount / capacity.maxPlaybooks) * 100) : 0,
             },
             pruningEnabled: capacity.autoPrune,
             lastCheck: this.lastCapacityCheck > 0 ? new Date(this.lastCapacityCheck) : null,
@@ -399,24 +759,20 @@ export class MemorySystem {
     /**
      * Close all stores
      */
-    /**
-     * Store a team trajectory and create a team experience
-     */
-    async storeTeamTrajectory(trajectory) {
-        await this.init();
-        return this.teamExperiences.storeTeamExperience({
-            teamTrajectory: trajectory,
-        });
-    }
     async close() {
+        // Stop the watcher first: its final flush drains through `playbooks`, which
+        // closes below, and through `persistence`, which Atlas closes after us.
+        if (this.cascade) {
+            await this.cascade.stop();
+            this.cascade = null;
+        }
         const closePromises = [
             this.experiences.close(),
             this.playbooks.close(),
             this.meta.close(),
             this.effectiveness.close(),
-            this.teamExperiences.close(),
             this.reflexion.close(),
-            this.causal.close(),
+            this.metaPlaybooks.close(),
         ];
         if (this.knowledgeBank) {
             closePromises.push(this.knowledgeBank.close());