agentic-dev 0.1.0 → 0.2.1

package/sdd/02_plan/03_architecture/README.md

@@ -0,0 +1,23 @@
+# Architecture Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 이 폴더는 구조, 리포지토리 거버넌스, 런타임 정렬, 툴체인 규칙 같은 횡단 계획을 durable 문서로 유지한다.
+- 날짜 기반 작업 메모는 남기지 않고, 현재 적용돼야 하는 규칙과 backlog만 덮어쓴다.
+
+## Plan Rule
+
+- 다른 `02_plan` 폴더와 동일하게 `README.md + durable 문서`만 유지하고, dated plan history는 두지 않는다.
+- `sdd/02_plan`은 현재 실행해야 할 기준만 남기고, 과거 계획 히스토리는 보관하지 않는다.
+- 개발계가 있는 대상은 `구현 -> build -> main push -> DEV(개발계) 배포 -> DEV 검수 -> 문서 갱신`을 기본 루틴으로 본다.
+- feature는 domain TODO 파일 안에서 기능코드 기준으로 관리한다.
+- screen은 service TODO 파일 안에서 화면코드 기준으로 관리한다.
+- architecture, IAC, test도 dated memo 대신 section README와 durable governance 문서에서 현재 규칙만 유지한다.
+- `02_plan` section 구조와 README 규칙은 final-only 기준으로 유지한다.
+
+## Current Documents
+
+- [architecture_document_governance.md](architecture_document_governance.md)
+- [repository_governance.md](repository_governance.md)
+- [runtime_and_structure_governance.md](runtime_and_structure_governance.md)
+- [toolchain_governance.md](toolchain_governance.md)
+- [templates-hexagonal-template-architecture.md](templates-hexagonal-template-architecture.md)

package/sdd/02_plan/03_architecture/architecture_document_governance.md

@@ -0,0 +1,40 @@
+# architecture document governance
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - `sdd/01_planning/03_architecture` 문서 구조와 경계를 공통 규칙으로 정의한다.
+  - 아키텍처 planning 문서는 공통/일반화된 구조를 우선 기록하되, 필요 시 `frontend`, `backend`, `infra`, `tech-research`로 특화 문서를 둔다.
+  - 프런트엔드, 백엔드, 인프라의 구조/패턴/구현 선택을 architecture 범위로 유지한다.
+  - 데이터 모델링 경계는 `sdd/01_planning/04_data`로 분리한다.
+- Out of scope:
+  - feature별 business rule 상세
+  - screen별 route/CTA/전이 상세
+  - entity/schema/ERD 수준의 데이터 모델링 상세
+
+## Acceptance Criteria
+
+- [ ] `03_architecture`는 공통 아키텍처 문서와 특화 아키텍처 문서를 함께 수용하는 구조로 설명된다.
+- [ ] frontend/backend/infra가 architecture 범위에 포함된다는 점이 planning 문서에 명시된다.
+- [ ] data modeling은 `04_data` 경계로 분리된다는 점이 planning 문서에 명시된다.
+
+## Current Notes
+
+- architecture 문서는 우선 공통 구조를 설명하고, 세부 구현 논점이 필요할 때만 영역별 문서로 내려간다.
+- frontend architecture는 모듈화, 컴포넌트, store/state, domain/use case, UI/UX, storage, API adapter 패턴을 다룬다.
+- backend architecture는 DDD context 구조, context 내부 계층, 3-layer, hexagonal, monolith/MSA/EDA/CQRS 같은 패턴과 실제 구현체 선택을 다룬다.
+- infra architecture는 컨테이너, 오케스트레이션, 데이터베이스, 네트워크, 이중화, 멀티리전 같은 서비스 기반 구조를 다룬다.
+
+## Validation
+
+- current references:
+  - `sdd/01_planning/03_architecture/README.md`
+  - `sdd/01_planning/03_architecture/INDEX.md`
+  - `sdd/01_planning/03_architecture/architecture_document_structure.md`
+  - `sdd/01_planning/03_architecture/frontend/README.md`
+  - `sdd/01_planning/03_architecture/backend/README.md`
+  - `sdd/01_planning/03_architecture/infra/README.md`
+  - `sdd/01_planning/04_data/README.md`

package/sdd/02_plan/03_architecture/build_ast_runtime_tree_governance.md

@@ -0,0 +1,53 @@
+# build ast runtime tree governance
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - `sdd/03_build` service summary를 실제 템플릿 runtime assembly 기준으로 재정렬한다.
+  - Claude/Codex/Ralph 하네스가 동일한 current-state build reading 규칙을 따르도록 canonical policy를 추가한다.
+  - `scripts/dev/audit_sdd_build_ast.py`를 템플릿 정본 gate로 유지한다.
+  - provider-first infra baseline과 build/runtime/toolchain 문서 간의 current-state drift를 줄인다.
+- Out of scope:
+  - 템플릿 앱/서버의 기능 요구사항 자체 변경
+  - 제품별 downstream branding이나 credential 값 추가
+
+## Assumptions
+
+- template repo의 `sdd/03_build`는 clone 이후 downstream repo가 그대로 이어받는 current-state 설명 문서다.
+- AST-style build 문서는 모든 관계를 하나의 트리에 과적재하지 않고, 주 runtime chain과 cross-cutting contract를 분리해 설명한다.
+- agentic harness는 repo-local path와 generic scaffold만 포함하고 실제 run 산출물은 commit 대상이 아니다.
+
+## Acceptance Criteria
+
+- [x] `scripts/dev/audit_sdd_build_ast.py`가 `ast_similarity=10`, `implementation_traceability=10`, `human_agent_readability=10`을 반환한다.
+- [x] `mobile`, `platform`, `admin`, `landing` service summary가 실제 `main.tsx -> AuthProvider -> BrowserRouter -> App -> ProtectedRoute/shell -> route leaf` 체인을 반영한다.
+- [x] `README`, `AGENTS`, `CLAUDE`, toolchain policy가 `.agent`, role agent, skill alias, AST current-state 규칙을 같이 설명한다.
+- [x] template infra 문서는 provider-first baseline(`aws/data`, `aws/domain`, `openstack/server`)을 current canonical split으로 설명한다.
+
+## Execution Checklist
+
+- [x] 기존 템플릿의 agentic/toolchain/AST 누락 축을 정리한다.
+- [x] `.agent` Ralph scaffold와 Claude/Codex alias/role surface를 추가한다.
+- [x] AST audit script와 plan/build/verify current-state 문서를 추가한다.
+- [x] service build summary를 runtime tree 기준으로 재작성한다.
+- [x] infra current-state 문서를 provider-first baseline으로 갱신한다.
+- [x] root compose baseline을 provider-first runtime split까지 더 일반화할 추가 필요 여부를 follow-up으로 평가한다.
+
+## Work Log
+
+- 2026-03-19: `templates`가 starter scaffold로는 충분하지만 `passv`/`palcar`에서 검증된 agentic harness, AST build governance, provider-first infra split이 빠져 있어 canonical repo로 승격이 필요하다고 정리했다.
+- 2026-03-19: `.agent` Ralph scaffold, Claude role agent surface, Codex alias skill, OTRO validation helper 문서를 정본에 추가하기로 결정했다.
+- 2026-03-19: `sdd/03_build/01_feature/service/*.md`를 실제 템플릿 runtime composition 기준으로 다시 쓰고 AST gate로 검증하는 흐름을 고정했다.
+- 2026-03-19: infra current-state는 기존 `openstack/dev|prod` 설명에 더해 `aws/data`, `aws/domain`, `openstack/server` provider-first split을 canonical baseline으로 반영했다.
+- 2026-03-19: AST gate와 `terraform validate` 3종이 모두 통과해 canonical template upgrade의 구조적 baseline을 고정했다.
+
+## Validation
+
+- `python3 scripts/dev/audit_sdd_build_ast.py --write .agent/sdd-build-ast-audit.json`
+- `rg -n "Ralph|iteration|Current Build Note|2026-" sdd/03_build -g '*.md'`
+- `terraform -chdir=infra/terraform/aws/data init -backend=false && terraform -chdir=infra/terraform/aws/data validate`
+- `terraform -chdir=infra/terraform/aws/domain init -backend=false && terraform -chdir=infra/terraform/aws/domain validate`
+- `terraform -chdir=infra/terraform/openstack/server init -backend=false && terraform -chdir=infra/terraform/openstack/server validate`

package/sdd/02_plan/03_architecture/repository_governance.md

@@ -0,0 +1,39 @@
+# repository governance
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - `main` canonical branch 운영
+  - repo path와 주요 문서 구조 정합성 유지
+  - SDD final-only 원칙 유지
+- Out of scope:
+  - 서비스별 feature/screen 상세 TODO
+
+## Acceptance Criteria
+
+- [x] `main`을 정본 브랜치로 유지한다.
+- [x] repo 경로와 주요 문서는 현재 `client/*`, `server/*`, `sdd/*` 구조를 기준으로 설명한다.
+- [x] plan/build/verify/operate는 dated history 없이 durable 문서만 유지한다.
+
+## Execution Checklist
+
+- [x] branch 운영 원칙을 현재 방식으로 고정한다.
+- [x] repo 주요 경로 기준을 `client/*`, `server/*`, `sdd/*` 구조로 고정한다.
+- [x] SDD final-only 원칙을 반영한다.
+
+## Current Notes
+
+- `main`을 canonical branch로 유지하는 규칙을 사용한다.
+- 템플릿 frontend 경로는 `client/platform`, `client/admin`, `client/mobile`, `client/landing` 기준이다.
+- SDD는 최종 일관성 문서만 유지하고, raw 운영 로그는 runtime logging system에 남긴다.
+- data modeling 계획 루트는 `sdd/01_planning/04_data`와 `sdd/02_plan/04_data`를 기준으로 유지한다.
+
+## Validation
+
+- current references:
+  - `AGENTS.md`
+  - `sdd/03_build/03_architecture/repository_governance.md`
+  - `sdd/04_verify/03_architecture/repository_governance.md`

package/sdd/02_plan/03_architecture/runtime_and_structure_governance.md

@@ -0,0 +1,38 @@
+# runtime and structure governance
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - template repo의 `server/*`, `client/*`, `infra/*` current 구조 기준 유지
+  - screen PDF, toolchain, runtime entrypoint 같은 현재 구조 설명
+- Out of scope:
+  - 서비스별 구현 상세
+
+## Acceptance Criteria
+
+- [x] repo structure 설명은 현재 폴더 구조를 기준으로 유지한다.
+- [x] runtime path와 screen planning path는 현재 canonical 위치만 가리킨다.
+- [x] dated refactor memo 없이 current structure만 남긴다.
+
+## Execution Checklist
+
+- [x] repo structure 기준 경로를 다시 점검한다.
+- [x] stale path reference를 current path로 교체한다.
+- [x] runtime/structure 설명을 durable 문서로 유지한다.
+
+## Current Notes
+
+- backend는 `server/contexts/*`, frontend는 `client/*`, 인프라는 `infra/*` current structure를 기준으로 설명한다.
+- screen planning은 `sdd/01_planning/02_screen/*.pdf`를 canonical source로 유지한다.
+- architecture planning은 root common docs + `frontend/`, `backend/`, `infra/`, `tech-research/` split을 기준으로 유지한다.
+- 저장소 구조 정렬 결과는 현재 디렉터리 기준만 남긴다.
+
+## Validation
+
+- current references:
+  - `sdd/01_planning/README.md`
+  - `sdd/03_build/03_architecture/repository_governance.md`
+  - `sdd/04_verify/03_architecture/repository_governance.md`

package/sdd/02_plan/03_architecture/templates-hexagonal-template-architecture.md

@@ -0,0 +1,9 @@
+# Templates Hexagonal Template Architecture
+
+현재 템플릿 레포의 기본 아키텍처 원칙:
+
+- 프론트는 `React + Tailwind + CSS token surface`
+- 백엔드는 `hexagonal + DDD`
+- 컨텍스트 외부 진입점은 `contracts`
+- adapter는 교환 가능해야 하며 application/domain은 저장소 세부사항을 직접 알지 않는다
+- 데이터 모델링 상세는 architecture가 아니라 `04_data`에서 다룬다

package/sdd/02_plan/03_architecture/toolchain_governance.md

@@ -0,0 +1,98 @@
+# toolchain governance
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - `sdd/99_toolchain` 아래 자동화 도구와 policy 문서의 current rule 유지
+  - Playwright exactness runner/manifest를 local screen regression의 canonical gate로 유지
+  - skill/tooling path와 proof artifact path 정렬
+  - local Claude/Codex `sdd` skill의 canonical path와 실제 저장소 구조 정렬
+  - `sdd` skill의 rollout gate를 explicit deployment scope 기준으로 제한
+  - 존재하지 않는 template builder file을 required canonical path처럼 안내하지 않도록 정리
+  - 프로젝트 루트에서 `sdd` skill을 설명하는 단일 entrypoint 문서 유지
+  - 루트 `SDD_SKILL.md`가 workflow, `sdd/` 구조, flow별 설명까지 포함하도록 확장
+  - 루트 `SDD_SKILL.md`가 toolchain, visual fidelity, exactness, functional alignment 구조까지 설명하도록 확장
+  - 루트 `SDD_SKILL.md`가 `sdd` 스킬의 trigger, non-use case, governance, section map, schema parity, regression, rollout, completion gate까지 포함하도록 확장
+  - ignored 상태였던 durable local scaffold/config를 template-tracked asset으로 승격
+- Out of scope:
+  - 개별 서비스 구현
+
+## Acceptance Criteria
+
+- [x] skill/tooling 관련 경로가 current SDD 구조를 가리킨다.
+- [x] proof artifact 예시도 final-only verify structure를 따른다.
+- [x] toolchain 설명은 현재 workflow rule만 남긴다.
+- [x] 화면명세 기반 정적 자산은 canonical `스펙에셋빌더` 선행 추출 rule을 current workflow로 유지한다.
+- [x] 회귀 검수 범위 선택 rule이 policy, toolchain, skill, SDD test 문서에 공통 반영된다.
+- [x] `.claude/skills/sdd-dev/SKILL.md`의 Codex canonical path가 실제 `.codex/skills/sdd/` 구조를 가리킨다.
+- [x] `sdd` skill은 rollout이 explicit scope일 때만 DEV/PROD/rollback gate를 completion bar로 해석한다.
+- [x] 디자인 가이드 builder 안내는 현재 저장소에 실제로 존재하는 automation inventory 기준으로만 적는다.
+- [x] 프로젝트 루트에서 `sdd` skill 용도와 canonical path를 빠르게 확인할 수 있는 단일 markdown entrypoint가 있다.
+- [x] `SDD_SKILL.md`는 요약 수준을 넘어서 workflow, folder structure, flow별 역할을 명확하게 설명한다.
+- [x] `SDD_SKILL.md`는 toolchain 역할과 visual fidelity / exactness / 기능 정합성 구조를 명확하게 설명한다.
+- [x] `SDD_SKILL.md`는 `sdd` 스킬의 거의 전체 해설서 수준으로 trigger, artifact rule, rollout gate, completion gate까지 설명한다.
+- [x] durable local scaffold/config 파일은 tracked asset으로 승격되고, generated/cache artifact는 계속 ignore된다.
+- [x] Playwright screen exactness는 ad-hoc CLI가 아니라 `sdd/99_toolchain/01_automation/` wrapper/manifest 기준으로 실행한다.
+
+## Execution Checklist
+
+- [x] stale verify/build path를 current path로 교체한다.
+- [x] toolchain README와 design note를 current governance와 정렬한다.
+- [x] reusable template path를 final-only 구조에 맞춘다.
+- [x] screen-spec static asset extraction rule을 skill과 toolchain 문서에 공통 반영한다.
+- [x] regression verification rule을 policy, skill, toolchain, test planning에 공통 반영한다.
+- [x] Claude `sdd-dev` alias가 stale `.codex/skills/sdd-dev/` 경로를 참조하지 않도록 정리한다.
+- [x] Codex/Claude `sdd` skill에서 rollout gate를 explicit deployment scope 조건으로 정리한다.
+- [x] 존재하지 않는 `screen_design_guide_builder.py`를 template canonical file처럼 적지 않도록 수정한다.
+- [x] 루트에 `sdd` skill 요약 문서를 추가하고 canonical source를 명시한다.
+- [x] 루트 `SDD_SKILL.md`에 workflow 단계, section 역할, flow별 상세 설명을 보강한다.
+- [x] 루트 `SDD_SKILL.md`에 toolchain, parity/proof, exactness, functional alignment 설명을 추가한다.
+- [x] 루트 `SDD_SKILL.md`에 trigger rule, non-use case, governance, section routing, schema parity, regression, completion gate 설명을 추가한다.
+- [x] `.claude/settings.local.json`, `.agent/sdd-build-ast-audit.json`, `.agent/runs/README.md`를 tracked asset으로 승격한다.
+- [x] `node_modules`, `dist`, `.venv`, `.terraform`, cache 계열은 generated/local artifact로 계속 제외한다.
+- [x] Playwright exactness suite registry와 runner를 toolchain canonical entrypoint로 편입한다.
+- [x] screen template가 suite id와 canonical runner command를 기본 항목으로 가진다.
+
+## Current Notes
+
+- toolchain은 `sdd/99_toolchain/01_automation`, `02_policies`, `03_templates` current split을 따른다.
+- Playwright local exactness는 `run_playwright_exactness.py`와 `playwright_exactness_manifest.py`를 canonical entrypoint로 사용한다.
+- screen 작업은 가능하면 `npx playwright test ...`를 직접 쓰지 않고 toolchain runner를 통해 suite id 기준으로 실행한다.
+- proof artifact는 `sdd/04_verify/10_test/ui_parity/` current path를 기준으로 관리한다.
+- toolchain 정책 문서의 정본은 `sdd/99_toolchain/02_policies`에 둔다.
+- skill/tooling 사용 여부는 개별 dated memo가 아니라 현재 workflow rule로만 유지한다.
+- 화면명세서의 icon/image/logo 등 재사용 가능한 정적 자산은 `spec_asset_builder.py` 또는 wrapper를 먼저 사용해 추출하고, 수동 재작성은 builder가 표현하지 못하는 경우에만 예외로 허용한다.
+- reusable asset planning root는 `sdd/01_planning/02_screen/assets/`이고, local Codex/Claude `sdd` skill도 같은 경로 기준으로 유지한다.
+- 회귀 검수는 direct target-only 확인으로 끝내지 않고, `sdd/02_plan/10_test/regression_verification.md` 기준으로 selected surface를 retained current-state로 남긴다.
+- Claude `sdd-dev` canonical asset reference는 현재 저장소의 `.codex/skills/sdd/` path를 기준으로 맞춘다.
+- rollout, DEV/PROD gate, rollback rule은 사용자가 배포를 요청했거나 저장소의 current policy/plan이 rollout을 completion bar로 올린 경우에만 강제한다.
+- 디자인 가이드 builder reference는 실제 존재하는 automation inventory를 기준으로 적고, 없는 file path를 canonical prerequisite처럼 고정하지 않는다.
+- 루트 `SDD_SKILL.md`는 단순 요약이 아니라 입문용 설명 문서로 유지하되, canonical rule은 local skill 원문과 toolchain policy에 둔다.
+- 루트 `SDD_SKILL.md`는 builder/harness/policy가 visual fidelity, exactness, 기능 정합성을 어떻게 연결하는지까지 설명한다.
+- 루트 `SDD_SKILL.md`는 skill 원문을 읽기 전에 전체 mental model을 잡는 해설서 역할을 하도록 유지한다.
+- `.claude/settings.local.json`은 local permission preset이지만 현재 템플릿이 재사용하는 scaffold로 승격한다.
+- `.agent/sdd-build-ast-audit.json`과 `.agent/runs/README.md`는 Ralph/AST scaffold의 durable template asset으로 승격한다.
+- generated output인 `dist`, `node_modules`, `.venv`, `.terraform`, cache, runtime run output은 계속 template commit 대상에서 제외한다.
+
+## Validation
+
+- current references:
+  - `AGENTS.md`
+  - `.codex/skills/sdd/SKILL.md`
+  - `.claude/skills/sdd/SKILL.md`
+  - `.claude/skills/sdd-dev/SKILL.md`
+  - `.claude/settings.local.json`
+  - `.agent/sdd-build-ast-audit.json`
+  - `.agent/runs/README.md`
+  - `SDD_SKILL.md`
+  - `sdd/01_planning/02_screen/assets/README.md`
+  - `sdd/99_toolchain/01_automation/README.md`
+  - `sdd/99_toolchain/01_automation/playwright_exactness_manifest.py`
+  - `sdd/99_toolchain/01_automation/run_playwright_exactness.py`
+  - `sdd/02_plan/10_test/verification_strategy.md`
+  - `sdd/04_verify/10_test/verification_harness.md`
+  - `sdd/99_toolchain/02_policies/regression-verification-policy.md`
+  - `sdd/02_plan/10_test/regression_verification.md`

package/sdd/02_plan/04_data/README.md

@@ -0,0 +1,5 @@
+# Data Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 데이터 모델, 관계, 키 정책 정렬 계획을 현재형 durable 문서로 유지한다.
+- dated data planning memo를 쌓지 않는다.

package/sdd/02_plan/05_api/README.md

@@ -0,0 +1,5 @@
+# API Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- API contract, request/response, transport rule 정렬 계획을 현재형 durable 문서로 유지한다.
+- dated API planning memo를 쌓지 않는다.

package/sdd/02_plan/06_iac/README.md

@@ -0,0 +1,11 @@
+# IaC Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 이 폴더는 배포, 런타임, 데이터베이스 운영 계획을 durable 문서로 유지한다.
+- dated deploy plan은 남기지 않고, 현재 유효한 delivery/runtime 계획만 갱신한다.
+
+## Common Rule
+
+- 다른 `02_plan` 폴더와 동일하게 `README.md + durable 문서`만 유지한다.
+- 실제 계획은 대상 문서를 직접 갱신하는 방식으로 관리하고, 날짜 기반 임시 plan 파일은 두지 않는다.
+- 개발계가 있는 대상은 `build -> main push -> DEV(개발계) 배포 -> DEV(개발계) 검수`를 delivery 기본 루틴으로 포함한다.

package/sdd/02_plan/06_iac/dev_runtime_delivery.md

@@ -0,0 +1,36 @@
+# dev runtime delivery
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - template repo의 DEV runtime/delivery baseline
+  - screen spec capture, frontend build, backend/root compose runtime 확인 기준
+- Out of scope:
+  - 특정 서비스의 release timeline
+
+## Acceptance Criteria
+
+- [x] DEV 검수 시 visible surface와 current build artifact 확인 기준을 명시한다.
+- [x] runtime bootstrap과 delivery path는 current structure만 설명한다.
+- [x] delivery plan도 final-only 문서로 유지한다.
+
+## Execution Checklist
+
+- [x] current delivery path를 정리한다.
+- [x] build artifact와 runtime health 확인 기준을 정리한다.
+- [x] dated deploy memo를 제거하고 durable 기준으로 대체한다.
+
+## Current Notes
+
+- template repo는 service별 frontend build와 backend test/boot path를 current runtime baseline으로 둔다.
+- screen spec capture/PDF generation도 current toolchain path를 기준으로 유지한다.
+- visible build artifact 확인과 targeted test/build 조합을 delivery 검수 기본으로 사용한다.
+
+## Validation
+
+- current references:
+  - `sdd/03_build/06_iac/dev_runtime_delivery.md`
+  - `sdd/04_verify/06_iac/dev_runtime_delivery.md`

package/sdd/02_plan/06_iac/template_runtime_delivery.md

@@ -0,0 +1,50 @@
+# template runtime delivery
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - root compose dev-focused runtime baseline
+  - dedicated host compose overlay positioning
+  - provider-first Terraform baseline
+  - workflow와 runtime 환경의 현재 연결 규칙
+- Out of scope:
+  - dated deploy memo
+  - service별 release timeline
+
+## Acceptance Criteria
+
+- [x] root `compose.yml`이 canonical dev-focused template runtime baseline으로 문서화된다.
+- [x] `infra/compose/dev.yml`, `infra/compose/prod.yml`이 dedicated DEV(개발계)/PROD overlay로 문서화된다.
+- [x] provider-first Terraform split(`aws/data`, `aws/domain`, `openstack/server`)이 current runtime baseline으로 문서화된다.
+
+## Execution Checklist
+
+- [x] root compose/service graph positioning을 README와 IaC 문서에 반영한다.
+- [x] dedicated host overlay 역할을 current compose baseline과 구분해 정리한다.
+- [x] toolchain policy reference와 IAC current-state 문서를 같은 runtime split으로 맞춘다.
+
+## Current Notes
+
+- current template runtime baseline은 passv-style split을 따라 root `compose.yml`을 dev-focused graph entrypoint로 둔다.
+- root `compose.yml`은 4개 frontend surface, `server`, 기본 `postgres`, optional DB profile을 함께 기동한다.
+- `infra/compose/dev.yml`, `infra/compose/prod.yml`은 dedicated host나 분리된 runtime delivery가 필요할 때 쓰는 overlay/example set이다.
+- infrastructure baseline은 `infra/terraform/README.md`를 기준으로 유지한다.
+- current canonical delivery split은 `AWS edge/domain -> OpenStack backend compute -> AWS data plane`이다.
+- CI baseline은 `.github/workflows/ci.yml`, `.github/workflows/frontend-parity.yml`를 사용한다.
+
+## Validation
+
+- current references:
+  - `README.md`
+  - `infra/compose/README.md`
+  - `sdd/99_toolchain/README.md`
+  - `sdd/99_toolchain/02_policies/compose-runtime-baseline-policy.md`
+  - `infra/terraform/README.md`
+  - `infra/terraform/aws/data/README.md`
+  - `infra/terraform/aws/domain/README.md`
+  - `infra/terraform/openstack/server/README.md`
+  - `.github/workflows/ci.yml`
+  - `.github/workflows/frontend-parity.yml`

package/sdd/02_plan/07_integration/README.md

@@ -0,0 +1,5 @@
+# Integration Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 내부/외부 연동 계약 정렬 계획을 현재형 durable 문서로 유지한다.
+- dated integration memo를 쌓지 않는다.

package/sdd/02_plan/07_integration/frontend_live_integration.md

@@ -0,0 +1,31 @@
+# frontend live integration
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - platform/admin/mobile/landing과 backend domain contract 연결 기준
+  - typed API helper와 current live wiring baseline
+
+## Acceptance Criteria
+
+- [x] frontend service split과 backend domain owner 매핑이 current baseline으로 정리된다.
+- [x] integration 계획은 service별 live fetch wiring을 현재형으로 설명한다.
+
+## Current Notes
+
+- `platform`은 catalog/orders/support 중심 operator surface를 사용한다.
+- `admin`은 alerts, catalog, orders 관리 surface를 사용한다.
+- `mobile`은 fulfillment, shipping 중심 surface를 사용한다.
+- `landing`은 catalog/public read surface를 사용한다.
+- `client/mobile/src/lib/useSpeechRecognitionInput.ts`를 template shared utility로 유지해, 화면/입력 컴포저의 browser speech-to-text affordance를 공통 모듈로 시작할 수 있게 한다.
+
+## Validation
+
+- current references:
+  - `client/platform/src`
+  - `client/admin/src`
+  - `client/mobile/src`
+  - `client/landing/src`

package/sdd/02_plan/08_nonfunctional/README.md

@@ -0,0 +1,5 @@
+# Nonfunctional Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 성능, 가용성, 확장성, 관측성 같은 비기능 요구 정렬 계획을 현재형 durable 문서로 유지한다.
+- dated cleanup memo를 쌓지 않는다.

package/sdd/02_plan/08_nonfunctional/repository_hygiene.md

@@ -0,0 +1,26 @@
+# repository hygiene
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - cache artifact, generated garbage, repository hygiene baseline
+  - lint/build/test를 방해하지 않는 저장소 청결 기준
+
+## Acceptance Criteria
+
+- [x] `*.pyc`, `__pycache__`, build garbage는 committed artifact로 남지 않는다.
+- [x] SDD는 current-state 문서만 유지한다.
+
+## Current Notes
+
+- Python cache artifact와 empty cache directory는 저장소에 남기지 않는다.
+- SDD는 generated history log를 남기지 않고 current-state 문서만 유지한다.
+
+## Validation
+
+- current references:
+  - `.gitignore`
+  - `sdd/README.md`

package/sdd/02_plan/09_security/README.md

@@ -0,0 +1,5 @@
+# Security Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 인증, 인가, 비밀 관리, 감사 기준 정렬 계획을 현재형 durable 문서로 유지한다.
+- dated security memo를 쌓지 않는다.

package/sdd/02_plan/10_test/README.md

@@ -0,0 +1,11 @@
+# Test Planning
+
+- 이 폴더는 `sdd/02_plan` 아래에서 에이전트의 현재 개발 계획을 관리한다.
+- 이 폴더는 반복적으로 유지해야 하는 검증 전략과 테스트 계획을 durable 문서로 관리한다.
+- 날짜별 테스트 계획 메모는 두지 않고, 현재 유지해야 하는 전략과 matrix만 갱신한다.
+
+## Common Rule
+
+- 다른 `02_plan` 폴더와 동일하게 `README.md + durable 문서`만 유지한다.
+- 실제 계획은 검증 전략 문서를 직접 갱신하는 방식으로 관리하고, 날짜 기반 임시 plan 파일은 두지 않는다.
+- 검증 전략과 회귀 검수 범위 선택은 각각 durable 문서로 유지하고, direct target-only 검수로 축약하지 않는다.

package/sdd/02_plan/10_test/regression_verification.md

@@ -0,0 +1,39 @@
+# regression verification
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - direct target 외에 upstream, downstream, shared surface까지 포함한 회귀 검수 범위 선정
+  - shared route, shell, auth/session, component, contract, generated asset, builder output 변경 시 adjacent consumer 포함 규칙
+  - 자동화가 없는 회귀 surface의 manual verification / residual risk 기록 기준
+- Out of scope:
+  - 개별 날짜별 test run history 보관
+
+## Acceptance Criteria
+
+- [x] 회귀 검수는 direct target-only로 끝내지 않는다.
+- [x] selected regression surface는 `sdd/02_plan`, `sdd/03_build`, `sdd/04_verify`에 current-state로 이어진다.
+- [x] automation gap은 scope 축소가 아니라 residual risk로 기록한다.
+
+## Execution Checklist
+
+- [x] regression surface 분류 기준을 direct, upstream, downstream, shared로 정리한다.
+- [x] shared change에서 adjacent consumer 검수 rule을 명시한다.
+- [x] manual verification과 residual risk 기록 rule을 current workflow에 반영한다.
+
+## Current Notes
+
+- 기본 최소 검수 범위는 direct target이지만, completion 판단은 selected regression surface 전체 기준으로 한다.
+- shared route, shell, auth/session, component, contract, generated asset, builder output 변경은 인접 consumer와 공용 surface까지 회귀 범위를 넓힌다.
+- 전용 automation이 아직 없으면 build, parity harness, targeted test, manual walk-through를 조합하고 미구현 automation은 residual risk로 남긴다.
+
+## Validation
+
+- current references:
+  - `AGENTS.md`
+  - `.codex/skills/sdd/SKILL.md`
+  - `sdd/99_toolchain/01_automation/README.md`
+  - `sdd/04_verify/10_test/verification_harness.md`

package/sdd/02_plan/10_test/templates/README.md

@@ -0,0 +1,8 @@
+# Templates Test Plan
+
+현재 템플릿 세트의 기본 검증 계약을 둔다.
+
+- `pnpm -r build`
+- `pytest`
+- auth runtime smoke
+- compose config validation

package/sdd/02_plan/10_test/templates/ui_parity_platform_contract.template.yaml

@@ -0,0 +1,23 @@
+kind: ui-parity
+metadata:
+  service: templates
+  owner: replace-me
+  generated_by: sdd/99_toolchain/01_automation/ui-parity/cli/scaffold-contract.mjs
+spec:
+  target_base_url: http://127.0.0.1:4301
+  adapter_path: client/platform/scripts/ui-parity-platform-adapter.mjs
+screens:
+  - id: TMP_001
+    route: /
+    reference_image: sdd/04_verify/10_test/ui_parity/reference/TMP_001.png
+    max_diff_ratio: 0
+    allow_resize: false
+    pixelmatch_threshold: 0.1
+    include_aa: true
+    capture_full_page: false
+    viewport:
+      width: 1440
+      height: 1024
+    mask_rects: []
+    notes:
+      - Replace screen ids, routes, and reference assets for the cloned service.

package/sdd/02_plan/10_test/verification_strategy.md

@@ -0,0 +1,43 @@
+# verification strategy
+
+- Owner: Codex
+- Status: active
+
+## Scope
+
+- In scope:
+  - feature/screen 구현 시 기본 검증 전략
+  - backend/frontend/build/proof 확인 조합
+- Out of scope:
+  - 개별 test run timeline 보관
+
+## Acceptance Criteria
+
+- [x] feature 변경은 최소한 관련 integration 또는 targeted verification surface를 남긴다.
+- [x] screen 변경은 build + proof 또는 targeted verification을 기본으로 한다.
+- [x] SDD verify는 durable current-summary만 유지한다.
+- [x] 회귀 검수 범위는 direct, upstream, downstream, shared surface까지 retained current-state로 선택한다.
+
+## Execution Checklist
+
+- [x] backend, frontend, proof verification 조합을 current strategy로 정리한다.
+- [x] UI parity 같은 proof harness 경로를 current structure로 맞춘다.
+- [x] verification plan도 dated memo가 아니라 durable 문서로 유지한다.
+- [x] regression surface selection baseline을 별도 durable 문서로 유지한다.
+
+## Current Notes
+
+- backend는 `pytest` targeted suite, frontend는 build, proof는 ui parity harness와 Playwright exactness runner를 기본 전략으로 둔다.
+- screen local exactness의 canonical entrypoint는 `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite <suite-id> --base-url <url>`이다.
+- direct `npx playwright test ...` 호출은 디버깅 예외로만 쓰고, retained verification command는 toolchain wrapper 기준으로 남긴다.
+- screen spec/PDF generator와 parity harness는 current toolchain path를 기준으로 검증한다.
+- verify는 날짜별 memo 대신 현재 retained checks와 residual risk만 남긴다.
+- 회귀 검수는 `sdd/02_plan/10_test/regression_verification.md`를 기준으로 direct target과 upstream/downstream/shared surface를 함께 선택한다.
+- build, parity, targeted test는 selected regression surface를 채우는 수단이지 scope 자체를 대체하지 않는다.
+
+## Validation
+
+- current references:
+  - `sdd/04_verify/README.md`
+  - `sdd/04_verify/10_test/verification_harness.md`
+  - `sdd/02_plan/10_test/regression_verification.md`

package/sdd/02_plan/99_generated/from_planning/ui_parity/.gitkeep

@@ -0,0 +1 @@
+