@projitive/mcp 1.0.0 → 1.0.2

package/output/tasks.js

@@ -1,33 +1,20 @@
 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 { findTextReferences } from "./helpers/markdown/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
 import { catchIt } from "./helpers/catch/index.js";
+import { TASK_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
 import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects } from "./projitive.js";
 import { isValidRoadmapId } from "./roadmap.js";
 export const TASKS_START = "<!-- PROJITIVE:TASKS:START -->";
 export const TASKS_END = "<!-- PROJITIVE:TASKS:END -->";
 export const ALLOWED_STATUS = ["TODO", "IN_PROGRESS", "BLOCKED", "DONE"];
 export const TASK_ID_REGEX = /^TASK-\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 appendLintSuggestions(target, suggestions) {
+    target.push(...renderLintSuggestions(suggestions));
 }
 function taskStatusGuidance(task) {
     if (task.status === "TODO") {
@@ -53,16 +40,6 @@ function taskStatusGuidance(task) {
         "- Keep report evidence immutable unless correction is required.",
     ];
 }
-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);
-    });
-}
 async function readOptionalMarkdown(filePath) {
     const content = await fs.readFile(filePath, "utf-8").catch(() => undefined);
     if (typeof content !== "string") {
@@ -282,6 +259,160 @@ export async function parseTasksBlock(markdown) {
     }
     return tasks;
 }
+export function findTaskIdsOutsideMarkers(markdown) {
+    const start = markdown.indexOf(TASKS_START);
+    const end = markdown.indexOf(TASKS_END);
+    const outsideText = (start !== -1 && end !== -1 && end > start)
+        ? `${markdown.slice(0, start)}\n${markdown.slice(end + TASKS_END.length)}`
+        : markdown;
+    const ids = outsideText.match(/TASK-\d{4}/g) ?? [];
+    return Array.from(new Set(ids));
+}
+function collectTaskLintSuggestionItems(tasks, options = {}) {
+    const suggestions = [];
+    const { markdown, outsideMarkerScopeIds } = options;
+    const duplicateIds = Array.from(tasks.reduce((counter, task) => {
+        counter.set(task.id, (counter.get(task.id) ?? 0) + 1);
+        return counter;
+    }, new Map())
+        .entries())
+        .filter(([, count]) => count > 1)
+        .map(([id]) => id);
+    if (duplicateIds.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.DUPLICATE_ID,
+            message: `Duplicate task IDs detected: ${duplicateIds.join(", ")}.`,
+            fixHint: "Keep task IDs unique in marker block.",
+        });
+    }
+    const inProgressWithoutOwner = tasks.filter((task) => task.status === "IN_PROGRESS" && task.owner.trim().length === 0);
+    if (inProgressWithoutOwner.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.IN_PROGRESS_OWNER_EMPTY,
+            message: `${inProgressWithoutOwner.length} IN_PROGRESS task(s) have empty owner.`,
+            fixHint: "Set owner before continuing execution.",
+        });
+    }
+    const doneWithoutLinks = tasks.filter((task) => task.status === "DONE" && task.links.length === 0);
+    if (doneWithoutLinks.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.DONE_LINKS_MISSING,
+            message: `${doneWithoutLinks.length} DONE task(s) have no links evidence.`,
+            fixHint: "Add at least one evidence link before keeping DONE.",
+        });
+    }
+    const blockedWithoutReason = tasks.filter((task) => task.status === "BLOCKED" && task.summary.trim().length === 0);
+    if (blockedWithoutReason.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKED_SUMMARY_EMPTY,
+            message: `${blockedWithoutReason.length} BLOCKED task(s) have empty summary.`,
+            fixHint: "Add blocker reason and unblock condition.",
+        });
+    }
+    const invalidUpdatedAt = tasks.filter((task) => !Number.isFinite(new Date(task.updatedAt).getTime()));
+    if (invalidUpdatedAt.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.UPDATED_AT_INVALID,
+            message: `${invalidUpdatedAt.length} task(s) have invalid updatedAt format.`,
+            fixHint: "Use ISO8601 UTC timestamp.",
+        });
+    }
+    const missingRoadmapRefs = tasks.filter((task) => task.roadmapRefs.length === 0);
+    if (missingRoadmapRefs.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.ROADMAP_REFS_EMPTY,
+            message: `${missingRoadmapRefs.length} task(s) have empty roadmapRefs.`,
+            fixHint: "Bind at least one ROADMAP-xxxx when applicable.",
+        });
+    }
+    if (typeof markdown === "string") {
+        const outsideMarkerTaskIds = findTaskIdsOutsideMarkers(markdown)
+            .filter((taskId) => (outsideMarkerScopeIds ? outsideMarkerScopeIds.has(taskId) : true));
+        if (outsideMarkerTaskIds.length > 0) {
+            suggestions.push({
+                code: TASK_LINT_CODES.OUTSIDE_MARKER,
+                message: `TASK IDs found outside marker block: ${outsideMarkerTaskIds.join(", ")}.`,
+                fixHint: "Keep task source of truth inside marker region only.",
+            });
+        }
+    }
+    return suggestions;
+}
+export function collectTaskLintSuggestions(tasks, markdown, outsideMarkerScopeIds) {
+    return renderLintSuggestions(collectTaskLintSuggestionItems(tasks, { markdown, outsideMarkerScopeIds }));
+}
+function collectSingleTaskLintSuggestions(task) {
+    const suggestions = [];
+    if (task.status === "IN_PROGRESS" && task.owner.trim().length === 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.IN_PROGRESS_OWNER_EMPTY,
+            message: "Current task is IN_PROGRESS but owner is empty.",
+            fixHint: "Set owner before continuing execution.",
+        });
+    }
+    if (task.status === "DONE" && task.links.length === 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.DONE_LINKS_MISSING,
+            message: "Current task is DONE but has no links evidence.",
+            fixHint: "Add at least one evidence link.",
+        });
+    }
+    if (task.status === "BLOCKED" && task.summary.trim().length === 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKED_SUMMARY_EMPTY,
+            message: "Current task is BLOCKED but summary is empty.",
+            fixHint: "Add blocker reason and unblock condition.",
+        });
+    }
+    if (!Number.isFinite(new Date(task.updatedAt).getTime())) {
+        suggestions.push({
+            code: TASK_LINT_CODES.UPDATED_AT_INVALID,
+            message: "Current task updatedAt is invalid.",
+            fixHint: "Use ISO8601 UTC timestamp.",
+        });
+    }
+    if (task.roadmapRefs.length === 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.ROADMAP_REFS_EMPTY,
+            message: "Current task has empty roadmapRefs.",
+            fixHint: "Bind ROADMAP-xxxx where applicable.",
+        });
+    }
+    return renderLintSuggestions(suggestions);
+}
+async function collectTaskFileLintSuggestions(governanceDir, task) {
+    const suggestions = [];
+    for (const link of task.links) {
+        const normalized = link.trim();
+        if (normalized.length === 0) {
+            continue;
+        }
+        if (/^https?:\/\//i.test(normalized)) {
+            continue;
+        }
+        const resolvedPath = path.resolve(governanceDir, normalized);
+        const exists = await fs.access(resolvedPath).then(() => true).catch(() => false);
+        if (!exists) {
+            suggestions.push({
+                code: TASK_LINT_CODES.LINK_TARGET_MISSING,
+                message: `Link target not found: ${normalized} (resolved: ${resolvedPath}).`,
+            });
+        }
+    }
+    const hookEntries = Object.entries(task.hooks)
+        .filter(([, value]) => typeof value === "string" && value.trim().length > 0);
+    for (const [hookKey, hookPath] of hookEntries) {
+        const resolvedPath = path.resolve(governanceDir, hookPath);
+        const exists = await fs.access(resolvedPath).then(() => true).catch(() => false);
+        if (!exists) {
+            suggestions.push({
+                code: TASK_LINT_CODES.HOOK_FILE_MISSING,
+                message: `Hook file not found for ${hookKey}: ${hookPath} (resolved: ${resolvedPath}).`,
+            });
+        }
+    }
+    return renderLintSuggestions(suggestions);
+}
 export function renderTasksMarkdown(tasks) {
     const sections = tasks.map((task) => {
         const roadmapRefs = task.roadmapRefs.length > 0 ? task.roadmapRefs.join(", ") : "(none)";
@@ -326,9 +457,13 @@ export async function ensureTasksFile(inputPath) {
     return tasksPath;
 }
 export async function loadTasks(inputPath) {
+    const { tasksPath, tasks } = await loadTasksDocument(inputPath);
+    return { tasksPath, tasks };
+}
+export async function loadTasksDocument(inputPath) {
     const tasksPath = await ensureTasksFile(inputPath);
     const markdown = await fs.readFile(tasksPath, "utf-8");
-    return { tasksPath, tasks: await parseTasksBlock(markdown) };
+    return { tasksPath, markdown, tasks: await parseTasksBlock(markdown) };
 }
 export async function saveTasks(tasksPath, tasks) {
     const normalized = tasks.map((task) => normalizeTask(task));
@@ -357,31 +492,41 @@ export function registerTaskTools(server) {
         },
     }, async ({ projectPath, status, limit }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
-        const { tasksPath, tasks } = await loadTasks(governanceDir);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const filtered = tasks
             .filter((task) => (status ? task.status === status : true))
             .slice(0, limit ?? 100);
-        const markdown = [
-            "# taskList",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- tasksPath: ${tasksPath}`,
-            `- filter.status: ${status ?? "(none)"}`,
-            `- returned: ${filtered.length}`,
-            "",
-            "## Evidence",
-            "- tasks:",
-            ...(filtered.length > 0
-                ? filtered.map((task) => `- ${task.id} | ${task.status} | ${task.title} | owner=${task.owner || ""} | updatedAt=${task.updatedAt}`)
-                : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Pick one task ID and call `taskContext`.",
-            "",
-            "## Next Call",
-            `- taskContext(projectPath=\"${governanceDir}\", taskId=\"TASK-0001\")`,
-        ].join("\n");
+        const lintSuggestions = collectTaskLintSuggestions(filtered, tasksMarkdown, new Set(filtered.map((task) => task.id)));
+        if (status && filtered.length === 0) {
+            appendLintSuggestions(lintSuggestions, [
+                {
+                    code: TASK_LINT_CODES.FILTER_EMPTY,
+                    message: `No tasks matched status=${status}.`,
+                    fixHint: "Confirm status values or update task states.",
+                },
+            ]);
+        }
+        const nextTaskId = filtered[0]?.id;
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- tasksPath: ${tasksPath}`,
+                    `- filter.status: ${status ?? "(none)"}`,
+                    `- returned: ${filtered.length}`,
+                ]),
+                evidenceSection([
+                    "- tasks:",
+                    ...filtered.map((task) => `- ${task.id} | ${task.status} | ${task.title} | owner=${task.owner || ""} | updatedAt=${task.updatedAt}`),
+                ]),
+                guidanceSection(["- Pick one task ID and call `taskContext`."]),
+                lintSection(lintSuggestions),
+                nextCallSection(nextTaskId
+                    ? `taskContext(projectPath=\"${governanceDir}\", taskId=\"${nextTaskId}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("taskNext", {
@@ -398,29 +543,29 @@ export function registerTaskTools(server) {
         const projects = await discoverProjects(root, depth);
         const rankedCandidates = rankActionableTaskCandidates(await readActionableTaskCandidates(projects));
         if (rankedCandidates.length === 0) {
-            const markdown = [
-                "# taskNext",
-                "",
-                "## Summary",
-                `- rootPath: ${root}`,
-                `- maxDepth: ${depth}`,
-                `- matchedProjects: ${projects.length}`,
-                "- actionableTasks: 0",
-                "",
-                "## Evidence",
-                "- candidates:",
-                "- (none)",
-                "",
-                "## Agent Guidance",
-                "- No TODO/IN_PROGRESS task is available.",
-                "- Create or reopen tasks in tasks.md, then rerun `taskNext`.",
-                "",
-                "## Next Call",
-                `- projectNext(rootPath=\"${root}\", maxDepth=${depth})`,
-            ].join("\n");
+            const markdown = renderToolResponseMarkdown({
+                toolName: "taskNext",
+                sections: [
+                    summarySection([
+                        `- rootPath: ${root}`,
+                        `- maxDepth: ${depth}`,
+                        `- matchedProjects: ${projects.length}`,
+                        "- actionableTasks: 0",
+                    ]),
+                    evidenceSection(["- candidates:", "- (none)"]),
+                    guidanceSection([
+                        "- No TODO/IN_PROGRESS task is available.",
+                        "- Create or reopen tasks in tasks.md, then rerun `taskNext`.",
+                    ]),
+                    lintSection(["- No actionable tasks found. Verify task statuses and required fields in marker block."]),
+                    nextCallSection(`projectNext(rootPath=\"${root}\", maxDepth=${depth})`),
+                ],
+            });
             return asText(markdown);
         }
         const selected = rankedCandidates[0];
+        const selectedTaskDocument = await loadTasksDocument(selected.governanceDir);
+        const lintSuggestions = collectTaskLintSuggestions(selectedTaskDocument.tasks, selectedTaskDocument.markdown);
         const artifacts = await discoverGovernanceArtifacts(selected.governanceDir);
         const fileCandidates = candidateFilesFromArtifacts(artifacts);
         const referenceLocations = (await Promise.all(fileCandidates.map((file) => findTextReferences(file, selected.task.id)))).flat();
@@ -428,55 +573,56 @@ export function registerTaskTools(server) {
         const relatedArtifacts = Array.from(new Set(referenceLocations.map((item) => item.filePath)));
         const suggestedReadOrder = [selected.tasksPath, ...relatedArtifacts.filter((item) => item !== selected.tasksPath)];
         const candidateLimit = topCandidates ?? 5;
-        const markdown = [
-            "# taskNext",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- matchedProjects: ${projects.length}`,
-            `- actionableTasks: ${rankedCandidates.length}`,
-            `- selectedProject: ${selected.governanceDir}`,
-            `- selectedTaskId: ${selected.task.id}`,
-            `- selectedTaskStatus: ${selected.task.status}`,
-            "",
-            "## Evidence",
-            "### Selected Task",
-            `- id: ${selected.task.id}`,
-            `- title: ${selected.task.title}`,
-            `- owner: ${selected.task.owner || "(none)"}`,
-            `- updatedAt: ${selected.task.updatedAt}`,
-            `- roadmapRefs: ${selected.task.roadmapRefs.join(", ") || "(none)"}`,
-            `- taskLocation: ${taskLocation ? `${taskLocation.filePath}#L${taskLocation.line}` : selected.tasksPath}`,
-            "",
-            "### Top Candidates",
-            ...rankedCandidates
-                .slice(0, candidateLimit)
-                .map((item, index) => `${index + 1}. ${item.task.id} | ${item.task.status} | ${item.task.title} | project=${item.governanceDir} | projectScore=${item.projectScore} | latest=${item.projectLatestUpdatedAt}`),
-            "",
-            "### Selection Reason",
-            "- Rank rule: projectScore DESC -> taskPriority DESC -> taskUpdatedAt DESC.",
-            `- Selected candidate scores: projectScore=${selected.projectScore}, taskPriority=${selected.taskPriority}, taskUpdatedAtMs=${selected.taskUpdatedAtMs}.`,
-            "",
-            "### Related Artifacts",
-            ...(relatedArtifacts.length > 0 ? relatedArtifacts.map((file) => `- ${file}`) : ["- (none)"]),
-            "",
-            "### Reference Locations",
-            ...(referenceLocations.length > 0
-                ? referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`)
-                : ["- (none)"]),
-            "",
-            "### Suggested Read Order",
-            ...suggestedReadOrder.map((item, index) => `${index + 1}. ${item}`),
-            "",
-            "## Agent Guidance",
-            "- Start immediately with Suggested Read Order and execute the selected task.",
-            "- Update markdown artifacts directly while keeping TASK/ROADMAP IDs unchanged.",
-            "- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.",
-            "",
-            "## Next Call",
-            `- taskContext(projectPath=\"${selected.governanceDir}\", taskId=\"${selected.task.id}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskNext",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- matchedProjects: ${projects.length}`,
+                    `- actionableTasks: ${rankedCandidates.length}`,
+                    `- selectedProject: ${selected.governanceDir}`,
+                    `- selectedTaskId: ${selected.task.id}`,
+                    `- selectedTaskStatus: ${selected.task.status}`,
+                ]),
+                evidenceSection([
+                    "### Selected Task",
+                    `- id: ${selected.task.id}`,
+                    `- title: ${selected.task.title}`,
+                    `- owner: ${selected.task.owner || "(none)"}`,
+                    `- updatedAt: ${selected.task.updatedAt}`,
+                    `- roadmapRefs: ${selected.task.roadmapRefs.join(", ") || "(none)"}`,
+                    `- taskLocation: ${taskLocation ? `${taskLocation.filePath}#L${taskLocation.line}` : selected.tasksPath}`,
+                    "",
+                    "### Top Candidates",
+                    ...rankedCandidates
+                        .slice(0, candidateLimit)
+                        .map((item, index) => `${index + 1}. ${item.task.id} | ${item.task.status} | ${item.task.title} | project=${item.governanceDir} | projectScore=${item.projectScore} | latest=${item.projectLatestUpdatedAt}`),
+                    "",
+                    "### Selection Reason",
+                    "- Rank rule: projectScore DESC -> taskPriority DESC -> taskUpdatedAt DESC.",
+                    `- Selected candidate scores: projectScore=${selected.projectScore}, taskPriority=${selected.taskPriority}, taskUpdatedAtMs=${selected.taskUpdatedAtMs}.`,
+                    "",
+                    "### Related Artifacts",
+                    ...(relatedArtifacts.length > 0 ? relatedArtifacts.map((file) => `- ${file}`) : ["- (none)"]),
+                    "",
+                    "### Reference Locations",
+                    ...(referenceLocations.length > 0
+                        ? referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`)
+                        : ["- (none)"]),
+                    "",
+                    "### Suggested Read Order",
+                    ...suggestedReadOrder.map((item, index) => `${index + 1}. ${item}`),
+                ]),
+                guidanceSection([
+                    "- Start immediately with Suggested Read Order and execute the selected task.",
+                    "- Update markdown artifacts directly while keeping TASK/ROADMAP IDs unchanged.",
+                    "- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.",
+                ]),
+                lintSection(lintSuggestions),
+                nextCallSection(`taskContext(projectPath=\"${selected.governanceDir}\", taskId=\"${selected.task.id}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("taskContext", {
@@ -489,20 +635,34 @@ export function registerTaskTools(server) {
     }, async ({ projectPath, taskId }) => {
         if (!isValidTaskId(taskId)) {
             return {
-                ...asText(renderErrorMarkdown("taskContext", `Invalid task ID format: ${taskId}`, ["- expected format: TASK-0001", "- retry with a valid task ID"], `taskContext(projectPath=\"${projectPath}\", taskId=\"TASK-0001\")`)),
+                ...asText(renderErrorMarkdown("taskContext", `Invalid task ID format: ${taskId}`, ["expected format: TASK-0001", "retry with a valid task ID"], `taskContext(projectPath=\"${projectPath}\", taskId=\"TASK-0001\")`)),
                 isError: true,
             };
         }
         const governanceDir = await resolveGovernanceDir(projectPath);
-        const { tasksPath, tasks } = await loadTasks(governanceDir);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const taskContextHooks = await readTaskContextHooks(governanceDir);
         const task = tasks.find((item) => item.id === taskId);
         if (!task) {
             return {
-                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["- run `taskList` to discover available IDs", "- retry with an existing task ID"], `taskList(projectPath=\"${governanceDir}\")`)),
+                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${governanceDir}\")`)),
                 isError: true,
             };
         }
+        const lintSuggestions = [
+            ...collectSingleTaskLintSuggestions(task),
+            ...(await collectTaskFileLintSuggestions(governanceDir, task)),
+        ];
+        const outsideMarkerTaskIds = findTaskIdsOutsideMarkers(tasksMarkdown);
+        if (outsideMarkerTaskIds.includes(task.id)) {
+            appendLintSuggestions(lintSuggestions, [
+                {
+                    code: TASK_LINT_CODES.OUTSIDE_MARKER,
+                    message: `Current task ID appears outside marker block (${task.id}).`,
+                    fixHint: "Keep task source of truth inside marker region.",
+                },
+            ]);
+        }
         const taskLocation = (await findTextReferences(tasksPath, taskId))[0];
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
         const fileCandidates = candidateFilesFromArtifacts(artifacts);
@@ -513,45 +673,64 @@ export function registerTaskTools(server) {
             .filter((value) => typeof value === "string" && value.trim().length > 0)
             .map((value) => path.resolve(governanceDir, value));
         const hookStatus = `head=${taskContextHooks.head ? "loaded" : "missing"}, footer=${taskContextHooks.footer ? "loaded" : "missing"}`;
-        const coreMarkdown = [
-            "# taskContext",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- taskId: ${task.id}`,
-            `- title: ${task.title}`,
-            `- status: ${task.status}`,
-            `- owner: ${task.owner}`,
-            `- updatedAt: ${task.updatedAt}`,
-            `- roadmapRefs: ${task.roadmapRefs.join(", ") || "(none)"}`,
-            `- taskLocation: ${taskLocation ? `${taskLocation.filePath}#L${taskLocation.line}` : tasksPath}`,
-            `- hookStatus: ${hookStatus}`,
-            "",
-            "## Evidence",
-            "### Related Artifacts",
-            ...(relatedArtifacts.length > 0 ? relatedArtifacts.map((file) => `- ${file}`) : ["- (none)"]),
-            "",
-            "### Reference Locations",
-            ...(referenceLocations.length > 0
-                ? referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`)
-                : ["- (none)"]),
-            "",
-            "### Hook Paths",
-            ...(hookPaths.length > 0 ? hookPaths.map((item) => `- ${item}`) : ["- (none)"]),
-            "",
-            "### Suggested Read Order",
-            ...suggestedReadOrder.map((item, index) => `${index + 1}. ${item}`),
-            "",
-            "## Agent Guidance",
-            "- Read the files in Suggested Read Order.",
-            "- Verify whether current status and evidence are consistent.",
-            ...taskStatusGuidance(task),
-            "- If updates are needed, edit tasks/designs/reports markdown directly and keep TASK IDs unchanged.",
-            "- After editing, re-run `taskContext` to verify references and context consistency.",
-            "",
-            "## Next Call",
-            `- taskContext(projectPath=\"${governanceDir}\", taskId=\"${task.id}\")`,
-        ].join("\n");
+        if (!taskContextHooks.head) {
+            appendLintSuggestions(lintSuggestions, [
+                {
+                    code: TASK_LINT_CODES.CONTEXT_HOOK_HEAD_MISSING,
+                    message: `Missing ${taskContextHooks.headPath}.`,
+                    fixHint: "Add a task context head hook template if you need standardized preface.",
+                },
+            ]);
+        }
+        if (!taskContextHooks.footer) {
+            appendLintSuggestions(lintSuggestions, [
+                {
+                    code: TASK_LINT_CODES.CONTEXT_HOOK_FOOTER_MISSING,
+                    message: `Missing ${taskContextHooks.footerPath}.`,
+                    fixHint: "Add a task context footer hook template for standardized close-out checks.",
+                },
+            ]);
+        }
+        const coreMarkdown = renderToolResponseMarkdown({
+            toolName: "taskContext",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- taskId: ${task.id}`,
+                    `- title: ${task.title}`,
+                    `- status: ${task.status}`,
+                    `- owner: ${task.owner}`,
+                    `- updatedAt: ${task.updatedAt}`,
+                    `- roadmapRefs: ${task.roadmapRefs.join(", ") || "(none)"}`,
+                    `- taskLocation: ${taskLocation ? `${taskLocation.filePath}#L${taskLocation.line}` : tasksPath}`,
+                    `- hookStatus: ${hookStatus}`,
+                ]),
+                evidenceSection([
+                    "### Related Artifacts",
+                    ...(relatedArtifacts.length > 0 ? relatedArtifacts.map((file) => `- ${file}`) : ["- (none)"]),
+                    "",
+                    "### Reference Locations",
+                    ...(referenceLocations.length > 0
+                        ? referenceLocations.map((item) => `- ${item.filePath}#L${item.line}: ${item.text}`)
+                        : ["- (none)"]),
+                    "",
+                    "### Hook Paths",
+                    ...(hookPaths.length > 0 ? hookPaths.map((item) => `- ${item}`) : ["- (none)"]),
+                    "",
+                    "### Suggested Read Order",
+                    ...suggestedReadOrder.map((item, index) => `${index + 1}. ${item}`),
+                ]),
+                guidanceSection([
+                    "- Read the files in Suggested Read Order.",
+                    "- Verify whether current status and evidence are consistent.",
+                    ...taskStatusGuidance(task),
+                    "- If updates are needed, edit tasks/designs/reports markdown directly and keep TASK IDs unchanged.",
+                    "- After editing, re-run `taskContext` to verify references and context consistency.",
+                ]),
+                lintSection(lintSuggestions),
+                nextCallSection(`taskContext(projectPath=\"${governanceDir}\", taskId=\"${task.id}\")`),
+            ],
+        });
         const markdownParts = [
             taskContextHooks.head,
             coreMarkdown,