agentic-dev 0.1.0 → 0.2.1

package/sdd/99_toolchain/01_automation/screen_spec_manifest.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+SCREEN_DIR = ROOT / "sdd/01_planning/02_screen"
+ASSET_DIR = ROOT / "sdd/99_toolchain/01_automation/assets"
+DESKTOP_CAPTURE_POLICY = {
+    "reference_visible_area": "1710x951",
+    "default_viewport": "1690x940",
+    "capture_mode": "viewport-first",
+}
+
+
+def screen(
+    *,
+    code: str,
+    name: str,
+    route: str,
+    access: str,
+    features: list[str],
+    asset: str,
+    requires_auth: bool,
+    callouts: list[tuple[tuple[float, float], str, str]],
+    crop_box: tuple[int, int, int, int] | None = None,
+    segments: list[dict] | None = None,
+) -> dict:
+    item = {
+        "code": code,
+        "name": name,
+        "route": route,
+        "access": access,
+        "features": features,
+        "asset": asset,
+        "requires_auth": requires_auth,
+        "callouts": callouts,
+    }
+    if crop_box:
+        item["crop_box"] = crop_box
+    if segments:
+        item["segments"] = segments
+    return item
+
+
+SCREEN_MANIFESTS = {
+    "platform": {
+        "title": "Templates Platform Screen Spec",
+        "service_label": "platform",
+        "output": str(SCREEN_DIR / "platform_screen_spec.pdf"),
+        "asset_dir": str(ASSET_DIR / "platform_screen_capture"),
+        "base_url": "http://127.0.0.1:3001",
+        "api_base": "http://127.0.0.1:8000/api/v1",
+        "storage_key": "platform.auth.token",
+        "capture_policy": DESKTOP_CAPTURE_POLICY,
+        "trim_background": False,
+        "cover_note": "첫 페이지는 platform 화면코드 인덱스다. 이후 페이지는 좌측 화면 캡처와 우측 번호형 기능 테이블을 함께 제공한다.",
+        "source_refs": [
+            {"label": "implementation", "path": "client/platform/src/app/App.tsx"},
+            {"label": "implementation", "path": "client/platform/src/pages"},
+            {"label": "capture assets", "path": "sdd/99_toolchain/01_automation/assets/platform_screen_capture"},
+        ],
+        "screens": [
+            screen(
+                code="PLT-S001",
+                name="Platform Login",
+                route="/login",
+                access="public",
+                features=["AUT-F001", "AUT-F002"],
+                asset="login.png",
+                requires_auth=False,
+                callouts=[
+                    ((0.25, 0.31), "서비스 소개 카피", "실제 API 인증 흐름과 로그인 이후 앱 셸 진입 방식을 좌측 설명 영역에서 안내한다."),
+                    ((0.78, 0.21), "Sign in 헤더", "플랫폼 로그인 목적과 예시 계정 프리셋 상태를 보여준다."),
+                    ((0.78, 0.38), "자격 증명 입력", "이메일과 비밀번호를 입력하고 오류 상태를 같은 카드 안에서 확인한다."),
+                    ((0.78, 0.48), "Continue CTA", "인증 성공 시 저장된 토큰으로 `auth/me`를 다시 호출한 뒤 보호 라우트로 이동한다."),
+                ],
+            ),
+            screen(
+                code="PLT-S002",
+                name="Platform Dashboard",
+                route="/",
+                access="protected",
+                features=["AUT-F002", "ORD-F001"],
+                asset="dashboard.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.17, 0.09), "상단 앱 셸", "브랜드, Overview/Orders 전환, 검색, 알림, 사용자 액션을 한 줄 헤더로 제공한다."),
+                    ((0.26, 0.25), "운영 통계 카드", "주문 overview 핵심 지표와 로딩 또는 오류 상태를 상단 카드 묶음으로 보여준다."),
+                    ((0.34, 0.60), "Recent activity 표", "최근 주문 이벤트를 주문 ID, 일자, customer, 상태 기준으로 읽는 메인 데이터 테이블이다."),
+                    ((0.83, 0.55), "Selected detail 패널", "선택 주문의 product, customer, status, amount를 보조 패널에서 확인한다."),
+                ],
+            ),
+            screen(
+                code="PLT-S003",
+                name="Platform Orders",
+                route="/orders",
+                access="protected",
+                features=["AUT-F002", "ORD-F002"],
+                asset="orders.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.17, 0.09), "상단 앱 셸", "Overview와 Orders 간 전환, 검색, 알림, 로그아웃 등 공통 워크스페이스 셸을 유지한다."),
+                    ((0.36, 0.25), "검색/필터 바", "Search orders 입력값으로 product, customer, 상태, 주문 ID를 클라이언트 필터링한다."),
+                    ((0.78, 0.25), "액션 버튼", "Reset으로 필터를 초기화하고 New order CTA로 신규 흐름 진입점을 노출한다."),
+                    ((0.44, 0.61), "주문 목록 테이블", "주문 ID, product, customer, 상태를 기준으로 현재 결과 집합을 표 형태로 보여준다."),
+                ],
+            ),
+        ],
+    },
+    "admin": {
+        "title": "Templates Admin Screen Spec",
+        "service_label": "admin",
+        "output": str(SCREEN_DIR / "admin_screen_spec.pdf"),
+        "asset_dir": str(ASSET_DIR / "admin_screen_capture"),
+        "base_url": "http://127.0.0.1:4000",
+        "api_base": "http://127.0.0.1:8000/api/v1",
+        "storage_key": "admin.auth.token",
+        "capture_policy": DESKTOP_CAPTURE_POLICY,
+        "trim_background": False,
+        "cover_note": "첫 페이지는 admin 화면코드 인덱스다. 이후 페이지는 좌측 화면 캡처와 우측 번호형 기능 테이블을 함께 제공한다.",
+        "source_refs": [
+            {"label": "implementation", "path": "client/admin/src/app/App.tsx"},
+            {"label": "implementation", "path": "client/admin/src/pages"},
+            {"label": "capture assets", "path": "sdd/99_toolchain/01_automation/assets/admin_screen_capture"},
+        ],
+        "screens": [
+            screen(
+                code="ADM-S001",
+                name="Admin Login",
+                route="/login",
+                access="public",
+                features=["AUT-F001", "AUT-F002"],
+                asset="login.png",
+                requires_auth=False,
+                callouts=[
+                    ((0.24, 0.34), "운영 콘솔 소개 영역", "좌측 다크 패널에서 Admin console 컨텍스트와 실로그인 인증 흐름을 설명한다."),
+                    ((0.79, 0.18), "Restricted access 헤더", "관리자 접근 제어 맥락과 Sign in 제목을 우측 카드 상단에 배치한다."),
+                    ((0.79, 0.36), "자격 증명 입력", "이메일, 비밀번호, 오류 메시지를 한 폼 안에서 처리한다."),
+                    ((0.79, 0.48), "Open admin console CTA", "성공 시 관리자 토큰 저장 후 운영 셸로 진입한다."),
+                ],
+            ),
+            screen(
+                code="ADM-S002",
+                name="Admin Dashboard",
+                route="/",
+                access="protected",
+                features=["AUT-F002", "ORD-F003"],
+                asset="dashboard.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.08, 0.35), "좌측 운영 레일", "대시보드, 거래 관리, 고객지원으로 이동하는 관리자 전용 내비게이션 레일이다."),
+                    ((0.40, 0.18), "운영 요약 카드", "운영 핵심 수치를 카드 단위로 먼저 요약해 전체 상태를 빠르게 파악하게 한다."),
+                    ((0.37, 0.58), "거래 상태별 현황", "단계별 거래 건수를 리스트형 카드로 보여주는 메인 분석 영역이다."),
+                    ((0.79, 0.58), "운영 알림", "위험/일반 알림을 tone별 카드로 묶어 후속 조치를 안내한다."),
+                ],
+            ),
+            screen(
+                code="ADM-S003",
+                name="Admin Queue",
+                route="/queue",
+                access="protected",
+                features=["AUT-F002", "ORD-F003"],
+                asset="queue.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.08, 0.35), "좌측 운영 레일", "현재 거래 관리 섹션 위치를 강조하면서 다른 운영 화면으로 이동할 수 있다."),
+                    ((0.33, 0.24), "거래관리 헤더", "현재 큐 화면 제목과 전체 거래 건수를 요약해 상단에 고정한다."),
+                    ((0.44, 0.60), "거래 큐 테이블", "주문 ID, 상품, 고객 정보를 기준으로 관리자 작업 대상을 표로 노출한다."),
+                    ((0.82, 0.60), "상태/SLA 열", "운영 우선순위 판단에 필요한 상태와 SLA 정보를 같은 행에서 확인하게 한다."),
+                ],
+            ),
+            screen(
+                code="ADM-S004",
+                name="Admin Support",
+                route="/support",
+                access="protected",
+                features=["AUT-F002", "SUP-F001"],
+                asset="support.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.08, 0.35), "좌측 운영 레일", "고객지원 섹션과 다른 관리자 기능을 오가는 공통 운영 내비게이션이다."),
+                    ((0.37, 0.21), "FAQ 관리 헤더", "현재 화면이 FAQ 운영 surface임을 제목으로 표시한다."),
+                    ((0.46, 0.55), "FAQ 목록", "질문과 노출 상태를 row 단위 카드로 보여주는 읽기 모델 영역이다."),
+                    ((0.86, 0.09), "상단 글로벌 액션", "알림, 현재 사용자, 로그아웃 등 관리자 공통 액션을 상단 바에 유지한다."),
+                ],
+            ),
+        ],
+    },
+    "mobile": {
+        "title": "Templates Mobile Screen Spec",
+        "service_label": "mobile",
+        "output": str(SCREEN_DIR / "mobile_screen_spec.pdf"),
+        "asset_dir": str(ASSET_DIR / "mobile_screen_capture"),
+        "base_url": "http://127.0.0.1:3002",
+        "api_base": "http://127.0.0.1:8000/api/v1",
+        "storage_key": "mobile.auth.token",
+        "capture_policy": DESKTOP_CAPTURE_POLICY,
+        "trim_background": False,
+        "cover_note": "첫 페이지는 mobile 화면코드 인덱스다. 이후 페이지는 좌측 화면 캡처와 우측 번호형 기능 테이블을 함께 제공한다.",
+        "source_refs": [
+            {"label": "implementation", "path": "client/mobile/src/app/App.tsx"},
+            {"label": "implementation", "path": "client/mobile/src/pages"},
+            {"label": "capture assets", "path": "sdd/99_toolchain/01_automation/assets/mobile_screen_capture"},
+        ],
+        "screens": [
+            screen(
+                code="MOB-S001",
+                name="Mobile Login",
+                route="/login",
+                access="public",
+                features=["AUT-F001", "AUT-F002"],
+                asset="login.png",
+                requires_auth=False,
+                callouts=[
+                    ((0.25, 0.32), "IN 소개 영역", "상담 흐름과 운영 상태를 동시에 여는 템플릿 맥락을 좌측 hero에서 설명한다."),
+                    ((0.79, 0.19), "Sign in 헤더", "IN workspace 진입 목적과 operator 기본 계정을 우측 로그인 카드 상단에 표시한다."),
+                    ((0.79, 0.39), "자격 증명 입력", "operator@example.com 기준 로그인 입력과 오류 상태를 한 폼에서 처리한다."),
+                    ((0.79, 0.49), "Continue CTA", "로그인 성공 시 저장된 세션으로 IN 보호 라우트에 진입한다."),
+                ],
+            ),
+            screen(
+                code="MOB-S002",
+                name="Mobile Dashboard",
+                route="/",
+                access="protected",
+                features=["AUT-F002", "FUL-F001"],
+                asset="dashboard.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.15, 0.11), "상단 IN 셸", "Overview/Fulfillment 전환, relay status pill, 사용자 정보, 로그아웃을 묶은 공통 헤더다."),
+                    ((0.34, 0.25), "Units in motion hero", "현재 이행 중인 unit 수와 모바일 워크스페이스 목적을 한눈에 보여주는 대형 hero section이다."),
+                    ((0.27, 0.48), "운영 통계 카드", "Open tasks, blocked, outbound ready 지표를 카드 묶음으로 제공한다."),
+                    ((0.33, 0.79), "Relay timeline", "패킹, 예외 검토, 출고 준비 이벤트를 시간축 카드로 정리한다."),
+                    ((0.83, 0.60), "Stage load", "단계별 작업량과 병목 구간을 우측 보조 패널에서 보여준다."),
+                ],
+            ),
+            screen(
+                code="MOB-S003",
+                name="Mobile Fulfillment",
+                route="/fulfillment",
+                access="protected",
+                features=["AUT-F002", "FUL-F002"],
+                asset="fulfillment.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.15, 0.11), "상단 IN 셸", "Fulfillment 화면에서도 Overview/Fulfillment 전환과 사용자 액션이 동일한 헤더 구조를 유지한다."),
+                    ((0.36, 0.23), "Fulfillment board 헤더", "현재 이행 보드 화면의 제목과 task surface 설명을 상단에서 제공한다."),
+                    ((0.39, 0.58), "Fulfillment board 테이블", "Order, task, assignee, status, SLA를 행 단위로 정리한 메인 운영 테이블이다."),
+                    ((0.83, 0.59), "Fulfillment notes", "이행 메모와 운영 체크포인트를 별도 패널로 분리해 보조 컨텍스트를 제공한다."),
+                ],
+            ),
+        ],
+    },
+    "landing": {
+        "title": "Templates Landing Screen Spec",
+        "service_label": "landing",
+        "output": str(SCREEN_DIR / "landing_screen_spec.pdf"),
+        "asset_dir": str(ASSET_DIR / "landing_screen_capture"),
+        "base_url": "http://127.0.0.1:3000",
+        "api_base": "http://127.0.0.1:8000/api/v1",
+        "storage_key": "landing.auth.token",
+        "capture_policy": DESKTOP_CAPTURE_POLICY,
+        "trim_background": False,
+        "cover_note": "첫 페이지는 landing 화면코드 인덱스다. 이후 페이지는 좌측 화면 캡처와 우측 번호형 기능 테이블을 함께 제공한다.",
+        "source_refs": [
+            {"label": "implementation", "path": "client/landing/src/App.tsx"},
+            {"label": "implementation", "path": "client/landing/src/pages"},
+            {"label": "capture assets", "path": "sdd/99_toolchain/01_automation/assets/landing_screen_capture"},
+        ],
+        "screens": [
+            screen(
+                code="LND-S001",
+                name="Landing Home",
+                route="/",
+                access="public",
+                features=["CAT-F001", "AUT-F002"],
+                asset="home.png",
+                requires_auth=False,
+                callouts=[
+                    ((0.16, 0.05), "글로벌 헤더", "브랜드, 섹션 앵커, 로그인 또는 workspace handoff 링크를 상단 헤더에 배치한다."),
+                    ((0.27, 0.20), "히어로 메시지와 CTA", "서비스 가치 제안과 Sign in/See examples CTA를 첫 섹션에서 강조한다."),
+                    ((0.77, 0.25), "카탈로그 스냅샷", "실시간 product 수, active count, highlighted catalog 상태를 요약 카드로 보여준다."),
+                    ((0.30, 0.56), "Features grid", "라이브 catalog product를 카드 그리드로 노출하는 예시 섹션이다."),
+                    ((0.50, 0.75), "Live proof 섹션", "`/api/v1/catalog/products` 기반 sync 결과를 집계 카드와 함께 증빙한다."),
+                    ((0.50, 0.92), "마무리 CTA", "템플릿 시작 CTA로 로그인 또는 workspace 진입을 유도하는 하단 배너다."),
+                ],
+            ),
+            screen(
+                code="LND-S002",
+                name="Landing Login",
+                route="/login",
+                access="public",
+                features=["AUT-F001", "AUT-F002"],
+                asset="login.png",
+                requires_auth=False,
+                callouts=[
+                    ((0.24, 0.34), "랜딩 소개 패널", "로그인 후 `/workspace`로 이어지는 흐름과 landing 복귀 링크를 좌측 소개 영역에서 설명한다."),
+                    ((0.78, 0.20), "Sign in 헤더", "멤버 접근 맥락과 workspace 진입 목적을 우측 로그인 폼 상단에 둔다."),
+                    ((0.78, 0.39), "자격 증명 입력", "이메일, 비밀번호, 오류 메시지를 같은 카드 안에서 처리한다."),
+                    ((0.78, 0.50), "Continue CTA", "성공 시 토큰 저장 후 보호된 `/workspace`로 이동한다."),
+                ],
+            ),
+            screen(
+                code="LND-S003",
+                name="Landing Workspace",
+                route="/workspace",
+                access="protected",
+                features=["AUT-F002", "CAT-F001"],
+                asset="workspace.png",
+                requires_auth=True,
+                callouts=[
+                    ((0.16, 0.07), "멤버 셸 헤더", "Workspace 링크, 현재 사용자, 로그아웃을 포함한 보호 라우트 전용 헤더다."),
+                    ((0.30, 0.32), "Protected workspace 카드", "인증된 사용자 전용 shell 설명과 catalog sync 상태를 메인 카드에 배치한다."),
+                    ((0.77, 0.32), "Current member 카드", "현재 로그인 사용자의 email, role, status를 우측 패널에서 보여준다."),
+                    ((0.30, 0.78), "Workspace product grid", "보호 라우트 안에서 조회한 product 목록을 카드 그리드로 렌더링한다."),
+                ],
+            ),
+        ],
+    },
+}

package/sdd/99_toolchain/01_automation/spec_asset_builder.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import argparse
+import atexit
+import base64
+import importlib.util
+import re
+import shutil
+import subprocess
+import tempfile
+from io import BytesIO
+from pathlib import Path
+from typing import Sequence
+
+from PIL import Image, ImageChops
+
+
+TEMP_DIR = Path(tempfile.mkdtemp(prefix="spec-asset-builder-"))
+PAGE_CACHE: dict[tuple[str, int, int], Image.Image] = {}
+SVG_IMAGE_HREF_PATTERN = re.compile(r'href="data:image/png;base64,([^"]+)"')
+
+
+def cleanup_tempdir() -> None:
+    shutil.rmtree(TEMP_DIR, ignore_errors=True)
+
+
+atexit.register(cleanup_tempdir)
+
+
+def parse_args(
+    argv: Sequence[str] | None = None,
+    *,
+    default_manifest: Path | None = None,
+    default_recipes_var: str = "ASSET_RECIPES",
+) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build static design assets from a recipe manifest.")
+    parser.add_argument("--manifest", default=str(default_manifest) if default_manifest else None, help="Path to the Python recipe manifest.")
+    parser.add_argument("--recipes-var", default=default_recipes_var, help="Manifest variable name that contains the recipe list.")
+    parser.add_argument("--asset", action="append", dest="assets", help="Asset id to build. Repeatable. Default builds all assets.")
+    parser.add_argument("--list", action="store_true", help="List available asset ids and exit.")
+    parser.add_argument("--verify-exact", action="store_true", help="Verify that each generated output is pixel-identical to the resolved source crop.")
+    args = parser.parse_args(argv)
+
+    if not args.manifest:
+        parser.error("--manifest is required")
+
+    return args
+
+
+def load_manifest(manifest_path: Path, recipes_var: str) -> list[dict]:
+    spec = importlib.util.spec_from_file_location("asset_recipe_manifest", manifest_path)
+    if spec is None or spec.loader is None:
+        raise SystemExit(f"Unable to load manifest: {manifest_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    recipes = getattr(module, recipes_var, None)
+    if recipes is None:
+        raise SystemExit(f"Manifest {manifest_path} does not define {recipes_var}")
+    if not isinstance(recipes, list):
+        raise SystemExit(f"{recipes_var} in {manifest_path} must be a list")
+    return recipes
+
+
+def load_pdf_page(path: Path, page: int, dpi: int) -> Image.Image:
+    key = (str(path), page, dpi)
+    cached = PAGE_CACHE.get(key)
+    if cached is not None:
+        return cached.copy()
+
+    output_prefix = TEMP_DIR / f"{path.stem}-p{page}-{dpi}"
+    subprocess.run(
+        [
+            "pdftoppm",
+            "-png",
+            "-singlefile",
+            "-f",
+            str(page),
+            "-l",
+            str(page),
+            "-r",
+            str(dpi),
+            str(path),
+            str(output_prefix),
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    image = Image.open(output_prefix.with_suffix(".png")).convert("RGBA")
+    PAGE_CACHE[key] = image.copy()
+    return image
+
+
+def load_image(path: Path) -> Image.Image:
+    return Image.open(path).convert("RGBA")
+
+
+def resolve_source(source: dict) -> Image.Image:
+    kind = source["kind"]
+    if kind == "pdf_page":
+        return load_pdf_page(Path(source["path"]), int(source["page"]), int(source["dpi"]))
+    if kind == "image":
+        return load_image(Path(source["path"]))
+    raise ValueError(f"Unsupported source kind: {kind}")
+
+
+def make_white_transparent(image: Image.Image, threshold: int) -> Image.Image:
+    converted = image.convert("RGBA")
+    pixels = []
+    for red, green, blue, alpha in converted.getdata():
+        if alpha and red >= threshold and green >= threshold and blue >= threshold:
+            pixels.append((255, 255, 255, 0))
+        else:
+            pixels.append((red, green, blue, alpha))
+    converted.putdata(pixels)
+    return converted
+
+
+def transform_image(image: Image.Image, recipe: dict) -> Image.Image:
+    working = image.copy()
+
+    crop_box = recipe.get("crop_box")
+    if crop_box is not None:
+        working = working.crop(tuple(crop_box))
+
+    threshold = recipe.get("transparent_white_threshold")
+    if threshold is not None:
+        working = make_white_transparent(working, int(threshold))
+
+    if recipe.get("trim"):
+        bbox = working.getbbox()
+        if not bbox:
+            raise ValueError(f"Recipe {recipe['id']} trimmed to empty image")
+        working = working.crop(bbox)
+
+    return working
+
+
+def encode_svg(image: Image.Image) -> str:
+    buffer = BytesIO()
+    image.save(buffer, format="PNG")
+    payload = base64.b64encode(buffer.getvalue()).decode("ascii")
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{image.width}" height="{image.height}" '
+        f'viewBox="0 0 {image.width} {image.height}" fill="none" role="img" aria-hidden="true">\n'
+        f'  <image width="{image.width}" height="{image.height}" href="data:image/png;base64,{payload}" />\n'
+        "</svg>\n"
+    )
+
+
+def write_output(image: Image.Image, output_path: Path, output_format: str) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if output_format == "svg":
+        output_path.write_text(encode_svg(image), encoding="utf-8")
+        return
+    if output_format == "png":
+        image.save(output_path, format="PNG")
+        return
+    raise ValueError(f"Unsupported output format: {output_format}")
+
+
+def read_output_image(output_path: Path, output_format: str) -> Image.Image:
+    if output_format == "png":
+        return Image.open(output_path).convert("RGBA")
+    if output_format == "svg":
+        raw = output_path.read_text(encoding="utf-8")
+        matched = SVG_IMAGE_HREF_PATTERN.search(raw)
+        if not matched:
+            raise ValueError(f"Unable to decode embedded PNG from {output_path}")
+        buffer = BytesIO(base64.b64decode(matched.group(1)))
+        return Image.open(buffer).convert("RGBA")
+    raise ValueError(f"Unsupported output format: {output_format}")
+
+
+def verify_exact_output(output_path: Path, output_format: str, expected_image: Image.Image) -> None:
+    actual = read_output_image(output_path, output_format)
+    expected = expected_image.convert("RGBA")
+
+    if actual.size != expected.size:
+        raise SystemExit(f"Exact verification failed for {output_path}: size mismatch {actual.size} != {expected.size}")
+
+    if ImageChops.difference(actual, expected).getbbox() is not None:
+        raise SystemExit(f"Exact verification failed for {output_path}: pixel mismatch")
+
+
+def infer_output_format(recipe: dict, output_path: Path) -> str:
+    if recipe.get("output_format"):
+        return str(recipe["output_format"])
+    if output_path.suffix.lower() == ".png":
+        return "png"
+    return "svg"
+
+
+def emit_recipe(
+    recipe: dict,
+    *,
+    source_image: Image.Image | None = None,
+    selected_assets: set[str] | None = None,
+    verify_exact: bool = False,
+) -> list[Path]:
+    source = source_image if source_image is not None else resolve_source(recipe["source"])
+    rendered = transform_image(source, recipe)
+    written: list[Path] = []
+
+    output = recipe.get("output")
+    if output is not None and (selected_assets is None or recipe["id"] in selected_assets):
+        output_path = Path(output)
+        output_format = infer_output_format(recipe, output_path)
+        write_output(rendered, output_path, output_format)
+        if verify_exact:
+            verify_exact_output(output_path, output_format, rendered)
+        written.append(output_path)
+
+    for child in recipe.get("children", []):
+        written.extend(
+            emit_recipe(
+                child,
+                source_image=rendered,
+                selected_assets=selected_assets,
+                verify_exact=verify_exact,
+            )
+        )
+
+    return written
+
+
+def collect_asset_ids(recipes: list[dict]) -> list[str]:
+    asset_ids: list[str] = []
+    for recipe in recipes:
+        if recipe.get("output") is not None:
+            asset_ids.append(recipe["id"])
+        asset_ids.extend(collect_asset_ids(recipe.get("children", [])))
+    return asset_ids
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    default_manifest: Path | None = None,
+    default_recipes_var: str = "ASSET_RECIPES",
+) -> None:
+    args = parse_args(argv, default_manifest=default_manifest, default_recipes_var=default_recipes_var)
+    manifest_path = Path(args.manifest).resolve()
+    recipes = load_manifest(manifest_path, args.recipes_var)
+    asset_ids = collect_asset_ids(recipes)
+
+    if args.list:
+        for asset_id in asset_ids:
+            print(asset_id)
+        return
+
+    selected_assets = set(args.assets) if args.assets else None
+    if selected_assets is not None:
+        unknown = sorted(selected_assets.difference(asset_ids))
+        if unknown:
+            raise SystemExit(f"Unknown asset ids: {', '.join(unknown)}")
+
+    written: list[Path] = []
+    for recipe in recipes:
+        written.extend(
+            emit_recipe(
+                recipe,
+                selected_assets=selected_assets,
+                verify_exact=args.verify_exact,
+            )
+        )
+
+    for path in written:
+        print(path)
+
+
+if __name__ == "__main__":
+    main()

package/sdd/99_toolchain/01_automation/ui-contract-projection.md

@@ -0,0 +1,79 @@
+# UI Contract Projection
+
+`UI Contract Projection`은 화면설계서, 계약 문서, reference asset을 제품 UI 구조 위로 투영하고 검증하는 템플릿/스킬 계층의 공통 명칭이다.
+
+## Canonical Naming
+
+- capability: `UI Contract Projection`
+- modes:
+  - `strict projection`
+  - `soft projection`
+- common actions:
+  - `project`
+  - `verify`
+  - `report`
+
+## Ownership Boundary
+
+- 이 문서는 Claude/Codex 스킬과 CLI 래퍼가 공유할 일반 템플릿 계약만 정의한다.
+- 제품별 screen registry, contract rows, evidence 경로는 각 제품 저장소의 `sdd`에서 확장한다.
+- 제품 런타임 route, auth, layout은 이 템플릿을 이유로 분기하지 않는다.
+
+## Skill Prompt Skeleton
+
+```md
+Goal: run UI Contract Projection for {product} {screen_or_flow}
+Mode: {strict projection | soft projection}
+Inputs:
+- contract: {path}
+- source artifact: {pdf|figma export|reference image|yaml}
+- product target: {repo path or route}
+
+Rules:
+- Preserve product runtime behavior.
+- Use React + shadcn/ui primitives and CSS token surface first.
+- Keep projection assets in sdd/toolchain only.
+- Do not add spec/proof/parity-only branches to runtime.
+
+Outputs:
+- updated product UI
+- updated sdd contract/evidence
+- projection report
+```
+
+## CLI Contract Template
+
+```bash
+ui-contract-projection project \
+  --mode strict \
+  --contract <path> \
+  --source <path-or-id> \
+  --target <repo-or-route>
+
+ui-contract-projection verify \
+  --mode strict \
+  --contract <path> \
+  --target <url-or-route> \
+  --evidence-root <path>
+
+ui-contract-projection report \
+  --contract <path> \
+  --evidence-root <path> \
+  --format markdown
+```
+
+## Required Gates
+
+1. `Structure`
+2. `Behavior`
+3. `Data`
+4. `UI Contract Projection`
+
+`strict projection`은 앞선 세 gate를 통과한 뒤에만 사용한다.
+
+## Frontend Defaults
+
+- `React + shadcn/ui`
+- CSS token surface
+- style expansion via `scss`, `styled-components`, or equivalent modern layer
+- shared primitives before screen-specific markup