v0.6.8 feat: codify pull-request descriptions

.oracle/orly.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "orly_version": "0.6.4",
+  "orly_version": "0.6.8",
   "packs": [
     "universal.authoring",
     "language.zig",

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`.
 

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>
 ```

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.

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`.
 

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.>
+````

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.json

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

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"