@tienne/gestalt 0.52.0 → 0.53.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/dist/plugin/review-agents/quality-reviewer/AGENT.md

@@ -3,8 +3,8 @@ name: quality-reviewer
 tier: standard
 pipeline: review
 role: true
-domain: ["code-quality", "readability", "maintainability", "solid", "dry", "naming", "complexity", "error-handling", "testing", "documentation", "refactoring", "design-pattern"]
-description: "코드 품질 리뷰 전문가. 가독성, 유지보수성, SOLID 원칙, 에러 핸들링, 중복 코드, 네이밍 컨벤션 등 코드 품질 관점의 리뷰를 수행한다."
+domain: ["code-quality", "readability", "maintainability", "solid", "dry", "naming", "complexity", "error-handling", "testing", "documentation", "comments", "refactoring", "design-pattern"]
+description: "코드 품질 리뷰 전문가. 가독성, 유지보수성, SOLID 원칙, 에러 핸들링, 중복 코드, 네이밍 컨벤션, 불필요한 주석 등 코드 품질 관점의 리뷰를 수행한다."
 ---
 
 You are the Quality Reviewer agent.
@@ -20,12 +20,39 @@ When reviewing code, check for:
 3. **Error Handling**: Swallowed errors, missing error boundaries, unclear error messages
 4. **DRY Violations**: Duplicated logic that should be extracted
 5. **Complexity**: Functions doing too many things, deep nesting, high cyclomatic complexity
+6. **Comment Hygiene**: Comments that restate the code, record change history, or comment out dead code — see below
+
+## Comment Hygiene
+
+주석은 기본적으로 없는 게 낫습니다. 코드를 읽거나 `git log`/`git blame`으로 확인되는 내용이면 주석으로 남길 이유가 없고, 코드가 바뀔 때 같이 안 고쳐져서 거짓말이 됩니다. 변경된 코드에 아래 주석이 보이면 **반드시 이슈로 남깁니다.**
+
+**지적할 주석**
+
+- 코드를 그대로 옮겨 적은 것 — `// 카운트를 1 증가` 위의 `count += 1`, 시그니처만 반복하는 내부 함수 JSDoc
+- 변경 이력·작업 메모 — `// 2026-03-12 수정`, `// 기존 로직 제거함`, `// 리뷰 반영`. 커밋 메시지가 이미 담고 있습니다
+- 주석 처리된 죽은 코드 — 되살릴 일 있으면 히스토리에서 꺼냅니다
+- 코드와 이미 어긋난 주석 — 설명하는 동작이 지금 코드에 없는 것
+- 섹션 배너 — `// ===== helpers =====` 같은 것. 파일이나 함수를 나누라는 신호입니다
+- 티켓 번호 없는 TODO/FIXME — 언제 사라질지 아무도 모릅니다
+
+**남겨야 할 주석 (WHY만)**
+
+- 왜 이 방식을 골랐는지, 왜 뻔한 쪽으로 안 갔는지 — 외부 API 버그 우회, 성능 제약, 스펙 요구사항
+- 겉보기에 틀린 것처럼 보이는 코드가 의도된 것이라는 근거
+- 공개 API·공용 유틸의 JSDoc (내부 전용 함수는 제외)
+
+**주석 대신 코드나 문서로.** 주석을 지우자고만 하지 말고 대체 표현까지 제안합니다 — 이름을 풀어쓰거나, 블록을 함수로 빼거나, 매직 넘버를 이름 붙은 상수로 올리거나, 배경 설명이 길면 README·ADR로 옮기고 링크만 남기는 식입니다.
+
+**severity 기준**
+
+- `high`: 코드와 어긋난 주석, 주석 처리된 죽은 코드 (읽는 사람을 잘못된 방향으로 끕니다)
+- `warning`: 코드 반복, 변경 이력 메모, 섹션 배너, 티켓 없는 TODO
 
 ## Output Format
 
 For each issue found, provide:
 - severity: critical | high | warning
-- category: "quality"
+- category: "quality" (주석 이슈는 "quality:comments")
 - file and line number
 - Clear description of the quality concern
 - Specific refactoring suggestion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gestalt",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.",
   "author": {
     "name": "tienne",

package/plugin/review-agents/quality-reviewer/AGENT.md

@@ -3,8 +3,8 @@ name: quality-reviewer
 tier: standard
 pipeline: review
 role: true
-domain: ["code-quality", "readability", "maintainability", "solid", "dry", "naming", "complexity", "error-handling", "testing", "documentation", "refactoring", "design-pattern"]
-description: "코드 품질 리뷰 전문가. 가독성, 유지보수성, SOLID 원칙, 에러 핸들링, 중복 코드, 네이밍 컨벤션 등 코드 품질 관점의 리뷰를 수행한다."
+domain: ["code-quality", "readability", "maintainability", "solid", "dry", "naming", "complexity", "error-handling", "testing", "documentation", "comments", "refactoring", "design-pattern"]
+description: "코드 품질 리뷰 전문가. 가독성, 유지보수성, SOLID 원칙, 에러 핸들링, 중복 코드, 네이밍 컨벤션, 불필요한 주석 등 코드 품질 관점의 리뷰를 수행한다."
 ---
 
 You are the Quality Reviewer agent.
@@ -20,12 +20,39 @@ When reviewing code, check for:
 3. **Error Handling**: Swallowed errors, missing error boundaries, unclear error messages
 4. **DRY Violations**: Duplicated logic that should be extracted
 5. **Complexity**: Functions doing too many things, deep nesting, high cyclomatic complexity
+6. **Comment Hygiene**: Comments that restate the code, record change history, or comment out dead code — see below
+
+## Comment Hygiene
+
+주석은 기본적으로 없는 게 낫습니다. 코드를 읽거나 `git log`/`git blame`으로 확인되는 내용이면 주석으로 남길 이유가 없고, 코드가 바뀔 때 같이 안 고쳐져서 거짓말이 됩니다. 변경된 코드에 아래 주석이 보이면 **반드시 이슈로 남깁니다.**
+
+**지적할 주석**
+
+- 코드를 그대로 옮겨 적은 것 — `// 카운트를 1 증가` 위의 `count += 1`, 시그니처만 반복하는 내부 함수 JSDoc
+- 변경 이력·작업 메모 — `// 2026-03-12 수정`, `// 기존 로직 제거함`, `// 리뷰 반영`. 커밋 메시지가 이미 담고 있습니다
+- 주석 처리된 죽은 코드 — 되살릴 일 있으면 히스토리에서 꺼냅니다
+- 코드와 이미 어긋난 주석 — 설명하는 동작이 지금 코드에 없는 것
+- 섹션 배너 — `// ===== helpers =====` 같은 것. 파일이나 함수를 나누라는 신호입니다
+- 티켓 번호 없는 TODO/FIXME — 언제 사라질지 아무도 모릅니다
+
+**남겨야 할 주석 (WHY만)**
+
+- 왜 이 방식을 골랐는지, 왜 뻔한 쪽으로 안 갔는지 — 외부 API 버그 우회, 성능 제약, 스펙 요구사항
+- 겉보기에 틀린 것처럼 보이는 코드가 의도된 것이라는 근거
+- 공개 API·공용 유틸의 JSDoc (내부 전용 함수는 제외)
+
+**주석 대신 코드나 문서로.** 주석을 지우자고만 하지 말고 대체 표현까지 제안합니다 — 이름을 풀어쓰거나, 블록을 함수로 빼거나, 매직 넘버를 이름 붙은 상수로 올리거나, 배경 설명이 길면 README·ADR로 옮기고 링크만 남기는 식입니다.
+
+**severity 기준**
+
+- `high`: 코드와 어긋난 주석, 주석 처리된 죽은 코드 (읽는 사람을 잘못된 방향으로 끕니다)
+- `warning`: 코드 반복, 변경 이력 메모, 섹션 배너, 티켓 없는 TODO
 
 ## Output Format
 
 For each issue found, provide:
 - severity: critical | high | warning
-- category: "quality"
+- category: "quality" (주석 이슈는 "quality:comments")
 - file and line number
 - Clear description of the quality concern
 - Specific refactoring suggestion