@projitive/mcp 2.0.3 → 2.0.4

package/output/source/tools/project.js

@@ -1,15 +1,14 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { z } from "zod";
-import { discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions, ensureStore, replaceRoadmapsInStore, replaceTasksInStore, markMarkdownViewDirty, loadTaskStatusStatsFromStore, loadRoadmapIdsFromStore, } from "../common/index.js";
-import { asText, evidenceSection, getDefaultToolTemplateMarkdown, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
-import { collectTaskLintSuggestions, loadTasksDocument, loadTasksDocumentWithOptions, renderTasksMarkdown } from "./task.js";
-import { loadRoadmapDocumentWithOptions, renderRoadmapMarkdown } from "./roadmap.js";
-export const PROJECT_MARKER = ".projitive";
-const DEFAULT_GOVERNANCE_DIR = ".projitive";
-const ignoreNames = new Set(["node_modules", ".git", ".next", "dist", "build"]);
-const DEFAULT_SCAN_DEPTH = 3;
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+import { discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions, ensureStore, replaceRoadmapsInStore, replaceTasksInStore, markMarkdownViewDirty, loadTaskStatusStatsFromStore, } from '../common/index.js';
+import { asText, evidenceSection, getDefaultToolTemplateMarkdown, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from '../common/index.js';
+import { collectTaskLintSuggestions, loadTasksDocument, loadTasksDocumentWithOptions, renderTasksMarkdown } from './task.js';
+import { loadRoadmapDocumentWithOptions, renderRoadmapMarkdown } from './roadmap.js';
+export const PROJECT_MARKER = '.projitive';
+const DEFAULT_GOVERNANCE_DIR = '.projitive';
+const ignoreNames = new Set(['node_modules', '.git', '.next', 'dist', 'build']);
 const MAX_SCAN_DEPTH = 8;
 function normalizePath(inputPath) {
     return inputPath ? path.resolve(inputPath) : process.cwd();
@@ -17,21 +16,21 @@ function normalizePath(inputPath) {
 function normalizeGovernanceDirName(input) {
     const name = input?.trim() || DEFAULT_GOVERNANCE_DIR;
     if (!name) {
-        throw new Error("governanceDir cannot be empty");
+        throw new Error('governanceDir cannot be empty');
     }
     if (path.isAbsolute(name)) {
-        throw new Error("governanceDir must be a relative directory name");
+        throw new Error('governanceDir must be a relative directory name');
     }
-    if (name.includes("/") || name.includes("\\")) {
-        throw new Error("governanceDir must not contain path separators");
+    if (name.includes('/') || name.includes('\\')) {
+        throw new Error('governanceDir must not contain path separators');
     }
-    if (name === "." || name === "..") {
-        throw new Error("governanceDir must be a normal directory name");
+    if (name === '.' || name === '..') {
+        throw new Error('governanceDir must be a normal directory name');
     }
     return name;
 }
 function parseDepthFromEnv(rawDepth) {
-    if (typeof rawDepth !== "string" || rawDepth.trim().length === 0) {
+    if (typeof rawDepth !== 'string' || rawDepth.trim().length === 0) {
         return undefined;
     }
     const parsed = Number.parseInt(rawDepth, 10);
@@ -42,7 +41,7 @@ function parseDepthFromEnv(rawDepth) {
 }
 function requireEnvVar(name) {
     const value = process.env[name];
-    if (typeof value !== "string" || value.trim().length === 0) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
         throw new Error(`Missing required environment variable: ${name}`);
     }
     return value.trim();
@@ -67,47 +66,47 @@ export function resolveScanRoots(inputPaths) {
         return normalizedInputPaths;
     }
     const configuredRoots = process.env.PROJITIVE_SCAN_ROOT_PATHS;
-    const rootsFromMultiEnv = typeof configuredRoots === "string"
+    const rootsFromMultiEnv = typeof configuredRoots === 'string'
         ? normalizeScanRoots(parseScanRoots(configuredRoots))
         : [];
     if (rootsFromMultiEnv.length > 0) {
         return rootsFromMultiEnv;
     }
     const legacyRoot = process.env.PROJITIVE_SCAN_ROOT_PATH;
-    const rootsFromLegacyEnv = typeof legacyRoot === "string"
+    const rootsFromLegacyEnv = typeof legacyRoot === 'string'
         ? normalizeScanRoots([legacyRoot])
         : [];
     if (rootsFromLegacyEnv.length > 0) {
         return rootsFromLegacyEnv;
     }
-    throw new Error("Missing required environment variable: PROJITIVE_SCAN_ROOT_PATHS (or legacy PROJITIVE_SCAN_ROOT_PATH)");
+    throw new Error('Missing required environment variable: PROJITIVE_SCAN_ROOT_PATHS (or legacy PROJITIVE_SCAN_ROOT_PATH)');
 }
 export function resolveScanRoot(inputPath) {
     return resolveScanRoots(inputPath ? [inputPath] : undefined)[0];
 }
 export function resolveScanDepth(inputDepth) {
-    const configuredDepthRaw = requireEnvVar("PROJITIVE_SCAN_MAX_DEPTH");
+    const configuredDepthRaw = requireEnvVar('PROJITIVE_SCAN_MAX_DEPTH');
     const configuredDepth = parseDepthFromEnv(configuredDepthRaw);
-    if (typeof configuredDepth !== "number") {
-        throw new Error("Invalid PROJITIVE_SCAN_MAX_DEPTH: expected integer in range 0-8");
+    if (typeof configuredDepth !== 'number') {
+        throw new Error('Invalid PROJITIVE_SCAN_MAX_DEPTH: expected integer in range 0-8');
     }
-    if (typeof inputDepth === "number") {
+    if (typeof inputDepth === 'number') {
         return inputDepth;
     }
     return configuredDepth;
 }
 function renderArtifactsMarkdown(artifacts) {
     const rows = artifacts.map((item) => {
-        if (item.kind === "file") {
-            const lineText = item.lineCount == null ? "-" : String(item.lineCount);
-            return `- ${item.exists ? "✅" : "❌"} ${item.name}  \n  path: ${item.path}  \n  lineCount: ${lineText}`;
+        if (item.kind === 'file') {
+            const lineText = item.lineCount == null ? '-' : String(item.lineCount);
+            return `- ${item.exists ? '✅' : '❌'} ${item.name}  \n  path: ${item.path}  \n  lineCount: ${lineText}`;
         }
         const nested = (item.markdownFiles ?? [])
             .map((entry) => `    - ${entry.path} (lines: ${entry.lineCount})`)
-            .join("\n");
-        return `- ${item.exists ? "✅" : "❌"} ${item.name}/  \n  path: ${item.path}${nested ? `\n  markdownFiles:\n${nested}` : ""}`;
+            .join('\n');
+        return `- ${item.exists ? '✅' : '❌'} ${item.name}/  \n  path: ${item.path}${nested ? `\n  markdownFiles:\n${nested}` : ''}`;
     });
-    return rows.join("\n");
+    return rows.join('\n');
 }
 async function readTasksSnapshot(governanceDir) {
     const tasksPath = path.join(governanceDir, PROJECT_MARKER);
@@ -118,8 +117,8 @@ async function readTasksSnapshot(governanceDir) {
             lintSuggestions: renderLintSuggestions([
                 {
                     code: PROJECT_LINT_CODES.TASKS_FILE_MISSING,
-                    message: "governance store is missing.",
-                    fixHint: "Initialize governance tasks structure first.",
+                    message: 'governance store is missing.',
+                    fixHint: 'Initialize governance tasks structure first.',
                 },
             ]),
             todo: 0,
@@ -127,7 +126,7 @@ async function readTasksSnapshot(governanceDir) {
             blocked: 0,
             done: 0,
             total: 0,
-            latestUpdatedAt: "(unknown)",
+            latestUpdatedAt: '(unknown)',
             score: 0,
         };
     }
@@ -141,15 +140,10 @@ async function readTasksSnapshot(governanceDir) {
         blocked: stats.blocked,
         done: stats.done,
         total: stats.total,
-        latestUpdatedAt: stats.latestUpdatedAt || "(unknown)",
+        latestUpdatedAt: stats.latestUpdatedAt || '(unknown)',
         score: stats.inProgress * 2 + stats.todo,
     };
 }
-async function readRoadmapIds(governanceDir) {
-    const dbPath = path.join(governanceDir, PROJECT_MARKER);
-    await ensureStore(dbPath);
-    return loadRoadmapIdsFromStore(dbPath);
-}
 export async function hasProjectMarker(dirPath) {
     const markerPath = path.join(dirPath, PROJECT_MARKER);
     const statResult = await catchIt(fs.stat(markerPath));
@@ -246,21 +240,21 @@ export async function discoverProjectsAcrossRoots(rootPaths, maxDepth) {
     return Array.from(new Set(perRootResults.flat())).sort();
 }
 const DEFAULT_TOOL_TEMPLATE_NAMES = [
-    "projectInit",
-    "projectScan",
-    "projectNext",
-    "projectLocate",
-    "projectContext",
-    "syncViews",
-    "taskList",
-    "taskNext",
-    "taskContext",
-    "taskCreate",
-    "taskUpdate",
-    "roadmapList",
-    "roadmapContext",
-    "roadmapCreate",
-    "roadmapUpdate",
+    'projectInit',
+    'projectScan',
+    'projectNext',
+    'projectLocate',
+    'projectContext',
+    'syncViews',
+    'taskList',
+    'taskNext',
+    'taskContext',
+    'taskCreate',
+    'taskUpdate',
+    'roadmapList',
+    'roadmapContext',
+    'roadmapCreate',
+    'roadmapUpdate',
 ];
 async function pathExists(targetPath) {
     const accessResult = await catchIt(fs.access(targetPath));
@@ -269,23 +263,23 @@ async function pathExists(targetPath) {
 async function writeTextFile(targetPath, content, force) {
     const exists = await pathExists(targetPath);
     if (exists && !force) {
-        return { path: targetPath, action: "skipped" };
+        return { path: targetPath, action: 'skipped' };
     }
-    await fs.writeFile(targetPath, content, "utf-8");
-    return { path: targetPath, action: exists ? "updated" : "created" };
+    await fs.writeFile(targetPath, content, 'utf-8');
+    return { path: targetPath, action: exists ? 'updated' : 'created' };
 }
 function defaultReadmeMarkdown(governanceDirName) {
     return [
-        "# Projitive Governance Workspace",
-        "",
+        '# Projitive Governance Workspace',
+        '',
         `This directory (\`${governanceDirName}/\`) is the governance root for this project.`,
-        "",
-        "## Conventions",
-        "- Keep roadmap/task source of truth in .projitive governance store.",
-        "- Treat roadmap.md/tasks.md as generated views from governance store.",
-        "- Keep IDs stable (TASK-xxxx / ROADMAP-xxxx).",
-        "- Update report evidence before status transitions.",
-    ].join("\n");
+        '',
+        '## Conventions',
+        '- Keep roadmap/task source of truth in .projitive governance store.',
+        '- Treat roadmap.md/tasks.md as generated views from governance store.',
+        '- Keep IDs stable (TASK-xxxx / ROADMAP-xxxx).',
+        '- Update report evidence before status transitions.',
+    ].join('\n');
 }
 function defaultRoadmapMarkdown(milestones = defaultRoadmapMilestones()) {
     return renderRoadmapMarkdown(milestones);
@@ -293,51 +287,51 @@ function defaultRoadmapMarkdown(milestones = defaultRoadmapMilestones()) {
 function defaultTasksMarkdown(updatedAt = new Date().toISOString()) {
     return renderTasksMarkdown([
         {
-            id: "TASK-0001",
-            title: "Bootstrap governance workspace",
-            status: "TODO",
-            owner: "unassigned",
-            summary: "Create initial governance artifacts and confirm task execution loop.",
+            id: 'TASK-0001',
+            title: 'Bootstrap governance workspace',
+            status: 'TODO',
+            owner: 'unassigned',
+            summary: 'Create initial governance artifacts and confirm task execution loop.',
             updatedAt,
             links: [],
-            roadmapRefs: ["ROADMAP-0001"],
+            roadmapRefs: ['ROADMAP-0001'],
         },
     ]);
 }
 function defaultRoadmapMilestones() {
     return [{
-            id: "ROADMAP-0001",
-            title: "Bootstrap governance baseline",
-            status: "active",
-            time: "2026-Q1",
+            id: 'ROADMAP-0001',
+            title: 'Bootstrap governance baseline',
+            status: 'active',
+            time: '2026-Q1',
             updatedAt: new Date().toISOString(),
         }];
 }
 function defaultTemplateReadmeMarkdown() {
     return [
-        "# Template Guide",
-        "",
-        "This directory stores response templates (one file per tool).",
-        "",
-        "How to enable:",
-        "- Set env `PROJITIVE_MESSAGE_TEMPLATE_PATH` to a template directory.",
-        "- Example: .projitive/templates/tools",
-        "",
-        "Rule:",
-        "- Prefer one template per tool: <toolName>.md (e.g. taskNext.md).",
-        "- Template directory mode only loads <toolName>.md files.",
-        "- If a tool template file is missing, Projitive will auto-generate that file before rendering.",
-        "- Include {{content}} to render original tool output.",
-        "- If {{content}} is missing, original output is appended after template text.",
-        "",
-        "Basic Variables:",
-        "- {{tool_name}}",
-        "- {{summary}}",
-        "- {{evidence}}",
-        "- {{guidance}}",
-        "- {{next_call}}",
-        "- {{content}}",
-    ].join("\n");
+        '# Template Guide',
+        '',
+        'This directory stores response templates (one file per tool).',
+        '',
+        'How to enable:',
+        '- Set env `PROJITIVE_MESSAGE_TEMPLATE_PATH` to a template directory.',
+        '- Example: .projitive/templates/tools',
+        '',
+        'Rule:',
+        '- Prefer one template per tool: <toolName>.md (e.g. taskNext.md).',
+        '- Template directory mode only loads <toolName>.md files.',
+        '- If a tool template file is missing, Projitive will auto-generate that file before rendering.',
+        '- Include {{content}} to render original tool output.',
+        '- If {{content}} is missing, original output is appended after template text.',
+        '',
+        'Basic Variables:',
+        '- {{tool_name}}',
+        '- {{summary}}',
+        '- {{evidence}}',
+        '- {{guidance}}',
+        '- {{next_call}}',
+        '- {{content}}',
+    ].join('\n');
 }
 export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
     const projectPath = normalizePath(inputPath);
@@ -353,15 +347,15 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
     const directories = [];
     const requiredDirectories = [
         governancePath,
-        path.join(governancePath, "designs"),
-        path.join(governancePath, "reports"),
-        path.join(governancePath, "templates"),
-        path.join(governancePath, "templates", "tools"),
+        path.join(governancePath, 'designs'),
+        path.join(governancePath, 'reports'),
+        path.join(governancePath, 'templates'),
+        path.join(governancePath, 'templates', 'tools'),
     ];
     for (const dirPath of requiredDirectories) {
         const exists = await pathExists(dirPath);
         await fs.mkdir(dirPath, { recursive: true });
-        directories.push({ path: dirPath, action: exists ? "skipped" : "created" });
+        directories.push({ path: dirPath, action: exists ? 'skipped' : 'created' });
     }
     const markerPath = path.join(governancePath, PROJECT_MARKER);
     const defaultRoadmapData = defaultRoadmapMilestones();
@@ -372,24 +366,24 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
         await replaceRoadmapsInStore(markerPath, defaultRoadmapData);
         await replaceTasksInStore(markerPath, [
             {
-                id: "TASK-0001",
-                title: "Bootstrap governance workspace",
-                status: "TODO",
-                owner: "unassigned",
-                summary: "Create initial governance artifacts and confirm task execution loop.",
+                id: 'TASK-0001',
+                title: 'Bootstrap governance workspace',
+                status: 'TODO',
+                owner: 'unassigned',
+                summary: 'Create initial governance artifacts and confirm task execution loop.',
                 updatedAt: defaultTaskUpdatedAt,
                 links: [],
-                roadmapRefs: ["ROADMAP-0001"],
+                roadmapRefs: ['ROADMAP-0001'],
             },
         ]);
     }
     const baseFiles = await Promise.all([
-        writeTextFile(path.join(governancePath, "README.md"), defaultReadmeMarkdown(governanceDirName), force),
-        writeTextFile(path.join(governancePath, "roadmap.md"), defaultRoadmapMarkdown(defaultRoadmapData), force),
-        writeTextFile(path.join(governancePath, "tasks.md"), defaultTasksMarkdown(defaultTaskUpdatedAt), force),
-        writeTextFile(path.join(governancePath, "templates", "README.md"), defaultTemplateReadmeMarkdown(), force),
+        writeTextFile(path.join(governancePath, 'README.md'), defaultReadmeMarkdown(governanceDirName), force),
+        writeTextFile(path.join(governancePath, 'roadmap.md'), defaultRoadmapMarkdown(defaultRoadmapData), force),
+        writeTextFile(path.join(governancePath, 'tasks.md'), defaultTasksMarkdown(defaultTaskUpdatedAt), force),
+        writeTextFile(path.join(governancePath, 'templates', 'README.md'), defaultTemplateReadmeMarkdown(), force),
     ]);
-    const toolTemplateFiles = await Promise.all(DEFAULT_TOOL_TEMPLATE_NAMES.map((toolName) => writeTextFile(path.join(governancePath, "templates", "tools", `${toolName}.md`), getDefaultToolTemplateMarkdown(toolName), force)));
+    const toolTemplateFiles = await Promise.all(DEFAULT_TOOL_TEMPLATE_NAMES.map((toolName) => writeTextFile(path.join(governancePath, 'templates', 'tools', `${toolName}.md`), getDefaultToolTemplateMarkdown(toolName), force)));
     const files = [...baseFiles, ...toolTemplateFiles];
     return {
         projectPath,
@@ -399,9 +393,9 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
     };
 }
 export function registerProjectTools(server) {
-    server.registerTool("projectInit", {
-        title: "Project Init",
-        description: "Bootstrap governance files when a project has no .projitive yet (requires projectPath)",
+    server.registerTool('projectInit', {
+        title: 'Project Init',
+        description: 'Bootstrap governance files when a project has no .projitive yet (requires projectPath)',
         inputSchema: {
             projectPath: z.string(),
             governanceDir: z.string().optional(),
@@ -410,43 +404,43 @@ export function registerProjectTools(server) {
     }, async ({ projectPath, governanceDir, force }) => {
         const initialized = await initializeProjectStructure(projectPath, governanceDir, force ?? false);
         const filesByAction = {
-            created: initialized.files.filter((item) => item.action === "created"),
-            updated: initialized.files.filter((item) => item.action === "updated"),
-            skipped: initialized.files.filter((item) => item.action === "skipped"),
+            created: initialized.files.filter((item) => item.action === 'created'),
+            updated: initialized.files.filter((item) => item.action === 'updated'),
+            skipped: initialized.files.filter((item) => item.action === 'skipped'),
         };
         const markdown = renderToolResponseMarkdown({
-            toolName: "projectInit",
+            toolName: 'projectInit',
             sections: [
                 summarySection([
                     `- projectPath: ${initialized.projectPath}`,
                     `- governanceDir: ${initialized.governanceDir}`,
-                    `- force: ${force === true ? "true" : "false"}`,
+                    `- force: ${force === true ? 'true' : 'false'}`,
                 ]),
                 evidenceSection([
                     `- createdFiles: ${filesByAction.created.length}`,
                     `- updatedFiles: ${filesByAction.updated.length}`,
                     `- skippedFiles: ${filesByAction.skipped.length}`,
-                    "- directories:",
+                    '- directories:',
                     ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
-                    "- files:",
+                    '- files:',
                     ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
                 ]),
                 guidanceSection([
-                    "- If files were skipped and you want to overwrite templates, rerun with force=true.",
-                    "- Continue with projectContext and taskList for execution.",
+                    '- If files were skipped and you want to overwrite templates, rerun with force=true.',
+                    '- Continue with projectContext and taskList for execution.',
                 ]),
                 lintSection([
-                    "- After init, fill owner/roadmapRefs/links in .projitive task table before marking DONE.",
-                    "- Keep task source-of-truth inside .projitive governance store.",
+                    '- After init, fill owner/roadmapRefs/links in .projitive task table before marking DONE.',
+                    '- Keep task source-of-truth inside .projitive governance store.',
                 ]),
-                nextCallSection(`projectContext(projectPath=\"${initialized.projectPath}\")`),
+                nextCallSection(`projectContext(projectPath="${initialized.projectPath}")`),
             ],
         });
         return asText(markdown);
     });
-    server.registerTool("projectScan", {
-        title: "Project Scan",
-        description: "Start here when project path is unknown; discover all governance roots",
+    server.registerTool('projectScan', {
+        title: 'Project Scan',
+        description: 'Start here when project path is unknown; discover all governance roots',
         inputSchema: {},
     }, async () => {
         const roots = resolveScanRoots();
@@ -454,35 +448,35 @@ export function registerProjectTools(server) {
         const governanceDirs = await discoverProjectsAcrossRoots(roots, depth);
         const projects = Array.from(new Set(governanceDirs.map((governanceDir) => toProjectPath(governanceDir)))).sort();
         const markdown = renderToolResponseMarkdown({
-            toolName: "projectScan",
+            toolName: 'projectScan',
             sections: [
                 summarySection([
-                    `- rootPaths: ${roots.join(", ")}`,
+                    `- rootPaths: ${roots.join(', ')}`,
                     `- rootCount: ${roots.length}`,
                     `- maxDepth: ${depth}`,
                     `- discoveredCount: ${projects.length}`,
                 ]),
                 evidenceSection([
-                    "- projects:",
+                    '- projects:',
                     ...projects.map((project, index) => `${index + 1}. ${project}`),
                 ]),
                 guidanceSection([
-                    "- Use one discovered project path and call `projectLocate` to lock governance root.",
-                    "- Then call `projectContext` to inspect current governance state.",
+                    '- Use one discovered project path and call `projectLocate` to lock governance root.',
+                    '- Then call `projectContext` to inspect current governance state.',
                 ]),
                 lintSection(projects.length === 0
-                    ? ["- No governance root discovered. Add `.projitive` marker and baseline artifacts before execution."]
-                    : ["- Run `projectContext` on a discovered project to receive module-level lint suggestions."]),
+                    ? ['- No governance root discovered. Add `.projitive` marker and baseline artifacts before execution.']
+                    : ['- Run `projectContext` on a discovered project to receive module-level lint suggestions.']),
                 nextCallSection(projects[0]
-                    ? `projectLocate(inputPath=\"${projects[0]}\")`
+                    ? `projectLocate(inputPath="${projects[0]}")`
                     : undefined),
             ],
         });
         return asText(markdown);
     });
-    server.registerTool("projectNext", {
-        title: "Project Next",
-        description: "Rank actionable projects and return the best execution target",
+    server.registerTool('projectNext', {
+        title: 'Project Next',
+        description: 'Rank actionable projects and return the best execution target',
         inputSchema: {
             limit: z.number().int().min(1).max(50).optional(),
         },
@@ -520,10 +514,10 @@ export function registerProjectTools(server) {
             ranked[0].lintSuggestions = collectTaskLintSuggestions(topDoc.tasks);
         }
         const markdown = renderToolResponseMarkdown({
-            toolName: "projectNext",
+            toolName: 'projectNext',
             sections: [
                 summarySection([
-                    `- rootPaths: ${roots.join(", ")}`,
+                    `- rootPaths: ${roots.join(', ')}`,
                     `- rootCount: ${roots.length}`,
                     `- maxDepth: ${depth}`,
                     `- matchedProjects: ${projects.length}`,
@@ -531,25 +525,25 @@ export function registerProjectTools(server) {
                     `- limit: ${limit ?? 10}`,
                 ]),
                 evidenceSection([
-                    "- rankedProjects:",
-                    ...ranked.map((item, index) => `${index + 1}. ${toProjectPath(item.governanceDir)} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt}${item.tasksExists ? "" : " | store=missing"}`),
+                    '- rankedProjects:',
+                    ...ranked.map((item, index) => `${index + 1}. ${toProjectPath(item.governanceDir)} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt}${item.tasksExists ? '' : ' | store=missing'}`),
                 ]),
                 guidanceSection([
-                    "- Pick top 1 project and call `projectContext` with its projectPath.",
-                    "- Then call `taskList` and `taskContext` to continue execution.",
-                    "- If governance store is missing, initialize governance before task-level operations.",
+                    '- Pick top 1 project and call `projectContext` with its projectPath.',
+                    '- Then call `taskList` and `taskContext` to continue execution.',
+                    '- If governance store is missing, initialize governance before task-level operations.',
                 ]),
                 lintSection(ranked[0]?.lintSuggestions ?? []),
                 nextCallSection(ranked[0]
-                    ? `projectContext(projectPath=\"${toProjectPath(ranked[0].governanceDir)}\")`
+                    ? `projectContext(projectPath="${toProjectPath(ranked[0].governanceDir)}")`
                     : undefined),
             ],
         });
         return asText(markdown);
     });
-    server.registerTool("projectLocate", {
-        title: "Project Locate",
-        description: "Resolve the nearest governance root from any in-project path",
+    server.registerTool('projectLocate', {
+        title: 'Project Locate',
+        description: 'Resolve the nearest governance root from any in-project path',
         inputSchema: {
             inputPath: z.string(),
         },
@@ -558,70 +552,74 @@ export function registerProjectTools(server) {
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
         const projectPath = toProjectPath(governanceDir);
         const markdown = renderToolResponseMarkdown({
-            toolName: "projectLocate",
+            toolName: 'projectLocate',
             sections: [
                 summarySection([
                     `- resolvedFrom: ${resolvedFrom}`,
                     `- projectPath: ${projectPath}`,
                     `- governanceDir: ${governanceDir}`,
                 ]),
-                guidanceSection(["- Call `projectContext` with this projectPath to get task and roadmap summaries."]),
-                lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
-                nextCallSection(`projectContext(projectPath=\"${projectPath}\")`),
+                guidanceSection(['- Call `projectContext` with this projectPath to get task and roadmap summaries.']),
+                lintSection(['- Run `projectContext` to get governance/module lint suggestions for this project.']),
+                nextCallSection(`projectContext(projectPath="${projectPath}")`),
             ],
         });
         return asText(markdown);
     });
-    server.registerTool("syncViews", {
-        title: "Sync Views",
-        description: "Materialize markdown views from .projitive governance store (tasks.md / roadmap.md)",
+    server.registerTool('syncViews', {
+        title: 'Sync Views',
+        description: 'Materialize markdown views from .projitive governance store (tasks.md / roadmap.md)',
         inputSchema: {
             projectPath: z.string(),
-            views: z.array(z.enum(["tasks", "roadmap"])).optional(),
+            views: z.array(z.enum(['tasks', 'roadmap'])).optional(),
             force: z.boolean().optional(),
         },
     }, async ({ projectPath, views, force }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const normalizedProjectPath = toProjectPath(governanceDir);
+        const tasksViewPath = path.join(governanceDir, 'tasks.md');
+        const roadmapViewPath = path.join(governanceDir, 'roadmap.md');
         const dbPath = path.join(governanceDir, PROJECT_MARKER);
         const selectedViews = views && views.length > 0
             ? Array.from(new Set(views))
-            : ["tasks", "roadmap"];
+            : ['tasks', 'roadmap'];
         const forceSync = force === true;
         if (forceSync) {
-            if (selectedViews.includes("tasks")) {
-                await markMarkdownViewDirty(dbPath, "tasks_markdown");
+            if (selectedViews.includes('tasks')) {
+                await markMarkdownViewDirty(dbPath, 'tasks_markdown');
             }
-            if (selectedViews.includes("roadmap")) {
-                await markMarkdownViewDirty(dbPath, "roadmaps_markdown");
+            if (selectedViews.includes('roadmap')) {
+                await markMarkdownViewDirty(dbPath, 'roadmaps_markdown');
             }
         }
         let taskCount;
         let roadmapCount;
-        if (selectedViews.includes("tasks")) {
+        if (selectedViews.includes('tasks')) {
             const taskDoc = await loadTasksDocumentWithOptions(governanceDir, forceSync);
             taskCount = taskDoc.tasks.length;
         }
-        if (selectedViews.includes("roadmap")) {
+        if (selectedViews.includes('roadmap')) {
             const roadmapDoc = await loadRoadmapDocumentWithOptions(governanceDir, forceSync);
             roadmapCount = roadmapDoc.milestones.length;
         }
         const markdown = renderToolResponseMarkdown({
-            toolName: "syncViews",
+            toolName: 'syncViews',
             sections: [
                 summarySection([
                     `- projectPath: ${normalizedProjectPath}`,
                     `- governanceDir: ${governanceDir}`,
-                    `- views: ${selectedViews.join(", ")}`,
-                    `- force: ${forceSync ? "true" : "false"}`,
+                    `- tasksView: ${tasksViewPath}`,
+                    `- roadmapView: ${roadmapViewPath}`,
+                    `- views: ${selectedViews.join(', ')}`,
+                    `- force: ${forceSync ? 'true' : 'false'}`,
                 ]),
                 evidenceSection([
-                    ...(typeof taskCount === "number" ? [`- tasks.md synced | taskCount=${taskCount}`] : []),
-                    ...(typeof roadmapCount === "number" ? [`- roadmap.md synced | roadmapCount=${roadmapCount}`] : []),
+                    ...(typeof taskCount === 'number' ? [`- tasks.md synced | taskCount=${taskCount}`] : []),
+                    ...(typeof roadmapCount === 'number' ? [`- roadmap.md synced | roadmapCount=${roadmapCount}`] : []),
                 ]),
                 guidanceSection([
-                    "Use this tool after batch updates when you need immediate markdown materialization.",
-                    "Routine workflows can rely on lazy sync and usually do not require force=true.",
+                    'Use this tool after batch updates when you need immediate markdown materialization.',
+                    'Routine workflows can rely on lazy sync and usually do not require force=true.',
                 ]),
                 lintSection([]),
                 nextCallSection(`projectContext(projectPath="${normalizedProjectPath}")`),
@@ -629,9 +627,9 @@ export function registerProjectTools(server) {
         });
         return asText(markdown);
     });
-    server.registerTool("projectContext", {
-        title: "Project Context",
-        description: "Get project-level summary before selecting or executing a task",
+    server.registerTool('projectContext', {
+        title: 'Project Context',
+        description: 'Get project-level summary before selecting or executing a task',
         inputSchema: {
             projectPath: z.string(),
         },
@@ -643,34 +641,36 @@ export function registerProjectTools(server) {
         await ensureStore(dbPath);
         const taskStats = await loadTaskStatusStatsFromStore(dbPath);
         const { markdownPath: tasksMarkdownPath, tasks } = await loadTasksDocument(governanceDir);
-        const roadmapIds = await readRoadmapIds(governanceDir);
+        const { markdownPath: roadmapMarkdownPath, milestones } = await loadRoadmapDocumentWithOptions(governanceDir, false);
+        const roadmapIds = milestones.map((item) => item.id);
         const lintSuggestions = collectTaskLintSuggestions(tasks);
         const markdown = renderToolResponseMarkdown({
-            toolName: "projectContext",
+            toolName: 'projectContext',
             sections: [
                 summarySection([
                     `- projectPath: ${normalizedProjectPath}`,
                     `- governanceDir: ${governanceDir}`,
                     `- tasksView: ${tasksMarkdownPath}`,
+                    `- roadmapView: ${roadmapMarkdownPath}`,
                     `- roadmapIds: ${roadmapIds.length}`,
                 ]),
                 evidenceSection([
-                    "### Task Summary",
+                    '### Task Summary',
                     `- total: ${taskStats.total}`,
                     `- TODO: ${taskStats.todo}`,
                     `- IN_PROGRESS: ${taskStats.inProgress}`,
                     `- BLOCKED: ${taskStats.blocked}`,
                     `- DONE: ${taskStats.done}`,
-                    "",
-                    "### Artifacts",
+                    '',
+                    '### Artifacts',
                     renderArtifactsMarkdown(artifacts),
                 ]),
                 guidanceSection([
-                    "- Start from `taskList` to choose a target task.",
-                    "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
+                    '- Start from `taskList` to choose a target task.',
+                    '- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.',
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskList(projectPath=\"${normalizedProjectPath}\")`),
+                nextCallSection(`taskList(projectPath="${normalizedProjectPath}")`),
             ],
         });
         return asText(markdown);