chore: enforce concise PR descriptions

.github/pull_request_template.md

@@ -1,91 +1,50 @@
 <!--
 Copyright 2024-2026 The NoKV Authors.
 SPDX-License-Identifier: Apache-2.0
+
+Follow CONTRIBUTING.md#pr-description-format and
+docs/development/pr_review_checklist.md.
+Use a concise English title: <type>: <outcome>.
+Keep every heading, write short plain English paragraphs, and minimize code
+details. Avoid repeated explanations, file-by-file summaries, and pasted diffs.
+If a section does not apply, say so briefly with a reason.
+Every non-merge commit must include a DCO Signed-off-by trailer.
 -->
 
-## Related Issue
+## TLDR
 
-<!--
-Every non-trivial PR should be tied to an existing issue so maintainers can
-review the agreed problem, scope, and design history before reading the diff.
+<!-- One or two sentences: the problem and resulting behavior. -->
 
-Use one of:
-- Closes #issue_number
-- Fixes #issue_number
-- Relates to #issue_number
+## Problem
 
-Small exceptions are allowed for typo-only docs edits, CI/dependency chores,
-release chores, and maintainer-approved emergency fixes. If this PR has no
-issue, explain the exception here.
--->
+<!-- Concrete trigger and current behavior. Link the existing issue using
+Closes #, Fixes #, or Relates to #. Only typo-only docs edits, CI/dependency
+chores, release chores, or maintainer-approved emergency fixes may omit an
+issue; explain the exception here. -->
 
-Closes | Fixes | Relates to #
-
-## Summary
-
--
-
-## Scope
-
-- [ ] This PR changes one logical boundary only.
-- [ ] No unrelated refactor, benchmark, metadata model, Holt layout,
-      object-store, agent interface, or docs change is mixed in.
-- [ ] The linked issue describes the user-visible problem, design decision, or
-      maintenance task this PR resolves.
-- [ ] Any breaking change is intentional and documented.
-- [ ] No compatibility shim, deprecated alias, or forwarding wrapper was added without a removal condition.
-
-## Change Size And Review
-
-- [ ] I checked GitHub's additions plus deletions for this pull request.
-- [ ] If the total is more than 5,000 lines, one core maintainer other than the
-      current-head pusher approved the exact current head commit. The author,
-      bots, non-core reviewers, duplicate reviewers, dismissed reviews, and
-      stale approvals do not count.
-- [ ] This change is still small enough for a focused review; approval count is
-      not being used to justify mixed package or lifecycle boundaries.
-
-## Code Contract (Code Changes Only)
-
-- [ ] Not applicable; this is a docs/config-only change.
-- [ ] Package boundaries follow `docs/development/code_contract.md`.
-- [ ] Shared helpers reuse the standard library or existing repository helpers.
-      New generic helper modules are domain-neutral and tested.
-- [ ] File names and file placement follow the code contract.
-- [ ] New types, interfaces, structs, fields, and functions use domain-specific names.
-- [ ] New errors are in the owning package's `errors.rs` and carry stable error kinds when crossing package boundaries.
-- [ ] New metrics/stats are owned by the package that reports or serves them.
-- [ ] Metadata changes document durability, atomicity, revision-reference
-      lifetime, snapshot/commit/event retention, GC epochs, and fail-closed
-      recovery boundaries.
-- [ ] Placement or routing changes preserve persisted `RootId -> LogicalShardId`
-      affinity, one active writer per shard, owner-epoch fencing, and explicit
-      shard-local atomicity; no split root or cross-shard transaction is implied.
-- [ ] Agent-interface changes keep the transport-free facade and schemas in
-      `nokv-agent`, routing and workflows in `nokv-client`, and the concrete
-      backend plus native full CLI wiring in `nokv`.
-- [ ] User-facing integration guidance orders the native full CLI first, the
-      direct Python SDK second, and the Rust SDK third, and does not present the
-      deprecated `nokv mcp` sidecar as a supported NoKV surface.
-
-## Claims and Evidence
-
-- [ ] User-facing documentation distinguishes current, experimental, and
-      planned capabilities.
-- [ ] Security claims do not treat a Workbench root or Agent scope as tenant
-      authentication or authorization.
-- [ ] Performance claims state the topology, comparison boundary, cache state,
-      run count, and raw-evidence location.
-- [ ] Benchmark-only behavior does not alter product semantics.
+## Consequences
 
-## Validation
+<!-- Why this matters to users or maintainers. -->
+
+## Example
+
+<!-- A short, concrete before/after scenario. Code is optional. -->
 
-<!-- List exact commands and key results. For each relevant check not run,
-explain why. Docs-only changes may mark Rust checks not applicable. -->
+## Solution
 
-- Command and result:
-- Not run (with reason):
+<!-- How the final change solves the problem, in plain English. -->
 
-## Contributor Sign-off
+## Gain
+
+<!-- The resulting benefit. Link evidence for quantified claims. -->
+
+## Tradeoffs
+
+<!-- Relevant costs, limitations, breaking changes, or remaining risks. -->
+
+## Validation
 
-- [ ] Every commit in this PR includes a DCO `Signed-off-by` trailer.
+<!-- List exact commands and key results. Explain relevant checks not run.
+Docs-only changes may mark Rust checks not applicable. Storage/recovery and
+performance claims need raw evidence and applicable acceptance-gate results;
+passing unit tests alone does not qualify those claims. -->

.github/workflows/pr-description-tests.yml

@@ -0,0 +1,22 @@
+# Copyright 2024-2026 The NoKV Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+name: PR Description Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-description-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - name: Test PR description policy
+        run: python3 scripts/ci/pr_description_test.py

.github/workflows/pr-description.yml

@@ -0,0 +1,47 @@
+# Copyright 2024-2026 The NoKV Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+name: PR Description
+
+on:
+  pull_request_target:
+    branches: [main]
+    types: [opened, reopened, synchronize, edited, ready_for_review]
+  workflow_dispatch:
+    inputs:
+      pull_request:
+        description: PR number to recheck against the current protected policy
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: pr-description-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pr-description:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      GH_TOKEN: ${{ github.token }}
+      POLICY_SHA: ${{ github.event.pull_request.base.sha || github.sha }}
+      PR_NUMBER: ${{ github.event.pull_request.number || inputs.pull_request }}
+    steps:
+      # Never check out PR code or interpolate PR titles/bodies into shell code.
+      - name: Validate live PR metadata with the protected base policy
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]]
+          policy="$RUNNER_TEMP/pr_description.py"
+          metadata="$RUNNER_TEMP/pr-description.json"
+          gh api \
+            "repos/$GITHUB_REPOSITORY/contents/scripts/ci/pr_description.py?ref=$POLICY_SHA" \
+            --jq .content | base64 --decode > "$policy"
+          gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" \
+            --jq '{title, body}' > "$metadata"
+          python3 "$policy" --pull-request-json "$metadata"

AGENTS.md

@@ -9,6 +9,31 @@ This repository uses `docs/development/code_contract.md` as the source of truth
 for Rust package boundaries, naming, errors, metrics, tests, DCO, and storage
 safety review.
 
+## PR Writing
+
+Follow the authoritative
+[PR description format](CONTRIBUTING.md#pr-description-format) and
+[pull request template](.github/pull_request_template.md) when creating or
+updating a PR. This is the repository's required format, including for agents.
+
+- Write a concise English title as `<type>: <outcome>`.
+- Use these body headings in order: `TLDR`, `Problem`, `Consequences`,
+  `Example`, `Solution`, `Gain`, `Tradeoffs`, then `Validation`.
+- Use short, plain English paragraphs. Explain the concrete problem, user
+  impact, and before/after behavior with minimal code details. Avoid file-by-file
+  summaries, pasted diffs, repeated explanations, and conversational history.
+- Link the issue under `Problem`; explain any permitted exception there.
+- Report exact validation commands and results, relevant checks not run, and
+  evidence limits. Do not claim unmeasured gains or unverified recovery.
+- Keep every heading; briefly explain when a section does not apply. Refresh
+  the title and body when the final scope changes.
+- Keep DCO sign-offs and all existing engineering and merge requirements.
+- Before opening or editing a PR, run `scripts/ci/pr_description.py` against a
+  JSON object containing its final `title` and `body`, using
+  `--pull-request-json <path>`. The same policy is the required remote
+  `pr-description` check; its regression tests are in
+  `scripts/ci/pr_description_test.py`.
+
 ## Local Collaboration Direction
 
 LingTai is no longer an active partner or a default integration target.

CONTRIBUTING.md

@@ -111,7 +111,8 @@ and run `git diff --check`.
 ## Pull Request Rules
 
 - Rebase on latest `upstream/main` before opening or updating a PR.
-- PR description must include: what changed, why it changed, and how you validated it (commands + key results).
+- Follow the [PR description format](#pr-description-format) and the
+  [pull request template](.github/pull_request_template.md).
 - Link related issue(s).
 - Include docs updates when behavior/config/CLI changes.
 - Keep PRs small enough for focused review.
@@ -131,6 +132,90 @@ and run `git diff --check`.
 - Every non-merge commit must include a `Signed-off-by` trailer matching the Developer Certificate of Origin in [`DCO`](./DCO).
 - If you use Codex or another agent to review a PR, point it at [`docs/development/code_contract.md`](./docs/development/code_contract.md) and [`docs/development/pr_review_checklist.md`](./docs/development/pr_review_checklist.md).
 
+### PR Description Format
+
+Use a concise English title in the form `<type>: <outcome>`. Describe the final
+change for a reviewer who has not read the discussion. Write short, plain
+English paragraphs focused on the problem and observable behavior. Mention
+code, symbols, and file paths only when needed to explain a decision or risk;
+do not turn the description into a file-by-file change log or paste the diff.
+
+Every PR description uses these headings in this order:
+
+| Heading | What to write |
+| --- | --- |
+| `TLDR` | One or two sentences stating the problem and resulting behavior. |
+| `Problem` | The concrete trigger and current behavior. Link the related issue here. |
+| `Consequences` | Why the problem matters to users or maintainers. |
+| `Example` | A short, concrete before/after scenario. Use a code snippet only if it makes the behavior clearer. |
+| `Solution` | How the change solves the problem, in plain English. |
+| `Gain` | The resulting benefit. Quantified claims require linked evidence. |
+| `Tradeoffs` | Relevant costs, limitations, breaking changes, or remaining risks. |
+| `Validation` | Exact commands and key results; explain relevant checks not run and link raw evidence for storage or performance claims. |
+
+Keep all headings. Usually one or two sentences per narrative section are
+enough; validation may use a short list. Do not repeat the same explanation
+across sections or invent benefits, risks, or examples to fill space. If a
+section does not apply, say so briefly with a reason. Update the title and
+description when the final scope changes, and omit abandoned approaches unless
+they explain a remaining tradeoff.
+
+Every non-trivial PR needs an existing issue linked with `Closes`, `Fixes`, or
+`Relates to`. Typo-only docs edits, CI/dependency chores, release chores, and
+maintainer-approved emergency fixes may omit an issue; explain the exception
+under `Problem`.
+
+For example, a documentation-only PR could read:
+
+```markdown
+## TLDR
+Make every PR explain its user impact with the same short structure.
+
+## Problem
+The template and contributor guide ask for different descriptions. Relates to #123.
+
+## Consequences
+Reviewers have to ask follow-up questions to understand the change.
+
+## Example
+Before: a list of edited files. After: a concrete problem and before/after behavior.
+
+## Solution
+Use one description format across the template, contributor guide, and agent instructions.
+
+## Gain
+Authors and reviewers have one clear writing standard.
+
+## Tradeoffs
+Small PRs still keep each heading, with brief answers where appropriate.
+
+## Validation
+
+- git diff --check: passed.
+- Local Markdown links: checked.
+- Rust checks: not applicable; documentation only.
+```
+
+This format does not replace DCO, scope, review, or evidence requirements.
+Use the [PR Review Checklist](docs/development/pr_review_checklist.md) for the
+engineering review; keep the description focused on this PR's behavior and
+validation.
+
+The required `pr-description` check enforces the title structure, exact section
+order, and filled-in content. It ignores HTML comments and does not treat
+headings inside fenced code examples as sections. Bare placeholders such as
+`TODO` or `N/A` fail; explain why a section does not apply. The check reruns on
+PR creation, reopening, pushes, title/body edits, and ready-for-review events.
+Plain English, brevity, factual claims, and relevance still require review.
+
+Run the same policy locally before opening or editing a PR:
+
+```bash
+gh pr view PR_NUMBER --json title,body > /tmp/nokv-pr-description.json
+python3 scripts/ci/pr_description.py --pull-request-json /tmp/nokv-pr-description.json
+python3 scripts/ci/pr_description_test.py
+```
+
 ## Code Guidelines
 
 - Use `rustfmt` formatting and pass `clippy` with warnings denied.

docs/development/change-governance.md

@@ -21,6 +21,9 @@ protection:
 - the current-head pusher cannot supply that approval;
 - unresolved review conversations block merge;
 - administrators are subject to the same restrictions;
+- PR titles and descriptions follow the
+  [required format](../../CONTRIBUTING.md#pr-description-format), enforced by
+  the required `pr-description` check;
 - the branch must be current with `main` and every required status must pass.
 
 GitHub-reported additions plus deletions are the review-size measure. The
@@ -49,6 +52,15 @@ the workflow does not publish a second custom commit status.
 This distinction is required: a normal `pull_request` workflow is part of the
 proposed diff and can otherwise weaken the check that evaluates itself.
 
+[`pr-description.yml`](../../.github/workflows/pr-description.yml) applies the
+same protected-base boundary to PR metadata. It reads the live title and body
+through `gh`, treats them only as data, and fetches the validator from the exact
+base SHA. It reruns on `edited` as well as creation, reopening, pushes, and
+ready-for-review events. A manual dispatch can recheck a PR with the current
+protected policy. Candidate policy regression tests run separately in
+[`pr-description-tests.yml`](../../.github/workflows/pr-description-tests.yml),
+so a skipped candidate job cannot satisfy the metadata check.
+
 The required status set is:
 
 - `nokv-workspace`;
@@ -57,6 +69,11 @@ The required status set is:
 - `signoff`;
 - `large-change-review`.
 
+The PR writing policy additionally requires `pr-description` and
+`pr-description-tests`. Enable the new required checks after the introducing
+PR has merged and the protected workflow is available; then verify the live
+branch-protection settings without removing existing checks.
+
 Every validation job that runs for each pull-request head is required. The
 Docker `image` check is the only CI exception: it continues in the background
 and reports failures, but its runtime does not delay a merge. `sync-project` is

docs/development/code_contract.md

@@ -151,6 +151,20 @@ that owns them. Do not move domain-specific or single-use logic into a generic
   S3-compatible boundary.
 - Prefer explicit invariants and local reasoning over manager-style wrappers.
 
+## PR Communication And DCO
+
+The [contribution guide](../../CONTRIBUTING.md#pr-description-format) owns the
+PR writing format. Use `TLDR`, `Problem`, `Consequences`, `Example`, `Solution`,
+`Gain`, `Tradeoffs`, and `Validation`, in that order, following the
+[template](../../.github/pull_request_template.md). Keep descriptions concise
+and in plain English, with minimal code details and a concrete before/after
+example. Include exact validation results and evidence for storage or
+performance claims; state relevant limits and checks not run.
+
+Every non-merge commit must carry a DCO `Signed-off-by` trailer as required by
+the [contribution guide](../../CONTRIBUTING.md#branch-and-commit-conventions)
+and [DCO](../../DCO).
+
 ## Validation
 
 Before pushing substantial code changes: