@mcp-graph-workflow/mcp-graph 3.0.0

package/dist/core/planner/lifecycle-phase.d.ts

@@ -0,0 +1,21 @@
+import type { GraphDocument } from "../graph/graph-types.js";
+export type LifecyclePhase = "ANALYZE" | "DESIGN" | "PLAN" | "IMPLEMENT" | "VALIDATE" | "REVIEW" | "HANDOFF" | "LISTENING";
+export interface PhaseGuidance {
+    reminder: string;
+    suggestedTools: string[];
+    principles: string[];
+}
+/**
+ * Detect the current lifecycle phase from the graph state.
+ *
+ * Heuristics:
+ * - No nodes → ANALYZE
+ * - Only requirement/epic/decision nodes → DESIGN
+ * - Tasks exist but no sprint assigned → PLAN
+ * - Any task in_progress → IMPLEMENT
+ * - Most tasks done, some remaining → VALIDATE
+ * - All actionable nodes done → REVIEW
+ */
+export declare function detectCurrentPhase(doc: GraphDocument): LifecyclePhase;
+export declare function getPhaseGuidance(phase: LifecyclePhase): PhaseGuidance;
+//# sourceMappingURL=lifecycle-phase.d.ts.map

package/dist/core/planner/lifecycle-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-phase.d.ts","sourceRoot":"","sources":["../../../src/core/planner/lifecycle-phase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,QAAQ,GACR,MAAM,GACN,WAAW,GACX,UAAU,GACV,QAAQ,GACR,SAAS,GACT,WAAW,CAAC;AAEhB,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CA4CrE;AA6CD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAErE"}

package/dist/core/planner/lifecycle-phase.js

@@ -0,0 +1,93 @@
+const DESIGN_ONLY_TYPES = new Set(["requirement", "epic", "decision", "constraint", "milestone", "risk"]);
+const TASK_TYPES = new Set(["task", "subtask"]);
+/**
+ * Detect the current lifecycle phase from the graph state.
+ *
+ * Heuristics:
+ * - No nodes → ANALYZE
+ * - Only requirement/epic/decision nodes → DESIGN
+ * - Tasks exist but no sprint assigned → PLAN
+ * - Any task in_progress → IMPLEMENT
+ * - Most tasks done, some remaining → VALIDATE
+ * - All actionable nodes done → REVIEW
+ */
+export function detectCurrentPhase(doc) {
+    const { nodes } = doc;
+    if (nodes.length === 0) {
+        return "ANALYZE";
+    }
+    const tasks = nodes.filter((n) => TASK_TYPES.has(n.type));
+    const hasOnlyDesignNodes = nodes.every((n) => DESIGN_ONLY_TYPES.has(n.type));
+    if (hasOnlyDesignNodes || tasks.length === 0) {
+        return "DESIGN";
+    }
+    const inProgress = tasks.filter((n) => n.status === "in_progress");
+    if (inProgress.length > 0) {
+        return "IMPLEMENT";
+    }
+    const doneTasks = tasks.filter((n) => n.status === "done");
+    const allDone = nodes.every((n) => n.status === "done" || !TASK_TYPES.has(n.type) && DESIGN_ONLY_TYPES.has(n.type));
+    if (doneTasks.length === tasks.length && tasks.length > 0) {
+        return "REVIEW";
+    }
+    const hasSprints = tasks.some((n) => n.sprint != null);
+    if (!hasSprints) {
+        return "PLAN";
+    }
+    // Most done but some remaining → VALIDATE
+    if (doneTasks.length > 0 && doneTasks.length >= tasks.length * 0.5) {
+        return "VALIDATE";
+    }
+    // Tasks with sprint but not started yet → still PLAN
+    const notStarted = tasks.every((n) => n.status === "backlog" || n.status === "ready");
+    if (notStarted) {
+        return "PLAN";
+    }
+    return "IMPLEMENT";
+}
+const GUIDANCE = {
+    ANALYZE: {
+        reminder: "Fase ANALYZE: Crie o PRD a partir da ideia. Defina requisitos, restrições e critérios de aceitação antes de qualquer código.",
+        suggestedTools: ["import_prd", "add_node", "search"],
+        principles: ["Definir antes de construir", "PRD como contrato", "Requisitos claros e mensuráveis"],
+    },
+    DESIGN: {
+        reminder: "Fase DESIGN: Defina a arquitetura e tome decisões técnicas. Use análise de impacto antes de definir a estrutura.",
+        suggestedTools: ["add_node", "edge", "decompose", "export"],
+        principles: ["Skeleton & Organs", "Decisões arquiteturais documentadas", "Anti-one-shot"],
+    },
+    PLAN: {
+        reminder: "Fase PLAN: Planeje o sprint, decomponha tasks grandes e sincronize documentação das libs.",
+        suggestedTools: ["plan_sprint", "decompose", "sync_stack_docs", "edge", "dependencies"],
+        principles: ["Decomposição atômica", "Sprint planning baseado em velocidade", "Dependências explícitas"],
+    },
+    IMPLEMENT: {
+        reminder: "Fase IMPLEMENT: TDD obrigatório — Red → Green → Refactor. Escreva o teste ANTES da implementação. Use `context` para token-efficiency.",
+        suggestedTools: ["next", "context", "update_status", "rag_context", "validate_task"],
+        principles: ["TDD Red→Green→Refactor", "Anti-one-shot", "Code detachment", "Decomposição atômica"],
+    },
+    VALIDATE: {
+        reminder: "Fase VALIDATE: Valide tasks completadas com testes E2E (Playwright). Verifique critérios de aceitação.",
+        suggestedTools: ["validate_task", "velocity", "stats", "list"],
+        principles: ["Validação automatizada", "Critérios de aceitação como contrato", "Zero tolerance para regressões"],
+    },
+    REVIEW: {
+        reminder: "Fase REVIEW: Revise o código, verifique blast radius e garanta que nada quebrou. Exporte o grafo para revisão.",
+        suggestedTools: ["export", "stats", "velocity", "dependencies"],
+        principles: ["Code review obrigatório", "Blast radius check", "Non-regression rule"],
+    },
+    HANDOFF: {
+        reminder: "Fase HANDOFF: Crie o PR, documente decisões e exporte o grafo. Prepare para entrega.",
+        suggestedTools: ["export", "snapshot", "stats", "velocity"],
+        principles: ["Documentação como entrega", "Grafo exportado", "Knowledge base atualizada"],
+    },
+    LISTENING: {
+        reminder: "Fase LISTENING: Colete feedback e adicione novos nodes ao grafo. Inicie novo ciclo se necessário.",
+        suggestedTools: ["add_node", "import_prd", "search", "list"],
+        principles: ["Feedback contínuo", "Iteração incremental", "CLAUDE.md como spec evolutiva"],
+    },
+};
+export function getPhaseGuidance(phase) {
+    return GUIDANCE[phase];
+}
+//# sourceMappingURL=lifecycle-phase.js.map

package/dist/core/planner/lifecycle-phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-phase.js","sourceRoot":"","sources":["../../../src/core/planner/lifecycle-phase.ts"],"names":[],"mappings":"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"}

package/dist/core/planner/next-task.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Execution planner: suggests the next best task to work on.
+ *
+ * Algorithm:
+ * 1. Filter nodes of type task/subtask with status backlog or ready
+ * 2. Eliminate nodes with unresolved depends_on edges (dependency target not done)
+ * 3. Eliminate nodes with blocked = true
+ * 4. Sort by: priority ASC, xpSize ASC, estimateMinutes ASC, createdAt ASC
+ */
+import type { GraphDocument, GraphNode } from "../graph/graph-types.js";
+export interface NextTaskResult {
+    node: GraphNode;
+    reason: string;
+}
+export declare function findNextTask(doc: GraphDocument): NextTaskResult | null;
+//# sourceMappingURL=next-task.d.ts.map

package/dist/core/planner/next-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-task.d.ts","sourceRoot":"","sources":["../../../src/core/planner/next-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAa,MAAM,yBAAyB,CAAC;AAOnF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,GAAG,IAAI,CAgGtE"}

package/dist/core/planner/next-task.js

@@ -0,0 +1,146 @@
+/**
+ * Execution planner: suggests the next best task to work on.
+ *
+ * Algorithm:
+ * 1. Filter nodes of type task/subtask with status backlog or ready
+ * 2. Eliminate nodes with unresolved depends_on edges (dependency target not done)
+ * 3. Eliminate nodes with blocked = true
+ * 4. Sort by: priority ASC, xpSize ASC, estimateMinutes ASC, createdAt ASC
+ */
+import { logger } from "../utils/logger.js";
+const XP_SIZE_ORDER = {
+    XS: 1, S: 2, M: 3, L: 4, XL: 5,
+};
+export function findNextTask(doc) {
+    // Step 1: Filter eligible nodes
+    const eligible = doc.nodes.filter((n) => (n.type === "task" || n.type === "subtask") &&
+        (n.status === "backlog" || n.status === "ready") &&
+        !n.blocked);
+    logger.debug("Next task candidates", {
+        eligible: eligible.length,
+        total: doc.nodes.length,
+    });
+    if (eligible.length === 0)
+        return null;
+    // Step 2: Build a set of done node IDs for dependency checking
+    const doneIds = new Set(doc.nodes.filter((n) => n.status === "done").map((n) => n.id));
+    // Step 3: Find depends_on edges and filter out nodes with unresolved deps
+    const unblocked = eligible.filter((node) => {
+        const depsEdges = doc.edges.filter((e) => e.from === node.id && e.relationType === "depends_on");
+        // All dependency targets must be done
+        return depsEdges.every((e) => doneIds.has(e.to));
+    });
+    if (unblocked.length === 0) {
+        // All eligible tasks have unresolved dependencies — return the one with fewest deps
+        const withDepCount = eligible.map((node) => {
+            const deps = doc.edges.filter((e) => e.from === node.id && e.relationType === "depends_on" && !doneIds.has(e.to));
+            return { node, pendingDeps: deps.length };
+        });
+        withDepCount.sort((a, b) => a.pendingDeps - b.pendingDeps);
+        logger.debug("next:all-blocked", {
+            eligibleCount: eligible.length,
+            bestPendingDeps: withDepCount[0].pendingDeps,
+        });
+        return {
+            node: withDepCount[0].node,
+            reason: `Todas as tasks têm dependências pendentes. Esta tem menos (${withDepCount[0].pendingDeps}).`,
+        };
+    }
+    // Step 4: Topological rank from priority_over edges (Kahn's algorithm)
+    const priorityRank = computePriorityRank(unblocked, doc.edges);
+    // Step 5: Sort
+    unblocked.sort((a, b) => {
+        // Priority_over topological rank ASC (lower rank = higher priority)
+        const rankA = priorityRank.get(a.id) ?? Infinity;
+        const rankB = priorityRank.get(b.id) ?? Infinity;
+        if (rankA !== rankB)
+            return rankA - rankB;
+        // Priority ASC (1 = critical, 5 = optional)
+        if (a.priority !== b.priority)
+            return a.priority - b.priority;
+        // XP size ASC
+        const sizeA = XP_SIZE_ORDER[a.xpSize || "M"] ?? 3;
+        const sizeB = XP_SIZE_ORDER[b.xpSize || "M"] ?? 3;
+        if (sizeA !== sizeB)
+            return sizeA - sizeB;
+        // Estimate ASC
+        const estA = a.estimateMinutes ?? 999;
+        const estB = b.estimateMinutes ?? 999;
+        if (estA !== estB)
+            return estA - estB;
+        // Prefer tasks with more acceptance criteria (clearer definition)
+        const acA = a.acceptanceCriteria?.length ?? 0;
+        const acB = b.acceptanceCriteria?.length ?? 0;
+        if (acA !== acB)
+            return acB - acA;
+        // CreatedAt ASC (older first)
+        return a.createdAt.localeCompare(b.createdAt);
+    });
+    const best = unblocked[0];
+    const reasons = ["desbloqueada"];
+    if (best.priority <= 2)
+        reasons.push("alta prioridade");
+    if (best.xpSize && XP_SIZE_ORDER[best.xpSize] <= 2)
+        reasons.push("baixa complexidade");
+    logger.debug("next:selected", {
+        nodeId: best.id,
+        title: best.title,
+        priority: best.priority,
+        candidatesCount: unblocked.length,
+        reason: reasons.join(", "),
+    });
+    return {
+        node: best,
+        reason: reasons.join(", "),
+    };
+}
+/**
+ * Kahn's algorithm topological sort on priority_over edges.
+ * Returns a map of nodeId → rank (0 = highest priority).
+ * Nodes in cycles get no rank (treated as Infinity in sort).
+ */
+function computePriorityRank(candidates, edges) {
+    const candidateIds = new Set(candidates.map((n) => n.id));
+    const rank = new Map();
+    // Filter priority_over edges where both endpoints are in the candidate set
+    const relevantEdges = edges.filter((e) => e.relationType === "priority_over" &&
+        candidateIds.has(e.from) &&
+        candidateIds.has(e.to));
+    if (relevantEdges.length === 0)
+        return rank;
+    // Build adjacency list and in-degree count
+    const inDegree = new Map();
+    const adj = new Map();
+    for (const id of candidateIds) {
+        inDegree.set(id, 0);
+        adj.set(id, []);
+    }
+    for (const edge of relevantEdges) {
+        adj.get(edge.from).push(edge.to);
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    }
+    // Kahn's: start with nodes that have 0 in-degree
+    const queue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    let currentRank = 0;
+    while (queue.length > 0) {
+        const batch = [...queue];
+        queue.length = 0;
+        for (const id of batch) {
+            rank.set(id, currentRank);
+            for (const neighbor of adj.get(id) ?? []) {
+                const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+                inDegree.set(neighbor, newDeg);
+                if (newDeg === 0)
+                    queue.push(neighbor);
+            }
+        }
+        currentRank++;
+    }
+    // Nodes still not in rank are part of cycles — they get no rank (Infinity in sort)
+    return rank;
+}
+//# sourceMappingURL=next-task.js.map

package/dist/core/planner/next-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-task.js","sourceRoot":"","sources":["../../../src/core/planner/next-task.ts"],"names":[],"mappings":"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"}

package/dist/core/planner/planning-report.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Planning Report — generates a structured report for sprint planning.
+ * Includes recommended order, missing docs, and risk assessment.
+ */
+import type { GraphDocument } from "../graph/graph-types.js";
+import type { SqliteStore } from "../store/sqlite-store.js";
+export interface PlanningReport {
+    /** Recommended task execution order */
+    recommendedOrder: Array<{
+        id: string;
+        title: string;
+        type: string;
+        priority: number;
+        xpSize: string;
+        reason: string;
+    }>;
+    /** Libraries or topics with missing documentation */
+    missingDocs: string[];
+    /** Risk assessment */
+    risks: Array<{
+        nodeId: string;
+        title: string;
+        risk: string;
+        severity: "low" | "medium" | "high";
+    }>;
+    /** Summary metrics */
+    summary: {
+        totalReady: number;
+        totalBlocked: number;
+        estimatedPoints: number;
+        avgVelocity: number | null;
+    };
+}
+/**
+ * Generate a planning report for the current sprint.
+ */
+export declare function generatePlanningReport(doc: GraphDocument, store: SqliteStore): PlanningReport;
+//# sourceMappingURL=planning-report.d.ts.map

package/dist/core/planner/planning-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-report.d.ts","sourceRoot":"","sources":["../../../src/core/planner/planning-report.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,gBAAgB,EAAE,KAAK,CAAC;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sBAAsB;IACtB,KAAK,EAAE,KAAK,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;KACrC,CAAC,CAAC;IACH,sBAAsB;IACtB,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,WAAW,GACjB,cAAc,CAiDhB"}

package/dist/core/planner/planning-report.js

@@ -0,0 +1,140 @@
+/**
+ * Planning Report — generates a structured report for sprint planning.
+ * Includes recommended order, missing docs, and risk assessment.
+ */
+import { KnowledgeStore } from "../store/knowledge-store.js";
+import { findNextTask } from "./next-task.js";
+import { calculateVelocity } from "./velocity.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Generate a planning report for the current sprint.
+ */
+export function generatePlanningReport(doc, store) {
+    const eligibleNodes = doc.nodes.filter((n) => (n.type === "task" || n.type === "subtask") &&
+        (n.status === "backlog" || n.status === "ready") &&
+        !n.blocked);
+    const blockedNodes = doc.nodes.filter((n) => (n.type === "task" || n.type === "subtask") &&
+        (n.status === "blocked" || n.blocked));
+    // Build recommended order using next-task algorithm iteratively
+    const recommendedOrder = buildRecommendedOrder(doc);
+    // Assess missing docs
+    const missingDocs = assessMissingDocs(store, eligibleNodes);
+    // Assess risks
+    const risks = assessRisks(doc, eligibleNodes, blockedNodes);
+    // Velocity
+    const velocity = calculateVelocity(doc);
+    const XP_POINTS = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
+    const estimatedPoints = eligibleNodes.reduce((sum, n) => sum + (XP_POINTS[n.xpSize ?? "M"] ?? 3), 0);
+    logger.info("Planning report generated", {
+        ready: eligibleNodes.length,
+        blocked: blockedNodes.length,
+        points: estimatedPoints,
+    });
+    return {
+        recommendedOrder,
+        missingDocs,
+        risks,
+        summary: {
+            totalReady: eligibleNodes.length,
+            totalBlocked: blockedNodes.length,
+            estimatedPoints,
+            avgVelocity: velocity.overall.avgPointsPerSprint,
+        },
+    };
+}
+function buildRecommendedOrder(doc) {
+    // Clone the doc to simulate progressive execution
+    const remaining = new Set(doc.nodes
+        .filter((n) => (n.type === "task" || n.type === "subtask") &&
+        (n.status === "backlog" || n.status === "ready") &&
+        !n.blocked)
+        .map((n) => n.id));
+    const order = [];
+    const simulatedDone = new Set(doc.nodes.filter((n) => n.status === "done").map((n) => n.id));
+    // Iteratively pick next task (max 20 iterations)
+    for (let i = 0; i < 20 && remaining.size > 0; i++) {
+        const result = findNextTask({
+            ...doc,
+            nodes: doc.nodes.map((n) => {
+                if (simulatedDone.has(n.id))
+                    return { ...n, status: "done" };
+                return n;
+            }),
+        });
+        if (!result || !remaining.has(result.node.id))
+            break;
+        order.push({
+            id: result.node.id,
+            title: result.node.title,
+            type: result.node.type,
+            priority: result.node.priority,
+            xpSize: result.node.xpSize ?? "M",
+            reason: result.reason,
+        });
+        simulatedDone.add(result.node.id);
+        remaining.delete(result.node.id);
+    }
+    return order;
+}
+function assessMissingDocs(store, nodes) {
+    try {
+        const knowledgeStore = new KnowledgeStore(store.getDb());
+        if (knowledgeStore.count() === 0)
+            return ["No knowledge documents indexed"];
+        const missing = [];
+        const checked = new Set();
+        for (const node of nodes) {
+            const tags = node.tags ?? [];
+            for (const tag of tags) {
+                if (checked.has(tag))
+                    continue;
+                checked.add(tag);
+                const results = knowledgeStore.search(tag, 1);
+                if (results.length === 0) {
+                    missing.push(tag);
+                }
+            }
+        }
+        return missing;
+    }
+    catch {
+        return [];
+    }
+}
+function assessRisks(doc, eligible, blocked) {
+    const risks = [];
+    // Blocked tasks are a risk
+    for (const node of blocked) {
+        risks.push({
+            nodeId: node.id,
+            title: node.title,
+            risk: "Task is blocked",
+            severity: "high",
+        });
+    }
+    // Tasks with many dependencies
+    for (const node of eligible) {
+        const deps = doc.edges.filter((e) => e.from === node.id && e.relationType === "depends_on");
+        if (deps.length >= 3) {
+            risks.push({
+                nodeId: node.id,
+                title: node.title,
+                risk: `Has ${deps.length} dependencies`,
+                severity: "medium",
+            });
+        }
+    }
+    // XL tasks are risky
+    for (const node of eligible) {
+        if (node.xpSize === "XL") {
+            risks.push({
+                nodeId: node.id,
+                title: node.title,
+                risk: "Extra-large task — consider decomposing",
+                severity: "medium",
+            });
+        }
+    }
+    return risks;
+}
+//# sourceMappingURL=planning-report.js.map

package/dist/core/planner/planning-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-report.js","sourceRoot":"","sources":["../../../src/core/planner/planning-report.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AA8B5C;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAkB,EAClB,KAAkB;IAElB,MAAM,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;QAC3C,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC;QAChD,CAAC,CAAC,CAAC,OAAO,CACb,CAAC;IAEF,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CACnC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;QAC3C,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,CACxC,CAAC;IAEF,gEAAgE;IAChE,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAEpD,sBAAsB;IACtB,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAE5D,eAAe;IACf,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;IAE5D,WAAW;IACX,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAExC,MAAM,SAAS,GAA2B,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;IAC7E,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAC1C,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,EACnD,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE;QACvC,KAAK,EAAE,aAAa,CAAC,MAAM;QAC3B,OAAO,EAAE,YAAY,CAAC,MAAM;QAC5B,MAAM,EAAE,eAAe;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,gBAAgB;QAChB,WAAW;QACX,KAAK;QACL,OAAO,EAAE;YACP,UAAU,EAAE,aAAa,CAAC,MAAM;YAChC,YAAY,EAAE,YAAY,CAAC,MAAM;YACjC,eAAe;YACf,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,kBAAkB;SACjD;KACF,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAC5B,GAAkB;IAElB,kDAAkD;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,GAAG,CAAC,KAAK;SACN,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;QAC3C,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC;QAChD,CAAC,CAAC,CAAC,OAAO,CACb;SACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACpB,CAAC;IAEF,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC9D,CAAC;IAEF,iDAAiD;IACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,YAAY,CAAC;YAC1B,GAAG,GAAG;YACN,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACzB,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAe,EAAE,CAAC;gBACtE,OAAO,CAAC,CAAC;YACX,CAAC,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM;QAErD,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE;YAClB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI;YACtB,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ;YAC9B,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QAEH,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CACxB,KAAkB,EAClB,KAAkB;IAElB,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACzD,IAAI,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,gCAAgC,CAAC,CAAC;QAE5E,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAEjB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACpB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,GAAkB,EAClB,QAAqB,EACrB,OAAoB;IAEpB,MAAM,KAAK,GAA4B,EAAE,CAAC;IAE1C,2BAA2B;IAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,iBAAiB;YACvB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;IACL,CAAC;IAED,+BAA+B;IAC/B,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAC3B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,YAAY,KAAK,YAAY,CAC7D,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC;gBACT,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,IAAI,EAAE,OAAO,IAAI,CAAC,MAAM,eAAe;gBACvC,QAAQ,EAAE,QAAQ;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC;gBACT,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,IAAI,EAAE,yCAAyC;gBAC/C,QAAQ,EAAE,QAAQ;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/planner/velocity.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Velocity tracking: measures sprint completion metrics.
+ *
+ * Computes:
+ * - Tasks completed per sprint
+ * - Average XP size completed
+ * - Estimated completion time (based on created→done timestamps)
+ */
+import type { GraphDocument } from "../graph/graph-types.js";
+export interface SprintVelocity {
+    sprint: string;
+    tasksCompleted: number;
+    totalPoints: number;
+    avgPointsPerTask: number;
+    avgCompletionHours: number | null;
+    tasks: VelocityTask[];
+}
+export interface VelocityTask {
+    id: string;
+    title: string;
+    xpSize: string;
+    points: number;
+    completionHours: number | null;
+}
+export interface VelocitySummary {
+    sprints: SprintVelocity[];
+    overall: {
+        totalTasksCompleted: number;
+        totalPoints: number;
+        avgPointsPerSprint: number;
+        avgCompletionHours: number | null;
+    };
+}
+/**
+ * Calculate velocity metrics for all sprints in the graph.
+ */
+export declare function calculateVelocity(doc: GraphDocument): VelocitySummary;
+//# sourceMappingURL=velocity.d.ts.map

package/dist/core/planner/velocity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocity.d.ts","sourceRoot":"","sources":["../../../src/core/planner/velocity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,yBAAyB,CAAC;AAOxE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE;QACP,mBAAmB,EAAE,MAAM,CAAC;QAC5B,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAwErE"}

package/dist/core/planner/velocity.js

@@ -0,0 +1,92 @@
+/**
+ * Velocity tracking: measures sprint completion metrics.
+ *
+ * Computes:
+ * - Tasks completed per sprint
+ * - Average XP size completed
+ * - Estimated completion time (based on created→done timestamps)
+ */
+import { logger } from "../utils/logger.js";
+const XP_SIZE_POINTS = {
+    XS: 1, S: 2, M: 3, L: 5, XL: 8,
+};
+/**
+ * Calculate velocity metrics for all sprints in the graph.
+ */
+export function calculateVelocity(doc) {
+    // Group done tasks by sprint
+    const doneTasks = doc.nodes.filter((n) => n.status === "done" && (n.type === "task" || n.type === "subtask"));
+    const bySprint = new Map();
+    for (const node of doneTasks) {
+        const sprint = node.sprint ?? "(no sprint)";
+        const group = bySprint.get(sprint) ?? [];
+        group.push(node);
+        bySprint.set(sprint, group);
+    }
+    const sprints = [];
+    for (const [sprint, tasks] of bySprint) {
+        const velocityTasks = tasks.map((t) => {
+            const points = XP_SIZE_POINTS[t.xpSize ?? "M"] ?? 3;
+            const completionHours = computeCompletionHours(t);
+            return {
+                id: t.id,
+                title: t.title,
+                xpSize: t.xpSize ?? "M",
+                points,
+                completionHours,
+            };
+        });
+        const totalPoints = velocityTasks.reduce((sum, t) => sum + t.points, 0);
+        const hoursValues = velocityTasks
+            .map((t) => t.completionHours)
+            .filter((h) => h !== null);
+        sprints.push({
+            sprint,
+            tasksCompleted: tasks.length,
+            totalPoints,
+            avgPointsPerTask: tasks.length > 0 ? Math.round((totalPoints / tasks.length) * 10) / 10 : 0,
+            avgCompletionHours: hoursValues.length > 0
+                ? Math.round((hoursValues.reduce((a, b) => a + b, 0) / hoursValues.length) * 10) / 10
+                : null,
+            tasks: velocityTasks,
+        });
+    }
+    // Sort sprints by name
+    sprints.sort((a, b) => a.sprint.localeCompare(b.sprint));
+    const totalTasksCompleted = doneTasks.length;
+    const totalPoints = sprints.reduce((sum, s) => sum + s.totalPoints, 0);
+    const sprintCount = sprints.filter((s) => s.sprint !== "(no sprint)").length || 1;
+    const allHours = sprints
+        .flatMap((s) => s.tasks)
+        .map((t) => t.completionHours)
+        .filter((h) => h !== null);
+    logger.info(`Velocity: ${totalTasksCompleted} tasks done, ${totalPoints} points across ${sprints.length} sprints`);
+    return {
+        sprints,
+        overall: {
+            totalTasksCompleted,
+            totalPoints,
+            avgPointsPerSprint: Math.round((totalPoints / sprintCount) * 10) / 10,
+            avgCompletionHours: allHours.length > 0
+                ? Math.round((allHours.reduce((a, b) => a + b, 0) / allHours.length) * 10) / 10
+                : null,
+        },
+    };
+}
+/**
+ * Estimate completion time in hours from createdAt to updatedAt.
+ * Returns null if timestamps are invalid or equal.
+ */
+function computeCompletionHours(node) {
+    try {
+        const created = new Date(node.createdAt).getTime();
+        const updated = new Date(node.updatedAt).getTime();
+        if (isNaN(created) || isNaN(updated) || updated <= created)
+            return null;
+        return Math.round(((updated - created) / (1000 * 60 * 60)) * 10) / 10;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=velocity.js.map

package/dist/core/planner/velocity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocity.js","sourceRoot":"","sources":["../../../src/core/planner/velocity.ts"],"names":[],"mappings":"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"}