@projitive/mcp 2.0.4 → 2.1.1

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "2.0.4",
+    "version": "2.1.1",
     "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.js

@@ -78,34 +78,69 @@ export function registerQuickStartPrompt(server) {
             '',
             '## Autonomous Operating Loop',
             '',
-            'Keep this loop until no high-value actionable work remains:',
-            '1. Discover: `taskNext()`',
-            '2. Execute: update governance store + docs + report evidence',
-            '3. Verify: `taskContext()`',
-            '4. Re-prioritize: `taskNext()`',
-            '',
-            'Stop and re-discover only when:',
-            '- Current task is BLOCKED with a clear blocker description and unblock condition',
-            '- Acceptance criteria are met and status is DONE',
-            '- Project has no actionable tasks and requires roadmap-driven task creation',
+            'Keep this loop while high-value actionable tasks exist:',
+            '1. Discover: `taskNext()` - Select highest-priority task',
+            '2. Execute: perform work + update governance store (.projitive) + docs',
+            '3. Verify: `taskContext()` - Confirm changes and consistency',
+            '4. Re-prioritize: `taskNext()` - Update priority and select next',
+            '',
+            '**When to Stop or Pause:**',
+            '',
+            '**Stop Reason 1: Task is BLOCKED and needs external action**',
+            '- Blocker must have: type, description, blockingEntity (if applicable), unblockCondition (if applicable)',
+            '- Cannot continue work until blocker is actually resolved (not just "in progress")',
+            '- Examples:',
+            '  - internal_dependency: dependent TASK must be DONE first',
+            '  - external_dependency: external party must deliver (tracked via escalationPath)',
+            '  - resource: tool/access/budget must be allocated (tracked via escalationPath)',
+            '  - approval: decision-maker must sign off (tracked via blockingEntity)',
+            '- **What to do next:** Follow BLOCKED guidance to unblock, then re-run `taskNext()`',
+            '',
+            '**Stop Reason 2: Task is DONE and all acceptance criteria are met**',
+            '- Verify in `taskContext()` that all links/references are consistent',
+            '- Check that report/design/roadmap evidence is properly documented',
+            '- **What to do next:** Run `taskNext()` to pick the next task',
+            '',
+            '**Stop Reason 3: No actionable tasks (all TODO blocked or no tasks exist)**',
+            '- Means: all unblocked work is complete, only blocked tasks remain OR no tasks at all',
+            '- **What to do next:** Analyze blockers and roadmap, create 1-3 new TODO tasks via `taskCreate()`',
             '',
             '## Special Cases',
             '',
             '### Case 1: No .projitive directory',
             'Call `projectInit(projectPath="<project-dir>")` to initialize governance structure.',
             '',
-            '### Case 2: No actionable tasks',
-            '1. Check if .projitive database is missing',
-            '2. If roadmap has active goals, split milestones into 1-3 executable TODO tasks',
-            '3. Apply task creation gate before adding each task:',
-            '   - Clear outcome: one-sentence done condition',
-            '   - Verifiable evidence: at least one report/designs/readme link target',
-            '   - Small slice: should be completable in one focused execution cycle',
-            '   - Traceability: include at least one roadmapRefs item when applicable',
-            '   - Distinct scope: avoid overlap with existing DONE/BLOCKED tasks',
-            '4. Prefer unblocking tasks that unlock multiple follow-up tasks',
-            '5. Re-run `taskNext()` to pick the new tasks',
-            '6. If still no tasks, read design documents in projitive://designs/ and create TODO tasks via `taskCreate()`',
+            '### Case 2: No actionable tasks (all TODO/IN_PROGRESS are blocked OR task count is zero)',
+            '',
+            '**If some tasks exist but all are BLOCKED:**',
+            '1. Run `taskList()` and filter by status = BLOCKED',
+            '2. For each BLOCKED task, check its blocker type:',
+            '   - **internal_dependency**: Is the blocking task listed? If no, create it',
+            '   - **external_dependency**: Is escalationPath defined? If no, add it',
+            '   - **resource**: Is escalationPath defined for requestor? If no, add it',
+            '   - **approval**: Is blockingEntity defined? If no, add it',
+            '3. For each blocker with missing metadata: call `taskUpdate()` to complete it',
+            '4. Select 1 BLOCKED task: follow its unblock guidance to take concrete action',
+            '5. Once blocker is resolved: call `taskUpdate(..., {status: "TODO"})` to unblock',
+            '6. Re-run `taskNext()` to see newly unblocked tasks',
+            '',
+            '**If no tasks exist at all (or only DONE tasks):**',
+            '1. Review `projectContext()` to confirm task count is 0',
+            '2. Read active roadmap milestones via `roadmapContext()`',
+            '3. For each active milestone, derive 1-3 executable TODO tasks:',
+            '   - **Clear outcome**: one-sentence done condition',
+            '   - **Evidence target**: at least one artifact (report, design, readme update)',
+            '   - **Small slice**: completable in one focused execution cycle',
+            '   - **Roadmap link**: link to roadmap via roadmapRefs',
+            '   - **Minimal dependencies**: avoid complex task chains at start',
+            '4. Call `taskCreate()` for each task with complete metadata',
+            '5. Re-run `taskNext()` to start executing the new tasks',
+            '',
+            '**If roadmap is also empty:**',
+            '1. Read design documents under `projitive://designs/`',
+            '2. Identify next architectural milestone or feature slice',
+            '3. Document in ROADMAP.md via `roadmapCreate()`',
+            '4. Create corresponding TODO tasks via `taskCreate()`',
             '',
             '## Hard Rules',
             '',
@@ -114,6 +149,7 @@ export function registerQuickStartPrompt(server) {
             '- **.projitive governance store is source of truth** - tasks.md/roadmap.md are generated views and may be overwritten',
             '- **Prefer tool writes over manual table/view edits** - Use taskCreate/taskUpdate/roadmapCreate/roadmapUpdate',
             '- **Always verify after updates** - Re-run taskContext() to confirm reference consistency',
+            '- **BLOCKED tasks require full blocker metadata** - type, description required; blockingEntity, unblockCondition, escalationPath as needed',
         ].join('\n');
         return asUserPrompt(text);
     });

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.js

@@ -73,21 +73,30 @@ export function registerTaskDiscoveryPrompt(server) {
             '   - Tasks with roadmapRefs first',
             '   - Tasks with explicit owner first',
             '',
-            '3. **BLOCKED** - Last consider blocked tasks',
-            '   - Need to analyze blocker reason first',
-            '   - May need to create sub-task to resolve blocker',
+            '3. **BLOCKED** - Last: unblock first before starting new work',
+            '   - Each BLOCKED task has blocker metadata with clear action steps',
+            '   - Check blocker type (internal_dependency, external_dependency, resource, approval)',
+            '   - Read taskContext to see blocker details and required action path',
+            '   - Follow the action path to unblock (may involve creating unblock task or reaching out)',
+            '   - Only move to TODO after unblock condition is actually met + documented',
             '',
             '### Discovery Methods',
             '',
             '#### Method A: Auto-select with taskNext() (Recommended)',
             '',
             'Call `taskNext()`, the tool will automatically:',
-            '- Sort all tasks by priority',
+            '- Sort all tasks by priority (IN_PROGRESS > TODO, filter out pure BLOCKED)',
             '- Select highest-priority actionable task',
             '- Return task ID and summary',
             '',
             'Then call `taskContext(projectPath="...", taskId="<task-id>")` for task details.',
             '',
+            '**If taskNext returns a BLOCKED task:**',
+            '- This means all TODO/IN_PROGRESS options have been exhausted',
+            '- You MUST resolve the blocker before starting other work',
+            '- Read blocker metadata and follow action path',
+            '- Once blocker is resolved, re-run taskNext() to get next actionable task',
+            '',
             '### Discovery Quality Gate (before creating new tasks)',
             'Only create a TODO when all conditions are true:',
             '- It can be finished in one focused execution cycle',