docs: require visual evidence for UI pull requests

[huangruiteng]

Summary

• Require frontend and other user-visible UI pull requests to declare their UI impact and attach public-safe visual evidence.
• Require before/after screenshots for existing surfaces, an explicit Before: N/A for new surfaces, and relevant viewport or state coverage.
• Preserve the repository boundary by allowing only synthetic or public-fixture screenshots.

Issue Or Task

• Closes #
• Contributor task ID: N/A

Validation

• Tested revision: 9920d855530891be733649df60e6a44ac65447ae
• Run state: finished
• Input classes: none

Check kind	Result	Public-safe evidence / limitation
static	passed	git diff --check; no whitespace errors.
static	passed	python examples/docs-governance-smoke.py; documentation governance remained consistent.
static	passed	python examples/repository-hygiene-smoke.py; tracked-file and public/private boundary checks passed.

• Coverage and gaps: The change only updates the pull-request template. Static documentation-governance and repository-boundary smokes cover the affected policy surface; runtime validation is not applicable.

Frontend / Visual Evidence

• UI impact: none
• Before: N/A
• After: N/A
• States and viewports shown: N/A
• Source data: none

Type of Change

• Bug fix
• New feature
• Breaking change
• Refactoring (no functional changes)
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
• Capability or extension (providers, adapters, skills)
• Public docs or presentation surface (README, protocols, dashboard)
• Build, packaging, installer, or CI
• Host or runtime integration

Technical Direction

• Core control-plane hardening

• Long-horizon benchmark evidence

• Operator surface and IM integration

• Shared Goal Authority and cross-host coordination

• Architecture and research incubator

• Target base branch: main

• Direction tracker or promotion unit: N/A

Shared-authority RFC fixture impact

N/A. This change does not claim progress against the TypeScript control-plane migration or Shared Goal Authority RFC.

Boundary Checklist

• Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
• I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
• I kept the change scoped to the linked issue/task.
• I completed the visual evidence section for UI changes, or marked UI impact none.
• Every commit includes a DCO Signed-off-by trailer (git commit -s).

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewed exact head: 9920d855530891be733649df60e6a44ac65447ae。没有发现阻塞问题；结论为 APPROVE。这是评审结论，不是合并操作。

动机

现有 PR 模板要求说明验证命令与数据来源，但没有明确让 UI 作者提交改动前后的实际画面。这样即使测试通过，评审者仍可能无法判断布局、响应式断点，以及空白、报错或权限状态是否真的改善。这次把视觉证据要求放在 PR 创建时就会遇到的位置，直接减少反复追问。最强的反对理由是给小改动增加填表成本；明确的 UI impact: none 和只覆盖发生变化的状态，使非 UI 修改不必制造无意义截图。无需为这个问题引入自动截图服务或新的机器门禁。

改动思路

复用 .github/PULL_REQUEST_TEMPLATE.md，由作者声明 UI 影响、提供证据，评审者判断证据是否对应真实改动。既有页面要求 before/after，新页面允许 Before: N/A；响应式布局变化提供桌面和移动视口，状态发生变化时才补相应状态。只有静态图不足以说明交互时才需要录屏。这是人工执行的贡献要求，不应误读为 CI 已自动验证截图质量，也不替代仓库已有的首屏 owner 预览批准规则。

具体改动

关键内容讲解

完整 diff 只有一个模板文件、增加 22 行，没有运行时代码、测试夹具或生成资源。新增 Frontend / Visual Evidence 节将要求放在验证说明后，包含 UI impact、Before、After、States and viewports shown、Source data 五个填写入口。前置说明覆盖 dashboard、网站、desktop 和文档界面，不局限于某个框架；对已有/新建页面、响应式和变化状态分别说明取证方式。末尾增加一项 checklist，把“UI 修改填写证据”与“非 UI 标记 none”连接起来。隐私边界值得保留：只允许 synthetic/public fixture，明确指出即使获准访问真实数据，也不代表可以公开其截图。已与 CONTRIBUTING 的验证披露和 AGENTS 的公开/私有边界对照，没有相互放宽。

对主干的风险

主要风险是执行质量，而不是产品回归：作者仍可能空着字段、贴无关首页或遗漏错误态。模板能提供明确检查入口，不能自动证明图片充分或安全。走查了“已有页面错误态和响应式变化”“新页面”“非 UI 改动”“已获授权但仍属私有的截图”四类情况，要求均能给出明确处理。独立执行 git diff --check HEAD^ HEAD、python examples/docs-governance-smoke.py、python examples/repository-hygiene-smoke.py，全部通过；远端检查成功，presentation 为预期跳过。没有 UI 实现变化，因此没有伪造浏览器视觉验证结论。

我的整体评价

这是与问题规模匹配的贡献流程改进，既没有新增第二套状态或校验器，也没有把首屏批准挪到事后。未来简化检查已经做过：保留现有模板作为唯一入口即可，不建议现在追加机械检查截图存在性的复杂框架。残余风险是人工评审执行不足，应在具体 UI PR 上检查证据相关性；不应因此阻塞这份清晰、局部的模板改动。

English verdict: APPROVE at 9920d855530891be733649df60e6a44ac65447ae. The 22-line template change makes before/after, changed-state and viewport evidence discoverable while excluding private screenshots and allowing non-UI changes to opt out. Independent diff, documentation-governance and repository-hygiene checks passed. This is human-enforced review guidance, not automated visual validation or merge authorization.