docs: require approval and end-to-end evidence

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -55,6 +55,19 @@ body:
       label: Screenshots (optional)
       description: Drag and drop screenshots here if applicable.
 
+  - type: markdown
+    attributes:
+      value: |
+        ### Before implementing a fix
+
+        If you want to implement a fix, comment on the issue with your proposed approach after submitting
+        it. Wait for a maintainer to approve the approach and assign the issue to you before writing code
+        or opening a pull request, including a draft.
+
+        If nobody responds within seven days, leave one polite follow-up and @mention the maintainers or
+        contributors already involved in the issue. People may have missed the original notification, so
+        a reminder is welcome. No response does not count as approval.
+
   - type: checkboxes
     id: checklist
     attributes:
@@ -62,3 +75,5 @@ body:
       options:
         - label: I've searched existing issues and this hasn't been reported yet.
           required: true
+        - label: If I implement this fix, I will wait for maintainer approval and assignment before writing code or opening a pull request.
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -36,6 +36,19 @@ body:
     validations:
       required: true
 
+  - type: markdown
+    attributes:
+      value: |
+        ### Before implementing this request
+
+        If you want to implement this request, comment on the issue with your proposed approach after
+        submitting it. Wait for a maintainer to approve the approach and assign the issue to you before
+        writing code or opening a pull request, including a draft.
+
+        If nobody responds within seven days, leave one polite follow-up and @mention the maintainers
+        or contributors already involved in the issue. People may have missed the original notification,
+        so a reminder is welcome. No response does not count as approval.
+
   - type: checkboxes
     id: checklist
     attributes:
@@ -43,3 +56,5 @@ body:
       options:
         - label: I've searched existing issues and this hasn't been requested yet.
           required: true
+        - label: If I implement this, I will wait for maintainer approval and assignment before writing code or opening a pull request.
+          required: true

.github/pull_request_template.md

@@ -1,10 +1,13 @@
 > [!IMPORTANT]
-> Ready-for-review PRs must satisfy every applicable section below. Incomplete submissions are closed
+> Before writing code or opening a PR, including a draft, discuss your approach in the linked issue
-> without detailed review, and you are welcome to resubmit once complete. Open a draft PR if the work
+> and wait for a maintainer to approve it and assign the issue to you. PRs opened without prior
+> approval and assignment will be closed without review. After approval, open a draft PR if the work
 > is not finished.
 
 Closes #
 
+- **Maintainer approval:** (link to the approval comment)
+- **Assigned contributor:** @
 - **Type:** bug fix | feature | refactor | docs | chore
 - **UI changed:** yes | no
 - **How I ran this:** `pnpm dev` | Docker | I did not run it
@@ -35,12 +38,33 @@ summarize it.
 
 ## Evidence
 
-UI changes require screenshots. Changes to behavior or interaction also require a short recording of
+Upload a recording that proves the changed behavior works in the real client. Show the starting state,
-the complete workflow. Screenshots must show the surrounding browser window rather than a cropped
+the user action, and the final result. If the workflow crosses multiple clients, show the result in
-element, and recordings must start from a page load. For backend changes, paste the log lines your
+each affected client.
-change emits.
 
-<!-- Drag files in here, or write "No UI changes." -->
+Ready-for-review PRs without the required evidence will not be reviewed. Keep the PR in draft until
+the evidence has been uploaded.
+
+Examples:
+
+- **Web:** Start from a page load, perform the affected workflow, and show the saved result after
+  refreshing the page.
+- **KOReader:** Perform the affected workflow inside KOReader and show the result there. For sync
+  changes, also show the corresponding result in BookOrbit.
+- **Kobo:** Perform the affected workflow on the device, run the sync, and show the resulting state on
+  the device and in BookOrbit where applicable.
+- **Scanner, import, or metadata:** Add or modify a real book, run the operation through its normal
+  BookOrbit control, and show the resulting book state in the BookOrbit UI.
+- **Server code used by a client:** Trigger the behavior from that client and show the result in the
+  client. Calling the endpoint directly is not end-to-end evidence.
+
+"No UI changes," written testing claims, automated test output, logs, API requests, database queries,
+and direct service calls are not evidence. They may support the recording but cannot replace it.
+
+Evidence must match the final commit. If the workflow cannot be demonstrated in its real client or
+device, keep the PR in draft and state what remains untested.
+
+<!-- Upload the recording here. -->
 
 ## Authorship and review
 
@@ -58,6 +82,7 @@ AI assistance is welcome on this project; unreviewed AI output is not. See the
 <summary><b>Contributor checklist</b></summary>
 
 - [ ] One focused change, linked above to an issue a maintainer approved
+- [ ] I discussed my approach and was assigned the issue before writing code or opening this PR
 - [ ] I read every line of the final diff
 - [ ] `pnpm verify` passes against the final diff
 - [ ] Tests added or updated per the [testing expectations](https://github.com/bookorbit/bookorbit/blob/main/docs/CONTRIBUTING.md#phase-7-write-and-run-tests)

docs/CONTRIBUTING.md

@@ -44,7 +44,8 @@ This is the end-to-end journey from idea to merged PR. Each phase builds on the
 
 ### Phase 1: Find or Create an Issue
 
-> **Issue first, PR second.** Every pull request must link to an approved issue. PRs without one will be closed.
+> **Issue first, PR second.** Every pull request must link to an approved issue assigned to the
+> contributor. PRs without prior approval and assignment will be closed without review.
 
 - Browse [open issues](../../issues) for something you want to tackle.
 - If you have a new idea, open one using the [bug report](../../issues/new?template=bug_report.yml) or [feature request](../../issues/new?template=feature_request.yml) template.
@@ -52,12 +53,22 @@ This is the end-to-end journey from idea to merged PR. Each phase builds on the
 
 ### Phase 2: Get Maintainer Approval
 
-Wait for explicit approval before writing code. Approval looks like:
+Before writing code, comment on the issue to say that you want to implement it and briefly describe
+your proposed approach. Then wait for both:
 
-- A :+1: reaction on your issue.
+- A maintainer comment explicitly approving the implementation.
-- A comment such as "go ahead", "approved", or "approved to proceed".
+- A maintainer assigning the issue to you.
 
-This step prevents wasted effort on changes that conflict with the project direction. Small bug fixes with clear reproduction are usually approved quickly.
+Do not start implementation or open a pull request, including a draft, until both have happened. A
+reaction or lack of a response does not count as approval.
+
+If nobody responds within seven days, leave one polite follow-up comment and @mention the maintainers
+or contributors already involved in the issue. People have responsibilities outside the project and
+may simply have missed the original notification, so a reminder is welcome. Continue waiting for an
+explicit reply before starting implementation or opening a pull request.
+
+This step prevents wasted effort on changes that conflict with the project direction. Small bug fixes
+with clear reproduction are usually approved quickly.
 
 ### Phase 3: Fork and Clone
 
@@ -183,7 +194,9 @@ git push origin BO-123-your-feature-name
 
 When creating the PR:
 
-- **Fill out the PR template.** It asks for a summary, the commands you ran with their real output, what you did while manually testing, visual evidence for UI changes, and an authorship note covering any AI assistance.
+- **Fill out the PR template.** It asks for the linked approval, a summary, the commands you ran with
+  their real output, what you did while manually testing, end-to-end evidence, and an authorship note
+  covering any AI assistance.
 - **Use a Conventional Commit-style PR title** (for example: `fix(reader): correct page count for multi-volume PDFs`).
 - **Link your issue** with a GitHub closing keyword in the description (`close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`) and an issue reference (`#123` or `owner/repo#123`).
   Example:
@@ -196,8 +209,10 @@ When creating the PR:
   Fixes: #123
   ```
 
-- **Open as a draft** if you want early direction feedback before the code is complete.
+- **Open as a draft** if the implementation is incomplete after the linked issue has been approved and
-- **Attach visual evidence for UI changes.** Include screenshots for every UI change and a short screen recording when behavior or interaction changes. Ready-for-review PRs missing applicable visual evidence will be closed without review and may be resubmitted once complete.
+  assigned. Use the issue for direction before approval.
+- **Attach end-to-end evidence.** Upload a recording showing the changed behavior through the real
+  client. Ready-for-review PRs without the required evidence will not be reviewed.
 - **Disclose AI usage** if applicable. See [AI_POLICY.md](AI_POLICY.md) for the format and expectations.
 
 ### Phase 11: Respond to Review