jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(bf-24wu4): update plan.md layout to v1.2 with shipped workspace reconciliation

Browse source 
- Update version from 1.1 to 1.2 (dated 2026-07-05)
- Add revision 1.2 entry documenting workspace reconciliation
- Expand File and Module Layout tree to include all shipped artifacts:
  - crates/pdftract-libpdftract (C ABI)
  - crates/pdftract-cer-diff (CER diff tool)
  - crates/pdftract-schema-migrate (schema migration tool)
  - xtask/ (build automation utilities)
  - sdk/ (PHP and Python subprocess SDKs)
  - templates/sdk-skeleton/ (SDK template)
  - e2e/phone-smoke/ (E2E phone smoke tests)
  - profiles/ (built-in and community profiles)
  - ci/ (CI gate scripts)
  - tools/ (fixture generation and debugging tools)
  - docs/user-docs/ (user-facing documentation)
  - Language SDK repositories (Node, Java, .NET, Go, Ruby, PHP, Swift)
- Add SDK cross-reference to docs/notes/sdk-architecture.md
- No semantic changes to phase specifications

Verification: notes/bf-24wu4.md
Closes: bf-24wu4
This commit is contained in:
jedarden 2026-07-05 22:50:03 -04:00
parent 155fdb0542
commit 82d2d561af
2 changed files with 137 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
docs/plan/plan.md
View file

@ -1,9 +1,9 @@
# pdftract Implementation Plan
**Version:** 1.1
**Status:** Active
**Repo:** jedarden/pdftract
**Last updated:** 2026-05-16
**Version:** 1.2
**Status:** Active
**Repo:** jedarden/pdftract
**Last updated:** 2026-07-05
---
@ -13,6 +13,7 @@
|---|---|---|
| 1.0 | 2026-05-16 | Initial plan: Phases 0–7, vector + OCR extraction, JSON/NDJSON/text output, PyO3 bindings, HTTP serve, StructTree, tables, forms, signatures, attachments. |
| 1.1 | 2026-05-16 | Brilliant-ideas integration round: added MCP server (Phase 6.7), Markdown output (6.5), multi-output emission (6.6), visual citation receipts (6.8), content-addressed cache (6.9), folder grep (7.8), inspector web viewer (7.9), document profiles (7.10), structural fingerprint (1.7), remote HTTP range source (1.8), document type classification (5.6). Plus pre-flight categories 1–4: Non-Goals, Glossary, ADRs, Open Questions, Proof Obligations, Acceptance Scenarios, Edge Case Catalog, Failure Mode Taxonomy, Diagnostic Code Catalog, Cross-Cutting Concerns, Anti-Patterns Catalog, Invariants. |
| 1.2 | 2026-07-05 | Workspace reconciliation: updated File and Module Layout to reflect shipped artifacts missing from v1.1 tree — added C ABI library (pdftract-libpdftract), CER diff tool (pdftract-cer-diff), schema migration tool (pdftract-schema-migrate), xtask build utilities, SDK skeleton templates, language SDK bindings (Node, Java, .NET, Go, Ruby, PHP, Swift), Python subprocess SDK, E2E phone smoke tests, built-in profiles at repo root, CI gate scripts, and tools directory. Cross-referenced SDK strategy to docs/notes/sdk-architecture.md. No semantic changes to phase specifications. |
Future revisions MUST append a new row before any material change lands in subsequent sections. The revision history is the single source of truth for "what changed when" — section-level edits MUST NOT silently mutate already-shipped semantics.
@ -235,8 +236,39 @@ pdftract/
│ │ └── verify_receipt.rs (Phase 6.8)
│ ├── pdftract-py/
│ │ └── src/lib.rs (PyO3 bindings, Phase 6.3)
│ ├── pdftract-libpdftract/
│ │ └── src/lib.rs (C ABI library; FFI layer for C/C++ integrations)
│ ├── pdftract-cer-diff/
│ │ └── src/main.rs (Character error rate diff tool; compares extractions)
│ ├── pdftract-schema-migrate/
│ │ └── src/main.rs (Schema migration tool; validates/translates schema versions)
│ └── pdftract-inspector-ui/
│ └── ... (HTML/CSS/JS bundled via include_bytes!, Phase 7.9)
├── xtask/
│ ├── Cargo.toml
│ └── src/
│ ├── main.rs (Build automation tasks: codegen, dist, schema generation)
│ ├── migrate/ (Schema migration utilities)
│ └── bin/ (Generated executables)
├── sdk/
│ ├── php/ (PHP subprocess SDK)
│ └── python-subprocess/ (Python subprocess SDK)
├── templates/
│ └── sdk-skeleton/ (SDK template for new language bindings)
├── Language SDK repositories (sibling repos under jedarden/):
│ ├── pdftract-node/ (Node.js/TypeScript SDK)
│ ├── pdftract-java/ (Java SDK)
│ ├── pdftract-dotnet/ (.NET SDK)
│ ├── pdftract-go/ (Go SDK)
│ ├── pdftract-ruby/ (Ruby SDK)
│ ├── pdftract-php/ (PHP SDK)
│ ├── pdftract-swift/ (Swift SDK)
│ └── swift-sdk/ (Swift native SDK)
├── e2e/
│ └── phone-smoke/ (End-to-end phone smoke tests)
├── profiles/
│ ├── builtin/ (Built-in document profiles; Phase 7.10)
│ └── community/ (Community-contributed profiles)
├── benches/
│ └── competitors/
│ ├── requirements.txt (pdfminer.six, pypdf, pdfplumber pins)
@ -244,12 +276,40 @@ pdftract/
├── build/
│ ├── font-fingerprints.json (Phase 2.2 Level 3 source data)
│ └── glyph-shapes.json (Phase 2.5 shape DB source data)
├── ci/
│ ├── rustdoc-gate.sh (Documentation coverage gate)
│ ├── schema-gate.sh (Schema validation gate)
│ └── wer-gate.sh (Word error rate gate)
├── tools/
│ ├── README.md (Tools documentation)
│ ├── convert_pdf_to_scanned.sh (PDF to scanned image converter)
│ ├── count_docs.py, count_docs.sh (Documentation counters)
│ ├── count_public_api.py (Public API surface counter)
│ ├── generate_encoding_fixtures.py, .rs (Encoding test fixture generator)
│ ├── generate_encrypted_pdf_fixtures.py, .rs (Encrypted PDF fixture generator)
│ ├── generate_invoice_fixture.rs, .py (Invoice test fixture generator)
│ ├── generate_stress_pdf.py (Stress test PDF generator)
│ ├── build-objstm-fixture/ (Object stream fixture builder)
│ ├── build-xref-fixture/ (XRef fixture builder)
│ ├── debug-fingerprint/ (Font fingerprint debugging utilities)
│ └── debug-fingerprint-diff/ (Fingerprint diff utilities)
├── docs/
│ ├── plan/plan.md (this document)
│ ├── research/ (per-feature deep dives referenced from phases)
│ ├── schema/v1.0/pdftract.schema.json (Phase 6.1 deliverable)
│ ├── integrations/ (MCP config snippets, IDE setup; populated post-v1)
│ └── notes/ (sdk-architecture.md, sdk-invocation.md, etc.)
│ ├── user-docs/ (User-facing documentation)
│ ├── notes/
│ │ ├── sdk-architecture.md (SDK strategy and architecture — SEE: SDK cross-reference)
│ │ ├── sdk-conformance-runner.md (SDK conformance test runner)
│ │ ├── sdk-contract.md (SDK contract specification)
│ │ ├── sdk-invocation.md (SDK invocation patterns)
│ │ └── ... (Additional project notes)
│ ├── adr/ (Architecture Decision Records)
│ ├── operations/ (Operational procedures)
│ ├── security/ (Security documentation)
│ ├── conformance/ (Conformance test specifications)
│ └── research-index.md (Research document index)
└── tests/
└── fixtures/
├── vector/ (clean LaTeX/Word/InDesign PDFs)
@ -265,6 +325,8 @@ pdftract/
└── profiles/ (per-profile fixture sets, Phase 7.10)
```
**SDK cross-reference:** The SDK strategy and architecture is documented in [`docs/notes/sdk-architecture.md`](docs/notes/sdk-architecture.md). Language SDK repositories are sibling repositories under the `jedarden/` organization; each SDK implements the contract specified in the SDK architecture document.
The layout is normative: phase-specific code MUST land in the file indicated for its phase. New top-level modules added in future revisions MUST be reflected here in the same plan revision that introduces them.
---

70
notes/bf-24wu4.md Normal file
View file

@ -0,0 +1,70 @@
# bf-24wu4 Verification Note
## Task
Update plan.md layout section and revision history to match the shipped workspace.
## Work Completed
### 1. Updated plan.md version and metadata
- **File:** `/home/coding/pdftract/docs/plan/plan.md`
- **Changes:**
- Updated version from 1.1 to 1.2
- Updated last updated date from 2026-05-16 to 2026-07-05
### 2. Added Revision 1.2 entry
Added a new row to the Revision History table:
| Version | Date | Material Changes |
|---|---|---|
| 1.2 | 2026-07-05 | Workspace reconciliation: updated File and Module Layout to reflect shipped artifacts missing from v1.1 tree — added C ABI library (pdftract-libpdftract), CER diff tool (pdftract-cer-diff), schema migration tool (pdftract-schema-migrate), xtask build utilities, SDK skeleton templates, language SDK bindings (Node, Java, .NET, Go, Ruby, PHP, Swift), Python subprocess SDK, E2E phone smoke tests, built-in profiles at repo root, CI gate scripts, and tools directory. Cross-referenced SDK strategy to docs/notes/sdk-architecture.md. No semantic changes to phase specifications. |
### 3. Updated File and Module Layout tree
Expanded the layout tree to include all shipped artifacts that were missing from v1.1:
**New crates added:**
- `crates/pdftract-libpdftract/` — C ABI library for C/C++ integrations
- `crates/pdftract-cer-diff/` — Character error rate diff tool
- `crates/pdftract-schema-migrate/` — Schema migration tool
**New top-level directories added:**
- `xtask/` — Build automation tasks (codegen, dist, schema generation)
- `sdk/` — SDK implementations (php/, python-subprocess/)
- `templates/sdk-skeleton/` — SDK template for new language bindings
- `e2e/phone-smoke/` — End-to-end phone smoke tests
- `profiles/` — Built-in and community document profiles
- `ci/` — CI gate scripts (rustdoc-gate.sh, schema-gate.sh, wer-gate.sh)
- `tools/` — Utility scripts and tools for fixture generation and debugging
**Language SDK repositories (sibling repos):**
- pdftract-node/
- pdftract-java/
- pdftract-dotnet/
- pdftract-go/
- pdftract-ruby/
- pdftract-php/
- pdftract-swift/
- swift-sdk/
**Additional docs sections added:**
- `docs/user-docs/` — User-facing documentation
- Expanded `docs/notes/` section with SDK-related documentation references
**SDK cross-reference added:**
Added a cross-reference note directing readers to `docs/notes/sdk-architecture.md` for SDK strategy and architecture details.
### 4. Verification
- ✅ No semantic changes were made to shipped phase sections
- ✅ Layout tree now reflects the actual workspace structure as of 2026-07-05
- ✅ All missing shipped artifacts from the task description have been added
- ✅ SDK architecture is properly cross-referenced
- ✅ Revision history properly documents the reconciliation
## Commit
Committed as `docs(bf-24wu4): update plan.md layout to v1.2 with shipped workspace reconciliation`
## Acceptance Criteria Status
- **PASS:** Append one revision 1.2 row describing the reconciliation ✅
- **PASS:** Update the layout tree to the actual workspace ✅
- **PASS:** Cross-reference SDK strategy to docs/notes/sdk-architecture.md ✅
- **PASS:** Make no semantic changes to shipped phase sections ✅
- **PASS:** Single plan-update bead for the 2026-07 gap review ✅