@agentsfleet/orly 0.6.8 → 0.6.9

package/.githooks/pre-commit

@@ -32,7 +32,11 @@ fi
 # that did or did not read the façade is still the session committing.
 SOURCE_PATTERN='\.(zig|ts|tsx|js|jsx|py|rs|go|sh|sql)$'
 
-if git diff --cached --name-only | grep -qE "$SOURCE_PATTERN"; then
+# Governance paths join the source list here: dispatch/edit_rules.sh declares
+# the corpus scope, so a staged rule edit now has a façade to have read. The
+# check itself stays the arbiter — a path outside every leaf's globs still
+# reports "nothing staged triggers a façade" and costs one grep.
+if git diff --cached --name-only | grep -qE "$SOURCE_PATTERN|$GOVERNANCE_PATTERN"; then
   if ! bash audits/doc-read.sh check; then
     echo "pre-commit: a triggered façade went unread — read it, or record why" >&2
     exit 1

package/audits/doc-read.sh

@@ -94,19 +94,21 @@ content_hash() {
   git -C "$LEDGER_ROOT" hash-object "$LEDGER_ROOT/$1" 2>/dev/null || printf ''
 }
 
-# Façade pages the staged files trigger, one per line. Same glob map the
-# reachability report uses: a façade's scope is its dispatch_init line, so this
-# check and the ledger can never disagree about what fires.
+# Façade pages the staged files trigger, one per line. Scope comes from
+# ledger_facade_scope — the page's own oracle-scope tag, else its leaf's
+# dispatch_init — which is the SAME resolver the ledger's reachability report
+# uses, so this check and the ledger can never disagree about what fires.
+# Iterating pages rather than leaves is the point: a façade without a
+# deterministic leaf still has a trigger surface, and used to be unaskable.
 expected_facade_pages() {
-  local staged="$1" script stem globs
-  while IFS= read -r script; do
-    [ -n "$script" ] || continue
-    stem="$(basename "$script" .sh)"
-    [ -f "$LEDGER_ROOT/dispatch/$stem.md" ] || continue
-    globs="$(ledger_facade_globs "$script")"
-    [ -n "$globs" ] || continue
-    [ "$(ledger_match_count "$globs" < "$staged")" -gt 0 ] && printf 'dispatch/%s.md\n' "$stem"
-  done < <(ledger_facade_scripts)
+  local staged="$1" page stem scope
+  while IFS= read -r page; do
+    [ -n "$page" ] || continue
+    scope="$(ledger_facade_scope "$page")"
+    [ -n "$scope" ] || continue
+    stem="$(basename "$page" .md)"
+    [ "$(ledger_match_count "$scope" < "$staged")" -gt 0 ] && printf 'dispatch/%s.md\n' "$stem"
+  done < <(ledger_facade_pages)
 }
 
 json_unescape() {

package/audits/rule-ledger-lib.sh

@@ -187,6 +187,40 @@ ledger_has_prefix() {
 DISPATCH_LIB_BASENAME="lib.sh"
 
 # The executable façades: dispatch/*.sh minus the shared library.
+# A façade's trigger surface, declared where it belongs: in the façade. The tag
+# is one HTML comment, invisible in rendered markdown, e.g.
+#   <!-- oracle-scope: *.rs -->
+# Scope used to be readable ONLY from a leaf's dispatch_init line, so the five
+# façades carrying deterministic checks had a voice and the other fourteen had
+# none — a Rust author was never asked to read the Rust rules, because
+# write_rust.md has no .sh. The page wins; the leaf remains the fallback so the
+# mechanised façades keep the scope they already declare, in one place.
+FACADE_SCOPE_TAG='^[[:space:]]*<!--[[:space:]]*oracle-scope:[^>]*-->[[:space:]]*$'
+
+ledger_facade_pages() {
+  local file
+  for file in "$LEDGER_ROOT"/dispatch/*.md; do
+    [ -f "$file" ] || continue
+    printf '%s\n' "$file"
+  done
+}
+
+# Space-separated, trailing space — same shape ledger_facade_globs returns, so
+# ledger_match_count reads either without knowing which declared it.
+ledger_facade_scope() {
+  local page="$1" tag stem leaf
+  tag="$(grep -hE "$FACADE_SCOPE_TAG" "$page" 2>/dev/null | head -1)"
+  if [ -n "$tag" ]; then
+    printf '%s' "$tag" \
+      | sed -e 's/.*oracle-scope:[[:space:]]*//' -e 's/[[:space:]]*-->.*//' \
+            -e 's/[[:space:]][[:space:]]*/ /g' -e 's/[[:space:]]*$/ /'
+    return 0
+  fi
+  stem="$(basename "$page" .md)"
+  leaf="$(dirname "$page")/$stem.sh"
+  [ -f "$leaf" ] && ledger_facade_globs "$leaf"
+}
+
 ledger_facade_scripts() {
   local file
   for file in "$LEDGER_ROOT"/dispatch/*.sh; do
@@ -208,7 +242,16 @@ ledger_facade_globs() {
 # is the match itself — the same expansion dispatch_resolve_files applies to
 # explicit file arguments, so a fire count means what the dispatcher means.
 ledger_match_count() {
-  local globs="$1" path glob matches=0
+  local globs="$1" path glob matches=0 reglob=""
+  # `for glob in $globs` needs WORD SPLITTING and must not get PATHNAME
+  # EXPANSION: unguarded, bash expands each pattern against the real tree
+  # first, so a façade declaring 'src/*' iterates the 33 files that happen to
+  # exist there and then compares them as literals — src/foo.rs matches
+  # nothing and core/* "matches" only because it expanded to the one file in
+  # core/. Latent while every leaf declared extension globs ('*.zig') that
+  # match nothing at the root and so survive expansion unchanged; the first
+  # path-glob façade turns it into a scope that silently reads wrong.
+  case "$-" in *f*) ;; *) reglob="yes"; set -f ;; esac
   while IFS= read -r path; do
     [ -n "$path" ] || continue
     for glob in $globs; do
@@ -216,6 +259,7 @@ ledger_match_count() {
       case "$path" in $glob) matches=$((matches + 1)); break ;; esac
     done
   done
+  [ -n "$reglob" ] && set +f
   printf '%d' "$matches"
 }
 

package/audits/rule-ledger.sh

@@ -101,12 +101,24 @@ check_registry_parity() {
 # is answerable from the tree — unlike "has this fired lately", which depends on
 # what happened to get committed recently and gates nothing.
 check_facade_scopes() {
-  local script stem
+  local script stem page
+  # Iterates LEAVES, not pages: a leaf is a promise that something mechanical
+  # fires, so one declaring no scope is dead weight whether or not a page sits
+  # beside it. A façade with no leaf and no tag is situational — a lifecycle
+  # stage transition, a "tests pass" claim, writing a PR body — and has no
+  # staged-diff trigger to declare, so it is not a finding.
   while IFS= read -r script; do
     [ -n "$script" ] || continue
-    [ -n "$(ledger_facade_globs "$script")" ] && continue
     stem="$(basename "$script" .sh)"
-    fail "facade=$stem declares no dispatch_init scope — dispatch/$stem.sh (nothing it carries can ever fire)"
+    page="$LEDGER_ROOT/dispatch/$stem.md"
+    # Either surface may carry the scope; ledger_facade_scope prefers the page
+    # and falls back to this leaf, so both spellings satisfy the same check.
+    if [ -f "$page" ]; then
+      [ -n "$(ledger_facade_scope "$page")" ] && continue
+    else
+      [ -n "$(ledger_facade_globs "$script")" ] && continue
+    fi
+    fail "facade=$stem declares no scope — no oracle-scope tag in dispatch/$stem.md and no dispatch_init in dispatch/$stem.sh (nothing it carries can ever fire)"
   done < <(ledger_facade_scripts)
 }
 

package/dispatch/edit_rules.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# dispatch/edit_rules.sh — the rule-corpus dispatch, DETERMINISTIC façade.
+#
+# Pairs with dispatch/edit_rules.md (the LATENT façade — prose the agent reads).
+#
+# This leaf exists for the reason RULE UFS exists in the Rust pack: a façade
+# that declares its scope in PROSE declares it to nobody. edit_rules.md has
+# always named its trigger surface — core/**, packs/**, schemas/**, src/**,
+# registry.json, governance hooks (edit_rules.md:15, and the same row in
+# docs/EXECUTE_DOC_READS.md) — but audits/doc-read.sh derives what fires from
+# `dispatch_init` globs in a leaf, and this façade had no leaf. So every
+# governance edit reported "nothing staged triggers a façade" and the DOC READ
+# GATE could not fire on the one surface whose edits change the rules
+# themselves. The globs below ARE that scope, now in a form a gate can read.
+#
+#   dispatch/edit_rules.sh <file> [...]   # explicit targets (EXECUTE)
+#   dispatch/edit_rules.sh --staged       # staged corpus files (CONFORM, pre-commit)
+#
+# Layering:  AGENTS.md → edit_rules.md (latent) → edit_rules.sh (this) → audits/*.sh
+# Signals:   🟢 pass · 🔴 fail (blocks) · 🤔 DECIDE (judgment; blocks the TURN, not the script)
+# Exit:      0 = mechanical gates pass · 1 = ≥1 failed · 2 = usage error.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+# Scope mirrors docs/EXECUTE_DOC_READS.md's governance row and edit_rules.md:15.
+# Kept in one order with them: a glob here that the row does not name is a leaf
+# reading more than the façade declares, which is the same drift inverted.
+# ONE LINE, deliberately: ledger_facade_globs reads `head -1` of the
+# dispatch_init line, so a backslash continuation declares an EMPTY scope and
+# the façade silently stops firing — the exact failure this leaf exists to end.
+dispatch_init "RULES" 'core/*' 'packs/*' 'schemas/*' 'src/*' 'registry.json' 'dispatch/*' 'audits/*' '.githooks/*' 'AGENTS.md' 'AGENTS.orly.md'
+dispatch_resolve_files "$@"
+dispatch_header
+
+# ── deterministic gates ────────────────────────────────────────────
+# Rule prose carries no milestone ids — the packs say so themselves ("never a
+# memory file, never a milestone cite"), and until now nothing read the corpus
+# for them. Same leaf write_any already wires, so no new code enters the gloss.
+dispatch_run_helper "MSID" "msid-ui.sh" "--staged"
+
+dispatch_verdict

package/dispatch/write_any.md

@@ -736,6 +736,34 @@ Every triggered consult is logged in the active spec's **Discovery** section, or
 
 NLR is the cleanup-on-touch arm; NLG bans new legacy framing pre-v2.0.0; this guard covers the harder judgment calls ("should this whole subsystem exist") that need the user's input.
 
+## Porting a codebase between languages (RULE PORT)
+
+> [JUDGMENT → NEW:PORT]
+
+A port is a REWRITE with a conformance test, never a transliteration.
+
+Before porting a construct, ask what it was working AROUND, not what it was.
+A thread with a stop flag is usually the absence of async. A registration map
+with generation counters is usually the absence of structured cancellation. A
+defer chain is usually the absence of ownership. Port the GUARANTEE; delete the
+workaround, and write down which guarantee replaced it.
+
+Every construct carried over needs one sentence: "kept because <the target
+language has no better mechanism>". If that sentence cannot be written
+honestly, it is transliteration.
+
+Conformance is on OBSERVABLE behaviour — wire bytes, rows, status codes, money,
+exit codes. Never on internal shape. A test that pins internal shape freezes
+the source language's debt into the target.
+
+Read the reference implementations the spec names before designing. Take the
+SHAPE and reject the specifics.
+
+Name the tech debt you are NOT carrying over, and where it went.
+
+A milestone titled "parity" means behavioural parity. It never licenses a
+one-to-one file, type, or thread mapping.
+
 ## Comment Voice — New to the Codebase, Familiar with the Goal
 
 > [JUDGMENT → NEW:CMT]

package/dispatch/write_go.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/dispatch/write_mdx.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/dispatch/write_python.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/dispatch/write_rust.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.

package/dispatch/write_shell.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/docs/EXECUTE_DOC_READS.md

@@ -10,10 +10,13 @@ Every triggered document requires one `📖 DOC READ: <path>` proof-line **per t
 | `core/**`, `packs/**`, `schemas/**`, `src/**`, `registry.json`, agent-home instruction links, repository rules synchronization, or governance hooks | `dispatch/edit_rules.md` + `docs/ORLY_ARCHITECTURE.md` — canonical sources, profiles, snapshots, refusal boundaries, and evidence. | <!-- oracle-packs:workflow.governance -->
 | Lifecycle stage transition (CHORE(open)/PLAN/CHORE(close)/LAND, worktree setup, milestone bootstrap) | `dispatch/lifecycle.md` — the entered stage's runbook section only (section-scan; fires on the transition itself, not on an Edit/Write). |
 | Any source file (cross-cutting authoring) | `dispatch/write_any.md` — length, logging, milestone-id, error-registry, UFS, greptile read, legacy-workaround family. |
+| Porting a codebase, module, or subsystem from another language | `dispatch/write_any.md` §Porting a codebase between languages — a port is a rewrite with a conformance test: port the guarantee, delete the workaround, conform on observable behaviour, name the debt not carried over. |
 | Spec's "Applicable Rules" | Each rule (canonical). Missing → the cross-cutting codes of `dispatch/write_any.md` are the floor; surface omission. |
 | `*.zig` | `dispatch/write_zig.md`. ZIG GATE per edit. |
 | `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `dispatch/write_ts_adhere_bun.md` — TS FILE SHAPE DECISION (§1) at PLAN, const/import/Bun-primitive discipline, anti-patterns. |
 | `*.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 -->
+| 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. |
 | `*.mdx` | `dispatch/write_mdx.md` — structure, front matter, links, code fences, accessibility, and Mintlify isolation. | <!-- oracle-packs:language.mdx -->

package/docs/RULE_ENFORCEMENT.md

@@ -13,8 +13,8 @@ regenerates this file and fails on any difference. To update it, run
 | `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** | | | | **26/281** | |
 
 ## 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.6.9",
   "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"