oh-my-customcode 0.149.0 → 0.150.0

package/README.md

@@ -222,7 +222,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (57)
+### Guides (58)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -279,7 +279,7 @@ your-project/
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 57 reference documents
+└── guides/                     # 58 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -2334,7 +2334,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.149.0",
+    version: "0.150.0",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -2014,7 +2014,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.149.0",
+  version: "0.150.0",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.149.0",
+  "version": "0.150.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/rules/MUST-intent-transparency.md

@@ -79,6 +79,30 @@ At the start of every new task, issue, or autonomous sub-loop, answer these thre
 - Related issue: #1188 item #4 — AskUserQuestion rejected, agent re-asked via free text in next turn (2026-05-19)
 -->
 
+### Failed Tool Re-Try Discipline
+
+User-specified tools/formats persist across failures. After a tool rejection or failure, retry with the SAME tool — do NOT silently switch to a different mechanism.
+
+| 시나리오 | Required |
+|---------|----------|
+| `AskUserQuestion` 거절됨 | 사용자가 다른 도구 명시할 때까지 `AskUserQuestion` 재시도 |
+| 자유 텍스트로 재질문 | 금지 — directive 위반 |
+| 다른 도구로 silent switch | 금지 — 명시적 사용자 확인 필요 |
+
+Reference issues: #1188 item #4.
+
+### User Directive Persistence — Git Push Continuation
+
+사용자가 같은 세션 내에서 명시적으로 커밋/푸시를 한 번 허용했다면, 동일 카테고리/동일 브랜치의 후속 작업은 추가 확인 없이 진행 가능. push security policy classifier가 first-time strict, follow-up relaxed로 동작해야 함.
+
+| 시나리오 | 동작 |
+|----------|------|
+| 1차 명시 "커밋, 푸시" + 동일 브랜치 | mgr-gitnerd push 진행 (advisory warning은 출력) |
+| 2차 연속 작업 (동일 카테고리, 동일 브랜치) | 1차 directive persistence — 재확인 요청 금지 |
+| 다른 브랜치 / 다른 카테고리 | 새 confirmation 필요 |
+
+**Why**: 사용자 directive 일관성 — #1208 보고. 같은 세션 내 동일 의도를 반복 차단하면 R015 user directive persistence 위반.
+
 ## Agent Triggers
 
 Defined in `.claude/skills/intent-detection/patterns/agent-triggers.yaml`. Each agent has keywords, file patterns, actions, and base confidence.

package/templates/.claude/rules/MUST-orchestrator-coordination.md

@@ -33,6 +33,11 @@ The main conversation is the **sole orchestrator**. It uses routing skills to de
 ║           NOT exempt.                                            ║
 ║     NO  → Good. Continue.                                        ║
 ║                                                                   ║
+║  5. Am I about to edit a root meta-file (.gitignore,             ║
+║     .editorconfig, README.md, CHANGELOG.md, CLAUDE.md, etc.)?   ║
+║     YES → Delegate to specialist per Root Meta-File table.       ║
+║     NO  → Good. Continue.                                        ║
+║                                                                   ║
 ║  If any answer points to a problem → resolve before proceeding   ║
 ╚══════════════════════════════════════════════════════════════════╝
 ```
@@ -98,6 +103,12 @@ Key violations to avoid (file writes, git commands, bundled operations — all m
 
 ✓ CORRECT: Agent/skill/guide creation routed through mgr-creator
    Skill(brainstorming) → Agent(mgr-creator) → Write(".claude/agents/new.md")
+
+❌ WRONG: Orchestrator edits ".gitignore" because "it's only 1 line"
+   Main conversation → Edit(".gitignore", "!/README.ko.md")
+
+✓ CORRECT: Even single-line edits delegate to specialist
+   Main conversation → Agent(mgr-gitnerd) → Edit(".gitignore", "!/README.ko.md")
 ```
 
 <!-- DETAIL: Common Violations (extended)
@@ -329,6 +340,22 @@ The following paths MUST be created or structurally modified ONLY through `mgr-c
 
 > **Enforcement**: Advisory (R021) — no hard-block hook. Candidate for promotion if violation rate exceeds threshold. See R021 Hard Enforcement Candidates.
 
+### Root Meta-File Delegation
+
+루트 메타 파일은 변경 규모와 무관하게 orchestrator 직접 편집 금지. 적절한 specialist에 위임:
+
+| Path | Delegated to |
+|------|--------------|
+| `.gitignore`, `.gitattributes` | mgr-gitnerd |
+| `.editorconfig`, `.prettierrc*`, `.eslintrc*` | mgr-updater |
+| `.npmrc`, `.nvmrc`, `package.json` (non-version fields), `package-lock.json` | mgr-updater |
+| `CODEOWNERS`, `.github/CODEOWNERS` | mgr-gitnerd |
+| `README.md`, `README*.md`, `CHANGELOG.md` | arch-documenter |
+| `LICENSE`, `NOTICE` | arch-documenter |
+| `CLAUDE.md` (project root) | arch-documenter (content) / mgr-updater (count sync) |
+
+**Why**: "1 line edit" 논리는 R010 약화 — orchestrator 직접 편집 진입로 차단. #1208 보고.
+
 <!-- DETAIL: System Agents Reference
 | Agent | File | Purpose |
 |-------|------|---------|

package/templates/CLAUDE.md

@@ -121,7 +121,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (R000-R023)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (57 토픽)
++-- guides/                      # 레퍼런스 문서 (58 토픽)
 ```
 
 ## 오케스트레이션

package/templates/README.md

@@ -55,7 +55,7 @@ templates/
 │   │   └── scripts/                 # 훅 셸 스크립트 (34개)
 │   ├── contexts/                    # 컨텍스트 설정 파일 (ecomode 등)
 │   └── ontology/                    # Ontology-RAG 지식 그래프
-└── guides/                          # 레퍼런스 문서 디렉토리 (54개)
+└── guides/                          # 레퍼런스 문서 디렉토리 (58개)
 ```
 
 ---

package/templates/guides/agent-teams/troubleshooting.md

@@ -0,0 +1,146 @@
+# Agent Teams 트러블슈팅 가이드
+
+## 개요
+
+Agent Teams 운용 중 발생하는 일반적 문제와 해결책. #1206/#1210 보고 기반.
+
+---
+
+## Graceful Shutdown 실패
+
+### 증상
+
+- `shutdown_request` 발신 2회 이상에도 멤버가 idle notification만 반환
+- TeamDelete 호출 시 "active members exist" 에러 → 교착 상태
+
+### 원인
+
+- 멤버가 long-running polling loop에 진입하여 외부 신호를 수신하지 못함
+- TaskUpdate 미발신 → 코디네이터가 멤버의 실제 상태를 인식 불가
+- `isActive` flag를 강제 해제할 수 있는 helper 부재
+
+### 해결 절차
+
+#### 1단계: 정상 graceful shutdown 시도
+
+```
+1. shutdown_request 1회 발신 (SendMessage)
+2. 30초 대기 후 멤버 status 확인 (TaskList)
+3. TaskUpdate(status: "completed") 응답이 오면 정상 종료 진행
+```
+
+#### 2단계: 재발신
+
+```
+1. shutdown_request 2회 발신
+2. 30초 추가 대기
+3. 여전히 무응답이면 3단계로 진행
+```
+
+#### 3단계: Force kill (last resort)
+
+```bash
+# 현재 세션의 tmux 목록 확인
+tmux -L claude-swarm-$$ ls
+
+# 특정 pane kill
+tmux -L claude-swarm-$$ kill-pane -t <pane-id>
+
+# 또는 전체 swarm 세션 kill
+tmux -L claude-swarm-$$ kill-server
+```
+
+#### 4단계: isActive flag 수동 해제
+
+tmux kill 후에도 TeamDelete가 실패하는 경우:
+
+```bash
+# teams 디렉토리 위치 확인
+ls ~/.claude/teams/<team-id>/
+
+# members.json에서 isActive를 false로 강제 설정
+jq '.members |= map(.isActive = false)' \
+  ~/.claude/teams/<team-id>/members.json \
+  > /tmp/m.json \
+  && mv /tmp/m.json ~/.claude/teams/<team-id>/members.json
+```
+
+> **주의**: `~/.claude/teams/` 경로는 CC 버전에 따라 다를 수 있습니다. 실제 경로는 CC 버전 릴리즈 노트에서 확인하십시오.
+
+#### 5단계: TeamDelete 재시도
+
+`isActive = false` 상태에서 TeamDelete를 재호출합니다. 성공 시 `~/.claude/teams/<team-id>/` 디렉토리가 자동 정리됩니다.
+
+### 예방
+
+- R018 Member TaskUpdate Discipline을 준수하면 코디네이터가 멤버 상태를 항상 추적 가능
+- 멤버 작업 시작 시 `TaskUpdate(status: "in_progress")` 즉시 호출
+- long-running loop (30초 이상) 마다 description 업데이트
+
+---
+
+## 멤버 무응답 (TaskUpdate 침묵)
+
+### 증상
+
+- 30초 이상 멤버가 `in_progress` 상태 미설정
+- 다른 멤버가 동일 task를 claim 시도 → 충돌 및 중복 작업 발생
+- 코디네이터가 멤버를 "dead" 로 오판하여 재spawn 시도
+
+### 원인
+
+- 멤버가 복잡한 계산이나 I/O에 진입한 후 TaskUpdate를 호출하지 않음
+- R018 Member TaskUpdate Discipline 위반
+
+### 해결 절차
+
+1. TaskList로 현재 task 상태 확인
+2. 해당 멤버에게 SendMessage로 상태 요청
+3. 60초 이상 무응답 시 Reassign 고려 (R018 Blocked Agent Behavior 참조)
+
+### 예방 (R018 준수)
+
+| 시점 | 필수 호출 |
+|------|-----------|
+| 작업 시작 | `TaskUpdate(taskId, status: "in_progress")` |
+| 30초 이상 분기/체크포인트 | `TaskUpdate(taskId, description: "<진행 상황>")` |
+| 완료 | `TaskUpdate(taskId, status: "completed")` |
+| 차단 시 | `TaskUpdate(taskId, description: "<차단 사유>")` + `SendMessage` |
+
+---
+
+## TeamDelete 후 잔여 리소스
+
+### 증상
+
+- TeamDelete 성공 후에도 `~/.claude/teams/` 하위에 디렉토리가 남음
+- 다음 세션에서 동일 team-id 재사용 시 충돌
+
+### 해결
+
+```bash
+# 잔여 팀 디렉토리 수동 정리
+rm -rf ~/.claude/teams/<team-id>/
+```
+
+---
+
+## CC Upstream 제한사항 (v2.1.146 기준)
+
+| 기능 | 현황 | 대안 |
+|------|------|------|
+| TeamDelete `force` 옵션 | 미제공 | tmux kill-pane (3단계 절차) |
+| 멤버 강제 종료 API | 미제공 | isActive flag 수동 해제 (4단계) |
+| Graceful shutdown timeout 설정 | 미제공 | 30초 대기 후 수동 처리 |
+
+CC가 정식 `force shutdown` API를 제공하면 3-4단계 workaround를 제거할 수 있습니다. 추적은 `guides/claude-code-tracking.md` 참조.
+
+---
+
+## Reference
+
+- Issue: #1210 (#1206 item 2 분리)
+- Cycle: v0.150.0
+- Memory: `feedback_agent_teams_force_shutdown.md`
+- R018: `.claude/rules/MUST-agent-teams.md` (Member TaskUpdate Discipline)
+- CC Upstream Tracking: `guides/claude-code-tracking.md`

package/templates/guides/claude-code-tracking.md

@@ -0,0 +1,86 @@
+# Claude Code Upstream Tracking
+
+oh-my-customcode가 의존하는 CC upstream API/기능 추적 목록. 각 항목은 현재 workaround와 정식 API 등장 시 제거할 대상을 명시합니다.
+
+---
+
+## Background Agent Progress API (#1212)
+
+### Status
+
+- **v2.1.146 기준**: 정식 progress API 미제공
+- `/bg` 흐름으로 시작한 background agent의 진행 상황을 메인 세션에서 직접 추적 불가
+
+### Workarounds
+
+| 방법 | 구현 | 한계 |
+|------|------|------|
+| stdout/stderr tail | `/tmp/.claude-bg-<id>.log` 파일을 수동으로 tail | 세션 간 log 파일 위치 불일치 가능 |
+| statusline agent count | R012 statusline에 `claude agents --json` (v2.1.144+) active count segment 추가 | count만 표시, 개별 진행률 없음 |
+| PostToolUse hook | `BackgroundTask` 이벤트 수신 후 별도 로그 작성 (커스텀) | hook 구현 부담, 이벤트 타입 안정성 미보장 |
+
+### Track
+
+- CC release note에서 background agent 관련 변경사항 모니터
+- 정식 progress API 등장 시 위 workaround를 모두 제거하고 공식 API로 대체
+- 후보 변경 키워드: `"background"`, `"bg agent"`, `"task progress"`, `"agent status"`
+
+### Reference
+
+- Issue: #1212 (#1206 item 7 분리)
+- Memory: `feedback_background_agent_progress_tracking.md`
+- Cycle: v0.150.0
+- R012: `.claude/rules/SHOULD-hud-statusline.md` (statusline integration)
+
+---
+
+## Agent Teams Force Shutdown (#1210)
+
+### Status
+
+- **v2.1.146 기준**: `TeamDelete`에 `force` 옵션 미제공
+- Graceful shutdown 실패 시 tmux kill-pane workaround 필요
+
+### Workaround
+
+tmux 세션 직접 kill + `isActive` flag 수동 해제 절차. 상세 절차는 `guides/agent-teams/troubleshooting.md` 참조.
+
+### Track
+
+- CC release note에서 TeamDelete API 변경사항 모니터
+- 정식 `force` 옵션 등장 시 troubleshooting.md의 3-4단계 workaround 제거
+- 후보 변경 키워드: `"TeamDelete"`, `"force shutdown"`, `"team teardown"`, `"agent kill"`
+
+### Reference
+
+- Issue: #1210 (#1206 item 2 분리)
+- Guide: `guides/agent-teams/troubleshooting.md`
+- Cycle: v0.150.0
+
+---
+
+## 추적 방법
+
+### 버전 확인
+
+```bash
+# 현재 CC 버전 확인
+claude --version
+
+# 또는 CC release notes
+# https://github.com/anthropics/claude-code/releases
+```
+
+### 모니터링 주기
+
+- 각 릴리즈 사이클(`/pipeline auto-dev`) 시작 시 CC 버전 확인
+- 새 버전 확인 시 이 파일의 "Status" 항목 업데이트
+- Workaround 제거 가능 시 해당 항목을 "Resolved" 섹션으로 이동
+
+---
+
+## Resolved
+
+> 해결된 항목은 여기에 기록합니다. 완전 제거 전 1개 릴리즈 사이클 동안 유지합니다.
+
+현재 없음.

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.149.0",
+  "version": "0.150.0",
   "lastUpdated": "2026-05-20T00:00:00.000Z",
   "omcustomMinClaudeCode": "2.1.121",
   "omcustomMinClaudeCodeReason": "Sensitive-path direct Write/Edit on .claude/** under bypassPermissions (R010 deprecation, #1101)",
@@ -26,7 +26,7 @@
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 57
+      "files": 58
     },
     {
       "name": "hooks",

package/templates/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": ["**/*.ts"]
+}