shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/timeline_phrases.py

@@ -0,0 +1,271 @@
+"""Human one-line phrases for recorded engine events and normalized agent signals."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, cast
+
+from shikiru.agents.contracts import (
+    Compacted,
+    Message,
+    QuotaReported,
+    SessionStarted,
+    ToolFinished,
+    ToolOutcome,
+    ToolStarted,
+    TurnEnded,
+    TurnFailed,
+    UsageReported,
+)
+from shikiru.domain.events import EventKind
+
+if TYPE_CHECKING:
+    from shikiru.domain.events import Event
+
+GLYPH_OK = "\N{CHECK MARK}"
+GLYPH_FAIL = "\N{BALLOT X}"
+GLYPH_ATTENTION = "!"
+GLYPH_ALARM = "\N{DOUBLE EXCLAMATION MARK}\N{VARIATION SELECTOR-15}"
+NO_GLYPH = ""
+PHRASE_SEPARATOR = " · "
+SIGNAL_MESSAGE = Message.__name__
+SIGNAL_TOOL_STARTED = ToolStarted.__name__
+SIGNAL_TOOL_FINISHED = ToolFinished.__name__
+SIGNAL_TURN_ENDED = TurnEnded.__name__
+SIGNAL_TURN_FAILED = TurnFailed.__name__
+_BOOKKEEPING = frozenset(
+    {
+        SessionStarted.__name__,
+        UsageReported.__name__,
+        QuotaReported.__name__,
+        Compacted.__name__,
+    }
+)
+_WORD_SEPARATOR = " "
+_QUOTE = '"'
+_ROUND_WORD = "round"
+_LIST_SEPARATOR = ", "
+_EXIT_LABEL = "exit"
+_SUCCESS_EXIT_CODE = 0
+_TURN_ENDED_LABEL = "turn ended"
+_TASK_ID_SEPARATOR = " "
+_DETAIL_FIELDS = ("command", "file_path", "path", "pattern", "url", "query")
+_TOOL_VERBS = {
+    "Bash": "ran",
+    "command": "ran",
+    "Edit": "edited",
+    "MultiEdit": "edited",
+    "Write": "edited",
+    "NotebookEdit": "edited",
+    "file_change": "edited",
+    "Read": "read",
+    "Grep": "searched",
+    "Glob": "searched",
+}
+
+
+class Tone(StrEnum):
+    """How strongly a phrase should stand out."""
+
+    PLAIN = "plain"
+    SUCCESS = "success"
+    FAILURE = "failure"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass(frozen=True)
+class Phrase:
+    """A one-line human description with its status glyph and tone."""
+
+    text: str
+    glyph: str = NO_GLYPH
+    tone: Tone = Tone.PLAIN
+
+
+type Detail = Callable[[Event], str]
+
+
+@dataclass(frozen=True)
+class _EventSpec:
+    label: str
+    glyph: str = NO_GLYPH
+    tone: Tone = Tone.PLAIN
+    detail: Detail | None = None
+
+
+def _field(key: str) -> Detail:
+    def read(event: Event) -> str:
+        value = event.data.get(key)
+        return "" if value is None else str(value)
+
+    return read
+
+
+def _message(event: Event) -> str:
+    prefix = f"{event.task_id}{_TASK_ID_SEPARATOR}" if event.task_id else ""
+    return event.message.removeprefix(prefix)
+
+
+def _step_round(event: Event) -> str:
+    parts = [str(event.data.get("step", ""))]
+    iteration = event.data.get("iteration")
+    if isinstance(iteration, int) and iteration >= 1:
+        parts.append(f"{_ROUND_WORD} {iteration}")
+    return _LIST_SEPARATOR.join(part for part in parts if part)
+
+
+def _rung_change(event: Event) -> str:
+    moved = f"{event.data.get('from')} to {event.data.get('to')}"
+    return PHRASE_SEPARATOR.join(part for part in (_field("role")(event), moved) if part)
+
+
+def _new_tasks(event: Event) -> str:
+    count = len(event.data.get("new_task_ids") or ())
+    return f"{count} new" if count else ""
+
+
+_VERDICTS = {
+    "accept": Phrase("accepted", GLYPH_OK, Tone.SUCCESS),
+    "changes_requested": Phrase("changes requested", GLYPH_FAIL, Tone.FAILURE),
+    "escalate": Phrase("escalate", GLYPH_ATTENTION, Tone.WARNING),
+    "supersede": Phrase("superseded"),
+}
+_EVENTS: dict[str, _EventSpec] = {
+    EventKind.TASK_QUEUED: _EventSpec("task queued"),
+    EventKind.TASK_STARTED: _EventSpec("task started", detail=_field("slot")),
+    EventKind.DISPATCH_FAILED: _EventSpec(
+        "dispatch failed", GLYPH_FAIL, Tone.FAILURE, _field("error")
+    ),
+    EventKind.STEP_STARTED: _EventSpec("step started", detail=_step_round),
+    EventKind.TURN_STARTED: _EventSpec("turn started", detail=_field("role")),
+    EventKind.TURN_COMPLETED: _EventSpec("turn completed", GLYPH_OK, Tone.SUCCESS, _field("role")),
+    EventKind.TURN_FAILED: _EventSpec("turn failed", GLYPH_FAIL, Tone.FAILURE, _message),
+    EventKind.TURN_STOPPED: _EventSpec("turn stopped", detail=_field("role")),
+    EventKind.NUDGE: _EventSpec("nudge sent", GLYPH_ATTENTION, Tone.WARNING, _field("role")),
+    EventKind.HELPER_ACTION: _EventSpec("helper", GLYPH_ATTENTION, Tone.WARNING, _message),
+    EventKind.RUNG_CHANGED: _EventSpec("rung changed", GLYPH_ATTENTION, Tone.WARNING, _rung_change),
+    EventKind.COMPACTED: _EventSpec("context compacted", detail=_field("role")),
+    EventKind.QUOTA_BLOCKED: _EventSpec(
+        "quota blocked", GLYPH_ATTENTION, Tone.WARNING, _field("agent")
+    ),
+    EventKind.QUOTA_CLEARED: _EventSpec("quota cleared", detail=_field("agent")),
+    EventKind.SCOPE_CHANGE: _EventSpec("scope changed", detail=_new_tasks),
+    EventKind.HOLD_SET: _EventSpec("hold set", detail=_field("hold")),
+    EventKind.HOLD_CLEARED: _EventSpec("hold cleared", detail=_field("hold")),
+    EventKind.TAKEN_OVER: _EventSpec("taken over", detail=_field("role")),
+    EventKind.HANDED_BACK: _EventSpec("handed back", detail=_field("role")),
+    EventKind.TAKEOVER_LOST: _EventSpec(
+        "takeover lost", GLYPH_ATTENTION, Tone.WARNING, _field("role")
+    ),
+    EventKind.OPERATOR_MESSAGE: _EventSpec("operator message", detail=_field("role")),
+    EventKind.ESCALATION: _EventSpec("escalated", GLYPH_ALARM, Tone.CRITICAL, _message),
+    EventKind.ESCALATION_RESOLVED: _EventSpec(
+        "escalation resolved", GLYPH_OK, Tone.SUCCESS, _field("resolution")
+    ),
+    EventKind.INTEGRATION_STARTED: _EventSpec("integration started"),
+    EventKind.INTEGRATION_APPLYING: _EventSpec("integration applying"),
+    EventKind.INTEGRATION_WAITING: _EventSpec(
+        "integration waiting", GLYPH_ATTENTION, Tone.WARNING, _message
+    ),
+    EventKind.PR_OPENED: _EventSpec("PR opened", GLYPH_OK, Tone.SUCCESS, _field("url")),
+    EventKind.PR_WITHDRAWN: _EventSpec("PR withdrawn", detail=_field("url")),
+    EventKind.TASK_DONE: _EventSpec("task done", GLYPH_OK, Tone.SUCCESS, _message),
+    EventKind.TASK_RETRIED: _EventSpec("task retried"),
+    EventKind.TASK_CANCELLED: _EventSpec("task cancelled", GLYPH_FAIL, Tone.FAILURE),
+    EventKind.PANE_RESTORED: _EventSpec("pane restored", detail=_field("pane")),
+    EventKind.ENGINE_FAULT: _EventSpec("engine fault", GLYPH_FAIL, Tone.FAILURE, _message),
+}
+
+
+def kind_phrase(kind: str) -> Phrase | None:
+    """Return the label, glyph and tone of an engine event kind, or None when it is unlisted."""
+    spec = _EVENTS.get(kind)
+    return None if spec is None else Phrase(spec.label, spec.glyph, spec.tone)
+
+
+def verdict_phrase(decision: str) -> Phrase | None:
+    """Return the phrase of a verdict decision, or None when the decision is unknown."""
+    return _VERDICTS.get(decision)
+
+
+def _joined(label: str, detail: str) -> str:
+    return f"{label}{PHRASE_SEPARATOR}{detail}" if detail else label
+
+
+def event_phrase(event: Event) -> Phrase:
+    """Describe one engine event in a human phrase; an unlisted kind shows its recorded message."""
+    if event.kind is EventKind.VERDICT:
+        verdict = _VERDICTS.get(str(event.data.get("decision")))
+        if verdict is None:
+            return Phrase(_joined("verdict", event.message))
+        return Phrase(_joined("verdict", verdict.text), verdict.glyph, verdict.tone)
+    spec = _EVENTS.get(event.kind)
+    if spec is None:
+        return Phrase(event.message)
+    detail = spec.detail(event) if spec.detail is not None else ""
+    return Phrase(_joined(spec.label, detail), spec.glyph, spec.tone)
+
+
+def tool_target(detail: str) -> str:
+    """Return the command, path or query inside a tool's JSON detail, else the detail itself."""
+    try:
+        decoded: object = json.loads(detail)
+    except json.JSONDecodeError:
+        return detail
+    if not isinstance(decoded, dict):
+        return detail
+    fields = cast("dict[str, object]", decoded)
+    for key in _DETAIL_FIELDS:
+        value = fields.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return detail
+
+
+def _tool_started(data: Mapping[str, object]) -> Phrase:
+    name = str(data.get("name", ""))
+    target = tool_target(str(data.get("detail") or ""))
+    verb = _TOOL_VERBS.get(name, name)
+    return Phrase(" ".join(part for part in (verb, target) if part))
+
+
+def _tool_finished(data: Mapping[str, object]) -> Phrase | None:
+    outcome = data.get("outcome")
+    exit_code = data.get("exit_code")
+    has_exit = type(exit_code) is int
+    if outcome not in (ToolOutcome.SUCCESS.value, ToolOutcome.FAILURE.value) and not has_exit:
+        return None
+    failed = outcome == ToolOutcome.FAILURE.value or (
+        has_exit and exit_code != _SUCCESS_EXIT_CODE and outcome != ToolOutcome.SUCCESS.value
+    )
+    label = f"{_EXIT_LABEL} {exit_code}" if has_exit else str(outcome)
+    glyph, tone = (GLYPH_FAIL, Tone.FAILURE) if failed else (GLYPH_OK, Tone.SUCCESS)
+    return Phrase(_joined(str(data.get("name", "")), label), glyph, tone)
+
+
+def _message_text(data: Mapping[str, object], key: str) -> str:
+    return _WORD_SEPARATOR.join(str(data.get(key) or "").split())
+
+
+def signal_phrase(signal: str, data: Mapping[str, object]) -> Phrase | None:
+    """Describe one normalized agent signal; bookkeeping and empty signals have no phrase (None)."""
+    if signal == SIGNAL_MESSAGE:
+        text = _message_text(data, "text")
+        return Phrase(f"{_QUOTE}{text}{_QUOTE}") if text else None
+    if signal == SIGNAL_TOOL_STARTED:
+        return _tool_started(data)
+    if signal == SIGNAL_TOOL_FINISHED:
+        return _tool_finished(data)
+    if signal == SIGNAL_TURN_ENDED:
+        return Phrase(
+            _joined(_TURN_ENDED_LABEL, _message_text(data, "last_message")), GLYPH_OK, Tone.SUCCESS
+        )
+    if signal == SIGNAL_TURN_FAILED:
+        return Phrase(
+            f"{data.get('kind')}: {_message_text(data, 'message')}", GLYPH_FAIL, Tone.FAILURE
+        )
+    return None if signal in _BOOKKEEPING else Phrase(signal)

shikiru/domain/versions.py

@@ -0,0 +1,18 @@
+"""Reading and comparing the version a tool prints."""
+
+from __future__ import annotations
+
+import re
+
+VERSION_PATTERN = re.compile(r"(\d+)\.(\d+)")
+
+Version = tuple[int, int]
+
+
+def parse_version(text: str) -> Version | None:
+    """Return the first `major.minor` in `text`, ignoring suffixes like the `a` of `3.3a`."""
+    found = VERSION_PATTERN.search(text)
+    if found is None:
+        return None
+    major, minor = found.groups()
+    return int(major), int(minor)

shikiru/domain/workflow.py

@@ -0,0 +1,372 @@
+"""Pure recorded workflow history projection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from shikiru.domain.events import Event, EventKind
+from shikiru.domain.reports import (
+    DECISION_ACCEPT,
+    DECISION_ANSWER,
+    DECISION_CHANGES_REQUESTED,
+    STATUS_COMPLETED,
+    ConsultAnswer,
+    ImplementationReport,
+    PlanReport,
+    Report,
+    ReportKind,
+    TriageReport,
+    Verdict,
+)
+from shikiru.domain.tasks import Mode, Status, Step, Task
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+WORKFLOW_STEP_KEY = "step"
+WORKFLOW_ITERATION_KEY = "iteration"
+WORKFLOW_TURN_KEY = "turn"
+WORKFLOW_DECISION_KEY = "decision"
+
+
+class WorkflowMilestoneState(StrEnum):
+    """Recorded semantic outcome for one workflow stage."""
+
+    DONE = auto()
+    CURRENT = auto()
+    LATER = auto()
+    SKIPPED = auto()
+    REWORK = auto()
+    UNKNOWN = auto()
+    STOPPED = auto()
+
+
+@dataclass(frozen=True)
+class WorkflowReport:
+    """One already-validated agent report with its retained turn identity."""
+
+    turn: str
+    kind: ReportKind
+    data: Report
+
+
+@dataclass(frozen=True)
+class WorkflowMilestone:
+    """One stage and its recorded workflow outcome."""
+
+    stage: Step
+    state: WorkflowMilestoneState
+
+
+@dataclass(frozen=True)
+class WorkflowProgress:
+    """Milestones projected from bounded task history and its completeness signal."""
+
+    milestones: tuple[WorkflowMilestone, ...]
+    history_complete: bool
+
+
+@dataclass(frozen=True)
+class _StepEntry:
+    event_index: int
+    event_id: int
+    step: Step | None
+    iteration: int | None
+
+
+def project_workflow(
+    task: Task,
+    events: Sequence[Event],
+    reports: Sequence[WorkflowReport],
+    *,
+    event_window_complete: bool,
+) -> WorkflowProgress:
+    """Project factual milestones from retained transitions and validated agent reports."""
+    history_complete = (
+        event_window_complete and bool(events) and events[0].kind is EventKind.TASK_QUEUED
+    )
+    entries = _step_entries(events)
+    entered_steps = {entry.step for entry in entries if entry.step is not None}
+    first_entered_step = entries[0].step if entries else None
+    reported_steps = {
+        step for report in reports if (step := _report_stage(report.kind)) is not None
+    }
+    completed_reports = _completed_reports(reports, events, entries)
+    stages = _workflow_stages(task, entered_steps, reported_steps, entries)
+    if not stages:
+        return WorkflowProgress((), history_complete)
+    recorded = entered_steps | reported_steps
+    settled = _settled_milestones(task, stages, recorded)
+    if settled is not None:
+        return WorkflowProgress(settled, history_complete)
+    stage_positions = {step: index for index, step in enumerate(stages)}
+    current_position = stage_positions.get(task.step) if task.step is not None else None
+    last_entries = _last_step_entries(entries)
+    verdicts = _verdicts(events)
+
+    def milestone_state(step: Step) -> WorkflowMilestoneState:
+        if step is task.step:
+            state = WorkflowMilestoneState.CURRENT
+        elif (
+            step is Step.TRIAGE
+            and history_complete
+            and first_entered_step in {Step.PLAN, Step.IMPLEMENT}
+        ):
+            state = WorkflowMilestoneState.SKIPPED
+        elif step in entered_steps | reported_steps:
+            latest_entry = last_entries.get(step)
+            later_steps = {
+                entry.step
+                for entry in entries
+                if latest_entry is not None
+                and entry.step is not None
+                and entry.event_index > latest_entry.event_index
+            }
+            rework_requested = step is Step.VERIFY and any(
+                index > (latest_entry.event_index if latest_entry is not None else -1)
+                and decision == DECISION_CHANGES_REQUESTED
+                for index, decision in verdicts
+            )
+            if rework_requested:
+                state = WorkflowMilestoneState.REWORK
+            elif _completed_by_later_step(step, later_steps) or _report_completes_entered_stage(
+                step,
+                latest_entry.event_id if latest_entry is not None else None,
+                completed_reports,
+            ):
+                state = WorkflowMilestoneState.DONE
+            else:
+                state = WorkflowMilestoneState.UNKNOWN
+        elif current_position is not None and stage_positions[step] > current_position:
+            state = WorkflowMilestoneState.LATER
+        else:
+            state = WorkflowMilestoneState.UNKNOWN
+        return state
+
+    milestones = tuple(
+        WorkflowMilestone(
+            stage=step,
+            state=milestone_state(step),
+        )
+        for step in stages
+    )
+    return WorkflowProgress(milestones, history_complete)
+
+
+def _settled_milestones(
+    task: Task, stages: tuple[Step, ...], recorded: set[Step]
+) -> tuple[WorkflowMilestone, ...] | None:
+    if task.status in (Status.DONE, Status.CANCELLED):
+        return _terminal_milestones(task, stages, recorded)
+    if task.step is None and not recorded:
+        return tuple(WorkflowMilestone(step, WorkflowMilestoneState.LATER) for step in stages)
+    return None
+
+
+def _terminal_milestones(
+    task: Task, stages: tuple[Step, ...], recorded: set[Step]
+) -> tuple[WorkflowMilestone, ...]:
+    def state(step: Step) -> WorkflowMilestoneState:
+        if task.status is Status.CANCELLED and step is task.step:
+            return WorkflowMilestoneState.STOPPED
+        if step in recorded or (step is Step.INTEGRATE and task.status is Status.DONE):
+            return WorkflowMilestoneState.DONE
+        return WorkflowMilestoneState.SKIPPED
+
+    return tuple(WorkflowMilestone(step, state(step)) for step in stages)
+
+
+def _step_entries(events: Sequence[Event]) -> list[_StepEntry]:
+    entries: list[_StepEntry] = []
+    for index, event in enumerate(events):
+        value = event.data.get(WORKFLOW_STEP_KEY)
+        if event.kind is not EventKind.STEP_STARTED:
+            continue
+        try:
+            step = Step(value) if isinstance(value, str) else None
+        except ValueError:
+            step = None
+        iteration = event.data.get(WORKFLOW_ITERATION_KEY)
+        entries.append(
+            _StepEntry(
+                index,
+                event.id,
+                step,
+                iteration if type(iteration) is int else None,
+            )
+        )
+    return entries
+
+
+def _completed_reports(
+    reports: Sequence[WorkflowReport],
+    events: Sequence[Event],
+    entries: list[_StepEntry],
+) -> set[tuple[Step, int]]:
+    report_entries: dict[str, tuple[Step, int]] = {}
+    for index, event in enumerate(events):
+        turn = event.data.get(WORKFLOW_TURN_KEY)
+        step_value = event.data.get(WORKFLOW_STEP_KEY)
+        iteration = event.data.get(WORKFLOW_ITERATION_KEY)
+        if (
+            event.kind is EventKind.TURN_STARTED
+            and isinstance(turn, str)
+            and isinstance(step_value, str)
+            and type(iteration) is int
+        ):
+            try:
+                step = Step(step_value)
+            except ValueError:
+                continue
+            if not entries:
+                continue
+            latest_entry = next(
+                (entry for entry in reversed(entries) if entry.event_index < index),
+                None,
+            )
+            if latest_entry is None or (latest_entry.step, latest_entry.iteration) != (
+                step,
+                iteration,
+            ):
+                continue
+            report_entries[turn] = (step, latest_entry.event_id)
+    completed: set[tuple[Step, int]] = set()
+    for report in reports:
+        stage = _report_stage(report.kind)
+        if stage is None or not _report_completes_stage(report.data):
+            continue
+        report_entry = report_entries.get(report.turn)
+        if report_entry is not None and report_entry[0] is stage:
+            completed.add((stage, report_entry[1]))
+    return completed
+
+
+def _last_step_entries(
+    entries: list[_StepEntry],
+) -> dict[Step, _StepEntry]:
+    last_entries: dict[Step, _StepEntry] = {}
+    for entry in entries:
+        if entry.step is not None:
+            last_entries[entry.step] = entry
+    return last_entries
+
+
+def _verdicts(events: Sequence[Event]) -> list[tuple[int, object]]:
+    return [
+        (index, event.data.get(WORKFLOW_DECISION_KEY))
+        for index, event in enumerate(events)
+        if event.kind is EventKind.VERDICT
+    ]
+
+
+def _workflow_stages(
+    task: Task,
+    entered_steps: set[Step],
+    reported_steps: set[Step],
+    entries: list[_StepEntry],
+) -> tuple[Step, ...]:
+    observed_steps = entered_steps | reported_steps
+    if task.mode is Mode.PLAN or task.step is Step.PLAN or Step.PLAN in observed_steps:
+        stages = [Step.TRIAGE, Step.PLAN, Step.INTEGRATE]
+        if Step.CONSULT in observed_steps or task.step is Step.CONSULT:
+            stages.append(Step.CONSULT)
+        if Step.VERIFY in entered_steps or task.step is Step.VERIFY:
+            stages.append(Step.VERIFY)
+        return tuple(stages)
+    if (
+        task.mode is Mode.IMPLEMENT
+        or task.step
+        in {
+            Step.IMPLEMENT,
+            Step.CONSULT,
+            Step.VERIFY,
+            Step.INTEGRATE,
+        }
+        or observed_steps & {Step.IMPLEMENT, Step.CONSULT, Step.VERIFY, Step.INTEGRATE}
+    ):
+        stages = [Step.TRIAGE, Step.IMPLEMENT, Step.VERIFY, Step.INTEGRATE]
+    elif task.step is Step.TRIAGE:
+        stages = [Step.TRIAGE]
+    else:
+        return ()
+    if Step.CONSULT in observed_steps or task.step is Step.CONSULT:
+        if _consult_follows_integration(task, entries):
+            stages.append(Step.CONSULT)
+        else:
+            stages.insert(stages.index(Step.IMPLEMENT) + 1, Step.CONSULT)
+    return tuple(stages)
+
+
+def _consult_follows_integration(task: Task, entries: list[_StepEntry]) -> bool:
+    if task.step is Step.CONSULT and task.status is Status.INTEGRATING:
+        return True
+    for index in range(len(entries) - 1, -1, -1):
+        entry = entries[index]
+        if entry.step is not Step.CONSULT or entry.iteration != task.iteration:
+            continue
+        if index == 0:
+            return False
+        previous = entries[index - 1]
+        return previous.step is Step.INTEGRATE and previous.iteration == task.iteration
+    if task.step is Step.CONSULT and entries:
+        latest = entries[-1]
+        return latest.step is Step.INTEGRATE and latest.iteration == task.iteration
+    return False
+
+
+def _completed_by_later_step(stage: Step, later_steps: set[Step]) -> bool:
+    match stage:
+        case Step.TRIAGE:
+            return bool(later_steps & {Step.PLAN, Step.IMPLEMENT})
+        case Step.PLAN:
+            return Step.INTEGRATE in later_steps
+        case Step.IMPLEMENT:
+            return bool(later_steps & {Step.VERIFY, Step.CONSULT})
+        case Step.CONSULT:
+            return bool(later_steps & {Step.IMPLEMENT, Step.INTEGRATE})
+        case Step.VERIFY:
+            return Step.INTEGRATE in later_steps
+        case Step.INTEGRATE:
+            return False
+
+
+def _report_stage(kind: ReportKind) -> Step | None:
+    match kind:
+        case ReportKind.TRIAGE:
+            return Step.TRIAGE
+        case ReportKind.PLAN:
+            return Step.PLAN
+        case ReportKind.IMPLEMENTATION:
+            return Step.IMPLEMENT
+        case ReportKind.CONSULT:
+            return Step.CONSULT
+        case ReportKind.VERDICT:
+            return Step.VERIFY
+        case (
+            ReportKind.FEEDBACK_ANALYSIS | ReportKind.FEEDBACK_REWORK | ReportKind.FEEDBACK_VERDICT
+        ):
+            return None
+
+
+def _report_completes_stage(report: Report) -> bool:
+    match report:
+        case TriageReport() | PlanReport():
+            return True
+        case ImplementationReport(status=status) if status == STATUS_COMPLETED:
+            return True
+        case ConsultAnswer(decision=decision) if decision == DECISION_ANSWER:
+            return True
+        case Verdict(decision=decision) if decision == DECISION_ACCEPT:
+            return True
+        case _:
+            return False
+
+
+def _report_completes_entered_stage(
+    stage: Step,
+    entered_identity: int | None,
+    completed_reports: set[tuple[Step, int]],
+) -> bool:
+    return entered_identity is not None and (stage, entered_identity) in completed_reports