ratchet apply

Implement a single existing change headlessly. apply runs exactly one agent for a forced apply transition through the change-scoped engine core (runChangeStep), with no batch manifest in sight. Run state is kept change-locally under .ratchet/changes/<change>/.run/.

Synopsis

ratchet apply <change> [options]

<change> is required: the name of an existing change under .ratchet/changes/<change>/.

Options

Option	Argument	Description
--force		Bypass the missing-plan precondition. The change-exists check still holds.
-m, --message	<guidance>	Extra guidance for the agent. Repeatable; joined into one "Additional guidance:" block.
--agent	<agent>	Override the coding agent for this step.
--locus	<locus>	Where the agent runs: local, docker, or remote.
--image	<image>	Container image for --locus docker.
--json		Output the structured step result as JSON.

Preconditions

Read from on-disk change state before any settings resolution or spawn:

• The change must exist. A non-existent change (.ratchet/changes/<change>/ absent) fails with an actionable error and no spawn. This check is never bypassed by --force.
• The change must have a plan.md. A change with no plan fails asking the user to run ratchet propose first, with no spawn. --force bypasses this check only.

Behavior

1. Enforce the preconditions above.
2. Resolve settings standalone (flag → project config → default) via resolveChangeStepSettings. An invalid --agent/--locus/--image fails before any agent is spawned. A malformed agent[:model] spec (empty agent or model part, e.g. claude:, :fable; whitespace-padded like claude: opus, claude :m, " claude"; or a model part starting with - like claude:-flag) is rejected with an actionable error naming the offending value before any spawn — the same shared schema (AgentSettingSchema → parseAgentSpec) the load and write paths use, so the flag path can never diverge from what the loader accepts.
3. Build a ChangeStepContext with batch undefined, transition: 'apply', the joined -m guidance, and the change-local journal, then run once via engine.runChangeStep. computeNextTransition is never consulted.
4. Render the structured StepResult as text, or as JSON with --json. The outcome journal entry is written under .ratchet/changes/<change>/.run/, so a blocked or awaiting-approval step stays resumable.

Run state

Run state is written under .ratchet/changes/<change>/.run/ — never under .ratchet/batches/. See Run-state locus.

Help group

apply is listed under the Workflow: heading in ratchet --help, after propose and before verify. See Workflow help group.