Skip to content

v0.8.0 remediation execution plan

  • Status: Completed
  • Finalized: 2026-08-17
  • Target release: v0.8.0
  • Umbrella issue: #35
  • Final qualification: #33
  • Audit contract: v0.8.0 historical audit and remediation record
  • Final execution state: R1–R9 complete and accepted; post-R9 COPYING distribution correction complete and accepted

Source snapshot audited: e4cef21b66d0e22661307a3fc7e246e71611517a
Companion audit and issue contracts: v0.8.0 historical audit and remediation record
Plan date: 2026-07-28
Status: completed historical execution plan

This document supersedes pyvoro2-v0.8-remediation-batches.md and its first-pass addendum as the canonical execution plan used during remediation. The older documents and the preserved instructions below remain audit history. The companion issue backlog contains the final evidence, full paste-ready issue bodies, and acceptance criteria.

Final status amendment

R1–R9 were completed and independently accepted. The post-R9 correction that makes wheel and sdist distributions carry and verify the mandatory COPYING payload was also completed and accepted. One exact final source commit is independently reviewed and frozen; issue #33 qualifies that exact commit and its artifacts before the public tag is created. Any tracked correction changes the candidate hash and requires renewed review and qualification, and no source edit is expected after #33. v0.8.0 uses the project Git tag, GitHub Release, and PyPI distribution process and intentionally creates no new pyvoro2 Zenodo software-version record; existing historical records remain valid.

The plan is designed for the following workflow:

  1. the maintainer reviews and approves scientific/API decisions;
  2. a Chat/Codex Extra High reasoning session turns one approved issue into an exact implementation prompt;
  3. Codex Extra High implements that one issue on the current branch;
  4. the resulting patch is reviewed against the issue contract before merging.

The issue text is intentionally precise about observable outcomes and stop conditions, while leaving ordinary internal implementation details to Codex.

The accepted R9 baseline includes ADR 0017. The final handoff is the exact source commit accepted after finalization and independent review; issue #33 qualifies that frozen commit rather than any earlier remediation baseline.

1. Executive plan

Use one umbrella tracker with nine child issues, R1–R9, followed by the separate final qualification and release issue #33. Work linearly unless a specific parallel branch is worth the added review cost.

R1 objective contract
  ↓
R2 certified scalar proximal solver
  ↓
R3 strict inputs, immutable values, native preconditions
  ↓
R4 certified periodic image geometry
  ↓
R5 non-optional generator and duplicate safety
  ↓
R6 observation/result/report identity
  ↓
R7 atomic active-set final state
  ↓
R8 severity-complete diagnostics
  ↓
post-remediation polish audit
  ↓
R9 public API/docs/distribution synchronization
  ↓
#33 clean release qualification

The strict dependency graph is slightly less linear:

R1 ──> R2
R1,R2 ──> R3                (recommended sequencing to avoid option churn)
R3 ──> R4 ──> R5
R3,R4 ──> R6
R1,R2,R6 ──> R7
R3,R5 ──> R8
R1–R8 ──> R9 ──> close #35 ──> #33

For a single maintainer, the recommended linear order is safer than exploiting possible parallelism. It keeps every later prompt based on the current merged source and avoids resolving the same conflict in several branches.

2. Why the work is represented as nine remediation issues plus #33

The plan deliberately avoids both extremes: one unreviewable mega-issue and a large collection of tiny validation tickets.

Issues that must remain separate

  • R1 and R2: R2’s algorithm is defined by R1’s formulas. Combining them would let implementation choices silently determine the objective contract.
  • R3 and R4: strict input/native safety is broad but mechanical; certified closest-lattice-vector geometry is a distinct numerical algorithm requiring independent oracles.
  • R4 and R5: R5 consumes R4’s minimum-image primitive, but duplicate and containment policy is a separate public safety contract.
  • R6 and R7: observation/row identity must exist before an active-set state can prove that all of its layers share one origin.
  • R8: diagnostic severity and strictness are externally visible and should not be hidden inside forward-safety implementation.
  • R9 and #33: documentation/distribution source must be corrected before a clean release run can qualify it. Issue #33 starts only after umbrella #35 is closed; it is evidence, not a place to decide API policy.

Work intentionally grouped

  • R3 groups exact-type validation, finite checks, immutable ownership, and native preconditions because they are manifestations of one invariant: invalid or mutable public values must not reach numerical/native code. Because the patch is broad, R3 may use two sequential PRs/prompts under one GitHub issue.
  • R9 groups naming, current documentation, licensing, and release-note synchronization because all depend on the final corrected behavior and are cheapest to audit together.

This structure is stable under step-by-step execution. Earlier issues may remove individual examples from later scopes, but they should not change the purpose or acceptance contract of a later issue.

3. GitHub organization

3.1 Umbrella tracker

Create one umbrella issue, for example:

Complete v0.8.0 pre-release correctness and safety remediation

Current checklist:

- [x] R1 — Correct and freeze the separator inverse objective contract
- [x] R2 — Replace the scalar proximal loop with a certified bounded solver
- [x] R3 — Harden public inputs, immutable value objects, and native preconditions
- [x] R4 — Implement certified periodic nearest-image and minimum-image geometry
- [x] R5 — Make forward generator containment and duplicate safety non-optional
- [x] R6 — Bind observations, fits, realizations, and reports to canonical source data
- [x] R7 — Make the active-set final state atomic and self-consistent
- [x] R8 — Make diagnostics and strict validation severity-complete
- [ ] R9 — Synchronize the public API, documentation, distribution, and release contract

The umbrella issue records status only. Do not duplicate every child issue’s technical contract in comments. After all nine items are complete, close #35; only then begin final qualification under issue #33.

3.2 Child issues and pull requests

Normally use one issue and one focused PR per R-number.

Exception:

  • R3 may have R3-A and R3-B PRs under the same issue:
  • R3-A: validators and native precondition guards;
  • R3-B: adoption and immutable ownership.

The first PR must not close R3. The issue closes only after both parts and the full regression matrix pass.

3.3 Suggested branch names

fix/v080-r1-objective-contract
fix/v080-r2-certified-prox
fix/v080-r3a-native-preconditions
fix/v080-r3b-input-ownership
fix/v080-r4-periodic-images
fix/v080-r5-generator-safety
fix/v080-r6-observation-identity
fix/v080-r7-active-final-state
fix/v080-r8-diagnostic-semantics
fix/v080-r9-public-release-contract
release/v080-qualification

Create each branch from the latest merged dev, not from the original audited snapshot.

4. Working rules for every issue

Every implementation issue must require:

  1. Reproduce before fixing. Add or preserve a failing regression probe where practical.
  2. Use an independent oracle. Backend agreement is not sufficient for mathematical code. Use analytic solutions, direct objective recomputation, finite differences, KKT/stationarity checks, exhaustive bounded lattice enumeration, or subprocess exit behavior as appropriate.
  3. Freeze policy first. Public formulas, defaults, severity, schemas, and identity rules belong in the approved issue/prompt, not in Codex’s improvisation.
  4. Make the smallest coherent change. Do not pull later issues into the current PR merely because a nearby file is open.
  5. Test in layers. Run the new focused tests first, then the relevant subsystem, then the full deterministic suite. Run fuzz/property tests when geometry, input parsing, or topology changes.
  6. Update current documentation with behavior. Add [Unreleased] changelog entries for user-visible corrections. Do not make final release claims before #33.
  7. Report evidence. Codex must list changed files, commands, results, compatibility implications, and remaining uncertainty.
  8. No release actions. Implementation prompts must forbid merging, tagging, publishing, or GitHub release actions.
  9. Stop rather than invent. If implementation needs a public decision not present in the issue, Codex must stop and request it.

5. Preparing the working checkout

5.1 Local review materials

The audit and remediation plan are source-controlled under docs/development/. Place only bulky or environment-specific probe output outside version control or under a locally excluded local-review/ directory:

local-review/
├── pyvoro2-v0.8-audit-probes.txt
├── pyvoro2-final-review-new-probes.log
├── pyvoro2-final-review-init-mem-cases.log
├── pyvoro2-final-review-triclinic-random-audit.log
└── native-donor/                 # optional; never a release input

Prefer .git/info/exclude for this local directory. Do not add donor binaries or private review artifacts to the public package accidentally.

5.2 Source authority

For every new issue/PR:

  • current source and tests define implemented behavior;
  • current guides/reference define documented public behavior;
  • accepted ADRs and the active v0.8 plan define durable policy;
  • the approved child issue defines the remediation outcome;
  • the audit files provide evidence, not independent API authority.

The original e4cef21 zip is evidence for the initial defect only. After R1, all implementation and review must use the latest branch/commit.

6. Chat-to-Codex workflow for each issue

Step 1 — Open a design/review Chat

Give the Chat/Codex Extra High reasoning model:

  • the current repository or current branch;
  • the one child issue body;
  • only the relevant audit probe/output;
  • the relevant accepted ADR/API inventory sections;
  • the manuscript section only when mathematical semantics require it.

Do not attach every historical planning file to every issue. Extra unrelated context makes it easier to follow obsolete decisions.

Ask the reasoning model to:

  1. reproduce and explain the finding;
  2. identify maintainer-level decisions;
  3. recommend an exact contract;
  4. analyze compatibility and issue boundaries;
  5. stop before code editing.

Step 2 — Approve the contract

Discuss the recommendations until the issue contains concrete decisions. For R1, R2, R4, R5, R6, and R8, this step is mandatory.

Record durable decisions in one or more of:

  • the GitHub issue;
  • an ADR when the decision extends beyond this bug;
  • the API inventory;
  • a short issue-scoped decision section.

Do not rely on private chat history as the only authority.

Step 3 — Generate the Codex Extra High implementation prompt

Ask the reasoning model to produce one paste-ready prompt for Codex Extra High. The prompt must include:

  • current issue and exact approved contract;
  • in-scope and out-of-scope files/behavior;
  • regression oracles;
  • stop conditions;
  • required commands and handoff report.

Review the prompt before running it. In particular, remove any instruction to “fix all related issues” or make opportunistic API improvements.

Step 4 — Run Codex Extra High

Run Codex in the current issue branch. It may inspect the whole repository but must implement only the current issue.

Step 5 — Independent post-implementation review

Provide the updated source/commit and the approved issue contract to a fresh review session. Ask it to:

  • inspect every changed file;
  • reproduce the original defect;
  • verify the independent oracle;
  • search for scope creep and new defects;
  • run targeted and full tests;
  • return a merge/no-merge verdict.

A green Codex self-summary is not the review.

Step 6 — Merge and update the ledger

After review passes:

  • merge into dev;
  • close or update the child issue;
  • check the umbrella item;
  • add issue/PR/test references to the draft R9 release-note ledger;
  • start the next branch from the new dev.

7. Generic design-Chat prompt

Use this template for issues with unresolved policy:

We are preparing pyvoro2 v0.8 remediation issue [R-ID — TITLE].

Read, in this order:

1. AGENTS.md and the active v0.8 plan/ADR.
2. The complete [R-ID] issue body in
   docs/development/audits/v0.8-pre-release.md.
3. The relevant source and tests listed below.
4. Only the audit probe(s) named below.
5. [Optional] the specified manuscript section.

Relevant source/tests:
[PASTE ISSUE-SPECIFIC PATHS]

Relevant audit evidence:
[PASTE FILENAMES OR THE SMALL REPRODUCTION]

Do not edit files, create branches, or perform GitHub actions.

First:
- verify the finding against the current branch rather than assuming the old
  snapshot still behaves identically;
- explain the defect and its user/scientific impact;
- identify every maintainer-level formula, default, schema, severity, or
  compatibility decision;
- recommend one exact contract and alternatives;
- determine whether the current issue boundary remains coherent;
- list independent regression oracles and likely affected public docs.

Present decisions for maintainer review. Do not generate an implementation
prompt until I approve the complete contract.

After approval, produce:
1. the final issue-scoped decision record;
2. one paste-ready Codex Extra High implementation prompt;
3. a post-implementation review checklist.

8. Generic Codex Extra High implementation prompt

Implement only pyvoro2 v0.8 remediation issue [R-ID — TITLE] on the current
branch.

Read:
- AGENTS.md;
- docs/development/plans/v0.8.md;
- relevant accepted ADRs and API-inventory sections;
- the approved [R-ID] issue contract below.

Approved contract:
[PASTE THE FINAL DECISIONS, NOT A CHAT SUMMARY]

In scope:
[PASTE THE ISSUE SCOPE]

Out of scope:
[PASTE THE ISSUE NON-GOALS]

Required independent regression oracles:
[PASTE THE ISSUE ORACLES]

Requirements:
1. Reproduce the current defect before or while adding the regression test.
2. Do not treat agreement between existing backends as the sole oracle.
3. Make the smallest coherent implementation change.
4. Preserve unrelated public API and numerical behavior.
5. Add current documentation and an Unreleased changelog entry for
   user-visible behavior.
6. Run focused tests, relevant subsystem tests, then the full deterministic
   suite; run fuzz/property or subprocess tests where required.
7. Follow generated-file rules from AGENTS.md.
8. Stop and report if implementation requires a public decision not contained
   in this contract, a new mandatory dependency, a vendored Voro++ change, or
   an unexplained numerical change.
9. Do not merge, tag, publish, or perform GitHub actions.

At handoff report:
- defect reproduction;
- implementation summary;
- files changed;
- tests/oracles added;
- exact commands and results;
- public compatibility/migration effect;
- remaining uncertainty or follow-up.

9. Generic post-Codex review prompt

Review the current pyvoro2 branch after implementation of [R-ID — TITLE].
Do not modify files.

Use the approved [R-ID] issue and decision record as the contract. Read AGENTS.md,
the active v0.8 plan, the relevant ADR/API inventory sections, and the original
focused audit evidence.

Please:
1. inspect every changed file and the complete diff;
2. reproduce the original defect on the corrected branch;
3. verify every independent regression oracle rather than trusting backend
   agreement or Codex’s report;
4. check public API, docs, changelog, generated files, and compatibility;
5. look for scope creep, duplicated validation, stale state, unsafe native
   paths, and newly introduced edge cases;
6. run focused, subsystem, full deterministic, and required fuzz/subprocess
   tests;
7. list findings by severity;
8. return a clear MERGE or DO NOT MERGE verdict with required follow-up.

10. Issue-specific execution cards

R1 execution card — objective contract

Approved child issue: #36

Accepted decisions:

Context for the design Chat

Read:

  • src/pyvoro2/inverse/separator/model.py;
  • src/pyvoro2/inverse/separator/problem.py;
  • src/pyvoro2/inverse/separator/solver.py;
  • objective/result fields in types.py and report.py;
  • current inverse theory/guide pages;
  • objective-related tests;
  • manuscript Sections 4.1–4.3 only.

Provide the ADMM parity and reciprocal finite-difference excerpts from pyvoro2-v0.8-audit-probes.txt.

Approved decisions copied into the implementation prompt

  • squared mismatch and the Huber quadratic branch are 0.5 * residual**2;
  • L2 is 0.5 * strength * ||weights - reference||**2, retaining the normal system L_obs + strength * I;
  • reciprocal penalties use the finite convex tangent continuation in ADR 0007;
  • zero-strength penalties are exact no-ops for evaluation, coupling, backend selection, and operator availability;
  • hard bounds use the shared float64 absolute-plus-relative policy and expose hard_max_tolerance;
  • successful statuses require finite reported soft objectives, and supported analytic warm-start failure falls back safely; and
  • weighted mismatch/L2 evaluation preserves finite binary64 results and checks exact zero terms before forming dangerous intermediates;
  • quadratic rows are constructed directly as rho = confidence * alpha**2 and q = confidence * alpha * (target - beta), without reconstructing q from rho * z_obs;
  • the measurement-space hard accepted interval is mapped into Bellman–Ford difference bounds without reapplying measurement tolerance in different units;
  • reciprocal values and derivatives use separate scale-safe evaluation, and hard-constrained ADMM success requires final hard-row satisfaction;
  • residual and ADMM convergence summaries use stable norm and RMS reductions; and
  • the corrections have no legacy scaling mode or public tolerance option.
  • all quadratic paths certify the final public binary64 weights through one backend-independent exact-zero or forward objective-gap contract;
  • bounded exact helpers may generate a rounded candidate, but they do not introduce an objective over the binary64 lattice or an output-resolution floor: an unrepresentable continuous zero optimum may therefore return numerical_failure;
  • private exact-helper thresholds may affect recovery, never the meaning of optimal;
  • completed ADMM iterations remain visible in n_iter when post-iteration final certification fails;
  • final active-set alignment is permitted only on a true zero-L2 gauge and only when exact binary64-input arithmetic proves that every fitted difference is unchanged;
  • the public API separates solver='direct'|'admm' from linear_backend='dense'|'sparse' and defaults to direct+dense;
  • auto, analytic, and the solver value sparse are removed without compatibility shims;
  • explicit ADMM actually executes ADMM whenever a component solve is required, and dense paths never import or switch to SciPy;
  • sparse direct and sparse ADMM explicitly require SciPy; and
  • results and reports record solver method and linear backend separately.

Expected implementation output

  • coherent scalar objective implementation;
  • scale-safe objective, quadratic-row, affine-prediction, and reduction helpers;
  • corrected ADMM coefficients and hard-success termination;
  • derivative, extreme-scale, accepted-set, and backend parity oracles;
  • exact formula documentation;
  • inspectable ADMM iteration metadata on certification failure;
  • certified active-set final-state packaging that cannot change a positive-L2 objective or a binary64 component contrast;
  • no proximal-algorithm replacement or ADMM-default tuning yet.

Merge gate

Do not merge if any backend/report still evaluates a differently scaled objective, if finite-difference tests avoid branch neighborhoods, if a private size threshold weakens success certification, if ADMM loses completed iteration metadata on final certification failure, if active-set final alignment changes a certified objective or fitted difference, or if dense calls silently acquire SciPy. The 16/17, 256/257, and 512/513 regressions are explicit merge gates.

R2 execution card — certified proximal solver

Context

Use the approved R1 formulas, solver.py, scalar penalty evaluation code, and the two source-controlled reproductions plus independently generated coverage. Do not reopen R1 unless a contradiction is found.

Decisions

  • complete-expression arithmetic and one compiled objective kernel;
  • rigorous one-sided derivative enclosures, exact point signs, and adjacent numeric-binary64 bracketing;
  • twofold balls with derived physical and base-two-scaled outward bounds;
  • certified ln(2) range reduction and bounded-polynomial exponential work;
  • direct branch-partitioned endpoint differences and bounded ambiguity fallback;
  • vectorized heterogeneous ordinary rows, scalar routing for unresolved rows, and structured failure mapping.

Expected implementation output

  • directly testable bounded scalar solver;
  • safeguarded sign-bracket convergence with no tolerance-based point success;
  • shared public/private/report objective semantics;
  • independent scalar, ball-primitive, exponential, forwarding, generated- audit, and performance oracle tests;
  • end-to-end ADMM status/objective checks.

Merge gate

No exhaustion path may return the last iterate as success. Every point success must prove the exact KKT signs, and every ordinary non-point success must end in an adjacent numeric-binary64 sign bracket. Private/public objective paths must agree on complete source expressions, terminal candidates must be selected by direct differences, and the frozen identical and heterogeneous 1/10/100/1000-row performance gates must pass with zero fallbacks on the canonical benchmark. Compensated centers, vector proposals, and unproved heuristic radii have no sign authority.

Implementation status

Issue #37 implements the corrected contract in ADR 0009 after two review rounds found split exponential objectives, cancellation-driven false point success, fixed high-precision transcendental work on the ADMM hot path, and then an invalid double-double enclosure that admitted a false bracket and wrong terminal endpoint. The revised implementation carries derived twofold-ball bounds through the scalar and heterogeneous batch paths and routes unresolved rows to the bounded scalar fallback. A subsequent remediation review tightened the batch boundary: reciprocal rows are excluded before array arithmetic, caller NumPy exception policy cannot change results, and exceptional lanes cannot suppress certificates for ordinary neighbors. Scalar and batch success now retain common derivative, direct-difference, selection, localization, and fallback-provenance evidence. The independent audit checks containment and endpoint decisions for all generated cases, and benchmark routing is measured at the actual batch/scalar entry points. The public solver/backend surface and ADMM decomposition remain unchanged. Maintainer review and the plan-wide release gates remain pending.

R3 execution card — validation, ownership, native safety

Part A prompt

Focus on:

  • new small validators;
  • cpp/bindings.cpp and cpp/bindings2d.cpp precondition guards;
  • init_mem, blocks, finite native arrays/parameters;
  • subprocess tests.

Use pyvoro2-final-review-init-mem-cases.log and the vendored 2D allocation logic as evidence.

Part B prompt

Focus on:

  • IDs, shifts, options, masks, tolerances;
  • models and retained arrays;
  • all domain classes and from_points;
  • immutable canonical ownership;
  • periodic flags, remapping, handedness, resource guard.

Decisions

  • accepted exact Boolean/NumPy scalar types;
  • left-handed-cell policy;
  • block/resource limit policy;
  • zero-allowed tolerance matrix.

Expected output

  • one coherent validation module or small set of responsibility-specific helpers;
  • no lossy conversion before validation;
  • safe direct native calls;
  • mutation and invalid-input matrices.

Merge gate

R3-A may merge independently, but R3 does not close until R3-B passes. After R3-A changes C++, the old native donor is no longer compatible.

Current implementation status (2026-08-09): R3-A and R3-B are complete. The integrated R3 review and regression gate were accepted. The completed reviewed R3 baseline is 555228cbf8f2179391a981ab59f005edb9e300b4; R4 starts from that baseline.

R4 execution card — certified periodic images

Context

Read:

  • src/pyvoro2/_internal/spatial/domain_geometry.py;
  • planar geometry adapter;
  • inverse/separator/constraints.py;
  • duplicate modules;
  • periodic-cell transforms and tests.

Provide both the concrete wrong-image example and the randomized audit log.

Decisions

  • exact/certified algorithm;
  • image_search lifecycle/meaning;
  • deterministic ties;
  • ill-conditioned-cell behavior;
  • explicit-shift authority.

Expected output

  • one internal minimum-image primitive;
  • exact/certified triclinic behavior;
  • exhaustive randomized oracle tests;
  • use by inverse resolution and by duplicate distances when current periodic wrapping is enabled, while preserving the unwrapped Cartesian check when it is disabled.

Merge gate

Increasing the default cube size is not acceptable. Any uncertified result must fail explicitly rather than warn and continue.

Current implementation status (2026-08-09): issue #40 replaces the bounded cube with the exact dyadic/proof-box contract recorded in ADR 0012. Separator inference and evaluated periodic duplicate-pair distances share the primitive when wrapping is enabled (wrap=True, or duplicate_wrap=True in forward operations); disabling wrapping preserves the established unwrapped Cartesian check. Explicit shifts and the R5 candidate-scanner and mandatory-safety boundary independent of duplicate_wrap are preserved. The dedicated independent mathematical/numerical review was approved. The final reviewed R4 baseline is 64324efbba9ba0b77194f7aab78bf51f415e6d7a; R5 starts from this state.

R5 execution card — generator safety

Context

Read both forward APIs, duplicate modules, domain adapters, inverse realization and active-set entry points, and the native insertion behavior. Provide the outside-site, exact-duplicate, periodic-process-exit, and threshold-bypass reproductions.

Decisions

  • mandatory native-safety floor;
  • semantics of off, warn, raise, threshold, and wrap;
  • half-open containment convention;
  • error type and message fields.

Expected output

  • centralized generator preparation;
  • safety independent of optional policy;
  • all forward/inverse entry points covered;
  • subprocess non-termination regression tests;
  • current documentation updates.

Merge gate

No combination of public duplicate options may reproduce a Voro++ process exit. Every generator omitted by the native half-open rule must instead be rejected before native insertion.

R6 execution card — source identity and reports

Context

Read:

  • constraints.py, solver.py, realize.py, types.py, report.py;
  • observation/result/report API-contract tests;
  • API inventory and result lifecycle docs.

Provide geometry-reuse, malformed-constructor, and unrelated-record probes.

Decisions

  • constructor/factory policy;
  • geometry and row identity/equivalence;
  • report schema/provenance;
  • serialized discriminator naming.

Expected output

  • canonical immutable observation data;
  • one equivalence/origin check used everywhere;
  • report schema tests and JSON round trips;
  • no shape-only association.

Merge gate

Equivalent copies must work under the approved policy, while unrelated same-shape data must fail. Codex may not invent schema fields.

R7 execution card — active final state

Implementation issue: #43

Decision: ADR 0015

Context

Use the merged R6 identity contract. Read active.py, active result types, report builders, and path/termination tests.

Expected output

  • one internal accepted-final-state structure;
  • explicit handling of every final-refit status;
  • no stale realization/records;
  • optional weights-dependent layers and strict-JSON null report semantics;
  • characterization tests for cycle/max/failure outcomes.

Merge gate

For every test result, mask, observations, weights, realization, records, and termination must be traceable to one final state.

R8 execution card — diagnostics

Implementation issue: #44

Decision: ADR 0016

Context

Read spatial and planar diagnostics/validation/normalization modules and public tessellation_check paths. Provide missing-ID, malformed-measure, non-finite normalization-tolerance, stale-flag, and planar warning-only reproductions.

Decision

Approve the exact relationship among issue severity, mode invariants, overall ok, and strict validation.

Expected output

  • centralized severity-complete ok;
  • expected-ID rules by mode;
  • explicit malformed/non-finite issues;
  • reset annotations;
  • cross-dimensional warning semantics.

The approved mode matrix treats absent standard IDs as errors, absent power IDs as informational hidden/empty sites, and absent IDs with undeclared mode as warnings. Required reciprocity findings are errors; optional inspection remains informational or warning-level. Strict and public compute wrappers consume the completed diagnostic rather than rebuilding a partial policy.

Merge gate

No error-level issue may coexist with ok=True, and warning-only findings may not fail unless explicitly promoted by the approved policy.

R9 execution card — public/distribution contract

Implementation issue: #45

Start with a short polish audit

After R1–R8 merge, run a bounded static review of:

  • docs, README source, examples, notebooks, generated pages;
  • API inventory, changelog, ADRs, active plan, release notes;
  • powerfit/PowerFit occurrences;
  • package metadata, notice/license packaging, distribution checks;
  • current workflows and release scripts.

The polish audit may add small R9 checklist items. It must not silently reopen approved mathematical or API contracts.

Frozen decisions

  • PowerFitBounds, PowerFitPredictions, PowerFitObjectiveBreakdown, and SelfConsistentPowerFitResult remain current advanced public names;
  • report schema pyvoro2.inverse.separator.report, version 1, and all three retained report kinds remain unchanged;
  • weight-first locate/ghost parity is a candidate v0.9 stabilization workstream, not v0.8 implementation;
  • ADR 0017 fixes v0.9 functional stabilization, the stable 1.0 core, v1.1 prescribed measures, and v1.2 mixed fitting;
  • one-repository/one-distribution through 1.0 and a formal no-persistent- functional-Voro++-fork rule remain open pre-1.0 decisions.

Expected output

  • synchronized current documentation;
  • full legacy-vocabulary classification;
  • actual Voro++ license in distributions and enforced checks;
  • pending release notes with issue/PR/test ledger;
  • roadmap-visible later candidates without prematurely freezing their issue grouping.

Merge gate

No final qualification claim is allowed yet. All generated files must be synchronized and every retained legacy term intentional.

Issue #33 execution card — final qualification

Historical execution card — superseded. The operative v0.8 handoff is defined by the final status amendment: all tracked source changes precede the frozen candidate, and issue #33 qualifies the exact post-finalization commit accepted after independent review. v0.8.0 creates no new Zenodo software-version record. The card below is preserved as development history.

Context

Begin only after all R1–R9 children have independent acceptance and umbrella issue #35 is closed. Reconcile issue #33's older named-deferral wording with ADR 0017 before work starts. Use only the exact clean accepted R9 commit and current release scripts/workflows. Do not use donor binaries.

Expected output

  • any final tooling/workflow patch needed for complete installed-wheel tests, sanitizer coverage, licensing, or provenance;
  • one complete 21-distribution qualification run;
  • machine-readable manifest and human release checklist;
  • final release notes updated only after evidence exists.

Merge/release gate

A failed platform, missing artifact, missing license, donor contamination, untraceable build, or absent regression oracle blocks the release. Do not rebuild artifacts after qualification without rerunning the complete gate.

11. Regression ledger

Maintain a small table in the umbrella issue or release qualification record as work merges:

Contract Owning issue Suggested test area Required oracle
ADMM/L2 objective parity R1 tests/inverse/separator/ analytic objective and backend parity
Scalar penalty derivatives R1 inverse separator tests finite differences
Certified scalar prox R2 inverse separator tests independent bounded scalar minimizer/KKT
init_mem/native preconditions R3 forward spatial/planar subprocess tests process survives with Python exception
Exact IDs/shifts/options R3 forward common + inverse tests strict type matrix
Immutable domains/models R3 domain/model tests caller-mutation tests
Triclinic nearest image R4 inverse periodic tests exhaustive bounded lattice oracle
Periodic minimum distance R4 duplicate tests exhaustive/analytic oracle
Non-periodic containment R5 forward 2D/3D tests half-open boundary cases
Mandatory duplicate safety R5 subprocess forward tests no native exit under any public mode
Geometry/row identity R6 inverse result tests mismatch/equivalent-copy matrix
Report schema/provenance R6 report/API-contract tests exact JSON schema/round trip
Atomic active final state R7 active tests state-origin invariants
Severity-complete diagnostics R8 planar/spatial diagnostic tests explicit error/warning matrix
Distribution license/content R9/#33 tooling/installed-wheel tests archive member inspection
Artifact provenance #33 release tooling exact manifest/hash checks

Do not mark a row complete because a general test happens to pass. Point to the specific regression test and the independent oracle.

12. Native donor rules during remediation

The existing CPython 3.13 manylinux donor may accelerate Python-only work, but its validity is tied to the old native interface and implementation.

Issue Donor use
R1 Allowed if no native file/interface changes
R2 Allowed if no native file/interface changes
R3-A Not allowed after C++ changes begin; compile fresh native modules
R3-B Use the fresh R3-A native build, or create a new documented donor from that exact native contract
R4–R9 Use fresh native modules compatible with the latest merged source; do not assume the original donor remains valid
#33 Donor use forbidden; build all native artifacts from the clean candidate commit

After any change to cpp/, CMake, native signatures, returned native records, or the Python/native precondition contract, regenerate the donor if continued fast testing is needed. Record its native-source commit/fingerprint and never place it in release directories.

13. Replanning and stop conditions

Pause the current Codex task and return to maintainer/design review when:

  • a finding no longer reproduces after an earlier issue;
  • implementation would change a public signature, default, serialized field, or documented numerical result beyond the approved contract;
  • a new mandatory dependency appears necessary;
  • a vendored Voro++ modification appears necessary;
  • an independent oracle disagrees with both old and proposed implementations;
  • a paper/reproducibility benchmark changes unexpectedly;
  • a supposedly local issue requires reopening a merged issue’s scientific decision;
  • sanitizer output reveals a separate native defect;
  • issue scope becomes too broad for one reviewable PR.

The correct response is not to “finish anyway.” Update the issue, create a small dependent issue if necessary, and regenerate the exact Codex prompt.

14. Timing of the small-issue audit

Do not spend another broad audit cycle on spelling, presentation, and optional performance before R1–R8. Those corrections will change the relevant APIs and documentation, making early polish inefficient.

After R8:

  1. run repository-wide static searches and documentation/link checks;
  2. inspect packaging metadata and generated artifacts;
  3. classify remaining naming and wording inconsistencies;
  4. add only release-relevant small fixes to R9;
  5. preserve release-relevant deferrals in the roadmap or existing issues without freezing future issue grouping prematurely.

This is the intended place to catch minor issues without diluting the critical remediation.

15. Final release sequence

Historical sequence — superseded. The numbered sequence below records the original remediation plan. The operative release sequence is defined by the final status amendment.

After R9 merges:

  1. confirm all nine R1–R9 children are complete and close umbrella issue #35;
  2. begin separate final qualification issue #33;
  3. create the clean release-candidate commit;
  4. run local/source qualification and sanitizer jobs;
  5. run the complete CI source matrix;
  6. build and test all 20 wheels plus the sdist;
  7. validate installed packages, licensing, metadata, report schema, and removed surfaces;
  8. generate the provenance manifest and artifact hashes;
  9. complete the release-note issue/PR/test ledger;
  10. review the evidence manually;
  11. tag the exact qualified commit;
  12. publish the already-qualified artifacts to PyPI/GitHub and archive the same release on Zenodo.

Do not rebuild after tagging or publication unless the complete artifact gate is rerun and a new release candidate is created.

16. Definition of done

The remediation is complete when:

  • R1–R9 are merged with independent review;
  • the regression ledger is complete;
  • all release-relevant deferrals are documented, with exact future issue grouping allowed to remain for later planning under ADR 0017;

  • 33 passes from one clean exact commit after #35 is closed;

  • every artifact is traceable and includes required third-party licensing;
  • release notes describe evidence rather than plans;
  • no donor binary participates in the release build;
  • the released package cannot reproduce any confirmed P0/P1 safety or correctness defect from the final audit.