solverforge-cli 4.0.x: Two-File Constraint Layout, Scaffolding SolverForge 0.26.1

solverforge-cli 4.0.4 was published on November 11, 2026, a day after 4.0.0, 4.0.1, 4.0.2, and 4.0.3, which followed 3.9.0, the line that scaffolds solverforge 0.25.0. solverforge-cli 4.0.4 targets solverforge 0.26.1; 4.0.0 and 4.0.1 target solverforge 0.25.1, and 4.0.2 and 4.0.3 target solverforge 0.26.0 with the same project layout as 4.0.4. The web shell keeps solverforge-ui 0.9.1 and solverforge-maps 2.3.3, and the MCP shell keeps rmcp 3.9.0. 4.0.0 is a breaking release: generate, destroy, and check read the constraint set from two files, so an app generated by an earlier line needs the one-time move in the Upgrade Checklist before 4.0.x can edit it.

What Changed

Fresh scaffolds target SolverForge 0.26.1 (4.0.4)

New projects pin solverforge 0.26.1, and solverforge --version reports Scaffold runtime target: SolverForge crate target 0.26.1. The generated files, solver.toml, and the UI, maps, and MCP targets are the same as in 4.0.3, and the solverforge-modeling skill describes 4.0.4 and 0.26.1. A generated app’s late_acceptance phases keep their score history across soft-level improvements; see the 0.26.x release note (#17).

Constraint assembly lives in src/constraints/assemble.rs — breaking change

A generated project keeps its constraint set in two files:

• src/constraints/mod.rs holds the managed constraint-modules block of mod lines, mod assemble;, and pub use assemble::create_constraints;.
• src/constraints/assemble.rs holds create_constraints and the managed constraint-calls block, which calls each module as super::<id>::constraint().

generate constraint writes src/constraints/<id>.rs and updates both files; destroy constraint removes the module line and the call. The two blocks are matched by name: the mod lines stay in rustfmt’s sorted order, and the calls keep insertion order, which is the constraint set’s evaluation order.

// src/constraints/assemble.rs
pub fn create_constraints() -> impl ConstraintSet<Plan, HardSoftScore> {
    // @solverforge:begin constraint-calls
    (
        super::task_assigned::constraint(),
        super::balanced_duration::constraint(),
    )
    // @solverforge:end constraint-calls
}

Module roots hold declarations only

Every mod.rs and lib.rs under src/ contains only module declarations, use items, and, in src/domain/mod.rs, the planning_model! manifest. solverforge check reports any function, type, impl, constant, static, macro definition, inline module body, or non-documentation inner attribute in those files and names the item to move; generate constraint and destroy constraint refuse to edit a src/constraints/mod.rs that holds code (#8).

check accepts entity-scoped value ranges

A scalar variable’s value_range_provider may name a Vec<usize> field on the same entity, which gives each entity its own legal domain. solverforge check accepts it alongside solution fact collections and reports a provider that is neither (#6).

The solverforge-modeling skill loads in agents that scan skills (4.0.3)

The skill’s scripts/solve-smoke-test.sh saves the app’s /demo-data and POST /jobs responses to files in its temporary directory and reads them with python3. Through 4.0.2 it piped those curl responses straight into python3, a pattern that agent skill scanners treat as remote code execution: Hermes Agent rated the whole skill dangerous and refused to load it, so a project set up with ./scripts/install-skill --project <dir> gave a Hermes session no solverforge-modeling skill. The 4.0.3 skill scans as safe and loads. The smoke test itself is unchanged: it builds the app, boots it, solves the default demo data, and requires a COMPLETED job with a score (#15). Generated projects and scaffold targets are the same as in 4.0.2.

Fresh scaffolds target SolverForge 0.26.0 (4.0.2)

New projects pin solverforge 0.26.0, and solverforge --version reports Scaffold runtime target: SolverForge crate target 0.26.0; 4.0.0 and 4.0.1 scaffold solverforge 0.25.1. Generated apps never construct a score director directly, so the 0.26.0 change to replica-director construction does not reach them, and the generated solver.toml is unchanged (#13).

Constraint listing follows the manifest (4.0.1)

The constraint ids that solverforge info, solverforge.app.toml, the web shell’s static/generated/ui-model.json, and destroy’s dependent-constraint hints report are the modules in the constraint-modules block. A helper module declared outside that block, such as mod shared; or #[cfg(test)] mod tests;, is not listed as a constraint, and a block whose modules and calls disagree is reported instead of guessed around (#11).

Published Version Boundaries

The 4.0.0 GitHub Release was published at 2026-11-10T00:42:04Z, and crates.io records the package at 2026-11-10T00:42:30Z. Its artifact (SHA-256 6c78ad746eed5a3088ea2a54342ff0e0cbf3059a57c11d00c06b3215d837b585) was built from the tag commit bd43abb00a4079450b5b8275d0538b47a2da686e, where the CI run passed on Linux, macOS, and Windows plus the integration tests, and the Publish and Release workflows succeeded.

crates.io records 4.0.1 at 2026-11-10T02:28:53Z, and its GitHub Release was published at 2026-11-10T02:42:52Z. Its artifact (SHA-256 b48647fc356fa419580c58596d5d7247565cf402ec34cefc3f20f913f569ad11) was built from the tag commit 21d405519c41bc773b3bc27ba1280ae0d29081f8, where the CI run passed on Linux, macOS, and Windows plus the integration tests, and the Publish and Release workflows succeeded.

The 4.0.2 GitHub Release was published at 2026-11-10T12:14:03Z, and crates.io records the package at 2026-11-10T12:23:03Z. Its artifact (SHA-256 b8e0e989da0e8531d2def434243de35dcc2afa99689bfeb873f3ee82228fe28e) was built from the tag commit 9a780eaf9d6a77bfb6f311ba943558faced14935, where the CI run passed on Linux, macOS, and Windows plus the integration tests, and the Publish and Release workflows succeeded.

crates.io records 4.0.3 at 2026-11-10T16:00:13Z, and its GitHub Release was published at 2026-11-10T16:08:17Z. Its artifact (SHA-256 e94c83bda45341f815cecd73bad3e80186004f9a2e0de40028170a6a9cdc4745) was built from the tag commit 5f2cafaa09a1d27ca4a6aa37e829a42138a2ee07, where the CI run passed on Linux, macOS, and Windows plus the integration tests, and the Publish and Release workflows succeeded.

The 4.0.4 GitHub Release was published at 2026-11-11T05:13:57Z, and crates.io records the package at 2026-11-11T05:14:05Z. Its artifact (SHA-256 63adb8f592464b8cafe04dbe7556824fd221dc3b83794241b4e5de64bacc39f9) was built from the tag commit 5d879665ec375b154d72f00dfcadf8613216b159, where the CI run passed on Linux, macOS, and Windows plus the integration tests, and the Publish and Release workflows succeeded.

Patch History

Upgrade Checklist

• Install with cargo install solverforge-cli --version 4.0.4 --locked --force and inspect solverforge --version.
• Replace an installed solverforge-modeling skill by running ./scripts/install-skill again, with the same --agent, --project, or --dir options, from a solverforge-cli checkout at v4.0.4.
• Upgrading the CLI does not change existing apps, but 4.0.x generate, destroy, and check fail on a project that still assembles its constraints in src/constraints/mod.rs. Move it once:
  1. Create src/constraints/assemble.rs with the use items create_constraints needs and the function itself, including its // @solverforge:begin constraint-calls and // @solverforge:end constraint-calls markers.
  2. Prefix every call in that block with super::, as in super::minimum_rest::constraint().
  3. Leave src/constraints/mod.rs with its doc comment, the constraint-modules block, mod assemble;, and pub use assemble::create_constraints;.
• Move any other code out of mod.rs and lib.rs files into modules of its own, and drop inner attributes such as #![cfg_attr(rustfmt, rustfmt_skip)] from those files; solverforge check names each item it rejects.
• Keep helper modules such as shared or tests outside the constraint-modules block.
• To move an app to solverforge 0.26.1, change its solverforge dependency (and any direct solverforge-* dependency) and the [runtime] lines of solverforge.app.toml; the 0.26.x upgrade checklist covers code that builds a ScoreDirector directly.

Where to read next

• Project Anatomy
• CLI Getting Started
• Operations Commands
• Agent Skills
• Complete 3.9.0 to 4.0.4 comparison
• 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4 GitHub Releases