@projitive/mcp 2.0.3 → 2.1.0

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

@@ -1,169 +1,497 @@
-import { describe, expect, it } from "vitest";
-import { collectTaskLintSuggestions, isValidTaskId, normalizeTask, rankActionableTaskCandidates, resolveNoTaskDiscoveryGuidance, renderTaskSeedTemplate, renderTasksMarkdown, loadTasksDocument, saveTasks, taskPriority, toTaskUpdatedAtMs, validateTransition, } from "./task.js";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
+import { describe, expect, it, vi } from 'vitest';
+import { collectTaskLintSuggestions, isValidTaskId, normalizeTask, rankActionableTaskCandidates, resolveNoTaskDiscoveryGuidance, renderTaskSeedTemplate, renderTasksMarkdown, loadTasksDocument, registerTaskTools, saveTasks, taskPriority, toTaskUpdatedAtMs, validateTransition, } from './task.js';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { replaceRoadmapsInStore } from '../common/store.js';
+async function createGovernanceWorkspace() {
+    const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-mcp-task-workspace-'));
+    const governanceDir = path.join(projectRoot, '.projitive');
+    const dbPath = path.join(governanceDir, '.projitive');
+    await fs.mkdir(governanceDir, { recursive: true });
+    await fs.writeFile(dbPath, '', 'utf-8');
+    return { projectRoot, governanceDir, dbPath };
+}
+function getToolHandler(mockServer, toolName) {
+    const call = mockServer.registerTool.mock.calls.find((entry) => entry[0] === toolName);
+    expect(call).toBeTruthy();
+    return call?.[2];
+}
 function buildCandidate(partial) {
     const task = normalizeTask({
         id: partial.id,
         title: partial.title,
         status: partial.status,
-        updatedAt: partial.task?.updatedAt ?? "2026-01-01T00:00:00.000Z",
+        updatedAt: partial.task?.updatedAt ?? '2026-01-01T00:00:00.000Z',
     });
     return {
-        governanceDir: partial.governanceDir ?? "/workspace/a",
+        governanceDir: partial.governanceDir ?? '/workspace/a',
         task,
         projectScore: partial.projectScore ?? 1,
-        projectLatestUpdatedAt: partial.projectLatestUpdatedAt ?? "2026-01-01T00:00:00.000Z",
+        projectLatestUpdatedAt: partial.projectLatestUpdatedAt ?? '2026-01-01T00:00:00.000Z',
         taskUpdatedAtMs: partial.taskUpdatedAtMs ?? toTaskUpdatedAtMs(task.updatedAt),
         taskPriority: partial.taskPriority ?? taskPriority(task.status),
     };
 }
-describe("tasks module", () => {
-    it("validates task IDs", () => {
-        expect(isValidTaskId("TASK-0001")).toBe(true);
-        expect(isValidTaskId("TASK-001")).toBe(false);
+describe('tasks module', () => {
+    it('validates task IDs', () => {
+        expect(isValidTaskId('TASK-0001')).toBe(true);
+        expect(isValidTaskId('TASK-1')).toBe(true);
+        expect(isValidTaskId('TASK-12345')).toBe(true);
+        expect(isValidTaskId('TASK-ABCD')).toBe(false);
     });
-    it("allows and rejects expected transitions", () => {
-        expect(validateTransition("TODO", "IN_PROGRESS")).toBe(true);
-        expect(validateTransition("IN_PROGRESS", "DONE")).toBe(true);
-        expect(validateTransition("DONE", "IN_PROGRESS")).toBe(false);
+    it('allows and rejects expected transitions', () => {
+        expect(validateTransition('TODO', 'IN_PROGRESS')).toBe(true);
+        expect(validateTransition('IN_PROGRESS', 'DONE')).toBe(true);
+        expect(validateTransition('DONE', 'IN_PROGRESS')).toBe(false);
     });
-    it("assigns priority for actionable statuses", () => {
-        expect(taskPriority("IN_PROGRESS")).toBe(2);
-        expect(taskPriority("TODO")).toBe(1);
-        expect(taskPriority("BLOCKED")).toBe(0);
+    it('assigns priority for actionable statuses', () => {
+        expect(taskPriority('IN_PROGRESS')).toBe(2);
+        expect(taskPriority('TODO')).toBe(1);
+        expect(taskPriority('BLOCKED')).toBe(0);
     });
-    it("returns zero timestamp for invalid date", () => {
-        expect(toTaskUpdatedAtMs("invalid")).toBe(0);
+    it('returns zero timestamp for invalid date', () => {
+        expect(toTaskUpdatedAtMs('invalid')).toBe(0);
     });
-    it("ranks by project score, then task priority, then recency", () => {
+    it('ranks by project score, then task priority, then recency', () => {
         const candidates = [
-            buildCandidate({ id: "TASK-0001", title: "A", status: "TODO", projectScore: 2 }),
-            buildCandidate({ id: "TASK-0002", title: "B", status: "IN_PROGRESS", projectScore: 2 }),
-            buildCandidate({ id: "TASK-0003", title: "C", status: "IN_PROGRESS", projectScore: 3 }),
+            buildCandidate({ id: 'TASK-0001', title: 'A', status: 'TODO', projectScore: 2 }),
+            buildCandidate({ id: 'TASK-0002', title: 'B', status: 'IN_PROGRESS', projectScore: 2 }),
+            buildCandidate({ id: 'TASK-0003', title: 'C', status: 'IN_PROGRESS', projectScore: 3 }),
         ];
         const ranked = rankActionableTaskCandidates(candidates);
-        expect(ranked[0].task.id).toBe("TASK-0003");
-        expect(ranked[1].task.id).toBe("TASK-0002");
-        expect(ranked[2].task.id).toBe("TASK-0001");
+        expect(ranked[0].task.id).toBe('TASK-0003');
+        expect(ranked[1].task.id).toBe('TASK-0002');
+        expect(ranked[2].task.id).toBe('TASK-0001');
     });
-    it("renders task markdown without legacy markers", () => {
-        const task = normalizeTask({ id: "TASK-0002", title: "render", status: "IN_PROGRESS" });
+    it('renders task markdown without legacy markers', () => {
+        const task = normalizeTask({ id: 'TASK-0002', title: 'render', status: 'IN_PROGRESS' });
         const markdown = renderTasksMarkdown([task]);
-        expect(markdown.includes("PROJITIVE:TASKS:START")).toBe(false);
-        expect(markdown.includes("PROJITIVE:TASKS:END")).toBe(false);
-        expect(markdown.includes("## TASK-0002 | IN_PROGRESS | render")).toBe(true);
+        expect(markdown.includes('PROJITIVE:TASKS:START')).toBe(false);
+        expect(markdown.includes('PROJITIVE:TASKS:END')).toBe(false);
+        expect(markdown.includes('## TASK-0002 | IN_PROGRESS | render')).toBe(true);
+        expect(markdown).toContain('Author: yinxulai');
+        expect(markdown).toContain('Repository: https://github.com/yinxulai/projitive');
+        expect(markdown).toContain('Do not edit this file manually.');
     });
-    it("renders tasks with subState and blocker metadata", () => {
+    it('renders tasks with subState and blocker metadata', () => {
         const task1 = normalizeTask({
-            id: "TASK-0001",
-            title: "In Progress Task",
-            status: "IN_PROGRESS",
+            id: 'TASK-0001',
+            title: 'In Progress Task',
+            status: 'IN_PROGRESS',
             subState: {
-                phase: "implementation",
+                phase: 'implementation',
                 confidence: 0.85,
             },
         });
         const task2 = normalizeTask({
-            id: "TASK-0002",
-            title: "Blocked Task",
-            status: "BLOCKED",
+            id: 'TASK-0002',
+            title: 'Blocked Task',
+            status: 'BLOCKED',
             blocker: {
-                type: "external_dependency",
-                description: "Waiting for API",
+                type: 'external_dependency',
+                description: 'Waiting for API',
             },
         });
         const markdown = renderTasksMarkdown([task1, task2]);
-        expect(markdown).toContain("phase: implementation");
-        expect(markdown).toContain("confidence: 0.85");
-        expect(markdown).toContain("type: external_dependency");
-        expect(markdown).toContain("description: Waiting for API");
+        expect(markdown).toContain('phase: implementation');
+        expect(markdown).toContain('confidence: 0.85');
+        expect(markdown).toContain('type: external_dependency');
+        expect(markdown).toContain('description: Waiting for API');
     });
-    it("collects lint lines with stable code prefix", () => {
+    it('collects lint lines with stable code prefix', () => {
         const task = normalizeTask({
-            id: "TASK-0001",
-            title: "lint",
-            status: "IN_PROGRESS",
-            owner: "",
+            id: 'TASK-0001',
+            title: 'lint',
+            status: 'IN_PROGRESS',
+            owner: '',
             roadmapRefs: [],
         });
         const lint = collectTaskLintSuggestions([task]);
-        expect(lint.some((line) => line.startsWith("- [TASK_IN_PROGRESS_OWNER_EMPTY]"))).toBe(true);
-        expect(lint.some((line) => line.startsWith("- [TASK_ROADMAP_REFS_EMPTY]"))).toBe(true);
+        expect(lint.some((line) => line.startsWith('- [TASK_IN_PROGRESS_OWNER_EMPTY]'))).toBe(true);
+        expect(lint.some((line) => line.startsWith('- [TASK_ROADMAP_REFS_EMPTY]'))).toBe(true);
     });
-    it("collects blocker/substate lint rules", () => {
+    it('collects blocker/substate lint rules', () => {
         const blocked = normalizeTask({
-            id: "TASK-0001",
-            title: "Blocked",
-            status: "BLOCKED",
-            summary: "blocked reason",
-            roadmapRefs: ["ROADMAP-0001"],
+            id: 'TASK-0001',
+            title: 'Blocked',
+            status: 'BLOCKED',
+            summary: 'blocked reason',
+            roadmapRefs: ['ROADMAP-0001'],
         });
         const inProgress = normalizeTask({
-            id: "TASK-0002",
-            title: "In Progress",
-            status: "IN_PROGRESS",
-            owner: "ai-copilot",
-            roadmapRefs: ["ROADMAP-0001"],
+            id: 'TASK-0002',
+            title: 'In Progress',
+            status: 'IN_PROGRESS',
+            owner: 'ai-copilot',
+            roadmapRefs: ['ROADMAP-0001'],
         });
         const lint = collectTaskLintSuggestions([blocked, inProgress]);
-        expect(lint.some((line) => line.includes("BLOCKED_WITHOUT_BLOCKER"))).toBe(true);
-        expect(lint.some((line) => line.includes("IN_PROGRESS_WITHOUT_SUBSTATE"))).toBe(true);
+        expect(lint.some((line) => line.includes('BLOCKED_WITHOUT_BLOCKER'))).toBe(true);
+        expect(lint.some((line) => line.includes('IN_PROGRESS_WITHOUT_SUBSTATE'))).toBe(true);
     });
-    it("normalizes links to project-root-relative format without leading slash", () => {
+    it('normalizes links to project-root-relative format without leading slash', () => {
         const task = normalizeTask({
-            id: "TASK-0003",
-            title: "link normalize",
-            status: "TODO",
-            links: ["/reports/a.md", "./designs/b.md", "reports/c.md", "https://example.com/evidence"],
+            id: 'TASK-0003',
+            title: 'link normalize',
+            status: 'TODO',
+            links: ['/reports/a.md', './designs/b.md', 'reports/c.md', 'https://example.com/evidence'],
         });
-        expect(task.links).toContain("reports/a.md");
-        expect(task.links).toContain("designs/b.md");
-        expect(task.links).toContain("reports/c.md");
-        expect(task.links).toContain("https://example.com/evidence");
-        expect(task.links.some((item) => item.startsWith("/"))).toBe(false);
+        expect(task.links).toContain('reports/a.md');
+        expect(task.links).toContain('designs/b.md');
+        expect(task.links).toContain('reports/c.md');
+        expect(task.links).toContain('https://example.com/evidence');
+        expect(task.links.some((item) => item.startsWith('/'))).toBe(false);
     });
-    it("lints invalid links path format", () => {
+    it('lints invalid links path format', () => {
         const task = normalizeTask({
-            id: "TASK-0004",
-            title: "invalid link",
-            status: "TODO",
-            links: ["../outside.md"],
-            roadmapRefs: ["ROADMAP-0001"],
+            id: 'TASK-0004',
+            title: 'invalid link',
+            status: 'TODO',
+            links: ['../outside.md'],
+            roadmapRefs: ['ROADMAP-0001'],
         });
         const lint = collectTaskLintSuggestions([task]);
-        expect(lint.some((line) => line.includes("TASK_LINK_PATH_FORMAT_INVALID"))).toBe(true);
+        expect(lint.some((line) => line.includes('TASK_LINK_PATH_FORMAT_INVALID'))).toBe(true);
     });
-    it("renders seed task template with provided roadmap ref", () => {
-        const lines = renderTaskSeedTemplate("ROADMAP-0099");
-        const markdown = lines.join("\n");
-        expect(markdown).toContain("- roadmapRefs: ROADMAP-0099");
+    it('renders seed task template with provided roadmap ref', () => {
+        const lines = renderTaskSeedTemplate('ROADMAP-0099');
+        const markdown = lines.join('\n');
+        expect(markdown).toContain('- roadmapRefs: ROADMAP-0099');
     });
-    it("uses default no-task guidance when hook file is absent", async () => {
-        const guidance = await resolveNoTaskDiscoveryGuidance("/path/that/does/not/exist");
+    it('uses default no-task guidance when hook file is absent', async () => {
+        const guidance = await resolveNoTaskDiscoveryGuidance('/path/that/does/not/exist');
         expect(guidance.length).toBeGreaterThan(3);
     });
-    it("returns same default no-task guidance regardless of path", async () => {
-        const guidanceA = await resolveNoTaskDiscoveryGuidance("/path/that/does/not/exist");
-        const guidanceB = await resolveNoTaskDiscoveryGuidance("/another/path");
+    it('returns same default no-task guidance regardless of path', async () => {
+        const guidanceA = await resolveNoTaskDiscoveryGuidance('/path/that/does/not/exist');
+        const guidanceB = await resolveNoTaskDiscoveryGuidance('/another/path');
         expect(guidanceA).toEqual(guidanceB);
     });
-    it("loads and saves tasks from governance store and keeps newest-first order", async () => {
-        const root = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-task-"));
-        const governanceDir = path.join(root, ".projitive");
+    it('loads and saves tasks from governance store and keeps newest-first order', async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-mcp-task-'));
+        const governanceDir = path.join(root, '.projitive');
         await fs.mkdir(governanceDir, { recursive: true });
-        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
-        const tasksPath = path.join(governanceDir, ".projitive");
+        await fs.writeFile(path.join(governanceDir, '.projitive'), '', 'utf-8');
+        const tasksPath = path.join(governanceDir, '.projitive');
         await saveTasks(tasksPath, [
-            normalizeTask({ id: "TASK-0001", title: "older", status: "TODO", updatedAt: "2026-01-01T00:00:00.000Z" }),
-            normalizeTask({ id: "TASK-0002", title: "newer", status: "TODO", updatedAt: "2026-02-01T00:00:00.000Z" }),
+            normalizeTask({ id: 'TASK-0001', title: 'older', status: 'TODO', updatedAt: '2026-01-01T00:00:00.000Z' }),
+            normalizeTask({ id: 'TASK-0002', title: 'newer', status: 'TODO', updatedAt: '2026-02-01T00:00:00.000Z' }),
         ]);
         const loaded = await loadTasksDocument(governanceDir);
-        expect(loaded.tasks[0].id).toBe("TASK-0002");
-        expect(loaded.tasks[1].id).toBe("TASK-0001");
-        const markdown = await fs.readFile(path.join(governanceDir, "tasks.md"), "utf-8");
-        expect(markdown).toContain("generated from .projitive governance store");
+        expect(loaded.tasks[0].id).toBe('TASK-0002');
+        expect(loaded.tasks[1].id).toBe('TASK-0001');
+        const markdown = await fs.readFile(path.join(governanceDir, 'tasks.md'), 'utf-8');
+        expect(markdown).toContain('generated from .projitive governance store');
+        expect(markdown).toContain('Author: yinxulai');
+        expect(markdown).toContain('Repository: https://github.com/yinxulai/projitive');
         await fs.rm(root, { recursive: true, force: true });
     });
+    it('taskCreate auto-generates the next task id and syncs tasks view', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Bootstrap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0009', title: 'existing', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskCreate = getToolHandler(mockServer, 'taskCreate');
+        const result = await taskCreate({
+            projectPath: projectRoot,
+            title: 'newly generated',
+            summary: 'auto id test',
+            roadmapRefs: ['ROADMAP-0001'],
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toContain('TASK-0010');
+        const loaded = await loadTasksDocument(governanceDir);
+        expect(loaded.tasks.some((task) => task.id === 'TASK-0010' && task.title === 'newly generated')).toBe(true);
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskUpdate rejects invalid status transitions', async () => {
+        const { projectRoot, dbPath } = await createGovernanceWorkspace();
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'done task', status: 'DONE' }),
+        ]);
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskUpdate = getToolHandler(mockServer, 'taskUpdate');
+        const result = await taskUpdate({
+            projectPath: projectRoot,
+            taskId: 'TASK-0001',
+            updates: { status: 'IN_PROGRESS' },
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Invalid status transition');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskNext emits no-actionable guidance when only blocked tasks exist', async () => {
+        const { projectRoot, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Blocked milestone', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({
+                id: 'TASK-0001',
+                title: 'blocked task',
+                status: 'BLOCKED',
+                summary: 'waiting',
+                roadmapRefs: ['ROADMAP-0001'],
+            }),
+        ]);
+        vi.stubEnv('PROJITIVE_SCAN_ROOT_PATHS', projectRoot);
+        vi.stubEnv('PROJITIVE_SCAN_MAX_DEPTH', '3');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskNext = getToolHandler(mockServer, 'taskNext');
+        const result = await taskNext({});
+        expect(result.content[0].text).toContain('No TODO/IN_PROGRESS task is available.');
+        expect(result.content[0].text).toContain('No-Task Discovery Checklist');
+        expect(result.content[0].text).toContain('taskCreate(projectPath=');
+        vi.unstubAllEnvs();
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskList and taskContext expose synced views and evidence for an existing task', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await fs.writeFile(path.join(projectRoot, 'README.md'), '# Root Readme\nTASK-0001\n', 'utf-8');
+        await saveTasks(dbPath, [
+            normalizeTask({
+                id: 'TASK-0001',
+                title: 'inspect me',
+                status: 'IN_PROGRESS',
+                owner: 'copilot',
+                summary: 'has evidence',
+                roadmapRefs: ['ROADMAP-0001'],
+                links: ['README.md'],
+            }),
+        ]);
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskList = getToolHandler(mockServer, 'taskList');
+        const listResult = await taskList({ projectPath: projectRoot, status: 'IN_PROGRESS' });
+        expect(listResult.content[0].text).toContain(`tasksView: ${path.join(governanceDir, 'tasks.md')}`);
+        expect(listResult.content[0].text).toContain('TASK-0001 | IN_PROGRESS | inspect me');
+        const taskContext = getToolHandler(mockServer, 'taskContext');
+        const contextResult = await taskContext({ projectPath: projectRoot, taskId: 'TASK-0001' });
+        expect(contextResult.content[0].text).toContain(`roadmapView: ${path.join(governanceDir, 'roadmap.md')}`);
+        expect(contextResult.content[0].text).toContain('### Reference Locations');
+        expect(contextResult.content[0].text).toContain('README.md');
+        expect(contextResult.content[0].text).toContain('### Pre-Execution Research Brief');
+        expect(contextResult.content[0].text).toContain('researchBriefStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('designs/research/TASK-0001.implementation-research.md');
+        expect(contextResult.content[0].text).toContain('architectureDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('styleDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('Project context docs gate is NOT satisfied');
+        expect(contextResult.content[0].text).toContain('PROJECT_ARCHITECTURE_DOC_MISSING');
+        expect(contextResult.content[0].text).toContain('PROJECT_STYLE_DOC_MISSING');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskUpdate allows TODO -> IN_PROGRESS when research brief is missing, with lint guidance', async () => {
+        const { projectRoot, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Bootstrap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'gate test', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskUpdate = getToolHandler(mockServer, 'taskUpdate');
+        const result = await taskUpdate({
+            projectPath: projectRoot,
+            taskId: 'TASK-0001',
+            updates: { status: 'IN_PROGRESS' },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toContain('newStatus: IN_PROGRESS');
+        expect(result.content[0].text).toContain('TASK_RESEARCH_BRIEF_MISSING');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskUpdate allows TODO -> IN_PROGRESS when research brief is ready', async () => {
+        const { projectRoot, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Bootstrap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'gate test pass', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        const researchDir = path.join(projectRoot, 'designs', 'research');
+        await fs.mkdir(researchDir, { recursive: true });
+        await fs.writeFile(path.join(researchDir, 'TASK-0001.implementation-research.md'), [
+            '# TASK-0001 Implementation Research Brief',
+            '',
+            '## Design Guidelines and Specs',
+            '- designs/PROJITIVE.md#L10-L20',
+            '',
+            '## Code Architecture and Implementation Findings',
+            '- packages/mcp/source/tools/task.ts#L1-L50',
+        ].join('\n'), 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskUpdate = getToolHandler(mockServer, 'taskUpdate');
+        const result = await taskUpdate({
+            projectPath: projectRoot,
+            taskId: 'TASK-0001',
+            updates: { status: 'IN_PROGRESS' },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toContain('newStatus: IN_PROGRESS');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskContext requires project core docs under designs/core (docs outside core do not satisfy)', async () => {
+        const { projectRoot, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'core docs rule', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        await fs.mkdir(path.join(projectRoot, 'designs'), { recursive: true });
+        await fs.writeFile(path.join(projectRoot, 'designs', 'architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(projectRoot, 'designs', 'style-guide.md'), '# Style\n', 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskContext = getToolHandler(mockServer, 'taskContext');
+        const contextResult = await taskContext({ projectPath: projectRoot, taskId: 'TASK-0001' });
+        expect(contextResult.content[0].text).toContain('architectureDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('styleDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('designs/core/architecture.md');
+        expect(contextResult.content[0].text).toContain('PROJECT_ARCHITECTURE_DOC_MISSING');
+        expect(contextResult.content[0].text).toContain('PROJECT_STYLE_DOC_MISSING');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskContext marks project core docs ready when architecture/style docs exist under designs/core', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'core docs ready', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        const coreDir = path.join(governanceDir, 'designs', 'core');
+        await fs.mkdir(coreDir, { recursive: true });
+        await fs.writeFile(path.join(coreDir, 'architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(coreDir, 'style-guide.md'), '# Style\n', 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskContext = getToolHandler(mockServer, 'taskContext');
+        const contextResult = await taskContext({ projectPath: projectRoot, taskId: 'TASK-0001' });
+        expect(contextResult.content[0].text).toContain('architectureDocsStatus: READY');
+        expect(contextResult.content[0].text).toContain('styleDocsStatus: READY');
+        expect(contextResult.content[0].text).toContain('Project context docs gate satisfied');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskContext requires fixed core doc filenames even under designs/core', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({ id: 'TASK-0001', title: 'fixed filename rule', status: 'TODO', roadmapRefs: ['ROADMAP-0001'] }),
+        ]);
+        const coreDir = path.join(governanceDir, 'designs', 'core');
+        await fs.mkdir(coreDir, { recursive: true });
+        await fs.writeFile(path.join(coreDir, 'system-architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(coreDir, 'visual-style.md'), '# Style\n', 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskContext = getToolHandler(mockServer, 'taskContext');
+        const contextResult = await taskContext({ projectPath: projectRoot, taskId: 'TASK-0001' });
+        expect(contextResult.content[0].text).toContain('architectureDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('styleDocsStatus: MISSING');
+        expect(contextResult.content[0].text).toContain('add required file designs/core/architecture.md');
+        expect(contextResult.content[0].text).toContain('add required file designs/core/style-guide.md');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskUpdate allows IN_PROGRESS -> DONE with lint guidance when conformance fails', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await saveTasks(dbPath, [
+            normalizeTask({
+                id: 'TASK-0001',
+                title: 'done gate fail',
+                status: 'IN_PROGRESS',
+                owner: 'ai-copilot',
+                roadmapRefs: ['ROADMAP-0001'],
+                links: [],
+            }),
+        ]);
+        const researchDir = path.join(projectRoot, 'designs', 'research');
+        await fs.mkdir(researchDir, { recursive: true });
+        await fs.writeFile(path.join(researchDir, 'TASK-0001.implementation-research.md'), [
+            '# TASK-0001 Implementation Research Brief',
+            '',
+            '## Design Guidelines and Specs',
+            '- designs/core/architecture.md#L1',
+            '',
+            '## Code Architecture and Implementation Findings',
+            '- packages/mcp/source/tools/task.ts#L1',
+        ].join('\n'), 'utf-8');
+        const coreDir = path.join(governanceDir, 'designs', 'core');
+        await fs.mkdir(coreDir, { recursive: true });
+        await fs.writeFile(path.join(coreDir, 'architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(coreDir, 'style-guide.md'), '# Style\n', 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskUpdate = getToolHandler(mockServer, 'taskUpdate');
+        const result = await taskUpdate({
+            projectPath: projectRoot,
+            taskId: 'TASK-0001',
+            updates: { status: 'DONE' },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toContain('newStatus: DONE');
+        expect(result.content[0].text).toContain('TASK_DONE_LINKS_MISSING');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
+    it('taskUpdate allows IN_PROGRESS -> DONE when conformance re-check passes', async () => {
+        const { projectRoot, governanceDir, dbPath } = await createGovernanceWorkspace();
+        await replaceRoadmapsInStore(dbPath, [
+            { id: 'ROADMAP-0001', title: 'Roadmap', status: 'active', updatedAt: '2026-03-14T00:00:00.000Z' },
+        ]);
+        await fs.writeFile(path.join(projectRoot, 'README.md'), '# Evidence\n', 'utf-8');
+        await saveTasks(dbPath, [
+            normalizeTask({
+                id: 'TASK-0001',
+                title: 'done gate pass',
+                status: 'IN_PROGRESS',
+                owner: 'ai-copilot',
+                roadmapRefs: ['ROADMAP-0001'],
+                links: ['README.md'],
+            }),
+        ]);
+        const researchDir = path.join(projectRoot, 'designs', 'research');
+        await fs.mkdir(researchDir, { recursive: true });
+        await fs.writeFile(path.join(researchDir, 'TASK-0001.implementation-research.md'), [
+            '# TASK-0001 Implementation Research Brief',
+            '',
+            '## Design Guidelines and Specs',
+            '- designs/core/architecture.md#L1',
+            '',
+            '## Code Architecture and Implementation Findings',
+            '- packages/mcp/source/tools/task.ts#L1',
+        ].join('\n'), 'utf-8');
+        const coreDir = path.join(governanceDir, 'designs', 'core');
+        await fs.mkdir(coreDir, { recursive: true });
+        await fs.writeFile(path.join(coreDir, 'architecture.md'), '# Architecture\n', 'utf-8');
+        await fs.writeFile(path.join(coreDir, 'style-guide.md'), '# Style\n', 'utf-8');
+        const mockServer = { registerTool: vi.fn() };
+        registerTaskTools(mockServer);
+        const taskUpdate = getToolHandler(mockServer, 'taskUpdate');
+        const result = await taskUpdate({
+            projectPath: projectRoot,
+            taskId: 'TASK-0001',
+            updates: { status: 'DONE' },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toContain('newStatus: DONE');
+        await fs.rm(projectRoot, { recursive: true, force: true });
+    });
 });