[platform] Publish a portable inspectable CLI specification artifact

[codeforester]

Goal

Let every managed CLI publish a versioned, machine-readable description without importing or executing implementation-specific internals.

Background

The packaged schemas at https://github.com/basefoundry/base-cli/blob/8a93d22156ba75a99965f7c355f867acba630069/lib/python/base_cli/schemas/v1 describe base-cli wire records. They do not describe a CLI's ownership, command topology, operational risk, supported platforms, dependencies, data sensitivity, or lifecycle contract.

A multi-language platform needs one portable artifact that a Python wheel, Go binary, Rust binary, Node package, JVM archive, or .NET tool can embed and expose.

Scope

• Define a JSON Schema for cli-spec.yaml and canonical JSON.
• Cover stable identity/version, owning team, escalation/runbook links, maturity/support tier, command/capability topology, supported platforms, dependencies, output/exit contracts, authentication, data classification, destructive behavior, deprecation, and specification version.
• Define an offline inspection command such as spec --output json.
• Define build-time embedding, digesting, and provenance metadata.
• Provide authoring and validation tools independent of base-cli runtime imports.

Acceptance Criteria

• The schema is parser- and language-neutral, versioned, and published at a stable URL.
• A CLI can return the canonical artifact offline with no network, config mutation, plugin loading, or credential access.
• Unknown future fields have an explicit forward-compatibility rule.
• Secret values and environment-specific credentials are forbidden and validated.
• Digest/source revision/build provenance can be verified.
• Reference artifacts exist for one base-cli application and at least one non-Python CLI.
• CI detects schema drift and stale embedded artifacts.
• The implementation/repository ownership decision is explicit; base-cli contains only its adapter if the platform resource is extracted.

Validation

Validate valid/invalid fixtures with at least two independent language implementations and inspect built wheel/binary artifacts from clean installations.

Non-Goals

• Do not make the spec a remote service.
• Do not scrape source repositories to infer authoritative fields.
• Do not put runtime secrets or live health data in the artifact.

Dependencies

• cli-platform/v1 behavioral contract
• [v1.0] Publish JSON Schema artifacts for machine contracts #240
• [v1.0] Add golden cross-language contract fixtures and validators #241

Project Fields

• Status: Backlog
• Priority: P1
• Area: Product
• Initiative: v1.0 Readiness
• Size: L

Ownership

• Assignee: @codeforester