feat: add auto-approve visibility status and events APIs

파트라슈 · 파트라슈 · commit d73d9f8938f4 · 2026-03-04T23:34:57.000+09:00
diff --git a/.env.example b/.env.example
@@ -49,5 +49,8 @@ MAESTRO_AUTO_APPROVE_COOLDOWN_MS=0
 # true면 정책 매칭/이벤트만 수행하고 실제 git merge는 실행하지 않음
 MAESTRO_AUTO_APPROVE_DRY_RUN=false
 
+# 자동승인 정책/실행 이벤트 로그 최대 저장 개수 (기본 500, 최소 50, 최대 5000)
+MAESTRO_AUTO_APPROVE_LOG_MAX_ITEMS=500
+
 # 승인 이력 링버퍼 최대 저장 개수 (기본 300, 최소 40, 최대 2000)
 MAESTRO_HISTORY_MAX_ITEMS=300
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ Maestro는 AI 에이전트가 생성하거나 수정한 코드 변경을 "승인
 - 기본 `HOST=127.0.0.1` + `ALLOWED_ORIGINS` 화이트리스트 기반 CORS 적용
 - 승인 이력 악보뷰(`WP-009`): `GET /api/history` + `HISTORY_APPEND` 실시간 히스토리 패널
 - `function bach`: 상단 미니 플레이어에서 YouTube 기반 BGM 재생/일시정지/볼륨/채널 URL 등록
-- 조건부 자동승인(`WP-008`) 2차: explicit/cooldown/dry-run/중복승인 차단 가드레일 반영 (기본 `OFF`)
+- 조건부 자동승인(`WP-008`) 2~3차: explicit/cooldown/dry-run/중복승인 차단 + 운영 가시성 API(`GET /api/auto-approve/status`, `GET /api/auto-approve/events`) 반영
 
 ## 현재 개발 현황 (2026-03-04 기준)
 
@@ -50,7 +50,7 @@ Maestro는 AI 에이전트가 생성하거나 수정한 코드 변경을 "승인
   - 원클릭 실행 경로(`npm run start:app`, `npm run check:env`) 제공
   - `start:app` 오류 조치 메시지/대시보드 URL 자동 감지 고도화
 - 확인된 개선 필요 항목
-  - 조건부 자동승인(`WP-008`) 3차 운영 가시성(API/로그) 고도화 필요
+  - 조건부 자동승인(`WP-008`) 운영 API 기반 대시보드 UI 가시화(후속)
   - `KI-001` `function bach` Hz 미노출 환경 원인 분석/재현 확보 필요
 
 ## 변경 필요 항목 및 작업계획
@@ -59,7 +59,7 @@ Maestro는 AI 에이전트가 생성하거나 수정한 코드 변경을 "승인
 
 즉시 진행할 핵심 3가지:
 
-1. P1 조건부 자동승인(`WP-008`) 3차: 운영 가시성 API/로그 확장
+1. P1 조건부 자동승인 운영 UI(운영 API 시각화) 고도화
 2. P2 승인 이력(`WP-009`) 3차: 악보 시각화 고도화 + 접근성 마감
 3. P2 문서/운영 동기화: 실행 표준 경로와 장애 대응 가이드 지속 업데이트
 
@@ -110,6 +110,13 @@ curl -X POST http://localhost:8080/api/request \
 
 조건부 자동승인에서 명시 플래그를 요구하도록 설정했다면(`MAESTRO_AUTO_APPROVE_REQUIRE_EXPLICIT=true`), 요청 본문에 `"autoApprove": true`를 포함해야 자동승인 대상이 됩니다.
 
+운영 상태 확인 API 예시:
+
+```bash
+curl -s http://localhost:8080/api/auto-approve/status | jq
+curl -s "http://localhost:8080/api/auto-approve/events?limit=20" | jq
+```
+
 ## 설치 가이드 (Installation)
 
 자세한 설치/사용법은 [USER_GUIDE.md](USER_GUIDE.md)를 참고하세요.
diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -112,6 +112,7 @@ cp .env.example .env
 | `MAESTRO_AUTO_APPROVE_REQUIRE_EXPLICIT` | `false` | `autoApprove=true` 명시 요청만 자동승인할지 여부 |
 | `MAESTRO_AUTO_APPROVE_COOLDOWN_MS` | `0` | 자동승인 시도 간 최소 간격(ms) |
 | `MAESTRO_AUTO_APPROVE_DRY_RUN` | `false` | 정책 매칭만 수행하고 실제 merge는 건너뜀 |
+| `MAESTRO_AUTO_APPROVE_LOG_MAX_ITEMS` | `500` | 자동승인 정책/실행 이벤트 로그 최대 저장 개수 (50~5000) |
 | `MAESTRO_HISTORY_MAX_ITEMS` | `300` | 승인 이력 링버퍼 최대 저장 개수 (40~2000) |
 
 예시 `.env`:
@@ -130,6 +131,7 @@ MAESTRO_AUTO_APPROVE_MAX_DESC_LENGTH=180
 MAESTRO_AUTO_APPROVE_REQUIRE_EXPLICIT=false
 MAESTRO_AUTO_APPROVE_COOLDOWN_MS=0
 MAESTRO_AUTO_APPROVE_DRY_RUN=false
+MAESTRO_AUTO_APPROVE_LOG_MAX_ITEMS=500
 MAESTRO_HISTORY_MAX_ITEMS=300
 ```
 
@@ -222,6 +224,18 @@ sh hooks/notify-maestro.sh feature/test-branch "테스트 커밋" "실제 통신
 조건부 자동승인을 켠 경우(`MAESTRO_AUTO_APPROVE_ENABLED=true`), 정책에 일치하는 요청은 대시보드 수동 입력 없이 자동 병합 시도가 수행됩니다.
 `MAESTRO_AUTO_APPROVE_REQUIRE_EXPLICIT=true`를 함께 사용하면 요청 본문에 `"autoApprove": true`를 넣은 요청만 자동승인 대상으로 처리됩니다.
 
+운영 가시성 API:
+
+```bash
+# 자동승인 설정/런타임 상태 + 최근 이벤트
+curl -s http://localhost:8080/api/auto-approve/status | jq
+
+# 자동승인 이벤트 로그 조회 (필터 가능)
+curl -s "http://localhost:8080/api/auto-approve/events?limit=20&decision=BLOCKED" | jq
+```
+
+`MAESTRO_SERVER_TOKEN`을 설정한 경우 위 API도 `Authorization: Bearer <token>` 헤더가 필요합니다.
+
 ---
 
 ## 롤백(UNDO) 사용법
diff --git a/docs/DEV_LOG_2026-02-28.md b/docs/DEV_LOG_2026-02-28.md
@@ -37,6 +37,7 @@
 | 2026-03-01 09:30+ | (working tree) | `WP-008` 2차: explicit/cooldown/dry-run + 중복 승인 방지 + 서버 회귀 확장 |
 | 2026-03-04 20:50+ | (working tree) | `WP-009` 상세설계 + 전문가 관점 설계 검증 문서화 |
 | 2026-03-04 22:40+ | (working tree) | `WP-009` 1~2차 구현: history buffer/API/`HISTORY_APPEND` + 히스토리 패널/필터/`H` 토글 + 회귀/QA/E2E/스모크 통과 |
+| 2026-03-04 23:30+ | (working tree) | `WP-008` 3차 완료: `/api/auto-approve/status` + `/api/auto-approve/events` + 운영 로그 링버퍼 + 서버 회귀/QA/E2E/스모크 통과 |
 
 ## 3) 이번 구간 성과
 
@@ -83,8 +84,8 @@
 
 ## 6) 다음 단계
 
-1. 다음 우선순위: `WP-008` 3차 구현(운영 가시성 API/로그 고도화)
-2. 다음 우선순위: `WP-009` 3차 구현(악보 시각화 고도화/접근성 마감)
+1. 다음 우선순위: `WP-009` 3차 구현(악보 시각화 고도화/접근성 마감)
+2. 다음 우선순위: `WP-008` 운영 API UI 시각화(대시보드 통합)
 3. `KI-001`(`function bach` Hz 미노출 환경) 분리 추적 유지
 
 ## 7) 다음 회고에서 반드시 비교할 지표
diff --git a/docs/QA_AGENT.md b/docs/QA_AGENT.md
@@ -43,6 +43,10 @@ npm run smoke:integration
   - 토큰 비활성: `200`
   - 토큰 활성 + 미인증/오인증: `401`
   - 토큰 활성 + 정인증: `200`
+- 자동승인 운영 API 분기
+  - `GET /api/auto-approve/status` 응답 구조/요약 값 검증
+  - `GET /api/auto-approve/events` limit/filter(`requestId`, `decision`, `reason`) 검증
+  - 토큰 활성 시 운영 API 미인증 요청 `401` 검증
 - CORS 정책 분기
   - 허용 Origin preflight: `204` + `Access-Control-Allow-Origin`
   - 비허용 Origin preflight/request: `403`
diff --git a/docs/WORK_PLAN.md b/docs/WORK_PLAN.md
@@ -41,7 +41,7 @@
 - `WP-005` 완료: 서버/UI/E2E + CI 게이트 + 통합 스모크(`npm run smoke:integration`) 반영
 - `WP-006` 완료: `check:env` preflight + `start:app` 원클릭 런처 + 가이드 반영
 - `WP-007` 진행중: 1차(상수/유틸 분리) + 2차(UI 컴포넌트 분해) + 3차(게임/입력/WebSocket 훅 분리) 완료
-- `WP-008` 진행중: 1차(정책 골격) + 2차(가드레일/중복승인 방지/운영스위치) 완료
+- `WP-008` 완료: 1차(정책 골격) + 2차(가드레일/중복승인 방지/운영스위치) + 3차(운영 가시성 API/로그) 완료
 - `WP-009` 진행중: 1차(서버 이력 버퍼/API) + 2차(히스토리 패널/필터/토글) 완료
 - QA 에이전트 설정 완료: `npm run qa` + 회귀 테스트 스위트 + QA 가이드 추가
 - `function bach` 1차 완료: 상단 미니 플레이어, 채널 URL 저장, 재생/일시정지/볼륨, 주파수(Hz) 시각화 반영
@@ -50,8 +50,8 @@
 
 ## 1-2) 다음 작업 포인트 (즉시 실행)
 
-1. `WP-008` 3차 구현: 운영 가시성(자동승인 사유/상태 로그 API) 강화
-2. `WP-009` 3차 구현: 악보 시각화(레인/밀도 표현) 고도화 + 접근성 마무리
+1. `WP-009` 3차 구현: 악보 시각화(레인/밀도 표현) 고도화 + 접근성 마무리
+2. `WP-008` 운영 API UI화: 운영 지표를 대시보드에서 시각 확인 가능하도록 확장
 3. `KI-001` 분리 추적: `function bach` Hz 미노출 환경 재현/원인 수집
 
 ## 1-6) `WP-009` 상세설계/전문가 검증 상태 (2026-03-04)
@@ -72,7 +72,9 @@
   - 1, 2, 4 완료 (`npm run qa`, `npm run test:e2e`, `npm run smoke:integration` 통과)
   - 3은 다음 스프린트에서 시각화 고도화로 진행
 
-## 1-5) `WP-008` 상세 실행계획 및 진행 상태 (2026-03-01)
+## 1-5) `WP-008` 상세 실행계획 및 진행 상태 (2026-03-04)
+
+- 3차 상세계획 문서: [`docs/WP-008_PHASE3_OPERABILITY_PLAN.md`](./WP-008_PHASE3_OPERABILITY_PLAN.md)
 
 고정 순서:
 
@@ -88,6 +90,7 @@
 | 정책 조건 조합 | `trustedAgents`/`branchPrefix`/`maxDescriptionLength` + `requireExplicit` + `cooldown` 평가 | `/api/request` 응답의 `autoApprove.reason`으로 차단 사유 확인 가능 | 완료 |
 | 중복 승인 방지 | 요청 상태맵(`ready/approving/merged/rejected`) + 중복 `APPROVE` 차단 | 동일 `requestId` 재승인 시 `MERGE_SKIPPED` 반환 | 완료 |
 | 운영 스위치 | `dryRun` 모드에서 정책 매칭만 수행, merge 미실행 | `AUTO_APPROVE_SKIPPED` 이벤트 확인 가능 | 완료 |
+| 운영 가시성 API/로그 | `/api/auto-approve/status`, `/api/auto-approve/events` + 링버퍼 로그(`MAESTRO_AUTO_APPROVE_LOG_MAX_ITEMS`) | 정책 판정/실행 결과를 API로 추적 가능 | 완료 |
 | 회귀 테스트 | 서버 회귀에 explicit/cooldown/dry-run/duplicate 케이스 추가 | `npm run qa` 통과 | 완료 |
 
 ## 1-3) 즉시 실행 결과 (2026-02-28)
diff --git a/docs/WP-008_PHASE3_OPERABILITY_PLAN.md b/docs/WP-008_PHASE3_OPERABILITY_PLAN.md
@@ -0,0 +1,126 @@
+# WP-008 3차 상세계획: 조건부 자동승인 운영 가시성
+
+기준일: 2026-03-04
+대상: Maestro Coding `WP-008` 3차
+
+## 1) 목표
+
+- 자동승인 정책 판정과 실행 결과를 운영자가 API만으로 추적할 수 있게 한다.
+- 기존 승인/반려/롤백/히스토리/function bach UX를 손상하지 않는다.
+- 보안 기준(`MAESTRO_SERVER_TOKEN`)과 동일한 접근제어를 유지한다.
+
+## 2) 전문가 검토 요약
+
+### A. Product/Ops 전문가
+
+- 필요 최소 정보:
+  - 현재 정책(활성화 여부, dry-run, cooldown, explicit)
+  - 현재 런타임 상태(in-flight, 최근 성공/실패 시각, 요청 상태 분포)
+  - 최근 이벤트 로그(왜 승인/차단됐는지 reason)
+- 결론: `status` + `events` 2개 API면 운영 추적 가능.
+
+### B. Backend 전문가
+
+- 메모리 링버퍼가 MVP+ 단계에서 가장 안전하고 빠름.
+- 이벤트 생성 지점:
+  1. `/api/request` 정책 판정 직후
+  2. `runConditionalAutoApprove` 실행 시작/스킵/성공/실패
+- 환경변수:
+  - `MAESTRO_AUTO_APPROVE_LOG_MAX_ITEMS` (기본 500)
+
+### C. Security 전문가
+
+- 운영 API는 상태/정책 정보를 포함하므로 token 모드에서는 인증 필수.
+- 민감값(토큰, 절대 경로)은 응답에서 제외.
+- allowlist 필드로만 로그 저장.
+
+### D. QA 전문가
+
+- 서버 회귀 필수 케이스:
+  - `GET /api/auto-approve/status` 응답 구조 검증
+  - `GET /api/auto-approve/events` limit/filter 검증
+  - token 설정 시 운영 API 401 검증
+  - cooldown/dry-run 케이스 reason 로그 검증
+
+## 3) 구현 범위
+
+포함:
+- `GET /api/auto-approve/status`
+- `GET /api/auto-approve/events`
+- 자동승인 이벤트 링버퍼 및 append 로직
+- `.env.example`, README/가이드/워크플랜/QA 문서 동기화
+- 서버 회귀 테스트 보강
+
+제외:
+- DB 영속 저장
+- 외부 로그 수집기 연동
+- 프론트 운영 대시보드 UI 추가
+
+## 4) API 스펙
+
+### GET `/api/auto-approve/status`
+
+응답 예시:
+
+```json
+{
+  "config": {
+    "enabled": true,
+    "dryRun": false,
+    "requireExplicit": true,
+    "cooldownMs": 60000,
+    "maxDescriptionLength": 180,
+    "branchPrefix": "feature/",
+    "trustedAgents": ["qa_agent"],
+    "trustedAgentsCount": 1
+  },
+  "runtime": {
+    "inFlightCount": 0,
+    "trackedRequestCount": 3,
+    "requestStateSummary": {
+      "ready": 1,
+      "approving": 0,
+      "merged": 1,
+      "rejected": 1
+    },
+    "lastAutoApproveAt": "2026-03-04T13:01:00.000Z",
+    "autoApproveEventCount": 12
+  },
+  "recentEvents": [],
+  "count": 12
+}
+```
+
+쿼리:
+- `eventsLimit` (기본 40, 최대 300)
+
+### GET `/api/auto-approve/events`
+
+쿼리:
+- `limit` (기본 40, 최대 300)
+- `requestId` (선택)
+- `decision` (선택: `ELIGIBLE|BLOCKED|EXECUTING|SKIPPED|MERGED|FAILED`)
+- `reason` (선택)
+
+응답:
+
+```json
+{
+  "items": [],
+  "count": 0,
+  "maxItems": 500
+}
+```
+
+## 5) 검증 게이트
+
+1. `npm run test:server`
+2. `npm run qa`
+3. `npm run test:e2e`
+4. `npm run smoke:integration`
+
+## 6) 완료 기준
+
+- 운영 API가 정책/실행 가시성을 제공한다.
+- 보안/회귀 테스트가 모두 통과한다.
+- 문서와 `.env.example`가 실제 코드와 일치한다.
diff --git a/maestro-server.js b/maestro-server.js
diff --git a/tests/server-regression.test.mjs b/tests/server-regression.test.mjs
