@projitive/mcp 1.0.4 → 1.0.6

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.4**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.6**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -149,7 +149,7 @@ npm run test
 #### `projectInit`
 
 - **Purpose**: manually initialize governance directory structure for a project (default `.projitive`).
-- **Input**: `projectPath?`, `governanceDir?`, `force?`
+- **Input**: `projectPath`, `governanceDir?`, `force?`
 - **Output Example (Markdown)**:
 
 ```markdown
@@ -177,7 +177,7 @@ npm run test
 #### `projectNext`
 
 - **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
-- **Input**: `rootPath?`, `maxDepth?`, `limit?`
+- **Input**: `maxDepth?`, `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**: `rootPath?`, `maxDepth?`, `topCandidates?`
+- **Input**: `maxDepth?`, `topCandidates?`
 - **Output Example (Markdown)**:
 
 ```markdown

package/output/package.json

@@ -1,22 +1,21 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",
     "type": "module",
     "bin": {
-        "mcp": "output/index.js"
+        "mcp": "output/source/index.js"
     },
-    "main": "./output/index.js",
-    "types": "./output/index.d.ts",
+    "main": "./output/source/index.js",
     "publishConfig": {
         "access": "public"
     },
     "scripts": {
         "test": "vitest run",
         "lint": "tsc -p tsconfig.json --noEmit",
-        "build": "tsc -p tsconfig.json",
+        "build": "rm -rf output && tsc -p tsconfig.json",
         "prepublishOnly": "npm run build",
         "dev": "tsc -p tsconfig.json --watch"
     },

package/output/source/design-context.js

@@ -0,0 +1,515 @@
+// Design Context Module for Projitive MCP
+// Provides fast-start design context for agents to understand Projitive goals, constraints, and execution rules
+export function registerDesignContextResources(server) {
+    server.registerResource("designQuickStart", "projitive://design/quick-start", {
+        title: "Design Quick Start",
+        description: "Fast-start guide to Projitive design goals, constraints, and execution rules",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://design/quick-start",
+                text: renderDesignQuickStart(),
+            },
+        ],
+    }));
+    server.registerResource("designPrinciples", "projitive://design/principles", {
+        title: "Design Principles",
+        description: "Core design principles governing Projitive specification and MCP implementation",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://design/principles",
+                text: renderDesignPrinciples(),
+            },
+        ],
+    }));
+    server.registerResource("executionRules", "projitive://design/execution-rules", {
+        title: "Execution Rules",
+        description: "Mandatory rules for agent execution within Projitive governance",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://design/execution-rules",
+                text: renderExecutionRules(),
+            },
+        ],
+    }));
+}
+export function registerDesignContextPrompts(server) {
+    server.registerPrompt("understandDesignContext", {
+        title: "Understand Design Context",
+        description: "Quickly load Projitive design goals, constraints, and execution rules",
+        argsSchema: {},
+    }, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Load Projitive design context to understand:",
+                        "1. Design goals and principles",
+                        "2. Constraints and boundaries",
+                        "3. Execution rules for agents",
+                        "",
+                        "Read these resources in order:",
+                        "1. projitive://design/quick-start",
+                        "2. projitive://design/principles",
+                        "3. projitive://design/execution-rules",
+                        "",
+                        "After reading, you should understand:",
+                        "- Projitive is a governance specification for agent-executable projects",
+                        "- MCP is one implementation of this spec",
+                        "- Governance artifacts are markdown-first",
+                        "- IDs must remain immutable, evidence is required for transitions",
+                        "- Agents follow: discover -> decide -> execute -> verify",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("fastStartExecution", {
+        title: "Fast Start Execution",
+        description: "Minimal steps to start executing within Projitive governance",
+        argsSchema: {},
+    }, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Execute Projitive task with minimal calls:",
+                        "",
+                        "Prerequisite:",
+                        "- If target project has no `.projitive`, run: projectInit(projectPath=<project-dir>)",
+                        "",
+                        "STEP 1: Get task (1 call)",
+                        "- Run: taskNext()",
+                        "- Result: selectedTaskId, suggestedReadOrder",
+                        "",
+                        "STEP 2: Load context (1-2 calls)",
+                        "- Read files in suggestedReadOrder",
+                        "- If design context needed: read projitive://design/quick-start",
+                        "",
+                        "STEP 3: Execute task",
+                        "- Edit governance markdown only (tasks/designs/reports)",
+                        "- Update task status with evidence",
+                        "",
+                        "STEP 4: Verify (1 call)",
+                        "- Run: taskContext(projectPath, taskId)",
+                        "- Confirm status/evidence/reference consistency",
+                        "",
+                        "Total calls: 4-6 per task execution cycle",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+}
+// Content renderers
+function renderDesignQuickStart() {
+    return [
+        "# Projitive Design Quick Start",
+        "",
+        "**Version:** 1.0.0  ",
+        "**Purpose:** Fast-start guide for agents to understand Projitive design goals, constraints, and execution rules",
+        "",
+        "## What is Projitive?",
+        "",
+        "Projitive is a **governance specification** for agent-executable projects. It defines:",
+        "- How projects self-describe their goals, tasks, and progress",
+        "- How agents discover and execute work within governance constraints",
+        "- How evidence is captured and validated for state transitions",
+        "",
+        "**MCP (Model Context Protocol)** is one implementation of Projitive spec.",
+        "",
+        "## Core Design Goals",
+        "",
+        "| Goal | Description |",
+        "|------|-------------|",
+        "| **Agent-First** | Governance designed for AI agents, not just human readers |",
+        "| **Markdown-First** | All artifacts are markdown with semantic markers |",
+        "| **Evidence-First** | Every state change requires evidence |",
+        "| **Immutable IDs** | TASK/ROADMAP IDs never change |",
+        "| **Discoverable** | One-call task discovery via `taskNext` |",
+        "",
+        "## Execution Constraints",
+        "",
+        "### Hard Rules (Never Violate)",
+        "",
+        "1. **ID Immutability**: TASK-XXXX and ROADMAP-XXXX IDs must never change",
+        "2. **Evidence Required**: Every status transition must have report evidence",
+        "3. **Markdown Governance**: Only edit files in `.projitive/` (tasks.md, roadmap.md, designs/, reports/)",
+        "4. **Status Machine**: Only valid transitions (TODO↔IN_PROGRESS, IN_PROGRESS→BLOCKED, BLOCKED→IN_PROGRESS, IN_PROGRESS→DONE)",
+        "",
+        "### Soft Guidelines (Prefer When Possible)",
+        "",
+        "- Update `updatedAt` timestamp on every task change",
+        "- Link reports in task `links` array",
+        "- Use `roadmapRefs` to connect tasks to roadmap items",
+        "- Create hooks in `.projitive/hooks/` for custom no-task behavior",
+        "",
+        "## Agent Execution Loop",
+        "",
+        "```",
+        "taskNext → taskContext → execute → taskContext (verify) → taskNext",
+        "```",
+        "",
+        "### Step-by-Step",
+        "",
+        "1. **Discover**: Call `taskNext` to get highest-priority actionable task",
+        "2. **Context**: Call `taskContext` to get full task details and read order",
+        "3. **Read**: Read files in suggested read order",
+        "4. **Execute**: Edit governance markdown, update task status with evidence",
+        "5. **Verify**: Re-run `taskContext` to confirm consistency",
+        "6. **Repeat**: Call `taskNext` for next task",
+        "",
+        "## Quick Reference",
+        "",
+        "| Resource | URI | Purpose |",
+        "|----------|-----|---------|",
+        "| Design Quick Start | `projitive://design/quick-start` | This document |",
+        "| Design Principles | `projitive://design/principles` | Core design principles |",
+        "| Execution Rules | `projitive://design/execution-rules` | Mandatory execution rules |",
+        "| Governance Workspace | `projitive://governance/workspace` | Primary governance README |",
+        "| Governance Tasks | `projitive://governance/tasks` | Current task pool |",
+        "| Governance Roadmap | `projitive://governance/roadmap` | Current roadmap |",
+        "| MCP Method Catalog | `projitive://mcp/method-catalog` | Method naming and purpose |",
+        "",
+        "## Next Steps",
+        "",
+        "1. Read `projitive://design/principles` for core design principles",
+        "2. Read `projitive://design/execution-rules` for mandatory rules",
+        "3. Run `taskNext` to discover your first task",
+        "4. Follow the Agent Execution Loop",
+        "",
+        "---",
+        "*Part of Projitive Design Context resources. See TASK-0006 for implementation details.*",
+    ].join("\n");
+}
+function renderDesignPrinciples() {
+    return [
+        "# Projitive Design Principles",
+        "",
+        "**Version:** 1.0.0  ",
+        "**Purpose:** Core design principles governing Projitive specification and MCP implementation",
+        "",
+        "## 1. Agent-First Design",
+        "",
+        "**Principle:** Governance artifacts are designed primarily for AI agents, not just human readers.",
+        "",
+        "### Implications",
+        "- One-call task discovery via `taskNext`",
+        "- Markdown-first outputs optimized for agent parsing",
+        "- Semantic markers for stable machine reading",
+        "- Clear read order suggestions in tool outputs",
+        "",
+        "### Examples",
+        "```markdown",
+        "## TASK-0001 | DONE | Bootstrap repository",
+        "- owner: ai-copilot",
+        "- summary: Create baseline governance artifacts",
+        "- updatedAt: 2026-02-21T07:48:00.000Z",
+        "```",
+        "",
+        "## 2. Markdown-First Artifacts",
+        "",
+        "**Principle:** All governance artifacts are markdown files with semantic structure.",
+        "",
+        "### Implications",
+        "- Human-readable and machine-parseable",
+        "- Version control friendly (git diffs)",
+        "- No binary lockfiles or proprietary formats",
+        "- Extensible through markdown conventions",
+        "",
+        "### Required Files",
+        "",
+        "| File | Purpose |",
+        "|------|---------|",
+        "| `.projitive/README.md` | Governance workspace overview |",
+        "| `.projitive/tasks.md` | Task pool and status |",
+        "| `.projitive/roadmap.md` | Roadmap items and milestones |",
+        "| `.projitive/designs/*.md` | Design specifications |",
+        "| `.projitive/reports/*.md` | Execution reports and evidence |",
+        "",
+        "## 3. Evidence-First Transitions",
+        "",
+        "**Principle:** Every state change requires evidence to be valid.",
+        "",
+        "### Implications",
+        "- Status transitions without evidence are rejected",
+        "- Reports in `.projitive/reports/` serve as evidence",
+        "- Task `links` array must reference reports",
+        "- `updatedAt` timestamp tracks when evidence was added",
+        "",
+        "### Evidence Requirements by Transition",
+        "",
+        "| Transition | Required Evidence |",
+        "|------------|-------------------|",
+        "| TODO → IN_PROGRESS | Task assignment, initial plan |",
+        "| IN_PROGRESS → DONE | Completion report, test results |",
+        "| IN_PROGRESS → BLOCKED | Blocker description, escalation path |",
+        "| BLOCKED → IN_PROGRESS | Unblock confirmation, new plan |",
+        "",
+        "### Example Evidence Report",
+        "",
+        "```markdown",
+        "# Task Completion Report: TASK-0006",
+        "",
+        "**Date:** 2026-02-21  ",
+        "**Task:** Enhance MCP design onboarding context  ",
+        "**Status:** DONE",
+        "",
+        "## Evidence",
+        "",
+        "1. Created `design-context.ts` with 3 new resources:",
+        "   - projitive://design/quick-start",
+        "   - projitive://design/principles",
+        "   - projitive://design/execution-rules",
+        "",
+        "2. Added 2 new prompts:",
+        "   - understandDesignContext",
+        "   - fastStartExecution",
+        "",
+        "## Verification",
+        "",
+        "- All resources accessible via MCP",
+        "- Prompts provide actionable guidance",
+        "- Design context reduces discovery calls from 5-7 to 1-2",
+        "```",
+        "",
+        "## 4. Immutable IDs",
+        "",
+        "**Principle:** TASK and ROADMAP IDs must never change once created.",
+        "",
+        "### Implications",
+        "- IDs are permanent references across all artifacts",
+        "- Renaming requires creating new ID, deprecating old",
+        "- Links and references remain stable over time",
+        "- Version history is traceable through immutable IDs",
+        "",
+        "### ID Format",
+        "",
+        "```",
+        "TASK-XXXX   # 4-digit sequential task ID",
+        "ROADMAP-XXXX  # 4-digit sequential roadmap ID",
+        "DESIGN-XXXX  # 4-digit sequential design ID",
+        "```",
+        "",
+        "## 5. Discoverable Execution",
+        "",
+        "**Principle:** Agents must be able to discover and execute work with minimal calls.",
+        "",
+        "### Implications",
+        "- One-call task discovery via `taskNext`",
+        "- Clear read order in tool outputs",
+        "- Hints for next call in every response",
+        "- Fallback paths when no actionable tasks exist",
+        "",
+        "### Execution Loop",
+        "",
+        "```",
+        "┌─────────┐    ┌─────────────┐    ┌──────────┐",
+        "│ taskNext │ -> │ taskContext │ -> │  Execute │",
+        "└─────────┘    └─────────────┘    └──────────┘",
+        "     ^                                    │",
+        "     └────────────────────────────────────┘",
+        "                    Verify",
+        "```",
+        "",
+        "### Target Metrics",
+        "",
+        "| Metric | Before | After |",
+        "|--------|--------|-------|",
+        "| Calls to discover task | 3-5 | 1 |",
+        "| Calls to get context | 2-3 | 1 |",
+        "| Calls to verify | 2-3 | 1 |",
+        "| Total per cycle | 7-11 | 3-4 |",
+        "",
+        "---",
+        "*Part of Projitive Design Context resources. See TASK-0006 for implementation details.*",
+    ].join("\n");
+}
+function renderExecutionRules() {
+    return [
+        "# Projitive Execution Rules",
+        "",
+        "**Version:** 1.0.0  ",
+        "**Purpose:** Mandatory rules for agent execution within Projitive governance",
+        "",
+        "> ⚠️ **WARNING**: Violation of Hard Rules may corrupt governance state. Always verify before committing changes.",
+        "",
+        "## Hard Rules (Never Violate)",
+        "",
+        "### RULE-1: ID Immutability",
+        "",
+        "**Rule**: TASK-XXXX and ROADMAP-XXXX IDs must never change once created.",
+        "",
+        "**Rationale**: IDs are permanent references. Changing them breaks all links and history.",
+        "",
+        "**Valid Actions**:",
+        "- Create new ID with new content",
+        "- Mark old ID as deprecated with link to new ID",
+        "- Update references to point to new ID",
+        "",
+        "**Invalid Actions**:",
+        "- Edit existing ID number",
+        "- Rename TASK-0001 to TASK-0002",
+        "- Reuse ID after deletion",
+        "",
+        "---",
+        "",
+        "### RULE-2: Evidence Required",
+        "",
+        "**Rule**: Every status transition must have evidence in `.projitive/reports/`.",
+        "",
+        "**Rationale**: Without evidence, status changes are unverifiable. Reports provide audit trail.",
+        "",
+        "**Valid Actions**:",
+        "- Create report before marking DONE",
+        "- Link report in task `links` array",
+        "- Update `updatedAt` timestamp",
+        "",
+        "**Invalid Actions**:",
+        "- Mark DONE without report",
+        "- Delete report after status change",
+        "- Use external evidence without linking",
+        "",
+        "**Evidence Requirements by Transition**:",
+        "",
+        "| Transition | Required Evidence |",
+        "|------------|-------------------|",
+        "| TODO → IN_PROGRESS | Task assignment, initial plan |",
+        "| IN_PROGRESS → DONE | Completion report, test results |",
+        "| IN_PROGRESS → BLOCKED | Blocker description, escalation path |",
+        "| BLOCKED → IN_PROGRESS | Unblock confirmation, new plan |",
+        "",
+        "---",
+        "",
+        "### RULE-3: Markdown Governance Only",
+        "",
+        "**Rule**: Only edit files in `.projitive/` directory (tasks.md, roadmap.md, designs/, reports/).",
+        "",
+        "**Rationale**: Governance state must be isolated from implementation. Mixing concerns corrupts both.",
+        "",
+        "**Valid Actions**:",
+        "- Edit `.projitive/tasks.md`",
+        "- Create `.projitive/reports/*.md`",
+        "- Update `.projitive/roadmap.md`",
+        "- Modify `.projitive/designs/*.md`",
+        "",
+        "**Invalid Actions**:",
+        "- Edit source code files",
+        "- Modify tests to fit governance",
+        "- Change implementation to match reports",
+        "",
+        "**Governance File Purposes**:",
+        "",
+        "| File | Purpose |",
+        "|------|---------|",
+        "| `.projitive/README.md` | Governance workspace overview |",
+        "| `.projitive/tasks.md` | Task pool and status tracking |",
+        "| `.projitive/roadmap.md` | Roadmap items and milestones |",
+        "| `.projitive/designs/*.md` | Design specifications |",
+        "| `.projitive/reports/*.md` | Execution reports and evidence |",
+        "| `.projitive/hooks/*.md` | Lifecycle hooks and custom prompts |",
+        "",
+        "---",
+        "",
+        "### RULE-4: Status Machine",
+        "",
+        "**Rule**: Only valid status transitions are allowed.",
+        "",
+        "**Valid Transitions**:",
+        "",
+        "```",
+        "TODO ↔ IN_PROGRESS",
+        "IN_PROGRESS → BLOCKED",
+        "BLOCKED → IN_PROGRESS",
+        "IN_PROGRESS → DONE",
+        "```",
+        "",
+        "**Invalid Transitions**:",
+        "",
+        "| Invalid | Reason |",
+        "|---------|--------|",
+        "| TODO → DONE | Missing execution evidence |",
+        "| DONE → any | Terminal state, create new task if needed |",
+        "| BLOCKED → DONE | Must go through IN_PROGRESS |",
+        "| any → TODO | No reset, create new task instead |",
+        "",
+        "---",
+        "",
+        "## Soft Guidelines (Prefer When Possible)",
+        "",
+        "### GUIDELINE-1: Update Timestamps",
+        "",
+        "Update `updatedAt` field whenever modifying a task.",
+        "",
+        "**Format**: ISO 8601 UTC (e.g., `2026-02-21T14:30:00.000Z`)",
+        "",
+        "---",
+        "",
+        "### GUIDELINE-2: Link Reports",
+        "",
+        "Add report paths to task `links` array for traceability.",
+        "",
+        "**Example**:",
+        "```yaml",
+        "links:",
+        "  - ./reports/task-0001-completion-2026-02-21.md",
+        "```",
+        "",
+        "---",
+        "",
+        "### GUIDELINE-3: Roadmap References",
+        "",
+        "Connect tasks to roadmap items via `roadmapRefs`.",
+        "",
+        "**Example**:",
+        "```yaml",
+        "roadmapRefs: ROADMAP-0001",
+        "```",
+        "",
+        "---",
+        "",
+        "### GUIDELINE-4: Custom Hooks",
+        "",
+        "Create hooks in `.projitive/hooks/` for custom behavior.",
+        "",
+        "**Standard Hook Files**:",
+        "",
+        "| File | Purpose |",
+        "|------|---------|",
+        "| `task_no_actionable.md` | Custom prompt when no tasks available |",
+        "",
+        "---",
+        "",
+        "## Verification Checklist",
+        "",
+        "Before committing changes, verify:",
+        "",
+        "- [ ] No ID changes (TASK/ROADMAP IDs unchanged)",
+        "- [ ] Evidence exists for status transitions",
+        "- [ ] Only `.projitive/` files modified",
+        "- [ ] Valid status transition per state machine",
+        "- [ ] `updatedAt` timestamp updated (guideline)",
+        "- [ ] Report linked in task `links` (guideline)",
+        "",
+        "---",
+        "",
+        "## See Also",
+        "",
+        "- `projitive://design/quick-start` - Overview and quick reference",
+        "- `projitive://design/principles` - Core design principles",
+        "- `.projitive/README.md` - Governance workspace overview",
+        "- `../design/README.md` - Design specification",
+        "",
+        "---",
+        "*Part of Projitive Design Context resources. See TASK-0006 for implementation details.*",
+    ].join("\n");
+}