Raise a cap on a stopped item

Raise the cap or budget that stopped a work item for that one item, retry it, and see it leave Needs you. A work item's own cap can exceed the chain's, up to maxima.work_item, so you need no config edit. For what the caps are, and why a raise is bounded, see Caps and budgets.

Before you start

• A work item that a cap stopped. The board shows it under Needs you, and kraft view show ID names the limit it hit.
• Its ID, for the command line: kraft view list.

Which cap stopped the item

The stop decides what the item offers.

Raising a cap in the interface

An item that a time or attempts cap stopped names the limit it hit and offers Raise cap: an editor for that one limit, showing its current value and the policy's maximum, if there is one. Save & retry sets the new value in the item's policy, keeping the item's other policy overrides, and retries the item. A refusal, such as a value past the maximum, shows beside the field and nothing is retried.

• On a phone, the bar's Raise cap, beside Steer, opens the same editor as a sheet titled for the limit, such as Raise the running time cap.
• On the board, a row's Raise cap for these caps opens the side panel on its Config tab, which has no editor for them. Click the panel's own Raise cap there: its main button at the bottom, or the one in Overview's banner.

A dollar stop in the interface

• The item-wide budget_usd. A stop on it names it as its limit, so the item's Raise cap (on a phone, Raise budget) opens a one-number editor and writes the item's policy for you. A stop on a node, step or task's budget_usd names no limit.
• The item's own dollar cap. The item's Raise cap opens the budget editor on the item's Config tab, and a phone offers Raise budget. Each offers +$5, +$10, no cap, or an amount you type. The amount opens with the cap in force selected, so what you type replaces it.

Budget stops and what the interface offers

Any other dollar or token stop, such as the daily cap, a token_budget or a node's budget_usd, has no raise in the interface. The item says "The item can't raise this cap: the policy or the chain sets it. Retry once it is raised there, or after local midnight for the daily cap.", and offers Retry in place of a raise (on a phone, Retry alone). To get past a node's own budget_usd, skip the node: see the per-scope cap.

On the board, a row or phone card for any budget stop reads Raise budget, even for one the item can't raise. What it opens depends on the stop:

• The item-wide budget_usd: the side panel's Overview, with the Raise budget cap dialog open.
• The item's own cap: the Config tab, with the budget editor open.
• A budget the item can't raise (the day's cap, say): the item on a banner (on a phone, its card) that says why not and offers Retry.

Raising a time or attempts cap from the command line

kraft item set-policy ID --policy time_cap_minutes=240
kraft item retry ID

set-policy replaces the item's whole override, so repeat every --policy you set earlier, or they are dropped. Read what the override holds in policy_override in kraft view show ID --json. --clear removes the override.

A cap on one path, such as verification.time_cap_minutes=90, may exceed that scope's level default up to its level's maximum. It may not exceed what the chain, the item's cap or an enclosing path already gives it. Kraft refuses a larger value and names both scopes.

Raising a budget from the command line

raise-budget and the MCP raise_budget tool raise whichever dollar cap stopped the item, as Raise cap does: the item-wide budget_usd in its policy, or the item's own cap that kraft item create --budget sets. On the item-wide budget_usd, they set it in the item's policy override and keep every other field the override sets. The two dollar caps tells them apart.

kraft item raise-budget ID --usd 25

raised the cap on <id> to $25 and retried it; the item is now running

Three stops are not raised this way:

• token_budget. Raise it with kraft item set-policy ID --policy token_budget=N, as for the time caps.
• A node's budget_usd. Skip the node instead: see the per-scope cap.
• budget.daily_usd. It is refused everywhere: raise it in policy.yaml, or wait for local midnight. Then run kraft item retry.

A change to budget_usd or token_budget in policy.yaml reaches only items filed after it.

If every slot is busy, raise-budget raises the cap and queues the retry: the item starts when a slot frees. kraft item pause takes it out of the queue.

A stop on unknown spend

A budget_usd stop on unknown spend is different: no higher cap passes it, since Kraft still cannot show the scope is under the new one. Clear the item-wide cap instead. This also retries the item:

kraft item raise-budget ID --usd none

budget_usd=none means no dollar cap for the work item, and none for each node, step or task the chain set no budget_usd on. It replaces the chain's, the repository's and the policy.yaml defaults. It is item-wide only, and refused when maxima.work_item.budget_usd is set. A cap the chain set on a node, step or task still binds: see the per-scope cap. token_budget, budget.work_item_usd and budget.daily_usd still bound the item.

The two dollar caps

An item has two dollar caps, and each has its own way up: see a dollar stop in the interface and raising a budget from the command line.

The per-scope cap

budget_usd in the item's policy is a per-scope cap, like the time caps. Item-wide it may exceed the chain's up to maxima.work_item. On a path it only tightens.

So this item cannot raise a budget_usd that the chain sets on a node, step or task: kraft item set-policy ID --policy budget_usd=N sets the cap item-wide, and a cap the chain set on that node still binds. Skip that node with kraft item skip ID, or raise the cap in the chain and file the item again.

An item-wide budget_usd from set-policy replaces the level defaults on every scope the chain set none on.

The item's own dollar cap

The item's own dollar cap is the one kraft item create --budget sets in place of budget.work_item_usd. No maxima bounds it. --usd none on raise-budget lifts it.

Which one the interface shows

Whichever of the two is lower stops the item first, so that is the one the item's Budget shows, on its Config tab and in the side panel. An item-wide budget_usd in the item's own policy, such as one Raise cap wrote, is listed under Changed for this item. While it is the lower cap, the pencil beside Budget changes it rather than the item's own cap.

Check it worked

1. The command ends by saying the item is running: kraft item retry ID prints retried <id>; the item is now running, and raise-budget prints the line above. If it says the item is "stopped for a person", the item stopped again: kraft view show ID says why.
2. On the board, the item has left Needs you. It sits under Running, and the header's N NEED YOU count is one lower.

Next steps

• Caps and budgets: what each cap bounds, its scopes, and why a raise is bounded by the maxima.
• Why did my item stop?: the stop reason on the item, and the fix for each.
• Item verbs: what raise-budget, set-policy and retry accept and refuse.