@aldegad/safedeps 2.4.1 → 2.5.1

package/ARCHITECTURE.md

@@ -43,7 +43,7 @@ safedeps owns security gates at two distinct moments, under one skill. It absorb
 
 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 secret-leak side of the release-time lane is per-repo and opt-in.** Its detection policy lives in the target repo, not in safedeps, so it does nothing until the repo provides a `.gitleaks` config and an active `.githooks/pre-commit`. `safedeps doctor` is the repo-entry diagnostic that closes that gap: it reports each piece of the secret-leak lane (`.gitleaks` policy, `pre-commit`, `core.hooksPath`, scanner availability) plus the global install-time gate, and exits non-zero when the per-repo lane has gaps. `safedeps doctor --fix` (= `safedeps hooks init` then `safedeps hooks install`) scaffolds a starter policy from `lib/gates/templates/` and activates the hooks. The scaffold is **non-destructive** — an existing repo-owned config is never overwritten — preserving the invariant that safedeps owns *execution*, not *policy*. The scaffolded `pre-commit` delegates to `safedeps scan secrets --staged` (a single canonical scanner path) and is fail-closed: an unresolvable `safedeps` or missing scanner blocks the commit rather than skipping silently.
+**The secret-leak side of the release-time lane is per-repo and opt-in.** Its detection policy lives in the target repo, not in safedeps, so it does nothing until the repo provides a `.gitleaks` config and an active `.githooks/pre-commit`. `safedeps doctor` is the repo-entry diagnostic that closes that gap: it reports each piece of the secret-leak lane (`.gitleaks` policy, `pre-commit`, `core.hooksPath`, scanner availability) plus the global install-time gate, and exits non-zero when the per-repo lane has gaps. `safedeps doctor --fix` (= `safedeps hooks init` then `safedeps hooks install`) scaffolds a starter policy from `lib/gates/templates/` and activates the hooks. The scaffold is **non-destructive** — an existing repo-owned config is never overwritten — preserving the invariant that safedeps owns *execution*, not *policy*. The scaffolded `pre-commit` runs two checks. The secret scan (`safedeps scan secrets --staged`) runs on every commit and is fail-closed: an unresolvable `safedeps` or a missing scanner blocks rather than skipping silently. The npm dependency audit (`safedeps audit npm`) also runs on every commit in a repo with an npm lockfile — not only when the lockfile changes — so a CVE disclosed *after* a package was installed is caught at the next commit by re-querying the advisory DB. The audit separates the security verdict from an availability failure via meaningful exit codes (0 clean / 1 vulnerable / 2 could-not-run): a real finding **blocks** (fail-closed), while an unreachable advisory DB makes the hook **warn and allow the commit** — an explicit, observable availability failover (per the no-silent-fallback invariant: it is logged to the commit output and does not change canonical truth), with CI and the daily re-check re-covering what the offline commit could not verify.
 
 **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.
 

package/README.ko.md

@@ -1,18 +1,41 @@
-# Safedeps
+# safedeps
 
-> **모든 install 을 미확정 블록으로 본다 — `safedeps` 는 안전한 것만 승인하고, 그렇지 않으면 reorg 한다.**
+> **AI 코딩 에이전트가 취약하거나 미승인된 의존성을 설치하지 못하게 막고, 빠져나간 건 롤백한다.**
 >
-> OSV / CISA KEV / GitHub Advisory 로 의존성 spec 을 사전 승인하고, Claude Code 와 Codex CLI 의 hook 에서 실제 설치 closure 를 강제하며, 승인과 어긋난 install 은 자동으로 마지막 안전 snapshot 으로 롤백한다.
+> `safedeps` 는 Claude Code·Codex CLI 에이전트가 실행하는 모든 의존성 install 을 게이트한다. 패키지를 OSV / CISA KEV / GitHub Advisory 로 사전 승인하고, 실제로 lockfile 에 깔린 closure 를 다시 검증하며, 어긋난 건 자동으로 롤백한다. 전부 로컬에서 돌고 런타임 의존성은 0.
+
+- **사전 승인** — 모든 `pkg@version` 과 (npm 은) 그 전체 transitive closure 를 설치 *전에* OSV(정본)·CISA KEV·GitHub Advisory 로 검사한다.
+- **실제 effect 강제** — 설치 후 실제 `package-lock.json` closure 를 다시 확인하므로, 래핑·난독화된 명령도 게이트를 못 빠져나간다.
+- **롤백** — 미승인·신규 취약 패키지는 마지막 확정 안전 snapshot 으로 되돌린다. Claude Code 에서는 install 이 inert(`--ignore-scripts`)로 돌아 거부된 패키지의 lifecycle script 가 아예 실행되지 않는다.
+
+## Quickstart
+
+```bash
+# 1. CLI 설치 — npm 패키지는 scoped, @aldegad/ 접두사 주의
+npm install -g @aldegad/safedeps
+
+# 2. Claude Code / Codex 에 hook 연결 (idempotent)
+cd "$(npm root -g)/@aldegad/safedeps" && node scripts/install/install-safedeps-hooks.mjs
+
+# 3. 끝 — 이제 에이전트가 실행하는 모든 의존성 install 이 자동으로 게이트된다.
+```
+
+> `safedeps` 는 CLI 명령어이고, npm 패키지는 **`@aldegad/safedeps`** 다 — npm 의 unscoped `safedeps` 는 무관한 남의 패키지. 전체 skill 소스 트리를 원하면 [설치](#설치) 참고.
 
 *Detailed reference → [README.md](./README.md) (영문, SSoT)*
 
 ---
 
-## "reorg" 는 뭐고 왜 그 비유인가
+## 배포 모델
 
-블록체인에서 **reorg (재편성)** 은 미확정 블록 시퀀스를 무효화하고 마지막 확정된 안전 상태로 체인을 되돌린다. `safedeps` 는 같은 원리를 `node_modules` 에 적용한다 — 모든 install 은 일련의 공급망 보안 검사를 통과하기 전까지는 **미확정 블록 후보** 로 취급된다. 의심스러우면 도구가 **reorg** 를 수행한다 — lock 파일, `package.json`, `node_modules` 를 마지막 확정된 안전 snapshot 으로 되돌린다.
+safedeps 에는 두 배포 surface 가 있다:
 
-빠른 advisory 피드백, 관측 가능한 rollback, silent fallback 없음. command guard 는 best-effort UX 이고, 설치 결과 effect 가 backstop 이다.
+1. **Agent skill + hooks (canonical)** -- repo 자체가 skill folder 다. `SKILL.md`, hook script, provider/ledger library, install helper 가 한 디렉터리에 함께 있다.
+2. **npm package (CLI convenience)** -- `@aldegad/safedeps` 는 `safedeps` command 를 설치한다. npm 설치만으로 Claude Code 나 Codex 가 skill 을 자동 discover 하지는 않는다. npm 설치 후에도 hook/skill installer 를 실행하거나 skill folder 를 수동 등록해야 한다.
+
+전체 skill/hook source tree 를 canonical artifact 로 원하면 GitHub release 를 쓴다. versioned global CLI 가 주목적이면 npm 을 쓴다.
+
+용어: safedeps 는 Claude/Codex hook 과 local CLI 로 동작하는 agent security skill 이다. plugin manifest 로 감싸기 전까지는 Codex plugin bundle 이 아니다.
 
 ---
 
@@ -23,7 +46,7 @@
 - **install-time** (이 README 의 초점) — advisory check + approved-spec ledger + 빠른 PreToolUse guard + PostToolUse effect enforcement + post-install reorg. 패키지 단위, install 명령과 실제 lockfile effect 주변.
 - **release-time** — `safedeps gates run`, `safedeps scan secrets [--repo|--worktree|--staged]`, `safedeps audit npm`, `safedeps hooks install|check`. repo 트리 secret scan, 의존성 audit, repo-local git hook 설치/검사 (push/release 전). repo-specific policy(gitleaks config, privacy 경로)는 대상 repo 에 남고 safedeps 는 실행 owner. *(옛 `security-release-gates` 흡수.)*
 
-release-time lane 의 secret 누출 쪽은 **repo 별이고 opt-in** 이다. `safedeps doctor` 가 그 repo-entry 점검이다 — repo 의 `.gitleaks` policy, `.githooks/pre-commit`, 활성 `core.hooksPath`, scanner 가용성을 진단하고(전역 install-time gate 상태도 같이 보고), `safedeps doctor --fix` 가 시작 policy 를 scaffold(`safedeps hooks init`)하고 활성화(`safedeps hooks install`)한다. scaffold 는 비파괴적이라 repo 가 소유한 기존 `.gitleaks.toml` 은 덮어쓰지 않으며, pre-commit hook 은 `safedeps scan secrets --staged` 에 위임하고 fail-closed 다. [secret 누출 lane (repo 별)](#secret-누출-lane-repo-별) 참고.
+release-time lane 의 secret 누출 쪽은 **repo 별이고 opt-in** 이다. `safedeps doctor` 가 그 repo-entry 점검이다 — repo 의 `.gitleaks` policy, `.githooks/pre-commit`, 활성 `core.hooksPath`, scanner 가용성을 진단하고(전역 install-time gate 상태도 같이 보고), `safedeps doctor --fix` 가 시작 policy 를 scaffold(`safedeps hooks init`)하고 활성화(`safedeps hooks install`)한다. scaffold 는 비파괴적이라 repo 가 소유한 기존 `.gitleaks.toml` 은 덮어쓰지 않으며, pre-commit hook 은 매 커밋 비밀키 스캔(`safedeps scan secrets --staged`)을 돌리고 npm repo 면 매 커밋 의존성 audit(`safedeps audit npm`)도 돌린다 — 실제 취약점은 차단(fail-closed)하고, 어드바이저리 DB 도달 불가 시에는 경고만 하고 커밋을 통과시킨다(관측 가능한 오프라인 failover). [secret 누출 lane (repo 별)](#secret-누출-lane-repo-별) 참고.
 
 ---
 
@@ -106,7 +129,11 @@ lane 구성 요소:
 
 - **`safedeps hooks init`** 가 시작용 `.gitleaks.toml`(private repo 면 `.gitleaks.private.toml`)과 `.githooks/pre-commit` 을 scaffold 한다. 기존 파일은 덮지 않고 유지 — policy 는 repo 가 소유한다.
 - **`safedeps hooks install`** 이 repo-local hook 을 활성화한다(`core.hooksPath = .githooks`).
-- **pre-commit hook 은 `safedeps scan secrets --staged` 에 위임**하고 **fail-closed** 다: scanner(로컬 `gitleaks` 또는 Docker)가 못 돌면 silent skip 이 아니라 커밋을 막는다. 의도된 우회는 사람이 소유하는 `git commit --no-verify` 뿐이다.
+- **pre-commit hook 은 두 검사를 돌린다**:
+  - **비밀키 스캔**(`safedeps scan secrets --staged`)을 매 커밋, **fail-closed**. scanner(로컬 `gitleaks` 또는 Docker)가 못 돌면 silent skip 이 아니라 커밋을 막는다.
+  - **npm 의존성 audit**(`safedeps audit npm`)을 npm lockfile 이 있는 repo 면 **매 커밋**. 취약한 직접·*transitive* 의존성을 잡는다 — 패키지를 깐 *뒤에* 공개된 CVE("그땐 안전해 보였는데 지금 발견됨")까지 포함해서, 사람이 손으로 절대 못 보는 그것. lockfile 이 바뀔 때만이 아니라 매 커밋 돌리는 게 핵심이다: 어드바이저리 DB 를 다시 조회하니까 이미 깔린 의존성에 *새로* 뜬 CVE 가 바로 다음 커밋에 드러난다. 보안 판정과 가용성 실패는 구분된다 — 실제 취약점은 **차단**(fail-closed)하지만, 어드바이저리 DB 가 **도달 불가**(오프라인/레지스트리 오류)면 **경고만 하고 커밋을 통과**시킨다(관측 가능한 가용성 failover, silent skip 아님). 오프라인 커밋이 못 본 건 CI 와 데일리 re-check 가 다시 메운다.
+
+  의도된 우회는 사람이 소유하는 `git commit --no-verify` 뿐이다.
 
 scaffold 된 `.gitleaks.toml` 은 **네가 손보는 시작점**이다: gitleaks 기본 ruleset 을 extend 하고, 값이 할당된 `.env` 커밋을 잡는 rule 을 더하며(`.env.example`/`.sample`/`.template` 변형은 allowlist), fixture 용 repo-owned `[allowlist]` 블록을 남겨둔다. safedeps 는 *실행* — `safedeps scan secrets` 로 gitleaks 구동 — 만 소유하고 policy 내용은 소유하지 않는다.
 
@@ -176,6 +203,14 @@ node scripts/install/install-safedeps-recheck-agent.mjs install --hour 9 --minut
 
 ---
 
+## "reorg" 는 뭐고 왜 그 비유인가
+
+블록체인에서 **reorg (재편성)** 은 미확정 블록 시퀀스를 무효화하고 마지막 확정된 안전 상태로 체인을 되돌린다. `safedeps` 는 모든 install 을 똑같이 본다 — 일련의 공급망 보안 검사를 통과하기 전까지는 미확정 블록 후보다. 설치된 effect 가 어긋나면 도구가 **reorg** 를 수행한다 — lock 파일, `package.json`, `node_modules` 를 마지막 확정된 안전 snapshot 으로 되돌린다.
+
+하지만 reorg 는 **최전선이 아니라 backstop 이다.** 나쁜 install 의 대부분은 여기까지 오지도 않는다 — 사전 승인 게이트가 미승인·플래그된 패키지를 실행 전에 *거부* 하고, Claude Code 에서는 install 이 **inert (`--ignore-scripts`)** 로 돌아 closure 가 깨끗하다고 검증되기 전까지 lifecycle script 가 실행되지 않는다. reorg 가 발동하는 건 잔여 케이스뿐이다 — 승인된 직접 패키지가 미승인·취약 transitive 를 끌어오거나, 래핑된 명령이 advisory 계층을 빠져나간 경우 — 그리고 그때조차 실행되지도 못한 파일을 되돌린다.
+
+빠른 advisory 피드백, 관측 가능한 rollback, silent fallback 없음. command guard 는 best-effort UX 이고, 설치 결과 effect 가 backstop 이다.
+
 ## 다른 도구와 뭐가 다른가
 
 `safedeps` 는 **AI 에이전트가 코딩 중 install 명령을 작성하는 순간**에 끼어드는 도구다. CI 스캔, PR 권장, runtime sandbox 처럼 다른 시점에서 동작하는 도구들과 핵심 차별점이 여기 있다.

package/README.md

@@ -1,14 +1,28 @@
-# Safedeps
+# safedeps
 
-> **Treat every install as an unconfirmed block — `safedeps` approves the safe ones, reorgs the rest.**
+> **Stop your AI coding agent from installing vulnerable or unapproved dependencies — and roll back the ones that slip through.**
 >
-> Pre-approve dependency installs against OSV / CISA KEV / GitHub Advisory, enforce the installed closure from Claude Code and Codex CLI hooks, and auto-rollback any install that diverges from the approved closure. *(한국어 README → [README.ko.md](./README.ko.md))*
+> `safedeps` gates every dependency install your Claude Code or Codex CLI agent runs. It pre-approves packages against OSV / CISA KEV / GitHub Advisory, re-verifies the closure that actually lands in your lockfile, and auto-rolls-back anything that diverges. Local-only, with zero runtime dependencies. *(한국어 README → [README.ko.md](./README.ko.md))*
 
-## Why "reorg"?
+- **Pre-approve** — every `pkg@version`, plus its full transitive closure for npm, is cleared against OSV (canonical), CISA KEV, and GitHub Advisory *before* it installs.
+- **Enforce the real effect** — after the install, the actual `package-lock.json` closure is re-checked, so a wrapped or obfuscated command can't sneak a package past the gate.
+- **Roll back** — anything unapproved or newly-vulnerable is reverted to the last confirmed safe snapshot. On Claude Code the install runs inert (`--ignore-scripts`), so a rejected package's lifecycle scripts never run.
 
-In blockchain networks, a **reorganization (reorg)** invalidates a sequence of blocks and reverts the chain to a previously confirmed safe state. `safedeps` applies the same principle to your `node_modules`: every install is treated as an unconfirmed block candidate until it passes a battery of supply-chain security checks. If anything looks wrong, the tool performs a **reorg** -- rolling back lock files, `package.json`, and `node_modules` to the last confirmed safe snapshot.
+## Quickstart
 
-Fast advisory feedback, observable rollback, and no hidden fallback. The command guard is best-effort UX; the installed effect is the backstop.
+```bash
+# 1. Install the CLI — the npm package is scoped, note the @aldegad/ prefix
+npm install -g @aldegad/safedeps
+
+# 2. Wire the hooks into Claude Code / Codex (idempotent)
+cd "$(npm root -g)/@aldegad/safedeps" && node scripts/install/install-safedeps-hooks.mjs
+
+# 3. Done — every dependency install your agent runs is now gated.
+```
+
+> `safedeps` is the CLI command; the npm package is **`@aldegad/safedeps`** — the unscoped `safedeps` on npm is an unrelated package. Prefer the full skill source tree? See [Installation](#installation).
+
+<!-- TODO(demo): add a 15-20s asciinema/VHS recording of safedeps catching a malicious install live (inert -> reorg). Highest-leverage conversion asset per launch review. -->
 
 ## Distribution Model
 
@@ -19,6 +33,8 @@ Safedeps has two distribution surfaces:
 
 Use the GitHub release when you want the full skill/hook source tree as the canonical artifact. Use npm when you mainly want a versioned global CLI.
 
+Terminology: safedeps is an agent security skill backed by Claude/Codex hooks and a local CLI. It is not a Codex plugin bundle unless it is later wrapped with a plugin manifest.
+
 ## Two Lanes
 
 `safedeps` owns two security lanes (full design in [`ARCHITECTURE.md`](./ARCHITECTURE.md) §1):
@@ -26,7 +42,7 @@ Use the GitHub release when you want the full skill/hook source tree as the cano
 - **Install-time** (the focus of this README) — advisory check + approved-spec ledger + fast PreToolUse guard + PostToolUse effect enforcement + post-install reorg. Per-package, around the install command and its actual lockfile effect.
 - **Release-time** — `safedeps gates run`, `safedeps scan secrets [--repo|--worktree|--staged]`, `safedeps audit npm`, `safedeps hooks install|check`. Repo-tree secret scan, dependency audit, and repo-local git hook install/check before push/release. Repo-specific policy (gitleaks config, privacy paths) stays in the target repo; safedeps owns execution. *(Absorbed the former `security-release-gates`.)*
 
-The secret-leak side of the release-time lane is **per-repo and opt-in**. `safedeps doctor` is its repo-entry check: it diagnoses the repo's `.gitleaks` policy, `.githooks/pre-commit`, the active `core.hooksPath`, and scanner availability (and reports the global install-time gate too), then `safedeps doctor --fix` scaffolds a starter policy (`safedeps hooks init`) and activates it (`safedeps hooks install`). The scaffold is non-destructive — an existing repo-owned `.gitleaks.toml` is never overwritten — and the pre-commit hook delegates to `safedeps scan secrets --staged`, fail-closed. See [Secret-Leak Lane (per-repo)](#secret-leak-lane-per-repo).
+The secret-leak side of the release-time lane is **per-repo and opt-in**. `safedeps doctor` is its repo-entry check: it diagnoses the repo's `.gitleaks` policy, `.githooks/pre-commit`, the active `core.hooksPath`, and scanner availability (and reports the global install-time gate too), then `safedeps doctor --fix` scaffolds a starter policy (`safedeps hooks init`) and activates it (`safedeps hooks install`). The scaffold is non-destructive — an existing repo-owned `.gitleaks.toml` is never overwritten — and the pre-commit hook runs a secret scan (`safedeps scan secrets --staged`) plus, on every commit in an npm repo, a dependency audit (`safedeps audit npm`): a real finding blocks (fail-closed), while an unreachable advisory DB only warns and lets the commit through (observable offline failover). See [Secret-Leak Lane (per-repo)](#secret-leak-lane-per-repo).
 
 ## How It Works
 
@@ -113,6 +129,14 @@ After the install command completes, the verify hook analyzes what changed. For
   4. The event is logged to `~/.safedeps/reorg.log`.
   5. Claude Code receives a system message detailing the detected threats and rollback actions.
 
+## Why "reorg"?
+
+The name borrows from blockchain, where a **reorganization (reorg)** invalidates a sequence of unconfirmed blocks and reverts the chain to its last confirmed safe state. `safedeps` treats every install the same way: an unconfirmed block candidate until it passes a battery of supply-chain checks. If the installed effect diverges, the tool performs a **reorg** -- rolling the lock file, `package.json`, and `node_modules` back to the last confirmed safe snapshot.
+
+But the reorg is the **backstop, not the front line.** Most bad installs never reach it: the pre-approval gate *denies* an unapproved or flagged package before it runs, and on Claude Code the install runs **inert** (`--ignore-scripts`) so lifecycle scripts do not execute until the closure verifies clean. The reorg fires for the residual case -- an approved direct package that pulls in an unapproved or vulnerable transitive, or a wrapped command that slips past the advisory layer -- and even then it rolls back files that never got to run.
+
+Fast advisory feedback, observable rollback, and no hidden fallback. The command guard is best-effort UX; the installed effect is the backstop.
+
 ## The Blockchain Analogy
 
 | Blockchain Concept | Safedeps Equivalent |
@@ -175,7 +199,11 @@ What the lane is made of:
 
 - **`safedeps hooks init`** scaffolds a starter `.gitleaks.toml` (or `.gitleaks.private.toml` for a private repo) and a `.githooks/pre-commit`. Existing files are kept, never overwritten — the repo owns the policy.
 - **`safedeps hooks install`** activates the repo-local hooks (`core.hooksPath = .githooks`).
-- The **pre-commit hook delegates to `safedeps scan secrets --staged`** and is **fail-closed**: if the scanner (local `gitleaks` or Docker) cannot run, it blocks the commit instead of skipping silently. The only intentional bypass is `git commit --no-verify`, which the human owns.
+- The **pre-commit hook runs two checks**:
+  - **Secret scan** (`safedeps scan secrets --staged`) on every commit, **fail-closed**. If the scanner (local `gitleaks` or Docker) cannot run, it blocks the commit instead of skipping silently.
+  - **npm dependency audit** (`safedeps audit npm`) on **every commit** in a repo that has an npm lockfile. This catches a vulnerable direct *or transitive* dependency — including a CVE that was published *after* you installed the package ("looked safe then, flagged now"), the kind of thing a human never reviews by hand. Running it every commit (not only when the lockfile changes) is the point: it re-queries the advisory DB so a newly-disclosed CVE on an already-installed dependency surfaces at the very next commit. The verdict and an availability failure are kept apart: a real finding **blocks** (fail-closed), but if the advisory DB is **unreachable** (offline / registry error) the hook **warns and lets the commit through** — an observable availability failover, never a silent skip. (CI and the daily re-check then re-cover what the offline commit could not verify.)
+
+  The only intentional bypass is `git commit --no-verify`, which the human owns.
 
 The scaffolded `.gitleaks.toml` is a **starter you tune**: it extends gitleaks' default ruleset, adds a rule for a committed `.env` with an assigned secret (the `.env.example`/`.sample`/`.template` variants are allowlisted), and leaves a repo-owned `[allowlist]` block for your fixtures. safedeps owns *execution* — running gitleaks via `safedeps scan secrets` — not the policy content.
 

package/ROADMAP.md

@@ -56,7 +56,7 @@ The internal engine keeps the v1 `reorg-guard` assets.
 
 ### Release notes
 
-- The npm package version in `package.json` is the single source of truth. `bin/safedeps` `SAFEDEPS_VERSION` tracks it and the smoke test reads `package.json` to compare (current: v2.4.1).
+- The npm package version in `package.json` is the single source of truth. `bin/safedeps` `SAFEDEPS_VERSION` tracks it and the smoke test reads `package.json` to compare (current: v2.5.0).
 - `npm test` runs the release smoke suite; the full fixture E2E lives under `v2.1-tests`.
 - The daily re-check uses no LLM tokens. It is opt-in: a macOS `launchd` user agent runs `safedeps re-check --json` daily, installed atomically by `install-safedeps-recheck-agent.mjs`. It writes `~/.safedeps/recheck.log` and `~/.safedeps/recheck-alerts.jsonl` and raises a macOS notification on a new CVE/KEV/revoke/provider-skip. Network is used only for OSV / CISA / GHSA queries.
 
@@ -140,6 +140,24 @@ The pending state PreToolUse hands to PostToolUse was a single global `current_s
 
 ---
 
+## v2.5 — pre-commit dependency audit (shipped)
+
+Status: shipped as v2.5.0.
+
+### What changed
+
+- **Pre-commit dependency audit** — the scaffolded `.githooks/pre-commit` now runs `safedeps audit npm` on **every commit** in a repo with an npm lockfile, alongside the secret scan. It catches a vulnerable direct or *transitive* dependency — including a CVE disclosed *after* the package was installed ("looked safe then, flagged now") — at the next commit, by re-querying the advisory DB instead of waiting for the daily re-check. Real usage drove it: a transitive `hono` advisory that Dependabot missed was caught exactly this way.
+- **Meaningful `audit npm` exit codes** — `0` clean / `1` vulnerable / `2` could-not-run (no lockfile, npm/jq missing, advisory DB unreachable). This separates the **security verdict** from an **availability failure**; npm audit collapses both into exit 1 on its own.
+- **Observable offline failover** — when the advisory DB is unreachable the hook **warns and allows** the commit (exit 2) rather than fail-closing, so a network outage never blocks an offline commit; a real finding (exit 1) still **blocks**. Per the no-silent-fallback invariant the failover is loud (printed to the commit output), and CI / the daily re-check re-cover what the offline commit could not verify.
+
+### Verification
+
+- `audit npm` exit-code contract (clean=0 / vulnerable=1 / unreachable=2), deterministic via a fake npm
+- pre-commit blocks a commit carrying a vulnerable dependency; warns + allows when the advisory DB is unreachable
+- existing secret-lane + smoke + e2e regression suite remains green
+
+---
+
 ## v3 (future)
 
 ### Ledger tamper resistance

package/SKILL.md

@@ -10,7 +10,9 @@ hooks:
 
 # Safedeps
 
-Two gates, one skill. You (the agent) are the primary user — drive both:
+Two gates, one skill. Safedeps is an agent security skill backed by Claude/Codex hooks and a local CLI. It is not a Codex plugin bundle unless it is later wrapped with a plugin manifest.
+
+You (the agent) are the primary user — drive both:
 
 - **Install-time gate** — clear every dependency install through an OSV-backed advisory check before it runs.
 - **Secret-leak gate** — stop a secret or a real `.env` from being committed (per-repo).
@@ -71,7 +73,7 @@ safedeps doctor --fix    # scaffold the policy + activate the hooks (non-destruc
 2. Gaps? Run `safedeps doctor --fix`. It scaffolds `.gitleaks.toml` (or `.gitleaks.private.toml`) and `.githooks/pre-commit`, then activates them. Existing repo files are never overwritten.
 3. Tune the scaffolded `.gitleaks.toml` for the repo — allowlist fixtures, add rules. You own the policy; safedeps runs it (gitleaks via `safedeps scan secrets`).
 
-The pre-commit hook delegates to `safedeps scan secrets --staged` and is **fail-closed**: no scanner → it blocks the commit. The only bypass is the human's `git commit --no-verify`.
+The pre-commit hook runs two checks: a secret scan (`safedeps scan secrets --staged`) on every commit (fail-closed), and an npm dependency audit (`safedeps audit npm`) on every commit in an npm repo — so a CVE published *after* you installed a package is caught at the next commit, not weeks later. `audit npm` exits 0 clean / 1 vulnerable / 2 could-not-run; the hook **blocks** on a real finding (1) but **warns and allows** when the advisory DB is unreachable (2 — observable offline failover). No secret scanner → blocks. The only bypass is the human's `git commit --no-verify`.
 
 ---
 

package/bin/safedeps

@@ -7,7 +7,7 @@
 
 set -euo pipefail
 
-SAFEDEPS_VERSION="2.4.1"
+SAFEDEPS_VERSION="2.5.1"
 
 # ---- repo / lib bootstrap ----------------------------------------------------
 

package/lib/gates/audit.sh

@@ -3,7 +3,17 @@ set -euo pipefail
 
 # safedeps audit npm — generic npm lockfile audit.
 # Absorbed from kuma-studio scripts/security/run-npm-audit.sh.
-# Missing lockfile stays fail-closed (no reproducible verdict without it).
+#
+# Exit codes are meaningful so a caller (e.g. the pre-commit hook) can tell a
+# security verdict apart from an availability problem — npm audit collapses both
+# into exit 1 on its own:
+#   0  clean — no advisory at or above the audit level
+#   1  vulnerable — at least one advisory at or above the level (BLOCK)
+#   2  could not produce a verdict — no lockfile, npm/jq missing, or the npm
+#      advisory database is unreachable (offline/registry error). This is an
+#      AVAILABILITY failure, not a clean bill of health; the caller decides
+#      whether to fail-closed or warn-and-continue.
+#  64  usage error
 
 REPO_ROOT=""
 AUDIT_LEVEL="${SAFEDEPS_NPM_AUDIT_LEVEL:-${KUMA_NPM_AUDIT_LEVEL:-moderate}}"
@@ -26,11 +36,53 @@ if [ -z "$REPO_ROOT" ]; then REPO_ROOT="$(pwd)"; fi
 REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
 cd "$REPO_ROOT"
 
-if [ ! -f package-lock.json ]; then
-  cat >&2 <<'EOF'
-ERROR: package-lock.json is missing, so npm audit cannot produce a reproducible dependency verdict.
-EOF
-  exit 1
+if [ ! -f package-lock.json ] && [ ! -f npm-shrinkwrap.json ]; then
+  printf 'safedeps audit: no package-lock.json/npm-shrinkwrap.json — cannot produce a reproducible verdict.\n' >&2
+  exit 2
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  printf 'safedeps audit: npm not found — cannot produce a dependency verdict.\n' >&2
+  exit 2
 fi
 
-exec npm audit --audit-level="$AUDIT_LEVEL"
+# Without jq we cannot reliably separate an offline failure from a real finding,
+# so degrade to a plain, fail-closed audit: any non-zero exit blocks (safe).
+if ! command -v jq >/dev/null 2>&1; then
+  npm audit --audit-level="$AUDIT_LEVEL"
+  exit $?
+fi
+
+# One JSON run. npm audit shares exit 1 between "vulnerable" and "could not run",
+# so we read the verdict from the payload, not the exit code.
+audit_json="$(npm audit --json 2>/dev/null || true)"
+
+# Unreachable advisory DB / setup error → npm emits a top-level {"error":...},
+# or no/invalid JSON. Availability failure, not a verdict.
+if [ -z "$audit_json" ] \
+   || ! printf '%s' "$audit_json" | jq -e . >/dev/null 2>&1 \
+   || printf '%s' "$audit_json" | jq -e 'has("error")' >/dev/null 2>&1; then
+  printf 'safedeps audit: could not reach the npm advisory database (offline or registry error).\n' >&2
+  exit 2
+fi
+
+# Count advisories at or above the configured level.
+n_at_level="$(printf '%s' "$audit_json" | jq --arg lvl "$AUDIT_LEVEL" '
+  (.metadata.vulnerabilities // {}) as $v
+  | ["low","moderate","high","critical"] as $order
+  | (($order | index($lvl)) // 1) as $min
+  | reduce $order[$min:][] as $s (0; . + ($v[$s] // 0))
+')"
+
+if [ "${n_at_level:-0}" -gt 0 ]; then
+  printf '%s' "$audit_json" | jq -r '
+    (.metadata.vulnerabilities // {}) as $v
+    | "  severities: " +
+      ([ "critical","high","moderate","low" ]
+       | map(select(($v[.] // 0) > 0) | "\($v[.]) \(.)") | join(", "))
+  ' >&2
+  printf '%s' "$audit_json" | jq -r '(.vulnerabilities // {}) | keys[] | "  - " + .' 2>/dev/null | head -20 >&2 || true
+  printf 'safedeps audit: %s advisory(ies) at or above "%s" — blocking. Run `npm audit` for the full report.\n' "$n_at_level" "$AUDIT_LEVEL" >&2
+  exit 1
+fi
+exit 0

package/lib/gates/templates/pre-commit.tmpl

@@ -1,11 +1,17 @@
 #!/bin/bash
-# .githooks/pre-commit — safedeps secret-leak gate (scaffolded by `safedeps hooks init`).
+# .githooks/pre-commit — safedeps repo gate (scaffolded by `safedeps hooks init`).
 #
-# Blocks a commit when gitleaks finds a secret in the STAGED changes, so a key
-# or a real .env never enters the repo's history. The detection POLICY lives in
-# this repo's .gitleaks.toml (public) / .gitleaks.private.toml (private);
-# safedeps owns execution. This hook delegates to one canonical scanner path:
-# `safedeps scan secrets --staged`.
+# Two checks:
+#   1. Secret scan (always, fail-closed) — blocks a commit when gitleaks finds a
+#      secret in the STAGED changes, so a key or a real .env never enters
+#      history. The detection POLICY lives in this repo's .gitleaks.toml
+#      (public) / .gitleaks.private.toml (private); safedeps owns execution.
+#   2. Dependency audit (npm) — on every commit when this repo has an npm
+#      lockfile. Catches a vulnerable direct or *transitive* dependency,
+#      including a CVE published AFTER you installed it ("looked safe then,
+#      flagged now"). A real finding blocks (fail-closed); only the advisory DB
+#      being unreachable (offline) warns and lets the commit through — an
+#      observable availability failover, never a silent skip.
 #
 # Intentional bypass (use sparingly — you own the risk):  git commit --no-verify
 set -euo pipefail
@@ -43,7 +49,30 @@ EOF
   exit 1
 fi
 
-# Delegate to the single canonical scanner. A non-zero exit means either a
-# secret was found OR no scanner (gitleaks/docker) is available — both
-# fail-closed and block the commit.
-exec "${sd}" scan secrets --staged --root "${repo_root}"
+# 1. Secret scan (always). A non-zero exit means either a secret was found OR
+#    no scanner (gitleaks/docker) is available — both fail-closed, block commit.
+"${sd}" scan secrets --staged --root "${repo_root}"
+
+# 2. Dependency audit (npm) — every commit when this repo has an npm lockfile.
+#    `safedeps audit npm` exit codes: 0 clean / 1 vulnerable / 2 could-not-run.
+#      - vulnerable (1)  → BLOCK (fail-closed on the security verdict).
+#      - unreachable (2) → WARN and ALLOW (availability failover, observable):
+#        an offline commit is never silently dropped, and CI / the daily
+#        re-check still cover what this commit could not verify.
+if [ -f "${repo_root}/package-lock.json" ] || [ -f "${repo_root}/npm-shrinkwrap.json" ]; then
+  if "${sd}" audit npm --root "${repo_root}"; then
+    : # clean — no advisory at or above the audit level.
+  else
+    audit_rc=$?
+    if [ "${audit_rc}" -eq 2 ]; then
+      {
+        printf '\n'
+        printf 'safedeps pre-commit: dependency audit could not reach the advisory DB.\n'
+        printf '  -> commit ALLOWED without a fresh dependency verdict (offline failover).\n'
+        printf '  -> re-run `safedeps audit npm` once online; CI / the daily re-check also cover this.\n'
+      } >&2
+    else
+      exit "${audit_rc}"   # vulnerable (or unknown failure) -> fail-closed.
+    fi
+  fi
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aldegad/safedeps",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "description": "Dependency install safety gate with OSV-backed advisory checks, approved-spec ledger enforcement, and reorg rollback hooks",
   "main": "bin/safedeps",
   "bin": {

package/scripts/install/install-safedeps-hooks.mjs

@@ -219,6 +219,51 @@ function unlinkBin() {
   removeSymlink(join(HOME, ".local", "bin", "safedeps"));
 }
 
+function safedepsOnPath() {
+  const dirs = (process.env.PATH || "").split(":").filter(Boolean);
+  return dirs.some((d) => {
+    try { return existsSync(join(d, "safedeps")); } catch { return false; }
+  });
+}
+
+// The dependency-install gate is global and now active. The rest of the
+// surface (secret-leak lane, dep audit) is per-repo and opt-in — its policy
+// lives in each repo. Nudge with a recommended setup; never auto-write.
+function printRecommendedSetup() {
+  const line = "─".repeat(58);
+  const out = [];
+  out.push("");
+  out.push("Recommended setup");
+  out.push(line);
+  out.push("  1. Dependency-install gate  ........  ✓ active now (global, all repos)");
+  out.push("       Every agent install is checked; for npm the installed");
+  out.push("       closure is reorged (rolled back) if it diverges.");
+  out.push("");
+  out.push("  The rest is per-repo and opt-in. Run these INSIDE a repo:");
+  out.push("");
+  out.push("  2. Pre-commit gate  ...............  recommended");
+  out.push("       safedeps doctor          # diagnose this repo (read-only)");
+  out.push("       safedeps doctor --fix    # scaffold .gitleaks.toml + pre-commit, then activate");
+  out.push("       → every commit: blocks a secret / real .env (fail-closed).");
+  out.push("       → every commit (npm repos): audits deps for vulnerable transitives;");
+  out.push("         a real finding blocks, an offline advisory DB only warns + allows.");
+  out.push("");
+  out.push("  3. Release / CI gate  .............  optional");
+  out.push("       safedeps gates run       # secret scan + npm dep audit + hook/CI check");
+  out.push("       → full-repo sweep for CI / pre-release: scans the whole tree (not just");
+  out.push("         the staged diff) and verifies the hooks themselves are installed.");
+  out.push("");
+  out.push("  Docs: README → \"Two Lanes\"");
+  if (!safedepsOnPath()) {
+    out.push("");
+    out.push("  Note: `safedeps` is not on your PATH. To run the commands above:");
+    out.push("    - re-run this installer with --link-bin (adds ~/.local/bin/safedeps), or");
+    out.push("    - use the full path: ~/.claude/skills/safedeps/bin/safedeps");
+  }
+  out.push("");
+  console.log(out.join("\n"));
+}
+
 function main() {
   if (!existsSync(REPO_PRE_HOOK) || !existsSync(REPO_POST_HOOK)) {
     throw new Error(`hook scripts not found at ${REPO_PRE_HOOK} / ${REPO_POST_HOOK}`);
@@ -242,9 +287,7 @@ function main() {
     log("uninstall done.");
   } else {
     log("install done. New hook events fire on the next session start.");
-    // The dependency-install gate is global. The secret-leak lane is per-repo
-    // and stays opt-in (its policy lives in each repo). Nudge, do not auto-write.
-    log("secret-leak lane is per-repo — in a repo run: safedeps doctor (then `safedeps doctor --fix` to scaffold + activate).");
+    printRecommendedSetup();
   }
 }
 

package/scripts/test/e2e.sh

@@ -190,6 +190,50 @@ EOF
 grep -qx 'rebuild' "${tmp_root}/npm-calls.log" || fail "post hook runs npm rebuild after verified injected install"
 pass "post hook rebuilds after verified inert install"
 
+# Reorg must actually revert the on-disk lockfile, not just print the message. The
+# missing-transitive test below proves the systemMessage; this proves the stronger
+# claim — a tampered lockfile is restored byte-for-byte to the last confirmed safe
+# snapshot on disk. Regression guard so a future change cannot break the rollback
+# while keeping the message green. Stub npm keeps `npm ci` from rewriting the file.
+revert_project="${tmp_root}/revert-project"
+mkdir -p "${revert_project}"
+printf '{"dependencies":{"fixture-parent":"1.0.0"}}\n' > "${revert_project}/package.json"
+cat > "${revert_project}/package-lock.json" <<'EOF'
+{
+  "name": "revert-project",
+  "lockfileVersion": 3,
+  "packages": {
+    "": {"dependencies": {"fixture-parent": "1.0.0"}},
+    "node_modules/fixture-parent": {"version": "1.0.0", "dependencies": {"fixture-child": "1.0.0"}},
+    "node_modules/fixture-child": {"version": "1.0.0"}
+  }
+}
+EOF
+cp "${revert_project}/package-lock.json" "${tmp_root}/revert-safe-lock.json"
+scripts/safedeps-pre-guard.sh > /dev/null <<EOF
+{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"},"cwd":"${revert_project}"}
+EOF
+cat > "${revert_project}/package-lock.json" <<'EOF'
+{
+  "name": "revert-project",
+  "lockfileVersion": 3,
+  "packages": {
+    "": {"dependencies": {"fixture-parent": "1.0.0"}},
+    "node_modules/fixture-parent": {"version": "1.0.0", "dependencies": {"fixture-child": "1.0.0"}},
+    "node_modules/fixture-child": {"version": "1.0.0"},
+    "node_modules/fixture-evil": {"version": "6.6.6", "resolved": "git://evil.example.com/fixture-evil.git"}
+  }
+}
+EOF
+revert_post=$(
+  PATH="${stub_bin}:${PATH}" scripts/safedeps-post-verify.sh <<EOF
+{"tool_name":"Bash","tool_input":{"command":"npm install fixture-parent@1.0.0"},"cwd":"${revert_project}"}
+EOF
+)
+grep -q '의심스러운 패키지 변경 감지' <<< "${revert_post}" || fail "reorg fires on a tampered lockfile"
+cmp -s "${revert_project}/package-lock.json" "${tmp_root}/revert-safe-lock.json" || fail "reorg restores the exact safe lockfile content on disk"
+pass "reorg reverts a tampered lockfile to safe content on disk"
+
 export SAFEDEPS_HOME="${tmp_root}/safe-missing-transitive"
 export SAFEDEPS_OSV_API_URL="http://127.0.0.1:${port}/osv/v1/query"
 export SAFEDEPS_OSV_BATCH_API_URL="http://127.0.0.1:${port}/osv/v1/querybatch"
@@ -225,7 +269,13 @@ EOF
 )
 grep -q '의심스러운 패키지 변경 감지' <<< "${missing_post}" || fail "post hook reorgs unapproved transitive package"
 grep -q 'fixture-child@1.0.0' <<< "${missing_post}" || fail "post hook names unapproved transitive package"
-pass "post hook reorgs unapproved transitive package"
+# Not just the message — the unapproved transitive must be gone from the on-disk
+# lockfile. (Reorg removes the tampered lockfile; a no-network reinstall may recreate
+# an empty one, so assert fixture-child is absent rather than the file itself.)
+if grep -q 'fixture-child' "${missing_project}/package-lock.json" 2>/dev/null; then
+  fail "post hook reorg leaves the unapproved transitive in the on-disk lockfile"
+fi
+pass "post hook reorgs unapproved transitive package (verified on disk)"
 
 export SAFEDEPS_HOME="${tmp_root}/safe"
 export SAFEDEPS_OSV_API_URL="http://127.0.0.1:${port}/osv/v1/query"
@@ -328,4 +378,64 @@ else
   printf 'ok - pre-commit gate behavior SKIPPED (needs gitleaks + openssl)\n'
 fi
 
+# --- Dependency audit gate (npm) — v2.5.0 -----------------------------------
+# A fake `npm` makes the crucial distinction deterministic and offline: a
+# vulnerable verdict (block) must never be confused with an unreachable advisory
+# DB (warn + allow). If those two collapsed, an offline failover would silently
+# let real vulnerabilities through.
+fakebin="${tmp_root}/fakebin"
+mkdir -p "${fakebin}"
+cat > "${fakebin}/npm" <<'FAKE'
+#!/bin/bash
+[ "${1:-}" = "audit" ] || exit 0
+case "${FAKE_NPM_MODE:-clean}" in
+  clean)   printf '%s\n' '{"auditReportVersion":2,"vulnerabilities":{},"metadata":{"vulnerabilities":{"info":0,"low":0,"moderate":0,"high":0,"critical":0,"total":0}}}'; exit 0 ;;
+  vuln)    printf '%s\n' '{"auditReportVersion":2,"vulnerabilities":{"hono":{"name":"hono","severity":"moderate","via":[{"title":"JWT"}]}},"metadata":{"vulnerabilities":{"info":0,"low":0,"moderate":4,"high":0,"critical":0,"total":4}}}'; exit 1 ;;
+  offline) printf '%s\n' '{"error":{"code":"ENOTFOUND","summary":"registry unreachable"}}'; exit 1 ;;
+esac
+FAKE
+chmod +x "${fakebin}/npm"
+
+if command -v jq >/dev/null 2>&1; then
+  audit_repo="${tmp_root}/audit-repo"
+  mkdir -p "${audit_repo}"
+  printf '{"name":"a","lockfileVersion":3}\n' > "${audit_repo}/package-lock.json"
+  run_audit() {
+    PATH="${fakebin}:${PATH}" FAKE_NPM_MODE="$1" \
+      "${ROOT_DIR}/bin/safedeps" audit npm --root "${audit_repo}" >/dev/null 2>&1
+  }
+  run_audit clean   && rc=0 || rc=$?; [ "${rc}" = "0" ] || fail "audit exit 0 on a clean lockfile (got ${rc})"
+  run_audit vuln    && rc=0 || rc=$?; [ "${rc}" = "1" ] || fail "audit exit 1 on a vulnerable lockfile (got ${rc})"
+  run_audit offline && rc=0 || rc=$?; [ "${rc}" = "2" ] || fail "audit exit 2 when the advisory DB is unreachable (got ${rc})"
+  pass "audit npm exit-code contract: clean=0 / vulnerable=1 / unreachable=2"
+else
+  printf 'ok - audit exit-code contract SKIPPED (needs jq)\n'
+fi
+
+if command -v gitleaks >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
+  dep_repo="${tmp_root}/dep-repo"
+  mkdir -p "${dep_repo}"
+  git -C "${dep_repo}" init -q
+  git -C "${dep_repo}" config user.email t@safedeps.test
+  git -C "${dep_repo}" config user.name safedeps-e2e
+  HOME="${tmp_root}/doc-home" "${ROOT_DIR}/bin/safedeps" doctor --fix --root "${dep_repo}" >/dev/null
+  printf '{"name":"a","lockfileVersion":3}\n' > "${dep_repo}/package-lock.json"
+  git -C "${dep_repo}" add package-lock.json
+
+  # Threat: a vulnerable dependency must BLOCK the commit (fail-closed verdict).
+  if PATH="${fakebin}:${PATH}" FAKE_NPM_MODE=vuln SAFEDEPS_BIN="${ROOT_DIR}/bin/safedeps" \
+       git -C "${dep_repo}" commit -q -m "vuln" 2>/dev/null; then
+    fail "pre-commit blocks a commit carrying a vulnerable dependency"
+  fi
+
+  # Availability failover: an unreachable advisory DB must WARN and ALLOW.
+  offline_out="$(PATH="${fakebin}:${PATH}" FAKE_NPM_MODE=offline SAFEDEPS_BIN="${ROOT_DIR}/bin/safedeps" \
+       git -C "${dep_repo}" commit -m "offline" 2>&1)" \
+    || fail "pre-commit allows the commit when the advisory DB is unreachable (offline failover)"
+  grep -q "offline failover" <<< "${offline_out}" || fail "offline failover prints an observable warning"
+  pass "pre-commit dep gate: blocks on vuln, warns+allows when offline"
+else
+  printf 'ok - pre-commit dep gate SKIPPED (needs gitleaks + jq)\n'
+fi
+
 printf 'e2e passed\n'