| file:line | issue | concrete fix |
| --- | --- | --- |
| `AGENTS.md:3-4` | Archaeology — CUT: `Plan of record: /home/.../.claude/plans/...` and experiment-journal pointer are private/dev-process breadcrumbs, not reader guidance. | Remove the plan path. If needed, keep one stable line: `Evidence: docs/evidence/` or link to public docs only. |
| `AGENTS.md:8-10` | Archaeology — CUT/SHORTEN: `WRITTEN (by the main agent, ported from verified j-steer-dev code -- do not rewrite...)` exposes agent/provenance history. | Replace with: `Core math is parity-tested; avoid changing it without rerunning parity checks.` |
| `AGENTS.md:26-29` | Archaeology — CUT: `U1 parity gate`, `U4 port check`, `run-524 reference vector` are internal run IDs. | Replace with one durable note: `Parity evidence lives under docs/evidence/.` |
| `AGENTS.md:34-40` | Archaeology — CUT: `U4 loop-close`, resumable artifact path, scratch scripts, TODO eval notebook are active worklog state. | Move to issue tracker or scratch notes; keep AGENTS to stable repo conventions only. |
| `AGENTS.md:46` | Archaeology — CUT: `Comments marked as Claude-authored where opinionated.` This preserves exactly the diary comments the library should lose. | Delete; comments should explain code, not authorship. |
| `jsteer/jacobian.py:3`, `jsteer/vjp.py:3`, `jsteer/applies.py:3` | Archaeology — CUT: `(drafted by Claude, ported from the verified j-steer-dev experiment code)`. | Delete from all module docstrings. |
| `jsteer/jacobian.py:5-6` | Archaeology — SHORTEN: `verified in j-steer-dev... Qwen3-4B, n=3 seeds` puts experiment diary in the core module header. | Move evidence detail to README/docs; module should say only that `word_vector` is the default verified path. |
| `jsteer/jacobian.py:20-22` | Archaeology — SHORTEN: `FAILED specificity controls in j-steer-dev...` is useful status but too journal-like in the module overview. | Replace with: `Persona variants are experimental and not recommended for targeted steering.` |
| `jsteer/vjp.py:12-13` | Archaeology — CUT: `this is the code path that produced the verified j-steer-dev result` is provenance, not API explanation. | Delete; keep only estimator conventions if needed. |
| `jsteer/vjp.py:87-90` | Archaeology + jargon — SHORTEN: `verified j-steer-dev method-0 extraction` and `linearization substrate` read like experiment notes. | Use: `Direct word-vector extraction over prompts; matches Jacobian.fit(...).word_vector(...) when settings match.` |
| `jsteer/jacobian.py:84-88` | Archaeology — CUT/SHORTEN: `_to_vector` docstring ends with `(Claude: found by U4 step-2 crash, pueue 550)`. | Keep the reason, drop diary: `Always CPU fp32 so cached and VJP paths return device-consistent Vectors.` |
| `jsteer/jacobian.py:202-203` | Archaeology — SHORTEN: `Claude: ... (external review)` is attribution/provenance. | Keep only: `Float bands are only resolved during fitting; steering requires explicit layer ints.` |
| `jsteer/jacobian.py:246-250` | Archaeology — SHORTEN: `# read your data:` plus `# Claude: asymmetry is intentional...` is chatty and attributed. | Keep concise rationale: `# Token selection uses unembed/final norm; cotangent uses raw W_U rows to match word_vector.` |
| `jsteer/vjp.py:41-42` | Archaeology — KEEP rationale, CUT attribution: `# Claude: the & with attention_mask...`. | Change to: `# Redundant for right-padded batches, but guards other padding layouts.` |
| `README.md:16-18` | Archaeology — SHORTEN: `parity-tested in artifacts/parity_u1.txt` brings internal artifact naming into the first explanation. | Say: `The cached pullback matches the direct VJP up to fp16 rounding.` Move artifact links to evidence docs. |
| `README.md:96-104` | Cleanliness — CUT: Credits include a long “Earlier work” reading list and speculative aside `We could generalize SAEs...`; also typo-like `Antropics works`. | Keep credits to the two deps plus repeng inspiration. Move papers elsewhere if needed. |
| `README.md:3,16-18` | Jargon — `pulling concept directions back` and `VJP` appear before defining that they are the same operation. | First use should read: `pullback — a vector-Jacobian product (VJP), J_l^T @ w — ...`. Then use one term consistently. |
| `jsteer/jacobian.py:20-26` | Jargon — `pullbacks`, `pulled back`, and `VJP` are all used without saying pullback = vector-Jacobian product. | Add one early definition after the formula: `Here pullback means the VJP J_l^T @ w.` |
| `jsteer/vjp.py:1` | Jargon — `Direct VJP pullback` stacks two undefined terms in the first sentence. | Use: `Direct vector-Jacobian product (VJP) pullback for one concept.` |
| `jsteer/jacobian.py:10,25`, `README.md:13` | Jargon — `position-averaged` / `pooled Jacobian` are coined terms unless the averaging axes are stated. | Define first use as: `averaged over fitting prompts and valid token positions`; avoid later switching to `pooled`. |
| `jsteer/vjp.py:88` | Jargon — `linearization substrate` is not sourced from jlens/repeng and is undefined. | Replace with plain language: `over the fitting prompts` or `over the prompts used to estimate the Jacobian`. |
| `jsteer/applies.py:112-115` | Jargon + over-explanation — `A "virtual token" injection...` is undefined and then explained by edge-case internals. | Rename plainly: `Replace the last k residual directions with v at the original activation norm; no sequence length changes.` |
| `jsteer/jacobian.py:1-39` | Docstring too long — module docstring repeats README, evidence, variants, cache rationale, layout, and usage; the core sentence is buried. | Cut to ~6 lines: purpose, formula, `fit`/`word_vector` usage. Move evidence/status to README. |
| `jsteer/vjp.py:1-18` | Docstring too long — repeats cached-path parity and estimator details before the reader sees the function. | Keep a short module docstring; put only necessary estimator notes on `pullback_vjp`. |
| `jsteer/applies.py:1-33` | Docstring too long — explains config, extraction, delivery, protocol, position semantics, and sign conventions all up front. | Replace with: `Register jsteer Vector methods with steering-lite and implement apply modes.` Move sign conventions to README/API docs if needed. |
| `jsteer/jacobian.py:94-98` | Docstring too long/chatty — `_word_cotangent` includes `Pulling THIS back... pure concept->residual map... persona-bundle confound`. | Shorten to: `Mean lm_head row for the first sub-token of each word; +C raises those logits.` |
| `jsteer/jacobian.py:146-150` | Docstring too long — `fit` buries the action under cost model and checkpoint details. | First sentence only: `Fit per-layer Jacobians on prompts using jlens.` Move cost/checkpoint detail to parameter docs or README. |
| `jsteer/jacobian.py:232-236` | Docstring too long — `persona_topk_vector` explains the whole experimental rationale inline. | Shorten to one sentence plus status: `Experimental: contrast top-k unembedded tokens from positive/negative persona means, then pull back like word_vector.` |
| `jsteer/jacobian.py:256-257` | Docstring/editorial — `Any honest demo/eval should show...` is moralizing. | Use neutral text: `Norm-matched random control vector for baseline comparisons.` |
| `jsteer/jacobian.py:264,268-269` | Docstring/comment style — `bonus` and `What the model 'thinks'` are demo prose, not clean API wording. | Rename comment to `# -- lens readout --`; docstring: `Decode the lens readout for a layer and position.` |
| `jsteer/applies.py:94-115` | Docstrings too explanatory for tiny apply functions; they repeat implementation details visible in the code. | Keep one-line behavior summaries for `apply_add`, `apply_add_last`, `apply_replace_last`; move caveats to README if users need them. |