@task-mcp/shared 1.0.26 → 1.0.28

package/src/schemas/task.ts

@@ -125,6 +125,54 @@ export const TechStackAnalysis = z.object({
 });
 export type TechStackAnalysis = z.infer<typeof TechStackAnalysis>;
 
+// Quality level for work context
+export const QualityLevel = z.enum(["quick", "standard", "thorough", "exhaustive"]);
+export type QualityLevel = z.infer<typeof QualityLevel>;
+
+// Work patterns for task execution
+export const WorkPatterns = z.object({
+  parallelExecution: z.boolean().optional(), // Use parallel agents
+  fileByFileAnalysis: z.boolean().optional(), // Analyze each file individually
+  testFirst: z.boolean().optional(), // Write tests before implementation
+  reviewRequired: z.boolean().optional(), // Require review before completion
+});
+export type WorkPatterns = z.infer<typeof WorkPatterns>;
+
+/**
+ * WorkContext - Captures the "how" of task execution
+ *
+ * When a session is interrupted and resumed, this context enables
+ * Claude to continue with the same quality level and methodology.
+ *
+ * @example
+ * ```typescript
+ * workContext: {
+ *   intent: "Migrate API layer to service pattern",
+ *   methodology: "Analyze each file → Review types → Extract service → Test",
+ *   qualityLevel: "thorough",
+ *   patterns: { fileByFileAnalysis: true, reviewRequired: true },
+ *   acceptanceCriteria: ["All tests pass", "No type errors"]
+ * }
+ * ```
+ */
+export const WorkContext = z.object({
+  // Work intent - why this task exists
+  intent: z.string().optional(),
+
+  // Methodology - how to approach the work
+  methodology: z.string().optional(),
+
+  // Quality level - how thorough the work should be
+  qualityLevel: QualityLevel.optional(),
+
+  // Work patterns - specific execution patterns
+  patterns: WorkPatterns.optional(),
+
+  // Acceptance criteria - conditions for completion
+  acceptanceCriteria: z.array(z.string()).optional(),
+});
+export type WorkContext = z.infer<typeof WorkContext>;
+
 // Core Task schema
 export const Task = z.object({
   id: z.string(),
@@ -170,6 +218,9 @@ export const Task = z.object({
   // Analysis fields (populated by Claude)
   complexity: ComplexityAnalysis.optional(),
   techStack: TechStackAnalysis.optional(),
+
+  // Work context - captures execution methodology for session resumption
+  workContext: WorkContext.optional(),
 });
 export type Task = z.infer<typeof Task>;
 
@@ -188,6 +239,8 @@ export const TaskCreateInput = z.object({
   tags: z.array(z.string()).optional(),
   sortOrder: z.number().optional(),
   recurrence: Recurrence.optional(),
+  // Work context for session resumption
+  workContext: WorkContext.optional(),
 });
 export type TaskCreateInput = z.infer<typeof TaskCreateInput>;
 
@@ -211,5 +264,7 @@ export const TaskUpdateInput = z.object({
   // Analysis fields
   complexity: ComplexityAnalysis.optional(),
   techStack: TechStackAnalysis.optional(),
+  // Work context for session resumption
+  workContext: WorkContext.optional(),
 });
 export type TaskUpdateInput = z.infer<typeof TaskUpdateInput>;

package/src/schemas/work-context.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "bun:test";
+import { WorkContext, WorkPatterns, QualityLevel } from "./task.js";
+
+describe("WorkContext Schema", () => {
+  describe("QualityLevel", () => {
+    it("should accept valid quality levels", () => {
+      expect(() => QualityLevel.parse("quick")).not.toThrow();
+      expect(() => QualityLevel.parse("standard")).not.toThrow();
+      expect(() => QualityLevel.parse("thorough")).not.toThrow();
+      expect(() => QualityLevel.parse("exhaustive")).not.toThrow();
+    });
+
+    it("should reject invalid quality levels", () => {
+      expect(() => QualityLevel.parse("fast")).toThrow();
+      expect(() => QualityLevel.parse("slow")).toThrow();
+      expect(() => QualityLevel.parse("normal")).toThrow();
+    });
+  });
+
+  describe("WorkPatterns", () => {
+    it("should validate work patterns with all fields", () => {
+      const patterns = {
+        parallelExecution: true,
+        fileByFileAnalysis: true,
+        testFirst: true,
+        reviewRequired: true,
+      };
+
+      expect(() => WorkPatterns.parse(patterns)).not.toThrow();
+      const parsed = WorkPatterns.parse(patterns);
+      expect(parsed.parallelExecution).toBe(true);
+      expect(parsed.fileByFileAnalysis).toBe(true);
+      expect(parsed.testFirst).toBe(true);
+      expect(parsed.reviewRequired).toBe(true);
+    });
+
+    it("should validate work patterns with partial fields", () => {
+      const patterns = {
+        testFirst: true,
+      };
+
+      expect(() => WorkPatterns.parse(patterns)).not.toThrow();
+      const parsed = WorkPatterns.parse(patterns);
+      expect(parsed.testFirst).toBe(true);
+      expect(parsed.parallelExecution).toBeUndefined();
+    });
+
+    it("should validate empty work patterns", () => {
+      expect(() => WorkPatterns.parse({})).not.toThrow();
+    });
+  });
+
+  describe("WorkContext", () => {
+    it("should validate full work context", () => {
+      const context = {
+        intent: "Migrate API layer to service pattern",
+        methodology: "Analyze each file -> Review types -> Extract service -> Test",
+        qualityLevel: "thorough" as const,
+        patterns: {
+          fileByFileAnalysis: true,
+          reviewRequired: true,
+        },
+        acceptanceCriteria: ["All tests pass", "No type errors", "100% coverage"],
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.intent).toBe("Migrate API layer to service pattern");
+      expect(parsed.methodology).toContain("Analyze each file");
+      expect(parsed.qualityLevel).toBe("thorough");
+      expect(parsed.patterns?.fileByFileAnalysis).toBe(true);
+      expect(parsed.acceptanceCriteria).toHaveLength(3);
+    });
+
+    it("should validate work context with only intent", () => {
+      const context = {
+        intent: "Quick bug fix",
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.intent).toBe("Quick bug fix");
+      expect(parsed.methodology).toBeUndefined();
+    });
+
+    it("should validate work context with only quality level", () => {
+      const context = {
+        qualityLevel: "quick" as const,
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.qualityLevel).toBe("quick");
+    });
+
+    it("should validate work context with only patterns", () => {
+      const context = {
+        patterns: {
+          parallelExecution: true,
+          testFirst: true,
+        },
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.patterns?.parallelExecution).toBe(true);
+      expect(parsed.patterns?.testFirst).toBe(true);
+    });
+
+    it("should validate work context with only acceptance criteria", () => {
+      const context = {
+        acceptanceCriteria: ["No critical bugs", "All edge cases handled"],
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.acceptanceCriteria).toHaveLength(2);
+      expect(parsed.acceptanceCriteria?.[0]).toBe("No critical bugs");
+    });
+
+    it("should validate empty work context", () => {
+      expect(() => WorkContext.parse({})).not.toThrow();
+    });
+
+    it("should reject invalid quality level in work context", () => {
+      const context = {
+        qualityLevel: "invalid" as const,
+      };
+
+      expect(() => WorkContext.parse(context)).toThrow();
+    });
+
+    it("should allow empty acceptance criteria array", () => {
+      const context = {
+        acceptanceCriteria: [],
+      };
+
+      expect(() => WorkContext.parse(context)).not.toThrow();
+      const parsed = WorkContext.parse(context);
+      expect(parsed.acceptanceCriteria).toHaveLength(0);
+    });
+  });
+
+  describe("WorkContext use cases", () => {
+    it("should represent thorough code review context", () => {
+      const codeReviewContext = {
+        intent: "Review PR for security vulnerabilities and code quality",
+        methodology: "Check security -> Review performance -> Verify tests -> Check style",
+        qualityLevel: "thorough" as const,
+        patterns: {
+          fileByFileAnalysis: true,
+          reviewRequired: true,
+        },
+        acceptanceCriteria: [
+          "No security vulnerabilities",
+          "All tests pass",
+          "Code follows style guide",
+        ],
+      };
+
+      const parsed = WorkContext.parse(codeReviewContext);
+      expect(parsed.qualityLevel).toBe("thorough");
+      expect(parsed.patterns?.fileByFileAnalysis).toBe(true);
+    });
+
+    it("should represent quick bug fix context", () => {
+      const bugFixContext = {
+        intent: "Fix null pointer exception in user service",
+        qualityLevel: "quick" as const,
+        acceptanceCriteria: ["Bug no longer occurs", "Existing tests pass"],
+      };
+
+      const parsed = WorkContext.parse(bugFixContext);
+      expect(parsed.qualityLevel).toBe("quick");
+      expect(parsed.methodology).toBeUndefined();
+      expect(parsed.patterns).toBeUndefined();
+    });
+
+    it("should represent exhaustive security audit context", () => {
+      const securityAuditContext = {
+        intent: "Comprehensive security audit of authentication system",
+        methodology: "OWASP Top 10 -> Dependency scan -> Penetration test -> Report",
+        qualityLevel: "exhaustive" as const,
+        patterns: {
+          parallelExecution: true,
+          fileByFileAnalysis: true,
+          reviewRequired: true,
+        },
+        acceptanceCriteria: [
+          "No critical vulnerabilities",
+          "No high vulnerabilities",
+          "All dependencies up to date",
+          "Security report generated",
+          "Remediation plan created",
+        ],
+      };
+
+      const parsed = WorkContext.parse(securityAuditContext);
+      expect(parsed.qualityLevel).toBe("exhaustive");
+      expect(parsed.patterns?.parallelExecution).toBe(true);
+      expect(parsed.acceptanceCriteria).toHaveLength(5);
+    });
+
+    it("should represent TDD development context", () => {
+      const tddContext = {
+        intent: "Implement new feature using test-driven development",
+        methodology: "Write failing test -> Implement -> Refactor -> Repeat",
+        qualityLevel: "standard" as const,
+        patterns: {
+          testFirst: true,
+          reviewRequired: true,
+        },
+        acceptanceCriteria: ["All tests pass", "Coverage > 80%"],
+      };
+
+      const parsed = WorkContext.parse(tddContext);
+      expect(parsed.patterns?.testFirst).toBe(true);
+      expect(parsed.qualityLevel).toBe("standard");
+    });
+  });
+});

package/src/utils/natural-language.test.ts

@@ -200,6 +200,62 @@ describe("parseTaskInput", () => {
       expect(() => parseTaskInput("   ")).toThrow(InputValidationError);
     });
   });
+
+  describe("workContext parsing", () => {
+    test("parses intent with :: separator", () => {
+      const result = parseTaskInput("API 리팩토링 :: 서비스 레이어 분리 !high");
+      expect(result.title).toBe("API 리팩토링");
+      expect(result.workContext?.intent).toBe("서비스 레이어 분리");
+      expect(result.priority).toBe("high");
+    });
+
+    test("parses qualityLevel with @thorough", () => {
+      const result = parseTaskInput("코드 리뷰 @thorough #backend");
+      expect(result.title).toBe("코드 리뷰");
+      expect(result.workContext?.qualityLevel).toBe("thorough");
+      expect(result.tags).toEqual(["backend"]);
+    });
+
+    test("parses qualityLevel with @quick", () => {
+      const result = parseTaskInput("버그 수정 @quick !high");
+      expect(result.title).toBe("버그 수정");
+      expect(result.workContext?.qualityLevel).toBe("quick");
+    });
+
+    test("parses Korean qualityLevel @꼼꼼히", () => {
+      const result = parseTaskInput("보안 점검 @꼼꼼히");
+      expect(result.workContext?.qualityLevel).toBe("thorough");
+    });
+
+    test("parses acceptanceCriteria with done:", () => {
+      const result = parseTaskInput("테스트 작성 done:테스트통과,커버리지80%");
+      expect(result.title).toBe("테스트 작성");
+      expect(result.workContext?.acceptanceCriteria).toEqual(["테스트통과", "커버리지80%"]);
+    });
+
+    test("parses full workContext", () => {
+      const result = parseTaskInput(
+        "API 마이그레이션 :: 서비스 분리 @thorough done:테스트통과,타입에러없음 !high #backend"
+      );
+      expect(result.title).toBe("API 마이그레이션");
+      expect(result.workContext?.intent).toBe("서비스 분리");
+      expect(result.workContext?.qualityLevel).toBe("thorough");
+      expect(result.workContext?.acceptanceCriteria).toEqual(["테스트통과", "타입에러없음"]);
+      expect(result.priority).toBe("high");
+      expect(result.tags).toEqual(["backend"]);
+    });
+
+    test("distinguishes qualityLevel from regular context", () => {
+      const result = parseTaskInput("작업 @thorough @focus @review");
+      expect(result.workContext?.qualityLevel).toBe("thorough");
+      expect(result.contexts).toEqual(["focus", "review"]);
+    });
+
+    test("no workContext when not specified", () => {
+      const result = parseTaskInput("간단한 작업 !medium #task");
+      expect(result.workContext).toBeUndefined();
+    });
+  });
 });
 
 describe("parseInboxInput", () => {

package/src/utils/natural-language.ts

@@ -1,7 +1,25 @@
-import type { Priority, TaskCreateInput } from "../schemas/task.js";
+import type { Priority, TaskCreateInput, QualityLevel, WorkContext } from "../schemas/task.js";
 import type { InboxCreateInput } from "../schemas/inbox.js";
 import { parseRelativeDate, formatDate } from "./date.js";
 
+/**
+ * Quality level keywords for workContext parsing
+ */
+const QUALITY_LEVEL_KEYWORDS: Record<string, QualityLevel> = {
+  quick: "quick",
+  빠르게: "quick",
+  간단히: "quick",
+  standard: "standard",
+  표준: "standard",
+  기본: "standard",
+  thorough: "thorough",
+  꼼꼼히: "thorough",
+  철저히: "thorough",
+  exhaustive: "exhaustive",
+  완전히: "exhaustive",
+  철저하게: "exhaustive",
+};
+
 /**
  * Maximum allowed input length for natural language parsing.
  * Prevents DoS attacks from extremely long input strings.
@@ -296,11 +314,45 @@ export function parseTaskInput(input: string): TaskCreateInput {
   validateInputLength(input);
   let remaining = input.trim();
   const result: TaskCreateInput = { title: "" };
+  const workContext: Partial<WorkContext> = {};
+
+  // Extract intent first (:: separator)
+  // Format: "Task title :: intent description"
+  const intentMatch = remaining.match(/\s*::\s*(.+?)(?=\s+[@#!~^]|$)/);
+  if (intentMatch) {
+    workContext.intent = intentMatch[1]!.trim();
+    remaining = remaining.replace(intentMatch[0], " ").trim();
+  }
+
+  // Extract acceptanceCriteria (done:xxx,yyy or done:xxx)
+  // Format: "done:criterion1,criterion2" or "done:single criterion"
+  const doneMatch = remaining.match(/done:([^\s@#!~^]+(?:,[^\s@#!~^]+)*)/i);
+  if (doneMatch) {
+    workContext.acceptanceCriteria = doneMatch[1]!.split(",").map((c) => c.trim());
+    remaining = remaining.replace(doneMatch[0], " ").trim();
+  }
+
+  // Extract qualityLevel (@quick, @thorough, etc.) - before contexts
+  // These are reserved keywords that become qualityLevel, not contexts
+  const qualityLevelKeywords = Object.keys(QUALITY_LEVEL_KEYWORDS);
+  const qualityPattern = new RegExp(`@(${qualityLevelKeywords.join("|")})(?=\\s|$)`, "iu");
+  const qualityMatch = remaining.match(qualityPattern);
+  if (qualityMatch) {
+    const keyword = qualityMatch[1]!.toLowerCase();
+    workContext.qualityLevel = QUALITY_LEVEL_KEYWORDS[keyword];
+    remaining = remaining.replace(qualityMatch[0], " ").trim();
+  }
 
-  // Extract contexts first (@focus, @review, @집중) - task-specific
+  // Extract contexts (@focus, @review, @집중) - task-specific
+  // Excluding qualityLevel keywords that were already processed
   const contextMatches = remaining.match(/@([\p{L}\p{N}_]+)/gu);
   if (contextMatches) {
-    result.contexts = contextMatches.map((m) => m.slice(1));
+    const contexts = contextMatches
+      .map((m) => m.slice(1))
+      .filter((c) => !QUALITY_LEVEL_KEYWORDS[c.toLowerCase()]);
+    if (contexts.length > 0) {
+      result.contexts = contexts;
+    }
     for (const match of contextMatches) {
       remaining = remaining.replace(match, "").trim();
     }
@@ -362,6 +414,11 @@ export function parseTaskInput(input: string): TaskCreateInput {
     );
   }
 
+  // Add workContext if any fields were extracted
+  if (Object.keys(workContext).length > 0) {
+    result.workContext = workContext as WorkContext;
+  }
+
   return result;
 }
 

package/src/utils/projection.ts

@@ -29,25 +29,46 @@ function assertNever(value: never): never {
  */
 export function formatTask(task: Task, format: ResponseFormat): TaskSummary | TaskPreview | Task {
   switch (format) {
-    case "concise":
-      return {
+    case "concise": {
+      const summary: TaskSummary = {
         id: task.id,
         title: task.title,
         status: task.status,
         priority: task.priority,
       };
+      // Include intent + qualityLevel for quick context understanding
+      if (task.workContext?.intent) {
+        summary.intent = task.workContext.intent;
+      }
+      if (task.workContext?.qualityLevel) {
+        summary.quality = task.workContext.qualityLevel;
+      }
+      return summary;
+    }
 
-    case "standard":
-      return {
+    case "standard": {
+      // Build result with only defined optional fields
+      const result: TaskPreview = {
         id: task.id,
         title: task.title,
         status: task.status,
         priority: task.priority,
-        dueDate: task.dueDate,
-        tags: task.tags,
-        contexts: task.contexts,
-        parentId: task.parentId,
+        ...(task.dueDate !== undefined && { dueDate: task.dueDate }),
+        ...(task.tags !== undefined && { tags: task.tags }),
+        ...(task.contexts !== undefined && { contexts: task.contexts }),
+        ...(task.parentId != null && { parentId: task.parentId }),
       };
+      // Include workContext summary if present (only defined fields)
+      if (task.workContext) {
+        const wc = task.workContext;
+        result.workContext = {
+          ...(wc.intent !== undefined && { intent: wc.intent }),
+          ...(wc.methodology !== undefined && { methodology: wc.methodology }),
+          ...(wc.qualityLevel !== undefined && { qualityLevel: wc.qualityLevel }),
+        };
+      }
+      return result;
+    }
 
     case "detailed":
       return task;