@tienne/gestalt 0.86.0 → 0.88.0

package/plugin/skills/diff-radius/SKILL.md

@@ -54,6 +54,7 @@ outputs:
   - coChangeTotalMatched
   - riskScore
   - summary
+  - freshness
 ---
 
 # Diff Radius Skill
@@ -70,6 +71,8 @@ outputs:
 /build-graph
 ```
 
+한 번 빌드해두면 그 뒤는 손대지 않아도 됩니다. 질의하기 전에 그래프를 작업 트리에 맞추므로 커밋 안 한 변경까지 반영된 그래프로 답합니다. 그래프 DB가 아예 없으면 자동으로 만들지 않으니 그때만 `/build-graph`를 돌립니다.
+
 ## 실행 방법
 
 ### 기본 (staged + unstaged 전체)
@@ -123,6 +126,7 @@ ges_code_graph {
 | `coChangeTotalMatched` | 임계를 통과한 이력 이웃 수. `coChangeMatchedCapped`가 꺼져 있으면 하한이 아니라 정확한 수다 |
 | `riskScore` | 위험도 점수 0~1 |
 | `summary` | 한 줄 요약 |
+| `freshness` | 질의 전 최신화 결과. `status`가 `fresh`(바뀐 것 없음), `refreshed`(반영하고 답함), `stale`(이전 그래프로 답함), `skipped`(DB가 없거나 최신화를 끔) 중 하나 |
 
 `rankedFiles` 각 항목의 `origin`은 `both`(import와 이력 양쪽), `history`(이력 전용), `import`(import 전용) 셋이다. `history`는 매니페스트끼리의 약속이나 코드와 그 문서처럼 서로 import하지 않아 파싱으로는 영영 안 잡히는 관계다. 커밋 직전에 "이것도 같이 고쳐야 하지 않나"를 잡아주는 자리라 이 스킬에서 특히 쓸모가 있다.
 
@@ -162,6 +166,13 @@ ges_code_graph {
    레포 최상위에서 /build-graph를 다시 돌리면 함께 바뀐 파일까지 잡습니다.
 ```
 
+`freshness.status`가 `stale`이면 결과 표시 위에 안내를 붙입니다. 결과는 나오지만 최근에 고친 파일이 빠져 있을 수 있습니다.
+
+```
+⚠️ 이전 그래프 기준으로 본 결과입니다 ({freshness.message}).
+   최근에 고친 파일은 빠져 있을 수 있습니다. 잠시 뒤 다시 부르면 그때 다시 맞춥니다.
+```
+
 `depthExhausted: true`면 위 표시 바로 아래에 한 줄을 덧붙입니다. 빠뜨리지 않습니다.
 
 ```

package/plugin/skills/review/SKILL.md

@@ -293,7 +293,11 @@ mkdir -p "$refsTmp"
 gestalt harness-refs collect --base <baseSha> --head <headSha> --backend <github|local> --json > "$refsTmp/refs.json"
 ```
 
-`--backend`는 `prTarget`이 `github`이면 `github`, 아니면 `local`입니다. `local`이면 관련 레포를 로컬 클론에서 찾으므로 `--repo-dir owner/name=<경로>`로 클론 위치를 알 수 있는 만큼 넘깁니다. stdout은 JSON 한 줄이고 종료 코드가 1이면 인자를 잘못 준 것입니다. 인자 오류가 아닌 실패는 `referenceCheckSkipped`로 담겨 오므로 종료 코드로 리뷰를 멈추지 않습니다.
+`--backend`는 `prTarget`이 `github`이면 `github`, 아니면 `local`입니다. 관련 레포의 로컬 클론을 알면 어느 쪽이든 `--repo-dir owner/name=<경로>`로 아는 만큼 넘깁니다.
+
+`github`이어도 관련 레포는 GitHub 코드 검색으로 찾지 않습니다. 코드 검색은 분당 10회라 바뀐 파일이 열 개만 넘어도 식별자 질의가 한도를 넘깁니다. CLI가 관련 레포마다 클론을 준비해 `git grep`으로 찾습니다. `--repo-dir`로 받은 클론을 먼저 쓰고 없으면 `~/.gestalt/repos/<워크트리 이름>-<경로 해시>/<owner>/<name>`에 기본 브랜치만 얕게 받습니다. 클론은 워크트리마다 따로라 여러 워크트리에서 리뷰를 동시에 돌려도 서로 부딪히지 않습니다. 수집을 시작할 때 워크트리가 지워졌거나 7일 넘게 안 쓴 클론을 치웁니다. 수집을 안 돌리는 동안 디스크를 비우려면 `gestalt harness-refs clones prune`을 부릅니다. 넘긴 클론이든 받아 둔 클론이든 매번 fetch하고 워킹트리가 아니라 origin 기본 브랜치를 읽으니, 넘기는 클론이 다른 브랜치에 있거나 고치던 중이어도 괜찮습니다. `local`은 지금처럼 `--repo-dir` 클론의 워킹트리를 그대로 읽습니다. GitHub 코드 검색에는 클론으로 못 덮는 자리만 갑니다. 관련 레포 목록 밖에서 이 레포를 부르는 레포를 찾는 조직 전체 검색과, 클론을 못 받은 레포입니다. 조직 전체 검색은 경로와 파일 이름, 스킬이나 에이전트 이름 같은 이름 질의만 보내고 남은 한도 안에서 앞쪽부터 씁니다.
+
+stdout은 JSON 한 줄이고 종료 코드가 1이면 인자를 잘못 준 것입니다. 인자 오류가 아닌 실패는 `referenceCheckSkipped`로 담겨 오므로 종료 코드로 리뷰를 멈추지 않습니다.
 
 `refs.json`에서 쓰는 필드는 아래뿐입니다.
 
@@ -305,8 +309,9 @@ gestalt harness-refs collect --base <baseSha> --head <headSha> --backend <github
 | `lookupBlocked` | 조회가 막힌 자리(`source`, `reason`, `detail`) |
 | `noGitHubRemote` | GitHub 원격이 없어 레포 간 검사를 못 함 |
 | `referenceCheckSkipped` | 레포 간 참조 검사를 전부 또는 일부 못 봤음 |
+| `backwardSearchCoverage` | 역방향 검색 질의를 몇 개 계획했고(`planned`) 몇 개를 다 봤는지(`searched`). `orgWide`는 조직 전체 검색만 따로 센 값입니다 |
 
-**막힘이 있으면 사용자에게 묻습니다.** `referenceCheckSkipped`가 `true`이거나 `lookupBlocked`가 비어 있지 않거나 `noGitHubRemote`가 `true`면 3단계 전에 멈추고 묻습니다. 막힌 이유(`reason`)를 한 줄로 알리고 둘 중 하나를 고르게 합니다.
+**막힘이 있으면 사용자에게 묻습니다.** `referenceCheckSkipped`가 `true`이거나 `lookupBlocked`가 비어 있지 않거나 `noGitHubRemote`가 `true`면 3단계 전에 멈추고 묻습니다. 막힌 이유(`reason`)를 한 줄로 알리고 둘 중 하나를 고르게 합니다. `reason`이 `rateLimited`면 `backwardSearchCoverage`로 얼마나 봤는지(질의 `searched`/`planned`개)를 같은 줄에 붙입니다. 다시 돌려도 한도는 분당 10회씩만 차서, 남은 질의가 많으면 기다려도 한 번에 안 끝난다는 걸 사용자가 보고 고르게 합니다.
 
 1. **기다린다.** 로그인이나 권한, 속도 제한을 풀고 다시 부르게 하고 여기서 멈춥니다.
 2. **참조 검사만 비워둔 채 진행한다.** 3단계로 넘어갑니다. 스크립트가 못 본 레포 간 참조는 이번 리뷰가 안 본 채로 남습니다.
@@ -319,6 +324,8 @@ gestalt review-loop rounds --pr <번호>       # 로컬 PR이나 PR 없는 브
 
 응답의 `noRemoteChoice`가 `proceedWithoutRefs`면 질문을 건너뛰고 그 답을 그대로 씁니다. '기다린다'는 재사용하지 않습니다. 기다리겠다던 사용자가 다시 불렀다는 것이 새 답이 필요하다는 신호입니다. 조회 막힘(`lookupBlocked`)은 원인이 풀릴 수 있어서 라운드마다 다시 묻습니다. 사용자의 답은 4.7단계 이벤트 결정에서 `gestalt review-loop approve-gate --record`에 `--user-choice`로 넘겨 라운드 기록에 남깁니다.
 
+**조직 전체 검색을 덜 본 것은 막힘이 아닙니다.** 관련 레포를 전부 찾았는데 한도 때문에 조직 전체 검색만 덜 봤으면 CLI가 `lookupBlocked`에 올리지 않고 `limitations`에 "조직 전체 검색은 질의 N/M개만 봤다"를 남깁니다. 묻지 않고 진행하되, `backwardSearchCoverage.orgWide`의 `searched`가 `planned`보다 작으면 [결과 표시](#결과-표시)의 **판정** 줄 아래에 그 수치를 한 줄로 남깁니다. 관련 레포 목록 밖은 그만큼 안 봤다는 뜻이라 조용히 빠지면 안 됩니다.
+
 **비워둔 채 진행하면 리포트에 그 사실을 남깁니다.** [결과 표시](#결과-표시)의 **판정** 줄 아래 한 줄입니다. 조용히 빠지면 사용자는 다른 레포 참조까지 봤다고 여깁니다. 이 상태의 라운드는 approve를 낼 수 없는 라운드가 되고 그 판정은 4.7단계 이벤트 결정이 `approve-gate`로 합니다.
 
 수집 도구가 아예 안 뜨는 경우(`gestalt` 바이너리가 없음, 명령이 없는 옛 버전)도 막힘과 같게 다룹니다. 못 돌렸다는 사실을 알리고 같은 두 가지를 묻습니다. 후보를 손으로 만들어 채우지 않습니다.

package/schemas/gestalt.schema.json

@@ -148,6 +148,25 @@
       "description": "Enable OS desktop notifications for pipeline events (env: GESTALT_NOTIFICATIONS)",
       "default": false
     },
+    "codeGraph": {
+      "type": "object",
+      "description": "Code knowledge graph settings",
+      "properties": {
+        "hooks": {
+          "type": "object",
+          "description": "Claude Code plugin hooks that inject code graph pointers into the session. Claude Code only",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Inject a repo map at session start, related file pointers per prompt, and impact plus co-change after edits. Off by default because plugin hooks run in every repo (env: GESTALT_CODE_GRAPH_HOOKS=1|0)",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "logLevel": {
       "type": "string",
       "enum": ["debug", "info", "warn", "error"],