docs(agents): sync local CI guidance (#5960)

## Summary

- Align GitHub Copilot instructions with the canonical `AGENTS.md` Local
CI guidance: Node/pnpm versions, `pnpm run ci` meaning, and avoiding
builds immediately before unit tests.
- Add tegg-specific Claude guidance for `duplicate proto` failures after
local builds.
- Add a durable wiki workflow page for local CI artifact cleanup and
link it from the wiki index/log.

## Validation

- `pnpm run fmtcheck` passed.
- `git diff --check` passed.
- Pre-commit hook was bypassed for the commit because `oxlint
--type-aware --fix` fails on a markdown-only staged set with `No files
found to lint`; full repo formatting passed before commit.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated contribution workflow guidance (Node.js minimum bumped to **>=
22.18.0**), including a new explicit lint step and revised build vs.
test ordering.
* Refined CI wording to reflect “tests with coverage” and recommended
working from the source tree first.
* Clarified local validation order (lint → tests from clean sources →
build when needed → docs).
* Expanded local CI instructions and troubleshooting for **duplicate
proto** failures by cleaning stale build artifacts, and added a local CI
workflow entry to the release log.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: killagu

.github/copilot-instructions.md

@@ -10,13 +10,13 @@ This is a **pnpm monorepo** with multiple packages using pnpm workspaces and cat
 
 ## Prerequisites and Environment Setup
 
-- **Node.js >= 20.19.0 required** - This is a hard requirement
-- Enable pnpm first: `corepack enable pnpm` (installs pnpm v10.16.0)
+- **Node.js >= 22.18.0 required** - This is a hard requirement
+- Enable pnpm first: `corepack enable pnpm` (uses the `packageManager` version from `package.json`, currently pnpm v10.28.0)
 - **NEVER CANCEL** any build or test commands - they can take several minutes to complete
 
 ## Bootstrap and Build Process
 
-**Always run these commands in sequence after fresh clone:**
+**Run these commands after a fresh clone:**
 
 ```bash
 # 1. Enable pnpm (required first)
@@ -25,13 +25,17 @@ corepack enable pnpm
 # 2. Install all dependencies - takes ~63 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
 pnpm install
 
-# 3. Build all packages - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
-pnpm run build
-
-# 4. Run linting (optional but recommended) - takes ~2 seconds
+# 3. Run pnpm run lint to check code quality across all packages - takes ~2 seconds
 pnpm run lint
+
+# 4. Build all packages when validating build output - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
+pnpm run build
 ```
 
+Run unit tests from a clean source tree, not immediately after `pnpm run build`.
+The main CI test job installs dependencies with `ut install --from pnpm` and
+runs tests with `ut run ci`; it does not run `build` before tests.
+
 ## Monorepo Structure
 
 ### Key Packages (all in `packages/` directory)
@@ -61,7 +65,7 @@ pnpm run lint
 
 - `pnpm run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
 - `pnpm run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
-- `pnpm run ci` - **Run test coverage + build (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
+- `pnpm run ci` - **Run tests with coverage (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
 
 ### Linting Commands
 
@@ -92,7 +96,7 @@ pnpm --filter=site run dev
 
 ### 1. Making Changes
 
-- Always build packages first: `pnpm run build`
+- Work from the source tree first. Build when you need to validate package output, but do not run build immediately before unit tests.
 - Work primarily in `packages/egg/src/` for core framework features
 - Use TypeScript throughout - all packages are TypeScript-based
 - Follow the existing directory conventions in `packages/egg/src/`:
@@ -107,16 +111,16 @@ pnpm --filter=site run dev
 **Always perform these validation steps after making changes:**
 
 ```bash
-# 1. Build all packages (required)
-pnpm run build
-
-# 2. Run linting
+# 1. Run pnpm run lint to check code quality across all packages
 pnpm run lint
 
-# 3. Run tests (some failures are expected in fresh environment)
+# 2. Run tests from a clean tree (some failures are expected in fresh environment)
 pnpm run test
 
-# 4. Test documentation site
+# 3. Build all packages when build output or packaging behavior is relevant
+pnpm run build
+
+# 4. Test documentation site when docs changed
 pnpm run site:dev
 ```
 
@@ -176,10 +180,15 @@ pnpm run site:dev
 - Some tests may fail in fresh environments - this is normal
 - Focus on fixing only failures related to your changes
 - Examples may have runtime issues - don't use them for validation
+- If tegg tests fail with `duplicate proto` after a local build, remove stale
+  `dist/` directories outside fixtures and re-run tests. Built `dist/*.js`
+  files can be scanned alongside `src/*.ts`, loading the same decorated class
+  twice.
 
 ### Build Issues
 
-- Always run `pnpm run build` after making changes
+- Run `pnpm run build` when validating build output, package exports, or changes
+  that affect generated artifacts.
 - TypeScript compilation errors will show clearly
 - Build warnings are generally acceptable
 
@@ -217,12 +226,12 @@ pnpm run site:dev
 
 After making changes, always verify:
 
-1. **Build Success**: `pnpm run build` completes without errors
-2. **Linting Passes**: `pnpm run lint` shows no new errors
+1. **Linting Passes**: `pnpm run lint` shows no new errors
+2. **Tests Run From Clean Sources**: `pnpm run test` executes without stale build artifacts interfering
 3. **Documentation Loads**: `pnpm run site:dev` starts successfully and site loads at http://localhost:8000
-4. **Tests Run**: `pnpm run test` executes (some failures expected, focus on your changes)
+4. **Build Success When Relevant**: `pnpm run build` completes without errors
 
-**Remember**: This is a complex enterprise framework. Always build first, validate incrementally, and focus on the core packages (`egg`, `core`, `utils`) for most development work.
+**Remember**: This is a complex enterprise framework. Validate incrementally, keep unit tests isolated from stale build artifacts, and focus on the core packages (`egg`, `core`, `utils`) for most development work.
 
 ## Commit Message Format
 

AGENTS.md

@@ -18,12 +18,14 @@ Egg is maintained as a pnpm monorepo.
 
 ## Core Commands
 
-- `pnpm install` hydrates the workspace.
-- `pnpm run build` builds all packages.
-- `pnpm run test` runs the main test suite.
-- `pnpm run lint` runs linting.
-- `pnpm run typecheck` runs TypeScript checking.
-- use filtered commands for focused work, for example `pnpm --filter=egg run test` or `pnpm --filter=site run dev`.
+The repository runs on [utoo](https://github.com/utooland/utoo) (`ut`); the workspace is still defined in `pnpm-workspace.yaml` (catalog mode), so `ut install` reads it via `--from pnpm`.
+
+- `ut install --from pnpm` hydrates the workspace.
+- `ut run build` builds all packages.
+- `ut run test` runs the main test suite.
+- `ut run lint` runs linting.
+- `ut run typecheck` runs TypeScript checking.
+- use filtered commands for focused work, for example `ut run test --workspace @eggjs/bin` or `ut run build -- --workspace ./tools/egg-bin`.
 
 ### Local CI
 
@@ -92,7 +94,7 @@ Then re-run tests.
 
 - review `SECURITY.md` before handling vulnerability-related work
 - do not commit secrets, credentials, or local-only URLs
-- keep local Node.js and pnpm versions aligned with the repository configuration
+- keep local Node.js, utoo, and pnpm versions aligned with the repository configuration (`engines.node`, `packageManager`)
 
 ## Shared Knowledge Workflow
 

tegg/CLAUDE.md

@@ -74,6 +74,11 @@ pnpm run test:cov            # Run tests with coverage
 pnpm run ci                  # Full CI: vitest with coverage and bail on first failure
 ```
 
+Run tegg tests from clean sources, not immediately after `pnpm run build`. If
+local tests fail with `duplicate proto` after a build, remove stale `dist/`
+directories outside fixtures as described in the root `AGENTS.md` Local CI
+section, then re-run tests.
+
 **Note:** Tests are configured in the monorepo root `vitest.config.ts` which includes all tegg packages (`tegg/core/*`, `tegg/plugin/*`, `tegg/standalone/*`).
 
 ### Type Checking & Linting

wiki/index.md

@@ -13,6 +13,7 @@ Read this file before exploring raw sources.
 
 - [CI parallel test metrics](./workflows/ci-parallel-test-metrics.md) - How the CI test gate surfaces avg/peak concurrency + parallel-efficiency metrics for the isolate:false suite, and how to read or reproduce them.
 - [Docs and API Updates](./workflows/docs-and-api-updates.md) - How to handle changes that affect user-facing docs or durable project understanding.
+- [Local CI](./workflows/local-ci.md) - Local validation should run tests from clean sources and avoid stale build artifacts before tegg tests.
 - [Egg-bin Windows shell probe hotspot](./workflows/egg-bin-windows-shell-probe.md) - How PR #6014 diagnosed hosted-Windows egg-bin startup slowness and why the final fix only presets SHELL.
 
 ## Decisions

wiki/log.md

@@ -49,6 +49,12 @@ Full **isolate:false suite validated GREEN** under CI-faithful parallelism (`--m
 - pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/concepts/vitest-isolate-false-state-leaks.md`
 - note: Under root `pool:threads` + `isolate:false`, two realm-global leaks caused nondeterministic cross-file/cross-project failures. (1) `setSnapshotModuleLoader` left module-level `_snapshotModuleLoader`/`isESM=false` set (no-op test teardown), poisoning module resolution for later files (`Can not find plugin …`). (2) `mockContext()` reused `currentContext` from a different app, binding helpers to the wrong app config (surl/csrf failures). Fixed both at the source. Full Node-22 suite: 15 → 3 failing files (remaining 2 environmental MySQL/DNS; `multipart/file-mode` is a pre-existing load flake that also fails under `isolate:true`). Reproduce on Node 22/24 with a utoo install — not Node 26 / bare pnpm.
 
+## [2026-06-03] workflow | document local CI artifact cleanup
+
+- sources touched: `AGENTS.md`, `.github/workflows/ci.yml`, `package.json`, `tegg/core/loader/src/impl/ModuleLoader.ts`, `tegg/core/metadata/src/model/graph/GlobalGraph.ts`
+- pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/workflows/local-ci.md`
+- note: Recorded that local unit tests should run from clean sources, because stale built `dist/` files can be scanned alongside tegg TypeScript sources and trigger `duplicate proto` failures.
+
 ## [2026-05-10] package | extract shared LoaderFS package
 
 - sources touched: `packages/loader-fs/src/index.ts`, `packages/loader-fs/package.json`, `packages/core/src/index.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts`

wiki/workflows/local-ci.md

@@ -0,0 +1,36 @@
+---
+title: Local CI
+type: workflow
+summary: Local validation should run tests from clean sources and avoid stale build artifacts before tegg tests.
+source_files:
+  - AGENTS.md
+  - .github/workflows/ci.yml
+  - package.json
+  - tegg/core/loader/src/impl/ModuleLoader.ts
+  - tegg/core/metadata/src/model/graph/GlobalGraph.ts
+updated_at: 2026-06-03
+status: active
+---
+
+# Local CI
+
+The repository's GitHub CI test job installs dependencies with
+`ut install --from pnpm` and runs tests with `ut run ci` for the main test
+matrix. It does not build packages before running tests.
+
+Local validation should follow the same shape for unit tests: run tests from
+clean source files, and build separately when validating generated output,
+package exports, or packaging behavior.
+
+## Stale Build Artifacts
+
+If local tegg tests fail with `duplicate proto` after a previous build, stale
+`dist/` directories are the first thing to check.
+
+Inference: tegg module loading can scan both source and built files when
+TypeScript is supported locally. Loading `src/*.ts` and `dist/*.js` for the same
+decorated class creates duplicate metadata graph entries, which surfaces as a
+`duplicate proto` error.
+
+Use the cleanup command in `AGENTS.md` to remove stale `dist/` directories
+outside `node_modules`, test directories, and fixtures before re-running tests.