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

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

N/A — 本 PR 不对应已提及的 issue；目前没有人工审查记录；改动仅涉及 Markdown 文档与两个兼容入口的符号链接，没有运行产品代码测试，已执行文档专用验证。

Description / 描述

背景

现有 agent 文档已经包含工程原则、架构速览和文档路由，但对任务应先读取哪些 owner 文档、请求与证据的关系、验证结论的适用范围、何时可以声称 ready，以及描述性事实与规范性要求冲突时如何处理，仍缺少统一边界。本次变更把共享 agent contract、文档所有权、证据范围和 review readiness 收敛到对应的 owner 中，同时保持普通贡献路径轻量。

本次改动

• AGENTS.md 明确它只拥有工程原则、架构速览和共享 agent contract；增加写代码、代码审查、架构、UI、翻译、贡献者 Markdown、PR 和手动验证的任务路由。
• AGENTS.md 保留并整理项目概览与五个运行上下文的架构速览，补充 authority/context/observation/oracle 的区分、rationale 与 evidence 要求、语义和物理审查覆盖、readiness 门槛、finding witness/impact 要求，以及完成检查清单。
• docs/README.md 与 docs/DOC-MAINTENANCE.md 更新文档所有权，明确兼容入口复用共享 contract 而不维护副本，并让相对链接检查按符号链接的真实目标解析链接基准。
• docs/pull-request.md 增加 N/A checklist note 与测试适用性的区分，并补充 decision/evidence/readiness 规则及按实际变更 contract 触发的证据表。
• docs/verification.md 增加 evidence scope 与 negative claims 规则，要求结论范围与实际证据类型一致；对“没有发生某个副作用”的结论要求 closure-window observation 或 causal proof。
• CLAUDE.md 与 .github/copilot-instructions.md 改为指向 AGENTS.md 的符号链接，避免维护重复的 agent 指令。

影响

本 PR 不改变扩展运行时代码、测试、生成文件或用户界面。它改变的是 agent 读取文档和作出审查/验证声明时的共享约定：具体机制仍由 routed owner 文档负责，兼容入口不再拥有独立副本，验证结论也必须限定在实际证据覆盖的范围内。

已知限制 / 取舍

• 本 PR 只修改文档与 agent 指令入口，因此没有运行产品测试或浏览器验证。
• 本地验证确认了符号链接模式、目标和解析后的内容；不同外部工具是否按预期加载符号链接，仍取决于工具自身实现，未在本地模拟所有远端 review surface。
• 文档专用检查验证的是最终 worktree 的链接、事实、所有权和政策一致性，不等同于扩展运行时行为验证。
• 本次变更保留轻量 PR 流程；证据规则按实际变更类型适用，不要求每个文档变更都附加产品测试或形式化证明包。

验证

• git diff --check 通过。
• CLAUDE.md 指向 AGENTS.md，.github/copilot-instructions.md 指向 ../AGENTS.md；两个入口均为符号链接，解析后的内容与 AGENTS.md 一致。
• 对 tracked Markdown 执行相对链接目标检查，并对符号链接按其真实目标解析链接基准；未发现 broken link target。
• 执行最终树的文档事实、所有权和政策一致性检查；未发现超出本次文档范围的敏感路径或隐私内容。
• 未运行 pnpm 产品测试；改动未触及产品代码、测试或生成文件。

建议审查重点

1. AGENTS.md 是否只保留共享 agent contract、工程原则和架构速览，具体机制是否仍由正确的 routed owner 文档拥有。
2. CLAUDE.md 与 .github/copilot-instructions.md 是否确实只是符号链接入口，未继续维护第二份指令。
3. authority/context/observation/oracle、holds/not observed，以及 descriptive fact/normative intent 的边界是否清晰。
4. N/A checklist note、测试适用性与 review readiness 规则是否保持了按变更范围触发的轻量流程。
5. 符号链接解析后的相对链接检查是否能覆盖兼容入口而不改变其他 Markdown 的链接语义。

Screenshots / 截图

N/A — 纯文档与指令入口变更，无 UI 变化。

[cyfung1031]

human checked

[CodFrm]

你还经常用copilot么？我现在感觉只有偶尔在页面的时候，可能会request一下copilot review，而且非常少了

我感觉都可以移除掉AGENTS.md等地方对copilot的描述了

[cyfung1031]

你还经常用copilot么？我现在感觉只有偶尔在页面的时候，可能会request一下copilot review，而且非常少了

我感觉都可以移除掉AGENTS.md等地方对copilot的描述了

都可以

[cyfung1031]

本次 rework 已在原 PR head ea597c28 上同步最新 main（88e73d8a），保留原 PR 提交作为比较基线。PR 标题和 body 未修改；同步后 GitHub 当前最终 diff 为 6 个文档路径，原 body 中关于两个 symlink 入口的描述属于历史上下文，现由修正 commit 处理为兼容的普通文件入口。

修正 commits：

• 7590540d：同步最新 main，并保留原 PR head 不变以便对比。
• 4b35b4ce：修正 Agent 入口与验证契约边界。恢复 CLAUDE.md 的 @AGENTS.md 导入和 Copilot 专属路由，避免 core.symlinks=false checkout 把入口变成字面路径；将 Markdown 链接检查绑定到指定 committed tree；统一 negative claim 的 holds / causal-proof 规则。
• 76106ea9：移除原 PR 加回的旧全仓库 issue-template 测试。最新 main 已把扫描移入 beforeAll 缓存；保留旧测试会执行重复扫描并重新引入 timeout/性能问题。

本地验证：

• pnpm run lint：Prettier、TypeScript、i18n、issue-template check、ESLint 全通过。
• pnpm run test:ci：327 个测试文件、3718 个测试全通过。
• 目标 Vitest：18/18 通过；CLI issue-template check 通过。
• revision-bound Markdown 链接检查：无 BROKEN 目标。
• core.symlinks=false clean checkout：两个入口均保持可读普通文件，Claude/Copilot 内容可加载。
• git diff --check 通过。

最终已发布 head：76106ea9。发布后的远端状态为：GitHub Actions 与 License Compliance SUCCESS；Codecov codecov/project FAILURE（67.22%，相对 88e73d8 下降 0.01%）。本地验证全部通过，但该项目级 Codecov 门槛仍需维护者决定是否接受或另行处理。

[cyfung1031]

已在原 PR 分支上完成重做并推送，最终头为 d70f01ec。

修正内容：

• 先以 PR 当前源分支 5c93b002 为基线，合并最新 main 1d2250c8，合并提交为 23fd8c17。
• 保留并核实了两个兼容入口的 symlink：CLAUDE.md -> AGENTS.md 与 .github/copilot-instructions.md -> ../AGENTS.md。没有重新加入 4b35b4c 中不必要的 @AGENTS.md 普通文件和 Copilot 专属路由。
• 447f03ed：将 Markdown 链接检查改为读取指定 committed tree，并正确解析 tree 中的 symlink，避免工作树/未跟踪文件影响结果。
• d70f01ec：对齐负面断言规则与验证报告模板，允许有充分 closure-window observation 或 causal proof 的 holds 结论。

验证：

• committed-tree Markdown 链接检查：通过，无 BROKEN。
• pnpm run check:issue-templates：12 个模板通过。
• Vitest：scripts/check-issue-templates.test.mjs，18/18 通过。
• TypeScript：pnpm exec tsc --noEmit --incremental false -p tsconfig.json，通过。
• Prettier 与 git diff --check：通过。
• 未运行浏览器 E2E；本次最终修正仅涉及文档/验证契约，且按文档规则不需要无关的运行时验证。

[cyfung1031]

更正并完成本次 rework：先绑定并更新原 PR 的真实 head 76106ea9，再合并原仓库最新 main 9e31780f，最终已推送到本 PR 分支，远端 head 为 24afff83。

先说明一个绑定错误：上一条 rework 说明引用的 d70f01e 属于 cyfung1031 fork 的同名分支，不是本 PR 的 head，请以本条说明为准；本次已直接更新 scriptscat/scriptcat 的原 PR 分支。

修正 commits：

• fd663cd9：在真实 PR head 上合并最新 main，保留 main 的常驻验证会话改动，并解决文档冲突。
• fd663cd9：恢复两个被 4b35b4c 改成普通文件的兼容入口为 symlink：CLAUDE.md -> AGENTS.md、.github/copilot-instructions.md -> ../AGENTS.md；同时移除不必要的独立 Copilot 路由内容。
• 24afff83：从 AGENTS.md 移除残留的 Copilot 专属路由描述，保持共享契约由 AGENTS.md 单一拥有。

验证结果：

• committed-tree Markdown 链接检查通过，无 BROKEN。
• pnpm run check:issue-templates 通过：12 个模板。
• 定向 Vitest 通过：2 个 test files、22/22 tests（issue templates + verification tools）。首次运行 verification-tools 时沙箱禁止 127.0.0.1 监听，出现 listen EPERM；在允许本地回环监听后重跑通过。
• pnpm exec tsc --noEmit --incremental false -p tsconfig.json 通过。
• Prettier 与 git diff --check 通过。
• 未运行浏览器 E2E；本次变更是文档/验证契约与兼容入口修正，且保留了最新 main 的验证会话测试。