{"slug":"business/TASK_TAXONOMY_AUDIT","title":"Long-running Task Taxonomy — Implementation Audit","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/TASK_TAXONOMY_AUDIT.mdx","bytes":6706,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nDate: 2026-07-20\nReviewer: Hermes Agent (cron job)\n\n## 1. Executive Summary\n\nThe proposal for organizing Hermes long-running and event-driven tasks across **12 categories** is **already fully implemented** in `services/task-management/`. The existing codebase matches the architecture proposal almost exactly:\n\n- **70 built-in task templates** across all 12 proposed categories\n- **16 MCP capability handlers** registered in the Task Management MCP\n- **Scheduler Durable Object** with alarm-based (time-based) and event-based (`/enqueue`) dispatch\n- **Retry/backoff**, **Dead Letter Queue**, **metrics**, **history**, and **logs** support\n- **5-stage execution model** documented: scheduled, interval, event, conditional, continuous\n\n## 2. Category Coverage\n\n| Category | Templates | Notes |\n|----------|-----------|-------|\n| automation | 6 | Renewal risk, customer health, pipeline refresh, invoice reconciliation, SLA compliance, license utilization |\n| watch | 6 | GitHub releases, HubSpot changes, Salesforce schema, Cloudflare deployments, production incidents, documentation updates |\n| memory | 7 | Compaction, entity merge, duplicate detection, timeline rebuilding, embedding regeneration, knowledge graph updates, continuity validation |\n| ai | 7 | Account summary, opportunity forecasting, ticket clustering, meeting summarization, churn prediction, next-best-action, knowledge synthesis |\n| integration | 6 | Connector health, incremental sync, full sync, OAuth validation, schema discovery, rate-limit monitoring |\n| infrastructure | 8 | Cloudflare health, DB optimization, queue depth, cache warming, secret rotation, backup verification, storage cleanup |\n| governance | 2 | Approval reminders, policy drift detection *(fewer templates than proposal)* |\n| security | 6 | Token expiration, secret exposure, failed login analysis, API key validation, certificate expiration, suspicious activity detection |\n| workspace | 7 | Dashboard refresh, KPI updates, timeline refresh, priority computation, work assignment, daily briefings |\n| agent | 6 | Plan evaluation, retry failed, clean history, optimize workflows, capability cache, learn from outcomes |\n| marketplace | 3 | Connector version discovery, validation, metadata updates *( fewest templates)* |\n| observability | 6 | Metrics aggregation, trace analysis, error clustering, latency analysis, cost reporting, capacity forecasting |\n\n## 3. Capability Inventory\n\n### Implemented Handlers (`src/handlers.ts`)\n\n**User-facing:**\n- `tasks.create`, `tasks.get`, `tasks.list`, `tasks.update`, `tasks.delete`\n- `tasks.pause`, `tasks.resume`, `tasks.runNow`\n- `tasks.history`, `tasks.logs`, `tasks.metrics`\n- `tasks.createFromTemplate`, `tasks.listTemplates`\n- `tasks.dlq`, `tasks.cancel`, `tasks.retry`\n\n**Internal (Scheduler DO):**\n- `tasks.getDue`, `tasks.markCompleted`, `tasks.markFailed`\n\n### MCP Pool Registration Status\n\nAll capabilities are implemented, but **2 are missing from the MCP Pool manifest** (`services/mcp-pool/src/registrations.ts`):\n\n| Capability | Handler Status | MCP Pool Status |\n|------------|---------------|-----------------|\n| `tasks.createFromTemplate` | ✅ Implemented | ❌ **Missing from registration** |\n| `tasks.listTemplates` | ✅ Implemented | ❌ **Missing from registration** |\n\n## 4. Architecture Alignment\n\n### Proposed vs Existing\n\n| Proposal | Existing | Status |\n|----------|----------|--------|\n| Task Management MCP | ✅ `services/task-management/` | Implemented |\n| Scheduler | ✅ Scheduler DO (`scheduler-do.ts`) | Implemented |\n| Event Watches | ✅ `/enqueue` endpoint, Signal Engine pattern | Implemented |\n| Workflow Engine | ✅ Scheduler DO dispatch | Implemented |\n| Retry Manager | ✅ Exponential/linear/fixed backoff | Implemented |\n| Notifications | ❌ Not explicitly implemented | Gap |\n| History | ✅ `task_execution_log` table | Implemented |\n| Dead Letter Queue | ✅ `ops-dlq` Queue binding | Implemented |\n| Metrics | ✅ `tasks.metrics` handler | Implemented |\n\n### Execution Models\n\n| Model | Proposal | Implementation |\n|-------|----------|----------------|\n| Time-based (cron) | ✅ `0 */6 * * *` | ✅ Cron parser + DO alarm scheduling |\n| Time-based (interval) | ✅ `every 5m` | ✅ `nextCronRun` + interval handling |\n| Event-based | ✅ `github.push` | ✅ `/enqueue` fetch handler |\n| Conditional | ✅ capability-gated | ✅ `conditionJson` field + TypeScript types |\n| Continuous | ✅ poll-based | ✅ `pollIntervalSeconds` + Scheduler DO alarm |\n\n## 5. Data Model\n\n**D1 Tables:**\n- `scheduled_tasks` — task registry with trigger types, retry policies, governance\n- `task_execution_log` — append-only execution history\n- `task_templates` — built-in template catalog (migration 002)\n\n**Indexes:**\n- `idx_st_tenant_enabled`, `idx_st_next_run`, `idx_st_capability`, `idx_st_trigger_type`, `idx_st_owner`\n- `idx_tel_task_id`, `idx_tel_tenant`, `idx_tel_status`\n- `idx_tt_category`, `idx_tt_id`\n\n## 6. Test Coverage\n\n| File | Coverage | Notes |\n|------|----------|-------|\n| `cron.test.ts` | ✅ Cron parsing & next-run calculation | 5 tests |\n| `watch.test.ts` | ✅ Event trigger creation | 1 test |\n| `metrics.test.ts` | ✅ Aggregation logic | 1 test |\n| `task-management.test.ts` | ✅ Capability export smoke test | 1 test |\n\n**Gap:** Integration tests for Scheduler DO dispatch, retry logic, DLQ routing, and capability invocation are absent.\n\n## 7. Gaps & Recommendations\n\n### High Priority\n1. **Register `tasks.createFromTemplate` and `tasks.listTemplates` in MCP Pool manifest** so they are discoverable by external callers.\n2. **Add Scheduler DO integration tests** covering alarm firing, event enqueue, retry backoff, and DLQ routing.\n\n### Low Priority\n3. **Add `[crons]` to `wrangler.toml` if platform-level cron triggers are needed** (currently the Scheduler DO uses DO alarms, which is the preferred dynamic-scheduling pattern — this is more of an architectural decision point than a bug).\n4. **Remove unused `TASK_QUEUE` binding** from `scheduler-do.ts` types (line 26) — it is declared but never used.\n5. **Update SQL migration 002 comment** to reflect the actual 12 categories in `TemplateCategory` rather than the stale `personal/customer-success/operations` list.\n\n## 8. Conclusion\n\nThe long-running task taxonomy proposed by the user is already the **canonical implementation** in this codebase. The architecturally-sound decision to use a Scheduler Durable Object (rather than Cloudflare Cron Triggers directly) enables the dynamic, multi-tenant, multi-trigger scheduling that the proposal requires. The remaining work is **completeness and test polish**, not core architecture.\n"}