An open source design system that's fully customizable and agent ready
TypeScript
[Spec] AST-035 DEC-7: a template's replaces needs CLI 0.6.4, not 0.7.0 (#7264)
Joey137c8abae63f
diff --git a/docs/specs/AST-035/spec.md b/docs/specs/AST-035/spec.mdindex a1dc5331c6..bd07825f7f 100644--- a/docs/specs/AST-035/spec.md+++ b/docs/specs/AST-035/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-10-07+approved_at: 2026-10-09phase: acceptedowners: [josephfarina, cixzhang]affects_architecture: [architecture:cli-surface]@@ -37,8 +37,10 @@ access to the Core original.- **FR1 — A template declares its own replacement.** An integration template MAYset `replaces` in its own metadata to an existing Core template id. Nopackage-level map declares replacements (`spec:AST-039/FR11`). The field is part- of the strict template metadata object, so CLIs before 0.7.0 reject it; an- integration that uses it MUST declare `@astryxdesign/cli >=0.7.0`.+ of the strict template metadata object, so stable CLIs before 0.6.4 reject it;+ an integration that uses it MUST declare an `@astryxdesign/cli` peer range whose+ lowest admitted version is at least 0.6.4, the first stable release that applies+ it (DEC-7).- **FR2 — A valid replacement owns default discovery.** When one valid declarationapplies, unqualified template lookup and default template projections MUST use theintegration template for the Core id. The integration template MUST remain@@ -130,13 +132,11 @@ access to the Core original.### Platform support-- Minimum supported CLI for an integration that declares `replaces`:- `@astryxdesign/cli >=0.7.0`. Earlier stable CLIs parse template metadata strictly:- they reject the field, print one warning, and withhold the package's templates and- doc topics, while its components still load.-- The replacement implementation may ship for forward validation before 0.7.0, but- remains pre-publication while no supported integration package may declare the- field. Stable 0.6.x conflict responses retain their warning-only shape. The+- Minimum supported CLI for an integration whose template declares `replaces`:+ `@astryxdesign/cli >=0.6.4`. Earlier stable CLIs parse template metadata strictly:+ they reject the field, print one warning, drop that template, and withhold the+ package's doc topics, while its other templates and its components still load.+- Stable 0.6.x conflict responses retain their warning-only shape. Thereplacement-specific conflict schema becomes eligible for an explicit, completeprojection update at 0.7.0; version alone does not activate it.- Component replacement: `@astryxdesign/cli >=0.6.7` is both the minimum supported CLI@@ -156,19 +156,19 @@ Project reports invalid contributions while retaining other valid contribution kand valid template or component siblings.The field is optional, and valid templates keep their selection behavior when it is-absent. Replacement declarations remain pre-publication throughout 0.6.x because an-integration package that uses one MUST require `@astryxdesign/cli >=0.7.0`; no valid-latest-stable integration consumer can rely on that path yet. Replacement selection-and mutable catalog membership therefore do not create a released victim. The-optional `TemplateListEntry.replaces` field is additive.+absent. Stable releases from 0.6.4 apply a declared replacement, and an integration+package that uses one requires `@astryxdesign/cli >=0.6.4`, a range that excludes+every stable release that rejects the field. Template winners are mutable catalog+data, so replacement selection does not create a released victim. The optional+`TemplateListEntry.replaces` field is additive.The released `IntegrationTemplateConflict` response is different: existing same-idconflicts are already stable. Final 0.6.x preserves their warning-only shape. Therequired `relationship` field and `severity: 'info'` value remain staged for a-deliberate complete projection update at or after 0.7.0, when replacement packages-become supported. A package-version bump alone leaves the warning-only projection in-place. Under `spec:AST-017/FR1`, FR2, FR5, FR7, and FR9–FR13, this pre-publication-capability plus the compatibility gate is a `[feat]` patch, not a breaking minor.+deliberate complete projection update at or after 0.7.0. A package-version bump+alone leaves the warning-only projection in place. Under `spec:AST-017/FR1`, FR2,+FR5, FR7, and FR9–FR13, the capability plus its compatibility gate is a `[feat]`+patch, not a breaking minor.Component discovery reads `replaces` from each valid component doc, and one resolverdecides component replacement, precedence, and findings. Component detail, batch@@ -187,7 +187,7 @@ replacement is a `[feat]` patch.| Contract | Verification | Representative states | Mutation or failure expectation || ---------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |-| FR1, FR6 | Template parser and discovery tests plus a released-CLI consumer run | field present, field absent, 0.6.3 CLI | a replacement is honored from anywhere but the template's own metadata |+| FR1, FR6 | Template parser and discovery tests, floor-table test, released-CLI consumer run | field present, field absent, published 0.6.3 and 0.6.4 CLIs, peer range at and below the floor | a replacement is honored from anywhere but the template's own metadata, or verify accepts a range below the floor || FR2, FR3 | Template API/CLI and real consumer-app tests | target id, own id, Core package, integration package | lookup becomes ambiguous or the Core original is unreachable || FR4, FR7 | Doctor and discovery tests plus a 0.6.x response-shape fixture | missing local/source, missing target, wrong kind, duplicate, same-id rejection, pre-publication replacement | invalid metadata activates a replacement, Doctor reports success, or a 0.6.x conflict gains staged fields || FR5 | Multi-integration and autolink tests | configured order, explicit versus autolinked, invalid loser | file/display order chooses the winner or invalid autolinking disables explicit intent |@@ -238,11 +238,12 @@ to discovery later.Put `replaces` in the integration template's own metadata. Every integration itemkeeps its per-item metadata in its own descriptor (`spec:AST-039/FR11`), and doc-topics already declare replacement with the same field. The cost: a CLI older than-0.7.0 rejects the unknown field and withholds the package's templates and doc-topics, where the manifest map let it fall back to own-id access. Integration-themes in 0.7.0 already need a 0.7.0 CLI, so this adds no new kind of break;-integrations that use `replaces` declare `@astryxdesign/cli >=0.7.0`.+topics already declare replacement with the same field. The cost: a stable CLI+before 0.6.4 rejects the unknown field, drops that template, and withholds the+package's doc topics, where the manifest map let it fall back to own-id access.+Integration themes, section ids, and namespace docs already need a 0.6.4 CLI, so+this adds no new kind of break; integrations that use `replaces` declare the CLI+floor in DEC-7.Rejected: `templateReplacements` in the manifest (DEC-1). It is a central catalog ofper-item data, which `spec:AST-039/FR11` forbids for every kind.@@ -251,6 +252,7 @@ per-item data, which `spec:AST-039/FR11` forbids for every kind.**Reference:** `spec:AST-035/DEC-4`**Decider:** `josephfarina`, `2026-09-29`+**Superseded in part by:** `spec:AST-035/DEC-7`, `2026-10-09`Integration-template replacement is not a fully published API before the supported0.7.0 integration-package boundary. Shipping its implementation in final 0.6.x is@@ -301,6 +303,22 @@ about the winner.Rejected: per-surface resolution — component, search, and swizzle would drift apart.+### DEC-7 — The template replacement floor is the first release that applies it++**Reference:** `spec:AST-035/DEC-7`+**Decider:** `josephfarina`, `2026-10-09`++An integration whose template sets `replaces` declares an `@astryxdesign/cli` peer+range that starts at 0.6.4, in place of DEC-4's `>=0.7.0`. Published 0.6.4 through+0.6.7 apply FR2 and FR3 to a declared replacement, and published 0.6.3 and earlier+reject the field. A floor that no published release satisfies makes npm leave the+CLI uninstalled in an app that installs the package. From 0.6.4, the `replaces`+declaration, replacement selection, and the optional list projection are published+surfaces under `spec:AST-017/FR24`; the expanded conflict fields stay+pre-publication until the projection change of FR7 and FR8 at or after 0.7.0.++Rejected: keeping `>=0.7.0` until 0.7.0 ships, because npm removes the CLI from apps on 0.6.x that install such a package.+## Open questionsNone.