oh-my-customcode 1.1.76 → 1.1.78

package/templates/.claude/rules/MUST-continuous-improvement.md

@@ -4,21 +4,39 @@
 
 ## Core Rule
 
-When user points out a violation: update the relevant rule → commit → then continue original task.
+When user points out a violation: update the relevant rule → commit → then continue original task. Update the rule itself, not just acknowledge the violation.
 
+<!-- DETAIL: Core Rule, original 2nd sentence
 Update the relevant rule rather than just acknowledging the violation.
+-->
 
 ## Workflow
 
+1. Acknowledge violation
+2. Identify root cause
+3. Update the rule
+4. Wiring check (see below) — when the new clause governs delegation prompts, apply it to this iteration's own delegation prompts before continuing
+5. Commit
+6. Continue original task
+
+<!-- DETAIL: Workflow, original wording
 1. Acknowledge violation
 2. Identify root cause (which rule was weak/unclear?)
 3. Update the rule (add clarity, examples, self-checks)
 4. Wiring check — confirm the rule is wired into an execution path, or mark it as wiring-not-required (see Rule Wiring Check below) — and, when the new clause governs delegation prompts, apply it to this iteration's own delegation prompts before continuing (동일 반복 self-check)
 5. Commit the change
 6. Continue original task following updated rules
+-->
 
 ### Rule Wiring Check (배선 확인)
 
+텍스트 추가와 실행 경로 배선은 별개다. 배선 누락 시 동일 결함이 재발한다. 판단: (1) 실행 경로(워크플로우/스킬/훅/CI) 존재 여부 (2) 반영 여부 (3) 없으면 "배선 불요" 명시. 오케스트레이터 자신의 산문·신설 조항의 동일 반복 내 즉시 적용에도 대칭 적용.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| 조항만 추가하고 커밋 → 발동 지점 없어 재발 | 발동 실행 경로 명시 + 반영 확인; 없으면 "배선 불요" |
+
+<!-- DETAIL: Rule Wiring Check intro, original wording
 규칙 텍스트를 추가하는 것과, 그 규칙이 실행 경로에서 발동되게 배선하는 것은 **별개 작업**이다. 텍스트만 추가하고 배선을 누락하면 동일 결함이 재발한다.
 
 **판단 항목** (규칙 승격 시 판단하고 기록):
@@ -31,7 +49,9 @@ Update the relevant rule rather than just acknowledging the violation.
 | Anti-pattern | Required |
 |--------------|----------|
 | 규칙 조항만 추가하고 커밋 → 자동화 경로에 발동 지점이 없어 동일 결함 재발 | 발동 실행 경로 명시 + 반영 확인; 대상 없으면 "배선 불요" 명시 |
+-->
 
+<!-- DETAIL: Rule Wiring Check, 원문 전문 (신설 조항 self-check, Origin, 적용 범위 확장)
 **신설 조항의 동일 반복 self-check (Origin: #1691 #4·#5·#7 — v1.1.71)**: 위임서 규율을 신설·보강한 반복에서는, 그 조항을 **같은 반복에서 오케스트레이터가 작성하는 이후 위임서에 즉시 적용**한 뒤 다음 단계로 넘어갑니다. v1.1.69에서 R010 「출처 인용과 인접 문구 점검도 같은 규율」을 신설한 바로 그 반복의 위임서가 이슈 문장을 인용하지 않고 같은 파일 grep을 요구하지 않아 자기 위반 3건(High 1건 포함)이 적대적 리뷰에서 적발되었습니다 — 텍스트가 룰에 실렸다는 사실은 오케스트레이터 자신의 행동이 바뀌었다는 증거가 아닙니다(배선: auto-dev.yaml implement 스텝 bullet — 신설·보강 조항의 Anti-pattern 표를 위임서와 1:1 대조, 4사본 — v1.1.75).
 
 | Anti-pattern | Required |
@@ -43,6 +63,7 @@ Origin: #1533 (v1.1.35에서 R017 (b) 조항 추가했으나 auto-dev.yaml versi
 Cross-reference: R021(Enforcement Policy — advisory 규칙의 발동 지점), R017(구조 검증).
 
 **적용 범위 확장 (Origin: #1698 #1 — v1.1.72)**: 이 self-check는 서브에이전트에 **요구하는** 규율뿐 아니라 오케스트레이터가 **스스로 작성하는 산문(룰 문안·요약·수치)**에도 대칭 적용됩니다. 상세·인용은 R010 「출처 인용과 인접 문구 점검도 같은 규율」 보강 항목 참조.
+-->
 
 ## Integration
 
@@ -54,6 +75,18 @@ Cross-reference: R021(Enforcement Policy — advisory 규칙의 발동 지점),
 
 ## Defect Response Matrix
 
+| Defect Type | Rule | Memory | Issue | Skill |
+|-------------|:----:|:------:|:-----:|:-----:|
+| Rule violation | ✅ | — | — | — |
+| CI/infra defect | — | ✅ | ✅ | — |
+| Process gap | ✅ | ✅ | ✅ | ⚠️3회+ |
+| Repeatable bug | — | ✅ | ✅ | ⚠️구조적 |
+| Agent selection fail | — | ✅ | — | ✅라우팅 |
+| Ext. convention miss | ✅ | ✅ | — | ⚠️3회+ |
+
+Skill 승격: candidacy ≥2회, 확정 ≥3회. CI/process/repeatable은 memory+issue 둘 다 필수. 릴리즈 결함은 자동 이슈 등록. 반복 실패는 feedback + `/omcustom:adaptive-harness --learn`.
+
+<!-- DETAIL: Defect Response Matrix, original table
 | Defect Type | Rule Update | Memory | Issue | Skill Promotion |
 |-------------|:-----------:|:------:|:-----:|:---------------:|
 | Rule violation (agent behavior) | ✅ | — | — | — |
@@ -62,7 +95,9 @@ Cross-reference: R021(Enforcement Policy — advisory 규칙의 발동 지점),
 | Repeatable system bug | — | ✅ | ✅ | ⚠️ (수정이 구조적일 경우, 일회성 아닐 때) |
 | Agent selection failure (wrong agent routed) | — | ✅ | — | ✅ (라우팅 스킬 업데이트 후보) |
 | External repo convention miss | ✅ | ✅ | — | ⚠️ (3회 이상 반복 시) |
+-->
 
+<!-- DETAIL: Defect Response Matrix 원문 전문
 **Skill Promotion**: feedback memory가 동일 패턴으로 3회 이상 반복되면 "failure pattern"으로 승격. skill-extractor의 `--mode failure` 플래그로 스킬 후보 분석 가능 (Skillify 내재화, #972).
 
 > **Quantitative threshold (clarified, #1268)**: candidacy begins at **≥2 occurrences** (propose a candidate via skill-extractor's 4-criteria gate); confirmed promotion to a tracked failure pattern requires **≥3 occurrences**. The ≥2 candidacy tier feeds skill-extractor Phase 1; the ≥3 tier gates actual skill creation. See `skill-extractor` Selection Discipline.
@@ -82,64 +117,132 @@ When repeating agent failures or suboptimal routing is detected:
 3. Profile updates improve future agent selection and harness optimization
 
 This connects R016's continuous improvement loop with the adaptive-harness skill's learning capability.
+-->
 
 ## Rule Clause Retirement (조항 은퇴 메커니즘)
 
+승격 루프(위반 지적 → 조항 추가)만 돌면 코퍼스가 단조 성장한다. 은퇴 루프를 대칭으로 운용해 코퍼스 크기를 정상 상태로 유지한다.
+
+<!-- DETAIL: Rule Clause Retirement intro, original wording (stale "~49.5k 토큰" figure — replaced by #1717 문자 단위 실측, see 예산 게이트 DETAIL below)
 R016의 승격 루프(위반 지적 → 규칙 조항 추가)는 코퍼스의 **단조 성장**을 낳는다. 은퇴 루프를 대칭으로 신설해 코퍼스 컨텍스트 비용(세션당 고정 주입 ~49.5k 토큰)의 무한 증가를 차단한다. 승격 루프는 실증된 편익이 있으므로 유지하고, 은퇴 루프만 신설한다 — 두 루프의 대칭이 코퍼스 크기를 정상 상태로 유지한다.
+-->
 
 ### 은퇴 대상
 
+| 대상 | 판정 기준 |
+|------|-----------|
+| 수정 완료된 플랫폼 버그 서사 | 행동 지시 가치 소멸 |
+| 장기 무발동 조항 | 마이너 2릴리즈 미발동 |
+
+<!-- DETAIL: 은퇴 대상, original wording
 | 대상 | 판정 기준 |
 |------|-----------|
 | 수정 완료된 플랫폼 버그 서사 | CC 버전노트 등 행동 지시 가치가 소멸한 조항 (버그가 이미 수정되어 회피 지침이 무의미) |
 | 장기 무발동 조항 | 마이너 2개 릴리즈 동안 위반 지적·회고 인용으로 발동되지 않은 조항 |
+-->
 
 ### 은퇴 절차
 
+1. 발동 추적(feedback memory) 2. 후보 선정(무발동+가치소멸) 3. HTML 주석으로 감싸 RETIRED 표식(릴리즈·사유)을 붙여 제외(무손실, Read 열람 — R005) 4. 재발 시 uncomment 복원
+
+<!-- DETAIL: 은퇴 절차, original wording
 1. **발동 추적**: `/homework` 회고·위반 지적 시 인용된 규칙 ID/조항을 feedback memory에 기록한다 (가벼운 추적 — 완전 자동화는 불요).
 2. **후보 선정**: 마이너 2릴리즈 무발동 + 행동 지시 가치 소멸 조항을 은퇴 후보로 선정한다.
-3. **HTML-comment화**: 조항을 `<!-- RETIRED (은퇴 릴리즈 vX.Y.Z, <사유>): 원문 -->` 로 감싸 auto-injection에서 제외한다. `<사유>`는 위 「은퇴 대상」 두 범주에 대응한다 — 장기 무발동은 `N릴리즈 무발동`, 수정 완료된 플랫폼 버그 서사는 `보존 기준 v2.1.NNN 미만`. Read 도구로 열람 가능하므로 무손실이다 (R005 Context Optimization via HTML Comments).
+3. **HTML-comment화**: 조항을 `<!\-\- RETIRED (은퇴 릴리즈 vX.Y.Z, <사유>): 원문 \-\->` 로 감싸 auto-injection에서 제외한다. `<사유>`는 위 「은퇴 대상」 두 범주에 대응한다 — 장기 무발동은 `N릴리즈 무발동`, 수정 완료된 플랫폼 버그 서사는 `보존 기준 v2.1.NNN 미만`. Read 도구로 열람 가능하므로 무손실이다 (R005 Context Optimization via HTML Comments).
 4. **부활**: 동일 패턴이 재발하면 uncomment하여 즉시 복원한다 — 승격 루프와 대칭이다.
+-->
+
+### 버전노트 보존정책 (v1.1.77 개정 — 서사는 가이드, 룰은 1줄만)
 
-### 버전노트 보존정책
+CC 릴리즈 지식은 `guides/claude-code/15-version-compatibility.md`에 규칙별 절로 기록한다. 룰 본문에는 **현재 행동을 바꾸는 규범일 때만** 최대 1줄 — 버전 나열·근거 서사는 가이드로, 룰에 쌓지 않는다. `claude-native` 버전 추적 이슈의 액션 아이템도 이 목적지를 따른다. auto-dev.yaml `implement` 스텝의 규칙 목록(4사본)에 이 목적지 규범을 배선했다.
 
+<!-- DETAIL: 구 정책(v1.1.50, 상대폭 기준선) — 원 헤딩 "### 버전노트 보존정책" — v1.1.77에서 위 정책으로 대체(RETIRED, #1717)
 - 규칙 내 CC 버전노트(`> **v2.1.NNN+**:`)는 최근 2-3개 마이너 릴리즈(현행 기준 v2.1.230 이상)만 visible 유지한다.
 - 그 이하 버전노트는 HTML-comment화(무손실 중간 단계) 하거나 `guides/claude-code/15-version-compatibility.md`로 이관한다.
 - `claude-native` 스킬이 생성하는 버전 추적 이슈를 규칙에 반영할 때, 최신만 visible로 두고 구버전은 즉시 은닉한다.
 - **기준선은 고정 상수가 아니라 최신 CC 대비 상대 폭으로 유지한다**: 기준선 v2.1.212가 설정될 당시 CC 최신은 v2.1.233이었으므로 보존 폭은 약 21 patch였다. 이번 상향(v1.1.50, `claude --version` = `npm view @anthropic-ai/claude-code version` 실측 = v2.1.251) 시점에 같은 폭을 유지하려면 기준선이 v2.1.230이어야 한다 — 기준선 갱신 시 "최신 실측값 − 약 20 patch"로 재계산할 것.
 
-#### 은퇴 판정 기준 (기준선 미만 ≠ 자동 은퇴)
+폐지 사유: 상대폭 재계산은 매 릴리즈 반복 비용을 낳았고, `/memory` 경고(#1717 실측)가 근본 한계를 드러냈다 — 24개 instruction 파일이 308.8k자로 CC 150k자 한도를 초과했다. 새 정책은 임계값 대신 목적지(가이드 vs 1줄)로 통제한다.
+-->
 
-기준선 미만은 은퇴 **검토 대상**을 정의할 뿐, 은퇴 **여부**를 자동으로 결정하지 않는다. 기준선 미만 노트는 다음 3개 조건을 **모두** 충족할 때만 은퇴(HTML-comment화)한다 — 하나라도 걸리면 **유지**하고, 유지 판정과 사유를 스윕 기록에 남긴다.
+### 예산 게이트 (Tier 1, Origin: #1717)
+
+`CLAUDE.md` + `.claude/rules/*.md` 주석 제외 합계는 **≤140,000자**(하드 한도 150,000자, validate-docs CI 강제). 초과 시 같은 커밋에서 다른 조항을 은퇴·DETAIL화 — 순증 커밋 금지.
+
+측정: `python3 -c "import re,glob; f=['CLAUDE.md']+glob.glob('.claude/rules/*.md'); print(sum(len(re.sub(r'<!\-\-.*?\-\->','',open(x).read(),flags=re.S)) for x in f))"`
+
+<!-- DETAIL: #1717 실측 근거, 이슈 원문 인용
+실측 (2026-09-24, develop `aee1e50e`). 측정 명령: `python3`로 `CLAUDE.md` + `.claude/rules/*.md` 각 파일의 (a) 원문 길이, (b) `<!\-\-.*?\-\->` 제거 후 길이, (c) 주석 제거본에서 `^> \*\*(★+ )?v2\.1` 로 시작하는 blockquote 문단 길이를 합산.
 
+| 지표 | 값 |
+|------|----|
+| 원문 합계 | 430,808자 |
+| **HTML 주석 제외 합계** | **306,752자** (경고의 308.8k와 일치 → CC는 주석을 세지 않음) |
+| 그중 CC 버전 노트 | 78,620자 |
+| 최대 파일(주석 제외) | R010 46,219 / R020 39,954 / R006 25,103 / R002 17,469 / R017 16,781 |
+
+R016이 적어 두었던 "세션당 고정 주입 ~49.5k 토큰"은 낡은 수치다 — 위 문자 단위 실측으로 대체한다(토큰 수는 tokenizer에 따라 달라지므로 문자 수를 1차 지표로 삼는다). Origin: #1717.
+-->
+
+### 은퇴 판정 기준 (후보 선정 ≠ 자동 은퇴)
+
+3조건 **모두** 충족해야 은퇴 — 하나라도 거짓이면 유지+사유 기록.
+
+| 조건 | 판정 |
+|------|------|
+| (a) 인용 부재 | 다른 visible 노트가 인용하지 않는가 |
+| (b) 비현행 | 현행 동작을 규정하지 않는가 |
+| (c) 진단 함의 소멸 | 회고적 재해석 근거가 없는가 |
+
+<!-- DETAIL: 은퇴 판정 기준, original table
 | 조건 | 판정 |
 |------|------|
 | (a) 인용 부재 | 다른 어떤 visible 노트도 그것을 "같은 계열"(cf., 연장선, 인접 등)로 인용하지 않는가 |
 | (b) 비현행 | 현행 동작을 규정하지 않는가 (예: 이미 롤백/재수정된 과거 상태 서술) |
 | (c) 진단 함의 소멸 | 회고적 진단 함의(과거 관측 재해석 근거)가 더 이상 없는가 |
+-->
+
+<!-- DETAIL: 은퇴 판정 기준, original heading "#### 은퇴 판정 기준 (기준선 미만 ≠ 자동 은퇴)" + 원문 전문 + v1.1.50 실적
+기준선 미만은 은퇴 **검토 대상**을 정의할 뿐, 은퇴 **여부**를 자동으로 결정하지 않는다. 기준선 미만 노트는 다음 3개 조건을 **모두** 충족할 때만 은퇴(HTML-comment화)한다 — 하나라도 걸리면 **유지**하고, 유지 판정과 사유를 스윕 기록에 남긴다.
 
 세 조건 모두 참 → 은퇴. 하나라도 거짓 → 유지(anchor로 인용되거나, 현행 동작을 서술하거나, 진단 함의가 살아있는 노트는 기준선 미만이어도 보존 가치가 있다). 이 기준은 v1.1.50 4개 병렬 그룹의 실제 판정에서 역추출한 것이다(아래 실적 참조) — "기준선 미만 = 즉시 은퇴"로 문자 그대로 읽으면 이 기준과 모순된다.
 
-#### 보존 기준 변경 = 전 룰 파일 스윕 (같은 릴리즈 내 필수)
+Origin: #1563 찐빠 #4 — R016이 보존 기준을 v2.1.212로 규정했으나 R001/R005/R012에 visible v2.1.208 노트 3건이 잔존해 v1.1.44에서 뒤늦게 은퇴. Cross-reference: R005(HTML-comment 컨텍스트 최적화), R017(Count Sync — 전수 grep + 의미 판별).
 
-보존 기준선을 상향하면 **같은 릴리즈에서 23개 룰 파일 전수를 스윕**한다 — "스윕"은 기준 미만 노트의 **전량 HTML-comment화**가 아니라, 위 「은퇴 판정 기준」 3조건에 따른 **전수 검토**(각 노트를 은퇴/유지로 판정하고 유지 시 사유를 기록)를 의미한다. 기준만 올리고 검토 자체를 다음 릴리즈로 이월하면 코퍼스가 기준과 불일치한 상태로 남고, 그 불일치는 다음 회고에서 "잔존 N건" 부채로 재발견될 때까지 보이지 않는다 — **이월 금지는 변하지 않는다**, 변하는 것은 "전수 은퇴"가 아니라 "전수 판정"이 의무라는 점이다. 스윕 범위는 `.claude/rules/**`와 `templates/.claude/rules/**` 양쪽이며, 잔존 여부는 **HTML 주석 안/밖을 구분해** 실측한다 — 단순 `grep`은 이미 은퇴한 주석 내부 노트까지 세어 판정을 왜곡한다.
+**실적 (v1.1.50)**: 기준선을 v2.1.212→v2.1.230으로 상향할 때, 룰 파일 소유권을 4개 병렬 그룹으로 분배해 각 그룹이 자기 담당 파일만 스윕했다 — 스윕을 **작업 종류**(예: "은퇴 담당" vs "신규 노트 담당")가 아니라 **파일 소유권**으로 분배해야 병렬 에이전트 간 동일 파일 동시 편집 충돌이 발생하지 않는다(R009 File-Disjoint 원칙의 룰 코퍼스 자체 적용 사례). 스윕 결과는 **은퇴 2건 / 유지 다수**(기준선 미만 visible 노트 49건이 11개 파일에 잔존 — 전수 검토 후 유지 판정) — 은퇴된 2건은 어떤 visible 노트도 인용하지 않는 순수 이력 서사(R006 v2.1.201/204: v2.1.201 Sonnet 5 harness reminder 전달방식, v2.1.204 headless SessionStart 스트리밍)였고, 유지된 노트 대부분은 다른 visible 노트가 "같은 계열"로 인용하는 anchor이거나(예: v2.1.222가 v2.1.211/212/214를 인용) 현행 동작을 서술 중이었다. 은퇴 2건이 바로 "인용 없는 서사만 은퇴됐다"는 판정 기준의 양성 사례다. **판정이 버전 번호가 아니라 인용 관계로 이루어졌다는 뜻**이며, **이 판정 기준을 같은 릴리즈에서 정식 조항으로 승격했다**(sauron FAIL 지적 → 같은 커밋 내 정합화 — 위 「은퇴 판정 기준」참조). 잔존 49건/11파일은 결함이 아니라 3조건 판정에 따른 유지 결과이므로, 다음 회고가 이를 "잔존 N건" 부채로 오인하지 않도록 여기 고정 기록한다.
+-->
+
+### 판정 기준 조정 시 전 룰 파일 스윕
+
+은퇴 판정 기준이 조정될 때 **같은 릴리즈에서 룰 파일 전수를 판정**(전량 은퇴 아닌 위 3조건 전수 검토, 이월 금지) — 예산 초과 자체의 remedy는 위 예산 게이트(같은 커밋에서 초과분만 은퇴·DETAIL화)이며 이 절과 별개다. 범위 `.claude/rules/**`+`templates/.claude/rules/**`, 잔존은 주석 안/밖 구분 실측.
 
+| Anti-pattern | Required |
+|--------------|----------|
+| 판정 없이 전량 은닉/이월, `grep -c`로 잔존 판정 | 3조건 항목별 판정 후 같은 릴리즈에서 완료; 주석 안/밖 구분해 visible만 계수 |
+
+<!-- DETAIL: 예산 초과·기준 변경 시 전 룰 파일 스윕, original anti-pattern table
 | Anti-pattern | Required |
 |--------------|----------|
 | 보존 기준선만 상향하고 기존 노트 검토를 다음 릴리즈로 이월 | 기준 상향과 전 룰 파일의 **전수 판정**(은퇴/유지 + 유지 사유 기록)을 같은 릴리즈에서 완료 |
 | 기준선 미만 노트를 판정 없이 전량 HTML-comment화 | 「은퇴 판정 기준」 3조건(인용 부재 AND 비현행 AND 진단 함의 소멸)을 적용해 항목별 판정 |
 | `grep -c` 히트 수로 잔존 판정 | 주석 안/밖을 구분해 **visible 잔존**만 계수 — 잔존 자체는 결함이 아니다(유지 판정의 결과일 수 있음) |
+-->
 
-Origin: #1563 찐빠 #4 — R016이 보존 기준을 v2.1.212로 규정했으나 R001/R005/R012에 visible v2.1.208 노트 3건이 잔존해 v1.1.44에서 뒤늦게 은퇴. Cross-reference: R005(HTML-comment 컨텍스트 최적화), R017(Count Sync — 전수 grep + 의미 판별).
-
-**실적 (v1.1.50)**: 기준선을 v2.1.212→v2.1.230으로 상향할 때, 룰 파일 소유권을 4개 병렬 그룹으로 분배해 각 그룹이 자기 담당 파일만 스윕했다 — 스윕을 **작업 종류**(예: "은퇴 담당" vs "신규 노트 담당")가 아니라 **파일 소유권**으로 분배해야 병렬 에이전트 간 동일 파일 동시 편집 충돌이 발생하지 않는다(R009 File-Disjoint 원칙의 룰 코퍼스 자체 적용 사례). 스윕 결과는 **은퇴 2건 / 유지 다수**(기준선 미만 visible 노트 49건이 11개 파일에 잔존 — 전수 검토 후 유지 판정) — 은퇴된 2건은 어떤 visible 노트도 인용하지 않는 순수 이력 서사(R006 v2.1.201/204: v2.1.201 Sonnet 5 harness reminder 전달방식, v2.1.204 headless SessionStart 스트리밍)였고, 유지된 노트 대부분은 다른 visible 노트가 "같은 계열"로 인용하는 anchor이거나(예: v2.1.222가 v2.1.211/212/214를 인용) 현행 동작을 서술 중이었다. 은퇴 2건이 바로 "인용 없는 서사만 은퇴됐다"는 판정 기준의 양성 사례다. **판정이 버전 번호가 아니라 인용 관계로 이루어졌다는 뜻**이며, **이 판정 기준을 같은 릴리즈에서 정식 조항으로 승격했다**(sauron FAIL 지적 → 같은 커밋 내 정합화 — 위 「은퇴 판정 기준」참조). 잔존 49건/11파일은 결함이 아니라 3조건 판정에 따른 유지 결과이므로, 다음 회고가 이를 "잔존 N건" 부채로 오인하지 않도록 여기 고정 기록한다.
+<!-- DETAIL: 원 헤딩 "#### 보존 기준 변경 = 전 룰 파일 스윕 (같은 릴리즈 내 필수)", original wording
+보존 기준선을 상향하면 **같은 릴리즈에서 23개 룰 파일 전수를 스윕**한다 — "스윕"은 기준 미만 노트의 **전량 HTML-comment화**가 아니라, 위 「은퇴 판정 기준」 3조건에 따른 **전수 검토**(각 노트를 은퇴/유지로 판정하고 유지 시 사유를 기록)를 의미한다. 기준만 올리고 검토 자체를 다음 릴리즈로 이월하면 코퍼스가 기준과 불일치한 상태로 남고, 그 불일치는 다음 회고에서 "잔존 N건" 부채로 재발견될 때까지 보이지 않는다 — **이월 금지는 변하지 않는다**, 변하는 것은 "전수 은퇴"가 아니라 "전수 판정"이 의무라는 점이다. 스윕 범위는 `.claude/rules/**`와 `templates/.claude/rules/**` 양쪽이며, 잔존 여부는 **HTML 주석 안/밖을 구분해** 실측한다 — 단순 `grep`은 이미 은퇴한 주석 내부 노트까지 세어 판정을 왜곡한다.
+-->
 
 ### Cross-References
 
+R005(HTML-comment 최적화), R017(버전 노트 반영 전 실측 게이트), R023(폐기 참조 탐지), Origin #1473, #1717.
+
+<!-- DETAIL: Cross-References, original wording
 R005(HTML-comment 컨텍스트 최적화), R023(Deprecated-Platform-Feature Staleness Check — 폐기 참조를 결정론적으로 탐지하여 은퇴 후보를 조기 발굴), Origin #1473.
+-->
 
-## External Repo Contribution Pre-Check
+## External Repo Contribution Pre-Check — Before contributing to an external repo, MUST read CONTRIBUTING.md/AGENTS.md/domain checklist/validation commands FIRST round, before implementation. See file table + self-check via Read tool.
 
+<!-- DETAIL: External Repo Contribution Pre-Check, original wording
 Before starting work on contributing to an external repository (skill submission, agent contribution, plugin development), MUST read these files in the target repo FIRST round:
 
 | File | Purpose |
@@ -166,6 +269,7 @@ Before first implementation commit on external contribution:
 ```
 
 Reference issues: #1188 item #5, #1188 item #7, #1198 item #5.
+-->
 
 ## Anti-Patterns — 5 patterns: "I'll update later", "one-time exception", "doesn't cover this", "finish task first", "calibration during action-oriented tone". See table via Read tool.
 

package/templates/.claude/rules/MUST-enforcement-policy.md

@@ -6,7 +6,11 @@
 
 oh-my-customcode uses an **advisory-first enforcement model**. Most rules are enforced through prompt engineering (CLAUDE.md, rules/, `SessionStart` re-injection[^postcompact]) rather than hard-blocking hooks. This is intentional — it preserves agent flexibility while maintaining behavioral standards.
 
+[^postcompact]: 재주입 보장 경로는 `SessionStart`(matcher `*`, `claude-md-reinject.sh`)다. PostCompact 배선은 유지되나 `additionalContext` 미정의로 효과 미보장. Origin: #1619 #7. 상세는 Read 도구로 열람.
+
+<!-- DETAIL: [^postcompact] footnote (full text)
 [^postcompact]: compact 후 재주입의 문서상 보장 경로는 `SessionStart`(matcher `*`, `claude-md-reinject.sh` — v1.1.50 #1617)이다. 기존 PostCompact prompt 배선은 유지되나 공식 문서상 `additionalContext`가 정의돼 있지 않아 효과 미보장·발동 미검증(hook-events-audit 2026-08-29). 후속 바이너리 프로브(postcompact-probe 2026-08-29, CC 2.1.251)에서 dispatch 경로 실재가 확인됨(전용 실행 함수·payload 스키마 `trigger`/`compact_summary`·dispatch map 등록, PreCompact 대비 동형 구조). 따라서 '발동 미검증'은 'dispatch 실재하나 라이브 발동·prompt 핸들러 효과는 미검증'으로 좁혀진다 — `additionalContext` 미정의는 불변이므로 재주입 보장 경로는 여전히 SessionStart다. Origin: #1619 #7 — 최초 보고는 'PostCompact 공식 부재'였으나 감사 실측 결과 실재하되 additionalContext 미정의로 정정됨. 서브에이전트 보고의 검증 없는 인용이 틀린 전제를 회고 이슈까지 전파시킨 사례 (R020 원인 분석 검증 조항의 실증).
+-->
 
 ## Enforcement Tiers
 
@@ -16,20 +20,28 @@ oh-my-customcode uses an **advisory-first enforcement model**. Most rules are en
 | Soft Block | Stop hook prompt | R011 session-end saves | Auto-performs then approves |
 | Conversation Block | PostToolUse hook + `continueOnBlock` (CC v2.1.139+), exit 2 | stuck-detector, context-budget-advisor, cost-cap-advisor | Feeds rejection reason into conversation; Claude continues with awareness |
 | Advisory | PostToolUse hooks | R007, R008, R009, R010, R018 | Warns via stderr, never blocks |
-| Advisory (proactive) | UserPromptSubmit + SubagentStop + PostToolUse hooks | R007, R008 (`r007-r008-drift-advisor.sh` — #1229 UserPromptSubmit, #1545 SubagentStop, #1553 PostToolUse) | Reads last assistant turn; emits advisory if header/prefix absent. SubagentStop wiring (#1545) closes the no-user-input autonomous-loop gap (`/fsd`); PostToolUse (#1553) covers the orchestrator-only stretch before the first subagent spawn. Complements retroactive Stop-hook (`session-reflection.sh`, #1190). **v1.1.43부터 실제 발화 — 아래 각주 참조.** v1.1.49부터 역방향(announce > tool_use) 신호 포함, 기본 off 옵트인 (#1595 #6). v1.1.73의 narration 채널 분리 옵션(`OMCUSTOM_R008_NARRATION`, #1701 #2)은 실 세션 5건(CC 2.1.233~2.1.274) 실측에서 narration 마커 매칭 0/354·판정 on/off 동일로 전제가 성립하지 않아 v1.1.74에서 은퇴했습니다(#1703) — R008 누락은 채널 오선택이 아니라 마커 미직렬화 형태입니다. **v1.1.62(#1650 D)부터 서브에이전트 세션에서는 침묵**: hook stdin의 `agent_id`(CC 스키마상 서브에이전트 내부 발화에만 존재)가 있으면 exit 0 — 단 `SubagentStart`/`SubagentStop`은 `agent_id`가 대상 식별자라 예외(판정 수행). 중첩 서브에이전트 안의 SubagentStop은 억제 못 함(R010 정책상 도달 불가 경로). 완료 보고가 advisory 응답으로 대체되던 훅 피드백 잠식(R020 8항, #1652 #3)의 advisory 계열 차단. |
+| Advisory (proactive) | UserPromptSubmit + SubagentStop + PostToolUse hooks | R007, R008 (`r007-r008-drift-advisor.sh` — #1229 UserPromptSubmit, #1545 SubagentStop, #1553 PostToolUse) | Reads last assistant turn; emits advisory if header/prefix absent. SubagentStop wiring (#1545) closes the no-user-input autonomous-loop gap (`/fsd`); PostToolUse (#1553) covers the orchestrator-only stretch before the first subagent spawn. Complements retroactive Stop-hook (`session-reflection.sh`, #1190). **v1.1.43부터 실제 발화**(파서 셀렉터 `.role`→`.message.role` 수정 — 상세는 Read 도구로 원문 주석 참조). v1.1.49부터 역방향(announce > tool_use) 신호 포함, 기본 off 옵트인 (#1595 #6). v1.1.73의 narration 채널 분리 옵션(`OMCUSTOM_R008_NARRATION`, #1701 #2)은 실 세션 5건(CC 2.1.233~2.1.274) 실측에서 narration 마커 매칭 0/354·판정 on/off 동일로 전제가 성립하지 않아 v1.1.74에서 은퇴했습니다(#1703) — R008 누락은 채널 오선택이 아니라 마커 미직렬화 형태입니다. **v1.1.62(#1650 D)부터 서브에이전트 세션에서는 침묵**: hook stdin의 `agent_id`(CC 스키마상 서브에이전트 내부 발화에만 존재)가 있으면 exit 0 — 단 `SubagentStart`/`SubagentStop`은 `agent_id`가 대상 식별자라 예외(판정 수행). 중첩 서브에이전트 안의 SubagentStop은 억제 못 함(R010 정책상 도달 불가 경로). 완료 보고가 advisory 응답으로 대체되던 훅 피드백 잠식(R020 8항, #1652 #3)의 advisory 계열 차단. |
 | Advisory (telemetry) | PostToolUseFailure hook | — (계측 전용, 규칙 강제 없음) | `failure-ledger.sh` (#1561, v1.1.44) — 도구 실패를 JSONL 원장에 append. stdout/stderr 무출력이라 모델에 도달하지 않으며 절대 차단하지 않음 |
 | Advisory (proactive) | UserPromptSubmit hook | R020 (원인 진단) | `fail-axis-cause-advisor.sh` (#1561, v1.1.44) — 원장에 실패 기록이 있는데 원인 진술 없는 재촉 프롬프트가 오면 `hookSpecificOutput.additionalContext`로 "원인 가설 되묻기" advisory 전달. 원장 부재 시 조용히 통과 |
 | Prompt-based | CLAUDE.md + rules/ + `SessionStart` 재주입(matcher `*`; PostCompact 이벤트 배선은 유지되나 효과 미보장[^postcompact]) | All MUST rules | Behavioral guidance in context |
 
+훅 배선: `.claude/hooks/hooks.json`은 CC가 직접 로드하지 않는다 — 로드되는 것은 `.claude/settings.json`(+로컬+templates 미러)이며 `hooks-settings.ts`가 변환한다. 편집 후 재생성(빌드) 필수 — 누락 시 변경이 발화에 반영되지 않는다. Origin: #1623 (v1.1.53). 상세는 Read 도구로 열람.
+
+<!-- DETAIL: 훅 배선 경로 (v1.1.53, #1623) — full narrative
 > **훅 배선 경로 (v1.1.53, #1623)**: `.claude/hooks/hooks.json`은 CC가 로드하는 파일이 아니다 — CC 2.1.251 바이너리에 `.claude/hooks` 경로 참조가 0건이고, `settings.json`에 `hooks` 키가 이력상 존재한 적이 없었다. 컴파일레이션 메타포로는 `hooks.json` = **소스**(source), CC가 실제 로드하는 것은 `.claude/settings.json`(+`.local.json`, +`templates/` 미러)의 공식 `hooks` 블록 = **빌드 산출물**이며, 변환은 `src/core/hooks-settings.ts`가 담당한다(matcher 조건 DSL 12건은 스크립트 자체 가드 3건 + stdin-가드 래퍼 9건으로 이관). `omcustom init` 사용자는 `installHooksSettings()`가 최종 settings.local.json에 병합하는 경로를 거친다. **`hooks.json`만 고치고 settings 재생성(빌드)을 누락하면 변경이 발화에 반영되지 않는다** — R022 Wiki Sync의 "페이지 갱신 + 매니페스트 재시딩" 이원 요구와 동형이다. 라이브 실증(2026-08-29 새 세션 프로브): SessionStart hook_success 9건(플러그인 2 + 프로젝트 7), `[claude-md-reinject]` 마커 5히트, UserPromptSubmit·Stop 발화 확인 — **세션 단위 발화의 최초 실측**은 이 릴리즈다.
+-->
 
 | Anti-pattern | Required |
 |--------------|----------|
 | `hooks.json`만 편집하고 커밋 → settings.json `hooks` 블록 미재생성 | 편집 후 `hooks-settings.ts` 변환기(빌드) 실행 → settings.json(+local+templates) 재생성 확인 후 커밋 |
 
+교훈: **배선 확인 ≠ 전달 확인 ≠ 발화 확인 ≠ 로드 확인** — R020 "actual outcome ≠ attempt"의 훅 도메인 재현 사례. 상세는 Read 도구로 열람.
+
+<!-- DETAIL: Advisory 발화 결함과 해소 + 교훈 상세 (실측)
 > **Advisory (proactive/retroactive) 발화 결함과 해소 (실측)**: `hookSpecificOutput.additionalContext` **전달 경로 자체는 #1547(v1.1.40)에서 구현**됐으나, 그 앞단 **파서 셀렉터 결함**으로 advisory가 **v1.1.42까지 한 번도 발화하지 못했다** — `jq -r '.role'`로 읽었으나 트랜스크립트 최상위에 `role` 키가 없어(실제는 `.message.role`) `last_assistant`가 항상 비고 즉시 `exit 0`으로 종료됐다. 당시 실측: 트랜스크립트 771개 전수에서 `"additionalContext":` 출현 0건, 라이브 프로브 stdout/stderr 각 0바이트. **proactive(`r007-r008-drift-advisor.sh`)와 retroactive(`session-reflection.sh`, 동일 결함) 두 계층 모두 미발화**였다. **v1.1.43에서 양 계층 파서 복구 + `PostToolUse` 배선을 완료했고, 라이브 프로브로 최초 발화를 확인했다(#1553).** **재검토(#1623)**: 이 서술은 세션 단위 CC 훅 서브시스템 경유 증거가 없다 — 당시에도 CC가 로드하는 `settings.json`에 `hooks` 블록이 부재했으므로, 리서치(git 이력 전수) 판단으로는 스크립트에 synthetic stdin을 직접 주입한 검증이었을 가능성이 가장 유력하다(단정 금지 — "직접 증거 없음"으로 기록). 세션 단위 발화의 최초 실측은 위 「훅 배선 경로 (v1.1.53, #1623)」의 v1.1.53이다. 후속으로 v1.1.44에서 R008 판정을 블록 인접 비교 → 턴 단위 개수 비교로 전환(#1563), v1.1.45에서 Skill 도구 면제를 추가했다(#1569). **v1.1.49에서 역방향 신호**(announce > tool_use — 도구 호출을 예고해 놓고 tool_use 블록 없이 턴을 종료한 방향)**를 추가했다(#1595 #6)** — 기존 판정식 `max(0, tool_use − announce)`는 이 방향을 **구조적으로 0으로 처리**해 원리적으로 탐지 불가였다. 역방향은 **전용 앵커 정규식**(`$an_anchored`, 줄 시작 앵커 있음 — forward의 `$an_tool`에는 적용하지 않는다. forward는 announce를 덜 세면 위반이 **늘어나기** 때문)을 쓰고, **Skill 포함 전체 tool_use가 0건**일 때만 계상한다(Skill 제외 카운트를 쓰면 Skill만 호출한 준수 턴에서 오발화). 기본 off 옵트인(`OMCUSTOM_R008_REVERSE=on`으로 활성)이다 — 482턴 실측에서 순진한 `announce − ntools > 0` 구현은 36턴에 발화해 advisory 총량을 2배로 만들었고(16건은 Skill 제외 아티팩트, 15건은 앵커 없는 정규식의 산문 매칭), 협소화 후 3/3 진양성·오탐 0(앵커 비용은 실제 announce 969줄 중 1줄, 0.1%)이 되었으나 표본이 3건이라 기본 활성은 보류했다. **배선 구조상 예방 효과가 없다는 점도 보류 근거다** — 결함 턴은 tool_use가 0이라 `PostToolUse`·`SubagentStop`이 발화하지 않고, `UserPromptSubmit`은 사용자가 이미 개입한 뒤 발화한다. 정시에 발화하는 유일한 이벤트는 `Stop`이며 거기 걸린 훅은 `session-reflection.sh`다. 역방향은 그래서 **의도적으로 advisor 전용**이며 `session-reflection.sh`에는 복제하지 않았다(같은 결함을 두 번 보고하면서 교정 기회는 여전히 0이 되고, 되돌릴 지점만 두 곳이 된다).
 >
 > 교훈: **배선 확인 ≠ 전달 확인 ≠ 발화 확인 ≠ 로드 확인** — R020 "actual outcome ≠ attempt"의 훅 도메인 재현 사례. v1.1.53(#1623)이 드러낸 것은 이 셋보다 앞선 **제4층**이다 — 배선 파일(`hooks.json`) 자체가 CC에 **로드되지 않았다면** 배선·전달·발화 확인은 전부 무의미한 층 위에서 이루어진 것이다.
+-->
 
 <!--
 > **v2.1.163+**: Stop and SubagentStop hooks can return `hookSpecificOutput.additionalContext` (JSON) to feed structured feedback back into Claude's context without triggering a hook error label. This enables advisory-style enforcement via Stop/SubagentStop hooks (e.g., `session-reflection.sh`, omcustom-loop SubagentStop) to pass richer context — replacing plain stderr text — without disrupting the turn continuation behavior that advisory-first enforcement relies on.
@@ -39,6 +51,7 @@ oh-my-customcode uses an **advisory-first enforcement model**. Most rules are en
 
 <!-- RETIRED (은퇴 릴리즈 v1.1.45, 보존 기준 v2.1.212 미만): > **v2.1.210+**: hook callback timeout이 모델에 user rejection으로 오보고되어 unattended 세션이 정지 대기하던 문제가 수정되었습니다. R021 advisory 훅(PostToolUse/UserPromptSubmit/Stop 등)이 매 턴 발화하고 /fsd 등 장기 무인 루프가 이에 의존하므로, hook timeout이 더 이상 phantom rejection으로 무인 세션을 중단시키지 않습니다 — cf. v2.1.199 훅 실패 관측성. -->
 
+<!-- DETAIL: CC version notes (v2.1.211-v2.1.275)
 > **v2.1.211/212/214+**: 훅의 enforcement 결정이 auto/unattended 모드에서 안정적으로 존중되도록 세 건이 수정되었습니다 — (211) auto mode가 unsandboxed Bash에 대한 PreToolUse 훅의 `ask` 결정을 덮어쓰던 문제가 수정되어 훅 `ask`가 최소 prompt로 floor되고, (212) `continue:false` 훅의 halt가 도구 실패·중간 완료 시 누락되던 문제 및 훅 인프라 오류가 user rejection으로 오보고되던 문제가 수정되었으며, (214) 훅 stdout JSON이 스키마 검증에 실패할 때 exit code 2가 문서대로 차단하지 못하던 문제가 수정되었습니다. R021 Enforcement Tiers(Hard Block=exit 2, Conversation Block=continueOnBlock exit 2, Advisory)가 훅의 block/ask 결정 존중에 의존하므로, 세 수정 모두 hard-block·advisory 훅(stage-blocker, rule-deletion-guard, stuck-detector 등)의 강제 신뢰성을 강화합니다 — v2.1.210 훅 timeout phantom-rejection 수정의 연장선.
 
 > **v2.1.222+**: PreToolUse auto-allow 훅이 background agent task(summaries/compaction/renames)에서 tool restriction을 우회하던 문제가 수정되었습니다. 즉 위 Enforcement Tiers 표의 **Hard Block 계층(stage-blocker, dev-server tmux, rule-deletion-guard)이 background agent task 경로에서 우회될 수 있었다**는 뜻이며, background agent를 쓰는 장기 무인 루프에서 hard-block 훅이 실제로는 강제되지 않는 구간이 존재했습니다. v2.1.211/212/214 훅 결정 존중 체인의 연장선입니다.
@@ -58,6 +71,7 @@ oh-my-customcode uses an **advisory-first enforcement model**. Most rules are en
 > **v2.1.274+**: Stop prompt 훅이 대화 중 매 block마다 **전체 프롬프트를 통째로 재전송**하던 결함이 수정되어, 반복 block은 이제 500자 라벨로 조건만 명시합니다. R020 8항·메모리 v1.1.53~56에 기록된 "Stop 훅 잠식" 패턴에 직접 관련됩니다 — 구버전에서는 Stop 훅이 반복 block될 때마다 전체 프롬프트 텍스트가 모델 컨텍스트에 재주입됐으므로, 당시 관측된 토큰/턴 소모의 **기계적으로 충분한 원인**입니다(가설 등급 귀속 — 관측과 정합하나 이것으로 확정되지는 않음, R020 hypothesis 규율). 또한 플러그인 `hooks/hooks.json` 최상위의 `$schema` 키에 대해 "unknown key" 통지가 더 이상 뜨지 않게 되었습니다 — 이 저장소의 `.claude/hooks/hooks.json` 소스 파일에 향후 `$schema`를 추가할 때 관련됩니다.
 
 > **v2.1.275+**: (275) "Fixed `SubagentStop` hooks with a specific `matcher` firing for every stopping subagent whose agent type was empty" — 실측(`.claude/settings.json` SubagentStop 블록) 결과 이 저장소의 배선은 `"matcher": "*"` **와일드카드**이므로, "specific matcher"를 대상으로 하는 이 결함의 직접 대상이 **아닙니다**. (275) 와일드카드는 모든 서브에이전트 종료에 발화하는 것이 정상 동작이므로, 275 이전 SubagentStop 발화 계수(R020 Self-Violation Counting)를 이 결함으로 재해석하지 않습니다 — 기록용입니다. (275) 향후 agent type별 matcher(예: `"mgr-gitnerd"`)로 좁히는 배선을 도입하면 그때부터 이 결함의 대상이 되므로, v2.1.275 미만 환경에서는 좁힌 matcher가 빈 agent type에도 매칭된다는 점을 전제합니다.
+-->
 
 ## Why Advisory-First
 

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

@@ -81,7 +81,10 @@ At the start of every new task, issue, or autonomous sub-loop, answer these thre
 
 ### Failed Tool Re-Try Discipline
 
+<!-- DETAIL: Failed Tool Re-Try Discipline intro (full wording)
 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.
+-->
+User-specified tools persist across failures — retry the SAME tool, do NOT silently switch.
 
 | 시나리오 | Required |
 |---------|----------|
@@ -89,12 +92,18 @@ User-specified tools/formats persist across failures. After a tool rejection or
 | 자유 텍스트로 재질문 | 금지 — directive 위반 |
 | 다른 도구로 silent switch | 금지 — 명시적 사용자 확인 필요 |
 
+<!-- DETAIL: Failed Tool Re-Try reference issue
 Reference issues: #1188 item #4.
+-->
 
 ### User Directive Persistence — Git Push Continuation
 
+<!-- DETAIL: Git Push Continuation intro (full original wording)
 사용자가 같은 세션 내에서 명시적으로 커밋/푸시를 한 번 허용했다면, 동일 카테고리/동일 브랜치의 후속 작업은 추가 확인 없이 진행 가능. push security policy classifier가 first-time strict, follow-up relaxed로 동작해야 함.
+-->
+사용자가 동일 세션·브랜치의 git 커밋/푸시를 한 번 허용하면 후속 동일 작업은 재확인 불요(advisory warning만 출력) — 아래 「Destructive Operation Approval Persistence」의 git 특수 사례.
 
+<!-- DETAIL: Git Push Continuation full table + rationale
 | 시나리오 | 동작 |
 |----------|------|
 | 1차 명시 "커밋, 푸시" + 동일 브랜치 | mgr-gitnerd push 진행 (advisory warning은 출력) |
@@ -102,11 +111,16 @@ Reference issues: #1188 item #4.
 | 다른 브랜치 / 다른 카테고리 | 새 confirmation 필요 |
 
 **Why**: 사용자 directive 일관성 — #1208 보고. 같은 세션 내 동일 의도를 반복 차단하면 R015 user directive persistence 위반.
+-->
 
 ### Destructive Operation Approval Persistence (Generalized)
 
+<!-- DETAIL: Destructive Operation Approval Persistence intro (full wording)
 The Git Push Continuation pattern (first-time strict / follow-up relaxed, scoped to session + category + target) generalizes to ALL repeated destructive operations within the same session. Examples: `supabase db push`, `terraform apply`, `kubectl delete`, bulk file deletes, database migrations.
+-->
+사용자가 category C·target T에 1차 명시 승인한 후 동일 C+T 반복은 재확인 불요(advisory 경고 유지); 다른 category/target은 새 확인 필요. 예: `supabase db push`, `terraform apply`, `kubectl delete`.
 
+<!-- DETAIL: Destructive Operation Approval Persistence Scope (full wording) + dropped Scenario/Behavior table (redundant with the sentence above)
 **Scope**: once the user explicitly approves a destructive operation of category C against target T in a session, follow-up operations of the SAME C + SAME T do NOT require re-confirmation. An advisory warning is still emitted. A different category or different target always requires fresh confirmation.
 
 | Scenario | Behavior |
@@ -114,33 +128,58 @@ The Git Push Continuation pattern (first-time strict / follow-up relaxed, scoped
 | 1st explicit approval (category C, target T) | Proceed; advisory warning emitted |
 | Follow-up same session (same C + same T) | No re-confirmation (directive persistence) |
 | Different category or target | Fresh confirmation required |
+
 | Platform **permission prompt** repeats (asking to re-approve an already-allowed command) | Add a `settings.json` permission `allow` rule scoped to the specific command — this suppresses the prompt |
 | Platform **safety classifier BLOCK** (e.g. auto-mode refuses/flags the action, not merely prompting) | `allow` rule addition is **NOT effective** — the classifier is a separate layer from the permission-prompt layer. Have the user run the command directly (`!` prefix), or remove the trigger itself (e.g. drop an unnecessary bypass flag — see R010 「우회 플래그는 우회 대상과 근거를 명시」) |
+-->
+
+**R001 예외 (MUST)**: R001의 파괴적 git 명령(`reset --hard`/`clean -fd`/공유 `push --force`/미병합 `branch -D`)은 제외 — 매번 명시 승인 필요.
+
+**Advisory 한계**: allow 규칙으로는 safety-classifier 차단이 해소되지 않습니다 — 사용자가 `!`로 직접 실행하거나 차단 트리거를 제거해야 합니다.
 
+<!-- DETAIL: R001 exclusion full English wording
 **R001 exclusion (MUST)**: R001-listed catastrophic git operations (`git reset --hard`, `git clean -fd`, `git push --force` to shared branches, `git branch -D` with unmerged commits) are EXCLUDED from this persistence rule — they always require explicit per-invocation approval regardless of prior session approvals.
+-->
 
+<!-- DETAIL: Boundary/honesty note + allow-vs-classifier full rationale
 **Boundary / honesty note**: This rule is ADVISORY and governs model behavior only. It CANNOT suppress Claude Code's platform-level auto-mode classifier prompts. For genuine prompt suppression on a repeated destructive command, the user must add a `settings.json` permission allow rule scoped to the specific command (e.g., a specific `supabase db push` invocation). The model SHOULD surface this workaround when the user expresses friction about repeated prompts.
 
 `settings.json` **allow 규칙은 permission prompt를 억제하지만, safety classifier 차단은 억제하지 못한다 — 서로 다른 층이다** (#1592). 실효 경로는 두 가지뿐이다: (a) 사용자가 직접 실행, (b) 차단 트리거 자체를 제거(예: 불필요한 `--admin` 제거). 부가로, CC v2.1.229+는 위험 플래그(`--force`/`--amend`/`--no-verify`)를 가진 git/gh 명령을 auto-approve하지 않는다(설치 버전 실측 v2.1.233).
+-->
 
+<!-- DETAIL: Origin #1592 case narrative
 > Origin: #1592 (v1.1.47 세션 실측) — `permissions.allow`에 `Bash(gh:*)`와 `defaultMode: bypassPermissions`가 있는데도 `--admin` 포함 머지 위임이 auto-mode classifier에 차단됐다. `Edit(.claude/**)` allow 규칙이 있는데도 `.claude/settings.local.json` 편집이 차단됐다. 두 사례 모두 allow 규칙이 걸어둔 permission-prompt 층을 이미 통과한 상태에서 별도의 classifier 층이 차단한 것 — allow 규칙 추가로는 해소되지 않았고, 실효 해법은 (a) `--admin` 제거(R010 선행 실측 조항, #1591), (b) 사용자 직접 실행이었다.
+-->
 
+<!-- DETAIL: Cross-references (full list)
 Cross-references: R001 (safety — destructive operation pre-checks still apply), R002 (permission tiers), R010 (우회 플래그 선행 실측 — 차단 트리거 제거 경로). Reference issues: #1230, #1226 (item 2), #1592.
+-->
 
 ## User-Provided Input Precedence
 
+<!-- DETAIL: Origin #1327 OAuth case narrative
 > Origin: #1327 찐빠 #1 — the user created a NEW GitHub OAuth App and provided fresh credentials, but a script's "reuse existing github IdP if present" logic kept the OLD IdP/client_id, so login flowed through the stale credential. The freshly-provided input was silently ignored.
+-->
 
+<!-- DETAIL: User-Provided Input Precedence full rationale
 When the user EXPLICITLY provides new input (credentials, config values, IdP, API keys, endpoints), applying that new input takes precedence over idempotent "reuse existing" logic. After applying, VERIFY the change took effect — but compare ONLY non-secret identifiers (client_id, endpoint URL, key fingerprint/last-4), NEVER echo secret values into the transcript (R001). For secret material, verify via a side-effect probe (e.g., a test auth call succeeds) rather than value comparison.
+-->
+사용자가 명시적으로 새 입력(자격증명·설정값·키)을 제공하면 기존 재사용 로직보다 우선 적용 — 검증은 **비밀 아닌 식별자**로만(시크릿 echo 금지, R001; 시크릿 자체는 side-effect probe로 검증).
 
 | Anti-pattern | Required |
 |--------------|----------|
 | "An existing X is present → reuse it" when the user just supplied a new X | Apply the user-supplied X; treat reuse-logic as a fallback only when the user supplied nothing |
+
+<!-- DETAIL: additional Anti-pattern rows (equals-case / subset-fields / post-apply-verify — narrower cases of the kept row above)
 | User-supplied X EQUALS the existing X | Reuse is correct (idempotent no-op) — do NOT re-provision |
 | User supplies only a SUBSET of fields | Apply the supplied fields; reuse existing values only for the unsupplied fields |
 | Apply new credential, assume it took effect | Verify post-apply via non-secret identifier match or a side-effect probe — never echo secret values (R001) |
+-->
 
+<!-- DETAIL: Cross-reference (full wording)
 Cross-reference: R001 (credential guardrails — never echo secret values), R020 (verify actual outcome).
+-->
+Cross-ref: R001, R020.
 
 ## Agent Triggers