agentic-dev 0.2.10 → 0.2.12

package/sdd/99_toolchain/01_automation/agentic-parity-harness-design.md

@@ -1,291 +0,0 @@
-# Agentic Parity Harness Design
-
-## Purpose
-
-이 템플릿은 단일 서비스 starter가 아니라, 복제 후 각 서비스가 자기 저장소 안에서 SDD 기반 하네스를 완결적으로 소유하는 출발점이다.
-
-따라서 이 문서의 목표는 다음이다.
-
-- 템플릿을 복제한 각 서비스 레포가 외부 하네스 저장소 없이도 `build -> proof -> deploy_dev -> verify_dev`를 실행하게 한다.
-- `agentic-dev` 계약, parity proof, phase runner, 분석기 같은 하네스 도구를 모두 `99_toolchain` 아래 정본으로 둔다.
-- UI parity strict proof를 프론트엔드 템플릿의 기본 하네스로 포함한다.
-- `proof`와 DEV 검증을 선택이 아니라 기본 강제 phase로 설계한다.
-- 스킬은 하네스 도구의 구현체가 아니라, `99_toolchain` 도구를 호출하는 인터페이스로만 동작한다.
-- 외부 collector/연구 시스템은 integration 대상일 뿐, 서비스 레포 내부 구현으로 복사하지 않는다.
-
-## Core Position
-
-이 설계에서는 `agentic-dev`와 parity proof를 separate ad-hoc scripts로 흩어두지 않는다.
-
-대신 다음처럼 해석한다.
-
-- `agentic-dev`
-  - 서비스별 phase 계약
-- `99_toolchain`
-  - 그 계약을 실행하는 공용 하네스 런타임의 repo-local 정본
-- skill
-  - `99_toolchain` 실행기를 호출하는 얇은 orchestration surface
-
-그리고 템플릿에서는 하네스 런타임을 `99_toolchain`으로 흡수한다.
-
-즉 복제 후 각 서비스 레포 안에는 둘 다 존재한다.
-
-- 서비스별 계약 파일
-- `99_toolchain` 하네스 실행기
-
-이렇게 해야 각 서비스 레포가 self-contained 가 된다.
-
-## Design Principles
-
-- self-contained first:
-  - 복제된 서비스 레포는 외부 skill 저장소가 없어도 하네스를 실행할 수 있어야 한다.
-- toolchain-owned execution:
-  - 하네스 실행 스크립트와 분석기는 `99_toolchain`의 소유물이어야 한다.
-- repo-local contract:
-  - 각 서비스는 자기 `build`, `proof`, `deploy_dev`, `verify_dev`, `proof_output`를 자기 레포 안에서 선언한다.
-- deterministic proof:
-  - `proof`는 strict parity 또는 동등한 결정적 UI 증거를 남겨야 한다.
-- evidence-first:
-  - 성공/실패는 콘솔 로그가 아니라 `sdd/03_verify/...` 산출물로 판단한다.
-- deploy discipline:
-  - DEV 반영이 필요한 작업은 `main push -> DEV deploy -> DEV verify`를 따른다.
-- external integration boundary:
-  - collector/backend/research 시스템은 외부에 두고, repo에는 adapter와 contract만 둔다.
-
-## Required Template Surface
-
-### 1. Toolchain-owned agentic runtime
-
-템플릿 안에 다음 runtime을 `sdd/99_toolchain/01_automation/agentic-dev/`로 포함한다.
-
-- `sdd/99_toolchain/01_automation/agentic-dev/run_repo_phase.sh`
-- `sdd/99_toolchain/01_automation/agentic-dev/resolve_repo_contract.py`
-- `sdd/99_toolchain/01_automation/agentic-dev/init_repo_contract.sh`
-- `sdd/99_toolchain/01_automation/agentic-dev/analyze_proof_results.py`
-- optional:
-  - `sdd/99_toolchain/01_automation/agentic-dev/bootstrap_spec_workspace.sh`
-  - `sdd/99_toolchain/01_automation/agentic-dev/assets/repo-contract.template.json`
-
-설계 규칙:
-
-- 이 파일들은 외부 저장소 참조가 아니라 템플릿 payload다.
-- 템플릿 개선 시 상위 `templates`에서 갱신하고, 각 서비스는 필요시 역전파한다.
-- 각 서비스 레포는 이 runtime을 자기 소유 코드처럼 취급한다.
-- skill은 이 디렉터리의 실행기를 호출해야 하며, 별도 구현을 복제하면 안 된다.
-
-### 2. Agentic contract layer
-
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`
-- `.codex/agentic-dev.json`
-- `.claude/agentic-dev.json`
-
-필수 contract shape:
-
-```json
-{
-  "schema_version": 1,
-  "name": "<service-name>",
-  "spec": {
-    "planning_paths": ["sdd/01_planning", "sdd/02_plan"],
-    "canonical_targets_dir": "sdd/02_plan"
-  },
-  "commands": {
-    "build": "<repo-local build command>",
-    "proof": "<repo-local deterministic proof command>",
-    "deploy_dev": "<repo-local DEV deploy command>",
-    "verify_dev": "<repo-local DEV verify command>"
-  },
-  "artifacts": {
-    "proof_output": "sdd/03_verify/10_test/<tool>/<latest>.json"
-  }
-}
-```
-
-설계 규칙:
-
-- vendored runner는 `.codex -> .claude -> sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json` 순서로 contract를 찾는다.
-- `.codex/agentic-dev.json`, `.claude/agentic-dev.json`는 canonical contract만 가리킨다.
-- 서비스별 차이는 오직 이 contract와 repo-local commands에서 표현한다.
-
-### 3. UI parity engine layer
-
-Frontend-capable template의 parity 실행 도구 정본은 `99_toolchain` 아래에 둔다.
-
-상세 구조와 레이어 분리는 [parity-execution-tooling-design.md](parity-execution-tooling-design.md)를 따른다.
-
-Frontend-capable template에는 다음 두 층이 있어야 한다.
-
-- toolchain-owned engine:
-  - `sdd/99_toolchain/01_automation/ui-parity/*`
-- app-specific adapter:
-  - `frontend/scripts/ui-parity-web-adapter.mjs`
-
-참조 구현 기준으로 초기 이관 대상 스크립트 묶음은 다음과 같다.
-
-- `frontend/scripts/ui-parity-core.mjs`
-- `frontend/scripts/ui-parity-runner.mjs`
-- `frontend/scripts/ui-parity-runtimes.mjs`
-- `frontend/scripts/ui-parity-auth.mjs`
-- `frontend/scripts/ui-parity-scaffold.mjs`
-- `frontend/scripts/ui-parity-route-gap-report.mjs`
-- `frontend/scripts/ui-parity-extract-reference-pages.mjs`
-- `frontend/scripts/ui-parity-materialize-reference-assets.mjs`
-- `frontend/scripts/ui-parity-normalize-reference-assets.mjs`
-- optional:
-  - `frontend/scripts/ui-parity-playwright-runner.mjs`
-  - `frontend/scripts/ui-parity-stagehand-runner.mjs`
-  - `frontend/scripts/ui-parity-parity1-upload.mjs`
-
-`frontend/package.json`에는 최소한 다음 entrypoint를 둔다.
-
-- `ui:parity:scaffold`
-- `ui:parity:proof`
-- `ui:parity`
-- `ui:parity:route-gap`
-
-### 4. Repo-local orchestration layer
-
-`scripts/dev/` 래퍼는 선택 레이어다.
-
-- base template에는 포함하지 않는다.
-- loop/sweep/edit-once가 필요할 때만 repo별로 추가한다.
-
-설계 규칙:
-
-- loop/sweep는 repo-local npm entrypoint를 호출한다.
-- research export는 dependency가 있으면 수행하고, 없으면 warning 수준으로 남기되 proof를 실패시키지 않는다.
-
-### 5. Contract and evidence layer
-
-표준 SDD 경로:
-
-- `sdd/02_plan/10_test/<service>/ui_parity_<target>_contract.yaml`
-- `sdd/02_plan/99_generated/from_planning/ui_parity/`
-- `sdd/03_verify/10_test/ui_parity/`
-
-권장 evidence 구조:
-
-- `reference/`
-- `<timestamp>/actual/`
-- `<timestamp>/diff/`
-- `loop_runs/`
-- `staged_runs/`
-- `ui_parity_latest.json`
-- `<service>_agentic_dev_latest.json`
-
-## Harness Enforcement Model
-
-### Required phases
-
-모든 프론트엔드 포함 서비스 템플릿은 아래 phase를 기본 강제한다.
-
-1. `build`
-2. `proof`
-3. `deploy_dev`
-4. `verify_dev`
-
-강제 규칙:
-
-- 프론트엔드 변경이 있는 repo는 `proof` 생략을 허용하지 않는다.
-- `proof_output`이 생성되지 않으면 `proof` 성공으로 보지 않는다.
-- DEV 반영이 필요한 작업은 `deploy_dev`와 `verify_dev`를 반드시 통과해야 한다.
-- DEV 반영 전에는 `main push`가 선행되어야 한다.
-- phase 실행은 항상 repo 내부 `sdd/99_toolchain/01_automation/agentic-dev/run_repo_phase.sh`를 기준으로 한다.
-
-### Gate semantics
-
-- `build`
-  - 빌드 또는 정적 검증 통과
-- `proof`
-  - strict parity 또는 deterministic UI proof 수행
-  - latest artifact 생성
-- `deploy_dev`
-  - repo-local DEV deploy 명령 성공
-- `verify_dev`
-  - 실제 DEV endpoint 또는 runtime smoke check 성공
-
-### Failure semantics
-
-- `proof` 실패:
-  - latest json, actual/diff artifacts, 관련 loop evidence를 남긴다.
-- `deploy_dev` 실패:
-  - 증거 문서에 실패 명령과 시점을 남긴다.
-- `verify_dev` 실패:
-  - `fix -> redeploy -> reverify` 루프로 되돌린다.
-
-## Boundary Model
-
-### Vendored into each service repo
-
-템플릿 복제 후 각 서비스가 직접 소유해야 하는 것:
-
-- `sdd/99_toolchain/01_automation/agentic-dev/*`
-- `sdd/99_toolchain/01_automation/ui-parity/*`
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json`
-- `.codex/agentic-dev.json`
-- `.claude/agentic-dev.json`
-- `frontend/scripts/ui-parity-web-adapter.mjs`
-- app-side collector upload adapter
-- repo-local loop/sweep scripts
-- evidence path declarations
-
-### Kept external
-
-서비스 레포 밖에 남겨야 하는 것:
-
-- `parity-1` collector backend
-- `parity-1` objective/research implementation
-- 실제 collector URL, API key, 저장소 위치 같은 환경값
-
-### Reference source only
-
-다음은 참조 구현일 뿐, 런타임 dependency로 남길 필요는 없다.
-
-- `say828-agent-market/codex/skills/universal-agentic-dev`
-
-정책:
-
-- 템플릿은 여기서 아이디어와 runner를 가져올 수 있다.
-- 하지만 최종 서비스 레포는 외부 skill 저장소가 없어도 실행 가능해야 한다.
-
-## Template Rollout Recommendation
-
-### Base template
-
-`templates`에는 최소한 다음을 넣는다.
-
-- `sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json` example
-- `.codex/agentic-dev.json`
-- `.claude/agentic-dev.json`
-- `sdd/99_toolchain/01_automation/agentic-dev/` vendored runtime
-- `sdd/99_toolchain/01_automation/ui-parity/` parity tooling
-- optional `scripts/dev/` parity orchestration wrappers
-- `sdd/02_plan/10_test/templates/ui_parity_web_contract.template.yaml`
-- `sdd/02_plan/99_generated/from_planning/ui_parity/.gitkeep`
-- `sdd/03_verify/10_test/ui_parity/.gitkeep`
-
-### Frontend template
-
-`templates/client/web` 또는 별도 frontend template에는 다음을 넣는다.
-
-- parity npm scripts
-- `client/web/scripts/ui-parity-web-adapter.mjs`
-- minimal screen catalog / route catalog placeholder
-- proof output path convention
-
-그리고 repo root에는 다음 toolchain 실행기를 둔다.
-
-- `sdd/99_toolchain/01_automation/ui-parity/*`
-- `sdd/99_toolchain/01_automation/agentic-dev/*`
-
-### Sanitization rules
-
-- `dist/`, `node_modules/`, captured images, timestamped runs, 실제 reference asset은 템플릿에 넣지 않는다.
-- contract 예시에는 실환경 URL 대신 placeholder를 둔다.
-
-## Non-Goals
-
-- `parity-1` collector/objective 코드를 서비스 레포 안으로 복사하지 않는다.
-- 특정 서비스의 화면 수, screen code, reference asset을 템플릿 공통값으로 고정하지 않는다.
-- 중앙 공용 하네스 서버나 외부 skill 저장소가 없으면 실행할 수 없는 구조를 강제하지 않는다.
-- 하네스 구현을 skill 내부 로직으로 숨겨 두지 않는다.

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

@@ -1,10 +0,0 @@
-from pathlib import Path
-
-from spec_asset_builder import main
-
-
-DEFAULT_MANIFEST = Path(__file__).resolve().parents[1] / "03_templates/asset_recipe_manifest.example.py"
-
-
-if __name__ == "__main__":
-    main(default_manifest=DEFAULT_MANIFEST)