jsteer/docs/reviews/code.md

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.