Baron

What moving this item to `role` WOULD be — advance / regress / reopen / noop, or unknown when the item's current role cannot be read — without moving it. A fact about the lifecycle order, not a judgement about the move.

Add a comment to an issue.

An issue's comments, oldest first, each body as the provider stores it (Azure keeps HTML). Read before posting evidence so the same note is not added twice.

Create an issue from abstract terms. typeRole -> native work-item type and initialRole -> native state are translated automatically per the active policy; capability gaps (e.g. no native hierarchy) are handled by the configured gap policy.

Fetch a normalized issue by id.

List the provider's iterations/sprints (each with a `current` flag). Empty when the provider has no sprints. Use it to find the active sprint or a target for set_iteration.

Link two issues with an abstract relationship. On providers without native typed links the link is emulated or degraded per the gap policy.

Move a work item through the workflow, or flag it. ops: `transition` (id, role, optional fields) — the semantic role layer, resolving an abstract role to the provider’s native state/column/label; on a provider whose transition carries a screen (Jira) a refusal with code TRANSITION_FIELDS_REQUIRED names the fields to pass back, verbatim, as `fields`; `reconcile` (id) — clear a role label the provider’s own state contradicts, commanding no role; `block` (id, reason — required) and `unblock` (id, optional reason), which set and clear an ORTHOGONAL flag and leave the role alone, so an item keeps t…

List issues filtered by workflow role and/or type role (filters are AND-combined). Returns a lightweight projection (no body); fetch an issue with get for full detail.

Read work items. ops: `get` (id) → one normalized issue; `comments` (id) → its comments, oldest first; `query` (role / typeRole / assignee, `@me` allowed / iteration, `@current` allowed / limit) → a filtered list; `iterations` (no args) → the provider's sprints, each with a `current` flag, empty where the provider has none.

Make an item's emulated role labels agree with the state the provider itself reports. Commands no role — it only clears a role label the provider's own state contradicts, which is what a merge that closes an issue leaves behind. A no-op where roles ride native states.

Move a work item to an iteration/sprint by path, or '@current' for the active sprint. Providers without sprints negotiate the gap per policy.

Where one item is, end to end, in ONE read: the issue, its canonical branch, the most recent pull request from that branch (any state) with its review/checks status, the latest CI runs on the branch, and the most recent deployment whose ref is the branch. A part that could not be filled is null AND named in `missing` with the reason (port not bound, or the item has not reached that hop) — read `missing` before concluding anything is absent. Prefer this over chaining get + pr_for_branch + pr_status + runs + deployments yourself.

Transition an issue to a target workflow role (idempotent). The adapter resolves the role to the provider-native state/column/label.

Clear an item's blocked flag. The workflow role is untouched. Optionally records why it was unblocked. Idempotent.

Edit an existing issue's title and/or body. A patch: whatever you omit is left untouched. The body goes to the field the item's type uses — a bug's body is its repro steps. Use this to correct a title or fill in a description after creation; it does not change role or assignee (use baron_issue_transition / baron_issue_assign).

Change a work item’s content. ops: `create` (title, typeRole, optional body/parentId/labels/initialRole); `update` (id, title and/or body — a patch, omitted fields are left alone); `comment` (id, body); `assign` (id, assignee — `@me` allowed); `link` (fromId, toId, type); `set_iteration` (id, iteration — `@current` allowed). Roles and type roles are abstract: the active policy maps them to the provider’s own states and types.

Record a durable learning (knowledge that should survive across runs).

Query recorded learnings by tag and/or free text (newest first).

Record something durable in Baron's own store (not a provider's). ops: `learning` (title, body, optional tags) — a decision worth keeping; `followup` (title, optional body/tags) — an open loop to come back to.

Read Baron's own store. ops: `learning` (optional tag/text/limit); `followup` (optional status/tag/limit).

ESCAPE HATCH — a raw, authenticated, NON-PORTABLE provider REST call. Last resort for when no normalized tool (issue/scm/ci/notify) covers the need. You supply the provider-native method + path (+ query/body); Baron only attaches the base URL + auth and returns the (size-capped) response. Prefer the normalized tools — this is provider-specific and will not port to another provider. Only providers bound in the active policy are reachable.

Send a notification. Targeting a channel or threading a reply may be degraded/errored per the gap policy on providers that lack those capabilities.

List the runnable recipes (built-ins + project recipes) with their declared inputs. Call this to discover what `baron_recipe_run` accepts before running a workflow.

Run a named recipe end-to-end as ONE deterministic, rule-enforced workflow (the engine — not you — enforces the step order). Supply all required inputs (from baron_recipe_list) in `inputs`; a missing required input errors rather than prompting. Prefer this over composing the individual issue/scm/ci tools yourself for a packaged workflow. Returns the run context as JSON (with its `runId`), and — when the recipe had anything to say — a SECOND text block with its messages. Read that block: it is where a recipe reports what it could not verify (task-land warns there when it merged past checks it c…

Create a branch from a base branch (defaults to the repository default branch).

Open a pull request. A requested draft may be degraded to a ready PR if the provider lacks draft support (per the gap policy); the returned `draft` reflects what was actually opened.

Find the most recent pull request for a branch matching `state` (null when none), with its normalized `state`. `open` (default) = the finish-flow idempotency probe (don't duplicate an open PR); `merged` = the drift probe (did this branch land while its item stayed in progress?).

Merge (land) a pull request — the last mile of the flow. Fails loudly (MERGE_FAILED) when the provider refuses: conflicts, unmet branch policies, or a PR that is still a draft. Check baron_scm_pr_status first if you want to know before trying.

Take a draft pull request out of draft ("ready for review"). task-finish opens drafts on purpose; this is how you signal it is ready to land.

Read a pull request's normalized status: state, review decision, mergeability, and a checks rollup — the "is it ready to merge?" view.

Add a discussion thread/comment to a pull request.

Read source-control state. ops: `pr_status` (pullRequestId) → normalized state, review decision, mergeability and a checks rollup; `pr_for_branch` (sourceBranch, optional state — `open` default / `merged` / `closed` / `all`) → the most recent matching PR or null. `open` is the idempotency probe before creating one; `merged` is the drift probe.

Change source-control state. ops: `branch_create` (name, optional fromBranch — idempotent); `pr_create` (title, sourceBranch, optional targetBranch/body/draft/assignees/autoComplete, plus linkedIssueKey and linkedIssueRelation — `closes` finishes the item on merge, `relates` only references it); `pr_thread` (pullRequestId, body); `pr_ready` (pullRequestId) — take it out of draft; `pr_merge` (pullRequestId, optional strategy/deleteSourceBranch). A provider that declines a merge surfaces as MERGE_FAILED rather than a false success.