@projitive/mcp 1.0.7 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.7**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.8**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -177,7 +177,7 @@ npm run test
 #### `projectNext`
 
 - **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
-- **Input**: `maxDepth?`, `limit?`
+- **Input**: `limit?`
 - **Output Example (Markdown)**:
 
 ```markdown
@@ -294,7 +294,7 @@ npm run test
 #### `taskNext`
 
 - **Purpose**: one-step workflow for project discovery + best task selection + evidence/read-order output.
-- **Input**: `maxDepth?`, `topCandidates?`
+- **Input**: `limit?`
 - **Output Example (Markdown)**:
 
 ```markdown

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.0.7",
+    "version": "1.1.1",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",
@@ -14,6 +14,8 @@
     },
     "scripts": {
         "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "benchmark": "vitest bench --run",
         "lint": "tsc -p tsconfig.json --noEmit",
         "build": "rm -rf output && tsc -p tsconfig.json",
         "prepublishOnly": "npm run build",
@@ -28,6 +30,7 @@
     },
     "devDependencies": {
         "@types/node": "^24.3.0",
+        "@vitest/coverage-v8": "^3.2.4",
         "tsx": "^4.20.5",
         "typescript": "^5.9.2",
         "vitest": "^3.2.4"

package/output/source/{helpers/catch → common}/catch.js

@@ -1,10 +1,10 @@
-// 辅助函数：检查是否为 PromiseLike
+// Helper function: check if value is PromiseLike
 function isPromiseLike(value) {
     return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
 }
 /**
- * 构造成功结果对象
- * isError 始终返回 false
+ * Construct success result object
+ * isError always returns false
  */
 function createSuccess(value) {
     return {
@@ -14,8 +14,8 @@ function createSuccess(value) {
     };
 }
 /**
- * 构造失败结果对象
- * isError 始终返回 true
+ * Construct failure result object
+ * isError always returns true
  */
 function createFailure(error) {
     return {
@@ -43,6 +43,6 @@ export async function catchIt(input) {
     catch (error) {
         return createFailure(error);
     }
-    // 理论上不会到达这里，兜底类型安全
+    // Theoretically shouldn't reach here, fallback for type safety
     return createFailure(new Error('Unexpected input type'));
 }

package/output/source/{helpers/catch → common}/catch.test.js

@@ -1,39 +1,39 @@
 import { describe, it, expect } from 'vitest';
 import { catchIt } from './catch.js';
 describe('catchIt', () => {
-    it('同步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+    it('sync function should return value, error undefined, isError false', async () => {
         const result = await catchIt(() => 123);
         expect(result.value).toBe(123);
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('异步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+    it('async function should return value, error undefined, isError false', async () => {
         const result = await catchIt(async () => 456);
         expect(result.value).toBe(456);
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('同步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('sync throw should return error, value undefined, isError true', async () => {
         const error = new Error('fail');
         const result = await catchIt(() => { throw error; });
         expect(result.value).toBeUndefined();
         expect(result.error).toBe(error);
         expect(result.isError()).toBe(true);
     });
-    it('异步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('async throw should return error, value undefined, isError true', async () => {
         const error = new Error('fail-async');
         const result = await catchIt(() => Promise.reject(error));
         expect(result.value).toBeUndefined();
         expect(result.error).toBe(error);
         expect(result.isError()).toBe(true);
     });
-    it('PromiseLike resolve 时应返回 value，error 为 undefined，isError 为 false', async () => {
+    it('PromiseLike resolve should return value, error undefined, isError false', async () => {
         const result = await catchIt(Promise.resolve('ok'));
         expect(result.value).toBe('ok');
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('PromiseLike reject 时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('PromiseLike reject should return error, value undefined, isError true', async () => {
         const error = new Error('promise-fail');
         const result = await catchIt(Promise.reject(error));
         expect(result.value).toBeUndefined();

package/output/source/common/confidence.js

@@ -0,0 +1,231 @@
+/**
+ * Projitive MCP - Confidence Scoring for Spec v1.1.0
+ *
+ * This module implements the confidence scoring algorithm for auto-discovery
+ * and task creation, along with validation hooks integration.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CONFIDENCE_WEIGHTS, CONFIDENCE_THRESHOLDS } from "../types.js";
+// ============================================================================
+// Confidence Scoring Algorithm
+// ============================================================================
+/**
+ * Calculate confidence score based on the three factors
+ * Formula: context_completeness * 0.4 + similar_task_history * 0.3 + specification_clarity * 0.3
+ */
+export function calculateConfidenceScore(factors) {
+    // Validate input ranges
+    const validateFactor = (value, name) => {
+        if (value < 0 || value > 1) {
+            console.warn(`[Confidence] ${name} value ${value} is outside [0, 1] range, clamping`);
+            return Math.max(0, Math.min(1, value));
+        }
+        return value;
+    };
+    const contextCompleteness = validateFactor(factors.contextCompleteness, "contextCompleteness");
+    const similarTaskHistory = validateFactor(factors.similarTaskHistory, "similarTaskHistory");
+    const specificationClarity = validateFactor(factors.specificationClarity, "specificationClarity");
+    // Calculate weighted score
+    const score = contextCompleteness * CONFIDENCE_WEIGHTS.contextCompleteness +
+        similarTaskHistory * CONFIDENCE_WEIGHTS.similarTaskHistory +
+        specificationClarity * CONFIDENCE_WEIGHTS.specificationClarity;
+    // Determine recommendation
+    let recommendation;
+    if (score >= CONFIDENCE_THRESHOLDS.autoCreate) {
+        recommendation = "auto_create";
+    }
+    else if (score >= CONFIDENCE_THRESHOLDS.reviewRequired) {
+        recommendation = "review_required";
+    }
+    else {
+        recommendation = "do_not_create";
+    }
+    return {
+        score,
+        factors: {
+            contextCompleteness,
+            similarTaskHistory,
+            specificationClarity,
+        },
+        recommendation,
+    };
+}
+// ============================================================================
+// Factor Calculation Helpers
+// ============================================================================
+/**
+ * Calculate context completeness factor by checking available governance artifacts
+ */
+export async function calculateContextCompleteness(governanceDir) {
+    const requiredFiles = [
+        "tasks.md",
+        "roadmap.md",
+        "README.md"
+    ];
+    const optionalFiles = [
+        "hooks/task_no_actionable.md",
+        "hooks/task_auto_create_validation.md"
+    ];
+    let availableCount = 0;
+    const totalFiles = requiredFiles.length + optionalFiles.length;
+    // Check required files
+    for (const file of requiredFiles) {
+        const filePath = path.join(governanceDir, file);
+        try {
+            await fs.access(filePath);
+            availableCount++;
+        }
+        catch {
+            // File doesn't exist
+        }
+    }
+    // Check optional files (weighted 0.5 each)
+    for (const file of optionalFiles) {
+        const filePath = path.join(governanceDir, file);
+        try {
+            await fs.access(filePath);
+            availableCount += 0.5;
+        }
+        catch {
+            // File doesn't exist
+        }
+    }
+    return Math.min(1, availableCount / totalFiles);
+}
+/**
+ * Calculate similar task history success rate
+ */
+export function calculateSimilarTaskHistory(tasks, candidateTaskSummary) {
+    // Filter similar tasks based on keyword matching
+    const keywords = candidateTaskSummary.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+    const similarTasks = tasks.filter(task => {
+        const taskText = `${task.title} ${task.summary}`.toLowerCase();
+        return keywords.some(keyword => taskText.includes(keyword));
+    });
+    if (similarTasks.length === 0) {
+        return 0.5; // Neutral score when no history
+    }
+    // Calculate success rate
+    const completedTasks = similarTasks.filter(task => task.status === "DONE");
+    return completedTasks.length / similarTasks.length;
+}
+/**
+ * Calculate specification clarity factor
+ */
+export function calculateSpecificationClarity(projectContext) {
+    let clarity = 0.3; // Base clarity
+    if (projectContext.hasRoadmap)
+        clarity += 0.2;
+    if (projectContext.hasDesignDocs)
+        clarity += 0.2;
+    if (projectContext.hasClearAcceptanceCriteria)
+        clarity += 0.3;
+    return Math.min(1, clarity);
+}
+// ============================================================================
+// Validation Hooks Integration
+// ============================================================================
+const TASK_AUTO_CREATE_VALIDATION_HOOK = "task_auto_create_validation.md";
+const DEFAULT_TASK_AUTO_CREATE_VALIDATION_HOOK = `# Task Auto-Create Validation Hook
+
+## Pre-Creation Checklist
+- [ ] Context files exist and are readable
+- [ ] Similar tasks have been completed successfully
+- [ ] Acceptance criteria are clear and testable
+- [ ] Dependencies are identified and available
+
+## Post-Creation Actions
+- [ ] Add evidence link to analysis document
+- [ ] Notify relevant stakeholders (if configured)
+- [ ] Schedule validation review (24h for high-confidence)
+`;
+/**
+ * Check if task auto-create validation hook exists
+ */
+export async function hasTaskAutoCreateValidationHook(governanceDir) {
+    const hookPath = path.join(governanceDir, "hooks", TASK_AUTO_CREATE_VALIDATION_HOOK);
+    try {
+        await fs.access(hookPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get or create task auto-create validation hook
+ */
+export async function getOrCreateTaskAutoCreateValidationHook(governanceDir) {
+    const hooksDir = path.join(governanceDir, "hooks");
+    const hookPath = path.join(hooksDir, TASK_AUTO_CREATE_VALIDATION_HOOK);
+    try {
+        // Try to read existing hook
+        const content = await fs.readFile(hookPath, "utf-8");
+        return content;
+    }
+    catch {
+        // Create hooks directory if it doesn't exist
+        try {
+            await fs.mkdir(hooksDir, { recursive: true });
+        }
+        catch {
+            // Directory already exists or creation failed silently
+        }
+        // Create default hook
+        await fs.writeFile(hookPath, DEFAULT_TASK_AUTO_CREATE_VALIDATION_HOOK, "utf-8");
+        return DEFAULT_TASK_AUTO_CREATE_VALIDATION_HOOK;
+    }
+}
+/**
+ * Run pre-creation validation checklist
+ */
+export async function runPreCreationValidation(governanceDir, confidenceScore) {
+    const issues = [];
+    // Check confidence score first
+    if (confidenceScore.recommendation === "do_not_create") {
+        issues.push(`Confidence score ${confidenceScore.score.toFixed(2)} is below threshold (${CONFIDENCE_THRESHOLDS.reviewRequired})`);
+    }
+    // Check context completeness
+    if (confidenceScore.factors.contextCompleteness < 0.6) {
+        issues.push(`Context completeness (${confidenceScore.factors.contextCompleteness.toFixed(2)}) is low - more governance artifacts recommended`);
+    }
+    // Check for validation hook
+    const hasHook = await hasTaskAutoCreateValidationHook(governanceDir);
+    if (!hasHook) {
+        issues.push("Task auto-create validation hook not found - will create default hook");
+    }
+    return {
+        passed: issues.length === 0 || confidenceScore.recommendation === "auto_create",
+        issues,
+    };
+}
+// ============================================================================
+// Confidence Report Generation
+// ============================================================================
+/**
+ * Generate a human-readable confidence report
+ */
+export function generateConfidenceReport(confidenceScore) {
+    const lines = [
+        "# Confidence Score Report",
+        "",
+        `## Final Score: ${(confidenceScore.score * 100).toFixed(0)}%`,
+        `**Recommendation**: ${confidenceScore.recommendation.replace(/_/g, " ")}`,
+        "",
+        "## Factor Breakdown",
+        "",
+        `| Factor | Score | Weight | Contribution |`,
+        `|--------|-------|--------|--------------|`,
+        `| Context Completeness | ${(confidenceScore.factors.contextCompleteness * 100).toFixed(0)}% | ${(CONFIDENCE_WEIGHTS.contextCompleteness * 100).toFixed(0)}% | ${(confidenceScore.factors.contextCompleteness * CONFIDENCE_WEIGHTS.contextCompleteness * 100).toFixed(0)}% |`,
+        `| Similar Task History | ${(confidenceScore.factors.similarTaskHistory * 100).toFixed(0)}% | ${(CONFIDENCE_WEIGHTS.similarTaskHistory * 100).toFixed(0)}% | ${(confidenceScore.factors.similarTaskHistory * CONFIDENCE_WEIGHTS.similarTaskHistory * 100).toFixed(0)}% |`,
+        `| Specification Clarity | ${(confidenceScore.factors.specificationClarity * 100).toFixed(0)}% | ${(CONFIDENCE_WEIGHTS.specificationClarity * 100).toFixed(0)}% | ${(confidenceScore.factors.specificationClarity * CONFIDENCE_WEIGHTS.specificationClarity * 100).toFixed(0)}% |`,
+        "",
+        "## Thresholds",
+        "",
+        `- Auto-create: >= ${(CONFIDENCE_THRESHOLDS.autoCreate * 100).toFixed(0)}%`,
+        `- Review required: ${(CONFIDENCE_THRESHOLDS.reviewRequired * 100).toFixed(0)}% - ${(CONFIDENCE_THRESHOLDS.autoCreate * 100).toFixed(0)}%`,
+        `- Do not create: < ${(CONFIDENCE_THRESHOLDS.reviewRequired * 100).toFixed(0)}%`,
+    ];
+    return lines.join("\n");
+}

package/output/source/common/confidence.test.js

@@ -0,0 +1,205 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { calculateConfidenceScore, calculateContextCompleteness, calculateSimilarTaskHistory, calculateSpecificationClarity, hasTaskAutoCreateValidationHook, getOrCreateTaskAutoCreateValidationHook, runPreCreationValidation, generateConfidenceReport, } from "./confidence.js";
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-confidence-test-"));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map(async (dir) => {
+        await fs.rm(dir, { recursive: true, force: true });
+    }));
+});
+describe("confidence module", () => {
+    describe("calculateConfidenceScore", () => {
+        it("calculates confidence score with valid inputs", () => {
+            const result = calculateConfidenceScore({
+                contextCompleteness: 0.8,
+                similarTaskHistory: 0.7,
+                specificationClarity: 0.9,
+            });
+            expect(result.score).toBeGreaterThan(0);
+            expect(result.score).toBeLessThanOrEqual(1);
+            expect(result.recommendation).toBeDefined();
+        });
+        it("recommends auto_create for high confidence scores", () => {
+            const result = calculateConfidenceScore({
+                contextCompleteness: 1.0,
+                similarTaskHistory: 1.0,
+                specificationClarity: 1.0,
+            });
+            expect(result.recommendation).toBe("auto_create");
+        });
+        it("recommends review_required for medium confidence scores", () => {
+            const result = calculateConfidenceScore({
+                contextCompleteness: 0.7,
+                similarTaskHistory: 0.7,
+                specificationClarity: 0.7,
+            });
+            expect(result.recommendation).toBe("review_required");
+        });
+        it("recommends do_not_create for low confidence scores", () => {
+            const result = calculateConfidenceScore({
+                contextCompleteness: 0.0,
+                similarTaskHistory: 0.0,
+                specificationClarity: 0.0,
+            });
+            expect(result.recommendation).toBe("do_not_create");
+        });
+        it("clamps values outside [0, 1] range", () => {
+            const result = calculateConfidenceScore({
+                contextCompleteness: 1.5,
+                similarTaskHistory: -0.5,
+                specificationClarity: 2.0,
+            });
+            expect(result.factors.contextCompleteness).toBe(1);
+            expect(result.factors.similarTaskHistory).toBe(0);
+            expect(result.factors.specificationClarity).toBe(1);
+        });
+    });
+    describe("calculateContextCompleteness", () => {
+        it("returns 0 for empty directory", async () => {
+            const root = await createTempDir();
+            const completeness = await calculateContextCompleteness(root);
+            expect(completeness).toBe(0);
+        });
+        it("returns higher score for more complete context", async () => {
+            const root = await createTempDir();
+            await fs.writeFile(path.join(root, "tasks.md"), "", "utf-8");
+            await fs.writeFile(path.join(root, "roadmap.md"), "", "utf-8");
+            await fs.writeFile(path.join(root, "README.md"), "", "utf-8");
+            const completeness = await calculateContextCompleteness(root);
+            expect(completeness).toBeGreaterThan(0.5);
+        });
+    });
+    describe("calculateSimilarTaskHistory", () => {
+        const sampleTasks = [
+            {
+                id: "TASK-0001",
+                title: "Implement feature X",
+                status: "DONE",
+                summary: "Build core functionality for feature X",
+                owner: "ai-copilot",
+                updatedAt: "2026-02-22T00:00:00.000Z",
+                links: [],
+                roadmapRefs: [],
+            },
+            {
+                id: "TASK-0002",
+                title: "Test feature Y",
+                status: "TODO",
+                summary: "Write tests for feature Y",
+                owner: "ai-copilot",
+                updatedAt: "2026-02-22T00:00:00.000Z",
+                links: [],
+                roadmapRefs: [],
+            },
+            {
+                id: "TASK-0003",
+                title: "Implement feature Z",
+                status: "DONE",
+                summary: "Build core functionality for feature Z",
+                owner: "ai-copilot",
+                updatedAt: "2026-02-22T00:00:00.000Z",
+                links: [],
+                roadmapRefs: [],
+            },
+        ];
+        it("returns 0.5 when no similar tasks", () => {
+            const result = calculateSimilarTaskHistory([], "Build something new");
+            expect(result).toBe(0.5);
+        });
+        it("calculates success rate for similar tasks", () => {
+            const result = calculateSimilarTaskHistory(sampleTasks, "Implement feature A with core functionality");
+            expect(result).toBeGreaterThan(0);
+            expect(result).toBeLessThanOrEqual(1);
+        });
+        it("handles tasks with no matching keywords", () => {
+            const result = calculateSimilarTaskHistory(sampleTasks, "Something completely different unrelated");
+            expect(result).toBe(0.5);
+        });
+    });
+    describe("calculateSpecificationClarity", () => {
+        it("returns base clarity with no context", () => {
+            const result = calculateSpecificationClarity({});
+            expect(result).toBe(0.3);
+        });
+        it("increases clarity with roadmap", () => {
+            const result = calculateSpecificationClarity({ hasRoadmap: true });
+            expect(result).toBeGreaterThan(0.3);
+        });
+        it("increases clarity with design docs", () => {
+            const result = calculateSpecificationClarity({ hasDesignDocs: true });
+            expect(result).toBeGreaterThan(0.3);
+        });
+        it("reaches maximum clarity with all factors", () => {
+            const result = calculateSpecificationClarity({
+                hasRoadmap: true,
+                hasDesignDocs: true,
+                hasClearAcceptanceCriteria: true,
+            });
+            expect(result).toBe(1);
+        });
+    });
+    describe("validation hooks", () => {
+        it("detects missing validation hook", async () => {
+            const root = await createTempDir();
+            const hasHook = await hasTaskAutoCreateValidationHook(root);
+            expect(hasHook).toBe(false);
+        });
+        it("creates default validation hook", async () => {
+            const root = await createTempDir();
+            const hookContent = await getOrCreateTaskAutoCreateValidationHook(root);
+            expect(hookContent).toContain("Task Auto-Create Validation Hook");
+        });
+        it("reads existing validation hook", async () => {
+            const root = await createTempDir();
+            const hooksDir = path.join(root, "hooks");
+            await fs.mkdir(hooksDir, { recursive: true });
+            const hookPath = path.join(hooksDir, "task_auto_create_validation.md");
+            await fs.writeFile(hookPath, "custom hook content", "utf-8");
+            const hookContent = await getOrCreateTaskAutoCreateValidationHook(root);
+            expect(hookContent).toBe("custom hook content");
+        });
+    });
+    describe("runPreCreationValidation", () => {
+        it("validates confidence score", async () => {
+            const root = await createTempDir();
+            const confidenceScore = calculateConfidenceScore({
+                contextCompleteness: 0.9,
+                similarTaskHistory: 0.9,
+                specificationClarity: 0.9,
+            });
+            const result = await runPreCreationValidation(root, confidenceScore);
+            expect(result.passed).toBeDefined();
+            expect(result.issues).toBeInstanceOf(Array);
+        });
+    });
+    describe("generateConfidenceReport", () => {
+        it("generates human-readable report", () => {
+            const confidenceScore = calculateConfidenceScore({
+                contextCompleteness: 0.8,
+                similarTaskHistory: 0.7,
+                specificationClarity: 0.9,
+            });
+            const report = generateConfidenceReport(confidenceScore);
+            expect(report).toContain("Confidence Score Report");
+            expect(report).toContain("Final Score");
+            expect(report).toContain("Factor Breakdown");
+            expect(report).toContain("Thresholds");
+        });
+        it("includes recommendation in report", () => {
+            const confidenceScore = calculateConfidenceScore({
+                contextCompleteness: 1.0,
+                similarTaskHistory: 1.0,
+                specificationClarity: 1.0,
+            });
+            const report = generateConfidenceReport(confidenceScore);
+            expect(report).toContain("auto create");
+        });
+    });
+});