bindery-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/CLAUDE.md

@@ -34,11 +34,22 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
     v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
     name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
-    book-wide, inline `<style>` blocks included).
+    book-wide, inline `<style>` blocks included). The two EPUB2-targeted fixes
+    (`--strip-epub3-attrs`, `--downgrade-epub3-tags`) are additionally gated on the
+    package version in the OPF (`package_version()`): inert on EPUB 3 books and when
+    no version can be read, since their target defects only exist below EPUB 3; the
+    attribute scrub is anchored to real start tags via
+    `transforms.strip_attrs_in_start_tags` (prose mentioning the attributes and
+    CDATA/comment content are preserved), and `strip_invalid_value` matches the
+    attribute name with a `(?<![\w:.-])value` lookbehind so `data-value` survives.
   * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`;
     pagination.py, watermark.py): remove only what a converter injected (page numbers,
     running headers, leaked tags, watermarks), fenced behind character conservation, tag
-    balance, and the epubcheck no-regression bar.
+    balance, and the epubcheck no-regression bar. The watermark anchored pass's
+    whole-match fallback only fires when the match holds nothing but the stamp; a
+    larger match (an unclosed stamp anchor that swallowed prose) is refused, counted
+    in `RepairReport.watermark_refusals`, and surfaced as a `manual_watermark_repair`
+    decision by `run phase1` on both the read-only and apply paths.
   Do not let any NEW fix touch content without its own flag; if a candidate repair cannot
   be made deterministically safe, it does not belong here — report it for manual repair
   instead.
@@ -58,14 +69,14 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 ## Layout
 
-- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`).
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms.
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
 - `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, and `monolithic` since v0.21.0, `--max-doc-chars N`) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story).
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
-- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching) — the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (remove+add in one `batch()`; `add_format` refuses duplicates); the external `calibredb` CLI is gone. Never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
+- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching) — the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched — never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
 - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
 - `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, and the version pin.
 

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.31.0
+Version: 0.32.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Author: vrnvctss
 License: MIT
@@ -51,14 +51,14 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
 - **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
-- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
 - **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
 - **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
 - **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
 - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
 - **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
-- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
-- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
 - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
@@ -67,9 +67,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
 
-- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
+- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
-- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved.
+- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved. An inline stamp link is deleted only when it holds nothing but the stamp; a match too large to be safe (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 
@@ -200,7 +200,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
-- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning. A directory-name-guessed id is trusted only when `metadata.db` corroborates it (the book exists and the file is that book's catalogued EPUB); an uncatalogued stray file inside a book directory is saved in place and the catalog row is left untouched.
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/README.md

@@ -29,14 +29,14 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
 - **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
-- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
 - **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
 - **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
 - **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
 - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
 - **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
-- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
-- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
 - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
@@ -45,9 +45,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
 
-- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
+- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
-- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved.
+- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved. An inline stamp link is deleted only when it holds nothing but the stamp; a match too large to be safe (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 
@@ -178,7 +178,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
-- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning. A directory-name-guessed id is trusted only when `metadata.db` corroborates it (the book exists and the file is that book's catalogued EPUB); an uncatalogued stray file inside a book directory is saved in place and the catalog row is left untouched.
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/patchnotes.md

@@ -1,4 +1,113 @@
 # bindery-cli Patch Notes
+## v0.32.0 (2026-09-10)
+
+### The four Bug Reports fixes (2026-09-08 sweep) and the anchored-attribute cluster
+
+- **`--strip-watermarks` refuses anchored matches larger than the stamp**
+  (the sweep demonstrated two paragraphs of real prose vanishing with
+  count 1). The anchored stamp regex is DOTALL with no tag budget, so an
+  unclosed stamp `<a>` matched through real prose to the next unrelated
+  `</a>`, and the whole-match fallback deleted everything in between;
+  epubcheck cannot see deleted text, so the no-regression bar accepted the
+  loss. The fallback now fires only when the match demonstrably holds
+  nothing but the stamp (a tag-free body within stamp length, or visible
+  text exactly the watermark), a second `<a>` opening inside the match
+  refuses it outright, and anything larger stays in place, counted in the
+  new `RepairReport.watermark_refusals` and surfaced by `run phase1` as a
+  `manual_watermark_repair` decision on both the read-only and apply paths.
+  Safe shapes (pure wrappers, inline stamp-only links) are byte-identical
+  to before.
+- **Roman page-number detection reads well-formed numerals only**, in both
+  `--strip-pagination` and the audit pagenumbers analyzer. The old
+  `[ivxlcdm]{2,7}` character set read ordinary English words as page
+  numbers (`mid` = 1499), and a standalone `<p>mid</p>` before a
+  lowercase-starting paragraph is exactly the confident interrupt shape,
+  so real words were deleted and merged away. A roman counts only when
+  well-formed (explicit subtractive pairs) and valued under 100, where
+  front-matter page numbers live and words do not (`mix` = M+IX = 1009).
+  Lowercase front-matter romans keep working; the audit copy's deliberately
+  different year handling is untouched.
+- **`install_format` verifies directory-guessed ids against metadata.db.**
+  In directory mode, an uncatalogued stray `.epub` inside a book directory
+  made the `(id)` directory guess fire, and the row update re-registered
+  the catalogued format name with the stray file's size: the catalogued
+  999-byte file untouched on disk while `data` recorded 8123 bytes. A
+  stale `(N)` directory for a deleted book crashed the sweep instead. A
+  guessed id now drives a row update only when metadata.db corroborates it
+  (the books row exists, the file sits in that book's own directory, and
+  when an EPUB row exists it carries the row's stored name); anything else
+  saves the repair in place with a warning and leaves the catalog
+  untouched. The resolver path needs no verification: its id comes from
+  the catalog's own path map.
+- **The EPUB2-targeted fixes are gated on the package version.** Neither
+  `--strip-epub3-attrs` nor `--downgrade-epub3-tags` checked what the
+  package declared, so under `--all` every EPUB3 book in a sweep took the
+  EPUB2 cure: a repairable EPUB3 book gained a net-new error from a
+  stripped nav `epub:type` (whole repair rejected), and a legal
+  `epub:type="chapter"` was silently removed because the gate only sees
+  epubcheck counts. Both fixes now fire only on EPUB 2 packages (major
+  version 1 or 2) and are inert on EPUB 3 packages and when no version can
+  be read, where their target defects do not exist.
+- **The anchored-attribute regex cluster closes with the gate** (the same
+  sweep's sharpest repair-pipeline finding): the attribute scrub runs
+  anchored on real start tags through the new
+  `transforms.strip_attrs_in_start_tags`, with CDATA sections and comments
+  protected, so prose mentioning `epub:type="chapter"` is no longer
+  deleted down to `Use here`; `strip_invalid_value` matches its attribute
+  name behind a `(?<![\w:.-])value` lookbehind, so `data-value="42"`
+  survives instead of becoming a malformed `<span  data->`.
+
+### Repair-pipeline correctness (Phase 14, the 2026-09-08 sweep's backlog)
+
+- **`--fix-id-colons` is consistent and honest.** Only the bare `id`
+  attribute is in scope (a lookbehind keeps `data-id` and `xml:id` values
+  untouched), the fragment of an external URL survives verbatim (it names a
+  position in another document), the NCX's `content src` fragments follow
+  the rename through the new `fix_ncx_src_fragments` so a ToC never dangles
+  against the ids it references, and only actual colons replaced are
+  counted (byte-identical reruns report 0 and no longer trigger the
+  re-encode the untouched-file guard exists to prevent).
+- **The anchor pass runs last.** `strip_broken_anchors`' id snapshot used
+  to predate the unwrap fixes, so an id they deleted still counted as
+  present and fragments pointing at it survived dangling. The anchor pass
+  now runs after every content fix, against a snapshot that replicates
+  each id-moving fix ahead of it.
+- **CDATA sections and comments are protected everywhere.**
+  `strip_broken_tags` and `unwrap_illegal_tags` joined the module's
+  protected-span machinery (the wrapper now forwards arguments, so the
+  protected_tags-carrying unwrap could be decorated); a leaked-looking tag
+  inside either is literal rendered text, not markup.
+- **Non-UTF-8 documents are skipped verbatim.** A fix firing on a
+  windows-1252 or UTF-16 document used to decode with U+FFFD substitutes
+  and re-encode UTF-8 under a declaration still naming the old encoding:
+  usually well-formed, so the gate could not see the corruption. The write
+  loop strict-decodes first; failures are copied byte-for-byte, counted in
+  the new `non_utf8_docs_skipped` entry, and left for manual repair.
+- **`--reserialize` requires an html root.** A broken non-HTML `.xml`
+  sidecar used to come back html/body-wrapped with `ns0:` prefixes,
+  structurally rewritten while staying well-formed; it is now returned
+  untouched.
+- **Seven papercuts.** `fix_ncx_playorder` is anchored to `<navPoint>`
+  start tags (nav-label text is untouchable); mimetype fixes increment
+  `files_changed`; `fix_manifest_ids` and its reference rewrites are
+  quote-agnostic (a single-quoting OPF used to be a silent count-0 no-op;
+  the two shadowed `_IDREF_ATTR_RE` definitions collapsed into one);
+  the css selector boundary recognizes `svg|st`, `:is(st, w)`, and
+  `:where(...)` forms and the stylesheet scan collects `.xpgt` page
+  templates, so styled tags keep their unwrap protection; watermark
+  normalization decodes entities (`OceanofPDF.com&nbsp;` stamps now
+  match); the prolog and duplicate-xmlns fixes run under the
+  protected-span wrapper; and the archive comment field rides the rewrite.
+
+Dry-run validation for this release: the 14 staged top500candidates plus
+the 3 books_to_fix fixtures swept clean (9 accepted, 2 gate-refused
+regressions, 0 errors), and a 200-candidate sample of the real library
+(5,228 EPUBs) under `--all --workers 4` matched the documented verdict
+mix (94 accepted, 84 equal, 16 gate-refused, 0 partial, 0 epubcheck
+errors, 0 unreadable) with zero crashes. Read-only throughout; the
+gate-refused books are the safety contract declining marginal repairs,
+left untouched for manual work.
+
 ## v0.31.0 (2026-09-09)
 
 ### Cascade: install through cquarry 1.17's set_format

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.31.0"
+version = "0.32.0"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/roadmap.md

@@ -619,7 +619,17 @@ real content vanish with count 1; the output is well-formed with equal or
 fewer fatals, so the `no_worse` bar accepts it. `watermark.py:207-213`.
 **Fix:** require the anchored match to be tag-free (or stamp-length visible
 text) before falling back to whole-match deletion; anything larger goes to
-`decisions_needed` for manual repair. *(Unfixed as of the 2026-09-08 sweep.)*
+`decisions_needed` for manual repair. *(Fixed in v0.32.0: the fallback now
+fires only when the match holds nothing but the stamp, a tag-free body within
+stamp length or a body whose visible text is exactly the watermark, and a
+second `<a>` opening inside the match refuses it outright (the close belongs
+to that other anchor). Larger matches are left in place and counted in
+`RepairReport.watermark_refusals`, surfaced in every sweep summary and as a
+`manual_watermark_repair` decision by `run phase1` on both the read-only and
+apply paths. The anchored pass now decides all matches left to right and
+applies deletions right to left, so a refusal can no longer be re-counted on
+rescan. Regression tests pin the reported two-paragraph loss, the tag-free
+long swallow, and the safe inline shapes.)*
 
 ### roman-numeral detector reads ordinary English words as page numbers (2026-09-08 sweep)
 **Bug in `--strip-pagination`:** `_ROMAN_RE = [ivxlcdm]{2,7}\Z` (IGNORECASE)
@@ -629,8 +639,15 @@ paragraph is a confident page-number hit and is deleted and merged away.
 epubcheck is blind to deleted text, so `no_worse` passes. `pagination.py:44`,
 `70-78`, `180-184`.
 **Fix:** require uppercase romans, or validate with a strict roman grammar
-(`M?(D?C{0,3}|C[MD])(X?L{0,3}|L?X{0,3})(I?V{0,3}|V?I{0,3})`). *(Unfixed as of
-the 2026-09-08 sweep.)*
+(`M?(D?C{0,3}|C[MD])(X?L{0,3}|L?X{0,3})(I?V{0,3}|V?I{0,3})`). *(Fixed in
+v0.32.0, taking the grammar option to keep lowercase front-matter romans
+working, with one addition the demonstrated words forced: the grammar alone
+still accepts `mix` (M+IX = 1009), so a roman is a page number only when it is
+well-formed AND its value stays under 100, where real roman page numbers live
+and words do not. The audit pagenumbers analyzer's verbatim-twin detector got
+the same fix; the audit copy's deliberately different year handling is
+untouched (still its own question). Tests pin the word list, the surviving
+numerals, and the cap.)*
 
 ### install_format can write a wrong size into metadata.db for stray files (2026-09-08 sweep)
 **Bug in `library --apply --install-to-calibre` without `--id`:**
@@ -645,7 +662,18 @@ book instead raises an uncaught `TypeError` at the `book["path"]` access.
 **Fix:** when the id came from the directory guess, verify the target
 matches the DB's book path and format name before the batch; otherwise save
 in place and warn without touching the row, and catch the `TypeError` path.
-*(Unfixed as of the 2026-09-08 sweep.)*
+*(Fixed in v0.32.0: a guessed id now drives a row update only when
+metadata.db corroborates it — the books row exists, the file sits in that
+book's catalogued directory, and when an EPUB row exists it carries that
+row's stored name. Any other guess (a stray file in a book directory, a
+stale `(N)` directory whose book is gone, the resolver's id gone from
+`books` mid-run) saves the repair in place with a warning and leaves the
+catalog untouched; the `TypeError` on the missing books row is gone. The
+existing verified-guess fresh-placement and wrong-directory-degrades tests
+are unchanged in behavior. Also rode along here: spec.md's install section
+still described the v0.31.0-retired remove+add `batch()`; it now describes
+`set_format`. Tests pin the stray-size incident shape and the stale-directory
+save.)*
 
 ### EPUB2-targeted structural fixes fire on EPUB3 books under --all (2026-09-08 sweep)
 **Bug in `--strip-epub3-attrs` / `--downgrade-epub3-tags` via the run verbs
@@ -659,7 +687,14 @@ epubcheck counts. phase1 and phase3 always pass `--all`.
 `epub.py:251-260`, `903-937`, `957-967`; `cli.py:830`, `976-987`.
 **Fix:** gate both fixes on the package version carried in `opf_text`, or
 make them finding-driven (only strip what the before-pass epubcheck flagged).
-*(Unfixed as of the 2026-09-08 sweep.)*
+*(Fixed in v0.32.0, taking the version-gate option: both fixes are licensed
+by `package_version(opf_text)` and are inert on EPUB 3 packages and when no
+version can be read. This kills both demonstrated outcomes: the repairable
+EPUB3 book no longer gains a net-new error from a stripped nav `epub:type`,
+and the legal count-neutral `epub:type="chapter"` survives. The finding-
+driven alternative was rejected because it would still silently mutate legal
+markup whenever an unrelated finding existed; the gate keeps EPUB3 books
+byte-identical.)*
 
 ## Phase 11: Migrate install-to-calibre to native cquarry API (proposed 2026-08-31)
 
@@ -837,7 +872,7 @@ can be net-neutral and ships silently.*
 
 ### Repair-pipeline correctness
 
-- [ ] **Anchor attribute-name regexes to real start tags.** Three findings
+- [x] **Anchor attribute-name regexes to real start tags.** Three findings
       share one root cause: bare attribute-name regexes that are not
       quote-aware and not tag-anchored. `strip_invalid_value` matches the
       `value` in `data-value="42"` (the `\b` matches between `-` and `v`)
@@ -848,7 +883,14 @@ can be net-neutral and ships silently.*
       contradicting that fix's own docstring. Reuse the quote-aware
       start-tag matcher + protected-span machinery the module already has,
       and a `(?<![\w:.-])value` lookbehind.
-- [ ] **Make `fix_id_colons` consistent and honest.** It rewrites fragments
+      *(Done in v0.32.0: `strip_epub3_attributes` now runs through the new
+      `transforms.strip_attrs_in_start_tags`, which anchors the edit on the
+      module's quote-aware `_START_TAG_RE` and never touches CDATA/comments;
+      `strip_invalid_value` gained the `(?<![\w:.-])value` lookbehind, so
+      `data-value`, `xvalue`, and `xml:value` all survive untouched. Tests
+      pin the prose-mention case, CDATA/comment protection, multi-line start
+      tags, and the lookalike attribute names.)*
+- [x] **Make `fix_id_colons` consistent and honest.** It rewrites fragments
       of external URLs (`http://example.com/page#sec:1` becomes `#sec_1`,
       breaking the link; `transforms.py:524`, `536`, docstring at 509 claims
       otherwise) and rewrites colon-bearing `data-id`/`xml:id`; it never
@@ -857,25 +899,55 @@ can be net-neutral and ships silently.*
       (`epub.py:976-979` vs the NCX branch at `873-901`); and it counts
       every matched `id` attribute even when no colon was replaced, so
       byte-identical reruns report phantom changes (`transforms.py:513-516`).
-- [ ] **Run anchor stripping last and protect CDATA/comments everywhere.**
+      *(Done in v0.32.0: only the bare `id` attribute is in scope (a
+      `(?<![\w:.-])` lookbehind keeps `data-id` and `xml:id` untouched), a
+      fragment is translated only when the target is not an absolute URI or
+      protocol-relative reference (`_EXTERNAL_TARGET_RE`), the new
+      `fix_ncx_src_fragments` runs in the NCX branch under `--fix-id-colons`
+      so ToC `content src` fragments follow the rename, and the id replacer
+      counts only actual colons replaced, so byte-identical reruns report 0
+      and the untouched-file guard holds. Live evidence for this box showed
+      up in the v0.32.0 dry run itself: two staged books were gate-REJECTED
+      on `fix_id_colons` regressions manufactured the old way. Tests pin
+      the external-URL, data-id/xml:id, phantom-count, and NCX-follow
+      shapes.)*
+- [x] **Run anchor stripping last and protect CDATA/comments everywhere.**
       `strip_broken_anchors`' id snapshot predates `unwrap_block_in_inline`
       and `unwrap_illegal_tags`, which can delete ids the snapshot thinks
       exist (`epub.py:980-997`); `strip_broken_tags` and
       `unwrap_illegal_tags` are not wrapped in the module's own
       protected-span machinery, so they edit inside CDATA (rendered text)
       and comments (`transforms.py:444-450`, `619-623`).
-- [ ] **Stop re-encoding non-UTF-8 documents.** Any fix that fires on a
+      *(Done in v0.32.0: the anchor pass now runs last in the content
+      pipeline, and the id snapshot pre-pass replicates every id-moving fix
+      ahead of it (reserialize, id-colon renames, both unwraps, the
+      resource prune), so a fragment whose target an earlier fix deleted is
+      stripped instead of left dangling; `_outside_protected` now forwards
+      arguments, so `strip_broken_tags` and `unwrap_illegal_tags` (with its
+      protected_tags set) are both decorated and never edit inside CDATA or
+      comments. Tests pin the dangling-fragment shape and the protected
+      spans for both transforms.)*
+- [x] **Stop re-encoding non-UTF-8 documents.** Any fix that fires on a
       windows-1252 or UTF-16 document decodes with `replace` and re-encodes
       UTF-8, materializing mojibake under an XML declaration that still
       names the old encoding; usually well-formed, so the gate cannot see
       it (`epub.py:874`, `902`, `939`, `1027`). Detect and skip with a
       report entry, per the project's manual-repair philosophy.
-- [ ] **Scope `--reserialize` to HTML roots.** A broken non-HTML `.xml`
+      *(Done in v0.32.0: the write loop strict-decodes each NCX, OPF, and
+      content document before any fix runs; a document that is not valid
+      UTF-8 is copied byte-for-byte, counted in the new
+      `non_utf8_docs_skipped` report entry, and left for manual repair.
+      UTF-8 siblings in the same book are still repaired.)*
+- [x] **Scope `--reserialize` to HTML roots.** A broken non-HTML `.xml`
       sidecar gets html5lib's HTML algorithm and comes back
       html/body-wrapped with `ns0:` prefixes, structurally rewritten while
       staying well-formed (`epub.py:938`, `reserialize.py:39-42`). Require
       an `html` root (or manifest media-type) before rebuilding.
-- [ ] **Smaller repair papercuts:** `fix_ncx_playorder` can rewrite
+      *(Done in v0.32.0, taking the html-root check: `reserialize_if_broken`
+      requires an `<html` root before it will rebuild, so a broken page
+      template or other XML sidecar is returned untouched instead of
+      structurally rewritten. Tests pin the sidecar shape.)*
+- [x] **Smaller repair papercuts:** `fix_ncx_playorder` can rewrite
       `playOrder="N"`-shaped text inside nav labels (unanchored pattern,
       `transforms.py:326-328`); mimetype fixes land in `report.fixes`
       without incrementing `files_changed` (`epub.py:837-840`);
@@ -886,6 +958,17 @@ can be net-neutral and ships silently.*
       watermark `_norm` doesn't unescape entities so `OceanofPDF.com&nbsp;`
       stamps are missed; drop_duplicate_xmlns/strip_prolog_junk edit inside
       comments; the archive comment field is dropped by the rewrite.
+      *(Done in v0.32.0, all seven: playorder resequencing is anchored to
+      `<navPoint>` start tags so nav-label text is untouchable; mimetype
+      fixes increment `files_changed`; `fix_manifest_ids` and its reference
+      rewrites are quote-agnostic (the shadowed `_IDREF_ATTR_RE` definitions
+      were unified into one quote-aware regex); the css selector boundary
+      recognizes `svg|st`, `:is(st, w)`, and `:where(...)` forms, and the
+      stylesheet scan collects `.xpgt` templates too; watermark `_norm`
+      decodes entities so `OceanofPDF.com&nbsp;` pure-matches; both
+      prolog/xmlns fixes run under the protected-span wrapper; and the
+      archive comment rides the rewrite (`zout.comment = zin.comment`).
+      Tests pin every one.)*
 
 ### audit.py correctness
 
@@ -1065,3 +1148,24 @@ wired into every mode it promises, and the apply path's failure modes (crash
 mid-run, backup clobber, daemon stall) are unpadded. Fix the four Bug
 Reports entries and the anchored-regex cluster before any further features;
 everything else is backlog, not danger.*
+
+## Phase 15: completeness spot-check analyzer (proposed 2026-09-10, from the phase-1 skill's own doctrine)
+
+*The phase-1 skill's step 2 has a judgment step with no tool owner: the
+completeness spot-check ("sample early, middle, and late pages ... read the
+LAST content page to confirm it reaches real back matter rather than cutting
+off mid-chapter"). Two consecutive phase-1 runs (2026-09-08 Strauss batch,
+2026-09-10 Redwall batch) used a hand-rolled zipfile sampler in /tmp for it,
+which is exactly the "hand-rolled substitute becomes permanent" pattern the
+skill forbids; the skill allows only two inline checks, both with filed
+phases here. The sampler also already needed one repair (href unquoting)
+that the shipped audit gets for free. Proposal: an `audit completeness`
+analyzer that, in the audit's existing single decompression pass, reports
+per book: spine doc count, prose-doc count (>400 visible chars), the first /
+middle / last prose doc's opening and closing text, trailing-ToC detection
+(a final spine doc that is mostly chapter-heading lines), and the fraction of
+unreadable docs. The 2026-09-10 Redwall run is the fixture set: Lord
+Brocktree (real Epilogue doc before a trailing 520-char ToC), Mattimeo
+(Chapter 50 verified as a real heading with prose after, inside a 174k-char
+split doc), The Long Patrol (percent-encoded hrefs defeated the hand-rolled
+reader; 55/57 prose docs).*

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/spec.md

@@ -91,8 +91,12 @@ part of the default pipeline:
   incomplete"). Adds visible content, hence opt-in like `--add-img-alt`.
 - **`--fix-missing-title`**: inject `<title>Unknown</title>` when the head has no usable
   title.
-- **`--fix-id-colons`**: illegal colons in `id="X:Y"` and their matching `#X:Y` fragment
-  references become `_`; word-bounded, so external URLs are untouched.
+- **`--fix-id-colons`**: illegal colons in `id="X:Y"` and their matching internal
+  `#X:Y` fragment references become `_`. Only the bare `id` attribute is in scope
+  (`data-id` values are arbitrary data and are never touched), the fragment of an
+  external URL names a position in that other document and survives verbatim, and the
+  NCX's `content src` fragments follow the rename (`fix_ncx_src_fragments`), so a ToC
+  never dangles against the ids it references.
 - **`--unwrap-block-in-inline`**: drop a `<span>` that illegally wraps a
   `<div>/<p>/<blockquote>`, keeping the block element and its text.
 - **`--strip-invalid-value`**: remove misplaced `value="..."` attributes from non-form
@@ -105,7 +109,9 @@ part of the default pipeline:
 - **`--strip-epub3-attrs`**: scrub the EPUB3-only attributes epubcheck rejects on an
   EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed,
   documented set; extend only with a named epubcheck finding). Rendering is unchanged,
-  and reader-legitimate lookalikes (`type`, the wider aria family) survive.
+  and reader-legitimate lookalikes (`type`, the wider aria family) survive. The edit is
+  anchored to real start tags and never touches CDATA sections or comments, so prose
+  that merely mentions `epub:type="chapter"` is preserved.
 - **`--downgrade-epub3-tags`**: downgrade EPUB3/HTML5 semantic elements to their EPUB2
   equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing
   classes and appending the semantic name (`class="figure"`) as the styling hook.
@@ -113,6 +119,12 @@ part of the default pipeline:
   (`css_protected_tags`/`style_block_tags` are parameterized over the tag set), so
   styled formatting can never be silently destroyed; a protected book keeps its
   RSC-005 findings, which is the honest outcome.
+
+Both EPUB2-targeted fixes are gated on the package version carried in the OPF: they
+fire on EPUB 2 packages (major version 2 or 1) and are inert on EPUB 3 packages and
+when no version can be read, where their target defects do not exist and firing them
+would strip legal attributes and downgrade legal elements (the 2026-09-08 sweep found
+every EPUB3 book in an `--all` sweep taking exactly that damage).
 - **`--unwrap-illegal-tags`**: delete `<st> <sentence> <o> <w> <pagebreak>` tags outright,
   inner text preserved. Its CSS precondition is enforced by the library itself:
   `transforms.css_protected_tags` scans every stylesheet entry in the book (nested at-rules
@@ -167,6 +179,14 @@ Since this removes visible text from the reading experience, it is lossy by desi
 ### Opt-in, lossy: watermark strip (`--strip-watermarks`)
 Strips known producer and redistributor watermarks out of EPUBs (e.g. OceanofPDF.com, ABC Amber LIT Converter). The removal is a balanced-element surgery rather than regex slicing: it locates the stamp and deletes the outermost wrapper whose *entire visible text* is the watermark, ensuring prose that merely mentions the URL is preserved. Also drops known zero-byte marker files. Like other lossy operations, this is verified via `no_worse`.
 
+When the stamp link sits inline (no clean wrapper), the bare `<a>` element may be
+deleted only when the match demonstrably holds nothing but the stamp: a tag-free
+body no longer than a stamp, or a body whose visible text is exactly the
+watermark. An anchored match larger than that (an unclosed stamp `<a>` that
+swallowed prose out to the next unrelated `</a>`) is refused: nothing is removed,
+the refusal is counted (`watermark_refusals`) and reported for manual repair, and
+`run phase1` surfaces it as a `manual_watermark_repair` decision.
+
 ## Archive rewrite
 
 Entries are copied one at a time; `mimetype` is written first and `ZIP_STORED`. Its
@@ -180,7 +200,12 @@ a fresh `ZipInfo` rather than the source one because OCF requires the mimetype e
 carry no extra field. Content documents and the NCX get the transforms above; every other
 entry is copied verbatim with its original compression. An eligible entry that no
 transform changed is also copied byte-for-byte, never decoded and re-encoded, so a
-clean non-UTF-8 file cannot be silently mangled. A `RepairReport` records
+clean non-UTF-8 file cannot be silently mangled. A document that is not valid UTF-8
+at all (windows-1252, UTF-16) is never decoded-with-replacement and re-encoded: it is
+copied byte-for-byte, counted in the report (`non_utf8_docs_skipped`), and left for
+manual repair. The anchor pass (`--strip-broken-anchors`) runs after every other
+content fix, against an id snapshot that replicates each id-moving fix ahead of it. A
+`RepairReport` records
 per-transform counts and whether the NCX uid was synced.
 
 ## The epubcheck gate
@@ -219,8 +244,10 @@ Scope is `<p>` elements (where the defect is carried). For each book:
 - A **page-number layer** is confirmed only when BOTH hold: >= 20 standalone arabic
   numbers AND >= 3 confident interrupts. A chapter-numbered book has zero interrupts, so
   its chapter numbers are never touched. Roman numerals are removed only as a confident
-  interrupt, preserving roman chapter and front-matter numbering. Year-range values
-  (1500-2099) are never page numbers.
+  interrupt, preserving roman chapter and front-matter numbering; a roman counts as a
+  number only when it is well-formed (explicit subtractive pairs) and under 100, so
+  ordinary words built from roman letters (`mid`, `mix`, `civil`) are never read as
+  pages. Year-range values (1500-2099) are never page numbers.
 - **Merging:** only a confident interrupt (lowercase continuation or word split) rejoins
   the two surrounding prose paragraphs (a word split closes up its hyphen). Every other
   removal is delete-only, leaving the existing paragraph break.
@@ -274,7 +301,16 @@ For a Calibre library (`Author/Title (id)/Title - Author.epub`):
   atomic-replacement contract live there).
 
 ### Native format installation (`--install-to-calibre`)
-Optionally, bindery-cli installs the repaired EPUB as the book's format through cquarry's write module (`WritableCalibreDB`): the file is placed atomically — an in-place replace over the catalogued file when one exists (same path, same `data.name`), or a fresh placement under the repaired file's stem otherwise — and the `data` row follows in one `batch()` transaction (`remove_format` + `add_format`, since `add_format` refuses duplicates), keeping the size truthful and queuing the book in `metadata_dirtied` so Calibre regenerates its sidecar .opf. The external `calibredb` CLI is no longer used (the v0.23.1 `--replace` crash class is gone with it). It automatically falls back to atomic filesystem replacement if a valid Calibre ID cannot be extracted, and a database failure degrades to the in-place save with a warning rather than losing the repair.
+Optionally, bindery-cli installs the repaired EPUB as the book's format through cquarry's write module (`WritableCalibreDB`): the file is placed atomically — an in-place replace over the catalogued file when one exists (same path, same `data.name`), or a fresh placement under the repaired file's stem otherwise — and the `data` row follows through `set_format` (cquarry 1.17's sanctioned remove+add in one transaction), keeping the size truthful and queuing the book in `metadata_dirtied` so Calibre regenerates its sidecar .opf. The external `calibredb` CLI is no longer used (the v0.23.1 `--replace` crash class is gone with it). It automatically falls back to atomic filesystem replacement if a valid Calibre ID cannot be extracted, and a database failure degrades to the in-place save with a warning rather than losing the repair.
+
+The no-catalog fallback guesses the id from the `(N)` directory fragment. A guessed
+id may drive a row update only when metadata.db corroborates it: the book row exists,
+the file lives in that book's own directory, and (when an EPUB is catalogued) carries
+its stored `data.name`. Anything else is a stray file inside a book directory; the
+repair is saved in place and the row is left untouched (updating the row from a stray
+wrote the stray's size over the catalogued entry, the 2026-09-08 stray-size incident),
+and a stale `(N)` directory whose book no longer exists saves in place instead of
+crashing the sweep.
 
 ## Audit subcommand (read-only)
 

{bindery_cli-0.31.0 → bindery_cli-0.32.0}/src/bindery/__init__.py

@@ -4,7 +4,7 @@ strip), epubcheck-gated.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.31.0"
+VERSION = "0.32.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402