Merge pull request #255 from PyAutoLabs/claude/latex-raw-string-docstrings-9h4ine

prompt: latex-raw-string-docstrings — unblock, implement across 6 repos, record

Author: Jammy2211

active.md

@@ -1,5 +1,50 @@
 # Active Tasks
 
+## latex-raw-string-docstrings
+- issue: https://github.com/PyAutoLabs/autolens_workspace/issues/491
+- status: workspace-dev — 5 of 6 PRs MERGED; HowToLens#73 held RED (not this PR's failure)
+- issue-umbrella: autolens_workspace#491 (one issue, six PRs)
+- merged: HowToFit#47, HowToGalaxy#70, autofit_workspace#145, autogalaxy_workspace#218,
+  autolens_workspace#492 — all green, incl. the CI 'Catalogue staleness' check, which
+  independently re-confirms the regeneration gate.
+- BLOCKED: HowToLens#73 red on smoke (3.12 + 3.13). Two scripts fail with numba
+  'Pass nopython_type_inference': chapter_3_pixelizations/tutorial_8_adaptive_pixelization.py
+  and tutorial_11_brightness_adaption.py. NEITHER is in the diff, and all 8 files that ARE
+  in it pass. Reproduced identically on one re-run. A docstring r-prefix cannot cause a numba
+  typing error. Prime suspect: PyAutoArray#453 (in-place Cholesky buffer + new numba kernels
+  for fnnls_cholesky) merged 2026-08-20 22:09:30 UTC, minutes before this run; CI installs
+  autoarray from source at HEAD, and the last green HowToLens main run (04:29 UTC) predates
+  it. NOT yet proven: two specific mechanisms were tested and BOTH passed under the exact CI
+  versions (numba 0.67.0 + scipy 1.17.1) — a strided Ubuf view into _cholupdate, and the new
+  np.dot inside _cho_solve_buffer. So the suspicion rests on timing + code area, not a
+  reproduced mechanism. Control experiment running: re-run of the last GREEN main build
+  (same commit, fresh dependency install) — if it now fails the same way, the break is on
+  main/library drift and this PR is clean.
+- prompt: active/latex_raw_string_docstrings.md
+- repos (all on branch claude/latex-raw-string-docstrings-9h4ine):
+  - HowToFit: 4 files, 13 literals, 7 corruptions repaired
+  - HowToGalaxy: 4 files, 20 literals, 13 repaired
+  - HowToLens: 8 files, 32 literals, 21 repaired
+  - autofit_workspace: 2 files, 2 literals, 1 repaired
+  - autogalaxy_workspace: 6 files, 30 literals, 28 repaired
+  - autolens_workspace: 17 files, 83 literals, 61 repaired
+- totals: 41 files, 180 literals, 131 corruptions repaired — 41 matches the survey exactly.
+- verification (per repo, in order): baseline regeneration is a NO-OP; both sweeps zero;
+  runtime value check (every changed literal's value compared HEAD vs worktree — the prefix
+  may only REMOVE corruption) = 131 repaired / 0 unexpected; diff-empty gate passes
+  byte-exactly on notebooks/ markdown/ llms-full.txt workspace_index.json. autolens_workspace
+  additionally: all 57 __Env__ declarations re-read IDENTICALLY, and 4 of the raw-stringed
+  files carry __Env__, so the PyAutoHands#251 fix is exercised end to end.
+- gate refinement: HowToFit's 4 `plt.ylabel` labels are runtime strings in CODE cells, which
+  copy source verbatim, so the `r` legitimately shows there. The gate holds exactly as written
+  for every docstring; that one code-cell delta is by design.
+- residue: autolens_workspace scripts/group/likelihood_function.py keeps 2 warned + 1 silent.
+  Three docstrings use the DOUBLE-backslash convention ($\\theta$, \\frac, \\vec) mixed with
+  single-backslash macros; adding `r` would double the correct ones. Needs a convention
+  decision + un-doubling 18 backslashes = a prose edit this task excludes. Follow-up.
+- follow-up to file: -W error::SyntaxWarning compile guard in workspace CI (catches only the
+  warned class; the silent class needs the AST sweep).
+
 ## numba-cpu-likelihood-profiling
 - issue: https://github.com/PyAutoLabs/autolens_profiling/issues/151
 - pr: https://github.com/PyAutoLabs/autolens_profiling/pull/152

…orkspaces/latex_raw_string_docstrings.md active/latex_raw_string_docstrings.mddraft/maintenance/workspaces/latex_raw_string_docstrings.md renamed to active/latex_raw_string_docstrings.md draft/maintenance/workspaces/latex_raw_string_docstrings.md renamed to active/latex_raw_string_docstrings.md

@@ -33,7 +33,12 @@ corner of the problem, and found a hard dependency the prompt did not know
 about. Both sweeps are ~20 lines each and specified below — rebuild them rather
 than trusting these counts blind.
 
-### BLOCKED BY: `draft/bug/hands/raw_string_docstring_prefix.md`
+### ~~BLOCKED BY~~ — CLEARED 2026-08-20
+
+The PyAutoHands prerequisite **merged**: issue #250 / PR #251 (merge `c887290`), all 3
+CI matrix jobs green. Both parsers accept `r`/`R` prefixes now, verified on `main`. This
+task is ready to start. History of the block, kept because it explains the gate below:
+
 
 Two PyAutoHands docstring parsers **silently** mis-handle an `r"""` opener, so
 raw-stringing these scripts today would break the generated artefacts rather
@@ -47,7 +52,22 @@ than fix them. Both reproduced, neither raises:
   `.../potential_correction/`), so their smoke env profile would be silently
   rerouted.
 
-Do not start this task until that Hands fix has merged.
+~~Do not start this task until that Hands fix has merged.~~ It has.
+
+**Re-verified 2026-08-20 (resumed `/start_dev`): still blocked, still unfixed.**
+Against PyAutoHands `main` @ `cdea28c`, on a probe pair differing only by an `r`
+on the first narrative docstring:
+
+- `_narrative_docstring_ranges` → plain `[(0, 2), (6, 10)]` vs raw `[(6, 10)]`
+  — the raw block is dropped, silently, no exception.
+- `read_env_declaration` → plain `['jax']` vs raw `None` — silently, no exception.
+
+`add_notebook_quotes.py:67` still reads `lines[start].startswith('"""')` and
+`env_config.py:110` still reads `^(?:"""|''')\s*$`; neither accepts an `r`/`R`
+prefix. No `feature/hands-raw-string-docstring-prefix` branch exists on the
+remote yet, and its own blocker (`feature/hands-hygiene-leftovers`) is still
+open. Re-run this two-probe check at the next `/start_dev` rather than trusting
+this note.
 
 ### Two sweeps are needed, not one
 
@@ -63,6 +83,17 @@ diagnostic at all — `\t` in `\theta`, `\f` in `\frac`, `\r` in `\rm`, `\b` in
   segment contains a backslash, flag any control character (`ord < 32`, `\n`
   excepted) in the *value* — **132 hits**.
 
+**The warning sweep is interpreter-dependent — check this before trusting a
+zero.** Invalid escape sequences are a `SyntaxWarning` only on **Python 3.12+**;
+on 3.11 and earlier they are a `DeprecationWarning`. A sweep that collects
+`SyntaxWarning` on a 3.11 interpreter reports **0 hits** and is
+indistinguishable from "already fixed" — verified 2026-08-20 on 3.11.15, where
+`compile()` on a docstring containing `$\odot$` yields 0 `SyntaxWarning` and 1
+`DeprecationWarning`. Collect **both** categories, or assert the interpreter is
+3.12+ before believing the count. (`-m compileall` needs `-f` too, or
+`__pycache__` suppresses recompilation and the counts silently drop.) This
+already cost one mis-grade on the 2026-08-09 sweep.
+
 `HowToLens/scripts/chapter_4_scaling_up_lensing/tutorial_5_cluster_scale.py`
 has **only** silent hits and zero warnings, so a warning-only sweep skips it
 entirely. Drive the edit off the union of both.
@@ -142,9 +173,18 @@ The four matplotlib labels in
 - `autocti_workspace`, every `*_workspace_test` / `*_workspace_developer`, and
   `PyAutoFit` / `PyAutoArray` / `PyAutoLens` source: swept, **zero** hits.
 
+## Constraints
+
+- Docstring content is user-facing tutorial prose. Add the `r` prefix and change
+  **nothing else** — do not reword the LaTeX or the surrounding sentences.
+  Prose changes belong to a docs task, not this one.
+- Notebooks are regenerated, never hand-edited.
+
 ## Verification per repo (the diff-empty gate)
 
-1. Both sweeps return zero.
+1. Both sweeps return zero — on a **3.12+** interpreter, or collecting
+   `DeprecationWarning` as well (see the interpreter trap above). A zero from a
+   3.11 `SyntaxWarning`-only sweep is vacuous and does not clear this gate.
 2. Regenerate:
    `PYTHONPATH=../PyAutoHands/autohands python3 ../PyAutoHands/autohands/generate.py <project>`
    (`howtofit`, `howtogalaxy`, `howtolens`, `autofit`, `autogalaxy`, `autolens`).
@@ -158,6 +198,17 @@ The four matplotlib labels in
 Ship as six independent PRs, one per repo. Prose-only, no API surface, so no
 cross-repo merge ordering.
 
+## Supersedes
+
+`draft/maintenance/autolens_workspace/latex_docstrings_invalid_escape_warnings.md`
+(filed 2026-08-09, split from #457) is the same defect measured on
+`autolens_workspace` alone — its 80 warnings across 17 files are exactly the 17
+files listed above, top-six counts matching. This prompt subsumes it across all
+six repos and adds the silent-escape class. Its unique content (the interpreter
+trap, now folded in above; the "do not reword the LaTeX or the prose while
+fixing the escapes" constraint) is carried here. One task, one prompt — pick up
+this file, not that one.
+
 ## Follow-up worth filing
 
 A `-W error::SyntaxWarning` compile guard in workspace CI, so this cannot

…bug/hands/raw_string_docstring_prefix.md …/08/hands-raw-string-docstring-prefix.mddraft/bug/hands/raw_string_docstring_prefix.md renamed to complete/2026/08/hands-raw-string-docstring-prefix.md draft/bug/hands/raw_string_docstring_prefix.md renamed to complete/2026/08/hands-raw-string-docstring-prefix.md

@@ -1,3 +1,50 @@
+- issue: https://github.com/PyAutoLabs/PyAutoHands/issues/250 (closed on merge)
+- shipped: 2026-08-20 — PyAutoHands PR https://github.com/PyAutoLabs/PyAutoHands/pull/251
+  (merge `c887290`, commit `27c828c`); all 3 CI matrix jobs green (pytest 3.12/3.13/3.14).
+- classification: bug (PyAutoHands) — silent parser defect, two sites.
+- summary: two independent docstring parsers silently mis-handled an `r"""` opener, and
+  neither raised. `add_notebook_quotes._narrative_docstring_ranges` tested
+  `lines[start].startswith('"""')`; a raw block is a perfectly good column-0
+  `ast.Expr(Constant(str))`, so it reached that test and failed it — the block was dropped
+  as a cell boundary and the tutorial prose would have shipped as a Python CODE cell
+  containing a bare string literal. `env_config._DOCSTRING_DELIM_RE` matched a bare
+  delimiter only, so an `r"""` opener was walked past and the block's CLOSER matched as an
+  opener instead — docstring parity inverted for the rest of the file and an `__Env__`
+  section further down was read as if outside a docstring, so `read_env_declaration`
+  returned `None` and the script's smoke env profile was silently rerouted. Both sites now
+  accept an optional `r`/`R` prefix on either delimiter
+  (`_TRIPLE_DELIM_OPENER_RE`, `_DOCSTRING_DELIM_RE`). Unblocks latex-raw-string-docstrings
+  (41 workspace files across 6 repos).
+- validation: 6 new regression tests, EACH verified to fail with the source change reverted
+  and pass with it. Full suite 14F/337P on branch vs 14F/331P on main — identical failure
+  sets, all 14 from `ipynb-py-convert` being unbuildable in the container (CI installs it,
+  and CI ran green on all three Python versions).
+- key traps:
+  - **The recorded blocker was not real.** The prompt said "blocked by hands-hygiene-leftovers
+    (worktree dirty)". That was LOCAL WORKTREE CONTENTION, not a code dependency:
+    `feature/hands-hygiene-leftovers` touches AGENTS.md, generate_release_notes.py,
+    bin/autohands and two unrelated tests — ZERO overlap with the two files here. Done in a
+    separate clone; the two merge in either order. Read a blocker before honouring it.
+  - **The parity case is the test that matters.** `read_env_declaration` breaks when the raw
+    docstring is NOT the one carrying the declaration — a single-block test passes while the
+    defect is live. Test an EARLIER raw docstring.
+  - **Do not run `black` on this repo.** It is not black-formatted: 44 files on main would
+    reformat. Match surrounding style instead.
+  - `ipynb-py-convert` will not build in a modern container, so the 14 notebook-level tests
+    cannot run locally. Assert on the CONVERTED SOURCE instead — the converter replaces the
+    opener line outright, so byte-identical conversion is the tighter claim and needs no
+    external tool.
+  - Checked and NOT affected, verified rather than assumed: `generate_markdown.script_title`
+    (its regex finds the `"""` after the `r` — same title either way) and `navigator.py`
+    (reads already-converted output). Boundary set confirmed not to have widened: column-0
+    raw single-quoted strings, assigned literals, raw bytes literals and f-strings all
+    remain non-boundaries.
+  - `pyauto-brain bug` mis-read this task: "owner unresolved", sized *large*,
+    "split into phases", for a two-line fix in a repo the prompt names in its header.
+    Worth a look at the Bug Agent's owner map for `hands`.
+
+## Original prompt
+
 # Teach the notebook/env parsers to accept raw-string (`r"""`) docstrings
 
 Type: bug

complete/index.md

@@ -6,7 +6,7 @@ Token-light navigation over the finished-work records (schema:
 only then grep a dated bucket. Curators: edit the band between the CURATED
 markers; everything below GENERATED is rebuilt.
 
-1060 records across 7 buckets.
+1061 records across 7 buckets.
 
 <!-- CURATED:START -->
 ## Highlights
@@ -69,6 +69,7 @@ _(curate hard-won records here — survives regeneration.)_
 - [folder-list-ref-drift-sweep](2026/08/folder-list-ref-drift-sweep.md) — Fixed the 12 real defects from the 2026-08-19 hygiene refs scan — 2 autoCTI_workspace/output casing refs, 2 ho…
 - [frozen-lane-counter](2026/08/frozen-lane-counter.md) — Added a third disjoint lane counter to the multi-start gradient search
 - [group-data-preparation-readme](2026/08/group-data-preparation-readme.md)
+- [hands-raw-string-docstring-prefix](2026/08/hands-raw-string-docstring-prefix.md) — closed on merge
 - [hazard-profiling-likelihood-tier](2026/08/hazard-profiling-likelihood-tier.md) — Tier-2 likelihood profiling landed with five persistent findings and corrected NNLS continuity semantics.
 - [health-conductor-stale-verdict](2026/08/health-conductor-stale-verdict.md)
 - [heart-green-validation-ingest](2026/08/heart-green-validation-ingest.md)