chore: publish v0.6.0

freshness nudge less naggy (window default + week snooze); harden the staleness keystone vs a non-list files field; add the tools/eval DeepInit-vs-/init benchmark; refresh README/docs with the /init grounding head-to-head (0.6%->77.6% verifiable file:line); correct stale private-repo assumptions for public launch

Published-from-internal: cd435b2

Author: elad-reznikov

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-init",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Generates a grounded, verified, two-tier agent context layer (lean CLAUDE.md + deep .ai/docs) for any codebase, plus report-only issue detection. 100% local, read-only.",
   "author": {
     "name": "DeepFusion Labs",

.gitignore

@@ -40,4 +40,5 @@ graphify-out/
 
 # DeepInit freshness-hook runtime state — local, machine-specific, never committed
 .ai/.deepinit-nudge-state
+.ai/.deepinit-nudge-snooze
 .claude/.deepinit-no-nudge

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to DeepInit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project uses **manual** `0.x`
 versioning (no release tooling derives this file).
 
+## [0.6.0] — 2026-06-27
+
+### Changed
+- _Summarize this release; replace this line._
+
+---
+
 ## [0.5.1] — Security reporting + output copy
 
 - **Security** — vulnerability reports can now be filed through GitHub Private Vulnerability

README.md

@@ -115,6 +115,7 @@ The trust-killer for a tool like this is the false positive, so detection biases
 
 Beyond that, the evidence is **INDICATIVE** and framed as comprehension/agreement — not "finds bugs in famous repos":
 
+- **Head-to-head vs `/init`.** On the *same* 9 repos (8 languages, small to large, some obscure), independent blind verifiers checked every claim in the lean `CLAUDE.md` *both* tools write: Claude Code's built-in `/init` grounded **0.6%** of its claims to a checkable `file:line`; DeepInit's quick `fast` mode, **77.6%** — same files, same front-door file, the difference is whether your agent gets a line it can open and trust. (INDICATIVE — mostly well-known OSS, fast mode, no wall-clock timing; it costs more too — see [Cost](#scope--boundaries) below.) → [`validation/matrix/`](validation/matrix/)
 - **It never re-flags a line a human already fixed.** Against an independent oracle of **22 real merged-bugfix pairs** (the metamorphic method — 4 languages, including 3 CVEs): recall **14/22 (64%, Wilson95 lower-bound 43%)** with **0/22 metamorphic false-positives.** Recall is reported-not-gated (small-n, real-repo); the make-or-break gate is the **0 metamorphic-FP.** → [`validation/`](validation/)
 - **The Mirror Test — does it actually understand your architecture?** We removed projects' own architecture docs, ran DeepInit on the code alone, and checked what it re-derived. Across **8 held-out repos**: faithfulness **98%**, **zero confidently-wrong claims**, coverage **66%** (strong on structure, weaker on deep invariants). The contamination answer: on 2 obscure repos a model is very unlikely to have memorized (one Go, one Rust) **faithfulness held at 100%** — so what it states about *unfamiliar* code is just as trustworthy; coverage varies with how deep one pass goes, not with trustworthiness. → [`validation/coverage/`](validation/coverage/)
 - **Real end-to-end runs** (the actual multi-component pipeline on excalidraw + kagent): faithfulness **100% on both**, **zero confidently-wrong facts**, ~130 grounded facts each. → [`validation/end-to-end/`](validation/end-to-end/)
@@ -128,7 +129,7 @@ Beyond that, the evidence is **INDICATIVE** and framed as comprehension/agreemen
 
 This isn't a weekend skill. **This is the harness — not the model.** A prompt hands you one ungrounded guess; the harness grounds every claim, measures its own false-alarm rate, and is regression-tested on every change.
 
-- **443 deterministic checks** (no model) across **99 oracle sections** that must stay all-PASS.
+- **446 deterministic checks** (no model) across **99 oracle sections** that must stay all-PASS.
 - A **mutation meta-harness** proves every one of those checks is load-bearing — not vacuous green.
 - The whole suite **stays green WITHOUT the held-out answer keys**, so the proof ships public while the keys stay private.
 - **CI runs it all on every change.**
@@ -145,7 +146,7 @@ make validate                                                # every gate, one c
 
 **Breadth:** a **16-repo / 13-language / 3-size matrix** ([`validation/matrix/`](validation/matrix/)) plus **15 cross-language field sweeps** (~1.12M LOC, [`validation/recall-discovery/`](validation/recall-discovery/)). **15 of 16 parse on the designed AST path** (only Crystal lacks a grammar → graceful grep fallback, which is exactly why kemal is our end-to-end degradation proof).
 
-**Real understanding beats "just ask an LLM."** Run three ways and scored against the AST as ground truth, DeepInit's full path grounds **98.9%** of its claims to a verified `file:line` (grep-fallback 100%); a naive LLM-only baseline grounds just **43.5%** (0% on one repo) and missed every grounded security-relevant finding. → [`validation/matrix/UNDERSTANDING-MATTERS.md`](validation/matrix/UNDERSTANDING-MATTERS.md)
+**Real understanding beats "just ask an LLM."** Run three ways and scored against the AST as ground truth, DeepInit's full path grounds **98.9%** of its claims to a verified `file:line` (grep-fallback 100%); a naive LLM-only baseline grounds just **43.5%** (0% on one repo) and missed every grounded security-relevant finding. (This is a *separate* measurement from the `/init` head-to-head above — DeepInit's *full* mode vs a raw-LLM baseline on 3 famous repos, not *fast* vs `/init` on 9 mixed repos; the two grounding numbers use different modes, repos, and baselines, so don't conflate or average them.) → [`validation/matrix/UNDERSTANDING-MATTERS.md`](validation/matrix/UNDERSTANDING-MATTERS.md)
 
 **We use it on our own code** — run over our own tooling, an independent internal reviewer's verdict was **WOULD-USE** (every "Critical to know" fact dual-grounded to a real `file:line`, all hard counts exact).
 
@@ -190,7 +191,7 @@ Plus a **class-conformance census overlay** — a non-detector that *enriches* a
 
 > **What this repo is:** DeepInit is a **Claude Code skill defined entirely in Markdown** — there is no application code. The "engine" is a Claude instance executing the instructions in [`skills/deep-init/`](skills/deep-init/). `skills/deep-init/SKILL.md` is the entry point; `skills/deep-init/references/*.md` are the stage specs, loaded on demand. Editing DeepInit means editing those instruction files.
 
-**Cost** is **INDICATIVE only**: DeepInit runs in your own Claude Code session — the cost is the token cost of one analysis pass (no subscription, no API key for the parser). A small repo is an inexpensive single pass; cost tracks component count more than raw lines. We have **no published dollar figure yet** while we finish benchmarking. → [`validation/matrix/COST-MODEL.md`](validation/matrix/COST-MODEL.md)
+**Cost** is **INDICATIVE only**: DeepInit runs in your own Claude Code session — the cost is the token cost of one analysis pass (no subscription, no API key for the parser). A small repo is an inexpensive single pass; cost tracks component count more than raw lines. The one metered head-to-head we've run (vs `/init`, above) measured **~$4.40 per run for DeepInit `fast` vs ~$0.89 for `/init`** on Claude Opus — ~46,000 vs ~5,700 output tokens (~8× the output for ~5× the cost, since DeepInit also writes the deep `.ai/docs/` tier; input is dominated by discounted prompt-cache reads, so cost isn't proportional to raw input). A published *per-size-tier* price still waits on a clean end-to-end accounting run. → [`validation/matrix/COST-MODEL.md`](validation/matrix/COST-MODEL.md)
 
 ---
 

commands/customize.md

@@ -13,7 +13,7 @@ BEFORE any analysis, collect the run settings as **type-safe button choices** us
 5. **Cost ceiling** — $25 (default) / $50 / Custom
 6. **Freshness & notifications** — Keep defaults / Configure… / Turn the nudge off / Pause in this repo
 
-Question 6 governs the proactive freshness surfaces (the SessionStart staleness nudge + commit breadcrumb / auto-update). Unlike 1–5 it controls *future* behavior, so on **Configure…** drill into a short follow-up `AskUserQuestion` (session-start nudge on/off · cadence session/window/always + window-hours · commit breadcrumb · auto-update · install the commit hook) and — per the SKILL.md *Freshness controls* spec — **persist** the chosen freshness keys ONLY on an explicit confirmation, via the surgical schema-validating writer (`python "${CLAUDE_PLUGIN_ROOT}/tools/freshness_config.py" --root <repo> --set <key>=<value> --apply`; **Pause in this repo** writes `.claude/.deepinit-no-nudge` instead). This is the one narrow exception to "a run never writes `.ai/deepinit.config`" — never hand-edit, never write without the user's "yes".
+Question 6 governs the proactive freshness surfaces (the SessionStart staleness nudge + commit breadcrumb / auto-update). Unlike 1–5 it controls *future* behavior, so on **Configure…** drill into a short follow-up `AskUserQuestion` (session-start nudge on/off · cadence window/session/always + window-hours [default window/24h] · decline back-off `notify-snooze-hours` [default 1 week] · commit breadcrumb · auto-update · install the commit hook) and — per the SKILL.md *Freshness controls* spec — **persist** the chosen freshness keys ONLY on an explicit confirmation, via the surgical schema-validating writer (`python "${CLAUDE_PLUGIN_ROOT}/tools/freshness_config.py" --root <repo> --set <key>=<value> --apply`; **Pause in this repo** writes `.claude/.deepinit-no-nudge` instead). This is the one narrow exception to "a run never writes `.ai/deepinit.config`" — never hand-edit, never write without the user's "yes".
 
 Then resolve the effective settings (max-quality defaults ← `.ai/deepinit.config` ← the picker answers), echo the one-line resolved panel, and run the full pipeline. Anything the picker does not cover stays available in `.ai/deepinit.config` (schema-validated) or as a flag.
 

commands/doctor.md

@@ -9,7 +9,7 @@ Run the **deep-init** skill's **preflight report** (`--doctor`) — **0 tokens,
 - **Scope** — the component registry, whether a DB / git history is present and in scope.
 - **Resolved settings** — the effective config (built-in max-quality defaults ← `.ai/deepinit.config` ← any flags), and whether `.ai/deepinit.config` is **valid** against `skills/deep-init/assets/deepinit.config.schema.json` (report unknown/invalid keys — warn, never fatal, R8).
 - **Enabled issue families** and the **estimated cost** (base + issue-pass terms).
-- **Freshness nudge — would it fire now?** Run `deepinit_status.py --explain` (0 tokens, no LLM) and show its verdict: docs stale or fresh, whether the SessionStart nudge is enabled or disabled (and by which switch), the cadence/window, and the last-nudge state. This answers "why am I not seeing the staleness nudge?" without guesswork.
+- **Freshness nudge — would it fire now?** Run `deepinit_status.py --explain` (0 tokens, no LLM) and show its verdict: docs stale or fresh, whether the SessionStart nudge is enabled or disabled (and by which switch), the cadence/window, the last-nudge state, and any active **[Not now]** decline-snooze. This answers "why am I not seeing the staleness nudge?" without guesswork.
 
 Then **OFFER (do not auto-run)** to install the freshness triggers via `setup-hooks` — the `deepinit_status.py` keystone + the post-commit + SessionStart hooks (`references/triggers.md`) — and point to `/deep-init:customize` → Freshness to change the cadence / window or turn the nudge off. Make no changes.
 

commands/version.md

@@ -6,7 +6,7 @@ Report the running DeepInit version — fast, no analysis. Do exactly this, then
 
 1. State the **loaded** version verbatim. This line ships inside the plugin markdown that is actually loaded in your session, so it is the source of truth for "what is running right now":
 
-   **DeepInit v0.5.1** <!-- deepinit:loaded-version -->
+   **DeepInit v0.6.0** <!-- deepinit:loaded-version -->
 
 2. Read the **on-disk** version (best-effort — skip gracefully if a path isn't present):
    - a local clone of this repo → `.claude-plugin/plugin.json` (the `"version"` field)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-init",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "private": true,
   "description": "DeepInit — a Claude Code skill that generates a grounded, verified, two-tier agent context layer (lean CLAUDE.md + deep .ai/docs) for any codebase, plus report-only issue detection. 100% local, read-only, MIT.",
   "license": "MIT",

skills/deep-init/SKILL.md

@@ -168,14 +168,15 @@ Keep it to these six — more would regress the zero-friction posture. The full
 ### Freshness controls (question 6 — the one step that PERSISTS)
 Questions 1–5 tune the immediate run only. Question 6 is different: it governs the **proactive freshness surfaces** (the plugin-shipped SessionStart staleness nudge + the optional commit breadcrumb / auto-update — `triggers.md`), which are *future* behavior, so its non-default answers are **persisted**, not applied to this run. Present it as type-safe buttons; on **Configure…**, drill into a short follow-up `AskUserQuestion` for the detail (still buttons, never hand-typed):
 - **Session-start nudge** — On (default) · Off → `notify-on-session-start`
-- **Cadence** — Once per new session (default) · Time window · Every session → `notify-cadence` (+ a window-hours follow-up when *Time window*: 6 (default) · 12 · 24 · Custom → `notify-window-hours`)
+- **Cadence** — Time window (default, ≈once/day so frequent short sessions aren't each re-nudged) · Once per new session · Every session → `notify-cadence` (+ a window-hours follow-up when *Time window*: 24 (default) · 12 · 6 · Custom → `notify-window-hours`)
+- **Decline back-off** — how long a **[Not now]** snoozes the nudge: 1 week (default) · 3 days · 1 day · Custom → `notify-snooze-hours`
 - **Commit breadcrumb** — On (default) · Off → `notify-on-commit`; **Auto-update (headless, spends tokens)** — Off (default) · On → `auto-update`
 - **Install the commit hook** — Install · Skip → `setup-hooks` (unchanged)
 
 **Persisting the choice — the one narrow config-write exception (R-config).** A DeepInit *run* **never** writes `.ai/deepinit.config` (it stays read-only input — see *Configuration*). This user-invoked Freshness step is the single, deliberate exception: when the user changes a persistent freshness setting, **state exactly which keys will be written and ask for an explicit confirmation first**, then persist via the deterministic, schema-validating writer — never a hand-edit:
 
 ```
-python "${CLAUDE_PLUGIN_ROOT}/tools/freshness_config.py" --root <repo> --set notify-on-session-start=off --set notify-cadence=window --set notify-window-hours=12 --apply
+python "${CLAUDE_PLUGIN_ROOT}/tools/freshness_config.py" --root <repo> --set notify-cadence=window --set notify-window-hours=24 --set notify-snooze-hours=168 --apply
 ```
 
 It is **surgical** — it upserts only the named freshness keys and leaves every other key, comment, and the file's layout intact, validating each value against the schema before writing. **Pause in this repo** is the exception's exception: it writes the `.claude/.deepinit-no-nudge` flag (gitignored), not the config. Without an explicit "yes", show the resulting config (run the writer without `--apply` to preview) and let the user save it themselves.

skills/deep-init/assets/deepinit.config.schema.json

@@ -58,8 +58,9 @@
     "notify-on-commit": { "enum": ["on", "off"], "default": "on", "description": "Post-commit prints a 0-token staleness nudge in the terminal (deepinit_status.py)." },
     "check-on-session-start": { "enum": ["on", "off"], "default": "on", "description": "Back-compat alias for notify-on-session-start." },
     "auto-update": { "enum": ["on", "off"], "default": "off", "description": "Opt-in: a detached headless `claude -p` runs --update after a source commit (spends tokens; never auto-commits)." },
-    "notify-cadence": { "enum": ["session", "window", "always"], "default": "session", "description": "How often the proactive SessionStart suggestion re-fires while docs stay stale. session (default) = once per NEW session (session-id dedup — proactive but never twice in one session); window = at most once per notify-window-hours (wall-clock back-off); always = every session start while stale." },
-    "notify-window-hours": { "type": "number", "minimum": 0, "default": 6, "description": "Back-off window in hours for notify-cadence=\"window\" (the SessionStart suggestion fires at most once per this many hours while stale). Ignored for session/always." },
+    "notify-cadence": { "enum": ["session", "window", "always"], "default": "window", "description": "How often the proactive SessionStart suggestion re-fires while docs stay stale. window (default) = at most once per notify-window-hours of wall-clock (≈once/day, so frequent new sessions don't each re-nudge); session = once per NEW session (session-id dedup — proactive but never twice in one session); always = every session start while stale." },
+    "notify-window-hours": { "type": "number", "minimum": 0, "default": 24, "description": "Back-off window in hours for notify-cadence=\"window\" (the default — the SessionStart suggestion fires at most once per this many hours while stale). Ignored for session/always." },
+    "notify-snooze-hours": { "type": "number", "minimum": 0, "default": 168, "description": "How long (hours) a \"Not now\" decline silences the suggestion. When the user declines the offer the agent records a back-off in .ai/.deepinit-nudge-snooze (via deepinit_status.py --snooze) and the hook stays silent until it expires (default 168 = one week — longer than the passive window, so an explicit decline buys more quiet than letting a nudge pass)." },
     "issues": { "enum": ["on", "off"], "default": "on", "description": "Detect issues (report-only; never enters the lean tier — R9)." },
     "issues-families": {
       "type": "array",