gh-verify plugin · skill guide

gh-verify:live

한 줄 요약 — 이미 떠 있는 앱이 정말 대상 커밋을 서빙 중임을 먼저 증명한 다음, PR 이 주장한 화면을 브라우저로 몰아 보고 살아남은 발견만 신규 이슈로 남긴다.

01

언제 쓰는가

gh-verify:live

서빙 체크아웃 신원

지금 화면을 그리고 있는 프로세스가 대상 커밋을 담고 있는가.

gh-verify:merged

신선한 클론 신원

누가 새로 clone 해도 그렇게 동작하는가.

자매 스킬과의 경계는 무엇을 증명하느냐로 갈린다.

띄울 앱이 있는 레포

사용자가 이미 dev 서버를 띄워 둔 상태로 PR 을 실물 확인할 때. 머지 직후가 주 용도지만 미머지 PR 브랜치에도 쓴다.

미머지 PR

띄울 앱이 없고 증명이 머지 커밋의 신선한 클론에서 나와야 한다면 이 스킬이 아니라 gh-verify:merged 다. 반대로 미머지 PR 은 gh-verify:merged 가 정지하므로 이 스킬을 쓴다.

배타적이지 않다

프론트엔드 PR 은 merged 로 유닛/빌드 재현성을, live 로 화면을 볼 수 있다.

머지 전 게이트는 따로

머지 전 정적 리뷰 게이트는 gh-verify:review-all 이다.

02

언제 쓰지 않는가

띄울 앱이 없는 레포 (shell · CLI · lib)

Do NOT use when there is no app to run and the proof must come from a fresh clone of the merge commit — that is gh-verify:merged.

유닛 테스트 대용

이 레포에서 test 는 bats/pytest 스위트를 뜻하고, 이 스킬은 기동 중인 서버에 브라우저로 붙는 실물 확인이다.

코드 수정 목적

원인이 보여도 고치지 않는다. 읽기 전용 경계다.

staging/운영 URL 대상

앱 데이터에 쓰기를 하므로 dev/fake 스택 전용이다.

03

호출

/gh-verify:live [pr-number] [remote] [flags]
두 positional 은 첫 글자로 구분한다 — 숫자로 시작하면 PR#(양의 정수여야 하며 아니면 exit 2), 아니면 remote 다. 그래서 /gh-verify:live upstream 처럼 PR 은 자동 감지하고 remote 만 지정하는 호출이 가능하다.
#이름기본값설명
1PR number, 또는 -h/--help/help자동생략 시 현재 브랜치 → 실패하면 현재 커밋을 포함하는 PR 을 역추적
2remote nameorigin대상 레포를 해석할 git remote

Flags

Flag기본값설명
--url <base-url>자동 발견앱 base URL. 주면 프런트 발견 단계를 건너뛴다
--api-url <origin>자동 발견백엔드 origin. 병렬 스택에서 엉뚱한 API 를 찌르는 것을 막는다
--start <cmd>없음서버 기동 명령. 기본은 기동하지 않는다 — 사용자가 이미 띄웠다고 전제한다
--matrix auto|fullautoauto 는 diff 에서 축을 유도, full 은 전체 곱을 훑는다
--viewports <csv>유도명시하면 그 폭만. 고정 기본값 없음
--locales <csv>유도명시하면 그 로케일만
--dry-runoff이슈 본문을 작성해서 출력하되 등록하지 않는다
--no-issueoff초안조차 쓰지 않고 리포트 행으로만 보고한다
--no-commentoff리포트를 PR 코멘트로 게시하지 않는다 (기본은 게시)
--allow-remote-hostoff로컬이 아닌 호스트 대상 허용. 로컬 판정: localhost · 127.0.0.0/8 · ::1 · [::1] · 0.0.0.0 · [::]
-h / --help / help—도움말 출력 후 정지

--dry-run 과 --no-issue 를 같이 주면 --no-issue 가 이긴다. --no-comment 는 그 둘과 독립이다. 플래그는 모두 --url X 와 --url=X 두 형태를 받는다.

Exit codes

Code원인
0검증이 끝났다 — 발견이 0건이든 N건이든, degraded 모드였든 포함
1검증 전 단언 실패(서빙 체크아웃 불일치 · 전환 no-op · 대상 가려짐), 서버 미발견, gh 미인증, 로컬 아닌 호스트에 --allow-remote-host 없음
2인자 오류: 숫자로 시작하는데 양의 정수가 아닌 PR#, http(s) 아닌 --url/--api-url, auto|full 아닌 --matrix, 잘못된 CSV, 값이 빈 플래그, 모르는 플래그, 남는 positional
04

동작 단계

  1. Step 1 — 인자 파싱

    devx_pr_verify_live_parse 로 플래그를 캡처하고 START_TS 를 기록한다.

  2. Step 2 — 대상 해석 + 환경 발견

    대상 레포와 PR 을 해석하고 LISTEN 소켓에서 base URL / API origin 을 발견한다. 후보가 여럿이면 AskUserQuestion — 추측하지 않는다. 로컬이 아니면 호스트 가드로 정지한다.

  3. Step 3 — 검증 전 단언 1: 서빙 체크아웃불일치면 정지

    변경된 코드를 서빙하는 모든 프로세스에 대해 cwd → repo root → ancestry 를 확인하고, PR 메타의 .mergeCommit.oid 와 비교한다(headRefOid 는 재작성되므로 미머지일 때만 폴백). 불일치면 몇 커밋 뒤처졌는지와 함께 정지한다.

  4. Step 4 — 검증 항목 결정

    연결 이슈의 AC → PR Test plan 미체크 항목 → 라우트 추론 → 질의 순. - [x] 를 통과로 취급하지 않고, 각 분기의 데이터 상태와 feature flag 게이트도 확인한다.

  5. Step 5 — 드라이버와 세션 (단언 2·3)전환 적용 · 비가림

    드라이버 사다리를 브라우저 바이너리까지 확인해 고르고, 로그인 · 오버레이 해제 · 로케일 전환 레시피를 캐시에서 읽거나 발견한다. 전환 적용·비가림 단언이 여기서 걸린다.

  6. Step 6 — 측정

    diff 로 축을 고른 뒤(--matrix full 은 opt-in) 각 항목을 기계 판독 가능한 단언으로 확인한다 — 측정값 · 형제 비교 · 지시-어포던스 · 셀렉터 규율 · 응답 가로채기 · 선행 조건 합성 · hit-test.

  7. Step 7 — 발견 → 이슈

    후보마다 자기 반증 3가설(하네스 오류 · 데이터 상태 · 의도된 동작)을 세워 반증하고, 게이트를 통과한 것만 발견 1건 = 이슈 1건으로 gh:issue-create 에 넘긴다.

  8. Step 8 — 리포트

    Checks: 뿐 아니라 Matrix: Unverified: Synthetic: Rejected: Created: 를 모두 담아 한 블록으로 출력한다.

  9. Step 9 — PR 코멘트 게시

    [OK]/[WARN] 이고 post_comment=1 일 때만 리포트 블록을 그대로 대상 PR 코멘트로 남긴다. [FAIL] 은 게시하지 않고, 게시 실패는 경고일 뿐 정지가 아니다.

05

주의사항

  • 검증 전 단언 3종(체크아웃 · 전환 적용 · 비가림) 중 하나라도 실패하면 측정하지 않고 정지한다. 측정하지 않은 통과를 보고하지 않는다.
  • 소스 코드는 읽기 전용 — 수정은 gh:issue-create 로 신규 이슈로만 나간다. 커밋도 push 도 하지 않는다.
  • 앱 데이터에는 쓰기를 한다. dev/fake 스택 전용이며, 그래서 비로컬 호스트는 --allow-remote-host 없이 접속하지 않는다.
  • 사용자가 띄운 서버를 죽이지 않는다 — --start 로 스킬이 띄운 것만 정리한다.
  • 근거 없는 발견, 자기 반증을 통과하지 못한 후보는 이슈로 만들지 않는다. 아무것도 안 나오면 이슈를 만들지 않는다.
  • 이슈는 dotfiles 가 아니라 대상 프로젝트 레포에 만들고, 생성 직전 그 레포를 출력한다.
  • 못 찾은 값을 추측하지 않고, 축소한 커버리지를 숨기지 않고, 자격증명을 로그 · 이슈 본문 · 레시피 캐시에 남기지 않는다.