modify template

Coding/Codex-cpp/.codex/config.toml

@@ -1,5 +1,4 @@
 #:schema https://developers.openai.com/codex/config-schema.json
 
 [features]
-hooks = true
- 
+codex_hooks = true

Coding/Codex-cpp/.codex/hooks/pre_commit_checks.py

@@ -0,0 +1,89 @@
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _repo_root(cwd: Path) -> Path:
+    try:
+        root = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return cwd
+    return Path(root)
+
+
+def _is_git_commit(command: str) -> bool:
+    return re.search(
+        r"^\s*git(?:\s+(?:-[A-Za-z]\s+\S+|--[A-Za-z0-9-]+(?:=\S+)?))*\s+commit\b",
+        command,
+    ) is not None
+
+
+def _deny(reason: str) -> None:
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+    )
+
+
+def _tail(text: str, limit: int = 1200) -> str:
+    text = text.strip()
+    if len(text) <= limit:
+        return text
+    return text[-limit:]
+
+
+def _build_pre_commit_commands(root: Path) -> list[list[str]]:
+    return [
+        [sys.executable, "-m", "unittest", "discover", "-s", "scripts", "-p", "test_*.py"],
+        [sys.executable, "scripts/validate_workspace.py"],
+    ]
+
+
+def _run_checks(root: Path) -> str | None:
+    for command in _build_pre_commit_commands(root):
+        result = subprocess.run(command, cwd=root, capture_output=True, text=True)
+        if result.returncode != 0:
+            details = _tail(result.stdout + "\n" + result.stderr)
+            label = " ".join(command)
+            if details:
+                return f"{label} failed:\n{details}"
+            return f"{label} failed with exit code {result.returncode}."
+
+    return None
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return 0
+
+    command = payload.get("tool_input", {}).get("command", "")
+    if not isinstance(command, str) or not _is_git_commit(command):
+        return 0
+
+    cwd = Path(payload.get("cwd") or Path.cwd())
+    root = _repo_root(cwd)
+    failure = _run_checks(root)
+    if failure:
+        _deny(f"PRE-COMMIT CHECKS: {failure}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Coding/Codex-cpp/.codex/hooks/tdd-guard.py

@@ -0,0 +1,205 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+SOURCE_SUFFIXES = {".h", ".hpp", ".hh", ".hxx", ".c", ".cc", ".cpp", ".cxx", ".ixx"}
+TEST_SUFFIXES = {".h", ".hpp", ".hh", ".hxx", ".c", ".cc", ".cpp", ".cxx", ".ixx"}
+CONFIG_SUFFIXES = {".json", ".md", ".yml", ".yaml", ".txt", ".cmake"}
+
+
+def _repo_root(cwd: Path) -> Path:
+    try:
+        root = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return cwd
+    return Path(root)
+
+
+def _extract_patch_paths(command: str) -> list[str]:
+    prefixes = (
+        "*** Add File: ",
+        "*** Update File: ",
+        "*** Delete File: ",
+        "*** Move to: ",
+    )
+    paths: list[str] = []
+    for raw_line in command.splitlines():
+        line = raw_line.strip()
+        for prefix in prefixes:
+            if line.startswith(prefix):
+                paths.append(line[len(prefix) :].strip())
+                break
+    return paths
+
+
+def _touched_paths(payload: dict) -> list[str]:
+    tool_input = payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return []
+
+    file_path = tool_input.get("file_path")
+    if isinstance(file_path, str) and file_path:
+        return [file_path]
+
+    command = tool_input.get("command")
+    if isinstance(command, str):
+        return _extract_patch_paths(command)
+
+    return []
+
+
+def _normalize(path_text: str) -> str:
+    return path_text.replace("\\", "/").lower()
+
+
+def _is_test_path(path_text: str) -> bool:
+    normalized = _normalize(path_text)
+    name = normalized.rsplit("/", 1)[-1]
+    path = Path(path_text)
+    return (
+        "/tests/" in f"/{normalized}"
+        or "/test/" in f"/{normalized}"
+        or name.endswith("_test.cpp")
+        or name.startswith("test_")
+        or ".test." in name
+        or ".spec." in name
+    ) and path.suffix.lower() in TEST_SUFFIXES
+
+
+def _token(text: str) -> str:
+    return "".join(ch for ch in text.lower() if ch.isalnum())
+
+
+def _module_token(path: Path) -> str:
+    parts = [part.lower() for part in path.parts]
+    for marker in ("include", "src"):
+        if marker not in parts:
+            continue
+        idx = parts.index(marker)
+        if marker == "include" and idx + 2 < len(parts) and parts[idx + 1] == "fesa":
+            return _token(parts[idx + 2])
+        if marker == "src" and idx + 1 < len(parts):
+            return _token(parts[idx + 1])
+    return ""
+
+
+def _related_tokens(path: Path) -> set[str]:
+    tokens = {_token(_base_name(path))}
+    module = _module_token(path)
+    if module:
+        tokens.add(module)
+    return {token for token in tokens if token}
+
+
+def _candidate_test_paths(paths: list[str], cwd: Path, root: Path) -> list[Path]:
+    candidates: list[Path] = []
+    for path_text in paths:
+        resolved = _resolve_path(path_text, cwd)
+        if _is_test_path(str(resolved)):
+            candidates.append(resolved)
+
+    for test_root_name in ("tests", "test"):
+        test_root = root / test_root_name
+        if not test_root.is_dir():
+            continue
+        for suffix in TEST_SUFFIXES:
+            candidates.extend(test_root.rglob(f"*{suffix}"))
+
+    return candidates
+
+
+def _has_related_test(path: Path, candidate_tests: list[Path]) -> bool:
+    tokens = _related_tokens(path)
+    for test_path in candidate_tests:
+        test_token = _token(test_path.stem)
+        if any(token and token in test_token for token in tokens):
+            return True
+    return False
+
+
+def _is_exempt(path_text: str) -> bool:
+    normalized = _normalize(path_text)
+    path = Path(path_text)
+    name = path.name.lower()
+
+    if name == "cmakelists.txt":
+        return True
+    if _is_test_path(path_text):
+        return True
+    if path.suffix.lower() in CONFIG_SUFFIXES:
+        return True
+    if "/cmake/" in normalized:
+        return True
+
+    return False
+
+
+def _resolve_path(path_text: str, cwd: Path) -> Path:
+    path = Path(path_text)
+    if path.is_absolute():
+        return path
+    return (cwd / path).resolve()
+
+
+def _base_name(path: Path) -> str:
+    for suffix in sorted(SOURCE_SUFFIXES, key=len, reverse=True):
+        if path.name.lower().endswith(suffix):
+            return path.name[: -len(suffix)]
+    return path.stem
+
+
+def _guarded_paths(paths: list[str], cwd: Path, root: Path) -> list[str]:
+    missing_tests: list[str] = []
+    candidate_tests = _candidate_test_paths(paths, cwd, root)
+    for path_text in paths:
+        if _is_exempt(path_text):
+            continue
+
+        path = _resolve_path(path_text, cwd)
+        if path.suffix.lower() not in SOURCE_SUFFIXES:
+            continue
+        if not _has_related_test(path, candidate_tests):
+            missing_tests.append(_base_name(path))
+
+    return missing_tests
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return 0
+
+    cwd = Path(payload.get("cwd") or Path.cwd())
+    root = _repo_root(cwd)
+    missing_tests = _guarded_paths(_touched_paths(payload), cwd, root)
+    if not missing_tests:
+        return 0
+
+    names = ", ".join(sorted(set(missing_tests)))
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": (
+                        "TDD GUARD: missing test file for "
+                        f"{names}. Write or add the test first."
+                    ),
+                }
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Coding/Codex-cpp/.codex/skills/harness-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: harness-review
+description: Use when reviewing this C++/MSVC Harness repository: local changes, generated phase files, step outputs, implementation diffs, missing tests, MSVC build readiness, or compliance with AGENTS.md, docs/ARCHITECTURE.md, docs/ADR.md, and Harness acceptance criteria.
+---
+
+# Harness Review
+
+## Overview
+
+Use this skill to review Harness work against the repository's persistent rules, architecture docs, C++/MSVC constraints, TDD guard policy, and executable verification requirements. Prioritize bugs, regressions, missing tests, and rule violations.
+
+## Review Process
+
+1. Read `/AGENTS.md`, `/docs/ARCHITECTURE.md`, and `/docs/ADR.md`.
+2. Inspect the changed files with `git status --short` and `git diff`.
+3. Check architecture, stack choices, C++ test coverage, critical rules, and MSVC/CMake readiness.
+4. Run relevant verification commands when feasible. If a command cannot be run, report that as residual risk.
+5. Lead with actionable findings. Keep summaries secondary.
+
+## Checklist
+
+| Item | Question |
+| --- | --- |
+| Architecture | Does the change follow `docs/ARCHITECTURE.md` ownership boundaries? |
+| Stack | Does the change stay within C++/MSVC/CMake decisions documented in `docs/ADR.md`? |
+| Tests | Are new or changed behaviors covered by Python Harness tests or C++ tests? |
+| TDD Guard | Would C++ production edits be blocked without related tests? |
+| Critical Rules | Does the change violate any `AGENTS.md` CRITICAL rule? |
+| Build | Do `python -m unittest discover -s scripts -p "test_*.py"` and `python scripts/validate_workspace.py` pass or provide an expected no-CMake message? |
+
+## Output Format
+
+If there are findings, list them first in severity order with file and line references when possible. Then include this table:
+
+| 항목 | 결과 | 비고 |
+| --- | --- | --- |
+| 아키텍처 준수 | PASS/FAIL | {상세} |
+| 기술 스택 준수 | PASS/FAIL | {상세} |
+| 테스트 존재 | PASS/FAIL | {상세} |
+| TDD Guard | PASS/FAIL | {상세} |
+| CRITICAL 규칙 | PASS/FAIL | {상세} |
+| 빌드/검증 가능 | PASS/FAIL | {상세} |
+
+When there are no findings, say that clearly, then mention any commands not run or remaining risk.

Coding/Codex-cpp/.codex/skills/harness-workflow/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: harness-workflow
+description: Use when planning or running this C++/MSVC Harness framework: reading AGENTS.md and docs/*.md, discussing implementation scope, creating or updating phases/index.json, phases/{task}/index.json, phases/{task}/stepN.md, or invoking scripts/execute.py for staged Codex execution.
+---
+
+# Harness Workflow
+
+## Overview
+
+Use this skill to turn a user-approved task into small, self-contained Harness steps that another Codex session can execute reliably. Keep every step grounded in repository docs, C++/MSVC constraints, TDD, and executable acceptance criteria.
+
+## Workflow
+
+1. Read `AGENTS.md` and relevant files under `docs/`, especially `docs/PRD.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
+2. Discuss unresolved product or technical decisions with the user before writing phase files.
+3. When the user asks for an implementation plan, draft steps and get approval before creating files.
+4. Create or update `phases/index.json`, `phases/{task-name}/index.json`, and one `phases/{task-name}/stepN.md` per step.
+5. Run the phase with `python scripts/execute.py {task-name}` when asked to execute it. Use `--push` only when the user asks to push.
+
+## Step Design Rules
+
+- Scope each step to one layer or module. Split steps when multiple modules would otherwise change together.
+- Make every step self-contained. Do not rely on prior conversation; include all required context and file paths.
+- Force context gathering. Each step must tell Codex which docs and previous outputs to read before editing.
+- Specify interfaces and signatures, not full implementations, unless exact code is required for a constraint.
+- Put core invariants directly in the step: idempotency, numerical conventions, data integrity, API contracts, or other non-negotiables.
+- Use executable acceptance criteria such as `python scripts/validate_workspace.py`, not abstract statements.
+- For C++ behavior changes, require tests first and name the expected test file or test executable.
+- Name steps with kebab-case slugs such as `project-setup`, `core-types`, or `solver-validation`.
+
+## Phase Files
+
+Create or update `phases/index.json`:
+
+```json
+{
+  "phases": [
+    {
+      "dir": "0-mvp",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+Create `phases/{task-name}/index.json`:
+
+```json
+{
+  "project": "FESA Harness",
+  "phase": "<task-name>",
+  "steps": [
+    { "step": 0, "name": "project-setup", "status": "pending" },
+    { "step": 1, "name": "core-types", "status": "pending" },
+    { "step": 2, "name": "validation-path", "status": "pending" }
+  ]
+}
+```
+
+Rules:
+
+- `project` comes from `AGENTS.md`.
+- `phase` matches the task directory name.
+- `steps[].step` starts at `0`.
+- Initial status is always `pending`.
+- Do not add timestamps when creating files. `scripts/execute.py` records `created_at`, `started_at`, `completed_at`, `failed_at`, and `blocked_at`.
+
+## Step Template
+
+```markdown
+# Step {N}: {name}
+
+## 읽어야 할 파일
+
+먼저 아래 파일들을 읽고 프로젝트의 아키텍처와 설계 의도를 파악하라:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- {previously created or modified files}
+
+이전 step에서 만들어진 코드를 꼼꼼히 읽고, 설계 의도를 이해한 뒤 작업하라.
+
+## 작업
+
+{Concrete instructions with file paths, interfaces, signatures, and rules.}
+
+## Tests To Write First
+
+- {Exact C++ or Python test file and behavior to add before implementation.}
+
+## Acceptance Criteria
+
+```bash
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## 검증 절차
+
+1. 위 AC 커맨드를 실행한다.
+2. 아키텍처 체크리스트를 확인한다:
+   - ARCHITECTURE.md 디렉토리 구조를 따르는가?
+   - ADR 기술 스택을 벗어나지 않았는가?
+   - AGENTS.md CRITICAL 규칙을 위반하지 않았는가?
+   - C++ 변경에는 관련 테스트가 존재하는가?
+3. 결과에 따라 `phases/{task-name}/index.json`의 해당 step을 업데이트한다:
+   - 성공: `"status": "completed"`, `"summary": "산출물 한 줄 요약"`
+   - 3회 수정 시도 후 실패: `"status": "error"`, `"error_message": "구체적 에러 내용"`
+   - 사용자 개입 필요: `"status": "blocked"`, `"blocked_reason": "구체적 사유"` 후 중단
+
+## 금지사항
+
+- JavaScript/TypeScript/npm fallback을 추가하지 마라. Reason: 이 Harness는 C++/MSVC 전용이다.
+- 기존 테스트를 깨뜨리지 마라.
+```
+
+## Execution And Recovery
+
+Run:
+
+```bash
+python scripts/execute.py {task-name}
+python scripts/execute.py {task-name} --push
+```
+
+`scripts/execute.py` creates or checks out `feat-{task-name}`, injects `AGENTS.md` and `docs/*.md` into each prompt, carries completed step summaries forward, retries failed steps up to three times, separates code and metadata commits, and records timestamps.
+
+If a step is `error`, set it back to `pending` and remove `error_message` after fixing the cause. If a step is `blocked`, resolve `blocked_reason`, set it back to `pending`, remove `blocked_reason`, and rerun.

Coding/Codex-cpp/.gitignore

@@ -0,0 +1,23 @@
+.vs/
+build/
+out/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+CTestTestfile.cmake
+Testing/
+*.vcxproj.user
+*.obj
+*.pdb
+*.ilk
+*.exe
+*.dll
+*.lib
+*.exp
+*.log
+__pycache__/
+*.pyc
+
+# phase execution outputs
+phases/**/phase*-output.json
+phases/**/step*-output.json

Coding/Codex-cpp/AGENTS.md

@@ -0,0 +1,44 @@
+# Project: FESA Harness
+
+## 기술 스택
+- C++17 이상
+- MSVC on Windows
+- CMake + CTest
+- Harness scripts in Python 3
+
+## 아키텍처 규칙
+- CRITICAL: 기본 검증 경로는 `python scripts/validate_workspace.py`이다.
+- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
+- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
+- CRITICAL: Abaqus reference artifact나 solver 코드 복원은 명시적으로 요청된 phase에서만 수행한다.
+- Harness runner는 `scripts/execute.py`에 둔다.
+- Codex hook 정책은 `.codex/hooks/`에 둔다.
+- Harness planning/review instructions are stored in `.codex/skills/`.
+- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.
+
+## 개발 프로세스
+- TDD를 기본으로 한다. C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
+- 커밋 전 hook은 Harness Python self-test와 workspace validation을 실행해야 한다.
+- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
+- 계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.
+
+## 명령어
+```bash
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+python scripts/execute.py <phase-dir>
+python scripts/execute.py <phase-dir> --push
+```
+
+## MSVC 검증 기본값
+- Generator: `Visual Studio 17 2022`
+- Platform: `x64`
+- Config: `Debug`
+- Build directory: `build/msvc-debug`
+
+Override variables:
+- `HARNESS_VALIDATION_COMMANDS`
+- `HARNESS_CMAKE_GENERATOR`
+- `HARNESS_CMAKE_PLATFORM`
+- `HARNESS_CMAKE_CONFIG`
+- `HARNESS_BUILD_DIR`

Coding/Codex-cpp/docs/ADR.md

@@ -0,0 +1,34 @@
+# Architecture Decision Records
+
+## 철학
+Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. C++/MSVC 프로젝트에서 npm, Next.js, TypeScript test naming을 기본값으로 두면 agent prompt와 hook policy가 잘못된 구현을 유도한다.
+
+---
+
+### ADR-001: C++ 전용 Harness
+**결정**: Harness scaffold는 C++/MSVC 전용으로 운영한다. JavaScript/TypeScript fallback은 유지하지 않는다.
+
+**이유**: FESA 개발 환경은 MSVC 기반 C++이다. 언어별 fallback을 남기면 validation, TDD guard, acceptance criteria가 흐려진다.
+
+**트레이드오프**: 같은 Harness scaffold를 JS/TS 프로젝트에 재사용할 수 없다. 필요하면 별도 template이나 language registry를 새 ADR로 설계한다.
+
+### ADR-002: CMake/MSVC/x64/Debug 기본 검증
+**결정**: 기본 workspace validation은 CMake, Visual Studio 17 2022 generator, x64 platform, Debug config, CTest로 수행한다.
+
+**이유**: MSVC 환경에서 CMake/CTest는 source tree가 복원되거나 새 C++ project가 추가될 때 가장 일관된 build/test entry point다.
+
+**트레이드오프**: Visual Studio solution-only project는 기본 지원하지 않는다. 명시적으로 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
+
+### ADR-003: 엄격한 C++ TDD Guard
+**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다.
+
+**이유**: Harness의 핵심 목적은 agent가 검증 없는 C++ 변경을 만들지 않도록 하는 것이다. Header 중심 C++ 구조에서도 module 또는 basename 기반 테스트 존재를 확인한다.
+
+**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
+
+### ADR-004: Harness 자체 테스트 우선
+**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 workspace validation을 실행한다.
+
+**이유**: 현재 저장소에는 C++ source tree가 없을 수 있다. Harness가 스스로 검증 가능해야 이후 phase generation과 source restoration을 안전하게 진행할 수 있다.
+
+**트레이드오프**: commit 시간이 조금 늘어난다. 대신 hook/validation regressions를 빠르게 잡는다.

Coding/Codex-cpp/docs/ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# 아키텍처
+
+## 목표
+이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.
+
+## 디렉토리 구조
+```text
+.codex/
+├── hooks/              # Codex hook scripts
+└── skills/             # Harness planning/review instructions
+docs/                   # Project and Harness guidance
+scripts/
+├── execute.py          # Phase step executor
+├── validate_workspace.py
+└── test_*.py           # Harness self-tests
+phases/                 # Optional generated phase plans
+```
+
+## 데이터 흐름
+```text
+User-approved task
+-> Harness phase files under phases/
+-> scripts/execute.py injects AGENTS.md and docs/*.md
+-> Codex executes one step at a time
+-> step updates phases/{phase}/index.json
+-> validation runs through scripts/validate_workspace.py
+```
+
+## Hook 흐름
+```text
+apply_patch/Edit/Write
+-> .codex/hooks/tdd-guard.py
+-> C++ production changes require related tests
+
+git commit command
+-> .codex/hooks/pre_commit_checks.py
+-> Python Harness self-tests
+-> scripts/validate_workspace.py
+```
+
+## Validation 흐름
+```text
+HARNESS_VALIDATION_COMMANDS set
+-> run exact commands
+
+CMakePresets.json has msvc-debug configure preset
+-> cmake --preset msvc-debug
+-> cmake --build preset binary dir --config Debug
+-> ctest --test-dir preset binary dir -C Debug
+
+CMakeLists.txt exists
+-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
+-> cmake --build build/msvc-debug --config Debug
+-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug
+
+No CMake project
+-> print guidance and exit successfully
+```

Coding/Codex-cpp/docs/PRD.md

@@ -0,0 +1,22 @@
+# PRD: C++/MSVC Harness
+
+## 목표
+Codex Harness가 C++/MSVC 프로젝트에서 phase planning, TDD guard, commit validation, workspace validation을 일관되게 수행하게 한다.
+
+## 사용자
+- Windows/MSVC 기반 C++ 개발자
+- Harness phase를 작성하고 실행하는 Codex agent
+- Harness 결과를 검토하는 reviewer
+
+## 핵심 기능
+1. CMake/MSVC/x64/Debug 기반 workspace validation
+2. C++ source/header 변경에 대한 엄격한 TDD guard
+3. npm 없이 Python self-test와 CMake/CTest 검증을 수행하는 pre-commit hook
+4. C++ 프로젝트에 맞는 Harness workflow/review prompt
+5. CMake project가 아직 없어도 Harness 자체 테스트가 가능한 no-op validation path
+
+## 제외 사항
+- 이전 FESA solver source tree 복원
+- JavaScript/TypeScript fallback 유지
+- Abaqus reference artifact 생성 또는 solver reference 비교 구현
+- Visual Studio `.sln`/`.vcxproj` 전용 MSBuild workflow

Coding/Codex-cpp/scripts/test_pre_commit_checks.py

@@ -0,0 +1,41 @@
+import importlib.util
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def load_pre_commit_checks():
+    module_path = Path(__file__).resolve().parent.parent / ".codex" / "hooks" / "pre_commit_checks.py"
+    spec = importlib.util.spec_from_file_location("pre_commit_checks", module_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class PreCommitChecksTests(unittest.TestCase):
+    def test_git_commit_runs_python_self_tests_and_workspace_validation(self):
+        pre_commit_checks = load_pre_commit_checks()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            commands = pre_commit_checks._build_pre_commit_commands(root)
+
+        self.assertEqual(
+            commands,
+            [
+                [sys.executable, "-m", "unittest", "discover", "-s", "scripts", "-p", "test_*.py"],
+                [sys.executable, "scripts/validate_workspace.py"],
+            ],
+        )
+        self.assertFalse(any("npm" in part.lower() for command in commands for part in command))
+
+    def test_only_git_commit_commands_trigger_checks(self):
+        pre_commit_checks = load_pre_commit_checks()
+        self.assertTrue(pre_commit_checks._is_git_commit('git commit -m "change"'))
+        self.assertTrue(pre_commit_checks._is_git_commit('git -c core.editor=true commit -m "change"'))
+        self.assertFalse(pre_commit_checks._is_git_commit("git status --short"))
+        self.assertFalse(pre_commit_checks._is_git_commit("echo git commit"))
+
+
+if __name__ == "__main__":
+    unittest.main()

Coding/Codex-cpp/scripts/test_tdd_guard.py

@@ -0,0 +1,61 @@
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def load_tdd_guard():
+    module_path = Path(__file__).resolve().parent.parent / ".codex" / "hooks" / "tdd-guard.py"
+    spec = importlib.util.spec_from_file_location("tdd_guard", module_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class CppTddGuardTests(unittest.TestCase):
+    def test_cpp_production_file_without_related_test_is_blocked(self):
+        tdd_guard = load_tdd_guard()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            source = root / "include" / "fesa" / "Core" / "DofManager.hpp"
+            source.parent.mkdir(parents=True)
+            source.write_text("#pragma once\n", encoding="utf-8")
+
+            self.assertEqual(tdd_guard._guarded_paths([str(source)], root, root), ["DofManager"])
+
+    def test_cpp_production_file_with_module_test_is_allowed(self):
+        tdd_guard = load_tdd_guard()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            source = root / "include" / "fesa" / "Core" / "DofManager.hpp"
+            source.parent.mkdir(parents=True)
+            source.write_text("#pragma once\n", encoding="utf-8")
+            tests_dir = root / "tests"
+            tests_dir.mkdir()
+            (tests_dir / "test_core_module_includes.cpp").write_text("int main() { return 0; }\n", encoding="utf-8")
+
+            self.assertEqual(tdd_guard._guarded_paths([str(source)], root, root), [])
+
+    def test_cpp_production_file_with_basename_test_in_same_patch_is_allowed(self):
+        tdd_guard = load_tdd_guard()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            source = root / "src" / "Math" / "DenseMatrix.cpp"
+            source.parent.mkdir(parents=True)
+            source.write_text("void f() {}\n", encoding="utf-8")
+            test_path = root / "tests" / "test_dense_matrix.cpp"
+
+            self.assertEqual(tdd_guard._guarded_paths([str(source), str(test_path)], root, root), [])
+
+    def test_cmake_and_docs_are_exempt(self):
+        tdd_guard = load_tdd_guard()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self.assertEqual(
+                tdd_guard._guarded_paths(["CMakeLists.txt", "docs/ARCHITECTURE.md", "cmake/toolchain.cmake"], root, root),
+                [],
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

Coding/Codex-cpp/scripts/test_validate_workspace.py

@@ -0,0 +1,94 @@
+import importlib.util
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+def load_validate_workspace():
+    module_path = Path(__file__).resolve().parent / "validate_workspace.py"
+    spec = importlib.util.spec_from_file_location("validate_workspace", module_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class ValidateWorkspaceTests(unittest.TestCase):
+    def test_env_commands_override_cmake_detection(self):
+        validate_workspace = load_validate_workspace()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "CMakeLists.txt").write_text("cmake_minimum_required(VERSION 3.20)\n", encoding="utf-8")
+            with patch.dict(os.environ, {"HARNESS_VALIDATION_COMMANDS": "echo first\n echo second \n"}, clear=True):
+                self.assertEqual(validate_workspace.discover_commands(root), ["echo first", "echo second"])
+
+    def test_msvc_debug_cmake_commands_are_default_for_cmake_project(self):
+        validate_workspace = load_validate_workspace()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "CMakeLists.txt").write_text("cmake_minimum_required(VERSION 3.20)\n", encoding="utf-8")
+            build_dir = root / "build" / "msvc-debug"
+            with patch.dict(os.environ, {}, clear=True):
+                self.assertEqual(
+                    validate_workspace.discover_commands(root),
+                    [
+                        f'cmake -S "{root}" -B "{build_dir}" -G "Visual Studio 17 2022" -A x64',
+                        f'cmake --build "{build_dir}" --config Debug',
+                        f'ctest --test-dir "{build_dir}" --output-on-failure -C Debug',
+                    ],
+                )
+
+    def test_msvc_debug_configure_preset_is_preferred_when_present(self):
+        validate_workspace = load_validate_workspace()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "CMakeLists.txt").write_text("cmake_minimum_required(VERSION 3.20)\n", encoding="utf-8")
+            (root / "CMakePresets.json").write_text(
+                """
+{
+  "version": 3,
+  "configurePresets": [
+    {
+      "name": "msvc-debug",
+      "generator": "Visual Studio 17 2022",
+      "binaryDir": "${sourceDir}/out/msvc-debug"
+    }
+  ]
+}
+""",
+                encoding="utf-8",
+            )
+            with patch.dict(os.environ, {}, clear=True):
+                self.assertEqual(
+                    validate_workspace.discover_commands(root),
+                    [
+                        "cmake --preset msvc-debug",
+                        f'cmake --build "{root / "out" / "msvc-debug"}" --config Debug',
+                        f'ctest --test-dir "{root / "out" / "msvc-debug"}" --output-on-failure -C Debug',
+                    ],
+                )
+
+    def test_no_cmake_project_has_no_validation_commands(self):
+        validate_workspace = load_validate_workspace()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            with patch.dict(os.environ, {}, clear=True):
+                self.assertEqual(validate_workspace.discover_commands(root), [])
+
+    def test_common_cmake_install_path_is_prepended_when_cmake_is_not_on_path(self):
+        validate_workspace = load_validate_workspace()
+        with tempfile.TemporaryDirectory() as tmp:
+            common_bin = Path(tmp) / "CMake" / "bin"
+            common_bin.mkdir(parents=True)
+            (common_bin / "cmake.exe").write_text("", encoding="utf-8")
+            (common_bin / "ctest.exe").write_text("", encoding="utf-8")
+            with patch.object(validate_workspace, "COMMON_CMAKE_BIN", common_bin):
+                with patch.object(validate_workspace.shutil, "which", return_value=None):
+                    env = validate_workspace.validation_environment({"PATH": "C:\\Windows\\System32"})
+
+            self.assertTrue(env["PATH"].startswith(str(common_bin)))
+
+
+if __name__ == "__main__":
+    unittest.main()

Coding/Codex-cpp/scripts/validate_workspace.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Run C++/MSVC Harness validation commands."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+DEFAULT_GENERATOR = "Visual Studio 17 2022"
+DEFAULT_PLATFORM = "x64"
+DEFAULT_CONFIG = "Debug"
+DEFAULT_BUILD_DIR = "build/msvc-debug"
+PRESET_NAME = "msvc-debug"
+COMMON_CMAKE_BIN = Path(r"C:\Program Files\CMake\bin")
+
+
+def load_env_commands() -> list[str]:
+    raw = os.environ.get("HARNESS_VALIDATION_COMMANDS", "")
+    return [line.strip() for line in raw.splitlines() if line.strip()]
+
+
+def _cmake_config() -> tuple[str, str, str, Path]:
+    generator = os.environ.get("HARNESS_CMAKE_GENERATOR", DEFAULT_GENERATOR)
+    platform = os.environ.get("HARNESS_CMAKE_PLATFORM", DEFAULT_PLATFORM)
+    config = os.environ.get("HARNESS_CMAKE_CONFIG", DEFAULT_CONFIG)
+    build_dir = Path(os.environ.get("HARNESS_BUILD_DIR", DEFAULT_BUILD_DIR))
+    return generator, platform, config, build_dir
+
+
+def _read_presets(root: Path) -> dict:
+    presets_file = root / "CMakePresets.json"
+    if not presets_file.exists():
+        return {}
+    try:
+        return json.loads(presets_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _preset_binary_dir(root: Path, preset: dict) -> Path:
+    binary_dir = str(preset.get("binaryDir") or DEFAULT_BUILD_DIR)
+    binary_dir = binary_dir.replace("${sourceDir}", str(root))
+    binary_dir = binary_dir.replace("$sourceDir", str(root))
+    path = Path(binary_dir)
+    return path if path.is_absolute() else root / path
+
+
+def load_preset_commands(root: Path) -> list[str]:
+    payload = _read_presets(root)
+    config = os.environ.get("HARNESS_CMAKE_CONFIG", DEFAULT_CONFIG)
+    for preset in payload.get("configurePresets", []):
+        if isinstance(preset, dict) and preset.get("name") == PRESET_NAME:
+            build_dir = _preset_binary_dir(root, preset)
+            return [
+                f"cmake --preset {PRESET_NAME}",
+                f'cmake --build "{build_dir}" --config {config}',
+                f'ctest --test-dir "{build_dir}" --output-on-failure -C {config}',
+            ]
+    return []
+
+
+def load_cmake_commands(root: Path) -> list[str]:
+    if not (root / "CMakeLists.txt").exists():
+        return []
+
+    generator, platform, config, build_dir = _cmake_config()
+    if not build_dir.is_absolute():
+        build_dir = root / build_dir
+    return [
+        f'cmake -S "{root}" -B "{build_dir}" -G "{generator}" -A {platform}',
+        f'cmake --build "{build_dir}" --config {config}',
+        f'ctest --test-dir "{build_dir}" --output-on-failure -C {config}',
+    ]
+
+
+def discover_commands(root: Path) -> list[str]:
+    env_commands = load_env_commands()
+    if env_commands:
+        return env_commands
+    preset_commands = load_preset_commands(root)
+    if preset_commands:
+        return preset_commands
+    return load_cmake_commands(root)
+
+
+def run_command(command: str, root: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        command,
+        cwd=root,
+        shell=True,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=validation_environment(os.environ),
+    )
+
+
+def validation_environment(base_env: os._Environ | dict[str, str]) -> dict[str, str]:
+    env = dict(base_env)
+    if shutil.which("cmake") is not None:
+        return env
+    cmake_exe = COMMON_CMAKE_BIN / "cmake.exe"
+    if not cmake_exe.exists():
+        return env
+
+    current_path = env.get("PATH", "")
+    paths = [part for part in current_path.split(os.pathsep) if part]
+    common_bin_text = str(COMMON_CMAKE_BIN)
+    if not any(part.lower() == common_bin_text.lower() for part in paths):
+        env["PATH"] = common_bin_text + (os.pathsep + current_path if current_path else "")
+    return env
+
+
+def emit_stream(prefix: str, content: str, *, stream) -> None:
+    text = (content or "").strip()
+    if not text:
+        return
+    print(prefix, file=stream)
+    print(text, file=stream)
+
+
+def main() -> int:
+    root = Path(__file__).resolve().parent.parent
+    commands = discover_commands(root)
+
+    if not commands:
+        print("No C++ validation commands configured.")
+        print("Add CMakeLists.txt or set HARNESS_VALIDATION_COMMANDS.")
+        return 0
+
+    for command in commands:
+        print(f"$ {command}")
+        result = run_command(command, root)
+        emit_stream("[stdout]", result.stdout, stream=sys.stdout)
+        emit_stream("[stderr]", result.stderr, stream=sys.stderr)
+        if result.returncode != 0:
+            print(f"Validation failed: {command}", file=sys.stderr)
+            return result.returncode
+
+    print("Validation succeeded.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Coding/Codex-tsjs/.codex/config.toml

@@ -0,0 +1,4 @@
+#:schema https://developers.openai.com/codex/config-schema.json
+
+[features]
+codex_hooks = true

Coding/Codex-tsjs/.codex/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -c \"import pathlib, runpy, subprocess; root = pathlib.Path(subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], text=True).strip()); runpy.run_path(str(root / '.codex' / 'hooks' / 'pre_commit_checks.py'), run_name='__main__')\"",
+            "timeout": 600,
+            "statusMessage": "Running pre-commit checks"
+          }
+        ]
+      },
+      {
+        "matcher": "^(apply_patch|Edit|Write)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -c \"import pathlib, runpy, subprocess; root = pathlib.Path(subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], text=True).strip()); runpy.run_path(str(root / '.codex' / 'hooks' / 'tdd-guard.py'), run_name='__main__')\"",
+            "timeout": 30,
+            "statusMessage": "Checking TDD guard"
+          }
+        ]
+      }
+    ]
+  }
+}

Coding/Codex-tsjs/.codex/skills/harness-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Harness Review"
+  short_description: "Review Harness changes safely"
+  default_prompt: "Use $harness-review to review Harness repository changes."

Coding/Codex-tsjs/.codex/skills/harness-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Harness Workflow"
+  short_description: "Plan staged Harness workflow steps"
+  default_prompt: "Use $harness-workflow to plan Harness phases and step files."

Coding/Codex-tsjs/docs/UI_GUIDE.md

@@ -0,0 +1,76 @@
+# UI 디자인 가이드
+
+## 디자인 원칙
+1. {원칙 1 — 예: "도구처럼 보여야 한다. 마케팅 페이지가 아니라 매일 쓰는 대시보드."}
+2. {원칙 2}
+3. {원칙 3}
+
+## AI 슬롭 안티패턴 — 하지 마라
+| 금지 사항 | 이유 |
+|-----------|------|
+| backdrop-filter: blur() | glass morphism은 AI 템플릿의 가장 흔한 징후 |
+| gradient-text (배경 그라데이션 텍스트) | AI가 만든 SaaS 랜딩의 1번 특징 |
+| "Powered by AI" 배지 | 기능이 아니라 장식. 사용자에게 가치 없음 |
+| box-shadow 글로우 애니메이션 | 네온 글로우 = AI 슬롭 |
+| 보라/인디고 브랜드 색상 | "AI = 보라색" 클리셰 |
+| 모든 카드에 동일한 rounded-2xl | 균일한 둥근 모서리는 템플릿 느낌 |
+| 배경 gradient orb (blur-3xl 원형) | 모든 AI 랜딩 페이지에 있는 장식 |
+
+## 색상
+### 배경
+| 용도 | 값 |
+|------|------|
+| 페이지 | {예: #0a0a0a} |
+| 카드 | {예: #141414} |
+
+### 텍스트
+| 용도 | 값 |
+|------|------|
+| 주 텍스트 | {예: text-white} |
+| 본문 | {예: text-neutral-300} |
+| 보조 | {예: text-neutral-400} |
+| 비활성 | {예: text-neutral-500} |
+
+### 데이터/시맨틱 색상
+| 용도 | 값 |
+|------|------|
+| {긍정/성공} | {예: #22c55e} |
+| {부정/에러} | {예: #ef4444} |
+| {중립/기본} | {예: #525252} |
+
+## 컴포넌트
+### 카드
+```
+{예: rounded-lg bg-[#141414] border border-neutral-800 p-6}
+```
+
+### 버튼
+```
+Primary: {예: rounded-lg bg-white text-black hover:bg-neutral-200}
+Text:    {예: text-neutral-500 hover:text-neutral-300}
+```
+
+### 입력 필드
+```
+{예: rounded-lg bg-neutral-900 border border-neutral-800 px-4 py-3}
+```
+
+## 레이아웃
+- 전체 너비: {예: max-w-5xl}
+- 정렬: {예: 좌측 정렬 기본. 중앙 정렬 금지}
+- 간격: {예: gap-3~4, 섹션 간 space-y-8}
+
+## 타이포그래피
+| 용도 | 스타일 |
+|------|--------|
+| 페이지 제목 | {예: text-4xl font-semibold text-white} |
+| 카드 제목 | {예: text-sm font-medium text-neutral-400} |
+| 본문 | {예: text-sm text-neutral-300 leading-relaxed} |
+
+## 애니메이션
+- {허용할 애니메이션만 나열. 예: fade-in (0.4s), slide-up (0.5s)}
+- {그 외 모든 애니메이션 금지}
+
+## 아이콘
+- {예: SVG 인라인, strokeWidth 1.5}
+- {예: 아이콘 컨테이너(둥근 배경 박스)로 감싸지 않는다}

Coding/Codex-tsjs/scripts/execute.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""
+Harness Step Executor — phase 내 step을 순차 실행하고 자가 교정한다.
+
+Usage:
+    python scripts/execute.py <phase-dir> [--push]
+"""
+
+import argparse
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import types
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import Optional
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+@contextlib.contextmanager
+def progress_indicator(label: str):
+    """터미널 진행 표시기. with 문으로 사용하며 .elapsed 로 경과 시간을 읽는다."""
+    frames = "◐◓◑◒"
+    stop = threading.Event()
+    t0 = time.monotonic()
+
+    def _animate():
+        idx = 0
+        while not stop.wait(0.12):
+            sec = int(time.monotonic() - t0)
+            sys.stderr.write(f"\r{frames[idx % len(frames)]} {label} [{sec}s]")
+            sys.stderr.flush()
+            idx += 1
+        sys.stderr.write("\r" + " " * (len(label) + 20) + "\r")
+        sys.stderr.flush()
+
+    th = threading.Thread(target=_animate, daemon=True)
+    th.start()
+    info = types.SimpleNamespace(elapsed=0.0)
+    try:
+        yield info
+    finally:
+        stop.set()
+        th.join()
+        info.elapsed = time.monotonic() - t0
+
+
+class StepExecutor:
+    """Phase 디렉토리 안의 step들을 순차 실행하는 하네스."""
+
+    MAX_RETRIES = 3
+    FEAT_MSG = "feat({phase}): step {num} — {name}"
+    CHORE_MSG = "chore({phase}): step {num} output"
+    TZ = timezone(timedelta(hours=9))
+
+    def __init__(self, phase_dir_name: str, *, auto_push: bool = False):
+        self._root = str(ROOT)
+        self._phases_dir = ROOT / "phases"
+        self._phase_dir = self._phases_dir / phase_dir_name
+        self._phase_dir_name = phase_dir_name
+        self._top_index_file = self._phases_dir / "index.json"
+        self._auto_push = auto_push
+
+        if not self._phase_dir.is_dir():
+            print(f"ERROR: {self._phase_dir} not found")
+            sys.exit(1)
+
+        self._index_file = self._phase_dir / "index.json"
+        if not self._index_file.exists():
+            print(f"ERROR: {self._index_file} not found")
+            sys.exit(1)
+
+        idx = self._read_json(self._index_file)
+        self._project = idx.get("project", "project")
+        self._phase_name = idx.get("phase", phase_dir_name)
+        self._total = len(idx["steps"])
+
+    def run(self):
+        self._print_header()
+        self._check_blockers()
+        self._checkout_branch()
+        guardrails = self._load_guardrails()
+        self._ensure_created_at()
+        self._execute_all_steps(guardrails)
+        self._finalize()
+
+    # --- timestamps ---
+
+    def _stamp(self) -> str:
+        return datetime.now(self.TZ).strftime("%Y-%m-%dT%H:%M:%S%z")
+
+    # --- JSON I/O ---
+
+    @staticmethod
+    def _read_json(p: Path) -> dict:
+        return json.loads(p.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _write_json(p: Path, data: dict):
+        p.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # --- git ---
+
+    def _run_git(self, *args) -> subprocess.CompletedProcess:
+        cmd = ["git"] + list(args)
+        return subprocess.run(cmd, cwd=self._root, capture_output=True, text=True)
+
+    def _checkout_branch(self):
+        branch = f"feat-{self._phase_name}"
+
+        r = self._run_git("rev-parse", "--abbrev-ref", "HEAD")
+        if r.returncode != 0:
+            print(f"  ERROR: git을 사용할 수 없거나 git repo가 아닙니다.")
+            print(f"  {r.stderr.strip()}")
+            sys.exit(1)
+
+        if r.stdout.strip() == branch:
+            return
+
+        r = self._run_git("rev-parse", "--verify", branch)
+        r = self._run_git("checkout", branch) if r.returncode == 0 else self._run_git("checkout", "-b", branch)
+
+        if r.returncode != 0:
+            print(f"  ERROR: 브랜치 '{branch}' checkout 실패.")
+            print(f"  {r.stderr.strip()}")
+            print(f"  Hint: 변경사항을 stash하거나 commit한 후 다시 시도하세요.")
+            sys.exit(1)
+
+        print(f"  Branch: {branch}")
+
+    def _commit_step(self, step_num: int, step_name: str):
+        output_rel = f"phases/{self._phase_dir_name}/step{step_num}-output.json"
+        index_rel = f"phases/{self._phase_dir_name}/index.json"
+
+        self._run_git("add", "-A")
+        self._run_git("reset", "HEAD", "--", output_rel)
+        self._run_git("reset", "HEAD", "--", index_rel)
+
+        if self._run_git("diff", "--cached", "--quiet").returncode != 0:
+            msg = self.FEAT_MSG.format(phase=self._phase_name, num=step_num, name=step_name)
+            r = self._run_git("commit", "-m", msg)
+            if r.returncode == 0:
+                print(f"  Commit: {msg}")
+            else:
+                print(f"  WARN: 코드 커밋 실패: {r.stderr.strip()}")
+
+        self._run_git("add", "-A")
+        if self._run_git("diff", "--cached", "--quiet").returncode != 0:
+            msg = self.CHORE_MSG.format(phase=self._phase_name, num=step_num)
+            r = self._run_git("commit", "-m", msg)
+            if r.returncode != 0:
+                print(f"  WARN: housekeeping 커밋 실패: {r.stderr.strip()}")
+
+    # --- top-level index ---
+
+    def _update_top_index(self, status: str):
+        if not self._top_index_file.exists():
+            return
+        top = self._read_json(self._top_index_file)
+        ts = self._stamp()
+        for phase in top.get("phases", []):
+            if phase.get("dir") == self._phase_dir_name:
+                phase["status"] = status
+                ts_key = {"completed": "completed_at", "error": "failed_at", "blocked": "blocked_at"}.get(status)
+                if ts_key:
+                    phase[ts_key] = ts
+                break
+        self._write_json(self._top_index_file, top)
+
+    # --- guardrails & context ---
+
+    def _load_guardrails(self) -> str:
+        sections = []
+        agents_md = ROOT / "AGENTS.md"
+        if agents_md.exists():
+            sections.append(f"## 프로젝트 규칙 (AGENTS.md)\n\n{agents_md.read_text(encoding='utf-8')}")
+        docs_dir = ROOT / "docs"
+        if docs_dir.is_dir():
+            for doc in sorted(docs_dir.glob("*.md")):
+                sections.append(f"## {doc.stem}\n\n{doc.read_text(encoding='utf-8')}")
+        return "\n\n---\n\n".join(sections) if sections else ""
+
+    @staticmethod
+    def _build_step_context(index: dict) -> str:
+        lines = [
+            f"- Step {s['step']} ({s['name']}): {s['summary']}"
+            for s in index["steps"]
+            if s["status"] == "completed" and s.get("summary")
+        ]
+        if not lines:
+            return ""
+        return "## 이전 Step 산출물\n\n" + "\n".join(lines) + "\n\n"
+
+    def _build_preamble(self, guardrails: str, step_context: str,
+                        prev_error: Optional[str] = None) -> str:
+        commit_example = self.FEAT_MSG.format(
+            phase=self._phase_name, num="N", name="<step-name>"
+        )
+        retry_section = ""
+        if prev_error:
+            retry_section = (
+                f"\n## ⚠ 이전 시도 실패 — 아래 에러를 반드시 참고하여 수정하라\n\n"
+                f"{prev_error}\n\n---\n\n"
+            )
+        return (
+            f"당신은 {self._project} 프로젝트의 개발자입니다. 아래 step을 수행하세요.\n\n"
+            f"{guardrails}\n\n---\n\n"
+            f"{step_context}{retry_section}"
+            f"## 작업 규칙\n\n"
+            f"1. 이전 step에서 작성된 코드를 확인하고 일관성을 유지하라.\n"
+            f"2. 이 step에 명시된 작업만 수행하라. 추가 기능이나 파일을 만들지 마라.\n"
+            f"3. 기존 테스트를 깨뜨리지 마라.\n"
+            f"4. AC(Acceptance Criteria) 검증을 직접 실행하라.\n"
+            f"5. /phases/{self._phase_dir_name}/index.json의 해당 step status를 업데이트하라:\n"
+            f"   - AC 통과 → \"completed\" + \"summary\" 필드에 이 step의 산출물을 한 줄로 요약\n"
+            f"   - {self.MAX_RETRIES}회 수정 시도 후에도 실패 → \"error\" + \"error_message\" 기록\n"
+            f"   - 사용자 개입이 필요한 경우 (API 키, 인증, 수동 설정 등) → \"blocked\" + \"blocked_reason\" 기록 후 즉시 중단\n"
+            f"6. 모든 변경사항을 커밋하라:\n"
+            f"   {commit_example}\n\n---\n\n"
+        )
+
+    # --- Codex 호출 ---
+
+    def _invoke_codex(self, step: dict, preamble: str) -> dict:
+        step_num, step_name = step["step"], step["name"]
+        step_file = self._phase_dir / f"step{step_num}.md"
+
+        if not step_file.exists():
+            print(f"  ERROR: {step_file} not found")
+            sys.exit(1)
+
+        prompt = preamble + step_file.read_text(encoding="utf-8")
+        result = subprocess.run(
+            ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "--json", prompt],
+            cwd=self._root, capture_output=True, text=True, timeout=1800,
+        )
+
+        if result.returncode != 0:
+            print(f"\n  WARN: Codex가 비정상 종료됨 (code {result.returncode})")
+            if result.stderr:
+                print(f"  stderr: {result.stderr[:500]}")
+
+        output = {
+            "step": step_num, "name": step_name,
+            "exitCode": result.returncode,
+            "stdout": result.stdout, "stderr": result.stderr,
+        }
+        out_path = self._phase_dir / f"step{step_num}-output.json"
+        with open(out_path, "w", encoding="utf-8") as f:
+            json.dump(output, f, indent=2, ensure_ascii=False)
+
+        return output
+
+    # --- 헤더 & 검증 ---
+
+    def _print_header(self):
+        print(f"\n{'='*60}")
+        print(f"  Harness Step Executor")
+        print(f"  Phase: {self._phase_name} | Steps: {self._total}")
+        if self._auto_push:
+            print(f"  Auto-push: enabled")
+        print(f"{'='*60}")
+
+    def _check_blockers(self):
+        index = self._read_json(self._index_file)
+        for s in reversed(index["steps"]):
+            if s["status"] == "error":
+                print(f"\n  ✗ Step {s['step']} ({s['name']}) failed.")
+                print(f"  Error: {s.get('error_message', 'unknown')}")
+                print(f"  Fix and reset status to 'pending' to retry.")
+                sys.exit(1)
+            if s["status"] == "blocked":
+                print(f"\n  ⏸ Step {s['step']} ({s['name']}) blocked.")
+                print(f"  Reason: {s.get('blocked_reason', 'unknown')}")
+                print(f"  Resolve and reset status to 'pending' to retry.")
+                sys.exit(2)
+            if s["status"] != "pending":
+                break
+
+    def _ensure_created_at(self):
+        index = self._read_json(self._index_file)
+        if "created_at" not in index:
+            index["created_at"] = self._stamp()
+            self._write_json(self._index_file, index)
+
+    # --- 실행 루프 ---
+
+    def _execute_single_step(self, step: dict, guardrails: str) -> bool:
+        """단일 step 실행 (재시도 포함). 완료되면 True, 실패/차단이면 False."""
+        step_num, step_name = step["step"], step["name"]
+        done = sum(1 for s in self._read_json(self._index_file)["steps"] if s["status"] == "completed")
+        prev_error = None
+
+        for attempt in range(1, self.MAX_RETRIES + 1):
+            index = self._read_json(self._index_file)
+            step_context = self._build_step_context(index)
+            preamble = self._build_preamble(guardrails, step_context, prev_error)
+
+            tag = f"Step {step_num}/{self._total - 1} ({done} done): {step_name}"
+            if attempt > 1:
+                tag += f" [retry {attempt}/{self.MAX_RETRIES}]"
+
+            with progress_indicator(tag) as pi:
+                self._invoke_codex(step, preamble)
+                elapsed = int(pi.elapsed)
+
+            index = self._read_json(self._index_file)
+            status = next((s.get("status", "pending") for s in index["steps"] if s["step"] == step_num), "pending")
+            ts = self._stamp()
+
+            if status == "completed":
+                for s in index["steps"]:
+                    if s["step"] == step_num:
+                        s["completed_at"] = ts
+                self._write_json(self._index_file, index)
+                self._commit_step(step_num, step_name)
+                print(f"  ✓ Step {step_num}: {step_name} [{elapsed}s]")
+                return True
+
+            if status == "blocked":
+                for s in index["steps"]:
+                    if s["step"] == step_num:
+                        s["blocked_at"] = ts
+                self._write_json(self._index_file, index)
+                reason = next((s.get("blocked_reason", "") for s in index["steps"] if s["step"] == step_num), "")
+                print(f"  ⏸ Step {step_num}: {step_name} blocked [{elapsed}s]")
+                print(f"    Reason: {reason}")
+                self._update_top_index("blocked")
+                sys.exit(2)
+
+            err_msg = next(
+                (s.get("error_message", "Step did not update status") for s in index["steps"] if s["step"] == step_num),
+                "Step did not update status",
+            )
+
+            if attempt < self.MAX_RETRIES:
+                for s in index["steps"]:
+                    if s["step"] == step_num:
+                        s["status"] = "pending"
+                        s.pop("error_message", None)
+                self._write_json(self._index_file, index)
+                prev_error = err_msg
+                print(f"  ↻ Step {step_num}: retry {attempt}/{self.MAX_RETRIES} — {err_msg}")
+            else:
+                for s in index["steps"]:
+                    if s["step"] == step_num:
+                        s["status"] = "error"
+                        s["error_message"] = f"[{self.MAX_RETRIES}회 시도 후 실패] {err_msg}"
+                        s["failed_at"] = ts
+                self._write_json(self._index_file, index)
+                self._commit_step(step_num, step_name)
+                print(f"  ✗ Step {step_num}: {step_name} failed after {self.MAX_RETRIES} attempts [{elapsed}s]")
+                print(f"    Error: {err_msg}")
+                self._update_top_index("error")
+                sys.exit(1)
+
+        return False  # unreachable
+
+    def _execute_all_steps(self, guardrails: str):
+        while True:
+            index = self._read_json(self._index_file)
+            pending = next((s for s in index["steps"] if s["status"] == "pending"), None)
+            if pending is None:
+                print("\n  All steps completed!")
+                return
+
+            step_num = pending["step"]
+            for s in index["steps"]:
+                if s["step"] == step_num and "started_at" not in s:
+                    s["started_at"] = self._stamp()
+                    self._write_json(self._index_file, index)
+                    break
+
+            self._execute_single_step(pending, guardrails)
+
+    def _finalize(self):
+        index = self._read_json(self._index_file)
+        index["completed_at"] = self._stamp()
+        self._write_json(self._index_file, index)
+        self._update_top_index("completed")
+
+        self._run_git("add", "-A")
+        if self._run_git("diff", "--cached", "--quiet").returncode != 0:
+            msg = f"chore({self._phase_name}): mark phase completed"
+            r = self._run_git("commit", "-m", msg)
+            if r.returncode == 0:
+                print(f"  ✓ {msg}")
+
+        if self._auto_push:
+            branch = f"feat-{self._phase_name}"
+            r = self._run_git("push", "-u", "origin", branch)
+            if r.returncode != 0:
+                print(f"\n  ERROR: git push 실패: {r.stderr.strip()}")
+                sys.exit(1)
+            print(f"  ✓ Pushed to origin/{branch}")
+
+        print(f"\n{'='*60}")
+        print(f"  Phase '{self._phase_name}' completed!")
+        print(f"{'='*60}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Harness Step Executor")
+    parser.add_argument("phase_dir", help="Phase directory name (e.g. 0-mvp)")
+    parser.add_argument("--push", action="store_true", help="Push branch after completion")
+    args = parser.parse_args()
+
+    StepExecutor(args.phase_dir, auto_push=args.push).run()
+
+
+if __name__ == "__main__":
+    main()