fix(core): harden command contracts for v1.3.2

[ikelaiah]

Pull Request: Release v1.3.2 - Contract Hardening

Target Release: v1.3.2

Release Date: 2026-07-30

Summary

This PR delivers the v1.3.2 roadmap milestone by correcting the mismatch
between the public ICommand contract and the runtime implementation, and by
clearly deprecating the non-functional custom-completion callback methods.

It also adds the maintenance roadmap, regression coverage, current
documentation, release notes, and version metadata for the patch release.

Type of Change

• Bug fix
• Backward-compatible interface addition
• API deprecation
• Regression test
• Documentation
• Breaking change

Contract Correction

• Add the optional ICommandParameterReceiver capability.
• Make TBaseCommand implement the receiver.
• Replace the unconditional ICommand-to-TBaseCommand downcast with a
  Supports() capability check.
• Remove the CLI.Command implementation dependency from
  CLI.Application.
• Verify that an independent ICommand implementation executes and
  returns its exit code.

Completion Callback Deprecation

• Mark RegisterFlagValueCompletion() as deprecated.
• Mark RegisterPositionalCompletion() as deprecated.
• Retain both methods as no-ops for 1.x source compatibility.
• State that removal is planned for v2.0.0.
• Confirm that built-in metadata completion is unaffected.

Documentation and Versioning

• Add ROADMAP.md with maintenance outcomes through v2.0.0.
• Update the API reference for ICommandParameterReceiver.
• Update the technical completion notes and architecture description.
• Add the dated 1.3.2 changelog entry and comparison links.
• Update the README badge to 1.3.2.
• Update Lazarus package metadata to 1.3.2.
• Add v1.3.2 release notes.
• Add this pull request note.

Compatibility

Existing TBaseCommand descendants require no changes. Existing application
factories, command registration calls, generated projects, and schema-version-1
manifests retain their behaviour.

Direct ICommand implementations no longer fail merely because they do not
inherit from TBaseCommand. The new receiver interface is optional.

The deprecated custom-completion methods remain callable in 1.x but can emit
compiler warnings. Removing calls to them is behaviour-preserving because the
methods were already no-ops.

Verification

• Framework suite: 39 tests, 0 errors, 0 failures.
• Interface-only command regression test.
• Deprecation compiler-warning smoke test.
• Windows generator unit tests.
• Generator golden-output test.
• Generated-project compile smoke test.
• Generator operations test.
• All seven example applications compiled.
• Lazarus runtime package build with metadata at 1.3.2.
• Local Markdown targets and fenced code blocks across 39 Markdown files.
• FPC 3.2.2.
• GitHub Actions after the PR is opened.

Release Readiness

• Release date finalized as 2026-07-30.
• Version metadata updated to 1.3.2.
• Changelog section dated and comparison links updated.
• Release notes prepared.
• Pull request notes prepared.
• Confirm GitHub Actions on Windows and Linux.

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