@projitive/mcp 1.2.0 → 2.0.1

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

@@ -0,0 +1,164 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ensureStore, getMarkdownViewState, getStoreVersion, loadActionableTasksFromStore, loadRoadmapIdsFromStore, loadRoadmapsFromStore, loadTaskStatusStatsFromStore, loadTasksFromStore, markMarkdownViewBuilt, markMarkdownViewDirty, replaceRoadmapsInStore, replaceTasksInStore, upsertRoadmapInStore, upsertTaskInStore, } from "./store.js";
+const tempPaths = [];
+async function createTempDbPath() {
+    const sandboxRoot = path.join(process.cwd(), ".tmp", "store-tests");
+    await fs.mkdir(sandboxRoot, { recursive: true });
+    const dir = await fs.mkdtemp(path.join(sandboxRoot, "case-"));
+    tempPaths.push(dir);
+    return path.join(dir, ".projitive");
+}
+async function readRawStore(dbPath) {
+    const content = await fs.readFile(dbPath, "utf8");
+    return JSON.parse(content);
+}
+function task(input) {
+    return {
+        id: input.id,
+        title: input.title,
+        status: input.status ?? "TODO",
+        owner: input.owner ?? "",
+        summary: input.summary ?? "",
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+        links: input.links ?? [],
+        roadmapRefs: input.roadmapRefs ?? [],
+        subState: input.subState,
+        blocker: input.blocker,
+    };
+}
+function milestone(input) {
+    return {
+        id: input.id,
+        title: input.title,
+        status: input.status ?? "active",
+        time: input.time,
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+    };
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+describe("store", () => {
+    it("initializes JSON store with default meta/view state", async () => {
+        const dbPath = await createTempDbPath();
+        await ensureStore(dbPath);
+        const store = await readRawStore(dbPath);
+        expect(store.schema).toBe("projitive-json-store");
+        expect(store.meta.store_schema_version).toBe(3);
+        expect(store.meta.tasks_version).toBe(0);
+        expect(store.meta.roadmaps_version).toBe(0);
+        expect(store.view_state.tasks_markdown.dirty).toBe(true);
+        expect(store.view_state.tasks_markdown.lastSourceVersion).toBe(0);
+        expect(store.view_state.roadmaps_markdown.dirty).toBe(true);
+        expect(store.view_state.roadmaps_markdown.lastSourceVersion).toBe(0);
+        expect(Array.isArray(store.migration_history)).toBe(true);
+    });
+    it("tracks view state dirty/build transitions", async () => {
+        const dbPath = await createTempDbPath();
+        await ensureStore(dbPath);
+        const initial = await getMarkdownViewState(dbPath, "tasks_markdown");
+        expect(initial.dirty).toBe(true);
+        await markMarkdownViewBuilt(dbPath, "tasks_markdown", 7, "2026-03-13T00:00:00.000Z");
+        const built = await getMarkdownViewState(dbPath, "tasks_markdown");
+        expect(built.dirty).toBe(false);
+        expect(built.lastSourceVersion).toBe(7);
+        expect(built.lastBuiltAt).toBe("2026-03-13T00:00:00.000Z");
+        await markMarkdownViewDirty(dbPath, "tasks_markdown");
+        const dirtyAgain = await getMarkdownViewState(dbPath, "tasks_markdown");
+        expect(dirtyAgain.dirty).toBe(true);
+        expect(dirtyAgain.lastSourceVersion).toBe(7);
+    });
+    it("upserts tasks and updates source/view versions", async () => {
+        const dbPath = await createTempDbPath();
+        await ensureStore(dbPath);
+        await upsertTaskInStore(dbPath, task({
+            id: "TASK-0001",
+            title: "First",
+            status: "TODO",
+            owner: "alice",
+            summary: "first",
+            updatedAt: "2026-03-13T00:00:00.000Z",
+            roadmapRefs: ["ROADMAP-0001"],
+        }));
+        await upsertTaskInStore(dbPath, task({
+            id: "TASK-0001",
+            title: "First Updated",
+            status: "IN_PROGRESS",
+            owner: "alice",
+            summary: "updated",
+            updatedAt: "2026-03-13T01:00:00.000Z",
+            roadmapRefs: ["ROADMAP-0001"],
+            links: ["reports/r1.md"],
+        }));
+        const tasks = await loadTasksFromStore(dbPath);
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0].title).toBe("First Updated");
+        expect(tasks[0].status).toBe("IN_PROGRESS");
+        expect(tasks[0].links).toEqual(["reports/r1.md"]);
+        const tasksVersion = await getStoreVersion(dbPath, "tasks");
+        expect(tasksVersion).toBe(2);
+        const viewState = await getMarkdownViewState(dbPath, "tasks_markdown");
+        expect(viewState.dirty).toBe(true);
+        const store = await readRawStore(dbPath);
+        const updated = store.tasks.find((item) => item.id === "TASK-0001");
+        expect(updated?.recordVersion).toBe(2);
+    });
+    it("replaces task set and computes actionable ranking/stats", async () => {
+        const dbPath = await createTempDbPath();
+        await ensureStore(dbPath);
+        await replaceTasksInStore(dbPath, [
+            task({ id: "TASK-0001", title: "Todo older", status: "TODO", updatedAt: "2026-03-10T00:00:00.000Z" }),
+            task({ id: "TASK-0002", title: "In progress", status: "IN_PROGRESS", updatedAt: "2026-03-12T00:00:00.000Z" }),
+            task({ id: "TASK-0003", title: "Todo newer", status: "TODO", updatedAt: "2026-03-13T00:00:00.000Z" }),
+            task({ id: "TASK-0004", title: "Blocked", status: "BLOCKED", updatedAt: "2026-03-11T00:00:00.000Z" }),
+            task({ id: "TASK-0005", title: "Done", status: "DONE", updatedAt: "2026-03-09T00:00:00.000Z" }),
+        ]);
+        const stats = await loadTaskStatusStatsFromStore(dbPath);
+        expect(stats.todo).toBe(2);
+        expect(stats.inProgress).toBe(1);
+        expect(stats.blocked).toBe(1);
+        expect(stats.done).toBe(1);
+        expect(stats.total).toBe(5);
+        expect(stats.latestUpdatedAt).toBe("2026-03-13T00:00:00.000Z");
+        const actionable = await loadActionableTasksFromStore(dbPath, 2);
+        expect(actionable).toHaveLength(2);
+        expect(actionable[0].id).toBe("TASK-0002");
+        expect(actionable[1].id).toBe("TASK-0003");
+        const tasksVersion = await getStoreVersion(dbPath, "tasks");
+        expect(tasksVersion).toBe(1);
+    });
+    it("upserts/replaces roadmaps and updates versions", async () => {
+        const dbPath = await createTempDbPath();
+        await ensureStore(dbPath);
+        await upsertRoadmapInStore(dbPath, milestone({
+            id: "ROADMAP-0001",
+            title: "Phase 1",
+            status: "active",
+            updatedAt: "2026-03-10T00:00:00.000Z",
+        }));
+        await upsertRoadmapInStore(dbPath, milestone({
+            id: "ROADMAP-0001",
+            title: "Phase 1 done",
+            status: "done",
+            time: "2026-Q1",
+            updatedAt: "2026-03-11T00:00:00.000Z",
+        }));
+        const list1 = await loadRoadmapsFromStore(dbPath);
+        expect(list1).toHaveLength(1);
+        expect(list1[0].title).toBe("Phase 1 done");
+        expect(list1[0].status).toBe("done");
+        expect(list1[0].time).toBe("2026-Q1");
+        await replaceRoadmapsInStore(dbPath, [
+            milestone({ id: "ROADMAP-0002", title: "Phase 2", status: "active", updatedAt: "2026-03-12T00:00:00.000Z" }),
+            milestone({ id: "ROADMAP-0003", title: "Phase 3", status: "done", updatedAt: "2026-03-13T00:00:00.000Z" }),
+        ]);
+        const ids = await loadRoadmapIdsFromStore(dbPath);
+        expect(ids).toEqual(["ROADMAP-0003", "ROADMAP-0002"]);
+        const roadmapsVersion = await getStoreVersion(dbPath, "roadmaps");
+        expect(roadmapsVersion).toBe(3);
+        const viewState = await getMarkdownViewState(dbPath, "roadmaps_markdown");
+        expect(viewState.dirty).toBe(true);
+    });
+});

package/output/source/index.js

@@ -18,7 +18,7 @@ const MCP_RUNTIME_VERSION = typeof packageJson.version === "string" && packageJs
 const server = new McpServer({
     name: "projitive",
     version: MCP_RUNTIME_VERSION,
-    description: "Semantic Projitive MCP for project/task discovery and agent guidance with markdown-first outputs",
+    description: "Semantic Projitive MCP for project/task discovery and agent guidance with sqlite-first governance outputs",
 });
 // 注册所有模块
 registerTools(server);

package/output/source/prompts/quickStart.js

@@ -54,6 +54,8 @@ export function registerQuickStartPrompt(server) {
             "",
             "### Option A: Auto-select (Recommended)",
             "Call `taskNext()` to get highest-priority actionable task.",
+            "If no actionable tasks are returned and roadmap has active goals, analyze roadmap context and create 1-3 TODO tasks manually.",
+            "Then call `taskNext()` again to re-rank.",
             "",
             "### Option B: Manual select",
             "1. Call `taskList()` to list all tasks",
@@ -65,12 +67,27 @@ export function registerQuickStartPrompt(server) {
             "After getting task context:",
             "1. Read evidence links in Suggested Read Order",
             "2. Understand task requirements and acceptance criteria",
-            "3. Edit governance markdown only (tasks/designs/reports/roadmap)",
-            "4. Update task status:",
+            "3. Write governance source via tools (`taskUpdate` / `roadmapUpdate`) instead of editing tasks.md/roadmap.md directly",
+            "4. Update docs (`designs/` / `reports/`) as required by evidence",
+            "5. If immediate markdown snapshots are needed, call `syncViews(projectPath=..., force=true)`",
+            "6. Update task status:",
             "   - TODO → IN_PROGRESS (when starting execution)",
             "   - IN_PROGRESS → DONE (when completed)",
             "   - IN_PROGRESS → BLOCKED (when blocked)",
-            "5. Re-run taskContext() to verify changes",
+            "7. Re-run taskContext() to verify changes",
+            "",
+            "## Autonomous Operating Loop",
+            "",
+            "Keep this loop until no high-value actionable work remains:",
+            "1. Discover: `taskNext()`",
+            "2. Execute: update sqlite + docs + report evidence",
+            "3. Verify: `taskContext()`",
+            "4. Re-prioritize: `taskNext()`",
+            "",
+            "Stop and re-discover only when:",
+            "- Current task is BLOCKED with a clear blocker description and unblock condition",
+            "- Acceptance criteria are met and status is DONE",
+            "- Project has no actionable tasks and requires roadmap-driven task creation",
             "",
             "## Special Cases",
             "",
@@ -78,15 +95,24 @@ export function registerQuickStartPrompt(server) {
             "Call `projectInit(projectPath=\"<project-dir>\")` to initialize governance structure.",
             "",
             "### Case 2: No actionable tasks",
-            "1. Check if tasks.md is missing",
-            "2. Read design documents in projitive://designs/",
-            "3. Create 1-3 new TODO tasks",
+            "1. Check if .projitive database is missing",
+            "2. If roadmap has active goals, split milestones into 1-3 executable TODO tasks",
+            "3. Apply task creation gate before adding each task:",
+            "   - Clear outcome: one-sentence done condition",
+            "   - Verifiable evidence: at least one report/designs/readme link target",
+            "   - Small slice: should be completable in one focused execution cycle",
+            "   - Traceability: include at least one roadmapRefs item when applicable",
+            "   - Distinct scope: avoid overlap with existing DONE/BLOCKED tasks",
+            "4. Prefer unblocking tasks that unlock multiple follow-up tasks",
+            "5. Re-run `taskNext()` to pick the new tasks",
+            "6. If still no tasks, read design documents in projitive://designs/ and create TODO tasks manually",
             "",
             "## Hard Rules",
             "",
             "- **NEVER modify TASK/ROADMAP IDs** - Keep them immutable once assigned",
             "- **Every status transition must have report evidence** - Create execution reports in reports/ directory",
-            "- **Only edit files under .projitive/** - Unless task scope explicitly requires otherwise",
+            "- **SQLite is source of truth** - tasks.md/roadmap.md are generated views and may be overwritten",
+            "- **Prefer tool writes over manual table/view edits** - Use taskUpdate/roadmapUpdate/syncViews",
             "- **Always verify after updates** - Re-run taskContext() to confirm reference consistency",
         ].join("\n");
         return asUserPrompt(text);

package/output/source/prompts/taskDiscovery.js

@@ -53,8 +53,9 @@ export function registerTaskDiscoveryPrompt(server) {
             "",
             "### Artifacts",
             "Check if these files exist:",
-            "- \u2705 tasks.md - Task list (required)",
-            "- \u2705 roadmap.md - Roadmap",
+            "- \u2705 .projitive - SQLite governance database (required)",
+            "- \u2705 tasks.md - Generated task view",
+            "- \u2705 roadmap.md - Generated roadmap view",
             "- \u2705 README.md - Project description",
             "- \u2705 designs/ - Design documents directory",
             "- \u2705 reports/ - Reports directory",
@@ -87,6 +88,14 @@ export function registerTaskDiscoveryPrompt(server) {
             "",
             "Then call `taskContext(projectPath=\"...\", taskId=\"<task-id>\")` for task details.",
             "",
+            "### Discovery Quality Gate (before creating new tasks)",
+            "Only create a TODO when all conditions are true:",
+            "- It can be finished in one focused execution cycle",
+            "- It has explicit done condition and measurable evidence output",
+            "- It links to roadmap/readme/report/design context",
+            "- It does not duplicate an existing TODO/IN_PROGRESS/BLOCKED task",
+            "- It improves project throughput (unblocks or delivers user-visible value)",
+            "",
             "#### Method B: Manual select with taskList()",
             "",
             "1. Call `taskList()` to get all tasks",
@@ -136,7 +145,8 @@ export function registerTaskDiscoveryPrompt(server) {
             "   - Reference history reports in reports/",
             "",
             "3. **Execute task content**",
-            "   - Edit governance files (tasks.md / designs/*.md / reports/*.md / roadmap.md)",
+            "   - Update sqlite task/roadmap tables via MCP tools; edit designs/*.md and reports/*.md as needed",
+            "   - If immediate markdown snapshots are required by another agent/session, call syncViews(force=true)",
             "   - Create execution report (reports/ directory)",
             "   - Update task status to DONE",
             "",
@@ -150,11 +160,14 @@ export function registerTaskDiscoveryPrompt(server) {
             "### Case 1: No tasks at all",
             "",
             "If taskNext() returns empty:",
-            "1. Check if tasks.md exists",
-            "2. Read design documents in designs/ directory",
-            "3. Read roadmap.md to understand project goals",
-            "4. Create 1-3 new TODO tasks",
-            "5. Each task must have:",
+            "1. Check if .projitive exists",
+            "2. Analyze active roadmap milestones and derive 1-3 executable TODO tasks",
+            "3. Prioritize milestone slices that unblock multiple downstream tasks",
+            "4. Re-run taskNext() and continue execution if tasks are available",
+            "5. If still empty, read design documents in designs/ directory",
+            "6. Read roadmap.md to understand project goals",
+            "7. Create 1-3 new TODO tasks",
+            "8. Each task must have:",
             "   - Unique TASK-xxxx ID",
             "   - Clear title",
             "   - Detailed summary",
@@ -169,7 +182,7 @@ export function registerTaskDiscoveryPrompt(server) {
             "",
             "### Case 3: Missing required governance files",
             "",
-            "If tasks.md does not exist:",
+            "If .projitive does not exist:",
             "1. Call `projectInit(projectPath=\"...\")` to initialize governance structure",
             "2. Then restart discovery flow",
             "",
@@ -184,6 +197,7 @@ export function registerTaskDiscoveryPrompt(server) {
             "| `taskList()` | List all tasks |",
             "| `taskContext()` | Get task details |",
             "| `taskUpdate()` | Update task status |",
+            "| `syncViews()` | Force materialize tasks.md/roadmap.md from sqlite |",
         ].join("\n");
         return asUserPrompt(text);
     });

package/output/source/prompts/taskExecution.js

@@ -70,11 +70,12 @@ export function registerTaskExecutionPrompt(server) {
             "   - Fill subState (optional, Spec v1.1.0)",
             "",
             "2. **Execute task content**",
-            "   - Only edit files under .projitive/",
-            "   - tasks.md - Update task status and metadata",
+            "   - Prefer MCP tool writes for sqlite source (`taskUpdate` / `roadmapUpdate`)",
+            "   - .projitive (task table) - Update task status and metadata",
             "   - designs/*.md - Add or update design documents",
             "   - reports/*.md - Create execution reports",
-            "   - roadmap.md - Update roadmap (if needed)",
+            "   - .projitive (roadmap table) - Update roadmap (if needed)",
+            "   - If downstream consumers require immediate markdown snapshots, call `syncViews(..., force=true)`",
             "",
             "3. **Create execution report**",
             "   - Create new report file in reports/ directory",
@@ -107,6 +108,13 @@ export function registerTaskExecutionPrompt(server) {
             "   - Call `taskNext()` for next task",
             "   - Repeat above workflow",
             "",
+            "## Autonomous Progress Rules",
+            "",
+            "- Keep WIP small: drive one task to DONE before starting another unless blocker requires branching.",
+            "- Prefer unblock-first execution: if one small task unlocks multiple tasks, do it first.",
+            "- Avoid churn: do not repeatedly flip status without producing new evidence.",
+            "- Every loop should leave one durable artifact update (task status, report, or roadmap progress).",
+            "",
             "## Special Cases",
             "",
             "### Case 1: Encountered a blocker",
@@ -123,8 +131,10 @@ export function registerTaskExecutionPrompt(server) {
             "",
             "If taskNext() returns empty:",
             "1. Call `projectContext()` to recheck project state",
-            "2. Read design documents in designs/ directory",
-            "3. Create 1-3 new TODO tasks",
+            "2. Analyze active roadmap milestones and find smallest executable slices",
+            "3. Read design documents in designs/ directory to find delivery gaps",
+            "4. Create 1-3 new TODO tasks only if each task has clear done condition and evidence output",
+            "5. Re-run `taskNext()` and continue",
             "",
             "### Case 3: Need to initialize governance",
             "",
@@ -143,9 +153,9 @@ export function registerTaskExecutionPrompt(server) {
             "   - IN_PROGRESS \u2192 DONE: Report REQUIRED",
             "   - IN_PROGRESS \u2192 BLOCKED: Report recommended to explain blocker",
             "",
-            "3. **Only edit files under .projitive/**",
-            "   - Unless task scope explicitly requires modifying other files",
-            "   - Any non-governance file edits must be explained in task summary",
+            "3. **SQLite-first writes only**",
+            "   - tasks.md/roadmap.md are generated views, not authoritative source",
+            "   - Use taskUpdate/roadmapUpdate as primary write path",
             "",
             "4. **Always verify after updates**",
             "   - After every taskUpdate() call",

package/output/source/resources/governance.js

@@ -15,7 +15,7 @@ export function registerGovernanceResources(server, repoRoot) {
     }));
     server.registerResource("governanceTasks", "projitive://governance/tasks", {
         title: "Governance Tasks",
-        description: "Current task pool and status under .projitive/tasks.md",
+        description: "Current task pool markdown view generated from .projitive sqlite task table",
         mimeType: "text/markdown",
     }, async () => ({
         contents: [
@@ -27,7 +27,7 @@ export function registerGovernanceResources(server, repoRoot) {
     }));
     server.registerResource("governanceRoadmap", "projitive://governance/roadmap", {
         title: "Governance Roadmap",
-        description: "Current roadmap under .projitive/roadmap.md",
+        description: "Current roadmap markdown view generated from .projitive sqlite roadmap table",
         mimeType: "text/markdown",
     }, async () => ({
         contents: [

package/output/source/resources/readme.test.js

@@ -10,7 +10,7 @@ describe("readme module", () => {
                 "",
                 "## Required Reading for Agents",
                 "",
-                "- Local: ./design/README.md",
+                "- Local: ./designs/README.md",
                 "- Local: .projitive/tasks.md",
                 "- External: https://example.com/docs",
                 "",
@@ -22,7 +22,7 @@ describe("readme module", () => {
             expect(result.length).toBe(3);
             expect(result[0]).toEqual({
                 source: "Local",
-                value: "./design/README.md",
+                value: "./designs/README.md",
             });
             expect(result[1]).toEqual({
                 source: "Local",