@agentsfleet/orly 0.6.8 → 0.7.0

package/docs/LOGGING_STANDARD.md

@@ -1,6 +1,6 @@
 # LOGGING_STANDARD — wire format and discipline for structured logs
 
-The contract between code that emits log records and the systems (humans, collectors, dashboards) that consume them. Cross-language: applies to every Zig, TypeScript, JavaScript, and shell call site that emits to `stderr`/`stdout`.
+The contract between code that emits log records and the systems (humans, collectors, dashboards) that consume them. Cross-language: applies to every Zig, Rust, TypeScript, JavaScript, and shell call site that emits to `stderr`/`stdout`.
 
 Pre-design rules, decisive defaults, and the anti-patterns each rule exists to prevent. Every rule has a one-line "why" so you can judge edge cases.
 
@@ -9,12 +9,13 @@ Pre-design rules, decisive defaults, and the anti-patterns each rule exists to p
 Triggers on every `Edit`/`Write` that adds, removes, or changes a log emit:
 
 - `*.zig` outside `vendor/`/`third_party/`/`.zig-cache/` — `std.log.*`, `std.debug.print`, `std.io.getStdErr().writer().print`, any helper in `src/lib/logging/`.
+- `*.rs` under `rustd/` outside test and benchmark scopes — `tracing::{error,warn,info,debug,trace}!`, `println!`, `eprintln!`, and `dbg!`.
 - `*.ts`/`*.tsx`/`*.js`/`*.jsx` outside `vendor/`/`node_modules/` — `console.*`, custom logger calls.
 - `*.sh` outside generated directories — `echo`, `printf` to `&2`.
 
 Out of scope (explicitly):
 
-- Test-only diagnostic prints inside `*_test.zig`, `*.test.ts`, `*.spec.ts`. Tests render to humans, not collectors; gates ignore.
+- Test-only diagnostic prints inside `*_test.zig`, Rust `tests/` and `benches/` trees or `#[cfg(test)]` items, `*.test.ts`, and `*.spec.ts`. Tests render to humans, not collectors; gates ignore.
 - Build/release scripts — the harness's own `audits/*`, `audits/release-*`, and any governance-repo tooling — toolchain output, not application logs.
 - Generated framework noise (Next.js startup banners, Bun runtime warnings) — out of our control.
 
@@ -123,6 +124,12 @@ a per-chunk callback: these flood collectors and drown the records that matter.
 `debug` is not a lesser level, it is the level with a volume switch. A sweep that
 reaps 4,000 workspaces logs each one at `debug` and its outcome at `info`.
 
+Boundary pairing and per-iteration severity both apply to hot polls. A lease poll
+that crosses Redis and Postgres on every iteration still emits its complete
+`_started` and `_completed`/`_failed` pair, but emits both records at `debug`.
+The pair satisfies rule 1; the level satisfies rule 3. A coarser poll-loop start,
+stop, or aggregate outcome may remain `info`.
+
 ### `err` and `warn` are unconditional
 
 > [UNENFORCED → "always emitted" is a runtime filter-configuration property; nothing greps for a suppressed err/warn path]
@@ -288,6 +295,48 @@ 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`)
+
+> [DETERMINISTIC → LOG]
+
+Rust uses the existing `tracing` crate and emits the same logical fields as §3.
+Every production emit supplies an `event` field, explicitly or through tracing's
+field shorthand, whose value is a snake_case `verb_noun`. Fields are structured
+arguments, never positional message formatting.
+
+> [JUDGMENT → RUST-STYLE]
+
+Every `warn` or `error` that maps to a registry code supplies
+`error_code = code` per §5. Hoist field expressions into locals before the macro
+call. The log bridge duplicates field expressions, and LLVM coverage
+instrumentation scores the dead copy; locals preserve evaluation and coverage
+behavior. A trailing string message is §3's optional `msg` and is always the
+last macro argument. Prefer fields alone when they already explain the event.
+
+```rust
+let code = error_code::INTERNAL_DB_QUERY.as_str();
+let id = runner.as_str();
+let reason = error.to_string();
+let event = "runner_lease_failed";
+tracing::warn!(error_code = code, runner_id = id, reason, event);
+```
+
+> [JUDGMENT → EVENT-COMPAT]
+
+Ports preserve existing event-name bytes by default. A Rust replacement for a
+Zig operation keeps the Zig event spelling so dashboards and alerts continue to
+match. Renaming is a separate, intentional observability migration.
+
+> [DETERMINISTIC → LOG]
+
+**Anti-patterns flagged by `logging.sh`:**
+
+| 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. |
+| `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. |
+
 ## §9 · Pretty-printer (dev-only render variant)
 
 In production: every record on the wire is logfmt. No exceptions.
@@ -330,10 +379,10 @@ 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` 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` 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. |
 | 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`, no exception: a loop body is not a boundary, and `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. |
+| 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. |
 | L5 | "Operator needs the full stack trace in `msg=`" | `msg=` capped at 300 chars; total fields per record capped at 15. Stack traces emit as a separate `event=stack_trace` record at `debug` level, correlated by `correlation_id`, not stuffed into `msg`. |
 | L6 | "Embedded newlines because I copy-pasted output" | Audit greps for raw newline byte inside quoted logfmt values. Must be `\n` literal (two chars). |
 | L7 | "Auto-mode is on, the gate block is ceremony" | **Auto-mode does NOT cover gate skips.** Skip without an explicit user-given override = automatic violation. No size threshold lets an edit bypass the gate. |
@@ -348,6 +397,9 @@ These are enforced by `logging.sh` (mechanical) and the dispatch façade (`dispa
 |---|---|
 | Free-form English log lines | Not greppable, not parseable, no event tag. |
 | `std.debug.print` outside tests | No level, no scope, no fields — dev debugging that escaped to main. |
+| Rust `println!`, `eprintln!`, or `dbg!` outside tests | No level, event, or structured fields — dev diagnostics that escaped to main. |
+| Rust `tracing` emit without `event` | Drops the stable event key required by §3. |
+| Positional formatting in a Rust `tracing` emit | Values become opaque message text instead of queryable fields. |
 | `console.log` in `agentsfleet` source | Bypasses logger, breaks `--json` mode, violates `dispatch/write_ts_adhere_bun.md` §10. |
 | Logging on hot per-iteration paths at `info` | Floods collectors. Use `debug` (gated off by default). |
 | `error_code=` missing on `err`/`warn` mapping to registry codes | Breaks traceability; future operator can't link log to docs. |
@@ -371,6 +423,7 @@ immediately preceding the edit. Generic "scope creep" is not a valid reason —
 - `dispatch/write_ts_adhere_bun.md` §10 — banned `console.log` in TS/JS source. Cross-referenced by `logging.sh`.
 - `dispatch/write_ts_adhere_bun.md` §9 — module-level error style (throw vs Result) for `agentsfleet`.
 - `dispatch/write_zig.md` — Zig discipline umbrella; this doc's §7 is the logging-specific layer.
+- `dispatch/write_rust.md` — Rust discipline umbrella; this doc's §8A is the logging-specific layer.
 - `LIFECYCLE_PATTERNS.md` — orthogonal: ownership/cleanup of structs, including allocator wiring for the thread-local log buffer.
 - M42_002 redaction harness (`src/runner/engine/runner_progress.zig`) — secret-redaction precondition; this doc's §6 inherits.
 - Universal rules (RULE UFS, RULE TGU, RULE PRI, RULE FLL, RULE ORP, RULE TST-NAM) live in `docs/greptile-learnings/RULES.md`.
@@ -388,10 +441,12 @@ its line covers the clauses under it until the next heading.
 
 | Tag | Meaning | Where the verdict comes from |
 |---|---|---|
-| `[DETERMINISTIC → LOG]` | a script decides; no talking past it | `audits/logging.sh` — `std.debug.print` and `console.*` in non-test source block; missing `error_code=` on `std.log.{err,warn}` reports as INFO |
+| `[DETERMINISTIC → LOG]` | a script decides; no talking past it | `audits/logging.sh` — direct Zig/Rust/TypeScript diagnostics and malformed Rust tracing emits in non-test source block; missing `error_code=` on `std.log.{err,warn}` reports as INFO |
 | `[JUDGMENT → BOUNDARY]` | is this operation boundary-crossing, and is its `_started`/`_completed`\|`_failed` pair complete | the agent at write time; the reviewer at `/review` |
 | `[JUDGMENT → REDACT]` | is this value a secret, or the label of one | the agent at write time; the M42_002 harness covers only executor-child output |
 | `[JUDGMENT → MSG-REVIEW]` | does this `msg=` carry a credential | the reviewer; no length or content check runs today |
 | `[JUDGMENT → TS-STYLE]` | throw-style or Result-style for this module | `dispatch/write_ts_adhere_bun.md` §9, agent-decided |
+| `[JUDGMENT → RUST-STYLE]` | does a Rust failure map to a registry code, and are field expressions safely hoisted | the agent at write time; the reviewer at `/review` |
+| `[JUDGMENT → EVENT-COMPAT]` | does a language port preserve the event bytes consumed by existing dashboards | the agent compares old and new event constants; the reviewer confirms intentional renames |
 | `[JUDGMENT → SECTION-SCAN]` | which sections of this file the current sub-task needs | the agent; `audits/doc-read.sh` records façade reads, not delegated-doc reads |
 | `[UNENFORCED → reason]` | acknowledged prose; the reason states why no check exists | nothing — that is the point of the class |

package/docs/ORLY_ARCHITECTURE.md

@@ -122,6 +122,25 @@ surfaces:
 
 Orly owns policy and invokes these commands. The repository owns what they do.
 
+## Usage telemetry
+
+Orly keeps usage telemetry off until a person enables anonymous collection in
+an interactive run. Hooks, Continuous Integration (CI), and other automated
+runs never ask for consent. Off writes no event and makes no network request.
+
+Anonymous events enter a bounded outbound spool under the agentsfleet state
+root. After each append, Orly launches a detached sync attempt and lets the
+command exit. The sync sends at most 100 events and exits without a fetch when
+another attempt ran within five minutes. A successful response removes the
+acknowledged prefix. Spool maintenance drops records older than seven days and
+keeps the file at or below 10 MiB, so an unavailable destination cannot create
+an unbounded local log. Orly runs no telemetry daemon.
+
+PostHog owns product-event storage and funnel analysis. Orly sends no source,
+path, repository, branch, argument, output, environment, hostname, username, or
+raw error value. A future Insights Fleet may query PostHog with a private key;
+the Fleet is an analysis consumer and never the public ingestion boundary.
+
 ## Evidence
 
 `orly verify --all --write-evidence` records the source commit and every check

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` | 10 | 13 | 26/26 | mechanical |
+| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 11 | 13 | 28/28 | 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/greptile-learnings/RULES.md` | — | 0 | 0 | 0/113 | mechanical |
-| **corpus** | | | | **26/280** | |
+| `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
+| **corpus** | | | | **28/283** | |
 
 ## How to read this
 

package/docs/greptile-learnings/RULES.md

@@ -179,6 +179,13 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 **Tags:** zig, testing, sql
 **Example:** tested 0 for a column with CHECK >= 512.
 
+## RULE TCF — A test that cannot fail is not a test
+
+**Rule:** Before trusting a test, make it red — delete the clause, guard, or branch it covers and confirm it fails. Assert what the check FOUND (the count, the symbol, the line), never only its exit code. A test that survives removal of its own subject is repaired or deleted, never kept for coverage.
+**Why:** A vacuous pass and a real pass look identical from the outside, so the suite reports green while the guarantee is already gone.
+**Tags:** testing, review, all
+**Example:** a tenant-scope property asserted absence only and passed with the scope clause deleted; a dispatch eval asserted an exit code while its glob pointed at a dead tree.
+
 ## RULE JCL — CLI JSON contract discipline
 
 **Rule:** Use only stable error codes; UNKNOWN_COMMAND must name the unrecognized token; dual jsonMode guards need a comment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.6.8",
+  "version": "0.7.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/go/rules.md

@@ -1,5 +1,7 @@
 # Go authoring
 
+<!-- oracle-scope: *.go -->
+
 Return errors, do not panic across a package boundary. Wrap with `%w` so the
 caller can still match the cause, and add context the caller does not already
 have — never re-wrap the same fact twice.

package/packs/language/mdx/rules.md

@@ -1,5 +1,7 @@
 # Markdown JSX authoring
 
+<!-- oracle-scope: *.mdx -->
+
 Treat Markdown JSX (MDX) as a language, not generic prose. Validate front matter,
 component nesting, links, code fences, and accessible image descriptions.
 

package/packs/language/python/rules.md

@@ -1,5 +1,7 @@
 # Python authoring
 
+<!-- oracle-scope: *.py -->
+
 Use standard-library parsers for structured input. Keep resource ownership in
 context managers. Validate data at parse boundaries and preserve specific
 exception classes until the caller can decide how to respond.

package/packs/language/rust/rules.md

@@ -1,5 +1,7 @@
 # Rust authoring
 
+<!-- oracle-scope: *.rs -->
+
 Use ownership and borrowing to make resource lifetime visible. Keep `unsafe`
 blocks small and state the invariant they rely on. Preserve error variants until
 the caller has enough information to decide whether to retry or stop.
@@ -31,6 +33,134 @@ 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)
+
+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

package/packs/language/shell/rules.md

@@ -1,5 +1,7 @@
 # Shell authoring
 
+<!-- oracle-scope: *.sh -->
+
 Quote expansions, use arrays for argument lists, and clean temporary files on
 every exit path. Avoid `eval` for external input. Match the repository's required
 shell and macOS Bash compatibility level.

package/registry.json

@@ -263,6 +263,10 @@
           "source": "dispatch/edit_rules.md",
           "target": "dispatch/edit_rules.md"
         },
+        {
+          "source": "dispatch/edit_rules.sh",
+          "target": "dispatch/edit_rules.sh"
+        },
         {
           "source": "audits/agents-md.md",
           "target": "audits/agents-md.md"

package/skills/orly-babysit-prs/SKILL.md

@@ -13,6 +13,12 @@ description: |
 
 # orly-babysit-prs
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-babysit-prs >/dev/null 2>&1 || true
+```
+
 Review bots (greptile on GitHub; greptile or another review bot on GitLab)
 post auto-reviews **asynchronously**. They land as PR review comments / MR
 discussion threads, not check runs, so `gh pr checks --watch` (or the glab

package/skills/orly-spec-new/SKILL.md

@@ -11,6 +11,12 @@ description: |
 
 # orly-spec-new
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-spec-new >/dev/null 2>&1 || true
+```
+
 A spec is the **rulebook** the executing agent (Orly) plans and ships from. This
 skill makes me author one whose Pull Request (PR) lands **deterministic, review-clean, and
 reported** — without a 20-questions loop. It is written for my reasoning, not as

package/skills/orly-write-integration-test/SKILL.md

@@ -11,6 +11,12 @@ description: >
 
 # Write Integration Test
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-write-integration-test >/dev/null 2>&1 || true
+```
+
 Service-layer tests that prove real wiring works under real failure modes. Sits between unit tests (`make test`) and browser E2E (gstack `/qa`, `/e2e-qa-playwright`).
 
 > **What this guarantees / what it doesn't.** Integration tests don't prove "zero bugs

package/skills/orly-write-unit-test/SKILL.md

@@ -11,6 +11,12 @@ description: >
 
 # Write Unit Test
 
+At invocation start, record the consent-gated usage signal without blocking the skill:
+
+```bash
+command -v orly >/dev/null 2>&1 && ORLY_INVOCATION=skill orly skill-event orly-write-unit-test >/dev/null 2>&1 || true
+```
+
 Generate tests that catch bugs before they ship. Tests run *during* implementation, not after.
 
 > **What this guarantees / what it doesn't.** No test suite proves "zero bugs in

package/src/cli.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 const ROOT = resolve(import.meta.dir, "..");
 const COMMAND = resolve(ROOT, "bin/orly");
@@ -18,6 +18,19 @@ describe("orly command", () => {
     expect(output).not.toContain("oracle-rules");
   });
 
+  test("telemetry_help_names_tiers_storage_and_privacy", () => {
+    const result = Bun.spawnSync([COMMAND, "--help"], { cwd: ROOT, stdout: "pipe", stderr: "pipe" });
+    const output = result.stdout.toString();
+
+    expect(output).toContain("off by default");
+    expect(output).toContain("anonymous");
+    expect(output).toContain("~/.config/agentsfleet/orly/.orly.json");
+    expect(output).toContain("AGENTSFLEET_STATE_DIR");
+    expect(output).toContain("ORLY_TELEMETRY_OFF=1");
+    expect(output).toContain("packaged Orly skill");
+    expect(output).toContain("never collects source, paths, repositories, branches, arguments, prompts");
+  });
+
   // Adversarial review found recordOptIn running before the --dry-run branch,
   // so a preview created .oracle/orly.json — and on an installed repository
   // permanently added the pack. A dry run changes nothing, opt-in included.
@@ -67,4 +80,72 @@ describe("orly command", () => {
 
     expect(result.exitCode).toBe(0);
   });
+
+  test("telemetry_failure_never_changes_command_result", () => {
+    const blockedRoot = join(mkdtempSync(join(tmpdir(), "orly-telemetry-blocked-")), "state-file");
+    writeFileSync(blockedRoot, "not a directory\n");
+    const enabled = { ...process.env, AGENTSFLEET_STATE_DIR: blockedRoot, ORLY_TELEMETRY: "anonymous" };
+    const off = { ...enabled, ORLY_TELEMETRY_OFF: "1" };
+    try {
+      const successWithFailure = Bun.spawnSync([COMMAND, "doctor"], { cwd: ROOT, env: enabled, stdout: "pipe", stderr: "pipe" });
+      const successWithOff = Bun.spawnSync([COMMAND, "doctor"], { cwd: ROOT, env: off, stdout: "pipe", stderr: "pipe" });
+      const errorWithFailure = Bun.spawnSync([COMMAND, "gate", "nope"], { cwd: ROOT, env: enabled, stdout: "pipe", stderr: "pipe" });
+      const errorWithOff = Bun.spawnSync([COMMAND, "gate", "nope"], { cwd: ROOT, env: off, stdout: "pipe", stderr: "pipe" });
+
+      expect(successWithFailure.exitCode).toBe(successWithOff.exitCode);
+      expect(successWithFailure.stdout.toString()).toBe(successWithOff.stdout.toString());
+      expect(errorWithFailure.exitCode).toBe(errorWithOff.exitCode);
+      expect(errorWithFailure.stderr.toString()).toBe(errorWithOff.stderr.toString());
+    } finally {
+      rmSync(dirname(blockedRoot), { recursive: true, force: true });
+    }
+  });
+
+  test("gate_command_records_its_selected_gate_and_failed_criterion", async () => {
+    const root = mkdtempSync(join(tmpdir(), "orly-telemetry-command-"));
+    const repo = join(root, "repo");
+    const stateRoot = join(root, "state");
+    Bun.spawnSync(["git", "init", "-q", repo]);
+    writeFileSync(join(repo, "README.md"), "fixture\n");
+    Bun.spawnSync(["git", "-C", repo, "add", "README.md"]);
+    Bun.spawnSync(["git", "-C", repo, "-c", "user.name=Orly Test", "-c", "user.email=orly@example.invalid", "commit", "-q", "-m", "test: seed"]);
+    Bun.spawnSync(["git", "-C", repo, "checkout", "-q", "-b", "feat/telemetry"]);
+    const env = {
+      ...process.env,
+      AGENTSFLEET_STATE_DIR: stateRoot,
+      ORLY_TELEMETRY: "anonymous",
+      ORLY_TELEMETRY_OFF: "0",
+      ORLY_POSTHOG_HOST: "http://127.0.0.1:1",
+    };
+    try {
+      const result = Bun.spawnSync([COMMAND, "gate", "pr"], { cwd: repo, env, stdout: "pipe", stderr: "pipe" });
+      expect(result.exitCode).toBe(1);
+      const failedCriterion = result.stdout.toString().match(/🔴 ([^:]+):/)?.[1];
+      expect(failedCriterion).toBeDefined();
+
+      const spool = join(stateRoot, "orly/analytics/orly-usage.jsonl");
+      for (let attempt = 0; attempt < 20 && !existsSync(spool); attempt += 1) await Bun.sleep(10);
+      const event = JSON.parse(readFileSync(spool, "utf8"));
+      expect(event).toMatchObject({ command: "gate", gate: "pr", outcome: "error", failed_criterion: failedCriterion });
+      expect(event.duration_ms).toBeGreaterThanOrEqual(0);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("skill_event_accepts_only_packaged_skills", () => {
+    const env = { ...process.env, ORLY_TELEMETRY_OFF: "1", ORLY_INVOCATION: "skill" };
+    const packagedSkills = ["orly-babysit-prs", "orly-spec-new", "orly-write-integration-test", "orly-write-unit-test"];
+    for (const skill of packagedSkills) {
+      const accepted = Bun.spawnSync([COMMAND, "skill-event", skill], { cwd: ROOT, env, stdout: "pipe", stderr: "pipe" });
+      expect(accepted.exitCode).toBe(0);
+      expect(accepted.stdout.toString()).toBe("");
+      expect(readFileSync(join(ROOT, "skills", skill, "SKILL.md"), "utf8")).toContain(`orly skill-event ${skill}`);
+    }
+    const rejected = Bun.spawnSync([COMMAND, "skill-event", "other-skill"], { cwd: ROOT, env, stdout: "pipe", stderr: "pipe" });
+
+    expect(rejected.exitCode).toBe(1);
+    expect(rejected.stderr.toString()).toContain("skill-event requires a packaged Orly skill name");
+    expect(Bun.spawnSync([COMMAND, "--help"], { cwd: ROOT, env, stdout: "pipe" }).stdout.toString()).not.toContain("skill-event");
+  });
 });