An open source design system that's fully customizable and agent ready
TypeScript
spec(cli): AST-048 a change to an existing page starts from the app shell (#6862)
Joeydb52d98aaa5b
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.mdindex bffc302d8f..b3f25a5282 100644--- a/docs/architecture/template-authoring.md+++ b/docs/architecture/template-authoring.md@@ -97,7 +97,7 @@ entry and pass one validation boundary. That boundary uses these requirements:| Scope | Required | Optional or conditional || -------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |-| Every entry | `id`, `package`, `type`, `name`, `displayName`, non-empty `description`, explicit `isReady`, and an existing source file | Source-specific provenance and diagnostics |+| Every entry | `id`, `package`, `type`, `name`, `displayName`, non-empty `description`, explicit `isReady`, and an existing source file | `keywords`; source-specific provenance and diagnostics || Page | Everything above; `category` when eligible for the overview | `scaffold`, `isHiddenFromOverview`; a hidden special-purpose page may omit `category` || Block | Everything above plus `exampleFor`, positive `aspectRatio`, and complete `componentsUsed` | `scale`, `isShowcase`, `alsoExampleFor`, `alsoShowcaseFor` || Primary showcase | Block requirements plus `isShowcase: true`; at most one resolved primary showcase per `(package, target)` | The same block may serve additional targets through `alsoShowcaseFor` |diff --git a/docs/specs/AST-048-build-recommendation/spec.md b/docs/specs/AST-048-build-recommendation/spec.mdindex 66bb7b0f18..d2492bddab 100644--- a/docs/specs/AST-048-build-recommendation/spec.md+++ b/docs/specs/AST-048-build-recommendation/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-09-29+approved_at: 2026-10-01phase: acceptedowners: [josephfarina]affects_architecture: [architecture:cli-surface]@@ -60,7 +60,9 @@ and template owners own what each template is.control, a state, a widget, a section) MUST start from the page template therequest places that part in, when the request gives that page, and from theapp shell (FR2) when it gives no page. The blocks and components in the kit- carry the part itself.+ carry the part itself. A request that changes a page the builder already has+ starts from the app shell (FR2): the page is the builder's to keep (FR9), and+ no template scaffolds it.- **FR4 — Never an unready start.** A template marked not ready MUST NOT be thestart or an alternative. When search matches one directly, the start'sreason MUST name it and say the start is the closest ready template or the@@ -129,17 +131,17 @@ When this ships:## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ---------- | ----------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |-| FR1, FR2 | Build kit tests | a request that names a template; a loose request; a request no template fits | A page build with no start, or a start that is not a page template |-| FR3 | Build kit tests | a part placed in a page; a part with no page | A part with no page starting from a page template |-| FR4 | Build kit tests | search's direct match is not ready | An unready template as the start or an alternative, or a reason that hides it |-| FR5 | Template integration tests | an integration template that replaces a Core one; a block sharing a page template's id | A start or alternative command that selects another template, or none |-| FR6, FR7 | Build kit tests | direct, closest, and fallback starts | A start without a basis or reason, or without its alternatives |-| FR8, FR12 | Text field tests | default and `--verbose` text for a build with every field populated | A response field the text never shows, or text out of the required order |-| FR9 | CLI text tests | any page build | Text without the keep-your-page line |-| FR10, FR11 | Response type and build tests | the canonical response type, the response docs, and existing fields on a page build | A missing recommendation field, or an existing field whose shape changes |-| FR13 | Playbook and agent docs tests | the playbook steps and the generated agent docs block | A surface that tells builders to compose a page from primitives before a template |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------- | ----------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2 | Build kit tests | a request that names a template; a loose request; a request no template fits | A page build with no start, or a start that is not a page template |+| FR3 | Build kit tests | a part placed in a page; a part with no page; a change to an existing page | A part with no page starting from a page template, or a change to an existing page starting from that page's template |+| FR4 | Build kit tests | search's direct match is not ready | An unready template as the start or an alternative, or a reason that hides it |+| FR5 | Template integration tests | an integration template that replaces a Core one; a block sharing a page template's id | A start or alternative command that selects another template, or none |+| FR6, FR7 | Build kit tests | direct, closest, and fallback starts | A start without a basis or reason, or without its alternatives |+| FR8, FR12 | Text field tests | default and `--verbose` text for a build with every field populated | A response field the text never shows, or text out of the required order |+| FR9 | CLI text tests | any page build | Text without the keep-your-page line |+| FR10, FR11 | Response type and build tests | the canonical response type, the response docs, and existing fields on a page build | A missing recommendation field, or an existing field whose shape changes |+| FR13 | Playbook and agent docs tests | the playbook steps and the generated agent docs block | A surface that tells builders to compose a page from primitives before a template |## Decision log@@ -179,11 +181,12 @@ Rejected: a single pick with no alternatives.### DEC-4 — A part starts where it lives**Reference:** `spec:AST-048/DEC-4`-**Decider:** `josephfarina`, `2026-09-29`+**Decider:** `josephfarina`, `2026-10-01`A part is built inside a page. When the request gives that page, its templateis where the part goes; when it gives none, the app shell is the frame, and the-blocks and components carry the part.+blocks and components carry the part. A change to an existing page is the same+case: the page is the builder's own, so no template is its start.Rejected: starting a part from whichever page template shares a word with it,which scaffolds an unrelated page for a single control; and giving a part no