diff --git a/README.ko.md b/README.ko.md index c3d292b..760eaa7 100644 --- a/README.ko.md +++ b/README.ko.md @@ -21,7 +21,9 @@ **업스트림 loop-orchestrator에서 바뀐 단 한 가지:** 계획 단계가 더 이상 선택적·플러거블 role이 아닙니다. **번들된 `wiki-plan` 방법론에 고정**되어 — 비단순 태스크는 코드를 쓰기 전에 모든 설계 결정을 번들 `wiki/`의 페이지로 -라우팅해 계획합니다. 루프의 나머지는 그대로입니다. +라우팅해 계획합니다. v1.17.0부터 이 계획 자체가 **분석 → 설계 → 분해의 +게이트 3단계**로 돌며, 각 단계는 기계 판정을 통과해야 다음으로 넘어갑니다 +(아래 참조). 루프의 나머지는 그대로입니다. 그 위에 dev-loop은 **지식 수집 루프**를 더합니다: 세션이 검증된 인사이트를 방출하면, `knowledge-flush`가 조사·중복제거·라우팅을 거쳐 위키를 키워가는 @@ -73,14 +75,35 @@ Claude Code 플러그인 마켓플레이스로 설치되므로, 스킬과 훅이 기존 상태 파일 폴링이 그대로입니다. 어느 쪽이든 워커 세션은 guardrails `ask`에서 멈추는 대신 에스컬레이션하고, 죽은 워커는 런을 멈추지 않고 빠르게 감지됩니다. -### 스텝 2는 `wiki-plan`에 고정 - -`wiki-plan`은 플래너에게 **위키 라우팅 스윕**을 시킵니다: `INDEX.md`를 읽고, -건드리는 각 도메인의 `index.md`를 읽고, 모든 설계 결정에 대해 그것을 소유한 -페이지를 찾아 — `결정 → 위키 페이지` 맵을 기록합니다. 결정은 구체적인 -값/코드로 적습니다("적절히" 금지). 그래서 구현 패스는 추측하는 대신 -실행합니다. 어떤 페이지도 다루지 않는 결정은 `[no-wiki]`로 표시되어 인제스트 -후보가 됩니다. 이것은 설정 가능한 role이 아니며 끌 수 없습니다. +### 스텝 2는 `wiki-plan`에 고정 — 게이트 3단계 + +`wiki-plan`은 **Phase A(분석) → gate-A → Phase B(설계) → gate-B → Phase +C(분해)**로 돕니다. 모든 종료 조건은 기계 판정 가능합니다 — `plan-gate.sh +emit`이 게이트 레저를 쓰고 `gate-check.sh --run`이 판정하므로, "계획이 +준비됐다"는 결코 자기 보고가 아닙니다: + +- **Phase A — 분석** (`plans//analysis.md`): Example Mapping 표로 쓴 + 요구사항(미해결 `OPEN:` 질문이 남으면 Phase B 진입이 막힘 — Definition of + Ready), 증거가 붙은 그라운드 트루스(재실행 가능한 baseline 테스트 명령, + 검색 근거가 달린 영향 파일, 핀 제약), load-bearing 미지수의 타임박스 + 스파이크, 그리고 `research` 롤을 통한 외부 베스트 프랙티스 검색. +- **Phase B — 설계** (`plans//design.md`): **위키 라우팅 스윕** — + `INDEX.md`를 읽고, 건드리는 각 도메인의 `index.md`를 읽고, 모든 설계 결정에 + 대해 그것을 소유한 페이지를 찾습니다. 각 결정 행은 선택, 실존하는 경로형 + 위키 근거(gate-B가 grep으로 검사), 기각한 대안, 그 결정이 틀렸을 때 잡아낼 + 테스트를 담습니다. 어떤 페이지도 다루지 않는 결정은 `[no-wiki]`로 표시되어 + 인제스트 후보가 됩니다. 이후 설계는 **`plan-reviewer` 서브에이전트**의 + 리뷰를 받습니다 — 읽기 전용, fresh context — 계획을 쓴 세션이 자기 설계를 + 채점하지 못하게 하는 장치입니다. +- **Phase C — 분해**: 순서 있는 small-model 크기 태스크. 각 태스크는 자기를 + 근거 짓는 위키 페이지들과, 자기 검증이 증명하는 요구사항(`covers: R`)을 + 명시하며 커버리지는 양방향으로 대조됩니다. 결정은 구체적인 값/코드로 + 적습니다("적절히" 금지). 그래서 구현 패스는 추측하는 대신 실행합니다. + +작은 태스크는 **lite 모드**(기계 판정: small 크기 + `[no-wiki]` 0 + 핀 무관)로 +baseline 핀과 grounding grep은 유지하되 리뷰어를 생략합니다 — 레저에 공개 +`ABANDON`으로 기록되며 조용한 생략은 불가합니다. 이것은 설정 가능한 role이 +아니며 끌 수 없습니다. 위키는 플러그인 루트에 있습니다(`wiki/`, `INDEX.md`, `AGENTS.md`, `templates/`). 위키 스킬들은 `${CLAUDE_PLUGIN_ROOT}` 기준으로 경로를 @@ -99,6 +122,7 @@ loop-orchestrator처럼 dev-loop은 설정 **없이도** 완전히 범용으로 | `tacit` | 과거 인시던트 / danger-zone 사례 | | `design` | Figma / 비주얼 스펙 MCP (UI 작업) | | `intake` | 이슈 트래커 (orchestrate의 작업 목록) | +| `research` | 외부 베스트 프랙티스/함정 검색 (wiki-plan Phase A/B). 미설정 시 고정 폴백: brave-search MCP 있으면 그것 → 내장 WebSearch → 공개 `ABANDON` | (`plan`은 role이 **아닙니다** — 계획 단계는 `wiki-plan`에 고정입니다. 그리고 번들 베스트프랙티스 `wiki/`는 설정이 필요 없습니다. `knowledge`는 *별개의* @@ -226,7 +250,7 @@ fail-closed로 거부됩니다. 게이트는 knowledge-flush PR로 좁게 스코 |-------|------| | `loop-implement` | **단일 구현자** — wiki-plan을 소비해 태스크를 순서대로 (각 태스크가 명시한 위키 페이지를 로드하며) 검증 루프로 실행. 계획 단계 = wiki-plan. | | `orchestrate` | **멀티 세션 오케스트레이터** — 하나의 목표를 병렬 워커 세션들로 분할, 각 세션은 loop-implement 실행 — 감지되면 **Orca 위에서**(Task/Dispatch 추적, `worker_done`/`ask`/`escalation` 이벤트 대기, 네이티브 liveness), 아니면 강화된 감시의 tmux(워커 질문 채널, 스톨 표면화, 허용목록 선택 UI 키). 스케줄링은 웨이브 배리어가 아니라 의존 그래프 + 슬롯 회계: `ready-set.sh`가 지금 시작해도 되는 task를 판정하고, 슬롯 수는 Gate 1에서 제안·승인되며 `LO_MAX_SESSIONS`가 상한이고, 실패한 의존은 조용한 대기가 아니라 보고되는 교착으로 드러난다. 역할별 모델 선택: 워커는 저렴한 모델, 플래너/감사자는 강한 모델. 워커는 guardrails `ask`에서 멈추지 않고 에스컬레이션하며, 실행 중 task 분할을 제안할 수 있고, 죽은 워커는 감지된다. 사람이 개입하는 두 게이트(task 분할 + substrate, 머지 전)는 항상 **AskUserQuestion 선택지**로 제시되며 `orchestrate-ask-gate.sh`가 이를 강제한다. | -| `wiki-plan` | **고정된 계획 방법론** — 각 결정을 위키 페이지로 라우팅, 순서 있는 페이지-내비게이션 태스크로 분해. | +| `wiki-plan` | **고정된 계획 방법론** — 게이트 3단계(분석 → 설계 → 분해): 증거 기반 분석, 위키 라우팅된 결정을 `plan-reviewer` 서브에이전트가 독립 리뷰, 이후 순서 있는 페이지-내비게이션 태스크로 분해. 게이트는 기계 판정(`plan-gate.sh` + `gate-check.sh`)이며, orchestrate는 게이트 증거 없는 계획을 디스패치하지 않는다. | | `wiki-ingest` | 검증된 지식을 올바른 시맨틱 레이어에 추가 (knowledge-flush가 사용). | | `wiki-query` | 위키에서 인용과 함께 질문에 답변. | | `wiki-lint` | 위키 건강 점검. | diff --git a/README.md b/README.md index a6a699c..300df56 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,10 @@ See [Orca integration](#orca-integration--supervision-not-just-spawning). **The one change from upstream loop-orchestrator:** the plan step is no longer an optional, pluggable role. It is **fixed to the bundled `wiki-plan` methodology** — every non-trivial task plans by routing each design decision to a page in the -bundled `wiki/` before any code is written. The rest of the loop is unchanged. +bundled `wiki/` before any code is written. Since v1.17.0 that planning itself +runs as **three gated phases — Analyze → Design → Decompose** — each judged +mechanically before the next may start (see below). The rest of the loop is +unchanged. On top of that, dev-loop adds a **knowledge-capture loop**: your sessions emit verified insights, and `knowledge-flush` researches, de-dups, routes, and opens a @@ -75,14 +78,37 @@ Run it two ways: guardrails `ask` instead of blocking, and a dead worker is detected fast rather than stalling the run. -### Step 2 is fixed to `wiki-plan` - -`wiki-plan` makes the planner do a **wiki routing sweep**: read `INDEX.md`, then -each touched domain's `index.md`, and for every design decision find the page -that owns it — recording a `decision → wiki page` map. Decisions are written as -concrete values/code (never "as appropriate"), so the implementing pass executes -instead of guessing. A decision no page covers is marked `[no-wiki]` and becomes -an ingest candidate. This is not a configurable role and cannot be turned off. +### Step 2 is fixed to `wiki-plan` — three gated phases + +`wiki-plan` runs **Phase A (Analyze) → gate-A → Phase B (Design) → gate-B → +Phase C (Decompose)**. Every exit condition is machine-checkable — `plan-gate.sh +emit` writes a gates ledger and `gate-check.sh --run` judges it — so "the plan +is ready" is never a self-report: + +- **Phase A — Analyze** (`plans//analysis.md`): requirements as an + Example-Mapping table (an unresolved `OPEN:` question blocks entry to Phase B — + Definition of Ready); ground truth with evidence attached (a re-runnable + baseline test command, affected files each with the search that proved them, + pinned-file constraints); time-boxed spikes for load-bearing unknowns; and an + external best-practice search via the `research` role. +- **Phase B — Design** (`plans//design.md`): the **wiki routing sweep** — + read `INDEX.md`, then each touched domain's `index.md`, and for every design + decision find the page that owns it. Each decision row carries its choice, its + wiki basis as a real path (gate-B greps that the page exists), the rejected + alternative, and the test that would catch it being wrong. A decision no page + covers is marked `[no-wiki]` and becomes an ingest candidate. The design is + then reviewed by the **`plan-reviewer` subagent** — read-only, fresh context, + so the session that wrote the plan never grades its own design. +- **Phase C — Decompose**: ordered, small-model-sized tasks, each naming the + exact wiki pages that ground it and the requirement (`covers: R`) its + verification proves — coverage is checked in both directions. Decisions are + written as concrete values/code (never "as appropriate"), so the implementing + pass executes instead of guessing. + +Small tasks take a **lite mode** (machine-judged: small size, no `[no-wiki]`, no +pins touched) that keeps the baseline pin and grounding grep but skips the +reviewer — recorded as an open `ABANDON` on the ledger, never a silent skip. +This is not a configurable role and cannot be turned off. The wiki lives at the plugin root (`wiki/`, `INDEX.md`, `AGENTS.md`, `templates/`); the wiki skills resolve their paths against `${CLAUDE_PLUGIN_ROOT}`. @@ -100,6 +126,7 @@ can map its **capability roles** to your real tools so the loop uses them: | `tacit` | past incidents / danger-zone lore | | `design` | Figma / visual-spec MCP (UI work) | | `intake` | issue tracker (orchestrate's work-list) | +| `research` | external best-practice/pitfall search (wiki-plan Phase A/B). Fixed fallback when unset: brave-search MCP if present → built-in WebSearch → open `ABANDON` | (`plan` is **not** a role — the plan step is fixed to `wiki-plan`. And the bundled best-practice `wiki/` needs no config; `knowledge` is a *separate* external wiki.) @@ -230,7 +257,7 @@ ordinary `gh pr create` in any repo. |-------|------| | `loop-implement` | **The single implementer** — consumes the wiki-plan and executes its tasks in order (loading each task's named wiki pages) through the verification loop. Plan step = wiki-plan. | | `orchestrate` | **The multi-session orchestrator** — split one goal into parallel worker sessions, each running loop-implement — over **Orca when detected** (Task/Dispatch tracking, event-driven `worker_done`/`ask`/`escalation` waits, native liveness), else tmux with a hardened watch (worker question channel, stall surfacing, allowlisted chooser keys). Scheduling is a dependency graph plus slot accounting, not wave barriers: `ready-set.sh` says what may start now, the slot count is proposed at Gate 1 and bounded by `LO_MAX_SESSIONS`, and a failed dependency surfaces as a reported deadlock rather than a silent wait. Per-role model selection: a cheap worker model, a strong planner/auditor. Workers escalate guardrails `ask`s instead of blocking, may propose splitting an over-large task mid-run, and dead workers are detected. Both human gates (task split + substrate, pre-merge) are put to you as **AskUserQuestion choosers**, enforced by `orchestrate-ask-gate.sh`. | -| `wiki-plan` | **The fixed plan methodology** — route each decision to a wiki page, decompose into ordered, page-navigated tasks. | +| `wiki-plan` | **The fixed plan methodology** — three gated phases (Analyze → Design → Decompose): evidence-backed analysis, wiki-routed decisions independently reviewed by the `plan-reviewer` subagent, then ordered, page-navigated tasks. Gates are judged mechanically (`plan-gate.sh` + `gate-check.sh`); orchestrate refuses to dispatch a plan without gate evidence. | | `wiki-ingest` | Add verified knowledge to the right semantic layer (used by knowledge-flush). | | `wiki-query` | Answer a question from the wiki with citations. | | `wiki-lint` | Health-check the wiki. |