Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): require complete response schema projection (#6095)

Cindy Zhanga6078be2be20
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
index 923c2936e1..691312163d 100644
--- a/docs/architecture/cli-surface.md
+++ b/docs/architecture/cli-surface.md
@@ -20,7 +20,7 @@ verified_by:
foundation/response/error-codes.test.mjs,
clients/cli/formatters/index.test.mjs,
]
-deciding_specs: []
+deciding_specs: [spec:AST-017/DEC-4]
---
# CLI surface architecture
@@ -66,6 +66,9 @@ integrations named in `astryx.config`. Each integration is loaded
independently, so one broken package degrades that package's contribution and
never fails the run.
+AST-017 DEC-4 owns stable response-entry fields and requires their complete type,
+test, applicable text, and consumer-documentation projections.
+
## Boundaries and invariants
- **INV1 — The CLI never asks a question.** No prompt, no TTY detection, no
@@ -115,7 +118,8 @@ updated in the same pull request when it moves an invariant:
- adding, removing, or renaming a command or subcommand;
- adding an error code, or changing what an existing code means;
-- adding a field to the JSON envelope, or changing the shape of one;
+- a change to a stable JSON envelope or discriminated response-entry field
+ follows `spec:AST-017/DEC-4`;
- adding a formatter, or writing to stdout from anywhere other than `emit` and
`jsonOut`;
- changing the file layout under `clients/cli/commands`.
@@ -144,8 +148,8 @@ non-interactive guarantee.
## Deciding specs
-None yet. This record describes behaviour that is already shipped. A change to
-an invariant above needs a system spec.
+- `spec:AST-017/DEC-4` — stable response fields and their complete projections
+ are current compatibility authority.
## Verification
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 4c3c920482..bd9725728b 100644
--- a/docs/specs/AST-017/spec.md
+++ b/docs/specs/AST-017/spec.md
@@ -10,7 +10,8 @@ approved_by: cixzhang
approved_at: 2026-09-02
phase: accepted
owners: [cixzhang, josephfarina]
-affects_architecture: [architecture:public-component-api]
+affects_architecture:
+ [architecture:public-component-api, architecture:cli-surface]
affects_families: []
affects_contributing: [contributing:release-process, contributing:templates]
affects_consumer_docs: [release-process, templates]
@@ -114,6 +115,13 @@ preserves the released contract.
adapter when needed; otherwise classify the narrower or higher-floor range as
breaking, describe the range change in its Changeset release note, and meet FR8's
migration obligation.
+- **FR13 — Stable machine schemas project every field.** A stable CLI response
+ contract includes fields inside discriminated `data` entries as well as the
+ outer envelope. Every field is present in the canonical response type, contract
+ tests, text projection where the command provides one, and complete
+ consumer-facing schema documentation. Adding an optional field is nonbreaking
+ when old consumers continue unchanged, but it remains a public schema update and
+ does not bypass current-authority review or documentation.
### Platform support
@@ -141,18 +149,20 @@ updates:
- changing or completely rebuilding the template's emitted starter page updates
content for future generations without modifying projects that already copied it.
-The stable compatibility boundary remains the CLI operation and response schema,
-not the individual entries currently present in the template catalog.
+The stable compatibility boundary remains the CLI operation and complete response
+schema, not the individual entries currently present in the template catalog.
+Nested entry fields are public schema even when optional; their type, tests, text
+projection where present, and consumer schema documentation move together.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |
-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |
-| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |
-| FR9–FR11 | CLI contract tests plus template catalog and output tests | slug rename, metadata edit, source rebuild, command or schema change | Catalog data is frozen as API, or a command/schema incompatibility is mislabeled as a catalog-only edit |
-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |
+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |
+| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |
+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |
+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |
## Decision log
@@ -207,6 +217,23 @@ Rejected: marking every dependency bump breaking, which would freeze compatible
maintenance, or calling an update nonbreaking merely because a coordinated upgrade
works, which would break supported independent consumers.
+### DEC-4 — Stable CLI response fields receive complete projections
+
+**Reference:** `spec:AST-017/DEC-4`
+**Decider:** `cixzhang`, `2026-09-06`
+
+Treat every field in a stable machine-readable CLI response—including nested
+entry fields—as public schema. Keep its canonical type, contract tests, applicable
+text output, and complete consumer documentation aligned in the same change.
+
+An optional field addition may remain nonbreaking when old consumers continue
+unchanged. That compatibility result does not make the field private or waive
+current-authority and documentation requirements.
+
+Rejected: documenting only the outer envelope, relying on implementation typedefs
+as consumer documentation, or treating a response-entry field as mutable catalog
+data merely because the value it carries may evolve.
+
## Open questions
None.