@aldegad/safedeps 2.1.0 → 2.2.0

package/ARCHITECTURE.md

@@ -1,166 +1,122 @@
-# Safedeps Architecture (v2)
+# Safedeps Architecture
 
-> **Note on naming**: 이 repo 는 v1 시절 `npm-reorg-guard` 로 출시됐다. v2 부터 ecosystem 통합 + advisory-first 게이트를 도입하면서 제품/CLI 이름을 **`safedeps`** 로 rename 한다. 내부 post-install rollback engine 은 v1 의 `reorg-guard` 컨셉을 그대로 계승. 이 문서는 v2 의 SSoT.
-
-기능 분리:
-- **README.md** — 사용자 설치/사용 가이드 (rename 후 갱신 예정)
-- **SKILL.md** — 스킬 메타 + hook 선언 (Claude/Codex skill loader 가 읽는 SSoT)
-- **ARCHITECTURE.md** — 내부 흐름·설계 (이 문서)
+> Internal design and runtime flow. User-facing setup lives in [`README.md`](./README.md); the skill manifest and hook declarations live in [`SKILL.md`](./SKILL.md). *(한국어 → [ARCHITECTURE.ko.md](./ARCHITECTURE.ko.md))*
+>
+> **Naming** — the project shipped as `npm-reorg-guard` in v1. v2 unified ecosystems and added the advisory ledger, renaming the product and CLI to **`safedeps`**. The post-install rollback engine still inherits the v1 `reorg-guard` design, and for npm the PostToolUse effect gate is the primary enforcement surface.
 
 ---
 
-## 0. 핵심 한 문장 (코덱시 합의)
+## Core idea
 
-> *Safedeps does not decide at install time from multiple live truths.*
-> *It approves one dependency spec from provider evidence first, then the hook only enforces that approved spec; reorg remains the rollback layer if the install result diverges.*
+> Safedeps does not decide at install time from several live truths at once. It approves one dependency closure from provider evidence *first*; then the post-install hook treats the installed lockfile closure as the authority, and reorg rolls back any unapproved or newly-vulnerable effect.
 
-번역: Safedeps 는 install 순간에 여러 라이브 truth 를 동시에 조회해서 결정하지 않는다. **사전에 provider evidence 로 안전한 dependency spec 을 먼저 승인** (approve) 하고, **hook 은 그 승인된 spec 과 명령이 일치할 때만 통과**시킨다. **reorg 는 install 결과가 spec 과 어긋날 때의 rollback layer** 로 남는다.
+Approval happens **before** the install, against canonical advisory evidence. Enforcement happens **after** the install, against what actually landed on disk. For npm, the full closure (direct + transitive) is checked through OSV `/v1/querybatch` with a 24-hour per-`pkg@version` cache. Closure resolution for the other ecosystems is future work.
 
 ---
 
-## 1. The Big Picture — 3-Phase Defense
+## 1. Two lanes, one umbrella
+
+safedeps owns security gates at two distinct moments, under one skill. It absorbed the v1 `npm-reorg-guard` (install-time reorg) and then the `security-release-gates` project (release-time checks, 2026-05-24). The goal is not to pile every "security" concern into one file — it is to give the gates a single canonical owner while keeping each lane's responsibility separate (SRP).
 
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│                  safedeps — one security umbrella                     │
+│                                                                      │
+│   INSTALL-TIME lane                    RELEASE-TIME lane              │
+│   (during development, per install)    (before a release / push)     │
+│   ─────────────────────                ──────────────────            │
+│   advisory check   (npm: OSV batch)    safedeps scan secrets         │
+│   fast command gate (PreToolUse)       safedeps audit deps           │
+│   npm effect gate  (PostToolUse)       safedeps hooks install|check  │
+│                                        safedeps git pre-commit       │
+│   scope: the package being installed   scope: the whole repo tree    │
+│                                        (absorbed from                 │
+│                                         security-release-gates)       │
+│                                                                      │
+│   shared: public DBs (OSV/KEV/GHSA) · local-first · no silent        │
+│   fallback (a provider/scanner miss is fail-closed)                  │
+└──────────────────────────────────────────────────────────────────────┘
 ```
-   ┌─────────────────────────────────────────────────────────────────────┐
-   │                                                                     │
-   │   Phase 1: ADVISORY GATE          Phase 2: HOOK ENFORCEMENT          │
-   │   ────────────────────            ────────────────────               │
-   │                                                                     │
-   │   사용자 의도                       │                                 │
-   │   (intent: 이 패키지 설치           │                                 │
-   │    하고 싶다)                       │                                 │
-   │      │                            │                                 │
-   │      ▼                            │                                 │
-   │   ┌─────────────┐    OSV.dev      │                                 │
-   │   │ safedeps    │◄────primary─────┤                                 │
-   │   │   check     │    CISA KEV     │                                 │
-   │   │             │◄──hard-risk────┤                                 │
-   │   │             │    GHSA         │                                 │
-   │   │             │◄──enrichment───┤                                 │
-   │   └──────┬──────┘                 │                                 │
-   │          │                                                          │
-   │          ▼                                                          │
-   │   ┌──────────────────────┐                                          │
-   │   │ approved spec ledger │                                          │
-   │   │ .safedeps/           │                                          │
-   │   │   approved-specs/    │                                          │
-   │   │   <hash>.json        │                                          │
-   │   │ • ecosystem          │                                          │
-   │   │ • package@version    │                                          │
-   │   │ • approved_at        │                                          │
-   │   │ • expires_at         │                                          │
-   │   │ • evidence sources   │                                          │
-   │   └──────┬───────────────┘                                          │
-   │          │                                                          │
-   │          ▼                                                          │
-   │                              ┌─────────────────┐                    │
-   │                              │ 사용자 / Claude  │                    │
-   │                              │ install 명령 발행 │                    │
-   │                              │ (npm install ..) │                    │
-   │                              └────────┬────────┘                    │
-   │                                       │                             │
-   │                                       ▼                             │
-   │                              ╔═════════════════════════╗            │
-   │                              ║ PreToolUse HOOK         ║            │
-   │                              ║ safedeps-pre-guard.sh   ║            │
-   │                              ╚════════╤════════════════╝            │
-   │                                       │                             │
-   │                              ledger 조회:                            │
-   │                              "이 명령의 ecosystem +                  │
-   │                               pkg@version 이 approved              │
-   │                               spec 과 일치?"                         │
-   │                                       │                             │
-   │                              ┌────────┴────────┐                    │
-   │                              ▼                 ▼                    │
-   │                          match O          match X                   │
-   │                              │                 │                    │
-   │                              ▼                 ▼                    │
-   │                       명령 실행          BLOCK + 안내                  │
-   │                          │              ("safedeps                   │
-   │                          │               check ... 먼저 해")          │
-   │                          ▼                                          │
-   │                  install 실행                                       │
-   │                          │                                          │
-   │                          ▼                                          │
-   │                  ╔══════════════════════════════╗                  │
-   │                  ║ PostToolUse HOOK             ║                  │
-   │                  ║ safedeps-post-verify.sh      ║                  │
-   │                  ╚════════╤═════════════════════╝                  │
-   │                           │                                         │
-   │                  lockfile diff vs                                   │
-   │                  approved spec 비교                                  │
-   │                           │                                         │
-   │                  ┌────────┴────────┐                                │
-   │                  ▼                 ▼                                │
-   │              spec 과 동일       diverged                             │
-   │                  │                 │                                │
-   │                  ▼                 ▼                                │
-   │              CONFIRM            REORG                               │
-   │              (clean baseline)   (rollback to                        │
-   │                                  last confirmed)                    │
-   │                                                                     │
-   │   Phase 3: POST-INSTALL SAFETY NET (v1 의 reorg engine 계승)         │
-   │   ───────────────────────────────────────────────                   │
-   │                                                                     │
-   └─────────────────────────────────────────────────────────────────────┘
+
+- **Install-time lane** (sections 2–13 below) — advisory check, fast command guard, and the npm effect gate + reorg. Per-package and proactive.
+- **Release-time lane** — the repo-tree checks from `security-release-gates` (secret scan, dependency audit, repo hook install/check, privacy profile), exposed under the `safedeps scan|audit|hooks|git` command namespace. Repo-specific policy (`.gitleaks.toml`, lockfiles) stays in the target repo; safedeps owns execution, install, and verification.
+
+The two lanes differ in timing and scope (one package's effect before/after install vs. the whole repo before a release). They live under one umbrella but stay separated by command namespace.
+
+**The effect-primary model is npm-only.** `pip`, `cargo`, `go`, `gem`, `maven`, and `nuget` stay on the v2.1 command-gate + reorg model until their closure resolvers land; they are not described as having PostToolUse closure authority.
+
+### Install-time flow
+
+```
+   intent ("I want to install this package")
+      │
+      ▼
+   ┌─────────────┐     OSV.dev  ──canonical──►
+   │ safedeps    │     CISA KEV ──hard-risk──►   advisory check
+   │   check     │     GHSA     ──enrichment─►   (Phase 1)
+   └──────┬──────┘
+          │  approve
+          ▼
+   ┌──────────────────────┐
+   │ approved-spec ledger │   ~/.safedeps/approved-specs/<hash>.json
+   │ ecosystem · pkg@ver  │   + transitive_specs (npm closure)
+   │ approved_at/expires  │
+   └──────────────────────┘
+          │
+          ▼
+   install command issued ──► PreToolUse hook (fast command guard, Phase 2)
+                                  │  ledger match?  ── miss ──► BLOCK + "run safedeps check first"
+                                  │  match ──► run
+                                  ▼
+                              install runs
+                                  │
+                                  ▼
+                              PostToolUse hook (npm effect gate, Phase 3)
+                                  │  lockfile closure vs ledger + OSV batch
+                                  ├─ approved & clean ──► CONFIRM (new safe baseline)
+                                  └─ unapproved / vulnerable ──► REORG (roll back to last confirmed)
 ```
 
-핵심 통찰:
-- **Phase 1 = pre-install advisory gate** (새로 추가). vuln DB 조회 → 안전 spec 결정. 사용자/Claude 가 install 명령 *작성하기 전에* 끝남.
-- **Phase 2 = hook enforcement**. hook 자체는 vuln DB 조회 안 함. **approved spec ledger 와의 일치만 검증**. 빠르고 결정론적.
-- **Phase 3 = post-install rollback**. v1 reorg engine 그대로. install 결과가 approved spec 과 어긋나면 마지막 confirmed 로 복원.
+- **Phase 1 — advisory check.** For npm, safedeps builds a script-free lockfile in a temp dir (`npm install <pkg>@<version> --package-lock-only --ignore-scripts`), extracts the full closure, and queries OSV `/v1/querybatch` for direct and transitive packages together. When clean, the direct ledger entry records `transitive_specs`.
+- **Phase 2 — fast command gate.** The PreToolUse hook parses the command, blocks obvious unapproved installs, and snapshots dependency files. It is a best-effort advisory layer that gives the agent immediate feedback — not the final authority. On Claude Code it also rewrites an npm install to add `--ignore-scripts` (via the hook `updatedInput` capability), so the install runs inert and no lifecycle script executes until the effect gate has verified the closure.
+- **Phase 3 — npm primary effect gate.** The PostToolUse hook compares the actual `package-lock.json` closure against the ledger's direct entries and their `transitive_specs`, and re-queries OSV in batch. Any unapproved or vulnerable package triggers a reorg to the last confirmed snapshot. This authority is scoped to the npm closure.
 
 ---
 
-## 2. Vulnerability DB — Source Hierarchy
+## 2. Advisory sources — one canonical truth
 
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│  TIER 1 — PRIMARY (canonical truth)                                   │
-│  ────────────────────────────────────────                             │
-│  OSV.dev                                                              │
-│    • multi-ecosystem (npm, pip, cargo, go, gem, maven, nuget, ...)    │
-│    • package@version 질의 표준화                                       │
-│    • Google 운영, 무료 API, JSON                                       │
-│    • GHSA, RustSec, GoVulnDB 등 다 aggregate                          │
-│    → 모든 advisory 의 1차 query target                                 │
-├──────────────────────────────────────────────────────────────────────┤
-│  TIER 2 — OVERLAY (hard-risk signal)                                  │
-│  ────────────────────────────────────────                             │
-│  CISA KEV (Known Exploited Vulnerabilities)                          │
-│    • "실제 야생에서 exploit 확인" 만 추림                                │
-│    • OSV 결과와 cross-reference: KEV 매치 시 hard-block (override 불가) │
-│    → 일반 CVE vs "급박한 CVE" 의 구분선                                 │
-├──────────────────────────────────────────────────────────────────────┤
-│  TIER 3 — ENRICHMENT / CROSS-CHECK                                    │
-│  ────────────────────────────────────────                             │
-│  GitHub Advisory (GHSA)                                              │
-│    • OSV 에 일부 들어오지만 first_patched_version /                    │
-│      vulnerable_version_range 같은 metadata 가 개발자 친화             │
-│    • "OSV 와 다른 결" 만 surface — discrepancy verifier 결              │
-│  NVD                                                                  │
-│    • CVE 원본, CVSS 점수, CPE 매핑, hasKev flag                        │
-│    • 점수 기반 우선순위 계산                                            │
-│  deps.dev (Google)                                                    │
-│    • OSV 기반 + package graph metadata (depended_by, license, ...)    │
-│    • transitive dep 위험 분석                                          │
-│  Snyk DB (optional)                                                   │
-│    • purl 기반 query, UI 풍부                                          │
-│    • 무료 quota 한도, configured optional feed 만 사용                  │
-└──────────────────────────────────────────────────────────────────────┘
+TIER 1 — PRIMARY (canonical truth)
+  OSV.dev
+    • multi-ecosystem (npm, pip, cargo, go, gem, maven, nuget, …)
+    • normalized package@version queries · free JSON API (Google)
+    • aggregates GHSA, RustSec, GoVulnDB, and more
+    → the first query target for every advisory
+
+TIER 2 — OVERLAY (hard-risk signal)
+  CISA KEV (Known Exploited Vulnerabilities)
+    • only "confirmed exploited in the wild"
+    • cross-referenced with OSV results; a KEV match is a hard block (no override)
+    → the line between an ordinary CVE and an urgent one
+
+TIER 3 — ENRICHMENT / CROSS-CHECK
+  GitHub Advisory (GHSA) — developer-friendly patched-version metadata; surfaced when it disagrees with OSV
+  NVD       — CVE source, CVSS scores, KEV flag (for score-based prioritization)
+  deps.dev  — OSV-based package graph metadata (transitive risk)
+  Snyk DB   — optional configured feed only (free-quota limited)
 ```
 
-설계 원칙: **canonical truth 는 OSV 하나**. 다른 source 는 enrichment 또는 overlay. 여러 라이브 source 를 \"동급 진실\" 로 두면 cross-fire 발생 — 우리는 OSV 를 truth 로 두고 KEV/GHSA/NVD/deps.dev 는 \"OSV 와 다르거나, OSV 가 못 본 신호\" 만 surface.
+Design principle: **OSV is the one canonical truth.** Every other source is overlay or enrichment. Treating several live sources as co-equal truths invites cross-fire; instead OSV is the truth, and KEV/GHSA/NVD/deps.dev only surface signals that disagree with OSV or that OSV did not see.
 
 ---
 
-## 3. Approved Spec Ledger — SSoT
+## 3. Approved-spec ledger (SSoT)
 
 `~/.safedeps/approved-specs/<hash>.json`:
 
 ```json
 {
-  "hash": "sha256:abc123...",
+  "hash": "sha256:abc123…",
   "ecosystem": "npm",
   "package": "@jackwener/opencli",
   "version": "1.7.16",
@@ -169,427 +125,277 @@
   "expires_at": "2026-06-18T13:00:00Z",
   "approved_by": "user@example.com",
   "evidence": {
-    "osv": { "queried_at": "2026-05-18T13:00:00Z", "vulnerabilities": [] },
-    "kev": { "queried_at": "2026-05-18T13:00:00Z", "exploited": false },
-    "ghsa": { "queried_at": "2026-05-18T13:00:00Z", "advisories": [] }
+    "closure_checked": true,
+    "provider": { "type": "osv-querybatch", "results": [] },
+    "closure": []
   },
   "transitive_specs": [
-    { "package": "...", "version": "...", "spec_hash": "..." }
+    { "ecosystem": "npm", "package": "…", "version": "…" }
   ]
 }
 ```
 
-**핵심 필드**:
-- `hash` — `(ecosystem, package, version)` 의 deterministic hash. hook 이 명령에서 같은 hash 추출 → ledger 조회.
-- `approved_at` / `expires_at` — **lifecycle TTL**. 기본 30일. 만료 후 새 CVE 가능성 있어 자동 revoke + re-check 강제.
-- `evidence` — 그 시점에 어느 source 가 무엇을 봤는지. audit trail.
-- `transitive_specs` — direct 만 아니라 transitive dep 도 ledger 에 박아 \"sub-dep 의 zero-day\" 도 감지 가능.
+Key fields:
 
-**Lifecycle**:
+- `hash` — a deterministic hash of `(ecosystem, package, version)`. The hook derives the same hash from a command and looks the ledger up by it.
+- `approved_at` / `expires_at` — lifecycle TTL, 30 days by default. After expiry a new CVE may exist, so the spec is auto-revoked and re-check is forced.
+- `evidence` — which source saw what, at approval time. An audit trail.
+- `transitive_specs` — the full transitive closure the direct entry approved. The npm effect gate reorgs any `pkg@version` that appears in the lockfile but is in neither the direct entry nor this array.
+
+Lifecycle:
 
 ```
-   approve            install            confirm            re-check
-   ───────            ───────            ───────            ────────
-      │                  │                  │                  │
-      ▼                  ▼                  ▼                  ▼
-   ledger 신규       hook 통과         ledger.confirmed=true   daily cron
-   approved_at=now   spec hash 일치     post-verify 일치        OSV re-query
-   expires_at=+30d                                              │
-                                                                ▼
-                                                        ┌──────┴──────┐
-                                                        ▼             ▼
-                                                  여전히 clean    새 CVE 발견
-                                                        │             │
-                                                        ▼             ▼
-                                                  expires_at      ledger revoke
-                                                  연장             + 사용자 경고
-                                                                  + (옵션) auto reorg
+approve            install            confirm              re-check (daily)
+───────            ───────            ───────              ────────────────
+ledger entry  ──►  hook passes   ──►  post-verify match  ──►  OSV re-query
+approved_at=now    spec matches       confirmed = true          │
+expires_at=+30d                                                 ▼
+                                                    still clean ──► extend expiry
+                                                    new CVE     ──► revoke + warn (+ optional reorg)
 ```
 
 ---
 
-## 4. Runtime Flow — 3-Phase Detail
+## 4. Runtime flow in detail
 
 ### Phase 1 — `safedeps check <ecosystem> <pkg>@<range>`
 
 ```
-사용자 / Claude:
-  "@jackwener/opencli ^1.7.0 깔고 싶음"
+safedeps check npm "@jackwener/opencli@^1.7.0"
         │
+        ├─► ledger lookup ── hit (valid) ──► "already safe, install is fine"
+        │                  └ miss/expired ──► proceed to check
         ▼
-┌─────────────────────────────────────────────────────────┐
-│ safedeps check npm "@jackwener/opencli@^1.7.0"           │
-└────────────────────┬────────────────────────────────────┘
-                     │
-        ┌────────────┴────────────────────────────┐
-        ▼                                         ▼
-   ┌──────────────┐                       ┌──────────────┐
-   │ resolve      │                       │ ledger lookup │
-   │ version      │                       │ "이미 approved?" │
-   │ range →      │                       └───────┬──────┘
-   │ candidate    │                               │
-   │ versions     │                               ▼
-   └──────┬───────┘                       ┌───────┴─────┐
-          │                               ▼             ▼
-          ▼                          hit (valid)    miss / expired
-   ┌──────────────┐                      │              │
-   │ OSV query    │                      ▼              ▼
-   │ per version  │              "이미 안전, install   "새로 check"
-   └──────┬───────┘               해도 됨"
-          │
-          ▼
-   ┌──────────────┐
-   │ KEV overlay  │
-   │ GHSA cross   │
-   └──────┬───────┘
-          │
-          ▼
-   ┌─────────────────────────────────┐
-   │ 결과 분류:                        │
-   │ • clean (no vuln) → approve      │
-   │ • patched_available → approve    │
-   │   안전 버전으로 spec 재작성        │
-   │   예: ^1.7.0 → ^1.7.16            │
-   │ • KEV hit → HARD BLOCK            │
-   │   "이 패키지는 실제 exploit 됨,    │
-   │    설치 X. 대체 모듈: AAA, BBB"   │
-   │ • CVE 있는데 patch X → WARN       │
-   │   "취약점 있음, 사용자 결정 필요"  │
-   └─────────────────────────────────┘
-          │
-          ▼
-   approved spec ledger 신규 entry 작성
-   sha256:abc123... = {ecosystem: npm, pkg, version, ...}
+   resolve range → concrete version(s)
+        │
+        ▼
+   OSV query  ──►  KEV overlay  ──►  GHSA cross-check
+        │
+        ▼
+   classify:
+     • clean              → approve
+     • patched available  → approve, rewrite spec to the fixed version (^1.7.0 → ^1.7.16)
+     • KEV hit            → HARD BLOCK ("exploited in the wild; do not install")
+     • CVE, no patch      → WARN (user decision required)
+        │
+        ▼
+   write a new approved-spec ledger entry
 ```
 
-### Phase 2 — Hook Enforcement (PreToolUse / `safedeps-pre-guard.sh`)
+For npm, "OSV query" runs over the **whole resolved closure** in one `/v1/querybatch` call, and the approved entry records every transitive package in `transitive_specs`.
+
+### Phase 2 — fast command guard (PreToolUse / `safedeps-pre-guard.sh`)
 
 ```
-Claude 가 Bash 실행 요청: "npm install @jackwener/opencli@^1.7.16"
+Claude runs: npm install @jackwener/opencli@^1.7.16
         │
         ▼
-   ┌─────────────────────────────────┐
-   │ safedeps-pre-guard.sh           │
-   │ 1. 명령 파싱:                    │
-   │    ecosystem = npm               │
-   │    pkg = @jackwener/opencli      │
-   │    version_range = ^1.7.16       │
-   │ 2. spec hash 계산                │
-   │ 3. ledger 조회                   │
-   └────────────┬────────────────────┘
-                │
-       ┌────────┴────────┐
-       ▼                 ▼
-   ledger hit          ledger miss
-   (approved +         (또는 expired)
-    not expired)            │
-       │                    ▼
-       ▼            ┌──────────────────────┐
-   PASS             │ BLOCK + Claude 한테    │
-   (명령 실행)       │ 안내:                  │
-                    │ "이 패키지가 advisory  │
-                    │  gate 통과 안 됨.      │
-                    │  safedeps check ...    │
-                    │  먼저 실행해서 spec    │
-                    │  approve 해야 함"      │
-                    └──────────────────────┘
+   parse command → ecosystem, package, version_range
+   compute spec hash → ledger lookup
+        │
+        ├─ hit (approved, not expired) ──► PASS (run the command)
+        └─ miss / expired ──────────────► BLOCK + "run `safedeps check …` first, then retry"
 ```
 
-### Phase 3 — Post-Install Rollback (PostToolUse / `safedeps-post-verify.sh`)
+The guard also snapshots lockfiles/manifests and keeps the v1 hardcoded pattern blocks (see section 5). It is fast and advisory; the authority is the post-install gate.
+
+### Phase 3 — npm primary effect gate + reorg (PostToolUse / `safedeps-post-verify.sh`)
 
 ```
-install 완료 → safedeps-post-verify.sh
+install done → safedeps-post-verify.sh
         │
         ▼
-   ┌─────────────────────────────────────────┐
-   │ 1. lockfile 새 entry 추출                │
-   │ 2. 각 entry 의 spec hash 계산             │
-   │ 3. ledger 와 비교                         │
-   │ 4. install script / native binary 검사    │
-   │    (v1 reorg-guard 로직 그대로)           │
-   └────────────┬────────────────────────────┘
-                │
-       ┌────────┴────────┐
-       ▼                 ▼
-   spec 과 동일       diverged
-   + 의심 없음        (예: transitive dep
-       │              이 ledger 에 없는
-       ▼              버전으로 깔림,
-   CONFIRM            install script 의심,
-   (ledger 의         native binary 출현)
-   confirmed=true)         │
-                            ▼
-                   REORG (v1 engine):
-                   • lockfile ← 마지막 confirmed snapshot
-                   • rm -rf node_modules
-                   • npm install (재설치 = ledger 와 일치)
-                   • reorg.log 기록
-                   • Claude 한테 경고
+   read the actual package-lock.json closure
+   check every pkg@version against the ledger (direct entries + transitive_specs)
+   re-query OSV in batch for the whole closure
+   inspect install scripts + native binaries (v1 reorg-guard logic)
+        │
+        ├─ all approved, clean, no suspicion ──► CONFIRM (new safe baseline)
+        └─ unapproved / vulnerable / suspicious ──► REORG:
+                 • restore lockfile from the last confirmed snapshot
+                 • rm -rf node_modules; reinstall to match the ledger
+                 • append to reorg.log; message the agent
 ```
 
 ---
 
-## 5. Threat Model (v2 갱신)
+## 5. Threat model
 
 ```
-┌─────────────────────────────────────────────────────────────────────┐
-│  PHASE 1 — ADVISORY GATE (`safedeps check`)                          │
-├─────────────────────────────────────────────────────────────────────┤
-│ • 알려진 CVE 매칭 (OSV.dev 기반, multi-ecosystem)                     │
-│ • KEV 매칭 시 hard-block (사용자 override 불가)                       │
-│ • patched_available 시 안전 버전으로 spec auto-rewrite                │
-│ • transitive dep 의 vuln 도 ledger 에 박아 sub-dep 침해 감지          │
-├─────────────────────────────────────────────────────────────────────┤
-│  PHASE 2 — HOOK ENFORCEMENT (`safedeps-pre-guard.sh`)                │
-├─────────────────────────────────────────────────────────────────────┤
-│ v1 의 hardcoded pattern 결도 유지 (defense-in-depth):                 │
-│ • typosquat 명단 매치                                                 │
-│ • curl|bash 류 pipe execution                                         │
-│ • 비표준 --registry URL                                               │
-│ • install script safety disabling                                     │
-│ • eval / subshell indirection                                         │
-│ + 새로운 enforcement:                                                  │
-│ • spec hash 가 ledger 에 없거나 expired → BLOCK + advisory gate 안내   │
-├─────────────────────────────────────────────────────────────────────┤
-│  PHASE 3 — POST-INSTALL REORG (`safedeps-post-verify.sh`)            │
-├─────────────────────────────────────────────────────────────────────┤
-│ • install script 의 network/code execution/sensitive path 검사        │
-│ • base64/hex obfuscation                                              │
-│ • 비표준 registry resolved URL                                        │
-│ • 50+ dep explosion                                                   │
-│ • native binary 출현                                                  │
-│ • lockfile entry 가 approved spec 과 diverged → REORG                 │
-└─────────────────────────────────────────────────────────────────────┘
+ADVISORY CHECK (safedeps check)
+  • known-CVE matching (OSV, multi-ecosystem)
+  • KEV match → hard block (no user override)
+  • patched-available → auto-rewrite the spec to the fixed version
+  • transitive vulns recorded in the ledger, so sub-dependency compromise is detectable
+
+FAST COMMAND GUARD (safedeps-pre-guard.sh)
+  v1 hardcoded patterns (defense-in-depth): typosquat list · curl|bash pipes ·
+  non-standard --registry · install-script-safety disabling · eval/subshell indirection
+  + fast advisory ledger check: missing/expired spec → block with advisory-gate guidance
+
+npm PRIMARY EFFECT GATE + REORG (safedeps-post-verify.sh)
+  • install-script network / code-execution / sensitive-path access
+  • base64 / hex obfuscation
+  • non-standard registry resolved URLs · 50+ dependency explosion · native binaries
+  • npm lockfile closure diverging from approved specs / transitive_specs → REORG
 ```
 
-**막지 않는 것 (현재 한계)**:
-- ledger 의 approved_at 이후 새로 발견된 zero-day — daily re-check 로만 catch 가능, install 시점엔 못 잡음.
-- npm registry 자체의 손상.
-- 사용자가 `--allow-unverified` 명시 우회한 경우 (observable, log 기록).
+**Install-script timing.** A package's `postinstall` script runs *during* `npm install`. On Claude Code, the Phase 2 hook injects `--ignore-scripts`, so the install is inert and scripts run only after the effect gate confirms the closure (via `npm rebuild`) — a rejected package's scripts never run. On Codex CLI, which does not expose the `updatedInput` hook capability, the install runs normally and a malicious install script can execute once before the post-install reorg cleans up. (The package's *runtime* code is removed before your app runs it on both engines; only install-time lifecycle scripts have this Codex window.)
+
+**What it does not stop (current limits):**
+
+- A zero-day discovered *after* `approved_at` — only the daily re-check catches it, not the install itself.
+- Compromise of the npm registry itself.
+- An install the user explicitly waved through with `--allow-unverified` (observable, logged).
+- An attacker writing to `~/.safedeps/approved-specs/` directly under the same OS user. The ledger is a local convenience cache; until signing/HMAC or install-time re-validation is added, it is not a security boundary against a same-user attacker. (The effect gate's OSV re-query does, however, still catch a forged approval for a *known-vulnerable* package — see [`ROADMAP.md`](./ROADMAP.md) "Ledger tamper resistance".)
 
 ---
 
-## 6. Provider Failure Modes (No Silent Fallback)
+## 6. Provider failure modes (no silent fallback)
 
 ```
-┌────────────────────────────────────────────────────────────────────┐
-│  OSV.dev 응답 무 / timeout                                          │
-│  ────────────────────                                               │
-│  • 1차: provider cache (local TTL 24h) 사용                          │
-│  • cache miss → fail-closed (block + "OSV 응답 없음, 재시도")        │
-│  • 사용자 explicit `--allow-unverified` 시만 우회 + log            │
-├────────────────────────────────────────────────────────────────────┤
-│  CISA KEV 응답 무                                                   │
-│  ────────────────────                                               │
-│  • KEV 는 매일 1회 download (정적 catalog), 로컬 cache 만 사용       │
-│  • 24h 이상 stale 시 경고                                           │
-├────────────────────────────────────────────────────────────────────┤
-│  GHSA / NVD 응답 무                                                 │
-│  ────────────────────                                               │
-│  • enrichment 결이라 fail-open 허용                                 │
-│  • OSV 결과로만 진행 + log 에 "GHSA cross-check skipped"            │
-└────────────────────────────────────────────────────────────────────┘
+OSV.dev — no response / timeout
+  • first: use the local provider cache (24h TTL)
+  • cache miss → fail-closed (block; "no OSV response, retry")
+  • bypass only with explicit --allow-unverified, and it is logged
+
+CISA KEV — no response
+  • KEV is a static catalog downloaded once a day; only the local cache is used
+  • warn when it is more than 24h stale
+
+GHSA / NVD — no response
+  • enrichment only, so fail-open is allowed
+  • proceed on OSV alone and log "GHSA cross-check skipped"
 ```
 
-설계 원칙: **silent fallback 금지**. 모든 우회는 observable + log. canonical truth (OSV) 가 응답 못 하면 default = fail-closed.
+Design principle: **no silent fallback.** Every bypass is observable and logged. When the canonical truth (OSV) cannot answer, the default is fail-closed.
 
 ---
 
-## 7. State Layout — `~/.safedeps/`
+## 7. State layout — `~/.safedeps/`
 
 ```
 ~/.safedeps/
-├── approved-specs/
-│   ├── sha256-abc123.json         ← 한 (ecosystem, package, version) 당 한 파일
-│   ├── sha256-def456.json
-│   └── ...
-│
-├── snapshots/                     ← v1 reorg snapshot 그대로 계승
-│   ├── 20260518-130000-xyz/
-│   │   ├── package-lock.json
-│   │   ├── yarn.lock
-│   │   ├── pnpm-lock.yaml
-│   │   ├── poetry.lock            ← v2 ecosystem 확장
-│   │   ├── uv.lock
-│   │   ├── Cargo.lock
-│   │   ├── go.sum
-│   │   ├── Gemfile.lock
-│   │   └── meta.json
-│   └── ...
-│
-├── confirmed_${dir_hash}          ← 프로젝트별 마지막 confirmed snapshot
-│
+├── approved-specs/            ← ledger SSoT, one JSON file per (ecosystem, package, version)
+│   ├── sha256-abc123.json
+│   └── …
+├── snapshots/                 ← reorg snapshots (inherited from v1, extended to all lockfiles)
+│   └── <id>/ { package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, uv.lock,
+│               Cargo.lock, go.sum, Gemfile.lock, meta.json }
+├── confirmed_${dir_hash}      ← per-project last confirmed snapshot
 ├── cache/
-│   ├── osv/                       ← OSV query 응답 cache (24h TTL)
-│   │   └── npm-@jackwener-opencli-1.7.16.json
-│   └── kev/                       ← CISA KEV daily catalog
-│       └── kev-2026-05-18.json
-│
-├── locks/                         ← atomic state (TOCTOU 방지)
-├── reorg.log                      ← REORG event 기록 (append-only)
-└── advisory.log                   ← advisory gate event 기록 (block/approve)
+│   ├── osv/                   ← OSV query responses (24h TTL)
+│   └── kev/                   ← CISA KEV daily catalog
+├── locks/                     ← atomic state (TOCTOU guard)
+├── reorg.log                  ← reorg events (append-only)
+└── advisory.log               ← advisory-gate decisions (approve / block)
 ```
 
-설계 결정:
-- `approved-specs/` = ledger SSoT, JSON-per-spec (atomic write).
-- `snapshots/` = v1 결 그대로 + py/rust/go/ruby lockfile 추가.
-- `cache/osv/`, `cache/kev/` = provider 응답 cache (TTL).
-- `advisory.log` = advisory gate 의 모든 approve/block decision audit trail.
+- `approved-specs/` is the ledger SSoT, one atomic JSON write per spec.
+- `snapshots/` keeps the v1 design plus the Python/Rust/Go/Ruby lockfiles.
+- `cache/osv/` and `cache/kev/` hold provider responses under TTL.
+- `advisory.log` is the audit trail of every approve/block decision.
 
 ---
 
-## 8. Multi-Ecosystem Support (v2 확장)
+## 8. Multi-ecosystem support
 
-| Ecosystem | Manifest | Lockfile | safedeps check 명령 |
+| Ecosystem | Manifest | Lockfile | `safedeps check` |
 |---|---|---|---|
 | npm | `package.json` | `package-lock.json` | `safedeps check npm <pkg>@<range>` |
-| yarn | `package.json` | `yarn.lock` | `safedeps check npm <pkg>@<range>` (OSV 공통) |
+| yarn | `package.json` | `yarn.lock` | `safedeps check npm <pkg>@<range>` |
 | pnpm | `package.json` | `pnpm-lock.yaml` | `safedeps check npm <pkg>@<range>` |
 | pip (Poetry) | `pyproject.toml` | `poetry.lock` | `safedeps check pypi <pkg>@<range>` |
 | pip (uv) | `pyproject.toml` | `uv.lock` | `safedeps check pypi <pkg>@<range>` |
 | pip (Pipenv) | `Pipfile` | `Pipfile.lock` | `safedeps check pypi <pkg>@<range>` |
-| pip (raw) | `requirements.txt` | (약함) | `safedeps check pypi <pkg>@<range>` |
+| pip (raw) | `requirements.txt` | (weak) | `safedeps check pypi <pkg>@<range>` |
 | cargo | `Cargo.toml` | `Cargo.lock` | `safedeps check crates.io <pkg>@<range>` |
 | go | `go.mod` | `go.sum` | `safedeps check go <pkg>@<range>` |
 | ruby | `Gemfile` | `Gemfile.lock` | `safedeps check rubygems <pkg>@<range>` |
-| maven | `pom.xml` | (해당 디렉토리) | `safedeps check maven <group>:<artifact>@<range>` |
+| maven | `pom.xml` | (directory) | `safedeps check maven <group>:<artifact>@<range>` |
 | nuget | `*.csproj` | `packages.lock.json` | `safedeps check nuget <pkg>@<range>` |
 
-각 ecosystem 의 typosquat 명단·install script 위험 패턴은 별도 정적 list 로. OSV.dev 가 ecosystem 정규화를 표준화해줘서 single API 결로 모두 cover.
+OSV normalizes ecosystem names, so one API path covers all of them at advisory-check time. Per-ecosystem typosquat lists and install-script risk patterns live in separate static lists. Note that the npm effect gate (closure-vs-ledger enforcement) is npm-only today; the other ecosystems use the command-gate + reorg model.
 
 ---
 
-## 9. 컴포넌트 책임 분리 (SoC)
+## 9. Component responsibilities (SoC)
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  SKILL.md             — Claude/Codex skill loader 가 읽는 SSoT.       │
-│                         hook 선언 + advisory gate 사용법 안내.         │
-├─────────────────────────────────────────────────────────────────────┤
-│  README.md            — 사용자 install 가이드.                         │
-├─────────────────────────────────────────────────────────────────────┤
-│  ARCHITECTURE.md      — 이 문서. 내부 흐름·설계.                       │
-├─────────────────────────────────────────────────────────────────────┤
-│  bin/safedeps         — CLI entry (advisory check, ledger 관리,        │
-│                         재검증 등).                                    │
-├─────────────────────────────────────────────────────────────────────┤
-│  scripts/safedeps-pre-guard.sh — PreToolUse hook. ledger 일치 검증     │
-│                         + v1 의 hardcoded pattern.                    │
-├─────────────────────────────────────────────────────────────────────┤
-│  scripts/safedeps-post-verify.sh — PostToolUse hook. lockfile diff +  │
-│                         spec 비교 + reorg.                             │
-├─────────────────────────────────────────────────────────────────────┤
-│  lib/providers/       — OSV / KEV / GHSA / NVD / deps.dev / Snyk      │
-│                         adapter. 하나의 query interface.               │
-├─────────────────────────────────────────────────────────────────────┤
-│  lib/ledger/          — approved spec ledger I/O. atomic write,        │
-│                         hash 계산, TTL 검사.                           │
-└─────────────────────────────────────────────────────────────────────┘
-```
+| Component | Responsibility |
+|---|---|
+| `SKILL.md` | The SSoT the Claude/Codex skill loader reads — hook declarations + advisory-gate usage. |
+| `README.md` | User install guide. |
+| `ARCHITECTURE.md` | This document — internal flow and design. |
+| `bin/safedeps` | CLI entry — advisory check, ledger management, re-check, migrate. |
+| `scripts/safedeps-pre-guard.sh` | PreToolUse hook — ledger match + v1 hardcoded patterns + snapshots. |
+| `scripts/safedeps-post-verify.sh` | PostToolUse hook — closure-vs-ledger effect gate + reorg. |
+| `lib/providers/` | OSV / KEV / GHSA (and optional NVD / deps.dev / Snyk) adapters behind one query interface. |
+| `lib/ledger/` | Approved-spec ledger I/O — atomic write, hashing, TTL checks. |
+| `lib/npm/closure.sh` | npm closure resolution from a lockfile. |
 
 ---
 
-## 10. 비교 — 기존 도구들과 결 (정확화)
+## 10. How safedeps differs from existing tools
 
-| 도구 | 결 | 동작 시점 | safedeps 와 차이 |
+| Tool | Focus | When | Difference from safedeps |
 |---|---|---|---|
-| `npm audit` | materialized lock 기반 취약점 보고 | post-install | spec 결정 / 차단 안 함, **보고만** |
-| `pip-audit` / `cargo audit` / `bundler-audit` | 같은 결, 다른 ecosystem | post-install | 같음 |
-| **socket.dev** | SaaS risk intelligence (behavioral + static) | pre-install + post-install | 클라우드 의존, 무료 quota 한도, **외부 SaaS** |
-| **lavamoat** | runtime permission containment (sandbox) | runtime | install 전 차단 X, **무겁고 dev 단계 부담** |
-| **pnpm `onlyBuiltDependencies`** | lifecycle script allowlist | install 단계 | typosquat / vuln DB X, **script 차단만** |
-| **deps.dev** | package graph metadata | query only | active gate 아님, **데이터만** |
-| **OSV-Scanner** | OSV 결 lockfile 스캔 | post-install (CI) | spec gate X, **lockfile 리포트만** |
-| **GitHub Dependabot** | PR 기반 dep update 권장 | repo-level (PR) | local install 차단 X, **PR 단계만** |
-| **`safedeps` (이것)** | **advisory gate + approved spec ledger + post-install reorg** | **pre-install + install + post-install** | **3-phase, multi-ecosystem, 로컬 first** |
-
-차별점 요약:
-- 다른 도구는 \"보고\" / \"sandbox\" / \"script 차단\" / \"PR 권장\" 중 하나에 집중.
-- safedeps 는 **\"advisory gate (Phase 1) → hook enforcement (Phase 2) → reorg fallback (Phase 3)\" 의 3겹 defense-in-depth**.
-- Snyk / socket.dev 와 달리 **SaaS 의존 X, 로컬 + 공개 DB (OSV/KEV/GHSA) 만**.
+| `npm audit` | report vulns from the materialized lock | post-install | reports only; no spec decision or blocking |
+| `pip-audit` / `cargo audit` / `bundler-audit` | same, other ecosystems | post-install | same |
+| socket.dev | SaaS risk intelligence (behavioral + static) | pre/post-install | cloud-dependent, free-quota limited, external SaaS |
+| lavamoat | runtime permission sandbox | runtime | no pre-install block; heavy on the dev loop |
+| pnpm `onlyBuiltDependencies` | lifecycle-script allowlist | install | no typosquat/vuln DB; script blocking only |
+| deps.dev | package graph metadata | query only | data, not an active gate |
+| OSV-Scanner | OSV scan of a lockfile | post-install (CI) | reports the lockfile; no spec gate |
+| GitHub Dependabot | PR-based dep updates | repo (PR) | no local install block; PR stage only |
+| **`safedeps`** | **advisory check + approved-spec ledger + npm effect gate + reorg** | **pre/install/post** | **closure-level enforcement, multi-ecosystem command guard, local-first** |
+
+In short: other tools focus on one of "report," "sandbox," "script-block," or "PR suggestion." safedeps layers advisory check → fast command guard → npm effect gate + reorg into defense-in-depth, and — unlike Snyk or socket.dev — depends on no SaaS, only the local CLI plus public databases (OSV / KEV / GHSA).
 
 ---
 
-## 11. 운영 로그
+## 11. Operational logs
 
 ```bash
-# advisory gate decision (approve / block)
-tail -f ~/.safedeps/advisory.log
-
-# reorg event
-tail -f ~/.safedeps/reorg.log
-
-# 현재 approved specs
-ls -lt ~/.safedeps/approved-specs/
-
-# 특정 spec 의 evidence
-cat ~/.safedeps/approved-specs/sha256-abc123.json | jq '.evidence'
-
-# expired specs (만료된 거 재검증 필요)
-find ~/.safedeps/approved-specs -name '*.json' -exec jq -r 'select(.expires_at < now) | "\(.package)@\(.version) expired \(.expires_at)"' {} \;
-
-# OSV cache 비우기 (강제 re-query)
-rm -rf ~/.safedeps/cache/osv/
+tail -f ~/.safedeps/advisory.log     # advisory-gate decisions (approve / block)
+tail -f ~/.safedeps/reorg.log        # reorg events
+ls -lt ~/.safedeps/approved-specs/   # current approved specs
+jq '.evidence' ~/.safedeps/approved-specs/sha256-abc123.json   # one spec's evidence
+rm -rf ~/.safedeps/cache/osv/        # clear the OSV cache (force re-query)
 ```
 
 ---
 
-## 12. v1 → v2 마이그레이션
+## 12. Legacy / migration: v1 `npm-reorg-guard` → v2
 
-```
-v1 (npm-reorg-guard)                v2 (safedeps)
-────────────────────                ──────────────
-
-~/.npm-reorg-guard/        →        ~/.safedeps/
-~/.claude/skills/                   ~/.claude/skills/
-  npm-reorg-guard/         →          safedeps/
-                                      (old local skill path is not canonical)
-
-scripts/guard.sh           →        scripts/safedeps-pre-guard.sh
-  (typosquat / pattern               + ledger lookup
-   매칭만)                            + v1 pattern 유지
-                                      + namespaced filename
-
-scripts/verify.sh          →        scripts/safedeps-post-verify.sh
-  (lockfile diff + reorg)            + approved spec diff
-                                      + v1 reorg 유지
-                                      + namespaced filename
-
-(없음)                     →        bin/safedeps  ← 새 CLI
-                                      check / approve / revoke /
-                                      re-check / ledger
-
-(없음)                     →        lib/providers/  ← OSV / KEV / GHSA / ...
-(없음)                     →        lib/ledger/    ← approved spec I/O
-
-GitHub repo:
-  aldegad/npm-reorg-guard  →        aldegad/safedeps
-                                      (GitHub redirect only)
-```
+| v1 (`npm-reorg-guard`) | v2 (`safedeps`) |
+|---|---|
+| `~/.npm-reorg-guard/` | `~/.safedeps/` |
+| `~/.claude/skills/npm-reorg-guard/` | `~/.claude/skills/safedeps/` |
+| `scripts/guard.sh` (pattern match only) | `scripts/safedeps-pre-guard.sh` (+ ledger lookup, namespaced) |
+| `scripts/verify.sh` (lockfile diff + reorg) | `scripts/safedeps-post-verify.sh` (+ approved-spec diff, namespaced) |
+| — | `bin/safedeps` — new CLI (check / approve / revoke / re-check / ledger) |
+| — | `lib/providers/`, `lib/ledger/` |
+| GitHub `aldegad/npm-reorg-guard` | `aldegad/safedeps` (redirect only) |
 
-v1 migration:
-- v1 hook 등록 path (`~/.claude/skills/npm-reorg-guard/scripts/*.sh`) 는 canonical 이 아니다. settings 는 `~/.claude/skills/safedeps/scripts/*.sh` 로 갱신한다.
-- v1 의 `~/.npm-reorg-guard/` 디렉토리 발견 시 `~/.safedeps/` 으로 마이그레이션한다 (snapshot chain 보존).
-- v1 사용자는 `safedeps migrate` 한 줄로 ledger 신규 생성 + 기존 confirmed snapshot 들을 그대로 approved spec 으로 변환.
+Migration:
+
+- The v1 hook path (`~/.claude/skills/npm-reorg-guard/scripts/*.sh`) is not canonical; settings point at `~/.claude/skills/safedeps/scripts/*.sh`.
+- When a `~/.npm-reorg-guard/` directory is found, its state migrates to `~/.safedeps/` (snapshot chain preserved).
+- A v1 user runs `safedeps migrate` once: it creates the ledger and carries existing confirmed snapshots over.
 
 ---
 
-## 13. 한계 + 미래 방향
+## 13. Limits and future direction
 
-**현재 한계 (v2 첫 출시)**:
-- approved_at 이후 발견된 zero-day 는 daily re-check 로만 catch.
-- npm/PyPI 같은 registry 자체 손상 시 우리도 못 막음.
-- KEV 는 24h 단위 update — 그 사이 새 KEV 등재 못 잡음.
-- transitive dep 의 vuln 검사는 ledger 폭증 가능 (수백 개 dep). 최적화 필요.
+**Current limits:**
 
-**미래 확장**:
-- **plugin model** — 사용자 정의 provider (회사 내부 vuln DB, private registry).
-- **policy file** — `.safedeps.toml` 로 \"우리 팀 정책: KEV hit 자동 block, CVSS 7+ 는 사용자 컨펌\" 같이 명시.
-- **CI mode** — `safedeps check --ci` 로 GitHub Actions / CircleCI 등에서 fail fast.
-- **multi-machine ledger sync** — 팀 차원의 approved spec 공유.
-- **deps.dev graph 활용** — transitive dep 의 \"위험 score\" 시각화.
-- **AI agent integration** — Claude / Codex 가 \"이 패키지 알려진 vuln 있음, 대체 모듈 X 권장\" 결로 직접 제안.
+- A zero-day discovered after `approved_at` is caught only by the daily re-check.
+- A compromise of the registry itself (npm/PyPI/…) is out of reach.
+- KEV updates once a day; a KEV listed in between is not caught until the next refresh.
+- Transitive-closure checking can grow the ledger to hundreds of entries; this needs optimization.
 
----
+**Future direction** (see [`ROADMAP.md`](./ROADMAP.md)):
 
-*문서 history*: v1 (`npm-reorg-guard`) 2026-05-18 작성 → v2 (`safedeps`) 2026-05-18 재작성. 코덱시 (surface:195) 와 클로디시 (surface:61) peer-question 합의안 기반.
+- Effect-based closure enforcement for the non-npm ecosystems.
+- Ledger tamper resistance (OSV-as-authority + tamper detection; no local signing).
+- Plugin providers, a `.safedeps.toml` policy file, CI mode, multi-machine ledger sync, and agent-suggested safe replacements.