agentic-dev 0.1.0 → 0.2.0

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+
+VALID_OK_STATUSES = {"passed"}
+VALID_FAIL_STATUSES = {"failed", "size_mismatch", "missing_reference", "capture_error"}
+
+
+def collect_cases(node, bucket):
+    if isinstance(node, dict):
+        score = None
+        identifier = None
+        for key in ("diff_ratio", "score", "difference_ratio"):
+            value = node.get(key)
+            if isinstance(value, (int, float)):
+                score = float(value)
+                break
+        for key in ("screen_code", "id", "name", "case", "route"):
+            value = node.get(key)
+            if isinstance(value, str) and value.strip():
+                identifier = value.strip()
+                break
+        if score is not None:
+            bucket.append((identifier or f"case_{len(bucket)+1}", score))
+        for value in node.values():
+            collect_cases(value, bucket)
+    elif isinstance(node, list):
+        for item in node:
+            collect_cases(item, bucket)
+
+
+def summarize(path: Path) -> int:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    cases = []
+    collect_cases(data, cases)
+    unique = []
+    seen = set()
+    for identifier, score in sorted(cases, key=lambda item: item[1], reverse=True):
+        key = (identifier, score)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append((identifier, score))
+
+    print(f"proof_file={path}")
+    print(f"cases_found={len(unique)}")
+    if not unique:
+        print("No comparable cases with numeric diff_ratio/score found.")
+        return 0
+    failing = [item for item in unique if item[1] > 0]
+    best = min(unique, key=lambda item: item[1])
+    worst = max(unique, key=lambda item: item[1])
+    print(f"failing_cases={len(failing)}")
+    print(f"best_case={best[0]} score={best[1]:.8f}")
+    print(f"worst_case={worst[0]} score={worst[1]:.8f}")
+    for identifier, score in failing[:10]:
+        print(f"- {identifier}: {score:.8f}")
+    return 0
+
+
+def check_gate(path: Path) -> int:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    summary = data.get("summary")
+    screens = data.get("screens")
+    if not isinstance(summary, dict):
+        print("proof_gate=fail reason=missing_summary")
+        return 2
+    if not isinstance(screens, list):
+        print("proof_gate=fail reason=missing_screens")
+        return 2
+
+    failing_statuses = []
+    for screen in screens:
+        if not isinstance(screen, dict):
+            failing_statuses.append(("unknown", "invalid_row"))
+            continue
+        status = screen.get("status")
+        identifier = screen.get("id") or screen.get("route") or "unknown"
+        if status in VALID_OK_STATUSES:
+            continue
+        if status in VALID_FAIL_STATUSES:
+            failing_statuses.append((identifier, status))
+        else:
+            failing_statuses.append((identifier, f"unknown_status:{status}"))
+
+    capture_error = int(summary.get("capture_error", 0) or 0)
+    failed = int(summary.get("failed", 0) or 0)
+    missing_reference = int(summary.get("missing_reference", 0) or 0)
+    matched = bool(summary.get("matched", False))
+
+    if failing_statuses or capture_error > 0 or failed > 0 or missing_reference > 0 or not matched:
+        print("proof_gate=fail")
+        print(f"summary_failed={failed}")
+        print(f"summary_missing_reference={missing_reference}")
+        print(f"summary_capture_error={capture_error}")
+        print(f"summary_matched={matched}")
+        for identifier, status in failing_statuses[:20]:
+            print(f"- {identifier}: {status}")
+        return 2
+
+    print("proof_gate=pass")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: analyze_proof_results.py [--gate] <proof-json>", file=sys.stderr)
+        return 1
+
+    gate_mode = False
+    args = sys.argv[1:]
+    if args and args[0] == "--gate":
+        gate_mode = True
+        args = args[1:]
+    if not args:
+        print("Usage: analyze_proof_results.py [--gate] <proof-json>", file=sys.stderr)
+        return 1
+
+    path = Path(args[0])
+    if not path.is_file():
+        print(f"File not found: {path}", file=sys.stderr)
+        return 1
+
+    if gate_mode:
+        return check_gate(path)
+    return summarize(path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+
+FAIL_STATUSES = {"missing", "stateful"}
+
+
+def summarize(path: Path) -> int:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    summary = data.get("summary", {})
+    screens = data.get("screens", [])
+    print(f"route_gap_file={path}")
+    print(f"service={data.get('service', 'unknown')}")
+    print(f"total={summary.get('total', 0)}")
+    print(f"direct={summary.get('direct', 0)}")
+    print(f"shared={summary.get('shared', 0)}")
+    print(f"stateful={summary.get('stateful', 0)}")
+    print(f"missing={summary.get('missing', 0)}")
+    for row in screens:
+        if isinstance(row, dict) and row.get("status") in FAIL_STATUSES:
+            print(f"- {row.get('id', 'unknown')}: {row.get('status')}")
+    return 0
+
+
+def check_gate(path: Path) -> int:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    summary = data.get("summary")
+    screens = data.get("screens")
+    if not isinstance(summary, dict):
+        print("route_gap_gate=fail reason=missing_summary")
+        return 2
+    if not isinstance(screens, list):
+        print("route_gap_gate=fail reason=missing_screens")
+        return 2
+
+    failing_rows = []
+    for row in screens:
+        if not isinstance(row, dict):
+            failing_rows.append(("unknown", "invalid_row"))
+            continue
+        status = str(row.get("status", "")).strip().lower()
+        identifier = row.get("id") or row.get("title") or "unknown"
+        if status in FAIL_STATUSES:
+            failing_rows.append((identifier, status))
+
+    if failing_rows or int(summary.get("missing", 0) or 0) > 0 or int(summary.get("stateful", 0) or 0) > 0:
+        print("route_gap_gate=fail")
+        print(f"summary_missing={summary.get('missing', 0)}")
+        print(f"summary_stateful={summary.get('stateful', 0)}")
+        for identifier, status in failing_rows[:20]:
+            print(f"- {identifier}: {status}")
+        return 2
+
+    print("route_gap_gate=pass")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: analyze_route_gap.py [--gate] <route-gap-json>", file=sys.stderr)
+        return 1
+
+    gate_mode = False
+    args = sys.argv[1:]
+    if args and args[0] == "--gate":
+        gate_mode = True
+        args = args[1:]
+    if not args:
+        print("Usage: analyze_route_gap.py [--gate] <route-gap-json>", file=sys.stderr)
+        return 1
+
+    path = Path(args[0])
+    if not path.is_file():
+        print(f"File not found: {path}", file=sys.stderr)
+        return 1
+
+    if gate_mode:
+        return check_gate(path)
+    return summarize(path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/sdd/99_toolchain/01_automation/agentic-dev/assets/repo-contract.template.json

@@ -0,0 +1,75 @@
+{
+  "schema_version": 1,
+  "name": "replace-service-name",
+  "spec": {
+    "planning_paths": [
+      "sdd/01_planning",
+      "sdd/02_plan"
+    ],
+    "canonical_targets_dir": "sdd/02_plan"
+  },
+  "frontend": {
+    "default_target": "platform",
+    "targets": {
+      "platform": {
+        "dir": "client/platform",
+        "adapter_path": "client/platform/scripts/ui-parity-platform-adapter.mjs",
+        "screens_path": "client/platform/src/lib/specScreens.json",
+        "routes_path": "client/platform/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4301",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_platform_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_platform_agentic_dev_latest.json"
+      },
+      "mobile": {
+        "dir": "client/mobile",
+        "adapter_path": "client/mobile/scripts/ui-parity-mobile-adapter.mjs",
+        "screens_path": "client/mobile/src/lib/specScreens.json",
+        "routes_path": "client/mobile/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4302",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_mobile_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_mobile_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_mobile_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_mobile_agentic_dev_latest.json"
+      },
+      "admin": {
+        "dir": "client/admin",
+        "adapter_path": "client/admin/scripts/ui-parity-admin-adapter.mjs",
+        "screens_path": "client/admin/src/lib/specScreens.json",
+        "routes_path": "client/admin/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4400",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_admin_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_admin_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_admin_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_admin_agentic_dev_latest.json"
+      },
+      "landing": {
+        "dir": "client/landing",
+        "adapter_path": "client/landing/scripts/ui-parity-landing-adapter.mjs",
+        "screens_path": "client/landing/src/lib/specScreens.json",
+        "routes_path": "client/landing/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4300",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_landing_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_landing_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_landing_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_landing_agentic_dev_latest.json"
+      }
+    }
+  },
+  "commands": {
+    "plan_audit": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh route_gap .",
+    "build": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh build .",
+    "proof": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh proof .",
+    "deploy_dev": "echo 'replace deploy_dev command' >&2",
+    "verify_dev": "echo 'replace verify_dev command' >&2"
+  },
+  "artifacts": {
+    "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.json",
+    "proof_output": "sdd/04_verify/10_test/ui_parity/replace_agentic_dev_latest.json"
+  },
+  "notes": [
+    "Replace the commands and proof output path after cloning the template.",
+    "plan_audit is expected to generate and gate a route-gap report before proof."
+  ]
+}

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: bootstrap_frontend_parity.sh [repo_root] [target]
+
+Run first-time frontend parity bootstrap for a cloned template.
+
+Steps:
+  1. init repo contract and route-gap assets
+  2. build frontend
+  3. start preview server
+  4. materialize reference assets
+  5. run plan_audit gate
+  6. run proof gate
+EOF
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+repo_root="$(cd "${1:-$(pwd)}" && pwd)"
+frontend_target="${2:-}"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+target_payload="$(python3 "${script_dir}/resolve_frontend_target.py" "${repo_root}" "${frontend_target}")"
+read_target_value() {
+  local key="$1"
+  python3 - "${target_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 value is None:
+    raise SystemExit(1)
+print(value if isinstance(value, str) else json.dumps(value, ensure_ascii=False))
+PY
+}
+target_name="$(read_target_value "name")"
+target_dir="$(read_target_value "target.dir")"
+preview_url="$(read_target_value "target.preview_url")"
+preview_log="${repo_root}/sdd/04_verify/10_test/ui_parity/${target_name}-preview.log"
+preview_pid=""
+
+cleanup() {
+  if [[ -n "${preview_pid}" ]] && kill -0 "${preview_pid}" >/dev/null 2>&1; then
+    kill "${preview_pid}" >/dev/null 2>&1 || true
+    wait "${preview_pid}" >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+bash "${script_dir}/init_frontend_parity.sh" "${repo_root}" "${frontend_target}"
+
+cd "${repo_root}"
+mkdir -p "$(dirname "${preview_log}")"
+bash "${script_dir}/run_frontend_target.sh" build "${repo_root}" "${frontend_target}"
+npm --prefix "${target_dir}" run preview >"${preview_log}" 2>&1 &
+preview_pid="$!"
+for _ in $(seq 1 30); do
+  if curl -fsS "${preview_url}" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+if ! curl -fsS "${preview_url}" >/dev/null 2>&1; then
+  echo "Preview server did not become ready: ${preview_url}" >&2
+  echo "Preview log: ${preview_log}" >&2
+  exit 1
+fi
+bash "${script_dir}/run_frontend_target.sh" materialize_references "${repo_root}" "${frontend_target}"
+
+bash "${script_dir}/run_repo_phase.sh" plan_audit "${repo_root}" "${frontend_target}"
+bash "${script_dir}/run_repo_phase.sh" proof "${repo_root}" "${frontend_target}"
+
+echo "frontend_parity_bootstrap=ok"

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: init_frontend_parity.sh [repo_root] [target]
+
+Bootstrap repo-local frontend parity assets for a cloned template.
+
+Steps:
+  1. Ensure repo contract aliases exist
+  2. Scaffold ui parity contract
+  3. Generate route-gap json/markdown manifests
+
+Optional runtime steps such as reference materialization and proof are intentionally excluded.
+EOF
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+repo_root="$(cd "${1:-$(pwd)}" && pwd)"
+frontend_target="${2:-}"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+bash "${script_dir}/init_repo_contract.sh" "${repo_root}" >/dev/null
+
+bash "${script_dir}/run_frontend_target.sh" scaffold "${repo_root}" "${frontend_target}"
+bash "${script_dir}/run_frontend_target.sh" route_gap "${repo_root}" "${frontend_target}"
+
+echo "frontend_parity_init=ok"

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: init_repo_contract.sh [repo_root]
+
+Create the canonical toolchain contract if it does not exist.
+Also create runtime-friendly aliases:
+  - .codex/agentic-dev.json
+  - .claude/agentic-dev.json
+Print the resulting canonical contract path.
+EOF
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+repo_root="$(cd "${1:-$(pwd)}" && pwd)"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+template_path="${script_dir}/assets/repo-contract.template.json"
+contract_path="${repo_root}/sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json"
+codex_dir="${repo_root}/.codex"
+claude_dir="${repo_root}/.claude"
+codex_alias_path="${codex_dir}/agentic-dev.json"
+claude_alias_path="${claude_dir}/agentic-dev.json"
+
+if [[ ! -f "${template_path}" ]]; then
+  echo "Template not found: ${template_path}" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "${contract_path}")" "${codex_dir}" "${claude_dir}"
+if [[ ! -f "${contract_path}" ]]; then
+  cp "${template_path}" "${contract_path}"
+fi
+
+python3 - "${codex_alias_path}" "${claude_alias_path}" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+payload = {"contract_path": "../sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json"}
+for raw_path in sys.argv[1:]:
+    path = Path(raw_path)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+PY
+
+printf '%s\n' "${contract_path}"

package/sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json

@@ -0,0 +1,76 @@
+{
+  "schema_version": 1,
+  "name": "templates-frontends",
+  "spec": {
+    "planning_paths": [
+      "sdd/01_planning",
+      "sdd/02_plan"
+    ],
+    "canonical_targets_dir": "sdd/02_plan"
+  },
+  "frontend": {
+    "default_target": "platform",
+    "targets": {
+      "platform": {
+        "dir": "client/platform",
+        "adapter_path": "client/platform/scripts/ui-parity-platform-adapter.mjs",
+        "screens_path": "client/platform/src/lib/specScreens.json",
+        "routes_path": "client/platform/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4301",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_platform_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_platform_agentic_dev_latest.json"
+      },
+      "mobile": {
+        "dir": "client/mobile",
+        "adapter_path": "client/mobile/scripts/ui-parity-mobile-adapter.mjs",
+        "screens_path": "client/mobile/src/lib/specScreens.json",
+        "routes_path": "client/mobile/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4302",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_mobile_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_mobile_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_mobile_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_mobile_agentic_dev_latest.json"
+      },
+      "admin": {
+        "dir": "client/admin",
+        "adapter_path": "client/admin/scripts/ui-parity-admin-adapter.mjs",
+        "screens_path": "client/admin/src/lib/specScreens.json",
+        "routes_path": "client/admin/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4400",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_admin_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_admin_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_admin_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_admin_agentic_dev_latest.json"
+      },
+      "landing": {
+        "dir": "client/landing",
+        "adapter_path": "client/landing/scripts/ui-parity-landing-adapter.mjs",
+        "screens_path": "client/landing/src/lib/specScreens.json",
+        "routes_path": "client/landing/src/lib/specRouteCatalog.json",
+        "preview_url": "http://127.0.0.1:4300",
+        "parity_contract_path": "sdd/02_plan/10_test/templates/ui_parity_landing_contract.yaml",
+        "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_landing_route_gap_report.json",
+        "route_gap_markdown_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_landing_route_gap_report.md",
+        "proof_output": "sdd/04_verify/10_test/ui_parity/templates_landing_agentic_dev_latest.json"
+      }
+    }
+  },
+  "commands": {
+    "plan_audit": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh route_gap .",
+    "build": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh build .",
+    "proof": "bash sdd/99_toolchain/01_automation/agentic-dev/run_frontend_target.sh proof .",
+    "deploy_dev": "echo 'configure deploy_dev command in sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json for the cloned service' >&2",
+    "verify_dev": "test -f \"$PWD/sdd/04_verify/10_test/ui_parity/templates_platform_agentic_dev_latest.json\" && echo verify-dev-placeholder-ok"
+  },
+  "artifacts": {
+    "route_gap_output": "sdd/02_plan/99_generated/from_planning/ui_parity/ui_parity_platform_route_gap_report.json",
+    "proof_output": "sdd/04_verify/10_test/ui_parity/templates_platform_agentic_dev_latest.json"
+  },
+  "notes": [
+    "This template contract is intentionally self-contained and points at repo-local 99_toolchain automation.",
+    "Replace deploy_dev and verify_dev with service-specific DEV commands after cloning the template.",
+    "plan_audit is expected to generate and gate a route-gap report before proof."
+  ]
+}

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+from resolve_repo_contract import resolve_repo_contract_path
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: resolve_frontend_target.py <repo_root> [target]", file=sys.stderr)
+        return 1
+
+    repo_root = Path(sys.argv[1]).resolve()
+    target_name = sys.argv[2].strip() if len(sys.argv) > 2 and sys.argv[2].strip() else None
+    contract_path = resolve_repo_contract_path(repo_root)
+    if contract_path is None:
+        print("Frontend contract not found via .codex/.claude/toolchain contract search order.", file=sys.stderr)
+        return 1
+
+    contract = json.loads(contract_path.read_text(encoding="utf-8"))
+    frontend = contract.get("frontend")
+    if not isinstance(frontend, dict):
+        print(f"Missing frontend block in {contract_path}", file=sys.stderr)
+        return 1
+
+    default_target = frontend.get("default_target")
+    targets = frontend.get("targets")
+    if not isinstance(default_target, str) or not default_target.strip():
+        print(f"Missing frontend.default_target in {contract_path}", file=sys.stderr)
+        return 1
+    if not isinstance(targets, dict):
+        print(f"Missing frontend.targets in {contract_path}", file=sys.stderr)
+        return 1
+
+    selected = target_name or default_target
+    target = targets.get(selected)
+    if not isinstance(target, dict):
+        print(f"Unknown frontend target: {selected}", file=sys.stderr)
+        return 1
+
+    payload = {
+        "name": selected,
+        "default_target": default_target,
+        "target": target,
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+
+SEARCH_ORDER = (
+    ".codex/agentic-dev.json",
+    ".claude/agentic-dev.json",
+    "sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json",
+)
+
+
+def candidate_paths(start: Path):
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    for base in (current, *current.parents):
+        for rel in SEARCH_ORDER:
+            yield base / rel
+
+
+def resolve_pointer(path: Path) -> Path:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    target = data.get("contract_path")
+    if isinstance(target, str) and target.strip():
+        resolved = (path.parent / target).resolve()
+        if not resolved.is_file():
+            raise FileNotFoundError(f"contract_path target not found: {resolved}")
+        return resolved
+    return path.resolve()
+
+
+def resolve_repo_contract_path(start: Path) -> Path | None:
+    for path in candidate_paths(start):
+        if path.is_file():
+            return resolve_pointer(path)
+    return None
+
+
+def main() -> int:
+    start = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    resolved = resolve_repo_contract_path(start)
+    if resolved is not None:
+        print(resolved)
+        return 0
+    print(
+        "No repo contract found. Checked .codex/agentic-dev.json, "
+        ".claude/agentic-dev.json, sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json in current and parent directories.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())