mirror of
https://github.com/storytold/pdfcraft.git
synced 2026-10-14 11:17:10 -04:00
Tanish MankuandClaude
681548a47f
Replaces this PR's earlier contents. It previously added a committed `docs/plan/` tree -- a status baseline, an architecture doc and an execution plan. Since then `main` has grown `docs/gaps.md`, `docs/target-app-parity.md`, `docs/roadmap.md` and `docs/architecture.md`, which are actively maintained (gaps.md was reviewed 2026-10-10 and updated 2026-10-11) and cover the same ground better, because they sit in the flow contributors already touch. Keeping a parallel plan would have meant two sources of truth and a document that rots; it had already gone conflicting twice in three days. So the plan is dropped and only the parts with no equivalent anywhere remain. `.github/pull_request_template.md` is new -- the repository had none, with 167 PRs open and 66 of them conflicting. It leads with the two things a contributor cannot be expected to know and that cannot be undone after a merge: provenance (no Adobe asset, no committed font, no copied GPL/AGPL code, behaviour from the spec rather than from reading another implementation) and the never-crash rules. It also asks for a test that has been *seen to fail* before the fix, and says plainly that per-crate verification is preferred because CI runs the workspace anyway. CLAUDE.md gains three things it did not record: the four-zoom review habit (clause, function, file, project) with the tests that mirror it; the external-PR bar; and a note that builds and tests should be scoped per crate, because a full workspace build has locked up a development machine and CI covers it. The commit rule now also says that `main` moves fast enough for PRs to rot -- 396 commits in three days -- and that conflict risk tracks how contested the files are rather than how large the change is. Co-Authored-By: Claude <[email protected]>
3.4 KiB
3.4 KiB
What this changes
How you verified it
cargo fmt --check- clippy with
-D warningson the crates I changed - tests pass on the crates I changed
cargo xtask layersandcargo xtask assets(if you touched crate boundaries or any asset)
Tests. New behaviour needs a test at the right scale — a property test, a unit test, a crate integration test or an end-to-end one. For a bug fix, please check that the test fails before your fix by reverting the fix and watching it go red. A test nobody has seen fail is not evidence that it pins anything.
Never-crash
Every PDF, script, MCP call, settings file and keystroke is untrusted input (AGENTS.md §4).
- No new
unwrap/expect/panic!/unreachable!/todo!outside tests, unless it is provably infallible with a comment saying why - No indexing or slicing with input-derived positions (
get, and strings only at char boundaries); checked or saturating arithmetic; allocations sized by input are capped; recursion is bounded - No
unsafe - Any crash this fixes has a small synthetic regression test
Provenance
This is the part that cannot be undone after a merge, and the part a new contributor is
least likely to know about. Please read AGENTS.md §1 before adding any asset.
- No asset from an Adobe product, and no Adobe icon recreated, traced or imitated
- No font files committed here (they live in storytold/craft-fonts)
- No GPL/AGPL code copied in — MuPDF, Ghostscript, Poppler, veraPDF and DSS may only be run as external oracle processes
- Behaviour comes from the specification or black-box observation, not from reading another implementation's source
- Every new asset has an
ATTRIBUTION.tomlentry andcargo xtask assetspasses
Security
--rootconfinement still holds on every path, including ones reached by nested tool dispatch- MCP and the UI control channel stay opt-in, loopback-only and token-authenticated
- No new outbound network access (that decision is the owner's)
Parity and reach
parity/acrobat-features.tomlupdated in this PR, withnotessaying what is still missing —shippedmeans "exists and tested", not "as good as Acrobat"- Reachable headlessly through an
automationtool where that applies (AGENTS.md§3), so agents can drive it and not just the UI - Docs updated if this changes a documented behaviour (
docs/, crate README)