From fa1cd11fc9b3fe46b771357e898e3c82ff4cb9db Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:19:18 +0900 Subject: [PATCH 01/14] docs: agent found dependencies missing in local but don't know how to fix --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 64ed8efcd..cdcc89301 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,10 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. +## Local Coding Environment +* Run `pnpm install` if dependencies are absent, invalid or stale. +* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. + ## Route the task before acting | Before you… | Read | From 6aadf84916699f12e1a4739ca145944542306928 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:26:20 +0900 Subject: [PATCH 02/14] =?UTF-8?q?=F0=9F=93=84=20=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E6=9C=AC=E5=9C=B0=E4=BE=9D=E8=B5=96=E5=AE=89=E8=A3=85=E6=8C=87?= =?UTF-8?q?=E5=BC=95=E4=B8=8E=E9=A1=B9=E7=9B=AE=E8=84=9A=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cdcc89301..c38853b3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ duplicating its rules. ## Local Coding Environment * Run `pnpm install` if dependencies are absent, invalid or stale. -* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. +* Run `pnpm run test:e2e:install` if Playwright Chromium is absent or stale. ## Route the task before acting From 10a82064035263fccb4acde0bf603dfcefd9060c Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:36:44 +0900 Subject: [PATCH 03/14] =?UTF-8?q?=F0=9F=93=84=20clarify=20agent=20dependen?= =?UTF-8?q?cy=20setup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cdcc89301..dd681e0d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,21 @@ separate contract. Use [`docs/README.md`](docs/README.md) as the index and follo duplicating its rules. ## Local Coding Environment -* Run `pnpm install` if dependencies are absent, invalid or stale. -* Run `pnpm exec playwright install chromium` if playwright chromium is absent, invalid or stale. + +Before running project commands, make sure the local prerequisites are ready. Treat these as environment +setup steps, not as reasons to change product code: + +1. If `node_modules` is missing or dependencies are invalid or stale, run `pnpm install`. Use the package + manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local + setup. +2. If an end-to-end test reports that the Playwright browser is missing or unusable, run + `pnpm run test:e2e:install` after dependency installation. This is a separate prerequisite from + `pnpm install` and is safe to rerun. +3. Retry the original command after setup. If setup is blocked by network, permission, or tool availability, + report the setup command and relevant error as an environment blocker; do not alter the lockfile or hide the + failure with a workaround. + +The complete command list and test mechanics are owned by [`docs/develop.md`](docs/develop.md). ## Route the task before acting From a99b53485c43f2dad15b78b199150e10d9837bce Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:48:50 +0900 Subject: [PATCH 04/14] =?UTF-8?q?=F0=9F=93=84=20split=20agent=20environmen?= =?UTF-8?q?t=20recovery=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 27 +++++++++++---------------- docs/develop.md | 13 +++++++++++++ 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dd681e0d5..1f28404f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,22 +5,17 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. -## Local Coding Environment - -Before running project commands, make sure the local prerequisites are ready. Treat these as environment -setup steps, not as reasons to change product code: - -1. If `node_modules` is missing or dependencies are invalid or stale, run `pnpm install`. Use the package - manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local - setup. -2. If an end-to-end test reports that the Playwright browser is missing or unusable, run - `pnpm run test:e2e:install` after dependency installation. This is a separate prerequisite from - `pnpm install` and is safe to rerun. -3. Retry the original command after setup. If setup is blocked by network, permission, or tool availability, - report the setup command and relevant error as an environment blocker; do not alter the lockfile or hide the - failure with a workaround. - -The complete command list and test mechanics are owned by [`docs/develop.md`](docs/develop.md). +## Environment Setup and Recovery + +Before running project commands, resolve missing prerequisites: + +1. Missing, invalid, or stale dependencies: run `pnpm install`. +2. Missing or unusable Playwright Chromium: after dependency installation, run `pnpm run test:e2e:install`. +3. Retry the original command. If setup is blocked by network, permission, or tool availability, report it as + an environment blocker instead of changing product code. + +See [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) for the +package-manager, lockfile, and failure-handling boundaries. ## Route the task before acting diff --git a/docs/develop.md b/docs/develop.md index 5696ca0c7..5f6600a27 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -29,6 +29,19 @@ pnpm run check:i18n # translation key parity (see docs/translation. pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, issues/new prefill ids ``` +### Environment Setup and Recovery + +Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change +product code: + +- Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by + this repository; do not switch to npm/yarn or manually add packages to repair a local setup. +- After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that + Playwright Chromium is missing or unusable. The command is safe to rerun. +- Retry the original command after setup. If network, permission, or tool availability blocks setup, report the + exact command and relevant error as an environment blocker; do not alter the lockfile or hide the failure with + a workaround. + No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs `check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript From af20796559c5796b89ea5c644b47e018f1405843 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:53:42 +0900 Subject: [PATCH 05/14] =?UTF-8?q?=F0=9F=93=84=20keep=20environment=20recov?= =?UTF-8?q?ery=20in=20its=20owner=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1f28404f5..7e8dfe48b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,23 +5,12 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. -## Environment Setup and Recovery - -Before running project commands, resolve missing prerequisites: - -1. Missing, invalid, or stale dependencies: run `pnpm install`. -2. Missing or unusable Playwright Chromium: after dependency installation, run `pnpm run test:e2e:install`. -3. Retry the original command. If setup is blocked by network, permission, or tool availability, report it as - an environment blocker instead of changing product code. - -See [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) for the -package-manager, lockfile, and failure-handling boundaries. - ## Route the task before acting | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | +| recover from missing dependencies or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | 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 | From a766c885b668deb2b315deb803f1f65c2f9ccca2 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 06:56:46 +0900 Subject: [PATCH 06/14] =?UTF-8?q?=F0=9F=93=84=20cover=20package=20manager?= =?UTF-8?q?=20bootstrap=20recovery?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- docs/develop.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7e8dfe48b..fad091feb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ duplicating its rules. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | -| recover from missing dependencies or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | +| recover from package-manager, dependency, or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | 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 | diff --git a/docs/develop.md b/docs/develop.md index 5f6600a27..7fa0e0924 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -34,6 +34,9 @@ pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change product code: +- If `pnpm` is unavailable, use the repository-declared package manager through Corepack when `corepack` is + available: run `corepack enable`, then `corepack install`, and verify with `pnpm --version`. If Corepack is also + unavailable or setup fails, report the command and error as an environment blocker; do not switch to npm/yarn. - Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by this repository; do not switch to npm/yarn or manually add packages to repair a local setup. - After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that From 0a6d1df68a2822d7e6e6f0762ac0ea7c1626b27b Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:00:44 +0900 Subject: [PATCH 07/14] =?UTF-8?q?=F0=9F=93=84=20preserve=20development=20c?= =?UTF-8?q?ommand=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 7fa0e0924..8bbf9b099 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -29,6 +29,17 @@ pnpm run check:i18n # translation key parity (see docs/translation. pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, issues/new prefill ids ``` +No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky +pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs +`check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript +are staged, and also runs `pnpm run test:ci` when committing on `main` or `release/*`. + +`check:issue-templates` guards a contract that is invisible in review: GitHub prefills an issue form from +`issues/new?...` query params keyed by **field id**, so renaming or deleting an id silently breaks every link +using it — including links already shipped in installed builds, which keep sending the old param name. + +After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension. + ### Environment Setup and Recovery Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change @@ -45,17 +56,6 @@ product code: exact command and relevant error as an environment blocker; do not alter the lockfile or hide the failure with a workaround. -No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky -pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs -`check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript -are staged, and also runs `pnpm run test:ci` when committing on `main` or `release/*`. - -`check:issue-templates` guards a contract that is invisible in review: GitHub prefills an issue form from -`issues/new?...` query params keyed by **field id**, so renaming or deleting an id silently breaks every link -using it — including links already shipped in installed builds, which keep sending the old param name. - -After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension. - ### External Access (`external_access/` subsystem) External Access — the user-facing "外部接入 / External Access" feature From 9d7a07dd74d7122fa42f0b7f608ec5d675c0371b Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 22 Aug 2026 07:45:03 +0900 Subject: [PATCH 08/14] =?UTF-8?q?=F0=9F=93=84=20route=20project=20commands?= =?UTF-8?q?=20to=20development=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + docs/develop.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index fad091feb..0ca329665 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ duplicating its rules. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | +| run project commands | [`docs/develop.md`](docs/develop.md) | | recover from package-manager, dependency, or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | 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` | diff --git a/docs/develop.md b/docs/develop.md index 8bbf9b099..091d7ec0e 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -49,7 +49,9 @@ product code: available: run `corepack enable`, then `corepack install`, and verify with `pnpm --version`. If Corepack is also unavailable or setup fails, report the command and error as an environment blocker; do not switch to npm/yarn. - Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by - this repository; do not switch to npm/yarn or manually add packages to repair a local setup. + this repository; do not switch to npm/yarn or manually add packages to repair a local setup. If `pnpm install` + changes `pnpm-lock.yaml`, stop and report the mismatch; do not commit that lockfile change as environment + recovery. - After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that Playwright Chromium is missing or unusable. The command is safe to rerun. - Retry the original command after setup. If network, permission, or tool availability blocks setup, report the From 15f1b28162a680eb6c42c5b0b4b928600b072e38 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 20:46:17 +0900 Subject: [PATCH 09/14] =?UTF-8?q?=F0=9F=93=84=20=E7=B2=BE=E7=AE=80?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=91=BD=E4=BB=A4=E8=B7=AF=E7=94=B1=E4=B8=8A?= =?UTF-8?q?=E4=B8=8B=E6=96=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 - docs/develop.md | 54 ++++++++++++++++++++++++++++++++----------------- 2 files changed, 35 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ca329665..007b0238d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,6 @@ duplicating its rules. | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | | run project commands | [`docs/develop.md`](docs/develop.md) | -| recover from package-manager, dependency, or Playwright browser errors | [`docs/develop.md#environment-setup-and-recovery`](docs/develop.md#environment-setup-and-recovery) | | 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 | diff --git a/docs/develop.md b/docs/develop.md index 091d7ec0e..8b1f5040a 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -21,7 +21,7 @@ pnpm run coverage pnpm run typecheck # tsc --noEmit pnpm run test:e2e:install # install Playwright Chromium (first run only) -pnpm run test:e2e # Playwright (e2e/*.spec.ts, 1 worker) +pnpm run test:e2e # Playwright (e2e/*.spec.ts; worker count comes from playwright.config.ts) pnpm run lint # prettier --check + tsc --noEmit + check:i18n + check:issue-templates, then eslint pnpm run lint-fix # prettier --write + tsc --noEmit + eslint --fix @@ -40,24 +40,6 @@ using it — including links already shipped in installed builds, which keep sen After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension. -### Environment Setup and Recovery - -Dependency installation and Playwright browser installation are separate prerequisites, not reasons to change -product code: - -- If `pnpm` is unavailable, use the repository-declared package manager through Corepack when `corepack` is - available: run `corepack enable`, then `corepack install`, and verify with `pnpm --version`. If Corepack is also - unavailable or setup fails, report the command and error as an environment blocker; do not switch to npm/yarn. -- Use `pnpm install` for missing, invalid, or stale Node dependencies. Follow the package manager declared by - this repository; do not switch to npm/yarn or manually add packages to repair a local setup. If `pnpm install` - changes `pnpm-lock.yaml`, stop and report the mismatch; do not commit that lockfile change as environment - recovery. -- After dependencies are installed, use `pnpm run test:e2e:install` when an end-to-end test reports that - Playwright Chromium is missing or unusable. The command is safe to rerun. -- Retry the original command after setup. If network, permission, or tool availability blocks setup, report the - exact command and relevant error as an environment blocker; do not alter the lockfile or hide the failure with - a workaround. - ### External Access (`external_access/` subsystem) External Access — the user-facing "外部接入 / External Access" feature @@ -198,4 +180,38 @@ Work from a feature branch or fork and open PRs against `main`. Chinese PR title Use `.github/pull_request_template.md` as the starting point. It is intentionally lightweight for human-authored PRs; agents should preserve its checklist and expand `Description / 描述` only when useful. The detailed structure is defined in [`pull-request.md`](./pull-request.md). Keep exact commands and results in `验证`, describe UI evidence when the change is visual, and do not claim checks or evidence that did not happen. +### Revision, Scope, and Publication Binding + +Before reviewing or reporting a branch or pull request, or creating/updating a pull request or pushing its +branch, bind the artifact, revision, and scope to the current remote state: + +1. Identify the target. For a live pull request, read its metadata and record its repository, base branch, head + branch, and head SHA. If only a local branch or commit is available, record its SHA and label all results + local-only; do not call them final pull-request evidence. +2. Fetch the current base and relevant head refs before choosing the parent or diff. For a new pull request, + fetch `origin/main` and branch from that ref. For an existing pull request, fetch the recorded head repository + and branch. +3. Compare the local SHA used for review or publication with the live branch/PR head using `git rev-parse HEAD`, + `git ls-remote refs/heads/` when a remote head exists, and the live pull-request + metadata. A local `HEAD` or tracking ref is not evidence of the pull-request head. If any identity differs, + stop, rebind the worktree and diff, and rerun the review before continuing. +4. For a live pull request, derive review conclusions and inclusion/exclusion claims from the live base-to-head + diff, including changed paths and patch content. Apply the final-diff rule in + [`pull-request.md#scope-claims-and-final-diff-evidence`](./pull-request.md#scope-claims-and-final-diff-evidence); + branch ancestry, intention, and an earlier local check are insufficient. +5. Before publication, require `git status --short --branch`, a named non-detached branch, and `git rev-parse + HEAD`; re-read the remote head immediately before pushing. Push normally only when the expected head is + unchanged. Never overwrite an unexpected or unreviewed remote commit. If the user explicitly authorizes a + rewrite, bind the current remote head, use a lease-protected force update against that exact SHA, and verify + the remote ref after pushing. +6. Before reporting results or changing pull-request metadata, re-read the live pull request and bind every claim + to its returned head SHA. Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim + edit invalidates earlier evidence; rerun the affected review, checks, and final-diff audit. + +The same binding applies to the scope you declared for your own change. A commit's gitmoji type and title, and the +task statement they serve, name a scope class; compare the final diff against that class before committing or +pushing. Move anything outside it into its own commit with its own justification, or restate the scope. A +production behavior change that arrives inside a test-cleanup or refactor commit is not reviewable as either, and +stays unreviewable no matter how correct it is on its own. + **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. From c9b2d83071da6a5fd886fbe1831c0af354278ad1 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 20:46:57 +0900 Subject: [PATCH 10/14] =?UTF-8?q?=F0=9F=93=84=20=E4=BF=9D=E6=8C=81?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3=E4=B8=8E=20PR=20=E5=9F=BA?= =?UTF-8?q?=E7=BA=BF=E4=B8=80=E8=87=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 36 +----------------------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 8b1f5040a..5696ca0c7 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -21,7 +21,7 @@ pnpm run coverage pnpm run typecheck # tsc --noEmit pnpm run test:e2e:install # install Playwright Chromium (first run only) -pnpm run test:e2e # Playwright (e2e/*.spec.ts; worker count comes from playwright.config.ts) +pnpm run test:e2e # Playwright (e2e/*.spec.ts, 1 worker) pnpm run lint # prettier --check + tsc --noEmit + check:i18n + check:issue-templates, then eslint pnpm run lint-fix # prettier --write + tsc --noEmit + eslint --fix @@ -180,38 +180,4 @@ Work from a feature branch or fork and open PRs against `main`. Chinese PR title Use `.github/pull_request_template.md` as the starting point. It is intentionally lightweight for human-authored PRs; agents should preserve its checklist and expand `Description / 描述` only when useful. The detailed structure is defined in [`pull-request.md`](./pull-request.md). Keep exact commands and results in `验证`, describe UI evidence when the change is visual, and do not claim checks or evidence that did not happen. -### Revision, Scope, and Publication Binding - -Before reviewing or reporting a branch or pull request, or creating/updating a pull request or pushing its -branch, bind the artifact, revision, and scope to the current remote state: - -1. Identify the target. For a live pull request, read its metadata and record its repository, base branch, head - branch, and head SHA. If only a local branch or commit is available, record its SHA and label all results - local-only; do not call them final pull-request evidence. -2. Fetch the current base and relevant head refs before choosing the parent or diff. For a new pull request, - fetch `origin/main` and branch from that ref. For an existing pull request, fetch the recorded head repository - and branch. -3. Compare the local SHA used for review or publication with the live branch/PR head using `git rev-parse HEAD`, - `git ls-remote refs/heads/` when a remote head exists, and the live pull-request - metadata. A local `HEAD` or tracking ref is not evidence of the pull-request head. If any identity differs, - stop, rebind the worktree and diff, and rerun the review before continuing. -4. For a live pull request, derive review conclusions and inclusion/exclusion claims from the live base-to-head - diff, including changed paths and patch content. Apply the final-diff rule in - [`pull-request.md#scope-claims-and-final-diff-evidence`](./pull-request.md#scope-claims-and-final-diff-evidence); - branch ancestry, intention, and an earlier local check are insufficient. -5. Before publication, require `git status --short --branch`, a named non-detached branch, and `git rev-parse - HEAD`; re-read the remote head immediately before pushing. Push normally only when the expected head is - unchanged. Never overwrite an unexpected or unreviewed remote commit. If the user explicitly authorizes a - rewrite, bind the current remote head, use a lease-protected force update against that exact SHA, and verify - the remote ref after pushing. -6. Before reporting results or changing pull-request metadata, re-read the live pull request and bind every claim - to its returned head SHA. Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim - edit invalidates earlier evidence; rerun the affected review, checks, and final-diff audit. - -The same binding applies to the scope you declared for your own change. A commit's gitmoji type and title, and the -task statement they serve, name a scope class; compare the final diff against that class before committing or -pushing. Move anything outside it into its own commit with its own justification, or restate the scope. A -production behavior change that arrives inside a test-cleanup or refactor commit is not reviewable as either, and -stays unreviewable no matter how correct it is on its own. - **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. From 9e5241deee9d8ead05e41789788ef972c232a9cb Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:12:02 +0900 Subject: [PATCH 11/14] =?UTF-8?q?=F0=9F=93=84=20route=20project=20commands?= =?UTF-8?q?=20to=20development=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 276d77f20..cb1854163 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ in the change as a named, accepted deviation — never as compliance. | Before you… | Read | | --- | --- | | write code | [`docs/develop.md`](docs/develop.md) | +| run project commands | [`docs/develop.md`](docs/develop.md) | | modify tests, test helpers, or test runner configuration | [`docs/references/develop-testing.md`](docs/references/develop-testing.md) — apply the test-boundary, observation, and harness rules before editing | | review or report a branch/PR, or create/update a PR or publish its branch | [`docs/develop.md#revision-scope-and-publication-binding`](docs/develop.md#revision-scope-and-publication-binding) + [`docs/pull-request.md`](docs/pull-request.md) | | change a process/message/service/persistence boundary or add a subsystem | [`docs/architecture.md`](docs/architecture.md) + the relevant `docs/references/architecture-*.md` | @@ -273,4 +274,4 @@ limitation instead of claiming “verified” or “all fixed” without evidenc - **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. + the relevant deep-dive rather than inventing a parallel abstraction. \ No newline at end of file From 57560896937526b2df6e2440688a518a35fa47c8 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:12:56 +0900 Subject: [PATCH 12/14] =?UTF-8?q?=F0=9F=93=84=20add=20conditional=20enviro?= =?UTF-8?q?nment=20recovery=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 8b1f5040a..cdc3e382f 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -29,6 +29,12 @@ pnpm run check:i18n # translation key parity (see docs/translation. pnpm run check:issue-templates # .github/ISSUE_TEMPLATE schema, zh/en parity, issues/new prefill ids ``` +If a project command fails because a local prerequisite is missing, restore that prerequisite and retry the +original command before reporting it blocked: use `pnpm install` for Node dependencies and +`pnpm run test:e2e:install` for missing Playwright Chromium. If `pnpm` itself is unavailable, activate the +repository-declared pnpm through Corepack when available. If setup cannot succeed or changes tracked files, report +that blocker or mismatch instead of switching package managers or committing recovery changes. + No standalone `format` script — formatting is part of `lint-fix` and runs through `prettier --write`. Husky pre-commit runs `prettier --check` and `pnpm run typecheck` plus ESLint for staged JS/TS files, runs `check:i18n` when locale files are staged and `check:issue-templates` when issue templates or `src/` TypeScript @@ -157,7 +163,6 @@ i18next; extension strings in `src/assets/_locales/`. The current locale list is ## Security & Configuration Tips Do not commit secrets, local certificates, build output, coverage, Playwright reports, test results, or local `.env` changes. - ## Commit & Pull Request Guidelines Commits must be single-purpose and **start with a gitmoji emoji** — use the actual emoji character, not the `:code:` text form, for example `git commit -m "🐛 fix template matching"` or `git commit -m "✨ add script filter"`. The leading emoji drives release changelog grouping (see the `release` skill), so pick the one that matches the change: @@ -214,4 +219,4 @@ pushing. Move anything outside it into its own commit with its own justification production behavior change that arrives inside a test-cleanup or refactor commit is not reviewable as either, and stays unreviewable no matter how correct it is on its own. -**Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. +**Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. \ No newline at end of file From ebe347a4b3a18098e9bb373f6bf67363eb27220a Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:14:06 +0900 Subject: [PATCH 13/14] =?UTF-8?q?=F0=9F=93=84=20preserve=20development=20g?= =?UTF-8?q?uide=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/develop.md b/docs/develop.md index cdc3e382f..f5277a119 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -163,6 +163,7 @@ i18next; extension strings in `src/assets/_locales/`. The current locale list is ## Security & Configuration Tips Do not commit secrets, local certificates, build output, coverage, Playwright reports, test results, or local `.env` changes. + ## Commit & Pull Request Guidelines Commits must be single-purpose and **start with a gitmoji emoji** — use the actual emoji character, not the `:code:` text form, for example `git commit -m "🐛 fix template matching"` or `git commit -m "✨ add script filter"`. The leading emoji drives release changelog grouping (see the `release` skill), so pick the one that matches the change: @@ -219,4 +220,4 @@ pushing. Move anything outside it into its own commit with its own justification production behavior change that arrives inside a test-cleanup or refactor commit is not reviewable as either, and stays unreviewable no matter how correct it is on its own. -**Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. \ No newline at end of file +**Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. From 935a735f49428047d169d1fcbf6edb5cf711489c Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:15:13 +0900 Subject: [PATCH 14/14] =?UTF-8?q?=F0=9F=93=84=20preserve=20agent=20guide?= =?UTF-8?q?=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cb1854163..3d994b2d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -274,4 +274,4 @@ limitation instead of claiming “verified” or “all fixed” without evidenc - **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. \ No newline at end of file + the relevant deep-dive rather than inventing a parallel abstraction.