Rollout Playbook
어떤 화면부터 harness로 옮길지, definition of done을 어떻게 잡을지 단계별로 정리합니다.
reopt design업데이트
1. phase 순서
| 단계 | 초점 | 설명 |
|---|---|---|
| Phase 1 | Runtime recipe abstraction | 완료. explicit recipe runtime 위에 workspace component를 primary API로 올렸습니다. |
| Phase 2 | Project screens rollout | 완료. project overview, audit, data-sources, settings까지 workspace-first recipe로 확산했습니다. |
| Phase 3 | Audit expansion | recipe-screen과 fullscreen-tool을 분리하고, fullscreen routes에는 ShellFullscreenToolSurface contract를 강제합니다. |
| Phase 4 | Smoke + visual proof | recipe별 대표 화면에 브라우저 기준 smoke와 screenshot proof를 붙여 문서 주장을 실제 UI 증거로 닫습니다. |
| Phase 5 | Workspace harness management | Builder `/harnesses`에서 여러 draft harness를 만들고 review gate, demo + workspace live preview, activity history, activate flow까지 묶어 harness를 사용자-facing 운영 도구로 끌어올립니다. |
2. covered recipe screens
아래 표는 Builder rollout registry에서 직접 생성된 현재 contract snapshot입니다. route, expected workspace, recipe가 문서와 audit에서 같은 source를 바라보게 만들었습니다.
| 경로 | 계약 | 감사 포인트 |
|---|---|---|
| /builder/starters | ListWorkspace · list | slots: toolbar · helpers: ShellSection, ShellStateBoundary · adapter: optional |
| /builder/projects/[projectId] | DetailWorkspace · detail | slots: aside · helpers: ShellSection · adapter: optional |
| /builder/projects/[projectId]/audit | ListWorkspace · list | slots: filters, footer · helpers: ShellSection, ShellStateBoundary · adapter: optional |
| /builder/projects/[projectId]/data-sources | ListWorkspace · list | slots: aside · helpers: ShellSection · adapter: ShellDataGridAdapter (DataGrid) |
| /builder/projects/[projectId]/settings | EditorWorkspace · editor | slots: header + content baseline · helpers: ShellSection · adapter: ShellEditorAdapter (Editor) |
3. fullscreen tool 예외
fullscreen tool도 같은 registry에서 생성됩니다. recipe-screen과 구분된 별도 contract를 유지하고, 공통 shell surface를 강제합니다.
| 경로 | 공통 surface | 감사 포인트 |
|---|---|---|
| /builder/projects/[projectId]/blocks | ShellFullscreenToolSurface | required slots: header |
| /builder/projects/[projectId]/theme | ShellFullscreenToolSurface | required slots: header |
| /builder/projects/[projectId]/uxflow | ShellFullscreenToolSurface | required slots: shared shell only |
| /builder/projects/[projectId]/pages/[pageId] | ShellFullscreenToolSurface | required slots: header |
Shared route contract
apps/web/lib/routes.ts
isProjectFullScreen() must cover pathname.includes(`${r.page("")}`.slice(0, -1)), pathname.endsWith(r.blocks()), pathname.endsWith(r.theme()), pathname.endsWith(r.uxflow()) so fullscreen tool routes stay outside the standard recipe-screen contract.
4. Definition of Done
- covered recipe screen은 workspace component를 primary API로 사용하고, explicit recipe metadata는 runtime 내부에서 유지된다.
- header / toolbar / filters / content / aside / footer 구조가 화면 성격에 맞게 명시적으로 정리되었다.
- loading / empty / error copy가 화면 고유 문구가 아니라 harness policy와 맞물린다.
- page width와 density가 ad-hoc className이 아니라 harness policy로 결정된다.
- DataGrid / Editor가 있다면 engine props는 유지되고 chrome만 adapter가 소유한다.
- fullscreen tool 화면은 recipe screen과 구분된 예외 계약으로 분류되고 ShellFullscreenToolSurface를 렌더링한다.
- opt harness doctor와 package lint가 layout과 실화면 경계를 깨는 직접 엔진 사용과 recipe 분류 문제를 잡아낸다.
- recipe별 대표 화면에 smoke + structure proof가 존재한다.
- reviewed draft를 runtime에 올리는 흐름에는 fresh PASS design proof가 포함된다.
- 동일 성격의 다음 화면으로 확산 가능한 패턴이 남았다.
5. 운영 도구와 proof
| 명령 | 역할 |
|---|---|
| opt harness check | rollout registry, generated docs freshness, scaffold bootstrap bundle completeness를 한 번에 검사해 CI gate로 사용합니다. |
| Open `/builder/harnesses` | workspace-owned harness draft를 생성하고 review 탭의 approval state와 compare summary, preview 탭의 demo/live comparison과 proof capture, activity 탭의 audit evidence를 한 흐름으로 검토합니다. |
| opt harness doctor | DESIGN.md, Builder layout, workspace rollout screen, fullscreen-tool surface contract와 scaffold/docs drift를 함께 진단합니다. |
| bun run --filter @reopt-ai/opt-shell lint | package lint와 함께 Builder rollout screen의 adapter/page 경계 위반을 실패로 처리하고 covered screen 규약을 유지합니다. |
| bun run --filter @reopt/web test:e2e | recipe별 대표 화면에 smoke + visual proof를 붙여 실제 브라우저 기준으로 문서 주장을 검증합니다. |
| Activate from `/builder/harnesses/[harnessId]` | 승인된 draft harness 중 fresh PASS proof를 가진 후보만 workspace active policy로 승격하고 Builder runtime layout에 즉시 반영한 뒤 activity feed에 actor/role/context audit evidence를 남깁니다. |
| bun run --filter @reopt-ai/opt-shell scaffold -- --kind workspace ... | 새 recipe screen과 fullscreen tool을 raw page composition 대신 harness-owned skeleton에서 시작합니다. |
Save before review
Preview proof와 review request는 저장된 draft definition을 기준으로만 평가합니다.
Meaningful diff required
active baseline과 의미 있는 차이가 없으면 review request와 approval이 409로 막힙니다.
Edits reset review
review 이후 저장된 수정이 생기면 status는 다시 DRAFT로 내려가고 audit evidence가 남습니다.
APPROVED required
activate는 APPROVED draft만 통과시키며, active runtime 반영 전 review state를 다시 확인합니다.
Design alignment required
alignment score가 review 상태면 APPROVED여도 activate가 409 design_review_required로 막힙니다.
Fresh design proof required
Preview에서 현재 draft hash와 일치하는 PASS proof를 다시 캡처해야 activate readiness가 닫힙니다.
Bootstrap bundle required
새 route는 entry, contract, preview fixture, docs, test, guard matrix를 같이 유지해야 bootstrap-ready로 간주합니다.
6. design proof gate
rollout completion은 더 이상 heuristic alignment만으로 닫히지 않습니다. Builder Manager는 review와 activate 사이에 fresh design proof를 요구하고, proof hash가 draft와 어긋나면 다시 Preview로 돌아가도록 만듭니다.
Save the current draft
proof는 unsaved local state가 아니라 저장된 candidate definition hash를 기준으로 생성됩니다.
Preview against a real context
Demo Fixtures 또는 Workspace Live에서 candidate와 active를 나란히 보고 route-specific evidence를 수집합니다.
Capture proof
saved proof는 fixture, source mode, required slots, DOM summary, alignment snapshot을 append-only audit에 남깁니다.
Re-capture after edits
draft definition이 바뀌면 기존 proof는 stale이 되며 activate는 409 design_proof_stale로 막힙니다.
Activate only with PASS proof
APPROVED, alignment pass, fresh PASS proof가 모두 닫혀야 activate가 최종 runtime 승격을 허용합니다.
7. scaffold 전략
rollout이 넓어질수록 첫 파일을 어떤 골격에서 시작하느냐가 중요합니다. `opt-shell scaffold`는 workspace와 fullscreen-tool용 기본 skeleton을 생성해, 새 화면이 raw `div` 조합이나 direct engine render로 시작되지 않도록 만듭니다.
Workspace scaffold
`--workspace list|detail|editor|dashboard`와 slot flags를 받아 `PageHeader`, `ShellSection`, `ShellStateBoundary`가 포함된 기본 골격을 만듭니다.
Fullscreen scaffold
`ShellFullscreenToolSurface`와 shared header/footer slot을 기본으로 생성해 fullscreen 예외도 bespoke shell로 새지 않게 합니다.
| Artifact | 파일 규약 | 역할 |
|---|---|---|
| Entry | page.tsx | workspace recipe 또는 fullscreen-tool surface를 시작하는 실제 route entry입니다. |
| Contract | .harness-contract.ts | route kind, required slots, artifact graph, verification scenario를 선언합니다. |
| Preview fixture | .harness-preview.fixture.ts | candidate/default/proof drift 상태를 preview와 review loop에서 재현하는 bootstrap fixture입니다. |
| Docs note | .harness-doc.md | route-specific rollout note와 artifact 연결 상태를 소스 옆에서 유지합니다. |
| Test stub | .harness.test.ts | generated bundle이 aligned 상태로 시작하는지 확인하고 route 전용 scenario test로 확장합니다. |
| Guard matrix | .harness-guard-matrix.md | review, design proof, activation blocker, verification matrix를 sidecar 문서로 유지합니다. |
Bootstrap verification matrix
save_persists_candidate, review_requires_meaningful_diff, review_reset_after_edit, activation_requires_design_proof, stale_proof_blocks_activation, design_drift_blocks_activation, activation_promotes_reviewed_candidate
8. 피해야 할 안티패턴
- 각 화면에서 adapter chrome을 다시 찢어 놓고 bespoke wrapper를 만드는 것
- harness 도입과 동시에 도메인 상태 모델까지 전부 재설계하는 것
- state boundary를 생략한 채 spinner나 empty copy를 개별 컴포넌트 안에 숨기는 것
- fullscreen tool 화면을 일반 recipe screen처럼 취급해 breadcrumb layout 규약을 강제로 씌우는 것
- fullscreen tool 화면마다 bespoke full-height shell을 새로 만들어 ShellFullscreenToolSurface contract를 우회하는 것
- covered recipe screen이 계속 low-level page composition에만 머물러 workspace-first 방향을 막는 것
- opt-ui primitive까지 harness에서 다시 re-export하여 경계를 흐리는 것
9. coverage tracking
computeShellCoverage()는 라우트 파일 목록과 contract registry의 rollout target을 비교하여 하네스 채택률을 수치화합니다.
- totalRouteFiles — 발견된 전체 라우트 파일 수
- coveredRouteFiles — rollout target에 매칭된 파일 수
- coveragePercent — 커버리지 퍼센트 (0-100)
- recipeBreakdown — recipe별 target 수
- uncoveredPaths — 미커버 경로 목록
computeShellCoverage() (@reopt-ai/opt-cli/audit)를 호출하면 커버리지 리포트를 그대로 얻을 수 있습니다.
10. pattern search
searchShellPatterns(query)는 하네스의 recipe, slot, policy, adapter, audit-rule, anti-pattern 패턴을 키워드로 검색합니다. Agent가 전체 컨텍스트를 읽지 않고 필요한 패턴만 조회할 수 있습니다.
- 50+ 패턴 엔트리 자동 인덱싱
- 키워드 매칭 + tag/title 보너스 점수로 랭킹
- 카테고리: recipe, slot, policy, adapter, audit-rule, anti-pattern
11. PR review & SARIF
findingsToSARIF()는 audit finding을 SARIF 2.1.0 포맷으로 변환하여 GitHub Code Scanning에 업로드할 수 있습니다. generatePRReviewComments()는 finding을 PR 인라인 댓글 형태로 변환합니다.
- SARIF 출력 →
github/codeql-action/upload-sarif통합 - PR 댓글 → finding별 severity badge + fix snippet 포함
- W3C DTCG 토큰 export →
exportShellTokensDTCG()로 Figma/Tokens Studio 호환 JSON 생성