CHANGELOG, briefs: 2.2.0 #82 done

briefs/2.2.0-remaining-issues.md: status item #1 flipped to done
with summary of what landed; detailed #82 section rewritten as a
DONE summary mirroring the #35 entry; "Recommendation for next
slot" updated to point at #80 (with the design-pass caveat) since
#83 is explicitly do-last. Added a new "Fleet-wide follow-ups"
section noting the deferred coverage.run.omit and dev-deps-via-pdm
sweeps so the next session can pick them up.

CHANGELOG.md: added Internal entries for the doc additions and the
revived test. The continuations behaviour itself is unchanged; what
changed is the documentation and the test coverage of an existing
property.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Technologicat

CHANGELOG.md

@@ -25,6 +25,8 @@
 
 - `unpythonic.llist.cons`: dropped the internal `_immutable` sentinel; the read-only `car`/`cdr` are now installed via `object.__setattr__` in `__init__`, and `__setattr__` is a one-liner that always raises.
 - `unpythonic.env.env`: dropped the `_direct_write` whitelist that allowed internal slots (`_env`, `_finalized`) to bypass `__setattr__`. Internal initialisation and `finalize()` now use `object.__setattr__` directly. Client code attempting `e._env = ...` or `e._finalized = ...` is now rejected by the reserved-name check (was silently allowed via the whitelist).
+- `doc/macros.md`: new "Topology of continuations: how the wiring works" subsection (with inlined `callcc_topology.png` diagram explaining the `cc`/`pcc` machinery) and "Scoping of locals in continuations" subsection (the rule, the box workaround, the three load-bearing limits that ruled out auto-`nonlocal` propagation). Closes #82.
+- `unpythonic/syntax/tests/test_conts.py`: revived the `"scoping, in presence of nonlocal"` testset that was disabled in 2022 due to a coverage.py source-parsing limitation. The new `[tool.coverage.run]` config in `pyproject.toml` scopes coverage to production code (excluding `*/tests/*`) and sidesteps the parse failure at report time.
 
 
 ---

briefs/2.2.0-remaining-issues.md

@@ -1,11 +1,20 @@
 # 2.2.0 — Remaining open issues (session handoff)
 
-Updated 2026-05-06 after #35 landed. The original snapshot ordering is
-preserved below; status flags mark what's done.
+Updated 2026-05-06 after #35 + #82 landed. The original snapshot
+ordering is preserved below; status flags mark what's done.
 
 ## Status
 
-1. **#82** — pending; docs-only.
+1. ~~**#82**~~ — **done** this session. New `doc/macros.md` subsections
+   "Topology of continuations: how the wiring works" (with inlined
+   `callcc_topology.png` diagram explaining the `cc`/`pcc` machinery)
+   and "Scoping of locals in continuations" (the rule, the workaround,
+   three load-bearing limits that ruled out auto-`nonlocal`
+   propagation). Revived the `"scoping, in presence of nonlocal"`
+   testset (disabled in 2022); the original coverage.py source-parsing
+   issue is now sidestepped via a new `[tool.coverage.run]` config
+   that scopes coverage to production code and excludes `*/tests/*`.
+   Issue closed.
 2. ~~**#76**~~ — **done** (commit `b6423e7`, plus `ad6c3f6` for the
    `tryf`/`withf` `_accepts_arity` unification). Issue closed.
 3. ~~**#85 step 1**~~ — **done** (commit `7034add`). `expect[]` shipped,
@@ -14,16 +23,33 @@ preserved below; status flags mark what's done.
 4. ~~**#35**~~ — **done** this session. `cons.__delattr__` interception
    (bug fix), `cons` simplified via `object.__setattr__` (drops the
    `_immutable` sentinel), error-message wording corrected. Bonus
-   `assignonce` `del`-rebind bypass fix and `env._direct_write` cleanup
-   (resolves the TODO at env.py:77). New issue **#102** opened against
-   3.0.0 for the `TypeError` → `dataclasses.FrozenInstanceError` swap
-   that was held back for API stability.
+   `assignonce` `del`-rebind bypass fix and `env._direct_write` cleanup.
+   New issue **#102** opened against 3.0.0 for the `TypeError` →
+   `dataclasses.FrozenInstanceError` swap that was held back for API
+   stability; subsequently superseded in scope by the
+   `FrozenAttributeError` shim (`TypeError` + `FrozenInstanceError`)
+   which lets us align with the stdlib idiom now without breaking 2.x
+   callers — #102 retained as the 3.0.0 "drop the `TypeError` base"
+   tracker.
 5. **#80** — pending; multi-shot generators, design pass before code.
 6. **#83** — pending; `end_lineno` / `end_col_offset` sweep, last.
 
-Recommendation for next slot: **#82** is the most parked of the
-remaining items, and the resume notes for it are detailed enough
-to pick up cold.
+Recommendation for next slot: **#80** is the more substantive of the
+two remaining items but wants an API-design discussion first (see its
+detailed entry below). **#83** is explicitly *do last* — cross-cutting,
+and easy to merge-conflict with anything else in flight.
+
+## Fleet-wide follow-ups (deferred to a future session)
+
+- **`[tool.coverage.run].omit` pattern** for other PDM projects. The
+  pattern is documented in `~/.claude/CI-SETUP-NOTES.md` §4a; sweep
+  applies to `pylu`, `pydgq`, `wlsqm`, `mcpyrate`, `raven`, `pyan3`
+  as relevant.
+- **Declare `coverage` (and `pytest-cov` where used) in
+  `[dependency-groups].dev`** rather than ad-hoc `pip install` in CI
+  workflows. Baseline updated in
+  `~/.claude/PROJECT-SETUP-NOTES.md`; project-by-project propagation
+  pending.
 
 ## Open before release
 
@@ -40,50 +66,14 @@ to pick up cold.
 
 ## #82 — Document scoping of locals in continuations
 
-**Decision: docs only, do not fix.** Per the ticket comments
-(Technologicat, 2022), implementation was tried (commit `2c7477c`,
-propagating parent-scope declarations into the continuation) but ran
-into three load-bearing limits:
-
-- Continuation parameters (assignment targets of `call_cc`) must shadow
-  same-named names from the parent scope.
-- No propagation upward — a name declared inside a continuation can't
-  become available to the parent context, even though source-wise
-  they're the same function. Would need a second pass.
-- At the top of a `with continuations` block, you can't tell from the
-  AST whether the block is inside a function (so `nonlocal` vs `global`
-  for parent locals is undecidable without whole-module analysis).
-
-Therefore: continuations introduce a scope boundary. Document this
-analogously to how Python's comprehensions and generator expressions do.
-
-**Resume notes (added 2026-05-05)**:
-
-- The original experiment lives at commit `2c7477c` — recover via git
-  archaeology (`git show 2c7477c`, `git diff 2c7477c~1 2c7477c` for the
-  shape of the change). The half-finished propagation logic and any
-  failing-test commits around it are the clearest source of the *why*.
-- There's an SVG/PDF illustration in the repo somewhere (predates this
-  session) that maps the scoping situation; needs locating and
-  deciphering to fold into the docs. Worth a `find . -name '*.svg'`
-  / `*.pdf` and a look at anything in `doc/` that isn't already
-  cross-referenced from `macros.md`.
-- Continuations are one of the most complex features in unpythonic.
-  Plan: either a dedicated subsection in `doc/macros.md` near the
-  existing continuations material, or a standalone `doc/continuations.md`
-  linked from there.
-- The compiled-out experimental code in `unpythonic/syntax/tailtools.py`
-  (mentioned in the original ticket) is half of the *why* — the other
-  half is the ticket comment thread. Both need to make it into the doc
-  in present-tense form.
-
-Touchpoints (when ready):
-- **Where to write**: `doc/macros.md` continuations section, or new
-  `doc/continuations.md`.
-- **Updated examples**: `unpythonic/syntax/tests/test_conts.py`, near
-  end of file (per ticket as of `f772df4`).
-
-Save for its own session — the writing is more careful than the code.
+**DONE this session.**
+
+- `doc/macros.md`: new `#### Topology of continuations: how the wiring works` subsection with inlined `callcc_topology.png` diagram, walking through the five panels (Base case, Sequence, Nested, Confetti chaining rule, Tail-call composition) and explaining what `cc` and `pcc` are, who sets them, and how the chain unwinds when a function ends or tail-calls another. Followed by `#### Scoping of locals in continuations` covering the rule (each `call_cc[]` introduces a scope boundary), the box workaround, and the three load-bearing limits that ruled out auto-`nonlocal` propagation. TOC updated.
+- `doc/callcc_topology.svg` re-exported with a white background (xviewer's checkerboard fallback made the transparent original unreadable); PNG export added.
+- `unpythonic/syntax/tests/test_conts.py`: revived the `"scoping, in presence of nonlocal"` testset (disabled in 2022 due to a coverage.py source-parsing issue). The test demonstrates that `nonlocal x` inside a continuation reaches back to the parent's `x`, just as in any ordinary nested closure. Ruff F811 silenced at the use site (post-macro the `nonlocal` is at the top of a separate function, so it isn't actually a redefinition).
+- `pyproject.toml`: new `[tool.coverage.run]` section scopes coverage to production code (`source = ["unpythonic"]`) and excludes `*/tests/*`. Sidesteps the coverage.py parse failure on the revived test at `coverage xml` time, and aligns with general "coverage signal is about production code, not tests" hygiene. Pattern documented in `~/.claude/CI-SETUP-NOTES.md` §4a for fleet propagation.
+- Bonus: `shift`/`reset` attribution corrected in the delimited-continuation parenthetical (Danvy & Filinski 1990, not Felleisen — Felleisen's operators are `control`/`prompt`) with links to Wikipedia and the Racket reference.
+- Issue closed.
 
 ## #76 — Add expression form of `with` (`withf`)