docs(contributing): add a Human Minimum section and a pull request template (#26375)

<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9REjCZdpYneJCoh3iaxyQGn)_
Part of #26081

Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么：`CONTRIBUTING.md` 新增「Human Minimum」一节(第一个 PR 最容易犯的 8 条规则，每条一句话加指向
AGENTS.md 原文的链接，`Clause-②` 与 `Metadata-protocol` 在用到处定义);新建
`.github/PULL_REQUEST_TEMPLATE.md`,用同一份清单做勾选项，并给出正文骨架和两条声明行。
- 为什么改：执行 #26081 裁决 A 的第二个 PR(裁决 6417533492);人类贡献者进门第一页现在把他们直接送进 82 KB
无目录的 AGENTS.md,PR 时也没有任何清单。
- 风险与回滚：只改文档，不改任何规则、门禁或发布包;回滚即 revert 本
PR。模板里的两条声明行留的是占位值，未填时读作「无声明」,不会替作者默认填 `no`/`none`。
- 先看：`CONTRIBUTING.md` 的 Human Minimum 第 5 条(Clause-② 定义)→
`.github/PULL_REQUEST_TEMPLATE.md` → `CONTRIBUTING.md` 其余三处指针改动。
- 两分钟验证：在本分支上点「New pull request」,正文应自动出现模板;或打开 CONTRIBUTING.md 的 Human
Minimum,逐个点 AGENTS.md 链接，都应落到对应标题。
- 需要你做的：无，席位落地(本 PR 不碰任何受管面)。

## What changes

- `CONTRIBUTING.md` gains a **Human Minimum** section between *Making a
Change* and *Where Things Live*: eight items, each one sentence naming
the rule plus a link to the AGENTS.md heading that states it (Zod first;
naming; no formatter; one issue / branch / PR and worktrees; changeset
with the two declaration lines; regenerate `packages/spec` artifacts;
generated and release-owned files; English artifacts). Item 5 defines
`Clause-②` and `Metadata-protocol` where they are used, as the ruling
asks. No rule text is copied from AGENTS.md; the section says AGENTS.md
text is the rule.
- Three existing CONTRIBUTING.md spots now point at the section: the
intro paragraph, *Making a Change* step 3, and step 5 (which named
`Clause-②` without defining it). *Opening the Pull Request* points at
the new template. The TOC lists the section.
- New `.github/PULL_REQUEST_TEMPLATE.md`: a `Fixes #` first line, What
changes / Why / Verification headings, the two declaration lines with
placeholder values, and the Human Minimum list as checkboxes linking
back to CONTRIBUTING.md.

## Tests

Docs only: no package, test or gate script changes.

## Acceptance notes

- **Template placeholders are not declarations.** Measured with
`scripts/pm/clause2-line.mjs`: an unfilled `Clause-②: yes | no` reads
`malformed` and `Metadata-protocol: added | narrowed | semantic | none`
reads `malformed`, which `check-changeset-no-major.mjs` treats as no
declaration. A template default of `no` / `none` would have declared for
the author, so the template does not ship one.
- **Template binds no closing keyword:** `node
scripts/check-closing-keyword-parity.mjs --body
.github/PULL_REQUEST_TEMPLATE.md` reports no parser binds (3 consulted).
- **Anchors into AGENTS.md are not gated.** `check:doc-anchors` scans
`content/`, `README.md` and `ARCHITECTURE.md` only, and lychee runs with
`include_fragments = "none"`, so the seven AGENTS.md anchors this
section links were checked by hand with `github-slugger@2.0.0` (the
workspace copy): all seven resolve, as do the ten in-file anchors. PR 1
of #26081 (AGENTS.md TOC and `docs/agents/`, Tier H, waiting on #26035)
must keep these headings or update these links.
- **Not done here:** AGENTS.md, CLAUDE.md, `.github/workflows/**` and
`ui/` are untouched. The North Star pointer in CONTRIBUTING.md (the card
cites `CONTRIBUTING.md:69`; it is line 111 on `main` and 114 after this
diff) belongs to #26073 and is unchanged. The cloud#3194 precedent was
read through the ruling and brief comments on #26081 (this session
cannot read the cloud repository).
- Not governed: neither path is in `GOVERNED_SURFACES`
(`scripts/pm/check-governed-merges.mjs`) or CODEOWNERS.

## Verification

Head `891a9b7a`, base `origin/main` `6390fe52`.

<details><summary>dispatch-gates families: 18 derived, 18 run, all exit
0</summary>

`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 18 families for the two paths. Each
ran with its exit captured before any pipe; all 18 exit 0:
`check-aggregator-roster` (+ `--self-test`),
`check-closing-keyword-parity` (+ `--self-test`),
`check-comment-mask-corpus`, `check-step-collectors` (+ `--self-test`),
`docs-audit/check-drift-comment`, `pm/ci-failure --self-test`, and `pnpm
check:` `cross-package-test-inputs`, `driver-memory-census`,
`gitlink-declared`, `nul-bytes`, `pnpm-filter-targets`,
`refd-timer-probe`, `required-contexts`, `shard-attestation`,
`watch-hint-literal`.

`--ran` reconciliation: `18 derived famil(ies) accounted for — 18 run, 0
NOT-MEASURED (a DERIVED zero — all 18 recorded an exit code and none of
them is 3)`.
</details>

<details><summary>Card acceptance commands</summary>

- `pnpm check:pm-governed-prose`: exit 0, `2 instruction surface(s) name
all 13 registered governed surfaces`.
- `node scripts/check-published-list-mirrors.mjs --self-test`: exit 0,
`All 37 self-test cases passed.`; the scan: exit 0.
- Link check: lychee 0.24.2 (the CI pin, built locally) with the exact
`LYCHEE_ARGS` from `check-links.yml`: exit 0, `2900 Total ... 2519 OK 0
Errors 381 Excluded`; both new links to
`.github/PULL_REQUEST_TEMPLATE.md` resolve `[200]`.
- Also run: `pnpm check:doc-authoring`, `pnpm check:doc-anchors` (598
fragment links resolve), `pnpm check:adr-links`, all exit 0.
</details>

---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmQGhbhawhbL2PcHVN8)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+Fixes #
+
+## What changes
+
+## Why
+
+## Verification
+
+Clause-②: yes | no
+Metadata-protocol: added | narrowed | semantic | none
+
+_Keep one value on each of the two lines above, each line starting with its key.
+[Human Minimum](https://github.com/objectstack-ai/objectstack/blob/main/CONTRIBUTING.md#human-minimum)
+item 5 says what they mean._
+
+## Human Minimum
+
+Each item is one rule from
+[CONTRIBUTING.md › Human Minimum](https://github.com/objectstack-ai/objectstack/blob/main/CONTRIBUTING.md#human-minimum),
+which links the AGENTS.md text that states it.
+
+- [ ] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
+- [ ] 2. Every name I added uses the casing for its kind.
+- [ ] 3. No formatter ran; `pnpm lint` passes.
+- [ ] 4. One issue, one branch off an up-to-date `main`, one pull request.
+- [ ] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
+- [ ] 6. `packages/spec` touched: its generated artifacts are regenerated and committed.
+- [ ] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`.
+- [ ] 8. Title, body and comments are in English.
+- [ ] The *Before Submitting* list in CONTRIBUTING.md is done.

CONTRIBUTING.md

@@ -10,13 +10,16 @@ pull request.
 alike.** It holds naming, the Zod-first and contract-first rules, the documentation
 guardrails and the changeset rules. This file does not restate them. Where a rule
 matters, it points you to AGENTS.md, and if the two ever disagree, AGENTS.md wins.
+[Human Minimum](#human-minimum) lists the rules a first pull request most often breaks,
+each with its pointer.
 
 ## 📋 Table of Contents
 
 - [Code of Conduct](#code-of-conduct)
 - [Getting Started](#getting-started)
 - [Build and Test Cost](#build-and-test-cost)
 - [Making a Change](#making-a-change)
+- [Human Minimum](#human-minimum)
 - [Where Things Live](#where-things-live)
 - [Package Directory](#package-directory)
 - [Pull Request Process](#pull-request-process)
@@ -121,7 +124,8 @@ Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`.
    `git worktree` instead of switching branches in a shared tree. AGENTS.md
    (Prime Directive #11 and *Multi-agent working discipline*) explains why, and what
    a worktree does not isolate.
-3. **Make the change, following AGENTS.md.** Read its *Prime Directives* before a
+3. **Make the change, following AGENTS.md.** Start with the
+   [Human Minimum](#human-minimum). Read its *Prime Directives* before a
    structural change, and its *Context Routing* table for the rules of the path you
    are editing.
 4. **Test what your change reaches**, not only the file you edited:
@@ -138,8 +142,50 @@ Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`.
 5. **Add a changeset when the change publishes.** Run `pnpm changeset` and commit the
    `.changeset/*.md` file it writes. A bug fix in a released package takes a `patch`
    changeset. AGENTS.md's *Post-Task Checklist* (step 3) states the whole rule: which
-   bump a change takes, the `Clause-②` declaration, and the migration a breaking
-   change must carry.
+   bump a change takes, the `Clause-②` and `Metadata-protocol` declarations (what they
+   mean: [Human Minimum](#human-minimum), item 5), and the migration a breaking change
+   must carry.
+
+## Human Minimum
+
+The rules a first pull request most often breaks. Each item names the rule in one
+sentence and links the AGENTS.md text that states it; that text is the rule, so read it
+before you rely on the summary. The
+[pull request template](./.github/PULL_REQUEST_TEMPLATE.md) asks you to confirm the
+same list.
+
+1. **Schemas start as Zod, and `packages/spec` holds no runtime logic.** AGENTS.md,
+   [Prime Directives 1 and 2](./AGENTS.md#prime-directives).
+2. **Each kind of name has one casing**: config keys, machine names, error codes,
+   metadata type names, REST paths and `OS_` environment variables. AGENTS.md,
+   [Prime Directives 3 and 9](./AGENTS.md#prime-directives).
+3. **No formatter: `pnpm lint` is the only style authority, and Prettier is never run on
+   a file you touch.** AGENTS.md, [Build & Test](./AGENTS.md#build--test).
+4. **One issue, one branch off an up-to-date `main`, one pull request; in a checkout that
+   coding agents also use, one `git worktree` per task.** AGENTS.md,
+   [Prime Directive 11](./AGENTS.md#prime-directives) and
+   [Multi-agent working discipline](./AGENTS.md#multi-agent-working-discipline) item 2.
+5. **A change that publishes carries a changeset, and the PR body and the changeset body
+   each declare a `Clause-②:` line and a `Metadata-protocol:` line.** AGENTS.md,
+   [Post-Task Checklist](./AGENTS.md#post-task-checklist) step 3, which has the exact
+   values and what each one requires.
+   - `Clause-②` answers one question: does this change widen or narrow what a published
+     package accepts or exposes (its accept set or public surface)? `Clause-②: no` when
+     it does neither; `Clause-②: yes` when it does.
+   - `Metadata-protocol` answers another: what changed in what a metadata author can
+     write? `added`, `narrowed`, `semantic`, or `none` for everything else.
+   - Each is a line of its own, starting with the key, so the `Check Changeset` gate can
+     read it.
+6. **Touched `packages/spec`? Regenerate and commit its generated artifacts before you
+   push.** AGENTS.md,
+   [Touched `packages/spec`?](./AGENTS.md#touched-packagesspec-regenerate-its-artifacts-before-pushing).
+7. **Generated and release-owned files are never hand-edited in your pull request**
+   (`content/docs/references/`, `packages/*/CHANGELOG.md`, `content/docs/releases/`),
+   and only the maintainer cuts a release. AGENTS.md,
+   [Documentation Guardrails](./AGENTS.md#documentation-guardrails) and
+   [Prime Directive 15](./AGENTS.md#prime-directives).
+8. **Issue and pull request titles, bodies and comments are written in English.**
+   AGENTS.md, [Communication](./AGENTS.md#communication).
 
 ## Where Things Live
 
@@ -302,7 +348,8 @@ new page needs before it shows up in the navigation.
 
 Push your branch to your fork and open a pull request against `main`. Its first line
 names the issue it fixes (`Fixes #1234`). The body says what changed, why, and how you
-verified it.
+verified it. The [pull request template](./.github/PULL_REQUEST_TEMPLATE.md) lays out
+that body, the two declaration lines and the [Human Minimum](#human-minimum) checklist.
 
 ### Review Process