@uzysjung/agent-harness 26.154.0 → 26.156.0

package/dist/trust-tier-drift.js

@@ -17,7 +17,7 @@ import {
   init_esm_shims,
   residentCost,
   resolveBundleRoot
-} from "./chunk-242TVGMZ.js";
+} from "./chunk-PPJUFG53.js";
 
 // src/trust-tier-drift.ts
 init_esm_shims();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzysjung/agent-harness",
-  "version": "26.154.0",
+  "version": "26.156.0",
   "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
   "type": "module",
   "publishConfig": {

package/templates/skills/recurrence-prevention/SKILL.md

@@ -116,8 +116,8 @@ one.)
 | Level | When | Countermeasure | Characteristic failure of this level |
 |---|---|---|---|
 | **0 기록** | 1st occurrence | Fix + durable record: memory/lessons entry with **Why** it matters and **How to apply**, or an occurrence link on a related rule's 신설 근거 line if one already exists | Records don't steer — nothing re-reads them at the decision moment |
-| **1 룰 강제 등록** | 2nd occurrence (the record failed) | Register a forced rule on the project's **always-loaded steering surface**, using the template below — one-line principle + a one-line "신설 근거" with links to each occurrence. `.claude/rules/<name>.md` (Claude Code) or a rules section in `AGENTS.md` (other CLIs) — and **verify it actually loads**: if the always-loaded context (CLAUDE.md / AGENTS.md) doesn't already pull that location in, reference the rule from it. A rule file nothing loads is still Level 0 with extra steps | Prose can be skimmed, forgotten under context pressure, or rationalized around |
-| **2 구조적 게이트** | 3rd+ occurrence, **or** a registered countermeasure failed — bypassed *or* followed as designed yet insufficient | Deterministic enforcement that does not depend on the agent reading anything: a test gate that fails CI, a pre-action hook that blocks the command (where the CLI supports hooks), or **derive-to-single-source** so the drift is structurally impossible | Gates that never demonstrably fire; gates so noisy they get bypassed |
+| **1 룰 강제 등록** | 2nd occurrence (the record failed) | Register a forced rule on the project's **always-loaded steering surface**, using the template below — one-line principle + a one-line "신설 근거" with links to each occurrence. `.claude/rules/<name>.md` (Claude Code) or a rules section in `AGENTS.md` (other CLIs) — and **verify it actually loads**: if the always-loaded context (CLAUDE.md / AGENTS.md) doesn't already pull that location in, reference the rule from it. A rule file nothing loads is still Level 0 with extra steps. **Shape**: the *minimum condition* that prevents the failure — what must be true, not how to do it — stated in positive form; a prohibition only where the damage is irreversible | Prose can be skimmed, forgotten under context pressure, or rationalized around |
+| **2 구조적 게이트** | 3rd+ occurrence, **or** a registered countermeasure failed — bypassed *or* followed as designed yet insufficient | Deterministic enforcement that does not depend on the agent reading anything: a test gate that fails CI, a pre-action hook that blocks the command (where the CLI supports hooks), or **derive-to-single-source** so the drift is structurally impossible. **Shape**: one level up means *more deterministic*, not *more forbidden* — the gate checks a result and leaves the model's judgment where no check can express it | Gates that never demonstrably fire; gates so noisy they get bypassed |
 
 Load-bearing principle at Level 2: **comment warnings and doc reminders are not a blocking
 mechanism.** If the countermeasure's effect depends on someone (human or model) reading prose at
@@ -136,7 +136,7 @@ fifth.
 
 **Level 1 pre-flight — a 2nd occurrence does not automatically earn a rule.** Per unit of
 enforcement a rule is the most expensive artifact on the ladder: it is read **every session, by
-every install, forever**, while a gate costs CI time and **zero** standing context. Answer three
+every install, forever**, while a gate costs CI time and **zero** standing context. Answer four
 questions in order and stop at the first that decides:
 
 1. **Can the wrong action be detected deterministically?** — a failing test, a hook that exits
@@ -149,14 +149,20 @@ questions in order and stop at the first that decides:
    nothing and bills every session. Stay at Level 0.
 3. **Is it general, or is it this project's circumstance?** A project's own incidents belong on
    that project's steering surface — never in a rule set that strangers install.
-
-Only what survives all three — **a judgement call no deterministic check can express, that
-changes behaviour, and that generalises** — is a rule candidate. That is the bar for "serious
+4. **Does the rule replace the model's judgment, or feed it?** A rule that fixes a procedure
+   ("always run X before Y", "review every edit") replaces a judgment the model could make by
+   risk — and stops improving when the model improves. Rewrite it as a one-line criterion (what
+   must be true, what evidence counts) and let the model choose the depth. A rule that removes a
+   place where the model decides is not a rule candidate in that form.
+
+Only what survives all four — **a judgement call no deterministic check can express, that
+changes behaviour, that generalises, and that gives the judgment an input instead of replacing
+it** — is a rule candidate. That is the bar for "serious
 enough to be worth permanent context".
 
 **Confirm before adding standing cost.** Levels 1 and 2 need explicit user confirmation. For a
 rule the escalation must state, in one block: signature · count with evidence · the proposed text ·
-**its standing cost in tokens and the resulting total** · which of the three questions it survived
+**its standing cost in tokens and the resulting total** · **its per-run cost** (seconds, rounds, or questions added to every task — a countermeasure that slows every task to prevent one incident is rejected unless "what actually happens without it" is the answer) · which of the four questions it survived
 and why the deterministic alternative does not work. **Do not guess the cost — measure the draft**
 (if the project reports context cost, run that report). Level 0 needs no confirmation — recording
 a fact is free and always right.
@@ -169,10 +175,11 @@ a fact is free and always right.
 <One-line principle, stated as an imperative.> **신설 근거: N회 재발** (<date/version> ·
 <date/version>) — 발생별 기록은 <issue / ADR / postmortem link per occurrence>.
 
-## 절대 원칙
+## 지켜야 할 상태
 
-**<The enforced behavior. One sentence if possible.>**
-<What is explicitly forbidden, and what to do instead.>
+**<The state that must hold when this rule is followed — positive form, one sentence if possible.>**
+<What breaks it, and what to do instead. A prohibition ("X 금지") belongs here only when X is
+irreversible damage or a protected gate; otherwise state the condition and leave the method to the agent.>
 
 ## 위반 발견 시
 
@@ -201,7 +208,7 @@ for mechanics — run 3-5 personas in parallel, independently, then synthesize):
 - **The adversary** — "this countermeasure will fail because…" for each candidate.
 
 Synthesize into 2-3 concrete countermeasure options with costs, and present them as a decision
-(recommendation first, ASIS→TOBE contrast — see `clear-korean-communication` if bundled). The
+(recommendation first, ASIS→TOBE contrast — see `user-centered-explanation` if bundled). The
 chosen option still lands on the ladder: it becomes a record, a rule, or a gate — the panel decides
 *what* the countermeasure is, the ladder decides *how hard* it is enforced. The
 never-above-your-count guard governs slips with no failed countermeasure; here, a prior
@@ -209,8 +216,9 @@ countermeasure that fired as designed and still failed already justifies landing
 it (a failed Level-1 rule → a Level-2 gate is escalation, not inflation).
 
 When choosing among the panel's options, compare them on prevention strength, false-positive rate,
-standing context cost, maintenance cost, and permission impact — and prefer the *smallest*
-mechanism that actually prevents the cause. The mechanism menu is in
+standing context cost, **per-run speed cost** (time, rounds, and questions added to every task),
+**effect on the model's autonomy** (does it feed a judgment or replace one), maintenance cost, and
+permission impact — and prefer the *smallest* mechanism that actually prevents the cause. The mechanism menu is in
 [references/failure-analysis.md](references/failure-analysis.md).
 
 ## Step 4 — Verify the countermeasure fires
@@ -235,8 +243,8 @@ would be a false ship. Before closing:
 - Classification: 단순 실수 | 복잡한 하네스 문제 (+ the discriminator that decided it)
 - Countermeasure: Level 0 기록 | Level 1 룰 | Level 2 게이트 | 페르소나 설계 → <chosen option>
 - Artifact: <path of memory entry / rule file / test or hook>
-- Standing cost: <rule 이면 측정치 ~N tokens/session + 갱신된 총합 | gate·record 면 0>
-- Pre-flight: <Level 1 3질문 통과 근거 — 결정론 불가 사유 · 행동 변화 · 일반성>
+- Standing cost: <rule 이면 측정치 ~N tokens/session + 갱신된 총합 | gate·record 면 0> · per-run: <매 작업에 더해지는 시간·라운드·질문 | 0>
+- Pre-flight: <Level 1 4질문 통과 근거 — 결정론 불가 사유 · 행동 변화 · 일반성 · 판단을 대신하지 않음>
 - Fires-verified: <RED→GREEN output, hook exit code, grep proof — or "룰 프로즈: 미검증" honestly>
 - User confirmation: <obtained for Level 1/2 | not needed (Level 0)>
 ```
@@ -265,6 +273,10 @@ before creating them. Level 0 records need no confirmation.
   is already on the failing trajectory even if no single rule looks unreasonable.
 - **Gate theater** — a gate that was never seen to fire may be checking nothing (wrong matcher,
   wrong path, dead config). Step 4 is mandatory, not optional polish.
+- **Prohibition accumulation** — countermeasures written only as "do not X" pile into a defence
+  list: each blocks one path to the bad state and none of the others, and a model reading a wall
+  of prohibitions either routes around it or freezes. Write the state that must hold; reserve
+  prohibitions for irreversible damage and protected gates.
 - **Same-level retry** — responding to a recurrence by rewriting the same rule more emphatically
   (CAPS, "NEVER", repetition). The level failed, not the wording. Escalate.
 - **Inflating the count** — when no prior artifact can be found, record this as the first confirmed
@@ -273,7 +285,7 @@ before creating them. Level 0 records need no confirmation.
 ## Cross-references
 
 - `multi-persona-review` — panel mechanics for the complex path (Step 3b).
-- `clear-korean-communication` — presenting countermeasure options for user confirmation
+- `user-centered-explanation` — presenting countermeasure options for user confirmation
   (recommendation first, ASIS→TOBE contrast).
 - **Periodic audit of accumulated countermeasures** — the natural cleanup loop for what this skill
   creates (are the rules and gates still TRUE, USED, AFFORDABLE, SAFE?). No bundled skill owns it;

package/templates/skills/recurrence-prevention/references/failure-analysis.md

@@ -47,17 +47,18 @@ Before designing anything durable, stop the bleeding without widening the blast
 
 ## Countermeasure mechanisms
 
-Prefer the smallest mechanism that prevents the *cause*, not the symptom:
-
-| Cause shape | Mechanism |
-|---|---|
-| Incorrect behavior | Fix the code or the contract |
-| A stable behavioral boundary regressed | Regression test |
-| The same truth is written in two places | Derive from one source (delete the copy) |
-| A deterministic lifecycle event is violated | Hook, or a verification gate |
-| A judgment recurs at decision time and no check can express it | A concise Rule (Level 1) |
-| Completion is claimed without evidence | Verification gate that requires the evidence |
-| Human or external coordination gap | Operating procedure / checklist |
+Prefer the smallest mechanism that prevents the *cause*, not the symptom — and count, for each
+candidate, what it costs on every run and what judgment it takes away from the model:
+
+| Cause shape | Mechanism | Per-run cost | Autonomy impact |
+|---|---|---|---|
+| Incorrect behavior | Fix the code or the contract | none | none |
+| A stable behavioral boundary regressed | Regression test | CI time | none — checks a result, not a method |
+| The same truth is written in two places | Derive from one source (delete the copy) | none (removes work) | none |
+| A deterministic lifecycle event is violated | Hook, or a verification gate | every matching action; a blocking hook adds a round each time it misfires | low if it checks a result; high if it fixes a procedure |
+| A judgment recurs at decision time and no check can express it | A concise Rule (Level 1) | every session (standing context) | feeds the judgment when it states a criterion; replaces it when it fixes a procedure — write the criterion |
+| Completion is claimed without evidence | Verification gate that requires the evidence | per completion claim | none — asks for evidence, not a method |
+| Human or external coordination gap | Operating procedure / checklist | every run of the procedure | high — use only where coordination, not judgment, is the gap |
 
 Verify a mechanical mechanism on **both** the bad case and the corrected case — a gate seen green
 only has never been shown to bite. Record prose-only safeguards as unverified enforcement; that

package/templates/skills/user-centered-explanation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: user-centered-explanation
+description: >-
+  개발 중 문제·변경안·선택지를 사용자 행동과 결과의 관점에서, 사용자의 언어로 설명한다.
+  맥락·원인·대안·추천 이유를 연결하고,
+  UI/UX 변경은 필요한 화면·문구·동작의 전후 차이를 보여준다.
+  사용자가 "뭔 소리야", "쉽게 설명해줘", "왜 문제야",
+  "사용자에게 뭐가 달라져?", "화면으로 보여줘", "선택지와 추천을 정리해줘"라고 하거나
+  중요한 선택·승인의 차이와 근거를 설명할 때 사용한다.
+  이 스킬만 호출하면 현재 대화의 미해결 문제나 직전 선택 요청을 사용자 관점으로 재정리한다.
+---
+
+# User-Centered Explanation
+
+개발 중 문제와 변경안을 사용자 행동·결과·선택의 관점으로 바꾸어 설명한다.
+사용자가 앞선 대화나 코드를 다시 읽지 않아도 다음을 판단할 수 있게 한다.
+
+**무슨 상황인지 → 무엇이 왜 문제인지 → 어떤 선택지가 있고 무엇이 달라지는지 → 무엇을 추천하며 왜 그런지**
+
+아래 순서·표·예시는 설명을 돕는 기본값이지 고정된 사고·작업 절차가 아니다. 사용자의 목적과 선호 형식을 존중하면서, 설명 깊이·비교 기준·표현 방식은 이해와 판단에 필요한 정보, 읽는 부담, 작업 비용을 고려해 선택한다.
+
+설명과 의사결정을 돕는 스킬이며 작업 범위나 승인 정책 자체를 변경하지 않는다. 답변 언어는 사용자가 쓰는 언어를 따른다.
+
+## 적용
+
+직접 호출되면 현재 대화에서 다음 순서로 대상을 찾는다.
+
+**사용자가 지정한 주제 → 미해결 문제·직전 선택 요청 → 직전 설명**
+
+대화에서 대상을 알 수 있으면 다시 묻지 않는다. 설명할 대상 자체가 없을 때만 원문이나 주제를 요청한다.
+
+직접 호출하거나 중요한 선택·승인을 설명할 때는 아래 기본 표를 우선 사용한다. 기존 형식이 충분히 명확하면 유지한다. 짧은 설명이나 도식이 더 명확하면 판단에 필요한 내용을 유지하면서 항목을 합치거나 표현을 바꿀 수 있다.
+
+직접 호출하지 않은 단순 정보 전달이나 완료 보고는 같은 설명 관점을 유지하되 필요한 내용만 짧게 전달한다.
+
+사용자가 별도 형식을 지정하면 그 형식을 따른다. 어떤 형식이든 **맥락·원인·대안·추천 이유** 중 현재 판단에 필요한 내용이 드러나게 한다.
+
+## 설명 원칙
+
+### 1. 사용자 관점에서 설명한다
+
+파일·함수·오류명보다 먼저 다음을 연결한다.
+
+**사용자가 하려는 일 → 현재 상태 → 문제 또는 제약 → 발생 원인 → 실제 영향**
+
+버그가 아니라 설계 선택, 요구사항 충돌, 환경 제약이라면 그대로 설명한다. 신규 기능은 달성할 목표를, 내부 개선은 직접적인 사용자 변화 여부와 유지보수·운영상의 이유를 설명한다.
+
+설명을 듣는 사람과 실제 영향을 받는 서비스 이용자·관리자·운영자가 다르면 구분한다. 같은 이름이 서로 다른 대상·위치·단계를 가리키면 먼저 구분하고, 실제 영향을 받는 사람의 과업을 기준으로 설명한다.
+
+기술 용어를 쉬운 단어로 바꾸는 데 그치지 않고, 어떤 상황에서 사용자가 무엇을 보거나 할 수 있는지 설명한다.
+
+예: “캐시 무효화를 수정한다”보다 “이름을 바꿔도 목록에는 예전 이름이 남습니다. 저장 후 목록도 최신 이름으로 갱신하도록 고칩니다.”라고 설명한다.
+
+기술 정보는 판단에 필요한 만큼만 사용하고, 낯선 용어는 해당 맥락에서 이해할 수 있게 풀어 쓴다. 정확한 기술명·관련 위치·제약은 필요한 경우 뒤에 덧붙이며, 쉽게 설명하기 위해 의미나 위험을 생략하지 않는다.
+
+### 2. 사실·가설·판단을 구분한다
+
+확인된 사실과 원인, 아직 확인되지 않은 가설, 추천 판단을 섞지 않는다.
+
+이미 확보한 근거가 현재 설명에도 유효하면 재사용한다. 추가 확인은 설명의 정확성이나 선택을 바꿀 수 있는 미확인 사항에 집중하고, 조사·검증의 깊이는 영향과 요청 범위에 맞춘다.
+
+원인이 확인되지 않았다면 원인을 단정하지 말고 다음을 구분한다.
+
+- 확인된 현상과 영향
+- 가능한 원인 또는 가설
+- 방향을 결정하기 위해 추가로 확인할 사항
+
+수치·비용·일정·효과는 근거가 있을 때만 사용한다. 추정치는 가정을 밝히고, 표를 채우기 위해 수치나 대안을 만들지 않는다.
+
+제안·구현·검증·배포 상태를 구분한다. 코드 수정이나 개념 도식만으로 실제 동작·사용성·배포까지 확인된 것처럼 표현하지 않는다.
+
+### 3. 실제 선택 차이를 설명한다
+
+선택지는 개수를 맞추지 말고 실제 선택할 가치가 있는 것만 제시한다. 현상 유지나 보류도 의미 있는 선택이면 포함한다.
+
+각 방안은 다음 차이가 드러나게 설명한다.
+
+**무엇을 하는가 → 왜 해결되는가 → 무엇이 달라지는가 → 어떤 부담이나 위험이 있는가**
+
+비용, 일정, 품질, 사용성, 안전성, 운영 부담 등 실제 결정을 바꾸는 기준에 집중한다.
+
+### 4. 추천은 명확하게 한다
+
+선택이나 조치가 필요할 때는 사용자의 목적과 현재 제약을 기준으로 가장 적합한 방안을 추천한다.
+
+추천에는 다음 중 실제 판단에 영향을 주는 내용을 포함한다.
+
+- 추천하는 이유
+- 다른 방안보다 적합한 이유
+- 감수해야 할 주요 단점
+- 추천을 바꿀 수 있는 중요한 미확인 조건
+
+추천은 판단이지 확인된 사실처럼 표현하지 않는다.
+
+## 기본 출력
+
+핵심 문제 또는 지금 필요한 판단을 먼저 짧게 밝히고, 다음 표를 기본으로 정리한다.
+
+| 항목 | 내용 |
+|---|---|
+| **맥락** | 사용자가 하려는 일, 기대 결과, 현재 상태와 이 문제가 나온 배경 |
+| **문제점** | 확인된 문제·제약, 원인 또는 미확인 사항, 누구에게 어떤 영향이 있는지 |
+| **해결방안** | 실제 가능한 방안과 해결 원리, 변경 후 행동·결과, 장점·부담 |
+| **추천방안** | 추천안과 이유, 주요 단점, 필요한 다음 행동 |
+
+설계 선택이나 목표를 설명하는 경우에는 필요에 따라 **문제점**을 **검토사항**으로 바꾼다. 문제가 없거나 조치가 필요 없다면 억지로 해결책을 만들지 말고 그 사실과 이유를 설명한다.
+
+선택지 비교가 복잡하면 **해결방안을 별도 비교표로 분리**할 수 있다.
+
+직접 호출하지 않은 완료 보고는 **무엇이 달라졌는지 → 무엇을 실제로 확인했는지 → 남은 제한이나 필요한 행동**을 중심으로 전달한다. 해당하지 않는 항목은 생략한다.
+
+### 화면·동작의 전후 비교
+
+UI/UX 변경에서 배치·문구·동작의 차이를 말만으로 판단하기 어렵거나 사용자가 시각적인 비교를 요청하면, 변경 전후를 보여준다.
+
+텍스트 환경에서 화면 배치·컴포넌트 구성은 코드 블록 안의 ASCII/Unicode 선으로 **AS-IS → TO-BE** 와이어프레임을 보여주는 것을 기본으로 한다. 문구만 바뀌면 문구를 비교하고, 화면 이동이나 작업 절차가 바뀌면 전후 사용 흐름을 보여준다.
+
+이미 있는 화면·도식이나 다른 표현이 더 명확하면 활용한다. 도구 사용이나 새 산출물 제작은 요청 범위와 권한 안에서, 설명과 판단에 주는 이점이 추가 부담보다 클 때 선택한다.
+
+같은 사용자 과업·데이터·상황을 기준으로 비교하고, 변경을 이해하는 데 필요한 영역만 표현한다. 실제 또는 제안하는 버튼명·필드명·안내 문구를 넣어 사용자가 보게 될 내용을 알 수 있게 한다.
+
+상호작용이 있으면 행동 후 결과를 함께 보여준다. 처리 중·실패·복구·권한 제한 상태가 판단에 영향을 주면 필요한 범위만 포함한다. 문구가 약속하는 동작과 제안하는 기능이 일치하도록 한다.
+
+이미 확인한 화면·코드·사용자 설명을 활용하고, 확인된 현재 상태와 가정·제안을 구분한다. 현재 화면을 확인하지 못했다면 사용자 설명을 바탕으로 재구성했다고 밝히거나, AS-IS 미확인으로 표시하고 TO-BE만 보여준다. 신규 화면은 억지로 AS-IS를 만들지 않고 현재 사용 흐름이나 제안 화면을 보여준다.
+
+텍스트 도식은 읽기 쉽도록 **표 밖의 코드 블록**에 둔다. 표를 함께 사용하면 **해결방안**에는 변경의 요지와 이유를 적고, 실제 전후 차이는 도식이 설명하게 한다. 다른 항목도 도식에서 충분히 전달되었다면 요지만 남기거나 합쳐 반복을 줄인다.
+
+## 질문과 승인
+
+질문·승인 여부는 기존 프로젝트 정책과 사용자 위임 범위를 따른다. 그 안에서 사용자 결정이 필요한 미해결 사항만 질문한다.
+
+이미 위임받은 판단은 합리적인 방안을 선택해 처리하고 이유를 설명한다.
+
+질문이 필요하다면 단순히 "어떻게 할까요?"라고 묻지 말고 다음이 드러나게 한다.
+
+**무엇을 결정해야 하는지, 선택지의 차이가 무엇인지, 무엇을 추천하는지**
+
+설명이나 재정리 요청에 `진행할까요?` 같은 불필요한 실행 승인을 덧붙이지 않는다.
+
+## 품질 기준
+
+최종 답변만 읽어도 사용자가 현재 판단에 필요한 범위에서 다음 연결을 이해할 수 있어야 한다.
+
+**맥락 → 문제 또는 검토사항과 원인 → 선택지와 전후 차이 → 추천 이유와 필요한 행동**
+
+화면이나 동작을 바꾸는 설명은 사용자가 무엇을 보고, 무엇을 하면 어떤 결과가 나오는지 예상할 수 있어야 한다. 제안·미확인 사항이 이미 구현되거나 검증된 사실로 읽히지 않는지 확인한다.
+
+형식의 충족보다 사용자가 상황과 변경 결과를 이해하고 판단할 수 있는지로 완성도를 평가한다. 이해와 판단에 충분하면 설명을 마치고, 같은 내용을 도입·표·도식·결론에서 반복하지 않는다.