AGENTS.md 및 README.md 파일을 한국어로 번역하고 업데이트하여 프로젝트 목표, 구조 및 개발 도구에 대한 정보를 명확히 하였습니다.

AGENTS.md

@@ -1,152 +1,358 @@
-# Repository Guidelines
+# core2026 작업 지침
 
-## Project Goal (Rewrite)
+## 적용 범위와 목표
 
-- This repository is transitioning from the legacy PHP codebase to a TypeScript-based monorepo using pnpm workspaces.
-- The legacy game remains the current active source under `legacy/` while the rewrite is prepared alongside it.
-- Legacy data under `legacy/` is for migration only; once DB migration is complete,
-  the runtime will no longer depend on legacy data.
+이 파일은 `core2026/` 전체에 적용됩니다. 하위 디렉터리에 더 가까운
+`AGENTS.md`가 생기면 사용자 지시, 가까운 파일, 이 파일, 상위 작업공간
+지침 순으로 적용합니다.
 
-## Project Naming
+목표는 `../ref/sam`의 PHP 서비스를 TypeScript 런타임으로 호환 이관하는
+것입니다. 내부 구조를 더 깔끔하게 만드는 일보다 기존 결과, 상태 전이, 권한,
+화면과 운영 경계를 보존하는 일이 우선입니다.
 
-- Official name: 삼국지 모의전투 HiDCHe
-- Common nicknames: 삼모, 삼모전, 힏체섭
-- Short forms in code/docs: sammo, hidche
-- TypeScript rewrite working name: sammo-ts
+## 현재 기준과 저장소 경계
 
-## Project Structure & Module Organization
+- `core2026/`은 제품 구현 저장소입니다. gateway/game frontend·API, game engine,
+  공통 package, Prisma와 검증 도구가 실제로 존재합니다.
+- PHP 기준 구현은 이 저장소 내부 `legacy/`가 아니라 `../ref/sam`입니다.
+  `devel`은 변경하지 않는 기준선이고 비교 fixture·계측은 `ng_compare`에만
+  두어 주세요.
+- 아키텍처 매핑과 보고서는 별도 상위 저장소의
+  `../docs/ref-core2026-mapping.md`, `../report/`에 있습니다. 두 Git 경계의
+  commit과 상태를 혼동하지 말아 주세요.
+- 이미지의 운영 소유자는 외부 Caddy의 `/image/*`입니다. 제품 저장소에 무단
+  복제하거나 앱 경로로 rewrite하지 말아 주세요.
 
-- `legacy/` contains the application source. This is the active codebase.
-- PHP entry points live under `legacy/` and `legacy/hwe/` (for example `legacy/index.php`, `legacy/hwe/index.php`).
-- `legacy/src/sammo/` contains core utility classes for the `sammo\\` namespace.
-- Core PHP domain logic lives under `legacy/hwe/sammo/` (also part of the `sammo\\` namespace).
-- Frontend TypeScript/Vue sources are in `legacy/hwe/ts/` with shared components in `legacy/hwe/ts/components/`.
-- Styles are split between `legacy/css/` and SCSS in `legacy/hwe/scss/`.
-- Tests: PHPUnit in `legacy/tests/`, TypeScript tests in `legacy/hwe/test-ts/`.
-- Static data/assets: scenarios in `legacy/hwe/scenario/`, templates in `legacy/hwe/templates/`.
-- Image storage listing (ls -R dump): `docs/image-storage.md`.
+작업 시작과 종료에 최소한 다음을 확인해 주세요.
 
-## Legacy Endpoint Patterns
+```sh
+git status --short --branch
+git remote -v
+git rev-parse HEAD
+```
 
-- JSON API handlers: `legacy/hwe/j_*.php`.
-- Vue multi-entry pages: `legacy/hwe/v_*.php`.
-- Legacy PHP + jQuery pages: `legacy/hwe/b_*.php` with POST handlers in `legacy/hwe/c_*.php`.
-- Modern API router: `legacy/hwe/api.php` accepts a path argument and dispatches to `legacy/hwe/API/` modules.
+상위 매핑/보고서를 바꾸면 상위 저장소에서도 같은 검사를 별도로 수행해 주세요.
+dirty 파일은 사용자의 변경일 수 있으므로 관련 없는 수정, 정리, stage,
+commit 또는 삭제를 하지 말아 주세요.
 
-## Planned Monorepo Layout (TypeScript Rewrite)
+## 완료 상태를 해석하는 법
 
-- `/packages/common`: shared utilities and type definitions.
-  - Frequently used utility functions should be registered here and utilized.
-- `/packages/infra`: Prisma/Redis connectors and other runtime infra.
-- `/packages/logic`: pure game logic with DI/interfaces for external dependencies.
-- `/app/gateway-frontend`: Gateway UI application.
-- `/app/gateway-api`: Gateway backend service.
-- `/app/game-frontend`: Game UI application.
-- `/app/game-api`: Game backend service per server+scenario profile.
-- `/app/game-engine`: Game engine / turn daemon per server+scenario profile.
-- `/tools/build-scripts`: build and deployment scripts.
+2026-07-27의 백엔드 누락 감사에서는 현재 `main`에서 재현 가능한 구체적
+미구현·미병합 항목을 찾지 못했습니다. 이를 “이관 전체 완료”로 해석하지 말아 주세요.
 
-## Planned Runtime & Tooling
+- 새 차등 fixture가 mismatch를 드러내면 다시 제품 결함으로 분류해 주세요.
+- green unit test는 ref 호환, 실제 DB transaction, Chromium geometry 또는
+  운영 장애 복구를 자동으로 증명하지 않습니다.
+- 환경 변수가 없는 기본 test에서 skip된 integration은 실행된 검증이 아닙니다.
+- local/mock prefix E2E와 실제 외부 Caddy·host/firewall 검증은 별도입니다.
+- report 제목의 `완료`보다 현재 코드, Git ancestry, 실행 경로와 재현 결과를
+  우선합니다.
 
-- TypeScript: `6.0.2` (workspace-wide fixed version)
-  - TypeScript 7 is temporarily excluded because compiler/tooling APIs required
-    by this repository and its toolchain are not yet available or compatible.
-  - Keep `app/*`, `packages/*`, and `tools/*` on the same exact TypeScript
-    version. Do not add a package-local TypeScript 5 or 7 override.
-  - Upgrade to TypeScript 7 only after the required APIs and dependent tooling
-    are available and the repository-wide typecheck, lint, build, tests, and
-    comparison tools pass. See `docs/architecture/typescript-version.md`.
-- Backend: Node.js + Fastify, with Prisma ORM.
-- Turn daemon: turn scheduler/resolver service for game ticks.
-- Turn daemon and API server communicate via Redis Stream or Redis pub/sub.
-- API server and frontend may use SSE for live updates.
-- API: tRPC + zod.
-- Frontend: Vue 3, Pinia, Vue Router, TailwindCSS, Vite.
-- Data: PostgreSQL; sessions backed by Redis.
-- Testing: Vitest.
-- Package manager: pnpm (workspace-based monorepo).
-- Build output: server builds emitted to `/dist/{profileName}` per profile.
+기능 작업 전에 관련 매핑 항목과 최신 report를 읽고, 오래된 결론은 현재
+코드와 commit으로 다시 확인해 주세요.
 
-## Suggested Monorepo Scripts (Proposal)
+## 실제 구조와 책임
 
-These are placeholders to align teams; adjust once packages exist.
+- `app/gateway-frontend`: 가입·로그인, 로비, 계정, 관리자 운영 UI
+- `app/gateway-api`: 계정·세션·profile 정책, operation queue와 PM2
+  orchestration
+- `app/game-frontend`: profile별 게임 SPA와 ref 호환 UI
+- `app/game-api`: tRPC/SSE, 조회·입력 API와 battle/auction/tournament worker
+- `app/game-engine`: turn daemon, scheduler, 월간 lifecycle와 DB flush
+- `packages/common`: 타입, 직렬화, RNG와 공통 유틸리티
+- `packages/logic`: 전투·명령·월간 action 등 도메인 로직
+- `packages/infra`: gateway/game Prisma schema, migration과 client
+- `tools/integration-tests`: PostgreSQL/Redis 및 ref↔core 차등
+- `tools/frontend-legacy-parity`: 실제 Chromium 비교
+- `tools/legacy-db-migration`: 장기보존 데이터 CLI 이관
 
-- `pnpm install`: install all workspace dependencies.
-- `pnpm typecheck`: run TypeScript type checks in all packages (via turbo).
-- `pnpm lint`: lint all packages (via turbo).
-- `pnpm test`: run all unit tests (via turbo).
-- `pnpm build`: build all packages/apps (via turbo).
-- `pnpm dev`: run dev servers where applicable (via turbo).
-- `pnpm --filter ./app/game-frontend dev`: run a single app by filter.
-- `pnpm --filter ./app/game-api dev`: run a single service by filter.
-- `pnpm --filter ./app/game-engine dev`: run a single service by filter.
+`tools/build-scripts/build-server.mjs`는 현재 profile resource 복사
+placeholder입니다. 이를 완성된 배포 bundle이나 검증된 profile build로 설명하지
+않습니다. 운영 build/reset/open은 gateway operation, commit별 worktree와
+orchestrator 실행 경로를 조사해 주세요.
 
-## Development Checklist (AI)
+## 레거시 매핑과 비교
 
-- After code changes, the AI MUST run `CI=1 pnpm typecheck`.
-- When changes require unit tests, run the relevant tests.
-  - For game engine changes, run (example):
-    `pnpm --filter @sammo-ts/game-engine test npcNationUprisingUnification`.
-  - Do NOT insert `--` after `test` when passing a Vitest file/name filter; it breaks the filter here.
-    Use `pnpm --filter @sammo-ts/game-engine test npcNationTechResearch.test.ts` (no `--`).
-- When migrating existing functionality, keep text and log output identical to the legacy behavior unless there is a technical blocker.
+기능을 변경하기 전에 다음을 end-to-end로 연결해 주세요.
 
-## Build Profiles (Proposal)
+1. ref entry point와 호출 순서
+2. PHP domain class, SQL read/write, template/CSS/JS와 사용자 출력
+3. core service/router/action/loader/flush와 frontend 호출부
+4. session/auth, validation, transaction, 비동기 경계와 오류 복구
+5. RNG 생성·소비와 persistence 순서
 
-- A build profile is a server+scenario pair; scenario selection is required even if a default exists.
-- Server builds should accept a profile (server variant) plus an explicit scenario file input.
-- Recommended pattern: `pnpm build:server --profile che --scenario default`.
-- Prefer environment variables for CI/CD (`PROFILE=che SCENARIO=default pnpm build:server`) and a small wrapper script for local usage.
-- Build output stays in `/dist/{profileName}` per profile to keep deployments predictable.
-- Profile selection can target different git branches or specific commits; server operators decide the compatibility baseline.
-- The scenario file determines unit sets and DB settings that must be prepared before build output is emitted.
+`../docs/ref-core2026-mapping.md`에는 1:1 대응을 억지로 만들지 말고 1:N/N:1
+소유권과 변환 지점을 기록해 주세요. `확인`, `부분 확인`, `가설`, `미구현`,
+`의도적 차이`를 근거와 함께 사용해 주세요. 문서와 코드가 다르면 먼저 양쪽 기준
+commit과 실제 실행을 확인하고 사실관계를 고쳐 주세요.
 
-## Server Profiles (Planned)
+ref 계측이 필요하면 다음을 지켜 주세요.
 
-- Server IDs: `che`, `kwe`, `pwe`, `twe`, `nya`, `pya`
-- Each build/run profile combines a server ID with a scenario selection.
+- `devel`에 test, endpoint, fixture나 debug 코드를 commit하지 말아 주세요.
+- 기존 `ng_compare` 이력과 분기 기준을 조사하고 reset/overwrite하지 말아 주세요.
+- 계측은 최소·deterministic·가능하면 read-only로 두고 test 환경 guard를
+  사용해 주세요.
+- 계측 유무가 결과, RNG 소비, DB mutation과 출력 순서를 바꾸지 않는지
+  확인해 주세요.
+- ref와 core 변경은 서로 다른 저장소와 commit으로 관리해 주세요.
 
-## Game Domain Notes (Behavioral Context)
+## 호환성 우선순위
 
-- Turn-based multiplayer loop with configurable tick length (historically 120/60/30/20/10/5/2/1 min; experimental day/night schedules).
-- Core stats: leadership, strength, intelligence with effects on internal affairs and combat.
-- Traits and modifiers apply via the Trigger system, evaluated by priority; "attempt" then "execute".
-- Scenarios define maps, NPCs, initial resources; scenario loading separated to allow future modding.
-- "Unit packs" bundle unit graphics, audio, and special effects per scenario.
+1. 전투 결과, 계산식, 판정·반올림·정렬과 RNG 소비 순서
+2. 턴/명령 조건, 자원 변화, DB 상태 전이와 권한
+3. API 요청·응답·오류, session과 인증
+4. 문구, 로그, 화면 흐름과 룩앤필
+5. 내부 구현 세부사항
 
-## Randomness Policy (Verifiable RNG)
+레거시의 이상해 보이는 동작도 계약일 수 있습니다. 보안 또는 데이터 손상 위험이
+아니면 우선 같은 동작을 재현하고 개선 제안은 분리해 주세요. 허용하는 차이는
+사용자 경험, 저장 상태와 후속 턴 결과에 영향이 없다는 근거를 mapping/report에
+남겨 주세요.
 
-- All game-impacting randomness must be verifiable and reproducible from a deterministic seed.
-- Prefer using the existing TypeScript implementations: `packages/common/src/util/LiteHashDRBG.ts`, `packages/common/src/rng.ts`(interface) and `packages/common/src/util/RandUtil.ts`.
-- Seed composition should include a hidden base seed plus action context (action type, time, actor, target) so results can be re-validated later.
-- Do not introduce ad-hoc randomness in game logic; allow non-deterministic randomness only for non-gameplay, cosmetic, or UI-only cases.
+## 인증과 권한
 
-## Coding Style & Naming Conventions
+- actor, general과 archive owner는 인증 session/token에서 서버가 결정합니다.
+  client가 보낸 user ID, general ID, owner, role을 권한 근거로 신뢰하지 말아 주세요.
+- game token의 profile, role, sanction과 장수 생성 정책을 world mutation보다
+  먼저 확인해 주세요.
+- 새 browser flow는 `x-session-token` 또는 현재 session transport를 사용하고
+  token을 query string이나 로그에 노출하지 말아 주세요.
+- 실패한 logout에서 client token을 먼저 버려 서버 revoke 실패를 숨기지 말아 주세요.
+- 비밀번호 원문·OAuth credential·global salt·private key·session token을
+  Git, CLI argument, build log, report 또는 screenshot에 넣지 말아 주세요.
+- `VITE_*`는 공개값입니다. 비밀값은 Git 제외 파일이나 `/run/secrets/...`를
+  사용해 주세요.
 
-- Follow repo lint/format configuration once it exists; keep diffs consistent within a file.
-- Indentation: 4 spaces for TypeScript, JSON, and Vue SFCs.
-- Prefer explicit types for public APIs; avoid `any` and narrow `unknown`.
-- Vue components: PascalCase filenames; composables use `useX` naming.
-- Use `camelCase` for variables/functions and `PascalCase` for classes/types.
-- Legacy concepts may use Korean identifiers; preserve Korean naming when it improves maintainability.
-- Hybrid naming is acceptable (e.g., `use전투규칙`, `use도시상태`) when the prefix is conventional but the domain term is Korean.
-- For classes, commands, and domain logic, add clear Korean comments to support Korean readers and future maintainers.
-- Use strong type conventions in TypeScript. Any is not allowed, and you should also be careful about using unknown.
-- Avoid dangerous casting, such as `as unknown as Something`.
+API를 변경하면 성공뿐 아니라 무인증, 다른 사용자, sanction/role, 잘못된
+입력과 경계값을 검사해 주세요. 권한 테스트는 router mock만으로 끝내지 않고 위험도에
+따라 실제 HTTP transport까지 확인해 주세요.
 
-## Commit & Pull Request Guidelines
+## 턴, transaction과 RNG
 
-- Git history is minimal and does not define a strict convention; use short, imperative messages (e.g., "Fix map cache loading").
-- PRs should include a concise description, testing notes/commands, and screenshots for UI changes.
+현재 gameplay mutation의 내구성 기준은 PostgreSQL `input_event`입니다.
 
-## Architecture References
+```text
+API request
+  -> input_event accept/idempotency
+  -> daemon claim + lease/fencing 확인
+  -> in-memory action/turn/monthly handlers
+  -> world/log/queue/result flush
+  -> input_event 완료를 같은 transaction으로 commit
+  -> realtime 알림
+```
 
-- Overview: `docs/architecture/overview.md`.
-- Legacy engine map: `docs/architecture/legacy-engine.md`.
-- TypeScript rewrite plan: `docs/architecture/rewrite-plan.md`.
-- Runtime and build profiles: `docs/architecture/runtime.md`.
+- Redis pub/sub은 best-effort fan-out이며 mutation commit의 source of truth가
+  아닙니다.
+- daemon lease/fencing을 우회하거나 이전 owner의 stale transaction을
+  commit 가능하게 만들지 말아 주세요.
+- 예약 queue의 revision/CAS, repeat/bulk 직렬화와 API/daemon race를 보존해 주세요.
+- 새 persistence field는 Prisma schema, 새 migration, domain/model type,
+  loader, in-memory dirty state, transaction flush와 reload test까지 연결해 주세요.
+- 기존 migration 파일이나 checksum을 수정하지 말아 주세요.
+- 전투·명령·월간 action의 호출, state patch, 로그와 RNG 소비 순서를
+  리팩터링 편의로 바꾸지 말아 주세요.
 
-## Documentation Workflow
+게임 난수는 기존 `packages/common/src/util/LiteHashDRBG.ts`, `RNG.ts`,
+`RandUtil.ts` 흐름을 사용해 주세요. `Math.random()` 같은 임의 경로를 gameplay에
+추가하지 말아 주세요. 후보가 하나뿐인 선택, 실패 분기, fallback에서도 ref가
+소비하는 RNG call을 생략하지 말아 주세요.
 
-- When AI proposes future improvements or expansions, record them in
-  `docs/architecture/todo.md` with an "AI suggestion" label.
+전투/RNG 변경에는 fixed seed 결과뿐 아니라 RNG trace, 로그, 전체 state
+side effect와 실패 경로의 ref 비교가 필요합니다. comparator ignore를 늘리기
+전에 canonical snapshot에서 누락된 field가 없는지 확인해 주세요.
+
+## 프론트엔드와 룩앤필
+
+새 디자인 시스템이나 현대적 재해석을 임의로 도입하지 말아 주세요. 보존 범위는
+layout, font, line-height, 줄바꿈, 색상, texture, border, shadow, opacity,
+이미지 natural size/aspect ratio/object-fit과 표시 순서입니다.
+
+- gateway `/gateway/`, game `/che/`와 `/hwe/` prefix에서 direct navigation,
+  refresh, tRPC, SSE와 asset URL을 확인해 주세요.
+- `kwe`, `twe`, `nya`, `pya`, `pwe`가 코드에 있어도 외부 route가 활성화된
+  것으로 가정하지 말아 주세요.
+- `/image/*`를 frontend build artifact로 가져오거나 root 배포 URL로
+  하드코딩하지 말아 주세요.
+- 공통화는 동일한 렌더링 계약이 확인된 token/shell에 한합니다. `.error`,
+  `.stack`처럼 이름만 같은 page selector를 전역화하지 말아 주세요.
+- `v-html`은 입력 source와 sanitization/allowlist를 확인해 주세요. 기존 warning을
+  일괄 disable하지 말아 주세요.
+
+UI를 변경하면 실제 Chromium을 사용해 주세요.
+
+- ref와 core에 같은 Chromium, viewport, device scale, zoom, locale, font,
+  image와 로그인/test data를 사용해 주세요.
+- 전체·영역 screenshot과 `getBoundingClientRect()`,
+  `getComputedStyle()`을 수집해 주세요.
+- `hover()`, focus, pointer down/up, checked/selected/disabled, dropdown,
+  modal과 transition 상태를 실제 interaction으로 만들어 주세요.
+- pixel diff mask는 시간·난수 등 불가피한 영역만 최소화하고 이유를 기록해 주세요.
+- auth redirect만 확인하고 visual parity라고 주장하지 말아 주세요.
+- 민감정보가 보이는 artifact는 저장하거나 report에 넣지 말아 주세요.
+
+CSS layer와 selector 경계는 `docs/frontend-css-architecture.md`, 비교 실행은
+`docs/frontend-legacy-parity.md`를 따라 주세요.
+
+## DB와 레거시 데이터 이관
+
+Gateway는 기본 `public`, game은 profile별 PostgreSQL schema를 사용합니다.
+schema 변경 후 최소한 다음을 위험도에 맞게 확인해 주세요.
+
+- 빈 DB migration 전체 적용
+- 두 번째 deploy가 no-op인지
+- 기존 설치에서 증분 적용되는지
+- unique/FK/index와 runtime query 일치
+- rollback 또는 backup/restore 경로
+
+`prisma db push`는 격리된 fixture에서 scoped schema 확인용으로만 사용하고
+정식 migration chain을 대신하지 말아 주세요.
+
+레거시 DB 이관은 `tools/legacy-db-migration` CLI만 사용해 주세요.
+
+- dry-run이 기본이며 실제 쓰기는 명시적 `--apply`가 필요합니다.
+- DB URL과 secret은 환경/secret file로 전달해 주세요.
+- PostgreSQL advisory lock, stable legacy key와 idempotent upsert를 보존해 주세요.
+- 현 시즌 `general/city/nation`, queue, message, market, log와 seasonal
+  storage를 장기보존 이관에 섞지 말아 주세요.
+- 운영 apply 전 backup, maintenance mode, source/target count와 rollback
+  절차를 다시 확인해 주세요.
+- dump에 우연히 있는 table이 아니라 ref schema와 사용자 범위를 기준으로
+  삼아 주세요.
+
+## 환경과 배포
+
+`.env` 또는 secret key를 추가하기 전에 `.gitignore`와 `.env.example`을
+함께 갱신해 주세요. example은 모든 필수 key와 명백한 placeholder를 포함하되 실제
+비밀을 담지 말아 주세요.
+
+전체 작업공간의 개발 PostgreSQL/Redis는
+`../docker_compose_files/development/`에서 worktree별로 격리할 수 있습니다.
+통합 fixture는 schema truncate와 Redis 초기화를 수행할 수 있으므로 병렬
+worktree가 같은 instance를 공유하지 않도록 해 주세요. volume 삭제 명령은 사용자가
+명시적으로 데이터 폐기를 요청하지 않으면 실행하지 말아 주세요.
+
+현재 외부 호스트 계약은 `0.0.0.0` bind와 `/gateway/`, `/che/`, `/hwe/`
+prefix입니다. Caddy는 외부 인프라로 취급하고 요청 없이 설정 변경을 전제하지
+않습니다. local preview/mock 성공을 외부 HTTPS 성공으로 보고하지 말아 주세요.
+
+Gateway preview를 검증할 때 최소 계약은 다음과 같습니다.
+
+```sh
+VITE_APP_BASE_PATH=/gateway \
+VITE_GATEWAY_API_URL=/gateway/api/trpc \
+VITE_GAME_API_URL_TEMPLATE='/{profile}/api/trpc' \
+VITE_GAME_WEB_URL_TEMPLATE='/{profile}/' \
+pnpm --filter @sammo-ts/gateway-frontend build
+```
+
+profile별 정확한 포트와 game frontend/API 변수는
+`docs/e2e-caddy-routing.md`에서 확인하고 현재 인프라와 대조해 주세요.
+
+## 개발과 검증 절차
+
+1. 현재 branch/status/remote, 사용자 변경과 가까운 지침을 확인해 주세요.
+2. 관련 mapping/report와 ref/core 호출 경로를 조사해 주세요.
+3. 보존할 계약, 허용할 차이와 검증 범위를 먼저 정합니다.
+4. 코드와 함께 type/schema/migration/fixture/mapping을 갱신해 주세요.
+5. 좁은 단위 test → typecheck/lint/build → DB integration → ref 차등 →
+   Chromium E2E 순으로 위험에 맞게 넓혀 주세요.
+6. 명령, 결과, skip/미검증과 baseline failure를 분리해 report에 기록해 주세요.
+7. 양쪽 Git diff/status와 필요한 ancestry를 다시 확인해 주세요.
+
+기본 정적 검사는 실제 루트 script를 사용해 주세요.
+
+```sh
+CI=1 pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+- 모든 코드 변경 후 `CI=1 pnpm typecheck`를 실행해 주세요.
+- `pnpm test`의 skip 수를 pass처럼 보고하지 말아 주세요.
+- Vitest file/name filter는 package script 뒤에 불필요한 `--`를 넣지 말아 주세요.
+  예: `pnpm --filter @sammo-ts/game-engine test monthlyCoreEventHandler.test.ts`
+- frontend package의 `test` placeholder를 실제 UI 검증으로 오해하지 말아 주세요.
+  해당 Playwright script 또는 legacy parity suite를 사용해 주세요.
+- 전체 lint/test의 기존 실패가 있으면 targeted 결과와 baseline 재현 결과를
+  구분하고, 관련 없는 기대값을 완화해 숨기지 말아 주세요.
+
+외부 서비스 없는 기본 integration:
+
+```sh
+pnpm test:integration
+```
+
+전용 PostgreSQL/Redis를 준비한 조건부 전체 경계:
+
+```sh
+pnpm test:integration:conditional
+```
+
+ref 명령과 UI entry point:
+
+```sh
+pnpm check:legacy:general
+pnpm check:legacy:nation
+pnpm test:e2e:frontend-legacy
+```
+
+각 command가 요구하는 ref checkout, Docker, DB URL, secret과 fixture는 관련
+docs에서 확인해 주세요. 존재하지 않는 명령을 오래된 report나 제안 문서만 보고
+실행하지 말아 주세요.
+
+## 코드 스타일
+
+- TypeScript는 workspace 전체에서 정확히 `6.0.2`를 사용해 주세요. package-local
+  다른 버전을 추가하지 말아 주세요.
+- TypeScript/JSON/Vue SFC는 기존 4-space 스타일을 유지해 주세요.
+- public API는 명시적 타입을 사용하고 `any`, 불필요하게 넓은 `unknown`,
+  `as unknown as` 우회를 피해 주세요.
+- Vue component는 PascalCase, composable은 `useX`, 변수/함수는 camelCase,
+  type/class는 PascalCase를 사용해 주세요.
+- 한국어 domain identifier와 설명은 의미가 더 명확할 때 유지해 주세요.
+- action/command/전투 코드에는 한국 독자가 side effect와 ref 근거를 이해할
+  수 있는 주석을 남기되 코드의 반복 설명은 피해 주세요.
+- 기능 이관과 무관한 대규모 formatting/refactor를 같은 변경에 섞지 말아 주세요.
+
+## 문서와 보고서
+
+기능·운영·호환성에 의미 있는 변경은 코드와 같은 작업에서 다음을 갱신해 주세요.
+
+- `README.md`: 사용자가 알아야 할 현재 구조, 시작점과 운영 경계
+- 이 `AGENTS.md`: 반복 작업 규칙과 검증 계약
+- `docs/*`: core2026 내부 구현·운영 상세
+- `../docs/ref-core2026-mapping.md`: ref↔core 근거와 상태
+- `../report/YYYY-MM-DD-간결한-작업명.md`: 재현 가능한 인수인계
+
+보고서에는 목적/범위, 조사한 ref, 변경 파일, 보존 계약, 명령과 결과,
+skip/미검증, 알려진 차이, 후속 작업과 저장소별 commit을 포함합니다. commit
+전이면 `커밋 전`으로 기록하고 서로 다른 저장소의 hash를 명확히 구분해 주세요.
+
+## Git, worktree와 commit
+
+- 중·장기 작업은 전용 branch/worktree와 고유 DB/Redis instance에서 합니다.
+- 최신 `main`을 통합하고 회귀를 확인한 뒤 요청된 범위에 따라 local `main`에
+  병합해 주세요. 원격 push는 별도 요청 없이는 하지 말아 주세요.
+- 관련 없는 사용자 변경을 stage/commit/revert하지 말아 주세요.
+- ref 비교 변경과 core 제품 변경, 상위 mapping/report 변경은 각 Git
+  저장소에서 별도 commit해 주세요.
+- 생성물, `.env`, DB volume, log, coverage, screenshot, test-results와
+  secret을 commit하지 말아 주세요.
+- worktree 정리는 clean status와
+  `git merge-base --is-ancestor HEAD <baseline>`을 모두 확인한 뒤 non-force
+  제거해 주세요. 이름, 나이 또는 uncommitted 여부만으로 삭제하지 말아 주세요.
+- 사용자가 commit을 요청하지 않은 일반 작업은 diff와 권장 commit 경계를
+  준비하되 임의로 commit하지 말아 주세요.
+
+## Qwen 보조 분석
+
+Qwen은 대규모 파일 목록, diff·로그 분류, 반복 추출과 누락 후보 재검색에만
+사용해 주세요. 필요한 최소 발췌만 전달하고 secret, 개인정보와 환경 파일 값을
+보내지 말아 주세요.
+
+- 아키텍처·보안·DB mutation·전투/RNG 판단과 최종 검증을 위임하지 말아 주세요.
+- 결과는 파일, Git, test 또는 실제 trace로 독립 검증해 주세요.
+- 응답 budget은 128–4096 token 범위로 제한해 주세요.
+- 실패하면 health 확인 후 일시 오류일 때 한 번만 재시도하고, 선택적 작업이면
+  로컬 분석을 계속해 주세요.