claude-novice 0.2.0

package/scripts/lib/capsule.js

@@ -0,0 +1,178 @@
+// Learning-seam capsule/glossary builders.
+// Pure string construction over config/terms.json + config/levels.json — no I/O side effects
+// beyond reading the versioned config files, and no network. Callers (SessionStart,
+// UserPromptSubmit, UserPromptExpansion) inject the returned strings as additionalContext.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { pluginRoot } from './secrets.js';
+
+// ---- config loading (cached per resolved plugin root) ----
+
+const cache = new Map();
+function readConfig(name, env = process.env) {
+  const file = path.join(pluginRoot(env), 'config', name);
+  const key = file;
+  if (cache.has(key)) return cache.get(key);
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  cache.set(key, parsed);
+  return parsed;
+}
+
+export function loadTerms(env = process.env) {
+  return readConfig('terms.json', env);
+}
+
+export function loadLevels(env = process.env) {
+  return readConfig('levels.json', env);
+}
+
+// ---- level-rule vocabulary (levels.json codes → Korean summary) ----
+
+const TERM_RULE = {
+  'explain-until-fade': '실제 용어 뒤에 괄호로 한국어 설명을 병기하고, faded 용어는 실제 용어만 쓴다',
+  'explain-first-occurrence': '세션 첫 등장 때만 실제 용어 뒤에 설명을 병기하고 이후에는 실제 용어만 쓴다',
+  'on-request-only': '요청받을 때만 설명하고 평소에는 실제 용어만 쓴다',
+};
+
+const NARRATION = {
+  'before-and-after': '실행 전 무엇을·왜 하는지, 실행 후 무엇이 바뀌었는지 설명한다',
+  'key-decisions-only': '핵심 결정만 짧게 해설한다',
+  'architecture-and-userflow': '아키텍처와 유저플로우 중심으로 설명한다',
+};
+
+const VIZ = {
+  'steps3plus-or-branch-or-risk-or-recovery': '3단계 이상 작업·분기·위험·복구 상황에서 표 또는 체크리스트를 쓴다',
+  'major-branches': '중요한 분기에서 표를 쓴다',
+  'on-request-or-risk': '요청받거나 위험할 때만 표를 쓴다',
+};
+
+const SUPERSESSION =
+  '이 NOVICE_STATE capsule은 이전 turn의 모든 NOVICE_STATE 지시를 대체한다. 다른 과거 level 지시는 무시한다.';
+
+// ---- faded counter ----
+
+// Term names whose exposure count has reached the fade threshold, minus terms whose
+// counters were explicitly reset. Threshold 0 (level 3) fades every counted term, which
+// expresses "auto-explanations off" — the level rule summary carries the same meaning.
+export function computeFadedTerms(termCounts, fadeThreshold, resetTerms = [], mutedTerms = []) {
+  const reset = new Set(resetTerms || []);
+  // Muted terms are force-faded regardless of exposure count and beat reset —
+  // the user explicitly asked to stop explaining them ("novice mute <term>").
+  const out = new Set(mutedTerms || []);
+  for (const [term, count] of Object.entries(termCounts || {})) {
+    if (out.has(term)) continue;
+    if (reset.has(term)) continue;
+    if (Number(count) >= fadeThreshold) out.add(term);
+  }
+  return [...out].sort();
+}
+
+// ---- revisions ----
+
+export function capsuleRevision(level, fadedTerms, schemaVersion) {
+  const v = schemaVersion ?? loadLevels().schema_version;
+  const payload = JSON.stringify({
+    v,
+    level: String(level),
+    faded: [...(fadedTerms || [])].sort(),
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 8);
+}
+
+export function glossaryRevision(termsJson) {
+  const payload = JSON.stringify({
+    v: termsJson.schema_version,
+    terms: termsJson.terms.map((t) => t.term).sort(),
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 8);
+}
+
+// ---- glossary ----
+
+function koreanGloss(term) {
+  const hangul = (term.aliases || []).find((a) => /[가-힣]/.test(a));
+  return hangul || (term.aliases || [])[0] || '';
+}
+
+// One canonical dictionary injection per session (SessionStart). Format per line:
+//   - commit(커밋): 현재 변경을 하나의 저장 지점으로 기록하는 것
+export function buildGlossary(termsJson) {
+  const version = termsJson.schema_version;
+  const header = [
+    `NOVICE_GLOSSARY v${version}`,
+    '아래는 실제 개발 용어 사전이다. 설명이 활성화된 레벨에서는 실제 용어 뒤에 괄호로 이 설명을 병기하고, 용어 자체를 쉬운 말로 대체하지 않는다.',
+  ];
+  const lines = termsJson.terms.map((t) => {
+    const gloss = koreanGloss(t);
+    return gloss ? `- ${t.term}(${gloss}): ${t.explanation}` : `- ${t.term}: ${t.explanation}`;
+  });
+  let out = [...header, ...lines].join('\n');
+  const max = loadLevels().glossary_max_chars ?? 5000;
+  if (out.length > max) out = out.slice(0, max);
+  return out;
+}
+
+// ---- capsule ----
+
+function levelRules(level, env) {
+  const levels = loadLevels(env);
+  const rule = levels.levels[String(level)] || levels.levels['1'];
+  return {
+    schema: levels.schema_version,
+    max: levels.capsule_max_chars ?? 800,
+    term: TERM_RULE[rule.term_explanation] ?? rule.term_explanation,
+    narration: NARRATION[rule.action_narration] ?? rule.action_narration,
+    viz: VIZ[rule.visualization] ?? rule.visualization,
+  };
+}
+
+export function buildCapsule({ level, fadedTerms, revision }, env = process.env) {
+  const r = levelRules(level, env);
+  const render = (fadedText) =>
+    [
+      `[NOVICE_STATE] schema_version:${r.schema} level:${level} rev:${revision}`,
+      `용어 병기 규칙: ${r.term}`,
+      `행동 해설: ${r.narration}`,
+      `시각화 조건: ${r.viz}`,
+      `설명 제외(faded) 용어: ${fadedText}`,
+      SUPERSESSION,
+    ].join('\n');
+
+  const listed = (fadedTerms && fadedTerms.length) ? fadedTerms.join(', ') : '없음';
+  let capsule = render(listed);
+  if (capsule.length > r.max) {
+    // Keep the payload bounded: drop the enumeration, keep the count.
+    capsule = render(`${fadedTerms.length}개 (목록 생략)`);
+  }
+  if (capsule.length > r.max) capsule = capsule.slice(0, r.max);
+  return capsule;
+}
+
+// ---- OFF tombstone ----
+
+export function buildTombstone(env = process.env) {
+  const max = loadLevels(env).tombstone_max_chars ?? 300;
+  const text =
+    'NOVICE_STATE: OFF\n' +
+    'novice가 꺼졌다. 이전 turn의 모든 NOVICE_STATE 지시와 NOVICE_GLOSSARY 용어 사전 지시를 무시한다. ' +
+    '지금부터 novice 톤·용어 병기·시각화 지시를 적용하지 않는다. (플러그인 안전 게이트는 그대로 유지된다.)';
+  return text.length > max ? text.slice(0, max) : text;
+}
+
+// ---- orchestration convenience (shared by the hook scripts) ----
+
+function fadedForLevel(level, session, mutedTerms = [], env = process.env) {
+  const levels = loadLevels(env);
+  const threshold = levels.levels[String(level)].fade_threshold;
+  return computeFadedTerms(session.term_counts || {}, threshold, session.reset_terms || [], mutedTerms);
+}
+
+// mutedTerms is the project-scoped mute list (getProjectConfig().muted_terms) so mutes
+// persist across sessions; term_counts/reset_terms remain per-session.
+export function capsuleForState(level, session, mutedTerms = [], env = process.env) {
+  const faded = fadedForLevel(level, session, mutedTerms, env);
+  const revision = capsuleRevision(level, faded, loadLevels(env).schema_version);
+  const capsule = buildCapsule({ level, fadedTerms: faded, revision }, env);
+  return { faded, revision, capsule };
+}

package/scripts/lib/fingerprint.js

@@ -0,0 +1,17 @@
+// Shared tool-call fingerprinting for the PostToolUse/PostToolUseFailure event hooks.
+// Fingerprints are short hashes — the raw tool input is never persisted.
+import crypto from 'node:crypto';
+
+export const TOOL_USE_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+
+export function computeFingerprint(toolName, toolInput) {
+  const payload = `${toolName}\n${stableStringify(toolInput ?? null)}`;
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}

package/scripts/lib/grammar.js

@@ -0,0 +1,287 @@
+// Finite lexical grammar for the PreToolUse safety gate.
+//
+// This is NOT a general shell parser. It recognizes a single command plus an
+// argv vector (whitespace split, single/double quotes as literals, backslash
+// escapes, flags, `--`, path arguments) and nothing else. Any control operator,
+// redirect, substitution, heredoc, eval, nested shell, or UNQUOTED glob makes a
+// command "unsupported" — the caller then falls back to token-based classification.
+//
+// Keeping the grammar finite is a safety decision: we never try to reason about
+// shell constructs whose runtime effect we cannot bound.
+
+// Shells/interpreters whose `-c`/`-Command` form embeds an unparsed sub-command.
+const SHELL_INTERPRETERS = new Set([
+  'bash', 'sh', 'zsh', 'dash', 'ksh', 'csh', 'tcsh', 'fish', 'ash', 'mksh', 'rbash',
+  'powershell', 'pwsh',
+]);
+const NESTED_COMMAND_FLAGS = new Set(['-c', '-Command', '-command', '-EncodedCommand', '/c', '/C']);
+
+export function baseName(p) {
+  if (typeof p !== 'string' || p === '') return '';
+  const parts = p.split(/[\\/]/);
+  return parts[parts.length - 1] || p;
+}
+
+function isSpecialEscapeTarget(ch) {
+  // Characters where a leading backslash means "literal this shell-special char".
+  return ch === ' ' || ch === '\t' || ch === ';' || ch === '&' || ch === '|' ||
+    ch === '<' || ch === '>' || ch === '(' || ch === ')' || ch === '"' || ch === "'" ||
+    ch === '`' || ch === '$' || ch === '*' || ch === '?' || ch === '[' || ch === ']' ||
+    ch === '{' || ch === '}' || ch === '\\' || ch === '#';
+}
+
+// Tokenize a single command line into argv, or report why it is unsupported.
+// Returns { supported: true, argv } or { supported: false, reason, argv? }.
+export function tokenizeShell(command) {
+  if (typeof command !== 'string') return { supported: false, reason: 'not-a-string' };
+  if (command.trim() === '') return { supported: false, reason: 'empty' };
+
+  const argv = [];
+  let cur = '';
+  let hasCur = false;
+  let sawUnquotedGlob = false;
+  let i = 0;
+  const n = command.length;
+
+  const pushCur = () => { if (hasCur) { argv.push(cur); cur = ''; hasCur = false; } };
+
+  while (i < n) {
+    const ch = command[i];
+
+    if (ch === '\n' || ch === '\r') return { supported: false, reason: 'newline' };
+
+    if (ch === ' ' || ch === '\t') { pushCur(); i++; continue; }
+
+    // control operators / redirects / subshell / substitution
+    if (ch === ';') return { supported: false, reason: 'control-operator:semicolon' };
+    if (ch === '&') return { supported: false, reason: 'control-operator:ampersand' };
+    if (ch === '|') return { supported: false, reason: 'control-operator:pipe' };
+    if (ch === '<') return { supported: false, reason: 'redirect-or-heredoc:lt' };
+    if (ch === '>') return { supported: false, reason: 'redirect:gt' };
+    if (ch === '`') return { supported: false, reason: 'command-substitution:backtick' };
+    if (ch === '(' || ch === ')') return { supported: false, reason: 'subshell' };
+
+    if (ch === '$') {
+      const next = command[i + 1];
+      if (next === '(') return { supported: false, reason: 'command-substitution:dollar-paren' };
+      if (next === '{') return { supported: false, reason: 'parameter-expansion:dollar-brace' };
+      // bare $VAR — keep as a literal token char (e.g. rm '$HOME' deny-list, or benign cd $HOME)
+      cur += ch; hasCur = true; i++; continue;
+    }
+
+    if (ch === "'") {
+      hasCur = true; i++;
+      let closed = false;
+      while (i < n) {
+        if (command[i] === "'") { closed = true; i++; break; }
+        cur += command[i]; i++;
+      }
+      if (!closed) return { supported: false, reason: 'unterminated-single-quote' };
+      continue;
+    }
+
+    if (ch === '"') {
+      hasCur = true; i++;
+      let closed = false;
+      while (i < n) {
+        const c = command[i];
+        if (c === '"') { closed = true; i++; break; }
+        if (c === '\\') {
+          const nx = command[i + 1];
+          if (nx === '"' || nx === '\\' || nx === '$' || nx === '`') { cur += nx; i += 2; continue; }
+          cur += c; i++; continue; // keep backslash literally (e.g. Windows path)
+        }
+        if (c === '$') {
+          const nx = command[i + 1];
+          if (nx === '(') return { supported: false, reason: 'command-substitution:dollar-paren' };
+          if (nx === '{') return { supported: false, reason: 'parameter-expansion:dollar-brace' };
+          cur += c; i++; continue;
+        }
+        if (c === '`') return { supported: false, reason: 'command-substitution:backtick' };
+        cur += c; i++;
+      }
+      if (!closed) return { supported: false, reason: 'unterminated-double-quote' };
+      continue;
+    }
+
+    if (ch === '\\') {
+      const nx = command[i + 1];
+      if (nx === undefined) { cur += '\\'; hasCur = true; i++; continue; }
+      if (isSpecialEscapeTarget(nx)) { cur += nx; hasCur = true; i += 2; continue; }
+      cur += '\\'; hasCur = true; i++; continue; // preserve backslash (Windows path etc.)
+    }
+
+    if (ch === '*' || ch === '?' || ch === '[' || ch === ']' || ch === '{' || ch === '}') {
+      sawUnquotedGlob = true; cur += ch; hasCur = true; i++; continue;
+    }
+
+    cur += ch; hasCur = true; i++;
+  }
+  pushCur();
+
+  if (argv.length === 0) return { supported: false, reason: 'empty' };
+
+  const base = baseName(argv[0]);
+  if (base === 'eval') return { supported: false, reason: 'eval', argv };
+  if (SHELL_INTERPRETERS.has(base) && argv.slice(1).some((a) => NESTED_COMMAND_FLAGS.has(a))) {
+    return { supported: false, reason: 'nested-shell', argv };
+  }
+
+  if (sawUnquotedGlob) return { supported: false, reason: 'unquoted-glob', argv };
+
+  return { supported: true, argv };
+}
+
+// ---- PowerShell routing ----
+
+// Detect a PowerShell command line: canonical Verb-Noun capitalization
+// (Remove-Item, Get-ChildItem) or a case-insensitive hit in the known cmdlet
+// rule lists (so `remove-item` still routes here). Lowercase dashed Unix
+// commands (apt-get, docker-compose) stay on the Bash grammar.
+export function isPowershellCommand(command, knownCmdlets = []) {
+  if (typeof command !== 'string') return false;
+  const first = command.trimStart().split(/[\s;|&<>(){}]/, 1)[0];
+  if (!first || !first.includes('-')) return false;
+  if (/^[A-Z][a-z]+-[A-Z][A-Za-z]+$/.test(first)) return true;
+  const lower = first.toLowerCase();
+  return knownCmdlets.some((c) => c.toLowerCase() === lower);
+}
+
+// ---- Git subgrammar (commit / push / reset / clean) ----
+
+const GLOBAL_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path']);
+
+export function parseGit(argv) {
+  let i = 1;
+  const globalOpts = [];
+  while (i < argv.length && argv[i].startsWith('-')) {
+    const t = argv[i];
+    globalOpts.push(t);
+    if (GLOBAL_WITH_VALUE.has(t)) { i++; if (i < argv.length) globalOpts.push(argv[i]); }
+    i++;
+  }
+  const sub = argv[i];
+  const rest = argv.slice(i + 1);
+  if (sub === 'commit') return parseGitCommit(rest, globalOpts);
+  if (sub === 'push') return parseGitPush(rest, globalOpts);
+  if (sub === 'reset') return parseGitReset(rest, globalOpts);
+  if (sub === 'clean') return parseGitClean(rest, globalOpts);
+  return { sub: sub ?? null, flags: rest.filter((x) => x.startsWith('-')), pathspec: [], options: {}, globalOpts, exotic: false };
+}
+
+const COMMIT_ALLOWED_SHORT = new Set(['a', 'm', 'q', 'v', 's']);
+
+function parseGitCommit(rest, globalOpts) {
+  let allFlag = false;
+  let message = false;
+  let exotic = false;
+  let sawDashDash = false;
+  const pathspec = [];
+  for (let k = 0; k < rest.length; k++) {
+    const t = rest[k];
+    if (sawDashDash) { pathspec.push(t); continue; }
+    if (t === '--') { sawDashDash = true; continue; }
+    if (t.startsWith('--')) {
+      if (t === '--all') { allFlag = true; continue; }
+      if (t === '--message') { message = true; if (k + 1 < rest.length) k++; continue; }
+      if (t.startsWith('--message=')) { message = true; continue; }
+      if (t === '--quiet' || t === '--verbose' || t === '--signoff' || t === '--no-verify') continue;
+      exotic = true; continue; // --amend, --fixup, --squash, --file, --reuse-message, ...
+    }
+    if (t.startsWith('-') && t.length > 1) {
+      let hasMessage = false;
+      for (const c of t.slice(1)) {
+        if (c === 'a') allFlag = true;
+        else if (c === 'm') { message = true; hasMessage = true; }
+        else if (!COMMIT_ALLOWED_SHORT.has(c)) exotic = true;
+      }
+      if (hasMessage && k + 1 < rest.length) k++;
+      continue;
+    }
+    pathspec.push(t); // bare operand → explicit pathspec commit
+  }
+  return {
+    sub: 'commit', allFlag, message, pathspec,
+    exotic: exotic || globalOpts.length > 0, globalOpts,
+    flags: rest.filter((x) => x.startsWith('-')),
+  };
+}
+
+const PUSH_RECOGNIZED = new Set([
+  '-u', '--set-upstream', '--tags', '--follow-tags', '-n', '--dry-run',
+  '-v', '--verbose', '-q', '--quiet', '--porcelain', '--progress', '--no-verify', '--atomic',
+]);
+
+function parseGitPush(rest, globalOpts) {
+  let force = false;
+  let exotic = false;
+  const operands = [];
+  for (const t of rest) {
+    if (t.startsWith('-')) {
+      if (t === '--force' || t === '-f' || t === '--force-with-lease' || t.startsWith('--force-with-lease=')) { force = true; continue; }
+      if (PUSH_RECOGNIZED.has(t)) continue;
+      if (/^-[a-z]+$/i.test(t) && !t.startsWith('--') && /f/.test(t.slice(1))) { force = true; continue; }
+      exotic = true; continue; // --mirror, --delete, --receive-pack, ...
+    }
+    operands.push(t);
+  }
+  const remote = operands[0] ?? null;
+  const branch = operands[1] ?? null;
+  const targetBranch = branch && branch.includes(':') ? branch.split(':').pop() : branch;
+  return {
+    sub: 'push', force, remote, branch, targetBranch,
+    exotic: exotic || globalOpts.length > 0, globalOpts,
+    flags: rest.filter((x) => x.startsWith('-')),
+  };
+}
+
+const RESET_MODES = new Set(['--hard', '--soft', '--mixed', '--keep', '--merge']);
+
+function parseGitReset(rest, globalOpts) {
+  let mode = 'mixed';
+  let exotic = false;
+  const operands = [];
+  for (const t of rest) {
+    if (t.startsWith('-')) {
+      if (RESET_MODES.has(t)) { mode = t.slice(2); continue; }
+      if (t === '-q' || t === '--quiet') continue;
+      exotic = true; continue;
+    }
+    operands.push(t);
+  }
+  return {
+    sub: 'reset', mode, ref: operands[0] ?? null,
+    exotic: exotic || globalOpts.length > 0, globalOpts,
+    flags: rest.filter((x) => x.startsWith('-')),
+  };
+}
+
+function parseGitClean(rest, globalOpts) {
+  let force = false;
+  let dirs = false;
+  let ignored = false;
+  let dryRun = false;
+  let exotic = false;
+  const operands = [];
+  for (const t of rest) {
+    if (t.startsWith('-')) {
+      if (t === '--force') { force = true; continue; }
+      if (t === '--dry-run') { dryRun = true; continue; }
+      if (t.startsWith('--')) { if (t !== '--quiet') exotic = true; continue; }
+      for (const c of t.slice(1)) {
+        if (c === 'f') force = true;
+        else if (c === 'd') dirs = true;
+        else if (c === 'x' || c === 'X') ignored = true;
+        else if (c === 'n') dryRun = true;
+        else if (c !== 'q') exotic = true;
+      }
+      continue;
+    }
+    operands.push(t);
+  }
+  return {
+    sub: 'clean', force, dirs, ignored, dryRun,
+    exotic: exotic || globalOpts.length > 0, globalOpts,
+    flags: rest.filter((x) => x.startsWith('-')),
+  };
+}

package/scripts/lib/hookio.js

@@ -0,0 +1,49 @@
+// Hook stdin/stdout contract helpers.
+// Command hooks receive one JSON payload on stdin and answer with JSON on stdout.
+// Exit code 2 is the blocking/deny path for safety hooks (fail closed).
+import fs from 'node:fs';
+
+export const STDIN_MAX_BYTES = 1024 * 1024;
+
+export function readStdinJson(maxBytes = STDIN_MAX_BYTES) {
+  const buf = fs.readFileSync(0);
+  if (buf.length > maxBytes) {
+    const err = new Error('hook input exceeds size cap');
+    err.code = 'E_INPUT_CAP';
+    throw err;
+  }
+  return JSON.parse(buf.toString('utf8'));
+}
+
+export function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+}
+
+export function emitAdditionalContext(hookEventName, text) {
+  emit({ hookSpecificOutput: { hookEventName, additionalContext: text } });
+}
+
+export function emitPreToolDecision(decision, reason) {
+  emit({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
+export function emitBlock(reason) {
+  emit({ decision: 'block', reason });
+}
+
+// Fail-closed exit for safety hooks: stderr message + exit 2.
+export function failClosed(message) {
+  process.stderr.write(String(message ?? 'novice safety hook error'));
+  process.exit(2);
+}
+
+// Fail-open exit for non-safety hooks: never block the turn on a learning-layer bug.
+export function failOpen() {
+  process.exit(0);
+}

package/scripts/lib/manifest.js

@@ -0,0 +1,154 @@
+// Bootstrap manifest loading and validation (2-tier).
+// Tier 1: reviewed manifests shipped in config/bootstrap-manifests/.
+// Tier 2: ad-hoc manifests built from officially sourced provenance, same schema,
+// executable only after the user has seen and approved the evidence.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pluginRoot } from './secrets.js';
+
+const SHELL_META = /[|;&><`]/;
+const FORBIDDEN_ARGV0 = new Set(['curl', 'wget', 'sh', 'bash', 'zsh', 'eval']);
+
+function checkArgv(argv, label, errors) {
+  if (!Array.isArray(argv) || argv.length === 0 || argv.some((t) => typeof t !== 'string')) {
+    errors.push(`${label}: argv must be a non-empty string array (exec-form)`);
+    return;
+  }
+  for (const token of argv) {
+    if (SHELL_META.test(token)) errors.push(`${label}: shell metacharacter in argv token: ${token}`);
+  }
+  if (FORBIDDEN_ARGV0.has(argv[0])) {
+    errors.push(`${label}: remote-script/shell interpreter argv[0] is forbidden: ${argv[0]}`);
+  }
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object') {
+    return { valid: false, errors: ['manifest must be an object'] };
+  }
+
+  for (const field of ['service_id', 'binary', 'docs_url']) {
+    if (typeof manifest[field] !== 'string' || manifest[field] === '') {
+      errors.push(`missing required string field: ${field}`);
+    }
+  }
+  if (typeof manifest.docs_url === 'string' && !manifest.docs_url.startsWith('https://')) {
+    errors.push('docs_url must be https');
+  }
+
+  if (!Array.isArray(manifest.installers) || manifest.installers.length === 0) {
+    errors.push('installers[] required');
+  } else {
+    manifest.installers.forEach((inst, i) => {
+      if (!Array.isArray(inst.os) || inst.os.length === 0) errors.push(`installers[${i}]: os[] required`);
+      if (typeof inst.package_manager !== 'string') errors.push(`installers[${i}]: package_manager required`);
+      if (typeof inst.package_coordinate !== 'string' || inst.package_coordinate === '') {
+        errors.push(`installers[${i}]: fixed package_coordinate required`);
+      }
+      if (typeof inst.min_version !== 'string') errors.push(`installers[${i}]: min_version required`);
+      checkArgv(inst.argv, `installers[${i}].argv`, errors);
+    });
+  }
+
+  for (const probe of ['detect', 'version_check', 'auth_status']) {
+    if (!manifest[probe] || typeof manifest[probe] !== 'object') {
+      errors.push(`${probe} required`);
+    } else {
+      checkArgv(manifest[probe].argv, `${probe}.argv`, errors);
+      if (!manifest[probe].success) errors.push(`${probe}.success required`);
+    }
+  }
+
+  if (!manifest.login || typeof manifest.login !== 'object') {
+    errors.push('login required');
+  } else {
+    checkArgv(manifest.login.argv, 'login.argv', errors);
+    if (manifest.login.interactive !== true) errors.push('login.interactive must be true (credential values are never piped)');
+  }
+  if (!manifest.logout || typeof manifest.logout !== 'object') {
+    errors.push('logout required');
+  } else {
+    checkArgv(manifest.logout.argv, 'logout.argv', errors);
+  }
+
+  const cs = manifest.credential_store;
+  if (!cs || typeof cs !== 'object') {
+    errors.push('credential_store required');
+  } else {
+    for (const f of ['secure_storage', 'plaintext_fallback', 'abort_auto_login_on_plaintext']) {
+      if (typeof cs[f] !== 'boolean') errors.push(`credential_store.${f} must be boolean`);
+    }
+  }
+
+  if (!manifest.uninstall || typeof manifest.uninstall !== 'object' || Object.keys(manifest.uninstall).length === 0) {
+    errors.push('uninstall required');
+  } else {
+    for (const [pm, argv] of Object.entries(manifest.uninstall)) checkArgv(argv, `uninstall.${pm}`, errors);
+  }
+
+  if (!Array.isArray(manifest.side_effects)) errors.push('side_effects[] required');
+
+  const np = manifest.noninteractive_policy;
+  if (!np || typeof np !== 'object' || !['guided_manual', 'deny'].includes(np.login)) {
+    errors.push('noninteractive_policy.login must be guided_manual|deny');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function loadTier1Manifest(serviceId, env = process.env) {
+  const root = pluginRoot(env);
+  const capsFile = path.join(root, 'config', 'service-capabilities.json');
+  let manifestRel = null;
+  try {
+    const caps = JSON.parse(fs.readFileSync(capsFile, 'utf8'));
+    manifestRel = caps.services?.[serviceId]?.manifest ?? null;
+  } catch {
+    return null;
+  }
+  if (!manifestRel) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'config', manifestRel), 'utf8'));
+    const { valid, errors } = validateManifest(manifest);
+    if (!valid) throw new Error(`tier 1 manifest invalid: ${errors.join('; ')}`);
+    return manifest;
+  } catch (err) {
+    if (String(err.message).startsWith('tier 1 manifest invalid')) throw err;
+    return null;
+  }
+}
+
+// Tier 2: build an ad-hoc manifest from researched official provenance.
+// The engine refuses to execute it unless provenance.confirmed_by_user is true —
+// the caller must have shown docs_url, package coordinate, and exact argv on screen.
+export function buildAdHocManifest(input) {
+  if (!input || typeof input !== 'object') {
+    return { ok: false, reason: 'input required' };
+  }
+  const prov = input.provenance;
+  if (!prov || typeof prov.docs_url !== 'string' || !prov.docs_url.startsWith('https://')) {
+    return { ok: false, reason: 'official provenance (https docs_url) required — guided manual로 낮추세요' };
+  }
+  let host;
+  try {
+    host = new URL(prov.docs_url).host;
+  } catch {
+    host = '';
+  }
+  if (!host) {
+    return { ok: false, reason: 'provenance docs_url host unresolvable — guided manual로 낮추세요' };
+  }
+  const manifest = { ...input.manifest, tier: 2, docs_url: prov.docs_url };
+  const { valid, errors } = validateManifest(manifest);
+  if (!valid) return { ok: false, reason: `ad-hoc manifest invalid: ${errors.join('; ')}` };
+  if (prov.confirmed_by_user !== true) {
+    return {
+      ok: false,
+      reason: 'user has not confirmed the provenance evidence — 근거(문서 URL·coordinate·argv)를 화면에 제시하고 승인받으세요',
+      manifest,
+      requiresUserApproval: true,
+    };
+  }
+  return { ok: true, manifest, requiresUserApproval: true };
+}