leerness 1.36.185 → 1.36.186

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.36.186 — 2026-09-05
+
+- T-0174: add read-only five-scope state inspection with worktree/project isolation and honest legacy inventory; reuse workspace snapshots, skip unused npm skill discovery and bookkeeping, preserve all existing state.
+
 ## 1.36.185 — 2026-09-04
 
 - T-0165/T-0166/T-0167/T-0171/T-0172: adds honest provider-capacity observation, exact-file TTL leases, strict Role/Agent/Routing v2 schemas, a fail-closed legacy role-store loader, and availability-aware role fallback with revision-bound execution provenance. Compatibility fields remain explicit, high-risk reviewer independence requires concrete model identities, corrupt state is preserved without provider execution, and all new surfaces are covered by adversarial regression probes.

package/README.ko.md

@@ -162,6 +162,11 @@ leerness mcp serve                          # JSON-RPC over stdio, 98개 도구
 
 ## 아키텍처 (외부 리뷰 검증)
 
+`leerness state inspect . --json`으로 현재 상태 위치와 Project / Worktree /
+Common-Control / Immutable-Record / Generated-View의 제안 경로를 확인할 수 있습니다.
+읽기 전용 진단이며 데이터 이동·runtime 활성화·모델 호출은 하지 않습니다.
+[진단 API](docs/state-paths-api.md)와 [단계별 구조 전환 계획](docs/state-scopes.md)을 참고하세요.
+
 - **런타임 의존성 0 / install-script 0** — `package.json` 의 dependencies/optional/peer 가 전부 비어 있고 postinstall 도 없습니다. 순수 Node stdlib(`fs`/`path`/`child_process`/`readline`). 공급망 공격면 최소. `leerness install-safety` 로 확인 가능.
 - **canonical JSON 단일 진실소스 + 마크다운 projection** — 메모리는 JSON 으로 저장하고 사람이 읽는 `.md` 는 파생물. 파이프(`|`)·개행·백틱·이모지·한글이 마크다운 테이블에서도 안전(셀 이스케이프 + round-trip).
 - **원자적 UTF-8 쓰기** — temp + rename 으로 부분쓰기 손상 방지, BOM 자동 strip.

package/README.md

@@ -93,6 +93,11 @@ Resolution never silently executes a fallback. Each applied choice is bound to t
 
 ## Make it enforced, not optional
 
+Before changing a multi-agent project's storage, inspect its actual workspace and proposed
+Git-private/common scopes with `leerness state inspect . --json`. It is read-only: no data
+migration, runtime activation, or provider calls. See [the state inspection API](docs/state-paths-api.md)
+and [the staged architecture plan](docs/state-scopes.md).
+
 By default leerness is **cooperative**: your AI agent runs the commands because CLAUDE.md / AGENTS.md tell it to. A determined agent could skip them. To turn the guideline into a guardrail:
 
 ```bash
@@ -156,7 +161,7 @@ MIT
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.36.185 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.36.186 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -210,7 +215,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.36.185는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **98개 도구**를 노출:
+Leerness v1.36.186는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **98개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -231,7 +236,7 @@ Leerness v1.36.185는 stdio JSON-RPC MCP server를 내장합니다 — Claude Co
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) 회귀 테스트 갱신 → 4) 전체 e2e 스위트 통과 → 5) npm publish + git tag → 6) main push → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **v1.9.x → 1.36.185 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
+현재 누적: **v1.9.x → 1.36.186 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
 
 ### 성능 가이드
 
@@ -269,5 +274,5 @@ leerness release pack --close --auto-main-push
 - `.leerness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
 - `.leerness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
 
-Last synced by Leerness v1.36.185: 2026-09-05
+Last synced by Leerness v1.36.186: 2026-09-05
 <!-- leerness:project-readme:end -->

package/bin/leerness.js

@@ -49,7 +49,7 @@ const {
   migrateLegacyWorkspace,
 } = require('../lib/workspace-dir');
 
-const VERSION = '1.36.185';
+const VERSION = '1.36.186';
 
 // MCP lifecycle 주소 표식은 현재 CLI 호출 한 번에만 유효하다. CLI bootstrap에서 즉시 env에서
 // 떼어 두어 `--no-record`/hook처럼 presence 기록 함수에 도달하지 않는 경로도 후속 child에 유출하지 않는다.
@@ -190,8 +190,8 @@ function _loadSkillCatalog() {
 
 // 1.9.341 (UR-0025 심층): BUILTIN_CATALOG (9 내장 스킬 catalog) 는 lib/catalogs.js 로 이전 (import).
 
-// 1.9.10: skillCatalog는 skillpack 우선, fallback builtin. _loadSkillCatalog 호출은 BUILTIN_CATALOG 정의 후.
-const skillCatalog = _loadSkillCatalog();
+// Catalog initialization is below the parser declarations so metadata-only
+// inspection can skip irrelevant skillpack discovery (including npm root -g).
 
 const routes = {
   planning:        { read: ['.leerness/plan.md','.leerness/progress-tracker.md','.leerness/project-brief.md','.leerness/current-state.md','.leerness/guideline.md'], update: ['.leerness/plan.md','.leerness/progress-tracker.md','.leerness/current-state.md','.leerness/session-handoff.md'] },
@@ -882,8 +882,13 @@ function _errorUiLang(root, command) {
   const parsed = nonFlagArgs();
   const resolvedCommand = command || parsed[0];
   if (resolvedCommand === 'mode' && has('--json')) return 'ko';
+  if (resolvedCommand === 'state' && parsed[1] === 'inspect') return _inspectionUiLang();
   return _uiLang(resolvedCommand === 'mode' ? _modeRoot(parsed, root) : root);
 }
+function _inspectionUiLang() {
+  const language = String(arg('--language', process.env.LEERNESS_LANG || 'ko')).toLowerCase();
+  return language === 'en' ? 'en' : 'ko';
+}
 // ko/en 쌍에서 해석된 UI 언어로 선택 (Phase 1: 첫 화면 한정 사용).
 function _tx(lang, ko, en) { return lang === 'en' ? en : ko; }
 function fm(role, readWhen, updateWhen, body, lang = 'ko') {
@@ -11487,6 +11492,7 @@ function commandsCmd(root) {
       { cmd: 'roles list|set|unset|catalog|suggest|verify|validate', desc: '모델별 역할 부여 + fail-closed 저장소 검증 — 1.9.270/T-0171', descEn: 'assign roles and validate the role store fail-closed — 1.9.270/T-0171' },
       { cmd: 'capabilities [--json]', desc: '권한·보안 표면 공개 (무엇을 하는지 + opt-out + 주의 명령) — 1.9.272', descEn: 'disclose the permission/security surface (what it does + opt-outs + commands to watch) — 1.9.272' },
       { cmd: 'state show|start|record|verify|handoff', desc: '.leerness/ JSON 상태 substrate (에이전트 간 인수인계 표준) — 1.9.278', descEn: '.leerness/ JSON state substrate (cross-agent handoff standard) — 1.9.278' },
+      { cmd: 'state inspect [path] [--json]', desc: '5-scope 현재/제안 경로와 기존 상태 목록 — 읽기 전용, 이동·활성화 없음', descEn: 'five-scope current/proposed paths and legacy inventory — read-only, no migration or activation' },
       { cmd: 'adapter <tool>|list [--dry-run]', desc: '도구별 지침/.mcp.json 선택 생성 (claude/cursor/codex/goose/...) — 1.9.280', descEn: 'generate per-tool instructions/.mcp.json selectively (claude/cursor/codex/goose/...) — 1.9.280' },
       { cmd: 'ci init [path] [--force]', desc: 'PR 마다 leerness gate 실행하는 GitHub Actions 워크플로 생성 (.github/workflows/leerness-gate.yml) — 1.9.444', descEn: 'create a GitHub Actions workflow that runs leerness gate on every PR (.github/workflows/leerness-gate.yml) — 1.9.444' },
       { cmd: 'export|prompt --target <agent>', desc: 'adapter 별칭 — 도구별 지침/계약 파일 생성 (claude/cursor/codex/agents-md/...) — 1.9.448', descEn: 'adapter alias — generate per-tool instruction/contract files (claude/cursor/codex/agents-md/...) — 1.9.448' },
@@ -12181,6 +12187,7 @@ const _OBSERVATION_ONLY_SUBCOMMANDS = new Map([
   ['lease', new Set(['list', 'check'])],
   ['roles', new Set(['validate'])],
   ['role', new Set(['validate'])],
+  ['state', new Set(['inspect'])],
 ]);
 function _cliMutationClass(args, cmd) {
   if (cmd === 'mcp') return 'observation-only'; // server startup must not mutate its incidental cwd
@@ -15563,6 +15570,7 @@ const _STRICT_COMMAND_FLAGS = {
   'lease list': { allowed: ['--session', '--all'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'lease list [--session <key>] [--all] [--json]' },
   'lease check': { allowed: ['--session'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'lease check <file> [--session <key>] [--json]' },
   'roles validate': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles validate [--path .] [--json]' },
+  'state inspect': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'state inspect [path] [--path <path>] [--json]' },
   'roles set': { allowed: ['--provider', '--to', '--model', '--model-family', '--policy', '--fallback-policy', '--candidate', '--candidate-family', '--remove-candidate', '--clear-candidates', '--persona', '--force'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles set <role> --provider <id> [--model <id>] [--policy strict|balanced|continuity]' },
   'roles unset': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles unset <role> [--path .] [--json]' },
   'roles suggest': { allowed: ['--apply'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles suggest [--apply] [--path .] [--json]' },
@@ -15644,6 +15652,13 @@ function _validateRolesCommandShape(cmd, args) {
 }
 
 function _validateCommandFlags(cmd, args) {
+  if (cmd === 'state' && args[1] === 'inspect') {
+    if (!_rejectDuplicateValueFlags(['--path'])) return false;
+    if (args.length > 3) {
+      failJson(has('--json'), 'too_many_arguments', 'Usage: state inspect [path] [--path <path>] [--json]');
+      return false;
+    }
+  }
   if (cmd === 'lease' && !_rejectDuplicateValueFlags(['--session', '--ttl', '--note', '--path'])) return false;
   if (cmd === 'agents' && args[1] === 'route'
     && !_rejectDuplicateValueFlags(['--tier', '--approved-by', '--reason', '--path'])) return false;
@@ -15656,6 +15671,7 @@ function _validateCommandFlags(cmd, args) {
   if (cmd === 'intent' && args[1] === 'expand') route = 'intent expand';
   if (cmd === 'lease') route = `lease ${args[1] == null ? 'list' : args[1]}`;
   if (roleSub) route = `roles ${roleSub === 'remove' || roleSub === 'rm' ? 'unset' : roleSub}`;
+  if (cmd === 'state' && args[1] === 'inspect') route = 'state inspect';
   const cfg = _STRICT_COMMAND_FLAGS[route];
   if (!cfg) return true;
   return _rejectUnknownFlags(cfg.allowed, cfg.usage, { globals: cfg.globals });
@@ -28893,6 +28909,21 @@ function _updateRun(root, id, mutator) {
 }
 // 1.9.328 (UR-0025): _splitList → lib/pure-utils.js 로 이동 (순수 콤마 리스트 분할, require 사용).
 
+// Inspect is intentionally independent of all legacy state loaders and writers.
+function stateInspectCmd(root) {
+  try {
+    const { inspectState, formatStateInspection } = require('../lib/state-inspect');
+    const report = inspectState(root);
+    if (has('--json')) return log(JSON.stringify(report, null, 2));
+    // Do not read a project manifest merely to render a metadata-only diagnostic.
+    return log(formatStateInspection(report, _inspectionUiLang()));
+  } catch (error) {
+    const known = error.name === 'StatePathError' || error.name === 'WorkspaceDirectoryError';
+    return failJson(has('--json'), known ? error.code : 'state_inspection_failed',
+      known ? error.message : 'State inspection failed; no files were changed.');
+  }
+}
+
 // leerness state <show|start|record|verify|handoff>
 // 1.9.292 (UR-0031): get_project_context — 외부 에이전트 온보딩용 단일 집약 컨텍스트.
 //   1콜로 현재 작업/미답 요청/최근 결정/활성 룰/next-actions/memory/프로젝트 의도를 구조화 회수.
@@ -31793,6 +31824,7 @@ SETUP & UPDATE
 
 STATUS & DIAGNOSTICS
   status [path]                   Install status (files present)
+  state inspect [path] [--json]   Read-only five-scope paths/inventory; no migration or runtime activation
   health [path] | doctor [--json]   health: project state · doctor: CLI install/environment (no path arg)
   verify [path]                   Required-file verification
   which [--json]                  Resolve current binary/version (npm cache conflicts)
@@ -31874,6 +31906,7 @@ function help() {
   log(`Leerness v${VERSION}\n\nUsage:\n  leerness init [path] [--language auto|ko|en] [--skills recommended|all|a,b]\n  leerness migrate [path] [--dry-run] [--force]\n  leerness update [path] [--check|--yes|--force|--from <tarball>]\n  leerness auto-update install [path]\n  leerness status [path]\n  leerness verify [path]\n  leerness debug [path]\n  leerness audit [path]\n  leerness check [path]\n  leerness scan secrets [path]\n  leerness encoding check [path]\n  leerness lazy detect [path]\n  leerness memory search "query" [--limit 5]\n  leerness handoff [path] [--all-apps] [--include p1,p2] [--since 24h|3d] [--compact] [--json]   # 1.9.17-22 워크스페이스 (--compact: LLM 시스템 프롬프트용 1줄 요약)\n  leerness orchestrate "<목표>" [--agents N] [--model qwen2.5:7b-instruct] [--retry-on-fail K]   # 1.9.22 Ollama opt-in (LEERNESS_OLLAMA_BASE_URL 필요)\n  leerness llm-bench record --score N --model X [--label L] [--tokens T]   # 1.9.22 LLM 벤치 히스토리 누적\n  leerness deps <capability> [--run-tests] [--json]   # 1.9.24 depends-on 역방향 추적 + 자동 회귀 sweep\n  leerness memory search "키" [--include-code]   # 1.9.25 소스 코드 본문도 검색 (모순 감지 핵심)\n  leerness brainstorm "주제" [--include-code]    # 1.9.25 코드 본문 hits 포함\n  leerness register-pending "<요청>" [--agent X] [--note Y]   # 1.9.25 다중 세션 in-progress 즉시 등록\n  leerness optimism-check <T-ID> [--json]   # 1.9.26/27 낙관적 표시 감지 (1.9.27: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수)\n  leerness persona list|show <id>|add <id>   # 1.9.29 페르소나 카탈로그 (보안/성능/UX/testing/docs 5종 내장)\n  leerness review <file> --persona <id1,id2,...>   # 1.9.29 도메인 페르소나 리뷰 프롬프트 자동 생성\n  leerness agents list|check|quota          # 외부 AI CLI 다축 가용성 확인\n  leerness agents resolve \"<task>\" --role <role> [--preset strict|balanced|continuity]   # 역할 유지 + 대체 선택지\n  leerness agents fallback provider|session|direct|hold \"<task>\" --role <role> [--session-provider P --session-model M --session-model-family F]   # 명시 선택·기록\n  leerness agents record completed|failed|reviewed|validated \"<summary>\" [--task T-ID --role R --to P --model M --model-family F --agent P --agent-model M --agent-model-family F --evidence E]\n  leerness agents history [--limit 20]        # 실행자·검수자·결과 provenance\n  leerness agents dispatch \"<task>\" --to <id>   # 활성 CLI 대상 실행 명령 생성 (실 호출 X, 사용자 실행)\n  leerness agents multi "<task>" [--only c1,c2] [--write] [--execute] [--timeout 60]   # 1.9.152/156 활성 N개 일괄 dispatch (--execute: 실 spawn + consensus)\n  leerness provider list|add|remove [args]   # 1.9.157 Provider Registry — 사용자 정의 CLI provider 동적 추가 (OpenRouter/Bedrock 흡수)\n  leerness agents dispatch "<task>" --multi   # 1.9.152 multi 모드 alias (또는 --to all)\n  leerness setup-agents [path] [--yes|--no-setup-agents]    # 1.9.32 sub-agent CLI 인터랙티브 설정 (.env + 미설치 자동 설치)\n  leerness init [path] [--no-stale-check]                   # 1.9.33 npx 캐시 함정 — 옛 버전 자동 경고 (끄려면 --no-stale-check)\n  leerness which [--json]                                   # 1.9.164 진단: 현재 실행 경로/버전 + npm 캐시 + PATH 후보 (구버전 충돌 해결)\n  leerness selftest [--json]                                # 1.9.258 코어 함수 무결성 자가 검증 (설치 손상/부분설치 감지, CI 친화 exit 1)\n  leerness shell-guard "<command>" [--json]                 # 1.9.260 터미널 명령 셸 호환성 린터 (PowerShell 5.1 && 미지원 등 실행 전 감지, UR-0020)\n  leerness shell-guard --record --cmd "..." --exit N        # 1.9.260 실패한 터미널 명령 기록 → 다음 분석 시 회수\n  leerness path-setup [--apply] [--json]                    # 1.9.254 leerness CLI PATH 자동 등록 (npm global bin 미등록 시)\n  leerness web check|screenshot|extract <url> [--out file.png] [--selector "css"]  # 1.9.165 playwright bridge (opt-in: npm i -g playwright + permissions.browser)\n  leerness pc check|click|type|screenshot [--x N --y N] [--text "s"] [--out f.png]  # 1.9.166 robotjs/nut-tree bridge (opt-in: npm i -g robotjs + permissions.mouse/keyboard, ⚠ full 모드 권장)\n  leerness lsp check|symbols|references <file/name> [--in dir] [--json]  # 1.9.167 LSP 어댑터 MVP (typescript opt-in + regex fallback, 코드 인텔리전스)\n  leerness review-request "<request>" [--json]  # 1.9.176 사용자 요청 사전 검토 (충돌/재사용/효율/권장 단계 — 사용자 명시)\n  leerness contract verify <spec.md> <impl.js> [--json]     # 1.9.35 명세 ↔ 구현 일치 검사 (함수/필드)\n  leerness reuse autodetect [path] [--apply] [--json]       # 1.9.35 src/*.js의 module.exports → reuse-map 후보 등록\n  leerness audit [path] [--fix]                              # 1.9.35 --fix: session-handoff/current-state 자동 갱신\n  leerness verify-claim <T-ID> ... [--strict-claims]   # 1.9.26 verify-claim에 낙관적 표시 자동 검사 통합
   leerness lens [${_lensDomainList()}] [--json]   # 1.18.3/1.36.97 분야별 자기질문 품질 렌즈 (database·contract·recovery·observability 심화 · axes 8축 경량 — 완료 선언 전 자가 점검)\n  leerness library [show|page] [path] [--json] [--ai]   # 1.36.98 재사용 인벤토리 — 컴포넌트·디자인 토큰 추출 (page: 오프라인 HTML · --ai: 에이전트용 압축)\n  leerness reuse-map [path] [--all-apps] [--include p1,p2] [--strict-elements] [--json] # 1.9.18 중복/잠재중복/depends-on\n  leerness verify-claim <T-ID> [--path .] [--run-tests] [--json]   # 1.9.18-20 evidence 자동 검증 (1.9.20: scenes/scripts 등 도메인 폴더 + jest/mocha 파싱)\n  leerness verify-code [path] [--build] [--bench]  # 1.9.20 --bench: scripts.bench 추가 실행 + evidence 누적\n  leerness session close [path]\n  leerness route <task-type>\n  leerness self check [path]\n  leerness readme sync [path]\n  leerness consistency check [path]\n  leerness consistency merge-design-guide [path]\n  leerness plan show|init|add|drop|progress|sync [args]\n  leerness task list|add|update|drop|fix-evidence|relink [args]\n  leerness skill list|info <name>\n  leerness skill learn <id> --doc <url> --command "..." --capability "..." [--note ...]\n  leerness skill use <id> [--note ...]\n  leerness skill optimize <id> --before "..." --after "..." [--note ...]\n  leerness skill remove <id>\n  leerness skill consolidate [--threshold 0.3]\n  leerness gate [path]                       # verify+audit+scan+encoding+lazy
   leerness lease acquire|release|list|check [file|lease-id] [--session KEY] [--ttl SEC] [--json]  # exact-file opt-in 협업 lease
+  leerness state inspect [path] [--json]   # 5-scope 경로/목록 읽기 전용 진단 — 이동·활성화 없음
   leerness retro [path] [--days 7] [--all-apps] [--include p1,p2] [--json]  # 회고 (1.9.13~1.9.16)
   leerness insights [path] [--all-apps] [--include p1,p2] [--json]         # 누적 통계 (1.9.13~1.9.16)
   leerness brainstorm "<주제>" [--all-apps] [--include p1,p2] [--json]    # 브레인스토밍 (1.9.13~1.9.16)
@@ -31910,6 +31943,12 @@ async function main() {
   if (!_rejectUnregisteredFlags(cmd)) return;
   if (!_rejectMalformedFlagForms(cmd, args)) return;
   if (!_validateCommandFlags(cmd, args)) return;
+  // Exact early dispatch is both a no-write boundary and a latency boundary:
+  // no workspace migration/guard rescans, usage locks, presence, or stale checks.
+  if (cmd === 'state' && args[1] === 'inspect') {
+    const explicit = arg('--path', null);
+    return stateInspectCmd(explicit !== null ? explicit : args[2] === undefined ? process.cwd() : args[2]);
+  }
   // 값이 존재하지만 의미가 잘못된 --keep 도 legacy migration/write 전에 거부한다.
   // preview serve 의 --keep 은 route별 boolean 계약이므로 숫자 검증 대상이 아니다.
   if (!_commandBooleanValueFlags(cmd, args[1]).has('--keep')) {
@@ -33091,6 +33130,14 @@ async function main() {
   return;
 }
 
+const skillCatalog = (() => {
+  const args = nonFlagArgs();
+  if (require.main === module && args[0] === 'state' && args[1] === 'inspect') {
+    return _withBuiltinSource(BUILTIN_CATALOG);
+  }
+  return _loadSkillCatalog();
+})();
+
 // 1.9.4 B: main 종료 후 exitCode를 명시적으로 process.exit으로 강제 (셸/wrapper 차 무시).
 // 1.9.255 (UR-0019 2단계): require.main 가드 — `require('harness.js')` 시 main() 미실행 (init 부작용 차단 + 내부 함수 단위 테스트 가능).
 //   CLI 직접 실행 (node harness.js / npx leerness) 시에만 main() 호출. 기존 동작 100% 보존.

package/docs/state-paths-api.md

@@ -0,0 +1,92 @@
+# State inspection API v1
+
+Available in v1.36.186. T-0174 / P-0020 is an additive inspection-only foundation.
+It does not move data or activate a new backend. The complete staged design is in
+[State scopes and migration](state-scopes.md).
+
+## CLI
+
+```sh
+leerness state inspect
+leerness state inspect ./project --json
+leerness state inspect --path ./project --language en
+```
+
+The target must be an existing directory. `--path` wins over the optional positional
+target; otherwise the target is the current directory. Blank paths, extra positionals,
+duplicate `--path`, unknown options and unsupported write flags fail before discovery.
+Text defaults to Korean; `--language` or `LEERNESS_LANG` chooses English/Korean without
+reading a project manifest. JSON is one document, with `ok: true` on success, or the
+standard `ok: false` / `code` / `error` envelope and exit 1 on failure.
+
+## Module export
+
+- `resolveStatePaths(root, options)` from `lib/state-paths.js`: read-only resolution;
+  default root is cwd. `options.env` supplies the child Git environment and workspace
+  override; `options.envValue` overrides workspace selection. Neither is persisted.
+
+`inspectState(root, options)` from `lib/state-inspect.js` adds `ok` and the fixed-list
+inventory; `formatStateInspection(report, language)` renders the already resolved
+snapshot without more I/O. The resolver does not initialize the CLI or discover skills.
+
+## Fields
+
+- schemaVersion: 1.
+- schema: `leerness.state-paths/v1` (inspection: `leerness.state-inspection/v1`).
+- activeLayout: `legacy`; existing writers remain authoritative.
+- runtimeActivated: false.
+- migrationAvailable: false.
+- projectRoot: canonical absolute directory of the requested project, not necessarily the Git root.
+- projectKey: `project-` plus SHA-256 of the canonical repository-relative project path.
+- projectRelativePath: forward-slash relative path, or `.` for a repository root/non-Git project.
+- git: absolute worktreeRoot/gitDir/gitCommonDir and linkedWorktree, or null for genuine non-Git.
+- workspace: selected name/path, canonical path, detectedPaths, legacy presence and recognition status.
+- scopes: exactly project, worktree, commonControl, immutableRecord and generatedView.
+- warnings: explicit non-Git, unrecognized/foreign and legacy-workspace observations.
+
+All `proposedPath` / `proposedPaths` values are future addresses, **not created, activated,
+validated as writable, or authorization to write**. Project scope separately reports
+`currentPath`. Inventory rows report the actual legacy path, classification, proposed
+semantic scope, migrationAvailable=false and lstat metadata (including links/errors).
+They are not a move plan. Mixed task/context/queue documents must be split by field;
+human intent is not disposable generated state.
+
+Inventory covers the selected path plus any other existing canonical/legacy workspace,
+with workspacePath and selectedWorkspace on each row. A legacy reader selection must not
+hide canonical runtime, nor may a canonical selection hide residual legacy evidence.
+Text output prefixes rows with the workspace directory name; contents are never merged.
+
+Project identity is independent of branch name and session. Matching repository-relative
+projects in linked worktrees share a common-control proposal, but never private runtime.
+Siblings differ. Separate clones/hosts do not share live control. Non-Git proposals use
+project-local `cache/state-runtime`, with commonControl unavailable, not an invented shared store.
+These keys are namespaces, not credentials. Moving a project inside a repo changes its key.
+
+## Failures and limits
+
+Path errors distinguish invalid/not-found/not-directory/unreadable targets. Git errors
+distinguish missing, unsupported, bare, metadata-directory, timeout, output-limit,
+unreadable, ambiguous output and repository discovery failure. Filesystem
+errors in Git-returned paths or the discovery marker walk remain Git-specific;
+they never misreport an existing inspection target as missing. Existing workspace
+conflict/override/link errors retain their codes; strict inspection adds workspace_unreadable.
+Git failure never silently falls back to a different backend. Existing discovery ceilings
+are respected; nonexistent ceilings are ignored as Git does. Git location/config injection
+overrides are sanitized through the existing gateway, not through a duplicate subprocess wrapper.
+
+One Git topology query has a 5-second process timeout and 64-KiB output cap (Windows executable
+discovery is a separate bounded gateway step). Git must support `--path-format=absolute`.
+Workspace discovery reads immediate directory names; inventory uses a fixed set of leaves
+and cached parent metadata without contents or recursive traversal. Links are not followed
+for inventory. This is an observational, non-transactional filesystem snapshot; it is not
+record validation, tracking detection, filesystem locking or a migration-integrity certificate.
+
+## Verification
+
+`npm run test:state-scopes` runs selector equivalence, topology/metadata and real CLI tests.
+The CLI test instruments normal execution without internal/no-migration/no-stale bypasses:
+one Git query, no npm/provider command, no project content read, no write; it also compares
+all fixture/cwd/Git file bytes and mtimes. Windows may perform trusted Git location and
+console encoding operations. No new runtime dependency, persistent config or MCP tool is added.
+Invalid option diagnostics are instrumented too: neither target nor unrelated cwd
+manifest contents are read merely to choose an error language.

package/docs/state-scopes.md

@@ -0,0 +1,264 @@
+# State scopes and migration design
+
+Status: scope inspection implemented; runtime architecture remains proposed (2026-09-05).
+Request: UR-0097; implementation/optimization approval: UR-0098. Audit: T-0173.
+First implementation: T-0174 / approved P-0020. See [the inspection API](state-paths-api.md).
+
+**Only path resolution and `state inspect` are implemented; the stores and migration below are designs.**
+The first implementation covers path resolution and read-only inspection only. Existing writers,
+data locations, task IDs, CLI/MCP contracts and approval gates remain unchanged until an
+explicitly approved migration passes its compatibility tests.
+
+## 1. Evidence from the current implementation
+
+Audited baseline: v1.36.185, commit `c84ab03b5b5d385985ee2797a95c02c7d4004be4`.
+
+| Surface | Existing source / storage | Structural consequence |
+|---|---|---|
+| Project directory | `lib/workspace-dir.js` resolves `.leerness` and migrates `.harness` | The baseline had no scope resolver. T-0174 adds one without replacing this migration; a pure selector reuses the existing inspection snapshot. |
+| Session presence | `lib/session-presence.js` predicates and `bin/leerness.js` I/O use `.leerness/cache/sessions/` | Sessions have addresses and ignored runtime files already, but different worktrees cannot see each other's presence through this store. |
+| Handoff freshness | `bin/leerness.js`: `.leerness/cache/handoffs/` | Session-bound freshness markers are consumed by handoff/enforcement; migrate those consumers together. |
+| REPL conversation sessions | `bin/leerness.js`: `.leerness/cache/agent-sessions/<sessionId>.jsonl` | This is a separate local conversation surface, not presence. Do not promote raw conversations into public audit records. |
+| Source-file lease | `lib/file-leases.js`: `.leerness/cache/file-leases.json` | Exact-file TTL coordination is local to a checkout; it is not a repository-wide task claim. |
+| State substrate | `bin/leerness.js`: `.leerness/state.json`, `runs/run-N.json`, `handoff/` | Session ownership fixes same-checkout cross-talk, but counters and mutable run files remain local branch files rather than globally unique completion records. |
+| Decisions and lessons | `_saveDecisions` / `_saveLessons`: JSON arrays plus Markdown projections | Valid JSON arrays take precedence. Current readers silently fall back to Markdown for invalid JSON/non-arrays; migration must not. Both the array and its projection are rewritten, so independent records still change the same tracked files on separate branches. |
+| Task progress | `readProgressRows` / `writeProgressRows`: `.leerness/progress-tracker.md` | The table is currently authoritative, not an event-derived view. Reclassifying it without migrating all readers and writers would lose task updates. |
+| Session close | `lib/session-close.js` reads task rows, writes handoff, updates auto-marked current-state lines, invokes further bookkeeping | File locks serialize local writes, not Git merges or a whole multi-file snapshot. The first in-progress task selects the recommendation, which need not be the current session's task. |
+| Execution provenance | `lib/role-fallback.js`: `.leerness/execution-ledger.jsonl` | Revision-bound role/fallback evidence exists, but this checkout ignores the ledger. It is not a durable Git audit record. |
+| Runtime-like tracked files | `git ls-files` includes `active-wakeups.json`, `auto-resume-plan.json`, `next-action-queue.json`, `pre-wake-report.json`, `last-handoff.json`, `routing-log.json` | Ignoring `cache/` alone does not remove mutable operational state from merge inputs. Classification must be per surface, not extension-based. |
+| Integrity checks | `lib/state-integrity.js` inspects only immediate `.leerness/*.json` parseability | Moving to nested stores needs explicit schema/record coverage; a green legacy scan cannot attest to new scopes. |
+
+Some fields mix intent with execution: a queued next action or resume plan may contain
+user-authored instructions. Preserve those as project/task inputs, and move only execution
+status/cursors to runtime. Never classify an entire mixed file as disposable cache.
+
+## 2. Three storage layers, five semantic scopes
+
+The three physical layers are **versioned project data**, **worktree-private execution**,
+and **repository-common coordination**. Immutable-Record and Generated-View are semantic
+scopes within that topology, not two additional database servers.
+
+| Scope | Proposed location | Authority and writer |
+|---|---|---|
+| Project | `<project>/.leerness/` and optional `config/` | Versioned policy, role definitions, project identity, task specifications and human-authored context; explicit project mutations only. |
+| Worktree | `<gitDir>/leerness/projects/<projectKey>/runtime/` | Per-session/per-run execution state. One owner per mutable session record; no branch name as identity. |
+| Common-Control | `<gitCommonDir>/leerness/control/projects/<projectKey>/` | Claims, leases, dependencies, registered worktrees, fencing revisions and run status. All writes pass the same ControlStore transaction boundary. |
+| Immutable-Record | `<project>/.leerness/memory/{decisions,lessons}/` and `.leerness/records/runs/<runId>/` | Individual durable knowledge/result/review records. Exclusive creation; corrected decisions link `supersedes`, never silently overwrite. |
+| Generated-View | `.leerness/generated/` for canonical projections; private runtime `views/` for live session views | Deterministic output with input digests and schema/generator versions. Canonical summary is written only by the consolidator. Live view is local and ignored. |
+
+The main worktree commonly has `gitDir === gitCommonDir`. Distinct `runtime/` and
+`control/` namespaces are therefore mandatory even there. A session subdirectory is still
+required: two agents can operate in one worktree.
+
+The audited repository confirmed the linked checkout's Git directory ends in
+`.git/worktrees/t0165-convergence`, while the main checkout and both common-directory
+queries resolve to the main `.git`. This matches the [Git worktree documentation](https://git-scm.com/docs/git-worktree#_details).
+Use Git's [absolute path queries](https://git-scm.com/docs/git-rev-parse#_options_for_files),
+not string concatenation with `<project>/.git`, which can be a gitfile.
+
+### Identity and unsupported environments
+
+- Resolve topology through the existing `lib/git.js` environment-sanitizing, shell-free
+  gateway. Resolve the worktree root separately from the Leerness project root.
+- Preserve existing workspace markers and foreign-directory detection. A directory with
+  only new `config/memory/records/generated` children is not automatically recognized by
+  today's workspace classifier; a versioned marker/compatibility update is required.
+- P-0020 uses a deterministic project key derived from the canonical repository-relative
+  project path (`.` for the root); identical subprojects across linked worktrees match,
+  sibling monorepo projects do not. A future explicit project ID can preserve identity
+  across project moves. Neither ID is a credential or an authorization boundary.
+- Resolve Windows case/alias/junction and symlink containment before writing. Reject
+  ambiguous mappings instead of silently sharing or relocating another project's state.
+- Bare repositories, broken gitfiles, permission failures, unsupported Git and Git absence
+  must be distinguishable. Git errors do not silently select a different storage backend.
+- True non-Git projects retain an explicitly labelled, ignored project-local runtime
+  fallback; they have no cross-worktree coordination guarantee. Inspection creates nothing.
+- Submodules use their own Git topology. Separate clones and separate hosts do not share
+  `gitCommonDir`; remote coordination is out of scope. Network filesystems need a separate
+  locking guarantee before they are supported for common control.
+
+## 3. Module boundaries and reuse
+
+The inspection modules exist now. Store/facade/view names below remain planned contracts:
+
+| Module | Responsibility | Existing component to reuse |
+|---|---|---|
+| `lib/state-paths.js`, `lib/state-git.js` (implemented) | Five-scope map, canonical project namespace and read-only Git topology; no activation | `lib/git.js`, one `lib/workspace-dir.js` snapshot + pure selection without migration |
+| `lib/state-inventory.js`, `lib/state-inspect.js` (implemented) | Fixed known-surface metadata inventory and CLI JSON/text projection; no recursive content scan | Existing workspace discovery; CLI exact early dispatch skips usage/migration/stale checks and unused skillpack/npm discovery |
+| `lib/state-manager.js` | Narrow orchestration facade, schema dispatch, explicit migration status; no giant all-purpose store | Existing CLI/MCP adapters delegate to this facade incrementally |
+| `lib/worktree-state.js` | Addressed sessions, runs, handoffs and resumable execution; explicit ownership | Session key and freshness contracts in `lib/session-presence.js`; existing run ownership rules |
+| `lib/control-store.js` | Repository-scoped task claim, revision CAS and fencing; transaction ordering | Existing lock primitives after common-root/multi-process validation; no duplication of Git execution |
+| `lib/memory-store.js` | Strict, bounded immutable record load/create; supersession/index projection | Existing decision/lesson parsers and renderers as legacy import adapters |
+| `lib/run-record.js` | Validate execution/review envelopes, finalize and durable receipt | `lib/role-agent-schema.js`, `lib/role-store.js`, `lib/role-fallback.js` provenance contracts |
+| `lib/state-views.js` | Pure deterministic rendering from an explicitly consistent snapshot | Existing Markdown renderers and dashboard serialization, preserving handwritten text |
+
+Dependency direction: CLI/MCP → StateManager → domain stores / views → path, Git and I/O
+primitives. Read-only topology inspection must not call initialization, workspace migration,
+telemetry, presence registration, lease creation or providers. Avoid reusing a convenient
+helper whose discovery path has write side effects.
+
+Runtime dependencies remain zero, Node >=18. Start with bounded JSON records and existing
+file-lock primitives, not a new YAML parser or SQLite package. `ControlStore` is a storage
+interface; a database backend is a future evidence-driven option, not an MVP dependency.
+
+## 4. Concurrency and conflict rules
+
+1. A session owns its mutable runtime files; other sessions submit records/messages through
+   a store operation, never directly edit its progress or handoff.
+2. Runtime is not a Git merge input. Moving files alone is insufficient: migrate ignore
+   rules, old writers, hooks, telemetry, integrity checks, packaging and cleanup too.
+3. Persistent knowledge is record-oriented. Use built-in random UUIDs or an equivalently
+   collision-resistant scheme, not a branch-local maximum counter. Preserve legacy IDs as
+   qualified import metadata; never merge two unrelated `T-0174`/`run-0001` by label alone.
+4. Same ID + same canonical payload is an idempotent replay. Same ID + different payload is
+   `record_id_conflict` and changes no records. Create atomically without overwrite.
+5. Generated-file conflicts are resolved by regenerating from accepted inputs. Preserve
+   human-written sections as project context before deprecating old mixed documents.
+6. Semantic decision disagreement creates a separate decision/review, not `merge=union`.
+7. A single logical consolidator publishes canonical project summaries. A role label alone
+   is insufficient: validate owner, lease generation and expected revision at publication.
+   Expired writers cannot publish after a successor acquires ownership (fencing).
+8. Physical source-file leases and repository task claims are distinct. Two worktrees can
+   edit their separate copies of the same path. Intentional duplicate task execution is
+   coordinated by a repository task key; source leases remain keyed by physical identity.
+9. Common control transactions cannot rely on a thread holding a lock elsewhere. Define
+   lock ordering, bounded critical sections, stale-owner recovery and byte/row limits;
+   verify concurrent acquisition and crash recovery with real processes.
+   Existing lock ownership must not be stolen solely because a PID looks absent or a TTL
+   expires. A new task-claim lease and a local write mutex have different recovery contracts.
+10. Visibility is not authority: provider observations can be unknown or stale. A role or
+    policy revision change requires revalidation; cross-worktree policy divergence cannot
+    be resolved by taking whichever branch updated control most recently.
+
+Presence currently records handoff/close observations, not a heartbeat protocol or proof
+that a process is alive. Common control must distinguish observed presence, a held lease,
+an expired heartbeat and unknown availability. Retain existing session identity validation.
+
+## 5. Run/review provenance and finalize
+
+Each run has separate implementer, reviewer and terminal result records. Fields include:
+schema version, globally unique run/task/agent identity, role, requested and actual
+provider/model, observed identity source, resolution/fallback chain and reasons,
+role/routing/availability revisions, branch/base/source commit, changed-file or diff digest,
+commands with exit results, tests/evidence references, issues, timestamps, and next role.
+Unknown model identity is explicitly unknown; never claim a specific model because it was
+requested. Existing strict high-risk review-independence policy remains intact.
+
+A review binds to the exact reviewed source commit (or explicitly identified uncommitted
+diff digest). Approval of one commit does not approve a later commit or a conflict-resolved
+merge. Dirty work is not represented as clean `HEAD` evidence. Record source commit and
+publication commit separately to avoid a self-referential commit hash inside its own record.
+
+Proposed lifecycle:
+
+```text
+running → execution-terminal → review/gate evaluated → finalize-prepared
+        → immutable records durable → integrated/accepted → cleanup-eligible
+```
+
+`failed`, `blocked` and `rejected` are valid terminal records; persisting them is not a
+successful task-completion claim. A record on an unmerged branch is provisional evidence,
+not canonical accepted project state. Consolidation uses accepted records from the selected
+integration revision plus an explicit control snapshot, not arbitrary branch-local files.
+
+Proposed `finalize` must be bounded, idempotent and crash-recoverable: validate owner/revision,
+freeze input digests, persist records, verify them by reading back, then update the control
+receipt. A missing/different record or changed source revision prevents cleanup. Do not mark
+finalized before the durable writes succeed. Recovery uses the journal/receipt to complete
+or reject a partial attempt without recreating a different result under the same ID.
+
+**A file written in a worktree is not yet safe against worktree removal.** Cleanup eligibility
+requires records/evidence referenced by an accepted retained Git revision (or an explicitly
+configured durable store); merely staged/untracked records are insufficient. Local ignored
+logs must be promoted or have their missing evidence represented before that receipt.
+
+Leerness can enforce finalize on its own adapter cleanup path, not intercept arbitrary
+external `git worktree remove --force`, manual deletion or `git prune`. There is no promise
+of an unbypassable Git removal hook. Worktree locks may reduce accidental pruning but are
+not a substitute for finalization and user-authorized cleanup. Never delete a worktree or
+its metadata as a side effect of inspect, handoff or migration.
+
+## 6. Staged delivery and migration order
+
+| Stage | Tracking | Deliverable / gate |
+|---|---|---|
+| Audit and design | T-0173 | Actual state map, reuse inventory, structural risks, compatibility order and preview; no runtime activation. |
+| Scope foundation | M-0014 / T-0174 / P-0020 | Resolver and `state inspect` read-only CLI contract; current/proposed locations distinguished; no stores moved and no new execution adapter. |
+| Private runtime | M-0015 / T-0175 | Explicit inventory/preview/confirm migration of session/runtime surfaces; per-session ownership; interrupted migration recovery. |
+| Common control | M-0016 / T-0176 | Task identity, claims, owner generations, version/revision compatibility and bounded ControlStore transactions. |
+| Durable records | M-0017 / T-0177 | Append-only memory import, run/review records and finalize durability receipts; old evidence retained. |
+| Views and adapters | M-0018 / T-0178 | Accepted-input snapshot, single-writer summaries, integrity/claims/CLI/MCP/cleanup integration; legacy window closed only with evidence. |
+
+M-0010's existing v2 validators stay usable and legacy runtime writes stay authoritative.
+Finalize its storage/migration design against M-0014 before implementing another independent
+path migration. Runtime activation must also satisfy M-0015 compatibility and M-0016 control
+contracts. M-0011 dispatch, M-0012 live visualization and M-0013 UI consume the same State API.
+Do not prematurely move the already documented role files into `config/`: filename aliases,
+CLI/MCP compatibility and the migration manifest must be specified first.
+
+Migration rules:
+
+- Inventory all writers/readers and classify fields, not just filenames. Snapshot original
+  bytes, inventory digest, source schema and Git tracking before asking to apply.
+- Legacy memory import must distinguish missing JSON from corrupt/invalid JSON. Existing
+  permissive loaders may fall back to stale Markdown; reuse parsers/renderers only behind a
+  strict source selection/validation boundary. Invalid canonical data stops migration and
+  preserves all original bytes, rather than silently promoting a Markdown fallback.
+- Quiesce all participating writers; a new lock cannot stop an old CLI that does not know it.
+  Detect active legacy clients and refuse activation; do not claim mixed-version safety
+  from a new manifest alone. Old clients must be upgraded/stopped before the boundary moves.
+- Stage copied data and validate digests, IDs, counters and provenance before activating one
+  versioned manifest. Use single-authority writes; do not create two independent writable
+  JSON/Markdown or legacy/v2 truths during a compatibility window.
+- Preserve originals as explicitly labelled legacy archives. Never blanket-untrack or delete
+  `.leerness`. Index/ignore changes and project instructions are part of an approved migration.
+- Pre-activation rollback preserves bytes. Post-activation rollback must first reconcile
+  newer events/records; copying an old backup over new writes is not rollback.
+- Default handoff and inspect remain tracked-file-read-only. Explicit project memory,
+  consolidation and finalization are the durable-write boundaries.
+
+## 7. Acceptance matrix
+
+- Main + two real linked worktrees: private paths differ, common paths match, sibling
+  subprojects remain separate; branch switch/detached HEAD do not change runtime identity.
+- Same worktree, two sessions: no current-run/evidence cross-talk; absent/invalid explicit
+  session identity fails safely for concurrent mutation instead of silently borrowing ownership.
+- Non-Git, Git missing, bare, broken gitfile, moved worktree, submodule, spaces, Unicode,
+  Windows alias/case/junction, permission errors and inherited Git location overrides.
+- Inspect/show: byte and mtime snapshots of project and Git metadata remain identical, no
+  cache/usage/salt/lease/lock creation, no subprocess provider calls, bounded stdout/JSON errors.
+- Multi-process claim/lease races, owner expiry/replacement, clock movement, duplicate IDs,
+  truncated JSONL, corrupt/future schema, failed writes and interruption at every commit point.
+- Independent records merge without shared counter edits; conflicting IDs/policy revisions
+  fail closed; decision disagreement stays explicit; generated views reproduce from digests.
+- Finalize replay, record durability failure, stale review commit, rejected review, failed
+  tests, missing provenance, evidence outside retained Git and worktree-removal preflight.
+- Legacy fixtures, handoff/MCP presence, file-lease and role-fallback probes plus installed
+  cleanroom and supported Node/Windows/POSIX release tests before enabling new runtime writes.
+
+## Inspection optimization and verification boundaries
+
+Each valid inspection makes one Git topology query through the existing gateway. On Windows
+the gateway also runs the trusted System32 executable locator; the normal console encoding
+bootstrap is unchanged. Inspection skips unrelated `npm root -g` skillpack discovery and
+does not call providers, register presence, take usage locks, or write caches.
+Workspace discovery enumerates the two immediate workspace directories once. Inventory covers
+known leaves in both existing locations (selected/unselected are explicit), with cached parent
+metadata: it does not read state contents,
+enumerate runtime descendants, query Git tracking, or certify record/schema integrity.
+No long-lived path cache is used: moving a worktree or changing the target refreshes topology.
+
+`npm run test:state-scopes` checks selector compatibility, real main/two linked worktrees,
+project namespaces, moved/detached worktrees, actual submodule topology, aliases, Git failure
+taxonomy, and CLI byte/mtime preservation with normal bookkeeping enabled. The scope probe
+also passed on Node 18/Windows; POSIX execution remains a separate CI check, not implied by it.
+Later concurrency/finalize/adapter acceptance bullets above do not apply to the implemented
+inspection-only stage and are not reported complete by its tests.
+
+## Not included in P-0020
+
+No automatic migration, control database, task dispatch, paid provider calls, source lease
+relocation, decision import, finalize command, worktree deletion or dashboard is implied by
+the path-inspection preview. Existing review/release rules still apply to implementation.
+Later stages require their own
+implementation scope and verification; this design does not mark them complete.

package/lib/pure-utils.js

@@ -275,6 +275,23 @@ function _parseSlashFromHelp(text, invoke = 'slash') {
 // 1.9.283 (UR-0025 2단계): 권한 등급(permission tiers) 순수 로직 — capabilities/policy 공유.
 const PERMISSION_TIERS = ['read-only', 'safe-write', 'project-write', 'shell-read', 'shell-write', 'git-write', 'network', 'publish'];
 function _tierRank(t) { const i = PERMISSION_TIERS.indexOf(String(t || '')); return i < 0 ? PERMISSION_TIERS.length : i; }
+// A narrow literal-text check for the inspection exemption, not a shell parser.
+// Quoted path punctuation is data; operators outside quotes and expansion syntax
+// retain the ordinary conservative classification below.
+function _isLiteralInspectionText(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i], next = text[i + 1] || '';
+    if (/[\r\n]/.test(ch)) return false;
+    if (quote) {
+      if (ch === quote) quote = null;
+      else if (quote === '"' && (ch === '`' || (ch === '$' && /[a-z0-9_{(]/i.test(next))
+        || (ch === '\\' && next === '"'))) return false;
+    } else if (ch === '"' || ch === "'") quote = ch;
+    else if (/[;&|<>()$`^]/.test(ch) || (ch === '\\' && /["']/.test(next))) return false;
+  }
+  return quote === null && !/%[^%\r\n]+%/.test(text);
+}
 // 명령/capability → 요구 등급 (순수 매핑)
 function _requiredTier(cmd) {
   const c = String(cmd || '').toLowerCase();
@@ -284,6 +301,9 @@ function _requiredTier(cmd) {
   const leaseCommand = c.match(/^\s*(?:(?:npx(?:\s+(?:-y|--yes))?\s+)?leerness(?:@[^\s]+)?\s+)?lease\s+(list|check|acquire|release)(?:\s|$)/);
   if (leaseCommand && (leaseCommand[1] === 'list' || leaseCommand[1] === 'check')) return 'read-only';
   if (leaseCommand) return 'safe-write';
+  // This exemption describes one inspect invocation, never composite shell text.
+  if (/^\s*(?:(?:npx(?:\s+(?:-y|--yes))?\s+)?leerness(?:@[^\s]+)?\s+)?state\s+inspect(?:\s|$)/.test(c)
+    && _isLiteralInspectionText(c)) return 'read-only';
   if (/release\s+publish|npm\s+publish|\bpublish\b/.test(c)) return 'publish';
   if (/\bweb\b/.test(c)) return 'network';
   if (/git\s+push|sync-main/.test(c)) return 'git-write';