@tienne/gestalt 0.91.0 → 0.93.0

package/plugin/skills/architecture/SKILL.md

@@ -337,7 +337,7 @@ AI 클라이언트가 플러그인으로 읽어 들이는 스킬과 에이전트
   ],
   "stateLabels": { "WAITING": "대기", "CALLED": "호출" },
   "transitions": [
-    { "id": "t-1", "from": "st-register", "to": "st-call", "path": "main", "label": "차례가 오면",
+    { "id": "t-1", "from": "st-register", "to": "st-call", "path": "main", "condition": "차례가 오면",
       "evidence": [ ... ], "lineStyle": "solid" }
   ]
 }
@@ -346,9 +346,13 @@ AI 클라이언트가 플러그인으로 읽어 들이는 스킬과 에이전트
 - **행위자**는 가로줄 하나씩이다. 사람은 `person`, 사람 손 없이 도는 배치나 자동 발송은 `system`, 지시를 읽고 스스로 판단하는 서브에이전트는 `agent`다. 위에서 아래로 적은 순서대로 쌓인다.
 - **단계**는 행위자가 하는 일 하나다. 상태 값이 있으면 `state`에 코드의 enum 이름 그대로 적는다. 그림 위쪽 구간이 이 값으로 나뉜다. 그림에는 enum 이름 대신 흐름의 `stateLabels`에 단 이름이 찍힌다. 상태 값마다 사용자 언어로 이름을 단다 (`WAITING` → 대기). 안 달면 영어 enum이 구간 머리와 단계 칩에 그대로 나온다. 상태가 없는 단계는 앞 단계 구간에 붙고 옆 흐름 단계는 갈라져 나온 단계 옆에 서니 구간을 따로 적지 않는다. `refs`에는 그 단계에서 쓰는 화면, API, 기능영역, 앱 노드 id를 단다. 범용 `component` 노드도 단다. 단계 서랍에서 그 카드로 건너가고 기술 카드 서랍에는 거꾸로 "이 항목이 나오는 흐름 단계"가 뜬다.
 - **전이**는 단계 사이 상태 변화다. 정상 흐름은 `main`, 취소나 노쇼처럼 정상 흐름을 벗어나는 전이는 `side`다.
-- **되돌리기와 정정은 단계가 아니라 전이로 적는다.** 새 상태가 생기지 않고 앞 상태로 돌아가기만 해서다. "되돌리기" 카드를 따로 만들지 말고 `매장 취소 → 호출`처럼 돌아가는 화살표 하나로 쓴다. 조건은 `label`에 적는다 (`되돌리기 (30분 이내)`). 그림에서는 두 카드 가까이로 지나가는 둥근 선에 ↩ 표시가 붙는다.
+- **선 위 글자는 `trigger`와 `condition`에 나눠 적는다.** 사용자가 누른 버튼 이름은 `trigger`(`주문 변경하기`), 그 길로 가는 조건은 `condition`(`차례가 오면`, `30분 이내`)이다. 그림에는 조건이 굵은 강조색으로 앞에 서고 누른 것이 뒤따른다. `label`은 예전 칸이다. 둘 중 하나라도 있으면 `label`은 선에 안 나오고 전이 서랍의 **메모** 줄로 간다. 새로 쓰는 IR에서는 `label`을 비우고 짧은 메모가 필요할 때만 쓴다.
+- **화면 흐름을 그릴 때도 같다.** 단계는 화면이나 시트 하나이고 전이의 `trigger`에 그 화면에서 누른 것을, `condition`에 길이 나뉘는 조건을 적는다. `trigger`는 버튼 이름 그대로 짧게 쓴다. 열 간격이 선 글자 폭을 따라 넓어지지만 한글 열두 자쯤에서 멈춰서 더 긴 글자는 이웃 카드 위로 넘친다. 화면에서 하는 일의 설명은 단계 `description`에 둔다.
+- **조건에 따라 길이 나뉘는 자리는 갈림길 단계로 적는다.** `"kind": "decision"`을 달면 카드 대신 마름모로 그려진다. 단계 이름은 `품절 상품 포함?`처럼 묻는 꼴로 쓰고 나가는 전이마다 `condition`을 단다 (`예`, `아니오`). 같은 높이의 카드로 가는 길은 오른쪽 꼭짓점에서, 위아래로 다른 높이의 카드로 가는 길은 위나 아래 꼭짓점에서 나간다. 갈림길은 흐름이 끝나는 자리가 아니라서 `terminal: true`를 함께 달면 스키마 위반이다. validate는 나가는 길이 하나뿐인 갈림길에 `auto:branch`를, 근거는 있는데 `condition`도 `label`도 없는 나가는 전이에 `auto:condition` 질문을 남긴다.
+- **되돌리기와 정정은 단계가 아니라 전이로 적는다.** 새 상태가 생기지 않고 앞 상태로 돌아가기만 해서다. "되돌리기" 카드를 따로 만들지 말고 `매장 취소 → 호출`처럼 돌아가는 화살표 하나로 쓴다. 누른 것과 조건은 나눠 적는다 (`"trigger": "되돌리기", "condition": "30분 이내"`). 그림에서는 두 카드 가까이로 지나가는 둥근 선에 ↩ 표시가 붙는다.
 - **흐름이 끝나는 단계에는 `"terminal": true`를 단다.** 착석, 취소, 만료처럼 더 갈 곳이 없는 단계다. 나가는 전이가 없는데 이 표시도 없으면 validate가 `auto:dead-end` 질문을 남긴다. 미루기처럼 다시 줄로 돌아가는 단계가 선을 빠뜨렸을 때 그림이 거기서 끝난 것처럼 읽히는 걸 막으려는 표시다. 그 질문이 뜨면 끝 단계로 표시하기 전에 이어지는 전이를 코드에서 먼저 찾는다. 되돌릴 수 있는 취소처럼 끝 단계에서 나가는 전이가 있어도 된다.
 - **정정도 같다.** 자동 노쇼를 착석으로 고치는 "노쇼 정정"은 `자동 노쇼 → 착석` 전이에 `actors: ["ops"]`다. 설명에 갈 수 있는 곳이 여럿 적혀 있으면 (착석이나 고객 취소) 전이도 그만큼 긋는다. validate가 이런 단계를 찾아 `auto:as-transition` 질문을 남긴다. 결제처럼 화면이 따로 있어 `refs`로 건너갈 일이 있는 단계는 카드로 둬도 된다.
+- **행위자가 한 명이어도 된다.** 손님 혼자 화면을 넘기는 흐름이면 `actors`에 하나만 적는다. 그때는 줄을 가를 일이 없어 왼쪽 행위자 머리 칸을 걷고 그림 맨 위 띠에 행위자 칩 하나만 세운다.
 - **여러 행위자가 할 수 있는 전이에는 `actors`를 단다.** 되돌리기를 손님도 매장도 할 수 있으면 `"actors": ["guest", "staff"]`다. 선 글자 옆에 행위자 이름이 붙는다. 행위자 줄은 그 사람이 하는 일을 놓는 자리라, 여럿이 하는 동작을 한 줄에 단계로 넣으면 틀린 그림이 된다.
 - 근거 규칙은 엣지와 같다. 상태를 바꾸는 코드 줄을 봤으면 `code` 근거로 실선이다. 기획 문서나 KB로만 확인했으면 `doc` 근거로 점선이다. 그 단계 카드도 점선 테두리가 된다. 근거 없는 단계나 전이는 그리지 않고 질문이 된다.
 - **기획 문서에만 있는 단계도 넣는다.** 아직 안 만든 기능이나 만들다 만 기능이 흐름 그림에서 같이 보여야 기술 그림과의 차이가 드러난다. 대신 근거는 `doc`뿐이라 점선이다.
@@ -357,6 +361,7 @@ AI 클라이언트가 플러그인으로 읽어 들이는 스킬과 에이전트
   - `participants`에는 그 경로에 나오는 스킬, 에이전트, MCP 서버만 10개 안팎으로 고른다. MCP 서버 자리에는 도구 처리기 `app_module`이나 도구 `endpoint`를 쓴다.
   - 메시지는 지도 엣지를 `edge`로 가리킨다. 문서 읽기처럼 지도에 선이 없는 단계는 자기 호출 메시지로 쓰고 그 SKILL.md 줄을 근거로 단다. 응답은 `reply: true`다. 조건이 맞을 때만 도는 단계는 `blocks`의 `opt`로 묶고 경우에 따라 하나만 도는 단계는 `alt`로 묶는다.
   - 세션이 도구를 두 번 불러 결과를 넘기는 2-Call Passthrough도 순서도에 그린다. 세션 모델과 MCP 서버를 오가는 메시지로 쓴다.
+  - 구간은 [`phases`](#질문별-그림을-얹는다)의 sequence 구간 규칙대로 직접 적는다.
   - 지도는 그대로 그린다. 무엇이 어느 플러그인에 있는지는 지도가 보여준다. 전체보기 지도 위에 질문별 그림 카드 줄이 뜨니 순서도가 몇 개인지는 위쪽 바를 안 눌러도 보인다.
   - IR의 `repos`가 둘 이상이면 순서도 머리 카드 둘째 줄에 노드의 레포 이름이 나온다. MCP 도구는 레포 대신 `<mcpServer> MCP`로 나온다. 카드에 그대로 찍히니 `participants`에 넣은 노드의 `repo`가 실제 레포와 맞는지 한 번 더 본다. MCP 도구에는 `mcpServer`를 빠뜨리지 않는다. 빠지면 도구를 기록한 레포 이름이 대신 나와 어느 서버의 도구인지 헷갈린다.
   - `flows`는 사람 쪽 업무 절차가 따로 있을 때만 쓴다. 그때는 사용자가 `person`, MCP 서버가 `system`, 세션 모델과 서브에이전트가 `agent`다. `refs`에는 스킬과 에이전트 노드 id도 단다.
@@ -513,7 +518,7 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 
 ### 페이지 글
 
-페이지에 그대로 보이는 글은 **사용자가 이 분석을 시킨 프롬프트의 언어로** 쓴다. 코드와 주석, 기획 문서가 영어여도 옮겨 쓴다. 미해결 질문(`question`), 노드 `description`, 기능영역 이름, `displayName`, 구간 `label`, 흐름의 `title`과 `description`, 행위자와 단계와 전이의 `label`, `stateLabels` 값이 그 자리다. 코드 식별자인 노드 `label`과 단계 `state`만 코드에 있는 그대로 둔다. 한국어라면 읽는 사람에게 말하는 해요체로 쓴다. 번역투나 AI 말투는 피하고 [`ai-tell-quick-rules.md`](../../role-agents/_shared/references/ai-tell-quick-rules.md)를 따른다.
+페이지에 그대로 보이는 글은 **사용자가 이 분석을 시킨 프롬프트의 언어로** 쓴다. 코드와 주석, 기획 문서가 영어여도 옮겨 쓴다. 미해결 질문(`question`), 노드 `description`, 기능영역 이름, `displayName`, 구간 `label`, 흐름의 `title`과 `description`, 행위자와 단계와 전이의 `label`, 전이의 `trigger`와 `condition`, `stateLabels` 값이 그 자리다. 코드 식별자인 노드 `label`과 단계 `state`만 코드에 있는 그대로 둔다. 한국어라면 읽는 사람에게 말하는 해요체로 쓴다. 번역투나 AI 말투는 피하고 [`ai-tell-quick-rules.md`](../../role-agents/_shared/references/ai-tell-quick-rules.md)를 따른다.
 
 ### 근거 규칙
 
@@ -602,6 +607,10 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
   "messages": [
     { "id": "m1", "from": "app", "to": "api", "label": "POST /orders/pay", "edge": "e-app-api", "evidence": [], "lineStyle": "solid" },
     { "id": "m2", "from": "pg", "to": "api", "label": "승인됨", "edge": "e-api-pg", "evidence": [], "lineStyle": "solid", "reply": true, "block": "b-result", "branch": "승인" }
+  ],
+  "phases": [
+    { "id": "p-pay", "label": "결제 요청", "from": "m1", "to": "m1" },
+    { "id": "p-result", "label": "승인 결과 받기", "from": "m2", "to": "m2" }
   ]
 }
 ```
@@ -612,6 +621,10 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 - 엣지로 안 잡히는 일(같은 노드 안의 검증, 문서에만 적힌 단계)은 `edge` 없이 자기 `evidence`를 단다. 자기 호출은 `from`과 `to`를 같게 쓴다.
 - 근거가 하나도 없는 메시지는 그려지지 않고 `auto:message:<id>` 질문이 된다. 메시지를 지어내 채우지 말고 Step 7로 넘긴다.
 - **sequence**: `participants`로 세로줄 순서를 정한다. 적으면 메시지 끝이 전부 여기 있어야 한다. 묶음은 `blocks`에 두고 메시지 `block`으로 건다. `alt`는 경우에 따라 하나만 도는 묶음, `opt`는 조건이 맞을 때만 도는 묶음, `loop`는 되풀이, `par`는 동시에 도는 묶음이다. `alt` 안의 경우 이름은 `branch`에 적는다. 한 묶음의 메시지는 붙여서 적는다.
+- **sequence 구간**: `phases`는 순서도를 단계로 나눈다. 그림 위 보기 전환의 **단계별 카드**와 **따라가기**가 이 구간대로 카드를 나누고 띠를 깐다. 구간 하나는 `{ id, label, from, to }`이고 `from`과 `to`는 이 그림의 메시지 id다. 두 메시지 다 그 구간에 든다.
+  - `label`은 사람이 읽는 단계 이름이다. 노드 id나 도구 이름(`ges_interview`) 말고 "요구사항 인터뷰", "스펙 만들기"처럼 그 구간에서 무슨 일이 벌어지는지를 쓴다. [페이지 글](#페이지-글) 규칙을 따른다.
+  - 첫 메시지부터 마지막 메시지까지 빈틈도 겹침도 없이 메시지 순서대로 적는다. 배열 순서도 메시지 순서와 같아야 하고 한 메시지는 한 구간에만 든다. 구간 경계가 묶음 한가운데를 지나는 건 괜찮다.
+  - 안 적으면 render가 알아서 자른다. 맨 위 참여자가 지금 구간에서 처음 만나는 대상을 부르는 자리에서 새 구간이 열리고 구간 이름은 그 대상의 표시 이름이다. 그래서 모든 호출이 한 진입점을 거치는 흐름은 구간 하나로 뭉친다. 세션 모델이나 스킬 하나가 모든 호출을 내보내는 하네스 순서도가 그렇다. 같은 대상을 여러 번 오가는 흐름은 같은 이름 구간이 되풀이된다. 이런 흐름과 참여자가 많은 순서도에는 `phases`를 적는다.
 - **dataflow**: `messages`만 쓴다. 데이터가 한 노드에서 다른 노드로 옮겨 가는 것 하나가 메시지 하나다. `blocks`와 메시지의 `reply`, `block`, `branch`는 쓰지 않는다.
 - **compare**: `messages`는 빈 배열로 두고 `sides`에 견줄 두 묶음을 적는다. `{ id, label, nodes[] }` 둘이고 id는 달라야 한다. 그림은 "첫 묶음에만", "둘 다", "둘째 묶음에만" 세 열로 선다.
 - 질문 하나에 그림 하나다. 질문이 여럿이면 그림도 여럿 단다.
@@ -651,7 +664,7 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 
 - 성공하면 `{ ok: true, autoUnresolved, drawable }`이다. `drawable`에 빠진 노드와 엣지가 있으면 왜 빠졌는지 `autoUnresolved`에서 확인한다.
 - 성공해도 `warnings`가 올 수 있다. 지금은 `NODE_DESCRIPTION_MISSING` 하나이고 그리는 노드 중 `description`이 빈 노드를 `nodeIds`에 모아 준다. render는 그대로 되지만 그 카드에는 설명 줄이 없다. [노드 설명](#노드-설명)대로 채운다. render 응답에도 같은 `warnings`가 실린다.
-- 실패하면 `errors[]`에 `code`와 `nodeId`나 `edgeId`가 온다. 질문별 그림 에러면 `projectionId`와 `messageId`가 온다.
+- 실패하면 `errors[]`에 `code`와 `nodeId`나 `edgeId`가 온다. 질문별 그림 에러면 `projectionId`와 `messageId`가 오고 구간 에러면 `phaseId`가 함께 온다.
 
 | 에러 코드                     | 고치는 법                                                                                                          |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -684,6 +697,11 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 | `SOLID_MESSAGE_WITHOUT_EVIDENCE` | 가리킨 엣지나 자기 근거에 code나 spec이 없다. 근거를 찾아 달거나 점선으로 바꾼다                                |
 | `PROJECTION_EMPTY`            | sequence와 dataflow에 메시지를 넣는다. 넣을 메시지가 없으면 그 그림을 뺀다                                         |
 | `PROJECTION_SHAPE_FIELD`      | 모양에 안 맞는 필드를 뺀다. [질문별 그림을 얹는다](#질문별-그림을-얹는다)의 모양별 설명을 본다                      |
+| `DUPLICATE_PHASE_ID`          | 한 그림 안에서 구간 id가 겹친다. 다시 짓는다                                                                       |
+| `PROJECTION_PHASE_MESSAGE_NOT_FOUND` | 구간 `from`이나 `to`를 그 그림의 메시지 id로 고친다. 다른 그림의 메시지는 못 가리킨다                       |
+| `PROJECTION_PHASE_REVERSED`   | `from`이 `to`보다 뒤 메시지다. 메시지 순서대로 앞쪽을 `from`에 둔다                                                |
+| `PROJECTION_PHASE_OVERLAP`    | 구간이 겹치면 다음 구간을 앞 구간의 `to` 바로 다음 메시지에서 시작한다. 구간 배열이 메시지 순서를 안 따르면 배열을 메시지 순서대로 다시 적는다 |
+| `PROJECTION_PHASE_GAP`        | 첫 구간은 첫 메시지에서 시작하고 마지막 구간은 마지막 메시지에서 끝낸다. 어느 구간에도 안 든 메시지는 앞뒤 구간에 넣는다. 배열이 메시지 순서대로인지도 함께 본다 |
 
 **최대 3회까지 고쳐 다시 validate한다.** 세 번째에도 같은 노드나 엣지에서 실패하면 더 붙잡지 않는다. 그 노드나 엣지를 IR에서 빼고 `unresolved`에 무엇을 왜 확인 못 했는지 질문으로 남긴다.
 
@@ -733,7 +751,7 @@ render는 validate를 다시 하고 이전 실행 IR과 병합해 노드 id를
 | 서비스 (`service:<id>`)   | 그 서비스의 기능영역과 서비스에 바로 단 화면, 거기서 닿는 `gateway`와 서버. 서비스를 서빙하는 버킷이 있으면 왼쪽에 도메인, CDN, 버킷 레인이 붙고 서비스 카드가 기능영역 레인 맨 위에 선다 |
 | 기능영역 (`feature:<id>`) | 그 기능영역의 화면, 화면이 부르는 엔드포인트, 거쳐 가는 `gateway`와 받는 모듈                                                                                                             |
 | 서버 (`server:<id>`)      | 그 모듈이나 `gateway`에 걸린 엔드포인트, 읽고 쓰는 테이블, 쓰는 클라이언트                                                                                                                |
-| 흐름 (`flow:<id>`)        | Step 3.5의 흐름 하나. 행위자 가로줄 위에 단계 카드가 왼쪽에서 오른쪽으로 선다. 옆 흐름은 정상 흐름과 다른 색 선이다. 서비스 레벨의 **흐름** 버튼으로 들어간다. `service` 없는 흐름은 전체 바로 아래 서고 전체 레벨의 **흐름** 버튼으로 들어간다 |
+| 흐름 (`flow:<id>`)        | Step 3.5의 흐름 하나. 행위자 가로줄 위에 단계 카드가 왼쪽에서 오른쪽으로 선다. 옆 흐름은 정상 흐름과 다른 색 선이다. 갈림길은 마름모로 서고 행위자가 한 명이면 가로줄 대신 맨 위에 칩 하나가 선다. 서비스 레벨의 **흐름** 버튼으로 들어간다. `service` 없는 흐름은 전체 바로 아래 서고 전체 레벨의 **흐름** 버튼으로 들어간다 |
 | 묶음 (`group:<id>`)       | `infra`, `data`, `process` 팩에서 자식을 가진 노드 하나. 바로 아래 자식만 보이고 손자 사이 선은 자식 카드 사이 선으로 묶인다. 바깥과 잇는 카드는 보내기만 하면 왼쪽, 받으면 오른쪽에 서고 한 열에 네 장이 넘으면 옆 열로 넘어간다 |
 | 질문 (`view:<id>`)        | 질문별 그림 하나. 전체 바로 아래 서고 전체 레벨 지도 위의 카드 줄이나 위쪽 바의 **질문별 그림** 버튼으로 들어간다. 메시지를 누르면 보내는 쪽, 받는 쪽, 근거가 나오고 지도의 카드로 건너간다 |
 

package/schemas/architecture-ir.schema.json

@@ -473,14 +473,27 @@
         "id": { "type": "string", "minLength": 1 },
         "actor": { "type": "string", "minLength": 1 },
         "label": { "type": "string", "minLength": 1 },
+        "kind": {
+          "type": "string",
+          "enum": ["step", "decision"],
+          "description": "decision is a branch drawn as a diamond. Omit for a plain step"
+        },
         "description": { "type": "string" },
         "state": { "type": "string", "minLength": 1 },
+        "terminal": {
+          "type": "boolean",
+          "description": "the flow may end here. Not allowed on a decision step"
+        },
         "refs": {
           "type": "array",
           "description": "ids of screen, endpoint, feature or micro_app nodes this step touches",
           "items": { "type": "string", "minLength": 1 }
         },
         "evidence": { "type": "array", "items": { "$ref": "#/definitions/evidence" } }
+      },
+      "if": { "properties": { "kind": { "const": "decision" } }, "required": ["kind"] },
+      "then": {
+        "not": { "properties": { "terminal": { "const": true } }, "required": ["terminal"] }
       }
     },
     "flowTransition": {
@@ -491,7 +504,27 @@
         "from": { "type": "string", "minLength": 1 },
         "to": { "type": "string", "minLength": 1 },
         "path": { "type": "string", "enum": ["main", "side"] },
-        "label": { "type": "string", "minLength": 1 },
+        "trigger": {
+          "type": "string",
+          "minLength": 1,
+          "description": "what the user pressed, such as a button name. Shown on the line"
+        },
+        "condition": {
+          "type": "string",
+          "minLength": 1,
+          "description": "when this branch is taken. Put it on lines leaving a decision step"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "description": "legacy text. Shown on the line only when trigger and condition are both absent"
+        },
+        "actors": {
+          "type": "array",
+          "minItems": 1,
+          "description": "ids of flow actors who can make this transition",
+          "items": { "type": "string", "minLength": 1 }
+        },
         "evidence": { "type": "array", "items": { "$ref": "#/definitions/evidence" } },
         "lineStyle": { "type": "string", "enum": ["solid", "dashed"] }
       }
@@ -580,9 +613,29 @@
           "type": "array",
           "description": "the two groups compare puts side by side, such as before and after",
           "items": { "$ref": "#/definitions/projectionSide" }
+        },
+        "phases": {
+          "type": "array",
+          "minItems": 1,
+          "description": "sequence only. Phases in message order, from and to inclusive, no overlap or gap. Leave out to split automatically",
+          "items": { "$ref": "#/definitions/projectionPhase" }
         }
       }
     },
+    "projectionPhase": {
+      "type": "object",
+      "required": ["id", "label", "from", "to"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "description": "step name a person reads"
+        },
+        "from": { "type": "string", "minLength": 1, "description": "first message id" },
+        "to": { "type": "string", "minLength": 1, "description": "last message id" }
+      }
+    },
     "projectionSide": {
       "type": "object",
       "required": ["id", "label", "nodes"],