@damper/mcp 0.8.3 → 0.8.5

package/dist/formatters.d.ts

@@ -4,6 +4,11 @@
  * Extracted for testability - these pure functions format API responses
  * into user-friendly text output.
  */
+export interface SelfAssessment {
+    missingContext?: string[];
+    toolIssues?: string[];
+    processGaps?: string[];
+}
 export interface StartTaskResult {
     id: string;
     status: string;
@@ -39,11 +44,16 @@ export interface AbandonTaskResult {
  * Format start_task response
  */
 export declare function formatStartTaskResponse(result: StartTaskResult): string;
+/**
+ * Format self-assessment follow-up actions.
+ * Guides the agent to propose improvements to the user with rationale.
+ */
+export declare function formatSelfAssessmentActions(assessment: SelfAssessment): string;
 /**
  * Format complete_task response
  */
-export declare function formatCompleteTaskResponse(result: CompleteTaskResult): string;
+export declare function formatCompleteTaskResponse(result: CompleteTaskResult, assessment?: SelfAssessment): string;
 /**
  * Format abandon_task response
  */
-export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean): string;
+export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean, assessment?: SelfAssessment): string;

package/dist/formatters.js

@@ -52,18 +52,67 @@ export function formatStartTaskResponse(result) {
     lines.push('1. `add_note`: "Session started: <goal>"');
     lines.push('2. Work: use `add_commit` for commits, `add_note` for decisions');
     lines.push('3. `add_note`: "Session end: <summary>"');
-    lines.push('4. `complete_task` (with `confirmations` if checklist exists) or `abandon_task`');
+    lines.push('4. `complete_task` (with `confirmations` and `selfAssessment`) or `abandon_task`');
+    return lines.join('\n');
+}
+/**
+ * Format self-assessment follow-up actions.
+ * Guides the agent to propose improvements to the user with rationale.
+ */
+export function formatSelfAssessmentActions(assessment) {
+    const lines = [];
+    const hasContent = (assessment.missingContext?.length ?? 0) > 0
+        || (assessment.toolIssues?.length ?? 0) > 0
+        || (assessment.processGaps?.length ?? 0) > 0;
+    if (!hasContent)
+        return '';
+    lines.push('\n🔍 **Self-Assessment — propose these improvements to the user:**');
+    lines.push('Explain each finding briefly and why fixing it helps future tasks. Ask for approval before acting.');
+    if (assessment.missingContext && assessment.missingContext.length > 0) {
+        lines.push('\n**Missing project context:**');
+        for (const item of assessment.missingContext) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose calling `update_context_section` to document these — explain that future agents will waste time rediscovering the same things.');
+    }
+    if (assessment.toolIssues && assessment.toolIssues.length > 0) {
+        lines.push('\n**Tool/workflow issues:**');
+        for (const item of assessment.toolIssues) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose calling `report_issue` for each — explain what went wrong and how it slowed the task.');
+    }
+    if (assessment.processGaps && assessment.processGaps.length > 0) {
+        lines.push('\n**Process/spec gaps:**');
+        for (const item of assessment.processGaps) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose `update_context_section` for doc gaps or `report_issue` for tooling problems — explain the friction it caused.');
+    }
     return lines.join('\n');
 }
 /**
  * Format complete_task response
  */
-export function formatCompleteTaskResponse(result) {
-    const lines = [`✅ Completed ${result.id}`];
-    lines.push('\n---');
-    lines.push('**📚 Before you finish:**');
-    lines.push('Did you learn something about this codebase that would help future agents?');
-    lines.push('→ Use `update_context_section` to share architecture, patterns, or gotchas.');
+export function formatCompleteTaskResponse(result, assessment) {
+    const lines = [`✅ Task ${result.id} moved to review`];
+    // Self-assessment follow-up actions (shown first if provided)
+    if (assessment) {
+        const actions = formatSelfAssessmentActions(assessment);
+        if (actions) {
+            lines.push(actions);
+        }
+    }
+    if (!assessment) {
+        // No assessment provided — nudge the agent to reflect
+        lines.push('\n---');
+        lines.push('**🔍 Before you finish — quick self-assessment:**');
+        lines.push('Reflect on your session. If you encountered any of these, propose improvements to the user:');
+        lines.push('• Missing project docs → offer to call `update_context_section`');
+        lines.push('• Confusing tools → offer to call `report_issue`');
+        lines.push('• Spec/process gaps → offer to update docs or report');
+        lines.push('Explain briefly why each improvement would help future tasks.');
+    }
     if (result.documentation) {
         if (result.documentation.affectedSections?.length > 0) {
             lines.push(`\nSections that may need updates: ${result.documentation.affectedSections.join(', ')}`);
@@ -77,11 +126,26 @@ export function formatCompleteTaskResponse(result) {
 /**
  * Format abandon_task response
  */
-export function formatAbandonTaskResponse(result, hasSummary) {
+export function formatAbandonTaskResponse(result, hasSummary, assessment) {
     const lines = [`⏸️ Abandoned ${result.id}: ${result.message}`];
     if (!hasSummary) {
         lines.push('\n⚠️ Tip: Include a summary next time for better handoff.');
     }
-    lines.push('\n💡 Task returned to "planned". Notes preserved for next agent.');
+    lines.push('\n💡 Task returned to "planned" (from in_progress or in_review). Notes preserved for next agent.');
+    // Self-assessment follow-up actions
+    if (assessment) {
+        const actions = formatSelfAssessmentActions(assessment);
+        if (actions) {
+            lines.push(actions);
+        }
+    }
+    if (!assessment) {
+        lines.push('\n---');
+        lines.push('**🔍 Before you finish — quick self-assessment:**');
+        lines.push('Something caused this task to be abandoned. Propose improvements to the user:');
+        lines.push('• Missing project docs that would have helped → offer to call `update_context_section`');
+        lines.push('• Tool issues that blocked progress → offer to call `report_issue`');
+        lines.push('Explain briefly why each fix would help the next agent pick this up smoothly.');
+    }
     return lines.join('\n');
 }

package/dist/index.js

@@ -123,7 +123,7 @@ server.registerTool('list_tasks', {
         'If total > returned tasks, paginate with offset (e.g. offset=50 for page 2).\n\n' +
         '**Recommended:** Call `get_project_context` before starting work to understand codebase patterns.',
     inputSchema: z.object({
-        status: z.enum(['planned', 'in_progress', 'done', 'all']).optional(),
+        status: z.enum(['planned', 'in_progress', 'in_review', 'done', 'all']).optional(),
         type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Filter by task type'),
         quarter: z.string().optional().describe('Filter by quarter (e.g., "Q1 2025") or "none" for unscheduled'),
         sort: z.enum(['importance', 'newest', 'votes']).optional().describe('Sort order: importance (priority+votes, default), newest, or votes'),
@@ -359,7 +359,7 @@ server.registerTool('create_task', {
         description: z.string().optional().describe('Task description (shown on public roadmap). Write for end users: 1-3 sentences on what changes and why it matters. ' +
             'No code references, file paths, or jargon.'),
         type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Task type (default: feature)'),
-        status: z.enum(['planned', 'in_progress', 'done']).optional(),
+        status: z.enum(['planned', 'in_progress', 'in_review', 'done']).optional(),
         priority: z.enum(['high', 'medium', 'low']).optional().describe('Task priority'),
         implementationPlan: z.string().optional().describe('Implementation plan (markdown, internal only - never shown publicly)'),
         isPublic: z.boolean().optional().describe('Whether task is visible on public roadmap (default: true)'),
@@ -593,6 +593,12 @@ server.registerTool('update_subtask', {
         },
     };
 });
+// Self-assessment schema for end-of-task reflection
+const SelfAssessmentSchema = z.object({
+    missingContext: z.array(z.string()).optional().describe('Project knowledge that was missing or wrong — things you had to figure out that should be documented for future agents'),
+    toolIssues: z.array(z.string()).optional().describe('MCP tools or workflow steps that were confusing, broken, or could be improved'),
+    processGaps: z.array(z.string()).optional().describe('Gaps in specs, checklists, or conventions that caused friction or mistakes'),
+});
 // Documentation reminder schema for complete_task response
 const DocumentationSchema = z.object({
     hasContext: z.boolean(),
@@ -602,10 +608,12 @@ const DocumentationSchema = z.object({
 // Tool: Complete task
 server.registerTool('complete_task', {
     title: 'Complete Task',
-    description: 'Mark task done with a brief one-line summary. Optionally log final commits at completion.\n\n' +
+    description: 'Mark task as ready for review (in_review). A human will verify and move it to done.\n\n' +
         '**Before calling:**\n' +
         '1. Push all commits\n' +
         '2. Check if project context docs need updating\n\n' +
+        '**Self-assessment:** Reflect on your session — what project knowledge was missing, what tools were confusing, ' +
+        'what process gaps caused friction. If you identify improvements, propose them to the user with a brief explanation.\n\n' +
         '**Completion checklist:** If the project has a completion checklist (shown in `start_task` response), ' +
         'you MUST pass `confirmations` — an array of `{item, evidence}` objects. Each confirmation needs the checklist item text ' +
         'and concrete evidence proving you verified it (e.g., test output, build log snippet). ' +
@@ -615,6 +623,8 @@ server.registerTool('complete_task', {
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().describe('Brief one-line summary of what was done, written for end users. Focus on the outcome, not the implementation.'),
+        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
+            'Be honest — this drives project improvements.'),
         commits: z.array(z.object({
             hash: z.string().describe('Commit hash (short or full)'),
             message: z.string().describe('Commit message'),
@@ -623,6 +633,7 @@ server.registerTool('complete_task', {
             item: z.string().describe('Checklist item text from start_task'),
             evidence: z.string().describe('Concrete proof of verification (e.g., "bun test: 47 passed, 0 failed")'),
         })).optional().describe('Completion checklist confirmations — echo back each item from the checklist shown in start_task'),
+        skipReview: z.boolean().optional().describe('Skip human review and mark task as done immediately (default: false, task goes to in_review)'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -635,11 +646,38 @@ server.registerTool('complete_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary, commits, confirmations }) => {
+}, async ({ taskId, summary, selfAssessment, commits, confirmations, skipReview }) => {
     try {
-        const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations });
+        const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations, skipReview });
+        // Log self-assessment as a structured note if provided
+        if (selfAssessment) {
+            const assessmentLines = ['Self-Assessment:'];
+            if (selfAssessment.missingContext?.length) {
+                assessmentLines.push('Missing context:');
+                for (const item of selfAssessment.missingContext)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (selfAssessment.toolIssues?.length) {
+                assessmentLines.push('Tool issues:');
+                for (const item of selfAssessment.toolIssues)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (selfAssessment.processGaps?.length) {
+                assessmentLines.push('Process gaps:');
+                for (const item of selfAssessment.processGaps)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (assessmentLines.length > 1) {
+                try {
+                    await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
+                }
+                catch {
+                    // Don't fail completion if note logging fails
+                }
+            }
+        }
         return {
-            content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
+            content: [{ type: 'text', text: formatCompleteTaskResponse(result, selfAssessment) }],
             structuredContent: result,
         };
     }
@@ -676,13 +714,17 @@ server.registerTool('complete_task', {
 // Tool: Abandon task
 server.registerTool('abandon_task', {
     title: 'Abandon Task',
-    description: 'Release lock and return task to planned status. Use when stopping work.\n\n' +
+    description: 'Release lock and return task to planned status. Works for in_progress and in_review tasks.\n\n' +
         '**Before calling:**\n' +
         '1. Push any WIP commits\n\n' +
-        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.',
+        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.\n\n' +
+        '**Self-assessment:** Especially important when abandoning — reflect on what blocked you ' +
+        'or what knowledge was missing so the next agent has a smoother experience.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().optional().describe('Handoff summary: what was done, what remains, any blockers'),
+        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
+            'Be honest — this drives project improvements.'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -695,10 +737,37 @@ server.registerTool('abandon_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary }) => {
+}, async ({ taskId, summary, selfAssessment }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/abandon`, summary ? { summary } : undefined);
+    // Log self-assessment as a structured note if provided
+    if (selfAssessment) {
+        const assessmentLines = ['Self-Assessment (abandoned):'];
+        if (selfAssessment.missingContext?.length) {
+            assessmentLines.push('Missing context:');
+            for (const item of selfAssessment.missingContext)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (selfAssessment.toolIssues?.length) {
+            assessmentLines.push('Tool issues:');
+            for (const item of selfAssessment.toolIssues)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (selfAssessment.processGaps?.length) {
+            assessmentLines.push('Process gaps:');
+            for (const item of selfAssessment.processGaps)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (assessmentLines.length > 1) {
+            try {
+                await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
+            }
+            catch {
+                // Don't fail abandonment if note logging fails
+            }
+        }
+    }
     return {
-        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary) }],
+        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary, selfAssessment) }],
         structuredContent: result,
     };
 });
@@ -748,7 +817,7 @@ server.registerTool('get_agent_instructions', {
         openWorldHint: false,
     },
 }, async ({ format = 'section' }) => {
-    const lastModified = '2026-02-08';
+    const lastModified = '2026-02-10';
     const section = `## Task Management with Damper MCP
 
 > Last updated: ${lastModified}
@@ -791,7 +860,11 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
   2. **Abandon and hand off** - Call \`abandon_task\` with a detailed handoff summary for the next agent.
 - NEVER leave a started task without completing or abandoning it
 - If the project has a **completion checklist** (shown in \`start_task\` response), you MUST pass all items as \`confirmations\` when calling \`complete_task\`
-- If you learned something about the codebase, consider updating project context
+- **Self-assessment:** Include \`selfAssessment\` when calling \`complete_task\` or \`abandon_task\`. Reflect honestly on:
+  - \`missingContext\` — What project knowledge was missing or wrong?
+  - \`toolIssues\` — Which tools or workflow steps were confusing or broken?
+  - \`processGaps\` — What specs or conventions were missing?
+  If you identify improvements, **propose them to the user** — explain briefly what you found and why fixing it helps future tasks. Only act after the user approves.
 
 ### Content Style Guide
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/mcp",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "MCP server for Damper task management",
   "author": "Damper <hello@usedamper.com>",
   "repository": {