Oko
Oko/Docs

Command reference

oko defects fix

Closes a defect with the published revision that contains its recorded repair, after asking Stado which releases of that repository exist; or, for a repair of one of the operator's own home documents (~/ARCHITECTURE.md, ~/NAMES.md, ~/STANDARD.md, ~/agents/*.md), which by his ruling live in no repository, with that document's SHA-256 as it is now.

Invocation#

Command
oko defects fix <id> --revision <repository>@<revision> | home:<path>@<sha256> --detail TEXT --completeness TEXT [--json]

Inputs and options#

  • --revision as <repository>@<revision>, or as home:<path under HOME>@<SHA-256 of the file> (shasum -a 256 ~/<path>); --detail says what closed it; --completeness says how the sweep was verified complete.

Output and state effect#

  • A build-first defect closes only once the claim about its repair holds (`oko claims verify`: a real test and an adversarial reviewer other than its author, both holding at the repair revision); before that the closure is refused with `defect <id> is build-first, and the claim about its repair is <standing>; …`, or `… no claim about its repair is recorded; …`, before Stado is asked. `oko defects released --close` leaves such an item open and names the same reason.
  • For a Stado-released repository: runs `stado release status <repository> --json`, checks that a published release contains the revision and that the revision contains the recorded repair, then closes the defect and prints `closed <id> by <revision>: <detail>`.
  • For a repository delivered by its own CI rather than Stado: reads the GitHub repository named by origin and every push-to-main workflow run. A carrying commit qualifies only when every observed workflow for that commit succeeded. Queued, running, cancelled and failed siblings prevent a passing side workflow from qualifying that push.
  • A failed origin lookup retains the exact `git -C <checkout> remote get-url origin` operation, its exit status and Git's diagnostic. It is not reported as an empty or unsupported GitHub origin. A command that could not start retains its OS cause.
  • For a home document: resolves both HOME and the requested document before checking containment and the resolved parent directories for a git checkout, then checks the file's SHA-256. A symlink cannot turn an outside file or repository file into a home-document repair. Resolution failures retain the requested path and actual OS cause; an escaping link names the resolved target and home boundary. The file agents read is the delivered artifact and no build exists for it. A recorded repair must name the same document. CLI and Desktop share this validation.
  • Before writing the closure, the locked register rechecks the repair revision, plan, recording time, detail, withdrawal and recorded history against the inspected record. Reopening and recording the same revision does not reuse the previous check, even within the same persisted timestamp second: reopening appends history. New observations also require a fresh check. A changed field refuses closure with `defect <id> changed its <field> while closure evidence was checked; close it again so the check covers its current repair and requirements`. The refusal leaves the concurrent record unchanged; CLI and Desktop use the same register operation.
  • The real home-document journey is `cargo test --manifest-path rust/Cargo.toml --test defects-home-document -- --nocapture`. Its runner must supply nonempty WISENT_TEST_EVIDENCE_DIR, WISENT_SOURCE_COMMIT, WISENT_SOURCE_SHA256 and WISENT_OUTPUT_DIR; Stado supplies these from its immutable worker request. It executes the actual release artifact at WISENT_OUTPUT_DIR/dist/oko, not Cargo's separately compiled test binary, and requires dist/SOURCE_REVISION to match the declared source. An unreadable revision file retains its path and OS cause. For local execution, use the actual retained release output and a retained evidence directory inside the checkout's ignored build directory. Each case uses a unique isolated home and register, retaining source/binary/test identities and command outputs or start errors. Every refused closure must leave the register byte-for-byte unchanged and print no successful record. These cases check document closure and refusals, not independent replay approval or Desktop rendering.
  • The origin-refusal journey refuses inherited GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR, GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES and GIT_NAMESPACE before creating fixtures. These selectors can override Git's working directory and redirect object writes. It does not clear them, change Git configuration or bypass hooks. Reports retain the child working directory, supplied stdin and isolated home/register paths without dumping the inherited environment.
  • `node tests/defects/origin-refusal.mjs` exercises the origin failure through the real CLI and Git. Supply OKO_BIN, OKO_TEST_SOURCE_REVISION and OKO_TEST_SUCCESS_EXIT. It creates only bare Git metadata in an isolated test home under .build/defects/origin-refusal, records a defect in its own register, observes Git's missing-origin refusal, requires Oko to expose that operation and cause, and verifies that the persisted defect remains open. No product checkout is copied or checked out and no operator register is changed. The source revision, binary/test digests, commands, exit statuses and persisted final record remain in the report after fixture cleanup.
  • The same isolated origin-refusal journey records a repair, checks that a missing manifest is retained in the release sweep's unreadable result, and attempts closure with absent and whitespace-only product declarations. Each refusal names the manifest and cause, emits no successful closure and leaves the persisted register byte-for-byte unchanged. It does not publish the fixture or use a substitute release identity.
  • The home-document journey also creates real symbolic links inside its isolated fixture: one targets a file outside its test home and another targets a document beneath repository metadata. Closure must refuse both, name the resolved boundary or checkout and leave the register unchanged. A link to a non-repository document still inside the home remains valid, with the accepted revision checked in the persisted register. These cases do not modify the operator's home or register.

Refusals and safe exits#

  • The usage refusals of `repaired` plus `oko defects requires --completeness <text>` (exit 2).
  • `<reference> cannot close <id>: Stado records no published release of <repository>, so no build contains it; record the pushed repair with `oko defects repaired <id> --revision <reference> --detail <what it changes>` and close it once a published release carries it`; `<reference> cannot close <id>: no published release of <repository> contains it (published: <versions>); …`; `<reference> cannot close <id>: it does not contain the recorded repair <repaired>; close it with a published revision that does`; `<reference> cannot close <id>: its recorded repair is <repaired>, in another repository; close it with a published revision of <repository> that contains that repair`.
  • For home:<path>@<sha256>: `revision <reference>: <path> is not a path under the home directory`; `revision <reference>: <file> is inside the git checkout <checkout>, so its repair is a commit there (<repository>@<commit>), proven by a published release`; `revision <reference>: <file> hashes to <actual> now, not <given>; name the SHA-256 of the file as it is (shasum -a 256 ~/<path>)`; `<file> cannot be read: <error>`; `<reference> cannot close <id>: its recorded repair is <repaired>, another document or repository`.
  • `defect <id> records <repair> now, not <checked> as checked; close it again so the release check covers that repair` when the repair changed while the release was being checked; `defect <id> was already closed by <revision>`; `stado release status <product> --json printed no readable document (<error>), so whether a build contains the revision is unknown` and the sibling sentence for a document without a runs list; `git merge-base --is-ancestor <revision> <commit> in <checkout> failed (<status>): <Git stderr>`. The ancestry diagnostic retains Git's actual cause; it does not guess that a published commit is missing.

CLI reference#