@3fn/core 13.0.0 → 14.0.0

package/governance/Component-Quick-Reference.md

@@ -69,7 +69,7 @@ Type primitives are specialized components within a family that provide opiniona
 
 For detailed Container-Card-Base documentation including props mapping, interactive behavior, and usage examples:
 ```
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Card-Base" })
+get_section({ path: "component-family-container", heading: "Container-Card-Base" })
 ```
 
 ## Naming Convention
@@ -156,22 +156,22 @@ Returns metadata and outline (~200 tokens) to understand document structure befo
 
 ```
 // Understand Form Inputs family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_summary({ path: "component-family-form-inputs" })
 
 // Understand Button family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Button.md" })
+get_document_summary({ path: "component-family-button" })
 
 // Understand Container family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Container.md" })
+get_document_summary({ path: "component-family-container" })
 
 // Understand Icon family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Icon.md" })
+get_document_summary({ path: "component-family-icon" })
 
 // Understand Chip family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Chip.md" })
+get_document_summary({ path: "component-family-chip" })
 
 // Get Container-Card-Base type primitive details
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Card-Base" })
+get_section({ path: "component-family-container", heading: "Container-Card-Base" })
 ```
 
 **Returns**: Document metadata (purpose, layer, relevant tasks) plus section outline with headings.
@@ -182,37 +182,37 @@ Returns targeted content (~500-2,000 tokens) for specific information needs:
 
 ```
 // Get component behavioral contracts
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Behavioral Contracts" })
+get_section({ path: "component-family-form-inputs", heading: "Behavioral Contracts" })
 
 // Get contract system conventions (taxonomy, naming, format)
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Taxonomy" })
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Naming Convention" })
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Canonical Format" })
+get_section({ path: "contract-system-reference", heading: "Taxonomy" })
+get_section({ path: "contract-system-reference", heading: "Naming Convention" })
+get_section({ path: "contract-system-reference", heading: "Canonical Format" })
 
 // Get inheritance structure
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Inheritance Structure" })
+get_section({ path: "component-family-button", heading: "Inheritance Structure" })
 
 // Get token dependencies
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Token Dependencies" })
+get_section({ path: "component-family-container", heading: "Token Dependencies" })
 
 // Get usage guidelines
-get_section({ path: ".kiro/steering/Component-Family-Icon.md", heading: "Usage Guidelines" })
+get_section({ path: "component-family-icon", heading: "Usage Guidelines" })
 
 // Get Chip family behavioral contracts
-get_section({ path: ".kiro/steering/Component-Family-Chip.md", heading: "Behavioral Contracts" })
+get_section({ path: "component-family-chip", heading: "Behavioral Contracts" })
 
 // Get cross-platform notes
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Cross-Platform Notes" })
+get_section({ path: "component-family-form-inputs", heading: "Cross-Platform Notes" })
 
 // Get radio component details
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Base" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Set" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Base" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Set" })
 
 // Get component schema definitions
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Component Schemas" })
+get_section({ path: "component-family-button", heading: "Component Schemas" })
 
 // Get placeholder family planned characteristics
-get_section({ path: ".kiro/steering/Component-Family-Modal.md", heading: "Planned Characteristics" })
+get_section({ path: "component-family-modal", heading: "Planned Characteristics" })
 ```
 
 **Returns**: Section content with parent heading context for document location.
@@ -223,10 +223,10 @@ Returns complete content (~2,000-10,000 tokens) when comprehensive reference is
 
 ```
 // Full Form Inputs family reference
-get_document_full({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_full({ path: "component-family-form-inputs" })
 
 // Full Button family reference
-get_document_full({ path: ".kiro/steering/Component-Family-Button.md" })
+get_document_full({ path: "component-family-button" })
 ```
 
 **Use sparingly**: Only when you need complete component family documentation.
@@ -241,10 +241,10 @@ find_docs({ concept: "form inputs" })   // discover by concept/keyword
 find_docs({ list: true })               // full catalog, paginated
 
 // List cross-references in a document
-list_cross_references({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+list_cross_references({ path: "component-family-form-inputs" })
 
 // Validate document metadata schema
-validate_metadata({ path: ".kiro/steering/Component-Family-Button.md" })
+validate_metadata({ path: "component-family-button" })
 
 // Check documentation index health
 get_index_health()
@@ -270,30 +270,30 @@ rebuild_index()
 **Example: Building a Login Form:**
 ```
 // Step 1: Get Form Inputs overview
-get_document_summary({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_summary({ path: "component-family-form-inputs" })
 
 // Step 2: Get specific component contracts
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Text-Email" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Text-Password" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Text-Email" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Text-Password" })
 
 // Step 3: Get button for submit action
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Button-CTA" })
+get_section({ path: "component-family-button", heading: "Button-CTA" })
 
 // Step 4: Get container for layout
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Base" })
+get_section({ path: "component-family-container", heading: "Container-Base" })
 ```
 
 **Example: Building a Survey with Radio Groups:**
 ```
 // Step 1: Get radio component details
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Base" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Set" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Base" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Set" })
 
 // Step 2: Get container for section layout
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Base" })
+get_section({ path: "component-family-container", heading: "Container-Base" })
 
 // Step 3: Get button for submit
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Button-CTA" })
+get_section({ path: "component-family-button", heading: "Button-CTA" })
 ```
 
 ## Related Documentation

package/governance/Component-Readiness-Status.md

@@ -13,7 +13,7 @@ description: Readiness status definitions, usage recommendations, and transition
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-01
+**Last Reviewed**: 2026-07-09
 
 ---
 
@@ -520,7 +520,7 @@ metadata:
 **Query component readiness**:
 ```
 get_section({ 
-  path: ".kiro/steering/Component-Family-Form-Inputs.md", 
+  path: "component-family-form-inputs", 
   heading: "Component Readiness" 
 })
 ```
@@ -544,54 +544,70 @@ get_section({
 | Component Family | Shared Need/Purpose | Status | MCP Document Path |
 |------------------|---------------------|--------|-------------------|
 | Buttons | User interaction and actions | 🟢 | `.kiro/steering/Component-Family-Button.md` |
-| Form Inputs | Data collection and validation | 🟢 | `.kiro/steering/Component-Family-Form-Inputs.md` |
-| Containers | Layout and content organization | 🟢 | `.kiro/steering/Component-Family-Container.md` |
-| Icons | Visual communication | 🔴 | `.kiro/steering/Component-Family-Icon.md` |
+| Form Inputs | Data collection and validation | 🟡 | `.kiro/steering/Component-Family-Form-Inputs.md` |
+| Containers | Layout and content organization | 🟡 | `.kiro/steering/Component-Family-Container.md` |
+| Icons | Visual communication | 🟡 | `.kiro/steering/Component-Family-Icon.md` |
+| Avatars | Identity representation | 🟡 | `.kiro/steering/Component-Family-Avatar.md` |
+| Badges & Tags | Status and labeling | 🟡 | `.kiro/steering/Component-Family-Badge.md` |
+| Chips | Selection, filtering, and input tokens | 🟡 | `.kiro/steering/Component-Family-Chip.md` |
+| Navigation | Wayfinding | 🟡 | `.kiro/steering/Component-Family-Navigation.md` |
+| Progress Indicators | Progress and step indication | 🟡 | `.kiro/steering/Component-Family-Progress.md` |
 | Modals | Overlay interactions | 🔴 | `.kiro/steering/Component-Family-Modal.md` |
-| Avatars | Identity representation | 🔴 | `.kiro/steering/Component-Family-Avatar.md` |
-| Badges & Tags | Status and labeling | 🔴 | `.kiro/steering/Component-Family-Badge.md` |
 | Data Displays | Information presentation | 🔴 | `.kiro/steering/Component-Family-Data-Display.md` |
 | Dividers | Visual separation | 🔴 | `.kiro/steering/Component-Family-Divider.md` |
 | Loading | Progress indication | 🔴 | `.kiro/steering/Component-Family-Loading.md` |
-| Navigation | Wayfinding | 🔴 | `.kiro/steering/Component-Family-Navigation.md` |
 ```
 
+> **🟡 in this table = "shipping, web production-ready, iOS/Android scaffold"** — the family has usable web implementations but has not reached the strict all-platform 🟢 bar. Per-component per-platform detail is in the Individual Component Status table below. Buttons is 🟢 only because it contains all-platform-production components (Button-VerticalList-Item/Set); its CTA/Icon members are themselves web-ready/mobile-scaffold. 🔴 families are genuine placeholders (no components ship).
+
 ---
 
 ## Individual Component Status
 
 This section lists all implemented components with their readiness status and implementation paths. Used by extraction workflows to check component existence and status.
 
-| Component | Family | Status | Implementation Path |
-|-----------|--------|--------|---------------------|
-| Avatar | Avatars | 🟡 Beta | `src/components/core/Avatar/` |
-| BadgeCountBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Count-Base/` |
-| BadgeCountNotification | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Count-Notification/` |
-| BadgeLabelBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Label-Base/` |
-| ButtonCTA | Buttons | 🟢 Production Ready | `src/components/core/Button-CTA/` |
-| ButtonIcon | Buttons | 🟢 Production Ready | `src/components/core/Button-Icon/` |
-| ButtonVerticalListItem | Buttons | 🟢 Production Ready | `src/components/core/Button-VerticalList-Item/` |
-| ButtonVerticalListSet | Buttons | 🟢 Production Ready | `src/components/core/Button-VerticalList-Set/` |
-| ChipBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Base/` |
-| ChipFilter | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Filter/` |
-| ChipInput | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Input/` |
-| ContainerBase | Containers | 🟢 Production Ready | `src/components/core/Container-Base/` |
-| ContainerCardBase | Containers | 🟢 Production Ready | `src/components/core/Container-Card-Base/` |
-| IconBase | Icons | 🟢 Production Ready | `src/components/core/Icon-Base/` |
-| InputCheckboxBase | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Checkbox-Base/` |
-| InputCheckboxLegal | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Checkbox-Legal/` |
-| InputRadioBase | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Radio-Base/` |
-| InputRadioSet | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Radio-Set/` |
-| InputTextBase | Form Inputs | ⚠️ Deprecated | `src/components/core/Input-Text-Base/` |
-| InputTextEmail | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-Email/` |
-| InputTextPassword | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-Password/` |
-| InputTextPhoneNumber | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-PhoneNumber/` |
-| ProgressIndicatorConnectorBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Connector-Base/` |
-| ProgressIndicatorLabelBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Label-Base/` |
-| ProgressIndicatorNodeBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Node-Base/` |
-| ProgressPaginationBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Pagination-Base/` |
-| ProgressStepperBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Stepper-Base/` |
-| ProgressStepperDetailed | Loading | 🟢 Production Ready | `src/components/core/Progress-Stepper-Detailed/` |
+**Per-platform status convention**: readiness is tracked per platform (web / iOS / Android). The **Status** column carries a single roll-up indicator; the **Platform Readiness** column shows the honest per-platform breakdown so no component's mobile immaturity is hidden behind a green light.
+
+- 🟢 **Production Ready** — production-ready across ALL declared platforms (web, iOS, Android), per the strict definition above. Currently only Button-VerticalList-Item and Button-VerticalList-Set meet this bar.
+- 🟡 **Web-ready, mobile-scaffold** — web is production-ready (implemented, tested, documented) but iOS and Android are scaffold (structure present, not test-covered). Safe to consume on web; treat mobile as not-yet-ready.
+- 🟡 **Scaffold (all platforms)** — structure present on all platforms but none production-ready; intentional for permissive/internal primitives (noted inline).
+
+| Component | Family | Status | Platform Readiness (web / iOS / Android) | Implementation Path |
+|-----------|--------|--------|------------------------------------------|---------------------|
+| Avatar-Base | Avatar | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Avatar-Base/` |
+| Badge-Count-Base | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Count-Base/` |
+| Badge-Count-Notification | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Count-Notification/` |
+| Badge-Label-Base | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Label-Base/` |
+| Button-CTA | Button | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Button-CTA/` |
+| Button-Icon | Button | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Button-Icon/` |
+| Button-VerticalList-Item | Button | 🟢 | 🟢 / 🟢 / 🟢 | `src/components/core/Button-VerticalList-Item/` |
+| Button-VerticalList-Set | Button | 🟢 | 🟢 / 🟢 / 🟢 | `src/components/core/Button-VerticalList-Set/` |
+| Chip-Base | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Base/` |
+| Chip-Filter | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Filter/` |
+| Chip-Input | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Input/` |
+| Container-Base | Container | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Container-Base/` |
+| Container-Card-Base | Container | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Container-Card-Base/` |
+| Icon-Base | Icon | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Icon-Base/` |
+| Input-Checkbox-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Checkbox-Base/` |
+| Input-Checkbox-Legal | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Checkbox-Legal/` |
+| Input-Radio-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Radio-Base/` |
+| Input-Radio-Set | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Radio-Set/` |
+| Input-Text-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Base/` |
+| Input-Text-Email | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Email/` |
+| Input-Text-Password | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Password/` |
+| Input-Text-PhoneNumber | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-PhoneNumber/` |
+| Nav-Header-Page | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-Header-Page/` |
+| Nav-SegmentedChoice-Base | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-SegmentedChoice-Base/` |
+| Nav-TabBar-Base | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-TabBar-Base/` |
+| Nav-Header-App | Navigation | 🟡 | scaffold / scaffold / scaffold — permissive scaffold by design | `src/components/core/Nav-Header-App/` |
+| Nav-Header-Base | Navigation | 🟡 | scaffold / scaffold / scaffold — internal-only primitive | `src/components/core/Nav-Header-Base/` |
+| Progress-Bar-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Bar-Base/` |
+| Progress-Indicator-Node-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Indicator-Node-Base/` |
+| Progress-Pagination-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Pagination-Base/` |
+| Progress-Stepper-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Stepper-Base/` |
+| Progress-Stepper-Detailed | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Stepper-Detailed/` |
+| Progress-Indicator-Connector-Base | Progress Indicators | 🟡 | scaffold / scaffold / scaffold | `src/components/core/Progress-Indicator-Connector-Base/` |
+| Progress-Indicator-Label-Base | Progress Indicators | 🟡 | scaffold / scaffold / scaffold | `src/components/core/Progress-Indicator-Label-Base/` |
 
 **Usage:**
 

package/governance/Component-Templates.md

@@ -12,7 +12,7 @@ aliases: how do i scaffold a new component, scaffold a new component template, n
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-02
+**Last Reviewed**: 2026-07-15
 
 ---
 
@@ -412,14 +412,6 @@ properties:
       - secondary: [description]
       - tertiary: [description]
   
-  # State properties
-  disabled:
-    type: boolean
-    required: false
-    default: false
-    description: |
-      When true, component is non-interactive with disabled visual styling.
-  
   # Callback properties
   [callbackProp]:
     type: "() => void"
@@ -709,14 +701,12 @@ focusable:
   behavior: |
     Component can receive focus via Tab key navigation.
     Focus state is visually indicated with a focus ring.
-    Focus is managed appropriately when disabled state changes.
   wcag: "2.1.1 Keyboard, 2.4.7 Focus Visible"
   platforms: [web, ios, android]
   validation: |
     - Tab key moves focus to component
     - Focus state is visually distinct with focus ring
     - Focus ring meets 3:1 contrast ratio
-    - Disabled components are not focusable
 ```
 
 #### Pressable Contract
@@ -726,7 +716,7 @@ pressable:
   description: Responds to press/click events
   behavior: |
     Component responds to click, tap, Enter key, and Space key.
-    Press triggers the callback when not disabled.
+    Press triggers the callback.
     Platform-appropriate feedback is provided during press.
   wcag: "2.1.1 Keyboard"
   platforms: [web, ios, android]
@@ -734,7 +724,6 @@ pressable:
     - Click/tap triggers callback
     - Enter key triggers callback
     - Space key triggers callback
-    - Callback not called when disabled
 ```
 
 #### Hoverable Contract
@@ -745,14 +734,12 @@ hoverable:
   behavior: |
     On pointer devices, component shows visual feedback when mouse
     hovers over the component. Uses blend.hoverDarker token.
-    Hover state not shown when disabled.
   wcag: "1.4.13 Content on Hover or Focus"
   platforms: [web, ios, android]
   validation: |
     - Visual feedback shown on mouse enter
     - Visual feedback removed on mouse leave
     - Hover uses blend.hoverDarker token
-    - Hover state not shown when disabled
     - iOS: Only on macOS/iPadOS with pointer
     - Android: Only on desktop/ChromeOS with pointer
 ```
@@ -761,28 +748,38 @@ hoverable:
 
 ### Contract Category 2: State Contracts
 
-#### Disabled State Contract
+#### No Disabled States — Standardized Exclusion
+
+**DesignerPunk components MUST NOT declare a disabled-state contract.** Per the
+2026-07-15 adjudication (`.kiro/issues/button-cta-disabled-state-adjudication.md`),
+the no-disabled-states philosophy now holds corpus-wide with zero exceptions —
+Button-CTA was the last remaining component with a live `disabled_state`
+contract, and it has been removed in favor of the standardized exclusion below.
+
+If an action is temporarily unavailable, use one of these alternatives instead:
+
+- **`state_loading`** — the action is in-flight (async operation running).
+- **Validate-on-press / validate-on-blur** — the action is available but the
+  current input is invalid; surface the error rather than disabling the trigger.
+- **Do not render the component** — if an action is genuinely unavailable
+  (no valid path forward), omit the component entirely rather than rendering
+  it in a disabled state.
+
+Every component's `contracts.yaml` MUST carry the standardized exclusion block
+(mirrored corpus-wide, e.g. `src/components/core/Button-CTA/contracts.yaml`):
 
 ```yaml
-disabled_state:
-  description: Prevents interaction when disabled
-  behavior: |
-    When disabled, component:
-    - Cannot receive focus
-    - Cannot be interacted with
-    - Uses desaturated colors (blend.disabledDesaturate)
-    - Shows cursor: not-allowed (web)
-    - Communicates disabled state to assistive technology
-  wcag: "4.1.2 Name, Role, Value"
-  platforms: [web, ios, android]
-  validation: |
-    - Component cannot receive focus when disabled
-    - Interactions do not trigger callbacks when disabled
-    - Visual styling indicates disabled state
-    - aria-disabled="true" set (web)
-    - Disabled state announced to screen readers
+excludes:
+  state_disabled:
+    reason: "DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered."
+    category: state
 ```
 
+Do not scaffold a `disabled` prop, a `disabled_state` contract, or any
+disabled-specific validation steps in new components. For the full rationale,
+see the exclusion reason above and the 2026-07-15 adjudication ruling
+(`.kiro/issues/button-cta-disabled-state-adjudication.md`).
+
 #### Error State Contract
 
 ```yaml
@@ -830,7 +827,7 @@ loading_state:
   behavior: |
     When in loading state, component:
     - Shows loading spinner or indicator
-    - Prevents interaction (similar to disabled)
+    - Prevents interaction while the async operation is in-flight
     - Maintains dimensions to prevent layout shift
     - Communicates loading state to assistive technology
   wcag: "4.1.3 Status Messages"
@@ -947,7 +944,6 @@ pressed_state:
     - Visual feedback shown during press
     - Feedback uses blend.pressedDarker token
     - Platform-appropriate animation/effect applied
-    - Pressed state not shown when disabled
 ```
 
 #### Gradient Glow Contract
@@ -1084,7 +1080,7 @@ renders_svg:
 | Keyboard navigation | focusable, focus_ring |
 | Click/tap interaction | pressable, pressed_state |
 | Mouse hover feedback | hoverable |
-| Disabled state | disabled_state |
+| Action temporarily unavailable | state_loading (in-flight), validates_on_blur (invalid input), or do not render (no valid path) — never a disabled-state contract; see "No Disabled States — Standardized Exclusion" |
 | Error handling | error_state, validates_on_blur |
 | Success feedback | success_state |
 | Loading indication | loading_state |

package/governance/Contract-System-Reference.md

@@ -2,7 +2,7 @@
 id: contract-system-reference
 inclusion: manual
 name: Contract-System-Reference
-description: Uniform behavioral contract system reference — 10-category taxonomy with definitions, concept catalog with all 136 concepts, {category}_{concept} naming convention, canonical contracts.yaml format, exclusion format, inheritance and composition patterns, classification rules. Load when creating or modifying component contracts, auditing contract coverage, or building contract-consuming systems.
+description: Uniform behavioral contract system reference — 10-category taxonomy with definitions, concept catalog with all 137 concepts, {category}_{concept} naming convention, canonical contracts.yaml format, exclusion format, inheritance and composition patterns, classification rules. Load when creating or modifying component contracts, auditing contract coverage, or building contract-consuming systems.
 ---
 
 # Contract System Reference
@@ -46,9 +46,9 @@ This document is the authoritative reference for contract conventions. For the d
 
 ## Concept Catalog
 
-136 concepts across 10 categories. Originally 116, derived from the 29 deployed contracts.yaml files in the Spec 078 audit; grown since through governed additions (`gradient_glow` ballot measure, Spec 088 Nav-Header concepts, Spec 090 Progress-Bar-Base concepts).
+137 concepts across 10 categories. Originally 116, derived from the 29 deployed contracts.yaml files in the Spec 078 audit; grown since through governed additions (`gradient_glow` ballot measure, Spec 088 Nav-Header concepts, Spec 090 Progress-Bar-Base concepts, `readonly` ballot measure 2026-07-15).
 
-*Adjudicated 2026-07-03 (Lina): 136 counted empirically from the per-category lists below (26+6+7+17+19+6+1+15+10+29), which are the enforced source of truth via `src/__tests__/stemma-system/contract-catalog-name-validation.test.ts`; the stale "117" figures dated from the last full-sweep update (gradient_glow, 2026-03-18), while only this section's rolling "Updated:" line had tracked subsequent additions to 136.*
+*Adjudicated 2026-07-03 (Lina): 137 counted empirically from the per-category lists below (26+6+7+17+19+6+1+16+10+29), which are the enforced source of truth via `src/__tests__/stemma-system/contract-catalog-name-validation.test.ts`; the stale "117" figures dated from the last full-sweep update (gradient_glow, 2026-03-18), while only this section's rolling "Updated:" line had tracked subsequent additions to 136. state grew to 16 via the 2026-07-15 readonly ballot.*
 
 ### accessibility (26)
 
@@ -78,9 +78,9 @@ This document is the authoritative reference for contract conventions. For the d
 
 `virtualization`
 
-### state (15)
+### state (16)
 
-`binary_derivation` · `checked` · `connector_derivation` · `controlled` · `disabled` · `error` · `indeterminate` · `loading` · `mode_driven` · `priority_derivation` · `selected` · `selected_styling` · `styling` · `success` · `visual_driven`
+`binary_derivation` · `checked` · `connector_derivation` · `controlled` · `disabled` · `error` · `indeterminate` · `loading` · `mode_driven` · `priority_derivation` · `readonly` · `selected` · `selected_styling` · `styling` · `success` · `visual_driven`
 
 ### validation (10)
 
@@ -110,7 +110,7 @@ All contract names follow `{category}_{concept}` in `snake_case`. No `supports_`
 | Checkmark animation | `animation_checkmark` |
 | Circular shape | `visual_circular_shape` |
 
-The Concept Catalog above lists all 136 concepts. For the historical migration mapping (113 source names → 104 canonical names, pre-Task 2.1), see `.kiro/specs/063-uniform-contract-system/findings/canonical-name-mapping.md`.
+The Concept Catalog above lists all 137 concepts. For the historical migration mapping (113 source names → 104 canonical names, pre-Task 2.1), see `.kiro/specs/063-uniform-contract-system/findings/canonical-name-mapping.md`.
 
 ---
 

package/governance/MCP-Integration-Guide.md

@@ -151,7 +151,7 @@ Both `find_docs` and keyworded `find_components` emit a three-layer confidence s
 
 **Token exemption:** token tools perform structured predicate retrieval with no relevance ranking — the three-layer model does not apply. Trigger: if a token tool is introduced with open-ended intent input and ranked output, it inherits this model. Bright line: predicate filter → no tier; relevance ranking → tier required.
 
-**119 Decision 4a cross-reference:** the agent-side certainty-calibration protocol that consumes a `partial` (propose best-fit + confidence + rationale → human go/no-go, with the proposal required to carry its own uncertainty) is captured in `.kiro/specs/119-steering-progressive-disclosure-redesign/design-outline.md` under Decision 4a. 121 emits the signal; 119 defines what the agent does with a `partial`.
+**119 Decision 4a cross-reference:** the agent-side certainty-calibration protocol that consumes a `partial` (propose best-fit + confidence + rationale → human go/no-go, with the proposal required to carry its own uncertainty) is captured in `.kiro/specs/119-agent-experience-architecture/design-outline.md` under Decision 4a. 121 emits the signal; 119 defines what the agent does with a `partial`.
 
 ---
 

package/governance/Process-Cross-Reference-Standards.md

@@ -8,7 +8,7 @@ description: Cross-reference standards for documentation — formatting rules, c
 # Process-Cross-Reference-Standards
 
 **Date**: 2026-01-03
-**Last Reviewed**: 2026-01-03
+**Last Reviewed**: 2026-07-09
 **Purpose**: Comprehensive guide for creating and maintaining cross-references in documentation
 **Organization**: process-standard
 **Scope**: cross-project
@@ -34,7 +34,7 @@ Cross-references MUST be used in the following documentation types:
 - **Completion Documents**: Task completion documentation in `.kiro/specs/[spec-name]/completion/`
 - **README Files**: Project and directory README files that provide navigation and context
 - **Overview Documents**: Master documents that map components to their documentation (e.g., `docs/token-system-overview.md`)
-- **Process Documentation**: Standards and methodology documents in `.kiro/steering/` and `docs/processes/`
+- **Process Documentation**: Standards and methodology documents in the MCP-served governance corpus (`governance/`), the always-loaded identity docs (`.kiro/steering/`), and `docs/processes/`
 
 **Rationale**: These are documentation artifacts where cross-references add value by helping readers discover related information and navigate between connected concepts.
 
@@ -113,11 +113,25 @@ export const TypographyTokens = {
 
 ## How to Format Cross-References
 
-Cross-references should follow consistent formatting patterns to ensure clarity and maintainability.
+Cross-references should follow consistent formatting patterns to ensure clarity and maintainability. **Which pattern applies depends on what you are linking to** — there are two reference classes:
+
+### Two Reference Classes (pick by target)
+
+| Target | How to reference | Example |
+|--------|------------------|---------|
+| **Governance corpus** — an MCP-served doc under `governance/` that carries an `id:` | **Bare-`id`** markdown link: `[Human Label](<doc-id>)` — the target's `id`, no path, no `.md`. Bare-id links are validated against the served index (Spec 119-B OB-1): a target that is not MCP-served will be dropped from cross-ref enumeration and flagged unresolved | `[Token Governance](token-governance)` |
+| **The 9 identity docs** under `.kiro/steering/` — always-loaded, NEVER MCP-served (Spec 119-A: identity refs never take the MCP round-trip; they carry `id:` for the uniqueness guard, not for resolution) | **Relative path** markdown link, like other non-id-indexed repo files (amended 2026-08-02, Civitas health-check follow-up #4 — the prior bare-id clause implied MCP resolvability these docs deliberately do not have) | `[Core Goals](../.kiro/steering/core-goals.md)` |
+| **Spec-local / repo-file** — spec artifacts (requirements/design/tasks/completion docs, spec guides), READMEs, and other repo files that are **not** `id`-indexed | **Relative path** markdown link (see "Relative Path Usage" below) | `[Design Decisions](../design.md#design-decisions)` |
+
+**Why the split.** Spec 119-A gave every doc in the MCP-served corpus a stable, relocation-independent `id` and made bare-`id` the addressing form (226 intra-corpus refs migrated). An `id`-addressed link survives file moves because the `id` — not the path — is the address. Spec artifacts and loose repo files carry no `id`, so relative paths remain their correct form.
+
+**The addressing grammar is owned elsewhere — do not re-derive it here.** The canonical source for the `id` form, the composite `docid#sectionid` section grammar, kebab-case filenames, and `aliases` is [Steering Addressing Conventions](steering-addressing-conventions). This document governs cross-reference *practice* (when to link, link-text quality, anti-patterns, maintenance); it defers the *grammar* to that doc so the two never drift.
+
+> **Tooling caveat (119-B OB-1).** Bare-`id` cross-refs **resolve** correctly (resolver strategy-1), but the cross-reference *parser* still only enumerates `.md`-suffixed targets, so `list_cross_references` and the `crossReferences` map currently under-count bare-`id` links. Enumeration parity is deferred to 119-B OB-1. Until then, do not treat an empty `list_cross_references` result as proof a doc has no inbound links.
 
 ### Relative Path Usage
 
-Always use relative paths from the current document location. Relative paths ensure links remain valid when the repository structure changes or when viewing documentation in different contexts.
+For **spec-local and repo-file references** (the second class above), use relative paths from the current document location. Relative paths ensure these links remain valid when viewed across different contexts. (For steering/governance-corpus targets, use the bare-`id` form instead — see the table above.)
 
 **Pattern**: Use `../` to navigate up directories and `./` for same-directory references
 
@@ -483,7 +497,7 @@ where properties are separated by concern.
 
 ## Related Guides
 
-- [Compositional Color Guide](https://github.com/3fn/DesignerPunkv2/blob/main/.kiro/specs/typography-token-expansion/compositional-color-guide.md)
+- [Compositional Color Guide](https://github.com/3fn/DesignerPunk/blob/main/.kiro/specs/typography-token-expansion/compositional-color-guide.md)
 - [Strategic Flexibility Guide](/Users/peter/.kiro/specs/typography-token-expansion/strategic-flexibility-guide.md)
 - [Inline Emphasis Guide](/.kiro/specs/typography-token-expansion/inline-emphasis-guide.md)
 ```
@@ -611,7 +625,7 @@ Strategic Flexibility Guide.
 
 When files are moved during organization:
 
-1. Update all cross-reference links to reflect new locations
+1. **Bare-`id` references to steering/governance-corpus docs need no update** — the `id` is the address, so it survives the move (this move-resilience is the reason 119-A adopted `id`-addressing). Update the *relative-path* references (spec-local / repo-file links) to reflect new locations.
 2. Verify bidirectional links remain consistent
 3. Test navigation by clicking links in rendered markdown
 4. Document any broken links and fix them immediately
@@ -621,10 +635,12 @@ When files are moved during organization:
 Periodically validate cross-reference integrity:
 
 - Verify all links resolve to existing documents
-- Check that relative paths are correct from document location
+- Check that relative paths are correct from document location (bare-`id` links resolve by `id`, not path, so there is no path to verify — confirm the `id` exists)
 - Confirm section anchors exist in target documents
 - Test navigation efficiency (related docs reachable in 2 clicks or less)
 
+> **Caveat (119-B OB-1):** automated link-graph tooling built on `list_cross_references` currently under-counts bare-`id` links (the parser enumerates only `.md`-suffixed targets). Until OB-1 lands, supplement automated enumeration with a text search for bare-`id` targets when auditing a doc's inbound/outbound links.
+
 ### Navigation as Aid, Not Dependency
 
 Cross-references should be navigation aids, not content dependencies:
@@ -654,12 +670,14 @@ Cross-references should be navigation aids, not content dependencies:
 
 ## Related Documentation
 
-- **File Organization Standards** - Metadata and directory structure
-- **Completion Documentation Guide** - Completion doc cross-reference patterns
-- **Development Workflow** - Task completion workflow
+- [Steering Addressing Conventions](steering-addressing-conventions) - **Canonical** `id` / `docid#sectionid` grammar, filename and `aliases` conventions (this doc defers the grammar there)
+- [Process File Organization](process-file-organization) - Metadata and directory structure
+- [Completion Documentation Guide](completion-documentation-guide) - Completion doc cross-reference patterns
+- [Process Development Workflow](process-development-workflow) - Task completion workflow
 
-**MCP Queries**:
+**MCP Queries** (bare-`id` in the `path` argument — the resolver addresses by `id`):
 ```
-get_section({ path: ".kiro/steering/Process-File-Organization.md", heading: "Required Metadata Fields" })
-get_document_full({ path: ".kiro/steering/Completion Documentation Guide.md" })
+get_section({ path: "steering-addressing-conventions", heading: "Convention 2: Composite `docid#sectionid` Addressing Grammar" })
+get_section({ path: "process-file-organization", heading: "Required Metadata Fields" })
+get_document_full({ path: "completion-documentation-guide" })
 ```