scriptscat · cyfung1031 · Aug 8, 2026
diff --git 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
@@ -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,19 +64,33 @@ 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
 
 `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.