docs(readme): document the gated Analyze/Design/Decompose plan cycle

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/<feature>/analysis.md`): Example Mapping 표로 쓴
+  요구사항(미해결 `OPEN:` 질문이 남으면 Phase B 진입이 막힘 — Definition of
+  Ready), 증거가 붙은 그라운드 트루스(재실행 가능한 baseline 테스트 명령,
+  검색 근거가 달린 영향 파일, 핀 제약), load-bearing 미지수의 타임박스
+  스파이크, 그리고 `research` 롤을 통한 외부 베스트 프랙티스 검색.
+- **Phase B — 설계** (`plans/<feature>/design.md`): **위키 라우팅 스윕** —
+  `INDEX.md`를 읽고, 건드리는 각 도메인의 `index.md`를 읽고, 모든 설계 결정에
+  대해 그것을 소유한 페이지를 찾습니다. 각 결정 행은 선택, 실존하는 경로형
+  위키 근거(gate-B가 grep으로 검사), 기각한 대안, 그 결정이 틀렸을 때 잡아낼
+  테스트를 담습니다. 어떤 페이지도 다루지 않는 결정은 `[no-wiki]`로 표시되어
+  인제스트 후보가 됩니다. 이후 설계는 **`plan-reviewer` 서브에이전트**의
+  리뷰를 받습니다 — 읽기 전용, fresh context — 계획을 쓴 세션이 자기 설계를
+  채점하지 못하게 하는 장치입니다.
+- **Phase C — 분해**: 순서 있는 small-model 크기 태스크. 각 태스크는 자기를
+  근거 짓는 위키 페이지들과, 자기 검증이 증명하는 요구사항(`covers: R<n>`)을
+  명시하며 커버리지는 양방향으로 대조됩니다. 결정은 구체적인 값/코드로
+  적습니다("적절히" 금지). 그래서 구현 패스는 추측하는 대신 실행합니다.
+
+작은 태스크는 **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` | 위키 건강 점검. |

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/<feature>/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/<feature>/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<n>`) 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. |