| name | knotch-transition |
| description | Transition the active unit to a new lifecycle status. Use when declaring the unit shipped, archived, abandoned, handed-off, or deprecated. Terminal transitions require every required phase to be resolved, or a forced override with rationale. |
| argument-hint | <target-status> [--forced --reason <text>] |
| allowed-tools | Bash(knotch transition *) Bash(knotch current) |
knotch-transition
Move the unit to a new status.
Common status values
Canonical Knotch workflow vocabulary:
draft, in_progress, in_review, shipped — non-terminal,
always allowed.- Terminal:
archived, abandoned, superseded, deprecated.
Adopter-forked workflows may expose a different status set;
knotch transition warns when the target is outside
W::known_statuses() but proceeds (the kernel's StatusId is
open-universe).
Syntax
knotch transition <target>
knotch transition <target> --forced --reason <rationale>
Examples:
knotch transition in_review
knotch transition archived --forced --reason "upstream feature dropped"
What fires
EventBody::StatusTransitioned { target, forced, rationale }.
What to check first
knotch current — confirm the active unit and its current status.- Target status must differ from current. No-op transitions are
rejected with
NoOpStatusTransition.
- For non-forced terminal transitions: every phase in
W::required_phases(scope) must be completed or skipped
(Phase × Status cross-invariant — see
@.claude/rules/preconditions.md).
- For forced transitions:
--reason is mandatory. Without it, the
precondition fails with ForcedWithoutRationale.
When NOT to use
- Shipping a milestone — that's
git commit plus the
verify-commit hook.
- Marking a phase — use
/knotch-mark.
- Undoing a prior event — use
knotch supersede <event-id>.
