release: publish v0.7.1

fix: report no longer silently shows 0 issues when the ledger shape or manifest counts differ

docs: restructure the README to lead with benefits and outcomes

Published-from-internal: 2390ac4799d7fab66974121da58670c32cf7515c

Author: elad-reznikov

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-init",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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",

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.7.1] — 2026-07-01
+
+### Changed
+- _Summarize this release; replace this line._
+
+---
+
 ## [0.7.0] — 2026-06-30
 
 ### Changed

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.7.0** <!-- deepinit:loaded-version -->
+   **DeepInit v0.7.1** <!-- 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.7.0",
+  "version": "0.7.1",
   "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/references/generation.md

@@ -94,7 +94,7 @@ Claude Code reads nested `CLAUDE.md` along the path to the file being worked on,
 On a Claude-Code repo a root `AGENTS.md` is **redundant** — Claude Code doesn't read it, and `CLAUDE.md` + `.ai/docs/` already deliver the full two-tier approach — so **a bare run does NOT emit a root `AGENTS.md`** (nor the per-tool projections). DeepInit emits the lean `AGENTS.md` (+ the projections in *Multi-agent projections* below) **only** as a **conditional cross-tool export**, when ANY of: a **cross-tool consumer is detected** (a `.cursor/` dir, `.github/copilot-instructions.md`, a `.windsurf/` dir — `detection.md`'s tool-dir detection) · `--canonical=agents` makes `AGENTS.md` the canonical content file · an explicit `--emit-agents` flag forces it. The cross-tool `AGENTS.md` carries the SAME lean tier and **MUST stay lean** (~100 lines — never a relocated brain). `emit_plan.py` reports `emit_agents_export` + the reason (`not_needed` / `cross_tool_detected` / `canonical_agents` / `forced`); the applied choice is **stated in the run summary** (R8 — never silent). *(`--canonical=claude` is the default; `--canonical=agents` swaps the roles — `AGENTS.md` becomes the content file and `CLAUDE.md` the thin `@AGENTS.md` import. Harness §59 G7 gates this model.)*
 
 ## Deep tier — `.ai/docs/` (on-demand, comprehensive, uncapped)
-Generation **finalizes** what extraction/horizontal produced in `.ai/docs/current/` into the published `.ai/docs/` layout (no token cap, D2-020):
+Generation **finalizes** the staging tree `.ai/docs/current/` — where Detect/Extract/Horizontal wrote their in-progress **doc** outputs alongside the `.deepinit_progress.json` resume checkpoint (`detection.md`/`extraction.md`/`horizontal.md`) — into the published, **FLAT** `.ai/docs/` layout below (no token cap, D2-020). Finalize **moves every published doc artifact up one level** (`.ai/docs/current/<doc>` → `.ai/docs/<doc>`) and **drops the staging-only intermediates** (Detect's `discovery.md`, the `.deepinit_progress.json` checkpoint, per-tool graphify scratch). **Staging→publish invariant (Emit-completeness): NO published DOC tier lingers under `.ai/docs/current/`** — `components/`, `decisions.md`, the horizontal docs, and `issues.md` all live FLAT under `.ai/docs/` in a finalized run; a `current/components/…` or `current/issues.md` beside the flat tree is a split-brain (finalize was interrupted — resume from the checkpoint), never the shipped shape. Any step writing a published doc under `.ai/docs/current/` MUST route through this finalize, never leave the doc stranded in `current/`. *(The ONLY artifacts that may remain under `current/` are the transient Detect outputs the report + the 0-token status keystone read from EITHER location — `structural-graph.json`, the checkpoint, the flat `.file_hashes.json`; `build_report.py` / `deepinit_status.py` try `current/` then flat.)* The published layout:
 ```
 .ai/docs/
   manifest.json
@@ -125,6 +125,19 @@ All issue content is **report-only**, **redacted** (runs through `redaction.md`
 
 **`.ai/docs/issues.md` — the deep issue ledger.** A **deep-tier REGENERATED** doc (like the five horizontal docs), with the R3 provenance header — **NOT an owned-region merge** (reserve owned-region + `.bak` for the lean `AGENTS.md` pointer line only). Per-component sections; each row is the `issues.md` §4.1 issue record (`ISS-` id, family, claim, provenance, severity, criticality, priority, certainty, verified, lifecycle, baseline). Only `verified` issues appear as confirmed; `[unverified]`/`[citation-weak]` stay clearly marked. **Dedup spans both representations:** the same drift may be a lean *context fact* (existing v2.0 behaviour, preserved by the Filter) AND an `ISS-` *defect* — the two are deduped, never cross-contaminated (the fact stays lean; the defect is deep-only). **Invariant:** a context fact and an issue are "the same finding" iff they share the issue baseline match-key `(file:line ± symbol)`; when they do, the *fact* may go lean (if non-obvious, per Filter) and the *defect* goes to `issues.md` only — **never the defect in lean, never both copies in lean.** **Worked example:** the fact "`orders.total` is `decimal(12,2)`" is lean context; the IF-2 defect "`orders.total` drifts — model `(10,2)` vs live DB `(12,4)`" shares that `file:line`, so it is emitted to the deep ledger only while the lean tier keeps just the factual type (no defect text, no duplication).
 
+**Canonical ledger markdown shape (emit EXACTLY this — the report parser reads it verbatim).** The report (`tools/build_docs_viewer.py :: parse_issues`, reused by `build_report.py`) recognizes each verified `ISS-` in EITHER of two equivalent forms — a **per-issue `### ISS-` block (H3)** grouped under a `## Component: <name>` / `## Fires (raised)` / lifecycle heading, **or** a **top-level `## ISS-` block (H2)** — using the SAME heading + `- **key:** value` bullets in both. `family`, `claim`, and `severity` are the load-bearing keys; keep the exact `- **<key>:**` spelling and one of the two headings. A ledger in any OTHER shape parses as **zero** verified issues and the report silently shows "0 issues" — so the report emits a build-time WARNING (`build_report.py :: issue_consistency_warnings`) whenever the parsed count disagrees with the manifest's `issues.counts.open`.
+```markdown
+## Component: <component>                                   # optional grouping heading (H2)
+### ISS-<comp>:<nnn> — <family> — <one-line title>          # per-issue block (H3); em-dash or hyphen separator
+- **family:** IF-1 | IF-2 | IF-3a | IF-4 | IF-5 | IF-6 | IF-7 | IF-8 | IF-10
+- **claim:** one-line, flag-don't-assert description of the potential issue
+- **provenance:** `path/to/file.ext:line`[, `…`]            # ≥1, repo-relative, verified
+- **severity:** Critical | High | Medium | Low              # ODC behaviour-impact (cosmetic ≈ Low)
+- **certainty:** HIGH | MEDIUM | LOW
+- **lifecycle:** open | resolved | regressed
+```
+(Equivalent top-level form: `## ISS-<comp>:<nnn> — <title>` with the same `- **family/claim/severity:**` bullets. `severity` is one of the canonical four; the report normalizes free-form synonyms into its five display tiers — `info`/`note` → Low, `trivial`/`nit` → cosmetic — see `build_report.py` `SEV_ALIASES`.)
+
 **`deepinit.sarif` — SARIF v2.1.0 (C-SARIF).** `tool.driver.rules[]` = the IF-families (`id: deepinit/IF-x`, `helpUri` → the family doc); each verified issue → `results[]` with `ruleId`, `level` (`error|warning|note` ← severity), `message.text` (the explanation), `locations[].physicalLocation` (`artifactLocation.uri` + `region.startLine` ← `file:line`), and `partialFingerprints` (← the **baseline match key**, via the shared normalization primitive defined in `issues.md` — enabling consumer-side baselining). **Semantic families (IF-1/IF-3a/IF-4) default to `note`/`warning`, never `error`,** until DeepInit's OWN measured FP justifies it (never a borrowed vendor severity; never flood a code host's Security tab). Emitted **downstream of redaction**; plugs into the existing D2-014 multi-agent-projection slot.
 
 Emit exactly this shape (the **machine-readable** contract GitHub code scanning ingests — the prose above maps onto these fields; the mandatory keys are `$schema`, `version: "2.1.0"`, `runs[].tool.driver.name`, and per-result `ruleId`/`level`/`message`/`locations`/`partialFingerprints`). `tool.driver.version` MUST be the **loaded DeepInit version** the run reports — never a fixed string; the `version` value in the example below is illustrative):

skills/deep-init/references/issues.md

@@ -42,6 +42,8 @@ ISS-{comp}:{nnn}                # or ISS-{nnn} for cross-component (R5)
   sarif_rule_id: deepinit/IF-1 …              # SARIF mapping (CD-E1)
   cross_model_agreement: (unset)               # reserved for AgentAlliance — SAME field name + honesty framing as verification.md (D2-019); never invent a parallel field
 ```
+**Emitted markdown SHAPE (the ledger the report parser reads).** The `.ai/docs/issues.md` ledger renders each record above as a per-issue markdown block, in EITHER a per-component `### ISS-<comp>:<nnn> — <family> — <title>` (H3) grouping under a `## Component: <name>` / `## Fires (raised)` / lifecycle heading, OR a top-level `## ISS-<comp>:<nnn> — <title>` (H2) block — with `- **family:** / - **claim:** / - **provenance:** / - **severity:** / - **certainty:** / - **lifecycle:**` bullets. The **exact heading + bullet-key shape is load-bearing** and pinned verbatim in `generation.md` "Issue outputs" (`family`/`claim`/`severity` are the keys `tools/build_docs_viewer.py :: parse_issues` reads); a divergent shape parses as **zero** verified issues (the emit↔parse consistency guard in `build_report.py` warns when the parsed count disagrees with `issues.counts.open`). Do NOT invent a new heading/bullet layout for the ledger.
+
 **Severity** is ODC-style behaviour-impact (a Core-entity unenforced write is High/Critical; cosmetic ≈ Low), **never** a borrowed vendor severity. **Raise only Core/Supporting**; Peripheral findings are listed in the deep tier only, never ranked up. **priority** ranks both the top-risk zones and every IF-1…IF-4 issue by the priority of its location (IF-5); mirror `filter.md`'s lean ranking, not a churn-only sort.
 
 ## Baseline match key + normalization — the shared primitive (§4.2 / §4.4)