chore(harness): entry SSOT + ownership-matrix + folder unify (#561 PR-A)

.cursor/rules/api-routes.mdc

@@ -3,6 +3,8 @@ description: Next.js API route conventions
 globs: "packages/web/app/api/**/*.ts"
 ---
 
+> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지.
+
 # API Route Conventions
 
 ## Handler Format

.cursor/rules/monorepo.mdc

@@ -3,6 +3,8 @@ description: decoded-monorepo conventions and architecture
 globs: "**/*"
 ---
 
+> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지.
+
 # decoded-monorepo
 
 ## Structure

.cursor/rules/react-components.mdc

@@ -3,6 +3,8 @@ description: React component conventions for decoded web package
 globs: "packages/web/**/*.tsx"
 ---
 
+> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지.
+
 # React Component Conventions
 
 ## Server vs Client Components

.cursor/rules/rust-api.mdc

@@ -3,6 +3,8 @@ description: Rust API server conventions (Axum + SeaORM)
 globs: "packages/api-server/**/*.rs"
 ---
 
+> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지.
+
 # Rust API Server Conventions
 
 ## Stack

AGENT.md

@@ -1,37 +1,5 @@
-# decoded-app AI 에이전트 맵
+# AGENT.md — 한국어 진입점 (redirect)
 
-> **Purpose**: AI 에이전트가 이 모노레포에서 작업할 때의 **한국어 진입점**입니다. 장문·표는 [`docs/agent/`](docs/agent/)와 [`.planning/codebase/`](.planning/codebase/)에 두었습니다.
+본 파일은 `AGENTS.md`로 합쳐졌다. 한국어 작업 메모를 포함한 cross-tool 진입 규칙은 **[`AGENTS.md`](AGENTS.md)** 를 읽는다.
 
-## 필수 진입 문서
-
-| 문서 | 역할 |
-|------|------|
-| **[CLAUDE.md](CLAUDE.md)** | 영문 **맵** (항상 읽기 쉬운 요약, 규칙, `docs/agent` 인덱스) |
-| **[docs/agent/README.md](docs/agent/README.md)** | 표·인벤토리 목차 (라우트, API, 훅, 디자인 시스템) |
-| **[.planning/codebase/](.planning/codebase/)** | 아키텍처, 스택, 컨벤션, 테스트, 연동 |
-
-## 작업 유형별로 열 파일
-
-| 작업 | 문서 |
-|------|------|
-| 명령어·패키지 구조·로컬 deps | [docs/agent/monorepo.md](docs/agent/monorepo.md) |
-| 웹 라우트·기능 영역 | [docs/agent/web-routes-and-features.md](docs/agent/web-routes-and-features.md) |
-| Next.js `app/api/v1` | [docs/agent/api-v1-routes.md](docs/agent/api-v1-routes.md) |
-| 훅·스토어·주요 경로 | [docs/agent/web-hooks-and-stores.md](docs/agent/web-hooks-and-stores.md) |
-| 디자인 시스템 import·컴포넌트 목록 | [docs/agent/design-system-llm.md](docs/agent/design-system-llm.md) |
-| Warehouse 스키마 (ETL·Seed) | [docs/agent/warehouse-schema.md](docs/agent/warehouse-schema.md) |
-| Rust API 서버 (`api-server`) | [packages/api-server/AGENT.md](packages/api-server/AGENT.md) |
-
-## 반드시 지킬 것
-
-1. **패키지 매니저**: **bun** (`bun run`, `bun add`). yarn/npm 아님.
-2. **상세 표의 SSOT**: `docs/agent/` — CLAUDE.md에는 링크만 있음.
-3. **디자인 시스템**: 새 UI는 [docs/design-system/](docs/design-system/) 및 `docs/agent/design-system-llm.md` 확인.
-4. **Supabase 쿼리**: 웹은 `packages/web/lib/supabase/queries/` 패턴 유지.
-
-## 기타
-
-- 디자인 시스템 토큰·UI 가이드: [docs/design-system/README.md](docs/design-system/README.md)
-- 문서 인덱스: [docs/README.md](docs/README.md)
-
-**마지막 업데이트**: 2026-04-02
+(파일 자체는 외부 link 호환을 위해 유지.)

AGENTS.md

@@ -1,6 +1,85 @@
-# Agents
+# AGENTS.md — Cross-tool agent entry point
 
-This repository uses **[CLAUDE.md](CLAUDE.md)** as the short entry map (rules and links).
+이 파일은 monorepo의 **canonical agent 진입점**이다. 모든 LLM 도구(Codex / Cursor / Warp / Claude Code / Gemini CLI)는 작업 시작 시 이 파일을 **가장 먼저** 읽는다.
 
-- **Inventories** (routes, `/api/v1/*`, hooks, design system): [`docs/agent/README.md`](docs/agent/README.md)
-- **Korean agent map**: [`AGENT.md`](AGENT.md)
+각 도구별 overlay는 본 파일을 보강만 한다 — 본 파일과 충돌하면 본 파일이 우선한다.
+
+## 도구별 overlay 매핑
+
+| 도구              | Overlay 파일           | 역할                                                            |
+| ----------------- | ---------------------- | --------------------------------------------------------------- |
+| Claude Code       | `CLAUDE.md`            | Claude Code 전용 routing 규칙(skill, OMC, GSD, Superpowers)     |
+| Warp Terminal     | `WARP.md`              | Warp 워크플로우 명령·자동화                                     |
+| Cursor            | `.cursor/rules/*.mdc`  | Cursor 네이티브 규칙(globs · description)                       |
+| Codex CLI         | `~/.codex/config.toml` | Hybrid harness Layer 2/2.5 (codex exec --profile fast / strict) |
+| 한국어 진입(공통) | `AGENT.md`             | `AGENTS.md` 1줄 redirect                                        |
+
+## 읽기 우선순위
+
+1. **AGENTS.md** (이 파일) — cross-tool 공통
+2. **`docs/wiki/schema/ownership-matrix.md`** — 정보 카테고리별 정본/pointer 매핑 SSOT
+3. **`docs/agent/README.md`** — agent 참조 인벤토리 목차 (라우트, API, 훅, 디자인 시스템)
+4. **`.planning/codebase/*`** — 스택·아키텍처·컨벤션·테스트
+5. 도구별 overlay (`CLAUDE.md`, `WARP.md`, `.cursor/rules`, ...)
+
+## Routing SSOT
+
+정보 카테고리별로 어디를 정본으로 보아야 하는지는 **`docs/wiki/schema/ownership-matrix.md`** 하나가 결정한다. 다른 파일은 그 행을 가리키기만 한다 — 표를 복제하지 않는다.
+
+대표 항목:
+
+- Stack/버전 → `.planning/codebase/STACK.md`
+- 코딩 컨벤션 → `docs/wiki/schema/conventions.md`
+- Skills inventory → **`docs/agent/skills.md`**
+- ADR → vault `Architecture/adr/` (monorepo 측 stub: `docs/adr/index.md`)
+- Harness wiki → `docs/wiki/wiki/harness/*`
+- Cross-tool agent entry → 이 파일
+
+전체 매트릭스: [`docs/wiki/schema/ownership-matrix.md`](docs/wiki/schema/ownership-matrix.md)
+
+## Documentation 위치 (decoded vs decoded-docs)
+
+| 종류                                      | 위치                                                                              |
+| ----------------------------------------- | --------------------------------------------------------------------------------- |
+| 코드 · LLM 라우팅 · agent 인벤토리 · spec | **이 레포** (`docs/agent/`, `docs/superpowers/`, `AGENTS.md`, 등)                 |
+| 회의 · 결정 · 기획 · 아키텍처 · 회고      | **[decoded-docs vault](https://github.com/decodedcorp/decoded-docs)** (별도 레포) |
+
+전체 sync policy: [decoded-docs/Guides/sync-policy.md](https://github.com/decodedcorp/decoded-docs/blob/main/Guides/sync-policy.md)
+
+회사 지식 질의(예: "지난주 결정 뭐였어?")는 Telegram 매니저 agent에게 — vault 기반 답변.
+
+## 작업 유형별 진입 파일
+
+| 작업                           | 문서                                    |
+| ------------------------------ | --------------------------------------- |
+| 명령어·패키지 구조·로컬 deps   | `docs/agent/monorepo.md`                |
+| 웹 라우트·기능 영역            | `docs/agent/web-routes-and-features.md` |
+| Next.js `app/api/v1`           | `docs/agent/api-v1-routes.md`           |
+| 훅·스토어                      | `docs/agent/web-hooks-and-stores.md`    |
+| 디자인 시스템 import·컴포넌트  | `docs/agent/design-system-llm.md`       |
+| Skills · slash commands        | `docs/agent/skills.md`                  |
+| Setup (issue tracker · triage) | `docs/agent/setup/`                     |
+| Rust API crate                 | `packages/api-server/AGENT.md`          |
+| 아키텍처·컨벤션·스택 심층      | `.planning/codebase/`                   |
+| Harness 세션 규율              | `docs/wiki/wiki/harness/*`              |
+
+## 반드시 지킬 것
+
+1. **패키지 매니저**: **bun** (`bun run`, `bun add`). yarn/npm 아님.
+2. **상세 표의 SSOT**: `docs/agent/` + `ownership-matrix.md` — overlay 파일에는 링크만.
+3. **Git workflow**: `feature/*` → `dev` → `main`. `main` 직접 push 금지. 상세는 `docs/GIT-WORKFLOW.md`.
+4. **Conventional Commits** 준수.
+5. **Skill 라우팅**: 사용자 요청이 skill과 매치되면 Skill tool을 FIRST action으로. 직접 답하지 않는다. 상세는 `docs/agent/skills.md`.
+6. **Generated 코드 금지**: `packages/web/lib/api/generated/`는 Orval 자동 생성, 수동 편집 금지.
+7. **Vault 결정**: 회의·결정·아키텍처·회고는 monorepo에 두지 않는다 — 항상 vault.
+
+## Harness Workflow
+
+| Tool        | Role                 | When                |
+| ----------- | -------------------- | ------------------- |
+| gstack      | 기획/리뷰/QA/배포    | Think → Plan → Ship |
+| Superpowers | TDD, 코드 품질 강제  | Build (구현)        |
+| OMC         | Claude + Gemini 듀얼 | 대규모 작업 보조    |
+| GSD quick   | 원자적 단발 패치     | 유지보수            |
+
+<!-- Last Updated: 2026-05-21 -->