증거와 재개

디렉토리#

runs/<job_id>/                    # 프로젝트 바깥, 비공개 운영 기록
  request.json                   # init 때 받은 입력을 보존
  state.json                     # run_state.py만 수정
  requirements.json / prd.html / prd.md
  receipts/<stage>-<attempt>.json
  evidence/                      # 로그·스냅샷·도구 응답

원본 파일은 init에 전달된 request가 가리키는 위치에서 읽는다. state.json에 원본 request 경로와 내용/첨부 해시를 기록하므로 해당 위치도 유지한다. 스킬 도구는 인증 토큰을 저장하지 않는다.

run_state.py의 CHECKS에 명시된 check를 전부 아래 형식으로 제출한다. 증거는 실행 디렉토리 기준 상대경로 또는 절대경로의 비어 있지 않은 파일이어야 한다. 에이전트가 실제 도구 결과를 파일로 보존하고 의미를 검토한 후 status를 넣는다. scaffold에는 serverpod_codegen(첫 생성 성공 로그), implement에는 serverpod_tests, publish에는 backend_boundary(preview/mock 또는 live/실백엔드 연결 결과)를 포함한다.

{
  "stage": "prd",
  "checks": {
    "source_coverage": {"status": "passed", "evidence": ["evidence/source-coverage.json"]},
    "requirements": {"status": "passed", "evidence": ["prd.html", "requirements.json"]}
  }
}

scaffold, implement, publish는 surfaces에 site/app/console/widgetbook 각각의 status와 evidence를 추가한다. publish에는 source_sha(40자리 Git SHA), run_url(GitHub Actions URL), pages_url(실제 사이트 루트), runtime_mode와 surface별 url도 필요하다. 네 URL은 같은 pages_url 아래 site/, app/, console/, widgetbook/이어야 한다.

모든 단계의 receipt에는 timing(실행 디렉토리 기준 evidence/<stage>-timing.md, 하위 단계 · 시작/끝 · 소요 · 비고 표)이 있어야 한다. 실행끼리 어디서 시간이 늘었는지 비교하기 위한 기록이다. 원장의 start/block/pass 시각으로 계산한 단계별 벽시계는 run_state.py --run-dir <run-dir> timing이 JSON으로 낸다(읽기 전용).

scaffold receipt의 checks.ci_baseline.run_response: 조립 직후 베이스라인에서 돈 Pages 워크플로 run의 gh run view <id> --json headSha,status,conclusion,url,event 실제 응답 보존 경로. 대상 저장소의 Actions run이고 completed/success여야 한다.

publish receipt의 추가 파일 필드:

• build_manifest: build_pages.py가 만든 루트 build.json의 보존 경로
• run_response: gh run view <id> --json headSha,status,conclusion,url 실제 응답 보존 경로
• surfaces.<surface>.served_manifest: 배포 URL에서 수령한 해당 build.json 보존 경로
• timing_summary: 배포 직전 run_state.py timing 출력을 저장한 evidence/timing-summary.json (다섯 단계 전부 포함)
• runtime_mode: live이면 backend.health_url(Pages 밖 HTTPS /readyz)과 backend.health_response({"url": ".../readyz", "status": 200} 형태의 실제 응답 보존 파일)

도구는 이 JSON의 SHA·surface·runtime_mode와 GitHub completed/success를 대조한다. pending CI나 이전 커밋이 CDN에 서빙되는 상태로는 pass할 수 없다. 실제 응답을 만들어내거나 가공하지 않는다.

로그/보고서는 attempt마다 새 이름으로 보존한다. 상위 게이트의 증거가 될 생성물은 snapshot으로 남겨 이후 화면 개발이 원본 파일을 수정해도 증거가 변조된 것으로 판정되지 않게 한다. passed는 모든 파일의 SHA-256도 저장한다. 파일 변경/소실은 stale이며 downstream 시작을 막는다. 이는 증거 파일 무결성 검사다. 실제 CI 성공이나 UI 정합성을 파일 이름만으로 추론하지 않는다.

pending → running → passed
              └→ blocked → running
passed 또는 running/blocked → invalidate → pending (해당 단계와 이후 전부)

start는 앞 단계의 유효한 passed를 요구한다. 동시에 둘을 running으로 만들 수 없다. pass는 running에서만 가능하며 증거가 빠지면 상태를 유지한 채 실패한다. 상태 갱신은 로컬 파일 잠금과 원자적 교체를 사용한다. 작업 중 세션이 죽어 잠금 파일이 남았다면 이전 프로세스가 끝났음을 확인한 뒤 잠금만 제거한다. alive인 실행과 동시 재개하지 않는다.

python3 <skill>/scripts/run_state.py --run-dir <run-dir> start design
python3 <skill>/scripts/run_state.py --run-dir <run-dir> pass design --evidence receipts/design-1.json
python3 <skill>/scripts/run_state.py --run-dir <run-dir> invalidate --from design --reason "Figma 시안 변경"

3-surface schema 1 실행을 재개하면 next_stage: prd로 표시하며 invalidate --from prd로 site/backend 계약부터 다시 확정해야 한다. 오래된 완료 상태를 그대로 재사용하지 않는다. 요청/첨부 변경은 prd부터, Figma/CoUI 디자인 변경은 design부터, 공급 버전 변경은 scaffold부터, 화면 소스 변경은 implement부터, 배포 설정 변경은 publish부터 재검증한다. 요청 내용 자체가 바뀌었으면 가장 보수적으로 prd부터 invalidate해야 입력 해시를 다시 채택한다. 외부 Figma/GitHub 상태는 이 로컬 도구가 자동 감시하지 않는다. resume/status 담당자가 실제 ID로 조회하고 미확인 상태를 그대로 보고한다.

status 출력의 next_stage는 첫 미통과/오래된 단계이다. 마지막 단계가 passed라도 앞의 증거가 변하면 전체 complete는 false다. 동일 request 재전송은 기존 상태를 반환하고 파일을 재생성하지 않는다. request의 job_id/project.root 변경은 같은 실행에 덮어쓸 수 없다.

새 init은 원장에 visual_review_policy: 1을 고정한다. design/implement/publish receipt는 visual_review로 별도 시각 검토 JSON을 참조한다. 원장은 PNG와 보고서·재검토 증거를 모두 해시한다. 누락, Figma/runtime 조건 불일치, 미해결 finding은 pass를 막는다. 기존 원장은 정책 필드가 없어도 종전 증거를 그대로 검증한다. 과거 완료가 새 시각 게이트를 통과했다는 뜻은 아니다. 기존 제품 개선은 새 run에서 검토하며 과거 receipt를 고치지 않는다.