From d82c9b1e48aed815854b510acce54ba42dc29345 Mon Sep 17 00:00:00 2001 From: "David E. Bernal Neira" Date: Tue, 28 Jul 2026 00:20:49 -0400 Subject: [PATCH 1/5] docs: add planning and release-model proposal (draft) A single version-controlled source for how PharmaPy-org/PharmaPy plans work and cuts releases: operating model, release-risk policy, the first milestone (0.1.0a1) with scope mapped to open PRs, Project changes, and a lazy-consensus decision log. Draft for discussion; adopts nothing until merged. --- PLANNING.md | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 PLANNING.md diff --git a/PLANNING.md b/PLANNING.md new file mode 100644 index 0000000..fa21363 --- /dev/null +++ b/PLANNING.md @@ -0,0 +1,275 @@ +# PharmaPy Planning and Release Model + +> **Status: DRAFT PROPOSAL — under discussion in this pull request. Not yet adopted.** +> +> This document is the single, version-controlled source for how the +> `PharmaPy-org/PharmaPy` repository plans work and cuts releases. It exists so +> the team can (1) agree on an operating model, (2) generate the GitHub +> milestone, Project views, and release notes *from* a reviewed source rather +> than ad hoc, and (3) verify our own process against an explicit checklist. +> +> Nothing here is policy until this PR is merged. Review it like code: comment +> on the lines you disagree with. Decisions to ratify are collected in +> [§7 Decision log](#7-decision-log). + +## Table of contents + +1. [Purpose and how to use this document](#1-purpose-and-how-to-use-this-document) +2. [Verified snapshot (2026-07-27)](#2-verified-snapshot-2026-07-27) +3. [Operating model](#3-operating-model) +4. [Release-risk policy](#4-release-risk-policy) +5. [First milestone: `0.1.0a1`](#5-first-milestone-010a1) +6. [Project (#1) changes](#6-project-1-changes) +7. [Decision log](#7-decision-log) +8. [Open questions for maintainers](#8-open-questions-for-maintainers) +9. [Adoption: how these sections graduate](#9-adoption-how-these-sections-graduate) + +--- + +## 1. Purpose and how to use this document + +This is a *planning* document, not user-facing docs. Three concrete uses: + +- **Verification.** §4–§5 define what "ready to release" means. Before we tag, + we walk the exit-criteria checklist and it must pass. +- **Generation.** §5 is written to be pasted into a GitHub **milestone** + description; §6 lists the exact Project view filters to create; §4 is the + rule we encode into release notes. +- **Discussion.** The team ratifies the open decisions in §7 by lazy consensus + (propose a default, set an objection window, silence = assent). + +**Guiding principle:** this is a 4–5 person, asynchronous, academic team whose +real delivery already flows through continuous PR merges. The model below +formalizes *that*, and deliberately avoids ceremony (sprints, mandatory +estimates, blocking committee gates) that a team this size will not sustain. + +**This document does not freeze other work.** PRs continue to merge normally +while this is discussed. The only thing gated on the outcome here is +*publishing a tag* — see §4 and §7. + +## 2. Verified snapshot (2026-07-27) + +Queried read-only from GitHub on 2026-07-27. **Time-sensitive** — re-verify +before acting on any count. + +- 85 open issues; **no milestones, no releases, no Git tags**; `pyproject.toml` + declares `version = "0.0.1"`. +- Labels on open issues: 62 `correctness`, 60 `status:verified`, + 1 `severity:critical`, 34 `severity:high`, 20 `severity:medium`, + 3 `severity:low`. Severity labels cover 58 of the 62 correctness issues + (4 correctness issues carry no severity), and every severity-labelled issue + is a correctness issue. +- The single `severity:critical` is **#68** (adiabatic crystallizer + energy-balance crash). +- Org **Project #1 "PharmaPy Development"** was created 2026-07-21. Its + `Priority` values are a mechanical copy of `Severity` (34 High / 20 Medium / + 3 Low / 1 Urgent — identical distribution), the `Size` field is unused + (0 of 85 items populated), and only #23, #26, #134 sit in any iteration. +- CI (`.github/workflows/ci.yml`) tests **Python 3.11 only**, while + `requires-python = ">=3.9"`. The Assimulo integration job is + `continue-on-error` (non-blocking). `master` CI is green. +- The codebase dates to 2021 and is published (DOI + `10.1016/j.compchemeng.2021.107408`); `0.0.1` is a placeholder, not release + history. + +## 3. Operating model + +One Project, milestone-anchored, continuous flow. Each GitHub concept has +exactly one meaning: + +| Concept | Meaning in this repo | +| --- | --- | +| **Project #1** | The single source of truth: full backlog, active board, and roadmap. We do **not** create a Project per release or subsystem. | +| **Status** | Workflow state only: `Todo` → `In progress` → `Done`. Delivery is controlled by a **work-in-progress (WIP) limit** on `In progress` (proposed: ≤ 6), not by sprints. | +| **Milestone** | A repository release (or a concrete, externally meaningful outcome). **Exactly one open at a time.** This is the primary planning horizon. | +| **Epic + sub-issues** | Decomposition of a large initiative, using native issue-type `Epic` and parent/sub-issue links. Current epics: #3, #17, #67, #118. This is the roadmap's backbone. | +| **Priority** | Maintainer delivery order — **re-triaged independently of severity** (see §7 D4). Until re-triaged it is unreliable and is kept out of delivery views. | +| **Severity** (label) | Technical impact of a *defect* only. Does not imply delivery order. | +| **Area** (label) | Affected subsystem. Useful for filtering; not a planning input. | +| **Assignee** | The one person accountable for the item. No duplicate "owner" field. | +| **Target date** | Only for a genuinely externally-dated deliverable. Not a general field. | +| **Iteration** | **Not used as a commitment unit.** (See §7 D3.) Removing it also removes the three-way conflict between iteration dates, `Target date`, and the milestone due date. | +| **Size** | **Not required.** Optional, and only populated for the ~8–10 near-term items if the team finds it useful. (See §7 D5.) | + +Rationale for dropping sprints: the iteration apparatus is 6 days old, its first +"iteration" was backdated and held zero items, and the current board contains +work outside the release while omitting the release's own critical blocker. The +team's actual, working coordination mechanism is per-PR "whoever lands second, +rebase" notes — continuous flow. We formalize that. + +## 4. Release-risk policy + +The correctness backlog is large (62 issues). Blocking a release on all of it +is neither achievable nor necessary. The rule: + +- **`severity:critical` → hard blocker.** No release ships with an open + critical. Each critical must be closed **with a regression test**. *(Today: + only #68, fixed by PR #106, which adds regression coverage for its four + sub-defects.)* +- **`severity:high` → not individually blocking, with a promotion rule.** A high + is *promoted* to a blocker if it either (a) produces a **silent wrong + numerical result in a documented example/tutorial**, or (b) affects a module + exercised by the release **smoke/validation suite**. All non-promoted highs + are **disclosed by number in the release notes**. +- **The gate is behavioral, not lexical.** "No open `severity:critical`" is + necessary but insufficient, because severity labels do not cover every + correctness issue. Release also requires the smoke/numerical suite green + (§5 exit criteria). +- **A named release manager decides promotions**, recorded on the milestone. + +## 5. First milestone: `0.1.0a1` + +> The block below is written to be pasted into the GitHub milestone +> description once §7 D1/D2 are ratified. + +**Milestone title:** `Org transition: installable, documented, CI-verified` +**Release version (Git tag / `pyproject`):** `0.1.0a1` *(alpha — proposed, see §7 D1)* + +**Goal.** Produce the first `PharmaPy-org`-maintained release: the package +installs and its core modules import in a clean, supported environment; core CI +and documentation are reproducible and public; the one critical defect is fixed; +release notes state the remaining known correctness limitations. This is +explicitly an **alpha** — it does not claim numerical production-validation. + +### Scope (in) — mapped to open PRs/issues + +| Issue | Delivered by | Role | +| --- | --- | --- | +| #68 | PR **#106** | The critical crystallizer crash + enthalpy basis (hard gate). | +| #134 | PR **#135** | Solver-free model imports (lazy Assimulo). | +| #130 | PR **#131** | Reproducible, public documentation (tracked as the outcome; #131 is one step and intentionally does not close #130). | +| packaging / clean install | PR **#136** | `pharmapy-sim` distribution, pixi environments, install guide, two-platform locked install matrix. Recheck the distribution name before publishing (#146). | +| #8 | (fold into #136) | Packaging/metadata modernization — de-duplicate against #136 rather than tracking twice. | + +### Scope (out) + +- #7 in its broad form (split out a release-specific smoke/validation issue — + see §8 Q1). +- #10, the full solver-abstraction initiative. +- All 62 correctness issues as a single release gate. +- Epic #118 and the complete StateLayout migration. +- Speculative bioreactor, crystallizer-extension, and scheduling initiatives. +- #23 (PR #114) and #26 (PR #115): **in flight, not release scope** unless the + owner confirms they are intended to ship here (§7 D6). "Work has started" is + not by itself a reason to include them. + +### Entry criteria + +- [ ] Every in-scope issue has an owner. +- [ ] #68 has a reproduction and a failing-first regression test. +- [ ] Version scheme (§7 D1) and distribution name (§7 D2) ratified. + +### Exit criteria + +- [ ] Supported Python versions and the dependency policy are explicit, and **CI + tests exactly what is claimed** (either expand CI beyond 3.11 or narrow + `requires-python` to `>=3.11`). +- [ ] A clean environment installs the package (pip and pixi), verified by a + smoke-install/import job. +- [ ] Core modules import **without Assimulo**; a solver path without Assimulo + fails with a clear, localized message (asserted by a test). +- [ ] Core CI and documentation CI are green; the public docs site and + pull-request previews are verified (#130). +- [ ] **#68 is closed with a regression test**, and the smoke/validation suite + is green. +- [ ] No open defect is labelled `severity:critical`. +- [ ] Release notes enumerate the open `severity:high` correctness issues by + number and make no production-validation claim. + +### Due-date policy + +No due date until the in-scope issues have owners, rough sizes, and an agreed +capacity forecast. Once set, the milestone date is a forecast, not a substitute +for issue-level `Target date`. + +### Milestone hygiene + +Put planned **issues** in the milestone. Do **not** add both an issue and its +linked PR (double-counts progress). Add a PR to the milestone only when the PR +is itself the tracked deliverable with no corresponding issue. + +## 6. Project (#1) changes + +**Views** (create/keep exactly these; remove the rest): + +| View | Layout | Filter | +| --- | --- | --- | +| Backlog | Table | `is:open` | +| Board | Board (by Status) | `is:open` — enforce the WIP limit on `In progress` | +| Release: 0.1.0a1 | Table | `milestone:"Org transition: installable, documented, CI-verified"` | +| Correctness defects | Table | `label:correctness` sorted by severity | +| Unassigned high-priority | Table | `no:assignee (label:severity:critical OR label:severity:high)` | +| Roadmap | Roadmap | `type:Epic` (not all 85 items) | + +Remove the `Current iteration` view (no iterations). + +**Fields:** retire `Iteration` and `Size` from the model; keep Status, Priority +(re-triaged), Severity/Area (labels), Milestone, Assignee, and a sparingly-used +`Target date`. + +**Automations:** keep auto-add of open issues and archive-on-close; add +auto-set `Status: Done` when the closing PR merges. Stop mirroring Severity into +Priority. + +**Immediate data fixes** (independent of the decisions): + +- [ ] Put #68 into active focus — it is the only hard release blocker. +- [ ] Assign #134, or return it from `In progress` to `Todo`. + +## 7. Decision log + +Ratify by lazy consensus. Proposed **objection window: one week from merge of +this PR**; silence = assent. Owner makes the call if consensus is unclear. + +| # | Decision | Proposed default | Reversible? | Owner | +| --- | --- | --- | --- | --- | +| **D1** | First release version | `0.1.0a1` (alpha) | Hard once tagged/DOI'd | maintainer | +| **D2** | Distribution name on the index | `pharmapy-sim` (recheck at publish, #146) | Hard once published | maintainer | +| **D3** | Timeboxed iterations | **Drop**; use WIP-limited continuous flow | Yes | team | +| **D4** | Priority model | Re-triage independently of severity (or collapse to `Now/Next/Later`) | Yes | maintainer | +| **D5** | `Size` field | Not required; optional for near-term items only | Yes | team | +| **D6** | #23/#26 in this release? | No unless the owner confirms they ship here | Yes | issue owner | +| **D7** | Release manager | Name one person; they decide high→blocker promotions | Yes | org | + +**Version comparison for D1:** + +- `0.0.2` — too timid; perpetuates the misleading `0.0.1` lineage and understates + a deliberate first org release. +- `0.1.0` — honest about the capability step, but reads as a stable feature + baseline, which 34 open high-severity correctness defects contradict. +- **`0.1.0a1`** *(proposed)* — signals "this is the target shape; correctness + work continues," and allows a1 → … → rc1 → 0.1.0 as the backlog burns down. +- A non-versioned milestone name is used regardless (above); the *tag* still + needs a number, so pair it with `0.1.0a1`. + +## 8. Open questions for maintainers + +These need a human decision; do not invent answers. + +1. **Smoke/validation suite.** What is the minimal numerical/smoke suite whose + green state gates the release? Should #7 be split into a release-specific + testing issue? +2. **Supported matrix.** Honor `>=3.9` (and test it in CI) or narrow to + `>=3.11`? +3. **Citable release.** Given the 2021 paper and DOI, do we want a + `CITATION.cff` + Zenodo archive for the eventual `0.1.0`? (Not required for + the alpha.) +4. **Safety/validation bar.** Do any users consume PharmaPy numerical output for + real process decisions? If so, the acceptable correctness bar may exceed "no + open critical," and the release-notes disclaimer must reflect it. +5. **Release cadence after 0.1.0.** Patch milestones (`0.1.x`) for bounded + correctness fixes; a later minor for meaningful API/architecture change. No + future milestones created until their scope is credible. + +## 9. Adoption: how these sections graduate + +On merge, this document becomes the reference. As decisions are ratified: + +- §4 (release-risk policy) and §5 due-date/hygiene → the durable content of a + future `RELEASING.md`. +- §3 (operating model) → the basis of `CONTRIBUTING.md` / the Project README. +- §5 (milestone block) → pasted into the created GitHub milestone. +- §6 → applied to Project #1. + +This file stays as the living planning record; the generated artifacts +(milestone, views, `RELEASING.md`) are downstream of it. From 257964148b3486c31f99da6d79449528b4e6a441 Mon Sep 17 00:00:00 2001 From: "David E. Bernal Neira" Date: Tue, 28 Jul 2026 12:03:02 -0400 Subject: [PATCH 2/5] docs: make PLANNING.md finalize-first (release PRs still flow) --- PLANNING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/PLANNING.md b/PLANNING.md index fa21363..f2ae62c 100644 --- a/PLANNING.md +++ b/PLANNING.md @@ -43,9 +43,13 @@ real delivery already flows through continuous PR merges. The model below formalizes *that*, and deliberately avoids ceremony (sprints, mandatory estimates, blocking committee gates) that a team this size will not sustain. -**This document does not freeze other work.** PRs continue to merge normally -while this is discussed. The only thing gated on the outcome here is -*publishing a tag* — see §4 and §7. +**Finalizing this document is the team's current top priority.** While it is +under discussion (proposed one-week objection window, §7), please **hold new or +unrelated pull requests** and do **not** cut the release tag until the model is +adopted. The in-flight release PRs this milestone already depends on — #106 +(fixes the critical #68), #135, #136, and #131 — should continue to merge, and +existing in-flight fixes may land at the owner's discretion; freezing the +release PRs would freeze the plan's own exit criteria (§5). See §4 and §7. ## 2. Verified snapshot (2026-07-27) From cb2c963e40421164485aab3bcf535c6510a71bec Mon Sep 17 00:00:00 2001 From: "David E. Bernal Neira" Date: Wed, 29 Jul 2026 09:59:19 -0400 Subject: [PATCH 3/5] docs: make planning policy durable --- PLANNING.md | 142 +++++++++++++++++++++++++++++----------------------- 1 file changed, 78 insertions(+), 64 deletions(-) diff --git a/PLANNING.md b/PLANNING.md index f2ae62c..9b983a9 100644 --- a/PLANNING.md +++ b/PLANNING.md @@ -1,6 +1,6 @@ # PharmaPy Planning and Release Model -> **Status: DRAFT PROPOSAL — under discussion in this pull request. Not yet adopted.** +> **Status:** Repository policy when present on the default branch. > > This document is the single, version-controlled source for how the > `PharmaPy-org/PharmaPy` repository plans work and cuts releases. It exists so @@ -8,14 +8,15 @@ > milestone, Project views, and release notes *from* a reviewed source rather > than ad hoc, and (3) verify our own process against an explicit checklist. > -> Nothing here is policy until this PR is merged. Review it like code: comment -> on the lines you disagree with. Decisions to ratify are collected in -> [§7 Decision log](#7-decision-log). +> Its authority is limited to planning, prioritization, and releases. Coding +> and verification rules belong in `AGENTS.md` if that file is adopted (see +> [§9](#9-adoption-how-these-sections-graduate)). Revisions to either policy +> document go through normal pull-request review. ## Table of contents 1. [Purpose and how to use this document](#1-purpose-and-how-to-use-this-document) -2. [Verified snapshot (2026-07-27)](#2-verified-snapshot-2026-07-27) +2. [Verified snapshot (2026-07-29)](#2-verified-snapshot-2026-07-29) 3. [Operating model](#3-operating-model) 4. [Release-risk policy](#4-release-risk-policy) 5. [First milestone: `0.1.0a1`](#5-first-milestone-010a1) @@ -35,28 +36,22 @@ This is a *planning* document, not user-facing docs. Three concrete uses: - **Generation.** §5 is written to be pasted into a GitHub **milestone** description; §6 lists the exact Project view filters to create; §4 is the rule we encode into release notes. -- **Discussion.** The team ratifies the open decisions in §7 by lazy consensus - (propose a default, set an objection window, silence = assent). +- **Discussion.** The team ratifies and revises decisions in §7 by lazy + consensus (propose a default, set an objection window, silence = assent). -**Guiding principle:** this is a 4–5 person, asynchronous, academic team whose -real delivery already flows through continuous PR merges. The model below -formalizes *that*, and deliberately avoids ceremony (sprints, mandatory -estimates, blocking committee gates) that a team this size will not sustain. +**Guiding principle:** this is a small, asynchronous, academic team whose real +delivery already flows through continuous PR merges. The model below formalizes +*that*, and deliberately avoids ceremony (sprints, mandatory estimates, +blocking committee gates) that the team will not sustain. -**Finalizing this document is the team's current top priority.** While it is -under discussion (proposed one-week objection window, §7), please **hold new or -unrelated pull requests** and do **not** cut the release tag until the model is -adopted. The in-flight release PRs this milestone already depends on — #106 -(fixes the critical #68), #135, #136, and #131 — should continue to merge, and -existing in-flight fixes may land at the owner's discretion; freezing the -release PRs would freeze the plan's own exit criteria (§5). See §4 and §7. +## 2. Verified snapshot (2026-07-29) -## 2. Verified snapshot (2026-07-27) +Queried read-only through the GitHub REST and GraphQL APIs at +**2026-07-29T13:54:25Z**. **Time-sensitive** — re-verify before acting on any +count. Re-running the Project claims requires organization access and a token +with the `read:project` scope. -Queried read-only from GitHub on 2026-07-27. **Time-sensitive** — re-verify -before acting on any count. - -- 85 open issues; **no milestones, no releases, no Git tags**; `pyproject.toml` +- 86 open issues; **no milestones, no releases, no Git tags**; `pyproject.toml` declares `version = "0.0.1"`. - Labels on open issues: 62 `correctness`, 60 `status:verified`, 1 `severity:critical`, 34 `severity:high`, 20 `severity:medium`, @@ -65,13 +60,14 @@ before acting on any count. is a correctness issue. - The single `severity:critical` is **#68** (adiabatic crystallizer energy-balance crash). -- Org **Project #1 "PharmaPy Development"** was created 2026-07-21. Its +- Org **Project #1 "PharmaPy Development"** was created 2026-07-21 and contains + 85 items. Its `Priority` values are a mechanical copy of `Severity` (34 High / 20 Medium / 3 Low / 1 Urgent — identical distribution), the `Size` field is unused (0 of 85 items populated), and only #23, #26, #134 sit in any iteration. -- CI (`.github/workflows/ci.yml`) tests **Python 3.11 only**, while - `requires-python = ">=3.9"`. The Assimulo integration job is - `continue-on-error` (non-blocking). `master` CI is green. +- CI (`.github/workflows/ci.yml`) runs core tests on **Python 3.11 only**, while + `requires-python = ">=3.9"`. Locked pixi installs gate Linux and Windows; the + Assimulo integration job is `continue-on-error` (informational). - The codebase dates to 2021 and is published (DOI `10.1016/j.compchemeng.2021.107408`); `0.0.1` is a placeholder, not release history. @@ -84,8 +80,8 @@ exactly one meaning: | Concept | Meaning in this repo | | --- | --- | | **Project #1** | The single source of truth: full backlog, active board, and roadmap. We do **not** create a Project per release or subsystem. | -| **Status** | Workflow state only: `Todo` → `In progress` → `Done`. Delivery is controlled by a **work-in-progress (WIP) limit** on `In progress` (proposed: ≤ 6), not by sprints. | -| **Milestone** | A repository release (or a concrete, externally meaningful outcome). **Exactly one open at a time.** This is the primary planning horizon. | +| **Status** | Workflow state only: `Todo` → `In progress` → `Done`. Delivery is controlled by a **work-in-progress (WIP) limit** on `In progress`, not by sprints. Set the cap when a milestone opens using **one active item per active contributor plus one shared review/unblocking slot**; the formula keeps the limit tied to actual team capacity instead of a magic number. | +| **Milestone** | A repository release (or a concrete, externally meaningful outcome). **Exactly one open at a time** because the Project roadmap already holds longer-horizon work; a second open milestone would create a competing release gate. | | **Epic + sub-issues** | Decomposition of a large initiative, using native issue-type `Epic` and parent/sub-issue links. Current epics: #3, #17, #67, #118. This is the roadmap's backbone. | | **Priority** | Maintainer delivery order — **re-triaged independently of severity** (see §7 D4). Until re-triaged it is unreliable and is kept out of delivery views. | | **Severity** (label) | Technical impact of a *defect* only. Does not imply delivery order. | @@ -93,18 +89,19 @@ exactly one meaning: | **Assignee** | The one person accountable for the item. No duplicate "owner" field. | | **Target date** | Only for a genuinely externally-dated deliverable. Not a general field. | | **Iteration** | **Not used as a commitment unit.** (See §7 D3.) Removing it also removes the three-way conflict between iteration dates, `Target date`, and the milestone due date. | -| **Size** | **Not required.** Optional, and only populated for the ~8–10 near-term items if the team finds it useful. (See §7 D5.) | +| **Size** | **Not required.** Optional, and only populated for current-milestone items if the team finds it useful. (See §7 D5.) | -Rationale for dropping sprints: the iteration apparatus is 6 days old, its first -"iteration" was backdated and held zero items, and the current board contains -work outside the release while omitting the release's own critical blocker. The -team's actual, working coordination mechanism is per-PR "whoever lands second, -rebase" notes — continuous flow. We formalize that. +Rationale for dropping sprints: the iteration apparatus was created on +2026-07-21 (the Project creation date in §2), its first "iteration" was backdated +and held zero items, and the current board contains work outside the release +while omitting the release's own critical blocker. The team's actual, working +coordination mechanism is per-PR "whoever lands second, rebase" notes — +continuous flow. We formalize that. ## 4. Release-risk policy -The correctness backlog is large (62 issues). Blocking a release on all of it -is neither achievable nor necessary. The rule: +The correctness backlog was 62 issues at the §2 snapshot. Blocking a release on +all of it is neither achievable nor necessary. The rule: - **`severity:critical` → hard blocker.** No release ships with an open critical. Each critical must be closed **with a regression test**. *(Today: @@ -135,22 +132,25 @@ and documentation are reproducible and public; the one critical defect is fixed; release notes state the remaining known correctness limitations. This is explicitly an **alpha** — it does not claim numerical production-validation. -### Scope (in) — mapped to open PRs/issues +### Scope (in) — mapped to tracked issues + +Implementation status is a dated snapshot from **2026-07-29T13:54:25Z**; the +issues remain the durable scope records and must be re-queried before copying +this table into a milestone. -| Issue | Delivered by | Role | +| Issue | Implementation status at snapshot | Role | | --- | --- | --- | -| #68 | PR **#106** | The critical crystallizer crash + enthalpy basis (hard gate). | -| #134 | PR **#135** | Solver-free model imports (lazy Assimulo). | -| #130 | PR **#131** | Reproducible, public documentation (tracked as the outcome; #131 is one step and intentionally does not close #130). | -| packaging / clean install | PR **#136** | `pharmapy-sim` distribution, pixi environments, install guide, two-platform locked install matrix. Recheck the distribution name before publishing (#146). | -| #8 | (fold into #136) | Packaging/metadata modernization — de-duplicate against #136 rather than tracking twice. | +| #68 | PR **#106** open | The critical crystallizer crash + enthalpy basis (hard gate). | +| #134 | PR **#135** open | Solver-free model imports (lazy Assimulo). | +| #130 | PR **#131** open | Reproducible, public documentation (#131 is one step and intentionally does not close #130). | +| #8 | PR **#136** merged | Packaging/metadata modernization, `pharmapy-sim` distribution, pixi environments, install guide, and two-platform locked install matrix. Remaining #8 scope stays on the issue; distribution-name reservation is tracked by #146. | ### Scope (out) - #7 in its broad form (split out a release-specific smoke/validation issue — see §8 Q1). - #10, the full solver-abstraction initiative. -- All 62 correctness issues as a single release gate. +- Every correctness issue counted in §2 as a single release gate. - Epic #118 and the complete StateLayout migration. - Speculative bioreactor, crystallizer-extension, and scheduling initiatives. - #23 (PR #114) and #26 (PR #115): **in flight, not release scope** unless the @@ -165,11 +165,14 @@ explicitly an **alpha** — it does not claim numerical production-validation. ### Exit criteria -- [ ] Supported Python versions and the dependency policy are explicit, and **CI - tests exactly what is claimed** (either expand CI beyond 3.11 or narrow - `requires-python` to `>=3.11`). -- [ ] A clean environment installs the package (pip and pixi), verified by a - smoke-install/import job. +- [ ] Supported Python versions are explicit and **CI tests exactly what is + claimed** (either expand CI beyond 3.11 or narrow `requires-python` to + `>=3.11`). Dependency bounds and environment policy remain sourced in + [`DEPENDENCIES.md`](DEPENDENCIES.md). +- [x] A clean environment installs the package through the documented pip and + locked pixi paths. PR #136 added the Linux/Windows smoke-install jobs and + [`INSTALLATION.md`](INSTALLATION.md); commands and lane semantics are + sourced in [`TESTING.md`](TESTING.md). - [ ] Core modules import **without Assimulo**; a solver path without Assimulo fails with a clear, localized message (asserted by a test). - [ ] Core CI and documentation CI are green; the public docs site and @@ -182,9 +185,9 @@ explicitly an **alpha** — it does not claim numerical production-validation. ### Due-date policy -No due date until the in-scope issues have owners, rough sizes, and an agreed -capacity forecast. Once set, the milestone date is a forecast, not a substitute -for issue-level `Target date`. +No due date until the in-scope issues have owners and an agreed capacity +forecast. Once set, the milestone date is a forecast, not a substitute for +issue-level `Target date`. ### Milestone hygiene @@ -203,7 +206,7 @@ is itself the tracked deliverable with no corresponding issue. | Release: 0.1.0a1 | Table | `milestone:"Org transition: installable, documented, CI-verified"` | | Correctness defects | Table | `label:correctness` sorted by severity | | Unassigned high-priority | Table | `no:assignee (label:severity:critical OR label:severity:high)` | -| Roadmap | Roadmap | `type:Epic` (not all 85 items) | +| Roadmap | Roadmap | `type:Epic` (not every Project item) | Remove the `Current iteration` view (no iterations). @@ -215,15 +218,18 @@ Remove the `Current iteration` view (no iterations). auto-set `Status: Done` when the closing PR merges. Stop mirroring Severity into Priority. -**Immediate data fixes** (independent of the decisions): - -- [ ] Put #68 into active focus — it is the only hard release blocker. -- [ ] Assign #134, or return it from `In progress` to `Todo`. +Operational follow-ups are recorded on their owning issues rather than as +one-shot checkboxes here: #68 owns hard-blocker status, while #134 owns its +assignee and Project status. ## 7. Decision log -Ratify by lazy consensus. Proposed **objection window: one week from merge of -this PR**; silence = assent. Owner makes the call if consensus is unclear. +Ratify by lazy consensus. Each ratification announcement names its proposed +default and exact start/end timestamps for a **one-week objection window**; +silence = assent. One week is used because it spans a full workweek for +asynchronous contributors. The announcement belongs in the relevant pull +request or tracking issue, not as a transient deadline in this file. The owner +makes the call if consensus is unclear. | # | Decision | Proposed default | Reversible? | Owner | | --- | --- | --- | --- | --- | @@ -233,7 +239,7 @@ this PR**; silence = assent. Owner makes the call if consensus is unclear. | **D4** | Priority model | Re-triage independently of severity (or collapse to `Now/Next/Later`) | Yes | maintainer | | **D5** | `Size` field | Not required; optional for near-term items only | Yes | team | | **D6** | #23/#26 in this release? | No unless the owner confirms they ship here | Yes | issue owner | -| **D7** | Release manager | Name one person; they decide high→blocker promotions | Yes | org | +| **D7** | Release manager | The maintainer who creates the milestone acts as release manager unless the milestone names another volunteer | Yes | maintainer | **Version comparison for D1:** @@ -250,8 +256,10 @@ this PR**; silence = assent. Owner makes the call if consensus is unclear. These need a human decision; do not invent answers. -1. **Smoke/validation suite.** What is the minimal numerical/smoke suite whose - green state gates the release? Should #7 be split into a release-specific +1. **Smoke/validation suite.** [`TESTING.md`](TESTING.md) already defines the + core pytest lane, locked pixi install matrix, and informational Assimulo + lane. Which of those existing lanes gate the release, and what numerical + assertions must be added on top? Should #7 be split into a release-specific testing issue? 2. **Supported matrix.** Honor `>=3.9` (and test it in CI) or narrow to `>=3.11`? @@ -271,9 +279,15 @@ On merge, this document becomes the reference. As decisions are ratified: - §4 (release-risk policy) and §5 due-date/hygiene → the durable content of a future `RELEASING.md`. -- §3 (operating model) → the basis of `CONTRIBUTING.md` / the Project README. +- §3 (operating model) → the planning half of a future `CONTRIBUTING.md` / the + Project README. - §5 (milestone block) → pasted into the created GitHub milestone. - §6 → applied to Project #1. +The authority split with PR #132 is deliberate: `PLANNING.md` owns work +planning, prioritization, and releases; the proposed `AGENTS.md` owns coding and +verification rules. A future contributor-facing `CONTRIBUTING.md` should +summarize and point to both rather than duplicate either. + This file stays as the living planning record; the generated artifacts (milestone, views, `RELEASING.md`) are downstream of it. From 488ded5a80edf011d91ac783aed74c7d88888f16 Mon Sep 17 00:00:00 2001 From: "David E. Bernal Neira" Date: Wed, 29 Jul 2026 13:00:58 -0400 Subject: [PATCH 4/5] docs: clarify planning ownership and release terms --- PLANNING.md | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/PLANNING.md b/PLANNING.md index 9b983a9..d2f4d21 100644 --- a/PLANNING.md +++ b/PLANNING.md @@ -126,6 +126,22 @@ all of it is neither achievable nor necessary. The rule: **Milestone title:** `Org transition: installable, documented, CI-verified` **Release version (Git tag / `pyproject`):** `0.1.0a1` *(alpha — proposed, see §7 D1)* +### Version terminology + +This repository uses [PEP 440](https://peps.python.org/pep-0440/) terminology. +The numeric suffix on a pre-release counts successive builds within that phase. + +| Term | Meaning in this plan | +| --- | --- | +| **Release** | A uniquely versioned snapshot of the project, represented by an immutable Git tag and published distribution. A release can be a pre-release or a final release. | +| **`0.1.0a1`** | The first **alpha** for the planned `0.1.0` series. It is suitable for early testing while known correctness gaps and planned release work remain. | +| **`0.1.0rc1`** | The first **release candidate**. Planned scope is complete; only fixes for release-blocking findings should separate it from the final release. | +| **`0.1.0`** | The **final release** for this series: the same release segment without a pre-release suffix. “Final” records progression through the release process; it does not by itself claim production validation. | + +The proposed progression is `0.1.0a1` → later alphas if findings require them → +`0.1.0rc1` → later release candidates if blockers remain → `0.1.0`. Each later +pre-release increments the numeric suffix for its phase. + **Goal.** Produce the first `PharmaPy-org`-maintained release: the package installs and its core modules import in a clean, supported environment; core CI and documentation are reproducible and public; the one critical defect is fixed; @@ -195,6 +211,14 @@ Put planned **issues** in the milestone. Do **not** add both an issue and its linked PR (double-counts progress). Add a PR to the milestone only when the PR is itself the tracked deliverable with no corresponding issue. +Assignments also live on the milestone **issues**, not in this file or on their +linked PRs. Each in-scope issue has one accountable GitHub assignee. The release +manager (§7 D7) is responsible for assigning unowned work before the milestone +starts and for ensuring the assignee and Project status stay current. When work +is handed off, the current assignee or release manager updates the issue before +the handoff; PR assignees and reviewers describe implementation and review +roles, not milestone ownership. + ## 6. Project (#1) changes **Views** (create/keep exactly these; remove the rest): @@ -248,7 +272,8 @@ makes the call if consensus is unclear. - `0.1.0` — honest about the capability step, but reads as a stable feature baseline, which 34 open high-severity correctness defects contradict. - **`0.1.0a1`** *(proposed)* — signals "this is the target shape; correctness - work continues," and allows a1 → … → rc1 → 0.1.0 as the backlog burns down. + work continues," and allows the alpha → release-candidate → final progression + defined in §5 as the backlog burns down. - A non-versioned milestone name is used regardless (above); the *tag* still needs a number, so pair it with `0.1.0a1`. @@ -289,5 +314,24 @@ planning, prioritization, and releases; the proposed `AGENTS.md` owns coding and verification rules. A future contributor-facing `CONTRIBUTING.md` should summarize and point to both rather than duplicate either. +### Maintenance responsibility and refresh triggers + +Any maintainer may propose policy changes through a pull request. The named +release manager owns milestone-specific maintenance: keeping the milestone +description synchronized with §5 and confirming the release gates before a tag. + +Maintenance is event-driven rather than scheduled on a fixed calendar. Refresh +the dated §2 snapshot and §5 implementation status together: + +- before creating or rolling over a milestone; +- before tagging any pre-release or final release; and +- when a ratified decision changes scope, the operating model, or a release + gate. + +Changing an individual work assignment does not require a `PLANNING.md` edit: +the issue assignee and Project status are the live operational record. A policy +change to who owns assignments does require review here. Do not advance the +snapshot timestamp unless every snapshot claim is re-queried in the same pass. + This file stays as the living planning record; the generated artifacts (milestone, views, `RELEASING.md`) are downstream of it. From 511f70562fcdc664be13f3b842adcc49587479db Mon Sep 17 00:00:00 2001 From: "David E. Bernal Neira" Date: Thu, 30 Jul 2026 10:34:45 -0400 Subject: [PATCH 5/5] docs: address planning review follow-up --- PLANNING.md | 127 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 54 deletions(-) diff --git a/PLANNING.md b/PLANNING.md index d2f4d21..3961595 100644 --- a/PLANNING.md +++ b/PLANNING.md @@ -9,21 +9,21 @@ > than ad hoc, and (3) verify our own process against an explicit checklist. > > Its authority is limited to planning, prioritization, and releases. Coding -> and verification rules belong in `AGENTS.md` if that file is adopted (see -> [§9](#9-adoption-how-these-sections-graduate)). Revisions to either policy -> document go through normal pull-request review. +> and verification rules are in `AGENTS.md` (see +> [§9](#9-adoption-and-maintenance)). Revisions to either policy document go +> through normal pull-request review. ## Table of contents 1. [Purpose and how to use this document](#1-purpose-and-how-to-use-this-document) -2. [Verified snapshot (2026-07-29)](#2-verified-snapshot-2026-07-29) +2. [Verified snapshot (2026-07-30)](#2-verified-snapshot-2026-07-30) 3. [Operating model](#3-operating-model) 4. [Release-risk policy](#4-release-risk-policy) 5. [First milestone: `0.1.0a1`](#5-first-milestone-010a1) 6. [Project (#1) changes](#6-project-1-changes) 7. [Decision log](#7-decision-log) 8. [Open questions for maintainers](#8-open-questions-for-maintainers) -9. [Adoption: how these sections graduate](#9-adoption-how-these-sections-graduate) +9. [Adoption and maintenance](#9-adoption-and-maintenance) --- @@ -41,13 +41,13 @@ This is a *planning* document, not user-facing docs. Three concrete uses: **Guiding principle:** this is a small, asynchronous, academic team whose real delivery already flows through continuous PR merges. The model below formalizes -*that*, and deliberately avoids ceremony (sprints, mandatory estimates, -blocking committee gates) that the team will not sustain. +*that*, and deliberately avoids ceremony (sprints, mandatory estimates, or +mandatory committee approvals) that the team will not sustain. -## 2. Verified snapshot (2026-07-29) +## 2. Verified snapshot (2026-07-30) Queried read-only through the GitHub REST and GraphQL APIs at -**2026-07-29T13:54:25Z**. **Time-sensitive** — re-verify before acting on any +**2026-07-30T14:29:55Z**. **Time-sensitive** — re-verify before acting on any count. Re-running the Project claims requires organization access and a token with the `read:project` scope. @@ -61,34 +61,46 @@ with the `read:project` scope. - The single `severity:critical` is **#68** (adiabatic crystallizer energy-balance crash). - Org **Project #1 "PharmaPy Development"** was created 2026-07-21 and contains - 85 items. Its - `Priority` values are a mechanical copy of `Severity` (34 High / 20 Medium / - 3 Low / 1 Urgent — identical distribution), the `Size` field is unused - (0 of 85 items populated), and only #23, #26, #134 sit in any iteration. + all 86 open issues. Its `Priority` values are a mechanical copy of `Severity` + for 58 issues (34 High / 20 Medium / 3 Low / 1 Urgent — identical + distribution), the `Size` field is unused (0 of 86 items populated), and only + #23, #26, #134 sit in any iteration. - CI (`.github/workflows/ci.yml`) runs core tests on **Python 3.11 only**, while - `requires-python = ">=3.9"`. Locked pixi installs gate Linux and Windows; the - Assimulo integration job is `continue-on-error` (informational). + `requires-python = ">=3.9"`. Locked pixi installs are required on Linux and + Windows; the Assimulo integration job is `continue-on-error` (informational). - The codebase dates to 2021 and is published (DOI `10.1016/j.compchemeng.2021.107408`); `0.0.1` is a placeholder, not release history. ## 3. Operating model -One Project, milestone-anchored, continuous flow. Each GitHub concept has -exactly one meaning: +Project #1 holds the work, milestones define release targets, and contributors +take the next item when they have capacity; the team does not plan in sprints. +Terms used below have these meanings: + +- A **blocker** is a problem that must be fixed before a release. +- An **epic** is a large issue that groups related smaller issues. +- The **release test suite** is the small set of install, import, example, and + numerical checks that must pass before release. §8 Q1 still needs a maintainer + decision on exactly which existing test lanes and new numerical checks it + contains. +- A **work-in-progress (WIP) limit** caps how many items may be `In progress` at + once. + +Each GitHub concept has one meaning: | Concept | Meaning in this repo | | --- | --- | | **Project #1** | The single source of truth: full backlog, active board, and roadmap. We do **not** create a Project per release or subsystem. | -| **Status** | Workflow state only: `Todo` → `In progress` → `Done`. Delivery is controlled by a **work-in-progress (WIP) limit** on `In progress`, not by sprints. Set the cap when a milestone opens using **one active item per active contributor plus one shared review/unblocking slot**; the formula keeps the limit tied to actual team capacity instead of a magic number. | -| **Milestone** | A repository release (or a concrete, externally meaningful outcome). **Exactly one open at a time** because the Project roadmap already holds longer-horizon work; a second open milestone would create a competing release gate. | -| **Epic + sub-issues** | Decomposition of a large initiative, using native issue-type `Epic` and parent/sub-issue links. Current epics: #3, #17, #67, #118. This is the roadmap's backbone. | -| **Priority** | Maintainer delivery order — **re-triaged independently of severity** (see §7 D4). Until re-triaged it is unreliable and is kept out of delivery views. | +| **Status** | Workflow state only: `Todo` → `In progress` → `Done`. Set the WIP limit when a milestone opens: one active item per active contributor, plus one shared slot for review or unblocking. For example, three active contributors give a limit of four items. | +| **Milestone** | A repository release (or a concrete, externally meaningful outcome). **Exactly one open at a time** because the Project roadmap already holds longer-horizon work; a second open milestone would create two competing definitions of "ready." | +| **Epic + sub-issues** | A large tracked effort and its smaller pieces, linked through GitHub's `Epic` type and parent/sub-issue links. Current epics: #3, #17, #67, #118. | +| **Priority** | Maintainer delivery order, separate from defect severity. Clear the 58 copied values as specified in §6; a blank value means `Needs triage` until a maintainer assigns a real delivery priority (see §7 D4). | | **Severity** (label) | Technical impact of a *defect* only. Does not imply delivery order. | | **Area** (label) | Affected subsystem. Useful for filtering; not a planning input. | | **Assignee** | The one person accountable for the item. No duplicate "owner" field. | | **Target date** | Only for a genuinely externally-dated deliverable. Not a general field. | -| **Iteration** | **Not used as a commitment unit.** (See §7 D3.) Removing it also removes the three-way conflict between iteration dates, `Target date`, and the milestone due date. | +| **Iteration** | Not used to promise what will ship by a date. (See §7 D3.) Removing it also removes the conflict between iteration dates, `Target date`, and the milestone due date. | | **Size** | **Not required.** Optional, and only populated for current-milestone items if the team finds it useful. (See §7 D5.) | Rationale for dropping sprints: the iteration apparatus was created on @@ -96,7 +108,7 @@ Rationale for dropping sprints: the iteration apparatus was created on and held zero items, and the current board contains work outside the release while omitting the release's own critical blocker. The team's actual, working coordination mechanism is per-PR "whoever lands second, rebase" notes — -continuous flow. We formalize that. +contributors take the next item as capacity opens. We formalize that. ## 4. Release-risk policy @@ -107,16 +119,17 @@ all of it is neither achievable nor necessary. The rule: critical. Each critical must be closed **with a regression test**. *(Today: only #68, fixed by PR #106, which adds regression coverage for its four sub-defects.)* -- **`severity:high` → not individually blocking, with a promotion rule.** A high - is *promoted* to a blocker if it either (a) produces a **silent wrong - numerical result in a documented example/tutorial**, or (b) affects a module - exercised by the release **smoke/validation suite**. All non-promoted highs - are **disclosed by number in the release notes**. -- **The gate is behavioral, not lexical.** "No open `severity:critical`" is - necessary but insufficient, because severity labels do not cover every - correctness issue. Release also requires the smoke/numerical suite green +- **`severity:high` → not individually blocking, with an escalation rule.** A + high-severity issue becomes a blocker if it either (a) produces a **silent + wrong numerical result in a documented example/tutorial**, or (b) affects a + module exercised by the **release test suite**. All other high-severity + issues are **listed by number in the release notes**. +- **The gate checks behavior, not just labels.** "No open + `severity:critical`" is necessary but insufficient, because severity labels + do not cover every correctness issue. The release test suite must also pass (§5 exit criteria). -- **A named release manager decides promotions**, recorded on the milestone. +- **A named release manager decides which high-severity issues become + blockers**, and records those decisions on the milestone. ## 5. First milestone: `0.1.0a1` @@ -136,7 +149,7 @@ The numeric suffix on a pre-release counts successive builds within that phase. | **Release** | A uniquely versioned snapshot of the project, represented by an immutable Git tag and published distribution. A release can be a pre-release or a final release. | | **`0.1.0a1`** | The first **alpha** for the planned `0.1.0` series. It is suitable for early testing while known correctness gaps and planned release work remain. | | **`0.1.0rc1`** | The first **release candidate**. Planned scope is complete; only fixes for release-blocking findings should separate it from the final release. | -| **`0.1.0`** | The **final release** for this series: the same release segment without a pre-release suffix. “Final” records progression through the release process; it does not by itself claim production validation. | +| **`0.1.0`** | The **final release** for this series: the same release segment without a pre-release suffix. "Final" records progression through the release process; it does not by itself claim production validation. | The proposed progression is `0.1.0a1` → later alphas if findings require them → `0.1.0rc1` → later release candidates if blockers remain → `0.1.0`. Each later @@ -150,23 +163,23 @@ explicitly an **alpha** — it does not claim numerical production-validation. ### Scope (in) — mapped to tracked issues -Implementation status is a dated snapshot from **2026-07-29T13:54:25Z**; the +Implementation status is a dated snapshot from **2026-07-30T14:29:55Z**; the issues remain the durable scope records and must be re-queried before copying this table into a milestone. | Issue | Implementation status at snapshot | Role | | --- | --- | --- | -| #68 | PR **#106** open | The critical crystallizer crash + enthalpy basis (hard gate). | +| #68 | PR **#106** open | The critical crystallizer crash + enthalpy basis (must be fixed before release). | | #134 | PR **#135** open | Solver-free model imports (lazy Assimulo). | | #130 | PR **#131** open | Reproducible, public documentation (#131 is one step and intentionally does not close #130). | | #8 | PR **#136** merged | Packaging/metadata modernization, `pharmapy-sim` distribution, pixi environments, install guide, and two-platform locked install matrix. Remaining #8 scope stays on the issue; distribution-name reservation is tracked by #146. | ### Scope (out) -- #7 in its broad form (split out a release-specific smoke/validation issue — +- #7 in its broad form (split out a release-specific test-suite issue — see §8 Q1). - #10, the full solver-abstraction initiative. -- Every correctness issue counted in §2 as a single release gate. +- Requiring every correctness issue counted in §2 to be closed before release. - Epic #118 and the complete StateLayout migration. - Speculative bioreactor, crystallizer-extension, and scheduling initiatives. - #23 (PR #114) and #26 (PR #115): **in flight, not release scope** unless the @@ -186,14 +199,14 @@ this table into a milestone. `>=3.11`). Dependency bounds and environment policy remain sourced in [`DEPENDENCIES.md`](DEPENDENCIES.md). - [x] A clean environment installs the package through the documented pip and - locked pixi paths. PR #136 added the Linux/Windows smoke-install jobs and + locked pixi paths. PR #136 added the Linux/Windows locked-install jobs and [`INSTALLATION.md`](INSTALLATION.md); commands and lane semantics are sourced in [`TESTING.md`](TESTING.md). - [ ] Core modules import **without Assimulo**; a solver path without Assimulo fails with a clear, localized message (asserted by a test). - [ ] Core CI and documentation CI are green; the public docs site and pull-request previews are verified (#130). -- [ ] **#68 is closed with a regression test**, and the smoke/validation suite +- [ ] **#68 is closed with a regression test**, and the release test suite is green. - [ ] No open defect is labelled `severity:critical`. - [ ] Release notes enumerate the open `severity:high` correctness issues by @@ -234,9 +247,11 @@ roles, not milestone ownership. Remove the `Current iteration` view (no iterations). -**Fields:** retire `Iteration` and `Size` from the model; keep Status, Priority -(re-triaged), Severity/Area (labels), Milestone, Assignee, and a sparingly-used -`Target date`. +**Fields:** retire `Iteration` and `Size` from the model. Clear the 58 existing +`Priority` values copied from `Severity`; a blank `Priority` means +`Needs triage`. Maintainers then assign Priority from delivery order, never by +copying Severity. Keep Status, Priority, Severity/Area (labels), Milestone, +Assignee, and a sparingly-used `Target date`. **Automations:** keep auto-add of open issues and archive-on-close; add auto-set `Status: Done` when the closing PR merges. Stop mirroring Severity into @@ -257,10 +272,10 @@ makes the call if consensus is unclear. | # | Decision | Proposed default | Reversible? | Owner | | --- | --- | --- | --- | --- | -| **D1** | First release version | `0.1.0a1` (alpha) | Hard once tagged/DOI'd | maintainer | -| **D2** | Distribution name on the index | `pharmapy-sim` (recheck at publish, #146) | Hard once published | maintainer | -| **D3** | Timeboxed iterations | **Drop**; use WIP-limited continuous flow | Yes | team | -| **D4** | Priority model | Re-triage independently of severity (or collapse to `Now/Next/Later`) | Yes | maintainer | +| **D1** | First release version | `0.1.0a1` (alpha) | No after the version or DOI is published | maintainer | +| **D2** | Distribution name on the index | `pharmapy-sim` (recheck at publish, #146) | No after publication | maintainer | +| **D3** | Timeboxed iterations | **Drop**; take the next item as capacity opens and enforce the WIP limit | Yes | team | +| **D4** | Priority model | Clear mirrored values; leave blank as `Needs triage`, then prioritize independently of severity (or use `Now/Next/Later`) | Yes | maintainer | | **D5** | `Size` field | Not required; optional for near-term items only | Yes | team | | **D6** | #23/#26 in this release? | No unless the owner confirms they ship here | Yes | issue owner | | **D7** | Release manager | The maintainer who creates the milestone acts as release manager unless the milestone names another volunteer | Yes | maintainer | @@ -273,7 +288,7 @@ makes the call if consensus is unclear. baseline, which 34 open high-severity correctness defects contradict. - **`0.1.0a1`** *(proposed)* — signals "this is the target shape; correctness work continues," and allows the alpha → release-candidate → final progression - defined in §5 as the backlog burns down. + defined in §5 as the remaining work is completed. - A non-versioned milestone name is used regardless (above); the *tag* still needs a number, so pair it with `0.1.0a1`. @@ -281,7 +296,7 @@ makes the call if consensus is unclear. These need a human decision; do not invent answers. -1. **Smoke/validation suite.** [`TESTING.md`](TESTING.md) already defines the +1. **Release test suite.** [`TESTING.md`](TESTING.md) already defines the core pytest lane, locked pixi install matrix, and informational Assimulo lane. Which of those existing lanes gate the release, and what numerical assertions must be added on top? Should #7 be split into a release-specific @@ -298,9 +313,10 @@ These need a human decision; do not invent answers. correctness fixes; a later minor for meaningful API/architecture change. No future milestones created until their scope is credible. -## 9. Adoption: how these sections graduate +## 9. Adoption and maintenance -On merge, this document becomes the reference. As decisions are ratified: +On merge, this document becomes the reference. As decisions are ratified, copy +the durable parts into the operational documents and GitHub records: - §4 (release-risk policy) and §5 due-date/hygiene → the durable content of a future `RELEASING.md`. @@ -309,10 +325,11 @@ On merge, this document becomes the reference. As decisions are ratified: - §5 (milestone block) → pasted into the created GitHub milestone. - §6 → applied to Project #1. -The authority split with PR #132 is deliberate: `PLANNING.md` owns work -planning, prioritization, and releases; the proposed `AGENTS.md` owns coding and -verification rules. A future contributor-facing `CONTRIBUTING.md` should -summarize and point to both rather than duplicate either. +The authority split with `AGENTS.md`, adopted through PR #132, is deliberate: +`PLANNING.md` owns work planning, prioritization, and releases; `AGENTS.md` +owns coding and verification rules. A future contributor-facing +`CONTRIBUTING.md` should summarize and point to both rather than duplicate +either. ### Maintenance responsibility and refresh triggers @@ -323,6 +340,8 @@ description synchronized with §5 and confirming the release gates before a tag. Maintenance is event-driven rather than scheduled on a fixed calendar. Refresh the dated §2 snapshot and §5 implementation status together: +- in the final revision after a review or ratification window closes and before + that revision is merged; - before creating or rolling over a milestone; - before tagging any pre-release or final release; and - when a ratified decision changes scope, the operating model, or a release