From c6fc58aecc6b5df35dfbce4c4e2cd7269ea3b980 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Apr 2026 05:11:35 +0000 Subject: [PATCH] =?UTF-8?q?docs(spec):=20unify=20Daemon=20tick=20loop=20or?= =?UTF-8?q?der=20to=20collect=E2=86=92evaluate=E2=86=92advance=E2=86=92exe?= =?UTF-8?q?cute=E2=86=92cron?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All spec documents now consistently follow the DESIGN.md canonical loop order. Changes: - daemon.md: add evaluator.evaluate() to summary loop pseudocode - lifecycle-hook.md: insert evaluate step, renumber steps 2→5, remove stale force_trigger("evaluate") call - queue-state-machine.md: replace "evaluate cron" with "Evaluator (Daemon tick)" - DESIGN.md: fix Actor table to "수집→분류→전이→실행→반영" order - Replace all v6 "evaluate cron" references with "Evaluator (Daemon tick)" https://claude.ai/code/session_01Qfqe81zxg7nS4yhNeALiVP --- spec/DESIGN.md | 4 ++-- spec/concerns/agent-workspace.md | 6 +++--- spec/concerns/cli-reference.md | 2 +- spec/concerns/daemon.md | 5 +++-- spec/concerns/lifecycle-hook.md | 10 ++++++---- spec/concerns/queue-state-machine.md | 6 +++--- 6 files changed, 18 insertions(+), 15 deletions(-) diff --git a/spec/DESIGN.md b/spec/DESIGN.md index c7aafa4..70815dc 100644 --- a/spec/DESIGN.md +++ b/spec/DESIGN.md @@ -28,7 +28,7 @@ stagnation이 감지 = 실패 패턴을 분석하고, 사고를 전환하 |-------|------|---------| | **운영자** | Belt를 설치·설정·모니터링하는 사람 | workspace.yaml 작성, `belt start`, TUI dashboard, HITL 응답 | | **이슈 작성자** | GitHub에 이슈를 등록하는 개발자/PM | 이슈 등록 + belt 라벨 부착 → Belt가 자동 수집 | -| **Belt Daemon** | 자율 실행 프로세스 | 수집 → 전이 → 실행 → 분류 → 반영 루프 | +| **Belt Daemon** | 자율 실행 프로세스 | 수집 → 분류 → 전이 → 실행 → 반영 루프 | | **LLM Agent** | handler prompt를 실행하는 AI (Claude, Gemini, Codex) | Daemon이 subprocess로 호출, worktree 안에서 실행 | | **GitHub** | 이슈/PR 소스 시스템 | DataSource.collect()가 `gh` CLI로 이슈 조회, on_done script가 PR 생성 | | **Cron Engine** | 주기 작업 스케줄러 | evaluate, gap-detection, hitl-timeout 등 내부 주기 실행 | @@ -400,7 +400,7 @@ Phase 2: handler 실행기 → Task trait 제거 Phase 3: evaluate + escalation - → evaluate cron (CLI 도구 호출), force_trigger + → Evaluator (Daemon tick, Progressive Pipeline) → escalation 정책, on_done/on_fail, Failed 상태 Phase 4: Agent + slash command diff --git a/spec/concerns/agent-workspace.md b/spec/concerns/agent-workspace.md index b0ecf7b..d449d70 100644 --- a/spec/concerns/agent-workspace.md +++ b/spec/concerns/agent-workspace.md @@ -2,7 +2,7 @@ > `belt agent` = 대화형 + 비대화형 LLM 세션. 자연어로 시스템을 조회하고 조작하는 통합 인터페이스. > -> 분류(Done or HITL)는 **코어 evaluate cron**이 담당한다. Agent는 분류기가 아니다. +> 분류(Done or HITL)는 **코어 Evaluator (Daemon tick)**가 담당한다. Agent는 분류기가 아니다. --- @@ -48,7 +48,7 @@ Evaluator (Daemon tick에서 Executor보다 먼저 실행): belt agent # 글로벌 rules 로드, 대화형 세션 시작 belt agent --workspace workspace.yaml # workspace 지정 대화형 세션 -# 비대화형 실행 (evaluate cron이 호출) +# 비대화형 실행 (Evaluator가 호출) belt agent -p "프롬프트" # 글로벌 rules로 비대화형 실행 belt agent --workspace workspace.yaml -p "프롬프트" # workspace 지정 비대화형 실행 @@ -240,5 +240,5 @@ Evaluator의 SemanticStage가 내부적으로 `belt agent -p`를 호출한다. - [DESIGN-v6](../DESIGN-v6.md) — QueuePhase 상태 머신 + evaluate 위치 - [CLI 레퍼런스](./cli-reference.md) — CLI 전체 커맨드 트리 -- [Cron 엔진](./cron-engine.md) — evaluate cron +- [Cron 엔진](./cron-engine.md) — 품질 루프 (gap-detection 등) - [Data Model](./data-model.md) — 컨텍스트 모델 (belt context 출력) diff --git a/spec/concerns/cli-reference.md b/spec/concerns/cli-reference.md index b51eea0..df3e2c8 100644 --- a/spec/concerns/cli-reference.md +++ b/spec/concerns/cli-reference.md @@ -62,7 +62,7 @@ belt │ ├── pause / resume / remove / trigger ├── agent ← 서브커맨드 없이 실행 시 대화형 세션 시작 │ ├── [default] # 대화형 세션 (글로벌 rules 로드) -│ ├── [-p ] # 비대화형 실행 (evaluate cron이 호출) +│ ├── [-p ] # 비대화형 실행 (Evaluator가 호출) │ ├── [--workspace ] # 대상 workspace 지정 │ ├── [--plan] # 실행 계획만 출력 │ ├── [--json] # JSON 출력 diff --git a/spec/concerns/daemon.md b/spec/concerns/daemon.md index 3833678..e46402d 100644 --- a/spec/concerns/daemon.md +++ b/spec/concerns/daemon.md @@ -33,6 +33,7 @@ Daemon은 상태 머신을 순회하며 전이를 결정하고 hook을 트리거 Daemon (CPU) loop { collector.collect() + evaluator.evaluate() // 판정 — 실행보다 먼저 advancer.advance() executor.execute() // handler 실행 + hook 트리거 cron_engine.tick() @@ -103,7 +104,7 @@ max_concurrent: 4 ``` - **workspace.concurrency**: workspace yaml 루트에 정의. "이 프로젝트에 동시에 몇 개까지 돌릴까". 모든 source의 아이템 합산 기준. -- **daemon.max_concurrent**: "머신 리소스 한계" (evaluate cron의 LLM 호출도 slot을 소비) +- **daemon.max_concurrent**: "머신 리소스 한계" (Evaluator의 LLM 호출도 slot을 소비) Advancer는 `Ready → Running` 전이 시 두 제한을 모두 확인한다. @@ -352,4 +353,4 @@ SIGINT → on_shutdown: - [Stagnation Detection](./stagnation.md) — Composite Similarity + Lateral Thinking - [DataSource](./datasource.md) — 수집/컨텍스트 추상화 - [AgentRuntime](./agent-runtime.md) — LLM 실행 추상화 -- [Cron 엔진](./cron-engine.md) — evaluate cron + 품질 루프 +- [Cron 엔진](./cron-engine.md) — 품질 루프 (gap-detection 등) diff --git a/spec/concerns/lifecycle-hook.md b/spec/concerns/lifecycle-hook.md index 977413d..c227294 100644 --- a/spec/concerns/lifecycle-hook.md +++ b/spec/concerns/lifecycle-hook.md @@ -193,11 +193,14 @@ loop { items = source.collect() queue.push(Pending, items) - // 2. 전이 (Advancer) — 변경 없음 + // 2. 판정 (Evaluator) — 실행보다 먼저 + evaluator.evaluate() + + // 3. 전이 (Advancer) — 변경 없음 advancer.advance_pending_to_ready() advancer.advance_ready_to_running(limit) - // 3. 실행 (Executor) + // 4. 실행 (Executor) for item in queue.get_new(Running): binding = lookup_workspace_binding(item) hook = binding.hook @@ -216,9 +219,8 @@ loop { break else: item.transit(Completed) - force_trigger("evaluate") - // 4. cron tick — 변경 없음 + // 5. cron tick — 변경 없음 cron_engine.tick() } diff --git a/spec/concerns/queue-state-machine.md b/spec/concerns/queue-state-machine.md index e1ddade..a20eaa4 100644 --- a/spec/concerns/queue-state-machine.md +++ b/spec/concerns/queue-state-machine.md @@ -126,7 +126,7 @@ QueueItem::builder() │ │ replan → HITL(replan) ────┤│ │ │ └───────────────────────────────┘│ │ │ │ │ - │ evaluate cron (per-item) │ │ + │ Evaluator (per-item, Daemon tick) │ │ │ (LLM이 belt queue done/hitl CLI 호출) │ │ │ │ │ ┌────┴────┐ │ │ @@ -225,7 +225,7 @@ Completed는 **안전한 대기 상태**. evaluate가 실패하든 CLI가 실패 | 실패 유형 | 동작 | 상태 | |-----------|------|------| -| evaluate LLM 오류/timeout | Completed 유지, 다음 cron tick에서 재시도 | Completed | +| evaluate LLM 오류/timeout | Completed 유지, 다음 Daemon tick에서 재시도 | Completed | | evaluate 반복 실패 (N회) | HITL로 에스컬레이션 | → HITL | | CLI 호출 실패 (`belt queue done/hitl`) | Completed 유지 + 에러 로그, 다음 tick 재시도 | Completed | | on_done script 실패 | Failed 상태 (on_fail은 실행하지 않음 — handler 실패가 아니므로) | → Failed | @@ -282,6 +282,6 @@ Completed는 **안전한 대기 상태**. evaluate가 실패하든 CLI가 실패 - [Stagnation Detection](./stagnation.md) — 반복 패턴 감지 + lateral thinking - [LifecycleHook](./lifecycle-hook.md) — 상태 전이 반응 trait - [DataSource](./datasource.md) — 수집/컨텍스트 + escalation 정책 -- [Cron 엔진](./cron-engine.md) — evaluate cron + force_trigger +- [Cron 엔진](./cron-engine.md) — 품질 루프 (gap-detection 등) - [실패 복구와 HITL](../flows/04-failure-and-hitl.md) — 실패/HITL 시나리오 - [Data Model](./data-model.md) — 테이블 스키마, 도메인 enum