Oko
Oko/Docs

Command reference

oko tasks evidence

Records evidence for Oko’s independent completion check without asking the operator to close the task manually.

Invocation#

Command
oko tasks evidence (<session> <number> | <task-id>) --by <session> [--commit REPOSITORY@REVISION] [--report PATH]

Inputs and options#

  • <session> and <number> name the task, or <task-id> names it by identity alone; --by names the session recording. --commit requires <repository>@<revision>, identifying a commit in that repository’s checkout; a bare commit hash is not accepted even when the command runs inside its repository. --report requires an existing report file, not the report’s text. At least one of --commit and --report is required.
  • --by, --commit and --report are singular. Repeating any of them refuses before database connection or evidence mutation rather than silently keeping the first value. Missing or empty values and unknown options also refuse at that boundary. One command may contain both one commit and one report; repeated registration replaces the task’s current evidence row, not an append-only collection of commits. For multi-repository work, retain the complete revision set in a report and register that report.
  • The real CLI journey is `node tests/evidence/arguments.mjs` in the Oko checkout. It requires the release build’s WISENT_SOURCE_COMMIT, WISENT_SOURCE_SHA256 and WISENT_OUTPUT_DIR; OKO_TEST_EVIDENCE_TASK and OKO_TEST_FIXTURE_SESSION must select a dedicated open, stated task with restorable proof owned by that fixture session. OKO_TEST_EVIDENCE_COMMIT and OKO_TEST_EVIDENCE_REPORT name genuine existing proof, while OKO_TEST_SUCCESS_EXIT and OKO_TEST_USAGE_EXIT declare the product’s documented success and usage statuses. Never select operator work.
  • The journey records one commit plus one report, reads both back, then checks repeated, missing, empty and unknown-option refusals against unchanged persisted proof. It also refuses a genuinely absent report path and a directory presented as a report, preserving the complete proof after each refusal. It restores the original proof references and author through the CLI; restoration has a new recording timestamp. Retain `.build/evidence/arguments/<run>/report.json`, including source/archive/binary/journey identities, commands, exit statuses, actual causes and restoration result. Source registration is not a passing run.
  • The registered native API journey `native_evidence_report_refusals_preserve_persisted_proof` uses the same dedicated task and fixture-session inputs plus OKO_TEST_SOURCE_REVISION. It invokes the real resident Tasks API against the shared database, requires the actual filesystem cause for a missing report and the non-file refusal for a directory, then reads the entire persisted proof back unchanged.

Output and state effect#

  • Writes evidence beside the ledger, keyed by the task’s identity, and prints the task with its identity. Evidence stays with the task when its number moves; a row this task left at an earlier number is removed. Evidence alone does not mark work done: Oko’s independent judge checks the answer and saves a verdict. Use --report for exports and investigations without a code change, or --commit for changed code. The operator’s later correction takes precedence.

Refusals and safe exits#

  • Refuses without a task and --by and prints the usage; refuses with “evidence needs a --commit or a --report, or it is not evidence” when neither is given; a bare commit refuses with “commit <revision> names no repository; write it as <repository>@<revision>”; an uninspectable --report path refuses with “cannot inspect evidence report <path>: <actual filesystem cause>”, and a directory or other non-file refuses with “evidence report <path> is not a regular file”; these shared CLI/native refusals occur before replacing evidence. A task nobody has stated refuses with “Nobody has written what it asks for, so there is nothing for this evidence to answer” and names oko tasks state as the repair; a number the ledger does not hold refuses by session and number; a defect’s identity refuses with “task <id> is a defect, not an instruction; claims, evidence and defects are recorded on the task it repairs”.

CLI reference#