Oko
Oko/Docs

Command reference

oko defects record

Records one evidence-backed defect with an observable whole-repair criterion, or a class with a revision-bound inventory. The operator's decision bound to a Tama gate still prevents recording a defect against that gate, and a repair that needs an action `oko admit` refuses now is not recorded.

Invocation#

Command
oko defects record --product NAME --title TEXT --surface TEXT --evidence TEXT --impact TEXT --found-in TEXT --repair TEXT (--criterion RESULT | --class --probe-program PROGRAM --probe-scope TEXT --probe-format lines|json --probe-arg ARG...) [--probe-pointer /PATH] [--shape TEXT] [--distinct-from ID ... --distinct-because REASON] [--needs ACTION ...] [--owner NAME] [--priority high|medium|low] [--json]

Inputs and options#

  • The observed product, title, surface, evidence, impact, found-in source and mechanism-plus-sweep repair plan are required.
  • For a single defect, --criterion names an observable complete result. A class uses --class and a probe: the program runs in its repository checkout, arguments include {revision} and may include {checkout}. It prints one remaining instance per line or a JSON array of strings at --probe-pointer. An empty successful inventory proves zero; nonzero exit or malformed output does not.
  • --distinct-from names separate incidents and needs --distinct-because saying how this one differs; --shape names their general design property; --owner and --priority assign it. The native API's defects record takes the same distinct_from and distinct_because.

Output and state effect#

  • Appends the defect to the register with a new id and prints `recorded <id> against <product>: <title>` with the assignment when one was given.
  • With --distinct-from, the reason is kept as the defect's first note: `recorded as distinct from <ids>: <reason>`.
  • Without --json the record is followed by `nearest open defect <short>: <title>` for every open defect of its product sharing the most subject words with its title, so the closest existing entry is read at once.
  • --shape writes the design property this defect is one instance of, in the recorder's words; when other defects of that shape are registered, the record is followed by `shape also recorded on <ids>: the second defect of one shape is the finding; write the shape down before the next fix`, so the pattern is read before the next workaround. The sentence is not printed with --json; `oko defects shapes` and `list --shape` read the same.

Refusals and safe exits#

  • `oko defects requires --product <text>` and the same for every other required flag (exit 2); a blank value names its missing product, title, surface, evidence, impact, source session or complete mechanism-and-sweep repair plan.
  • --needs, repeatable, names each action class the repair runs (build, compile, test, install or release) and is kept on the defect as `needs`; while a standing ruling forbids one for the defect's product the record is refused with that verdict, `<action> of <product> may not run until a later ruling of the operator allows it: the operator's ruling <id> on <subject> …`, and nothing is written. A word that is no action class is refused naming the classes. The same proposal is also judged by Brama against the forbidden constraints with the gates above.
  • A missing completion criterion or class probe is refused; a probe without its scope, program, revision argument, output format or JSON array pointer is refused by name.
  • `<word> is not a priority; one of high, medium, low`.
  • `a defect recorded as distinct from <ids> says why it is a different fault: add --distinct-because <how it differs>` when --distinct-from is given without a reason; nothing is written.
  • An exact open product/title refuses as `open defect <id> already records this product and title; add new evidence with oko defects note <id> --text <observation> instead`, unless `--distinct-from <id>` with its reason explicitly names that different incident.
  • Restated open titles refuse as `open defects already say this: <short>: "<title>"; ...`; the answer names every conflicting entry and the required `--distinct-from <short>` arguments with `--distinct-because <how it differs>`. A pushed repair awaiting release is quoted with its revision.
  • An open defect of the same product and surface carrying an unreleased repair refuses with `open defects of this product and surface carry a pushed repair that no build has proven or installed yet`; it names each entry, its repair revision and each required `--distinct-from <short>` with `--distinct-because <how it differs>`.

CLI reference#