pr Body Merge Instructions

# Merging the Brutal Honesty §4 block into your existing PR template

## When to use this vs. the full template

- **No existing `.github/PULL_REQUEST_TEMPLATE.md`** → use the full template:
  `cp templates/pr-body.md.template .github/PULL_REQUEST_TEMPLATE.md`. That
  template includes `## Summary`, `## Test plan`, and the §4 block in one
  document and is the greenfield path.
- **Existing `.github/PULL_REQUEST_TEMPLATE.md`** (you have Quality
  Checklists, type-of-change taxonomies, validation commands, route-update
  reminders, etc. you want to keep) → use this merge pattern with
  `templates/pr-body-merge-snippet.md`. That snippet supplies only the §4
  fields, so your existing content survives.

The choice is symmetric with the CLAUDE.md pattern: full snippet for a
greenfield repo, merge snippet for one that already has its own
conventions.

## Where to put it

At the BOTTOM of your existing template, below an `---` horizontal rule.

The kit's §4 block is the LAST section because it depends on the rest of
the PR body being filled in first (EVIDENCE references the runtime
evidence produced by the work described above; LOOP_IMPL_ITERATIONS
references the test plan above). Pasting it at the top would force authors to fill
in BHS lines before they know what they did.

Example final layout of your `.github/PULL_REQUEST_TEMPLATE.md`:

    ## Summary
    <your repo's existing summary template>

    ## Test plan
    - [ ] <your repo's existing checklist>

    ## Quality checklist
    - [ ] <your repo's existing items>

    ---  <!-- HR separates your sections from the kit's -->

    ## Brutal Honesty (rulebook v3.7.1 §4)
    <paste the snippet body here>

The HR is the visual separator AND a hint to authors: everything below
is parsed by `validate_pr_brutal_honesty.py` and cannot be paraphrased.

## Conflict resolution if you already have a brutal-honesty section

Replace it. Do not partially edit. The v3.7.1 §4 block is one atomic unit
and partial edits drift the doc out of sync with the rulebook — which is
itself L4 partial-with-claim-of-complete (claiming "we follow v3.7.1" when
the template is an older hybrid).

Search for any existing field-style lines (`BHS_SELF_DRAFT:`,
`BHS_TIER_B:`, `BHS_OFFICIAL:`, `EVIDENCE:`, `SMOKE:`) and delete them
before pasting. Hybrid templates fail validation in worse ways than no
template, because `validate_pr_brutal_honesty.py` parses the first
matching line — a stale v3.2 line will satisfy the regex while encoding a
v3.2 contract, and the validator cannot tell which line is the "real"
one.

## After pasting

1. Run a synthetic PR-body validation to confirm the merged template
   parses without "missing field" errors:

       ```bash
       python scripts/validate_pr_brutal_honesty.py --body .github/PULL_REQUEST_TEMPLATE.md
       ```

   Expected: the validator either passes or reports specific field-value
   failures (e.g. `<placeholder>` still in the value, or score parse
   failures because the template hints are not numbers). It must NOT
   report `missing required field` for any field name — every required
   field name must be PRESENT in the merged template, even if the values
   are still placeholders for adopter-filled content.

2. Open your next PR and verify the §4 block appears in the PR body
   (GitHub's "Edit description" UI shows the template at creation time).
   If the section is missing from the rendered template, check that you
   pasted below the `---` and not inside a fenced code block — fenced
   blocks render as text and break the validator's line-by-line parse.

## What NOT to do

- **Do not paraphrase the field names.** `BHS_SELF_DRAFT`, `BHS_TIER_B`,
  `BHS_OFFICIAL`, `EVIDENCE`, `SMOKE`, etc. are exact tokens the
  validator greps for. Renaming them silently fails validation in a way
  that looks like the validator is broken; it is not — the field is
  missing.

- **Do not move the snippet to a separate file** linked from the PR
  template. GitHub does not interpolate file links into the PR body; the
  §4 block must be inline. The whole point of the merge-not-clobber
  pattern is that the §4 fields live in the same file as the rest of
  your template.

- **Do not "summarize for brevity."** A summary that drops the lie
  taxonomy reference (`L16`, `Other L1-L16`), the operator-override
  clause, or any required field is not v3.7.1; it is your own custom
  convention with v3.7.1 branding, which is itself a §1 L4 violation.

- **Do not delete `v3.5/templates/pr-body.md.template`** from the kit.
  It remains the greenfield install path for adopters with no existing
  PR template. The merge snippet is a sibling artifact, not a
  replacement.