Oko
Oko/Docs

Command reference

oko defects classes cause

Names a cause of a class with the evidence it was found by and the mechanism planned on each layer; changes it; or takes it back.

Invocation#

Command
oko defects classes cause add <class> --text CAUSE --evidence EVIDENCE --by SESSION [--prevent PLAN] [--detect PLAN] [--recover PLAN] [--measure PLAN] | cause edit <class> <cause> --by SESSION [--text …] [--evidence …] [--prevent …] [--detect …] [--recover …] [--measure …] | cause remove <class> <cause> --reason REASON --by SESSION [--json]

Inputs and options#

  • Every cause carries four layers: prevent (stops the shape where it is made: a Tama gate, one shared library function every instance moves to, or a lint), detect (finds an instance that got through), recover (repairs it) and measure (counts it). A layer holds a plan in words until a mechanism lands on it: a Tama hook, a product command's refusal or a real test under tests/, by name and the revision that carries it.
  • A cause is named by its identifier or the start of it. The causes are kept beside the defect register in `<register>.classes.json`; `OKO_CLASS_REGISTER` moves it.
  • The completion probe measures from the install records: a hook was installed when the Tama hook registry carrying it was written, which every install does whole; a refusal or test since the oldest installation of its product's command line, in the unbroken run up to the current one, whose source revision contains the mechanism's (`stado product status <product> --surface cli`). The first reading that finds every layer standing (`show`, `check`, or the closing gate) keeps that moment as `installedAt`, which the listing shows; a change to a cause or a mechanism clears it.

Output and state effect#

  • Prints `class <short id> names the cause` (`changed the cause`, `took the cause back`) and the class's causes as a table: `cause <id> <text>`, its evidence, and one line per layer `<layer>: <plan or nothing planned>; <landed: <mechanism> or not landed>`; --json prints `{class, causes, installedAt}`. An edit notes `cause <id> changed by <session>; it said: <text>; its evidence was: <evidence>` on the class. A cause taken back stays listed with `[taken back by <session>: <reason>]`, is noted on the class, and no longer counts.
  • `oko defects classes show <class>` prints the table and every step still missing, the install of each landed mechanism read; --json prints `{class, causes, standing, missing, closable}`. The native API takes `classes {verb: "cause_add" | "cause_edit" | "cause_remove" | "show", …}`; OkoKit's `addCause`, `editCause`, `removeCause` and `classCauses`, and Oko Desktop's class card, call them.

Refusals and safe exits#

  • `defect <id> is not a class; `oko defects classes` lists the classes and `oko defects classes open` opens one`; `class <id> already names this cause as <cause>; change it with `oko defects classes cause edit <class> <cause> --by <session>``; `no cause with id <cause> is registered on class <id>; its causes are [<ids>]`.
  • `oko defects classes cause edit changes --text, --evidence or a layer's plan (--prevent, --detect, --recover, --measure); none was given` and `oko defects classes requires --by <text>` (exit 2); a blank text, evidence, plan, reason or session names what is missing.

CLI reference#