Roadmap: 12-month delivery plan (Jul 2026 - Jun 2027)

[andres9403]

Single view of what happens when, in what order, and what would make us change
course. Scope lives in the milestones; this issue carries sequence, dependencies,
and decisions.

This issue is expected to change. It is updated at the monthly refinement and
closed at the end of the delivery year.

Who is working on what

Who	Time	Owns
A - @andres9403	90%	Existing backlog (58 issues), refactor review, release, documentation service
B - @Mazhar331	40%	Existing backlog (32 issues), techno-economic scaffold, tests, docs
C - crystallizer developer	100%, from Month 2	Crystallization stream (#153) - parallel workflow
D - bioreactor developer	100%, from Month 2	Bioreactor stream (#152) - parallel workflow

A and B close the existing issues. C and D build new capability in their own
workflows. Month 1 = July 2026, so the year runs to June 2027.

Honest expectation on the backlog

There are 58 issues with a severity label. After the refactor integration and
the release/documentation work are paid for, A and B have roughly 7-15
person-weeks left for defect fixing this year. That closes somewhere around
10-25 of them.

So the year-one commitment is not "close the backlog". It is: the one
critical defect, plus the high-severity defects that block the release or a
demonstrator. Everything else stays visible and carries into next year. Better
to say that now than to discover it in month nine.

Month by month

Months	What lands	Key issues
2 (Aug 2026)	Review queue drained; documentation building under PharmaPy-org; integration contract agreed before C and D start committing	#150, #130, 8 open PRs
3 (Sep)	Tag 1.0.0a1 - installs cleanly, imports without Assimulo, no open critical defect. Refactor decision deadline.	#134, #68, #101, #11, #8
4-5 (Oct-Nov)	Rebased refactor opened as a reviewable PR stack; balance-closure tests written against master before the merge	#148, #149
6-7 (Dec-Jan)	Refactor merged; tag 1.0.0b1	#148, #140, #141, #113
8 (Feb)	Post-merge stabilisation; crystallizer and kinetics defects revalidated	#26, #35, #43, #46, #47
9-10 (Mar-Apr)	Tag 1.0.0 - first maintained release; techno-economic scaffold	#151, #127-#129, #138
11-12 (May-Jun)	Tag 1.1.0 - demonstrator capability from the C and D streams	#153, #152

Version sequence

1.0.0 (this year) -> 2.0.0 (merge the published PharmaPy 2.0 drug-product
work) -> 3.0.0 (digital-twin identity release). The demonstrators ship as
1.1.0 this year because 3.0.0 cannot come before 2.0.0 exists.

Critical path

Drain the review queue -> author rebases the refactor -> gates G5/G7 -> 1.0.0b1
-> demonstrators.

Every link is owned by A. C and D run in parallel but cannot shorten it. The
rebase itself depends on a contributor outside the team, which is the single
biggest schedule risk.

Decisions still open

Decision	Who decides	By when
Scope of the bioreactor demonstrator (#152)	Stakeholders	End of Month 2 - a full-time developer starts without it
How the crystallizer stream overlaps the refactor (#153)	Stakeholders	End of Month 2
Confirm demonstrators ship as 1.1.0	Maintainers	Month 3
A and B time allocation for Months 7-12	Stakeholders	End of Month 6

What would make us change course

• Rebased refactor PR not open by end of Month 3 -> stop waiting; take the useful crystallization commits and plan the architecture ourselves
• Refactor not merged by end of Month 7 -> ship 1.0.0 without it and re-plan
• More than 12 items in progress or in review for two months -> A stops starting new work and only reviews until the queue clears
• Documentation not building under PharmaPy-org by end of Month 3 -> 1.0.0a1 ships and says so plainly in the release notes
• Branch author unavailable for 4 weeks -> trigger the first gate immediately
• A stream branch goes 2 weeks without rebasing, twice -> pause that stream and land what exists first

Related

Milestones: 1.0.0a1, 1.0.0b1, 1.0.0, 1.1.0

Open conflict - version number. #146 records a maintainer decision dated
2026-07-31 that the first PyPI release is 3.0.0, and the release workflow
and tag policy are already built around it. The milestones above use 1.0.0.
These need reconciling before the first tag. No PyPI name reservation will
happen: per #146 the name is rechecked immediately before publication.
Epics: #148, #151, #152, #153 · Supporting: #149, #150
Policy: AGENTS.md (code), and CONTRIBUTING.md / RELEASING.md once #150 lands

[andres9403]

Refactor and version decisions are now open in #148

The three decisions that gate the Months 4-7 part of this roadmap have been
opened for discussion in
#148:

1. Rebase commitment and timeline for MultiPhaseVesselRefactor — needs the
   branch author.
2. MultiPhaseVessel or StateLayout (State vectors rely on memorized positional order across unit operations — introduce a single source of truth (StateLayout) #118) — one must supersede the other;
   Implement StateLayout pack, unpack, and validation infrastructure #142, Migrate evaporator and flash state handling to StateLayout #143, Migrate Drying_Model state handling to StateLayout #144, Migrate remaining unit-operation state handling to StateLayout #145, Units-and-basis correctness strategy: canonical registry, boundary validation, and balance tests (not Pint in the core) #133, Introduce a shared UnitOperation base class and constants module #12 and Decouple the ODE/DAE solver behind an interface (assimulo optional, scipy fallback) #10 are held until it is decided.
3. Version number — Publish PharmaPy 3.0.0 to PyPI as pharmapy-sim #146 records a decision that the first PyPI release is
   3.0.0, and release.yml and the pypi tag policy are built around it,
   while the milestones here are named 1.0.0*. These need reconciling before
   the first tag.

Decision deadline for all three: end of Month 3 (2026-09-30). If the rebase
has not started by then, the fallback is to take the useful crystallization
commits and plan the architecture ourselves.

Correction to this roadmap

The Month 2 row previously said pharmapy-sim would be claimed on PyPI. That
was wrong. Per the decision recorded in #146, no placeholder release will be
published to reserve the name; a pending Trusted Publisher does not reserve it
either, so the name is rechecked immediately before publication. #146 has been
moved to the final release milestone accordingly, and the Month 2 row now reads:

Review queue drained; documentation building under PharmaPy-org; integration
contract agreed before C and D start committing.

Unchanged and still the priority

Month 2 is the review queue. Eight PRs are open, all with passing checks, five
of them more than 14 days old, and #115 is approved and mergeable now. Five of
the eight touch files the refactor rewrites, so landing them before any
rebase avoids making the author redo the work.

[andres9403]

@bernalde — summary of a planning pass done on 2026-07-31, since it touched a lot
of issues at once and you will have seen the notifications.

What was set up

Milestones (there were none). Four created, and 88 of 92 open issues assigned
to one. The four without a milestone are deliberate: #3, #17 and #67 are umbrella
epics, and #16 (scheduling) is deferred beyond this year.

Assignment. Every open issue now has an owner — 31 were unassigned before.
@parkyr's 15 issues were reassigned; their two open PRs (#114, #115) are left for
them to close.

Labels. Six added: refactor:mpv (56 issues that will need revalidating after
the MultiPhaseVessel merge), release-gate, blocked:external, area:release,
stale:review, evidence:source-reviewed. Nothing was deleted or renamed —
status:planned and status:verified are untouched, since migrating them
touches 81 issues and should follow a decision on native issue types.

Metadata gaps closed. #140 and #141 were labelled correctness and
status:verified but had no severity. #127, #128 and #129 had no labels at all;
they are now linked as sub-issues of a new epic. #101 is now a sub-issue of #67.

Project #1. Added In review and Blocked to Status — previously "In
progress" hid both, which is why the three items marked in progress were actually
all sitting in review. Added a Workstream field for the parallel branches.
Removed Size, Iteration and Target date, which had 0, 3 and 0 values set.
Cleared all 58 Priority values: they were an exact mirror of the severity
labels, so the field carried no independent information. Blank now means "needs
triage".

New issues: #148 refactor integration epic, #149 balance regression tests,
#150 integration contract, #151 techno-economic epic, #152 bioreactor epic,
#153 crystallization epic, #154 pinned roadmap.

Tag pushed: archive/mpv-refactor-20260731 at 435971c, preserving the
MultiPhaseVesselRefactor tip before anyone rebases it.

One conflict I created, and did not resolve

The four milestones are named 1.0.0a1 / 1.0.0b1 / 1.0.0 / 1.1.0.

You updated #146 the same day to record that the first PyPI release is 3.0.0,
and release.yml and the pypi environment tag policy are already built around
that. I read #146 earlier in the day, before that rewrite, and did not re-check it
before naming the milestones. That is my error, not a considered disagreement.

The conflict is flagged in #154 and in the discussion on #148 rather than
resolved, because it is your call. If 3.0.0 stands, renaming four milestones is
the only change needed. I also removed "claim pharmapy-sim on PyPI" from the
Month 2 plan and moved #146 to the final release milestone, since your decision
is explicitly not to publish a placeholder.

What needs a decision

Opened for discussion in
#148,
all with an end-of-Month-3 deadline:

1. Rebase commitment and timeline for MultiPhaseVesselRefactor — needs
   @ZacharyHillman18.
2. MultiPhaseVessel or StateLayout (State vectors rely on memorized positional order across unit operations — introduce a single source of truth (StateLayout) #118)? Both solve state ordering. Implement StateLayout pack, unpack, and validation infrastructure #142,
   Migrate evaporator and flash state handling to StateLayout #143, Migrate Drying_Model state handling to StateLayout #144, Migrate remaining unit-operation state handling to StateLayout #145, Units-and-basis correctness strategy: canonical registry, boundary validation, and balance tests (not Pint in the core) #133, Introduce a shared UnitOperation base class and constants module #12 and Decouple the ODE/DAE solver behind an interface (assimulo optional, scipy fallback) #10 are held until this is settled.
3. Version number, per above.

Also open: the scope of the bioreactor demonstrator (#152) and how the
crystallization stream overlaps the refactor (#153).

What is still not done

• Project views and automations — the ProjectV2 API cannot create them, so they
  need the UI. Auto-adding PRs to the Project matters most: the eight open
  PRs are the current bottleneck and are invisible on the board.
• CONTRIBUTING.md and RELEASING.md (Integration contract for parallel development workflows #150) — not written.
• Native issue types are still unset on most issues.
• Discussions are disabled on this repository, which is worth revisiting given
  the conclusion in docs: add planning and release model #147 that coordination belongs there.

The thing worth acting on first

Eight PRs are open, all with passing checks, five more than 14 days old, and
#115 is approved and mergeable now. Five of the eight touch files that
MultiPhaseVesselRefactor rewrites, so landing them before any rebase avoids
making that work happen twice.

[bernalde]

Plan-validation review — 2026-07-31

Deep review of this roadmap against live repository state: milestones, all 93 open issues, labels, assignees, sub-issue links, Project #1 fields and values, the 8 open PRs and their CI rollups, git refs, the refactor branch diff, and release.yml at 0656c7b. Findings are severity-tagged as in a maintainer PR review; there is no verdict to post — everything here is input to the monthly refinement.

Verified

The plan's checkable claims are almost all accurate:

• Milestones 1.0.0a1/1.0.0b1/1.0.0/1.1.0 exist with open-issue split 7/27/45/9 = 88 assigned, matching the summary comment.
• 8 open PRs (Fix semibatch reactor energy flow term #102, Fix crystallizer energy balance units and jacket paths #106, Fix reactor mode crash paths #107, Fix reversible reaction Jacobian #114, Fix BatchCryst concentration Jacobian sign #115, Replace bare except clauses with specific exceptions #126, Publish reproducible PharmaPy documentation #131, Make optional Assimulo imports lazy #135) — every check on every PR is SUCCESS; 5 are >14 days old; Fix BatchCryst concentration Jacobian sign #115 is APPROVED, MERGEABLE, CLEAN. Matches the "drain first" claim and [Epic] Integrate the MultiPhaseVessel architecture #148's sequence list exactly.
• refactor:mpv sits on exactly 56 open issues. Critical: [Crystallizers] Energy balances crash in adiabatic/jacket modes and mix enthalpy bases #68 is the only severity:critical and is in 1.0.0a1, consistent with the a1 gate "no open critical defect".
• Tag archive/mpv-refactor-20260731 exists and points to 435971c, which equals the current MultiPhaseVesselRefactor branch tip.
• G1–G9, the 2026-09-30 decision deadline, and the staged-extraction fallback are all concretely defined in [Epic] Integrate the MultiPhaseVessel architecture #148; "gates G5/G7" in the critical path resolve there.
• Month-3 key issues (Allow solver-free model imports without Assimulo #134, Critical: [Crystallizers] Energy balances crash in adiabatic/jacket modes and mix enthalpy bases #68, High: [Phases] Multi-temperature VaporPhase mass-basis latent heat drops component columns #101, Code hygiene: logging instead of print, bare excepts, hardcoded paths, dead code #11, Modernize packaging and project metadata (pyproject.toml, drop egg-info) #8) plus Month-2's Publish PharmaPy-org documentation and refresh developer attribution #130/Integration contract for parallel development workflows #150 are exactly the 7 open issues in 1.0.0a1; the Months 6–7, 9–10, and 11–12 key issues each sit in the milestone their month implies (one exception — see the Question below).
• Project Implement CI/CD pipeline and enhance testing framework for PharmaPy #1: Status now has In review and Blocked; Workstream exists with master/mpv-refactor/crystallizer/bioreactor; Size/Iteration/Target date are gone. Issues are on the board (93 items); the open PRs are indeed not.
• Document SimExec labor cost assumptions and references #127–Audit SimExec documentation and units #129 are sub-issues of [Epic] Techno-economic reporting scaffold #151; High: [Phases] Multi-temperature VaporPhase mass-basis latent heat drops component columns #101 is a sub-issue of [Epic] Verified runnability and correctness defects from June 2026 audit (#68-#89) #67. Ownership counts match assignee data: @andres9403 59 open issues (58 plus this roadmap), @Mazhar331 32.
• Capacity arithmetic is internally consistent: 7–15 person-weeks closing 10–25 defects implies ~0.5–1.5 weeks per verified defect, which matches the effort visible in the open fix PRs.

Findings

Blocking — the version conflict is wider than "rename four milestones"

The flagged #146 conflict is real, but the recorded remediation scope ("If 3.0.0 stands, renaming four milestones is the only change needed") is wrong. If 3.0.0 stands, at least four more things change:

1. The Version sequence paragraph (1.0.0 → 2.0.0 → 3.0.0) and the stated reason demonstrators ship as 1.1.0 ("3.0.0 cannot come before 2.0.0 exists") contradict Publish PharmaPy 3.0.0 to PyPI as pharmapy-sim #146 directly — Publish PharmaPy 3.0.0 to PyPI as pharmapy-sim #146's own gate list handles v2 provenance by documenting it in the release notes, not by requiring a prior 2.0.0 release. That paragraph needs rewriting, not renaming.
2. release.yml triggers on v[0-9]+.[0-9]+.[0-9]+ and hard-fails unless the tag equals [project].version (currently 0.0.1). Tagging v1.0.0 in Months 9–10 therefore either fails CI or — after a version bump plus pypi environment approval — publishes 1.0.0 to PyPI, violating Publish PharmaPy 3.0.0 to PyPI as pharmapy-sim #146's "the first intended PyPI release is 3.0.0". The roadmap never says which of its four tags are git-only and which imply a PyPI release; each month row that says "Tag X" should say which it is.
3. Pre-release tags (v1.0.0a1, v1.0.0b1) do not match that workflow pattern — safe, but by accident of the regex. Record it as intended behavior, and pick the tag spelling explicitly (repo history contains the irregular v.1.0.0).
4. Publish PharmaPy 3.0.0 to PyPI as pharmapy-sim #146 — the issue titled "Publish PharmaPy 3.0.0" — currently sits inside the milestone named 1.0.0, so the conflict is embedded in the tracker itself, not only in prose.

Suggested fix: when the Month-3 decision lands, update the Version sequence section here, annotate each roadmap tag as git-only or PyPI, reconcile milestone names, and re-home #146.

Blocking — 1.0.0a1 milestone description still instructs the retracted PyPI claim

The milestone description reads "… documentation reproducible and published under PharmaPy-org; pharmapy-sim claimed on PyPI; no open severity:critical defect." That contradicts the decision recorded in #146 (no placeholder release) and this issue's own correction — anyone executing the milestone as written performs the retracted step. The same edit should reconcile the docs gate with the Month-3 tripwire ("1.0.0a1 ships and says so plainly in the release notes"): as written the tripwire allows shipping a1 without published docs while the milestone description makes them a hard gate. Fix: edit the milestone description now — drop the PyPI claim, and mark the docs gate as waivable-with-disclosure per the tripwire.

Question — 1.0.0b1 tag timing vs milestone membership

Months 6–7 tag 1.0.0b1, but Month 8's revalidation issues #26, #35, #46, #47 are all in the 1.0.0b1 milestone (while #43 in the same row is in 1.0.0). Either the tag waits for post-merge stabilization — matching G9's own ordering, "full suite green; 1.0.0b1 tagged" — or those four issues belong in the 1.0.0 milestone. Which is intended? As written, the b1 tag ships with open b1-milestone defects by design.

Nonblocking — no fallback for the reassigned PRs (#114/#115)

"Review queue drained" by end of Month 2 depends partly on @parkyr: #115 is approved and only needs a maintainer merge, but #114 has CHANGES_REQUESTED and is left "for them to close". The tripwire list covers the refactor author's unavailability but not this. Suggested tripwire in the existing style: "A reassigned PR gets no author response for 2 weeks → a maintainer completes it on a follow-up branch, preserving authorship."

Nonblocking — "five of the eight touch files the refactor rewrites" is an undercount: it is eight of eight

Against merge-base d6eaf85, the refactor branch changes 25 files, including Reactors.py, Crystallizers.py, Kinetics.py, MixedPhases.py, ThermoModule.py, and Drying_Model.py. Every one of the 8 open PRs touches at least one of these: #102/#107 (Reactors), #106 (Crystallizers, MixedPhases), #114 (Kinetics, Reactors), #115 (Crystallizers), #126 (Crystallizers, ThermoModule), #131 (Kinetics, Reactors), #135 (Crystallizers, Drying_Model, Reactors). This strengthens the drain-first argument; update the sentence here and in the summary comment.

Nonblocking — stale counts in the body

• "58 issues with a severity label" → now 60: the same planning pass added severity to Bug: Drying.solve_unit initialization can omit temp_cond #140/Bug: DynamicCollector states_di order disagrees with packed state order #141 (as the summary comment records) but the body count was not updated. The 7–15 person-week / 10–25 closure arithmetic is unaffected at this precision.
• "Cleared all 58 Priority values" → one survivor: SNV PCR prediction returns NaN for a single new spectrum #138 still carries Priority = Medium on Project Implement CI/CD pipeline and enhance testing framework for PharmaPy #1.
• The summary comment's "four issues without a milestone (deliberate)" is now five — Roadmap: 12-month delivery plan (Jul 2026 - Jun 2027) #154 itself has none. Fine if deliberate (it closes at year end); worth saying so.

Nonblocking — set milestone due dates

All four milestones have due_on unset while this roadmap commits to specific months. Setting them (a1: 2026-09-30, b1: 2027-01-31, 1.0.0: 2027-04-30, 1.1.0: 2027-06-30) makes slippage visible in GitHub's own milestone UI at zero ongoing cost.

Nonblocking — make gate shorthand and thresholds self-contained

"Gates G5/G7" appear in the critical path with no expansion; a parenthetical ("G5 scientific regression evidence, G7 fix preservation") keeps the pinned roadmap readable without a hop to #148. Similarly, the WIP tripwire's threshold of 12 in-progress/in-review items is an undocumented constant — for a ~1.3-FTE core team it is generous; label it an assumption (or tie it to per-person WIP) so the monthly refinement can adjust it deliberately rather than treat it as calibrated.

Assessment

The structure is sound and unusually honest for a roadmap: the backlog expectation is quantified rather than aspirational, the critical path correctly identifies its single-threaded owner, every tripwire has a trigger and a consequence, and the #148 fallback is concrete enough to execute. Nearly every factual claim survived verification against live state. The two Blocking items both orbit the version-number conflict the plan already flags — the issue is that the recorded remediation ("rename four milestones") would leave the roadmap internally inconsistent and the release automation pointed at the wrong outcome. Both are cheap to fix and should land before the Month-3 tag decision.

Checks run: milestone/issue/label/assignee/sub-issue queries and CI rollups for all 8 open PRs via gh; Project #1 field inventory and full Priority sweep via GraphQL; tag/branch ref verification via git ls-remote; refactor diff computed against merge-base d6eaf85; release.yml trigger and tag-version gate read at 0656c7b. No claims taken on trust.