crewly 1.6.4 → 1.7.0

package/dist/backend/backend/src/services/memory/mission-context.service.js

@@ -0,0 +1,365 @@
+/**
+ * Mission Context Service — auto-injectable mission card for agent prompts.
+ *
+ * Builds a compact (≤2KB) markdown card that summarizes the active
+ * project OKR, the team's most-relevant active missions, and the team
+ * sub-OKR (if any) so every agent wakes with the answer to "what
+ * mission am I serving right now?".
+ *
+ * Per Memory Phase 1 / Fix M1: today, agents must call `recall` or
+ * `get_goals` explicitly to find the mission they're serving — and per
+ * the architecture audit, an agent can finish a sprint without ever
+ * reading it. This service closes that gap by feeding a tiny mission
+ * card into prompt assembly automatically.
+ *
+ * Out of scope for Phase 1 (deferred to later phases):
+ *   - Narrative summarization of mission state (no LLM round-trip here)
+ *   - Vector embedding / semantic recall
+ *   - Memory review queue / supersession
+ *
+ * @module services/memory/mission-context.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { LoggerService } from '../core/logger.service.js';
+import { GoalTrackingService } from './goal-tracking.service.js';
+import { sortMissionsByPriority, } from '../../types/v2/mission.types.js';
+import { MEMORY_CONSTANTS } from '../../constants.js';
+// ---------------------------------------------------------------------------
+// Tunables
+// ---------------------------------------------------------------------------
+/**
+ * Hard upper bound on the rendered mission card. The spec calls for
+ * 1-2KB; we cap at 2KB and truncate by section priority (most-recent
+ * status → oldest first) when over budget.
+ */
+export const MISSION_CONTEXT_HARD_CAP_BYTES = 2048;
+/** Maximum lines extracted from `goals.md` for the project-OKR slice. */
+const GOALS_MAX_LINES = 4;
+/** Maximum active missions to surface per call (sorted by priority + recency). */
+const MAX_MISSIONS = 2;
+/** Maximum status updates surfaced under "Recent Mission Status". */
+const MAX_STATUS_UPDATES = 3;
+/** Maximum lines extracted from the team sub-OKR file. */
+const TEAM_SUB_OKR_MAX_LINES = 4;
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Builds a small markdown card describing the agent's mission context.
+ *
+ * Singleton, side-effect-free reads. All file IO is fail-soft: any
+ * read or parse error skips the affected section but never throws into
+ * the prompt-assembly path.
+ *
+ * @example
+ * ```ts
+ * const svc = MissionContextService.getInstance();
+ * const card = await svc.getContextForAgent({
+ *   agentId: 'crewly-product-leo-21a5477e',
+ *   projectPath: '/Users/me/projects/crewly',
+ *   teamId: '28a4ac10-...',
+ *   teamSlug: 'product',
+ * });
+ * if (card) prompt += `\n${card}`;
+ * ```
+ */
+export class MissionContextService {
+    static instance = null;
+    logger;
+    goalService;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('MissionContextService');
+        this.goalService = GoalTrackingService.getInstance();
+    }
+    /** Get the shared singleton instance. */
+    static getInstance() {
+        if (!MissionContextService.instance) {
+            MissionContextService.instance = new MissionContextService();
+        }
+        return MissionContextService.instance;
+    }
+    /** Reset for tests. */
+    static clearInstance() {
+        MissionContextService.instance = null;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Build the mission-context card for an agent.
+     *
+     * Returns the empty string when no signals are available — callers
+     * should treat empty output as "skip the section entirely" rather
+     * than rendering an empty heading.
+     *
+     * @param req - Request inputs
+     * @returns A ≤2KB markdown card, or `''` when nothing is worth showing
+     */
+    async getContextForAgent(req) {
+        const goalsLines = await this.loadProjectGoalsSlice(req.projectPath);
+        // Filter accepts the agent's own team plus any ancestors (parent OKRs).
+        // De-duped at the call site; service treats the resulting set as the
+        // authoritative match list.
+        const teamScope = uniqueNonEmpty([req.teamId, ...(req.ancestorTeamIds ?? [])]);
+        const missions = await this.loadActiveTeamMissions(req.projectPath, teamScope);
+        const teamSubOkrLines = await this.loadTeamSubOkrSlice(req.projectPath, req.teamSlug);
+        const statusUpdates = collectRecentStatusUpdates(missions);
+        if (goalsLines.length === 0 &&
+            missions.length === 0 &&
+            teamSubOkrLines.length === 0 &&
+            statusUpdates.length === 0) {
+            this.logger.debug('No mission signals — emitting empty card', {
+                agentId: req.agentId,
+                teamId: req.teamId,
+            });
+            return '';
+        }
+        const card = renderMissionCard({
+            goalsLines,
+            missions: missions.slice(0, MAX_MISSIONS),
+            teamSubOkrLines,
+            statusUpdates: statusUpdates.slice(0, MAX_STATUS_UPDATES),
+        });
+        const capped = enforceHardCap(card, MISSION_CONTEXT_HARD_CAP_BYTES);
+        this.logger.debug('Mission card built', {
+            agentId: req.agentId,
+            teamId: req.teamId,
+            bytes: Buffer.byteLength(capped, 'utf-8'),
+            missionCount: missions.length,
+        });
+        return capped;
+    }
+    // -------------------------------------------------------------------------
+    // Internal readers (each one fail-soft — never throws)
+    // -------------------------------------------------------------------------
+    /**
+     * Read up to `GOALS_MAX_LINES` non-empty, non-comment lines from
+     * the project's `goals.md`. Returns `[]` when the file is missing.
+     */
+    async loadProjectGoalsSlice(projectPath) {
+        try {
+            const raw = await this.goalService.getGoals(projectPath);
+            if (!raw)
+                return [];
+            return extractMeaningfulLines(raw, GOALS_MAX_LINES);
+        }
+        catch (err) {
+            this.logger.warn('Failed to load project goals.md', {
+                projectPath,
+                error: errMsg(err),
+            });
+            return [];
+        }
+    }
+    /**
+     * Read all `*.json` files under `<projectPath>/.crewly/missions/`,
+     * filter to active missions whose `ownerTeamId` is in the supplied
+     * `teamScope` (own team + any ancestor teams the caller passed in),
+     * and sort by priority + recency. Returns `[]` on any error.
+     */
+    async loadActiveTeamMissions(projectPath, teamScope) {
+        if (teamScope.length === 0)
+            return [];
+        const dir = path.join(projectPath, '.crewly', 'missions');
+        let files;
+        try {
+            files = await fs.readdir(dir);
+        }
+        catch {
+            // Directory missing == no missions == empty section. Not an error.
+            return [];
+        }
+        const scope = new Set(teamScope);
+        const missions = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(dir, file), 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed.status === 'active' && scope.has(parsed.ownerTeamId)) {
+                    missions.push(parsed);
+                }
+            }
+            catch (err) {
+                this.logger.debug('Skipping unreadable mission file', {
+                    file,
+                    error: errMsg(err),
+                });
+            }
+        }
+        return sortMissionsByPriority(missions);
+    }
+    /**
+     * Read the team sub-OKR file at
+     * `<projectPath>/.crewly/goals/<teamSlug>-team-sub-okr.md`. Returns
+     * `[]` when no slug, no file, or any read error.
+     */
+    async loadTeamSubOkrSlice(projectPath, teamSlug) {
+        if (!teamSlug)
+            return [];
+        const filePath = path.join(projectPath, '.crewly', MEMORY_CONSTANTS.PATHS.GOALS_DIR, `${teamSlug}-team-sub-okr.md`);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            return extractMeaningfulLines(raw, TEAM_SUB_OKR_MAX_LINES);
+        }
+        catch {
+            // Missing file is the common case — skip silently.
+            return [];
+        }
+    }
+}
+/**
+ * Collect the most recent status updates across the supplied missions.
+ * A mission contributes at most one entry. Missions with no
+ * `lastReviewSummary` are skipped. Result is sorted by `lastReviewAt`
+ * descending; missions with no `lastReviewAt` sort last.
+ */
+export function collectRecentStatusUpdates(missions) {
+    const updates = [];
+    for (const m of missions) {
+        if (!m.lastReviewSummary)
+            continue;
+        updates.push({
+            missionId: m.id,
+            objective: m.objective,
+            summary: m.lastReviewSummary,
+            reviewedAt: m.lastReviewAt,
+        });
+    }
+    updates.sort((a, b) => {
+        const ta = a.reviewedAt ? Date.parse(a.reviewedAt) : 0;
+        const tb = b.reviewedAt ? Date.parse(b.reviewedAt) : 0;
+        return tb - ta;
+    });
+    return updates;
+}
+/**
+ * Extract up to `maxLines` "meaningful" lines from a markdown blob.
+ *
+ * Rules:
+ *   - skip empty lines
+ *   - skip standalone HTML/MD comments
+ *   - keep headings, prose, list items
+ *   - trim trailing whitespace
+ *   - de-duplicate consecutive identical lines
+ */
+export function extractMeaningfulLines(raw, maxLines) {
+    const out = [];
+    let lastPushed = '';
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (!line.trim())
+            continue;
+        if (/^\s*<!--.*-->\s*$/.test(line))
+            continue;
+        if (line === lastPushed)
+            continue;
+        out.push(line);
+        lastPushed = line;
+        if (out.length >= maxLines)
+            break;
+    }
+    return out;
+}
+/**
+ * Render the final mission card as markdown using the spec template.
+ * Sections with no data are omitted entirely (no empty headings).
+ */
+export function renderMissionCard(args) {
+    const { goalsLines, missions, teamSubOkrLines, statusUpdates } = args;
+    const sections = ['## Current Mission Context', ''];
+    if (goalsLines.length > 0) {
+        sections.push('Active Project OKR (90-day):');
+        for (const line of goalsLines)
+            sections.push(line);
+        sections.push('');
+    }
+    if (missions.length > 0) {
+        sections.push('Current Active Missions:');
+        for (const m of missions) {
+            sections.push(`- ${formatMissionLine(m)}`);
+        }
+        sections.push('');
+    }
+    if (teamSubOkrLines.length > 0) {
+        sections.push("Your Team's Sub-OKR:");
+        for (const line of teamSubOkrLines)
+            sections.push(line);
+        sections.push('');
+    }
+    if (statusUpdates.length > 0) {
+        sections.push('Recent Mission Status:');
+        for (const u of statusUpdates) {
+            sections.push(`- ${formatStatusLine(u)}`);
+        }
+        sections.push('');
+    }
+    // Trim trailing blank line for tidiness
+    while (sections.length > 0 && sections[sections.length - 1] === '') {
+        sections.pop();
+    }
+    return sections.join('\n');
+}
+/**
+ * Format one mission as a single line: priority + objective +
+ * top-of-success-criteria summary.
+ */
+function formatMissionLine(m) {
+    const priority = m.priority ?? 'medium';
+    const tail = m.successCriteria?.length > 0 ? ` — ${m.successCriteria[0]}` : '';
+    return `[${priority}] ${m.objective}${tail}`;
+}
+/** Format one status update as a single bullet. */
+function formatStatusLine(u) {
+    const date = u.reviewedAt ? u.reviewedAt.slice(0, 10) : '—';
+    return `${date}: ${u.objective} — ${u.summary}`;
+}
+/**
+ * Enforce the hard byte cap. If `card` already fits, returns it
+ * unchanged. Otherwise truncates line-by-line from the bottom until
+ * it fits, then appends a single ellipsis line so the card is
+ * obviously truncated.
+ */
+export function enforceHardCap(card, maxBytes) {
+    if (Buffer.byteLength(card, 'utf-8') <= maxBytes)
+        return card;
+    const lines = card.split('\n');
+    const ellipsis = '… (truncated to fit 2KB cap)';
+    while (lines.length > 0) {
+        lines.pop();
+        const candidate = `${lines.join('\n')}\n${ellipsis}`;
+        if (Buffer.byteLength(candidate, 'utf-8') <= maxBytes) {
+            return candidate;
+        }
+    }
+    // Even the heading didn't fit — return just the ellipsis.
+    return ellipsis;
+}
+/** Stringify an unknown error for log fields. */
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Return the input array de-duplicated and stripped of empty / falsy
+ * entries while preserving first-seen order.
+ */
+function uniqueNonEmpty(values) {
+    const out = [];
+    const seen = new Set();
+    for (const v of values) {
+        if (!v)
+            continue;
+        if (seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+/**
+ * Module-level convenience: get the singleton in one call.
+ */
+export const getMissionContextService = () => MissionContextService.getInstance();
+//# sourceMappingURL=mission-context.service.js.map

package/dist/backend/backend/src/services/memory/mission-context.service.js.map

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

package/dist/backend/backend/src/services/memory/role-knowledge-eligibility.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Role-knowledge recall-eligibility helpers (M3 — Memory Importance,
+ * Confidence, Evidence + lifecycle filtering).
+ *
+ * Implements the recall-eligibility rules from
+ * `.crewly/specs/2026-05-03-memory-codebase-improvement-plan.md` §183-187:
+ *
+ * | Rule                                              | Effect                                  |
+ * | ------------------------------------------------- | --------------------------------------- |
+ * | importance ≥ 0.85 AND confidence ≥ 0.7            | Eligible for auto-inject into context   |
+ * | confidence < 0.5                                  | NEVER auto-inject (explicit recall only)|
+ * | supersededBy != null                              | Hidden from default recall (audit-only) |
+ * | ttl < now                                         | Archived, hidden from recall            |
+ * | shouldInjectByDefault === false                   | Hidden from default recall              |
+ * | shouldInjectByDefault === true                    | Auto-inject (overrides derivation)      |
+ *
+ * The helpers are split from `memory.service.ts` so the live (singleton)
+ * service and the agent-memory service can share one implementation.
+ *
+ * @module services/memory/role-knowledge-eligibility
+ */
+import type { RoleKnowledgeEntry } from '../../types/memory.types.js';
+/**
+ * Default importance value for legacy entries that pre-date M3.
+ * Per spec §191: "existing entries get default importance=0.5".
+ */
+export declare const DEFAULT_IMPORTANCE = 0.5;
+/**
+ * Default confidence value for legacy entries that omit the field.
+ * Per spec §191: default confidence=0.7.
+ */
+export declare const DEFAULT_CONFIDENCE = 0.7;
+/**
+ * Lower bound for "auto-inject eligible" entries.
+ */
+export declare const AUTO_INJECT_IMPORTANCE_MIN = 0.85;
+/**
+ * Confidence floor for auto-inject (cannot auto-inject below this).
+ */
+export declare const AUTO_INJECT_CONFIDENCE_MIN = 0.7;
+/**
+ * Hard cut-off — entries below this confidence are NEVER auto-injected,
+ * regardless of importance or `shouldInjectByDefault` overrides.
+ *
+ * Per spec §185: "confidence < 0.5 → NEVER auto-inject (only show on
+ * explicit recall)".
+ */
+export declare const NEVER_AUTO_INJECT_CONFIDENCE = 0.5;
+/**
+ * Check whether an entry has expired against the supplied "now".
+ *
+ * @param entry - Knowledge entry under evaluation
+ * @param now - Reference instant (ISO string or Date). Defaults to Date.now().
+ * @returns true when the entry's TTL has passed
+ */
+export declare function isExpired(entry: Pick<RoleKnowledgeEntry, 'ttl'>, now?: Date): boolean;
+/**
+ * Lazy-migrate a possibly-legacy entry to v3 shape **for read**.
+ *
+ * The migration is non-destructive — it returns a copy with M3 defaults
+ * filled in:
+ *
+ * - `importance` → `DEFAULT_IMPORTANCE` when missing
+ * - `confidence` → `DEFAULT_CONFIDENCE` when missing
+ * - `evidence`   → `[learnedFrom]` when learnedFrom present, else `[]`
+ * - `shouldInjectByDefault` left **undefined** so the eligibility
+ *   predicate can fall back to the derived rule
+ *
+ * Callers that **persist** entries should write the v3 fields explicitly;
+ * this helper deliberately does not write back.
+ *
+ * @param entry - Legacy or v3 entry to normalize for read
+ * @returns Entry with v3 fields guaranteed (importance + confidence
+ *          + evidence)
+ *
+ * @example
+ * ```typescript
+ * const view = lazyMigrateEntry(rawEntry);
+ * if (isAutoInjectEligible(view)) prompt += view.content;
+ * ```
+ */
+export declare function lazyMigrateEntry(entry: RoleKnowledgeEntry): RoleKnowledgeEntry;
+/**
+ * Check whether an entry is eligible to be auto-injected into agent
+ * context by default.
+ *
+ * **Rule order (per spec §183-187):**
+ * 1. Hidden if `superseded === true` or `supersededBy != null` — audit-only.
+ * 2. Hidden if expired (`ttl < now`).
+ * 3. Honored if `shouldInjectByDefault` is explicitly set:
+ *    - `false` → NEVER auto-inject regardless of scores.
+ *    - `true`  → auto-inject UNLESS confidence < 0.5 (the hard floor
+ *               from §185).
+ * 4. Otherwise derived: `importance >= 0.85 AND confidence >= 0.7`.
+ *
+ * @remarks
+ * **Phase-2 priority filter — DO NOT wire into the prompt path until M5.**
+ *
+ * This helper is forward-declared and intentionally NOT called from any
+ * production prompt-build path in M3. M5 wires it into
+ * `generateRoleKnowledgeContext` and `generateSchedulingContext` AFTER
+ * the legacy-entry backfill lands.
+ *
+ * Wiring it into M3's prompt path would be a P0 regression: pre-migration
+ * entries default to `importance=0.5` and `shouldInjectByDefault=false`
+ * (per spec §191), so the derived gate `importance >= 0.85` would cull
+ * every pre-migration knowledge entry on day one. The backfill in M5 lifts
+ * `importance`/`shouldInjectByDefault` for the entries that actually
+ * deserve auto-injection, then this helper becomes safe to wire.
+ *
+ * See `.crewly/specs/2026-05-03-memory-codebase-improvement-plan.md` M5
+ * for the wiring instruction.
+ *
+ * @param entry - Knowledge entry under evaluation (does not need to be pre-migrated)
+ * @param now - Reference instant for TTL evaluation. Defaults to Date.now().
+ * @returns true when this entry should appear in default-recall results
+ *
+ * @example
+ * ```typescript
+ * const visible = entries.filter((e) => isAutoInjectEligible(e));
+ * ```
+ */
+export declare function isAutoInjectEligible(entry: RoleKnowledgeEntry, now?: Date): boolean;
+/**
+ * Should this entry be **completely hidden** from default-recall?
+ *
+ * This is a strict superset of "not eligible for auto-inject" — entries
+ * that are merely below the auto-inject score gate are still surfaced on
+ * default recall (just not auto-injected into prompts), but entries that
+ * are superseded or expired are not surfaced at all unless the caller
+ * explicitly opts in.
+ *
+ * @param entry - Knowledge entry under evaluation
+ * @param now - Reference instant for TTL evaluation. Defaults to Date.now().
+ * @returns true when default recall should drop this entry
+ */
+export declare function isHiddenFromDefaultRecall(entry: RoleKnowledgeEntry, now?: Date): boolean;
+//# sourceMappingURL=role-knowledge-eligibility.d.ts.map

package/dist/backend/backend/src/services/memory/role-knowledge-eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-knowledge-eligibility.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/role-knowledge-eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACtC,GAAG,GAAE,IAAiB,GACrB,OAAO,CAOT;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,kBAAkB,CAa9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAsBT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,kBAAkB,EACzB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAIT"}