feat(FN-1840): merge fusion/fn-1840

packages/engine/src/executor.ts

@@ -213,6 +213,10 @@ You can save and retrieve named documents for this task. Use these to store plan
 
 Documents are versioned — each write creates a new revision. Use meaningful keys like "plan", "notes", "research", "architecture".
 
+**IMPORTANT — Save your deliverables as documents:** When your task produces written output (documentation, specifications, reports, API references, README updates, guides, or any other content), you MUST save that content as a task document using \`task_document_write\`. Use a key that describes the deliverable (e.g., key="readme", key="api-docs", key="changelog"). Do this in addition to writing the file to disk — the document persists in the task for review even after the worktree is cleaned up.
+
+If the task's PROMPT.md includes a "Documentation Requirements" section listing files to update, save each updated file's final content as a task document with a matching key.
+
 ## Git discipline
 - Commit after completing each step (not after every file change)
 - Use conventional commit messages prefixed with the task ID

packages/engine/src/step-session-executor.ts

@@ -28,6 +28,7 @@ import { AgentLogger } from "./agent-logger.js";
 import { createLogger } from "./logger.js";
 import { isContextLimitError } from "./context-limit-detector.js";
 import { checkSessionError } from "./usage-limit-detector.js";
+import { createTaskDocumentWriteTool, createTaskDocumentReadTool } from "./agent-tools.js";
 
 const stepExecLog = createLogger("step-session-executor");
 
@@ -402,6 +403,15 @@ export function buildStepPrompt(
     parts.push(gitSection, "");
   }
 
+  // Add document save guidance for the last step (delivery step)
+  if (isLastStep) {
+    parts.push(
+      "",
+      "**Document your deliverables:** When this task produces written output (documentation, specifications, reports, API references, README updates, guides, or any other content), save that content as a task document using `task_document_write(key='...', content='...')`. Use a key that describes the deliverable (e.g., key=\"readme\", key=\"api-docs\"). The document persists in the task for review even after the worktree is cleaned up.",
+      "",
+    );
+  }
+
   parts.push("After completing this step, commit your changes and call task_done(). Do NOT proceed to subsequent steps.");
 
   return parts.join("\n");
@@ -769,6 +779,14 @@ export class StepSessionExecutor {
           // Get plugin tools from plugin runner if available
           const pluginTools = this.options.pluginRunner?.getPluginTools() ?? [];
 
+          // Get document tools from task store if available
+          const documentTools = this.options.store
+            ? [
+                createTaskDocumentWriteTool(this.options.store, taskDetail.id),
+                createTaskDocumentReadTool(this.options.store, taskDetail.id),
+              ]
+            : [];
+
           // Create fresh agent session for this attempt
           const createResult = await createKbAgent({
             cwd: worktreePath,
@@ -776,7 +794,7 @@ export class StepSessionExecutor {
             defaultProvider: taskDetail.modelProvider,
             defaultModelId: taskDetail.modelId,
             defaultThinkingLevel: taskDetail.thinkingLevel,
-            customTools: pluginTools,
+            customTools: [...pluginTools, ...documentTools],
             onText: (delta) => {
               agentLogger.onText(delta);
               stuckTaskDetector?.recordActivity(trackingKey);

packages/engine/src/triage.ts

@@ -112,6 +112,7 @@ Follow this structure exactly:
 ### Step {N}: Documentation & Delivery
 
 - [ ] Update relevant documentation
+- [ ] Save documentation deliverables as task documents via \`task_document_write\` (key="docs", content=...)
 - [ ] Out-of-scope findings created as new tasks via \`task_create\` tool
 
 ## Documentation Requirements
@@ -217,6 +218,7 @@ When the planning conversation produces a structured plan, save it as a document
 - Be specific — name actual files, functions, and patterns from the codebase
 - Steps should express OUTCOMES, not micro-instructions (2-5 checkboxes per step)
 - Always include a testing step and a documentation step
+- For tasks whose primary deliverable is documentation (updating docs, writing README, API references), include an explicit step or checkbox instructing the executor to save the final documentation content via \`task_document_write\`
 - Include a "Do NOT" section with project-appropriate guardrails
 - Size assessment: S (<2h), M (2-4h), L (4-8h). Split if XL (8h+)
 - Review level scoring: Blast radius (0-2), Pattern novelty (0-2), Security (0-2), Reversibility (0-2)