@agentsfleet/orly 0.6.6 → 0.6.8

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/ufs.sh

@@ -343,48 +343,57 @@ done < <(awk -v re="$NUMERIC_RE" '
 ' "${FILES[@]}")
 
 # ── 3. cross-runtime-orphan ─────────────────────────────────────────────────
-# Full-codebase ERR_* parity check. Scoped to ERR_* prefix because that's
-# the cross-runtime contract surface (server error codes consumed by
-# clients). Server (Zig) is the source of truth — every JS/TS ERR_* must
-# have a matching Zig pub const ERR_*. Zig-only ERR_* consts are fine
-# (server-internal codes don't need a client mirror).
+# Full-tree ERR_* parity. Scoped to the ERR_* prefix because that is the
+# cross-runtime contract surface — server error codes a client consumes. Zig is
+# the source of truth: every client-side ERR_* must have a matching Zig
+# `pub const ERR_*`. Zig-only codes are fine; a server-internal code needs no
+# client mirror.
 #
-# Scans the *working tree* via `git ls-files` — sees staged content even
-# before it lands in HEAD, closing the previous diff-mode blindspot where
-# a fix staged in pre-commit couldn't satisfy a check that only read
-# committed history.
+# Scoped BY RUNTIME, not by one repository's directory names. The previous form
+# globbed `src/*.zig`, `agentsfleet/src/*.{js,jsx,ts,tsx}` and
+# `ui/packages/*/src/*.ts{,x}` — one repository's layout inside a gate every
+# repository receives, and it aged exactly as badly as that implies.
+# `agentsfleet/src/` stopped existing, so the JavaScript half globbed ZERO
+# files and "every JS ERR_* has a Zig twin" passed by scanning nothing, while
+# three real codes one directory over went uncompared. A check aimed at a path
+# that resolves to nothing is the same silent green this audit exists to catch.
 #
-# Perf (M70): batched `xargs grep` (single process across all files)
-# instead of `xargs -I{} grep` (one process per file). On agentsfleet the
-# server-side scan dropped from ~30s to <2s.
+# Zig is the source of truth WHERE ZIG EXISTS. A repository with no Zig has
+# nothing to compare against, so the check reports that it skipped rather than
+# passing vacuously — and, more to the point, does not turn every error code in
+# a pure-TypeScript repository into an orphan the moment the globs get fixed.
+#
+# Perf (M70): batched `xargs grep` (single process across all files) instead of
+# `xargs -I{} grep` (one process per file). The server-side scan dropped from
+# ~30s to <2s on a 1000-file Zig tree; scoping by runtime keeps that shape.
 
-zig_err=$(git ls-files -z -- 'src/*.zig' 2>/dev/null \
-  | { grep -zvE '_test\.zig$|^src/zbench_fixtures\.zig$' || true; } \
-  | xargs -0 grep -hE '^pub const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
-  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+# Test and fixture trees are excluded DIRECTORY-shaped, not by `.test.` infix
+# alone. `cli/test/acceptance/fixtures/install-negatives-ops.ts` declares codes
+# that are INPUTS to a negative test — an infix-only filter walked straight
+# past it and would have reported two fixtures as production orphans.
+PARITY_EXCLUDE='(^|/)(test|tests|__tests__|fixtures)/|_test\.zig$|\.test\.|\.spec\.|(^|/)node_modules/|^vendor/|^third_party/|^src/zbench_fixtures\.zig$'
 
-js_err=$(git ls-files -z -- 'agentsfleet/src/*.js' 'agentsfleet/src/*.jsx' 'agentsfleet/src/*.ts' 'agentsfleet/src/*.tsx' 2>/dev/null \
-  | { grep -zvE '\.test\.|\.spec\.' || true; } \
-  | xargs -0 grep -hE '^export const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
-  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+parity_codes() {
+  local declaration="$1"; shift
+  git ls-files -z -- "$@" 2>/dev/null \
+    | { grep -zvE "$PARITY_EXCLUDE" || true; } \
+    | { xargs -0 grep -hE "$declaration" 2>/dev/null || true; } \
+    | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true
+}
 
-ui_err=$(git ls-files -z -- 'ui/packages/*/src/*.ts' 'ui/packages/*/src/*.tsx' 2>/dev/null \
-  | { grep -zvE '\.test\.|\.spec\.' || true; } \
-  | xargs -0 grep -hE '^export const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
-  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+zig_err=$(parity_codes '^pub const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' '*.zig')
+client_err=$(parity_codes '^export const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' '*.js' '*.jsx' '*.ts' '*.tsx')
 
-# Every JS ERR_* must exist in Zig.
-for c in $js_err; do
-  if ! echo "$zig_err" | grep -qx "$c"; then
-    record "cross-runtime-orphan $c absent-in-zig"
-  fi
-done
-# Every TS (UI) ERR_* must exist in Zig.
-for c in $ui_err; do
-  if ! echo "$zig_err" | grep -qx "$c"; then
-    record "cross-runtime-orphan $c absent-in-zig"
-  fi
-done
+if [ -z "$zig_err" ]; then
+  ok "audit-ufs: cross-runtime parity skipped — no Zig ERR_* declared, so this repository has no source of truth to compare against"
+else
+  # Every client-side ERR_* must exist in Zig.
+  for c in $client_err; do
+    if ! echo "$zig_err" | grep -qx "$c"; then
+      record "cross-runtime-orphan $c absent-in-zig"
+    fi
+  done
+fi
 
 # ── Report ──────────────────────────────────────────────────────────────────
 

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/write_any.md

@@ -348,7 +348,7 @@ ERROR REGISTRY GATE: <file>
 <!-- oracle-packs:start product.agentsfleet -->
 In this repository those surfaces are `src/` (Zig), `rustd/crates/*/src/` (Rust), `cli/src/` and `ui/packages/*/{src,app,lib,components,pages,tests}/` (TypeScript).
 
-`agentsfleet/src/` and `agentsfleet/test/` were listed here until they stopped existing. A trigger path that resolves to nothing is the same silent green this card's gate exists to prevent — and the identical stale prefix in `ufs.sh`'s cross-runtime parity scan means its JavaScript half reads zero files today.
+`agentsfleet/src/` and `agentsfleet/test/` were listed here until they stopped existing. A trigger path that resolves to nothing is the same silent green this card's gate exists to prevent. The identical stale prefix sat in `ufs.sh`'s cross-runtime parity scan, where it made the JavaScript half read zero files; that scan now derives its runtimes instead of naming directories, so no path in it can go stale again.
 <!-- oracle-packs:end -->
 
 **Override:** `UFS GATE: SKIPPED per user override (reason: ...)` immediately preceding the edit. **User-only**; auto-mode does not cover.
@@ -370,7 +370,7 @@ Three discipline points, all part of RULE UFS:
 
 2. **Semantic numeric literals → named constant.** Numeric literals carrying meaning beyond their digits become named consts even at first use. Includes: conversion factors (powers-of-ten ≥ 1e3 used as multipliers/divisors), thresholds, sub-cent rates, time-unit factors, byte-unit factors, retry caps, sentinel offsets. Bare `1_000_000_000` in `nanos / 1_000_000_000` is a smell — `nanos / NANOS_PER_USD` is the rule.
 
-3. **Cross-runtime parity.** Any constant that exists in more than one runtime (Zig, TS, JS) **must share its identifier verbatim**, modulo case where a language idiom forces it (Zig snake_case → TS/JS SCREAMING_SNAKE is a single-runtime style choice; the *semantic* name is identical). When a literal in runtime A would benefit from a name and a sibling runtime already has that name, reuse it. When introducing a new constant, define it in every runtime that uses the same value, same commit. There is no per-constant carve-out: this applies to every cross-runtime constant, not a curated subset.
+3. **Cross-runtime parity.** Any constant that exists in more than one of the runtimes this repository ships **must share its identifier verbatim**, modulo case where a language idiom forces it (Zig snake_case → TS/JS SCREAMING_SNAKE is a single-runtime style choice; the *semantic* name is identical). When a literal in runtime A would benefit from a name and a sibling runtime already has that name, reuse it. When introducing a new constant, define it in every runtime that uses the same value, same commit. There is no per-constant carve-out: this applies to every cross-runtime constant, not a curated subset.
 
 The gate exists because RULE UFS is otherwise pure self-policing. Without an audit script, an inline literal in a 800-LOC editing session reliably slips past attention.
 
@@ -421,6 +421,8 @@ The previous `--diff` (`BASE...HEAD`) default was retired with M70. The forcing
 
 `--all` is accepted as a back-compat alias for the default. `--diff` is rejected with exit 2 + a pointer to this section.
 
+**Parity scope is derived, not named.** The ERR_* parity scan reads `*.zig` as the source of truth and every other in-scope runtime file as the client side, anywhere in the tree. It used to glob three fixed directories; when one of them stopped existing the glob matched zero files and "every client `ERR_*` has a Zig twin" passed by scanning nothing. Where a repository ships no Zig there is no source of truth, so the check prints that it skipped — a repository with one runtime is not a repository with an orphan in every file. Test and fixture trees are excluded directory-shaped (`test/`, `tests/`, `fixtures/`), because a code declared as the INPUT to a negative test is not a client mirror.
+
 **Languages the leaf reads.** Zig, TypeScript, JavaScript, Rust and Go. The rule is one rule, but each language hides its literals differently, so each gets a lane in `is_source` + the string-dup pass:
 
 | Language | Held out of the count, and why |

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

@@ -25,5 +25,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/package.json

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