agentic-dev 0.2.11 → 0.2.13

package/sdd/99_toolchain/01_automation/parity-execution-tooling-design.md

@@ -1,319 +0,0 @@
-# Parity Execution Tooling Design
-
-## Position
-
-UI parity 관련 `실행 도구`는 `sdd/99_toolchain/01_automation`의 소유물로 본다.
-
-즉 템플릿을 복제한 서비스 레포 안에서는 다음처럼 역할을 나눈다.
-
-- `sdd/99_toolchain/01_automation`
-  - parity 실행 도구와 인터페이스의 정본
-  - agentic-dev phase runner와 analyzer의 정본
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`
-  - 이 도구를 어떤 phase에서 어떤 명령으로 호출할지 선언하는 canonical 계약
-- `frontend/scripts`
-  - 실제 화면/라우트/인증/브라우저 런타임에 붙는 앱별 adapter
-- optional `scripts/dev`
-  - 반복 루프, staged sweep, 단일 수정 실행기 같은 운영 오케스트레이션
-
-이 구조를 쓰는 이유는 다음과 같다.
-
-- parity는 특정 앱 기능이 아니라 하네스/검증 도구다.
-- 따라서 엔진과 인터페이스의 정본은 `99_toolchain`에 두는 편이 맞다.
-- 같은 이유로 `agentic-dev` phase runner, contract resolver, proof analyzer도 `99_toolchain`에 둬야 한다.
-- 반면 앱별 route/auth/seed/session/crop 규칙은 `frontend/scripts` 같은 adapter 층에 둬야 한다.
-
-## Layered Ownership
-
-### Layer 1. Toolchain-owned parity runtime
-
-위치:
-
-- `sdd/99_toolchain/01_automation/ui-parity/`
-
-여기에 들어갈 것:
-
-- `core/`
-  - parity 비교 핵심 로직
-  - diff 계산
-  - artifact writing
-  - result normalization
-- `cli/`
-  - `run-proof`
-  - `scaffold-contract`
-  - `route-gap-report`
-  - `extract-reference-pages`
-  - `materialize-reference-assets`
-  - `normalize-reference-assets`
-  - optional `upload-parity1`
-- `runtime/`
-  - playwright runner
-  - stagehand runner
-  - browser/session helpers
-- `contracts/`
-  - JSON/YAML schema 예시
-  - proof result shape
-  - collector metadata shape
-- `interfaces/`
-  - command interface 문서
-  - artifact path 규약
-  - environment variable 규약
-
-소유 원칙:
-
-- 앱과 무관한 범용 실행 로직은 전부 여기 둔다.
-- 새 서비스를 시작해도 이 레이어는 거의 그대로 복제되어야 한다.
-
-### Layer 1b. Toolchain-owned agentic runtime
-
-위치:
-
-- `sdd/99_toolchain/01_automation/agentic-dev/`
-
-여기에 들어갈 것:
-
-- contract resolver
-- phase runner
-- proof result analyzer
-- repo contract template
-- optional spec bootstrap helpers
-
-소유 원칙:
-
-- skill은 이 레이어를 호출해야 한다.
-- skill이 phase runner를 따로 재구현하면 안 된다.
-- 서비스별 차이는 contract에만 두고 실행기는 공용 하네스로 유지한다.
-
-### Layer 2. Repo-local agentic phase contract
-
-위치:
-
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`
-- `.codex/agentic-dev.json`
-- `.claude/agentic-dev.json`
-
-역할:
-
-- `build`, `proof`, `deploy_dev`, `verify_dev` phase를 정의
-- `proof`에서 Layer 1 parity tooling을 호출
-- 하네스 phase 실행기의 입력 계약 역할 수행
-
-소유 원칙:
-
-- 이 레이어는 선언 레이어다.
-- parity 엔진을 직접 구현하지 않는다.
-- phase runner도 직접 구현하지 않는다.
-- `proof_output` 위치를 artifact contract로 보장한다.
-
-### Layer 3. App-specific parity adapter
-
-위치:
-
-- `frontend/scripts/ui-parity-web-adapter.mjs`
-- 또는 `frontend/src/lib/ui-parity/*`
-
-역할:
-
-- screen catalog
-- route catalog
-- auth/session seed
-- app-specific masking
-- app-specific capture preparation
-- reference asset mapping
-
-소유 원칙:
-
-- 앱을 바꾸면 가장 많이 바뀌는 레이어다.
-- 공통 엔진을 몰라도 이 레이어만 바꿔 새 앱에 붙일 수 있어야 한다.
-
-### Layer 4. Dev operations wrapper
-
-위치:
-
-- optional `scripts/dev/*parity*.sh`
-
-역할:
-
-- screen-by-screen loop
-- staged threshold sweep
-- one-shot editor loop
-- optional research export hook
-
-소유 원칙:
-
-- 운영 반복 실행과 실험 제어를 담당한다.
-- proof core와 contract는 재사용하고, 반복 실행만 별도 책임으로 둔다.
-
-## Recommended Directory Layout
-
-```text
-sdd/99_toolchain/01_automation/agentic-dev/
-  repo-contract.json
-.codex/
-  agentic-dev.json
-.claude/
-  agentic-dev.json
-
-sdd/
-  02_plan/
-    10_test/
-      <service>/
-        ui_parity_web_contract.yaml
-    99_generated/
-      from_planning/
-        ui_parity/
-  03_verify/
-    10_test/
-      ui_parity/
-  99_toolchain/
-    03_automation/
-      agentic-dev/
-        run_repo_phase.sh
-        resolve_repo_contract.py
-        init_repo_contract.sh
-        analyze_proof_results.py
-      ui-parity/
-        core/
-        cli/
-        runtime/
-        contracts/
-        interfaces/
-        README.md
-        ui-parity-proof-interface.md
-        ui-parity-artifact-layout.md
-
-frontend/
-  scripts/
-    ui-parity-web-adapter.mjs
-  src/
-    lib/
-      specScreens.json
-      specRouteCatalog.json
-```
-
-## Phase Wiring
-
-### build
-
-- 앱 빌드
-- 정적 타입/테스트
-
-예시:
-
-```json
-"build": "npm --prefix frontend run build"
-```
-
-### proof
-
-- `sdd/99_toolchain/01_automation/agentic-dev/run_repo_phase.sh`가 contract를 읽는다.
-- contract의 `proof`는 `sdd/99_toolchain/01_automation/ui-parity/cli/run-proof`를 호출한다.
-- `run-proof`는 app adapter를 읽고 strict parity를 실행한다.
-- 결과는 `sdd/03_verify/10_test/ui_parity/...`에 저장한다.
-
-예시 shape:
-
-```json
-"proof": "node sdd/99_toolchain/01_automation/ui-parity/cli/run-proof.mjs --adapter frontend/scripts/ui-parity-web-adapter.mjs --contract sdd/02_plan/10_test/<service>/ui_parity_web_contract.yaml --out sdd/03_verify/10_test/ui_parity/<service>_agentic_dev_latest.json"
-```
-
-### deploy_dev
-
-- repo-local 배포 스크립트 호출
-
-### verify_dev
-
-- DEV endpoint smoke check
-- proof artifact 존재 확인
-
-## Artifact Contracts
-
-### Required proof output
-
-`artifacts.proof_output`는 다음 요구를 만족해야 한다.
-
-- latest single JSON file
-- screen별 `actual_image`, `diff_image`, `diff_ratio`
-- route/target/reference dimensions
-- fail/pass summary
-
-### Required evidence tree
-
-- `reference/`
-- `<timestamp>/actual/`
-- `<timestamp>/diff/`
-- `loop_runs/`
-- `staged_runs/`
-
-정책:
-
-- phase 성공 여부는 이 구조의 존재와 JSON 무결성으로 판단한다.
-
-## Interface Boundaries
-
-### Toolchain to app adapter
-
-Toolchain은 app adapter에 다음만 기대한다.
-
-- screen list
-- route mapping
-- auth preparer
-- mask rect provider
-- reference registry location
-- target base URL
-
-Toolchain은 앱 DOM 구조를 직접 하드코딩하지 않는다.
-
-### Toolchain to agentic contract
-
-Toolchain은 contract에 다음만 기대한다.
-
-- `commands.proof`
-- `artifacts.proof_output`
-
-agentic contract는 parity 내부 로직을 몰라도 된다.
-
-### Optional external integrations
-
-- `parity-1 collector`
-  - optional upload target
-- `parity-1 objective export`
-  - optional research export
-
-정책:
-
-- 외부 integration이 없어도 parity proof 자체는 완결되어야 한다.
-
-## Enforcement Rules
-
-- 프론트엔드가 있는 템플릿은 `proof` phase를 mandatory로 둔다.
-- `proof_output`이 생성되지 않으면 실패다.
-- DEV 반영이 요구되는 작업은 `deploy_dev -> verify_dev`를 mandatory로 둔다.
-- `main push` 이전 DEV 배포는 허용하지 않는다.
-- `sdd/99_toolchain/01_automation/agentic-dev/run_repo_phase.sh`는 phase 순서를 우회하지 못하게 해야 한다.
-
-## Why `99_toolchain`
-
-`99_toolchain`에 두는 것이 맞는 이유:
-
-- parity는 앱 기능이 아니라 검증 자동화다.
-- 정책, 인터페이스, 실행기, 산출물 계약이 모두 toolchain 성격이다.
-- `agentic-dev` runner도 같은 이유로 toolchain 소유가 맞다.
-- `frontend/scripts`에 전부 넣으면 서비스별 앱 코드와 하네스 코드가 다시 섞인다.
-- `99_toolchain`에 engine을 두고 `frontend`에는 adapter만 두면 책임 분리가 선명해진다.
-
-## Migration Recommendation
-
-현재 reference implementation에서 템플릿 정본으로 승격할 때는 다음 순서를 권장한다.
-
-1. `frontend/scripts/ui-parity-*.mjs` 중 app-agnostic 로직을 `sdd/99_toolchain/01_automation/ui-parity/`로 이동
-2. app-specific 로직만 `frontend/scripts/ui-parity-web-adapter.mjs`로 축소
-3. `agentic-dev` runner를 `sdd/99_toolchain/01_automation/agentic-dev/`로 이동
-4. `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`은 새 toolchain CLI를 호출하도록 단순화
-5. `scripts/dev/*parity*.sh`는 필요할 때만 repo별로 추가하고, base template에는 포함하지 않는다
-
-## Non-Goals
-
-- `parity-1` backend를 repo 안에 복사하지 않는다.
-- 특정 서비스의 screen code 체계를 toolchain에 하드코딩하지 않는다.
-- app adapter 없이 toolchain만으로 모든 앱을 자동 추론하게 만들지 않는다.

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

@@ -1,21 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[3]
-PLAYWRIGHT_HARNESS_ROOT = ROOT / "research" / "agent-browser" / "pocs" / "playwright-dev-e2e"
-PLAYWRIGHT_CONFIG = PLAYWRIGHT_HARNESS_ROOT / "playwright.config.js"
-PLAYWRIGHT_PACKAGE = PLAYWRIGHT_HARNESS_ROOT / "package.json"
-PLAYWRIGHT_RESULTS_DIR = ROOT / "research" / "agent-browser" / "results"
-
-
-# Downstream repos should populate this registry with durable suite ids.
-PLAYWRIGHT_SUITES: list[dict[str, object]] = []
-
-
-def get_suite_by_id(suite_id: str) -> dict[str, object]:
-    for suite in PLAYWRIGHT_SUITES:
-        if suite["id"] == suite_id:
-            return suite
-    raise KeyError(suite_id)

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

@@ -1,87 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-from typing import Sequence
-
-from playwright_exactness_manifest import PLAYWRIGHT_HARNESS_ROOT, PLAYWRIGHT_SUITES, get_suite_by_id
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Run retained Playwright exactness suites through the canonical SDD toolchain entrypoint.",
-    )
-    parser.add_argument("--list", action="store_true", help="List registered suite ids and exit.")
-    parser.add_argument("--suite", action="append", dest="suites", help="Suite id from playwright_exactness_manifest.py. Repeatable.")
-    parser.add_argument("--base-url", help="Override BASE_URL.")
-    parser.add_argument("--api-base-url", help="Override API_BASE_URL.")
-    parser.add_argument("--browser", help="Forward Playwright --browser option.")
-    parser.add_argument("--grep", help="Forward Playwright -g/--grep option.")
-    parser.add_argument("--reporter", default="list", help="Playwright reporter. Default: list")
-    parser.add_argument("--dry-run", action="store_true", help="Print command and exit without running.")
-    parser.add_argument("--arg", action="append", dest="extra_args", default=[], help="Additional Playwright CLI arg. Repeatable.")
-    return parser.parse_args()
-
-
-def emit_suite_list() -> None:
-    json.dump(PLAYWRIGHT_SUITES, sys.stdout, ensure_ascii=False, indent=2)
-    sys.stdout.write("\n")
-
-
-def build_command(suite_ids: Sequence[str], *, grep: str | None, browser: str | None, reporter: str, extra_args: Sequence[str]) -> list[str]:
-    command = ["npm", "test", "--"]
-    for suite_id in suite_ids:
-        suite = get_suite_by_id(suite_id)
-        command.append(str(suite["spec"]))
-    if grep:
-        command.extend(["-g", grep])
-    if browser:
-        command.append(f"--browser={browser}")
-    if reporter:
-        command.append(f"--reporter={reporter}")
-    command.extend(extra_args)
-    return command
-
-
-def main() -> int:
-    args = parse_args()
-    if args.list:
-        emit_suite_list()
-        return 0
-
-    if not args.suites:
-        raise SystemExit("At least one --suite is required unless --list is used.")
-
-    command = build_command(
-        args.suites,
-        grep=args.grep,
-        browser=args.browser,
-        reporter=args.reporter,
-        extra_args=args.extra_args,
-    )
-
-    env = os.environ.copy()
-    if args.base_url:
-        env["BASE_URL"] = args.base_url
-    if args.api_base_url:
-        env["API_BASE_URL"] = args.api_base_url
-
-    if args.dry_run:
-        print(f"cwd={PLAYWRIGHT_HARNESS_ROOT}")
-        print("command=" + " ".join(command))
-        if args.base_url:
-            print(f"BASE_URL={args.base_url}")
-        if args.api_base_url:
-            print(f"API_BASE_URL={args.api_base_url}")
-        return 0
-
-    completed = subprocess.run(command, cwd=PLAYWRIGHT_HARNESS_ROOT, env=env, check=False)
-    return completed.returncode
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())