diff --git a/AGENTS.md b/AGENTS.md index f5c953f8..77091bd4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,10 @@ `AGENTS.md`가 생기면 사용자 지시, 가까운 파일, 이 파일, 상위 작업공간 지침 순으로 적용합니다. -목표는 `../ref/sam`의 PHP 서비스를 TypeScript 런타임으로 호환 이관하는 -것입니다. 내부 구조를 더 깔끔하게 만드는 일보다 기존 결과, 상태 전이, 권한, -화면과 운영 경계를 보존하는 일이 우선입니다. +`../ref/sam`은 누락·회귀를 찾고 기존 개념과 사용자 기대를 이해하기 위한 PHP +기준 구현입니다. `core2026`은 0.1.0 출시 이후 독립적으로 발전하는 제품이므로, +이관 중인 계승 영역은 기존 결과·상태 전이·권한·화면·운영 경계를 우선 보존하되 +명시적인 신규 기능·밸런스·UX 결정까지 Ref와 기계적으로 일치시키지 않습니다. ## 현재 기준과 저장소 경계 @@ -41,7 +42,9 @@ commit 또는 삭제를 하지 말아 주세요. 판정해 주세요. 기능 목록이나 report의 완료 표현만으로 전체 이관이 끝났다고 판정하지 말아 주세요. -- 새 차등 fixture가 mismatch를 드러내면 다시 제품 결함으로 분류해 주세요. +- 새 차등 fixture가 mismatch를 드러내면 계승 계약, 의도적 제품 차이, 누락·회귀, + 비교 불가 중 무엇인지 조사한 뒤 분류해 주세요. mismatch만으로 제품 결함을 + 확정하지 않습니다. - green unit test는 ref 호환, 실제 DB transaction, Chromium geometry 또는 운영 장애 복구를 자동으로 증명하지 않습니다. - 환경 변수가 없는 기본 test에서 skip된 integration은 실행된 검증이 아닙니다. @@ -95,6 +98,20 @@ priority/unique-ID trigger와 닫힌 의미 이벤트를 한 범용 hook으로 `의도적 차이`를 근거와 함께 사용해 주세요. 문서와 코드가 다르면 먼저 양쪽 기준 commit과 실제 실행을 확인하고 사실관계를 고쳐 주세요. +Ref 비교 전에 대상 계약도 구분해 주세요. + +- 별도 제품 결정이 없는 기존 기능은 **계승 계약**으로 보고 사용자 목적, 도메인 + 의미, 권한·소유권, 상태 수명주기와 관찰 가능한 결과를 비교합니다. +- 신규 기능·밸런스·안전·운영·UX 정책은 **의도적 제품 차이**로 기록하고 목적, + 적용 버전과 범위, 상태·후속 턴 영향, migration/호환 경계와 Core 회귀 테스트를 + 둡니다. Ref와 다른 값이 나오는 것 자체는 실패가 아닙니다. +- 제품 결정 없이 기존 개념이나 정보가 사라진 경우는 **누락·회귀**, Ref에 대응 + 개념이 없는 기능은 **비교 불가**입니다. 후자는 자체 불변조건으로 검증합니다. + +차등 테스트는 차이를 감지하는 도구이지 제품 정책의 판정자가 아닙니다. 계승 +계약에만 exact equality를 요구하고, 의도적 차이는 별도 기대값·허용 목록·버전된 +fixture로 명시하여 무작정 테스트를 끄거나 Ref 기대값에 되맞추지 마세요. + ref 계측이 필요하면 다음을 지켜 주세요. - `devel`에 test, endpoint, fixture나 debug 코드를 commit하지 말아 주세요. @@ -105,7 +122,7 @@ ref 계측이 필요하면 다음을 지켜 주세요. 확인해 주세요. - ref와 core 변경은 서로 다른 저장소와 commit으로 관리해 주세요. -## 호환성 우선순위 +## 계승 계약의 호환성 우선순위 1. 전투 결과, 계산식, 판정·반올림·정렬과 RNG 소비 순서 2. 턴/명령 조건, 자원 변화, DB 상태 전이와 권한 @@ -113,10 +130,12 @@ ref 계측이 필요하면 다음을 지켜 주세요. 4. 문구, 로그, 화면 흐름과 룩앤필 5. 내부 구현 세부사항 -레거시의 이상해 보이는 동작도 계약일 수 있습니다. 보안 또는 데이터 손상 위험이 -아니면 우선 같은 동작을 재현하고 개선 제안은 분리해 주세요. 허용하는 차이는 -사용자 경험, 저장 상태와 후속 턴 결과에 영향이 없다는 근거를 mapping/report에 -남겨 주세요. +레거시의 이상해 보이는 동작도 계승 계약일 수 있습니다. 보안 또는 데이터 손상 +위험이 아니면 먼저 재현하고 제품 변경은 분리해 주세요. 반대로 승인·출시된 Core +차이는 Ref 결과만을 이유로 되돌리지 않습니다. 의도적 차이는 사용자 경험·저장 +상태·후속 턴에 영향을 줄 수 있으므로 그 영향과 전환 경계를 mapping/report에 +명시합니다. 보안, 데이터 무결성, 인증 actor 권한과 운영 안전은 신규 기능이라는 +이름만으로 완화하지 않습니다. ## 인증과 권한 diff --git a/docs/architecture/turn-state-differential-testing.md b/docs/architecture/turn-state-differential-testing.md index 48be9459..a61c712d 100644 --- a/docs/architecture/turn-state-differential-testing.md +++ b/docs/architecture/turn-state-differential-testing.md @@ -6,6 +6,14 @@ 상태 mutation과 persistence 순서를 비교합니다. 명령 이름이나 최종 성공 여부만 같은 것은 호환성 근거가 아닙니다. +이 비교는 차이를 검출하는 장치이지 모든 차이를 제품 결함으로 판정하는 장치가 +아닙니다. 대상 영역을 먼저 계승 계약, 의도적 제품 차이, 누락·회귀 또는 비교 +불가로 분류합니다. Exact equality는 계승 계약에만 요구합니다. 밸런스 조정이나 +신규 규칙처럼 의도적으로 결과가 달라지는 영역은 목적·적용 버전·영향 필드·RNG와 +persistence 변화·migration 경계를 mapping/report에 기록하고, versioned fixture나 +명시적인 기대 차이와 Core 회귀 테스트로 검증합니다. 단순히 Ref 차등 suite를 +skip하거나 느슨한 정규화로 차이를 숨기지 않습니다. + ## 검증 계층 | 계층 | 위치 | 보장 범위 | diff --git a/docs/frontend-legacy-parity.md b/docs/frontend-legacy-parity.md index fa873ec1..5dc44c3e 100644 --- a/docs/frontend-legacy-parity.md +++ b/docs/frontend-legacy-parity.md @@ -5,6 +5,14 @@ are enforced while the PHP frontend is moved to the Vue applications. The workspace-level `docs/ref-core2026-mapping.md` remains the source of truth for the end-to-end PHP-to-core2026 mapping. +Ref comparison detects missing information and unintended interaction or layout +regressions; it does not permanently freeze every Core screen pixel-for-pixel. +Classify each difference as an inherited contract, an intentional product +difference, a missing/regressed behavior, or a Core-only feature. Exact visual +equality applies only where the inherited contract declares it. Intentional UX, +accessibility, or responsive changes need a documented scope, user impact, and +Core-owned geometry and interaction assertions instead of a disabled parity test. + ## Canonical browser fixture `tools/frontend-legacy-parity/fixtures/canonical.ts` contains deterministic,