crewly 1.5.18 → 1.5.19

package/dist/backend/backend/src/services/v3/okr-review.service.js

@@ -0,0 +1,221 @@
+/**
+ * OKR Review Service
+ *
+ * Implements the feedback loop for Mission OKR execution:
+ * 1. Aggregate KR + task progress
+ * 2. Derive recommendation (pure math)
+ * 3. Trigger next action (continue / review skill / replan / escalate)
+ *
+ * Does NOT contain LLM logic — triggers the review-mission skill
+ * when agent reasoning is needed.
+ *
+ * @module services/v3/okr-review.service
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { LoggerService } from '../core/logger.service.js';
+import { KRTrackingService } from './kr-tracking.service.js';
+import { MissionExecutorService } from './mission-executor.service.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+function getMissionsDir() {
+    return path.join(process.cwd(), '.crewly', 'missions');
+}
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Service for executing periodic OKR reviews and processing review decisions.
+ */
+export class OKRReviewService {
+    static instance = null;
+    logger;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('OKRReview');
+    }
+    static getInstance() {
+        if (!OKRReviewService.instance) {
+            OKRReviewService.instance = new OKRReviewService();
+        }
+        return OKRReviewService.instance;
+    }
+    static resetInstance() {
+        OKRReviewService.instance = null;
+    }
+    // -------------------------------------------------------------------------
+    // Review Execution
+    // -------------------------------------------------------------------------
+    /**
+     * Execute a scheduled OKR review for a mission.
+     *
+     * 1. Load mission
+     * 2. Aggregate KR progress
+     * 3. Aggregate task progress
+     * 4. Derive recommendation
+     * 5. Determine action based on recommendation + policy
+     * 6. Persist review summary on mission
+     *
+     * @param missionId - Mission to review
+     * @returns Review result with recommendation and action
+     */
+    async executeReview(missionId) {
+        const mission = await this.loadMission(missionId);
+        if (!mission) {
+            throw new Error(`Mission ${missionId} not found`);
+        }
+        const staleCycles = mission.staleCycles ?? 0;
+        const krService = KRTrackingService.getInstance();
+        const okrSummary = await krService.computeMissionOKRProgress(missionId, staleCycles);
+        const executor = MissionExecutorService.getInstance();
+        const taskProgress = await executor.checkProgress(missionId);
+        // Determine if KRs progressed since last review
+        const previousProgress = this.extractPreviousProgress(mission.lastReviewSummary);
+        const progressStalled = previousProgress !== null && okrSummary.overallProgress <= previousProgress;
+        // Update stale cycles
+        const newStaleCycles = progressStalled ? staleCycles + 1 : 0;
+        // Re-derive recommendation with updated stale cycles
+        const finalSummary = progressStalled
+            ? await krService.computeMissionOKRProgress(missionId, newStaleCycles)
+            : okrSummary;
+        // Determine action
+        let action;
+        switch (finalSummary.recommendation) {
+            case 'continue':
+                action = 'continue';
+                break;
+            case 'adjust_strategy':
+                action = 'trigger_review_skill';
+                break;
+            case 'replan':
+                action = 'trigger_replan';
+                break;
+            case 'escalate':
+                action = 'escalate';
+                break;
+            default:
+                action = 'continue';
+        }
+        const result = {
+            missionId,
+            reviewedAt: new Date().toISOString(),
+            okrSummary: finalSummary,
+            recommendation: finalSummary.recommendation,
+            action,
+        };
+        // Persist review summary on mission
+        await this.updateMissionReview(missionId, {
+            lastReviewSummary: `Progress: ${finalSummary.overallProgress}% | ${finalSummary.achieved}/${finalSummary.totalKRs} achieved | Recommendation: ${finalSummary.recommendation}`,
+            staleCycles: newStaleCycles,
+            lastReviewAt: result.reviewedAt,
+        });
+        this.logger.info('OKR review completed', {
+            missionId,
+            progress: finalSummary.overallProgress,
+            recommendation: finalSummary.recommendation,
+            action,
+            staleCycles: newStaleCycles,
+        });
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Review Decision Processing
+    // -------------------------------------------------------------------------
+    /**
+     * Process a review decision from the review-mission skill.
+     *
+     * @param missionId - Mission ID
+     * @param decision - The agent's review decision
+     */
+    async processReviewDecision(missionId, decision) {
+        const mission = await this.loadMission(missionId);
+        if (!mission)
+            throw new Error(`Mission ${missionId} not found`);
+        const executor = MissionExecutorService.getInstance();
+        switch (decision.action) {
+            case 'continue':
+                // No action needed
+                break;
+            case 'adjust_strategy':
+                if (decision.newStrategy) {
+                    await this.updateMissionReview(missionId, {
+                        currentStrategy: decision.newStrategy,
+                    });
+                }
+                break;
+            case 'replan_phase':
+                // Cancel remaining tasks, bump phase for new decomposition
+                await executor.cancelRemainingPhaseTasks(missionId);
+                if (decision.newPhase) {
+                    // Phase will be set when new decomposition arrives
+                    this.logger.info('Replan triggered', { missionId, newPhase: decision.newPhase });
+                }
+                break;
+            case 'add_tasks':
+                // Additional tasks will be submitted via the decompose endpoint
+                this.logger.info('Additional tasks requested', { missionId });
+                break;
+            case 'cancel_mission':
+                await this.updateMissionReview(missionId, { status: 'cancelled' });
+                await executor.pauseMission(missionId);
+                this.logger.info('Mission cancelled via review', { missionId });
+                break;
+        }
+        // Record learnings
+        if (decision.learnings && decision.learnings.length > 0) {
+            const updatedMission = await this.loadMission(missionId);
+            if (updatedMission) {
+                const learnings = updatedMission.learnings ?? [];
+                learnings.push(...decision.learnings);
+                await this.updateMissionReview(missionId, { learnings });
+            }
+        }
+        // Update KR targets if requested
+        if (decision.krUpdates) {
+            const krService = KRTrackingService.getInstance();
+            for (const update of decision.krUpdates) {
+                await krService.update(missionId, update.krId, {
+                    target: update.newTarget,
+                });
+            }
+        }
+        this.logger.info('Review decision processed', { missionId, action: decision.action });
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Load a mission from disk.
+     */
+    async loadMission(missionId) {
+        try {
+            const filePath = path.join(getMissionsDir(), `${missionId}.json`);
+            const raw = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Update mission fields on disk (partial merge).
+     */
+    async updateMissionReview(missionId, updates) {
+        const mission = await this.loadMission(missionId);
+        if (!mission)
+            return;
+        const merged = { ...mission, ...updates, updatedAt: new Date().toISOString() };
+        const filePath = path.join(getMissionsDir(), `${missionId}.json`);
+        await fs.writeFile(filePath, JSON.stringify(merged, null, 2));
+    }
+    /**
+     * Extract previous overall progress from review summary string.
+     */
+    extractPreviousProgress(summary) {
+        if (!summary)
+            return null;
+        const match = summary.match(/Progress:\s*(\d+)%/);
+        return match ? parseInt(match[1], 10) : null;
+    }
+}
+//# sourceMappingURL=okr-review.service.js.map

package/dist/backend/backend/src/services/v3/okr-review.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"okr-review.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/v3/okr-review.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AASvE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,SAAS,cAAc;IACrB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACzD,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAC,QAAQ,GAA4B,IAAI,CAAC;IACvC,MAAM,CAAkB;IAEzC;QACE,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC;YAC/B,gBAAgB,CAAC,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACrD,CAAC;QACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,aAAa;QAClB,gBAAgB,CAAC,QAAQ,GAAG,IAAI,CAAC;IACnC,CAAC;IAED,4EAA4E;IAC5E,mBAAmB;IACnB,4EAA4E;IAE5E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,aAAa,CAAC,SAAiB;QACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,YAAY,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,EAAE,CAAC;QAClD,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,yBAAyB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACrF,MAAM,QAAQ,GAAG,sBAAsB,CAAC,WAAW,EAAE,CAAC;QACtD,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAE7D,gDAAgD;QAChD,MAAM,gBAAgB,GAAG,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACjF,MAAM,eAAe,GAAG,gBAAgB,KAAK,IAAI,IAAI,UAAU,CAAC,eAAe,IAAI,gBAAgB,CAAC;QAEpG,sBAAsB;QACtB,MAAM,cAAc,GAAG,eAAe,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7D,qDAAqD;QACrD,MAAM,YAAY,GAAG,eAAe;YAClC,CAAC,CAAC,MAAM,SAAS,CAAC,yBAAyB,CAAC,SAAS,EAAE,cAAc,CAAC;YACtE,CAAC,CAAC,UAAU,CAAC;QAEf,mBAAmB;QACnB,IAAI,MAAiC,CAAC;QACtC,QAAQ,YAAY,CAAC,cAAc,EAAE,CAAC;YACpC,KAAK,UAAU;gBACb,MAAM,GAAG,UAAU,CAAC;gBACpB,MAAM;YACR,KAAK,iBAAiB;gBACpB,MAAM,GAAG,sBAAsB,CAAC;gBAChC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,GAAG,gBAAgB,CAAC;gBAC1B,MAAM;YACR,KAAK,UAAU;gBACb,MAAM,GAAG,UAAU,CAAC;gBACpB,MAAM;YACR;gBACE,MAAM,GAAG,UAAU,CAAC;QACxB,CAAC;QAED,MAAM,MAAM,GAAoB;YAC9B,SAAS;YACT,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,UAAU,EAAE,YAAY;YACxB,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,MAAM;SACP,CAAC;QAEF,oCAAoC;QACpC,MAAM,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE;YACxC,iBAAiB,EAAE,aAAa,YAAY,CAAC,eAAe,OAAO,YAAY,CAAC,QAAQ,IAAI,YAAY,CAAC,QAAQ,+BAA+B,YAAY,CAAC,cAAc,EAAE;YAC7K,WAAW,EAAE,cAAc;YAC3B,YAAY,EAAE,MAAM,CAAC,UAAU;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE;YACvC,SAAS;YACT,QAAQ,EAAE,YAAY,CAAC,eAAe;YACtC,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,MAAM;YACN,WAAW,EAAE,cAAc;SAC5B,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,4EAA4E;IAC5E,6BAA6B;IAC7B,4EAA4E;IAE5E;;;;;OAKG;IACH,KAAK,CAAC,qBAAqB,CAAC,SAAiB,EAAE,QAAwB;QACrE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,YAAY,CAAC,CAAC;QAEhE,MAAM,QAAQ,GAAG,sBAAsB,CAAC,WAAW,EAAE,CAAC;QAEtD,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxB,KAAK,UAAU;gBACb,mBAAmB;gBACnB,MAAM;YAER,KAAK,iBAAiB;gBACpB,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;oBACzB,MAAM,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE;wBACxC,eAAe,EAAE,QAAQ,CAAC,WAAW;qBACtC,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YAER,KAAK,cAAc;gBACjB,2DAA2D;gBAC3D,MAAM,QAAQ,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC;gBACpD,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;oBACtB,mDAAmD;oBACnD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACnF,CAAC;gBACD,MAAM;YAER,KAAK,WAAW;gBACd,gEAAgE;gBAChE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC9D,MAAM;YAER,KAAK,gBAAgB;gBACnB,MAAM,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;gBACnE,MAAM,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;gBACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;gBAChE,MAAM;QACV,CAAC;QAED,mBAAmB;QACnB,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;YACzD,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,SAAS,GAAG,cAAc,CAAC,SAAS,IAAI,EAAE,CAAC;gBACjD,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACtC,MAAM,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,EAAE,CAAC;YAClD,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACxC,MAAM,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE;oBAC7C,MAAM,EAAE,MAAM,CAAC,SAAS;iBACzB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,4EAA4E;IAC5E,UAAU;IACV,4EAA4E;IAE5E;;OAEG;IACK,KAAK,CAAC,WAAW,CAAC,SAAiB;QACzC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;YAClE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,mBAAmB,CAC/B,SAAiB,EACjB,OAAyB;QAEzB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;QAClE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,OAAgB;QAC9C,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAClD,OAAO,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC"}

package/dist/backend/backend/src/services/v3/project-task-watcher.service.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ProjectTaskWatcherService — Watches `.crewly/tasks/` for new ProjectTask files
+ * and automatically creates WorkItems in the TaskPool.
+ *
+ * This service ensures that every ProjectTask file with status 'open' or 'in_progress'
+ * results in a corresponding WorkItem. It handles two scenarios:
+ *
+ * 1. **Initial sync**: Scans existing task files on startup and creates missing WorkItems
+ * 2. **Live watch**: Monitors the tasks directory for new `.md` files via chokidar
+ *
+ * Design principle: Fire-and-forget. Errors are logged but never block normal operations.
+ *
+ * @module services/v3/project-task-watcher.service
+ */
+/**
+ * Metadata parsed from a ProjectTask markdown file.
+ */
+export interface ParsedProjectTask {
+    /** Derived from filename (sans extension) */
+    taskId: string;
+    /** First H1 heading or filename */
+    title: string;
+    /** Full markdown content */
+    description: string;
+    /** Priority parsed from metadata block, defaults to 'medium' */
+    priority: string;
+    /** Milestone (parent directory name) */
+    milestone: string;
+    /** Status folder name: 'open' | 'in_progress' */
+    statusFolder: string;
+    /** Assigned session name, if present */
+    assignedTo?: string;
+}
+/**
+ * Watches the `.crewly/tasks/` directory for ProjectTask files and ensures
+ * each one has a corresponding WorkItem in the TaskPool.
+ *
+ * @example
+ * ```typescript
+ * const watcher = new ProjectTaskWatcherService('/path/to/project');
+ * await watcher.start();
+ * // ...later:
+ * watcher.dispose();
+ * ```
+ */
+export declare class ProjectTaskWatcherService {
+    private readonly logger;
+    private readonly projectPath;
+    private readonly tasksBaseDir;
+    private watcher;
+    private pendingFiles;
+    private debounceTimer;
+    /**
+     * Creates a new ProjectTaskWatcherService.
+     *
+     * @param projectPath - Absolute path to the project root
+     */
+    constructor(projectPath: string);
+    /**
+     * Starts watching for new ProjectTask files and performs an initial sync.
+     *
+     * 1. Ensures the tasks directory exists
+     * 2. Scans all existing open/in_progress tasks and creates missing WorkItems
+     * 3. Starts a chokidar watcher for live file creation events
+     */
+    start(): Promise<void>;
+    /**
+     * Scans all milestone directories for open/in_progress task files
+     * and creates WorkItems for any that don't already exist in the TaskPool.
+     */
+    syncExistingTasks(): Promise<void>;
+    /**
+     * Starts the chokidar file watcher on the tasks directory.
+     * Watches for new `.md` files in any `open/` or `in_progress/` subdirectory.
+     */
+    private startWatcher;
+    /**
+     * Handles a newly detected task file. Debounces rapid creation events.
+     *
+     * @param filePath - Absolute path to the new task file
+     */
+    private onFileAdded;
+    /**
+     * Schedules a debounced batch sync of pending files.
+     */
+    private scheduleDebouncedSync;
+    /**
+     * Ensures a WorkItem exists in the TaskPool for the given ProjectTask file.
+     * If one already exists (matched by projectTaskId), this is a no-op.
+     *
+     * @param filePath - Absolute path to the task .md file
+     * @param milestone - The milestone directory name
+     * @param statusFolder - The status folder name ('open' or 'in_progress')
+     * @returns True if a new WorkItem was created, false if already existed
+     */
+    ensureWorkItemForTask(filePath: string, milestone: string, statusFolder: string, options?: {
+        skipStalenessCheck?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Stops the file watcher and cleans up resources.
+     */
+    dispose(): void;
+}
+/**
+ * Parses a ProjectTask markdown file to extract metadata.
+ *
+ * Extracts:
+ * - Title from first H1 heading or filename
+ * - Priority from `**Priority**: ...` line
+ * - AssignedTo from `**Assigned to**: ...` line
+ *
+ * @param filePath - Absolute path to the .md file
+ * @param milestone - Milestone directory name
+ * @param statusFolder - Status folder name
+ * @returns Parsed task metadata, or null if the file is unreadable
+ */
+export declare function parseProjectTaskFile(filePath: string, milestone: string, statusFolder: string): Promise<ParsedProjectTask | null>;
+//# sourceMappingURL=project-task-watcher.service.d.ts.map

package/dist/backend/backend/src/services/v3/project-task-watcher.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-task-watcher.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/v3/project-task-watcher.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgCH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,aAAa,CAA8C;IAEnE;;;;OAIG;gBACS,WAAW,EAAE,MAAM;IAM/B;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyCxC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAyBpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;;;;;;;OAQG;IACG,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,OAAO,CAAC,OAAO,CAAC;IA0DnB;;OAEG;IACH,OAAO,IAAI,IAAI;CAYhB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA6BnC"}

package/dist/backend/backend/src/services/v3/project-task-watcher.service.js

@@ -0,0 +1,326 @@
+/**
+ * ProjectTaskWatcherService — Watches `.crewly/tasks/` for new ProjectTask files
+ * and automatically creates WorkItems in the TaskPool.
+ *
+ * This service ensures that every ProjectTask file with status 'open' or 'in_progress'
+ * results in a corresponding WorkItem. It handles two scenarios:
+ *
+ * 1. **Initial sync**: Scans existing task files on startup and creates missing WorkItems
+ * 2. **Live watch**: Monitors the tasks directory for new `.md` files via chokidar
+ *
+ * Design principle: Fire-and-forget. Errors are logged but never block normal operations.
+ *
+ * @module services/v3/project-task-watcher.service
+ */
+import * as chokidar from 'chokidar';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { LoggerService } from '../core/logger.service.js';
+import { TaskPoolService } from '../task-pool/task-pool.service.js';
+import { createWorkItem } from '../../types/v2/work-item.types.js';
+import { ensureDir } from '../../utils/file-io.utils.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Debounce interval in ms to batch rapid file creation events. */
+const WATCHER_DEBOUNCE_MS = 500;
+/** Subdirectories within a milestone folder that indicate actionable tasks. */
+const ACTIONABLE_STATUS_FOLDERS = ['open', 'in_progress'];
+/**
+ * Maximum age (ms) for a task file to be considered during initial startup sync.
+ * Tasks older than this are assumed stale and skipped during initial scan.
+ * Live watcher still processes new files regardless of age.
+ * Default: 48 hours.
+ */
+const STARTUP_SYNC_MAX_AGE_MS = 48 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Watches the `.crewly/tasks/` directory for ProjectTask files and ensures
+ * each one has a corresponding WorkItem in the TaskPool.
+ *
+ * @example
+ * ```typescript
+ * const watcher = new ProjectTaskWatcherService('/path/to/project');
+ * await watcher.start();
+ * // ...later:
+ * watcher.dispose();
+ * ```
+ */
+export class ProjectTaskWatcherService {
+    logger;
+    projectPath;
+    tasksBaseDir;
+    watcher = null;
+    pendingFiles = new Set();
+    debounceTimer = null;
+    /**
+     * Creates a new ProjectTaskWatcherService.
+     *
+     * @param projectPath - Absolute path to the project root
+     */
+    constructor(projectPath) {
+        this.logger = LoggerService.getInstance().createComponentLogger('ProjectTaskWatcher');
+        this.projectPath = projectPath;
+        this.tasksBaseDir = path.join(projectPath, '.crewly', 'tasks');
+    }
+    /**
+     * Starts watching for new ProjectTask files and performs an initial sync.
+     *
+     * 1. Ensures the tasks directory exists
+     * 2. Scans all existing open/in_progress tasks and creates missing WorkItems
+     * 3. Starts a chokidar watcher for live file creation events
+     */
+    async start() {
+        try {
+            await ensureDir(this.tasksBaseDir);
+        }
+        catch {
+            this.logger.warn('Tasks directory does not exist and cannot be created', {
+                tasksBaseDir: this.tasksBaseDir,
+            });
+            return;
+        }
+        // Step 1: Initial sync — scan existing task files
+        await this.syncExistingTasks();
+        // Step 2: Start live watcher
+        this.startWatcher();
+        this.logger.info('ProjectTaskWatcherService started', {
+            tasksBaseDir: this.tasksBaseDir,
+        });
+    }
+    /**
+     * Scans all milestone directories for open/in_progress task files
+     * and creates WorkItems for any that don't already exist in the TaskPool.
+     */
+    async syncExistingTasks() {
+        try {
+            const entries = await fs.readdir(this.tasksBaseDir, { withFileTypes: true });
+            const milestones = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+            let synced = 0;
+            for (const milestone of milestones) {
+                for (const statusFolder of ACTIONABLE_STATUS_FOLDERS) {
+                    const dir = path.join(this.tasksBaseDir, milestone, statusFolder);
+                    let files;
+                    try {
+                        files = await fs.readdir(dir);
+                    }
+                    catch {
+                        // Directory doesn't exist — skip
+                        continue;
+                    }
+                    for (const file of files) {
+                        if (!file.endsWith('.md'))
+                            continue;
+                        const filePath = path.join(dir, file);
+                        const created = await this.ensureWorkItemForTask(filePath, milestone, statusFolder);
+                        if (created)
+                            synced++;
+                    }
+                }
+            }
+            if (synced > 0) {
+                this.logger.info('Initial sync created WorkItems for existing tasks', {
+                    count: synced,
+                });
+            }
+        }
+        catch (err) {
+            this.logger.warn('Initial task sync failed (non-fatal)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Starts the chokidar file watcher on the tasks directory.
+     * Watches for new `.md` files in any `open/` or `in_progress/` subdirectory.
+     */
+    startWatcher() {
+        // Watch pattern: .crewly/tasks/*/{open,in_progress}/*.md
+        const watchPattern = path.join(this.tasksBaseDir, '**', '*.md');
+        this.watcher = chokidar.watch(watchPattern, {
+            ignoreInitial: true,
+            persistent: true,
+            depth: 3,
+            awaitWriteFinish: {
+                stabilityThreshold: 300,
+                pollInterval: 100,
+            },
+        });
+        this.watcher.on('add', (filePath) => {
+            this.onFileAdded(filePath);
+        });
+        this.watcher.on('error', (err) => {
+            this.logger.warn('File watcher error (non-fatal)', {
+                error: err.message,
+            });
+        });
+    }
+    /**
+     * Handles a newly detected task file. Debounces rapid creation events.
+     *
+     * @param filePath - Absolute path to the new task file
+     */
+    onFileAdded(filePath) {
+        // Only process files in actionable status folders
+        const relative = path.relative(this.tasksBaseDir, filePath);
+        const parts = relative.split(path.sep);
+        // Expected structure: {milestone}/{statusFolder}/{filename}.md
+        if (parts.length < 3)
+            return;
+        const statusFolder = parts[parts.length - 2];
+        if (!ACTIONABLE_STATUS_FOLDERS.includes(statusFolder))
+            return;
+        this.pendingFiles.add(filePath);
+        this.scheduleDebouncedSync();
+    }
+    /**
+     * Schedules a debounced batch sync of pending files.
+     */
+    scheduleDebouncedSync() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(async () => {
+            const files = Array.from(this.pendingFiles);
+            this.pendingFiles.clear();
+            for (const filePath of files) {
+                try {
+                    const relative = path.relative(this.tasksBaseDir, filePath);
+                    const parts = relative.split(path.sep);
+                    const milestone = parts[0];
+                    const statusFolder = parts[parts.length - 2];
+                    await this.ensureWorkItemForTask(filePath, milestone, statusFolder, { skipStalenessCheck: true });
+                }
+                catch (err) {
+                    this.logger.warn('Failed to process new task file (non-fatal)', {
+                        filePath,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }, WATCHER_DEBOUNCE_MS);
+    }
+    /**
+     * Ensures a WorkItem exists in the TaskPool for the given ProjectTask file.
+     * If one already exists (matched by projectTaskId), this is a no-op.
+     *
+     * @param filePath - Absolute path to the task .md file
+     * @param milestone - The milestone directory name
+     * @param statusFolder - The status folder name ('open' or 'in_progress')
+     * @returns True if a new WorkItem was created, false if already existed
+     */
+    async ensureWorkItemForTask(filePath, milestone, statusFolder, options) {
+        try {
+            const parsed = await parseProjectTaskFile(filePath, milestone, statusFolder);
+            if (!parsed)
+                return false;
+            // Staleness check: skip old files during initial sync to prevent
+            // re-creating WorkItems for long-abandoned tasks on every restart
+            if (!options?.skipStalenessCheck) {
+                try {
+                    const stat = await fs.stat(filePath);
+                    const ageMs = Date.now() - stat.mtimeMs;
+                    if (ageMs > STARTUP_SYNC_MAX_AGE_MS) {
+                        return false;
+                    }
+                }
+                catch {
+                    // If we can't stat the file, skip it
+                    return false;
+                }
+            }
+            const taskPool = TaskPoolService.getInstance();
+            const existing = await taskPool.getAllItems();
+            // Dedup: check if a WorkItem with this projectTaskId already exists
+            if (existing.some((wi) => wi.projectTaskId === parsed.taskId)) {
+                return false;
+            }
+            const workItem = createWorkItem({
+                type: 'project_task',
+                owner: parsed.assignedTo ? 'agent' : 'orchestrator',
+                target: parsed.assignedTo,
+                title: parsed.title,
+                description: parsed.description.substring(0, 500),
+                projectTaskId: parsed.taskId,
+                maxRetries: 2,
+            });
+            await taskPool.addToPool(workItem);
+            this.logger.info('WorkItem auto-created from ProjectTask file', {
+                workItemId: workItem.id,
+                taskId: parsed.taskId,
+                milestone: parsed.milestone,
+                status: parsed.statusFolder,
+                assignedTo: parsed.assignedTo,
+            });
+            return true;
+        }
+        catch (err) {
+            this.logger.warn('ensureWorkItemForTask failed (non-fatal)', {
+                filePath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+    }
+    /**
+     * Stops the file watcher and cleans up resources.
+     */
+    dispose() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        this.pendingFiles.clear();
+        this.logger.info('ProjectTaskWatcherService disposed');
+    }
+}
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parses a ProjectTask markdown file to extract metadata.
+ *
+ * Extracts:
+ * - Title from first H1 heading or filename
+ * - Priority from `**Priority**: ...` line
+ * - AssignedTo from `**Assigned to**: ...` line
+ *
+ * @param filePath - Absolute path to the .md file
+ * @param milestone - Milestone directory name
+ * @param statusFolder - Status folder name
+ * @returns Parsed task metadata, or null if the file is unreadable
+ */
+export async function parseProjectTaskFile(filePath, milestone, statusFolder) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const fileName = path.basename(filePath, '.md');
+        // Extract title from first H1 heading
+        const titleMatch = content.match(/^#\s+(.+)$/m);
+        const title = titleMatch ? titleMatch[1].trim() : fileName;
+        // Extract priority
+        const priorityMatch = content.match(/\*\*Priority\*\*:\s*(\S+)/i);
+        const priority = priorityMatch ? priorityMatch[1].toLowerCase() : 'medium';
+        // Extract assigned session name
+        const assignedMatch = content.match(/\*\*Assigned to\*\*:\s*(\S+)/i);
+        const assignedTo = assignedMatch ? assignedMatch[1] : undefined;
+        return {
+            taskId: fileName,
+            title,
+            description: content,
+            priority,
+            milestone,
+            statusFolder,
+            assignedTo,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=project-task-watcher.service.js.map