Graph capability repairs — the 0.7.0 seams, simulation-verified

CHANGELOG.md

@@ -7,6 +7,70 @@ Versioning: [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+
+- **The after-edit impact card now actually fires.** Hosts send absolute file
+  paths while the spec's module index is repo-relative, so the PostToolUse
+  impact card (0.7.0) never rendered in real usage — 0/361 module paths resolved
+  on cladding-self, 99.2% after relativizing. The card also shows the
+  repo-relative path now.
+- **Legacy `F-NNN` ids joined the doc graph.** The doc scanner matched only
+  hash-style ids, so docs referencing legacy features (F-001…F-083, 80 live
+  shards) produced no edges and no `DOC_LINK_INTEGRITY` validation. One shared
+  F-id lexer (`src/spec/feature-id.ts`) now feeds both scan sites — +10 doc
+  references restored on cladding-self, zero new warnings.
+- **Shared-file blast radius is complete.** `clad_get_working_set` on a module
+  path seeded only the alphabetically-first owner, silently dropping the other
+  owners' dependents and regression tests (a hub file reported 0 impacted vs the
+  real 83). Module queries fan out to every owner now, and `breaks_if_changed`
+  finally participates in the token budget: deeper dependents clip first, the
+  depth-1 direct set is never dropped, and every clip is reported in
+  `budget.truncated`.
+- **`clad measure` attributes its numbers honestly.** The headline shrink factor
+  was mostly the 3000-token budget cap doing the work, not the graph. The report
+  now splits cap-driven vs structural shrink (the uncapped slice is ≈1.16x of
+  naive on cladding-self — code plus metadata, not smaller) and the CLI headline
+  says "budget enforces Nx" instead of selling cap arithmetic as savings. The
+  injected file reader now feeds both the slice and the baseline (one universe).
+- **The live viewer can no longer render stale.** SSE refresh compared node
+  COUNTS, so edge-only and same-count changes never redrew — it now compares the
+  server's exact graph text. The health pill counts distinct files (a file's
+  module/test/doc twin nodes counted once), and the mobile sidebar button works.
+- **`clad graph serve` fails honestly.** A mid-write or unparseable spec used to
+  answer HTTP 200 + a prose error labeled as JSON — now 503 with a JSON error
+  payload. A busy port prints one clean line instead of a raw stack; watcher
+  errors degrade to manual refresh; foreign Host headers are refused
+  (DNS-rebinding guard); and `/health.json` parses the spec once instead of ~10×
+  per request (611ms → 81ms measured).
+- **Graph sources are reviewable again.** Three source files carried raw NUL
+  bytes, so git treated them as binary — the 0.7.0 graph core shipped with a
+  review-invisible diff. Replaced with the six-character backslash-u-0000 escapes (byte-identical at
+  runtime, attestation digests unchanged) and guarded by a hygiene test.
+- **One file, one focus.** The same path can exist as a module, a test, and a
+  doc node at once (95 such paths on cladding-self); focus queries
+  (`--focus`, `clad_get_graph`) and health badges now cover all of a path's
+  nodes instead of the first one found.
+- Renderer/CLI hygiene: mermaid ids no longer collide silently, DOT/mermaid/
+  Obsidian labels escape their metacharacters, a typo'd `--format`/`--depth`
+  fails loudly instead of falling back to mermaid, a corrupt event-log line no
+  longer crashes `clad_get_events`, and the viewer bundle keeps three.js's MIT
+  notice.
+
+### Changed
+
+- **`clad_get_graph` without a focus returns a stats summary** (node/edge counts
+  by kind + top hubs, ~2KB) instead of the whole graph — the full dump measured
+  ~285KB (~70k tokens) in a single MCP result on cladding-self and grows with
+  the project. Pass a query for a neighborhood; `clad graph export --format
+  json` still dumps everything.
+- **`clad infer-deps` sees re-exports and literal dynamic imports**
+  (`export … from './x.js'`, `import('./x.js')`) — barrel-file dependencies now
+  produce edges, and a non-literal `import(expr)` flags the file as
+  under-reported. The JS/TS extraction path is now covered by fixtures (it
+  shipped with none).
+- Deprecated verb/prompt aliases (0.6.0 renames) now say "removed in 0.8" —
+  0.7.0 still shipped every alias while the notice claimed removal in 0.7.
+
 ## [0.7.0] — 2026-07-01 — Knowledge Graph
 
 ### Knowledge graph (spec↔code↔doc)
@@ -43,22 +107,25 @@ always-current graph you can query for impact and *see* in a graph viewer.
   graph tool. `--focus <id> --depth N` exports just one neighborhood. `stats`
   ranks the load-bearing hubs by degree.
 - **Our own graph viewer, colored by SSoT layer.** `clad graph export --format
-  html` writes one self-contained file you can double-click — a dependency-free
-  interactive graph (no internet, no install). Each spec layer gets its own color
-  (sealed spec / design / derived / audit), code sits in a neutral tone, and
-  features show their readable slug instead of an opaque id. Search, filter by
-  layer or kind, hover to light up a neighborhood, drag to pin, a "Live/Calm"
-  toggle, light/dark — all in one offline page.
-- **A live graph that follows your work.** `clad graph serve` opens the same
+  html` writes one self-contained file you can double-click — a fully offline
+  interactive graph (no internet, no install; the rendering library is bundled
+  inside the file). Each spec layer gets its own color (sealed spec / design /
+  derived / audit), code sits in a neutral tone, and features show their
+  readable slug instead of an opaque id. Search, filter by layer or kind, hover
+  for details, click a node to fly to its neighborhood, light/dark — all in one
+  offline page. *(Corrected 0.7.1: this entry originally described an earlier
+  2D prototype with force sliders and a Live/Calm toggle that did not ship —
+  what shipped is the WebGL viewer below.)*
+- **A live graph that follows your work.** `clad graph serve` hosts the same
   viewer at a local address and **updates itself as you edit** — change the spec
   or a doc and the open page reflects it, no re-export. Agents can read the same
   always-current graph through the new `clad_get_graph` tool.
-- **An Obsidian-grade viewer.** The layout is now a continuously-running force
-  simulation: drag a node and the web stretches and recoils with real tension;
-  hovering pauses the motion so you can read; four force sliders (center / repel /
-  link / link distance) retune it live. Each node class has its own color — the
-  four spec layers, and code/test/doc each distinct — so the structure reads at a
-  glance.
+- **A galaxy you can orbit.** The viewer renders the whole graph as a WebGL 3D
+  galaxy (three.js, bundled offline): spec at the core, code/tests/docs fanning
+  outward on their own shells, hubs sized by how load-bearing they are. The
+  layout is deterministic — the same graph always lands in the same shape (no
+  randomness), so an export is reproducible byte-for-byte. Drag to orbit, scroll
+  to zoom, click to focus.
 - **The killer: live conformance, healing as you watch.** Every node carries its
   real spec↔code health, computed from cladding's own drift detectors — a feature
   whose test went missing, a file no feature claims, a doc pointing at a deleted
@@ -70,10 +137,10 @@ always-current graph you can query for impact and *see* in a graph viewer.
 **Notes**
 
 - Drift detectors: 37 → 40 — this work adds `DOC_LINK_INTEGRITY` and `INFERABLE_DEPENDS_ON`; develop's `UNVERIFIED_AC` (below) is the third.
-- The viewer is hand-rolled (no bundled third-party graph library) to stay
-  dependency-free and fully offline; the layout draws itself and settles, then
-  stays calm. It is a way to *see and navigate* the spec↔code↔doc structure, not
-  a correctness check — run `clad check` for that.
+- The viewer bundles three.js into the single offline file (no CDN, no network
+  request — *corrected 0.7.1: this note originally claimed "no bundled
+  third-party graph library"*). It is a way to *see and navigate* the
+  spec↔code↔doc structure, not a correctness check — run `clad check` for that.
 - Design + measured cost/benefit model: `docs/knowledge-graph/design.md`.
 ### Added
 

README.md

@@ -112,7 +112,7 @@ Blue = spec (center), orange = code, green = tests, pink = docs; more-connected
 
 </div>
 
-- **See — the whole project on one canvas** — Run `clad graph serve` and it opens in your browser; you see what connects to what at a glance.
+- **See — the whole project on one canvas** — Run `clad graph serve`, open the printed localhost address in your browser, and you see what connects to what at a glance.
 - **Ask — "what breaks if I change this?"** — Ask the map and it tells you what's affected and which tests to run — it doesn't guess.
 - **Measure — it shines brighter the larger the project** — The amount you have to look at when fixing something drops sharply — on average **4× less** than reading everything. (`clad measure`)
 

docs/ab-evaluation/case-efficiency-measurement.md

@@ -34,6 +34,17 @@ its shard+modules, and the graph resolves the dependency radius + the exact regr
 > different statistic from the 4.1× median-of-ratios, not a contradiction. Both come straight
 > from `clad measure` (`medianShrinkFactor` vs `medianSliceTokens`/`medianNaiveTokens`).
 
+> **Correction (0.7.1 — cap attribution).** A later validity check showed the shrink numbers
+> above are largely the working set's **3000-token default budget** doing the compressing, not
+> the graph: with the cap lifted, the structural slice is ≈**1.16× of naive** on cladding-self —
+> the slice is the code PLUS structured metadata, not a smaller artifact. On cladding-self
+> 163/199 features hit the cap (their "shrink" is cap arithmetic, ≈3.9×) while the 36 that fit
+> actually grow (0.7×). `clad measure` now reports the split (`fitsCount`/`truncatedCount`,
+> `medianShrinkFit`/`medianShrinkTruncated`, `medianStructuralRatio`) and its headline
+> attributes the reduction to the budget. Read the vapt 4.1× above the same way: the honest
+> claim is **a guaranteed token budget with needs/breaks/verify wiring attached**, not "N×
+> smaller context".
+
 ## Honest scope (what this does and does NOT claim)
 - This is the efficiency the **infrastructure CAN provide** — an upper bound vs **one** naive
   baseline (shard + all module files). It is real, deterministic, and model-independent.
@@ -49,10 +60,12 @@ its shard+modules, and the graph resolves the dependency radius + the exact regr
   cheaper end-to-end (it greps anyway). Consistent with the long-standing governance-⊥-correctness
   prior.
 - **Goal axes (search + context efficiency, stability/traceability)**: **POSITIVE + now quantified**
-  — 4.1× smaller context per change, dependency radius + regression set resolved deterministically,
-  a queryable/visualizable dependency graph (0→698 edges on vapt). This is the value to feature:
-  *cladding makes the context for a change small, the blast radius explicit, and the regression set
-  known* — for humans and for agents that choose to use it — not "smarter agents".
+  — a budget-guaranteed bounded context per change (see the 0.7.1 correction: the raw "4.1×
+  smaller" is the budget cap enforcing the bound, not structural shrink), dependency radius +
+  regression set resolved deterministically, a queryable/visualizable dependency graph (0→698
+  edges on vapt). This is the value to feature: *cladding makes the context for a change bounded,
+  the blast radius explicit, and the regression set known* — for humans and for agents that
+  choose to use it — not "smarter agents".
 
 **Reproduce:** `clad measure` (table) or `clad measure --json` (per-feature). Original vapt
 untouched; measured on a disposable clone. No push/deploy.

docs/glossary.md

@@ -65,7 +65,7 @@
 | `impact` | stable (0.7.0) | Print the blast radius for a change — the transitive dependents of a feature/file plus the scenarios and the regression test set to re-run. The backward complement of `context` (what depends on this, vs what this needs). | 영향 반경(blast radius) |
 | `measure` | stable (0.7.0) | Report the search + context efficiency the graph provides per feature — working-set tokens vs the naive (shard + all module files) baseline, dependency depth/edges resolved, regression-set coverage. Deterministic; measures what the graph CAN provide, not agent adoption. | 효율 측정 |
 | `infer`-deps | stable (0.7.0) | Suggest feature `depends_on` edges from the code import graph — the dependency edges cladding never auto-produced. Resolves each module's imports to the owning feature; prints reviewable suggestions (a human merges them — anti-self-cert). | 의존 추론 |
-| `graph` | stable (0.7.0) | Render the spec↔code↔doc knowledge graph for a viewer (`export` → mermaid/dot/json/Obsidian-vault) or report its shape (`stats` → counts + hubs). Reuses best-in-class viewers instead of a bespoke UI. | 지식 그래프 |
+| `graph` | stable (0.7.0) | Render the spec↔code↔doc knowledge graph: `export` → mermaid/dot/json/Obsidian-vault or a self-contained offline `html` viewer (WebGL, three.js bundled); `serve` → the same viewer live on localhost, auto-reloading as spec/docs change; `stats` → counts + hubs. | 지식 그래프 |
 | `hook` | stable (0.6.0) | Host hook protocol adapter — consumes one host lifecycle event (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop) as stdin JSON; always exits 0. Honest limit: PreToolUse blocking only sees Edit/Write tool calls — a YAML edit made through Bash bypasses lane one; the Stop hook's post-hoc detectors are lane two. Neither lane alone is the guarantee. | 호스트 훅 프로토콜 어댑터 |
 | `changelog` | stable (0.6.0) | Render shipped changes since a git ref into human-facing documents — capability-grouped markdown / `--json` manifest / `--audit` verification table / `--catalog` spec listing. Named `changelog` deliberately, NOT `digest` (which means cryptographic hash in this domain — see Naming conventions). | 변경 이력 렌더링 |
 

docs/knowledge-graph/design.md

@@ -1,10 +1,12 @@
 # Cladding Knowledge Graph — design & cost model
 
-> Status: design (v0.7.0 track). Honest framing: this layer improves **traceability
-> completeness** and **context-selection efficiency (retrieval)**. It does **not**
-> improve LLM correctness or "reasoning depth" — cladding's own A/B record shows
-> conformance is orthogonal to the spec layer (vanilla ties cladding across 6 domains).
-> We sell *connection that stays current* and *bounded context*, not smarter answers.
+> Status: design (v0.7.0 track), with a **post-ship addendum (§8)** recording where
+> the shipped capability deliberately departed from this document. Honest framing:
+> this layer improves **traceability completeness** and **context-selection
+> efficiency (retrieval)**. It does **not** improve LLM correctness or "reasoning
+> depth" — cladding's own A/B record shows conformance is orthogonal to the spec
+> layer (vanilla ties cladding across 6 domains). We sell *connection that stays
+> current* and *bounded context*, not smarter answers.
 
 ## 1. Why (the SSoT thesis, made queryable)
 
@@ -137,3 +139,32 @@ Each: author shard (hash id) → implement → blind-author tests (separate cont
 `clad done` (flips only on GREEN `clad check --tier=pre-push --strict`). Modules are
 shared (`src/spec`, `src/optimizer`, `src/serve`, `src/stages/detectors`), so the
 features run sequentially.
+
+## 8. Post-ship addendum (2026-07-02) — where v0.7.0 departed from this design
+
+This document froze the decision record as of planning. Three decisions were
+reversed or extended during delivery; recording them here keeps this doc honest
+instead of contradicting the shipped tree ("all documents connected, always
+current" must apply to the design doc itself).
+
+- **§5's "no bespoke web UI" was reversed.** v0.7.0 shipped a bespoke viewer
+  after all: a self-contained offline HTML export (`--format html`) and a live
+  server (`clad graph serve`, node:http + SSE auto-reload), rendering the graph
+  as a deterministic WebGL galaxy (three.js bundled — F-02343cd1, F-77f7ead0,
+  F-64a5c159). Why the reversal held up: the mermaid/DOT/Obsidian emitters
+  stayed (this section's real point — reuse where viewers exist), but no
+  existing viewer could show cladding's differentiator — per-node LIVE
+  spec↔code conformance from our own drift detectors (`/health.json`,
+  graph-health stage) — so the "high-effort, low-marginal-value" premise no
+  longer applied to that slice of value. The export formats and `stats` shipped
+  exactly as designed.
+- **`clad_get_dependents` shipped as `clad_get_impact`** (plus `clad impact` on
+  the CLI); the forward/backward pair is `clad_get_context` / `clad_get_impact`.
+- **Scope grew beyond §6 IN:** working-set assembly (`clad_get_working_set`),
+  iterative impact slicing, `clad infer-deps` (restoring the empty `depends_on`
+  data layer), and `clad measure` shipped in the same track.
+- **`spec/_doc-links.yaml` is a grep/human index, not the export source.**
+  buildGraph re-derives doc edges from `docs/` directly on every build (that is
+  what keeps the live view current); the yaml exists so "which docs explain
+  feature X" is one grep away and so reviews can diff doc-link changes. §5's
+  "graph-export source" phrasing overstated it.