@projitive/mcp 2.0.3 → 2.1.0

package/output/source/tools/project.js

@@ -1,39 +1,31 @@
-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, loadTaskStatusStatsFromStore, createGovernedTool, getDefaultToolTemplateMarkdown, } 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();
 }
 function normalizeGovernanceDirName(input) {
     const name = input?.trim() || DEFAULT_GOVERNANCE_DIR;
-    if (!name) {
-        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) {
-        return undefined;
-    }
     const parsed = Number.parseInt(rawDepth, 10);
     if (!Number.isFinite(parsed)) {
         return undefined;
@@ -42,7 +34,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 +59,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 +110,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 +119,7 @@ async function readTasksSnapshot(governanceDir) {
             blocked: 0,
             done: 0,
             total: 0,
-            latestUpdatedAt: "(unknown)",
+            latestUpdatedAt: '(unknown)',
             score: 0,
         };
     }
@@ -141,15 +133,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 +233,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 +256,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 +280,49 @@ 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.',
+        '',
+        'Basic Variables:',
+        '- {{tool_name}}',
+        '- {{summary}}',
+        '- {{evidence}}',
+        '- {{guidance}}',
+        '- {{lint_suggestions}}',
+        '- {{next_call}}',
+    ].join('\n');
 }
 export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
     const projectPath = normalizePath(inputPath);
@@ -353,15 +338,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 +357,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,280 +384,248 @@ 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(...createGovernedTool({
+        name: '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(),
             force: z.boolean().optional(),
         },
-    }, 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"),
-        };
-        const markdown = renderToolResponseMarkdown({
-            toolName: "projectInit",
-            sections: [
-                summarySection([
-                    `- projectPath: ${initialized.projectPath}`,
-                    `- governanceDir: ${initialized.governanceDir}`,
-                    `- force: ${force === true ? "true" : "false"}`,
-                ]),
-                evidenceSection([
-                    `- createdFiles: ${filesByAction.created.length}`,
-                    `- updatedFiles: ${filesByAction.updated.length}`,
-                    `- skippedFiles: ${filesByAction.skipped.length}`,
-                    "- directories:",
-                    ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
-                    "- 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.",
-                ]),
-                lintSection([
-                    "- 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}\")`),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("projectScan", {
-        title: "Project Scan",
-        description: "Start here when project path is unknown; discover all governance roots",
+        async execute({ 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'),
+            };
+            return { initialized, filesByAction, force: force ?? false };
+        },
+        summary: ({ initialized, force }) => [
+            `- projectPath: ${initialized.projectPath}`,
+            `- governanceDir: ${initialized.governanceDir}`,
+            `- force: ${force ? 'true' : 'false'}`,
+        ],
+        evidence: ({ initialized, filesByAction }) => [
+            `- createdFiles: ${filesByAction.created.length}`,
+            `- updatedFiles: ${filesByAction.updated.length}`,
+            `- skippedFiles: ${filesByAction.skipped.length}`,
+            '- directories:',
+            ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
+            '- files:',
+            ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
+        ],
+        guidance: () => [
+            '- If files were skipped and you want to overwrite templates, rerun with force=true.',
+            '- Continue with projectContext and taskList for execution.',
+        ],
+        suggestions: () => [
+            '- After init, fill owner/roadmapRefs/links in .projitive task table before marking DONE.',
+            '- Keep task source-of-truth inside .projitive governance store.',
+        ],
+        nextCall: ({ initialized }) => `projectContext(projectPath="${initialized.projectPath}")`,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'projectScan',
+        title: 'Project Scan',
+        description: 'Start here when project path is unknown; discover all governance roots',
         inputSchema: {},
-    }, async () => {
-        const roots = resolveScanRoots();
-        const depth = resolveScanDepth();
-        const governanceDirs = await discoverProjectsAcrossRoots(roots, depth);
-        const projects = Array.from(new Set(governanceDirs.map((governanceDir) => toProjectPath(governanceDir)))).sort();
-        const markdown = renderToolResponseMarkdown({
-            toolName: "projectScan",
-            sections: [
-                summarySection([
-                    `- rootPaths: ${roots.join(", ")}`,
-                    `- rootCount: ${roots.length}`,
-                    `- maxDepth: ${depth}`,
-                    `- discoveredCount: ${projects.length}`,
-                ]),
-                evidenceSection([
-                    "- 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.",
-                ]),
-                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."]),
-                nextCallSection(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",
+        async execute() {
+            const roots = resolveScanRoots();
+            const depth = resolveScanDepth();
+            const governanceDirs = await discoverProjectsAcrossRoots(roots, depth);
+            const projects = Array.from(new Set(governanceDirs.map((governanceDir) => toProjectPath(governanceDir)))).sort();
+            return { roots, depth, projects };
+        },
+        summary: ({ roots, depth, projects }) => [
+            `- rootPaths: ${roots.join(', ')}`,
+            `- rootCount: ${roots.length}`,
+            `- maxDepth: ${depth}`,
+            `- discoveredCount: ${projects.length}`,
+        ],
+        evidence: ({ projects }) => [
+            '- projects:',
+            ...projects.map((project, index) => `${index + 1}. ${project}`),
+        ],
+        guidance: () => [
+            '- Use one discovered project path and call `projectLocate` to lock governance root.',
+            '- Then call `projectContext` to inspect current governance state.',
+        ],
+        suggestions: ({ projects }) => 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.'],
+        nextCall: ({ projects }) => projects[0] ? `projectLocate(inputPath="${projects[0]}")` : undefined,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'projectNext',
+        title: 'Project Next',
+        description: 'Rank actionable projects and return the best execution target',
         inputSchema: {
             limit: z.number().int().min(1).max(50).optional(),
         },
-    }, async ({ limit }) => {
-        const roots = resolveScanRoots();
-        const depth = resolveScanDepth();
-        const projects = await discoverProjectsAcrossRoots(roots, depth);
-        const snapshots = await Promise.all(projects.map(async (governanceDir) => {
-            const snapshot = await readTasksSnapshot(governanceDir);
-            const actionable = snapshot.inProgress + snapshot.todo;
-            return {
-                governanceDir,
-                tasksExists: snapshot.exists,
-                lintSuggestions: snapshot.lintSuggestions,
-                inProgress: snapshot.inProgress,
-                todo: snapshot.todo,
-                blocked: snapshot.blocked,
-                done: snapshot.done,
-                actionable,
-                latestUpdatedAt: snapshot.latestUpdatedAt,
-                score: snapshot.score,
-            };
-        }));
-        const ranked = snapshots
-            .filter((item) => item.actionable > 0)
-            .sort((a, b) => {
-            if (b.score !== a.score) {
-                return b.score - a.score;
-            }
-            return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
-        })
-            .slice(0, limit ?? 10);
-        if (ranked[0]) {
-            const topDoc = await loadTasksDocument(ranked[0].governanceDir);
-            ranked[0].lintSuggestions = collectTaskLintSuggestions(topDoc.tasks);
-        }
-        const markdown = renderToolResponseMarkdown({
-            toolName: "projectNext",
-            sections: [
-                summarySection([
-                    `- rootPaths: ${roots.join(", ")}`,
-                    `- rootCount: ${roots.length}`,
-                    `- maxDepth: ${depth}`,
-                    `- matchedProjects: ${projects.length}`,
-                    `- actionableProjects: ${ranked.length}`,
-                    `- 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"}`),
-                ]),
-                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.",
-                ]),
-                lintSection(ranked[0]?.lintSuggestions ?? []),
-                nextCallSection(ranked[0]
-                    ? `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",
+        async execute({ limit }) {
+            const roots = resolveScanRoots();
+            const depth = resolveScanDepth();
+            const projects = await discoverProjectsAcrossRoots(roots, depth);
+            const snapshots = await Promise.all(projects.map(async (governanceDir) => {
+                const snapshot = await readTasksSnapshot(governanceDir);
+                const actionable = snapshot.inProgress + snapshot.todo;
+                return {
+                    governanceDir,
+                    tasksExists: snapshot.exists,
+                    lintSuggestions: snapshot.lintSuggestions,
+                    inProgress: snapshot.inProgress,
+                    todo: snapshot.todo,
+                    blocked: snapshot.blocked,
+                    done: snapshot.done,
+                    actionable,
+                    latestUpdatedAt: snapshot.latestUpdatedAt,
+                    score: snapshot.score,
+                };
+            }));
+            const ranked = snapshots
+                .filter((item) => item.actionable > 0)
+                .sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
+            })
+                .slice(0, limit ?? 10);
+            const topTasks = ranked[0] ? (await loadTasksDocument(ranked[0].governanceDir)).tasks : undefined;
+            return { roots, depth, projects, ranked, limit: limit ?? 10, topTasks };
+        },
+        summary: ({ roots, depth, projects, ranked, limit }) => [
+            `- rootPaths: ${roots.join(', ')}`,
+            `- rootCount: ${roots.length}`,
+            `- maxDepth: ${depth}`,
+            `- matchedProjects: ${projects.length}`,
+            `- actionableProjects: ${ranked.length}`,
+            `- limit: ${limit}`,
+        ],
+        evidence: ({ ranked }) => [
+            '- 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'}`),
+        ],
+        guidance: () => [
+            '- 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.',
+        ],
+        suggestions: ({ topTasks }) => topTasks ? collectTaskLintSuggestions(topTasks) : [],
+        nextCall: ({ ranked }) => ranked[0] ? `projectContext(projectPath="${toProjectPath(ranked[0].governanceDir)}")` : undefined,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'projectLocate',
+        title: 'Project Locate',
+        description: 'Resolve the nearest governance root from any in-project path',
         inputSchema: {
             inputPath: z.string(),
         },
-    }, async ({ inputPath }) => {
-        const resolvedFrom = normalizePath(inputPath);
-        const governanceDir = await resolveGovernanceDir(resolvedFrom);
-        const projectPath = toProjectPath(governanceDir);
-        const markdown = renderToolResponseMarkdown({
-            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}\")`),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("syncViews", {
-        title: "Sync Views",
-        description: "Materialize markdown views from .projitive governance store (tasks.md / roadmap.md)",
+        async execute({ inputPath }) {
+            const resolvedFrom = normalizePath(inputPath);
+            const governanceDir = await resolveGovernanceDir(resolvedFrom);
+            const projectPath = toProjectPath(governanceDir);
+            return { resolvedFrom, governanceDir, projectPath };
+        },
+        summary: ({ resolvedFrom, projectPath, governanceDir }) => [
+            `- resolvedFrom: ${resolvedFrom}`,
+            `- projectPath: ${projectPath}`,
+            `- governanceDir: ${governanceDir}`,
+        ],
+        guidance: () => ['- Call `projectContext` with this projectPath to get task and roadmap summaries.'],
+        suggestions: () => ['- Run `projectContext` to get governance/module lint suggestions for this project.'],
+        nextCall: ({ projectPath }) => `projectContext(projectPath="${projectPath}")`,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: '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 dbPath = path.join(governanceDir, PROJECT_MARKER);
-        const selectedViews = views && views.length > 0
-            ? Array.from(new Set(views))
-            : ["tasks", "roadmap"];
-        const forceSync = force === true;
-        if (forceSync) {
-            if (selectedViews.includes("tasks")) {
-                await markMarkdownViewDirty(dbPath, "tasks_markdown");
+        async execute({ 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 selectedViews = views && views.length > 0 ? Array.from(new Set(views)) : ['tasks', 'roadmap'];
+            const forceSync = force === true;
+            let taskCount;
+            let roadmapCount;
+            if (selectedViews.includes('tasks')) {
+                const taskDoc = await loadTasksDocumentWithOptions(governanceDir, forceSync);
+                taskCount = taskDoc.tasks.length;
             }
-            if (selectedViews.includes("roadmap")) {
-                await markMarkdownViewDirty(dbPath, "roadmaps_markdown");
+            if (selectedViews.includes('roadmap')) {
+                const roadmapDoc = await loadRoadmapDocumentWithOptions(governanceDir, forceSync);
+                roadmapCount = roadmapDoc.milestones.length;
             }
-        }
-        let taskCount;
-        let roadmapCount;
-        if (selectedViews.includes("tasks")) {
-            const taskDoc = await loadTasksDocumentWithOptions(governanceDir, forceSync);
-            taskCount = taskDoc.tasks.length;
-        }
-        if (selectedViews.includes("roadmap")) {
-            const roadmapDoc = await loadRoadmapDocumentWithOptions(governanceDir, forceSync);
-            roadmapCount = roadmapDoc.milestones.length;
-        }
-        const markdown = renderToolResponseMarkdown({
-            toolName: "syncViews",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- views: ${selectedViews.join(", ")}`,
-                    `- force: ${forceSync ? "true" : "false"}`,
-                ]),
-                evidenceSection([
-                    ...(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.",
-                ]),
-                lintSection([]),
-                nextCallSection(`projectContext(projectPath="${normalizedProjectPath}")`),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("projectContext", {
-        title: "Project Context",
-        description: "Get project-level summary before selecting or executing a task",
+            return { normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, selectedViews, forceSync, taskCount, roadmapCount };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, selectedViews, forceSync }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksViewPath}`,
+            `- roadmapView: ${roadmapViewPath}`,
+            `- views: ${selectedViews.join(', ')}`,
+            `- force: ${forceSync ? 'true' : 'false'}`,
+        ],
+        evidence: ({ taskCount, roadmapCount }) => [
+            ...(typeof taskCount === 'number' ? [`- tasks.md synced | taskCount=${taskCount}`] : []),
+            ...(typeof roadmapCount === 'number' ? [`- roadmap.md synced | roadmapCount=${roadmapCount}`] : []),
+        ],
+        guidance: () => [
+            '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.',
+        ],
+        suggestions: () => [],
+        nextCall: ({ normalizedProjectPath }) => `projectContext(projectPath="${normalizedProjectPath}")`,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'projectContext',
+        title: 'Project Context',
+        description: 'Get project-level summary before selecting or executing a task',
         inputSchema: {
             projectPath: z.string(),
         },
-    }, async ({ projectPath }) => {
-        const governanceDir = await resolveGovernanceDir(projectPath);
-        const normalizedProjectPath = toProjectPath(governanceDir);
-        const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const dbPath = path.join(governanceDir, PROJECT_MARKER);
-        await ensureStore(dbPath);
-        const taskStats = await loadTaskStatusStatsFromStore(dbPath);
-        const { markdownPath: tasksMarkdownPath, tasks } = await loadTasksDocument(governanceDir);
-        const roadmapIds = await readRoadmapIds(governanceDir);
-        const lintSuggestions = collectTaskLintSuggestions(tasks);
-        const markdown = renderToolResponseMarkdown({
-            toolName: "projectContext",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- tasksView: ${tasksMarkdownPath}`,
-                    `- roadmapIds: ${roadmapIds.length}`,
-                ]),
-                evidenceSection([
-                    "### Task Summary",
-                    `- total: ${taskStats.total}`,
-                    `- TODO: ${taskStats.todo}`,
-                    `- IN_PROGRESS: ${taskStats.inProgress}`,
-                    `- BLOCKED: ${taskStats.blocked}`,
-                    `- DONE: ${taskStats.done}`,
-                    "",
-                    "### 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.",
-                ]),
-                lintSection(lintSuggestions),
-                nextCallSection(`taskList(projectPath=\"${normalizedProjectPath}\")`),
-            ],
-        });
-        return asText(markdown);
-    });
+        async execute({ projectPath }) {
+            const governanceDir = await resolveGovernanceDir(projectPath);
+            const normalizedProjectPath = toProjectPath(governanceDir);
+            const artifacts = await discoverGovernanceArtifacts(governanceDir);
+            const dbPath = path.join(governanceDir, PROJECT_MARKER);
+            await ensureStore(dbPath);
+            const taskStats = await loadTaskStatusStatsFromStore(dbPath);
+            const { markdownPath: tasksMarkdownPath, tasks } = await loadTasksDocument(governanceDir);
+            const { markdownPath: roadmapMarkdownPath, milestones } = await loadRoadmapDocumentWithOptions(governanceDir, false);
+            const roadmapIds = milestones.map((item) => item.id);
+            return { normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds, taskStats, artifacts, tasks };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksMarkdownPath}`,
+            `- roadmapView: ${roadmapMarkdownPath}`,
+            `- roadmapIds: ${roadmapIds.length}`,
+        ],
+        evidence: ({ taskStats, artifacts }) => [
+            '### Task Summary',
+            `- total: ${taskStats.total}`,
+            `- TODO: ${taskStats.todo}`,
+            `- IN_PROGRESS: ${taskStats.inProgress}`,
+            `- BLOCKED: ${taskStats.blocked}`,
+            `- DONE: ${taskStats.done}`,
+            '',
+            '### Artifacts',
+            renderArtifactsMarkdown(artifacts),
+        ],
+        guidance: () => [
+            '- Start from `taskList` to choose a target task.',
+            '- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.',
+        ],
+        suggestions: ({ tasks }) => collectTaskLintSuggestions(tasks),
+        nextCall: ({ normalizedProjectPath }) => `taskList(projectPath="${normalizedProjectPath}")`,
+    }));
 }