bindery-cli 0.34.0__tar.gz → 0.36.0__tar.gz

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/CLAUDE.md

@@ -77,12 +77,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) 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). Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book.
 - `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` (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/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.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, and the version pin.
 
 ## Conventions
 

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.34.0
+Version: 0.36.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
@@ -13,7 +13,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Requires-Python: >=3.14
-Requires-Dist: cquarry>=1.17.0
+Requires-Dist: cquarry>=1.19.0
 Requires-Dist: tqdm
 Requires-Dist: vir-tui>=2.2.0
 Provides-Extra: reserialize
@@ -57,8 +57,8 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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). 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.
+- **`--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:`).
@@ -82,7 +82,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
 
 Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
 
-Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a small in-process daemon that compiles `FastDaemon.java` into a temp directory at runtime and drives a warm JVM over a pipe. The daemon is a pool bounded by `--workers` (serial runs use one), its every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good — the two paths must never disagree about a book, and the subprocess oracle is the fallback by design. The daemon is also the scariest under-tested code in the repo and depends on a matched javac/java pair; its status is recorded in the roadmap's Phase 12 postscript and Phase 14 backlog.
+Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
 The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
@@ -126,10 +126,15 @@ bindery audit ocr ~/docs/Calibre\ Library
 # Flag books where a single content document is too large for readers to render
 bindery audit monolithic ~/docs/Calibre\ Library
 
+# Spot-check completeness: prose coverage, first/middle/last excerpts, trailing ToC
+bindery audit completeness ~/docs/Calibre\ Library
+
 # Run all audits and generate a comprehensive CSV
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
+**Completeness spot-check:** the `completeness` audit answers the pre-import question "does this book reach its end?" It reports, per book: the prose-document count against the spine (docs with 400+ visible characters), the opening and closing text of the first/middle/last prose doc, a trailing-ToC classification of the final spine doc (a link-dense chapter list after the real back matter), and the fraction of unreadable docs. A trailing ToC is reported as an advisory, never a failure: the closing excerpt always comes from the real back matter, so a human can confirm the book ends where the author ended it.
+
 Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
 ```sh
 bindery audit pagenumbers /path/to/loose/epubs
@@ -204,7 +209,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. 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.
+- `--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.34.0 → bindery_cli-0.36.0}/README.md

@@ -35,8 +35,8 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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). 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.
+- **`--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:`).
@@ -60,7 +60,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
 
 Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
 
-Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a small in-process daemon that compiles `FastDaemon.java` into a temp directory at runtime and drives a warm JVM over a pipe. The daemon is a pool bounded by `--workers` (serial runs use one), its every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good — the two paths must never disagree about a book, and the subprocess oracle is the fallback by design. The daemon is also the scariest under-tested code in the repo and depends on a matched javac/java pair; its status is recorded in the roadmap's Phase 12 postscript and Phase 14 backlog.
+Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
 The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
@@ -104,10 +104,15 @@ bindery audit ocr ~/docs/Calibre\ Library
 # Flag books where a single content document is too large for readers to render
 bindery audit monolithic ~/docs/Calibre\ Library
 
+# Spot-check completeness: prose coverage, first/middle/last excerpts, trailing ToC
+bindery audit completeness ~/docs/Calibre\ Library
+
 # Run all audits and generate a comprehensive CSV
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
+**Completeness spot-check:** the `completeness` audit answers the pre-import question "does this book reach its end?" It reports, per book: the prose-document count against the spine (docs with 400+ visible characters), the opening and closing text of the first/middle/last prose doc, a trailing-ToC classification of the final spine doc (a link-dense chapter list after the real back matter), and the fraction of unreadable docs. A trailing ToC is reported as an advisory, never a failure: the closing excerpt always comes from the real back matter, so a human can confirm the book ends where the author ended it.
+
 Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
 ```sh
 bindery audit pagenumbers /path/to/loose/epubs
@@ -182,7 +187,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. 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.
+- `--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.36.0/REPORT-12-Sept.md

@@ -0,0 +1,119 @@
+# REPORT-12-Sept: the repair-landscape research (bindery-cli vs real-world EPUB damage)
+
+Research date: 2026-09-10/11. Method: a read-only research pass mapping
+the full taxonomy of real-world EPUB damage — by producer (Calibre
+conversions, Word/Office export, InDesign, legacy OCR, Adobe Digital
+Editions, KindleUnpack, self-pub aggregators, Windows case-manglers) —
+against this repo's shipped repair surface, the Phase 14/15 backlogs,
+and the Bug Reports. References include the upstream clone's format
+readers. Full evidence lives in the agent's findings; this report is
+the distilled verdict and every actionable gap with its routing.
+
+## Verdict
+
+Bindery handles roughly **60-65% of real-world damage classes
+end-to-end** and is near-complete for its founding niche: markup
+well-formedness (the conversion-fatals class), NCX basics,
+zip/mimetype container hygiene, dead-reference pruning, watermark and
+page-number furniture, and archive/spine diagnosis (corruption, DRM
+skip, ToC-bloat classification). Phase 14's hardening and all five Bug
+Reports are shipped through v0.35.0; Phase 15 (the completeness
+analyzer) is approved.
+
+The missing ~35% is not more markup surgery. It is **package-level
+repairs** — container.xml, manifest media-types, spine attribute
+cleanup, encryption.xml/obfuscation state, zip-level dedupe, href
+case/IRI mismatches — and the finding that matters most: several of
+those classes are **gateway defects**. Epubcheck stays fatal while
+they persist, so no shipped repair can ever be gate-accepted on those
+books. They are locked out of the pipeline entirely.
+
+## A. The damage-taxonomy matrix and the repair gaps
+
+1. **Missing/corrupt `META-INF/container.xml`** (any producer):
+   epubcheck fatal; the OPF is unfindable. The locator falls back to
+   the first `.opf` but never writes the file. Deterministic fix:
+   generate the standard container.xml at the located OPF (upstream
+   calibre's `initialize_container` is the model). Effort S; HIGH
+   value — a gateway repair that unlocks an entire class of books.
+2. **Stale font-obfuscation state** (publisher EPUB3 fonts; IDPF
+   `2008/embedding` and Adobe `pdf/enc#RC`): post-KindleUnpack/strip
+   tools decrypt fonts in place but leave `encryption.xml` declaring
+   obfuscation; epubcheck errors and the audit implies DRM where there
+   is none. Fix: detect via font magic bytes at offset 0 vs the
+   CipherReference; prune stale entries; drop encryption.xml when only
+   obfuscation entries remain and the fonts verify. Never
+   un-obfuscate. Also gives the audit a real OBFUSCATED-vs-DRM
+   distinction. Effort M; needs the magic-byte detection validated on
+   real samples first.
+3. **Wrong/missing manifest `media-type`** (aggregators, ADE): fonts,
+   images, and media declared with wrong types. Fix: sniff magic bytes
+   or extension map; attribute-only. Effort S.
+4. **href case/backslash/IRI mismatches** (KindleUnpack, Windows
+   producers): `Images/Cover.JPG` vs `images/cover.jpg`, backslash
+   separators, `%XX` variants — the file IS present, so
+   `--prune-missing-resources` cannot touch the RSC-007/PKG-010 it
+   causes. Fix: case-insensitive namemap when exactly one match;
+   backslash to slash. Effort M.
+5. **Dangling reference edges after pruning** (any producer):
+   `spine@toc`, `item@media-overlay`, `item@fallback`, and EPUB2 cover
+   meta pointing at items the prune pass deleted. Today's prune checks
+   only `spine_ids` — it can manufacture the regression the gate then
+   rejects. Fix: extend prune to rewrite those edges (the rewrite
+   machinery exists in fix_manifest_ids). Effort S/M.
+6. **Duplicate zip entries** (any producer): last-wins shadowing; the
+   audit counts `dup_entries`, the rewrite copies both. Fix: drop
+   shadowed duplicates on rewrite. Effort S.
+7. **Cover wiring** (EPUB2 producers): dangling `<meta name="cover">`,
+   missing EPUB3 `properties="cover-image"`, wrong cover media-type —
+   calibre and booksellers extract no cover. Narrow, finding-driven
+   repair when the cover is identifiable from the existing guide/meta;
+   audit-only otherwise. Effort M.
+8. **Broken CSS from converters**: `url()` to absent assets, malformed
+   selectors. Repair is fiddly; ship the audit-only detector first and
+   let prevalence data decide. Effort M (repair).
+9. **Human-facing metadata validity** (self-pub/Word): non-ISO
+   `dc:date`, invalid `dc:language`, missing EPUB3
+   `dcterms:modified`. Explicit non-goal today; `dcterms:modified`
+   also collides with byte-determinism. Needs a written charter
+   ruling: carve-out with a determinism-safe timestamp policy, or
+   route to cquarry/CalibreQuarry. Effort M + a decision.
+10. **EPUB3 dual-ToC drift** (nav vs NCX): detection is a
+    deterministic structural diff feeding `decisions_needed`; full
+    sync is ToC synthesis and stays out of charter permanently.
+    Effort L if repair is ever attempted; audit-only recommended.
+11. **No-repair classes, correctly routed**: OCR garbage, truncated
+    re-sources, absent font families (audit + re-source); real DRM
+    (clean ENCRYPTED skip — shipped); DB-level format rows
+    (cquarry's, done); catalog completeness and human-facing metadata
+    quality (CalibreQuarry's audits).
+
+## B. Research-before-boxing
+
+1. **FastSweep prevalence study** — run `fast_sweep.py --mode=extract`
+   aggregation over the full library targeting the new classes
+   (container.xml presence/validity, encryption.xml algorithms,
+   media-type warnings, case-mismatch RSC-007s). The harness exists;
+   it sizes every box above with real counts before any is built.
+2. **The metadata carve-out ruling** (gap 9) — Brandon decides;
+   the audit records both options.
+3. **The obfuscation magic-byte table** (gap 2) — validate IDPF and
+   Adobe font prefixes against real samples before the repair ships.
+
+## C. Routing notes
+
+Package-structure repairs (items 1-6) fit the existing "structural
+opt-ins + gate" model without reopening the semantics-preserving
+contract. Items 7-10 each need an explicit scope decision first.
+Cross-repo: DB-level size/format-row mismatches route to cquarry
+(set_format, shipped); catalog completeness, duplicate detection, and
+human-facing metadata quality route to CalibreQuarry's audits; OCR,
+truncation, monolithic, and missing-font content stay audit-and-
+re-source permanently.
+
+## D. Phase 16 routing
+
+Items 1-6 (the ungated package-structure repairs) are boxed in
+roadmap.md **Phase 16** with the FastSweep prevalence study leading.
+Items 7-10 are recorded as decision-gated boxes. Phase 15 (approved)
+runs first if its fixture work is not yet done.

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/patchnotes.md

@@ -1,4 +1,89 @@
 # bindery-cli Patch Notes
+## v0.36.0 (2026-09-12)
+
+### The completeness spot-check: `audit completeness` (Phase 15)
+
+- **The phase-1 judgment step finally has a tool owner.** The import
+  skill's completeness step asks a human question with no tool behind
+  it: "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 answered it with a
+  hand-rolled zipfile sampler in /tmp. The new analyzer rides the
+  audit's existing single decompression pass (no second decode of any
+  book) and reports, per book: spine doc count, prose-doc count (spine
+  docs with at least 400 visible characters), the opening and closing
+  120 characters of the first/middle/last prose doc, a trailing-ToC
+  classification of the final spine doc, and the fraction of unreadable
+  docs (corrupt entries plus unresolved itemrefs).
+- **A trailing ToC never impersonates the ending.** The final spine doc
+  is classified as a chapter list when short link lines dominate it and
+  no block runs to paragraph length; such a doc is book furniture and
+  is excluded from the prose sampling, so the closing excerpt comes
+  from the real back matter. Verified against the real 2026-09-10
+  Redwall fixtures: Lord Brocktree's trailing ToC is caught and the
+  Epilogue is sampled as the last prose doc; The Long Patrol reads
+  exactly 55/57 prose docs through the percent-encoded hrefs that
+  defeated the hand-rolled sampler; Mattimeo's split doc (chapter
+  headings with real prose after every one) stays prose.
+- **Advisory by contract.** The analyzer never flags a book and never
+  moves the exit code: the archive, spine, and emptytext verdicts keep
+  owning the flags. The verdict status is ADVISORY (not OK) when a
+  trailing ToC is present or the unreadable fraction reaches 10%.
+  `audit all` and `run phase1` include it through the battery, the CLI
+  grows the `completeness` mode, and `--json` records carry its
+  verdicts in the same shape as the other analyzers.
+
+### Dependencies
+
+- Adopted cquarry 1.18.0 (floor + lock): the set_format repair lane now keeps
+  Calibre's FTS index and page counts honest automatically (the sidecar's
+  dirty queue and the pages rescan flag ride the write), and the search and
+  runtime fixes come along in the shared layer.
+- Adopted cquarry 1.19.0 (floor + lock): the repair lane gains its undo
+  primitive -- save_original_format/restore_original_format -- so a format
+  repair can put the original bytes back if it goes wrong.
+
+### Repo records
+
+- The release-tag backlog is settled forward-only from v0.35.0: the
+  nine untagged 0.18.0-0.26.0 entries are exempted by decision of
+  record (2026-09-11), and the v0.28.0 retag and the v0.33.0 em-dash
+  tag repair stay recorded-only force-pushes (roadmap.md, "Tag
+  policy").
+
+## v0.35.0 (2026-09-10)
+
+### The epubcheck daemon, reconciled: oracle-identical counts at ~15x the speed
+
+- **FastDaemon v2 measures exactly what the subprocess oracle measures.**
+  The daemon's old Java side counted message occurrences from
+  `CheckingReport`'s counters, while the gate has always measured the
+  counts in epubcheck's own `--json` output, which aggregates identical
+  messages (one book: 243 occurrences, 4 aggregated messages). On the
+  staged-fixture corpus the two methods diverged on 11 of 14 books, so
+  the daemon could never be enabled without changing what the gate
+  measures. The new daemon calls `CheckingReport.generate()` and reads
+  `nFatal`/`nError`/`nWarning` out of the JSON epubcheck itself
+  serializes: identical numbers by construction. Verified against the
+  subprocess oracle on all 14 staged books and on a 100-book
+  real-library sample: 114/114 identical.
+- **No more javac, no more version skew.** The daemon now launches
+  through Java's single-file source launcher (JEP 330): the running JVM
+  compiles the daemon in memory with its own compiler, so the
+  javac-newer-than-java skew that kept the daemon dead on this machine
+  (javac 27-ea, java 25) cannot recur on any toolchain.
+- **Measured, working daemon throughput: ~0.27s/book warm against
+  ~4.2s/book for the subprocess oracle** (15.6x). With `--workers N`
+  each worker gets its own warm daemon from the bounded pool, and every
+  roundtrip stays bounded by the caller's timeout with the fail-safe
+  fallback to the subprocess oracle.
+- **The dedup semantics are pinned by a suite test:** a book engineered
+  with one defect repeated three times plus one different defect must
+  answer 2 errors (the aggregated count), not 4 occurrences (the old
+  daemon's answer). Skipped where no epubcheck/JDK exists, like the
+  other oracle tests. README and spec's gate sections describe the new
+  design.
+
 ## v0.34.0 (2026-09-10)
 
 ### Brandon's three calls: partial books are trouble, the contract reconciled, the daemon decision informed

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.34.0"
+version = "0.36.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 = [
@@ -27,7 +27,7 @@ authors = [
 dependencies = [
   "tqdm",
   "vir-tui>=2.2.0",
-  "cquarry>=1.17.0",
+  "cquarry>=1.19.0",
 ]
 
 [project.optional-dependencies]

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/roadmap.md

@@ -663,7 +663,7 @@ book instead raises an uncaught `TypeError` at the `book["path"]` access.
 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.
 *(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
+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
@@ -996,7 +996,7 @@ can be net-neutral and ships silently.*
       v0.22.0 "its own verdict in every mode" promise (`audit.py:1565`,
       `1783-1803`, `1520-1558`).
       *(Done in v0.33.0: the archive and spine sections run unconditionally
-      after the selected content sections — they are always-on verdicts and
+      after the selected content sections; they are always-on verdicts and
       were already scanned and recorded in the JSON; only the console/rc
       path was dead. A CRC-corrupt book now prints its CORRUPT section and
       fails library mode with exit 1, matching directory mode. Test pins
@@ -1156,7 +1156,24 @@ can be net-neutral and ships silently.*
       javac at all), but the daemon should stay off until its counting
       matches the JSON oracle; retire-or-reconcile remains the open
       decision. The daemon already self-disables safely, and --workers
-      parallelism works via subprocesses.)**
+      parallelism works via subprocesses.)
+      *(DECIDED 2026-09-10: Brandon chose RECONCILE over retire. The
+      counting divergence turned out to run deeper than the daemon: the
+      CLI's human summary counts message occurrences (243 on one book)
+      while epubcheck's own --json output counts aggregated messages
+      (4 on the same book), and the gate has always measured the
+      aggregated scale. The reconciliation is therefore by construction:
+      FastDaemon v2 calls CheckingReport.generate() and reads nFatal/
+      nError/nWarning from the JSON epubcheck itself serializes, so the
+      daemon measures the subprocess oracle's numbers exactly. Verified
+      against the subprocess oracle on all 14 staged books (the same
+      corpus that diverged 11/14 under the old daemon) and on a
+      100-book real-library sample. The launch switched to Java's
+      single-file source launcher, removing javac and the version skew
+      permanently; the dedup semantics are pinned by a suite test
+      (skipped where no epubcheck/JDK exists). Daemon warm throughput
+      measured at ~0.27s/book vs ~4.2s/book subprocess. Shipped in
+      v0.35.0.)**
 - [x] **Smaller apply papercuts:** `--limit -1` and a missing
       `--audit` file raise tracebacks instead of usage errors
       (`cli.py:434`, `373`); the fresh-format branch of `install_format`
@@ -1269,7 +1286,7 @@ can be net-neutral and ships silently.*
 
 ### Documentation (drift is real but narrow)
 
-- [ ] **Reconcile spec.md with the shipped opt-ins.** The contract's
+- [x] **Reconcile spec.md with the shipped opt-ins.** The contract's
       non-goals forbid exactly what `--reserialize` (v0.3.0, the lone
       html5lib dependency) and `--strip-bad-attrs` (v0.4.0) do, and neither
       has a spec section; the OPF half of `--fix-ids` is missing;
@@ -1277,6 +1294,10 @@ can be net-neutral and ships silently.*
       NCX sentence at spec.md:52-53 is garbled (a dangling "to the OPF
       unique identifier" tail). A contributor reading spec.md first would
       conclude two shipped flags violate the charter.
+      *(APPLIED 2026-09-10, commit 01ad173, on Brandon's verbatim go
+      recorded in the audit sheet's evening answers; shipped with
+      v0.34.0. Ticked 2026-09-11 in the main-thread double-check after
+      the verifier caught the work shipping unticked.)*
       **GATED on Brandon: spec.md is the contract file. Draft proposal,
       ready to apply on a go (do not apply without one):**
       (1) Non-goals bullet 2 ("Repairing genuinely mangled structure
@@ -1351,6 +1372,14 @@ everything else is backlog, not danger.*
 
 ## Phase 15: completeness spot-check analyzer (proposed 2026-09-10, from the phase-1 skill's own doctrine)
 
+*(SHIPPED 2026-09-12 as v0.36.0: `audit completeness` rides the existing
+single decompression pass; the Redwall-shaped regression tests landed
+first (4021ce7), the analyzer second (e6156c0). Verified against the
+real fixtures: Lord Brocktree's trailing ToC is caught with the Epilogue
+sampled as the last prose doc, The Long Patrol reads exactly 55/57
+prose docs through its percent-encoded hrefs, and Mattimeo's split doc
+stays prose. Advisory by contract; `all` and `run phase1` include it.)*
+
 *(RAISED with Brandon 2026-09-10, batched with the session-start raises;
 recommendation: APPROVE. Execution is gated on that go; the proposal
 below is filed and costed. The Redwall run it names is a ready-made
@@ -1375,3 +1404,88 @@ 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).*
+
+## Phase 16: package-structure repairs (proposed 2026-09-12, from REPORT-12-Sept.md)
+
+A research pass mapped the full real-world EPUB damage taxonomy against
+the shipped repair surface: bindery handles ~60-65% of damage classes
+end-to-end, and the missing slice is package-level structure — several
+classes of which are GATEWAY DEFECTS (epubcheck stays fatal, so no
+shipped repair can ever be gate-accepted on those books). Full evidence,
+producer classes, and the cross-repo routing live in
+REPORT-12-Sept.md. Lead with the prevalence study; every box below is
+an opt-in structural repair under the existing gate contract.
+
+### A. Research first (boxes cannot be honestly sized without these)
+
+- [ ] **FastSweep prevalence study**: run `fast_sweep.py
+  --mode=extract` aggregation over the full library for the new
+  classes — container.xml presence/validity, encryption.xml
+  algorithms, manifest media-type warnings, case-mismatch RSC-007s.
+  Each Phase 16 repair box gets its real count before it opens.
+- [ ] **Obfuscation magic-byte validation**: confirm the IDPF
+  (`2008/embedding`) and Adobe (`pdf/enc#RC`) font prefixes at offset 0
+  against real samples before the encryption-repair box opens.
+
+### B. The repairs (each: opt-in flag, dry-run default, gate-accepted)
+
+- [ ] **`--fix-container`**: generate META-INF/container.xml at the
+  located OPF (model: upstream calibre's initialize_container).
+  Gateway repair, effort S, HIGH value.
+- [ ] **Obfuscation-aware encryption.xml repair**: prune stale
+  obfuscation entries when font magic bytes prove the fonts are
+  decrypted in place; drop encryption.xml when only obfuscation entries
+  remain and fonts verify. NEVER un-obfuscate. M.
+- [ ] **Audit distinction: OBFUSCATED vs DRM** in audit.py (today the
+  ENCRYPTED verdict keys on unreadable entries and implies DRM where
+  publisher obfuscation is benign). S, rides the box above.
+- [ ] **Reference-edge completion for `--prune-missing-resources`**:
+  rewrite `spine@toc`, `item@media-overlay`, `item@fallback`, and EPUB2
+  cover-meta edges when their targets are pruned (machinery exists in
+  fix_manifest_ids). Prevents manufacturing gate regressions. S/M.
+- [ ] **Manifest media-type normalization**: sniff magic bytes /
+  extension map; attribute-only. S.
+- [ ] **href case/backslash resolution**: case-insensitive namemap when
+  exactly one zip entry matches; backslash to slash. Kills the
+  present-file RSC-007/PKG-010 slice prune cannot touch. M.
+- [ ] **Duplicate zip-entry dedupe on rewrite**: drop shadowed
+  duplicates (audit already counts `dup_entries`). S.
+
+### C. Decision-gated (recorded boxes; no work without a ruling)
+
+- [ ] **Cover wiring repair** (dangling `<meta name="cover">`, missing
+  `properties="cover-image"`, wrong cover media-type): narrow,
+  finding-driven repair vs audit-only. Needs the scope decision. M.
+- [ ] **Metadata validity carve-out ruling** (non-ISO `dc:date`,
+  invalid `dc:language`, missing `dcterms:modified`): bindery opt-in
+  with a determinism-safe timestamp policy, or route to
+  cquarry/CalibreQuarry. Needs a written charter ruling. M.
+- [ ] **NCX<->nav drift DETECTOR** (audit-only; structural diff feeding
+  `decisions_needed`; ToC synthesis stays out of charter
+  permanently). L if repair is ever attempted.
+- [ ] **CSS url() pruning** as `--prune-missing-resources` scope
+  extension: only after the prevalence study says it matters. M.
+
+Ship shape: A leads; then B in value order (container, encryption,
+prune-edges, media-types); C boxes record their decisions and wait.
+Each repair ships with a fixture built from the prevalence study's
+real samples, a regression test written before the fix, and the gate
+(epubcheck) accepting the result.
+
+## Tag policy (decided 2026-09-11, recorded 2026-09-12)
+
+The release-tag backlog is settled, forward-only:
+
+- **v0.35.0 is the anchor.** Every release from v0.36.0 on is tagged at
+  its release commit under auto-tag promotion (a fully qualified release
+  is tagged and pushed without asking; the blitz rulebook's decision 22).
+- **The nine untagged 0.18.0-0.26.0 entries are exempted** by decision
+  of record (2026-09-11): no backfill tags will be cut for them. Their
+  release notes live in patchnotes.md and their wheels are on PyPI; the
+  missing git tags are accepted history.
+- **Two recorded-only repairs stay force-pushes, undecided:** the
+  v0.28.0 retag (the tag points at a red commit) and the v0.33.0
+  em-dash tag message (the pushed tag carries two em-dashes the
+  proofread missed; the source patchnotes entry was fixed immediately in
+  1c374c1). Either would need publish.yml disabled around the push and
+  Brandon's explicit go; neither is ever auto-executed.

{bindery_cli-0.34.0 → bindery_cli-0.36.0}/spec.md

@@ -239,10 +239,16 @@ the gate has not accepted anything, so nothing is applied or written. With
 `--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
 
 The oracle itself runs two ways: the `epubcheck --json -` subprocess, or a persistent
-daemon (`_EpubcheckDaemon`, a bounded pool sized by `--workers`) that compiles
-`FastDaemon.java` at runtime and drives a warm JVM over a pipe. Every daemon roundtrip
-is bounded by the caller's timeout, and any daemon failure tears it down and falls back
-to the subprocess for good, so the two paths can never disagree about a book.
+daemon (`_EpubcheckDaemon`, a bounded pool sized by `--workers`) that writes
+`FastDaemon.java` at runtime and launches it through Java's single-file source
+launcher (in-memory compilation by the running JVM: no javac, no version skew),
+driving the warm JVM over a pipe. The daemon answers with the counts it reads from
+the JSON that epubcheck's own `CheckingReport.generate()` serializes (the same
+document `--json` produces), so both paths measure identically by construction.
+(Epubcheck's JSON counts aggregated messages, not occurrences: a defect repeated
+three times is one error. The gate has always measured that scale.) Every daemon
+roundtrip is bounded by the caller's timeout, and any daemon failure tears it down
+and falls back to the subprocess for good.
 
 ## Page-number strip (opt-in, lossy)
 
@@ -337,8 +343,8 @@ crashing the sweep.
 
 ## Audit subcommand (read-only)
 
-`bindery audit {content,pagenumbers,emptytext,ocr,monolithic,all} [PATH] [--max-doc-chars N]
-[--tag TAG] [--id IDs]` (v0.15.0, `audit.py`; `--tag` since v0.18.0; `monolithic` since v0.21.0; `--id` since v0.19.0, comma-lists in v0.23.0) inspects
+`bindery audit {content,pagenumbers,emptytext,ocr,monolithic,completeness,all} [PATH] [--max-doc-chars N]
+[--tag TAG] [--id IDs]` (v0.15.0, `audit.py`; `--tag` since v0.18.0; `monolithic` since v0.21.0, `--max-doc-chars N`; `--id` since v0.19.0, comma-lists in v0.23.0; `completeness` since v0.36.0) inspects
 EPUB body text for flaws epubcheck cannot see: non-English script blocks, baked-in page-number
 layers (sliding-window density heuristics), empty or thin books, systemic OCR damage, and
 single oversized content documents (one spine doc at or above 300k characters — readers refuse
@@ -347,6 +353,18 @@ is fully read for CRC + decompression, reporting CORRUPT rather than EMPTY), and
 issues. Manifest/NCX references to absent files are classified as either `convention` (ToC is bloated but
 present documents form a consecutive chapter span) or `fragment` (the span itself is broken).
 
+The completeness analyzer is the phase-1 spot-check and is advisory by contract: it never
+flags a book and never moves the exit code. Per book it reports the spine doc count, the
+prose-doc count (spine docs carrying at least 400 visible characters), the opening and closing
+120 characters of the first/middle/last prose doc, a trailing-ToC classification of the final
+spine doc, and the fraction of spine docs that could not be read (corrupt entries plus
+unresolved itemrefs). A trailing ToC (the final doc is dominated by short link lines, at
+least half its lines carry links, and no block runs to paragraph length) is book furniture:
+it is excluded from the prose sampling so the closing excerpt comes from the real back
+matter, and the verdict becomes ADVISORY (as it does at an unreadable fraction of 10% or
+more). Like emptytext it is skipped wholesale when the archive verdict owns the body-text
+story.
+
 In library mode, EPUB files are resolved through `cquarry.db.CalibreDB.get_format_path()` — the
 storage-layout logic is not duplicated here. The scan itself still writes nothing. The opt-in
 `--tag TAG` pass applies `TAG` to flagged books via `cquarry.write.WritableCalibreDB`, the

{bindery_cli-0.34.0 → bindery_cli-0.36.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.34.0"
+VERSION = "0.36.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402