로컬 E2E 검증 하네스(실제 HAL·포털·Agent 4대 + 가짜 Webmaker·AriMail·메일)와 34개 완료 조건 흐름 기록

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/verification/README.md

@@ -0,0 +1,38 @@
+# 검증 기록(docs/verification)
+
+이 디렉터리에는 Ariweb Suite 의 **로컬 종단 간 검증 하네스**(`test/e2e/`)가 만든 기록이 쌓인다. 개발 지시 "Release 0.1.1 완료 조건" 34개 흐름을
+실제 HAL·고객 포털·Node Agent 프로세스로 걸어 보고, 흐름마다 다음 판정과 증거(HTTP 상태·최종 화면 상태·작업 단계)를 남긴다.
+
+| 판정 | 뜻 |
+|---|---|
+| 로컬 확인(verified_local) | 로컬 환경에서 끝까지 확인됨 |
+| 부분 확인(partial) | 일부 단계만 확인됨(나머지는 실 인프라가 필요하거나 선행 흐름의 결함으로 막힘) |
+| 로컬 확인 불가(not_verifiable_locally) | 실 DNS·메일 왕복·공인 서버 등이 필요 |
+| 실패(결함)(failed) | 실제 결함으로 보이는 실패 — 보고서의 "발견한 결함" 에 재현 정보 |
+
+**이 기록은 출시 판정이 아니다.** 개발 지시는 각 흐름을 실제 배포 환경에서 최종 화면·외부 접속·실제 메일 왕복·실제 사용량·실제 배포 버전으로 판정하도록 요구한다.
+로컬 하네스는 결함을 빨리 찾고, 실서버 검증 전에 어떤 흐름이 어디까지 동작하는지 드러내는 용도다.
+
+## 실행
+
+```bash
+node --no-warnings test/e2e.test.mjs            # 전체(5분 안에 끝남). docs/verification/local-e2e-<날짜>.md/.json 생성
+ARIWEB_E2E_FLOWS=30-sites,80-hal node --no-warnings test/e2e.test.mjs   # 흐름 그룹 일부만
+ARIWEB_E2E_STRICT=1 node --no-warnings test/e2e.test.mjs                 # failed 판정이 있으면 종료 코드 1
+ARIWEB_E2E_KEEP=1 …                                                      # 임시 디렉터리(test/.tmp/e2e-*) 보존
+ARIWEB_E2E=0 …                                                           # 건너뜀(test/run.mjs 에서 제외하고 싶을 때)
+```
+
+## 하네스 구성(test/e2e/)
+
+- `boot.mjs` — 빈 포트·임시 데이터 디렉터리로 가짜 서비스 → HAL(설정 토큰·릴리스 등록·부트스트랩 → 서버 실행 → 운영자 최초 설정·로그인) → Node Agent 4대(control/web/backup/web, `ARIWEB_AGENT_STUB_CMDS=1` 로 systemctl/nginx/certbot 은 기록만, tar 와 파일 배치는 실제) → 고객 포털(Catalog 자동 시드, AriMail 서버 등록) 순으로 띄운다.
+- `fake-mail.mjs` — Resend 호환 발신 API 포획(가입 확인·초대·필수 알림 메일에서 토큰·링크를 꺼낸다).
+- `fake-webmaker.mjs` — Webmaker 의 포털 연동 면(`/api/internal/ariweb/*` 서명 검증, 프로젝트·저장본·export tar.gz, `/api/auth/sso` 1회용 티켓).
+- `fake-arimail.mjs` — AriMail 의 설정·관리자·사용량 API(도메인별 보장량·경고 구간·제한 사유 계산). SMTP/IMAP 은 없다.
+- `flows/*.mjs` — 흐름 그룹(번호순 실행). 각 단계는 `steps().run()` 으로 증거를 남기며 결함이 보이면 `report.bug()` 로 재현 정보를 적는다. 결함을 우회하지 않고, 막힌 뒤 흐름은 `partial`(선행 흐름 번호) 로 적는다.
+- `report.mjs` — 흐름·결함·실 인프라 필요 항목을 Markdown/JSON 으로 쓴다. 비밀값은 lib/redact 로 가린다.
+
+## 로컬에서 확인할 수 없는 것(실서버·실 DNS 필요)
+
+도메인 소유 확인(TXT)·DNS 반영·HTTPS 발급·외부 접속 확인, 메일 DNS 와 외부 송신·수신·회신 왕복, 실제 서버 간 이전·백업 저장소, 모듈 설치(/srv/ariweb 권한), 재해복구의 실제 다른 호스트 복원.
+이 항목들은 하네스가 `not_verifiable_locally` 또는 `partial` 로 적고 "실제 인프라가 필요한 항목" 절에 모은다.