chore(07-02): bring in plan 01 prerequisites

Cherry-pick plan 01 task quality gate validation module and its
integration into IPC, API server, and automation service.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/main/api-server.ts

@@ -8,6 +8,7 @@ import { canAssignTask, canControlAgent, canManageGoal, canManageOrganization, c
 import { resolveApprovalDecision, shouldAutoApproveApproval } from "./approval-policy";
 import type { AppDatabase } from "./database";
 import { inferTaskType } from "./connector-matching";
+import { validateTaskCreation } from "./task-quality-gates";
 import { dispatchAgentMessage } from "./message-dispatch";
 import type { DesktopEvent, SectionId } from "@shared/types";
 
@@ -561,6 +562,12 @@ export class AgentApiServer {
         this.json(res, 403, { error: "Current agent is not allowed to assign this task to the selected agent" });
         return;
       }
+      const isHeartbeat = input.title.startsWith("[Heartbeat]");
+      const taskValidation = validateTaskCreation({ title: input.title, description: input.description ?? "" }, isHeartbeat);
+      if (!taskValidation.valid) {
+        this.json(res, 422, { error: taskValidation.errors.join("; ") });
+        return;
+      }
 
       let id: string;
       try {
@@ -1582,6 +1589,14 @@ export class AgentApiServer {
       if (actionItems.length > 0) {
         for (const item of actionItems) {
           if (item.title && typeof item.title === "string") {
+            const meetingTaskValidation = validateTaskCreation(
+              { title: item.title, description: item.description ?? `Action item from meeting: ${data.title ?? existing.title}` },
+              false,
+            );
+            if (!meetingTaskValidation.valid) {
+              // Log but skip invalid meeting action items rather than failing the whole request
+              continue;
+            }
             const taskId = this.db.saveTask({
               companyId: token.companyId,
               title: item.title,

src/main/automation-service.ts

@@ -8,6 +8,7 @@ import type {
   RunStatus,
 } from "@shared/types";
 import { dispatchAgentMessage } from "./message-dispatch";
+import { validateTaskCreation } from "./task-quality-gates";
 import type { NotificationOptions } from "./notification-service";
 
 /** Document types considered important enough to gate behind user review when reviewDeliverables is enabled. */
@@ -268,6 +269,12 @@ export function createAutomationService({
         const description = (config.description as string) ?? "";
         const priority = (config.priority as string) ?? "medium";
         const assigneeAgentId = (config.assigneeAgentId as string) ?? null;
+        const isHeartbeat = title.startsWith("[Heartbeat]");
+        const taskValidation = validateTaskCreation({ title, description }, isHeartbeat);
+        if (!taskValidation.valid) {
+          logger.warn(`[automation] Skipping create_task — validation failed: ${taskValidation.errors.join("; ")}`);
+          break;
+        }
         const taskId = db.saveTask({
           companyId: ctx.companyId,
           projectId: ctx.projectId ?? (config.projectId as string) ?? null,

src/main/ipc-core-work-graph-handlers.ts

@@ -11,6 +11,7 @@ import {
 import { getConnectorExecutionReadinessIssue } from "@shared/connector-policy";
 import { resolveApprovalDecision, shouldAutoApproveApproval } from "./approval-policy";
 import { fail, ok, type RegisterCoreHandlersDependencies } from "./ipc-core-common";
+import { validateTaskCreation, checkCapabilityMatch } from "./task-quality-gates";
 
 export function registerCoreWorkGraphHandlers({
   registerHandle,
@@ -314,6 +315,13 @@ export function registerCoreWorkGraphHandlers({
       return fail("INVALID_COMPANY_REFERENCE", `The selected ${invalidReference.label} does not belong to the current company.`);
     }
     const isNew = !parsed.id;
+    if (isNew) {
+      const isHeartbeat = parsed.title.startsWith("[Heartbeat]");
+      const validation = validateTaskCreation(parsed, isHeartbeat);
+      if (!validation.valid) {
+        return fail("TASK_VALIDATION_FAILED", validation.errors.join("; "));
+      }
+    }
     let previousStatus: string | null = null;
     let previousAssigneeAgentId: string | null = null;
     if (!isNew) {
@@ -355,8 +363,17 @@ export function registerCoreWorkGraphHandlers({
         wakeAgentIfPossible(parsed.assigneeAgentId, parsed.companyId, "assignment");
       }
     }
+    let capabilityWarning: string | undefined;
+    if (isNew && parsed.assigneeAgentId) {
+      try {
+        const match = checkCapabilityMatch(db, parsed.assigneeAgentId, parsed.description, parsed.companyId);
+        if (!match.matched) {
+          capabilityWarning = match.warning;
+        }
+      } catch { /* capability check is advisory — never block task creation */ }
+    }
     publishDomainChanged();
-    return ok(id);
+    return ok({ id, capabilityWarning });
   });
 
   registerHandle(IPC_CHANNELS.deleteAgent, async (_event, payload) => {

src/main/task-quality-gates.ts

@@ -0,0 +1,163 @@
+/**
+ * Task Quality Gates — pure validation functions for task creation.
+ *
+ * Called by IPC handlers, API server, and automation service to enforce
+ * minimum description quality, acceptance criteria, and capability matching.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TaskValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface CapabilityMatchResult {
+  matched: boolean;
+  warning?: string;
+}
+
+/** Minimal DB interface for capability matching — keeps the function testable with mocks.
+ *  Skill methods are optional since the skill system may not be implemented yet (graceful degradation per D-07). */
+export interface CapabilityMatchDb {
+  getAgent(id: string): { name: string; capabilities: string };
+  listAgentSkillAssignments?(id: string): string[];
+  getCompanySkill?(companyId: string, skillId: string): { name: string; description: string | null; slug: string } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MIN_DESCRIPTION_LENGTH = 50;
+
+export const ACCEPTANCE_CRITERIA_KEYWORDS: readonly string[] = [
+  "acceptance criteria",
+  "done when",
+  "success criteria",
+  "definition of done",
+  "requirements:",
+  "must:",
+  "should:",
+  "- [ ]",
+  "- [x]",
+  "deliverable:",
+  "expected outcome",
+  "exit criteria",
+];
+
+// ---------------------------------------------------------------------------
+// checkAcceptanceCriteria
+// ---------------------------------------------------------------------------
+
+export function checkAcceptanceCriteria(description: string): { hasCriteria: boolean; suggestion: string } {
+  const lower = description.toLowerCase();
+  const found = ACCEPTANCE_CRITERIA_KEYWORDS.some((kw) => lower.includes(kw));
+
+  if (found) {
+    return { hasCriteria: true, suggestion: "" };
+  }
+
+  return {
+    hasCriteria: false,
+    suggestion:
+      'Task description should include acceptance criteria. Add a "Done when:" or "Acceptance criteria:" section, or use checkbox items (- [ ]) to define success conditions.',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateTaskCreation
+// ---------------------------------------------------------------------------
+
+export function validateTaskCreation(
+  input: { title: string; description: string },
+  isHeartbeat: boolean,
+): TaskValidationResult {
+  // Heartbeat tasks bypass all validation
+  if (isHeartbeat) {
+    return { valid: true, errors: [], warnings: [] };
+  }
+
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // TASK-01: Minimum description length
+  if (input.description.length < MIN_DESCRIPTION_LENGTH) {
+    errors.push(
+      `Task description must be at least ${MIN_DESCRIPTION_LENGTH} characters (currently ${input.description.length}). Add details about what needs to be done, expected behavior, and any constraints.`,
+    );
+  }
+
+  // TASK-02: Acceptance criteria detection (only check if length passes)
+  if (input.description.length >= MIN_DESCRIPTION_LENGTH) {
+    const criteria = checkAcceptanceCriteria(input.description);
+    if (!criteria.hasCriteria) {
+      errors.push(criteria.suggestion);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// checkCapabilityMatch
+// ---------------------------------------------------------------------------
+
+/** Tokenize text into words >3 chars, same pattern as database.ts autoAssignTask */
+function tokenize(text: string): string[] {
+  return text.toLowerCase().split(/\W+/).filter((w) => w.length > 3);
+}
+
+export function checkCapabilityMatch(
+  db: CapabilityMatchDb,
+  agentId: string,
+  taskDescription: string,
+  companyId: string,
+): CapabilityMatchResult {
+  const taskWords = tokenize(taskDescription);
+
+  // Nothing to match against — task description too short/vague
+  if (taskWords.length === 0) {
+    return { matched: true };
+  }
+
+  const agent = db.getAgent(agentId);
+  const capWords = tokenize(agent.capabilities);
+  const capabilityOverlap = taskWords.filter((w) => capWords.includes(w)).length;
+
+  // Check skill assignments for additional matching (graceful degradation)
+  let skillOverlap = 0;
+  try {
+    if (db.listAgentSkillAssignments && db.getCompanySkill) {
+      const skillIds = db.listAgentSkillAssignments(agentId);
+      for (const skillId of skillIds) {
+        const skill = db.getCompanySkill(companyId, skillId);
+        if (skill) {
+          const skillWords = tokenize(`${skill.name} ${skill.description ?? ""} ${skill.slug}`);
+          skillOverlap += taskWords.filter((w) => skillWords.includes(w)).length;
+        }
+      }
+    }
+  } catch {
+    // Skill system may not be available — graceful degradation per D-07
+  }
+
+  // Direct capability or skill overlap found
+  if (capabilityOverlap > 0 || skillOverlap > 0) {
+    return { matched: true };
+  }
+
+  // No capabilities defined at all — graceful degradation (Pitfall 4)
+  if (capWords.length === 0 && skillOverlap === 0) {
+    return { matched: true };
+  }
+
+  // Agent has capabilities but no overlap — warn
+  return {
+    matched: false,
+    warning: `Agent "${agent.name}" may lack skills for this task. Their capabilities (${agent.capabilities.slice(0, 80)}...) have no overlap with the task description. Consider reassigning.`,
+  };
+}