@projitive/mcp 1.0.8 → 1.1.2

package/output/source/{tasks.js → tools/task.js}

@@ -1,14 +1,12 @@
 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, toProjectPath } from "./projitive.js";
+import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, findTextReferences } from "../common/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
+import { catchIt, TASK_LINT_CODES, renderLintSuggestions } from "../common/index.js";
+import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects, toProjectPath } from "./project.js";
 import { isValidRoadmapId } from "./roadmap.js";
+import { SUB_STATE_PHASES, BLOCKER_TYPES } from "../types.js";
 export const TASKS_START = "<!-- PROJITIVE:TASKS:START -->";
 export const TASKS_END = "<!-- PROJITIVE:TASKS:END -->";
 export const ALLOWED_STATUS = ["TODO", "IN_PROGRESS", "BLOCKED", "DONE"];
@@ -52,7 +50,7 @@ const NO_TASK_DISCOVERY_HOOK_FILE = "task_no_actionable.md";
 const DEFAULT_NO_TASK_DISCOVERY_GUIDANCE = [
     "- Check whether current code violates project guide/spec conventions; create TODO tasks for each actionable gap.",
     "- Check unit/integration test coverage and identify high-value missing tests; create TODO tasks for meaningful coverage improvements.",
-    "- Check development/testing workflow for bottlenecks (slow feedback, fragile scripts, unclear runbooks); create TODO tasks to improve reliability.",
+    "- Check development/testing workflow for bottlenecks (slow feedback, fragile scripts, unclear runbooks); create tasks to improve reliability.",
     "- Scan for TODO/FIXME/HACK comments and convert feasible items into governed TODO tasks with evidence links.",
     "- Check dependency freshness and security advisories; create tasks for safe upgrades when needed.",
     "- Check repeated manual operations that can be automated (lint/test/release checks); create tasks to reduce operational toil.",
@@ -174,11 +172,119 @@ export function rankActionableTaskCandidates(candidates) {
         return a.task.id.localeCompare(b.task.id);
     });
 }
+// Helper function to check if a line is a top-level task field
+function isTopLevelField(line) {
+    const topLevelFields = [
+        "- owner:",
+        "- summary:",
+        "- updatedAt:",
+        "- roadmapRefs:",
+        "- links:",
+        "- hooks:",
+        "- subState:",
+        "- blocker:",
+    ];
+    return topLevelFields.some((field) => line.startsWith(field));
+}
+// Parse subState nested field
+function parseSubState(lines, startIndex) {
+    const subState = {};
+    let index = startIndex + 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        // Check if we've reached the end of subState (new top-level field or new task)
+        if (trimmed.startsWith("- ") && isTopLevelField(trimmed)) {
+            break;
+        }
+        // Check if we've reached a new task
+        if (trimmed.startsWith("## TASK-")) {
+            break;
+        }
+        // Parse nested fields (2-space indentation expected)
+        if (trimmed.startsWith("- phase:")) {
+            const phase = trimmed.replace("- phase:", "").trim();
+            if (SUB_STATE_PHASES.includes(phase)) {
+                subState.phase = phase;
+            }
+        }
+        else if (trimmed.startsWith("- confidence:")) {
+            const confidenceStr = trimmed.replace("- confidence:", "").trim();
+            const confidence = Number.parseFloat(confidenceStr);
+            if (!Number.isNaN(confidence) && confidence >= 0 && confidence <= 1) {
+                subState.confidence = confidence;
+            }
+        }
+        else if (trimmed.startsWith("- estimatedCompletion:")) {
+            const estimatedCompletion = trimmed.replace("- estimatedCompletion:", "").trim();
+            if (estimatedCompletion && estimatedCompletion !== "(none)") {
+                subState.estimatedCompletion = estimatedCompletion;
+            }
+        }
+        index++;
+    }
+    return { subState, endIndex: index - 1 };
+}
+// Parse blocker nested field
+function parseBlocker(lines, startIndex) {
+    const blocker = {};
+    let index = startIndex + 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        // Check if we've reached the end of blocker (new top-level field or new task)
+        if (trimmed.startsWith("- ") && isTopLevelField(trimmed)) {
+            break;
+        }
+        // Check if we've reached a new task
+        if (trimmed.startsWith("## TASK-")) {
+            break;
+        }
+        // Parse nested fields (2-space indentation expected)
+        if (trimmed.startsWith("- type:")) {
+            const type = trimmed.replace("- type:", "").trim();
+            if (BLOCKER_TYPES.includes(type)) {
+                blocker.type = type;
+            }
+        }
+        else if (trimmed.startsWith("- description:")) {
+            const description = trimmed.replace("- description:", "").trim();
+            if (description && description !== "(none)") {
+                blocker.description = description;
+            }
+        }
+        else if (trimmed.startsWith("- blockingEntity:")) {
+            const blockingEntity = trimmed.replace("- blockingEntity:", "").trim();
+            if (blockingEntity && blockingEntity !== "(none)") {
+                blocker.blockingEntity = blockingEntity;
+            }
+        }
+        else if (trimmed.startsWith("- unblockCondition:")) {
+            const unblockCondition = trimmed.replace("- unblockCondition:", "").trim();
+            if (unblockCondition && unblockCondition !== "(none)") {
+                blocker.unblockCondition = unblockCondition;
+            }
+        }
+        else if (trimmed.startsWith("- escalationPath:")) {
+            const escalationPath = trimmed.replace("- escalationPath:", "").trim();
+            if (escalationPath && escalationPath !== "(none)") {
+                blocker.escalationPath = escalationPath;
+            }
+        }
+        index++;
+    }
+    // Validate required fields
+    if (!blocker.type || !blocker.description) {
+        // Return empty blocker if required fields are missing
+        return { blocker: { type: "external_dependency", description: "Unknown blocker" }, endIndex: index - 1 };
+    }
+    return { blocker: blocker, endIndex: index - 1 };
+}
 export function normalizeTask(task) {
     const normalizedRoadmapRefs = Array.isArray(task.roadmapRefs)
         ? task.roadmapRefs.map(String).filter((value) => isValidRoadmapId(value))
         : [];
-    return {
+    const normalized = {
         id: String(task.id),
         title: String(task.title),
         status: ALLOWED_STATUS.includes(task.status) ? task.status : "TODO",
@@ -188,6 +294,14 @@ export function normalizeTask(task) {
         links: Array.isArray(task.links) ? task.links.map(String) : [],
         roadmapRefs: Array.from(new Set(normalizedRoadmapRefs)),
     };
+    // Include optional v1.1.0 fields if present
+    if (task.subState) {
+        normalized.subState = task.subState;
+    }
+    if (task.blocker) {
+        normalized.blocker = task.blocker;
+    }
+    return normalized;
 }
 export async function parseTasksBlock(markdown) {
     const start = markdown.indexOf(TASKS_START);
@@ -224,7 +338,10 @@ export async function parseTasksBlock(markdown) {
         };
         let inLinks = false;
         let inHooks = false;
-        for (const line of lines.slice(1)) {
+        // Convert to indexed for loop to allow skipping lines when parsing subState/blocker
+        const sectionLines = lines.slice(1);
+        for (let lineIndex = 0; lineIndex < sectionLines.length; lineIndex++) {
+            const line = sectionLines[lineIndex];
             const trimmed = line.trim();
             if (!trimmed) {
                 continue;
@@ -270,6 +387,30 @@ export async function parseTasksBlock(markdown) {
                 inHooks = true;
                 continue;
             }
+            // Handle subState nested field (Spec v1.1.0)
+            if (trimmed.startsWith("- subState:")) {
+                const { subState, endIndex } = parseSubState(sectionLines, lineIndex);
+                if (Object.keys(subState).length > 0) {
+                    taskDraft.subState = subState;
+                }
+                // Skip to the end of subState parsing
+                lineIndex = endIndex;
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
+            // Handle blocker nested field (Spec v1.1.0)
+            if (trimmed.startsWith("- blocker:")) {
+                const { blocker, endIndex } = parseBlocker(sectionLines, lineIndex);
+                if (blocker.type && blocker.description) {
+                    taskDraft.blocker = blocker;
+                }
+                // Skip to the end of blocker parsing
+                lineIndex = endIndex;
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
             const nestedItem = trimmed.match(/^-\s+(.+)$/);
             if (!nestedItem) {
                 continue;
@@ -367,6 +508,60 @@ function collectTaskLintSuggestionItems(tasks, options = {}) {
             });
         }
     }
+    // ============================================================================
+    // Spec v1.1.0 - Blocker Categorization Validation
+    // ============================================================================
+    const blockedWithoutBlocker = tasks.filter((task) => task.status === "BLOCKED" && !task.blocker);
+    if (blockedWithoutBlocker.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKED_WITHOUT_BLOCKER,
+            message: `${blockedWithoutBlocker.length} BLOCKED task(s) have no blocker metadata.`,
+            fixHint: "Add structured blocker metadata with type and description.",
+        });
+    }
+    const blockerTypeInvalid = tasks.filter((task) => task.blocker && !BLOCKER_TYPES.includes(task.blocker.type));
+    if (blockerTypeInvalid.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKER_TYPE_INVALID,
+            message: `${blockerTypeInvalid.length} task(s) have invalid blocker type.`,
+            fixHint: `Use one of: ${BLOCKER_TYPES.join(", ")}.`,
+        });
+    }
+    const blockerDescriptionEmpty = tasks.filter((task) => task.blocker && !task.blocker.description?.trim());
+    if (blockerDescriptionEmpty.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKER_DESCRIPTION_EMPTY,
+            message: `${blockerDescriptionEmpty.length} task(s) have empty blocker description.`,
+            fixHint: "Provide a clear description of why the task is blocked.",
+        });
+    }
+    // ============================================================================
+    // Spec v1.1.0 - Sub-state Metadata Validation (Optional but Recommended)
+    // ============================================================================
+    const inProgressWithoutSubState = tasks.filter((task) => task.status === "IN_PROGRESS" && !task.subState);
+    if (inProgressWithoutSubState.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.IN_PROGRESS_WITHOUT_SUBSTATE,
+            message: `${inProgressWithoutSubState.length} IN_PROGRESS task(s) have no subState metadata.`,
+            fixHint: "Add optional subState metadata for better progress tracking.",
+        });
+    }
+    const subStatePhaseInvalid = tasks.filter((task) => task.subState?.phase && !SUB_STATE_PHASES.includes(task.subState.phase));
+    if (subStatePhaseInvalid.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.SUBSTATE_PHASE_INVALID,
+            message: `${subStatePhaseInvalid.length} task(s) have invalid subState phase.`,
+            fixHint: `Use one of: ${SUB_STATE_PHASES.join(", ")}.`,
+        });
+    }
+    const subStateConfidenceInvalid = tasks.filter((task) => typeof task.subState?.confidence === "number" && (task.subState.confidence < 0 || task.subState.confidence > 1));
+    if (subStateConfidenceInvalid.length > 0) {
+        suggestions.push({
+            code: TASK_LINT_CODES.SUBSTATE_CONFIDENCE_INVALID,
+            message: `${subStateConfidenceInvalid.length} task(s) have invalid confidence score.`,
+            fixHint: "Confidence must be between 0.0 and 1.0.",
+        });
+    }
     return suggestions;
 }
 export function collectTaskLintSuggestions(tasks, markdown, outsideMarkerScopeIds) {
@@ -409,6 +604,54 @@ function collectSingleTaskLintSuggestions(task) {
             fixHint: "Bind ROADMAP-xxxx where applicable.",
         });
     }
+    // ============================================================================
+    // Spec v1.1.0 - Blocker Categorization Validation (Single Task)
+    // ============================================================================
+    if (task.status === "BLOCKED" && !task.blocker) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKED_WITHOUT_BLOCKER,
+            message: "Current task is BLOCKED but has no blocker metadata.",
+            fixHint: "Add structured blocker metadata with type and description.",
+        });
+    }
+    if (task.blocker && !BLOCKER_TYPES.includes(task.blocker.type)) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKER_TYPE_INVALID,
+            message: `Current task has invalid blocker type: ${task.blocker.type}.`,
+            fixHint: `Use one of: ${BLOCKER_TYPES.join(", ")}.`,
+        });
+    }
+    if (task.blocker && !task.blocker.description?.trim()) {
+        suggestions.push({
+            code: TASK_LINT_CODES.BLOCKER_DESCRIPTION_EMPTY,
+            message: "Current task has empty blocker description.",
+            fixHint: "Provide a clear description of why the task is blocked.",
+        });
+    }
+    // ============================================================================
+    // Spec v1.1.0 - Sub-state Metadata Validation (Single Task, Optional)
+    // ============================================================================
+    if (task.status === "IN_PROGRESS" && !task.subState) {
+        suggestions.push({
+            code: TASK_LINT_CODES.IN_PROGRESS_WITHOUT_SUBSTATE,
+            message: "Current task is IN_PROGRESS but has no subState metadata.",
+            fixHint: "Add optional subState metadata for better progress tracking.",
+        });
+    }
+    if (task.subState?.phase && !SUB_STATE_PHASES.includes(task.subState.phase)) {
+        suggestions.push({
+            code: TASK_LINT_CODES.SUBSTATE_PHASE_INVALID,
+            message: `Current task has invalid subState phase: ${task.subState.phase}.`,
+            fixHint: `Use one of: ${SUB_STATE_PHASES.join(", ")}.`,
+        });
+    }
+    if (typeof task.subState?.confidence === "number" && (task.subState.confidence < 0 || task.subState.confidence > 1)) {
+        suggestions.push({
+            code: TASK_LINT_CODES.SUBSTATE_CONFIDENCE_INVALID,
+            message: `Current task has invalid confidence score: ${task.subState.confidence}.`,
+            fixHint: "Confidence must be between 0.0 and 1.0.",
+        });
+    }
     return renderLintSuggestions(suggestions);
 }
 async function collectTaskFileLintSuggestions(governanceDir, task) {
@@ -438,19 +681,48 @@ export function renderTasksMarkdown(tasks) {
         const links = task.links.length > 0
             ? ["- links:", ...task.links.map((link) => `  - ${link}`)]
             : ["- links:", "  - (none)"];
-        return [
+        const lines = [
             `## ${task.id} | ${task.status} | ${task.title}`,
             `- owner: ${task.owner || "(none)"}`,
             `- summary: ${task.summary || "(none)"}`,
             `- updatedAt: ${task.updatedAt}`,
             `- roadmapRefs: ${roadmapRefs}`,
             ...links,
-        ].join("\n");
+        ];
+        // Add subState for IN_PROGRESS tasks (Spec v1.1.0)
+        if (task.subState && task.status === "IN_PROGRESS") {
+            lines.push(`- subState:`);
+            if (task.subState.phase) {
+                lines.push(`  - phase: ${task.subState.phase}`);
+            }
+            if (typeof task.subState.confidence === "number") {
+                lines.push(`  - confidence: ${task.subState.confidence}`);
+            }
+            if (task.subState.estimatedCompletion) {
+                lines.push(`  - estimatedCompletion: ${task.subState.estimatedCompletion}`);
+            }
+        }
+        // Add blocker for BLOCKED tasks (Spec v1.1.0)
+        if (task.blocker && task.status === "BLOCKED") {
+            lines.push(`- blocker:`);
+            lines.push(`  - type: ${task.blocker.type}`);
+            lines.push(`  - description: ${task.blocker.description}`);
+            if (task.blocker.blockingEntity) {
+                lines.push(`  - blockingEntity: ${task.blocker.blockingEntity}`);
+            }
+            if (task.blocker.unblockCondition) {
+                lines.push(`  - unblockCondition: ${task.blocker.unblockCondition}`);
+            }
+            if (task.blocker.escalationPath) {
+                lines.push(`  - escalationPath: ${task.blocker.escalationPath}`);
+            }
+        }
+        return lines.join("\n");
     });
     return [
         "# Tasks",
         "",
-        "本文件由 Projitive MCP 维护，手动编辑请保持 Markdown 结构合法。",
+        "This file is maintained by Projitive MCP. If editing manually, please keep the Markdown structure valid.",
         "",
         TASKS_START,
         ...(sections.length > 0 ? sections : ["(no tasks)"]),
@@ -719,19 +991,49 @@ export function registerTaskTools(server) {
         const referenceLocations = (await Promise.all(fileCandidates.map((file) => findTextReferences(file, taskId)))).flat();
         const relatedArtifacts = Array.from(new Set(referenceLocations.map((item) => item.filePath)));
         const suggestedReadOrder = [tasksPath, ...relatedArtifacts.filter((item) => item !== tasksPath)];
+        // Build summary with subState and blocker info (v1.1.0)
+        const summaryLines = [
+            `- 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}`,
+        ];
+        // Add subState info for IN_PROGRESS tasks (v1.1.0)
+        if (task.subState && task.status === "IN_PROGRESS") {
+            summaryLines.push(`- subState:`);
+            if (task.subState.phase) {
+                summaryLines.push(`  - phase: ${task.subState.phase}`);
+            }
+            if (typeof task.subState.confidence === "number") {
+                summaryLines.push(`  - confidence: ${task.subState.confidence}`);
+            }
+            if (task.subState.estimatedCompletion) {
+                summaryLines.push(`  - estimatedCompletion: ${task.subState.estimatedCompletion}`);
+            }
+        }
+        // Add blocker info for BLOCKED tasks (v1.1.0)
+        if (task.blocker && task.status === "BLOCKED") {
+            summaryLines.push(`- blocker:`);
+            summaryLines.push(`  - type: ${task.blocker.type}`);
+            summaryLines.push(`  - description: ${task.blocker.description}`);
+            if (task.blocker.blockingEntity) {
+                summaryLines.push(`  - blockingEntity: ${task.blocker.blockingEntity}`);
+            }
+            if (task.blocker.unblockCondition) {
+                summaryLines.push(`  - unblockCondition: ${task.blocker.unblockCondition}`);
+            }
+            if (task.blocker.escalationPath) {
+                summaryLines.push(`  - escalationPath: ${task.blocker.escalationPath}`);
+            }
+        }
         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}`,
-                ]),
+                summarySection(summaryLines),
                 evidenceSection([
                     "### Related Artifacts",
                     ...(relatedArtifacts.length > 0 ? relatedArtifacts.map((file) => `- ${file}`) : ["- (none)"]),
@@ -757,4 +1059,149 @@ export function registerTaskTools(server) {
         });
         return asText(coreMarkdown);
     });
+    // taskUpdate tool - Update task fields including subState and blocker (Spec v1.1.0)
+    server.registerTool("taskUpdate", {
+        title: "Task Update",
+        description: "Update task fields including status, owner, summary, subState, and blocker metadata",
+        inputSchema: {
+            projectPath: z.string(),
+            taskId: z.string(),
+            updates: z.object({
+                status: z.enum(["TODO", "IN_PROGRESS", "BLOCKED", "DONE"]).optional(),
+                owner: z.string().optional(),
+                summary: z.string().optional(),
+                roadmapRefs: z.array(z.string()).optional(),
+                links: z.array(z.string()).optional(),
+                subState: z.object({
+                    phase: z.enum(["discovery", "design", "implementation", "testing"]).optional(),
+                    confidence: z.number().min(0).max(1).optional(),
+                    estimatedCompletion: z.string().optional(),
+                }).optional(),
+                blocker: z.object({
+                    type: z.enum(["internal_dependency", "external_dependency", "resource", "approval"]),
+                    description: z.string(),
+                    blockingEntity: z.string().optional(),
+                    unblockCondition: z.string().optional(),
+                    escalationPath: z.string().optional(),
+                }).optional(),
+            }),
+        },
+    }, async ({ projectPath, taskId, updates }) => {
+        if (!isValidTaskId(taskId)) {
+            return {
+                ...asText(renderErrorMarkdown("taskUpdate", `Invalid task ID format: ${taskId}`, ["expected format: TASK-0001", "retry with a valid task ID"], `taskUpdate(projectPath=\"${projectPath}\", taskId=\"TASK-0001\", updates={...})`)),
+                isError: true,
+            };
+        }
+        const governanceDir = await resolveGovernanceDir(projectPath);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
+        const taskIndex = tasks.findIndex((item) => item.id === taskId);
+        if (taskIndex === -1) {
+            return {
+                ...asText(renderErrorMarkdown("taskUpdate", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${toProjectPath(governanceDir)}\")`)),
+                isError: true,
+            };
+        }
+        const task = tasks[taskIndex];
+        const originalStatus = task.status;
+        // Validate status transition
+        if (updates.status && !validateTransition(originalStatus, updates.status)) {
+            return {
+                ...asText(renderErrorMarkdown("taskUpdate", `Invalid status transition: ${originalStatus} -> ${updates.status}`, ["use `validateTransition` to check allowed transitions", "provide evidence when transitioning to DONE"], `taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${taskId}\")`)),
+                isError: true,
+            };
+        }
+        // Apply updates
+        if (updates.status)
+            task.status = updates.status;
+        if (updates.owner !== undefined)
+            task.owner = updates.owner;
+        if (updates.summary !== undefined)
+            task.summary = updates.summary;
+        if (updates.roadmapRefs)
+            task.roadmapRefs = updates.roadmapRefs;
+        if (updates.links)
+            task.links = updates.links;
+        // Handle subState (Spec v1.1.0)
+        if (updates.subState !== undefined) {
+            if (updates.subState === null) {
+                delete task.subState;
+            }
+            else {
+                task.subState = {
+                    ...(task.subState || {}),
+                    ...updates.subState,
+                };
+            }
+        }
+        // Handle blocker (Spec v1.1.0)
+        if (updates.blocker !== undefined) {
+            if (updates.blocker === null) {
+                delete task.blocker;
+            }
+            else {
+                task.blocker = updates.blocker;
+            }
+        }
+        // Update updatedAt
+        task.updatedAt = nowIso();
+        // Save tasks
+        await saveTasks(tasksPath, tasks);
+        // Build response
+        const updateSummary = [
+            `- taskId: ${taskId}`,
+            `- originalStatus: ${originalStatus}`,
+            `- newStatus: ${task.status}`,
+            `- updatedAt: ${task.updatedAt}`,
+        ];
+        if (task.subState) {
+            updateSummary.push(`- subState:`);
+            if (task.subState.phase)
+                updateSummary.push(`  - phase: ${task.subState.phase}`);
+            if (typeof task.subState.confidence === "number")
+                updateSummary.push(`  - confidence: ${task.subState.confidence}`);
+            if (task.subState.estimatedCompletion)
+                updateSummary.push(`  - estimatedCompletion: ${task.subState.estimatedCompletion}`);
+        }
+        if (task.blocker) {
+            updateSummary.push(`- blocker:`);
+            updateSummary.push(`  - type: ${task.blocker.type}`);
+            updateSummary.push(`  - description: ${task.blocker.description}`);
+            if (task.blocker.blockingEntity)
+                updateSummary.push(`  - blockingEntity: ${task.blocker.blockingEntity}`);
+            if (task.blocker.unblockCondition)
+                updateSummary.push(`  - unblockCondition: ${task.blocker.unblockCondition}`);
+            if (task.blocker.escalationPath)
+                updateSummary.push(`  - escalationPath: ${task.blocker.escalationPath}`);
+        }
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskUpdate",
+            sections: [
+                summarySection(updateSummary),
+                evidenceSection([
+                    "### Updated Task",
+                    `- ${task.id} | ${task.status} | ${task.title}`,
+                    `- owner: ${task.owner || "(none)"}`,
+                    `- summary: ${task.summary || "(none)"}`,
+                    "",
+                    "### Update Details",
+                    ...(updates.status ? [`- status: ${originalStatus} → ${updates.status}`] : []),
+                    ...(updates.owner !== undefined ? [`- owner: ${updates.owner}`] : []),
+                    ...(updates.summary !== undefined ? [`- summary: ${updates.summary}`] : []),
+                    ...(updates.roadmapRefs ? [`- roadmapRefs: ${updates.roadmapRefs.join(", ")}`] : []),
+                    ...(updates.links ? [`- links: ${updates.links.join(", ")}`] : []),
+                    ...(updates.subState ? [`- subState: ${JSON.stringify(updates.subState)}`] : []),
+                    ...(updates.blocker ? [`- blocker: ${JSON.stringify(updates.blocker)}`] : []),
+                ]),
+                guidanceSection([
+                    "Task updated successfully. Run `taskContext` to verify the changes.",
+                    "If status changed to DONE, ensure evidence links are added.",
+                    "If subState or blocker were updated, verify the metadata is correct.",
+                ]),
+                lintSection([]),
+                nextCallSection(`taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${taskId}\")`),
+            ],
+        });
+        return asText(markdown);
+    });
 }