jutell 1.1.0 → 2.0.0

package/README.md

@@ -1,8 +1,8 @@
 # jutell
 
-**Your coding agent writes the code. JuTell helps you understand what happened.**
+**Tell your coding agent what you actually mean — and understand what it actually did.**
 
-JuTell sits beside Codex, Claude Code, or OpenCode and turns their work into a plain-language report: what changed, what's actually verified, what's still unknown, and what to do next.
+Before work, JuTell clarifies only the decisions that would actually change the result (at most one concise question) and checks project facts itself. After work, it turns the result into a plain-language report: what changed, what's actually verified, what's still unknown, and what to do next. It never guarantees your agent's answers — it keeps both directions honest.
 
 ```bash
 npm install -g jutell
@@ -32,7 +32,7 @@ Most people should use the npm install above.
 cd packages/cli
 npm install
 npm pack
-npm install -g ./jutell-1.1.0.tgz
+npm install -g ./jutell-2.0.0.tgz
 ```
 </details>
 

package/assets/mcp-server/index.js

@@ -5,7 +5,7 @@ import { activeFeatures, beginnerReportRules, bridgeStatus, reportPreferences, s
 import { recordToolCall } from './tools/usage-counters.js';
 const server = new McpServer({
     name: 'JuTell',
-    version: '1.1.0',
+    version: '2.0.0',
 }, {
     instructions: 'JuTell by Ju0 is a local read-only report helper. Read only project configuration and approved report rules. Never access project code, Git diff, prompts, AI answers, secrets, or external networks. Skill mode remains available if this MCP server is disabled or unavailable. When both jutell and beginner_bridge servers are visible, prefer the canonical jutell server; use beginner_bridge only for compatibility. For owner-facing reports, apply the JuTell reporting guidance before composing the final answer. Prefer these tools over re-reading the JuTell Skill reference files when both are available, since a tool call returns the same project-specific rules in one step. Call get_beginner_report_rules once, at task completion, right before writing the final report — not after every file read, shell command, or edit, and not to verify work that is already done. If these tools are unavailable or blocked, fall back to the JuTell Skill files without interrupting the task, and never tell the user JuTell MCP was used unless a JuTell tool call actually returned a result in this task.',
 });

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: beginner-bridge
-jutellSkillVersion: "1.1.0"
+jutellSkillVersion: "2.0.0"
 schemaVersion: 1
 description: JuTell by Ju0 creates concise, evidence-based work reports for non-developers, separating observed facts, code-based expectations, verification results, risks, and user actions. The legacy Skill ID is retained for compatibility.
 ---
@@ -54,45 +54,240 @@ JuTell MCP가 보이면 canonical `jutell` 서버를 사용한다. `jutell`과 `
 
 JuTell MCP를 사용할 수 있고 이미 확보한 근거를 재사용해 보고·검증·핸드오프 단계의 모호함을 줄여줄 때는 MCP 도구를 우선한다. MCP가 보이지 않거나 Provider 정책으로 막혀 있거나 불필요한 추가 작업이 될 때는 방해 없이 이 Skill의 참고 문서로 계속 진행한다. 두 경로 모두 최종 결과물의 품질은 같아야 한다. 실제로 JuTell MCP 도구를 호출해 응답을 받은 경우에만 "JuTell MCP를 사용했다"고 표현하고, 호출하지 않았다면 이 Skill의 지침만 따랐다고 표현한다.
 
+## Intent Bridge
+
+실제로 코드나 문서를 바꾸기 전에, 사용자 요청에 결과를 크게 바꿀 수 있는 불확실함이 있는지 확인하고, 있으면 이해한 내용을 짧게 보여준 뒤 승인이나 수정을 받는 절차다. `requestClarificationGuide` Feature가 꺼져 있으면 이 절차 전체를 적용하지 않고 평소처럼 바로 진행한다.
+
+사용자에게는 실제 결정만 묻고, 확인 가능한 사실은 Agent가 직접 확인한다. 질문이 필요하다면 결과를 가장 크게 바꾸는 것 하나만 묻는다.
+
+### 언제 보여주나
+
+요청이 짧다는 이유만으로 보여주지 않는다. 판단 기준은 하나뿐이다: **Agent가 불확실한 부분을 스스로 추측해서 진행하면, 결과가 사용자가 원한 것과 크게 달라질 수 있는가.**
+
+보여줘야 하는 예 (무엇을 어떻게 바꿀지가 정해지지 않음):
+- "로그인 화면 좀 더 깔끔하게 해줘."
+- "이 버튼 좀 더 좋게 바꿔줘."
+- "회원가입 좀 간단하게 만들어줘."
+
+보여주지 않는 예 (짧아도 이미 명확함 — 무엇을, 어디를, 어떻게 바꿀지가 요청 자체에 이미 있다):
+- "README에서 'teh'를 'the'로 고쳐줘."
+- "list.js의 remove 함수 테스트 하나 추가해줘."
+- "버튼 텍스트를 '로그인'에서 '시작하기'로 바꿔줘."
+
+### 질문하기 전에 다섯 가지로 나눈다
+
+사용자에게 물을지 말지 정하기 전에, 남은 불확실함을 다음 다섯 가지로 나눈다. 이 다섯 가지는 Agent 내부 판단 기준이다 — `ASK_USER`, `AGENT_CHECK` 같은 이름표를 사용자에게 그대로 보여주는 기술 UI로 만들지 않는다. 쉬운 말로 바꿔 쓰는 것이 실제로 도움이 될 때만 자연스럽게 반영한다.
+
+- **AGENT_CHECK** — 사용자 결정이 아니라 저장소·코드·환경에서 Agent가 직접 확인할 수 있는 사실.
+- **SAFE_INFERENCE** — 되돌릴 수 있고 결과를 크게 제한하지 않는, 위험이 낮은 추론.
+- **NON_BLOCKING_UNKNOWN** — 아직 모르지만 지금 진행해도 안전한 것.
+- **BLOCKING_UNKNOWN** — 잘못 추측하면 결과가 사용자 의도와 크게 달라질 수 있는 것.
+- **ASK_USER** — 실제로 사용자에게 물어야 하는 것. 아래 판단 기준을 그대로 적용해서 정한다.
+
+#### ASK_USER 판단 기준
+
+다음 두 가지가 **모두** 사실일 때만 ASK_USER로 분류한다.
+
+1. Agent가 프로젝트·저장소·환경의 근거만으로 답을 신뢰성 있게 확정할 수 없다.
+2. 그럴듯한 답이 여러 개 있고, 그 답에 따라 결과가 크게 달라지거나 사용자 의도를 어길 위험이 있다.
+
+둘 중 하나라도 아니면 사용자에게 묻지 않는다. 점수판, confidence 퍼센트, 질문 순위를 매기는 엔진을 따로 만들지 않는다.
+
+#### AGENT_CHECK — 먼저 저장소에서 확인한다
+
+질문을 만들기 전에, Agent가 스스로 확인할 수 있는 사실은 먼저 확인한다. 예: 현재 사용 중인 framework, 파일·컴포넌트 위치, 현재 화면 구조, 기존 스타일, 기존 입력 필드, 현재 동작, 테스트 framework, 기존 반응형 처리 방식.
+
+저장소에서 확인할 수 있는 기술 사실을 사용자에게 묻지 않는다.
+
+나쁜 예:
+- "어떤 CSS 프레임워크를 쓰고 계신가요?" — Agent가 확인할 수 있으면 묻지 않는다.
+- "로그인 버튼이 있는 컴포넌트가 어디인가요?" — Agent가 찾을 수 있으면 묻지 않는다.
+
+사용자는 저장소 조회 도구가 아니다.
+
+AGENT_CHECK에는 필수 관련 수정 범위를 정하는 데 필요한 기술적 제약 확인도 포함된다. 예: 로그인 처리 코드가 특정 요소 ID나 필드 이름을 그대로 참조하는지 확인하는 것. 이런 제약은 사용자의 의도가 아니라 Agent가 직접 확인한 구현 사실이며, 새로운 분류를 따로 만들지 않고 이 AGENT_CHECK 안에서 다룬다.
+
+#### SAFE_INFERENCE — 낮은 위험의 추론
+
+다음을 모두 만족하면 낮은 위험의 추론으로 진행할 수 있다.
+
+- 되돌릴 수 있다.
+- 결과를 크게 제한하지 않는다.
+- 다른 그럴듯한 답을 골랐어도 사용자 의도를 크게 어기지 않는다.
+
+이때도 필요한 곳에는 추론이라는 표시를 남긴다. SAFE_INFERENCE를 조용히 사용자 의도로 승격하지 않는다.
+
+#### NON_BLOCKING_UNKNOWN — 몰라도 진행할 수 있다
+
+아직 정해지지 않았지만 작업을 안전하게 진행할 수 있으면, 억지로 질문을 만들지 않는다. 모르는 채로 남긴다. 필요하면 Intent Bridge의 "아직 정하지 않은 것" 항목이나 최종 보고서에 남긴다.
+
+예: 나중에 조정 가능한 세밀한 시각적 디테일.
+
+#### BLOCKING_UNKNOWN — 추측하면 결과가 크게 달라진다
+
+추측이 실제로 잘못된 제품 결과로 이어질 수 있으면 BLOCKING_UNKNOWN이 되고, ASK_USER 대상이 될 수 있다.
+
+예:
+- 기존 동작이 실제로 바뀔 수 있는지
+- 기존 필드가 실제로 삭제될 수 있는지
+- 결제 흐름 요구사항이 실제로 바뀔 수 있는지
+- 사용자가 원하는 것이 가벼운 정리인지, 전체적인 느낌을 바꾸는 재설계인지
+
+이 예시를 다른 상황까지 과도하게 일반화하지 않는다.
+
+### 질문 없이 진행하는 경로
+
+Intent Bridge가 항상 사용자 질문을 요구하지는 않는다. 다음 흐름도 정상이다.
+
+1. 사용자 요청을 받는다.
+2. 결과를 크게 바꿀 수 있는 불확실함이 있는지 본다.
+3. Agent가 확인 가능한 사실(AGENT_CHECK)을 먼저 확인한다.
+4. 남은 것이 SAFE_INFERENCE나 NON_BLOCKING_UNKNOWN뿐이고 실제 BLOCKING_UNKNOWN이 남지 않으면
+5. 이해한 내용을 짧게 보여줄 수는 있지만, 실제 사용자 결정을 물을 필요는 없다.
+6. Agent가 바로 작업을 진행한다.
+
+이럴 때는 판단할 실제 사용자 결정이 남아 있지 않으므로 "이대로 진행해도 될까요?" 같은 형식적인 확인 질문도 만들지 않는다. 이 동작은 V2.1에서 의도한 것이다.
+
+### 다섯 가지 정보 구분
+
+- **사용자가 직접 말한 것 (USER_SAID)** — 사용자의 표현을 그대로 옮긴다. 바꿔 쓰지 않는다.
+- **JuTell이 이해한 것 (UNDERSTOOD)** — 쉬운 말로 다시 표현할 수 있지만, 사용자가 말하지 않은 새 요구사항을 추가하지 않는다.
+- **JuTell이 추론한 것 (INFERRED)** — 반드시 추론이라고 표시한다. 절대 사용자가 직접 말한 것으로 바꿔 쓰지 않는다.
+- **아직 정하지 않은 것 (UNKNOWN)** — 모르는 채로 남긴다. 추측으로 채우거나 요구사항으로 바꾸지 않는다.
+- **Agent가 먼저 확인할 것 (AGENT_SHOULD_CHECK)** — 사용자가 결정할 일이 아니라, Agent가 저장소·코드에서 직접 확인해야 할 사실만 적는다.
+
+위 AGENT_SHOULD_CHECK는 앞서 정리한 AGENT_CHECK 판단과 같은 항목이다 — 보고서에 남길 때의 이름일 뿐, 별도 체계가 아니다.
+
+### 질문은 최대 하나
+
+ASK_USER가 필요하면 질문은 최대 하나다.
+
+질문을 고르기 전에 다음을 모두 제외한다.
+- AGENT_CHECK 항목
+- SAFE_INFERENCE 항목
+- NON_BLOCKING_UNKNOWN 항목
+
+그러고도 BLOCKING_UNKNOWN이 여러 개 남으면, 잘못 추측했을 때 사용자가 실제로 원했을 것과 가장 크게 달라지는 항목 하나만 고른다.
+
+다음 기준으로 고르지 않는다.
+- 가장 기술적인 항목
+- 구현이 가장 어려운 항목
+- 목록에서 첫 번째로 나온 항목
+
+질문의 가치가 구현 편의보다 우선한다.
+
+### 형식
+
+짧게 유지한다. 값이 있는 항목만 보여주고, 빈 항목은 만들지 않는다. 모든 필드를 강제로 채우지 않는다. `templates/request-builder/`의 어휘(WHY·IMPORTANT·DO NOT CHANGE·DONE WHEN 등)를 참고해도 되지만, 8단계 템플릿 전체를 대화에 그대로 옮기지 않는다. 사용자의 평소 말투를 개발자 용어로 바꿔 쓰지 않는다.
+
+```
+제가 이렇게 이해했어요.
+
+원하는 것
+(이해한 내용, 한 문장)
+
+건드리지 말 것 (있을 때만)
+(사용자가 말했거나 요청 자체로 명백히 손대면 안 되는 부분)
+
+유지할 것 (있을 때만)
+(파일은 바뀌어도 계속 그대로 동작해야 하는 것)
+
+제가 추론한 것 (있을 때만)
+(추론이라고 분명히 표시)
+
+아직 정하지 않은 것 (있을 때만)
+(모르는 채로)
+
+Agent가 먼저 확인할 것 (있을 때만)
+(저장소·코드 사실 확인 항목)
+```
+
+건드리지 말 것과 유지할 것은 다르다. 건드리지 말 것은 손대면 안 되는 부분(예: 색상, 인증 로직) 자체이고, 유지할 것은 구현 파일이 바뀌어도 계속 그대로 동작해야 하는 기능(예: 로그인 제출 동작)이다. 필수 관련 수정으로 어떤 파일을 열어보거나 살짝 손보는 것과, 건드리지 말 것의 값·동작을 실제로 바꾸는 것을 같은 것으로 보지 않는다 — 후자만 금지한다. 값이 있을 때만 보여주는 다른 필드와 마찬가지로, 사용자가 말했거나 요청 자체로 명백할 때만 이 두 필드를 보여주고, 모든 요청에 습관적으로 채우지 않는다.
+
+실제 사용자 결정(BLOCKING_UNKNOWN)이 남아 있으면, 위 내용 뒤에 그 결정을 묻는 문장 하나만 덧붙인다. 이 문장 자체가 질문이다 — 쉬운 말을 쓰고, 실제 제품·사용자 결정을 묻고, 한 문장으로 답할 수 있게 하고, 기술 용어를 피하고, 필요할 때만 2~3개의 구체적인 선택지를 보여주고, 구현 방법이 아니라 결과로 설명한다.
+
+예시 형태(그대로 베끼지 않는다): "현재 분위기는 유지하면서 정리할까요, 아니면 전체적인 느낌까지 바꿔도 될까요?"
+
+나쁜 예: "CSS 아키텍처를 유지할까요?", "Grid와 Flex 중 어떤 방식이 좋으세요?" — 기술 용어이거나 구현 방식을 묻고 있다.
+
+실제 사용자 결정이 남아 있지 않으면 이 문장을 만들지 않는다. "이대로 진행해도 될까요?" 같은 일반적인 확인 문구를 결정 질문 대신, 또는 결정 질문에 이어 덧붙이지 않는다.
+
+질문 하나를 물은 뒤에는 같은 내용을 다른 말로 다시 확인하지 않는다. "결정 질문" 다음에 "이대로 진행해도 될까요?"를 잇는 것처럼, 같은 선택을 다른 표현으로 두 번 묻는 형태를 만들지 않는다.
+
+### 위험이 있는 요청
+
+`references/risk-level-guide.md`의 위험 어휘를 그대로 재사용한다. 결제, 로그인과 인증·권한, 데이터베이스 구조나 데이터 손실처럼 위험이 높은 영역과 관련된 요청은, 남은 불확실함이 실제 사용자·비즈니스 동작을 크게 바꿀 수 있을 때 ASK_USER 쪽으로 더 기울여 판단한다.
+
+새로운 위험 분류 체계를 따로 만들지 않는다. 결제·인증·데이터 관련 요청이라는 이유만으로 모든 요청에 자동으로 질문하지 않는다 — 위 두 가지 ASK_USER 조건은 그대로 적용되고, 위험은 경계선에서 Agent가 얼마나 신중해야 하는지에만 영향을 준다.
+
+### 한 번만 확인한다
+
+이 확인은 요청당 최대 한 번이다. 사용자가 승인하거나 고쳐 말하면 그 내용으로 바로 진행한다. 사용자의 답변에도 여전히 불확실함이 남으면 JuTell이 Intent Bridge를 다시 반복하지 않는다 — 그 지점부터는 평소 Agent의 판단과 질문 방식을 따른다. JuTell은 자체적으로 여러 번 되묻는 질문 엔진을 만들지 않는다.
+
+작업을 진행하는 도중 완료를 막는 새로운 사용자 결정이 나타났는데 이번 요청에서 이미 질문을 한 번 사용했다면, 같은 내용을 다른 말로 다시 묻지 않는다. 이때는 `확인 완료`로 마무리하지 않는다 — 보고서 상태를 `작업 보류`로 두고, 남은 결정 하나를 `사용자 결정 필요`로 짧게 설명한 뒤 사용자의 다음 답을 기다린다. 이것도 별도의 질문 엔진이 아니라 이 절의 한 번만 확인한다 규칙과 기존 보고서 상태를 그대로 적용한 것이다.
+
 ## 실행 절차
 
 1. 소유자 대상 구현·보고 작업이면 최종 답변을 작성하기 전에 JuTell 보고 규칙(`get_beginner_report_rules` 등)을 먼저 확인해 적용한다. 이 확인은 작업이 끝나갈 때, 최종 보고를 쓰기 직전 한 번만 한다. 파일을 읽거나 도구를 쓸 때마다, 또는 이미 끝난 작업을 다시 검증하려고 반복 확인하지 않는다. JuTell MCP를 사용할 수 있으면 이 확인을 MCP 도구 호출 한 번으로 처리하고 참고 문서를 여러 개 다시 읽지 않는다. MCP를 사용할 수 없으면 `references/report-format.md` 등 이 Skill의 참고 문서로 대신한다.
-2. 사용자 요청, 작업 유형, 허용 범위와 금지 범위를 확인한다.
-3. 코드 변경 작업이면 가능한 범위에서 작업 시작 기준 상태를 기록한다.
+2. 실제로 코드나 문서를 바꾸기 전에, 위 Intent Bridge 기준(AGENT_CHECK·SAFE_INFERENCE·NON_BLOCKING_UNKNOWN·BLOCKING_UNKNOWN·ASK_USER 다섯 가지 분류 포함)으로 이번 요청에 남은 불확실함을 정리한다. AGENT_CHECK 항목은 먼저 저장소·코드에서 직접 확인한다. `requestClarificationGuide`가 켜져 있고 그런 불확실함이 있으면 Intent Bridge 형식대로 이해한 내용을 짧게 보여준다. 이때 실제 사용자 결정(BLOCKING_UNKNOWN)이 남아 있으면 그 결정을 묻는 질문 하나만 받은 뒤 진행하고, SAFE_INFERENCE나 NON_BLOCKING_UNKNOWN만 남아 있으면 질문 없이 바로 진행한다. 불확실함이 전혀 없거나 `requestClarificationGuide`가 꺼져 있으면 평소처럼 바로 진행한다.
+3. 사용자 요청, 작업 유형, 허용 범위와 금지 범위를 확인한다. 이 구분은 `requestClarificationGuide` 설정이나 Intent Bridge 표시 여부와 관계없이 항상 적용한다 — 정밀한 요청처럼 Intent Bridge를 보여줄 필요가 없을 때도 조용히 적용되는 내부 판단이다.
+   * 직접 범위: 사용자가 실제로 요청한 변경 대상 그 자체. Intent Bridge의 "원하는 것"이 곧 직접 범위이며, 이를 별도의 "무엇을 바꿔도 되는지" 필드로 다시 만들지 않는다.
+   * 필수 관련 수정: 직접 범위를 올바르고 안전하고 일관되게 완료하기 위해 함께 손봐야 하는 부분. 예: 필드 하나를 없애면 그 필드를 참조하던 검증·테스트·안내 문구도 함께 정리한다. 같은 기능 영역 안에 머물고, 요청하지 않은 새 기능을 더하지 않고, 사용자가 이미 정한 것을 뒤집지 않는 한 필수 관련 수정은 따로 허락을 구하지 않고 진행한다. "한 줄만 고친다"로 좁게 해석해 안전한 완료에 필요한 관련 수정까지 막지 않는다.
+   * 건드리면 안 되는 부분: 사용자가 직접 말했거나("색상은 건드리지 마", "기능은 건드리지 마") 요청 자체로 명백히 손대면 안 되는 부분. 이 부분을 열어보거나 필수 관련 수정으로 훑어보는 것과, 실제로 그 값이나 동작을 바꾸는 것을 같은 것으로 보지 않는다 — 후자만 금지한다.
+   * 유지해야 할 동작: 구현 파일은 바뀌어도 계속 그대로 동작해야 하는 기능. 예: 화면을 다시 꾸며도 로그인 제출·검증 동작은 그대로 동작해야 한다. "파일을 건드렸다"를 "동작이 바뀌었다"와 같은 것으로 보지 않는다.
+   * 범위 밖: 이번 요청이 요구하지 않는 부분. Agent가 보기에 더 나은 개선이라도 사용자 허락 없이는 범위를 넓히지 않는다. 이번 요청 없이는 직접 범위를 안전하고 올바르게 완료할 수 없고, 그 답에 따라 결과가 크게 달라지거나 사용자 의도를 어길 위험이 있을 때만 위 Intent Bridge의 ASK_USER 판단 기준을 그대로 적용해 최대 한 번 묻는다 — 범위 전용 질문 체계를 새로 만들지 않는다. 그렇지 않으면 조용히 수행하지 않는다. 유용하면 최종 보고서에서 범위 밖 관찰이나 기존 다음 행동 제안(최대 3개)으로만 짧게 알리고, 건드리지 않았다는 사실 자체를 숨기지 않는다. 지금 요청을 그 개선 작업으로 바꾸지 않는다.
+4. 코드 변경 작업이면 가능한 범위에서 작업 시작 기준 상태를 기록한다.
    * Git 저장소와 브랜치
    * 기존 수정 파일과 추적되지 않은 파일
    * 실행 가능한 테스트·빌드·검사 명령
    * 브라우저 또는 실제 실행 가능 여부
-4. 기준 상태를 기록하지 못하면 기존 변경과 이번 변경을 임의로 섞지 않는다. Codex가 직접 수정한 사실이 명확한 파일만 이번 변경으로 표시하고 나머지는 출처 구분 불가로 표시한다.
-5. 실제 변경 파일과 내용을 확인한다. 파일명만으로 기능 역할이나 변경 의미를 확정하지 않는다.
-6. 주요 파일을 작업 규모에 맞게 선택한다. 단순 작업은 최대 3개, 일반 작업은 최대 5개를 우선 설명한다.
-7. 공식 문서나 프로젝트 설정에서 확인 가능한 검증 명령을 찾는다. 명령을 임의로 만들어 실행하지 않는다.
-8. 안전한 검증만 실행한다.
+5. 기준 상태를 기록하지 못하면 기존 변경과 이번 변경을 임의로 섞지 않는다. Codex가 직접 수정한 사실이 명확한 파일만 이번 변경으로 표시하고 나머지는 출처 구분 불가로 표시한다.
+6. 실제 변경 파일과 내용을 확인한다. 파일명만으로 기능 역할이나 변경 의미를 확정하지 않는다.
+7. 주요 파일을 작업 규모에 맞게 선택한다. 단순 작업은 최대 3개, 일반 작업은 최대 5개를 우선 설명한다.
+8. 공식 문서나 프로젝트 설정에서 확인 가능한 검증 명령을 찾는다. 명령을 임의로 만들어 실행하지 않는다.
+9. 안전한 검증만 실행한다.
    * 사용자가 실행을 금지한 명령은 실행하지 않는다.
    * 비밀정보를 출력할 가능성이 있는 명령은 실행하지 않는다.
    * 전체 환경변수, `.env`, 인증 헤더, 쿠키, 토큰, 연결 문자열을 그대로 출력하지 않는다.
    * 도구 출력과 오류 로그를 사용자에게 보여주기 전에 민감한 값을 제거한다.
    * 브라우저는 현재 Codex 환경에 이미 제공되고 사용자가 허용한 경우에만 선택적으로 사용한다.
-9. 검증 결과를 실제 실행 범위와 함께 기록한다. 실행하지 못한 검증을 통과했다고 쓰지 않는다.
-10. 네 가지 정보 체계를 분리한다.
+10. 무엇을 검증할지는 이번 요청 모양에 맞춘다. 확인 순서는 다음과 같다.
+   1. 원하는 것 — 사용자가 실제로 요청한 결과가 실제로 일어났는지. Intent Bridge의 "원하는 것"과 같다.
+   2. 건드리지 말 것·유지할 것 — 사용자가 말했거나 요청 자체로 명백한 보존 조건이 실제로 유지됐는지. 사용자가 이번 요청에서 완료 조건으로 직접 말한 것(예: "테스트까지 통과하게 해줘", "모바일에서 안 깨지는 것까지 확인해줘")도 여기 포함한다.
+   3. 위 변경과 직접 관련된 회귀 증거.
+   4. 위 세 가지로 설명되지 않는 추가 근거가 실제로 필요할 때만 그 이상을 확인한다.
+
+   프로젝트에 전체 테스트나 검증 수단이 있다는 이유만으로 이번 요청과 관계없는 검증까지 실행하지 않는다. README 오타 하나처럼 작은 작업은 diff 확인만으로 충분하고, 전화번호 입력 필드 제거처럼 검증·테스트와 실제로 연결된 작업은 관련 테스트까지 실행한다. 위 1·2번과 직접 관련된 테스트는 그 테스트가 실제로 그 결과나 보존 조건을 확인해줄 때 실행한다 — 프로젝트에 전체 테스트가 있는지 여부와 관계없다.
+
+   실제 화면 확인이 이번 요청의 결과나 완료 조건을 뒷받침하는 데 실제로 필요한 경우가 아니면 이 확인만을 위해 브라우저를 새로 켜지 않는다. 필요해서 확인하려는데 쓸 수 없으면 확인했다고 쓰지 않고 그 사실 그대로 기록한다. 이런 보조 확인 수단이 없다는 사실만으로 바로 `작업 보류`가 되지는 않는다 — 그 확인이 이번 요청의 완료 조건 자체였는지에 따라 달라진다.
+
+   사용자가 완료 조건을 따로 말하지 않았다면, Agent가 이번 요청 모양에 맞는 최소 검증을 스스로 정한다. 이는 추론(INFERRED)이며, 사용자가 말한 것(USER_SAID)으로 바꿔 쓰지 않는다. 이 구분이 사용자 이해에 실제로 중요할 때만 보고서에 드러내고, 매번 체크리스트로 보여주지 않는다.
+
+   이미 작업 중에 확보한 근거로 위 조건이 증명됐다면, 형식을 맞추려고 같은 파일을 다시 읽거나 같은 검증을 다시 실행하지 않는다.
+11. 검증 결과를 실제 실행 범위와 함께 기록한다. 실행하지 못한 검증을 통과했다고 쓰지 않는다. 확인하지 못한 것은 확인했다고 쓰지 않는다.
+12. 네 가지 정보 체계를 분리한다.
    * 근거 출처: 파일, Git, 명령, 브라우저 또는 실제 실행, 코드 예상, 사용자 제공 정보
    * 확인 상태: 확인됨, 일부 확인, 확인하지 못함
    * 사용자 행동: 사용자 확인 필요, 추가 테스트 권장, 설정 필요, 사용자 결정 필요
    * 보고서 상태: 확인 완료, 추가 확인 필요, 일부 확인, 작업 보류, 범위 밖
-11. 위험도는 변경 영향도를 기준으로 판단한다. 검증 도구가 없다는 이유만으로 위험도를 판정 불가로 만들지 않는다. 여러 조건이 겹치면 가장 높은 위험도를 적용한다.
-12. 필요한 용어만 처음 등장할 때 설명한다. 기술 전용 용어는 해당 기술이 사용되는 것을 확인한 경우에만 설명한다. 기본 사전에 없는 용어는 추측하지 않는다.
-13. 활성 Feature와 `references/report-format.md`에 따라 하나의 비개발자용 최종 보고를 작성한다. `explainedDiff`가 활성이면 의미 있는 변경에 같은 근거로 설명형 변경 요약을 덧붙인다. 중요한 코드 블록이 이미 작업 과정에서 확인되었고 사용자 이해에 실제 도움이 될 때만 1~2개까지 보여준다. 이 섹션만을 위해 파일을 다시 읽거나 git diff를 다시 실행하지 않는다. `explainedDiff`가 꺼져 있으면 Readable Code도 생략한다(사용자가 코드 설명을 명시한 경우만 예외).
-14. `requestBuilder`가 활성이고 사용자가 다음 AI에게 넘기기·세션 마무리·이어서 할 일 정리를 요청하면, 현재 작업에서 이미 아는 근거만으로 `다음 AI에게 전달하기` 블록을 만든다. Request Builder의 `NEXT_AGENT_HANDOFF` 템플릿 또는 세션 `SESSION_SUMMARY`를 재사용해도 된다. 저장소 재탐색, 테스트 재실행, 자동 전송, HTML/클라우드 산출물은 만들지 않는다.
-15. `nextActionSuggestions`가 활성일 때 보고서 끝에 다음 행동 제안을 **최대 3개**만 추가한다. 다음 경우에만 제안한다.
+13. `확인 완료`는 원하는 것이 실제로 일어났고, 사용자가 말한 건드리지 말 것·유지할 것·완료 조건이 실제로 유지됐다고 확인했을 때만 쓴다. 이 중 하나라도 확인하지 못했다면 `확인 완료` 대신 `추가 확인 필요`·`일부 확인`·`작업 보류` 중 이번 요청과 실제로 맞는 상태를 쓴다. 이 항목들은 `docs/BEGINNER_REPORT_SPEC.md`의 중요한 미확인 사항에 포함된다. 이번 요청과 직접 관련 없는 다른 미확인 사항 때문에 `확인 완료`를 막지는 않는다. 새로운 보고서 상태를 만들지 않고 위 다섯 가지 기존 상태만 사용한다.
+
+    관련 검증이 통과했다는 사실이 이 판단을 뒤집지 않는다 — 테스트는 실제로 다룬 범위만 증명한다. Agent가 이번 작업 중 이미 알게 된, 원하는 것의 실제 성공이나 보존·완료 조건의 실제 성립에 필수적인 미확인·실패가 있으면(예: 필드 제거로 외부 서비스 연결처럼 이미 중요한 미확인 사항으로 보는 항목에 새로 의존하게 됐는데 그 연결이 확인되지 않은 경우), 관련 테스트가 통과했더라도 `확인 완료`를 쓰지 않고 `위험과 사용자 확인`에 그 사실을 짧게 밝힌다. 완료에 필수적이지 않은 미확인 때문에 곧장 `작업 보류`로 가지 않는다 — 그런 경우는 기존 상태 우선순위를 따른다. 이것은 확인하지 않은 것을 확인했다고 말하는 허위 검증과는 다른 문제다 — 사실을 정직하게 보고했더라도 그 사실을 알면서 `확인 완료`를 고르면 그 자체가 성급한 완료다. JuTell은 이 판단이 실제로 맞는지 독립적으로 검증하거나 보장하지 않는다 — Agent가 실제로 아는 것을 근거로 정직하게 상태를 고르는지가 전부다.
+14. 위험도는 변경 영향도를 기준으로 판단한다. 검증 도구가 없다는 이유만으로 위험도를 판정 불가로 만들지 않는다. 여러 조건이 겹치면 가장 높은 위험도를 적용한다.
+15. 필요한 용어만 처음 등장할 때 설명한다. 기술 전용 용어는 해당 기술이 사용되는 것을 확인한 경우에만 설명한다. 기본 사전에 없는 용어는 추측하지 않는다.
+16. 활성 Feature와 `references/report-format.md`에 따라 하나의 비개발자용 최종 보고를 작성한다. `explainedDiff`가 활성이면 의미 있는 변경에 같은 근거로 설명형 변경 요약을 덧붙인다. 중요한 코드 블록이 이미 작업 과정에서 확인되었고 사용자 이해에 실제 도움이 될 때만 1~2개까지 보여준다. 이 섹션만을 위해 파일을 다시 읽거나 git diff를 다시 실행하지 않는다. `explainedDiff`가 꺼져 있으면 Readable Code도 생략한다(사용자가 코드 설명을 명시한 경우만 예외).
+17. `requestBuilder`가 활성이고 사용자가 다음 AI에게 넘기기·세션 마무리·이어서 할 일 정리를 요청하면, 현재 작업에서 이미 아는 근거만으로 `다음 AI에게 전달하기` 블록을 만든다. Request Builder의 `NEXT_AGENT_HANDOFF` 템플릿 또는 세션 `SESSION_SUMMARY`를 재사용해도 된다. 저장소 재탐색, 테스트 재실행, 자동 전송, HTML/클라우드 산출물은 만들지 않는다. 이번 작업에서 Intent Bridge로 승인받은 내용이 있으면 "지금 하던 일"에 그대로 재사용하고, 다시 확인하지 않는다.
+18. `nextActionSuggestions`가 활성일 때 보고서 끝에 다음 행동 제안을 **최대 3개**만 추가한다. 다음 경우에만 제안한다.
      * 사용자가 직접 확인해야 할 항목이 남은 경우
      * 검증되지 않아 보류된 항목이 있는 경우
      * 설정이 필요한 경우
      * 데이터 손실·보안 위험이 확인된 경우
      제안은 보고서에서 이미 확인된 항목 중에서만 고르고, 추측이나 새 작업을 제안하지 않는다. 해당하지 않으면 생략한다.
-16. 제출 전 다음을 점검한다.
+19. 제출 전 다음을 점검한다.
    * 화면 변화와 내부 변화를 분리했는가
    * 예상과 실제 확인을 구분했는가
    * 근거가 중요한 주장과 일치하는가
+   * 원하는 것과 사용자가 말한 건드리지 말 것·유지할 것·완료 조건을 실제로 확인했는가
    * 검증 결과와 보고서 상태가 일치하는가
    * 위험도 근거가 실제 변경과 일치하는가
    * 주요 파일 수를 지켰는가

package/assets/skill/references/report-format.md

@@ -11,6 +11,8 @@
 * 사용자 행동: 사용자 확인 필요, 추가 테스트 권장, 설정 필요, 사용자 결정 필요
 * 보고서 상태: 확인 완료, 추가 확인 필요, 일부 확인, 작업 보류, 범위 밖
 
+이번 요청이 실제로 원하는 결과를 만들어냈는지, 사용자가 말한 건드리지 말 것·유지할 것·완료 조건이 실제로 유지됐는지 확인하지 못했다면 `확인 완료`를 쓰지 않는다. 관련 검증이 통과했다는 사실만으로 이 판단을 대신하지 않는다 — 검증은 실제로 다룬 범위만 증명한다. 완료에 필수적인 미확인·실패를 이미 알고 있다면 `위험과 사용자 확인`에 짧게 밝히고 `확인 완료`가 아닌 실제로 맞는 상태를 쓴다.
+
 검증 결과는 별도로 표시한다.
 
 * 통과
@@ -22,6 +24,8 @@
 
 중요한 주장에는 가능한 경우 근거와 확인 상태를 함께 적는다. 코드만 보고 예상한 내용은 `근거: 코드 예상`과 `확인 상태: 확인하지 못함`으로 표시한다.
 
+이번 요청이 요구하지 않는 더 나은 개선을 발견해도 조용히 수행하지 않는다. 유용하면 수행하지 않고 다음 행동 제안(6.6)이나 범위 밖 관찰로 짧게만 언급하며, 건드리지 않았다는 사실 자체를 숨기지 않는다.
+
 ## 2. 단순 작업 보고
 
 문구, 색상, 작은 화면 배치처럼 위험이 낮은 작업에 사용한다.
@@ -53,6 +57,8 @@
 
 단순 작업은 기본 항목마다 1~2문장, 주요 파일 최대 3개, 전체 기본 12문장 또는 약 25줄을 우선한다. 안전 문제나 중요한 실패가 있으면 정확한 경고를 우선한다.
 
+완료에 필수적인 미확인·실패를 이미 알고 있으면, 형식을 위한 별도 항목을 만들지 않고 `위험과 사용자 확인`에 그 사실을 짧게 밝힌다(예: "외부 신원 인증 서비스 실제 연결은 확인하지 못했습니다"). 그런 사실이 있으면 `보고서 상태`에 `확인 완료`를 쓰지 않는다.
+
 ## 3. 일반 작업 보고
 
 기능 동작이 바뀌거나 여러 파일이 수정된 경우 사용한다.

package/assets/version.json

@@ -1,5 +1,5 @@
 {
-  "cli": "1.1.0",
+  "cli": "2.0.0",
   "skill": "확인 필요",
   "mcp": "0.1.0",
   "admin": "0.1.0"

package/dist/installer/agents.js

@@ -6,6 +6,7 @@ const managedBlock = `${JUTELL_AGENTS_BEGIN}
 ## JuTell
 
 - 코드 또는 문서 변경 후 \`.agents/skills/beginner-bridge/SKILL.md\`와 \`.jutell.json\`을 먼저 읽습니다. 소유자 대상 구현/보고 전에는 JuTell 보고 규칙을 먼저 적용해 최종 답변을 작성합니다.
+- 실제로 코드나 문서를 바꾸기 전에는, 요청에 결과를 크게 바꿀 수 있는 불확실함이 있는지 SKILL.md의 Intent Bridge 규칙으로 판단합니다. 불확실함이 없거나 \`requestClarificationGuide\`가 꺼져 있으면 평소처럼 바로 진행합니다.
 - JuTell MCP가 보이면 canonical \`jutell\` 서버를 사용합니다. \`jutell\`과 legacy \`beginner_bridge\`가 모두 보이면 \`jutell\`을 우선하고 \`beginner_bridge\`는 호환용으로만 사용합니다.
 - JuTell MCP를 사용할 수 있고 이미 확보한 근거로 보고·검증·핸드오프의 모호함을 줄여줄 때는 그 도구를 우선합니다. 사용할 수 없거나 Provider 정책으로 막혀 있으면 작업을 멈추지 않고 JuTell Skill로 계속합니다. 실제로 호출해 응답을 받은 경우에만 JuTell MCP를 사용했다고 말합니다.
 - 확인하지 않은 결과를 사실처럼 표현하지 않습니다.

package/dist/output/format.js

@@ -140,7 +140,7 @@ export function parseOptions(args) {
 }
 export function scopeLabel(scope) { return scope === 'global' ? '사용자 전역' : '현재 프로젝트'; }
 export function printHelp(io) {
-    io.write(`JuTell CLI 1.1.0
+    io.write(`JuTell CLI 2.0.0
 
 시작할 때는 jutell만 입력하면 됩니다.
 설치된 Coding Agent(Codex, OpenCode, Claude Code)를 찾아 연결하고,

package/dist/process/mcpProbe.js

@@ -6,7 +6,7 @@ const INITIALIZE = JSON.stringify({
     jsonrpc: '2.0',
     id: 1,
     method: 'initialize',
-    params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'jutell-doctor', version: '1.1.0' } },
+    params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'jutell-doctor', version: '2.0.0' } },
 });
 const INITIALIZED = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' });
 const TOOLS_LIST = JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jutell",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "JuTell by Ju0 — non-developer harness for AI coding agents (Skill, MCP, local dashboard)",
   "license": "MIT",
   "repository": {