@projitive/mcp 2.0.4 → 2.1.1

package/output/source/prompts/taskDiscovery.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+import { registerTaskDiscoveryPrompt } from './taskDiscovery.js';
+describe('taskDiscovery prompt', () => {
+    it('registers the prompt and renders project-specific discovery guidance', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerTaskDiscoveryPrompt(server);
+        const handler = server.registerPrompt.mock.calls[0][2];
+        const result = await handler({ projectPath: '/workspace/app' });
+        const text = result.messages[0].content.text;
+        expect(server.registerPrompt.mock.calls[0][0]).toBe('taskDiscovery');
+        expect(text).toContain('Known project path: "/workspace/app"');
+        expect(text).toContain('Method A: Auto-select with taskNext()');
+        expect(text).toContain('roadmapCreate');
+    });
+    it('renders unknown-project discovery steps', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerTaskDiscoveryPrompt(server);
+        const handler = server.registerPrompt.mock.calls[0][2];
+        const result = await handler({});
+        const text = result.messages[0].content.text;
+        expect(text).toContain('Call `projectScan()` to discover all governance roots');
+        expect(text).toContain('Call `projectContext(projectPath="<project-path>")` to load project context');
+    });
+});

package/output/source/prompts/taskExecution.js

@@ -43,6 +43,16 @@ export function registerTaskExecutionPrompt(server) {
             '- Understand task background and motivation',
             '- Identify task acceptance criteria',
             '- Look for related design decisions',
+            '- Check Pre-Execution Research Brief status in taskContext output',
+            '- If status is MISSING/INCOMPLETE, complete it before any implementation',
+            '',
+            '### Pre-Execution Research Brief (Mandatory Gate)',
+            '- Fixed file name: `designs/research/<TASK-ID>.implementation-research.md`',
+            '- Required sections:',
+            '  - `## Design Guidelines and Specs`',
+            '  - `## Code Architecture and Implementation Findings`',
+            '- Must include line locations (for example `path/to/file.ts#L42`)',
+            '- You MUST read this file before progressing implementation',
             '',
             '### Evidence',
             '- Candidate Files - Related file list',
@@ -59,12 +69,15 @@ export function registerTaskExecutionPrompt(server) {
             '|----------------|-----------|-------------|',
             '| TODO | \u2192 IN_PROGRESS | When starting execution |',
             '| IN_PROGRESS | \u2192 DONE | When task is complete |',
-            '| IN_PROGRESS | \u2192 BLOCKED | When blocked |',
-            '| BLOCKED | \u2192 TODO | When blocker is resolved |',
+            '| IN_PROGRESS | \u2192 BLOCKED | When production is halted by external factor |',
+            '| BLOCKED | \u2192 TODO | When blocker condition is resolved + evidence is documented |',
+            '| BLOCKED | \u2192 UNBLOCK TASK (new) | Optional: create a new TODO task if blocker requires work (e.g., someone else must do something) |',
             '',
             '### Execution Steps',
             '',
             '1. **Prepare (if status is TODO)',
+            '   - Ensure Pre-Execution Research Brief status is READY in `taskContext()`',
+            '   - If not READY, complete research brief first and re-run `taskContext()`',
             '   - Call `taskUpdate()` to change status to IN_PROGRESS',
             '   - Set owner (if empty)',
             '   - Fill subState (optional, Spec v1.1.0)',
@@ -117,17 +130,59 @@ export function registerTaskExecutionPrompt(server) {
             '',
             '## Special Cases',
             '',
-            '### Case 1: Encountered a blocker',
+            '### Case 1: Encountered a blocker during IN_PROGRESS',
             '',
-            'If unable to continue task execution:',
-            '1. Call `taskUpdate()` to change status to BLOCKED',
-            '2. Fill blocker field (Spec v1.1.0):',
-            '   - type: Blocker type (dependency/missing-info/technical-debt/other)',
-            '   - description: Blocker description',
-            '   - relatedLinks: Related links (optional)',
-            '3. Create a new TODO task via `taskCreate()` to resolve blocker',
+            'If unable to continue task execution due to external/blocking factors:',
             '',
-            '### Case 2: No actionable tasks',
+            '**Always do these steps:**',
+            '1. Call `taskUpdate()` to change status to BLOCKED',
+            '2. Fill blocker metadata (REQUIRED - Spec v1.1.0):',
+            '   - **type**: One of: `internal_dependency`, `external_dependency`, `resource`, `approval`',
+            '   - **description**: Clear description of what is blocking and why',
+            '   - **blockingEntity** (optional): Who/what is causing block (person, team, external service)',
+            '   - **unblockCondition** (optional): Specific condition needed to unblock (e.g., "TASK-42 must be completed")',
+            '   - **escalationPath** (optional): Path to escalate if blocker persists',
+            '',
+            '**Then choose ONE of these paths based on blocker type:**',
+            '',
+            '#### If `internal_dependency` (another task must complete first)',
+            '- Check if the blocking task exists and has owner assigned.',
+            '- If exists: coordinate with owner and recheck after their task completes.',
+            '- If missing: create new TASK via taskCreate() with explicit unblock condition.',
+            '',
+            '#### If `external_dependency` (external party/service/approval needed)',
+            '- Document blockingEntity clearly.',
+            '- If unclear how to reach them, add escalationPath.',
+            '- Wait for external delivery or take action per escalationPath.',
+            '',
+            '#### If `resource` (missing tool, access, budget, personnel)',
+            '- Document what resource is needed (in description).',
+            '- If owner unknown, set escalationPath.',
+            '- Take action to request/allocate resource.',
+            '',
+            '#### If `approval` (needs approver sign-off)',
+            '- Document who must approve (blockingEntity).',
+            '- Prepare approval request with clear criteria.',
+            '- Track approval status and escalate if delayed.',
+            '',
+            '**What NOT to do:**',
+            '- Do NOT leave BLOCKED task without blocker metadata.',
+            '- Do NOT mark BLOCKED if it\'s actually just "waiting for me to finish" (keep IN_PROGRESS).',
+            '- Do NOT flip BLOCKED → TODO unless actual unblock condition is met + documented.',
+            '',
+            '### Case 2: Found a BLOCKED task in taskNext()',
+            '',
+            'If taskNext() returns a BLOCKED task instead of TODO/IN_PROGRESS:',
+            '1. Read blocker metadata carefully (shown in taskContext output).',
+            '2. Follow blocker-specific action path in taskStatusGuidance output.',
+            '3. Take concrete steps to unblock:',
+            '   - Create/track dependency task',
+            '   - Reach out to blocking entity',
+            '   - Request missing resource',
+            '   - Follow escalation path if applicable',
+            '4. Once unblock condition is met: call `taskUpdate(taskId, {status: \'TODO\'})` and re-run taskNext().',
+            '',
+            '### Case 3: No actionable tasks (all TODO are blocked)',
             '',
             'If taskNext() returns empty:',
             '1. Call `projectContext()` to recheck project state',
@@ -152,7 +207,7 @@ export function registerTaskExecutionPrompt(server) {
             '2. **Every status transition must have report evidence**',
             '   - TODO \u2192 IN_PROGRESS: Report not required',
             '   - IN_PROGRESS \u2192 DONE: Report REQUIRED',
-            '   - IN_PROGRESS \u2192 BLOCKED: Report recommended to explain blocker',
+            '   - IN_PROGRESS \u2192 BLOCKED: Include report to explain blocker',
             '',
             '3. **Governance-store-first writes only**',
             '   - tasks.md/roadmap.md are generated views, not authoritative source',
@@ -166,6 +221,10 @@ export function registerTaskExecutionPrompt(server) {
             '5. **Keep updatedAt in sync**',
             '   - Every time you update a task',
             '   - Must update updatedAt to current time (ISO 8601 format)',
+            '',
+            '6. **Pre-execution research brief is mandatory**',
+            '   - `TODO -> IN_PROGRESS` is not allowed until research brief is READY',
+            '   - Always read `designs/research/<TASK-ID>.implementation-research.md` before implementation',
         ].join('\n');
         return asUserPrompt(text);
     });

package/output/source/prompts/taskExecution.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import { registerTaskExecutionPrompt } from './taskExecution.js';
+describe('taskExecution prompt', () => {
+    it('registers the prompt and renders direct taskContext entry when task is known', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerTaskExecutionPrompt(server);
+        const handler = server.registerPrompt.mock.calls[0][2];
+        const result = await handler({ projectPath: '/workspace/app', taskId: 'TASK-0007' });
+        const text = result.messages[0].content.text;
+        expect(server.registerPrompt.mock.calls[0][0]).toBe('taskExecution');
+        expect(text).toContain('1) Run taskContext(projectPath="/workspace/app", taskId="TASK-0007").');
+        expect(text).toContain('Every status transition must have report evidence');
+        expect(text).toContain('Pre-Execution Research Brief (Mandatory Gate)');
+        expect(text).toContain('designs/research/<TASK-ID>.implementation-research.md');
+    });
+    it('falls back to taskNext when task is not provided', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerTaskExecutionPrompt(server);
+        const handler = server.registerPrompt.mock.calls[0][2];
+        const result = await handler({});
+        const text = result.messages[0].content.text;
+        expect(text).toContain('1) Run taskNext().');
+        expect(text).toContain('Governance-store-first writes only');
+        expect(text).toContain('TODO -> IN_PROGRESS');
+        expect(text).toContain('research brief is READY');
+    });
+});

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

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerDesignFilesResources } from './designs.js';
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-design-resource-test-'));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+    vi.restoreAllMocks();
+});
+describe('design resources registration', () => {
+    it('registers discovered markdown design resources recursively', async () => {
+        const root = await createTempDir();
+        const designsDir = path.join(root, '.projitive', 'designs', 'mobile');
+        await fs.mkdir(designsDir, { recursive: true });
+        await fs.writeFile(path.join(root, '.projitive', 'designs', 'architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(designsDir, 'screen.md'), '# Screen\n', 'utf-8');
+        const server = { registerResource: vi.fn() };
+        await registerDesignFilesResources(server, root);
+        const calls = server.registerResource.mock.calls;
+        expect(calls).toHaveLength(2);
+        expect(calls.map((call) => call[0])).toEqual(expect.arrayContaining(['design-architecture', 'design-mobile-screen']));
+        const mobileHandler = calls.find((call) => call[0] === 'design-mobile-screen')?.[3];
+        const result = await mobileHandler();
+        expect(result.contents[0]).toEqual({
+            uri: 'projitive://designs/mobile-screen',
+            text: '# Screen\n',
+        });
+    });
+    it('registers default fallback resource when designs directory is missing', async () => {
+        const root = await createTempDir();
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const server = { registerResource: vi.fn() };
+        await registerDesignFilesResources(server, root);
+        const calls = server.registerResource.mock.calls;
+        expect(calls).toHaveLength(1);
+        expect(calls[0][0]).toBe('designs');
+        expect(warnSpy).toHaveBeenCalledOnce();
+        const handler = calls[0][3];
+        await expect(handler()).resolves.toMatchObject({
+            contents: [{
+                    uri: 'projitive://designs',
+                    text: '# Designs Directory\n\nDesign documents not found. Please create design files in .projitive/designs/ directory.',
+                }],
+        });
+    });
+});

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

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerGovernanceResources } from './governance.js';
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-governance-resource-test-'));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+    vi.restoreAllMocks();
+});
+describe('governance resources', () => {
+    it('registers workspace, tasks, and roadmap resources from markdown files', async () => {
+        const root = await createTempDir();
+        const governanceDir = path.join(root, '.projitive');
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, 'README.md'), '# Workspace\n', 'utf-8');
+        await fs.writeFile(path.join(governanceDir, 'tasks.md'), '# Tasks\n', 'utf-8');
+        await fs.writeFile(path.join(governanceDir, 'roadmap.md'), '# Roadmap\n', 'utf-8');
+        const server = { registerResource: vi.fn() };
+        registerGovernanceResources(server, root);
+        const calls = server.registerResource.mock.calls;
+        expect(calls).toHaveLength(3);
+        const workspaceHandler = calls[0][3];
+        const tasksHandler = calls[1][3];
+        const roadmapHandler = calls[2][3];
+        await expect(workspaceHandler()).resolves.toMatchObject({ contents: [{ uri: 'projitive://governance/workspace', text: '# Workspace\n' }] });
+        await expect(tasksHandler()).resolves.toMatchObject({ contents: [{ uri: 'projitive://governance/tasks', text: '# Tasks\n' }] });
+        await expect(roadmapHandler()).resolves.toMatchObject({ contents: [{ uri: 'projitive://governance/roadmap', text: '# Roadmap\n' }] });
+    });
+});

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

@@ -0,0 +1,18 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('./governance.js', () => ({
+    registerGovernanceResources: vi.fn(),
+}));
+vi.mock('./designs.js', () => ({
+    registerDesignFilesResources: vi.fn(),
+}));
+import { registerGovernanceResources } from './governance.js';
+import { registerDesignFilesResources } from './designs.js';
+import { registerResources } from './index.js';
+describe('resources index module', () => {
+    it('registers governance and design resources', () => {
+        const server = {};
+        registerResources(server, '/workspace/repo');
+        expect(registerGovernanceResources).toHaveBeenCalledWith(server, '/workspace/repo');
+        expect(registerDesignFilesResources).toHaveBeenCalledWith(server, '/workspace/repo');
+    });
+});

package/output/source/tools/index.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('./project.js', () => ({
+    registerProjectTools: vi.fn(),
+}));
+vi.mock('./task.js', () => ({
+    registerTaskTools: vi.fn(),
+}));
+vi.mock('./roadmap.js', () => ({
+    registerRoadmapTools: vi.fn(),
+}));
+import { registerProjectTools } from './project.js';
+import { registerTaskTools } from './task.js';
+import { registerRoadmapTools } from './roadmap.js';
+import { registerTools } from './index.js';
+describe('tools index module', () => {
+    it('registers all tool groups', () => {
+        const server = {};
+        registerTools(server);
+        expect(registerProjectTools).toHaveBeenCalledWith(server);
+        expect(registerTaskTools).toHaveBeenCalledWith(server);
+        expect(registerRoadmapTools).toHaveBeenCalledWith(server);
+    });
+});