@tienne/gestalt 0.90.1 → 0.92.0

package/plugin/skills/architecture/SKILL.md

@@ -295,7 +295,8 @@ AI 클라이언트가 플러그인으로 읽어 들이는 스킬과 에이전트
 
    ```json
    { "id": "tool:plan", "kind": "endpoint", "label": "ges_plan", "protocol": "mcp",
-     "mcpServer": "gestalt", "parent": "svc-gestalt", "actions": ["start", "submit"], "evidence": [ ... ] }
+     "mcpServer": "gestalt", "parent": "svc-gestalt", "actions": ["start", "submit"],
+     "description": "실행 계획을 세우고 단계별로 제출받는 도구예요.", "evidence": [ ... ] }
    ```
 
 5. **도구 호출 매칭**: SKILL.md와 AGENT.md에서 도구 이름과 `action=`, `action: '...'` 줄을 찾아 `skillToolCalls`로, 서버 코드의 도구 등록을 `serverTools`로 적어 `match_endpoints`에 넘긴다. HTTP 쪽 `feCalls`와 함께 넘겨도 된다.
@@ -356,6 +357,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도 단다.
@@ -501,6 +503,15 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 - render 응답의 `unstagedNodes`가 0이 아니면 규칙이 빠진 노드가 **그 밖**에 모인 것이다. 인프라처럼 일부러 뺀 게 아니면 규칙을 보탠다.
 - 구간 이름은 페이지에 그대로 보이니 아래 해요체 규칙처럼 읽는 사람 말로 쓴다.
 
+### 노드 설명
+
+**모든 노드에 `description`을 한 줄씩 단다.** 카드 이름 밑에 한 줄로 붙고 카드를 누르면 열리는 서랍 맨 위에 그대로 나온다. 이름만 봐서는 무엇인지 모르는 사람이 이 줄을 읽고 그림을 따라간다.
+
+- 그 노드가 무엇을 하는지 한 문장으로 쓴다. 카드에서는 한 줄을 넘으면 말줄임표로 잘리고 전체는 툴팁과 서랍에서 보인다. 그래서 앞쪽에 핵심을 둔다.
+- 출처가 이미 있는 노드는 거기서 가져와 한 줄로 줄인다. 스킬은 SKILL.md 프런트매터의 `description`, MCP 도구는 도구 등록의 description, 에이전트는 AGENT.md의 `description`이나 첫 문단이다. 트리거 문구나 사용 예시는 걷어내고 하는 일만 남긴다.
+- 출처가 없으면 코드에서 읽은 대로 쓴다. 화면은 사용자가 거기서 하는 일, API는 무엇을 돌려주거나 바꾸는지, 테이블은 무엇을 담는지다.
+- 빈 채로 두면 validate가 `warnings`에 `NODE_DESCRIPTION_MISSING`을 싣는다. 에러가 아니라 render는 막지 않는다. 경고에 실린 `nodeIds`를 채워 다시 validate한다.
+
 ### 페이지 글
 
 페이지에 그대로 보이는 글은 **사용자가 이 분석을 시킨 프롬프트의 언어로** 쓴다. 코드와 주석, 기획 문서가 영어여도 옮겨 쓴다. 미해결 질문(`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)를 따른다.
@@ -592,6 +603,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" }
   ]
 }
 ```
@@ -602,6 +617,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는 달라야 한다. 그림은 "첫 묶음에만", "둘 다", "둘째 묶음에만" 세 열로 선다.
 - 질문 하나에 그림 하나다. 질문이 여럿이면 그림도 여럿 단다.
@@ -640,7 +659,8 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 ```
 
 - 성공하면 `{ ok: true, autoUnresolved, drawable }`이다. `drawable`에 빠진 노드와 엣지가 있으면 왜 빠졌는지 `autoUnresolved`에서 확인한다.
-- 실패하면 `errors[]`에 `code`와 `nodeId`나 `edgeId`가 온다. 질문별 그림 에러면 `projectionId`와 `messageId`가 온다.
+- 성공해도 `warnings`가 올 수 있다. 지금은 `NODE_DESCRIPTION_MISSING` 하나이고 그리는 노드 중 `description`이 빈 노드를 `nodeIds`에 모아 준다. render는 그대로 되지만 그 카드에는 설명 줄이 없다. [노드 설명](#노드-설명)대로 채운다. render 응답에도 같은 `warnings`가 실린다.
+- 실패하면 `errors[]`에 `code`와 `nodeId`나 `edgeId`가 온다. 질문별 그림 에러면 `projectionId`와 `messageId`가 오고 구간 에러면 `phaseId`가 함께 온다.
 
 | 에러 코드                     | 고치는 법                                                                                                          |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -673,6 +693,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`에 무엇을 왜 확인 못 했는지 질문으로 남긴다.
 

package/schemas/architecture-ir.schema.json

@@ -580,9 +580,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"],