chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/runtime/queue.py

@@ -0,0 +1,565 @@
+"""The agent task queue: one record per ready agent rule instance (DESIGN.md 5.5, D35).
+
+An agent runtime that runs outside the engine's process (for example the user's own
+agent harness, driven through tool calls) cannot be called like a function: the engine
+hands out tasks, the harness does them, and the engine checks the result. This module
+keeps that hand-over as state, under the state backend (never in the repo tree)::
+
+    <state>/runtime/tasks/<sha256(task_id)>.json      AgentTaskRecord   (engine writes)
+    <state>/runtime/baselines/<sha256(task_id)>.json  file hashes at dispatch
+    <state>/runtime/agents/<sha256(agent_id)>.json    AgentBinding      (write guard writes)
+
+A task moves ``ready -> dispatched -> submitted -> accepted | rejected |
+budget_exhausted | needs_human``; a ``rejected`` task is dispatched again until its
+``tries`` are used up. Each dispatch also records what the task's agent must not read
+(``denied_reads``, from its role's read policy), for the harness's guard. The runtime
+that checks the submits keeps the agent rule loop's count on the record
+(``budget_state``: tries, infra retries, the last failures and redo instruction), and
+``dispatch`` never hands a task out more than ``max_dispatches`` times in one budget
+cycle (tries plus infra retries). Every file has
+a single writer, so the engine and the harness's write guard (a separate process) never
+overwrite each other's updates: the guard owns the agent bindings and their tool-call
+counts, the engine owns everything else.
+
+Pure Python over JSON files: no subprocess, no VCS, no knowledge of any harness.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from collections.abc import Iterable, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, ValidationError
+
+from chipgraph.core.contracts import AgentResult, ModelTier, RuleId
+from chipgraph.core.contracts.types import FailureLabel
+from chipgraph.core.plugin_api.types import AgentTask
+from chipgraph.core.runtime.roles import find_role, model_ladder
+from chipgraph.core.state.layout import StateLayout
+
+TaskStatus = Literal[
+    "ready",
+    "dispatched",
+    "submitted",
+    "accepted",
+    "rejected",
+    "budget_exhausted",
+    "needs_human",
+]
+"""Where an agent task is in its life: see the module docstring for the transitions."""
+
+OPEN_STATUSES: frozenset[TaskStatus] = frozenset({"ready", "rejected"})
+"""Statuses a task can be dispatched from."""
+
+ACTIVE_STATUSES: frozenset[TaskStatus] = frozenset({"dispatched", "submitted"})
+"""Statuses in which an agent may be working on the task, or the engine is checking it."""
+
+DEFAULT_TOOL_CALL_CAP = 80
+"""Tool calls one dispatch of a task may make, over every agent bound to it.
+
+A harness's own turn limit may not count the work of the agents it starts (spike S7:
+the turn limit counts only the main session), so the engine keeps this budget itself,
+per task.
+"""
+
+
+class QueueError(Exception):
+    """An unknown task, or a transition its current status does not allow."""
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def state_key(value: str) -> str:
+    """The file name stem for a task id or an agent id: its sha256 hex digest."""
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+BudgetStop = Literal["tries", "stagnation", "infra", "planning"]
+"""Why a task's loop stopped on a submit: its tries ran out, two tries in a row left the
+same outputs and failures, its infra retries ran out, or the checks point at the spec."""
+
+
+class TaskBudgetState(BaseModel):
+    """The agent rule loop's count for one task, kept across submits (DESIGN.md 5.2).
+
+    An out-of-process runtime checks one attempt per submit, so the loop's budget state
+    (`chipgraph.core.engine.agent_rule.BudgetState`: tries used, infra retries, the last
+    failure signature) lives on the task record, with what the next attempt and a
+    HANDOFF need (the last label, failures and redo instruction). It counts one budget
+    cycle: a reopened task starts a new one. Tokens and cost are not kept: such a
+    runtime does not report them per task.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    dispatches: int = Field(default=0, ge=0, description="Dispatches in this budget cycle.")
+    tries_used: int = Field(default=0, ge=0, description="Tries used (failed or passed).")
+    failed_tries: int = Field(default=0, ge=0, description="Tries that failed.")
+    infra_failures: int = Field(
+        default=0, ge=0, description="Submits that failed on infra (not tries)."
+    )
+    last_signature: str | None = Field(
+        default=None, description="Output hashes and failures of the last failed try."
+    )
+    stagnant: bool = Field(
+        default=False, description="The last two failed tries had the same signature."
+    )
+    output_hashes: dict[str, str] = Field(
+        default_factory=dict, description="Output path to content hash at the last submit."
+    )
+    label: FailureLabel | None = Field(default=None, description="Label of the last failure.")
+    tier: ModelTier | None = Field(default=None, description="Model tier of the last try.")
+    failed_checks: tuple[str, ...] = Field(
+        default=(), description="Check ids that did not pass on the last failed submit."
+    )
+    failures: tuple[str, ...] = Field(
+        default=(), description="One line per failing check of the last failed submit."
+    )
+    redo: str | None = Field(
+        default=None, description="The redo instruction for the next try (bounded text)."
+    )
+    stop: BudgetStop | None = Field(default=None, description="Why the loop stopped, if it did.")
+    handoff: str | None = Field(
+        default=None, description="The HANDOFF.md written when the loop stopped."
+    )
+
+
+class AgentTaskRecord(BaseModel):
+    """One agent rule instance handed to an out-of-process agent runtime."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    task_id: str = Field(min_length=1, description="The rule instance id this task fulfils.")
+    rule_id: RuleId = Field(description="The rule this task is an instance of.")
+    role: str = Field(min_length=1, description="The agent role that runs this task.")
+    skills: tuple[str, ...] = Field(default=(), description="Skill ids available to the role.")
+    allowed_writes: tuple[str, ...] = Field(
+        min_length=1, description="Repo-relative paths the agent may write: the outputs."
+    )
+    tries: int = Field(ge=1, description="Submissions allowed before the budget is exhausted.")
+    tier: ModelTier = Field(default="medium", description="Model tier for the first attempt.")
+    escalate: ModelTier | None = Field(
+        default=None, description="Model tier for later attempts, if the rule escalates."
+    )
+    denied_reads: tuple[str, ...] = Field(
+        default=(),
+        description=(
+            "Repo-relative paths and globs the agent must not read (its role's read policy "
+            "resolved against the project); set on every dispatch. The guard refuses reads "
+            "of them, and listings or searches that could reach them."
+        ),
+    )
+    status: TaskStatus = Field(default="ready", description="Where the task is in its life.")
+    attempts: int = Field(default=0, ge=0, description="Rejected submissions so far.")
+    dispatches: int = Field(default=0, ge=0, description="How many times it was handed out.")
+    tool_call_cap: int = Field(
+        default=DEFAULT_TOOL_CALL_CAP, ge=1, description="Tool calls allowed per dispatch."
+    )
+    inputs_hash: str = Field(description="Hash of the instance's inputs when it was enqueued.")
+    run_id: str | None = Field(default=None, description="The run that last dispatched it.")
+    accepted_hashes: dict[str, str] = Field(
+        default_factory=dict, description="Output path to content hash, when accepted."
+    )
+    reasons: tuple[str, ...] = Field(default=(), description="Why the last submit was rejected.")
+    outside: tuple[str, ...] = Field(
+        default=(), description="Files the last rejected attempt changed outside its outputs."
+    )
+    last_result: AgentResult | None = Field(default=None, description="The last agent result.")
+    max_dispatches: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Most dispatches in one budget cycle: tries plus infra retries. `dispatch` "
+            "refuses one more. Unset on records written before it existed."
+        ),
+    )
+    budget_state: TaskBudgetState | None = Field(
+        default=None, description="The loop's count across submits; unset until dispatched."
+    )
+    workspace: str | None = Field(
+        default=None,
+        description=(
+            "Absolute path to the task's isolated workspace, when `fanout.isolate` is true "
+            "or the rule sets `isolate: true`. The workspace is a worktree at HEAD with the "
+            "task's declared inputs copied in; the subagent writes there, not the user's tree."
+        ),
+    )
+    seed_hashes: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Content hash of each input file copied into the workspace when it was seeded, "
+            "keyed by repo-relative path. Used to detect changes during the task."
+        ),
+    )
+    updated_at: AwareDatetime = Field(default_factory=_now, description="Last change.")
+
+    @property
+    def current_tier(self) -> ModelTier:
+        """The model tier for the next attempt: `escalate` once an attempt was rejected."""
+        if self.attempts >= 1 and self.escalate is not None:
+            return self.escalate
+        return self.tier
+
+    @property
+    def state(self) -> TaskBudgetState:
+        """The budget state; for a record without one, what its counters imply.
+
+        A record from before `budget_state` existed counted every rejected submit as a
+        try and dispatched once per try, so `attempts` stands for both (plus the
+        dispatch in progress, if any).
+        """
+        if self.budget_state is not None:
+            return self.budget_state
+        active = 1 if self.status in ACTIVE_STATUSES else 0
+        return TaskBudgetState(
+            dispatches=self.attempts + active,
+            tries_used=self.attempts,
+            failed_tries=self.attempts,
+        )
+
+
+class AgentBinding(BaseModel):
+    """Which task one agent works on, and how many tool calls it made (guard-owned).
+
+    Written only by the harness's write guard, which binds an agent to a task when the
+    agent asks for that task's context. The engine only reads it.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    agent_id: str = Field(min_length=1, description="The harness's id for the agent.")
+    agent_type: str = Field(default="", description="The agent definition it runs.")
+    task_id: str = Field(min_length=1, description="The task the agent is bound to.")
+    dispatch: int = Field(ge=1, description="The task's `dispatches` count when it bound.")
+    tool_calls: int = Field(default=0, ge=0, description="Tool calls the agent made so far.")
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+class TaskQueue:
+    """Reads and writes the agent task queue under a project's state directory."""
+
+    def __init__(self, layout: StateLayout) -> None:
+        self.layout = layout
+        self.runtime_dir = layout.state_dir / "runtime"
+        self.tasks_dir = self.runtime_dir / "tasks"
+        self.baselines_dir = self.runtime_dir / "baselines"
+        self.agents_dir = self.runtime_dir / "agents"
+
+    # --- reading -------------------------------------------------------------------
+
+    def _task_path(self, task_id: str) -> Path:
+        return self.tasks_dir / f"{state_key(task_id)}.json"
+
+    def get(self, task_id: str) -> AgentTaskRecord | None:
+        """The record for `task_id`, or `None` if it was never enqueued."""
+        path = self._task_path(task_id)
+        if not path.is_file():
+            return None
+        return AgentTaskRecord.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def require(self, task_id: str) -> AgentTaskRecord:
+        """The record for `task_id`; raises `QueueError` if there is none."""
+        record = self.get(task_id)
+        if record is None:
+            raise QueueError(f"no agent task {task_id!r}")
+        return record
+
+    def all(self) -> list[AgentTaskRecord]:
+        """Every record, sorted by task id."""
+        if not self.tasks_dir.is_dir():
+            return []
+        records = [
+            AgentTaskRecord.model_validate_json(path.read_text(encoding="utf-8"))
+            for path in self.tasks_dir.glob("*.json")
+        ]
+        return sorted(records, key=lambda r: r.task_id)
+
+    def baseline(self, task_id: str) -> dict[str, str]:
+        """The file hashes recorded when `task_id` was last dispatched (empty if none)."""
+        path = self.baselines_dir / f"{state_key(task_id)}.json"
+        if not path.is_file():
+            return {}
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or not all(
+            isinstance(k, str) and isinstance(v, str) for k, v in data.items()
+        ):
+            raise QueueError(f"baseline {path} is not a mapping of path to hash")
+        return dict(data)
+
+    def bindings(self, task_id: str | None = None) -> list[AgentBinding]:
+        """Agent bindings written by the write guard, optionally only those for `task_id`.
+
+        A binding file that does not validate raises `QueueError`: it is the guard's
+        state, and a broken one means the guard is denying every call anyway.
+        """
+        if not self.agents_dir.is_dir():
+            return []
+        found: list[AgentBinding] = []
+        for path in sorted(self.agents_dir.glob("*.json")):
+            try:
+                binding = AgentBinding.model_validate_json(path.read_text(encoding="utf-8"))
+            except ValidationError as exc:
+                raise QueueError(f"broken agent binding {path}: {exc}") from exc
+            if task_id is None or binding.task_id == task_id:
+                found.append(binding)
+        return found
+
+    def tool_calls(self, task_id: str) -> int:
+        """Tool calls made so far in the task's current dispatch, over all its agents."""
+        record = self.require(task_id)
+        return sum(b.tool_calls for b in self.bindings(task_id) if b.dispatch == record.dispatches)
+
+    # --- writing -------------------------------------------------------------------
+
+    def _put(self, record: AgentTaskRecord) -> AgentTaskRecord:
+        record = record.model_copy(update={"updated_at": _now()})
+        _write_atomic(self._task_path(record.task_id), record.model_dump_json(indent=2))
+        return record
+
+    def enqueue(
+        self,
+        task: AgentTask,
+        *,
+        inputs_hash: str,
+        output_hashes: Mapping[str, str],
+        tool_call_cap: int = DEFAULT_TOOL_CALL_CAP,
+        max_dispatches: int | None = None,
+        task_id: str | None = None,
+    ) -> AgentTaskRecord:
+        """Add `task` as `ready`, or return its existing record (idempotent).
+
+        An existing record is reopened as a fresh `ready` task (attempts back to 0) when
+        the work it did no longer holds: an `accepted` task whose inputs changed or whose
+        outputs no longer hash as accepted, or a `budget_exhausted`/`needs_human` task
+        whose inputs changed (a person fixed the spec, say). Otherwise it is unchanged.
+        A reopened task starts a new budget cycle (no `budget_state`); its `dispatches`
+        count goes on, so the guard's bindings of earlier dispatches stay stale.
+
+        The model tiers come from the task's role (`RoleSpec.default_tier`,
+        `escalate_to`) unless the rule's budget sets `tier` or `escalate` itself.
+        `max_dispatches` bounds the dispatches of a new record (see `dispatch`).
+        `task_id` (best-of-N) names the record `<instance id>#<n>` instead of the instance id:
+        a candidate of the same instance, with its own workspace and budget.
+        """
+        task_id = task_id or task.instance.instance_id
+        existing = self.get(task_id)
+        if existing is not None:
+            inputs_changed = existing.inputs_hash != inputs_hash
+            if existing.status == "accepted":
+                outputs_changed = dict(output_hashes) != existing.accepted_hashes
+                if not inputs_changed and not outputs_changed:
+                    return existing
+            elif existing.status in ("budget_exhausted", "needs_human"):
+                if not inputs_changed:
+                    return existing
+            else:
+                return existing
+        tier, escalate = model_ladder(find_role(task.role), task.budget)
+        record = AgentTaskRecord(
+            task_id=task_id,
+            rule_id=task.instance.rule_id,
+            role=task.role,
+            skills=task.skills,
+            allowed_writes=task.allowed_writes,
+            tries=task.budget.tries,
+            tier=tier,
+            escalate=escalate,
+            tool_call_cap=tool_call_cap,
+            inputs_hash=inputs_hash,
+            dispatches=existing.dispatches if existing is not None else 0,
+            max_dispatches=max_dispatches,
+        )
+        return self._put(record)
+
+    def _transition(
+        self, task_id: str, allowed: frozenset[TaskStatus], action: str
+    ) -> AgentTaskRecord:
+        record = self.require(task_id)
+        if record.status not in allowed:
+            raise QueueError(
+                f"cannot {action} task {task_id!r}: it is {record.status!r} "
+                f"(needs one of {sorted(allowed)})"
+            )
+        return record
+
+    def dispatch(
+        self,
+        task_id: str,
+        *,
+        run_id: str,
+        baseline: Mapping[str, str],
+        denied_reads: Iterable[str] = (),
+        workspace: str | None = None,
+        seed_hashes: Mapping[str, str] | None = None,
+    ) -> AgentTaskRecord:
+        """Hand the task out: `ready`/`rejected` -> `dispatched`, with a new baseline.
+
+        `denied_reads` (the role's read policy resolved against the project as it is
+        now) replaces the record's, in the same write as the status change, so the
+        guard never sees the task dispatched without it. Counts the dispatch in the
+        budget cycle; refused (`QueueError`) once `max_dispatches` were handed out.
+
+        `workspace` (absolute path) and `seed_hashes` (input path -> hash) are set when
+        `fanout.isolate` is true: the task runs in an isolated workspace, not the user's
+        tree. The guard uses `workspace` to route writes there.
+        """
+        record = self._transition(task_id, OPEN_STATUSES, "dispatch")
+        state = record.state
+        if record.max_dispatches is not None and state.dispatches >= record.max_dispatches:
+            raise QueueError(
+                f"cannot dispatch task {task_id!r}: it was handed out "
+                f"{state.dispatches} times, its limit (tries plus infra retries)"
+            )
+        _write_atomic(
+            self.baselines_dir / f"{state_key(task_id)}.json",
+            json.dumps(dict(sorted(baseline.items())), indent=1),
+        )
+        update: dict[str, object] = {
+            "status": "dispatched",
+            "dispatches": record.dispatches + 1,
+            "run_id": run_id,
+            "denied_reads": tuple(sorted(set(denied_reads))),
+            "budget_state": state.model_copy(update={"dispatches": state.dispatches + 1}),
+            "workspace": workspace,
+            "seed_hashes": dict(seed_hashes) if seed_hashes is not None else {},
+        }
+        return self._put(record.model_copy(update=update))
+
+    def mark_submitted(self, task_id: str) -> AgentTaskRecord:
+        """`dispatched` -> `submitted`: the engine is checking the work (no more writes)."""
+        record = self._transition(task_id, frozenset({"dispatched"}), "submit")
+        return self._put(record.model_copy(update={"status": "submitted"}))
+
+    def unsubmit(self, task_id: str) -> AgentTaskRecord:
+        """`submitted` -> `dispatched`, when checking the work failed for reasons of its own."""
+        record = self._transition(task_id, frozenset({"submitted"}), "unsubmit")
+        return self._put(record.model_copy(update={"status": "dispatched"}))
+
+    def accept(
+        self,
+        task_id: str,
+        *,
+        result: AgentResult,
+        output_hashes: Mapping[str, str],
+        budget_state: TaskBudgetState | None = None,
+    ) -> AgentTaskRecord:
+        """`submitted` -> `accepted`, remembering the output hashes that were accepted."""
+        record = self._transition(task_id, frozenset({"submitted"}), "accept")
+        update: dict[str, object] = {
+            "status": "accepted",
+            "accepted_hashes": dict(output_hashes),
+            "reasons": (),
+            "outside": (),
+            "last_result": result,
+        }
+        if budget_state is not None:
+            update["budget_state"] = budget_state
+        return self._put(record.model_copy(update=update))
+
+    def reject(
+        self,
+        task_id: str,
+        *,
+        result: AgentResult,
+        reasons: tuple[str, ...],
+        outside: tuple[str, ...] = (),
+        counted: bool = True,
+        exhausted: bool | None = None,
+        budget_state: TaskBudgetState | None = None,
+    ) -> AgentTaskRecord:
+        """`submitted` -> `rejected`, or `budget_exhausted` once every try is used.
+
+        The stored result's status says which: `failed` or `budget_exhausted`. A submit
+        that is not `counted` (an infra failure) uses no try. `exhausted` overrides the
+        default "every try used" (the loop's budget may stop earlier, or on infra);
+        `budget_state` replaces the record's.
+        """
+        record = self._transition(task_id, frozenset({"submitted"}), "reject")
+        attempts = record.attempts + (1 if counted else 0)
+        if exhausted is None:
+            exhausted = attempts >= record.tries
+        status: TaskStatus = "budget_exhausted" if exhausted else "rejected"
+        final = result.model_copy(update={"status": "budget_exhausted" if exhausted else "failed"})
+        update: dict[str, object] = {
+            "status": status,
+            "attempts": attempts,
+            "reasons": reasons,
+            "outside": outside,
+            "last_result": final,
+        }
+        if budget_state is not None:
+            update["budget_state"] = budget_state
+        return self._put(record.model_copy(update=update))
+
+    def needs_human(
+        self,
+        task_id: str,
+        *,
+        result: AgentResult,
+        budget_state: TaskBudgetState | None = None,
+    ) -> AgentTaskRecord:
+        """`dispatched`/`submitted` -> `needs_human`: a person must answer `open_questions`."""
+        if result.status != "needs_human":
+            raise QueueError("needs_human needs an AgentResult with status 'needs_human'")
+        record = self._transition(task_id, ACTIVE_STATUSES, "hand to a person")
+        update: dict[str, object] = {
+            "status": "needs_human",
+            "reasons": result.open_questions,
+            "last_result": result,
+        }
+        if budget_state is not None:
+            update["budget_state"] = budget_state
+        return self._put(record.model_copy(update=update))
+
+    def reopen(self, task_id: str) -> AgentTaskRecord | None:
+        """`budget_exhausted`/`needs_human` -> `ready`, with a fresh budget cycle.
+
+        A person's go-ahead to try a stopped task again (a rewind). Any other status, or
+        no record, is left alone (`None`). `dispatches` goes on, as in `enqueue`.
+        """
+        record = self.get(task_id)
+        if record is None or record.status not in ("budget_exhausted", "needs_human"):
+            return None
+        return self._put(
+            record.model_copy(
+                update={
+                    "status": "ready",
+                    "attempts": 0,
+                    "reasons": (),
+                    "outside": (),
+                    "last_result": None,
+                    "budget_state": None,
+                }
+            )
+        )
+
+
+__all__ = [
+    "ACTIVE_STATUSES",
+    "DEFAULT_TOOL_CALL_CAP",
+    "OPEN_STATUSES",
+    "AgentBinding",
+    "AgentTaskRecord",
+    "BudgetStop",
+    "QueueError",
+    "TaskBudgetState",
+    "TaskQueue",
+    "TaskStatus",
+    "state_key",
+]

chipgraph/core/runtime/roles/__init__.py

@@ -0,0 +1,91 @@
+"""Roles and skills as data (DESIGN.md 5.1, 5.4; D8).
+
+- `RoleSpec` (`spec`): one role's prompt and tool table: capabilities, write scope,
+  read policy, model tier and escalation tier. The built-in roles are files under
+  `data/` (`registry`: `get_role`, `list_roles`).
+- `SkillSpec`, `load_skills` (`skills`): skills the packs provide, checked per role.
+- `policy`: the tool table applied to rules (`check_agent_rules`), to a task's model
+  tiers (`model_ladder`) and to what its agent may read (`denied_reads`).
+- `ReviewReport`, `review_problems` (`review`): the structured reply of a role that
+  writes no files (the Critic), from which the engine writes the task's output.
+
+Generic: no harness, tool or project names. A runtime maps the abstract capabilities to
+its own tools (runtime `claude-code`: `chipgraph.adapters.runtime.claude_code.agents`).
+"""
+
+from chipgraph.core.runtime.roles.policy import (
+    LayoutValue,
+    check_agent_rules,
+    covers_denied,
+    denied_kind,
+    denied_reads,
+    model_ladder,
+    path_denied,
+    static_prefix,
+    task_denied_reads,
+)
+from chipgraph.core.runtime.roles.registry import find_role, get_role, list_roles, roles_dir
+from chipgraph.core.runtime.roles.review import (
+    ReviewComment,
+    ReviewReport,
+    ReviewScope,
+    diff_hunks,
+    parse_review,
+    review_problems,
+)
+from chipgraph.core.runtime.roles.skills import (
+    SkillError,
+    SkillId,
+    SkillSet,
+    SkillSpec,
+    load_skills,
+    parse_skill_file,
+)
+from chipgraph.core.runtime.roles.spec import (
+    CAPABILITIES,
+    Capability,
+    ReadPolicy,
+    RoleError,
+    RoleId,
+    RoleSpec,
+    WriteScope,
+    parse_role_file,
+    split_frontmatter,
+)
+
+__all__ = [
+    "CAPABILITIES",
+    "Capability",
+    "LayoutValue",
+    "ReadPolicy",
+    "ReviewComment",
+    "ReviewReport",
+    "ReviewScope",
+    "RoleError",
+    "RoleId",
+    "RoleSpec",
+    "SkillError",
+    "SkillId",
+    "SkillSet",
+    "SkillSpec",
+    "WriteScope",
+    "check_agent_rules",
+    "covers_denied",
+    "denied_kind",
+    "denied_reads",
+    "diff_hunks",
+    "find_role",
+    "get_role",
+    "list_roles",
+    "load_skills",
+    "model_ladder",
+    "parse_review",
+    "parse_role_file",
+    "parse_skill_file",
+    "path_denied",
+    "review_problems",
+    "roles_dir",
+    "split_frontmatter",
+    "static_prefix",
+    "task_denied_reads",
+]