@projitive/mcp 1.0.1 → 1.0.3

package/output/projitive.js

@@ -4,17 +4,14 @@ import process from "node:process";
 import { z } from "zod";
 import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { catchIt } from "./helpers/catch/index.js";
-import { loadTasks } from "./tasks.js";
+import { PROJECT_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
+import { collectTaskLintSuggestions, loadTasksDocument } from "./tasks.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;
 const MAX_SCAN_DEPTH = 8;
-function asText(markdown) {
-    return {
-        content: [{ type: "text", text: markdown }],
-    };
-}
 function normalizePath(inputPath) {
     return inputPath ? path.resolve(inputPath) : process.cwd();
 }
@@ -71,11 +68,22 @@ async function readTasksSnapshot(governanceDir) {
     const tasksPath = path.join(governanceDir, "tasks.md");
     const markdown = await fs.readFile(tasksPath, "utf-8").catch(() => undefined);
     if (typeof markdown !== "string") {
-        return { tasksPath, exists: false, tasks: [] };
+        return {
+            tasksPath,
+            exists: false,
+            tasks: [],
+            lintSuggestions: renderLintSuggestions([
+                {
+                    code: PROJECT_LINT_CODES.TASKS_FILE_MISSING,
+                    message: "tasks.md is missing.",
+                    fixHint: "Initialize governance tasks structure first.",
+                },
+            ]),
+        };
     }
     const { parseTasksBlock } = await import("./tasks.js");
     const tasks = await parseTasksBlock(markdown);
-    return { tasksPath, exists: true, tasks };
+    return { tasksPath, exists: true, tasks, lintSuggestions: collectTaskLintSuggestions(tasks, markdown) };
 }
 function latestTaskUpdatedAt(tasks) {
     const timestamps = tasks
@@ -193,12 +201,30 @@ function defaultTasksMarkdown() {
         "- owner: unassigned",
         "- summary: Create initial governance artifacts and confirm task execution loop.",
         `- updatedAt: ${updatedAt}`,
-        "- links:",
         "- roadmapRefs: ROADMAP-0001",
-        "- hooks:",
+        "- links:",
+        "  - (none)",
         "<!-- PROJITIVE:TASKS:END -->",
     ].join("\n");
 }
+function defaultNoTaskDiscoveryHookMarkdown() {
+    return [
+        "Objective:",
+        "- When no actionable task exists, proactively discover meaningful work and convert it into TODO tasks.",
+        "",
+        "Checklist:",
+        "- Check whether code violates project guides/specs; create tasks for each actionable gap.",
+        "- Check test coverage improvement opportunities; create tasks for high-value missing tests.",
+        "- Check development/testing workflow bottlenecks; create tasks for reliability and speed improvements.",
+        "- Check TODO/FIXME/HACK comments; turn feasible items into governed tasks.",
+        "- Check dependency/security hygiene and stale tooling; create tasks where upgrades are justified.",
+        "",
+        "Output Format:",
+        "- Candidate findings (3-10)",
+        "- Proposed tasks (TASK-xxxx style)",
+        "- Priority rationale",
+    ].join("\n");
+}
 export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
     const rootPath = normalizePath(inputPath);
     const governanceDirName = normalizeGovernanceDirName(governanceDir);
@@ -223,6 +249,7 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
         writeTextFile(path.join(governancePath, "README.md"), defaultReadmeMarkdown(governanceDirName), force),
         writeTextFile(path.join(governancePath, "roadmap.md"), defaultRoadmapMarkdown(), force),
         writeTextFile(path.join(governancePath, "tasks.md"), defaultTasksMarkdown(), force),
+        writeTextFile(path.join(governancePath, "hooks", "task_no_actionable.md"), defaultNoTaskDiscoveryHookMarkdown(), force),
     ]);
     return {
         rootPath,
@@ -248,31 +275,35 @@ export function registerProjectTools(server) {
             updated: initialized.files.filter((item) => item.action === "updated"),
             skipped: initialized.files.filter((item) => item.action === "skipped"),
         };
-        const markdown = [
-            "# projectInit",
-            "",
-            "## Summary",
-            `- rootPath: ${initialized.rootPath}`,
-            `- governanceDir: ${initialized.governanceDir}`,
-            `- markerPath: ${initialized.markerPath}`,
-            `- force: ${force === true ? "true" : "false"}`,
-            "",
-            "## Evidence",
-            `- 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}`),
-            "",
-            "## Agent Guidance",
-            "- If files were skipped and you want to overwrite templates, rerun with force=true.",
-            "- Continue with projectContext and taskList for execution.",
-            "",
-            "## Next Call",
-            `- projectContext(projectPath=\"${initialized.governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectInit",
+            sections: [
+                summarySection([
+                    `- rootPath: ${initialized.rootPath}`,
+                    `- governanceDir: ${initialized.governanceDir}`,
+                    `- markerPath: ${initialized.markerPath}`,
+                    `- 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 tasks.md before marking DONE.",
+                    "- Keep task source-of-truth inside marker block only.",
+                ]),
+                nextCallSection(`projectContext(projectPath=\"${initialized.governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectScan", {
@@ -286,27 +317,30 @@ export function registerProjectTools(server) {
         const root = resolveScanRoot(rootPath);
         const depth = resolveScanDepth(maxDepth);
         const projects = await discoverProjects(root, depth);
-        const markdown = [
-            "# projectScan",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- discoveredCount: ${projects.length}`,
-            "",
-            "## Evidence",
-            "- projects:",
-            ...(projects.length > 0 ? projects.map((project, index) => `${index + 1}. ${project}`) : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Use one discovered project path and call `projectLocate` to lock governance root.",
-            "- Then call `projectContext` to inspect current governance state.",
-            "",
-            "## Next Call",
-            ...(projects.length > 0
-                ? [`- projectLocate(inputPath=\"${projects[0]}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectScan",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- 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", {
@@ -332,7 +366,7 @@ export function registerProjectTools(server) {
                 governanceDir,
                 tasksPath: snapshot.tasksPath,
                 tasksExists: snapshot.exists,
-                total: snapshot.tasks.length,
+                lintSuggestions: snapshot.lintSuggestions,
                 inProgress,
                 todo,
                 blocked,
@@ -351,32 +385,31 @@ export function registerProjectTools(server) {
             return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
         })
             .slice(0, limit ?? 10);
-        const markdown = [
-            "# projectNext",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- matchedProjects: ${projects.length}`,
-            `- actionableProjects: ${ranked.length}`,
-            `- limit: ${limit ?? 10}`,
-            "",
-            "## Evidence",
-            "- rankedProjects:",
-            ...(ranked.length > 0
-                ? ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt} | tasksPath=${item.tasksPath}${item.tasksExists ? "" : " (missing)"}`)
-                : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Pick top 1 project and call `projectContext` with its governanceDir.",
-            "- Then call `taskList` and `taskContext` to continue execution.",
-            "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
-            "",
-            "## Next Call",
-            ...(ranked.length > 0
-                ? [`- projectContext(projectPath=\"${ranked[0].governanceDir}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectNext",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- matchedProjects: ${projects.length}`,
+                    `- actionableProjects: ${ranked.length}`,
+                    `- limit: ${limit ?? 10}`,
+                ]),
+                evidenceSection([
+                    "- rankedProjects:",
+                    ...ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt} | tasksPath=${item.tasksPath}${item.tasksExists ? "" : " (missing)"}`),
+                ]),
+                guidanceSection([
+                    "- Pick top 1 project and call `projectContext` with its governanceDir.",
+                    "- Then call `taskList` and `taskContext` to continue execution.",
+                    "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
+                ]),
+                lintSection(ranked[0]?.lintSuggestions ?? []),
+                nextCallSection(ranked[0]
+                    ? `projectContext(projectPath=\"${ranked[0].governanceDir}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectLocate", {
@@ -389,20 +422,19 @@ export function registerProjectTools(server) {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
         const markerPath = path.join(governanceDir, ".projitive");
-        const markdown = [
-            "# projectLocate",
-            "",
-            "## Summary",
-            `- resolvedFrom: ${resolvedFrom}`,
-            `- governanceDir: ${governanceDir}`,
-            `- markerPath: ${markerPath}`,
-            "",
-            "## Agent Guidance",
-            "- Call `projectContext` with this governanceDir to get task and roadmap summaries.",
-            "",
-            "## Next Call",
-            `- projectContext(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectLocate",
+            sections: [
+                summarySection([
+                    `- resolvedFrom: ${resolvedFrom}`,
+                    `- governanceDir: ${governanceDir}`,
+                    `- markerPath: ${markerPath}`,
+                ]),
+                guidanceSection(["- Call `projectContext` with this governanceDir to get task and roadmap summaries."]),
+                lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
+                nextCallSection(`projectContext(projectPath=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectContext", {
@@ -414,8 +446,9 @@ export function registerProjectTools(server) {
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const { tasksPath, tasks } = await loadTasks(governanceDir);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const roadmapIds = await readRoadmapIds(governanceDir);
+        const lintSuggestions = collectTaskLintSuggestions(tasks, tasksMarkdown);
         const taskSummary = {
             total: tasks.length,
             TODO: tasks.filter((task) => task.status === "TODO").length,
@@ -423,32 +456,33 @@ export function registerProjectTools(server) {
             BLOCKED: tasks.filter((task) => task.status === "BLOCKED").length,
             DONE: tasks.filter((task) => task.status === "DONE").length,
         };
-        const markdown = [
-            "# projectContext",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- tasksFile: ${tasksPath}`,
-            `- roadmapIds: ${roadmapIds.length}`,
-            "",
-            "## Evidence",
-            "### Task Summary",
-            `- total: ${taskSummary.total}`,
-            `- TODO: ${taskSummary.TODO}`,
-            `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
-            `- BLOCKED: ${taskSummary.BLOCKED}`,
-            `- DONE: ${taskSummary.DONE}`,
-            "",
-            "### Artifacts",
-            renderArtifactsMarkdown(artifacts),
-            "",
-            "## Agent Guidance",
-            "- Start from `taskList` to choose a target task.",
-            "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
-            "",
-            "## Next Call",
-            `- taskList(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectContext",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- tasksFile: ${tasksPath}`,
+                    `- roadmapIds: ${roadmapIds.length}`,
+                ]),
+                evidenceSection([
+                    "### Task Summary",
+                    `- total: ${taskSummary.total}`,
+                    `- TODO: ${taskSummary.TODO}`,
+                    `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
+                    `- BLOCKED: ${taskSummary.BLOCKED}`,
+                    `- DONE: ${taskSummary.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=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
 }

package/output/projitive.test.js

@@ -52,6 +52,7 @@ describe("projitive module", () => {
             path.join(root, ".projitive", "README.md"),
             path.join(root, ".projitive", "roadmap.md"),
             path.join(root, ".projitive", "tasks.md"),
+            path.join(root, ".projitive", "hooks", "task_no_actionable.md"),
             path.join(root, ".projitive", "designs"),
             path.join(root, ".projitive", "reports"),
             path.join(root, ".projitive", "hooks"),

package/output/rendering-input-guard.test.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+const MODULE_FILES = [
+    "tasks.ts",
+    "roadmap.ts",
+    "projitive.ts",
+];
+const INVALID_LITERAL_PATTERN = /["'`]\s*-\s+(#{1,6}\s|>\s*|```)/g;
+describe("rendering input guard", () => {
+    it("does not contain accidental bullet-prefixed markdown literals in module outputs", async () => {
+        const sourceDir = path.resolve(import.meta.dirname);
+        for (const file of MODULE_FILES) {
+            const filePath = path.join(sourceDir, file);
+            const content = await fs.readFile(filePath, "utf-8");
+            const matches = content.match(INVALID_LITERAL_PATTERN) ?? [];
+            expect(matches, `invalid literals in ${filePath}`).toHaveLength(0);
+        }
+    });
+});

package/output/roadmap.js

@@ -1,39 +1,60 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { candidateFilesFromArtifacts } from "./helpers/artifacts/index.js";
 import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
+import { ROADMAP_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
 import { findTextReferences } from "./helpers/markdown/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
 import { resolveGovernanceDir } from "./projitive.js";
 import { loadTasks } from "./tasks.js";
 export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
-function asText(markdown) {
-    return {
-        content: [{ type: "text", text: markdown }],
-    };
-}
-function renderErrorMarkdown(toolName, cause, nextSteps, retryExample) {
-    return [
-        `# ${toolName}`,
-        "",
-        "## Error",
-        `- cause: ${cause}`,
-        "",
-        "## Next Step",
-        ...(nextSteps.length > 0 ? nextSteps : ["- (none)"]),
-        "",
-        "## Retry Example",
-        `- ${retryExample ?? "(none)"}`,
-    ].join("\n");
+function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
+    const suggestions = [];
+    if (roadmapIds.length === 0) {
+        suggestions.push({
+            code: ROADMAP_LINT_CODES.IDS_EMPTY,
+            message: "No roadmap IDs found in roadmap.md.",
+            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 tasks.md.",
+            fixHint: "Add task cards and bind roadmapRefs for traceability.",
+        });
+        return suggestions;
+    }
+    const roadmapSet = new Set(roadmapIds);
+    const unboundTasks = tasks.filter((task) => task.roadmapRefs.length === 0);
+    if (unboundTasks.length > 0) {
+        suggestions.push({
+            code: ROADMAP_LINT_CODES.TASK_REFS_EMPTY,
+            message: `${unboundTasks.length} task(s) have empty roadmapRefs.`,
+            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.",
+        });
+    }
+    const noLinkedRoadmaps = roadmapIds.filter((id) => !tasks.some((task) => task.roadmapRefs.includes(id)));
+    if (noLinkedRoadmaps.length > 0) {
+        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 ? ", ..." : ""}.`,
+        });
+    }
+    return suggestions;
 }
-function candidateFilesFromArtifacts(artifacts) {
-    return artifacts
-        .filter((item) => item.exists)
-        .flatMap((item) => {
-        if (item.kind === "file") {
-            return [item.path];
-        }
-        return (item.markdownFiles ?? []).map((entry) => entry.path);
-    });
+export function collectRoadmapLintSuggestions(roadmapIds, tasks) {
+    return renderLintSuggestions(collectRoadmapLintSuggestionItems(roadmapIds, tasks));
 }
 export function isValidRoadmapId(id) {
     return ROADMAP_ID_REGEX.test(id);
@@ -60,30 +81,28 @@ export function registerRoadmapTools(server) {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const roadmapIds = await readRoadmapIds(governanceDir);
         const { tasks } = await loadTasks(governanceDir);
-        const markdown = [
-            "# roadmapList",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- roadmapCount: ${roadmapIds.length}`,
-            "",
-            "## Evidence",
-            "- roadmaps:",
-            ...(roadmapIds.length > 0
-                ? roadmapIds.map((id) => {
-                    const linkedTasks = tasks.filter((task) => task.roadmapRefs.includes(id));
-                    return `- ${id} | linkedTasks=${linkedTasks.length}`;
-                })
-                : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Pick one roadmap ID and call `roadmapContext`.",
-            "",
-            "## Next Call",
-            ...(roadmapIds.length > 0
-                ? [`- roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapIds[0]}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const lintSuggestions = collectRoadmapLintSuggestions(roadmapIds, tasks);
+        const markdown = renderToolResponseMarkdown({
+            toolName: "roadmapList",
+            sections: [
+                summarySection([
+                    `- 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=\"${governanceDir}\", roadmapId=\"${roadmapIds[0]}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("roadmapContext", {
@@ -96,7 +115,7 @@ export function registerRoadmapTools(server) {
     }, 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\")`)),
+                ...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,
             };
         }
@@ -106,34 +125,41 @@ export function registerRoadmapTools(server) {
         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 markdown = [
-            "# roadmapContext",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- roadmapId: ${roadmapId}`,
-            `- relatedTasks: ${relatedTasks.length}`,
-            `- references: ${referenceLocations.length}`,
-            "",
-            "## Evidence",
-            "### Related Tasks",
-            ...(relatedTasks.length > 0
-                ? relatedTasks.map((task) => `- ${task.id} | ${task.status} | ${task.title}`)
-                : ["- (none)"]),
-            "",
-            "### Reference Locations",
-            ...(referenceLocations.length > 0
-                ? referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`)
-                : ["- (none)"]),
-            "",
-            "## Agent 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.",
-            "",
-            "## Next Call",
-            `- roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapId}\")`,
-        ].join("\n");
+        const roadmapIds = await readRoadmapIds(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([
+                    `- 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=\"${governanceDir}\", roadmapId=\"${roadmapId}\")`),
+            ],
+        });
         return asText(markdown);
     });
 }

package/output/roadmap.test.js

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { collectRoadmapLintSuggestions } from "./roadmap.js";
+import { normalizeTask } from "./tasks.js";
+describe("roadmap lint rendering alignment", () => {
+    it("renders roadmap lint in code-prefixed markdown lines", () => {
+        const lint = collectRoadmapLintSuggestions(["ROADMAP-0001"], [
+            normalizeTask({ id: "TASK-0001", title: "x", status: "TODO", roadmapRefs: [] }),
+        ]);
+        expect(lint.some((line) => line.startsWith("- [ROADMAP_TASK_REFS_EMPTY]"))).toBe(true);
+    });
+});