@projitive/mcp 2.0.4 → 2.1.0

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "2.0.4",
+    "version": "2.1.0",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",

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

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { ConfidenceScoreError, FileNotFoundError, FileReadError, FileWriteError, GovernanceRootNotFoundError, InvalidTaskIdError, MCPError, ProjectError, ProjectNotFoundError, PromptNotFoundError, ProjitiveError, ResourceNotFoundError, TaskError, TaskNotFoundError, TaskValidationError, ValidationError, } from './errors.js';
+describe('errors module', () => {
+    it('constructs base and project/task hierarchy errors with metadata', () => {
+        const base = new ProjitiveError('base failure', 'BASE', { a: 1 });
+        const project = new ProjectError('project failure', 'PROJECT', { projectPath: '/tmp/project' });
+        const task = new TaskError('task failure', 'TASK', { taskId: 'TASK-0001' });
+        expect(base.name).toBe('ProjitiveError');
+        expect(base.code).toBe('BASE');
+        expect(base.details).toEqual({ a: 1 });
+        expect(project.name).toBe('ProjectError');
+        expect(project.code).toBe('PROJECT');
+        expect(task.name).toBe('TaskError');
+        expect(task.code).toBe('TASK');
+    });
+    it('constructs specific project and task lookup errors', () => {
+        const projectNotFound = new ProjectNotFoundError('/tmp/missing');
+        const governanceNotFound = new GovernanceRootNotFoundError('/tmp/project');
+        const taskNotFound = new TaskNotFoundError('TASK-0001');
+        const invalidTaskId = new InvalidTaskIdError('BAD');
+        const taskValidation = new TaskValidationError('TASK-0001', ['owner required', 'links required']);
+        expect(projectNotFound.code).toBe('PROJECT_NOT_FOUND');
+        expect(projectNotFound.message).toContain('/tmp/missing');
+        expect(governanceNotFound.code).toBe('GOVERNANCE_ROOT_NOT_FOUND');
+        expect(taskNotFound.code).toBe('TASK_NOT_FOUND');
+        expect(invalidTaskId.code).toBe('INVALID_TASK_ID');
+        expect(taskValidation.code).toBe('TASK_VALIDATION_FAILED');
+        expect(taskValidation.errors).toEqual(['owner required', 'links required']);
+        expect(taskValidation.message).toContain('owner required, links required');
+    });
+    it('constructs file and validation related errors', () => {
+        const cause = new Error('disk offline');
+        const notFound = new FileNotFoundError('/tmp/a.md');
+        const readError = new FileReadError('/tmp/b.md', cause);
+        const writeError = new FileWriteError('/tmp/c.md', cause);
+        const validation = new ValidationError('invalid input', ['field missing']);
+        const confidence = new ConfidenceScoreError('bad confidence', 1.5, ['must be <= 1']);
+        expect(notFound.name).toBe('FileError');
+        expect(notFound.code).toBe('FILE_NOT_FOUND');
+        expect(readError.details).toMatchObject({ filePath: '/tmp/b.md', cause: 'disk offline' });
+        expect(writeError.details).toMatchObject({ filePath: '/tmp/c.md', cause: 'disk offline' });
+        expect(validation.name).toBe('ValidationError');
+        expect(validation.code).toBe('VALIDATION_FAILED');
+        expect(validation.errors).toEqual(['field missing']);
+        expect(confidence.code).toBe('CONFIDENCE_SCORE_ERROR');
+        expect(confidence.score).toBe(1.5);
+    });
+    it('constructs MCP related not-found errors', () => {
+        const mcp = new MCPError('mcp failed', 'MCP_GENERIC', { retry: true });
+        const resource = new ResourceNotFoundError('projitive://missing');
+        const prompt = new PromptNotFoundError('taskExecution');
+        expect(mcp.name).toBe('MCPError');
+        expect(mcp.details).toEqual({ retry: true });
+        expect(resource.code).toBe('RESOURCE_NOT_FOUND');
+        expect(resource.message).toContain('projitive://missing');
+        expect(prompt.code).toBe('PROMPT_NOT_FOUND');
+        expect(prompt.message).toContain('taskExecution');
+    });
+});

package/output/source/common/files.js

@@ -11,16 +11,27 @@ async function fileLineCount(filePath) {
     return content.split(/\r?\n/).length;
 }
 async function listMarkdownFiles(dirPath) {
-    const entriesResult = await catchIt(fs.readdir(dirPath, { withFileTypes: true }));
-    if (entriesResult.isError()) {
-        return [];
-    }
-    const entries = entriesResult.value;
-    const files = entries.filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'));
     const result = [];
-    for (const file of files) {
-        const fullPath = path.join(dirPath, file.name);
-        result.push({ path: fullPath, lineCount: await fileLineCount(fullPath) });
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const currentDir = stack.pop();
+        if (!currentDir) {
+            continue;
+        }
+        const entriesResult = await catchIt(fs.readdir(currentDir, { withFileTypes: true }));
+        if (entriesResult.isError()) {
+            continue;
+        }
+        for (const entry of entriesResult.value) {
+            const entryPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(entryPath);
+                continue;
+            }
+            if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+                result.push({ path: entryPath, lineCount: await fileLineCount(entryPath) });
+            }
+        }
     }
     return result.sort((a, b) => a.path.localeCompare(b.path));
 }

package/output/source/common/index.js

@@ -8,3 +8,4 @@ export * from './catch.js';
 export * from './artifacts.js';
 export * from './linter.js';
 export * from './store.js';
+export * from './tool.js';

package/output/source/common/linter.js

@@ -12,7 +12,6 @@ export const TASK_LINT_CODES = {
     UPDATED_AT_INVALID: 'TASK_UPDATED_AT_INVALID',
     ROADMAP_REFS_EMPTY: 'TASK_ROADMAP_REFS_EMPTY',
     OUTSIDE_MARKER: 'TASK_OUTSIDE_MARKER',
-    LINK_TARGET_MISSING: 'TASK_LINK_TARGET_MISSING',
     LINK_PATH_FORMAT_INVALID: 'TASK_LINK_PATH_FORMAT_INVALID',
     HOOK_FILE_MISSING: 'TASK_HOOK_FILE_MISSING',
     FILTER_EMPTY: 'TASK_FILTER_EMPTY',
@@ -25,6 +24,7 @@ export const TASK_LINT_CODES = {
     IN_PROGRESS_WITHOUT_SUBSTATE: 'TASK_IN_PROGRESS_WITHOUT_SUBSTATE',
     SUBSTATE_PHASE_INVALID: 'TASK_SUBSTATE_PHASE_INVALID',
     SUBSTATE_CONFIDENCE_INVALID: 'TASK_SUBSTATE_CONFIDENCE_INVALID',
+    RESEARCH_BRIEF_MISSING: 'TASK_RESEARCH_BRIEF_MISSING',
 };
 export const ROADMAP_LINT_CODES = {
     IDS_EMPTY: 'ROADMAP_IDS_EMPTY',
@@ -36,4 +36,6 @@ export const ROADMAP_LINT_CODES = {
 };
 export const PROJECT_LINT_CODES = {
     TASKS_FILE_MISSING: 'PROJECT_TASKS_FILE_MISSING',
+    ARCHITECTURE_DOC_MISSING: 'PROJECT_ARCHITECTURE_DOC_MISSING',
+    STYLE_DOC_MISSING: 'PROJECT_STYLE_DOC_MISSING',
 };

package/output/source/common/response.js

@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
 const MESSAGE_TEMPLATE_ENV = 'PROJITIVE_MESSAGE_TEMPLATE_PATH';
-const CONTENT_TEMPLATE_TOKEN = '{{content}}';
 function baseToolTemplateMarkdown() {
     return [
         '# {{tool_name}}',
@@ -15,58 +14,53 @@ function baseToolTemplateMarkdown() {
         '## Agent Guidance',
         '{{guidance}}',
         '',
+        '## Lint Suggestions',
+        '{{suggestions}}',
+        '',
         '## Next Call',
         '{{next_call}}',
-        '',
-        '## Raw Response',
-        '{{content}}',
     ].join('\n');
 }
-function contextGuideTemplateExtra() {
-    return [
-        '',
-        '## Common Tool Guides To Read First',
-        '- ./CLAUDE.md',
-        '- ./AGENTS.md',
-        '- ./.github/copilot-instructions.md',
-        '- ./.cursorrules',
-        '- ./.github/instructions/*',
-        '- ./.cursor/rules/*',
-    ];
-}
-function idleDiscoveryTemplateExtra() {
-    return [
-        '',
-        '## Idle Discovery Checklist (When No Actionable Task)',
-        '- Scan backlog comments: TODO / FIXME / HACK / XXX.',
-        '- Check lint gaps and create executable fix tasks.',
-        '- Check test quality gaps (missing tests, flaky tests, low-value coverage).',
-        '- Learn current project architecture and consolidate/update design docs in designs/.',
-        '- Re-run {{tool_name}} after creating 1-3 focused TODO tasks.',
-    ];
-}
-function commitReminderTemplateExtra() {
-    return [
-        '',
-        '## Commit Reminder',
-        '- After this update, create a commit to keep progress auditable.',
-        '- Recommended format: type(scope): summary',
-        '- Example: feat(task): complete TASK-0007 validation flow',
-        '- Footer suggestion: Refs: TASK-0007, ROADMAP-0002',
-    ];
-}
 export function getDefaultToolTemplateMarkdown(toolName) {
-    const base = baseToolTemplateMarkdown().split('\n');
+    const base = baseToolTemplateMarkdown();
     if (toolName === 'taskNext') {
-        return [...base, ...idleDiscoveryTemplateExtra()].join('\n');
+        return [
+            base,
+            '',
+            '## Idle Discovery Checklist (When No Actionable Task)',
+            '- Scan backlog comments: TODO / FIXME / HACK / XXX.',
+            '- Check lint gaps and create executable fix tasks.',
+            '- Check test quality gaps (missing tests, flaky tests, low-value coverage).',
+            '- Learn current project architecture and consolidate/update design docs in designs/.',
+            '- Review and update architecture docs under designs/core/ (architecture.md, style-guide.md) if missing or outdated.',
+            '- Re-run {{tool_name}} after creating 1-3 focused TODO tasks.',
+        ].join('\n');
     }
     if (toolName === 'projectContext' || toolName === 'taskContext' || toolName === 'roadmapContext') {
-        return [...base, ...contextGuideTemplateExtra()].join('\n');
+        return [
+            base,
+            '',
+            '## Common Tool Guides To Read First',
+            '- ./CLAUDE.md',
+            '- ./AGENTS.md',
+            '- ./.github/copilot-instructions.md',
+            '- ./.cursorrules',
+            '- ./.github/instructions/*',
+            '- ./.cursor/rules/*',
+        ].join('\n');
     }
     if (toolName === 'taskUpdate' || toolName === 'roadmapUpdate') {
-        return [...base, ...commitReminderTemplateExtra()].join('\n');
-    }
-    return base.join('\n');
+        return [
+            base,
+            '',
+            '## Commit Reminder',
+            '- After this update, create a commit to keep progress auditable.',
+            '- Recommended format: type(scope): summary',
+            '- Example: feat(task): complete TASK-0007 validation flow',
+            '- Footer suggestion: Refs: TASK-0007, ROADMAP-0002',
+        ].join('\n');
+    }
+    return base;
 }
 function loadTemplateFile(templatePath) {
     try {
@@ -172,13 +166,13 @@ function toSectionText(section) {
 function resolveSection(payload, title) {
     return payload.sections.find((item) => item.title === title);
 }
-function buildToolTemplateVariables(payload, classicMarkdown) {
+function buildToolTemplateVariables(payload) {
     return {
         tool_name: payload.toolName,
-        content: classicMarkdown,
         summary: toSectionText(resolveSection(payload, 'Summary')),
         evidence: toSectionText(resolveSection(payload, 'Evidence')),
         guidance: toSectionText(resolveSection(payload, 'Agent Guidance')),
+        suggestions: toSectionText(resolveSection(payload, 'Lint Suggestions')),
         next_call: toSectionText(resolveSection(payload, 'Next Call')),
     };
 }
@@ -187,33 +181,23 @@ function applyTemplateVariables(template, variables) {
     for (const [key, value] of Object.entries(variables)) {
         rendered = rendered.split(`{{${key}}}`).join(value);
     }
-    if (!rendered.includes(variables.content) && !template.includes(CONTENT_TEMPLATE_TOKEN)) {
-        rendered = `${rendered}\n\n${variables.content}`;
-    }
     return rendered.trimEnd();
 }
 export function renderToolResponseMarkdown(payload) {
-    const body = payload.sections.flatMap((section) => [
-        `## ${section.title}`,
-        ...withFallback(section.lines),
-        '',
-    ]);
-    const classicMarkdown = [
-        `# ${payload.toolName}`,
-        '',
-        ...body,
-    ].join('\n').trimEnd();
     const template = loadMessageTemplate(payload.toolName);
-    const variables = buildToolTemplateVariables(payload, classicMarkdown);
+    const variables = buildToolTemplateVariables(payload);
     return applyTemplateVariables(template, variables);
 }
 export function renderErrorMarkdown(toolName, cause, nextSteps, retryExample) {
-    return renderToolResponseMarkdown({
-        toolName,
-        sections: [
-            section('Error', [`cause: ${cause}`]),
-            section('Next Step', nextSteps),
-            section('Retry Example', [retryExample ?? '(none)']),
-        ],
-    });
+    const sections = [
+        section('Error', [`cause: ${cause}`]),
+        section('Next Step', nextSteps),
+        section('Retry Example', [retryExample ?? '(none)']),
+    ];
+    const body = sections.flatMap((sec) => [
+        `## ${sec.title}`,
+        ...withFallback(sec.lines),
+        '',
+    ]);
+    return [`# ${toolName}`, '', ...body].join('\n').trimEnd();
 }

package/output/source/common/tool.js

@@ -0,0 +1,43 @@
+import { asText, renderToolResponseMarkdown, renderErrorMarkdown, evidenceSection, guidanceSection, lintSection, nextCallSection, summarySection, } from './response.js';
+export class ToolExecutionError extends Error {
+    nextSteps;
+    retryExample;
+    constructor(message, nextSteps = [], retryExample) {
+        super(message);
+        this.nextSteps = nextSteps;
+        this.retryExample = retryExample;
+        this.name = 'ToolExecutionError';
+    }
+}
+export function createGovernedTool(spec) {
+    const cb = async (input) => {
+        try {
+            const ctx = { now: new Date().toISOString() };
+            const data = await spec.execute(input, ctx);
+            const markdown = renderToolResponseMarkdown({
+                toolName: spec.name,
+                sections: [
+                    summarySection(await spec.summary(data, ctx)),
+                    evidenceSection(await (spec.evidence?.(data, ctx) ?? [])),
+                    guidanceSection(await spec.guidance(data, ctx)),
+                    lintSection(await (spec.suggestions?.(data, ctx) ?? [])),
+                    nextCallSection(await spec.nextCall(data, ctx)),
+                ],
+            });
+            return asText(markdown);
+        }
+        catch (error) {
+            if (error instanceof ToolExecutionError) {
+                return {
+                    ...asText(renderErrorMarkdown(spec.name, error.message, error.nextSteps, error.retryExample)),
+                    isError: true,
+                };
+            }
+            return {
+                ...asText(renderErrorMarkdown(spec.name, String(error), [])),
+                isError: true,
+            };
+        }
+    };
+    return [spec.name, { title: spec.title, description: spec.description, inputSchema: spec.inputSchema }, cb];
+}

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

@@ -0,0 +1,48 @@
+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 { capitalizeFirstLetter, formatTitle, readMarkdownOrFallback } from './utils.js';
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-utils-test-'));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    vi.restoreAllMocks();
+    await Promise.all(tempPaths.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+describe('utils module', () => {
+    it('reads markdown content when file exists and is non-empty', async () => {
+        const root = await createTempDir();
+        const filePath = path.join(root, 'README.md');
+        await fs.writeFile(filePath, '# Hello\n', 'utf-8');
+        const content = await readMarkdownOrFallback('README.md', 'Fallback', root);
+        expect(content).toBe('# Hello\n');
+    });
+    it('returns fallback markdown for missing or empty files', async () => {
+        const root = await createTempDir();
+        await fs.writeFile(path.join(root, 'empty.md'), '   ', 'utf-8');
+        const missing = await readMarkdownOrFallback('missing.md', 'Missing Title', root);
+        const empty = await readMarkdownOrFallback('empty.md', 'Empty Title', root);
+        expect(missing).toContain('# Missing Title');
+        expect(missing).toContain('- status: missing-or-empty');
+        expect(empty).toContain('# Empty Title');
+        expect(empty).toContain('- file: empty.md');
+    });
+    it('logs non-ENOENT read errors before falling back', async () => {
+        const root = await createTempDir();
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        vi.spyOn(fs, 'readFile').mockRejectedValueOnce({ code: 'EACCES' });
+        const result = await readMarkdownOrFallback('secret.md', 'Secret', root);
+        expect(result).toContain('# Secret');
+        expect(errorSpy).toHaveBeenCalledOnce();
+    });
+    it('formats title helpers consistently', () => {
+        expect(capitalizeFirstLetter('task_execution')).toBe('TaskExecution');
+        expect(capitalizeFirstLetter('roadmap-next')).toBe('RoadmapNext');
+        expect(formatTitle('task_execution')).toBe('Task Execution');
+        expect(formatTitle('roadmap-next')).toBe('Roadmap Next');
+    });
+});

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

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+const hoisted = vi.hoisted(() => {
+    const connectMock = vi.fn().mockResolvedValue(undefined);
+    const serverInstance = { connect: connectMock };
+    return {
+        connectMock,
+        serverInstance,
+        registerToolsMock: vi.fn(),
+        registerPromptsMock: vi.fn(),
+        registerResourcesMock: vi.fn(),
+        mcpServerMock: vi.fn().mockImplementation(() => serverInstance),
+        stdioTransportMock: vi.fn().mockImplementation(() => ({ kind: 'stdio' })),
+    };
+});
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js', () => ({
+    McpServer: hoisted.mcpServerMock,
+}));
+vi.mock('@modelcontextprotocol/sdk/server/stdio.js', () => ({
+    StdioServerTransport: hoisted.stdioTransportMock,
+}));
+vi.mock('./tools/index.js', () => ({
+    registerTools: hoisted.registerToolsMock,
+}));
+vi.mock('./prompts/index.js', () => ({
+    registerPrompts: hoisted.registerPromptsMock,
+}));
+vi.mock('./resources/index.js', () => ({
+    registerResources: hoisted.registerResourcesMock,
+}));
+describe('index runtime module', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.resetModules();
+        hoisted.connectMock.mockClear();
+        hoisted.registerToolsMock.mockClear();
+        hoisted.registerPromptsMock.mockClear();
+        hoisted.registerResourcesMock.mockClear();
+        hoisted.mcpServerMock.mockClear();
+        hoisted.stdioTransportMock.mockClear();
+    });
+    it('boots the MCP server, registers modules, and connects stdio transport', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        await import('./index.js');
+        await Promise.resolve();
+        expect(hoisted.mcpServerMock).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'projitive',
+            description: expect.stringContaining('governance-store-first outputs'),
+        }));
+        expect(hoisted.registerToolsMock).toHaveBeenCalledWith(hoisted.serverInstance);
+        expect(hoisted.registerPromptsMock).toHaveBeenCalledWith(hoisted.serverInstance);
+        expect(hoisted.registerResourcesMock).toHaveBeenCalledWith(hoisted.serverInstance, expect.any(String));
+        expect(hoisted.stdioTransportMock).toHaveBeenCalledOnce();
+        expect(hoisted.connectMock).toHaveBeenCalledOnce();
+        expect(errorSpy).toHaveBeenCalledWith('[projitive-mcp] starting server');
+        expect(errorSpy.mock.calls.some((call) => String(call[0]).includes('transport=stdio'))).toBe(true);
+    });
+});

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

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('./quickStart.js', () => ({
+    registerQuickStartPrompt: vi.fn(),
+}));
+vi.mock('./taskDiscovery.js', () => ({
+    registerTaskDiscoveryPrompt: vi.fn(),
+}));
+vi.mock('./taskExecution.js', () => ({
+    registerTaskExecutionPrompt: vi.fn(),
+}));
+import { registerQuickStartPrompt } from './quickStart.js';
+import { registerTaskDiscoveryPrompt } from './taskDiscovery.js';
+import { registerTaskExecutionPrompt } from './taskExecution.js';
+import { registerPrompts } from './index.js';
+describe('prompts index module', () => {
+    it('registers all prompt categories', () => {
+        const server = {};
+        registerPrompts(server);
+        expect(registerQuickStartPrompt).toHaveBeenCalledWith(server);
+        expect(registerTaskDiscoveryPrompt).toHaveBeenCalledWith(server);
+        expect(registerTaskExecutionPrompt).toHaveBeenCalledWith(server);
+    });
+});

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

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+import { registerQuickStartPrompt } from './quickStart.js';
+describe('quickStart prompt', () => {
+    it('registers the prompt and renders known project guidance', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerQuickStartPrompt(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('quickStart');
+        expect(text).toContain('Known project path: "/workspace/app"');
+        expect(text).toContain('taskCreate');
+        expect(text).toContain('.projitive governance store is source of truth');
+    });
+    it('renders discovery workflow when project path is unknown', async () => {
+        const server = { registerPrompt: vi.fn() };
+        registerQuickStartPrompt(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 `projectLocate(inputPath="<selected-path>")` to lock governance root');
+    });
+});

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',
@@ -65,6 +75,8 @@ export function registerTaskExecutionPrompt(server) {
             '### 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)',
@@ -152,7 +164,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 +178,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.',
+                }],
+        });
+    });
+});