docs(agents): sync local CI guidance

.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
 

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

@@ -11,6 +11,7 @@ Read this file before exploring raw sources.
 ## Workflows
 
 - [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.
 
 ## Decisions
 

wiki/log.md

@@ -2,6 +2,12 @@
 
 Dates use the workspace-local Asia/Shanghai calendar date.
 
+## [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.