shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/briefing.py

@@ -0,0 +1,257 @@
+"""Pure derivations behind the task briefing: rework, verdict, produced work, tests and PR."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from shikiru.domain.reports import DECISION_ACCEPT
+from shikiru.domain.tasks import Hold, Status
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from shikiru.domain.reports import TestRun, Verdict
+
+FACTS_COMMITS_HEADING = "### Commits (base..HEAD)"
+FACTS_DIFF_STAT_HEADING = "### Diff stat (base...HEAD)"
+FACTS_NONE_MARKER = "(none)"
+PR_OPEN_STATE = "OPEN"
+PR_MERGED_STATE = "MERGED"
+PR_URL_KEY = "url"
+PR_STATE_KEY = "state"
+PR_CHECKS_PENDING_KEY = "checks_pending"
+PR_CHECKS_FAILING_KEY = "checks_failing"
+MAX_BRIEFING_ACTIONS = 4
+FIRST_PASS_ITERATION = 1
+LAST_WORDS_ELLIPSIS = "…"
+_FACTS_SECTION_BREAK = "\n\n"
+_FACTS_PARTS = 4
+_DIFF_SUMMARY = re.compile(
+    r"(?P<files>\d+) files? changed"
+    r"(?:, (?P<insertions>\d+) insertions?\(\+\))?"
+    r"(?:, (?P<deletions>\d+) deletions?\(-\))?"
+)
+_PR_NUMBER = re.compile(r"/pull/(?P<number>\d+)/?$")
+
+
+class BriefingAction(StrEnum):
+    """A briefing verb, declared in offer order; each value is the palette action it opens."""
+
+    ANSWER = "resolve"
+    TAKE_OVER = "take-over"
+    HAND_BACK = "hand-back"
+    MESSAGE = "message"
+    PAUSE = "pause"
+    RESUME = "resume"
+    CANCEL = "cancel"
+
+
+@dataclass(frozen=True)
+class VerdictCounts:
+    """A verdict's decision and its issues counted by severity."""
+
+    decision: str
+    blocker: int
+    major: int
+    minor: int
+
+    @property
+    def has_problems(self) -> bool:
+        """Whether the verdict is anything but a clean accept."""
+        return self.decision != DECISION_ACCEPT or bool(self.blocker or self.major or self.minor)
+
+
+@dataclass(frozen=True)
+class ProducedNumbers:
+    """Commits, files and lines recorded in the facts snapshot."""
+
+    commits: int
+    files: int
+    insertions: int
+    deletions: int
+
+
+@dataclass(frozen=True)
+class ReportedTests:
+    """Agent-reported test results by outcome."""
+
+    passed: int
+    failed: int
+    skipped: int
+
+
+@dataclass(frozen=True)
+class PullRequestLine:
+    """The recorded pull request; checks are set only when the engine recorded them."""
+
+    state: str
+    url: str | None
+    number: int | None
+    checks_pending: bool | None
+    checks_failing: bool | None
+
+
+def escalation_remaining(
+    rejections_on_rung: int, escalate_after: int, *, can_escalate: bool
+) -> int | None:
+    """Return the rejections left before the Implementer's rung escalates automatically.
+
+    The counter counts rework at one rung; the rejection that makes it reach `escalate_after`
+    moves the rung up, so the remainder is only meaningful once a rejection happened and the
+    ladder still has a higher rung.
+    """
+    remaining = escalate_after - rejections_on_rung
+    if rejections_on_rung < 1 or not can_escalate or remaining < 1:
+        return None
+    return remaining
+
+
+def verdict_counts(verdict: Verdict) -> VerdictCounts:
+    """Count `verdict`'s issues by severity beside its decision."""
+    return severity_counts(verdict.decision, [issue.severity for issue in verdict.issues])
+
+
+def severity_counts(decision: str, severities: Sequence[str]) -> VerdictCounts:
+    """Count `severities` by level beside `decision`."""
+    return VerdictCounts(
+        decision,
+        severities.count("blocker"),
+        severities.count("major"),
+        severities.count("minor"),
+    )
+
+
+def reported_tests(tests: Sequence[TestRun]) -> ReportedTests:
+    """Count `tests` by their reported result."""
+    results = [test.result for test in tests]
+    return ReportedTests(results.count("passed"), results.count("failed"), results.count("skipped"))
+
+
+def _facts_blocks(facts: str | None) -> tuple[str, str] | None:
+    if facts is None:
+        return None
+    parts = facts.split(_FACTS_SECTION_BREAK)
+    if len(parts) < _FACTS_PARTS:
+        return None
+    commits_heading, commits_block, diff_heading, diff_block, *_ = parts
+    if commits_heading != FACTS_COMMITS_HEADING or diff_heading != FACTS_DIFF_STAT_HEADING:
+        return None
+    return commits_block, diff_block
+
+
+def facts_commit_lines(facts: str | None) -> tuple[str, ...]:
+    """Return the one-line commits of rendered facts, empty when none or unreadable."""
+    blocks = _facts_blocks(facts)
+    if blocks is None or blocks[0] == FACTS_NONE_MARKER:
+        return ()
+    return tuple(blocks[0].splitlines())
+
+
+def parse_produced(facts: str | None) -> ProducedNumbers | None:
+    """Read the commit count and diff summary from rendered facts, or None when unreadable.
+
+    An empty diff prints no summary line and renders as `(none)`, which is zero change.
+    """
+    blocks = _facts_blocks(facts)
+    if blocks is None:
+        return None
+    commits = len(facts_commit_lines(facts))
+    diff_block = blocks[1]
+    if diff_block == FACTS_NONE_MARKER:
+        return ProducedNumbers(commits, 0, 0, 0)
+    summary = _DIFF_SUMMARY.search(diff_block.strip().splitlines()[-1])
+    if summary is None:
+        return None
+    return ProducedNumbers(
+        commits,
+        int(summary["files"]),
+        int(summary["insertions"] or 0),
+        int(summary["deletions"] or 0),
+    )
+
+
+def pull_request_line(data: Mapping[str, object], *, task_done: bool = False) -> PullRequestLine:
+    """Describe the latest recorded pull request event; an open event records no state yet.
+
+    A Done task has its pull request merged, whatever the last recorded event said.
+    """
+    url = data.get(PR_URL_KEY)
+    state = data.get(PR_STATE_KEY)
+    link = url if isinstance(url, str) else None
+    match = _PR_NUMBER.search(link) if link is not None else None
+    pending = data.get(PR_CHECKS_PENDING_KEY)
+    failing = data.get(PR_CHECKS_FAILING_KEY)
+    return PullRequestLine(
+        state=PR_MERGED_STATE
+        if task_done
+        else (state if isinstance(state, str) else PR_OPEN_STATE),
+        url=link,
+        number=int(match["number"]) if match is not None else None,
+        checks_pending=pending if isinstance(pending, bool) else None,
+        checks_failing=failing if isinstance(failing, bool) else None,
+    )
+
+
+def squashed(text: str) -> str | None:
+    """Collapse the whitespace runs of `text` to single spaces, or None when it is blank."""
+    return " ".join(text.split()) or None
+
+
+def one_line(text: str, limit: int) -> str | None:
+    """Collapse `text` to one line of at most `limit` characters, or None when it is blank."""
+    collapsed = squashed(text)
+    if collapsed is None:
+        return None
+    if len(collapsed) <= limit:
+        return collapsed
+    return collapsed[: limit - len(LAST_WORDS_ELLIPSIS)].rstrip() + LAST_WORDS_ELLIPSIS
+
+
+def briefing_actions(
+    status: Status,
+    holds: Sequence[str],
+    *,
+    operator_owned: bool,
+    can_take_over: bool = False,
+    waiting: bool = False,
+) -> tuple[BriefingAction, ...]:
+    """Return the at most four verbs the briefing offers for a task in this state.
+
+    A decision comes first, then the ownership hand-over, a message, and the pause hold's
+    opposite; Cancel always closes the row of an unfinished task and a finished task offers
+    none. Take over is offered whenever the operator action can work (`can_take_over`, the
+    palette's own availability for the acting role). A waiting task has no agent to read a
+    message, so it offers none. An intervention hold is cleared by handing back, so it never
+    offers Resume.
+    """
+    if status in (Status.DONE, Status.CANCELLED):
+        return ()
+    verbs: list[BriefingAction] = []
+    if status is Status.ESCALATED:
+        verbs.append(BriefingAction.ANSWER)
+    if operator_owned:
+        verbs.append(BriefingAction.HAND_BACK)
+    elif can_take_over:
+        verbs.append(BriefingAction.TAKE_OVER)
+    if not waiting:
+        verbs.append(BriefingAction.MESSAGE)
+    if Hold.PAUSED.value in holds:
+        verbs.append(BriefingAction.RESUME)
+    elif not holds:
+        verbs.append(BriefingAction.PAUSE)
+    return (*verbs[: MAX_BRIEFING_ACTIONS - 1], BriefingAction.CANCEL)
+
+
+def rework_progress(iteration: int, max_iterations: int) -> tuple[int, int] | None:
+    """Return `(reworks so far, reworks allowed)`, or None until the first rework.
+
+    `iteration` counts implement/verify rounds from 1, so the first pass is not a rework, and
+    the round that reaches `max_iterations` is the final one: `max_iterations - 1` reworks fit.
+    """
+    allowed = max_iterations - FIRST_PASS_ITERATION
+    if iteration <= FIRST_PASS_ITERATION or allowed < 1:
+        return None
+    return iteration - FIRST_PASS_ITERATION, allowed

shikiru/domain/commands.py

@@ -0,0 +1,219 @@
+"""Operator command models, discriminated by `kind` for storage."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from shikiru.agents.contracts import Rung
+from shikiru.config.settings import ComplexityName
+from shikiru.domain.tasks import DomainModel, Mode, Role
+
+COMMAND_ID_KEY = "command_id"
+EVENT_TEXT_KEY = "text"
+COMMAND_POLL_SECONDS = 0.25
+COMMAND_RESULT_ERROR_KEY = "error"
+COMMAND_REJECTED_FALLBACK = "engine rejected the command"
+
+
+class CommandStatus(StrEnum):
+    """The `commands.status` lifecycle."""
+
+    PENDING = auto()
+    DONE = auto()
+    REJECTED = auto()
+
+
+class CommandKind(StrEnum):
+    """The `commands.kind` discriminator."""
+
+    SUBMIT = auto()
+    PRIORITIZE = auto()
+    PAUSE = auto()
+    RESUME = auto()
+    CANCEL = auto()
+    RETRY = auto()
+    SET_RUNG = auto()
+    SAY = auto()
+    TAKE_OVER = auto()
+    HAND_BACK = auto()
+    RESOLVE = auto()
+    STOP = auto()
+
+
+class IdentifiedCommand(DomainModel):
+    """A command whose effects are recognised on replay by the queue row id it is read with."""
+
+    command_id: int | None = None
+
+
+class Submit(DomainModel):
+    """`submit "<request>" [flags]`: the queue allocates the task id when appending it."""
+
+    kind: Literal[CommandKind.SUBMIT] = CommandKind.SUBMIT
+    task_id: str | None = None
+    title: str
+    request: str
+    mode: Mode | None = None
+    complexity: ComplexityName | None = None
+    priority: int = 0
+    depends_on: list[str] = Field(default_factory=list)
+    leader: Rung | None = None
+    implementer: Rung | None = None
+
+
+class Prioritize(DomainModel):
+    """`prioritize T-n N`: sets a task's dispatch priority."""
+
+    kind: Literal[CommandKind.PRIORITIZE] = CommandKind.PRIORITIZE
+    task_id: str
+    priority: int
+
+
+class Pause(DomainModel):
+    """`pause T-n [--now]`: holds a task; `now` also interrupts and cancels the current step."""
+
+    kind: Literal[CommandKind.PAUSE] = CommandKind.PAUSE
+    task_id: str
+    now: bool = False
+
+
+class Resume(DomainModel):
+    """`resume T-n`: clears the `paused` hold, or injects `continue` when it was `intervention`."""
+
+    kind: Literal[CommandKind.RESUME] = CommandKind.RESUME
+    task_id: str
+
+
+class Cancel(IdentifiedCommand):
+    """`cancel T-n`: cancels a task and keeps its branch."""
+
+    kind: Literal[CommandKind.CANCEL] = CommandKind.CANCEL
+    task_id: str
+
+
+class Retry(IdentifiedCommand):
+    """`retry T-n`: cancels and re-runs the task's current step."""
+
+    kind: Literal[CommandKind.RETRY] = CommandKind.RETRY
+    task_id: str
+
+
+class SetRung(DomainModel):
+    """`rung T-n <role> <agent:model:effort>`: overrides a role's rung from the next turn."""
+
+    kind: Literal[CommandKind.SET_RUNG] = CommandKind.SET_RUNG
+    task_id: str
+    role: Role
+    rung: Rung
+
+
+class Say(IdentifiedCommand):
+    """`say T-n <role> "<text>"`: queues a message for the role's next turn.
+
+    The queue fills `command_id` so a replayed delivery is recognised.
+    """
+
+    kind: Literal[CommandKind.SAY] = CommandKind.SAY
+    task_id: str
+    role: Role
+    text: str
+
+
+class TakeOver(IdentifiedCommand):
+    """`take-over T-n <role>`: stops the turn and opens the role's session in its pane."""
+
+    kind: Literal[CommandKind.TAKE_OVER] = CommandKind.TAKE_OVER
+    task_id: str
+    role: Role
+
+
+class HandBack(IdentifiedCommand):
+    """`hand-back T-n <role>`: returns a taken-over session to the engine.
+
+    The queue fills `command_id` so a replayed delivery is recognised.
+    """
+
+    kind: Literal[CommandKind.HAND_BACK] = CommandKind.HAND_BACK
+    task_id: str
+    role: Role
+
+
+class ResolutionKind(StrEnum):
+    """The `resolve` answer's discriminator."""
+
+    ANSWER = auto()
+    RETRY = auto()
+    ACCEPT = auto()
+    CANCEL = auto()
+
+
+class AnswerResolution(DomainModel):
+    """`resolve E-n <answer TEXT>`: runs a consult turn with the Operator's text."""
+
+    kind: Literal[ResolutionKind.ANSWER] = ResolutionKind.ANSWER
+    text: str
+
+
+class RetryResolution(DomainModel):
+    """`resolve E-n retry [--rung a:m:e]`: re-runs the failed step, optionally on a new rung."""
+
+    kind: Literal[ResolutionKind.RETRY] = ResolutionKind.RETRY
+    rung: Rung | None = None
+
+
+class AcceptResolution(DomainModel):
+    """`resolve E-n accept`: integrates the task as-is."""
+
+    kind: Literal[ResolutionKind.ACCEPT] = ResolutionKind.ACCEPT
+
+
+class CancelResolution(DomainModel):
+    """`resolve E-n cancel`: cancels the task and keeps its branch."""
+
+    kind: Literal[ResolutionKind.CANCEL] = ResolutionKind.CANCEL
+
+
+Resolution = Annotated[
+    AnswerResolution | RetryResolution | AcceptResolution | CancelResolution,
+    Field(discriminator="kind"),
+]
+
+
+class Resolve(IdentifiedCommand):
+    """`resolve E-n <...>`: resolves an open escalation."""
+
+    kind: Literal[CommandKind.RESOLVE] = CommandKind.RESOLVE
+    escalation_id: str
+    resolution: Resolution
+
+
+class Stop(DomainModel):
+    """`stop`: stops the engine; panes and their turns keep running."""
+
+    kind: Literal[CommandKind.STOP] = CommandKind.STOP
+
+
+Command = Annotated[
+    Submit
+    | Prioritize
+    | Pause
+    | Resume
+    | Cancel
+    | Retry
+    | SetRung
+    | Say
+    | TakeOver
+    | HandBack
+    | Resolve
+    | Stop,
+    Field(discriminator="kind"),
+]
+
+
+def command_rejection_cause(result: dict[str, object] | None) -> str:
+    """Return the engine's `error` text from a rejected command's result, else a fixed phrase."""
+    error = None if result is None else result.get(COMMAND_RESULT_ERROR_KEY)
+    return error if isinstance(error, str) else COMMAND_REJECTED_FALLBACK

shikiru/domain/decisions.py

@@ -0,0 +1,231 @@
+"""Pure derivation of a task's Decisions: a chronological log of who decided what."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, cast
+
+from shikiru.domain.briefing import pull_request_line, squashed
+from shikiru.domain.commands import EVENT_TEXT_KEY, ResolutionKind
+from shikiru.domain.events import EventKind
+from shikiru.domain.reports import (
+    DECISION_ACCEPT,
+    DECISION_ESCALATE,
+    DECISION_SUPERSEDE,
+    SEVERITY_BLOCKER,
+)
+from shikiru.domain.tasks import Hold
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from datetime import datetime
+
+    from shikiru.domain.events import Event
+
+MAX_DETAIL_LINES = 3
+DECISION_KEY = "decision"
+SUMMARY_KEY = "summary"
+ISSUES_KEY = "issues"
+SEVERITY_KEY = "severity"
+DESCRIPTION_KEY = "description"
+LOCATION_KEY = "location"
+RESOLUTION_KEY = "resolution"
+ROLE_KEY = "role"
+HOLD_KEY = "hold"
+NEW_TASKS_KEY = "new_task_ids"
+SCOPE_CHANGES_KEY = "scope_changes"
+RUNG_FROM_KEY = "from"
+RUNG_TO_KEY = "to"
+OPERATOR_KEY = "operator"
+_SEVERITY_ORDER = {SEVERITY_BLOCKER: 0, "major": 1, "minor": 2}
+_UNRANKED = len(_SEVERITY_ORDER)
+_VERDICT_WORDS = {DECISION_ACCEPT: "accepted", DECISION_SUPERSEDE: "superseded"}
+
+
+class Decider(StrEnum):
+    """Who made a decision, as the Decisions rows name them."""
+
+    LEADER = "Leader"
+    YOU = "You"
+    ENGINE = "Engine"
+
+
+@dataclass(frozen=True)
+class DecisionEntry:
+    """One decision: when, by whom, a what/why headline and its capped detail lines."""
+
+    at: datetime
+    decider: Decider
+    headline: str
+    details: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class TaskDecisions:
+    """A task's decisions, oldest first."""
+
+    entries: tuple[DecisionEntry, ...]
+
+
+def _text(data: dict[str, object], key: str) -> str | None:
+    value = data.get(key)
+    return squashed(value) if isinstance(value, str) else None
+
+
+def _items(data: dict[str, object], key: str) -> list[object]:
+    value = data.get(key)
+    return cast("list[object]", value) if isinstance(value, list) else []
+
+
+def _entry(event: Event, decider: Decider, headline: str, *details: str) -> DecisionEntry:
+    return DecisionEntry(event.ts, decider, headline, details[:MAX_DETAIL_LINES])
+
+
+def _issue_line(issue: dict[str, object]) -> str | None:
+    description = _text(issue, DESCRIPTION_KEY)
+    location = _text(issue, LOCATION_KEY)
+    if description is None:
+        return None
+    return f"{description} ({location})" if location else description
+
+
+def _issue_lines(data: dict[str, object]) -> list[str]:
+    issues = cast(
+        "list[dict[str, object]]",
+        [issue for issue in _items(data, ISSUES_KEY) if isinstance(issue, dict)],
+    )
+    ranked = sorted(
+        issues,
+        key=lambda issue: _SEVERITY_ORDER.get(str(issue.get(SEVERITY_KEY)), _UNRANKED),
+    )
+    return [line for line in map(_issue_line, ranked) if line is not None]
+
+
+def _verdict(event: Event, _: str | None) -> DecisionEntry | None:
+    decision = str(event.data.get(DECISION_KEY))
+    if decision == DECISION_ESCALATE:
+        return None
+    summary = _text(event.data, SUMMARY_KEY)
+    headline = _VERDICT_WORDS.get(decision, decision.replace("_", " "))
+    return _entry(
+        event, Decider.LEADER, headline, *([summary] if summary else []), *_issue_lines(event.data)
+    )
+
+
+def _escalation(event: Event, _: str | None) -> DecisionEntry:
+    question = squashed(event.message)
+    return _entry(event, Decider.LEADER, f"escalated: {question}" if question else "escalated")
+
+
+def _resolution(event: Event, _: str | None) -> DecisionEntry | None:
+    answer = _text(event.data, EVENT_TEXT_KEY)
+    headlines = {
+        ResolutionKind.ANSWER.value: f'answered "{answer}"' if answer else "answered",
+        ResolutionKind.RETRY.value: "retried",
+        ResolutionKind.ACCEPT.value: "accepted as is",
+    }
+    headline = headlines.get(str(event.data.get(RESOLUTION_KEY)))
+    return _entry(event, Decider.YOU, headline) if headline is not None else None
+
+
+def _scope_change(event: Event, _: str | None) -> DecisionEntry:
+    added = [str(task) for task in _items(event.data, NEW_TASKS_KEY)]
+    scope = [
+        text for text in map(squashed, map(str, _items(event.data, SCOPE_CHANGES_KEY))) if text
+    ]
+    return _entry(
+        event, Decider.LEADER, f"added {', '.join(added)}" if added else "scope changed", *scope
+    )
+
+
+def _role(event: Event) -> str:
+    return str(event.data.get(ROLE_KEY)).capitalize()
+
+
+def _rung_change(event: Event, _: str | None) -> DecisionEntry:
+    decider = Decider.YOU if event.data.get(OPERATOR_KEY) else Decider.ENGINE
+    old = event.data.get(RUNG_FROM_KEY)
+    lead = (
+        f"{_role(event)}: {old} \N{RIGHTWARDS ARROW}"
+        if old
+        else f"{_role(event)} \N{RIGHTWARDS ARROW}"
+    )
+    return _entry(event, decider, f"{lead} {event.data.get(RUNG_TO_KEY)}")
+
+
+def _operator_message(event: Event, _: str | None) -> DecisionEntry:
+    text = _text(event.data, EVENT_TEXT_KEY)
+    return _entry(
+        event,
+        Decider.YOU,
+        f'messaged {_role(event)} "{text}"' if text else f"messaged {_role(event)}",
+    )
+
+
+def _you(headline: str) -> Callable[[Event, str | None], DecisionEntry]:
+    return lambda event, _: _entry(event, Decider.YOU, headline)
+
+
+def _role_action(verb: str) -> Callable[[Event, str | None], DecisionEntry]:
+    return lambda event, _: _entry(event, Decider.YOU, f"{verb} {_role(event)}")
+
+
+def _paused(headline: str) -> Callable[[Event, str | None], DecisionEntry | None]:
+    def build(event: Event, _: str | None) -> DecisionEntry | None:
+        return (
+            _entry(event, Decider.YOU, headline)
+            if event.data.get(HOLD_KEY) == Hold.PAUSED.value
+            else None
+        )
+
+    return build
+
+
+def _pull_request(verb: str) -> Callable[[Event, str | None], DecisionEntry]:
+    def build(event: Event, _: str | None) -> DecisionEntry:
+        number = pull_request_line(event.data).number
+        return _entry(event, Decider.ENGINE, f"PR #{number} {verb}" if number else f"PR {verb}")
+
+    return build
+
+
+def _done(event: Event, pull_request: str | None) -> DecisionEntry:
+    return _entry(event, Decider.ENGINE, f"{pull_request} merged" if pull_request else "merged")
+
+
+_BUILDERS: dict[EventKind, Callable[[Event, str | None], DecisionEntry | None]] = {
+    EventKind.VERDICT: _verdict,
+    EventKind.ESCALATION: _escalation,
+    EventKind.ESCALATION_RESOLVED: _resolution,
+    EventKind.SCOPE_CHANGE: _scope_change,
+    EventKind.RUNG_CHANGED: _rung_change,
+    EventKind.OPERATOR_MESSAGE: _operator_message,
+    EventKind.TAKEN_OVER: _role_action("took over"),
+    EventKind.HANDED_BACK: _role_action("handed back"),
+    EventKind.HOLD_SET: _paused("paused"),
+    EventKind.HOLD_CLEARED: _paused("resumed"),
+    EventKind.TASK_RETRIED: _you("retried"),
+    EventKind.TASK_CANCELLED: _you("cancelled"),
+    EventKind.PR_OPENED: _pull_request("opened"),
+    EventKind.PR_WITHDRAWN: _pull_request("withdrawn"),
+    EventKind.TASK_DONE: _done,
+}
+
+
+def derive_decisions(events: Sequence[Event]) -> TaskDecisions:
+    """Derive a task's decision log from its recorded events, oldest first.
+
+    Events of other kinds are ignored; a cancelling resolution is shown by the cancel event.
+    """
+    entries: list[DecisionEntry] = []
+    pull_request: str | None = None
+    for event in sorted(events, key=lambda recorded: recorded.id):
+        if event.kind is EventKind.PR_OPENED:
+            number = pull_request_line(event.data).number
+            pull_request = f"PR #{number}" if number else "PR"
+        builder = _BUILDERS.get(event.kind)
+        entry = builder(event, pull_request) if builder is not None else None
+        if entry is not None:
+            entries.append(entry)
+    return TaskDecisions(tuple(entries))