Pages live 문서 검증을 정본 공개 계약과 일치시킨다

[developer-1px]

Goal Anchor

• Outcome: 정상적으로 배포된 현재 공개 문서를 오래된 기준으로 거절하는 Pages live 검증 실패를 해결합니다.
• Done: 문서 원천·Pages 산출물·live 응답이 정본 공개 계약을 같은 owner에서 검사하고, 현재 문서 통과/구계약·삭제된 surface 거절 회귀 및 실제 live 재검증을 갖춘 수정 PR을 엽니다.
• Don't: Core 공개 API·wire, 제품 UI, 정상 문서 내용을 구계약에 맞춰 변경하지 않습니다. 검사를 생략하거나 재시도 증가로 실패를 숨기지 않습니다. Database saved-view와 편집 표현 책임을 정본화한다 #587·refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #589 및 npm 배포·배포 설정 변경은 포함하지 않으며 merge는 별도 승인 대상으로 둡니다.

승인과 재현

사용자는 Pages 배포 후 검증의 live llms.txt is missing the v3 Core contract. 실패를 보고받고 “대응해”라고 요청했습니다. 현재 배포 검증 실패만 대응하며 기존 미병합 PR은 제외합니다.

• 실패 run: https://github.com/developer-1px/json-document/actions/runs/34115659033
• 기준: main 5df3b687555eb9aa9cd6a2e93db7ec02dc9c200f. 이 head의 일반 CI는 통과했습니다.
• 실제 /llms.txt는 HTTP 200이고 docs/public/llms.txt와 byte 단위 동일합니다. 현재 문서는 23개 Root symbol을 설명하지만 site/scripts/evaluate-live.mjs는 21개를 요구합니다.
• SITE_LIVE_ATTEMPTS=1 npm run site:evaluate:live로 동일 실패를 재현했습니다. 로컬 Pages 산출물 검사는 llms 존재만 확인하고 live 내용 검사를 공유하지 않습니다.
• 문서 evaluator와 live evaluator의 companion allowlist도 별도로 유지되어 향후 같은 drift를 일으킬 수 있습니다.

완료 조건

1. Root symbol 수는 Core의 기존 public-contract.json, 유효한 공개 package 참조는 기존 owner 등록 정보에서 읽습니다. 새 수동 사본을 만들지 않습니다.
2. 공개 문서 계약 검사 책임을 기존 docs 검증 위치에 명시하고 docs 원천·Pages artifact·live가 같은 검사를 소비합니다. HTTP fetch·retry와 artifact I/O는 각 실행기에 유지합니다.
3. 현재 llms 원문은 통과하며 구 21-symbol 주장, 필수 v3/six-member/companion 설명 누락, 삭제된 package/subpath/lab 참조는 계속 실패합니다.
4. 회귀 테스트, docs 평가, Pages build/evaluation/HTTP smoke 및 실제 배포 사이트의 수정된 live 검사 결과를 기록합니다.

범위와 경계

이 책임은 repository의 문서 검증 도구이며 새로운 SDK package/public concept가 아닙니다. Runtime export·site Usage UI를 추가하지 않습니다. 일반 route/meta/manifest 검증이나 CI planner 전체를 재설계하지 않습니다. 기존 사용자 checkout의 개인 자료는 보존합니다.

[developer-1px]

작업 시작

Goal Anchor

• Outcome: 정상적으로 배포된 현재 공개 문서를 오래된 기준으로 거절하는 Pages live 검증 실패를 해결합니다.
• Done: 문서 원천·Pages 산출물·live 응답이 정본 공개 계약을 같은 owner에서 검사하고, 현재 문서 통과/구계약·삭제된 surface 거절 회귀 및 실제 live 재검증을 갖춘 수정 PR을 엽니다.
• Don't: Core 공개 API·wire, 제품 UI, 정상 문서 내용을 구계약에 맞춰 변경하지 않습니다. 검사를 생략하거나 재시도 증가로 실패를 숨기지 않습니다. Database saved-view와 편집 표현 책임을 정본화한다 #587·refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #589 및 npm 배포·배포 설정 변경은 포함하지 않으며 merge는 별도 승인 대상으로 둡니다.

원격 issue read-back으로 범위를 확인했습니다. 기준 main은 5df3b687555eb9aa9cd6a2e93db7ec02dc9c200f, branch는 issue-717-pages-public-contract입니다. 기존 checkout의 tracked/staged 변경은 없고 untracked 개인 자료는 보존했습니다.

책임 점검 범위

발생 위치	역할/판정	처리
docs/evaluate.mjs	공개 package 참조 validation / 정본 API 분리 필요	명시적 docs validator를 소비
site/scripts/evaluate-live.mjs	같은 내용 validation의 중복 + HTTP/retry 조립	중복 내용 검사를 docs owner로 위임, transport 유지
site/scripts/evaluate.mjs	artifact 검증 조립 / 같은 내용 검사 누락	배포 전에 같은 owner로 llms 검사
site/scripts/evaluate-http.mjs	HTTP status/content-type/asset 연결	내용 정본은 앞선 artifact 검사에 맡기고 그대로 유지

공개 계약 데이터는 Core public-contract.json, package 집합은 기존 docs/api-reference/packages.mjs를 소비합니다. 새 runtime package나 site 공개 개념은 아닙니다. docs owner의 명시적 ESM API·문서·회귀 및 실제 evaluator 소비로 내부 검증 책임을 닫습니다.

현재 배포와 소스 동일 / 기존 live 검사 실패 [확인]
  → 문서 validation owner + negative regression
  → docs / artifact / live 소비와 중복 제거
  → 관련 tests + docs + Pages build/HTTP + 실제 live
  → diff 리뷰·commit·push·PR

UI 변경이 없어 새 Chrome profile이나 브라우저 조작은 필요하지 않습니다. 실제 배포 검증은 HTTP를 통해 수행합니다.

[developer-1px]

구현·검증 결과

원래 Goal Anchor를 유지합니다. 새 SDK/공개 UI/배포 설정은 추가하지 않았습니다.

• docs/public-contract-checks.mjs: Root symbol 수를 Core public-contract.json에서, package 참조 집합을 기존 api-reference/packages.mjs에서 읽습니다. 별도 수동 allowlist 두 개를 제거했습니다.
• 같은 owner를 docs 원천·Pages artifact·live 응답 evaluator 세 곳이 소비합니다. HTTP fetch/retry, route/meta/manifest와 HTTP smoke 책임은 기존 실행기에 유지합니다.
• docs/README.md에 내부 검사 owner를 명시하고 같은 오래된 21-symbol 설명은 숫자 사본 대신 정본 public surface 참조로 바로잡았습니다.
• 현재 원문 통과, 21-symbol 및 필수 설명 누락 거절, 등록된 모든 package 허용, 삭제된 package/subpath/lab 참조 거절, evaluator 위임 guard 14 tests 통과.
• Site 전체 137 tests 통과, 전체 package build·docs evaluation·workspace 29 libraries 통과.
• 실제 live 검증: 기존 코드에서 단일 attempt 실패를 재현한 뒤, 수정된 코드로 같은 배포 사이트에 SITE_LIVE_ATTEMPTS=1 npm run site:evaluate:live를 실행해 **live site evaluation ok**를 확인했습니다. 원격 사이트나 배포 artifact는 변경하지 않았습니다.

남은 검증: Pages build/evaluation/HTTP smoke, 잘못된 artifact에 대한 실제 실행기 거절, 최종 diff self-review·commit·push·PR. 일반 main CI와 Pages 배포 후 검증은 별개이며 기존 실패 run 자체가 성공으로 바뀐 것으로 보고하지 않습니다.

[developer-1px]

PR 열림 — pr-open

PR #718: #718

원격 issue↔PR Goal Anchor와 완료 조건 1~4, 실제 changed path 6개, 검증 결과의 대응을 확인했습니다. local HEAD와 remote PR head는 0af5b04a558e330dbf3833f512fcca2699005ad4로 일치하고 작업트리는 clean입니다.

• 원인: 현재 배포 llms는 HTTP 200 / 12,428 bytes로 source와 byte 단위 동일한데, live 검사만 21-symbol을 요구했습니다.
• 완료: docs·artifact·live의 내용 검사 owner 통합, 정본 데이터 소비, 구계약/삭제 surface 거절 유지, README와 회귀/위임 guard.
• Site 137 tests(신규 회귀 14개), 전체 build, docs/workspace/Site typecheck·정본/스타일 guards, standard conformance 347 passed / 4 skipped, Pages build/evaluation/HTTP smoke 통과.
• malformed 21-symbol artifact를 실제 evaluator가 exit 1로 거절하고 복원 뒤 다시 통과했습니다. 생성 artifact는 source와 동일하게 복원했습니다.
• 현재 배포 사이트에 수정된 live checker를 실행해 live site evaluation ok를 확인했습니다. 배포 내용을 고치거나 검사/retry를 우회하지 않았습니다.
• UI 변경이 없는 repository 검증 도구 수정이므로 show-me는 non-applicable입니다.

PR CI는 진행 중입니다. main의 과거 실패 run이 해결 상태로 바뀐 것은 아닙니다. merge·npm 배포는 하지 않았고 기존 #587·#589와 사용자 개인 자료도 건드리지 않았습니다.

[developer-1px]

최종 PR CI 통과

CI run, head 0af5b04a558e330dbf3833f512fcca2699005ad4:

• Plan 통과.
• Package 통과.
• Site 통과: 문서·Pages artifact/HTTP 및 선택된 browser 검증 포함.
• External kit은 repository planner가 이번 문서 검증 도구 변경에 불필요하다고 분류하여 skip했습니다. 실행 성공으로 계산하지 않습니다.

원래 1~4 완료 조건에 대한 로컬 검증과 현재 배포 사이트 read-only live 검사도 모두 통과했습니다. 상태는 pr-open입니다. 아직 main에 merge하거나 배포 workflow를 재실행하지 않았고, 사용자 개인 자료와 기존 미병합 PR은 보존했습니다.

[developer-1px]

merge 단계 시작 — 승인된 contract delta

사용자가 PR #718에 대해 “merge”를 명시적으로 승인했습니다.

• Before: 수정 PR-open에서 종료하며 merge는 별도 승인 대상입니다.
• After: 원래 문서 검증 수정 범위를 유지한 채 검증된 head를 merge하고, 자동 Pages 배포 후 live 검증을 확인한 뒤 이번 merged branch/worktree만 정리합니다.
• 유지: Core API·wire·제품 UI·배포 설정 변경 없음, Database saved-view와 편집 표현 책임을 정본화한다 #587·refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #589 및 npm 배포 제외, 기존 개인 자료 보존.

원격 issue 본문/진행 기록, PR 본문·실제 diff·head·base·리뷰와 repository gate를 다시 확인했습니다. head는 0af5b04a558e330dbf3833f512fcca2699005ad4, base는 5df3b687555eb9aa9cd6a2e93db7ec02dc9c200f이고 local과 remote가 일치합니다. 작업트리는 clean입니다.

PR CI의 Plan·Package·Site는 통과했고 External kit은 planner에 따른 skip입니다. 외부 review/inline comment와 blocking review는 없으며 관리자 우회 없이 해당 head만 squash merge합니다.

[developer-1px]

merge·배포 검증·정리 완료 — landed-clean

사용자가 승인한 merge 단계를 완료했습니다.

• PR Pages live 문서 검증을 정본 공개 계약과 일치시킨다 #718: MERGED, merge commit 08de2da6f45dd42714c89046b95e18963763a62f.
• 이슈 Pages live 문서 검증을 정본 공개 계약과 일치시킨다 #717: CLOSED.
• 이번 merge의 Pages workflow: build·deploy 모두 성공했고 Evaluate live site 단계도 성공했습니다. 기존의 21-symbol 오판 실패가 실제 배포 workflow에서 해소됐습니다.
• 로컬 main과 origin/main은 위 merge commit으로 일치합니다. 최종 PR 검증 head 0af5b04a558e330dbf3833f512fcca2699005ad4와 merge 후 파일 tree가 동일하며 main의 docs 평가·build도 통과했습니다.
• 이번 작업의 issue-717-pages-public-contract 로컬/원격 branch와 worktree만 제거했습니다. 구현은 merge commit에 보존됩니다.
• 기존 untracked 개인 자료 4개와 다른 branch·미병합 PR은 보존했습니다. tracked/staged 변경은 없습니다.
• npm 배포나 배포 workflow 설정 변경은 하지 않았습니다.

과거 실패 run을 재실행해 성공으로 덮어쓴 것이 아니라, 수정 commit의 새 자동 Pages run이 정상 완료된 결과입니다. PR CI의 검증 결과와 별개로 실제 Pages 배포 후 검증까지 확인했습니다.