knotch

Record a named human reviewer's approval (or rejection) of a prior event on the active unit. Use for human-in-the-loop sign-off on gate decisions, status transitions, or milestone ships — never for agent self-review. Emits `ApprovalRecorded` with a bounded rationale so audits surface the signature instead of hunting through prose.

Read the current state of a unit — current phase, status, shipped milestones, model timeline — or find units that match a predicate. Works for active, archived, abandoned, and handed-off units alike (projections are pure historical reads). Use when the agent needs a fact before planning its next action.

Read the current state of a unit — current phase, status, shipped milestones, model timeline — or find units that match a predicate. Works for active, archived, abandoned, and handed-off units alike (projections are pure historical reads). Use when the agent needs a fact before planning its next action.

Record a gate decision with long-form rationale on the active unit. The canonical Knotch workflow ships gates G0..G4 (Scope / Clarify / Plan / Review / Drift) with an 8-char `min_rationale_chars` floor — too-short text rejects as `RationaleTooShort`. Adopter-forked workflows may expose different gate vocabularies.

Record a phase completion or skip on the active unit. The canonical `Knotch` workflow phases are `specify → plan → build → review → ship`; adopter-forked workflows may expose different names — run `knotch show --format json` on the active unit to see the current vocabulary. Does NOT handle milestones (those attach to commits via a `Knotch-Milestone:` git trailer — see "When NOT to use").

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.