@agentsfleet/orly 0.7.0 → 0.7.1

package/audits/logging.sh

@@ -9,7 +9,7 @@
 #   - agentsfleet scope-prefix format from LOGGING_STANDARD §7 (the
 #     `log.scoped(...)` API path under `src/logging/`)
 #   - `UZ-XXX-NNN` as the `error_code=` substring per LOGGING_STANDARD §5
-#   - `src/` + `rustd/` + `agentsfleet/src/` as the scan roots
+#   - `src/` + `agentsfleet/src/` as the Zig and TypeScript scan roots
 # A parameterised version that reads prefix + scope-api path + scan
 # roots from a per-project config is the right long-term shape; not
 # done yet. Today, this script lives in dotfiles so the gate body and
@@ -19,7 +19,9 @@
 #   BLOCK  — exits 1, must fix:
 #            - `std.debug.print(` in non-test source under src/.
 #            - `println!` / `eprintln!` / `dbg!`, missing `event`, or positional
-#              tracing formatting in non-test Rust source under rustd/.
+#              tracing formatting in runtime Rust source. Direct stream writes
+#              may carry `// logging: <reason>` on or immediately above the
+#              emit when stdout or stderr is the intended program interface.
 #            - `console.log/debug/info/warn/error` in agentsfleet/src outside tests.
 #   INFO   — surfaced for reviewer/agent attention, doesn't block:
 #            - `std.log.scoped(...)` outside `src/logging/` (LOGGING_STANDARD §7
@@ -31,7 +33,8 @@
 #
 # Modes:
 #   --staged   diff-scope: only files in `git diff --cached`
-#   --all      (default) full src/ + rustd/ + agentsfleet/src/ scan
+#   --all      (default) full src/ + every tracked/unignored *.rs +
+#              agentsfleet/src/ scan
 #   --strict   promote every INFO finding to BLOCK (post-migration use)
 #
 # Exits 0 clean, 1 on BLOCK findings.
@@ -81,9 +84,9 @@ is_test_zig() {
   return 1
 }
 
-is_test_rust_path() {
+is_non_runtime_rust_path() {
   case "$1" in
-    */tests/*|*/benches/*) return 0 ;;
+    build.rs|*/build.rs|tests/*|*/tests/*|benches/*|*/benches/*|examples/*|*/examples/*) return 0 ;;
   esac
   return 1
 }
@@ -95,11 +98,13 @@ gather_paths() {
   case "$MODE" in
     --staged)
       git diff --cached --name-only --diff-filter=ACMRT \
-        | grep -E '^(src/.*\.zig$|rustd/.*\.rs$|agentsfleet/src/.*\.(js|jsx|ts|tsx)$)' || true
+        | grep -E '(^src/.*\.zig$|\.rs$|^agentsfleet/src/.*\.(js|jsx|ts|tsx)$)' || true
       ;;
     --all)
       find src -type f -name '*.zig' 2>/dev/null || true
-      find rustd -type f -name '*.rs' 2>/dev/null || true
+      while IFS= read -r path; do
+        [[ -f "$path" ]] && printf '%s\n' "$path"
+      done < <(git ls-files --cached --others --exclude-standard -- '*.rs')
       find agentsfleet/src -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \) 2>/dev/null || true
       ;;
   esac
@@ -116,12 +121,13 @@ fi
 # single awk/grep passes.
 zig_nontest=()
 rust_nontest=()
+rust_candidates=()
 js_nontest=()
 for f in "${FILES[@]}"; do
   if [[ "$f" == *.zig ]] && ! is_test_zig "$f"; then
     zig_nontest+=("$f")
   fi
-  if [[ "$f" == *.rs ]] && ! is_test_rust_path "$f"; then
+  if [[ "$f" == *.rs ]] && ! is_non_runtime_rust_path "$f"; then
     rust_nontest+=("$f")
   fi
   case "$f" in
@@ -132,6 +138,10 @@ for f in "${FILES[@]}"; do
   esac
 done
 
+if [[ ${#rust_nontest[@]} -gt 0 ]]; then
+  mapfile -t rust_candidates < <(grep -lE '(^|[^[:alnum:]_])(println|eprintln|dbg)!|tracing::(error|warn|info|debug|trace)!' "${rust_nontest[@]}" 2>/dev/null || true)
+fi
+
 # ---------------------------------------------------------------------------
 # 2. BLOCKING: std.debug.print in non-test Zig source.
 # ---------------------------------------------------------------------------
@@ -146,10 +156,40 @@ if [[ ${#zig_nontest[@]} -gt 0 ]]; then
     fail "$f:$ln — \`std.debug.print\` in non-test source (LOGGING_STANDARD §10A.L1)"
     debug_print_hits=$((debug_print_hits + 1))
   done < <(awk '
-    FNR == 1 { in_test = 0 }
-    /^test "/ { in_test = 1; next }
-    /^}/ { in_test = 0; next }
-    /(^|[^A-Za-z0-9_])std\.debug\.print\(/ { if (!in_test) printf "%s:%d\n", FILENAME, FNR }
+    function comment_text(text, output, cursor, char, escaped, quoted) {
+      escaped = 0
+      quoted = 0
+      for (cursor = 1; cursor <= length(text); cursor++) {
+        char = substr(text, cursor, 1)
+        if (quoted) {
+          if (escaped) escaped = 0
+          else if (char == "\\") escaped = 1
+          else if (char == "\"") quoted = 0
+          continue
+        }
+        if (char == "\"") {
+          quoted = 1
+          continue
+        }
+        if (char == "/" && substr(text, cursor + 1, 1) == "/")
+          return substr(text, cursor + 2)
+      }
+      return ""
+    }
+    function has_logging_reason(text, comment) {
+      if (text ~ /^[[:space:]]*\\\\/) return 0
+      comment = comment_text(text)
+      return comment ~ /^[[:space:]]*logging:[[:space:]]*[^[:space:]]/
+    }
+    FNR == 1 { in_test = 0; previous_annotation = 0 }
+    {
+      annotated = has_logging_reason($0) || previous_annotation
+      if ($0 ~ /^test "/) in_test = 1
+      else if ($0 ~ /^}/) in_test = 0
+      else if ($0 ~ /(^|[^A-Za-z0-9_])std\.debug\.print\(/ && !in_test && !annotated)
+        printf "%s:%d\n", FILENAME, FNR
+      previous_annotation = has_logging_reason($0)
+    }
   ' "${zig_nontest[@]}")
 fi
 
@@ -160,7 +200,7 @@ fi
 rust_direct_hits=0
 rust_missing_event_hits=0
 rust_positional_hits=0
-if [[ ${#rust_nontest[@]} -gt 0 ]]; then
+if [[ ${#rust_candidates[@]} -gt 0 ]]; then
   while IFS='|' read -r kind f ln; do
     [[ -z "$kind" ]] && continue
     case "$kind" in
@@ -227,6 +267,30 @@ if [[ ${#rust_nontest[@]} -gt 0 ]]; then
       }
       return output
     }
+    function comment_text(text, cursor, char, escaped, quoted) {
+      escaped = 0
+      quoted = 0
+      for (cursor = 1; cursor <= length(text); cursor++) {
+        char = substr(text, cursor, 1)
+        if (quoted) {
+          if (escaped) escaped = 0
+          else if (char == "\\") escaped = 1
+          else if (char == "\"") quoted = 0
+          continue
+        }
+        if (char == "\"") {
+          quoted = 1
+          continue
+        }
+        if (char == "/" && substr(text, cursor + 1, 1) == "/")
+          return substr(text, cursor + 2)
+      }
+      return ""
+    }
+    function has_logging_reason(text, comment) {
+      comment = comment_text(text)
+      return comment ~ /^[[:space:]]*logging:[[:space:]]*[^[:space:]]/
+    }
     function check_emit() {
       if (emit_code !~ /event[[:space:]]*=/ && emit_code !~ /[(,][[:space:]]*event[[:space:]]*[,)]/)
         printf "event|%s|%d\n", FILENAME, emit_line
@@ -244,15 +308,21 @@ if [[ ${#rust_nontest[@]} -gt 0 ]]; then
       emit_parens = 0
       emit_code = ""
       emit_source = ""
+      previous_annotation = 0
     }
     {
+      current_annotation = has_logging_reason($0)
       code = code_only($0)
-      if (!in_emit && code ~ /^[[:space:]]*$/) next
+      if (!in_emit && code ~ /^[[:space:]]*$/) {
+        previous_annotation = current_annotation
+        next
+      }
       opens = count_char(code, "\\{")
       closes = count_char(code, "\\}")
       if (test_depth > 0) {
         depth += opens - closes
         if (depth < test_depth) test_depth = 0
+        previous_annotation = current_annotation
         next
       }
       if (code ~ /^[[:space:]]*#\[cfg\(test\)\]/) {
@@ -261,6 +331,7 @@ if [[ ${#rust_nontest[@]} -gt 0 ]]; then
           depth += opens - closes
           if (depth < test_depth) test_depth = 0
         } else cfg_test = 1
+        previous_annotation = current_annotation
         next
       }
       if (cfg_test) {
@@ -270,9 +341,10 @@ if [[ ${#rust_nontest[@]} -gt 0 ]]; then
           if (depth < test_depth) test_depth = 0
           cfg_test = 0
         } else if (code ~ /;/) cfg_test = 0
+        previous_annotation = current_annotation
         next
       }
-      if (code ~ /(^|[^[:alnum:]_])(println|eprintln|dbg)!/)
+      if (code ~ /(^|[^[:alnum:]_])(println|eprintln|dbg)!/ && !current_annotation && !previous_annotation)
         printf "direct|%s|%d\n", FILENAME, FNR
       if (!in_emit && match(code, /tracing::(error|warn|info|debug|trace)!/)) {
         in_emit = 1
@@ -288,8 +360,9 @@ if [[ ${#rust_nontest[@]} -gt 0 ]]; then
       }
       if (in_emit && emit_parens <= 0) check_emit()
       depth += opens - closes
+      previous_annotation = current_annotation
     }
-  ' "${rust_nontest[@]}")
+  ' "${rust_candidates[@]}")
 fi
 
 # ---------------------------------------------------------------------------
@@ -363,6 +436,7 @@ fi
 ok "scanned ${#FILES[@]} files; std.debug.print=$debug_print_hits rust-direct=$rust_direct_hits rust-missing-event=$rust_missing_event_hits rust-positional=$rust_positional_hits console.*=$console_hits std.log.scoped=$scoped_hits missing-error_code=$missing_code_hits"
 if [[ $FAIL -ne 0 ]]; then
   printf "\n🔴 LOGGING GATE: blocking violations. See dispatch/write_any.md (Logging Gate).\n" >&2
+  printf "Intentional direct Zig or Rust stream output requires '// logging: <reason>' on or immediately above the emit; the reason must be non-empty.\n" >&2
   exit 1
 fi
 [[ $INFO_COUNT -gt 0 ]] && note "$INFO_COUNT informational findings; not blocking. Use --strict to enforce."

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/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,7 +6,7 @@ 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 |
@@ -14,7 +14,7 @@ regenerates this file and fails on any difference. To update it, run
 | `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/114 | mechanical |
-| **corpus** | | | | **28/283** | |
+| **corpus** | | | | **30/285** | |
 
 ## How to read this
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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",