@projitive/mcp 1.2.0 → 2.0.0

package/README.md

@@ -2,80 +2,47 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.8**
+## Version
 
-Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
+- Current Spec Version: projitive-spec v1.0.0
+- MCP Version: 2.0.0
 
-## Agent Delivery Loop
+## 60-Second Start
 
-```mermaid
-flowchart LR
-  A[taskNext / projectNext] --> B[taskContext / projectContext]
-  B --> C[Update tasks/designs/reports]
-  C --> D[taskContext verify]
-  D --> E{More actionable work?}
-  E -->|Yes| A
-  E -->|No| F[Done / wait for new tasks]
-```
-
-## Why Developers Choose This MCP
-
-- Predictable API family: `List/Context` as core, `Next/Scan/Locate` for acceleration.
-- Governance-safe automation: state changes are guided by evidence-first workflow.
-- Agent-ready outputs: markdown contracts optimized for tool-chaining, not raw JSON blobs.
-- Production publishing pipeline: release-triggered CI with lint/test/publish gates.
-
-## How It Helps Agents Manage and Advance Projects
-
-This MCP is designed to make agent execution operational, not just informative. It gives agents a closed-loop workflow:
-
-1. **Find what to do next**
-  - `taskNext` or `projectNext` ranks actionable targets.
-2. **Build the right context**
-  - `taskContext` / `projectContext` / `roadmapContext` provide evidence, references, and next-call hints.
-3. **Execute with governance constraints**
-  - Agent updates markdown artifacts (`tasks.md`, `designs/`, `reports/`) with immutable IDs and evidence rules.
-4. **Re-verify and continue**
-  - Re-run `taskContext` (or `roadmapContext`) to confirm consistency, then move to the next task.
+If you only read one section, read this:
 
-In short: it converts agent work from ad-hoc edits into a **discover → decide → execute → verify** delivery loop.
+1. Start server: `npx -y @projitive/mcp`
+2. Configure mcp.json with scan roots and depth
+3. Run: taskNext -> taskContext -> taskUpdate -> taskContext -> taskNext
 
-## Agent Workflow (Shortest Path)
+Why teams use it:
 
-```text
-taskNext
-  -> taskContext
-  -> update artifacts (tasks/designs/reports)
-  -> taskContext (verify)
-  -> taskNext (next cycle)
-```
-
-When no actionable task exists (`actionableTasks: 0`), use bootstrap path:
+- Faster next-task selection
+- Better evidence traceability
+- More predictable multi-agent delivery
 
-```text
-taskNext
-  -> projectContext
-  -> create 1-3 TODO tasks in tasks.md marker block (from roadmap/readme/report gaps)
-  -> taskNext
-```
+## What It Is Useful For
 
-Optional customization: add `hooks/task_no_actionable.md` in governance root to override the default no-task discovery checklist.
+Projitive MCP helps agents move work forward in governed projects without losing traceability.
 
-When the agent starts inside a project:
+- Pick the next highest-value task quickly.
+- Build execution context with linked evidence.
+- Update task and roadmap state in a consistent, auditable way.
+- Keep delivery loop stable across long-running multi-agent workflows.
 
-```text
-projectLocate -> projectContext -> taskList -> taskContext
-```
+## How To Use
 
-## Quick Start
+### 1. Start MCP Server
 
-Use npm package directly in MCP client configuration:
+Use package directly in your MCP client:
 
 ```bash
 npx -y @projitive/mcp
 ```
 
-MCP client config example (`mcp.json`):
+### 2. Add Client Config
+
+Example mcp.json:
 
 ```json
 {
@@ -92,403 +59,127 @@ MCP client config example (`mcp.json`):
 }
 ```
 
-Environment variables (required):
-
-- `PROJITIVE_SCAN_ROOT_PATHS`: required scan roots for discovery methods.
-  - Use platform-delimiter string (`:` on Linux/macOS, `;` on Windows), e.g. `/workspace/a:/workspace/b`.
-  - Fallback: if not set, legacy `PROJITIVE_SCAN_ROOT_PATH` is used.
-- `PROJITIVE_SCAN_MAX_DEPTH`: required scan depth for discovery methods (integer `0-8`).
-
-Local path startup is not the recommended usage mode in this README.
-
-For maintainers/contributors only:
-
-```bash
-cd packages/mcp
-npm ci
-npm run build
-npm run test
-```
-
-## Spec Version
-
-- Current aligned spec version: `projitive-spec v1.0.0`
-- Note: Projitive is a general governance specification; MCP is one implementation of this spec.
-- Alignment rule: MCP major version must match the spec major version (currently both `v1.x`).
-
-## Design Boundaries
-
-- MCP handles discovery, locating, summarization, and execution guidance.
-- Agents/AI handle reading and updating markdown content.
-- MCP does not provide direct artifact-write APIs such as `task.update_*`, `roadmap.update_*`, or `sync_*`.
-- All tool outputs are agent-oriented Markdown (not raw JSON objects).
-- Standard output sections: `Summary` / `Evidence` / `Agent Guidance` / `Next Call`.
-- Standard error sections: `Error` / `Next Step` / `Retry Example`.
-
-## MCP Capability Model
-
-- Tools: execute discovery/locating/summarization actions (primary channel).
-- Resources: expose readable governance artifacts for low-cost context loading.
-- Prompts: provide parameterized workflow templates to reduce execution drift.
-
-### Resources (Implemented)
-
-- `projitive://governance/workspace`: reads `.projitive/README.md`
-- `projitive://governance/tasks`: reads `.projitive/tasks.md`
-- `projitive://governance/roadmap`: reads `.projitive/roadmap.md`
-- `projitive://mcp/method-catalog`: method naming and role catalog (`List/Context/Next/Scan/Locate`)
-
-### Prompts (Implemented)
-
-- `executeTaskWorkflow`: standard execution chain (`taskNext -> taskContext -> artifacts update -> verify`)
-- `updateTaskStatusWithEvidence`: status transition + evidence alignment template
-- `triageProjectGovernance`: project-level governance triage template
-
-## Tools Methods
-
-### Discovery Layer
-
-#### `projectInit`
-
-- **Purpose**: manually initialize governance directory structure for a project (default `.projitive`).
-- **Input**: `projectPath`, `governanceDir?`, `force?`
-- **Output Example (Markdown)**:
-
-```markdown
-# projectInit
-
-## Summary
-- projectPath: /workspace/proj-a
-- governanceDir: /workspace/proj-a/.projitive
-- markerPath: /workspace/proj-a/.projitive/.projitive
-- force: false
-
-## Evidence
-- createdFiles: 4
-- updatedFiles: 0
-- skippedFiles: 0
-
-## Agent Guidance
-- If files were skipped and you want to overwrite templates, rerun with force=true.
-- Continue with projectContext and taskList for execution.
-
-## Next Call
-- projectContext(projectPath="/workspace/proj-a/.projitive")
-```
-
-#### `projectNext`
-
-- **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
-- **Input**: `limit?`
-- **Output Example (Markdown)**:
-
-```markdown
-# projectNext
+Required environment variables:
 
-## Summary
-- rootPath: /workspace
-- maxDepth: 3
-- matchedProjects: 8
-- actionableProjects: 3
-- limit: 10
+- PROJITIVE_SCAN_ROOT_PATHS: discovery roots (platform-delimited)
+- PROJITIVE_SCAN_MAX_DEPTH: discovery depth (0-8)
 
-## Evidence
-- rankedProjects:
-1. /workspace/proj-a | actionable=5 | in_progress=2 | todo=3 | blocked=1 | done=4 | latest=2026-02-17T12:00:00.000Z | tasksPath=/workspace/proj-a/tasks.md
-2. /workspace/proj-b | actionable=3 | in_progress=1 | todo=2 | blocked=0 | done=7 | latest=2026-02-16T09:00:00.000Z | tasksPath=/workspace/proj-b/tasks.md
+Fallback: when PROJITIVE_SCAN_ROOT_PATHS is not set, legacy PROJITIVE_SCAN_ROOT_PATH is used.
 
-## Agent Guidance
-- Pick top 1 project and call `projectContext` with its governanceDir.
-- Then call `taskList` and `taskContext` to continue execution.
+### 3. Use The Default Delivery Loop
 
-## Next Call
-- projectContext(projectPath="/workspace/proj-a")
-```
-
-#### `projectScan`
-
-- **Purpose**: scan directories and discover governable projects.
-- **Input**: `(none)`
-- **Output Example (Markdown)**:
-
-```markdown
-# projectScan
-
-## Summary
-- rootPath: /workspace
-- maxDepth: 3
-- discoveredCount: 2
-
-## Evidence
-- projects:
-1. /workspace/proj-a
-2. /workspace/proj-b
-
-## Agent Guidance
-- Use one discovered project path and call `projectLocate` to lock governance root.
-- Then call `projectContext` to inspect current governance state.
-
-## Next Call
-- projectLocate(inputPath="/workspace/proj-a")
-```
-
-#### `projectLocate`
-
-- **Purpose**: when an agent is already inside a project path, resolve the nearest `.projitive` upward.
-- **Input**: `inputPath`
-- **Output Example (Markdown)**:
-
-```markdown
-# projectLocate
-
-## Summary
-- resolvedFrom: /workspace/proj-a/packages/mcp
-- governanceDir: /workspace/proj-a
-- markerPath: /workspace/proj-a/.projitive
-
-## Agent Guidance
-- Call `projectContext` with this governanceDir to get task and roadmap summaries.
-
-## Next Call
-- projectContext(projectPath="/workspace/proj-a")
-```
-
-#### `projectContext`
-
-- **Purpose**: summarize governance state instead of only returning file lists.
-- **Input**: `projectPath`
-- **Output Example (Markdown)**:
-
-```markdown
-# projectContext
-
-## Summary
-- governanceDir: /workspace/proj-a
-- tasksFile: /workspace/proj-a/tasks.md
-- roadmapIds: 3
-
-## Evidence
-### Task Summary
-- total: 12
-- TODO: 4
-- IN_PROGRESS: 3
-- BLOCKED: 1
-- DONE: 4
-
-### Artifacts
-- ✅ README.md
-- ✅ roadmap.md
-- ✅ tasks.md
-- ✅ designs/
-- ✅ reports/
-- ✅ hooks/
-
-## Agent Guidance
-- Start from `taskList` to choose a target task.
-- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.
-
-## Next Call
-- taskList(projectPath="/workspace/proj-a")
-```
-
-### Task Layer
-
-#### `taskNext`
-
-- **Purpose**: one-step workflow for project discovery + best task selection + evidence/read-order output.
-- **Input**: `limit?`
-- **Output Example (Markdown)**:
-
-```markdown
-# taskNext
-
-## Summary
-- rootPath: /workspace
-- maxDepth: 3
-- matchedProjects: 8
-- actionableTasks: 12
-- selectedProject: /workspace/proj-a
-- selectedTaskId: TASK-0003
-- selectedTaskStatus: IN_PROGRESS
-
-## Evidence
-### Selected Task
-- id: TASK-0003
-- title: Build MCP tools
-- taskLocation: /workspace/proj-a/tasks.md#L42
-
-### Top Candidates
-1. TASK-0003 | IN_PROGRESS | Build MCP tools | project=/workspace/proj-a | projectScore=6
-2. TASK-0007 | TODO | Add docs examples | project=/workspace/proj-b | projectScore=5
-
-### Selection Reason
-- Rank rule: projectScore DESC -> taskPriority DESC -> taskUpdatedAt DESC.
-- Selected candidate scores: projectScore=6, taskPriority=2, taskUpdatedAtMs=1739793600000.
-
-### Suggested Read Order
-1. /workspace/proj-a/tasks.md
-2. /workspace/proj-a/designs/mcp-design.md
-3. /workspace/proj-a/reports/mcp-progress.md
-
-## Agent Guidance
-- Start immediately with Suggested Read Order and execute the selected task.
-- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.
-
-## Next Call
-- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
+```mermaid
+flowchart LR
+  A[taskNext / projectNext] --> B[taskContext / projectContext]
+  B --> C[Update task and roadmap + docs]
+  C --> D[taskContext verify]
+  D --> E{More actionable work?}
+  E -->|Yes| A
+  E -->|No| F[Done / wait for new tasks]
 ```
 
-- **Recommended Path**: prefer `taskNext` to avoid multi-hop flow (`projectNext -> projectContext -> taskList -> taskContext`).
-
-#### `taskList`
-
-- **Purpose**: list tasks in current project, with optional status filtering and limiting.
-- **Input**: `projectPath`, `status?`, `limit?`
-- **Output Example (Markdown)**:
+Recommended minimal sequence:
 
-```markdown
-# taskList
+1. taskNext
+2. taskContext
+3. taskUpdate and/or roadmapUpdate
+4. taskContext
+5. taskNext
 
-## Summary
-- governanceDir: /workspace/proj-a
-- tasksPath: /workspace/proj-a/tasks.md
-- filter.status: IN_PROGRESS
-- returned: 2
+### 4. New User Minimal Flow
 
-## Evidence
-- tasks:
-- TASK-0003 | IN_PROGRESS | Build MCP tools | owner=alice | updatedAt=2026-02-17T12:00:00.000Z
-- TASK-0007 | IN_PROGRESS | Add docs examples | owner=bob | updatedAt=2026-02-17T13:30:00.000Z
+This is the shortest end-to-end path from first connection to first governed update:
 
-## Agent Guidance
-- Pick one task ID and call `taskContext`.
-
-## Next Call
-- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
-```
+```mermaid
+sequenceDiagram
+  participant U as User/Agent
+  participant M as Projitive MCP
 
-#### `taskContext`
-
-- **Purpose**: return task detail + related evidence locations in one call (replacing `trace.references`).
-- **Input**: `projectPath`, `taskId`
-- **Output Example (Markdown)**:
-
-```markdown
-# taskContext
-
-## Summary
-- governanceDir: /workspace/proj-a
-- taskId: TASK-0003
-- title: Build MCP tools
-- status: IN_PROGRESS
-- owner: alice
-- updatedAt: 2026-02-17T12:00:00.000Z
-- roadmapRefs: ROADMAP-0001
-- taskLocation: /workspace/proj-a/tasks.md#L42
-
-## Evidence
-### Related Artifacts
-- /workspace/proj-a/tasks.md
-- /workspace/proj-a/designs/mcp-design.md
-- /workspace/proj-a/reports/mcp-progress.md
-
-### Reference Locations
-- /workspace/proj-a/tasks.md#L42: "id": "TASK-0003"
-- /workspace/proj-a/designs/mcp-design.md#L18: Ref: TASK-0003
-
-### Suggested Read Order
-1. /workspace/proj-a/tasks.md
-2. /workspace/proj-a/designs/mcp-design.md
-3. /workspace/proj-a/reports/mcp-progress.md
-
-## Agent Guidance
-- Read the files in Suggested Read Order.
-- Verify whether current status and evidence are consistent.
-- This task is IN_PROGRESS: prioritize finishing with report/design evidence updates.
-- Verify references stay consistent before marking DONE.
-
-## Next Call
-- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
+  U->>M: projectScan()
+  M-->>U: discovered governance projects
+  U->>M: projectContext(projectPath)
+  M-->>U: task/roadmap summary
+  U->>M: taskNext()
+  M-->>U: selected actionable task
+  U->>M: taskContext(projectPath, taskId)
+  M-->>U: evidence and read order
+  U->>M: taskUpdate(projectPath, taskId, updates)
+  M-->>U: updated task state
+  U->>M: taskContext(projectPath, taskId)
+  M-->>U: verification snapshot
 ```
 
-### Roadmap Layer
+## What You Can Do With It
 
-#### `roadmapList`
+### Core Tools
 
-- **Purpose**: list roadmap items and linked task summary.
-- **Input**: `projectPath`
-- **Output Example (Markdown)**:
+| Group | Tool | Purpose |
+| --- | --- | --- |
+| Project | projectInit | Initialize governance structure |
+| Project | projectScan | Discover governable projects |
+| Project | projectNext | Rank actionable projects |
+| Project | projectLocate | Resolve nearest governance root |
+| Project | projectContext | Summarize governance context |
+| Project | syncViews | Force materialize markdown views |
+| Task | taskList | List tasks |
+| Task | taskNext | Select best actionable task |
+| Task | taskContext | Get task evidence and reading order |
+| Task | taskUpdate | Update task state and metadata |
+| Roadmap | roadmapList | List roadmaps and linked tasks |
+| Roadmap | roadmapContext | Get roadmap context |
+| Roadmap | roadmapUpdate | Update roadmap milestone fields |
 
-```markdown
-# roadmapList
+### Resources
 
-## Summary
-- governanceDir: /workspace/proj-a
-- roadmapCount: 2
+- projitive://governance/workspace
+- projitive://governance/tasks
+- projitive://governance/roadmap
+- projitive://mcp/method-catalog
 
-## Evidence
-- roadmaps:
-- ROADMAP-0001 | linkedTasks=6
-- ROADMAP-0002 | linkedTasks=3
+### Prompts
 
-## Agent Guidance
-- Pick one roadmap ID and call `roadmapContext`.
+- executeTaskWorkflow
+- updateTaskStatusWithEvidence
+- triageProjectGovernance
 
-## Next Call
-- roadmapContext(projectPath="/workspace/proj-a", roadmapId="ROADMAP-0001")
-```
+## Design Philosophy
 
-#### `roadmapContext`
+### 1. Source Of Truth vs Views
 
-- **Purpose**: get single roadmap detail and reference locations.
-- **Input**: `projectPath`, `roadmapId`
-- **Output Example (Markdown)**:
+- Governance source data is stored in .projitive.
+- tasks.md and roadmap.md are materialized/generated views.
+- Manual edits on generated views can be overwritten by sync.
 
-```markdown
-# roadmapContext
+### 2. Query Performance Without Extra Files
 
-## Summary
-- governanceDir: /workspace/proj-a
-- roadmapId: ROADMAP-0001
-- relatedTasks: 6
-- references: 9
+- Query path uses embedded DuckDB in memory by default.
+- No extra intermediate DuckDB database file is created.
 
-## Evidence
-### Related Tasks
-- TASK-0001 | DONE | Bootstrap governance
-- TASK-0003 | IN_PROGRESS | Build MCP tools
+### 3. Evidence-First Execution
 
-### Reference Locations
-- /workspace/proj-a/roadmap.md#L21: ROADMAP-0001
-- /workspace/proj-a/tasks.md#L42: "roadmapRefs": ["ROADMAP-0001"]
+- State changes should be backed by report/design/readme evidence.
+- Tool output format is agent-friendly markdown for chained execution.
 
-## Agent Guidance
-- Read roadmap references first, then related tasks.
-- Keep ROADMAP/TASK IDs unchanged while updating markdown files.
+### 4. Deterministic Multi-Agent Workflow
 
-## Next Call
-- roadmapContext(projectPath="/workspace/proj-a", roadmapId="ROADMAP-0001")
-```
+- Prefer tool-based writes over ad-hoc markdown edits.
+- Keep IDs stable and transitions explicit.
+- Re-verify context after each significant update.
 
-## Unified Error Output Example
+## Architecture Documents
 
-```markdown
-# taskContext
+- Index: docs/README_CN.md
+- Current architecture: docs/ARCHITECTURE_CN.md
+- Migration architecture: docs/MIGRATION_ARCHITECTURE_CN.md
+- Historical proposals: REFACTOR_CN.md, REFACTOR_V2_CN.md
 
-## Error
-- cause: Invalid task ID format: TASK-12
+## Development
 
-## Next Step
-- expected format: TASK-0001
-- retry with a valid task ID
+For maintainers:
 
-## Retry Example
-- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0001")
+```bash
+cd packages/mcp
+npm ci
+npm run build
+npm run test
 ```
-
-## Recommended Agent Call Flow
-
-1. `taskNext`: one-step discovery and top task selection (default path).
-2. `taskContext`: fetch detailed evidence for a specific task ID when needed.
-3. `projectNext`: optional project-level scheduling flow when you need project-first dispatch.
-4. When already in a project path, use `projectLocate` to quickly resolve governance root.

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.2.0",
+    "version": "2.0.0",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",
@@ -25,11 +25,14 @@
         "output"
     ],
     "dependencies": {
+        "@duckdb/node-api": "1.5.0-r.1",
         "@modelcontextprotocol/sdk": "^1.17.5",
+        "sql.js": "^1.14.1",
         "zod": "^3.23.8"
     },
     "devDependencies": {
         "@types/node": "^24.3.0",
+        "@types/sql.js": "^1.4.9",
         "@vitest/coverage-v8": "^3.2.4",
         "tsx": "^4.20.5",
         "typescript": "^5.9.2",

package/output/source/common/files.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { catchIt } from "./catch.js";
 const FILE_ARTIFACTS = ["README.md", "roadmap.md", "tasks.md"];
-const DIRECTORY_ARTIFACTS = ["designs", "reports", "hooks"];
+const DIRECTORY_ARTIFACTS = ["designs", "reports", "templates"];
 async function fileLineCount(filePath) {
     const content = await fs.readFile(filePath, "utf-8");
     if (!content) {

package/output/source/common/index.js

@@ -7,3 +7,4 @@ export * from "./response.js";
 export * from "./catch.js";
 export * from "./artifacts.js";
 export * from "./linter.js";
+export * from "./store.js";