functualize-tasks 0.1.0__tar.gz

functualize_tasks-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_tasks-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: functualize-tasks
+Version: 0.1.0
+Summary: Tasks Domain SDK for functualize — task management capabilities
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-tasks
+
+> **Status: Published** — Independently installable from PyPI.
+
+Tasks Domain SDK for the functualize framework. Provides a task management capability
+that acts as a mutable planning scratchpad within job execution — create, list, update,
+delete, and link tasks with structured event emission on every mutation. Storage is
+delegated to pluggable `TaskProvider` implementations, making the capability
+backend-agnostic.
+
+## Installation
+
+```bash
+pip install functualize-tasks
+```
+
+## Quick Start
+
+```python
+from functualize_tasks import Tasks, TaskStatus, TaskLink
+
+tasks = Tasks()
+
+# Create tasks
+task_id = tasks.add("Run database migration")
+tasks.add("Deploy service", linked_to=TaskLink(kind="job", target="deploy"))
+
+# Update status
+tasks.update(task_id, status=TaskStatus.IN_PROGRESS)
+tasks.update(task_id, status=TaskStatus.DONE, notes="Migration complete")
+
+# List and filter
+pending = tasks.list(status=TaskStatus.PENDING)
+all_tasks = tasks.list(filter="service")
+```
+
+## Features
+
+- **CRUD task management** — add, list, update, delete, and link tasks with a clean method-call API
+- **Event-driven mutations** — every state change emits structured events (`tasks.task.created`, `tasks.task.updated`, `tasks.task.completed`, `tasks.task.deleted`) via a duck-typed EventBus
+- **Pluggable storage** — implement the `TaskProvider` protocol to back tasks with any persistence layer (in-memory, SQLite, remote service)
+- **Rich data model** — `TaskItem` with status enum (`PENDING`, `IN_PROGRESS`, `DONE`, `SKIPPED`, `BLOCKED`), optional `TaskLink` to associate tasks with jobs or workflow steps
+- **Testing double included** — `MockTasks` captures all operations for assertion while executing against a real in-memory provider
+- **Type-safe** — fully typed with PEP 561 `py.typed` marker for mypy/pyright support
+
+## API Reference
+
+Public classes, types, and constants exported by this plugin:
+
+### Capability
+
+- `Tasks` — Main capability class providing `add()`, `list()`, `update()`, `delete()`, and `link()` methods
+
+### Protocols
+
+- `TaskProvider` — Runtime-checkable protocol that storage backends must implement
+
+### Types
+
+- `TaskItem` — Frozen dataclass representing a task (id, title, status, linked_to, notes, creator, created_at)
+- `TaskLink` — Frozen dataclass specifying a link kind and target
+- `TaskStatus` — String enum with values: `PENDING`, `IN_PROGRESS`, `DONE`, `SKIPPED`, `BLOCKED`
+
+### Errors
+
+- `TaskNotFound` — Raised when an operation targets a non-existent task ID
+
+### Event Constants
+
+- `TASKS_CREATED` — `"tasks.task.created"`
+- `TASKS_UPDATED` — `"tasks.task.updated"`
+- `TASKS_COMPLETED` — `"tasks.task.completed"`
+- `TASKS_DELETED` — `"tasks.task.deleted"`
+
+### Testing
+
+- `MockTasks` — Operation-capturing testing double with `operations`, `adds`, `updates`, `deletes`, `links` properties
+- `MockTaskOperation` — Frozen dataclass recording a single captured method call (method, args, kwargs, result)
+
+### Metadata
+
+- `domain_metadata` — `DomainMetadata` instance describing the tasks domain SDK
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-tasks/tests/ -v
+```

functualize_tasks-0.1.0/README.md

@@ -0,0 +1,90 @@
+# functualize-tasks
+
+> **Status: Published** — Independently installable from PyPI.
+
+Tasks Domain SDK for the functualize framework. Provides a task management capability
+that acts as a mutable planning scratchpad within job execution — create, list, update,
+delete, and link tasks with structured event emission on every mutation. Storage is
+delegated to pluggable `TaskProvider` implementations, making the capability
+backend-agnostic.
+
+## Installation
+
+```bash
+pip install functualize-tasks
+```
+
+## Quick Start
+
+```python
+from functualize_tasks import Tasks, TaskStatus, TaskLink
+
+tasks = Tasks()
+
+# Create tasks
+task_id = tasks.add("Run database migration")
+tasks.add("Deploy service", linked_to=TaskLink(kind="job", target="deploy"))
+
+# Update status
+tasks.update(task_id, status=TaskStatus.IN_PROGRESS)
+tasks.update(task_id, status=TaskStatus.DONE, notes="Migration complete")
+
+# List and filter
+pending = tasks.list(status=TaskStatus.PENDING)
+all_tasks = tasks.list(filter="service")
+```
+
+## Features
+
+- **CRUD task management** — add, list, update, delete, and link tasks with a clean method-call API
+- **Event-driven mutations** — every state change emits structured events (`tasks.task.created`, `tasks.task.updated`, `tasks.task.completed`, `tasks.task.deleted`) via a duck-typed EventBus
+- **Pluggable storage** — implement the `TaskProvider` protocol to back tasks with any persistence layer (in-memory, SQLite, remote service)
+- **Rich data model** — `TaskItem` with status enum (`PENDING`, `IN_PROGRESS`, `DONE`, `SKIPPED`, `BLOCKED`), optional `TaskLink` to associate tasks with jobs or workflow steps
+- **Testing double included** — `MockTasks` captures all operations for assertion while executing against a real in-memory provider
+- **Type-safe** — fully typed with PEP 561 `py.typed` marker for mypy/pyright support
+
+## API Reference
+
+Public classes, types, and constants exported by this plugin:
+
+### Capability
+
+- `Tasks` — Main capability class providing `add()`, `list()`, `update()`, `delete()`, and `link()` methods
+
+### Protocols
+
+- `TaskProvider` — Runtime-checkable protocol that storage backends must implement
+
+### Types
+
+- `TaskItem` — Frozen dataclass representing a task (id, title, status, linked_to, notes, creator, created_at)
+- `TaskLink` — Frozen dataclass specifying a link kind and target
+- `TaskStatus` — String enum with values: `PENDING`, `IN_PROGRESS`, `DONE`, `SKIPPED`, `BLOCKED`
+
+### Errors
+
+- `TaskNotFound` — Raised when an operation targets a non-existent task ID
+
+### Event Constants
+
+- `TASKS_CREATED` — `"tasks.task.created"`
+- `TASKS_UPDATED` — `"tasks.task.updated"`
+- `TASKS_COMPLETED` — `"tasks.task.completed"`
+- `TASKS_DELETED` — `"tasks.task.deleted"`
+
+### Testing
+
+- `MockTasks` — Operation-capturing testing double with `operations`, `adds`, `updates`, `deletes`, `links` properties
+- `MockTaskOperation` — Frozen dataclass recording a single captured method call (method, args, kwargs, result)
+
+### Metadata
+
+- `domain_metadata` — `DomainMetadata` instance describing the tasks domain SDK
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-tasks/tests/ -v
+```

functualize_tasks-0.1.0/examples/README.md

@@ -0,0 +1,13 @@
+# functualize-tasks Examples
+
+The task-management domain SDK: `Tasks` capability, `TaskStatus`, and the `MockTasks` testing double (a working in-memory provider that also records operations).
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`todo/`](todo/) | A job creating and completing tasks through the `Tasks` capability |
+
+```bash
+uv run pytest plugins/functualize-tasks/examples/ -v
+```
+
+For a persistent provider, see [`functualize-tasks-local/examples/`](../../functualize-tasks-local/examples/).

functualize_tasks-0.1.0/examples/todo/test_todo.py

@@ -0,0 +1,14 @@
+"""Tests for the todo example."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from todo import plan_release
+
+
+def test_completed_task_leaves_the_list():
+    remaining = plan_release(MagicMock())
+    assert remaining == ["Run smoke tests", "Tag release"]

functualize_tasks-0.1.0/examples/todo/todo.py

@@ -0,0 +1,27 @@
+"""Track work items through the Tasks capability.
+
+Uses MockTasks (a real in-memory provider that also records operations)
+so the example is self-contained; in a real app the framework injects a
+`Tasks` capability backed by the installed provider.
+"""
+
+from functualize_tasks import TaskStatus
+from functualize_tasks.testing import MockTasks
+
+from functualize.job import RunContext
+
+
+def plan_release(rc: RunContext) -> list[str]:
+    """Create a small release checklist and complete the first item."""
+    tasks = MockTasks()
+
+    build_id = tasks.add("Build artifacts")
+    tasks.add("Run smoke tests")
+    tasks.add("Tag release")
+
+    tasks.update(build_id, status=TaskStatus.DONE)
+    rc.log("Build artifacts: done")
+
+    remaining = [t.title for t in tasks.list() if t.status is not TaskStatus.DONE]
+    rc.log(f"Remaining: {', '.join(remaining)}")
+    return remaining

functualize_tasks-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "functualize-tasks"
+version = "0.1.0"
+description = "Tasks Domain SDK for functualize — task management capabilities"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.entry-points."functualize.domains"]
+tasks = "functualize_tasks._metadata:domain_metadata"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_tasks"]

functualize_tasks-0.1.0/src/functualize_tasks/__init__.py

@@ -0,0 +1,41 @@
+"""functualize-tasks — Tasks Domain SDK.
+
+Provides the Tasks capability class, TaskProvider protocol, shared types,
+errors, event constants, and testing doubles for task management.
+"""
+
+from functualize_tasks._errors import TaskNotFoundError
+from functualize_tasks._events import (
+    TASKS_COMPLETED,
+    TASKS_CREATED,
+    TASKS_DELETED,
+    TASKS_UPDATED,
+)
+from functualize_tasks._metadata import domain_metadata
+from functualize_tasks._protocols import TaskProvider
+from functualize_tasks._tasks import Tasks
+from functualize_tasks._types import TaskItem, TaskLink, TaskStatus
+from functualize_tasks.testing._mock_tasks import MockTaskOperation, MockTasks
+
+__all__ = [
+    # Capability Class
+    "Tasks",
+    # Protocols
+    "TaskProvider",
+    # Types
+    "TaskItem",
+    "TaskLink",
+    "TaskStatus",
+    # Errors
+    "TaskNotFoundError",
+    # Event Constants
+    "TASKS_CREATED",
+    "TASKS_UPDATED",
+    "TASKS_COMPLETED",
+    "TASKS_DELETED",
+    # Testing Doubles
+    "MockTaskOperation",
+    "MockTasks",
+    # Metadata
+    "domain_metadata",
+]

functualize_tasks-0.1.0/src/functualize_tasks/_errors.py

@@ -0,0 +1,7 @@
+"""Error classes for the Tasks Domain SDK."""
+
+
+class TaskNotFoundError(Exception):
+    """Raised when a task operation targets a task_id that does not exist."""
+
+    pass

functualize_tasks-0.1.0/src/functualize_tasks/_events.py

@@ -0,0 +1,9 @@
+"""Event name constants for the Tasks Domain SDK.
+
+Events follow the {domain}.{resource}.{action} grammar.
+"""
+
+TASKS_CREATED: str = "tasks.task.created"
+TASKS_UPDATED: str = "tasks.task.updated"
+TASKS_COMPLETED: str = "tasks.task.completed"
+TASKS_DELETED: str = "tasks.task.deleted"

functualize_tasks-0.1.0/src/functualize_tasks/_metadata.py

@@ -0,0 +1,37 @@
+"""Domain metadata for the Tasks SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DomainMetadata:
+    """Self-describing metadata for a domain SDK."""
+
+    name: str
+    display_name: str
+    description: str
+    capability_class: str
+    provider_protocol: str
+    config_section: str
+    entry_point_group: str
+    events_prefix: str
+    scaffold_template: str | None = None
+    documentation_url: str | None = None
+    mock_factory: str | None = None
+
+
+domain_metadata = DomainMetadata(
+    name="tasks",
+    display_name="Tasks",
+    description="Task management and planning scratchpad",
+    capability_class="functualize_tasks.Tasks",
+    provider_protocol="functualize_tasks.TaskProvider",
+    config_section="tasks",
+    entry_point_group="functualize.tasks_providers",
+    events_prefix="tasks.",
+    scaffold_template=None,
+    documentation_url=None,
+    mock_factory="functualize_tasks.testing:MockTasks",
+)

functualize_tasks-0.1.0/src/functualize_tasks/_protocols.py

@@ -0,0 +1,89 @@
+"""Tasks domain protocol — TaskProvider.
+
+Defines the protocol interface that task implementation plugins must satisfy.
+The Tasks capability delegates all storage and retrieval operations to a
+TaskProvider implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from functualize_tasks._types import TaskItem, TaskLink, TaskStatus
+
+
+@runtime_checkable
+class TaskProvider(Protocol):
+    """Protocol for task storage implementation plugins.
+
+    Implementation plugins (e.g., local state-backed, remote service) must
+    satisfy this protocol. The Tasks capability delegates all CRUD operations
+    to the active TaskProvider.
+    """
+
+    def add(self, title: str, linked_to: TaskLink | None = None) -> str:
+        """Create a new task and return its generated unique ID.
+
+        Args:
+            title: Human-readable title for the task.
+            linked_to: Optional link associating the task with a job,
+                       workflow step, or job phase.
+
+        Returns:
+            The unique identifier of the newly created task.
+        """
+        ...
+
+    def list(
+        self, status: TaskStatus | None = None, filter: str | None = None
+    ) -> list[TaskItem]:
+        """List tasks, optionally filtered by status or title substring.
+
+        Args:
+            status: If provided, return only tasks matching this status.
+            filter: If provided, return only tasks whose title contains
+                    this substring.
+
+        Returns:
+            A list of matching TaskItem instances.
+        """
+        ...
+
+    def update(
+        self, task_id: str, status: TaskStatus | None = None, notes: str | None = None
+    ) -> None:
+        """Update a task's status and/or notes.
+
+        Args:
+            task_id: The unique identifier of the task to update.
+            status: If provided, the new status to set.
+            notes: If provided, the new notes to set.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        ...
+
+    def delete(self, task_id: str) -> None:
+        """Delete a task by its ID.
+
+        Args:
+            task_id: The unique identifier of the task to delete.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        ...
+
+    def link(self, task_id: str, linked_to: TaskLink) -> None:
+        """Associate a task with a job, workflow step, or job phase.
+
+        Args:
+            task_id: The unique identifier of the task to link.
+            linked_to: The link specifying the kind and target.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        ...

functualize_tasks-0.1.0/src/functualize_tasks/_tasks.py

@@ -0,0 +1,250 @@
+"""Tasks capability class — mutable planning scratchpad.
+
+The Tasks class provides methods to add, list, update, delete, and link
+tasks. It delegates all storage operations to a TaskProvider and emits
+structured events via a duck-typed EventBus on every mutation.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any, Protocol
+
+from functualize_tasks._errors import TaskNotFoundError
+from functualize_tasks._events import (
+    TASKS_COMPLETED,
+    TASKS_CREATED,
+    TASKS_DELETED,
+    TASKS_UPDATED,
+)
+from functualize_tasks._types import TaskItem, TaskLink, TaskStatus
+
+if TYPE_CHECKING:
+    from functualize_tasks._protocols import TaskProvider
+
+
+class _EventBus(Protocol):
+    """Duck-typed EventBus — only requires an emit method."""
+
+    def emit(self, event_name: str, **payload: Any) -> None: ...
+
+
+class _InMemoryTaskProvider:
+    """Simple in-memory TaskProvider used when no external provider is configured.
+
+    Stores tasks in a dict keyed by task ID. Suitable for ephemeral use
+    when no persistent TaskProvider plugin is installed.
+    """
+
+    def __init__(self) -> None:
+        self._tasks: dict[str, TaskItem] = {}
+
+    def add(self, title: str, linked_to: TaskLink | None = None) -> str:
+        task_id = uuid.uuid4().hex
+        task = TaskItem(
+            id=task_id,
+            title=title,
+            status=TaskStatus.PENDING,
+            linked_to=linked_to,
+        )
+        self._tasks[task_id] = task
+        return task_id
+
+    def list(
+        self, status: TaskStatus | None = None, filter: str | None = None
+    ) -> list[TaskItem]:
+        results = list(self._tasks.values())
+        if status is not None:
+            results = [t for t in results if t.status == status]
+        if filter is not None:
+            results = [t for t in results if filter in t.title]
+        return results
+
+    def get(self, task_id: str) -> TaskItem | None:
+        return self._tasks.get(task_id)
+
+    def update(
+        self, task_id: str, status: TaskStatus | None = None, notes: str | None = None
+    ) -> None:
+        task = self._tasks.get(task_id)
+        if task is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+        # Build updated task (frozen dataclass — must reconstruct)
+        updates: dict[str, Any] = {}
+        if status is not None:
+            updates["status"] = status
+        if notes is not None:
+            updates["notes"] = notes
+        if updates:
+            from dataclasses import asdict
+
+            data = asdict(task)
+            data.update(updates)
+            self._tasks[task_id] = TaskItem(**data)
+
+    def delete(self, task_id: str) -> None:
+        if task_id not in self._tasks:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+        del self._tasks[task_id]
+
+    def link(self, task_id: str, linked_to: TaskLink) -> None:
+        task = self._tasks.get(task_id)
+        if task is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+        from dataclasses import asdict
+
+        data = asdict(task)
+        data["linked_to"] = linked_to
+        self._tasks[task_id] = TaskItem(**data)
+
+
+class Tasks:
+    """Task management capability — mutable planning scratchpad.
+
+    Provides methods to create, list, update, delete, and link tasks.
+    Delegates all storage to a TaskProvider implementation and emits
+    structured events on every mutation via a duck-typed EventBus.
+
+    Args:
+        _provider: The TaskProvider implementation for persistence.
+                   If None, an in-memory provider is used.
+        _event_bus: Optional duck-typed EventBus with an emit(event_name, **payload)
+                    method. If None, events are silently discarded.
+    """
+
+    def __init__(
+        self,
+        *,
+        _provider: TaskProvider | None = None,
+        _event_bus: _EventBus | None = None,
+    ) -> None:
+        self._provider: TaskProvider = (
+            _provider if _provider is not None else _InMemoryTaskProvider()
+        )  # type: ignore[assignment]
+        self._event_bus = _event_bus
+
+    def _emit(self, event_name: str, **payload: Any) -> None:
+        """Emit an event if an event bus is available."""
+        if self._event_bus is not None:
+            self._event_bus.emit(event_name, **payload)
+
+    def add(self, title: str, *, linked_to: TaskLink | None = None) -> str:
+        """Create a new task and return its generated unique ID.
+
+        Emits a ``tasks.task.created`` event with payload containing the
+        task id, title, and linked_to.
+
+        Args:
+            title: Human-readable title for the task.
+            linked_to: Optional link associating the task with a job,
+                       workflow step, or job phase.
+
+        Returns:
+            The unique identifier of the newly created task.
+        """
+        task_id = self._provider.add(title, linked_to)
+        self._emit(
+            TASKS_CREATED,
+            task_id=task_id,
+            title=title,
+            linked_to=linked_to,
+        )
+        return task_id
+
+    def list(
+        self,
+        *,
+        status: TaskStatus | None = None,
+        filter: str | None = None,
+    ) -> list[TaskItem]:
+        """List tasks, optionally filtered by status or title substring.
+
+        Args:
+            status: If provided, return only tasks matching this status.
+            filter: If provided, return only tasks whose title contains
+                    this substring.
+
+        Returns:
+            A list of matching TaskItem instances.
+        """
+        return self._provider.list(status, filter)
+
+    def update(
+        self,
+        task_id: str,
+        *,
+        status: TaskStatus | None = None,
+        notes: str | None = None,
+    ) -> None:
+        """Update a task's status and/or notes.
+
+        Emits ``tasks.task.updated`` when the status changes, and
+        ``tasks.task.completed`` when the new status is DONE.
+
+        Args:
+            task_id: The unique identifier of the task to update.
+            status: If provided, the new status to set.
+            notes: If provided, the new notes to set.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        # Retrieve old status before updating (for event payload)
+        old_tasks = self._provider.list()
+        old_task = next((t for t in old_tasks if t.id == task_id), None)
+        if old_task is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+
+        old_status = old_task.status
+
+        self._provider.update(task_id, status, notes)
+
+        # Emit updated event when status changes
+        if status is not None and status != old_status:
+            self._emit(
+                TASKS_UPDATED,
+                task_id=task_id,
+                old_status=old_status.value,
+                new_status=status.value,
+            )
+            # Emit completed event when transitioning to DONE
+            if status == TaskStatus.DONE:
+                self._emit(TASKS_COMPLETED, task_id=task_id)
+
+    def delete(self, task_id: str) -> None:
+        """Delete a task by its ID.
+
+        Emits a ``tasks.task.deleted`` event with the task id.
+
+        Args:
+            task_id: The unique identifier of the task to delete.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        # Verify existence before delegating (requirement: raise immediately)
+        old_tasks = self._provider.list()
+        old_task = next((t for t in old_tasks if t.id == task_id), None)
+        if old_task is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+
+        self._provider.delete(task_id)
+        self._emit(TASKS_DELETED, task_id=task_id)
+
+    def link(self, task_id: str, linked_to: TaskLink) -> None:
+        """Associate a task with a job, workflow step, or job phase.
+
+        Args:
+            task_id: The unique identifier of the task to link.
+            linked_to: The link specifying the kind and target.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        # Verify existence before delegating
+        old_tasks = self._provider.list()
+        old_task = next((t for t in old_tasks if t.id == task_id), None)
+        if old_task is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found.")
+
+        self._provider.link(task_id, linked_to)

functualize_tasks-0.1.0/src/functualize_tasks/_types.py

@@ -0,0 +1,52 @@
+"""Shared types for the Tasks Domain SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class TaskStatus(StrEnum):
+    """Status of a task item."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+    SKIPPED = "skipped"
+    BLOCKED = "blocked"
+
+
+@dataclass(frozen=True)
+class TaskLink:
+    """Specifies what a task is optionally linked to.
+
+    Attributes:
+        kind: The type of link — "job", "workflow_step", or "job_phase".
+        target: The identifier of the linked entity.
+    """
+
+    kind: str  # "job" | "workflow_step" | "job_phase"
+    target: str
+
+
+@dataclass(frozen=True)
+class TaskItem:
+    """A single task with id, title, status, and optional metadata.
+
+    Attributes:
+        id: Unique identifier of the task.
+        title: Human-readable title of the task.
+        status: Current status of the task.
+        linked_to: Optional link to a job, workflow step, or job phase.
+        notes: Optional free-form notes.
+        creator: Optional identifier of who created the task.
+        created_at: Optional UNIX timestamp of creation time.
+    """
+
+    id: str
+    title: str
+    status: TaskStatus
+    linked_to: TaskLink | None = None
+    notes: str | None = None
+    creator: str | None = None
+    created_at: float | None = None

functualize_tasks-0.1.0/src/functualize_tasks/testing/__init__.py

@@ -0,0 +1,13 @@
+"""Tasks testing doubles — MockTasks.
+
+Provides a deterministic, operation-capturing testing double for the Tasks
+capability, suitable for unit and integration testing of jobs that use
+task management features.
+"""
+
+from functualize_tasks.testing._mock_tasks import MockTaskOperation, MockTasks
+
+__all__ = [
+    "MockTaskOperation",
+    "MockTasks",
+]

functualize_tasks-0.1.0/src/functualize_tasks/testing/_mock_tasks.py

@@ -0,0 +1,168 @@
+"""MockTasks — operation-capturing testing double.
+
+Provides a Tasks implementation for testing that captures all operations
+(add, list, update, delete, link) for assertion. Backed by an in-memory
+TaskProvider so operations actually execute, and all calls are recorded
+in a queryable log.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from functualize_tasks._tasks import Tasks, _InMemoryTaskProvider
+
+if TYPE_CHECKING:
+    from functualize_tasks._types import TaskItem, TaskLink, TaskStatus
+
+
+@dataclass(frozen=True)
+class MockTaskOperation:
+    """A recorded operation on the MockTasks instance.
+
+    Attributes:
+        method: The method name that was called (e.g., "add", "list").
+        args: Positional arguments as a tuple.
+        kwargs: Keyword arguments as a dict.
+        result: The return value of the operation (None for void methods).
+    """
+
+    method: str
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    result: Any = None
+
+
+class MockTasks(Tasks):
+    """Testing double for Tasks that captures all operations for assertion.
+
+    Extends the Tasks capability with a real in-memory provider so that
+    operations actually execute (add creates tasks, list returns them, etc.),
+    while also recording every call in an operations log that tests can
+    query and assert against.
+
+    Example:
+        >>> tasks = MockTasks()
+        >>> task_id = tasks.add("Write tests")
+        >>> tasks.update(task_id, status=TaskStatus.IN_PROGRESS)
+        >>> assert len(tasks.operations) == 2
+        >>> assert tasks.operations[0].method == "add"
+        >>> assert tasks.operations[1].method == "update"
+        >>> assert tasks.adds == [tasks.operations[0]]
+
+    Args:
+        None — uses an internal in-memory provider automatically.
+    """
+
+    def __init__(self) -> None:
+        provider = _InMemoryTaskProvider()
+        super().__init__(_provider=provider)
+        self._operations: list[MockTaskOperation] = []
+
+    @property
+    def operations(self) -> list[MockTaskOperation]:
+        """All recorded operations in call order."""
+        return list(self._operations)
+
+    @property
+    def adds(self) -> list[MockTaskOperation]:
+        """All recorded 'add' operations."""
+        return [op for op in self._operations if op.method == "add"]
+
+    @property
+    def lists(self) -> list[MockTaskOperation]:
+        """All recorded 'list' operations."""
+        return [op for op in self._operations if op.method == "list"]
+
+    @property
+    def updates(self) -> list[MockTaskOperation]:
+        """All recorded 'update' operations."""
+        return [op for op in self._operations if op.method == "update"]
+
+    @property
+    def deletes(self) -> list[MockTaskOperation]:
+        """All recorded 'delete' operations."""
+        return [op for op in self._operations if op.method == "delete"]
+
+    @property
+    def links(self) -> list[MockTaskOperation]:
+        """All recorded 'link' operations."""
+        return [op for op in self._operations if op.method == "link"]
+
+    def reset(self) -> None:
+        """Clear all recorded operations."""
+        self._operations.clear()
+
+    def add(self, title: str, *, linked_to: TaskLink | None = None) -> str:
+        """Create a task and record the operation."""
+        result = super().add(title, linked_to=linked_to)
+        self._operations.append(
+            MockTaskOperation(
+                method="add",
+                args=(title,),
+                kwargs={"linked_to": linked_to},
+                result=result,
+            )
+        )
+        return result
+
+    def list(
+        self,
+        *,
+        status: TaskStatus | None = None,
+        filter: str | None = None,
+    ) -> list[TaskItem]:
+        """List tasks and record the operation."""
+        result = super().list(status=status, filter=filter)
+        self._operations.append(
+            MockTaskOperation(
+                method="list",
+                args=(),
+                kwargs={"status": status, "filter": filter},
+                result=result,
+            )
+        )
+        return result
+
+    def update(
+        self,
+        task_id: str,
+        *,
+        status: TaskStatus | None = None,
+        notes: str | None = None,
+    ) -> None:
+        """Update a task and record the operation."""
+        super().update(task_id, status=status, notes=notes)
+        self._operations.append(
+            MockTaskOperation(
+                method="update",
+                args=(task_id,),
+                kwargs={"status": status, "notes": notes},
+                result=None,
+            )
+        )
+
+    def delete(self, task_id: str) -> None:
+        """Delete a task and record the operation."""
+        super().delete(task_id)
+        self._operations.append(
+            MockTaskOperation(
+                method="delete",
+                args=(task_id,),
+                kwargs={},
+                result=None,
+            )
+        )
+
+    def link(self, task_id: str, linked_to: TaskLink) -> None:
+        """Link a task and record the operation."""
+        super().link(task_id, linked_to=linked_to)
+        self._operations.append(
+            MockTaskOperation(
+                method="link",
+                args=(task_id,),
+                kwargs={"linked_to": linked_to},
+                result=None,
+            )
+        )

functualize_tasks-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared fixtures for functualize-tasks plugin tests."""

functualize_tasks-0.1.0/tests/test_plugin.py

@@ -0,0 +1,15 @@
+"""Unit tests for functualize-tasks domain SDK.
+
+Tests the task capability protocols and domain metadata.
+"""
+
+from __future__ import annotations
+
+
+class TestImports:
+    """Verify the plugin is importable."""
+
+    def test_import_package(self):
+        import functualize_tasks
+
+        assert dir(functualize_tasks)

functualize_tasks-0.1.0/tests/test_tasks_capability.py

@@ -0,0 +1,180 @@
+"""Functional tests for functualize-tasks domain SDK.
+
+Tests the Tasks capability class, status transitions, MockTasks
+operation recording, and event emission on state changes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from functualize_tasks import (
+    TASKS_COMPLETED,
+    TASKS_CREATED,
+    TASKS_DELETED,
+    TASKS_UPDATED,
+    MockTasks,
+    TaskLink,
+    TaskNotFoundError,
+    Tasks,
+    TaskStatus,
+)
+
+
+class _CapturingEventBus:
+    """Minimal event bus that records all emitted events for assertion."""
+
+    def __init__(self) -> None:
+        self.events: list[tuple[str, dict[str, Any]]] = []
+
+    def emit(self, event_name: str, **payload: Any) -> None:
+        self.events.append((event_name, payload))
+
+
+class TestTaskCreation:
+    """Tests for creating tasks via the Tasks capability."""
+
+    def test_add_returns_unique_id(self):
+        """Happy path: adding a task returns a non-empty string ID."""
+        tasks = Tasks()
+        task_id = tasks.add("Write tests")
+        assert isinstance(task_id, str)
+        assert len(task_id) > 0
+
+    def test_add_creates_task_with_pending_status(self):
+        """Happy path: a newly added task has PENDING status."""
+        tasks = Tasks()
+        task_id = tasks.add("Deploy service")
+        items = tasks.list()
+        assert len(items) == 1
+        assert items[0].id == task_id
+        assert items[0].title == "Deploy service"
+        assert items[0].status == TaskStatus.PENDING
+
+    def test_add_with_link(self):
+        """Happy path: task can be created with a link."""
+        tasks = Tasks()
+        link = TaskLink(kind="job", target="deploy")
+        tasks.add("Run migrations", linked_to=link)
+        items = tasks.list()
+        assert items[0].linked_to == link
+
+
+class TestStatusTransitions:
+    """Tests for updating task status through transitions."""
+
+    def test_transition_pending_to_in_progress(self):
+        """Happy path: task status can transition from PENDING to IN_PROGRESS."""
+        tasks = Tasks()
+        task_id = tasks.add("Build")
+        tasks.update(task_id, status=TaskStatus.IN_PROGRESS)
+        items = tasks.list()
+        assert items[0].status == TaskStatus.IN_PROGRESS
+
+    def test_transition_to_done(self):
+        """Happy path: task status can transition to DONE."""
+        tasks = Tasks()
+        task_id = tasks.add("Test")
+        tasks.update(task_id, status=TaskStatus.DONE)
+        items = tasks.list()
+        assert items[0].status == TaskStatus.DONE
+
+    def test_update_nonexistent_task_raises_task_not_found(self):
+        """Error case: updating a nonexistent task raises TaskNotFoundError."""
+        tasks = Tasks()
+        with pytest.raises(TaskNotFoundError):
+            tasks.update("nonexistent-id", status=TaskStatus.DONE)
+
+    def test_delete_nonexistent_task_raises_task_not_found(self):
+        """Error case: deleting a nonexistent task raises TaskNotFoundError."""
+        tasks = Tasks()
+        with pytest.raises(TaskNotFoundError):
+            tasks.delete("nonexistent-id")
+
+
+class TestMockTasksBehavior:
+    """Tests for the MockTasks testing double — operation recording."""
+
+    def test_mock_records_add_operations(self):
+        """Happy path: MockTasks records add operations with result."""
+        mock = MockTasks()
+        task_id = mock.add("First task")
+        assert len(mock.operations) == 1
+        assert mock.operations[0].method == "add"
+        assert mock.operations[0].args == ("First task",)
+        assert mock.operations[0].result == task_id
+
+    def test_mock_records_multiple_operation_types(self):
+        """Happy path: MockTasks records mixed operations in order."""
+        mock = MockTasks()
+        task_id = mock.add("Task A")
+        mock.list()
+        mock.update(task_id, status=TaskStatus.IN_PROGRESS)
+        assert len(mock.operations) == 3
+        assert mock.adds[0].method == "add"
+        assert mock.lists[0].method == "list"
+        assert mock.updates[0].method == "update"
+
+    def test_mock_reset_clears_operations(self):
+        """Happy path: reset clears all recorded operations."""
+        mock = MockTasks()
+        mock.add("Task B")
+        assert len(mock.operations) == 1
+        mock.reset()
+        assert len(mock.operations) == 0
+
+
+class TestEventEmission:
+    """Tests for event emission on state changes."""
+
+    def test_add_emits_created_event(self):
+        """Happy path: adding a task emits tasks.task.created."""
+        bus = _CapturingEventBus()
+        tasks = Tasks(_event_bus=bus)
+        task_id = tasks.add("Event test")
+        assert len(bus.events) == 1
+        event_name, payload = bus.events[0]
+        assert event_name == TASKS_CREATED
+        assert payload["task_id"] == task_id
+        assert payload["title"] == "Event test"
+
+    def test_update_status_emits_updated_event(self):
+        """Happy path: changing status emits tasks.task.updated."""
+        bus = _CapturingEventBus()
+        tasks = Tasks(_event_bus=bus)
+        task_id = tasks.add("Status event")
+        bus.events.clear()  # Clear the created event
+
+        tasks.update(task_id, status=TaskStatus.IN_PROGRESS)
+        assert len(bus.events) == 1
+        event_name, payload = bus.events[0]
+        assert event_name == TASKS_UPDATED
+        assert payload["task_id"] == task_id
+        assert payload["old_status"] == TaskStatus.PENDING.value
+        assert payload["new_status"] == TaskStatus.IN_PROGRESS.value
+
+    def test_transition_to_done_emits_completed_event(self):
+        """Happy path: transitioning to DONE emits both updated and completed."""
+        bus = _CapturingEventBus()
+        tasks = Tasks(_event_bus=bus)
+        task_id = tasks.add("Complete me")
+        bus.events.clear()
+
+        tasks.update(task_id, status=TaskStatus.DONE)
+        event_names = [name for name, _ in bus.events]
+        assert TASKS_UPDATED in event_names
+        assert TASKS_COMPLETED in event_names
+
+    def test_delete_emits_deleted_event(self):
+        """Happy path: deleting a task emits tasks.task.deleted."""
+        bus = _CapturingEventBus()
+        tasks = Tasks(_event_bus=bus)
+        task_id = tasks.add("Delete me")
+        bus.events.clear()
+
+        tasks.delete(task_id)
+        assert len(bus.events) == 1
+        event_name, payload = bus.events[0]
+        assert event_name == TASKS_DELETED
+        assert payload["task_id"] == task_id