@agentsfleet/orly 0.6.7 → 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/AGENTS.md

@@ -144,6 +144,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | write auth-flow / token-minting files | `write_auth` | `dispatch/write_auth.md` — auth invariants; reads the product repo's `docs/AUTH.md` before · 🟣 delegated (product repo). |
 | write published docs / OpenAPI prose | `write_documentation` | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` before narrower guides; page, fragment, API, changelog scopes differ · 🟣 delegated to repository pre-commit checks. |
 | write a changelog entry | `write_changelog` | `dispatch/write_changelog.md` — changelog voice (one headline, no marketing words, `**Bold lead-noun**` bullets, history append-only); reads `docs/CHANGELOG_VOICE.md` · 🤔 judgment-only. |
+| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; review dispositions; commands with real output. |
 | claim "tests pass / ready / shipping" | `verify` | `dispatch/verify.md` — verification tiers (`make` canonical; package-scoped runners are **not** verification), done-message glyph format · 🤔 judgment-only, `VERIFY GATE: <target> skipped per environment constraint (reason: ...)` only when genuinely unrunnable. |
 | name a stream/channel/Redis namespace/queue/RPC/Postgres schema, or describe a flow | `name_architecture` | `dispatch/name_architecture.md` — architecture-consult discipline; grep relevant `docs/architecture/` (chat brainstorming counts) · **no override** — doc wins until reconciled. |
 | run a lifecycle stage (open→close a stream, worktree setup, milestone bootstrap) | `lifecycle` | `dispatch/lifecycle.md` — stage runbooks: CHORE(open/close) checklists, PLAN expansions, spec discipline, deferral format, pre-PR gates, LAND · 🤔 judgment-only. |
@@ -240,7 +241,7 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 
 **PR budget — one per milestone.** One ready PR plus one follow-up is the ceiling. Fold new scope into the open PR (reopen `done/`→`active/` if needed), not a third.
 
-**Required outputs** — full checklist in `dispatch/lifecycle.md`: all Dimensions/Sections `DONE` (`IN_PROGRESS` if parked) · spec → `docs/v*/done/` iff complete · new changelog `<Update>` **and** the affected `~/Projects/docs/` pages revised · `docs/architecture/**` diff or Session-Notes why-not · PR `## Session notes` (decisions, deferrals, skill + babysit outcomes) · orphan sweep (RULE ORP) · ephemeral `HANDOFF*` docs deleted · `git status -uall` audit, **empty post-commit** before the PR · version sync (`make check-version` passes).
+**Required outputs** — full checklist in `dispatch/lifecycle.md`: all Dimensions/Sections `DONE` (`IN_PROGRESS` if parked) · spec → `docs/v*/done/` iff complete · new changelog `<Update>` **and** the affected `~/Projects/docs/` pages revised · `docs/architecture/**` diff or Session-Notes why-not · PR body per `dispatch/write_pr_description.md` · orphan sweep (RULE ORP) · ephemeral `HANDOFF*` docs deleted · `git status -uall` audit, **empty post-commit** before the PR · version sync (`make check-version` passes).
 
 **Deferral discipline.** A "deferred to follow-up" claim requires an **user-acked verbatim quote** in PR Session Notes (or spec Discovery); agent-unilateral deferral = incomplete scope, not deferral — CHORE(close) blocks until the item lands or the quote is captured. Quote format + HANDOFF faithfulness: `dispatch/lifecycle.md`.
 

package/audits/agents-md.md

@@ -269,7 +269,7 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 
 This scenario exists because the most likely failure of the operating model is
 not a missing rule — it's the *agent misreading a rule that is present*.
-AGENTS.md is ~32 KB of table-dense, exception-laden prose (SOUL.md inlined); the conditions
+AGENTS.md is byte-capped, table-dense prose (SOUL.md inlined); the conditions
 below are where an LLM reading it tends to drift, conflate, or confabulate.
 The questions force *proof of reading* over *recall*.
 
@@ -366,6 +366,18 @@ than only the one with a Read hook.
 | 28.3 | Does the DOC READ GATE require recording each triggered read with `bash audits/doc-read.sh log <path>` — runnable in every runtime, automatic in Claude Code via the `PostToolUse` Read hook — with `.githooks/pre-commit` comparing the record against the staged diff? | YES |
 | 28.4 | When no read record exists (a runtime without hook support, before the command is run), does `audits/doc-read.sh check` warn 🟠 and exit 0 rather than red — because a check that fires where it cannot work teaches people to ignore it? | YES |
 
+### Scenario 29 — Pull-request and merge-request descriptions
+
+Pull Request (PR) and Merge Request (MR) bodies use the same shape on both
+forges.
+
+| # | Question | Expected |
+|---|---|---|
+| 29.1 | Does writing or updating a PR/MR body through either `gh` or `glab` route to `dispatch/write_pr_description.md`? | YES |
+| 29.2 | Must each working session re-read the forge body, append the highest numbered `## Session notes <N>` plus one followed by `## Review` and `## Make`, and preserve every earlier unit? | YES |
+| 29.3 | Does the façade require two or three outcome-first prose lines, useful fenced ASCII diagrams at most 78 columns using measured values, P0/P1/P2 review dispositions, and commands paired with actual output? | YES |
+| 29.4 | Must clean review say `No findings.`, skipped review and verification name why, and unverified claims identify what would verify them? | YES |
+
 ## Comprehension layer
 
 The deterministic audit proves the rules are *present*; it cannot prove an
@@ -457,6 +469,8 @@ Scenario verdicts:
 | 25 | Allocator and concurrency discipline    | <N/M YES>       |
 | 26 | Rules propagation                       | <N/M YES>       |
 | 27 | Rule-path residence and reachability    | <N/M YES>       |
+| 28 | Rule-enforcement ledger and doc reads   | <N/M YES>       |
+| 29 | PR and MR descriptions                  | <N/M YES>       |
 
 OVERALL: PASS | FAIL — <reason if fail>
 ```

package/audits/data.sh

@@ -45,7 +45,7 @@ REQUIRED_DISPATCH=(
   "write_spec" "write_http" "write_auth" "write_changelog"
   "write_documentation" "verify" "name_architecture" "edit_rules"
   "write_rust" "write_go" "write_python" "write_shell" "write_mdx"
-  "lifecycle"
+  "write_pr_description" "lifecycle"
 )
 
 # Check 2 — every source/config language has at least one mention.
@@ -105,6 +105,7 @@ DOTFILES_RESIDENT=(
   "dispatch/write_auth.md"
   "dispatch/write_changelog.md"
   "dispatch/write_documentation.md"
+  "dispatch/write_pr_description.md"
   "dispatch/verify.md"
   "dispatch/name_architecture.md"
   "dispatch/edit_rules.md"
@@ -169,6 +170,7 @@ NAMED_SCENARIOS=(
   "Rules propagation"        # Scenario 26
   "Rule-path"                # Scenario 27
   "Rule-enforcement ledger"  # Scenario 28
+  "Pull-request and merge-request descriptions"  # Scenario 29
 )
 
 # Check 14 — the Rule-extension protocol must enumerate all four wiring steps.

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/core/operating-model.md

@@ -148,6 +148,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | write auth-flow / token-minting files | `write_auth` | `dispatch/write_auth.md` — auth invariants; reads the product repo's `docs/AUTH.md` before · 🟣 delegated (product repo). | <!-- oracle-packs:domain.auth -->
 | write published docs / OpenAPI prose | `write_documentation` | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` before narrower guides; page, fragment, API, changelog scopes differ · 🟣 delegated to repository pre-commit checks. | <!-- oracle-packs:domain.documentation -->
 | write a changelog entry | `write_changelog` | `dispatch/write_changelog.md` — changelog voice (one headline, no marketing words, `**Bold lead-noun**` bullets, history append-only); reads `docs/CHANGELOG_VOICE.md` · 🤔 judgment-only. | <!-- oracle-packs:domain.changelog -->
+| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; review dispositions; commands with real output. | <!-- oracle-packs:universal.authoring -->
 | claim "tests pass / ready / shipping" | `verify` | `dispatch/verify.md` — verification tiers (`make` canonical; package-scoped runners are **not** verification), done-message glyph format · 🤔 judgment-only, `VERIFY GATE: <target> skipped per environment constraint (reason: ...)` only when genuinely unrunnable. | <!-- oracle-packs:product.agentsfleet -->
 | name a stream/channel/Redis namespace/queue/RPC/Postgres schema, or describe a flow | `name_architecture` | `dispatch/name_architecture.md` — architecture-consult discipline; grep relevant `docs/architecture/` (chat brainstorming counts) · **no override** — doc wins until reconciled. | <!-- oracle-packs:universal.authoring -->
 | run a lifecycle stage (open→close a stream, worktree setup, milestone bootstrap) | `lifecycle` | `dispatch/lifecycle.md` — stage runbooks: CHORE(open/close) checklists, PLAN expansions, spec discipline, deferral format, pre-PR gates, LAND · 🤔 judgment-only. |
@@ -255,7 +256,7 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 
 **PR budget — one per milestone.** One ready PR plus one follow-up is the ceiling. Fold new scope into the open PR (reopen `done/`→`active/` if needed), not a third.
 
-**Required outputs** — full checklist in `dispatch/lifecycle.md`: all Dimensions/Sections `DONE` (`IN_PROGRESS` if parked) · spec → `docs/v*/done/` iff complete · new changelog `<Update>` **and** the affected `~/Projects/docs/` pages revised · `docs/architecture/**` diff or Session-Notes why-not · PR `## Session notes` (decisions, deferrals, skill + babysit outcomes) · orphan sweep (RULE ORP) · ephemeral `HANDOFF*` docs deleted · `git status -uall` audit, **empty post-commit** before the PR · version sync (`make check-version` passes).
+**Required outputs** — full checklist in `dispatch/lifecycle.md`: all Dimensions/Sections `DONE` (`IN_PROGRESS` if parked) · spec → `docs/v*/done/` iff complete · new changelog `<Update>` **and** the affected `~/Projects/docs/` pages revised · `docs/architecture/**` diff or Session-Notes why-not · PR body per `dispatch/write_pr_description.md` · orphan sweep (RULE ORP) · ephemeral `HANDOFF*` docs deleted · `git status -uall` audit, **empty post-commit** before the PR · version sync (`make check-version` passes).
 
 **Deferral discipline.** A "deferred to follow-up" claim requires an **user-acked verbatim quote** in PR Session Notes (or spec Discovery); agent-unilateral deferral = incomplete scope, not deferral — CHORE(close) blocks until the item lands or the quote is captured. Quote format + HANDOFF faithfulness: `dispatch/lifecycle.md`.
 

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_pr_description.md

@@ -0,0 +1,152 @@
+# Pull-request and merge-request description dispatch
+
+Read this file before writing or updating a Pull Request (PR) or Merge Request
+(MR) body, including an update that only appends session notes. It governs
+GitHub and GitLab equally.
+
+## Trigger
+
+This dispatch fires before any forge command or API call that creates or changes
+a PR or MR body. This includes `gh pr create`, `gh pr edit --body`,
+`glab mr create`, and `glab mr update --description`. A helper, skill, or script
+that writes the body fires the same rule.
+
+## Append unit and sequence
+
+Append exactly one complete unit per working session that touches the PR or MR,
+after review and verification have finished:
+
+1. `## Session notes <N>`
+2. `## Review`
+3. `## Make`
+
+Read the complete existing body before composing the unit. Find every heading
+that exactly matches `## Session notes <integer>`. Use 1 when none exists;
+otherwise use the highest integer plus 1. Re-read the body immediately before
+the write and recompute the number if another session appended meanwhile. The
+forge body is the source of truth; chat, a local draft, and commit count are not.
+
+Append the unit once, preserving every earlier numbered unit. Never renumber,
+rewrite, reorder, or consolidate earlier units. Build the complete unit locally
+and make one body update so Review and Make cannot be mistaken for missing.
+
+For GitHub, read with `gh pr view --json body --jq .body` and write with
+`gh pr edit --body` or `--body-file`. For GitLab, read with
+`glab mr view --output json --jq .description` and write with
+`glab mr update --description`. Preserve all body content that precedes the
+first numbered unit.
+
+## Session notes <N>
+
+Start with two or three lines of plain prose, never more. Lead with what was
+fixed. Include decisions and open deferrals that the next agent needs. Do not
+add a preamble or restate the ticket.
+
+Follow with a pictorial explanation using American Standard Code for
+Information Interchange (ASCII) diagrams in fenced code blocks. The picture is
+the substance when it can show a before/after, topology, proportion, measured
+scale, or broken flow more clearly than a sentence. Use the sentence when it is
+clearer. Never draw a box that merely repeats its caption.
+
+Every diagram must:
+
+- stay at or below 78 columns, including indentation;
+- be inside a fence so both forges render it monospaced;
+- label axes and units where they exist;
+- use measured values copied from real command output, never illustrative
+  values.
+
+These are real examples from a test-hardening PR. Copy their register, never
+their numbers:
+
+```text
+   BEFORE                              AFTER
+   ┌──────────────────────────┐        ┌──────────────────────────┐
+   │ 671 tests  ........ PASS │        │ 671 tests  ........ PASS │
+   │   incl. all 5 properties │        │ scope property ... FAIL ✓│
+   └──────────────────────────┘        └──────────────────────────┘
+     a live cross-tenant read            the mutant is caught
+     ships green
+```
+
+```text
+   compiler accepts 16 keys        generator emitted 8
+   ┌────────────────────────────────────────────────┐
+   │████████████████░░░░░░░░░░░░░░░░│  BEFORE  50%   │
+   └────────────────────────────────────────────────┘
+```
+
+```text
+   0.001ms      0.01      0.1        1         10        100
+   ├────────────┼─────────┼──────────┼─────────┼──────────┤
+        ▲                  ▲          ▲            ▲
+    cache HIT          NEW budget  OLD budget   cache MISS
+   0.003-0.005ms        0.1ms        1.0ms      12-21ms
+```
+
+## Review
+
+Lead with the review result. Record every finding with P0, P1, or P2 severity,
+the file and line, the defect, and its disposition. Use `FIXED` or `DEFERRED`;
+a deferral also needs the user acknowledgement required by the lifecycle rule.
+
+```text
+P0  oql_property_tests.rs:86  tenant-scope property asserted absence only —
+                              passed with the scope clause deleted.  FIXED
+P1  query_load_test.rs:183    only assertion was arithmetic, green at any
+                              latency.  FIXED
+P2  grpc_auth_test.rs:33      constant re-typed instead of imported.  DEFERRED
+```
+
+Write `No findings.` when review ran and found none. If review did not run,
+write `Review not run — <reason>.` A missing heading never means clean.
+
+## Make
+
+Lead with the verification state. List each command actually run with its exit
+status and decisive output line. Use measured counts and baselines from that
+run; never replace output with “tests pass.”
+
+```text
+make test              exit 0   860 passed; 0 failed   (baseline 846, +14)
+cargo clippy --all-targets -- -D warnings   exit 0
+make harness-verify    All checks passed!
+gitleaks               no leaks found, 54 commits scanned
+```
+
+For every command that could not run, name the command and the reason. Label
+the evidence source when it is not Continuous Integration (CI), such as
+`local — real stack`. Include the review skill and `orly-babysit-prs` command
+outcomes here; if either could not run, name why. Never present a local run as
+a green pipeline.
+
+## Whole-body rules
+
+- Every factual claim traces to an actual command output line in Make or to a
+  command-named measurement in the diagram. State unchecked facts as
+  `Unverified: <fact> — <what would verify it>`.
+- Lead with the answer in each section. Put reasoning after it and detail last.
+- Use no marketing adjectives, throat-clearing opener, or closing paragraph
+  that repeats the body.
+- Write for the next agent first: branch state, decisions, and open work must
+  be findable without reconstructing the session.
+
+## Complete template
+
+````markdown
+## Session notes <N>
+
+<Outcome in two or three lines, backed by the evidence below.>
+
+```text
+<Useful measured diagram, at most 78 columns.>
+```
+
+## Review
+
+<P0/P1/P2 entries with dispositions, No findings., or not-run reason.>
+
+## Make
+
+<Commands paired with exit status and decisive real output lines.>
+````

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 -->
@@ -25,5 +28,6 @@ Every triggered document requires one `📖 DOC READ: <path>` proof-line **per t
 | Auth-flow | `docs/AUTH.md`. |
 | Published `*.mdx`, reusable Markdown JSX (MDX) fragment, customer readme, or public OpenAPI prose | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` — establish page, fragment, API, or changelog scope before narrower guides. |
 | Changelog `<Update>` / release note (`changelog.mdx`) | First `dispatch/write_documentation.md`, then `dispatch/write_changelog.md` → `docs/CHANGELOG_VOICE.md`; internal-only ⇒ no entry. |
+| Write or update a PR/MR body, including session notes (`gh pr create/edit --body`, `glab mr create/update --description`, forge API, helper, or skill) | `dispatch/write_pr_description.md` — append-only numbered session unit, measured diagram, review findings, and command output. |
 | `schema/*.sql` / migration | `dispatch/write_sql.md` + `docs/SCHEMA_CONVENTIONS.md` — naming/type conventions, schema/migration rules + Schema Table Removal Guard. Re-print Schema Guard output. |
 | Any spec under `docs/v*/{pending,active,done}/` or `docs/TEMPLATE.md` | `docs/TEMPLATE.md` "Prohibited" section — no time/effort estimates, no complexity ratings, no percentage-complete, no owners/dates. SPEC TEMPLATE GATE per edit. |

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.7",
+  "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

@@ -32,6 +32,10 @@
           "source": "dispatch/name_architecture.md",
           "target": "dispatch/name_architecture.md"
         },
+        {
+          "source": "dispatch/write_pr_description.md",
+          "target": "dispatch/write_pr_description.md"
+        },
         {
           "source": "audits/ufs.sh",
           "target": "audits/ufs.sh"
@@ -259,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"