code-towel 1.414__tar.gz → 1.618__tar.gz

{code_towel-1.414 → code_towel-1.618}/CHANGELOG.md

@@ -7,6 +7,32 @@ ecosystem evidence behind each claim. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [1.618] — 2026-09-16
+
+### Changed
+- Cross-file helpers are imported relatively by default (`from .module import
+  helper`), which stays valid when an out-of-place output is adopted into its
+  real location. An absolute import is used only when a packaging marker
+  (`pyproject.toml`/`setup.*`) anchors the module name, so the previous
+  behavior is preserved for in-place refactoring of a packaged project.
+- Trivial forwarding helpers are no longer proposed: a block whose helper body
+  would be a single `raise`, a `return` of one call, or a bare call adds
+  indirection without sharing logic. Construct the engine with
+  `skip_trivial_helpers=False` to restore the old behavior.
+- A cross-file helper is placed in a module that does not close an import cycle.
+  When the shared block spans modules, the helper is hosted in one the others
+  already import rather than adding a back-edge; the extraction is declined only
+  when no placement is safe (a genuine pre-existing cycle). This replaces the
+  earlier behavior of hosting the helper in the first module and declining
+  whenever that would cycle.
+
+### Fixed
+- The rename tool no longer refuses a module merely because it contains a local
+  variable or parameter named `vars`, `globals`, `locals`, `eval`, or `exec`;
+  it flags only a genuine reference to the builtin.
+
 ## [1.414] — 2026-09-15
 
 First release prepared under the open-source audit. Beta: the engineering and

{code_towel-1.414 → code_towel-1.618}/CONTRIBUTING.md

@@ -172,4 +172,4 @@ Thank you for contributing to Towel!
 
 For reproducible tool versions, use `uv sync --frozen --extra dev` and the commands in README.md. CI runs the full tests and an unconditional 85% coverage gate for each supported Python version. `just release VERSION` prepares local distributions only; publication requires maintainer review of the current audit and policy decisions.
 
-Release maintainers should follow [docs/RELEASING.md](docs/RELEASING.md). Legacy AST normalization helpers are compatibility utilities, not safe preprocessing passes; do not use them to justify behavior-preservation claims.
+Release maintainers should follow [docs/RELEASING.md](docs/RELEASING.md).

{code_towel-1.414/src/code_towel.egg-info → code_towel-1.618}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-towel
-Version: 1.414
+Version: 1.618
 Summary: A Python tool that DRYs your code - finds and refactors repeated code using unification-based analysis
 Author: Eric Allen
 License-Expression: Apache-2.0
@@ -36,19 +36,85 @@ Dynamic: license-file
 
 Towel finds repeated Python code using unification and proposes helper-function extractions.
 
+> **Install from PyPI as [`code-towel`](https://pypi.org/project/code-towel/)** (the command is `towel`):
+> `pip install code-towel`
+> Do **not** install `towel`: `pip install towel` and `uvx towel` fetch a different, unrelated project.
+
 **Release status: 1.414 (beta).** Every accepted proposal is verified by instantiating the helper with each call's arguments and comparing the result with the block it replaces; arguments that could have observable effects or fresh identity are evaluated inside the helper at their original position. A standing ecosystem check refactors 91 public projects and runs each one's own test suite before and after: 75 pass identically, 13 produce no proposal, and 3 differ only in documented frame-sensitive or source-observing ways (see below). Refactoring is still a change to your code: preview first, review the diff, and run your tests. [Known limitations](docs/KNOWN_LIMITATIONS.md) lists what is verified, what is rejected, and what remains outside the model; [the readiness report](docs/PRODUCTION_READINESS.md) records the evidence.
 
+**New here?** The [Quick start](docs/QUICKSTART.md) gets you from install to a reviewed refactoring in four steps.
+
+## What it does
+
+Towel finds code that is repeated across your functions and pulls each group of
+duplicates into one shared helper, rewriting the copies as calls to it. It works
+by *anti-unification*: it computes the least-general generalization of the
+matching blocks, so the parts that are the same become the helper's body and the
+parts that differ become its parameters.
+
+Given two functions that share a block:
+
+```python
+def order_summary(order):
+    items = [i for i in order.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return f"Order {order.id}: ${total}"
+
+def quote_summary(quote):
+    items = [i for i in quote.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return f"Quote {quote.id}: ${total}"
+```
+
+Towel proposes the shared block as a helper (emitted with a placeholder name you
+rename afterward) and rewrites both functions to call it:
+
+```python
+def __extracted_func_0(record):
+    items = [i for i in record.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return total
+
+def order_summary(order):
+    total = __extracted_func_0(order)
+    return f"Order {order.id}: ${total}"
+
+def quote_summary(quote):
+    total = __extracted_func_0(quote)
+    return f"Quote {quote.id}: ${total}"
+```
+
+What makes Towel different from a search-and-replace is that it is conservative
+and verified. It proposes an extraction only when it can prove the result runs
+the same as the original — instantiating the helper with each call's arguments
+and comparing against the block it replaced — and it refuses cases it cannot
+establish rather than guess. It skips trivial extractions that would add
+indirection without sharing real logic, wraps arguments that must not be
+evaluated eagerly in zero-argument `lambda`s (see
+[below](#why-some-arguments-are-wrapped-in-lambda)), and leaves naming to you.
+Nothing is written without your say-so: the workflow is preview, refactor into a
+copy, review the diff, and run your tests.
+
 ## Install
 
-The runtime uses only the standard library; optional `tqdm` provides progress bars. Platform, CPU, memory, and disk requirements are in [Requirements](#requirements) below.
+The PyPI package is **`code-towel`**; installing it gives you the **`towel`** command.
 
 ```bash
-python -m pip install .
+pip install code-towel
 towel --version
 towel --help
 ```
 
-The commands below describe this checkout; previously published distributions may differ.
+Install `code-towel`, not `towel`: the name `towel` on PyPI is a different, unrelated project, so `pip install towel` and `uvx towel` will not install this tool. To run it with `uvx` without installing, name the package explicitly:
+
+```bash
+uvx --from code-towel towel --help
+```
+
+The runtime uses only the standard library; optional `tqdm` provides progress bars. Platform, CPU, memory, and disk requirements are in [Requirements](#requirements) below.
 
 ## Requirements
 
@@ -79,7 +145,8 @@ The two largest projects in the ecosystem check, networkx and Sphinx, are the sl
 ## Use
 
 ```bash
-# Read-only analysis
+# Read-only analysis: lists each opportunity with the extracted helper and,
+# per call site, the original block (-) next to the generated call (+)
 towel preview path/to/project
 
 # Write to a new output directory
@@ -98,7 +165,7 @@ To roll back an interrupted batch, use `towel recover /path/to/.towel-transactio
 
 For detailed conservative rejection reasons, set `DEBUG_PROPOSAL_REJECTIONS=1` when running preview.
 
-`towel-dry` and `towel-preview` are compatibility entry points. `python scripts/dry` delegates to the same installed CLI. Run `towel dry --help` for import-layout, iteration, and progress options.
+Run `towel dry --help` for import-layout, iteration, and progress options.
 
 ## What is analyzed
 
@@ -106,10 +173,51 @@ The pipeline parses modules, analyzes scopes, collects functions and classes, co
 
 Differing sub-expressions become helper parameters. Names, literals, and tuples of those are passed eagerly; any other expression is passed as a zero-argument thunk and evaluated inside the helper where the original expression stood, so evaluation order, count, and conditionality are preserved. Expressions that read names bound inside the block are lambda-lifted with those names as arguments. A thunk the helper would evaluate first, once, and unconditionally is passed eagerly instead, since nothing can observe the difference. Before a proposal is offered, the helper is instantiated with each call's arguments and must reproduce the original block up to renamed binders.
 
-The refactoring pipeline preserves the original Python operators. The legacy `ast_normalizer` utilities remain available with deprecation warnings for compatibility, but can change Python behavior and are not used by this pipeline. Generator/suspension operations and frame-sensitive calls such as `locals()` are conservatively rejected. Nested blocks that bind names used outside the block are rejected until full control-flow liveness is supported. Static local import cycles and cross-module global declarations are rejected. This reduces the number of proposals rather than claiming an unsupported transformation is safe.
+The refactoring pipeline preserves the original Python operators. Generator/suspension operations and frame-sensitive calls such as `locals()` are conservatively rejected. Nested blocks that bind names used outside the block are rejected until full control-flow liveness is supported. Static local import cycles and cross-module global declarations are rejected. This reduces the number of proposals rather than claiming an unsupported transformation is safe.
 
 Dynamic imports, reflection, arbitrary callbacks, runtime rebinding, metaclasses, and external side effects limit what can be established statically. Each engine owns a bounded analysis session with content checks and isolated AST snapshots. The test import-isolation harness and an individual engine instance require sequential use. Candidates involving detected namespace rebinding, frame inspection, or comprehension assignment expressions are rejected; opaque external reflection and rebinding remain outside the supported model.
 
+## Why some arguments are wrapped in `lambda`
+
+When the differing sub-expression between two duplicates is more than a plain value, Towel passes it as a zero-argument lambda (a *thunk*) and calls it inside the helper at the exact place the original expression stood. In the output that looks like this:
+
+```python
+notify(lambda: welcome_email(user))
+```
+
+To a casual reader the lambda looks redundant. It is not. Passing the expression directly would evaluate it once, unconditionally, at the call site, and that changes behavior whenever the original evaluated it conditionally, more than once, or not at all. Consider two blocks that differ only in one call (illustrative):
+
+```python
+# before
+if user.active:
+    send(welcome_email(user))
+```
+
+Pass that call eagerly and it runs for every user, active or not:
+
+```python
+# WRONG: welcome_email(user) runs unconditionally, with its side effects, and
+# can raise, even when user.active is False
+def notify(message, user):
+    if user.active:
+        send(message)
+
+notify(welcome_email(user), user)
+```
+
+The thunk defers it to the spot the original code ran it, preserving the condition:
+
+```python
+# correct
+def notify(build_message, user):
+    if user.active:
+        send(build_message())
+
+notify(lambda: welcome_email(user), user)
+```
+
+The same reasoning covers an expression inside a loop (the thunk runs once per iteration, as the original did) or one that might raise. Towel keeps the wrapper only where it can matter: an expression the helper would evaluate first, once, and unconditionally is passed directly, because then nothing can observe the difference. So a `lambda:` in the output is a deliberate marker that Towel is preserving that argument's timing, count, or conditionality; its absence means eager evaluation was proven equivalent.
+
 ## Naming the helpers with an LLM
 
 Towel deliberately generates meaningless names, `__extracted_func_3` and `__param_0`, and leaves the naming to a separate, review-first step. Extraction is a verified mechanical transformation; choosing a good name is a judgment call, so the two are kept apart. The intended workflow hands the naming to a coding assistant, because the assistant reads far better names out of the call sites than any heuristic, and you review its choices before they touch the code.
@@ -131,6 +239,8 @@ towel rename-helpers path/to/cleaned --rename-file renames.json
 
 The JSON inventory gives the assistant what it needs to name well: every helper with its scope, source, and call sites, and for each parameter its evaluation kind (`value`, `thunk`, `lifted`, `receiver`) and the actual argument expressions passed at every call site. A parameter that always receives `user.email` and `account.email` should become `email`, and the argument expressions are how the assistant sees that.
 
+Each helper also carries a `changes` list: for every call site, the exact original block it replaced (`before`) next to the generated call (`after`). Seeing what the code did before extraction is what lets an assistant finish good names, write a docstring, and infer parameter and return types. This comes from a small `.towel-helpers.json` that `towel dry` writes next to its output; it is only for the naming step and is safe to delete afterward.
+
 Each inventory entry carries the exact mapping key to use as a rename target: `"path.py:helper"` renames a module-level helper together with its importers, `"helper"` renames a unique class-level helper together with every attribute reference, and `"path.py:helper.__param_0"` renames a parameter within the helper's scope. The rename is applied as one atomic batch with scope and importer checks; a name collision, a mangled name, or a dynamic reference aborts the whole batch and reports the reason, so a bad suggestion changes nothing. `--dry-run` reports the same JSON without writing.
 
 The shared `towel-rename` skill (in the agent-skills repository) walks an assistant through the whole loop: extract, review the diff, name, apply, and re-test. An interactive prompt mode is also available for naming by hand, and it calls no LLM service.
@@ -160,15 +270,21 @@ Behavioral tests compare sampled return values and types, exceptions, output, an
 
 ## Documentation
 
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Known limitations](docs/KNOWN_LIMITATIONS.md)
-- [Production readiness and ecosystem evidence](docs/PRODUCTION_READINESS.md)
-- [Adversarial review](docs/ADVERSARIAL_REVIEW.md)
-- [Historical issues](KNOWN_ISSUES.md)
+Start here:
+
+- [Quick start](docs/QUICKSTART.md) — install and refactor in four steps
+- [Known limitations](docs/KNOWN_LIMITATIONS.md) — what is verified, what is rejected, and what is outside the model
+- [Python API guide](docs/USAGE_GUIDE.md) — using `UnificationRefactorEngine` directly
+
+How it works and why to trust it:
+
+- [Architecture](docs/ARCHITECTURE.md) — the pipeline, the algorithms, and their references
+- [Production readiness](docs/PRODUCTION_READINESS.md) — the ecosystem evidence behind the claims
+- [Adversarial review](docs/ADVERSARIAL_REVIEW.md) — defects found and repaired
+
+Project:
 
-Historical notes and example outputs document earlier versions and may describe behavior superseded by the current audit. The current CLI help and source define the available interface.
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Releasing](docs/RELEASING.md)
 
 ## License
 

{code_towel-1.414 → code_towel-1.618}/README.md

@@ -2,19 +2,85 @@
 
 Towel finds repeated Python code using unification and proposes helper-function extractions.
 
+> **Install from PyPI as [`code-towel`](https://pypi.org/project/code-towel/)** (the command is `towel`):
+> `pip install code-towel`
+> Do **not** install `towel`: `pip install towel` and `uvx towel` fetch a different, unrelated project.
+
 **Release status: 1.414 (beta).** Every accepted proposal is verified by instantiating the helper with each call's arguments and comparing the result with the block it replaces; arguments that could have observable effects or fresh identity are evaluated inside the helper at their original position. A standing ecosystem check refactors 91 public projects and runs each one's own test suite before and after: 75 pass identically, 13 produce no proposal, and 3 differ only in documented frame-sensitive or source-observing ways (see below). Refactoring is still a change to your code: preview first, review the diff, and run your tests. [Known limitations](docs/KNOWN_LIMITATIONS.md) lists what is verified, what is rejected, and what remains outside the model; [the readiness report](docs/PRODUCTION_READINESS.md) records the evidence.
 
+**New here?** The [Quick start](docs/QUICKSTART.md) gets you from install to a reviewed refactoring in four steps.
+
+## What it does
+
+Towel finds code that is repeated across your functions and pulls each group of
+duplicates into one shared helper, rewriting the copies as calls to it. It works
+by *anti-unification*: it computes the least-general generalization of the
+matching blocks, so the parts that are the same become the helper's body and the
+parts that differ become its parameters.
+
+Given two functions that share a block:
+
+```python
+def order_summary(order):
+    items = [i for i in order.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return f"Order {order.id}: ${total}"
+
+def quote_summary(quote):
+    items = [i for i in quote.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return f"Quote {quote.id}: ${total}"
+```
+
+Towel proposes the shared block as a helper (emitted with a placeholder name you
+rename afterward) and rewrites both functions to call it:
+
+```python
+def __extracted_func_0(record):
+    items = [i for i in record.items if i.in_stock]
+    subtotal = sum(i.price for i in items)
+    total = round(subtotal * 1.08, 2)
+    return total
+
+def order_summary(order):
+    total = __extracted_func_0(order)
+    return f"Order {order.id}: ${total}"
+
+def quote_summary(quote):
+    total = __extracted_func_0(quote)
+    return f"Quote {quote.id}: ${total}"
+```
+
+What makes Towel different from a search-and-replace is that it is conservative
+and verified. It proposes an extraction only when it can prove the result runs
+the same as the original — instantiating the helper with each call's arguments
+and comparing against the block it replaced — and it refuses cases it cannot
+establish rather than guess. It skips trivial extractions that would add
+indirection without sharing real logic, wraps arguments that must not be
+evaluated eagerly in zero-argument `lambda`s (see
+[below](#why-some-arguments-are-wrapped-in-lambda)), and leaves naming to you.
+Nothing is written without your say-so: the workflow is preview, refactor into a
+copy, review the diff, and run your tests.
+
 ## Install
 
-The runtime uses only the standard library; optional `tqdm` provides progress bars. Platform, CPU, memory, and disk requirements are in [Requirements](#requirements) below.
+The PyPI package is **`code-towel`**; installing it gives you the **`towel`** command.
 
 ```bash
-python -m pip install .
+pip install code-towel
 towel --version
 towel --help
 ```
 
-The commands below describe this checkout; previously published distributions may differ.
+Install `code-towel`, not `towel`: the name `towel` on PyPI is a different, unrelated project, so `pip install towel` and `uvx towel` will not install this tool. To run it with `uvx` without installing, name the package explicitly:
+
+```bash
+uvx --from code-towel towel --help
+```
+
+The runtime uses only the standard library; optional `tqdm` provides progress bars. Platform, CPU, memory, and disk requirements are in [Requirements](#requirements) below.
 
 ## Requirements
 
@@ -45,7 +111,8 @@ The two largest projects in the ecosystem check, networkx and Sphinx, are the sl
 ## Use
 
 ```bash
-# Read-only analysis
+# Read-only analysis: lists each opportunity with the extracted helper and,
+# per call site, the original block (-) next to the generated call (+)
 towel preview path/to/project
 
 # Write to a new output directory
@@ -64,7 +131,7 @@ To roll back an interrupted batch, use `towel recover /path/to/.towel-transactio
 
 For detailed conservative rejection reasons, set `DEBUG_PROPOSAL_REJECTIONS=1` when running preview.
 
-`towel-dry` and `towel-preview` are compatibility entry points. `python scripts/dry` delegates to the same installed CLI. Run `towel dry --help` for import-layout, iteration, and progress options.
+Run `towel dry --help` for import-layout, iteration, and progress options.
 
 ## What is analyzed
 
@@ -72,10 +139,51 @@ The pipeline parses modules, analyzes scopes, collects functions and classes, co
 
 Differing sub-expressions become helper parameters. Names, literals, and tuples of those are passed eagerly; any other expression is passed as a zero-argument thunk and evaluated inside the helper where the original expression stood, so evaluation order, count, and conditionality are preserved. Expressions that read names bound inside the block are lambda-lifted with those names as arguments. A thunk the helper would evaluate first, once, and unconditionally is passed eagerly instead, since nothing can observe the difference. Before a proposal is offered, the helper is instantiated with each call's arguments and must reproduce the original block up to renamed binders.
 
-The refactoring pipeline preserves the original Python operators. The legacy `ast_normalizer` utilities remain available with deprecation warnings for compatibility, but can change Python behavior and are not used by this pipeline. Generator/suspension operations and frame-sensitive calls such as `locals()` are conservatively rejected. Nested blocks that bind names used outside the block are rejected until full control-flow liveness is supported. Static local import cycles and cross-module global declarations are rejected. This reduces the number of proposals rather than claiming an unsupported transformation is safe.
+The refactoring pipeline preserves the original Python operators. Generator/suspension operations and frame-sensitive calls such as `locals()` are conservatively rejected. Nested blocks that bind names used outside the block are rejected until full control-flow liveness is supported. Static local import cycles and cross-module global declarations are rejected. This reduces the number of proposals rather than claiming an unsupported transformation is safe.
 
 Dynamic imports, reflection, arbitrary callbacks, runtime rebinding, metaclasses, and external side effects limit what can be established statically. Each engine owns a bounded analysis session with content checks and isolated AST snapshots. The test import-isolation harness and an individual engine instance require sequential use. Candidates involving detected namespace rebinding, frame inspection, or comprehension assignment expressions are rejected; opaque external reflection and rebinding remain outside the supported model.
 
+## Why some arguments are wrapped in `lambda`
+
+When the differing sub-expression between two duplicates is more than a plain value, Towel passes it as a zero-argument lambda (a *thunk*) and calls it inside the helper at the exact place the original expression stood. In the output that looks like this:
+
+```python
+notify(lambda: welcome_email(user))
+```
+
+To a casual reader the lambda looks redundant. It is not. Passing the expression directly would evaluate it once, unconditionally, at the call site, and that changes behavior whenever the original evaluated it conditionally, more than once, or not at all. Consider two blocks that differ only in one call (illustrative):
+
+```python
+# before
+if user.active:
+    send(welcome_email(user))
+```
+
+Pass that call eagerly and it runs for every user, active or not:
+
+```python
+# WRONG: welcome_email(user) runs unconditionally, with its side effects, and
+# can raise, even when user.active is False
+def notify(message, user):
+    if user.active:
+        send(message)
+
+notify(welcome_email(user), user)
+```
+
+The thunk defers it to the spot the original code ran it, preserving the condition:
+
+```python
+# correct
+def notify(build_message, user):
+    if user.active:
+        send(build_message())
+
+notify(lambda: welcome_email(user), user)
+```
+
+The same reasoning covers an expression inside a loop (the thunk runs once per iteration, as the original did) or one that might raise. Towel keeps the wrapper only where it can matter: an expression the helper would evaluate first, once, and unconditionally is passed directly, because then nothing can observe the difference. So a `lambda:` in the output is a deliberate marker that Towel is preserving that argument's timing, count, or conditionality; its absence means eager evaluation was proven equivalent.
+
 ## Naming the helpers with an LLM
 
 Towel deliberately generates meaningless names, `__extracted_func_3` and `__param_0`, and leaves the naming to a separate, review-first step. Extraction is a verified mechanical transformation; choosing a good name is a judgment call, so the two are kept apart. The intended workflow hands the naming to a coding assistant, because the assistant reads far better names out of the call sites than any heuristic, and you review its choices before they touch the code.
@@ -97,6 +205,8 @@ towel rename-helpers path/to/cleaned --rename-file renames.json
 
 The JSON inventory gives the assistant what it needs to name well: every helper with its scope, source, and call sites, and for each parameter its evaluation kind (`value`, `thunk`, `lifted`, `receiver`) and the actual argument expressions passed at every call site. A parameter that always receives `user.email` and `account.email` should become `email`, and the argument expressions are how the assistant sees that.
 
+Each helper also carries a `changes` list: for every call site, the exact original block it replaced (`before`) next to the generated call (`after`). Seeing what the code did before extraction is what lets an assistant finish good names, write a docstring, and infer parameter and return types. This comes from a small `.towel-helpers.json` that `towel dry` writes next to its output; it is only for the naming step and is safe to delete afterward.
+
 Each inventory entry carries the exact mapping key to use as a rename target: `"path.py:helper"` renames a module-level helper together with its importers, `"helper"` renames a unique class-level helper together with every attribute reference, and `"path.py:helper.__param_0"` renames a parameter within the helper's scope. The rename is applied as one atomic batch with scope and importer checks; a name collision, a mangled name, or a dynamic reference aborts the whole batch and reports the reason, so a bad suggestion changes nothing. `--dry-run` reports the same JSON without writing.
 
 The shared `towel-rename` skill (in the agent-skills repository) walks an assistant through the whole loop: extract, review the diff, name, apply, and re-test. An interactive prompt mode is also available for naming by hand, and it calls no LLM service.
@@ -126,15 +236,21 @@ Behavioral tests compare sampled return values and types, exceptions, output, an
 
 ## Documentation
 
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Known limitations](docs/KNOWN_LIMITATIONS.md)
-- [Production readiness and ecosystem evidence](docs/PRODUCTION_READINESS.md)
-- [Adversarial review](docs/ADVERSARIAL_REVIEW.md)
-- [Historical issues](KNOWN_ISSUES.md)
+Start here:
+
+- [Quick start](docs/QUICKSTART.md) — install and refactor in four steps
+- [Known limitations](docs/KNOWN_LIMITATIONS.md) — what is verified, what is rejected, and what is outside the model
+- [Python API guide](docs/USAGE_GUIDE.md) — using `UnificationRefactorEngine` directly
+
+How it works and why to trust it:
+
+- [Architecture](docs/ARCHITECTURE.md) — the pipeline, the algorithms, and their references
+- [Production readiness](docs/PRODUCTION_READINESS.md) — the ecosystem evidence behind the claims
+- [Adversarial review](docs/ADVERSARIAL_REVIEW.md) — defects found and repaired
+
+Project:
 
-Historical notes and example outputs document earlier versions and may describe behavior superseded by the current audit. The current CLI help and source define the available interface.
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Releasing](docs/RELEASING.md)
 
 ## License
 

code_towel-1.618/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+Towel rewrites source code. Review the generated diff and run the affected project's own tests before adopting it; see [docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) for what is verified and what is not.
+
+## Supported versions
+
+Security fixes are provided for the latest released version, currently **1.414**. Earlier versions are not supported; the PyPI releases `1.0.0`–`1.0.4` are yanked for broken import handling and are not a recommended installation target. Upgrade to the latest release rather than relying on a fix to an older one.
+
+## Reporting a vulnerability
+
+Report suspected vulnerabilities privately through GitHub's **"Report a vulnerability"** button on this repository's **Security** tab (Security → Advisories → Report a vulnerability). That opens a private security advisory visible only to the maintainer. Please do not open a public issue for a security report, and do not include credentials or confidential source code in a report.
+
+This is a solo-maintained project with no formal response-time commitment. Reports are handled on a best-effort basis; you will receive an acknowledgment when a report is triaged. If a report leads to a fix, it ships in a new release, and the affected versions are noted in the advisory and the [changelog](CHANGELOG.md).
+
+## Execution and source safety
+
+Towel's analysis parses Python syntax without executing the analyzed project. The behavioral test harness executes fixtures and must be used only on trusted code. The rename assistant prints a prompt containing source excerpts for the user to transfer manually; consider the destination before sharing confidential code.
+
+Directory refactoring excludes symlinked Python files and refuses overlapping input/output trees. Generated files are compiled before writing. Writes use staged byte plans, per-file atomic replacement, rollback, and an interruption-recovery journal. Apply and recovery require exclusive write access; an unrelated writer can race snapshot checks. A batch is not globally atomic to readers, and a sequence of extractions is not a single atomic operation. Compilation does not prove behavior preservation. Static analysis cannot fully model reflection, dynamic imports, arbitrary callbacks, or external effects. Keep the original version under source control and review every generated diff.

{code_towel-1.414 → code_towel-1.618}/docs/ARCHITECTURE.md

@@ -42,7 +42,10 @@ fixed-point loop (below).
    blocks that unify with the accepted template and can share the helper.
 9. **Materialize.** `extractor.py` renders the helper and the call sites,
    compiles the generated Python to confirm it parses, and detects overlapping
-   replacements.
+   replacements. A proposal whose rendered helper body is a single forwarding
+   statement — a lone `raise`, a `return` of one call, or a bare call — is
+   dropped here: it would only add indirection. Construct the engine with
+   `skip_trivial_helpers=False` to keep such helpers.
 10. **Apply.** `changes.py` turns accepted proposals into an immutable byte
     plan and applies it transactionally (see *Application and recovery*).
 
@@ -172,8 +175,23 @@ helper can be imported correctly. It reads the build backend from
 `pyproject.toml` and derives import roots for setuptools (including
 `package-dir` mappings and the classic `src` layout), Hatch (wheel
 `packages`/`sources`), Flit, Poetry (`packages` with `from`), and pdm
-(`package-dir`). A layout it cannot resolve safely raises rather than guessing;
-the ecosystem check reports those as `UNSUPPORTED`. `semantic_safety.py`'s
+(`package-dir`). An unrecognized backend falls back to conventional inference:
+a package or module named after the distribution, in the project root or under
+`src`. Only a layout that cannot be resolved either way raises rather than
+guessing; the ecosystem check reports those as `UNSUPPORTED`.
+
+For a helper shared between two files in the same package, `refactor_engine.py`
+generates a relative import (`from .module import helper`, or a deeper
+`..sub.module`). A relative import encodes only the intrinsic same-package
+relationship, so it stays valid wherever the code lands — in particular when an
+out-of-place output is adopted into its real location, the documented workflow —
+and it matches the intra-package style the code already uses. An absolute import
+is used only when the discovered layout is anchored by a real packaging marker
+(`ProjectLayout.metadata_root`), so the absolute name survives relocation; a flat
+module with no package, where a relative import would not resolve, keeps a bare
+absolute name.
+
+`semantic_safety.py`'s
 `would_create_import_cycle` follows static imports through local modules,
 caching each module's import edges by path, mtime, and size, and rejects a
 helper placement that would close a cycle.
@@ -273,16 +291,6 @@ mapping as one atomic batch with scope and importer checks; a collision, a
 mangled name, or a dynamic reference aborts the whole batch and reports why, so
 a bad suggestion changes nothing. See the README for the end-to-end workflow.
 
-## Legacy normalization utilities
-
-[`ast_normalizer.py`](../src/towel/unification/ast_normalizer.py) is an
-importable compatibility module that emits `DeprecationWarning` when its
-transformers are constructed. Its assignment-to-augmented-assignment and
-arithmetic rewrites are **not used by the production pipeline** and are unsafe
-for arbitrary Python (`x = x + y` and `x += y` differ in aliasing and operator
-dispatch; reordering changes evaluation order and overloaded behavior). Do not
-reintroduce them into analysis or use them as an equivalence oracle.
-
 ## Verification and evidence
 
 The transformation's safety rests on the per-proposal instantiation invariant.
@@ -341,6 +349,8 @@ but the ideas and their names are from the literature.
 | Liveness and orphans | `definite_assignment.py`, `orphan_detector.py` |
 | Safety guards, import cycles, pre-scan | `semantic_safety.py` |
 | Helper and call-site rendering | `extractor.py`, `thunk_inlining.py` |
+| Parameter enumeration | `parameters.py` |
+| Progress reporting | `progress.py` |
 | Structural memoization | `structural_memo.py` |
 | Cross-file layout | `project_layout.py` |
 | Data model | `models.py` |

{code_towel-1.414 → code_towel-1.618}/docs/KNOWN_LIMITATIONS.md

@@ -127,6 +127,10 @@ uncertainty. Common reasons a real duplicate is not extracted:
 
 - A differing sub-expression is a slice, a starred item, or a whole f-string;
   these are container syntax rather than values.
+- The extracted helper body would be a single forwarding statement — a lone
+  `raise`, a `return` of one call, or a bare call. Such a helper shares no
+  logic, only a name, so it is skipped by default; construct the engine with
+  `skip_trivial_helpers=False` to keep it.
 - The block deletes, rebinds, or declares a name the caller keeps using.
 - A nested function or lambda shares a rebound name with the block.
 - The helper would need more than the configured maximum parameters.
@@ -143,11 +147,13 @@ uncertainty. Common reasons a real duplicate is not extracted:
   would have to be rendered inside the preceding branch's `else`; the
   `elif`'s own body and further branches remain candidates. This gives up a
   valid extraction when the preceding branch always exits (tabulate).
-- Project layouts other than setuptools, Hatch, Flit, Poetry, and pdm
-  conventions are refused for directory mode because import roots cannot be
-  inferred safely; the ecosystem check reports these as `UNSUPPORTED`.
-  Poetry ``packages`` entries with ``to`` or glob patterns, and a pdm
-  ``package-dir`` pattern, are refused likewise.
+- setuptools, Hatch, Flit, Poetry, and pdm layouts are read from their own
+  configuration. Any other build backend (for example ``flit_scm``) falls back
+  to conventional inference: a package or module named after the distribution,
+  in the project root or under ``src``. A project whose layout cannot be
+  resolved either way is refused for directory mode, and the ecosystem check
+  reports it as `UNSUPPORTED`. Poetry ``packages`` entries with ``to`` or glob
+  patterns, and a pdm ``package-dir`` pattern, are refused likewise.
 
 Set `DEBUG_PROPOSAL_REJECTIONS=1` to print the reason for each rejected pair.
 

code_towel-1.618/docs/QUICKSTART.md

@@ -0,0 +1,66 @@
+# Quick start
+
+Towel finds repeated Python code and extracts each group of duplicates into one
+helper function, rewriting the duplicates as calls. It verifies every extraction
+and leaves the naming to you. Refactoring changes your code, so the workflow is:
+preview, apply to a copy, review the diff, and run your tests.
+
+## Install
+
+```bash
+pip install code-towel
+towel --version
+```
+
+The PyPI package is `code-towel` and the command is `towel`. Do not install
+`towel`: that name belongs to a different, unrelated project, so `pip install
+towel` and `uvx towel` will not get this tool. Python 3.11–3.13 on macOS or
+Linux, no runtime dependencies.
+
+## 1. See what it would change (read-only)
+
+```bash
+towel preview path/to/project
+```
+
+For each opportunity, `preview` prints the extracted helper and, per call site, the original block (`-`) next to the generated call (`+`), so you can see exactly what would change before applying anything.
+
+## 2. Refactor into a fresh copy
+
+Never refactor in place on your first run — write to a new directory and diff it.
+
+```bash
+towel dry path/to/project path/to/cleaned --non-interactive
+diff -ru path/to/project path/to/cleaned | less
+```
+
+The output compiles and, for every proposal, the generated helper is verified to
+reproduce the exact code it replaced. Helpers get placeholder names like
+`__extracted_func_3`.
+
+## 3. Give the helpers real names (optional, LLM-assisted)
+
+```bash
+towel rename-helpers path/to/cleaned --list --json > helpers.json
+# Have a coding assistant read helpers.json and write renames.json,
+# then apply the batch (it aborts whole if any name is unsafe):
+towel rename-helpers path/to/cleaned --rename-file renames.json --dry-run
+towel rename-helpers path/to/cleaned --rename-file renames.json
+```
+
+See the [README](../README.md#naming-the-helpers-with-an-llm) for the full
+naming workflow.
+
+## 4. Review and test
+
+```bash
+# adopt the cleaned copy however you version-control it, then:
+pytest   # or your project's own test command
+```
+
+## Next
+
+- [README](../README.md) — full CLI usage, requirements, and timing
+- [Known limitations](KNOWN_LIMITATIONS.md) — what is verified, rejected, and outside the model
+- [Python API guide](USAGE_GUIDE.md) — using `UnificationRefactorEngine` directly
+- [Architecture](ARCHITECTURE.md) — how it works