crewly 1.0.0

package/dist/backend/backend/src/services/memory/goal-tracking.service.js

@@ -0,0 +1,353 @@
+/**
+ * Goal Tracking Service
+ *
+ * Manages project-level goal files, current team focus, and a decisions log
+ * with retrospective outcomes. All files are stored as Markdown under
+ * `{projectPath}/.crewly/goals/`.
+ *
+ * Files managed:
+ * - `goals.md` — Append-only log of user-stated goals
+ * - `current_focus.md` — Overwritten each time the team focus changes
+ * - `decisions_log.md` — Append-only decisions with mutable outcome sections
+ *
+ * @module services/memory/goal-tracking.service
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { ensureDir, atomicWriteFile } from '../../utils/file-io.utils.js';
+import { MEMORY_CONSTANTS } from '../../constants.js';
+import { LoggerService } from '../core/logger.service.js';
+/**
+ * Service for tracking project goals, team focus, and architectural decisions.
+ *
+ * Follows the singleton pattern for consistent state management across
+ * the backend. Uses atomic writes for full-file overwrites and plain
+ * `fs.appendFile` for append-only logs (goals, decisions) where partial
+ * writes are acceptable.
+ *
+ * @example
+ * ```typescript
+ * const goalService = GoalTrackingService.getInstance();
+ *
+ * // Set a project goal
+ * await goalService.setGoal('/path/to/project', 'Ship v2.0 by March 15th', 'user');
+ *
+ * // Update team focus
+ * await goalService.updateFocus('/path/to/project', 'Completing auth module');
+ *
+ * // Log a decision
+ * const decId = await goalService.logDecision('/path/to/project', {
+ *   title: 'Use PostgreSQL over MongoDB',
+ *   decision: 'PostgreSQL for primary data store',
+ *   rationale: 'Relational data model fits our schema better',
+ *   decidedBy: 'orchestrator',
+ *   alternatives: ['MongoDB', 'DynamoDB'],
+ * });
+ *
+ * // Later, record the outcome
+ * await goalService.updateDecisionOutcome(
+ *   '/path/to/project',
+ *   decId,
+ *   'Successful - query performance is excellent',
+ *   'Invest time in schema design upfront to avoid migrations',
+ * );
+ * ```
+ */
+export class GoalTrackingService {
+    static instance = null;
+    /** Monotonic counter to ensure unique decision IDs even within the same millisecond */
+    decisionCounter = 0;
+    logger = LoggerService.getInstance().createComponentLogger('GoalTrackingService');
+    /**
+     * Creates a new GoalTrackingService instance.
+     * Use {@link getInstance} for the singleton.
+     */
+    constructor() {
+        // No initialization needed — all paths are derived from projectPath at call time
+    }
+    /**
+     * Gets the singleton instance of GoalTrackingService.
+     *
+     * @returns The singleton GoalTrackingService instance
+     */
+    static getInstance() {
+        if (!GoalTrackingService.instance) {
+            GoalTrackingService.instance = new GoalTrackingService();
+        }
+        return GoalTrackingService.instance;
+    }
+    /**
+     * Clears the singleton instance.
+     * Intended for test isolation only — never call in production.
+     */
+    static clearInstance() {
+        GoalTrackingService.instance = null;
+    }
+    // ========================= HELPERS =========================
+    /**
+     * Returns the absolute path to the goals directory for a project.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns Absolute path to `{projectPath}/.crewly/goals`
+     */
+    getGoalsDir(projectPath) {
+        return path.join(projectPath, '.crewly', MEMORY_CONSTANTS.PATHS.GOALS_DIR);
+    }
+    /**
+     * Safely reads a file and returns its content, or `null` if the file
+     * does not exist.
+     *
+     * Permission errors and other unexpected failures are re-thrown.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns File content as a UTF-8 string, or `null` if not found
+     */
+    async safeReadFile(filePath) {
+        try {
+            return await fs.readFile(filePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    // ========================= PUBLIC INTERFACE =========================
+    /**
+     * Appends a new goal entry to `goals.md`.
+     *
+     * If the file does not yet exist it is created with a Markdown header
+     * before the first entry is appended.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param goal - The goal text to record
+     * @param setBy - Who set the goal (defaults to `'user'`)
+     *
+     * @example
+     * ```typescript
+     * await goalService.setGoal('/projects/phoenix', 'Achieve 80% test coverage', 'user');
+     * ```
+     */
+    async setGoal(projectPath, goal, setBy = 'user') {
+        const goalsDir = this.getGoalsDir(projectPath);
+        await ensureDir(goalsDir);
+        const goalsFile = path.join(goalsDir, MEMORY_CONSTANTS.PATHS.GOALS_FILE);
+        const existing = await this.safeReadFile(goalsFile);
+        const timestamp = new Date().toISOString();
+        const entry = `\n### [${timestamp}] Set by ${setBy}\n${goal}\n`;
+        if (existing === null) {
+            const header = `# Project Goals\n\n`;
+            await fs.writeFile(goalsFile, header + entry, 'utf-8');
+            this.logger.debug('Created goals file with first entry', { projectPath, setBy });
+        }
+        else {
+            await fs.appendFile(goalsFile, entry, 'utf-8');
+            this.logger.debug('Appended goal entry', { projectPath, setBy });
+        }
+    }
+    /**
+     * Reads and returns the full contents of `goals.md`.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The goals file content, or `null` if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const goals = await goalService.getGoals('/projects/phoenix');
+     * if (goals) {
+     *   console.log(goals);
+     * }
+     * ```
+     */
+    async getGoals(projectPath) {
+        const goalsFile = path.join(this.getGoalsDir(projectPath), MEMORY_CONSTANTS.PATHS.GOALS_FILE);
+        return this.safeReadFile(goalsFile);
+    }
+    /**
+     * Overwrites `current_focus.md` with the new focus description.
+     *
+     * Uses {@link atomicWriteFile} to ensure the file is never left in a
+     * partial-write state.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param focus - The new focus description
+     * @param updatedBy - Who updated the focus (defaults to `'orchestrator'`)
+     *
+     * @example
+     * ```typescript
+     * await goalService.updateFocus(
+     *   '/projects/phoenix',
+     *   'Completing the authentication module and writing integration tests',
+     *   'orchestrator',
+     * );
+     * ```
+     */
+    async updateFocus(projectPath, focus, updatedBy = 'orchestrator') {
+        const goalsDir = this.getGoalsDir(projectPath);
+        await ensureDir(goalsDir);
+        const focusFile = path.join(goalsDir, MEMORY_CONSTANTS.PATHS.FOCUS_FILE);
+        const timestamp = new Date().toISOString();
+        const content = `# Current Focus\n` +
+            `\n` +
+            `**Updated:** ${timestamp}\n` +
+            `**By:** ${updatedBy}\n` +
+            `\n` +
+            `${focus}\n`;
+        await atomicWriteFile(focusFile, content);
+        this.logger.debug('Updated current focus', { projectPath, updatedBy });
+    }
+    /**
+     * Reads and returns the full contents of `current_focus.md`.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The current focus file content, or `null` if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const focus = await goalService.getCurrentFocus('/projects/phoenix');
+     * ```
+     */
+    async getCurrentFocus(projectPath) {
+        const focusFile = path.join(this.getGoalsDir(projectPath), MEMORY_CONSTANTS.PATHS.FOCUS_FILE);
+        return this.safeReadFile(focusFile);
+    }
+    /**
+     * Appends a new decision entry to `decisions_log.md` and returns a
+     * unique decision ID.
+     *
+     * If the file does not yet exist it is created with a Markdown header
+     * before the first entry is appended.
+     *
+     * The outcome field is initially set to `_pending_` and can be updated
+     * later via {@link updateDecisionOutcome}.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param decision - Decision parameters (title, decision, rationale, etc.)
+     * @returns The generated decision ID (format: `dec-{timestamp}-{counter}`)
+     *
+     * @throws {Error} If the file system write fails
+     *
+     * @example
+     * ```typescript
+     * const decisionId = await goalService.logDecision('/projects/phoenix', {
+     *   title: 'Use Redis for caching',
+     *   decision: 'Redis over Memcached',
+     *   rationale: 'Better data structure support and persistence options',
+     *   decidedBy: 'orchestrator',
+     *   alternatives: ['Memcached', 'In-memory Map'],
+     * });
+     * // decisionId => 'dec-1707500000000-0'
+     * ```
+     */
+    async logDecision(projectPath, decision) {
+        const goalsDir = this.getGoalsDir(projectPath);
+        await ensureDir(goalsDir);
+        const decisionsFile = path.join(goalsDir, MEMORY_CONSTANTS.PATHS.DECISIONS_LOG);
+        const existing = await this.safeReadFile(decisionsFile);
+        const timestamp = new Date().toISOString();
+        const decisionId = `dec-${Date.now()}-${this.decisionCounter++}`;
+        const alternativesText = decision.alternatives?.join(', ') || 'None recorded';
+        const entry = `\n## [${decisionId}] ${decision.title}\n` +
+            `**Date:** ${timestamp}\n` +
+            `**By:** ${decision.decidedBy}\n` +
+            `**Decision:** ${decision.decision}\n` +
+            `**Rationale:** ${decision.rationale}\n` +
+            `**Alternatives:** ${alternativesText}\n` +
+            `**Outcome:** _pending_\n` +
+            `\n---\n`;
+        if (existing === null) {
+            const header = `# Decisions Log\n\n`;
+            await fs.writeFile(decisionsFile, header + entry, 'utf-8');
+            this.logger.debug('Created decisions log with first entry', { projectPath, decisionId });
+        }
+        else {
+            await fs.appendFile(decisionsFile, entry, 'utf-8');
+            this.logger.debug('Appended decision entry', { projectPath, decisionId });
+        }
+        return decisionId;
+    }
+    /**
+     * Updates the outcome of a previously logged decision.
+     *
+     * Reads `decisions_log.md`, locates the section matching the given
+     * `decisionId`, replaces the `**Outcome:** _pending_` line with the
+     * actual outcome (plus optional learnings and a timestamp), and writes
+     * the file back atomically.
+     *
+     * If the decision ID is not found or the file does not exist, a warning
+     * is logged and the method returns without throwing.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param decisionId - The decision ID returned by {@link logDecision}
+     * @param outcome - Description of the actual outcome
+     * @param learnings - Optional lessons learned from this decision
+     *
+     * @example
+     * ```typescript
+     * await goalService.updateDecisionOutcome(
+     *   '/projects/phoenix',
+     *   'dec-1707500000000',
+     *   'Successful - Redis reduced API latency by 40%',
+     *   'Set explicit TTLs on all cache keys to prevent stale data',
+     * );
+     * ```
+     */
+    async updateDecisionOutcome(projectPath, decisionId, outcome, learnings) {
+        const decisionsFile = path.join(this.getGoalsDir(projectPath), MEMORY_CONSTANTS.PATHS.DECISIONS_LOG);
+        const content = await this.safeReadFile(decisionsFile);
+        if (content === null) {
+            this.logger.warn('Decisions log not found, cannot update outcome', { projectPath, decisionId });
+            return;
+        }
+        // Verify the decision ID exists in the file
+        if (!content.includes(`[${decisionId}]`)) {
+            this.logger.warn('Decision ID not found in decisions log', { projectPath, decisionId });
+            return;
+        }
+        const timestamp = new Date().toISOString();
+        const learningsText = learnings || 'None recorded';
+        const replacement = `**Outcome:** ${outcome}\n` +
+            `**Learnings:** ${learningsText}\n` +
+            `**Recorded:** ${timestamp}`;
+        // Replace the first occurrence of _pending_ that belongs to this decision.
+        // We find the decision section header then replace the pending outcome within it.
+        const sectionMarker = `[${decisionId}]`;
+        const sectionStart = content.indexOf(sectionMarker);
+        if (sectionStart === -1) {
+            this.logger.warn('Decision section not found', { projectPath, decisionId });
+            return;
+        }
+        // Find the **Outcome:** _pending_ line within this decision's section
+        const pendingPattern = '**Outcome:** _pending_';
+        const pendingIndex = content.indexOf(pendingPattern, sectionStart);
+        if (pendingIndex === -1) {
+            this.logger.warn('Decision outcome already recorded or not in pending state', { projectPath, decisionId });
+            return;
+        }
+        const updatedContent = content.substring(0, pendingIndex) +
+            replacement +
+            content.substring(pendingIndex + pendingPattern.length);
+        await atomicWriteFile(decisionsFile, updatedContent);
+        this.logger.debug('Updated decision outcome', { projectPath, decisionId });
+    }
+    /**
+     * Reads and returns the full contents of `decisions_log.md`.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The decisions log content, or `null` if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const log = await goalService.getDecisionsLog('/projects/phoenix');
+     * if (log) {
+     *   console.log(log);
+     * }
+     * ```
+     */
+    async getDecisionsLog(projectPath) {
+        const decisionsFile = path.join(this.getGoalsDir(projectPath), MEMORY_CONSTANTS.PATHS.DECISIONS_LOG);
+        return this.safeReadFile(decisionsFile);
+    }
+}
+//# sourceMappingURL=goal-tracking.service.js.map

package/dist/backend/backend/src/services/memory/goal-tracking.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-tracking.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/goal-tracking.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/memory/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Memory Services Module
+ *
+ * Provides services for managing agent and project memory.
+ *
+ * @module services/memory
+ */
+export { AgentMemoryService, type IAgentMemoryService, type TaskCompletionMetrics } from './agent-memory.service.js';
+export { ProjectMemoryService, type IProjectMemoryService, type SearchResults } from './project-memory.service.js';
+export { MemoryService, type IMemoryService, type RememberParams, type RecallParams, type RecallResult, type LearningParams, type RememberCategory, type MemoryScope as UnifiedMemoryScope } from './memory.service.js';
+export { SessionMemoryService } from './session-memory.service.js';
+export { DailyLogService } from './daily-log.service.js';
+export { GoalTrackingService } from './goal-tracking.service.js';
+export { LearningAccumulationService } from './learning-accumulation.service.js';
+export type { AgentMemory, ProjectMemory, RoleKnowledgeEntry, PatternEntry, DecisionEntry, GotchaEntry, RelationshipEntry, LearningEntry, AgentPreferences, PerformanceMetrics, MemoryQueryOptions, MemoryQueryResult, MemoryScope, RoleKnowledgeCategory, PatternCategory, GotchaSeverity, RelationshipType, LearningCategory, SessionSummary, StartupBriefing, AgentIndexEntry, ProjectAgentsIndex, DailyLogEntry, LearningAccumulationEntry, } from '../../types/memory.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/backend/src/services/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACrH,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACnH,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,IAAI,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxN,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGjF,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC"}

package/dist/backend/backend/src/services/memory/index.js

@@ -0,0 +1,15 @@
+/**
+ * Memory Services Module
+ *
+ * Provides services for managing agent and project memory.
+ *
+ * @module services/memory
+ */
+export { AgentMemoryService } from './agent-memory.service.js';
+export { ProjectMemoryService } from './project-memory.service.js';
+export { MemoryService } from './memory.service.js';
+export { SessionMemoryService } from './session-memory.service.js';
+export { DailyLogService } from './daily-log.service.js';
+export { GoalTrackingService } from './goal-tracking.service.js';
+export { LearningAccumulationService } from './learning-accumulation.service.js';
+//# sourceMappingURL=index.js.map

package/dist/backend/backend/src/services/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAwD,MAAM,2BAA2B,CAAC;AACrH,OAAO,EAAE,oBAAoB,EAAkD,MAAM,6BAA6B,CAAC;AACnH,OAAO,EAAE,aAAa,EAAsK,MAAM,qBAAqB,CAAC;AACxN,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/backend/backend/src/services/memory/learning-accumulation.service.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Learning Accumulation Service
+ *
+ * Manages persistent learning files at two levels:
+ * - **Project-level:** `{projectPath}/.crewly/learning/what_worked.md` and `what_failed.md`
+ * - **Global-level:** `~/.crewly/learning/cross_project_insights.md`
+ *
+ * Learning entries are appended as timestamped markdown sections so agents can
+ * review past successes, failures, and cross-project insights when starting
+ * new tasks or resuming work.
+ *
+ * @module services/memory/learning-accumulation.service
+ */
+/**
+ * Service for accumulating learning entries into markdown files
+ *
+ * Follows the singleton pattern for consistent state management.
+ * Entries are appended atomically using `fs.appendFile` so concurrent
+ * writes from different agents do not corrupt the file.
+ *
+ * @example
+ * ```typescript
+ * const learningService = LearningAccumulationService.getInstance();
+ * await learningService.recordSuccess(
+ *   '/home/user/my-project',
+ *   'dev-001',
+ *   'developer',
+ *   'Parallel test execution reduced CI time by 40%',
+ *   'Applied to Jest with --maxWorkers=4'
+ * );
+ * ```
+ */
+export declare class LearningAccumulationService {
+    private static instance;
+    private readonly logger;
+    /**
+     * Private constructor to enforce singleton usage
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of LearningAccumulationService
+     *
+     * @returns The singleton LearningAccumulationService instance
+     */
+    static getInstance(): LearningAccumulationService;
+    /**
+     * Clears the singleton instance (useful for testing)
+     */
+    static clearInstance(): void;
+    /**
+     * Returns the absolute path to a project's learning directory
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns Absolute path to `{projectPath}/.crewly/learning`
+     */
+    private getLearningDir;
+    /**
+     * Returns the absolute path to the global learning directory
+     *
+     * @returns Absolute path to `~/.crewly/learning`
+     */
+    private getGlobalLearningDir;
+    /**
+     * Reads a file and returns its content, or null if the file does not exist
+     *
+     * Permission errors and other unexpected I/O failures are propagated.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns File content as a string, or null when the file is missing
+     */
+    private safeReadFile;
+    /**
+     * Formats a learning entry as a markdown section
+     *
+     * The resulting block uses a level-3 heading with an ISO timestamp,
+     * followed by the description and optional context, terminated by
+     * a horizontal rule separator.
+     *
+     * @param agentId - Identifier of the agent that produced the learning
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of the learning
+     * @param context - Optional additional context or notes
+     * @returns Formatted markdown entry string
+     *
+     * @example
+     * ```typescript
+     * const entry = this.formatEntry('dev-001', 'developer', 'Tests pass faster with parallelism');
+     * // ### [2026-02-09T12:00:00.000Z] developer / dev-001
+     * // Tests pass faster with parallelism
+     * // Context: None
+     * //
+     * // ---
+     * ```
+     */
+    private formatEntry;
+    /**
+     * Ensures a learning file exists, creating it with the provided header if missing
+     *
+     * @param filePath - Absolute path to the markdown file
+     * @param header - Header content to write when creating the file
+     */
+    private ensureFileWithHeader;
+    /**
+     * Records a successful pattern, approach, or solution to the project's
+     * `what_worked.md` learning file
+     *
+     * If the learning directory or file does not exist it is created automatically.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param agentId - Identifier of the agent recording the success
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of what worked
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordSuccess(
+     *   '/home/user/my-project',
+     *   'dev-001',
+     *   'developer',
+     *   'Using database transactions for batch inserts prevented partial writes',
+     *   'PostgreSQL with pg-promise library'
+     * );
+     * ```
+     */
+    recordSuccess(projectPath: string, agentId: string, role: string, description: string, context?: string): Promise<void>;
+    /**
+     * Records a failed approach, pitfall, or mistake to the project's
+     * `what_failed.md` learning file
+     *
+     * If the learning directory or file does not exist it is created automatically.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param agentId - Identifier of the agent recording the failure
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of what failed
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordFailure(
+     *   '/home/user/my-project',
+     *   'qa-001',
+     *   'qa',
+     *   'Snapshot tests broke on every UI change, causing CI churn',
+     *   'Replaced with visual regression tests'
+     * );
+     * ```
+     */
+    recordFailure(projectPath: string, agentId: string, role: string, description: string, context?: string): Promise<void>;
+    /**
+     * Records a cross-project insight to the global
+     * `~/.crewly/learning/cross_project_insights.md` file
+     *
+     * Cross-project insights capture learnings that are not specific to a
+     * single project and can inform agent behaviour across the entire workspace.
+     *
+     * @param agentId - Identifier of the agent recording the insight
+     * @param role - Role of the agent (e.g. 'developer', 'qa')
+     * @param description - Human-readable description of the insight
+     * @param context - Optional additional context or notes
+     *
+     * @example
+     * ```typescript
+     * await learningService.recordCrossProjectInsight(
+     *   'dev-002',
+     *   'developer',
+     *   'TypeScript strict mode catches 30% more bugs at compile time',
+     *   'Observed across 4 projects in Q1 2026'
+     * );
+     * ```
+     */
+    recordCrossProjectInsight(agentId: string, role: string, description: string, context?: string): Promise<void>;
+    /**
+     * Reads the project's `what_worked.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts that need
+     * only the most recent entries.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * // Get full file
+     * const all = await learningService.getSuccesses('/home/user/project');
+     *
+     * // Get last 2000 chars for a briefing
+     * const recent = await learningService.getSuccesses('/home/user/project', 2000);
+     * ```
+     */
+    getSuccesses(projectPath: string, tailChars?: number): Promise<string | null>;
+    /**
+     * Reads the project's `what_failed.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts that need
+     * only the most recent entries.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const failures = await learningService.getFailures('/home/user/project', 1500);
+     * ```
+     */
+    getFailures(projectPath: string, tailChars?: number): Promise<string | null>;
+    /**
+     * Reads the global `cross_project_insights.md` learning file
+     *
+     * When `tailChars` is specified only the last N characters of the file
+     * are returned, which is useful for startup briefing prompts.
+     *
+     * @param tailChars - Optional maximum number of trailing characters to return
+     * @returns File content (or tail thereof), or null if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const insights = await learningService.getCrossProjectInsights(3000);
+     * ```
+     */
+    getCrossProjectInsights(tailChars?: number): Promise<string | null>;
+}
+//# sourceMappingURL=learning-accumulation.service.d.ts.map

package/dist/backend/backend/src/services/memory/learning-accumulation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-accumulation.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/learning-accumulation.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA4C;IAEnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoF;IAE3G;;OAEG;IACH,OAAO;IAIP;;;;OAIG;WACW,WAAW,IAAI,2BAA2B;IAOxD;;OAEG;WACW,aAAa,IAAI,IAAI;IAMnC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAQtB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;OAOG;YACW,YAAY;IAW1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;;OAKG;YACW,oBAAoB;IASlC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,aAAa,CACxB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,aAAa,CACxB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,yBAAyB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;;;;;;;;;;;;OAmBG;IACU,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB1F;;;;;;;;;;;;;;;OAeG;IACU,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkBzF;;;;;;;;;;;;;OAaG;IACU,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAiBjF"}