@projitive/mcp 2.0.3 → 2.1.0

package/output/source/tools/roadmap.js

@@ -1,32 +1,30 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, ROADMAP_LINT_CODES, renderLintSuggestions, findTextReferences, ensureStore, loadRoadmapsFromStore, upsertRoadmapInStore, getStoreVersion, getMarkdownViewState, markMarkdownViewBuilt, } from "../common/index.js";
-import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
-import { resolveGovernanceDir, toProjectPath } from "./project.js";
-import { loadTasks } from "./task.js";
-export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
-export const ROADMAP_MARKDOWN_FILE = "roadmap.md";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, ROADMAP_LINT_CODES, renderLintSuggestions, findTextReferences, ensureStore, loadRoadmapsFromStore, upsertRoadmapInStore, getStoreVersion, getMarkdownViewState, markMarkdownViewBuilt, createGovernedTool, ToolExecutionError, } from '../common/index.js';
+import { resolveGovernanceDir, toProjectPath } from './project.js';
+import { loadTasks, loadTasksDocument } from './task.js';
+export const ROADMAP_ID_REGEX = /^ROADMAP-(\d+)$/;
+export const ROADMAP_MARKDOWN_FILE = 'roadmap.md';
 function nowIso() {
     return new Date().toISOString();
 }
 function nextRoadmapId(milestones) {
     const maxSuffix = milestones
         .map((item) => toRoadmapIdNumericSuffix(item.id))
-        .filter((value) => Number.isFinite(value) && value >= 0)
+        .filter((value) => value > 0)
         .reduce((max, value) => Math.max(max, value), 0);
     const next = maxSuffix + 1;
-    if (next > 9999) {
-        throw new Error("ROADMAP ID overflow: maximum supported ID is ROADMAP-9999");
-    }
-    return `ROADMAP-${String(next).padStart(4, "0")}`;
+    const minWidth = Math.max(4, String(next).length);
+    return `ROADMAP-${String(next).padStart(minWidth, '0')}`;
 }
 function toRoadmapIdNumericSuffix(roadmapId) {
-    const match = roadmapId.match(/^(?:ROADMAP-)(\d{4})$/);
+    const match = roadmapId.match(ROADMAP_ID_REGEX);
     if (!match) {
         return -1;
     }
-    return Number.parseInt(match[1], 10);
+    const suffix = Number.parseInt(match[1], 10);
+    return Number.isFinite(suffix) ? suffix : -1;
 }
 function sortMilestonesNewestFirst(milestones) {
     return [...milestones].sort((a, b) => {
@@ -34,20 +32,16 @@ function sortMilestonesNewestFirst(milestones) {
         if (Number.isFinite(updatedAtDelta) && updatedAtDelta !== 0) {
             return updatedAtDelta;
         }
-        const idDelta = toRoadmapIdNumericSuffix(b.id) - toRoadmapIdNumericSuffix(a.id);
-        if (idDelta !== 0) {
-            return idDelta;
-        }
-        return b.id.localeCompare(a.id);
+        return toRoadmapIdNumericSuffix(b.id) - toRoadmapIdNumericSuffix(a.id);
     });
 }
 function normalizeMilestone(raw) {
     return {
         id: String(raw.id),
         title: String(raw.title),
-        status: raw.status === "done" ? "done" : "active",
-        time: typeof raw.time === "string" && raw.time.trim().length > 0 ? raw.time.trim() : undefined,
-        updatedAt: typeof raw.updatedAt === "string" && Number.isFinite(new Date(raw.updatedAt).getTime()) ? raw.updatedAt : nowIso(),
+        status: raw.status === 'done' ? 'done' : 'active',
+        time: typeof raw.time === 'string' && raw.time.trim().length > 0 ? raw.time.trim() : undefined,
+        updatedAt: typeof raw.updatedAt === 'string' && Number.isFinite(new Date(raw.updatedAt).getTime()) ? raw.updatedAt : nowIso(),
     };
 }
 function normalizeAndSortMilestones(milestones) {
@@ -57,29 +51,33 @@ function normalizeAndSortMilestones(milestones) {
 }
 export function renderRoadmapMarkdown(milestones) {
     const lines = sortMilestonesNewestFirst(milestones).map((item) => {
-        const checkbox = item.status === "done" ? "x" : " ";
-        const timeText = item.time ? ` (time: ${item.time})` : "";
+        const checkbox = item.status === 'done' ? 'x' : ' ';
+        const timeText = item.time ? ` (time: ${item.time})` : '';
         return `- [${checkbox}] ${item.id}: ${item.title}${timeText}`;
     });
     return [
-        "# Roadmap",
-        "",
-        "This file is generated from .projitive governance store by Projitive MCP. Manual edits will be overwritten.",
-        "",
-        "## Active Milestones",
-        ...(lines.length > 0 ? lines : ["- (no milestones)"]),
-        "",
-    ].join("\n");
+        '# Roadmap',
+        '',
+        'Projitive is an AI-first project governance framework for tasks, roadmaps, reports, and designs.',
+        'Author: yinxulai',
+        'Repository: https://github.com/yinxulai/projitive',
+        'Do not edit this file manually. This file is automatically generated by Projitive.',
+        'This file is generated from .projitive governance store by Projitive MCP. Manual edits will be overwritten.',
+        '',
+        '## Active Milestones',
+        ...(lines.length > 0 ? lines : ['- (no milestones)']),
+        '',
+    ].join('\n');
 }
 function resolveRoadmapArtifactPaths(governanceDir) {
     return {
-        roadmapPath: path.join(governanceDir, ".projitive"),
+        roadmapPath: path.join(governanceDir, '.projitive'),
         markdownPath: path.join(governanceDir, ROADMAP_MARKDOWN_FILE),
     };
 }
 async function syncRoadmapMarkdownView(roadmapPath, markdownPath, markdown, force = false) {
-    const sourceVersion = await getStoreVersion(roadmapPath, "roadmaps");
-    const viewState = await getMarkdownViewState(roadmapPath, "roadmaps_markdown");
+    const sourceVersion = await getStoreVersion(roadmapPath, 'roadmaps');
+    const viewState = await getMarkdownViewState(roadmapPath, 'roadmaps_markdown');
     const markdownExists = await fs.access(markdownPath).then(() => true).catch(() => false);
     const shouldWrite = force
         || !markdownExists
@@ -88,8 +86,8 @@ async function syncRoadmapMarkdownView(roadmapPath, markdownPath, markdown, forc
     if (!shouldWrite) {
         return;
     }
-    await fs.writeFile(markdownPath, markdown, "utf-8");
-    await markMarkdownViewBuilt(roadmapPath, "roadmaps_markdown", sourceVersion);
+    await fs.writeFile(markdownPath, markdown, 'utf-8');
+    await markMarkdownViewBuilt(roadmapPath, 'roadmaps_markdown', sourceVersion);
 }
 export async function loadRoadmapDocument(inputPath) {
     return loadRoadmapDocumentWithOptions(inputPath, false);
@@ -98,8 +96,7 @@ export async function loadRoadmapDocumentWithOptions(inputPath, forceViewSync) {
     const governanceDir = await resolveGovernanceDir(inputPath);
     const { roadmapPath, markdownPath } = resolveRoadmapArtifactPaths(governanceDir);
     await ensureStore(roadmapPath);
-    const milestones = normalizeAndSortMilestones(await loadRoadmapsFromStore(roadmapPath));
-    const normalizedMilestones = normalizeAndSortMilestones(milestones);
+    const normalizedMilestones = normalizeAndSortMilestones(await loadRoadmapsFromStore(roadmapPath));
     const markdown = renderRoadmapMarkdown(normalizedMilestones);
     await syncRoadmapMarkdownView(roadmapPath, markdownPath, markdown, forceViewSync);
     return {
@@ -118,15 +115,15 @@ function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
     if (roadmapIds.length === 0) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.IDS_EMPTY,
-            message: "No roadmap IDs found in .projitive roadmap table.",
-            fixHint: "Add at least one ROADMAP-xxxx milestone.",
+            message: 'No roadmap IDs found in .projitive roadmap table.',
+            fixHint: 'Add at least one ROADMAP-xxxx milestone.',
         });
     }
     if (tasks.length === 0) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.TASKS_EMPTY,
-            message: "No tasks found in .projitive task table.",
-            fixHint: "Add task cards and bind roadmapRefs for traceability.",
+            message: 'No tasks found in .projitive task table.',
+            fixHint: 'Add task cards and bind roadmapRefs for traceability.',
         });
         return suggestions;
     }
@@ -136,15 +133,15 @@ function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.TASK_REFS_EMPTY,
             message: `${unboundTasks.length} task(s) have empty roadmapRefs.`,
-            fixHint: "Bind ROADMAP-xxxx where applicable.",
+            fixHint: 'Bind ROADMAP-xxxx where applicable.',
         });
     }
     const unknownRefs = Array.from(new Set(tasks.flatMap((task) => task.roadmapRefs).filter((id) => !roadmapSet.has(id))));
     if (unknownRefs.length > 0) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.UNKNOWN_REFS,
-            message: `Unknown roadmapRefs detected: ${unknownRefs.join(", ")}.`,
-            fixHint: "Add missing roadmap IDs or fix task references.",
+            message: `Unknown roadmapRefs detected: ${unknownRefs.join(', ')}.`,
+            fixHint: 'Add missing roadmap IDs or fix task references.',
         });
     }
     const noLinkedRoadmaps = roadmapIds.filter((id) => !tasks.some((task) => task.roadmapRefs.includes(id)));
@@ -152,7 +149,7 @@ function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.ZERO_LINKED_TASKS,
             message: `${noLinkedRoadmaps.length} roadmap ID(s) have zero linked tasks.`,
-            fixHint: `Consider binding tasks to: ${noLinkedRoadmaps.slice(0, 3).join(", ")}${noLinkedRoadmaps.length > 3 ? ", ..." : ""}.`,
+            fixHint: `Consider binding tasks to: ${noLinkedRoadmaps.slice(0, 3).join(', ')}${noLinkedRoadmaps.length > 3 ? ', ...' : ''}.`,
         });
     }
     return suggestions;
@@ -161,234 +158,218 @@ export function collectRoadmapLintSuggestions(roadmapIds, tasks) {
     return renderLintSuggestions(collectRoadmapLintSuggestionItems(roadmapIds, tasks));
 }
 export function isValidRoadmapId(id) {
-    return ROADMAP_ID_REGEX.test(id);
+    return toRoadmapIdNumericSuffix(id) > 0;
 }
 export function registerRoadmapTools(server) {
-    server.registerTool("roadmapList", {
-        title: "Roadmap List",
-        description: "List roadmap IDs and task linkage for planning or traceability",
+    server.registerTool(...createGovernedTool({
+        name: 'roadmapList',
+        title: 'Roadmap List',
+        description: 'List roadmap IDs and task linkage for planning or traceability',
         inputSchema: {
             projectPath: z.string(),
         },
-    }, async ({ projectPath }) => {
-        const governanceDir = await resolveGovernanceDir(projectPath);
-        const normalizedProjectPath = toProjectPath(governanceDir);
-        const roadmapIds = await loadRoadmapIds(governanceDir);
-        const { tasks } = await loadTasks(governanceDir);
-        const lintSuggestions = collectRoadmapLintSuggestions(roadmapIds, tasks);
-        const markdown = renderToolResponseMarkdown({
-            toolName: "roadmapList",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- roadmapCount: ${roadmapIds.length}`,
-                ]),
-                evidenceSection([
-                    "- roadmaps:",
-                    ...roadmapIds.map((id) => {
-                        const linkedTasks = tasks.filter((task) => task.roadmapRefs.includes(id));
-                        return `- ${id} | linkedTasks=${linkedTasks.length}`;
-                    }),
-                ]),
-                guidanceSection(["- Pick one roadmap ID and call `roadmapContext`."]),
-                lintSection(lintSuggestions),
-                nextCallSection(roadmapIds[0]
-                    ? `roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapIds[0]}\")`
-                    : undefined),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("roadmapContext", {
-        title: "Roadmap Context",
-        description: "Inspect one roadmap with linked tasks and reference locations",
+        async execute({ projectPath }) {
+            const governanceDir = await resolveGovernanceDir(projectPath);
+            const normalizedProjectPath = toProjectPath(governanceDir);
+            const { milestones, markdownPath: roadmapViewPath } = await loadRoadmapDocument(governanceDir);
+            const roadmapIds = milestones.map((item) => item.id);
+            const { tasks, markdownPath: tasksViewPath } = await loadTasksDocument(governanceDir);
+            return { normalizedProjectPath, governanceDir, roadmapIds, roadmapViewPath, tasksViewPath, tasks };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, roadmapIds }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksViewPath}`,
+            `- roadmapView: ${roadmapViewPath}`,
+            `- roadmapCount: ${roadmapIds.length}`,
+        ],
+        evidence: ({ roadmapIds, tasks }) => [
+            '- roadmaps:',
+            ...roadmapIds.map((id) => {
+                const linkedTasks = tasks.filter((task) => task.roadmapRefs.includes(id));
+                return `- ${id} | linkedTasks=${linkedTasks.length}`;
+            }),
+        ],
+        guidance: () => ['- Pick one roadmap ID and call `roadmapContext`.'],
+        suggestions: ({ roadmapIds, tasks }) => collectRoadmapLintSuggestions(roadmapIds, tasks),
+        nextCall: ({ roadmapIds, normalizedProjectPath }) => roadmapIds[0]
+            ? `roadmapContext(projectPath="${normalizedProjectPath}", roadmapId="${roadmapIds[0]}")`
+            : undefined,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'roadmapContext',
+        title: 'Roadmap Context',
+        description: 'Inspect one roadmap with linked tasks and reference locations',
         inputSchema: {
             projectPath: z.string(),
             roadmapId: z.string(),
         },
-    }, async ({ projectPath, roadmapId }) => {
-        if (!isValidRoadmapId(roadmapId)) {
-            return {
-                ...asText(renderErrorMarkdown("roadmapContext", `Invalid roadmap ID format: ${roadmapId}`, ["expected format: ROADMAP-0001", "retry with a valid roadmap ID"], `roadmapContext(projectPath=\"${projectPath}\", roadmapId=\"ROADMAP-0001\")`)),
-                isError: true,
-            };
-        }
-        const governanceDir = await resolveGovernanceDir(projectPath);
-        const normalizedProjectPath = toProjectPath(governanceDir);
-        const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const fileCandidates = candidateFilesFromArtifacts(artifacts);
-        const referenceLocations = (await Promise.all(fileCandidates.map((file) => findTextReferences(file, roadmapId)))).flat();
-        const { tasks } = await loadTasks(governanceDir);
-        const relatedTasks = tasks.filter((task) => task.roadmapRefs.includes(roadmapId));
-        const roadmapIds = await loadRoadmapIds(governanceDir);
-        const lintSuggestionItems = collectRoadmapLintSuggestionItems(roadmapIds, tasks);
-        if (relatedTasks.length === 0) {
-            lintSuggestionItems.push({
-                code: ROADMAP_LINT_CODES.CONTEXT_RELATED_TASKS_EMPTY,
-                message: `relatedTasks=0 for ${roadmapId}.`,
-                fixHint: "Batch bind task roadmapRefs to improve execution traceability.",
-            });
-        }
-        const lintSuggestions = renderLintSuggestions(lintSuggestionItems);
-        const markdown = renderToolResponseMarkdown({
-            toolName: "roadmapContext",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- roadmapId: ${roadmapId}`,
-                    `- relatedTasks: ${relatedTasks.length}`,
-                    `- references: ${referenceLocations.length}`,
-                ]),
-                evidenceSection([
-                    "### Related Tasks",
-                    ...relatedTasks.map((task) => `- ${task.id} | ${task.status} | ${task.title}`),
-                    "",
-                    "### Reference Locations",
-                    ...referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`),
-                ]),
-                guidanceSection([
-                    "- Read roadmap references first, then related tasks.",
-                    "- Keep ROADMAP/TASK IDs unchanged while updating markdown files.",
-                    "- Re-run `roadmapContext` after edits to confirm references remain consistent.",
-                ]),
-                lintSection(lintSuggestions),
-                nextCallSection(`roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapId}\")`),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("roadmapCreate", {
-        title: "Roadmap Create",
-        description: "Create one roadmap milestone in governance store",
+        async execute({ projectPath, roadmapId }) {
+            if (!isValidRoadmapId(roadmapId)) {
+                throw new ToolExecutionError(`Invalid roadmap ID format: ${roadmapId}`, ['expected format: ROADMAP-1 or ROADMAP-0001', 'retry with a valid roadmap ID'], `roadmapContext(projectPath="${projectPath}", roadmapId="ROADMAP-0001")`);
+            }
+            const governanceDir = await resolveGovernanceDir(projectPath);
+            const normalizedProjectPath = toProjectPath(governanceDir);
+            const { markdownPath: roadmapViewPath } = resolveRoadmapArtifactPaths(governanceDir);
+            const artifacts = await discoverGovernanceArtifacts(governanceDir);
+            const fileCandidates = candidateFilesFromArtifacts(artifacts);
+            const referenceLocations = (await Promise.all(fileCandidates.map((file) => findTextReferences(file, roadmapId)))).flat();
+            const { tasks, markdownPath: tasksViewPath } = await loadTasksDocument(governanceDir);
+            const relatedTasks = tasks.filter((task) => task.roadmapRefs.includes(roadmapId));
+            const roadmapIds = await loadRoadmapIds(governanceDir);
+            return { normalizedProjectPath, governanceDir, roadmapId, roadmapViewPath, tasksViewPath, relatedTasks, referenceLocations, roadmapIds, tasks };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, roadmapId, relatedTasks, referenceLocations }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksViewPath}`,
+            `- roadmapView: ${roadmapViewPath}`,
+            `- roadmapId: ${roadmapId}`,
+            `- relatedTasks: ${relatedTasks.length}`,
+            `- references: ${referenceLocations.length}`,
+        ],
+        evidence: ({ relatedTasks, referenceLocations }) => [
+            '### Related Tasks',
+            ...relatedTasks.map((task) => `- ${task.id} | ${task.status} | ${task.title}`),
+            '',
+            '### Reference Locations',
+            ...referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`),
+        ],
+        guidance: () => [
+            '- Read roadmap references first, then related tasks.',
+            '- Keep ROADMAP/TASK IDs unchanged while updating markdown files.',
+            '- Re-run `roadmapContext` after edits to confirm references remain consistent.',
+        ],
+        suggestions: ({ roadmapIds, tasks, relatedTasks, roadmapId }) => {
+            const items = collectRoadmapLintSuggestionItems(roadmapIds, tasks);
+            if (relatedTasks.length === 0) {
+                items.push({
+                    code: ROADMAP_LINT_CODES.CONTEXT_RELATED_TASKS_EMPTY,
+                    message: `relatedTasks=0 for ${roadmapId}.`,
+                    fixHint: 'Batch bind task roadmapRefs to improve execution traceability.',
+                });
+            }
+            return renderLintSuggestions(items);
+        },
+        nextCall: ({ normalizedProjectPath, roadmapId }) => `roadmapContext(projectPath="${normalizedProjectPath}", roadmapId="${roadmapId}")`,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'roadmapCreate',
+        title: 'Roadmap Create',
+        description: 'Create one roadmap milestone in governance store',
         inputSchema: {
             projectPath: z.string(),
             roadmapId: z.string().optional(),
             title: z.string(),
-            status: z.enum(["active", "done"]).optional(),
+            status: z.enum(['active', 'done']).optional(),
             time: z.string().optional(),
         },
-    }, async ({ projectPath, roadmapId, title, status, time }) => {
-        if (roadmapId && !isValidRoadmapId(roadmapId)) {
-            return {
-                ...asText(renderErrorMarkdown("roadmapCreate", `Invalid roadmap ID format: ${roadmapId}`, ["expected format: ROADMAP-0001", "omit roadmapId to auto-generate next ID"], `roadmapCreate(projectPath=\"${projectPath}\", title=\"Define milestone\", time=\"2026-Q2\")`)),
-                isError: true,
-            };
-        }
-        const governanceDir = await resolveGovernanceDir(projectPath);
-        const normalizedProjectPath = toProjectPath(governanceDir);
-        const doc = await loadRoadmapDocument(governanceDir);
-        const finalRoadmapId = roadmapId ?? nextRoadmapId(doc.milestones);
-        const duplicated = doc.milestones.some((item) => item.id === finalRoadmapId);
-        if (duplicated) {
-            return {
-                ...asText(renderErrorMarkdown("roadmapCreate", `Roadmap milestone already exists: ${finalRoadmapId}`, ["roadmap IDs must be unique", "use roadmapUpdate for existing milestone"], `roadmapUpdate(projectPath=\"${normalizedProjectPath}\", roadmapId=\"${finalRoadmapId}\", updates={...})`)),
-                isError: true,
-            };
-        }
-        const created = normalizeMilestone({
-            id: finalRoadmapId,
-            title,
-            status: status ?? "active",
-            time,
-            updatedAt: nowIso(),
-        });
-        await upsertRoadmapInStore(doc.roadmapPath, created);
-        const refreshed = await loadRoadmapDocumentWithOptions(governanceDir, true);
-        const { tasks } = await loadTasks(governanceDir);
-        const lintSuggestions = collectRoadmapLintSuggestions(refreshed.milestones.map((item) => item.id), tasks);
-        const markdown = renderToolResponseMarkdown({
-            toolName: "roadmapCreate",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- roadmapId: ${created.id}`,
-                    `- status: ${created.status}`,
-                    `- updatedAt: ${created.updatedAt}`,
-                ]),
-                evidenceSection([
-                    "### Created Milestone",
-                    `- ${created.id} | ${created.status} | ${created.title}${created.time ? ` | time=${created.time}` : ""}`,
-                    "",
-                    "### Roadmap Count",
-                    `- total: ${refreshed.milestones.length}`,
-                ]),
-                guidanceSection([
-                    "Milestone created successfully and roadmap.md has been synced.",
-                    "Re-run roadmapContext to verify linked task traceability.",
-                ]),
-                lintSection(lintSuggestions),
-                nextCallSection(`roadmapContext(projectPath=\"${normalizedProjectPath}\", roadmapId=\"${created.id}\")`),
-            ],
-        });
-        return asText(markdown);
-    });
-    server.registerTool("roadmapUpdate", {
-        title: "Roadmap Update",
-        description: "Update one roadmap milestone fields incrementally in governance store",
+        async execute({ projectPath, roadmapId, title, status, time }) {
+            if (roadmapId && !isValidRoadmapId(roadmapId)) {
+                throw new ToolExecutionError(`Invalid roadmap ID format: ${roadmapId}`, ['expected format: ROADMAP-1 or ROADMAP-0001', 'omit roadmapId to auto-generate next ID'], `roadmapCreate(projectPath="${projectPath}", title="Define milestone", time="2026-Q2")`);
+            }
+            const governanceDir = await resolveGovernanceDir(projectPath);
+            const normalizedProjectPath = toProjectPath(governanceDir);
+            const doc = await loadRoadmapDocument(governanceDir);
+            const { markdownPath: tasksViewPath } = await loadTasksDocument(governanceDir);
+            const finalRoadmapId = roadmapId ?? nextRoadmapId(doc.milestones);
+            const duplicated = doc.milestones.some((item) => item.id === finalRoadmapId);
+            if (duplicated) {
+                throw new ToolExecutionError(`Roadmap milestone already exists: ${finalRoadmapId}`, ['roadmap IDs must be unique', 'use roadmapUpdate for existing milestone'], `roadmapUpdate(projectPath="${normalizedProjectPath}", roadmapId="${finalRoadmapId}", updates={...})`);
+            }
+            const created = normalizeMilestone({
+                id: finalRoadmapId,
+                title,
+                status: status ?? 'active',
+                time,
+                updatedAt: nowIso(),
+            });
+            await upsertRoadmapInStore(doc.roadmapPath, created);
+            const refreshed = await loadRoadmapDocumentWithOptions(governanceDir, true);
+            const { tasks } = await loadTasks(governanceDir);
+            return { normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath: refreshed.markdownPath, created, refreshed, tasks };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, created }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksViewPath}`,
+            `- roadmapView: ${roadmapViewPath}`,
+            `- roadmapId: ${created.id}`,
+            `- status: ${created.status}`,
+            `- updatedAt: ${created.updatedAt}`,
+        ],
+        evidence: ({ created, refreshed }) => [
+            '### Created Milestone',
+            `- ${created.id} | ${created.status} | ${created.title}${created.time ? ` | time=${created.time}` : ''}`,
+            '',
+            '### Roadmap Count',
+            `- total: ${refreshed.milestones.length}`,
+        ],
+        guidance: () => [
+            'Milestone created successfully and roadmap.md has been synced.',
+            'Re-run roadmapContext to verify linked task traceability.',
+        ],
+        suggestions: ({ refreshed, tasks }) => collectRoadmapLintSuggestions(refreshed.milestones.map((item) => item.id), tasks),
+        nextCall: ({ normalizedProjectPath, created }) => `roadmapContext(projectPath="${normalizedProjectPath}", roadmapId="${created.id}")`,
+    }));
+    server.registerTool(...createGovernedTool({
+        name: 'roadmapUpdate',
+        title: 'Roadmap Update',
+        description: 'Update one roadmap milestone fields incrementally in governance store',
         inputSchema: {
             projectPath: z.string(),
             roadmapId: z.string(),
             updates: z.object({
                 title: z.string().optional(),
-                status: z.enum(["active", "done"]).optional(),
+                status: z.enum(['active', 'done']).optional(),
                 time: z.string().optional(),
             }),
         },
-    }, async ({ projectPath, roadmapId, updates }) => {
-        if (!isValidRoadmapId(roadmapId)) {
-            return {
-                ...asText(renderErrorMarkdown("roadmapUpdate", `Invalid roadmap ID format: ${roadmapId}`, ["expected format: ROADMAP-0001", "retry with a valid roadmap ID"], `roadmapUpdate(projectPath="${projectPath}", roadmapId="ROADMAP-0001", updates={...})`)),
-                isError: true,
-            };
-        }
-        const governanceDir = await resolveGovernanceDir(projectPath);
-        const normalizedProjectPath = toProjectPath(governanceDir);
-        const doc = await loadRoadmapDocument(governanceDir);
-        const existing = doc.milestones.find((item) => item.id === roadmapId);
-        if (!existing) {
-            return {
-                ...asText(renderErrorMarkdown("roadmapUpdate", `Roadmap milestone not found: ${roadmapId}`, ["run roadmapList to discover existing roadmap IDs", "retry with an existing roadmap ID"], `roadmapList(projectPath="${toProjectPath(governanceDir)}")`)),
-                isError: true,
+        async execute({ projectPath, roadmapId, updates }) {
+            if (!isValidRoadmapId(roadmapId)) {
+                throw new ToolExecutionError(`Invalid roadmap ID format: ${roadmapId}`, ['expected format: ROADMAP-1 or ROADMAP-0001', 'retry with a valid roadmap ID'], `roadmapUpdate(projectPath="${projectPath}", roadmapId="ROADMAP-0001", updates={...})`);
+            }
+            const governanceDir = await resolveGovernanceDir(projectPath);
+            const normalizedProjectPath = toProjectPath(governanceDir);
+            const doc = await loadRoadmapDocument(governanceDir);
+            const { markdownPath: tasksViewPath } = await loadTasksDocument(governanceDir);
+            const existing = doc.milestones.find((item) => item.id === roadmapId);
+            if (!existing) {
+                throw new ToolExecutionError(`Roadmap milestone not found: ${roadmapId}`, ['run roadmapList to discover existing roadmap IDs', 'retry with an existing roadmap ID'], `roadmapList(projectPath="${toProjectPath(governanceDir)}")`);
+            }
+            const updated = {
+                ...existing,
+                title: updates.title ?? existing.title,
+                status: updates.status ?? existing.status,
+                time: updates.time ?? existing.time,
+                updatedAt: nowIso(),
             };
-        }
-        const updated = {
-            ...existing,
-            title: updates.title ?? existing.title,
-            status: updates.status ?? existing.status,
-            time: updates.time ?? existing.time,
-            updatedAt: nowIso(),
-        };
-        await upsertRoadmapInStore(doc.roadmapPath, updated);
-        const refreshed = await loadRoadmapDocumentWithOptions(governanceDir, true);
-        const markdown = renderToolResponseMarkdown({
-            toolName: "roadmapUpdate",
-            sections: [
-                summarySection([
-                    `- projectPath: ${normalizedProjectPath}`,
-                    `- governanceDir: ${governanceDir}`,
-                    `- roadmapId: ${roadmapId}`,
-                    `- newStatus: ${updated.status}`,
-                    `- updatedAt: ${updated.updatedAt}`,
-                ]),
-                evidenceSection([
-                    "### Updated Milestone",
-                    `- ${updated.id} | ${updated.status} | ${updated.title}${updated.time ? ` | time=${updated.time}` : ""}`,
-                    "",
-                    `### Roadmap Count`,
-                    `- total: ${refreshed.milestones.length}`,
-                ]),
-                guidanceSection([
-                    "Milestone updated successfully and roadmap.md has been synced.",
-                    "Re-run roadmapContext to verify linked task traceability.",
-                    ".projitive governance store is source of truth; roadmap.md is a generated view and may be overwritten.",
-                ]),
-                lintSection([]),
-                nextCallSection(`roadmapContext(projectPath="${toProjectPath(governanceDir)}", roadmapId="${roadmapId}")`),
-            ],
-        });
-        return asText(markdown);
-    });
+            await upsertRoadmapInStore(doc.roadmapPath, updated);
+            const refreshed = await loadRoadmapDocumentWithOptions(governanceDir, true);
+            return { normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath: refreshed.markdownPath, roadmapId, updated, refreshed };
+        },
+        summary: ({ normalizedProjectPath, governanceDir, tasksViewPath, roadmapViewPath, roadmapId, updated }) => [
+            `- projectPath: ${normalizedProjectPath}`,
+            `- governanceDir: ${governanceDir}`,
+            `- tasksView: ${tasksViewPath}`,
+            `- roadmapView: ${roadmapViewPath}`,
+            `- roadmapId: ${roadmapId}`,
+            `- newStatus: ${updated.status}`,
+            `- updatedAt: ${updated.updatedAt}`,
+        ],
+        evidence: ({ updated, refreshed }) => [
+            '### Updated Milestone',
+            `- ${updated.id} | ${updated.status} | ${updated.title}${updated.time ? ` | time=${updated.time}` : ''}`,
+            '',
+            '### Roadmap Count',
+            `- total: ${refreshed.milestones.length}`,
+        ],
+        guidance: () => [
+            'Milestone updated successfully and roadmap.md has been synced.',
+            'Re-run roadmapContext to verify linked task traceability.',
+            '.projitive governance store is source of truth; roadmap.md is a generated view and may be overwritten.',
+        ],
+        suggestions: () => [],
+        nextCall: ({ normalizedProjectPath, roadmapId }) => `roadmapContext(projectPath="${normalizedProjectPath}", roadmapId="${roadmapId}")`,
+    }));
 }