claude-novice 0.2.0

package/scripts/stop.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Stop: incrementally count canonical "용어(설명)" exposures in the final assistant
+// message and update the per-session fade counters. Defensive by contract:
+// missing last_assistant_message or stop_hook_active=true leaves counters untouched,
+// and a repeated Stop for the same message (same hash) is a no-op.
+// Learning hook: fail open (exit 0, no output) on any internal error.
+import crypto from 'node:crypto';
+import { readStdinJson, failOpen } from './lib/hookio.js';
+import { loadSession, saveSession } from './lib/state.js';
+import { loadTerms } from './lib/capsule.js';
+
+function stripCode(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Canonical exposure: the real term immediately followed by "(" + a parenthetical
+// that begins with the first characters of the canonical explanation. This shape is
+// generated by the novice glossary rule, so bare mentions and user quotes don't count.
+function countsInMessage(message, terms) {
+  const text = stripCode(message);
+  const counted = [];
+  for (const t of terms) {
+    const prefix = t.explanation.slice(0, 6);
+    const gloss = (t.aliases || []).find((a) => /[가-힣]/.test(a));
+    const pattern = new RegExp(
+      `${escapeRegExp(t.term)}\\s?\\((?:${escapeRegExp(gloss ?? '')}[:：]?\\s*)?${escapeRegExp(prefix)}`,
+      'i',
+    );
+    if (pattern.test(text)) counted.push(t.term);
+  }
+  return counted;
+}
+
+function main() {
+  const input = readStdinJson();
+  if (input.stop_hook_active === true) return;
+  const message = input.last_assistant_message;
+  if (typeof message !== 'string' || message === '') return;
+  const sessionId = input.session_id;
+  if (typeof sessionId !== 'string' || sessionId === '') return;
+
+  const hash = crypto.createHash('sha256').update(message).digest('hex');
+  const session = loadSession(sessionId);
+  if (session.last_message_hash === hash) return;
+  session.last_message_hash = hash;
+
+  const counted = countsInMessage(message, loadTerms().terms);
+  for (const term of counted) {
+    session.term_counts[term] = (session.term_counts[term] ?? 0) + 1;
+    // A reset term that gets explained again starts a fresh fade cycle.
+    if (Array.isArray(session.reset_terms) && session.reset_terms.includes(term)) {
+      session.reset_terms = session.reset_terms.filter((x) => x !== term);
+    }
+  }
+  saveSession(sessionId, session);
+}
+
+try {
+  main();
+  process.exit(0);
+} catch {
+  failOpen();
+}

package/scripts/user-prompt-expansion.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// UserPromptExpansion: deterministic handler for the /novice:mode slash command.
+// Valid args update project state and inject the fresh capsule (or OFF tombstone).
+// Invalid args block the expansion (state untouched) and show the allowed values.
+// Empty args are a read-only status query.
+// Learning hook: fail open (exit 0, no output) on any internal error.
+import { readStdinJson, emitAdditionalContext, emitBlock, failOpen } from './lib/hookio.js';
+import { getProjectConfig, setProjectMode, loadSession, saveSession } from './lib/state.js';
+// setProjectMode preserves muted_terms; re-read via getProjectConfig for the capsule.
+import { buildTombstone, capsuleForState } from './lib/capsule.js';
+
+const VALID_ARGS = new Set(['1', '2', '3', 'off']);
+
+function statusText(config) {
+  const state = config.enabled ? `Level ${config.level}` : 'off';
+  return [
+    `[novice 상태] 현재 mode: ${state}`,
+    '적용 범위: 현재 프로젝트 (프로젝트별로 저장된다)',
+    '안전 게이트: novice off와 무관하게 플러그인이 활성화된 동안 항상 유지된다.',
+    '전환: /novice:mode 1|2|3|off',
+  ].join('\n');
+}
+
+function main() {
+  const input = readStdinJson();
+  if (input.command_name !== 'novice:mode') return;
+
+  const sessionId = input.session_id;
+  const cwd = input.cwd || process.cwd();
+  const args = String(input.command_args ?? '').trim();
+
+  // Status query — read-only.
+  if (args === '') {
+    emitAdditionalContext('UserPromptExpansion', statusText(getProjectConfig(cwd)));
+    return;
+  }
+
+  if (!VALID_ARGS.has(args)) {
+    emitBlock('사용할 수 있는 값: /novice:mode 1|2|3|off — 예: /novice:mode 2');
+    return;
+  }
+
+  const next = setProjectMode(cwd, args);
+  if (typeof sessionId !== 'string' || sessionId === '') return;
+
+  const session = loadSession(sessionId);
+  if (args === 'off') {
+    emitAdditionalContext('UserPromptExpansion', buildTombstone());
+    session.off_tombstone_emitted = true;
+    session.capsule_revision = null;
+  } else {
+    const { revision, capsule } = capsuleForState(next.level, session, next.muted_terms || []);
+    emitAdditionalContext('UserPromptExpansion', capsule);
+    session.capsule_revision = revision;
+    session.off_tombstone_emitted = false;
+  }
+  session.skip_next_submit = false;
+  saveSession(sessionId, session);
+}
+
+try {
+  main();
+  process.exit(0);
+} catch {
+  failOpen();
+}

package/scripts/user-prompt-submit.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// UserPromptSubmit: natural-language mode switching, persistent reset, and duplicate-capsule
+// suppression. Exact /novice:mode slash prompts are handed to UserPromptExpansion (we emit
+// nothing so old and new capsules never coexist in one turn).
+// Learning hook: fail open (exit 0, no output) on any internal error.
+import { readStdinJson, emitAdditionalContext, failOpen } from './lib/hookio.js';
+import { getProjectConfig, setProjectMode, muteProjectTerm, unmuteProjectTerm, loadSession, saveSession } from './lib/state.js';
+import { loadTerms, buildTombstone, capsuleForState } from './lib/capsule.js';
+
+const SLASH_MODE = /^\/novice:mode(\s[\s\S]*)?$/;
+const RESET_ALL = 'novice reset all';
+const RESET_ONE = /^novice reset (.+)$/;
+const MUTE_ONE = /^novice mute (.+)$/;
+const UNMUTE_ONE = /^novice unmute (.+)$/;
+const MODE_ALIAS = { 'novice 1': '1', 'novice 2': '2', 'novice 3': '3', 'novice off': 'off' };
+
+// trim → strip ONE trailing period (ASCII '.' or Korean '。') → collapse internal whitespace.
+function normalizeForAlias(prompt) {
+  let s = String(prompt ?? '').trim();
+  s = s.replace(/[.。]$/, '');
+  s = s.replace(/\s+/g, ' ').trim();
+  return s;
+}
+
+// Resolve a term name or alias (case-insensitive) to its canonical term name.
+function resolveTerm(raw) {
+  const key = String(raw).trim().toLowerCase();
+  for (const t of loadTerms().terms) {
+    if (t.term.toLowerCase() === key) return t.term;
+    if ((t.aliases || []).some((a) => a.toLowerCase() === key)) return t.term;
+  }
+  return null;
+}
+
+// Emit the current capsule (enabled) or nothing, honoring the skip_next_submit handshake.
+function emitCurrentOrSkip(sessionId, config, session) {
+  if (config.enabled) {
+    const { revision, capsule } = capsuleForState(config.level, session, config.muted_terms);
+    if (session.skip_next_submit === true && revision === session.capsule_revision) {
+      session.skip_next_submit = false;
+      saveSession(sessionId, session);
+      return;
+    }
+    emitAdditionalContext('UserPromptSubmit', capsule);
+    session.capsule_revision = revision;
+    session.skip_next_submit = false;
+    saveSession(sessionId, session);
+    return;
+  }
+  // Disabled: one-shot tombstone if capsules were injected earlier this session.
+  if (session.off_tombstone_emitted !== true && session.capsule_revision != null) {
+    emitAdditionalContext('UserPromptSubmit', buildTombstone());
+    session.off_tombstone_emitted = true;
+    session.capsule_revision = null;
+    session.skip_next_submit = false;
+    saveSession(sessionId, session);
+  }
+}
+
+// Apply a mode change the same way the slash/expansion path does, then inject fresh state.
+function applyModeChange(sessionId, cwd, session, mode) {
+  const next = setProjectMode(cwd, mode);
+  if (mode === 'off') {
+    emitAdditionalContext('UserPromptSubmit', buildTombstone());
+    session.off_tombstone_emitted = true;
+    session.capsule_revision = null;
+    session.skip_next_submit = false;
+    saveSession(sessionId, session);
+    return;
+  }
+  const { revision, capsule } = capsuleForState(next.level, session, next.muted_terms || []);
+  emitAdditionalContext('UserPromptSubmit', capsule);
+  session.capsule_revision = revision;
+  session.off_tombstone_emitted = false;
+  session.skip_next_submit = false;
+  saveSession(sessionId, session);
+}
+
+function main() {
+  const input = readStdinJson();
+  const sessionId = input.session_id;
+  const cwd = input.cwd || process.cwd();
+  if (typeof sessionId !== 'string' || sessionId === '') return;
+
+  const rawTrimmed = String(input.prompt ?? '').trim();
+
+  // (b) Exact slash command → expansion owns this turn.
+  if (SLASH_MODE.test(rawTrimmed)) return;
+
+  const session = loadSession(sessionId);
+  const normalized = normalizeForAlias(input.prompt);
+  const key = normalized.toLowerCase();
+
+  // (c) Natural-language mode aliases → same writer as the slash path.
+  if (Object.prototype.hasOwnProperty.call(MODE_ALIAS, key)) {
+    applyModeChange(sessionId, cwd, session, MODE_ALIAS[key]);
+    return;
+  }
+
+  // (c) Persistent reset — reset all.
+  if (key === RESET_ALL) {
+    session.term_counts = {};
+    session.reset_terms = [];
+    saveSession(sessionId, session);
+    emitCurrentOrSkip(sessionId, getProjectConfig(cwd), session);
+    return;
+  }
+
+  // (c) Persistent reset — reset one term (only when it resolves to a known term/alias).
+  const one = key.match(RESET_ONE);
+  if (one) {
+    const term = resolveTerm(one[1]);
+    if (term) {
+      if (session.term_counts) delete session.term_counts[term];
+      const rs = new Set(session.reset_terms || []);
+      rs.add(term);
+      session.reset_terms = [...rs];
+      saveSession(sessionId, session);
+      emitCurrentOrSkip(sessionId, getProjectConfig(cwd), session);
+      return;
+    }
+    // Unknown target → treat as an ordinary prompt (fall through).
+  }
+
+  // (c) Mute one term — force-fade it permanently across sessions (project-scoped).
+  const mute = key.match(MUTE_ONE);
+  if (mute) {
+    const term = resolveTerm(mute[1]);
+    if (term) {
+      muteProjectTerm(cwd, term);
+      emitCurrentOrSkip(sessionId, getProjectConfig(cwd), session);
+      return;
+    }
+    // Unknown target → treat as an ordinary prompt (fall through).
+  }
+
+  // (c) Unmute one term — undo a previous mute (explanations resume per the fade rule).
+  const unmute = key.match(UNMUTE_ONE);
+  if (unmute) {
+    const term = resolveTerm(unmute[1]);
+    if (term) {
+      unmuteProjectTerm(cwd, term);
+      emitCurrentOrSkip(sessionId, getProjectConfig(cwd), session);
+      return;
+    }
+    // Unknown target → treat as an ordinary prompt (fall through).
+  }
+
+  // (d)/(e) Ordinary prompt.
+  emitCurrentOrSkip(sessionId, getProjectConfig(cwd), session);
+}
+
+try {
+  main();
+  process.exit(0);
+} catch {
+  failOpen();
+}

package/scripts/verify-docs.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// verify-docs: 문서-코드 일치 + 레이어 종속성 정적 검사.
+// ESLint 대체(zero-dep 원칙). 실패 시 exit 1. pretest에 연결되어 매 테스트 전 실행된다.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const errors = [];
+const ok = (cond, msg) => { if (!cond) errors.push(msg); };
+const read = (p) => fs.readFileSync(path.join(root, p), 'utf8');
+const exists = (p) => fs.existsSync(path.join(root, p));
+
+// 모든 import/export 지정자 수집 (static·side-effect·re-export·dynamic 전부).
+function collectSpecifiers(src) {
+  const specs = [];
+  for (const re of [
+    /(?:^|\n)\s*import\s[^;]*?from\s*['"]([^'"]+)['"]/g, // import x from 'y'
+    /(?:^|\n)\s*import\s*['"]([^'"]+)['"]/g, // import 'y' (side-effect)
+    /(?:^|\n)\s*export\s[^;]*?from\s*['"]([^'"]+)['"]/g, // export … from 'y'
+    /import\(\s*['"]([^'"]+)['"]\s*\)/g, // import('y') (dynamic)
+  ]) {
+    for (const m of src.matchAll(re)) specs.push(m[1]);
+  }
+  return specs;
+}
+
+// 1) AGENTS.md가 참조하는 상대 경로가 실존하는지 (http·앵커 제외, ./ 유무 무관).
+const agents = read('AGENTS.md');
+for (const m of agents.matchAll(/\]\((?!https?:)([^)]+)\)/g)) {
+  const target = m[1].split('#')[0].replace(/^\.\//, '');
+  if (target) ok(exists(target), `AGENTS.md가 참조하는 경로가 없음: ${target}`);
+}
+
+// 2) CLAUDE.md는 @AGENTS.md 참조여야 함 (SSOT 정규화).
+ok(read('CLAUDE.md').trim() === '@AGENTS.md', 'CLAUDE.md는 "@AGENTS.md" 참조여야 함');
+
+// 3) plugin.json은 hooks 키를 넣지 않는다 (중복 로드 실패 방지).
+const plugin = JSON.parse(read('.claude-plugin/plugin.json'));
+ok(!('hooks' in plugin), 'plugin.json에 hooks 키가 있으면 중복 로드 실패 — 제거하세요');
+for (const [, v] of Object.entries(plugin.userConfig ?? {})) {
+  ok(typeof v.title === 'string', 'userConfig 항목에 title 필수');
+}
+
+// 4a) 레이어 규칙: scripts/lib/*.js(L2)는 node 내장 또는 같은 lib만 import.
+const libDir = path.join(root, 'scripts', 'lib');
+for (const f of fs.readdirSync(libDir).filter((x) => x.endsWith('.js'))) {
+  for (const spec of collectSpecifiers(fs.readFileSync(path.join(libDir, f), 'utf8'))) {
+    const isNode = spec.startsWith('node:');
+    // 같은 lib 디렉토리: "./name.js" (./ 이후에 추가 경로 구분자 없음).
+    const isSameLib = spec.startsWith('./') && !spec.slice(2).includes('/');
+    ok(isNode || isSameLib, `레이어 위반: scripts/lib/${f} 가 '${spec}' import (lib는 node 내장 또는 같은 lib만 허용)`);
+  }
+}
+
+// 4b) 레이어 규칙: scripts/*.js(L3 hook)는 node 내장 또는 ./lib/*만 import (hook→hook 금지).
+const scriptsDir = path.join(root, 'scripts');
+for (const f of fs.readdirSync(scriptsDir).filter((x) => x.endsWith('.js'))) {
+  for (const spec of collectSpecifiers(fs.readFileSync(path.join(scriptsDir, f), 'utf8'))) {
+    const isNode = spec.startsWith('node:');
+    const isLib = spec.startsWith('./lib/');
+    ok(isNode || isLib, `레이어 위반: scripts/${f} 가 '${spec}' import (hook은 node 내장 또는 ./lib/*만 허용 — hook→hook·외부 금지)`);
+  }
+}
+
+// 5) 문서 수치 일치: config/terms.json 용어 수 == 문서 표기(32).
+const terms = JSON.parse(read('config/terms.json')).terms.length;
+ok(terms === 32, `terms.json 용어 수 ${terms} != 문서 표기 32`);
+
+// 6) bootstrap manifest 3종 실존 (service-capabilities 참조와 일치).
+const caps = JSON.parse(read('config/service-capabilities.json'));
+for (const svc of Object.values(caps.services ?? {})) {
+  ok(exists(path.join('config', svc.manifest)), `manifest 없음: ${svc.manifest}`);
+}
+
+// 7) docs/harness 필수 5종 존재.
+for (const f of ['principles.md', 'maturity-framework.md', 'fix-catalog.md', 'gc-history.md', 'harness-setup.md']) {
+  ok(exists(path.join('docs', 'harness', f)), `docs/harness/${f} 누락`);
+}
+
+// 8) lib 레지스트리 일치: 실제 scripts/lib/*.js 모듈이 전부 ARCHITECTURE.md 모듈맵에 등재됐는지
+//    (Search Before Building — 레지스트리 drift 방지). *.mjs·helper 제외.
+const arch = read('ARCHITECTURE.md');
+for (const f of fs.readdirSync(path.join(root, 'scripts', 'lib')).filter((x) => x.endsWith('.js'))) {
+  const mod = f.replace(/\.js$/, '');
+  ok(arch.includes(`\`${mod}.js\``), `ARCHITECTURE.md lib 모듈맵에 scripts/lib/${f} 누락 (레지스트리 drift)`);
+}
+
+if (errors.length) {
+  console.error('verify-docs FAILED:\n' + errors.map((e) => `  ✗ ${e}`).join('\n'));
+  process.exit(1);
+}
+console.log('verify-docs OK');

package/skills/mode/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: mode
+description: novice 레벨 확인·전환 — /novice:mode 1|2|3|off
+disable-model-invocation: true
+---
+
+# /novice:mode — novice 레벨 확인·전환
+
+인자 없이 실행하면 현재 상태를 보여 주고, `1|2|3|off` 인자로 mode를 전환한다.
+mode는 **현재 프로젝트에** 저장되어 세션이 바뀌어도 유지된다.
+
+## 레벨별 동작
+
+| 축 | Level 1 (기본) | Level 2 | Level 3 | off |
+|---|---|---|---|---|
+| 용어 설명 | 세션 첫 노출부터 3회까지 병기 | 3회까지 병기 | 요청 시만 설명 | novice 설명 없음 |
+| 행동 해설 | 실행 전 무엇·왜, 실행 후 변경 결과 | 핵심 결정만 | 아키텍처·유저플로우 중심 | novice 지시 억제 |
+| 시각화 | 3단계 이상 작업·분기·복구 시 표 | 중요 분기에서 표 | 요청 또는 위험 시 표 | novice 시각화 없음 |
+| 안전 게이트 | 유지 | 유지 | 유지 | **유지** (플러그인 활성 동안) |
+
+- 용어는 순화하지 않는다. `commit(현재 변경을 하나의 저장 지점으로 기록하는 것)`처럼
+  실제 용어 뒤에 설명을 병기하고, 충분히 노출된 용어는 설명을 걷어낸다.
+- `off`는 novice 톤·설명·시각화만 끈다. 파괴·시크릿·외부 부작용 안전 게이트는
+  플러그인이 활성화된 동안 계속 동작한다. 플러그인 자체를 disable하면 게이트도 사라진다.
+
+## 사용 예
+
+```
+/novice:mode        ← 현재 level, 적용 범위, 안전 게이트 상태 표시
+/novice:mode 2      ← Level 2로 전환
+/novice:mode off    ← novice 학습층 끄기
+```
+
+## 자연어 별칭 (프롬프트 전체가 정확히 일치할 때만)
+
+- `novice 1` / `novice 2` / `novice 3` / `novice off` — mode 전환
+- `novice reset all` — 모든 용어 설명 카운터 초기화
+- `novice reset <용어>` — 해당 용어만 초기화 (예: `novice reset commit`) — 다시 처음부터 카운트
+- `novice mute <용어>` — 해당 용어를 영구 제외 (노출 횟수와 무관하게 설명 중단, 예: `novice mute commit`)
+- `novice unmute <용어>` — mute 해제 (다시 fade 규칙에 따라 설명)
+
+reset과 mute의 차이: **reset**은 카운터를 0으로 되돌려 다시 N회 설명하게 하고,
+**mute**는 지금 즉시 설명을 끊고 계속 끊어 둔다. `novice mute`는 용어(alias 포함)를 인식하며,
+사전에 없는 용어는 무시한다. mute는 **프로젝트 단위로 저장되어 세션이 바뀌어도 유지**된다
+(reset·용어 카운터는 세션 스코프).
+
+"더 쉽게 설명해 줘" 같은 일반 문장은 현재 답변에만 영향을 주고 mode를 바꾸지 않는다.
+잘못 전환했다면 같은 명령으로 즉시 되돌릴 수 있다.

package/skills/novice/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: novice
+description: novice 학습 동반자 현황 + 하위 명령 안내 (front door) — /novice:mode, /novice:setup-service
+disable-model-invocation: true
+---
+
+# /novice — 현황 + 하위 명령
+
+이 플러그인의 front door다. 인자 없이 현재 상태를 한눈에 보여 주고, 실제 작업은
+하위 명령으로 넘긴다. (플러그인 명령은 항상 `/novice:` 로 namespace된다.)
+
+## 할 일
+
+1. 현재 프로젝트의 novice 설정을 읽어 아래 표로 보여 준다. 상태는 다음 명령으로 읽는다
+   (`CLAUDE_PLUGIN_DATA`는 런타임이 주입하므로 인자로 넘기지 않는다):
+
+   ```
+   node -e "import(process.env.CLAUDE_PLUGIN_ROOT + '/scripts/lib/state.js').then(m=>{const c=m.getProjectConfig(process.cwd());console.log(JSON.stringify({level:c.level,enabled:c.enabled,muted:c.muted_terms}))})"
+   ```
+
+   | 항목 | 값 |
+   |---|---|
+   | novice 레벨 | `level` (enabled=false면 "off"로 표시) |
+   | 학습층 | enabled=true → 켜짐 / false → 꺼짐 |
+   | 안전 게이트 | 최소 deny-only 코어 — 파괴 비가역 명령·노출된 시크릿만 차단. 플러그인 활성 동안 유지 |
+   | mute된 용어 | `muted` 목록 (없으면 "없음") |
+
+2. 이어서 하위 명령을 안내한다:
+
+   | 명령 | 용도 |
+   |---|---|
+   | `/novice:mode 1\|2\|3\|off` | 레벨 확인·전환 (상세: mode 스킬) |
+   | `/novice:setup-service` | 외부 서비스 CLI 부트스트랩 (탐지·설치·로그인·인증) |
+   | `novice mute/unmute/reset <용어>` | 용어 설명 제어 (자연어 별칭) |
+
+## 하지 말 것
+
+- 상태만 보여 주고 임의로 mode를 바꾸지 않는다. 전환은 `/novice:mode`가 담당한다.
+- 안전 게이트는 **최소 deny-only 코어**다: 파괴 비가역 작업(`rm -rf ~` 등)과 노출된 시크릿만
+  차단하고, 그 외(파싱 불가한 파이프·체인 포함)는 Claude Code 네이티브 권한에 위임한다.
+  "항상 모든 걸 막는다"고 단정하지 않는다 (README 안전 게이트 위협 모델 참조).

package/skills/setup-service/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: setup-service
+description: 외부 서비스 CLI 부트스트랩 — 탐지·설치·로그인·인증 확인까지 2-tier 승인 흐름
+---
+
+# setup-service — 외부 서비스 CLI 부트스트랩
+
+manifest 기반 상태 머신 `resolve → preflight → plan → approve → apply → verify → recover`로
+외부 서비스 CLI를 준비한다. 엔진은 `scripts/bootstrap-engine.js` 라이브러리이고,
+provider별 차이는 전부 `config/bootstrap-manifests/*.json` 데이터에 있다.
+
+## 자동화 경계 (절대 넘지 않는다)
+
+- 자동화하는 것: **CLI 탐지 → 설치 → 로그인 실행 → 인증 상태 확인**까지.
+- 자동화하지 않는 것: 리소스 생성·연결, env/secret 값 입력, 배포, 결제, 삭제, 약관 동의.
+  이후 단계는 무엇을·왜·어느 명령으로 하는지 단계별로 안내하고 **사용자가 직접 실행**한다.
+- credential 값을 절대 요청·보관·전달·자동입력하지 않는다. 브라우저·device flow·MFA는
+  사용자가 직접 완료한다. 값을 대화·명령 인자·shell history에 넣지 않도록 경고한다.
+
+## 2-tier 규칙
+
+| | Tier 1 | Tier 2 |
+|---|---|---|
+| 대상 | 검토된 manifest (vercel, gh, supabase) | 그 외 모든 CLI |
+| 근거 | repo 동봉 version 관리 manifest | engine이 조사한 공식 docs URL·package coordinate |
+| 실행 조건 | 표준 승인 (설치 1회 + 로그인 1회) | **근거 출처와 실행 argv를 화면에 그대로 제시**하고 사용자가 승인한 경우에만 |
+| 근거 미확인 시 | — | guided manual로 낮춤 (설치·로그인 진행 안 함) |
+| 위험 verb 차단 | provider-aware (manifest 등재분) | generic grammar 보증만 — 이 차이를 승인 UI에 표시 |
+
+## 진행 절차 (모델 지침)
+
+1. **resolve**: 서비스명을 Tier 1 manifest에 매핑. 미등재면 공식 문서·registry를 조사해
+   ad-hoc manifest(같은 schema, `tier: 2`)를 만들고 근거를 표로 제시한다.
+2. **preflight** (read-only): 설치 여부, version, 기존 인증, credential 저장 방식, 대화형 여부.
+   이미 인증돼 있으면 로그인을 재실행하지 않는다.
+3. **plan/approve**: 설치 위치·전역 변경·인증 저장 위치·실행 argv·되돌리기(logout/uninstall)를
+   표로 보여 주고 **설치와 로그인 각각 1회씩** 승인받는다. 승인은 해당 실행 1회에만 유효하다.
+4. **apply**: 승인된 manifest argv만 exec-form으로 한 명령씩 실행. `curl | bash`·shell 문자열 조립 금지.
+5. **verify**: version check와 auth status로 각각 검증한다.
+6. **recover** (실패 시): 완료 단계, 남은 전역 파일·credential 위치, 재시도·logout·uninstall
+   명령을 보고만 한다. **자동 logout/uninstall은 하지 않는다.**
+
+## capability 라우터 (CLI → MCP → Chrome → guided manual)
+
+경로 선택·검증·다운그레이드는 `scripts/lib/capability-router.js`가 결정한다.
+`scripts/bootstrap-engine.js`의 `setupService(engine, serviceId, capability, ctx)`가 진입점이며,
+`cli` 경로만 manifest 엔진을 직접 실행하고 나머지는 **plan(안내)만 반환**한다.
+
+- **경로 결정**: `resolveCapability`가 `capability_priority`(CLI→MCP→Chrome→guided manual) 순으로
+  각 경로의 가용성을 검사해 첫 사용 가능 경로를 고른다. provisioning·deploy·env_setup처럼
+  service-capabilities에서 `guided_manual`로 고정된 capability는 즉시 guided manual로 간다.
+- **MCP 검증(`validateMcpCandidate`)**: 두 경로. (1) 정적 `mcp_allowlist`에 server·transport·
+  publisher가 정확히 일치 + provenance verified + 요청 tool이 전부 allowlist 안 + 해당 capability
+  담당 엔트리 → 사전 검토분이라 재확인 없이 사용. (2) 사용자가 Claude runtime에 **이미 등록한 서버**
+  (`registered:true` — 등록이 곧 provenance) + 이번 작업에 **명시적 동의**(`userConsent:true`) →
+  동의한 tool 범위 안에서 사용. 둘 다 아니면 경로를 건너뛴다. **allowlist 기본값은 비어 있어,
+  등록·동의가 없으면 아무 MCP도 자동 실행되지 않는다.** 어느 경로든 MCP tool 실제 호출은 모델이
+  하고 PreToolUse 안전 게이트가 계속 검사하며, MCP 서버를 자동 설치하지 않는다.
+- **CLI 동의(`cliUserConsent`)**: Tier 1 검토 manifest 외에, 사용자가 근거(docs URL·coordinate·argv)를
+  확인하고 명시적으로 동의한 Tier 2 CLI도 사용한다. 동의 없는 설치·로그인은 하지 않는다.
+- **Chrome 판정(`chromeDecision`)**: 공식 Claude in Chrome이 연결되고 제3자 provider가 아닐 때만
+  visible mode로 사용한다. login/CAPTCHA/MFA·최종 submit은 항상 사용자가 직접 완료한다.
+- **한계(정직 표기)**: 라우터는 경로 결정·검증·다운그레이드·plan 생성까지다. 플러그인은 MCP 서버를
+  spawn하거나 MCP tool을 호출하거나 Chrome을 조작하지 않는다(비목표: 임의 MCP 자동 설치 금지).
+
+## 중단·다운그레이드 조건
+
+- secure credential storage가 없어 **평문 저장**으로 떨어지는 환경(manifest
+  `credential_store.abort_auto_login_on_plaintext: true`) → 자동 로그인 중단,
+  저장 위치·위험·logout/삭제 방법 안내.
+- 비대화형 환경(`claude -p`, CI) → manifest `noninteractive_policy.login`에 따라
+  deny 또는 guided manual (예: `GH_TOKEN`/`SUPABASE_ACCESS_TOKEN`은 사용자가 직접 설정).
+- 사용자가 CLI 설치를 거부하거나 preflight 실패 → 위 라우터가 allowlisted 공식 MCP →
+  visible Chrome → guided manual 순으로 낮춘다. login/CAPTCHA/MFA·최종 submit은 항상 사용자 몫.
+
+## GitHub OAuth App (guided manual)
+
+GitHub OAuth App 생성·callback 등록은 자동화하지 않고 콘솔 단계로 안내한다.
+OAuth App은 callback URL을 하나만 지원하므로 local·preview·production 동시 등록을 약속하지 않고,
+환경별 app 분리 또는 GitHub App 전환을 옵션으로 제시한다. Client ID/Secret 값은 사용자가
+직접 콘솔에서 확인·입력하며 플러그인은 값을 받지 않는다.
+
+## 부트스트랩 이후 (guided manual 예시)
+
+- env 설정: 어떤 변수가 왜 필요한지 설명하고 `vercel env add NAME` 같은 **대화형 명령** 또는
+  콘솔 화면을 안내한다. 실제 값은 사용자가 그 프롬프트/화면에 직접 입력한다.
+- 리소스 생성·배포·삭제: 명령과 영향을 안내하고 사용자가 실행한다. 유료·production·삭제는
+  특히 사용자 실행 원칙.