agentic-dev 0.1.0 → 0.2.1

package/sdd/04_verify/01_feature/README.md

@@ -0,0 +1,5 @@
+# Feature Verification
+
+- 이 폴더는 feature 범주별 현재 retained verification 상태를 요약한다.
+- service와 domain을 각각 큰 범주로 묶어 관리한다.
+- 오래된 개별 test run 문서는 유지하지 않고, 현재 남겨둘 가치가 있는 검증 결과만 요약한다.

package/sdd/04_verify/01_feature/domain_verification.md

@@ -0,0 +1,14 @@
+# domain verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- feature spec은 current domain split을 기준으로 유지된다.
+- dated planning metadata는 제거되어 final-only 기준을 따른다.
+
+## Residual Risk
+
+- domain contract가 바뀌면 feature spec과 build summary를 함께 갱신해야 한다.

package/sdd/04_verify/01_feature/service_verification.md

@@ -0,0 +1,22 @@
+# service verification
+
+## Scope
+
+- platform, admin, mobile, landing 서비스 surface의 현재 retained verification을 요약한다.
+
+## Current Status
+
+- `platform`: pass
+- `admin`: pass
+- `mobile`: pass
+- `landing`: pass
+
+## Retained Checks
+
+- service별 frontend build가 current baseline 검증 surface다.
+- typed API contract와 backend domain contract 정합성은 domain verification을 상속한다.
+- screen surface 상세는 `04_verify/02_screen/` 기준으로 읽는다.
+
+## Residual Risk
+
+- 실제 서비스 repo에 적용할 때는 각 app별 targeted build와 proof를 다시 재실행해야 한다.

package/sdd/04_verify/02_screen/README.md

@@ -0,0 +1,6 @@
+# Screen Verification
+
+- 이 폴더는 screen별 현재 retained verification 상태를 유지한다.
+- service split을 따라 `04_verify/02_screen/<service>/` 아래에 둔다.
+- dated gate/test log를 쌓지 않고, current retained checks와 residual risk만 남긴다.
+- 새 verify section을 추가할 때는 `_screen_verify_template.md`를 기준으로 runtime tree, Playwright suite id, canonical runner command, artifact path를 함께 남긴다.

package/sdd/04_verify/02_screen/_screen_verify_template.md

@@ -0,0 +1,20 @@
+# Screen Verify Summary Template
+
+## Status
+
+- pass | fail | partial
+
+## Retained Checks
+
+- runtime tree:
+- canonical Playwright suite id:
+- canonical runner command: `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite <suite-id> --base-url <url>`
+- retained screenshot/json artifacts:
+- builder/design guide/asset checks:
+- live-vs-local split:
+
+## Residual Risk
+
+- exactness gap:
+- live verification gap:
+- shared surface regression gap:

package/sdd/04_verify/02_screen/admin/README.md

@@ -0,0 +1,4 @@
+# Admin Screen Verification
+
+- current source: `sdd/01_planning/02_screen/admin_screen_spec.pdf`
+- 이 폴더는 admin screen별 retained verification summary를 유지한다.

package/sdd/04_verify/02_screen/landing/README.md

@@ -0,0 +1,4 @@
+# Landing Screen Verification
+
+- current source: `sdd/01_planning/02_screen/landing_screen_spec.pdf`
+- 이 폴더는 landing screen별 retained verification summary를 유지한다.

package/sdd/04_verify/02_screen/mobile/README.md

@@ -0,0 +1,4 @@
+# Mobile Screen Verification
+
+- current source: `sdd/01_planning/02_screen/mobile_screen_spec.pdf`
+- 이 폴더는 mobile screen별 retained verification summary를 유지한다.

package/sdd/04_verify/02_screen/platform/README.md

@@ -0,0 +1,4 @@
+# Platform Screen Verification
+
+- current source: `sdd/01_planning/02_screen/platform_screen_spec.pdf`
+- 이 폴더는 platform screen별 retained verification summary를 유지한다.

package/sdd/04_verify/03_architecture/README.md

@@ -0,0 +1,10 @@
+# Architecture Verification
+
+- 구조/거버넌스 관련 retained verification summary를 유지한다.
+- architecture planning 구조와 저장소 거버넌스가 현재 문서 체계에 맞게 유지되는지 검증한다.
+
+## Current Documents
+
+- [architecture_document_governance.md](architecture_document_governance.md)
+- [repository_governance.md](repository_governance.md)
+- [toolchain_governance.md](toolchain_governance.md)

package/sdd/04_verify/03_architecture/architecture_document_governance.md

@@ -0,0 +1,15 @@
+# architecture document governance verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- `sdd/01_planning/03_architecture/README.md`, `INDEX.md`가 공통/특화 구조를 함께 설명한다.
+- `sdd/01_planning/03_architecture/frontend`, `backend`, `infra`, `tech-research` README가 각 architecture 범위를 분리해 설명한다.
+- `sdd/01_planning/04_data/README.md`가 data modeling 경계를 architecture 밖으로 유지한다.
+
+## Residual Risk
+
+- 아직 `frontend/`, `backend/`, `infra`, `tech-research` 하위의 상세 architecture 문서는 skeleton README 수준이므로, 실제 구조 논점이 늘어나면 개별 문서를 계속 채워야 한다.

package/sdd/04_verify/03_architecture/build_ast_runtime_tree_governance.md

@@ -0,0 +1,28 @@
+# build ast runtime tree governance
+
+## Verification Target
+
+- `templates` AST-style build/runtime-tree governance
+
+## Gate Commands
+
+- `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'`
+
+## Latest Known Status
+
+- status: pass
+- primary command: `python3 scripts/dev/audit_sdd_build_ast.py --write .agent/sdd-build-ast-audit.json`
+- machine-readable result: `.agent/sdd-build-ast-audit.json`
+- scores: `ast_similarity=10`, `implementation_traceability=10`, `human_agent_readability=10`
+- finding summary: residual finding 없음, `all_ten=true`
+- supporting check: `rg -n "Ralph|iteration|Current Build Note|2026-" sdd/03_build -g '*.md'` returned no matches
+- supporting infra checks:
+  - `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`
+
+## Residual Risk
+
+- runtime entrypoint나 shell structure가 바뀌면 service summary와 audit needle을 함께 갱신하지 않으면 AST 점수가 어긋난다.
+- downstream repo가 template를 복제한 뒤 role agent나 skill alias만 가져가고 policy를 생략하면 build current-state 규칙이 약해질 수 있다.

package/sdd/04_verify/03_architecture/repository_governance.md

@@ -0,0 +1,16 @@
+# repository governance verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- `AGENTS.md`와 `sdd/README.md`가 final-only SDD 규칙을 설명한다.
+- build/verify/operate가 history-style section 없이 current-state 문서로 정리된다.
+- planning data modeling root가 `04_data`로 유지된다.
+- screen build/verify summary가 service split 아래에 정리된다.
+
+## Residual Risk
+
+- toolchain이나 skill이 legacy path를 다시 참조하면 구조와 충돌한다.

package/sdd/04_verify/03_architecture/toolchain_governance.md

@@ -0,0 +1,58 @@
+# toolchain governance verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --list`
+  - pass
+  - canonical Playwright suite registry entrypoint가 현재 toolchain에 추가됐다
+- `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite example --base-url http://127.0.0.1:3000 --dry-run`
+  - not run
+  - template repo에는 아직 등록된 suite가 없어 dry-run 대상 suite는 downstream repo가 채운 뒤 검증해야 한다
+- `python3 -m py_compile sdd/99_toolchain/01_automation/playwright_exactness_manifest.py sdd/99_toolchain/01_automation/run_playwright_exactness.py`
+  - pass
+  - Playwright exactness wrapper/manifest Python syntax가 유효하다
+- `git check-ignore -v .claude/settings.local.json .agent/sdd-build-ast-audit.json .agent/runs/README.md client/admin/dist server/.venv`
+  - pass
+  - durable scaffold/config는 unignore 대상으로 승격했고, generated artifact는 계속 ignore 대상으로 남겼다
+- `rg -n "trigger하는가|정본과 우선순위|문서 거버넌스와 산출물 원칙|Schema parity와 persistence 작업은 왜 별도 축인가|Regression verification은 왜 별도 구조를 갖는가|완료 기준을 어떻게 봐야 하는가" SDD_SKILL.md`
+  - pass
+  - 루트 `SDD_SKILL.md`가 `sdd` 스킬의 trigger, governance, schema parity, regression, completion gate까지 설명하도록 확장됐다
+- `rg -n "Toolchain을 어떻게 봐야 하는가|Visual Fidelity를 맞추는 구조|Exactness를 맞추는 구조|기능 정합성을 맞추는 구조" SDD_SKILL.md`
+  - pass
+  - 루트 `SDD_SKILL.md`가 toolchain, visual fidelity, exactness, 기능 정합성 구조를 별도 섹션으로 설명한다
+- `rg -n "folder structure|Feature 플로우|Screen 플로우|Architecture 플로우|Operate / Rollout 플로우" SDD_SKILL.md`
+  - pass
+  - 루트 `SDD_SKILL.md`가 workflow와 `sdd/` 구조, flow별 설명을 포함하도록 확장됐다
+- `rg -n "sdd-dev/|screen_design_guide_builder\\.py|explicitly in scope|Do not infer rollout scope" .codex/skills/sdd .claude/skills/sdd*`
+  - pass
+  - stale `.codex/skills/sdd-dev/` reference가 제거됐고, rollout gate는 explicit deployment scope 기준으로 정리됐으며, 없는 design guide builder file path 고정도 제거됐다
+- `test -f SDD_SKILL.md`
+  - pass
+  - 프로젝트 루트에 `sdd` skill 요약 entrypoint가 추가됐다
+- `rg -n "brand_assets|brand asset|Brand Asset|브랜드 자산|브랜드 에셋|build_mobile_brand_assets|mobile_brand_asset_manifest|BRAND_ASSET_RECIPES" sdd/01_planning/02_screen sdd/02_plan/03_architecture sdd/03_build/03_architecture sdd/99_toolchain .codex/skills/sdd .claude/skills/sdd`
+  - pass
+  - template repo planning/toolchain/local skill에서 legacy brand asset naming이 제거됐다
+- `git diff --check -- SDD_SKILL.md sdd/02_plan/03_architecture/toolchain_governance.md sdd/03_build/03_architecture/toolchain_governance.md sdd/04_verify/03_architecture/toolchain_governance.md .codex/skills/sdd/SKILL.md .claude/skills/sdd-dev/SKILL.md`
+  - pass
+- `sdd/99_toolchain/02_policies/regression-verification-policy.md`가 회귀 검수 규칙의 정본으로 추가됐다.
+- `AGENTS.md`, `.codex/skills/sdd/SKILL.md`, `sdd/99_toolchain/01_automation/README.md`가 direct-only verification 금지와 selected regression surface 기록 규칙을 함께 설명한다.
+- `sdd/01_planning/02_screen/assets/README.md`, `.codex/skills/sdd/SKILL.md`, `.claude/skills/sdd/SKILL.md`, `sdd/99_toolchain/01_automation/README.md`가 reusable asset planning root를 `assets/`로 일치시킨다.
+- `sdd/02_plan/10_test/regression_verification.md`, `sdd/03_build/10_test/regression_verification.md`, `sdd/04_verify/10_test/regression_verification.md`가 current-state trail을 이룬다.
+- `.claude/skills/sdd-dev/SKILL.md`가 현재 Codex canonical path와 section map path를 직접 가리킨다.
+- `.codex/skills/sdd/SKILL.md`는 rollout scope를 `sdd/05_operate` 존재 여부가 아니라 explicit deployment scope 또는 completion policy로 해석한다.
+- `.codex/skills/sdd/SKILL.md`, `sdd/99_toolchain/01_automation/README.md`, `sdd/99_toolchain/02_policies/regression-verification-policy.md`가 Playwright exactness wrapper/manifest를 canonical local gate로 함께 설명한다.
+- `SDD_SKILL.md`는 루트에서 빠르게 찾는 설명 entrypoint이고, workflow/structure 설명과 canonical source 분리를 함께 명시한다.
+- `SDD_SKILL.md`는 visual fidelity, exactness, 기능 정합성을 각각 분리해 설명하고, toolchain과 verify artifact가 이 셋을 어떻게 연결하는지 명시한다.
+- `SDD_SKILL.md`는 이제 `sdd` 스킬 전체를 이해하기 위한 루트 해설서 역할을 하며, skill 원문 해석 전에 필요한 mental model을 제공한다.
+- durable local scaffold와 generated artifact를 구분하는 ignore policy가 `.gitignore`에 반영됐다.
+
+## Residual Risk
+
+- regression surface selector 자동화가 아직 없어서 initial scope selection은 문서 기준/manual 판단에 의존한다.
+- template repo에는 concrete Playwright suite source가 아직 없으므로, downstream repo가 harness root와 suite registry를 채우기 전까지는 runner가 empty registry 상태로 유지된다.
+- rollout completion bar 해석은 여전히 저장소 정책과 사용자 요청의 명시성에 의존하므로, 배포가 애매한 요청은 시작 시 scope를 분명히 해야 한다.
+- `.claude/settings.local.json`은 local override 이름을 유지하므로 downstream에서 환경별 차이가 생기면 별도 override policy 정리가 필요할 수 있다.

package/sdd/04_verify/06_iac/README.md

@@ -0,0 +1,3 @@
+# IaC Verification
+
+- delivery/runtime 관련 retained verification summary를 유지한다.

package/sdd/04_verify/06_iac/dev_runtime_delivery.md

@@ -0,0 +1,10 @@
+# dev runtime delivery verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- current delivery baseline은 frontend build, backend test, screen capture/PDF generation 조합으로 유지된다.
+- proof/output path는 current `sdd/04_verify/10_test/ui_parity/` 구조를 따른다.

package/sdd/04_verify/06_iac/template_runtime_delivery.md

@@ -0,0 +1,42 @@
+# template runtime delivery verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- `rg -n "canonical dev-focused|dedicated host|AWS edge/domain|compose.yml" README.md infra/compose/README.md sdd/02_plan/06_iac/template_runtime_delivery.md sdd/03_build/06_iac/template_runtime_delivery.md sdd/99_toolchain/README.md sdd/99_toolchain/02_policies/compose-runtime-baseline-policy.md`
+  - pass
+  - root compose baseline과 dedicated overlay positioning이 target docs에서 같은 표현으로 유지된다.
+- `rg -n '/home/sh/Documents/Github/templates/' . -g '*.md'`
+  - pass
+  - canonical template docs에 절대 filesystem 링크가 남아 있지 않다.
+- `docker compose --env-file .env.example -f compose.yml config`
+  - pass
+- `docker compose --env-file infra/compose/.env.dev.example -f infra/compose/dev.yml config`
+  - pass
+- `docker compose --env-file infra/compose/.env.prod.example -f infra/compose/prod.yml config`
+  - pass
+- `docker compose --env-file .env.example -f compose.yml build server client-landing client-platform client-mobile client-admin`
+  - pass
+- `SERVER_HTTP_PORT=38080 CLIENT_LANDING_PORT=33000 CLIENT_PLATFORM_PORT=33001 CLIENT_MOBILE_PORT=33002 CLIENT_ADMIN_PORT=34000 docker compose --env-file .env.example -f compose.yml up -d postgres server client-landing client-platform client-mobile client-admin`
+  - pass
+  - root compose baseline이 high-port override에서도 `postgres + server + 4 clients`를 모두 기동했다.
+- `curl -sf http://127.0.0.1:38080/health`
+  - pass
+  - backend health 응답은 `{"status":"ok"}`였다.
+- `SERVER_HTTP_PORT=38080 CLIENT_LANDING_PORT=33000 CLIENT_PLATFORM_PORT=33001 CLIENT_MOBILE_PORT=33002 CLIENT_ADMIN_PORT=34000 docker compose --env-file .env.example -f compose.yml down`
+  - pass
+- `terraform -chdir=infra/terraform/aws/data init -backend=false && terraform -chdir=infra/terraform/aws/data validate`
+  - pass
+- `terraform -chdir=infra/terraform/aws/domain init -backend=false && terraform -chdir=infra/terraform/aws/domain validate`
+  - pass
+- `terraform -chdir=infra/terraform/openstack/server init -backend=false && terraform -chdir=infra/terraform/openstack/server validate`
+  - pass
+- `git diff --check -- README.md infra/compose/README.md sdd/02_plan/06_iac/template_runtime_delivery.md sdd/03_build/06_iac/template_runtime_delivery.md sdd/04_verify/06_iac/template_runtime_delivery.md sdd/99_toolchain/README.md sdd/99_toolchain/02_policies/compose-runtime-baseline-policy.md sdd/99_toolchain/02_policies/convention-storage-policy.md`
+  - pass
+
+## Residual Risk
+
+- root compose service graph나 remote overlay 역할이 다시 바뀌면 README, IaC summary, toolchain policy를 같은 턴에 다시 맞춰야 한다.

package/sdd/04_verify/07_integration/README.md

@@ -0,0 +1,3 @@
+# Integration Verification
+
+- integration retained verification summary를 유지한다.

package/sdd/04_verify/07_integration/frontend_live_integration.md

@@ -0,0 +1,16 @@
+# frontend live integration verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- service app split과 backend domain owner 매핑이 current integration baseline으로 유지된다.
+- parity tooling reference path는 stable current path를 사용한다.
+- `client/mobile/src/lib/useSpeechRecognitionInput.ts` shared utility가 template mobile build/typecheck에 포함된다.
+
+## Residual Risk
+
+- app별 adapter/contract path가 바뀌면 parity tooling 경로도 함께 갱신해야 한다.
+- browser speech recognition support와 permission UX는 template utility만으로 보장되지 않으므로, 실제 consumer screen에서 별도 verify가 필요하다.

package/sdd/04_verify/08_nonfunctional/README.md

@@ -0,0 +1,3 @@
+# Nonfunctional Verification
+
+- repository hygiene 관련 retained verification summary를 유지한다.

package/sdd/04_verify/08_nonfunctional/repository_hygiene.md

@@ -0,0 +1,14 @@
+# repository hygiene verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- dated SDD log section은 제거되고 final-only section만 유지된다.
+- planning spec의 작성일 metadata는 제거된다.
+
+## Residual Risk
+
+- generator가 날짜 메타데이터를 다시 쓰면 planning current-state rule과 충돌한다.

package/sdd/04_verify/10_test/README.md

@@ -0,0 +1,9 @@
+# Test Verification
+
+- 반복 사용하는 검증 harness summary를 유지한다.
+- regression verification summary도 같은 section에서 유지한다.
+
+## Current Documents
+
+- [verification_harness.md](verification_harness.md)
+- [regression_verification.md](regression_verification.md)

package/sdd/04_verify/10_test/regression_verification.md

@@ -0,0 +1,16 @@
+# regression verification
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- `sdd/02_plan/10_test/regression_verification.md`가 current regression scope baseline으로 추가됐다.
+- `AGENTS.md`, `.codex/skills/sdd/SKILL.md`, `sdd/99_toolchain/01_automation/README.md`가 direct-only verification 금지와 selected regression surface 기록 규칙을 함께 유지한다.
+- `sdd/03_build/10_test/regression_verification.md`가 template workflow 반영 상태를 current-state로 설명한다.
+- screen exact automation gate가 Playwright인 경우 suite id, toolchain runner command, artifact path를 retained check에 함께 남긴다.
+
+## Residual Risk
+
+- regression scope selection은 아직 자동 selector가 없어서 문서 규칙과 reviewer 판단에 의존한다.

package/sdd/04_verify/10_test/ui_parity/README.md

@@ -0,0 +1,4 @@
+# UI Parity Artifacts
+
+- UI parity reference asset과 proof output의 current durable 위치다.
+- latest-named artifact를 같은 경로에서 덮어써 유지한다.

package/sdd/04_verify/10_test/verification_harness.md

@@ -0,0 +1,17 @@
+# verification harness
+
+## Status
+
+- pass
+
+## Retained Checks
+
+- verify harness는 stable current artifact path를 사용한다.
+- UI parity reference asset과 proof output은 current durable location을 사용한다.
+- screen local exactness는 `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite <suite-id> --base-url <url>`를 canonical harness entrypoint로 사용한다.
+- regression verification scope는 별도 durable baseline에서 선택하고, harness는 selected surface 중 automation 가능한 slice를 담당한다.
+
+## Residual Risk
+
+- harness CLI default path가 legacy verify folder를 다시 가리키면 drift가 생긴다.
+- regression surface selector 자동화가 없어 shared-impact 판정은 문서와 reviewer 판단에 의존한다.

package/sdd/04_verify/README.md

@@ -0,0 +1,22 @@
+# Verify Governance
+
+## Purpose
+
+- `sdd/04_verify/`는 현재 구현 상태에 대한 retained verification을 durable 문서로 유지하는 루트다.
+- 날짜별 gate/test log를 쌓지 않고, 현재 기준의 pass/fail 상태와 residual risk만 남긴다.
+
+## Canonical Rule
+
+- `04_verify`는 `02_plan`, `03_build`와 같은 section 축을 따른다.
+- feature, screen, architecture, IAC, test surface별 verification summary를 같은 파일에서 갱신한다.
+- history성 gate/test 로그는 `04_verify`에 두지 않는다.
+
+## Sections
+
+- `01_feature/`: feature 범주별 retained verification summary
+- `02_screen/`: screen별 retained verification summary
+- `03_architecture/`: 거버넌스/구조 관련 verification summary
+- `06_iac/`: delivery/runtime verification summary
+- `07_integration/`: integration verification summary
+- `08_nonfunctional/`: nonfunctional verification summary
+- `10_test/`: 반복 사용하는 검증 harness summary

package/sdd/05_operate/01_runbooks/.gitkeep

@@ -0,0 +1 @@
+

package/sdd/05_operate/01_runbooks/README.md

@@ -0,0 +1,4 @@
+# Runbooks
+
+- 이 폴더는 현재 유효한 운영 절차를 durable runbook으로 유지한다.
+- 날짜별 운영 이력은 두지 않고, 지금 따라야 하는 절차만 갱신한다.

package/sdd/05_operate/02_delivery_status/README.md

@@ -0,0 +1,4 @@
+# Delivery Status
+
+- 이 폴더는 현재 live deployment와 monitoring baseline을 durable 문서로 유지한다.
+- service surface별 current status만 남기고, 과거 release log는 보관하지 않는다.

package/sdd/05_operate/02_delivery_status/service_status.md

@@ -0,0 +1,16 @@
+# service status
+
+## Current Live State
+
+- template repo는 root compose/developer baseline 기준의 current buildable state를 유지한다.
+- production release timeline은 SDD에 누적하지 않는다.
+
+## Monitoring Baseline
+
+- backend `pytest`
+- frontend app build
+- parity harness current output path 확인
+
+## Residual Risk
+
+- 실제 서비스 레포에 이식할 때는 각 서비스의 runtime/edge 기준으로 다시 구체화해야 한다.

package/sdd/05_operate/README.md

@@ -0,0 +1,12 @@
+# Operate Governance
+
+## Purpose
+
+- `sdd/05_operate/`는 현재 배포 상태, 모니터링 기준, 운영 절차를 durable 문서로 유지하는 루트다.
+- raw 운영 로그나 히스토리성 release note는 남기지 않는다.
+
+## Canonical Rule
+
+- runbook은 절차를 설명하는 durable 문서로 유지한다.
+- delivery status는 현재 live state와 확인 기준만 남기고 덮어쓴다.
+- raw runtime log와 상세 incident timeline은 backend/application logging system의 역할이다.

package/sdd/99_toolchain/01_automation/.gitkeep

@@ -0,0 +1 @@
+

package/sdd/99_toolchain/01_automation/README.md

@@ -0,0 +1,76 @@
+# Automation Toolchain
+
+`01_automation`은 screen spec 생성, capture asset 수집, parity harness 실행, Playwright exactness orchestration, recipe 기반 정적 자산 생성을 위한 자동화 자산을 둔다.
+
+## Scope
+
+- screen spec capture script
+- screen spec PDF generator
+- parity harness
+- Playwright exactness runner / suite registry
+- generator manifest
+- asset recipe builder
+- regression verification scope selection rule
+
+## Screen Spec Rule
+
+- feature code: `DOMAIN-FNNN`
+- screen code: `SERVICE-SNNN`
+- desktop capture 기준 visible area: `1710x951`
+- 기본 capture viewport: `1690x940`
+- capture mode: `viewport-first`
+
+## Canonical Tools
+
+- [screen_spec_manifest.py](./screen_spec_manifest.py)
+- [capture_screen_assets.mjs](./capture_screen_assets.mjs)
+- [build_screen_spec_pdf.py](./build_screen_spec_pdf.py)
+- [spec_asset_builder.py](./spec_asset_builder.py)
+- [build_asset_recipes.py](./build_asset_recipes.py)
+- [playwright_exactness_manifest.py](./playwright_exactness_manifest.py)
+- [run_playwright_exactness.py](./run_playwright_exactness.py)
+
+## Storage Rule
+
+- generated runtime asset은 각 구현 repo 경로에 둔다.
+- planning 산출물은 `sdd/01_planning/02_screen/assets/` 아래에 둔다.
+- generator와 manifest는 `sdd/99_toolchain/01_automation/`에 둔다.
+- Playwright harness source는 repo 상황에 따라 `research/agent-browser/pocs/playwright-dev-e2e/` 같은 runtime location에 둘 수 있지만, canonical invocation과 suite registry는 `sdd/99_toolchain/01_automation/`이 소유한다.
+
+## Regression Verification Rule
+
+- toolchain은 builder/harness를 제공하더라도 direct target만 확인하고 종료하는 흐름을 허용하지 않는다.
+- `sdd` 작업은 `sdd/02_plan/10_test/regression_verification.md`를 기준으로 direct, upstream, downstream, shared surface를 선택한다.
+- parity harness나 build check는 회귀 검수의 일부일 뿐이고, 실제 완료 기준은 선택한 regression surface 전체에 대한 retained evidence다.
+- Playwright exactness suite가 있는 surface는 `run_playwright_exactness.py`를 canonical local gate로 사용한다.
+- shared route, shell, auth/session, shared component, API/data contract, generated asset, builder output 변경은 adjacent consumer까지 검수 범위를 넓힌다.
+- 아직 자동화가 없는 회귀 surface는 command/manual verification으로 메우고, automation gap은 `sdd/03_build`, `sdd/04_verify`에 residual risk로 남긴다.
+- Browser Use나 수동 시각 점검은 Playwright exactness gate를 대체하지 않고 보강/진단 용도로만 사용한다.
+
+## Asset Recipe Rule
+
+- 정적 디자인 자산 추출의 canonical tool name은 `스펙에셋빌더`다.
+- generic 실행 파일은 `[spec_asset_builder.py](./spec_asset_builder.py)`다.
+- `[build_asset_recipes.py](./build_asset_recipes.py)`는 기존 호출 호환용 wrapper다.
+- 화면명세서에 있는 icon, logo, illustration, 기타 재사용 가능한 static asset은 먼저 `스펙에셋빌더`로 추출한 뒤 구현 코드에서 사용한다.
+- reusable asset planning 문서는 `sdd/01_planning/02_screen/assets/` 아래에 둔다.
+- 프로젝트별 규칙은 Python manifest에서 `ASSET_RECIPES` 리스트로 선언한다.
+- 각 recipe는 `source`, `crop_box`, `transparent_white_threshold`, `trim`, `output`, `children`을 조합해 재사용 가능한 SVG/PNG 자산을 생성한다.
+- `--verify-exact`를 사용하면 generated output이 source crop과 픽셀 단위로 동일한지 검증한다.
+- builder로 표현 가능한 자산을 수동 redraw나 screenshot crop으로 대체하지 않는다.
+- 수동 예외가 필요하면 plan/build/verify 문서에 source, 예외 사유, 최종 자산 경로를 함께 남긴다.
+- 예시 manifest는 [`../03_templates/asset_recipe_manifest.example.py`](../03_templates/asset_recipe_manifest.example.py)에 둔다.
+- 예시 generated output은 [`../03_templates/generated_assets/README.md`](../03_templates/generated_assets/README.md) 경로를 사용한다.
+
+## Playwright Exactness Rule
+
+- Playwright exactness의 canonical registry는 [playwright_exactness_manifest.py](./playwright_exactness_manifest.py)다.
+- canonical runner는 [run_playwright_exactness.py](./run_playwright_exactness.py)다.
+- downstream repo는 suite source를 runtime location에 둘 수 있지만, retained command는 wrapper 기준으로 남긴다.
+- suite id, spec file, target screen batch, artifact path는 durable current-state로 관리한다.
+- screen 작업의 기본 local exactness gate는 다음 순서를 따른다.
+  - design guide / asset / screen spec baseline 확인
+  - `python3 sdd/99_toolchain/01_automation/run_playwright_exactness.py --suite <suite-id> --base-url <url>`
+  - 필요하면 `--api-base-url`, `--browser`, `--grep`를 추가한다.
+  - 실행 결과와 artifact path를 `sdd/04_verify` current summary에 기록한다.
+- 시작점 예시는 [`../03_templates/playwright_exactness_manifest.example.py`](../03_templates/playwright_exactness_manifest.example.py)를 따른다.