Defect register

Defect register#

A defect found in a Wisent product is recorded in Oko, with the evidence that was actually seen, what it costs while it is open, and the session that found it. It is closed by naming the revision that carries the repair.

Why it lives here, and not in a product's documentation#

A defect record needs the private details required to reproduce and repair it: observed hosts, paths, service labels and failures. Those details belong in Oko, not a published repository or documentation page. Product documentation describes the behavior, commands and diagnostic meaning without copying an incident record.

Oko already watches the work: it holds the sessions, the transcripts and the assignments a defect was found beside. The register is a file on the machine that found the defect, published nowhere.

A defect is not a task#

A task comes from the operator and closes when the answer is delivered. A defect is a fact about a product and closes only when the product stops being broken — often several sessions and several tasks later, sometimes without any instruction at all. If a defect were a task it would close with the conversation that found it, which is exactly what used to happen.

The two are tied by found_in: every record carries the session identifier, so the transcript and the work it interrupted can be read back.

Commands#

What a record holds#

found_in, repair_plan, the declared completion measure, notes, owner and priority, and any claimed_in, repaired_in, or fixed_in revision are retained. Standing is derived: an unsupported repair or closure becomes claimed and open; a check passed on main is verified until a published release closes it as fixed; a withdrawal is separate. There is no trusted mutable repaired label. A claim revision and failed check stay visible in notes and probe observations.

Oko Desktop receives that measured standing from the resident Oko native service on lists, detail reads and mutations. It does not infer verification from a nonempty repair revision, probe field or report path. An older service without the standing value is a decoding refusal, not a green repair card.

found_in is who found the defect or the one <repository>@<commit> that still has it. record and found-in refuse a value that names a revision but not exactly one commit: --found-in <value> names more than one revision for a list, --found-in <value>: <revision> is not a commit id for a branch or tag (they move), and <revision> is not a commit in <checkout> for a commit the workshop's checkout does not hold. Tama's build gate orders a repair after the commit the defect was found in, and none of those can be ordered.

repaired also refuses a revision committed before the defect was recorded when found_in names no commit of that repository: Tama's build gate would read such a repair as none. The refusal prints the command to run first, oko defects found-in <id> --revision <repository>@<parent of the repair> --reason <why>, after which the same repaired call is accepted.

oko defects unordered [--json] lists the open defects recorded before these refusals whose repair Tama's build gate still cannot order: the defect's id, its found-in, the recorded repair and that repair's parent, with the found-in command to run when the repair really is the fix. It changes nothing. A repair committed before its defect was recorded is either the fix recorded late or a revision that never fixed it; read the repair, then correct the found-in or withdraw the repair with reopen. Oko Desktop's Defects screen shows the same list under Repairs the build gate cannot order; each row's Name `<parent>` as found in asks why and runs the same operation as oko defects found-in.

An ordering check that cannot read Git never treats the repair as ordered. repaired refuses the operation and leaves the register unchanged. unordered lists a historical verified repair whose order cannot be read as its own row with the Git operation and actual cause; unqualified claims remain open, not repairs to order. A home-document repair uses its verified document digest instead of Git ancestry. The real CLI journey in tests/defects/found_in.rs exercises a finder revision, an unordered attempt, the correction and its still-unqualified claim.

oko defects rebased [--product NAME] [--apply] [--json] follows a found-in, repair or repair-claim revision a rewrite took off main. It matches the commit on main with the same author date and git patch-id --stable. --apply records found-in first and follows a claim to the new commit while retaining the old id in a note; it does not transfer a passed criterion report to a different source revision. A new report bound to the new commit must qualify the claim through repaired. A commit dropped rather than rewritten, a merge or empty commit, or a commit the checkout no longer holds is listed with its cause and recorded nowhere. naming <repository>@<commit> includes claims so Git gates can see the attempted work too. --json returns {id, field, recorded, on_main, cause, applied}.

oko defects released [--product NAME] [--close] [--json] lists the open defects whose recorded repair a published release already carries. Without --product it asks Stado once for every product's releases (stado release status --json, which reads every recorded run whatever product it is asked about, so asking it once per product cost the same read for every product), writes oko defects released: <product>: <n> published release(s) on stderr for each product that reading names, and judges the whole register against it; with --product it asks for that one product. A defect counts when its repair revision is an ancestor of (or is) one of the published source commits. Each line names the defect, the product, the version, the commit and the repair. With --close every listed defect is closed through the same fix and its release check, which reads the same answer, with the carrying release as the detail and the completeness; without it nothing changes. A product Stado does not release or cannot answer for is named once under not read: instead of stopping the read; a product the whole-fleet reading names no release of carries nothing. Run it after each batch release, so a repair the release published stops being counted as open work.

owner names who repairs the defect; priority orders the work. Records without those fields read as unassigned.

shape is the design property the defect is one instance of, written by record --shape or shape; the second defect of one shape is the finding, so the register names the others of a shape whenever one is recorded or shaped, and shapes reads them together.

A repair starts with the mechanism, not one incident: declare its shape and run shape-review on the proposed main revision. Oko reads siblings from the defect register and literal code paths from Git at that commit and its parent. When the mechanism recurs, the review names the shared concept and migration, or a consolidation defect already linked part-of from all members. repaired re-reads that inventory before it records a claim; it refuses a stale review with the missing shape, changed revision, members or source operation. In Oko Desktop → Defects → Record the pushed repair, Review mechanism performs the same search, shows its refusal in the sheet, and the defect card shows the persisted inventory. The claim record retains the review alongside completion evidence and verdicts; an adversarial reviewer checks that the claimed concept removed the private mechanisms.

The source construct must occur at the repair commit or its parent; an empty Git inventory is a refusal naming the literal and revision, not proof that the mechanism has no other callers. Defects → Shapes shows each class record and the source-bound reviews of its members alongside the open count.

The inventory distinguishes every path at the commit or parent from paths where the private construct still occurs at the proposed revision. CLI show prints both; older reviews without the current-source reading say to review again. The class task stays ready when a private occurrence remains even if one defect was closed; a partial patch cannot finish the class.

For an operator home document revision (home:<path>@<sha256>), Oko verifies the current document digest and searches that document itself; there is no Git parent. The real-journey criterion report still identifies that digest and the CLI-observed final document state before a repair is accepted.

Supervisor actions on a recorded executor also belong to the defect. Use oko sessions send EXECUTOR --text "redirect" --defect DEFECT --intervention redirect --submit, --intervention approval for permission, or oko sessions interrupt EXECUTOR --defect DEFECT for a running call. A submitted send with --assign gives that single executor the defect through the same register as oko defects assign; a draft without --submit refuses assignment before changing ownership or typing. Without an open, unrepaired defect Oko refuses before typing into a supervised executor. show retains each action's kind, message, target, time and actual result; another intervention on the same defect or shape raises its priority to high. A refused delivery is recorded with the broker's cause, not counted as a success. Oko Desktop's Sessions → Agent sessions has the same defect, message, redirect/approval, assignment and interrupt controls; the Defects screen shows their history.

Recording any defect now queues a Brama model reading of its design shape; --shape remains an explicit correction. The defect is recorded even while Brama cannot answer, and oko reflection list --pending names the failed operation and cause rather than pretending the defect has no common shape. The model compares existing shapes by mechanism, not spelling. Once another defect of the same product and shape is recorded, reflection upserts a class-repair work item assigned to a recorded executor. Its acceptance is a mechanism change, a sweep of existing instances and a real journey on the released repair. Closing one instance cannot close the class while another remains open. Fixing, withdrawing or reopening an instance requeues class status reconciliation. A database or assignment refusal stays in the queue with its cause.

The register is stored at ~/Library/Application Support/Oko/defects.json. OKO_DEFECT_REGISTER moves it, which is what a test uses and what a second machine points at its own copy.

Both registers are owned by oko, the one Oko program, and every verb of oko defects and oko blockers takes --json. Oko Desktop runs the same binary and only displays what it answers; OKO_BINARY names a different binary for it. When none is found, every screen says oko is not installed and lists the places it looked.

For example, if a second record --product stado --title "alerts send exited zero when every channel refused" … meets an open entry, the command exits nonzero and names that entry. Use oko defects note <id> --text "the failure happened again on another host"; investigate and repair the cause rather than adding a second open entry. After oko defects fix <id> --revision stado@<commit> --detail "delivery result is checked" --completeness "the replay on the released binary exits non-zero; the sweep found no other caller", a new failure with the same title is a recurrence and may be recorded separately. If the observations are different incidents despite an identical title, name the earlier ID with --distinct-from and say how they differ with --distinct-because; the register then keeps both, the reason in the new defect's notes. Transcript reflection asks Brama to compare the recorded operations and uses that distinction itself, recording the judge's reading as the reason, or leaves a cause in its queue when the model cannot decide.

Repair, one build, then the judge#

Work runs in three steps, the same for every task and every defect:

1. Repair. Write, commit and push the code, then record oko tasks evidence <task> --commit <repo>@<rev> and the source revision on a defect. oko defects repaired measures its declared check on main: passing evidence or a zero-instance inventory qualifies it; failure retains a claim, which the build gate still counts as open and unrepaired. Submit the qualified change through the product's release queue.

<repo> is the checkout's relative path under ~/Documents/CodingProjects/Wisent; <rev> is its pushed source revision. Nested repository paths are supported. A path with .. or a leading / is refused with <repo> is not a checkout path under the workspace, and a path with no checkout there with there is no checkout of <repo> at <path> to verify the revision against.

1. One build. Control counts unqualified tasks and defects. Claimed repairs remain unrepaired and cannot open the batch gate. After source work and qualification, Stado builds the queued products under the operator's standing decision. The control pass keeps Stado's own JSON answer for each build call; an answer that is not JSON is kept word for word as {unreadable, cause} with the parser's cause, and a refused call as {refused}. An open task whose handoff names no session is listed by the handoff it came in.
2. The judge. The real source-bound run, observed final state and release evidence qualify tasks; oko defects fix closes a verified repair carried by a published release, or the defect stays open.

No schedule builds on the clock: a build before every item carries its repair would test half the work.

Blocker register#

A blocker is something that genuinely stops work, and it lives in its own list next to the defect register, at ~/Library/Application Support/Oko/blockers.json (OKO_BLOCKER_REGISTER moves it). An answer's blocker section is not prose: every line names a blocker from this list by its eight-character identifier — one that is already there, or one the session has just added.

A resume condition must be a state somebody can check: a service answering, a release published, a file present. oko blockers record refuses a condition that waits for somebody's choice (a decision, deciding, choosing or picking, in Polish or English) with the operator's rule: "Czekanie na decyzje operatora jest ZABRONIONE. Masz pracowac az skonczysz swoje zadanie. Brak decyzji operatora nie jest blockerem." The recovery paths an agent would list for the operator to choose from are its own work, and it carries them out.

Tama's block-repeated-blocker stop gate enforces the rule. It refuses an answer whose blocker section has a line that names no registered blocker, names one that is off the list, or names one whose last still-blocks check is more than an hour old; each refusal prints the command that fixes it. An empty section, none or brak passes.

Blockers, under Work in Oko Desktop, shows the same list: the failed call, what it waits on, its error, what was tried, when work resumes and every check. Each open blocker has a reason field and two buttons, It still blocks and It can be resolved — take it off, which run the same operation as oko blockers check. A resolved blocker shows its resolution, a reason field and It blocks again — put it back, which runs oko blockers reopen. Work queue, at the top, shows oko work queue: every open defect in order with the reason for its rank, and a field for one executor as --executor does. What waits on what, below it, shows oko blockers graph: each loop, the critical path, every node something waits on with how many items it unblocks, and every edge with its source; a field cuts it through one node as --from does.

Ruling register#

A ruling records a standing decision about a task or defect: a consent, refusal, definition or prohibition. It lives at ~/Library/Application Support/Oko/rulings.json (OKO_RULING_REGISTER moves it). Each entry names its subjects, so another session can retrieve the standing decision without asking again, and its author: the member of the organization who said it, with their central role as the organization's register held it.

Any member of the organization may steer agents, not only one operator. Who may is read from the organization's register, never from a list in Oko: an owner steers by role, and any other member steers once an owner grants them Oko's steering.decide permission. oko rulings record refuses a member who may not steer and names the grant that would let them. When two decisions conflict, the later one supersedes the earlier only when it is repeated in the standing-rule ledger, its author may steer, and — when the earlier one is an owner's — its author is an owner too; the superseded ruling keeps the replacement, its author and that rule.

Every member's messages take the same path: each is stored with the member whose session said it, read for its kind, and placed in the task graph. oko tasks map prints by author: with the tasks per member, and --json gives every entry an author {member, email, role} from the register (only member once the register no longer lists them) and counts.byAuthor. Oko Desktop → Tasks → Task map shows the same counts labelled with each member's address. oko tasks rules --all --json names each standing rule's author, which oko rulings gates reconcile and oko rulings supersede check against the register before a rule binds a hook or replaces an earlier decision.

Use oko rulings record --session <source-session> --ordinal <message-number> --subject <task-or-defect-id> --by <recording-session> to bind an existing operator message to its subject. oko rulings list --subject <task-or-defect-id> retrieves the standing decision. The recorder supplies the message identity, not a replacement quotation. A correction he gave is finished only when oko rulings audit names its mechanism; a session that cannot build one yet runs oko rulings audit --record --product <product> --found-in <repo>@<revision> so the defect register holds it.

Rulings, under Work in Oko Desktop, shows the ruling standing on each subject — the operator's words, the session and message number, what it decides, who recorded it and Enforced by, the bound mechanism or nothing yet — and records a new one from a session, a message number and the subjects, running the same operation as oko rulings record. Each standing entry has a form that binds its mechanism (kind, name, product, revision; Bind this mechanism runs oko rulings enforce) and This ruling does not decide `<subject>` — take it off, which runs oko rulings unbind for that one subject. Find repeats runs oko rulings repeats and lists, per subject, the agent answers that named it after the ruling. Count what was said runs oko transcripts occurrences for the words typed, by anyone, the assistant or the operator, and shows the total, the count per session, the sessions this machine does not hold and every message that said them.

Operator messages and their records, on the same screen, takes a session and runs the same reading as oko rulings unlinked --session: every operator message with what it was read as and the task, ruling or defect it is linked to, and an Unlinked line naming the messages linked to none of them with their reading, or saying every message is carried by a task or linked to a ruling or a defect.

Who steers, on the same screen, lists every member with their central role and whether they steer, and offers Grant and Revoke for each member who is not an owner, running the same operations as oko rulings steering. Every ruling's words are labelled Said by `<email>` · `<role>`, and a superseded ruling shows the replacement's author and the precedence rule that decided it.

Wasted-build register#

A build started without checking the code and the installation first is recorded against the model that started it, at ~/Library/Application Support/Oko/shame.json (OKO_SHAME_REGISTER moves it). Each entry names the model, the session, the product, the build, what was not checked and what was lost, and raises that model's penalty.

Penalties grow with the number of entries a model has:

• One entry — `check-before-build`. Before each later build of a product, the model reads that product's installation state with stado product status <product> --surface <surface> and the open defects of the product and of Stado.
• Two entries — `no-build`. The model may not build for seven days from its second entry.
• Three or more entries — `no-code`. The model may not build, compile or test anything, with no end date.

Tama's block-one-off-repairs gate reads the penalty of the model the session's transcript last switched to, before any build consent or readiness check. no-build and no-code refuse the build. check-before-build refuses a build of a product until the same turn has run stado product status <product> successfully. The same gate refuses every fleet rollback (stado product rollback, stado release rollback, stado release restore-local): the way on is a forward repair, committed, pushed and installed.

Wasted builds, under Work in Oko Desktop, shows each model's penalty and every entry with what was not checked, what was lost, the session and the time it was recorded.

Purgatory#

When the operator gives an answer his worst verdict (oko rulings record --subject verdict:worst:<session>#<ordinal>), the session that gave it is held in purgatory: Tama's block-tools-in-purgatory refuses every tool call of that session, quoting his verdicts, until the session writes a self-criticism. The way out stays open: the session writes the self-criticism as the text of an answer and, in that same answer, runs oko purgatory confess --session <its id>, which copies that answer from the session's own transcript. Only that command and oko purgatory status --session <its id>, each as one plain command naming that very session, pass the gate; a confession for another session, one with another command riding along and one writing its output to a file are refused. The register is ~/Library/Application Support/Oko/purgatory.json (OKO_PURGATORY_REGISTER moves it).

A verdict the operator supersedes no longer holds anyone. Purgatory, under Work in Oko Desktop, lists the same sessions with each verdict, self-criticism and withdrawal; Record its newest answer as its self-criticism runs oko purgatory confess, and This is not a self-criticism — take it back asks why and runs oko purgatory withdraw.

In Oko Desktop#

Defects, under Work, reads the native register's counted list. Its summary shows open, claimed, verified, fixed, withdrawn from the same derived standing as oko defects list --counts, not an editable status. A claimed row retains the attempted revision, remaining instances or probe refusal and notes explaining why no check qualified it. The record also shows its evidence, impact, repair plan, observations, owner and priority. Record the pushed repair, Completion measure, Close with a revision, Write the repair plan and Assign use the same register operations as their CLI verbs; a refusal remains visible in the sheet rather than appearing as success.

Above the list, Show selects every defect, still broken, waiting for a verified repair or nobody assigned. Product, Owner and Shape narrow the same native list selection as CLI filters; the summary counts the full register after each refresh. A Shapes section groups records by their design property.

A closed defect carries a Reopen button beside the revision that closed it. It asks why the closing evidence does not prove the repair and runs the same operation as oko defects reopen: the defect lists as broken again and the old closing stays in its history as a note. A reopen without a reason cannot be sent, and the register's refusal of an open defect is shown in the sheet.

Record the pushed repair measures a source-bound real-journey report for one defect or reruns a revision-bound class inventory. For a single defect, retain the report JSON after the journey and pass its path as --evidence: defectId and criterion name this record and its declared measure, sourceRevision is the commit on main, result is passed, binarySha256 and testSha256 identify executed artifacts, commands records each executable, arguments, exit, stdout and stderr, and observedFinalState states the persisted or external result. The path is a measure, not a prose assertion. Missing files, mismatched identities or revisions, failed commands and absent observed state retain the revision as CLAIMED with the actual diagnostic. A passed check on main says VERIFIED, AWAITING RELEASE until a published release qualifies FIXED IN RELEASE. A rewritten commit needs a new journey report bound to its new revision. Withdraw the repair uses oko defects reopen, retaining the old claim in history.

An open defect also carries Withdraw as recorded in error. It asks what shows the product does not have the defect and runs the same operation as oko defects withdraw; the heading then reads WITHDRAWN, the record shows when and why, and Restore runs oko defects reopen to take the withdrawal back.