Roadmap: press as the whole publisher

The idea, stated once: a book repository holds the manuscript, its configuration, and its accepted art. The press holds the reusable publishing system: builds, verification, editorial law, agent instruments, art direction, front matter, retail preparation, and registration guidance.

Someone who understands press should be able to run press new, write a book, and finish with every promised artifact—EPUB, HTML, website, print-ready interior and cover wrap, and publication checklists—without copying publishing machinery into the book repository.

How this roadmap stays true

roadmap/milestones.json is the source of record for milestone identity, state, title, description, and reader-facing presentation order. Git commits and reviewed pull requests provide the durable history. GitHub milestones are the mutable execution view: they own live issue assignment, progress, and discussion. This page is the human-readable view and is published directly as the website’s roadmap.

The generated section below must never be edited by hand. Run python3 scripts/sync_roadmap.py --write after changing the registry. Every milestone links to its live issue list; every description links back to the relevant repository contracts or successor work.

This direction is intentionally one-way:

Propose roadmap intent in the repository.
Review the registry and generated roadmap in a pull request. The pull_request run only proves schema and projection; it holds no write authority, so a fork PR can never edit GitHub metadata.
Merge the immutable record to main.
Reconcile GitHub’s milestone metadata from that record. The push-to-main reconcile job runs scripts/sync_roadmap.py --apply-github with least-privilege issues: write (and contents: read), guarded by a concurrency group keyed to the workflow so an older commit’s run is superseded and cannot overwrite a newer commit’s metadata. It aligns only title, state, and description for milestone numbers already in the registry; it never creates or deletes a milestone and never edits an issue, and it writes a job summary linking the source commit and each changed milestone. A milestone in the registry but absent on GitHub is reported, not created.
Build the website from the same commit.

A weekly (and manually dispatchable) github-drift job stays an independent, read-only alarm: it reports out-of-band edits but never repairs them, so GitHub is never treated as a second source of truth.

Manual recovery: if the reconcile job is unavailable (an outage, a revoked token) and GitHub has drifted, a maintainer with gh authenticated repairs it locally with the same idempotent command the job runs:

python3 scripts/sync_roadmap.py --apply-github   # write: reconcile GitHub to the registry
python3 scripts/sync_roadmap.py --check-github   # read-only: report drift without writing

Editing milestone metadata only in GitHub is detectable drift, not a second source of truth. Issue titles, bodies, labels, and milestone assignments remain native GitHub data; duplicating them here would create a noisy and fragile shadow issue tracker.

Delivery milestones

Future and breaking horizons

Work deliberately held beyond the current v1 delivery train because it is breaking, optional, or depends on a mature single-book contract.

Later — Catalog · Open

Optional multi-book catalog after the single-book publishing contract is mature. Milestone: milestone 5. Scoped feature: issue 6. Roadmap context: the roadmap. Artifact contract to preserve: the architecture guide.

Delivery trust — live proofs · Open

The delivery-trust work that cannot be finished from a single identity or a single CI run: the live second-party proofs (#87, human-run, needs a second GitHub account/org), and assembling the release trust chain from receipts the individual CI jobs emit and upload (#150), rather than synthesizing the chain inside the release-contract job.

Icebox · Open

Deferred indefinitely: worthwhile work with a finished design or plan, held out of the active train until it is prioritized. Not blocked on anything external – a deliberate scheduling choice. Holds #173 (third-party extension registration), whose design is ratified in docs/THIRD-PARTY-EXTENSIONS-PLAN.md and whose implementation is a future major; and the custom merchant-of-record commerce stack (the order broker, hosted checkout, provider adapters, payment/fulfillment state machines, webhooks, outbox, reconciliation, and privacy/observability infrastructure), set aside because self-fulfilled or provider-seller-of-record selling is not what the press is about. Plan of record: docs/DIRECT-ORDERING-PLAN.md.

Book breadth · Open

Broaden the kinds of books press can make. Profile axis first – color interiors, more trims, large-print – each an additive, v2-minor-compatible sealed profile proven by a golden-copy inspection; then a finisher source mode that publishes, registers, and print-packs an externally-designed interior press did not typeset. The heuristic: a new profile of the prose engine is core press work, a new engine is not. Non-Latin and right-to-left scripts stay in the Icebox as a major per script family.

Completed foundations

Closed milestones retained as the historical foundation for the active work and as links to their shipped issue records.

v1.1.1 — Integrity hotfix · Complete

Historical integrity hotfix: correctness and release-safety failures where a command could succeed while public output was wrong or unsafe. Review the closed scope at milestone 1 and release history at the changelog. The contract it established is documented at the architecture guide.

v1.2 — Executable contracts · Complete

Historical executable-contract release: centralized configuration/artifact contracts, stronger verifiers, and real consumer-book integration. Closed scope: milestone 2. Architecture: the architecture guide. Generated artifact reference: the command reference. Successor integrity work: milestone 6.

v1.3 — Public readiness · Complete

Historical public-readiness release: licensing, installation, support/security guidance, portability, and repository-boundary evidence. Closed scope: milestone 3. Installation: the installation guide. Contribution policy: the contributing guide. Remaining live second-party proof: issue 87.

v2 — Composable press · Complete

Reserved for breaking design/extension work that cannot ship under the v1 rendering contract: configurable geometry/themes, vendor-neutral operator boundaries, and other explicitly breaking changes. Milestone: milestone 4. Breaking-change issues: the tracked issues. Versioning contract: the architecture guide. Roadmap: the roadmap.

v1.10 — Boundary integrity · Complete

Completed boundary-integrity release: source/publication safety, archive and format verification, retail artifacts, workflow input containment, exact toolchain identity, and resumable releases. Release: the v1.10.0 release. Closed scope: milestone 6. Architecture and artifact laws: the architecture guide. Its verifiers become named accumulated-trust proofs in milestone 9; release/container outcomes feed milestone 10.

v1.11 — Workflow coherence · Complete

Workflow and public-contract coherence: durable editorial/research outcomes, domain-neutral instruments, aesthetic/config documentation, contributor guidance, package metadata, and complexity debt. Milestone/issues: milestone 7. Public architecture/reference issue: issue 33. Contributor contract: the contributing guide. Testing traceability is implemented separately in milestone 8.

v1.12 — Trust foundations · Complete

Accumulated-trust foundation: pytest/selftest structure, executable invariant and callable-surface ledgers, collection-time proof enforcement, typed deterministic adapters, composable book factories, fixture provenance, property tests, and bounded replayable fuzzing. Milestone/issues: milestone 8. Start at issue 78, then invariant ledger issue 79. Feeds adversarial artifact proof: milestone 9. Architecture: the architecture guide.

v1.13 — Adversarial artifact proof · Complete

Adversarial artifact proof built on v1.12: named damage operators, fixture-specific negative diagnostics, deterministic build/mutate/verify state models, pairwise/high-risk scenarios, real-tool integrations, compatibility, and design-major visual regression. Milestone/issues: milestone 9. Prerequisite foundation: milestone 8. Damage harness: issue 88. Real-tool runner: issue 91. Feeds delivery trust: milestone 10.

v1.15.2 — Delivery trust completion · Complete

The delivery-trust work deferred from v1.14/v1.15.1, shipped in v1.15.2: the layered CI reorder and the complete accumulated-trust receipt chain (#94/#97 — a release must present every trust layer, contiguous and linked, not a placeholder standing in for them), the deterministic mutation-score ratchet over the pure-computation modules (#95), and the per-module branch-coverage floor ratchet (#96). The live second-party proofs (#87) and the per-job receipt assembly (#150) moved to the ‘Delivery trust — live proofs’ milestone, which needs a second identity and cross-job CI artifacts.

v1.15 — Operator desk · Complete

Post-v1.14 optional operator desk: a single typed command catalog, digest/receipt-backed artifact status (never mtimes), typed doctor findings, a versioned child-event protocol, deterministic single-child control, DESK/target-picker/RUN views, headless active-signal tests, installed-wheel proof, and public documentation. Milestone/issues: milestone 11. Start with command catalog issue 100, events issue 102, packaging boundary issue 104, and test harness issue 108. Evidence status issue 101 depends on trust receipts issue 93. Release gate: issue 114. Durable plan: the TUI plan. Architecture: the architecture guide. Textual testing: textual.textualize.io.

v1.16 — Direct print ordering · Complete

Post-v1.15 direct-to-reader print ordering on the seller-of-record model: the provider (Lulu first) is the legal seller and owns payment, tax, fulfillment, and support, so press ships no payment infrastructure. Remaining after the manifest (#118, done): provider qualification and physical sample protocol (#117), a generated accessible storefront CTA with a no-JS fallback (#123) linking to the provider-hosted checkout (#139), a capped golden-copy inspection (#143), documentation (#138), and the release gate (#144). The custom merchant-of-record machinery (broker, Stripe checkout, provider API adapters, state machines, webhooks, outbox, reconciliation) is deferred indefinitely to the Icebox milestone. Plan: direct-ordering-plan.

v1.18 — Public experience and adoption · Complete

Completed public-experience release: beginner onboarding, validated configuration UI, conventional CLI discovery, accessible/semantic documentation and reader surfaces, public CI/toolchain consumption, and contributor/discovery governance. Release: the v1.18.0 release. Closed scope: milestone 15. Public site: clintecker.github.io. Residual reader metadata and gallery render proof moved to milestone 4 as #158 and #190.

v1.19 — Maintenance and compatibility · Complete

Completed maintenance/compatibility release: contributor verification, print-safe interiors, registrations and printing guides, security controls, Python 3.14 qualification, warning-clean dependency compatibility, hook isolation, and supported Action pins. Latest patch: the v1.19.1 release. Closed scope: milestone 16. Compatibility: compatibility. Registrations delivery: issue 191. Optional read-only lookup moved to issue 203.

Product laws carried through every milestone

Facts are stated once and projected mechanically wherever possible.
Generators establish structure; verifiers prove the generated artifacts as objects rather than trusting command exit status.
A scar becomes an executable invariant, a named proof, or an explicit public contract—not merely a warning in prose.
Valid output and behavior remain compatible within a major release. Changes to typography, layout, or other pinned design contracts wait for a new major.
Book repositories contain book facts. Reusable publishing machinery belongs in press and must work from an installed distribution without a source checkout.
Trust accumulates from deterministic functions through compositions, real tools, complete workflows, consumer repositories, and release identity. A higher layer cannot erase missing proof below it.

The detailed system and artifact invariants live in docs/ARCHITECTURE.md; the public command and artifact surface lives in docs/REFERENCE.md; shipped changes live in CHANGELOG.md.

Long horizon

The v1 milestones strengthen correctness and completeness without changing the rendering contract. v2 — Composable press holds breaking design and extension work such as configurable geometry, themes, and vendor-neutral operator boundaries. Later — Catalog holds the optional multi-book catalog after the single-book publishing contract is mature.

Ideas that are not scheduled remain issues until their dependencies, invariant impact, and release compatibility are understood. A milestone is a delivery claim, not an aspiration bucket.