Release FeatureLens v0.10.0

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v0.10.0
+
+- Added a zero-extra-GPU **Discovery–causality alignment** panel after candidate triage.
+- Joined discovery rank/score with target-effect rank and next-token-distribution-shift rank for the same screened candidates.
+- Added descriptive Spearman ρ summaries for candidate evidence vs absolute target effect and vs next-token JS.
+- Added an association-evidence-vs-target-effect scatter plot and rank-shift table.
+- Kept the v0.9 in-place focus implementation unchanged after HF validation.
+- HF validation remains GPU-budget-aware: only the discovery and candidate-triage paths need to be exercised.
+
 ## v0.9.0
 
 ### In-place focus and layout polish

README.md

@@ -13,7 +13,7 @@ license: mit
 
 # FeatureLens — Causal Interpretability Workbench
 
-> **v0.9:** a GPU-budget-aware discovery-to-causality workflow with in-place aspect-preserving focus, compact result headings, causal-ready candidate discovery, and a batched multi-candidate ablation screen before the full random-control causal test.
+> **v0.10:** an association-to-causality synthesis workflow that joins concept discovery and batched causal triage, exposes rank disagreement, and quantifies descriptive concordance without spending another GPU call.
 
 **Research question:**
 
@@ -37,6 +37,7 @@ FeatureLens uses **Qwen3-1.7B-Base** with **Qwen-Scope residual-stream sparse au
 11. **Specificity** — are targeted effects larger than norm-matched random residual perturbations?
 12. **Contrastive specificity** — does an edit change preference between a desired and comparison continuation?
 13. **Geometry** — are selected SAE decoder directions aligned, orthogonal, or cancelling before downstream model non-linearity?
+14. **Association–causality concordance** — do features ranked highly by concept evidence also rank highly by downstream target effect or distribution shift?
 
 A high AUROC, high paraphrase overlap, or a large activation is still correlational evidence. Causal evidence comes from downstream change under controlled intervention.
 
@@ -348,15 +349,14 @@ FeatureLens/
 └── research_config.json
 ```
 
-## v0.9 live workflow improvements
+## v0.10 association-to-causality synthesis
 
-- **Causal-ready candidate ranking** requires concept contrast and current-token activity before suggesting a feature for immediate intervention.
-- **Batched causal candidate triage** screens up to eight discovered candidates in one target-scoring batch before the expensive random-control causal test.
-- **Dose response** has independent feature and target inputs with concise scale semantics.
-- **Cue × context interpretation** reports cue-dominant tested patterns from the measured activation matrix rather than generic boilerplate.
-- **In-place focus** expands plots/tables at their existing page location and preserves plot aspect ratio instead of opening an HF-iframe overlay.
-- **Compact table headings** use the Dataframe toolbar band rather than leaving a large blank gap above the table.
-- HF validation is **GPU-budget-aware**: unchanged inference paths are not rerun on every release.
+- **Discovery–causality alignment** joins the concept-discovery table with the batched ablation screen for the same shortlist.
+- **Three ranks are kept separate:** discovery evidence, target-continuation effect, and whole next-token distribution shift.
+- **Descriptive Spearman concordance** reports candidate-score correlation with absolute target effect and with next-token JS; small live screens are never presented as significance tests.
+- **Rank-shift diagnostics** make cases such as a discovery-rank #1 feature becoming target-effect rank #5 immediately visible.
+- **Association-vs-target-effect scatter** is generated from the same two existing GPU calls; the synthesis itself costs no additional GPU time.
+- Existing v0.9 causal-ready discovery, candidate triage, in-place focus, and GPU-budget-aware validation remain unchanged.
 
 ## Validation
 
@@ -368,7 +368,7 @@ python scripts/ui_smoke.py
 python scripts/release_check.py
 ```
 
-See [`docs/VALIDATION.md`](docs/VALIDATION.md). The v0.9 validation guide uses the **exact labels shown in the UI** and deliberately avoids rerunning unchanged GPU-heavy regressions. HF acceptance is limited to code paths changed in this release.
+See [`docs/VALIDATION.md`](docs/VALIDATION.md). The v0.10 validation guide uses the **exact labels shown in the UI**. It reuses the existing discovery + triage workflow and does not ask for paraphrase, trajectory, feature-set, dose-response, or focus regressions because those implementations were not changed.
 
 ## Limitations
 
@@ -384,7 +384,7 @@ See [`docs/VALIDATION.md`](docs/VALIDATION.md). The v0.9 validation guide uses t
 ## Resume-ready description
 
 > **FeatureLens — Causal Interpretability Workbench** | PyTorch, Qwen3, Sparse Autoencoders, Mechanistic Interpretability, Gradio
-> Built an SAE-based interpretability system for Qwen3-1.7B with held-out concept discovery, concept-guided candidate discovery, token/prompt-wide, completion-cue, and cue × context feature evidence, reconstruction-preserving single and multi-feature interventions, full-continuation and contrastive preference scoring, dose-response analysis, decoder-geometry/non-additivity diagnostics, and norm-matched random-control ensembles.
+> Built an SAE-based interpretability system for Qwen3-1.7B with held-out concept discovery, concept-guided candidate discovery, token/prompt-wide, completion-cue, and cue × context feature evidence, reconstruction-preserving single and multi-feature interventions, full-continuation and contrastive preference scoring, dose-response analysis, decoder-geometry/non-additivity diagnostics, discovery-to-causality rank analysis, and norm-matched random-control ensembles.
 
 ## Acknowledgements
 

app.py

@@ -632,6 +632,123 @@ def _candidate_screen_metrics_markdown(result) -> str:
     )
 
 
+
+def _spearman_rank_corr(left: list[float], right: list[float]) -> float | None:
+    """Descriptive Spearman correlation with tie-aware average ranks."""
+    if len(left) != len(right) or len(left) < 2:
+        return None
+    left_s = pd.Series(left, dtype="float64")
+    right_s = pd.Series(right, dtype="float64")
+    if left_s.nunique(dropna=True) < 2 or right_s.nunique(dropna=True) < 2:
+        return None
+    value = left_s.rank(method="average").corr(right_s.rank(method="average"))
+    return None if pd.isna(value) else float(value)
+
+
+def _candidate_alignment_outputs(
+    discovery_table: pd.DataFrame | None,
+    screen_table: pd.DataFrame | None,
+) -> tuple[str, pd.DataFrame, pd.DataFrame]:
+    """Join discovery evidence to causal triage results without another model call."""
+    empty_columns = [
+        "Feature id",
+        "Discovery rank",
+        "Target-effect rank",
+        "Distribution-shift rank",
+        "Candidate score",
+        "Selectivity",
+        "Current token activation",
+        "|Δ mean log p/token|",
+        "Next-token JS",
+        "Discovery→target rank shift",
+    ]
+    if discovery_table is None or screen_table is None:
+        return "", pd.DataFrame(columns=empty_columns), pd.DataFrame()
+    discovery = pd.DataFrame(discovery_table).copy()
+    screen = pd.DataFrame(screen_table).copy()
+    if discovery.empty or screen.empty or "Feature id" not in discovery or "Feature id" not in screen:
+        return "", pd.DataFrame(columns=empty_columns), pd.DataFrame()
+
+    discovery["Feature id"] = pd.to_numeric(discovery["Feature id"], errors="coerce")
+    screen["Feature id"] = pd.to_numeric(screen["Feature id"], errors="coerce")
+    discovery = discovery.dropna(subset=["Feature id"]).copy()
+    screen = screen.dropna(subset=["Feature id"]).copy()
+    discovery["Feature id"] = discovery["Feature id"].astype(int)
+    screen["Feature id"] = screen["Feature id"].astype(int)
+
+    needed_discovery = {"Rank", "Candidate score", "Selectivity", "Current token activation"}
+    needed_screen = {"Rank", "Δ mean log p/token", "Next-token JS"}
+    if not needed_discovery.issubset(discovery.columns) or not needed_screen.issubset(screen.columns):
+        return "", pd.DataFrame(columns=empty_columns), pd.DataFrame()
+
+    discovery_lookup = discovery.set_index("Feature id", drop=False)
+    js_ranked = screen.sort_values(["Next-token JS", "Feature id"], ascending=[False, True]).reset_index(drop=True)
+    js_ranks = {int(row["Feature id"]): rank for rank, (_, row) in enumerate(js_ranked.iterrows(), start=1)}
+
+    rows: list[list[object]] = []
+    for _, causal_row in screen.iterrows():
+        feature_id = int(causal_row["Feature id"])
+        if feature_id not in discovery_lookup.index:
+            continue
+        discovery_row = discovery_lookup.loc[feature_id]
+        # set_index can technically return a DataFrame for duplicate ids; use the first row deterministically.
+        if isinstance(discovery_row, pd.DataFrame):
+            discovery_row = discovery_row.iloc[0]
+        discovery_rank = int(float(discovery_row["Rank"]))
+        target_rank = int(float(causal_row["Rank"]))
+        mean_delta = float(causal_row["Δ mean log p/token"])
+        rows.append(
+            [
+                feature_id,
+                discovery_rank,
+                target_rank,
+                int(js_ranks[feature_id]),
+                float(discovery_row["Candidate score"]),
+                float(discovery_row["Selectivity"]),
+                float(discovery_row["Current token activation"]),
+                abs(mean_delta),
+                float(causal_row["Next-token JS"]),
+                discovery_rank - target_rank,
+            ]
+        )
+
+    table = pd.DataFrame(rows, columns=empty_columns)
+    if table.empty:
+        return "", table, pd.DataFrame()
+
+    rho_target = _spearman_rank_corr(
+        table["Candidate score"].astype(float).tolist(),
+        table["|Δ mean log p/token|"].astype(float).tolist(),
+    )
+    rho_js = _spearman_rank_corr(
+        table["Candidate score"].astype(float).tolist(),
+        table["Next-token JS"].astype(float).tolist(),
+    )
+
+    top_discovery = table.sort_values(["Discovery rank", "Feature id"]).iloc[0]
+    top_target = table.sort_values(["Target-effect rank", "Feature id"]).iloc[0]
+    top_js = table.sort_values(["Distribution-shift rank", "Feature id"]).iloc[0]
+
+    def fmt_rho(value: float | None) -> str:
+        return "undefined" if value is None else f"{value:+.3f}"
+
+    summary = (
+        f"Compared **{len(table)}** screened candidates using the discovery evidence and causal triage from the same workflow.  \n"
+        f"Top discovery candidate: **{int(top_discovery['Feature id'])}** · strongest target effect: "
+        f"**{int(top_target['Feature id'])}** · strongest next-token distribution shift: **{int(top_js['Feature id'])}**.  \n"
+        f"Spearman ρ(candidate score, |target effect|): **{fmt_rho(rho_target)}** · "
+        f"ρ(candidate score, next-token JS): **{fmt_rho(rho_js)}**.  \n\n"
+        "This is the project's central association-vs-causality diagnostic: a feature can rank highly by concept evidence yet "
+        "rank weakly by downstream target effect, or vice versa. With only a handful of screened features and no random-control "
+        "ensemble in triage, these correlations are **descriptive**, not significance claims."
+    )
+
+    chart = table[["Feature id", "Candidate score", "|Δ mean log p/token|", "Discovery rank", "Target-effect rank", "Next-token JS"]].copy()
+    chart["Feature id"] = chart["Feature id"].astype(str)
+    chart["Series"] = "Screened candidate"
+    return summary, table, chart
+
+
 def _cue_context_metrics_markdown(result) -> str:
     active = ", ".join(
         f"{cue}: {count}/{len(result.stems)} contexts"
@@ -1197,6 +1314,7 @@ def run_candidate_causal_screen(
     token_index: int,
     feature_ids: list[str] | None,
     target_text: str,
+    discovery_table: pd.DataFrame | None,
 ):
     try:
         selected = [int(float(value)) for value in (feature_ids or [])]
@@ -1228,12 +1346,19 @@ def run_candidate_causal_screen(
             choices=choices,
             value=choices[0] if choices else None,
         )
+        alignment_metrics, alignment_table, alignment_chart = _candidate_alignment_outputs(
+            discovery_table, table
+        )
         return (
             _candidate_screen_metrics_markdown(result),
             table,
             chart,
             candidate_update,
             _tsv(table),
+            alignment_metrics,
+            alignment_table,
+            alignment_chart,
+            _tsv(alignment_table),
         )
     except Exception as exc:
         _raise_ui_error(exc)
@@ -1320,7 +1445,7 @@ def set_mode_help(mode: str):
 with gr.Blocks(title="FeatureLens — Causal Interpretability Workbench", fill_width=True) as demo:
     gr.HTML(
         '<header class="hero">'
-        '<h1>FeatureLens <span style="font-size:.48em;opacity:.58;font-weight:400">v0.9</span></h1>'
+        '<h1>FeatureLens <span style="font-size:.48em;opacity:.58;font-weight:400">v0.10</span></h1>'
         '<div class="subtitle">Causal Interpretability Workbench</div>'
         '<div class="question">Discover sparse features, test robustness, and separate correlation from causal influence.</div>'
         '</header>'
@@ -1908,6 +2033,48 @@ with gr.Blocks(title="FeatureLens — Causal Interpretability Workbench", fill_w
             elem_classes=["candidate-help"],
         )
 
+        gr.Markdown("#### Association vs causal influence")
+        gr.Markdown(
+            "Computed from the discovery table and the ablation screen above — **no additional GPU call**. "
+            "It compares concept-evidence rank with target-effect and distribution-shift ranks for the same shortlist.",
+            elem_classes=["candidate-help"],
+        )
+        candidate_alignment_metrics = gr.Markdown()
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=3):
+                _table_heading('Discovery–causality alignment')
+                candidate_alignment_table = gr.Dataframe(
+                    interactive=False,
+                    label="Discovery–causality alignment",
+                    show_label=False,
+                    buttons=["fullscreen"],
+                    elem_classes=["result-table"],
+                    wrap=False,
+                    max_height=360,
+                )
+                candidate_alignment_tsv = gr.Textbox(visible="hidden")
+                candidate_alignment_copy = _copy_button()
+            with gr.Column(scale=2):
+                candidate_alignment_plot = gr.ScatterPlot(
+                    x="Candidate score",
+                    y="|Δ mean log p/token|",
+                    color="Series",
+                    color_map={"Screened candidate": INK_TEAL},
+                    title="Association evidence vs target effect",
+                    elem_id="plot-association-causality",
+                    x_title="Discovery candidate score",
+                    y_title="|Δ mean log p/token|",
+                    tooltip=[
+                        "Feature id",
+                        "Discovery rank",
+                        "Target-effect rank",
+                        "Next-token JS",
+                    ],
+                    buttons=["fullscreen", "export"],
+                    elem_classes=["fl-plot"],
+                    height=330,
+                )
+
         gr.HTML('<div class="section-rule">C. Inspect one feature</div>')
         contrast_location = gr.Markdown(
             "**Activation trace uses the current Workbench prompt.** The controlled concept scan below uses its own balanced prompt set."
@@ -2334,13 +2501,24 @@ Association, robustness, geometry, and intervention evidence remain separate cla
     )
     candidate_screen_btn.click(
         run_candidate_causal_screen,
-        inputs=[prompt, discovery_layer, token_index, candidate_screen_ids, candidate_screen_target],
+        inputs=[
+            prompt,
+            discovery_layer,
+            token_index,
+            candidate_screen_ids,
+            candidate_screen_target,
+            discovery_table,
+        ],
         outputs=[
             candidate_screen_metrics,
             candidate_screen_table,
             candidate_screen_plot,
             discovery_candidate,
             candidate_screen_tsv,
+            candidate_alignment_metrics,
+            candidate_alignment_table,
+            candidate_alignment_plot,
+            candidate_alignment_tsv,
         ],
     )
     candidate_screen_table.select(
@@ -2397,6 +2575,7 @@ Association, robustness, geometry, and intervention evidence remain separate cla
         (contrast_copy, contrast_tsv),
         (discovery_copy, discovery_tsv),
         (candidate_screen_copy, candidate_screen_tsv),
+        (candidate_alignment_copy, candidate_alignment_tsv),
         (cue_copy, cue_tsv),
         (cue_context_copy, cue_context_tsv),
         (para_copy, para_tsv),

docs/METHODOLOGY.md

@@ -439,3 +439,26 @@ for each candidate feature $i$, stacks a zero-edit reference plus all candidate
 Rows are ordered by absolute target mean-log-probability effect. This ordering is deliberately a **native-ablation effect screen**, not a significance or specificity statistic. No random-control ensemble is used at this stage. A promising candidate should be promoted to the existing single-feature causal test, which compares the SAE edit with the eight-direction norm-matched random ensemble.
 
 This two-stage design reduces live GPU use while preserving the stronger causal standard for any result that is ultimately interpreted.
+
+
+## v0.10 discovery-to-causality concordance
+
+The central FeatureLens question is not only whether a concept-associated SAE feature can be intervened on, but whether **association strength predicts causal influence**. v0.10 therefore joins the live concept-discovery evidence with the batched candidate-ablation screen for the same shortlist.
+
+For each screened feature, the synthesis keeps three orderings separate:
+
+1. **Discovery rank** from the chosen exploratory concept-evidence score.
+2. **Target-effect rank** from $|\Delta \bar{\ell}_{\mathrm{target}}|$, the absolute change in teacher-forced mean target log-probability per token under native ablation.
+3. **Distribution-shift rank** from next-token Jensen–Shannon divergence.
+
+The UI also reports a rank shift
+
+$$
+\Delta r_i = r_i^{\mathrm{discovery}} - r_i^{\mathrm{target}},
+$$
+
+so positive values indicate a feature that rises in the target-effect ordering relative to discovery, while negative values indicate a feature that looked stronger associatively than causally for the specified continuation.
+
+Across the small screened set, FeatureLens computes tie-aware Spearman correlations between candidate score and (a) absolute target effect and (b) next-token JS. These are deliberately labeled **descriptive** because the live shortlist is small and the triage stage does not spend random-control ensembles. A promoted feature still requires the full single-feature causal test before specificity is interpreted.
+
+This synthesis costs no additional model forward: it is computed from the discovery and triage tables already produced by the two-stage workflow.

docs/VALIDATION.md

@@ -1,6 +1,8 @@
-# FeatureLens v0.9 validation
+# FeatureLens v0.10 validation
 
-This guide intentionally **does not** ask you to rerun unchanged GPU-heavy regressions. Identity paraphrase, layer trajectory, and the 1/3/5 feature-set sweep were unchanged in v0.9 and remain covered by automated tests. Save the HF ZeroGPU quota for the two inference paths changed/added here.
+v0.10 does **not** change paraphrase robustness, layer trajectory, feature-set interventions, dose-response inference, cue × context, or the in-place focus implementation. Do not spend ZeroGPU quota rerunning those paths.
+
+The only new live behavior is the **association-to-causality synthesis** computed after the existing discovery + candidate-triage workflow.
 
 ## 1. Local release gate — no HF GPU
 
@@ -19,25 +21,25 @@ Expected high-level result:
 - all tests pass;
 - Ruff reports `All checks passed!`;
 - `FeatureLens UI launch smoke: PASS`;
-- release check ends with `release: v0.9.0`.
+- release check ends with `release: v0.10.0`.
 
-If any command fails, stop there rather than running HF tests.
+Stop if any local gate fails.
 
 ---
 
-# HF acceptance — only two GPU calls required
+# HF acceptance — two GPU calls total
 
-Keep the default Workbench prompt unless stated otherwise:
+Use the existing Workbench context:
 
 - **Workbench → Prompt:** `The derivative of x squared is`
 - **Workbench → Residual layer:** `14`
 - **Workbench → Prompt token index:** `-1`
 
-You do **not** need to run **Inspect sparse features** first for these v0.9 checks.
+You do **not** need to click **Inspect sparse features** first.
 
-## 2. GPU call 1 — causal-ready discovery + layout/focus test
+## 2. GPU call 1 — causal-ready mathematics discovery
 
-Go to:
+Exact path:
 
 **Feature evidence → A. Concept-guided candidate discovery**
 
@@ -53,46 +55,21 @@ Click:
 
 **Discover concept-associated candidates**
 
-### Pass conditions
-
-1. **Candidate feature evidence** is visually close to the table itself. There should not be a large empty band between the heading and the first table row/header.
-2. **Candidate features to screen** in section B is automatically populated with up to the first five returned candidate IDs.
-3. The discovery summary says all displayed candidates are active at the selected Workbench token for this ranking.
-4. No page jump occurs merely because results render.
-
-### In-place plot focus
-
-On the **Candidate evidence score** graph, click the existing fullscreen/focus toolbar icon.
-
-Pass if:
+Expected regression behavior from v0.9:
 
-- the chart expands **where it already sits on the page**;
-- it does not jump to the top of the HF Space;
-- it remains aspect-ratio preserving rather than becoming extremely tall/long;
-- it does not require horizontal page traversal;
-- clicking the same icon again (or pressing `Esc`) returns it to the normal size without changing your surrounding page location.
+- the summary should say `12/12` displayed candidates are active at the selected Workbench token;
+- **Candidate features to screen** should auto-populate with the first five returned feature IDs;
+- no additional UI/focus regression testing is required because that code was not changed in v0.10.
 
-### In-place table focus
+For the current canonical prompt, the v0.9 result began with candidates `16369`, `5712`, `26112`, `25992`, `21670`. Exact floating-point values can vary slightly, but a major ordering change should be reported.
 
-Click the fullscreen/focus icon on **Candidate feature evidence**.
-
-Pass if:
-
-- the table widens at its current location rather than opening at the top of the Space;
-- the surrounding page position is unchanged after toggling back;
-- horizontal scrolling stays inside the table when needed.
-
-Do not rerun discovery merely to test focus. Use this already-populated output for both focus checks.
-
----
+## 3. GPU call 2 — triage + association-to-causality synthesis
 
-## 3. GPU call 2 — batched causal candidate triage
-
-Stay in:
+Exact path:
 
 **Feature evidence → B. Batched causal candidate triage**
 
-The discovery run should already have populated **Candidate features to screen**. Leave the default first five candidates selected unless fewer than five were returned.
+Leave the five auto-populated candidates selected.
 
 Set:
 
@@ -102,53 +79,76 @@ Click:
 
 **Screen candidate ablations**
 
-### Expected output
+The normal **Candidate ablation screen** should appear first.
+
+Immediately below it, without another GPU action, v0.10 should populate:
+
+### `Association vs causal influence`
 
-The summary should explicitly call this a **triage screen** and explain that the full random-control ensemble is deferred to **Workbench → II. Single-feature causal test**.
+with:
 
-The **Candidate ablation screen** table must contain these columns:
+1. a descriptive summary;
+2. **Discovery–causality alignment** table;
+3. **Association evidence vs target effect** scatter plot.
+
+### Required alignment-table columns
 
-- `Rank`
 - `Feature id`
-- `Native activation`
-- `Active at current token`
-- `Perturbation L2`
-- `Δ mean log p/token`
-- `Δ sequence log p`
+- `Discovery rank`
+- `Target-effect rank`
+- `Distribution-shift rank`
+- `Candidate score`
+- `Selectivity`
+- `Current token activation`
+- `|Δ mean log p/token|`
 - `Next-token JS`
+- `Discovery→target rank shift`
+
+### Required summary behavior
 
-Pass if:
+The summary must identify separately:
 
-- all selected causal-ready candidates report `Active at current token = True`;
-- rows are ordered from the largest absolute `Δ mean log p/token` to the smallest;
-- the 1st-ranked screen result is automatically placed into **Selected candidate feature id**;
-- clicking another row updates **Selected candidate feature id** without a GPU call;
-- the plot and table focus controls behave in-place as in Test 2.
+- top discovery candidate;
+- strongest target-effect candidate;
+- strongest next-token distribution-shift candidate;
+- Spearman `ρ(candidate score, |target effect|)`;
+- Spearman `ρ(candidate score, next-token JS)`;
+- an explicit warning that the live correlations are descriptive because the screened set is small and triage has no random-control ensemble.
 
-### What to send back
+For the exact v0.9 values you reported, the expected qualitative pattern is:
 
-For v0.9 I only need:
+- discovery rank #1: feature `16369`;
+- strongest target effect: feature `25992`;
+- strongest next-token JS shift: feature `16369`;
+- discovery score versus target-effect magnitude: strongly negative descriptive rank correlation;
+- discovery score versus JS: positive but weaker descriptive rank correlation.
 
-1. the **Candidate ablation screen** table;
-2. the triage summary;
-3. whether plot focus passed;
-4. whether table focus passed;
-5. whether heading/table spacing now looks natural.
+Do not require exact decimals as a pass condition.
 
-No paraphrase, layer-trajectory, feature-set-sweep, or dose-response reruns are required for v0.9 acceptance because those inference implementations were not changed.
+### Rank-shift sanity check
+
+For the v0.9 ordering:
+
+- feature `25992`: discovery rank `4`, target-effect rank `1` → `Discovery→target rank shift = +3`;
+- feature `16369`: discovery rank `1`, target-effect rank `5` → rank shift `-4`.
+
+This is the most important v0.10 regression check because it demonstrates that concept-evidence rank and target-causal rank are not interchangeable.
 
 ---
 
-## 4. Zero-GPU visual checks
+## 4. What to send back
+
+Only send:
 
-These do not require running an experiment:
+1. the v0.10 **Candidate ablation screen** if it changed materially from v0.9;
+2. the new **Discovery–causality alignment** table;
+3. the new association/causality summary with the two Spearman values;
+4. optionally a screenshot of **Association evidence vs target effect** if the plot looks wrong.
 
-- **Workbench → III. Single-feature scale dose-response** should show its own **Dose-response feature id** and **Dose-response target continuation** fields without the old “Standalone experiment” explanation.
-- The short explanatory line should only define the 0× / 1× / 2× scale semantics.
-- Existing result-table headings should use the same compact spacing pattern throughout the app.
+Do **not** rerun identity paraphrase, layer trajectory, 1/3/5 sweep, dose response, cue × context, or focus behavior for v0.10. Those implementations were not changed.
 
 ---
 
 # Final hardening later
 
-The comprehensive adversarial suite (invalid feature IDs, long prompts, inactive-feature edge cases, rapid double clicks, mixed-language prompts, etc.) remains deferred until the live feature set is frozen. That final pass should be done once, not on every iteration.
+The broad adversarial/release suite remains deferred until the live feature set is frozen. After v0.10 acceptance, the next high-value step should be the real offline held-out benchmark rather than another round of unrelated live widgets.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "featurelens"
-version = "0.9.0"
+version = "0.10.0"
 description = "Causal sparse-feature interpretability workbench for Qwen3 and Qwen-Scope SAEs"
 requires-python = ">=3.10"
 

research_config.json

@@ -90,7 +90,7 @@
     "contrastive_continuation_preference_test",
     "feature_decoder_geometry"
   ],
-  "concept_candidate_discovery_metric": "balanced exploratory score = selectivity \u00d7 target activation rate \u00d7 log1p(target mean); causal-ready mode additionally requires current-token activity and log-scales that activation; raw mean-difference remains available as a scale-sensitive comparison",
+  "concept_candidate_discovery_metric": "balanced exploratory score = selectivity × target activation rate × log1p(target mean); causal-ready mode additionally requires current-token activity and log-scales that activation; raw mean-difference remains available as a scale-sensitive comparison",
   "completion_cue_scan": "final-token feature activation after controlled suffix/cue substitution",
   "live_features_v0_6": [
     "start_here_plain_language_onboarding",
@@ -126,5 +126,18 @@
     "concise_independent_dose_response_copy",
     "batched_candidate_causal_triage",
     "gpu_budget_aware_hf_validation_scope"
+  ],
+  "candidate_alignment_metrics": [
+    "discovery rank versus target-effect rank",
+    "discovery rank versus next-token JS rank",
+    "Spearman candidate score versus absolute target effect",
+    "Spearman candidate score versus next-token JS"
+  ],
+  "live_features_v0_10": [
+    "discovery_to_causality_alignment_table",
+    "association_evidence_vs_target_effect_scatter",
+    "descriptive_spearman_concordance_summary",
+    "target_effect_vs_distribution_shift_rank_separation",
+    "no_extra_gpu_candidate_synthesis"
   ]
 }

scripts/release_check.py

@@ -256,16 +256,20 @@ def check_readme() -> None:
         'batched causal candidate triage',
         'in-place',
         'gpu',
+        'discovery–causality alignment',
+        'spearman',
+        'rank-shift',
+        'no additional gpu',
     ]
     missing = [value for value in required_strings if value.lower() not in readme.lower()]
     if missing:
-        raise SystemExit(f'README.md is missing required v0.9 content: {missing}')
+        raise SystemExit(f'README.md is missing required v0.10 content: {missing}')
 
 
 def check_pyproject() -> None:
     text = (ROOT / 'pyproject.toml').read_text(encoding='utf-8')
-    if 'version = "0.9.0"' not in text:
-        raise SystemExit('pyproject.toml must declare version 0.9.0.')
+    if 'version = "0.10.0"' not in text:
+        raise SystemExit('pyproject.toml must declare version 0.10.0.')
 
 
 def main() -> None:
@@ -283,7 +287,7 @@ def main() -> None:
     print(f'  layers: {config["layers"]}')
     print(f'  feature-set sizes: {config["feature_set_sizes"]}')
     print(f'  random controls: {config["live_random_controls"]}')
-    print('  release: v0.9.0')
+    print('  release: v0.10.0')
 
 
 if __name__ == '__main__':

tests/test_ui_helpers.py

@@ -130,3 +130,54 @@ def test_candidate_screen_has_independent_target_and_multiselect() -> None:
     assert app.candidate_screen_target.value == '2x'
     assert app.candidate_screen_ids.multiselect is True
     assert app.candidate_screen_ids.max_choices == 8
+
+
+def test_candidate_alignment_exposes_discovery_causality_divergence() -> None:
+    app = _import_app()
+    discovery = pd.DataFrame(
+        [
+            [1, 16369, 4.7348, 15.0, 0.0, 15.0, 1.0, 0.5, 0.0, 50.0, 29.25, True],
+            [2, 5712, 4.1969, 9.1, 1.5, 7.6, 0.72, 1.0, 0.17, 11.4, 11.38, True],
+            [3, 26112, 3.9419, 10.8, 0.0, 10.8, 1.0, 0.5, 0.0, 23.4, 23.42, True],
+            [4, 25992, 3.7342, 10.1, 0.0, 10.1, 1.0, 0.5, 0.0, 21.4, 21.36, True],
+            [5, 21670, 3.6200, 18.9, 2.0, 16.9, 0.81, 0.75, 0.125, 25.3, 6.36, True],
+        ],
+        columns=[
+            'Rank', 'Feature id', 'Candidate score', 'Target mean max', 'Other mean max',
+            'Mean difference', 'Selectivity', 'Target activation rate', 'Other activation rate',
+            'Current prompt max', 'Current token activation', 'Active at current token',
+        ],
+    )
+    screen = pd.DataFrame(
+        [
+            [1, 25992, 21.3, True, 21.3, -0.1119, -0.2238, 0.001066],
+            [2, 21670, 6.36, True, 6.36, 0.0313, 0.0626, 0.000106],
+            [3, 26112, 23.4, True, 23.4, -0.0211, -0.0423, 0.000417],
+            [4, 5712, 11.38, True, 11.38, 0.0110, 0.0221, 0.000155],
+            [5, 16369, 29.23, True, 29.23, -0.0101, -0.0201, 0.001714],
+        ],
+        columns=[
+            'Rank', 'Feature id', 'Native activation', 'Active at current token', 'Perturbation L2',
+            'Δ mean log p/token', 'Δ sequence log p', 'Next-token JS',
+        ],
+    )
+    summary, table, chart = app._candidate_alignment_outputs(discovery, screen)
+    assert len(table) == 5
+    assert int(table.loc[table['Target-effect rank'].idxmin(), 'Feature id']) == 25992
+    assert int(table.loc[table['Distribution-shift rank'].idxmin(), 'Feature id']) == 16369
+    row_25992 = table.loc[table['Feature id'] == 25992].iloc[0]
+    row_16369 = table.loc[table['Feature id'] == 16369].iloc[0]
+    assert int(row_25992['Discovery→target rank shift']) == 3
+    assert int(row_16369['Discovery→target rank shift']) == -4
+    assert 'Spearman' in summary
+    assert '-0.900' in summary
+    assert '+0.600' in summary
+    assert 'descriptive' in summary
+    assert set(chart['Feature id']) == {'16369', '5712', '26112', '25992', '21670'}
+
+
+def test_candidate_alignment_ui_uses_same_screen_call_and_no_new_gpu_button() -> None:
+    app = _import_app()
+    assert app.candidate_alignment_table.show_label is False
+    assert app.candidate_alignment_plot.visible is True
+    assert 'Association evidence vs target effect' == app.candidate_alignment_plot.title