@agentsfleet/orly 0.5.0

package/docs/LOGGING_STANDARD.md

@@ -0,0 +1,397 @@
+# 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`.
+
+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.
+
+## §1 · Scope
+
+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/`.
+- `*.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.
+- Build/release scripts in `~/Projects/dotfiles/`, `audits/release-*` — toolchain output, not application logs.
+- Generated framework noise (Next.js startup banners, Bun runtime warnings) — out of our control.
+
+The **LOGGING GATE** (`dispatch/write_any.md`, Logging Gate) sits on top of this file — it fires in addition to the language-level rules in `dispatch/write_zig.md` and `dispatch/write_ts_adhere_bun.md`, not instead of them.
+
+## §2 · Today's de-facto standard (survey-derived)
+
+Documented honestly, not aspirationally. Pre-M62 baseline (the fix-pass converges every existing emit toward §3 onward):
+
+- Zig calls are mostly `std.log.scoped(.tag).info(comptime fmt, args)` with positional `{s} {d}` placeholders. Severity choice is inconsistent: successful happy-path events sometimes log at `info`, sometimes are silent. Per-call migration to the structured `log.<level>("event", .{ .field = val })` form is in flight.
+
+> [DETERMINISTIC → LOG]
+
+- A small number of Zig sites use `std.debug.print` directly — bypasses the scope/level system entirely. Always a violation.
+
+> [UNENFORCED → umbrella pointer; enforcement lives in the tagged clauses §3 onward, not in this survey sentence itself]
+
+- The named module `log` (source: `src/lib/logging/mod.zig`) exposes `scoped(.tag)` returning a logger struct with `.err` / `.warn` / `.info` / `.debug` methods. M62 removed the older free-function helpers (`logErr` / `logErrWithHint` / `logWarnErr`) — there is no compat shim.
+- TypeScript (`cli/src/**`) calls `console.log`/`console.error` directly. No structure. No scope. No severity beyond err vs out.
+- Error-code embedding (`UZ-XXX-NNN`) appears on some `err` lines but not others. The registry (`src/agentsfleetd/errors/error_registry.zig`) is the source of truth, but enforcement is voluntary.
+- No collector-friendly format. Logs are a mix of free-form English and ad-hoc `key={value}` fragments.
+
+The proposed standard below is what every new emit must conform to and what the fix-pass converges existing emits toward.
+
+## §3 · Wire format — logfmt
+
+Every record is a single newline-terminated line in **logfmt**: space-separated `key=value` pairs, value-quoted only when the value contains whitespace or `=` or `"`.
+
+```
+ts_ms=1715004901234 level=warn scope=executor event=tool_call_failed correlation_id=abc-123 error_code=UZ-EXEC-012 tool=bash duration_ms=1240 msg="tool returned non-zero"
+```
+
+> [UNENFORCED → record shape is a runtime-rendered property; no linter parses emitted logfmt for key presence/order, and none of this section is checked by audits/logging.sh]
+
+**Required keys per record (in this order):**
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `ts_ms` | u64 | always | Unix epoch milliseconds. Single source of truth for ordering. |
+| `level` | enum | always | One of `err`, `warn`, `info`, `debug`, `trace`. See §4. |
+| `scope` | snake_case ident | always | Subsystem tag (e.g. `executor`, `http`, `auth`, `redis`). See §7 for the binding. |
+| `event` | snake_case `verb_noun` | always | What happened. Examples: `request_started`, `tool_call_failed`, `worker_drained`. |
+| `error_code` | `UZ-XXX-NNN` | required on `err`/`warn` mapping to a registry code | See §5. |
+| `correlation_id` | string | optional | Trace context where present. |
+| `msg` | string | optional | Human-readable elaboration. **Last** field by convention so multiline-ish msgs don't break grep. |
+| `<arbitrary>` | any | optional | Domain fields (`tool=bash`, `duration_ms=1240`, `worker_id=42`). Snake_case keys. |
+
+**Encoding rules:**
+
+- Values with no whitespace, `=`, or `"`: bare (`duration_ms=1240`, `tool=bash`).
+- Values with whitespace or `=` or `"`: double-quoted, with `"` and `\` backslash-escaped (`msg="tool returned: \"exit 1\""`).
+- Newlines in values: replaced with `\n` literal (two chars). Logfmt is one-line-per-record; embedded newlines break tooling.
+- Booleans: `true` / `false`.
+- Numbers: bare integers and decimals. No thousands separators.
+- Slices/arrays: omit. If you need to log a collection, log it as count + sample (`count=42 sample=abc,def,ghi`) or emit one record per item.
+- Null/absent: omit the key entirely. **Don't emit `key=null` or `key=`** — empty/null fields confuse parsers.
+
+**Why logfmt and not JSON:** logfmt is grep-friendly for `tail -f`, parses cleanly into Loki / Vector / Promtail / Mezmo / Datadog with zero transform, and is readable without tooling. JSON would also work but is uglier on a dev box. logfmt is the production-server sweet spot. See §9 for the optional pretty-printer.
+
+## §4 · Severity contract
+
+> [UNENFORCED → the closed method set on LoggerFor (§7) blocks a sixth level at compile time; audits/logging.sh does not check level count]
+
+Five levels. Use them as defined; do not invent intermediate levels.
+
+| Level | When | Examples | Default visibility |
+|---|---|---|---|
+| `err` | Operation failed; user/operator action required; data may be inconsistent. | DB connection lost, auth failure, panic recovery, syscall failure that breaks a request. | always emitted |
+| `warn` | Operation succeeded but with degraded behaviour, or an expected failure on a recoverable path. | Retry succeeded after one failure; cache miss to slow path; deprecated endpoint hit. | always emitted |
+| `info` | Operation boundaries and operationally significant state changes. | Server start/stop, an operation's `_started`/`_completed` pair, migration applied, batch boundary, a subsystem coming up. | emitted in production |
+| `debug` | Exhaustive diagnostic detail — the level you switch **on** to debug. | Per-iteration tool calls, full request/response shapes, every branch of a multi-step pipeline, cache lookup outcomes. | hidden by default; opt-in via env var (see §7) |
+| `trace` | Per-byte / per-event firehose. | Bytes-on-the-wire, parser tokens, allocator events. | hidden by default; opt-in only; rarely written |
+
+`info` has three rules, in this order. The first is a duty to log, the second a
+licence, the third the only prohibition.
+
+> [JUDGMENT → BOUNDARY]
+
+**1. REQUIRED — bracket every boundary-crossing operation.** An operation that
+crosses a process, network, datastore, or subprocess boundary, or that bookends a
+lifecycle phase, MUST emit `<thing>_started` on entry and exactly one of
+`<thing>_completed` / `<thing>_failed` on **every** exit path, carrying an id
+that correlates the pair. Boot phases, migrations, lease lifecycle, outbound
+vendor calls, subprocess execution, subsystem startup and shutdown all qualify.
+
+This one is a requirement rather than advice because the failure it prevents is
+invisible until an incident: an entry with no exit means a hang reads exactly
+like work that was never reached, and that is the state an operator cannot
+debug. An exit with no entry is the same defect from the other side — you cannot
+tell how long it took or whether it ran twice. Adding the second half of a pair
+is never scope creep.
+
+It is narrow on purpose. It binds operations that can *hang*, not functions. Do
+not manufacture a `_started` for a pure computation, an accessor, or anything
+that cannot fail slowly.
+
+**2. OPEN — everything else is the engineer's judgement.** There is no allow-list
+of permitted event names, and none may be introduced. An engineer who judges a
+state change worth an operator's attention logs it at `info` and owes nobody a
+justification; a reviewer asking for its removal owes a concrete reason. The cost
+of a missing `info` is an incident nobody can bisect. The cost of an extra one is
+a line in a log. Those are not symmetric, so the default is to log it.
+
+**3. PROHIBITED — per-iteration paths are `debug`.** A loop body, a per-row step,
+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`.
+
+### `err` and `warn` are unconditional
+
+> [UNENFORCED → "always emitted" is a runtime filter-configuration property; nothing greps for a suppressed err/warn path]
+
+Both are **always emitted**, in every build and every environment, and there is
+no volume argument against either. If a code path can fail, its failure is
+logged — a silent `catch {}` on a path that can genuinely fail is the defect,
+not the log line that would have named it. §5 governs what the record carries;
+this rule governs that the record exists at all.
+
+There is no `fatal` level (§11). A condition that ends the process is `err`
+immediately before the exit, so the last line an operator reads is the reason.
+
+### Detail and redaction
+
+> [UNENFORCED → broad principle; the M42_002 harness redacts executor-child stdout, not every log call site in the codebase]
+
+`info` carries the fields that make a significant event actionable — ids,
+counts, outcomes, durations, the resolved configuration source. It is not a bare
+event name. `debug` carries whatever it takes to diagnose: full payload shapes,
+every branch taken, intermediate state.
+
+**Redaction is level-independent.** §6 applies identically at `debug` and at
+`trace`. "Exhaustive" describes *volume and breadth*, never permission to log a
+credential: a secret that only appears when debugging is on is still a secret in
+a log file, and debugging is on precisely when something is already going wrong.
+> [JUDGMENT → REDACT]
+
+Log the source (`source=env:OPENAI_API_KEY`), never the value, at every level.
+
+> [UNENFORCED → same closed-method-set reasoning as §4 — compile-time, not audits/logging.sh]
+
+`note` is **NOT** a level. Bun has it; we do not. Five levels only.
+
+## §5 · Error-code embedding
+
+> [DETERMINISTIC → LOG]
+
+Every `err` and `warn` record that maps to a domain error MUST carry `error_code=UZ-XXX-NNN` where `UZ-XXX-NNN` is declared in `src/agentsfleetd/errors/error_registry.zig`.
+
+- **Used-but-undeclared** (`UZ-FAKE-999` appearing in code, no entry in registry): **blocking** in `make lint`.
+- **Declared-but-unreferenced** (registry has `UZ-LEGACY-007`, no code references it): **informational**. Deletion may be deferred to a sweep milestone.
+
+Embed the code as a struct field on the logger call: `log.err("event_name", .{ .error_code = error_codes.ERR_X, .err = @errorName(err) })`. The encoding helpers in `src/lib/logging/mod.zig` serialize it as `error_code=UZ-XXX-NNN` per §3. CLI (`agentsfleet`) renders the code in human format and as `code: "UZ-XXX-NNN"` in `--json` output (see §8).
+
+System-level failures with no domain meaning (e.g. raw `EACCES` from a syscall before we attribute it to a tenant operation) emit without `error_code`. The follow-up rule: if a syscall failure surfaces to a user, it gets attributed to a registry code at the boundary.
+
+## §6 · PII / secret discipline
+
+> [UNENFORCED → broad principle; no scan covers every log call site in the codebase for credential-shaped values]
+
+Inherits the redaction list from M42_002 (`src/runner/engine/runner_progress.zig`). Same secret values must not appear anywhere in log records.
+
+> [JUDGMENT → REDACT]
+
+- **Allocator outputs** (Postgres connection strings, Redis URLs, OAuth tokens, OpenAI keys) — never log. If a record needs to identify a config source, log the *source* (`source=env:OPENAI_API_KEY`), not the *value*.
+- **Tenant-supplied secrets** (workspace API keys, BYOK credentials) — redaction harness covers stdout/stderr from executor children. Log emit sites in this codebase MUST NOT bypass the harness.
+- **Stderr coverage gap** — today's redactor covers child stdout only. Closing this gap (extending to stderr) is part of M62_001's fix-pass, not a separate milestone.
+
+> [JUDGMENT → MSG-REVIEW]
+
+- **`msg=` fields** — values copy-pasted into `msg=` are the most common leak source. Audit script flags long `msg=` values; reviewer must verify they don't carry credentials.
+
+When in doubt, omit. A missing field is recoverable; a leaked secret is not.
+
+## §7 · Per-language binding — Zig
+
+The wire format above is produced by helpers in `src/lib/logging/mod.zig`, exposed as the named module `log` so any layer-isolated tree (auth/, executor/) can import it without violating layer rules. Call sites use:
+
+```zig
+const logging = @import("log");                  // named module, see build.zig
+const log = logging.scoped(.executor);            // compile-time enum-literal tag
+
+log.info("tool_call_started", .{
+    .correlation_id = req.id,
+    .tool = "bash",
+});
+
+log.warn("tool_call_failed", .{
+    .error_code = "UZ-EXEC-012",
+    .tool = "bash",
+    .duration_ms = elapsed,
+    .msg = "tool returned non-zero",
+});
+```
+
+**Mechanics:**
+
+> [UNENFORCED → would need semantic call-site analysis; regex-based audits/logging.sh cannot distinguish manual string assembly from a helper call, and cannot see runtime env-var re-check behaviour]
+
+- `logging.scoped(.tag)` returns a type bound to that compile-time scope (the `.tag` is an enum literal). The returned type exposes `.err`, `.warn`, `.info`, `.debug` methods.
+- Each method takes a comptime `event: []const u8` (snake_case `verb_noun`) and an anonymous-struct of fields.
+- Field encoding to logfmt happens in the helper, not at the call site. Call sites never assemble strings.
+- Optional fields with null payload are omitted (no `key=null` / `key=`) per §3.
+
+**Compile-time visibility short-circuit** — pattern adapted from Bun's `Output.scoped` (`bun:src/output.zig:869`). Hidden scopes compile to **zero instructions**:
+
+```zig
+pub fn LoggerFor(comptime scope: Scope) type {
+    return struct {
+        pub inline fn debug(comptime event: Event, fields: anytype) void {
+            if (comptime scope_visibility(scope, .debug) == .hidden) return;
+            emit(.debug, scope, event, fields);
+        }
+        // ... err / warn / info / trace
+    };
+}
+```
+
+The `comptime if ... return` makes the entire emit path disappear when the scope is gated off. A `debug`-tagged log call in a tight loop, when its scope is gated off, costs zero. Faster than any runtime-flag library.
+
+**Runtime visibility override** — env var `AGENTSFLEET_LOG_<SCOPE>=debug` (e.g. `AGENTSFLEET_LOG_EXECUTOR=debug`) flips a scope to debug-visible without recompiling. Read once at startup, cached. Production never re-checks env per call.
+
+**Field encoding is allocation-free on the hot path** — the helper writes directly to a thread-local 4 KiB buffer and flushes on `\n`. Spillover to heap only on records exceeding 4 KiB, which is rare and warns at debug.
+
+**Anti-patterns flagged by `logging.sh`:**
+
+| 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.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. |
+
+## §8 · Per-language binding — TypeScript / JavaScript (`agentsfleet`)
+
+Wire format identical to §3. CLI obeys two render modes:
+
+**Human mode** (default — TTY attached, no `--json` flag):
+
+```
+error UZ-EXEC-012: tool returned non-zero (executor) tool=bash duration=1.24s
+  hint: check the tool's stderr above for details
+  see: https://docs.agentsfleet.net/errors/UZ-EXEC-012
+```
+
+Colors: red `error`, dim parens. Rendering inspired by Bun's `SystemError.format()` (`bun:src/bun.js/bindings/SystemError.zig:85`) — same shape, our error registry as the source.
+
+**JSON mode** (`--json` flag, or stdout is a pipe and `AGENTSFLEET_FORMAT=json` is set):
+
+```json
+{ "code": "UZ-EXEC-012", "message": "tool returned non-zero", "scope": "executor", "fields": { "tool": "bash", "duration_ms": 1240 }, "hint": "check the tool's stderr above for details", "docs": "https://docs.agentsfleet.net/errors/UZ-EXEC-012" }
+```
+
+Schema mirrors Bun's `SystemError` extern struct (`bun:src/bun.js/bindings/SystemError.zig:1`) — `{ code, message, ...context, hint?, docs? }`. Our `code` is `UZ-XXX-NNN` (registry-defined) rather than errno; the *shape* is what we mirror.
+
+> [DETERMINISTIC → LOG]
+
+**Logging emit sites** in `cli/src/**` use a thin Bun-runtime logger that produces logfmt records to `stderr`. `console.log` / `console.error` are forbidden in source per `dispatch/write_ts_adhere_bun.md` §10 — `logging.sh` enforces this for TS/JS.
+
+> [JUDGMENT → TS-STYLE]
+
+**Module-level error style** is governed by `dispatch/write_ts_adhere_bun.md` §9 (one style per module — throw OR Result, never both). The error type itself is the same:
+
+```ts
+class AgentError extends Error {
+  readonly code: string;          // UZ-XXX-NNN
+  readonly fields: Record<string, unknown>;
+  readonly hint?: string;
+}
+```
+
+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.
+
+## §9 · Pretty-printer (dev-only render variant)
+
+In production: every record on the wire is logfmt. No exceptions.
+
+In development (TTY attached, optional `AGENTSFLEET_LOG_PRETTY=1` env var): the same record can render as a colored printf-style line for human readability:
+
+```
+14:32:18.234  WARN  executor  tool_call_failed  tool=bash duration=1.24s — tool returned non-zero  [UZ-EXEC-012]
+```
+
+Mechanics:
+
+> [UNENFORCED → render-path architecture; a static scan cannot see how many times a record renders, and §9 is explicitly off the audit path by its own third bullet]
+
+- TTY check happens **once at process startup** (`isatty(stderr) && env.AGENTSFLEET_LOG_PRETTY != "0"`). Cached as a compile-once boolean.
+- A single sink picks the formatter at startup; from then on every record renders through the chosen formatter exactly once. **No strip step. No re-render.** The wire path never sees colors.
+- LOGGING GATE audits the **wire** format only. Pretty mode is post-hoc render and not on the audit path.
+
+Performance: zero measurable production impact. The pretty-vs-logfmt selector is one branch the predictor handles in a single cycle; in production (no TTY) it always takes the logfmt path. See `§7` for hot-path details (compile-time visibility short-circuit, thread-local 4 KiB buffer).
+
+## §10 · Reference: Bun's conventions (citations)
+
+We borrowed pattern, not code. Concrete file:line references for traceability:
+
+| Concept | Bun reference | What we took |
+|---|---|---|
+| Scoped logger with comptime visibility | `~/Projects/oss/bun/src/output.zig:869-902` | `Scope` enum + `LoggerFor(scope)` returning a struct of inline methods. Compile-time short-circuit via `comptime if (visibility == .hidden) return;`. |
+| Severity ladder | `~/Projects/oss/bun/src/logger.zig:1-31` | Five levels (we drop Bun's `note`). |
+| `Output.err` rendering errno + label + syscall | `~/Projects/oss/bun/src/output.zig:1155-1170` | Inspiration for `agentsfleet` human render: `code: message (context)`. |
+| `SystemError` JSON-facing shape | `~/Projects/oss/bun/src/bun.js/bindings/SystemError.zig:1-12` | `{ code, message, path?, syscall?, ... }` mirrored as our `--json` output schema. |
+| `SystemError.format()` ANSI-colored render | `~/Projects/oss/bun/src/bun.js/bindings/SystemError.zig:85-116` | Pattern reused for `agentsfleet` human mode (red code, dim context). |
+
+Zero lines copied verbatim. The patterns above each compile to ~10–30 lines of our own Zig/TypeScript in idiomatic form.
+
+## §10A · Tightening clauses (closures of common skip rationalizations)
+
+> [UNENFORCED → section pointer; each row below names its own enforcement — logging.sh, error-codes.sh, or the façade]
+
+Failure modes the audit script and reviewer must close. These are **not aspirational** — each closes a specific way an agent could otherwise dodge the rule.
+
+| # | 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. |
+| 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. |
+| 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. |
+| L8 | "I read this doc at session start; subsequent edits don't need re-print" | Gate fires **per-edit**. The printed `🔴 LOGGING GATE` block is required before every triggered Edit/Write, not once per session. |
+| L9 | "Fix-pass touches every line; printing per-line is noise" | Fix-pass produces **one combined gate block per file**, not per-line. The block lists all violations addressed in that file. Still required, just consolidated. |
+
+These are enforced by `logging.sh` (mechanical) and the dispatch façade (`dispatch/write_any.md`, Logging Gate — output discipline). When in conflict, the façade wins — it is the enforcement layer.
+
+## §11 · Anti-patterns (named, banned)
+
+| Pattern | Why banned |
+|---|---|
+| 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. |
+| `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. |
+| Logging credentials, tokens, or BYOK keys | Severe leak surface. Redaction harness mandatory. |
+| Multi-line records (embedded `\n` in values) | Breaks `tail -f`, breaks Loki, breaks every parser. |
+| `key=null` or `key=` (empty value) | Confuses parsers; some treat as missing, others as the literal string `null`. Omit the key. |
+| Inventing severity levels (`notice`, `severe`, `fatal`) | Five levels only. New names diverge from collector dashboards. |
+
+## §12 · Override syntax
+
+Per-record override (rare, user-only):
+
+```
+LOGGING RULE §<N>: SKIPPED per user override (reason: ...)
+```
+
+immediately preceding the edit. Generic "scope creep" is not a valid reason — name a concrete external constraint (third-party library log shape, vendored code, pre-launch debugging that won't ship). Auto-mode does NOT cover this override.
+
+## §13 · Family
+
+- `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.
+- `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`.
+- Length caps in `dispatch/write_any.md` (File & Function Length).
+
+> [JUDGMENT → SECTION-SCAN]
+
+- This file is the **wire-format and discipline layer** that those universal rules cannot express. Read it once at session start; on sub-task shape change, section-scan (`grep -n "^## "`) and re-read only the touched sections — never the full file again.
+
+## §14 · Enforcement tag glossary
+
+Every clause above carries a class tag. `docs/RULE_ENFORCEMENT.md` counts them;
+`audits/rule-ledger.sh --census` is the command that reads them. A tag alone on
+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 |
+| `[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 → 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

@@ -0,0 +1,129 @@
+# Orly architecture
+
+Orly does two jobs. It renders one rules file, and it proves the boundary
+before a Pull Request (PR) opens. What it stores where is the one thing that
+has changed shape since this document was first written — see "Why it's
+materialised" below; the gates section after it is unaffected.
+
+## Topology
+
+```text
+core/operating-model.md   packs/**   registry.json
+                              │
+                         bin/orly
+                              │
+          ┌───────────────────┴───────────────────┐
+          │                                       │
+   orly update                              orly gate
+          │                                       │
+   AGENTS.md (repo root)                  reads git + the tree,
+          │                               runs the declared commands,
+   ~/.claude/CLAUDE.md ─┐                 prints green or red
+   ~/.codex/AGENTS.md  ─┼─ symlinks              │
+   opencode, amp       ─┘                  exit 0 or 1
+```
+
+One generated artifact on this machine: the root `AGENTS.md`. Every agent home
+here links to it, so a rule edit is one commit and reaches every session in
+this checkout at once — that property is local to Kishore's own machine and
+unaffected by anything below.
+
+Every other repository gets its rules a different way: `orly init` materialises
+the packs its own sources select — rendered `AGENTS.md`, the rule docs, the gate
+scripts, the hooks that run them — into that repository, and writes
+`.oracle/orly.json` recording the engine version and every file it wrote,
+alongside the repository's own packs, commands, and surfaces. `orly update` re-materialises against the currently installed engine
+version; `orly doctor` reports drift between the lock and disk instead of
+silently tolerating it. A materialised repository needs no checkout of this
+one, on any machine, to read its own rules or run its own gates.
+
+## Why it's materialised
+
+An earlier model (M01) rejected storing per-repository copies: it had cost a
+re-baseline commit on every edit, a SHA-256 manifest that invalidated whenever
+the tool itself changed, and drift nobody caught — three of four consumer
+repositories were stale anyway. The fix at the time was to derive instead of
+store: one rendered `AGENTS.md`, symlinked into every agent home, with gate
+scripts resolved live from this checkout via `$ORLY_ROOT`.
+
+That traded the storage cost for a distribution cost undiscovered until a
+second engineer tried to install the harness without this checkout present —
+the symlink and `$ORLY_ROOT` both require a copy of `~/Projects/dotfiles` at a
+known path, which is exactly what a fresh machine, a Continuous Integration
+(CI) runner, or a remote fleet container does not have. `orly init` (M03)
+restores storage, but not the failure mode that got it removed: `orly update`
+turns a rule change into one command per repository instead of the manual
+sync M01 rejected, and the lock makes staleness a reported condition —
+`orly doctor` — instead of a silent one. cache-kit.rs is the evidence for both
+failure modes in the same repository: its `.oracle/` snapshot from the
+pre-thin model sat frozen for four weeks with no update path, and its
+generated `AGENTS.md` told a Rust crate its project name was `agentsfleet` —
+a persona/product leak M03 also closes, by fencing both behind opt-in packs a
+a repository without those sources never selects.
+
+`orly verify --all` still re-renders each pack set twice and compares, then
+compares the committed root `AGENTS.md` against a fresh render — that
+determinism proof is unchanged by any of this.
+
+## Gates
+
+`orly gate` runs three groups in order and stops at the first red one.
+
+| Gate | Proves |
+|---|---|
+| `work` | branch is not the default; tree is clean; the repository declares its commands in `.oracle/orly.json` |
+| `verify` | Dimensions marked DONE (when a spec exists); `conform`; the fast `verify.*` commands |
+| `pr` | tree clean; branch pushed; spec gate + closed-spec follow-through (`spec.moved` / `spec.baseline` / `spec.ordering` / `spec.deferrals`); docs updated for user-surface changes; the slow suites |
+
+Every criterion is mechanical — it reads an exit code or a file. Claims that
+cannot be proven that way stay prose and are graded by the spec's rubric; they
+never become fake criteria.
+
+Four behaviours worth knowing:
+
+- **No spec, no problem — but closing is not escaping.** Spec criteria skip
+  with a printed reason, so an ad-hoc bug fix meets the quality gates without
+  being told to write a spec. A spec moved to `done/` on the branch is still
+  discovered through its `Branch:` header and gates the PR — CHORE(close)
+  never skip-passes the criteria it exists to satisfy. Two active specs is an
+  error — one stream per worktree.
+- **A worktree is its repository.** `repositories.json` registers primary
+  checkouts only; a linked worktree resolves through the set of checkouts git
+  reports for the shared object store. Streams stay ephemeral and unregistered,
+  and the declared commands still run in the worktree, never in the checkout
+  that carries the registry entry.
+- **Slow suites are conditional.** `verify.integration` and `verify.memory` run
+  only when the branch diff carries code files.
+- **The docs gate is diff-shaped.** A change under the repository's `surfaces.user`
+  prefixes with no matching `surfaces.docs` change is red. Test files and the
+  spec tree never count.
+
+## Overrides
+
+`orly override <criterion> --reason <REASON>` writes an empty commit carrying an
+`Orly-Override: <criterion> (<reason>)` trailer. It is immutable once pushed,
+visible in the PR, scoped to the branch by merge-base, and dead after the merge.
+A red criterion with a matching trailer reports `overridden`, never green. A
+malformed trailer is not an override; the gate stays red.
+
+## Profiles
+
+`.oracle/orly.json` names any opt-in packs, the command surface, and optionally the diff
+surfaces:
+
+```json
+{
+  "commands": { "conform": [["make", "harness-verify"]],
+                "verify.unit": [["make", "test-unit-all"]] },
+  "surfaces": { "user": ["src/agentsfleetd/http/", "cli/src/"],
+                "docs": ["docs/"] }
+}
+```
+
+Orly owns policy and invokes these commands. The repository owns what they do.
+
+## Evidence
+
+`orly verify --all --write-evidence` records the source commit and every check
+into `.oracle/evidence.json` (git-ignored). Pre-push writes it when the pushed
+range touches governance paths.