📄 完善 Agent 文档职责、证据与审查边界

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/DOC-MAINTENANCE.md

@@ -88,7 +88,7 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 
 | Doc | Owns |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | Engineering principles + architecture quick-map. `CLAUDE.md` only `@import`s it. |
+| [`../AGENTS.md`](../AGENTS.md) | Engineering principles, architecture quick-map, and shared agent contract. `CLAUDE.md` and other compatibility entry points are symlink aliases; they do not own a separate policy. |
 | [`develop.md`](./develop.md) | The concrete "how": commands, structure, style, i18n, commit/PR. Testing → [`references/develop-testing.md`](./references/develop-testing.md). |
 | [`pull-request.md`](./pull-request.md) | The PR body: structure and evidence rules. The human-facing template stays lightweight. |
 | [`design.md`](./design.md) | The design system; tokens, component palette, and layout/motion/state/a11y patterns → the three `references/design-*.md`. |
@@ -99,7 +99,6 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: organization rules, fact-check / anti-drift discipline, policy-consistency checks — across every tracked contributor Markdown, not just `AGENTS.md` + `docs/*`. |
 | [`README.md`](./README.md) | The reader-facing index: what each doc contains and when to read it. |
-| `.github/copilot-instructions.md` | Copilot-specific entry point and genuine tool-specific differences only; shared facts route to the owning doc above instead of being copied. |
 | Package-local `README.md` (e.g. `packages/message/README.md`, `packages/filesystem/README.md`) | That package's purpose, boundaries, entry points, and local gotchas — not a duplicate of repo-wide architecture or coding policy. |
 
 This table records **ownership boundaries** — which doc a given fact belongs in. It is deliberately *not* the
@@ -177,7 +176,11 @@ git ls-files '*.md' | while IFS= read -r doc; do
   # references/verification-report-template.md's screenshot/resource examples, verification.md's
   # "Evidence location" spans) aren't false-flagged as broken
   sed '/^```/,/^```/d; /^~~~/,/^~~~/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^(https?:|mailto:|#|app:)' | while IFS= read -r link; do
-    target="$(dirname "$doc")/${link%%#*}"
+    link_doc="$doc"
+    if [ -L "$doc" ]; then
+      link_doc="$(dirname "$doc")/$(readlink "$doc")"
+    fi
+    target="$(dirname "$link_doc")/${link%%#*}"
     [ -e "$target" ] && echo "ok     $doc → $link" || echo "BROKEN $doc → $link"
   done
 done
@@ -197,9 +200,13 @@ a heading — an external deep link into that heading breaks if you rename it wi
 
 ## When you find a discrepancy
 
-Fix the **doc** to match the code — the code on this branch is the source of truth. The exception: if the code
-itself is wrong (a real bug), fix the code and say so in the PR. Either way, never silently drop a check you
-couldn't satisfy — surface it in the PR description so a reviewer can confirm.
+Fix the **doc** to match the code for descriptive facts about the current branch — the code on this branch is
+the source of truth for names, paths, and current implementation shape. Normative intended behavior may instead
+be owned by a specification, compatibility contract, security policy, accepted test oracle, or maintainer
+decision. When those sources conflict with the current code, surface the conflict and resolve it with the owning
+authority; do not silently rewrite either side to make the patch easier. If the code itself is wrong, fix the code
+and say so in the PR. Either way, never silently drop a check you couldn't satisfy — surface it in the PR
+description so a reviewer can confirm.
 
 ## Honest completion claims
 

docs/README.md

@@ -6,7 +6,7 @@
 
 | 文档 | 说明 |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源 —— 但仅相对 `CLAUDE.md`(其仅导入它)成立;`.github/copilot-instructions.md` 是 Copilot 的独立入口,与本文件共享的事实需在两边都改动时做一致性核对(parity review)。 |
+| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览与 AI coding agent 的共享约定所有者；`CLAUDE.md` 与其他兼容入口均通过符号链接复用它，不维护副本。 |
 | [`develop.md`](./develop.md) | 开发规范:命令、目录结构、编码风格、UI/主题、i18n、提交/PR 流程;测试设计/清理口径与运行机制(含 Vitest 性能)拆到 [`references/develop-testing.md`](./references/develop-testing.md)。**写代码前先读。** |
 | [`pull-request.md`](./pull-request.md) | PR 描述指南:代理与贡献者使用的详细章节、按变更类型取舍规则、验证与审查信息要求。 |
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |

docs/pull-request.md

@@ -60,6 +60,54 @@ For a normal feature or behavior change, use the following sections when they ar
 
 Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR — the same applies to any other checklist item: leave it unchecked (without rewording it) whether the work wasn't done or doesn't apply. If an item doesn't apply to this PR, add a brief `N/A — <why>` note below the checklist, so reviewers can tell "not applicable" from "not done" — an unchecked box alone doesn't distinguish the two.
 
+The brief `N/A` note above is only for an inapplicable PR checklist item. Test dimensions remain applicability-gated by [the testing guide](./references/develop-testing.md) and are omitted when they do not apply; do not add a formal applicability table or proof packet to a PR.
+
+## Decision, evidence, and readiness
+
+For a material behavior, configuration, security, performance, compatibility, persistence, migration, release, or refactor change, write enough context for a reviewer to reconstruct:
+
+1. the problem or requirement;
+2. the affected scope and consequence;
+3. the evidence that the premise is real;
+4. why action is justified;
+5. the selected remedy and material trade-off;
+6. acceptance evidence; and
+7. the remaining limitation or risk.
+
+Keep this chain proportional. A confirmed one-line correction or a small documentation fix needs only the material parts; a non-trivial design choice should explain why doing nothing or a plausible smaller alternative was not selected and what would reopen the decision.
+
+Keep these roles separate:
+
+- maintainer direction authorizes execution within the requested scope;
+- an issue, PR description, or discussion supplies stated intent and scope context;
+- source inspection, tests, browser runs, and integrations provide observations;
+- a specification, compatibility contract, security policy, accepted test oracle, or maintainer decision owns normative correctness.
+
+An issue or PR does not by itself prove that a bug exists, that a remedy is necessary, that a change is correct, or that external publication or residual-risk acceptance is authorized.
+
+Consider risk for every material change. Use an explicit limitation or rollback paragraph when the change affects shared APIs, persistence, permissions, security/privacy, browser compatibility, cross-context messaging, asynchronous lifecycle, or release/build behavior. Identify residual risk and the decision owner; do not claim that a significant residual risk has been accepted without that owner's decision.
+
+An agent must not present a change as review-ready when a material acceptance condition fails, a critical claim is unverified or contradicted, the diff exceeds the justified scope, required verification is missing without an adequate substitute, a known correctness/security/privacy/compatibility defect remains, or the description no longer matches the final patch. An explicitly requested draft or investigation may still be submitted when labeled as such. Report the blocker, the evidence, and the condition that would clear it.
+
+Verification claims bind to a revision or clearly identified worktree. If code, configuration, generated artifacts, or a decision-relevant description changes after a check, rerun every affected check before claiming readiness. A final commit SHA is sufficient identity for ordinary GitHub work; a cryptographic evidence ledger is not required by default.
+
+## Evidence triggered by changed contract
+
+Activate only the rows touched by the actual change; mixed changes use their union.
+
+| Changed contract | Extra evidence to expect |
+| --- | --- |
+| Bug fix | Before reproducer, expected behavior, regression test or justified manual evidence, and the same reproducer after the fix |
+| New behavior | User/system need, observable acceptance criteria, and compatibility/scope boundaries |
+| Refactor | Concrete structural problem and evidence that behavior/public contracts are preserved |
+| Performance/resource | Baseline, workload, environment, method, before/after result, and accepted correctness/complexity trade-off |
+| Security/privacy/permissions | Protected boundary, threat or failure mode, safe verification, residual risk, and private reporting when appropriate |
+| Dependency/build/configuration | Compatibility or lifecycle reason, version/platform scope, lock/generated rationale, and build verification |
+| Documentation/tests only | The authoritative behavior or decision being corrected or preserved; verify claims, links, or tests without inventing runtime evidence |
+| Generated/mechanical | Source input, tool/command, reason for regeneration, and evidence that unrelated semantic edits were not mixed in |
+| Persistence/migration/release | Compatibility and data scope, ordering/irreversibility, rollback/restore path, and rehearsal or invariant evidence where safe |
+| Async/concurrency/stateful UI | Duplicate in-flight work, stale or late results, cancellation/retry, cleanup, and identity or generation ordering where applicable |
+
 ## Review-oriented content
 
 For non-trivial changes, make the description useful for review:

docs/verification.md

@@ -296,6 +296,14 @@ before assertions).
     which in `report.md`; never dress up a red run as green.
 - Never weaken an assertion or skip a check to make a scratch run "pass".
 
+### Evidence scope and negative claims
+
+Name the evidence type behind each material conclusion. Source or static reasoning proves only what follows from the inspected source and contract; an executed unit or fixture proves its scenario; browser runtime evidence proves the observed browser scenario; an external integration observation proves that integration run. Do not promote one evidence type into a broader claim without additional support.
+
+When claiming that something did **not** happen — such as a request, write, disclosure, duplicate event, or stale callback — either observe the forbidden channel through the relevant completion or closure window, or provide a causal proof that execution cannot reach that side effect. An error callback, missing success callback, final UI value, or final persisted value alone is insufficient.
+
+For a negative claim, `holds` requires that closure-window observation or causal proof. Otherwise report `not observed`, preserving the per-claim verdicts above; this rule does not replace them.
+
 ## Maintaining this guide
 
 When the workflow or the paths in it change, keep this doc true to the branch (see

scripts/check-issue-templates.test.mjs

@@ -81,7 +81,8 @@ describe("issue 模板机械检查", () => {
     expect(problemsOf(makeFixtureRoot())).toEqual([]);
   });
 
-  it("仓库现有的 issue 模板应全部通过检查", () => {
+  // 该用例会读取整个 src 并解析 issues/new 链接，冷缓存或 worker 并发时可能超过 fast 项目的 340ms 预算。
+  it("仓库现有的 issue 模板应全部通过检查", { timeout: 850 }, () => {
     expect(problemsOf(REPO_ROOT)).toEqual([]);
   });