claude-novice 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "novice",
+  "description": "비개발자 입문자용 Claude Code 학습 동반자 — 실제 개발 용어 보존, 안전 게이트, 외부 서비스 CLI 부트스트랩",
+  "owner": {
+    "name": "hjsh200219",
+    "url": "https://github.com/hjsh200219"
+  },
+  "plugins": [
+    {
+      "name": "novice",
+      "description": "비개발자 입문자를 위한 3단계 학습 동반자. 용어 설명 병기(fade), 파괴·시크릿·비용 안전 게이트, 2-tier CLI 부트스트랩(vercel/gh/supabase) + MCP·Chrome capability 라우터.",
+      "source": ".",
+      "category": "education",
+      "tags": [
+        "beginner",
+        "onboarding",
+        "korean",
+        "education",
+        "safety",
+        "vibe-coding",
+        "hooks"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "novice",
+  "version": "0.2.0",
+  "description": "비개발자 입문자를 위한 3단계 학습 동반자 — 실제 개발 용어 보존, 안전 게이트, 외부 서비스 CLI 부트스트랩",
+  "author": {
+    "name": "SHC"
+  },
+  "userConfig": {
+    "default_level": {
+      "type": "number",
+      "title": "기본 novice 레벨",
+      "description": "novice 기본 레벨 (1=최고 초보, 2=중간, 3=아키텍처 중심)",
+      "default": 1
+    },
+    "novice_enabled": {
+      "type": "boolean",
+      "title": "novice 활성화",
+      "description": "novice 학습 동반자 활성화 여부 (안전 게이트는 이 값과 무관하게 플러그인 활성 시 항상 동작)",
+      "default": true
+    }
+  }
+}

package/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# ARCHITECTURE
+
+novice는 Claude Code hook + skill + config 데이터로 구성된 학습 동반자 플러그인이다.
+런타임 코드는 hook 핸들러(stdin JSON → stdout JSON)이고, 동작 규칙은 config JSON에 데이터로 있다.
+
+## 레이어와 종속성 방향
+
+```
+config/*.json (데이터 SSOT)
+      ▲ (읽기 전용 소비)
+scripts/lib/*.js (순수 로직)
+      ▲ (import)
+scripts/*.js (hook 핸들러)        skills/*/SKILL.md (모델용 절차)
+      ▲
+tests/ (검증)
+```
+
+| 레이어 | 위치 | 역할 | 허용 import |
+|--------|------|------|-------------|
+| L1 config | `config/*.json`, `config/bootstrap-manifests/` | 동작 규칙 데이터 SSOT | (코드 아님) |
+| L2 lib | `scripts/lib/` | 순수 로직 | node 내장 + 같은 lib. **hook 핸들러 import 금지** |
+| L3 hook | `scripts/*.js` | hook 진입점 | `scripts/lib/`, node 내장 |
+| L4 skills | `skills/` | 모델용 절차 문서 | (문서) |
+| L5 tests | `tests/` | 검증 | 전부 |
+
+**종속성 규칙**: L2 lib는 L3 hook을 import하지 않는다(역방향 금지). hook은 lib를 통해서만 상태·검증에 접근한다. config는 코드가 읽는 데이터이며 코드를 참조하지 않는다. 상세 규칙: [docs/design-docs/layer-rules.md](./docs/design-docs/layer-rules.md).
+
+## lib 모듈 맵 (L2)
+| 모듈 | 책임 |
+|---|---|
+| `state.js` | 영속·세션 상태 단일 진입. atomic write, 0600, symlink 거부, project override / session state, mute(프로젝트 스코프) |
+| `hookio.js` | stdin/stdout 계약, emit 헬퍼, fail-open/fail-closed |
+| `secrets.js` | 시크릿 스캔·redaction (원문 미저장), 안전 규칙 로드 |
+| `grammar.js` | Bash·PowerShell 유한 grammar 토크나이저 + git subgrammar |
+| `capsule.js` | mode capsule·glossary·tombstone·fade 계산 |
+| `manifest.js` | bootstrap manifest 검증·로드 (Tier 1/2) |
+| `capability-router.js` | CLI→MCP→Chrome→guided manual 경로 결정·검증·다운그레이드 |
+| `fingerprint.js` | tool 호출 fingerprint (post-tool event 중복 제거) |
+| `safety.js` | PreToolUse 안전 분석 (rm·git·deploy·MCP 판정, grammar+secret 소비) |
+
+## hook 핸들러 맵 (L3)
+| hook | 파일 | 책임 |
+|---|---|---|
+| SessionStart | `session-start.js` | 상태 복구·capsule/glossary 주입 |
+| UserPromptSubmit | `user-prompt-submit.js` | 자연어 명령(mode/reset/mute), capsule 중복 방지 |
+| UserPromptExpansion | `user-prompt-expansion.js` | `/novice:mode` 처리 |
+| PreToolUse | `pre-tool-use.js` | 안전 게이트 (deny-only; 파괴 비가역·시크릿만 차단, 오류 시 fail-closed) |
+| PostToolUse | `post-tool-use.js` | 출력 redaction + event 기록 |
+| PostToolUseFailure | `post-tool-use-failure.js` | 실패 event 기록 |
+| PostToolBatch | `post-tool-batch.js` | batch 집계·개입 (single-writer) |
+| Stop | `stop.js` | 용어 카운터 |
+| SessionEnd | `session-end.js` | 세션 정리·TTL |
+| (라이브러리) | `bootstrap-engine.js` | setup-service 상태 머신 + capability 라우터 |
+
+## 교차 관심사
+- **상태**: 전부 `state.js` 경유, `CLAUDE_PLUGIN_DATA` 아래에만.
+- **안전**: pre-tool-use = fail-closed; 학습 hook = fail-open.
+- **시크릿**: `secrets.js`가 스캔·redaction, 원문은 로그·state·metric에 미기록.
+- **credential**: 플러그인이 값을 다루지 않음. bootstrap audit엔 메타데이터만.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHC (hjsh200219)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,372 @@
+# novice — 비개발자 입문자용 Claude Code 플러그인
+
+**한국어** · [English](#english)
+
+비개발자 입문자가 Claude Code로 바이브 코딩을 시작할 때 실제 개발 용어와 학습 기회를 보존하고,
+외부 서비스 CLI 설정을 안전한 범위에서 돕고, CLI 공포와 파괴·비용·시크릿 노출 위험을 줄이는
+3단계 학습 동반자 플러그인입니다.
+
+- 스펙: `docs/PRD.md` (revision 12)
+- 최소 지원 런타임: Claude Code `2.1.215`
+- 상태: MVP 구현 완료 — 테스트 147개 통과 (외부 dependency 0).
+  실제 2.1.215 runtime에서 hook payload 캡처 + `--plugin-dir` live E2E 검증 완료.
+  남은 것은 사람 참가자가 필요한 product beta 검증(concierge/moderated).
+
+## 설치
+
+Claude Code 안에서 marketplace를 등록한 뒤 설치합니다:
+
+```
+/plugin marketplace add hjsh200219/novice
+/plugin install novice@novice
+/reload-plugins
+```
+
+- 설치 확인: `/plugin` 목록에서 novice가 enabled인지 확인하고, `/novice`를 실행해
+  상태 대시보드가 나오면 정상입니다.
+- **업데이트**: 설치본은 캐시 복사본이라 자동 갱신되지 않습니다. `/plugin` 메뉴에서
+  novice marketplace를 update한 뒤 플러그인을 재설치하세요.
+- 로컬 개발·수정 테스트: 리포를 clone한 뒤 `claude --plugin-dir <리포 경로>`로
+  설치 없이 로드할 수 있습니다.
+- npm 채널: [`claude-novice`](https://www.npmjs.com/package/claude-novice) 패키지로도
+  배포됩니다. `npm install -g claude-novice` 후 `claude --plugin-dir "$(npm root -g)/claude-novice"`로
+  로드하거나, 자체 marketplace의 plugin `source`에 `{"source":"npm","package":"claude-novice"}`를
+  쓸 수 있습니다.
+- 제거: `/plugin uninstall novice` — 제거하면 안전 게이트도 함께 사라집니다
+  (아래 위협 모델 참조).
+
+## 사용법
+
+| 명령 | 동작 |
+|---|---|
+| `/novice` | front door — 현재 상태(레벨·학습층·안전 게이트·mute) 대시보드 + 하위 명령 안내 |
+| `/novice:mode` | 현재 level, 적용 범위, 안전 게이트 유지 여부 표시 |
+| `/novice:mode 1` | Level 1 (기본값) — 모든 용어에 설명 병기, 실행 전·후 해설 |
+| `/novice:mode 2` | Level 2 — 3회까지 설명, 핵심 결정만 해설 |
+| `/novice:mode 3` | Level 3 — 요청 시만 설명, 아키텍처·유저플로우 중심 |
+| `/novice:mode off` | novice 톤·설명·시각화 완전 제거 (안전 게이트는 유지) |
+
+### 자연어 명령
+
+프롬프트 **전체가 정확히** 아래 형태와 일치할 때만 동작합니다(앞뒤 공백·마침표만 허용).
+"더 쉽게 설명해 줘" 같은 일반 문장은 현재 답변에만 영향을 주고 설정을 바꾸지 않습니다.
+
+| 명령 | 동작 | 예시 |
+|---|---|---|
+| `novice 1` / `novice 2` / `novice 3` / `novice off` | 모드 전환 (`/novice:mode N`과 동일) | `novice 2` |
+| `novice reset all` | 모든 용어의 설명 카운터 초기화 (다시 처음부터 N회 설명) | `novice reset all` |
+| `novice reset <용어>` | 특정 용어만 카운터 초기화 | `novice reset commit` |
+| `novice mute <용어>` | 특정 용어를 **영구 제외** — 노출 횟수와 무관하게 설명 중단 | `novice mute commit` |
+| `novice unmute <용어>` | mute 해제 — 다시 fade 규칙에 따라 설명 | `novice unmute commit` |
+
+- **reset vs mute**: `reset`은 카운터를 0으로 되돌려 **다시** N회 설명하게 하고, `mute`는 지금 즉시 설명을 끊고 계속 끊어 둡니다.
+- **mute는 프로젝트 단위**로 저장되어 세션이 바뀌어도 유지됩니다. reset·용어 카운터는 세션 스코프입니다.
+- 용어(예: `commit`)는 한글 별칭(`커밋`)으로도 지정할 수 있고, 사전에 없는 용어는 무시됩니다.
+
+용어는 순화하지 않습니다. `commit(현재 변경을 하나의 저장 지점으로 기록하는 것)`처럼
+실제 용어 뒤에 설명을 병기하고, 세션에서 충분히 노출된 용어(Level 1 기준 3회)는 설명을 걷어냅니다.
+
+## 외부 서비스 CLI 부트스트랩 (2-tier)
+
+자동화 경계는 두 tier 모두 **탐지 → 설치 → 로그인 → 인증 상태 확인까지**입니다.
+
+- **Tier 1** (검토된 manifest: Vercel, GitHub CLI, Supabase): 고정 package coordinate로
+  표준 승인 흐름 실행. 설치와 로그인은 각각 1회씩 승인받습니다.
+- **Tier 2** (그 외 CLI): 공식 문서 URL·package coordinate·실행 argv를 화면에 그대로
+  제시하고, 사용자가 근거를 확인·승인한 경우에만 같은 engine으로 진행합니다.
+  공식 근거를 확인할 수 없으면 guided manual로 낮춥니다.
+
+리소스 생성·env/secret 값 입력·배포는 **사용자가 직접** 하거나 guided manual로 안내합니다.
+플러그인은 credential 값을 요청·보관·전달·자동입력하지 않습니다.
+secure 저장소를 지원하는 CLI(gh, supabase)가 plaintext fallback으로 떨어지는 환경에서는
+자동 로그인을 중단합니다. 파일 저장이 공식 기본 동작인 CLI(vercel)는 저장 위치와
+logout 경로를 로그인 승인 전에 고지합니다 — provider별 정책은 manifest의
+`credential_store`에 명시되어 있습니다.
+
+CLI 설치를 거부하거나 preflight가 실패하면 capability 라우터가
+**CLI → 공식/동의된 MCP → visible Chrome → guided manual** 순으로 경로를 낮춥니다.
+MCP는 두 경우에 쓰입니다 — (1) `mcp_allowlist`에 server·transport·publisher·tool·provenance가
+모두 일치하는 사전 검토 엔트리, 또는 (2) **사용자가 Claude에 이미 등록한 서버 + 이번 작업에
+명시적으로 동의**한 경우(동의한 tool 범위). 기본 allowlist는 비어 있어 등록·동의 없이는 자동
+실행되지 않고, MCP 서버를 자동 설치하지 않습니다. CLI도 Tier 1 검토 manifest 외에 **사용자가
+근거 확인 후 동의한 Tier 2 CLI**를 사용합니다. Chrome은 공식 Claude in Chrome 연결 시 visible
+mode로만 씁니다. 라우터는 경로 결정·검증·다운그레이드까지 하고, 실제 MCP tool 호출은 모델이(안전
+게이트가 계속 가드), Chrome 조작·최종 submit은 사용자가 합니다.
+
+## 안전 게이트 위협 모델
+
+안전 게이트는 **최소 deny-only 코어**입니다. 긍정적으로 식별한 파괴 비가역 작업과 노출된
+시크릿 값만 차단하고, 확인 질문(ask) 티어는 두지 않습니다. 파싱할 수 없거나 애매한 명령은
+판정하지 않고 **Claude Code 네이티브 권한 프롬프트**에 위임합니다.
+
+| 위협 | 동작 | 보증하지 않는 범위 |
+|---|---|---|
+| 로컬 파괴 명령 (`rm -rf ~`·`/`·프로젝트 루트, `dd`/`mkfs`/`shred`, PowerShell `Format-Volume`/`Clear-Disk`) | bare 명령을 파싱해 catastrophic이면 deny | 난독화, 파이프·체인·치환 낀 명령, 일반 폴더 삭제, 플러그인 밖 실행 |
+| Git history 파괴 (`push --force`) | protected branch 대상이면 deny | 비보호 branch force-push, `reset --hard`·`clean`(위임), 다른 Git client 작업 |
+| DB/원격 리소스 삭제 (CLI·MCP) | production/unknown 대상 파괴 작업 deny | staging/dev 대상(위임), 외부 콘솔 직접 작업 |
+| 시크릿 commit/deploy/명령줄 노출 | commit candidate tree·deploy 인자·명령줄 스캔 후 시크릿 값 발견 시 deny | 미지원 포맷, 암호화·난독화된 시크릿, 스캔 불가(대용량·exotic 옵션) |
+| 비용·반복 루프 | batch당 최대 1회 개입 안내 | 정확한 과금 계산, hard billing cap |
+
+### 명시적 비보증 (No silent security claims)
+
+- **범용 shell parser가 아닙니다.** bare 단일 command + argv만 유한 grammar로 파싱합니다.
+  pipe·리다이렉트·명령 치환·체인(`&&`·`;`) 등 미지원 문법은 **판정하지 않고 Claude Code
+  네이티브 권한에 위임**합니다. 이 위임 때문에 파이프 낀 파괴 명령(`rm -rf / ; …`)은 novice가
+  잡지 않을 수 있습니다 — 대신 CC 기본 권한 프롬프트가 처리합니다. (단, 명령줄에 노출된
+  시크릿 값은 문법과 무관하게 스캔·deny합니다.)
+- **확인 질문(ask) 티어가 없습니다.** 애매하면 묻지 않고 위임합니다 — benign 명령에 대한
+  false-prompt를 없애기 위한 설계입니다. 되돌리기 어려운 파괴/시크릿만 차단합니다.
+- **완전한 DLP·시크릿 관리자·악성 MCP 방어가 아닙니다.** 알려진 패턴 fixture 기준으로만 탐지합니다.
+  스캔할 수 없는 대상(대용량 파일·exotic git 옵션·unborn HEAD)은 차단하지 않고 위임합니다.
+- **timeout fail-open 한계:** Claude Code가 hook timeout·강제 종료를 non-blocking으로
+  처리하는 경우는 보증 범위 밖입니다. hook 내부 오류·잘못된 입력·입력 상한 초과만 deny(fail closed)합니다.
+- **플러그인을 disable/uninstall하면 안전 게이트도 사라집니다.** "always-on"은 플러그인이
+  활성화된 동안만 의미합니다. novice `off`는 학습층만 끄고 안전 게이트는 유지합니다.
+- **Git은 tracked 로컬 파일만 보호합니다.** untracked/ignored 파일, 외부 DB, 배포 리소스는
+  Git checkpoint로 복구되지 않습니다.
+
+## 상태와 privacy
+
+- 상태는 `${CLAUDE_PLUGIN_DATA}` 아래에만 저장합니다 (project override, 세션별 용어 카운터).
+  plugin root에는 쓰지 않습니다.
+- 상태 파일: atomic write, `0600`, symlink 거부, size cap. 세션 상태는 `/clear` 시 삭제, 30일 TTL.
+- secret scanner는 후보 바이트를 메모리에서만 검사하고 원문을 로그·state·metric에 남기지 않습니다.
+- bootstrap audit에는 service ID·manifest revision·단계·exit status만 저장합니다.
+- 원격 telemetry를 보내지 않습니다.
+
+## Release Notes
+
+### 0.2.0 (2026-07-21)
+- **안전 게이트를 deny-only 최소 코어로 전환** — 확인 질문(ask) 티어 제거. benign
+  파이프·체인 명령(`find … | sort && ls`)마다 뜨던 false-prompt 소멸. 파싱 불가·모호한
+  명령은 판정 없이 Claude Code 네이티브 권한에 위임.
+- deny 유지: `rm` 홈·루트·프로젝트 루트, `dd`/`mkfs`/`shred`·disk-format cmdlet,
+  protected branch force-push, production/unknown 파괴 MCP, commit/deploy/명령줄 시크릿 값.
+- `/novice` front door 명령 추가 — 상태 대시보드(레벨·학습층·안전 게이트·mute) + 하위 명령 안내.
+- commit/deploy 시크릿 스캔에 `tests/fixtures/` 경로 예외 — 플러그인이 자기 테스트
+  fixture에 자기 게이트로 걸리던 오탐 해소.
+- config 정리: 미사용 ask 잔재(`dangerous_tokens`·`git_rules` 등) 제거, 위임 의미를
+  `delegate` 값으로 명명. PRD rev 12, 테스트 147.
+
+### 0.1.0 (2026-07-20)
+- 최초 릴리스 — 3단계 학습 동반자(용어 병기·fade·mute), 파괴·시크릿·비용 안전 게이트,
+  2-tier CLI 부트스트랩(vercel/gh/supabase), MCP·Chrome capability 라우터. PRD rev 11.
+
+## 개발
+
+```bash
+npm test                  # 전체 (unit + integration)
+npm run test:unit
+npm run test:integration
+```
+
+외부 runtime dependency 없음 (Node >= 18, node:test). 테스트 구성: unit 11개 파일
+(config·state·mode·capsule·stop·grammar·secrets·batch·bootstrap·capability-router·output-style),
+integration 4개 파일 (hooks-contract·safety-corpus·safety-mutation·latency-benchmark).
+안전 gate는 mutation 하네스로도 검증합니다 — 위험 명령 35건을 106개 mutant로 변형해 detector
+우회가 없음을 확인합니다. latency 벤치는 blocking hook의 p95 예산(UserPromptSubmit ≤300ms,
+PreToolUse ≤250ms)을 회귀 테스트로 강제합니다(`NOVICE_BENCH_ITERS`로 반복 횟수 조정).
+
+`tests/fixtures/contract/`의 hook payload fixture는 Claude Code **2.1.215 실측 캡처**입니다
+(provenance 필드로 캡처/파생/문서 구분 — 상세는 해당 디렉토리 README).
+플러그인 자체도 같은 runtime에 `--plugin-dir`로 로드해 `/novice:mode` expansion →
+상태 갱신 → capsule 주입까지 live E2E로 확인했고, hook 실행 순서(expansion→submit)도 실측했습니다.
+
+코드로 검증 불가라 남는 항목: 실제 CLI 설치·로그인 E2E(사용자 환경·계정 필요),
+`/clear`·compact의 SessionStart source·MCP destructive payload 실측(headless 트리거 불가),
+product beta 지표(사람 참가자 필요).
+
+---
+
+<a name="english"></a>
+
+# novice — a beginner-friendly Claude Code plugin
+
+[한국어](#novice--비개발자-입문자용-claude-code-플러그인) · **English**
+
+A three-level learning companion plugin for non-developers starting out with Claude Code.
+It preserves real development terminology and learning opportunities, helps set up external
+service CLIs within a safe boundary, and reduces the fear of the CLI along with the risk of
+destructive commands, runaway cost, and secret exposure.
+
+- Spec: `docs/PRD.md` (revision 12)
+- Minimum supported runtime: Claude Code `2.1.215`
+- Status: MVP implemented — 147 tests passing (zero external
+  dependencies). Verified against a real 2.1.215 runtime via hook-payload capture and a
+  `--plugin-dir` live E2E. What remains is the product beta, which needs human participants.
+
+## Installation
+
+Register the marketplace inside Claude Code, then install:
+
+```
+/plugin marketplace add hjsh200219/novice
+/plugin install novice@novice
+/reload-plugins
+```
+
+- Verify: check that novice is enabled in `/plugin`, then run `/novice` — a status
+  dashboard means it's working.
+- **Updating**: the installed copy is a cached snapshot and does not auto-update. Update the
+  novice marketplace in the `/plugin` menu, then reinstall the plugin.
+- Local development: clone the repo and load it without installing via
+  `claude --plugin-dir <repo path>`.
+- npm channel: also published as [`claude-novice`](https://www.npmjs.com/package/claude-novice).
+  `npm install -g claude-novice` then `claude --plugin-dir "$(npm root -g)/claude-novice"`,
+  or point your own marketplace's plugin `source` at `{"source":"npm","package":"claude-novice"}`.
+- Uninstall: `/plugin uninstall novice` — removing the plugin also removes the safety gate
+  (see the threat model below).
+
+## Usage
+
+| Command | Behavior |
+|---|---|
+| `/novice:mode` | Show current level, scope, and whether the safety gate stays on |
+| `/novice:mode 1` | Level 1 (default) — explanation appended to every term, before/after narration |
+| `/novice:mode 2` | Level 2 — explain up to 3 times, narrate key decisions only |
+| `/novice:mode 3` | Level 3 — explain on request only, architecture/user-flow focused |
+| `/novice:mode off` | Fully remove novice tone/explanations/visualization (safety gate stays on) |
+
+### Natural-language commands
+
+These act only when the **entire prompt matches exactly** (leading/trailing whitespace and a
+trailing period are tolerated). A general sentence like "explain it more simply" affects only
+the current answer and does not change any setting.
+
+| Command | Behavior | Example |
+|---|---|---|
+| `novice 1` / `novice 2` / `novice 3` / `novice off` | Switch mode (same as `/novice:mode N`) | `novice 2` |
+| `novice reset all` | Reset every term's explanation counter (explain N times again) | `novice reset all` |
+| `novice reset <term>` | Reset one term's counter | `novice reset commit` |
+| `novice mute <term>` | **Permanently exclude** a term — explanation stops regardless of count | `novice mute commit` |
+| `novice unmute <term>` | Undo a mute — explanation resumes per the fade rule | `novice unmute commit` |
+
+- **reset vs mute**: `reset` restarts the counter from zero so the term is explained N more
+  times; `mute` stops the explanation right now and keeps it off.
+- **mute is stored per project**, so it persists across sessions. reset and the term counters
+  are session-scoped.
+- A term (e.g. `commit`) can be named by its Korean alias (`커밋`) too; unknown terms are ignored.
+
+Terms are never simplified away. It appends an explanation after the real term, as in
+`commit (recording the current changes as one save point)`, and once a term has appeared
+enough times in a session (3 times at Level 1) the explanation is dropped.
+
+## External service CLI bootstrap (2-tier)
+
+The automation boundary for both tiers is **detect → install → log in → verify auth**.
+
+- **Tier 1** (reviewed manifests: Vercel, GitHub CLI, Supabase): runs the standard approval
+  flow with fixed package coordinates. Install and login are each approved once.
+- **Tier 2** (any other CLI): the engine shows the official docs URL, package coordinate, and
+  the exact argv on screen, and proceeds through the same engine only after the user confirms
+  and approves the evidence. If no official provenance can be confirmed, it falls back to a
+  guided manual.
+
+Creating resources, entering env/secret values, and deploying are done by **the user
+directly** or guided manually. The plugin never requests, stores, forwards, or auto-fills
+credential values. For a CLI that supports secure storage (gh, supabase), auto-login is
+aborted when the environment falls back to plaintext. For a CLI whose documented default is
+file storage (vercel), the storage location and logout path are disclosed before the login is
+approved — the per-provider policy lives in each manifest's `credential_store`.
+
+If CLI install is refused or preflight fails, a capability router downgrades along
+**CLI → official/consented MCP → visible Chrome → guided manual**. MCP is used in two cases —
+(1) a pre-reviewed `mcp_allowlist` entry matching on server, transport, publisher, tools, and
+provenance, or (2) a server the **user has already registered in Claude plus explicit per-task
+consent** (limited to the consented tools). The default allowlist is empty, so nothing runs
+without registration + consent, and MCP servers are never auto-installed. CLI likewise accepts,
+beyond the Tier 1 reviewed manifests, a **Tier 2 CLI the user explicitly consents to after
+seeing the evidence**. Chrome is used in visible mode only when the official Claude in Chrome is
+connected. The router decides, validates, and downgrades — actual MCP tool calls are made by the
+model (still guarded by the safety gate), and Chrome actions / final submit are done by the user.
+
+## Safety gate threat model
+
+The safety gate is a **minimal, deny-only core**. It blocks only positively-identified,
+irreversible destructive actions and exposed secret values; there is no confirmation (ask) tier.
+Anything it cannot parse or is unsure about gets no opinion and is delegated to **Claude Code's
+native permission prompt**.
+
+| Threat | Behavior | Not guaranteed |
+|---|---|---|
+| Local destructive commands (`rm -rf ~`·`/`·project root, `dd`/`mkfs`/`shred`, PowerShell `Format-Volume`/`Clear-Disk`) | parse the bare command, deny if catastrophic | Obfuscation, piped/chained/substituted commands, deleting a normal folder, execution outside the plugin |
+| Git history destruction (`push --force`) | deny when the target is a protected branch | Force-push to an unprotected branch, `reset --hard`·`clean` (delegated), other Git clients |
+| DB / remote resource deletion (CLI·MCP) | deny destructive ops on production/unknown targets | staging/dev targets (delegated), actions in an external console |
+| Secret commit / deploy / command-line exposure | scan commit candidate tree, deploy args, and the command line; deny on a secret value | Unsupported formats, encrypted/obfuscated secrets, unscannable (oversize·exotic) |
+| Cost / retry loops | at most one intervention per batch | Exact billing, hard billing cap |
+
+### Explicit non-guarantees (No silent security claims)
+
+- **Not a general shell parser.** It parses only a single bare command + argv. Unsupported
+  syntax — pipes, redirects, command substitution, chains (`&&`·`;`) — gets **no opinion and is
+  delegated to Claude Code's native permission**. Because of this, a piped destructive command
+  (`rm -rf / ; …`) may not be caught by novice — Claude Code's own prompt handles it instead.
+  (A secret value on the command line is still scanned and denied regardless of grammar.)
+- **No confirmation (ask) tier.** When unsure it delegates rather than prompting — by design, to
+  eliminate false prompts on benign commands. Only hard-to-reverse destruction/secrets are blocked.
+- **Not a full DLP, secret manager, or malicious-MCP defense.** Detection is based only on
+  known-pattern fixtures. Unscannable targets (large files, exotic git options, unborn HEAD) are
+  delegated, not blocked.
+- **timeout fail-open limit:** cases where Claude Code treats a hook timeout / forced kill as
+  non-blocking are outside the guarantee. Internal hook errors, malformed input, and input-cap
+  overflow are denied (fail closed).
+- **Disabling/uninstalling the plugin removes the safety gate too.** "Always-on" only means
+  while the plugin is enabled. novice `off` turns off only the learning layer; the safety gate
+  stays on.
+- **Git protects tracked local files only.** Untracked/ignored files, external DBs, and deploy
+  resources are not recoverable via a Git checkpoint.
+
+## State and privacy
+
+- State is stored only under `${CLAUDE_PLUGIN_DATA}` (project override, per-session term
+  counters). Nothing is written to the plugin root.
+- State files: atomic write, `0600`, symlink refusal, size cap. Session state is deleted on
+  `/clear`, with a 30-day TTL.
+- The secret scanner inspects candidate bytes in memory only and never leaves the original in
+  logs/state/metrics.
+- The bootstrap audit stores only service ID, manifest revision, step, and exit status.
+- No remote telemetry is sent.
+
+## Release Notes
+
+### 0.2.0 (2026-07-21)
+- **Safety gate reduced to a deny-only minimal core** — the confirmation (ask) tier is gone;
+  false prompts on benign piped/chained commands are eliminated. Unparseable/ambiguous commands
+  are delegated to Claude Code's native permission prompt.
+- Still denied: `rm` of home/root/project root, `dd`/`mkfs`/`shred`/disk-format cmdlets,
+  protected-branch force-push, destructive MCP on production/unknown, secret values in
+  commits/deploys/command lines.
+- New `/novice` front-door command (status dashboard + subcommand guide).
+- `tests/fixtures/` excluded from the commit/deploy secret scan (the plugin no longer blocks
+  committing its own test corpus). Config cleanup, PRD rev 12, 147 tests.
+
+### 0.1.0 (2026-07-20)
+- Initial release — 3-level learning companion (term annotation·fade·mute), safety gate,
+  2-tier CLI bootstrap (vercel/gh/supabase), MCP·Chrome capability router. PRD rev 11.
+
+## Development
+
+```bash
+npm test                  # everything (unit + integration)
+npm run test:unit
+npm run test:integration
+```
+
+No external runtime dependencies (Node >= 18, node:test). Test layout: 11 unit files
+(config·state·mode·capsule·stop·grammar·secrets·batch·bootstrap·capability-router·output-style),
+4 integration files (hooks-contract·safety-corpus·safety-mutation·latency-benchmark). The safety
+gate is also checked by a mutation harness — it mutates 35 dangerous commands into 106 mutants
+and confirms the detector is never bypassed. The latency benchmark enforces the blocking-hook p95
+budget (UserPromptSubmit ≤300ms, PreToolUse ≤250ms) as a regression test (tune iterations with
+`NOVICE_BENCH_ITERS`).
+
+The hook-payload fixtures in `tests/fixtures/contract/` are **real Claude Code 2.1.215
+captures** (the `provenance` field distinguishes captured/derived/documented — see that
+directory's README). The plugin itself was also loaded on the same runtime via `--plugin-dir`
+and confirmed end to end: `/novice:mode` expansion → state update → capsule injection, and the
+hook execution order (expansion→submit) was captured too.
+
+What cannot be verified in code (documented as such): real CLI install/login E2E (needs the
+user's environment and accounts), real captures of the `/clear`/compact SessionStart source and
+the MCP destructive payload (cannot be triggered headlessly), and the product-beta metrics
+(need human participants).

package/config/bootstrap-manifests/github-cli.json

@@ -0,0 +1,80 @@
+{
+  "schema_version": 1,
+  "manifest_revision": 1,
+  "reviewed_at": "2026-07-20",
+  "tier": 1,
+  "service_id": "github",
+  "binary": "gh",
+  "docs_url": "https://cli.github.com/manual/gh_auth_login",
+  "installers": [
+    {
+      "os": ["darwin"],
+      "package_manager": "homebrew",
+      "package_coordinate": "gh",
+      "argv": ["brew", "install", "gh"],
+      "min_version": "2.40.0",
+      "global_changes": ["Homebrew Cellar에 gh 설치"]
+    },
+    {
+      "os": ["linux"],
+      "package_manager": "apt",
+      "package_coordinate": "gh",
+      "argv": ["sudo", "apt-get", "install", "-y", "gh"],
+      "min_version": "2.40.0",
+      "global_changes": ["시스템 패키지로 gh 설치"]
+    },
+    {
+      "os": ["win32"],
+      "package_manager": "winget",
+      "package_coordinate": "GitHub.cli",
+      "argv": ["winget", "install", "--id", "GitHub.cli", "--exact"],
+      "min_version": "2.40.0",
+      "global_changes": ["시스템에 GitHub CLI 설치"]
+    }
+  ],
+  "detect": {
+    "argv": ["gh", "--version"],
+    "success": { "exit_code": 0 }
+  },
+  "version_check": {
+    "argv": ["gh", "--version"],
+    "success": { "exit_code": 0, "stdout_regex": "gh version \\d+\\.\\d+\\.\\d+" }
+  },
+  "auth_status": {
+    "argv": ["gh", "auth", "status"],
+    "success": { "exit_code": 0 },
+    "unauthenticated": { "exit_code_not": 0 }
+  },
+  "login": {
+    "argv": ["gh", "auth", "login", "--web"],
+    "interactive": true,
+    "user_completes": ["브라우저 device flow 인증 코드 입력"],
+    "success_verify": "auth_status"
+  },
+  "logout": {
+    "argv": ["gh", "auth", "logout"]
+  },
+  "credential_store": {
+    "storage": "OS keychain (macOS Keychain, Windows Credential Manager, libsecret) 우선",
+    "secure_storage": true,
+    "plaintext_fallback": true,
+    "plaintext_fallback_location": "~/.config/gh/hosts.yml",
+    "abort_auto_login_on_plaintext": true,
+    "abort_note": "keychain을 쓸 수 없어 hosts.yml plaintext로 떨어지는 환경이면 자동 로그인을 중단하고 위치·위험·logout 경로를 안내한다.",
+    "disclosure": "인증 토큰은 기본적으로 OS keychain에 저장된다. keychain이 없으면 ~/.config/gh/hosts.yml에 평문 저장될 수 있다."
+  },
+  "uninstall": {
+    "homebrew": ["brew", "uninstall", "gh"],
+    "apt": ["sudo", "apt-get", "remove", "-y", "gh"],
+    "winget": ["winget", "uninstall", "--id", "GitHub.cli"]
+  },
+  "side_effects": [
+    "전역 패키지 추가",
+    "~/.config/gh 설정 디렉토리 생성",
+    "OS keychain에 인증 항목 추가"
+  ],
+  "noninteractive_policy": {
+    "login": "deny",
+    "reason": "gh auth login 대화형 흐름은 비대화형 환경에서 실행하지 않는다. GH_TOKEN 환경변수 사용법을 guided manual로 안내한다"
+  }
+}

package/config/bootstrap-manifests/supabase.json

@@ -0,0 +1,71 @@
+{
+  "schema_version": 1,
+  "manifest_revision": 1,
+  "reviewed_at": "2026-07-20",
+  "tier": 1,
+  "service_id": "supabase",
+  "binary": "supabase",
+  "docs_url": "https://supabase.com/docs/reference/cli/install",
+  "installers": [
+    {
+      "os": ["darwin", "linux"],
+      "package_manager": "homebrew",
+      "package_coordinate": "supabase/tap/supabase",
+      "argv": ["brew", "install", "supabase/tap/supabase"],
+      "min_version": "1.200.0",
+      "global_changes": ["Homebrew tap 추가 및 supabase 설치"]
+    },
+    {
+      "os": ["win32"],
+      "package_manager": "scoop",
+      "package_coordinate": "supabase",
+      "argv": ["scoop", "install", "supabase"],
+      "min_version": "1.200.0",
+      "global_changes": ["scoop bucket에서 supabase 설치"]
+    }
+  ],
+  "detect": {
+    "argv": ["supabase", "--version"],
+    "success": { "exit_code": 0 }
+  },
+  "version_check": {
+    "argv": ["supabase", "--version"],
+    "success": { "exit_code": 0, "stdout_regex": "\\d+\\.\\d+\\.\\d+" }
+  },
+  "auth_status": {
+    "argv": ["supabase", "projects", "list"],
+    "success": { "exit_code": 0 },
+    "unauthenticated": { "exit_code_not": 0 }
+  },
+  "login": {
+    "argv": ["supabase", "login"],
+    "interactive": true,
+    "user_completes": ["브라우저에서 access token 발급·확인"],
+    "success_verify": "auth_status"
+  },
+  "logout": {
+    "argv": ["supabase", "logout"]
+  },
+  "credential_store": {
+    "storage": "OS native credential storage (macOS Keychain 등) 우선",
+    "secure_storage": true,
+    "plaintext_fallback": true,
+    "plaintext_fallback_location": "~/.supabase/access-token",
+    "abort_auto_login_on_plaintext": true,
+    "abort_note": "native credential storage가 없어 plaintext 파일로 떨어지면 자동 로그인을 중단하고 위치·삭제 방법을 안내한다.",
+    "disclosure": "access token은 기본적으로 OS 보안 저장소에 저장된다. 미지원 환경에서는 ~/.supabase 아래 평문 저장될 수 있다."
+  },
+  "uninstall": {
+    "homebrew": ["brew", "uninstall", "supabase"],
+    "scoop": ["scoop", "uninstall", "supabase"]
+  },
+  "side_effects": [
+    "전역 패키지 추가",
+    "~/.supabase 설정 디렉토리 생성 가능",
+    "OS keychain에 access token 항목 추가"
+  ],
+  "noninteractive_policy": {
+    "login": "guided_manual",
+    "reason": "supabase login은 브라우저 토큰 발급이 필요하다. 비대화형 환경에서는 SUPABASE_ACCESS_TOKEN 환경변수 설정을 사용자가 직접 하도록 안내한다"
+  }
+}