Merge branch 'issue-13-release-matrix-r060-stack' into release/0.6.0

Author: blackopsrepl

Makefile

@@ -195,9 +195,14 @@ publish-crates-dry: test banner
 	@printf "$(CYAN)$(BOLD)║              Pre-Publish Verification                    ║$(RESET)\n"
 	@printf "$(CYAN)$(BOLD)╚══════════════════════════════════════════════════════════╝$(RESET)\n\n"
 	@printf "$(GREEN)$(CHECK) All tests passed$(RESET)\n"
-	@printf "$(ARROW) Publishing order: $(GRAY)core → macros → scoring → config → solver → facade → cli$(RESET)\n\n"
-	@printf "$(GRAY)Note: cargo publish --dry-run cannot validate unpublished workspace inter-dependencies.$(RESET)\n"
-	@printf "$(GRAY)Tests passing indicates crates are ready. Use 'make publish-crates' to publish.$(RESET)\n\n"
+	@printf "$(ARROW) Publishing order: $(GRAY)core → macros → scoring → config → solver → cvrp → console → facade → cli$(RESET)\n\n"
+	@printf "$(PROGRESS) Running cargo publish --dry-run for standalone crates...\n"
+	@cargo publish --dry-run -p solverforge-core >/dev/null && printf "$(GREEN)$(CHECK) solverforge-core dry-run passed$(RESET)\n" || exit 1
+	@cargo publish --dry-run -p solverforge-macros >/dev/null && printf "$(GREEN)$(CHECK) solverforge-macros dry-run passed$(RESET)\n" || exit 1
+	@cargo publish --dry-run -p solverforge-console >/dev/null && printf "$(GREEN)$(CHECK) solverforge-console dry-run passed$(RESET)\n" || exit 1
+	@cargo publish --dry-run -p solverforge-cli >/dev/null && printf "$(GREEN)$(CHECK) solverforge-cli dry-run passed$(RESET)\n" || exit 1
+	@printf "$(GRAY)Dependent crates still need staggered dry-runs once their exact-version dependencies are visible on crates.io.$(RESET)\n"
+	@printf "$(GRAY)Run cargo publish --dry-run for scoring, config, solver, cvrp, and facade immediately before each upload.$(RESET)\n\n"
 
 publish-crates: banner
 	@printf "$(CYAN)$(BOLD)╔══════════════════════════════════════════════════════════╗$(RESET)\n"
@@ -207,25 +212,31 @@ publish-crates: banner
 	@printf "$(YELLOW)Press Ctrl+C to abort, or Enter to continue...$(RESET)\n"
 	@read dummy
 	@printf "\n$(PROGRESS) Publishing crates in dependency order...\n\n"
-	@printf "$(ARROW) [1/7] Publishing solverforge-core...\n"
+	@printf "$(ARROW) [1/9] Publishing solverforge-core...\n"
 	@cargo publish -p solverforge-core && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [2/7] Publishing solverforge-macros...\n"
+	@printf "$(ARROW) [2/9] Publishing solverforge-macros...\n"
 	@cargo publish -p solverforge-macros && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [3/7] Publishing solverforge-scoring...\n"
+	@printf "$(ARROW) [3/9] Publishing solverforge-scoring...\n"
 	@cargo publish -p solverforge-scoring && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [4/7] Publishing solverforge-config...\n"
+	@printf "$(ARROW) [4/9] Publishing solverforge-config...\n"
 	@cargo publish -p solverforge-config && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [5/7] Publishing solverforge-solver...\n"
+	@printf "$(ARROW) [5/9] Publishing solverforge-solver...\n"
 	@cargo publish -p solverforge-solver && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [6/7] Publishing solverforge (facade)...\n"
+	@printf "$(ARROW) [6/9] Publishing solverforge-cvrp...\n"
+	@cargo publish -p solverforge-cvrp && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
+	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
+	@printf "$(ARROW) [7/9] Publishing solverforge-console...\n"
+	@cargo publish -p solverforge-console && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
+	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
+	@printf "$(ARROW) [8/9] Publishing solverforge (facade)...\n"
 	@cargo publish -p solverforge && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "$(GRAY)Waiting 45s for crates.io index...$(RESET)\n" && sleep 45
-	@printf "$(ARROW) [7/7] Publishing solverforge-cli...\n"
+	@printf "$(ARROW) [9/9] Publishing solverforge-cli...\n"
 	@cargo publish -p solverforge-cli && printf "$(GREEN)$(CHECK) Published$(RESET)\n" || exit 1
 	@printf "\n$(GREEN)$(BOLD)╔══════════════════════════════════════════════════════════╗$(RESET)\n"
 	@printf "$(GREEN)$(BOLD)║          $(CHECK) All crates published successfully!            ║$(RESET)\n"
@@ -286,7 +297,7 @@ help: banner
 	@/bin/echo -e ""
 	@/bin/echo -e "$(CYAN)$(BOLD)Publishing:$(RESET)"
 	@/bin/echo -e "  $(GREEN)make publish-crates-dry$(RESET) - Dry-run publish to crates.io"
-	@/bin/echo -e "  $(GREEN)make publish-crates$(RESET) - $(RED)$(BOLD)Publish to crates.io (all 8 crates)$(RESET)"
+	@/bin/echo -e "  $(GREEN)make publish-crates$(RESET) - $(RED)$(BOLD)Publish to crates.io (all 9 publishable crates)$(RESET)"
 	@/bin/echo -e ""
 	@/bin/echo -e "$(CYAN)$(BOLD)CLI:$(RESET)"
 	@/bin/echo -e "  $(GREEN)make install-cli$(RESET)    - Install solverforge CLI binary"

README.md

@@ -83,6 +83,10 @@ solverforge = { version = "0.5", features = ["console"] }
 | `decimal` | Decimal score support via `rust_decimal` |
 | `serde` | Serialization support for domain types |
 
+## Release Operations
+
+The workspace release checklist, publish order, and crate stability matrix live in [RELEASE.md](RELEASE.md).
+
 ## Quick Start
 
 ### 1. Define Your Domain Model

RELEASE.md

@@ -0,0 +1,82 @@
+# Release Guide
+
+Release reference for the `release/0.6.0` line and later patch releases.
+
+## Stability Matrix
+
+| Crate | Status | Release Expectation | Notes |
+|-------|--------|---------------------|-------|
+| `solverforge-core` | Stable | Publish on every coordinated release | Foundational score/domain traits; lowest-level dependency |
+| `solverforge-macros` | Stable | Publish on every coordinated release | Proc-macro surface used by the facade and templates |
+| `solverforge-scoring` | Stable | Publish on every coordinated release | Constraint-stream and incremental scoring engine |
+| `solverforge-config` | Stable | Publish on every coordinated release | Runtime configuration consumed by the solver layer |
+| `solverforge-solver` | Stable | Publish on every coordinated release | Main solve engine and manager APIs |
+| `solverforge` | Stable | Publish on every coordinated release | Public facade crate and primary library entry point |
+| `solverforge-cli` | Beta | Publish when scaffold or operator workflow changes | User-facing binary; validate generated projects before release |
+| `solverforge-cvrp` | Beta | Publish on every facade version change | Required by the facade's exact-version dependency set |
+| `solverforge-console` | Beta | Publish on every facade version change | Required for the facade's exact-version optional `console` feature |
+| `solverforge-test` | Internal | Do not publish | Shared test fixtures only |
+
+Status definitions:
+
+- `Stable`: public API expected to remain coherent across the release line; regressions block release.
+- `Beta`: supported and versioned, but still more likely to receive usability and coverage fixes between patch releases.
+- `Internal`: workspace-only support crate; not part of the published product surface.
+
+## Publish Order
+
+When versions change across the workspace, publish crates in dependency order:
+
+1. `solverforge-core`
+2. `solverforge-macros`
+3. `solverforge-scoring`
+4. `solverforge-config`
+5. `solverforge-solver`
+6. `solverforge-cvrp`
+7. `solverforge-console`
+8. `solverforge`
+9. `solverforge-cli`
+
+`solverforge-test` stays unpublished.
+
+## Release Checklist
+
+1. Confirm the release branch is correct.
+   Use `release/0.6.0` as the base for this release line.
+2. Confirm all release-blocking PRs are merged.
+   Verify open issues/PRs targeted at the release branch are either merged or explicitly deferred.
+3. Sync version and changelog state.
+   Update `CHANGELOG.md` and ensure workspace crate versions are coherent.
+4. Validate canonical docs.
+   Check `README.md`, crate `WIREFRAME.md` files, and this document for stale public-surface details.
+5. Run formatting and lint gates.
+   `cargo fmt --all -- --check`
+   `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+6. Run test gates.
+   `cargo test --workspace --all-features`
+   `make pre-release`
+7. Validate scaffolded user flows.
+   Run `cargo test -p solverforge-cli`
+   Run ignored scaffold cargo-check tests if template-affecting changes landed.
+8. Verify publishability.
+   Run real package dry-runs for crates that can be verified before publish:
+   `cargo publish --dry-run -p solverforge-core`
+   `cargo publish --dry-run -p solverforge-macros`
+   `cargo publish --dry-run -p solverforge-console`
+   `cargo publish --dry-run -p solverforge-cli`
+   For dependent crates (`solverforge-scoring`, `solverforge-config`, `solverforge-solver`, `solverforge-cvrp`, `solverforge`), rerun `cargo publish --dry-run -p <crate>` immediately before uploading each crate, after its exact-version dependencies are visible on crates.io.
+9. Publish crates in dependency order.
+   Use `make publish-crates` or publish manually in the order listed above.
+10. Post-publish verification.
+    Confirm crates.io versions, docs.rs builds, and install smoke tests:
+    `cargo install solverforge-cli --version <version>`
+    `cargo add solverforge@<version>`
+
+## Release Notes Inputs
+
+Capture these before tagging:
+
+- Merged PR list against `release/0.6.0`
+- Breaking public-surface changes, if any
+- New templates, commands, macros, or helper APIs
+- New validation coverage or release-risk reductions