@agentsfleet/orly 0.10.13 → 0.11.0

package/dispatch/write_ts_adhere_bun.md

@@ -280,6 +280,16 @@ immediately preceding the edit. **User-invokable only.** Generic "scope creep" /
 - Length caps live in `dispatch/write_any.md` (LENGTH GATE — file ≤ 350, fn ≤ 50, method ≤ 70 — same as every other source language).
 - This file is the **TypeScript / Bun-specific** layer that those universal rules cannot express. Scan its section headers at the first TS/JS touch (`grep -nE "^##+ "` — two-plus hashes, so nested cards surface) and read the sections the diff shape touches; on sub-task shape change, re-scan and read only newly-touched sections — never the full file.
 
+## Repository design system
+
+> [JUDGMENT → ARCH]
+
+Use the consuming repository's declared component library and design tokens.
+Locate its exports and styles before substituting primitives; do not import
+another product's package or invent its directory layout.
+Run the repository's declared checks and review substitutions against that source.
+
+<!-- oracle-packs:start product.agentsfleet -->
 ## Merged from dissolved gate cards
 
 > [container]
@@ -491,3 +501,4 @@ If the arbitrary you want is a legitimate design value that simply has no token
 4. Add the utility to the table above in this gate body (same dotfiles commit — Invariance Suite Gate applies)
 
 This is the path to a system that grows without dilution.
+<!-- oracle-packs:end -->

package/dispatch/write_zig.md

@@ -31,13 +31,15 @@ Status: Canonical Zig source of truth for agents and commits
 
 > [JUDGMENT → ARCH]
 
-For every commit that touches `*.zig`, the agent runs the workflow below — no human approvals required mid-loop. This façade is the human-discipline complement to `make lint`; rules already enforced by lint are not duplicated here. The agent owns the rules that lint cannot mechanically catch.
+For every commit touching Zig, run the workflow below alongside the repository's
+declared conformance and verification commands. The reviewer owns the rules
+those commands cannot mechanically check.
 
 1. **Before write (trigger: about to edit / create `*.zig`):** scan this façade's section headers (`grep -n "^## " dispatch/write_zig.md`). Re-read any section whose topic the diff touches: concurrency for atomics / threads, allocator-ownership for new structs, doc-comments for new `pub` types, comptime assertions for new invariants, single-type-module pattern for new file structure, etc.
 
 2. **During write:** for each surfaced uncertainty (atomic ordering choice, allocator pattern, naming, structural choice), state the rule and the choice in chat — don't decide silently.
 
-3. **Before commit (post-`make lint`):** run a self-audit grep against the staged diff for the rules `make lint` does not enforce. Don't ask for approval; do the audit and either comply or state explicitly why an exception applies.
+3. **Before commit (after declared conformance):** inspect the staged diff for rules the repository's checks do not enforce. Comply or record an explicitly authorized exception.
     - Weak atomic orderings (`\.\(acquire\|release\|monotonic\|unordered\)\b`) — every match needs a `// safe because: ...` comment within 3 lines.
     - New `pub` symbols — confirm at least one external import via `grep -rn "<symbol>"`. Remove `pub` if unreferenced.
     - New structs that own heap memory — confirm `alloc:` field OR doc-comment naming the caller-owned-allocator pattern.
@@ -55,15 +57,15 @@ For every commit that touches `*.zig`, the agent runs the workflow below — no
 
 > [DETERMINISTIC → TODO-CHECK]
 
-- Run `make lint`, `make test`, and `gitleaks detect` before any commit that includes Zig changes.
-- Run the repository's database-backed integration lane, with `TEST_DATABASE_URL` pointed at its test database, when touching DB-backed handlers, proposal flows, or temp-table-based Zig tests.
+- Run the repository's declared conformance and verification commands and required secret scanner before committing Zig changes.
+- Run its database-backed integration lane with its declared test configuration when touching database behavior.
 - Read this file before creating any new `*.zig` file.
 - Use `conn.exec()` for INSERT / UPDATE / DDL whenever possible.
 - Drain early-exit `conn.query()` results before `deinit()`.
 - Copy row-backed slices before `q.drain()` or `q.deinit()`.
 - Materialize rows into owned memory before issuing writes on the same `pg.Conn`.
 - Keep temp-table fixtures aligned with the real production write contract.
-- Use `var rows: std.ArrayList(T) = .empty;` for ArrayList init (Zig 0.16; the `= .{}` form was 0.15). Pass alloc per-operation: `append(alloc, ...)`, `toOwnedSlice(alloc)`, `deinit(alloc)`.
+- Match container initialization and allocator calls to the repository's pinned Zig version; read that version's implementation before changing the shape.
 - Use `q.*.next()` and `q.*.drain()` when the query result is passed through `anytype` as a pointer (`&q`). Direct local vars use `q.next()`.
 - Reference nested struct types with the full path: `Module.Struct.NestedType`, not `Module.NestedType`.
 - Add new test files to test discovery. Either `_ = @import("path/to/new_file.zig");` in `main.zig`'s test block, or — preferred when a façade already exists — in a `test {}` block inside the façade (`test { _ = @import("foo_test.zig"); }`). Zig strips `test {}` blocks in release builds, so this adds zero bytes to the production binary. The façade pattern keeps `main.zig` at a flat one-line-per-module list and lets each module own its own test discovery.
@@ -99,12 +101,18 @@ For every commit that touches `*.zig`, the agent runs the workflow below — no
 
 > [DETERMINISTIC → PUB]
 
+Use the repository's selected linter and preserve its unused-public-symbol
+checks. If it has no such checker, review public consumers explicitly;
+installing this language pack does not select a linter version.
+
+<!-- oracle-packs:start product.agentsfleet -->
 - This repo uses `zlint` as part of `make lint`.
 - Pinned version: `v0.9.0`.
 - **`unused-decls: error` is load-bearing.** PUB GATE (the pub-surface section of this façade) delegates mechanical consumer-grep to this rule — a `pub` without an in-tree consumer fails `make lint`. Disabling or downgrading it silently bypasses half the gate; if you must, amend PUB GATE in the same diff so the design call is captured elsewhere.
 - `suppressed-errors` stays off because this repo intentionally uses narrow `pg` cleanup patterns that a generic rule cannot classify correctly.
 - `unsafe-undefined` is a good future tightening target once current low-level uses are cleaned up or annotated.
 - A disabled ZLint is not useful; prefer a scoped ruleset that passes today and tightens over time.
+<!-- oracle-packs:end -->
 
 ## Memory Safety Rules
 
@@ -262,10 +270,15 @@ fix it in the same commit. No spec needed — these are incremental improvements
 - Decide ownership before writing helpers: allocator, free/deinit path, and whether data is owned or borrowed.
 - If the file touches `pg`, apply the query lifecycle rules above before writing the first helper.
 
-## HTTP Integration Tests — Use TestHarness
+## HTTP Integration Tests
 
 > [JUDGMENT → ARCH]
 
+Use the repository's shared HTTP harness and real schema fixtures.
+Register new tests in its discovery graph and keep setup and cleanup owned by
+each test. Do not assume another product's harness or environment variable.
+
+<!-- oracle-packs:start product.agentsfleet -->
 Canonical source: `src/http/test_harness.zig`. Every `*_http_integration_test.zig` under `src/http/` MUST consume it.
 
 - **Do not** define a local `TestServer` / `RunningServer` struct, local `startTestServer()` / `startServer()`, local `sendReq()` / `sendRequest()`, or local `waitForServer()`. These are provided by `TestHarness` with a fluent Request/Response API.
@@ -274,17 +287,17 @@ Canonical source: `src/http/test_harness.zig`. Every `*_http_integration_test.zi
 - **Test fixtures live in a sibling `*_test_fixtures.zig`** beside the integration file, or in a shared fixture module — not inlined. See `src/http/webhook_test_fixtures.zig` for the pattern.
 - **Skip gracefully when DB is absent** — `TestHarness.start` returns `error.SkipZigTest` when `TEST_DATABASE_URL` is unset; tests just propagate it.
 - New file registration: add `_ = @import("..._test.zig")` to the `test {}` block at the bottom of `src/http/server.zig` (not `src/main.zig`). Integration tests discover from there.
+<!-- oracle-packs:end -->
 
 ## Commands
 
 > [DETERMINISTIC → TODO-CHECK]
 
-- `make lint`
-- `make test`
-- The database-backed integration lane, with `TEST_DATABASE_URL` pointed at the test database
-- `gitleaks detect`
-- Connection-drain audit — a static check that every `conn.query()` has `.drain()` in the same function. Run the repository's lane for it when touching any file that calls `conn.query()`.
+- Declared `conform` and applicable `verify.*` commands from `.orly/orly.json`.
+- The repository's database integration configuration and required secret scanner.
+- Query cleanup — drain every result before releasing its connection, including early exits. Use wrapper-owned draining where the repository provides it. Run any declared cleanup check and review the owner's cleanup path; no generic static check proves wrapper behavior.
 
+<!-- oracle-packs:start product.agentsfleet -->
 ## Zig 0.15.2 API Gotchas (M3_001)
 
 > [DETERMINISTIC → XCOMPILE]
@@ -293,17 +306,24 @@ Canonical source: `src/http/test_harness.zig`. Every `*_http_integration_test.zi
 - `std.fmt.parseHex` does not exist. Use `std.fmt.hexToBytes(&out, hex_str)` to decode hex to bytes.
 - `std.fmt.fmtSliceHexLower` does not exist. Use `std.fmt.bytesToHex(bytes, .lower)` to encode bytes to hex.
 - When unsure about an API, check the codebase first: `grep -rn "ArrayList\|hexToBytes" src/ --include="*.zig"` to see how existing code uses it.
+<!-- oracle-packs:end -->
 
 ## Cross-Compile Verification (M22_001)
 
 > [DETERMINISTIC → XCOMPILE]
 
+Compile the repository's declared platform matrix, including applicable test
+graphs. Execute platform-specific tests on their declared supported runtime;
+compilation alone does not prove runtime behavior.
+
+<!-- oracle-packs:start product.agentsfleet -->
 - Run `zig build -Dtarget=x86_64-linux && zig build -Dtarget=aarch64-linux` before every commit that touches Zig files. Do not rely on macOS-only compilation.
 - **Production-binary targets alone do NOT catch Linux-gated drift.** Code inside `if (builtin.os.tag == .linux)` branches and test-only helpers is comptime-dead on a macOS target and never analysed in the production graph (M82 shipped green locally; three Linux-gated `std.fs.accessAbsolute` sites failed CI). For cross-platform changes, also compile the linux **test graphs**: `zig build test -Dtarget=x86_64-linux` + `zig build test-lib -Dtarget=x86_64-linux` + `zig build --build-file build_runner.zig test -Dtarget=x86_64-linux`. A clean compile ending only in `unable to execute binaries from the target` is the PASS signal.
 - **Linux-gated tests compile but never RUN on macOS** (`SkipZigTest` off-linux) — a wrong runtime assertion slips through to CI (M84_007). To execute locally: cross-compile the test graph `-Dtarget=aarch64-linux`, take the static ELF from `.zig-cache/o/*/`, and run it in a **native arm64** container: `docker run --rm --platform linux/arm64 -v "$PWD:/w" -w /w debian:stable-slim /w/<binary>`. qemu-emulated x86_64 is a false oracle — its fork/clone emulation breaks tests that pass on real Linux. Note: prod children run under bwrap (closes non-passed fds), so bwrap-less tests must assert the *relative* fd property (child fds ⊆ parent), never absolute fd counts.
 - `std.http.Client.open()` does not exist on Linux targets in Zig 0.15.2. Use `client.request()` + `response.reader()` + `readVec()` for cross-platform HTTP streaming.
 - `std.Io.Reader` on Linux has `readVec()`, not `read()`. Use `readVec(&[_][]u8{&buf})` for single-buffer reads.
 - Verify stdlib API existence by grepping: `grep -n "pub fn" ~/.local/share/mise/installs/zig/*/lib/std/http/Client.zig`
+<!-- oracle-packs:end -->
 
 ## TLS Transport (M22_001)
 
@@ -496,7 +516,7 @@ Rules:
 
 > [DETERMINISTIC → XCOMPILE]
 
-- Verification runs the repository's DECLARED commands (`.oracle/orly.json`), never `zig build test` standalone. `zig build test` runs only the Zig unit set and silently skips every other language's tests and the cross-language gates the declared commands cover. Use `zig build` for compilation, never for "did my change pass tests".
+- Verification runs the repository's DECLARED commands (`.orly/orly.json`), never `zig build test` standalone. `zig build test` runs only the Zig unit set and silently skips every other language's tests and the cross-language gates the declared commands cover. Use `zig build` for compilation, never for "did my change pass tests".
 - A memory-leak lane, where the repository declares one, is required when the diff touches server lifecycle, allocator wiring, or cross-thread heap ownership. The macOS `leaks` tool prints a "not debuggable" line under System Integrity Protection — that is expected; the authoritative signal is the allocator-leak phase across `std.testing.allocator`-wrapped tests.
 
 ## Doc-Comments and Inline Comments
@@ -530,7 +550,8 @@ Extends "Type Design Rules". Two patterns, both legitimate; pick deliberately an
 
 > [DETERMINISTIC → TODO-CHECK]
 
-- snake_case throughout: file names, fields, functions, locals, constants. agentsfleet has no JS-interop boundary — there is no carve-out for camelCase fields. (Bun mixes the two for JS-mapped fields; we do not.)
+- Use snake_case for Zig names. Match externally defined field spellings only at an explicit interoperability boundary.
+- `agentsfleet` has no JavaScript interoperability boundary; its Zig fields stay snake_case. <!-- oracle-packs:product.agentsfleet -->
 
 ## RULE UFS — Named constants for repeated and semantic literals
 
@@ -641,8 +662,8 @@ paths never reach a global to allocate. Debug/test builds pick the leak-checking
 Purpose Allocator (GPA); release picks the C allocator. Global state never holds the allocator
 for a Zig path.
 **Exemplar:** ghostty `global.zig:74-96` (allocator selection at `main`, Valgrind detected at
-runtime). In-repo: `agentsfleetd/main.zig` and `runner/daemon/worker_pool.zig` own the GPA;
-everything below takes `alloc` as an argument.
+runtime). Everything below the owner takes `alloc` as an argument.
+In `agentsfleet`, `agentsfleetd/main.zig` and `runner/daemon/worker_pool.zig` own the GPA. <!-- oracle-packs:product.agentsfleet -->
 
 ### A2 — errdefer ladder: one errdefer immediately after each acquisition
 
@@ -831,20 +852,31 @@ PUB GATE and LIFECYCLE GATE answer different questions and neither defers to the
 
 The init/deinit pairing audit treats all of `deinit`, `close`, `release`, `destroy`, `shutdown`, `dispose`, `free` as lifecycle (cleanup) methods. Renaming `deinit` to `close` or `release` does NOT bypass the pairing requirement — a struct owning heap memory or an opaque handle still needs an `init`-paired cleanup method under any of those names.
 
-### Empty-pair and arena-leakage informational flags
+### Empty-pair and arena-lifetime review
 
-> [DETERMINISTIC → DEINIT]
+> [JUDGMENT → ARCH]
 
-Two non-blocking informational flags the pairing audit surfaces: (1) `init` body empty AND `deinit` body empty — likely a pair-for-shape that isn't actually needed; (2) an arena-allocated slice stored in a long-lived struct — the reviewer must either restructure the ownership or explicitly acknowledge the arena-lifetime mismatch. Neither blocks mechanically; both demand a reviewer decision rather than silent acceptance.
+The reviewer checks empty lifecycle pairs and arena-backed slices retained
+beyond the arena's lifetime. `deinit-pairs.sh` emits neither finding.
+Remove a redundant pair or explain its owned state; fix any lifetime mismatch
+before the owning object can outlive the arena.
 
-### Scope: full-tree audit, staged content satisfies the same hook run
+### Scope: full tree, explicit files and indexed content
 
 > [DETERMINISTIC → DEINIT]
 
-`deinit-pairs.sh` walks the full `src/` working tree via `git ls-files`. The index includes staged-but-not-yet-committed content, so a fix staged in pre-commit satisfies the check on the same hook run. `--staged` is preserved as an opt-in narrowing mode for iterative dev.
+`deinit-pairs.sh` defaults to tracked Zig files throughout the working tree.
+`--staged` checks staged paths from an owned snapshot of their indexed bytes and
+configuration; `-- <files>` checks only the named working-tree files.
+An unstaged fix cannot clear a staged violation.
 
 ### Deinit idempotency assertion (reviewer-owned)
 
 > [JUDGMENT → DIDEM]
 
-Every type with a cleanup contract should carry a test proving its cleanup method is idempotent (or its single-shot ownership is asserted) — the mechanical audit reports idempotency-test:<present|missing> but does not block on it; presence/absence is a reviewer responsibility, not a machine pass/fail. A struct whose `deinit` frees fields must have a test that exercises the success-cleanup path so the leak detector fires on a missed or double free.
+Every owning type needs a test of its cleanup lifetime.
+For a value that survives cleanup, prove repeated cleanup is safe; for a heap
+object that destroys itself, prove the owner releases it exactly once and
+clears its handle. Never call a method through a freed pointer.
+The leaf emits no `idempotency-test` result; the reviewer inspects the tests and
+allocation paths, including success and failed initialization.

package/docs/CHANGELOG_VOICE.md

@@ -4,7 +4,8 @@
 > Prerequisite: read [`DOCUMENTATION_RULES.md`](./DOCUMENTATION_RULES.md) first.
 > Changelog history keeps its archive exception; this file adds the narrower voice.
 
-Editing `~/Projects/docs/changelog.mdx` or any other Mintlify `<Update>` block.
+Use these voice rules in the repository's declared changelog.
+Apply Mintlify block rules only where that format is already selected.
 
 - **One headline per entry, no marketing words.** Apply Documentation rule 07
   (`DOC-07`) from `DOCUMENTATION_RULES.md`. Also ban "magical", "we are pleased
@@ -14,5 +15,13 @@ Editing `~/Projects/docs/changelog.mdx` or any other Mintlify `<Update>` block.
 - **Internal cleanup / refactor entries get the most aggressive trimming.** One lead paragraph + one bullet list. Skip "Test coverage" sections unless the test count is the headline. Indy's exact direction: *"Keep internal code cleanup, refactor to a minimal."*
 - **Never drop load-bearing facts.** Error codes (`UZ-AUTH-003`), endpoint paths + method + body shape + status code, env var names + defaults, schema column / table names, CLI subcommand + flag names, migration steps, money amounts. Tighten prose, not meaning.
 - **Historical entries are archives.** Brevity-pass them; never rewrite the past. A typo correction (e.g. `$0.001` → `$0.01` when it was never true) is allowed and must be called out in the commit message.
-- **Rate constants are declared once, so a money claim has one thing to match.** `rustd/crates/afd_billing/src/nanos.rs` holds the rates and `afd_core::money` holds the nanos denominator; the daemon charges from them and every client renders the figure it was served. A changelog rate or money claim is checked against those constants, never against a client. Public docs are the surface nothing reaches: when a rate changes, update `~/Projects/docs/snippets/rates.mdx` in a paired Pull Request (PR). In `*.mdx`, import its named values rather than hand-typing money amounts.
+- **Rate constants are declared once, so a money claim has one thing to match.**
+  Check claims against the repository's canonical billing constants and update
+  its published rate tables in the same change.
+<!-- oracle-packs:start product.agentsfleet -->
+- For `agentsfleet`, the rate sources are `rustd/crates/afd_billing/src/nanos.rs`
+  and the denominator in `afd_core::money`. Update
+  `~/Projects/docs/snippets/rates.mdx` through its authorized branch flow;
+  import its named values in Markdown JSX (MDX) instead of copying amounts.
+<!-- oracle-packs:end -->
 - **The Mintlify reference Indy pasted (May 1 / May 8 entries) is canonical voice.** Mirror its rhythm, not its product nouns.

package/docs/EXECUTE_DOC_READS.md

@@ -12,22 +12,22 @@ Every triggered document requires one `📖 DOC READ: <path>` proof-line **per t
 | Any source file (cross-cutting authoring) | `dispatch/write_any.md` — length, logging, milestone-id, error-registry, UFS, greptile read, legacy-workaround family. |
 | Porting a codebase, module, or subsystem from another language | `dispatch/write_any.md` §Porting a codebase between languages — a port is a rewrite with a conformance test: port the guarantee, delete the workaround, conform on observable behaviour, name the debt not carried over. |
 | Spec's "Applicable Rules" | Each rule (canonical). Missing → the cross-cutting codes of `dispatch/write_any.md` are the floor; surface omission. |
-| `*.zig` | `dispatch/write_zig.md`. ZIG GATE per edit. |
-| `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `dispatch/write_ts_adhere_bun.md` — TS FILE SHAPE DECISION (§1) at PLAN, const/import/Bun-primitive discipline, anti-patterns. |
+| `*.zig` | `dispatch/write_zig.md`. ZIG GATE per edit. | <!-- oracle-packs:language.zig -->
+| `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `dispatch/write_ts_adhere_bun.md` — TS FILE SHAPE DECISION (§1) at PLAN, const/import/Bun-primitive discipline, anti-patterns. | <!-- oracle-packs:language.typescript,language.javascript -->
 | `*.rs` | `dispatch/write_rust.md` — ownership, error variants, feature combinations, and contention tests. | <!-- oracle-packs:language.rust -->
 | Rust error type, `Result` alias, or any fallible signature | `dispatch/write_rust.md` §Error discipline — one error per crate, one `Result` alias, `#[from]` composition, `source()` never returns self. ERR-RS fires per edit: `audits/rust-error.sh` (via `dispatch/write_rust.sh`) blocks a `map_err` that stringifies its own cause and an error type with no alias in its crate; the remaining clauses stay judgment. | <!-- oracle-packs:language.rust -->
 | Designing a Rust function, type, or module; writing `match` on a `Result`/`Option`; any production `unwrap()` | `dispatch/write_rust.md` §Functional design — Result pipelines over control-flow trees, illegal states unrepresentable, bind once, `unwrap` needs a proved invariant. | <!-- oracle-packs:language.rust -->
-| `*.py` | `dispatch/write_python.md` — parsing boundaries, resource ownership, and specific exceptions. |
-| `*.sh` | `dispatch/write_shell.md` — quoting, array arguments, cleanup, input safety, and shell compatibility. |
+| `*.py` | `dispatch/write_python.md` — parsing boundaries, resource ownership, and specific exceptions. | <!-- oracle-packs:language.python -->
+| `*.sh` | `dispatch/write_shell.md` — quoting, array arguments, cleanup, input safety, and shell compatibility. | <!-- oracle-packs:language.shell -->
 | `*.mdx` | `dispatch/write_mdx.md` — structure, front matter, links, code fences, accessibility, and Mintlify isolation. | <!-- oracle-packs:language.mdx -->
 | Log emit (any language; see LOGGING GATE triggers) | `docs/LOGGING_STANDARD.md` — wire format (logfmt), severity ladder, error-code embedding, scope/event discipline, PII redaction, §10A tightenings. LOGGING GATE per edit. |
-| Lifecycle method in `*.zig` (`init|deinit|close|release|destroy|shutdown|dispose|free`) | `docs/LIFECYCLE_PATTERNS.md` — init/deinit pairing, errdefer placement, allocator ownership, defer/errdefer mutual exclusion, §10A tightenings. LIFECYCLE GATE per edit. |
-| `rustd/crates/afd_api*/src/handler/**` or `public/openapi/**` | `docs/REST_API_DESIGN_GUIDELINES.md` — Quick Checklist; §1–§5 (URL/method/body/response/error), §6 (OpenAPI), §7 (6-place route registration), §8 (`Hx` handler interface), §10 (pre-PR gates). |
+| Lifecycle method in Zig | `docs/LIFECYCLE_PATTERNS.md` — ownership, acquisition cleanup, repeated cleanup of surviving values and exactly-once release of self-destroying objects. | <!-- oracle-packs:language.zig -->
+| HTTP handlers, route registration or OpenAPI | `docs/REST_API_DESIGN_GUIDELINES.md` — endpoint checklist and the repository's mounted authorization and handler shape. | <!-- oracle-packs:domain.http -->
 | `ui/packages/**/*.{tsx,jsx,css}`, `app/**/*.{tsx,jsx,css}`, `components/**/*.{tsx,jsx,css}`, repo-root `globals.css`, or any file changing visual tokens / motion / typography | `DESIGN.md` (repo root) or `docs/DESIGN_SYSTEM.md` — whichever the repo carries. Design system source of truth: typography stack, color tokens, the single accent and its currency rule, motion signature, spacing/density, component principles, CLI palette mapping. DOC READ proof-line per turn. |
-| `*.tsx` / `*.jsx` under `ui/packages/{app,website}/` | `dispatch/write_ts_adhere_bun.md` (Design Tokens) — token-utility table (text/tracking/leading/max-w/min-w/spacing/motion/radius/color). DESIGN TOKEN GATE fires per edit; audit via project-side `audits/design-tokens.sh`. |
+| `*.tsx` / `*.jsx` under `ui/packages/{app,website}/` | `dispatch/write_ts_adhere_bun.md` (Design Tokens) — token-utility table (text/tracking/leading/max-w/min-w/spacing/motion/radius/color). DESIGN TOKEN GATE fires per edit; audit via project-side `audits/design-tokens.sh`. | <!-- oracle-packs:language.typescript,language.javascript -->
 | Auth-flow | `docs/AUTH.md`. |
-| Published `*.mdx`, reusable Markdown JSX (MDX) fragment, customer readme, or public OpenAPI prose | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` — establish page, fragment, API, or changelog scope before narrower guides. |
-| Changelog `<Update>` / release note (`changelog.mdx`) | First `dispatch/write_documentation.md`, then `dispatch/write_changelog.md` → `docs/CHANGELOG_VOICE.md`; internal-only ⇒ no entry. |
+| Published `*.mdx`, reusable Markdown JSX (MDX) fragment, customer readme, or public OpenAPI prose | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` — establish page, fragment, API, or changelog scope before narrower guides. | <!-- oracle-packs:domain.documentation -->
+| Changelog `<Update>` / release note (`changelog.mdx`) | First `dispatch/write_documentation.md`, then `dispatch/write_changelog.md` → `docs/CHANGELOG_VOICE.md`; internal-only ⇒ no entry. | <!-- oracle-packs:domain.changelog -->
 | Write or update a PR/MR body, including session notes (`gh pr create/edit --body`, `glab mr create/update --description`, forge API, helper, or skill) | `dispatch/write_pr_description.md` — append-only numbered session unit, measured diagram, review findings, and command output. |
-| `schema/*.sql` / migration | `dispatch/write_sql.md` + `docs/SCHEMA_CONVENTIONS.md` — naming/type conventions, schema/migration rules + Schema Table Removal Guard. Re-print Schema Guard output. |
+| SQL / migration registration | `dispatch/write_sql.md` + `docs/SCHEMA_CONVENTIONS.md` — the repository's live-data policy and selected product guard. | <!-- oracle-packs:domain.sql -->
 | Any spec under `docs/v*/{pending,active,done}/` or `docs/TEMPLATE.md` | `docs/TEMPLATE.md` "Prohibited" section — no time/effort estimates, no complexity ratings, no percentage-complete, no owners/dates. SPEC TEMPLATE GATE per edit. |

package/docs/HARNESS_VERIFY_OUTPUT.md

@@ -7,13 +7,16 @@ Runs after EXECUTE, before VERIFY. Aggregates every gate verdict; lifecycle cann
 
 ## Combined end-of-turn audit
 
-Single awk over `git diff -U0 HEAD`, replaces 4 separate self-audits. For every `+` line:
+`audits/msid-ui.sh` makes one awk pass over added lines. Its default
+`--staged` mode reads `git diff --cached -U0`; `--diff` reads the comparison
+revision through checkout HEAD (`audits/msid-ui.sh:76–85`). It emits:
 
 - Emit `MS-ID:` hits when file is source/config and matches `M[0-9]+_[0-9]+|§[0-9]+(\.[0-9]+)+|\bT[0-9]+\b|\bdim [0-9]+\.[0-9]+\b`.
-- Emit `PUB:` hits when `*.zig` and line matches `^\+(pub | *pub fn | *[A-Z][a-zA-Z]+,$)`.
 - Emit `UI:` hits when under `ui/packages/app/**.{tsx,jsx}` and line contains `<(section|button|input|dialog|article|nav|header|form)\b`.
 
-Non-empty = address before CONFORM passes.
+Non-empty = address before CONFORM passes. Public declarations remain subject
+to the separate Public (PUB) Gate: zlint checks unused declarations, and the
+agent records the shape decision (`audits/msid-ui.sh:16–33`).
 
 ## Required output
 

package/docs/JUDGMENTS.md

@@ -0,0 +1,153 @@
+---
+type: reference
+audience: contributor
+verified: 2026-10-04
+product_version: 0.11.0
+executable: false
+---
+
+# Jev judgment advice
+
+## Synopsis
+
+`orly judge` asks one bounded question about evidence you select.
+It accompanies planning, verification, review and documentation.
+Its answer suggests an inspection or a fixed next action.
+
+```text
+orly judge <plan|verify|review|document> --input <manifest>
+  [--project <root>] [--refresh] [--json]
+```
+
+Jev is TypeSafe's System One model.
+The command pins `jev-1.13.0` and runs TypeScript source with Bun.
+Use the same `bunx` installation as 0.10.x.
+TypeScript 7 is development tooling; evidence selection uses a JavaScript parser.
+
+Advice cannot approve work, change a gate result or run a suggested command.
+Existing deterministic checks and owner decisions still apply.
+Hooks do not request advice or upload source.
+
+## Example with output
+
+Save a manifest describing the required result and its evidence:
+
+```json
+{
+  "stage": "verify",
+  "items": [{
+    "id": "locale",
+    "question": "verify.assertion",
+    "requirement": "The label matches the requested locale's formatted date, including year, month and day.",
+    "evidence": [
+      { "role": "implementation", "path": "src/label.ts", "selector": { "kind": "file" } },
+      { "role": "test", "path": "src/label.test.ts", "selector": { "kind": "test", "name": "label respects locale" } }
+    ]
+  }]
+}
+```
+
+Run without refresh to read an existing exact replay:
+
+```sh
+orly judge verify --input judgments.json
+```
+
+For inputs without a replay, the command reports:
+
+```text
+Jev advice — deterministic checks and owner decisions still apply.
+locale: incomplete — No exact replay for these inputs. Use --refresh to permit scanned source upload.
+```
+
+This result has exit status `2` and makes no provider request.
+To request live advice, supply `TYPESAFE_API_KEY` through your environment and install `gitleaks`.
+Then explicitly permit the selected source upload:
+
+```sh
+bunx @agentsfleet/orly judge verify --input judgments.json --refresh --json
+```
+
+The report includes typed answers, selected source references, request counts, elapsed time and token usage.
+The report excludes selected source text and credentials.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| Stage | Must match the manifest and each selected question |
+| `--input` | Required JSON manifest path; maximum 64 KiB |
+| `--project` | Evidence root; defaults to the current directory |
+| `--refresh` | Permits secret-scanned evidence upload and one provider request per item |
+| `--json` | Prints a structured report |
+| `--help` | Prints usage, selectors and the question catalog |
+
+Kibibyte (KiB) means 1,024 bytes.
+A manifest contains at most 12 uniquely named items.
+Each item has a question, requirement and at most eight evidence references.
+
+Each reference names a role, relative path and selector.
+Roles are `spec`, `implementation`, `test`, `rule`, `claim`, `result` and `context`.
+Name necessary unchanged context explicitly; the command does not discover dependencies.
+
+| Selector | Required fields | Selected evidence |
+|---|---|---|
+| `file` | `kind` | Whole bounded file |
+| `function` | `kind`, `name` | One complete TypeScript or JavaScript function |
+| `test` | `kind`, `name` | One named executable `test` or `it` call |
+| `section` | `kind`, `heading` | One plain Markdown heading through its peer or ancestor boundary |
+
+Duplicate matches, skipped tests, malformed syntax and escaping paths are refused.
+Individual files have a 256 KiB cap; complete selected state has a 24 KiB cap.
+Oversized evidence is refused rather than truncated.
+
+### Atomic questions and timing
+
+| Question | Run when | Required input | Jev criterion | Decision to take |
+|---|---|---|---|---|
+| `plan.prerequisites` | Before accepting a plan | One requirement and its `spec` evidence | Necessary inputs, credentials, fetch locations, permissions and ordering are explicit | Clarify a missing prerequisite |
+| `plan.observable_result` | Before implementation | One requirement and its `spec` evidence | Success and refusal have concrete observable results | Add the missing expected result |
+| `verify.assertion` | Before accepting a test as proof | Required behavior plus complete `implementation` and `test` evidence | The assertion checks that behavior, distinguishes a supplied wrong result, and targets the named operation | Keep the exact assertion or strengthen a weak, missing or misplaced assertion |
+| `review.failure_path` | While disposing of a failure finding | One named failure requirement and `implementation` evidence | The path preserves the failure and handles acquired resources | Trace the path and add a failure test |
+| `review.rule_applicability` | Before deciding a rule finding | One `rule`, its condition and `implementation` evidence | The selected code meets that rule's trigger | Apply the rule or inspect applicability; the owner decides exceptions |
+| `document.claim` | Before publishing a claim | One `claim` plus `implementation` or measured `result` evidence | Evidence supports the exact scope, quantities and conditions | Narrow the claim or collect missing proof |
+
+Choice answers classify assertions as `exact`, `weak`, `wrong_target`, `missing` or `insufficient`.
+Noul answers provide a probability for the question's stated property.
+The question catalog supplies fixed actions; the model cannot supply commands.
+
+The experiment marks strength below `0.8` as uncertain.
+This threshold has no independent calibration.
+Uncertainty requires inspection and cannot waive a rule or satisfy verification.
+
+### Replay and request limits
+
+Default mode reads `.orly/judgments/` without contacting the provider.
+Identity binds the project root, model, question definition, requirement, selectors and selected source bytes.
+Changed inputs require an explicit refresh.
+
+Live preflight checks every item before uploading any item.
+Each request has a 15-second deadline, including response reading, and a 64 KiB response cap.
+Requests are sequential and receive no automatic retries.
+
+Replay files use private permissions and omit source text.
+Their checksum detects accidental reply changes; a local owner can edit and reseal them.
+Replay remains advisory and cannot prove independent model accuracy.
+
+## Errors
+
+| Result | Meaning and next step |
+|---|---|
+| Exit `0` | Every item has valid advice; concerns and uncertainty still require inspection |
+| Exit `2` | An item or manifest is incomplete; inspect the reported reason |
+| No exact replay | Use unchanged inputs or explicitly request refresh |
+| Missing credential | Supply the provider key through the environment |
+| Failed secret scan | Remove credentials from selected evidence before retrying |
+| Missing or ambiguous evidence | Correct the reference or include necessary context |
+| Invalid provider reply | No valid replay was saved; inspect the provider failure before retrying |
+
+## Related pages
+
+- [Architecture](ORLY_ARCHITECTURE.md)
+- [Project overview](../README.md)
+- [Unit test skill](../skills/orly-write-unit-test/SKILL.md)

package/docs/LIFECYCLE_PATTERNS.md

@@ -149,7 +149,10 @@ pub const Watcher = struct {
 **Mandatory rules:**
 
 1. **`deinit` must free everything `init` allocated.** Lints catch the inverse (`init` allocates, `deinit` doesn't free) but not silently-correct cases (`init` allocates A and B, `deinit` frees only A — silent leak). Reviewer responsibility: walk the alloc list against the free list.
-2. **`deinit` must be idempotent.** Calling it twice must not crash. Either set freed pointers to undefined (`self.events = &.{}` after free) or guard with `if (self.events.len > 0)`.
+2. **Cleanup follows the object's lifetime.** A surviving value clears its
+   owned fields and permits repeated cleanup. A heap object that destroys
+   itself is released exactly once by its owner, which clears its handle;
+   calling `deinit` through the freed pointer is forbidden.
 3. **`deinit` does not return errors.** Cleanup that *can* fail (closing a file, flushing a buffer) must be split into a separate explicit method (`pub fn close(self: *Self) !void`) called before `deinit`, or the failure must be logged and swallowed inside deinit.
 4. **No partial deinit.** Once `deinit` runs, the struct is dead. Don't leave half-freed state for "the caller will free the rest" — that's a leak waiting to happen.
 5. **Deinit order is reverse of init order.** Free children before freeing the parent that owns them. `errdefer` chains in init naturally produce the right order; mirror it in deinit.
@@ -254,17 +257,21 @@ Anything else is a smell:
 
 The struct's `deinit` method is the single source of truth for cleanup. Call sites use `defer self.deinit()` (or `errdefer` if ownership might transfer mid-function) and never reach inside the struct.
 
-## §10 · Anti-patterns flagged by `deinit-pairs.sh`
+## §10 · Machine checks and mandatory ownership review
 
-| Pattern | Severity | Fix |
+`deinit-pairs.sh` checks refined public initializer/cleanup pairing and nearby
+`defer`/`errdefer` conflicts on the same target. It does not prove struct-level
+ownership, cleanup placement, allocator lifetime or failure-path coverage.
+
+| Pattern | Detection | Fix |
 |---|---|---|
-| `pub fn init(` with no matching `pub fn deinit(` in the same struct | **blocking** | Add `deinit`, or remove `init` if the struct is value-type without resources. |
-| `pub fn deinit(` with no matching `pub fn init(` | **blocking** | Likely tail of a refactor — restore init, or rename deinit to a non-lifecycle name (e.g. `close`, `release`). |
-| `errdefer` at end of init scope (batched) | informational | Move adjacent to the allocation it protects. |
-| `defer` and `errdefer` on the same allocation | **blocking** | Pick one. |
-| `init` returning `*Self` without `errdefer alloc.destroy(self)` | **blocking** | The most common leak class on init failure. |
-| `deinit` that calls allocator-storing struct's `allocator` field after some other field's `.deinit()` (use-after-free risk if children depend on parent's allocator) | informational | Reorder cleanup to free children first. |
-| Stored allocator field never used in deinit | informational | Either remove the field or wire it. |
+| Allocating or heap-returning public `init` without a same-file cleanup method | **blocking machine check**; reviewer verifies the matching owner | Add the owner's cleanup method; resource-free value initialization needs no empty pair. |
+| Cleanup with no corresponding ownership acquisition | **mandatory review** | Check all acquisition paths before removing or renaming the method. |
+| `errdefer` at end of init scope (batched) | **mandatory review** | Move adjacent to the allocation it protects. |
+| `defer` and `errdefer` on the same allocation | **blocking machine check** within four lines; mandatory review elsewhere | Pick the cleanup matching the ownership path. |
+| `init` returning `*Self` without failure-path destruction | **mandatory review** | Release the heap owner on every failed initialization path. |
+| Cleanup order invalidates an allocator still needed by children | **mandatory review** | Release children before invalidating their allocator. |
+| Stored allocator field never used in cleanup | **mandatory review** | Remove the field or release the owned resources through it. |
 
 ## §10A · Tightening clauses (closures of common skip rationalizations)
 
@@ -272,18 +279,21 @@ Failure modes the audit script and reviewer must close. These are **not aspirati
 
 | # | Rationalization | Closure |
 |---|---|---|
-| LC1 | "Struct is small / one allocation, skip `deinit`" | Any heap allocation OR opaque handle (file descriptor, mutex, socket, GPU resource, lock) requires `deinit`. **No size threshold**. Audit script flags struct definitions with `allocator.alloc`/`alloc.create`/`std.fs.File.open` whose enclosing struct lacks `pub fn deinit`. |
+| LC1 | "Struct is small / one allocation, skip `deinit`" | Every owned allocation or opaque handle needs cleanup. The leaf checks allocating or heap-returning public initializers for a same-file cleanup method; the reviewer checks ownership acquired later and matches every acquisition to release. |
 | LC2 | "Renamed `deinit` to `close` / `release` to dodge pair audit" | Audit script treats `deinit`, `close`, `release`, `destroy`, `shutdown`, `free`, `dispose` as **lifecycle methods**. All require a paired `init` and trigger LIFECYCLE GATE. Rename does not bypass; intent does. |
-| LC3 | "I'll batch `errdefer` at the bottom of init, easier to read" | The LAST `errdefer` line in init must lexically precede the LAST allocation it protects. Audit script enforces line-position. Batched-at-bottom errdefer is **blocking**. |
+| LC3 | "I'll batch `errdefer` at the bottom of init, easier to read" | Place each `errdefer` immediately after its acquisition, before the next fallible operation. The reviewer checks every early return; the leaf does not enforce placement. |
 | LC4 | "Both `defer` and `errdefer` on the same allocation, belt-and-suspenders" | Audit greps for `defer X.free(Y)` + `errdefer X.free(Y)` (or the reverse) in the same scope. **Blocking violation** — pick one per §6. |
-| LC5 | "`deinit` is idempotent in practice; no test needed" | Every struct with `deinit` must have a `*_test.zig` test that calls `s.deinit(); s.deinit();` and asserts no crash (sentinel-on-second-call is fine). Reviewer responsibility. Audit cannot fully grep for this; reviewer must verify. |
-| LC6 | "Storing arena slice in long-lived struct works in my test" | Heuristic flag: struct fields of slice type AND a stored `*ArenaAllocator` field → audit raises informational warning. Reviewer must acknowledge or restructure. |
-| LC7 | "Empty no-op `init` paired with empty no-op `deinit` to satisfy the gate" | Audit informational-flags when both `init` and `deinit` bodies are empty or single `_ = self;`. Pair exists for shape, not for state — likely should be a `const` value or removed. |
+| LC5 | "Cleanup works in practice; no test needed" | Reviewer verifies repeated cleanup of surviving values or exactly-once release and cleared owner handles for self-destroying heap objects. Never invoke a freed object's method. The leaf reports no test-presence verdict. |
+| LC6 | "Storing arena slice in long-lived struct works in my test" | Reviewer checks that the arena outlives every retained slice and fixes any mismatch; the leaf emits no arena-lifetime warning. |
+| LC7 | "Empty no-op `init` paired with empty no-op `deinit` to satisfy the gate" | Reviewer removes redundant pairs or explains their owned state; the leaf emits no empty-pair warning. |
 | LC8 | "Auto-mode is on" | **Auto-mode does NOT cover gate skips.** Skip without explicit user-given override = automatic violation. |
 | LC9 | "Renamed-only file (no content change), gate doesn't fire" | Rename without content change does **not** fire LIFECYCLE GATE. Rename + content change does. Pure rename is a no-op for the gate. |
 | LC10 | "Two docs disagree (e.g. write_zig.md says X, LIFECYCLE_PATTERNS says Y)" | Precedence: dispatch façade > standards doc > spec. The façade (`dispatch/write_zig.md`, lifecycle) is the canonical enforcement layer. |
 
-These are enforced by `deinit-pairs.sh` (mechanical) and the dispatch façade (`dispatch/write_zig.md`, lifecycle — output discipline). When in conflict, the façade wins.
+`deinit-pairs.sh` checks allocating initializer pairs and adjacent conflicting
+`defer`/`errdefer` releases. The reviewer handles the other obligations above;
+a green leaf result cannot replace them. The dispatch façade names the same
+ownership rules.
 
 ## §11 · Carve-out: PUB GATE vs LIFECYCLE GATE