볼트 최적화기 (한국어판)

⚠️ 이 블록은 영어 원본을 한국어 볼트용으로 감싸는 마스터 오버라이드입니다. 아래 본문·references의 어떤 영어 지시와 충돌하더라도 이 블록이 우선합니다. 프레임워크의 판단 로직·정규식·구조는 그대로 따르되, 아래 두 가지만 한국어 기준으로 바꿉니다: (1) 사용자에게 보이는 출력 언어, (2) 언어 종속적 수치·치환 규칙.

오버라이드 0 — 출력 언어: 무조건 한국어

• Step 0/1/1.5의 안내 문구, 발견 요약 블록, 분류 표
• 프레임워크 진행 라인(예: "F1 … → 22건 발견")
• 모든

  AskUserQuestion

  walk 질문과 선택지
• 각 finding의

  reasoning

  ·

  action

  ·

  excerpt

  설명(원문 인용 excerpt는 원본 유지, 그에 대한 설명은 한국어)
• HTML 리포트의 모든 라벨·헤더·설명(한국어 템플릿 사용 — 아래 오버라이드 4)
• 최종 요약 블록

reasoning

오버라이드 1 — 토큰 추정 공식 (가장 중요한 한국어 조정)

bytes/4

chars/4

bytes/4

chars/4

tokens ≈ bytes/4

한글_글자수 = 유니코드 Hangul(음절 AC00–D7A3, 자모 1100–11FF, 3130–318F) 개수
그외_글자수 = 공백 제외 나머지 글자수 (영문·숫자·기호·코드)

추정_토큰 ≈ (한글_글자수 × 1.5) + (그외_글자수 × 0.25)

• 계수

  1.5

  (한글)와

  0.25

  (그 외)는 근사치이며 토크나이저·내용 구성에 따라 변합니다. 안전을 위해 살짝 과대 추정하는 방향으로 잡았습니다(예산 초과를 놓치는 것보다 일찍 경고하는 게 낫다)
• 토큰 예산 수치 자체는 바꾸지 않습니다. 예산(F4 자동로드 ~3K, daily 2K, F5 파일당 권장 ~2.5K / 하드 25K)은 언어 중립적 목표입니다. 바뀌는 건 오직 "이 파일이 몇 토큰인가"를 세는 방법뿐입니다
• 결과: 영어 공식으로는 예산 안에 들어 보이던 한국어 파일이 실제로는 초과인 경우를 정확히 잡아냅니다. 리포트의 "절감 토큰" 수치도 한국어 기준으로 맞습니다

오버라이드 2 — 파일 크기 예산: 바이트가 아니라 토큰으로

• F5 파일당 권장 예산을 바이트가 아니라 토큰으로 판정합니다: 오버라이드 1 공식으로 추정한 토큰이 권장 ~2,500토큰 초과 → warn, 하드 25,000토큰(또는 100KB) 초과 → fail. 바이트(KB)는 참고용 보조 지표로만 리포트에 병기
• G7.4 README 밀도: "sparse"·"bloated" 판정도 바이트가 아니라 토큰/내용 충실도로 봅니다. 한글 README는 같은 정보량이라도 바이트가 크니 8KB 기준을 그대로 쓰면 멀쩡한 문서가 bloated로 잘못 잡힙니다. sparse는 "개요·상태·다음 단계 중 빠진 게 있는가", bloated는 "한 파일에 분리돼야 할 하위 주제가 여럿인가"로 판정(바이트는 참고만)

오버라이드 3 — em대시(G7.1) & 한국어 문체 위생(G7.5 신설)

• 두 절을 잇고 뒤 절이 앞을 부연 → 마침표로 문장 분리, 또는 "즉,"·"곧"·쉼표로 연결 (콜론

  :

  은 한국어 산문에서 어색하니 지양)
• 삽입구 설정 → 쉼표(

  , … ,

  ) 또는 괄호(

  ( )

  )
• 절 끝에서 마침표 역할 → 마침표(

  . 

  )로 문장 분리
• 숫자·날짜 범위의 엔대시(

  100–200

  ,

  2026–2027

  )는 유지(위반 아님)
• 인용문 안의 대시는 원문 보존

• 문장 끝 "~것입니다"·"~할 수 있습니다"의 기계적 반복(한 문단 3회 이상)
• 상투적 마무리어 뭉침: "종합적으로"·"결론적으로"·"요컨대"·"정리하자면"의 남발
• 접속어 스태킹: "또한"·"게다가"·"뿐만 아니라"의 연속 사용
• 강조어 인플레이션: "매우"·"굉장히"·"정말"·"너무"의 습관적 삽입
• 번역체 조사구 남발: "~에 대해"·"~을 통해"·"~에 있어서"·"~와 관련하여"
• 3개 병렬(rule of three)이 기계적으로 반복되는 문장

오버라이드 4 — HTML 리포트: 한국어 템플릿 사용

references/report-template.html

오버라이드 5 — 한국어 출력 문자열 (원본 영어 블록 대체)

• Step 0 시작 안내: "9개 프레임워크로 볼트를 감사합니다. 먼저 폴더 구조를 파악하고(Step 1.5 — 폴더 이름을 가정하지 않습니다), 이후 모든 수정안을 항목별로 함께 검토합니다. 각 단계는 작업(task)으로 표시됩니다."
• 볼트 아님 판정: "마크다운 볼트로 보이지 않습니다 — .md 파일이나 CLAUDE.md를 찾지 못했습니다. 볼트 루트로 이동한 뒤 다시 실행해 주세요."
• 프레임워크 진행 라인: "F1 Anthropic CLAUDE.md — CLAUDE.md 14개 읽고 후보 312건 판단 → 22건 발견 (fail 5 · warn 17)" 형식
• 최종 요약(Step 6.4 Part 3):

  ✅ 최적화 실행 완료 — 이번에 바뀐 내용입니다:
  리포트: {결정폴더}/{YYYY-MM-DD}-vault-audit.html
  JSON 원본: {결정폴더}/{YYYY-MM-DD}-vault-audit-findings.json
  점수(F1–G7): {전} → {후} ({부호}{델타}) — "{해석_전}" → "{해석_후}"
  파일 {N}개 감사 · 수정 {적용수}건 적용 · 기계적 실패 {실패수}건 (사유는 리포트 참고)
  em대시: {전} → {후} · 프론트매터 완결: {전}% → {후}% · 폴더 인덱스 커버리지: {전}% → {후}%
  절감 토큰: {절감}(에이전트 로드 {비율}% 감소) · 주 {세션}회 기준 연 ~{연간절감} 토큰 절약

  선택-walk 모드면 "계획 저장 {n}건 · 거절 {n}건" 줄을 덧붙입니다

오버라이드 6 — 점수 해석 표 (한국어)

Vault Optimizer (영어 원본 지시층 — 출력은 한국어)

아래 본문은 영어 원본 지시입니다. 로직·구조·정규식은 그대로 따르되, 사용자에게 보이는 모든 출력은 상단 오버라이드 0에 따라 한국어로 냅니다.

Operating philosophy — read carefully, this is what makes this skill different

1. Every finding ships a concrete fix. No flag-only. No "warn and forget." No manual-review pile. When the user runs apply-mode, every finding becomes either an applied edit, a saved migration step in a dated reorg plan, or (only if the user explicitly declines this finding in walk) a recorded decline. Nothing lingers as an open warning across runs.
2. Severity is informational, not gating.

   fail

   /

   warn

   /

   info

   describes how load-bearing the issue is; it does not gate whether a fix is offered. Every check produces fixes.
3. Walk per item, user picks the target. Bulk-apply is reserved for purely mechanical fixes (em dashes, duplicate H1). Anything semantic — wikilink repointing, merges, routing rewrites, Plot.md generation, reorganizations — is walk-only with the user confirming the destination/winner/wording per item.
4. Two modes for every fix: apply now (executes in this run) or save to plan (writes the change as a checklist step into

   Intelligence/decisions/{date}-reorg.md

   for staged execution). User picks per finding for high-blast-radius items. Smaller fixes default to apply-now.
5. Visible progress, never silent. Step 0.5 creates one TaskCreate entry per stage and per framework; tasks update

   in_progress

   →

   completed

   as the run unfolds. The user watches the audit walk through the vault rather than waiting for one big report at the end.
6. Read and reason, don't just match. Every framework's triggers surface candidates; every finding requires the agent to read context, judge alignment with the user's stated world, and produce reasoning specific to the case. No paraphrased rule restatements as "reasoning."
7. Discover structure, never assume folder names. Vaults vary. One user's curated layer is

   Context/

   ; another's is

   About/

   ,

   Me/

   , frontmatter on root, or scattered across topic folders. The optimizer runs Step 1.5 (role discovery) before any framework, and every framework references roles (context-equivalent, decisions-equivalent, daily-equivalent, folder-index convention…) discovered from content — never hardcoded names. If a role is missing, it surfaces as a finding with a proposed fix ("you have no decisions-equivalent folder; here's a recommendation"), not as a silent assumption. Static path references in pass files are always abstractions; the agent resolves them through the role registry at run time.

Frameworks

references/anthropic-claude-md.md

references/passes-anthropic-claude-md.md

CLAUDE.md

references/karpathy-llm-wiki.md

references/passes-karpathy-wiki.md

references/caveman-compression.md

references/passes-caveman.md

references/chroma-context-rot.md

references/passes-chroma-context-rot.md

.md

references/anthropic-managed-memory.md

references/passes-anthropic-memory.md

.md

references/progressive-disclosure.md

references/passes-progressive-disclosure.md

SKILL.md

references/passes-general-hygiene.md

.md

references/anthropic-dreams.md

references/passes-reflection.md

Context/

Projects/

Intelligence/decisions/

Resources/

Daily/

Intelligence/meetings/

references/anthropic-architecture.md

references/passes-architecture.md

Plot.md

Flow

1. Verify the cwd looks like a vault — light check (Step 0)
2. Create the visible task list — TaskCreate one task per stage + framework (Step 0.5)
3. Discover & classify every

   .md

   file — only technical skips (Step 1)
4. Iterate frameworks F1 → F9, applying each framework's lens with agent judgment; F8 = cross-vault synthesis, F9 = whole-vault structural reasoning + discoverability walk (Step 2)
5. Aggregate findings + write the architectural read paragraph (Steps 3 and 3.5)
6. Walk every finding through apply-now / save-to-plan — no skip option for fixes; every finding becomes an applied edit, a saved migration step, or an explicit per-item user decline (Step 4)
7. Apply approved fixes (Step 5)
8. Render HTML dashboard, save, open in browser, emit as artifact (Step 6)

Step 0 — Verify the cwd looks like a vault

test -f CLAUDE.md || test -f claude.md
[ "$(find . -maxdepth 4 -name 'CLAUDE.md' | head -1)" ]
[ "$(find . -maxdepth 1 -name '*.md' | wc -l)" -gt 0 ]

마크다운 볼트로 보이지 않습니다 —

.md

파일이나

CLAUDE.md

를 찾지 못했습니다. 볼트 루트로

cd

한 뒤 다시 실행해 주세요.

9개 프레임워크로 볼트를 감사합니다. 먼저 폴더 구조를 파악하고(Step 1.5 — 폴더 이름을 가정하지 않습니다), 이후 모든 수정안을 항목별로 함께 검토합니다. 각 단계는 작업(task)으로 표시됩니다.

Step 0.5 — Create the visible task list (TaskCreate)

[ ] .md 파일 발견 및 분류 (Step 1)
[ ] 역할 발견 — 의미 기반 폴더/파일 분류, 이름 하드코딩 없음 (Step 1.5)
[ ] F1 Anthropic CLAUDE.md — CLAUDE.md 읽고 후보 판단
[ ] F2 Karpathy 위키 — 위키링크·고아 노트·스키마
[ ] F3 Caveman — 지시층 파일 압축
[ ] F4 Chroma Context Rot — 길이·방해요소·위치
[ ] F5 Anthropic Memory — 파일 크기·이름·인덱스
[ ] F6 Progressive Disclosure — SKILL.md 계층화
[ ] G7 위생 — em대시·프론트매터·H1·한국어 문체
[ ] F8 Reflection — 파일 간 종합 클러스터링·판단
[ ] F9 아키텍처 — 라우팅 진위·Plot.md 존재·탐색성 워크
[ ] 발견 집계 + 아키텍처 읽기 (Step 3 / 3.5)
[ ] 모든 발견을 적용/계획저장으로 워크 (Step 4)
[ ] 승인된 수정 적용 (Step 5)
[ ] 대시보드 렌더링 + 열기 (Step 6)

in_progress

completed

Step 1 — Discover & classify every

.md

file

1.1 — Universal glob (every file audited)

find . -name '*.md' \
  -not -path '*/.git/*' \
  -not -path '*/.obsidian/*' \
  -not -path '*/.trash/*' \
  -not -path '*/.claude/worktrees/*' \
  -not -path '*/node_modules/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*'

.md

1.2 — Classify each file by role (first match wins) — hints only

\d{4}-\d{2}-\d{2}\.md

daily

root-claude

./CLAUDE.md

./claude.md

folder-claude

CLAUDE.md

claude.md

claude-rules

.claude/rules/

skill

SKILL.md

index

index.md

readme

README.md

daily

\d{4}-\d{2}-\d{2}\.md

Daily/

meeting

*meetings*/

\d{4}-\d{2}-\d{2} - .+\.md

Daily/

transcript

*transcripts*/

decision

*decisions*/

template

*templates*/

-template.md

context

Context/

note

{
  "root_claude": "./CLAUDE.md",
  "folder_claudes": [...],
  "claude_rules": [...],
  "skills": [...],
  "indexes": [...],
  "readmes": [...],
  "dailies": [...],
  "meetings": [...],
  "transcripts": [...],
  "decisions": [...],
  "templates": [...],
  "context_files": [...],
  "notes": [...],
  "by_folder": {...},
  "stats": {"total_files": N, "total_bytes": B, "folders": F}
}

1.3 — Build supporting indexes (used by F2/F4)

vault_filename_index

.md

inbound_link_index

routing_table

top_level_entries

find . -maxdepth 1

headers_index

protected_zones_map

1.4 — Show classification summary in chat (one block, before any framework runs)

## 📋 Discovery — {N} markdown files across {F} folders, {B-formatted} total

| Role | Count |
|---|---:|
| Root CLAUDE.md | 1 |
| Folder CLAUDE.mds | {n} |
| Skills (SKILL.md) | {n} |
| .claude/rules | {n} |
| Indexes / READMEs | {n} |
| Context files | {n} |
| Notes | {n} |
| Dailies | {n} |
| Meetings | {n} |
| Transcripts | {n} |
| Decisions | {n} |
| Templates | {n} |

**Framework targets (every file in scope is audited):**
- F1 Anthropic CLAUDE.md → {n} CLAUDE.md files
- F2 Karpathy Wiki → {n} content notes (notes + context + decision + meeting + index + readme) + 1 schema doc check
- F3 Caveman → {n} instruction-layer files (CLAUDE.md + SKILL.md + .claude/rules + skill references)
- F4 Chroma Context Rot → {N} files (every `.md`)
- F5 Anthropic Memory → {N} files (every `.md`)
- F6 Progressive Disclosure → {n} skills
- G7 General Hygiene → {N} files
- F8 Reflection → {n} files in discovered curated-layer roles + {n} files in discovered session-layer roles ({window} window) for cross-vault synthesis
- F9 Architecture → routing table ({n} entries), {n} folders for index presence + freshness against the discovered convention, full navigation graph for discoverability, vault-specific orientation built from the discovered identity-layer

Running role discovery (Step 1.5) now…

Step 1.5 — Role discovery (semantic, not name-based)

context

projects

decisions

daily

meetings

transcripts

resources

skills

archive

identity

folder_index_convention

1.5.1 — How discovery works

1. Read folder names + Plot/README/index/CLAUDE files at the top level, then top-2-deep. Build a candidate list: which folders look like they could play this role based on name + their own description?
2. Read 3–5 sample files per candidate folder. Does the content match the role's purpose?
3. Score and pick. Highest-confidence candidate wins. If no candidate clears medium confidence → role is

   missing

   .

Context/

About/

Me/

Personal/

Identity/

identity

1.5.2 — Standard roles (patterns the agent recognizes)

identity

context

projects

decisions

daily

YYYY-MM-DD\.md

meetings

transcripts

resources

skills

SKILL.md

archive

folder_index_convention

Plot.md

README.md

index.md

_index.md

CLAUDE.md

1.5.3 — Custom roles (every other folder)

1. Read the folder's index file (under the discovered convention) if present.
2. Sample 3–5 files in the folder. Read first 1500 chars + headers.
3. Read the parent folder's index (if any) to see how this folder is described upstream.
4. Assign a custom role:

   • name

     — a slug derived from the folder name plus content (e.g.,

     Building/

     with prototype-build content → role name

     building

     ;

     Garden/

     with idea-incubation content →

     garden

     ).

   • layer

     — one of

     curated

     (canonical, durable),

     session

     (ephemeral, time-stamped),

     archive

     (deactivated),

     meta

     (tooling, system files),

     unknown

     (agent could not confidently classify).

   • purpose

     — 1-line description of what the folder holds.

   • is_standard: false

     .

   • confidence: high | medium | low

     .

building

layer: curated

context

1.5.4 — Output: the role registry

.claude/vault-roles.json

{
  "vault_root": "./",
  "discovered_at": "2026-05-08T14:23:00Z",
  "folder_index_convention": {
    "name": "README.md",
    "confidence": "high",
    "evidence": "23 of 31 non-trivial folders have README.md",
    "coverage": 0.74
  },
  "roles": [
    {"name": "identity",  "path": "./About/me.md", "kind": "file",   "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Operator bio + voice"},
    {"name": "context",   "path": "./Knowledge/",  "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Org/strategy/brand canonical knowledge"},
    {"name": "projects",  "path": "./Work/",       "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Active and recent work units"},
    {"name": "daily",     "path": "./Journal/",    "kind": "folder", "layer": "session", "is_standard": true,  "confidence": "medium", "purpose": "Per-day journal entries"},
    {"name": "resources", "path": "./Library/",    "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Prompts, frameworks, templates"},
    {"name": "archive",   "path": "./_archive/",   "kind": "folder", "layer": "archive", "is_standard": true,  "confidence": "high",   "purpose": "Deactivated content"},
    {"name": "building",  "path": "./Building/",   "kind": "folder", "layer": "curated", "is_standard": false, "confidence": "high",   "purpose": "Active prototype builds and experiments"},
    {"name": "garden",    "path": "./Garden/",     "kind": "folder", "layer": "curated", "is_standard": false, "confidence": "medium", "purpose": "Long-form essays in slow incubation"},
    {"name": "inbox",     "path": "./Inbox/",      "kind": "folder", "layer": "session", "is_standard": false, "confidence": "high",   "purpose": "Unprocessed capture; aged out into Garden or Resources"}
  ],
  "missing_standard_roles": ["decisions", "meetings", "transcripts"],
  "low_confidence_roles": ["garden"],
  "unconfirmed_custom_roles": []
}

1.5.5 — Show the discovery summary in chat (one block)

## 🔍 Your vault structure — {N_folders} folders classified

| Folder | Role | Layer | Purpose | Confidence |
|---|---|---|---|---|
| ./About/me.md | identity | curated | Operator bio + voice | high |
| ./Knowledge/ | context | curated | Org/strategy/brand | high |
| ./Work/ | projects | curated | Active and recent work | high |
| ./Journal/ | daily | session | Per-day journal | medium |
| ./Library/ | resources | curated | Prompts, frameworks, templates | high |
| ./_archive/ | archive | archive | Deactivated content | high |
| ./Building/ | building (custom) | curated | Active prototype builds | high |
| ./Garden/ | garden (custom) | curated | Long-form essays in slow incubation | medium |
| ./Inbox/ | inbox (custom) | session | Unprocessed capture | high |

**Folder-index convention I detected:** README.md (74% coverage)

I'll audit this structure as it stands. F9.0 may suggest specific structural improvements where I see concrete evidence they'd help your vault (not just because BenAI uses them) — you'll review each suggestion in walk. Confirmed assignments persist to `.claude/vault-roles.json`.

Running F1 now…

1.5.6 — Hard rules for downstream frameworks

• Frameworks reference roles by layer, not by name. F8's curated layer = every role with

  layer == 'curated'

  (standard or custom). F8's session layer = every role with

  layer == 'session'

  . F9 walks every folder regardless of role membership.
• Custom roles participate in every framework that operates on their layer. If

  building

  is

  layer: curated

  , F8 looks at

  Building/

  for merge candidates, contradictions, themes, and promotions exactly like

  Context/

  .
• Missing roles never block a framework. If

  decisions

  is missing, F8 proceeds without it; F9.0 produces a finding suggesting the user create one (or assign the role to an existing custom folder).
• The folder-index convention is what F9.2 enforces — not Plot.md by default. If the user's vault uses README.md, F9.2 generates/refreshes README.md. If no convention exists, F9.0 proposes adopting one.
• Persisted registry is read at the start of Step 1.5. If

  .claude/vault-roles.json

  exists from a prior run, the agent loads it as the baseline and only re-classifies new folders or folders the user flagged for re-review. Confirmed assignments don't re-prompt every run.
• No framework hardcodes folder paths or file names. Examples in pass files are illustrative; runtime resolves through the registry.

Step 2 — Iterate frameworks F1 → F9 with judgment

reasoning

\bjust\b

IMPORTANT:

voice.md

brand.md

2.1 — For each framework F1, F2, F3, F4, F5, F6, G7, F8, F9 (in this order)

in_progress

completed

1. Read the pass-implementation file for that framework (e.g.,

   references/passes-anthropic-claude-md.md

   for F1). Cache it for the duration of the framework run.
2. Determine the file scope from the table at the top of this SKILL.md (e.g., F1 = every CLAUDE.md; F6 = every SKILL.md; F4/F5/G7 = every

   .md

   ).
3. For each check in the pass file:
   • Apply the trigger heuristic (regex / metric / structural pattern) to surface candidates fast. Some checks have no trigger — the file itself is the candidate.
   • For each candidate, read the surrounding 5–15 lines with the

     Read

     tool, then apply the agent-judgment criteria the pass file lists. Read other files (linked targets, sibling clusters, the file's index) when judgment requires it.
   • Decide: does this case actually violate the framework rule in this file's specific context? Or is it a false positive (the pass file lists common ones to skip)?
   • If real → produce a finding. If not → drop it; the trigger was a candidate, not a verdict.
   • Every finding includes a

     reasoning

     field (1–2 sentences specific to this case, not a generic restatement of the rule).
4. Run the framework's vault-wide checks (using indexes from Step 1.3): orphan detection, dead wikilinks, distractor pairs, schema compliance, etc. — see each pass file's "vault-wide" sections.
5. Emit one progress line when the framework completes:

   F1 Anthropic CLAUDE.md — read 14 CLAUDE.md files, judged 312 candidates → 22 findings (5 fail · 17 warn)

   The

   judged

   count vs

   findings

   count is a sanity check: if they're roughly equal, the run was lazy (regex candidates became findings without judgment); if

   judged

   ≫

   findings

   , judgment is filtering false positives — that's the intended behavior.

2.2 — Reasoning sanity gate (per framework)

reasoning

2.3 — Finding schema (every framework, every path)

{
  "framework": "F1",
  "check_id": "F1.2",
  "check_name": "Specificity heuristic",
  "path": "./Projects/foo/CLAUDE.md",
  "line": 42,
  "severity": "warn",
  "excerpt": "Be careful with auth",
  "reasoning": "This rule sits in the top half of a CLAUDE.md that's otherwise a routing index — there's no specific auth boundary, file path, or function named anywhere else. As a primary rule it falls into the 35%-compliance bucket; either anchor it to a specific path/function or remove it.",
  "action": "Either delete or rewrite as 'All /api/admin/* routes must call requireAdmin() from src/auth/middleware.ts'.",
  "fixable": false,
  "fixed": false,
  "citation": "anthropic-claude-md.md → Specificity beats vagueness"
}

reasoning

fixable: true

fixable: false

fix_status

• applied

  → fix executed this run (green FIXED pill)

• saved_to_plan

  → fix written into

  Intelligence/decisions/{date}-reorg.md

  for staged execution (blue SAVED pill)

• declined

  → user explicitly chose not to fix this item in walk (grey DECLINED pill)

• failed

  → fix attempted but failed safety check (red FAILED pill, with

  failure_reason

  )

Step 3 — Aggregate findings + compute score

Score formula (framework-weighted)

For each framework F1..G7:
  deduction = (fail_count × 5) + (warn_count × 1)
  capped_deduction = min(deduction, 25)
score = max(0, 100 - sum(capped_deduction for F1..G7))

✅ 9개 프레임워크 모두 적용 완료.

| 프레임워크 | 파일 | 체크 | 발견 | Fail | Warn | 제안된 수정 |
|---|---:|---:|---:|---:|---:|---:|
| F1 Anthropic CLAUDE.md | … | … | … | … | … | … |
| F2 Karpathy Wiki | … | … | … | … | … | … |
| F3 Caveman | … | … | … | … | … | … |
| F4 Chroma Context Rot | … | … | … | … | … | … |
| F5 Anthropic Memory | … | … | … | … | … | … |
| F6 Progressive Disclosure | … | … | … | … | … | … |
| G7 Hygiene | … | … | … | … | … | … |
| F8 Reflection | … | … | … | … | … | … |
| F9 Architecture | … | … | … | … | … | … |
| **TOTAL** | … | … | … | … | … | … |

Score: {score_before}/100 (F8 + F9 not scored). Walking the architectural read next…

Step 3.5 — Architectural read (the synthesis paragraph)

Context/

### Architectural read

{1–3 short paragraphs. Each paragraph: one structural observation, why it matters for *this* user's world (cite Context/), the F9 finding(s) that surfaced it, the proposed direction.}

Step 4 — Walk every finding through apply-now / save-to-plan

applied

saved_to_plan

declined

failed

4.1 — One opening AskUserQuestion (the apply gate)

AskUserQuestion

"Audit complete: {N_total} findings across 9 frameworks ({fail} fail · {warn} warn · {info} info). Every finding has a proposed fix. Pick mode:"

1. Bulk-apply (apply everything, no escapes) — every finding gets applied. Walk prompts only fire where the agent genuinely needs the user to pick a target/wording (e.g., "merge target: A or B?"). All else applies without per-item confirmation. The only valid non-applied state is

   failed

   (mechanical: OS lock, file conflict, dependency missing). No

   saved_to_plan

   , no

   declined

   . Use this when you've said "apply everything."
2. Selective walk — fire a per-finding prompt for every fix; user picks apply / save-to-plan / decline per item. Use when reviewing carefully or for a first run on a new vault.
3. Save everything to plan — write all proposed fixes as checklist steps into the discovered decisions-equivalent folder; no edits applied this run.
4. Cancel — abort before any fixes.

4.1.1 — Bulk-apply mode rules (Option 1)

• No

  saved_to_plan

  outcomes. That state is removed from the available

  fix_status

  set.
• No

  declined

  outcomes. Same.
• The agent does not unilaterally decide a finding is "test fixture," "the user probably didn't want this," "too complex to apply mechanically," or "judgment-required-per-section" and route it to anything other than applied/failed. If applying a fix mechanically would damage content, the agent attempts the safest mechanical version (e.g., split a 222KB file at H2 boundaries with a

  <!-- automated split, review headings -->

  marker; mark the split as

  applied

  with

  applied_with_caveat: true

  ).
• Walk prompts fire only when the agent genuinely cannot pick a target without the user. Example: F8.2 merge with three plausible canonical targets — fire the prompt. Example: G7.1 em-dash substitution — apply without prompting; the agent's per-occurrence reasoning already chose the substitution.
• Mechanical failures are still recorded as

  failed

  with

  failure_reason

  (OS-locked file, missing parent directory, file conflict, framework-safety check rolled back the fix). Failed fixes are reported in the dashboard with their reason — they're not silently skipped.
• The agent must not pre-classify findings as "skip in bulk-apply mode." Every finding is in scope. If applying a daystar/ test-fixture fix damages a deliberate test pattern, the user can revert that file specifically — but the agent doesn't make that call.

4.2 — Per-finding walk loop

1. Show the finding compactly in chat: path, severity, 1-line excerpt, the proposed fix's

   proposed_edit

   or migration step.
2. Fire AskUserQuestion with the per-finding-type sub-prompt:

1. Update the finding's

   fix_status

   (

   applied

   /

   saved_to_plan

   /

   declined

   ) and any

   per_item_target

   chosen by the user.
2. TaskUpdate the current framework's task with a

   {i}/{N}

   progress note every 10 findings.

4.3 — Save-to-plan file format

1. If

   roles.decisions.path

   is set → save under

   {decisions.path}/{YYYY-MM-DD}-reorg.md

   .
2. Else if any folder matches

   *decisions*/

   ,

   *logs*/

   ,

   *records*/

   (case-insensitive) → use that.
3. Else create

   audits/

   at vault root and save there. Note the missing decisions role to F9.0 — the user gets a fix proposal to formalize a decisions-equivalent folder.

---
status: pending
type: reorg-plan
tags: [optimizer, plan]
date: 2026-05-08
source: os-optimizer run 2026-05-08T14:23:00Z
---

# Vault reorg plan — 2026-05-08

Generated by os-optimizer. Each item is a fix proposal saved for staged execution. Walk them when ready.

## F9.6 Reorg proposals

- [ ] **Merge `Notes/` into `Resources/notes/`** — F9.5 finding cluster: both folders hold scratch with 38% file-name overlap. Migration:
  - Move 12 files from `Notes/` to `Resources/notes/`.
  - Redirect 4 inbound wikilinks.
  - Update root CLAUDE.md routing entry to remove `Notes/`.
  - Delete empty `Notes/` directory.
  - Reasoning: `Resources/notes/` Plot.md states it holds reference notes; `Notes/` Plot.md states the same. Per `Context/me.md`, the user's stated convention is one resource library — keeping two is structural drift.

## F8.2 Merge candidates

- [ ] **Merge `Notes/2026-q1-strategy.md` and `Projects/positioning/research/strategy-thoughts.md` into `Context/strategy.md`** — F8.2 finding. Steps: …

(continues per saved finding)

4.4 — Failure to walk

completed

Step 5 — Apply approved fixes (set

fix_status

per finding)

fix_status

applied

saved_to_plan

declined

failed

fix_status

Intelligence/decisions/{date}-reorg.md

5.0 — Capture BEFORE metrics (mandatory, before any fix lands)

before_metrics

• file_count

• total_chars

  (sum of body bytes, post-frontmatter)

• total_tokens_est

  (한국어 공식:

  (한글글자수 × 1.5) + (그외글자수 × 0.25)

  — 오버라이드 1.

  chars/4

  아님)

• em_dash_count

  (G7.1 trigger output)

• frontmatter_complete_pct

  (files with

  status:

  + ≥2

  tags:

  / total)

• wikilink_orphan_count

  (no inbound wikilink)

• index_coverage_pct

  (folders with the discovered folder-index file / non-trivial folder count)

• findings_open

  (count of findings touching files in this role)

• findings_count

• fail_count

  ,

  warn_count

  ,

  info_count

• applied_count

  (starts at 0)

• failed_count

  (starts at 0)

• score_contribution

  (per the Step 3 formula; F8/F9 always 0)

5.1 — Em dashes (G7.1)

• For each

  applied

  finding: replace

  —

  →

  . 

  ,

  –

  →

  , 

  in stripped body only.
• Re-strip protected zones after; if any code/URL/wikilink was touched → revert that file's change AND set

  fix_status: failed

  with

  failure_reason

  .
• Use

  Edit

  with

  replace_all: true

  per file.
• Set

  fix_status: applied

  on every G7.1 finding whose file was successfully fixed.

5.2 — Duplicate H1 (G7.3 / F1.10)

• Remove the H1 line and any blank line immediately following.
• Use

  Edit

  . Set

  fix_status: applied

  .

5.3 — Wikilink fixes (F2.2)

• For each finding the user approved (bulk = top-1 suggestion, walk = chosen target): replace

  [[Old Target]]

  with the picked replacement.
• Preserve surrounding text byte-for-byte.
• Mark

  fixed: true

  per finding fixed;

  fixed: false

  for any skipped or low-confidence ones the user said no to.

5.4 — Skill-vault rewrites (F6.11)

• Update SKILL.md to read the vault

  Context/

  path instead of the duplicate ref.
• Grep the rest of the skill folder for the duplicate ref filename.
• If still referenced → surface conflict, skip deletion, set

  fix_status: failed

  .
• Otherwise →

  rm

  the duplicate, set

  fix_status: applied

  .

5.5 — Caveman substitutions (F3.1, F3.2, F3.3, F3.4) — only if user opted in per file

• Apply substitution table from

  references/passes-caveman.md

  to the stripped body.
• Re-strip protected zones; if any was modified → abort the fix on that file, report, set

  fix_status: failed

  for that file's findings.
• Mark

  fixed: true

  on every F3.x finding for files the agent successfully substituted.

5.6 — Reflection fixes (F8.1, F8.3, F8.2, F8.4, F8.5) — walk-only, per-item user-confirmed targets

1. F8.1 contradictions — for each approved finding: rewrite the loser file. Either replace contradicted line with

   See [[Winner]] for current state.

   (defer mode) or delete the line entirely (drop mode); the user picks per item in Step 4. Use

   Edit

   . Set

   fix_status: applied

   .
2. F8.3 stale entries — for each approved finding: rewrite the curated entry with the new state. Append

   ## History

   section with the prior wording if it has decision context (per pass file rule). Add wikilink to superseding source. Set

   fix_status: applied

   .
3. F8.2 merge candidates — for each approved cluster:
   • Concatenate unique sections from sources into the canonical target (skip duplicate paragraphs).
   • Re-check size against F5 budget. If merged file > 10KB → abort the merge, set

     fix_status: failed

     , surface as flag-only with the abort reason in

     reasoning_post

     .
   • Grep the vault for

     [[SourceName]]

     and

     [[SourceName|alias]]

     patterns; replace each with

     [[CanonicalName|alias]]

     (or

     [[CanonicalName]]

     ).
   • Verify zero new dead wikilinks (run F2.2 trigger on every file touched). If any new dead link surfaced → roll back this finding's fix, set

     fix_status: failed

     .
   • Move source files to

     Intelligence/archive/{YYYY-MM-DD}-merged/

     . Use

     Bash mv

     .
   • Set

     fix_status: applied

     .
4. F8.4 emergent themes — for each approved finding:
   • Create the new file at the user-chosen path (default

     Context/{theme-slug}.md

     or

     Resources/{theme-slug}-MOC.md

     ).
   • Frontmatter must include

     status:

     ,

     tags:

     ,

     type:

     ,

     date:

     (G7.2 compliance) and contain no em dashes (G7.1).
   • Body: 1-line definition, 3–5 key points, wikilinks back to every source note in the cluster.
   • Set

     fix_status: applied

     .
5. F8.5 promotions — for each approved finding:
   • Append the durable content to the chosen destination (

     Context/

     ,

     Resources/

     , or

     Intelligence/decisions/

     ).
   • In the source file, replace the original lines with

     See [[Target#section]]

     .
   • Set

     fix_status: applied

     .

• Re-strip protected zones on every file written. If any code/URL/wikilink/path/frontmatter was modified outside the intended edit → roll back, set

  fix_status: failed

  .
• If the touched file targets a CLAUDE.md or claude.md → abort (this should have been caught in Step 4 as flag-only, but defense in depth).
• If the touched file's size now exceeds F5's 10KB recommended budget → record the violation in

  reasoning_post

  ; the next audit run will surface it as F5 flag-only (don't roll back, but log).

5.7 — Architecture fixes (F9.1, F9.2, F9.3, F9.4, F9.5, F9.6, F9.7) — walk-only, per-item user-confirmed targets

1. F9.1 routing rewrites — for each

   applied

   finding:

   Edit

   the root CLAUDE.md routing table with the user-confirmed line(s). Per-item only; no batch rewrites. This is the single legitimate path for editing a CLAUDE.md (per-item user approval).
2. F9.2 Plot.md generation / regeneration — for each

   applied

   finding:
   • If missing:

     Write

     the agent-drafted Plot.md (user already confirmed Purpose + child descriptions in walk).
   • If stale:

     Edit

     to update the Children list; preserve any user edits to Purpose if not deprecated.
   • Verify size ≤ 8KB; verify G7.1 (no em dashes) and G7.2 (frontmatter complete).
3. F9.3 discoverability fixes — for each

   applied

   finding, apply the user-chosen repair:
   • "Add to Plot.md" →

     Edit

     the parent Plot.md.
   • "Add routing entry" →

     Edit

     root CLAUDE.md routing.
   • "Move file" →

     Bash mv

     ; redirect inbound wikilinks (same as F8.2 mechanic).
   • "Archive" →

     Bash mv

     to

     Intelligence/archive/

     .
4. F9.4 misplaced files —

   Bash mv

   to user-chosen folder. Update source folder's Plot.md (remove child) and target folder's Plot.md (add child). Redirect inbound wikilinks.
5. F9.5 folder duplication — for "merge into" findings: walk through file moves one at a time (each is its own

   applied

   micro-step). For "clarify Plot.md purposes" findings:

   Edit

   both Plot.mds.
6. F9.6 reorg proposals — only here if the user picked "apply now"; save-to-plan ones are already in the dated reorg file. For apply-now: walk each migration step in the proposal as its own micro-finding (move X, rename Y, update routing entry Z), each confirmed individually before execution.
7. F9.7 orientation gap —

   Edit

   root CLAUDE.md with the agent-drafted section the user confirmed. Per-item only.

• Re-run F2.2 trigger on every file touched. If new dead wikilinks appeared → roll back that fix, set

  fix_status: failed

  .
• Re-check root CLAUDE.md size against F1.1 budget after F9.1 / F9.7 edits. Over budget → record in

  failure_reason

  ; the next audit run will flag F1.1.
• Plot.md writes must pass G7.1 + G7.2 + F5 (≤ 8KB) by construction; if any check fails → roll back,

  fix_status: failed

  .

5.8 — Generic per-item fix runner (F1.x, F4.x, F5.x — previously flag-only)

1. Read the file.
2. Apply the agent-drafted

   proposed_edit

   from the finding (the user already confirmed or edited it in Step 4.2).
3. Re-strip protected zones; if any code/URL/path/frontmatter outside the intended edit was modified → roll back,

   fix_status: failed

   .
4. If the file is a CLAUDE.md → only proceed if

   applied

   came through walk-with-explicit-confirmation (Step 4.2). Never bulk-apply CLAUDE.md edits via this runner.
5. Set

   fix_status: applied

   on success.

• F1.2 vague rule rewrite or deletion
• F1.5 platitude deletion
• F1.7 reorder for position effect
• F4.3 critical-info reorder
• F4.4 lead-in preamble removal
• F5.1 file split (split file at agent-suggested headers; user confirmed split-points in walk)
• F5.3 filename rename via

  Bash mv

  + inbound wikilink redirect

5.9 — Capture AFTER metrics (mandatory, after every fix)

• Per-role metrics (re-run the same probes from 5.0 — files may have been split, em dashes stripped, frontmatter added).
• Per-framework metrics (recount findings against the current vault state — many findings should now resolve to zero because their underlying issue was fixed).
• Recompute the score using the formula in Step 3, against the re-measured findings count. This is

  {{SCORE_AFTER}}

  . Do not reuse the BEFORE score.
• Compute deltas:

  tokens_saved_per_role

  ,

  em_dashes_removed

  ,

  frontmatter_pct_delta

  ,

  findings_resolved_per_framework

  .

5.10 — Verify fix-status totals add up

• total_applied

  = findings with

  fix_status: applied

  .

• total_saved_to_plan

  = findings with

  fix_status: saved_to_plan

  .

• total_declined

  = findings with

  fix_status: declined

  .

• total_failed

  = findings with

  fix_status: failed

  .

total_findings

null

fix_status

fix_status

Failure handling

Always preserve

• Files in technical skip list (

  .git

  ,

  .obsidian

  ,

  .trash

  ,

  node_modules

  ,

  dist

  ,

  build

  ).
• Code fences, inline code, URLs, file paths, frontmatter keys, wikilinks, table delimiters, headings, dates, version numbers.

Step 6 — Render, save, open, and surface the HTML

6.1 — Compute per-framework metrics

{{F1_FILES}}

{{F1_CHECKS}}

{{F1_FINDINGS_BEFORE}}

{{F1_FINDINGS_AFTER}}

{{F1_FAIL_BEFORE}}

{{F1_FAIL_AFTER}}

{{F1_WARN_BEFORE}}

{{F1_WARN_AFTER}}

{{F1_INFO_BEFORE}}

{{F1_INFO_AFTER}}

{{F1_APPLIED}}

{{F1_FAILED}}

{{F1_DETAILS}}

{{ARCHITECTURAL_READ}}

{{F8_INSIGHTS_SURFACED}}

{{F8_INSIGHTS_APPLIED}}

{{F9_PROPOSALS}}

{{F9_APPLIED}}

{{F9_FAILED}}

{{ROLE_METRICS_TABLE}}

{{FRAMEWORK_METRICS_TABLE}}

{{REORG_PLAN_PATH}}

{{TOTAL_FIXABLE}}

fixable: true

{{TOTAL_FIXED}}

fixed: true

{{TOTAL_FIXABLE_NOT_FIXED}}

fixable: true && fixed: false

{{TOTAL_BEFORE}}

{{TOTAL_AFTER}}

{{TOTAL_SAVED}}

{{TOTAL_PCT}}

{{SCORE_BEFORE}}

{{SCORE_AFTER}}

{{SCORE_DELTA}}

{{SCORE_DELTA_SIGN}}

{{SESSION_BEFORE}}

{{SESSION_AFTER}}

{{SESSION_PCT}}

{{ANNUAL_SAVINGS}}

{{TOTAL_SAVED}} × SESSIONS_PER_WEEK × WEEKS_PER_YEAR

{{SESSIONS_PER_WEEK}}

{{WEEKS_PER_YEAR}}

{{FILES_SCANNED}}

{{FOLDERS_COVERED}}

{{ORG_NAME}}

Context/business.md

Context/organization.md

name:

{{DATE}}

{{TIMESTAMP}}

{{Fx_DETAILS}}

6.1.5 — Per-role and per-framework before/after tables

{{ROLE_METRICS_TABLE}}

{{FRAMEWORK_METRICS_TABLE}}

점수(F1–G7): 46 → 97 (+51) · "볼트 부패" → "잘 다듬어짐"

6.2 — Build the HTML

references/report-template.html

references/report-row-template.html

references/report-section-template.html

references/report-finding-template.html

1. Read all four templates.
2. For each framework F1..F9:
   • Render one row from

     report-row-template.html

     with the framework's metrics → append to

     {{ROWS}}

     accumulator.
   • For each finding (cap at top-25 per framework, ranked: fixed first, then fail before warn, then by check ID): render one card from

     report-finding-template.html

     → append to that section's

     {{FINDINGS_HTML}}

     . HTML-escape

     EXCERPT

     ,

     REASONING

     , and

     ACTION

     (

     <

     ,

     >

     ,

     &

     ,

     "

     ). The

     REASONING

     field is mandatory — if the finding has no reasoning text, the skill is bugged; fail loudly.
   • Compute

     {{STATUS_PILL}}

     per finding from

     fix_status

     :

     • applied

       →

       <span class="pill fixed">이번 실행 적용</span>

     • saved_to_plan

       →

       <span class="pill saved">계획 저장</span>

       (links to

       {{REORG_PLAN_PATH}}

       )

     • declined

       →

       <span class="pill declined">거절</span>

     • failed

       →

       <span class="pill failed">실패</span>

       (with

       failure_reason

       shown inline)
   • If 0 findings: leave

     {{FINDINGS_HTML}}

     empty and substitute

     {{CLEAN_STATE}}

     with

     <div class="clean">✅ 모든 체크 통과. 이 프레임워크에서 발견된 문제 없음.</div>

     .
   • If total findings > 25: substitute

     {{MORE_NOTE}}

     with

     <p class="more">…외 {N}건이 {YYYY-MM-DD}-vault-audit-findings.json에 기록됨.</p>

     . Otherwise leave empty.
   • Render the section from

     report-section-template.html

     → append to

     {{DETAILS}}

     accumulator.
3. Substitute

   {{ROWS}}

   and

   {{DETAILS}}

   in the main template.
4. Substitute every other

   {{PLACEHOLDER}}

   (header stats, score, session impact, etc.).
5. Sanity pass: scan the rendered HTML for any leftover

   {{...}}

   or

   {{ }}

   . If any remain → fail loudly, never save a half-rendered file.

{{FRAMEWORK_WHY}}

• F1: "Anthropic 가이드: CLAUDE.md는 pruning 테스트를 통과하는, 가장 작고 구체적인 지시 집합으로 유지한다. 구체적 규칙은 약 89% 준수율, 모호한 규칙은 약 35%에 그친다."
• F2: "Karpathy의 LLM 위키: 지식은 한 번 컴파일해 최신 상태로 유지한다. Lint가 끊긴 링크·고아 노트·모순·누락된 상호참조·소화되지 않은 원본을 잡아낸다."
• F3: "Caveman 압축: 모든 토큰이 주의력을 두고 경쟁한다. 에이전트가 읽는 지시층에서 군더더기·헤징·인사치레·장황한 접속어를 걷어낸다."
• F4: "Chroma context rot: 모든 모델은 길이가 늘수록 성능이 저하되고, 방해 요소가 해를 끼치며, 위치가 중요하다. 핵심 규칙을 앞에 두고 자동 로드 예산을 빡빡하게 유지한다."
• F5: "Anthropic Memory: 파일당 ≤100KB / ~25K 토큰(권장 ~2,500토큰, 한국어는 토큰 기준). 초점 잡힌 여러 파일이 하나의 거대 파일보다 낫다. 에이전트는 이름으로 탐색한다."
• F6: "Progressive Disclosure: 컨텍스트 창은 공공재다. 스킬 메타데이터는 항상, 본문은 관련 시, references는 필요 시 로드한다. references는 한 홉 깊이로 유지한다."
• G7: "프로젝트 규칙 + 현장 노트: em대시 규율, 프론트매터 준수, 파일명과 중복되는 H1 금지, README 위생. 한국어판은 한국어 문장부호 치환과 번역체·AI 문체 냄새(G7.5)까지 점검한다."
• F8: "Reflection(Anthropic Dreams 착안): 파일별 lint로는 모순·중복·오래된 가정·떠오르는 주제를 볼 수 없다. 큐레이션 레이어와 최근 세션을 함께 읽어 이를 드러내고, 사용자가 항목별로 승인하는 구체적 수정안을 제안한다."
• F9: "아키텍처 & 탐색성: 동료 클로드가 실제로 걷는 경로(루트 CLAUDE.md → 라우팅 → 폴더 Plot.md → 파일)를 따라간다. 라우팅 항목이 폴더 현실과 맞는지, 모든 폴더에 최신 Plot.md가 있는지, 모든 파일이 3홉 이내로 도달 가능한지, CLAUDE.md가 이 사용자의 세계를 실제로 안내하는지 검증한다."

6.3 — Save (uses the role registry, not hardcoded paths)

1. roles.decisions.path

   is set → save there.
2. Else

   roles.archive.path

   is set + writable → save there.
3. Else create

   audits/

   at vault root and save there. Note the missing role to F9.0.

{decisions-folder}/{YYYY-MM-DD}-vault-audit.html

{decisions-folder}/{YYYY-MM-DD}-vault-audit-findings.json

6.4 — Open + render + summarize (final response, in this order)

Bash

open "{path}"

xdg-open

start

html

✅ Optimizer run complete — here's what changed:
Report: {decisions-folder}/{YYYY-MM-DD}-vault-audit.html
JSON sidecar: {decisions-folder}/{YYYY-MM-DD}-vault-audit-findings.json
Score (F1–G7): {score_before} → {score_after} ({delta_sign}{delta}) — "{interpretation_before}" → "{interpretation_after}"
{N} files audited · {applied_total} fixes applied · {failed_total} mechanical failures (see report for reasons)
Em dashes: {em_before} → {em_after} (-{em_delta}) · Frontmatter coverage: {fm_pct_before} → {fm_pct_after} (+{fm_pct_delta}pp) · Folder-index coverage: {idx_pct_before} → {idx_pct_after} (+{idx_pct_delta}pp)
Tokens saved: {tokens_saved} ({tokens_pct_saved}% reduction in agent-load) · ~{annual_savings} tokens/year saved at {sessions}/week

applied

failed

Rules — what to never do

• Never assume a folder or file by name. Always resolve through the role registry built in Step 1.5.

  Context/

  ,

  Projects/

  ,

  Daily/

  ,

  Plot.md

  ,

  me.md

  , etc. are examples in the documentation; the runtime resolves abstract roles to whatever the user actually has.
• Never ignore a folder because it doesn't fit a standard role. Every folder is classified — standard or custom — with a layer. Custom roles (

  Building/

  ,

  Garden/

  , anything user-specific) are first-class participants in every framework that operates on their layer. Skipping them defeats the discovery pass.
• Never treat the role registry as ephemeral. Persist confirmed assignments to

  .claude/vault-roles.json

  at end of Step 1.5 so future runs start from the user's confirmed view of their vault, not from a fresh re-classification that re-prompts everything.
• Never propose a structural change purely because BenAI uses that convention. F9.0 tier-2 findings (functional improvements suggesting BenAI conventions) must cite specific evidence in this vault that the convention would resolve a real problem. F9.6 reorg proposals must cite the user's own stated folder purposes. "BenAI does X" is not a valid justification anywhere in the optimizer. The BenAI taxonomy is a recognition lens and an optional reference — never a target shape the user must conform to.
• Never drop a tier-2 finding when the user has a custom role already serving the function. If

  Lab/

  (custom curated) is already playing the projects role, no F9.0 tier-2 finding fires for "you should add a projects folder." Function over name.
• Never unilaterally decide a finding is "test fixture," "user probably didn't want this," "judgment-required-per-section," or any other agent-invented reason to route a finding to anything other than

  applied

  /

  failed

  in bulk-apply mode. The user said apply everything; that means everything. If applying is mechanically dangerous, attempt the safest mechanical version (e.g., split a 222KB file at H2 boundaries with an automated-split marker, mark

  applied_with_caveat: true

  ). The only valid escape is mechanical failure with a recorded

  failure_reason

  .
• Never render the dashboard with the BEFORE score. Step 5.9 is mandatory: re-measure after fixes, recompute score, populate

  {{SCORE_AFTER}}

  and the per-role/per-framework after columns. A dashboard that shows only BEFORE-state numbers is a bug.
• Never frame the final summary as "what we need to do" in bulk-apply mode. The summary is retrospective: what changed, how much, what failed mechanically and why. Save-to-plan / declined / "for later" framings belong only to selective-walk mode.
• Never apply a change the user didn't approve via

  AskUserQuestion

  walk in Step 4.
• Never auto-rewrite a CLAUDE.md without per-item user confirmation. F1.x edits, F9.1 routing rewrites, and F9.7 orientation additions are walk-only — the user reviews and confirms each drafted edit before it lands.
• Never delete a file before grepping for references.
• Never modify files in the technical skip list (

  .git

  ,

  .obsidian

  ,

  .trash

  ,

  node_modules

  ,

  dist

  ,

  build

  ).
• Never apply substitutions inside protected zones (code, URLs, paths, frontmatter, wikilinks, headings, table delimiters, dates).
• Never skip a file because of its role. The classification routes rules; it never excludes files.
• Never skip a framework. F1–F9 all run every audit.
• Never leave a finding open. Every finding ends Step 5 with

  fix_status

  set to

  applied

  ,

  saved_to_plan

  ,

  declined

  , or

  failed

  . Unset is a bug.
• Never bulk-apply semantic fixes (F2.2 wikilinks, F2.4 cross-refs, F8.x reflection, F9.1–F9.7 architecture). Every semantic fix walks per item with the user confirming target/winner/destination/wording.
• Never let F8 or F9 modify a SKILL.md or anything in

  .claude/rules/

  . F8's scope is the curated layer; F9's scope excludes SKILL.md and

  .claude/rules/

  .
• Never complete an F8.2 merge or F9.5 folder merge without verifying (a) merged file size against F5's per-file budget and (b) zero new dead wikilinks. Failing either rolls back and sets

  fix_status: failed

  .
• Never generate a Plot.md that exceeds 8KB or has em dashes. If a folder's children list would push Plot.md over budget, route to F9.6 reorg proposal (split the folder) instead.
• Never delete a merge source. F8.2 / F9.5 archive sources to

  Intelligence/archive/{date}-merged/

  .
• Never score F8 or F9 into the health score. Both surface optimization opportunities, not lint failures; the score covers F1–G7 only.
• Never paraphrase a framework rule when surfacing a finding. Read the relevant pass-implementation file when running its checks; cite the framework in the finding. The Step 2.2 sanity gate enforces this.
• Never run silently. Step 0.5 creates the visible task list; every framework's task transitions

  in_progress

  →

  completed

  as the run unfolds. Skipping the task list defeats the skill.
• Never ship a half-rendered template. If any

  {{placeholder}}

  survives → fail.
• Never dump partial HTML mid-run. The full HTML appears once, at the end (Step 6.4 Part 2). Don't paste HTML twice; don't paste partial fragments while findings are being collected.

Why this skill exists

references/{framework}.md

references/passes-{framework}.md