Status, Refined and Blocked

Most trackers squash three questions into one dropdown, which is how “In Progress” ends up meaning “we talked about it once”. Hydrant keeps them apart.

• Status: where is it in the process?
• Refined: do we know what done looks like?
• Blocked: is something else in the way?

Before you start

An issue to practice on. Changing statuses needs no special role. Renaming or adding stages needs an Admin or the Owner. Who can do what.

Steps

Set the status

Use the status control on the issue or its row. A new workspace has eight stages:

Stage	Means
Backlog	Captured. Not yet promised to anybody.
Ready	Understood, and waiting for someone to start.
In Progress	Someone is actually on it.
Agent Review	An agent is checking the work.
Human Review	A person is.
Done	Accepted.
Iced	Deliberately shelved. Not dead, not soon.
Canceled	Not happening.

Review stages have no approval gates. They’re places work waits, not permissions. A review stage can name who looks, though: see reviewers.

Mark it Refined

Refinement on an issue is either Needs refinement (“Still has loose ends.”) or Refined (“Scope and acceptance checks are clear.”). Flip it when you could hand the issue to a stranger, or an agent, without a meeting.

One rule is enforced: Ready requires Refined.

• Move an unrefined issue to a Ready stage and Hydrant asks “Ready to start?”. Mark Refined and move to Ready does both in one go; Cancel leaves it where it was.
• In the new-issue form, picking a Ready stage makes you tick Refined and ready to start.
• You can’t un-refine an issue that’s sitting in Ready (“To clear refinement, choose another status first.”).

Read Blocked

Nobody sets Blocked. Hydrant works it out from blocked-by relationships. An issue is blocked while at least one of its blockers is still open:

• A blocker that is Done, Canceled or in the Trash stops counting.
• A blocker that is Iced or Snoozed still counts. Shelving a problem doesn’t solve it.

A blocked row shows a Blocked chip: a red no-entry icon and the number of blockers. Hover or click it to see them. Open one that’s still in play and its Status icon wears the same no-entry badge, so a Ready that can’t start yet doesn’t pass for one that can. Hover Status for the count; Relationships lists the culprits, on any screen.

Priority and size

Neither affects status, refinement or blocking. Priority is No priority, Low, Medium, High or Urgent; if everything is Urgent, nothing is. Size is optional and relative. Both are covered in Labels, sizes and priority.

Reviewers on a review stage

An admin can name Reviewers on any review stage under Settings › Workflow, on every plan. Reviewers hear when work arrives in that stage, with a Waiting for your review notification, and get Accept and Send back on the issue, under Status. A stage that names nobody leaves both buttons to every member and tells no one.

• Accept moves the issue to the next review stage, or to Done when none follows.
• Send back asks what needs to change. Your note goes on the issue as a comment, and the issue goes back to Ready (Backlog if it isn’t refined). Whoever built it, or whoever owns the agent that did, gets a Sent back notification.
• Undo, right after either, puts the issue back where it was. A send-back’s note stays.
• Naming reviewers enforces nothing. Anyone can still move the status by hand; reviewers just get asked first.
• Someone who leaves the workspace stops being a reviewer. An agent decides as the person who connected it, so it can accept or send back wherever they can.
• Reviewers get through a pile on Sign-off.

Where Done work has got to

If your workspace ships through environments (Solo Pro, turned on under Settings › Workflow), a Done issue also shows Environment. Done still means done. Environment says where the change has got to: Testing, Staging, Production, whatever you call yours.

• Marking an issue Done puts it in the first environment, or further along when GitHub environment detection sees its commits there already.
• Pick another environment on the issue to move it, forward or back. Going straight to a later one is fine for a hotfix, and the history names what it skipped.
• Not in an environment is for Done work that never deploys.
• Reopening an issue takes it out of its environment. Finishing it again starts back at the first one.

Canceled and unfinished issues don’t have an environment. Agents set it with the same rules.

An environment can also need sign-off. An admin names its Approvers under Settings › Workflow. Any issue that lands there waits for one of them, and they don’t have to be the assignee.

• The issue shows Approval under Environment, with Waiting for … until an approver answers. While it’s your turn, every answer is a button under it: Approve, Approve with a follow-up…, OK behind flag, Hold…, Pass and Reject…. Once you’ve answered, or someone else has, they fold away behind Change your answer (or Answer anyway). Take back approval undoes an approval.
• Approve with a follow-up… is for “fine, ship it, but”: it approves the issue and files a new one in the same step. Say what the follow-up should fix; that’s required, and it becomes the new issue’s description. The follow-up starts in Backlog, needing refinement and unassigned, titled Follow-up to #N: and your first line, linked to the original as related. It joins the original’s project when that project is still taking new work, and its milestone when that’s open, but not its labels. The original shows Follow-up #N under Approved by …. Undo right after takes the approval back and moves the follow-up to Trash, unless someone has already edited, commented on or linked it, in which case it stays. Taking the approval back later never touches the follow-up.
• Reject needs a reason. The reason goes on the issue as a comment, and the issue goes back to Ready (Backlog if it isn’t refined), which takes it out of the environment. Hydrant doesn’t touch your branches. Whether the code gets reverted, flagged off or fixed forward is up to you, so say which in the reason.
• Hold is the other “no”, for work whose code is already there and will be fixed forward. It needs a reason too, posted the same way, but the issue stays Done and in its environment, so anything waiting on it stays unblocked. It shows Held by … and counts against promotion like waiting work. Take back hold or Approve once the fix lands. Use Reject when the work shouldn’t count as done.
• Pass means “not mine to judge”: a CEO who reviews features, not dependency bumps. No reason needed and nothing is posted. It’s recorded as not reviewed by you and never holds up a promotion. If another approver hasn’t answered yet, the issue keeps waiting for them and shows Passed by … under who it waits for; once every approver has passed it shows Passed by … and stops counting as waiting. Take back pass undoes it, and you can still approve, hold or reject later.
• What each approver reviews. Under Settings › Workflow, an admin can press Set who reviews what under an environment’s approvers and give each one a list of projects and labels, such as “Alex reviews Checkout, Reports, Billing”. An issue is theirs when its own project is on the list or it carries one of the labels. Everything else is passed for them automatically: it isn’t in their queue, it doesn’t notify them and it never waits on them. If another approver reviews it, it waits for them; if nobody does, the issue shows No one reviews this in Staging. It passes straight through. and promotes like passed work. An approver with no list reviews everything, as before.
  • A passed-by-rule issue shows Passed for Alex Rivera (outside what they review) under who it waits for. Alex can still open it and approve, hold or reject it with Answer anyway; Pass and Take back pass don’t apply to a pass that came from the list.
  • It’s worked out each time the issue is read, so changing a list, an issue’s project or its labels changes what waits for whom straight away, including work already waiting. Changing what someone reviews never rewrites answers they gave.
  • An approver who passed by hand, was removed and was later made an approver again keeps that earlier pass: it counts again. Their review list doesn’t come back; they review everything until an admin sets it again.
  • A list whose projects and labels have all been deleted counts as reviewing everything, so a mistake means more review, not less.
• Moving an issue to another environment and back starts a fresh wait. A hotfix that skips a gated environment doesn’t need its approval.
• Someone who leaves the workspace stops being an approver. An environment with no approvers doesn’t wait for anyone.
• Approvers can decide a whole pile at once on Sign-off.
• Approvers see what’s waiting for them at the top of Cockpit, under Waiting for your approval, oldest first and grouped by environment when there’s more than one, and get a Waiting for your approval notification when something arrives. Agents read the same list by filtering issues with approval=waiting-for-me.
• To clear a long queue, filter issues by Approval › Waiting for your approval (a long Cockpit section links there as See all in a list), select the issues and use Approval in the bulk bar: Approve, OK behind flag, Hold…, Pass, Take back approval, hold or pass or Reject…. Hold and Reject ask for one reason and post it on each issue. Every issue is decided on its own, under the same rules as above. Issues you don’t approve, ones already in that state and ones that changed since you looked are skipped and named.

An agent can approve (with or without a follow-up), hold, pass or reject only when the person who connected it is an approver.

An admin can also give each environment a URL under Settings › Workflow, such as your staging site’s address. The issue’s approval, Waiting for your approval in Cockpit and the Environments page then show Open Staging (or whatever the environment is called), which opens that address in a new tab. It has to start with https:// or http://, and a username or password in it is refused, because everyone in the workspace can see it. Hydrant never opens or checks the address itself.

If your team ships unfinished work behind feature flags, an admin can turn on Flag keys under the environment list in Settings › Workflow. Every issue then gets a Flag key field, for the name of the flag it ships behind (like new-checkout). You can fill it in at any stage.

• An approver can press OK behind flag instead of Approve. That says the work can go on as long as the flag stays off, and it records which flag. It needs a flag key on the issue first.
• Change the key afterwards and the issue waits for approval again, because the approver said yes to the old one.
• The promote batch shows each issue’s key next to its title.
• Hydrant doesn’t read or change your flags. The key is a name, not a switch.
• Turning flag keys off hides the field and the button. Keys and decisions already recorded stay.

Environments in the sidebar shows your environments as one strip, in order, each with its count of Done issues and the state of the step out of it, such as 40 waiting, All approved, not cleared or Cleared. The last one reads Live. With many environments or a narrow window the strip gets more compact, or splits into rows, rather than scrolling sideways. It opens on the step that matters now (select another step to look at it): how many are on it, how long the oldest has waited, a link to open the environment, its dockets, and what still stops it moving, blockers first. After you fast-forward a branch, Promote (for example Promote 25 to Production) moves everything in that environment up one step in a single go. It shows the batch first and takes an optional commit SHA. Anyone in the workspace can promote, and an agent can run the same promotion over MCP, for example from its own nightly job. Each moved issue’s history says who promoted it and at which commit, and the page’s History lists every promotion, releases included, with the dockets that travelled with it.

Promoting out of an environment with approvers adds a summary above the batch, like “23 issues: 20 approved, 2 passed, 1 waiting”, and marks each issue still waiting, held or passed. Passed work moves without asking: every approver answered it. Promoting waiting or held work is allowed but never an accident: tick Promote 1 issue that’s still waiting for approval (or that’s held) first, and a batch that changes before you promote asks again. The promotion record says how many went out held or never reviewed; agents see which were held in held_issue_ids and which went out passed in passed_issue_ids from list_promotions. A held issue arrives in the next environment waiting, like everything promoted: a hold belongs to the environment it was given in. Issues that arrived before the environment had approvers count as waiting. Agents see the same counts in preview_promotion and pass acknowledgeWaiting to promote_environment. An environment with approvers can also be cleared by one of them on Sign-off: their word that it’s good to go. The dialog says who cleared it and when. Without a clearance it says so, and the same tick covers it (Promote without a clearance); the promotion record notes that it went without one. It’s a warning, not a block: Hydrant can’t stop a fast-forward. Agents read the clearance in preview_promotion and list_promotions, and pass acknowledgeUncleared: true to promote without one; acknowledgeWaiting alone doesn’t cover it.

A promotion into your last environment can be a release. Give it a name, like 1.4 or a date, and notes in Markdown, either in the Promote dialog or later with Name this release on the promotion. The release gets its own page listing exactly the issues that promotion moved, so “what went out in 1.4” is one link. Issues reopened, canceled, trashed or moved out of that environment since the release are listed first, and a long release has a filter for finding one issue by title or number. Names are unique in the workspace. Removing a release clears its name and notes; the promotion and its issues stay. Agents can name releases, write their notes and read them by name over MCP.

Rename the process

Admins and the Owner can add, rename and reorder stages under Settings › Workflow. Every stage keeps one of seven behaviors (backlog, ready, in progress, review, done, iced, canceled), and the rules follow the behavior, not the name. Custom stages can also have an icon from the built-in glyph set. Pick one when adding a stage, or use the icon control on its row. Choose Behavior icon to reset it. Color still follows the behavior; default stages keep their icons. Default stages can be renamed and reordered, but not removed.

What you should see

Control tower is the payoff. Its Ready group is what the team can pick up, and anything stuck wears its Blocked chip. Pull its Remove before flight tag and the stuck ones step aside, leaving only what can go now. When that list is honest, “what should I pick up next?” stops being a meeting.

If it goes sideways

• “Ready requires explicit refinement.” Mark the issue Refined first, or pick another status. Agents get the same answer.
• “Only Done issues have an environment.” Finish the issue first, or leave its environment alone.
• “Add a flag key first.” OK behind flag needs the flag’s name on the issue. Add it under Flag key, then decide.
• “Only … can accept or send this back.” You’re not one of that stage’s reviewers. Move the status yourself, or ask an admin to add you.
• “#431 already left review.” Someone moved it while you were looking.
• “Already passed. It’s outside what you review.” The issue isn’t in your list for that environment, so it’s already passed for you. Approve, hold or reject it if you want a say.
• “That pass comes from what you review, not from you.” There’s no pass of yours to take back. Approve, hold or reject it instead, or ask an admin to change what you review.
• “Only approvers of Staging have a scope there.” Make the person an approver of that environment first, then set what they review.
• “Only … can approve issues in Staging.” You’re not one of that environment’s approvers. Being an admin or the assignee doesn’t count. An admin can add you.
• An environment won’t delete. Issues are in it or have been, so it stays for their history. Rename it instead.
• “Only promotions into Production can be releases.” Earlier steps stay plain promotions. Name the one that reached your last environment.
• “1.4 is already a release in this workspace.” Names ignore case. Pick another, or rename the old one first.
• “1 issue in Staging is still waiting for approval.” An approver hasn’t signed it off yet. Get it approved, or promote it anyway: tick the box in the dialog, or send acknowledgeWaiting: true from an agent.
• “Staging hasn’t been cleared.” No approver has cleared it, or a clearance was taken back after a change. Ask an approver to look, or promote anyway: tick the box, or send acknowledgeUncleared: true from an agent.
• “What’s in Testing changed since you looked.” Someone finished, moved, approved or took back an issue, or cleared the environment or took the clearance back, while you were confirming. The list refreshes; check it and promote again. Nothing moved the first time.
• The Refinement control is disabled. The issue is in Ready. Move it, then un-refine it.
• It says Blocked, but the blocker is finished. Finished how? Only Done, Canceled or Trash clear a blocker. If it’s really done, say so with its status. Whoever is assigned the blocked issue gets an Unblocked notification when that happens.
• You canceled something and other issues changed. They didn’t, quite. Canceling a blocker first shows how many issues lose it and whether each will then qualify for Available to start. Their links and statuses stay as they were.
• “This stage is retained by saved views, issues or their history.” A stage that has ever been used can’t be removed. Rename it or stop using it. Default stages can be renamed and reordered, but never removed.