From 70fcc142be837f83b35eff5c32b119b1adf5e83e Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Sat, 8 Aug 2026 09:45:34 +0900
Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=93=84=20=E6=BE=84=E6=B8=85=20Agent?=
 =?UTF-8?q?=20=E6=96=87=E6=A1=A3=E8=81=8C=E8=B4=A3=E4=B8=8E=E5=AE=A1?=
 =?UTF-8?q?=E6=9F=A5=E9=97=A8=E6=A7=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/copilot-instructions.md | 70 ++++++++++++++++++++++-----------
 AGENTS.md                       | 34 +++++++++++-----
 2 files changed, 70 insertions(+), 34 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 49fe962a8..fbc1c49b2 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,30 +1,52 @@
 # ScriptCat — Copilot Instructions
 
-> **This file only holds Copilot-specific behavior and a router.** Architecture, coding conventions, commands,
-> and testing mechanics are owned by [`../AGENTS.md`](../AGENTS.md) and the docs it routes to
-> (`docs/develop.md`, `docs/architecture.md`, `docs/references/*`, `docs/verification.md`, `docs/design.md`,
-> `docs/translation.md`). Read those before reviewing or writing code — don't rely on a second, separately
-> maintained copy of them here; when this file and one of those docs disagree, the owning doc wins and this
-> file should be corrected to match.
+> **Copilot-specific delta only.** Shared engineering principles and the architecture quick-map are owned by
+> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. Read those sources before
+> reviewing or writing code. If this file disagrees with an owning document, the owning document wins and this
+> file should be corrected rather than expanded into a second source of truth.
 
 ## Code Review
 
 - Respond in Chinese when performing a code review (用中文回复代码审查意见).
-- Conduct a **comprehensive and independent review** of the entire PR every time:
-  - **Full review every time** — review all modified files regardless of previous reviews or comments; treat
-    re-reviews as new, not relying on prior review state.
-  - **No skipping files** — examine every changed file regardless of type (`.md`, `.json`, `.yml`, `.toml`,
-    `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.).
-  - **PR descriptions/commit messages/discussion are reference context only** — the review's conclusions must
-    be grounded in the actual code and file changes, inferring intent from the diff itself.
-  - **Independent verification** — don't assume an unchanged file or a previously reviewed section is safe;
-    verify code paths potentially affected by the current changes.
-
-## Minimal fallback (only if this surface can't reliably follow the link above)
-
-ScriptCat is a Manifest V3 browser extension (TypeScript + React 19 + Rspack, pnpm) that runs
-Tampermonkey-compatible userscripts across five isolated contexts — Service Worker, Content, Inject, Offscreen,
-Sandbox — communicating over `packages/message`. If you cannot load `AGENTS.md`, treat any architecture,
-persistence-pattern, or service-shape claim you're tempted to state here as unverified, and prefer asking the
-reviewer to confirm against `AGENTS.md` / `docs/architecture.md` over inventing a summary — this file is not
-the source of truth for those facts and must not re-accumulate a parallel copy of them.
+- Perform a **comprehensive, independent review of the entire current diff** every time:
+  - inspect every changed file, regardless of extension or whether it was reviewed previously;
+  - use PR descriptions, commit messages, and discussion only as context — conclusions must be grounded in the
+    current repository state and the actual diff;
+  - re-check affected code paths instead of assuming unchanged or previously reviewed code is safe.
+- Use the architecture map and routed subsystem docs from `AGENTS.md` when a finding depends on repository-specific
+  behavior. Do not recreate those facts here from memory.
+
+### Finding gate
+
+For PR-review findings, focus on defects introduced by the current diff or made newly reachable by it. A
+pre-existing defect discovered while tracing an affected code path may still be reported only when it has material
+correctness, security, data-loss, reliability, or comparably significant user/developer impact. Label it clearly as
+**pre-existing** so the reviewer can separate regression risk from nearby debt; otherwise keep the review scoped to
+the change.
+
+For any finding you report, apply every relevant check below:
+
+1. **Relation to the change:** state whether the defect is introduced/newly reachable or pre-existing in an affected
+   path; do not imply the PR caused a defect when it did not.
+2. **Concrete trigger or proof path:** state the input/state/browser/context that reaches it, **or** a demonstrable
+   code path / invariant violation when runtime reproduction is not the appropriate proof (for example a race,
+   lifecycle violation, resource leak, or security-boundary error).
+3. **Concrete impact:** explain the user/developer-visible consequence, not just a stylistic preference or
+   hypothetical concern.
+4. **Located:** point to the smallest useful changed location when the finding is PR-introduced. For a pre-existing
+   finding, point to the smallest useful affected location when that location is represented in the diff; if the
+   relevant location is outside the diff, report it in the review summary instead of attaching it to an unrelated
+   changed line.
+5. **Distinct:** do not create a second finding for the same root cause unless the separate location needs an
+   independent fix.
+6. **Actionable:** make clear which behavior or contract must be restored without prescribing an unrelated refactor.
+
+If a repository-specific assumption is needed to support a finding and it cannot be verified from the owning
+docs/code, **do not submit it as a finding**. If the uncertainty is still useful to the reviewer, put it in the review
+summary as an explicit question or unverified assumption and identify the canonical source that would resolve it.
+
+## Minimal fallback when linked instructions are unavailable
+
+Do **not** invent or retain a parallel architecture/coding summary here. Limit work to facts that are directly
+verifiable from the current diff and files, avoid structural recommendations that depend on unavailable
+repository policy, and explicitly state which canonical instruction source could not be loaded.
diff --git a/AGENTS.md b/AGENTS.md
index 8eb928f4d..ea5a6417b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,29 +1,30 @@
 # Repository Guidelines
 
-This file provides guidance to AI coding agents (Claude Code, etc.) when working with code in this repository.
-It holds only the engineering principles and the architecture quick-map; the concrete "how" belongs to the docs
-below. `CLAUDE.md` merely `@import`s this file — don't split guidance between the two. Link the owning doc
-instead of copying its content here.
+This is the repo-wide contract for AI coding agents. It owns **engineering principles** and the **architecture quick-map** only. Concrete mechanics belong to the routed docs below. `CLAUDE.md` only imports this file, and `.github/copilot-instructions.md` may add Copilot-specific behavior but must not duplicate shared policy or architecture.
 
-**Read before you act.** [`docs/README.md`](docs/README.md) indexes the full doc set.
+Use [`docs/README.md`](docs/README.md) as the document index. When a routed document owns a concern, follow that document and link to it rather than copying its content here.
+
+## Route the task before acting
 
 | Before you… | Read |
 | --- | --- |
 | write any code | [`docs/develop.md`](docs/develop.md) |
+| change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) — plus the relevant `docs/references/architecture-*.md` deep-dive |
 | build or modify any page, dialog, or block | [`docs/design.md`](docs/design.md) — its Core Constraints apply to *every* UI change, not only new pages |
 | add or change localized content | [`docs/translation.md`](docs/translation.md) — plus the matching `docs/references/terminology-<locale>.md` when one exists |
 | add, edit, reorganize, or review any tracked contributor Markdown (this file, `docs/*`, `.github/*.md`, package- and source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — *if you can't grep it on this branch, don't claim it* |
 | open or update a pull request | [`docs/pull-request.md`](docs/pull-request.md) |
 | manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — a throwaway scratch script against the built extension, not the committed suite |
 
+For a task that spans several rows, read each applicable owner before performing that part of the task; do not front-load unrelated docs just because they might become relevant later. For a task that fits none of them cleanly, inspect `docs/README.md` and the nearby implementation/tests before inventing a new rule or abstraction.
+
 ## Project Overview
 
 ScriptCat — Manifest V3 browser extension that runs Tampermonkey-compatible user scripts. TypeScript + React 19 + Rspack. Package manager is **pnpm** (preinstall enforces). The presentation layer (`src/pages/`) is **shadcn/ui + Tailwind CSS v4** (migrated from Arco Design + UnoCSS).
 
 ## Engineering Principles
 
-These are non-negotiable, regardless of what `docs/develop.md` says about mechanics — where a principle's scope
-isn't universal, that's called out in the item itself.
+These are the repo-wide defaults. When a principle links to a narrow, explicit exception in its owning document, that exception is part of the same contract; unrelated or unlinked downstream prose does not silently override the principle.
 
 - **Fix root causes, not symptoms — refactor over patch.** No `as any` / `// @ts-ignore` / try-catch swallow / defensive skips to make errors disappear (宁愿重构也不要打补丁). If a test fails, fix the code, not the test — the narrow exceptions (a wrong test contract; a test that never carried value) are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
 - **Confirm before you fix.** Before touching a reported bug, reproduce it and confirm it actually exists — never fix from assumption. Capture the reproduction, then fix, **in that order** (确定 bug 存在 → 写测试或记录验证证据 → 修复); how to reproduce and what counts as capture are in [`docs/verification.md`](docs/verification.md) and the TDD entry below.
@@ -36,14 +37,13 @@ isn't universal, that's called out in the item itself.
 
 ## Architecture
 
-Quick map only — the internals guide and its "how to extend" recipes are in
-[`docs/architecture.md`](docs/architecture.md).
+This is an orientation map, not an implementation manual. Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or adding a subsystem.
 
 ### Multi-Process Model
 
 5 isolated contexts communicating via message passing:
 
-```
+```text
 Service Worker (src/service_worker.ts)
   ├── ExtensionMessage ──────────────→ Content Script (src/content.ts)
   │                                        └── CustomEventMessage ──→ Inject Script (src/inject.ts)
@@ -64,15 +64,18 @@ Service Worker (src/service_worker.ts)
 Execution paths: page scripts → `chrome.userScripts`; background → SW → Offscreen → Sandbox; scheduled → cron in Sandbox.
 
 ### Message Passing (`packages/message/`)
+
 `ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔ Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome), `CustomEventMessage` (CustomEvent — Content ↔ Inject), `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers
+
 - Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/`) plus **cross-cutting subsystems** (`agent/`, `extension/`, `queue.ts`) — not one uniform shape. Details, inventory, "adding a service": [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
 - Persistence is a backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / custom), not one pattern. Details, inventory, "adding an entity": [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
 - **GM API** split across content / SW / offscreen, each a `GMApi`; values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
 - **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five contexts, not a sixth. Full write-up: [`docs/references/architecture-agent.md`](docs/references/architecture-agent.md).
 
 ### Browser Extension APIs (MV3)
+
 `chrome.userScripts` (page injection), Offscreen API (DOM in background), Declarative Net Request (intercepts `.user.js` URLs to trigger install flow).
 
 ### Key Packages
@@ -80,3 +83,14 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 `message/` (with mocks), `filesystem/` (WebDAV, cloud drive providers, zip export — see [`docs/cloud-sync.md`](docs/cloud-sync.md)), `cloudscript/`, `eslint/` (userscript lint config — `eslint-plugin-userscripts`-based `defaultConfig` for the in-app editor), `chrome-extension-mock/`.
 
 The project's *own* custom ESLint rules live in `eslint-rules/` at the repo root, **not** in `packages/eslint/`; both are documented in [`docs/develop.md`](docs/develop.md#eslint-custom-rules).
+
+## Completion checksum
+
+Before claiming a task is complete, use the applicable owner docs above to verify the final state. This section is a handoff checklist, not a second copy of their mechanics; when a detail matters, the linked owner wins. If an item cannot be checked, report the limitation instead of upgrading the claim to “verified” or “all fixed.”
+
+- **Owners:** every part of the task was checked against its applicable routed owner; documentation work follows [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md).
+- **Evidence:** reproduction, tests, and manual evidence satisfy the applicable rules in [`docs/references/develop-testing.md`](docs/references/develop-testing.md) and [`docs/verification.md`](docs/verification.md), including any explicit exception used.
+- **Contract & scope:** the final diff still matches the requested/verified behavior and the scope-discipline principles above; no unrelated compatibility layer or cleanup slipped in.
+- **Extension point:** architecture-sensitive changes were checked against [`docs/architecture.md`](docs/architecture.md) and the relevant deep-dive instead of creating a parallel abstraction from memory.
+- **Facts:** changed documentation claims were checked using the branch-aware process in [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md), not memory or untracked files.
+- **Verification:** the checks required by the applicable owner docs were run, and any environment/tooling blocker is stated explicitly in the completion report or PR.

From 223b652f2ddb0a1a117f8d47e79095c0133285c9 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:50:10 +0900
Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=AE=E6=AD=A3=20Agent?=
 =?UTF-8?q?=20=E6=96=87=E6=A1=A3=E8=B7=AF=E7=94=B1=E4=B8=8E=E8=81=8C?=
 =?UTF-8?q?=E8=B4=A3=E8=BE=B9=E7=95=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/copilot-instructions.md | 16 ++++++----------
 docs/README.md                  |  2 +-
 2 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index fbc1c49b2..8d42cc995 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,20 +1,16 @@
 # ScriptCat — Copilot Instructions
 
 > **Copilot-specific delta only.** Shared engineering principles and the architecture quick-map are owned by
-> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. Read those sources before
-> reviewing or writing code. If this file disagrees with an owning document, the owning document wins and this
-> file should be corrected rather than expanded into a second source of truth.
+> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. For code review, also read
+> [`../docs/develop.md`](../docs/develop.md). Read those sources before reviewing or writing code. If this file
+> disagrees with an owning document, the owning document wins and this file should be corrected rather than
+> expanded into a second source of truth.
 
 ## Code Review
 
 - Respond in Chinese when performing a code review (用中文回复代码审查意见).
-- Perform a **comprehensive, independent review of the entire current diff** every time:
-  - inspect every changed file, regardless of extension or whether it was reviewed previously;
-  - use PR descriptions, commit messages, and discussion only as context — conclusions must be grounded in the
-    current repository state and the actual diff;
-  - re-check affected code paths instead of assuming unchanged or previously reviewed code is safe.
-- Use the architecture map and routed subsystem docs from `AGENTS.md` when a finding depends on repository-specific
-  behavior. Do not recreate those facts here from memory.
+- Re-review the entire current diff independently every time; do not treat prior review results or comments as a
+  substitute for a fresh review.
 
 ### Finding gate
 
diff --git a/docs/README.md b/docs/README.md
index f34c011f5..25aff0be5 100644
--- a/docs/README.md
+++ b/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` 仅导入它，`.github/copilot-instructions.md` 仅保留 Copilot 专属增量。 |
 | [`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)。**做页面/对话框/区块前先读。** |

From fc447e457882587876f42500c122e70e953aaece Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Tue, 11 Aug 2026 02:51:30 +0900
Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=84=20=E5=AE=8C=E5=96=84=20Agent?=
 =?UTF-8?q?=20=E6=96=87=E6=A1=A3=E8=81=8C=E8=B4=A3=E3=80=81=E8=AF=81?=
 =?UTF-8?q?=E6=8D=AE=E4=B8=8E=E5=AE=A1=E6=9F=A5=E8=BE=B9=E7=95=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/copilot-instructions.md | 49 +--------------------------------
 AGENTS.md                       | 12 +++++++-
 CLAUDE.md                       |  2 +-
 docs/DOC-MAINTENANCE.md         | 19 +++++++++----
 docs/README.md                  |  2 +-
 docs/pull-request.md            | 48 ++++++++++++++++++++++++++++++++
 docs/verification.md            |  8 ++++++
 7 files changed, 83 insertions(+), 57 deletions(-)
 mode change 100644 => 120000 .github/copilot-instructions.md
 mode change 100644 => 120000 CLAUDE.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
deleted file mode 100644
index 8d42cc995..000000000
--- a/.github/copilot-instructions.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# ScriptCat — Copilot Instructions
-
-> **Copilot-specific delta only.** Shared engineering principles and the architecture quick-map are owned by
-> [`../AGENTS.md`](../AGENTS.md); mechanics are owned by the docs it routes to. For code review, also read
-> [`../docs/develop.md`](../docs/develop.md). Read those sources before reviewing or writing code. If this file
-> disagrees with an owning document, the owning document wins and this file should be corrected rather than
-> expanded into a second source of truth.
-
-## Code Review
-
-- Respond in Chinese when performing a code review (用中文回复代码审查意见).
-- Re-review the entire current diff independently every time; do not treat prior review results or comments as a
-  substitute for a fresh review.
-
-### Finding gate
-
-For PR-review findings, focus on defects introduced by the current diff or made newly reachable by it. A
-pre-existing defect discovered while tracing an affected code path may still be reported only when it has material
-correctness, security, data-loss, reliability, or comparably significant user/developer impact. Label it clearly as
-**pre-existing** so the reviewer can separate regression risk from nearby debt; otherwise keep the review scoped to
-the change.
-
-For any finding you report, apply every relevant check below:
-
-1. **Relation to the change:** state whether the defect is introduced/newly reachable or pre-existing in an affected
-   path; do not imply the PR caused a defect when it did not.
-2. **Concrete trigger or proof path:** state the input/state/browser/context that reaches it, **or** a demonstrable
-   code path / invariant violation when runtime reproduction is not the appropriate proof (for example a race,
-   lifecycle violation, resource leak, or security-boundary error).
-3. **Concrete impact:** explain the user/developer-visible consequence, not just a stylistic preference or
-   hypothetical concern.
-4. **Located:** point to the smallest useful changed location when the finding is PR-introduced. For a pre-existing
-   finding, point to the smallest useful affected location when that location is represented in the diff; if the
-   relevant location is outside the diff, report it in the review summary instead of attaching it to an unrelated
-   changed line.
-5. **Distinct:** do not create a second finding for the same root cause unless the separate location needs an
-   independent fix.
-6. **Actionable:** make clear which behavior or contract must be restored without prescribing an unrelated refactor.
-
-If a repository-specific assumption is needed to support a finding and it cannot be verified from the owning
-docs/code, **do not submit it as a finding**. If the uncertainty is still useful to the reviewer, put it in the review
-summary as an explicit question or unverified assumption and identify the canonical source that would resolve it.
-
-## Minimal fallback when linked instructions are unavailable
-
-Do **not** invent or retain a parallel architecture/coding summary here. Limit work to facts that are directly
-verifiable from the current diff and files, avoid structural recommendations that depend on unavailable
-repository policy, and explicitly state which canonical instruction source could not be loaded.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 000000000..be77ac83a
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index ea5a6417b..4dc2e37fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # Repository Guidelines
 
-This is the repo-wide contract for AI coding agents. It owns **engineering principles** and the **architecture quick-map** only. Concrete mechanics belong to the routed docs below. `CLAUDE.md` only imports this file, and `.github/copilot-instructions.md` may add Copilot-specific behavior but must not duplicate shared policy or architecture.
+This is the repo-wide contract for AI coding agents. It owns **engineering principles** and the **architecture quick-map** only. Concrete mechanics belong to the routed docs below. Compatibility instruction entry points reuse this file and do not maintain a second contract.
 
 Use [`docs/README.md`](docs/README.md) as the document index. When a routed document owns a concern, follow that document and link to it rather than copying its content here.
 
@@ -35,6 +35,16 @@ These are the repo-wide defaults. When a principle links to a narrow, explicit e
 - **No dead code or `// removed` markers** — git remembers. Delete unused code outright.
 - **Comments explain "why", not "what".** Do not use ephemeral review labels such as `finding N` or review-round identifiers in comments or test names. Permanent issue or PR references are allowed when useful, but must supplement—not replace—the explanation. Do not restate code, duplicate enclosing documentation, or leave stale comments after code changes. See [`docs/develop.md`](docs/develop.md#comment-discipline) for the full policy.
 
+## Decision and review discipline
+
+- **Evidence before conclusion.** A request or maintainer direction authorizes scoped work; it does not prove a reported bug, necessity, or correctness. Separate execution authority, stated context, observations, and the normative specification or accepted contract. State when a material claim is inferred, unverified, or contradicted.
+- **Rationale before implementation summary.** For a material change, connect the observable problem or requirement, affected scope and consequence, why action is justified, the selected remedy, acceptance evidence, and remaining limitation. The diff shows what changed; it does not prove why the change was necessary.
+- **Smallest justified semantic scope, not smallest diff.** A larger refactor is appropriate when it is the smallest sound root-cause repair. Do not call a solution minimal, best, or least risky without comparative support.
+- **Claim strength follows evidence.** Source reasoning, an executed test, browser runtime, and an external integration run prove different scopes. A negative claim requires observation of the relevant channel through its closure window or a causal proof that the side effect cannot occur.
+- **Agent readiness is bounded.** An agent must not present a material change as review-ready when acceptance fails, a critical contradiction or evidence gap remains, the scope is unjustified, or final-patch evidence is stale. An explicitly requested draft or investigation may proceed when labeled as such; report the blocker and the condition that would clear it.
+- **Review coverage is semantic as well as physical.** Inspect every changed file and follow affected paths. Map material semantic families to representatives, disposition, highest-risk seam, and residual risk; distinguish confidence in a finding from completeness of the declared scope. On re-review, bind the current head and reconcile findings as still present, resolved, narrowed, stale, or new.
+- **Findings need a witness and impact.** Report a finding only with a concrete trigger or proof path, a material consequence, a useful location, and an actionable contract to restore. Do not turn an unverified repository-specific assumption into a finding.
+
 ## Architecture
 
 This is an orientation map, not an implementation manual. Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or adding a subsystem.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 43c994c2d..000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-@AGENTS.md
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000..47dc3e3d8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
index ecfa661f8..46a2deee5 100644
--- a/docs/DOC-MAINTENANCE.md
+++ b/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
 
diff --git a/docs/README.md b/docs/README.md
index 25aff0be5..5b4fc35cf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,7 +6,7 @@
 
 | 文档 | 说明 |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览与 AI coding agent 的共享约定所有者；`CLAUDE.md` 仅导入它，`.github/copilot-instructions.md` 仅保留 Copilot 专属增量。 |
+| [`../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)。**做页面/对话框/区块前先读。** |
diff --git a/docs/pull-request.md b/docs/pull-request.md
index 3ef4475d7..870222532 100644
--- a/docs/pull-request.md
+++ b/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:
diff --git a/docs/verification.md b/docs/verification.md
index 1002fb866..83857c65e 100644
--- a/docs/verification.md
+++ b/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

From 55359301874c4d87411ff1fa6fec747cbbbe1262 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Tue, 11 Aug 2026 02:53:33 +0900
Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=84=20=E8=A1=A5=E5=85=85=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E5=AE=A1=E6=9F=A5=E6=96=87=E6=A1=A3=E8=B7=AF=E7=94=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AGENTS.md b/AGENTS.md
index 4dc2e37fd..98fbc8aed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,6 +9,7 @@ Use [`docs/README.md`](docs/README.md) as the document index. When a routed docu
 | Before you… | Read |
 | --- | --- |
 | write any code | [`docs/develop.md`](docs/develop.md) |
+| review code or a pull request | [`docs/develop.md`](docs/develop.md) — plus [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules |
 | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) — plus the relevant `docs/references/architecture-*.md` deep-dive |
 | build or modify any page, dialog, or block | [`docs/design.md`](docs/design.md) — its Core Constraints apply to *every* UI change, not only new pages |
 | add or change localized content | [`docs/translation.md`](docs/translation.md) — plus the matching `docs/references/terminology-<locale>.md` when one exists |

From 7d7e268da56b1a3598007718074d09cce5386088 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Tue, 11 Aug 2026 03:46:56 +0900
Subject: [PATCH 5/6] Update AGENTS.md

---
 AGENTS.md | 169 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 115 insertions(+), 54 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 98fbc8aed..082976722 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,58 +1,102 @@
 # Repository Guidelines
 
-This is the repo-wide contract for AI coding agents. It owns **engineering principles** and the **architecture quick-map** only. Concrete mechanics belong to the routed docs below. Compatibility instruction entry points reuse this file and do not maintain a second contract.
-
-Use [`docs/README.md`](docs/README.md) as the document index. When a routed document owns a concern, follow that document and link to it rather than copying its content here.
+This is the repo-wide contract for AI coding agents. It owns only engineering principles and the architecture
+quick-map; concrete mechanics belong to the routed docs. Compatibility entry points reuse this file and have
+no separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of
+duplicating its rules.
 
 ## Route the task before acting
 
 | Before you… | Read |
 | --- | --- |
-| write any code | [`docs/develop.md`](docs/develop.md) |
-| review code or a pull request | [`docs/develop.md`](docs/develop.md) — plus [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules |
-| change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) — plus the relevant `docs/references/architecture-*.md` deep-dive |
-| build or modify any page, dialog, or block | [`docs/design.md`](docs/design.md) — its Core Constraints apply to *every* UI change, not only new pages |
-| add or change localized content | [`docs/translation.md`](docs/translation.md) — plus the matching `docs/references/terminology-<locale>.md` when one exists |
-| add, edit, reorganize, or review any tracked contributor Markdown (this file, `docs/*`, `.github/*.md`, package- and source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — *if you can't grep it on this branch, don't claim it* |
+| write code | [`docs/develop.md`](docs/develop.md) |
+| review code or a pull request | [`docs/develop.md`](docs/develop.md) + [`docs/pull-request.md`](docs/pull-request.md) for PR-body rules |
+| change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` |
+| build or modify a page, dialog, or block | [`docs/design.md`](docs/design.md) — Core Constraints apply to every UI change |
+| add or change localized content | [`docs/translation.md`](docs/translation.md) + matching `docs/references/terminology-<locale>.md` when present |
+| add, edit, reorganize, or review tracked contributor Markdown (`AGENTS.md`, `docs/*`, `.github/*.md`, package/source-local READMEs) | [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md) — if you can't grep it on this branch, don't claim it |
 | open or update a pull request | [`docs/pull-request.md`](docs/pull-request.md) |
-| manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — a throwaway scratch script against the built extension, not the committed suite |
+| manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — use a throwaway scratch script against the built extension, not the committed suite |
 
-For a task that spans several rows, read each applicable owner before performing that part of the task; do not front-load unrelated docs just because they might become relevant later. For a task that fits none of them cleanly, inspect `docs/README.md` and the nearby implementation/tests before inventing a new rule or abstraction.
+For tasks matching multiple rows, read every applicable owner before that work; do not front-load unrelated
+docs. For tasks matching none, inspect `docs/README.md` and nearby implementation/tests before inventing a rule
+or abstraction.
 
 ## Project Overview
 
-ScriptCat — Manifest V3 browser extension that runs Tampermonkey-compatible user scripts. TypeScript + React 19 + Rspack. Package manager is **pnpm** (preinstall enforces). The presentation layer (`src/pages/`) is **shadcn/ui + Tailwind CSS v4** (migrated from Arco Design + UnoCSS).
+ScriptCat is a Manifest V3 browser extension for Tampermonkey-compatible user scripts, built with TypeScript,
+React 19, and Rspack. **pnpm** is required by `preinstall`. The presentation layer (`src/pages/`) uses shadcn/ui
+and Tailwind CSS v4 (migrated from Arco Design + UnoCSS).
 
 ## Engineering Principles
 
-These are the repo-wide defaults. When a principle links to a narrow, explicit exception in its owning document, that exception is part of the same contract; unrelated or unlinked downstream prose does not silently override the principle.
-
-- **Fix root causes, not symptoms — refactor over patch.** No `as any` / `// @ts-ignore` / try-catch swallow / defensive skips to make errors disappear (宁愿重构也不要打补丁). If a test fails, fix the code, not the test — the narrow exceptions (a wrong test contract; a test that never carried value) are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
-- **Confirm before you fix.** Before touching a reported bug, reproduce it and confirm it actually exists — never fix from assumption. Capture the reproduction, then fix, **in that order** (确定 bug 存在 → 写测试或记录验证证据 → 修复); how to reproduce and what counts as capture are in [`docs/verification.md`](docs/verification.md) and the TDD entry below.
-- **TDD/BDD first, for changes that alter observable behavior.** Write failing tests **before** implementing new or changed behavior, using BDD-style `describe`/`it` titles (Chinese or English). Two narrow exceptions — neither a blanket file/task category — are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#when-tdd-doesnt-apply). (Runner, mocks, and how to run tests are in `docs/develop.md`.)
-- **SOLID, high cohesion & low coupling — applied to the existing extension points.** Persistence is a small backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / a few custom repos), not one pattern to default to — pick by matching an existing entity with the same needs; see [`docs/references/architecture-data.md`](docs/references/architecture-data.md#adding-an-entity). For messages, use `Group.on(...)`. Not every service takes the same constructor shape — context services vs. the Agent subsystem differ; see [`docs/references/architecture-services.md`](docs/references/architecture-services.md#adding-a-service). Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
-- **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime.
-- **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. Don't remove or narrow currently supported behavior just to simplify a fix — only do so when the task or an already-verified contract explicitly calls for that change. This rule also governs test cleanup — [`docs/references/develop-testing.md`](docs/references/develop-testing.md#scope--cleanup-boundary) operationalizes it for tests, it does not carve out an exception.
-- **No dead code or `// removed` markers** — git remembers. Delete unused code outright.
-- **Comments explain "why", not "what".** Do not use ephemeral review labels such as `finding N` or review-round identifiers in comments or test names. Permanent issue or PR references are allowed when useful, but must supplement—not replace—the explanation. Do not restate code, duplicate enclosing documentation, or leave stale comments after code changes. See [`docs/develop.md`](docs/develop.md#comment-discipline) for the full policy.
+These are repo-wide defaults. A linked, narrow exception in its owning doc is part of the contract; unrelated
+downstream prose does not override it.
+
+- **Fix root causes, not symptoms — refactor over patch.** No `as any`, `// @ts-ignore`, swallowed errors, or
+  defensive skips or try-catch swallowing (宁愿重构也不要打补丁). When a test fails, fix the code rather than the test, except for a wrong
+  test contract or valueless test as defined in
+  [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
+- **Confirm before fixing.** Reproduce and confirm a reported bug before changing it; capture the reproduction
+  first (确定 bug 存在 → 写测试或记录验证证据 → 修复). Use [`docs/verification.md`](docs/verification.md) and
+  the TDD principle in this section for the evidence standard.
+- **TDD/BDD first for observable behavior.** Write a failing `describe`/`it` test before implementation, with
+  Chinese or English titles. The two narrow, non-blanket exceptions are in
+  [`docs/references/develop-testing.md`](docs/references/develop-testing.md#when-tdd-doesnt-apply); runner,
+  mocks, and how to run tests are in [`docs/develop.md`](docs/develop.md).
+- **SOLID, high cohesion, low coupling.** Match existing extension points: persistence uses the small
+  `Repo<T>` / `DAO<T>` / `OPFSRepo` / custom-repo taxonomy, matching an existing entity with the same needs;
+  messages use `Group.on(...)`; service constructor shapes differ by context and Agent subsystem; depend on
+  narrow interfaces such as `IMessageQueue`, not `MessageQueue`. See
+  [`docs/references/architecture-data.md`](docs/references/architecture-data.md#adding-an-entity),
+  [`docs/references/architecture-services.md`](docs/references/architecture-services.md#adding-a-service).
+- **Direct replacement over adapter sandwiches.** Replace a backend/library in place; add
+  `interface Foo + LegacyImpl + NewImpl` only when both must coexist at runtime.
+- **Scope discipline.** Bug fix ≠ cleanup PR: touch only required files (不要动和任务不相干的文件), add no unneeded
+  helpers/abstractions/validation/backwards-compat shims, and prefer three similar lines to a premature abstraction.
+  Do not remove or narrow supported
+  behavior for simplification unless the task or an already-verified contract explicitly calls for it. The same boundary applies to
+  test cleanup; see [`docs/references/develop-testing.md`](docs/references/develop-testing.md#scope--cleanup-boundary).
+- **No dead code or `// removed` markers.** Delete unused code; git remembers.
+- **Comments explain why.** Do not restate code, duplicate enclosing documentation, leave stale comments, or use
+  ephemeral review-round labels such as `finding N` in comments or test names. Permanent issue/PR references may
+  supplement, not replace, the explanation. See
+  [`docs/develop.md`](docs/develop.md#comment-discipline).
 
 ## Decision and review discipline
 
-- **Evidence before conclusion.** A request or maintainer direction authorizes scoped work; it does not prove a reported bug, necessity, or correctness. Separate execution authority, stated context, observations, and the normative specification or accepted contract. State when a material claim is inferred, unverified, or contradicted.
-- **Rationale before implementation summary.** For a material change, connect the observable problem or requirement, affected scope and consequence, why action is justified, the selected remedy, acceptance evidence, and remaining limitation. The diff shows what changed; it does not prove why the change was necessary.
-- **Smallest justified semantic scope, not smallest diff.** A larger refactor is appropriate when it is the smallest sound root-cause repair. Do not call a solution minimal, best, or least risky without comparative support.
-- **Claim strength follows evidence.** Source reasoning, an executed test, browser runtime, and an external integration run prove different scopes. A negative claim requires observation of the relevant channel through its closure window or a causal proof that the side effect cannot occur.
-- **Agent readiness is bounded.** An agent must not present a material change as review-ready when acceptance fails, a critical contradiction or evidence gap remains, the scope is unjustified, or final-patch evidence is stale. An explicitly requested draft or investigation may proceed when labeled as such; report the blocker and the condition that would clear it.
-- **Review coverage is semantic as well as physical.** Inspect every changed file and follow affected paths. Map material semantic families to representatives, disposition, highest-risk seam, and residual risk; distinguish confidence in a finding from completeness of the declared scope. On re-review, bind the current head and reconcile findings as still present, resolved, narrowed, stale, or new.
-- **Findings need a witness and impact.** Report a finding only with a concrete trigger or proof path, a material consequence, a useful location, and an actionable contract to restore. Do not turn an unverified repository-specific assumption into a finding.
+- **Separate authority from evidence.** A request or maintainer direction is execution authority within scope;
+  issues/PRs provide stated intent and context; source inspection, tests, browser runs, and integrations provide
+  observations; normative specifications, compatibility contracts, security policies, accepted contracts or oracles, and
+  maintainer decisions determine correctness. A request/issue/PR does not prove a bug, necessity, or correctness.
+  Label inferences, unverified, and contradicted claims.
+- **State rationale before summary.** For material changes, connect problem/requirement → affected
+  scope/consequence → premise evidence → justification → remedy/trade-off → acceptance evidence → limitation/risk.
+  A diff shows what changed, not why.
+- **Use the smallest justified semantic scope, not smallest diff.** A larger refactor is valid when it is the
+  smallest sound root-cause repair; do not call a solution minimal, best, or least risky without support.
+- **Match claim strength to evidence.** Static reasoning, executed tests, browser runs, and external integrations
+  prove different scopes. A negative claim needs the relevant channel observed through its closure window or a
+  causal proof that the side effect cannot occur.
+- **Bound readiness.** Do not call a material change review-ready with failed acceptance, a critical contradiction
+  or evidence gap, unjustified scope, or stale final-patch evidence. A requested draft/investigation may proceed
+  when labeled; report the blocker and clearing condition.
+- **Review semantic and physical coverage.** Inspect every changed file and affected path. Map material semantic
+  families to representatives, disposition, highest-risk seam, and residual risk; separate confidence from
+  completeness. On re-review, bind the current head and reconcile findings as present, resolved, narrowed, stale,
+  or new.
+- **Require a witness and impact for findings.** Report only a concrete trigger/proof path, material consequence,
+  useful location, and actionable contract to restore; do not turn an unverified repository assumption into a
+  finding.
 
 ## Architecture
 
-This is an orientation map, not an implementation manual. Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or adding a subsystem.
+Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or
+adding a subsystem. This section is orientation, not an implementation manual.
 
 ### Multi-Process Model
 
-5 isolated contexts communicating via message passing:
+5 isolated contexts communicate by message passing:
 
 ```text
 Service Worker (src/service_worker.ts)
@@ -66,42 +110,59 @@ Service Worker (src/service_worker.ts)
 > `EventPageOffscreenManager` on Firefox MV3; Offscreen replies to SW over `ExtensionMessage`. `WindowMessage`
 > is the Offscreen ↔ Sandbox channel.
 
-- **Service Worker** — central hub: script CRUD, chrome APIs, permission verification, resource caching, message routing
-- **Content** — bridges SW and inject script
-- **Inject** — runs in page context with `unsafeWindow`
-- **Offscreen** — DOM-capable background environment for background/scheduled scripts
-- **Sandbox** — isolated execution via `with(arguments[0])`; cron scheduling
+- **Service Worker** — central hub for script CRUD, Chrome APIs, permission verification, resource caching, and message routing.
+- **Content** — bridges SW and inject script.
+- **Inject** — runs in page context with `unsafeWindow`.
+- **Offscreen** — DOM-capable background environment for background/scheduled scripts.
+- **Sandbox** — isolated execution via `with(arguments[0])`; cron scheduling.
 
-Execution paths: page scripts → `chrome.userScripts`; background → SW → Offscreen → Sandbox; scheduled → cron in Sandbox.
+Execution paths: page scripts → `chrome.userScripts`; background → SW → Offscreen → Sandbox; scheduled → cron in
+Sandbox.
 
 ### Message Passing (`packages/message/`)
 
-`ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔ Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome), `CustomEventMessage` (CustomEvent — Content ↔ Inject), `MessageQueue` (cross-context broadcast).
+`ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔
+Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome),
+`CustomEventMessage` (CustomEvent — Content ↔ Inject), and `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers
 
-- Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/`) plus **cross-cutting subsystems** (`agent/`, `extension/`, `queue.ts`) — not one uniform shape. Details, inventory, "adding a service": [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
-- Persistence is a backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / custom), not one pattern. Details, inventory, "adding an entity": [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
-- **GM API** split across content / SW / offscreen, each a `GMApi`; values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
-- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five contexts, not a sixth. Full write-up: [`docs/references/architecture-agent.md`](docs/references/architecture-agent.md).
+- Services live under `src/app/service/` as context services (`content/`, `offscreen/`, `sandbox/`,
+  `service_worker/`) plus cross-cutting subsystems (`agent/`, `extension/`, `queue.ts`), not one uniform shape. See
+  [`docs/references/architecture-services.md`](docs/references/architecture-services.md#adding-a-service) for inventory and adding services.
+- Persistence is a backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / custom), not one default pattern. See
+  [`docs/references/architecture-data.md`](docs/references/architecture-data.md#adding-an-entity) for inventory and adding entities.
+- **GM API** is split across content / SW / offscreen, each with a `GMApi`; values use `ValueService`. See
+  [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md) for additions.
+- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the five contexts, not a sixth. See
+  [`docs/references/architecture-agent.md`](docs/references/architecture-agent.md).
 
 ### Browser Extension APIs (MV3)
 
-`chrome.userScripts` (page injection), Offscreen API (DOM in background), Declarative Net Request (intercepts `.user.js` URLs to trigger install flow).
+`chrome.userScripts` (page injection), Offscreen API (DOM in background), and Declarative Net Request (intercepts
+`.user.js` URLs to trigger installation).
 
 ### Key Packages
 
-`message/` (with mocks), `filesystem/` (WebDAV, cloud drive providers, zip export — see [`docs/cloud-sync.md`](docs/cloud-sync.md)), `cloudscript/`, `eslint/` (userscript lint config — `eslint-plugin-userscripts`-based `defaultConfig` for the in-app editor), `chrome-extension-mock/`.
-
-The project's *own* custom ESLint rules live in `eslint-rules/` at the repo root, **not** in `packages/eslint/`; both are documented in [`docs/develop.md`](docs/develop.md#eslint-custom-rules).
+`message/` (with mocks), `filesystem/` (WebDAV, cloud-drive providers, ZIP export; see
+[`docs/cloud-sync.md`](docs/cloud-sync.md)), `cloudscript/`, `eslint/` (userscript lint config based on
+`eslint-plugin-userscripts` and `defaultConfig` for the in-app editor), and `chrome-extension-mock/`. The project's own custom ESLint
+rules live in root `eslint-rules/`, not `packages/eslint/`; both are documented in
+[`docs/develop.md`](docs/develop.md#eslint-custom-rules).
 
 ## Completion checksum
 
-Before claiming a task is complete, use the applicable owner docs above to verify the final state. This section is a handoff checklist, not a second copy of their mechanics; when a detail matters, the linked owner wins. If an item cannot be checked, report the limitation instead of upgrading the claim to “verified” or “all fixed.”
-
-- **Owners:** every part of the task was checked against its applicable routed owner; documentation work follows [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md).
-- **Evidence:** reproduction, tests, and manual evidence satisfy the applicable rules in [`docs/references/develop-testing.md`](docs/references/develop-testing.md) and [`docs/verification.md`](docs/verification.md), including any explicit exception used.
-- **Contract & scope:** the final diff still matches the requested/verified behavior and the scope-discipline principles above; no unrelated compatibility layer or cleanup slipped in.
-- **Extension point:** architecture-sensitive changes were checked against [`docs/architecture.md`](docs/architecture.md) and the relevant deep-dive instead of creating a parallel abstraction from memory.
-- **Facts:** changed documentation claims were checked using the branch-aware process in [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md), not memory or untracked files.
-- **Verification:** the checks required by the applicable owner docs were run, and any environment/tooling blocker is stated explicitly in the completion report or PR.
+Before claiming completion, use the applicable owner docs to check the final state. This is a handoff checklist, not
+a second copy of their mechanics; when details matter, linked owners win. If a check cannot be completed, state the
+limitation instead of claiming “verified” or “all fixed” without evidence.
+
+- **Owners/facts.** Every task part follows its routed owner; changed documentation follows
+  [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md), including branch-aware fact checks against committed
+  code, not memory or untracked files.
+- **Evidence/verification.** Reproduction, tests, manual evidence, and the applicable rules in
+  [`docs/references/develop-testing.md`](docs/references/develop-testing.md) and [`docs/verification.md`](docs/verification.md)
+  support the claim, including any explicit exception; run required checks and report blockers or tooling limits.
+- **Contract/scope.** The final diff matches the requested or verified behavior, contains no unrelated cleanup or
+  compatibility layer, and preserves scope discipline.
+- **Architecture.** Boundary-sensitive work was checked against [`docs/architecture.md`](docs/architecture.md) and
+  the relevant deep-dive rather than inventing a parallel abstraction.

From ea597c28edbd94a054b7b0e9b07c9684b08877a6 Mon Sep 17 00:00:00 2001
From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com>
Date: Tue, 11 Aug 2026 04:46:48 +0900
Subject: [PATCH 6/6] Update check-issue-templates.test.mjs

---
 scripts/check-issue-templates.test.mjs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/check-issue-templates.test.mjs b/scripts/check-issue-templates.test.mjs
index b2b1f5145..28be8d58d 100644
--- a/scripts/check-issue-templates.test.mjs
+++ b/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([]);
   });