sprag-cli 3.40.0

package/presets/korean-style/supplement.md

@@ -0,0 +1,93 @@
+<!--
+  claude-token-saver's own supplement to the vendored fluent-korean guidance.
+  Compiled 2026-09-13 from:
+  - 국립국어원 「한눈에 알아보는 공공언어 바로 쓰기」 및 한글문화연대의 번역투 교정 사례 (urimal.org/4544)
+  - 쿠버네티스 문서 한글화 가이드 (kubernetes.io/ko/docs/contribute/localization_ko/)
+  - 「한국어 AI 글쓰기에서 피해야 할 상투적 패턴」 (gist: woonjangahn)
+  - 문장 연결 원칙: 생글생글 논술 첨삭노트 133 (sgsg.hankyung.com/article/2013012517791),
+    구정보-신정보 배열과 주제 연쇄는 국어 글쓰기 교육의 통설
+  - 응집성 실증 근거: 「한국어 교육과 결속성(cohesion) 및 응집성(coherence)의 문제」
+    (KCI ART002501143: 결속 장치와 텍스트 질은 상관이 없거나 부적),
+    「한국어 학습자의 쓰기 텍스트에 나타난 응결성과 응집성의 상관분석」
+    (KCI ART002240473, 우리말글: 대용 남발은 부적 상관, 상술형 접속만 정적 상관),
+    「한국어 학습자 텍스트의 내용적 오류 양상: 응집성 중심」
+    (DBpia NODE11604445, 2023: 주제부-설명부 분석, 오류를 관련성·일관성으로 분류)
+  - 나무위키 「번역체 문장」의 과교정 경고
+
+  Only patterns that survive a conservative bar are included: each clause names
+  a form that is nearly always an improvement to change, and the final section
+  lists forms that must NOT be "corrected". This file is appended to the
+  session-start injection after fluent-korean.md; see src/korean-style.js.
+-->
+
+## 보강 지침 (claude-token-saver 자체 수집분)
+
+앞의 fluent-korean 본문에 더해, 아래 지침도 같은 범위와 같은 우선순위로 적용합니다. 각 조항은 국립국어원의 공공언어 지침과 공개된 기술 문서 한글화 지침에서 보수적으로 골라 낸 것이므로, 판단이 갈리는 표현은 여기에 싣지 않았습니다.
+
+### 번역투 추가 조항
+
+1. 이중 피동을 쓰지 않습니다. 피동 표현이 필요하면 단일 피동으로 충분합니다.
+   - ✗ 보여집니다, 쓰여진, 잊혀진, 되어지고 → ○ 보입니다, 쓰인, 잊힌, 되고
+
+2. 일본어에서 온 굳은 번역투는 항상 바꿉니다.
+   - ✗ 성공에 다름 아니다 → ○ 성공일 뿐이다, 바로 성공이다
+   - ✗ 노력하지 않으면 안 됩니다 → ○ 노력해야 합니다
+
+3. 조사만으로 충분한 곳에 관용구를 끼우지 않습니다.
+   - ✗ 모든 분야에 있어서 기준이 필요하다 → ○ 모든 분야에서 기준이 필요하다
+   - ✗ 국민투표에 의하여 결정한다 → ○ 국민투표로 결정한다
+   - ✗ 미국 여행을 가기 위해 영어를 공부했다 → ○ 미국 여행을 가려고 영어를 공부했다
+
+4. 속성 서술에 '가지다'를 쓰지 않습니다. 영어 have의 직역이라 서술이 늘어집니다.
+   - ✗ 하나라는 의미를 가지고 있다 → ○ 하나라는 의미다
+   - ✗ 세 가지 장점을 가진다 → ○ 장점이 세 가지 있다
+
+5. 행위자가 분명한 문장은 능동으로 씁니다. 피동은 행위자를 밝힐 수 없거나 밝힐 필요가 없을 때만 씁니다.
+   - ✗ 아이들은 보육원에 의해 보호되었다 → ○ 보육원이 아이들을 보호했다
+
+### 상투 패턴 억제 조항
+
+LLM 산출물에서 반복적으로 관찰되는 습관입니다. 금지가 아니라 절제 대상이므로, 한 문서 안에서 되풀이될 때 고칩니다.
+
+1. 수식어를 자동으로 붙이지 않습니다. '다양한', '핵심적인', '효과적으로', '성공적으로' 같은 수식어는 구체 정보가 없으면 빼고, 있으면 그 정보로 대체합니다.
+   - ✗ 다양한 분야에서 활용됩니다 → ○ 금융과 의료 분야에서 활용됩니다
+
+2. 표지판 문장을 줄입니다. '지금부터 살펴보겠습니다' 같은 도입, '결론적으로' 같은 마무리 표지는 본문이 짧으면 빼고 바로 내용을 적습니다.
+
+3. 수사적 질문을 던지고 곧바로 답하는 구성을 쓰지 않습니다.
+   - ✗ 해답은 무엇일까요? 바로 캐시입니다. → ○ 해답은 캐시입니다.
+
+4. '~뿐만 아니라 ~도' 구문은 한 문단에 한 번까지만 씁니다.
+
+5. 영어(한글) 병기는 용어가 처음 나올 때 한 번만 하고, 그 뒤로는 정착된 한쪽 표기만 씁니다. 이는 쿠버네티스 한글화 가이드의 병기 원칙과 같습니다.
+
+6. 근거 없이 긍정적으로 끝맺지 않습니다. '앞으로의 발전이 기대됩니다' 같은 마무리는 내용이 뒷받침할 때만 씁니다.
+
+### 문장 연결 조항 (응집성)
+
+문장 하나하나가 옳아도 이어짐이 어색하면 읽기 어렵습니다. 아래 원칙은 문장을 잇는 방법이므로, 문서와 내레이션처럼 이어 읽는 글에 우선 적용합니다. 연구 결과가 방향을 정해 줍니다. 접속어와 지시어 같은 표층 연결 장치는 글의 품질과 상관이 없거나 오히려 부적 상관이고, 앞 내용을 자세히 풀어 주는 상술형 연결만이 품질과 정적 상관을 보였습니다. 그러므로 연결이 어색할 때 접속어를 더하는 대신, 정보의 배열을 고치는 쪽으로 손질합니다.
+
+1. 아는 것에서 새 것으로 나아갑니다. 문장 앞부분에는 독자가 이미 아는 정보를 놓고, 새 정보는 뒷부분에 놓습니다. 다음 문장은 앞 문장이 끝에 내놓은 새 정보를 머리에서 받아 이어 갑니다.
+   - ✗ 캐시 적중률이 떨어졌다. 요청 사이의 간격이 TTL을 넘긴 것이 원인이다. 5분이 기본 TTL이다.
+   - ○ 캐시 적중률이 떨어졌다. 원인은 요청 사이의 간격이 TTL을 넘긴 것이다. 이 TTL의 기본값은 5분이다.
+
+2. 지시어에는 가리키는 대상이 하나만 있어야 합니다. '이', '그', '이러한'이 바로 앞 문장의 무엇을 받는지 즉시 답할 수 없으면, 지시어 대신 그 명사를 다시 적습니다. 대용 표현을 자주 쓸수록 의미 연결이 약해진다는 상관 분석 결과가 있으므로, 지시어는 아껴 씁니다.
+
+3. 한 문단 안에서는 주어나 관점을 유지합니다. 문장마다 주어가 바뀌면 독자가 매번 시점을 다시 잡아야 하므로, 바꿀 이유가 없으면 같은 주어로 잇거나 자연스럽게 생략합니다.
+
+4. 접속어는 논리 관계가 실제로 있을 때만 씁니다. '또한'과 '그리고'가 반복되면 문장들이 연결된 것이 아니라 나열만 된 상태라는 신호이므로, 접속어를 더할 것이 아니라 문장 순서와 정보 배열부터 다시 잡습니다. 인과가 있으면 '그래서'나 '~하므로'처럼 관계를 이름 붙여 잇습니다.
+
+5. 문장 사이의 비약을 없앱니다. 뒤 문장이 전제하는 조건이나 이유는 앞 문장이 미리 준비해 두어야 하며, 준비 없이 결론이 나오면 그 사이에 다리가 되는 문장을 하나 넣습니다.
+
+6. 짧은 문장 여러 개가 같은 대상을 반복하면, 덜 중요한 문장을 수식어구로 바꾸어 핵심 문장에 붙입니다.
+   - ✗ 토끼와 거북이가 경주를 했다. 토끼는 잠을 잤다. 거북이가 이겼다.
+   - ○ 잠을 잔 토끼와 달리, 거북이는 꾸준히 걸어 경주에서 이겼다.
+
+### 과교정 금지 조항
+
+교정 자체가 오류가 되는 경우입니다. 나무위키 번역체 문서와 국립국어원 논의가 공통으로 경고하는 지점이므로, 아래 표현에는 위 조항들을 적용하지 않습니다.
+
+1. 전문 용어와 정착된 관용 표기는 원형을 유지합니다. 분야에서 굳은 표기를 일반 어휘로 바꾸면 오히려 뜻이 흐려집니다.
+2. 문어체는 오류가 아닙니다. 구어로만 고쳐 쓰라는 요구는 이 지침에 없습니다.
+3. 원문을 그대로 옮기는 인용은 손보지 않습니다.
+4. 검사 도구의 지적은 확인 요청이지 판정이 아닙니다. 굳은 표현이라 판단해 유지할 때는 그 이유를 한 줄로 남깁니다.

package/presets/model-rules.json

@@ -0,0 +1,115 @@
+{
+  "note": [
+    "Curated tier-delegation presets bundled with the package — the model-fitting",
+    "counterpart to presets/ratchet-rules.md. These were promoted from the author's",
+    "own route-scan candidates over months of real sessions, then stripped of the",
+    "originating examples, project paths and recurrence counts: what carries over is",
+    "the shape of the work (category, tier, agent, cap), not the author's transcripts.",
+    "Each entry is offered one at a time at session start; nothing is registered",
+    "without the user saying yes. Caps are the defaults a scan would calibrate to;",
+    "later scans refresh the stats on whatever the user accepts.",
+    "Rule sentences are composed at accept time from modelRuleBaseText() so that a",
+    "reworded template never leaves this file stale."
+  ],
+  "presets": [
+    {
+      "id": "run-t2",
+      "tier": "T2",
+      "category": "run",
+      "label": "명령 실행 (빌드·테스트·git)",
+      "labelEn": "running commands (build/test/git)",
+      "agent": "haiku-runner",
+      "example": "npm test 돌려봐",
+      "exampleEn": "run npm test",
+      "budget": { "calls": 8, "out": 1500 }
+    },
+    {
+      "id": "run-t1",
+      "tier": "T1",
+      "category": "run",
+      "label": "명령 실행 (빌드·테스트·git)",
+      "labelEn": "running commands (build/test/git)",
+      "agent": "sonnet",
+      "example": "빌드하고 실패한 테스트만 보여줘",
+      "exampleEn": "build it and show only the failing tests",
+      "budget": { "calls": null, "out": 6000 }
+    },
+    {
+      "id": "explore-t2",
+      "tier": "T2",
+      "category": "explore",
+      "label": "탐색·조회 (파일/값 찾기)",
+      "labelEn": "lookup (finding files/values)",
+      "agent": "haiku-explore",
+      "example": "이 설정값 어느 파일에 있어?",
+      "exampleEn": "which file holds this config value?",
+      "budget": { "calls": 8, "out": 1500 }
+    },
+    {
+      "id": "explore-t1",
+      "tier": "T1",
+      "category": "explore",
+      "label": "탐색·조회 (파일/값 찾기)",
+      "labelEn": "lookup (finding files/values)",
+      "agent": "sonnet",
+      "example": "이 함수를 호출하는 곳 전부 찾아줘",
+      "exampleEn": "find every caller of this function",
+      "budget": { "calls": null, "out": 6000 }
+    },
+    {
+      "id": "check-t2",
+      "tier": "T2",
+      "category": "check",
+      "label": "상태 확인·검증",
+      "labelEn": "status checks / verification",
+      "agent": "haiku-explore",
+      "example": "지금 배포된 버전이 뭔지 확인해줘",
+      "exampleEn": "check which version is deployed right now",
+      "budget": { "calls": 8, "out": 1500 }
+    },
+    {
+      "id": "check-t1",
+      "tier": "T1",
+      "category": "check",
+      "label": "상태 확인·검증",
+      "labelEn": "status checks / verification",
+      "agent": "sonnet",
+      "example": "마이그레이션이 실제로 적용됐는지 확인해줘",
+      "exampleEn": "verify the migration actually applied",
+      "budget": { "calls": null, "out": 6000 }
+    },
+    {
+      "id": "paste-t2",
+      "tier": "T2",
+      "category": "paste",
+      "label": "붙여넣은 화면·로그 질문",
+      "labelEn": "questions about pasted screens/logs",
+      "agent": "haiku-explore",
+      "example": "이 에러 로그는 무슨 뜻이야?",
+      "exampleEn": "what does this error log mean?",
+      "budget": { "calls": 8, "out": 1500 }
+    },
+    {
+      "id": "paste-t1",
+      "tier": "T1",
+      "category": "paste",
+      "label": "붙여넣은 화면·로그 질문",
+      "labelEn": "questions about pasted screens/logs",
+      "agent": "sonnet",
+      "example": "이 스택트레이스에서 어느 모듈이 죽은 건지 짚어줘",
+      "exampleEn": "point out which module failed in this stack trace",
+      "budget": { "calls": null, "out": 8000 }
+    },
+    {
+      "id": "read-t2",
+      "tier": "T2",
+      "category": "read",
+      "label": "읽기·요약·설명",
+      "labelEn": "reading / summarizing / explaining",
+      "agent": "haiku-explore",
+      "example": "이 README 요약해줘",
+      "exampleEn": "summarize this README",
+      "budget": { "calls": 8, "out": 1900 }
+    }
+  ]
+}

package/presets/ratchet-rules.json

@@ -0,0 +1,38 @@
+{
+  "note": [
+    "Curated ratchet rules bundled with the package — promoted from mistakes that",
+    "actually recurred in the author's sessions, not from theory. `harness pull`",
+    "registers the whole set at once; `seed` offers them one at a time and records",
+    "each answer. Both read this file, so there is one source for the wording.",
+    "Each rule carries both languages because the text is injected into the model's",
+    "context, where a Korean-only rule would steer an English session into Korean.",
+    "Ids are derived from the `ko` text (the canonical one), so a rule keeps its",
+    "identity — and a user's 'no' — when the English wording is revised."
+  ],
+  "rules": [
+    {
+      "ko": "웹 fetch/search에서 robots·UA 차단('unable to fetch' 등)이 발생하면 → curl에 브라우저 UA(Mozilla/5.0 ... Chrome/...) 헤더를 붙여 재시도. reddit 등은 .json 엔드포인트 + UA 조합으로 접근 가능",
+      "en": "When a web fetch/search is blocked by robots or user-agent checks ('unable to fetch' and similar) → retry with curl carrying a browser UA header (Mozilla/5.0 ... Chrome/...). Sites like reddit also answer on their .json endpoints with that UA"
+    },
+    {
+      "ko": "ratchet 룰 promote 호출 직전 사용자에게 scope(project/global)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --project/--global 플래그를 명시해 실행",
+      "en": "Ask the user for the scope (project or global) before calling ratchet promote — the Bash environment is non-TTY, so the CLI's readline prompt never appears; the caller (the model) has to ask and pass --project/--global explicitly"
+    },
+    {
+      "ko": "자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐",
+      "en": "Never refactor, compress or reword marker text that an automated tool finds by grep or regex (headings, anchors, keyword lines) — exact-match detection breaks on a single changed character"
+    },
+    {
+      "ko": "자동화 설계에서 vision/screenshot 루프가 보이면 → 호출 가능한 함수·API·MCP tool부터 찾는다. 통제 가능한 내부 도구는 무조건 API, 통제 불가 외부 SaaS만 vision 차선책. 인터페이스를 바꾼 뒤에 모델을 내린다 — 거꾸로 가면 토큰 폭발",
+      "en": "When an automation design calls for a vision/screenshot loop → look for a callable function, API or MCP tool first. Anything you control gets an API; vision is the fallback only for external SaaS you cannot change. Fix the interface before lowering the model — doing it the other way round explodes the token cost"
+    },
+    {
+      "ko": "입력 데이터(ground-truth) 변경 시 그에 의존하는 모든 파생 자산을 끝까지 재생성한다 — 중간 단계를 생략하면 stale 산출물이 새 입력 위에 얹혀 결과가 깨짐",
+      "en": "When the ground-truth input changes, regenerate every derived asset all the way through — skipping an intermediate step leaves a stale artifact sitting on top of the new input and the result breaks"
+    },
+    {
+      "ko": "탐색·조회·상태 확인·명령 실행 같은 단순 요청은 `model: haiku` 서브에이전트로 위임해 상위 모델 토큰을 아낀다 (읽기 전용 preset 에이전트가 이미 있으면 그걸 쓰고, 없으면 티어만 내려서 위임)",
+      "en": "Delegate simple requests — lookup, status checks, running commands — to a `model: haiku` subagent to keep the expensive model's tokens for real work (use an existing read-only preset agent when there is one; otherwise delegate with the tier lowered)"
+    }
+  ]
+}