oh-my-customcode 1.1.76 → 1.1.78

package/templates/.claude/rules/MUST-tool-identification.md

@@ -15,12 +15,16 @@ For parallel calls: list ALL identifications BEFORE the tool calls.
 
 ### Common Violations to Avoid
 
+See examples via Read tool.
+
+<!-- DETAIL: Common Violations to Avoid — code block
 ```
 ❌ Missing: tool call with no identification prefix
 ✓ Correct: [agent-name][model] → Tool: WebFetch
            [agent-name][model] → Fetching: url
            <tool_call>...</tool_call>
 ```
+-->
 
 <!-- DETAIL: Full violation examples
 Incorrect: Calling tools without identification — no [agent][model] prefix before tool_call
@@ -33,31 +37,56 @@ Correct parallel: list ALL [agent][model] → Tool/Fetching/Running lines FIRST,
 
 ### Required-Parameter Completeness Check
 
+R008 prefix와 실제 호출은 분리 — prefix 출력 후 required 파라미터 완비를 확인한다.
+
+<!-- DETAIL: Required-Parameter Completeness Check intro — full text
 R008 prefix(announce)와 실제 도구 호출은 분리된 단계다. prefix 를 출력한 뒤 호출 payload 에서 도구 스키마상 required 파라미터를 누락하면 호출이 실패하거나 빈 동작이 된다. 호출 직전, prefix 존재뿐 아니라 required 파라미터가 모두 채워졌는지 확인한다.
+-->
+
+Anti-pattern: prefix만 출력·required 필드 누락 → prefix + required 필드 완비 후 호출.
 
+<!-- DETAIL: Required-Parameter Completeness Check table — full text
 | Anti-pattern | Required |
 |--------------|----------|
+| prefix만 출력하고 `questions` 배열 없음/빈 배열로 호출 | prefix + `questions` 배열(≥1) 모두 채워 호출 |
+| announce 후 payload required 필드 누락 | announce와 동일 메시지에서 required 필드 완비 호출 |
+-->
+
+<!-- DETAIL: Required-Parameter Completeness Check table rows — full text
 | AskUserQuestion 호출 앞에 Core Rule 형식의 prefix 라인(에이전트·모델 대괄호 다음 화살표와 Tool 표기)만 출력하고 `questions` 파라미터 없이/빈 배열로 호출 | prefix + `questions` 배열(최소 1개) 모두 채워 호출 |
 | announce 후 payload 의 required 필드 누락 (announce-payload separation gap) | announce 와 동일 메시지에서 required 필드 완비 호출 |
+-->
+
+Cross-reference: R020. Reference issue: #1324.
 
+<!-- DETAIL: Required-Parameter Completeness Check cross-ref — full text
 Cross-reference: R020 (action-completeness precondition — invoke 전에 required 파라미터 확인). Reference issue: #1324 (찐빠: AskUserQuestion `questions`-missing recurrence).
+-->
 
 ## Models
 
+`opus`(reasoning)/`sonnet`(default)/`haiku`(fast).
+
+<!-- DETAIL: Models table — full text
 | Model | Use |
 |-------|-----|
 | `opus` | Complex reasoning, architecture |
 | `sonnet` | General tasks, code generation (default) |
 | `haiku` | Fast simple tasks, file search |
+-->
 
 ## Tool Categories
 
+File Read/Write, Network(WebFetch), Execution(Bash/Agent).
+
+<!-- DETAIL: Tool Categories table — full text
 | Category | Tools | Verb |
 |----------|-------|------|
 | File Read | Read, Glob, Grep | Reading / Searching |
 | File Write | Write, Edit | Writing / Editing |
 | Network | WebFetch | Fetching |
 | Execution | Bash, Agent | Running / Spawning |
+-->
 
 ## Agent Tool Format
 
@@ -69,7 +98,11 @@ subagent_type:model → description
 
 ## Parallel Spawn Prefix Rule
 
+2+ 병렬 스폰 시 각 에이전트 `description`에 `[N]` 접두사(1-indexed) 필수.
+
+<!-- DETAIL: Parallel Spawn Prefix Rule intro — full text
 When spawning 2+ agents in parallel, each agent's `description` parameter MUST include a `[N]` prefix (1-indexed) to enable correlation with the Running display:
+-->
 
 ```
 Agent(description: "[1] Go code review", subagent_type: "lang-golang-expert")
@@ -78,7 +111,11 @@ Agent(description: "[2] Python code review", subagent_type: "lang-python-expert"
 
 Single agent spawns do NOT use the `[N]` prefix.
 
+단일 스폰도 Core Rule 접두사 필수 — advisor는 Tool 표기/번호 항목/단독 라인/Spawning 헤더 4종을 인식하나 요구 형식은 Core Rule 접두사다. Origin: #1652 #3-3.
+
+<!-- DETAIL: 단일 스폰 Core Rule 접두사 필수 — full text
 **단일 스폰도 Core Rule 접두사 필수 (Origin: #1652 #3-3, advisor 정합 #1650 E)**: 단일 Agent 스폰은 `[N]` 항목 형식 대신 Core Rule 형식의 접두사 라인(에이전트·모델 대괄호 + 화살표 + Tool 표기 + `Agent`)을 호출 직전에 출력한다. advisor(`.claude/hooks/scripts/r007-r008-drift-advisor.sh`)가 announce로 계수하는 것은 4종 — Tool 표기 라인, 대괄호 번호가 붙은 spawn 항목, **대괄호 번호 없이 에이전트타입:모델 다음에 화살표와 설명이 이어지는 단독 라인**(#1650 E에서 추가), Spawning 헤더 라인 — 이며 스폰 표기 3종은 **번호 항목 > 단독 라인 > Spawning 헤더** 순으로 하나만 채택된다. 단독 라인만 쓴 응답이 R008 누락으로 오계상되던 결함은 v1.1.62에서 해소됐다(v1.1.60 세션 실측 → v1.1.61 적대적 리뷰 재현 → #1650 E 적용). **다만 규칙이 요구하는 형식은 여전히 Core Rule 접두사 라인이다** — 단독 라인 계수는 오탐 제거이지 표기 승격이 아니다. 접두사 라인과 단독 라인이 함께 있으면 advisor는 단독 라인을 **동반 라인으로 보아 차감**하므로(Target 라인과 동일 취급) 병기해도 이중 계수되지 않는다. **단독 라인은 반드시 줄 시작(선행 공백만 허용)이어야 한다** — 리스트 마커가 앞에 붙으면 계수되지 않는다. advisor 판정식을 바꿀 때 이 문단을 같은 커밋에서 갱신한다(R016 Rule Wiring Check).
+-->
 
 ```
 [claude][opus] → Tool: Agent
@@ -87,7 +124,11 @@ Single agent spawns do NOT use the `[N]` prefix.
 
 | Anti-pattern | Required |
 |--------------|----------|
+| 단일 스폰을 단독 라인으로만 announce | Core Rule 접두사 라인을 호출 직전 출력 |
+
+<!-- DETAIL: Parallel Spawn Prefix Rule anti-pattern row — full text
 | 단일 스폰을 번호 없는 에이전트타입:모델 화살표 설명 단독 라인으로만 announce | Core Rule 접두사 라인(Tool 표기 + Agent)을 호출 직전에 출력; 항목 라인은 Target 라인으로 병기 가능 |
+-->
 
 This ensures the Running display:
 ```
@@ -105,21 +146,39 @@ matches the spawn announcement:
 
 ### Spawn Announce 리터럴 — advisor 정규식 정합 (Origin: #1595 #5)
 
+
+<!-- DETAIL: Spawn Announce 리터럴 intro — full text
 위 예시는 `.claude/hooks/scripts/r007-r008-drift-advisor.sh`의 판정식과 리터럴로 일치한다. 다음 변형은 **미매칭**되어, 규칙을 지킨 응답이 R008 위반으로 계상된다.
+-->
+
+금지: 번호 앞 리스트마커/백틱, Spawning 뒤 콜론 생략, 화살표 없이 설명만 이어붙임 — 셋 다 advisor 미매칭.
 
+<!-- DETAIL: Spawn Announce 리터럴 mismatch table — full text
 | 금지 변형 | 미매칭 이유 |
 |-----------|-------------|
 | 번호 앞에 리스트 마커(`- `)나 백틱을 붙임 | spawn-item 정규식은 **줄 시작의 대괄호 숫자**를 요구하며, 선행 공백만 허용한다 |
 | Spawning 뒤 콜론 생략 (예: "Spawning 4 agents") | 헤더 정규식이 **콜론**을 요구한다 |
 | 에이전트타입:모델 뒤에 화살표 없이 설명만 이어붙임 | spawn-item 정규식이 **화살표**를 요구한다 (U+2192 / ASCII 하이픈-부등호 / U+2014-부등호 3종만 인식) |
+-->
 
+<!-- DETAIL: 규칙-정규식 정합 필요성 — full text
 규칙 문구와 탐지기 정규식이 어긋나면 오탐 계수가 다시 규칙 개정의 근거가 되는 악순환이 생긴다. 형식을 바꿀 때는 advisor 정규식을 같은 커밋에서 갱신한다(R016 Rule Wiring Check).
+-->
+
 
+<!-- DETAIL: 문서 작성 주의 — full text
 **문서 작성 주의**: advisor의 announce 정규식에는 줄 시작 앵커가 없어, 표 셀·인라인 백틱 안에 완전한 리터럴을 넣으면 **그 문서를 인용하는 응답 턴이 announce로 오계상**된다(482턴 실측에서 실제 발생). 형식 예시는 코드 펜스 안에 줄 시작으로만 두고, 표에서는 산문으로 서술한다.
+-->
 
+Cross-ref: R009, R020.
+
+<!-- DETAIL: Spawn Announce 리터럴 cross-ref — full text
 Cross-ref: R009 「Narrative Announcement Format」(같은 리터럴을 산문 announce에 적용), R020 「자가 계수는 advisor 판정식을 재현한다」.
+-->
 
+<!-- DETAIL: Origin #1595 #5 — full text
 Origin: #1595 #5 (v1.1.48 세션 — R008 위반 3건이 단일 턴에 집중. tool_use=5 / announce=2로 계산됐고, 실제 announce는 리스트 마커와 백틱이 앞에 붙은 형식이라 전부 미매칭. 헤더도 콜론이 없었다).
+-->
 
 <!--
 > **v2.1.174+**: Fixed the Workflow tool's `agent()` subagents missing per-agent attribution headers. Workflow-spawned subagents now carry attribution consistent with R008 — when authoring Workflow scripts, each `agent()` call is attributed like a direct Agent tool spawn. Align Workflow orchestration with the R008 `[agent][model] → Tool:` identification discipline: a Workflow `agent()` fan-out should still be reasoned about with the same per-agent identification model as parallel Agent tool spawns.
@@ -127,29 +186,51 @@ Origin: #1595 #5 (v1.1.48 세션 — R008 위반 3건이 단일 턴에 집중. t
 
 ## announce와 헤더는 narration이 아니라 visible text 블록으로 (Origin: #1654)
 
+`text` 블록과 narration 블록은 한 메시지에 공존하지 않는다 — narration 요약만으로 턴을 시작하면 R007/R008 마커가 어디에도 남지 않는다. 헤더(`┌─ Agent:` 또는 단축 헤더)와 Core Rule 접두사를 **text 블록**에 먼저 쓴다 — 산문 요약은 그 뒤에. "announce를 썼다"는 기억으로 advisory를 오탐이라 가정하지 말고, 트랜스크립트의 text 블록에서 마커를 실측한다.
+
+<!-- DETAIL: announce/헤더 narration vs text 블록 — full text
 모델 출력에는 `text` 블록과 **narration 블록**(트랜스크립트에 `type:"thinking"` + signature 라벨 `narration`으로 직렬화되는 사용자향 짧은 산문)이 있고, 한 API 메시지에는 **둘 중 하나만** 실린다(v1.1.61~62 세션 실측: 115메시지 중 공존 0). 도구 호출 턴을 narration 요약 한 문장("…했습니다. 이제 …하겠습니다")으로 시작하면 R007 헤더와 R008 접두사는 **어디에도 남지 않는다** — 실측: narration 47블록에 R007 헤더 0건, 대괄호 번호 항목 0건, Tool 표기 0건(조사 문장 인용 제외). advisor는 `type != "thinking"` 필터로 narration을 배제하므로 이 턴들은 전부 누락으로 계상되며, 실제로 v1.1.61 세션 advisory 18건은 **전부 진양성**이었다(직렬화 유실 가설은 advisor가 메시지 직후에 판정했다는 사실로 배제됨).
+-->
 
+<!-- DETAIL: announce/헤더 narration Anti-pattern table — full text
 | Anti-pattern | Required |
 |--------------|----------|
 | 도구 호출 턴을 짧은 요약 산문만으로 시작(narration 채널로 흐름) | 헤더(`┌─ Agent:` 또는 단축 헤더)와 Core Rule 접두사를 **text 블록**으로 명시 — 산문 요약은 그 뒤에 |
 | "announce를 썼다"는 기억으로 advisory를 오탐으로 가정 | 트랜스크립트의 `text` 블록에서 마커를 실측(R020 Self-Violation Counting) |
+-->
 
+<!-- DETAIL: Iteration 1/2 대비 서술 (v1.1.75 보강으로 대체됨) — full text
 Iteration 1(Agent 스폰 15메시지 전부 narration)과 Iteration 2(7메시지 text)의 대비는 계수 도구 결함이 아니라 출력 채널 선택의 차이로 서술했으나, 이 귀속은 아래 v1.1.75 보강으로 대체되었다.
+-->
+
+실측(1008건): text 블록 부재 비율이 CC 2.1.251+에서 급증 — 근본 원인 `[가설]` 미확정.
 
+<!-- DETAIL: 원인 귀속 보강 (Origin #1703·#1706, v1.1.75) — full text
 **원인 귀속 보강 (Origin: #1703·#1706 — v1.1.75)**: 실 세션 6건·tool_use 응답 1008건(아티팩트 Part B 표 5건 860건 + 각주 인용 2.1.251 세션 148건, 재계산)을 재측정한 결과, text 블록이 없는 tool_use 응답의 비율이 CC 2.1.233에서 0%(0/256)였다가 2.1.251에서 39.2%(58/148)로 급증하고 2.1.258~2.1.275 구간에서 53.6~61.8%로 유지되는 것을 확인했습니다. 이 경계는 CHANGELOG v2.1.251의 "Fixed conversations getting stuck on \"text content blocks must be non-empty\" errors after a turn where the model produced only thinking" 항목과 일치합니다. narration 채널 옵션은 thinking 본문 354건 전수에서 마커가 0건 매칭되어 은퇴했으므로(#1703), R008 누락 턴은 마커가 narration으로 옮겨간 것이 아니라 thinking과 tool_use만 있고 text 블록이 없는 형태로 기록된 것입니다. `[가설]` 2.1.251 이전의 thinking-only 턴이 클라이언트 측 text 강제 주입으로 감춰졌는지 API 재시도로 트랜스크립트에서 탈락했는지, 그리고 thinking 내용이 announce 정규식과 왜 불일치하는지는 API 원본 스트리밍 로그 대조 없이는 미확정입니다.
+-->
 
 ## Tier-3 Interaction Tool Prefix (MANDATORY)
 
+<!-- DETAIL: Tier-3 Interaction Tool Prefix intro — full text
 R008 "every tool call" applies to Tier-3 interaction tools too — NOT only file/exec tools. Applying the Core Rule prefix form (에이전트·모델 대괄호 다음 화살표와 Tool 표기) to Agent/Bash/Read while omitting it on `AskUserQuestion`, `TodoWrite`, `EnterPlanMode`, etc. is a violation.
+-->
+
+AskUserQuestion/TodoWrite/EnterPlanMode/ExitPlanMode 필수; Skill만 예외(R007 헤더로 식별).
 
+<!-- DETAIL: Tier-3 prefix table — full text
 | Tool | R008 prefix required? |
 |------|----------------------|
 | AskUserQuestion | YES — Core Rule 형식의 prefix(에이전트·모델 대괄호 + 화살표 + Tool 표기 + 도구명)를 호출 앞에 출력 |
 | TodoWrite | YES |
 | EnterPlanMode / ExitPlanMode | YES |
 | Skill | NO separate R008 prefix — identified via R007 `claude → {skill-name}` integrated header instead |
+-->
 
+Skill 호출만 예외 — R007 통합 헤더(`claude → {skill-name}`)로 식별하며 별도 R008 접두사는 불요.
+
+<!-- DETAIL: Skill invocation exception — full text
 Skill invocation is the one exception: it is identified through the R007 integrated identification block (`┌─ Agent: claude → {skill-name}`), not a standalone R008 tool prefix.
+-->
 
 <!-- Reference issue: #1321 (session 113 retrospective, 찐빠 #2 — AskUserQuestion prefix omitted twice). -->
 
@@ -172,7 +253,11 @@ Agent(description: "[2] Python code review", subagent_type: "lang-python-expert"
 
 1. 이 호출 위에 Core Rule 형식의 prefix 라인(에이전트명·모델 대괄호 + 화살표 + Tool 표기 + 도구명)이 있는가?
 2. agent-name 과 model 이 현재 컨텍스트와 일치하는가?
+3. required 파라미터가 모두 채워져 있는가? (예: AskUserQuestion의 `questions` 배열이 비어 있지 않아야 함)
+
+<!-- DETAIL: Multi-Turn Self-Check item 3 — full text
 3. 이 호출에 도구 스키마상 required 파라미터가 모두 채워져 있는가? (예: AskUserQuestion 는 `questions` 배열이 비어 있지 않아야 함) prefix(announce)만 출력하고 실제 호출 payload 의 required 필드를 누락하면 안 된다.
+-->
 
 체크 실패 시 즉시 prefix/필수 파라미터를 보완한 후 호출.
 
@@ -190,8 +275,11 @@ Reference issue: #1096.
 
 ### Short Response Discipline
 
-도구 호출 prefix 도 응답 길이와 무관하게 필수. 같은 턴 내 여러 도구를 호출할 때 각 호출 직전에 개별 prefix 표시:
+도구 호출 prefix 도 응답 길이와 무관하게 필수. 같은 턴 내 여러 도구를 호출할 때 각 호출 직전에 개별 prefix 표시.
+
+형식은 Core Rule 코드 블록과 동일 — 호출마다 개별 표시. 상세는 Read 도구로 열람.
 
+<!-- DETAIL: Short Response Discipline — code block
 ```
 [agent][model] → Tool: Read
 [agent][model] → Target: file1.md
@@ -201,11 +289,15 @@ Reference issue: #1096.
 [agent][model] → Target: gh issue list
 <Bash call>
 ```
+-->
 
 <!-- Reference issues: #1188 item #3, #1198 item #3. -->
 
 ### External-Project / Debugging Session Vigilance
 
+R007과 세트로 자가 점검 — oh-my-customcode/외부 프로젝트/SSH·배포·인프라 작업 모두 동일하게 필수.
+
+<!-- DETAIL: External-Project Vigilance intro + session table — full text
 R007 헤더와 마찬가지로, R008 prefix 누락도 외부 프로젝트 디버깅·배포 세션에서 가장 자주 발생한다. R007/R008은 세트로 함께 자가 점검한다.
 
 | 세션 유형 | R008 prefix |
@@ -213,6 +305,7 @@ R007 헤더와 마찬가지로, R008 prefix 누락도 외부 프로젝트 디버
 | oh-my-customcode 작업 | 필수 |
 | 외부 프로젝트 디버깅 | **동일하게 필수** |
 | SSH / 배포 / 인프라 작업 | **동일하게 필수** |
+-->
 
 <!-- DETAIL: Case history — 외부 프로젝트 진단 세션(#1417)에서 Bash/Edit/Read/Agent 모든 호출에 `[agent][model] → Tool:` prefix가 세션 전체 누락된 재발이 관측되었다 — 도구 호출 직전 prefix 부착을 워크플로에 내재화한다.
 Reference issues: #1401, #1417.

package/templates/.claude/rules/SHOULD-ecomode.md

@@ -94,7 +94,7 @@ Active removal of irrelevant retrieved content from agent context. Complements o
 
 > **v2.1.260+**: 1M 컨텍스트를 가진 모델의 auto-compact 시점이 확대되어, Opus·Fable 세션도 이제 1M 토큰 한도 직전에 compact되고 매우 큰 컨텍스트에서의 recovery compaction이 더 이상 10분 타임아웃으로 실패하지 않습니다 — 위 v2.1.251 Sonnet 5 노트를 Opus/Fable 계열로 확장하는 것이므로, `CLAUDE_CODE_DISABLE_1M_CONTEXT`가 설정되지 않은 한 이 섹션의 백분율 임계값은 이제 세 모델군 전체에서 절대 토큰량 ~1M에 대응합니다. 같은 릴리즈에서 `/cost`와 statusline의 `prompt_cache` 필드가 prompt-cache miss의 **가능성 있는 원인**(도구 정의·시스템 프롬프트 변경, TTL 경과 idle)을 표시하도록 개선되어, 이 규칙이 다루는 캐시 관련 비용 이상 징후를 진단할 때 그 원인 후보를 출발점으로 삼을 수 있습니다 — 후보이지 확정 원인이 아니므로 R020 Proxy Signal 원칙대로 실측으로 확정합니다(cross-ref R012 statusline).
 
-> **v2.1.261+**: 컨텍스트 비용 진단 도구 2종이 추가되었습니다. `/skill-doctor`는 로드된 스킬 중 사용되지 않는 것과 그 컨텍스트 비용을 표시해 가지치기 대상을 알려줍니다 — 이 저장소의 115개 스킬 열거 블록과 `profile` 스킬의 플러그인 세트 전환에 직접 관련됩니다. `bashOutputMaxChars`/`taskOutputMaxChars` 설정은 command·background-task 출력이 파일로 저장되기 전 모델에 인라인 전달되는 상한을 올릴 수 있습니다(최대 128K자). 지침: 이 상한을 기본값으로 올리지 않습니다 — 이 규칙의 압축 원칙(파일 목록 → 개수, 오류 트레이스 → 앞/뒤 줄)이 작은 인라인 출력을 선호하므로, pass/fail 라인이 잘리는 특정 검증에 한해서만 올리고 그 외에는 독립적인 exit-code 조회(R005 #1492)를 우선합니다.
+> **v2.1.261+**: 컨텍스트 비용 진단 도구 2종이 추가되었습니다. `/skill-doctor`는 로드된 스킬 중 사용되지 않는 것과 그 컨텍스트 비용을 표시해 가지치기 대상을 알려줍니다 — 이 저장소의 115개 스킬 열거 블록과 `profile` 스킬의 플러그인 세트 전환에 직접 관련됩니다. `bashOutputMaxChars`/`taskOutputMaxChars` 설정은 command·background-task 출력이 파일로 저장되기 전 모델에 인라인 전달되는 상한을 올릴 수 있습니다(최대 128K자). **v2.1.277+**: `taskOutputMaxChars`는 `TaskOutput` 도구 제거로 더 이상 효과가 없습니다(상세는 `guides/claude-code/15-version-compatibility.md`). 지침: `bashOutputMaxChars`는 기본값으로 올리지 않습니다 — 이 규칙의 압축 원칙(파일 목록 → 개수, 오류 트레이스 → 앞/뒤 줄)이 작은 인라인 출력을 선호하므로, pass/fail 라인이 잘리는 특정 검증에 한해서만 올리고 그 외에는 독립적인 exit-code 조회(R005 #1492)를 우선합니다.
 
 > **v2.1.269/273+**: (269) auto-compaction이 요약할 완전한 이전 대화 교환이 없을 때(주로 매우 큰 프롬프트를 쓰는 SDK 세션) "Prompt is too long"으로 세션이 영구적으로 멈추던 결함이 수정되었습니다. (273) context meter와 auto-compact가 advisor-tool 턴을 실제 컨텍스트 크기의 약 **2배**로 계산해 auto-compact가 실제 창의 약 **절반** 지점에서 발동하던 결함이 수정되었습니다 — 이 규칙의 백분율 임계값에 대한 함의: 273 이전 2.1.2xx에서 advisor tool을 쓴 세션은 CTX% 수치와 auto-compact 시점이 최대 2배 부풀려져, 그 수치에 근거한 예산 판단이 의도치 않게 보수적이었습니다; 273+에서는 미터를 다시 신뢰할 수 있습니다(cross-ref R012 statusline CTX 세그먼트).
 

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -23,15 +23,28 @@ Agent frontmatter `memory: project|user|local` enables persistent memory:
 
 ## Subagent memory:project Source-Tree Pollution Guard
 
+
+<!-- DETAIL: Origin #1335 pollution guard
 > Origin: #1335 ② — lang-kotlin-expert with `memory: project`, working in a Kotlin source subdirectory, wrote memory to `mobile/.../com/baekenough/secondbrain/.claude/agent-memory/` — INSIDE the source package. Caught and removed just before commit.
+-->
 
+`memory: project` 서브에이전트가 하위 디렉토리에서 실행되면 `.claude/agent-memory/`가 소스 트리 안에 잘못 생성될 수 있습니다 — 메모리는 항상 프로젝트 루트 `.claude/`로 귀결해야 합니다.
+
+<!-- DETAIL: subagent memory pollution norm
 A subagent with `memory: project` working in a SUBDIRECTORY can create `.claude/agent-memory/` relative to its current working directory, polluting the source tree (e.g., inside a source package). Memory MUST resolve to the PROJECT ROOT `.claude/`, never a nested working dir.
+-->
+
 
 | Anti-pattern | Required |
 |--------------|----------|
 | Accept a subagent's `.claude/agent-memory/` written under a source package | Verify memory writes land at project-root `.claude/`; remove any nested `.claude/agent-memory/` from source dirs before commit |
 
+커밋 전 `find . -path '*/src/*/.claude' -o -path '*/main/*/.claude'`로 중첩 생성 여부를 확인합니다.
+
+<!-- DETAIL: nested memory check command
 Check for nested `.claude/agent-memory/` (e.g., `find . -path '*/src/*/.claude' -o -path '*/main/*/.claude'`) before committing subagent work.
+-->
+
 
 ## Best Practices
 
@@ -281,6 +294,9 @@ User Model data feeds into intent-detection (R015) and routing skill confidence
 
 ## Attention-Weight Memory Tiering
 
+메모리 항목은 confidence(신뢰도)와 attention weight(접근성) 두 축으로 관리하며, Hot/Warm/Cold/Archived 4-tier로 200줄 MEMORY.md 예산을 배분합니다. sys-memory-keeper에 메모리 갱신을 위임할 때는 위임서에 "압축·정리·티어 재평가 불요 — 지시한 항목만 기록"을 명시합니다(정리는 별도 위임, #1660).
+
+<!-- DETAIL: Attention-Weight Memory Tiering full detail (Origin #1279 through delegation-prompt rationale)
 > Origin: #1279 (Dual-Brain scout:internalize 부분 내재화 — attention-weight tiering만)
 
 메모리 항목은 신뢰도(confidence)와 접근성(attention weight)의 **두 축**으로 관리한다. 이 두 축은 직교한다.
@@ -349,6 +365,7 @@ Temporal Decay(시간 경과 기반)와 Attention-Weight Tiering(접근 빈도
 - archive 이동 시: `sessions_archive_*.md`에 append, MEMORY.md에 인덱스 라인 유지
 
 **위임서 표준 문안 (Origin: #1660 하네스 제안)**: sys-memory-keeper에 세션 메모리 갱신을 위임할 때 위임서에 "**압축·정리·티어 재평가 불요 — 지시한 항목만 기록**"을 명시합니다(정리가 필요하면 별도 위임으로 분리). 명시하지 않으면 에이전트가 자체적으로 MEMORY.md 압축을 목표에 추가해 턴 예산을 소진합니다 — v1.1.63 반복(#1660)에서 이 원인으로 15턴 절단이 2회 발생했습니다(R020 「maxTurns 절단 실증」의 메모리 위임 각도). 위 Tier 승강·archive 이동은 세션 종료 시 **별도 단일 목표 위임**으로 수행합니다.
+-->
 
 ## Mid-Session Immediate Save
 
@@ -362,7 +379,11 @@ Save memory IMMEDIATELY upon surprising discovery — do not defer to session en
 | User correction / feedback | Save `feedback_*.md` now | Honor correction immediately |
 | Root-cause hypothesis (원인 진단) | Save `feedback_*.md` ONLY with a `[hypothesis: <unverified-basis summary>]` first-line tag until the code path has been read and the decision logic reproduced 1:1; promote to plain fact only after that verification | Statistical correlation from transcript counts is NOT code causation — an unverified cause saved as fact propagates to issues and future sessions (#1652 #1; R020 「통계적 상관 ≠ 코드 인과」) |
 
+`[hypothesis: …]` 태그 규약(#1652 #1): 원인 진단을 메모리에 즉시 저장할 때는 본문 첫 줄에 `[hypothesis: <미검증 근거 요약>]`를 붙이고, 코드 경로 대조·판정 로직 1:1 재현으로 검증한 뒤에만 태그를 제거합니다 — 검증 전에는 결론이 아니라 트리거로만 사용합니다.
+
+<!-- DETAIL: hypothesis tag full rationale with 실증 examples
 **`[hypothesis: …]` 태그 규약 (Origin: #1652 #1)**: 원인 진단을 메모리에 즉시 저장할 때는 본문 첫 줄에 `[hypothesis: <미검증 근거 요약>]`를 붙인다. 검증(코드 경로 대조·판정 로직 1:1 재현) 완료 시 태그를 제거하거나 파일을 정정한다. 태그가 남아 있는 항목은 후속 세션에서 전제로 쓰지 않고 **검증 트리거로만** 사용한다 — 위 「Safety-Related Feedback Memory Framing」과 같은 원리(결론형이 아니라 검증 의무형)다. 실증: v1.1.59 세션에서 #1643 원인을 트랜스크립트 통계(첫 레코드 thinking 13/21)만으로 "advisor가 thinking 전용 첫 레코드를 병합하지 못함"이라 확정 저장했다가 jq 1:1 재현으로 반박됐고(실제 원인은 레이블 문구 모호성), 같은 세션에서 `gh pr merge --delete-branch` 로컬 부수효과도 reflog 3건으로 "확정" 저장한 뒤 4번째 머지에서 재현되지 않아 "원인 미확정"으로 정정했다. 리터럴은 `[hypothesis:` 접두 하나로 통일하며, 검증 여부 조회는 `grep -l '^\[hypothesis:' <memory dir>`로 결정론적으로 수행한다. 최초 적용 대상: `feedback_gh_merge_delete_branch_local_side_effect.md`(v1.1.60 세션에서 "원인 미확정"으로 정정된 항목) — v1.1.61 세션 종료 시 sys-memory-keeper가 태그를 부착한다.
+-->
 
 See rationale and cross-references via Read tool.
 
@@ -380,26 +401,42 @@ Related records from session v0.87.2~v0.88.0 (issue #869). The originating memor
 
 ## Procedure-Summary Scope Tagging
 
+절차·순서를 압축 요약할 때는 적용 스코프(예: "릴리즈 단계 내부 순서")를 함께 표기합니다 — 압축이 문맥 경계를 지우면 하위 단계 순서가 전체 파이프라인 순서로 오독됩니다.
+
+<!-- DETAIL: procedure-summary scope tagging full norm
 절차·순서를 메모리에 압축 요약할 때는 **적용 스코프를 함께 표기**한다. 압축은 문맥 경계를 가장 먼저 버리므로, 하위 단계 내부의 순서가 파이프라인 전체 순서로 읽히는 오독이 발생한다. 스코프 표기는 괄호 한 마디면 충분하다 — "(릴리즈 단계 내부 순서)", "(구현 커밋에는 미적용)"처럼 **무엇에 적용되지 않는지**까지 적으면 오독 여지가 사라진다.
+-->
 
 | Anti-pattern | Required |
 |--------------|----------|
 | `release 브랜치 선생성 → 버전범프 → PR` (스코프 미표기 → 전체 파이프라인 순서로 오독) | `릴리즈 단계 내부 순서: release 브랜치 선생성 → 버전범프 → PR (구현 커밋은 develop 직행)` |
 
+<!-- DETAIL: Origin #1563 procedure-summary
 Origin: #1563 찐빠 #5 — 위 요약이 릴리즈 단계 내부 순서인데 전체 파이프라인 순서로 오독되었다. Cross-reference: R013(Compact Output — 압축이 버리는 것을 인지), 위 Mid-Session Immediate Save(트리거 문맥 보존).
+-->
 
 ## Safety-Related Feedback Memory Framing
 
+<!-- DETAIL: Origin #1307 safety feedback framing
 > Origin: #1307 찐빠 #2 (Medium) — a sys-memory-keeper delegation prompt framed a learning as "오탐으로 판단하고 진행한다" (conclude it's a false positive and proceed), tripping the memory-poisoning safety classifier and requiring a rewrite.
+-->
+
+안전 관련 피드백 메모리는 **검증-의무형**으로 작성하고 **결론형**("오탐이므로 무시")은 금지합니다 — 결론형은 향후 세션이 진짜 위협 경고를 무시하게 만듭니다(memory-poisoning).
 
+<!-- DETAIL: safety feedback framing full norm
 Safety-related feedback memories MUST be written in **verification-obligation form**, NOT **conclusion form**. Conclusion-form framing ("ignore the warning and proceed", "오탐이므로 무시") risks future sessions ignoring genuine threat warnings (memory-poisoning).
+-->
 
 | Anti-pattern (conclusion form) | Required (verification-obligation form) |
 |--------------------------------|------------------------------------------|
 | "이 경고는 오탐이므로 무시하고 진행" | "이 패턴은 X 검증을 트리거; 검증 통과 시에만 진행, 실패 시 STOP" |
 | "warning is false positive, proceed" | "warning triggers a duty to verify Y; proceed only if verified, else STOP" |
 
+트리거(확인할 것)+STOP 조건(중단 시점)으로 작성하고, 특정 경고 부류를 무시할 상시 허가로 쓰지 않습니다.
+
+<!-- DETAIL: safety learnings triggers full text
 Write safety learnings as triggers (what to check) + STOP conditions (when to halt), never as standing permission to dismiss a class of warnings.
+-->
 
 ## Session-End Auto-Save
 
@@ -432,7 +469,11 @@ User signals session end
 
 ### Session-End Self-Check (MANDATORY)
 
+(1) sys-memory-keeper가 MEMORY.md 갱신했는가? (2) omcustom-feedback 활성 시, 마찰·학습이 관측되면 모델이 회고 이슈 초안을 Phase 4A 게이트로 제시할 수 있습니다(선택, MAY) — 또는 수동 트리거를 안내합니다. 확인 후 사용자에게 완료 보고합니다.
+
+<!-- DETAIL: session-end self-check full text
 (1) sys-memory-keeper updated MEMORY.md? (2) If `omcustom-feedback` skill is active, model MAY draft a retrospective feedback issue for user approval — or prompt user to trigger it manually. Both required before confirming to user. See full self-check via Read tool.
+-->
 
 <!-- DETAIL: Session-End Self-Check (MANDATORY)
 ```
@@ -457,6 +498,9 @@ User signals session end
 
 ### Session-End Retrospective Feedback (Model-Drafted)
 
+omcustom-feedback가 모델 호출 가능해진 이후(#1227), 세션 종료 시 마찰·학습이 관측되면 모델이 회고 피드백 이슈 초안을 작성해 Phase 4A 확인 게이트로 제시할 수 있습니다 — 자동 제출은 금지이며 항상 사용자 승인이 필요합니다.
+
+<!-- DETAIL: Session-End Retrospective Feedback full workflow/trigger/table detail
 Since `omcustom-feedback` is now model-invocable (#1227), the model MAY draft a retrospective feedback issue at session end — instead of only prompting the user to compose one manually.
 
 **Workflow**
@@ -481,22 +525,35 @@ Since `omcustom-feedback` is now model-invocable (#1227), the model MAY draft a
 The model-drafted path is an enhancement: it proposes a concrete draft rather than asking the user to compose from scratch. Both paths remain valid; neither replaces the other.
 
 References: #1226 (item 3), #1227.
+-->
 
 ### Failure Policy
 
 - Memory write failure is **non-blocking**: MUST NOT prevent session from ending
 - If sys-memory-keeper fails to write MEMORY.md: log warning, confirm to user anyway
 
+<!-- DETAIL: v2.1.228+ session cleanup memory deletion fix
 > **v2.1.228+**: **session cleanup이 프로젝트 memory 폴더 내부 내용을 삭제하던 결함**이 수정되었습니다. 구버전에서는 MEMORY.md·archive 파일이 세션 정리 단계에서 소실될 수 있었으므로, 메모리 누락을 위 Failure Policy의 쓰기 실패로만 진단하지 않습니다 — 쓰기는 성공했으나 정리에 삭제된 경우일 수 있습니다. 위 Memory Scopes 표대로 `project` 스코프(`.claude/agent-memory/`)는 git tracked라 복구 가능하지만 `user`/`local` 스코프는 복구 수단이 없습니다.
+-->
 
+<!-- DETAIL: v2.1.251+ directory change transcript relocation
 > **v2.1.251+**: 디렉토리 변경으로 세션이 동일 ID의 기존 트랜스크립트 위에 재배치돼 트랜스크립트가 손상/유실되던 결함이 수정되었습니다. 위 v2.1.228 "session cleanup이 project memory 폴더 내용을 삭제하던 결함"과 **같은 계열의 데이터 무결성 보강**입니다 — 구버전에서는 트랜스크립트 자체가 손상될 수 있었으므로, 그 시기 세션의 R020 회고적 위반 계수(트랜스크립트 파싱 기반)가 **불완전한 원본을 셌을 가능성**이 있습니다. `/cd`로 디렉토리를 옮기는 워크플로우에서 특히 유의합니다.
+-->
 
+<!-- DETAIL: v2.1.232+ Cowork user-scope import
 > **v2.1.232+**: Cowork 세션이 **user-scope 메모리 파일의 외부 @-import를 인라인하지 않습니다**. 즉 `~/.claude/agent-memory/`의 MEMORY.md가 @-import로 외부 파일을 끌어오는 구조라면 세션 종류에 따라 그 내용이 컨텍스트에 없을 수 있으므로, 항상 로드되어야 하는 내용은 import 참조가 아니라 **MEMORY.md 본문**에 둡니다(위 200줄 예산 내 Hot/Warm 배치 원칙과 정합).
+-->
 
+<!-- DETAIL: v2.1.268+ MEMORY.md truncation warning/compact dollar sign
 > **v2.1.268+**: (268) MEMORY.md truncation 경고가 이제 **몇 줄이 잘렸는지와 잘린 시작 위치**를 함께 표시합니다 — 위 「200줄 MEMORY.md 예산과의 연계」의 결정론적 트리거입니다: 이 경고가 뜨면 Cold 항목을 archive로 이동해야 합니다. (268) `/compact`와 auto-compact가 만드는 대화 요약이 `$` 시퀀스를 포함한 텍스트를 훼손하던 결함이 수정되었습니다 — 구버전에서 셸 스니펫(`$?`, `${PIPESTATUS[0]}`, `$PPID`)을 담은 compaction 요약은 손상됐을 수 있으므로, compact 이후의 요약을 근거로 "실제 실행된 명령"을 회상하는 것은 ground-truth가 아닙니다(cross-ref R005 zsh/`$?` 노트, R020). (268) `/compact`로 끝난 대화를 재개할 때 복원 파일 노트가 매 재개마다 동일한 순서로 로드되도록 수정되었습니다.
+-->
 
+<!-- DETAIL: v2.1.271/273+ background dedup/resume file-read/blockReadsOutside
 > **v2.1.271/273+**: (271) 대화가 compact된 뒤에도 계속 돌고 있던 백그라운드 명령(watch task, dev server)의 **중복 사본**이 새로 시작되던 결함이 수정되었습니다 — 구버전에서 post-compact 중복 프로세스는 지시가 아니라 compaction 아티팩트였습니다(cross-ref R010 dev-server tmux hard block). (271) `/resume`·`/teleport`가 이전 대화의 파일-읽음 추적을 그대로 유지해, 재개된 대화가 **한 번도 읽지 않은 파일**을 편집할 수 있던 결함이 수정되었습니다(cross-ref R005 v2.1.228 read-before-write 노트). (271) claude.ai에서 동기화된 스킬이 로그아웃 후에도 디스크에 남아있던 결함이 수정되어, `cleanupPeriodDays` 내 갱신되지 않은 사본은 이제 복구 가능한 휴지통으로 이동합니다. (273) `permissions.blockReadsOutsideWorkingDirectories`: 저장소 settings가 지정한 메모리 디렉토리는 더 이상 프롬프트에 로드·회상·색인·memory extraction에 사용되지 않습니다 — 이 규칙의 `autoMemoryDirectory`와 관련됩니다: 이 설정 하에서는 저장소가 지정한 메모리 디렉토리가 제외됩니다.
+-->
 
+<!-- DETAIL: v2.1.275+ CHANGELOG memory age note/resume malformed block
 > **v2.1.275+**: (275) CHANGELOG 원문: "Fixed a restored memory file's age note changing between requests after a compaction or resume, which caused prompt cache misses." 이 저장소는 auto-memory MEMORY.md를 매 세션 로드하므로, 275 이전 compaction/resume 이후의 cache miss 일부는 이 원인일 수 있습니다(R013 prompt_cache 원인 후보로만 취급 — 확정 아님). (275) CHANGELOG 원문: "Fixed sessions failing to resume or start when their saved transcript contains a malformed message content block" 및 "Fixed `--resume`, the resume picker preview, resumed background agents and the transcript view failing on a session whose saved history contains a malformed task-reminder or @-file attachment entry." 위 v2.1.251 트랜스크립트 무결성 노트의 연장이며, 275 이전 "resume 실패"는 세션 손실이 아니라 단일 malformed 엔트리 때문일 수 있었으므로 R020 트랜스크립트 계수는 그런 세션을 하한값으로 취급합니다.
+-->
 
 <!-- RETIRED (은퇴 릴리즈 v1.1.45, 보존 기준 v2.1.212 미만): > **v2.1.210+**: MEMORY.md 인덱스가 read limit을 초과하게 만드는 memory write는 이제 silent truncation 대신 명시적 오류를 반환합니다. write 실패는 여전히 non-blocking이지만, 오류 수신 시 log-warning으로 끝내지 말고 예산 초과 처리(Attention-Weight Tiering — Cold 항목 archive 이동)로 축소 후 재시도합니다 — 이전의 silent truncation을 가정하고 oversize write를 던지면 업데이트가 반영되지 않습니다. -->