agentic-dev 0.1.0 → 0.2.0

package/sdd/01_planning/04_data/templates_data_modeling.md

@@ -0,0 +1,119 @@
+# templates data modeling
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+현재 구현된 backend domain model과 저장 관점을 entity 수준으로 요약한다.
+
+## 1. Auth Account
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | 인증 계정 식별자 |
+| `name` | `str` | 표시 이름 |
+| `email` | `EmailStr` | 로그인 이메일 |
+| `role` | `str` | `admin`, `operator` 등 인증 역할 |
+| `status` | `str` | 인증 가능 상태 |
+| `password_hash` | `str` | credential hash |
+
+## 2. User Profile
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | 사용자 식별자 |
+| `name` | `str` | 사용자 이름 |
+| `email` | `EmailStr` | 연락/표시 이메일 |
+| `role` | `str` | 운영 역할 |
+| `status` | `str` | 활성 상태 |
+| `timezone` | `str` | 지역/표시용 timezone |
+| `last_login_at` | `str` | 최근 로그인 시각 |
+
+## 3. Catalog Product
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | 상품 식별자 |
+| `slug` | `str` | URL/업무용 유니크 slug |
+| `name` | `str` | 상품명 |
+| `brand` | `str` | 브랜드명 |
+| `category` | `str` | 카테고리 |
+| `status` | `draft|active|archived` | 카탈로그 노출 상태 |
+| `short_description` | `str` | 카드용 요약 문구 |
+| `description` | `str` | 상세 설명 |
+| `hero_image` | `MediaAsset` | 대표 이미지 |
+| `gallery` | `list[MediaAsset]` | 추가 이미지 |
+| `price` | `Money` | 판매가 |
+| `compare_at_price` | `Money?` | 비교가 |
+| `tags` | `list[str]` | 태그 |
+| `attributes` | `list[ProductAttribute]` | 속성 리스트 |
+| `variants` | `list[ProductVariant]` | SKU variant 리스트 |
+| `created_at` | `str` | 생성 시각 |
+| `updated_at` | `str` | 수정 시각 |
+
+## 4. Inventory Level
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `sku` | `str` | 재고 식별 단위 |
+| `product_id` | `str` | catalog product 참조 |
+| `product_name` | `str` | 표시용 상품명 |
+| `variant_name` | `str` | variant 이름 |
+| `location_id` | `str` | 물류 거점 식별자 |
+| `location_name` | `str` | 거점 이름 |
+| `on_hand` | `int` | 실재고 |
+| `reserved` | `int` | 선점 재고 |
+| `safety_stock` | `int` | 안전 재고 |
+| `reorder_point` | `int` | 재주문 기준점 |
+| `updated_at` | `str` | 수정 시각 |
+
+## 5. Order
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | 주문 식별자 |
+| `product_id` | `str` | 상품 참조 |
+| `product_name` | `str` | 표시용 상품명 |
+| `customer_name` | `str` | 고객명 |
+| `seller_name` | `str` | 판매자/셀러명 |
+| `status` | `str` | 결제/주문 상태 |
+| `fulfillment_status` | `str` | 이행 상태 |
+| `created_at` | `str` | 생성 시각 |
+| `amount_krw` | `int` | 주문 금액 |
+| `risk` | `str` | 운영 위험도 |
+| `stage` | `str` | 운영 단계 |
+| `sla` | `str` | SLA 표시 |
+| `is_new_today` | `bool` | 당일 신규 여부 |
+
+## 6. Fulfillment Task
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | task 식별자 |
+| `order_id` | `str` | 주문 참조 |
+| `title` | `str` | 작업 제목 |
+| `assignee` | `str` | 담당자 |
+| `stage` | `str` | 이행 단계 |
+| `status` | `str` | task 상태 |
+| `priority` | `str` | 우선순위 |
+| `channel` | `str` | 유입 채널 |
+| `sla_minutes` | `int` | SLA 분 단위 |
+| `units` | `int` | 처리 수량 |
+
+## 7. Support FAQ
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | `str` | FAQ 식별자 |
+| `question` | `str` | 질문 |
+| `answer` | `str` | 답변 |
+| `category` | `str` | FAQ 카테고리 |
+| `visibility` | `str` | 노출 여부 |
+| `updated_at` | `str` | 수정 시각 |
+
+## 8. Key Policy
+
+- 현재 템플릿은 string id를 사용한다.
+- 실제 서비스 구현 시 time-ordered UUID v7을 기본 식별자로 채택한다.
+- legacy numeric id는 새 이커머스 baseline에서 사용하지 않는다.
+- `auth`와 `user`는 같은 사람을 표현하더라도 저장 목적이 다르므로 독립 레코드로 유지한다.

package/sdd/01_planning/05_api/README.md

@@ -0,0 +1,12 @@
+# 05 API
+
+API 원천 계약을 둔다.
+
+- `/api/v1/auth/login`
+- `/api/v1/auth/me`
+- `/api/v1/users`
+- template example endpoint
+
+## Canonical Docs
+
+- [templates_api_contract.md](./templates_api_contract.md)

package/sdd/01_planning/05_api/templates_api_contract.md

@@ -0,0 +1,90 @@
+# templates server contract
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+현재 server runtime이 제공하는 HTTP contract를 구현 기준으로 정리한다.
+
+## 1. HTTP Endpoint Matrix
+
+| Method | Path | Domain | Purpose | Response |
+| --- | --- | --- | --- | --- |
+| `GET` | `/health` | health | root health probe | `{"status":"ok"}` |
+| `GET` | `/api/v1/status` | health | API health/status probe | `{"service":"template-server","status":"healthy"}` |
+| `POST` | `/api/v1/auth/login` | auth | credential 로그인과 token 발급 | `AuthToken` |
+| `GET` | `/api/v1/auth/me` | auth | bearer token 기반 현재 사용자 조회 | `AuthenticatedUser` |
+| `GET` | `/api/v1/users` | user | 사용자 summary 목록 조회 | `list[UserSummary]` |
+| `GET` | `/api/v1/users/{user_id}` | user | 단일 사용자 상세 조회 | `UserDetail` |
+| `PATCH` | `/api/v1/users/{user_id}/status` | user | 사용자 상태 변경 | `UserDetail` |
+| `GET` | `/api/v1/catalog/products` | catalog | 공개/운영 상품 목록 조회 | `list[ProductSummary]` |
+| `GET` | `/api/v1/catalog/products/{product_id}` | catalog | 단일 상품 상세 조회 | `ProductDetail` |
+| `POST` | `/api/v1/catalog/products` | catalog | 상품 생성 | `ProductDetail` |
+| `PUT` | `/api/v1/catalog/products/{product_id}` | catalog | 상품 수정 | `ProductDetail` |
+| `PATCH` | `/api/v1/catalog/products/{product_id}/status` | catalog | 상품 상태 변경 | `ProductDetail` |
+| `GET` | `/api/v1/inventory/levels` | inventory | 재고 레벨 목록 조회 | `list[InventoryLevel]` |
+| `GET` | `/api/v1/inventory/levels/{sku}/{location_id}` | inventory | 단일 재고 레벨 조회 | `InventoryLevel` |
+| `POST` | `/api/v1/inventory/levels/{sku}/{location_id}/adjustments` | inventory | 재고 증감 조정 | `InventoryMutationReceipt` |
+| `POST` | `/api/v1/inventory/levels/{sku}/{location_id}/reservations` | inventory | 재고 선점 | `InventoryMutationReceipt` |
+| `POST` | `/api/v1/inventory/levels/{sku}/{location_id}/releases` | inventory | 재고 선점 해제 | `InventoryMutationReceipt` |
+| `PUT` | `/api/v1/inventory/levels/{sku}/{location_id}` | inventory | 재고 절대값 재설정 | `InventoryMutationReceipt` |
+| `GET` | `/api/v1/orders/overview` | orders | platform dashboard overview 조회 | `OrderOverview` |
+| `GET` | `/api/v1/orders` | orders | platform order table row 조회 | `list[OrderSummary]` |
+| `POST` | `/api/v1/orders` | orders | 주문 생성 | `OrderRecord` |
+| `PATCH` | `/api/v1/orders/{order_id}/status` | orders | 주문 상태 전이 | `OrderStatusTransition` |
+| `GET` | `/api/v1/orders/admin/overview` | orders | admin dashboard 운영 overview 조회 | `AdminOrderOverview` |
+| `GET` | `/api/v1/orders/admin/queue` | orders | admin queue table row 조회 | `list[AdminQueueItem]` |
+| `GET` | `/api/v1/shipping/overview` | shipping | mobile 배송 overview 조회 | `ShippingOverview` |
+| `GET` | `/api/v1/shipping/shipments` | shipping | shipment 목록 조회 | `list[ShipmentSummary]` |
+| `PATCH` | `/api/v1/shipping/shipments/{shipment_id}/status` | shipping | 배송 상태 전이 | `ShipmentStatusTransition` |
+| `GET` | `/api/v1/alerts` | alerts | admin 운영 알람 feed 조회 | `AlertsPayload` |
+| `POST` | `/api/v1/alerts/{alert_id}/read` | alerts | 운영 알람 1건 읽음 처리 | `AlertReadResult` |
+| `POST` | `/api/v1/alerts/read-all` | alerts | 운영 알람 전체 읽음 처리 | `AlertsReadAllResult` |
+| `GET` | `/api/v1/support/faqs` | support | admin FAQ 목록 조회 | `list[SupportFaq]` |
+| `POST` | `/api/v1/support/faqs` | support | FAQ 생성 | `SupportFaqRecord` |
+| `PATCH` | `/api/v1/support/faqs/{faq_id}/visibility` | support | FAQ visibility 변경 | `SupportFaqRecord` |
+| `GET` | `/api/v1/fulfillment/overview` | fulfillment | mobile dashboard 운영 overview 조회 | `FulfillmentOverview` |
+| `GET` | `/api/v1/fulfillment/board` | fulfillment | mobile fulfillment board 조회 | `FulfillmentBoardPayload` |
+| `PATCH` | `/api/v1/fulfillment/tasks/{task_id}/status` | fulfillment | fulfillment task 상태 전이 | `FulfillmentTaskStatusTransition` |
+
+## 2. Auth Contract
+
+- 인증 방식: `Authorization: Bearer <token>`
+- login 입력: `email`, `password`
+- login 성공 시 `access_token`, `token_type`, `user_id` 반환
+- `auth/me`는 유효 token subject를 `AuthenticatedUser`로 해석
+- `users`, `catalog` command, `inventory`, `orders`, `shipping`, `alerts`, `support`, `fulfillment`는 보호된 contract다
+
+## 3. Error Baseline
+
+- invalid credential: `401 Invalid credentials`
+- invalid token: `401 Invalid token`
+- forbidden role: `403 Forbidden`
+- missing resource:
+  - HTTP: `404 ... not found`
+- conflict:
+  - duplicate catalog slug: `409 Catalog product slug already exists`
+  - invalid inventory mutation: `409 ...`
+
+## 4. Frontend Binding Notes
+
+- `client/platform`
+  - `/`는 `GET /api/v1/orders/overview`를 소비한다.
+  - `/orders`는 `GET /api/v1/orders`를 소비한다.
+- `client/admin`
+  - `/`는 `GET /api/v1/orders/admin/overview`를 소비한다.
+  - admin shell과 dashboard는 `GET /api/v1/alerts`를 운영 알람 source로 사용한다.
+  - `/queue`는 `GET /api/v1/orders/admin/queue`를 소비한다.
+  - `/support`는 `GET /api/v1/support/faqs`를 소비한다.
+- `client/mobile`
+  - `/`는 `GET /api/v1/fulfillment/overview`를 소비한다.
+  - `/fulfillment`는 `GET /api/v1/fulfillment/board`를 소비한다.
+  - `/shipping`은 `GET /api/v1/shipping/overview`, `GET /api/v1/shipping/shipments`를 소비한다.
+- `client/landing`
+  - `/`와 `/workspace`는 `GET /api/v1/catalog/products`를 live catalog surface로 사용한다.
+- auth flow는 네 app 모두 `POST /api/v1/auth/login`과 `GET /api/v1/auth/me`를 유지한다.
+
+## 5. Stack Notes
+
+- HTTP: `FastAPI 0.116.x + Uvicorn 0.35.x`
+- Compose runtime: `server`

package/sdd/01_planning/06_iac/README.md

@@ -0,0 +1,11 @@
+# 06 IaC
+
+템플릿 런타임 부팅 원천 자료를 둔다.
+
+- Dockerfile
+- compose
+- env contracts
+
+## Canonical Docs
+
+- [templates_runtime_and_cicd_baseline.md](./templates_runtime_and_cicd_baseline.md)

package/sdd/01_planning/06_iac/templates_runtime_and_cicd_baseline.md

@@ -0,0 +1,46 @@
+# templates runtime and cicd baseline
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+템플릿 저장소의 root compose runtime baseline과 CI baseline을 정리한다.
+
+## 1. Compose Runtime Baseline
+
+| Surface | Default Port |
+| --- | --- |
+| landing | `3000` |
+| platform | `3001` |
+| mobile | `3002` |
+| admin | `4000` |
+| api | `8000` |
+
+## 2. Compose Rule
+
+- root `compose.yml`이 canonical dev-focused runtime baseline이다.
+- dedicated host용 DEV(개발계)/PROD overlay는 `infra/compose/dev.yml`, `infra/compose/prod.yml`을 사용한다.
+- 환경변수 contract는 `.env.example`을 source-of-truth로 유지한다.
+
+## 3. CI/CD Rule
+
+- 이 레포는 템플릿 저장소이므로 실제 배포를 수행하지 않는다.
+- `.github/workflows`는 다음만 책임진다.
+  - root compose/overlay config validation
+  - backend test
+  - frontend build matrix
+  - AST build audit와 parity target resolution
+  - canonical Terraform skeleton validate
+
+## 4. Delivery Note
+
+- 실제 서비스 레포로 clone된 뒤 DEV/PROD deploy workflow를 추가한다.
+- template repo의 workflow는 `검증용 CI`만 유지한다.
+
+## 5. Remote Infra Template Layout
+
+- canonical Terraform split은 `infra/terraform/aws/data`, `infra/terraform/aws/domain`, `infra/terraform/openstack/server`다.
+- `infra/terraform/openstack/dev`, `infra/terraform/openstack/prod`는 lower-level starter root로 유지한다.
+- 공통 OpenStack host/network/security group 로직은 `infra/terraform/openstack/modules/environment_host`에 둔다.
+- DEV(개발계)와 PROD는 별도 Terraform state를 사용한다.
+- cloud-init compose 자동 기동은 각 환경 root의 `compose_env_content`와 `deploy_compose_on_boot`로 제어한다.

package/sdd/01_planning/07_integration/README.md

@@ -0,0 +1,11 @@
+# 07 Integration
+
+프론트와 `api`의 통합 원천 시나리오를 둔다.
+
+- login flow
+- token persistence
+- adapter selection
+
+## Canonical Docs
+
+- [templates_frontend_api_integration.md](./templates_frontend_api_integration.md)

package/sdd/01_planning/07_integration/templates_frontend_api_integration.md

@@ -0,0 +1,46 @@
+# templates frontend api integration
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+현재 frontend와 backend의 실제 연결 지점을 정리한다.
+
+## 1. Shared Integration Rule
+
+- 네 개의 frontend 모두 공통 `auth` contract를 사용한다.
+- `POST /api/v1/auth/login`으로 access token을 발급받고 로컬 storage에 저장한다.
+- `GET /api/v1/auth/me`로 초기 세션을 복원한다.
+
+## 2. Service Coupling Summary
+
+| Service | Real Backend Coupling | Note |
+| --- | --- | --- |
+| platform | `auth`, `orders` | dashboard overview와 orders table을 live contract에 연결 |
+| admin | `auth`, `orders`, `alerts`, `support` | overview/queue/support surface와 alerts drawer를 live contract에 연결 |
+| mobile | `auth`, `fulfillment`, `shipping` | dashboard overview와 fulfillment/shipping surface를 live contract에 연결 |
+| landing | `auth`, `catalog` | home/workspace에서 catalog products를 읽어 public/protected surface를 구성 |
+
+## 3. Coupling Detail
+
+- platform
+  - bearer session은 기존 `AuthProvider`가 유지한다.
+  - page load 시 `orders/overview`, `orders`를 fetch하고 search는 client-side filter로 처리한다.
+- admin
+  - protected route는 그대로 유지한다.
+  - dashboard는 `orders/admin/overview`와 `alerts`를 병렬 fetch한다.
+  - queue, support, alerts drawer는 개별 page-level effect로 fetch한다.
+- mobile
+  - overview와 board payload는 mobile shell 진입 후 fetch한다.
+  - status/tone badge는 response의 string field를 frontend palette에 매핑한다.
+  - board route는 `/fulfillment`다.
+  - shipping route는 `/shipping`이고 shipment status feed를 별도 fetch한다.
+- landing
+  - public home에서도 `catalog/products`를 읽어 live catalog proof를 보여준다.
+  - protected workspace는 auth user summary와 catalog product grid를 함께 노출한다.
+
+## 4. Known Gaps
+
+- platform/admin은 아직 catalog/inventory command surface를 직접 소비하지 않는다.
+- order 생성, fulfillment 전이, shipping 전이, support create/update, alerts read는 backend contract로 존재하지만 frontend action UI는 baseline 최소 액션 중심이다.
+- landing은 catalog read를 public/protected दोनों surface에 재사용하지만 category/detail 분해까지는 아직 없다.

package/sdd/01_planning/08_nonfunctional/README.md

@@ -0,0 +1,7 @@
+# 08 Nonfunctional
+
+비기능 요구 원천 자료를 둔다.
+
+- build reproducibility
+- template startup speed
+- DX requirements

package/sdd/01_planning/09_security/README.md

@@ -0,0 +1,7 @@
+# 09 Security
+
+보안 원천 자료를 둔다.
+
+- bootstrap credential handling
+- JWT secret rules
+- CORS baseline

package/sdd/01_planning/10_test/README.md

@@ -0,0 +1,12 @@
+# 10 Test
+
+테스트 원천 목록을 둔다.
+
+- frontend build matrix
+- api pytest matrix
+- auth runtime smoke
+- compose validation
+
+## Canonical Docs
+
+- [templates_test_strategy.md](./templates_test_strategy.md)

package/sdd/01_planning/10_test/templates_test_strategy.md

@@ -0,0 +1,60 @@
+# templates test strategy
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+template baseline을 유지하기 위한 테스트 전략을 정의한다.
+
+## 1. Backend
+
+- `server/tests/e2e/test_domain_feature_flows.py`
+  - `AUT-F001`
+  - `AUT-F002`
+  - `USR-F001`
+  - `USR-F002`
+  - `USR-F003`
+  - `CAT-F001`
+  - `CAT-F003`
+  - `CAT-F004`
+  - `CAT-F005`
+  - `INV-F001`
+  - `INV-F002`
+  - `INV-F003`
+  - `INV-F004`
+  - `INV-F005`
+  - `INV-F006`
+  - `ORD-F001`
+  - `ORD-F002`
+  - `ORD-F003`
+  - `ORD-F004`
+  - `ORD-F005`
+  - `ORD-F006`
+  - `SHP-F001`
+  - `SHP-F002`
+  - `SHP-F003`
+  - `ALR-F001`
+  - `ALR-F002`
+  - `ALR-F003`
+  - `SUP-F001`
+  - `SUP-F002`
+  - `SUP-F003`
+  - `FUL-F001`
+  - `FUL-F002`
+  - `FUL-F003`
+- `server/tests/test_health.py`
+  - `HLT-F001`
+  - `HLT-F002`
+  - auth/user smoke
+
+## 2. Frontend
+
+- `platform`, `admin`, `mobile`, `landing`는 각 서비스별 production build를 통과해야 한다.
+- screen spec은 `PLT-S001`, `ADM-S001`, `MOB-S001`, `LND-S001` 규칙으로 구현 route와 관련 feature를 함께 검증한다.
+- parity harness가 활성화되면 route-gap과 proof artifact를 추가 검증한다.
+
+## 3. CI Gate
+
+- backend: `./.venv/bin/python -m pytest -q` 또는 CI 환경의 `uv run pytest -q`
+- frontend: `pnpm build` matrix
+- toolchain: `build_screen_spec_pdf.py`, `capture_screen_assets.mjs`, `new_plan.sh` shell validation

package/sdd/01_planning/INDEX.md

@@ -0,0 +1,19 @@
+# Planning Index
+
+- [01_feature/INDEX.md](./01_feature/INDEX.md)
+- [02_screen/INDEX.md](./02_screen/INDEX.md)
+- [03_architecture/INDEX.md](./03_architecture/INDEX.md)
+- [04_data/INDEX.md](./04_data/INDEX.md)
+- [05_api/README.md](./05_api/README.md)
+- [06_iac/README.md](./06_iac/README.md)
+- [07_integration/README.md](./07_integration/README.md)
+- [08_nonfunctional/README.md](./08_nonfunctional/README.md)
+- [09_security/README.md](./09_security/README.md)
+- [10_test/README.md](./10_test/README.md)
+
+## Structure Rule
+
+- `01_feature`, `02_screen`는 실제 서비스 표면(`platform`, `mobile`, `admin`, `landing`) 기준으로 유지한다.
+- `03_architecture` 이후는 서비스별 실산출물이 없으면 common-first로 유지한다.
+- `03_architecture`는 공통 문서를 먼저 두고 필요 시 `frontend/`, `backend/`, `infra/`, `tech-research/`로 세분화한다.
+- 데이터 모델링은 `04_data`에서 다루고 architecture 문서에는 중복 기록하지 않는다.

package/sdd/01_planning/README.md

@@ -0,0 +1,17 @@
+# Planning Governance
+
+## Purpose
+
+- `sdd/01_planning/`은 현재 구현과 검수의 기준이 되는 canonical spec을 유지한다.
+- feature, screen, architecture, data, API, IAC, integration, nonfunctional, security, test planning 모두 현재 기준만 남긴다.
+
+## Final-Only Rule
+
+- planning도 날짜별 작업 메모나 히스토리성 보조 문서를 쌓지 않는다.
+- 계속 참고할 가치가 있는 리서치만 현재형 문서로 유지한다.
+- source reference가 필요하면 현재 canonical source만 남기고, raw capture log나 일회성 추출 로그는 두지 않는다.
+
+## Structure Rule
+
+- `01_feature`, `02_screen`는 실제 서비스 표면 기준으로 유지한다.
+- `03_architecture` 이후 planning 폴더는 서비스별 실산출물이 없으면 common-first 구조로 유지한다.

package/sdd/02_plan/01_feature/README.md

@@ -0,0 +1,34 @@
+# Feature TODO Rule
+
+## Common Rule
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 다른 `02_plan` 폴더와 동일하게 `README.md + durable TODO 파일`만 유지하고, dated plan history는 두지 않는다.
+
+## Canonical Rule
+
+- 기능 계획은 domain별 durable TODO 파일로 관리한다.
+- 신규 작업이 생겨도 날짜별 파일을 추가하지 않는다.
+- 같은 domain 파일 안에서는 canonical 기능코드 기준 표만 계속 갱신한다.
+- service feature spec은 source reference로만 사용하고, active TODO는 domain 파일만 유지한다.
+
+## Naming
+
+- 파일명은 날짜 prefix를 쓰지 않는다.
+- 권장 형식: `{domain}_todos.md`
+
+## Location
+
+- active feature TODO는 `sdd/02_plan/01_feature/` root에 둔다.
+
+## Minimum Sections
+
+- domain summary
+- feature items
+- acceptance criteria
+- current notes
+- latest verification
+
+## Template
+
+- [`_feature_todo_template.md`](_feature_todo_template.md)

package/sdd/02_plan/01_feature/_feature_todo_template.md

@@ -0,0 +1,29 @@
+# {domain code} {domain name}
+
+- Owner: Codex
+- Status: active
+
+## Domain Summary
+
+- domain code:
+- canonical source:
+- update rule: 이 파일 안에서 feature code 기준으로 계속 갱신한다.
+
+## Feature Items
+
+| Feature Code | Use Case | Status | Current Notes |
+| --- | --- | --- | --- |
+| `{DOMAIN}-F001` |  | `planned` |  |
+
+## Acceptance Criteria
+
+- [ ] 이 파일이 해당 domain feature TODO의 single source of truth로 유지된다.
+- [ ] 신규 작업은 해당 feature code row와 current notes만 갱신한다.
+
+## Current Notes
+
+- TODO는 canonical domain feature code 기준으로만 유지한다.
+
+## Latest Verification
+
+- current plan normalization reference: `sdd/02_plan/01_feature/<domain>_todos.md`

package/sdd/02_plan/02_screen/INDEX.md

@@ -0,0 +1,19 @@
+# Screen TODO Index
+
+## Canonical Sources
+
+- [mobile_screen_spec.pdf](../../01_planning/02_screen/mobile_screen_spec.pdf)
+- [platform_screen_spec.pdf](../../01_planning/02_screen/platform_screen_spec.pdf)
+- [admin_screen_spec.pdf](../../01_planning/02_screen/admin_screen_spec.pdf)
+- [landing_screen_spec.pdf](../../01_planning/02_screen/landing_screen_spec.pdf)
+
+## Current Planning Templates
+
+- [README.md](./README.md)
+- [_screen_todo_template.md](./_screen_todo_template.md)
+
+## Naming Rule
+
+- active screen plan file: `<service>_todos.md`
+- screen section identifier inside file: `{SERVICE}-S{NNN}`
+- mobile legacy source key는 필요할 때만 문서 내부에서 `APP_###` field로 기록한다.

package/sdd/02_plan/02_screen/README.md

@@ -0,0 +1,39 @@
+# Screen TODO Rule
+
+## Common Rule
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 다른 `02_plan` 폴더와 동일하게 `README.md + durable TODO 파일`만 유지하고, dated plan history는 두지 않는다.
+- 개발계가 있는 화면 작업은 `구현 -> build -> DEV(개발계) 배포 -> DEV 검수 -> 같은 TODO 파일 갱신`을 기본 루틴으로 둔다.
+
+## Canonical Rule
+
+- 화면 계획은 service별 durable TODO 파일로 관리한다.
+- `01_feature`와 동일하게 날짜별 작업 문서를 계속 추가하지 않는다.
+- 같은 service 파일 안에서 화면코드 기준으로 계속 갱신한다.
+- mobile source key인 `APP_###`는 파일명이 아니라 문서 내부 field로만 기록한다.
+- 과거 screen plan 문서는 별도 보관하지 않고, 현재 기준 README와 service TODO만 유지한다.
+
+## Location
+
+- 서비스별 화면 TODO는 `sdd/02_plan/02_screen/` root에 둔다.
+- 예:
+  - `sdd/02_plan/02_screen/mobile_todos.md`
+  - `sdd/02_plan/02_screen/platform_todos.md`
+
+## Naming
+
+- 파일명은 날짜 prefix를 쓰지 않는다.
+- 권장 형식: `{service}_todos.md`
+
+## Minimum Sections
+
+- service summary
+- shared constraints or baseline
+- screen items
+- delivery phases or backlog
+- latest verification references
+
+## Template
+
+- [`_screen_todo_template.md`](_screen_todo_template.md)

package/sdd/02_plan/02_screen/_screen_todo_template.md

@@ -0,0 +1,60 @@
+# {service} screen TODO
+
+- Owner: Codex
+- Status: active
+
+## Service Summary
+
+- service:
+- canonical source:
+- update rule: 이 파일 안에서 화면코드 기준으로 계속 갱신한다.
+
+## Shared Constraints
+
+- source key rule:
+- route baseline:
+- shared API/modeling note:
+
+## Screen Items
+
+### {screen code} {screen name}
+
+#### Screen Summary
+
+- source key:
+- route:
+- retained runtime tree:
+- local exactness suite id:
+- canonical runner command: `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite <suite-id> --base-url <url>`
+
+#### Acceptance Criteria
+
+- [ ]
+- [ ] relevant builder/design guide baseline is current for this surface
+- [ ] Playwright exactness suite exists or is extended in the same task
+- [ ] verify artifact path (`json/png`) is identified before implementation closes
+
+#### Open TODO
+
+- [ ]
+
+#### Current Notes
+
+- current scope/status notes only
+- use Browser Use/manual capture only as supplemental diagnosis when a Playwright suite already exists
+
+#### Latest Verification
+
+- current build/verify references:
+- latest exactness command:
+- latest exactness artifact:
+
+## Delivery Phases
+
+- `P0`:
+- `P1`:
+- `P2`:
+
+## Current Notes
+
+- current service-level notes only