Commit Graph
5 Commits
Author SHA1 Message Date
DongHyeonka 16202fd48d fix(docs): 현재 계약 문서의 경로·명령·게이트 ID를 검사한다 (14-05)
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).

고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
  artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
  ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
  (ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
  starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
  가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
  적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
  문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
  작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
  기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
  읽는다), README "Files you can delete after copying"의 이력 중 지워진
  것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
  FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
  적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
  3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
  경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
  ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
  모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.

위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
  링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
  경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
  시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
  계약 문서(README, compatibility.md, starter-experience.md,
  manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
  복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
  본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.

검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
  기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
  "failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
  통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
  tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
  돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
  고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
  EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
  deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
  eslint 통과. check-ci-contract, generate-artifact-schemas --check,
  generate-ci-workflow --check, check-adapter-inventory 통과.
  check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
  이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
2026-11-03 01:13:16 +09:00
DongHyeonka e98a980dff fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.

고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).

버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
  newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.

위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.

검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
  "expected { ok: true, value: undefined } to match object { ok: false }"
  로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
  to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
  contract-registry-lookup, browser-security, runtime-adapters,
  release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
  eslint 통과, check-registries PASS, verify-documentation-readiness
  PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonkaandClaude Opus 5.5 17d617ab7a fix(contracts): classify unknown schema changes as breaking and gate the runtime config schema against a baseline (07-02, 13-10)
The classifier called type, enum and nullable changes "none" and treated new
keys under strict readers as additive; FE-GATE-014 only checked hand-written
fixtures. It now fails closed and compares the committed baseline with the
schema the build emits. The doc lists per-boundary reader rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:04:25 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 89f3c69413 feat: govern frontend contract compatibility 2026-07-25 21:19:20 +09:00