@agentsfleet/orly 0.7.0 → 0.8.0

package/dispatch/lib.sh

@@ -80,6 +80,7 @@ declare -A DISPATCH_GLOSS=(
   [LOG]="LOGging discipline (scoped event, error_code, severity, redaction)"
   [MSID]="Milestone-ID ban in source (M{N}_{NNN} / §x.y / T{N} / dim)"
   [ERR]="ERror Registry (UZ-XXX-NNN declared + referenced)"
+  [ERR-RS]="Rust ERror discipline (one type per crate, Result alias, no stringified cause)"
   [GRP]="GREptile rule audit (diff vs greptile-learnings/RULES.md codes)"
   [LDC]="Legacy-Design Consult (A remove / B patch / C keep)"
 )
@@ -92,13 +93,35 @@ dispatch_init() {
   DISPATCH_EXTS=("$@")
 }
 
+# Paths this repository's engine wrote, one per line, from the install record.
+#
+# A managed file is orly's, not the repository's: the next `orly update`
+# overwrites it, so a finding against one is a chore nobody can complete. Left
+# unfiltered, staging a fresh install put orly's own leaf helpers in front of
+# orly's own length gate — audits/logging.sh is 444 lines against a 350 cap —
+# and the first commit of an adoption failed on the adoption itself.
+dispatch_managed_paths() {
+  local config="$TARGET_ROOT/.oracle/orly.json"
+  [ -f "$config" ] || return 0
+  sed -n '/"managed"[[:space:]]*:[[:space:]]*\[/,/\]/p' "$config" \
+    | grep -oE '"[^"]+"' \
+    | sed -e 's/^"//' -e 's/"$//' \
+    | grep -vx 'managed' || true
+}
+
 # Resolve targets: explicit file args, or --staged self-discovery via git.
+# Explicit arguments are never filtered — naming a file is asking about it.
 dispatch_resolve_files() {
   DISPATCH_FILES=()
   if [ "${1:-}" = "--staged" ]; then
-    local pathspecs=() e
+    local pathspecs=() e managed
     for e in "${DISPATCH_EXTS[@]}"; do pathspecs+=("$e"); done
-    while IFS= read -r f; do [ -n "$f" ] && DISPATCH_FILES+=("$f"); done \
+    managed="$(dispatch_managed_paths)"
+    while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      [ -n "$managed" ] && grep -qxF "$f" <<<"$managed" && continue
+      DISPATCH_FILES+=("$f")
+    done \
       < <(git -C "$TARGET_ROOT" diff --cached --name-only --diff-filter=ACMRT -- "${pathspecs[@]}" \
           | grep -vE '(^|/)(vendor|third_party|node_modules|\.zig-cache|dist|build|\.next)/' || true)
   elif [ "$#" -ge 1 ]; then
@@ -124,9 +147,11 @@ dispatch_resolve_files() {
 # dispatch must never claim a file its gates cannot parse.
 dispatch_add_shebang_files() {
   [ "${1:-}" = "--staged" ] || return 0
-  local f base path firstline
+  local f base path firstline managed
+  managed="$(dispatch_managed_paths)"
   while IFS= read -r f; do
     [ -n "$f" ] || continue
+    [ -n "$managed" ] && grep -qxF "$f" <<<"$managed" && continue
     base="${f##*/}"
     case "$base" in *.*) continue ;; esac
     path="$TARGET_ROOT/$f"; [ -f "$path" ] || path="$f"; [ -f "$path" ] || continue

package/dispatch/lifecycle.md

@@ -10,6 +10,33 @@ that moment. 🤔 judgment-only — no `.sh` pair; CONFORM's deterministic gates
 Section-scan first (`grep -n "^## " dispatch/lifecycle.md`); read the stage you
 are entering, not the whole file.
 
+## What runs at each stage
+
+The mechanical half of the lifecycle, in one table. Everything in the "runs"
+column is a command, not a claim — `orly gate` reads the repository's declared
+`.oracle/orly.json` commands and never invents one.
+
+| Stage | Runs | Fired by |
+|---|---|---|
+| CHORE(open) | the declared `verify.unit` once, to record `Test Baseline:` | the agent |
+| PLAN | nothing — no file mutations | — |
+| EXECUTE | the dispatch façade for each edited file type; DOC READ recorded via `audits/doc-read.sh log` | the agent, and the runtime's read hook where it has one |
+| CONFORM | the declared `conform` command | `orly gate work` — the generated pre-commit hook |
+| VERIFY (Section) | `conform` plus the declared lane covering the surface touched | the agent |
+| VERIFY (milestone) | the fast `verify.*` set: lint, unit, version | `orly gate verify` — the generated pre-push hook |
+| REVIEW | gstack `/review` over the diff | the agent |
+| DOCUMENT | nothing mechanical | — |
+| COMMIT | `conform` again, on the staged tree | the pre-commit hook |
+| CHORE(close) | every spec criterion, branch shape, clean tree, pushed branch, docs surface, and the slow `verify.*` suites | `orly gate pr`, by hand, before `gh pr create` |
+| LAND | nothing gated | — |
+
+Three properties hold this together. A gate only asks what it can answer
+honestly at that moment: `work` judges no git state, because a commit hook's
+tree is dirty by construction and a new spec is committed on the default branch.
+Each tier runs once per cadence — `conform` at commit, the fast set at push, the
+slow set at the close. And `orly gate pr` can skip the fast set because
+`git.pushed` proves HEAD is the commit pre-push already graded.
+
 ## CHORE (open) — runbook
 
 1. Spec `docs/v*/pending/` → `active/`; `Status: IN_PROGRESS`; `Branch:` set.

package/dispatch/verify.md

@@ -31,24 +31,52 @@ Package-scoped runners (`bun run test`, `vitest <file>`, `cargo test -p <crate>`
 are **not** verification — they skip every other package's lint and tests and the
 cross-language gates. The declared `make` targets are the canonical gates.
 
-## Required runs
+## Two cadences, one boundary
+
+"Always" is not a cadence. A Section closing and a milestone closing are
+different claims, and running the whole declared set at both spends the
+wall-clock of the comprehensive tier to answer a question the scoped lane
+already answered.
+
+The gates match those cadences: `orly gate work` runs the declared `conform`
+alone (every commit, seconds), `orly gate verify` runs the fast `verify.*` set
+(every push), and `orly gate pr` runs the whole-branch criteria and the slow
+suites (the close). Each tier runs once per cadence.
+
+**Section lane (per Section, and per done-claim inside one).** `make
+harness-verify` — the declared `conform`, seconds — plus the lane that covers
+the surface the Section touched (`make test-unit-rustd`, `make test-unit-app`,
+…). This proves a Section. It is not a repository claim and never satisfies a
+VERIFY row on its own.
+
+**Milestone boundary (once, at CHORE(close), before the PR).** Every command
+`.oracle/orly.json` declares, in one pass: `conform`, `verify.lint`,
+`verify.unit`, `verify.version`, and the slow tier (`verify.integration`,
+`verify.memory`). This is the repository claim, and it is what the done-message
+below reports.
+
+Run `orly gate pr` at the close. It does not re-run the fast tier, and it does
+not need to: its own `git.pushed` criterion proves HEAD is exactly the commit
+the pre-push `orly gate verify` already graded. A bare `orly gate` chains all
+three gates — use it on a branch whose earlier gates never ran.
 
 | Target | When |
 |---|---|
-| `make lint-all` | Always. The declared `verify.lint`. |
-| `make test-unit-all` | Always. The declared `verify.unit` — the cargo workspace plus every package coverage gate. |
-| `make harness-verify` | Always. The declared `conform` — the deterministic gate audit. |
-| `make check-version` | Always. The declared `verify.version`. |
+| `make harness-verify` | Section lane and boundary. The declared `conform` — the deterministic gate audit. |
+| `make lint-all` | Boundary. The declared `verify.lint`. |
+| `make test-unit-all` | Boundary. The declared `verify.unit` — the cargo workspace plus every package coverage gate. |
+| `make check-version` | Boundary. The declared `verify.version`. |
+| `make test-integration-rustd` | Boundary. The declared `verify.integration` — live Postgres and Redis; `orly gate pr` skips it on a branch carrying no code. |
 | `make wire-fixtures` | The `/v1/runners` wire types changed. Regenerate, then review the diff — a changed fixture IS the wire change. |
 | `make bench` (local) | Diff touches request-path code, allocator wiring, or startup/shutdown sequencing. |
 | `API_BENCH_URL=https://api-dev.agentsfleet.net/healthz make bench` | After branch deploys to dev. |
 | `/orly-write-integration-test` (skill) | With `/orly-write-unit-test` at VERIFY when the diff crosses module boundaries with real I/O; otherwise record `N/A — <reason>`. |
 | Acceptance e2e (live tier) | Diff touches a surface the live/acceptance tier covers — relevant suites green, or their opt-in skip matrix recorded. |
 
-There is no slow tier. The Zig integration and memory-leak lanes retired with the
-rest of the Zig gating, so nothing a developer runs needs live Postgres or Redis.
-A package-scoped runner (`cargo test -p afd_wire`, `bun run test` inside a
-package) proves that package and never the repository.
+The declared set in `.oracle/orly.json` is the source of truth for what exists,
+and a lane listed there is a lane that runs at the boundary — including the slow
+tier. A package-scoped runner (`cargo test -p afd_wire`, `bun run test` inside a
+package) proves that package and never the repository, at either cadence.
 
 ## Wire-fixture evidence rule
 
@@ -70,10 +98,16 @@ generated output; a type change with no fixture diff means the emitter never ran
 
 ## Required output (done-message)
 
-**Success:**
+**Success (boundary):**
 
 ```
-✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🔆 harness-verify ✓ · 🔆 check-version ✓
+✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🧩 test-integration-rustd ✓ · 🔆 harness-verify ✓ · 🔆 check-version ✓
+```
+
+**Success (Section lane)** — names the lane it ran, never the repository:
+
+```
+✅ Section verified: 🔆 harness-verify ✓ · 🧪 test-unit-<surface> ✓ <N>p/<M>s
 ```
 
 **Failure (any required target failed):**

package/dispatch/write_any.md

@@ -127,7 +127,7 @@ shebang and is the authoritative check.
 **Triggers** — every `Edit`/`Write` that adds, removes, or changes a log emit:
 
 - `*.zig` outside `vendor/`/`third_party/`/`.zig-cache/`/`*_test.zig` — `std.log.*`, `std.debug.print`, raw stderr writes, calls into the `log` named module (source: `src/logging/mod.zig`).
-- `*.rs` under `rustd/` outside `tests/`, `benches/`, and `#[cfg(test)]` items — `tracing::*`, `println!`, `eprintln!`, and `dbg!`.
+- Every tracked or unignored `*.rs` outside `build.rs`, `examples/`, `tests/`, `benches/`, and `#[cfg(test)]` items — `tracing::*`, `println!`, `eprintln!`, and `dbg!`.
 - `*.ts`/`*.tsx`/`*.js`/`*.jsx` outside `vendor/`/`node_modules/`/`*.test.*`/`*.spec.*` — `console.*`, custom logger calls.
 - `*.sh` outside generated dirs — `echo`/`printf` to `&2`.
 
@@ -150,7 +150,8 @@ shebang and is the authoritative check.
 | New `err`/`warn` log mapping to a domain failure | registry-scheme `error_code=` field required (agentsfleet: `UZ-XXX-NNN`). Registry entry must land in same commit. |
 | Per-iteration / hot-loop log | Use `debug` (hidden by default), not `info`. |
 | `info` level | No allow-list — `info` is open (§4 rule 2). Two checks instead: a boundary-crossing operation needs its `_started`/`_completed`\|`_failed` pair on every exit path (rule 1), and a per-iteration path is `debug` (rule 3). Hot-poll boundary pairs remain complete but use `debug`. |
-| `console.log`/`std.debug.print`/Rust print macro in non-test source | Forbidden. Convert to the structured logger or delete before commit. |
+| `console.log` in non-test source | Forbidden. Convert to the structured logger or delete before commit. |
+| `std.debug.print` or a Rust print macro in runtime source | Convert to structured logging. When the stream output is the program interface, add `// logging: <reason>` on or immediately above the emit. The reason is mandatory. |
 | `std.log.scoped` outside `src/logging/` | Migration target. The `log` named module's `scoped` API is the only non-test entry point; flip the file's alias and migrate every call site in the same commit. |
 | `msg=` field | ≤ 300 chars. Stack traces emit as separate `event=stack_trace` debug record. |
 | Multi-line values | Newlines must be `\n` literal (two chars), not raw newline byte. |
@@ -190,13 +191,13 @@ LOGGING GATE: <file>
 
 > [DETERMINISTIC → LOG]
 
-`logging.sh` walks the **full `src/` + `rustd/` + `agentsfleet/src/` working tree**. The staged mode reads the index, 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.
+`logging.sh` walks `src/**/*.zig`, every tracked or unignored `*.rs`, and `agentsfleet/src/**/*.{js,jsx,ts,tsx}`. Rust repositories do not need to use a fixed source-root name. The staged mode reads the index, 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 development.
 
 #### End-of-turn audit
 
 > [DETERMINISTIC → LOG]
 
-`audits/logging.sh` runs as part of `make lint`. It greps `std.log.*`, Rust `tracing` and direct-print macros, `console.*`, and raw stderr writes. It does NOT see calls through the Zig `log` named module's `scoped()`, so a clean run is not evidence that §4/§5 hold everywhere. Mechanical today: direct Zig/Rust/TypeScript diagnostics, Rust's required `event` field and positional-format ban, `std.log.scoped` outside `src/lib/logging/`, and legacy Zig error-code hints. Reviewer-side: severity choice, entry/exit pairing, registry applicability, inline Rust expression hoisting, and Personally Identifiable Information (PII) spot-checks.
+`audits/logging.sh` runs as part of `make lint`. It greps `std.log.*`, Rust `tracing` and direct-print macros, `console.*`, and raw stderr writes. It accepts a direct Zig or Rust stream write only when `// logging: <reason>` appears on or immediately above the emit with a non-empty reason. It does NOT see calls through the Zig `log` named module's `scoped()`, so a clean run is not evidence that §4/§5 hold everywhere. Mechanical today: direct Zig/Rust/TypeScript diagnostics, Rust's required `event` field and positional-format ban, `std.log.scoped` outside `src/lib/logging/`, and legacy Zig error-code hints. Reviewer-side: reason validity, severity choice, entry/exit pairing, registry applicability, inline Rust expression hoisting, and Personally Identifiable Information (PII) spot-checks.
 
 #### Family
 

package/dispatch/write_go.md

@@ -22,5 +22,13 @@ a working value.
 Table-driven tests are the default shape. Concurrency work needs a `-race` run,
 and a deterministic contention test rather than a sleep.
 
+A string literal repeated in one file becomes a named constant — `audits/ufs.sh`
+reads `*.go` and enforces it. Two Go shapes are held out, because no rename can
+fix them: members of a `const ( … )` group, which state the binding keyword once
+on the opening line rather than per member, and backtick struct tags, whose
+quoted halves (`json:"id"`) are addressed by reflection and cannot hold a const.
+Both are carve-outs for what the *language* makes unfixable, not permission —
+a flag name or a label spelled inline twice is still the rule.
+
 The repository owns formatting, vet, lint, build, and test commands — it
 declares them in `.oracle/orly.json`.

package/dispatch/write_rust.md

@@ -33,6 +33,172 @@ Local convention wins on conflict, but the divergence is named in the review
 output. Refresh the copy when the user asks or a cited rule looks stale
 (re-run the fetch; upstream updates continuously).
 
+## Error discipline (RULE ERR-RS)
+
+> [DETERMINISTIC → ERR-RS]
+
+Two of the clauses below are decided by `audits/rust-error.sh`, which
+`dispatch/write_rust.sh` runs over staged Rust: an error type with no `Result`
+alias in its crate, and a `map_err` that stringifies its own cause. The other
+two — whether a `source()` implementation returns its own kind, and whether a
+context addition is warranted — need the call site read beside the diff and stay
+the agent's call at write time.
+
+One error type per crate, and a `Result` alias beside it:
+
+    pub type Result<T, E = Error> = core::result::Result<T, E>;
+
+Every fallible function in the crate returns `Result<T>`. The default type
+parameter is what lets the few functions answering with a foreign error keep
+the same spelling — `Result<T, VerifyError>` — instead of reaching for
+`std::result::Result`. A reader must never have to check WHICH error a
+signature returns to know it is this crate's.
+
+**Compose with `From`; `?` does the lifting.** This is `M-FROM-ERROR` and is
+read there, carve-out included; what the guideline leaves open is how the
+variant is spelled, which locally is `#[from]`:
+
+    #[derive(Debug, thiserror::Error)]
+    pub enum BootFailure {
+        #[error(transparent)]
+        Environment(#[from] Refusal),
+        #[error("cannot boot: the database would not answer")]
+        Database(#[from] db::Error),
+    }
+
+**`map_err` only to ADD context the call site alone knows** — a role tag, a
+budget, an operation name; the same carve-out `M-FROM-ERROR` names. And never
+this, which no guideline covers:
+
+    // WRONG: a lossy conversion wearing a conversion's clothes.
+    .map_err(|error| Mine::Database(error.to_string()))?
+
+`to_string()` on the way INTO an error type destroys the `source()` chain. It
+compiles, it reads fine, and it silently defeats every chain walker downstream.
+
+**`source()` returns what caused you, never yourself.** An error whose
+`Display` already renders its kind must not also return that kind as its
+source, or a chain walker prints the same sentence twice before reaching
+anything new:
+
+    // WRONG — Display is "[code] {kind}", so the kind is already printed.
+    fn source(&self) -> Option<&(dyn Error + 'static)> { Some(&self.kind) }
+
+    // RIGHT — skip ourselves, hand back what the kind wraps.
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        std::error::Error::source(&self.kind)
+    }
+
+**Not every error has a cause, and that is not a defect.** A variant holding
+another error has one; a variant holding only data (`MissingUrl { knob }`) does
+not — nothing *caused* an unset variable. A test asserting `source().is_some()`
+for every variant is WRONG and forces authors to invent causes. Assert the real
+invariant: where there IS a source, it is not a repeat of our own message.
+
+**Divergence from the reference guideline, named as that section requires.**
+`M-ERRORS-CANONICAL-STRUCTS` prescribes a situation-specific `struct` carrying
+a `Backtrace` and lets a complex crate expose several error types;
+`M-APP-ERROR` further lets an application crate skip its own type for
+`anyhow`/`eyre`/`ohno::AppError`. This rule diverges on all three for one
+reason: a `#[from]`-composed enum behind a single per-crate alias is what lets
+`?` lift across a crate boundary with no call-site conversion, and an
+application-level catch-all erases the variant the caller would have matched
+on. A `Backtrace` inside a variant is welcome. A crate with two genuinely
+unrelated fallible surfaces may carry a second type — with its own alias, under
+these same rules. Cite this divergence in review rather than re-deriving it.
+
+Prior art, not invention: `core_api` (multi-crate workspace, per-crate
+`error.rs` with `pub type Result<T>` + flat `Error`, in production for years),
+bun (`thiserror`, `#[from]`, `pub type Result<T, E = Error>`), habitat (one
+payload-carrying `enum Error`, one alias).
+
+## Functional design (RULE FN-RS)
+
+Design the fallible path as a Result PIPELINE, never as a control-flow tree.
+
+**Fallibility lives in the type, never in a sentinel.** A function that can
+fail returns `Result<T>`; a value that can be absent returns `Option<T>`.
+Never a bool-plus-out-parameter, never a magic value (-1, empty string, null
+UUID), never a logged-and-swallowed error. If the caller cannot see the
+failure in the signature, the design is wrong before the body is written.
+
+**Compose with combinators; spend `match` only where arms genuinely differ.**
+`?`, `map`, `and_then`, `ok_or_else`, `unwrap_or_else` say "transform on
+success, pass failure through" in one line, where a nested match spends five
+and gives every arm a chance to swallow the `Err`:
+
+    // WRONG: the failure path is hand-plumbed, twice.
+    let config = match load(path) {
+        Ok(raw) => match parse(&raw) {
+            Ok(c) => c,
+            Err(e) => return Err(e.into()),
+        },
+        Err(e) => return Err(e.into()),
+    };
+
+    // RIGHT: one pipeline; `?` and `From` (RULE ERR-RS) do the lifting.
+    let config = parse(&load(path)?)?;
+
+A `match` earns its place when the arms carry different LOGIC — not when one
+arm is a hand-written `?`.
+
+**Make illegal states unrepresentable; parse, don't validate.** Convert raw
+input into a type that can only hold valid states ONCE, at the boundary, and
+pass that type inward. Two `Option` fields where exactly one is ever set is an
+enum. A `state: String` compared against literals is an enum. A checked-then-
+used raw value is a newtype whose constructor returns `Result` — that
+constructor is `M-STRONG-TYPES-GUARD`, and picking the type family is
+`M-STRONG-TYPES`. What those do not say is the consequence: interior code that
+trusts its types needs no defensive re-checks — delete them.
+
+**Expression-orientation: bind once.** `let x = if ... { a } else { b };` and
+`let x = match ...` — never a mutable default that later branches overwrite.
+A `mut` that exists only to simulate an expression is a bug surface with no
+compensating power.
+
+**`unwrap()` / `expect()` are for tests and for invariants already proved.**
+`M-PANIC-ON-BUG` settles when a panic is right and `M-PANIC-MESSAGE` that it
+must be helpful; the addition here is WHAT the message carries — the proof
+("mutex never poisoned: no thread panics while holding it"). In production
+code, an `unwrap()` without a written invariant is a `Result` that was never
+designed.
+
+Prior art, not invention: `core_api` — a multi-crate production workspace
+where every crate with a fallible surface carries its own `error.rs` +
+`Result` alias, and the fallible path is written as pipelines throughout
+(573 `.map`, 463 `.and_then`, 164 `.ok_or_else` across the workspace). It has
+run in production for years; its author attributes the absence of error-path
+defects to exactly this design, and the maintenance record bears that out.
+
+## Constant discipline (RULE UFS)
+
+`audits/ufs.sh` reads `*.rs`. It did not until this pack said so, and the cost
+was concrete: a crate spelled a wire verb inline twice — `pong == "PONG" ||
+pong.contains("PONG")` — while `write_any.sh` printed a green UFS row over the
+file, because the façade had always declared `*.rs` and the leaf had never read
+it. Bind the repeated literal to a `const` or `static` and use the name.
+
+Four Rust shapes are held out of the count, because no rename can fix them:
+
+- **`#[cfg(test)]` and `#[test]` blocks.** Rust keeps unit tests inside the file
+  they cover, so fixture keys would otherwise read as that file's worst debt.
+- **Feature-gated test seams** — `#[cfg(feature = "test-util")]`. A helper that
+  hands a sibling integration test one of each error kind has to compile into
+  the crate, which is the only reason it is not behind `cfg(test)`; its contents
+  are fixture data all the same. The match is narrow on purpose: `test` as a
+  whole word or a `-`/`_` segment, so `#[cfg(feature = "redis")]` still counts.
+- **Attribute literals** — `#[serde(rename = "…")]`, `#[cfg(feature = "…")]`,
+  `#[doc = "…"]`. An attribute takes a literal token by language rule; a const
+  is not accepted in that position.
+- **`tests/` and `benches/`** at the crate root, which are fixture trees.
+
+Everything else counts, including `examples/` — not because it compiles, but
+because what repeats there is coupling, not demonstration. A cache namespace
+declared at the top of a walkthrough and matched ninety lines below it, or a
+fixture id that is both the fake store's match arm and the key five call sites
+pass, breaks silently when one end moves. That is the drift RULE UFS exists to
+catch, and example code is where a reader copies it from.
+
 ## Evolution
 
 This pack is young next to the Zig façade and grows the same way: a Rust

package/dispatch/write_rust.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# dispatch/write_rust.sh — the Rust dispatch, DETERMINISTIC façade.
+#
+# Pairs with dispatch/write_rust.md (the LATENT façade — prose the agent reads).
+# This .sh runs the mechanically-checkable subset of the Rust discipline and
+# emits ONE verdict block. The latent trigger ("about to write a *.rs file")
+# dispatches here; everything below is deterministic and re-runnable.
+#
+#   dispatch/write_rust.sh <src/file.rs> [...]   # explicit targets (EXECUTE)
+#   dispatch/write_rust.sh --staged              # staged *.rs (CONFORM, pre-commit)
+#
+# Layering:  AGENTS.md → write_rust.md (latent) → write_rust.sh (this) → audits/*.sh
+# Signals:   🟢 pass · 🔴 fail (blocks) · 🤔 DECIDE (judgment; blocks the TURN, not the script) · 🟣 delegated
+# Exit:      0 = mechanical gates pass · 1 = ≥1 failed · 2 = usage error.
+#
+# Note: Rust had no deterministic façade at all until this file, which is why
+# the error standard the operating model calls mandatory was enforced by review
+# alone. ERR-RS carries the two clauses a machine can decide from the text — a
+# map_err that stringifies its own cause, and an error type with no Result alias
+# beside it. The rest of write_rust.md stays judgment on purpose: ownership,
+# justified `unsafe`, feature combinations, and whether a source() implementation
+# returns its own kind all need a call site read beside the diff, and a gate that
+# guesses at those is a gate people learn to ignore.
+#
+# UFS over *.rs is NOT re-run here. It is wired once in its home façade
+# (write_any), and the universal-code carve-out makes that row satisfy the tag
+# wherever it appears — running it twice would report one violation as two.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+dispatch_init "RUST" '*.rs'
+dispatch_resolve_files "$@"
+dispatch_header
+
+# ── deterministic gates ────────────────────────────────────────────
+dispatch_run_helper "ERR-RS" rust-error.sh --staged
+
+dispatch_verdict

package/docs/EXECUTE_DOC_READS.md

@@ -15,7 +15,7 @@ Every triggered document requires one `📖 DOC READ: <path>` proof-line **per t
 | `*.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. |
 | `*.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. | <!-- 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. |

package/docs/LOGGING_STANDARD.md

@@ -250,7 +250,7 @@ The `comptime if ... return` makes the entire emit path disappear when the scope
 | Pattern | Why banned | Fix |
 |---|---|---|
 | `std.log.info("..."` outside `logging.scoped(.tag)` | Bypasses scope/event/field discipline. | Convert to `logging.scoped(.tag).info("event", .{...})`. |
-| `std.debug.print(` in non-test source | No level, no scope, no field structure. Dev-only debugging that escaped to main. | Convert or delete before commit. |
+| `std.debug.print(` in non-test source | No level, no scope, no field structure. Dev-only debugging that escaped to main. | Convert or delete. If stdout or stderr is the program interface, add `// logging: <reason>` on or immediately above the emit. |
 | `std.log.err` without `error_code=` field | Drops registry traceability. | Add the registry code, or add a registry entry if missing. |
 | `std.log.scoped(...)` outside `src/lib/logging/` | Free-form printf-style emit. | Switch the file's alias to `const log = logging.scoped(.tag);` and migrate every call site to the event+fields form. |
 | Positional `{s} {d}` placeholders | Not logfmt; not greppable. | Convert to struct-of-fields. |
@@ -295,7 +295,7 @@ class AgentError extends Error {
 
 Throw-style modules `throw new AgentError({...})`. Result-style modules return `{ ok: false, error: new AgentError({...}) }`. Render path picks human or JSON based on the runtime mode.
 
-## §8A · Per-language binding — Rust (`rustd`)
+## §8A · Per-language binding — Rust
 
 > [DETERMINISTIC → LOG]
 
@@ -333,10 +333,20 @@ match. Renaming is a separate, intentional observability migration.
 
 | Pattern | Why banned | Fix |
 |---|---|---|
-| `println!`, `eprintln!`, or `dbg!` in non-test source | No level, event, or structured fields. | Convert to a `tracing` emit or delete. |
+| `println!`, `eprintln!`, or `dbg!` in runtime source | No level, event, or structured fields. | Convert to a `tracing` emit or delete. If the stream is the program interface, add `// logging: <reason>` on or immediately above the emit. |
 | `tracing::<level>!` without `event = ...` | Drops the stable §3 event key. | Add the byte-stable snake_case event field. |
 | Positional formatting in a `tracing` message | Hides values inside text and defeats field queries. | Hoist values and emit named fields. |
 
+The annotation reason is mandatory and must be non-empty. A bare `// logging:`
+marker still fails. The annotation is for direct program output, such as a
+command result or a fatal renderer that must work before tracing starts. It does
+not excuse an incomplete `tracing` emit.
+
+```rust
+// logging: stdout is this command's answer, not a log record
+println!("{}", rendered_summary);
+```
+
 ## §9 · Pretty-printer (dev-only render variant)
 
 In production: every record on the wire is logfmt. No exceptions.
@@ -379,7 +389,7 @@ Failure modes the audit script and reviewer must close. These are **not aspirati
 
 | # | Rationalization | Closure |
 |---|---|---|
-| L1 | "Temporary debug print, I'll remove later" | `logging.sh` greps `std.debug.print`, Rust `println!` / `eprintln!` / `dbg!`, and `console.log` / `console.debug` / `console.info` in non-test source unconditionally. Found in commit → gate fails. No "temporary" carve-out. |
+| L1 | "Temporary debug print, I'll remove later" | `logging.sh` rejects `std.debug.print`, Rust `println!` / `eprintln!` / `dbg!`, and `console.log` / `console.debug` / `console.info` in runtime source. Direct Zig or Rust stream output needs `// logging: <reason>` on or immediately above the emit. The reason must be non-empty and explain why the stream is the program interface. |
 | L2 | "`std.log.scoped` is fine, `obs.scoped` is just a wrapper" | `std.log.scoped` is **forbidden** in `src/**/*.zig` outside `src/lib/logging/`. Only `obs.scoped` is callable. Audit flags every `std.log.` call site. |
 | L3 | "I added `error_code=UZ-NEW-001` — registry entry coming next commit" | The registry entry **must land in the same commit** as the first reference. `error-codes.sh` runs against the staged diff; missing entry = blocking. |
 | L4 | "This per-iteration event matters for debugging — `info`-level" | Per-iteration and per-row paths are `debug`, including mandatory boundary pairs on hot polls. `debug` is the level with a volume switch. This closes the ONLY `info` prohibition — there is no allow-list of event names and none may be reintroduced (§4). The inverse rationalization is closed too: "this operation is obviously fine, no need to log it" does not survive §4 rule 1, which requires a `_started`/`_completed`\|`_failed` pair on every boundary-crossing operation. Reviewer checks the pair and the loop, never the spelling. |

package/docs/RULE_ENFORCEMENT.md

@@ -6,15 +6,15 @@ regenerates this file and fails on any difference. To update it, run
 
 | Rule document | enforced by | judged | acknowledged | classified | trigger |
 |---|---|--:|--:|--:|---|
-| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 11 | 13 | 28/28 | mechanical |
+| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 11 | 13 | 30/30 | mechanical |
 | `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/74 | mechanical |
 | `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
 | `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/22 | latent |
 | `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
 | `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
-| `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/4 | uncited |
+| `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/7 | uncited |
 | `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
-| **corpus** | | | | **28/283** | |
+| **corpus** | | | | **30/288** | |
 
 ## How to read this
 

package/docs/VERIFY_TIERS.md

@@ -8,16 +8,33 @@ page carries only what is specific to this repository.
 
 | Tier | Command | When |
 |---|---|---|
-| conform | `make harness-verify` | Always, after EXECUTE and before the rest. Any 🔴 returns to EXECUTE. |
-| lint | `make lint-all` | Always. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors); script self-tests ride `lint-scripts`. |
-| unit | `make test-unit-all` | Always. The cargo workspace plus every TypeScript package coverage gate. |
-| version | `make check-version` | Always. `VERSION` against `build.zig.zon`, `cli/package.json` and both `rustd/Cargo.toml` sites. |
-
-These four are exactly what `.oracle/orly.json` declares and exactly what
-`orly gate` runs, so the rubric and the mechanical gate grade one boundary.
-
-There is no slow tier. The Zig integration and memory-leak lanes retired with the
-rest of the Zig gating, so no lane a developer runs needs live Postgres or Redis.
+| conform | `make harness-verify` | Section lane and boundary, after EXECUTE and before the rest. Any 🔴 returns to EXECUTE. |
+| lint | `make lint-all` | Boundary. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors); script self-tests ride `lint-scripts`. |
+| unit | `make test-unit-all` | Boundary. The cargo workspace plus every TypeScript package coverage gate. |
+| version | `make check-version` | Boundary. `VERSION` against `build.zig.zon`, `cli/package.json` and both `rustd/Cargo.toml` sites. |
+| integration | `make test-integration-rustd` | Boundary. Live Postgres and Redis via docker compose, schemas reset per run. `orly gate pr` skips it on a branch carrying no code. |
+
+These five are exactly what `.oracle/orly.json` declares and exactly what
+`orly gate pr` runs, so the rubric and the mechanical gate grade one boundary.
+
+**Two cadences.** A Section closing is not a milestone closing. Inside a
+Section, run `make harness-verify` plus the lane covering the surface the
+Section touched (`make test-unit-rustd`, `make test-unit-app`, …) — enough to
+prove the Section, never a repository claim. The full table above runs ONCE, at
+CHORE(close).
+
+**Which gate runs which row.** `orly gate work` runs the `conform` row alone and
+is what the pre-commit hook fires, so it costs seconds. `orly gate verify` runs
+the lint, unit, and version rows and is what pre-push fires. `orly gate pr` runs
+the integration row plus the whole-branch and spec criteria, and is what
+CHORE(close) fires — it skips the fast rows because `git.pushed` proves HEAD is
+the commit pre-push already graded.
+
+One lane needs live datastores, and only one. `make/test-infra.mk` brings up
+docker compose Postgres and Redis for `test-integration-rustd`; `make
+test-unit-all` stays datastore-free, because every Rust test needing one is
+`#[ignore]`d and runs only in that lane. `KEEP_TEST_STATE=1` skips the reset for
+the inner loop; Continuous Integration (CI) never sets it.
 
 ## Test Baseline
 
@@ -61,7 +78,14 @@ Paste the deciding line, not the exit code. A gate that reports a number — a s
 against a cap, a count against a budget — is owed that number in the done message.
 
 ```
-✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🔆 harness-verify ✓ · 🔆 check-version ✓
+✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🧩 test-integration-rustd ✓ · 🔆 harness-verify ✓ · 🔆 check-version ✓
+```
+
+A Section lane reports what it ran and says so, never borrowing the repository's
+verdict:
+
+```
+✅ Section verified: 🔆 harness-verify ✓ · 🧪 test-unit-<surface> ✓ <N>p/<M>s
 ```
 
 A skipped target is surfaced as 🟠 with its reason, never dressed as a pass.

package/docs/greptile-learnings/RULES.md

@@ -51,6 +51,7 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 | LOG | LOGging discipline (scoped event, error_code, severity, redaction) |
 | MSID | Milestone-ID ban in source (M{N}_{NNN} / §x.y / T{N} / dim) |
 | ERR | ERror Registry (UZ-XXX-NNN declared + referenced) |
+| ERR-RS | Rust ERror discipline (one type per crate, Result alias, no stringified cause) |
 | GRP | GREptile rule audit (diff vs greptile-learnings/RULES.md codes) |
 | LDC | Legacy-Design Consult (A remove / B patch / C keep) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",

package/packs/language/rust/rules.md

@@ -35,6 +35,15 @@ output. Refresh the copy when the user asks or a cited rule looks stale
 
 ## Error discipline (RULE ERR-RS)
 
+> [DETERMINISTIC → ERR-RS]
+
+Two of the clauses below are decided by `audits/rust-error.sh`, which
+`dispatch/write_rust.sh` runs over staged Rust: an error type with no `Result`
+alias in its crate, and a `map_err` that stringifies its own cause. The other
+two — whether a `source()` implementation returns its own kind, and whether a
+context addition is warranted — need the call site read beside the diff and stay
+the agent's call at write time.
+
 One error type per crate, and a `Result` alias beside it:
 
     pub type Result<T, E = Error> = core::result::Result<T, E>;