feat(release): stabilize before expanding

[ikelaiah]

Pull Request: Release v1.3.3 - Stabilize Before Expanding

Target Release: v1.3.3

Release Date: 2026-08-14

Summary

This PR delivers the focused v1.3.3 roadmap milestone. It makes example
cleanup safe, replaces placeholder help tests with behavioural assertions,
accepts separated negative integer and float values, protects password debug
values, reduces internal application complexity, and keeps all seven canonical
examples buildable in Windows and Linux CI.

The release adds no public command API, parameter kind, generator capability,
or completion feature.

Type of Change

• Bug fix
• Regression test
• CI coverage
• Documentation
• Breaking change

Safe Example Cleanup

• Restrict Bash and PowerShell cleanup scripts to generated compiler
  artifacts.
• Preserve tracked completion scripts, documentation, and other
  repository files.
• Add isolated Bash and PowerShell cleanup smoke checks.
• Compile all seven canonical examples before each cleanup check.
• Verify generated binaries are removed and tracked files remain unchanged.

Help Coverage

• Add an internal output-capture seam for framework tests.
• Keep output capture out of normal builds and retain the public
  ICLIApplication API unchanged.
• Replace placeholder tests with assertions for usage, descriptions,
  required options, defaults, complete help, and subcommands.

Parser Correctness

• Accept --count -1 for registered integer options.
• Accept --rate -2.5 for registered float options.
• Retain existing equals syntax such as --count=-1.
• Confirm unknown options still fail validation and prevent command
  execution.

Internal Maintenance and Diagnostics

• Force isolated framework unit rebuilds on Windows and Linux.
• Exclude capture-specific state and entry points from normal builds.
• Redact separated and equals-form password values in framework debug
  output.
• Share one parameter-value implementation across validation and command
  execution.
• Consolidate application and base-command help formatting.
• Extract completion calculation and remove unreachable private callback
  paths and unused temporary allocations.
• Decompose application dispatch while preserving the public facade.

CI, Documentation, and Versioning

• Configure the example build-and-cleanup smoke check in Windows and Linux CI.
• Run that CI check when runtime, example, cleanup-script, test, or
  workflow files change.
• Update the README and user manual with negative-value behaviour and the
  cleanup smoke command.
• Add the dated v1.3.3 changelog entry and release notes.
• Update Lazarus package metadata to 1.3.3.
• Add this pull request note.

Compatibility

No migration is required. Existing command registration, validation,
completion, generator behaviour, and schema-version-1 projects remain
compatible.

The parser accepts a separated leading - only when it is a valid integer or
float value for the registered option. Values beginning with - for other
parameter kinds continue to require equals syntax.

Verification

• Framework suite: 43 tests, 0 errors, 0 failures.
• Separated and equals-form negative integer and float regression coverage.
• Unknown-option regression coverage.
• Windows example build-and-cleanup smoke check covering all seven examples.
• Windows generator unit, golden-output, compile-smoke, and operations
  suites.
• Lazarus runtime package build in an isolated clean source copy with version
  metadata at 1.3.3.
• git diff --check passes.
• FPC 3.2.2.
• GitHub Actions on Windows and Linux after the PR is opened.

Release Readiness

• Release date finalized as 2026-08-14.
• Version metadata updated to 1.3.3.
• Changelog and release notes prepared.
• Pull request notes prepared.
• Confirm GitHub Actions on Windows and Linux.

After merge, create the v1.3.3 tag and publish the prepared release notes.