alissa-tools-github-orcloop 0.1.0__tar.gz → 0.2.0__tar.gz

{alissa_tools_github_orcloop-0.1.0/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.1.0
+Version: 0.2.0
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -46,13 +46,16 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
-## Status — O0 scaffold
+## Status
 
-This is the **O0 scaffold** only: the distribution skeleton, repo tooling, and
-a CLI stub (`alissa-orcloop --version`). No daemon logic yet — config surface,
-Alissa/GitHub clients, the decision loop, and the Docker image land across
-O1–O5 (see the repo [README](../README.md) lane map). The reserved runtime env
-prefix is `ALISSA_ORC_*`.
+The daemon is live: the config surface (O1), the Alissa/GitHub clients and the
+release ledger (O2), and the decision loop — both the release and close edges
+(O3) — are all in place, driven by the `alissa-orcloop` CLI. See the repo
+[README](../README.md) for the end-to-end documentation: the pipeline role, the
+`Autonomous-Dev` / `Autonomous-Scope` marker contract, both decision matrices,
+the full `ALISSA_ORC_*` configuration surface, and the escalation catalog.
+Packaging the daemon as a container image (O5) is the remaining lane. The
+reserved runtime env prefix is `ALISSA_ORC_*`.
 
 ## Install
 

{alissa_tools_github_orcloop-0.1.0 → alissa_tools_github_orcloop-0.2.0}/README.md

@@ -29,13 +29,16 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
-## Status — O0 scaffold
-
-This is the **O0 scaffold** only: the distribution skeleton, repo tooling, and
-a CLI stub (`alissa-orcloop --version`). No daemon logic yet — config surface,
-Alissa/GitHub clients, the decision loop, and the Docker image land across
-O1–O5 (see the repo [README](../README.md) lane map). The reserved runtime env
-prefix is `ALISSA_ORC_*`.
+## Status
+
+The daemon is live: the config surface (O1), the Alissa/GitHub clients and the
+release ledger (O2), and the decision loop — both the release and close edges
+(O3) — are all in place, driven by the `alissa-orcloop` CLI. See the repo
+[README](../README.md) for the end-to-end documentation: the pipeline role, the
+`Autonomous-Dev` / `Autonomous-Scope` marker contract, both decision matrices,
+the full `ALISSA_ORC_*` configuration surface, and the escalation catalog.
+Packaging the daemon as a container image (O5) is the remaining lane. The
+reserved runtime env prefix is `ALISSA_ORC_*`.
 
 ## Install
 

{alissa_tools_github_orcloop-0.1.0 → alissa_tools_github_orcloop-0.2.0}/src/main/alissa/tools/github/orcloop/__init__.py

@@ -6,9 +6,9 @@ releases tasks marked ready as `alissa:develop` issues, and closes the loop when
 the resulting PR merges. It is the mechanical driver that turns committed work in
 Alissa into GitHub issues the develop/review daemons can pick up.
 
-This is the **O0 scaffold**: the distribution skeleton, repo tooling, and CLI
-stub only — no daemon logic. The moving parts (config surface, Alissa/GitHub
-clients, the decision loop, the Docker image) land across O1–O5; see the repo
+O1 landed the config surface (`config.py`), the marker contract (`markers.py`),
+and the real `alissa-orcloop` CLI. The remaining moving parts (Alissa/GitHub
+clients, the decision loop, the Docker image) land across O2–O5; see the repo
 README's lane map. The reserved runtime env prefix is `ALISSA_ORC_*`.
 """
 

alissa_tools_github_orcloop-0.2.0/src/main/alissa/tools/github/orcloop/__main__.py

@@ -0,0 +1,209 @@
+"""CLI entry point: alissa-orcloop (or python -m alissa.tools.github.orcloop).
+
+O1 wired the config surface and the argument parser; O3 wires the decision
+loop behind it. The CLI resolves and validates the full configuration
+(four-layer precedence, fail-closed `repos` guard), reports the effective
+settings, then runs the orchestrator: `--once` for a single sweep (pair it
+with `--dry-run -v` to print every decision and its reasons without touching
+GitHub or the task graph), otherwise `run_forever`. Config errors still surface
+here, at startup, with a clean exit code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .alissa_client import AlissaError
+from .config import (
+    Config,
+    load_config_file,
+    resolve_config_path,
+)
+from .ghclient import RateLimited
+from .loop import Orchestrator
+from .proc import CommandError
+from .version import version
+
+log = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="alissa-orcloop",
+        description="Orchestrate the Alissa task graph into alissa:develop "
+        "issues and close the loop on merge — the orchestrator daemon of the "
+        "Alissa GitHub daemon family.",
+        epilog="Every setting below can also live in the config file; a CLI "
+        "flag wins over the file, and an ALISSA_ORC_* environment variable "
+        "wins over the flag. workspace_root is CLI-only, so one config can "
+        "drive several orchestrators over different workspaces.",
+    )
+
+    p.add_argument(
+        "--version", action="version", version=f"%(prog)s {version.value}"
+    )
+    p.add_argument(
+        "--workspace-root",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="the workspace this orchestrator runs against (default: current "
+        "directory); also where the ledger defaults",
+    )
+    p.add_argument(
+        "-c",
+        "--config-path",
+        "--config",
+        dest="config_path",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="config file; without it, ./orcloop.config.json then "
+        "<workspace-root>/orcloop.config.json, else defaults only",
+    )
+
+    mode = p.add_argument_group("mode")
+    mode.add_argument(
+        "--once", action="store_true", help="run a single pass and exit"
+    )
+    mode.add_argument("-v", "--verbose", action="store_true")
+
+    over = p.add_argument_group(
+        "config overrides (win over the config file; ALISSA_ORC_* wins over these)"
+    )
+    over.add_argument(
+        "--repo",
+        dest="repos",
+        action="append",
+        metavar="OWNER/REPO",
+        help="watch this repo; repeatable. When given, REPLACES the config "
+        "`repos` list. The allowlist is fail-closed: an empty allowlist is a "
+        "fatal startup error, not a no-op.",
+    )
+    over.add_argument("--label", metavar="LABEL", help="issue label released work carries")
+    over.add_argument("--poll-interval", type=int, metavar="SECONDS")
+    over.add_argument("--repo-parallelism", type=int, metavar="N", help="repos advanced per pass")
+    over.add_argument("--release-blocked-floor-days", type=int, metavar="DAYS")
+    over.add_argument("--marker-key", metavar="KEY", help="Autonomous-Dev trailer key")
+    over.add_argument("--scope-key", metavar="KEY", help="Autonomous-Scope trailer key")
+    over.add_argument("--alissa-endpoint", metavar="URL")
+    over.add_argument("--ledger-path", type=Path, metavar="PATH")
+
+    close = over.add_mutually_exclusive_group()
+    close.add_argument(
+        "--close-loop",
+        dest="close_loop_enabled",
+        action="store_true",
+        default=None,
+        help="drive the origin task forward when a released PR merges (the default)",
+    )
+    close.add_argument(
+        "--no-close-loop",
+        dest="close_loop_enabled",
+        action="store_false",
+        help="release-only: never act on merges, even if the config enables it",
+    )
+
+    dry = over.add_mutually_exclusive_group()
+    dry.add_argument(
+        "--dry-run",
+        dest="dry_run",
+        action="store_true",
+        default=None,
+        help="decide and log, but never release an issue or touch task/GitHub state",
+    )
+    dry.add_argument(
+        "--no-dry-run",
+        dest="dry_run",
+        action="store_false",
+        help="act for real even if the config sets dry_run",
+    )
+    return p
+
+
+def overrides_from(args: argparse.Namespace) -> dict:
+    """CLI values, with None meaning 'not specified' so the config file shows
+    through. `repos` becomes a tuple so it matches the file form."""
+    return {
+        "repos": tuple(args.repos) if args.repos else None,
+        "label": args.label,
+        "poll_interval": args.poll_interval,
+        "repo_parallelism": args.repo_parallelism,
+        "release_blocked_floor_days": args.release_blocked_floor_days,
+        "marker_key": args.marker_key,
+        "scope_key": args.scope_key,
+        "alissa_endpoint": args.alissa_endpoint,
+        "ledger_path": args.ledger_path,
+        "close_loop_enabled": args.close_loop_enabled,
+        "dry_run": args.dry_run,
+    }
+
+
+def resolve_config(args: argparse.Namespace) -> Config:
+    workspace_root = args.workspace_root or Path.cwd()
+    path = resolve_config_path(args.config_path, workspace_root)
+
+    file_data = load_config_file(path) if path else {}
+    log.info("config: %s", path or "none found — defaults + CLI + env only")
+
+    return Config.build(workspace_root, file_data, overrides_from(args))
+
+
+def log_effective_config(config: Config) -> None:
+    """The resolved settings, defaults and all. INFO carries the decisions an
+    operator needs; -v (DEBUG) shows the full surface."""
+    log.info("watching %s for label %r", ", ".join(config.repos), config.label)
+    log.info(
+        "poll every %ss; repo_parallelism=%s; dry_run=%s; close_loop=%s",
+        config.poll_interval, config.repo_parallelism, config.dry_run,
+        config.close_loop_enabled,
+    )
+    log.debug("marker_key: %s", config.marker_key)
+    log.debug("scope_key: %s", config.scope_key)
+    log.debug("release_blocked_floor_days: %s", config.release_blocked_floor_days)
+    log.debug("alissa_endpoint: %s", config.alissa_endpoint)
+    log.debug("ledger_db: %s", config.ledger_db)
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    try:
+        config = resolve_config(args)
+        log.info("workspace: %s", config.workspace_root)
+        log_effective_config(config)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 0
+
+    orchestrator = Orchestrator(config)
+    try:
+        if args.once:
+            orchestrator.poll_once()
+        else:
+            log.info("starting orchestrator; polling every %ss", config.poll_interval)
+            orchestrator.run_forever()
+    except KeyboardInterrupt:
+        return 0
+    except (AlissaError, CommandError, RateLimited) as exc:
+        # A single --once pass surfaces a transport/adapter failure as a non-zero
+        # exit for the operator; run_forever swallows and backs off instead of
+        # exiting, so this only fires under --once.
+        print(f"orchestrator error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alissa_tools_github_orcloop-0.2.0/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -0,0 +1,393 @@
+"""Alissa task-graph adapter for the orchestrator.
+
+TRANSPORT DECISION (the O2 spike, spec v1 §1)
+=============================================
+orcloop talks to Alissa as the operator actor over the **Alissa REST API**
+(`https://api.alissa.app`, versioned under `/v1`), using the Python **stdlib
+only** (`urllib`) and a personal access token from `ALISSA_API_TOKEN`. No third
+-party HTTP library, no subprocess: the transport is in-process `urllib`, hidden
+entirely behind this adapter.
+
+Rationale, and why the two options the issue named were rejected:
+
+* **REST over stdlib HTTP (CHOSEN).** The token authenticates every `/v1`
+  endpoint with a plain `Authorization: Bearer` header -- no browser/OAuth flow
+  -- and the REST surface exposes exactly the operations the loop needs
+  (filtered task list, task read, evidence, criteria, status, comments). Every
+  failure arrives as an HTTP status code, which maps cleanly onto the narrow
+  error taxonomy below (auth vs transient vs not-found). Stdlib `urllib` keeps
+  the distribution dependency-free, matching the family posture (devloop and
+  reviewloop ship no third-party runtime deps either). This is the same
+  transport the `alissa-api` skill's bundled `scripts/alissa_api.py` client
+  uses, so the shape is proven against the live endpoint.
+
+* **JSON-RPC against the Alissa MCP HTTP endpoint (REJECTED -- no reachable
+  endpoint).** The spike found no MCP server in the daemon/worker environment
+  (`claude mcp list` is empty), so there is no MCP HTTP endpoint to speak
+  JSON-RPC to; the token authenticates the REST API, not an MCP transport. The
+  MCP surface is an editor/agent integration, not an operator daemon one --
+  building a JSON-RPC client against an endpoint that does not exist here was a
+  dead end. REST reaches the identical task-graph operations directly.
+
+* **Shelling to the `alissa` CLI (REJECTED -- taxonomy + capability).** The CLI
+  can read/write tasks, but (a) its `task list` takes no `status`/marker filter
+  (per the `alissa-api` skill, filtered listing and ranking are REST/MCP only),
+  so the loop's `list_marked_committed_tasks` would have to over-fetch and
+  filter client-side, and (b) subprocess failures surface as an exit code plus
+  free-text stderr, which cannot be classified into auth/transient/not-found
+  as reliably as an HTTP status. REST gives both the server-side `status=`
+  filter and clean status codes.
+
+Live smoke run confirming the choice is documented in the PR body.
+
+ERROR TAXONOMY
+==============
+Three narrow, actionable buckets so the loop can react without string-matching:
+
+* ``AlissaAuthError``  -- 401/403 (missing/invalid token, or no role on the
+  task, e.g. the ``NOT_OWNER`` code). Permanent, operator-fixable; do not retry.
+* ``AlissaNotFound``   -- 404 (task/evidence/criterion absent or not visible to
+  the bound actor). Permanent for this ref.
+* ``AlissaTransient``  -- 408/429/5xx and every transport failure (DNS, refused
+  connection, timeout). Retry-later signals.
+
+Anything else (a 400 validation error, say) surfaces as the base
+``AlissaError`` -- a bug to fix, not a condition to retry blindly.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+DEFAULT_BASE = "https://api.alissa.app"
+
+# The readiness marker: an operator "releases" a committed task to the develop
+# pipeline by placing this token in the task's description. It is deliberately
+# the SAME string as the GitHub label orcloop stamps on the issue it creates --
+# one token means both "ready to release" (on the Alissa task) and "for the
+# develop daemon" (on the GitHub issue). The value is overridable per call so
+# the O1 config surface / O3 loop can supply a configured marker; this constant
+# is the documented default. See the repo README's pipeline description.
+RELEASE_MARKER = "alissa:develop"
+
+
+class AlissaError(RuntimeError):
+    """Base class. `status` is the HTTP code (0 for transport failures); `code`
+    is the API's machine error string (`{"error": ...}`) when one was sent."""
+
+    def __init__(self, status: int, payload: object, code: str | None = None):
+        self.status = status
+        self.payload = payload
+        self.code = code
+        super().__init__(f"HTTP {status}{f' {code}' if code else ''}: {payload}")
+
+
+class AlissaAuthError(AlissaError):
+    """401/403: no valid token, or the bound actor has no role on the task.
+    Permanent and operator-fixable -- never retried."""
+
+
+class AlissaNotFound(AlissaError):
+    """404: the task/evidence/criterion is absent or invisible to this actor."""
+
+
+class AlissaTransient(AlissaError):
+    """408/429/5xx or a transport failure -- a retry-later signal."""
+
+
+@dataclass(frozen=True)
+class MarkedTask:
+    """A release candidate as the LIST endpoint reports it. `description` is the
+    list payload's `descriptionPreview` -- possibly truncated, enough to filter
+    on; the loop calls `get_task` for the full body before writing the issue."""
+
+    ref: str  # TASK-<taskNumber>
+    task_number: int
+    title: str
+    status: str
+    description: str
+
+
+@dataclass(frozen=True)
+class Criterion:
+    id: str
+    description: str
+    satisfied: bool
+
+
+@dataclass(frozen=True)
+class Dependency:
+    """One upstream (depends-on) task, as the DETAIL endpoint reports it under
+    `upstreamTasks`. `ref` is `TASK-<n>` when the upstream row carries a task
+    number, else its opaque id (the upstream preview omits taskNumber for some
+    actors); `status` is what the O3 dependsOn gate reads."""
+
+    ref: str
+    status: str
+
+
+@dataclass(frozen=True)
+class Task:
+    """A task as the DETAIL endpoint reports it -- full description and DoD,
+    plus the validation criteria the loop satisfies on close.
+
+    O3 added the release-queue fields: `priority` and `created_at` drive the
+    priority-then-age ordering, and `dependencies` (with `depends_on_count`)
+    drives the dependsOn gate. They default to the "unset" shape so a detail
+    payload that omits them -- and any caller constructing a Task by hand --
+    reads as no-priority / age-zero / no-deps rather than raising."""
+
+    ref: str  # TASK-<taskNumber>
+    task_number: int
+    title: str
+    status: str
+    description: str
+    definition_of_done: str
+    criteria: tuple[Criterion, ...]
+    priority: str = ""
+    created_at: int = 0  # ms since epoch; 0 when the payload omits createdAt
+    # The resolved upstream tasks (statuses the dependsOn gate reads).
+    dependencies: tuple[Dependency, ...] = ()
+    # len(dependsOn): may EXCEED len(dependencies) when an upstream is invisible
+    # to this actor -- the gate treats that mismatch as "not provably clear".
+    depends_on_count: int = 0
+
+
+def _query(params: dict) -> str:
+    """`?a=b&…` from params: skip None, comma-join lists (any-of), bools as
+    true/false. Empty → ''. Mirrors the bundled alissa_api.py client."""
+    pairs: list[tuple[str, str]] = []
+    for key, val in params.items():
+        if val is None:
+            continue
+        if isinstance(val, bool):
+            pairs.append((key, "true" if val else "false"))
+        elif isinstance(val, (list, tuple)):
+            if val:
+                pairs.append((key, ",".join(str(v) for v in val)))
+        else:
+            pairs.append((key, str(val)))
+    return ("?" + urllib.parse.urlencode(pairs)) if pairs else ""
+
+
+class AlissaClient:
+    """Thin REST adapter over the task-graph operations orcloop needs.
+
+    Transport is hidden: callers see `MarkedTask`/`Task` and the taxonomy
+    exceptions, never HTTP. Reads `ALISSA_API_TOKEN` and `ALISSA_BASE` from the
+    environment (both overridable in the constructor for tests)."""
+
+    def __init__(self, token: str | None = None, base: str | None = None, *, timeout: int = 30):
+        self.base = (base or os.environ.get("ALISSA_BASE") or DEFAULT_BASE).rstrip("/")
+        self._token = token if token is not None else os.environ.get("ALISSA_API_TOKEN")
+        self._timeout = timeout
+
+    # --- transport ---------------------------------------------------------
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> object:
+        """One REST call. Translates every failure into the narrow taxonomy;
+        the caller never sees a raw urllib error or HTTP status."""
+        if not self._token:
+            # No token at all is an auth condition, not a transport one: the
+            # operator must set ALISSA_API_TOKEN. Fail the same way a 401 would.
+            raise AlissaAuthError(0, "ALISSA_API_TOKEN is not set")
+
+        url = f"{self.base}{path}"
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Accept": "application/json", "Authorization": f"Bearer {self._token}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # noqa: S310
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise self._classify(exc) from None
+        except urllib.error.URLError as exc:
+            # DNS failure, refused connection, timeout: all retry-later.
+            raise AlissaTransient(0, str(exc.reason)) from None
+        return json.loads(raw) if raw.strip() else {}
+
+    @staticmethod
+    def _classify(exc: "urllib.error.HTTPError") -> AlissaError:
+        """Map an HTTP error onto the taxonomy. The API sends JSON error bodies
+        (`{"error": CODE, "message": ...}`); the code rides along on the
+        exception when present, but classification keys on the STATUS -- codes
+        are advisory, statuses are the contract."""
+        detail: object = exc.read().decode("utf-8", "replace")
+        code: str | None = None
+        try:
+            parsed = json.loads(detail)  # type: ignore[arg-type]
+            if isinstance(parsed, dict):
+                detail = parsed
+                raw_code = parsed.get("error")
+                code = raw_code if isinstance(raw_code, str) else None
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+        status = exc.code
+        if status in (401, 403):
+            return AlissaAuthError(status, detail, code)
+        if status == 404:
+            return AlissaNotFound(status, detail, code)
+        if status == 408 or status == 429 or 500 <= status <= 599:
+            return AlissaTransient(status, detail, code)
+        return AlissaError(status, detail, code)
+
+    # --- adapter surface ---------------------------------------------------
+
+    def list_marked_committed_tasks(self, marker: str = RELEASE_MARKER) -> list[MarkedTask]:
+        """Committed tasks carrying the release `marker`, with descriptions.
+
+        The status filter runs server-side (`GET /v1/tasks?status=committed`);
+        the marker filter runs here against the fields the LIST endpoint returns
+        -- `title`, `descriptionPreview`, `dodPreview`. A marker buried past the
+        preview truncation window will be missed, which is why the operator
+        convention is to place it in the task description where it leads the
+        preview; the loop re-reads the full body via `get_task` before writing
+        the issue anyway.
+
+        An empty/whitespace marker returns [] rather than matching every task:
+        a blank marker must mean "release nothing", never "release everything"
+        -- the same fail-closed spirit the GitHub search carries.
+        """
+        marker = marker.strip()
+        if not marker:
+            log.warning(
+                "list_marked_committed_tasks: empty release marker -- nothing is "
+                "released. A blank marker would match every committed task, so "
+                "this fails closed; configure a marker to release something."
+            )
+            return []
+
+        payload = self._request("GET", "/v1/tasks" + _query({"status": "committed"}))
+        tasks = payload.get("tasks") if isinstance(payload, dict) else None
+        if not isinstance(tasks, list):
+            return []
+
+        out: list[MarkedTask] = []
+        for row in tasks:
+            if not isinstance(row, dict):
+                continue
+            number = row.get("taskNumber")
+            if not isinstance(number, int):
+                continue
+            title = row.get("title") or ""
+            description = row.get("descriptionPreview") or ""
+            dod = row.get("dodPreview") or ""
+            if marker not in f"{title}\n{description}\n{dod}":
+                continue
+            out.append(
+                MarkedTask(
+                    ref=f"TASK-{number}",
+                    task_number=number,
+                    title=title,
+                    status=row.get("status") or "",
+                    description=description,
+                )
+            )
+        return out
+
+    def get_task(self, ref: str) -> Task:
+        """Full detail for one task. `ref` is any reference form the API accepts
+        (`TASK-<n>`, public id, url). Raises `AlissaNotFound` when the bound
+        actor has no role on it."""
+        payload = self._request("GET", f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}")
+        task = payload.get("task") if isinstance(payload, dict) else None
+        if not isinstance(task, dict):
+            # A 2xx with no task object is a contract violation, not a 404 --
+            # surface it as the base error rather than fabricating a Task.
+            raise AlissaError(200, f"no task object in response for {ref!r}")
+
+        criteria: list[Criterion] = []
+        for crit in task.get("validationCriteria") or []:
+            if not isinstance(crit, dict):
+                continue
+            criteria.append(
+                Criterion(
+                    id=str(crit.get("id") or ""),
+                    description=crit.get("description") or "",
+                    satisfied=bool(crit.get("satisfied")),
+                )
+            )
+
+        # The dependsOn gate reads upstream statuses. `dependsOn` is the id
+        # list; `upstreamTasks` is the resolved view (id/title/status). We key
+        # the gate on the resolved statuses but remember the raw dependsOn
+        # count so an upstream this actor cannot see (present in dependsOn,
+        # absent from upstreamTasks) reads as "not provably clear".
+        dependencies: list[Dependency] = []
+        for up in task.get("upstreamTasks") or []:
+            if not isinstance(up, dict):
+                continue
+            up_number = up.get("taskNumber")
+            up_ref = (
+                f"TASK-{up_number}"
+                if isinstance(up_number, int)
+                else str(up.get("_id") or "")
+            )
+            dependencies.append(Dependency(ref=up_ref, status=up.get("status") or ""))
+        depends_on = task.get("dependsOn")
+        depends_on_count = len(depends_on) if isinstance(depends_on, list) else 0
+
+        created_raw = task.get("createdAt")
+        created_at = int(created_raw) if isinstance(created_raw, (int, float)) else 0
+
+        number = task.get("taskNumber")
+        return Task(
+            ref=f"TASK-{number}" if isinstance(number, int) else str(ref),
+            task_number=number if isinstance(number, int) else 0,
+            title=task.get("title") or "",
+            status=task.get("status") or "",
+            description=task.get("description") or "",
+            definition_of_done=task.get("definitionOfDone") or "",
+            criteria=tuple(criteria),
+            priority=task.get("priority") or "",
+            created_at=created_at,
+            dependencies=tuple(dependencies),
+            depends_on_count=depends_on_count,
+        )
+
+    def add_evidence(self, ref: str, title: str, markdown: str, *, item_type: str = "evidence") -> None:
+        """Attach an evidence/deliverable item (outputs surface, not context).
+        orcloop uses this to record loop-closure evidence on the origin task."""
+        self._request(
+            "POST",
+            f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}/evidence",
+            {"title": title, "markdownContent": markdown, "itemType": item_type},
+        )
+
+    def satisfy_criterion(self, ref: str, criterion_id: str) -> None:
+        """Mark one validation criterion satisfied. No partial-credit shortcut:
+        every criterion is satisfied individually before a task can validate."""
+        self._request(
+            "POST",
+            f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}"
+            f"/criteria/{urllib.parse.quote(str(criterion_id), safe='')}/satisfy",
+        )
+
+    def set_status(self, ref: str, status: str) -> None:
+        """Move a task along the transition matrix (draft → committed →
+        in_progress → pending_validation → validated, with blocked/cancelled
+        side moves). Illegal transitions come back as the base `AlissaError`."""
+        self._request(
+            "POST",
+            f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}/status",
+            {"status": status},
+        )
+
+    def add_comment(self, ref: str, body: str) -> None:
+        """Post a comment. The endpoint field is `content`, not `body`."""
+        self._request(
+            "POST",
+            f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}/comments",
+            {"content": body},
+        )