feat(core): lifecycle engine, workflow + state classes, Spike seed + CI

Slice 1, PR 1 of 4 — the core contracts the rest of the slice builds on.

- panopticon.core.models: domain types (Task, Repo[+git_url], HistoryEntry, Turn,
  Mode, Status, Responsibility) — pure data, no clock, no I/O.
- panopticon.core.state: states as classes — State (non-terminal, inherits a DROPPED
  transition) / TerminalState, with built-in Complete/Dropped terminals.
- panopticon.core.workflow: the Workflow interface owns the whole state machine —
  nested State classes discovered and their string/class transitions resolved +
  validated at instantiation; queries (transitions, can_transition, is_terminal, …);
  and task lifecycle (start_task, apply_transition with turn tracking and per-
  responsibility gating). Dropping is the universal escape hatch and bypasses gating.
- panopticon.workflows.Spike: the minimal seed workflow.
- Golden tests for resolution/gating; a determinism test forbidding LLM imports.
- GitHub Actions CI: uv sync, mypy, pytest.

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

Author: tildesrc

.gitignore

@@ -1,2 +1,13 @@
 # Editor / Obsidian vault metadata
 .obsidian/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/

README.md

@@ -0,0 +1,32 @@
+# panopticon
+
+Orchestrate multiple coding agents across isolated tasks and **configurable workflows**.
+
+A ground-up rewrite of the [cloude-cade](https://github.com/tildesrc/cloude-cade)
+prototype. The design lives on the [`design-docs`](../../tree/design-docs) branch
+(goals, parity analysis, architecture, roadmap, and ADRs).
+
+## Architecture in one paragraph
+
+A deterministic control plane (the **task service**) owns task state and drives
+per-workflow state machines; a per-machine **runner** spawns task containers and host
+tmux sessions; a **terminal controller** runs the dashboard. **All LLM calls happen
+inside task containers** — the control plane, runner, and dashboard never call a model.
+See the `design-docs` branch for the full picture.
+
+## Status
+
+Early development. Building Milestone 1 in vertical slices (see the roadmap). This slice
+lands the core contracts:
+
+- `panopticon.core` — domain models, the workflow port (`Workflow` ABC), and the
+  deterministic lifecycle engine (state machine, turn tracking, responsibility gating).
+- `panopticon.workflows.FreeFormWorkflow` — the minimal seed workflow.
+
+## Development
+
+```sh
+uv sync              # create the venv and install dev deps
+uv run pytest        # run tests
+uv run mypy -p panopticon   # type-check
+```

pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "panopticon"
+version = "0.0.1"
+description = "Orchestrate multiple coding agents across isolated tasks and configurable workflows."
+requires-python = ">=3.11"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/panopticon"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+namespace_packages = true
+explicit_package_bases = true

src/panopticon/__init__.py

@@ -0,0 +1,3 @@
+"""panopticon — keep an eye on your agents."""
+
+__version__ = "0.0.1"

src/panopticon/core/__init__.py

@@ -0,0 +1,48 @@
+"""Core domain: models, state classes, and the workflow interface (the state machine).
+
+Nothing in this package performs I/O or calls an LLM (enforced by a determinism test).
+"""
+
+from panopticon.core.models import (
+    HistoryEntry,
+    Mode,
+    Repo,
+    Responsibility,
+    Status,
+    Task,
+    Turn,
+)
+from panopticon.core.state import (
+    BaseState,
+    Complete,
+    Dropped,
+    State,
+    TerminalState,
+)
+from panopticon.core.workflow import (
+    IllegalTransition,
+    InvalidWorkflow,
+    ResolvedState,
+    ResponsibilitiesNotMet,
+    Workflow,
+)
+
+__all__ = [
+    "BaseState",
+    "Complete",
+    "Dropped",
+    "HistoryEntry",
+    "IllegalTransition",
+    "InvalidWorkflow",
+    "Mode",
+    "Repo",
+    "ResolvedState",
+    "ResponsibilitiesNotMet",
+    "Responsibility",
+    "State",
+    "Status",
+    "Task",
+    "TerminalState",
+    "Turn",
+    "Workflow",
+]

src/panopticon/core/models.py

@@ -0,0 +1,96 @@
+"""Core domain models — pure data, no I/O, no LLM.
+
+These types are the vocabulary the whole system shares. They deliberately carry no
+behavior beyond holding state; the rules live in :class:`panopticon.core.workflow.Workflow`, and
+the state classes live in :mod:`panopticon.core.state`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Turn(str, Enum):
+    """Who currently holds the turn — who must act next before anything else happens."""
+
+    USER = "user"
+    AGENT = "agent"
+
+
+class Mode(str, Enum):
+    """Per-state classification a workflow supplies; the workflow derives the turn from it."""
+
+    FOREGROUND = "foreground"  # user-driven — the turn goes to the user on entry
+    BACKGROUND = "background"  # agent-driven — the turn goes to the agent on entry
+
+
+class Status(str, Enum):
+    """Resolution status of a single responsibility."""
+
+    PENDING = "pending"  # not yet resolved — blocks handing the turn back
+    MET = "met"
+    FAILED = "failed"  # could not be satisfied; requires a comment
+
+
+@dataclass(frozen=True)
+class Responsibility:
+    """An agent obligation for a state.
+
+    The workflow supplies these as *definitions* (``status`` ``PENDING``, no comment). The
+    agent resolves each to ``MET`` or ``FAILED`` before handing the turn back; a ``FAILED``
+    responsibility must carry a ``comment`` explaining why. They are agent-only — user
+    actions drive transitions directly rather than being modelled as responsibilities.
+    """
+
+    key: str
+    description: str
+    status: Status = Status.PENDING
+    comment: str | None = None
+
+    def resolve(self, status: Status, comment: str | None = None) -> Responsibility:
+        """Return a resolved copy carrying the definition's ``key``/``description``."""
+        return Responsibility(
+            key=self.key, description=self.description, status=status, comment=comment
+        )
+
+
+@dataclass
+class Repo:
+    """A repository tasks operate on. Owns secret references (added in a later slice)."""
+
+    id: str
+    name: str
+    git_url: str
+    default_base: str = "main"
+
+
+@dataclass(frozen=True)
+class HistoryEntry:
+    """One append-only entry in a task's transition log.
+
+    Timestamps are passed in by the caller (the task service stamps them); the core
+    never reads the clock, which keeps the state machine deterministic and testable.
+    ``responsibilities`` holds the set the agent resolved on this transition (empty when the
+    state being left defines none).
+    """
+
+    at: str  # ISO-8601 timestamp, supplied by the caller
+    from_state: str | None
+    to_state: str
+    via: str | None = None
+    note: str | None = None
+    responsibilities: tuple[Responsibility, ...] = ()
+
+
+@dataclass
+class Task:
+    """A unit of work. Identity is the internal ``id``; ``slug`` is a human label set later."""
+
+    id: str
+    repo_id: str
+    workflow: str
+    state: str
+    turn: Turn
+    slug: str | None = None
+    history: list[HistoryEntry] = field(default_factory=list)

src/panopticon/core/state.py

@@ -0,0 +1,65 @@
+"""Workflow states, expressed as classes (declarative, à la an ORM model).
+
+A state is a **class** used as a type-level identity (never instantiated). Subclass:
+
+* :class:`State` — a non-terminal state. It carries an inherited transition to
+  :class:`Dropped`, so every task is always droppable; concrete states add their own
+  ``transitions`` (which accumulate with the inherited ``Dropped`` across the hierarchy).
+* :class:`TerminalState` — a terminal state (no outgoing transitions).
+
+``transitions`` entries are other state **classes** or their ``label`` **strings**; strings
+are resolved to classes when the owning :class:`~panopticon.core.workflow.Workflow` is built
+(forward references — e.g. cycles — must use strings, as with an ORM relationship).
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import ClassVar
+
+from panopticon.core.models import Mode, Responsibility
+
+TransitionRef = "type[BaseState] | str"
+
+
+class BaseState(ABC):
+    """Common base for workflow states — use :class:`State` or :class:`TerminalState`."""
+
+    #: Stable identifier — persisted in ``Task.state`` and shown on the dashboard.
+    label: ClassVar[str]
+    #: Foreground (user-driven) or background (agent-driven).
+    mode: ClassVar[Mode]
+    #: The agent's obligations while in this state (empty = ungated).
+    responsibilities: ClassVar[tuple[Responsibility, ...]] = ()
+
+
+class TerminalState(BaseState):
+    """A terminal state: the task is finished here; no outgoing transitions.
+
+    Defaults ``mode`` to foreground — the turn returns to the user once a task is terminal.
+    """
+
+    mode: ClassVar[Mode] = Mode.FOREGROUND
+
+
+class Complete(TerminalState):
+    """Built-in terminal state for successfully finished tasks."""
+
+    label: ClassVar[str] = "COMPLETE"
+
+
+class Dropped(TerminalState):
+    """Built-in terminal state for abandoned tasks. Reachable from every non-terminal state."""
+
+    label: ClassVar[str] = "DROPPED"
+
+
+class State(BaseState):
+    """A non-terminal state.
+
+    Concrete states set ``label``, ``mode``, optionally ``responsibilities``, and
+    ``transitions``. The inherited transition to :class:`Dropped` makes every task droppable
+    without each state having to declare it.
+    """
+
+    transitions: ClassVar[tuple[type[BaseState] | str, ...]] = (Dropped,)