bindery-cli 0.48.1__tar.gz → 0.49.0__tar.gz

bindery_cli-0.48.1/CLAUDE.md → bindery_cli-0.49.0/AGENTS.md

@@ -1,4 +1,4 @@
-# CLAUDE.md (bindery-cli)
+# AGENTS.md (bindery-cli)
 
 Per-project guidance. Overrides the global file where they conflict.
 
@@ -120,13 +120,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
 - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); 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; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs 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. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
   custom-rendered and colors itself with the CPython 3.14 argparse theme,
-  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. `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). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
+  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `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). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
 - `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
 - `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, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
 
 ## Conventions
 
-- Type hints, `from __future__ import annotations`, ruff for lint and format.
+- Python style follows the global conventions (type hints, `from __future__ import annotations`, ruff for lint and format; `~/.zcode/AGENTS.md`).
 - `./run_tests.sh` runs the suite in the project venv. Since the 3.12 floor, `uv run --python X` REBUILDS `.venv` for interpreter X, and the `python_version >= '3.14'` markers then gate vir-tui/cquarry OUT of it below 3.14 (the suite goes red with ModuleNotFoundError: cquarry). After interpreter experiments, rebuild with `uv run --python 3.14` before running the suite again.
 - `VERSION` lives in `src/bindery/__init__.py`, mirrored in `pyproject.toml`. Bump both.
 - Run tests with `./run_tests.sh`.
@@ -136,3 +136,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 The library is real data. The loop is always: dry run on `/tmp` copies, inspect the
 report, then apply with backups. epubcheck is the oracle; a repaired book that still has
 fatals is `partial` and must be left for manual work, never auto-applied.
+
+## Release flow
+
+Commit and push verified work (the standing push grant in the global file; force-pushes
+still need approval), wait for CI to go green, then tag: annotated `vX.Y.Z` at the release
+commit, message = that release's patchnotes entry verbatim (`--cleanup=verbatim`; the full
+tag procedure lives in `~/.zcode/AGENTS.md`). The tag drives `publish.yml`: the PyPI push
+plus the Bindery Repair plugin zip attached to the GitHub release. Version carriers:
+`src/bindery/__init__.py`'s VERSION and `pyproject.toml`; bump both.

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.48.1
+Version: 0.49.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -206,7 +206,9 @@ The sections below take each in turn.
 Help is two-level: `bindery repair --help` (or `library --help`) lists the
 shared repair flags grouped with one-line descriptions, and
 `bindery repair --help-repairs` prints the full reference carrying every
-flag's long rationale. On a terminal both are ANSI-colored with the same
+flag's long rationale, and `bindery --help-json` dumps the complete
+surface (every subcommand and flag, the repair reference, the per-verb
+exit contract, the Calibre gates) as machine-readable JSON. On a terminal both are ANSI-colored with the same
 theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
 `FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
 them.
@@ -236,7 +238,11 @@ 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
+# Cover-art quality and ToC-drift audits (advisory; never move the exit code)
+bindery audit cover ~/docs/Calibre\ Library
+bindery audit tocdrift ~/docs/Calibre\ Library
+
+# Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
@@ -265,7 +271,7 @@ With `--id`, `--json` accepts exactly one book id (each single-book run writes t
 
 **Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT, with the first broken entry named, instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
 
-### Tagging flagged books (opt-in)
+### Tagging flagged books (opt-in; the write is refused while Calibre runs)
 
 By default an audit writes nothing. With `--tag TAG` (library mode only), every book the audit
 flags is tagged in `metadata.db` through cquarry's trigger-safe write module, useful for piping
@@ -276,17 +282,23 @@ cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
 ```
 
 The audit itself stays read-only; only the final tagging pass writes, it skips books that already
-carry the tag, and THIN emptytext advisories are never tagged. Close Calibre first so the write
-does not fight its lock. Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
+carry the tag, and THIN emptytext advisories are never tagged. The write is REFUSED with exit 1
+while Calibre is running (a fail-closed pgrep guard: close Calibre and re-run). Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
 desktop app regenerates their sidecar `.opf`s (and re-pushes metadata to wireless readers) on its
 next startup: no manual resync needed.
 
 
-Repair one book to a new file (gated; writes only if it is an improvement):
+## Repairing a book
+
+Repair one book to a new file (gated; writes only if it is an improvement). Without an
+output path the verb is a probe: the gate runs and the report says what would change,
+and nothing is written anywhere, so probing a file can never litter the directory
+under vetting:
 
 ```sh
-bindery repair broken.epub                 # -> "broken (repaired).epub"
-bindery repair broken.epub fixed.epub
+bindery repair broken.epub                 # probe: report only, nothing written
+bindery repair broken.epub --all --json report.json   # probe with a machine-readable record
+bindery repair broken.epub fixed.epub      # rescue form: write the repaired file
 bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
 bindery repair stubs.epub --strip-stub-docs      # drop repeated placeholder chapters
 bindery repair broken.epub fixed.epub --json report.json  # machine-readable record
@@ -295,7 +307,11 @@ bindery repair broken.epub fixed.epub --json report.json  # machine-readable rec
 `repair --json FILE` writes one record in the `library --json` per-book
 vocabulary (`status`, `applied`, `before`/`after` counts, the fix `summary`),
 on every processing outcome including nochange and reject: a calling agent
-gets the same facts the console lines carry.
+gets the same facts the console lines carry. On a probe the record's
+`output` is null and `applied` stays false; the counts and the fix
+breakdown still describe the gate-accepted projection.
+
+## Sweeping a library
 
 Scan a Calibre library and see what would be fixed, writing nothing:
 
@@ -328,7 +344,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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.
-- Exit codes for `repair`, `library`, and `run`: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1. The `audit` verb runs its own contract, the inverse shape: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors (a path that is not a directory, a directory with no EPUBs, an unknown book id).
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean, probed, OR written (a probe writes nothing and exits 0; a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`); it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/README.md

@@ -179,7 +179,9 @@ The sections below take each in turn.
 Help is two-level: `bindery repair --help` (or `library --help`) lists the
 shared repair flags grouped with one-line descriptions, and
 `bindery repair --help-repairs` prints the full reference carrying every
-flag's long rationale. On a terminal both are ANSI-colored with the same
+flag's long rationale, and `bindery --help-json` dumps the complete
+surface (every subcommand and flag, the repair reference, the per-verb
+exit contract, the Calibre gates) as machine-readable JSON. On a terminal both are ANSI-colored with the same
 theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
 `FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
 them.
@@ -209,7 +211,11 @@ 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
+# Cover-art quality and ToC-drift audits (advisory; never move the exit code)
+bindery audit cover ~/docs/Calibre\ Library
+bindery audit tocdrift ~/docs/Calibre\ Library
+
+# Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
@@ -238,7 +244,7 @@ With `--id`, `--json` accepts exactly one book id (each single-book run writes t
 
 **Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT, with the first broken entry named, instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
 
-### Tagging flagged books (opt-in)
+### Tagging flagged books (opt-in; the write is refused while Calibre runs)
 
 By default an audit writes nothing. With `--tag TAG` (library mode only), every book the audit
 flags is tagged in `metadata.db` through cquarry's trigger-safe write module, useful for piping
@@ -249,17 +255,23 @@ cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
 ```
 
 The audit itself stays read-only; only the final tagging pass writes, it skips books that already
-carry the tag, and THIN emptytext advisories are never tagged. Close Calibre first so the write
-does not fight its lock. Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
+carry the tag, and THIN emptytext advisories are never tagged. The write is REFUSED with exit 1
+while Calibre is running (a fail-closed pgrep guard: close Calibre and re-run). Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
 desktop app regenerates their sidecar `.opf`s (and re-pushes metadata to wireless readers) on its
 next startup: no manual resync needed.
 
 
-Repair one book to a new file (gated; writes only if it is an improvement):
+## Repairing a book
+
+Repair one book to a new file (gated; writes only if it is an improvement). Without an
+output path the verb is a probe: the gate runs and the report says what would change,
+and nothing is written anywhere, so probing a file can never litter the directory
+under vetting:
 
 ```sh
-bindery repair broken.epub                 # -> "broken (repaired).epub"
-bindery repair broken.epub fixed.epub
+bindery repair broken.epub                 # probe: report only, nothing written
+bindery repair broken.epub --all --json report.json   # probe with a machine-readable record
+bindery repair broken.epub fixed.epub      # rescue form: write the repaired file
 bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
 bindery repair stubs.epub --strip-stub-docs      # drop repeated placeholder chapters
 bindery repair broken.epub fixed.epub --json report.json  # machine-readable record
@@ -268,7 +280,11 @@ bindery repair broken.epub fixed.epub --json report.json  # machine-readable rec
 `repair --json FILE` writes one record in the `library --json` per-book
 vocabulary (`status`, `applied`, `before`/`after` counts, the fix `summary`),
 on every processing outcome including nochange and reject: a calling agent
-gets the same facts the console lines carry.
+gets the same facts the console lines carry. On a probe the record's
+`output` is null and `applied` stays false; the counts and the fix
+breakdown still describe the gate-accepted projection.
+
+## Sweeping a library
 
 Scan a Calibre library and see what would be fixed, writing nothing:
 
@@ -301,7 +317,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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.
-- Exit codes for `repair`, `library`, and `run`: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1. The `audit` verb runs its own contract, the inverse shape: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors (a path that is not a directory, a directory with no EPUBs, an unknown book id).
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean, probed, OR written (a probe writes nothing and exits 0; a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`); it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/patchnotes.md

@@ -1,5 +1,74 @@
 # bindery-cli Patch Notes
 
+## v0.49.0 (2026-10-13)
+
+### The single-file repair probe writes nothing (issue #7)
+
+Found live in a phase-1 vetting run: `bindery repair <file> --all --json
+report.json`, the acquisition pipeline's documented single-candidate
+probe, wrote its full repaired output as an 11MB `...(repaired).epub`
+sibling inside the vetted tree, where anything beside the files gets
+inventoried: import litter by the pipeline's own rule, carrying a name
+only the `(repaired)` suffix apart from the original, so a later driver
+pointed at the pre-probe filename list either missed it or
+double-handled it.
+
+- **No output path is now a probe**: the epubcheck gate runs, the
+  console lines and the `--json` record carry the full projection
+  (status, before/after counts, the structured fix breakdown), and
+  nothing is written anywhere; the repaired bytes stay in the scratch
+  workdir and vanish. On a probe the record's `output` is null and
+  `applied` stays false.
+- **Writing needs an explicit destination** (`bindery repair book.epub
+  out.epub`), and that rescue form is byte-for-byte what it was: same
+  gate, same copy-the-accepted-bytes rule, same `--force` and
+  refuse-to-overwrite-the-input guards.
+- The probe's console verdict is the record's own status vocabulary
+  (`accept:`/`equal:`/`unvalidated:`; partial keeps its established
+  PARTIAL phrasing), followed by an explicit "probe: nothing written"
+  line; a probe that would be partial still exits 0 with the record's
+  status carrying the verdict.
+- The repair `--help` text (new probe example, the output positional's
+  no-write meaning) and `--help-json`'s exit contract tell the new
+  truth; README and spec.md document both forms. The exit contract
+  itself is unchanged: 0 clean/probed/written including partial, 1
+  trouble, never 2.
+- Three pins added (643 total): the probe writes nothing on the accept
+  and partial paths, and the `equal` noop verdict is carried honestly
+  rather than dressed up as repairable.
+
+## v0.48.2 (2026-10-06)
+
+### The 12-agent docs audit: README/spec/CLAUDE tell the v0.48 truth
+
+v0.48.0/v0.48.1 truthed the help and `--help-json` but touched only
+cli.py; the four-lens documentation audit converged on that lag. This
+propagates it (docs and two docstrings only, no behavior changes):
+
+- **README's exit-contract bullet taught repair's dead contract**
+  (trouble=2, usage=1) and omitted partial-writes-at-0, audit's exit 3,
+  and the lock-class refusals: it is per-verb now, mirroring
+  `--help-json`'s exit_contract block.
+- **The enforced closed-Calibre gate is stated where trust is earned**:
+  README's tagging section (advice became enforcement) and the
+  install-to-calibre story name the three doors and exit 1; spec's
+  Library replacement, Native installation, and audit sections name
+  their refusals; CLAUDE.md carries the v0.48 pair
+  (`_require_closed_calibre`, `--help-json`) plus the per-verb exit
+  truth.
+- spec's audit exit vocabulary gains the exit-3 class and the repair
+  carve-out is named where the inverse shape is attributed; the
+  partial-repair rule gets repair's writes-the-output exception;
+  spec's plugin config list gains `max_log_mb`.
+- README: Repairing a book / Sweeping a library section headers (the
+  usage docs were buried headerless inside the tagging subsection),
+  cover/tocdrift audit examples, `--help-json` in the help paragraph.
+- Two stale code docstrings the audit flagged: `__init__` (four lossy
+  strips, eight analyzers) and validate.py's `no_worse` (stub strips
+  and the rename half included).
+- One pin added (640 total): the newest patchnotes heading must carry
+VERSION.
+
 ## v0.48.1 (2026-10-06)
 
 ### The 12-agent audit: the exit contracts tell the truth
@@ -34,7 +103,7 @@ silences:
 - One code fix: the no-backup lossy warning now covers
   --strip-stub-docs (it warned for its three siblings only).
 
-15 pins updated/added (639 total).
+3 help pins updated to the new truths (639 total, unchanged).
 
 ## v0.48.0 (2026-10-06)
 

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.48.1"
+version = "0.49.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.48.1 → bindery_cli-0.49.0}/roadmap.md

@@ -42,6 +42,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | 0.46 | RSC-016 `--fix-comment-double-hyphen` (the last open repair class) and the RepairFlags dataclass | v0.46.0 |
 | 0.47 | The intake-wave batch (five open issues): the stub classifier's body-pool + image-carrier exemption, the NCName-complete `--fix-ids`, and `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr` | v0.47.0 |
 | 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
+| 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
 
 ## Open work
 

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/spec.md

@@ -433,32 +433,7 @@ book can never be auto-applied through the lossy path.
 
 For a Calibre library (`Author/Title (id)/Title - Author.epub`):
 
-- Work is done on a temporary copy; the original is read-only until the gate accepts.
-- Replacement is **atomic**: the repaired bytes are written to a temp file in the same
-  directory, fsynced, then `os.replace()`d over the original. The filename and path
-  Calibre expects never change; no partial file is ever visible.
-- The original file mode is preserved. Only the `.epub` is touched; `metadata.opf`,
-  `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync.
-- Writing requires `--apply` (default is a dry run). A backup is taken first when
-  `--backup DIR` or `--backup-inplace` is given.
-- A book that cannot be read at all (not a zip, truncated, encrypted entries) is
-  reported and counted as `unreadable`; it never aborts the rest of the sweep.
-- The `library` exit code is 0 for a clean sweep, 1 for a usage error, and 2 when any
-  book was rejected, unreadable, or failed epubcheck, so scripts can detect trouble.
-  Argparse-level misuse (unknown flag, malformed argument) exits 2 before the tool's
-  own validation runs; the tool's own usage validations exit 1. A `partial` book
-  (improved but still fatal) is reported for manual follow-up and counts as trouble:
-  `library`, `run phase1`, and `run phase3` all exit 2 on it (unified 2026-09-10).
-  The `audit` verb is the deliberate exception, its own contract in the inverse
-  shape: 0 clean, 1 when any book was flagged (a flag is the audit's trouble, so it
-  takes the trouble slot), 2 for its own usage errors (a path that is not a
-  directory, a directory with no EPUBs, an unknown book id) and for tagging-setup
-  failure.
-- With `--sweep`, `--workers N` runs the candidate-selection epubcheck pass through N
-  concurrent workers (default 1: serial, unchanged). Books are checked in windows of N
-  consumed in input order, so the candidate set and the before-measurements are identical
-  to the serial sweep; the repair phase is never parallel (the shared workdir and the
-  atomic-replacement contract live there).
+`--apply` is a filesystem write door and the install door is a metadata.db write door: `--apply --install-to-calibre` is REFUSED with exit 1 while Calibre is running (a fail-closed pgrep guard). `--backup-keep N` (minimum 2) caps the ring of same-named per-book backups.
 
 ### 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 and `data.name`; 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.
@@ -472,6 +447,8 @@ wrote the stray's size over the catalogued entry, the 2026-09-08 stray-size inci
 and a stale `(N)` directory whose book no longer exists saves in place instead of
 crashing the sweep.
 
+This door is lock-class: `--install-to-calibre` is REFUSED with exit 1 while Calibre is running (a fail-closed pgrep guard; close Calibre and re-run).
+
 ## Audit subcommand (read-only)
 
 `bindery audit {content,pagenumbers,emptytext,ocr,monolithic,completeness,cover,tocdrift,all} [PATH] [--max-doc-chars N]
@@ -518,7 +495,7 @@ storage-layout logic is not duplicated here. The scan itself still writes nothin
 separate trigger-safe write module (it registers Calibre's `title_sort`/`uuid4` SQL functions,
 bumps `books.last_modified`, and cleans link tables before tag deletion). THIN emptytext
 advisories stay untagged; already-tagged books are skipped; a missing file is a scan error, not a
-silent skip.
+silent skip. The tag write is lock-class: REFUSED with exit 1 while Calibre is running.
 
 `--json FILE` (v0.29.0) writes the same verdicts machine-readably, in the `library --json`
 shape: one record per file with a `status` (`clean`, `problem`, or `error`) and per-analyzer
@@ -582,6 +559,16 @@ half of the same information: consumers narrow lossy consent by fix class
 as data, never by substring-matching the rendered summary (v0.45.0; the
 phase1 payload inherits them through its per-book repair records).
 
+DST is optional, and the two forms have different write contracts. With a
+DST the verb is the rescue form: the gate-accepted bytes are written there
+(the input is never overwritten; an existing DST needs `--force`). Without
+a DST the verb is a probe: the gate runs and the record carries the
+projection (`output` null, `applied` false), and nothing is written
+anywhere, so probing a file in a vetted tree cannot litter it with a
+`(repaired).epub` sibling (the v0.48.2-and-before default, retired in
+v0.49.0; a probe that would be partial still exits 0 with `status`
+carrying the verdict).
+
 ## The Calibre plugin (Bindery Repair)
 
 Each release vendors the repair core into a Calibre plugin zip,
@@ -630,6 +617,7 @@ Behavior contract:
   the user's epubcheck binary under the `no_worse` bar and refused on a
   regression; an unanswered measurement never refuses. The mode is off by
   default (the latency ruling stands; the default pass is safe ungated).
+- **`max_log_mb`** (default 2): the plugin log's size cap in megabytes, one `.old` generation kept on rotation; `0` disables logging.
 
 ## Out of scope (non-goals)
 

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/src/bindery/__init__.py

@@ -1,17 +1,17 @@
 """bindery-cli: deterministic, epubcheck-gated EPUB repair and content auditing.
 
 The repair side: an always-on core of five well-formedness fixes plus the NCX
-pipeline and the mimetype fix, with the structural repairs, the three lossy
-strips (page numbers, broken tags, watermarks), and the safe opt-ins behind
-explicit flags. Around it: the read-only `audit` verb (six body-text
-analyzers), the `library` sweep with atomic in-place replacement in a Calibre
+pipeline and the mimetype fix, with the structural repairs, the four lossy
+strips (page numbers, broken tags, watermarks, stub documents), and the safe opt-ins behind
+explicit flags. Around it: the read-only `audit` verb (eight body-text and
+structural analyzers), the `library` sweep with atomic in-place replacement in a Calibre
 library, the `run phase1`/`phase3` acquisition slices, and the Bindery Repair
 Calibre plugin built from this core.
 
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.48.1"
+VERSION = "0.49.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/src/bindery/cli.py

@@ -420,7 +420,7 @@ class _HelpJsonAction(argparse.Action):
             "tool": "bindery",
             "version": __version__,
             "exit_contract": {
-                "0": "clean (repair: also written, including partial)",
+                "0": "clean (repair: also probed or written, including partial)",
                 "1": "library/run slices: trouble found; repair: trouble "
                 "(refused/failed/unreadable) or invocation problem; audit: "
                 "FINDINGS (the inverse contract, per spec.md); "
@@ -432,7 +432,8 @@ class _HelpJsonAction(argparse.Action):
                 "3": "audit: findings PLUS a failed --json/--tag write",
                 "130": "interrupted",
                 "per_verb": {
-                    "repair": "0 clean/written (partial writes, exit 0); "
+                    "repair": "0 clean/probed/written (a probe writes "
+                    "nothing, not even the sibling; partial writes, exit 0); "
                     "1 trouble or invocation problem; never 2",
                     "audit": "0 clean; 1 findings; 2 usage/environment; "
                     "3 findings + failed report write",
@@ -938,20 +939,21 @@ def run_repair(args) -> int:
     if not src.is_file():
         print(f"error: no such file: {src}", file=sys.stderr)
         return 1
-    dst = (
-        Path(args.output).expanduser()
-        if args.output
-        else src.with_name(f"{src.stem} (repaired).epub")
-    )
-    if dst.resolve() == src.resolve():
-        print("error: refusing to overwrite the input in place", file=sys.stderr)
-        return 1
-    if dst.exists() and not args.force:
-        print(
-            f"error: output exists: {dst} (pass --force to overwrite)",
-            file=sys.stderr,
-        )
-        return 1
+    # No output path is the probe form (issue #7): the gate runs and the
+    # report carries the projection, but nothing is written; the old
+    # implicit "(repaired).epub" sibling was import litter in a vetted tree.
+    # Writing needs an explicit destination.
+    dst = Path(args.output).expanduser() if args.output else None
+    if dst is not None:
+        if dst.resolve() == src.resolve():
+            print("error: refusing to overwrite the input in place", file=sys.stderr)
+            return 1
+        if dst.exists() and not args.force:
+            print(
+                f"error: output exists: {dst} (pass --force to overwrite)",
+                file=sys.stderr,
+            )
+            return 1
 
     def emit(record: dict) -> None:
         if getattr(args, "json_path", None):
@@ -974,7 +976,7 @@ def run_repair(args) -> int:
                 {
                     "mode": "repair",
                     "path": str(src),
-                    "output": str(dst),
+                    "output": str(dst) if dst else None,
                     "status": "error",
                     "applied": False,
                     "before": None,
@@ -990,7 +992,7 @@ def run_repair(args) -> int:
         base_record = {
             "mode": "repair",
             "path": str(src),
-            "output": str(dst),
+            "output": str(dst) if dst else None,
             "status": o.status,
             "applied": False,
             "before": _counts_dict(o.before),
@@ -1017,13 +1019,28 @@ def run_repair(args) -> int:
             )
             emit(base_record)
             return 1
+        ba = f"{o.before} -> {o.after}  " if o.before else ""
+        if dst is None:
+            # Probe: the accepted bytes stay in the scratch workdir; the JSON
+            # record and these console lines are the whole deliverable. The
+            # verdict word is the record's own status vocabulary.
+            verdict = (
+                "PARTIAL (still has fatals; needs manual work)"
+                if o.status == "partial"
+                else o.status
+            )
+            print(
+                f"{verdict}: {ba}{o.summary}\n"
+                "probe: nothing written (pass an output path to write the repaired file)"
+            )
+            emit(base_record)
+            return 0
         # Copy the exact bytes the gate accepted. Re-repairing src here would silently
         # drop the opt-in flags (--fix-ids, --reserialize, --strip-bad-attrs) and write
         # a file that differs from the one epubcheck validated.
         shutil.copyfile(work / "repaired.epub", dst)
         base_record["applied"] = True
         emit(base_record)
-        ba = f"{o.before} -> {o.after}  " if o.before else ""
         if o.status == "partial":
             # The file is a real improvement and worth writing, but calling it
             # "repaired" would read as fixed; it still will not open.
@@ -2078,13 +2095,15 @@ def build_parser() -> argparse.ArgumentParser:
 
     r = sub.add_parser(
         "repair",
-        help="repair a single EPUB to a new file",
+        help="repair a single EPUB (a probe when no output path is given)",
         usage="bindery repair [options] path [output]",
-        description="Repair one EPUB into a new file with the epubcheck-gated "
-        "core pass: the five well-formedness fixes, the NCX pipeline, and the "
-        "mimetype fix run always; every other repair is opt-in (grouped "
-        "below) and applied only when epubcheck confirms the result improved. "
-        "Never prompts. Exit codes: 0 clean or written (a PARTIAL repair "
+        description="Repair one EPUB with the epubcheck-gated core pass: the "
+        "five well-formedness fixes, the NCX pipeline, and the mimetype fix "
+        "run always; every other repair is opt-in (grouped below) and "
+        "applied only when epubcheck confirms the result improved. Without "
+        "an output path the verb is a probe: the gate runs and the report "
+        "says what would change, and nothing is written anywhere. Never "
+        "prompts. Exit codes: 0 clean, probed, or written (a PARTIAL repair "
         "writes its best output and exits 0; the --json record's status "
         "says so), 1 trouble (repair refused by the gate, epubcheck "
         "failure, or unreadable input) or invocation problem (bad args, "
@@ -2093,12 +2112,19 @@ def build_parser() -> argparse.ArgumentParser:
         epilog="examples:\n"
         "  bindery repair book.epub out.epub\n"
         "  bindery repair book.epub out.epub --all\n"
+        "  bindery repair book.epub --all --json report.json   "
+        "# probe: report only, nothing written\n"
         "  bindery repair book.epub out.epub --fix-svg-dup-ids "
         "--fix-cdata-terminator\n",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     r.add_argument("path")
-    r.add_argument("output", nargs="?")
+    r.add_argument(
+        "output",
+        nargs="?",
+        help="destination for the repaired file; omit it to probe "
+        "(report only, nothing written)",
+    )
     rc = r.add_argument_group("run control")
     rc.add_argument(
         "--force",

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/src/bindery/validate.py

@@ -2,7 +2,8 @@
 
 epubcheck is the external oracle. The `gate` demands measured improvement
 (fewer fatals, or fewer errors on a clean book) and `no_worse` accepts the
-lossy strips and cover repairs when nothing regressed. There is no degrade
+lossy strips (including stub-document strips), the cover wiring repairs, and
+the space-entry renames when nothing regressed. There is no degrade
 path: if epubcheck is not installed, callers refuse (exit 1, "epubcheck not
 found") unless the user explicitly passes --no-validate, which skips the gate
 and trusts the RepairReport alone.

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/tests/test_cli.py

@@ -184,6 +184,79 @@ class TestRepairRefusesOverwrite(unittest.TestCase):
             self.assertNotEqual(dst.read_bytes(), b"precious")
 
 
+class TestRepairProbeForm(unittest.TestCase):
+    """repair without an output path is a probe (issue #7): the gate runs,
+    the record carries the projection, and nothing is written anywhere; the
+    old implicit "(repaired).epub" sibling was import litter in a vetted
+    tree."""
+
+    def test_accept_probe_writes_nothing(self):
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            jout = Path(td) / "probe.json"
+            results = [CheckResult(1, 0, 0), CheckResult(0, 0, 0)]
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.run_epubcheck", side_effect=results),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src), "--json", str(jout)])
+            data = json.loads(jout.read_text())
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub", "probe.json"])
+        self.assertEqual(data["status"], "accept")
+        self.assertFalse(data["applied"])
+        self.assertIsNone(data["output"])
+        self.assertEqual(data["after"]["fatals"], 0)
+        self.assertIn("accept:", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+    def test_equal_probe_reports_the_noop_and_writes_nothing(self):
+        # 'equal' is the gate's noop verdict (accepted, no measurable gain);
+        # the probe must carry that status, not dress it up as repairable.
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            report = RepairReport(fixes={"fix_named_entities": 1})
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.repair_epub", return_value=report),
+                mock.patch(
+                    "bindery.cli.run_epubcheck",
+                    side_effect=[CheckResult(0, 0, 0), CheckResult(0, 0, 0)],
+                ),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src)])
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub"])
+        self.assertIn("equal:", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+    def test_partial_probe_reports_and_writes_nothing(self):
+        # A probe that would be partial is still exit 0 (the verb's own
+        # contract: partial is the record's status, not a failure); the
+        # point here is that the "best output" is NOT written.
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            results = [CheckResult(3, 0, 0), CheckResult(1, 0, 0)]
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.run_epubcheck", side_effect=results),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src)])
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub"])
+        self.assertIn("PARTIAL", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+
 class TestRepairWritesGatedBytes(unittest.TestCase):
     @unittest.skipUnless(HAVE_HTML5LIB, "html5lib not installed")
     def test_opt_in_flags_reach_the_output_file(self):

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/tests/test_version.py

@@ -111,3 +111,14 @@ class TestSyntaxFloor(unittest.TestCase):
         # the tree has dozens of modules; a broken path glob must not
         # let the guard pass vacuously
         self.assertGreaterEqual(checked, 20)
+
+    def test_patchnotes_newest_heading_matches(self):
+        # the docs-audit lesson: the release log's newest heading is a
+        # version carrier like any other
+        patchnotes = (
+            Path(__file__).resolve().parent.parent / "patchnotes.md"
+        ).read_text()
+        heading = next(
+            line.strip() for line in patchnotes.splitlines() if line.startswith("## v")
+        )
+        self.assertIn(CODE_VERSION, heading)

{bindery_cli-0.48.1 → bindery_cli-0.49.0}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "bindery-cli"
-version = "0.48.1"
+version = "0.49.0"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry", marker = "python_full_version >= '3.14'" },

bindery_cli-0.48.1/AGENTS.md

@@ -1 +0,0 @@
-CLAUDE.md