aestheticfunction · ryandmonk · Aug 10, 2026 · Aug 10, 2026
diff --git a/ADOPTING.md b/ADOPTING.md
@@ -27,18 +27,18 @@ there.)
 
 | # | Step | Mode |
 |---|------|------|
-| 1 | [Extract a snapshot from your codebase](#step-1--extract-a-snapshot) | 🤖 Automated |
-| 2 | [~~Set the version to the current spec~~](#step-2--set-the-version) — retired; snapshots declare it | 🤖 Automated |
-| 3 | [Review the snapshot against reality](#step-3--review-the-snapshot) | 👀 Human review |
-| 4 | [Author component guidance](#step-4--author-component-guidance) | ⚖️ Design decision |
-| 5 | [Define categories and tag components](#step-5--define-categories) | ⚖️ Design decision |
-| 6 | [Record patterns and anti-patterns](#step-6--patterns-and-anti-patterns) | ⚖️ Design decision |
-| 7 | [Name your intents](#step-7--name-your-intents) | ⚖️ Design decision |
-| 8 | [Write rules](#step-8--write-rules) | ⚖️ Design decision |
-| 9 | [Write worked examples and cross-link them](#step-9--worked-examples) | ⚖️ Design decision (machine-validated) |
-| 10 | [Validate the contract](#step-10--validate) | 🤖 Automated |
-| 11 | [Serve it to agents](#step-11--serve-it-to-agents) | 🤖 Automated |
-| 12 | [Generate, lint, and render](#step-12--generate-lint-render) | 🤖 Automated (rendering profile: ⚖️) |
+| 1 | [Extract a snapshot from your codebase](#step-1--extract-a-snapshot---automated) | 🤖 Automated |
+| 2 | [~~Set the version to the current spec~~](#step-2--set-the-version--retired) — retired; snapshots declare it | 🤖 Automated |
+| 3 | [Review the snapshot against reality](#step-3--review-the-snapshot---human-review) | 👀 Human review |
+| 4 | [Author component guidance](#step-4--author-component-guidance--) | ⚖️ Design decision |
+| 5 | [Define categories and tag components](#step-5--define-categories--) | ⚖️ Design decision |
+| 6 | [Record patterns and anti-patterns](#step-6--patterns-and-anti-patterns--) | ⚖️ Design decision |
+| 7 | [Name your intents](#step-7--name-your-intents--) | ⚖️ Design decision |
+| 8 | [Write rules](#step-8--write-rules--) | ⚖️ Design decision |
+| 9 | [Write worked examples and cross-link them](#step-9--worked-examples---machine-validated) | ⚖️ Design decision (machine-validated) |
+| 10 | [Validate the contract](#step-10--validate---automated) | 🤖 Automated |
+| 11 | [Serve it to agents](#step-11--serve-it-to-agents---automated) | 🤖 Automated |
+| 12 | [Generate, lint, and render](#step-12--generate-lint-render---rendering-profile-) | 🤖 Automated (rendering profile: ⚖️) |
 
 Step 1 assumes a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase
 (what [dspack-export](https://github.com/aestheticfunction/dspack-export)

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Think of it as OpenAPI for design systems.
 
 > **Status: v0.4 draft available.**
 >
-> The current draft is [`spec/dspack-v0.4.md`](./spec/dspack-v0.4.md) (written as a delta over [v0.3](./spec/dspack-v0.3.md)), with a matching [JSON Schema](./schema/dspack.v0.4.schema.json), a companion [surface schema](./schema/dspack.surface.v0_1.schema.json), and a [shadcn/ui reference example](./examples/shadcn-ui.dspack.json). v0.4 adds **component categories** (a contract-defined registry that rules can select by) and the **`required-props` rule type** ("this component must carry named content directly" — the refinement driven by measured projection-gap failures), and is strictly additive: a valid v0.3 document with `"dspack": "0.4"` validates against the v0.4 schema (see the [migration guide](./spec/migration-v0.3-to-v0.4.md)). Earlier specs and schemas ([v0.3](./spec/dspack-v0.3.md), [v0.2](./spec/dspack-v0.2.md), [v0.1](./spec/dspack-v0.1.md)) are preserved for reference. This is a draft — breaking changes may occur before v1.0. Contributions to the design are welcome at any stage.
+> The current draft is [`spec/dspack-v0.4.md`](./spec/dspack-v0.4.md) (written as a delta over [v0.3](./spec/dspack-v0.3.md)), with a matching [JSON Schema](./schema/dspack.v0.4.schema.json), a companion [surface schema](./schema/dspack.surface.v0_1.schema.json), and a [shadcn/ui reference example](./examples/shadcn-ui.dspack.json). v0.4 adds **component categories** (a contract-defined registry that rules can select by), the **`required-props` rule type** ("this component must carry named content directly" — the refinement driven by measured projection-gap failures), and two later amendments: **`requiredCategories`** (§4.3 — a component must contain a member of a named category) and **S2 sub-component containment** (§5.1 — a sub-declared id may appear only inside its declaring compound). It is strictly additive: a valid v0.3 document with `"dspack": "0.4"` validates against the v0.4 schema (see the [migration guide](./spec/migration-v0.3-to-v0.4.md)). Earlier specs and schemas ([v0.3](./spec/dspack-v0.3.md), [v0.2](./spec/dspack-v0.2.md), [v0.1](./spec/dspack-v0.1.md)) are preserved for reference. This is a draft — breaking changes may occur before v1.0. Contributions to the design are welcome at any stage.
 
 ---
 
@@ -189,7 +189,7 @@ The following milestones represent the current intended direction. They are not
 | **shadcn/ui example dspack** | A reference dspack file for the [shadcn/ui](https://ui.shadcn.com) component library — _[available](./examples/shadcn-ui.dspack.json)_ |
 | **v0.2 spec draft** | Adds structured generation constraints: lifecycle status, accessibility, composition rules, contextual constraints, variant semantics, token hierarchy, themes, layout primitives, and anti-pattern severity — _[available](./spec/dspack-v0.2.md)_ |
 | **v0.3 spec draft** | Adds the machine-checkable governance blocks: named intents, typed deterministic rules with rationales, compilable examples, and the companion dspack surface format — _[available](./spec/dspack-v0.3.md)_ |
-| **v0.4 spec draft** | Adds component categories (contract-defined registry, category-based rule selection) and the `required-props` rule type, both driven by measured pipeline evidence — _[available](./spec/dspack-v0.4.md)_ |
+| **v0.4 spec draft** | Adds component categories (contract-defined registry, category-based rule selection) and the `required-props` rule type, plus the `requiredCategories` (§4.3) and sub-component containment (§5.1) amendments — all driven by measured pipeline evidence — _[available](./spec/dspack-v0.4.md)_ |
 | **ds-mcp v0 release** | First release of the reference implementation, validated against the v0.2 spec; current releases support v0.1 through v0.4 — _[available](https://github.com/aestheticfunction/ds-mcp)_ |
 | **Community RFCs** | Open RFC process for proposing additions and changes to the spec |
 | **v1.0 spec stabilization** | First stable, versioned release of the specification; breaking changes require a formal process after this point |

diff --git a/examples/README.md b/examples/README.md
@@ -7,4 +7,4 @@ Example dspack files live in this directory. Examples are intended to help imple
 - [`shadcn-ui.dspack.json`](./shadcn-ui.dspack.json) — a reference dspack file for the [shadcn/ui](https://ui.shadcn.com) component library
 - [`astryx.dspack.json`](./astryx.dspack.json) — a governed slice of Meta's [Astryx](https://github.com/facebook/astryx) design system (pinned v0.1.4; published on npm under the `@astryxdesign` scope): 12 components, categories mirroring Astryx's own docs taxonomy, and 14 rules converted from the repository's structured `*.doc.mjs` guidance and the studio's example-expansion governance, each rule with a provenance link (`x-source`). Notable: Astryx components are props-based (labels are required string props; tables and menus are data-driven array props) — a deliberately different idiom from shadcn's compound composition
 
-The shadcn/ui example demonstrates the corpus concepts (tokens, components, patterns, anti-patterns, framework bindings), the v0.3 governance blocks (intents, rules, examples), and the v0.4 additions (component categories, a `required-props` rule, a category-based `forbidden-composition` rule). It validates against the [v0.4 JSON Schema](../schema/dspack.v0.4.schema.json).
+The shadcn/ui example demonstrates the corpus concepts (tokens, components, patterns, anti-patterns, framework bindings), the v0.3 governance blocks (intents, rules, examples), and the v0.4 additions: 7 component categories, 26 `required-props` rules, 2 category-based `forbidden-composition` rules, and a `requiredCategories` rule (`rule.form-control-carries-control`). It validates against the [v0.4 JSON Schema](../schema/dspack.v0.4.schema.json).
diff --git a/examples/astryx.dspack.json b/examples/astryx.dspack.json
@@ -2,7 +2,7 @@
   "$schema": "../schema/dspack.v0.4.schema.json",
   "dspack": "0.4",
   "name": "Astryx",
-  "description": "A nine-component slice of Meta's Astryx design system (open source, MIT; 160+ components; explicitly guidance-over-enforcement: design opinions live in docs, components render whatever they are passed). This contract converts a subset of that prose guidance into machine-checkable governance. Components and guidance are sourced from the repository's structured *.doc.mjs files at the pinned tag.",
+  "description": "A twelve-component slice of Meta's Astryx design system (open source, MIT; 160+ components; explicitly guidance-over-enforcement: design opinions live in docs, components render whatever they are passed). This contract converts a subset of that prose guidance into machine-checkable governance. Components and guidance are sourced from the repository's structured *.doc.mjs files at the pinned tag.",
   "version": "0.1.4",
   "metadata": {
     "source": "https://github.com/facebook/astryx/tree/v0.1.4",

diff --git a/schema/README.md b/schema/README.md
@@ -5,7 +5,7 @@ JSON Schema and related validation artifacts for dspack live in this directory.
 ## Current schemas
 
 - [`dspack.v0.4.schema.json`](./dspack.v0.4.schema.json) — JSON Schema for dspack v0.4
-  (current draft; adds component categories and the `required-props` rule type)
+  (current draft; adds component categories, the `required-props` rule type, and the `requiredCategories` / sub-component-containment amendments)
 - [`dspack.v0.3.schema.json`](./dspack.v0.3.schema.json) — JSON Schema for dspack v0.3
   (adds the governance blocks: `intents`, `rules`, `examples`)
 - [`dspack.surface.v0_1.schema.json`](./dspack.surface.v0_1.schema.json) — JSON Schema for

diff --git a/spec/README.md b/spec/README.md
@@ -6,8 +6,9 @@ Versioned specification documents for dspack live in this directory.
 
 - [`dspack-v0.4.md`](./dspack-v0.4.md) — v0.4 specification (current draft, written as a
   delta over v0.3): component categories (contract-defined registry, membership metadata,
-  the `forbiddenCategories` rule form) and the `required-props` rule type ("this component
-  must carry named content directly")
+  the `forbiddenCategories` rule form), the `required-props` rule type ("this component
+  must carry named content directly"), and two amendments: `requiredCategories` (§4.3) and
+  S2 sub-component containment (§5.1)
 - [`migration-v0.3-to-v0.4.md`](./migration-v0.3-to-v0.4.md) — migration guide (v0.4 is
   strictly additive; includes the worked v0.4 deltas from the shadcn contract)
 - [`dspack-v0.3.md`](./dspack-v0.3.md) — v0.3 specification (written as a

diff --git a/spec/migration-v0.3-to-v0.4.md b/spec/migration-v0.3-to-v0.4.md
@@ -33,9 +33,9 @@ three v0.3 rule types' semantics are frozen (v0.3 §5.5); enumerated
 ## Worked example: the v0.4 shadcn contract deltas
 
 The repository's [`examples/shadcn-ui.dspack.json`](../examples/shadcn-ui.dspack.json)
-shows all three additions in use.
+shows all four additions in use.
 
-**A registry of two categories, populated where the metadata already lived** (the
+**A registry of categories (the worked contract declares seven: interactive, overlay, form, layout, content, feedback, navigation), populated where the metadata already lived** (the
 `tags` fields sketched the taxonomy; categories make it referenceable by rules):
 
 ```json