Skip to content

docs: the PDF path reached the ADR 0020 stages too - #641

Merged
willhea merged 1 commit into
developfrom
worktree-adr0020-pdf-doc-followup
Aug 15, 2026
Merged

docs: the PDF path reached the ADR 0020 stages too#641
willhea merged 1 commit into
developfrom
worktree-adr0020-pdf-doc-followup

Conversation

@willhea

@willhea willhea commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Two documentation statements went false when #639 and #638 merged six minutes apart.

#639 separated the PDF pipeline into the same four ADR 0020 stages and landed first; #638 landed second still saying the PDF path was unmigrated. Nothing could have caught this: #639 touches neither docs/decisions/0020-matching-stages.md nor docs/architecture.md, so there was no textual conflict, no failing test, and no merge-queue signal — only prose that had quietly stopped being true.

What changed

docs/decisions/0020-matching-stages.md — the Let classification re-consult similarity rejection cited diff_pdf._hunk_for_paired_blocks as still thresholding a correspondence score inside classification, and used that as the reason the record does not unify the two implementations.

Slice 6a closed precisely that violation. The function no longer receives a similarity at all; the moved-vs-modified rule moved unchanged into pdf_round1_move_basis, an assignment stage, and what remains is the modified emitter. The entry now says both pipelines hold the separation, and keeps the half that is still true — they share the boundary rule, not an implementation.

docs/architecture.md — said the PDF path was not migrated. It now says what it is: the same four stages, reached separately, with its own byte-identity gate (tests/test_pdf_canonical_baseline.py) and its own boundary tests. It also states why the implementations stay apart, since that is the question a reader asks next: an XML observation is a parsed tree node and a PDF observation is a reconstructed block, so a shared matcher would have to pick one representation and lose the other.

Verification

Every symbol was checked against the merged tree, not against #639's description:

  • pdf_round1_move_basissrc/deltatrack/diff_pdf.py:704
  • tests/test_pdf_canonical_baseline.py — exists
  • PdfObservation addresses a _Block, mirroring diff_bill.ObservationBillNode

A sweep for other "PDF is not migrated" claims found none. The remaining PDF-path statements concern lossiness and pre-publication availability, which are unaffected.

Documentation only — git diff over src/ and tests/ is empty. Docs and ADR-index gates pass (34); ruff check and ruff format --check clean.

Refs: ADR 0020

🤖 Generated with Claude Code

… has not

PR #639 separated the PDF pipeline into the same four stages, and merged into develop about six
minutes before #638. Two statements #638 carried were therefore false on arrival, and nothing
could have caught it: #639 touches neither ADR 0020 nor docs/architecture.md, so there was no
textual conflict and no failing test -- only prose that had quietly stopped being true.

ADR 0020's rejected-alternatives entry cited `diff_pdf._hunk_for_paired_blocks` as still
thresholding a correspondence score inside classification, and offered that as the reason the
record does not unify the two implementations. Slice 6a closed exactly that violation: the
function no longer receives a similarity, the moved-vs-modified rule moved unchanged into
`pdf_round1_move_basis`, an assignment stage, and what remains is the `modified` emitter. The
entry now describes both pipelines holding the separation, and keeps the part that is still
true -- they share the boundary rule, not an implementation.

docs/architecture.md said the PDF path was not migrated. It now says what it is: the same four
stages, reached separately, with its own byte-identity gate and boundary tests. The reason the
implementations stay apart is stated rather than implied, because it is the question a reader
asks next -- an XML observation is a parsed tree node and a PDF observation is a reconstructed
block, so a shared matcher would have to pick one representation and lose the other.

Every symbol cited was checked against the merged tree rather than against #639's description:
`pdf_round1_move_basis` at diff_pdf.py:704, tests/test_pdf_canonical_baseline.py, and
PdfObservation addressing a `_Block` as diff_bill.Observation addresses a BillNode. A sweep for
other "PDF is not migrated" claims found none; the remaining PDF-path statements are about
lossiness and pre-publication availability, which are unaffected.

Documentation only. No src/ or tests/ change.

Refs: ADR 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@willhea
willhea marked this pull request as ready for review August 15, 2026 15:59
@willhea
willhea added this pull request to the merge queue Aug 15, 2026
Merged via the queue into develop with commit 19108be Aug 15, 2026
31 checks passed
@willhea
willhea deleted the worktree-adr0020-pdf-doc-followup branch August 15, 2026 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant