Propose a change for review

tovio change propose, against a Forge.

Written By Dustin

Last updated 21 minutes ago

tovio change propose --remote <host:port>tovio change propose <chg-id> --target main --remote <host:port>

Submits a change to a Forge for review, and opens it. This needs a Forge — peer sync alone has no review surface.

Argument	Default
The change id	The current change, if omitted.
`--target <lane>`	`main`.
`--remote <host:port>`	Required. No default.
`--cert <file.der>`	This repository's `.tovio/relay-cert.der`. Pinning is always enforced; there is no skip path.

Push the change first

The Forge reviews commits it holds, so push the change before proposing it. Two refusals happen locally, before any network call: a draft or abandoned change is not proposable (TVO-OP-012 — promote or restore it first), and a change id no reachable commit carries is TVO-OP-006.

What happens next

The proposal gets a prop: id. The Forge pins the pair it will review against: your change's commit, and a base it computes itself from the served tip of the target lane. That base is never a field you supply, which is what makes the review gates sound.

Reviewers then approve or request changes. Landing is gated on whatever the target lane and the touched paths require: approval counts, reviewer eligibility, required checks, and protected-path read coverage.

Other ways to propose

Flag	What it changes
`--onto prop:<id>`	Stacks this proposal on an open parent instead of the lane tip. See the stacked-proposal article.
`--sovereign`	The change stays in a repository you control and is surfaced to the target Forge by reference, so your work survives the target rejecting it. A target that cannot resolve the reference refuses with `TVO-FORGE-077`.
`--visibility restricted --reader <did>`	Narrows who can see the proposal, repeatable. It can only ever narrow within the repository's existing readers, never widen.

Watching it

tovio change watch <chg-id> --remote <host:port>tovio change watch <chg-id> --once --remote <host:port>

Polls the Forge's event feed, surfacing each new event touching the change once, and resolving when a landed or resolved event arrives. --once polls a single round and reports.

--remote is not optional in practice: without it there is no live event source, and watch fails closed with TVO-OP-010 rather than pretending to watch.

Notify intent

tovio change notify <chg-id>

Records a durable notify-intent: "tell me when this reaches a watched state". It is local, never synced, idempotent, and reversible with tovio undo. Delivery is the Forge event feed's concern.

Updating a proposal

Amend or rebase your change and push again. The change id survives, so the proposal follows it rather than being orphaned — that is why rebasing under review is safe here. Note that an amendment re-pins both the reviewed commit and the computed base, which invalidates prior approvals by design.

Common refusals

Code	Meaning
`TVO-FORGE-011`	A protected path the land would introduce has no approving reviewer cleared to read it.
`TVO-FORGE-013`	The target lane advanced since the review, so the pinned base is stale.
`TVO-FORGE-003`	A required check is pending, failing, or was never posted.
`TVO-FORGE-080`	A change-controlled path was pushed directly; open a proposal instead.