feat(#146): implement major-zero behavior for Nova version bumps

- Maintain breaking-change bumps on the 0.y.z line for stable versions.
- Plan the next minor version instead of jumping to 1.0.0.
- Print guidance for manually setting 1.0.0 once the software is stable.

Author: stiwicourage

CHANGELOG.md

@@ -1,28 +1,33 @@
 # Changelog
 
-All notable changes to this project will be documented in this file and **PreReleased/UNRELEASED** changes will be
-included in the
-next **stable** release!
+All notable changes to this project will be documented in this file and **PREVIEW / UNRELEASED** changes will be
+included in the next **stable** release!
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
 ### Added
 
-### Fixed
-
 ### Changed
 
-### Documentation
+- Keep stable `Update-NovaModuleVersion` / `% nova bump` releases on the SemVer major-zero development line.
+    - When the current stable version is `0.y.z` and commit history implies a breaking change, Nova now plans the next
+      minor version instead of auto-jumping to `1.0.0`.
+    - The bump result still reports the detected `Major` label and now prints guidance about manually setting `1.0.0`
+      once the software is stable.
+    - `-Preview` behavior is unchanged.
+
+### Deprecated
 
 ### Removed
 
-## [2.1.0] - 2026-04-29
+### Fixed
 
-### Added
+### Security
 
+## [2.1.0] - 2026-04-29
+### Added
 - Add `Install-NovaCli` and a packaged `nova` launcher so macOS and Linux users can install and run `nova` directly
   from zsh or bash.
     - `nova` now remains the launcher-facing CLI surface, while `Invoke-NovaCli` stays the explicit PowerShell cmdlet
@@ -108,22 +113,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `nova bump --what-if` and `% run.ps1` now surface a predictable summary for previous version, new version, label,
       and commit count.
 
-### Fixed
-
-- Fix unsupported `nova` help invocations so they now return Nova's structured CLI validation error instead of a
-  PowerShell parameter-binding failure.
-- Keep manifest/package helper edge cases aligned with their intended behavior.
-    - Manifest settings resolution now accepts ordered dictionary metadata shapes in addition to plain hashtables.
-    - `New-NovaPackageArtifacts` now accepts an empty metadata list and returns an empty artifact result instead of
-      failing during parameter binding.
-- Fix configuration and validation errors so empty `project.json` files and unsupported `Manifest` keys fail fast with
-  clear messages.
-- Fix semantic-release PSGallery publishing on fresh CI runners by bootstrapping the PSResourceGet repository store
-  before
-  `Publish-PSResource` runs.
-
 ### Changed
-
 - Change the project to a Nova command model, replacing the previous mixed MT/Nova workflow.
     - All public commands are now Nova commands, and the `nova` CLI / `Invoke-NovaCli` command surface is the primary
       entry point for all operations.
@@ -143,35 +133,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Change `Publish-NovaModule -Local` and `% nova publish --local` so a successful local publish also reloads the
   published module from the local install path into the active PowerShell session.
 
-### Documentation
-
-- Split documentation into contributor-focused repository docs and task-oriented GitHub Pages user guides.
-- Expand the public site into a fuller developer end-user manual with rewritten getting started, core workflows, working
-  with modules, troubleshooting, concepts, release notes, and license pages plus new reference-style pages for
-  commands, `project.json`, packaging/delivery, and versioning/update behavior.
-    - The guides now let readers switch between PowerShell and command-line examples, including the local-publish-plus-
-      `pwsh` handoff for `Get-ExampleGreeting` and fresh-process `pwsh`
-- Clean the generated PowerShell cmdlet help so `Get-Help` pages no longer mix in `nova` launcher syntax or GNU-style
-  CLI options.
-- Refresh public `Get-Help` content and examples for the Nova commands, including CLI usage and preview/confirmation
-  scenarios.
-    - Simplify `Invoke-NovaCli` help so it matches the launcher-vs-cmdlet split cleanly and PlatyPS can generate command
-      help without failing during local builds.
-- Update the `nova` CLI documentation and help text to use POSIX/GNU-style long and short options while keeping
-  PowerShell cmdlet examples in their native PowerShell form.
-
 ### Removed
-
 - **BREAKING CHANGE**: Remove the legacy `MT` commands and MT-branded command documentation in favor of the Nova command
   model.
     - All public commands are now Nova commands, and the `nova` CLI / `Invoke-NovaCli` command surface is the primary
       entry point for all
       operations.
 
-## [1.9.0] - 2026-04-10
+### Fixed
 
-### Added
+- Fix unsupported `nova` help invocations so they now return Nova's structured CLI validation error instead of a
+  PowerShell parameter-binding failure.
+- Keep manifest/package helper edge cases aligned with their intended behavior.
+    - Manifest settings resolution now accepts ordered dictionary metadata shapes in addition to plain hashtables.
+    - `New-NovaPackageArtifacts` now accepts an empty metadata list and returns an empty artifact result instead of
+      failing during parameter binding.
+- Fix configuration and validation errors so empty `project.json` files and unsupported `Manifest` keys fail fast with
+  clear messages.
+- Fix semantic-release PSGallery publishing on fresh CI runners by bootstrapping the PSResourceGet repository store
+  before
+  `Publish-PSResource` runs.
 
+## [1.9.0] - 2026-04-10
+### Added
 - Nova command model and CLI entrypoint:
     - New root command: `nova`
     - New public commands: `Get-NovaProjectInfo`, `Invoke-NovaBuild`, `Invoke-NovaCli`, `Invoke-NovaRelease`,
@@ -182,21 +166,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New GitHub workflow: PowerShell code quality (`.github/workflows/powershell.yml`).
 
 ### Changed
-
 - Updated test workflow triggers in `.github/workflows/Tests.yml` to improve branch/PR coverage.
 - Updated README module naming references to `NovaModuleTools`.
 - Source alignment updates to match installed `NovaModuleTools` v`1.8.0` behavior for compatibility.
 
-### Fixed
-
-- Resource lookup compatibility in `Get-ResourceFilePath` for source/dist execution contexts.
+### Deprecated
 
-### Documentation
+- `MT` commands and MT-branded command documentation in favor of the Nova command model.
 
-- Added documentation and release notes context for the Nova command model and workflow/security updates.
+### Fixed
+- Resource lookup compatibility in `Get-ResourceFilePath` for source/dist execution contexts.
 
 ## [1.8.0] - 2026-04-08
-
 ### Added
 - Project settings:
     - `BuildRecursiveFolders` (default `true`): recursive discovery for `src/classes`, `src/private` and `tests`.
@@ -210,15 +191,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Build determinism: files are processed in a deterministic order by relative path (case-insensitive), and load order is always `classes → public → private`.
 
-### Documentation
-- README: document enterprise defaults, deterministic load order, and duplicate-function validation.
-
 ## [1.3.0] - 2025-09-23
-
 - Added support for `ps1xml1` format data. Place it in resources folder with `Name.format.ps1xml` to be automatically added as format file and imported in module manifest
 
 ## [1.2.0] - 2025-09-17
-
 ### Added
 - Added support for classes directory inside src
 - Initialize-NovaModule generates classes directory during fresh project
@@ -228,74 +204,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Version upgrade using update-mtmoduleversion now support build tags. Improvements to semver versioning.
 
 ## [1.1.3] - 2025-09-14
-
 ### Added
-
 - Now supports preview tag in Update-NovaModuleVersion
 - Now supports semver naming in both project.json and modulemanifest
 - Module build supports `preview` or `prerelease` tag
 - Preview version looks like `1.2.3-preview`
 
 ## [1.1.0] - 2025-08-28
-
 ## Added
-
 - Now Module manifest includes `AliasesToExport`. This helps loading aliases without explicitly importing modules to
   session.
 - thanks to @djs-zmtc for suggesting the feature
 
 ## [1.0.0] - 2025-03-11
-
 ### Added
-
 - New optional project setting `CopyResourcesToModuleRoot`. Setting to true places resource files in the root directory
   of module. Default is `false` to provide backward compatibility. Thanks to @[BrooksV](https://github.com/BrooksV)
 
 ### Fixed
-
 - **BREAKING CHANGE**: Typo corrected: ProjecUri to ProjectUri. Existing projects require manual update.
 
 ## [0.0.9] - 2024-07-17
-
 ### Fixed
-
 - Fixed #7, Invoke build should not through for empty tags
 
 ## [0.0.7] - 2024-07-17
-
 ### Added
-
 - Now "Manifest" section of project JSON supports all Manifest parameters, use exact name of parameter (from New-ModuleManifest) as key in JSON
 
 ## Fixed
-
 - Fixed the example project README so it no longer suggests that `example/` includes a `run.ps1` helper script; it now
   points users to building `NovaModuleTools` from the repository root or using the Gallery workflow.
 - Corrected typo in ProjectUri from `ProjecUri` to correct spelling.
 
 ## [0.0.6] - 2024-07-08
 
 ### Added
-
 - `Test-NovaBuild` now supports including and excluding tags
 
 ### Fixed
-
 - Code cleanup
 
 ## [0.0.5] - 2024-07-05
-
 ### Added
-
 - More verbose info during MTModule creation
 
 ### Fixed
-
 - Issue #2 : Git initialization implemented
 - Issue #1 : Doesn't create empty `tests` folder when user chooses `no` to tests
 
 ## [0.0.4] - 2024-06-25
-
 ### Added
 - First release to `psgallery`
 - All basic functionality of Module is ready
@@ -339,4 +297,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.0.6]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.5...Version_0.0.6
 [0.0.5]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.4...Version_0.0.5
 [0.0.4]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.3...Version_0.0.4
-

README.md

@@ -212,10 +212,16 @@ These switches keep the behavior explicit and opt-in:
 - `Update-NovaModuleVersion -ContinuousIntegration` also falls back to a patch bump when the current `HEAD` already
   matches the latest tag, so release automation can seed the next prerelease line without requiring an extra commit
   first
+- `Update-NovaModuleVersion` and `% nova bump` treat stable `0.y.z` versions as the SemVer initial-development phase,
+  so breaking-change bumps stay on the `0.y.z` line by planning the next minor version instead of jumping to `1.0.0`
 - `Publish-NovaModule -ContinuousIntegration` restores the built module after publish completes
 - `Invoke-NovaRelease -ContinuousIntegration` forwards that CI intent through the nested build/bump boundaries and then
   restores the built module again after publish
 
+When Nova reports that a breaking-change bump was detected while the current stable version is still `0.y.z`, it also
+prints guidance about manually setting `1.0.0` once the software is stable. Preview bumps keep their current behavior
+and are not remapped by this rule.
+
 Useful local helper:
 
 ```powershell

docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md

@@ -42,6 +42,11 @@ The release label is inferred from the commit set:
 - `Minor` for `feat:` commits
 - `Patch` for `fix:` commits and all other cases
 
+When the current stable version is still on `0.y.z` and the inferred label is `Major`, Nova keeps the release on the
+initial-development line and plans the next minor version instead of jumping straight to `1.0.0`. The result still
+reports the detected `Major` label so you can see that the commit set contained a breaking change, and Nova prints
+guidance about manually setting `1.0.0` once the software is stable. `-Preview` behavior stays unchanged.
+
 When Git tags exist, only commits since the latest tag are considered. If the folder is not a Git repository, the
 command falls back to a patch bump.
 
@@ -162,6 +167,23 @@ PS> Update-NovaModuleVersion -ContinuousIntegration
 
 Re-imports the built `dist/<ProjectName>/<ProjectName>.psd1` first and then runs the normal version bump workflow.
 
+### EXAMPLE 9
+
+```text
+PS> Update-NovaModuleVersion -WhatIf
+
+What if: Performing the operation "Update module version using Major release label" on target "project.json".
+WARNING: Major version zero (0.y.z) is for initial development, so Nova keeps breaking-change bumps on the 0.y.z line and plans the next minor version instead of 1.0.0. Set 1.0.0 manually once the software is stable; after that, automatic major-version bumps work normally.
+
+PreviousVersion: 0.1.0
+NewVersion: 0.2.0
+Label: Major
+CommitCount: 34
+```
+
+Shows how breaking-change commits stay on the `0.y.z` initial-development line for stable bumps, while still warning
+that `1.0.0` should be set manually when the API becomes stable.
+
 ## PARAMETERS
 
 ### -Path

docs/commands.html

@@ -476,6 +476,10 @@ <h3><code>Update-NovaModuleVersion</code> / <code>% nova bump</code></h3>
                             <li><strong>Notable behavior:</strong> falls back to a patch bump when the folder is not a
                                 Git repository, but throws when the repository exists and has no commits yet
                             </li>
+                            <li><strong>Major-zero rule:</strong> stable <code>0.y.z</code> projects keep
+                                breaking-change
+                                bumps on the initial-development line, so a detected <code>Major</code> bump plans the
+                                next minor version until you manually set <code>1.0.0</code></li>
                             <li><strong>Prerelease rule:</strong> finalizes matching prerelease targets like
                                 <code>2.0.0-preview7 -&gt; 2.0.0</code> instead of carrying the old prerelease label
                                 into

docs/versioning-and-updates.html

@@ -165,6 +165,15 @@ <h3>How Nova chooses the bump label</h3>
                     <li><strong>Minor</strong> for <code>feat:</code> commits</li>
                     <li><strong>Patch</strong> for <code>fix:</code> commits and all other cases</li>
                 </ul>
+                <p>While your project is still on a stable <code>0.y.z</code> version, Nova treats SemVer major zero as
+                    the initial-development phase. A breaking-change bump still reports the detected
+                    <strong>Major</strong> label, but the planned stable version stays on the <code>0.y.z</code> line by
+                    advancing to the next minor version instead of jumping to <code>1.0.0</code>. Nova also prints a
+                    reminder to set <code>1.0.0</code> manually once the API is stable. Preview mode stays unchanged.
+                </p>
+                <pre><code>0.0.1 + Patch -> 0.0.2
+0.1.0 + Minor -> 0.2.0
+0.1.0 + Major -> 0.2.0</code></pre>
                 <p>When Git tags exist, Nova uses commits since the latest tag. When the folder is not a Git repository,
                     Nova falls back to a patch bump. When the repository exists but has no commits yet, Nova stops with
                     a clear error.</p>

src/private/cli/FormatNovaCliCommandResult.ps1

@@ -47,7 +47,29 @@ function Format-NovaCliVersionUpdateResult {
         'Version plan:'
     }
 
-    return "$summaryPrefix $( $Result.PreviousVersion ) -> $( $Result.NewVersion ) | Label: $( $Result.Label ) | Commits: $( $Result.CommitCount )"
+    $summary = "$summaryPrefix $( $Result.PreviousVersion ) -> $( $Result.NewVersion ) | Label: $( $Result.Label ) | Commits: $( $Result.CommitCount )"
+    $advisoryMessage = Get-NovaCliVersionUpdateAdvisoryMessage -Result $Result
+    if ( [string]::IsNullOrWhiteSpace($advisoryMessage)) {
+        return $summary
+    }
+
+    return @(
+        $summary
+        $advisoryMessage
+    ) -join [Environment]::NewLine
+}
+
+function Get-NovaCliVersionUpdateAdvisoryMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    if ($Result.PSObject.Properties.Name -notcontains 'AdvisoryMessage') {
+        return $null
+    }
+
+    return $Result.AdvisoryMessage
 }
 
 function Format-NovaCliCommandResult {