Agent Contract

1. 기본 우선순위

2. 작업 모델

에이전트는 먼저 루트 `DESIGN.md`로 look and feel을 읽고, 그 다음 현재 화면이 어떤 작업 흐름인지 분류한 뒤 recipe와 adapter를 선택해야 합니다. 현재 runtime에서는 `ListWorkspace` 같은 helper가 우선 진입점이고, `ShellPage recipe="..."`는 escape hatch로 남습니다. 임의 div 조합으로 화면을 완성한 뒤 나중에 harness를 덧씌우는 방식은 허용하지 않습니다. harness는 후처리 테마가 아니라 설계의 시작점이어야 합니다.

managed harness를 다룰 때도 같은 원칙이 적용됩니다. draft를 수정한 뒤 바로 activate하는 것이 아니라 preview로 결과를 확인하고, current hash 기준 fresh proof를 캡처하고, review note와 approval evidence를 남긴 뒤, APPROVED 상태와 DESIGN.md alignment readiness를 모두 만족할 때만 runtime으로 승격해야 합니다. 하네스는 단순 설정 JSON이 아니라 검토 가능한 제품 정책 단위입니다.

3. definition of done

• DESIGN.md의 visual intent와 opt-shell recipe가 충돌하지 않는다.
• 화면이 canonical recipe 중 하나로 설명 가능하다.
• loading / empty / error 상태가 ShellStateBoundary로 통일된다.
• DataGrid / Editor chrome이 adapter ownership 아래 있다.
• page width와 density가 manifest policy로 결정된다.
• managed harness draft는 review를 거쳐 APPROVED가 된 뒤에만 activation 대상이 된다.
• managed harness draft의 design alignment score가 review 상태면 activation 대상이 아니다.
• managed harness draft는 current hash에 연결된 fresh PASS design proof가 없으면 activation 대상이 아니다.
• approved draft를 수정하면 review 상태가 다시 DRAFT로 돌아가 stale approval을 막는다.
• approved draft를 수정하면 이전 design proof도 stale이 되어 다시 proof를 캡처해야 한다.
• scaffold bundle, generated docs, opt harness check/doctor가 현재 contract와 같은 상태를 가리킨다.
• opt harness check/doctor와 package lint가 위반을 잡고 docs가 현재 상태를 반영한다.

covered screen에서는 low-level `ShellPage` 조합보다 workspace-first abstraction이 우선입니다. direct `ShellPage` 사용은 예외로 남겨야 recipe가 단순 label이 아니라 실제 설계 계약으로 기능합니다.

4. enforcement 계층

5. 리뷰 기준

리뷰에서는 "예뻐 보이는가"보다 "harness ownership이 유지되는가"를 먼저 봅니다. 직접 엔진 렌더링, 임의 width override, 상태 UX 분산, recipe 불명확성은 모두 품질 회귀로 취급합니다. 이 기준이 있어야 에이전트 산출물이 팀 내에서 반복 가능해집니다.

managed harness 리뷰에서는 여기에 한 가지가 더 붙습니다. `preview가 충분히 설명력을 가지는가`, `review note와 actor evidence가 남는가`, `승인 전 activation이 막히는가`, `DESIGN.md alignment review 상태가 activation gate에 실제로 연결되는가`, `current draft 기준 fresh design proof가 있는가`, `activity intelligence가 이후 운영 학습으로 남는가`를 함께 봐야 합니다. 그래야 하네스가 단순 개인 설정이 아니라 팀이 공유하는 제품 운영 기준이 됩니다.

6. ESLint 하네스 규칙

@reopt/eslint-config/opt-shell-rules 플러그인이 IDE 실시간 피드백을 제공합니다. CI 시점 감사 외에 개발 중 즉시 위반을 잡습니다.

7. progressive phase disclosure

ShellAgentPhase는 agent에 노출되는 하네스 정보를 개발 단계별로 제한합니다. 한 번에 모든 recipe/slot/policy/adapter를 보여주면 agent 정확도가 떨어지므로, 단계에 맞는 정보만 제공합니다.

8. completeness scoring

computeCompletenessScore()는 audit finding을 7개 카테고리로 분류하고 가중 평균으로 0-100 점수를 산출합니다. agent가 "얼마나 완성됐는지" 임계값 기반 판단을 할 수 있습니다.

Builder 하네스 매니저의 Activation Readiness 체크리스트와 Recipe 탭 사이드바에서 이 점수를 실시간으로 확인할 수 있습니다.