agentic-dev 0.1.0 → 0.2.0

package/sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: run_frontend_target.sh <action> [repo_root] [target]
+
+Actions:
+  build
+  preview
+  scaffold
+  route_gap
+  materialize_references
+  proof
+EOF
+}
+
+if [[ $# -lt 1 ]]; then
+  usage >&2
+  exit 1
+fi
+
+action="$1"
+repo_root="$(cd "${2:-$(pwd)}" && pwd)"
+target_name="${3:-${FRONTEND_TARGET:-}}"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+resolver_path="${script_dir}/resolve_frontend_target.py"
+payload="$(python3 "${resolver_path}" "${repo_root}" "${target_name}")"
+
+read_target_value() {
+  local key="$1"
+  python3 - "${payload}" "${key}" <<'PY'
+import json
+import sys
+
+payload = json.loads(sys.argv[1])
+key = sys.argv[2]
+value = payload
+for part in key.split("."):
+    if not isinstance(value, dict):
+        raise SystemExit(1)
+    value = value.get(part)
+if isinstance(value, (dict, list)):
+    print(json.dumps(value, ensure_ascii=False))
+elif value is None:
+    raise SystemExit(1)
+else:
+    print(str(value))
+PY
+}
+
+target_id="$(read_target_value "name")"
+target_dir="$(read_target_value "target.dir")"
+adapter_path="$(read_target_value "target.adapter_path")"
+screens_path="$(read_target_value "target.screens_path")"
+routes_path="$(read_target_value "target.routes_path")"
+parity_contract_path="$(read_target_value "target.parity_contract_path")"
+route_gap_output="$(read_target_value "target.route_gap_output")"
+route_gap_markdown_output="$(read_target_value "target.route_gap_markdown_output")"
+proof_output="$(read_target_value "target.proof_output")"
+
+cd "${repo_root}"
+
+case "${action}" in
+  build)
+    npm --prefix "${target_dir}" run build
+    ;;
+  preview)
+    npm --prefix "${target_dir}" run preview
+    ;;
+  scaffold)
+    node sdd/99_toolchain/01_automation/ui-parity/cli/scaffold-contract.mjs \
+      --adapter "${adapter_path}" \
+      --out "${parity_contract_path}"
+    ;;
+  route_gap)
+    node sdd/99_toolchain/01_automation/ui-parity/cli/route-gap-report.mjs \
+      --service "${target_id}" \
+      --screens "${screens_path}" \
+      --routes "${routes_path}" \
+      --out "${route_gap_output}" \
+      --markdown-out "${route_gap_markdown_output}"
+    ;;
+  materialize_references)
+    node sdd/99_toolchain/01_automation/ui-parity/cli/materialize-reference-assets.mjs \
+      --adapter "${adapter_path}" \
+      --contract "${parity_contract_path}"
+    ;;
+  proof)
+    node sdd/99_toolchain/01_automation/ui-parity/cli/run-proof.mjs \
+      --adapter "${adapter_path}" \
+      --contract "${parity_contract_path}" \
+      --out "${proof_output}"
+    ;;
+  *)
+    echo "Unsupported frontend action: ${action}" >&2
+    usage >&2
+    exit 1
+    ;;
+esac

package/sdd/99_toolchain/01_automation/agentic-dev/run_repo_phase.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: run_repo_phase.sh <phase> [repo_root] [target]
+
+Run a repo-local command from the nearest repo contract.
+
+Supported phases:
+  plan_audit
+  build
+  proof
+  deploy_dev
+  verify_dev
+  full_dev
+EOF
+}
+
+if [[ $# -lt 1 ]]; then
+  usage >&2
+  exit 1
+fi
+
+phase="$1"
+repo_root="${2:-$(pwd)}"
+frontend_target="${3:-}"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+resolver_path="${script_dir}/resolve_repo_contract.py"
+frontend_resolver_path="${script_dir}/resolve_frontend_target.py"
+proof_schema_path="${script_dir}/../ui-parity/contracts/proof-result.schema.json"
+route_gap_schema_path="${script_dir}/../ui-parity/contracts/route-gap-report.schema.json"
+schema_validator_path="${script_dir}/validate_json_schema.py"
+
+resolve_contract() {
+  "${resolver_path}" "${repo_root}"
+}
+
+load_contract_value() {
+  local contract_path="$1"
+  local key="$2"
+  python3 - "${contract_path}" "${key}" <<'PY'
+import json
+import sys
+
+contract_path, key = sys.argv[1], sys.argv[2]
+with open(contract_path, "r", encoding="utf-8") as handle:
+    data = json.load(handle)
+
+keys = key.split(".")
+value = data
+for part in keys:
+    if not isinstance(value, dict):
+        raise SystemExit(1)
+    value = value.get(part)
+
+if not isinstance(value, str) or not value.strip():
+    raise SystemExit(1)
+
+print(value.strip())
+PY
+}
+
+run_single_phase() {
+  local contract_path="$1"
+  local repo_root_path="$2"
+  local single_phase="$3"
+  local command
+  command="$(load_contract_value "${contract_path}" "commands.${single_phase}")" || {
+    echo "Phase command not found in ${contract_path}: ${single_phase}" >&2
+    exit 1
+  }
+
+  printf 'Running phase `%s` from %s\n' "${single_phase}" "${contract_path}"
+  (
+    cd "${repo_root_path}"
+    if [[ -n "${frontend_target}" ]]; then
+      export FRONTEND_TARGET="${frontend_target}"
+    fi
+    eval "${command}"
+  )
+
+  if [[ "${single_phase}" == "plan_audit" ]]; then
+    local route_gap_output
+    route_gap_output="$(python3 "${frontend_resolver_path}" "${repo_root_path}" "${frontend_target}" | python3 -c 'import json,sys; print(json.load(sys.stdin)["target"]["route_gap_output"])')" || \
+    route_gap_output="$(load_contract_value "${contract_path}" "artifacts.route_gap_output")" || {
+      echo "Route gap artifact path not found in ${contract_path}" >&2
+      exit 1
+    }
+    if [[ ! -f "${repo_root_path}/${route_gap_output}" ]]; then
+      echo "Expected route gap artifact missing: ${repo_root_path}/${route_gap_output}" >&2
+      exit 1
+    fi
+    python3 "${schema_validator_path}" "${route_gap_schema_path}" "${repo_root_path}/${route_gap_output}"
+    python3 "${script_dir}/analyze_route_gap.py" --gate "${repo_root_path}/${route_gap_output}"
+  fi
+
+  if [[ "${single_phase}" == "proof" || "${single_phase}" == "verify_dev" ]]; then
+    local proof_output
+    proof_output="$(python3 "${frontend_resolver_path}" "${repo_root_path}" "${frontend_target}" | python3 -c 'import json,sys; print(json.load(sys.stdin)["target"]["proof_output"])')" || \
+    proof_output="$(load_contract_value "${contract_path}" "artifacts.proof_output")" || {
+      echo "Proof artifact path not found in ${contract_path}" >&2
+      exit 1
+    }
+    if [[ ! -f "${repo_root_path}/${proof_output}" ]]; then
+      echo "Expected proof artifact missing: ${repo_root_path}/${proof_output}" >&2
+      exit 1
+    fi
+    python3 "${schema_validator_path}" "${proof_schema_path}" "${repo_root_path}/${proof_output}"
+    if [[ "${single_phase}" == "proof" ]]; then
+      python3 "${script_dir}/analyze_proof_results.py" --gate "${repo_root_path}/${proof_output}"
+    fi
+  fi
+}
+
+if [[ ! -f "${resolver_path}" ]]; then
+  echo "Missing contract resolver: ${resolver_path}" >&2
+  exit 1
+fi
+
+contract_path="$(resolve_contract)" || exit 1
+repo_root="$(cd "$(dirname "${contract_path}")/.." && pwd)"
+
+case "${phase}" in
+  plan_audit|build|proof|deploy_dev|verify_dev)
+    run_single_phase "${contract_path}" "${repo_root}" "${phase}"
+    ;;
+  full_dev)
+    run_single_phase "${contract_path}" "${repo_root}" plan_audit
+    run_single_phase "${contract_path}" "${repo_root}" build
+    run_single_phase "${contract_path}" "${repo_root}" proof
+    run_single_phase "${contract_path}" "${repo_root}" deploy_dev
+    run_single_phase "${contract_path}" "${repo_root}" verify_dev
+    ;;
+  *)
+    echo "Unsupported phase: ${phase}" >&2
+    usage >&2
+    exit 1
+    ;;
+esac

package/sdd/99_toolchain/01_automation/agentic-dev/validate_json_schema.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("Usage: validate_json_schema.py <schema-json> <instance-json>", file=sys.stderr)
+        return 1
+
+    schema_path = Path(sys.argv[1])
+    instance_path = Path(sys.argv[2])
+    if not schema_path.is_file():
+        print(f"Schema not found: {schema_path}", file=sys.stderr)
+        return 1
+    if not instance_path.is_file():
+        print(f"Instance not found: {instance_path}", file=sys.stderr)
+        return 1
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    instance = json.loads(instance_path.read_text(encoding="utf-8"))
+    validator = Draft202012Validator(schema)
+    errors = sorted(validator.iter_errors(instance), key=lambda error: list(error.absolute_path))
+    if errors:
+      print("schema_validation=fail")
+      for error in errors[:20]:
+          path_label = ".".join(str(part) for part in error.absolute_path) or "<root>"
+          print(f"- {path_label}: {error.message}")
+      return 2
+
+    print("schema_validation=pass")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,291 @@
+# 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/04_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/04_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-platform-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/04_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-platform-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_platform_contract.template.yaml`
+- `sdd/02_plan/99_generated/from_planning/ui_parity/.gitkeep`
+- `sdd/04_verify/10_test/ui_parity/.gitkeep`
+
+### Frontend template
+
+`templates/client/platform` 또는 별도 frontend template에는 다음을 넣는다.
+
+- parity npm scripts
+- `client/platform/scripts/ui-parity-platform-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

@@ -0,0 +1,10 @@
+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)