@aldegad/safedeps 2.2.0 → 2.4.1

package/ARCHITECTURE.md

@@ -39,10 +39,12 @@ safedeps owns security gates at two distinct moments, under one skill. It absorb
 ```
 
 - **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.
+- **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|doctor` 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 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 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
@@ -332,6 +334,8 @@ OSV normalizes ecosystem names, so one API path covers all of them at advisory-c
 | `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. |
+| `lib/gates/` | Release-time repo lane — `scan.sh` (gitleaks runner), `audit.sh` (npm lockfile audit), `hooks.sh` (`install`/`check`/`init`), `doctor.sh` (posture diagnose + `--fix`), `repo-profile.sh` (public/private resolution). Owns *execution*; the repo owns *policy*. |
+| `lib/gates/templates/` | Starter `.gitleaks[.private].toml` + `.githooks/pre-commit`, scaffolded by `hooks init`. Seeds the repo owns and tunes — never overwritten on re-run. |
 
 ---
 

package/README.ko.md

@@ -23,6 +23,8 @@
 - **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-별) 참고.
+
 ---
 
 ## 어떻게 동작
@@ -72,6 +74,46 @@
 
 ---
 
+## secret 누출 lane (repo 별)
+
+install-time gate 는 전역이지만, secret 이나 진짜 `.env` 가 커밋되는 걸 막는 건 **repo 별이고 opt-in** 이다 — 탐지 policy 가 safedeps 가 아니라 각 repo 에 있기 때문이다. `safedeps doctor` 가 그 빈틈을 메우는 진입점이다.
+
+```bash
+# 이 repo 의 자세 진단 (read-only). secret lane 에 gap 이 있으면 non-zero 로 끝난다.
+$ safedeps doctor
+safedeps doctor — repo security posture
+repo:    /path/to/repo
+profile: public
+
+Secret-leak lane (per-repo)
+  ✓ git worktree
+  ✗ gitleaks config (.gitleaks.toml)             → safedeps hooks init --root "/path/to/repo"
+  ✗ .githooks/pre-commit (present)               → safedeps hooks init --root "/path/to/repo"
+  ✗ git hooks active (core.hooksPath=<unset>)    → safedeps hooks install --root "/path/to/repo"
+  ✓ secret scanner available (gitleaks)
+
+Dependency-install gate (global, all repos)
+  ✓ dependency-install gate installed (~/.claude/skills/safedeps)
+
+3 gap(s) in the secret-leak lane.
+Fix all at once:  safedeps doctor --fix --root "/path/to/repo"
+
+# 시작 policy scaffold + hook 활성화 (비파괴적).
+$ safedeps doctor --fix
+```
+
+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` 뿐이다.
+
+scaffold 된 `.gitleaks.toml` 은 **네가 손보는 시작점**이다: gitleaks 기본 ruleset 을 extend 하고, 값이 할당된 `.env` 커밋을 잡는 rule 을 더하며(`.env.example`/`.sample`/`.template` 변형은 allowlist), fixture 용 repo-owned `[allowlist]` 블록을 남겨둔다. safedeps 는 *실행* — `safedeps scan secrets` 로 gitleaks 구동 — 만 소유하고 policy 내용은 소유하지 않는다.
+
+`safedeps doctor --json` 은 `{ command, repo, profile, gaps, ok, checks[] }` 를 돌려준다; `gaps`/`ok` 는 repo 별 secret 누출 lane 만 반영한다.
+
+---
+
 ## 설치
 
 ### 1) GitHub clone (skill 본체 설치, canonical)

package/README.md

@@ -26,6 +26,8 @@ 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).
+
 ## How It Works
 
 `safedeps` works in two moves around every install:
@@ -141,6 +143,44 @@ After the install command completes, the verify hook analyzes what changed. For
 | Dependency confusion | >50 new dependencies in a single install | PostToolUse effect verify | **Reorg** |
 | Native binaries | Compiled executables in `node_modules/.bin/` | PostToolUse effect verify | **Reorg** |
 
+## Secret-Leak Lane (per-repo)
+
+The install-time gate is global, but stopping a secret or a real `.env` from being committed is **per-repo** and stays opt-in — its detection policy lives in each repo, not in safedeps. `safedeps doctor` is the entry point that closes that gap.
+
+```bash
+# Diagnose this repo's posture (read-only). Exits non-zero if the secret lane has gaps.
+$ safedeps doctor
+safedeps doctor — repo security posture
+repo:    /path/to/repo
+profile: public
+
+Secret-leak lane (per-repo)
+  ✓ git worktree
+  ✗ gitleaks config (.gitleaks.toml)             → safedeps hooks init --root "/path/to/repo"
+  ✗ .githooks/pre-commit (present)               → safedeps hooks init --root "/path/to/repo"
+  ✗ git hooks active (core.hooksPath=<unset>)    → safedeps hooks install --root "/path/to/repo"
+  ✓ secret scanner available (gitleaks)
+
+Dependency-install gate (global, all repos)
+  ✓ dependency-install gate installed (~/.claude/skills/safedeps)
+
+3 gap(s) in the secret-leak lane.
+Fix all at once:  safedeps doctor --fix --root "/path/to/repo"
+
+# Scaffold the starter policy + activate the hooks (non-destructive).
+$ safedeps doctor --fix
+```
+
+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 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.
+
+`safedeps doctor --json` returns `{ command, repo, profile, gaps, ok, checks[] }`; `gaps`/`ok` reflect the per-repo secret-leak lane only.
+
 ## Installation
 
 ### Prerequisites
@@ -307,6 +347,8 @@ safedeps/
   lib/
     providers/    # OSV / CISA KEV / GHSA adapters
     ledger/       # approved-spec ledger
+    npm/          # lockfile closure resolver
+    gates/        # repo-tree lane: scan / audit / hooks / doctor + templates/
   scripts/
     safedeps-pre-guard.sh       # PreToolUse hook -- advisory ledger UX + snapshots
     safedeps-post-verify.sh     # PostToolUse hook -- npm primary effect verification + reorg

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.2.0).
+- 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).
 - `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.
 
@@ -87,7 +87,56 @@ This phase covers npm lockfile closure only. pip / cargo / go / gem / maven / nu
 
 ### Current focus
 
-1. `v2.2.0-release`: merge `safedeps-security-hardening`, tag `v2.2.0`, GitHub release, `npm publish`.
+1. `v2.2.0-release`: merged `safedeps-security-hardening`, tagged `v2.2.0` (GitHub release + `npm publish`).
+
+---
+
+## v2.3 — secret-leak lane doctor + scaffold (shipped)
+
+Status: shipped as v2.3.0.
+
+### What changed
+
+- **`safedeps doctor`** — a repo-entry posture check. It diagnoses the per-repo secret-leak lane (`.gitleaks` policy, `.githooks/pre-commit`, active `core.hooksPath`, scanner availability) and reports the global install-time gate too. Read-only by default, `--json` for agents, exits non-zero when the secret-leak lane has gaps.
+- **`safedeps doctor --fix` / `safedeps hooks init`** — scaffolds a starter `.gitleaks.toml` (or `.gitleaks.private.toml`) and `.githooks/pre-commit` from `lib/gates/templates/`, then activates the hooks. Non-destructive: an existing repo-owned policy is never overwritten.
+- **Agent-as-security-role framing** — `SKILL.md` makes `safedeps doctor` a repo-entry step so the agent, not a later leak, closes the secret-lane gap. The installer prints a per-repo nudge (no auto-write into repos — the policy boundary stays with the repo).
+- **Fail-closed delegation** — the scaffolded `pre-commit` delegates to `safedeps scan secrets --staged` (one canonical scanner path); an unresolvable `safedeps` or a missing scanner blocks the commit rather than skipping silently.
+
+### Design decisions
+
+- `doctor` is holistic but **secret-lane-centric**: its exit code reflects the per-repo lane only; the global dependency gate is reported (`deps` check) but does not gate the repo result.
+- safedeps owns **execution**, the repo owns **policy**. Templates are seeds the repo tunes, consistent with the existing Two Lanes invariant.
+
+### Verification
+
+- `safedeps doctor` flags gaps on an unconfigured repo and reports clean after `--fix`
+- `hooks init` is non-destructive across a re-run (repo edits survive)
+- pre-commit gate denies a committed secret, passes clean and `.env.example` placeholder commits (bypass harness + regression)
+- existing smoke + fixture E2E regression suite remains green
+
+---
+
+## v2.4 — fail-closed hooks + supply-chain hardening (shipped)
+
+Status: shipped as v2.4.0.
+
+### What changed
+
+- **Fail-closed gate** — the PreToolUse/PostToolUse hooks no longer `exit 0` (silent pass) when they cannot run. A lock-unavailable install now **denies** fail-closed; an unavoidable `jq`-missing case becomes an **explicit allow-with-warning**; every such outcome is recorded in `~/.safedeps/advisory.log` (observable, per the no-silent-fallback invariant). The PostToolUse path records an un-runnable gate as **UNVERIFIED** rather than a clean pass.
+- **`SECURITY.md`** — vulnerability disclosure policy, supported versions, scope, and the by-design security properties (no SaaS, zero deps, no silent fallback).
+- **CI hardening** — `actions/*` pinned to commit SHA; the gitleaks download is checksum-verified; a ShellCheck gate (error-clean); a macOS + Linux matrix (the v2.3 `stat` fix proved cross-OS coverage matters); and an `npm pack` step that keeps the zero-dependency property honest.
+
+### Verification
+
+- lock-unavailable install denies fail-closed and logs to `advisory.log`
+- jq-missing denies a likely install (best-effort fail-closed) and logs it; only non-install commands fall through
+- a missing ledger library denies fail-closed instead of falling through to allow
+- ShellCheck (`--severity=error`) is clean across all shell sources
+- existing smoke + e2e regression suite remains green on both Linux and macOS
+
+### v2.4.1 — concurrent-install race fix (#5)
+
+The pending state PreToolUse hands to PostToolUse was a single global `current_state` file, so two installs overlapping in one project could clobber each other and the effect gate could verify the wrong install (or skip one). Pending state is now keyed **per install** — `dir_hash` + a hash of the command with the inert-install rewrite normalized out — so PreToolUse and PostToolUse of the same install agree on a key while concurrent installs stay isolated. A concurrency harness (two installs → two pending files; a post consumes only its own) guards it.
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+safedeps is a security tool, so it holds itself to the posture it enforces: local-only, no SaaS, **zero runtime npm dependencies**, fail-closed gates, and observable bypasses.
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 2.x (latest minor) | ✅ |
+| < 2.0 (`npm-reorg-guard`) | ❌ — migrate with `safedeps migrate` |
+
+Fixes land on the latest minor. Pin to a released tag for reproducibility.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a vulnerability.** Report it privately:
+
+1. **Preferred** — GitHub private advisory: the repo's **Security → Report a vulnerability** tab (<https://github.com/aldegad/safedeps/security/advisories/new>).
+2. **Email** — `aldegad@gmail.com` with `[safedeps security]` in the subject.
+
+Please include: affected version (`safedeps --json version`), a minimal reproduction, the impact (e.g. a gate bypass, a fail-open path, a reorg that misses a threat), and any logs from `~/.safedeps/advisory.log` / `~/.safedeps/reorg.log`.
+
+### What counts
+
+In scope — anything that defeats a gate or weakens its guarantees, for example:
+
+- a dependency-install command that bypasses the PreToolUse guard or the PostToolUse effect gate;
+- a malicious package whose closure or install scripts pass verification when they should reorg;
+- a **fail-open** path (a gate that silently passes when it cannot run);
+- a secret-leak lane bypass (a committed secret the scaffolded gate misses);
+- ledger tampering that grants an unapproved spec (note: the ledger is a same-user convenience cache, **not** a boundary against a same-user attacker until signing lands — that limit is documented, not a vuln).
+
+Out of scope — issues requiring an already-root/same-user attacker beyond the documented threat model, or third-party advisory-database accuracy (OSV/KEV/GHSA own their data).
+
+## Response
+
+- Acknowledgement within ~72 hours.
+- A fix or mitigation plan for confirmed reports, coordinated before public disclosure.
+- Credit in the release notes if you'd like it.
+
+## Security properties (by design)
+
+- **No SaaS** — local CLI + public databases (OSV / CISA KEV / GHSA) only.
+- **Zero npm dependencies** — the tool ships no runtime deps; this is a deliberate security property, kept enforced by `npm pack` review in CI.
+- **No silent fallback** — a provider/scanner miss is fail-closed (the install is denied). The one unavoidable exception is `jq` being absent — it is needed to parse the hook payload — and even then the guard reads the raw payload and denies anything that looks like a dependency install, falling back to an explicit allow-with-warning only for non-install commands. Every such outcome is recorded in `~/.safedeps/advisory.log`.

package/SKILL.md

@@ -10,72 +10,97 @@ hooks:
 
 # Safedeps
 
-Safedeps protects development dependency installs with a three-phase flow:
+Two gates, one skill. You (the agent) are the primary user — drive both:
 
-1. **Phase 1 — Advisory gate (`safedeps check`)**: query OSV (canonical advisory truth), CISA KEV (overlay), and GitHub Advisory (enrichment) before install. For npm, resolve the full dependency closure with a script-free lockfile probe and OSV `/v1/querybatch`; write the approved direct spec plus `transitive_specs` to `~/.safedeps/approved-specs/<hash>.json` with a 30-day TTL.
-2. **Phase 2 — Fast command guard (`scripts/safedeps-pre-guard.sh`)**: the PreToolUse hook does not call providers. It checks the approved-spec ledger for package/version tokens in the about-to-run install command and snapshots dependency truth. Miss or expired → block with a structured message that names the exact `safedeps check` command to run next. On Claude Code it also rewrites an npm install to add `--ignore-scripts` (hook `updatedInput`), so the install runs inert until verified; Codex CLI lacks `updatedInput`, so it falls back to detect-and-rollback.
-3. **Phase 3 — Effect enforcement + reorg (`scripts/safedeps-post-verify.sh`)**: PostToolUse is the primary enforcement surface for npm. It compares the actual `package-lock.json` closure against direct ledger entries and their `transitive_specs`, re-checks the closure with OSV batch, and rolls back when any package is unapproved/vulnerable or install scripts look suspicious. After a verified inert install it runs `npm rebuild` so the now-trusted lifecycle scripts execute.
+- **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).
 
-> **Release-time lane**: the `security-release-gates` orchestrator is absorbed into `safedeps gates`. It runs the repo-tree gates (secret scan, dependency audit, repo git-hook/CI check, install-guard presence) from one entry point, detecting and orchestrating the repo's `security:*` npm scripts, `scripts/security/*`, and gitleaks/npm-audit fallback. Splitting the individual `scan`/`audit`/`hooks`/`git` commands out and fully migrating a target repo's `scripts/security/*` is follow-up work. Design SSoT: [`ARCHITECTURE.md`](./ARCHITECTURE.md) §1 (Two Lanes).
+---
 
-## CLI Reference
+## Install-time gate
 
+The hooks enforce this; you just run `check` first.
+
+- **PreToolUse** blocks an install whose spec is not approved and quotes the exact `safedeps check` to run. On Claude Code it also rewrites an npm install with `--ignore-scripts`, so it runs **inert** until verified; Codex CLI uses detect-and-rollback.
+- **PostToolUse** is the npm enforcement authority: it reads the real `package-lock.json` closure, checks every package against the ledger + an OSV batch, and **reorgs** (rolls back) anything unapproved, vulnerable, or with suspicious install scripts. Effect-primary is **npm-only**; pip/cargo/go/gem/maven/nuget use the command-gate + reorg model.
+
+### Before every install, run
+
+```bash
+safedeps check <ecosystem> <pkg>@<range> --json
 ```
-safedeps check <ecosystem> <pkg>@<version|range> [--json]
-safedeps ledger [--json]
-safedeps revoke <hash> | <ecosystem> <pkg>@<version> | <pkg>@<version> [--reason <r>] [--json]
-safedeps re-check [--json]
-safedeps migrate [--keep-legacy]
-safedeps gates [run] [--root <repo>] [--strict] [--no-run]
-safedeps help [command]
-safedeps version
-```
 
-**Ecosystems** (OSV-normalized): `npm`, `pypi`, `crates.io`, `go`, `rubygems`, `maven`, `nuget`.
+- Ecosystems: `npm`, `pypi`, `crates.io`, `go`, `rubygems`, `maven`, `nuget`.
+- Not on PATH? Use `~/.claude/skills/safedeps/bin/safedeps` (Claude) or `~/.codex/skills/safedeps/bin/safedeps` (Codex). Block messages already quote a runnable path.
+
+### Then act on `result`
 
-**Exit codes**:
+| `result` | Action |
+|---|---|
+| `clean` / `already_approved` | Install. Use `install_hint` verbatim — it pins the approved version. |
+| `patched_available` | Install `suggested_spec` instead (e.g. `^14.0.0` → `14.0.5`). |
+| `cve_unpatched` | Do not install. Surface the CVEs, propose an alternative package. |
+| `kev_hard_block` | Do not install. Recommend an alternative — actively exploited in the wild. |
+| `provider_unavailable` | Do not install. OSV unreachable, no fresh cache. Retry later or tell the human. |
+| `error` | Fix the spec (e.g. an unpublished version) and retry. |
 
-| Code | Meaning |
-|---:|---|
-| 0 | clean — spec approved, install is safe |
-| 2 | CVE found, no patched version available — install blocked, human decision required |
-| 3 | CISA KEV match — hard block, install must not proceed |
-| 4 | input error or provider unavailable (fail-closed) |
+Install only after approval. If the approved version differs from your argument, the hook blocks again — re-narrow and retry.
 
-**Global flags**: `--json` (machine-readable, stable schema, no color, no spinner), `--no-color` (disable ANSI colors in human mode).
+### Rules
 
-## For AI Agents
+- Never bypass the gate. A provider miss is **fail-closed**, never fail-open.
+- `kev_hard_block` is non-negotiable — recommend an alternative, never ask the human to override.
+- Use `install_hint` / `suggested_spec` verbatim — a fresh range defeats the spec lock.
 
-You are the primary user of this skill when you propose `npm install`, `pip install`, `cargo add`, etc. Treat `safedeps check` as a mandatory pre-step. The PreToolUse hook will block the install if you skip it.
+### When the hook blocks you
 
-### Workflow
+The block message is `permissionDecisionReason`. The command quoted in backticks is runnable as-is — run it **verbatim**, parse the `--json` output, and retry the install with the approved version.
 
-1. **Before issuing any install command**, call:
+---
 
-   ```bash
-   safedeps check <ecosystem> <pkg>@<range> --json
-   ```
+## Secret-leak gate (per-repo)
 
-   Use `--json` so the output is parseable. Read the `result` field.
+The install-time gate is global; this one is per-repo and opt-in. Make it part of entering a repo, so the agent — not a later leak — is on guard.
 
-   If `safedeps` is not on your PATH, invoke it at the skill path instead — `~/.claude/skills/safedeps/bin/safedeps` (Claude Code) or `~/.codex/skills/safedeps/bin/safedeps` (Codex CLI). The hook's block messages already name a runnable path, so when blocked you never have to resolve this yourself.
+```bash
+safedeps doctor          # diagnose; exits non-zero if the secret lane has gaps
+safedeps doctor --fix    # scaffold the policy + activate the hooks (non-destructive)
+```
+
+1. On repo entry, run `safedeps doctor` (`--json` for the `checks` array).
+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`.
+
+---
+
+## CLI reference
+
+```
+safedeps check <ecosystem> <pkg>@<version|range> [--json]
+safedeps ledger [--json]
+safedeps revoke <hash> | <ecosystem> <pkg>@<version> | <pkg>@<version> [--reason <r>] [--json]
+safedeps re-check [--json]
+safedeps doctor [--root <repo>] [--fix] [--json]
+safedeps hooks <install|check|init> [--root <repo>]
+safedeps scan secrets [--repo|--worktree|--staged] [--root <repo>]
+safedeps audit [npm] [--root <repo>]
+safedeps gates [run] [--root <repo>] [--strict] [--no-run]
+safedeps migrate [--keep-legacy]
+safedeps help [command]
+safedeps version
+```
 
-2. **Decide from `result`**:
+**Global flags**: `--json` (stable machine-readable schema), `--no-color`.
 
-   | `result` | Action |
-   |---|---|
-   | `clean` / `already_approved` | Proceed with the install. Use `install_hint` verbatim if present (it pins to the exact approved version). |
-   | `patched_available` | Approved spec narrowed to a safe version. Replace your install argument with `suggested_spec`. Example: `^14.0.0` → `14.0.5`. |
-   | `cve_unpatched` | Do **not** install. Surface the CVE list to the human, propose an alternative package. |
-   | `kev_hard_block` | Do **not** install. Recommend an alternative module — the package is actively exploited in the wild. |
-   | `provider_unavailable` | OSV is unreachable and there is no fresh cache. Do not install. Retry later or tell the human. |
-   | `error` | Argument parsing or version/closure resolution failed (e.g. an unpublished version). Fix the spec and retry. |
+**Exit codes**: `0` clean/approved · `2` CVE, no patch (human decision) · `3` CISA KEV hard block · `4` input error or provider unavailable (fail-closed).
 
-3. **Issue the install** only after the spec is approved. The hook re-checks the ledger; if the approved version differs from your install argument, the hook will block again — re-narrow and retry.
+---
 
-### JSON schema (stable, agent-facing)
+## JSON schemas (agent-facing)
 
-`check` result envelope, common fields:
+`check`:
 
 ```json
 {
@@ -92,115 +117,27 @@ You are the primary user of this skill when you propose `npm install`, `pip inst
 }
 ```
 
-`patched_available` adds `"suggested_spec": "1.2.5"`. `kev_hard_block` retains the full `vulnerabilities` and `kev.matches` arrays for evidence. `cve_unpatched` retains `vulnerabilities`.
-
-`ledger` returns `{ "command": "ledger", "count": N, "specs": [...] }` where each spec has `hash`, `ecosystem`, `package`, `version`, `version_range`, `approved_at`, `expires_at`, `approved_by`, `expired` (bool), `revoked` (bool).
-
-`revoke` returns `{ "command": "revoke", "revoked": true, "reason": "...", "spec": {...} }`.
-
-`re-check` returns `{ "command": "re-check", "checked": N, "still_clean": N, "newly_vulnerable": [...], "kev_hit": [...], "revoked": [...] }`.
-
-`migrate` returns `{ "migrated": bool, "legacyRoot": "...", "targetRoot": "...", "copied": N, "skipped": N, "archivedAs": "..." }`.
-
-### When the hook blocks you
+- `patched_available` adds `suggested_spec`. `kev_hard_block` keeps `vulnerabilities` + `kev.matches`. `cve_unpatched` keeps `vulnerabilities`.
 
-`scripts/safedeps-pre-guard.sh` emits a Claude Code / Codex CLI hook decision using the modern PreToolUse schema:
+`doctor`:
 
 ```json
 {
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "safedeps: install not approved (ecosystem=npm) — run `safedeps check npm @scope/pkg@^1.2.0` first, then retry the install using the approved version (see install_hint in the check output)."
-  }
+  "command": "doctor",
+  "repo": "/path/to/repo",
+  "profile": "public | private",
+  "gaps": 0,
+  "ok": true,
+  "checks": [
+    { "lane": "secret | deps", "status": "ok | gap | na", "label": "...", "remedy": "safedeps hooks init ..." }
+  ]
 }
 ```
 
-Both engines surface `permissionDecisionReason` back to you as the block message. The command quoted inside backticks is already runnable as-is — bare `safedeps` when the CLI is on PATH, otherwise an absolute path. Run it **verbatim** (do not rewrite a full path back down to a bare `safedeps`), parse the `--json` output, and retry the install with the approved version.
-
-### Hard rules
-
-- Never bypass the advisory gate. There is no silent fallback. If the provider is unreachable, fail-closed is the correct outcome.
-- KEV (`result: "kev_hard_block"`) is non-negotiable. Recommend an alternative; do not ask the human to override.
-- Use `install_hint` or `suggested_spec` verbatim. Do not rewrite the version with a fresh range — that defeats the spec lock.
-
-## For Humans
-
-Default output is Korean + ANSI color + braille spinner during long calls. Designed for terminal use, no flags needed.
-
-```bash
-$ safedeps check npm "@scope/pkg@^14.0.0"
-· 버전 해석 중 (@scope/pkg@^14.0.0)
-· 취약점 조회 중 (OSV / KEV / GHSA)
-⚠ @scope/pkg@14.0.3 에 2 개 CVE — 안전 버전 14.0.5 으로 좁혀 재조회합니다.
-· 14.0.5 재조회 중
-✓ @scope/pkg@14.0.5 승인 (until 2026-06-17T...)
-· ledger: sha256:abc123...
-
-$ safedeps ledger
-STATE    ECOSYSTEM    PACKAGE       VERSION    APPROVED              EXPIRES               HASH
-ACTIVE   npm          @scope/pkg    14.0.5     2026-05-18T...        2026-06-17T...        sha256:abc...
-
-$ safedeps revoke @scope/pkg@14.0.5 --reason "team policy change"
-✓ 취소: npm @scope/pkg@14.0.5
-
-$ safedeps re-check
-· 재검증 npm left-pad@1.3.0
-· 검증 완료: 1 개 중 1 개 clean
-```
-
-### Color legend
+- `gaps` / `ok` reflect the per-repo secret-leak lane only; a missing global gate is a `deps` check but does not change `ok`.
 
-- `· gray` — info / progress
-- `✓ green` — safe, approved
-- `⚠ yellow` — warning, manual decision required
-- `✗ red` — hard error or KEV block
+`ledger`, `revoke`, `re-check`, `migrate` each return a `{ "command": "...", ... }` envelope; run `safedeps help <command>` for the fields.
 
-Disable color with `--no-color` or `NO_COLOR=1`. Non-TTY pipes also strip color automatically.
-
-## Current Components
-
-- `bin/safedeps` — CLI (this entry point). Bash. Source-loads providers + ledger libs.
-- `lib/providers/providers.sh` — OSV / CISA KEV / GitHub Advisory adapters with a single query interface and 24h local cache under `~/.safedeps/cache/`.
-- `lib/ledger/ledger.sh` — approved spec JSON ledger I/O under `~/.safedeps/approved-specs/`, deterministic spec hash, TTL checks, atomic writes.
-- `scripts/safedeps-pre-guard.sh` — PreToolUse hook. v1 command pattern guard + ledger lookup for install commands.
-- `scripts/safedeps-post-verify.sh` — PostToolUse hook. v1 rollback engine + npm effect gate (lockfile closure vs ledger + OSV batch).
-- `lib/npm/closure.sh` — npm lockfile closure extraction and script-free temp lockfile resolver.
-- `scripts/install/install-safedeps-hooks.mjs` — cross-engine installer. Symlinks `~/.claude/skills/safedeps` and `~/.codex/skills/safedeps`, idempotently patches `~/.claude/settings.json` and `~/.codex/hooks.json`. `--uninstall` removes both.
-
-## Provider Failure Policy
-
-- OSV.dev is primary. Fresh cache may be used for 24h; cache miss or stale cache on OSV failure is fail-closed (`safedeps check` exits 4, hook blocks).
-- CISA KEV is an overlay. Stale or unavailable catalog is surfaced as a warning/status, not hidden.
-- GitHub Advisory is enrichment. Failure is fail-open only with an observable skipped status and advisory log entry.
-
-## Installation
-
-The cross-engine installer registers the skill + hooks for Claude Code and Codex CLI in one shot. It is idempotent and backs up `settings.json` / `hooks.json` before writing.
-
-```bash
-node scripts/install/install-safedeps-hooks.mjs            # install
-node scripts/install/install-safedeps-hooks.mjs --uninstall # remove
-```
-
-What it does:
-
-- Symlink the repo at `~/.claude/skills/safedeps` (when `~/.claude` exists) and `~/.codex/skills/safedeps` (when `~/.codex` exists).
-- Patch `~/.claude/settings.json` `hooks.PreToolUse[matcher=Bash]` and `hooks.PostToolUse[matcher=Bash]` with the canonical script paths.
-- Patch `~/.codex/hooks.json` with the same matcher and paths.
-- Optionally symlink `~/.local/bin/safedeps -> bin/safedeps` (via `--link-bin`) for a clean `safedeps` on PATH. **Not required** — the hook block messages and this skill fall back to the absolute skill-relative path, so the gate is fully self-contained without any PATH setup.
-
-Manual registration is also supported — see [Claude Code Hooks reference](https://code.claude.com/docs/en/hooks) and [Codex CLI Hooks](https://developers.openai.com/codex/hooks). The canonical script paths are:
-
-- PreToolUse: `<skills-root>/safedeps/scripts/safedeps-pre-guard.sh`
-- PostToolUse: `<skills-root>/safedeps/scripts/safedeps-post-verify.sh`
-
-## State
-
-- Approved specs: `~/.safedeps/approved-specs/`
-- Provider cache: `~/.safedeps/cache/`
-- Reorg snapshots: `~/.safedeps/snapshots/`
-- Advisory log: `~/.safedeps/advisory.log`
-- Reorg log: `~/.safedeps/reorg.log`
+---
 
-`safedeps` is the canonical skill name, state namespace, and repository name.
+Human terminal guide, install steps, and internal design: [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md). `safedeps` is the canonical skill name, state namespace, and repository name.

package/bin/safedeps

@@ -7,7 +7,7 @@
 
 set -euo pipefail
 
-SAFEDEPS_VERSION="2.2.0"
+SAFEDEPS_VERSION="2.4.1"
 
 # ---- repo / lib bootstrap ----------------------------------------------------
 
@@ -1027,6 +1027,11 @@ cmd_hooks() {
   exec bash "${SAFEDEPS_REPO_DIR}/lib/gates/hooks.sh" "$@"
 }
 
+cmd_doctor() {
+  exec env SAFEDEPS_JSON_MODE="${SAFEDEPS_JSON_MODE}" \
+    bash "${SAFEDEPS_REPO_DIR}/lib/gates/doctor.sh" "$@"
+}
+
 # ---- help / version ----------------------------------------------------------
 
 cmd_version() {
@@ -1081,6 +1086,33 @@ safedeps migrate [--keep-legacy]
 
   Migrate legacy ~/.npm-reorg-guard state into ~/.safedeps.
   By default the legacy directory is archived to remove the old active truth path.
+EOF
+      ;;
+    doctor)
+      cat <<'EOF'
+safedeps doctor [--root <repo>] [--fix] [--json]
+
+  Diagnose this repo's security posture: the per-repo secret-leak lane
+  (.gitleaks policy + .githooks/pre-commit + active core.hooksPath + an
+  available scanner) plus the global dependency-install gate. Read-only by
+  default; exits 1 when the secret-leak lane has gaps.
+
+  --fix   Scaffold the missing policy (hooks init) and activate it (hooks
+          install). Non-destructive: existing repo-owned files are kept.
+
+  The scaffolded .gitleaks.toml is a STARTER you own and tune; safedeps owns
+  execution (running gitleaks via `safedeps scan secrets`), not the policy.
+EOF
+      ;;
+    hooks)
+      cat <<'EOF'
+safedeps hooks <install|check|init> [--root <repo>] [--hooks-path <dir>] [--auto]
+
+  init     Scaffold the repo's secret-leak policy from starter templates
+           (.gitleaks[.private].toml + .githooks/pre-commit). Non-destructive.
+  install  Activate repo-local git hooks (sets core.hooksPath). Requires the
+           hook file to exist — run `init` first if the repo has none.
+  check    Verify the hooks are active, executable, and a scanner is available.
 EOF
       ;;
     *)
@@ -1099,7 +1131,8 @@ COMMANDS
   gates [run]                               Release-time repo gates: secret scan, dep audit, hook/CI check.
   scan secrets [--repo|--worktree|--staged] Run gitleaks secret scan (repo profile aware).
   audit [npm]                               Run npm lockfile audit.
-  hooks <install|check>                     Install/verify repo-local git hooks.
+  hooks <install|check|init>                Install/verify/scaffold repo-local git hooks.
+  doctor [--fix]                            Diagnose this repo's secret-leak lane (--fix scaffolds + activates).
   help [command]                            Show help.
   version                                   Print version.
 
@@ -1163,6 +1196,7 @@ main() {
     scan)     cmd_scan     "$@" ;;
     audit)    cmd_audit    "$@" ;;
     hooks)    cmd_hooks    "$@" ;;
+    doctor)   cmd_doctor   "$@" ;;
     help)     cmd_help     "$@" ;;
     version)  cmd_version ;;
     *)